@doswiftly/storefront-sdk 11.1.0 → 11.3.1

package/dist/react/hooks/use-auth.js

@@ -1,153 +1,36 @@
 /**
- * useAuth — wraps AuthClient + updates auth store.
+ * useAuth — convenience facade composing `useLogin`, `useLogout`, and
+ * `useRefreshToken`. Preserves the pre-11.2 API for backward compatibility.
  *
- * Centralizes login/logout/renew with dual-layer persistence:
- * - httpOnly cookie (for SSR/middleware) — via onSetToken/onClearToken callbacks
- * - Zustand store (for client-side state)
+ * **Prefer the focused hooks** in new code — they tree-shake better, isolate
+ * state, and keep dependency arrays smaller:
  *
- * Does NOT use React Query — plain async + store updates.
- * Template can wrap in useMutation() if React Query features are needed.
- *
- * @example
  * ```tsx
- * const { login, logout, isLoading } = useAuth();
+ * // Smaller bundle, single-responsibility:
+ * const { login, isLoggingIn } = useLogin({ onSetToken });
+ * const { logout } = useLogout({ onClearToken });
  *
- * const result = await login('user@example.com', 'password');
- * if (result.success) router.push('/account');
+ * // Convenience aggregator (legacy / mixed flows):
+ * const { login, logout, refreshToken, isLoading } = useAuth({ onSetToken, onClearToken });
  * ```
+ *
+ * Centralizes dual-layer persistence:
+ *   - httpOnly cookie (for SSR/middleware) — via `onSetToken`/`onClearToken`
+ *     callbacks that hit your BFF route handlers
+ *   - Zustand auth store (for client-side state).
  */
 'use client';
