@doswiftly/storefront-sdk 18.0.0 → 19.0.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## 19.0.0
+
+### Major Changes
+
+- 7ee241f: Move the server-side cookie readers to the server entry and rename them for intent.
+
+  The two async cookie readers now live in `@doswiftly/storefront-sdk/react/server` (next to
+  `getInitialAuth`) and are renamed to describe what they read instead of how:
+
+  | Removed (from `@doswiftly/storefront-sdk/react`) | New (in `@doswiftly/storefront-sdk/react/server`) |
+  | ------------------------------------------------ | ------------------------------------------------- |
+  | `getCurrencyFromCookieAsync()`                   | `readCurrencyCookie()`                            |
+  | `getCartIdFromCookieAsync()`                     | `readCartIdCookie()`                              |
+
+  Both keep the same return type, `Promise<string | null>`, and read the same cookies
+  (`preferred-currency`, `cart-id`). They are still server-first with a `document.cookie` fallback,
+  so they remain safe to call from either side — these cookies are readable (not httpOnly).
+
+  `getCookie`, `setCookie`, `deleteCookie`, and `createBrowserCartCookieStore` are unchanged and
+  still exported from `@doswiftly/storefront-sdk/react`.
+
+  **Why**: the readers depend on `next/headers`, a server-only API, but were exported from the
+  client React entry — so the entry's own description ("client-side; for server use `next/headers`")
+  contradicted two of its functions. Moving them next to `getInitialAuth` keeps `next/headers` out of
+  the client entry and gives both cold-start cookie reads (auth, and now cart-id / currency) one home.
+
+  **Migration** — update the import path and the names:
+
+  ```ts
+  // Before — client React entry
+  import {
+    getCurrencyFromCookieAsync,
+    getCartIdFromCookieAsync,
+  } from "@doswiftly/storefront-sdk/react";
+  const currency = await getCurrencyFromCookieAsync();
+  const cartId = await getCartIdFromCookieAsync();
+
+  // After — server entry (use in a Server Component)
+  import {
+    readCurrencyCookie,
+    readCartIdCookie,
+  } from "@doswiftly/storefront-sdk/react/server";
+  const currency = await readCurrencyCookie();
+  const cartId = await readCartIdCookie();
+  ```
+
+  Reading the cart-id server-side is the supported way to resolve a returning buyer's cart on the
+  first render — including when a separate checkout deployment shares the storefront domain:
+
+  ```ts
+  // app/checkout/page.tsx (Server Component)
+  import { readCartIdCookie } from "@doswiftly/storefront-sdk/react/server";
+
+  const cartId = await readCartIdCookie();
+  const cart = cartId ? await fetchCart(cartId) : null;
+  ```
+
+  **Migration checklist**:
+  - [ ] Replace `getCurrencyFromCookieAsync` / `getCartIdFromCookieAsync` imports from
+        `@doswiftly/storefront-sdk/react` with `readCurrencyCookie` / `readCartIdCookie` from
+        `@doswiftly/storefront-sdk/react/server`.
+  - [ ] For purely client-side reads, use `getCookie('preferred-currency')` /
+        `getCookie('cart-id')` (or `createBrowserCartCookieStore()` for the cart id) from
+        `@doswiftly/storefront-sdk/react` instead.
+
+## 18.1.0
+
+### Minor Changes
+
+- ff03fd3: Add `<CartManagerProvider>` + `useCartManagerContext()` so a single cart manager can be shared across a checkout tree, plus optional lifecycle callbacks on `useCartManager` and the provider.
+
+  **Why** — `useCartManager` keeps per-mount state (loading status, recovery coordinator, cart-expired listeners). Calling it in several components creates independent managers, so a checkout that wants one loading indicator, one recovery queue, and one cart-expired subscription had to hand-roll a React Context wrapper. This ships that wrapper as a first-class, opt-in provider, matching the provider-first pattern already used by `<StorefrontProvider>`, `<CurrencyProvider>`, and `<CartProvider>`.
+
+  **Additive (backward-compatible)**:
+  1. `<CartManagerProvider>` creates one `useCartManager` instance and exposes it through Context; `useCartManagerContext()` reads it (throws when used outside the provider). The provider must be rendered inside `<StorefrontProvider>`.
+  2. New optional lifecycle callbacks, accepted both by `useCartManager(options)` and as `<CartManagerProvider>` props:
+     - `onMutationStart(operation)` — fired when a mutation starts.
+     - `onMutationSuccess(operation)` — fired after it resolves.
+     - `onMutationError(operation, error)` — fired with a buyer-surfaceable error (its message comes from the backend). Cart expiry and session loss are delivered through the dedicated `onExpired` / session-expired channels and do NOT trigger `onMutationError`, so `toast.error(error.message)` is safe to wire.
+
+     A transient missing-cart error that the manager transparently recovers from resolves as success. Callbacks are invoked defensively — a throwing callback never rejects the underlying mutation (it is logged via `console.warn`).
+
+  3. New exported types: `CartManagerProviderProps`, `CartManagerLifecycleCallbacks`, `UseCartManagerOptions`.
+
+  **Usage example**:
+
+  ```tsx
+  "use client";
+  import { useRouter } from "next/navigation";
+  import { toast } from "sonner";
+  import {
+    CartManagerProvider,
+    useCartManagerContext,
+  } from "@doswiftly/storefront-sdk/react";
+
+  function Checkout({ initialCartId }: { initialCartId: string | null }) {
+    const router = useRouter();
+    return (
+      <CartManagerProvider
+        initialCartId={initialCartId}
+        onMutationSuccess={() => router.refresh()}
+        onMutationError={(operation, error) => toast.error(error.message)}
+      >
+        <CheckoutForm />
+      </CartManagerProvider>
+    );
+  }
+
+  function CheckoutForm() {
+    // one shared manager for the whole form
+    const { addItem, complete, status } = useCartManagerContext();
+    // ...
+  }
+  ```
+
+  **Migration checklist** — none required; everything is opt-in.
+  - [ ] Optional: replace a hand-rolled `useCartManager` Context wrapper with `<CartManagerProvider>` + `useCartManagerContext()`.
+  - [ ] Optional: move per-call toast / refresh side-effects into `onMutationSuccess` / `onMutationError` on the provider.
+  - [ ] Keep calling `useCartManager()` directly where you want independent managers (e.g. multi-cart B2B, an admin "view this cart" panel).
+
+  **Standards reference** — provider-first sharing of a stateful instance with listeners and async initialisation is the established React-ecosystem pattern (`QueryClientProvider`, Stripe `<Elements>`), and mirrors the provider-first cart APIs of leading commerce SDKs.
+
 ## 18.0.0
 
 ### Major Changes

