create-cartbase 0.1.16 → 0.1.18

package/template/app/docs/search.md

@@ -1,227 +1,227 @@
-# Search
-
-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 product-to-product rails, BOTH of them,
-  discriminated by `kind`:
-  - `kind=related` (default) — the rail below the product. 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.
-  - `kind=complementary` — the "goes with this" slot above the product. The
-    merchant's picks in their order and NOTHING else; `auto_filled` is always
-    false. There is no fallback by design: similarity can be computed,
-    complementarity is a merchant judgement, and a guessed upsell beside the
-    buy button is worse than an empty slot. An empty response means render
-    nothing.
-- **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 `{ kind? (related|complementary, default related),
-  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.
+# Search
+
+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 product-to-product rails, BOTH of them,
+  discriminated by `kind`:
+  - `kind=related` (default) — the rail below the product. 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.
+  - `kind=complementary` — the "goes with this" slot above the product. The
+    merchant's picks in their order and NOTHING else; `auto_filled` is always
+    false. There is no fallback by design: similarity can be computed,
+    complementarity is a merchant judgement, and a guessed upsell beside the
+    buy button is worse than an empty slot. An empty response means render
+    nothing.
+- **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 `{ kind? (related|complementary, default related),
+  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.

package/template/app/docs/store.md

@@ -1,47 +1,47 @@
-# Store
-
-The store's own identity: its name, its slug and its brand (what the
-merchant set under Settings → Brand). One anonymous read, usually at
-layout level, so a storefront titles, heads and foots itself with the
-merchant's name and never hardcodes one. Logo URLs are public. Colors are
-`#rrggbb`. Every field except `name` and `slug` may be null.
-
-SDK module: `@cartbase/storefront/api/store` (from 0.8.0; on 0.7.0 call
-`client.request("/api/store/store")` with the same shape).
-
----
-
-## GET /api/store/store
-
-- **Purpose** — read the store's id, name, slug and brand.
-- **Auth** — anon: the store's publishable key (`x-publishable-api-key`).
-- **Request** — `GET /api/store/store`
-- **Response 200**
-
-```jsonc
-{
-  "store": {
-    "id": "1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd",   // the store's public id (what PlatformInit mounts)
-    "name": "Demo Store",
-    "slug": "demo-store",
-    "brand": {
-      "logo_url": "https://…/brand/…/logo.png",   // or null
-      "logo_square_url": null,
-      "color_primary": "#111111",                  // or null
-      "color_secondary": null,
-      "slogan": null
-    }
-  }
-}
-```
-
-- **Errors** — `404 store_not_found` when the key names no live store.
-
-```ts
-import { getStore } from "@cartbase/storefront/api/store"
-
-export async function generateMetadata() {
-  const { store } = await getStore(await getServerClient())
-  return createStorefrontMetadata({ title: store.name, description: store.brand.slogan ?? undefined })
-}
-```
+# Store
+
+The store's own identity: its name, its slug and its brand (what the
+merchant set under Settings → Brand). One anonymous read, usually at
+layout level, so a storefront titles, heads and foots itself with the
+merchant's name and never hardcodes one. Logo URLs are public. Colors are
+`#rrggbb`. Every field except `name` and `slug` may be null.
+
+SDK module: `@cartbase/storefront/api/store` (from 0.8.0; on 0.7.0 call
+`client.request("/api/store/store")` with the same shape).
+
+---
+
+## GET /api/store/store
+
+- **Purpose** — read the store's id, name, slug and brand.
+- **Auth** — anon: the store's publishable key (`x-publishable-api-key`).
+- **Request** — `GET /api/store/store`
+- **Response 200**
+
+```jsonc
+{
+  "store": {
+    "id": "1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd",   // the store's public id (what PlatformInit mounts)
+    "name": "Demo Store",
+    "slug": "demo-store",
+    "brand": {
+      "logo_url": "https://…/brand/…/logo.png",   // or null
+      "logo_square_url": null,
+      "color_primary": "#111111",                  // or null
+      "color_secondary": null,
+      "slogan": null
+    }
+  }
+}
+```
+
+- **Errors** — `404 store_not_found` when the key names no live store.
+
+```ts
+import { getStore } from "@cartbase/storefront/api/store"
+
+export async function generateMetadata() {
+  const { store } = await getStore(await getServerClient())
+  return createStorefrontMetadata({ title: store.name, description: store.brand.slogan ?? undefined })
+}
+```