@doswiftly/storefront-sdk 11.0.0 → 11.2.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 11.2.0
+
+### Minor Changes
+
+- 760f965: Added automatic stale-cart recovery to the core SDK so every consumer (React, Vue, mobile, CLI, SSR) gets the same protection against `CART_NOT_FOUND` / `ALREADY_COMPLETED` errors without re-implementing detection, cookie cleanup, and retry orchestration.
+
+  **What's new** (importable from `@doswiftly/storefront-sdk`):
+  - `isCartRecoverableError(err)` — type-safe predicate that inspects `err.userErrors[].code` (works across PL/EN/any backend locale, unlike message string matching).
+  - `CART_RECOVERABLE_ERROR_CODES` — readonly tuple of codes that warrant cart recreation; mirrored against the backend `CartErrorCode` enum by a drift test.
+  - `executeWithCartRecovery(opts)` — pure async orchestrator for any consumer.
+  - `createCartRecoveryRunner({ cartClient, cookieStore })` — DX-friendly factory that curries the dependencies, shares a Phase-0 concurrency mutex across operations, and exposes an `onExpired(listener)` subscription for global UI feedback.
+  - `CartCookieStore` — port interface (`get` / `set` / `clear`) the caller implements once per runtime. From `@doswiftly/storefront-sdk/react` we now also export `createBrowserCartCookieStore()` (SSR-safe).
+  - `CartRecoveryNotPossibleError` — thrown when an operation cannot be safely replayed (line-id / shipping-method references the dead cart). Carries `reason: 'state-dependent' | 'recreate-failed' | 'retry-also-failed'` for diagnostic UX.
+  - `recreateWithInput(input)` / `recreateWithLines(lines)` — sugar helpers for the most common atomic `cartCreate(payload)` recovery strategies.
+
+  **Per-operation taxonomy (decision is in the SDK, not in caller code):**
+
+  | Operation                                                                                    | Strategy                                                                                                                                         |
+  | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+  | `addItems`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote` | Auto-replay via a single atomic `cartCreate(input)` — recovery is invisible to the caller                                                        |
+  | `updateItems`, `removeItems`                                                                 | Bail with `CartRecoveryNotPossibleError` and emit a `cart-expired` event — replaying on a fresh empty cart would silently lose the user's intent |
+
+  **React updates:**
+  - `useCartManager` now uses the recovery runner internally. Detection is code-based (no more PL/EN regression — previous implementation matched `'cart not found'` in the error message, which never matched a Polish backend response). Recovery now covers all mutations exposed by the hook, not just `addItem`. New methods: `updateBuyerIdentity`, `setShippingAddress`. New API: `onExpired(listener)` returning an unsubscribe function.
+  - `createCartStore` now recovers `addToCart` automatically. New optional `CartActions.createCartWithLines(lines)` lets templates wire the atomic single-round-trip path; without it the store falls back to `createCart()` + `addLines()`. `updateQuantity` and `removeFromCart` bail with the `cart-expired` event when the cart is gone (previously the store kept its local id pointing at a dead cart). `CartStoreConfig.onExpired?(event)` lets the consumer subscribe.
+
+  **Migration:**
+  - No required code changes for existing React consumers — `useCartManager` and `createCartStore` keep their public surface.
+  - If you previously caught `StorefrontError` to detect stale carts via message string matching, switch to `isCartRecoverableError(err)` (code-based, locale-proof) or — preferably — subscribe to `runner.onExpired(...)` / `useCartManager().onExpired(...)` / `createCartStore({ onExpired })`.
+  - Non-React consumers should wrap their cart mutations in `createCartRecoveryRunner` and implement a `CartCookieStore` adapter for their environment (browser via `createBrowserCartCookieStore()`, server-side via `next/headers`, CLI via in-memory `Map`, mobile via AsyncStorage).
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
+## 11.1.0
+
+### Minor Changes
+
+- c2e80b2: Add `paymentCreate` — initiate a payment session for a completed order.
+
+  After `cartComplete` returns an order, call `paymentCreate` (when `order.canCreatePayment` is `true`) to start the payment. Orders with an offline payment method (cash on delivery, manual bank transfer) skip this step. The returned `PaymentSession` is flow-aware — branch on `session.flow`:
+  - `ONLINE_REDIRECT` → redirect the browser to `session.redirectUrl`
+  - `ONLINE_EMBEDDED` → render an in-page widget with `session.clientSecret`
+  - `INSTANT_DIRECT` → already settled, read `session.status`
+
+  **`@doswiftly/storefront-operations`** — new `PaymentCreate` mutation and `PaymentSession` fragment.
+
+  **`@doswiftly/storefront-sdk`** — new `CartClient.createPayment(input)` method, plus the `PaymentSession`, `PaymentCreateInput`, `PaymentInitiationFlow` and `PaymentErrorCode` types.
+
+  ```ts
+  const { order } = await cartClient.complete({ cartId });
+  if (order.canCreatePayment) {
+    const session = await cartClient.createPayment({
+      orderId: order.id,
+      returnUrl: "https://my-shop.example/checkout/complete",
+    });
+    if (session.flow === "ONLINE_REDIRECT") {
+      window.location.href = session.redirectUrl!;
+    }
+  }
+  ```
+
+  `paymentCreate` is idempotent on the order — re-calling returns the existing still-valid session instead of creating a duplicate, so it is safe to retry. `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop. The call throws on validation/business errors — inspect `error.userErrors[0].code` (`PaymentErrorCode`): `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`.
+
 ## 11.0.0
 
 ### Major Changes

