@doswiftly/storefront-sdk 11.1.0 → 11.3.1

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

@@ -0,0 +1,210 @@
+/**
+ * Cart recovery — DX-first auto-recovery for stale cart errors.
+ *
+ * Backend cart write operations enforce stricter checks than reads. Cart can
+ * return successfully from `cart(id)` query while `cartAddLines(id)` rejects with
+ * `userErrors[].code = 'CART_NOT_FOUND'` (ownership/lifetime drift after read).
+ * Same happens after checkout: cart transitions to CONVERTED status → next write
+ * yields `ALREADY_COMPLETED`.
+ *
+ * This module gives every SDK consumer (React, Vue, Svelte, mobile, CLI) the
+ * same automatic recovery without each integrator reimplementing detection,
+ * cookie cleanup, and retry orchestration.
+ *
+ * The runner classifies operations:
+ *
+ *   - **Auto-replay** — operation provides `recreateAndRun` (atomic create-and-run
+ *     against a fresh cart). Storefront caller sees the operation succeed; the
+ *     swap is invisible. Typical fit: `addItems` via `cartCreate({ lines })`.
+ *
+ *   - **Bail + event** — operation has no `recreateAndRun`, i.e. it references
+ *     state from the dead cart (lineIds for update/remove, shippingMethodId for
+ *     select). Replaying on an empty cart would silently lose user intent, so
+ *     the runner clears the cookie, emits `cart-expired`, and throws
+ *     `CartRecoveryNotPossibleError`. UI subscribes once globally and shows a
+ *     toast / banner — caller code never writes `try / catch` per mutation.
+ *
+ * Detection is **code-based** (`err.userErrors[].code`) not message-based —
+ * resilient to PL/EN/future locales. Concurrent operations share one in-flight
+ * recovery promise so a double-click never produces two orphan carts.
+ *
+ * Core stays 0-deps: cookie I/O is injected via `CartCookieStore` port (caller
+ * provides browser / Next.js server / AsyncStorage / in-memory implementation).
+ */
+import { StorefrontError } from '../errors';
+import { CartClient, type CartMutationOutcome } from './cart-client';
+import type { Cart, CartCreateInput } from './types';
+/**
+ * Cart error codes that require recreation of the cart resource.
+ *
+ * - `CART_NOT_FOUND` — cart expired, missing, or owner mismatch (backend masks
+ *   `UNAUTHORIZED` as `CART_NOT_FOUND` to avoid leaking ownership info).
+ * - `ALREADY_COMPLETED` — cart status not in `{ACTIVE, RECOVERED}` (CONVERTED
+ *   after checkout, EXPIRED via TTL, or ABANDONED by purge worker).
+ *
+ * Other codes (`NOT_ENOUGH_IN_STOCK`, validation, fulfillment) are recoverable
+ * by user input, not by cart recreation — they propagate unchanged.
+ */
+export declare const CART_RECOVERABLE_ERROR_CODES: readonly ["CART_NOT_FOUND", "ALREADY_COMPLETED"];
+export type CartRecoverableErrorCode = (typeof CART_RECOVERABLE_ERROR_CODES)[number];
+/**
+ * Type-safe predicate for "this error means the cart resource is gone".
+ *
+ * Inspects `err.userErrors[].code` (structured field) — never matches against
+ * `err.message` (locale-dependent, non-stable). Returns `true` only when a
+ * `StorefrontError` carries at least one userError with a recoverable code.
+ */
+export declare function isCartRecoverableError(err: unknown): err is StorefrontError;
+/**
+ * Cookie I/O port. Caller's responsibility — core never touches `document.cookie`.
+ *
+ * Three methods form a cohesive lifecycle (read existing, write new, clear after
+ * expiry). Implementations:
+ *
+ *   - Browser: `createBrowserCartCookieStore()` (from `@doswiftly/storefront-sdk/react`)
+ *   - Next.js Server Component / Route Handler: wrap `cookies()` from `next/headers`
+ *   - React Native / mobile: AsyncStorage adapter
+ *   - CLI / Node: file-based or in-memory `Map<string, string>`
+ *   - Tests: in-memory stub
+ */
+export interface CartCookieStore {
+    /** Returns the persisted cart id or null. Must be synchronous. */
+    get(): string | null;
+    /** Persists cart id. `options.maxAge` defaults to platform `CART_COOKIE_MAX_AGE`. */
+    set(cartId: string, options?: {
+        maxAge?: number;
+    }): void;
+    /** Removes the cookie. Called when the current cart became unrecoverable. */
+    clear(): void;
+}
+/**
+ * Description of an operation the runner will execute, with optional recovery
+ * strategy.
+ *
+ * `run` is the happy-path call against an existing `cartId`. The runner invokes
+ * it first; on success, returns its value.
+ *
+ * `recreateAndRun` is the **auto-replay strategy**: when defined, on recoverable
+ * error the runner clears the cookie, calls `recreateAndRun(cartClient)` which
+ * atomically creates a fresh cart with the same payload (e.g. `cartCreate({ lines })`
+ * for `addItems`), persists the new id, and returns the operation result in one
+ * round trip. When absent, the runner bails with `CartRecoveryNotPossibleError`
+ * and emits a `cart-expired` event — appropriate for operations that reference
+ * state from the dead cart (`updateItems(lineId)`, `selectShippingMethod`, etc.).
+ */
+export interface CartRecoveryOperation<T> {
+    /** Happy-path call with current cart id. */
+    run: (cartId: string) => Promise<T>;
+    /**
+     * Optional atomic "create new cart and run with payload in one go" strategy.
+     * Define for replay-safe operations; omit for state-dependent ones.
+     */
+    recreateAndRun?: (cartClient: CartClient) => Promise<{
+        cart: Cart;
+        result: T;
+    }>;
+    /** Optional diagnostic label surfaced in `CartExpiredEvent.operation`. */
+    name?: string;
+}
+export type CartRecoveryFailureReason = 'state-dependent' | 'recreate-failed' | 'retry-also-failed';
+/**
+ * Thrown when an operation hits a recoverable cart error but recovery is not
+ * possible (no `recreateAndRun`, or recovery itself failed). UI should clear
+ * local cart state and prompt the user to start over.
+ */
+export declare class CartRecoveryNotPossibleError extends Error {
+    readonly reason: CartRecoveryFailureReason;
+    readonly cause: unknown;
+    constructor(reason: CartRecoveryFailureReason, cause: unknown, message?: string);
+}
+export interface CartExpiredEvent {
+    /** Why recovery did not produce a usable cart for the caller. */
+    reason: CartRecoveryFailureReason;
+    /** Cart id present in the cookie immediately before clearing (null if cookie was empty). */
+    oldCartId: string | null;
+    /** Operation name from `CartRecoveryOperation.name` if provided, otherwise 'unknown'. */
+    operation: string;
+    /** Original error that triggered recovery (or recreate failure). */
+    cause: unknown;
+}
+export interface ExecuteWithCartRecoveryOptions<T> {
+    cartClient: CartClient;
+    cookieStore: CartCookieStore;
+    operation: CartRecoveryOperation<T>;
+    /** Initial-create fallback when cookie is empty. Defaults to `cartClient.create()`. */
+    ensureCart?: () => Promise<Cart>;
+    /** Cookie `maxAge` override propagated to `cookieStore.set`. */
+    cookieMaxAge?: number;
+    /** Optional listener fired before the runner throws `CartRecoveryNotPossibleError`. */
+    onExpired?: (event: CartExpiredEvent) => void;
+}
+/**
+ * Runs an operation against the current cart, recovering once on
+ * `CART_NOT_FOUND` / `ALREADY_COMPLETED`. Pure async function — non-React
+ * consumers can wire this directly without the runner factory.
+ */
+export declare function executeWithCartRecovery<T>(opts: ExecuteWithCartRecoveryOptions<T>): Promise<T>;
+export interface CartRecoveryRunner {
+    /** Run any operation through the recovery pipeline. */
+    execute<T>(operation: CartRecoveryOperation<T>): Promise<T>;
+    /**
+     * Convenience read with auto-cookie-cleanup. Returns the cart or null.
+     * If the backend returns `CART_NOT_FOUND` via `userErrors`, clears the cookie
+     * and resolves null instead of throwing.
+     */
+    getCart(): Promise<Cart | null>;
+    /**
+     * Subscribe to `cart-expired` events fired when the runner bails or recreate
+     * fails. Returns an unsubscribe function. Multiple subscribers are supported.
+     */
+    onExpired(listener: (event: CartExpiredEvent) => void): () => void;
+    /** Underlying cart client (for advanced flows / read-only helpers). */
+    readonly cartClient: CartClient;
+    /** Underlying cookie store (for advanced flows). */
+    readonly cookieStore: CartCookieStore;
+}
+export interface CreateCartRecoveryRunnerOptions {
+    cartClient: CartClient;
+    cookieStore: CartCookieStore;
+    /** Initial-create payload override (default: empty cart). */
+    ensureCart?: () => Promise<Cart>;
+    /** Cookie `maxAge` propagated to all `cookieStore.set` calls. */
+    cookieMaxAge?: number;
+}
+/**
+ * Build a per-shop-session runner that shares a recovery coordinator across
+ * concurrent operations and exposes an `onExpired` listener pattern.
+ */
+export declare function createCartRecoveryRunner(options: CreateCartRecoveryRunnerOptions): CartRecoveryRunner;
+/**
+ * Build a `recreateAndRun` for any operation expressible as a single
+ * `cartCreate(input)` call. The fresh cart's outcome (`{ cart, warnings }`) is
+ * returned as `result`, matching what the equivalent post-create write would
+ * have returned — caller code stays uniform between happy and recovery paths.
+ *
+ * Use for: `addItems` (lines), `updateBuyerIdentity` (buyerIdentity),
+ * `setShippingAddress` (shippingAddress), `updateDiscountCodes` (discountCodes),
+ * `updateNote` (note), or any combination.
+ *
+ * @example
+ * ```typescript
+ * const operation: CartRecoveryOperation<CartMutationOutcome> = {
+ *   run: (cartId) => cartClient.addItems(cartId, lines),
+ *   recreateAndRun: recreateWithInput({ lines }),
+ *   name: 'addItems',
+ * };
+ * ```
+ */
+export declare function recreateWithInput(input: CartCreateInput): (cartClient: CartClient) => Promise<{
+    cart: Cart;
+    result: CartMutationOutcome;
+}>;
+/**
+ * Specialized alias for the most common case (`addItems` recovery).
+ * Equivalent to `recreateWithInput({ lines, ...extraInput })`.
+ */
+export declare function recreateWithLines(lines: NonNullable<CartCreateInput['lines']>, extraInput?: Omit<CartCreateInput, 'lines'>): (cartClient: CartClient) => Promise<{
+    cart: Cart;
+    result: CartMutationOutcome;
+}>;
+//# sourceMappingURL=cart-recovery.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,271 @@
+/**
+ * Cart recovery — DX-first auto-recovery for stale cart errors.
+ *
+ * Backend cart write operations enforce stricter checks than reads. Cart can
+ * return successfully from `cart(id)` query while `cartAddLines(id)` rejects with
+ * `userErrors[].code = 'CART_NOT_FOUND'` (ownership/lifetime drift after read).
+ * Same happens after checkout: cart transitions to CONVERTED status → next write
+ * yields `ALREADY_COMPLETED`.
+ *
+ * This module gives every SDK consumer (React, Vue, Svelte, mobile, CLI) the
+ * same automatic recovery without each integrator reimplementing detection,
+ * cookie cleanup, and retry orchestration.
+ *
+ * The runner classifies operations:
+ *
+ *   - **Auto-replay** — operation provides `recreateAndRun` (atomic create-and-run
+ *     against a fresh cart). Storefront caller sees the operation succeed; the
+ *     swap is invisible. Typical fit: `addItems` via `cartCreate({ lines })`.
+ *
+ *   - **Bail + event** — operation has no `recreateAndRun`, i.e. it references
+ *     state from the dead cart (lineIds for update/remove, shippingMethodId for
+ *     select). Replaying on an empty cart would silently lose user intent, so
+ *     the runner clears the cookie, emits `cart-expired`, and throws
+ *     `CartRecoveryNotPossibleError`. UI subscribes once globally and shows a
+ *     toast / banner — caller code never writes `try / catch` per mutation.
+ *
+ * Detection is **code-based** (`err.userErrors[].code`) not message-based —
+ * resilient to PL/EN/future locales. Concurrent operations share one in-flight
+ * recovery promise so a double-click never produces two orphan carts.
+ *
+ * Core stays 0-deps: cookie I/O is injected via `CartCookieStore` port (caller
+ * provides browser / Next.js server / AsyncStorage / in-memory implementation).
+ */
+import { StorefrontError } from '../errors';
+// ---------------------------------------------------------------------------
+// Error codes — must mirror backend CartErrorCode enum (guarded by drift test)
+// ---------------------------------------------------------------------------
+/**
+ * Cart error codes that require recreation of the cart resource.
+ *
+ * - `CART_NOT_FOUND` — cart expired, missing, or owner mismatch (backend masks
+ *   `UNAUTHORIZED` as `CART_NOT_FOUND` to avoid leaking ownership info).
+ * - `ALREADY_COMPLETED` — cart status not in `{ACTIVE, RECOVERED}` (CONVERTED
+ *   after checkout, EXPIRED via TTL, or ABANDONED by purge worker).
+ *
+ * Other codes (`NOT_ENOUGH_IN_STOCK`, validation, fulfillment) are recoverable
+ * by user input, not by cart recreation — they propagate unchanged.
+ */
+export const CART_RECOVERABLE_ERROR_CODES = ['CART_NOT_FOUND', 'ALREADY_COMPLETED'];
+const RECOVERABLE_CODE_SET = new Set(CART_RECOVERABLE_ERROR_CODES);
+// ---------------------------------------------------------------------------
+// Detection — code-based, locale-proof
+// ---------------------------------------------------------------------------
+/**
+ * Type-safe predicate for "this error means the cart resource is gone".
+ *
+ * Inspects `err.userErrors[].code` (structured field) — never matches against
+ * `err.message` (locale-dependent, non-stable). Returns `true` only when a
+ * `StorefrontError` carries at least one userError with a recoverable code.
+ */
+export function isCartRecoverableError(err) {
+    if (!(err instanceof StorefrontError))
+        return false;
+    if (err.userErrors.length === 0)
+        return false;
+    return err.userErrors.some((ue) => typeof ue.code === 'string' && RECOVERABLE_CODE_SET.has(ue.code));
+}
+/**
+ * Thrown when an operation hits a recoverable cart error but recovery is not
+ * possible (no `recreateAndRun`, or recovery itself failed). UI should clear
+ * local cart state and prompt the user to start over.
+ */
+export class CartRecoveryNotPossibleError extends Error {
+    reason;
+    cause;
+    constructor(reason, cause, message) {
+        super(message ?? defaultMessageFor(reason), { cause });
+        this.name = 'CartRecoveryNotPossibleError';
+        this.reason = reason;
+        this.cause = cause;
+    }
+}
+function defaultMessageFor(reason) {
+    switch (reason) {
+        case 'state-dependent':
+            return 'Cart expired and this operation cannot be safely replayed on a new cart';
+        case 'recreate-failed':
+            return 'Cart expired and creating a replacement cart failed';
+        case 'retry-also-failed':
+            return 'Cart expired; the replacement cart was also rejected by the backend';
+    }
+}
+function createCoordinator() {
+    return { inFlight: null };
+}
+async function acquireCartId(coord, factory) {
+    if (coord.inFlight)
+        return coord.inFlight;
+    const p = factory().finally(() => {
+        if (coord.inFlight === p)
+            coord.inFlight = null;
+    });
+    coord.inFlight = p;
+    return p;
+}
+/**
+ * Runs an operation against the current cart, recovering once on
+ * `CART_NOT_FOUND` / `ALREADY_COMPLETED`. Pure async function — non-React
+ * consumers can wire this directly without the runner factory.
+ */
+export async function executeWithCartRecovery(opts) {
+    const { cartClient, cookieStore, operation, ensureCart, cookieMaxAge, onExpired } = opts;
+    const coord = opts.recoveryCoordinator ?? createCoordinator();
+    const opName = operation.name ?? 'unknown';
+    // Phase 0 — ensure cart exists (cookie may be empty on first interaction).
+    let cartId = cookieStore.get();
+    if (!cartId) {
+        cartId = await acquireCartId(coord, async () => {
+            const created = ensureCart ? await ensureCart() : (await cartClient.create()).cart;
+            cookieStore.set(created.id, cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : undefined);
+            return created.id;
+        });
+    }
+    // Phase 1 — happy path.
+    try {
+        return await operation.run(cartId);
+    }
+    catch (err) {
+        if (!isCartRecoverableError(err))
+            throw err;
+        const oldCartId = cartId;
+        // Phase 2a — bail path (operation has no replay strategy).
+        if (!operation.recreateAndRun) {
+            cookieStore.clear();
+            const event = {
+                reason: 'state-dependent',
+                oldCartId,
+                operation: opName,
+                cause: err,
+            };
+            onExpired?.(event);
+            throw new CartRecoveryNotPossibleError('state-dependent', err);
+        }
+        // Phase 2b — atomic recreate via operation strategy.
+        // Concurrent recoveries are intentionally NOT deduplicated here: each
+        // operation carries its own payload (different lines / address / etc.) and
+        // merging them would silently drop one. The Phase 0 mutex covers the much
+        // more common collision (multiple components mounting and observing an
+        // empty cookie at the same time). If two operations recover concurrently
+        // one new cart per operation is created — the last `cookieStore.set` wins,
+        // matching the natural "last-write" semantics of cookies.
+        let result;
+        try {
+            cookieStore.clear();
+            const recreated = await operation.recreateAndRun(cartClient);
+            cookieStore.set(recreated.cart.id, cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : undefined);
+            result = recreated.result;
+        }
+        catch (recreateErr) {
+            // If recreate itself returned a recoverable user error, treat as
+            // retry-also-failed — backend is rejecting fresh carts somehow, bail.
+            const reason = isCartRecoverableError(recreateErr)
+                ? 'retry-also-failed'
+                : 'recreate-failed';
+            const event = {
+                reason,
+                oldCartId,
+                operation: opName,
+                cause: recreateErr,
+            };
+            onExpired?.(event);
+            throw new CartRecoveryNotPossibleError(reason, recreateErr);
+        }
+        return result;
+    }
+}
+/**
+ * Build a per-shop-session runner that shares a recovery coordinator across
+ * concurrent operations and exposes an `onExpired` listener pattern.
+ */
+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) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listeners must not break recovery flow — swallow listener exceptions.
+            }
+        }
+    }
+    return {
+        cartClient,
+        cookieStore,
+        async execute(operation) {
+            const internalOpts = {
+                cartClient,
+                cookieStore,
+                operation,
+                ensureCart,
+                cookieMaxAge,
+                recoveryCoordinator: coordinator,
+                onExpired: emit,
+            };
+            return executeWithCartRecovery(internalOpts);
+        },
+        async getCart() {
+            const cartId = cookieStore.get();
+            if (!cartId)
+                return null;
+            try {
+                return await cartClient.get(cartId);
+            }
+            catch (err) {
+                if (isCartRecoverableError(err)) {
+                    cookieStore.clear();
+                    emit({
+                        reason: 'state-dependent',
+                        oldCartId: cartId,
+                        operation: 'getCart',
+                        cause: err,
+                    });
+                    return null;
+                }
+                throw err;
+            }
+        },
+        onExpired(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers for common recreate strategies (DRY for SDK + template code)
+// ---------------------------------------------------------------------------
+/**
+ * Build a `recreateAndRun` for any operation expressible as a single
+ * `cartCreate(input)` call. The fresh cart's outcome (`{ cart, warnings }`) is
+ * returned as `result`, matching what the equivalent post-create write would
+ * have returned — caller code stays uniform between happy and recovery paths.
+ *
+ * Use for: `addItems` (lines), `updateBuyerIdentity` (buyerIdentity),
+ * `setShippingAddress` (shippingAddress), `updateDiscountCodes` (discountCodes),
+ * `updateNote` (note), or any combination.
+ *
+ * @example
+ * ```typescript
+ * const operation: CartRecoveryOperation<CartMutationOutcome> = {
+ *   run: (cartId) => cartClient.addItems(cartId, lines),
+ *   recreateAndRun: recreateWithInput({ lines }),
+ *   name: 'addItems',
+ * };
+ * ```
+ */
+export function recreateWithInput(input) {
+    return async (cartClient) => {
+        const outcome = await cartClient.create(input);
+        return { cart: outcome.cart, result: outcome };
+    };
+}
+/**
+ * Specialized alias for the most common case (`addItems` recovery).
+ * Equivalent to `recreateWithInput({ lines, ...extraInput })`.
+ */
+export function recreateWithLines(lines, extraInput = {}) {
+    return recreateWithInput({ ...extraInput, lines });
+}

package/dist/core/index.d.ts

@@ -48,6 +48,8 @@ export { StorefrontError, ErrorCodes, type StorefrontErrorOptions } from './erro
 export { cacheNone, cacheShort, cacheLong, cachePrivate, cacheCustom, generateCacheControlHeader, type CacheOverrides, } from './cache';
 export { CartClient } from './cart/cart-client';
 export type { CartMutationOutcome, CartCompleteOutcome } from './cart/cart-client';
+export { CART_RECOVERABLE_ERROR_CODES, isCartRecoverableError, executeWithCartRecovery, createCartRecoveryRunner, CartRecoveryNotPossibleError, recreateWithInput, recreateWithLines, } from './cart/cart-recovery';
+export type { CartRecoverableErrorCode, CartCookieStore, CartRecoveryOperation, CartRecoveryFailureReason, CartExpiredEvent, CartRecoveryRunner, CreateCartRecoveryRunnerOptions, ExecuteWithCartRecoveryOptions, } from './cart/cart-recovery';
 export type { Cart, CartLine, CartLineEdge, CartLineConnection, ProductVariant, ProductVariantWeight, ImageThumbnail, PageInfo, AttributeSelection, CartLineCost, CartCost, CartBuyerIdentity, CartDiscountCode, CartDiscountAllocation, CartLineInput, CartLineUpdateInput, CartCreateInput, CartBuyerIdentityInput, CartAttributeSelectionInput, SelectedOption, Money, CartAddressInput, CartSetShippingAddressInput, CartSetBillingAddressInput, CartSelectShippingMethodInput, CartSelectPaymentMethodInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartUpdateGiftCardRecipientInput, CartCompleteInput, CartShippingMethod, CartAppliedGiftCard, CartSelectedPaymentMethod, PaymentMethodType, CartWarning, Order, PaymentInitiationFlow, PaymentErrorCode, PaymentSession, PaymentCreateInput, DiscountValidationResult, DiscountInfo, DiscountValidationError, DiscountErrorCode, DiscountApplicationType, } from './cart/types';
 export { AuthClient } from './auth/auth-client';
 export type { Customer, CustomerAccessToken, MailingAddress, AuthResult, CustomerCreateInput, } from './auth/types';

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}

package/dist/core/index.js

@@ -52,6 +52,8 @@ export { StorefrontError, ErrorCodes } from './errors';
 export { cacheNone, cacheShort, cacheLong, cachePrivate, cacheCustom, generateCacheControlHeader, } from './cache';
 // Cart client
 export { CartClient } from './cart/cart-client';
+// Cart recovery (stale cart auto-recovery — works without React)
+export { CART_RECOVERABLE_ERROR_CODES, isCartRecoverableError, executeWithCartRecovery, createCartRecoveryRunner, CartRecoveryNotPossibleError, recreateWithInput, recreateWithLines, } from './cart/cart-recovery';
 // Auth client
 export { AuthClient } from './auth/auth-client';
 // Helpers

package/dist/react/components/AddToCartButton.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `<AddToCartButton>` — minimal opinionated "add to cart" trigger that wires
+ * `useCartManager().addItem` to a `<button>` with loading state and error
+ * surfacing.
+ *
+ * Headless: no styling. Renders a button that:
+ *   - disables itself while the mutation is in flight (`aria-busy`),
+ *   - exposes the last error to assistive tech via a visually-hidden alert,
+ *   - invokes `onSuccess` / `onError` callbacks for consumer-side toasts
+ *     or analytics.
+ *
+ * The component does **not** subscribe to the global `onExpired` event — that
+ * is the consumer's responsibility (typically a single global toast). On
+ * stale-cart recovery the SDK swaps the cart transparently and this button
+ * just reports success.
+ *
+ * @example
+ * ```tsx
+ * <AddToCartButton variantId={variant.id} quantity={1}>
+ *   Add to cart
+ * </AddToCartButton>
+ * ```
+ */
+import { type ButtonHTMLAttributes, type ReactNode } from 'react';
+interface CartLineAttribute {
+    key: string;
+    value: string;
+}
+type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type' | 'onClick' | 'aria-busy' | 'onError'>;
+export interface AddToCartButtonProps extends ButtonProps {
+    /** Product variant identifier to add. */
+    variantId: string;
+    /** Quantity (default 1). */
+    quantity?: number;
+    /** Cart line attributes (custom options, gift wrap, etc.). */
+    attributes?: CartLineAttribute[];
+    /** Button label / contents. Defaults to "Add to cart". */
+    children?: ReactNode;
+    /** Called after the mutation succeeds with the updated cart summary. */
+    onSuccess?: (result: {
+        cartId: string;
+        totalQuantity: number;
+    }) => void;
+    /** Called when the mutation throws (does not bubble through React Error Boundary). */
+    onError?: (error: Error) => void;
+}
+export declare function AddToCartButton({ variantId, quantity, attributes, children, onSuccess, onError, disabled, ...buttonProps }: AddToCartButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=AddToCartButton.d.ts.map

package/dist/react/components/AddToCartButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AddToCartButton.d.ts","sourceRoot":"","sources":["../../../src/react/components/AddToCartButton.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAY,KAAK,oBAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG5E,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,KAAK,WAAW,GAAG,IAAI,CACrB,oBAAoB,CAAC,iBAAiB,CAAC,EAEvC,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAC7C,CAAC;AAEF,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,sFAAsF;IACtF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,QAAY,EACZ,UAAU,EACV,QAAQ,EACR,SAAS,EACT,OAAO,EACP,QAAQ,EACR,GAAG,WAAW,EACf,EAAE,oBAAoB,2CAqCtB"}

package/dist/react/components/AddToCartButton.js

@@ -0,0 +1,47 @@
+/**
+ * `<AddToCartButton>` — minimal opinionated "add to cart" trigger that wires
+ * `useCartManager().addItem` to a `<button>` with loading state and error
+ * surfacing.
+ *
+ * Headless: no styling. Renders a button that:
+ *   - disables itself while the mutation is in flight (`aria-busy`),
+ *   - exposes the last error to assistive tech via a visually-hidden alert,
+ *   - invokes `onSuccess` / `onError` callbacks for consumer-side toasts
+ *     or analytics.
+ *
+ * The component does **not** subscribe to the global `onExpired` event — that
+ * is the consumer's responsibility (typically a single global toast). On
+ * stale-cart recovery the SDK swaps the cart transparently and this button
+ * just reports success.
+ *
+ * @example
+ * ```tsx
+ * <AddToCartButton variantId={variant.id} quantity={1}>
+ *   Add to cart
+ * </AddToCartButton>
+ * ```
+ */
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { useCartManager } from '../hooks/use-cart-manager';
+export function AddToCartButton({ variantId, quantity = 1, attributes, children, onSuccess, onError, disabled, ...buttonProps }) {
+    const { addItem, isLoading } = useCartManager();
+    const [localError, setLocalError] = useState(null);
+    const handleClick = async () => {
+        setLocalError(null);
+        try {
+            const result = await addItem([{ variantId, quantity, attributes }]);
+            onSuccess?.({
+                cartId: result.cart.id,
+                totalQuantity: result.cart.totalQuantity,
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Failed to add to cart');
+            setLocalError(error);
+            onError?.(error);
+        }
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ...buttonProps, type: "button", onClick: handleClick, disabled: disabled || isLoading, "aria-busy": isLoading || undefined, children: children ?? 'Add to cart' }), localError && (_jsx("span", { role: "alert", style: { position: 'absolute', width: 1, height: 1, overflow: 'hidden', clip: 'rect(0 0 0 0)' }, children: localError.message }))] }));
+}

