@doswiftly/storefront-sdk 11.0.0 → 11.2.0

package/dist/core/operations/cart.js

@@ -264,6 +264,18 @@ const CART_WARNING_FRAGMENT = `
     target
   }
 `;
+const PAYMENT_SESSION_FRAGMENT = `
+  fragment PaymentSession on PaymentSession {
+    id
+    orderId
+    flow
+    provider
+    redirectUrl
+    clientSecret
+    status
+    expiresAt
+  }
+`;
 // ---------------------------------------------------------------------------
 // Queries
 // ---------------------------------------------------------------------------
@@ -470,6 +482,22 @@ export const CART_COMPLETE = composeOperation(`
   ${USER_ERROR_FRAGMENT}
   ${CART_WARNING_FRAGMENT}
 `);
+/**
+ * paymentCreate — initiates a payment session for an order created by
+ * `cartComplete`. Call after checking `order.canCreatePayment`. Idempotent on
+ * the order — re-calling returns the existing still-valid session. Branch on
+ * `payment.flow` (redirect / embedded / instant) to launch the payment.
+ */
+export const PAYMENT_CREATE = composeOperation(`
+  mutation PaymentCreate($input: PaymentCreateInput!) {
+    paymentCreate(input: $input) {
+      payment { ...PaymentSession }
+      userErrors { ...UserError }
+    }
+  }
+  ${PAYMENT_SESSION_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`);
 /**
  * cartValidateDiscountCode Query — read-only preview discount applicability
  * (Decision D3). No cart side effects; storefront UI używa do inline feedback

package/dist/react/cookies.d.ts

@@ -23,6 +23,27 @@ export declare function setCookie(name: string, value: string, options?: {
  * Delete cookie (client-side only).
  */
 export declare function deleteCookie(name: string, path?: string): void;
