@doswiftly/storefront-sdk 17.0.0 → 18.1.0

package/CHANGELOG.md

@@ -1,5 +1,981 @@
 # Changelog
 
+## 18.1.0
+
+### Minor Changes
+
+- ff03fd3: Add `<CartManagerProvider>` + `useCartManagerContext()` so a single cart manager can be shared across a checkout tree, plus optional lifecycle callbacks on `useCartManager` and the provider.
+
+  **Why** — `useCartManager` keeps per-mount state (loading status, recovery coordinator, cart-expired listeners). Calling it in several components creates independent managers, so a checkout that wants one loading indicator, one recovery queue, and one cart-expired subscription had to hand-roll a React Context wrapper. This ships that wrapper as a first-class, opt-in provider, matching the provider-first pattern already used by `<StorefrontProvider>`, `<CurrencyProvider>`, and `<CartProvider>`.
+
+  **Additive (backward-compatible)**:
+  1. `<CartManagerProvider>` creates one `useCartManager` instance and exposes it through Context; `useCartManagerContext()` reads it (throws when used outside the provider). The provider must be rendered inside `<StorefrontProvider>`.
+  2. New optional lifecycle callbacks, accepted both by `useCartManager(options)` and as `<CartManagerProvider>` props:
+     - `onMutationStart(operation)` — fired when a mutation starts.
+     - `onMutationSuccess(operation)` — fired after it resolves.
+     - `onMutationError(operation, error)` — fired with a buyer-surfaceable error (its message comes from the backend). Cart expiry and session loss are delivered through the dedicated `onExpired` / session-expired channels and do NOT trigger `onMutationError`, so `toast.error(error.message)` is safe to wire.
+
+     A transient missing-cart error that the manager transparently recovers from resolves as success. Callbacks are invoked defensively — a throwing callback never rejects the underlying mutation (it is logged via `console.warn`).
+
+  3. New exported types: `CartManagerProviderProps`, `CartManagerLifecycleCallbacks`, `UseCartManagerOptions`.
+
+  **Usage example**:
+
+  ```tsx
+  "use client";
+  import { useRouter } from "next/navigation";
+  import { toast } from "sonner";
+  import {
+    CartManagerProvider,
+    useCartManagerContext,
+  } from "@doswiftly/storefront-sdk/react";
+
+  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>
+    );
+  }
+
+  function CheckoutForm() {
+    // one shared manager for the whole form
+    const { addItem, complete, status } = useCartManagerContext();
+    // ...
+  }
+  ```
+
+  **Migration checklist** — none required; everything is opt-in.
+  - [ ] Optional: replace a hand-rolled `useCartManager` Context wrapper with `<CartManagerProvider>` + `useCartManagerContext()`.
+  - [ ] Optional: move per-call toast / refresh side-effects into `onMutationSuccess` / `onMutationError` on the provider.
+  - [ ] Keep calling `useCartManager()` directly where you want independent managers (e.g. multi-cart B2B, an admin "view this cart" panel).
+
+  **Standards reference** — provider-first sharing of a stateful instance with listeners and async initialisation is the established React-ecosystem pattern (`QueryClientProvider`, Stripe `<Elements>`), and mirrors the provider-first cart APIs of leading commerce SDKs.
+
+## 18.0.0
+
+### Major Changes
+
+- 1d51cc7: Schema MAJOR: nine String/`[String]` image URL fields replaced with `Image`/`[Image!]!`. Every storefront-facing image field now supports `Image.url(transform: ...)` and multi-tenant CDN signing on shop-owned media. Migration touches return, brand, shipping carrier, loyalty benefit, product review, attribute swatch, and payment surfaces.
+
+  **Why**: This is the final batch of the image-transform pipeline sweep. Previously these nine fields returned a raw string (or list of strings), so storefronts could not request specific sizes, formats, or crops. After this change, every image-bearing field on the storefront API exposes the same `Image` shape as `Product` and `ProductVariant` — pass an `ImageTransformInput` to the `url` argument to get a responsive variant, and rely on imgproxy signing where the merchant uploaded media to our CDN.
+
+  **Schema diff (9 fields)**:
+
+  | Type                      | Before                  | After               |
+  | ------------------------- | ----------------------- | ------------------- |
+  | `ReturnLineItem`          | `imageUrl: String`      | `image: Image`      |
+  | `Brand`                   | `logo: String`          | `logo: Image`       |
+  | `BrandFilterValue`        | `logo: String`          | `logo: Image`       |
+  | `ShippingCarrier`         | `logoUrl: String`       | `logo: Image`       |
+  | `TierBenefit`             | `icon: String`          | `icon: Image`       |
+  | `ProductReview`           | `images: [String]`      | `images: [Image!]!` |
+  | `AttributeSwatch`         | `imageUrl: String`      | `image: Image`      |
+  | `PaymentMethod`           | `icon: String`          | `icon: Image`       |
+  | `PaymentMethodInstrument` | `brandImageUrl: String` | `brandImage: Image` |
+
+  **Migration — pick a thumbnail fragment and replace selections**:
+
+  The storefront-operations package ships an `ImageThumbnail` fragment (`{ id, url(transform: { maxWidth: 300 }), altText, width, height, thumbhash }`) plus `ImageCard` (maxWidth 800) and `ImageFull` (maxWidth 1600). Pick the size that matches where you render the image.
+
+  ```diff
+  fragment ReturnItem on ReturnItem {
+     id
+     variantTitle
+  -  imageUrl
+  +  image {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment ShippingCarrier on ShippingCarrier {
+     id
+     name
+  -  logoUrl
+  +  logo {
+  +    ...ImageThumbnail
+  +  }
+     serviceCode
+  }
+
+  fragment AttributeSwatch on AttributeSwatch {
+     colorHex
+  -  imageUrl
+  +  image {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment ProductReview on ProductReview {
+     id
+     rating
+  -  images
+  +  images {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment LoyaltyTier on LoyaltyTier {
+     id
+     name
+     customBenefits {
+       name
+       description
+  -    icon
+  +    icon {
+  +      ...ImageThumbnail
+  +    }
+     }
+  }
+
+  fragment PaymentMethod on PaymentMethod {
+     id
+     name
+     type
+  -  icon
+  +  icon {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment PaymentMethodInstrument on PaymentMethodInstrument {
+     providerCode
+     instrumentCode
+     displayName
+  -  brandImageUrl
+  +  brandImage {
+  +    ...ImageThumbnail
+  +  }
+     enabled
+  }
+
+  # Brand (used inside MenuItem.resource union and as Product.brand)
+  {
+     brand {
+       id
+       handle
+       name
+  -    logo
+  +    logo {
+  +      ...ImageThumbnail
+  +    }
+     }
+  }
+
+  # BrandFilterValue (used inside AvailableFilters.brands)
+  {
+     brands {
+       id
+       handle
+       name
+  -    logo
+  +    logo {
+  +      ...ImageThumbnail
+  +    }
+       productCount
+     }
+  }
+  ```
+
+  **Field renames** (additional to type changes):
+  - `ShippingCarrier.logoUrl` → `ShippingCarrier.logo`
+  - `AttributeSwatch.imageUrl` → `AttributeSwatch.image`
+  - `ReturnLineItem.imageUrl` → `ReturnLineItem.image`
+  - `PaymentMethodInstrument.brandImageUrl` → `PaymentMethodInstrument.brandImage`
+
+  Rename + type change happen in the same release; you have to update both the field name and the selection set.
+
+  **Inline transform alternative**: if you do not want to use `ImageThumbnail`, you can request the URL with an explicit transform — the result is identical:
+
+  ```graphql
+  {
+    carrier {
+      logo {
+        url(transform: { maxWidth: 64, preferredContentType: WEBP })
+        altText
+      }
+    }
+  }
+  ```
+
+  **Migration checklist**:
+  - [ ] Update every fragment listed above so the selection set requests `url`/`altText`/etc. instead of treating the field as a scalar.
+  - [ ] Rename selections for the four fields that changed name (`logoUrl`/`imageUrl`/`brandImageUrl`).
+  - [ ] Re-run codegen so your generated TypedDocumentNode bindings reflect the new shape.
+  - [ ] If your UI rendered the old string URL directly, switch to consuming `field.url` (and optionally `field.altText`); pick the transform size that matches your component.
+  - [ ] `ProductReview.images` is now a non-null list of non-null `Image` values — drop any defensive null handling around individual elements but keep the empty-array case.
+
+  **No backend-input breakage**: `ReviewCreateInput.images` still takes `[String]` URLs from the customer at submission time. Only the response field changed shape.
+
+- e28e902: Payment schema naming overhaul — one coherent provider / method / instrument model.
+
+  **Why**: payment fields mixed three concepts under inconsistent names — a `ProviderCode` enum, a `PaymentMethodInstrument` object whose fields were `instrumentCode` / `providerCode`, and `*Code`-suffixed mutation inputs. Every payment field now follows a single convention: **provider** (who processes the payment — `PAYU`, `PRZELEWY24`), **method** (the category the buyer picks — `BLIK`, `CARD`), **instrument** (the concrete option within a method — a specific BLIK code or bank deep-link).
+
+  **Breaking**:
+  1. Enum `ProviderCode` → `PaymentProvider` (values unchanged: `PAYU`, `PRZELEWY24`, `STRIPE`, ...).
+  2. Object `PaymentMethodInstrument` → `PaymentInstrument`; field `instrumentCode` → `code`, field `providerCode` → `provider`.
+  3. Enums `PaymentMethodInstrumentType` → `PaymentInstrumentType`, `PaymentMethodInstrumentDisplayHint` → `PaymentInstrumentDisplayHint`.
+  4. `Cart.selectedPaymentInstrumentCode` → `Cart.selectedPaymentInstrument`.
+  5. `CartSelectPaymentMethodInput`: `preferredProviderCode` → `preferredProvider`, `preferredInstrumentCode` → `preferredInstrument`.
+  6. `CartSelectPaymentMethodInput.preferredProvider` is now the `PaymentProvider` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...) instead of a lowercase `String`. It matches the output — `PaymentInstrument.provider` and `PaymentMethod.preferredProvider` are already `PaymentProvider` — so you read the value off the API and pass it straight back, no case conversion. The schema now self-documents the selectable gateways. (`preferredInstrument` stays `String` — instrument codes are gateway-specific.)
+
+  **Usage example**:
+
+  ```graphql
+  # before
+  fragment Instrument on PaymentMethodInstrument {
+    providerCode
+    instrumentCode
+    displayName
+  }
+  mutation Select($input: CartSelectPaymentMethodInput!) {
+    cartSelectPaymentMethod(input: $input) {
+      cart {
+        selectedPaymentInstrumentCode
+      }
+    }
+  }
+  # $input: { cartId, methodType: BLIK, preferredProviderCode: "payu", preferredInstrumentCode: "blik" }
+
+  # after
+  fragment Instrument on PaymentInstrument {
+    provider
+    code
+    displayName
+  }
+  mutation Select($input: CartSelectPaymentMethodInput!) {
+    cartSelectPaymentMethod(input: $input) {
+      cart {
+        selectedPaymentInstrument
+      }
+    }
+  }
+  # $input: { cartId, methodType: BLIK, preferredProvider: PAYU, preferredInstrument: "blik" }
+  #   ^ preferredProvider is the PaymentProvider enum (UPPERCASE) — read it from
+  #     `instrument.provider` / `method.preferredProvider` and pass it back verbatim.
+  ```
+
+  ```ts
+  // SDK types — before
+  import type {
+    PaymentMethodInstrument,
+    ProviderCode,
+  } from "@doswiftly/storefront-sdk";
+  const code = instrument.instrumentCode;
+  const who = instrument.providerCode;
+
+  // after
+  import type {
+    PaymentInstrument,
+    PaymentProvider,
+  } from "@doswiftly/storefront-sdk";
+  const code = instrument.code;
+  const who = instrument.provider;
+  ```
+
+  The pre-built `<PaymentInstrumentSection>` / `<PaymentInstrumentTile>` component props (`selectedInstrumentCode`, `onSelectInstrument`) are unchanged — only the instrument data shape (`.code`) changed.
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Rename type references: `PaymentMethodInstrument` → `PaymentInstrument`, `ProviderCode` → `PaymentProvider`, `PaymentMethodInstrumentType`/`PaymentMethodInstrumentDisplayHint` → `PaymentInstrumentType`/`PaymentInstrumentDisplayHint`
+  - [ ] Field access: `instrument.instrumentCode` → `instrument.code`, `instrument.providerCode` → `instrument.provider`
+  - [ ] Cart selection: `cart.selectedPaymentInstrumentCode` → `cart.selectedPaymentInstrument`
+  - [ ] Mutation input: `preferredProviderCode` → `preferredProvider`, `preferredInstrumentCode` → `preferredInstrument`
+  - [ ] Mutation input value: pass the `PaymentProvider` enum (UPPERCASE) to `preferredProvider`, not a lowercase string — `preferredProvider: "payu"` → `preferredProvider: PAYU`. Drop any `.toLowerCase()` you applied to `instrument.provider` before sending it back.
+  - [ ] If you hand-write GraphQL operations: update fragments + re-run codegen against the published `schema.graphql`
+
+- 159184c: `ShipmentItem.imageUrl: String` replaced with `ShipmentItem.image: Image`.
+
+  **Why**: The previous `imageUrl` field returned a raw URL without transform support and was unreachable due to a resolver mapping bug (snapshot field names did not match what the storefront-facing mapper expected). The new `image: Image` field aligns shipment item images with `Product` and `ProductVariant` patterns — storefronts can request specific sizes, formats, and crops via `image { url(transform: { maxWidth: 200, preferredContentType: WEBP }) }`.
+
+  **Image source**: live variant image with snapshot fallback. The variant is loaded per-request via DataLoader (no N+1 cost when rendering many shipment items at once), and the resolved URL passes through the storefront's image transform pipeline so the requested dimensions/format are honored. When the variant has been deleted since the shipment was created, `image` returns `null` — render a placeholder client-side. The `title`, `variantTitle`, and `sku` fields stay as immutable snapshots from the time of fulfillment, so the tracking page still shows what was shipped even after a product is removed from the catalog.
+
+  **Migration**:
+
+  ```diff
+  fragment ShipmentItem on ShipmentItem {
+    id
+    title
+    variantTitle
+    sku
+    quantity
+  -  imageUrl
+  +  image {
+  +    ...ImageThumbnail
+  +  }
+  }
+  ```
+
+  Or, if you prefer to inline the transform without using the `ImageThumbnail` fragment:
+
+  ```diff
+  fragment ShipmentItem on ShipmentItem {
+    id
+    title
+    variantTitle
+    sku
+    quantity
+  -  imageUrl
+  +  image {
+  +    url(transform: { maxWidth: 200, preferredContentType: WEBP })
+  +    altText
+  +  }
+  }
+  ```
+
+  **Migration checklist**:
+  - [ ] Replace `imageUrl` selections in your `ShipmentItem` fragments / inline queries with `image { ...ImageThumbnail }` (or inline transform).
+  - [ ] Handle the `image: null` case in your ShipmentItem rendering (variant deleted after fulfillment — render a placeholder).
+  - [ ] Re-run codegen so your TypedDocumentNode bindings reflect the new shape.
+  - [ ] No SDK code changes are required beyond the regenerated operation types — the linked SDK bump exists to keep `@doswiftly/storefront-sdk` in version parity with `@doswiftly/storefront-operations`.
+
+- cc7edbe: SDK-BFF customer authentication — same-origin route handlers + automatic session refresh.
+
+  **Why**: Customer auth now runs entirely same-origin on your storefront domain through a backend-for-frontend layer. The browser never calls the commerce API for auth, and the refresh token never reaches JavaScript — it lives in a first-party httpOnly cookie read only server-side and exchanged server-to-server. This behaves identically on a platform subdomain, a custom domain, and off-platform hosting (e.g. Vercel), because the route handlers live on your own domain rather than depending on any edge layer.
+
+  **New**
+  - `createStorefrontAuthRoute({ apiUrl, shopSlug, isTrustedOrigin? })` (from `@doswiftly/storefront-sdk/react/server`) generates the `login` / `refresh` / `logout` / `whoami` route handlers. Mount once:
+
+    ```ts
+    // app/api/auth/[action]/route.ts
+    import {
+      createStorefrontAuthRoute,
+      trustedForwardedHostValidator,
+    } from "@doswiftly/storefront-sdk/react/server";
+
+    export const { GET, POST } = createStorefrontAuthRoute({
+      apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+      shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+      isTrustedOrigin: trustedForwardedHostValidator, // when running behind a reverse proxy
+    });
+    ```
+
+  - `getInitialAuth()` (server-only) reads the first-party cookies and returns `{ isAuthenticated, accessToken, expiresAt }` to seed the provider on the first render — no flash of signed-out UI, no extra round-trip:
+
+    ```tsx
+    // app/layout.tsx (Server Component)
+    const { isAuthenticated, accessToken, expiresAt } = await getInitialAuth();
+    return (
+      <StorefrontProvider
+        initialIsAuthenticated={isAuthenticated}
+        initialAccessToken={accessToken}
+        initialExpiresAt={expiresAt}
+        /* ...config, shopData */
+      >
+        {children}
+      </StorefrontProvider>
+    );
+    ```
+
+  - `AuthClient.refreshSession()` refreshes the session via the same-origin `POST /api/auth/refresh`, returning `{ accessToken, expiresAt }`. The proactive scheduler (`autoRefresh`, on by default in the browser) and the reactive 401 retry now use it — so an already-expired access token still refreshes silently.
+
+  **Breaking**
+  1. Automatic refresh (the proactive scheduler and the 401 retry) now goes through `POST /api/auth/refresh` instead of a GraphQL refresh. You **must** mount `createStorefrontAuthRoute` for refresh to work.
+  2. `useSessionRefresh` no longer accepts an `authBasePath` option — the base path comes from the provider-configured auth client.
+  3. The refresh cookie is scoped to the auth base path (so logout can revoke the session), and the readable session-expiry hint cookie is long-lived (so a returning visitor is not shown as signed-out on a cold start).
+
+  **Migration checklist**
+  - [ ] Add `app/api/auth/[action]/route.ts` exporting `createStorefrontAuthRoute(...)`.
+  - [ ] Seed the provider from `getInitialAuth()` in your root layout (Server Component).
+  - [ ] Remove any `authBasePath` argument passed to `useSessionRefresh`.
+  - [ ] Subscribe with `useSessionExpired(cb)` to react globally (notice + redirect to sign-in).
+  - [ ] Behind a reverse proxy that rewrites `Host`, pass `isTrustedOrigin: trustedForwardedHostValidator`.
+
+  **Standards reference**: RFC 6265 (cookie path-matching), RFC 9700 (OAuth 2.0 security best current practice — token endpoints are public; security is protocol-level, not network allowlists).
+
+  `@doswiftly/storefront-operations` is version-synced with this release (linked pair); it has no operation changes in this entry.
+
+### Minor Changes
+
+- 9969bdd: Keep customer sessions alive automatically — proactive refresh + session-expiry awareness.
+
+  **Why**: an active buyer should never be logged out mid-session. The SDK now renews the access token for you, ahead of expiry, and exposes a single global signal for when a session truly cannot be saved.
+
+  **Additive (backward-compatible)**:
+  1. **Automatic proactive refresh** — on by default in the browser (off on the server): `<StorefrontProvider>` renews the access token shortly before it expires, reschedules from each new expiry, and recovers on tab wake. Nothing to pass and nothing to copy into your app; opt out with `autoRefresh={false}`. This is the primary protection — in the happy path the token is renewed before it ever expires.
+  2. **Global session-expired signal** — `useSessionExpired((event) => { ... })` fires when the session cannot be renewed (a refresh failed on tab wake, or a reactive refresh after a 401 also failed). Use it to show a notice and redirect to sign-in. The new `ErrorCodes.SESSION_EXPIRED` names the condition.
+  3. **Reactive recovery on a 401** — if a read request comes back with HTTP 401, the SDK runs a single, deduped refresh and replays the request automatically; a state-changing request never auto-retries — it bails and emits the session-expired signal instead.
+  4. **Session expiry in state** — the auth store now tracks `expiresAt` (ISO 8601), populated from login, refresh and the current-customer query; the access token stays in memory only and `expiresAt` is never persisted. A new `sessionExpiresAt` field is available on the `Customer` type, and `<StorefrontProvider initialExpiresAt>` seeds it during server rendering for an instant cold-start schedule.
+
+  **Usage**:
+
+  ```tsx
+  // works out of the box — proactive refresh is on by default in the browser
+  // (nothing to pass; opt out with autoRefresh={false})
+  <StorefrontProvider config={config} shopData={shopData}>
+    {children}
+  </StorefrontProvider>;
+
+  // anywhere near the root — react globally when a session could not be saved
+  useSessionExpired(() => {
+    toast("Your session expired — please sign in again.");
+    router.push("/login");
+  });
+  ```
+
+  **Migration**: none — everything is additive. `autoRefresh` is opt-out (default-on in the browser) and existing manual refresh flows keep working. The proactive refresh syncs the renewed token through the same `/api/auth/set-token` route you already use for login — no extra wiring. Point it elsewhere with `authBasePath` if your auth routes are mounted on a different base path.
+
+  ```
+
+  ```
+
+- 5525fd4: `createStorefrontClient({ debug })` now accepts a tagged union — `boolean | 'verbose' | DebugOptions` — and a `'verbose'` mode dumps the full request and response with `Authorization` / `customerAccessToken` redacted. Mutation `userErrors[]` are surfaced on the response log by default.
+
+  **Why** — until now `debug: true` logged only `operationName + variables` on the request and `status + hasErrors` on the response. To see the actual GraphQL query, the response body, the populated `userErrors[]`, headers, or timing, you had to open DevTools → Network → filter by `graphql` → click the request → scroll Response. With dozens of requests per checkout session that workflow is painful. This release surfaces the same information inline in the console — opt-in, per-dimension, with sensitive credentials redacted unconditionally.
+
+  **Additive (backward-compatible)**:
+  1. `debug: true` continues to produce the exact same output as v17.1.0 — minimal request/response meta. Existing consumers see no change.
+  2. `debug: 'verbose'` enables every dimension:
+     - Full GraphQL query document on the request.
+     - Variables on the request (already logged in `true` mode).
+     - Request headers on the request, redacted (see below).
+     - Full response body (`data` + `errors` + `extensions`) on the response.
+     - Response headers on the response, redacted.
+     - Flattened `userErrors[]` from mutation payloads, on the response.
+     - `durationMs` (request start → response received) on the response.
+  3. `debug: DebugOptions` enables individual dimensions:
+
+     ```ts
+     interface DebugOptions {
+       request?: boolean; // full query string (default false)
+       response?: boolean; // full data + errors + extensions (default false)
+       headers?: boolean; // request + response headers (default false)
+       timing?: boolean; // durationMs (default false)
+       userErrors?: boolean; // flat userErrors[] from mutations (default true)
+       log?: (event: DebugEvent) => void; // custom sink (default console.log)
+     }
+     ```
+
+     `DebugEvent` is a stable contract:
+
+     ```ts
+     interface DebugEvent {
+       phase: "request" | "response";
+       operationName: string | undefined;
+       data: Record<string, unknown>;
+     }
+     ```
+
+  4. Environment variable opt-in: `DOSWIFTLY_SDK_DEBUG=verbose` (or `true` / `1` / `minimal`) activates the chosen preset when `debug` is omitted in code. The env var is **ignored** when `NODE_ENV=production` to prevent accidental customer-data logging from a misconfigured environment — explicit programmatic `debug` is still honoured (operator-driven traces).
+
+  **Deep nested payloads render in full** — the default logger emits the header line via `console.log` and the data payload via `console.dir(data, { depth: null, colors: false })`. Node's default `util.inspect` depth is 2, which truncates `data: { cart: { shippingAddress: [Object] } }` exactly when verbose mode is supposed to surface it. `console.dir(..., { depth: null })` is the cross-runtime escape hatch — Node honours the option, browser DevTools ignores it and renders an interactive drill-down. `colors: false` keeps log files and CI output grep-friendly. If you pipe through a custom `log` sink the default sink is bypassed entirely — your serializer (`pino`, `winston`, JSON.stringify) decides depth.
+
+  **Redaction** — unconditional whenever headers are logged, regardless of mode:
+  - `Authorization: Bearer <token>` → `Authorization: Bearer ***<last4>`
+  - `Cookie: customerAccessToken=<value>; …` → `Cookie: customerAccessToken=***<last4>; …`
+  - `Set-Cookie: customerAccessToken=<value>; …` → same masking on response headers.
+
+  **Usage example** — point a verbose log at a structured logger:
+
+  ```ts
+  import { createStorefrontClient } from "@doswiftly/storefront-sdk";
+  import pino from "pino";
+
+  const logger = pino({ name: "storefront" });
+
+  const client = createStorefrontClient({
+    apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+    shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+    debug: {
+      request: true,
+      response: true,
+      headers: true,
+      timing: true,
+      userErrors: true,
+      log: (event) =>
+        logger[event.phase === "request" ? "debug" : "info"]({
+          op: event.operationName,
+          ...event.data,
+        }),
+    },
+  });
+  ```
+
+  Or simply `debug: 'verbose'` to dump to `console.log` during development:
+
+  ```ts
+  const client = createStorefrontClient({ apiUrl, shopSlug, debug: "verbose" });
+  ```
+
+  Or set `DOSWIFTLY_SDK_DEBUG=verbose` in `.env.local` and leave `debug` out of code entirely.
+
+  **Migration checklist** — none required. `debug: true` and `debug: false` (and omitting `debug`) behave exactly as before. Opt into the new modes when you need them.
+
+  **Standards reference** — the per-dimension shape and `log` sink hook align with the conventions used by Stripe SDK (`{ logLevel, log }`) and Apollo Client's `loggerLink`. The credential redaction matches the OWASP cheat-sheet guidance for logging requests behind an auth boundary.
+
+- 5525fd4: Schema enums are now exported as runtime values **and** TypeScript types — usable with `z.enum(...)`, `Object.values(...)`, `Object.keys(...)`, and any other runtime validator.
+
+  **Why** — until now enums like `PaymentMethodType`, `ProductTypeEnum`, `CountryCode`, `CurrencyCode`, `DeliveryType`, `CartWarningCode`, `OrderPaymentStatus` (and 11 more) were emitted as type-only union literals: `type PaymentMethodType = 'CARD' | 'BLIK' | ...`. They compiled away to nothing, so you couldn't pipe them into `z.enum(...)`, iterate them in `Object.values(...)`, or expose them to a form validator without hand-maintaining a parallel list. Every SDK bump risked silent drift between the SDK's union and your local copy. This release fixes that.
+
+  **Additive (backward-compatible)**:
+
+  For every schema enum, the generated types now emit a pair under the same identifier:
+
+  ```ts
+  // runtime value
+  export const PaymentMethodType = {
+    BankTransfer: "BANK_TRANSFER",
+    Blik: "BLIK",
+    Card: "CARD",
+    CashOnDelivery: "CASH_ON_DELIVERY",
+    Other: "OTHER",
+  } as const;
+
+  // type alias (same shape as before — `'BANK_TRANSFER' | 'BLIK' | …`)
+  export type PaymentMethodType =
+    (typeof PaymentMethodType)[keyof typeof PaymentMethodType];
+  ```
+
+  - `import type { PaymentMethodType }` keeps working — TypeScript resolves the alias as before.
+  - `import { PaymentMethodType }` now also brings in the const object.
+  - `Object.values(PaymentMethodType)` returns the schema string values (`'BANK_TRANSFER'`, `'BLIK'`, …).
+
+  Enum values use `SCREAMING_SNAKE_CASE` (matching the GraphQL schema), keys use `PascalCase` (idiomatic for runtime accessors).
+
+  **Usage example** — Zod schema with runtime values:
+
+  ```ts
+  import { PaymentMethodType, DeliveryType } from "@doswiftly/storefront-sdk";
+  import { z } from "zod";
+
+  // Cast is needed because z.enum requires a non-empty tuple literal — the
+  // runtime values are a string-literal subtype of PaymentMethodType.
+  const checkoutSchema = z.object({
+    paymentMethod: z.enum(
+      Object.values(PaymentMethodType) as [
+        PaymentMethodType,
+        ...PaymentMethodType[],
+      ],
+    ),
+    deliveryType: z.enum(
+      Object.values(DeliveryType) as [DeliveryType, ...DeliveryType[]],
+    ),
+  });
+
+  // Or compare directly at runtime:
+  if (selected === PaymentMethodType.Blik) {
+    // …
+  }
+  ```
+
+  Enums included in this release: `PaymentMethodType`, `PaymentInitiationFlow`, `PaymentMethodInstrumentDisplayHint`, `PaymentMethodInstrumentType`, `PaymentMethodUnavailableReason`, `DeliveryType`, `ProductTypeEnum`, `CurrencyCode`, `CountryCode`, `LanguageCode`, `WeightUnit`, `CartWarningCode`, `AttributeType`, `AttributeFillingMode`, `AttributeBillingMode`, `AttributeOptionSurchargeType`, `StorefrontOrderStatus`, `OrderPaymentStatus`, `OrderFulfillmentStatus`, `DiscountApplicationType`, `DiscountErrorCode`, `ProviderCode`.
+
+  `PaymentErrorCode` stays type-only — it is a hand-curated `userErrors[].code` contract from `createPayment`, not a GraphQL enum.
+
+  **Migration checklist** — optional cleanup for existing storefronts:
+  - [ ] Delete any locally-duplicated arrays of enum values (e.g. `const PAYMENT_METHOD_TYPES = ['CARD', 'BLIK', ...] as const`) and replace with `Object.values(PaymentMethodType)`.
+  - [ ] Replace ad-hoc `z.string()` validators on enum fields with `z.enum(Object.values(X) as [X, ...X[]])`.
+  - [ ] If you imported with `import type { X }` you do not have to change anything — the type alias still resolves identically.
+
+  **Standards reference** — this is the same emit pattern produced by `@graphql-codegen/typescript`'s `enumsAsConst: true`. Bundle size impact is negligible (each enum is a plain object with string-literal values, tree-shakeable at the consumer); SDK runtime dependencies remain at zero.
+
+- 9b62091: `PaymentMethodType` exposes two additional categories that the platform already supports server-side: `WALLET` (Apple Pay / Google Pay / Visa Mobile) and `INSTALLMENT` (Klarna, PayPo, Twisto, Alior Raty). Storefront code can now branch on them without falling through to `OTHER`.
+
+  **Why** — the GraphQL `PaymentMethodType` enum had drifted away from the underlying domain enum: PayU and Przelewy24 adapters were already mapping payByLink / method names to `WALLET` and `INSTALLMENT` (Apple Pay, Google Pay, BNPL providers), but the public GraphQL enum only declared `CARD / BLIK / BANK_TRANSFER / CASH_ON_DELIVERY / OTHER`. A storefront calling `getAvailablePaymentMethods` against a shop with Apple Pay enabled would crash with `Enum "PaymentMethodType" cannot represent value: "WALLET"`. The enum is now sourced from a single domain definition — drift between the platform's internal enum and the public GraphQL enum is structurally impossible going forward.
+
+  **Additive (backward-compatible)**:
+
+  Two new runtime values exposed by the const + type alias (per `enumsAsConst` codegen):
+
+  ```ts
+  import { PaymentMethodType } from "@doswiftly/storefront-sdk";
+
+  PaymentMethodType.Wallet; // 'WALLET'
+  PaymentMethodType.Installment; // 'INSTALLMENT'
+
+  Object.values(PaymentMethodType);
+  // ['BANK_TRANSFER', 'BLIK', 'CARD', 'CASH_ON_DELIVERY', 'INSTALLMENT', 'OTHER', 'WALLET']
+  ```
+
+  The TypeScript union type widens correspondingly to include `'WALLET' | 'INSTALLMENT'`. Existing code that handled `'OTHER'` as a catch-all keeps working — methods previously falling through to `OTHER` now report their specific category, and any exhaustive switch on `PaymentMethodType` gets a compile error pointing at the missing case.
+
+  **Usage example** — render brand-correct iconography for wallet checkouts:
+
+  ```tsx
+  import { PaymentMethodType } from "@doswiftly/storefront-sdk";
+
+  function PaymentMethodIcon({ type }: { type: PaymentMethodType }) {
+    switch (type) {
+      case PaymentMethodType.Card:
+        return <CardIcon />;
+      case PaymentMethodType.Blik:
+        return <BlikIcon />;
+      case PaymentMethodType.BankTransfer:
+        return <BankIcon />;
+      case PaymentMethodType.Wallet:
+        return <WalletIcon />; // NEW — Apple Pay / Google Pay
+      case PaymentMethodType.Installment:
+        return <InstallmentIcon />; // NEW — Klarna / PayPo / Twisto
+      case PaymentMethodType.CashOnDelivery:
+        return <CashIcon />;
+      case PaymentMethodType.Other:
+        return <GenericPaymentIcon />;
+    }
+  }
+  ```
+
+  **Migration checklist** — none required for storefronts that already routed `OTHER` to a generic icon:
+  - [ ] (Optional) Add explicit branches for `Wallet` / `Installment` in payment method UI to render brand-correct iconography (Apple Pay logo, Klarna logo, etc.) instead of the generic fallback.
+  - [ ] (Optional) If you ran exhaustive `switch (method.type)` blocks asserted with `never`-check, add the two new cases — the compiler points at them on the next build.
+
+  **Standards reference** — Apple Pay / Google Pay are typically classified under "digital wallet" payment methods in industry catalogues (Stripe, Adyen, Braintree all use `wallet` as a top-level category). `INSTALLMENT` covers Buy-Now-Pay-Later providers that present multi-instalment options at checkout.
+
+- 78bd561: `<StorefrontProvider>` now accepts an `initialAccessToken` prop for server-side JWT seed, plus `authStore.setAuth` accepts a nullable customer.
+
+  **Why** — when your storefront has the raw access token server-side (httpOnly cookie value read from a Server Component, SSO redirect parameter, magic link callback, dev-seed env var), previously there was no clean way to inject it into the auth store on the first render. You had to write a `<DevAuthHydration>` workaround with `useEffect`, accept an unnecessary round-trip to `/api/auth/whoami` before `authMiddleware` could add `Authorization: Bearer ...`, or drop down to `useAuthStoreApi().setState({ accessToken })` because `setAuth` required a non-null customer (which you don't have when all you've got is a raw JWT). This release closes that gap.
+
+  **Additive (backward-compatible)**:
+  1. New optional prop on `<StorefrontProvider>`:
+
+     ```ts
+     interface StorefrontProviderProps {
+       // existing props unchanged
+       initialIsAuthenticated?: boolean;
+       initialLanguage?: string;
+
+       // NEW
+       initialAccessToken?: string | null;
+     }
+     ```
+
+     The value seeds the auth store on first mount, so the SDK's request interceptor attaches `Authorization: Bearer ...` to every outgoing GraphQL call from the very first request — no round-trip to `/api/auth/whoami` required to populate the token.
+
+  2. `isAuthenticated` defaults to `!!initialAccessToken` when `initialIsAuthenticated` is not provided (a raw token implies authenticated). Pass `initialIsAuthenticated={false}` explicitly to override in edge cases (opt-out flow, recovery banner holding a token without claiming auth state).
+  3. `AuthStore.setAuth` signature relaxed from `(customer: CustomerInfo, accessToken: string) => void` to `(customer: CustomerInfo | null, accessToken: string) => void`. The runtime already accepted `null`; this aligns the compile-time type with actual behavior (`AuthStore.customer` was already `CustomerInfo | null`). Use case: you have the token (from `initialAccessToken`, SSO callback, magic link) but the customer profile is fetched separately — `setAuth(null, token)` is now valid instead of bypassing the action with `setState`.
+
+  **Usage example**:
+
+  ```tsx
+  // app/layout.tsx
+  import { cookies } from "next/headers";
+  import {
+    StorefrontProvider,
+    AUTH_COOKIE_NAME,
+  } from "@doswiftly/storefront-sdk";
+
+  export default async function RootLayout({ children }) {
+    const cookieStore = await cookies();
+    const initialAccessToken = cookieStore.get(AUTH_COOKIE_NAME)?.value ?? null;
+
+    return (
+      <StorefrontProvider
+        config={{ apiUrl, shopSlug }}
+        shopData={shop}
+        initialAccessToken={initialAccessToken}
+      >
+        {children}
+      </StorefrontProvider>
+    );
+  }
+  ```
+
+  **Security** — the seeded token lives **only in memory** (RAM). It is **never written to localStorage** (XSS hardening — same guarantee as for tokens set later via `useLogin()`, in place since v5.0.0). Hard refresh resets the in-memory token; your Server Component re-reads the httpOnly cookie and seeds the new render.
+
+  **Choosing between `initialIsAuthenticated` and `initialAccessToken`**:
+
+  | You know server-side                                                 | Pass                                 | Round-trip to `/api/auth/whoami`                       |
+  | -------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
+  | _Whether_ the user is signed in (cookie present, value not readable) | `initialIsAuthenticated: boolean`    | Required to fetch the token                            |
+  | The raw JWT itself (cookie value, SSO param, env seed)               | `initialAccessToken: string \| null` | Not required — middleware works from the first request |
+
+  **Migration checklist** — none required. Existing consumers that pass only `initialIsAuthenticated` (or nothing at all) continue to work without changes. To opt into zero-round-trip auth init, read the cookie value (instead of just its presence) and pass it as `initialAccessToken`.
+
+- 5525fd4: `useCartManager` now covers the full checkout lifecycle (9 new operations) and auto-clears the `cart-id` cookie after a successful `complete()` — buyers returning to `/checkout` after payment get a fresh empty cart instead of the converted one.
+
+  **Why** — until now `useCartManager` exposed only the shopping-cart surface (`addItem` / `updateItem` / `removeItem` / `setShippingAddress` / `updateBuyerIdentity` / `updateDiscountCodes` / `updateNote`). Anything past that point — selecting a shipping method, picking a payment method, applying a gift card, finalising the order — required dropping down to the raw `CartClient` and managing cart-id cookie cleanup manually. Two parallel APIs in one checkout form, plus a stale cookie that pointed at a completed cart after every successful order. This release closes both gaps in a single hook.
+
+  **Additive (backward-compatible)**:
+  1. New mutations on `UseCartManagerResult` — all wrapped in the same recovery runner that powers the existing surface, so a stale cart triggers either an auto-replay (`updateAttributes`) or a `cart-expired` event (`complete`, `selectShippingMethod`, `selectPaymentMethod`, `clearPaymentSelection`, `setBillingAddress`, `applyGiftCard`, `removeGiftCard`, `updateGiftCardRecipient`). `createPayment` operates on `orderId`, so it lives outside the recovery runner but still benefits from the shared `status` tracking.
+
+     ```ts
+     interface UseCartManagerResult {
+       // existing — unchanged
+       addItem(lines: CartLineInput[]): Promise<CartMutationOutcome>;
+       updateItem(lines: CartLineUpdateInput[]): Promise<CartMutationOutcome>;
+       removeItem(lineIds: string[]): Promise<CartMutationOutcome>;
+       setShippingAddress(
+         address: CartAddressInput,
+       ): Promise<CartMutationOutcome>;
+       updateBuyerIdentity(
+         buyerIdentity: CartBuyerIdentityInput,
+       ): Promise<CartMutationOutcome>;
+       updateDiscountCodes(codes: string[]): Promise<CartMutationOutcome>;
+       updateNote(note: string): Promise<CartMutationOutcome>;
+
+       // NEW
+       updateAttributes(
+         attributes: CartAttributeInput[],
+       ): 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>;
+       complete(
+         input?: Omit<CartCompleteInput, "cartId">,
+       ): Promise<CartCompleteOutcome>;
+       createPayment(input: PaymentCreateInput): Promise<PaymentSession>;
+     }
+     ```
+
+     Every method takes its input without `cartId` — the hook injects the current cookie value automatically, matching how `setShippingAddress(address)` and `updateDiscountCodes(codes)` already work.
+
+  2. `complete()` clears the `cart-id` cookie and resets `status` to `idle` after a successful call. A subsequent `addItem(...)` then creates a fresh cart automatically — the recovery runner reuses the same code path that already handles the empty-cookie case on a first-time add.
+  3. `status.operation` now includes the new operation names (`'complete'`, `'selectShippingMethod'`, `'selectPaymentMethod'`, `'clearPaymentSelection'`, `'setBillingAddress'`, `'updateAttributes'`, `'applyGiftCard'`, `'removeGiftCard'`, `'updateGiftCardRecipient'`, `'createPayment'`) — drive a single `<Spinner label={status.operation} />` across the whole checkout form.
+
+  **Usage example** — replace raw `CartClient` calls in your checkout flow:
+
+  ```tsx
+  "use client";
+  import { useCartManager } from "@doswiftly/storefront-sdk/react";
+  import { useRouter } from "next/navigation";
+
+  export function CheckoutSubmit() {
+    const router = useRouter();
+    const { complete, createPayment, status, error } = useCartManager();
+
+    async function onSubmit() {
+      const { order } = await complete({ idempotencyKey: crypto.randomUUID() });
+      // cart-id cookie is already cleared at this point — addItem from here on
+      // would create a fresh cart.
+
+      const successUrl = `/checkout/success?token=${order.accessToken}&orderNumber=${order.orderNumber}`;
+
+      if (order.canCreatePayment) {
+        const session = await createPayment({
+          orderId: order.id,
+          returnUrl: `${window.location.origin}${successUrl}`,
+        });
+        if (session.flow === "ONLINE_REDIRECT") {
+          window.location.href = session.redirectUrl!;
+          return;
+        }
+      }
+
+      router.push(successUrl);
+    }
+
+    return (
+      <button onClick={onSubmit} disabled={status.type === "loading"}>
+        {status.type === "loading"
+          ? `Working — ${status.operation}…`
+          : "Place order"}
+      </button>
+    );
+  }
+  ```
+
+  **Recovery taxonomy for the new operations**:
+
+  | Operation                 | On stale cart                                | Why                                                  |
+  | ------------------------- | -------------------------------------------- | ---------------------------------------------------- |
+  | `updateAttributes`        | Auto-replay via `cartCreate({ attributes })` | Stateless metadata — atomic re-create is safe        |
+  | `setBillingAddress`       | Bail + `cart-expired` event                  | Separate from shipping; cart must exist              |
+  | `selectShippingMethod`    | Bail + `cart-expired` event                  | Method is tied to cart contents and shipping address |
+  | `selectPaymentMethod`     | Bail + `cart-expired` event                  | Payment selection on existing cart state             |
+  | `clearPaymentSelection`   | Bail + `cart-expired` event                  | Operates on existing payment fields                  |
+  | `applyGiftCard`           | Bail + `cart-expired` event                  | Balance allocation tied to cart total                |
+  | `removeGiftCard`          | Bail + `cart-expired` event                  | `giftCardId` refers to a row on the dead cart        |
+  | `updateGiftCardRecipient` | Bail + `cart-expired` event                  | `lineId` refers to a line in the dead cart           |
+  | `complete`                | Bail + `cart-expired` event                  | A finalised cart cannot be auto-recreated            |
+  | `createPayment`           | Out of recovery scope                        | Operates on `orderId`, not `cartId`                  |
+
+  Bail operations fire your existing `onExpired(...)` listener with `event.operation` set — UI shows the same toast/banner you already wired up for `updateItem`/`removeItem`.
+
+  **Migration checklist** — optional refactor for existing storefronts:
+  - [ ] Replace `cartClient.complete({ cartId, ... })` + manual `cookieStore.clear()` with `useCartManager().complete({ ... })`.
+  - [ ] Replace `cartClient.selectShippingMethod` / `selectPaymentMethod` / `applyGiftCard` / etc. with the corresponding `useCartManager` methods to get free recovery handling and unified `status` tracking.
+  - [ ] If your `onExpired` listener was bound on `useCartManager`, the same listener now also catches stale carts on the new operations — no extra wiring.
+
+  Calling the raw `CartClient` methods directly still works exactly as before — the new hook surface is purely additive on top.
+
+- 468f70b: `useCartManager` now accepts an optional `{ initialCartId }` seed — closes the last gap blocking server-known-cart-id storefronts from adopting the full checkout suite (`complete`, `selectShippingMethod`, `selectPaymentMethod`, …) shipped earlier.
+
+  **Why** — `useCartManager` reads the cart-id exclusively from the `cart-id` cookie. Storefronts that resolve cart-id server-side (dev env seed for sample storefronts without a product listing, magic-link checkout where the URL carries the cart-id, embedded iframes where the parent supplies cart-id via `postMessage`, customer-service "view this cart" tools, server-side recovery, multi-cart B2B selectors) had no clean way to feed that value into the hook. The workaround was to drop down to raw `CartClient` for every checkout mutation and lose the auto-recovery + `complete` cookie cleanup that the hook provides. This release mirrors the `<StorefrontProvider initialAccessToken>` pattern (v17.1.0) for the cart-id half of the checkout state.
+
+  **Additive (backward-compatible)**:
+
+  ```ts
+  interface UseCartManagerOptions {
+    initialCartId?: string | null;
+  }
+
+  function useCartManager(
+    options?: UseCartManagerOptions,
+  ): UseCartManagerResult;
+  ```
+
+  Calling `useCartManager()` with no arguments is unchanged. Pass `{ initialCartId }` to seed the hook with a server-known value.
+
+  **Priority order**: `cookie wins → seed → auto-create`. The cookie is the canonical cross-tab state; the seed only fills the gap when the cookie is empty. Once the seed is used, it is eagerly written to the cookie so subsequent reads (other tabs, the next mutation, `getCart`) observe a single source of truth.
+
+  **Stale seed handling** — no special-case code path. A stale seed flows through the standard recovery pipeline:
+  - `addItem` (and other auto-replay ops) → backend returns `CART_NOT_FOUND` → runner clears the cookie, calls `cartCreate({ lines })` against a fresh cart, writes the new id to the cookie, returns the operation result. Storefront sees a successful `addItem` with a populated cart.
+  - `updateItem` / `removeItem` / `selectShippingMethod` / `selectPaymentMethod` / `complete` / other state-dependent ops → runner clears the cookie, emits `cart-expired`, throws `CartRecoveryNotPossibleError`. UI shows the toast/banner already wired up for the cookie-driven flow — no extra subscription needed.
+
+  **Usage example** — magic-link checkout (cart-id resolved server-side from URL params, passed through Server Component to Client Component):
+
+  ```tsx
+  // app/checkout/[token]/page.tsx — Server Component
+  import { cookies } from "next/headers";
+  import { CART_COOKIE_NAME } from "@doswiftly/storefront-sdk";
+  import { CheckoutClient } from "./CheckoutClient";
+  import { resolveCartIdFromMagicLinkToken } from "@/lib/magic-link";
+
+  export default async function CheckoutPage({
+    params,
+  }: {
+    params: Promise<{ token: string }>;
+  }) {
+    const { token } = await params;
+    const cookieJar = await cookies();
+    const initialCartId =
+      cookieJar.get(CART_COOKIE_NAME)?.value ??
+      (await resolveCartIdFromMagicLinkToken(token));
+
+    return <CheckoutClient initialCartId={initialCartId} />;
+  }
+  ```
+
+  ```tsx
+  // app/checkout/[token]/CheckoutClient.tsx
+  "use client";
+
+  import { useCartManager } from "@doswiftly/storefront-sdk/react";
+
+  export function CheckoutClient({
+    initialCartId,
+  }: {
+    initialCartId: string | null;
+  }) {
+    // Hook handles seed → cookie → recovery transparently. No raw CartClient needed.
+    const { complete, selectPaymentMethod, addItem, status } = useCartManager({
+      initialCartId,
+    });
+    // ... checkout flow exactly as for a cookie-driven storefront
+    return /* ... */;
+  }
+  ```
+
+  **Migration checklist** — none required for existing storefronts. The new option is opt-in. To adopt:
+  - [ ] Identify your server-known cart-id source (URL params, env var for dev fixtures, parent `postMessage` for iframes, internal admin lookup).
+  - [ ] Resolve it in a Server Component (Next.js App Router) or Route Handler, pass through to a Client Component as a prop.
+  - [ ] In the Client Component, pass it to `useCartManager({ initialCartId })`.
+  - [ ] Remove any previous workaround that manually set the `cart-id` cookie before the hook mounted.
+
+  Calling `useCartManager` with no options or with `{ initialCartId: null }` continues to behave exactly as before.
+
+  **Standards reference** — symmetric with the `initialAccessToken` prop on `<StorefrontProvider>` (v17.1.0): both are seeds for first-render state that the client cannot read from the canonical source on its own. Same priority semantics (`canonical store wins → seed → fallback`), same eager-promotion behaviour (seed flows into the canonical store on first use).
+
+### Patch Changes
+
+- 9bac7e9: Fix stale field names in the `CartSelectPaymentMethodInput` description. The input's description still referenced `preferredProviderCode` / `preferredInstrumentCode` after those fields were renamed to `preferredProvider` / `preferredInstrument`. Description-only correction — field names, types and behavior are unchanged.
+- 9857460: Version-sync with `@doswiftly/storefront-operations`: the bundled GraphQL schema now carries clean English descriptions (no code changes).
+- a5a3f4b: Image transform pipeline extended to shop-owned content surfaces: `BlogCategory.image`, `BlogPost.featuredImage`, `LoyaltyReward.image`, and `MenuItem.image`.
+
+  These four fields already accepted an `Image.url(transform: ...)` selection, but the URL was not threaded through the storefront CDN context, so any URL stored as a relative path (rather than a full https URL) skipped the imgproxy signing step. Now all four resolvers build the CDN context per query and pass it to `mapImageToGraphQL`, so transform-aware URLs honor multi-tenant signing on shop-owned media.
+
+  No schema changes. Selections that already used `image { url(transform: ...) }` keep working — the only behavior change is that URLs stored as relative paths are now CDN-signed before transforms apply. URLs stored as absolute https values keep returning unchanged (the helper falls back to the raw value when there is no path component).
+
+  **What this enables**:
+
+  ```graphql
+  query BlogList {
+    blogPosts(first: 10) {
+      edges {
+        node {
+          title
+          featuredImage {
+            url(transform: { maxWidth: 800, preferredContentType: WEBP })
+            altText
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  The same `image { url(transform: ...) }` pattern is also valid on `BlogCategory`, `LoyaltyReward`, and `MenuItem`.
+
+  **No migration required.**
+
+- 0c0205d: Image transform support extended to `Cart.lines[].variant.image`, `Order.lineItems[].variant.image`, `Collection.image`, and `Category.image`.
+
+  Previously these four image fields returned a plain object that did not pass through the storefront image pipeline, so calling `image { url(transform: { maxWidth: 200, preferredContentType: WEBP }) }` silently returned a raw URL without applying the requested size/format. Now all four resolvers map images through the same transform pipeline used by `Product` and `ProductVariant`, so `Image.url(transform: ...)` honors the requested dimensions and format.
+
+  No schema changes — selections that already used `image { url }` keep working and start receiving the transform-aware URL when a transform argument is supplied. Selections that already used `image { url(transform: ...) }` now apply the transform end-to-end.
+
+  **What you can do now**:
+
+  ```graphql
+  query CartThumbnails {
+    cart {
+      lines {
+        edges {
+          node {
+            variant {
+              image {
+                url(transform: { maxWidth: 200, preferredContentType: WEBP })
+                altText
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  The same `image { url(transform: ...) }` pattern is now valid on `Order.lineItems[].variant`, `Collection.image`, and `Category.image`.
+
+  **No migration required** — existing storefronts continue to work. To take advantage of transforms on these surfaces, switch hardcoded sizes in your `<img src>` rendering to a parametrized `url(transform: ...)` selection.
+
+- 9c55b39: Export the payment enums `PaymentProvider`, `PaymentInstrumentType`, `PaymentInstrumentDisplayHint` and `PaymentMethodUnavailableReason` from the package root.
+
+  **Why**: these enums were already generated but only reachable via a deep import path, which reads as private API. They are now re-exported from the package entry point alongside the other schema enums (`PaymentMethodType`, `DeliveryType`, ...), so you can type a wrapper around `cartSelectPaymentMethod` — whose `preferredProvider` input is the `PaymentProvider` enum — without reaching into internals.
+
+  **Additive (backward-compatible)**: each enum is both a runtime value (`Object.values(PaymentProvider)`) and a type (`import type { PaymentProvider }`). No existing import changes.
+
+  **Usage example**:
+
+  ```ts
+  import { PaymentProvider } from "@doswiftly/storefront-sdk";
+
+  // Type a wrapper prop:
+  type SelectArgs = { preferredProvider?: PaymentProvider };
+
+  // Or read the value at runtime:
+  const all = Object.values(PaymentProvider); // ['PAYU', 'PRZELEWY24', ...]
+  ```
+
+  **Migration checklist**: optional — if you used a deep import to reach these enums, switch to the package root import.
+
+  `@doswiftly/storefront-operations` carries a version-sync bump only — no operation or schema change.
+
+- 8c0d8fa: Version-sync release — no code changes in this package.
+
+  Released together with `@doswiftly/storefront-operations` (linked pair) so consumers can pick up the new `./operations.json` subpath export without a mismatched-version warning.
+
 ## 17.0.0
 
 ### Major Changes