create-cartbase 0.0.1 → 0.1.0

package/template/app/docs/gift-cards.md

@@ -0,0 +1,153 @@
+# Gift cards — tender on carts
+
+Gift-card redemption is a **payment tender** (`pp_giftcard`), never a
+discount: cart totals and VAT compute first and **never move**; applied
+cards cover part (or all) of `cart.total` and the remainder provider
+(Stripe/COD/manual) charges only what is left. Balances derive from an
+append-only transactions ledger — resolved LIVE on every cart read, so a
+balance spent elsewhere shrinks this cart's tender instead of
+over-redeeming. Actual redemption happens ONLY at cart complete, atomically.
+
+**Auth for every endpoint on this page:** anon `x-client-id`.
+
+SDK module: `@cartbase/storefront/api/gift-cards`. Zero-remainder checkout
+(cards cover everything) is part of the Buy-click sequence — see
+[checkout.md](checkout.md).
+
+---
+
+## Cart decoration (every cart read)
+
+Every cart response carries three tender fields (declared on the `Cart` DTO
+in `@cartbase/storefront/api/carts`; see [carts.md](carts.md) for the full
+cart shape):
+
+```jsonc
+{
+  "cart": {
+    // …totals (NEVER moved by gift cards)…
+    "total": 54,
+    "gift_cards": [                 // apply order; each covers min(live balance, remaining total)
+      { "id": "gift_…", "last4": "PQRS", "amount": 25 }
+      // a disabled/expired/depleted card stays listed at amount: 0
+    ],
+    "gift_card_total": 25,          // Σ coverage = the pp_giftcard session amount
+    "gift_card_remainder": 29       // max(total − gift_card_total, 0) — what the remainder provider charges
+  }
+}
+```
+
+```bash
+# The decoration fields exist on every cart read (empty state shown here).
+CART_JSON=$(curl -sf -X POST "$BASE/api/store/carts" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email":"gc-doc-'"$RUN"'@example.test",
+       "items":[{"variant_id":"variant_01tst000000000000000002","quantity":1}]}')
+CART_ID=$(echo "$CART_JSON" | grep -o '"id":"cart_[^"]*"' | head -1 | cut -d'"' -f4)
+echo "$CART_JSON" | grep -q '"gift_cards":\[\]'
+echo "$CART_JSON" | grep -q '"gift_card_total":0'
+echo "$CART_JSON" | grep -q '"gift_card_remainder"'
+```
+
+---
+
+## POST /api/store/carts/:id/gift-cards — apply a code
+
+- **Purpose** — apply a gift-card code to an open cart (idempotent
+  re-apply).
+- **Auth** — anon `x-client-id`.
+- **Request** — `{code}` (`.strict()`, 4–64 chars). The code travels ONCE,
+  here; it is hashed at rest and never echoed back.
+- **Response** — `200 {cart, gift_card}` — a MASKED confirmation:
+
+```jsonc
+{
+  "cart": { "…": "decorated cart — gift_cards/gift_card_total/gift_card_remainder updated, total untouched" },
+  "gift_card": {
+    "id": "gift_…",
+    "last4": "PQRS",              // last 4 chars of the code — never the code
+    "amount_applied": 25          // how much of THIS cart this card covers right now
+  }
+}
+```
+
+- **Errors** — deliberately a single generic answer, **no code-existence
+  oracle**: unknown, disabled, expired, depleted and foreign-tenant codes
+  are all `400 {code: "invalid_gift_card"}`. Attempts are recorded BEFORE
+  lookup and rate-limited per cart (10 / 15 min) AND per IP (30 / 15 min) →
+  `429 {code: "rate_limited"}` — a valid code inside a burned window is
+  refused the same way. Also 404 `cart_not_found`, 409 `cart_completed`,
+  400 `validation_failed`.
+- **SDK** — `giftCards.applyGiftCard(client, cartId, {code})`.
+- **Components** — checkout gift-card field (show `last4` +
+  `amount_applied`; on 400 show one generic "code cannot be applied"
+  message — do NOT branch on failure reasons that the API deliberately
+  hides).
+- **Settings** — cards are issued/disabled in the admin (gift-cards admin
+  surface); expiry + balance live on the card's ledger. Applying also syncs
+  the internal `pp_giftcard` payment session when a payment collection
+  already exists (creating one composes it — checkout.md).
+
+```bash
+# Executable error contract: the generic-oracle answer. (A happy-path apply
+# needs an admin-issued card — shown in the jsonc above; proven end-to-end
+# by tests/store/gift-cards.test.ts.)
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+  "$BASE/api/store/carts/$CART_ID/gift-cards" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -H "x-forwarded-for: 10.90.$((RANDOM % 250)).$((RANDOM % 250))" \
+  -d '{"code":"NOPE-NOPE-NOPE-NOPE"}')
+test "$STATUS" = 400
+RES=$(curl -s -X POST "$BASE/api/store/carts/$CART_ID/gift-cards" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -H "x-forwarded-for: 10.90.$((RANDOM % 250)).$((RANDOM % 250))" \
+  -d '{"code":"ALSO-NOT-A-REAL-CODE"}')
+echo "$RES" | grep -q '"code":"invalid_gift_card"'
+```
+
+---
+
+## DELETE /api/store/carts/:id/gift-cards — remove an applied card
+
+- **Purpose** — remove an applied card from an open cart (idempotent —
+  removing a never-applied id still returns the cart).
+- **Auth** — anon `x-client-id`.
+- **Request** — `{gift_card_id}` (`.strict()`; the id from
+  `cart.gift_cards[].id` or the apply confirmation).
+- **Response** — `200 {cart}` (decoration recomputed; the `pp_giftcard`
+  session re-synced to the remaining tender).
+- **Errors** — 404 `cart_not_found`, 409 `cart_completed`, 400
+  `validation_failed`.
+- **SDK** — `giftCards.removeGiftCard(client, cartId, {gift_card_id})`.
+- **Components** — checkout applied-cards list (remove chip).
+
+```bash
+# Idempotent remove is executable without an issued card.
+curl -sf -X DELETE "$BASE/api/store/carts/$CART_ID/gift-cards" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"gift_card_id":"gift_never_applied"}' | grep -q '"gift_card_total":0'
+```
+
+---
+
+## What happens at complete (contract summary)
+
+Redemption is atomic at `POST /carts/:id/complete` — idempotent per
+(card, order); two carts racing one balance: exactly one completes, the
+loser gets `402 gift_card_insufficient_balance` and its order is
+compensated away. A remainder-payment failure reverses this order's
+redemptions back to the cards before rethrowing. A gift session that no
+longer covers its amount (card disabled/drained since apply) →
+`402 payment_incomplete` / `402 gift_card_not_redeemable`, nothing burned.
+Zero-remainder carts complete on the gift session alone — no provider
+involved. Refunds/cancels always reverse tender **to the card**, never to
+a bank. Buying gift-card products (digital issue-on-purchase, physical
+activate-at-packing) is a catalog concern — see the product docs and the
+gift-cards admin surface.
+
+## Cleanup / accretion note
+
+This page creates carts only (no store-facing delete endpoint exists —
+same inert accretion as the suite's own cart tests) and applies no real
+cards. Invalid-code attempts land in the rate-limit ledger under a unique
+random IP per run, far below the per-IP window.

package/template/app/docs/integrations.md

@@ -0,0 +1,137 @@
+# Store integrations config — carriers, COD, tracking, lockers
+
+Store-public integration configuration for render/checkout time
+(couriers-port + tracking-integrations cards). The payload is **composed**
+from an ordered block registry — each block owns distinct top-level keys
+(`carriers`, `cod`, `tracking` today; future blocks append). It is NOT
+wrapped in an envelope: the blocks ARE the top-level keys.
+
+**Security law (the allowlist rule)**: every block is an explicit
+allowlist — objects are built field-by-field from capability descriptors
+and the few named public config values. Credentials are never read into a
+response object, so **secrets can never appear in this payload**: carrier
+API keys, Meta CAPI `access_token`, GA4 `api_secret`, Klaviyo
+`private_key`. The executable block below asserts their absence on the
+live payload; `tests/store/store-integrations.test.ts` asserts it
+key-by-key.
+
+## GET /api/store/integrations — the composed config
+
+- **Purpose**: one call at storefront boot/checkout for carrier
+  capabilities, the COD fee row, and the public analytics tag IDs.
+- **Auth**: anon (`x-client-id`); `x-publishable-api-key` is **validated
+  when present** (unknown/revoked/foreign-tenant key →
+  `400 invalid_publishable_key`) and may be omitted by single-channel
+  storefronts.
+- **Request**: no params.
+- **Response**:
+
+```jsonc
+{
+  // Only ENABLED carriers appear — disabled/unconfigured are ABSENT,
+  // never `enabled: false`. Keyed by provider slug.
+  "carriers": {
+    "boxnow": {
+      "enabled": true,
+      "cod": true,             // carrier collects cash on delivery
+      "pickup_points": false,  // office/pickup-point delivery
+      "lockers": true,         // locker/APM network
+      "lockers_url": "/api/store/integrations/boxnow/lockers"  // only when lockers
+    }
+  },
+  // null unless the cod integration is enabled AND fee_amount > 0 — the
+  // exact gate the totals engine applies, so the storefront's optimistic
+  // fee row can never disagree with the charged total. EUR only.
+  "cod": {
+    "enabled": true,
+    "fee_amount": 3.5,          // EUR major units
+    "fee_currency": "eur",
+    "fee_label": "Cash on delivery fee",
+    "description": null          // admin's checkout note, or null
+  },
+  // Public tag config — only ENABLED providers with a public id appear.
+  "tracking": {
+    "facebookPixel": { "pixelId": "123…" },
+    "gtm": { "containerId": "GTM-…" },
+    "ga4": { "measurementId": "G-…" },
+    "klaviyo": { "publicKey": "…" },
+    "googleAds": { "conversionId": "AW-…", "conversionLabel": "…" },
+    "consent_required": true     // always present — mirrors the consent CMP's enabled
+  }
+}
+```
+
+- **Errors**: `400 missing_client_id` · `400 invalid_publishable_key`.
+- **SDK**: `integrations.getIntegrationsConfig(client)`
+- **Components**: carrier/locker pickers, COD fee row in checkout, tracking
+  mounts (`<MetaPixel>/<GA4>/<Gtm>` behind the consent gate).
+- **Settings**: admin → Settings → Integrations (per-provider enable +
+  config); consent settings drive `tracking.consent_required`; Rybbit is
+  deliberately ABSENT (platform analytics, not a tenant integration).
+
+Tracking wiring contract: mount tags only through the consent gate when
+`consent_required` (see [consent.md](consent.md)); Purchase events MUST use
+`eventID = "purchase_" + order.display_id` so Meta dedupes browser Pixel vs
+server CAPI; write TrackingAttribution keys into `cart.metadata`
+(consent-gated) so server events inherit fbp/fbc/anon-id/ga signals.
+
+```bash
+BODY=$(curl -sf "$BASE/api/store/integrations" -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"carriers"'
+echo "$BODY" | grep -q '"tracking"'
+echo "$BODY" | grep -q '"consent_required"'
+# THE ALLOWLIST RULE, asserted negatively: no secret key names, ever.
+if echo "$BODY" | grep -qE 'access_token|api_secret|private_key|client_secret|credentials'; then
+  echo "SECRET LEAK in /api/store/integrations payload"; exit 1
+fi
+# A valid publishable key passes validation (B2B channel-scoped dev key).
+curl -sf "$BASE/api/store/integrations" -H "x-client-id: $CLIENT_ID" \
+  -H "x-publishable-api-key: $PUBLISHABLE_KEY" | grep -q '"tracking"'
+# A bogus key → 400 invalid_publishable_key.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/integrations" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: pk_doc_bogus_$RUN")
+test "$STATUS" = 400
+```
+
+## GET /api/store/integrations/boxnow/lockers — locker directory
+
+- **Purpose**: the BoxNow APM directory for the checkout locker picker.
+  Discover availability via `carriers.boxnow.lockers_url` on the config
+  above — don't probe for the 503.
+- **Auth**: anon (`x-client-id`).
+- **Response**:
+
+```jsonc
+{
+  "lockers": [
+    {
+      "id": "42",
+      "title": "BoxNow Sofia Center",
+      "addressLine1": "bul. Vitosha 1",
+      "addressLine2": "",
+      "postalCode": "1000",
+      "country": "BG",
+      "lat": 42.6977,   // number or null — malformed carrier data → null, never NaN
+      "lng": 23.3219,
+      "note": ""
+    }
+  ]
+}
+```
+
+- **Errors**: `503 {message, lockers: []}` (BoxNow not configured/enabled
+  for the store) · `502 {message, lockers: []}` (carrier call failed).
+  Every state carries the `lockers` key — a picker can always map over it.
+- **Caching**: in-process 10-min TTL per store +
+  `Cache-Control: public, max-age=600, stale-while-revalidate=3600`.
+- **SDK**: `integrations.listBoxNowLockers(client)`
+- **Components**: checkout locker picker (carrier picker family).
+- **Settings**: BoxNow credentials + enable in admin → Settings →
+  Integrations.
+
+```bash
+# The always-true contract: whatever the configuration state (200 with a
+# directory, 503 unconfigured, 502 upstream), the payload carries `lockers`.
+curl -s "$BASE/api/store/integrations/boxnow/lockers" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"lockers"'
+```

package/template/app/docs/menus.md

@@ -0,0 +1,73 @@
+# Menus — backend-owned navigation
+
+Shopify Storefront `Menu` shape **verbatim** (content-navigation card).
+Items store a typed resource reference; `url` is **computed at read time**
+from the live handle (`src/lib/content/paths.ts`) — a product/page handle
+rename never breaks a menu. Items whose referenced resource is deleted or
+not storefront-visible (draft page/post/product, inactive or internal
+category) are **skipped, subtree included** — the payload only ever contains
+renderable links. Nesting is 3 levels max.
+
+## GET /api/store/menus/:handle — one menu
+
+- **Purpose**: render the storefront navigation (header `main-menu`, footer
+  menus — handles are merchant-chosen in admin → Content → Navigation).
+- **Auth**: anon (`x-client-id`).
+- **Request**: path handle only.
+- **Response**:
+
+```jsonc
+{
+  "menu": {
+    "handle": "main-menu",
+    "title": "Main menu",
+    "items": [
+      {
+        "title": "Shop",
+        "type": "collection",       // frontpage|collection|product|category|page|blog_post|external
+        "url": "/collections/all",  // computed at read time; "/" for frontpage; verbatim for external
+        "resourceId": "pcol_<hex>", // null for frontpage/external
+        "items": [ /* same shape, ≤ 3 levels total */ ]
+      }
+    ]
+  }
+}
+```
+
+- **Errors**: `404 {code: "not_found"}` — unknown OR deleted handle. A
+  store with zero menus 404s every handle; the storefront must handle this
+  gracefully (render no nav) — the API never 500s for it.
+- **SDK**: `menus.getMenu(client, handle)`
+- **Components**: header navigation, footer link lists, mobile drawer.
+- **Settings**: menus are authored in admin → Content → Navigation;
+  deleting a referenced resource silently drops its item here.
+
+### ETag / caching semantics
+
+- Every 200 carries `ETag` (sha1 of the payload) and
+  `Cache-Control: public, s-maxage=60, stale-while-revalidate=3600`.
+- A request with `If-None-Match: <etag>` answers **304** with an empty body
+  when the menu is unchanged. Browsers do this transparently. Next.js RSC
+  callers: `menus.getMenu(client, handle)` takes no per-call
+  `RequestOptions` (none of the SDK domain functions forward them yet) —
+  cache at the route level (`export const revalidate = 60`) or supply a
+  caching `fetch` in `StorefrontClientConfig.fetch` instead of hand-rolling
+  ETag replay.
+- The `menu.updated` domain event fires on every menu mutation — the future
+  cache-revalidation hook.
+
+```bash
+# Unknown handle → the clean 404 contract with the stable code (the state
+# every storefront must survive: a deleted menu it still references).
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/menus/doc-no-such-menu-$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+curl -s "$BASE/api/store/menus/doc-no-such-menu-$RUN" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"code":"not_found"'
+```
+
+> Menus are admin-authored and the shared dev tenant seeds none, so the
+> happy path (payload shape, ETag → 304 round-trip) is pinned executably by
+> `tests/store/menus-store.test.ts` and the SDK contract test
+> `tests/contract/sdk-content.contract.test.ts`, which create a menu with
+> admin auth.

package/template/app/docs/metaobjects.md

@@ -0,0 +1,126 @@
+# Metaobjects — merchant-defined content types
+
+Merchant-defined structured content (size charts, brand profiles, FAQ
+blocks) served by TYPE + HANDLE (metaobjects card). **ACTIVE entries only —
+drafts 404** (lib filter AND anon RLS, defense in depth).
+
+Capabilities per definition:
+- `renderable` → payload gains `seo {title, description}` (title falls back
+  to `displayName`, description to null);
+- `online_store` → payload gains `url` (`/metaobjects/<type>/<handle>` —
+  the storefront prepends its origin).
+
+References resolve at **read** time: a target the storefront cannot see
+(deleted, or draft under anon RLS) yields `reference: null` — never
+dropped, never a 500. `by-metafield` is a **reserved type slug** (the
+static route shadows `/:type`; rejected at definition create).
+
+Metaobject shape (all endpoints):
+
+```jsonc
+{
+  "id": "uuid",
+  "type": "size-chart",
+  "handle": "shirts-eu",
+  "displayName": "Shirts (EU)",
+  "fields": [
+    { "key": "body", "kind": "rich_text", "value": "<table>…</table>" },
+    { "key": "product", "kind": "product_reference", "value": "prod_…",
+      "reference": { "id": "prod_…", "title": "Linen Shirt", "handle": "linen-shirt" } }
+  ],
+  "seo": { "title": "Shirts (EU)", "description": null },  // renderable only
+  "url": "/metaobjects/size-chart/shirts-eu",              // online_store only
+  "updatedAt": "ISO-8601"
+}
+```
+
+> Definitions + entries are admin-authored; the shared dev tenant seeds
+> none, so the executable blocks prove the 404/400 contracts and the happy
+> paths are pinned by `tests/store/metaobjects-store.test.ts` (admin-auth
+> fixtures).
+
+## GET /api/store/metaobjects/:type — list entries
+
+- **Purpose**: list ACTIVE entries of one type (e.g. all FAQ blocks),
+  newest-updated first.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{limit?, offset?}` — `limit` clamped to 1–100
+  (default 20; out-of-range values are clamped, not rejected).
+- **Response**: `{metaobjects: [Metaobject…], count, offset, limit}` — list
+  payloads carry **raw** field values (`reference` NOT resolved; the
+  by-handle read is the resolve hot path). `seo`/`url` capabilities still
+  apply.
+- **Errors**: `404 not_found` (unknown type).
+- **SDK**: `metaobjects.listMetaobjects(client, type, query?)`
+- **Components**: FAQ/content-block section renderers.
+- **Settings**: definitions + entry status in admin → Content → Metaobjects.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/metaobjects/doc-no-such-type-$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+curl -s "$BASE/api/store/metaobjects/doc-no-such-type-$RUN" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"code":"not_found"'
+```
+
+## GET /api/store/metaobjects/:type/:handle — one entry
+
+- **Purpose**: render one entry — references RESOLVED (invisible targets →
+  `reference: null`).
+- **Auth**: anon (`x-client-id`).
+- **Response**: `{metaobject: Metaobject}` (shape above, references
+  resolved).
+- **Errors**: `404 not_found` — unknown type, unknown handle, or a DRAFT
+  entry (drafts are indistinguishable from missing, by design).
+- **SDK**: `metaobjects.getMetaobject(client, type, handle)`
+- **Components**: size-chart modal, brand-profile block.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/metaobjects/doc-no-such-type-$RUN/doc-h-$RUN" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+## GET /api/store/metaobjects/by-metafield — the product→chart chain
+
+- **Purpose**: the canonical fetch chain — resolve an entity's
+  `metaobject_reference` METAFIELD into full metaobject payload(s) in ONE
+  call: storefront reads the product (id in hand) → this call with the
+  metafield key → the resolved chart.
+- **Auth**: anon (`x-client-id`). Leak boundary (deliberate): only
+  `metaobject_reference` definitions resolve here — any other metafield key
+  404s, so no other metafield value can exit through this route; entries
+  return ACTIVE-only.
+- **Request**: query `{entity_type, entity_id, key}` — all three required.
+- **Response**: `metaobjects` always present, in stored order. `metaobject`
+  (first entry or null) is present **only for single-valued definitions** —
+  LIST definitions return `{metaobjects}` alone:
+
+```jsonc
+// single-valued definition
+{ "metaobject": { /* Metaobject */ }, "metaobjects": [ /* [it] */ ] }
+// list definition
+{ "metaobjects": [ /* Metaobject[] in stored order */ ] }
+```
+
+- **Errors**: `400 invalid_data` (missing entity_type/entity_id/key) ·
+  `404 not_found` (no such definition, wrong field_type, or no stored
+  value for the entity).
+- **SDK**: `metaobjects.getMetaobjectsByMetafield(client, query)`
+- **Components**: PDP size-chart trigger; any metafield-driven block.
+- **Settings**: the metafield definition (entity type + key +
+  `metaobject_reference` field type) in admin → Settings → Metafields.
+
+```bash
+# Missing params → 400 invalid_data.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/metaobjects/by-metafield?entity_type=product" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 400
+# Unknown key on a real seeded product → 404 (the leak-boundary contract).
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/metaobjects/by-metafield?entity_type=product&entity_id=prod_01tst00000000000000000001&key=doc-nokey-$RUN" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```