@doswiftly/storefront-sdk 17.0.0 → 18.1.0

package/dist/react/index.js

@@ -16,11 +16,14 @@ 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';
 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/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/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 }));
 }
 /**

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

@@ -10,14 +10,18 @@
  * @example
  * ```tsx
  * // app/layout.tsx
- * import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+ * import { cookies } from 'next/headers';
+ * import { StorefrontProvider, AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
  *
  * export default async function RootLayout({ children }) {
- *   const shopData = await fetchShop();
+ *   const [shopData, cookieStore] = await Promise.all([fetchShop(), cookies()]);
+ *   const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+ *
  *   return (
  *     <StorefrontProvider
  *       config={{ apiUrl: '...', shopSlug: '...' }}
  *       shopData={shopData}
+ *       initialAccessToken={initialAccessToken}
  *     >
  *       {children}
  *     </StorefrontProvider>
@@ -35,14 +39,58 @@ export interface StorefrontProviderProps extends StorefrontClientProviderProps {
      * eliminating the flash of "Sign In" while Zustand persist rehydrates from localStorage.
      *
      * Read from cookies() in a Server Component (layout.tsx) and pass here.
+     *
+     * Defaults to `!!initialAccessToken` when omitted (raw token implies authenticated).
+     * Pass `false` explicitly to override that default in edge cases (opt-out flow,
+     * recovery banner that holds a token without claiming auth state).
      */
     initialIsAuthenticated?: boolean;
+    /**
+     * Server-side token seed. See {@link CreateAuthStoreOptions.initialAccessToken}
+     * for full semantics and security guarantees (token kept in memory, never
+     * persisted). Wire up from your Server Component with `cookies()` + `AUTH_COOKIE_NAME`.
+     *
+     * @example
+     * ```tsx
+     * // app/layout.tsx
+     * import { cookies } from 'next/headers';
+     * import { AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
+     *
+     * const cookieStore = await cookies();
+     * const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+     *
+     * <StorefrontProvider initialAccessToken={initialAccessToken} ...>
+     * ```
+     */
+    initialAccessToken?: string | null;
     /**
      * Server-side language hint — pass the URL locale from next-intl params.
      * Eliminates flash of wrong language on first render by initializing the
      * language store with the correct value from the server.
      */
     initialLanguage?: string;
+    /**
+     * Proactive session refresh. Defaults to ON in the browser and OFF on the
+     * server — you do NOT need to pass it. When active, the SDK renews the access
+     * token shortly before it expires so an active buyer is never logged out
+     * mid-session, and fires a global `session-expired` signal (subscribe via
+     * `useSessionExpired`) when the session can no longer be kept alive. Pass
+     * `autoRefresh={false}` to opt out and drive refreshing yourself.
+     */
+    autoRefresh?: boolean;
+    /**
+     * Base path of the SDK-BFF auth route handlers (default `/api/auth`). The
+     * proactive scheduler and the reactive-401 renewal post to `${authBasePath}/refresh`
+     * (same-origin), which rotates the refresh cookie server-side. Override only for
+     * non-standard mounts — it must match where `createStorefrontAuthRoute` is mounted.
+     */
+    authBasePath?: string;
+    /**
+     * Server-side session-expiry seed (ISO 8601) — typically the readable
+     * `session-expiry` cookie value read in a Server Component. Lets the refresh
+     * scheduler arm on the first render (cold start) without a whoami round-trip.
+     */
+    initialExpiresAt?: string | null;
 }
