create-cartbase 0.0.1 → 0.1.0

package/template/app/docs/regions.md

@@ -0,0 +1,207 @@
+# Regions, currencies, locales
+
+Catalog-context primitives a storefront resolves at boot: regions feed the
+pricing context (`region_id` → region currency), currencies tell you what the
+store has enabled, locales drive the language switcher and the client's
+`x-locale` header. All reads are anonymous. Money is EUR decimal major units
+everywhere.
+
+SDK module: `@cartbase/storefront/api/regions`.
+
+---
+
+## GET /api/store/regions
+
+- **Purpose** — list the store's regions; a storefront usually picks one at
+  boot (or by shopper choice) and passes its id/currency as the pricing
+  context on catalog reads.
+- **Auth** — anon: `x-client-id` required.
+- **Request** — `GET /api/store/regions`
+
+```jsonc
+// query (all optional)
+{
+  "q": "bulg",             // case-insensitive substring on name
+  "currency_code": "eur",  // exact match, lowercased server-side
+  "limit": 50,             // 1–200, default 50
+  "offset": 0
+}
+```
+
+- **Response** — ordered by name. NOTE: Cartbase regions carry NO embedded
+  `countries` array (divergence from Medusa's Store API — country/tax scope
+  lives server-side in `tax_regions`).
+
+```jsonc
+{
+  "regions": [
+    {
+      "id": "reg_01tst000000000000000000001",
+      "name": "Bulgaria",
+      "currency_code": "eur",       // lowercase — feeds the pricing context
+      "automatic_taxes": true,
+      "metadata": null,
+      "created_at": "2026-07-01T00:00:00.000Z",
+      "updated_at": "2026-07-01T00:00:00.000Z"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 50
+}
+```
+
+- **Working curl**
+
+```bash
+REGIONS=$(curl -sf "$BASE/api/store/regions" -H "x-client-id: $CLIENT_ID")
+echo "$REGIONS" | grep -q '"regions"'
+echo "$REGIONS" | grep -q '"count"'
+REGION_ID=$(echo "$REGIONS" | grep -o '"id":"reg_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$REGION_ID"
+```
+
+- **Errors** — 400 `missing_client_id` (header absent/empty),
+  400 `validation_failed` (bad limit/offset).
+- **SDK** — `listRegions(client, query?)`.
+- **Components** — region/currency selector (see components.md).
+- **Settings** — Admin → Settings → Regions.
+
+```bash
+# Auth contract: no x-client-id → 400 missing_client_id
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/regions")
+test "$STATUS" = 400
+curl -s "$BASE/api/store/regions" | grep -q '"code":"missing_client_id"'
+```
+
+---
+
+## GET /api/store/regions/:id
+
+- **Purpose** — retrieve one region (e.g. re-hydrate the shopper's stored
+  choice).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — `GET /api/store/regions/{region_id}` — no query.
+- **Response** — `{ "region": { ...same shape as the list rows... } }`
+- **Working curl**
+
+```bash
+REGION=$(curl -sf "$BASE/api/store/regions/$REGION_ID" -H "x-client-id: $CLIENT_ID")
+echo "$REGION" | grep -q '"region"'
+echo "$REGION" | grep -q '"currency_code"'
+```
+
+- **Errors** — 404 `not_found` (unknown id, soft-deleted, or another
+  tenant's region — invisible, not forbidden).
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/regions/reg_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+curl -s "$BASE/api/store/regions/reg_doesnotexist$RUN" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"code":"not_found"'
+```
+
+- **SDK** — `retrieveRegion(client, regionId)`.
+- **Components** — region/currency selector.
+- **Settings** — Admin → Settings → Regions.
+
+---
+
+## GET /api/store/currencies
+
+- **Purpose** — list the currencies ENABLED on this store (the shared
+  currency catalog filtered by the store's `store_currencies` links). Use
+  for formatting metadata (symbol, decimal digits).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — query `{ code?, limit?, offset? }` (`code` exact,
+  lowercased; `limit` 1–200, default 50).
+- **Response** — ordered by code; a store with no enabled currencies
+  returns an empty list.
+
+```jsonc
+{
+  "currencies": [
+    {
+      "code": "eur",
+      "name": "Euro",
+      "symbol": "€",
+      "symbol_native": "€",
+      "decimal_digits": 2,
+      "rounding": 0,
+      "created_at": "2026-07-01T00:00:00.000Z",
+      "updated_at": "2026-07-01T00:00:00.000Z"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 50
+}
+```
+
+- **Working curl**
+
+```bash
+CURRENCIES=$(curl -sf "$BASE/api/store/currencies" -H "x-client-id: $CLIENT_ID")
+echo "$CURRENCIES" | grep -q '"currencies"'
+echo "$CURRENCIES" | grep -q '"code":"eur"'   # the dev store enables EUR
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`.
+- **SDK** — `listCurrencies(client, query?)`.
+- **Components** — price formatting helpers.
+- **Settings** — Admin → Settings → Store → currencies (enable/disable +
+  default).
+
+---
+
+## GET /api/store/currencies/:code
+
+- **Purpose** — retrieve one currency by code (case-insensitive).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — `GET /api/store/currencies/{code}` — no query.
+- **Response** — `{ "currency": { ...same shape as the list rows... } }`
+- **Working curl**
+
+```bash
+CURRENCY=$(curl -sf "$BASE/api/store/currencies/eur" -H "x-client-id: $CLIENT_ID")
+echo "$CURRENCY" | grep -q '"currency"'
+echo "$CURRENCY" | grep -q '"symbol"'
+```
+
+- **Errors** — 404 `not_found`.
+- **CODE-TRUTH NOTE** — unlike the list, the single read is NOT filtered by
+  the store's enabled set: any currency in the shared catalog resolves.
+  Treat the LIST as the authority on what the store supports.
+- **SDK** — `retrieveCurrency(client, code)`.
+- **Components** — price formatting helpers.
+- **Settings** — Admin → Settings → Store → currencies.
+
+---
+
+## GET /api/store/locales
+
+- **Purpose** — the store's supported locale codes; drives the language
+  switcher and the value your client sends as `x-locale`.
+- **Auth** — anon: `x-client-id` required.
+- **Request** — no query.
+- **Response** — default locale FIRST, then alphabetical:
+
+```jsonc
+{ "locales": ["en", "bg"] }
+```
+
+- **Working curl**
+
+```bash
+LOCALES=$(curl -sf "$BASE/api/store/locales" -H "x-client-id: $CLIENT_ID")
+echo "$LOCALES" | grep -q '"locales"'
+echo "$LOCALES" | grep -q '"en"'
+```
+
+- **Errors** — 400 `missing_client_id`.
+- **SDK** — `listLocales(client)`.
+- **Components** — locale switcher; `StorefrontClient`'s `getLocale` hook.
+- **Settings** — Admin → Settings → Store → locales (per-store
+  `store_locales` manager; Cartbase's intentional divergence from Medusa's
+  global locale catalog).

package/template/app/docs/reviews.md

@@ -0,0 +1,223 @@
+# Reviews — widget, token wizard, photo rewards
+
+Verified-purchase reviews. Reviews exist **only** via a
+single-use, order-scoped, expiring **token** minted by the request scanner
+and mailed as `<review_link_base>/<token>` — the token IS the auth for
+every write; no login. All public reads serve `status='visible'` rows only
+— hidden/pending/deleted never leak (RLS-enforced too).
+
+The wizard is two-step: **submit** (rating + body, consumes the token) →
+**photo** (attach media, mint the reward code). Resume rule: token consumed
++ `review.reward_code` null → resume at the photo step; `reward_code` set →
+fully done, show the code.
+
+> Public reads below run executably against the seeded `Linen Shirt`
+> product (`prod_01tst00000000000000000001`, scripts/seed-fixtures.ts) —
+> shape holds at any review count, including zero. Token-gated writes need
+> a server-minted token, so their happy paths are pinned by
+> `tests/store/reviews-store.test.ts` + `tests/contract/reviews-widget.contract.test.ts`;
+> here the error contracts run executably.
+
+## GET /api/store/reviews — list visible reviews
+
+- **Purpose**: the paginated review list under the PDP widget.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{product_id (required), sort? default|rating|date,
+  order? asc|desc, limit? (≤50, default 10), offset?}`. `default` = with-
+  media first, newest within.
+- **Response**: `{reviews: [PublicReview…], count, has_more}`.
+  `PublicReview` is EXACTLY these keys (leak guard — no email/order/IP/
+  reward/status; media entries hidden by moderation are filtered out):
+
+```jsonc
+{
+  "reviews": [
+    {
+      "id": "uuid",
+      "customer_name": "Елена Г.",
+      "rating": 5,
+      "title": null,                  // always null — the form has no title
+      "body": "Страхотна риза!",
+      "media": [ { "type": "image", "url": "https://…", "thumb": "https://…", "w": 0, "h": 0, "bytes": 0 } ],
+      "admin_response": null,
+      "admin_response_at": null,
+      "created_at": "ISO-8601"
+    }
+  ],
+  "count": 1,
+  "has_more": false
+}
+```
+
+- **Errors**: `400 validation_failed` (missing product_id, bad sort/limit).
+- **SDK**: `reviews.listReviews(client, query)`
+- **Components**: review list / masonry grid (review widget family).
+
+```bash
+curl -sf "$BASE/api/store/reviews?product_id=prod_01tst00000000000000000001&sort=date" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"has_more"'
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/reviews" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 400
+```
+
+## GET /api/store/reviews/aggregate — star-badge stats
+
+- **Purpose**: the PDP star rating + histogram. Visible only. Edge-cached
+  60s (`Cache-Control: public, max-age=60, s-maxage=60`).
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{product_id}`.
+- **Response**: `{product_id, count, avg_rating, distribution: {"1"…"5"}}`
+  — `avg_rating` rounded to 1 decimal, 0 when no reviews.
+- **Errors**: `400 validation_failed`.
+- **SDK**: `reviews.getAggregate(client, productId)`
+- **Components**: star badge (PDP + product cards).
+
+```bash
+curl -sf "$BASE/api/store/reviews/aggregate?product_id=prod_01tst00000000000000000001" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"distribution"'
+```
+
+## GET /api/store/reviews/widget — one-call widget payload
+
+- **Purpose**: aggregate + first page (sized/sorted per the store's
+  Settings → Reviews display options) + display options in ONE call — what
+  the product widget + star badge mount from. Edge-cached 60s.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{product_id}`.
+- **Response**:
+
+```jsonc
+{
+  "product_id": "prod_…",
+  "aggregate": { /* ReviewAggregate — shape above */ },
+  "reviews": [ /* PublicReview[] — first page */ ],
+  "count": 3,
+  "has_more": false,
+  "options": { "layout": "masonry", "page_size": 6, "photo_first": true }
+}
+```
+
+- **Errors**: `400 validation_failed`.
+- **SDK**: `reviews.getWidget(client, productId)`
+- **Components**: the review widget (masonry/list) + star badge.
+- **Settings**: `widget_layout`, `widget_page_size`, `widget_photo_first`
+  (admin → Settings → Reviews).
+
+```bash
+BODY=$(curl -sf "$BASE/api/store/reviews/widget?product_id=prod_01tst00000000000000000001" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"aggregate"'
+echo "$BODY" | grep -q '"options"'
+echo "$BODY" | grep -q '"photo_first"'
+```
+
+## GET /api/store/reviews/token/:token — validate + form context
+
+- **Purpose**: bootstrap the review form from the emailed link: validity,
+  product card, greeting, and the RESUME state. **Never cached** — state
+  changes on submit.
+- **Auth**: anon (`x-client-id`); the token is the bearer secret.
+- **Response** — ALWAYS 200, `TokenValidation`:
+
+```jsonc
+// invalid
+{ "valid": false, "reason": "not_found" }   // or "expired" | "invalid" (malformed/too short)
+// valid
+{
+  "valid": true,
+  "already_submitted": false,
+  "review": null,                  // {id, reward_code} once submitted
+  "product": { "id": "prod_…", "handle": "linen-shirt", "title": "Linen Shirt", "thumbnail": "https://…" },
+  "customer_name": "Елена",
+  "expires_at": "ISO-8601"
+}
+```
+
+- **Errors**: none over HTTP — failures are in-band (`valid: false`).
+- **SDK**: `reviews.validateToken(client, token)`
+- **Components**: review wizard entry route.
+
+```bash
+# Unknown (but well-formed) token → in-band not_found, HTTP 200.
+curl -sf "$BASE/api/store/reviews/token/doc-not-a-real-token-$RUN" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"reason":"not_found"'
+# Malformed (too short) → "invalid".
+curl -sf "$BASE/api/store/reviews/token/short" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"reason":"invalid"'
+```
+
+## POST /api/store/reviews — submit (wizard step 1)
+
+- **Purpose**: create the review from a token. Consumes the token;
+  idempotent on the (order, product) unique — a race/retry returns the
+  existing review and still consumes the token.
+- **Auth**: anon (`x-client-id`); the token is the auth.
+- **Request**: `{token, rating: 1–5 int, body (REQUIRED — a rating alone is
+  not a review; HTML stripped, ≤2000 chars), media?}` — media ≤ 7 items
+  (≤6 images + ≤1 video), URLs must be on the store's file host (from
+  upload-url below). **No title field.**
+- **Response**: `{id, success: true}`.
+- **Errors**: `400 invalid_data` (shape / empty-after-sanitize body / media
+  rule) · `404 not_found` (unknown token) · `409 conflict` (token consumed
+  — replay) · `410 gone` (expired) · `429 rate_limited` (3/h per IP).
+- **SDK**: `reviews.submitReview(client, input)`
+- **Components**: review wizard, step 1.
+- **Settings**: `moderation_mode: "hold"` lands the review as `pending`
+  (not publicly visible until approved); `auto_publish` goes live at once.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$BASE/api/store/reviews" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"token": "doc-not-a-real-token-'$RUN'", "rating": 5, "body": "great"}')
+test "$STATUS" = 404
+```
+
+## POST /api/store/reviews/:id/photo — attach media + reward (step 2)
+
+- **Purpose**: attach media and mint the single-use reward code (a REAL
+  promotion, percentage-off-order — 10% default). The reward is for the
+  PHOTO, never the rating. Idempotent — retries return the same code; a
+  promo-mint failure never loses the media. A CONSUMED token is accepted
+  (step 1 consumed it).
+- **Auth**: anon (`x-client-id`); the token must match the review's
+  (order, product) pair.
+- **Request**: `{token, media (1–7 items, ≤6 images + ≤1 video, file-host
+  URLs only)}`.
+- **Response**: `{code}` (fresh mint — also emails the `review-reward`
+  template) | `{code, already_issued: true}` (retry) | `{code: null,
+  message}` (mint failed; media saved).
+- **Errors**: `400 invalid_data` · `403 forbidden` (token does not match
+  this review) · `404 not_found` (review or token unknown).
+- **SDK**: `reviews.attachReviewPhoto(client, reviewId, input)`
+- **Components**: review wizard, step 2 (photo + reward reveal).
+- **Settings**: `reward_enabled`, `reward_percentage`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  -X POST "$BASE/api/store/reviews/00000000-0000-0000-0000-00000000dead/photo" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"token": "doc-not-a-real-token-'$RUN'", "media": [{"type": "image", "url": "https://example.com/x.jpg"}]}')
+test "$STATUS" = 400
+```
+
+## POST /api/store/reviews/upload-url — signed media upload
+
+- **Purpose**: get a signed R2 PUT for the photo step. Upload the raw file
+  to `uploadUrl`, then reference `publicUrl` in the media array. A consumed
+  token is accepted; expiry still applies.
+- **Auth**: anon (`x-client-id`); the token is the auth.
+- **Request**: `{token, name, type (image/jpeg|jpg|png|webp or
+  video/mp4|quicktime), size?}` — caps: image ≤ 8MB, video ≤ 50MB.
+- **Response**: `{uploadUrl, publicUrl, key, filename}`.
+- **Errors**: `400 invalid_data` (unsupported MIME, too large) ·
+  `404 not_found` (unknown token) · `410 gone` (expired token).
+- **SDK**: `reviews.createUploadUrl(client, input)`
+- **Components**: review wizard photo picker.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$BASE/api/store/reviews/upload-url" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"token": "doc-not-a-real-token-'$RUN'", "name": "x.jpg", "type": "image/jpeg"}')
+test "$STATUS" = 404
+```

package/template/app/docs/search.md

@@ -0,0 +1,218 @@
+# Search & related products
+
+Configurable storefront search (search-discovery card) plus the PDP's
+related-products rail. Results are the SAME canonical product objects the
+products listing serves (see products.md) — reuse your product-card renderer
+as-is. Money is EUR decimal major units.
+
+SDK module: `@cartbase/storefront/api/search`.
+
+**Matching** — title/subtitle/description full-text (Cyrillic-correct
+'simple' config, prefix match) ∪ typo tolerance via trigram similarity on
+the title ("linnen" finds "Linen Shirt") ∪ SKU prefix ∪ exact tag value.
+Draft products, other tenants, and products outside the publishable key's
+channels NEVER appear.
+
+**Synonyms (admin-authored)** — expansion is BIDIRECTIONAL and SINGLE-LEVEL
+(bounded — expansions never re-expand; capped at 24 terms): a query word
+matching a row's term adds its synonyms; a query word matching one of a
+row's synonyms adds the term + its sibling synonyms. So with the admin row
+`term: "зехтин", synonyms: ["olive oil"]`, EITHER direction finds the
+product. Terms are normalized lowercase.
+
+**Pins & boosts (admin-authored)** — ordering is: (1) pins for this EXACT
+normalized query, in position order — pins are INJECTED even without a text
+match, but only if they pass filters + channel scope + published (the leak
+rule applies to pins too); then (2) globally-boosted products WITHIN the
+match set, in position order; then (3) relevance rank with a deterministic
+tie-break. Global boosts reorder, never inject.
+
+**Cache rule** — responses carry `calculated_price` when a pricing context
+is given; they vary by customer group — never cache shared when a JWT was
+present.
+
+---
+
+## GET /api/store/products/search
+
+- **Purpose** — the search results page + autocomplete backend.
+- **Auth** — anon: `x-client-id` required; `x-publishable-api-key` optional
+  (channel scope, products-listing semantics); Bearer JWT optional (group
+  pricing).
+- **Request**
+
+```jsonc
+// query — q is REQUIRED (min 1 char), everything else optional
+{
+  "q": "linen",
+  "collection_id": "pcol_a,pcol_b", // CSV
+  "category_id": "pcat_a",          // CSV
+  "tag_id": "ptag_a",               // CSV
+  "type_id": "ptyp_a",              // CSV
+  "price_min": 10,                  // major units, on the product's cheapest base price
+  "price_max": 50,
+  "availability": "in_stock",       // in_stock | out_of_stock
+  // Option filters — dynamic keys, repeatable; OR within an option, AND
+  // across options. URL-encode titles ("Length (cm)" → option.Length%20(cm)):
+  "option.Size": "S,M",
+  "currency_code": "eur",           // pricing context (default price facet currency: eur)
+  "region_id": "reg_…",
+  "limit": 20,                      // 1–100, default 20
+  "offset": 0
+}
+```
+
+- **Response**
+
+```jsonc
+{
+  "results": [ /* canonical product objects — see products.md */ ],
+  "facets": [
+    {
+      "key": "price",              // "price" | "availability" | "type" |
+                                   // "tags" | "collection" | "options.<Title>"
+      "label": "Price",
+      "type": "range",             // "range" for price, "value" otherwise
+      "buckets": [
+        { "value": "20-40", "label": "€20 – €40", "count": 3,
+          "min": 20, "max": 40 }   // min/max on range buckets only; max null = open top
+      ]
+    },
+    {
+      "key": "availability", "label": "Availability", "type": "value",
+      "buckets": [ { "value": "in_stock", "label": "In stock", "count": 5 } ]
+    }
+  ],
+  "total": 5,
+  "offset": 0,
+  "limit": 20
+}
+```
+
+  **Facets** follow the tenant's Settings → Search & discovery → Filters
+  config (order + enabled; defaults: price, availability, type, tags,
+  collection). **The faceting count rule:** each facet's bucket counts are
+  computed on the result set filtered by every OTHER active filter — the
+  facet's own dimension is excluded, so selecting "Size: M" never zeroes the
+  other sizes. Empty buckets are omitted; a facet with no buckets is
+  omitted (the dev tenant has no tags/types, so those facets simply don't
+  appear). Price buckets: `auto` (deterministic nice-number split of
+  observed prices, ≤10 buckets) or `fixed` admin ranges; apply one by
+  passing its `min`/`max` back as `price_min`/`price_max`. Value-facet
+  buckets carry ids as `value` (type/tags/collection) or the option value
+  string (`options.<Title>`).
+
+- **Working curl** — seeded catalog: Linen Shirt (45), Wool Beanie (23),
+  Leather Belt (60), all in the `essentials` collection:
+
+```bash
+SEARCH=$(curl -sf "$BASE/api/store/products/search?q=linen&currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$SEARCH" | grep -q '"results"'
+echo "$SEARCH" | grep -q '"facets"'
+echo "$SEARCH" | grep -q '"total"'
+echo "$SEARCH" | grep -q '"handle":"linen-shirt"'
+echo "$SEARCH" | grep -q '"calculated_price"'
+# Default facet config puts price + availability on a priced, stocked catalog:
+echo "$SEARCH" | grep -q '"key":"price"'
+echo "$SEARCH" | grep -q '"key":"availability"'
+```
+
+```bash
+# Typo tolerance (title trigram): "linnen" still finds the Linen Shirt.
+curl -sf "$BASE/api/store/products/search?q=linnen" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"linen-shirt"'
+# SKU prefix match:
+curl -sf "$BASE/api/store/products/search?q=LIN-SHIRT" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"linen-shirt"'
+```
+
+```bash
+# Option filter: only the Linen Shirt has Size S; the beanie (Color) and the
+# belt (Length (cm)) don't match option.Size at all.
+OPT=$(curl -sf "$BASE/api/store/products/search?q=linen&option.Size=S" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$OPT" | grep -q '"handle":"linen-shirt"'
+# A value no variant carries → empty result set (envelope intact):
+curl -sf "$BASE/api/store/products/search?q=linen&option.Size=XXL" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"results":\[\]'
+```
+
+```bash
+# Channel scope: the dev PUBLISHABLE_KEY is bound to the B2B channel
+# (shirt + beanie). "leather" matches anon but returns nothing under the key.
+curl -sf "$BASE/api/store/products/search?q=leather" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"leather-belt"'
+curl -sf "$BASE/api/store/products/search?q=leather" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
+  | grep -q '"results":\[\]'
+```
+
+- **Errors** — 400 `validation_failed` (missing/empty `q`, bad
+  `availability`, limit > 100), 400 `missing_client_id`,
+  400 `invalid_publishable_key`, 400 `invalid_region`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/search" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 400
+curl -s "$BASE/api/store/products/search" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"code":"validation_failed"'
+```
+
+- **SDK** — `searchProducts(client, query)` — pass option filters as
+  `options: { Size: ["S","M"] }`; the SDK folds them into `option.<Title>`
+  params.
+- **Components** — search page, facet sidebar, autocomplete.
+- **Settings** — Search & discovery: synonyms, pins (per-query) + global
+  boosts, facet order/enabled, price bucket strategy (auto/fixed).
+
+---
+
+## GET /api/store/products/:idOrHandle/related
+
+- **Purpose** — the PDP's related-products rail. Manual admin picks first
+  (position order), then a DETERMINISTIC fallback fills to `limit`: same
+  primary collection (newest first), then most-shared-tags.
+  `auto_filled: true` when any fallback item is present.
+- **Auth** — anon: `x-client-id`; optional publishable key — the anchor
+  product must be visible to the key, and scoped-away products never appear
+  as related items; optional Bearer JWT (group pricing).
+- **Request** — query `{ limit? (1–24, default 12), currency_code?,
+  region_id? }`. Accepts a product id (`prod_…`) or handle.
+- **Response**
+
+```jsonc
+{
+  "products": [ /* canonical product objects, self-excluded */ ],
+  "count": 2,
+  "auto_filled": true   // at least one item came from the fallback chain
+}
+```
+
+- **Working curl** — the seeded products share the `essentials` collection,
+  so the shirt's rail fills from it:
+
+```bash
+RELATED=$(curl -sf "$BASE/api/store/products/linen-shirt/related?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$RELATED" | grep -q '"products"'
+echo "$RELATED" | grep -q '"auto_filled"'
+echo "$RELATED" | grep -q '"count"'
+```
+
+- **Errors** — 404 `not_found` (unknown id/handle, draft, or anchor outside
+  the key's channels), 400 `validation_failed`, 400 `invalid_region`.
+
+```bash
+# Channel scope on the ANCHOR: the belt is outside the B2B key's channels.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/leather-belt/related" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY")
+test "$STATUS" = 404
+```
+
+- **SDK** — `listRelatedProducts(client, idOrHandle, query?)`.
+- **Components** — PDP related rail.
+- **Settings** — manual picks: Admin → Product → Related (drag-ordered,
+  ≤24); the fallback chain needs no configuration.