@doswiftly/storefront-sdk 19.1.0 → 20.0.0

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

@@ -32,14 +32,16 @@
  * provides browser / Next.js server / AsyncStorage / in-memory implementation).
  */
 import { StorefrontError } from '../errors';
+import { parseCartCookieValue } from './cookie-config';
 // ---------------------------------------------------------------------------
 // Error codes — must mirror backend CartErrorCode enum (guarded by drift test)
 // ---------------------------------------------------------------------------
 /**
  * Cart error codes that require recreation of the cart resource.
  *
- * - `CART_NOT_FOUND` — cart expired, missing, or owner mismatch (backend masks
- *   `UNAUTHORIZED` as `CART_NOT_FOUND` to avoid leaking ownership info).
+ * - `CART_NOT_FOUND` — cart expired, missing, or the access secret was absent
+ *   or did not match. The backend returns one uniform code so it never leaks
+ *   whether a given cart exists.
  * - `ALREADY_COMPLETED` — cart status not in `{ACTIVE, RECOVERED}` (CONVERTED
  *   after checkout, EXPIRED via TTL, or ABANDONED by purge worker).
  *
@@ -65,53 +67,6 @@ export function isCartRecoverableError(err) {
         return false;
     return err.userErrors.some((ue) => typeof ue.code === 'string' && RECOVERABLE_CODE_SET.has(ue.code));
 }
-// ---------------------------------------------------------------------------
-// Session error codes — auth-recoverable, distinct from cart-resource recovery
-// ---------------------------------------------------------------------------
-/**
- * Cart error codes that signal a missing or invalid auth context on a
- * customer-owned cart — distinct from cart-resource recovery
- * (`CART_RECOVERABLE_ERROR_CODES`).
- *
- * - `CART_UNAUTHENTICATED` — anonymous request OR present-but-invalid token
- *   (expired JWT, malformed). The cart resource is intact and reachable
- *   again after re-auth.
- *
- * Storefronts SHOULD preserve the `cart-id` cookie when handling these
- * codes and prompt sign-in — the same cart resumes after a successful login.
- */
-export const CART_SESSION_ERROR_CODES = ['CART_UNAUTHENTICATED'];
-const SESSION_CODE_SET = new Set(CART_SESSION_ERROR_CODES);
-/**
- * Type-safe predicate for "this error means the session is gone, but the
- * cart resource is intact". Distinct from `isCartRecoverableError`
- * (cart-resource recovery) — `isCartSessionError` matches auth-recoverable
- * codes that should trigger re-auth flow, NOT cart cookie cleanup.
- *
- * Inspects `err.userErrors[].code` (structured field) — never matches against
- * `err.message` (locale-dependent, non-stable).
- */
-export function isCartSessionError(err) {
-    if (!(err instanceof StorefrontError))
-        return false;
-    if (err.userErrors.length === 0)
-        return false;
-    return err.userErrors.some((ue) => typeof ue.code === 'string' && SESSION_CODE_SET.has(ue.code));
-}
-/**
- * Thrown when a cart operation fails with a session error
- * (`CART_UNAUTHENTICATED`). Distinct from `CartRecoveryNotPossibleError`
- * (cart-resource issue) — storefronts should redirect to a sign-in flow
- * and retry the operation after re-auth.
- */
-export class CartSessionRequiredError extends Error {
-    cause;
-    constructor(cause, message) {
-        super(message ?? 'Session required — please sign in to continue', { cause });
-        this.name = 'CartSessionRequiredError';
-        this.cause = cause;
-    }
-}
 /**
  * Thrown when an operation hits a recoverable cart error but recovery is not
  * possible (no `recreateAndRun`, or recovery itself failed). UI should clear
@@ -150,13 +105,32 @@ async function acquireCartId(coord, factory) {
     coord.inFlight = p;
     return p;
 }
+/**
+ * Promote a server-known seed into the cookie store and return its cart id.
+ *
+ * The seed may be a bare cart id or the composite `<cartId>.<secret>` value.
+ * When it carries a secret the composite is written so later requests send the
+ * access secret and reach the seeded cart; a bare id is written without one and
+ * degrades to a fresh cart on the next write. Returns `null` when the seed does
+ * not parse to a usable cart id.
+ */
+function seedCookieFromInitialCartId(cookieStore, initialCartId, cookieMaxAge) {
+    const parsed = parseCartCookieValue(initialCartId);
+    if (!parsed)
+        return null;
+    cookieStore.set(parsed.cartId, {
+        secret: parsed.cartSecret,
+        ...(cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : {}),
+    });
+    return parsed.cartId;
+}
 /**
  * Runs an operation against the current cart, recovering once on
  * `CART_NOT_FOUND` / `ALREADY_COMPLETED`. Pure async function — non-React
  * consumers can wire this directly without the runner factory.
  */
 export async function executeWithCartRecovery(opts) {
-    const { cartClient, cookieStore, operation, ensureCart, cookieMaxAge, onExpired, onSessionExpired, initialCartId, } = opts;
+    const { cartClient, cookieStore, operation, ensureCart, cookieMaxAge, onExpired, initialCartId, } = opts;
     const coord = opts.recoveryCoordinator ?? createCoordinator();
     const opName = operation.name ?? 'unknown';
     // Phase 0 — ensure cart exists (cookie may be empty on first interaction).
@@ -167,14 +141,16 @@ export async function executeWithCartRecovery(opts) {
     // 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;
+        cartId = seedCookieFromInitialCartId(cookieStore, initialCartId, cookieMaxAge);
     }
     if (!cartId) {
         cartId = await acquireCartId(coord, async () => {
-            const created = ensureCart ? await ensureCart() : (await cartClient.create()).cart;
-            cookieStore.set(created.id, cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : undefined);
-            return created.id;
+            const created = ensureCart ? await ensureCart() : await cartClient.create();
+            cookieStore.set(created.cart.id, {
+                secret: created.secret ?? null,
+                ...(cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : {}),
+            });
+            return created.cart.id;
         });
     }
     // Phase 1 — happy path.
@@ -182,17 +158,6 @@ export async function executeWithCartRecovery(opts) {
         return await operation.run(cartId);
     }
     catch (err) {
-        // Session loss — cart resource intact, re-auth needed. Preserve cookie
-        // so the same cart resumes after a successful login.
-        if (isCartSessionError(err)) {
-            const sessionEvent = {
-                oldCartId: cartId,
-                operation: opName,
-                cause: err,
-            };
-            onSessionExpired?.(sessionEvent);
-            throw new CartSessionRequiredError(err);
-        }
         if (!isCartRecoverableError(err))
             throw err;
         const oldCartId = cartId;
@@ -220,7 +185,10 @@ export async function executeWithCartRecovery(opts) {
         try {
             cookieStore.clear();
             const recreated = await operation.recreateAndRun(cartClient);
-            cookieStore.set(recreated.cart.id, cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : undefined);
+            cookieStore.set(recreated.cart.id, {
+                secret: recreated.secret ?? null,
+                ...(cookieMaxAge !== undefined ? { maxAge: cookieMaxAge } : {}),
+            });
             result = recreated.result;
         }
         catch (recreateErr) {
@@ -249,7 +217,6 @@ export function createCartRecoveryRunner(options) {
     const { cartClient, cookieStore, ensureCart, cookieMaxAge, initialCartId } = options;
     const coordinator = createCoordinator();
     const expiredListeners = new Set();
-    const sessionListeners = new Set();
     function emitExpired(event) {
         for (const listener of expiredListeners) {
             try {
@@ -260,16 +227,6 @@ export function createCartRecoveryRunner(options) {
             }
         }
     }
-    function emitSessionExpired(event) {
-        for (const listener of sessionListeners) {
-            try {
-                listener(event);
-            }
-            catch {
-                // Listeners must not break recovery flow — swallow listener exceptions.
-            }
-        }
-    }
     return {
         cartClient,
         cookieStore,
@@ -283,7 +240,6 @@ export function createCartRecoveryRunner(options) {
                 initialCartId,
                 recoveryCoordinator: coordinator,
                 onExpired: emitExpired,
-                onSessionExpired: emitSessionExpired,
             };
             return executeWithCartRecovery(internalOpts);
         },
@@ -293,8 +249,7 @@ export function createCartRecoveryRunner(options) {
             // 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;
+                cartId = seedCookieFromInitialCartId(cookieStore, initialCartId, cookieMaxAge);
             }
             if (!cartId)
                 return null;
@@ -302,15 +257,6 @@ export function createCartRecoveryRunner(options) {
                 return await cartClient.get(cartId);
             }
             catch (err) {
-                if (isCartSessionError(err)) {
-                    // Cart resource intact — re-auth required. Preserve cookie.
-                    emitSessionExpired({
-                        oldCartId: cartId,
-                        operation: 'getCart',
-                        cause: err,
-                    });
-                    throw new CartSessionRequiredError(err);
-                }
                 if (isCartRecoverableError(err)) {
                     cookieStore.clear();
                     emitExpired({
@@ -328,10 +274,6 @@ export function createCartRecoveryRunner(options) {
             expiredListeners.add(listener);
             return () => expiredListeners.delete(listener);
         },
-        onSessionExpired(listener) {
-            sessionListeners.add(listener);
-            return () => sessionListeners.delete(listener);
-        },
     };
 }
 // ---------------------------------------------------------------------------
@@ -359,7 +301,7 @@ export function createCartRecoveryRunner(options) {
 export function recreateWithInput(input) {
     return async (cartClient) => {
         const outcome = await cartClient.create(input);
-        return { cart: outcome.cart, result: outcome };
+        return { cart: outcome.cart, secret: outcome.secret, result: outcome };
     };
 }
 /**

package/dist/core/cart/cookie-config.d.ts

@@ -2,13 +2,39 @@
  * Cart cookie configuration — platform contract.
  *
  * Used by:
- * - SDK cart store (client-side cookie read/write for cartId)
+ * - SDK cart store (client-side cookie read/write)
  * - Server-side cart prefetching (SSR cart badge, middleware)
  * - proxy.ts (edge cart ID detection)
  *
- * Single cookie for cart ID persistence. Value is a plain cart ID string
- * (not JSON) — server can read it directly via cookies().get('cart-id').
+ * The cookie value is composite: `<cartId>.<secret>`. The cart id is a UUID and
+ * the secret is base64url — neither contains a dot, so the first dot separates
+ * the two halves. A legacy plain `<cartId>` value (written before the cart
+ * carried a secret) parses with `cartSecret: null`; the client then operates
+ * without the `x-cart-secret` header and the backend treats the cart as
+ * unreachable, so the SDK recreates a fresh one.
  */
 export declare const CART_COOKIE_NAME = "cart-id";
 export declare const CART_COOKIE_MAX_AGE: number;
+/**
+ * Structured cart cookie value — the cart identifier plus its access secret.
+ * `cartSecret` is `null` for a legacy plain-id cookie (no secret half).
+ */
+export interface CartCredentials {
+    cartId: string;
+    cartSecret: string | null;
+}
+/**
+ * Parse the raw `cart-id` cookie value into `{ cartId, cartSecret }`.
+ *
+ * - `"<uuid>.<secret>"` → both halves (split on the first dot).
+ * - `"<uuid>"` (no dot, legacy) → `{ cartId, cartSecret: null }`.
+ * - trailing dot (`"<uuid>."`) → id only, `cartSecret: null`.
+ * - empty / leading-dot / blank → `null` (no usable cart id).
+ */
+export declare function parseCartCookieValue(raw: string | null | undefined): CartCredentials | null;
+/** Build the composite `<cartId>.<secret>` cookie value. */
+export declare function formatCartCookieValue(input: {
+    cartId: string;
+    cartSecret: string;
+}): string;
 //# sourceMappingURL=cookie-config.d.ts.map

package/dist/core/cart/cookie-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cookie-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAC1C,eAAO,MAAM,mBAAmB,QAAoB,CAAC"}
+{"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cookie-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAC1C,eAAO,MAAM,mBAAmB,QAAoB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAc3F;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE3F"}

package/dist/core/cart/cookie-config.js

@@ -2,12 +2,44 @@
  * Cart cookie configuration — platform contract.
  *
  * Used by:
- * - SDK cart store (client-side cookie read/write for cartId)
+ * - SDK cart store (client-side cookie read/write)
  * - Server-side cart prefetching (SSR cart badge, middleware)
  * - proxy.ts (edge cart ID detection)
  *
- * Single cookie for cart ID persistence. Value is a plain cart ID string
- * (not JSON) — server can read it directly via cookies().get('cart-id').
+ * The cookie value is composite: `<cartId>.<secret>`. The cart id is a UUID and
+ * the secret is base64url — neither contains a dot, so the first dot separates
+ * the two halves. A legacy plain `<cartId>` value (written before the cart
+ * carried a secret) parses with `cartSecret: null`; the client then operates
+ * without the `x-cart-secret` header and the backend treats the cart as
+ * unreachable, so the SDK recreates a fresh one.
  */
 export const CART_COOKIE_NAME = 'cart-id';
 export const CART_COOKIE_MAX_AGE = 30 * 24 * 60 * 60; // 30 days
+/**
+ * Parse the raw `cart-id` cookie value into `{ cartId, cartSecret }`.
+ *
+ * - `"<uuid>.<secret>"` → both halves (split on the first dot).
+ * - `"<uuid>"` (no dot, legacy) → `{ cartId, cartSecret: null }`.
+ * - trailing dot (`"<uuid>."`) → id only, `cartSecret: null`.
+ * - empty / leading-dot / blank → `null` (no usable cart id).
+ */
+export function parseCartCookieValue(raw) {
+    if (!raw)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const dotIndex = trimmed.indexOf('.');
+    if (dotIndex === -1) {
+        return { cartId: trimmed, cartSecret: null };
+    }
+    const cartId = trimmed.slice(0, dotIndex);
+    const cartSecret = trimmed.slice(dotIndex + 1);
+    if (!cartId)
+        return null;
+    return { cartId, cartSecret: cartSecret || null };
+}
+/** Build the composite `<cartId>.<secret>` cookie value. */
+export function formatCartCookieValue(input) {
+    return `${input.cartId}.${input.cartSecret}`;
+}