@cartbase/storefront 0.20.0 → 0.21.0

package/src/api/collections.ts

@@ -1,130 +1,130 @@
-/**
- * @cartbase/storefront/api/collections — collections + membership listings.
- *
- * Collections are the merchant's curated product groupings
- * (collections-upgrade card): manual or smart (`conditions`/`match`), with a
- * per-collection `default_sort` the membership listing honors and an
- * optional per-request `order` override. Docs:
- * docs/storefront/collections.md.
- */
-import type { StorefrontClient } from "./http"
-import type { IsoDateString, ListEnvelope, PaginationQuery, PricingContextQuery } from "./types"
-import type { StoreProduct } from "./products"
-
-/** Sort modes accepted by `default_sort` and the `order` override. */
-export type CollectionSortMode =
-  | "manual"
-  | "title_asc"
-  | "title_desc"
-  | "price_asc"
-  | "price_desc"
-  | "newest"
-  | "oldest"
-  | "best_selling"
-
-export interface StoreCollection {
-  id: string
-  title: string
-  handle: string
-  /** "manual" | "smart" (smart membership is computed from `conditions`). */
-  type: string
-  description: string | null
-  image_url: string | null
-  /** The sort the membership listing uses when no `order` override is sent. */
-  default_sort: string
-  /** Smart-collection condition rows (admin-authored; opaque to render). */
-  conditions: unknown
-  /** Smart matching: "all" | "any". */
-  match: string
-  /** SEO override; null = fall back to `title`. */
-  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
-}
-
-export interface ListCollectionsQuery extends PaginationQuery {
-  /** Case-insensitive substring match on title. */
-  q?: string
-  handle?: string
-  /**
-   * Channel scope: a collection with channel links is visible ONLY on those
-   * channels (excluded from other channels' lists); a collection with no
-   * links is visible everywhere.
-   */
-  sales_channel_id?: string
-}
-
-export interface CollectionListResponse extends ListEnvelope {
-  collections: StoreCollection[]
-}
-
-export interface CollectionResponse {
-  collection: StoreCollection
-}
-
-export interface ListCollectionProductsQuery extends PricingContextQuery, PaginationQuery {
-  /** Sort override — any CollectionSortMode; unknown values are ignored. */
-  order?: CollectionSortMode | string
-  /** Channel scope: a collection scoped to OTHER channels 404s here. */
-  sales_channel_id?: string
-}
-
-export interface CollectionProductsResponse extends ListEnvelope {
-  products: StoreProduct[]
-}
-
-/**
- * List collections, ordered by title.
- *
- * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
- * 400 `validation_failed`. Settings: collection channel links
- * (`sales_channel_id` scope), smart-collection conditions.
- */
-export async function listCollections(
-  client: StorefrontClient,
-  query?: ListCollectionsQuery
-): Promise<CollectionListResponse> {
-  return client.get("/api/store/collections", { query: { ...query } })
-}
-
-/**
- * Retrieve one collection by id. (Look up by handle via
- * `listCollections({ handle })`.)
- *
- * Auth: anon (`x-client-id`). Errors: 404 `not_found`. NOTE: the single read
- * takes no `sales_channel_id` — channel scope applies to the list and to the
- * membership listing, not here.
- */
-export async function retrieveCollection(
-  client: StorefrontClient,
-  collectionId: string
-): Promise<CollectionResponse> {
-  return client.get(`/api/store/collections/${encodeURIComponent(collectionId)}`)
-}
-
-/**
- * List a collection's products — the MEMBERSHIP join (multi-collection
- * products appear in every collection they belong to), published products
- * only, ordered by the collection's `default_sort` unless `order` overrides
- * (manual position, title, EUR price asc/desc, newest/oldest, best_selling
- * 90-day aggregate). Products carry the full `StoreProduct` shape incl.
- * `calculated_price` when a pricing context is given.
- *
- * Auth: anon (`x-client-id`); optional Bearer JWT for group-aware pricing.
- * Errors: 404 `not_found` (unknown collection, or scoped away from
- * `sales_channel_id`), 400 `validation_failed`, 400 `invalid_region`.
- * `limit` 1–100 (default 50). Settings: collection default_sort + manual
- * order, channel links, price lists.
- */
-export async function listCollectionProducts(
-  client: StorefrontClient,
-  collectionId: string,
-  query?: ListCollectionProductsQuery
-): Promise<CollectionProductsResponse> {
-  return client.get(`/api/store/collections/${encodeURIComponent(collectionId)}/products`, {
-    query: { ...query },
-  })
-}
+/**
+ * @cartbase/storefront/api/collections — collections + membership listings.
+ *
+ * Collections are the merchant's curated product groupings
+ * (collections-upgrade card): manual or smart (`conditions`/`match`), with a
+ * per-collection `default_sort` the membership listing honors and an
+ * optional per-request `order` override. Docs:
+ * docs/storefront/collections.md.
+ */
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, ListEnvelope, PaginationQuery, PricingContextQuery } from "./types"
+import type { StoreProduct } from "./products"
+
+/** Sort modes accepted by `default_sort` and the `order` override. */
+export type CollectionSortMode =
+  | "manual"
+  | "title_asc"
+  | "title_desc"
+  | "price_asc"
+  | "price_desc"
+  | "newest"
+  | "oldest"
+  | "best_selling"
+
+export interface StoreCollection {
+  id: string
+  title: string
+  handle: string
+  /** "manual" | "smart" (smart membership is computed from `conditions`). */
+  type: string
+  description: string | null
+  image_url: string | null
+  /** The sort the membership listing uses when no `order` override is sent. */
+  default_sort: string
+  /** Smart-collection condition rows (admin-authored; opaque to render). */
+  conditions: unknown
+  /** Smart matching: "all" | "any". */
+  match: string
+  /** SEO override; null = fall back to `title`. */
+  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
+}
+
+export interface ListCollectionsQuery extends PaginationQuery {
+  /** Case-insensitive substring match on title. */
+  q?: string
+  handle?: string
+  /**
+   * Channel scope: a collection with channel links is visible ONLY on those
+   * channels (excluded from other channels' lists); a collection with no
+   * links is visible everywhere.
+   */
+  sales_channel_id?: string
+}
+
+export interface CollectionListResponse extends ListEnvelope {
+  collections: StoreCollection[]
+}
+
+export interface CollectionResponse {
+  collection: StoreCollection
+}
+
+export interface ListCollectionProductsQuery extends PricingContextQuery, PaginationQuery {
+  /** Sort override — any CollectionSortMode; unknown values are ignored. */
+  order?: CollectionSortMode | string
+  /** Channel scope: a collection scoped to OTHER channels 404s here. */
+  sales_channel_id?: string
+}
+
+export interface CollectionProductsResponse extends ListEnvelope {
+  products: StoreProduct[]
+}
+
+/**
+ * List collections, ordered by title.
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`. Settings: collection channel links
+ * (`sales_channel_id` scope), smart-collection conditions.
+ */
+export async function listCollections(
+  client: StorefrontClient,
+  query?: ListCollectionsQuery
+): Promise<CollectionListResponse> {
+  return client.get("/api/store/collections", { query: { ...query } })
+}
+
+/**
+ * Retrieve one collection by id. (Look up by handle via
+ * `listCollections({ handle })`.)
+ *
+ * Auth: anon (`x-client-id`). Errors: 404 `not_found`. NOTE: the single read
+ * takes no `sales_channel_id` — channel scope applies to the list and to the
+ * membership listing, not here.
+ */
+export async function retrieveCollection(
+  client: StorefrontClient,
+  collectionId: string
+): Promise<CollectionResponse> {
+  return client.get(`/api/store/collections/${encodeURIComponent(collectionId)}`)
+}
+
+/**
+ * List a collection's products — the MEMBERSHIP join (multi-collection
+ * products appear in every collection they belong to), published products
+ * only, ordered by the collection's `default_sort` unless `order` overrides
+ * (manual position, title, EUR price asc/desc, newest/oldest, best_selling
+ * 90-day aggregate). Products carry the full `StoreProduct` shape incl.
+ * `calculated_price` when a pricing context is given.
+ *
+ * Auth: anon (`x-client-id`); optional Bearer JWT for group-aware pricing.
+ * Errors: 404 `not_found` (unknown collection, or scoped away from
+ * `sales_channel_id`), 400 `validation_failed`, 400 `invalid_region`.
+ * `limit` 1–100 (default 50). Settings: collection default_sort + manual
+ * order, channel links, price lists.
+ */
+export async function listCollectionProducts(
+  client: StorefrontClient,
+  collectionId: string,
+  query?: ListCollectionProductsQuery
+): Promise<CollectionProductsResponse> {
+  return client.get(`/api/store/collections/${encodeURIComponent(collectionId)}/products`, {
+    query: { ...query },
+  })
+}

