@develemit/commerce-server 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# @develemit/commerce-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fastify plugins for a small shop: the public catalog, no-oversell inventory
+holds, Stripe hosted checkout, and orders. The package ships its own Drizzle
+schema and migrations, and the host owns the database pool and the secrets.
+
+## Install
+
+```sh
+pnpm add @develemit/commerce-server fastify drizzle-orm pg
+pnpm add stripe   # only if you use createStripeGateway
+pnpm add @fastify/multipart   # only if you pass `admin`
+```
+
+## Integrate
+
+```ts
+import Fastify from 'fastify';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import {
+  commercePlugin,
+  commerceSchema,
+  createStripeGateway,
+  runCommerceMigrations,
+  startHoldSweeper,
+} from '@develemit/commerce-server';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = drizzle(pool, { schema: commerceSchema });
+await runCommerceMigrations(db); // history lives in __commerce_migrations
+
+const app = Fastify();
+await app.register(commercePlugin, {
+  prefix: '/api/commerce',
+  db,
+  currency: 'USD',
+  payment: createStripeGateway({
+    secretKey: process.env.STRIPE_SECRET_KEY!,
+    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+  }),
+  urls: {
+    success: (sessionId) =>
+      `https://shop.example/checkout/success?session_id=${sessionId}`,
+    cancel: 'https://shop.example/cart',
+  },
+  shippingCountries: ['US'], // default
+});
+
+const sweeper = startHoldSweeper(db, { intervalMs: 60_000 });
+app.addHook('onClose', async () => sweeper.stop());
+```
+
+`payment` and `urls` go together. Omit both (`commercePlugin({ db, currency })`)
+for a catalog-only mount: the checkout, webhook, and order routes aren't
+registered, so `/checkout` returns 404.
+
+## Category labels
+
+`GET /catalog/categories` labels each category with its slug. Pass
+`categoryLabels` (a record, or a function returning `undefined` for no label)
+to show display names; unmatched slugs keep the slug.
+
+```ts
+categoryLabels: { 'wall-art': 'Wall Art', 'one-of-a-kind': 'One of a Kind' }
+```
+
+## Shipping rates and order hooks
+
+Active rows in `commerce_shipping_rates` (in the checkout currency, ordered by
+`sort`) are sent to Stripe as `shipping_options`. The buyer's choice is stored
+on the order as `shippingCents` and `shippingLabel`, and `totalCents` is
+subtotal plus shipping. Load rates with `seedShippingRates(db, rates)`, an
+idempotent upsert on `label`. With no active rates the session has no
+shipping options.
+
+The package sends no email. Pass `hooks` and send your own:
+
+```ts
+hooks: {
+  onOrderPaid: async (order) => mailer.send(confirmation(order)),
+  onOrderExpired: async (order) => {},
+  onOrderNeedsAttention: async (order) => notifyStaffToRefund(order),
+  onOrderPaymentFailed: async (order) => mailer.send(paymentFailed(order)),
+}
+```
+
+| Hook                    | Fires when                                                                                                            |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `onOrderPaid`           | Payment succeeded and stock was committed.                                                                            |
+| `onOrderExpired`        | The checkout session expired unpaid; stock is released.                                                               |
+| `onOrderNeedsAttention` | Payment succeeded but the stock is gone (see [Orders that need attention](docs/admin.md#orders-that-need-attention)). |
+| `onOrderPaymentFailed`  | An async payment (e.g. bank debit) failed; stock is released.                                                         |
+| `onOrderShipped`        | The admin first marks a paid order shipped (not on a tracking edit).                                                  |
+| `onOrderRefunded`       | An admin refund is recorded. Receives `(order, refund)`.                                                              |
+
+`onOrderNeedsAttention` fires when a payment succeeded but the stock is gone
+(see [Orders that need attention](docs/admin.md#orders-that-need-attention)). The order is `needs_attention`; refund it with
+`POST /admin/orders/:id/refunds`. All hooks receive an `OrderDetail` (items, totals, email, address). Hooks run after
+the webhook transaction commits, once per processed event, so a replayed event
+never re-fires them. A hook that throws is logged and the webhook still
+returns 200, so make hooks idempotent and do your own retry if delivery
+matters.
+
+The package never reads `process.env`; pass everything in. Load products with
+`seedProducts(db, products)`, an idempotent upsert on `slug`.
+
+## Running a shop
+
+The order lifecycle, from the host's side:
+
+1. **Buy.** Checkout creates a `pending` order and holds stock. The payment
+   webhook makes it `paid` and fires `onOrderPaid` (send the confirmation).
+2. **Ship.** `POST /admin/orders/:id/ship` with carrier and tracking. The order
+   is `shipped` and `onOrderShipped` fires once (send the tracking email). The
+   buyer's order lookup now includes `fulfillment`.
+3. **Refund.** `POST /admin/orders/:id/refunds` with an `Idempotency-Key`,
+   optionally `restock: true`. A full refund makes the order `refunded` and
+   fires `onOrderRefunded`. Refunds made in the Stripe dashboard arrive through
+   the `charge.refunded` webhook and fire the same hook.
+4. **Stuck orders.** A paid order whose stock is gone is `needs_attention`
+   (`onOrderNeedsAttention`). Resolve it or refund it, see [Orders that need attention](docs/admin.md#orders-that-need-attention).
+
+Every hook: `onOrderPaid`, `onOrderExpired`, `onOrderNeedsAttention`,
+`onOrderPaymentFailed`, `onOrderShipped`, `onOrderRefunded`. The table under
+"Shipping rates and order hooks" says when each fires. For a working
+reference, see `apps/playground-e2e/tests/order-management.spec.ts`.
+
+## Admin API and payments
+
+- [Admin API](docs/admin.md): product and order management, refunds, and orders that need attention.
+- [Payment gateways](docs/payments.md): the `PaymentGateway` contract and the manual Stripe test-mode purchase.
+
+## Caching
+
+The public catalog GETs send `Cache-Control: public, max-age=30,
+stale-while-revalidate=300` and a strong `ETag`, and answer a matching
+`If-None-Match` (including `W/` and comma lists) with an empty 304. Errors get
+`Cache-Control: no-store`. Admin, checkout and order routes are untouched.
+
+Pass `catalogCache: { cacheControl: '...' }` to `commercePlugin` to change the
+header, or `cacheControl: false` to omit it (the `ETag` is still sent), for
+hosts that manage caching at a CDN.
+
+The `ETag` hashes the uncompressed body. Register `@fastify/compress` at the
+app root before `commercePlugin`, so its `onSend` runs after the catalog's.
+
+## Production checklist
+
+- **Compression:** register `@fastify/compress` at the app root before
+  `commercePlugin` (JSON shrinks 70-80%). The kit doesn't wrap your app.
+- **Catalog caching:** see [Caching](#caching); put a CDN in front of the
+  catalog GETs.
+- **Images:** serve uploads with long immutable caching and lazy-loaded
+  `<img>`s (the storefront's default); keep image types out of compression.
+- **Uploads on a CDN:** point `storage` at object storage behind a CDN rather
+  than the API process.
+- **Webhooks:** forward the Stripe events (`checkout.session.completed`,
+  expiry and async failure) to `/orders/webhooks/stripe`; see
+  [Payment gateways](docs/payments.md).
+  Webhook raw-body parsing is request-side and unaffected by compression.
+- **Retries:** refunds require an `Idempotency-Key`; reuse it when retrying so
+  a refund can't be issued twice.
+- Admin routes: see [Admin API](docs/admin.md).
+
+## Routes
+
+Relative to the host's prefix:
+
+| Route                            | Purpose                                                    |
+| -------------------------------- | ---------------------------------------------------------- |
+| `GET /catalog/products`          | Active products (`?category=`, `?featured=true`)           |
+| `GET /catalog/products/:slug`    | One product, or 404 `PRODUCT_NOT_FOUND`                    |
+| `GET /catalog/categories`        | Active product counts per category                         |
+| `POST /checkout`                 | `{ items: [{ productId, quantity }] }` → `{ url }`, or 409 |
+| `POST /orders/webhooks/stripe`   | Stripe webhook (raw body, `stripe-signature` header)       |
+| `GET /orders/session/:sessionId` | `orderSummarySchema` for the success page                  |
+
+## How checkout stays honest
+
+- Prices come from the database. Anything else the client sends is ignored.
+- `POST /checkout` locks the product rows (`SELECT … FOR UPDATE`), checks free
+  quantity (`quantity − active unexpired holds`), and records holds for 31
+  minutes, matching the Stripe session's `expires_at`. Two buyers racing for a
+  single piece get one 200 and one 409 `{ unavailableProductIds }`.
+- The catalog reports `reserved` while every unit is held, and `quantity` is
+  the free quantity.
+- `checkout.session.completed` marks the order paid and decrements stock.
+  `checkout.session.expired` releases the holds. Each event id is stored in
+  `commerce_stripe_events` in the same transaction, so replays are no-ops.
+- A completion that arrives after the hold lapsed is committed only if the
+  stock is still free. If another buyer took it, quantity is left alone, the
+  order becomes `needs_attention`, and `onOrderNeedsAttention` fires instead
+  of `onOrderPaid`.
+- A completed session with `payment_status: unpaid` (bank debits) leaves the
+  order `pending`, stores the buyer's details, and extends the hold to 14
+  days. `checkout.session.async_payment_succeeded` then settles it exactly
+  like a completion; `async_payment_failed` cancels the order and releases the
+  stock.
+- Enable these webhook events in the Stripe dashboard:
+  `checkout.session.completed`, `checkout.session.expired`,
+  `checkout.session.async_payment_succeeded`,
+  `checkout.session.async_payment_failed`, `charge.refunded`.
+- `charge.refunded` records refunds made outside the kit (Stripe dashboard,
+  support, disputes) as `source: 'gateway'` refunds and fires
+  `onOrderRefunded`. Refunds started through the admin API are matched by
+  their idempotency key and never recorded twice. Gateway refunds never
+  restock, because the kit can't know whether the goods came back.
+- `startHoldSweeper` only tidies lapsed holds; free quantity already ignores
+  them, so the plugin is correct without it.