create-cartbase 0.1.15 → 0.1.17

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

@@ -1,153 +1,153 @@
-# Gift cards
-
-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.
+# Gift cards
+
+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/metaobjects.md

@@ -1,126 +1,126 @@
-# Metaobjects
-
-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
-```
+# Metaobjects
+
+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
+```