package/src/api/consent.ts

@@ -1,75 +1,75 @@
-/**
- * @cartbase/storefront/api/consent — the store's CMP configuration for the
- * built-in Consent Mode v2 banner (consent-management card).
- *
- * Ground truth: src/app/api/store/consent/route.ts +
- * src/lib/consent/model.ts (publicConsentPayload — exact allowlist).
- *
- * WIRING TRAP (the one that matters): the synchronous Consent Mode v2
- * DEFAULT (`<ConsentInit>`, first child of <body>) must NEVER wait on this
- * fetch — resolve the config server-side (RSC) and inline it. Render the
- * built-in banner only when `enabled && mode === "builtin"`. In `external`
- * mode the merchant's CMP owns the UI and must write the same `_1c_consent`
- * cookie (or call `setConsent()`) — all Cartbase-side tag gating works off
- * that one seam. Choices persist 12 months.
- */
-
-import type { StorefrontClient } from "./http"
-
-/** Per-locale banner copy — every field present (defaults merged server-side). */
-export interface ConsentCopy {
-  // Layer 1
-  title: string
-  body: string
-  privacy_link_label: string
-  accept_label: string
-  settings_label: string
-  reject_label: string
-  // Layer 2 (preferences)
-  settings_title: string
-  accept_all_label: string
-  save_label: string
-  reject_all_label: string
-  necessary_label: string
-  necessary_description: string
-  analytics_label: string
-  analytics_description: string
-  ads_label: string
-  ads_description: string
-}
-
-/**
- * The EXACT public payload — an allowlist; nothing else will ever appear.
- * Defaults are ALWAYS applied server-side, so this is complete and
- * renderable even for an unconfigured store (BG + EN copy shipped).
- */
-export interface ConsentConfig {
-  enabled: boolean
-  /** `builtin` = Cartbase renders the banner; `external` = merchant CMP owns UI. */
-  mode: "builtin" | "external"
-  /** `modal` = blocking centered modal; `banner-bottom` = non-blocking bar. */
-  layout: "modal" | "banner-bottom"
-  /** Storefront-relative privacy/cookies page link. */
-  privacy_href: string
-  /** Show a reject-all button on the first layer. */
-  reject_on_first_layer: boolean
-  /** Keyed by locale code (at least `bg` + `en`). */
-  copy: Record<string, ConsentCopy>
-}
-
-export interface ConsentResponse {
-  consent: ConsentConfig
-}
-
-/**
- * GET /api/store/consent — the complete, renderable consent configuration.
- *
- * Auth: anon (x-client-id).
- * Errors: 400 missing_client_id only — the payload always succeeds
- * (corrupt/missing config degrades to defaults, never to a broken banner).
- * Settings: admin → Settings → Consent (enabled/mode/layout/copy);
- * `integrations.tracking.consent_required` mirrors `enabled`.
- */
-export async function getConsent(client: StorefrontClient): Promise<ConsentResponse> {
-  return client.get("/api/store/consent")
-}
+/**
+ * @cartbase/storefront/api/consent — the store's CMP configuration for the
+ * built-in Consent Mode v2 banner (consent-management card).
+ *
+ * Ground truth: src/app/api/store/consent/route.ts +
+ * src/lib/consent/model.ts (publicConsentPayload — exact allowlist).
+ *
+ * WIRING TRAP (the one that matters): the synchronous Consent Mode v2
+ * DEFAULT (`<ConsentInit>`, first child of <body>) must NEVER wait on this
+ * fetch — resolve the config server-side (RSC) and inline it. Render the
+ * built-in banner only when `enabled && mode === "builtin"`. In `external`
+ * mode the merchant's CMP owns the UI and must write the same `_1c_consent`
+ * cookie (or call `setConsent()`) — all Cartbase-side tag gating works off
+ * that one seam. Choices persist 12 months.
+ */
+
+import type { StorefrontClient } from "./http"
+
+/** Per-locale banner copy — every field present (defaults merged server-side). */
+export interface ConsentCopy {
+  // Layer 1
+  title: string
+  body: string
+  privacy_link_label: string
+  accept_label: string
+  settings_label: string
+  reject_label: string
+  // Layer 2 (preferences)
+  settings_title: string
+  accept_all_label: string
+  save_label: string
+  reject_all_label: string
+  necessary_label: string
+  necessary_description: string
+  analytics_label: string
+  analytics_description: string
+  ads_label: string
+  ads_description: string
+}
+
+/**
+ * The EXACT public payload — an allowlist; nothing else will ever appear.
+ * Defaults are ALWAYS applied server-side, so this is complete and
+ * renderable even for an unconfigured store (BG + EN copy shipped).
+ */
+export interface ConsentConfig {
+  enabled: boolean
+  /** `builtin` = Cartbase renders the banner; `external` = merchant CMP owns UI. */
+  mode: "builtin" | "external"
+  /** `modal` = blocking centered modal; `banner-bottom` = non-blocking bar. */
+  layout: "modal" | "banner-bottom"
+  /** Storefront-relative privacy/cookies page link. */
+  privacy_href: string
+  /** Show a reject-all button on the first layer. */
+  reject_on_first_layer: boolean
+  /** Keyed by locale code (at least `bg` + `en`). */
+  copy: Record<string, ConsentCopy>
+}
+
+export interface ConsentResponse {
+  consent: ConsentConfig
+}
+
+/**
+ * GET /api/store/consent — the complete, renderable consent configuration.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 400 missing_client_id only — the payload always succeeds
+ * (corrupt/missing config degrades to defaults, never to a broken banner).
+ * Settings: admin → Settings → Consent (enabled/mode/layout/copy);
+ * `integrations.tracking.consent_required` mirrors `enabled`.
+ */
+export async function getConsent(client: StorefrontClient): Promise<ConsentResponse> {
+  return client.get("/api/store/consent")
+}