-import { useState, useCallback } from 'react';
-import { useStorefrontClientContext } from '../providers/storefront-client-provider';
-import { useAuthStore, useAuthStoreApi } from '../stores/store-context';
-import { StorefrontError } from '../../core/errors';
+import { useLogin } from './use-login';
+import { useLogout } from './use-logout';
+import { useRefreshToken } from './use-refresh-token';
 export function useAuth(options = {}) {
-    const { authClient } = useStorefrontClientContext();
-    const { setAuth, clearAuth } = useAuthStore();
-    const authStore = useAuthStoreApi();
-    const [isLoggingIn, setIsLoggingIn] = useState(false);
-    const [isLoggingOut, setIsLoggingOut] = useState(false);
-    const [isRefreshingToken, setIsRenewingToken] = useState(false);
-    const [error, setError] = useState(null);
-    const login = useCallback(async (email, password) => {
-        setError(null);
-        setIsLoggingIn(true);
-        try {
-            const result = await authClient.login(email, password);
-            // Set httpOnly cookie
-            if (options.onSetToken) {
-                await options.onSetToken(result.accessToken);
-            }
-            // Fetch customer data and set store
-            try {
-                const customer = await authClient.getCustomer();
-                if (customer) {
-                    setAuth({
-                        id: customer.id,
-                        email: customer.email,
-                        firstName: customer.firstName ?? undefined,
-                        lastName: customer.lastName ?? undefined,
-                        phone: customer.phone ?? undefined,
-                    }, result.accessToken);
-                }
-                else {
-                    setAuth({ id: '', email }, result.accessToken);
-                }
-            }
-            catch {
-                // Customer fetch failed — store minimal data
-                setAuth({ id: '', email }, result.accessToken);
-            }
-            return {
-                success: true,
-                userErrors: [],
-                accessToken: result.accessToken,
-                expiresAt: result.expiresAt,
-            };
-        }
-        catch (err) {
-            if (err instanceof StorefrontError && err.hasUserErrors) {
-                return {
-                    success: false,
-                    userErrors: err.userErrors.map((e) => ({
-                        message: e.message,
-                        field: e.field,
-                    })),
-                };
-            }
-            const message = err instanceof Error ? err.message : 'Login failed';
-            setError(message);
-            return { success: false, userErrors: [{ message }] };
-        }
-        finally {
-            setIsLoggingIn(false);
-        }
-    }, [authClient, setAuth, options]);
-    const logout = useCallback(async () => {
-        setError(null);
-        setIsLoggingOut(true);
-        try {
-            // Auth context resolved server-side from cookie/Bearer — no token arg needed
-            await authClient.logout();
-            // Clear httpOnly cookie
-            if (options.onClearToken) {
-                await options.onClearToken();
-            }
-            clearAuth();
-            return { success: true, userErrors: [] };
-        }
-        catch (err) {
-            // Even on error, clear local state
-            clearAuth();
-            const message = err instanceof Error ? err.message : 'Logout failed';
-            setError(message);
-            return { success: false, userErrors: [{ message }] };
-        }
-        finally {
-            setIsLoggingOut(false);
-        }
-    }, [authClient, clearAuth, options, authStore]);
-    const refreshToken = useCallback(async () => {
-        setError(null);
-        setIsRenewingToken(true);
-        try {
-            // Auth context resolved server-side from cookie/Bearer — no token arg needed.
-            // If no active session, backend will return 401 and refreshToken throws.
-            const result = await authClient.refreshToken();
-            // Update httpOnly cookie
-            if (options.onSetToken) {
-                await options.onSetToken(result.accessToken);
-            }
-            // Update store (keep customer data, update token)
-            const currentCustomer = authStore.getState().customer;
-            if (currentCustomer) {
-                setAuth(currentCustomer, result.accessToken);
-            }
-            return {
-                success: true,
-                userErrors: [],
-                accessToken: result.accessToken,
-                expiresAt: result.expiresAt,
-            };
-        }
-        catch (err) {
-            if (err instanceof StorefrontError && err.hasUserErrors) {
-                return {
-                    success: false,
-                    userErrors: err.userErrors.map((e) => ({
-                        message: e.message,
-                        field: e.field,
-                    })),
-                };
-            }
-            const message = err instanceof Error ? err.message : 'Token renewal failed';
-            setError(message);
-            return { success: false, userErrors: [{ message }] };
-        }
-        finally {
-            setIsRenewingToken(false);
-        }
-    }, [authClient, setAuth, options, authStore]);
+    const { login, isLoggingIn, error: loginError } = useLogin(options);
+    const { logout, isLoggingOut, error: logoutError } = useLogout(options);
+    const { refreshToken, isRefreshingToken, error: refreshError } = useRefreshToken(options);
+    // Aggregate the most-recent error across the three flows. Each focused hook
+    // tracks its own error independently, but legacy consumers expect a single
+    // `error` field — surface whichever is non-null (priority: login > logout > refresh).
+    const error = loginError ?? logoutError ?? refreshError;
     return {
         login,
         logout,

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

@@ -1,31 +1,91 @@
 /**
- * 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';
+/**
+ * Names of mutations exposed by the hook — narrows `status.operation` for
+ * exhaustive consumer-side switching (e.g. operation-specific spinners).
+ */
+export type CartManagerOperation = 'addItem' | 'updateItem' | 'removeItem' | 'updateBuyerIdentity' | 'setShippingAddress' | 'updateDiscountCodes' | 'updateNote';
+/**
+ * Tagged union of cart mutation lifecycle states. Lets callers do exhaustive
+ * switching without remembering which boolean flag pairs with which:
+ *
+ * ```tsx
+ * const { status } = useCartManager();
+ * if (status.type === 'loading') return <Spinner label={status.operation} />;
+ * if (status.type === 'error') return <ErrorBanner error={status.error} />;
+ * // narrowed here: status.type ∈ { 'idle', 'success' }
+ * ```
+ *
+ * `idle` is the initial state and the state after `clearCart()`.
+ */
+export type CartManagerStatus = {
+    type: 'idle';
+} | {
+    type: 'loading';
+    operation: CartManagerOperation;
+} | {
+    type: 'error';
+    operation: CartManagerOperation;
+    error: Error;
+} | {
+    type: 'success';
+    operation: CartManagerOperation;
+};
+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;
+    status: CartManagerStatus;
+    /** `true` when status.type === 'loading'. */
     isLoading: boolean;
+    /** Error message when status.type === 'error', otherwise null. */
     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;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,qBAAqB,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,YAAY,CAAC;AAEjB;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,oBAAoB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEzD,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,MAAM,EAAE,iBAAiB,CAAC;IAG1B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,cAAc,IAAI,oBAAoB,CA0LrD"}

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

@@ -1,221 +1,133 @@
 /**
- * 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();
  *
- * await addItem([{ variantId: 'variant-123', quantity: 1 }]);
+ *   useEffect(() => onExpired(() => toast('Koszyk wygasł, dodaj produkty ponownie')), [onExpired]);
+ *
+ *   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) => {
-        setError(null);
-        setIsLoading(true);
-        try {
-            const cartId = await getOrCreateCartId(options?.forceNewCart);
-            return await cartClient.addItems(cartId, lines);
-        }
-        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);
-            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);
+    const [status, setStatus] = useState({ type: 'idle' });
+    // 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 — drives the tagged-union status. Delegates
+    // recovery semantics to the runner (which fires onExpired separately).
+    const wrapMutation = useCallback(async (operation, run, failureFallbackMessage) => {
+        setStatus({ type: 'loading', operation });
         try {
-            const cartId = getCartIdFromCookie();
-            if (!cartId)
-                throw new Error('No cart found');
-            return await cartClient.removeItems(cartId, lineIds);
+            const result = await run();
+            setStatus({ type: 'success', operation });
+            return result;
         }
         catch (err) {
-            if (isCartExpired(err)) {
-                clearCartIdCookie();
-            }
-            const message = err instanceof Error ? err.message : 'Failed to remove from cart';
-            setError(message);
+            const error = err instanceof Error ? err : new Error(failureFallbackMessage);
+            setStatus({ type: 'error', operation, error });
             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('addItem', () => 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('updateBuyerIdentity', () => 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('setShippingAddress', () => 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('updateDiscountCodes', () => 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('updateNote', () => 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('updateItem', () => runner.execute({
+        name: 'updateItem',
+        run: (cartId) => cartClient.updateItems(cartId, lines),
+    }), 'Failed to update cart'), [runner, cartClient, wrapMutation]);
+    const removeItem = useCallback((lineIds) => wrapMutation('removeItem', () => runner.execute({
+        name: 'removeItem',
+        run: (cartId) => cartClient.removeItems(cartId, lineIds),
+    }), 'Failed to remove from cart'), [runner, cartClient, wrapMutation]);
+    // --- Lifecycle ---
+    const clearCart = useCallback(() => {
+        cookieStore.clear();
+        setStatus({ type: 'idle' });
+    }, [cookieStore]);
+    // Backward-compatible derived selectors over the tagged-union status.
+    const isLoading = status.type === 'loading';
+    const error = status.type === 'error' ? status.error.message : null;
     return {
         getCart,
+        getCartId,
         addItem,
-        updateItem,
-        removeItem,
+        updateBuyerIdentity,
+        setShippingAddress,
         updateDiscountCodes,
         updateNote,
+        updateItem,
+        removeItem,
         clearCart,
-        getCartId,
+        onExpired,
+        status,
         isLoading,
         error,
     };

package/dist/react/hooks/use-login.d.ts

@@ -0,0 +1,40 @@
+/**
+ * useLogin — focused hook for the login flow.
+ *
+ * Composes the auth client + Zustand store + httpOnly cookie BFF callback.
+ * Returns `success`/`userErrors` rather than throwing on credential errors —
+ * standard form submission pattern.
+ *
+ * @example
+ * ```tsx
+ * const { login, isLoggingIn, error } = useLogin({ onSetToken });
+ * const result = await login(email, password);
+ * if (!result.success) showErrors(result.userErrors);
+ * ```
+ */
+export interface UseLoginOptions {
+    /**
+     * Called after successful login with the new access token. Use this to set
+     * the httpOnly cookie via an API route handler (`createSetTokenHandler`).
+     */
+    onSetToken?: (token: string) => Promise<void>;
+}
+export interface LoginResult {
+    success: boolean;
+    userErrors: Array<{
+        message: string;
+        field?: string[];
+    }>;
+    accessToken?: string;
+    expiresAt?: string;
+}
+export interface UseLoginReturn {
+    /** Submit the login form. Resolves with `{success, userErrors}` rather than throwing on credential failures. */
+    login: (email: string, password: string) => Promise<LoginResult>;
+    /** `true` while a login request is in flight. */
+    isLoggingIn: boolean;
+    /** Last unexpected error message (network, server) — credential failures land in `userErrors` instead. */
+    error: string | null;
+}
+export declare function useLogin(options?: UseLoginOptions): UseLoginReturn;
+//# sourceMappingURL=use-login.d.ts.map