@doswiftly/storefront-sdk 15.1.0 → 16.1.0

package/CHANGELOG.md

@@ -1,5 +1,374 @@
 # Changelog
 
+## 16.1.0
+
+### Minor Changes
+
+- 1e6062e: Read the gift card recipient back from the cart.
+
+  `cartUpdateGiftCardRecipient` already persisted the recipient (email, name,
+  personalised message) on a gift card line — but the `CartLine` type didn't
+  expose any field to read it. Storefronts that render the checkout server-side
+  (SSR, deep link, "back to cart" navigation) had no way to know that the buyer
+  had already filled in the recipient form on a previous visit. The recipient
+  dialog opened blank, like nothing had been saved.
+
+  **New field** — `CartLine.giftCardRecipient: GiftCardLineRecipient`
+
+  ```graphql
+  type GiftCardLineRecipient {
+    recipientEmail: String
+    recipientName: String
+    message: String
+  }
+  ```
+
+  All three fields are individually nullable so a partial set (email only, no
+  name or message) is representable as-is. The field on `CartLine` itself is
+  nullable — `null` means the buyer has not set a recipient yet, in which case
+  the gift card is delivered to the order `customerEmail` on completion.
+
+  `null` is also what you get for any non-gift-card line — there is no risk of
+  the field reporting a stale recipient from a previous line at the same index.
+
+  **Use it to seed your form**
+
+  ```tsx
+  const cart = await cartClient.get(cartId);
+  const giftLine = cart?.lines.edges.find(
+    (e) => e.node.productType === "GIFT_CARD",
+  );
+
+  <GiftRecipientForm
+    defaultValues={
+      giftLine?.node.giftCardRecipient ?? {
+        recipientEmail: "",
+        recipientName: "",
+        message: "",
+      }
+    }
+    onSubmit={(values) =>
+      cartClient.updateGiftCardRecipient(cartId, giftLine!.node.id, values)
+    }
+  />;
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. The `CartLine` fragment
+  shipped by the SDK already includes the new field after this release, so
+  upgrading immediately unlocks the read path. No client code changes required
+  to keep existing flows working.
+
+- ac2e306: Distinguish recoverable session loss from permanent cart denial.
+
+  Adds a new `CART_UNAUTHENTICATED` code to the cart error envelope. Until now,
+  both "your sign-in expired" and "this cart belongs to someone else" surfaced
+  as `CART_FORBIDDEN`, so a storefront had no way to know whether to send the
+  buyer to `/login` (recoverable) or to drop the cart cookie (permanent).
+  After the typical ~24h session TTL, the buyer would silently lose their
+  checkout state instead of being prompted to re-authenticate.
+
+  **New code** — `CART_UNAUTHENTICATED`
+
+  | Condition                                                                             | Code                         | Recovery                                                    |
+  | ------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------- |
+  | Anonymous request **or** expired/invalid session on a cart that belongs to a customer | `CART_UNAUTHENTICATED`       | Re-authenticate. Cart is preserved (`cart-id` cookie kept). |
+  | Authenticated as a **different** customer than the cart owner                         | `CART_FORBIDDEN` (unchanged) | Drop the cart cookie and start over.                        |
+
+  The cart resource itself is intact in the `CART_UNAUTHENTICATED` case — the
+  buyer's saved address, line items, discount codes, and gift cards return as
+  soon as they sign in.
+
+  **New SDK signal** — `runner.onSessionExpired(...)`
+
+  The recovery runner now exposes a separate event for session loss, distinct
+  from `onExpired` (which is for cart-resource lifecycle: cart not found, cart
+  already completed). Subscribe once at the provider level and route the buyer
+  to `/login` with a `return_to` parameter; the cart cookie stays put.
+
+  ```ts
+  // app/providers.tsx
+  const unsubExpired = runner.onExpired(() => {
+    // cart resource gone — start fresh
+    router.push("/cart/new");
+  });
+
+  const unsubSession = runner.onSessionExpired(() => {
+    // session gone, cart preserved — sign back in
+    router.push(`/login?return_to=${encodeURIComponent(location.pathname)}`);
+  });
+  ```
+
+  The session branch throws `CartSessionRequiredError` (re-exported alongside
+  `CartRecoveryNotPossibleError`) and does **not** invoke `recreateAndRun` —
+  recreating the cart on a stale session would discard the buyer's progress.
+
+  **Imperative handling**
+
+  If you handle mutation errors directly (Server Action, custom hook), add one
+  case to your existing switch:
+
+  ```ts
+  switch (err.userErrors[0]?.code) {
+    case "CART_UNAUTHENTICATED":
+      redirect(`/login?return_to=${encodeURIComponent("/checkout")}`);
+      break;
+    case "CART_FORBIDDEN":
+      cookies().delete("cart-id");
+      redirect("/cart/expired");
+      break;
+    // ...existing cases for CART_NOT_FOUND / ALREADY_COMPLETED
+  }
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. Existing `case 'CART_FORBIDDEN'`
+  branches keep working as before. Opt in to the new code at your own pace; until
+  you add the case, anonymous and cross-customer denials fall into your existing
+  default branch (one will be recoverable, one will not — adding the case lets
+  you distinguish them).
+
+## 16.0.0
+
+### Major Changes
+
+- ca67b92: **BREAKING** — the formatting utilities switch from a hardcoded 13-currency map to runtime-driven `Intl.NumberFormat` resolution. Every ISO 4217 currency known to the runtime is now supported, with the locale-correct symbol and separators.
+
+  **API changes**
+  - `formatDate(date, locale)` — `locale` is now a required argument. The previous hardcoded `'en-US'` default is gone.
+  - `formatDateTime(date, locale)` — `locale` required.
+  - `formatNumber(num, locale)` — `locale` required.
+  - `formatPrice(price, locale?)` — `locale` is now optional. When omitted, the runtime default (`Intl.NumberFormat().resolvedOptions().locale`) is used. The previous `CURRENCY_LOCALES`-keyed auto-selection is gone.
+  - `formatAmount(amount, currencyCode, locale?)` — third argument added (optional).
+  - `formatPriceRange(min, max, locale?)` — third argument added (optional).
+  - `getCurrencySymbol(code, locale?)` — second argument added (optional). The symbol is derived from `Intl.NumberFormat.formatToParts()`; output depends on the locale (`getCurrencySymbol('PLN', 'pl-PL') === 'zł'`, `getCurrencySymbol('PLN', 'en-US') === 'PLN'`).
+
+  **Removed exports**
+  - `CURRENCY_SYMBOLS` — the 13-entry map is gone. Use `getCurrencySymbol(code, locale)` instead, or read the symbol from `Intl.NumberFormat.formatToParts()` directly.
+  - `CURRENCY_LOCALES` — the locale-to-currency map is gone. Pick the locale from the storefront's i18n context (or read `shop.localeToCurrencyMap` from the API for per-shop overrides) and pass it to `formatPrice` / `formatAmount`.
+
+  **Why**
+  - The hardcoded 13-currency map covered ~7% of the ISO 4217 currencies the API now ships in `CurrencyCode` (~180 entries). Every currency outside that list silently fell back to `en-US` formatting — a Brazilian (BRL) or Indian (INR) storefront had to either write its own formatter or accept US-style output.
+  - Locale↔currency is a **per-shop** decision (`shop.localeToCurrencyMap` in the schema is explicitly marked SSOT). A globally-hardcoded map in the SDK is the wrong place for that knowledge — it makes Polish customers of a multi-locale shop unable to see PLN in `'en-PL'` even when the merchant configured it.
+  - Money precision: `formatPrice` and `formatAmount` no longer apply `parseFloat` to `Money.amount`. Decimal strings are forwarded to `Intl.NumberFormat.format()` verbatim, preserving precision across locales and unusual subunit currencies (JPY/KRW zero-decimal, BHD/JOD/KWD three-decimal, ISK rounding).
+
+  **Migration**
+
+  ```ts
+  // Before
+  import {
+    formatDate,
+    formatPrice,
+    CURRENCY_LOCALES,
+    CURRENCY_SYMBOLS,
+  } from "@doswiftly/storefront-sdk";
+
+  formatDate(order.createdAt); // hardcoded "Dec 9, 2025"
+  formatPrice({ amount: "12.50", currencyCode: "PLN" }); // auto-picked pl-PL → "12,50 zł"
+  CURRENCY_LOCALES.PLN; // "pl-PL"
+  CURRENCY_SYMBOLS.PLN; // "zł"
+
+  // After (Client Components)
+  import { useLocale } from "next-intl";
+  import {
+    formatDate,
+    formatPrice,
+    getCurrencySymbol,
+  } from "@doswiftly/storefront-sdk";
+
+  const locale = useLocale(); // e.g. "pl-PL"
+  formatDate(order.createdAt, locale);
+  formatPrice({ amount: "12.50", currencyCode: "PLN" }, locale);
+  getCurrencySymbol("PLN", locale); // "zł"
+
+  // After (Server Components / Route Handlers)
+  import { getLocale } from "next-intl/server";
+  const locale = await getLocale();
+  formatDate(order.createdAt, locale);
+  ```
+
+  For per-shop locale↔currency overrides, read `shop.localeToCurrencyMap` from the Storefront API and resolve the locale yourself before calling `formatPrice` / `formatAmount`.
+
+  **New: Context-driven format hooks**
+
+  `@doswiftly/storefront-sdk/react` now ships convenience hooks that pull the active language from `useLanguageStore` (inside `<StorefrontProvider>`) and return a memoised, locale-bound formatter. Use them when you don't want to pass `locale` to every call:
+
+  ```ts
+  import {
+    useFormatPrice,
+    useFormatAmount,
+    useFormatPriceRange,
+    useFormatDate,
+    useFormatDateTime,
+    useFormatNumber,
+    useGetCurrencySymbol,
+  } from '@doswiftly/storefront-sdk/react';
+
+  function Cart() {
+    const formatPrice = useFormatPrice();
+    return <span>{formatPrice(item.price)}</span>;
+  }
+
+  function OrderRow() {
+    const formatDate = useFormatDate();
+    return <span>{formatDate(order.processedAt)}</span>;
+  }
+  ```
+
+  Each hook accepts an optional last `localeOverride` argument that wins over the store value — useful for a "show in US format" toggle on a single element:
+
+  ```ts
+  const formatPrice = useFormatPrice();
+  return <span>{formatPrice(item.price, 'en-US')}</span>;
+  ```
+
+  Resolution per call: `localeOverride` → `useLanguageStore().language` → runtime default.
+
+  Use the vanilla `formatPrice` / `formatDate` / etc. from `@doswiftly/storefront-sdk` (no hook) with an explicit `locale` for server components, e-mail templates, or any code path outside a provider.
+
+  `formatPercentage` is unchanged.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — no operations changes.
+
+### Minor Changes
+
+- 885c011: Re-export checkout types from the public API. `CartClient` methods added in 15.1.0 (`getAvailablePaymentMethods`, `getAvailableShippingMethods`) returned typed payloads, but the named types were not part of the public surface — component props and function signatures touching these payloads required `Awaited<ReturnType<...>>` workarounds. This change closes that gap.
+
+  **Newly exported types:**
+  - `PaymentMethod`, `AvailablePaymentMethods` — shape returned by `CartClient.getAvailablePaymentMethods()`
+  - `AvailableShippingMethod`, `AvailableShippingMethodsPayload`, `FreeShippingProgress`, `DeliveryEstimate`, `ShippingCarrier`, `DeliveryType` — shape returned by `CartClient.getAvailableShippingMethods()`
+  - `PickupPoint`, `PickupPointInput` — locker / pickup-point delivery (surfaced via `MailingAddress.pickupPoint` and `CartAddressInput.pickupPoint`)
+  - `CartAttributeInput` — input shape for `CartClient.updateAttributes()`
+  - `ShippingAddressInput` — input shape for the `availableShippingMethods` standalone query
+
+  **Example:**
+
+  ```ts
+  import type {
+    AvailableShippingMethodsPayload,
+    AvailableShippingMethod,
+    DeliveryType,
+  } from "@doswiftly/storefront-sdk";
+
+  function isPickup(method: AvailableShippingMethod): boolean {
+    return method.deliveryType === "PICKUP_POINT";
+  }
+  ```
+
+  No runtime changes — types already existed internally; this change only adds them to the published surface.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — no operations changes.
+
+- fd3d199: Expose `cart.cost.totalDiscount` and `cart.cost.totalShipping` through the `CartCost` fragment.
+
+  The schema already exposed `CartCost.totalDiscount: Money!` (aggregate of every entry in `cart.discountAllocations`) and `CartCost.totalShipping: Money` (cost of the currently selected shipping method, `null` until one is selected), but the shared `CartCost` fragment did not select them — so they were not part of the typed `Cart.cost` returned by `CartClient`. Storefronts wanting to render a single "Discounts: -X" row or a shipping summary had to either sum `discountAllocations` client-side (precision-sensitive across currencies) or query the schema directly and bypass the typed surface.
+
+  After this release, both fields are part of `Cart.cost` returned by every `CartClient` operation — `get`, `create`, `addItems`, `updateItems`, `removeItems`, `setShippingAddress`, `setBillingAddress`, `selectShippingMethod`, `selectPaymentMethod`, `updateBuyerIdentity`, `updateDiscountCodes`, `updateNote`, `updateAttributes`, `applyGiftCard`, `removeGiftCard`, `updateGiftCardRecipient`.
+
+  **Example:**
+
+  ```ts
+  const cart = await cartClient.get(cartId);
+
+  const summary = {
+    subtotal: cart.cost.subtotal,
+    discount: cart.cost.totalDiscount, // Money — defaults to amount 0
+    shipping: cart.cost.totalShipping, // Money | null — null until selectShippingMethod()
+    tax: cart.cost.totalTax,
+    total: cart.cost.total, // grand total — use directly on checkout summary
+  };
+  ```
+
+  `totalDiscount` is required (defaults to amount 0 when no discount applies). `totalShipping` is nullable — `null` means no shipping method has been selected yet, an amount of 0 means a free-shipping method was selected.
+
+  Additive — existing consumers keep every field they had before, no breaking change.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity (fragment update).
+
+- 51091df: Expose `Cart.status` and `Cart.completedOrder` so storefronts can detect a completed (or expired / abandoned) cart on read, without having to attempt a mutation first and react to its `userErrors[].code`.
+
+  **New fields**
+  - `Cart.status: CartStatus!` — lifecycle status (`ACTIVE`, `ABANDONED`, `CONVERTED`, `RECOVERED`, `EXPIRED`). Only `ACTIVE` carts accept mutations; any other status rejects subsequent mutations with `CartErrorCode.ALREADY_COMPLETED`.
+  - `Cart.completedOrder: Order` — the order this cart converted into. Populated only when `status === CONVERTED`; null on every other status.
+
+  **Why**
+
+  When a buyer returned to the checkout page after completing their order (SSR re-render, deep link, "back" button after redirect), the SDK could only ask `cart(id)` for the cart and got the full pre-completion state back — every form value still there, the "Pay" button still active. The first mutation then failed with `ALREADY_COMPLETED`, after the buyer had already filled out fields. With `status` exposed, the storefront detects the terminal state on initial render and redirects to the order confirmation directly — using the `accessToken` on `completedOrder` for guest tracking, no extra `orderByToken` round-trip.
+
+  **Example**
+
+  ```ts
+  const cart = await cartClient.get(cartId);
+  if (!cart) {
+    // Cart not found — guide the buyer to create a new one
+    return redirect("/cart");
+  }
+  if (cart.status !== "ACTIVE") {
+    if (cart.completedOrder) {
+      // Render the order confirmation page off the data you already have
+      return redirect(`/order/${cart.completedOrder.accessToken}`);
+    }
+    // Abandoned / expired — start a fresh cart
+    return redirect("/cart/new");
+  }
+  // Render the checkout form normally
+  ```
+
+  Additive — every existing query that selects the shared `Cart` fragment now sees the two new fields automatically. No breaking change.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — schema sync delivers the new fields and the `CartStatus` enum.
+
+### Patch Changes
+
+- 7ce8ac4: Clarify how `apiUrl` and `shopSlug` are configured.
+
+  `createStorefrontClient` and `<StorefrontProvider>` take `apiUrl` and `shopSlug` as **explicit `config`** — the SDK does not read environment variables, sniff hostnames, or inspect request headers. The storefront supplies the values; the SDK uses them verbatim.
+
+  Scaffolded storefronts ship a config helper (`lib/graphql/config.ts`) that resolves the two values from these sources, in order:
+  1. `doswiftly.config.ts` (preferred — committed file generated at `doswiftly init`)
+  2. `NEXT_PUBLIC_API_URL` + `NEXT_PUBLIC_SHOP_SLUG` (fallback, used for local development)
+  3. `http://localhost:8000` + `demo-shop` (defaults — smoke test only)
+
+  Scratch-built storefronts can skip the helper and pass values into `config={}` directly.
+
+  **What's new**
+  - `@doswiftly/storefront-sdk` README: new `## Configuration` section between `## Installation` and `## Quick Start`. Documents the explicit-config requirement, the three-source resolver shipped with scaffolded storefronts, and when env-var wiring actually matters.
+  - `@doswiftly/storefront-operations` `AGENTS.md`: new `### Configuration sources` convention inside `## Critical conventions — DO NOT hallucinate`. AI assistants now prefer `doswiftly.config.ts` and only fall back to the canonical env-var names.
+
+  Documentation only — no code change.
+
+- f4efab9: Add `ShopConfigFields` fragment + `query ShopConfig` for `<StorefrontProvider>` setup.
+
+  `<StorefrontProvider shopData={...}>` from `@doswiftly/storefront-sdk/react` expects a `ShopConfig` payload with a specific shape: currency setup (including `localeToCurrencyMap`), language setup, and bot protection. Until now the storefront had to hand-write the field selection, and it was easy to miss `localeToCurrencyMap` (used internally by the SDK for browser-locale-based currency detection) or to add an extra field that didn't match the `ShopConfig` interface.
+
+  **New**
+  - `fragment ShopConfigFields on Shop` — minimal selection that matches the `ShopConfig` interface 1:1.
+  - `query ShopConfig { shop { ...ShopConfigFields } }` — ready-to-use query for the provider.
+
+  **Example**
+
+  ```ts
+  const SHOP_CONFIG_QUERY = /* GraphQL */ `
+    query ShopConfig {
+      shop {
+        ...ShopConfigFields
+      }
+    }
+  `;
+
+  // In a Server Component:
+  const { data } = await execute(SHOP_CONFIG_QUERY);
+  return <StorefrontProvider shopData={data.shop}>{children}</StorefrontProvider>;
+  ```
+
+  Use the larger `Shop` fragment + `query Shop` when you also need branding / contact / business hours for your UI; use `ShopConfig` when you only need to bootstrap the provider.
+
+  Additive — no breaking change.
+
+  `@doswiftly/storefront-sdk` bumped to keep linked parity — no code change.
+
 ## 15.1.0
 
 ### Minor Changes