package/README.md

@@ -493,6 +493,37 @@ export function CartButton() {
 
 Methods returning `CartMutationOutcome` are: `addItem`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote` (auto-replay) and `updateItem`, `removeItem` (bail + `onExpired`). Use `clearCart` to reset locally without backend call.
 
+### React: `<CartManagerProvider>` (shared instance)
+
+`useCartManager` keeps per-mount state, so calling it in several components creates independent managers. To share one source of truth across a checkout — one loading state, one recovery queue, one `cart-expired` subscription — wrap the subtree in `<CartManagerProvider>` (inside `<StorefrontProvider>`) and read it with `useCartManagerContext()`. The provider also takes lifecycle callbacks so cross-cutting side-effects live in one place:
+
+```tsx
+'use client';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+import { CartManagerProvider, useCartManagerContext } from '@doswiftly/storefront-sdk/react';
+
+function Checkout({ initialCartId }: { initialCartId: string | null }) {
+  const router = useRouter();
+  return (
+    <CartManagerProvider
+      initialCartId={initialCartId}
+      onMutationSuccess={() => router.refresh()}
+      onMutationError={(operation, error) => toast.error(error.message)}
+    >
+      <CheckoutForm />
+    </CartManagerProvider>
+  );
+}
+
+function CheckoutForm() {
+  const { addItem, complete, status } = useCartManagerContext();
+  // ...
+}
+```
+
+For deliberately independent managers (multi-cart B2B, an admin "view this cart" panel) call `useCartManager()` directly instead.
+
 ### AuthClient
 
 ```typescript

package/dist/react/cookies.d.ts

@@ -1,8 +1,10 @@
 /**
- * Cookie utilities for SDK consumers.
+ * Client-side cookie utilities for SDK consumers.
  *
- * Simple, framework-agnostic cookie read/write for client-side.
- * For Next.js server-side cookies, use `cookies()` from next/headers.
+ * Synchronous read/write over `document.cookie`, SSR-safe via a `typeof document`
+ * guard (return null / no-op when there is no document). To read these cookies in
+ * a Next.js Server Component use the `@doswiftly/storefront-sdk/react/server`
+ * entry (`readCartIdCookie`, `readCurrencyCookie`).
  */
 /**
  * Get cookie value by name (client-side only).
@@ -44,23 +46,4 @@ import type { CartCookieStore } from '../core/cart/cart-recovery';
  * ```
  */
 export declare function createBrowserCartCookieStore(): CartCookieStore;
-/**
- * Get preferred currency from cookie (async — works with Next.js cookies()).
- * Falls back to document.cookie on client.
- */
-export declare function getCurrencyFromCookieAsync(): Promise<string | null>;
-/**
- * Get cart ID from cookie (async — works with Next.js cookies()).
- * Falls back to document.cookie on client.
- *
- * Use in Server Components for SSR cart badge:
- * ```typescript
- * const cartId = await getCartIdFromCookieAsync();
- * if (cartId) {
- *   const cart = await fetchCart(cartId);
- *   // Render cart badge with real totalQuantity — no skeleton needed
- * }
- * ```
- */
-export declare function getCartIdFromCookieAsync(): Promise<string | null>;
 //# sourceMappingURL=cookies.d.ts.map

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;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"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/react/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;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;AAGD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,CAQ9D"}

