@cartbase/storefront 0.20.0 → 0.21.0

package/src/api/gift-cards.ts

@@ -1,112 +1,112 @@
-/**
- * @cartbase/storefront/api/gift-cards — gift-card TENDER on carts.
- *
- * Redemption is a payment tender (`pp_giftcard`), never a discount: cart
- * totals/VAT compute first and NEVER move; applied cards cover part (or all)
- * of `cart.total` and the remainder provider (Stripe/COD/manual) charges
- * only what is left. The cart decoration fields (`gift_cards[]`,
- * `gift_card_total`, `gift_card_remainder` — declared on the `Cart` DTO in
- * `./carts`) are derived from the LIVE transactions ledger at every read.
- *
- * Route ground truth: src/app/api/store/carts/[id]/gift-cards/route.ts +
- * src/lib/gift-cards/{redeem,tender}.ts. Doc: docs/storefront/gift-cards.md.
- *
- * Security model baked into the contract:
- *  - failure is ONE generic answer — unknown, disabled, expired, depleted
- *    and foreign-tenant codes are all `400 invalid_gift_card` (no
- *    code-existence oracle);
- *  - attempts are recorded BEFORE lookup and rate-limited per cart
- *    (10 / 15 min) AND per IP (30 / 15 min) → `429 rate_limited`;
- *  - the confirmation is MASKED (`last4` only) — the code is never echoed.
- */
-import type { StorefrontClient } from "./http"
-import type { MajorUnitAmount } from "./types"
-import type { Cart } from "./carts"
-
-// ---------------------------------------------------------------------------
-// DTOs
-// ---------------------------------------------------------------------------
-
-/** Body of POST /api/store/carts/:id/gift-cards (`.strict()`). */
-export interface ApplyGiftCardInput {
-  /** The plaintext code (4–64 chars). Hashed at rest server-side. */
-  code: string
-}
-
-/** Body of DELETE /api/store/carts/:id/gift-cards (`.strict()`). */
-export interface RemoveGiftCardInput {
-  /** The applied card's id (from `cart.gift_cards[].id` or the apply response). */
-  gift_card_id: string
-}
-
-/** Masked apply confirmation. */
-export interface AppliedGiftCardConfirmation {
-  id: string
-  /** Last 4 characters of the code — the full code is never echoed. */
-  last4: string
-  /**
-   * How much of the cart total THIS card covers right now
-   * (`min(live balance, remaining total)` in apply order).
-   */
-  amount_applied: MajorUnitAmount
-}
-
-export interface ApplyGiftCardResponse {
-  /** Decorated cart — `gift_cards[]` / `gift_card_total` / `gift_card_remainder` updated; `total` untouched. */
-  cart: Cart
-  gift_card: AppliedGiftCardConfirmation
-}
-
-export interface RemoveGiftCardResponse {
-  cart: Cart
-}
-
-// ---------------------------------------------------------------------------
-// Functions
-// ---------------------------------------------------------------------------
-
-/**
- * Apply a gift-card code to an open cart (idempotent re-apply). → 200
- * `{cart, gift_card}` with a MASKED confirmation.
- *
- * Auth: anon `x-client-id`.
- * Errors: 400 `invalid_gift_card` (the deliberate generic answer for
- * unknown/disabled/expired/depleted/foreign-tenant codes), 429
- * `rate_limited` (per-cart and per-IP attempt windows — a valid code inside
- * a burned window is refused the same way), 404 `cart_not_found`, 409
- * `cart_completed`, 400 `validation_failed`.
- *
- * Behavior: also syncs the internal `pp_giftcard` payment session to the
- * covered amount when a payment collection exists (no-op before one does —
- * creating the collection composes it). Actual balance redemption happens
- * ONLY at cart complete, atomically; a card drained elsewhere in the
- * meantime shrinks this cart's tender at the next read instead of
- * over-redeeming.
- * Settings: gift cards are issued/disabled from the admin; expiry and
- * balance live on the card's ledger.
- */
-export async function applyGiftCard(
-  client: StorefrontClient,
-  cartId: string,
-  input: ApplyGiftCardInput
-): Promise<ApplyGiftCardResponse> {
-  return client.post(`/api/store/carts/${cartId}/gift-cards`, input)
-}
-
-/**
- * Remove an applied gift card from an open cart (idempotent). → 200 `{cart}`.
- *
- * Auth: anon `x-client-id`.
- * Errors: 404 `cart_not_found`, 409 `cart_completed`, 400
- * `validation_failed`.
- * Behavior: re-syncs the `pp_giftcard` session to the remaining tender
- * (removing the last card zeroes it), so the remainder provider's session
- * re-inflates to the full total on the next amount sync.
- */
-export async function removeGiftCard(
-  client: StorefrontClient,
-  cartId: string,
-  input: RemoveGiftCardInput
-): Promise<RemoveGiftCardResponse> {
-  return client.delete(`/api/store/carts/${cartId}/gift-cards`, input)
-}
+/**
+ * @cartbase/storefront/api/gift-cards — gift-card TENDER on carts.
+ *
+ * Redemption is a payment tender (`pp_giftcard`), never a discount: cart
+ * totals/VAT compute first and NEVER move; applied cards cover part (or all)
+ * of `cart.total` and the remainder provider (Stripe/COD/manual) charges
+ * only what is left. The cart decoration fields (`gift_cards[]`,
+ * `gift_card_total`, `gift_card_remainder` — declared on the `Cart` DTO in
+ * `./carts`) are derived from the LIVE transactions ledger at every read.
+ *
+ * Route ground truth: src/app/api/store/carts/[id]/gift-cards/route.ts +
+ * src/lib/gift-cards/{redeem,tender}.ts. Doc: docs/storefront/gift-cards.md.
+ *
+ * Security model baked into the contract:
+ *  - failure is ONE generic answer — unknown, disabled, expired, depleted
+ *    and foreign-tenant codes are all `400 invalid_gift_card` (no
+ *    code-existence oracle);
+ *  - attempts are recorded BEFORE lookup and rate-limited per cart
+ *    (10 / 15 min) AND per IP (30 / 15 min) → `429 rate_limited`;
+ *  - the confirmation is MASKED (`last4` only) — the code is never echoed.
+ */
+import type { StorefrontClient } from "./http"
+import type { MajorUnitAmount } from "./types"
+import type { Cart } from "./carts"
+
+// ---------------------------------------------------------------------------
+// DTOs
+// ---------------------------------------------------------------------------
+
+/** Body of POST /api/store/carts/:id/gift-cards (`.strict()`). */
+export interface ApplyGiftCardInput {
+  /** The plaintext code (4–64 chars). Hashed at rest server-side. */
+  code: string
+}
+
+/** Body of DELETE /api/store/carts/:id/gift-cards (`.strict()`). */
+export interface RemoveGiftCardInput {
+  /** The applied card's id (from `cart.gift_cards[].id` or the apply response). */
+  gift_card_id: string
+}
+
+/** Masked apply confirmation. */
+export interface AppliedGiftCardConfirmation {
+  id: string
+  /** Last 4 characters of the code — the full code is never echoed. */
+  last4: string
+  /**
+   * How much of the cart total THIS card covers right now
+   * (`min(live balance, remaining total)` in apply order).
+   */
+  amount_applied: MajorUnitAmount
+}
+
+export interface ApplyGiftCardResponse {
+  /** Decorated cart — `gift_cards[]` / `gift_card_total` / `gift_card_remainder` updated; `total` untouched. */
+  cart: Cart
+  gift_card: AppliedGiftCardConfirmation
+}
+
+export interface RemoveGiftCardResponse {
+  cart: Cart
+}
+
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply a gift-card code to an open cart (idempotent re-apply). → 200
+ * `{cart, gift_card}` with a MASKED confirmation.
+ *
+ * Auth: anon `x-client-id`.
+ * Errors: 400 `invalid_gift_card` (the deliberate generic answer for
+ * unknown/disabled/expired/depleted/foreign-tenant codes), 429
+ * `rate_limited` (per-cart and per-IP attempt windows — a valid code inside
+ * a burned window is refused the same way), 404 `cart_not_found`, 409
+ * `cart_completed`, 400 `validation_failed`.
+ *
+ * Behavior: also syncs the internal `pp_giftcard` payment session to the
+ * covered amount when a payment collection exists (no-op before one does —
+ * creating the collection composes it). Actual balance redemption happens
+ * ONLY at cart complete, atomically; a card drained elsewhere in the
+ * meantime shrinks this cart's tender at the next read instead of
+ * over-redeeming.
+ * Settings: gift cards are issued/disabled from the admin; expiry and
+ * balance live on the card's ledger.
+ */
+export async function applyGiftCard(
+  client: StorefrontClient,
+  cartId: string,
+  input: ApplyGiftCardInput
+): Promise<ApplyGiftCardResponse> {
+  return client.post(`/api/store/carts/${cartId}/gift-cards`, input)
+}
+
+/**
+ * Remove an applied gift card from an open cart (idempotent). → 200 `{cart}`.
+ *
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found`, 409 `cart_completed`, 400
+ * `validation_failed`.
+ * Behavior: re-syncs the `pp_giftcard` session to the remaining tender
+ * (removing the last card zeroes it), so the remainder provider's session
+ * re-inflates to the full total on the next amount sync.
+ */
+export async function removeGiftCard(
+  client: StorefrontClient,
+  cartId: string,
+  input: RemoveGiftCardInput
+): Promise<RemoveGiftCardResponse> {
+  return client.delete(`/api/store/carts/${cartId}/gift-cards`, input)
+}

