@doswiftly/storefront-operations 17.0.0 → 18.1.0

package/AGENTS.md

@@ -27,7 +27,7 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 17.0.0
+- **Schema version**: 18.1.0
 - **Queries**: 52
 - **Mutations**: 41
 - **Fragments**: 104

package/CHANGELOG.md

@@ -1,5 +1,555 @@
 # Changelog
 
+## 18.1.0
+
+### Minor Changes
+
+- ff03fd3: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package.
+
+## 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: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `debug: 'verbose'` mode and `DebugOptions` granular controls.
+- 5525fd4: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive runtime const exports of schema enums.
+- 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: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `<StorefrontProvider initialAccessToken>` prop and `authStore.setAuth` signature relax.
+- 5525fd4: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `useCartManager` checkout suite and `complete()` auto-cleanup.
+- 468f70b: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `useCartManager({ initialCartId })` server-known seed.
+
+### 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: Polished all GraphQL schema descriptions to consistent professional English (documentation only — no contract 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: Expose `operations.json` through the package `exports` map.
+
+  **Why**: Documentation generators, MDX components, and other build-time tools need structural access to operation metadata (name, kind, section, description, variables, fragmentRefs, body) without parsing raw `.graphql` files. The `operations.json` file was already published in the npm tarball; this change makes it consumable via a typed subpath import.
+
+  **Additive (backward-compatible)**:
+
+  ```ts
+  // New: structural import of all operations
+  import operations from "@doswiftly/storefront-operations/operations.json";
+
+  console.log(operations.queries.length); // 52
+  console.log(operations.mutations.length); // 41
+
+  // Existing imports unchanged:
+  import schema from "@doswiftly/storefront-operations/schema.graphql";
+  ```
+
+  **Usage example** — build-time docs generation:
+
+  ```ts
+  import operations from "@doswiftly/storefront-operations/operations.json";
+
+  const cartOps = operations.mutations.filter(
+    (op) => op.section === "Cart Mutations",
+  );
+
+  for (const op of cartOps) {
+    console.log(`${op.name}: ${op.description}`);
+    console.log(
+      `  Variables: ${op.variables.map((v) => `${v.name}: ${v.type}`).join(", ")}`,
+    );
+  }
+  ```
+
+  **Migration checklist**: none — additive change, existing consumers unaffected.
+
 ## 17.0.0
 
 ### Major Changes

package/README.md

@@ -380,7 +380,7 @@ full executable body of each operation.
 | `CartSetShippingAddress` | Phase 3 unify-cart-graphql-surface: wszystkie fulfillment + payment + completion operations teraz na Cart aggregate (zamiast Checkout dual-aggregate). Klient robi typowy checkout flow: cart create/add items → setShipping/Billing/Method → selectPayment → (optional) applyGiftCard → cartComplete → Order created. Sets the shipping address on the cart (full replace, not patch). Triggers cart re-pricing (tax recalculation per address country/region). Address format validated against `CartAddressInput` constraints (firstName/lastName/streetLine1/city/country/postalCode required). Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
 | `CartSetBillingAddress` | Sets the billing address on the cart (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
 | `CartSelectShippingMethod` | Selects a shipping method by `shippingMethodId` (typed `ID!`, a stable shipping-method UUID — NOT a per-request token). The id comes from a list of methods available for the current address + cart subtotal (queryable separately). Errors: `SHIPPING_METHOD_REQUIRED`, `ZIP_CODE_NOT_SUPPORTED`, `CART_NOT_FOUND`. |
-| `CartSelectPaymentMethod` | Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...). Optional `preferredProviderId` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category. Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`. |
+| `CartSelectPaymentMethod` | Selects a payment method on the cart by category (`methodType` — BLIK, CARD, BANK_TRANSFER, ...). Optional `preferredProvider` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. The backend resolves the gateway routing from `MerchantPaymentConfig` at `cartComplete`; the selection persisted here is the category. Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`, `CART_UNAUTHENTICATED`. |
 | `CartApplyGiftCard` | Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically at `cartComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`. |
 | `CartRemoveGiftCard` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `cartComplete`, removing before completion has no effect on the underlying gift card balance. |
 | `CartUpdateGiftCardRecipient` | Sets per-line-item recipient details (name, email, message) for digital gift card products in the cart (line items where the variant represents a gift-card SKU). Required before `cartComplete` for any line item with a gift-card variant. Recipient details propagated to the resulting order. |
