create-cartbase 0.1.16 → 0.1.17

package/template/app/docs/categories.md

@@ -1,194 +1,194 @@
-# Categories
-
-Taxonomy reads for navigation trees and filter UIs. Categories are
-hierarchical (`parent_category_id`) with optional ancestor/descendant tree
-embedding; tags and types are flat value lists whose ids feed the `tag_id` /
-`type_id` filters on product listings and search.
-
-SDK module: `@cartbase/storefront/api/categories`.
-
-**Visibility:** only ACTIVE, non-internal categories exist on the store
-surface — enforced by the anon RLS policy, so an inactive/internal category
-404s even when retrieved by id.
-
----
-
-## GET /api/store/product-categories
-
-- **Purpose** — category list / one tree level (pass `parent_category_id`
-  to walk levels, or the tree flags to embed whole branches).
-- **Auth** — anon: `x-client-id` required.
-- **Request**
-
-```jsonc
-// query (all optional)
-{
-  "q": "appa",                       // case-insensitive substring on name
-  "handle": "apparel",               // exact
-  "parent_category_id": "pcat_…",    // children of this category
-  "include_ancestors_tree": true,    // embed parent_category chains
-  "include_descendants_tree": true,  // embed category_children recursively
-  "limit": 50,                       // 1–200, default 50
-  "offset": 0
-}
-```
-
-- **Response** — `{ product_categories, count, offset, limit }`, ordered by
-  `rank`:
-
-```jsonc
-{
-  "product_categories": [
-    {
-      "id": "pcat_01tst00000000000000000001",
-      "name": "Apparel",
-      "handle": "apparel",
-      "description": null,
-      "parent_category_id": null,
-      "rank": 0,
-      "is_active": true,        // always true on the store surface
-      "is_internal": false,     // always false on the store surface
-      "mpath": null,
-      "seo_title": null,        // null = fall back to name
-      "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",
-      // only when include_descendants_tree=true:
-      "category_children": [ /* same shape, recursive */ ],
-      // only when include_ancestors_tree=true:
-      "parent_category": null
-    }
-  ],
-  "count": 1, "offset": 0, "limit": 50
-}
-```
-
-- **Working curl** — the seeded catalog carries the `apparel` category:
-
-```bash
-CATEGORIES=$(curl -sf "$BASE/api/store/product-categories?handle=apparel" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$CATEGORIES" | grep -q '"product_categories"'
-echo "$CATEGORIES" | grep -q '"handle":"apparel"'
-CAT_ID=$(echo "$CATEGORIES" | grep -o '"id":"pcat_[^"]*"' | head -1 | cut -d'"' -f4)
-test -n "$CAT_ID"
-```
-
-- **Errors** — 400 `missing_client_id`, 400 `validation_failed`.
-- **SDK** — `listCategories(client, query?)`.
-- **Components** — category navigation tree, breadcrumbs.
-- **Settings** — Admin → Categories: `is_active` / `is_internal` flags,
-  rank ordering, SEO overrides.
-
----
-
-## GET /api/store/product-categories/:id
-
-- **Purpose** — retrieve one category, optionally with its tree (category
-  landing page + breadcrumbs in one call).
-- **Auth** — anon: `x-client-id` required.
-- **Request** — query `{ include_ancestors_tree?, include_descendants_tree? }`.
-- **Response** — `{ "product_category": { ... } }` (tree fields only when
-  requested; trees contain visible categories only).
-- **Working curl**
-
-```bash
-CATEGORY=$(curl -sf \
-  "$BASE/api/store/product-categories/$CAT_ID?include_descendants_tree=true" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$CATEGORY" | grep -q '"product_category"'
-echo "$CATEGORY" | grep -q '"category_children"'
-```
-
-- **Errors** — 404 `not_found` (unknown, deleted, or inactive/internal —
-  RLS hides them even by id).
-
-```bash
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/product-categories/pcat_doesnotexist$RUN" \
-  -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 404
-```
-
-- **SDK** — `retrieveCategory(client, categoryId, query?)`.
-- **Components** — category page header, breadcrumbs.
-- **Settings** — as the list.
-
----
-
-## GET /api/store/product-tags
-
-- **Purpose** — tag list (filter chips). Use the returned ids as `tag_id`
-  filters on `/products` and `/products/search`.
-- **Auth** — anon: `x-client-id` required.
-- **Request** — query `{ q?, value?, limit?, offset? }` (`q` substring,
-  `value` exact; `limit` 1–200, default 50).
-- **Response** — ordered by value:
-
-```jsonc
-{
-  "product_tags": [
-    { "id": "ptag_…", "value": "summer", "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 dev tenant seeds no tags, so this asserts the
-  envelope (the shape contract), not contents:
-
-```bash
-TAGS=$(curl -sf "$BASE/api/store/product-tags" -H "x-client-id: $CLIENT_ID")
-echo "$TAGS" | grep -q '"product_tags"'
-echo "$TAGS" | grep -q '"count"'
-```
-
-- **Errors** — 400 `missing_client_id`, 400 `validation_failed`;
-  retrieve (`GET /api/store/product-tags/:id` → `{ "product_tag": …}`) 404s
-  on unknown ids:
-
-```bash
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/product-tags/ptag_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 404
-```
-
-- **SDK** — `listProductTags(client, query?)` /
-  `retrieveProductTag(client, tagId)`.
-- **Components** — filter sidebar chips.
-- **Settings** — tags are authored on products in admin.
-
----
-
-## GET /api/store/product-types
-
-- **Purpose** — type list; ids feed `type_id` filters on listings/search.
-- **Auth** — anon: `x-client-id` required.
-- **Request** — query `{ q?, value?, limit?, offset? }` (same semantics as
-  tags).
-- **Response** — `{ product_types, count, offset, limit }`, rows
-  `{ id, value, metadata, created_at, updated_at }`, ordered by value.
-- **Working curl**
-
-```bash
-TYPES=$(curl -sf "$BASE/api/store/product-types" -H "x-client-id: $CLIENT_ID")
-echo "$TYPES" | grep -q '"product_types"'
-echo "$TYPES" | grep -q '"count"'
-```
-
-- **Errors** — 400 `missing_client_id`, 400 `validation_failed`; retrieve
-  (`GET /api/store/product-types/:id` → `{ "product_type": …}`) 404s on
-  unknown ids:
-
-```bash
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/product-types/ptyp_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 404
-```
-
-- **SDK** — `listProductTypes(client, query?)` /
-  `retrieveProductType(client, typeId)`.
-- **Components** — filter sidebar.
-- **Settings** — types are authored on products in admin.
+# Categories
+
+Taxonomy reads for navigation trees and filter UIs. Categories are
+hierarchical (`parent_category_id`) with optional ancestor/descendant tree
+embedding; tags and types are flat value lists whose ids feed the `tag_id` /
+`type_id` filters on product listings and search.
+
+SDK module: `@cartbase/storefront/api/categories`.
+
+**Visibility:** only ACTIVE, non-internal categories exist on the store
+surface — enforced by the anon RLS policy, so an inactive/internal category
+404s even when retrieved by id.
+
+---
+
+## GET /api/store/product-categories
+
+- **Purpose** — category list / one tree level (pass `parent_category_id`
+  to walk levels, or the tree flags to embed whole branches).
+- **Auth** — anon: `x-client-id` required.
+- **Request**
+
+```jsonc
+// query (all optional)
+{
+  "q": "appa",                       // case-insensitive substring on name
+  "handle": "apparel",               // exact
+  "parent_category_id": "pcat_…",    // children of this category
+  "include_ancestors_tree": true,    // embed parent_category chains
+  "include_descendants_tree": true,  // embed category_children recursively
+  "limit": 50,                       // 1–200, default 50
+  "offset": 0
+}
+```
+
+- **Response** — `{ product_categories, count, offset, limit }`, ordered by
+  `rank`:
+
+```jsonc
+{
+  "product_categories": [
+    {
+      "id": "pcat_01tst00000000000000000001",
+      "name": "Apparel",
+      "handle": "apparel",
+      "description": null,
+      "parent_category_id": null,
+      "rank": 0,
+      "is_active": true,        // always true on the store surface
+      "is_internal": false,     // always false on the store surface
+      "mpath": null,
+      "seo_title": null,        // null = fall back to name
+      "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",
+      // only when include_descendants_tree=true:
+      "category_children": [ /* same shape, recursive */ ],
+      // only when include_ancestors_tree=true:
+      "parent_category": null
+    }
+  ],
+  "count": 1, "offset": 0, "limit": 50
+}
+```
+
+- **Working curl** — the seeded catalog carries the `apparel` category:
+
+```bash
+CATEGORIES=$(curl -sf "$BASE/api/store/product-categories?handle=apparel" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$CATEGORIES" | grep -q '"product_categories"'
+echo "$CATEGORIES" | grep -q '"handle":"apparel"'
+CAT_ID=$(echo "$CATEGORIES" | grep -o '"id":"pcat_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$CAT_ID"
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`.
+- **SDK** — `listCategories(client, query?)`.
+- **Components** — category navigation tree, breadcrumbs.
+- **Settings** — Admin → Categories: `is_active` / `is_internal` flags,
+  rank ordering, SEO overrides.
+
+---
+
+## GET /api/store/product-categories/:id
+
+- **Purpose** — retrieve one category, optionally with its tree (category
+  landing page + breadcrumbs in one call).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — query `{ include_ancestors_tree?, include_descendants_tree? }`.
+- **Response** — `{ "product_category": { ... } }` (tree fields only when
+  requested; trees contain visible categories only).
+- **Working curl**
+
+```bash
+CATEGORY=$(curl -sf \
+  "$BASE/api/store/product-categories/$CAT_ID?include_descendants_tree=true" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$CATEGORY" | grep -q '"product_category"'
+echo "$CATEGORY" | grep -q '"category_children"'
+```
+
+- **Errors** — 404 `not_found` (unknown, deleted, or inactive/internal —
+  RLS hides them even by id).
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/product-categories/pcat_doesnotexist$RUN" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+- **SDK** — `retrieveCategory(client, categoryId, query?)`.
+- **Components** — category page header, breadcrumbs.
+- **Settings** — as the list.
+
+---
+
+## GET /api/store/product-tags
+
+- **Purpose** — tag list (filter chips). Use the returned ids as `tag_id`
+  filters on `/products` and `/products/search`.
+- **Auth** — anon: `x-client-id` required.
+- **Request** — query `{ q?, value?, limit?, offset? }` (`q` substring,
+  `value` exact; `limit` 1–200, default 50).
+- **Response** — ordered by value:
+
+```jsonc
+{
+  "product_tags": [
+    { "id": "ptag_…", "value": "summer", "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 dev tenant seeds no tags, so this asserts the
+  envelope (the shape contract), not contents:
+
+```bash
+TAGS=$(curl -sf "$BASE/api/store/product-tags" -H "x-client-id: $CLIENT_ID")
+echo "$TAGS" | grep -q '"product_tags"'
+echo "$TAGS" | grep -q '"count"'
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`;
+  retrieve (`GET /api/store/product-tags/:id` → `{ "product_tag": …}`) 404s
+  on unknown ids:
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/product-tags/ptag_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+- **SDK** — `listProductTags(client, query?)` /
+  `retrieveProductTag(client, tagId)`.
+- **Components** — filter sidebar chips.
+- **Settings** — tags are authored on products in admin.
+
+---
+
+## GET /api/store/product-types
+
+- **Purpose** — type list; ids feed `type_id` filters on listings/search.
+- **Auth** — anon: `x-client-id` required.
+- **Request** — query `{ q?, value?, limit?, offset? }` (same semantics as
+  tags).
+- **Response** — `{ product_types, count, offset, limit }`, rows
+  `{ id, value, metadata, created_at, updated_at }`, ordered by value.
+- **Working curl**
+
+```bash
+TYPES=$(curl -sf "$BASE/api/store/product-types" -H "x-client-id: $CLIENT_ID")
+echo "$TYPES" | grep -q '"product_types"'
+echo "$TYPES" | grep -q '"count"'
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`; retrieve
+  (`GET /api/store/product-types/:id` → `{ "product_type": …}`) 404s on
+  unknown ids:
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/product-types/ptyp_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+- **SDK** — `listProductTypes(client, query?)` /
+  `retrieveProductType(client, typeId)`.
+- **Components** — filter sidebar.
+- **Settings** — types are authored on products in admin.