@develemit/commerce-server 0.3.0 → 0.6.0

package/docs/admin.md

@@ -9,8 +9,11 @@ management under `/admin`. Without it, no admin routes exist (404).
   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`.
+  `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                                                |
 | ---------------------------------------- | ------------------------------------------------------ |
@@ -18,6 +21,7 @@ management under `/admin`. Without it, no admin routes exist (404).
 | `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                   |
 
@@ -86,3 +90,27 @@ the item. Either:
   take the last unit. The order becomes `paid` and `onOrderPaid` fires, so the
   host sends its normal confirmation.
 - **Refund it:** `POST /admin/orders/:id/refunds`, see above.
+
+## Admin discounts API
+
+Registered under `/admin/discounts` only when both `admin` and checkout are
+configured, behind the same `authorize` hook (401 otherwise).
+
+| Route                        | Purpose                                                                                                                                                     |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /admin/discounts`       | Newest first. `?status=active\|inactive\|scheduled\|expired` (computed from `active` and the dates), `?q=` (code prefix), `?cursor=`, `?limit=` (1-100, 25) |
+| `POST /admin/discounts`      | `DiscountInput`. 201 with the discount. A taken code: 409 `DISCOUNT_CODE_TAKEN`                                                                             |
+| `GET /admin/discounts/:id`   | One discount                                                                                                                                                |
+| `PATCH /admin/discounts/:id` | `DiscountPatch`. Send `null` to clear `minSubtotalCents`, `startsAt`, `endsAt` or `maxRedemptions`                                                          |
+
+Every discount carries `redeemedCount` (committed redemptions) and
+`reservedCount` (reserved, awaiting payment). The list returns
+`{ items, nextCursor }`; treat the cursor as opaque.
+
+- Codes are trimmed and uppercased. Once a redemption exists in any status,
+  `code`, `type`, `percentOff`, `amountOffCents` and `currency` cannot change
+  (409 `DISCOUNT_IN_USE`); dates, `active`, `minSubtotalCents` and
+  `maxRedemptions` still can.
+- `maxRedemptions` cannot go below reserved plus committed redemptions (400
+  `MAX_REDEMPTIONS_BELOW_USAGE`).
+- There is no delete. Deactivate with `{ "active": false }`.

package/docs/payments.md

@@ -10,13 +10,41 @@ 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
+- `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.
+
+## Discounts
+
+A discount code is an amount off the merchandise subtotal, never shipping. The
+server re-evaluates the code at checkout and passes the gateway
+`discount: { code, amountCents }` on `createCheckoutSession`. A custom gateway
+must apply it (for example as a one-off coupon or a negative line), or the
+buyer is charged the undiscounted price while the order records the discount.
+`createStripeGateway` creates a one-off coupon (`amount_off`,
+`duration: 'once'`, `max_redemptions: 1`) and passes it in `discounts`.
+`createFakeGateway` records the discount on `sessions`.
+
 ## Manual Stripe test-mode purchase
 
 Uses the playground apps in this repo and a Stripe account in test mode.

package/migrations/0007_discounts.sql

@@ -0,0 +1,40 @@
+CREATE TABLE "commerce_discount_redemptions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"discount_id" uuid NOT NULL,
+	"order_id" uuid NOT NULL,
+	"status" text DEFAULT 'reserved' NOT NULL,
+	"amount_cents" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "commerce_discount_redemptions_order_id_unique" UNIQUE("order_id"),
+	CONSTRAINT "commerce_discount_redemptions_amount_check" CHECK ("commerce_discount_redemptions"."amount_cents" > 0),
+	CONSTRAINT "commerce_discount_redemptions_status_check" CHECK ("commerce_discount_redemptions"."status" in ('reserved', 'committed', 'released'))
+);
+--> statement-breakpoint
+CREATE TABLE "commerce_discounts" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"code" text NOT NULL,
+	"type" text NOT NULL,
+	"percent_off" integer,
+	"amount_off_cents" integer,
+	"currency" text,
+	"min_subtotal_cents" integer,
+	"starts_at" timestamp with time zone,
+	"ends_at" timestamp with time zone,
+	"max_redemptions" integer,
+	"active" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "commerce_discounts_code_unique" UNIQUE("code"),
+	CONSTRAINT "commerce_discounts_code_check" CHECK ("commerce_discounts"."code" = upper("commerce_discounts"."code")),
+	CONSTRAINT "commerce_discounts_percent_check" CHECK ("commerce_discounts"."percent_off" is null or ("commerce_discounts"."percent_off" between 1 and 100)),
+	CONSTRAINT "commerce_discounts_amount_check" CHECK ("commerce_discounts"."amount_off_cents" is null or "commerce_discounts"."amount_off_cents" > 0),
+	CONSTRAINT "commerce_discounts_max_redemptions_check" CHECK ("commerce_discounts"."max_redemptions" is null or "commerce_discounts"."max_redemptions" > 0),
+	CONSTRAINT "commerce_discounts_type_fields_check" CHECK (("commerce_discounts"."type" = 'percent' and "commerce_discounts"."percent_off" is not null and "commerce_discounts"."amount_off_cents" is null and "commerce_discounts"."currency" is null) or ("commerce_discounts"."type" = 'fixed' and "commerce_discounts"."percent_off" is null and "commerce_discounts"."amount_off_cents" is not null and "commerce_discounts"."currency" is not null))
+);
+--> statement-breakpoint
+ALTER TABLE "commerce_orders" ADD COLUMN "discount_cents" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "commerce_orders" ADD COLUMN "discount_code" text;--> statement-breakpoint
+ALTER TABLE "commerce_discount_redemptions" ADD CONSTRAINT "commerce_discount_redemptions_discount_id_commerce_discounts_id_fk" FOREIGN KEY ("discount_id") REFERENCES "public"."commerce_discounts"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "commerce_discount_redemptions" ADD CONSTRAINT "commerce_discount_redemptions_order_id_commerce_orders_id_fk" FOREIGN KEY ("order_id") REFERENCES "public"."commerce_orders"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "commerce_discount_redemptions_discount_status_idx" ON "commerce_discount_redemptions" USING btree ("discount_id","status");