+import type { CartCookieStore } from '../core/cart/cart-recovery';
+/**
+ * Build a browser-side `CartCookieStore` backed by `document.cookie`.
+ *
+ * SSR-safe: when `document` is unavailable (Node / Edge SSR) `get` returns null
+ * and `set`/`clear` are no-ops — the runner falls back to creating a cart on
+ * first client-side interaction.
+ *
+ * Defaults: `maxAge = CART_COOKIE_MAX_AGE` (30 days), `samesite=lax`, `path=/`,
+ * `secure` auto-detected from `location.protocol`. Pass per-call `maxAge` via
+ * `set(cartId, { maxAge })` if needed.
+ *
+ * @example
+ * ```tsx
+ * const runner = createCartRecoveryRunner({
+ *   cartClient,
+ *   cookieStore: createBrowserCartCookieStore(),
+ * });
+ * ```
+ */
+export declare function createBrowserCartCookieStore(): CartCookieStore;
 /**
  * Get preferred currency from cookie (async — works with Next.js cookies()).
  * Falls back to document.cookie on client.

package/dist/react/cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/react/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACpF,IAAI,CAON;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,IAAI,CAG3D;AAKD;;;GAGG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYvE"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/react/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACpF,IAAI,CAON;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,IAAI,CAG3D;AAID,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,CAQ9D;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYvE"}

package/dist/react/cookies.js

@@ -36,7 +36,35 @@ export function deleteCookie(name, path = '/') {
     document.cookie = `${name}=;max-age=0;path=${path}`;
 }
 import { CURRENCY_COOKIE_NAME } from '../core/currency/cookie-config';
-import { CART_COOKIE_NAME } from '../core/cart/cookie-config';
+import { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from '../core/cart/cookie-config';
+/**
+ * Build a browser-side `CartCookieStore` backed by `document.cookie`.
+ *
+ * SSR-safe: when `document` is unavailable (Node / Edge SSR) `get` returns null
+ * and `set`/`clear` are no-ops — the runner falls back to creating a cart on
+ * first client-side interaction.
+ *
+ * Defaults: `maxAge = CART_COOKIE_MAX_AGE` (30 days), `samesite=lax`, `path=/`,
+ * `secure` auto-detected from `location.protocol`. Pass per-call `maxAge` via
+ * `set(cartId, { maxAge })` if needed.
+ *
+ * @example
+ * ```tsx
+ * const runner = createCartRecoveryRunner({
+ *   cartClient,
+ *   cookieStore: createBrowserCartCookieStore(),
+ * });
+ * ```
+ */
+export function createBrowserCartCookieStore() {
+    return {
+        get: () => getCookie(CART_COOKIE_NAME),
+        set: (cartId, options) => {
+            setCookie(CART_COOKIE_NAME, cartId, { maxAge: options?.maxAge ?? CART_COOKIE_MAX_AGE });
+        },
+        clear: () => deleteCookie(CART_COOKIE_NAME),
+    };
+}
 /**
  * Get preferred currency from cookie (async — works with Next.js cookies()).
  * Falls back to document.cookie on client.

package/dist/react/hooks/use-cart-manager.d.ts

@@ -1,31 +1,57 @@
 /**
- * useCartManager — wraps CartClient with cart ID persistence + loading states.
+ * useCartManager — DX-first cart hook with automatic stale-cart recovery.
  *
- * Auto-creates cart on first add. CartId persisted in cookie (SSR/edge visible).
- * Does NOT use React Query — plain async + useState.
- * Template wraps in useMutation() if React Query features are needed.
+ * Wraps `CartClient` with cookie persistence + per-operation recovery strategy.
+ * Built on top of `createCartRecoveryRunner` from the core layer, so the same
+ * recovery semantics work for non-React consumers (Vue/Svelte/CLI/mobile).
+ *
+ * Per-operation strategy:
+ *
+ * | Operation               | Strategy                              | Why                                           |
+ * | ----------------------- | ------------------------------------- | --------------------------------------------- |
+ * | `addItem`               | Auto-replay (atomic `cartCreate`)     | Storefront expects "add to cart" always works |
+ * | `updateBuyerIdentity`   | Auto-replay                           | User just typed email/phone — keep it         |
+ * | `setShippingAddress`    | Auto-replay                           | User just typed address — keep it             |
+ * | `updateDiscountCodes`   | Auto-replay                           | Coupon valid independently of cart            |
+ * | `updateNote`            | Auto-replay                           | Stateless / idempotent                        |
+ * | `updateItem`            | Bail + `cart-expired` event           | `lineId` refers to a line in the dead cart    |
+ * | `removeItem`            | Bail + `cart-expired` event           | jw.                                           |
+ *
+ * On bail the runner clears the cookie and calls every `onExpired` listener
+ * with a `CartExpiredEvent`. UI subscribes once globally and shows a toast /
+ * banner — caller code never writes `try / catch` per mutation.
+ *
+ * Auto-creates cart on first add. Cart id persisted in `cart-id` cookie
+ * (SSR/edge visible, 30 days, samesite=lax).
  *
  * @example
  * ```tsx
- * const { addItem, updateQuantity, removeItem, isLoading } = useCartManager();
+ * function CartUI() {
+ *   const { addItem, onExpired } = useCartManager();
+ *
+ *   useEffect(() => onExpired(() => toast('Koszyk wygasł, dodaj produkty ponownie')), [onExpired]);
  *
- * await addItem([{ variantId: 'variant-123', quantity: 1 }]);
+ *   return <button onClick={() => addItem([{ variantId, quantity: 1 }])}>Add</button>;
+ * }
  * ```
  */
-import type { Cart, CartLineInput, CartLineUpdateInput } from '../../core/cart/types';
+import type { Cart, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput } from '../../core/cart/types';
 import type { CartMutationOutcome } from '../../core/cart/cart-client';
-export declare function useCartManager(): {
+import { type CartExpiredEvent } from '../../core/cart/cart-recovery';
+export interface UseCartManagerResult {
     getCart: () => Promise<Cart | null>;
-    addItem: (lines: CartLineInput[], options?: {
-        forceNewCart?: boolean;
-    }) => Promise<CartMutationOutcome>;
-    updateItem: (lines: CartLineUpdateInput[]) => Promise<CartMutationOutcome>;
-    removeItem: (lineIds: string[]) => Promise<CartMutationOutcome>;
+    getCartId: () => string | null;
+    addItem: (lines: CartLineInput[]) => Promise<CartMutationOutcome>;
+    updateBuyerIdentity: (buyerIdentity: CartBuyerIdentityInput) => Promise<CartMutationOutcome>;
+    setShippingAddress: (address: CartAddressInput) => Promise<CartMutationOutcome>;
     updateDiscountCodes: (codes: string[]) => Promise<CartMutationOutcome>;
     updateNote: (note: string) => Promise<CartMutationOutcome>;
+    updateItem: (lines: CartLineUpdateInput[]) => Promise<CartMutationOutcome>;
+    removeItem: (lineIds: string[]) => Promise<CartMutationOutcome>;
     clearCart: () => void;
-    getCartId: () => string | null;
+    onExpired: (listener: (event: CartExpiredEvent) => void) => () => void;
     isLoading: boolean;
     error: string | null;
-};
+}
+export declare function useCartManager(): UseCartManagerResult;
 //# sourceMappingURL=use-cart-manager.d.ts.map