package/README.md

@@ -24,6 +24,34 @@ Layered runtime SDK for DoSwiftly Commerce storefronts. Framework-agnostic core
 pnpm add @doswiftly/storefront-sdk
 ```
 
+## Configuration
+
+`createStorefrontClient` and `<StorefrontProvider>` take `apiUrl` and `shopSlug` as **explicit `config`** — the SDK does not read environment variables, sniff hostnames, or inspect request headers. The storefront supplies the values; the SDK uses them verbatim.
+
+Scaffolded storefronts (`doswiftly init`) ship a `graphqlConfig` helper (`lib/graphql/config.ts`) that resolves both values from three sources in order:
+
+| Source | When | What it gives you |
+| --- | --- | --- |
+| **`doswiftly.config.ts`** (preferred) | `doswiftly init` storefronts | A committed config file with both values. No env wiring needed in normal use. |
+| `NEXT_PUBLIC_API_URL` + `NEXT_PUBLIC_SHOP_SLUG` (fallback) | Local development; storefronts scaffolded outside `doswiftly init` | Standard Next.js public env vars. `doswiftly dev` rewrites `NEXT_PUBLIC_API_URL` to a local CORS proxy at runtime so client-side calls don't hit production CORS headers. |
+| `http://localhost:8000` + `demo-shop` (defaults) | Empty smoke test | Last-resort placeholders so the project boots before any config is written. |
+
+If you go the env-var route, use **exactly these names** — `doswiftly dev` keys off them when overriding. Inventing `API_URL`, `STOREFRONT_URL`, or `TENANT_SLUG` means the dev proxy starts, but your storefront still calls the production API directly and you only learn about it on the first client-side mutation (build and SSR pass silently).
+
+```ts
+// app/layout.tsx — Next.js App Router, template-generated wiring
+import { graphqlConfig } from '@/lib/graphql/config';
+
+<StorefrontProvider
+  config={{ apiUrl: graphqlConfig.apiUrl, shopSlug: graphqlConfig.shopSlug }}
+  shopData={shopData}
+>
+  {children}
+</StorefrontProvider>
+```
+
+Scratch-built storefronts can read `process.env.NEXT_PUBLIC_*` directly and pass the values into `config={}` — the resolution helper is a convenience, not a requirement.
+
 ## Quick Start
 
 ### Core (framework-agnostic)