package/dist/react/cookies.js

@@ -1,8 +1,10 @@
 /**
- * Cookie utilities for SDK consumers.
+ * Client-side cookie utilities for SDK consumers.
  *
- * Simple, framework-agnostic cookie read/write for client-side.
- * For Next.js server-side cookies, use `cookies()` from next/headers.
+ * Synchronous read/write over `document.cookie`, SSR-safe via a `typeof document`
+ * guard (return null / no-op when there is no document). To read these cookies in
+ * a Next.js Server Component use the `@doswiftly/storefront-sdk/react/server`
+ * entry (`readCartIdCookie`, `readCurrencyCookie`).
  */
 /**
  * Get cookie value by name (client-side only).
@@ -35,7 +37,6 @@ export function deleteCookie(name, path = '/') {
         return;
     document.cookie = `${name}=;max-age=0;path=${path}`;
 }
-import { CURRENCY_COOKIE_NAME } from '../core/currency/cookie-config';
 import { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from '../core/cart/cookie-config';
 /**
  * Build a browser-side `CartCookieStore` backed by `document.cookie`.
@@ -65,46 +66,3 @@ export function createBrowserCartCookieStore() {
         clear: () => deleteCookie(CART_COOKIE_NAME),
     };
 }
-/**
- * Get preferred currency from cookie (async — works with Next.js cookies()).
- * Falls back to document.cookie on client.
- */
-export async function getCurrencyFromCookieAsync() {
-    // Server-side: try Next.js cookies()
-    try {
-        const { cookies } = await import('next/headers');
-        const cookieStore = await cookies();
-        return cookieStore.get(CURRENCY_COOKIE_NAME)?.value ?? null;
-    }
-    catch {
-        // Not in a server context or next not available
-    }
-    // Client-side fallback
-    return getCookie(CURRENCY_COOKIE_NAME);
-}
-/**
- * Get cart ID from cookie (async — works with Next.js cookies()).
- * Falls back to document.cookie on client.
- *
- * Use in Server Components for SSR cart badge:
- * ```typescript
- * const cartId = await getCartIdFromCookieAsync();
- * if (cartId) {
- *   const cart = await fetchCart(cartId);
- *   // Render cart badge with real totalQuantity — no skeleton needed
- * }
- * ```
- */
-export async function getCartIdFromCookieAsync() {
-    // Server-side: try Next.js cookies()
-    try {
-        const { cookies } = await import('next/headers');
-        const cookieStore = await cookies();
-        return cookieStore.get(CART_COOKIE_NAME)?.value ?? null;
-    }
-    catch {
-        // Not in a server context or next not available
-    }
-    // Client-side fallback
-    return getCookie(CART_COOKIE_NAME);
-}

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

@@ -119,11 +119,40 @@ export type CartManagerStatus = {
     type: 'success';
     operation: CartManagerOperation;
 };
