@doswiftly/storefront-sdk 17.0.0 → 18.0.0

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

@@ -7,23 +7,53 @@
  *
  * 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.                                           |
+ * | 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                        |
+ * | `updateAttributes`         | Auto-replay                           | Stateless metadata — atomic re-create OK      |
+ * | `updateItem`               | Bail + `cart-expired` event           | `lineId` refers to a line in the dead cart    |
+ * | `removeItem`               | Bail + `cart-expired` event           | jw.                                           |
+ * | `setBillingAddress`        | Bail + `cart-expired` event           | Cart must exist (separate from shipping)      |
+ * | `selectShippingMethod`     | Bail + `cart-expired` event           | Method tied to cart contents + address        |
+ * | `selectPaymentMethod`      | Bail + `cart-expired` event           | Payment selection on existing cart state      |
+ * | `clearPaymentSelection`    | Bail + `cart-expired` event           | Operates on existing cart payment fields      |
+ * | `applyGiftCard`            | Bail + `cart-expired` event           | Balance allocation tied to cart total         |
+ * | `removeGiftCard`           | Bail + `cart-expired` event           | `giftCardId` refers to row on dead cart       |
+ * | `updateGiftCardRecipient`  | Bail + `cart-expired` event           | `lineId` refers to a line in the dead cart    |
+ * | `complete`                 | Bail + `cart-expired` event           | Finalised cart cannot be auto-recreated       |
+ * | `createPayment`            | Out of recovery scope                 | Operates on `orderId` (post-complete)         |
  *
  * 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.
  *
+ * After `complete` success the hook auto-clears the `cart-id` cookie and
+ * resets status to `idle` — buyer returning to `/checkout` (back from the
+ * payment gateway, deep link, new tab) gets a fresh empty cart instead of the
+ * CONVERTED cart. Manual `clearCart()` remains available as an escape hatch.
+ *
  * Auto-creates cart on first add. Cart id persisted in `cart-id` cookie
  * (SSR/edge visible, 30 days, samesite=lax).
  *
+ * ### Server-known cart-id (env seed, magic-link, iframe, customer service)
+ *
+ * Pass `{ initialCartId }` to seed the hook with a cart-id resolved server-side
+ * (read from URL params in a Route Handler, env var for dev fixtures, parent
+ * `postMessage` for embedded iframe, admin "view this cart" lookup). The hook
+ * applies priority `cookie wins → seed → auto-create`. The seed is eagerly
+ * written to the cart-id cookie so cross-tab tabs and standard recovery
+ * semantics operate on a canonical value. A stale seed goes through the same
+ * recovery flow as a stale cookie — `addItem` auto-replays through
+ * `cartCreate({ lines })`, state-dependent ops bail with `cart-expired`.
+ *
+ * Mirrors the `<StorefrontProvider initialAccessToken>` pattern for the
+ * cart-id half of the checkout state — both are seeds for the first render
+ * when the client cannot read the canonical source itself.
+ *
  * @example
  * ```tsx
  * function CartUI() {
@@ -34,21 +64,46 @@
  *   return <button onClick={() => addItem([{ variantId, quantity: 1 }])}>Add</button>;
  * }
  * ```
+ *
+ * @example Server-known cart-id
+ * ```tsx
+ * // app/checkout/page.tsx — Server Component
+ * import { cookies } from 'next/headers';
+ * import { CART_COOKIE_NAME } from '@doswiftly/storefront-sdk';
+ *
+ * export default async function CheckoutPage() {
+ *   const cookieJar = await cookies();
+ *   const initialCartId =
+ *     cookieJar.get(CART_COOKIE_NAME)?.value ?? process.env.NEXT_PUBLIC_DEV_CART_ID ?? null;
+ *   return <CheckoutClient initialCartId={initialCartId} />;
+ * }
+ *
+ * // CheckoutClient.tsx — 'use client'
+ * function CheckoutClient({ initialCartId }: { initialCartId: string | null }) {
+ *   const { complete, selectPaymentMethod, addItem } = useCartManager({ initialCartId });
+ *   // ... rest unchanged — hook handles seed → cookie → recovery transparently
+ * }
+ * ```
  */
 'use client';
 import { useCallback, useMemo, useState } from 'react';
 import { useStorefrontClientContext } from '../providers/storefront-client-provider';
 import { createCartRecoveryRunner, recreateWithInput, } from '../../core/cart/cart-recovery';
 import { createBrowserCartCookieStore } from '../cookies';
