@cartbase/storefront 0.19.0 → 0.20.1

package/src/api/checkout.ts

@@ -1,526 +1,526 @@
-/**
- * @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 for a processor, or a
- *     provider-less row for a merchant method). 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_profile_id: string | null
-  data: Record<string, unknown> | null
-  /** The option's display label (e.g. "Express") as `{ label }`, or null. */
-  type: { label: string } | 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
-}
-
-/** A connected PROCESSOR entry of GET /api/store/payment-providers. */
-export interface StorePaymentProcessorEntry {
-  /** e.g. `pp_stripe`. `pp_giftcard` is internal and never listed. */
-  id: string
-  is_enabled: boolean
-  created_at?: string
-}
-
-/** A merchant PAYMENT METHOD entry (pp_* kill, 20260811250000): methods
- * stand alone — no provider id anywhere. Initiate sessions with
- * `payment_method_id`; `kind === "cod"` marks the pre-created
- * collection-on-delivery method (courier cash collection); `instructions`
- * is the merchant's checkout note, rendered under the method. */
-export interface StorePaymentMethodEntry {
-  payment_method_id: string
-  name: string
-  kind: "manual" | "cod"
-  instructions: string | null
-  /** The method's fee (any method may carry one) — predict
-   * `payment_method_fee_total` from it before a session exists. */
-  fee_amount: number | null
-  fee_label: string | null
-}
-
-/** Row of GET /api/store/payment-providers — a processor or a method. */
-export type StorePaymentEntry = StorePaymentProcessorEntry | StorePaymentMethodEntry
-
-/** True when the entry is a merchant payment method (vs a processor). */
-export const isMethodEntry = (
-  entry: StorePaymentEntry
-): entry is StorePaymentMethodEntry => "payment_method_id" in entry
-
-export interface PaymentProviderListResponse extends ListEnvelope {
-  payment_providers: StorePaymentEntry[]
-}
-
-/**
- * List everything payable (rule-filtered, display-ordered): connected
- * processors + every ENABLED merchant method. → 200 list envelope;
- * `count`/`limit` = full filtered list (no pagination). An empty list is
- * honest: a fresh store cannot take money until the merchant connects a
- * processor, flips the COD switch, or creates a manual method
- * (no-payment-method-by-default).
- * Auth: anon `x-client-id`.
- * Settings: processor enablement (admin integrations), the Payments
- * settings methods manager, checkout rules (`target_type=payment_method`,
- * methods participate under their `payment_method_id`) +
- * `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 {
-  /** A connected processor (`pp_stripe`) — NEVER `pp_giftcard` (→ 400
-   * `invalid_provider`). Exactly ONE of `provider_id` /
-   * `payment_method_id` (→ 400 `invalid_data` otherwise). */
-  provider_id?: string
-  /** A merchant payment method (`payment_method_id` from the listing's
-   * method entries) — the session lands with `provider_id` NULL and the
-   * method snapshot (`payment_method_id`/`_name`/`_kind`) in `data`. */
-  payment_method_id?: string
-  /**
-   * Merged into the session's `data` blob. Server-owned keys
-   * (`payment_intent_id`, `client_secret`, `status`, `stripe_customer_id`,
-   * `setup_future_usage`, and the method snapshot keys) are 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
-  /** The processor, or NULL for a merchant-method session (the method
-   * snapshot lives in `data`). */
-  provider_id: string | null
-  /** `collection.amount − gift_card_total` — the remainder this tender charges. */
-  amount: MajorUnitAmount
-  currency_code: string
-  /** `pending` until authorized at complete. */
-  status: string
-  authorized_at: string | null
-  /**
-   * Tender blob. For Stripe: `payment_intent_id`, `client_secret`
-   * (mount Stripe Elements with it), `status`. For methods: the snapshot
-   * `payment_method_id` / `payment_method_name` / `payment_method_kind`.
-   */
-  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 / unknown processor) | `invalid_data` (tender XOR violated,
- * unknown/disabled method) | `stripe_not_configured` | `validation_failed`.
- * Settings: Stripe credentials (admin integrations); gift-card tender
- * shrinks the session amount; the COD fee appears on the cart the moment a
- * live COD-method 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>
-  /** A connected processor (`pp_stripe`) — never `pp_giftcard`. Exactly ONE
-   * of `payment_provider` / `payment_method_id`. */
-  payment_provider?: string
-  /** A merchant payment method — the session lands provider-less with the
-   * method snapshot (pp_* kill, 20260811250000). */
-  payment_method_id?: 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 method sessions and zero-remainder carts. */
-  client_secret: string | null
-  /** The processor whose session was minted; null for method sessions and
-   * when zero-remainder skipped the session. */
-  provider_id: string | null
-  /** The method whose session was minted; null for processor sessions and
-   * when zero-remainder skipped the session. */
-  payment_method_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 the COD method 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 tender session — `client_secret`,
- * `provider_id` and `payment_method_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()`; merchant methods → `completeCart()` directly.
- *
- * Auth: anon `x-client-id`.
- * Errors: 404 `cart_not_found` | `shipping_option_not_found`, 409
- * `cart_completed`, 400 `validation_failed` | `invalid_provider` |
- * `invalid_data` (tender XOR violated) | `shipping_price_missing` |
- * `stripe_not_configured`.
- * Settings: Stripe credentials, the COD method's 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()`).
- * At most ONE of the two — the requested tender; omit both to sync
- * whatever session is pending. */
-export interface SyncPaymentAmountInput {
-  /** Rotate to this processor when the pending session's tender differs. */
-  provider_id?: string
-  /** Rotate to this merchant method when the pending session's tender differs. */
-  payment_method_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
-  payment_method_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`)
-}
-
-// ---------------------------------------------------------------------------
-// Browser-side error reporting
-// ---------------------------------------------------------------------------
-
-/** Body of POST /api/store/checkout-errors (`.strict()`). */
-export interface ReportCheckoutErrorInput {
-  /** The orchestration hook's errorType, e.g. "place_order_error". */
-  error_type: string
-  message: string
-  cart_id?: string
-  /** Redacted context — ids, codes, flags. Never card data, never addresses. */
-  context?: Record<string, unknown>
-}
-
-/**
- * Report a browser-side checkout failure into the platform's
- * checkout_error_logs (step `browser`) so the merchant sees WHY a checkout
- * died in the customer's browser — Stripe.js confirm errors, a 3DS return
- * that came back not-succeeded, a place-order rejection after payment.
- * `useCheckoutOrchestration` calls this BY DEFAULT when no `logError`
- * override is given. Fire-and-forget by contract: swallows every failure —
- * reporting an error must never break a checkout. Rate-limited server-side.
- *
- * Auth: anon `x-client-id`.
- */
-export async function reportCheckoutError(
-  client: StorefrontClient,
-  input: ReportCheckoutErrorInput
-): Promise<void> {
-  try {
-    await client.post(`/api/store/checkout-errors`, input)
-  } catch {
-    // Swallowed by contract — the sink must never take the checkout down.
-  }
-}
+/**
+ * @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 for a processor, or a
+ *     provider-less row for a merchant method). 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_profile_id: string | null
+  data: Record<string, unknown> | null
+  /** The option's display label (e.g. "Express") as `{ label }`, or null. */
+  type: { label: string } | 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
+}
+
+/** A connected PROCESSOR entry of GET /api/store/payment-providers. */
+export interface StorePaymentProcessorEntry {
+  /** e.g. `pp_stripe`. `pp_giftcard` is internal and never listed. */
+  id: string
+  is_enabled: boolean
+  created_at?: string
+}
+
+/** A merchant PAYMENT METHOD entry (pp_* kill, 20260811250000): methods
+ * stand alone — no provider id anywhere. Initiate sessions with
+ * `payment_method_id`; `kind === "cod"` marks the pre-created
+ * collection-on-delivery method (courier cash collection); `instructions`
+ * is the merchant's checkout note, rendered under the method. */
+export interface StorePaymentMethodEntry {
+  payment_method_id: string
+  name: string
+  kind: "manual" | "cod"
+  instructions: string | null
+  /** The method's fee (any method may carry one) — predict
+   * `payment_method_fee_total` from it before a session exists. */
+  fee_amount: number | null
+  fee_label: string | null
+}
+
+/** Row of GET /api/store/payment-providers — a processor or a method. */
+export type StorePaymentEntry = StorePaymentProcessorEntry | StorePaymentMethodEntry
+
+/** True when the entry is a merchant payment method (vs a processor). */
+export const isMethodEntry = (
+  entry: StorePaymentEntry
+): entry is StorePaymentMethodEntry => "payment_method_id" in entry
+
+export interface PaymentProviderListResponse extends ListEnvelope {
+  payment_providers: StorePaymentEntry[]
+}
+
+/**
+ * List everything payable (rule-filtered, display-ordered): connected
+ * processors + every ENABLED merchant method. → 200 list envelope;
+ * `count`/`limit` = full filtered list (no pagination). An empty list is
+ * honest: a fresh store cannot take money until the merchant connects a
+ * processor, flips the COD switch, or creates a manual method
+ * (no-payment-method-by-default).
+ * Auth: anon `x-client-id`.
+ * Settings: processor enablement (admin integrations), the Payments
+ * settings methods manager, checkout rules (`target_type=payment_method`,
+ * methods participate under their `payment_method_id`) +
+ * `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 {
+  /** A connected processor (`pp_stripe`) — NEVER `pp_giftcard` (→ 400
+   * `invalid_provider`). Exactly ONE of `provider_id` /
+   * `payment_method_id` (→ 400 `invalid_data` otherwise). */
+  provider_id?: string
+  /** A merchant payment method (`payment_method_id` from the listing's
+   * method entries) — the session lands with `provider_id` NULL and the
+   * method snapshot (`payment_method_id`/`_name`/`_kind`) in `data`. */
+  payment_method_id?: string
+  /**
+   * Merged into the session's `data` blob. Server-owned keys
+   * (`payment_intent_id`, `client_secret`, `status`, `stripe_customer_id`,
+   * `setup_future_usage`, and the method snapshot keys) are 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
+  /** The processor, or NULL for a merchant-method session (the method
+   * snapshot lives in `data`). */
+  provider_id: string | null
+  /** `collection.amount − gift_card_total` — the remainder this tender charges. */
+  amount: MajorUnitAmount
+  currency_code: string
+  /** `pending` until authorized at complete. */
+  status: string
+  authorized_at: string | null
+  /**
+   * Tender blob. For Stripe: `payment_intent_id`, `client_secret`
+   * (mount Stripe Elements with it), `status`. For methods: the snapshot
+   * `payment_method_id` / `payment_method_name` / `payment_method_kind`.
+   */
+  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 / unknown processor) | `invalid_data` (tender XOR violated,
+ * unknown/disabled method) | `stripe_not_configured` | `validation_failed`.
+ * Settings: Stripe credentials (admin integrations); gift-card tender
+ * shrinks the session amount; the COD fee appears on the cart the moment a
+ * live COD-method 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>
+  /** A connected processor (`pp_stripe`) — never `pp_giftcard`. Exactly ONE
+   * of `payment_provider` / `payment_method_id`. */
+  payment_provider?: string
+  /** A merchant payment method — the session lands provider-less with the
+   * method snapshot (pp_* kill, 20260811250000). */
+  payment_method_id?: 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 method sessions and zero-remainder carts. */
+  client_secret: string | null
+  /** The processor whose session was minted; null for method sessions and
+   * when zero-remainder skipped the session. */
+  provider_id: string | null
+  /** The method whose session was minted; null for processor sessions and
+   * when zero-remainder skipped the session. */
+  payment_method_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 the COD method 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 tender session — `client_secret`,
+ * `provider_id` and `payment_method_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()`; merchant methods → `completeCart()` directly.
+ *
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found` | `shipping_option_not_found`, 409
+ * `cart_completed`, 400 `validation_failed` | `invalid_provider` |
+ * `invalid_data` (tender XOR violated) | `shipping_price_missing` |
+ * `stripe_not_configured`.
+ * Settings: Stripe credentials, the COD method's 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()`).
+ * At most ONE of the two — the requested tender; omit both to sync
+ * whatever session is pending. */
+export interface SyncPaymentAmountInput {
+  /** Rotate to this processor when the pending session's tender differs. */
+  provider_id?: string
+  /** Rotate to this merchant method when the pending session's tender differs. */
+  payment_method_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
+  payment_method_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`)
+}
+
+// ---------------------------------------------------------------------------
+// Browser-side error reporting
+// ---------------------------------------------------------------------------
+
+/** Body of POST /api/store/checkout-errors (`.strict()`). */
+export interface ReportCheckoutErrorInput {
+  /** The orchestration hook's errorType, e.g. "place_order_error". */
+  error_type: string
+  message: string
+  cart_id?: string
+  /** Redacted context — ids, codes, flags. Never card data, never addresses. */
+  context?: Record<string, unknown>
+}
+
+/**
+ * Report a browser-side checkout failure into the platform's
+ * checkout_error_logs (step `browser`) so the merchant sees WHY a checkout
+ * died in the customer's browser — Stripe.js confirm errors, a 3DS return
+ * that came back not-succeeded, a place-order rejection after payment.
+ * `useCheckoutOrchestration` calls this BY DEFAULT when no `logError`
+ * override is given. Fire-and-forget by contract: swallows every failure —
+ * reporting an error must never break a checkout. Rate-limited server-side.
+ *
+ * Auth: anon `x-client-id`.
+ */
+export async function reportCheckoutError(
+  client: StorefrontClient,
+  input: ReportCheckoutErrorInput
+): Promise<void> {
+  try {
+    await client.post(`/api/store/checkout-errors`, input)
+  } catch {
+    // Swallowed by contract — the sink must never take the checkout down.
+  }
+}