+/**
+ * Optional lifecycle callbacks fired around every cart and checkout operation
+ * the hook drives. Centralise cross-cutting side-effects — a global loading
+ * indicator, a toast on failure, a router refresh on success — in one place
+ * instead of wrapping each call site.
+ *
+ * `onMutationError` fires only for failures you can surface to the buyer: its
+ * `error` carries a backend-translated message. Cart expiry and session loss
+ * are delivered through their own dedicated channels (`onExpired` and the
+ * session-expired event) — they carry SDK-internal messages and do NOT trigger
+ * `onMutationError`. A transient missing-cart error that the manager recovers
+ * from (by recreating the cart) resolves as success, so it never reaches the
+ * error callback either.
+ *
+ * Callbacks are invoked defensively: a throwing callback never rejects the
+ * underlying mutation.
+ */
+export interface CartManagerLifecycleCallbacks {
+    /** Fired when an operation starts, before the request is sent. */
+    onMutationStart?: (operation: CartManagerOperation) => void;
+    /** Fired after an operation resolves successfully. */
+    onMutationSuccess?: (operation: CartManagerOperation) => void;
+    /**
+     * Fired when an operation fails with a buyer-surfaceable error. Cart expiry
+     * and session loss are routed to `onExpired` / the session-expired event
+     * instead, not here.
+     */
+    onMutationError?: (operation: CartManagerOperation, error: Error) => void;
+}
 /**
  * Optional configuration for `useCartManager`. All fields additive — calling
  * the hook with no arguments preserves the original cookie-driven behaviour.
  */