package/dist/core/cart/cart-recovery.d.ts

@@ -55,6 +55,54 @@ export type CartRecoverableErrorCode = (typeof CART_RECOVERABLE_ERROR_CODES)[num
  * `StorefrontError` carries at least one userError with a recoverable code.
  */
 export declare function isCartRecoverableError(err: unknown): err is StorefrontError;
+/**
+ * Cart error codes that signal a missing or invalid auth context on a
+ * customer-owned cart — distinct from cart-resource recovery
+ * (`CART_RECOVERABLE_ERROR_CODES`).
+ *
+ * - `CART_UNAUTHENTICATED` — anonymous request OR present-but-invalid token
+ *   (expired JWT, malformed). The cart resource is intact and reachable
+ *   again after re-auth.
+ *
+ * Storefronts SHOULD preserve the `cart-id` cookie when handling these
+ * codes and prompt sign-in — the same cart resumes after a successful login.
+ */
+export declare const CART_SESSION_ERROR_CODES: readonly ["CART_UNAUTHENTICATED"];
+export type CartSessionErrorCode = (typeof CART_SESSION_ERROR_CODES)[number];
+/**
+ * Type-safe predicate for "this error means the session is gone, but the
+ * cart resource is intact". Distinct from `isCartRecoverableError`
+ * (cart-resource recovery) — `isCartSessionError` matches auth-recoverable
+ * codes that should trigger re-auth flow, NOT cart cookie cleanup.
+ *
+ * Inspects `err.userErrors[].code` (structured field) — never matches against
+ * `err.message` (locale-dependent, non-stable).
+ */
+export declare function isCartSessionError(err: unknown): err is StorefrontError;
+/**
+ * Event fired when the runner observes a session error (`CART_UNAUTHENTICATED`).
+ * Cart-id cookie is NOT cleared — the cart resource is intact and the buyer
+ * should be prompted to re-authenticate; after a successful login the same
+ * cart resumes.
+ */
+export interface CartSessionExpiredEvent {
+    /** Cart id from the cookie at the time of the failure (null when no cart was set). */
+    oldCartId: string | null;
+    /** Operation name from `CartRecoveryOperation.name` if provided, otherwise 'unknown'. */
+    operation: string;
+    /** Original `StorefrontError` carrying the `CART_UNAUTHENTICATED` userError. */
+    cause: unknown;
+}
+/**
+ * Thrown when a cart operation fails with a session error
+ * (`CART_UNAUTHENTICATED`). Distinct from `CartRecoveryNotPossibleError`
+ * (cart-resource issue) — storefronts should redirect to a sign-in flow
+ * and retry the operation after re-auth.
+ */
+export declare class CartSessionRequiredError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown, message?: string);
+}
 /**
  * Cookie I/O port. Caller's responsibility — core never touches `document.cookie`.
  *
@@ -137,6 +185,14 @@ export interface ExecuteWithCartRecoveryOptions<T> {
     cookieMaxAge?: number;
     /** Optional listener fired before the runner throws `CartRecoveryNotPossibleError`. */
     onExpired?: (event: CartExpiredEvent) => void;
