create-cartbase 0.1.19 → 0.1.21

package/template/app/docs/orders.md

@@ -1,221 +1,221 @@
-# Orders
-
-The authenticated customer's order surface: list, detail (items +
-fulfillments with tracking + addresses) and order transfers. There is **no
-anonymous order read** — every endpoint on this page requires a customer
-session (`authorization: Bearer <jwt>`, obtained via the passwordless code
-flow — see [auth.md](auth.md)); a guest's only order handle is the
-`completeCart()` response ([checkout.md](checkout.md)). Missing/invalid
-JWT → `401 {code: "unauthenticated"}` — demonstrated executably below;
-happy-path shapes are shown as jsonc (a customer session is admin-owned
-state on the shared tenant; the authenticated paths are proven by
-`tests/store/customer-accounts-ownership.test.ts` and the transfer suite).
-
-**Auth for every endpoint on this page:** `x-client-id` + Bearer JWT.
-
-SDK module: `@cartbase/storefront/api/orders`.
-
----
-
-## GET /api/store/orders/display/:displayId — my order by its human number
-
-- **Purpose** — resolve "order #42" (the number customers see in emails and
-  confirmations) to the full order detail; account order pages and support
-  links use this instead of the opaque id.
-- **Auth** — Bearer JWT required, same ownership scope as the id read:
-  another customer's number is `404 not_found`. `display_id` is a guessable
-  autoincrement — that is exactly why there is no anonymous lookup.
-- **Request** — `GET`, no query. A numeric segment matches the
-  autoincrement `display_id` OR a purely-numeric `custom_display_id`
-  (custom wins ties — it is the number the store actually showed); any
-  other segment matches `custom_display_id` only.
-- **Response** — identical `{order}` detail shape to
-  `GET /api/store/orders/:id` above.
-- **Errors** — 401 `unauthenticated`; 404 `not_found`.
-- **SDK** — `orders.retrieveOrderByDisplayId(client, displayId)`.
-- **Components** — order-confirmation deep links, account order detail.
-- **Settings** — `custom_display_id` is set by merchants/imports (admin
-  surface); absent it, only the autoincrement resolves.
-
-```bash
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/orders/display/42" -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 401
-```
-
----
-
-## GET /api/store/orders — list my orders
-
-- **Purpose** — the account "My orders" list, newest first.
-- **Auth** — Bearer JWT required. Scoped to the session customer AND the
-  tenant — another customer's orders are invisible (not 403).
-- **Request** — `GET ?limit=&offset=&status=` — `limit` 1–200 (default
-  20), `offset` ≥ 0 (default 0), `status` exact-match filter (`pending`,
-  `completed`, `canceled`, …).
-- **Response** — plain order rows (NO embeds — fetch the detail for
-  items/tracking):
-
-```jsonc
-{
-  "orders": [{
-    "id": "order_…",
-    "display_id": 42,              // human-facing autoincrement
-    "status": "pending",
-    "email": "jane@example.com",
-    "currency_code": "eur",
-    "customer_id": "cus_…",
-    "sales_channel_id": null,
-    "region_id": "reg_…",
-    "metadata": {},                // internal staff notes NEVER appear here
-    "created_at": "2026-07-20T…", "updated_at": "2026-07-20T…"
-  }],
-  "count": 1, "offset": 0, "limit": 20
-}
-```
-
-- **Errors** — 401 `unauthenticated`; 400 `validation_failed` (bad
-  limit/offset).
-- **SDK** — `orders.listOrders(client, {limit, offset, status})`.
-- **Components** — account order-history page.
-- **Settings** — none (ownership is structural).
-
-```bash
-# Executable auth contract: no Bearer → 401 unauthenticated.
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/orders" -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 401
-```
-
----
-
-## GET /api/store/orders/:id — my order, in full
-
-- **Purpose** — the order-detail page: items, fulfillment lifecycle +
-  tracking, both addresses.
-- **Auth** — Bearer JWT required. Ownership is part of the lookup: an
-  unknown id and another customer's order are BOTH `404 not_found`
-  (indistinguishable — no existence oracle).
-- **Request** — `GET`, no query.
-- **Response** — a store-safe subset of the admin order select (no
-  customer row, no payment internals, no internal timeline comments):
-
-```jsonc
-{
-  "order": {
-    "id": "order_…", "display_id": 42, "status": "pending",
-    "email": "jane@example.com", "currency_code": "eur",
-    "items": [{                       // version pivot + embedded line item
-      "id": "oi_…", "order_id": "order_…", "quantity": 1,
-      "line_item": {
-        "id": "oli_…", "title": "M", "product_title": "Linen Shirt",
-        "product_handle": "linen-shirt", "thumbnail": "https://…",
-        "variant_id": "variant_…", "variant_sku": "LIN-SHIRT-M",
-        "unit_price": 45, "metadata": null
-      }
-    }],
-    "fulfillments": [{                // couriers surface
-      "fulfillment": {
-        "id": "ful_…",
-        "packed_at": "2026-07-20T…", "shipped_at": null,
-        "delivered_at": null, "canceled_at": null,
-        "labels": [{ "tracking_number": "…", "tracking_url": "https://…" }]
-      }
-    }],
-    "shipping_address": { "first_name": "Jane", "city": "Sofia", "…": "order_addresses row" },
-    "billing_address":  { "…": "order_addresses row" }
-  }
-}
-```
-
-- **Errors** — 401 `unauthenticated`; 404 `not_found`.
-- **SDK** — `orders.retrieveOrder(client, orderId)`.
-- **Components** — order-detail page, tracking widget.
-- **Settings** — fulfillment/tracking data appears as the merchant packs
-  and ships (admin fulfillment flow + carrier labels).
-
-```bash
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/orders/order_any" -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 401
-```
-
----
-
-## Order transfers — claim a (guest) order into my account
-
-Flow: the **claiming** customer calls `request` on an order that is not
-theirs → a one-time token is stored for the order's email holder (email
-dispatch pending server-side) → the claimer, whose account email must
-EQUAL the order's email, calls `accept` with the token. `decline` (the
-recipient rejects, token required) or `cancel` (the requester withdraws)
-end a pending transfer. One pending transfer per order — a duplicate
-`request` acknowledges with the same `{transfer: {requested: true}}` shape
-without creating another. **The token never crosses this surface** — it is
-email-delivered only (pinned by
-`tests/store/order-transfer-token-leak.test.ts`).
-
-### POST /api/store/orders/:id/transfer/request
-
-- **Request** — `{description?}`.
-- **Response** — `200 {"order":{"id":"order_…","transfer":{"requested":true}}}`
-  (or the existing pending action object on a duplicate request).
-- **Errors** — 401 `unauthenticated`; 404 `not_found`; 400 `already_owned`
-  (the order already belongs to the caller).
-- **SDK** — `orders.requestOrderTransfer(client, orderId, {description})`.
-
-### POST /api/store/orders/:id/transfer/accept
-
-- **Request** — `{token}` (≥16 chars, from the transfer email).
-- **Response** — `200 {order}` — the full updated order row, now owned by
-  the caller.
-- **Errors** — 401 `unauthenticated`; 404 `not_found` (order / no pending
-  transfer); 403 `invalid_token` | `email_mismatch` (the caller's email
-  must match the order's original email — a leaked token alone is not
-  enough); 400 `validation_failed`.
-- **SDK** — `orders.acceptOrderTransfer(client, orderId, {token})`.
-
-### POST /api/store/orders/:id/transfer/decline
-
-- **Request** — `{token}`.
-- **Response** — `200 {"order":{"id":"order_…","transfer":{"declined":true}}}`.
-- **Errors** — 401 `unauthenticated`; 404 `not_found`; 403 `invalid_token`;
-  400 `validation_failed`.
-- **SDK** — `orders.declineOrderTransfer(client, orderId, {token})`.
-
-### POST /api/store/orders/:id/transfer/cancel
-
-- **Request** — no body.
-- **Response** — `200 {"order":{"id":"order_…","transfer":{"canceled":true}}}`.
-- **Errors** — 401 `unauthenticated`; 404 `not_found`; 403 `forbidden`
-  (only the requester may cancel).
-- **SDK** — `orders.cancelOrderTransfer(client, orderId)`.
-- **Components** — account "claim this order" flow + the transfer email's
-  accept/decline landing page.
-
-```bash
-# Executable auth contract for the transfer family (all four Bearer-gated).
-# Note the ordering nuance: accept/decline validate the BODY before auth,
-# so a missing token 400s even for guests; request/cancel hit auth first.
-for EP in transfer/request transfer/cancel; do
-  STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
-    "$BASE/api/store/orders/order_any/$EP" \
-    -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
-  test "$STATUS" = 401
-done
-for EP in transfer/accept transfer/decline; do
-  RES=$(curl -s -X POST "$BASE/api/store/orders/order_any/$EP" \
-    -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
-  echo "$RES" | grep -q '"code":"validation_failed"'
-  STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
-    "$BASE/api/store/orders/order_any/$EP" \
-    -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
-    -d '{"token":"0123456789abcdef0123456789abcdef"}')
-  test "$STATUS" = 401
-done
-```
-
-## Cleanup / accretion note
-
-This page creates nothing — every executable block is a read/auth-contract
-probe against nonexistent ids.
+# Orders
+
+The authenticated customer's order surface: list, detail (items +
+fulfillments with tracking + addresses) and order transfers. There is **no
+anonymous order read** — every endpoint on this page requires a customer
+session (`authorization: Bearer <jwt>`, obtained via the passwordless code
+flow — see [auth.md](auth.md)); a guest's only order handle is the
+`completeCart()` response ([checkout.md](checkout.md)). Missing/invalid
+JWT → `401 {code: "unauthenticated"}` — demonstrated executably below;
+happy-path shapes are shown as jsonc (a customer session is admin-owned
+state on the shared tenant; the authenticated paths are proven by
+`tests/store/customer-accounts-ownership.test.ts` and the transfer suite).
+
+**Auth for every endpoint on this page:** `x-client-id` + Bearer JWT.
+
+SDK module: `@cartbase/storefront/api/orders`.
+
+---
+
+## GET /api/store/orders/display/:displayId — my order by its human number
+
+- **Purpose** — resolve "order #42" (the number customers see in emails and
+  confirmations) to the full order detail; account order pages and support
+  links use this instead of the opaque id.
+- **Auth** — Bearer JWT required, same ownership scope as the id read:
+  another customer's number is `404 not_found`. `display_id` is a guessable
+  autoincrement — that is exactly why there is no anonymous lookup.
+- **Request** — `GET`, no query. A numeric segment matches the
+  autoincrement `display_id` OR a purely-numeric `custom_display_id`
+  (custom wins ties — it is the number the store actually showed); any
+  other segment matches `custom_display_id` only.
+- **Response** — identical `{order}` detail shape to
+  `GET /api/store/orders/:id` above.
+- **Errors** — 401 `unauthenticated`; 404 `not_found`.
+- **SDK** — `orders.retrieveOrderByDisplayId(client, displayId)`.
+- **Components** — order-confirmation deep links, account order detail.
+- **Settings** — `custom_display_id` is set by merchants/imports (admin
+  surface); absent it, only the autoincrement resolves.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/orders/display/42" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 401
+```
+
+---
+
+## GET /api/store/orders — list my orders
+
+- **Purpose** — the account "My orders" list, newest first.
+- **Auth** — Bearer JWT required. Scoped to the session customer AND the
+  tenant — another customer's orders are invisible (not 403).
+- **Request** — `GET ?limit=&offset=&status=` — `limit` 1–200 (default
+  20), `offset` ≥ 0 (default 0), `status` exact-match filter (`pending`,
+  `completed`, `canceled`, …).
+- **Response** — plain order rows (NO embeds — fetch the detail for
+  items/tracking):
+
+```jsonc
+{
+  "orders": [{
+    "id": "order_…",
+    "display_id": 42,              // human-facing autoincrement
+    "status": "pending",
+    "email": "jane@example.com",
+    "currency_code": "eur",
+    "customer_id": "cus_…",
+    "sales_channel_id": null,
+    "region_id": "reg_…",
+    "metadata": {},                // internal staff notes NEVER appear here
+    "created_at": "2026-07-20T…", "updated_at": "2026-07-20T…"
+  }],
+  "count": 1, "offset": 0, "limit": 20
+}
+```
+
+- **Errors** — 401 `unauthenticated`; 400 `validation_failed` (bad
+  limit/offset).
+- **SDK** — `orders.listOrders(client, {limit, offset, status})`.
+- **Components** — account order-history page.
+- **Settings** — none (ownership is structural).
+
+```bash
+# Executable auth contract: no Bearer → 401 unauthenticated.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/orders" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 401
+```
+
+---
+
+## GET /api/store/orders/:id — my order, in full
+
+- **Purpose** — the order-detail page: items, fulfillment lifecycle +
+  tracking, both addresses.
+- **Auth** — Bearer JWT required. Ownership is part of the lookup: an
+  unknown id and another customer's order are BOTH `404 not_found`
+  (indistinguishable — no existence oracle).
+- **Request** — `GET`, no query.
+- **Response** — a store-safe subset of the admin order select (no
+  customer row, no payment internals, no internal timeline comments):
+
+```jsonc
+{
+  "order": {
+    "id": "order_…", "display_id": 42, "status": "pending",
+    "email": "jane@example.com", "currency_code": "eur",
+    "items": [{                       // version pivot + embedded line item
+      "id": "oi_…", "order_id": "order_…", "quantity": 1,
+      "line_item": {
+        "id": "oli_…", "title": "M", "product_title": "Linen Shirt",
+        "product_handle": "linen-shirt", "thumbnail": "https://…",
+        "variant_id": "variant_…", "variant_sku": "LIN-SHIRT-M",
+        "unit_price": 45, "metadata": null
+      }
+    }],
+    "fulfillments": [{                // couriers surface
+      "fulfillment": {
+        "id": "ful_…",
+        "packed_at": "2026-07-20T…", "shipped_at": null,
+        "delivered_at": null, "canceled_at": null,
+        "labels": [{ "tracking_number": "…", "tracking_url": "https://…" }]
+      }
+    }],
+    "shipping_address": { "first_name": "Jane", "city": "Sofia", "…": "order_addresses row" },
+    "billing_address":  { "…": "order_addresses row" }
+  }
+}
+```
+
+- **Errors** — 401 `unauthenticated`; 404 `not_found`.
+- **SDK** — `orders.retrieveOrder(client, orderId)`.
+- **Components** — order-detail page, tracking widget.
+- **Settings** — fulfillment/tracking data appears as the merchant packs
+  and ships (admin fulfillment flow + carrier labels).
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/orders/order_any" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 401
+```
+
+---
+
+## Order transfers — claim a (guest) order into my account
+
+Flow: the **claiming** customer calls `request` on an order that is not
+theirs → a one-time token is stored for the order's email holder (email
+dispatch pending server-side) → the claimer, whose account email must
+EQUAL the order's email, calls `accept` with the token. `decline` (the
+recipient rejects, token required) or `cancel` (the requester withdraws)
+end a pending transfer. One pending transfer per order — a duplicate
+`request` acknowledges with the same `{transfer: {requested: true}}` shape
+without creating another. **The token never crosses this surface** — it is
+email-delivered only (pinned by
+`tests/store/order-transfer-token-leak.test.ts`).
+
+### POST /api/store/orders/:id/transfer/request
+
+- **Request** — `{description?}`.
+- **Response** — `200 {"order":{"id":"order_…","transfer":{"requested":true}}}`
+  (or the existing pending action object on a duplicate request).
+- **Errors** — 401 `unauthenticated`; 404 `not_found`; 400 `already_owned`
+  (the order already belongs to the caller).
+- **SDK** — `orders.requestOrderTransfer(client, orderId, {description})`.
+
+### POST /api/store/orders/:id/transfer/accept
+
+- **Request** — `{token}` (≥16 chars, from the transfer email).
+- **Response** — `200 {order}` — the full updated order row, now owned by
+  the caller.
+- **Errors** — 401 `unauthenticated`; 404 `not_found` (order / no pending
+  transfer); 403 `invalid_token` | `email_mismatch` (the caller's email
+  must match the order's original email — a leaked token alone is not
+  enough); 400 `validation_failed`.
+- **SDK** — `orders.acceptOrderTransfer(client, orderId, {token})`.
+
+### POST /api/store/orders/:id/transfer/decline
+
+- **Request** — `{token}`.
+- **Response** — `200 {"order":{"id":"order_…","transfer":{"declined":true}}}`.
+- **Errors** — 401 `unauthenticated`; 404 `not_found`; 403 `invalid_token`;
+  400 `validation_failed`.
+- **SDK** — `orders.declineOrderTransfer(client, orderId, {token})`.
+
+### POST /api/store/orders/:id/transfer/cancel
+
+- **Request** — no body.
+- **Response** — `200 {"order":{"id":"order_…","transfer":{"canceled":true}}}`.
+- **Errors** — 401 `unauthenticated`; 404 `not_found`; 403 `forbidden`
+  (only the requester may cancel).
+- **SDK** — `orders.cancelOrderTransfer(client, orderId)`.
+- **Components** — account "claim this order" flow + the transfer email's
+  accept/decline landing page.
+
+```bash
+# Executable auth contract for the transfer family (all four Bearer-gated).
+# Note the ordering nuance: accept/decline validate the BODY before auth,
+# so a missing token 400s even for guests; request/cancel hit auth first.
+for EP in transfer/request transfer/cancel; do
+  STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+    "$BASE/api/store/orders/order_any/$EP" \
+    -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
+  test "$STATUS" = 401
+done
+for EP in transfer/accept transfer/decline; do
+  RES=$(curl -s -X POST "$BASE/api/store/orders/order_any/$EP" \
+    -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
+  echo "$RES" | grep -q '"code":"validation_failed"'
+  STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+    "$BASE/api/store/orders/order_any/$EP" \
+    -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+    -d '{"token":"0123456789abcdef0123456789abcdef"}')
+  test "$STATUS" = 401
+done
+```
+
+## Cleanup / accretion note
+
+This page creates nothing — every executable block is a read/auth-contract
+probe against nonexistent ids.