package/src/api/content.ts

@@ -1,125 +1,125 @@
-/**
- * @cartbase/storefront/api/content — pages + blogs (content-pages-blog card).
- *
- * Ground truth: src/app/api/store/pages/[handle]/route.ts,
- * src/app/api/store/blogs/[handle]/posts{,/[postHandle]}/route.ts,
- * src/lib/content/article-shape.ts.
- *
- * Shapes are Shopify Storefront `Page` / `Article` verbatim so storefront
- * code ports 1:1. PUBLISHED only — drafts and deleted rows 404 (lib filter
- * AND anon RLS). Stored HTML is server-sanitized on write — safe to render
- * raw (`dangerouslySetInnerHTML`).
- *
- * Path convention (src/lib/content/paths.ts, shared with menus/redirects):
- * `/pages/<handle>`, `/blogs/<handle>`, `/blogs/<blog>/<post>`.
- */
-
-import type { StorefrontClient } from "./http"
-import type { IsoDateString, PaginationQuery } from "./types"
-
-/** Shopify Storefront `Page`, verbatim. */
-export interface Page {
-  /** `cpage_<hex>` */
-  id: string
-  handle: string
-  title: string
-  /** Sanitized HTML — safe to render raw. */
-  body: string
-  /** Stripped text, ~160-char word-boundary truncation. */
-  bodySummary: string
-  /** Fallbacks applied server-side: title / bodySummary. */
-  seo: { title: string; description: string }
-  publishedAt: IsoDateString
-  createdAt: IsoDateString
-  updatedAt: IsoDateString
-}
-
-export interface PageResponse {
-  page: Page
-}
-
-/**
- * GET /api/store/pages/:handle — one published page.
- *
- * Auth: anon (x-client-id).
- * Errors: 404 not_found (unknown handle, draft, or deleted).
- * Settings: policy pages (privacy-policy, terms-of-service, refund-policy,
- * shipping-policy) are seeded as DRAFTS — they 404 until published.
- */
-export async function getPage(
-  client: StorefrontClient,
-  handle: string
-): Promise<PageResponse> {
-  return client.get(`/api/store/pages/${encodeURIComponent(handle)}`)
-}
-
-/** Shopify Storefront `Article`, verbatim. */
-export interface Article {
-  /** `bpost_<hex>` */
-  id: string
-  handle: string
-  title: string
-  /** Sanitized HTML — safe to render raw. */
-  contentHtml: string
-  /** Plain-text version of contentHtml. */
-  content: string
-  /** Author-provided; falls back to truncated content. */
-  excerpt: string
-  /** null when the post has no hero image. altText is always null today. */
-  image: { url: string; altText: null } | null
-  tags: string[]
-  /** null when the post has no author name set. */
-  author: { name: string } | null
-  publishedAt: IsoDateString
-  /** Fallbacks applied server-side: title / excerpt. */
-  seo: { title: string; description: string }
-  blog: { handle: string; title: string }
-}
-
-export interface ArticleResponse {
-  article: Article
-}
-
-export type ListBlogPostsQuery = PaginationQuery
-
-export interface BlogPostListResponse {
-  blog: { handle: string; title: string }
-  articles: Article[]
-  count: number
-  offset: number
-  limit: number
-}
-
-/**
- * GET /api/store/blogs/:handle/posts — published posts of one blog,
- * `published_at` desc. `limit` ≤ 100 (default 20), `offset` ≥ 0.
- *
- * Auth: anon (x-client-id).
- * Errors: 404 not_found (unknown blog handle) · 400 validation_failed
- * (limit/offset out of range).
- */
-export async function listBlogPosts(
-  client: StorefrontClient,
-  blogHandle: string,
-  query?: ListBlogPostsQuery
-): Promise<BlogPostListResponse> {
-  return client.get(`/api/store/blogs/${encodeURIComponent(blogHandle)}/posts`, {
-    query: { ...query },
-  })
-}
-
-/**
- * GET /api/store/blogs/:handle/posts/:postHandle — one published article.
- *
- * Auth: anon (x-client-id).
- * Errors: 404 not_found (unknown blog OR unknown/draft post).
- */
-export async function getBlogPost(
-  client: StorefrontClient,
-  blogHandle: string,
-  postHandle: string
-): Promise<ArticleResponse> {
-  return client.get(
-    `/api/store/blogs/${encodeURIComponent(blogHandle)}/posts/${encodeURIComponent(postHandle)}`
-  )
-}
+/**
+ * @cartbase/storefront/api/content — pages + blogs (content-pages-blog card).
+ *
+ * Ground truth: src/app/api/store/pages/[handle]/route.ts,
+ * src/app/api/store/blogs/[handle]/posts{,/[postHandle]}/route.ts,
+ * src/lib/content/article-shape.ts.
+ *
+ * Shapes are Shopify Storefront `Page` / `Article` verbatim so storefront
+ * code ports 1:1. PUBLISHED only — drafts and deleted rows 404 (lib filter
+ * AND anon RLS). Stored HTML is server-sanitized on write — safe to render
+ * raw (`dangerouslySetInnerHTML`).
+ *
+ * Path convention (src/lib/content/paths.ts, shared with menus/redirects):
+ * `/pages/<handle>`, `/blogs/<handle>`, `/blogs/<blog>/<post>`.
+ */
+
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, PaginationQuery } from "./types"
+
+/** Shopify Storefront `Page`, verbatim. */
+export interface Page {
+  /** `cpage_<hex>` */
+  id: string
+  handle: string
+  title: string
+  /** Sanitized HTML — safe to render raw. */
+  body: string
+  /** Stripped text, ~160-char word-boundary truncation. */
+  bodySummary: string
+  /** Fallbacks applied server-side: title / bodySummary. */
+  seo: { title: string; description: string }
+  publishedAt: IsoDateString
+  createdAt: IsoDateString
+  updatedAt: IsoDateString
+}
+
+export interface PageResponse {
+  page: Page
+}
+
+/**
+ * GET /api/store/pages/:handle — one published page.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 404 not_found (unknown handle, draft, or deleted).
+ * Settings: policy pages (privacy-policy, terms-of-service, refund-policy,
+ * shipping-policy) are seeded as DRAFTS — they 404 until published.
+ */
+export async function getPage(
+  client: StorefrontClient,
+  handle: string
+): Promise<PageResponse> {
+  return client.get(`/api/store/pages/${encodeURIComponent(handle)}`)
+}
+
+/** Shopify Storefront `Article`, verbatim. */
+export interface Article {
+  /** `bpost_<hex>` */
+  id: string
+  handle: string
+  title: string
+  /** Sanitized HTML — safe to render raw. */
+  contentHtml: string
+  /** Plain-text version of contentHtml. */
+  content: string
+  /** Author-provided; falls back to truncated content. */
+  excerpt: string
+  /** null when the post has no hero image. altText is always null today. */
+  image: { url: string; altText: null } | null
+  tags: string[]
+  /** null when the post has no author name set. */
+  author: { name: string } | null
+  publishedAt: IsoDateString
+  /** Fallbacks applied server-side: title / excerpt. */
+  seo: { title: string; description: string }
+  blog: { handle: string; title: string }
+}
+
+export interface ArticleResponse {
+  article: Article
+}
+
+export type ListBlogPostsQuery = PaginationQuery
+
+export interface BlogPostListResponse {
+  blog: { handle: string; title: string }
+  articles: Article[]
+  count: number
+  offset: number
+  limit: number
+}
+
+/**
+ * GET /api/store/blogs/:handle/posts — published posts of one blog,
+ * `published_at` desc. `limit` ≤ 100 (default 20), `offset` ≥ 0.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 404 not_found (unknown blog handle) · 400 validation_failed
+ * (limit/offset out of range).
+ */
+export async function listBlogPosts(
+  client: StorefrontClient,
+  blogHandle: string,
+  query?: ListBlogPostsQuery
+): Promise<BlogPostListResponse> {
+  return client.get(`/api/store/blogs/${encodeURIComponent(blogHandle)}/posts`, {
+    query: { ...query },
+  })
+}
+
+/**
+ * GET /api/store/blogs/:handle/posts/:postHandle — one published article.
+ *
+ * Auth: anon (x-client-id).
+ * Errors: 404 not_found (unknown blog OR unknown/draft post).
+ */
+export async function getBlogPost(
+  client: StorefrontClient,
+  blogHandle: string,
+  postHandle: string
+): Promise<ArticleResponse> {
+  return client.get(
+    `/api/store/blogs/${encodeURIComponent(blogHandle)}/posts/${encodeURIComponent(postHandle)}`
+  )
+}