-export interface UseCartManagerOptions {
+export interface UseCartManagerOptions extends CartManagerLifecycleCallbacks {
     /**
      * Server-known cart-id seed used when the `cart-id` cookie is empty on
      * mount. Cookie wins when present; the seed only fills the gap on the

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":"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"}
+{"version":3,"file":"use-cart-manager.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart-manager.ts"],"names":[],"mappings":"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"}

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

@@ -86,15 +86,48 @@
  * ```
  */
 'use client';
-import { useCallback, useMemo, useState } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
 import { useStorefrontClientContext } from '../providers/storefront-client-provider';
-import { createCartRecoveryRunner, recreateWithInput, } from '../../core/cart/cart-recovery';
+import { createCartRecoveryRunner, recreateWithInput, CartRecoveryNotPossibleError, CartSessionRequiredError, } from '../../core/cart/cart-recovery';
 import { createBrowserCartCookieStore } from '../cookies';
+/**
+ * Invoke an optional lifecycle callback without letting a thrown callback
+ * reject the cart mutation it wraps. A misbehaving UI side-effect (toast,
+ * navigation) must never corrupt cart state or surface as a failed mutation —
+ * but the throw is logged so the consumer bug stays debuggable.
+ */
+function safeInvoke(run) {
+    try {
+        run();
+    }
+    catch (err) {
+        console.warn('[storefront-sdk] cart manager lifecycle callback threw', err);
+    }
+}
+/**
+ * Cart expiry (`CartRecoveryNotPossibleError`) and session loss
+ * (`CartSessionRequiredError`) are surfaced through their own dedicated
+ * channels (`onExpired` / the session-expired event) and carry SDK-internal
+ * English messages. They are NOT routed to `onMutationError`, whose error is
+ * meant to be surfaceable to the buyer.
+ */
+function isDedicatedChannelError(err) {
+    return err instanceof CartRecoveryNotPossibleError || err instanceof CartSessionRequiredError;
+}
 export function useCartManager(options) {
     const { cartClient } = useStorefrontClientContext();
     const [status, setStatus] = useState({ type: 'idle' });
     // Cookie store is stateless — keep one instance per hook mount.
     const cookieStore = useMemo(() => createBrowserCartCookieStore(), []);
+    // Latest-callback ref: the mutation wrapper reads `lifecycleRef.current` so it
+    // always fires the current callbacks while keeping its own deps array empty
+    // (a stable `wrapMutation` avoids rebuilding every mutation on each render).
+    const lifecycleRef = useRef({});
+    lifecycleRef.current = {
+        onMutationStart: options?.onMutationStart,
+        onMutationSuccess: options?.onMutationSuccess,
+        onMutationError: options?.onMutationError,
+    };
     // Normalize seed so the runner identity is stable across `undefined` /
     // `null` props and only flips when the storefront actually swaps the seed.
     const initialCartId = options?.initialCartId ?? null;
@@ -113,14 +146,19 @@ export function useCartManager(options) {
     // recovery semantics to the runner (which fires onExpired separately).
     const wrapMutation = useCallback(async (operation, run, failureFallbackMessage) => {
         setStatus({ type: 'loading', operation });
+        safeInvoke(() => lifecycleRef.current.onMutationStart?.(operation));
         try {
             const result = await run();
             setStatus({ type: 'success', operation });
+            safeInvoke(() => lifecycleRef.current.onMutationSuccess?.(operation));
             return result;
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(failureFallbackMessage);
             setStatus({ type: 'error', operation, error });
+            if (!isDedicatedChannelError(error)) {
+                safeInvoke(() => lifecycleRef.current.onMutationError?.(operation, error));
+            }
             throw err;
         }
     }, []);
@@ -206,6 +244,7 @@ export function useCartManager(options) {
      */
     const complete = useCallback(async (input) => {
         setStatus({ type: 'loading', operation: 'complete' });
+        safeInvoke(() => lifecycleRef.current.onMutationStart?.('complete'));
         try {
             const result = await runner.execute({
                 name: 'complete',
@@ -213,11 +252,15 @@ export function useCartManager(options) {
             });
             cookieStore.clear();
             setStatus({ type: 'idle' });
+            safeInvoke(() => lifecycleRef.current.onMutationSuccess?.('complete'));
             return result;
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error('Failed to complete cart');
             setStatus({ type: 'error', operation: 'complete', error });
+            if (!isDedicatedChannelError(error)) {
+                safeInvoke(() => lifecycleRef.current.onMutationError?.('complete', error));
+            }
             throw err;
         }
     }, [runner, cartClient, cookieStore]);
@@ -237,7 +280,11 @@ export function useCartManager(options) {
     // Backward-compatible derived selectors over the tagged-union status.
     const isLoading = status.type === 'loading';
     const error = status.type === 'error' ? status.error.message : null;
-    return {
+    // Memoize the aggregate so the object identity changes only when `status`
+    // flips (the sole reactive field) — every method is already useCallback-stable.
+    // Keeps `<CartManagerProvider>`'s Context value referentially stable across
+    // unrelated re-renders, matching the sibling StorefrontClientProvider.
+    return useMemo(() => ({
         getCart,
         getCartId,
         addItem,
@@ -262,5 +309,30 @@ export function useCartManager(options) {
         status,
         isLoading,
         error,
-    };
+    }), [
+        getCart,
+        getCartId,
+        addItem,
+        updateBuyerIdentity,
+        setShippingAddress,
+        updateDiscountCodes,
+        updateNote,
+        updateAttributes,
+        updateItem,
+        removeItem,
+        setBillingAddress,
+        selectShippingMethod,
+        selectPaymentMethod,
+        clearPaymentSelection,
+        applyGiftCard,
+        removeGiftCard,
+        updateGiftCardRecipient,
+        complete,
+        createPayment,
+        clearCart,
+        onExpired,
+        status,
+        isLoading,
+        error,
+    ]);
 }

package/dist/react/index.d.ts

@@ -15,6 +15,7 @@ export { StorefrontProvider, type StorefrontProviderProps } from './providers/st
 export { StorefrontClientProvider, type StorefrontClientProviderProps } from './providers/storefront-client-provider';
 export { CurrencyProvider, type CurrencyProviderProps } from './providers/currency-provider';
 export { LanguageProvider, type LanguageProviderProps } from './providers/language-provider';
+export { CartManagerProvider, useCartManagerContext, type CartManagerProviderProps } from './providers/cart-manager-provider';
 export { useAuth, type UseAuthOptions, type LoginResult, type LogoutResult, type TokenRefreshResult } from './hooks/use-auth';
 export { useLogin, type UseLoginOptions, type UseLoginReturn } from './hooks/use-login';
 export { useLogout, type UseLogoutOptions, type UseLogoutReturn } from './hooks/use-logout';
@@ -22,7 +23,7 @@ export { useRefreshToken, type UseRefreshTokenOptions, type UseRefreshTokenRetur
 export { useSessionRefresh, type UseSessionRefreshOptions } from './hooks/use-session-refresh';
 export { useSessionExpired } from './hooks/use-session-expired';
 export type { SessionExpiredEvent, SessionExpiredReason, SessionExpiredEmitter } from '../core/auth/session-events';
-export { useCartManager, type CartManagerOperation, type CartManagerStatus, type UseCartManagerResult } from './hooks/use-cart-manager';
+export { useCartManager, type CartManagerOperation, type CartManagerStatus, type UseCartManagerResult, type UseCartManagerOptions, type CartManagerLifecycleCallbacks } from './hooks/use-cart-manager';
 export { useCart, type UseCartOptions, type UseCartResult, type ServerCartOperation } from './hooks/use-cart';
 export { useStorefrontClient } from './hooks/use-storefront-client';
 export { useCurrency } from './hooks/use-currency';
@@ -35,7 +36,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, createBrowserCartCookieStore, } from './cookies';
+export { getCookie, setCookie, deleteCookie, 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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -16,6 +16,7 @@ export { StorefrontProvider } from './providers/storefront-provider';
 export { StorefrontClientProvider } from './providers/storefront-client-provider';
 export { CurrencyProvider } from './providers/currency-provider';
 export { LanguageProvider } from './providers/language-provider';
+export { CartManagerProvider, useCartManagerContext } from './providers/cart-manager-provider';
 // Hooks
 export { useAuth } from './hooks/use-auth';
 export { useLogin } from './hooks/use-login';
@@ -34,8 +35,9 @@ export { useLanguageStore, useLanguageStoreApi } from './stores/store-context';
 // Selectors
 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, createBrowserCartCookieStore, } from './cookies';
+// Cookie utilities (client-side). Server-side readers (readCartIdCookie,
+// readCurrencyCookie) live in `@doswiftly/storefront-sdk/react/server`.
+export { getCookie, setCookie, deleteCookie, createBrowserCartCookieStore, } from './cookies';
 // Bot protection
 export { useBotProtection } from './hooks/use-bot-protection';
 // Generic hooks

package/dist/react/providers/cart-manager-provider.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CartManagerProvider — shares a single `useCartManager` instance across the tree.
+ *
+ * `useCartManager` owns per-mount state (status, recovery coordinator, cart-expired
+ * listeners), so calling it in several components creates independent managers
+ * with separate loading state and separate recovery queues. Wrap the checkout
+ * subtree in `<CartManagerProvider>` and read the shared instance with
+ * `useCartManagerContext()` to get one source of truth: one loading indicator,
+ * one recovery coordinator, one cart-expired subscription.
+ *
+ * Must be rendered inside `<StorefrontProvider>` — it builds on the storefront
+ * client from context. For deliberately independent managers (e.g. a multi-cart
+ * admin view) call `useCartManager()` directly instead of using this provider.
+ *
+ * @example
+ * ```tsx
+ * // app/checkout/page.tsx — Server Component resolves the cart-id
+ * <CartManagerProvider
+ *   initialCartId={cartId}
+ *   onMutationError={(operation, error) => toast.error(error.message)}
+ *   onMutationSuccess={() => router.refresh()}
+ * >
+ *   <CheckoutForm />
+ * </CartManagerProvider>
+ *
+ * // CheckoutForm.tsx
+ * const { addItem, complete, status } = useCartManagerContext();
+ * ```
+ */
+import { type ReactNode } from 'react';
+import { type CartManagerLifecycleCallbacks, type UseCartManagerResult } from '../hooks/use-cart-manager';
+export interface CartManagerProviderProps extends CartManagerLifecycleCallbacks {
+    /**
+     * Server-known cart-id seed forwarded to `useCartManager`. Used only when the
+     * `cart-id` cookie is empty on mount — the cookie always wins when present.
+     */
+    initialCartId?: string | null;
+    children: ReactNode;
+}
+/**
+ * Creates one `useCartManager` instance and exposes it to descendants via
+ * Context. Lifecycle callbacks are forwarded to the underlying hook.
+ */
+export declare function CartManagerProvider({ initialCartId, onMutationStart, onMutationSuccess, onMutationError, children, }: CartManagerProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the shared cart manager provided by the nearest `<CartManagerProvider>`.
+ * Throws when called outside a provider.
+ */
+export declare function useCartManagerContext(): UseCartManagerResult;
+//# sourceMappingURL=cart-manager-provider.d.ts.map

package/dist/react/providers/cart-manager-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart-manager-provider.d.ts","sourceRoot":"","sources":["../../../src/react/providers/cart-manager-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClE,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAKnC,MAAM,WAAW,wBAAyB,SAAQ,6BAA6B;IAC7E;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,QAAQ,GACT,EAAE,wBAAwB,2CAS1B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAM5D"}

package/dist/react/providers/cart-manager-provider.js

@@ -0,0 +1,59 @@
+/**
+ * CartManagerProvider — shares a single `useCartManager` instance across the tree.
+ *
+ * `useCartManager` owns per-mount state (status, recovery coordinator, cart-expired
+ * listeners), so calling it in several components creates independent managers
+ * with separate loading state and separate recovery queues. Wrap the checkout
+ * subtree in `<CartManagerProvider>` and read the shared instance with
+ * `useCartManagerContext()` to get one source of truth: one loading indicator,
+ * one recovery coordinator, one cart-expired subscription.
+ *
+ * Must be rendered inside `<StorefrontProvider>` — it builds on the storefront
+ * client from context. For deliberately independent managers (e.g. a multi-cart
+ * admin view) call `useCartManager()` directly instead of using this provider.
+ *
+ * @example
+ * ```tsx
+ * // app/checkout/page.tsx — Server Component resolves the cart-id
+ * <CartManagerProvider
+ *   initialCartId={cartId}
+ *   onMutationError={(operation, error) => toast.error(error.message)}
+ *   onMutationSuccess={() => router.refresh()}
+ * >
+ *   <CheckoutForm />
+ * </CartManagerProvider>
+ *
+ * // CheckoutForm.tsx
+ * const { addItem, complete, status } = useCartManagerContext();
+ * ```
+ */
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+import { useCartManager, } from '../hooks/use-cart-manager';
+const CartManagerContext = createContext(null);
+CartManagerContext.displayName = 'CartManagerContext';
+/**
+ * Creates one `useCartManager` instance and exposes it to descendants via
+ * Context. Lifecycle callbacks are forwarded to the underlying hook.
+ */
+export function CartManagerProvider({ initialCartId, onMutationStart, onMutationSuccess, onMutationError, children, }) {
+    const manager = useCartManager({
+        initialCartId,
+        onMutationStart,
+        onMutationSuccess,
+        onMutationError,
+    });
+    return _jsx(CartManagerContext.Provider, { value: manager, children: children });
+}
+/**
+ * Read the shared cart manager provided by the nearest `<CartManagerProvider>`.
+ * Throws when called outside a provider.
+ */
+export function useCartManagerContext() {
+    const ctx = useContext(CartManagerContext);
+    if (!ctx) {
+        throw new Error('useCartManagerContext must be used within CartManagerProvider');
+    }
+    return ctx;
+}

package/dist/react/server/cookie-readers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-first readers for the storefront's readable first-party cookies.
+ *
+ * `readCartIdCookie` / `readCurrencyCookie` return the `cart-id` /
+ * `preferred-currency` cookie value. They run server-first: in a Next.js Server
+ * Component they read the request cookies via `next/headers`; when that is
+ * unavailable (client bundle, build time, non-Next runtime) they fall back to
+ * `document.cookie`. This isomorphic behaviour is deliberate and safe here
+ * because both cookies are readable (NOT httpOnly) — unlike the auth token,
+ * which `getInitialAuth` reads server-only precisely because it is httpOnly.
+ *
+ * They live under `@doswiftly/storefront-sdk/react/server` so the `next/headers`
+ * dependency stays out of the client entry; the dynamic import keeps importing
+ * this module safe in runtimes without `next/headers`.
+ *
+ * @example
+ * ```tsx
+ * // app/checkout/page.tsx (Server Component)
+ * import { readCartIdCookie } from '@doswiftly/storefront-sdk/react/server';
+ *
+ * const cartId = await readCartIdCookie();
+ * const cart = cartId ? await fetchCart(cartId) : null;
+ * ```
+ */
+/** Read the first-party `cart-id` cookie (server-first, client fallback). */
+export declare function readCartIdCookie(): Promise<string | null>;
+/** Read the first-party `preferred-currency` cookie (server-first, client fallback). */
+export declare function readCurrencyCookie(): Promise<string | null>;
+//# sourceMappingURL=cookie-readers.d.ts.map

package/dist/react/server/cookie-readers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-readers.d.ts","sourceRoot":"","sources":["../../../src/react/server/cookie-readers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAuBH,6EAA6E;AAC7E,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE/D;AAED,wFAAwF;AACxF,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEjE"}

package/dist/react/server/cookie-readers.js

@@ -0,0 +1,52 @@
+/**
+ * Server-first readers for the storefront's readable first-party cookies.
+ *
+ * `readCartIdCookie` / `readCurrencyCookie` return the `cart-id` /
+ * `preferred-currency` cookie value. They run server-first: in a Next.js Server
+ * Component they read the request cookies via `next/headers`; when that is
+ * unavailable (client bundle, build time, non-Next runtime) they fall back to
+ * `document.cookie`. This isomorphic behaviour is deliberate and safe here
+ * because both cookies are readable (NOT httpOnly) — unlike the auth token,
+ * which `getInitialAuth` reads server-only precisely because it is httpOnly.
+ *
+ * They live under `@doswiftly/storefront-sdk/react/server` so the `next/headers`
+ * dependency stays out of the client entry; the dynamic import keeps importing
+ * this module safe in runtimes without `next/headers`.
+ *
+ * @example
+ * ```tsx
+ * // app/checkout/page.tsx (Server Component)
+ * import { readCartIdCookie } from '@doswiftly/storefront-sdk/react/server';
+ *
+ * const cartId = await readCartIdCookie();
+ * const cart = cartId ? await fetchCart(cartId) : null;
+ * ```
+ */
+import { CART_COOKIE_NAME } from '../../core/cart/cookie-config';
+import { CURRENCY_COOKIE_NAME } from '../../core/currency/cookie-config';
+import { getCookie } from '../cookies';
+/**
+ * Read a cookie server-first: the request cookies via `next/headers` in a Server
+ * Component, falling back to `document.cookie` on the client / outside a request
+ * scope. Returns null when the cookie is absent on both sides.
+ */
+async function readCookieIsomorphic(name) {
+    try {
+        const { cookies } = await import('next/headers');
+        const store = await cookies();
+        return store.get(name)?.value ?? null;
+    }
+    catch {
+        // No Next.js server request scope (client bundle, build time, non-Next
+        // runtime) — fall back to the client reader (null on the server).
+        return getCookie(name);
+    }
+}
+/** Read the first-party `cart-id` cookie (server-first, client fallback). */
+export async function readCartIdCookie() {
+    return readCookieIsomorphic(CART_COOKIE_NAME);
+}
+/** Read the first-party `preferred-currency` cookie (server-first, client fallback). */
+export async function readCurrencyCookie() {
+    return readCookieIsomorphic(CURRENCY_COOKIE_NAME);
+}

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

@@ -1,5 +1,6 @@
 export { getStorefrontClient, type ServerClientOptions } from './get-storefront-client';
 export { createStorefrontAuthRoute, type StorefrontAuthRouteOptions, type StorefrontAuthRouteHandlers, } from './create-storefront-auth-route';
 export { getInitialAuth, type InitialAuth } from './get-initial-auth';
+export { readCartIdCookie, readCurrencyCookie } from './cookie-readers';
 export { trustedForwardedHostValidator, originAllowlistValidator, type OriginValidator, type OriginValidatorContext, } from '../../core/auth/handlers';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGxF,OAAO,EACL,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGxF,OAAO,EACL,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGxE,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAC"}

package/dist/react/server/index.js

@@ -3,5 +3,7 @@ export { getStorefrontClient } from './get-storefront-client';
 export { createStorefrontAuthRoute, } from './create-storefront-auth-route';
 // Server-only cold-start auth seed from the first-party cookies.
 export { getInitialAuth } from './get-initial-auth';
+// Server-first readers for the readable first-party cookies (cart-id, currency).
+export { readCartIdCookie, readCurrencyCookie } from './cookie-readers';
 // Origin validators — wire CSRF defense-in-depth on the route handlers from a single import.
 export { trustedForwardedHostValidator, originAllowlistValidator, } from '../../core/auth/handlers';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,