package/src/api/http.ts

@@ -1,180 +1,181 @@
-/**
- * @cartbase/storefront — the ONE http seam.
- *
- * Every SDK function in this package is a thin typed wrapper over
- * `storeFetch()` from a `StorefrontClient`. Auth model (store-api.md):
- *
- *  - `x-publishable-api-key` — THE store's key: names the store on its own
- *                              (one key, 2026-09-07) and scopes catalog and
- *                              carts to the key's sales channels
- *  - `x-client-id`      — the platform's own door (hosted builds carry it);
- *                          optional, wins over the key when both are sent
- *  - `authorization: Bearer <jwt>` — customer session (passwordless code
- *                              flow or supabase password login)
- *  - `x-locale`         — optional storefront locale hint
- *
- * The client is isomorphic (browser + RSC/server actions) — it holds no
- * global state; construct once per request scope on the server, once per
- * app on the client.
- */
-
-import { StoreApiError } from "./types"
-
-export interface StorefrontClientConfig {
-  /** Deployment origin, e.g. `https://admin.cartbase.ai` */
-  baseUrl: string
-  /**
-   * The store's publishable key: names the store and scopes the catalog to
-   * the key's sales channels. The one input a merchant hands out; at least
-   * one of `publishableKey` and `clientId` is required.
-   */
-  publishableKey?: string
-  /** Tenant id — the platform's own door. Optional when a key is given. */
-  clientId?: string
-  /** Called per request; return the customer JWT or null for guests. */
-  getAuthToken?: () => string | null | Promise<string | null>
-  /** Called per request; return the active locale code or null. */
-  getLocale?: () => string | null | Promise<string | null>
-  /** Override fetch (tests, custom caching). Defaults to global fetch. */
-  fetch?: typeof fetch
-}
-
-export type QueryValue = string | number | boolean | null | undefined
-export type Query = Record<string, QueryValue | QueryValue[]>
-
-/**
- * The reads the platform's CDN holds for anonymous shoppers (store-api.md
- * § Caching). Such a request carries the store's publishable key in its
- * address as `pk`, so the edge can tell one store's answers from another's,
- * and the shopper's locale as `locale`. A request with a customer token
- * carries neither: its prices are the shopper's own, and an address without
- * the key is never held and never served from the hold. Carts, checkout,
- * consent, customers and every write are never on this list.
- */
-const CACHEABLE_READ_PREFIXES = [
-  "/api/store/store",
-  "/api/store/menus",
-  "/api/store/regions",
-  "/api/store/collections",
-  "/api/store/products",
-  "/api/store/product-variants",
-  "/api/store/product-categories",
-  "/api/store/product-types",
-  "/api/store/product-tags",
-  "/api/store/reviews",
-  "/api/store/currencies",
-  "/api/store/countries",
-  "/api/store/locales",
-  "/api/store/pages",
-  "/api/store/blogs",
-  "/api/store/metaobjects",
-  "/api/store/url-redirects",
-  "/api/store/return-reasons",
-]
-
-export function isCacheableStoreRead(pathname: string): boolean {
-  return CACHEABLE_READ_PREFIXES.some(
-    (prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`)
-  )
-}
-
-export interface RequestOptions {
-  method?: "GET" | "POST" | "DELETE"
-  query?: Query
-  body?: unknown
-  headers?: Record<string, string>
-  /** Passed through to fetch — lets Next.js RSC callers tag cache behavior. */
-  cache?: RequestCache
-  next?: { revalidate?: number | false; tags?: string[] }
-  signal?: AbortSignal
-}
-
-export class StorefrontClient {
-  constructor(private readonly config: StorefrontClientConfig) {
-    if (!config.baseUrl) throw new Error("StorefrontClient: baseUrl is required")
-    if (!config.publishableKey && !config.clientId) {
-      throw new Error("StorefrontClient: publishableKey (or clientId) is required")
-    }
-  }
-
-  /** The low-level typed request. Domain modules call this — apps rarely should. */
-  async request<T>(path: string, opts: RequestOptions = {}): Promise<T> {
-    const url = new URL(
-      path.replace(/^\//, ""),
-      this.config.baseUrl.replace(/\/?$/, "/")
-    )
-    if (opts.query) {
-      for (const [key, value] of Object.entries(opts.query)) {
-        if (value === undefined || value === null) continue
-        if (Array.isArray(value)) {
-          const joined = value.filter((v) => v !== undefined && v !== null).join(",")
-          if (joined) url.searchParams.set(key, joined)
-        } else {
-          url.searchParams.set(key, String(value))
-        }
-      }
-    }
-
-    const headers: Record<string, string> = {
-      ...(this.config.clientId ? { "x-client-id": this.config.clientId } : {}),
-      ...(this.config.publishableKey
-        ? { "x-publishable-api-key": this.config.publishableKey }
-        : {}),
-      ...(opts.body !== undefined ? { "content-type": "application/json" } : {}),
-      ...(opts.headers ?? {}),
-    }
-    const token = this.config.getAuthToken ? await this.config.getAuthToken() : null
-    if (token && !headers.authorization) headers.authorization = `Bearer ${token}`
-    const locale = this.config.getLocale ? await this.config.getLocale() : null
-    if (locale && !headers["x-locale"]) headers["x-locale"] = locale
-
-    // An anonymous catalogue read carries its key (and locale) in the
-    // address, so the platform's CDN may hold the answer for this store.
-    const method = opts.method ?? "GET"
-    const anonymous = !headers.authorization
-    if (
-      method === "GET" &&
-      anonymous &&
-      this.config.publishableKey &&
-      isCacheableStoreRead(url.pathname)
-    ) {
-      url.searchParams.set("pk", this.config.publishableKey)
-      if (locale) url.searchParams.set("locale", locale)
-    }
-
-    const doFetch = this.config.fetch ?? fetch
-    const res = await doFetch(url.toString(), {
-      method,
-      headers,
-      body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-      cache: opts.cache,
-      ...(opts.next ? { next: opts.next } : {}),
-      signal: opts.signal,
-    } as RequestInit)
-
-    if (!res.ok) {
-      let detail: unknown
-      const text = await res.text()
-      try {
-        detail = JSON.parse(text)
-      } catch {
-        detail = text
-      }
-      throw new StoreApiError(res.status, detail)
-    }
-    if (res.status === 204) return undefined as T
-    return (await res.json()) as T
-  }
-
-  get<T>(path: string, opts: Omit<RequestOptions, "method" | "body"> = {}): Promise<T> {
-    return this.request<T>(path, { ...opts, method: "GET" })
-  }
-
-  post<T>(path: string, body?: unknown, opts: Omit<RequestOptions, "method" | "body"> = {}): Promise<T> {
-    return this.request<T>(path, { ...opts, method: "POST", body })
-  }
-
-  delete<T>(path: string, body?: unknown, opts: Omit<RequestOptions, "method" | "body"> = {}): Promise<T> {
-    return this.request<T>(path, { ...opts, method: "DELETE", body })
-  }
-}
+/**
+ * @cartbase/storefront — the ONE http seam.
+ *
+ * Every SDK function in this package is a thin typed wrapper over
+ * `storeFetch()` from a `StorefrontClient`. Auth model (store-api.md):
+ *
+ *  - `x-publishable-api-key` — THE store's key: names the store on its own
+ *                              (one key, 2026-09-07) and scopes catalog and
+ *                              carts to the key's sales channels
+ *  - `x-client-id`      — the platform's own door (hosted builds carry it);
+ *                          optional, wins over the key when both are sent
+ *  - `authorization: Bearer <jwt>` — customer session (passwordless code
+ *                              flow or supabase password login)
+ *  - `x-locale`         — optional storefront locale hint
+ *
+ * The client is isomorphic (browser + RSC/server actions) — it holds no
+ * global state; construct once per request scope on the server, once per
+ * app on the client.
+ */
+
+import { StoreApiError } from "./types"
+
+export interface StorefrontClientConfig {
+  /** Deployment origin, e.g. `https://admin.cartbase.ai` */
+  baseUrl: string
+  /**
+   * The store's publishable key: names the store and scopes the catalog to
+   * the key's sales channels. The one input a merchant hands out; at least
+   * one of `publishableKey` and `clientId` is required.
+   */
+  publishableKey?: string
+  /** Tenant id — the platform's own door. Optional when a key is given. */
+  clientId?: string
+  /** Called per request; return the customer JWT or null for guests. */
+  getAuthToken?: () => string | null | Promise<string | null>
+  /** Called per request; return the active locale code or null. */
+  getLocale?: () => string | null | Promise<string | null>
+  /** Override fetch (tests, custom caching). Defaults to global fetch. */
+  fetch?: typeof fetch
+}
+
+export type QueryValue = string | number | boolean | null | undefined
+export type Query = Record<string, QueryValue | QueryValue[]>
+
+/**
+ * The reads the platform's CDN holds for anonymous shoppers (store-api.md
+ * § Caching). Such a request carries the store's publishable key in its
+ * address as `pk`, so the edge can tell one store's answers from another's,
+ * and the shopper's locale as `locale`. A request with a customer token
+ * carries neither: its prices are the shopper's own, and an address without
+ * the key is never held and never served from the hold. Carts, checkout,
+ * consent, customers and every write are never on this list.
+ */
+const CACHEABLE_READ_PREFIXES = [
+  "/api/store/store",
+  "/api/store/menus",
+  "/api/store/regions",
+  "/api/store/collections",
+  "/api/store/products",
+  "/api/store/product-variants",
+  "/api/store/product-categories",
+  "/api/store/product-types",
+  "/api/store/product-tags",
+  "/api/store/reviews",
+  "/api/store/payment-marks",
+  "/api/store/currencies",
+  "/api/store/countries",
+  "/api/store/locales",
+  "/api/store/pages",
+  "/api/store/blogs",
+  "/api/store/metaobjects",
+  "/api/store/url-redirects",
+  "/api/store/return-reasons",
+]
+
+export function isCacheableStoreRead(pathname: string): boolean {
+  return CACHEABLE_READ_PREFIXES.some(
+    (prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`)
+  )
+}
+
+export interface RequestOptions {
+  method?: "GET" | "POST" | "DELETE"
+  query?: Query
+  body?: unknown
+  headers?: Record<string, string>
+  /** Passed through to fetch — lets Next.js RSC callers tag cache behavior. */
+  cache?: RequestCache
+  next?: { revalidate?: number | false; tags?: string[] }
+  signal?: AbortSignal
+}
+
+export class StorefrontClient {
+  constructor(private readonly config: StorefrontClientConfig) {
+    if (!config.baseUrl) throw new Error("StorefrontClient: baseUrl is required")
+    if (!config.publishableKey && !config.clientId) {
+      throw new Error("StorefrontClient: publishableKey (or clientId) is required")
+    }
+  }
+
+  /** The low-level typed request. Domain modules call this — apps rarely should. */
+  async request<T>(path: string, opts: RequestOptions = {}): Promise<T> {
+    const url = new URL(
+      path.replace(/^\//, ""),
+      this.config.baseUrl.replace(/\/?$/, "/")
+    )
+    if (opts.query) {
+      for (const [key, value] of Object.entries(opts.query)) {
+        if (value === undefined || value === null) continue
+        if (Array.isArray(value)) {
+          const joined = value.filter((v) => v !== undefined && v !== null).join(",")
+          if (joined) url.searchParams.set(key, joined)
+        } else {
+          url.searchParams.set(key, String(value))
+        }
+      }
+    }
+
+    const headers: Record<string, string> = {
+      ...(this.config.clientId ? { "x-client-id": this.config.clientId } : {}),
+      ...(this.config.publishableKey
+        ? { "x-publishable-api-key": this.config.publishableKey }
+        : {}),
+      ...(opts.body !== undefined ? { "content-type": "application/json" } : {}),
+      ...(opts.headers ?? {}),
+    }
+    const token = this.config.getAuthToken ? await this.config.getAuthToken() : null
+    if (token && !headers.authorization) headers.authorization = `Bearer ${token}`
+    const locale = this.config.getLocale ? await this.config.getLocale() : null
+    if (locale && !headers["x-locale"]) headers["x-locale"] = locale
+
+    // An anonymous catalogue read carries its key (and locale) in the
+    // address, so the platform's CDN may hold the answer for this store.
+    const method = opts.method ?? "GET"
+    const anonymous = !headers.authorization
+    if (
+      method === "GET" &&
+      anonymous &&
+      this.config.publishableKey &&
+      isCacheableStoreRead(url.pathname)
+    ) {
+      url.searchParams.set("pk", this.config.publishableKey)
+      if (locale) url.searchParams.set("locale", locale)
+    }
+
+    const doFetch = this.config.fetch ?? fetch
+    const res = await doFetch(url.toString(), {
+      method,
+      headers,
+      body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+      cache: opts.cache,
+      ...(opts.next ? { next: opts.next } : {}),
+      signal: opts.signal,
+    } as RequestInit)
+
+    if (!res.ok) {
+      let detail: unknown
+      const text = await res.text()
+      try {
+        detail = JSON.parse(text)
+      } catch {
+        detail = text
+      }
+      throw new StoreApiError(res.status, detail)
+    }
+    if (res.status === 204) return undefined as T
+    return (await res.json()) as T
+  }
+
+  get<T>(path: string, opts: Omit<RequestOptions, "method" | "body"> = {}): Promise<T> {
+    return this.request<T>(path, { ...opts, method: "GET" })
+  }
+
+  post<T>(path: string, body?: unknown, opts: Omit<RequestOptions, "method" | "body"> = {}): Promise<T> {
+    return this.request<T>(path, { ...opts, method: "POST", body })
+  }
+
+  delete<T>(path: string, body?: unknown, opts: Omit<RequestOptions, "method" | "body"> = {}): Promise<T> {
+    return this.request<T>(path, { ...opts, method: "DELETE", body })
+  }
+}