@develemit/commerce-server 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+## 0.7.0 (2026-11-04)
+
+### Features
+
+- `devCheckout` orders now complete with a buyer email (`dev-buyer@example.com`), a sample shipping address and the session's first shipping rate, so `onOrderPaid` hooks see real fields. New `devCheckout: { buyer }` option (object or `(sessionId) => buyer`) overrides them; `DevBuyer` and `DevBuyerSetting` types are exported.
+- Drafts can be incomplete: migration `0008` makes `price_cents` and `category` nullable and gives `name` a `''` default. Publishing (`PATCH` to `status: 'active'`) with a missing name, price, category or photo answers 422 `PRODUCT_INCOMPLETE` with `missing`. New `admin.requirePhotoToPublish` option (default `true`).
+- `GET /admin/products/counts` returns `{ all, live, draft, sold, archived, incompleteDrafts }`.
+- Nameless drafts get a temporary `draft-<id>` slug, replaced once by the name slug the first time a name is set, then frozen.
+- **Changed:** `GET /admin/products` pages newest first (`created_at` then `slug`, descending); cursors from before this change page in the wrong direction. New `excludeArchived=true` query param leaves archived products out, and `incomplete=true` keeps only drafts missing a name, price or category (the set `incompleteDrafts` counts).
+- The public catalog skips active rows missing a price or category.
+
+### Features
+
+- `PaymentGateway.preflight?()` is new and optional; `commercePlugin` awaits it during registration. `createStripeGateway` implements it, so a host with Stripe configured but the optional peer `stripe` missing fails at startup with `Run: pnpm add stripe` rather than at the first checkout.
+
+### Fixes
+
+- `createDiskStorage` `put` and `delete` now accept a top-level key such as `x.png`; before, only nested keys worked. Every traversal guard is unchanged.
+- **Changed:** `POST /admin/products` with `status: 'active'` now follows the photo rule too: while `admin.requirePhotoToPublish` is on (the default) it answers 422 `PRODUCT_INCOMPLETE` with `missing: ['images']`, because images can only upload after create. Create the product as a draft, add photos, then publish with `PATCH`. Hosts that create active products directly must do that or set `requirePhotoToPublish: false`.
+- `checkoutUrls(...).success` no longer percent-encodes Stripe's `{CHECKOUT_SESSION_ID}` placeholder, so Stripe substitutes the real session id and buyers land on `/checkout/success?session_id=cs_…` with an id that matches their order. Hosts using `checkoutUrls` with Stripe on 0.5.0–0.6.x should upgrade. No API change.
+
+### Docs
+
+- The package now ships `CHANGELOG.md` and declares `description`, `repository` and `homepage`. The README documents the lower-level exports (`catalogPlugin`, `ordersPlugin`, `ProductNotFoundError`, `WebhookSignatureError`, `SESSION_ID_PLACEHOLDER`, `isFakeGateway`, `createMemoryStorage`) and rate-limiting the public checkout routes.
+
+## 0.6.0 (2026-11-03)
+
+### Features
+
+- `orderEmailLines(order, { locale, labels })` turns an `OrderDetail` into email-ready pieces: item, subtotal, discount (only when one applied), shipping and total lines, the ship-to address, and `text` / `html` renderings with every value HTML-escaped. Money is formatted like the storefront's `formatPrice`. New types `EmailLine`, `OrderEmailLabels`, `OrderEmailLines`, `OrderEmailLinesOptions`.
+
+## 0.5.0 (2026-11-02)
+
+### Features
+
+- `resolvePayment(env = process.env)` picks the Stripe or fake gateway from `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `PAYMENT_GATEWAY` and `NODE_ENV`, and throws on half-configured Stripe or the fake gateway in production. `checkoutUrls(webUrl, { successPath, cancelPath })` builds the `urls` option. New types `CheckoutUrlPaths`, `PaymentEnv`.
+- `commercePlugin({ devCheckout: true | { apiUrl } })` adds `GET /checkout/dev/:sessionId/complete` for the fake gateway: it completes the order through the webhook event path and redirects to the success URL (`?outcome=expired` releases it and redirects to the cancel URL), so a full purchase runs locally without Stripe. Registration throws when `NODE_ENV=production`; the route is skipped for any other gateway. New exports `isFakeGateway`, `DevCheckoutSetting`; `FakeGateway` gains `kind: 'fake'` and `useSessionUrl()`.
+- `createDiskStorage({ dir, publicUrl })` is a `FileStorage` that writes under `dir` and rejects keys that escape it (`..`, absolute paths, encoded traversal, NUL bytes, symlinks pointing outside). `openStoredFile(dir, key)` opens a stored file for serving (stream, image content type, size) or returns `null`, with the same guard. New types `DiskStorageOptions`, `StoredFileStream`.
+
+### Fixes
+
+- `createStripeGateway`'s one-off discount coupons now set `redeem_by` to the checkout session's expiry, so coupons from failed or abandoned sessions expire on their own.
+- Admin order and discount list cursors keep Postgres's microsecond `created_at`, so paging never skips or repeats rows created within the same millisecond. Cursors issued by earlier versions (ISO milliseconds) are still accepted.
+- Image upload (`POST /admin/products/:id/images`) applies the same trimmed, 500-character `alt` rule as the PATCH route (400 when longer).
+- Editing a redeemed fixed discount with a case-only currency difference no longer answers 409 `DISCOUNT_IN_USE`.
+
+## 0.4.0 (2026-10-30)
+
+### Features
+
+- Migration `0007` (`commerce_discounts`, `commerce_discount_redemptions`, and `discount_cents`/`discount_code` on `commerce_orders`; existing orders get `discount_cents = 0`). Apply it with `runCommerceMigrations` before serving traffic. Order totals are now subtotal − discount + shipping.
+- `PATCH /admin/products/:id/images/:imageId` with `{ alt }` edits an existing image's alt text (404 `PRODUCT_NOT_FOUND` / `IMAGE_NOT_FOUND`, 400 on invalid input) and returns the updated product. Catalog ETags change with the new alt text.
+- `GET|POST /admin/discounts` and `GET|PATCH /admin/discounts/:id` (only when `admin` and checkout are configured) list, create, edit and deactivate discount codes, with `redeemedCount` and `reservedCount`. Codes are unique (409 `DISCOUNT_CODE_TAKEN`); once redeemed, the code and value can't change (409 `DISCOUNT_IN_USE`) and `maxRedemptions` can't drop below usage (400). No hard delete. New contracts `adminDiscountListQuerySchema`, `adminDiscountPageSchema`, `discountStatusSchema`.
+- `POST /checkout/discount/preview` (only when checkout is configured) prices a cart on the server and answers the discount a code would take off, or 422 `DISCOUNT_INVALID` with a `reason`. Inactive codes are reported as `not_found`. Rate-limit it at the host.
+- `POST /checkout` accepts `discountCode`. The code is re-evaluated against server prices and a redemption is reserved in the same transaction as the stock holds, under a row lock on the discount, so `maxRedemptions` holds under concurrent checkouts. A rejected code answers 422 `DISCOUNT_INVALID` with a `reason` and creates no order. The order stores `discountCode`/`discountCents`. Payment commits the redemption; expiry, a failed async payment, the hold sweeper, or a failed gateway call releases it. A `needs_attention` order keeps it reserved until resolved (committed) or fully refunded (released). Refunds of paid orders leave it committed.
+- `CreateCheckoutSessionInput` gains an optional `discount: { code, amountCents }` (new exported type `CheckoutDiscount`). It is an amount off the merchandise subtotal, never shipping. **Custom gateways should apply it**, or the buyer is charged the undiscounted price while the order records the discount. `createStripeGateway` creates a one-off coupon (`duration: 'once'`, `max_redemptions: 1`) and passes `discounts: [{ coupon }]`; `createFakeGateway` records it on `sessions`.
+
+## 0.3.0 (2026-10-30)
+
+### Features
+
+- `GET /admin/products` accepts `?stock=in|sold` (stored quantity above 0, or 0; holds are ignored), combinable with `status` and `q`.
+- Public catalog GETs send `Cache-Control` (default `public, max-age=30, stale-while-revalidate=300`) and a strong `ETag`, and answer `If-None-Match` with 304. New `catalogCache: { cacheControl?: string | false }` option on `commercePlugin`; catalog errors send `no-store`.
+
+### Breaking changes
+
+- `GET /admin/products` now returns `{ items, nextCursor }` instead of an array. Page with `?limit=` (1-100, default 50) and `?cursor=`, filter with `?status=`, and search names with `?q=` (case-insensitive substring, `%`/`_` literal). Order is unchanged (`created_at`, then `slug`); a bad cursor gives 400 `INVALID_CURSOR`.
+- `GET /catalog/products` now returns `{ items, nextCursor }` instead of an array. Items are cards (no description, materials or dimensions; only the first image). Page with `?limit=` (1-100, default 48) and `?cursor=`; a bad cursor gives 400 `INVALID_CURSOR`, a bad limit 400 `INVALID_QUERY`. Order is unchanged (`created_at`, then `slug`). `GET /catalog/products/:slug` is unchanged.
+
+### Fixes
+
+- Published tarballs no longer include declaration maps (`*.d.ts.map`), which pointed at `src/` files that were not shipped. JS sourcemaps now embed `sourcesContent`.
+
+## 0.2.0 (2026-10-29)
+
+First published release. 0.1.0 was tagged but never published to npm, so installing 0.2.0 gets everything in both entries below.
+
+### Breaking changes
+
+- `PaymentGateway` has a new required method, `refund({ sessionId, amountCents, idempotencyKey })`, returning `{ gatewayRefundId }`. Custom gateways must implement it; `createStripeGateway` and `createFakeGateway` already do. The `PaymentEvent` union also gains a `payment.refunded` member (`GatewayRefundEvent`), which custom gateways may emit, so exhaustive switches over it need a new case.
+- `POST /admin/orders/:id/refunds` requires an `Idempotency-Key` header (1-255 characters, else 400 `IDEMPOTENCY_KEY_REQUIRED`).
+
+### Features
+
+- Migrations `0005` (`refunded` order status, fulfillment columns, `commerce_order_refunds`) and `0006` (refund `idempotency_key`, unique per order, and pending refund rows). Apply them with `runCommerceMigrations`.
+- Admin order routes, behind `admin.authorize` and only when checkout is configured: `GET /admin/orders` (filter, search, cursor paging), `GET /admin/orders/:id`, `POST /admin/orders/:id/ship`, `POST /admin/orders/:id/resolve` and `POST /admin/orders/:id/refunds`.
+- Refunds go through the gateway, can restock, and set the order `refunded` once the balance reaches zero. Errors: 400 `REFUND_EXCEEDS_BALANCE`, `RESTOCK_REQUIRES_FULL_REFUND` and `RESTOCK_NOT_APPLICABLE` (`needs_attention` orders never took stock), and 502 `REFUND_GATEWAY_ERROR`. Concurrent refunds count against the balance while in flight.
+- `POST /admin/orders/:id/ship` records carrier and tracking and moves `paid` to `shipped`. The buyer's `GET /orders/session/:id` now returns `fulfillment`.
+- `POST /admin/orders/:id/resolve` moves a `needs_attention` order to `paid` when stock is available, or answers 409 `INSUFFICIENT_STOCK` with `productIds`.
+- Hooks `onOrderShipped` (first ship only) and `onOrderRefunded(order, refund)`. `onOrderPaid` also fires when an order is resolved.
+- `charge.refunded` webhook: refunds made in the Stripe dashboard are recorded as `source: 'gateway'` refunds. Stripe refunds started by the kit carry `metadata.commerceRefundKey`, so the webhook echo matches the pending row instead of recording a second one. Enable `charge.refunded` on your Stripe webhook endpoint.
+- An unknown refund outcome (gateway timeout, network error or 5xx) keeps the pending refund and answers 502 `REFUND_OUTCOME_UNKNOWN`, so a fresh `Idempotency-Key` can't refund twice; retry with the same key. Only a certain failure (Stripe 4xx) still deletes the row. Custom gateways signal certainty by throwing `RefundRejectedError`; the fake gateway gets `failNextRefundUncertain()`, and `failNextRefund()` now throws a `RefundRejectedError`.
+- `GET /admin/orders?hasPendingRefund=true|false`, and pending refunds appear in `AdminOrderDetail.refunds` (`refundedCents` still counts confirmed ones only).
+- Exported `RefundInput` and `GatewayRefund` types. The fake gateway records `refunds` and `refundCalls`, and has `failNextRefund()` and `refunded()`.
+
+## 0.1.0 (2026-10-29)
+
+First release. Fastify plugins that own their Drizzle schema and migrations. Peers: `fastify`, `drizzle-orm`, `pg`. Optional peers: `stripe` (Stripe gateway) and `@fastify/multipart` (admin image upload).
+
+### Features
+
+- Owned schema and migrations `0000`–`0004`, applied with `runCommerceMigrations`; `commerceSchema` is exported for host queries.
+- `commercePlugin` (and the lower-level `catalogPlugin` / `ordersPlugin`): catalog routes, checkout and order lookup.
+- Checkout re-reads prices server-side and reserves stock with no-oversell inventory holds. `startHoldSweeper` releases lapsed holds.
+- Payment gateways: `createStripeGateway` and `createFakeGateway` (signed test webhooks). Implement `PaymentGateway` to add another.
+- Webhook handling for completed, expired, async-succeeded and async-failed payments. A payment that arrives after its hold lapsed, or an unpaid async completion, no longer silently commits stock; the order moves to `needs_attention`.
+- Shipping rates (`seedShippingRates`, `shippingCountries`) with the chosen rate and address stored on the order.
+- Order hooks: `onOrderPaid`, `onOrderExpired`, `onOrderNeedsAttention`, `onOrderPaymentFailed` (async payment failed; stock already released). Hook failures are logged, not thrown.
+- Catalog-only mode: omit `payment` and `urls` to mount the catalog without checkout.
+- Admin product API (`AdminOptions`): host-supplied `authorize`, product CRUD, and image upload and ordering through the `FileStorage` interface (`createMemoryStorage` included).
+- `seedProducts` for fixtures and demos.
+- `categoryLabels` option (record or function) sets display labels for `GET /catalog/categories`; unmatched slugs fall back to the slug.

package/README.md

@@ -4,11 +4,16 @@ 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.
 
+New here? Start with the
+[getting-started guide](https://github.com/develemit/develemit-commerce/blob/main/docs/getting-started.md).
+What changed in each version, including new migrations, is in
+[CHANGELOG.md](CHANGELOG.md).
+
 ## Install
 
 ```sh
 pnpm add @develemit/commerce-server fastify drizzle-orm pg
