@develemit/commerce-server 0.6.0 → 0.8.0

package/docs/admin.md

@@ -5,6 +5,9 @@ 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
@@ -15,15 +18,17 @@ management under `/admin`. Without it, no admin routes exist (404).
   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/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                   |
+| 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                                                                       |
+| `DELETE /admin/products/:id`             | Deletes a never-live draft with no order lines (204), its files and holds; else 409 `PRODUCT_NOT_DELETABLE` (`reason`) |
+| `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
@@ -31,8 +36,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,11 +5,16 @@ 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.
+  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
@@ -34,6 +39,14 @@ only knows sessions created since the process started (404 otherwise), and
 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;

package/migrations/0009_product_published_at.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "commerce_products" ADD COLUMN "published_at" timestamp with time zone;--> statement-breakpoint
+UPDATE "commerce_products" SET "published_at" = "updated_at" WHERE "status" <> 'draft';