@cartbase/storefront 0.20.0 → 0.21.0

package/src/api/carts.ts

@@ -1,523 +1,523 @@
-/**
- * @cartbase/storefront/api/carts — cart lifecycle.
- *
- * Wraps the store cart routes (src/app/api/store/carts/**). Every mutation
- * returns the FULL decorated cart (loadAndDecorate → decorateCartTotals +
- * gift-card tender fields) so the storefront never recomputes money —
- * totals are SERVER truth (DOCTRINE: the SDK displays, the API owns math).
- *
- * Auth: all cart routes are anon-writable — `x-client-id` (sent by the
- * client) is the only requirement. A customer JWT (`authorization: Bearer`)
- * is OPTIONAL and changes behavior where noted (customer attach, B2B group
- * pricing). Amounts are EUR decimal major units.
- *
- * Doc: docs/storefront/carts.md · Errors envelope: `{error, code, details?}`
- * → thrown as StoreApiError.
- */
-import { readVisitorId } from "../lib/visitor"
-import type { StorefrontClient } from "./http"
-import type { IsoDateString, MajorUnitAmount } from "./types"
-
-// ---------------------------------------------------------------------------
-// DTOs — ground truth: carts/route.ts, carts/_create.ts, carts/_helpers.ts,
-// carts/_totals.ts, carts/_address.ts, [id]/line-items, [id]/customer,
-// [id]/complete/_flow.ts.
-// ---------------------------------------------------------------------------
-
-/**
- * Address input (create/update). All fields optional on the generic cart
- * routes (`AddressSchema.passthrough()` server-side — extra keys are kept).
- * NOTE: prepare-checkout has its OWN stricter address schema (see
- * `checkout.ts` PrepareCheckoutAddress — most fields required there).
- */
-export interface CartAddressInput {
-  first_name?: string
-  last_name?: string
-  company?: string
-  address_1?: string
-  address_2?: string
-  city?: string
-  /** Lowercased server-side. */
-  country_code?: string
-  province?: string
-  postal_code?: string
-  phone?: string
-  metadata?: Record<string, unknown>
-  [key: string]: unknown
-}
-
-/** Stored cart address row (`cart_addresses`). Unset fields come back null. */
-export interface CartAddress {
-  id: string
-  first_name: string | null
-  last_name: string | null
-  company: string | null
-  address_1: string | null
-  address_2: string | null
-  city: string | null
-  country_code: string | null
-  province: string | null
-  postal_code: string | null
-  phone: string | null
-  metadata: Record<string, unknown> | null
-  [key: string]: unknown
-}
-
-export interface CartLineItemAdjustment {
-  id: string
-  amount: MajorUnitAmount
-  promotion_id?: string | null
-  [key: string]: unknown
-}
-
-export interface CartTaxLine {
-  id: string
-  /** Percentage, e.g. 20 for BG VAT. */
-  rate: number
-  [key: string]: unknown
-}
-
-/**
- * Per-line money decoration (carts/_totals.ts `decorateItem`) — present on
- * every item and shipping method in every cart response.
- */
-export interface LineTotals {
-  subtotal: MajorUnitAmount
-  total: MajorUnitAmount
-  original_total: MajorUnitAmount
-  tax_total: MajorUnitAmount
-  original_tax_total: MajorUnitAmount
-  discount_total: MajorUnitAmount
-  discount_subtotal: MajorUnitAmount
-  discount_tax_total: MajorUnitAmount
-}
-
-/** Decorated cart line item (`cart_line_items` row + LineTotals). */
-export interface CartLineItem extends LineTotals {
-  id: string
-  cart_id: string
-  variant_id: string | null
-  product_id: string | null
-  title: string | null
-  subtitle: string | null
-  product_title: string | null
-  product_handle: string | null
-  thumbnail: string | null
-  variant_title: string | null
-  variant_sku: string | null
-  quantity: number
-  unit_price: MajorUnitAmount
-  is_tax_inclusive: boolean
-  /** false for gift-card lines — they are never discountable. */
-  is_discountable: boolean
-  /** Gift-card product flag, copied onto the line at add time. */
-  is_giftcard: boolean
-  /** false for digital gift cards — lets digital-only carts complete without a shipping method. */
-  requires_shipping: boolean
-  metadata: Record<string, unknown> | null
-  adjustments: CartLineItemAdjustment[]
-  tax_lines: CartTaxLine[]
-  [key: string]: unknown
-}
-
-/** Decorated cart shipping method (`cart_shipping_methods` row + LineTotals). */
-export interface CartShippingMethod extends LineTotals {
-  id: string
-  cart_id: string
-  shipping_option_id: string | null
-  name: string | null
-  amount: MajorUnitAmount
-  is_tax_inclusive: boolean
-  data: Record<string, unknown> | null
-  adjustments: CartLineItemAdjustment[]
-  tax_lines: CartTaxLine[]
-  [key: string]: unknown
-}
-
-/**
- * Applied gift card as decorated onto every cart read (gift-card tender —
- * see `gift-cards.ts` for apply/remove). `amount` is derived from the LIVE
- * ledger at every read; a disabled/expired/depleted card stays listed at 0.
- */
-export interface AppliedGiftCard {
-  id: string
-  /** Masked — the code itself is never echoed. */
-  last4: string
-  amount: MajorUnitAmount
-}
-
-/**
- * The decorated cart — every cart-returning endpoint sends this shape
- * (`{cart: Cart}`). Totals fields are computed by decorateCartTotals
- * (carts/_totals.ts); gift-card fields by resolveGiftCardTender; the COD fee
- * by resolveCodFee. All numbers are EUR decimal major units.
- */
-export interface Cart {
-  id: string
-  region_id: string | null
-  currency_code: string
-  email: string | null
-  /** Set ONLY via the auth-derived paths (create with JWT / setCartCustomer). */
-  customer_id: string | null
-  sales_channel_id: string | null
-  locale: string | null
-  completed_at: IsoDateString | null
-  metadata: Record<string, unknown> | null
-  created_at: IsoDateString
-  updated_at: IsoDateString
-  region?: Record<string, unknown> | null
-  items: CartLineItem[]
-  shipping_methods: CartShippingMethod[]
-  shipping_address: CartAddress | null
-  billing_address: CartAddress | null
-  credit_lines: Array<{ amount: MajorUnitAmount; [key: string]: unknown }>
-  promotions: Array<Record<string, unknown>>
-  /** Embedded pivot → payment collection (+ its payment_sessions). */
-  payment_collection: unknown
-  // — cart-level totals (decorateCartTotals) —
-  total: MajorUnitAmount
-  subtotal: MajorUnitAmount
-  tax_total: MajorUnitAmount
-  discount_total: MajorUnitAmount
-  discount_subtotal: MajorUnitAmount
-  discount_tax_total: MajorUnitAmount
-  shipping_total: MajorUnitAmount
-  shipping_subtotal: MajorUnitAmount
-  shipping_tax_total: MajorUnitAmount
-  shipping_discount_total: MajorUnitAmount
-  original_shipping_total: MajorUnitAmount
-  original_shipping_subtotal: MajorUnitAmount
-  original_shipping_tax_total: MajorUnitAmount
-  item_total: MajorUnitAmount
-  item_subtotal: MajorUnitAmount
-  item_tax_total: MajorUnitAmount
-  item_discount_total: MajorUnitAmount
-  original_item_total: MajorUnitAmount
-  original_item_subtotal: MajorUnitAmount
-  original_item_tax_total: MajorUnitAmount
-  original_total: MajorUnitAmount
-  original_subtotal: MajorUnitAmount
-  original_tax_total: MajorUnitAmount
-  credit_line_total: MajorUnitAmount
-  credit_line_subtotal: MajorUnitAmount
-  credit_line_tax_total: MajorUnitAmount
-  /** The payment method fee — the chosen method's fee_amount (any method
-   * may carry one); non-zero only while a live method session is selected.
-   * Folded into `total`; its own totals row, never a line item. */
-  payment_method_fee_total: MajorUnitAmount
-  payment_method_fee_label: string | null
-  // — gift-card tender decoration (totals NEVER move; see gift-cards.ts) —
-  gift_cards: AppliedGiftCard[]
-  /** Σ of applied-card coverage (= the pp_giftcard session amount). */
-  gift_card_total: MajorUnitAmount
-  /** `max(total − gift_card_total, 0)` — what the remainder provider charges. */
-  gift_card_remainder: MajorUnitAmount
-  [key: string]: unknown
-}
-
-export interface CartResponse {
-  cart: Cart
-}
-
-/**
- * Body of POST /api/store/carts (`.strict()` — unknown keys → 400
- * `validation_failed`). `customer_id` is deliberately NOT a field: the
- * customer is derived from the Bearer JWT (forgery-vector guard G2).
- */
-export interface CreateCartInput {
-  /** Falls back to `stores.default_region_id`; neither → 400 `region_required`. */
-  region_id?: string
-  email?: string
-  /** Must be enabled for the store; region currency is the default. */
-  currency_code?: string
-  items?: Array<{ variant_id: string; quantity: number; selling_plan_id?: string }>
-  /**
-   * B2B v1: with a publishable key, omitting this defaults to the key's
-   * channel; a channel OUTSIDE the key's scope → 400 `invalid_sales_channel`.
-   */
-  sales_channel_id?: string
-  promo_codes?: string[]
-  shipping_address?: CartAddressInput
-  billing_address?: CartAddressInput
-  metadata?: Record<string, unknown>
-  locale?: string
-  /**
-   * THE JOIN KEY: this browser's visitor id, which is what connects the
-   * browsing that led here to the money. Attached automatically by
-   * `createCart` when the page can read the cookie, so a storefront never
-   * has to remember it. Stamped at birth or never.
-   */
-  device_id?: string
-}
-
-/**
- * Body of POST /api/store/carts/:id (partial update, `.strict()`).
- * Addresses: object = set/replace in place, null = clear, absent = untouched.
- * A region change re-resolves currency, CLEARS the shipping address (unless
- * a new one is provided in the same call), drops custom-priced items and
- * re-prices the rest.
- */
-export interface UpdateCartInput {
-  region_id?: string
-  email?: string
-  currency_code?: string
-  sales_channel_id?: string
-  metadata?: Record<string, unknown>
-  locale?: string
-  /** Write-once: a cart that already carries a visitor keeps it. */
-  device_id?: string
-  shipping_address?: CartAddressInput | null
-  billing_address?: CartAddressInput | null
-}
-
-export interface AddLineItemInput {
-  variant_id: string
-  /**
-   * Positive integer. Adding a variant already in the cart UNDER THE SAME
-   * PLAN (or both one-time) bumps its quantity; a one-time line and a
-   * subscription line of the same variant stay separate.
-   */
-  quantity: number
-  /**
-   * Subscription plan for this line (from
-   * `products.listSellingPlans`). The server validates the plan is enabled
-   * and attached to the variant's product (else 400 `invalid_selling_plan`)
-   * and applies the plan price. Omit for a one-time purchase.
-   */
-  selling_plan_id?: string
-  metadata?: Record<string, unknown>
-}
-
-export interface UpdateLineItemInput {
-  /**
-   * Integer ≥ 0 — REQUIRED. 0 deletes the line. NOTE (code wins over
-   * store-api.md): `metadata` is NOT accepted on update, only on add.
-   */
-  quantity: number
-}
-
-/**
- * Success shape of POST /api/store/carts/:id/complete.
- *
- * NOTE (code wins over store-api.md): the route NEVER returns the Medusa
- * `{type:"cart", cart, error}` failure union — failures THROW the standard
- * error envelope (StoreApiError) and the cart stays open/retryable.
- */
-export interface CompleteCartResult {
-  type: "order"
-  order: CompletedOrder
-}
-
-/** Order shape returned by complete (complete/_flow.ts loadOrder). */
-export interface CompletedOrder {
-  id: string
-  display_id?: number
-  status: string
-  email: string | null
-  currency_code: string
-  customer_id: string | null
-  sales_channel_id?: string | null
-  created_at: IsoDateString
-  summary: Array<Record<string, unknown>> | Record<string, unknown> | null
-  /** Flattened line items (order_line_items + pivot quantity). */
-  items: Array<Record<string, unknown> & { quantity: number }>
-  [key: string]: unknown
-}
-
-// ---------------------------------------------------------------------------
-// Functions
-// ---------------------------------------------------------------------------
-
-/**
- * Create a cart. → 201 `{cart}`.
- *
- * Auth: anon `x-client-id`; optional Bearer JWT attaches the customer
- * (customer_id + email) and prices initial items with the customer's B2B
- * groups; optional publishable key applies channel scope.
- * Errors: 400 `validation_failed` | `invalid_region` | `region_required` |
- * `invalid_sales_channel` | `price_not_found` (an initial item has no price
- * in the cart currency), 404 `variant_not_found`. An unsupported
- * `currency_code` does NOT error — it silently falls back to the region
- * currency (only `store_currencies` rows are honored).
- * Settings: store default region; enabled store currencies; publishable-key
- * channel scope; automatic promotions re-applied on create.
- */
-export async function createCart(
-  client: StorefrontClient,
-  input: CreateCartInput = {}
-): Promise<CartResponse> {
-  // The visitor id rides along automatically. It exists only in this
-  // browser at this moment, so a cart created without it can never be
-  // attributed afterwards — which is why this is here and not left to the
-  // caller to remember.
-  const device_id = input.device_id ?? readVisitorId()
-  return client.post("/api/store/carts", device_id ? { ...input, device_id } : input)
-}
-
-/**
- * Retrieve the decorated cart. → 200 `{cart}`.
- * Auth: anon `x-client-id`. Errors: 404 `cart_not_found`.
- * Every read re-runs tax recalc + totals + gift-card tender — amounts are
- * always current (a gift-card balance spent elsewhere shrinks this cart's
- * tender at the next read).
- */
-export async function retrieveCart(
-  client: StorefrontClient,
-  cartId: string
-): Promise<CartResponse> {
-  return client.get(`/api/store/carts/${cartId}`)
-}
-
-/**
- * Partial-update the cart. → 200 `{cart}`.
- * Auth: anon `x-client-id`.
- * Errors: 404 `cart_not_found`, 409 `cart_completed`, 400
- * `validation_failed` | `invalid_region` (unsupported `currency_code` falls
- * back to the region currency instead of erroring).
- * Settings: region change re-prices lines using the cart customer's groups
- * (B2B price lists) and re-applies promotions.
- */
-export async function updateCart(
-  client: StorefrontClient,
-  cartId: string,
-  input: UpdateCartInput
-): Promise<CartResponse> {
-  return client.post(`/api/store/carts/${cartId}`, input)
-}
-
-/**
- * Attach the AUTHENTICATED customer to the cart. Body is empty by contract
- * (`z.object({}).strict()`) — the customer comes from the Bearer JWT, never
- * from the body (forgery-vector guard). → 200 `{cart}`.
- * Auth: `x-client-id` + REQUIRED Bearer JWT.
- * Errors: 401 `unauthenticated`, 404 `cart_not_found`, 409 `cart_completed`,
- * 400 `validation_failed` (any body key).
- */
-export async function setCartCustomer(
-  client: StorefrontClient,
-  cartId: string
-): Promise<CartResponse> {
-  return client.post(`/api/store/carts/${cartId}/customer`, {})
-}
-
-/**
- * Add a line item (same-variant add bumps quantity). → 200 `{cart}`.
- * Auth: anon `x-client-id`.
- * Errors: 404 `cart_not_found` | `variant_not_found`, 409 `cart_completed`,
- * 400 `insufficient_inventory` (kit-aware: every linked inventory component
- * is checked; details carry `{variant_id, inventory_item_id, available,
- * requested}`) | `validation_failed` | `price_not_found` (variant has no
- * price in the cart currency).
- * Settings: B2B price lists (via the cart's attached customer), gift-card
- * product flag (`is_giftcard`/`requires_shipping` ride the line), automatic
- * promotions re-applied.
- */
-export async function addLineItem(
-  client: StorefrontClient,
-  cartId: string,
-  input: AddLineItemInput
-): Promise<CartResponse> {
-  return client.post(`/api/store/carts/${cartId}/line-items`, input)
-}
-
-/**
- * Set a line's quantity (0 deletes it). → 200 `{cart}`.
- * Auth: anon `x-client-id`.
- * Errors: 404 `cart_not_found` | `line_item_not_found`, 409 `cart_completed`,
- * 400 `insufficient_inventory` | `validation_failed`.
- */
-export async function updateLineItem(
-  client: StorefrontClient,
-  cartId: string,
-  lineItemId: string,
-  input: UpdateLineItemInput
-): Promise<CartResponse> {
-  return client.post(`/api/store/carts/${cartId}/line-items/${lineItemId}`, input)
-}
-
-/**
- * Remove a line item (idempotent — removing an already-gone line still
- * returns the cart). → 200 `{cart}`.
- * Auth: anon `x-client-id`. Errors: 404 `cart_not_found` (bad cart id).
- */
-export async function deleteLineItem(
-  client: StorefrontClient,
-  cartId: string,
-  lineItemId: string
-): Promise<CartResponse> {
-  return client.delete(`/api/store/carts/${cartId}/line-items/${lineItemId}`)
-}
-
-/**
- * Complete the cart → place the order. → 200 `{type:"order", order}`.
- * Idempotent: recalling for a completed cart returns the SAME order
- * (order_cart link); concurrent completes are serialized by a CAS lock
- * (the loser either returns the winner's order or 409 `cart_locked`).
- *
- * Auth: anon `x-client-id` (guest checkout) — but when the store setting
- * `accounts_mode='required'`, a guest cart (no attached customer) → 403
- * `account_required`.
- *
- * Validation errors (400): `cart_email_required`, `cart_empty`,
- * `shipping_address_required`, `shipping_method_required` (only when a line
- * `requires_shipping` — digital-only carts skip it),
- * `payment_collection_required`, `payment_session_required`,
- * `checkout_method_hidden` (checkout-rules completion guard), 400
- * `insufficient_inventory` (reserve step). Payment errors (402):
- * `requires_action` (3DS — details carry `client_secret`),
- * `payment_not_authorized`, `payment_not_initiated`, `payment_incomplete`,
- * `gift_card_insufficient_balance`, `gift_card_not_redeemable`. 409
- * `cart_locked`. Any failure compensates fully (order deleted, inventory
- * released, gift tender reversed, cart unlocked) — the cart stays retryable.
- *
- * Settings: checkout rules (completion guard), accounts_mode, COD fee
- * (carried onto the order via order_summaries.totals), gift-card tender
- * (zero-remainder carts complete on the gift session alone).
- * Emits `order.placed` on the durable bus after commit.
- */
-export async function completeCart(
-  client: StorefrontClient,
-  cartId: string
-): Promise<CompleteCartResult> {
-  return client.post(`/api/store/carts/${cartId}/complete`, {})
-}
-
-// ---------------------------------------------------------------------------
-// Promotions — promo codes on the cart (batch-10 merge: the checkout
-// DiscountSection consumed the route raw before this wrapper existed).
-// ---------------------------------------------------------------------------
-
-/**
- * Apply promo code(s) to the cart. → 200 `{cart}` (decorated — totals and
- * `promotions` recomputed server-side; adding is idempotent per code).
- * Auth: anon `x-client-id`.
- * Errors: 404 `cart_not_found`, 400 zod (`promo_codes` must be a non-empty
- * string array), 404 `promotion_not_found` (unknown code on ADD), 400
- * `promotion_inactive` (draft/expired code on ADD).
- */
-export async function applyPromotions(
-  client: StorefrontClient,
-  cartId: string,
-  promoCodes: string[]
-): Promise<CartResponse> {
-  return client.post(`/api/store/carts/${cartId}/promotions`, {
-    promo_codes: promoCodes,
-  })
-}
-
-/**
- * Remove promo code(s) from the cart. → 200 `{cart}` (decorated). Unknown
- * codes silently no-op on remove (Medusa parity).
- * Auth: anon `x-client-id`.
- * Errors: 404 `cart_not_found`, 400 zod.
- */
-export async function removePromotions(
-  client: StorefrontClient,
-  cartId: string,
-  promoCodes: string[]
-): Promise<CartResponse> {
-  return client.request(`/api/store/carts/${cartId}/promotions`, {
-    method: "DELETE",
-    body: { promo_codes: promoCodes },
-  })
-}
+/**
+ * @cartbase/storefront/api/carts — cart lifecycle.
+ *
+ * Wraps the store cart routes (src/app/api/store/carts/**). Every mutation
+ * returns the FULL decorated cart (loadAndDecorate → decorateCartTotals +
+ * gift-card tender fields) so the storefront never recomputes money —
+ * totals are SERVER truth (DOCTRINE: the SDK displays, the API owns math).
+ *
+ * Auth: all cart routes are anon-writable — `x-client-id` (sent by the
+ * client) is the only requirement. A customer JWT (`authorization: Bearer`)
+ * is OPTIONAL and changes behavior where noted (customer attach, B2B group
+ * pricing). Amounts are EUR decimal major units.
+ *
+ * Doc: docs/storefront/carts.md · Errors envelope: `{error, code, details?}`
+ * → thrown as StoreApiError.
+ */
+import { readVisitorId } from "../lib/visitor"
+import type { StorefrontClient } from "./http"
+import type { IsoDateString, MajorUnitAmount } from "./types"
+
+// ---------------------------------------------------------------------------
+// DTOs — ground truth: carts/route.ts, carts/_create.ts, carts/_helpers.ts,
+// carts/_totals.ts, carts/_address.ts, [id]/line-items, [id]/customer,
+// [id]/complete/_flow.ts.
+// ---------------------------------------------------------------------------
+
+/**
+ * Address input (create/update). All fields optional on the generic cart
+ * routes (`AddressSchema.passthrough()` server-side — extra keys are kept).
+ * NOTE: prepare-checkout has its OWN stricter address schema (see
+ * `checkout.ts` PrepareCheckoutAddress — most fields required there).
+ */
+export interface CartAddressInput {
+  first_name?: string
+  last_name?: string
+  company?: string
+  address_1?: string
+  address_2?: string
+  city?: string
+  /** Lowercased server-side. */
+  country_code?: string
+  province?: string
+  postal_code?: string
+  phone?: string
+  metadata?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+/** Stored cart address row (`cart_addresses`). Unset fields come back null. */
+export interface CartAddress {
+  id: string
+  first_name: string | null
+  last_name: string | null
+  company: string | null
+  address_1: string | null
+  address_2: string | null
+  city: string | null
+  country_code: string | null
+  province: string | null
+  postal_code: string | null
+  phone: string | null
+  metadata: Record<string, unknown> | null
+  [key: string]: unknown
+}
+
+export interface CartLineItemAdjustment {
+  id: string
+  amount: MajorUnitAmount
+  promotion_id?: string | null
+  [key: string]: unknown
+}
+
+export interface CartTaxLine {
+  id: string
+  /** Percentage, e.g. 20 for BG VAT. */
+  rate: number
+  [key: string]: unknown
+}
+
+/**
+ * Per-line money decoration (carts/_totals.ts `decorateItem`) — present on
+ * every item and shipping method in every cart response.
+ */
+export interface LineTotals {
+  subtotal: MajorUnitAmount
+  total: MajorUnitAmount
+  original_total: MajorUnitAmount
+  tax_total: MajorUnitAmount
+  original_tax_total: MajorUnitAmount
+  discount_total: MajorUnitAmount
+  discount_subtotal: MajorUnitAmount
+  discount_tax_total: MajorUnitAmount
+}
+
+/** Decorated cart line item (`cart_line_items` row + LineTotals). */
+export interface CartLineItem extends LineTotals {
+  id: string
+  cart_id: string
+  variant_id: string | null
+  product_id: string | null
+  title: string | null
+  subtitle: string | null
+  product_title: string | null
+  product_handle: string | null
+  thumbnail: string | null
+  variant_title: string | null
+  variant_sku: string | null
+  quantity: number
+  unit_price: MajorUnitAmount
+  is_tax_inclusive: boolean
+  /** false for gift-card lines — they are never discountable. */
+  is_discountable: boolean
+  /** Gift-card product flag, copied onto the line at add time. */
+  is_giftcard: boolean
+  /** false for digital gift cards — lets digital-only carts complete without a shipping method. */
+  requires_shipping: boolean
+  metadata: Record<string, unknown> | null
+  adjustments: CartLineItemAdjustment[]
+  tax_lines: CartTaxLine[]
+  [key: string]: unknown
+}
+
+/** Decorated cart shipping method (`cart_shipping_methods` row + LineTotals). */
+export interface CartShippingMethod extends LineTotals {
+  id: string
+  cart_id: string
+  shipping_option_id: string | null
+  name: string | null
+  amount: MajorUnitAmount
+  is_tax_inclusive: boolean
+  data: Record<string, unknown> | null
+  adjustments: CartLineItemAdjustment[]
+  tax_lines: CartTaxLine[]
+  [key: string]: unknown
+}
+
+/**
+ * Applied gift card as decorated onto every cart read (gift-card tender —
+ * see `gift-cards.ts` for apply/remove). `amount` is derived from the LIVE
+ * ledger at every read; a disabled/expired/depleted card stays listed at 0.
+ */
+export interface AppliedGiftCard {
+  id: string
+  /** Masked — the code itself is never echoed. */
+  last4: string
+  amount: MajorUnitAmount
+}
+
+/**
+ * The decorated cart — every cart-returning endpoint sends this shape
+ * (`{cart: Cart}`). Totals fields are computed by decorateCartTotals
+ * (carts/_totals.ts); gift-card fields by resolveGiftCardTender; the COD fee
+ * by resolveCodFee. All numbers are EUR decimal major units.
+ */
+export interface Cart {
+  id: string
+  region_id: string | null
+  currency_code: string
+  email: string | null
+  /** Set ONLY via the auth-derived paths (create with JWT / setCartCustomer). */
+  customer_id: string | null
+  sales_channel_id: string | null
+  locale: string | null
+  completed_at: IsoDateString | null
+  metadata: Record<string, unknown> | null
+  created_at: IsoDateString
+  updated_at: IsoDateString
+  region?: Record<string, unknown> | null
+  items: CartLineItem[]
+  shipping_methods: CartShippingMethod[]
+  shipping_address: CartAddress | null
+  billing_address: CartAddress | null
+  credit_lines: Array<{ amount: MajorUnitAmount; [key: string]: unknown }>
+  promotions: Array<Record<string, unknown>>
+  /** Embedded pivot → payment collection (+ its payment_sessions). */
+  payment_collection: unknown
+  // — cart-level totals (decorateCartTotals) —
+  total: MajorUnitAmount
+  subtotal: MajorUnitAmount
+  tax_total: MajorUnitAmount
+  discount_total: MajorUnitAmount
+  discount_subtotal: MajorUnitAmount
+  discount_tax_total: MajorUnitAmount
+  shipping_total: MajorUnitAmount
+  shipping_subtotal: MajorUnitAmount
+  shipping_tax_total: MajorUnitAmount
+  shipping_discount_total: MajorUnitAmount
+  original_shipping_total: MajorUnitAmount
+  original_shipping_subtotal: MajorUnitAmount
+  original_shipping_tax_total: MajorUnitAmount
+  item_total: MajorUnitAmount
+  item_subtotal: MajorUnitAmount
+  item_tax_total: MajorUnitAmount
+  item_discount_total: MajorUnitAmount
+  original_item_total: MajorUnitAmount
+  original_item_subtotal: MajorUnitAmount
+  original_item_tax_total: MajorUnitAmount
+  original_total: MajorUnitAmount
+  original_subtotal: MajorUnitAmount
+  original_tax_total: MajorUnitAmount
+  credit_line_total: MajorUnitAmount
+  credit_line_subtotal: MajorUnitAmount
+  credit_line_tax_total: MajorUnitAmount
+  /** The payment method fee — the chosen method's fee_amount (any method
+   * may carry one); non-zero only while a live method session is selected.
+   * Folded into `total`; its own totals row, never a line item. */
+  payment_method_fee_total: MajorUnitAmount
+  payment_method_fee_label: string | null
+  // — gift-card tender decoration (totals NEVER move; see gift-cards.ts) —
+  gift_cards: AppliedGiftCard[]
+  /** Σ of applied-card coverage (= the pp_giftcard session amount). */
+  gift_card_total: MajorUnitAmount
+  /** `max(total − gift_card_total, 0)` — what the remainder provider charges. */
+  gift_card_remainder: MajorUnitAmount
+  [key: string]: unknown
+}
+
+export interface CartResponse {
+  cart: Cart
+}
+
+/**
+ * Body of POST /api/store/carts (`.strict()` — unknown keys → 400
+ * `validation_failed`). `customer_id` is deliberately NOT a field: the
+ * customer is derived from the Bearer JWT (forgery-vector guard G2).
+ */
+export interface CreateCartInput {
+  /** Falls back to `stores.default_region_id`; neither → 400 `region_required`. */
+  region_id?: string
+  email?: string
+  /** Must be enabled for the store; region currency is the default. */
+  currency_code?: string
+  items?: Array<{ variant_id: string; quantity: number; selling_plan_id?: string }>
+  /**
+   * B2B v1: with a publishable key, omitting this defaults to the key's
+   * channel; a channel OUTSIDE the key's scope → 400 `invalid_sales_channel`.
+   */
+  sales_channel_id?: string
+  promo_codes?: string[]
+  shipping_address?: CartAddressInput
+  billing_address?: CartAddressInput
+  metadata?: Record<string, unknown>
+  locale?: string
+  /**
+   * THE JOIN KEY: this browser's visitor id, which is what connects the
+   * browsing that led here to the money. Attached automatically by
+   * `createCart` when the page can read the cookie, so a storefront never
+   * has to remember it. Stamped at birth or never.
+   */
+  device_id?: string
+}
+
+/**
+ * Body of POST /api/store/carts/:id (partial update, `.strict()`).
+ * Addresses: object = set/replace in place, null = clear, absent = untouched.
+ * A region change re-resolves currency, CLEARS the shipping address (unless
+ * a new one is provided in the same call), drops custom-priced items and
+ * re-prices the rest.
+ */
+export interface UpdateCartInput {
+  region_id?: string
+  email?: string
+  currency_code?: string
+  sales_channel_id?: string
+  metadata?: Record<string, unknown>
+  locale?: string
+  /** Write-once: a cart that already carries a visitor keeps it. */
+  device_id?: string
+  shipping_address?: CartAddressInput | null
+  billing_address?: CartAddressInput | null
+}
+
+export interface AddLineItemInput {
+  variant_id: string
+  /**
+   * Positive integer. Adding a variant already in the cart UNDER THE SAME
+   * PLAN (or both one-time) bumps its quantity; a one-time line and a
+   * subscription line of the same variant stay separate.
+   */
+  quantity: number
+  /**
+   * Subscription plan for this line (from
+   * `products.listSellingPlans`). The server validates the plan is enabled
+   * and attached to the variant's product (else 400 `invalid_selling_plan`)
+   * and applies the plan price. Omit for a one-time purchase.
+   */
+  selling_plan_id?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface UpdateLineItemInput {
+  /**
+   * Integer ≥ 0 — REQUIRED. 0 deletes the line. NOTE (code wins over
+   * store-api.md): `metadata` is NOT accepted on update, only on add.
+   */
+  quantity: number
+}
+
+/**
+ * Success shape of POST /api/store/carts/:id/complete.
+ *
+ * NOTE (code wins over store-api.md): the route NEVER returns the Medusa
+ * `{type:"cart", cart, error}` failure union — failures THROW the standard
+ * error envelope (StoreApiError) and the cart stays open/retryable.
+ */
+export interface CompleteCartResult {
+  type: "order"
+  order: CompletedOrder
+}
+
+/** Order shape returned by complete (complete/_flow.ts loadOrder). */
+export interface CompletedOrder {
+  id: string
+  display_id?: number
+  status: string
+  email: string | null
+  currency_code: string
+  customer_id: string | null
+  sales_channel_id?: string | null
+  created_at: IsoDateString
+  summary: Array<Record<string, unknown>> | Record<string, unknown> | null
+  /** Flattened line items (order_line_items + pivot quantity). */
+  items: Array<Record<string, unknown> & { quantity: number }>
+  [key: string]: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a cart. → 201 `{cart}`.
+ *
+ * Auth: anon `x-client-id`; optional Bearer JWT attaches the customer
+ * (customer_id + email) and prices initial items with the customer's B2B
+ * groups; optional publishable key applies channel scope.
+ * Errors: 400 `validation_failed` | `invalid_region` | `region_required` |
+ * `invalid_sales_channel` | `price_not_found` (an initial item has no price
+ * in the cart currency), 404 `variant_not_found`. An unsupported
+ * `currency_code` does NOT error — it silently falls back to the region
+ * currency (only `store_currencies` rows are honored).
+ * Settings: store default region; enabled store currencies; publishable-key
+ * channel scope; automatic promotions re-applied on create.
+ */
+export async function createCart(
+  client: StorefrontClient,
+  input: CreateCartInput = {}
+): Promise<CartResponse> {
+  // The visitor id rides along automatically. It exists only in this
+  // browser at this moment, so a cart created without it can never be
+  // attributed afterwards — which is why this is here and not left to the
+  // caller to remember.
+  const device_id = input.device_id ?? readVisitorId()
+  return client.post("/api/store/carts", device_id ? { ...input, device_id } : input)
+}
+
+/**
+ * Retrieve the decorated cart. → 200 `{cart}`.
+ * Auth: anon `x-client-id`. Errors: 404 `cart_not_found`.
+ * Every read re-runs tax recalc + totals + gift-card tender — amounts are
+ * always current (a gift-card balance spent elsewhere shrinks this cart's
+ * tender at the next read).
+ */
+export async function retrieveCart(
+  client: StorefrontClient,
+  cartId: string
+): Promise<CartResponse> {
+  return client.get(`/api/store/carts/${cartId}`)
+}
+
+/**
+ * Partial-update the cart. → 200 `{cart}`.
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found`, 409 `cart_completed`, 400
+ * `validation_failed` | `invalid_region` (unsupported `currency_code` falls
+ * back to the region currency instead of erroring).
+ * Settings: region change re-prices lines using the cart customer's groups
+ * (B2B price lists) and re-applies promotions.
+ */
+export async function updateCart(
+  client: StorefrontClient,
+  cartId: string,
+  input: UpdateCartInput
+): Promise<CartResponse> {
+  return client.post(`/api/store/carts/${cartId}`, input)
+}
+
+/**
+ * Attach the AUTHENTICATED customer to the cart. Body is empty by contract
+ * (`z.object({}).strict()`) — the customer comes from the Bearer JWT, never
+ * from the body (forgery-vector guard). → 200 `{cart}`.
+ * Auth: `x-client-id` + REQUIRED Bearer JWT.
+ * Errors: 401 `unauthenticated`, 404 `cart_not_found`, 409 `cart_completed`,
+ * 400 `validation_failed` (any body key).
+ */
+export async function setCartCustomer(
+  client: StorefrontClient,
+  cartId: string
+): Promise<CartResponse> {
+  return client.post(`/api/store/carts/${cartId}/customer`, {})
+}
+
+/**
+ * Add a line item (same-variant add bumps quantity). → 200 `{cart}`.
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found` | `variant_not_found`, 409 `cart_completed`,
+ * 400 `insufficient_inventory` (kit-aware: every linked inventory component
+ * is checked; details carry `{variant_id, inventory_item_id, available,
+ * requested}`) | `validation_failed` | `price_not_found` (variant has no
+ * price in the cart currency).
+ * Settings: B2B price lists (via the cart's attached customer), gift-card
+ * product flag (`is_giftcard`/`requires_shipping` ride the line), automatic
+ * promotions re-applied.
+ */
+export async function addLineItem(
+  client: StorefrontClient,
+  cartId: string,
+  input: AddLineItemInput
+): Promise<CartResponse> {
+  return client.post(`/api/store/carts/${cartId}/line-items`, input)
+}
+
+/**
+ * Set a line's quantity (0 deletes it). → 200 `{cart}`.
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found` | `line_item_not_found`, 409 `cart_completed`,
+ * 400 `insufficient_inventory` | `validation_failed`.
+ */
+export async function updateLineItem(
+  client: StorefrontClient,
+  cartId: string,
+  lineItemId: string,
+  input: UpdateLineItemInput
+): Promise<CartResponse> {
+  return client.post(`/api/store/carts/${cartId}/line-items/${lineItemId}`, input)
+}
+
+/**
+ * Remove a line item (idempotent — removing an already-gone line still
+ * returns the cart). → 200 `{cart}`.
+ * Auth: anon `x-client-id`. Errors: 404 `cart_not_found` (bad cart id).
+ */
+export async function deleteLineItem(
+  client: StorefrontClient,
+  cartId: string,
+  lineItemId: string
+): Promise<CartResponse> {
+  return client.delete(`/api/store/carts/${cartId}/line-items/${lineItemId}`)
+}
+
+/**
+ * Complete the cart → place the order. → 200 `{type:"order", order}`.
+ * Idempotent: recalling for a completed cart returns the SAME order
+ * (order_cart link); concurrent completes are serialized by a CAS lock
+ * (the loser either returns the winner's order or 409 `cart_locked`).
+ *
+ * Auth: anon `x-client-id` (guest checkout) — but when the store setting
+ * `accounts_mode='required'`, a guest cart (no attached customer) → 403
+ * `account_required`.
+ *
+ * Validation errors (400): `cart_email_required`, `cart_empty`,
+ * `shipping_address_required`, `shipping_method_required` (only when a line
+ * `requires_shipping` — digital-only carts skip it),
+ * `payment_collection_required`, `payment_session_required`,
+ * `checkout_method_hidden` (checkout-rules completion guard), 400
+ * `insufficient_inventory` (reserve step). Payment errors (402):
+ * `requires_action` (3DS — details carry `client_secret`),
+ * `payment_not_authorized`, `payment_not_initiated`, `payment_incomplete`,
+ * `gift_card_insufficient_balance`, `gift_card_not_redeemable`. 409
+ * `cart_locked`. Any failure compensates fully (order deleted, inventory
+ * released, gift tender reversed, cart unlocked) — the cart stays retryable.
+ *
+ * Settings: checkout rules (completion guard), accounts_mode, COD fee
+ * (carried onto the order via order_summaries.totals), gift-card tender
+ * (zero-remainder carts complete on the gift session alone).
+ * Emits `order.placed` on the durable bus after commit.
+ */
+export async function completeCart(
+  client: StorefrontClient,
+  cartId: string
+): Promise<CompleteCartResult> {
+  return client.post(`/api/store/carts/${cartId}/complete`, {})
+}
+
+// ---------------------------------------------------------------------------
+// Promotions — promo codes on the cart (batch-10 merge: the checkout
+// DiscountSection consumed the route raw before this wrapper existed).
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply promo code(s) to the cart. → 200 `{cart}` (decorated — totals and
+ * `promotions` recomputed server-side; adding is idempotent per code).
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found`, 400 zod (`promo_codes` must be a non-empty
+ * string array), 404 `promotion_not_found` (unknown code on ADD), 400
+ * `promotion_inactive` (draft/expired code on ADD).
+ */
+export async function applyPromotions(
+  client: StorefrontClient,
+  cartId: string,
+  promoCodes: string[]
+): Promise<CartResponse> {
+  return client.post(`/api/store/carts/${cartId}/promotions`, {
+    promo_codes: promoCodes,
+  })
+}
+
+/**
+ * Remove promo code(s) from the cart. → 200 `{cart}` (decorated). Unknown
+ * codes silently no-op on remove (Medusa parity).
+ * Auth: anon `x-client-id`.
+ * Errors: 404 `cart_not_found`, 400 zod.
+ */
+export async function removePromotions(
+  client: StorefrontClient,
+  cartId: string,
+  promoCodes: string[]
+): Promise<CartResponse> {
+  return client.request(`/api/store/carts/${cartId}/promotions`, {
+    method: "DELETE",
+    body: { promo_codes: promoCodes },
+  })
+}