+    /**
+     * Optional listener fired before the runner throws
+     * `CartSessionRequiredError`. Distinct from `onExpired` — the cart
+     * resource is intact, but the session/auth context is missing or invalid.
+     * Storefront should redirect to sign-in and retry the operation after
+     * re-auth; the same cart resumes.
+     */
+    onSessionExpired?: (event: CartSessionExpiredEvent) => void;
 }
 /**
  * Runs an operation against the current cart, recovering once on
@@ -158,6 +214,13 @@ export interface CartRecoveryRunner {
      * fails. Returns an unsubscribe function. Multiple subscribers are supported.
      */
     onExpired(listener: (event: CartExpiredEvent) => void): () => void;
+    /**
+     * Subscribe to `session-expired` events fired when the runner observes a
+     * `CART_UNAUTHENTICATED` userError (cart resource intact, re-auth required).
+     * The cart-id cookie is preserved so the same cart resumes after a successful
+     * sign-in. Returns an unsubscribe function. Multiple subscribers are supported.
+     */
+    onSessionExpired(listener: (event: CartSessionExpiredEvent) => void): () => void;
     /** Underlying cart client (for advanced flows / read-only helpers). */
     readonly cartClient: CartClient;
     /** Underlying cookie store (for advanced flows). */

package/dist/core/cart/cart-recovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cart-recovery.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAMrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,kDAAmD,CAAC;AAE7F,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAQrF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAM3E;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,GAAG,IAAI,MAAM,GAAG,IAAI,CAAC;IACrB,qFAAqF;IACrF,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,6EAA6E;IAC7E,KAAK,IAAI,IAAI,CAAC;CACf;AAMD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,4CAA4C;IAC5C,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACpC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAChF,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,MAAM,EAAE,yBAAyB,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM;CAMhF;AAaD,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,MAAM,EAAE,yBAAyB,CAAC;IAClC,4FAA4F;IAC5F,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAC;CAChB;AAmCD,MAAM,WAAW,8BAA8B,CAAC,CAAC;IAC/C,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,eAAe,CAAC;IAC7B,SAAS,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACpC,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC/C;AAOD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,IAAI,EAAE,8BAA8B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,CAAC,CAuEZ;AAMD,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnE,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;CACvC;AAED,MAAM,WAAW,+BAA+B;IAC9C,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,eAAe,CAAC;IAC7B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,kBAAkB,CAyDpB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,IACxC,YAAY,UAAU,KAAG,OAAO,CAAC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAI5F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,EAC5C,UAAU,GAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAM,gBAZrB,UAAU,KAAG,OAAO,CAAC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAe5F"}
+{"version":3,"file":"cart-recovery.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-recovery.ts"],"names":[],"mappings":"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"}

