@doswiftly/storefront-sdk 16.1.0 → 18.0.0

package/dist/react/helpers/browser-data.js

@@ -0,0 +1,84 @@
+/**
+ * `getBrowserDataForPayment()` — collects browser context required by PSD2/3DS2
+ * authentication flows (card-on-file z 3DS challenge, BLIK confirmation,
+ * Apple/Google Pay z risk scoring).
+ *
+ * **Browser-only** — throws gdy `typeof window === 'undefined'` (server-side
+ * rendering). Caller MUSI gate'ować call w useEffect / event handler / browser
+ * code path. NEVER call this w Server Component lub Route Handler.
+ *
+ * Wartości pochodzą z standard Web APIs:
+ *   - `userAgent` — `navigator.userAgent`.
+ *   - `language` — `navigator.language` (BCP 47, fallback `en-US`).
+ *   - `screen{Width,Height}` — `window.screen.{width,height}`.
+ *   - `colorDepth` — `window.screen.colorDepth`.
+ *   - `timezoneOffset` — `new Date().getTimezoneOffset()` (signed integer, minutes,
+ *     reverse signed per ECMA: dodatnie = behind UTC, ujemne = ahead).
+ *   - `javaEnabled` — `navigator.javaEnabled?.()` (deprecated ale wymagane PSD2/EMV
+ *     specification; fallback `false` gdy browser nie expose'uje).
+ *   - `acceptHeader` — NIE dostępne client-side (`navigator` nie expose'uje request
+ *     headers). Caller passes z server context lub omits (gateway-dependent
+ *     requirement). Helper zwraca undefined.
+ *
+ * Shape matches PSD2/3DS2 BrowserData specification (EMVCo) — adapter na backend
+ * `IPaymentProvider.createPayment` może merge wprost do gateway-specific body
+ * (Adyen `browserInfo`, Stripe `payment_method_data.billing_details.browser_info`,
+ * Mollie `cardToken` z 3DS lookup).
+ *
+ * @example
+ * ```tsx
+ * // W event handler (browser-only):
+ * function handleCheckoutSubmit() {
+ *   const browserData = getBrowserDataForPayment();
+ *   await cart.createPayment({ ..., browserData });
+ * }
+ *
+ * // SSR-safe wrap:
+ * if (typeof window !== 'undefined') {
+ *   const browserData = getBrowserDataForPayment();
+ *   ...
+ * }
+ * ```
+ *
+ * Added by payment-instrument-preselection-advanced sub-sprint Adv-2 Req 9.5
+ * (carry-over z Adv-1 plan — moved here as standalone utility, no backend
+ * mutation impact yet — Adv-3 będzie consumer'em w `paymentCreate` input).
+ */
+/**
+ * Throw'd gdy helper wywołany w SSR context (Server Component, Route Handler,
+ * Node bez JSDOM). Caller MUSI guard'ować przez `typeof window` check albo
+ * wywołać tylko w event handler / `useEffect`.
+ */
+export class BrowserDataNotAvailableError extends Error {
+    constructor() {
+        super('getBrowserDataForPayment requires browser context (window/navigator/screen unavailable).');
+        this.name = 'BrowserDataNotAvailableError';
+    }
+}
+export function getBrowserDataForPayment() {
+    if (typeof window === 'undefined' || typeof navigator === 'undefined' || typeof window.screen === 'undefined') {
+        throw new BrowserDataNotAvailableError();
+    }
+    // `navigator.javaEnabled` jest deprecated ale wciąż obecny w major browsers — guard
+    // dla future removal. Falsy fallback gdy missing (PSD2 spec wymaga boolean, not undefined).
+    const javaEnabled = typeof navigator.javaEnabled === 'function' ? Boolean(navigator.javaEnabled()) : false;
+    // `Intl.DateTimeFormat` jest dostępny we wszystkich modern browsers — optional capture
+    // dla gateways które wymagają IANA name zamiast offset (np. Adyen).
+    let timezone;
+    try {
+        timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        timezone = undefined;
+    }
+    return {
+        userAgent: navigator.userAgent,
+        language: navigator.language || 'en-US',
+        screenWidth: window.screen.width,
+        screenHeight: window.screen.height,
+        colorDepth: window.screen.colorDepth,
+        timezoneOffset: new Date().getTimezoneOffset(),
+        javaEnabled,
+        timezone,
+    };
+}

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

@@ -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,15 +64,35 @@
  *   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
