storefront

The API behind a small online shop, running on Cloudflare Workers. Products, carts and orders live in D1, product images in R2, and payments go through Stripe.

It is a plain fetch handler with a small router, no framework, and the tests run the real SQL migrations on Node's built-in SQLite, so npm test needs nothing but Node 24.

Running it

npm install
npm test
npm run typecheck

To run the Worker locally:

npx wrangler d1 migrations apply storefront --local
echo 'ADMIN_TOKEN=dev-admin-token' > .dev.vars
npm run dev

Checkout needs Stripe: add STRIPE_SECRET_KEY to .dev.vars with a secret key from your Stripe account's test mode.

Then add a product and look at the catalog:

curl -X PUT localhost:8787/admin/products/wool-socks \
  -H 'authorization: Bearer dev-admin-token' -H 'content-type: application/json' \
  -d '{"name":"Wool socks","price_cents":1800,"stock":40}'
curl localhost:8787/products

API

Method and path	What it does
GET /products	Active products, by name
GET /products/:id	One active product
PUT /admin/products/:id	Create or replace a product (admin token)
PUT /admin/products/:id/image	Upload the product's image (admin token)
GET /images/<key>	A product image
POST /carts	A new, empty cart
GET /carts/:id	A cart with its lines and totals
PUT /carts/:id/items/:product	Set a quantity, { "quantity": n }
DELETE /carts/:id/items/:product	Remove a line
POST /carts/:id/checkout	Create the order and its PaymentIntent, { email, ship_to }
GET /orders/:id	An order and its status

Errors are JSON, { "error": "<code>", "message": "..." }, with extra fields where they help (an out_of_stock error says how many are available).

Layout

src/            storefront-api: router, catalog, carts, images, checkout
migrations/     D1 schema, applied in order
test/           node --test suites and the D1 and R2 stand-ins
.rebasely/      architecture map, knowledge base and CI workflow

The knowledge base in .rebasely/kb explains how each part works and why; start at its index.

License

MIT