package/dist/react/hooks/use-cart-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cart-manager.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAwBvE,wBAAgB,cAAc;mBAiCU,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;qBAoBjD,aAAa,EAAE,YACZ;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KACnC,OAAO,CAAC,mBAAmB,CAAC;wBAyBtB,mBAAmB,EAAE,KAC3B,OAAO,CAAC,mBAAmB,CAAC;0BAuBgB,MAAM,EAAE,KAAG,OAAO,CAAC,mBAAmB,CAAC;iCAuBhC,MAAM,EAAE,KAAG,OAAO,CAAC,mBAAmB,CAAC;uBAoBjD,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAAC;;qBA2B/C,MAAM,GAAG,IAAI;;;EAiBhD"}
+{"version":3,"file":"use-cart-manager.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAMH,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,oBAAoB;IAEnC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAG/B,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClE,mBAAmB,EAAE,CAAC,aAAa,EAAE,sBAAsB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7F,kBAAkB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChF,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAG3D,UAAU,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3E,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAGhE,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAGvE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,cAAc,IAAI,oBAAoB,CA6KrD"}

package/dist/react/hooks/use-cart-manager.js

@@ -1,221 +1,130 @@
 /**
- * useCartManager — wraps CartClient with cart ID persistence + loading states.
+ * useCartManager — DX-first cart hook with automatic stale-cart recovery.
  *
- * Auto-creates cart on first add. CartId persisted in cookie (SSR/edge visible).
- * Does NOT use React Query — plain async + useState.
- * Template wraps in useMutation() if React Query features are needed.
+ * Wraps `CartClient` with cookie persistence + per-operation recovery strategy.
+ * Built on top of `createCartRecoveryRunner` from the core layer, so the same
+ * recovery semantics work for non-React consumers (Vue/Svelte/CLI/mobile).
+ *
+ * Per-operation strategy:
+ *
+ * | Operation               | Strategy                              | Why                                           |
+ * | ----------------------- | ------------------------------------- | --------------------------------------------- |
+ * | `addItem`               | Auto-replay (atomic `cartCreate`)     | Storefront expects "add to cart" always works |
+ * | `updateBuyerIdentity`   | Auto-replay                           | User just typed email/phone — keep it         |
+ * | `setShippingAddress`    | Auto-replay                           | User just typed address — keep it             |
+ * | `updateDiscountCodes`   | Auto-replay                           | Coupon valid independently of cart            |
+ * | `updateNote`            | Auto-replay                           | Stateless / idempotent                        |
+ * | `updateItem`            | Bail + `cart-expired` event           | `lineId` refers to a line in the dead cart    |
+ * | `removeItem`            | Bail + `cart-expired` event           | jw.                                           |
+ *
+ * On bail the runner clears the cookie and calls every `onExpired` listener
+ * with a `CartExpiredEvent`. UI subscribes once globally and shows a toast /
+ * banner — caller code never writes `try / catch` per mutation.
+ *
+ * Auto-creates cart on first add. Cart id persisted in `cart-id` cookie
+ * (SSR/edge visible, 30 days, samesite=lax).
  *
  * @example
  * ```tsx
- * const { addItem, updateQuantity, removeItem, isLoading } = useCartManager();
+ * function CartUI() {
+ *   const { addItem, onExpired } = useCartManager();
+ *
+ *   useEffect(() => onExpired(() => toast('Koszyk wygasł, dodaj produkty ponownie')), [onExpired]);
  *
- * await addItem([{ variantId: 'variant-123', quantity: 1 }]);
+ *   return <button onClick={() => addItem([{ variantId, quantity: 1 }])}>Add</button>;
+ * }
  * ```
  */
 'use client';
