@doswiftly/storefront-sdk 21.0.0 → 21.0.1

package/README.md

@@ -6,12 +6,17 @@ Layered runtime SDK for DoSwiftly Commerce storefronts. Framework-agnostic core
 
 ```
 @doswiftly/storefront-sdk
-├── core (.)              — Framework-agnostic: transport, middleware, CartClient, AuthClient,
-│                           cache, format utilities, image types, sanitizeHtml,
-│                           normalizeConnection, auth cookie config/handlers/token client, route matching
-├── react (./react)       — React adapter: providers, Zustand stores (Context-based), hooks,
-│                           useHydrated, useDebouncedValue, createStoreContext
-├── react/server          — Server-side client factory
+├── core (.)              — Framework-agnostic: transport + middleware pipeline,
+│                           CartClient / AuthClient, cart recovery runner,
+│                           cart capability cookie (id + secret), auth route helpers,
+│                           bot-protection managers, errors, format utilities,
+│                           sanitizeHtml, normalizeConnection, schema enums
+├── react (./react)       — React adapter: StorefrontProvider, CartManagerProvider,
+│                           Zustand stores (Context-based), auth/cart/session hooks,
+│                           pre-built headless components
+├── react/server          — Server-side: client factory, SDK-BFF auth route
+│                           (createStorefrontAuthRoute), getInitialAuth,
+│                           first-party cookie readers, server cart-secret middleware
 └── cache (./cache)       — Cache strategy functions
 ```
 
