@cartbase/storefront 0.17.0 → 0.18.0

package/src/api/search.ts

@@ -1,163 +1,163 @@
-/**
- * @cartbase/storefront/api/search — storefront search + related products
- * (search-discovery card).
- *
- * Results are the SAME `StoreProduct` objects the products listing serves —
- * reuse your product-card renderer as-is. Matching: full-text
- * (Cyrillic-correct, prefix) ∪ title trigram typo tolerance ∪ SKU prefix ∪
- * exact tag value; admin synonyms expand bidirectionally one level; admin
- * pins for the exact query rank first, then global boosts, then relevance.
- * Docs: docs/storefront/search.md.
- */
-import type { Query, StorefrontClient } from "./http"
-import type { PricingContextQuery } from "./types"
-import type { StoreProduct } from "./products"
-
-export interface SearchFacetBucket {
-  /** Filter value to send back (id, option value, or "min-max" for price). */
-  value: string
-  label: string
-  count: number
-  /** Range (price) buckets only — pass back as `price_min`/`price_max`. */
-  min?: number
-  max?: number | null
-}
-
-export interface SearchFacet {
-  /** "price" | "availability" | "type" | "tags" | "collection" | "options.<Title>" */
-  key: string
-  label: string
-  type: "value" | "range"
-  buckets: SearchFacetBucket[]
-}
-
-export interface SearchProductsQuery extends PricingContextQuery {
-  /** Required, min 1 char. */
-  q: string
-  collection_id?: string[]
-  category_id?: string[]
-  tag_id?: string[]
-  type_id?: string[]
-  /** Major units in the pricing currency, applied to the cheapest base price. */
-  price_min?: number
-  price_max?: number
-  availability?: "in_stock" | "out_of_stock"
-  /**
-   * Option filters: title → accepted values (OR within an option, AND
-   * across options). Serialized as `option.<Title>=v1,v2` params.
-   */
-  options?: Record<string, string[]>
-  /** 1–100, default 20. */
-  limit?: number
-  offset?: number
-}
-
-export interface SearchProductsResponse {
-  results: StoreProduct[]
-  /**
-   * Per the tenant's Settings → Search & discovery → Filters config.
-   * Counts follow the standard faceting rule: each facet is computed on the
-   * result set filtered by every OTHER active filter (own dimension
-   * excluded). Empty buckets and empty facets are omitted.
-   */
-  facets: SearchFacet[]
-  total: number
-  offset: number
-  limit: number
-}
-
-export interface RelatedProductsQuery extends PricingContextQuery {
-  /** 1–24, default 12. */
-  limit?: number
-}
-
-/**
- * Complementary products — the merchant's "goes with this" picks, for the
- * slot ABOVE the product rather than the carousel below it.
- *
- * It has no fallback and never will: "similar to this" can be computed from
- * collections and tags, "buy this with it" is a merchant judgement, and a
- * guessed upsell beside the buy button is worse than an empty slot. An empty
- * response means the merchant has not chosen — render nothing.
- */
-export type ComplementaryProductsQuery = RelatedProductsQuery
-
-export interface RelatedProductsResponse {
-  products: StoreProduct[]
-  count: number
-  /** True when any item came from the deterministic fallback chain. */
-  auto_filled: boolean
-}
-
-/** Fold the `options` record into `option.<Title>` wire params. */
-function toSearchParams(query: SearchProductsQuery): Query {
-  const { options, ...rest } = query
-  const out: Query = { ...rest }
-  if (options) {
-    for (const [title, values] of Object.entries(options)) {
-      if (values.length) out[`option.${title}`] = values
-    }
-  }
-  return out
-}
-
-/**
- * Search published products. Draft products, other tenants, and products
- * outside the publishable key's channels NEVER appear (pins included).
- *
- * Auth: anon (`x-client-id`); optional `x-publishable-api-key` scopes the
- * catalog to the key's channels (empty results when nothing matches);
- * optional Bearer JWT makes `calculated_price` group-aware — never cache
- * price-decorated responses shared.
- *
- * Errors: 400 `missing_client_id`, 400 `validation_failed` (missing/empty
- * `q`, bad enum), 400 `invalid_publishable_key`, 400 `invalid_region`.
- * Settings: Search & discovery — synonyms, pins/boosts, facet config
- * (order/enabled, price bucket strategy).
- */
-export async function searchProducts(
-  client: StorefrontClient,
-  query: SearchProductsQuery
-): Promise<SearchProductsResponse> {
-  return client.get("/api/store/products/search", { query: toSearchParams(query) })
-}
-
-/**
- * Related products for a PDP: manual admin picks first (position order),
- * then a deterministic fallback fills to `limit` — same primary collection
- * (newest first), then most-shared-tags. Accepts a product id or handle.
- *
- * Auth: anon (`x-client-id`); optional publishable key — the anchor product
- * must be visible to the key (404 otherwise) and scoped-away products never
- * appear as related items. Errors: 404 `not_found` (unknown/draft/
- * channel-hidden anchor), 400 `validation_failed`, 400 `invalid_region`.
- * Settings: manual related picks (Admin → Product → Related).
- */
-export async function listRelatedProducts(
-  client: StorefrontClient,
-  idOrHandle: string,
-  query?: RelatedProductsQuery
-): Promise<RelatedProductsResponse> {
-  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}/related`, {
-    query: { ...query },
-  })
-}
-
-/**
- * Complementary products for a PDP: the merchant's manual picks, in their
- * order, and nothing else — `auto_filled` is always false.
- *
- * Same endpoint as related, discriminated by `kind`, because the two lists
- * are one table and one code path apart only by meaning. Auth, errors and
- * channel scoping are identical to `listRelatedProducts`.
- * Settings: Admin → Product → Complementary products.
- */
-export async function listComplementaryProducts(
-  client: StorefrontClient,
-  idOrHandle: string,
-  query?: ComplementaryProductsQuery
-): Promise<RelatedProductsResponse> {
-  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}/related`, {
-    query: { ...query, kind: "complementary" },
-  })
-}
+/**
+ * @cartbase/storefront/api/search — storefront search + related products
+ * (search-discovery card).
+ *
+ * Results are the SAME `StoreProduct` objects the products listing serves —
+ * reuse your product-card renderer as-is. Matching: full-text
+ * (Cyrillic-correct, prefix) ∪ title trigram typo tolerance ∪ SKU prefix ∪
+ * exact tag value; admin synonyms expand bidirectionally one level; admin
+ * pins for the exact query rank first, then global boosts, then relevance.
+ * Docs: docs/storefront/search.md.
+ */
+import type { Query, StorefrontClient } from "./http"
+import type { PricingContextQuery } from "./types"
+import type { StoreProduct } from "./products"
+
+export interface SearchFacetBucket {
+  /** Filter value to send back (id, option value, or "min-max" for price). */
+  value: string
+  label: string
+  count: number
+  /** Range (price) buckets only — pass back as `price_min`/`price_max`. */
+  min?: number
+  max?: number | null
+}
+
+export interface SearchFacet {
+  /** "price" | "availability" | "type" | "tags" | "collection" | "options.<Title>" */
+  key: string
+  label: string
+  type: "value" | "range"
+  buckets: SearchFacetBucket[]
+}
+
+export interface SearchProductsQuery extends PricingContextQuery {
+  /** Required, min 1 char. */
+  q: string
+  collection_id?: string[]
+  category_id?: string[]
+  tag_id?: string[]
+  type_id?: string[]
+  /** Major units in the pricing currency, applied to the cheapest base price. */
+  price_min?: number
+  price_max?: number
+  availability?: "in_stock" | "out_of_stock"
+  /**
+   * Option filters: title → accepted values (OR within an option, AND
+   * across options). Serialized as `option.<Title>=v1,v2` params.
+   */
+  options?: Record<string, string[]>
+  /** 1–100, default 20. */
+  limit?: number
+  offset?: number
+}
+
+export interface SearchProductsResponse {
+  results: StoreProduct[]
+  /**
+   * Per the tenant's Settings → Search & discovery → Filters config.
+   * Counts follow the standard faceting rule: each facet is computed on the
+   * result set filtered by every OTHER active filter (own dimension
+   * excluded). Empty buckets and empty facets are omitted.
+   */
+  facets: SearchFacet[]
+  total: number
+  offset: number
+  limit: number
+}
+
+export interface RelatedProductsQuery extends PricingContextQuery {
+  /** 1–24, default 12. */
+  limit?: number
+}
+
+/**
+ * Complementary products — the merchant's "goes with this" picks, for the
+ * slot ABOVE the product rather than the carousel below it.
+ *
+ * It has no fallback and never will: "similar to this" can be computed from
+ * collections and tags, "buy this with it" is a merchant judgement, and a
+ * guessed upsell beside the buy button is worse than an empty slot. An empty
+ * response means the merchant has not chosen — render nothing.
+ */
+export type ComplementaryProductsQuery = RelatedProductsQuery
+
+export interface RelatedProductsResponse {
+  products: StoreProduct[]
+  count: number
+  /** True when any item came from the deterministic fallback chain. */
+  auto_filled: boolean
+}
+
+/** Fold the `options` record into `option.<Title>` wire params. */
+function toSearchParams(query: SearchProductsQuery): Query {
+  const { options, ...rest } = query
+  const out: Query = { ...rest }
+  if (options) {
+    for (const [title, values] of Object.entries(options)) {
+      if (values.length) out[`option.${title}`] = values
+    }
+  }
+  return out
+}
+
+/**
+ * Search published products. Draft products, other tenants, and products
+ * outside the publishable key's channels NEVER appear (pins included).
+ *
+ * Auth: anon (`x-client-id`); optional `x-publishable-api-key` scopes the
+ * catalog to the key's channels (empty results when nothing matches);
+ * optional Bearer JWT makes `calculated_price` group-aware — never cache
+ * price-decorated responses shared.
+ *
+ * Errors: 400 `missing_client_id`, 400 `validation_failed` (missing/empty
+ * `q`, bad enum), 400 `invalid_publishable_key`, 400 `invalid_region`.
+ * Settings: Search & discovery — synonyms, pins/boosts, facet config
+ * (order/enabled, price bucket strategy).
+ */
+export async function searchProducts(
+  client: StorefrontClient,
+  query: SearchProductsQuery
+): Promise<SearchProductsResponse> {
+  return client.get("/api/store/products/search", { query: toSearchParams(query) })
+}
+
+/**
+ * Related products for a PDP: manual admin picks first (position order),
+ * then a deterministic fallback fills to `limit` — same primary collection
+ * (newest first), then most-shared-tags. Accepts a product id or handle.
+ *
+ * Auth: anon (`x-client-id`); optional publishable key — the anchor product
+ * must be visible to the key (404 otherwise) and scoped-away products never
+ * appear as related items. Errors: 404 `not_found` (unknown/draft/
+ * channel-hidden anchor), 400 `validation_failed`, 400 `invalid_region`.
+ * Settings: manual related picks (Admin → Product → Related).
+ */
+export async function listRelatedProducts(
+  client: StorefrontClient,
+  idOrHandle: string,
+  query?: RelatedProductsQuery
+): Promise<RelatedProductsResponse> {
+  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}/related`, {
+    query: { ...query },
+  })
+}
+
+/**
+ * Complementary products for a PDP: the merchant's manual picks, in their
+ * order, and nothing else — `auto_filled` is always false.
+ *
+ * Same endpoint as related, discriminated by `kind`, because the two lists
+ * are one table and one code path apart only by meaning. Auth, errors and
+ * channel scoping are identical to `listRelatedProducts`.
+ * Settings: Admin → Product → Complementary products.
+ */
+export async function listComplementaryProducts(
+  client: StorefrontClient,
+  idOrHandle: string,
+  query?: ComplementaryProductsQuery
+): Promise<RelatedProductsResponse> {
+  return client.get(`/api/store/products/${encodeURIComponent(idOrHandle)}/related`, {
+    query: { ...query, kind: "complementary" },
+  })
+}

package/src/api/store.ts

@@ -1,35 +1,35 @@
-/**
- * @cartbase/storefront/api/store — the store's identity.
- *
- * Name, slug and brand (the merchant's Settings → Brand): what a
- * storefront needs to title, head and foot itself without hardcoding a
- * name. One anonymous read at layout level. Docs: docs/storefront/store.md.
- */
-import type { StorefrontClient } from "./http"
-
-export interface StoreBrand {
-  /** Primary logo, public URL, or null. */
-  logo_url: string | null
-  /** Square mark, public URL, or null. */
-  logo_square_url: string | null
-  /** `#rrggbb` or null. */
-  color_primary: string | null
-  /** `#rrggbb` or null. */
-  color_secondary: string | null
-  slogan: string | null
-}
-
-export interface StoreIdentity {
-  /** The store's public id: what `<PlatformInit storeId>` mounts. */
-  id: string
-  /** The store's display name. */
-  name: string
-  /** The store's slug; its address is `{slug}.cartbase.net` until a custom domain. */
-  slug: string
-  brand: StoreBrand
-}
-
-/** GET /api/store/store — anon. */
-export function getStore(client: StorefrontClient): Promise<{ store: StoreIdentity }> {
-  return client.request<{ store: StoreIdentity }>("/api/store/store")
-}
+/**
+ * @cartbase/storefront/api/store — the store's identity.
+ *
+ * Name, slug and brand (the merchant's Settings → Brand): what a
+ * storefront needs to title, head and foot itself without hardcoding a
+ * name. One anonymous read at layout level. Docs: docs/storefront/store.md.
+ */
+import type { StorefrontClient } from "./http"
+
+export interface StoreBrand {
+  /** Primary logo, public URL, or null. */
+  logo_url: string | null
+  /** Square mark, public URL, or null. */
+  logo_square_url: string | null
+  /** `#rrggbb` or null. */
+  color_primary: string | null
+  /** `#rrggbb` or null. */
+  color_secondary: string | null
+  slogan: string | null
+}
+
+export interface StoreIdentity {
+  /** The store's public id: what `<PlatformInit storeId>` mounts. */
+  id: string
+  /** The store's display name. */
+  name: string
+  /** The store's slug; its address is `{slug}.cartbase.net` until a custom domain. */
+  slug: string
+  brand: StoreBrand
+}
+
+/** GET /api/store/store — anon. */
+export function getStore(client: StorefrontClient): Promise<{ store: StoreIdentity }> {
+  return client.request<{ store: StoreIdentity }>("/api/store/store")
+}