-import { useState, useCallback } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 import { useStorefrontClientContext } from '../providers/storefront-client-provider';
-import { StorefrontError } from '../../core/errors';
-// ---------------------------------------------------------------------------
-// Cart ID persistence (cookie — SSR/edge visible)
-// ---------------------------------------------------------------------------
-function getCartIdFromCookie() {
-    if (typeof document === 'undefined')
-        return null;
-    const match = document.cookie.match(/(?:^|;\s*)cart-id=([^;]*)/);
-    return match ? decodeURIComponent(match[1]) : null;
-}
-function setCartIdCookie(cartId) {
-    if (typeof document === 'undefined')
-        return;
-    const maxAge = 30 * 24 * 60 * 60; // 30 days
-    document.cookie = `cart-id=${encodeURIComponent(cartId)};max-age=${maxAge};path=/;samesite=lax`;
-}
-function clearCartIdCookie() {
-    if (typeof document === 'undefined')
-        return;
-    document.cookie = 'cart-id=;max-age=0;path=/';
-}
+import { createCartRecoveryRunner, recreateWithInput, } from '../../core/cart/cart-recovery';
+import { createBrowserCartCookieStore } from '../cookies';
 export function useCartManager() {
     const { cartClient } = useStorefrontClientContext();
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
-    /**
-     * Get existing cart ID from cookie or create a new cart.
-     */
-    const getOrCreateCartId = useCallback(async (forceNew = false) => {
-        if (!forceNew) {
-            const existing = getCartIdFromCookie();
-            if (existing)
-                return existing;
-        }
-        const { cart } = await cartClient.create();
-        setCartIdCookie(cart.id);
-        return cart.id;
-    }, [cartClient]);
-    /**
-     * Check if error indicates cart not found (expired).
-     */
-    const isCartExpired = (err) => {
-        if (err instanceof StorefrontError) {
-            return err.message.toLowerCase().includes('cart not found') ||
-                err.message.toLowerCase().includes('cart does not exist');
-        }
-        return false;
-    };
-    /**
-     * Fetch current cart. Returns null if no cart exists.
-     */
-    const getCart = useCallback(async () => {
-        const cartId = getCartIdFromCookie();
-        if (!cartId)
-            return null;
-        try {
-            return await cartClient.get(cartId);
-        }
-        catch (err) {
-            if (isCartExpired(err)) {
-                clearCartIdCookie();
-                return null;
-            }
-            throw err;
-        }
-    }, [cartClient]);
-    /**
-     * Add items to cart. Creates cart if needed.
-     * On expired cart, clears cookie, creates new cart, retries once.
-     */
-    const addItem = useCallback(async (lines, options) => {
+    // Cookie store is stateless — keep one instance per hook mount.
+    const cookieStore = useMemo(() => createBrowserCartCookieStore(), []);
+    // Recovery runner is bound to cartClient identity (changes only on provider
+    // re-mount). Sharing one runner per hook gives concurrent operations a single
+    // recovery coordinator (Phase 0 mutex).
+    const runner = useMemo(() => createCartRecoveryRunner({ cartClient, cookieStore }), [cartClient, cookieStore]);
+    // Subscribe to cart-expired events. The returned unsubscribe function is
+    // bound to the current runner identity — wrap calls in
+    // `useEffect(() => onExpired(...), [onExpired])` so React re-subscribes when
+    // the provider (and thus the runner) remounts.
+    const onExpired = useCallback((listener) => runner.onExpired(listener), [runner]);
+    // Generic mutation wrapper — sets loading + error state, delegates recovery
+    // semantics to the runner.
+    const wrapMutation = useCallback(async (run, failureFallbackMessage) => {
         setError(null);
         setIsLoading(true);
         try {
-            const cartId = await getOrCreateCartId(options?.forceNewCart);
-            return await cartClient.addItems(cartId, lines);
+            return await run();
         }
         catch (err) {
-            if (isCartExpired(err) && !options?.forceNewCart) {
-                clearCartIdCookie();
-                return addItem(lines, { forceNewCart: true });
-            }
-            const message = err instanceof Error ? err.message : 'Failed to add to cart';
-            setError(message);
+            setError(err instanceof Error ? err.message : failureFallbackMessage);
             throw err;
         }
         finally {
             setIsLoading(false);
         }
-    }, [cartClient, getOrCreateCartId]);
-    /**
-     * Update line items (quantity, attributes).
-     */
-    const updateItem = useCallback(async (lines) => {
-        setError(null);
-        setIsLoading(true);
-        try {
-            const cartId = getCartIdFromCookie();
-            if (!cartId)
-                throw new Error('No cart found');
-            return await cartClient.updateItems(cartId, lines);
-        }
-        catch (err) {
-            if (isCartExpired(err)) {
-                clearCartIdCookie();
-            }
-            const message = err instanceof Error ? err.message : 'Failed to update cart';
-            setError(message);
-            throw err;
-        }
-        finally {
-            setIsLoading(false);
-        }
-    }, [cartClient]);
-    /**
-     * Remove items by line IDs.
-     */
-    const removeItem = useCallback(async (lineIds) => {
-        setError(null);
-        setIsLoading(true);
-        try {
-            const cartId = getCartIdFromCookie();
-            if (!cartId)
-                throw new Error('No cart found');
-            return await cartClient.removeItems(cartId, lineIds);
-        }
-        catch (err) {
-            if (isCartExpired(err)) {
-                clearCartIdCookie();
-            }
-            const message = err instanceof Error ? err.message : 'Failed to remove from cart';
-            setError(message);
-            throw err;
-        }
-        finally {
-            setIsLoading(false);
-        }
-    }, [cartClient]);
-    /**
-     * Update discount codes (replaces all existing).
-     */
-    const updateDiscountCodes = useCallback(async (codes) => {
-        setError(null);
-        setIsLoading(true);
-        try {
-            const cartId = getCartIdFromCookie();
-            if (!cartId)
-                throw new Error('No cart found');
-            return await cartClient.updateDiscountCodes(cartId, codes);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : 'Failed to update discount codes';
-            setError(message);
-            throw err;
-        }
-        finally {
-            setIsLoading(false);
-        }
-    }, [cartClient]);
-    /**
-     * Update cart note.
-     */
-    const updateNote = useCallback(async (note) => {
-        setError(null);
-        setIsLoading(true);
-        try {
-            const cartId = getCartIdFromCookie();
-            if (!cartId)
-                throw new Error('No cart found');
-            return await cartClient.updateNote(cartId, note);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : 'Failed to update note';
-            setError(message);
-            throw err;
-        }
-        finally {
-            setIsLoading(false);
-        }
-    }, [cartClient]);
-    /**
-     * Clear cart — removes cookie.
-     */
-    const clearCart = useCallback(() => {
-        clearCartIdCookie();
-    }, []);
-    /**
-     * Get current cart ID from cookie (if exists).
-     */
-    const getCartId = useCallback(() => {
-        return getCartIdFromCookie();
     }, []);
+    // --- Read ---
+    const getCart = useCallback(() => runner.getCart(), [runner]);
+    const getCartId = useCallback(() => cookieStore.get(), [cookieStore]);
+    // --- Auto-replay mutations ---
+    const addItem = useCallback((lines) => wrapMutation(() => runner.execute({
+        name: 'addItem',
+        run: (cartId) => cartClient.addItems(cartId, lines),
+        recreateAndRun: recreateWithInput({ lines }),
+    }), 'Failed to add to cart'), [runner, cartClient, wrapMutation]);
+    const updateBuyerIdentity = useCallback((buyerIdentity) => wrapMutation(() => runner.execute({
+        name: 'updateBuyerIdentity',
+        run: (cartId) => cartClient.updateBuyerIdentity(cartId, buyerIdentity),
+        recreateAndRun: recreateWithInput({ buyerIdentity }),
+    }), 'Failed to update buyer identity'), [runner, cartClient, wrapMutation]);
+    const setShippingAddress = useCallback((address) => wrapMutation(() => runner.execute({
+        name: 'setShippingAddress',
+        run: (cartId) => cartClient.setShippingAddress({ cartId, address }),
+        recreateAndRun: recreateWithInput({ shippingAddress: address }),
+    }), 'Failed to set shipping address'), [runner, cartClient, wrapMutation]);
+    const updateDiscountCodes = useCallback((codes) => wrapMutation(() => runner.execute({
+        name: 'updateDiscountCodes',
+        run: (cartId) => cartClient.updateDiscountCodes(cartId, codes),
+        recreateAndRun: recreateWithInput({ discountCodes: codes }),
+    }), 'Failed to update discount codes'), [runner, cartClient, wrapMutation]);
+    const updateNote = useCallback((note) => wrapMutation(() => runner.execute({
+        name: 'updateNote',
+        run: (cartId) => cartClient.updateNote(cartId, note),
+        recreateAndRun: recreateWithInput({ note }),
+    }), 'Failed to update note'), [runner, cartClient, wrapMutation]);
+    // --- Bail-on-stale mutations (no recreateAndRun — fires onExpired + throws) ---
+    const updateItem = useCallback((lines) => wrapMutation(() => runner.execute({
+        name: 'updateItem',
+        run: (cartId) => cartClient.updateItems(cartId, lines),
+    }), 'Failed to update cart'), [runner, cartClient, wrapMutation]);
+    const removeItem = useCallback((lineIds) => wrapMutation(() => runner.execute({
+        name: 'removeItem',
+        run: (cartId) => cartClient.removeItems(cartId, lineIds),
+    }), 'Failed to remove from cart'), [runner, cartClient, wrapMutation]);
+    // --- Lifecycle ---
+    const clearCart = useCallback(() => {
+        cookieStore.clear();
+    }, [cookieStore]);
     return {
         getCart,
+        getCartId,
         addItem,
-        updateItem,
-        removeItem,
+        updateBuyerIdentity,
+        setShippingAddress,
         updateDiscountCodes,
         updateNote,
+        updateItem,
+        removeItem,
         clearCart,
-        getCartId,
+        onExpired,
         isLoading,
         error,
     };

package/dist/react/index.d.ts

@@ -28,7 +28,7 @@ export type { LanguageStore } from './stores/language.store';
 export type { ShopConfig } from './types/shop-config';
 export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './stores/currency.store';
 export { selectLanguage, selectDefaultLanguage, selectSupportedLanguages, selectLanguageIsLoaded } from './stores/language.store';
-export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync, getCartIdFromCookieAsync } from './cookies';
+export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync, getCartIdFromCookieAsync, createBrowserCartCookieStore, } from './cookies';
 export { useBotProtection } from './hooks/use-bot-protection';
 export { useHydrated } from './hooks/use-hydrated';
 export { useDebouncedValue } from './hooks/use-debounced-value';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,KAAK,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AACtH,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAG7F,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9H,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACxH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGlI,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAGrH,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,KAAK,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AACtH,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAG7F,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9H,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACxH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGlI,OAAO,EACL,SAAS,EACT,SAAS,EACT,YAAY,EACZ,0BAA0B,EAC1B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/react/index.js

@@ -29,7 +29,7 @@ export { useLanguageStore, useLanguageStoreApi } from './stores/store-context';
 export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './stores/currency.store';
 export { selectLanguage, selectDefaultLanguage, selectSupportedLanguages, selectLanguageIsLoaded } from './stores/language.store';
 // Cookie utilities
-export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync, getCartIdFromCookieAsync } from './cookies';
+export { getCookie, setCookie, deleteCookie, getCurrencyFromCookieAsync, getCartIdFromCookieAsync, createBrowserCartCookieStore, } from './cookies';
 // Bot protection
 export { useBotProtection } from './hooks/use-bot-protection';
 // Generic hooks

