npm - @doswiftly/storefront-sdk - Versions diffs - 17.0.0 → 18.0.0 - Mend

@doswiftly/storefront-sdk 17.0.0 → 18.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (83) hide show

package/CHANGELOG.md +919 -0
package/README.md +16 -4
package/dist/core/auth/auth-client.d.ts +39 -3
package/dist/core/auth/auth-client.d.ts.map +1 -1
package/dist/core/auth/auth-client.js +51 -3
package/dist/core/auth/cookie-config.d.ts +52 -3
package/dist/core/auth/cookie-config.d.ts.map +1 -1
package/dist/core/auth/cookie-config.js +60 -6
package/dist/core/auth/handlers.d.ts +46 -0
package/dist/core/auth/handlers.d.ts.map +1 -1
package/dist/core/auth/handlers.js +9 -2
package/dist/core/auth/session-events.d.ts +38 -0
package/dist/core/auth/session-events.d.ts.map +1 -0
package/dist/core/auth/session-events.js +35 -0
package/dist/core/cart/cart-recovery.d.ts +23 -0
package/dist/core/cart/cart-recovery.d.ts.map +1 -1
package/dist/core/cart/cart-recovery.js +20 -3
package/dist/core/cart/types.d.ts +2 -1
package/dist/core/cart/types.d.ts.map +1 -1
package/dist/core/cart/types.js +7 -1
package/dist/core/client/create-client.d.ts.map +1 -1
package/dist/core/client/create-client.js +7 -3
package/dist/core/client/execute.d.ts +29 -3
package/dist/core/client/execute.d.ts.map +1 -1
package/dist/core/client/execute.js +174 -3
package/dist/core/client/types.d.ts +50 -2
package/dist/core/client/types.d.ts.map +1 -1
package/dist/core/errors.d.ts +6 -0
package/dist/core/errors.d.ts.map +1 -1
package/dist/core/errors.js +6 -0
package/dist/core/generated/operation-types.d.ts +838 -221
package/dist/core/generated/operation-types.d.ts.map +1 -1
package/dist/core/generated/operation-types.js +560 -1
package/dist/core/index.d.ts +6 -3
package/dist/core/index.d.ts.map +1 -1
package/dist/core/index.js +12 -2
package/dist/core/middleware/session-retry.d.ts +47 -0
package/dist/core/middleware/session-retry.d.ts.map +1 -0
package/dist/core/middleware/session-retry.js +71 -0
package/dist/core/operations/auth.d.ts.map +1 -1
package/dist/core/operations/auth.js +1 -0
package/dist/core/operations/cart.d.ts.map +1 -1
package/dist/core/operations/cart.js +15 -11
package/dist/react/components/PaymentInstrumentSection.d.ts.map +1 -1
package/dist/react/components/PaymentInstrumentSection.js +4 -4
package/dist/react/components/PaymentInstrumentTile.d.ts +7 -7
package/dist/react/components/PaymentInstrumentTile.d.ts.map +1 -1
package/dist/react/components/PaymentInstrumentTile.js +4 -3
package/dist/react/hooks/use-cart-manager.d.ts +104 -13
package/dist/react/hooks/use-cart-manager.d.ts.map +1 -1
package/dist/react/hooks/use-cart-manager.js +144 -12
package/dist/react/hooks/use-login.d.ts.map +1 -1
package/dist/react/hooks/use-login.js +3 -3
package/dist/react/hooks/use-refresh-token.d.ts.map +1 -1
package/dist/react/hooks/use-refresh-token.js +6 -4
package/dist/react/hooks/use-session-expired.d.ts +16 -0
package/dist/react/hooks/use-session-expired.d.ts.map +1 -0
package/dist/react/hooks/use-session-expired.js +26 -0
package/dist/react/hooks/use-session-refresh.d.ts +32 -0
package/dist/react/hooks/use-session-refresh.d.ts.map +1 -0
package/dist/react/hooks/use-session-refresh.js +147 -0
package/dist/react/index.d.ts +3 -0
package/dist/react/index.d.ts.map +1 -1
package/dist/react/index.js +2 -0
package/dist/react/providers/storefront-client-provider.d.ts +10 -1
package/dist/react/providers/storefront-client-provider.d.ts.map +1 -1
package/dist/react/providers/storefront-client-provider.js +38 -3
package/dist/react/providers/storefront-provider.d.ts +51 -3
package/dist/react/providers/storefront-provider.d.ts.map +1 -1
package/dist/react/providers/storefront-provider.js +22 -5
package/dist/react/server/create-storefront-auth-route.d.ts +63 -0
package/dist/react/server/create-storefront-auth-route.d.ts.map +1 -0
package/dist/react/server/create-storefront-auth-route.js +239 -0
package/dist/react/server/get-initial-auth.d.ts +57 -0
package/dist/react/server/get-initial-auth.d.ts.map +1 -0
package/dist/react/server/get-initial-auth.js +55 -0
package/dist/react/server/index.d.ts +3 -0
package/dist/react/server/index.d.ts.map +1 -1
package/dist/react/server/index.js +6 -0
package/dist/react/stores/auth.store.d.ts +46 -2
package/dist/react/stores/auth.store.d.ts.map +1 -1
package/dist/react/stores/auth.store.js +19 -7
package/package.json +4 -2