package/dist/react/components/CartCount.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `<CartCount>` — render the cart item count with screen-reader-friendly
+ * semantics (`aria-live="polite"`).
+ *
+ * Receives `count` explicitly rather than reading from a store — the SDK's
+ * cart store tracks `cartId`, not line totals (which come from a GraphQL
+ * query in the consumer). This keeps the component reusable across data
+ * layers (React Query, SWR, Apollo, custom fetcher).
+ *
+ * @example
+ * ```tsx
+ * const { data } = useCartQuery(cartId);
+ * <CartCount count={data?.totalQuantity ?? 0} />
+ * ```
+ */
+export interface CartCountProps {
+    /** Number of items in the cart. */
+    count: number;
+    /** Class name for styling. */
+    className?: string;
+    /**
+     * Custom formatter (e.g. localised pluralisation).
+     * Default: stringifies the count.
+     */
+    formatter?: (count: number) => string;
+    /**
+     * Optional label rendered after the count (e.g. "items"). Use a localised
+     * string from the consumer's i18n layer rather than hardcoding.
+     */
+    label?: string;
+    /** Hide entirely when count is zero (default `false`). */
+    hideWhenEmpty?: boolean;
+}
+export declare function CartCount({ count, className, formatter, label, hideWhenEmpty, }: CartCountProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=CartCount.d.ts.map