@develemit/commerce-server 0.4.0 → 0.7.0

package/docs/admin.md

@@ -5,22 +5,29 @@ Part of [`@develemit/commerce-server`](../README.md).
 Pass `admin: { authorize, storage }` to `commercePlugin` to register product
 management under `/admin`. Without it, no admin routes exist (404).
 
+- `requirePhotoToPublish` (default `true`) makes `PATCH` to `status: 'active'`
+  refuse a draft with no image. Set `false` for shops that go live without
+  photos.
 - `authorize(req)` returns `true` to allow the request; `false` gives a 401.
   The kit owns no identity: check a session, token or header yourself.
 - `storage` implements `FileStorage` (`put(key, stream, contentType)` and
   `delete(key)`). Keys look like `products/<productId>/<uuid>.<ext>`.
-  `createMemoryStorage()` is for tests; a local-disk example lives in
-  `apps/playground-api/src/storage.ts`.
-
-| Route                                    | Purpose                                                |
-| ---------------------------------------- | ------------------------------------------------------ |
-| `GET/POST /admin/products`               | List all statuses / create (`adminProductInputSchema`) |
-| `GET/PATCH /admin/products/:id`          | Read / edit; `{ sold: true }` sets quantity to 0       |
-| `POST /admin/products/:id/images`        | Multipart `file` (+ optional `alt`), 8MB max           |
-| `PATCH /admin/products/:id/images/order` | `{ imageIds }`, every image exactly once               |
-| `PATCH /admin/products/:id/images/:id`   | `{ alt }` (trimmed, max 500); 404 for unknown image    |
-| `DELETE /admin/products/:id/images/:id`  | Removes the row and the stored file                    |
-| `GET/PUT /admin/shipping-rates`          | `PUT` replaces the full set of rates                   |
+  `createMemoryStorage()` is for tests. `createDiskStorage({ dir, publicUrl })`
+  is a development-grade local disk store that rejects keys escaping `dir`
+  (`..`, absolute paths, encoded traversal, NUL bytes, symlinks out); serve its
+  files with `openStoredFile(dir, key)`, which returns `{ stream, contentType,
+size }` or `null` (answer 404).
+
+| Route                                    | Purpose                                                  |
+| ---------------------------------------- | -------------------------------------------------------- |
+| `GET/POST /admin/products`               | List all statuses / create (`adminProductInputSchema`)   |
+| `GET /admin/products/counts`             | `{ all, live, draft, sold, archived, incompleteDrafts }` |
+| `GET/PATCH /admin/products/:id`          | Read / edit; `{ sold: true }` sets quantity to 0         |
+| `POST /admin/products/:id/images`        | Multipart `file` (+ optional `alt`), 8MB max             |
+| `PATCH /admin/products/:id/images/order` | `{ imageIds }`, every image exactly once                 |
+| `PATCH /admin/products/:id/images/:id`   | `{ alt }` (trimmed, max 500); 404 for unknown image      |
+| `DELETE /admin/products/:id/images/:id`  | Removes the row and the stored file                      |
+| `GET/PUT /admin/shipping-rates`          | `PUT` replaces the full set of rates                     |
 
 Stored image keys are `products/<productId>/<uuid>.<ext>` and are never
 overwritten, so their URLs are safe to cache forever. Serve `FileStorage` URLs