@@ -488,7 +488,7 @@ full executable body of each operation.
 | `Cart` | `Cart` | Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes, plus fulfillment fields (email/phone/addresses/shipping method/payment method/applied gift cards). Spread on the cart drawer / cart page; refetch after every cart mutation including completion lifecycle. |
 | `CartShippingMethod` | `CartShippingMethod` | Shipping method selected on a cart (D8 term unification — wcześniej ShippingRate). Returned przez `cart.selectedShippingMethod` po `cartSelectShippingMethod` mutation. |
 | `CartAppliedGiftCard` | `CartAppliedGiftCard` | Gift card applied to a cart — `id` is the stable handle the storefront passes to `cartRemoveGiftCard` (no need to keep the raw code around). Plus masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`. |
-| `CartSelectedPaymentMethod` | `PaymentMethod` | Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon, description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display. |
+| `CartSelectedPaymentMethod` | `PaymentMethod` | Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon image (transformable), description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display. |
 
 #### Shop
 
@@ -509,8 +509,8 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `PaymentMethodInstrument` | `PaymentMethodInstrument` | A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PIN_ENTRY`, `WALLET_TAP`, `BANK_LIST`, `CARD_FORM`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide. |
-| `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...). `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic. `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `instrumentCode` as `preferredInstrumentCode` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step. |
+| `PaymentInstrument` | `PaymentInstrument` | A single concrete instrument exposed by a gateway provider (BLIK code, branded bank, wallet, card brand). Pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. `displayHint` is a semantic UX hint (`PROMINENT_BUTTON`, `BRANDED_TILE`, `DROPDOWN_OPTION`, `RADIO_OPTION`) — storefront branches rendering accordingly. `enabled: false` means the gateway reported the instrument as temporarily disabled — gray out, don't hide. |
+| `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — method-centric. `type` is the category (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER) — drive iconography here. `provider`, `providersAvailable`, `preferredProvider` are `PaymentProvider` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...). `available` is `false` when the resolving gateway is temporarily unavailable or reported the method as disabled — gray-out the tile, don't hide it; `unavailableReason` carries the diagnostic. `instruments` lists concrete gateway-side instruments (BLIK code, branded banks, wallets) when the gateway exposes granular data — pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` for direct deep-link to that instrument screen on the gateway. Spread on the checkout payment step. |
 | `AvailablePaymentMethods` | `AvailablePaymentMethods` | Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query. |
 | `PaymentSession` | `PaymentSession` | Initiated payment session for an order — returned by the `paymentCreate` mutation. Branch on `flow`: `ONLINE_REDIRECT` (redirect the browser to `redirectUrl`), `ONLINE_EMBEDDED` (render an in-page widget with `clientSecret`), `INSTANT_DIRECT` (settled with no UI — read `status`). `expiresAt` is ISO 8601, present when the gateway session has a TTL. |
 | `PaymentWarning` | `PaymentWarning` | Non-blocking signal emitted alongside `userErrors[]` in `paymentCreate` payload — backend state change context (e.g. an auto-clear of preselected instrument after gateway rejection). Pre-translated by backend per shop locale. `code === 'INSTRUMENT_CLEARED_FOR_RETRY'` signals storefront that the next `paymentCreate` will land on the gateway default landing page (server-side cleared `Order.paymentInstrumentCode` after `INSTRUMENT_PRESELECTION_FAILED`). `retryHint` is optional context for UI dispatch — currently unused for `INSTRUMENT_CLEARED_FOR_RETRY`, reserved for future warning codes. |
@@ -521,7 +521,7 @@ full executable body of each operation.
 | --- | --- | --- |
 | `ShipmentEvent` | `ShipmentEvent` | One tracking event in the shipment timeline — status, description, location, timestamp. Spread on the tracking page timeline. |
 | `ShipmentPackage` | `ShipmentPackage` | Physical package metadata (weight + dimensions). Used in the merchant's label generation; storefronts rarely render this directly. |
-| `ShipmentItem` | `ShipmentItem` | One item in a shipment — title, variant, sku, quantity, image URL. Spread inside `Shipment.items[]` for the tracking page item list. |
+| `ShipmentItem` | `ShipmentItem` | One item in a shipment — title, variant, sku, quantity, live variant image (transformable). Spread inside `Shipment.items[]` for the tracking page item list. `image` is live from the current variant (snapshot fallback when variant has been deleted since fulfillment — returns null, render a placeholder). |
 | `Shipment` | `Shipment` | Full shipment shape — provider, tracking number + URL, label URL, status, ETA, recipient address, packages, items, full event timeline. Spread on the tracking page. |
 | `ShipmentBasic` | `Shipment` | Lightweight shipment shape — id, tracking number + URL, status, dates. No items / events / address. Use for order summary cards or on the public `shipmentByTrackingNumber` query. |
 
@@ -547,7 +547,7 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `ShippingCarrier` | `ShippingCarrier` | Carrier offering the shipping method — id, display name, logo URL, internal service code. |
+| `ShippingCarrier` | `ShippingCarrier` | Carrier offering the shipping method — id, display name, logo image (transformable), internal service code. |
 | `DeliveryEstimate` | `DeliveryEstimate` | Estimated delivery window — `minDays` to `maxDays` plus a human-readable description (e.g. "2-4 business days"). |
 | `FreeShippingProgress` | `FreeShippingProgress` | Free-shipping progress info — `qualifies` flag, current cart amount, threshold, remaining to qualify, percent progress, and a localized message ("Add 20 PLN more for free shipping"). Use to render a free-shipping progress bar in the cart drawer. |
 | `AvailableShippingMethod` | `AvailableShippingMethod` | One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. `deliveryType` signals whether to render a pickup-point / locker picker (`HOME` vs `PICKUP_POINT` / `LOCKER`) so the storefront does not have to infer it from the method name. Spread on the checkout shipping step. |
@@ -556,7 +556,7 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `AttributeSwatch` | `AttributeSwatch` | Visual swatch for an attribute filter value — color hex (for color filters) or image URL (for pattern/material swatches). |
+| `AttributeSwatch` | `AttributeSwatch` | Visual swatch for an attribute filter value — color hex (for color filters) or image (for pattern/material swatches). |
 | `AttributeRangeBounds` | `AttributeRangeBounds` | Numeric range bounds for slider-style filters — min, max, currency code (when relevant). |
 | `AttributeFilterValue` | `AttributeFilterValue` | One discrete value in a filterable attribute (e.g. "Red" for the Color filter). Includes `productCount` in the current listing context (for "(12)" badges next to filter values), optional swatch and price modifier. |
 | `AttributeDefinition` | `AttributeDefinition` | Filterable attribute exposed on the storefront — name, type (SELECT / CHECKBOX / SLIDER / etc.), filterability flags, display order, and either discrete `filterValues[]` or numeric `rangeBounds`. Spread inside `availableFilters.attributes[]`. |