package/README.md

@@ -158,6 +158,89 @@ const existing = await cartClient.get(cartId);
 
 Auto-throws `StorefrontError` with code `USER_ERROR` on validation failures.
 
+### Cart recovery (stale carts)
+
+Carts can become unusable between reads and writes — they expire (TTL), lock after checkout (`ALREADY_COMPLETED`), or get cleaned up by a purge worker. Write mutations then reject with `userErrors[].code = 'CART_NOT_FOUND'` even though the previous `cart(id)` query succeeded.
+
+The recovery utilities in core make this transparent for the caller. Every operation classifies itself: replay-safe operations (`addItems`, `updateBuyerIdentity`, `setShippingAddress`, discount codes, note) auto-recover via an atomic `cartCreate(input)`; state-dependent operations (`updateItems`, `removeItems`) bail with a `CartRecoveryNotPossibleError` and emit a `cart-expired` event so your UI can surface a single toast/banner instead of every call site handling the error.
+
+```typescript
+import {
+  CartClient,
+  createCartRecoveryRunner,
+  recreateWithInput,
+  CartRecoveryNotPossibleError,
+  type CartCookieStore,
+} from '@doswiftly/storefront-sdk';
+
+// Implement the cookie port for your runtime (or use createBrowserCartCookieStore from /react)
+const cookieStore: CartCookieStore = {
+  get: () => readCartCookie(),
+  set: (cartId) => writeCartCookie(cartId),
+  clear: () => deleteCartCookie(),
+};
+
+const cartClient = new CartClient(client);
+const runner = createCartRecoveryRunner({ cartClient, cookieStore });
+
+runner.onExpired((event) => {
+  // Fired when the runner cannot transparently recover. UI prompts user to retry.
+  console.warn(`Cart expired (${event.reason}). Reset local state.`);
+});
+
+// Auto-replay: storefront caller never thinks about recovery
+const { cart, warnings } = await runner.execute({
+  name: 'addItems',
+  run: (cartId) => cartClient.addItems(cartId, [{ variantId: 'v-123', quantity: 1 }]),
+  recreateAndRun: recreateWithInput({ lines: [{ variantId: 'v-123', quantity: 1 }] }),
+});
+
+// Bail-on-stale: operation throws CartRecoveryNotPossibleError if cart is gone
+try {
+  await runner.execute({
+    name: 'updateItem',
+    run: (cartId) => cartClient.updateItems(cartId, [{ id: 'line-1', quantity: 2 }]),
+    // No recreateAndRun — replaying on an empty cart would silently lose the user's intent.
+  });
+} catch (err) {
+  if (err instanceof CartRecoveryNotPossibleError) {
+    // Already handled by the onExpired listener above.
+  } else {
+    throw err;
+  }
+}
+```
+
+Detection inspects `err.userErrors[].code` (`CART_NOT_FOUND` / `ALREADY_COMPLETED`) — locale-independent.
+
+### React: `useCartManager` (DX-first hook)
+
+`useCartManager` is the React wrapper around the recovery runner — same per-operation taxonomy, just `useState`-driven loading/error and an `onExpired` subscription helper:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { useCartManager } from '@doswiftly/storefront-sdk/react';
+import { toast } from 'sonner';
+
+export function CartButton() {
+  const { addItem, updateItem, onExpired, isLoading } = useCartManager();
+
+  useEffect(
+    () => onExpired((e) => toast.error(e.reason === 'state-dependent' ? 'Twój koszyk wygasł, dodaj produkty ponownie' : 'Nie udało się odzyskać koszyka')),
+    [onExpired],
+  );
+
+  return (
+    <button onClick={() => addItem([{ variantId: 'v-123', quantity: 1 }])} disabled={isLoading}>
+      Add to cart
+    </button>
+  );
+}
+```
+
+Methods returning `CartMutationOutcome` are: `addItem`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote` (auto-replay) and `updateItem`, `removeItem` (bail + `onExpired`). Use `clearCart` to reset locally without backend call.
+
 ### AuthClient
 
 ```typescript

package/dist/__tests__/unit/use-cart-manager.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-cart-manager.test.d.ts.map

package/dist/__tests__/unit/use-cart-manager.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cart-manager.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/use-cart-manager.test.tsx"],"names":[],"mappings":""}

package/dist/__tests__/unit/use-cart-manager.test.js

@@ -0,0 +1,400 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+// @vitest-environment jsdom
+/**
+ * Unit tests for useCartManager — DX-first cart hook with automatic stale-cart
+ * recovery.
+ *
+ * Mocks the StorefrontClientContext directly (no full StorefrontProvider stack)
+ * so each test owns its CartClient spy and can simulate recoverable / fatal
+ * errors per-mutation. Recovery semantics under the hood are covered by
+ * cart-recovery.test.ts — these tests focus on the React wrapper:
+ *
+ *   - per-operation taxonomy reaches the right code path (replay vs bail)
+ *   - onExpired subscribers fire on bail / recreate-fail
+ *   - isLoading / error state transitions are correct
+ *   - cookie-based cart id persistence works through document.cookie
+ *
+ * Note: hook is rendered via `renderHook` from @testing-library/react. Awaits
+ * inside `act(async () => { ... })` flush React effects before assertions.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useCartManager } from '../../react/hooks/use-cart-manager';
+import { StorefrontError, ErrorCodes } from '../../core/errors';
+import { CartClient } from '../../core/cart/cart-client';
+// ---------------------------------------------------------------------------
+// Mock StorefrontClientContext — supply our own cartClient per test
+// ---------------------------------------------------------------------------
+let activeCartClient;
+vi.mock('../../react/providers/storefront-client-provider', () => ({
+    useStorefrontClientContext: () => ({
+        client: {},
+        cartClient: activeCartClient,
+        authClient: {},
+    }),
+}));
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+function mockStorefrontClient() {
+    return {
+        query: vi.fn(async () => ({})),
+        mutate: vi.fn(async () => ({})),
+        use: vi.fn(),
+    };
+}
+const fakeCart = (id = 'cart-fresh') => ({
+    id,
+    lines: { edges: [], nodes: [], pageInfo: {}, totalCount: 0 },
+    totalQuantity: 0,
+    cost: { total: { amount: '0', currencyCode: 'PLN' }, subtotal: { amount: '0', currencyCode: 'PLN' } },
+});
+const FAKE_CART = fakeCart();
+function recoverableError(code, message) {
+    return new StorefrontError({
+        code: ErrorCodes.USER_ERROR,
+        message: message ?? 'User errors in response',
+        userErrors: [{ message: message ?? 'simulated', code, field: [] }],
+    });
+}
+function nonRecoverableError() {
+    return new StorefrontError({
+        code: ErrorCodes.USER_ERROR,
+        message: 'Out of stock',
+        userErrors: [{ message: 'low stock', code: 'NOT_ENOUGH_IN_STOCK', field: [] }],
+    });
+}
+function setCartCookie(value) {
+    if (value === null) {
+        document.cookie = 'cart-id=;max-age=0;path=/';
+    }
+    else {
+        document.cookie = `cart-id=${value};path=/`;
+    }
+}
+function getCartCookie() {
+    const match = document.cookie.match(/(?:^|;\s*)cart-id=([^;]*)/);
+    return match ? decodeURIComponent(match[1]) : null;
+}
+const Wrapper = ({ children }) => _jsx(_Fragment, { children: children });
+beforeEach(() => {
+    activeCartClient = new CartClient(mockStorefrontClient());
+    setCartCookie(null);
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    setCartCookie(null);
+});
+// ---------------------------------------------------------------------------
+// addItem — auto-replay
+// ---------------------------------------------------------------------------
+describe('useCartManager — addItem (auto-replay)', () => {
+    it('creates cart on first add when cookie empty (Phase 0)', async () => {
+        const createSpy = vi.spyOn(activeCartClient, 'create').mockResolvedValue({ cart: FAKE_CART, warnings: [] });
+        const addSpy = vi.spyOn(activeCartClient, 'addItems').mockResolvedValue({ cart: FAKE_CART, warnings: [] });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await result.current.addItem([{ variantId: 'v1', quantity: 1 }]);
+        });
+        expect(createSpy).toHaveBeenCalledTimes(1);
+        expect(addSpy).toHaveBeenCalledWith('cart-fresh', [{ variantId: 'v1', quantity: 1 }]);
+        expect(getCartCookie()).toBe('cart-fresh');
+    });
+    it('uses cookie cart-id on subsequent adds', async () => {
+        setCartCookie('existing-cart');
+        const createSpy = vi.spyOn(activeCartClient, 'create');
+        const addSpy = vi.spyOn(activeCartClient, 'addItems').mockResolvedValue({ cart: FAKE_CART, warnings: [] });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await result.current.addItem([{ variantId: 'v1', quantity: 1 }]);
+        });
+        expect(createSpy).not.toHaveBeenCalled();
+        expect(addSpy).toHaveBeenCalledWith('existing-cart', [{ variantId: 'v1', quantity: 1 }]);
+    });
+    it('auto-recovers on CART_NOT_FOUND via atomic cartCreate({ lines })', async () => {
+        setCartCookie('stale-cart');
+        const stale = recoverableError('CART_NOT_FOUND');
+        vi.spyOn(activeCartClient, 'addItems').mockRejectedValue(stale);
+        const createSpy = vi.spyOn(activeCartClient, 'create').mockResolvedValue({
+            cart: fakeCart('cart-recovered'),
+            warnings: [],
+        });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            const outcome = await result.current.addItem([{ variantId: 'v1', quantity: 2 }]);
+            expect(outcome.cart.id).toBe('cart-recovered');
+        });
+        // Atomic recreate: cartCreate({ lines: [...] }) — NOT empty create + addItems
+        expect(createSpy).toHaveBeenCalledWith({ lines: [{ variantId: 'v1', quantity: 2 }] });
+        expect(getCartCookie()).toBe('cart-recovered');
+    });
+    it('auto-recovers on ALREADY_COMPLETED (post-checkout locked cart)', async () => {
+        setCartCookie('locked-cart');
+        vi.spyOn(activeCartClient, 'addItems').mockRejectedValue(recoverableError('ALREADY_COMPLETED'));
+        vi.spyOn(activeCartClient, 'create').mockResolvedValue({
+            cart: fakeCart('post-checkout-cart'),
+            warnings: [],
+        });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await result.current.addItem([{ variantId: 'v1' }]);
+        });
+        expect(getCartCookie()).toBe('post-checkout-cart');
+    });
+    it('PL locale message does not break detection (regression for legacy useCartManager bug)', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'addItems').mockRejectedValue(recoverableError('CART_NOT_FOUND', 'Nie znaleziono koszyka'));
+        const createSpy = vi.spyOn(activeCartClient, 'create').mockResolvedValue({
+            cart: fakeCart('pl-recovered'),
+            warnings: [],
+        });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await result.current.addItem([{ variantId: 'v1' }]);
+        });
+        expect(createSpy).toHaveBeenCalledTimes(1);
+    });
+    it('propagates non-recoverable errors (stock) without recovery', async () => {
+        setCartCookie('cart-1');
+        const stock = nonRecoverableError();
+        vi.spyOn(activeCartClient, 'addItems').mockRejectedValue(stock);
+        const createSpy = vi.spyOn(activeCartClient, 'create');
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await expect(result.current.addItem([{ variantId: 'oos' }])).rejects.toBe(stock);
+        });
+        expect(createSpy).not.toHaveBeenCalled();
+        expect(getCartCookie()).toBe('cart-1');
+        expect(result.current.error).toBe('Out of stock');
+    });
+});
+// ---------------------------------------------------------------------------
+// updateItem / removeItem — bail
+// ---------------------------------------------------------------------------
+describe('useCartManager — updateItem / removeItem (bail)', () => {
+    it('updateItem on CART_NOT_FOUND throws CartRecoveryNotPossibleError + fires onExpired', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'updateItems').mockRejectedValue(recoverableError('CART_NOT_FOUND'));
+        const createSpy = vi.spyOn(activeCartClient, 'create');
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        const listener = vi.fn();
+        act(() => {
+            result.current.onExpired(listener);
+        });
+        await act(async () => {
+            await expect(result.current.updateItem([{ id: 'line-1', quantity: 5 }])).rejects.toMatchObject({ name: 'CartRecoveryNotPossibleError', reason: 'state-dependent' });
+        });
+        expect(createSpy).not.toHaveBeenCalled(); // no replay — operation is state-dependent
+        expect(getCartCookie()).toBeNull(); // cookie cleared
+        expect(listener).toHaveBeenCalledWith(expect.objectContaining({ reason: 'state-dependent', operation: 'updateItem' }));
+    });
+    it('removeItem on ALREADY_COMPLETED bails the same way', async () => {
+        setCartCookie('locked');
+        vi.spyOn(activeCartClient, 'removeItems').mockRejectedValue(recoverableError('ALREADY_COMPLETED'));
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        const listener = vi.fn();
+        act(() => {
+            result.current.onExpired(listener);
+        });
+        await act(async () => {
+            await expect(result.current.removeItem(['line-1'])).rejects.toMatchObject({
+                name: 'CartRecoveryNotPossibleError',
+            });
+        });
+        expect(listener).toHaveBeenCalledWith(expect.objectContaining({ operation: 'removeItem' }));
+    });
+    it('updateItem propagates non-recoverable error without bail', async () => {
+        setCartCookie('cart-1');
+        const validation = new Error('Quantity must be positive');
+        vi.spyOn(activeCartClient, 'updateItems').mockRejectedValue(validation);
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        const listener = vi.fn();
+        act(() => {
+            result.current.onExpired(listener);
+        });
+        await act(async () => {
+            await expect(result.current.updateItem([{ id: 'l1', quantity: -1 }])).rejects.toBe(validation);
+        });
+        expect(getCartCookie()).toBe('cart-1'); // cookie not cleared — cart still good
+        expect(listener).not.toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// Other auto-replay mutations
+// ---------------------------------------------------------------------------
+describe('useCartManager — checkout-flow mutations (auto-replay)', () => {
+    it('updateDiscountCodes auto-replays via cartCreate({ discountCodes })', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'updateDiscountCodes').mockRejectedValue(recoverableError('CART_NOT_FOUND'));
+        const createSpy = vi.spyOn(activeCartClient, 'create').mockResolvedValue({
+            cart: fakeCart('rec'),
+            warnings: [],
+        });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await result.current.updateDiscountCodes(['SAVE10', 'FREESHIP']);
+        });
+        expect(createSpy).toHaveBeenCalledWith({ discountCodes: ['SAVE10', 'FREESHIP'] });
+    });
+    it('updateNote auto-replays via cartCreate({ note })', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'updateNote').mockRejectedValue(recoverableError('CART_NOT_FOUND'));
+        const createSpy = vi.spyOn(activeCartClient, 'create').mockResolvedValue({
+            cart: fakeCart('rec'),
+            warnings: [],
+        });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await result.current.updateNote('Gift wrap');
+        });
+        expect(createSpy).toHaveBeenCalledWith({ note: 'Gift wrap' });
+    });
+    it('updateBuyerIdentity auto-replays via cartCreate({ buyerIdentity })', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'updateBuyerIdentity').mockRejectedValue(recoverableError('CART_NOT_FOUND'));
+        const createSpy = vi.spyOn(activeCartClient, 'create').mockResolvedValue({
+            cart: fakeCart('rec'),
+            warnings: [],
+        });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await result.current.updateBuyerIdentity({ email: 'user@example.com' });
+        });
+        expect(createSpy).toHaveBeenCalledWith({ buyerIdentity: { email: 'user@example.com' } });
+    });
+    it('setShippingAddress auto-replays via cartCreate({ shippingAddress })', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'setShippingAddress').mockRejectedValue(recoverableError('CART_NOT_FOUND'));
+        const createSpy = vi.spyOn(activeCartClient, 'create').mockResolvedValue({
+            cart: fakeCart('rec'),
+            warnings: [],
+        });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        const address = {
+            firstName: 'Anna',
+            lastName: 'Nowak',
+            streetLine1: 'ul. Krakowska 1',
+            city: 'Warszawa',
+            country: 'PL',
+            postalCode: '00-001',
+        };
+        await act(async () => {
+            await result.current.setShippingAddress(address);
+        });
+        expect(createSpy).toHaveBeenCalledWith({ shippingAddress: address });
+    });
+});
+// ---------------------------------------------------------------------------
+// getCart — read with auto-clear
+// ---------------------------------------------------------------------------
+describe('useCartManager — getCart', () => {
+    it('returns cart on success', async () => {
+        setCartCookie('existing');
+        vi.spyOn(activeCartClient, 'get').mockResolvedValue(FAKE_CART);
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        let cart;
+        await act(async () => {
+            cart = await result.current.getCart();
+        });
+        expect(cart).toEqual(FAKE_CART);
+    });
+    it('returns null + clears cookie when backend returns CART_NOT_FOUND via userErrors', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'get').mockRejectedValue(recoverableError('CART_NOT_FOUND'));
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        const listener = vi.fn();
+        act(() => {
+            result.current.onExpired(listener);
+        });
+        let cart;
+        await act(async () => {
+            cart = await result.current.getCart();
+        });
+        expect(cart).toBeNull();
+        expect(getCartCookie()).toBeNull();
+        expect(listener).toHaveBeenCalledWith(expect.objectContaining({ reason: 'state-dependent', operation: 'getCart' }));
+    });
+    it('returns null without fetching when cookie is empty', async () => {
+        const getSpy = vi.spyOn(activeCartClient, 'get');
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        let cart;
+        await act(async () => {
+            cart = await result.current.getCart();
+        });
+        expect(cart).toBeNull();
+        expect(getSpy).not.toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// onExpired lifecycle + reactive state
+// ---------------------------------------------------------------------------
+describe('useCartManager — onExpired + state', () => {
+    it('listener unsubscribe stops further notifications', async () => {
+        setCartCookie('stale');
+        vi.spyOn(activeCartClient, 'updateItems').mockRejectedValue(recoverableError('CART_NOT_FOUND'));
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        const listener = vi.fn();
+        let unsubscribe;
+        act(() => {
+            unsubscribe = result.current.onExpired(listener);
+        });
+        act(() => {
+            unsubscribe();
+        });
+        await act(async () => {
+            await expect(result.current.updateItem([{ id: 'l1', quantity: 1 }])).rejects.toBeDefined();
+        });
+        expect(listener).not.toHaveBeenCalled();
+    });
+    it('isLoading toggles around a mutation', async () => {
+        setCartCookie('cart-1');
+        let resolveAdd = null;
+        const addPromise = new Promise((r) => {
+            resolveAdd = r;
+        });
+        vi.spyOn(activeCartClient, 'addItems').mockImplementation(() => addPromise);
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        expect(result.current.isLoading).toBe(false);
+        let pending;
+        act(() => {
+            pending = result.current.addItem([{ variantId: 'v1' }]);
+        });
+        // After invocation but before resolve — isLoading should be true on next tick
+        await act(async () => {
+            await new Promise((r) => setTimeout(r, 0));
+        });
+        expect(result.current.isLoading).toBe(true);
+        await act(async () => {
+            resolveAdd({ cart: FAKE_CART, warnings: [] });
+            await pending;
+        });
+        expect(result.current.isLoading).toBe(false);
+    });
+    it('error state is populated on failure and cleared on subsequent success', async () => {
+        setCartCookie('cart-1');
+        const fail = new Error('boom');
+        const addSpy = vi.spyOn(activeCartClient, 'addItems')
+            .mockRejectedValueOnce(fail)
+            .mockResolvedValueOnce({ cart: FAKE_CART, warnings: [] });
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        await act(async () => {
+            await expect(result.current.addItem([{ variantId: 'v1' }])).rejects.toBe(fail);
+        });
+        expect(result.current.error).toBe('boom');
+        await act(async () => {
+            await result.current.addItem([{ variantId: 'v1' }]);
+        });
+        expect(result.current.error).toBeNull();
+        expect(addSpy).toHaveBeenCalledTimes(2);
+    });
+    it('clearCart removes the cookie', async () => {
+        setCartCookie('to-clear');
+        const { result } = renderHook(() => useCartManager(), { wrapper: Wrapper });
+        expect(result.current.getCartId()).toBe('to-clear');
+        act(() => {
+            result.current.clearCart();
+        });
+        expect(getCartCookie()).toBeNull();
+        expect(result.current.getCartId()).toBeNull();
+    });
+});

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

@@ -22,7 +22,7 @@
  * ```
  */
 import type { StorefrontClient } from '../client/types';
