@cartbase/storefront 0.1.0

package/src/api/checkout.ts

@@ -0,0 +1,440 @@
+/**
+ * @cartbase/storefront/api/checkout — the checkout sequence.
+ *
+ * Two ways to drive checkout, both wrapped here:
+ *
+ *  1. **Orchestrated (recommended)** — `prepareCheckout()` is the atomic
+ *     Buy-click: ONE call writes address (+billing mirror), shipping method
+ *     (+ carrier metadata), payment collection and the payment session at
+ *     the FINAL amount (real Stripe PaymentIntent, or a plain row for
+ *     pp_cod/pp_manual). Then `completeCart()` (see `./carts`). Amount
+ *     drift/repair between the two: `syncPaymentAmount()` and
+ *     `refreshPaymentIfTerminal()`.
+ *
+ *  2. **Manual (Medusa-style)** — `listShippingOptions()` →
+ *     `addShippingMethod()` → `createPaymentCollection()` →
+ *     `initiatePaymentSession()` → `completeCart()`.
+ *
+ * Amount authority everywhere: the SERVER totals engine. The client never
+ * supplies an amount; sessions charge `total − gift_card_total`. Money is
+ * EUR decimal major units. Route ground truth: src/app/api/store/
+ * {shipping-options,payment-providers,payment-collections}/**, carts/[id]/
+ * {shipping-methods,prepare-checkout,sync-payment-amount,
+ * refresh-payment-if-terminal} + src/lib/checkout-orchestration/*.
+ * Doc: docs/storefront/checkout.md.
+ */
+import type { StorefrontClient } from "./http"
+import type { ListEnvelope, MajorUnitAmount } from "./types"
+import type { CartResponse } from "./carts"
+
+// ---------------------------------------------------------------------------
+// Shipping options
+// ---------------------------------------------------------------------------
+
+export interface ListShippingOptionsQuery {
+  /**
+   * Prices the options in the cart's currency AND gives the checkout-rules
+   * engine its evaluation context. Without it `amount` is null and
+   * cart-dependent hide rules cannot match (the completion guard remains
+   * the boundary).
+   */
+  cart_id?: string
+}
+
+/** Row of GET /api/store/shipping-options. */
+export interface StoreShippingOption {
+  id: string
+  name: string
+  provider_id: string | null
+  service_zone_id: string | null
+  shipping_option_type_id: string | null
+  shipping_profile_id: string | null
+  data: Record<string, unknown> | null
+  /** Embedded `shipping_option_types` row (label/description/code) or null. */
+  type: Record<string, unknown> | null
+  /** Flat price in the cart currency; null without `cart_id` or when no price row matches. */
+  amount: MajorUnitAmount | null
+  /** Always "flat" today — calculated-rate carriers are not wired yet. */
+  price_type: "flat"
+  [key: string]: unknown
+}
+
+export interface ShippingOptionListResponse extends ListEnvelope {
+  shipping_options: StoreShippingOption[]
+}
+
+/**
+ * List shipping options (rule-filtered, display-ordered). → 200 list
+ * envelope; `count`/`limit` = full filtered list (no pagination).
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found` (bad `cart_id`).
+ * Settings: checkout rules (`target_type=shipping_option`) hide options
+ * server-side; `checkout_method_order` orders them; rules evaluate the cart
+ * context (customer tags/groups, totals, weight, channel, country) when
+ * `cart_id` is passed. Fail-open: a broken rule never bricks the listing.
+ */
+export async function listShippingOptions(
+  client: StorefrontClient,
+  query: ListShippingOptionsQuery = {}
+): Promise<ShippingOptionListResponse> {
+  return client.get("/api/store/shipping-options", { query: { ...query } })
+}
+
+export interface CalculateShippingOptionInput {
+  cart_id: string
+  /** Provider-specific fields — accepted and currently ignored (flat prices only). */
+  data?: Record<string, unknown>
+}
+
+export interface CalculateShippingOptionResponse {
+  shipping_option: StoreShippingOption & { amount: MajorUnitAmount }
+}
+
+/**
+ * Price one option for a cart. → 200 `{shipping_option}` with `amount` in
+ * the cart currency. Today this returns the flat price-set match —
+ * calculated-rate carriers are not wired (the `data` body is reserved).
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found` | `shipping_option_not_found`, 400
+ * `shipping_price_missing` (no price row in the cart currency) |
+ * `validation_failed`.
+ */
+export async function calculateShippingOption(
+  client: StorefrontClient,
+  shippingOptionId: string,
+  input: CalculateShippingOptionInput
+): Promise<CalculateShippingOptionResponse> {
+  return client.post(`/api/store/shipping-options/${shippingOptionId}/calculate`, input)
+}
+
+/**
+ * Add/replace the cart's shipping method (manual checkout path — the
+ * orchestrated path does this inside `prepareCheckout`). → 200 `{cart}`.
+ * Body: `{option_id, data?}` (`.strict()`).
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found` | `shipping_option_not_found`, 409
+ * `cart_completed`, 400 `shipping_price_missing` | `validation_failed`.
+ */
+export async function addShippingMethod(
+  client: StorefrontClient,
+  cartId: string,
+  input: { option_id: string; data?: Record<string, unknown> }
+): Promise<CartResponse> {
+  return client.post(`/api/store/carts/${cartId}/shipping-methods`, input)
+}
+
+// ---------------------------------------------------------------------------
+// Payment providers
+// ---------------------------------------------------------------------------
+
+export interface ListPaymentProvidersQuery {
+  /** Scope to providers linked to this region (`region_payment_provider`). */
+  region_id?: string
+  /**
+   * Checkout-rules evaluation context — storefronts SHOULD pass it during
+   * checkout; without it cart-dependent hide rules cannot match here.
+   */
+  cart_id?: string
+}
+
+/** Row of GET /api/store/payment-providers. */
+export interface StorePaymentProvider {
+  /** e.g. `pp_stripe`, `pp_cod`, `pp_manual`. `pp_giftcard` is internal and never listed. */
+  id: string
+  is_enabled: boolean
+  created_at?: string
+}
+
+export interface PaymentProviderListResponse extends ListEnvelope {
+  payment_providers: StorePaymentProvider[]
+}
+
+/**
+ * List enabled payment providers (rule-filtered, display-ordered). → 200
+ * list envelope; `count`/`limit` = full filtered list (no pagination).
+ * Without `region_id`: the tenant's enabled providers
+ * (`tenant_payment_providers` ∩ enabled catalog rows). With `region_id`:
+ * providers linked to that region.
+ * Auth: anon `x-client-id`.
+ * Settings: provider enablement (admin integrations — enabling the COD or
+ * Stripe integration provisions `pp_cod`/`pp_stripe`), checkout rules
+ * (`target_type=payment_method`) + `checkout_method_order`.
+ */
+export async function listPaymentProviders(
+  client: StorefrontClient,
+  query: ListPaymentProvidersQuery = {}
+): Promise<PaymentProviderListResponse> {
+  return client.get("/api/store/payment-providers", { query: { ...query } })
+}
+
+// ---------------------------------------------------------------------------
+// Payment collections + sessions (manual checkout path)
+// ---------------------------------------------------------------------------
+
+/**
+ * Body of POST /api/store/payment-collections.
+ * NOTE (code wins over store-api.md): ONLY `cart_id` is read — the
+ * contract's `provider_id`/`data` fields are ignored by the route; the
+ * provider is chosen when initiating the payment session.
+ */
+export interface CreatePaymentCollectionInput {
+  cart_id: string
+}
+
+export interface StorePaymentCollection {
+  id: string
+  /** Always the cart's CURRENT decorated total (refreshed on every call). */
+  amount: MajorUnitAmount
+  currency_code: string
+  /** `not_paid` until complete authorizes. */
+  status: string
+  payment_sessions?: StorePaymentSession[]
+  [key: string]: unknown
+}
+
+export interface CreatePaymentCollectionResponse {
+  payment_collection: StorePaymentCollection
+}
+
+/**
+ * Ensure the cart's payment collection (ONE per cart, idempotent). → 201
+ * `{payment_collection}` when created, 200 when the existing one was
+ * refreshed to the current total.
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found`, 400 `validation_failed`.
+ * Behavior: the moment a collection exists, any applied gift-card tender is
+ * composed as an internal `pp_giftcard` session (gift-cards contract).
+ */
+export async function createPaymentCollection(
+  client: StorefrontClient,
+  input: CreatePaymentCollectionInput
+): Promise<CreatePaymentCollectionResponse> {
+  return client.post("/api/store/payment-collections", input)
+}
+
+export interface InitiatePaymentSessionInput {
+  /** `pp_stripe` | `pp_cod` | `pp_manual` — NEVER `pp_giftcard` (→ 400 `invalid_provider`). */
+  provider_id: string
+  /**
+   * Merged into the session's `data` blob. Provider-state keys
+   * (`payment_intent_id`, `client_secret`, `status`, `stripe_customer_id`,
+   * `setup_future_usage`) are server-owned and stripped.
+   */
+  data?: Record<string, unknown>
+  /**
+   * Subscription carts only — saves the card for future off-session renewal
+   * charges. Requires a logged-in customer (guest → 400 `customer_required`);
+   * the server resolves WHICH customer from the cart, never from the client.
+   * Setting this IS the mandate moment: render the saved-card consent text
+   * next to the payment element when you set it. No-op on non-card providers.
+   */
+  save_payment_method?: boolean
+}
+
+export interface StorePaymentSession {
+  id: string
+  provider_id: string
+  /** `collection.amount − gift_card_total` — the remainder this provider charges. */
+  amount: MajorUnitAmount
+  currency_code: string
+  /** `pending` until authorized at complete. */
+  status: string
+  authorized_at: string | null
+  /**
+   * Provider blob. For Stripe: `payment_intent_id`, `client_secret`
+   * (mount Stripe Elements with it), `status`. Plain row for pp_cod/pp_manual.
+   */
+  data: Record<string, unknown> | null
+  [key: string]: unknown
+}
+
+export interface InitiatePaymentSessionResponse {
+  payment_session: StorePaymentSession
+}
+
+/**
+ * Mint (or repair) the payment session for a provider on a collection —
+ * idempotent per provider. → 201 `{payment_session}` when created, 200 when
+ * the existing session was returned/repaired. For Stripe the PaymentIntent
+ * is minted FIRST (idempotency key = session id); amount drift is synced
+ * in place; terminal PIs self-heal by rotation.
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `payment_collection_not_found`, 400 `invalid_provider`
+ * (pp_giftcard) | `stripe_not_configured` | `validation_failed`.
+ * Settings: Stripe credentials (admin integrations); gift-card tender
+ * shrinks the session amount; COD fee appears on the cart the moment a live
+ * pp_cod session exists.
+ */
+export async function initiatePaymentSession(
+  client: StorefrontClient,
+  paymentCollectionId: string,
+  input: InitiatePaymentSessionInput
+): Promise<InitiatePaymentSessionResponse> {
+  return client.post(
+    `/api/store/payment-collections/${paymentCollectionId}/payment-sessions`,
+    input
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrated Buy-click (prepare → confirm → complete)
+// ---------------------------------------------------------------------------
+
+/**
+ * Address for prepare-checkout — STRICTER than the generic cart address:
+ * every field required except `address_2`/`company`/`province` (min 1 char;
+ * phone included — it's the courier's primary recovery channel).
+ */
+export interface PrepareCheckoutAddress {
+  first_name: string
+  last_name: string
+  address_1: string
+  address_2?: string
+  company?: string
+  province?: string
+  city: string
+  postal_code: string
+  country_code: string
+  phone: string
+}
+
+/** Body of POST /api/store/carts/:id/prepare-checkout (`.strict()`). */
+export interface PrepareCheckoutInput {
+  shipping_address: PrepareCheckoutAddress
+  /** A shipping option id (billing address mirrors the shipping address). */
+  shipping_method_id: string
+  /** Stored on the cart_shipping_methods row. */
+  shipping_method_data?: Record<string, unknown>
+  /**
+   * Opaque per-carrier keys (locker/office pickers) merged into
+   * `cart.metadata`; keys written by the PREVIOUS prepare call are removed
+   * first (tracked under the reserved `_prepared_carrier_keys` marker) so
+   * switching carriers never leaks stale fields into the order.
+   */
+  carrier_metadata?: Record<string, unknown>
+  /** `pp_stripe` | `pp_cod` | `pp_manual` — never `pp_giftcard` (→ 400 `invalid_provider`). */
+  payment_provider: string
+}
+
+/** Response of prepare-checkout (verbatim src/lib/checkout-orchestration/prepare.ts). */
+export interface PrepareCheckoutResult {
+  cart_id: string
+  payment_collection_id: string | null
+  /** Stripe Elements secret; null for pp_cod/pp_manual and zero-remainder carts. */
+  client_secret: string | null
+  /** The provider whose session was minted; null when zero-remainder skipped the session. */
+  provider_id: string | null
+}
+
+/**
+ * Atomic Buy-click step 1 of 2. ONE call writes address (+billing mirror) +
+ * carrier metadata → shipping method (priced against the new destination) →
+ * payment collection at the shipped total → payment session at the FINAL
+ * amount. For pp_cod the native fee applies once the session exists, so
+ * amounts are re-synced after it. Zero-remainder carts (gift cards cover
+ * the total) skip the provider session — `client_secret`/`provider_id`
+ * come back null and the cart completes on the gift session.
+ *
+ * Fully compensated (wire-pattern): any failure rolls back session →
+ * collection → shipping method → addresses/metadata to the pre-call
+ * snapshot and records a reverted execution-ledger row; failures land in
+ * `checkout_error_logs` (step `prepare-checkout`).
+ *
+ * After prepare: Stripe → `stripe.confirmPayment(client_secret)` →
+ * `completeCart()`; COD/manual → `completeCart()` directly.
+ *
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found` | `shipping_option_not_found`, 409
+ * `cart_completed`, 400 `validation_failed` | `invalid_provider` |
+ * `shipping_price_missing` | `stripe_not_configured`.
+ * Settings: Stripe credentials, COD integration fee, gift-card tender,
+ * checkout rules (enforced at listings + complete, not here).
+ */
+export async function prepareCheckout(
+  client: StorefrontClient,
+  cartId: string,
+  input: PrepareCheckoutInput
+): Promise<PrepareCheckoutResult> {
+  return client.post(`/api/store/carts/${cartId}/prepare-checkout`, input)
+}
+
+/** Body of POST /api/store/carts/:id/sync-payment-amount (`.strict()`). */
+export interface SyncPaymentAmountInput {
+  /** Rotate to this provider when it differs from the pending session's. */
+  provider_id?: string
+}
+
+/** Response matrix (verbatim src/lib/checkout-orchestration/sync.ts). */
+export interface SyncPaymentAmountResult {
+  synced: boolean
+  /** true = old session retired + fresh session minted (new client_secret). */
+  rotated?: boolean
+  client_secret?: string | null
+  provider_id?: string | null
+  /** No-op reasons: `cart-completed` | `no_payment_collection` | `no_pending_session`. */
+  reason?: string
+}
+
+/**
+ * Align the pending provider session with the cart's CURRENT total, in
+ * place when possible — the happy path returns the SAME `client_secret` so
+ * `<Elements>` never remounts. Call after anything that changes the total
+ * (line/shipping/gift-card changes) while checkout is mounted.
+ *
+ * Matrix: completed cart → `{synced:false, reason:"cart-completed"}`; no
+ * collection → `no_payment_collection`; no pending provider session (gift
+ * sessions excluded) → `no_pending_session`; provider matches + amount
+ * current → no-op `{synced:true, rotated:false}`; amount drifted →
+ * in-place update (same secret); provider mismatch OR the Stripe update
+ * refused (terminal PI) → rotation `{synced:true, rotated:true}` with a
+ * fresh secret. The old PI is voided best-effort on rotation.
+ *
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found`, 400 `validation_failed` |
+ * `stripe_not_configured`. Failures land in `checkout_error_logs`
+ * (step `sync-payment-amount`).
+ */
+export async function syncPaymentAmount(
+  client: StorefrontClient,
+  cartId: string,
+  input: SyncPaymentAmountInput = {}
+): Promise<SyncPaymentAmountResult> {
+  return client.post(`/api/store/carts/${cartId}/sync-payment-amount`, input)
+}
+
+/** Response (verbatim src/lib/checkout-orchestration/refresh.ts). */
+export interface RefreshPaymentResult {
+  rotated: boolean
+  /**
+   * Rotated: `pi-terminal` | `pi-missing`. Not rotated: `cart-completed` |
+   * `no-stripe-session` | `no-pi-id` | `stripe-not-configured` |
+   * `still-usable` (+ `status`) | `stripe-error` (+ `error`).
+   */
+  reason: string
+  /** Present with `still-usable` — the live PI status. */
+  status?: string
+  /** Present after rotation — the dead PI's status (or "missing"). */
+  previous_status?: string
+  /** Present with `stripe-error`. */
+  error?: string
+}
+
+/**
+ * Reactive dead-PI recovery — reconcile the pending STRIPE session against
+ * Stripe's actual PaymentIntent and rotate a fresh session/PI when the
+ * intent is terminal (`succeeded`/`canceled`/`requires_capture`) or
+ * missing. Call from Elements `loaderror` or on page mount for aged carts —
+ * NEVER proactively per render (the proactive variant caused a production
+ * reload loop). Any transient Stripe error returns
+ * `{rotated:false, reason:"stripe-error"}` WITHOUT rotating. No body.
+ *
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found`. Every rotation writes an audit row
+ * (`checkout_error_logs` step `refresh-payment`, code `rotated`).
+ */
+export async function refreshPaymentIfTerminal(
+  client: StorefrontClient,
+  cartId: string
+): Promise<RefreshPaymentResult> {
+  return client.post(`/api/store/carts/${cartId}/refresh-payment-if-terminal`)
+}

package/src/api/collections.ts

@@ -0,0 +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 },
+  })
+}

package/src/api/consent.ts

@@ -0,0 +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 barter-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` = barter 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")
+}