@@ -28,8 +35,31 @@ through a CDN with `Cache-Control: public, max-age=31536000, immutable`, and
 have it (or the storefront's image adapter) resize.
 
 Uploads are checked by magic bytes (jpeg, png, webp, heic), not by filename or
-the client's content type. Slugs come from the name at creation and stay
-stable on rename. Edits never touch inventory holds.
+the client's content type. Edits never touch inventory holds.
+
+## Drafts and publishing
+
+A draft may have no name, price or category (a photo-only draft). It never
+appears in the public catalog. Publishing needs all three, plus a photo unless
+`requirePhotoToPublish` is `false`:
+
+- `PATCH` to `status: 'active'` with something missing answers `422`
+  `{ error: 'PRODUCT_INCOMPLETE', missing: ['name' | 'priceCents' | 'category' | 'images'] }`.
+  `AdminClient` throws `ProductIncompleteError` with `missing`.
+- `POST` with `status: 'active'` and no name, price or category answers `400
+INVALID_INPUT` with one issue per missing field. A photo is not checked on
+  create, since a new product has no images yet.
+- The public catalog also skips any active row missing a price or category.
+
+Slugs: a nameless draft gets `draft-<first 8 chars of id>`. The first time it
+is given a name the slug becomes `slugify(name)` (made unique with `-2`, `-3`).
+After that it never changes, so renaming a live product keeps shop links
+stable. A product created with a name keeps that slug on rename.
+
+Counts: each number equals the total of the matching list filter. `live` is
+`status=active`, `draft` is `status=draft`, `archived` is `status=archived`,
+`sold` is `stock=sold` (any status), and `all` is every non-archived product.
+`incompleteDrafts` counts drafts missing a name, price or category.
 
 ## Admin orders API
 

package/docs/payments.md

@@ -5,18 +5,48 @@ Part of [`@develemit/commerce-server`](../README.md).
 `payment` takes any `PaymentGateway` (`createCheckoutSession`,
 `verifyWebhook`, `refund`). `refund({ sessionId, amountCents, idempotencyKey })`
 must return the same `gatewayRefundId` when called again with the same key.
+A gateway may also define `preflight(): Promise<void>`; `commercePlugin` awaits
+it during registration, so a gateway that can't work fails startup.
 Two ship with the package:
 
 - `createStripeGateway({ secretKey, webhookSecret })` loads `stripe` lazily, so
   it's an optional peer. Refunds look up the session's PaymentIntent and call
   `refunds.create` with the idempotency key.
-- `createFakeGateway()` for tests. Its session URL is the success URL, and
+  Registration awaits the optional `preflight()` hook, which loads `stripe`,
+  so a missing package fails startup with `pnpm add stripe` instead of the
+  first checkout. A passed-in `client` skips the import.
+- `createFakeGateway()` for tests and local development. By default its
+  session URL is the success URL (see [Local checkout](#local-checkout-without-stripe)
+  for a click-through flow), and
   `completed(sessionId)` / `expired(sessionId)` / `asyncPaid(sessionId)` /
   `asyncFailed(sessionId)` return signed webhook bodies to
   post to the webhook route. `refunds` lists the refunds it made (one per
   key), `refundCalls` every call, and `failNextRefund()` makes the next one
   throw.
 
+## Local checkout without Stripe
+
+Pass `devCheckout: true` (or `{ apiUrl: 'http://localhost:3301' }` when the
+browser reaches the api on another origin) to `commercePlugin` while using the
+fake gateway. Checkout then returns a session URL pointing at
+`GET <prefix>/checkout/dev/:sessionId/complete`, which applies a paid
+`checkout.completed` event through the same path the webhook uses (holds and
+discount redemptions commit, `onOrderPaid` runs) and answers 302 to
+`urls.success(sessionId)`. `?outcome=expired` releases the order instead and
+redirects to `urls.cancel`. The route is only registered for the fake gateway,
+only knows sessions created since the process started (404 otherwise), and
+`commercePlugin` throws at registration when `NODE_ENV=production`. Gate the
+option on `NODE_ENV !== 'production'` so one config works in every
+environment.
+
+The completed order looks like a real one: buyer email `dev-buyer@example.com`,
+a sample US address, and the session's first offered shipping rate (so the
+total includes shipping; no rate means no shipping line). Override the buyer
+with `devCheckout: { buyer: { email, name, address } }`, or pass
+`buyer: (sessionId) => ({ ... })` to compute it per session. Omitted fields keep
+their defaults, so `onOrderPaid` hooks that send a confirmation email or buy a
+label can run locally without a custom dev route.
+
 ## Discounts
 
 A discount code is an amount off the merchandise subtotal, never shipping. The

package/migrations/0008_draft_products_incomplete.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "commerce_products" ALTER COLUMN "name" SET DEFAULT '';--> statement-breakpoint
+ALTER TABLE "commerce_products" ALTER COLUMN "price_cents" DROP NOT NULL;--> statement-breakpoint
+ALTER TABLE "commerce_products" ALTER COLUMN "category" DROP NOT NULL;