package/README.md CHANGED Viewed

@@ -151,10 +151,13 @@ export default async function RootLayout({ children }: { children: React.ReactNo
   // `shop.botProtection` — whatever StorefrontProvider needs.
   const { shop } = await serverClient.query(SHOP_BASICS_QUERY);
-  // Read the httpOnly auth cookie server-side so we can hydrate the auth store
-  // without a flash of "Sign In".
+  // Read the raw JWT from the httpOnly auth cookie server-side and seed it into
+  // the auth store. This eliminates the round-trip to `/api/auth/whoami` on the
+  // first mount — `authMiddleware` adds `Authorization: Bearer ...` from the
+  // very first request. Token stays in memory only (never written to
+  // localStorage — `persist.partialize` excludes `accessToken`, XSS hardening).
   const cookieStore = await cookies();
-  const initialIsAuthenticated = Boolean(cookieStore.get(AUTH_COOKIE_NAME)?.value);
+  const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
   return (
     <html lang="pl">
@@ -165,7 +168,7 @@ export default async function RootLayout({ children }: { children: React.ReactNo
             shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
           }}
           shopData={shop}
-          initialIsAuthenticated={initialIsAuthenticated}
+          initialAccessToken={initialAccessToken}
         >
           {children}
         </StorefrontProvider>
@@ -175,6 +178,15 @@ export default async function RootLayout({ children }: { children: React.ReactNo
 }
 ```
+> **Tip — `initialIsAuthenticated` vs `initialAccessToken`:** if you only know
+> *whether* the user is signed in (cookie present, value not readable server-side),
+> pass `initialIsAuthenticated={Boolean(...)}` — UI starts in the right gating
+> state, and the SDK fetches the token via `createWhoamiHandler` on first mount.
+> If you have the raw JWT server-side (cookie value, SSO redirect param,
+> dev-seed env var), prefer `initialAccessToken={token}` — no round-trip needed.
+> When `initialAccessToken` is truthy, `isAuthenticated` defaults to `true`
+> automatically; pass `initialIsAuthenticated={false}` to override.
 **2. `app/api/auth/set-token/route.ts`** — BFF route that sets the httpOnly
 cookie. The SDK ships factories so each file is two lines:

package/dist/core/auth/auth-client.d.ts CHANGED Viewed

@@ -17,9 +17,26 @@
  */
 import type { StorefrontClient } from '../client/types';
 import type { AuthResult, Customer, CustomerCreateInput, MailingAddress } from './types';
+/** Result of a same-origin BFF session refresh — the new access token + its absolute expiry. */
+export interface SessionRefreshResult {
+    accessToken: string;
+    expiresAt: string;
+}
+/**
+ * Options configuring the same-origin BFF transport used by {@link AuthClient.refreshSession}.
+ * GraphQL auth operations (login/register/getCustomer) keep using the injected
+ * `StorefrontClient`; only `refreshSession` talks to the same-origin route.
+ */
+export interface AuthClientOptions {
+    /** Base path of the SDK-BFF auth route handlers (default `/api/auth`). */
+    authBasePath?: string;
+    /** Custom fetch (tests, non-standard runtimes). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
 export declare class AuthClient {
     private readonly client;
-    constructor(client: StorefrontClient);
+    private readonly options;
+    constructor(client: StorefrontClient, options?: AuthClientOptions);
     /**
      * Login with email and password.
      * Returns access token + expiry.
@@ -33,8 +50,27 @@ export declare class AuthClient {
      */
     logout(): Promise<void>;
     /**
-     * Refresh access token — extends expiry. Auth context czytany przez backend
-     * z cookie / Authorization Bearer (jak inne authenticated mutations).
+     * Refresh the session via the same-origin BFF route (`POST {authBasePath}/refresh`).
+     *
+     * This is the browser refresh path: the route handler reads the httpOnly
+     * refresh cookie server-side, rotates it against the backend server-to-server,
+     * sets the new first-party cookies, and returns only the new access token +
+     * absolute expiry. The refresh token is never read by JS — so an EXPIRED access
+     * token still refreshes (the GraphQL `customerRefreshToken` mutation could not,
+     * as it required a valid access token).
+     *
+     * Throws a {@link StorefrontError} with code `SESSION_EXPIRED` when the route
+     * responds non-OK (reused/expired/missing refresh token) — the scheduler and
+     * the reactive-401 middleware translate that into a `session-expired` signal.
+     */
+    refreshSession(): Promise<SessionRefreshResult>;
+    /**
+     * Refresh the access token via the GraphQL `customerRefreshToken` mutation.
+     *
+     * @deprecated The browser refresh now goes through {@link refreshSession}
+     * (same-origin BFF). This GraphQL mutation requires a still-valid access token
+     * and is retained for backward compatibility until it is removed in a future
+     * major release. Prefer `refreshSession()`.
      */
     refreshToken(): Promise<AuthResult>;
     /**

package/dist/core/auth/auth-client.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/core/auth/auth-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;~~AAWzF~~,qBAAa,UAAU;~~IACT~~,OAAO,CAAC,QAAQ,CAAC,MAAM;~~gBAAN~~,MAAM,EAAE,gBAAgB;~~IAErD~~;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBjE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAa7B~~;;;OAGG~~;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAiBzC;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB/D;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQ7C;;;;;;;;;;OAUG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;CAMvD"}
1	+ {"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/core/auth/auth-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAYzF,gGAAgG;AAChG,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,iBAAsB;IAGlD;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBjE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAa7B;;;;;;;;;;;;;OAaG;IACG,cAAc,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAgCrD;;;;;;;OAOG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAiBzC;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB/D;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQ7C;;;;;;;;;;OAUG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;CAMvD"}

package/dist/core/auth/auth-client.js CHANGED Viewed

@@ -16,11 +16,14 @@
  * ```
  */
 import { assertNoUserErrors } from '../helpers/assert-no-user-errors';
+import { StorefrontError, ErrorCodes } from '../errors';
 import { CUSTOMER_LOGIN, CUSTOMER_LOGOUT, CUSTOMER_REFRESH_TOKEN, CUSTOMER_SIGNUP, CUSTOMER_QUERY, CUSTOMER_ADDRESSES_QUERY, } from '../operations/auth';
 export class AuthClient {
     client;
-    constructor(client) {
+    options;
+    constructor(client, options = {}) {
         this.client = client;
+        this.options = options;
     }
     /**
      * Login with email and password.
@@ -50,8 +53,53 @@ export class AuthClient {
         }
     }
     /**
-     * Refresh access token — extends expiry. Auth context czytany przez backend
-     * z cookie / Authorization Bearer (jak inne authenticated mutations).
+     * Refresh the session via the same-origin BFF route (`POST {authBasePath}/refresh`).
+     *
+     * This is the browser refresh path: the route handler reads the httpOnly
+     * refresh cookie server-side, rotates it against the backend server-to-server,
+     * sets the new first-party cookies, and returns only the new access token +
+     * absolute expiry. The refresh token is never read by JS — so an EXPIRED access
+     * token still refreshes (the GraphQL `customerRefreshToken` mutation could not,
+     * as it required a valid access token).
+     *
+     * Throws a {@link StorefrontError} with code `SESSION_EXPIRED` when the route
+     * responds non-OK (reused/expired/missing refresh token) — the scheduler and
+     * the reactive-401 middleware translate that into a `session-expired` signal.
+     */
+    async refreshSession() {
+        const base = (this.options.authBasePath ?? '/api/auth').replace(/\/$/, '');
+        const fetchFn = this.options.fetch ?? globalThis.fetch;
+        const response = await fetchFn(`${base}/refresh`, {
+            method: 'POST',
+            headers: { Accept: 'application/json' },
+            // Same-origin route on the storefront domain — the httpOnly refresh cookie
+            // is attached automatically; the token never enters JavaScript.
+            credentials: 'same-origin',
+        });
+        if (!response.ok) {
+            throw new StorefrontError({
+                code: ErrorCodes.SESSION_EXPIRED,
+                message: `Session refresh failed (HTTP ${response.status})`,
+                status: response.status,
+            });
+        }
+        const data = (await response.json());
+        if (!data.accessToken || !data.expiresAt) {
+            throw new StorefrontError({
+                code: ErrorCodes.SESSION_EXPIRED,
+                message: 'Session refresh returned an incomplete token pair',
+                status: response.status,
+            });
+        }
+        return { accessToken: data.accessToken, expiresAt: data.expiresAt };
+    }
+    /**
+     * Refresh the access token via the GraphQL `customerRefreshToken` mutation.
+     *
+     * @deprecated The browser refresh now goes through {@link refreshSession}
+     * (same-origin BFF). This GraphQL mutation requires a still-valid access token
+     * and is retained for backward compatibility until it is removed in a future
+     * major release. Prefer `refreshSession()`.
      */
     async refreshToken() {
         const data = await this.client.mutate(CUSTOMER_REFRESH_TOKEN);

package/dist/core/auth/cookie-config.d.ts CHANGED Viewed

@@ -1,11 +1,20 @@
 /**
  * Auth Cookie Configuration — platform contract.
  *
- * Backend validates cookie by name `customerAccessToken`.
- * Every storefront MUST use the same name. Security options
- * (httpOnly, secure, sameSite) are the platform standard.
+ * The SDK-BFF route handlers (`createStorefrontAuthRoute`) own these first-party
+ * cookies on the storefront domain; the backend never emits a `Set-Cookie` to a
+ * browser (it returns tokens in the body, server-to-server). Every storefront
+ * MUST use the same cookie names — they are read by the SDK auth middleware
+ * (access) and the proactive scheduler (session-expiry), and forwarded
+ * server-side by the BFF (refresh). Changing a name is a platform-wide contract
+ * change (backend rotation namespace + middleware + template).
  */
+/** Short-lived access token (Bearer). Host-only, httpOnly, `Path=/` (SSR + every request). */
 export declare const AUTH_COOKIE_NAME = "customerAccessToken";
+/** Long-lived rotation refresh token. Host-only, httpOnly, isolated to the refresh path. */
+export declare const REFRESH_COOKIE_NAME = "customerRefreshToken";
+/** Readable (non-httpOnly) absolute session-expiry hint for the proactive scheduler's cold start. */
+export declare const SESSION_EXPIRY_COOKIE_NAME = "session-expiry";
 export declare const AUTH_COOKIE_DEFAULTS: {
     readonly name: "customerAccessToken";
     readonly path: "/";
@@ -15,4 +24,44 @@ export declare const AUTH_COOKIE_DEFAULTS: {
     readonly maxAge: number;
 };
 export type AuthCookieConfig = typeof AUTH_COOKIE_DEFAULTS;
+/**
+ * Refresh-token cookie attributes. Scoped to the auth base path (`/api/auth`) so
+ * it reaches BOTH the refresh route (to rotate) and the logout route (to revoke,
+ * via possession-proof) while staying off GraphQL data traffic, which lives on a
+ * different path. The token is read only server-side and never reaches
+ * JavaScript. `maxAge` is the refresh-token lifetime (30 days); the backend body
+ * carries no refresh expiry, so the BFF route uses this constant.
+ *
+ * The `path` must equal the route's mount base so logout receives the cookie — a
+ * narrower `/api/auth/refresh` would NOT be sent to `/api/auth/logout` (cookies
+ * are not sent to sibling paths), leaving the family un-revoked on logout.
+ */
+export declare const REFRESH_COOKIE_DEFAULTS: {
+    readonly name: "customerRefreshToken";
+    readonly path: "/api/auth";
+    readonly sameSite: "lax";
+    readonly httpOnly: true;
+    readonly secure: boolean;
+    readonly maxAge: number;
+};
+export type RefreshCookieConfig = typeof REFRESH_COOKIE_DEFAULTS;
+/**
+ * Session-expiry hint cookie attributes. Deliberately NOT httpOnly — the value
+ * is only an absolute ISO timestamp (no secret), readable so the proactive
+ * scheduler can arm on a cold start without a whoami round-trip. It lives as long
+ * as the refresh session (30 days), NOT as long as the short access token: a
+ * returning visitor whose access token has lapsed must still find this hint on a
+ * cold start so the app renders signed-in and recovers the session (a past
+ * timestamp tells the scheduler to refresh immediately) instead of flashing
+ * signed-out.
+ */
+export declare const SESSION_EXPIRY_COOKIE_DEFAULTS: {
+    readonly name: "session-expiry";
+    readonly path: "/";
+    readonly sameSite: "lax";
+    readonly httpOnly: false;
+    readonly secure: boolean;
+    readonly maxAge: number;
+};
+export type SessionExpiryCookieConfig = typeof SESSION_EXPIRY_COOKIE_DEFAULTS;
 //# sourceMappingURL=cookie-config.d.ts.map

package/dist/core/auth/cookie-config.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/auth/cookie-config.ts"],"names":[],"mappings":"AAAA~~;;;;;;GAMG~~;AAEH,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,eAAO,MAAM,oBAAoB;;;;;;;~~CAUvB~~,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,oBAAoB,CAAC"}
1	+ {"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/auth/cookie-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,8FAA8F;AAC9F,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,mBAAmB,CAAC;AAa3D,eAAO,MAAM,oBAAoB;;;;;;;CAOvB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,oBAAoB,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB;;;;;;;CAO1B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,OAAO,uBAAuB,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B;;;;;;;CAOjC,CAAC;AAEX,MAAM,MAAM,yBAAyB,GAAG,OAAO,8BAA8B,CAAC"}

package/dist/core/auth/cookie-config.js CHANGED Viewed

@@ -1,18 +1,72 @@
 /**
  * Auth Cookie Configuration — platform contract.
  *
- * Backend validates cookie by name `customerAccessToken`.
- * Every storefront MUST use the same name. Security options
- * (httpOnly, secure, sameSite) are the platform standard.
+ * The SDK-BFF route handlers (`createStorefrontAuthRoute`) own these first-party
+ * cookies on the storefront domain; the backend never emits a `Set-Cookie` to a
+ * browser (it returns tokens in the body, server-to-server). Every storefront
+ * MUST use the same cookie names — they are read by the SDK auth middleware
+ * (access) and the proactive scheduler (session-expiry), and forwarded
+ * server-side by the BFF (refresh). Changing a name is a platform-wide contract
+ * change (backend rotation namespace + middleware + template).
  */
+/** Short-lived access token (Bearer). Host-only, httpOnly, `Path=/` (SSR + every request). */
 export const AUTH_COOKIE_NAME = 'customerAccessToken';
+/** Long-lived rotation refresh token. Host-only, httpOnly, isolated to the refresh path. */
+export const REFRESH_COOKIE_NAME = 'customerRefreshToken';
+/** Readable (non-httpOnly) absolute session-expiry hint for the proactive scheduler's cold start. */
+export const SESSION_EXPIRY_COOKIE_NAME = 'session-expiry';
+/**
+ * Whether cookies must carry the `Secure` attribute. `true` over HTTPS in the
+ * browser and in production on the server; `false` in local HTTP development so
+ * the cookie is still accepted. Evaluated once at module load — the BFF route
+ * runs server-side, so the `process.env.NODE_ENV` branch is the live one there.
+ */
+const SECURE = typeof window !== 'undefined'
+    ? window.location.protocol === 'https:'
+    : process.env.NODE_ENV === 'production';
 export const AUTH_COOKIE_DEFAULTS = {
     name: AUTH_COOKIE_NAME,
     path: '/',
     sameSite: 'lax',
     httpOnly: true,
-    secure: typeof window !== 'undefined'
-        ? window.location.protocol === 'https:'
-        : process.env.NODE_ENV === 'production',
+    secure: SECURE,
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+};
+/**
+ * Refresh-token cookie attributes. Scoped to the auth base path (`/api/auth`) so
+ * it reaches BOTH the refresh route (to rotate) and the logout route (to revoke,
+ * via possession-proof) while staying off GraphQL data traffic, which lives on a
+ * different path. The token is read only server-side and never reaches
+ * JavaScript. `maxAge` is the refresh-token lifetime (30 days); the backend body
+ * carries no refresh expiry, so the BFF route uses this constant.
+ *
+ * The `path` must equal the route's mount base so logout receives the cookie — a
+ * narrower `/api/auth/refresh` would NOT be sent to `/api/auth/logout` (cookies
+ * are not sent to sibling paths), leaving the family un-revoked on logout.
+ */
+export const REFRESH_COOKIE_DEFAULTS = {
+    name: REFRESH_COOKIE_NAME,
+    path: '/api/auth',
+    sameSite: 'lax',
+    httpOnly: true,
+    secure: SECURE,
     maxAge: 60 * 60 * 24 * 30, // 30 days
 };
+/**
+ * Session-expiry hint cookie attributes. Deliberately NOT httpOnly — the value
+ * is only an absolute ISO timestamp (no secret), readable so the proactive
+ * scheduler can arm on a cold start without a whoami round-trip. It lives as long
+ * as the refresh session (30 days), NOT as long as the short access token: a
+ * returning visitor whose access token has lapsed must still find this hint on a
+ * cold start so the app renders signed-in and recovers the session (a past
+ * timestamp tells the scheduler to refresh immediately) instead of flashing
+ * signed-out.
+ */
+export const SESSION_EXPIRY_COOKIE_DEFAULTS = {
+    name: SESSION_EXPIRY_COOKIE_NAME,
+    path: '/',
+    sameSite: 'lax',
+    httpOnly: false,
+    secure: SECURE,
+    maxAge: 60 * 60 * 24 * 30, // 30 days — outlives the access token so cold-start recovery works
+};

package/dist/core/auth/handlers.d.ts CHANGED Viewed

@@ -51,6 +51,52 @@ interface ClearTokenHandlerOptions {
     /** Optional predicate that bypasses strict Host check when truthy. */
     isTrustedOrigin?: OriginValidator | null;
 }
+/**
+ * Serialize a single `Set-Cookie` header value. Shared by the set/clear token
+ * handlers and the `createStorefrontAuthRoute` factory so cookie attribute
+ * emission stays identical across both. The value is emitted as-is — callers
+ * pass cookie-safe values (JWT base64url, opaque `{familyId}.{uuid}`, ISO
+ * timestamps) or pre-encode.
+ */
+export declare function serializeCookie(name: string, value: string, options: {
+    maxAge?: number;
+    path?: string;
+    sameSite?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+}): string;
+/**
+ * Validate the Origin header against the Host header to prevent CSRF from
+ * unrelated origins.
+ *
+ * Compares the *parsed* origin's host with the request's host header, not a
+ * substring match — `origin.includes(host)` was bypassable two ways:
+ * - `host = ""` (or missing) → `origin.includes('')` always true;
+ * - `origin = "https://attacker.example/?host=trusted"` → substring match
+ *   passes for any trusted host name.
+ *
+ * For state-changing methods (POST/PUT/PATCH/DELETE) browsers always send
+ * Origin (fetch spec § 3.5.6 — "method is neither GET nor HEAD"). For safe
+ * methods (GET/HEAD) browsers OMIT Origin for same-origin requests; passing
+ * `allowMissingOrigin: true` skips the "Origin required" check while still
+ * validating mismatch when Origin happens to be present (defense-in-depth
+ * for cross-origin GET edge cases).
+ *
+ * When `isTrustedOrigin` is provided, the predicate is evaluated AFTER the
+ * Origin is parsed but BEFORE the strict Host comparison. If the predicate
+ * returns truthy, the request passes — useful when running behind a reverse
+ * proxy that rewrites or strips the `Host` header (Cloudflare Workers
+ * dispatch, Vercel, etc.) while preserving the customer-facing host in
+ * `X-Forwarded-Host`. The predicate is consulted instead of (not in addition
+ * to) the strict check.
+ *
+ * Server-to-server callers without an Origin header should hit the GraphQL
+ * API directly, not these BFF handlers.
+ */
+export declare function validateOrigin(request: Request, options?: {
+    allowMissingOrigin?: boolean;
+    isTrustedOrigin?: OriginValidator | null;
+}): Promise<Response | null>;
 /**
  * Pre-built {@link OriginValidator} that passes when the parsed `Origin` host
  * matches a hostname set by a trusted reverse proxy.

package/dist/core/auth/handlers.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/core/auth/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,sBAAsB,KACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,UAAU,sBAAsB;IAC9B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED,UAAU,wBAAwB;IAChC,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;~~AAqHD~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EAAE,GACvB,eAAe,CAajB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,sBAAsB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiEzC;AAED,UAAU,oBAAoB;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAwEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,CAAC,EAAE,wBAAwB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAoCzC"}
1	+ {"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/core/auth/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,sBAAsB,KACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,UAAU,sBAAsB;IAC9B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED,UAAU,wBAAwB;IAChC,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GACA,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;IACR,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C,GACA,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA2D1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EAAE,GACvB,eAAe,CAajB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,sBAAsB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiEzC;AAED,UAAU,oBAAoB;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAwEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,CAAC,EAAE,wBAAwB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAoCzC"}

package/dist/core/auth/handlers.js CHANGED Viewed

@@ -13,7 +13,14 @@
  * ```
  */
 import { AUTH_COOKIE_NAME, AUTH_COOKIE_DEFAULTS } from './cookie-config';
-function serializeCookie(name, value, options) {
+/**
+ * Serialize a single `Set-Cookie` header value. Shared by the set/clear token
+ * handlers and the `createStorefrontAuthRoute` factory so cookie attribute
+ * emission stays identical across both. The value is emitted as-is — callers
+ * pass cookie-safe values (JWT base64url, opaque `{familyId}.{uuid}`, ISO
+ * timestamps) or pre-encode.
+ */
+export function serializeCookie(name, value, options) {
     const parts = [`${name}=${value}`];
     if (options.maxAge != null)
         parts.push(`Max-Age=${options.maxAge}`);
@@ -55,7 +62,7 @@ function serializeCookie(name, value, options) {
  * Server-to-server callers without an Origin header should hit the GraphQL
  * API directly, not these BFF handlers.
  */
-async function validateOrigin(request, options) {
+export async function validateOrigin(request, options) {
     const origin = request.headers.get('origin');
     // GET/HEAD same-origin: browser omits Origin per fetch spec — pass through.
     // Mutating methods (POST/etc.) MUST have Origin (browsers always send it).

package/dist/core/auth/session-events.d.ts ADDED Viewed

@@ -0,0 +1,38 @@
+/**
+ * Session-expired event channel — auth-level pub/sub (0-deps core).
+ *
+ * Distinct from cart-recovery's `CartSessionExpiredEvent` (scoped to one cart
+ * operation): this fires when the CUSTOMER auth session can no longer be kept
+ * alive — the proactive scheduler's refresh failed on tab wake, or a reactive
+ * refresh after a 401 also failed. Storefronts subscribe once globally
+ * (`useSessionExpired`) and react (notify + redirect to sign-in).
+ *
+ * Mirrors the cart-recovery emitter shape (Set + emit-swallows-listener-errors
+ * + subscribe→unsubscribe). 0-deps (Inv-1): plain `Set` + closure, no React /
+ * DOM. The provider owns the instance (`useRef` + Context, Inv-3) — never a
+ * module-level singleton.
+ */
+export type SessionExpiredReason =
+/** Proactive scheduler tried to refresh on tab wake but the session was already gone. */
+'wake-refresh-failed'
+/** A reactive refresh after a 401 failed (the retry also could not renew the session). */
+ | 'reactive-refresh-failed'
+/** A state-changing operation hit a 401 and was intentionally not retried. */
+ | 'mutation-unauthorized';
+export interface SessionExpiredEvent {
+    /** Why the session is considered expired. */
+    reason: SessionExpiredReason;
+    /** Original error that triggered the event, when one is available. */
+    cause?: unknown;
+}
+export interface SessionExpiredEmitter {
+    /**
+     * Notify every subscriber. Listener exceptions are swallowed so one bad
+     * listener can never break the auth flow nor the other listeners.
+     */
+    emit(event: SessionExpiredEvent): void;
+    /** Subscribe to session-expired events. Returns an unsubscribe function. */
+    subscribe(listener: (event: SessionExpiredEvent) => void): () => void;
+}
+export declare function createSessionExpiredEmitter(): SessionExpiredEmitter;
+//# sourceMappingURL=session-events.d.ts.map

package/dist/core/auth/session-events.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../../../src/core/auth/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,oBAAoB;AAC9B,yFAAyF;AACvF,qBAAqB;AACvB,0FAA0F;GACxF,yBAAyB;AAC3B,8EAA8E;GAC5E,uBAAuB,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACvC,4EAA4E;IAC5E,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACvE;AAED,wBAAgB,2BAA2B,IAAI,qBAAqB,CAoBnE"}

package/dist/core/auth/session-events.js ADDED Viewed

@@ -0,0 +1,35 @@
+/**
+ * Session-expired event channel — auth-level pub/sub (0-deps core).
+ *
+ * Distinct from cart-recovery's `CartSessionExpiredEvent` (scoped to one cart
+ * operation): this fires when the CUSTOMER auth session can no longer be kept
+ * alive — the proactive scheduler's refresh failed on tab wake, or a reactive
+ * refresh after a 401 also failed. Storefronts subscribe once globally
+ * (`useSessionExpired`) and react (notify + redirect to sign-in).
+ *
+ * Mirrors the cart-recovery emitter shape (Set + emit-swallows-listener-errors
+ * + subscribe→unsubscribe). 0-deps (Inv-1): plain `Set` + closure, no React /
+ * DOM. The provider owns the instance (`useRef` + Context, Inv-3) — never a
+ * module-level singleton.
+ */
+export function createSessionExpiredEmitter() {
+    const listeners = new Set();
+    return {
+        emit(event) {
+            for (const listener of listeners) {
+                try {
+                    listener(event);
+                }
+                catch {
+                    // Listeners must not break the auth flow — swallow listener exceptions.
+                }
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/core/cart/cart-recovery.d.ts CHANGED Viewed

@@ -193,6 +193,23 @@ export interface ExecuteWithCartRecoveryOptions<T> {
      * re-auth; the same cart resumes.
      */
     onSessionExpired?: (event: CartSessionExpiredEvent) => void;
+    /**
+     * Server-known cart-id seed used when the cookie store is empty. Cookie
+     * wins when present; the seed only fills the gap on first interaction.
+     *
+     * On Phase 0 the runner eagerly copies the seed into the cookie store so
+     * cross-tab tabs observe the same cart-id and recovery semantics match
+     * the standard cookie-driven path. If the seed is stale the recovery
+     * runner clears it via the usual Phase 2a/2b flow (bail with
+     * `cart-expired` for state-dependent ops, atomic recreate for replayable
+     * ops) — no special-case code needed at this layer.
+     *
+     * Use cases: env seed for dev sample storefronts (sample cart fixture
+     * without a product listing), magic-link checkout, embedded iframe
+     * (parent supplies cart-id via postMessage), customer-service "view this
+     * cart" UI, server-side recovery, multi-cart B2B selectors.
+     */
+    initialCartId?: string | null;
 }
 /**
  * Runs an operation against the current cart, recovering once on
@@ -233,6 +250,12 @@ export interface CreateCartRecoveryRunnerOptions {
     ensureCart?: () => Promise<Cart>;
     /** Cookie `maxAge` propagated to all `cookieStore.set` calls. */
     cookieMaxAge?: number;
+    /**
+     * Server-known cart-id seed — see
+     * `ExecuteWithCartRecoveryOptions.initialCartId`. Applied to every
+     * `execute` and `getCart` call on this runner instance.
+     */
+    initialCartId?: string | null;
 }
 /**
  * Build a per-shop-session runner that shares a recovery coordinator across

package/dist/core/cart/cart-recovery.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cart-recovery.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-recovery.ts"],"names":[],"mappings":"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~~CAC7D~~;AAOD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,IAAI,EAAE,8BAA8B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,CAAC,~~CAmFZ~~;AAMD,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnE;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACjF,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;CACvC;AAED,MAAM,WAAW,+BAA+B;IAC9C,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,eAAe,CAAC;IAC7B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;~~CACvB~~;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,kBAAkB,~~CAmFpB~~;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,IACxC,YAAY,UAAU,KAAG,OAAO,CAAC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAI5F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,EAC5C,UAAU,GAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAM,gBAZrB,UAAU,KAAG,OAAO,CAAC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAe5F"}
1	+ {"version":3,"file":"cart-recovery.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-recovery.ts"],"names":[],"mappings":"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"}

package/dist/core/cart/cart-recovery.js CHANGED Viewed

@@ -156,11 +156,20 @@ async function acquireCartId(coord, factory) {
  * consumers can wire this directly without the runner factory.
  */
 export async function executeWithCartRecovery(opts) {
-    const { cartClient, cookieStore, operation, ensureCart, cookieMaxAge, onExpired, onSessionExpired } = opts;
+    const { cartClient, cookieStore, operation, ensureCart, cookieMaxAge, onExpired, onSessionExpired, initialCartId, } = opts;
     const coord = opts.recoveryCoordinator ?? createCoordinator();
     const opName = operation.name ?? 'unknown';
     // Phase 0 — ensure cart exists (cookie may be empty on first interaction).
+    // Priority: cookie wins (cross-tab canonical state) → initialCartId seed
+    // (server-known via env / SSO / magic-link / iframe / customer service) →
+    // auto-create fallback through the coordinator. The seed is eagerly written
+    // to the cookie so subsequent reads see a canonical value and the recovery
+    // path (Phase 2a/2b) operates on a known cookie when the seed turns out stale.
     let cartId = cookieStore.get();
+    if (!cartId && initialCartId) {
+        cookieStore.set(initialCartId, cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : undefined);
+        cartId = initialCartId;
+    }
     if (!cartId) {
         cartId = await acquireCartId(coord, async () => {
             const created = ensureCart ? await ensureCart() : (await cartClient.create()).cart;
@@ -237,7 +246,7 @@ export async function executeWithCartRecovery(opts) {
  * concurrent operations and exposes an `onExpired` listener pattern.
  */
 export function createCartRecoveryRunner(options) {
-    const { cartClient, cookieStore, ensureCart, cookieMaxAge } = options;
+    const { cartClient, cookieStore, ensureCart, cookieMaxAge, initialCartId } = options;
     const coordinator = createCoordinator();
     const expiredListeners = new Set();
     const sessionListeners = new Set();
@@ -271,6 +280,7 @@ export function createCartRecoveryRunner(options) {
                 operation,
                 ensureCart,
                 cookieMaxAge,
+                initialCartId,
                 recoveryCoordinator: coordinator,
                 onExpired: emitExpired,
                 onSessionExpired: emitSessionExpired,
@@ -278,7 +288,14 @@ export function createCartRecoveryRunner(options) {
             return executeWithCartRecovery(internalOpts);
         },
         async getCart() {
-            const cartId = cookieStore.get();
+            // Symmetric with Phase 0 of `execute` — cookie wins, seed fills the gap
+            // and is eagerly promoted to the cookie so the next mutation picks it up
+            // from the canonical source without re-reading the seed.
+            let cartId = cookieStore.get();
+            if (!cartId && initialCartId) {
+                cookieStore.set(initialCartId, cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : undefined);
+                cartId = initialCartId;
+            }
             if (!cartId)
                 return null;
             try {

package/dist/core/cart/types.d.ts CHANGED Viewed

@@ -93,7 +93,8 @@ export type PaymentSession = PaymentSessionFragment;
 export type DiscountValidationResult = CartValidateDiscountCodeQuery['cartValidateDiscountCode'];
 export type DiscountInfo = NonNullable<DiscountValidationResult['discount']>;
 export type DiscountValidationError = NonNullable<DiscountValidationResult['error']>;
-export type { CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput, CartAttributeInput, CartCompleteInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartSelectPaymentMethodInput, CartClearPaymentSelectionInput, CartSelectShippingMethodInput, CartSetBillingAddressInput, CartSetShippingAddressInput, CartUpdateGiftCardRecipientInput, PaymentCreateInput, ShippingAddressInput, PickupPointInput, DeliveryType, DeliveryEstimate, ShippingCarrier, FreeShippingProgress, PickupPoint, AttributeSelectionInput as CartAttributeSelectionInput, PaymentMethodType, PaymentInitiationFlow, DiscountApplicationType, DiscountErrorCode, CurrencyCode, CountryCode, LanguageCode, ProductTypeEnum, WeightUnit, CartWarningCode, AttributeType, AttributeFillingMode, AttributeBillingMode, AttributeOptionSurchargeType, StorefrontOrderStatus, OrderPaymentStatus, OrderFulfillmentStatus, } from '../generated/operation-types';
+export type { CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput, CartAttributeInput, CartCompleteInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartSelectPaymentMethodInput, CartClearPaymentSelectionInput, CartSelectShippingMethodInput, CartSetBillingAddressInput, CartSetShippingAddressInput, CartUpdateGiftCardRecipientInput, PaymentCreateInput, ShippingAddressInput, PickupPointInput, DeliveryEstimate, ShippingCarrier, FreeShippingProgress, PickupPoint, AttributeSelectionInput as CartAttributeSelectionInput, } from '../generated/operation-types';
+export { DeliveryType, PaymentMethodType, PaymentInitiationFlow, DiscountApplicationType, DiscountErrorCode, CurrencyCode, CountryCode, LanguageCode, ProductTypeEnum, WeightUnit, CartWarningCode, AttributeType, AttributeFillingMode, AttributeBillingMode, AttributeOptionSurchargeType, StorefrontOrderStatus, OrderPaymentStatus, OrderFulfillmentStatus, PaymentProvider, PaymentInstrumentType, PaymentInstrumentDisplayHint, PaymentMethodUnavailableReason, } from '../generated/operation-types';
 /**
  * Machine-readable error code surfaced when `createPayment` fails. The call
  * throws a `StorefrontError` on `userErrors` — read `.userErrors[0].code` off