@cartbase/storefront 0.14.0 → 0.16.0

package/src/api/products.ts

@@ -1,310 +1,330 @@
-/**
- * @cartbase/storefront/api/products — products + product variants.
- *
- * The catalog read surface. Response shapes are the canonical store product
- * object every discovery endpoint reuses (search results, collection
- * membership pages, related products) — build ONE product-card renderer
- * against `StoreProduct` and reuse it everywhere.
- *
- * Pricing: pass `currency_code` (or `region_id`) to receive
- * `variant.calculated_price` (group-aware when a customer JWT is attached).
- * Raw `prices` embeds contain BASE rows only — price-list rows are stripped
- * server-side (leak rule) and surface exclusively through
- * `calculated_price`. Docs: docs/storefront/products.md.
- */
-import type { StorefrontClient } from "./http"
-import type {
-  CalculatedPrice,
-  IsoDateString,
-  ListEnvelope,
-  PaginationQuery,
-  PricingContextQuery,
-} from "./types"
-
-/** Raw base price row (`prices` table). Amounts are EUR-style major units. */
-export interface StorePriceRow {
-  id: string
-  amount: number
-  currency_code: string
-  min_quantity: number | null
-  max_quantity: number | null
-  price_set_id: string
-  /** Always null on the store surface — price-list rows are stripped. */
-  price_list_id: string | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-}
-
-/**
- * The wire shape of `variant.prices`: a price-set LINK embed, not a flat
- * array. Base rows live at `prices[].price_set.prices[]`.
- */
-export interface StoreVariantPriceSetLink {
-  price_set: { prices: StorePriceRow[] | null } | null
-}
-
-/** `variant.options[]` — the option VALUE with its parent option embedded. */
-export interface StoreVariantOptionValueLink {
-  value: {
-    id: string
-    value: string
-    option_id: string
-    metadata: Record<string, unknown> | null
-    option: StoreProductOption | null
-  } | null
-}
-
-export interface StoreProductOptionValue {
-  id: string
-  value: string
-  option_id: string
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-}
-
-export interface StoreProductOption {
-  id: string
-  title: string
-  product_id: string
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-  /** Present on `product.options[]`; absent inside variant option links. */
-  values?: StoreProductOptionValue[]
-}
-
-export interface StoreProductImage {
-  id: string
-  url: string
-  rank: number
-  product_id: string
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-}
-
-export interface StoreProductVariant {
-  id: string
-  title: string
-  product_id: string
-  sku: string | null
-  barcode: string | null
-  ean: string | null
-  upc: string | null
-  thumbnail: string | null
-  allow_backorder: boolean
-  manage_inventory: boolean
-  variant_rank: number
-  weight: number | null
-  length: number | null
-  height: number | null
-  width: number | null
-  hs_code: string | null
-  origin_country: string | null
-  mid_code: string | null
-  material: string | null
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-  options: StoreVariantOptionValueLink[]
-  /** Base-price rows via the price-set link embed (leak rule applied). */
-  prices: StoreVariantPriceSetLink[]
-  /**
-   * Present when a pricing context was resolvable (`currency_code` or
-   * `region_id` given); null otherwise, and null when no price matches the
-   * context. Varies by customer group — never cache shared.
-   */
-  calculated_price: CalculatedPrice | null
-  /**
-   * THE availability predicate, computed server-side (untracked or
-   * backorderable ⇒ true; otherwise kit-aware available stock > 0).
-   * Optional only for wire back-compat with platforms that predate it —
-   * when absent, components fall back to the optimistic legacy behavior.
-   */
-  in_stock?: boolean
-}
-
-export interface StoreProduct {
-  id: string
-  title: string
-  subtitle: string | null
-  description: string | null
-  handle: string
-  status: "published"
-  thumbnail: string | null
-  is_giftcard: boolean
-  discountable: boolean
-  collection_id: string | null
-  type_id: string | null
-  external_id: string | null
-  weight: number | null
-  length: number | null
-  height: number | null
-  width: number | null
-  hs_code: string | null
-  origin_country: string | null
-  mid_code: string | null
-  material: string | null
-  /** SEO override; null = fall back to `title`. */
-  seo_title: string | null
-  /** SEO override; null = fall back to the plain-text `description`. */
-  seo_description: string | null
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-  variants: StoreProductVariant[]
-  images: StoreProductImage[]
-  options: StoreProductOption[]
-  collection: { id: string; title: string; handle: string } | null
-  categories: Array<{ category: { id: string; name: string; handle: string } | null }>
-  tags: Array<{ tag: { id: string; value: string } | null }>
-  type: { id: string; value: string } | null
-}
-
-export interface ListProductsQuery extends PricingContextQuery, PaginationQuery {
-  /** Case-insensitive substring match on title (full search: use /search). */
-  q?: string
-  /** Product ids (joined as CSV on the wire). */
-  id?: string[]
-  handle?: string
-  collection_id?: string[]
-  category_id?: string[]
-  tag_id?: string[]
-  type_id?: string[]
-  /**
-   * Sort column; prefix with `-` for descending (e.g. `-created_at`,
-   * the default).
-   */
-  order?: string
-}
-
-export interface ProductListResponse extends ListEnvelope {
-  products: StoreProduct[]
-}
-
-export interface ProductResponse {
-  product: StoreProduct
-}
-
-export interface ListProductVariantsQuery extends PricingContextQuery, PaginationQuery {
-  /** Variant ids as CSV in ONE string (wire format of the route). */
-  id?: string
-  product_id?: string
-  sku?: string
-}
-
-export interface ProductVariantListResponse extends ListEnvelope {
-  variants: StoreProductVariant[]
-}
-
-export interface ProductVariantResponse {
-  variant: StoreProductVariant
-}
-
-/**
- * List published products (newest first by default).
- *
- * Auth: anon (`x-client-id`); optional `x-publishable-api-key` restricts the
- * catalog to products linked to the key's sales channels (a channel-scoped
- * key with no matching products returns an empty list). Optional Bearer JWT
- * makes `calculated_price` customer-group-aware.
- *
- * Errors: 400 `missing_client_id`, 400 `validation_failed`,
- * 400 `invalid_publishable_key`, 400 `invalid_region`.
- * Settings: price lists (B2B pricing), sales-channel product links,
- * publishable-key channel bindings.
- */
-export async function listProducts(
-  client: StorefrontClient,
-  query?: ListProductsQuery
-): Promise<ProductListResponse> {
-  return client.get("/api/store/products", { query: { ...query } })
-}
-
-/**
- * Retrieve one product by id (`prod_…`) or handle — storefronts deep-link by
- * handle.
- *
- * Auth: anon (`x-client-id`); optional publishable key + Bearer JWT as on
- * the list. Errors: 404 `not_found` (unknown, draft — RLS-hidden — or
- * outside the key's channels: invisible, not forbidden),
- * 400 `invalid_publishable_key`, 400 `invalid_region`.
- */
-export async function retrieveProduct(
-  client: StorefrontClient,
-  idOrHandle: string,
-  query?: PricingContextQuery
-): Promise<ProductResponse> {
-  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}`, {
-    query: { ...query },
-  })
-}
-
-/**
- * List product variants (cart-line hydration). `id` accepts a CSV of variant
- * ids for multi-lookup. Ordered by `variant_rank`.
- *
- * Auth: anon (`x-client-id`); optional Bearer JWT for group-aware
- * `calculated_price`. NOTE: this listing is NOT publishable-key
- * channel-scoped (scope applies to product reads). Errors:
- * 400 `missing_client_id`, 400 `validation_failed`, 400 `invalid_region`.
- */
-export async function listProductVariants(
-  client: StorefrontClient,
-  query?: ListProductVariantsQuery
-): Promise<ProductVariantListResponse> {
-  return client.get("/api/store/product-variants", { query: { ...query } })
-}
-
-/**
- * Retrieve one variant by id, options + base prices hydrated,
- * `calculated_price` when a pricing context is given.
- *
- * Auth: anon (`x-client-id`). Errors: 404 `not_found`, 400 `invalid_region`.
- */
-export async function retrieveProductVariant(
-  client: StorefrontClient,
-  variantId: string,
-  query?: PricingContextQuery
-): Promise<ProductVariantResponse> {
-  return client.get(`/api/store/product-variants/${encodeURIComponent(variantId)}`, {
-    query: { ...query },
-  })
-}
-
-/** A subscription offer on a product (PDP purchase options). */
-export interface StoreSellingPlan {
-  id: string
-  name: string
-  interval: "day" | "week" | "month" | "year"
-  interval_count: number
-  /** null = catalog price (the plan only sets the cadence). */
-  pricing_type: "percent" | "fixed" | null
-  pricing_value: number | null
-  min_cycles: number | null
-  max_cycles: number | null
-}
-
-export interface SellingPlanListResponse {
-  selling_plans: StoreSellingPlan[]
-  count: number
-}
-
-/**
- * The subscription plans a product can be purchased with — render as PDP
- * purchase options (one-time vs each plan). The chosen plan id goes on the
- * cart line (`carts.addLineItem` `selling_plan_id`); the server applies the
- * plan price. Empty list = product is one-time only.
- *
- * Auth: anon (`x-client-id`); publishable-key channel scope applies (same
- * rule as the product read). Errors: 404 `not_found`.
- */
-export async function listSellingPlans(
-  client: StorefrontClient,
-  idOrHandle: string
-): Promise<SellingPlanListResponse> {
-  return client.get(
-    `/api/store/products/${encodeURIComponent(idOrHandle)}/selling-plans`
-  )
-}
+/**
+ * @cartbase/storefront/api/products — products + product variants.
+ *
+ * The catalog read surface. Response shapes are the canonical store product
+ * object every discovery endpoint reuses (search results, collection
+ * membership pages, related products) — build ONE product-card renderer
+ * against `StoreProduct` and reuse it everywhere.
+ *
+ * Pricing: pass `currency_code` (or `region_id`) to receive
+ * `variant.calculated_price` (group-aware when a customer JWT is attached).
+ * Raw `prices` embeds contain BASE rows only — price-list rows are stripped
+ * server-side (leak rule) and surface exclusively through
+ * `calculated_price`. Docs: docs/storefront/products.md.
+ */
+import type { StorefrontClient } from "./http"
+import type {
+  CalculatedPrice,
+  IsoDateString,
+  ListEnvelope,
+  PaginationQuery,
+  PricingContextQuery,
+} from "./types"
+
+/** Raw base price row (`prices` table). Amounts are EUR-style major units. */
+export interface StorePriceRow {
+  id: string
+  amount: number
+  currency_code: string
+  min_quantity: number | null
+  max_quantity: number | null
+  price_set_id: string
+  /** Always null on the store surface — price-list rows are stripped. */
+  price_list_id: string | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+/**
+ * The wire shape of `variant.prices`: a price-set LINK embed, not a flat
+ * array. Base rows live at `prices[].price_set.prices[]`.
+ */
+export interface StoreVariantPriceSetLink {
+  price_set: { prices: StorePriceRow[] | null } | null
+}
+
+/** `variant.options[]` — the option VALUE with its parent option embedded. */
+export interface StoreVariantOptionValueLink {
+  value: {
+    id: string
+    value: string
+    option_id: string
+    metadata: Record<string, unknown> | null
+    option: StoreProductOption | null
+  } | null
+}
+
+export interface StoreProductOptionValue {
+  id: string
+  value: string
+  option_id: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+export interface StoreProductOption {
+  id: string
+  title: string
+  product_id: string
+  /** The merchant's order of the options on the product page. */
+  position: number
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  /** Present on `product.options[]`; absent inside variant option links. */
+  values?: StoreProductOptionValue[]
+}
+
+export interface StoreProductImage {
+  id: string
+  url: string
+  rank: number
+  product_id: string
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+}
+
+export interface StoreProductVariant {
+  id: string
+  title: string
+  product_id: string
+  sku: string | null
+  barcode: string | null
+  ean: string | null
+  upc: string | null
+  thumbnail: string | null
+  allow_backorder: boolean
+  manage_inventory: boolean
+  variant_rank: number
+  weight: number | null
+  length: number | null
+  height: number | null
+  width: number | null
+  hs_code: string | null
+  origin_country: string | null
+  mid_code: string | null
+  material: string | null
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  options: StoreVariantOptionValueLink[]
+  /** Base-price rows via the price-set link embed (leak rule applied). */
+  prices: StoreVariantPriceSetLink[]
+  /**
+   * Present when a pricing context was resolvable (`currency_code` or
+   * `region_id` given); null otherwise, and null when no price matches the
+   * context. Varies by customer group — never cache shared.
+   */
+  calculated_price: CalculatedPrice | null
+  /**
+   * THE availability predicate, computed server-side (untracked or
+   * backorderable ⇒ true; otherwise kit-aware available stock > 0).
+   * Optional only for wire back-compat with platforms that predate it —
+   * when absent, components fall back to the optimistic legacy behavior.
+   */
+  in_stock?: boolean
+}
+
+export interface StoreProduct {
+  id: string
+  title: string
+  subtitle: string | null
+  description: string | null
+  handle: string
+  status: "published"
+  thumbnail: string | null
+  is_giftcard: boolean
+  discountable: boolean
+  type_id: string | null
+  external_id: string | null
+  /** The brand, as plain text on the product (product-vendor card). */
+  vendor: string | null
+  weight: number | null
+  length: number | null
+  height: number | null
+  width: number | null
+  hs_code: string | null
+  origin_country: string | null
+  mid_code: string | null
+  material: string | null
+  /** SEO override; null = fall back to `title`. */
+  seo_title: string | null
+  /** SEO override; null = fall back to the plain-text `description`. */
+  seo_description: string | null
+  metadata: Record<string, unknown> | null
+  /**
+   * The store's custom fields under their definition keys
+   * (`custom.product_label_1`), values as stored: a string for text, a
+   * number, a boolean, an array for a list, an id for a metaobject
+   * reference. Public definitions only (Settings, Custom fields switches one
+   * off); always present, `{}` when the product has none. Served by every
+   * product read since 2026-09-14 (docs/storefront/products.md).
+   */
+  metafields: Record<string, unknown>
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  variants: StoreProductVariant[]
+  images: StoreProductImage[]
+  options: StoreProductOption[]
+  /**
+   * EVERY collection the product belongs to, in the shape categories and
+   * tags already had. It was a single `collection` object resolved through
+   * products.collection_id, a column that held one of a product's
+   * collections at most and none at all for the ones a catalogue migration
+   * or a smart rule placed; the membership join is the one store since
+   * 2026-09-15 (docs/storefront/products.md).
+   */
+  collections: Array<{ collection: { id: string; title: string; handle: string } | null }>
+  categories: Array<{ category: { id: string; name: string; handle: string } | null }>
+  tags: Array<{ tag: { id: string; value: string } | null }>
+  type: { id: string; value: string } | null
+}
+
+export interface ListProductsQuery extends PricingContextQuery, PaginationQuery {
+  /** Case-insensitive substring match on title (full search: use /search). */
+  q?: string
+  /** Product ids (joined as CSV on the wire). */
+  id?: string[]
+  handle?: string
+  collection_id?: string[]
+  category_id?: string[]
+  tag_id?: string[]
+  type_id?: string[]
+  /**
+   * Sort column; prefix with `-` for descending (e.g. `-created_at`,
+   * the default).
+   */
+  order?: string
+}
+
+export interface ProductListResponse extends ListEnvelope {
+  products: StoreProduct[]
+}
+
+export interface ProductResponse {
+  product: StoreProduct
+}
+
+export interface ListProductVariantsQuery extends PricingContextQuery, PaginationQuery {
+  /** Variant ids as CSV in ONE string (wire format of the route). */
+  id?: string
+  product_id?: string
+  sku?: string
+}
+
+export interface ProductVariantListResponse extends ListEnvelope {
+  variants: StoreProductVariant[]
+}
+
+export interface ProductVariantResponse {
+  variant: StoreProductVariant
+}
+
+/**
+ * List published products (newest first by default).
+ *
+ * Auth: anon (`x-client-id`); optional `x-publishable-api-key` restricts the
+ * catalog to products linked to the key's sales channels (a channel-scoped
+ * key with no matching products returns an empty list). Optional Bearer JWT
+ * makes `calculated_price` customer-group-aware.
+ *
+ * Errors: 400 `missing_client_id`, 400 `validation_failed`,
+ * 400 `invalid_publishable_key`, 400 `invalid_region`.
+ * Settings: price lists (B2B pricing), sales-channel product links,
+ * publishable-key channel bindings.
+ */
+export async function listProducts(
+  client: StorefrontClient,
+  query?: ListProductsQuery
+): Promise<ProductListResponse> {
+  return client.get("/api/store/products", { query: { ...query } })
+}
+
+/**
+ * Retrieve one product by id (`prod_…`) or handle — storefronts deep-link by
+ * handle.
+ *
+ * Auth: anon (`x-client-id`); optional publishable key + Bearer JWT as on
+ * the list. Errors: 404 `not_found` (unknown, draft — RLS-hidden — or
+ * outside the key's channels: invisible, not forbidden),
+ * 400 `invalid_publishable_key`, 400 `invalid_region`.
+ */
+export async function retrieveProduct(
+  client: StorefrontClient,
+  idOrHandle: string,
+  query?: PricingContextQuery
+): Promise<ProductResponse> {
+  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}`, {
+    query: { ...query },
+  })
+}
+
+/**
+ * List product variants (cart-line hydration). `id` accepts a CSV of variant
+ * ids for multi-lookup. Ordered by `variant_rank`.
+ *
+ * Auth: anon (`x-client-id`); optional Bearer JWT for group-aware
+ * `calculated_price`. NOTE: this listing is NOT publishable-key
+ * channel-scoped (scope applies to product reads). Errors:
+ * 400 `missing_client_id`, 400 `validation_failed`, 400 `invalid_region`.
+ */
+export async function listProductVariants(
+  client: StorefrontClient,
+  query?: ListProductVariantsQuery
+): Promise<ProductVariantListResponse> {
+  return client.get("/api/store/product-variants", { query: { ...query } })
+}
+
+/**
+ * Retrieve one variant by id, options + base prices hydrated,
+ * `calculated_price` when a pricing context is given.
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found`, 400 `invalid_region`.
+ */
+export async function retrieveProductVariant(
+  client: StorefrontClient,
+  variantId: string,
+  query?: PricingContextQuery
+): Promise<ProductVariantResponse> {
+  return client.get(`/api/store/product-variants/${encodeURIComponent(variantId)}`, {
+    query: { ...query },
+  })
+}
+
+/** A subscription offer on a product (PDP purchase options). */
+export interface StoreSellingPlan {
+  id: string
+  name: string
+  interval: "day" | "week" | "month" | "year"
+  interval_count: number
+  /** null = catalog price (the plan only sets the cadence). */
+  pricing_type: "percent" | "fixed" | null
+  pricing_value: number | null
+  min_cycles: number | null
+  max_cycles: number | null
+}
+
+export interface SellingPlanListResponse {
+  selling_plans: StoreSellingPlan[]
+  count: number
+}
+
+/**
+ * The subscription plans a product can be purchased with — render as PDP
+ * purchase options (one-time vs each plan). The chosen plan id goes on the
+ * cart line (`carts.addLineItem` `selling_plan_id`); the server applies the
+ * plan price. Empty list = product is one-time only.
+ *
+ * Auth: anon (`x-client-id`); publishable-key channel scope applies (same
+ * rule as the product read). Errors: 404 `not_found`.
+ */
+export async function listSellingPlans(
+  client: StorefrontClient,
+  idOrHandle: string
+): Promise<SellingPlanListResponse> {
+  return client.get(
+    `/api/store/products/${encodeURIComponent(idOrHandle)}/selling-plans`
+  )
+}