-pnpm add stripe   # only if you use createStripeGateway
+pnpm add stripe   # whenever the Stripe keys are set, including via resolvePayment
 pnpm add @fastify/multipart   # only if you pass `admin`
 ```
 
@@ -204,7 +209,33 @@ Relative to the host's prefix:
 | `POST /checkout`                  | `{ items: [{ productId, quantity }] }` → `{ url }`, or 409      |
 | `POST /checkout/discount/preview` | `{ code, items }` → discount preview, or 422 `DISCOUNT_INVALID` |
 | `POST /orders/webhooks/stripe`    | Stripe webhook (raw body, `stripe-signature` header)            |
-| `GET /orders/session/:sessionId`  | `orderSummarySchema` for the success page                       |
+| `GET /orders/session/:sessionId`  | `orderSummarySchema` for the success page (no shipping address) |
+
+With `devCheckout`, the fake gateway also gets
+`GET /checkout/dev/:sessionId/complete` (see [Local checkout](docs/payments.md#local-checkout-without-stripe)).
+The dev order gets a sample buyer email, address and the first shipping rate;
+`devCheckout: { buyer }` overrides them.
+Admin routes are listed in [docs/admin.md](docs/admin.md).
+
+`POST /checkout` and `POST /checkout/discount/preview` are public and write or
+price carts, so rate-limit both at the host (for example `@fastify/rate-limit`
+with a route config).
+
+## Lower-level exports
+
+- `catalogPlugin` and `ordersPlugin` are the two halves `commercePlugin`
+  registers. Use them only to mount the catalog without checkout, or to put
+  them under different prefixes.
+- `ProductNotFoundError` is thrown by the catalog service. The route turns it
+  into a 404.
+- `WebhookSignatureError` is what a `PaymentGateway`'s `verifyWebhook` should
+  throw for a bad signature. The webhook route answers 400 for it.
+- `SESSION_ID_PLACEHOLDER` (`{CHECKOUT_SESSION_ID}`): checkout builds the
+  success URL as `urls.success(SESSION_ID_PLACEHOLDER)`. Stripe fills it in
+  itself, but a custom gateway must replace it with its session id.
+- `isFakeGateway(gateway)` narrows a `PaymentGateway` to the fake one (for
+  dev-only wiring).
+- `createMemoryStorage()` is an in-memory `FileStorage` for tests.
 
 ## Discounts
 

package/dist/index.d.ts

@@ -52,7 +52,7 @@ declare const commerceSchema: {
                 data: string;
                 driverParam: string;
                 notNull: true;
-                hasDefault: false;
+                hasDefault: true;
                 isPrimaryKey: false;
                 isAutoincrement: false;
                 hasRuntimeDefault: false;
@@ -119,7 +119,7 @@ declare const commerceSchema: {
                 columnType: "PgInteger";
                 data: number;
                 driverParam: string | number;
-                notNull: true;
+                notNull: false;
                 hasDefault: false;
                 isPrimaryKey: false;
                 isAutoincrement: false;
@@ -153,7 +153,7 @@ declare const commerceSchema: {
                 columnType: "PgText";
                 data: string;
                 driverParam: string;
-                notNull: true;
+                notNull: false;
                 hasDefault: false;
                 isPrimaryKey: false;
                 isAutoincrement: false;
@@ -1643,6 +1643,7 @@ interface FileStorage {
 interface AdminOptions {
     authorize(req: FastifyRequest): Promise<boolean>;
     storage: FileStorage;
+    requirePhotoToPublish?: boolean;
 }
 
 interface CatalogCacheOptions {
@@ -1745,6 +1746,7 @@ interface GatewayRefund {
     gatewayRefundId: string;
 }
 interface PaymentGateway {
+    preflight?(): Promise<void>;
     createCheckoutSession(input: CreateCheckoutSessionInput): Promise<CheckoutSession>;
     verifyWebhook(rawBody: Buffer, signature: string | undefined): Promise<PaymentEvent>;
     refund(input: RefundInput): Promise<GatewayRefund>;
@@ -1775,6 +1777,13 @@ interface OrderHooks {
     onOrderRefunded?(order: OrderDetail, refund: OrderRefund): Promise<void>;
 }
 
+interface DevBuyer {
+    email?: string;
+    name?: string;
+    address?: ShippingAddress;
+}
+type DevBuyerSetting = DevBuyer | ((sessionId: string) => DevBuyer);
+
 interface CheckoutOptions {
     payment: PaymentGateway;
     urls: CheckoutUrls;
@@ -1784,6 +1793,7 @@ interface CheckoutOptions {
 }
 interface DevCheckoutSetting {
     apiUrl?: string;
+    buyer?: DevBuyerSetting;
 }
 interface CatalogOnlyOptions {
     payment?: undefined;
@@ -1966,4 +1976,4 @@ interface CheckoutUrlPaths {
 declare function checkoutUrls(webUrl: string, { successPath, cancelPath, }?: CheckoutUrlPaths): CheckoutUrls;
 
 export { ProductNotFoundError, SESSION_ID_PLACEHOLDER, WebhookSignatureError, catalogPlugin, checkoutUrls, commercePlugin, commerceSchema, createDiskStorage, createFakeGateway, createMemoryStorage, createStripeGateway, isFakeGateway, openStoredFile, orderEmailLines, ordersPlugin, resolvePayment, runCommerceMigrations, seedProducts, seedShippingRates, startHoldSweeper };
-export type { AdminOptions, CatalogCacheOptions, CatalogPluginOptions, CategoryLabels, CheckoutDiscount, CheckoutLine, CheckoutSession, CheckoutUrlPaths, CheckoutUrls, ChosenShipping, CommerceDb, CommercePluginOptions, CommerceSchema, CreateCheckoutSessionInput, DevCheckoutSetting, DiskStorageOptions, EmailLine, FakeGateway, FakeGatewayOptions, FileStorage, GatewayRefund, HoldSweeper, HoldSweeperOptions, MemoryStorage, OrderEmailLabels, OrderEmailLines, OrderEmailLinesOptions, OrderHooks, OrdersPluginOptions, PaymentEnv, PaymentEvent, PaymentGateway, RefundInput, SeedProduct, SeedShippingRate, ShippingAddress, ShippingRateOption, SignedWebhook, StoredFile, StoredFileStream, StripeGatewayOptions };
+export type { AdminOptions, CatalogCacheOptions, CatalogPluginOptions, CategoryLabels, CheckoutDiscount, CheckoutLine, CheckoutSession, CheckoutUrlPaths, CheckoutUrls, ChosenShipping, CommerceDb, CommercePluginOptions, CommerceSchema, CreateCheckoutSessionInput, DevBuyer, DevBuyerSetting, DevCheckoutSetting, DiskStorageOptions, EmailLine, FakeGateway, FakeGatewayOptions, FileStorage, GatewayRefund, HoldSweeper, HoldSweeperOptions, MemoryStorage, OrderEmailLabels, OrderEmailLines, OrderEmailLinesOptions, OrderHooks, OrdersPluginOptions, PaymentEnv, PaymentEvent, PaymentGateway, RefundInput, SeedProduct, SeedShippingRate, ShippingAddress, ShippingRateOption, SignedWebhook, StoredFile, StoredFileStream, StripeGatewayOptions };