-import type { Cart, CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartSetShippingAddressInput, CartSetBillingAddressInput, CartSelectShippingMethodInput, CartSelectPaymentMethodInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartUpdateGiftCardRecipientInput, CartCompleteInput, CartWarning, Order, DiscountValidationResult } from './types';
+import type { Cart, CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartSetShippingAddressInput, CartSetBillingAddressInput, CartSelectShippingMethodInput, CartSelectPaymentMethodInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartUpdateGiftCardRecipientInput, CartCompleteInput, CartWarning, Order, DiscountValidationResult, PaymentSession, PaymentCreateInput } from './types';
 /**
  * Standard mutation return shape — `cart` is non-null on success (userErrors
  * cause assertNoUserErrors to throw), `warnings` may be empty.
@@ -130,6 +130,24 @@ export declare class CartClient {
      * `paymentCreate` mutation after checking `order.canCreatePayment`.
      */
     complete(input: CartCompleteInput): Promise<CartCompleteOutcome>;
+    /**
+     * Initiate a payment session for an order created by `complete()`. Call this
+     * when `order.canCreatePayment` is `true` — orders with an offline payment
+     * method (cash on delivery, manual bank transfer) skip this step.
+     *
+     * `input.returnUrl` / `input.cancelUrl` are optional; when supplied they must
+     * point to a verified domain of the shop (the server rejects others). The
+     * returned `PaymentSession` is flow-aware — branch on `session.flow`:
+     * `ONLINE_REDIRECT` → redirect to `session.redirectUrl`, `ONLINE_EMBEDDED` →
+     * render a widget with `session.clientSecret`, `INSTANT_DIRECT` → already
+     * settled, read `session.status`.
+     *
+     * Idempotent — calling it again for the same order returns the existing
+     * still-valid session instead of creating a duplicate (safe to retry).
+     * Throws a `StorefrontError` (carrying `userErrors`) when the order can't be
+     * paid — inspect `.userErrors[0].code` (`PaymentErrorCode`).
+     */
+    createPayment(input: PaymentCreateInput): Promise<PaymentSession>;
     /**
      * Validate discount code preview (Decision D3) — read-only Query, NIE
      * mutation. Doesn't modify cart state. Returns `{ isValid, discount?, error? }`

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

@@ -1 +1 @@
-{"version":3,"file":"cart-client.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EACV,IAAI,EACJ,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,uBAAuB,EACvB,gCAAgC,EAChC,iBAAiB,EACjB,WAAW,EACX,KAAK,EACL,wBAAwB,EACzB,MAAM,SAAS,CAAC;AA8CjB;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAQ/C;;OAEG;IACG,MAAM,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASnE;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASpF;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAS7F;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASlF;;;OAGG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAShG;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAS5E;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,sBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAa9G;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAS1F;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASxF;;;OAGG;IACG,oBAAoB,CAAC,KAAK,EAAE,6BAA6B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAS9F;;;OAGG;IACG,mBAAmB,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAS5F;;;OAGG;IACG,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAShF;;;OAGG;IACG,cAAc,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASlF;;;;OAIG;IACG,uBAAuB,CAAC,KAAK,EAAE,gCAAgC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASpG;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYtE;;;;;;;;OAQG;IACG,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC;CAOpG"}
+{"version":3,"file":"cart-client.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-client.ts"],"names":[],"mappings":"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"}

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

@@ -22,7 +22,7 @@
  * ```
  */
 import { assertNoUserErrors } from '../helpers/assert-no-user-errors';