-export declare function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialLanguage, }: StorefrontProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialAccessToken, initialExpiresAt, initialLanguage, autoRefresh, authBasePath, }: StorefrontProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=storefront-provider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"storefront-provider.d.ts","sourceRoot":"","sources":["../../../src/react/providers/storefront-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,OAAO,EAA4B,KAAK,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAC5G,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMnF,MAAM,WAAW,uBAAwB,SAAQ,6BAA6B;IAC5E,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,eAAe,GAChB,EAAE,uBAAuB,2CA+BzB"}
+{"version":3,"file":"storefront-provider.d.ts","sourceRoot":"","sources":["../../../src/react/providers/storefront-provider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH,OAAO,EAA4B,KAAK,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAC5G,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AASnF,MAAM,WAAW,uBAAwB,SAAQ,6BAA6B;IAC5E,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;;;OAgBG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,GACb,EAAE,uBAAuB,2CAwCzB"}

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

@@ -10,14 +10,18 @@
  * @example
  * ```tsx
  * // app/layout.tsx
- * import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+ * import { cookies } from 'next/headers';
+ * import { StorefrontProvider, AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
  *
  * export default async function RootLayout({ children }) {
- *   const shopData = await fetchShop();
+ *   const [shopData, cookieStore] = await Promise.all([fetchShop(), cookies()]);
+ *   const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+ *
  *   return (
  *     <StorefrontProvider
  *       config={{ apiUrl: '...', shopSlug: '...' }}
  *       shopData={shopData}
+ *       initialAccessToken={initialAccessToken}
  *     >
  *       {children}
  *     </StorefrontProvider>
@@ -38,10 +42,23 @@ import { LanguageProvider } from './language-provider';
 import { createBotProtectionManager } from '../../core/bot-protection/create-manager';
 import { BotProtectionContext } from '../bot-protection/bot-protection-context';
 import { BotProtectionWidget } from '../bot-protection/bot-protection-widget';
-export function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialLanguage, }) {
-    const authStoreRef = useRef(createAuthStore(initialIsAuthenticated));
+import { createSessionExpiredEmitter } from '../../core/auth/session-events';
+import { SessionExpiredContext } from '../hooks/use-session-expired';
+import { useSessionRefresh } from '../hooks/use-session-refresh';
+export function StorefrontProvider({ children, config, middleware, shopData, initialIsAuthenticated, initialAccessToken, initialExpiresAt, initialLanguage, autoRefresh, authBasePath, }) {
+    const authStoreRef = useRef(createAuthStore({ initialIsAuthenticated, initialAccessToken, initialExpiresAt }));
     const currencyStoreRef = useRef(createCurrencyStore());
     const languageStoreRef = useRef(createLanguageStore(initialLanguage));
+    const sessionExpiredRef = useRef(createSessionExpiredEmitter());
     const botProtectionRef = useRef(shopData.botProtection ? createBotProtectionManager(shopData.botProtection) : null);
-    return (_jsx(AuthStoreContext.Provider, { value: authStoreRef.current, children: _jsx(CurrencyStoreContext.Provider, { value: currencyStoreRef.current, children: _jsx(LanguageStoreContext.Provider, { value: languageStoreRef.current, children: _jsx(StorefrontClientProvider, { config: config, middleware: middleware, botProtection: botProtectionRef.current, botProtectionOperations: shopData.botProtection?.protectedOperations, children: _jsx(BotProtectionContext.Provider, { value: { manager: botProtectionRef.current }, children: _jsx(CurrencyProvider, { shopData: shopData, children: _jsxs(LanguageProvider, { shopData: shopData, children: [_jsx(BotProtectionWidget, { manager: botProtectionRef.current }), children] }) }) }) }) }) }) }));
+    return (_jsx(AuthStoreContext.Provider, { value: authStoreRef.current, children: _jsx(CurrencyStoreContext.Provider, { value: currencyStoreRef.current, children: _jsx(LanguageStoreContext.Provider, { value: languageStoreRef.current, children: _jsx(StorefrontClientProvider, { config: config, middleware: middleware, botProtection: botProtectionRef.current, botProtectionOperations: shopData.botProtection?.protectedOperations, sessionExpiredEmitter: sessionExpiredRef.current, authBasePath: authBasePath, children: _jsx(BotProtectionContext.Provider, { value: { manager: botProtectionRef.current }, children: _jsx(CurrencyProvider, { shopData: shopData, children: _jsxs(LanguageProvider, { shopData: shopData, children: [_jsx(BotProtectionWidget, { manager: botProtectionRef.current }), _jsx(SessionRefreshRunner, { autoRefresh: autoRefresh, emitter: sessionExpiredRef.current }), _jsx(SessionExpiredContext.Provider, { value: sessionExpiredRef.current, children: children })] }) }) }) }) }) }) }));
+}
+/**
+ * Internal — drives the proactive refresh scheduler from inside the provider
+ * tree (so it can read the client + auth store via context). Renders nothing.
+ * The scheduler itself is a browser-only no-op on the server.
+ */
+function SessionRefreshRunner({ autoRefresh, emitter, }) {
+    useSessionRefresh({ enabled: autoRefresh, sessionExpiredEmitter: emitter });
+    return null;
 }

package/dist/react/server/create-storefront-auth-route.d.ts

@@ -0,0 +1,63 @@
+/**
+ * createStorefrontAuthRoute — SDK-BFF auth route handlers.
+ *
+ * Generates the four same-origin auth route handlers that live on the storefront
+ * domain (`/api/auth/[action]`): `login`, `refresh`, `logout` (POST) and `whoami`
+ * (GET). Each handler calls the backend `/storefront/auth/*` namespace
+ * server-to-server with `X-Shop-Slug` as a routing hint, owns the first-party
+ * httpOnly cookies on the storefront domain, and returns ONLY
+ * `{ accessToken, expiresAt[, customer] }` to JavaScript — the refresh token is
+ * read server-side and never reaches the browser's JS.
+ *
+ * This is the universal auth transport: the route handlers live on the
+ * storefront's own domain, so first-party cookies work identically on a platform
+ * subdomain, a custom domain, and off-platform hosting (e.g. Vercel) —
+ * independent of any reverse proxy in front. The backend never emits a
+ * `Set-Cookie` to a browser (tokens travel in the server-to-server response
+ * body); the BFF sets the cookies here.
+ *
+ * 0 runtime dependencies — pure Web API (`Request`/`Response`/`fetch`). No React,
+ * no `next/*`. Mount it in a Next.js (or any framework) route:
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/[action]/route.ts
+ * import { createStorefrontAuthRoute, trustedForwardedHostValidator } from '@doswiftly/storefront-sdk/react/server';
+ *
+ * export const { GET, POST } = createStorefrontAuthRoute({
+ *   apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+ *   shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+ *   isTrustedOrigin: trustedForwardedHostValidator, // when behind a reverse proxy that rewrites Host
+ * });
+ * ```
+ */
+import { type OriginValidator } from '../../core/auth/handlers';
+export interface StorefrontAuthRouteOptions {
+    /** Backend base URL (e.g. `https://api.doswiftly.pl`). The server-to-server namespace is `${apiUrl}/storefront/auth/*`. */
+    apiUrl: string;
+    /** Shop slug forwarded as the `X-Shop-Slug` routing hint (selects the tenant; never binds the rotation family). */
+    shopSlug: string;
+    /**
+     * CSRF defense-in-depth predicate. When the storefront runs behind a reverse
+     * proxy that rewrites/strips `Host` (Cloudflare Workers, Vercel, NGINX),
+     * pass `trustedForwardedHostValidator`. This is NOT the primary control — the
+     * backend's protocol controls (rotation + reuse-detection + rate-limit +
+     * possession-proof) are. See {@link OriginValidator}.
+     */
+    isTrustedOrigin?: OriginValidator | null;
+    /**
+     * Base path the route is mounted at (default `/api/auth`). The refresh cookie's
+     * `Path` is set to it so the cookie reaches both the refresh and logout routes
+     * (siblings under this base) but not GraphQL data traffic, which lives on a
+     * different path.
+     */
+    authBasePath?: string;
+    /** Custom fetch (tests, non-standard runtimes). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface StorefrontAuthRouteHandlers {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+}
+export declare function createStorefrontAuthRoute(options: StorefrontAuthRouteOptions): StorefrontAuthRouteHandlers;
+//# sourceMappingURL=create-storefront-auth-route.d.ts.map

package/dist/react/server/create-storefront-auth-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-storefront-auth-route.d.ts","sourceRoot":"","sources":["../../../src/react/server/create-storefront-auth-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAOlC,MAAM,WAAW,0BAA0B;IACzC,2HAA2H;IAC3H,MAAM,EAAE,MAAM,CAAC;IACf,mHAAmH;IACnH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/C;AAgDD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,2BAA2B,CA+L7B"}