package/dist/react/stores/cart.store.d.ts

@@ -1,27 +1,50 @@
 /**
- * Cart Store — DI-based cart state management with cookie persistence.
+ * Cart Store — DI-based cart state management with cookie persistence and
+ * automatic stale-cart recovery.
  *
- * SDK orchestrates cart lifecycle (init, mutations, error handling).
- * Template provides CartActions implementation via DI (getActions getter).
- * Cart ID persisted in cookie (SSR/edge visible) — follows currency store pattern.
+ * SDK orchestrates cart lifecycle (init, mutations, recovery, error handling).
+ * Template provides `CartActions` via DI (getActions getter). Cart id persisted
+ * in cookie (SSR/edge visible) — follows currency store pattern.
+ *
+ * Per-operation recovery strategy (DX-first — caller never thinks about it):
+ *
+ *   - **`addToCart`** auto-replays on stale-cart errors. If the template
+ *     implements the optional `actions.createCartWithLines`, recovery is atomic
+ *     (single `cartCreate({ lines })` round trip). Otherwise falls back to
+ *     `createCart()` + `addLines()` (2 round trips, same end result).
+ *
+ *   - **`updateQuantity`** and **`removeFromCart`** bail on stale-cart errors:
+ *     local cart id is cleared, `onExpired` listeners fire, error surfaces via
+ *     `onMutationError`. Replaying on a fresh empty cart would silently lose
+ *     user intent (the lineId no longer exists).
+ *
+ * Stale-cart detection inspects `err.userErrors[].code` (CART_NOT_FOUND /
+ * ALREADY_COMPLETED) — locale-proof, see {@link isCartRecoverableError}.
  *
  * @example
  * ```typescript
  * import { createCartStore, type CartActions } from '@doswiftly/storefront-sdk/react';
  *
  * const actions: CartActions = {
- *   fetchCart: async (cartId) => api.getCart(cartId),
- *   createCart: async () => api.createCart().then(c => c.id),
- *   addLines: async (cartId, lines) => api.addLines(cartId, lines),
- *   updateLines: async (cartId, lines) => api.updateLines(cartId, lines),
- *   removeLines: async (cartId, lineIds) => api.removeLines(cartId, lineIds),
+ *   fetchCart: (id) => api.getCart(id),
+ *   createCart: () => api.createCart().then(c => c.id),
+ *   addLines: (id, lines) => api.addLines(id, lines),
+ *   updateLines: (id, lines) => api.updateLines(id, lines),
+ *   removeLines: (id, ids) => api.removeLines(id, ids),
+ *   // optional — enables atomic add-to-cart recovery
+ *   createCartWithLines: (lines) => api.cartCreate({ lines }),
  * };
  *
- * const store = createCartStore({ getActions: () => actions });
+ * const store = createCartStore({
+ *   getActions: () => actions,
+ *   onExpired: (e) => toast.error('Koszyk wygasł, dodaj produkty ponownie'),
+ * });
  * ```
  */
 import type { CartLineInput, CartLineUpdateInput } from '../../core/cart/types';