-export function useCartManager() {
+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(), []);
+    // 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;
     // 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]);
+    // recovery coordinator (Phase 0 mutex). `initialCartId` is part of the
+    // identity so a switch (e.g. cart switcher in a multi-cart B2B UI) rebuilds
+    // the runner instead of carrying the previous seed forward.
+    const runner = useMemo(() => createCartRecoveryRunner({ cartClient, cookieStore, initialCartId }), [cartClient, cookieStore, initialCartId]);
     // 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
@@ -98,6 +153,11 @@ export function useCartManager() {
         run: (cartId) => cartClient.updateNote(cartId, note),
         recreateAndRun: recreateWithInput({ note }),
     }), 'Failed to update note'), [runner, cartClient, wrapMutation]);
+    const updateAttributes = useCallback((attributes) => wrapMutation('updateAttributes', () => runner.execute({
+        name: 'updateAttributes',
+        run: (cartId) => cartClient.updateAttributes(cartId, attributes),
+        recreateAndRun: recreateWithInput({ attributes }),
+    }), 'Failed to update cart attributes'), [runner, cartClient, wrapMutation]);
     // --- Bail-on-stale mutations (no recreateAndRun — fires onExpired + throws) ---
     const updateItem = useCallback((lines) => wrapMutation('updateItem', () => runner.execute({
         name: 'updateItem',
@@ -107,6 +167,68 @@ export function useCartManager() {
         name: 'removeItem',
         run: (cartId) => cartClient.removeItems(cartId, lineIds),
     }), 'Failed to remove from cart'), [runner, cartClient, wrapMutation]);
+    const setBillingAddress = useCallback((address) => wrapMutation('setBillingAddress', () => runner.execute({
+        name: 'setBillingAddress',
+        run: (cartId) => cartClient.setBillingAddress({ cartId, address }),
+    }), 'Failed to set billing address'), [runner, cartClient, wrapMutation]);
+    const selectShippingMethod = useCallback((input) => wrapMutation('selectShippingMethod', () => runner.execute({
+        name: 'selectShippingMethod',
+        run: (cartId) => cartClient.selectShippingMethod({ cartId, ...input }),
+    }), 'Failed to select shipping method'), [runner, cartClient, wrapMutation]);
+    const selectPaymentMethod = useCallback((input) => wrapMutation('selectPaymentMethod', () => runner.execute({
+        name: 'selectPaymentMethod',
+        run: (cartId) => cartClient.selectPaymentMethod({ cartId, ...input }),
+    }), 'Failed to select payment method'), [runner, cartClient, wrapMutation]);
+    const clearPaymentSelection = useCallback((input) => wrapMutation('clearPaymentSelection', () => runner.execute({
+        name: 'clearPaymentSelection',
+        run: (cartId) => cartClient.clearPaymentSelection({ cartId, ...(input ?? {}) }),
+    }), 'Failed to clear payment selection'), [runner, cartClient, wrapMutation]);
+    const applyGiftCard = useCallback((input) => wrapMutation('applyGiftCard', () => runner.execute({
+        name: 'applyGiftCard',
+        run: (cartId) => cartClient.applyGiftCard({ cartId, ...input }),
+    }), 'Failed to apply gift card'), [runner, cartClient, wrapMutation]);
+    const removeGiftCard = useCallback((input) => wrapMutation('removeGiftCard', () => runner.execute({
+        name: 'removeGiftCard',
+        run: (cartId) => cartClient.removeGiftCard({ cartId, ...input }),
+    }), 'Failed to remove gift card'), [runner, cartClient, wrapMutation]);
+    const updateGiftCardRecipient = useCallback((input) => wrapMutation('updateGiftCardRecipient', () => runner.execute({
+        name: 'updateGiftCardRecipient',
+        run: (cartId) => cartClient.updateGiftCardRecipient({ cartId, ...input }),
+    }), 'Failed to update gift card recipient'), [runner, cartClient, wrapMutation]);
+    // --- Completion lifecycle ---
+    /**
+     * Bail-on-stale completion. On success the cart is CONVERTED/locked, so the
+     * hook auto-clears the cart cookie and resets status to `idle`. A follow-up
+     * `addItem` recreates a fresh cart through the standard recovery runner.
+     * `wrapMutation` is intentionally bypassed — its success path leaves status
+     * as `{ type: 'success', operation: 'complete' }`, but the cart no longer
+     * exists in the cookie state, so `idle` is the truthful representation.
+     */
+    const complete = useCallback(async (input) => {
+        setStatus({ type: 'loading', operation: 'complete' });
+        try {
+            const result = await runner.execute({
+                name: 'complete',
+                run: (cartId) => cartClient.complete({ cartId, ...(input ?? {}) }),
+            });
+            cookieStore.clear();
+            setStatus({ type: 'idle' });
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Failed to complete cart');
+            setStatus({ type: 'error', operation: 'complete', error });
+            throw err;
+        }
+    }, [runner, cartClient, cookieStore]);
+    /**
+     * Payment session creation. NOT a cart operation (works on `orderId` from
+     * `complete().order.id`) so the recovery runner is bypassed — there is no
+     * cart to recover from. Wrapped in `wrapMutation` only for status tracking
+     * so consumers can render a single `<Spinner label={status.operation} />`
+     * across the whole checkout lifecycle.
+     */
+    const createPayment = useCallback((input) => wrapMutation('createPayment', () => cartClient.createPayment(input), 'Failed to create payment'), [cartClient, wrapMutation]);
     // --- Lifecycle ---
     const clearCart = useCallback(() => {
         cookieStore.clear();
@@ -123,8 +245,18 @@ export function useCartManager() {
         setShippingAddress,
         updateDiscountCodes,
         updateNote,
+        updateAttributes,
         updateItem,
         removeItem,
+        setBillingAddress,
+        selectShippingMethod,
+        selectPaymentMethod,
+        clearPaymentSelection,
+        applyGiftCard,
+        removeGiftCard,
+        updateGiftCardRecipient,
+        complete,
+        createPayment,
         clearCart,
         onExpired,
         status,

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

@@ -1 +1 @@
-{"version":3,"file":"use-login.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-login.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,gHAAgH;IAChH,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,0GAA0G;IAC1G,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CA+DtE"}
+{"version":3,"file":"use-login.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-login.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,gHAAgH;IAChH,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,0GAA0G;IAC1G,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAgEtE"}

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

@@ -40,14 +40,14 @@ export function useLogin(options = {}) {
                         firstName: customer.firstName ?? undefined,
                         lastName: customer.lastName ?? undefined,
                         phone: customer.phone ?? undefined,
-                    }, result.accessToken);
+                    }, result.accessToken, result.expiresAt);
                 }
                 else {
-                    setAuth({ id: '', email }, result.accessToken);
+                    setAuth({ id: '', email }, result.accessToken, result.expiresAt);
                 }
             }
             catch {
-                setAuth({ id: '', email }, result.accessToken);
+                setAuth({ id: '', email }, result.accessToken, result.expiresAt);
             }
             return {
                 success: true,

package/dist/react/hooks/use-refresh-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-refresh-token.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-refresh-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,WAAW,sBAAsB;IACrC,qFAAqF;IACrF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,YAAY,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChD,mDAAmD;IACnD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,yFAAyF;IACzF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,qBAAqB,CA+C3F"}
+{"version":3,"file":"use-refresh-token.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-refresh-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,WAAW,sBAAsB;IACrC,qFAAqF;IACrF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,YAAY,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChD,mDAAmD;IACnD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,yFAAyF;IACzF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,qBAAqB,CAiD3F"}

package/dist/react/hooks/use-refresh-token.js

@@ -36,10 +36,12 @@ export function useRefreshToken(options = {}) {
             if (options.onSetToken) {
                 await options.onSetToken(result.accessToken);
             }
-            const currentCustomer = authStore.getState().customer;
-            if (currentCustomer) {
-                setAuth(currentCustomer, result.accessToken);
-            }
+            // Thread the new token + expiry into the store unconditionally — `setAuth`
+            // accepts a null customer, so a server-seeded session without a loaded
+            // profile (SSO callback / magic link / dev seed) still gets its refreshed
+            // `expiresAt`, keeping the proactive scheduler armed (parity with the
+            // in-provider refresh + scheduler, which also pass `getState().customer`).
+            setAuth(authStore.getState().customer, result.accessToken, result.expiresAt);
             return {
                 success: true,
                 userErrors: [],

package/dist/react/hooks/use-session-expired.d.ts

@@ -0,0 +1,16 @@
+/**
+ * useSessionExpired — subscribe to the global session-expired signal.
+ *
+ * Fired when the SDK can no longer keep the customer session alive: a proactive
+ * refresh failed on tab wake (R6.3), or a reactive refresh after a 401 also
+ * failed (R2.4). Use once near the app root to react globally — show a notice
+ * and redirect to sign-in (R14.2). No-op outside `StorefrontProvider`.
+ */
+import type { SessionExpiredEmitter, SessionExpiredEvent } from '../../core/auth/session-events';
+/**
+ * Context carrying the provider-scoped session-expired emitter. Created in
+ * `StorefrontProvider` via `useRef` (Inv-3 — never a module-level singleton).
+ */
+export declare const SessionExpiredContext: import("react").Context<SessionExpiredEmitter | null>;
+export declare function useSessionExpired(listener: (event: SessionExpiredEvent) => void): void;
+//# sourceMappingURL=use-session-expired.d.ts.map

package/dist/react/hooks/use-session-expired.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-session-expired.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-session-expired.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAEjG;;;GAGG;AACH,eAAO,MAAM,qBAAqB,uDAAoD,CAAC;AAEvF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,CAUtF"}

package/dist/react/hooks/use-session-expired.js

@@ -0,0 +1,26 @@
+/**
+ * useSessionExpired — subscribe to the global session-expired signal.
+ *
+ * Fired when the SDK can no longer keep the customer session alive: a proactive
+ * refresh failed on tab wake (R6.3), or a reactive refresh after a 401 also
+ * failed (R2.4). Use once near the app root to react globally — show a notice
+ * and redirect to sign-in (R14.2). No-op outside `StorefrontProvider`.
+ */
+'use client';
+import { createContext, useContext, useEffect, useRef } from 'react';
+/**
+ * Context carrying the provider-scoped session-expired emitter. Created in
+ * `StorefrontProvider` via `useRef` (Inv-3 — never a module-level singleton).
+ */
+export const SessionExpiredContext = createContext(null);
+export function useSessionExpired(listener) {
+    const emitter = useContext(SessionExpiredContext);
+    // Keep the latest listener without re-subscribing on every render.
+    const ref = useRef(listener);
+    ref.current = listener;
+    useEffect(() => {
+        if (!emitter)
+            return;
+        return emitter.subscribe((event) => ref.current(event));
+    }, [emitter]);
+}

package/dist/react/hooks/use-session-refresh.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useSessionRefresh — proactive, browser-only session-refresh scheduler.
+ *
+ * Renews the access token shortly *before* it expires so an active buyer is
+ * never logged out mid-session, reschedules from each new expiry, and never runs
+ * on the server. On tab wake after the token already lapsed it tries once and —
+ * if the session can no longer be recovered — emits `session-expired` and clears
+ * local auth.
+ *
+ * The refresh goes through the same-origin BFF route via
+ * `AuthClient.refreshSession()` (`POST {authBasePath}/refresh`). The route handler
+ * reads the httpOnly refresh cookie server-side, rotates it against the backend,
+ * and sets the new first-party cookies — so an ALREADY-EXPIRED access token still
+ * refreshes (the old GraphQL `customerRefreshToken` could not, as it needed a
+ * valid access token). No `setToken` round-trip and no consumer callback.
+ *
+ * The timer lives in the effect closure (provider lifecycle), never in module state.
+ */
+import type { SessionExpiredEmitter } from '../../core/auth/session-events';
+export interface UseSessionRefreshOptions {
+    /** Master switch. Defaults to `true` in the browser, `false` on the server. */
+    enabled?: boolean;
+    /** Refresh this many ms before the token's `expiresAt` (default 60_000). */
+    bufferMs?: number;
+    /**
+     * Emitter the scheduler notifies when a wake-time refresh cannot recover the
+     * session. Provided by `StorefrontProvider`; subscribe via `useSessionExpired`.
+     */
+    sessionExpiredEmitter?: SessionExpiredEmitter;
+}
+export declare function useSessionRefresh(options?: UseSessionRefreshOptions): void;
+//# sourceMappingURL=use-session-refresh.d.ts.map

package/dist/react/hooks/use-session-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-session-refresh.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-session-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE5E,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CAC/C;AAYD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,IAAI,CAkH9E"}

package/dist/react/hooks/use-session-refresh.js

@@ -0,0 +1,147 @@
+/**
+ * useSessionRefresh — proactive, browser-only session-refresh scheduler.
+ *
+ * Renews the access token shortly *before* it expires so an active buyer is
+ * never logged out mid-session, reschedules from each new expiry, and never runs
+ * on the server. On tab wake after the token already lapsed it tries once and —
+ * if the session can no longer be recovered — emits `session-expired` and clears
+ * local auth.
+ *
+ * The refresh goes through the same-origin BFF route via
+ * `AuthClient.refreshSession()` (`POST {authBasePath}/refresh`). The route handler
+ * reads the httpOnly refresh cookie server-side, rotates it against the backend,
+ * and sets the new first-party cookies — so an ALREADY-EXPIRED access token still
+ * refreshes (the old GraphQL `customerRefreshToken` could not, as it needed a
+ * valid access token). No `setToken` round-trip and no consumer callback.
+ *
+ * The timer lives in the effect closure (provider lifecycle), never in module state.
+ */
+'use client';
+import { useEffect, useRef } from 'react';
+import { useAuthStoreApi } from '../stores/store-context';
+import { useStorefrontClientContext } from '../providers/storefront-client-provider';
+const DEFAULT_BUFFER_MS = 60_000;
+/** Backoff before retrying a proactive refresh that failed while the token was still valid. */
+const PROACTIVE_RETRY_MS = 15_000;
+/**
+ * When the token is already within the buffer window but still valid, space out
+ * refreshes by this much so a token whose lifetime is <= the buffer cannot
+ * busy-loop the scheduler.
+ */
+const WITHIN_BUFFER_RETRY_MS = 5_000;
+export function useSessionRefresh(options = {}) {
+    const { enabled, bufferMs = DEFAULT_BUFFER_MS, sessionExpiredEmitter } = options;
+    const isBrowser = typeof window !== 'undefined';
+    const active = (enabled ?? isBrowser) && isBrowser;
+    const { authClient } = useStorefrontClientContext();
+    const authStore = useAuthStoreApi();
+    // Moving parts in refs so the scheduling effect re-runs only on structural
+    // deps (active / bufferMs / authBasePath / store identity), not on every render.
+    const authClientRef = useRef(authClient);
+    authClientRef.current = authClient;
+    const emitterRef = useRef(sessionExpiredEmitter);
+    emitterRef.current = sessionExpiredEmitter;
+    useEffect(() => {
+        if (!active)
+            return;
+        let timer;
+        let disposed = false;
+        let inFlight = false;
+        // Tracks the expiry we last scheduled against, so the store subscription
+        // ignores our own writes (we reschedule explicitly after a refresh).
+        let lastExpiresAt = authStore.getState().expiresAt;
+        const clearTimer = () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        };
+        const doRefresh = async (tokenAlreadyExpired) => {
+            if (inFlight)
+                return;
+            inFlight = true;
+            try {
+                // Same-origin BFF refresh: the route reads the httpOnly refresh cookie
+                // server-side, rotates it against the backend, and sets the new
+                // first-party cookies. No `setToken` round-trip — the route owns the cookie.
+                const result = await authClientRef.current.refreshSession();
+                if (disposed)
+                    return;
+                lastExpiresAt = result.expiresAt;
+                authStore.getState().setAuth(authStore.getState().customer, result.accessToken, result.expiresAt);
+                schedule();
+            }
+            catch (err) {
+                if (disposed)
+                    return;
+                if (tokenAlreadyExpired) {
+                    // The access token had already lapsed and the BFF refresh could not
+                    // recover the session (refresh token expired/reused/revoked). Clear
+                    // local auth and notify so the storefront can prompt re-login.
+                    authStore.getState().clearAuth();
+                    emitterRef.current?.emit({ reason: 'wake-refresh-failed', cause: err });
+                }
+                else {
+                    // Token still valid — a proactive refresh failed transiently
+                    // (network / server blip). Do NOT log the buyer out; retry shortly.
+                    clearTimer();
+                    timer = setTimeout(schedule, PROACTIVE_RETRY_MS);
+                }
+            }
+            finally {
+                inFlight = false;
+            }
+        };
+        const schedule = () => {
+            clearTimer();
+            const { expiresAt, isAuthenticated } = authStore.getState();
+            if (!expiresAt || !isAuthenticated)
+                return;
+            const expiryMs = new Date(expiresAt).getTime();
+            if (Number.isNaN(expiryMs))
+                return;
+            const now = Date.now();
+            let fireIn;
+            if (now >= expiryMs) {
+                // Already expired (e.g. tab slept past expiry) — recover ASAP.
+                fireIn = 0;
+            }
+            else {
+                const untilBuffer = expiryMs - bufferMs - now;
+                // Within the buffer but still valid — space retries so a token whose
+                // lifetime is <= the buffer cannot busy-loop.
+                fireIn = untilBuffer > 0 ? untilBuffer : WITHIN_BUFFER_RETRY_MS;
+            }
+            // ALWAYS arm a timer — never call doRefresh synchronously. A synchronous
+            // call can re-enter while a refresh is in flight and be dropped by the
+            // in-flight guard, leaving the scheduler permanently stalled; the timer
+            // fires after the current call stack, by which point `inFlight` has reset.
+            // `tokenAlreadyExpired` is re-derived at fire time (the clock has moved).
+            timer = setTimeout(() => void doRefresh(Date.now() >= expiryMs), fireIn);
+        };
+        // Reschedule when expiresAt changes from outside (login, manual refresh).
+        const unsubscribe = authStore.subscribe((state) => {
+            if (disposed)
+                return;
+            if (state.expiresAt !== lastExpiresAt) {
+                lastExpiresAt = state.expiresAt;
+                schedule();
+            }
+        });
+        // Wake-from-sleep: background tabs throttle/pause timers — on return,
+        // recompute (and refresh immediately if the token already lapsed).
+        const onVisibility = () => {
+            if (document.visibilityState === 'visible' && !disposed)
+                schedule();
+        };
+        document.addEventListener('visibilitychange', onVisibility);
+        schedule();
+        return () => {
+            disposed = true;
+            clearTimer();
+            unsubscribe();
+            document.removeEventListener('visibilitychange', onVisibility);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [active, bufferMs, authStore]);
+}

package/dist/react/index.d.ts

@@ -19,6 +19,9 @@ export { useAuth, type UseAuthOptions, type LoginResult, type LogoutResult, type
 export { useLogin, type UseLoginOptions, type UseLoginReturn } from './hooks/use-login';
 export { useLogout, type UseLogoutOptions, type UseLogoutReturn } from './hooks/use-logout';
 export { useRefreshToken, type UseRefreshTokenOptions, type UseRefreshTokenReturn } from './hooks/use-refresh-token';
+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 { useCart, type UseCartOptions, type UseCartResult, type ServerCartOperation } from './hooks/use-cart';
 export { useStorefrontClient } from './hooks/use-storefront-client';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,KAAK,6BAA6B,EAAE,MAAM,wCAAwC,CAAC;AACtH,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAG7F,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9H,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACrH,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACxI,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC9G,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACxH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGlI,OAAO,EACL,SAAS,EACT,SAAS,EACT,YAAY,EACZ,0BAA0B,EAC1B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACL,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGpE,OAAO,EACL,KAAK,EACL,KAAK,UAAU,EACf,KAAK,EACL,KAAK,mBAAmB,EACxB,SAAS,EACT,KAAK,cAAc,EACnB,eAAe,EACf,KAAK,oBAAoB,EACzB,YAAY,EACZ,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,qBAAqB,EACrB,KAAK,0BAA0B,EAC/B,KAAK,+BAA+B,EACpC,wBAAwB,EACxB,KAAK,6BAA6B,EAClC,KAAK,8BAA8B,GACpC,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -21,6 +21,8 @@ export { useAuth } from './hooks/use-auth';
 export { useLogin } from './hooks/use-login';
 export { useLogout } from './hooks/use-logout';
 export { useRefreshToken } from './hooks/use-refresh-token';
+export { useSessionRefresh } from './hooks/use-session-refresh';
+export { useSessionExpired } from './hooks/use-session-expired';
 export { useCartManager } from './hooks/use-cart-manager';
 export { useCart } from './hooks/use-cart';
 export { useStorefrontClient } from './hooks/use-storefront-client';

package/dist/react/providers/storefront-client-provider.d.ts

@@ -11,6 +11,7 @@ import { CartClient } from '../../core/cart/cart-client';
 import { AuthClient } from '../../core/auth/auth-client';
 import { type BotProtectionTokenProvider } from '../../core/middleware/bot-protection';
 import type { StorefrontClient, StorefrontClientConfig, Middleware } from '../../core/client/types';
+import type { SessionExpiredEmitter } from '../../core/auth/session-events';
 export interface StorefrontClientContextValue {
     client: StorefrontClient;
     cartClient: CartClient;
@@ -28,8 +29,16 @@ export interface StorefrontClientProviderProps {
     botProtection?: BotProtectionTokenProvider | null;
     /** Operations that require bot protection (from shop query) */
     botProtectionOperations?: string[];
+    /**
+     * Auth-level session-expired emitter (from StorefrontProvider). When present,
+     * a reactive 401 on a read query triggers a single deduped refresh + replay,
+     * while a 401 on a mutation — or a refresh that also fails — fires this emitter.
+     */
+    sessionExpiredEmitter?: SessionExpiredEmitter;
+    /** Base path of the auth route handlers used to sync the httpOnly cookie after a reactive refresh (default `/api/auth`). */
+    authBasePath?: string;
 }
-export declare function StorefrontClientProvider({ children, config, middleware: customMiddleware, botProtection, botProtectionOperations, }: StorefrontClientProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function StorefrontClientProvider({ children, config, middleware: customMiddleware, botProtection, botProtectionOperations, sessionExpiredEmitter, authBasePath, }: StorefrontClientProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Get StorefrontClient context value.
  * Must be used within StorefrontClientProvider.

package/dist/react/providers/storefront-client-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storefront-client-provider.d.ts","sourceRoot":"","sources":["../../../src/react/providers/storefront-client-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAA6C,MAAM,OAAO,CAAC;AAElE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAIzD,OAAO,EAA2B,KAAK,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAKhH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpG,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;CACxB;AAID,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,sBAAsB,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,oEAAoE;IACpE,aAAa,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAClD,+DAA+D;IAC/D,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;CACpC;AAED,wBAAgB,wBAAwB,CAAC,EACvC,QAAQ,EACR,MAAM,EACN,UAAU,EAAE,gBAAqB,EACjC,aAAa,EACb,uBAAuB,GACxB,EAAE,6BAA6B,2CAyC/B;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,4BAA4B,CAMzE"}
+{"version":3,"file":"storefront-client-provider.d.ts","sourceRoot":"","sources":["../../../src/react/providers/storefront-client-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAA6C,MAAM,OAAO,CAAC;AAElE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAIzD,OAAO,EAA2B,KAAK,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAKhH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE5E,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;CACxB;AAID,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,sBAAsB,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,oEAAoE;IACpE,aAAa,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAClD,+DAA+D;IAC/D,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,4HAA4H;IAC5H,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,wBAAwB,CAAC,EACvC,QAAQ,EACR,MAAM,EACN,UAAU,EAAE,gBAAqB,EACjC,aAAa,EACb,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,GACb,EAAE,6BAA6B,2CAyE/B;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,4BAA4B,CAMzE"}

package/dist/react/providers/storefront-client-provider.js

@@ -20,15 +20,46 @@ import { retryMiddleware } from '../../core/middleware/retry';
 import { timeoutMiddleware } from '../../core/middleware/timeout';
 import { errorMiddleware } from '../../core/middleware/errors';
 import { useAuthStoreApi, useCurrencyStoreApi, useLanguageStoreApi } from '../stores/store-context';
+import { sessionRetryMiddleware } from '../../core/middleware/session-retry';
 const StorefrontClientContext = createContext(null);
-export function StorefrontClientProvider({ children, config, middleware: customMiddleware = [], botProtection, botProtectionOperations, }) {
+export function StorefrontClientProvider({ children, config, middleware: customMiddleware = [], botProtection, botProtectionOperations, sessionExpiredEmitter, authBasePath, }) {
     const authStore = useAuthStoreApi();
     const currencyStore = useCurrencyStoreApi();
     const languageStore = useLanguageStoreApi();
     const value = useMemo(() => {
+        // Reactive-401 renewal via the same-origin BFF route (`refreshSession`): the
+        // route reads the httpOnly refresh cookie server-side and sets the new
+        // first-party cookies, so no GraphQL refresh and no `setToken` round-trip.
+        // Forward-declared so this closure can reach the AuthClient created below.
+        // Deduped so concurrent 401s share a single renewal.
+        let authClientForRefresh;
+        let inFlightRefresh = null;
+        const refresh = () => {
+            if (inFlightRefresh)
+                return inFlightRefresh;
+            inFlightRefresh = (async () => {
+                try {
+                    const result = await authClientForRefresh.refreshSession();
+                    authStore.getState().setAuth(authStore.getState().customer, result.accessToken, result.expiresAt);
+                    return true;
+                }
+                catch {
+                    authStore.getState().clearAuth();
+                    return false;
+                }
+                finally {
+                    inFlightRefresh = null;
+                }
+            })();
+            return inFlightRefresh;
+        };
         const client = createStorefrontClient({
             ...config,
             middleware: [
+                // Reactive 401 — OUTERMOST so the replay re-runs auth with the fresh token.
+                ...(sessionExpiredEmitter
+                    ? [sessionRetryMiddleware({ refresh, onSessionExpired: (e) => sessionExpiredEmitter.emit(e) })]
+                    : []),
                 // Header middleware (runs first)
                 authMiddleware(() => authStore.getState().accessToken),
                 currencyMiddleware(() => currencyStore.getState().currency),
@@ -49,10 +80,14 @@ export function StorefrontClientProvider({ children, config, middleware: customM
             ],
         });
         const cartClient = new CartClient(client);
-        const authClient = new AuthClient(client);
+        // The AuthClient's `refreshSession()` posts to the same-origin BFF route at
+        // `${authBasePath}/refresh`; pass the configured base so a non-standard mount
+        // still resolves (default `/api/auth`).
+        const authClient = new AuthClient(client, { authBasePath });
+        authClientForRefresh = authClient;
         return { client, cartClient, authClient };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [config.apiUrl, config.shopSlug, authStore, currencyStore, languageStore]);
+    }, [config.apiUrl, config.shopSlug, authStore, currencyStore, languageStore, sessionExpiredEmitter, authBasePath]);
     return (_jsx(StorefrontClientContext.Provider, { value: value, children: children }));
 }
 /**