@@ -38,383 +43,569 @@ Scaffolded storefronts (`doswiftly init`) ship a `graphqlConfig` helper (`lib/gr
 
 If you go the env-var route, use **exactly these names** — `doswiftly dev` keys off them when overriding. Inventing `API_URL`, `STOREFRONT_URL`, or `TENANT_SLUG` means the dev proxy starts, but your storefront still calls the production API directly and you only learn about it on the first client-side mutation (build and SSR pass silently).
 
+Scratch-built storefronts can read `process.env.NEXT_PUBLIC_*` directly and pass the values into `config={}` — the resolution helper is a convenience, not a requirement.
+
+## Quick start — Next.js App Router
+
+Four files give you a production-grade storefront runtime: first-party auth cookies with automatic session refresh, a shared cart with stale-cart auto-recovery, and a typed GraphQL client with the full middleware pipeline.
+
+**1. `app/api/auth/[action]/route.ts`** — one file mounts the whole auth surface
+(`POST /api/auth/login | refresh | logout`, `GET /api/auth/whoami`). The handlers
+run on the storefront's own domain, call the backend server-to-server, and own the
+first-party httpOnly cookies — the refresh token never reaches browser JavaScript:
+
 ```ts
-// app/layout.tsx — Next.js App Router, template-generated wiring
-import { graphqlConfig } from '@/lib/graphql/config';
+import {
+  createStorefrontAuthRoute,
+  trustedForwardedHostValidator,
+} from '@doswiftly/storefront-sdk/react/server';
 
-<StorefrontProvider
-  config={{ apiUrl: graphqlConfig.apiUrl, shopSlug: graphqlConfig.shopSlug }}
-  shopData={shopData}
->
-  {children}
-</StorefrontProvider>
+export const { GET, POST } = createStorefrontAuthRoute({
+  apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+  shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+  // Pass when the storefront runs behind a reverse proxy that rewrites Host
+  // (DoSwiftly hosting, Vercel). Omit for bare deployments / local dev.
+  isTrustedOrigin: trustedForwardedHostValidator,
+});
 ```
 
-Scratch-built storefronts can read `process.env.NEXT_PUBLIC_*` directly and pass the values into `config={}` — the resolution helper is a convenience, not a requirement.
+**2. `app/layout.tsx`** — seed the first render from the first-party cookies via
+`getInitialAuth()` (no signed-out flash, no whoami round-trip) and wrap the tree
+in `StorefrontProvider`:
+
+```tsx
+import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+import { getStorefrontClient, getInitialAuth } from '@doswiftly/storefront-sdk/react/server';
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const serverClient = getStorefrontClient({
+    apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+    shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+  });
+
+  // `SHOP_CONFIG_QUERY` is your own operation — generated by graphql-codegen from
+  // `@doswiftly/storefront-operations/schema.graphql`. It must request the fields
+  // of the `ShopConfig` shape: `currencyCode`, `supportedCurrencies`,
+  // `defaultLanguage`, `supportedLanguages`, `botProtection`.
+  const [{ shop }, initialAuth] = await Promise.all([
+    serverClient.query(SHOP_CONFIG_QUERY),
+    getInitialAuth(),
+  ]);
+
+  return (
+    <html lang="pl">
+      <body>
+        <StorefrontProvider
+          config={{
+            apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+            shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+          }}
+          shopData={shop}
+          initialIsAuthenticated={initialAuth.isAuthenticated}
+          initialAccessToken={initialAuth.accessToken}
+          initialExpiresAt={initialAuth.expiresAt}
+        >
+          {children}
+        </StorefrontProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+Session refresh is **automatic** — the provider defaults to `autoRefresh` in the
+browser: a scheduler renews the access token shortly before it expires, and a 401
+on a read query triggers a single deduped refresh + replay. Pass
+`autoRefresh={false}` to drive refreshing yourself.
+
+**3. Cart — wrap the shopping subtree in `CartManagerProvider`** (one shared cart
+manager: one loading state, one recovery queue) and read it with
+`useCartManagerContext()`:
+
+```tsx
+'use client';
+import { CartManagerProvider, useCartManagerContext } from '@doswiftly/storefront-sdk/react';
+import { toast } from 'sonner';
+
+export function ShopProviders({ children }: { children: React.ReactNode }) {
+  return (
+    <CartManagerProvider
+      onMutationError={(operation, error) => toast.error(error.message)}
+    >
+      {children}
+    </CartManagerProvider>
+  );
+}
+
+export function AddToCart({ variantId }: { variantId: string }) {
+  const { addItem, status } = useCartManagerContext();
+  return (
+    <button
+      onClick={() => addItem([{ variantId, quantity: 1 }])}
+      disabled={status.type === 'loading'}
+    >
+      Add to cart
+    </button>
+  );
+}
+```
+
+The cart cookie, the cart access secret, creation on first add, and stale-cart
+recovery are all handled for you — see [Cart](#cart).
 
-## Quick Start
+**4. Global session + cart expiry handling** — mount once near the root:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { useSessionExpired, useCartManagerContext } from '@doswiftly/storefront-sdk/react';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+
+export function GlobalGuards() {
+  const router = useRouter();
+  const { onExpired } = useCartManagerContext();
+
+  // Fired when the SDK can no longer keep the customer session alive.
+  useSessionExpired(() => router.replace('/auth/login?reason=session_expired'));
+
+  // Fired when a stale cart cannot be transparently recovered.
+  useEffect(
+    () => onExpired(() => toast.error('Your cart expired — please add the items again')),
+    [onExpired],
+  );
+  return null;
+}
+```
 
-### Core (framework-agnostic)
+## Quick start — Core (framework-agnostic)
 
 ```typescript
 import {
   createStorefrontClient,
-  authMiddleware,
-  currencyMiddleware,
+  cartSecretMiddleware,
   retryMiddleware,
   timeoutMiddleware,
   errorMiddleware,
   CartClient,
-  AuthClient,
+  formatCartCookieValue,
 } from '@doswiftly/storefront-sdk';
 
+let cartSecret: string | null = null;
+
 const client = createStorefrontClient({
   apiUrl: 'https://api.doswiftly.pl',
   shopSlug: 'my-shop',
   middleware: [
-    authMiddleware(() => getToken()),
-    currencyMiddleware(() => getCurrency()),
+    cartSecretMiddleware(() => cartSecret), // lazy getter — picks up rotation
     retryMiddleware({ maxRetries: 2 }),
     timeoutMiddleware({ timeout: 5000 }),
     errorMiddleware(), // ALWAYS LAST
   ],
 });
 
-// Query (deduplicated, cached)
-const data = await client.query(ProductQuery, { handle: 'foo' }, cacheLong());
+const cartClient = new CartClient(client);
+
+// `create` reveals a one-time cart access secret — store it immediately.
+// Possession of the secret is what authorizes cart reads and writes.
+const { cart, secret } = await cartClient.create();
+cartSecret = secret;
+if (secret) {
+  persistCookie('cart-id', formatCartCookieValue({ cartId: cart.id, cartSecret: secret }));
+}
 
-// Mutation (never cached, never retried)
-const result = await client.mutate(CartCreateMutation, { input: {} });
+const { cart: updated, warnings } = await cartClient.addItems(cart.id, [
+  { variantId: 'variant-123', quantity: 1 },
+]);
 ```
 
-### React (Next.js)
+Queries are deduplicated and cacheable; mutations are never cached and never
+retried.
 
-```tsx
-// app/layout.tsx
-import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+## Export paths
 
-export default function Layout({ children }) {
-  return (
-    <StorefrontProvider
-      config={{ apiUrl: process.env.NEXT_PUBLIC_API_URL!, shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG! }}
-      shopData={shopData}
-    >
-      {children}
-    </StorefrontProvider>
-  );
-}
-```
+| Path | Description | Dependencies |
+|------|-------------|-------------|
+| `@doswiftly/storefront-sdk` | Core: transport, middleware, clients, recovery, errors, format, enums, cookie contracts | **0** |
+| `@doswiftly/storefront-sdk/react` | Providers, hooks, stores, pre-built UI components | react, zustand |
+| `@doswiftly/storefront-sdk/react/server` | Server client factory, SDK-BFF auth route, cookie readers | react (peer; `getInitialAuth` additionally requires Next.js) |
+| `@doswiftly/storefront-sdk/cache` | Cache strategy functions | **0** |
+
+## Authentication
+
+### Session model
+
+Auth runs through **BFF route handlers on the storefront's own domain**
+(`createStorefrontAuthRoute`). The browser never talks to the backend directly
+for auth — the route handlers do, server-to-server. First-party cookies work
+identically on a platform subdomain, a custom domain, and off-platform hosting.
+
+| Cookie | httpOnly | Path | Purpose |
+|--------|----------|------|---------|
+| `customerAccessToken` | yes | `/` | Access token — read server-side to seed SSR and the in-memory store |
+| `customerRefreshToken` | yes | `/api/auth` | Refresh token — read exclusively server-side by the BFF route |
+| `session-expiry` | no | `/` | Readable absolute expiry (ISO 8601) for the refresh scheduler |
+
+Renewal is automatic (`<StorefrontProvider autoRefresh>` — default ON in the
+browser):
+
+- **Proactive** — a scheduler calls `POST {authBasePath}/refresh` shortly before
+  `expiresAt`; the route rotates the refresh cookie and returns a fresh access token.
+- **Reactive** — a 401 on a read query triggers one deduped refresh and replays
+  the query. A 401 on a **mutation** never retries — it fires the
+  `session-expired` signal instead (replaying a mutation, e.g. a payment, would
+  be unsafe).
+
+When the session cannot be kept alive, subscribe globally:
 
 ```tsx
-// Client Component
 'use client';
-import { useAuth, useCartManager, useAuthStore, useCurrencyStore, useAuthHydrated } from '@doswiftly/storefront-sdk/react';
+import { useSessionExpired } from '@doswiftly/storefront-sdk/react';
 
-const { login, logout } = useAuth({ onSetToken, onClearToken });
-const { addItem, removeItem, lines, isLoading } = useCartManager();
-const { isAuthenticated, customer } = useAuthStore();
-const authHydrated = useAuthHydrated(); // true after persist rehydration
-const { currency, setCurrency } = useCurrencyStore();
+useSessionExpired((event) => router.replace('/auth/login'));
 ```
 
-## Export Paths
+### Sign-in form (BFF login)
 
-| Path | Description | Dependencies |
-|------|-------------|-------------|
-| `@doswiftly/storefront-sdk` | Core: transport, middleware, clients, errors, format, image types, sanitize, auth handlers, route matching | **0** |
-| `@doswiftly/storefront-sdk/react` | Providers, hooks, pre-built UI components, Zustand stores | react, zustand |
-| `@doswiftly/storefront-sdk/react/server` | Server-side client factory | react |
-| `@doswiftly/storefront-sdk/cache` | Cache strategy functions | **0** |
+`POST {authBasePath}/login` is the only flow that sets the **full cookie set**
+(access + refresh + expiry) on the storefront domain — required for automatic
+session refresh. Post the credentials, then seed the client-side store with the
+returned token:
 
-## Next.js 16 App Router — first add-to-cart in 15 minutes
+```tsx
+'use client';
+import { useAuthStore } from '@doswiftly/storefront-sdk/react';
+
+export function LoginForm() {
+  const setAuth = useAuthStore((s) => s.setAuth);
+
+  async function onSubmit(email: string, password: string) {
+    const res = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+    if (!res.ok) {
+      // Backend errors are passed through verbatim (already localized).
+      const body = await res.json().catch(() => null);
+      showError(body);
+      return;
+    }
+    const { accessToken, expiresAt, customer } = await res.json();
+    setAuth(customer ?? null, accessToken, expiresAt);
+  }
+  // ...
+}
+```
+
+After a successful sign-in, merge the guest cart into the customer's cart with
+`cartClient.merge(guestCartId)` — see [Auth ↔ cart lifecycle](#auth--cart-lifecycle).
 
-End-to-end skeleton that gets you a working cart + auth flow without writing
-the middleware pipeline by hand. Copy the files below into a fresh `app/`
-directory and you're live.
+### GraphQL auth hooks — `useLogin` / `useLogout` / `useAuth`
 
-**1. `app/layout.tsx`** — wrap the tree in `StorefrontProvider`:
+The focused hooks drive auth over the **GraphQL transport**
+(`customerLogin` / `customerLogout` mutations) and keep the token in the
+in-memory store. The backend sets/clears its own httpOnly cookie on these
+mutations, on the **API domain** — fine for same-site setups and non-browser
+clients. For first-party cookies on the storefront domain (and the refresh
+cookie required by `autoRefresh`) prefer the BFF login above; the optional
+`onSetToken` / `onClearToken` callbacks let you sync a cookie through your own
+route during migration from older setups.
 
 ```tsx
-import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
-import { getStorefrontClient } from '@doswiftly/storefront-sdk/react/server';
-import { cookies } from 'next/headers';
-import { AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
+import { useLogin, useLogout } from '@doswiftly/storefront-sdk/react';
 
-export default async function RootLayout({ children }: { children: React.ReactNode }) {
-  const serverClient = getStorefrontClient({
-    apiUrl: process.env.NEXT_PUBLIC_API_URL!,
-    shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
-  });
-  // `SHOP_BASICS_QUERY` is your own operation — generated by graphql-codegen
-  // from `@doswiftly/storefront-operations/schema.graphql`. It should request
-  // `shop.currency`, `shop.supportedCurrencies`, `shop.supportedLanguages`,
-  // `shop.botProtection` — whatever StorefrontProvider needs.
-  const { shop } = await serverClient.query(SHOP_BASICS_QUERY);
-
-  // 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 initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+const { login, isLoggingIn, error } = useLogin();
+const { logout, isLoggingOut } = useLogout();
 
-  return (
-    <html lang="pl">
-      <body>
-        <StorefrontProvider
-          config={{
-            apiUrl: process.env.NEXT_PUBLIC_API_URL!,
-            shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
-          }}
-          shopData={shop}
-          initialAccessToken={initialAccessToken}
-        >
-          {children}
-        </StorefrontProvider>
-      </body>
-    </html>
-  );
-}
+const result = await login(email, password);
+if (!result.success) showErrors(result.userErrors); // backend-translated messages
 ```
 
-> **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.
+`useLogout` additionally downgrades the active cart to guest before logging out
+(clears the customer's contact details, addresses and saved-payment selection so
+they do not linger on a shared device) — best-effort, never blocks sign-out.
 
-**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:
+`useAuth(options?)` is a convenience facade aggregating `useLogin`, `useLogout`
+and `useRefreshToken`:
 
 ```ts
-import { createSetTokenHandler } from '@doswiftly/storefront-sdk';
-export const POST = createSetTokenHandler();
+const {
+  login, logout, refreshToken,
+  isLoggingIn, isLoggingOut, isRefreshingToken, isLoading,
+  error,
+} = useAuth();
 ```
 
-**3. `app/api/auth/clear-token/route.ts`** — clears the cookie on logout:
+Auth **state** (customer, flags) lives in the store, not in the hooks:
 
 ```ts
-import { createClearTokenHandler } from '@doswiftly/storefront-sdk';
-export const POST = createClearTokenHandler();
+import { useAuthStore, useAuthHydrated } from '@doswiftly/storefront-sdk/react';
+
+const isAuthenticated = useAuthStore((s) => s.isAuthenticated);
+const customer = useAuthStore((s) => s.customer);
+const authHydrated = useAuthHydrated(); // true after persist rehydration
 ```
 
-**4. `app/api/auth/whoami/route.ts`** — hydrates customer state from the
-httpOnly cookie after a hard refresh (`accessToken` no longer persists in
-localStorage — XSS hardening):
+### AuthClient (no React)
 
-```ts
-import { createWhoamiHandler } from '@doswiftly/storefront-sdk';
+```typescript
+import { AuthClient } from '@doswiftly/storefront-sdk';
 
-export const GET = createWhoamiHandler({
-  apiUrl: process.env.NEXT_PUBLIC_API_URL!,
-  shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
-});
+const authClient = new AuthClient(client, { authBasePath: '/api/auth' });
 ```
 
-**5. Sign-in form** — uses the focused `useLogin` hook + wires the BFF
-callback:
+| Method | Returns | Notes |
+|---|---|---|
+| `login(email, password)` | `Promise<AuthResult>` | GraphQL mutation; throws `StorefrontError` with backend-translated `userErrors` |
+| `register(input)` | `Promise<AuthResult>` | `CustomerCreateInput`; result carries `customer` |
+| `logout()` | `Promise<void>` | Never throws (token may already be expired) |
+| `refreshSession()` | `Promise<SessionRefreshResult>` | Same-origin `POST {authBasePath}/refresh` (BFF) — works with an **expired** access token; throws `SESSION_EXPIRED` on failure |
+| `getCustomer()` | `Promise<Customer \| null>` | `null` when unauthenticated |
+| `getAddresses()` | `Promise<MailingAddress[] \| null>` | Saved address book incl. B2B fields (`taxId`, `vatNumber`) and `isDefault`; `null` when unauthenticated |
+| `refreshToken()` | `Promise<AuthResult>` | **Deprecated** — GraphQL refresh requires a still-valid access token; use `refreshSession()` |
 
-```tsx
-'use client';
-import { useLogin } from '@doswiftly/storefront-sdk/react';
+### Low-level route handlers (escape hatch)
 
-export function LoginForm() {
-  const { login, isLoggingIn, error } = useLogin({
-    onSetToken: async (token) => {
-      await fetch('/api/auth/set-token', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token }),
-      });
-    },
-  });
+`createStorefrontAuthRoute` is the recommended mount. The standalone Web API
+factories remain available for custom setups and migrations:
 
-  return (
-    <form onSubmit={async (e) => {
-      e.preventDefault();
-      const data = new FormData(e.currentTarget);
-      const result = await login(String(data.get('email')), String(data.get('password')));
-      if (result.success) location.href = '/account';
-    }}>
-      <input name="email" type="email" required />
-      <input name="password" type="password" required />
-      <button type="submit" disabled={isLoggingIn}>{isLoggingIn ? 'Signing in…' : 'Sign in'}</button>
-      {error && <p role="alert">{error}</p>}
-    </form>
-  );
-}
+```ts
+import {
+  createSetTokenHandler,   // POST — sets the httpOnly access-token cookie
+  createClearTokenHandler, // POST — clears it
+  createWhoamiHandler,     // GET  — hydrates { isAuthenticated, customer } from the cookie
+} from '@doswiftly/storefront-sdk';
+
+export const POST = createSetTokenHandler();
 ```
 
-**6. Product card with add-to-cart** — pre-built components:
+All handlers are pure Web API (`Request`/`Response`) — they run in Next.js Route
+Handlers, Cloudflare Workers, Deno, etc. Security baked in: strict origin
+validation, Content-Type check, `SameSite=Lax`, httpOnly cookies.
 
-```tsx
-'use client';
-import { Image, PriceDisplay, AddToCartButton } from '@doswiftly/storefront-sdk/react';
+### Behind a reverse proxy
 
-export function ProductCard({ product }: { product: ProductCardFields }) {
-  return (
-    <article>
-      <Image data={product.featuredImage} sizes="(max-width: 768px) 100vw, 33vw" />
-      <h2>{product.title}</h2>
-      <PriceDisplay
-        price={product.price.amount * 100}
-        compareAtPrice={product.compareAtPrice ? product.compareAtPrice.amount * 100 : undefined}
-        currency={product.price.currencyCode}
-      />
-      <AddToCartButton variantId={product.firstVariant.id}>Add to cart</AddToCartButton>
-    </article>
-  );
-}
+When a proxy rewrites/strips `Host` (DoSwiftly hosting, Vercel, NGINX), strict
+`Origin host === Host` validation would 403 every auth call. Every handler (and
+`createStorefrontAuthRoute`) accepts an `isTrustedOrigin` predicate:
+
+```ts
+import {
+  trustedForwardedHostValidator, // trust X-Forwarded-Host (set by the proxy)
+  originAllowlistValidator,      // static allowlist of origins
+} from '@doswiftly/storefront-sdk';
+
+createStorefrontAuthRoute({ apiUrl, shopSlug, isTrustedOrigin: trustedForwardedHostValidator });
+// or
+createSetTokenHandler({
+  isTrustedOrigin: originAllowlistValidator(['https://shop.example.com']),
+});
 ```
 
-That's it. Cart recovery (stale-cart auto-replay) is automatic — wire a single
-global `onExpired` toast subscriber once in `app/layout.tsx`:
+Custom predicates get `({ origin, originHost, request })` and may be async. A
+throwing predicate fails closed (falls back to strict matching).
 
-```tsx
-'use client';
-import { useEffect } from 'react';
-import { useCartManager } from '@doswiftly/storefront-sdk/react';
-import { toast } from 'sonner';
+### Auth token client (client-side helper)
 
-export function CartExpiredToast() {
-  const { onExpired } = useCartManager();
-  useEffect(() => onExpired((e) => {
-    toast.error(e.reason === 'state-dependent'
-      ? 'Twój koszyk wygasł, dodaj produkty ponownie'
-      : 'Nie udało się odzyskać koszyka, spróbuj ponownie');
-  }), [onExpired]);
-  return null;
-}
+```typescript
+import { createAuthTokenClient } from '@doswiftly/storefront-sdk';
+
+const { setToken, clearToken } = createAuthTokenClient();
+await setToken(accessToken);  // POST /api/auth/set-token
+await clearToken();           // POST /api/auth/clear-token
 ```
 
-## Pre-built React components
+## Cart
 
-Headless, accessibility-aware, zero styling — pass `className` to integrate
-with your CSS approach. Available from `@doswiftly/storefront-sdk/react`:
+### Capability model — cart id + secret
 
-| Component | Purpose |
-|-----------|---------|
-| `<Money amount currency>` | Locale-formatted price string from minor units |
-| `<Image data sizes priority>` | `<img>` with thumbhash blur placeholder + sane defaults |
-| `<CartCount count label>` | Aria-live cart item count |
-| `<AddToCartButton variantId quantity>` | Button wired to `useCartManager.addItem` |
-| `<PriceDisplay price compareAtPrice currency>` | Price + optional strikethrough sale price |
-| `<CartTotals subtotal tax shipping discount total currency>` | Cart financial breakdown `<dl>` |
+Cart access is authorized by **possession of a secret**, not by the customer
+session. The `cart-id` cookie stores a composite value `"<cartId>.<secret>"`
+(30 days, SSR/edge-visible, not httpOnly — the cart carries no payment data).
+`CartClient.create()` and `recoveryRedeem()` reveal the secret **once**; the SDK
+persists it into the cookie for you. Every request then carries the secret in
+the `x-cart-secret` header via middleware:
+
+- **Browser**: `StorefrontProvider` wires `cartSecretMiddleware` automatically —
+  the secret is read lazily from the cookie on every request, so a rotated
+  secret is picked up without rebuilding the client.
+- **Server (SSR/edge)**: prepend `serverCartSecretMiddleware(await readCartCredentials())`
+  to your server client — see [Server-side](#server-side-reactserver).
+- **Custom runtimes**: `cartSecretMiddleware(() => secret)` + the
+  `parseCartCookieValue` / `formatCartCookieValue` helpers.
+
+A cookie without the secret half (or a stale capability) makes the cart
+unreachable — mutations reject with `CART_NOT_FOUND` and the standard recovery
+flow recreates a fresh cart.
+
+### `useCartManager` — cookie-driven cart + checkout lifecycle
+
+The primary React cart API. Owns the `cart-id` cookie, auto-creates the cart on
+first add, persists the secret, and recovers from stale carts per operation:
 
 ```tsx
-import { Money, Image, CartCount, AddToCartButton, PriceDisplay, CartTotals } from '@doswiftly/storefront-sdk/react';
+'use client';
+import { useCartManager } from '@doswiftly/storefront-sdk/react';
 
-<Money amount={9990} currency="PLN" />          {/* "99,90 zł" */}
-<PriceDisplay price={7990} compareAtPrice={9990} currency="PLN" />
-<CartCount count={3} label="items" />
+const {
+  // Read
+  getCart, getCartId,
+  // Mutations (all return Promise<CartMutationOutcome> = { cart, warnings })
+  addItem, updateItem, removeItem,
+  updateBuyerIdentity, setShippingAddress, setBillingAddress,
+  updateDiscountCodes, updateNote, updateAttributes,
+  selectShippingMethod, selectPaymentMethod, clearPaymentSelection,
+  applyGiftCard, removeGiftCard, updateGiftCardRecipient,
+  // Completion
+  complete,      // Promise<CartCompleteOutcome> = { order, warnings }
+  createPayment, // Promise<PaymentSession> — post-completion, works on orderId
+  // Lifecycle
+  clearCart, onExpired,
+  // Reactive state
+  status,        // tagged union — see below
+  isLoading, error, // derived selectors over `status`
+} = useCartManager(options?);
 ```
 
-## GraphQL schema for codegen
+**Per-operation recovery strategy** — when a write hits a stale cart
+(`userErrors[].code` ∈ `CART_NOT_FOUND` / `ALREADY_COMPLETED`):
 
-The GraphQL SDL ships in the linked `@doswiftly/storefront-operations` package
-(which is installed alongside the SDK) — point your codegen / IDE plugin at it
-directly. No live backend required:
+| Strategy | Operations | Behaviour |
+|---|---|---|
+| **Auto-replay** | `addItem`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote`, `updateAttributes` | Transparently recreates the cart via an atomic `cartCreate(input)` and resolves as success |
+| **Bail + event** | `updateItem`, `removeItem`, `setBillingAddress`, `selectShippingMethod`, `selectPaymentMethod`, `clearPaymentSelection`, `applyGiftCard`, `removeGiftCard`, `updateGiftCardRecipient`, `complete` | Clears the cookie, throws `CartRecoveryNotPossibleError`, and fires every `onExpired` listener — subscribe once globally instead of try/catching every call site |
+| **Out of scope** | `createPayment` | Operates on `orderId` (post-completion) — no cart to recover |
 
-```ts
-// codegen.ts — uses raw .graphql file from the operations package
-const config = {
-  schema: 'node_modules/@doswiftly/storefront-operations/schema.graphql',
-  documents: ['./app/**/*.{ts,tsx,graphql}'],
-  generates: { './generated/graphql.ts': { /* … */ } },
-};
-export default config;
+**Status** is a tagged union for exhaustive rendering:
+
+```tsx
+const { status } = useCartManager();
+if (status.type === 'loading') return <Spinner label={status.operation} />;
+if (status.type === 'error') return <ErrorBanner error={status.error} />;
+// status.type ∈ { 'idle', 'success' }
 ```
 
-For VS Code GraphQL extension, point `graphql-config` at the same path.
+**Options** (`UseCartManagerOptions`) — all additive:
 
-## Auth: focused hooks vs the facade
+| Option | Purpose |
+|---|---|
+| `initialCartId` | Server-known cart-id seed used when the cookie is empty on mount (cookie wins). Accepts a bare id or the composite `"<cartId>.<secret>"` value — pass the composite when the secret is known server-side. Use cases: SSR checkout, magic-link, embedded iframe, customer-service "view this cart", multi-cart B2B. |
+| `onMutationStart` / `onMutationSuccess` / `onMutationError` | Lifecycle callbacks around every operation — centralize toasts / router refresh / loading indicators. Cart expiry goes to `onExpired`, **not** `onMutationError`. |
+| `cookieDebug` | Debug sink for `cart-id` cookie writes — see [Debug logging](#debug-logging). |
 
-Prefer the per-flow hooks in new code — smaller bundles, isolated state:
+### `<CartManagerProvider>` — one shared instance
+
+`useCartManager` keeps per-mount state, so calling it in several components
+creates independent managers. Wrap the subtree (inside `StorefrontProvider`) and
+read the shared instance with `useCartManagerContext()`:
 
 ```tsx
-import { useLogin, useLogout, useRefreshToken } from '@doswiftly/storefront-sdk/react';
+'use client';
+import { CartManagerProvider, useCartManagerContext } from '@doswiftly/storefront-sdk/react';
+
+<CartManagerProvider
+  initialCartId={initialCartId}
+  onMutationSuccess={() => router.refresh()}
+  onMutationError={(operation, error) => toast.error(error.message)}
+>
+  <CheckoutForm />
+</CartManagerProvider>;
 
-const { login, isLoggingIn } = useLogin({ onSetToken });
-const { logout, isLoggingOut } = useLogout({ onClearToken });
-const { refreshToken } = useRefreshToken({ onSetToken });
+// CheckoutForm.tsx
+const { addItem, complete, status } = useCartManagerContext();
 ```
 
-The legacy `useAuth` facade still works (combines all three):
+For deliberately independent managers (multi-cart B2B, an admin "view this cart"
+panel) call `useCartManager()` directly instead.
+
+### Checkout completion + payment
 
 ```tsx
-import { useAuth } from '@doswiftly/storefront-sdk/react';
-const { login, logout, refreshToken, isLoading, error } = useAuth({ onSetToken, onClearToken });
+const { complete, createPayment } = useCartManagerContext();
+
+// 1. Finalize the cart into an Order. On success the cart-id cookie is cleared
+//    and status resets to idle — a follow-up addItem creates a fresh cart.
+const { order } = await complete();
+
+// 2. Decide the payment flow from the Order itself — no hardcoded brand checks.
+if (order.canCreatePayment) {
+  const session = await createPayment({
+    orderId: order.id,
+    returnUrl: `${origin}/checkout/return`, // optional — must point to a verified shop domain
+  });
+  // Branch on session.flow: redirectUrl (redirect), clientSecret (embedded
+  // widget), status (instant settlement). Failures throw with
+  // `err.userErrors[0].code` of the PAYMENT_* family.
+}
 ```
 
-## Core API
+`getBrowserDataForPayment()` (from `/react`) is a standalone helper collecting
+the browser context fields used by strong-customer-authentication flows
+(user agent, screen, timezone, language); it throws
+`BrowserDataNotAvailableError` outside the browser — call it in an event
+handler, never during SSR.
 
-### createStorefrontClient
+The completed `order` also carries `order.accessToken` — an opaque token for
+guest order lookup via `cartClient.getOrderByToken(token, email?)`.
+
+### Discovery queries (CartClient)
 
 ```typescript
-const client = createStorefrontClient({
-  apiUrl: string,
-  shopSlug: string,
-  middleware?: Middleware[],
-  defaultHeaders?: Record<string, string>,
-  fetch?: typeof globalThis.fetch, // custom fetch (polyfill, test mocks)
-  debug?: boolean,                 // log requests in dev
-});
+const cartClient = new CartClient(client);
 
-client.query<T, V>(document, variables?, cache?): Promise<T>
-client.mutate<T, V>(document, variables?): Promise<T>
-client.use(middleware): void // imperative middleware add
-```
+// Cart-aware shipping preview for an address. Returns null when the cart is gone.
+const payload = await cartClient.getAvailableShippingMethods(cartId, address);
+if (payload) {
+  if (payload.userErrors.length > 0) {
+    // Backend business condition with a translated message
+    // (e.g. a digital-only cart needs no shipping).
+    show(payload.userErrors[0].message);
+  } else {
+    render(payload.methods, payload.freeShippingProgress);
+    // each method carries deliveryType: HOME | PICKUP_POINT | LOCKER
+  }
+}
 
-Features: lazy pipeline compilation, same-tick request deduplication, TypedDocumentString support.
+// Shop-level payment methods + the default pre-selection signal.
+const { methods, defaultMethod } = await cartClient.getAvailablePaymentMethods();
 
-### Middleware Pipeline
+// Validate a discount code before applying it.
+const result = await cartClient.validateDiscountCode(cartId, 'SAVE10');
+if (!result.isValid) show(result.error?.message); // backend-translated
 
-Order matters: `auth → currency → [custom] → retry → timeout → errors (LAST)`
+// Guest order lookup by the opaque token from complete().
+const order = await cartClient.getOrderByToken(token, email);
+```
 
-```typescript
-import {
-  authMiddleware,      // Authorization: Bearer {token}
-  currencyMiddleware,  // X-Preferred-Currency header
-  retryMiddleware,     // Exponential backoff (queries only, not mutations)
-  timeoutMiddleware,   // AbortController, edge-safe (default 5s)
-  errorMiddleware,     // Normalizes all errors → StorefrontError (ALWAYS LAST)
-} from '@doswiftly/storefront-sdk';
+Error-handling contract across the SDK (messages are **always**
+backend-translated per `Accept-Language` — the SDK never synthesizes copy):
 
-// Custom middleware
-const logMiddleware: Middleware = async (req, next) => {
-  console.log('Request:', req.operationName);
-  const response = await next(req);
-  console.log('Response:', response.status);
-  return response;
-};
-```
+| Backend shape | SDK behaviour | You handle |
+|---|---|---|
+| Mutation with `userErrors[]` | Throws `StorefrontError`; `err.userErrors[0].message` is translated | `try/catch`, branch on `err.userErrors[0].code` |
+| Nullable query root | Returns `T \| null` | `if (!result) …` |
+| Structured payload (errors inside) | Returns the raw payload | Branch on `payload.userErrors[].code` / `payload.error.code` |
 
-### CartClient
+### Auth ↔ cart lifecycle
 
 ```typescript
-const cartClient = new CartClient(client);
-
-const cart = await cartClient.create();
-const updated = await cartClient.addItems(cartId, [{ variantId: 'v-123', quantity: 1 }]);
-await cartClient.updateItems(cartId, [{ id: 'line-1', quantity: 3 }]);
-await cartClient.removeItems(cartId, ['line-1']);
-await cartClient.updateDiscountCodes(cartId, ['SAVE10']);
-await cartClient.updateNote(cartId, 'Gift message');
-await cartClient.updateBuyerIdentity(cartId, { email: 'user@example.com' });
-const existing = await cartClient.get(cartId);
-```
+// After a successful sign-in: merge the guest cart into the customer context.
+// The secret is preserved — the same cookie keeps working.
+await cartClient.merge(guestCartId);
 
-Auto-throws `StorefrontError` with code `USER_ERROR` on validation failures.
+// On sign-out: strip customer PII from the cart (contact details, addresses,
+// saved-payment selection). `useLogout` calls this automatically.
+await cartClient.downgradeOnLogout(cartId);
 
-### Cart recovery (stale carts)
+// Cart recovery links (e.g. from an abandoned-cart email): redeem the token.
+// Rotates the secret — persist the new composite cookie value.
+const { cart, secret } = await cartClient.recoveryRedeem(token);
+```
 
-Carts can become unusable between reads and writes — they expire (TTL), lock after checkout (`ALREADY_COMPLETED`), or get cleaned up by a purge worker. Write mutations then reject with `userErrors[].code = 'CART_NOT_FOUND'` even though the previous `cart(id)` query succeeded.
+### Cart recovery without React
 
-The recovery utilities in core make this transparent for the caller. Every operation classifies itself: replay-safe operations (`addItems`, `updateBuyerIdentity`, `setShippingAddress`, discount codes, note) auto-recover via an atomic `cartCreate(input)`; state-dependent operations (`updateItems`, `removeItems`) bail with a `CartRecoveryNotPossibleError` and emit a `cart-expired` event so your UI can surface a single toast/banner instead of every call site handling the error.
+The same recovery semantics ship in core for Vue/Svelte/CLI/mobile consumers:
 
 ```typescript
 import {
@@ -425,117 +616,163 @@ import {
   type CartCookieStore,
 } from '@doswiftly/storefront-sdk';
 
-// Implement the cookie port for your runtime (or use createBrowserCartCookieStore from /react)
+// Implement the cookie port for your runtime
+// (browsers can use createBrowserCartCookieStore from /react).
 const cookieStore: CartCookieStore = {
-  get: () => readCartCookie(),
-  set: (cartId) => writeCartCookie(cartId),
+  get: () => readCartCookie(),                    // returns the cart id
+  set: (cartId, opts) => writeCartCookie(cartId, opts?.secret),
   clear: () => deleteCartCookie(),
 };
 
-const cartClient = new CartClient(client);
 const runner = createCartRecoveryRunner({ cartClient, cookieStore });
 
 runner.onExpired((event) => {
-  // Fired when the runner cannot transparently recover. UI prompts user to retry.
-  console.warn(`Cart expired (${event.reason}). Reset local state.`);
+  console.warn(`Cart expired (${event.reason}) — reset local state.`);
 });
 
-// Auto-replay: storefront caller never thinks about recovery
+// Auto-replay: the caller never thinks about stale carts.
 const { cart, warnings } = await runner.execute({
   name: 'addItems',
   run: (cartId) => cartClient.addItems(cartId, [{ variantId: 'v-123', quantity: 1 }]),
   recreateAndRun: recreateWithInput({ lines: [{ variantId: 'v-123', quantity: 1 }] }),
 });
 
-// Bail-on-stale: operation throws CartRecoveryNotPossibleError if cart is gone
-try {
-  await runner.execute({
-    name: 'updateItem',
-    run: (cartId) => cartClient.updateItems(cartId, [{ id: 'line-1', quantity: 2 }]),
-    // No recreateAndRun — replaying on an empty cart would silently lose the user's intent.
-  });
-} catch (err) {
-  if (err instanceof CartRecoveryNotPossibleError) {
-    // Already handled by the onExpired listener above.
-  } else {
-    throw err;
-  }
-}
+// Bail-on-stale: no recreateAndRun — throws CartRecoveryNotPossibleError instead.
 ```
 
-Detection inspects `err.userErrors[].code` (`CART_NOT_FOUND` / `ALREADY_COMPLETED`) — locale-independent.
+Detection inspects `err.userErrors[].code` (`CART_NOT_FOUND` /
+`ALREADY_COMPLETED`) — locale-independent. The runner also creates the cart on
+first use (deduped across concurrent calls) and persists the revealed secret
+through the cookie store.
 
-### React: `useCartManager` (DX-first hook)
+### `useCart(cartId)` — server-driven cart
 
-`useCartManager` is the React wrapper around the recovery runner — same per-operation taxonomy, just `useState`-driven loading/error and an `onExpired` subscription helper:
+Sister of `useCartManager` bound to an **explicit** `cartId` prop — never touches
+the cookie, no auto-recovery. For SSR-rendered checkout, deep-link order
+recovery, and admin "view this cart" UIs:
 
 ```tsx
 'use client';
-import { useEffect } from 'react';
-import { useCartManager } from '@doswiftly/storefront-sdk/react';
-import { toast } from 'sonner';
+import { useCart } from '@doswiftly/storefront-sdk/react';
+
+const {
+  cart, isLoading, error, operation,
+  refetch,
+  addItems, updateItems, removeItems,
+  updateBuyerIdentity, setShippingAddress,
+  updateDiscountCodes, updateNote, updateAttributes,
+} = useCart(cartId, {
+  autoFetch: false,   // skip the mount fetch when the server already rendered the cart
+  initialCart,        // SSR seed — combine with autoFetch: false
+});
+```
 
-export function CartButton() {
-  const { addItem, updateItem, onExpired, isLoading } = useCartManager();
+## Pre-built React components
 
-  useEffect(
-    () => onExpired((e) => toast.error(e.reason === 'state-dependent' ? 'Twój koszyk wygasł, dodaj produkty ponownie' : 'Nie udało się odzyskać koszyka')),
-    [onExpired],
-  );
+Headless, accessibility-aware, zero styling — pass `className` to integrate with
+your CSS approach. Available from `@doswiftly/storefront-sdk/react`:
 
-  return (
-    <button onClick={() => addItem([{ variantId: 'v-123', quantity: 1 }])} disabled={isLoading}>
-      Add to cart
-    </button>
-  );
-}
+| Component | Purpose |
+|-----------|---------|
+| `<Money amount currency>` | Locale-formatted price string from minor units |
+| `<Image data sizes priority>` | `<img>` with thumbhash blur placeholder + sane defaults |
+| `<CartCount count label>` | Aria-live cart item count |
+| `<AddToCartButton variantId quantity>` | Button wired to `useCartManager().addItem` (loading state + a11y error surfacing) |
+| `<PriceDisplay price compareAtPrice currency>` | Price + optional strikethrough sale price |
+| `<CartTotals subtotal tax shipping discount total currency>` | Cart financial breakdown `<dl>` |
+| `<PaymentInstrumentTile instrument>` | One selectable payment instrument (card brand, wallet, bank) |
+| `<PaymentInstrumentSection method>` | Instrument group for a payment method (renders tiles) |
+
+```tsx
+import { Money, PriceDisplay, CartCount } from '@doswiftly/storefront-sdk/react';
+
+<Money amount={9990} currency="PLN" />          {/* "99,90 zł" */}
+<PriceDisplay price={7990} compareAtPrice={9990} currency="PLN" />
+<CartCount count={3} label="items" />
 ```
 
-Methods returning `CartMutationOutcome` are: `addItem`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote` (auto-replay) and `updateItem`, `removeItem` (bail + `onExpired`). Use `clearCart` to reset locally without backend call.
+## Middleware pipeline
 
-### React: `<CartManagerProvider>` (shared instance)
+Default order (wired automatically by `StorefrontProvider`):
 
-`useCartManager` keeps per-mount state, so calling it in several components creates independent managers. To share one source of truth across a checkout — one loading state, one recovery queue, one `cart-expired` subscription — wrap the subtree in `<CartManagerProvider>` (inside `<StorefrontProvider>`) and read it with `useCartManagerContext()`. The provider also takes lifecycle callbacks so cross-cutting side-effects live in one place:
+```
+auth → cart-secret → currency → language → bot-protection → [custom] → retry → timeout → errors (ALWAYS LAST)
+```
 
-```tsx
-'use client';
-import { useRouter } from 'next/navigation';
-import { toast } from 'sonner';
-import { CartManagerProvider, useCartManagerContext } from '@doswiftly/storefront-sdk/react';
+When session refresh is active, a reactive-401 middleware wraps the whole
+pipeline: a 401 on a read query triggers one deduped `refreshSession()` and a
+replay; a 401 on a mutation fires the `session-expired` signal instead.
 
-function Checkout({ initialCartId }: { initialCartId: string | null }) {
-  const router = useRouter();
-  return (
-    <CartManagerProvider
-      initialCartId={initialCartId}
-      onMutationSuccess={() => router.refresh()}
-      onMutationError={(operation, error) => toast.error(error.message)}
-    >
-      <CheckoutForm />
-    </CartManagerProvider>
-  );
-}
+```typescript
+import {
+  authMiddleware,           // Authorization: Bearer <token> (lazy getter)
+  cartSecretMiddleware,     // x-cart-secret header (lazy getter)
+  currencyMiddleware,       // X-Preferred-Currency header
+  languageMiddleware,       // X-Language header (skipped when null — intentional)
+  botProtectionMiddleware,  // challenge token for protected mutations only
+  retryMiddleware,          // exponential backoff + jitter — queries only, never mutations
+  timeoutMiddleware,        // AbortController, edge-safe (default 5s)
+  errorMiddleware,          // normalizes all errors → StorefrontError (ALWAYS LAST)
+  sessionRetryMiddleware,   // reactive-401 refresh + replay (queries only)
+} from '@doswiftly/storefront-sdk';
 
-function CheckoutForm() {
-  const { addItem, complete, status } = useCartManagerContext();
-  // ...
-}
+// Custom middleware
+const logMiddleware: Middleware = async (request, next) => {
+  console.log('Request:', request.operationName);
+  const response = await next(request);
+  return response;
+};
 ```
 
-For deliberately independent managers (multi-cart B2B, an admin "view this cart" panel) call `useCartManager()` directly instead.
+Middleware that reads mutable state takes a **lazy getter**
+(`authMiddleware(() => store.getState().accessToken)`) so rotated values are
+picked up without rebuilding the client.
 
-### AuthClient
+## Core API
+
+### createStorefrontClient
 
 ```typescript
-const authClient = new AuthClient(client);
+const client = createStorefrontClient({
+  apiUrl: string,
+  shopSlug: string,
+  middleware?: Middleware[],
+  defaultHeaders?: Record<string, string>,
+  fetch?: typeof globalThis.fetch,        // custom fetch (polyfill, test mocks)
+  debug?: boolean | 'verbose' | DebugOptions,
+});
+
+client.query<T, V>(document, variables?, cache?): Promise<T>
+client.mutate<T, V>(document, variables?): Promise<T>
+client.use(middleware): void // imperative middleware add
+```
+
+Features: lazy pipeline compilation, same-tick request deduplication (queries
+only), `TypedDocumentString` support from graphql-codegen.
 
-const { accessToken, expiresAt } = await authClient.login('user@example.com', 'pass');
-await authClient.logout();
-const renewed = await authClient.refreshToken();
-const { accessToken: regToken, customer } = await authClient.register({ email, password, firstName });
-const me = await authClient.getCustomer();
+### Debug logging
+
+```typescript
+createStorefrontClient({ apiUrl, shopSlug, debug: 'verbose' });
 ```
 
+- `debug: true` — minimal: operation name + variables on request, status +
+  userErrors on response.
+- `debug: 'verbose'` — everything: full query, variables, headers, response
+  body, timing, userErrors.
+- `debug: { request?, response?, headers?, timing?, userErrors?, log? }` —
+  granular per-dimension opt-in, plus a custom sink
+  (`log: (event: DebugEvent) => void`) for routing into your logger.
+- Env fallback: `DOSWIFTLY_SDK_DEBUG=verbose|true|minimal` when the option is
+  omitted — disabled in `NODE_ENV=production` (PII safety).
+- `Authorization: Bearer …` and auth-cookie values are **unconditionally
+  redacted** to `***<last4>` whenever headers are logged.
+
+`createRemoteDebugTransport` builds a shared remote sink — pass it as
+`debug: { remote: transport }` on the client and as `cookieDebug` on the
+providers so GraphQL operations and cookie writes land on one timeline with a
+single session id.
+
 ### StorefrontError
 
 ```typescript
@@ -545,10 +782,10 @@ try {
   await client.query(ProductQuery, { handle: 'missing' });
 } catch (err) {
   if (err instanceof StorefrontError) {
-    err.code;           // 'GRAPHQL_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'USER_ERROR' | ...
+    err.code;           // 'GRAPHQL_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'USER_ERROR' | 'SESSION_EXPIRED' | ...
     err.status;         // HTTP status (0 for network errors)
     err.graphqlErrors;  // GraphQL-level errors
-    err.userErrors;     // Field-level validation errors
+    err.userErrors;     // field-level validation errors (backend-translated messages)
     err.hasUserErrors;  // boolean
     err.isNetworkError; // boolean
     err.isTimeout;      // boolean
@@ -556,274 +793,284 @@ try {
 }
 ```
 
-### Format Utilities
+`assertNoUserErrors(payload)` — the helper the clients use internally — is also
+exported for custom operations: it throws a `StorefrontError` carrying the first
+backend-translated `userErrors[].message`.
+
+### Schema enums — runtime constants
+
+Every schema enum is exported as a **runtime const + type alias pair**, so both
+`import type { DeliveryType }` and `Object.values(DeliveryType)` work:
+
+```typescript
+import { DeliveryType, PaymentMethodType, CountryCode } from '@doswiftly/storefront-sdk';
+
+const schema = z.enum(Object.values(PaymentMethodType)); // runtime validation
+type T = DeliveryType;                                   // 'HOME' | 'PICKUP_POINT' | 'LOCKER'
+```
+
+Available: `DeliveryType`, `PaymentMethodType`, `PaymentInitiationFlow`,
+`CurrencyCode`, `CountryCode`, `LanguageCode`, `ProductTypeEnum`, `WeightUnit`,
+`CartWarningCode`, `AttributeType`, `AttributeFillingMode`,
+`AttributeBillingMode`, `AttributeOptionSurchargeType`, `StorefrontOrderStatus`,
+`OrderPaymentStatus`, `OrderFulfillmentStatus`, `DiscountErrorCode`,
+`DiscountApplicationType`, `PaymentProvider`, `PaymentInstrumentType`,
+`PaymentInstrumentDisplayHint`, `PaymentMethodUnavailableReason`.
+
+### Format utilities
 
 ```typescript
 import {
-  formatPrice,
-  formatPriceRange,
-  formatAmount,
-  formatDate,
-  formatDateTime,
-  formatNumber,
-  formatPercentage,
+  formatPrice, formatPriceRange, formatAmount,
+  formatDate, formatDateTime, formatNumber, formatPercentage,
   getCurrencySymbol,
-  CURRENCY_SYMBOLS,
-  CURRENCY_LOCALES,
 } from '@doswiftly/storefront-sdk';
 
 formatPrice({ amount: '99.99', currencyCode: 'USD' }); // "$99.99"
-formatPriceRange(minPrice, maxPrice);                   // "$10.00 - $50.00"
 formatAmount('115.20', 'EUR');                          // "115,20 €"
-formatDate(new Date());                                // "Dec 9, 2025"
-formatPercentage(0.15);                                // "15%"
+formatPercentage(0.15);                                 // "15%"
 ```
 
-### Image Types
-
-GraphQL API returns ready-to-use CDN URLs via `url(transform: { maxWidth: 800 })`. No client-side loader needed.
+Locale-bound versions that follow the active storefront language are available
+as React hooks — see [Format hooks](#format-hooks).
 
-`ImageData` type matches GraphQL `Image` fragment: `{ url, altText?, width?, height?, id? }`.
-
-### HTML Sanitizer
+### HTML sanitizer + connection normalizer
 
 ```typescript
-import { sanitizeHtml } from '@doswiftly/storefront-sdk';
+import { sanitizeHtml, normalizeConnection } from '@doswiftly/storefront-sdk';
 
-// Defense-in-depth: strips <script>, event handlers, javascript: URLs
-const safe = sanitizeHtml(userHtml);
-```
+const safe = sanitizeHtml(userHtml); // strips <script>, event handlers, javascript: URLs
 
-### Connection Normalizer
+const { items, pageInfo, totalCount } = normalizeConnection(data.products); // Relay → flat array
+```
 
-```typescript
-import { normalizeConnection } from '@doswiftly/storefront-sdk';
+### Cookie contracts (platform constants)
 
-// Relay connection → flat array
-const { items, pageInfo, totalCount } = normalizeConnection(data.products);
-```
+All first-party cookie names/defaults the platform relies on are exported —
+never hardcode the strings:
 
-### Auth Cookie Config (Platform Contract)
+| Constant | Cookie | Notes |
+|---|---|---|
+| `AUTH_COOKIE_NAME` / `AUTH_COOKIE_DEFAULTS` | `customerAccessToken` | httpOnly access token |
+| `REFRESH_COOKIE_NAME` / `REFRESH_COOKIE_DEFAULTS` | `customerRefreshToken` | httpOnly, path-scoped to the auth route |
+| `SESSION_EXPIRY_COOKIE_NAME` / `SESSION_EXPIRY_COOKIE_DEFAULTS` | `session-expiry` | readable expiry hint for the scheduler |
+| `CART_COOKIE_NAME` / `CART_COOKIE_MAX_AGE` | `cart-id` | composite `"<cartId>.<secret>"`, 30 days |
+| `CURRENCY_COOKIE_NAME` / `CURRENCY_COOKIE_MAX_AGE` / `CURRENCY_HEADER_NAME` | `preferred-currency` | |
+| `LANGUAGE_COOKIE_NAME` / `LANGUAGE_COOKIE_MAX_AGE` / `LANGUAGE_HEADER_NAME` | `preferred-language` | |
 
 ```typescript
-import { AUTH_COOKIE_NAME, AUTH_COOKIE_DEFAULTS } from '@doswiftly/storefront-sdk';
+import { parseCartCookieValue, formatCartCookieValue } from '@doswiftly/storefront-sdk';
 
-// AUTH_COOKIE_NAME = 'customerAccessToken'
-// AUTH_COOKIE_DEFAULTS = { name, path, sameSite, httpOnly, secure, maxAge }
+parseCartCookieValue('abc.s3cret'); // { cartId: 'abc', cartSecret: 's3cret' }
+parseCartCookieValue('abc');        // { cartId: 'abc', cartSecret: null } (legacy)
+formatCartCookieValue({ cartId: 'abc', cartSecret: 's3cret' }); // 'abc.s3cret'
 ```
 
-### Auth Cookie Handlers (API Route Factories)
+### Route matching
 
 ```typescript
-import { createSetTokenHandler, createClearTokenHandler } from '@doswiftly/storefront-sdk';
-
-// Next.js API route (2 lines):
-// app/api/auth/set-token/route.ts
-export const POST = createSetTokenHandler();
+import { matchesRoute } from '@doswiftly/storefront-sdk';
 
-// app/api/auth/clear-token/route.ts
-export const POST = createClearTokenHandler();
+matchesRoute('/account/orders', ['/account']); // true (exact + prefix matching)
 ```
 
-Uses pure Web API (Request/Response) — 0 deps, framework-agnostic.
-Security: origin validation, Content-Type check, CSRF via SameSite=Lax, httpOnly cookie.
+## React adapter
 
-### Auth Token Client (Client-side)
+### `<StorefrontProvider>` props
 
-```typescript
-import { createAuthTokenClient } from '@doswiftly/storefront-sdk';
+| Prop | Type | Purpose |
+|---|---|---|
+| `config` | `{ apiUrl, shopSlug, … }` | Client config (full `StorefrontClientConfig`, incl. `debug`) |
+| `shopData` | `ShopConfig` | `currencyCode`, `supportedCurrencies`, `localeToCurrencyMap?`, `defaultLanguage?`, `supportedLanguages?`, `botProtection?` |
+| `middleware` | `Middleware[]` | Extra middleware, inserted after the built-in header middleware |
+| `initialIsAuthenticated` | `boolean` | Server-side auth hint — no "Sign in" flash. Defaults to `!!initialAccessToken` |
+| `initialAccessToken` | `string \| null` | Server-side raw JWT seed (kept in memory, never persisted) |
+| `initialExpiresAt` | `string \| null` | Session expiry seed (ISO 8601) — arms the refresh scheduler on cold start |
+| `initialLanguage` | `string` | Server-side locale hint — no language flash |
+| `autoRefresh` | `boolean` | Proactive session refresh — default ON in the browser |
+| `authBasePath` | `string` | Where the BFF auth route is mounted (default `/api/auth`) |
+| `cookieDebug` | `(event: DebugEvent) => void` | Debug sink for currency/language cookie writes |
 
-const { setToken, clearToken } = createAuthTokenClient();
-await setToken(accessToken);  // POST /api/auth/set-token
-await clearToken();           // POST /api/auth/clear-token
-```
-
-### Route Matching
+The provider creates all store instances per mount (no module-level singletons —
+safe under bundler module duplication), wires the default middleware pipeline,
+mounts the bot-protection widget when the shop has it configured, and runs the
+session-refresh scheduler.
 
-```typescript
-import { matchesRoute } from '@doswiftly/storefront-sdk';
+`StorefrontClientProvider`, `CurrencyProvider`, `LanguageProvider` are exported
+separately for custom composition.
 
-// Supports exact and prefix matching
-matchesRoute('/account/orders', ['/account']); // true
-matchesRoute('/products', ['/account']);        // false
-```
+### Stores (Context-based)
 
-### Cache Strategies
+All store hooks require the `StorefrontProvider` wrapper and accept an optional
+selector:
 
 ```typescript
-import { cacheLong, cacheShort, cacheNone, cachePrivate, cacheCustom } from '@doswiftly/storefront-sdk/cache';
-
-cacheLong()                              // 1h + 23h stale-while-revalidate
-cacheLong({ tags: ['product', slug] })   // with Next.js revalidation tags
-cacheShort()                             // 1s + 9s swr
-cacheNone()                              // no-store
-cachePrivate()                           // private, 1s + 9s swr
-cacheCustom({ maxAge: 300, swr: 600 })   // 5min + 10min swr
-```
+import {
+  useAuthStore, useAuthStoreApi, useAuthHydrated,
+  useCurrencyStore, useCurrencyStoreApi,
+  useLanguageStore, useLanguageStoreApi,
+} from '@doswiftly/storefront-sdk/react';
+
+// Auth
+const { isAuthenticated, customer, accessToken, expiresAt, setAuth, clearAuth } = useAuthStore();
+const isAuthenticated = useAuthStore((s) => s.isAuthenticated); // with selector
+const authHydrated = useAuthHydrated(); // true after localStorage rehydration
 
-## React Adapter
+// Currency
+const { currency, baseCurrency, supportedCurrencies, setCurrency, isLoaded } = useCurrencyStore();
 
-### Providers
+// Language
+const { language, setLanguage } = useLanguageStore();
 
-```tsx
-// Convenience (recommended)
-<StorefrontProvider config={{ apiUrl, shopSlug }} shopData={shop}>
-  {children}
-</StorefrontProvider>
+// `*StoreApi` variants return the raw store for .getState() in callbacks
+const token = useAuthStoreApi().getState().accessToken;
 ```
 
-`StorefrontProvider` creates Zustand store instances via `useRef` and provides them through React Context. This eliminates module-level singleton issues with Turbopack/bundler module duplication.
+Pre-built selectors: `selectCurrency`, `selectBaseCurrency`,
+`selectSupportedCurrencies`, `selectIsLoaded`, `selectLanguage`,
+`selectDefaultLanguage`, `selectSupportedLanguages`, `selectLanguageIsLoaded`.
 
-### useAuth
+**Security note:** the access token is **never** persisted to
+`localStorage`/`sessionStorage` — it lives in memory (and in the httpOnly
+cookie). Persisted auth state covers only `customer` + `isAuthenticated`.
 
-```typescript
-const {
-  login,         // (email, password) => Promise<LoginResult>
-  logout,        // () => Promise<LogoutResult>
-  refreshToken,  // () => Promise<TokenRefreshResult>
-  isLoggingIn, isLoggingOut, isRefreshingToken, isLoading,
-  error,
-} = useAuth({
-  onSetToken: async (token) => { /* set httpOnly cookie via server route */ },
-  onClearToken: async () => { /* clear httpOnly cookie */ },
-});
-```
+`useCurrency()` is a convenience aggregator over the currency store.
+
+### Format hooks
 
-### Cart Store (DI-based) — recommended for templates
+Locale-aware formatters bound to the active storefront language:
 
 ```typescript
-import { createCartStore, CartProvider, useCartStore, type CartActions } from '@doswiftly/storefront-sdk/react';
+import {
+  useFormatPrice, useFormatAmount, useFormatPriceRange,
+  useFormatDate, useFormatDateTime, useFormatNumber, useGetCurrencySymbol,
+} from '@doswiftly/storefront-sdk/react';
 
-// Template provides CartActions implementation (transport layer)
-const store = createCartStore({
-  getActions: () => cartActions,     // getter — called per operation (fresh refs)
-  onMutationSuccess: (action, cart) => { /* toast, cache invalidation */ },
-  onMutationError: (action, error) => { /* error toast */ },
-});
+const formatPrice = useFormatPrice();
+formatPrice({ amount: '99.99', currencyCode: 'PLN' }); // honors the active locale
+```
 
-// Provider (separate from StorefrontProvider — template composes in StoresProvider)
-<CartProvider store={store}>{children}</CartProvider>
+### Generic hooks
 
-// Hooks (Context-based, selector overloads)
-const { cartId, isOpen, isLoading, addToCart, clearCart, openCart } = useCartStore();
-const cartId = useCartStore(s => s.cartId); // with selector
+```typescript
+import { useHydrated, useDebouncedValue, useStorefrontClient } from '@doswiftly/storefront-sdk/react';
 
-// Selectors
-import { selectCartId, selectIsCartOpen, selectCartIsLoading } from '@doswiftly/storefront-sdk/react';
+const isHydrated = useHydrated();        // false during SSR + first client render
+const debounced = useDebouncedValue(query, 300);
+const client = useStorefrontClient();    // the StorefrontClient from context
 ```
 
-SDK orchestrates: auto-init (fetch or create), expired cart recovery, loading/error state, mutation callbacks.
-Template provides: CartActions DI implementation (GraphQL hooks, React Query, fetch — any transport).
+### `createStoreContext`
 
-### useCartManager (alternative — cookie-based, simple)
+Build your own Context-based Zustand stores (the same pattern the SDK uses —
+no module-level singletons):
 
 ```typescript
-const {
-  getCart,       // () => Promise<Cart | null>
-  addItem,       // (lines: CartLineInput[]) => Promise<Cart>
-  updateItem,    // (lines: CartLineUpdateInput[]) => Promise<Cart>
-  removeItem,    // (lineIds: string[]) => Promise<Cart>
-  updateDiscountCodes, updateNote, clearCart, getCartId,
-  isLoading, error,
-} = useCartManager();
+import { createStoreContext } from '@doswiftly/storefront-sdk/react';
+
+const { Provider: WishlistProvider, useStore: useWishlistStore, useApi: useWishlistStoreApi } =
+  createStoreContext<WishlistState>('WishlistStore');
 ```
 
-Cart ID is persisted in a cookie (SSR/edge visible). Plain async + useState, no React Query dependency.
+### Bot protection
 
-### useHydrated
+When the shop has bot protection configured (`shopData.botProtection`), the
+provider loads the challenge widget and `botProtectionMiddleware` attaches
+tokens to protected mutations automatically. `useBotProtection()` exposes
+`execute()` for manual token acquisition; `createBotProtectionManager` /
+`FallbackBotProtectionManager` are exported from core for custom wiring.
+Fail-open by default — a challenge outage never blocks checkout.
 
-```typescript
-import { useHydrated } from '@doswiftly/storefront-sdk/react';
+## Server-side (`/react/server`)
 
-const isHydrated = useHydrated();
-// false during SSR and first client render, true after hydration
-// Use to guard browser-only state (localStorage, cookies, window)
+```typescript
+import {
+  getStorefrontClient,          // server client factory (10s timeout, retry, errors)
+  createStorefrontAuthRoute,    // SDK-BFF auth route — see Authentication
+  getInitialAuth,               // cold-start auth seed from first-party cookies (Next.js)
+  readCartIdCookie,             // cart id (string | null)
+  readCartCredentials,          // { cartId, cartSecret } | null — composite cookie
+  readCurrencyCookie,           // preferred currency (string | null)
+  serverCartSecretMiddleware,   // attach x-cart-secret on SSR/edge cart reads
+  trustedForwardedHostValidator,
+  originAllowlistValidator,
+} from '@doswiftly/storefront-sdk/react/server';
 ```
 
-### useDebouncedValue
+SSR cart read with the capability secret:
 
 ```typescript
-import { useDebouncedValue } from '@doswiftly/storefront-sdk/react';
+// Server Component / Route Handler
+const credentials = await readCartCredentials();
 
-const debouncedQuery = useDebouncedValue(query, 300);
+const client = getStorefrontClient({
+  apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+  shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+  middleware: [serverCartSecretMiddleware(credentials)],
+});
+
+const cart = credentials ? await new CartClient(client).get(credentials.cartId) : null;
 ```
 
-### createStoreContext
+The server factory ships **without** auth/currency middleware (there are no
+stores on the server) — add request-scoped headers via custom middleware. For
+authenticated SSR reads, forward the access token from the httpOnly cookie:
 
 ```typescript
-import { createStoreContext } from '@doswiftly/storefront-sdk/react';
-import { createStore } from 'zustand/vanilla';
-
-// Define store factory + Context-based hooks (eliminates module-level singletons)
-const { Provider: CartProvider, useStore: useCartStore, useApi: useCartStoreApi } =
-  createStoreContext<CartState>('CartStore');
-
-// In layout:
-const cartStore = useRef(createCartStore()).current;
-<CartProvider store={cartStore}>{children}</CartProvider>
-
-// In components:
-const isOpen = useCartStore((s) => s.isOpen);
-const api = useCartStoreApi(); // for .getState() in callbacks
+middleware: [
+  async (request, next) => {
+    const token = (await cookies()).get(AUTH_COOKIE_NAME)?.value;
+    if (token) request.headers['Authorization'] = `Bearer ${token}`;
+    return next(request);
+  },
+],
 ```
 
-### Zustand Stores (Context-based)
-
-Stores use `createStore()` from `zustand/vanilla` + React Context pattern. All store hooks require `StorefrontProvider` wrapper.
+## Caching
 
 ```typescript
-import { useAuthStore, useAuthHydrated, useCurrencyStore } from '@doswiftly/storefront-sdk/react';
-
-// Auth — state
-const { isAuthenticated, customer, accessToken } = useAuthStore();
-// Auth — with selector
-const isAuthenticated = useAuthStore(s => s.isAuthenticated);
-// Auth — persist hydration (replaces old isHydrated store field)
-const authHydrated = useAuthHydrated(); // true after localStorage rehydration
+import { cacheLong, cacheShort, cacheNone, cachePrivate, cacheCustom } from '@doswiftly/storefront-sdk/cache';
 
-// Currency
-const { currency, baseCurrency, supportedCurrencies, setCurrency, isLoaded } = useCurrencyStore();
+cacheLong()                              // 1h + 23h stale-while-revalidate
+cacheLong({ tags: ['product', slug] })   // with Next.js revalidation tags
+cacheShort()                             // 1s + 9s swr
+cacheNone()                              // no-store
+cachePrivate()                           // private, 1s + 9s swr
+cacheCustom({ maxAge: 300, swr: 600 })   // 5min + 10min swr
 
-// For .getState() in callbacks (e.g. logout, refreshToken)
-import { useAuthStoreApi, useCurrencyStoreApi } from '@doswiftly/storefront-sdk/react';
-const authStore = useAuthStoreApi();
-const token = authStore.getState().accessToken;
+const data = await client.query(ProductQuery, { handle }, cacheLong());
 ```
 
-### Server-side
+## GraphQL schema for codegen
 
-```typescript
-import { getStorefrontClient } from '@doswiftly/storefront-sdk/react/server';
+The GraphQL SDL ships in the linked `@doswiftly/storefront-operations` package
+(installed alongside the SDK) — point your codegen / IDE plugin at it directly.
+No live backend required:
 
-// Server Component or Route Handler
-const client = getStorefrontClient({
-  apiUrl: process.env.API_URL!,
-  shopSlug: process.env.SHOP_SLUG!,
-});
+```ts
+// codegen.ts — uses the raw .graphql file from the operations package
+const config = {
+  schema: 'node_modules/@doswiftly/storefront-operations/schema.graphql',
+  documents: ['./app/**/*.{ts,tsx,graphql}'],
+  generates: { './generated/graphql.ts': { /* … */ } },
+};
+export default config;
 ```
 
-## Template Integration
+For the VS Code GraphQL extension, point `graphql-config` at the same path.
+`client.query`/`client.mutate` accept the generated `TypedDocumentString`
+documents directly.
 
-Storefronts (Next.js templates) import SDK for **infrastructure** and own their **data-fetching layer**:
+## Deprecated
 
-```
-SDK provides:                    Template owns:
-├── Transport + Middleware       ├── codegen.ts + generated/graphql.ts
-├── CartClient + AuthClient      ├── lib/graphql/hooks.ts (React Query)
-├── Cart Store (DI-based)        ├── lib/graphql/server.ts (React cache)
-├── Providers + Zustand stores   ├── lib/graphql/fragments/
-├── Format utilities             ├── hooks/use-cart-di.ts (CartActions DI impl)
-├── sanitizeHtml                 ├── hooks/use-cart-actions.ts (UX wrapper)
-├── ImageData type               ├── components/product/product-image.tsx
-├── normalizeConnection          ├── stores/ (checkout, wishlist via createStoreContext)
-├── Auth handlers + token client ├── lib/auth/routes.ts (route config)
-├── useHydrated + useDebouncedValue
-├── createStoreContext           └── components/providers/
-├── AUTH_COOKIE_NAME + matchesRoute
-└── Cache strategies
-```
+| Symbol | Replacement |
+|---|---|
+| `createCartStore`, `CartProvider`, `useCartStore`, `useCartStoreApi` | `useCartManager` / `<CartManagerProvider>` — the legacy store predates capability carts and does not carry the cart secret |
+| `AuthClient.refreshToken()`, `useRefreshToken` | Automatic refresh (`autoRefresh`) / `AuthClient.refreshSession()` — the GraphQL refresh requires a still-valid access token |
+| `ShopCurrencyData` | `ShopConfig` |
 
-Data-fetching hooks are generated locally via `@graphql-codegen/client-preset` (TypedDocumentString).
+Deprecated symbols remain exported for backward compatibility and will be
+removed in a future major release.
 
 ## License