+import { type CartExpiredEvent } from '../../core/cart/cart-recovery';
 export type { CartLineInput, CartLineUpdateInput } from '../../core/cart/types';
+export type { CartExpiredEvent } from '../../core/cart/cart-recovery';
 /** Minimal cart data returned by DI actions. */
 export interface CartData {
     id: string;
@@ -39,6 +62,16 @@ export interface CartActions {
     updateLines: (cartId: string, lines: CartLineUpdateInput[]) => Promise<CartData>;
     /** Remove line items. Return updated cart or throw. */
     removeLines: (cartId: string, lineIds: string[]) => Promise<CartData>;
+    /**
+     * Optional — atomic create-with-lines for stale-cart recovery. When provided,
+     * the store recovers from `CART_NOT_FOUND` / `ALREADY_COMPLETED` in a single
+     * `cartCreate({ lines })` round trip. When omitted, store falls back to
+     * `createCart()` + `addLines()` (2 round trips, identical outcome).
+     *
+     * Wire this when your GraphQL `cartCreate` mutation accepts an initial
+     * `lines` payload (DoSwiftly Storefront API does).
+     */
+    createCartWithLines?: (lines: CartLineInput[]) => Promise<CartData>;
 }
 /** Action names passed to mutation callbacks. */
 export type CartMutationAction = 'initCart' | 'addToCart' | 'updateQuantity' | 'removeFromCart';
@@ -49,6 +82,20 @@ export interface CartStoreConfig {
     onMutationSuccess?: (action: CartMutationAction, cart: CartData) => void;
     /** Called on mutation error. */
     onMutationError?: (action: CartMutationAction, error: unknown) => void;
+    /**
+     * Called when a stale-cart event terminates an operation:
+     *
+     *   - `state-dependent` — bail-on-stale operation (`updateQuantity`,
+     *     `removeFromCart`) cannot be safely replayed on a new cart.
+     *   - `recreate-failed` — recovery attempted but creating the replacement
+     *     cart failed (network / backend error).
+     *   - `retry-also-failed` — replacement cart also rejected by backend
+     *     (rare; usually indicates a backend race / bug).
+     *
+     * Typical UI usage: subscribe once globally and surface a toast / banner
+     * inviting the user to add products again.
+     */
+    onExpired?: (event: CartExpiredEvent) => void;
 }
 export interface CartState {
     cartId: string | null;