create-cartbase 0.0.1 → 0.1.0

package/template/app/docs/collections.md

@@ -0,0 +1,167 @@
+# Collections & membership listings
+
+Curated product groupings (manual or smart). The membership listing —
+`/collections/:id/products` — is the collection page's data source: it reads
+the membership JOIN (multi-collection products appear in every collection
+they belong to), honors the collection's `default_sort`, and accepts a
+per-request `order` override. Money is EUR decimal major units.
+
+SDK module: `@cartbase/storefront/api/collections`.
+
+**Channel scope (Shopify publish-to-channel semantics):** a collection with
+sales-channel links is visible ONLY on those channels; a collection with no
+links is visible everywhere. Pass your channel as `sales_channel_id` — the
+list excludes scoped-away collections, and the membership listing 404s them.
+
+---
+
+## GET /api/store/collections
+
+- **Purpose** — list collections (navigation, collection index pages).
+- **Auth** — anon: `x-client-id` required.
+- **Request**
+
+```jsonc
+// query (all optional)
+{
+  "q": "essen",                 // case-insensitive substring on title
+  "handle": "essentials",       // exact — THE handle lookup (no /:handle route)
+  "sales_channel_id": "sc_…",   // channel scope (see above)
+  "limit": 50,                  // 1–200, default 50
+  "offset": 0
+}
+```
+
+- **Response** — `{ collections, count, offset, limit }`, ordered by title:
+
+```jsonc
+{
+  "collections": [
+    {
+      "id": "pcol_01tst00000000000000000001",
+      "title": "Essentials",
+      "handle": "essentials",
+      "type": "manual",             // "manual" | "smart"
+      "description": null,
+      "image_url": null,
+      "default_sort": "manual",     // used by /products when no order override
+      "conditions": [],             // smart-collection rules (admin-authored)
+      "match": "all",               // smart matching: "all" | "any"
+      "seo_title": null,            // null = fall back to title
+      "seo_description": null,      // null = fall back to description
+      "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** — the seeded catalog carries the `essentials` collection:
+
+```bash
+COLLECTIONS=$(curl -sf "$BASE/api/store/collections?handle=essentials" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$COLLECTIONS" | grep -q '"collections"'
+echo "$COLLECTIONS" | grep -q '"handle":"essentials"'
+COL_ID=$(echo "$COLLECTIONS" | grep -o '"id":"pcol_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$COL_ID"
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`.
+- **SDK** — `listCollections(client, query?)`.
+- **Components** — navigation, collection index grid.
+- **Settings** — collection channel links; smart-collection conditions
+  (membership recomputes on rule/product change).
+
+---
+
+## GET /api/store/collections/:id
+
+- **Purpose** — retrieve one collection (header/SEO block of a collection
+  page). By-handle lookup goes through the list (`?handle=`).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — no query. NOTE (code truth): the single read takes no
+  `sales_channel_id` — channel scope applies to the list and the membership
+  listing, not here.
+- **Response** — `{ "collection": { ...same shape as list rows... } }`
+- **Working curl**
+
+```bash
+COLLECTION=$(curl -sf "$BASE/api/store/collections/$COL_ID" -H "x-client-id: $CLIENT_ID")
+echo "$COLLECTION" | grep -q '"collection"'
+echo "$COLLECTION" | grep -q '"default_sort"'
+```
+
+- **Errors** — 404 `not_found`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/collections/pcol_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+- **SDK** — `retrieveCollection(client, collectionId)`.
+- **Components** — collection page header.
+- **Settings** — SEO overrides.
+
+---
+
+## GET /api/store/collections/:id/products
+
+- **Purpose** — the collection page's product grid: membership join,
+  published products only, ordered by the collection's `default_sort` with
+  an optional `order` override.
+- **Auth** — anon: `x-client-id`; optional Bearer JWT (group pricing).
+- **Request**
+
+```jsonc
+// query (all optional)
+{
+  "order": "price_asc",       // override: manual | title_asc | title_desc |
+                              //   price_asc | price_desc | newest | oldest |
+                              //   best_selling (90-day aggregate).
+                              //   Unknown values are IGNORED (default_sort used).
+  "sales_channel_id": "sc_…", // a collection scoped to OTHER channels 404s
+  "currency_code": "eur",     // pricing context → calculated_price
+  "region_id": "reg_…",
+  "limit": 50,                // 1–100, default 50
+  "offset": 0
+}
+```
+
+- **Response** — `{ products, count, offset, limit }` — products carry the
+  FULL canonical product shape (see products.md), incl. `calculated_price`
+  when a pricing context is given. `count` is the visible membership size.
+- **Working curl** — seeded membership (backfilled from
+  `products.collection_id`) contains the three fixture products:
+
+```bash
+MEMBERS=$(curl -sf "$BASE/api/store/collections/$COL_ID/products?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$MEMBERS" | grep -q '"products"'
+echo "$MEMBERS" | grep -q '"handle":"linen-shirt"'
+echo "$MEMBERS" | grep -q '"calculated_price"'
+```
+
+```bash
+# Sort override: price_asc puts the Wool Beanie (EUR 23) before the Linen
+# Shirt (EUR 45) — asserted as RELATIVE order so unrelated rows can't break it.
+curl -sf "$BASE/api/store/collections/$COL_ID/products?order=price_asc" \
+  -H "x-client-id: $CLIENT_ID" | node -e "
+const c=[];process.stdin.on('data',d=>c.push(d)).on('end',()=>{
+  const j=JSON.parse(Buffer.concat(c));
+  const h=j.products.map(p=>p.handle);
+  const a=h.indexOf('wool-beanie'), b=h.indexOf('linen-shirt');
+  if(a<0||b<0||a>b){console.error('price_asc order wrong: '+h.join(','));process.exit(1)}
+})"
+```
+
+- **Errors** — 404 `not_found` (unknown collection, or scoped away from the
+  given `sales_channel_id`), 400 `validation_failed`, 400 `invalid_region`.
+- **SDK** — `listCollectionProducts(client, collectionId, query?)`.
+- **Components** — product card grid + sort dropdown (emit the `order`
+  values above).
+- **Settings** — collection `default_sort` + manual position order
+  (drag-reorder in admin); price lists; channel links.