create-cartbase 0.0.1 → 0.1.0

package/template/app/docs/orders.md

@@ -0,0 +1,221 @@
+# Orders — customer reads + transfers
+
+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.

package/template/app/docs/products.md

@@ -0,0 +1,300 @@
+# Products & variants
+
+The catalog read surface. The product object documented here is THE
+canonical shape every discovery endpoint reuses (search results, collection
+membership pages, related products) — build one product-card renderer
+against it. Money is EUR decimal major units.
+
+SDK module: `@cartbase/storefront/api/products`.
+
+**Pricing context (applies to every endpoint here):** pass `currency_code`
+(or `region_id` — its region's currency is used; unknown region → 400
+`invalid_region`) to receive `variant.calculated_price`. Without either,
+`calculated_price` is `null` and only raw base prices are listed. Customer
+groups come ONLY from the optional `authorization: Bearer <jwt>` — never
+from params. **Cache rule:** any response carrying `calculated_price` varies
+by customer group — never cache it shared when a JWT was present.
+
+**Leak rule:** raw price rows in store responses contain ONLY base
+(non-price-list) rows. Price-list amounts surface exclusively through
+`calculated_price` for the caller's own context.
+
+**Publishable-key channel scope:** sending `x-publishable-api-key` restricts
+the catalog to products linked to the key's sales channels — a product
+outside them **404s on retrieve and disappears from lists** (invisible, not
+forbidden). A key with no channel links scopes nothing. Unknown/revoked/
+foreign key → 400 `invalid_publishable_key`.
+
+---
+
+## GET /api/store/products
+
+- **Purpose** — the product listing: catalog pages, filtered grids.
+  Published products only (drafts are RLS-invisible).
+- **Auth** — anon: `x-client-id` required; `x-publishable-api-key` optional
+  (channel scope); `authorization: Bearer <jwt>` optional (group pricing).
+- **Request**
+
+```jsonc
+// query (all optional)
+{
+  "q": "linen",                  // case-insensitive substring on TITLE only
+  "id": "prod_a,prod_b",         // CSV of ids
+  "handle": "linen-shirt",       // exact
+  "collection_id": "pcol_a",     // CSV — products.collection_id (primary collection)
+  "category_id": "pcat_a",       // CSV — category membership
+  "tag_id": "ptag_a",            // CSV — tag membership
+  "type_id": "ptyp_a",           // CSV
+  "order": "-created_at",        // sort column, "-" prefix = desc (default -created_at)
+  "currency_code": "eur",        // pricing context
+  "region_id": "reg_…",          //   or region → currency
+  "limit": 50,                   // 1–200, default 50
+  "offset": 0
+}
+```
+
+- **Response** — `{ products, count, offset, limit }`; each product:
+
+```jsonc
+{
+  "id": "prod_01tst00000000000000000001",
+  "title": "Linen Shirt",
+  "subtitle": null,
+  "description": "Lightweight linen shirt, relaxed fit.",
+  "handle": "linen-shirt",
+  "status": "published",              // always — drafts never appear
+  "thumbnail": "https://…/600/800",
+  "is_giftcard": false,
+  "discountable": true,
+  "collection_id": "pcol_01tst00000000000000000001",
+  "type_id": null,
+  "external_id": null,
+  "weight": null, "length": null, "height": null, "width": null,
+  "hs_code": null, "origin_country": null, "mid_code": null, "material": null,
+  "seo_title": null,                  // null = fall back to title
+  "seo_description": null,            // null = fall back to plain-text description
+  "metadata": null,
+  "created_at": "2026-07-01T00:00:00.000Z",
+  "updated_at": "2026-07-01T00:00:00.000Z",
+  "variants": [
+    {
+      "id": "variant_01tst000000000000000001",
+      "title": "S",
+      "product_id": "prod_01tst00000000000000000001",
+      "sku": "LIN-SHIRT-S",
+      "barcode": null, "ean": null, "upc": null,
+      "thumbnail": null,
+      "allow_backorder": false,
+      "manage_inventory": true,
+      "variant_rank": 0,
+      "metadata": null,
+      "options": [
+        { "value": { "id": "optv_…", "value": "S", "option_id": "opt_…",
+                     "option": { "id": "opt_…", "title": "Size", "product_id": "prod_…" } } }
+      ],
+      // Raw BASE prices via the price-set link embed (leak rule: price-list
+      // rows are stripped — price_list_id is always null here):
+      "prices": [
+        { "price_set": { "prices": [
+            { "id": "price_…", "amount": 45, "currency_code": "eur",
+              "min_quantity": null, "max_quantity": null,
+              "price_set_id": "pset_…", "price_list_id": null }
+        ] } }
+      ],
+      // Present when a pricing context was given; null otherwise or when no
+      // price matches. b2b-v1 shape (store-api.md §Pricing context):
+      "calculated_price": {
+        "calculated_amount": 45,
+        "original_amount": 45,
+        "currency_code": "eur",
+        "is_calculated_price_price_list": false,
+        "price_list_id": null,
+        "price_list_type": null
+      }
+    }
+  ],
+  "images": [ { "id": "pimg_…", "url": "https://…", "rank": 0 } ],
+  "options": [ { "id": "opt_…", "title": "Size",
+                 "values": [ { "id": "optv_…", "value": "S" } ] } ],
+  "collection": { "id": "pcol_…", "title": "Essentials", "handle": "essentials" },
+  "categories": [ { "category": { "id": "pcat_…", "name": "Apparel", "handle": "apparel" } } ],
+  "tags": [ { "tag": { "id": "ptag_…", "value": "summer" } } ],
+  "type": null
+}
+```
+
+- **Working curl**
+
+```bash
+PRODUCTS=$(curl -sf "$BASE/api/store/products?limit=5" -H "x-client-id: $CLIENT_ID")
+echo "$PRODUCTS" | grep -q '"products"'
+echo "$PRODUCTS" | grep -q '"count"'
+# The handle filter answers deterministically regardless of catalog size.
+curl -sf "$BASE/api/store/products?handle=linen-shirt" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"linen-shirt"'
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`,
+  400 `invalid_publishable_key`, 400 `invalid_region`.
+- **SDK** — `listProducts(client, query?)`.
+- **Components** — product card grid (components.md).
+- **Settings** — sales-channel product links + publishable-key bindings
+  (channel scope), price lists (calculated_price).
+
+---
+
+## GET /api/store/products/:idOrHandle
+
+- **Purpose** — the PDP read. Accepts a product id (`prod_…`) or a handle —
+  storefronts deep-link by handle.
+- **Auth** — as the list.
+- **Request** — query: pricing context only (`currency_code` / `region_id`).
+- **Response** — `{ "product": { ...shape above... } }`
+- **Working curl** — with pricing context; asserts the seeded base price
+  (Linen Shirt, EUR 45) and the leak rule structurally:
+
+```bash
+PRODUCT=$(curl -sf "$BASE/api/store/products/linen-shirt?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$PRODUCT" | grep -q '"product"'
+echo "$PRODUCT" | grep -q '"calculated_price"'
+echo "$PRODUCT" | grep -q '"calculated_amount":45'
+echo "$PRODUCT" | grep -q '"seo_title"'
+```
+
+```bash
+# Leak rule, asserted structurally: every raw price row is a BASE row
+# (price_list_id null) — price-list amounts only ever ride calculated_price.
+echo "$PRODUCT" | node -e "
+const c=[];process.stdin.on('data',d=>c.push(d)).on('end',()=>{
+  const j=JSON.parse(Buffer.concat(c));
+  const rows=j.product.variants.flatMap(v=>v.prices??[]).flatMap(l=>l.price_set?.prices??[]);
+  if(!rows.length){console.error('no base price rows');process.exit(1)}
+  if(rows.some(r=>r.price_list_id!==null)){console.error('price-list row leaked');process.exit(1)}
+})"
+```
+
+- **Errors** — 404 `not_found` (unknown handle/id, draft, soft-deleted, or
+  outside the publishable key's channels), 400 `invalid_publishable_key`,
+  400 `invalid_region`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/no-such-handle-$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+```bash
+# Channel scope: the dev PUBLISHABLE_KEY is bound to the B2B channel, whose
+# catalog is Linen Shirt + Wool Beanie. The Leather Belt exists (anon read
+# works) but 404s under the key — invisible, not forbidden.
+curl -sf "$BASE/api/store/products/leather-belt" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"handle":"leather-belt"'
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/leather-belt" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY")
+test "$STATUS" = 404
+curl -sf "$BASE/api/store/products/linen-shirt" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
+  | grep -q '"handle":"linen-shirt"'
+```
+
+```bash
+# Unknown key → 400 invalid_publishable_key (never a silent unscoped read).
+BODY=$(curl -s "$BASE/api/store/products/linen-shirt" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: pk_bogus_$RUN")
+echo "$BODY" | grep -q '"code":"invalid_publishable_key"'
+```
+
+- **SDK** — `retrieveProduct(client, idOrHandle, query?)`.
+- **Components** — PDP family: gallery, option picker, price block.
+- **Settings** — as the list; SEO overrides (Admin → Product → SEO).
+
+---
+
+## GET /api/store/products/:idOrHandle/selling-plans
+
+- **Purpose** — the subscription plans this product can be purchased with
+  (subscriptions add-on). Render as PDP purchase options (one-time vs each
+  plan); the chosen plan id goes on the cart line
+  (`POST /carts/:id/line-items` `selling_plan_id`) and the SERVER applies
+  the plan price. Empty list = one-time only.
+- **Auth** — anon `x-client-id`; publishable-key channel scope applies
+  (same visibility rule as the product read).
+- **Response** — `{ selling_plans: [{id, name, interval, interval_count,
+  pricing_type, pricing_value, min_cycles, max_cycles}], count }`.
+  `pricing_type` `percent` (percent off) | `fixed` (fixed unit price, EUR
+  major units) | `null` (catalog price — the plan only sets the cadence);
+  enabled plans only, merchant-defined order.
+- **Errors** — 404 `not_found` (same rules as the product read).
+- **SDK** — `products.listSellingPlans(client, idOrHandle)`.
+- **Components** — `PurchaseOptions` (products family): controlled radio
+  group, one-time + plans with display-only price preview
+  (`previewPlanPrice` mirrors the server's math; the server is truth).
+  NOTE: a cart with a plan line requires a logged-in customer at payment
+  (checkout.md `save_payment_method`) — surface login before checkout.
+
+```bash
+# The dev tenant seeds no plans — the endpoint contract still executes:
+# a valid product answers with the envelope, an unknown product 404s.
+SPLANS=$(curl -sf "$BASE/api/store/products/linen-shirt/selling-plans" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$SPLANS" | grep -q '"selling_plans"'
+echo "$SPLANS" | grep -q '"count"'
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/no-such-handle-$RUN/selling-plans" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+---
+
+## GET /api/store/product-variants
+
+- **Purpose** — variant multi-lookup (cart-line hydration). `id` accepts a
+  CSV of variant ids in ONE param. Ordered by `variant_rank`.
+- **Auth** — anon: `x-client-id`; optional Bearer JWT (group pricing).
+  NOTE (code truth): this listing is NOT publishable-key channel-scoped —
+  scope applies to product reads.
+- **Request** — query `{ id?, product_id?, sku?, currency_code?, region_id?,
+  limit?, offset? }` (`limit` 1–200, default 50).
+- **Response** — `{ variants, count, offset, limit }`; variant shape exactly
+  as embedded in products above (options + prices + calculated_price).
+- **Working curl**
+
+```bash
+VARIANTS=$(curl -sf "$BASE/api/store/product-variants?sku=LIN-SHIRT-S&currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$VARIANTS" | grep -q '"variants"'
+echo "$VARIANTS" | grep -q '"sku":"LIN-SHIRT-S"'
+VARIANT_ID=$(echo "$VARIANTS" | grep -o '"id":"variant_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$VARIANT_ID"
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`,
+  400 `invalid_region`.
+- **SDK** — `listProductVariants(client, query?)`.
+- **Components** — cart line renderer.
+- **Settings** — price lists (calculated_price).
+
+---
+
+## GET /api/store/product-variants/:id
+
+- **Purpose** — retrieve one variant with options + base prices hydrated.
+- **Auth** — anon: `x-client-id`; optional Bearer JWT.
+- **Request** — query: pricing context only.
+- **Response** — `{ "variant": { ... } }`
+- **Working curl**
+
+```bash
+VARIANT=$(curl -sf "$BASE/api/store/product-variants/$VARIANT_ID?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$VARIANT" | grep -q '"variant"'
+echo "$VARIANT" | grep -q '"calculated_price"'
+```
+
+- **Errors** — 404 `not_found`, 400 `invalid_region`.
+- **SDK** — `retrieveProductVariant(client, variantId, query?)`.
+- **Components** — cart line renderer, option picker.
+- **Settings** — price lists.

package/template/app/docs/redirects.md

@@ -0,0 +1,50 @@
+# URL redirects — 404-path lookup
+
+Exact-match redirect lookup (seo-listings card 21). **Hot-path rule: call
+this ONLY from the storefront's not-found handler** — never on regular page
+loads (index-covered exact match on `(client_id, from_path)`). When
+`to_path` is non-null, issue a **301** to it; when null, render the 404.
+
+Redirects are created in admin and **automatically on handle renames** of
+products/collections/pages/posts — wiring this once means renames never
+break old URLs (path convention shared with [content.md](content.md) and
+[menus.md](menus.md)).
+
+## GET /api/store/url-redirects?path=… — lookup
+
+- **Purpose**: resolve a missed pathname (e.g. `/products/old-handle`) to
+  its redirect target, if any.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{path}` — the exact pathname that 404'd (leading
+  slash included), min length 1.
+- **Response**:
+
+```jsonc
+{
+  "path": "/products/old-handle",   // echoed
+  "to_path": "/products/new-handle" // or null — no redirect, render the 404
+}
+```
+
+- **Errors**: `400 validation_failed` (missing/empty `path`) ·
+  `400 missing_client_id`.
+- **SDK**: `redirects.lookupRedirect(client, path)`
+- **Components**: the storefront `not-found` handler (no visual component).
+- **Settings**: admin → Content → URL redirects; automatic rows on handle
+  renames.
+
+```bash
+# Miss → to_path null (the everyday 404 case), echo intact.
+BODY=$(curl -sf "$BASE/api/store/url-redirects?path=/doc-no-such-path-$RUN" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"to_path":null'
+echo "$BODY" | grep -q "doc-no-such-path-$RUN"
+# Missing path param → 400.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/url-redirects" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 400
+```
+
+> The hit case (`to_path` non-null) requires an admin-created redirect row;
+> it is pinned executably by `tests/store/url-redirects-lookup.test.ts` and
+> the SDK contract test `tests/contract/sdk-content.contract.test.ts`.