-import { CART_QUERY, CART_CREATE, CART_ADD_LINES, CART_UPDATE_LINES, CART_REMOVE_LINES, CART_DISCOUNT_CODES_UPDATE, CART_UPDATE_NOTE, CART_UPDATE_BUYER_IDENTITY, CART_SET_SHIPPING_ADDRESS, CART_SET_BILLING_ADDRESS, CART_SELECT_SHIPPING_METHOD, CART_SELECT_PAYMENT_METHOD, CART_APPLY_GIFT_CARD, CART_REMOVE_GIFT_CARD, CART_UPDATE_GIFT_CARD_RECIPIENT, CART_COMPLETE, CART_VALIDATE_DISCOUNT_CODE, } from '../operations/cart';
+import { CART_QUERY, CART_CREATE, CART_ADD_LINES, CART_UPDATE_LINES, CART_REMOVE_LINES, CART_DISCOUNT_CODES_UPDATE, CART_UPDATE_NOTE, CART_UPDATE_BUYER_IDENTITY, CART_SET_SHIPPING_ADDRESS, CART_SET_BILLING_ADDRESS, CART_SELECT_SHIPPING_METHOD, CART_SELECT_PAYMENT_METHOD, CART_APPLY_GIFT_CARD, CART_REMOVE_GIFT_CARD, CART_UPDATE_GIFT_CARD_RECIPIENT, CART_COMPLETE, CART_VALIDATE_DISCOUNT_CODE, PAYMENT_CREATE, } from '../operations/cart';
 export class CartClient {
     client;
     constructor(client) {
@@ -181,6 +181,28 @@ export class CartClient {
             warnings: data.cartComplete.warnings ?? [],
         };
     }
+    /**
+     * Initiate a payment session for an order created by `complete()`. Call this
+     * when `order.canCreatePayment` is `true` — orders with an offline payment
+     * method (cash on delivery, manual bank transfer) skip this step.
+     *
+     * `input.returnUrl` / `input.cancelUrl` are optional; when supplied they must
+     * point to a verified domain of the shop (the server rejects others). The
+     * returned `PaymentSession` is flow-aware — branch on `session.flow`:
+     * `ONLINE_REDIRECT` → redirect to `session.redirectUrl`, `ONLINE_EMBEDDED` →
+     * render a widget with `session.clientSecret`, `INSTANT_DIRECT` → already
+     * settled, read `session.status`.
+     *
+     * Idempotent — calling it again for the same order returns the existing
+     * still-valid session instead of creating a duplicate (safe to retry).
+     * Throws a `StorefrontError` (carrying `userErrors`) when the order can't be
+     * paid — inspect `.userErrors[0].code` (`PaymentErrorCode`).
+     */
+    async createPayment(input) {
+        const data = await this.client.mutate(PAYMENT_CREATE, { input });
+        assertNoUserErrors(data.paymentCreate);
+        return data.paymentCreate.payment;
+    }
     /**
      * Validate discount code preview (Decision D3) — read-only Query, NIE
      * mutation. Doesn't modify cart state. Returns `{ isValid, discount?, error? }`