package/dist/core/cart/cart-recovery.js

@@ -65,6 +65,53 @@ export function isCartRecoverableError(err) {
         return false;
     return err.userErrors.some((ue) => typeof ue.code === 'string' && RECOVERABLE_CODE_SET.has(ue.code));
 }
+// ---------------------------------------------------------------------------
+// Session error codes — auth-recoverable, distinct from cart-resource recovery
+// ---------------------------------------------------------------------------
+/**
+ * Cart error codes that signal a missing or invalid auth context on a
+ * customer-owned cart — distinct from cart-resource recovery
+ * (`CART_RECOVERABLE_ERROR_CODES`).
+ *
+ * - `CART_UNAUTHENTICATED` — anonymous request OR present-but-invalid token
+ *   (expired JWT, malformed). The cart resource is intact and reachable
+ *   again after re-auth.
+ *
+ * Storefronts SHOULD preserve the `cart-id` cookie when handling these
+ * codes and prompt sign-in — the same cart resumes after a successful login.
+ */
+export const CART_SESSION_ERROR_CODES = ['CART_UNAUTHENTICATED'];
+const SESSION_CODE_SET = new Set(CART_SESSION_ERROR_CODES);
+/**
+ * Type-safe predicate for "this error means the session is gone, but the
+ * cart resource is intact". Distinct from `isCartRecoverableError`
+ * (cart-resource recovery) — `isCartSessionError` matches auth-recoverable
+ * codes that should trigger re-auth flow, NOT cart cookie cleanup.
+ *
+ * Inspects `err.userErrors[].code` (structured field) — never matches against
+ * `err.message` (locale-dependent, non-stable).
+ */
+export function isCartSessionError(err) {
+    if (!(err instanceof StorefrontError))
+        return false;
+    if (err.userErrors.length === 0)
+        return false;
+    return err.userErrors.some((ue) => typeof ue.code === 'string' && SESSION_CODE_SET.has(ue.code));
+}
+/**
+ * Thrown when a cart operation fails with a session error
+ * (`CART_UNAUTHENTICATED`). Distinct from `CartRecoveryNotPossibleError`
+ * (cart-resource issue) — storefronts should redirect to a sign-in flow
+ * and retry the operation after re-auth.
+ */
+export class CartSessionRequiredError extends Error {
+    cause;
+    constructor(cause, message) {
+        super(message ?? 'Session required — please sign in to continue', { cause });
+        this.name = 'CartSessionRequiredError';
+        this.cause = cause;
+    }
+}
 /**
  * Thrown when an operation hits a recoverable cart error but recovery is not
  * possible (no `recreateAndRun`, or recovery itself failed). UI should clear
@@ -109,7 +156,7 @@ async function acquireCartId(coord, factory) {
  * consumers can wire this directly without the runner factory.
  */
 export async function executeWithCartRecovery(opts) {
-    const { cartClient, cookieStore, operation, ensureCart, cookieMaxAge, onExpired } = opts;
+    const { cartClient, cookieStore, operation, ensureCart, cookieMaxAge, onExpired, onSessionExpired } = opts;
     const coord = opts.recoveryCoordinator ?? createCoordinator();
     const opName = operation.name ?? 'unknown';
     // Phase 0 — ensure cart exists (cookie may be empty on first interaction).
@@ -126,6 +173,17 @@ export async function executeWithCartRecovery(opts) {
         return await operation.run(cartId);
     }
     catch (err) {
+        // Session loss — cart resource intact, re-auth needed. Preserve cookie
+        // so the same cart resumes after a successful login.
+        if (isCartSessionError(err)) {
+            const sessionEvent = {
+                oldCartId: cartId,
+                operation: opName,
+                cause: err,
+            };
+            onSessionExpired?.(sessionEvent);
+            throw new CartSessionRequiredError(err);
+        }
         if (!isCartRecoverableError(err))
             throw err;
         const oldCartId = cartId;
@@ -181,9 +239,20 @@ export async function executeWithCartRecovery(opts) {
 export function createCartRecoveryRunner(options) {
     const { cartClient, cookieStore, ensureCart, cookieMaxAge } = options;
     const coordinator = createCoordinator();
-    const listeners = new Set();
-    function emit(event) {
-        for (const listener of listeners) {
+    const expiredListeners = new Set();
+    const sessionListeners = new Set();
+    function emitExpired(event) {
+        for (const listener of expiredListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listeners must not break recovery flow — swallow listener exceptions.
+            }
+        }
+    }
+    function emitSessionExpired(event) {
+        for (const listener of sessionListeners) {
             try {
                 listener(event);
             }
@@ -203,7 +272,8 @@ export function createCartRecoveryRunner(options) {
                 ensureCart,
                 cookieMaxAge,
                 recoveryCoordinator: coordinator,
-                onExpired: emit,
+                onExpired: emitExpired,
+                onSessionExpired: emitSessionExpired,
             };
             return executeWithCartRecovery(internalOpts);
         },
@@ -215,9 +285,18 @@ export function createCartRecoveryRunner(options) {
                 return await cartClient.get(cartId);
             }
             catch (err) {
+                if (isCartSessionError(err)) {
+                    // Cart resource intact — re-auth required. Preserve cookie.
+                    emitSessionExpired({
+                        oldCartId: cartId,
+                        operation: 'getCart',
+                        cause: err,
+                    });
+                    throw new CartSessionRequiredError(err);
+                }
                 if (isCartRecoverableError(err)) {
                     cookieStore.clear();
-                    emit({
+                    emitExpired({
                         reason: 'state-dependent',
                         oldCartId: cartId,
                         operation: 'getCart',
@@ -229,8 +308,12 @@ export function createCartRecoveryRunner(options) {
             }
         },
         onExpired(listener) {
-            listeners.add(listener);
-            return () => listeners.delete(listener);
+            expiredListeners.add(listener);
+            return () => expiredListeners.delete(listener);
+        },
+        onSessionExpired(listener) {
+            sessionListeners.add(listener);
+            return () => sessionListeners.delete(listener);
         },
     };
 }

package/dist/core/cart/types.d.ts

@@ -93,7 +93,7 @@ export type PaymentSession = PaymentSessionFragment;
 export type DiscountValidationResult = CartValidateDiscountCodeQuery['cartValidateDiscountCode'];
 export type DiscountInfo = NonNullable<DiscountValidationResult['discount']>;
 export type DiscountValidationError = NonNullable<DiscountValidationResult['error']>;
-export type { CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput, CartAttributeInput, CartCompleteInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartSelectPaymentMethodInput, CartSelectShippingMethodInput, CartSetBillingAddressInput, CartSetShippingAddressInput, CartUpdateGiftCardRecipientInput, PaymentCreateInput, ShippingAddressInput, DeliveryType, AttributeSelectionInput as CartAttributeSelectionInput, PaymentMethodType, PaymentInitiationFlow, DiscountApplicationType, DiscountErrorCode, CurrencyCode, CountryCode, LanguageCode, ProductTypeEnum, WeightUnit, CartWarningCode, AttributeType, AttributeFillingMode, AttributeBillingMode, AttributeOptionSurchargeType, StorefrontOrderStatus, OrderPaymentStatus, OrderFulfillmentStatus, } from '../generated/operation-types';
+export type { CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput, CartAttributeInput, CartCompleteInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartSelectPaymentMethodInput, CartSelectShippingMethodInput, CartSetBillingAddressInput, CartSetShippingAddressInput, CartUpdateGiftCardRecipientInput, PaymentCreateInput, ShippingAddressInput, PickupPointInput, DeliveryType, DeliveryEstimate, ShippingCarrier, FreeShippingProgress, PickupPoint, AttributeSelectionInput as CartAttributeSelectionInput, PaymentMethodType, PaymentInitiationFlow, DiscountApplicationType, DiscountErrorCode, CurrencyCode, CountryCode, LanguageCode, ProductTypeEnum, WeightUnit, CartWarningCode, AttributeType, AttributeFillingMode, AttributeBillingMode, AttributeOptionSurchargeType, StorefrontOrderStatus, OrderPaymentStatus, OrderFulfillmentStatus, } from '../generated/operation-types';
 /**
  * Machine-readable error code surfaced when `createPayment` fails. The call
  * throws a `StorefrontError` on `userErrors` — read `.userErrors[0].code` off