+ * }
+ * ```
  */
-import type { Cart, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput } from '../../core/cart/types';
-import type { CartMutationOutcome } from '../../core/cart/cart-client';
+import type { Cart, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput, CartAttributeInput, CartCompleteInput, CartSelectShippingMethodInput, CartSelectPaymentMethodInput, CartClearPaymentSelectionInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartUpdateGiftCardRecipientInput, PaymentCreateInput, PaymentSession } from '../../core/cart/types';
+import type { CartMutationOutcome, CartCompleteOutcome } from '../../core/cart/cart-client';
 import { type CartExpiredEvent } from '../../core/cart/cart-recovery';
 /**
  * Names of mutations exposed by the hook — narrows `status.operation` for
  * exhaustive consumer-side switching (e.g. operation-specific spinners).
  */
-export type CartManagerOperation = 'addItem' | 'updateItem' | 'removeItem' | 'updateBuyerIdentity' | 'setShippingAddress' | 'updateDiscountCodes' | 'updateNote';
+export type CartManagerOperation = 'addItem' | 'updateItem' | 'removeItem' | 'updateBuyerIdentity' | 'setShippingAddress' | 'setBillingAddress' | 'updateDiscountCodes' | 'updateNote' | 'updateAttributes' | 'selectShippingMethod' | 'selectPaymentMethod' | 'clearPaymentSelection' | 'applyGiftCard' | 'removeGiftCard' | 'updateGiftCardRecipient' | 'complete' | 'createPayment';
 /**
  * Tagged union of cart mutation lifecycle states. Lets callers do exhaustive
  * switching without remembering which boolean flag pairs with which:
@@ -69,6 +119,24 @@ export type CartManagerStatus = {
     type: 'success';
     operation: CartManagerOperation;
 };
+/**
+ * Optional configuration for `useCartManager`. All fields additive — calling
+ * the hook with no arguments preserves the original cookie-driven behaviour.
+ */
+export interface UseCartManagerOptions {
+    /**
+     * Server-known cart-id seed used when the `cart-id` cookie is empty on
+     * mount. Cookie wins when present; the seed only fills the gap on the
+     * first interaction. Eagerly promoted to the cookie store so cross-tab
+     * tabs and standard recovery semantics operate on a canonical value.
+     *
+     * See the hook-level `@example Server-known cart-id` block for the full
+     * Server-Component → Client-Component data flow. Use for env seed (dev),
+     * magic-link checkout, embedded iframe (parent supplies cart-id),
+     * customer service "view this cart", multi-cart B2B selectors.
+     */
+    initialCartId?: string | null;
+}
 export interface UseCartManagerResult {
     getCart: () => Promise<Cart | null>;
     getCartId: () => string | null;
@@ -77,8 +145,31 @@ export interface UseCartManagerResult {
     setShippingAddress: (address: CartAddressInput) => Promise<CartMutationOutcome>;
     updateDiscountCodes: (codes: string[]) => Promise<CartMutationOutcome>;
     updateNote: (note: string) => Promise<CartMutationOutcome>;
+    updateAttributes: (attributes: CartAttributeInput[]) => Promise<CartMutationOutcome>;
     updateItem: (lines: CartLineUpdateInput[]) => Promise<CartMutationOutcome>;
     removeItem: (lineIds: string[]) => Promise<CartMutationOutcome>;
+    setBillingAddress: (address: CartAddressInput) => Promise<CartMutationOutcome>;
+    selectShippingMethod: (input: Omit<CartSelectShippingMethodInput, 'cartId'>) => Promise<CartMutationOutcome>;
+    selectPaymentMethod: (input: Omit<CartSelectPaymentMethodInput, 'cartId'>) => Promise<CartMutationOutcome>;
+    clearPaymentSelection: (input?: Omit<CartClearPaymentSelectionInput, 'cartId'>) => Promise<CartMutationOutcome>;
+    applyGiftCard: (input: Omit<CartApplyGiftCardInput, 'cartId'>) => Promise<CartMutationOutcome>;
+    removeGiftCard: (input: Omit<CartRemoveGiftCardInput, 'cartId'>) => Promise<CartMutationOutcome>;
+    updateGiftCardRecipient: (input: Omit<CartUpdateGiftCardRecipientInput, 'cartId'>) => Promise<CartMutationOutcome>;
+    /**
+     * Finalise the cart into an Order. On success the `cart-id` cookie is
+     * cleared and status resets to `idle` — a follow-up `addItem` auto-creates
+     * a fresh cart, matching shop-again UX. The cart itself is NOT returned
+     * (CONVERTED/locked after completion); work with `result.order` for
+     * post-checkout flows (`order.canCreatePayment`, `order.accessToken`).
+     */
+    complete: (input?: Omit<CartCompleteInput, 'cartId'>) => Promise<CartCompleteOutcome>;
+    /**
+     * Initiate a payment session for an order created by `complete`. NOT a
+     * cart operation (works on `orderId`, not `cartId`) — included on the
+     * manager for a single checkout-lifecycle API. Throws on
+     * `userErrors[].code === 'PAYMENT_*'` — branch on `err.userErrors[0].code`.
+     */
+    createPayment: (input: PaymentCreateInput) => Promise<PaymentSession>;
     clearCart: () => void;
     onExpired: (listener: (event: CartExpiredEvent) => void) => () => void;
     status: CartManagerStatus;
@@ -87,5 +178,5 @@ export interface UseCartManagerResult {
     /** Error message when status.type === 'error', otherwise null. */
     error: string | null;
 }
-export declare function useCartManager(): UseCartManagerResult;
+export declare function useCartManager(options?: UseCartManagerOptions): UseCartManagerResult;
 //# sourceMappingURL=use-cart-manager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"use-cart-manager.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAMH,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,+BAA+B,CAAC;AAGvC;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,qBAAqB,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,YAAY,CAAC;AAEjB;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,oBAAoB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IAEnC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAG/B,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClE,mBAAmB,EAAE,CAAC,aAAa,EAAE,sBAAsB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7F,kBAAkB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChF,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAG3D,UAAU,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3E,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAGhE,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAGvE,MAAM,EAAE,iBAAiB,CAAC;IAG1B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,cAAc,IAAI,oBAAoB,CA0LrD"}
+{"version":3,"file":"use-cart-manager.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart-manager.ts"],"names":[],"mappings":"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"}

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

@@ -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"}