package/src/api/types.ts

@@ -1,91 +1,91 @@
-/**
- * @cartbase/storefront — shared API surface types.
- *
- * The envelope + error contract every domain module builds on. Shapes are
- * the documented store-API contract (docs/contracts/store-api.md and the
- * per-domain teaching docs under docs/storefront/): single entities come
- * back as `{ <resource>: {...} }`, lists as `{ <resources>: [...], count,
- * offset, limit }`, and errors as `{ error, code, details? }`.
- *
- * Domain modules own their DTOs; only cross-domain primitives live here.
- */
-
-/** List envelope every collection endpoint returns. */
-export interface ListEnvelope {
-  count: number
-  offset: number
-  limit: number
-}
-
-/** The wire error body (`{ error, code, details? }`). */
-export interface StoreApiErrorBody {
-  error?: string
-  message?: string
-  code?: string
-  details?: unknown
-}
-
-/**
- * Thrown for every non-2xx response. `status` + `code` are the stable
- * programmatic surface (codes are contract-listed per endpoint, e.g.
- * `invalid_gift_card`, `checkout_method_hidden`, `rate_limited`);
- * `body` keeps the raw payload for anything else.
- */
-export class StoreApiError extends Error {
-  readonly status: number
-  readonly code: string | null
-  readonly body: unknown
-
-  constructor(status: number, body: unknown) {
-    const parsed = (body ?? {}) as StoreApiErrorBody
-    super(parsed.error ?? parsed.message ?? `Store API error (${status})`)
-    this.name = "StoreApiError"
-    this.status = status
-    this.code = typeof parsed.code === "string" ? parsed.code : null
-    this.body = body
-  }
-}
-
-/** ISO-8601 timestamp string (the wire format for every date field). */
-export type IsoDateString = string
-
-/**
- * Money amounts are decimal major units (EUR 45.5, not cents) everywhere in
- * the store API. Conversion to minor units happens only at provider
- * boundaries server-side — the SDK never does money math (server truth).
- */
-export type MajorUnitAmount = number
-
-/** `variant.calculated_price` (b2b-v1 pricing context, store-api.md). */
-export interface CalculatedPrice {
-  calculated_amount: MajorUnitAmount
-  original_amount: MajorUnitAmount
-  currency_code: string
-  is_calculated_price_price_list: boolean
-  price_list_id: string | null
-  price_list_type: "sale" | "override" | null
-}
-
-/** Raw base price row on variants (`product.prices[]` shape detail). */
-export interface PriceRow {
-  amount: MajorUnitAmount
-  currency_code: string
-  min_quantity?: number | null
-  max_quantity?: number | null
-}
-
-/**
- * Pricing context accepted by every price-decorated listing (products,
- * collections products, search, related). Server composes the rest
- * (customer groups from the Bearer JWT, never from params).
- */
-export interface PricingContextQuery {
-  currency_code?: string
-  region_id?: string
-}
-
-/** Standard pagination query accepted by list endpoints. */
-export interface PaginationQuery {
-  limit?: number
-  offset?: number
-}
+/**
+ * @cartbase/storefront — shared API surface types.
+ *
+ * The envelope + error contract every domain module builds on. Shapes are
+ * the documented store-API contract (docs/contracts/store-api.md and the
+ * per-domain teaching docs under docs/storefront/): single entities come
+ * back as `{ <resource>: {...} }`, lists as `{ <resources>: [...], count,
+ * offset, limit }`, and errors as `{ error, code, details? }`.
+ *
+ * Domain modules own their DTOs; only cross-domain primitives live here.
+ */
+
+/** List envelope every collection endpoint returns. */
+export interface ListEnvelope {
+  count: number
+  offset: number
+  limit: number
+}
+
+/** The wire error body (`{ error, code, details? }`). */
+export interface StoreApiErrorBody {
+  error?: string
+  message?: string
+  code?: string
+  details?: unknown
+}
+
+/**
+ * Thrown for every non-2xx response. `status` + `code` are the stable
+ * programmatic surface (codes are contract-listed per endpoint, e.g.
+ * `invalid_gift_card`, `checkout_method_hidden`, `rate_limited`);
+ * `body` keeps the raw payload for anything else.
+ */
+export class StoreApiError extends Error {
+  readonly status: number
+  readonly code: string | null
+  readonly body: unknown
+
+  constructor(status: number, body: unknown) {
+    const parsed = (body ?? {}) as StoreApiErrorBody
+    super(parsed.error ?? parsed.message ?? `Store API error (${status})`)
+    this.name = "StoreApiError"
+    this.status = status
+    this.code = typeof parsed.code === "string" ? parsed.code : null
+    this.body = body
+  }
+}
+
+/** ISO-8601 timestamp string (the wire format for every date field). */
+export type IsoDateString = string
+
+/**
+ * Money amounts are decimal major units (EUR 45.5, not cents) everywhere in
+ * the store API. Conversion to minor units happens only at provider
+ * boundaries server-side — the SDK never does money math (server truth).
+ */
+export type MajorUnitAmount = number
+
+/** `variant.calculated_price` (b2b-v1 pricing context, store-api.md). */
+export interface CalculatedPrice {
+  calculated_amount: MajorUnitAmount
+  original_amount: MajorUnitAmount
+  currency_code: string
+  is_calculated_price_price_list: boolean
+  price_list_id: string | null
+  price_list_type: "sale" | "override" | null
+}
+
+/** Raw base price row on variants (`product.prices[]` shape detail). */
+export interface PriceRow {
+  amount: MajorUnitAmount
+  currency_code: string
+  min_quantity?: number | null
+  max_quantity?: number | null
+}
+
+/**
+ * Pricing context accepted by every price-decorated listing (products,
+ * collections products, search, related). Server composes the rest
+ * (customer groups from the Bearer JWT, never from params).
+ */
+export interface PricingContextQuery {
+  currency_code?: string
+  region_id?: string
+}
+
+/** Standard pagination query accepted by list endpoints. */
+export interface PaginationQuery {
+  limit?: number
+  offset?: number
+}