@cartbase/storefront 0.17.0 → 0.18.0

package/src/api/categories.ts

@@ -1,184 +1,184 @@
-/**
- * @cartbase/storefront/api/categories — product categories, tags, types.
- *
- * 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. Only ACTIVE, non-internal
- * categories are storefront-visible (RLS-enforced — inactive/internal 404
- * even by id). Docs: docs/storefront/categories.md.
- */
-import type { StorefrontClient } from "./http"
-import type { IsoDateString, ListEnvelope, PaginationQuery } from "./types"
-
-export interface StoreProductCategory {
-  id: string
-  name: string
-  handle: string
-  description: string | null
-  parent_category_id: string | null
-  rank: number
-  is_active: true
-  is_internal: false
-  /** Materialized path (internal ordering detail). */
-  mpath: string | null
-  /** SEO override; null = fall back to `name`. */
-  seo_title: string | null
-  /** SEO override; null = fall back to `description`. */
-  seo_description: string | null
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-  /** Present only when `include_descendants_tree` was requested. */
-  category_children?: StoreProductCategory[]
-  /** Present only when `include_ancestors_tree` was requested. */
-  parent_category?: StoreProductCategory | null
-}
-
-export interface StoreProductTag {
-  id: string
-  value: string
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-}
-
-export interface StoreProductType {
-  id: string
-  value: string
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-}
-
-export interface ListCategoriesQuery extends PaginationQuery {
-  /** Case-insensitive substring match on name. */
-  q?: string
-  handle?: string
-  /** List one level: children of this category. */
-  parent_category_id?: string
-  /** Embed `parent_category` chains on each row. */
-  include_ancestors_tree?: boolean
-  /** Embed `category_children` recursively on each row. */
-  include_descendants_tree?: boolean
-}
-
-export interface CategoryListResponse extends ListEnvelope {
-  product_categories: StoreProductCategory[]
-}
-
-export interface CategoryResponse {
-  product_category: StoreProductCategory
-}
-
-export interface RetrieveCategoryQuery {
-  include_ancestors_tree?: boolean
-  include_descendants_tree?: boolean
-}
-
-export interface ListTagsQuery extends PaginationQuery {
-  /** Case-insensitive substring match on value. */
-  q?: string
-  /** Exact value match. */
-  value?: string
-}
-
-export interface TagListResponse extends ListEnvelope {
-  product_tags: StoreProductTag[]
-}
-
-export interface TagResponse {
-  product_tag: StoreProductTag
-}
-
-export type ListTypesQuery = ListTagsQuery
-
-export interface TypeListResponse extends ListEnvelope {
-  product_types: StoreProductType[]
-}
-
-export interface TypeResponse {
-  product_type: StoreProductType
-}
-
-/**
- * List active, non-internal categories ordered by `rank`. Tree flags embed
- * ancestors/descendants per row (visible categories only).
- *
- * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
- * 400 `validation_failed`. Settings: category `is_active`/`is_internal`
- * flags and rank ordering (Admin → Categories).
- */
-export async function listCategories(
-  client: StorefrontClient,
-  query?: ListCategoriesQuery
-): Promise<CategoryListResponse> {
-  return client.get("/api/store/product-categories", { query: { ...query } })
-}
-
-/**
- * Retrieve one category by id, optionally with its ancestor/descendant tree.
- *
- * Auth: anon (`x-client-id`). Errors: 404 `not_found` (unknown, deleted, or
- * inactive/internal — RLS hides them even by id).
- */
-export async function retrieveCategory(
-  client: StorefrontClient,
-  categoryId: string,
-  query?: RetrieveCategoryQuery
-): Promise<CategoryResponse> {
-  return client.get(`/api/store/product-categories/${encodeURIComponent(categoryId)}`, {
-    query: { ...query },
-  })
-}
-
-/**
- * List product tags ordered by value (filter chips; tag ids feed
- * `tag_id` filters on product listings and search).
- *
- * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
- * 400 `validation_failed`.
- */
-export async function listProductTags(
-  client: StorefrontClient,
-  query?: ListTagsQuery
-): Promise<TagListResponse> {
-  return client.get("/api/store/product-tags", { query: { ...query } })
-}
-
-/**
- * Retrieve one product tag by id.
- *
- * Auth: anon (`x-client-id`). Errors: 404 `not_found`.
- */
-export async function retrieveProductTag(
-  client: StorefrontClient,
-  tagId: string
-): Promise<TagResponse> {
-  return client.get(`/api/store/product-tags/${encodeURIComponent(tagId)}`)
-}
-
-/**
- * List product types ordered by value (type ids feed `type_id` filters on
- * product listings and search).
- *
- * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
- * 400 `validation_failed`.
- */
-export async function listProductTypes(
-  client: StorefrontClient,
-  query?: ListTypesQuery
-): Promise<TypeListResponse> {
-  return client.get("/api/store/product-types", { query: { ...query } })
-}
-
-/**
- * Retrieve one product type by id.
- *
- * Auth: anon (`x-client-id`). Errors: 404 `not_found`.
- */
-export async function retrieveProductType(
-  client: StorefrontClient,
-  typeId: string
-): Promise<TypeResponse> {
-  return client.get(`/api/store/product-types/${encodeURIComponent(typeId)}`)
-}
+/**
+ * @cartbase/storefront/api/categories — product categories, tags, types.
+ *
+ * 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. Only ACTIVE, non-internal
+ * categories are storefront-visible (RLS-enforced — inactive/internal 404
+ * even by id). Docs: docs/storefront/categories.md.
+ */
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, ListEnvelope, PaginationQuery } from "./types"
+
+export interface StoreProductCategory {
+  id: string
+  name: string
+  handle: string
+  description: string | null
+  parent_category_id: string | null
+  rank: number
+  is_active: true
+  is_internal: false
+  /** Materialized path (internal ordering detail). */
+  mpath: string | null
+  /** SEO override; null = fall back to `name`. */
+  seo_title: string | null
+  /** SEO override; null = fall back to `description`. */
+  seo_description: string | null
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  /** Present only when `include_descendants_tree` was requested. */
+  category_children?: StoreProductCategory[]
+  /** Present only when `include_ancestors_tree` was requested. */
+  parent_category?: StoreProductCategory | null
+}
+
+export interface StoreProductTag {
+  id: string
+  value: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+export interface StoreProductType {
+  id: string
+  value: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+export interface ListCategoriesQuery extends PaginationQuery {
+  /** Case-insensitive substring match on name. */
+  q?: string
+  handle?: string
+  /** List one level: children of this category. */
+  parent_category_id?: string
+  /** Embed `parent_category` chains on each row. */
+  include_ancestors_tree?: boolean
+  /** Embed `category_children` recursively on each row. */
+  include_descendants_tree?: boolean
+}
+
+export interface CategoryListResponse extends ListEnvelope {
+  product_categories: StoreProductCategory[]
+}
+
+export interface CategoryResponse {
+  product_category: StoreProductCategory
+}
+
+export interface RetrieveCategoryQuery {
+  include_ancestors_tree?: boolean
+  include_descendants_tree?: boolean
+}
+
+export interface ListTagsQuery extends PaginationQuery {
+  /** Case-insensitive substring match on value. */
+  q?: string
+  /** Exact value match. */
+  value?: string
+}
+
+export interface TagListResponse extends ListEnvelope {
+  product_tags: StoreProductTag[]
+}
+
+export interface TagResponse {
+  product_tag: StoreProductTag
+}
+
+export type ListTypesQuery = ListTagsQuery
+
+export interface TypeListResponse extends ListEnvelope {
+  product_types: StoreProductType[]
+}
+
+export interface TypeResponse {
+  product_type: StoreProductType
+}
+
+/**
+ * List active, non-internal categories ordered by `rank`. Tree flags embed
+ * ancestors/descendants per row (visible categories only).
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`. Settings: category `is_active`/`is_internal`
+ * flags and rank ordering (Admin → Categories).
+ */
+export async function listCategories(
+  client: StorefrontClient,
+  query?: ListCategoriesQuery
+): Promise<CategoryListResponse> {
+  return client.get("/api/store/product-categories", { query: { ...query } })
+}
+
+/**
+ * Retrieve one category by id, optionally with its ancestor/descendant tree.
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found` (unknown, deleted, or
+ * inactive/internal — RLS hides them even by id).
+ */
+export async function retrieveCategory(
+  client: StorefrontClient,
+  categoryId: string,
+  query?: RetrieveCategoryQuery
+): Promise<CategoryResponse> {
+  return client.get(`/api/store/product-categories/${encodeURIComponent(categoryId)}`, {
+    query: { ...query },
+  })
+}
+
+/**
+ * List product tags ordered by value (filter chips; tag ids feed
+ * `tag_id` filters on product listings and search).
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`.
+ */
+export async function listProductTags(
+  client: StorefrontClient,
+  query?: ListTagsQuery
+): Promise<TagListResponse> {
+  return client.get("/api/store/product-tags", { query: { ...query } })
+}
+
+/**
+ * Retrieve one product tag by id.
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found`.
+ */
+export async function retrieveProductTag(
+  client: StorefrontClient,
+  tagId: string
+): Promise<TagResponse> {
+  return client.get(`/api/store/product-tags/${encodeURIComponent(tagId)}`)
+}
+
+/**
+ * List product types ordered by value (type ids feed `type_id` filters on
+ * product listings and search).
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`.
+ */
+export async function listProductTypes(
+  client: StorefrontClient,
+  query?: ListTypesQuery
+): Promise<TypeListResponse> {
+  return client.get("/api/store/product-types", { query: { ...query } })
+}
+
+/**
+ * Retrieve one product type by id.
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found`.
+ */
+export async function retrieveProductType(
+  client: StorefrontClient,
+  typeId: string
+): Promise<TypeResponse> {
+  return client.get(`/api/store/product-types/${encodeURIComponent(typeId)}`)
+}