@doswiftly/storefront-operations 16.0.0 → 17.0.0

package/AGENTS.md

@@ -27,10 +27,10 @@ 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**: 16.0.0
+- **Schema version**: 17.0.0
 - **Queries**: 52
-- **Mutations**: 40
-- **Fragments**: 102
+- **Mutations**: 41
+- **Fragments**: 104
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order

package/CHANGELOG.md

@@ -1,5 +1,471 @@
 # Changelog
 
+## 17.0.0
+
+### Major Changes
+
+- d3f0f04: `cartSelectPaymentMethod` mutation is now method-centric.
+
+  The buyer picks a payment **category** (`BLIK`, `CARD`, `BANK_TRANSFER`, ...) and the backend resolves the preferred gateway from the merchant's `MerchantPaymentConfig` at `paymentCreate` time. Previously the storefront had to look up a per-provider tile UUID via `availablePaymentMethods` and pass it as `paymentMethodId`.
+
+  **Breaking** — `CartSelectPaymentMethodInput` shape changed:
+
+  ```graphql
+  # Before
+  input CartSelectPaymentMethodInput {
+    cartId: ID!
+    paymentMethodId: ID! # UUID of a per-provider tile
+  }
+
+  # After
+  input CartSelectPaymentMethodInput {
+    cartId: ID!
+    methodType: PaymentMethodType! # BLIK, CARD, BANK_TRANSFER, ...
+    preferredProviderId: String # optional override (provider code)
+  }
+  ```
+
+  Migration:
+
+  ```ts
+  // Before
+  await sdk.cartSelectPaymentMethod({ input: { cartId, paymentMethodId } });
+
+  // After
+  await sdk.cartSelectPaymentMethod({ input: { cartId, methodType: "BLIK" } });
+  // Or with explicit gateway override:
+  await sdk.cartSelectPaymentMethod({
+    input: { cartId, methodType: "BLIK", preferredProviderId: "payu" },
+  });
+  ```
+
+  The `availablePaymentMethods` query now returns deduplicated rows per `PaymentMethodType` (one row per BLIK, CARD, ...) with `providersAvailable` (gateway codes sorted by merchant priority) and `preferredProvider` (head of the list). The legacy `group: BY_PROVIDER` argument was removed — there is one canonical shape.
+
+  **Why** — A merchant configuring PayU + Przelewy24 would previously see "PayU BLIK" and "P24 BLIK" as two separate tiles on the storefront. After this change the storefront shows one BLIK tile; the merchant chooses which gateway handles BLIK via priority settings, and the buyer never sees the internal routing.
+
+  **Live capability sync (opt-in)** — gateway adapters may expose an optional `getAvailablePaymentMethods(credentials, { currency, amount, country })` capability returning the gateway-reported active methods (min/max amount, brand image, enabled flag). When supported, the platform caches the response per shop/currency and uses it to refine the storefront picker. Gateways without the capability fall back to a static capability matrix. Gateway HTTP failures are soft-failed — the buyer always sees the merchant's configured methods even when the upstream is temporarily unreachable.
+
+- 7931668: Payment instrument preselection — direct deep-link to a specific instrument screen on the hosted gateway page (BLIK code, branded bank, wallet, card brand) instead of the gateway default landing.
+
+  **Why**: shoppers picking BLIK from the storefront UI now skip the gateway method picker entirely — the redirect lands directly on the BLIK code entry. Same flow for picking mBank, ING, Apple Pay, etc. Industry shorthand calls this "deep-link checkout" — 5-15% conversion uplift on single-instrument funnels.
+
+  **Breaking schema changes**:
+  1. `CartSelectPaymentMethodInput.preferredProviderId` → `preferredProviderCode`. Rename only — same semantics (override the merchant's preferred provider). Aligns with the `*Code` naming convention (`*Id` reserved for UUIDs, `*Code` for lowercase string identifiers like `payu` / `przelewy24`).
+
+     ```graphql
+     # Before
+     input CartSelectPaymentMethodInput {
+       cartId: ID!
+       methodType: PaymentMethodType!
+       preferredProviderId: String # ← removed
+     }
+
+     # After
+     input CartSelectPaymentMethodInput {
+       cartId: ID!
+       methodType: PaymentMethodType!
+       preferredProviderCode: String # ← renamed
+       preferredInstrumentCode: String # ← new (additive)
+     }
+     ```
+
+  2. `PaymentMethod.provider` / `PaymentMethod.providersAvailable` / `PaymentMethod.preferredProvider` / `Order.paymentMethod` / `Payment.provider` are now the typed `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, `STRIPE`, `CASH_ON_DELIVERY`, `BANK_TRANSFER`, `MANUAL_PAYMENT`, `GIFT_CARD`, `TEST_GATEWAY`) instead of `String`. Replace any `if (provider === 'payu')` storefront branches with the imported enum.
+
+     ```ts
+     // Before
+     if (paymentMethod.provider === "payu") {
+       /* ... */
+     }
+
+     // After
+     import { ProviderCode } from "@doswiftly/storefront-sdk";
+     if (paymentMethod.provider === ProviderCode.PAYU) {
+       /* ... */
+     }
+     ```
+
+  3. `PaymentMethod.amountLimits` removed from the SDK fragment. The field still exists on the schema for backward-compat, but the SDK no longer selects it — most storefronts never used it and the data is provider-specific (PayU/P24 report limits per method, not per checkout). Re-add it to your local fragment if you need it.
+
+  **Additive (backward-compatible)**:
+  - `PaymentMethod.instruments: [PaymentMethodInstrument!]` — concrete instruments exposed by the gateway (BLIK code, branded banks, wallets, card brands). Each instrument carries `providerCode`, `instrumentCode`, `displayName`, `brandImageUrl`, `displayHint` (semantic UX hint: `PIN_ENTRY` / `WALLET_TAP` / `BANK_LIST` / `CARD_FORM`), `enabled`. `null` when the gateway doesn't expose granular data; empty array when all instruments are disabled.
+  - `cartSelectPaymentMethod(input: { preferredInstrumentCode })` — pass the chosen instrument's `instrumentCode` to persist it on the cart. Eager validation cross-checks against the gateway's live capabilities — invalid codes return `userErrors[].code = 'CART_INVALID_INSTRUMENT_CODE'`.
+  - `Cart.selectedPaymentInstrumentCode: String` — round-trips the persisted choice so the storefront can re-render the selected instrument on cart refresh.
+  - `Order.paymentInstrumentCode: String` — propagated from cart at `cartComplete`; the gateway adapter uses it to build the deep-link payload at `paymentCreate`.
+
+  **Usage example** — instrument-level deep-link checkout:
+
+  ```ts
+  import { useCartManager, ProviderCode } from "@doswiftly/storefront-sdk";
+
+  const { selectPaymentMethod, complete, createPayment } = useCartManager();
+
+  // 1. Render the instrument tiles from the gateway-reported list
+  const method = availablePaymentMethods.methods.find((m) => m.type === "BLIK");
+  const instrument = method?.instruments?.find(
+    (i) => i.instrumentCode === "blik",
+  );
+
+  // 2. Persist the buyer's choice on the cart
+  await selectPaymentMethod({
+    methodType: "BLIK",
+    preferredProviderCode: "payu",
+    preferredInstrumentCode: instrument.instrumentCode,
+  });
+
+  // 3. Complete the cart — instrument propagates to the Order
+  const { order } = await complete();
+
+  // 4. Initiate payment — gateway redirects directly to the BLIK code screen
+  const session = await createPayment(order.id);
+  window.location.href = session.redirectUrl;
+  ```
+
+  **Error handling**:
+  - `userErrors[].code === 'CART_INVALID_INSTRUMENT_CODE'` — instrument code is not available with the chosen provider (gateway disabled it, merchant config changed, typo). Refresh `availablePaymentMethods` and re-prompt the buyer.
+  - `paymentCreate` failed gateway initiation with the preselected instrument? The order's `paymentInstrumentCode` is automatically cleared (best-effort) — the next `paymentCreate` call falls back to the gateway default landing page. Storefront just retries.
+
+  **Rate limits**:
+  - `availablePaymentMethods` Query: 60 requests/min per IP+shop. Live capability lookups (OAuth + gateway list call) are expensive — hitting the limit returns `extensions.code: 'THROTTLED'` with `retryAfter`. Don't poll; cache the result for the duration of the checkout step.
+
+  **Gateway API version pinning**:
+  - PayU API pinned to `v2_1`, Przelewy24 API pinned to `v1`. When the upstream gateway ships a major version migration, the SDK / operations packages will bump major together with the constant update.
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Rename `preferredProviderId` → `preferredProviderCode` everywhere in storefront mutations.
+  - [ ] Replace string comparisons (`provider === 'payu'`) with `ProviderCode` enum.
+  - [ ] Re-add `amountLimits` to your local PaymentMethod fragment if you used it.
+  - [ ] (Optional) Render the new `instruments` array as tiles to enable instrument-level deep-link checkout — 1-2 extra hours of UI work, measurable conversion impact on single-instrument flows.
+
+### Minor Changes
+
+- fd82b62: `PaymentMethod` type gains availability + amount limit fields.
+
+  The storefront `PaymentMethod` returned by `availablePaymentMethods` (and `Cart.availablePaymentMethods` / `Cart.selectedPaymentMethod`) now carries three additional fields:
+  - **`available: Boolean!`** — `false` when the resolving gateway is temporarily unavailable (incident, maintenance) or reported the method as disabled. Storefront should gray-out the tile instead of hiding it — gives merchants observability into routing failures.
+  - **`unavailableReason: PaymentMethodUnavailableReason`** — diagnostic enum (`GATEWAY_DOWN`, `GATEWAY_DISABLED`, `NO_INSTRUMENTS`, `CREDENTIALS_INVALID`). Null when `available` is true. Use for context-aware copy ("Provider is temporarily down" vs "Method not configured").
+  - **`amountLimits: PaymentMethodAmountLimits`** — gateway-reported min/max transaction amount in the resolving currency (e.g. BLIK 1-20000 PLN). Filter the picker against cart total. Null when the gateway does not report limits.
+
+  ```graphql
+  fragment PaymentMethod on PaymentMethod {
+    # existing fields (id, name, provider, type, icon, ...)
+    providersAvailable
+    preferredProvider
+    available
+    unavailableReason
+    amountLimits {
+      min
+      max
+      currency
+    }
+  }
+  ```
+
+  **Currency** is automatically resolved from the storefront context (cascade: `@inContext(currency:)` directive → `X-Preferred-Currency` header → cookie → `Accept-Language` → shop default). Override per query via the `@inContext(currency: "EUR")` directive — no new schema argument.
+
+  **Migration example** for storefront pickers:
+
+  ```ts
+  const { methods } = await sdk.cart.availablePaymentMethods();
+  return methods.map((method) => (
+    <PaymentTile
+      key={method.type}
+      type={method.type}
+      disabled={!method.available}
+      tooltip={method.unavailableReason && reasonCopy[method.unavailableReason]}
+      badge={method.amountLimits && cart.total > method.amountLimits.max ? 'Cart too large' : null}
+    />
+  ));
+  ```
+
+  Backend additionally sanitizes provider error messages (strips OAuth tokens, URLs, JSON secret keys, stack traces) before returning them in admin diagnostic responses — internal logs keep the full error for diagnostics.
+
+- c878d14: Payment instrument preselection — storefront UX completion (distinct error code + warnings array + explicit deselect mutation).
+
+  **Why**: storefront dispatching dla instrument failure stał się context-aware. Dziś generic `PAYMENT_FAILED` post-auto-clear nie pozwalał odróżnić "instrument cleared, retry default landing OK" od "real gateway outage, retry kolejnym attempt". Plus brak explicit deselect — accordion "wróć do wyboru metody" UI wymagał hack typu re-select method.
+
+  **Additive (backward-compatible)**:
+  1. `PaymentErrorCode.INSTRUMENT_PRESELECTION_FAILED` — new enum value. Wystawiany po auto-clear `Order.paymentInstrumentCode` post-`InvalidPaymentInstrumentError`. Distinct od `PAYMENT_FAILED` (generic gateway failure fallback dla credentials / network / 5xx / circuit breaker).
+  2. `PaymentCreatePayload.warnings: [PaymentWarning!]!` — new field, default empty array. Emitted post-auto-clear z entry `{ code: INSTRUMENT_CLEARED_FOR_RETRY, message, retryHint: null }`. Storefront dispatches retry hint differently (accordion reset / progress bar / itp.).
+  3. `cartClearPaymentSelection(input: { cartId: ID! })` — new mutation. Atomic NULL across all payment selection fields. Idempotent. The cart must be `ACTIVE` — `CONVERTED` carts reject with `userErrors[0].code = 'ALREADY_COMPLETED'`. Rate limit 30/min.
+
+  **Storefront usage** — handle instrument failure z context-aware retry:
+
+  ```ts
+  import {
+    useCartManager,
+    type CartMutationOutcome,
+  } from "@doswiftly/storefront-sdk";
+
+  const { selectPaymentMethod, clearPaymentSelection, createPayment } =
+    useCartManager();
+
+  // 1. Klient wybiera BLIK preselect
+  await selectPaymentMethod({
+    methodType: "BLIK",
+    preferredProviderCode: "payu",
+    preferredInstrumentCode: "blik",
+  });
+
+  // 2. Try paymentCreate — może rzucić instrument-specific error
+  try {
+    const session = await createPayment(orderId);
+    window.location.href = session.redirectUrl;
+  } catch (err) {
+    if (err.userErrors?.[0]?.code === "INSTRUMENT_PRESELECTION_FAILED") {
+      // Backend auto-cleared instrument — show retry button
+      // Warning message available via err.warnings[0].message
+      showRetryUI({
+        title: "Instrument płatności niedostępny",
+        message: err.warnings?.[0]?.message ?? err.message,
+        onRetry: () => createPayment(orderId), // next attempt = default landing
+      });
+    } else if (err.userErrors?.[0]?.code === "PAYMENT_FAILED") {
+      // Generic gateway outage — retry z tym samym instrumentem
+      showOutageUI({
+        message: err.message,
+        onRetry: () => createPayment(orderId),
+      });
+    }
+  }
+
+  // 3. Accordion "wróć do wyboru metody" — explicit deselect
+  await clearPaymentSelection({ cartId });
+  // Cart.selectedPaymentMethod === null, Cart.selectedPaymentInstrumentCode === null
+  ```
+
+  **Migration guide for existing storefronts**:
+  - [ ] Add `warnings[]` to your `paymentCreate` selection set (if you use a custom GraphQL document instead of the SDK helpers).
+  - [ ] Branch UI dispatch on `userErrors[0].code === 'INSTRUMENT_PRESELECTION_FAILED'` distinct from `PAYMENT_FAILED`.
+  - [ ] (Optional) Replace any accordion-reset hack with `cartClearPaymentSelection({ cartId })` — clearer API, idempotent, single round-trip.
+
+  **Standards note**: splitting `userErrors[]` (blocking) and `warnings[]` (non-blocking) is a common e-commerce convention. The `INSTRUMENT_PRESELECTION_FAILED` semantics match retry-hint patterns used by major payment gateway SDKs (Stripe `payment_method_unavailable`, etc.).
+
+- c553c80: Payment instrument preselection — cart re-validation stale signal + headless instrument components + browser data helper.
+
+  **Why**: previously the storefront kept showing an obsolete instrument selection until the buyer clicked "pay" — only then did the gateway reject it. The signal is now **proactive**: every cart query re-validates the selection against live gateway capabilities and emits a warning when the method or instrument disappeared. Plus a set of pre-built headless React components so the instrument picker no longer requires manual `displayHint` dispatch.
+
+  **Additive (backward-compatible)**:
+  1. `Cart.warnings: [CartWarning!]!` — new field, default empty array. Computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` (code) when `selectedPaymentMethod` or `selectedPaymentInstrumentCode` no longer matches live gateway capabilities. Read-only signal — backend persistence is preserved (clear via `cartClearPaymentSelection` or a fresh `cartSelectPaymentMethod`).
+  2. `Cart.selectedPaymentMethod` re-validation — when the method disappeared from live caps the field returns `null` plus a warning with `target: 'selectedPaymentMethod'`.
+  3. `Cart.selectedPaymentInstrumentCode` re-validation — when only the instrument disappeared (method preserved), the field returns `null` plus a warning with `target: 'selectedPaymentInstrumentCode'` (method-level signal stays intact). Backend persistence is preserved — a re-select gets a fresh state.
+  4. `CartWarningCode.PAYMENT_SELECTION_STALE` — new enum value in the existing `CartWarning` envelope.
+  5. Graceful degradation — when the live capability check fails (gateway timeout / network outage), `Cart` returns the existing selection without a warning (UX continuity over freshness; `cartComplete` time-of-payment validation is the final safety net).
+  6. `<PaymentInstrumentTile>` — new pre-built headless component. Single instrument button with full ARIA contract (`role="radio"`, `aria-checked`, `aria-label`, `data-instrument-code`, `data-display-hint`, `data-selected`). Zero opinionated styling — class props per part (button, icon, label). `displayHint` is emitted as a `data-display-hint` attribute so you can style via CSS attribute selectors.
+  7. `<PaymentInstrumentSection>` — new pre-built headless component. Radio-group container with keyboard navigation (ArrowUp/Down/Left/Right wrap, Home/End jump). Renders one `<PaymentInstrumentTile>` per instrument in the order received from `availablePaymentMethods` (no client-side resort — the backend ordering is the source of truth).
+  8. `getBrowserDataForPayment()` — new helper. Collects PSD2/3DS2 browser context (`userAgent`, `language`, screen dimensions, color depth, timezone offset, IANA timezone, `javaEnabled` fallback). Browser-only — throws `BrowserDataNotAvailableError` in SSR. Forward-looking utility for future 3DS challenge flows.
+
+  **Storefront usage** — listen to the stale signal in your cart query:
+
+  ```ts
+  const { cart } = useCart(cartId);
+
+  const staleWarning = cart?.warnings?.find(
+    (w) => w.code === "PAYMENT_SELECTION_STALE",
+  );
+
+  if (staleWarning) {
+    // The backend signals that the buyer picked a method which is no longer
+    // available at the gateway — show a "pick another method" dialog.
+    // `target` distinguishes method vs instrument level:
+    if (staleWarning.target === "selectedPaymentMethod") {
+      // cart.selectedPaymentMethod === null — full re-select required
+    } else if (staleWarning.target === "selectedPaymentInstrumentCode") {
+      // cart.selectedPaymentMethod is still set, only the instrument cleared
+    }
+    // Backend persistence is preserved — `cartClearPaymentSelection` or
+    // a fresh `cartSelectPaymentMethod` is the consumer's responsibility.
+  }
+  ```
+
+  **Storefront usage** — instrument picker with pre-built components:
+
+  ```tsx
+  import { PaymentInstrumentSection } from "@doswiftly/storefront-sdk/react";
+  import { useState } from "react";
+
+  function CheckoutPaymentStep({ method }: { method: PaymentMethod }) {
+    const [instrumentCode, setInstrumentCode] = useState<string | undefined>(
+      undefined,
+    );
+
+    return (
+      <PaymentInstrumentSection
+        method={method}
+        selectedInstrumentCode={instrumentCode}
+        onSelectInstrument={(code) => {
+          setInstrumentCode(code);
+          cart.selectPaymentMethod({
+            methodType: method.type,
+            preferredProviderCode: method.preferredProvider,
+            preferredInstrumentCode: code,
+          });
+        }}
+        sectionClassName="grid grid-cols-2 gap-2"
+        tileClassName="rounded border p-3 hover:bg-gray-50 data-[selected=true]:border-blue-500"
+        labelClassName="font-semibold"
+        ariaLabel="Pick a payment instrument"
+      />
+    );
+  }
+  ```
+
+  **Storefront usage** — browser data for future 3DS flows:
+
+  ```ts
+  import { getBrowserDataForPayment, BrowserDataNotAvailableError } from '@doswiftly/storefront-sdk/react';
+
+  function handleCheckoutSubmit() {
+    try {
+      const browserData = getBrowserDataForPayment();
+      // Pass to paymentCreate input when the gateway requires a 3DS challenge
+      await cart.createPayment({ ..., browserData });
+    } catch (err) {
+      if (err instanceof BrowserDataNotAvailableError) {
+        // SSR / no DOM — skip browser data; the gateway uses its default flow
+      }
+      throw err;
+    }
+  }
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Add `warnings { message code target }` to your cart query selection set (if you use a custom GraphQL document instead of the SDK fragments — SDK fragments are updated automatically).
+  - [ ] Branch UI on `cart.warnings[].code === 'PAYMENT_SELECTION_STALE'` to show a re-prompt dialog before checkout submit.
+  - [ ] (Optional) Replace a custom instrument picker with `<PaymentInstrumentSection>` — saves boilerplate, ships full ARIA + keyboard nav out of the box.
+  - [ ] (Forward-looking) Adopt `getBrowserDataForPayment()` in checkout submit handlers when 3DS flows become relevant (currently optional — the gateway accepts an undefined `browserData`).
+
+  **Standards reference**: `PaymentInstrumentSection` follows the WAI-ARIA radiogroup pattern (https://www.w3.org/WAI/ARIA/apg/patterns/radio/). The browser data helper shape matches the EMVCo 3DS2 BrowserData specification.
+
+## 16.1.0
+
+### Minor Changes
+
+- 1e6062e: Read the gift card recipient back from the cart.
+
+  `cartUpdateGiftCardRecipient` already persisted the recipient (email, name,
+  personalised message) on a gift card line — but the `CartLine` type didn't
+  expose any field to read it. Storefronts that render the checkout server-side
+  (SSR, deep link, "back to cart" navigation) had no way to know that the buyer
+  had already filled in the recipient form on a previous visit. The recipient
+  dialog opened blank, like nothing had been saved.
+
+  **New field** — `CartLine.giftCardRecipient: GiftCardLineRecipient`
+
+  ```graphql
+  type GiftCardLineRecipient {
+    recipientEmail: String
+    recipientName: String
+    message: String
+  }
+  ```
+
+  All three fields are individually nullable so a partial set (email only, no
+  name or message) is representable as-is. The field on `CartLine` itself is
+  nullable — `null` means the buyer has not set a recipient yet, in which case
+  the gift card is delivered to the order `customerEmail` on completion.
+
+  `null` is also what you get for any non-gift-card line — there is no risk of
+  the field reporting a stale recipient from a previous line at the same index.
+
+  **Use it to seed your form**
+
+  ```tsx
+  const cart = await cartClient.get(cartId);
+  const giftLine = cart?.lines.edges.find(
+    (e) => e.node.productType === "GIFT_CARD",
+  );
+
+  <GiftRecipientForm
+    defaultValues={
+      giftLine?.node.giftCardRecipient ?? {
+        recipientEmail: "",
+        recipientName: "",
+        message: "",
+      }
+    }
+    onSubmit={(values) =>
+      cartClient.updateGiftCardRecipient(cartId, giftLine!.node.id, values)
+    }
+  />;
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. The `CartLine` fragment
+  shipped by the SDK already includes the new field after this release, so
+  upgrading immediately unlocks the read path. No client code changes required
+  to keep existing flows working.
+
+- ac2e306: Distinguish recoverable session loss from permanent cart denial.
+
+  Adds a new `CART_UNAUTHENTICATED` code to the cart error envelope. Until now,
+  both "your sign-in expired" and "this cart belongs to someone else" surfaced
+  as `CART_FORBIDDEN`, so a storefront had no way to know whether to send the
+  buyer to `/login` (recoverable) or to drop the cart cookie (permanent).
+  After the typical ~24h session TTL, the buyer would silently lose their
+  checkout state instead of being prompted to re-authenticate.
+
+  **New code** — `CART_UNAUTHENTICATED`
+
+  | Condition                                                                             | Code                         | Recovery                                                    |
+  | ------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------- |
+  | Anonymous request **or** expired/invalid session on a cart that belongs to a customer | `CART_UNAUTHENTICATED`       | Re-authenticate. Cart is preserved (`cart-id` cookie kept). |
+  | Authenticated as a **different** customer than the cart owner                         | `CART_FORBIDDEN` (unchanged) | Drop the cart cookie and start over.                        |
+
+  The cart resource itself is intact in the `CART_UNAUTHENTICATED` case — the
+  buyer's saved address, line items, discount codes, and gift cards return as
+  soon as they sign in.
+
+  **New SDK signal** — `runner.onSessionExpired(...)`
+
+  The recovery runner now exposes a separate event for session loss, distinct
+  from `onExpired` (which is for cart-resource lifecycle: cart not found, cart
+  already completed). Subscribe once at the provider level and route the buyer
+  to `/login` with a `return_to` parameter; the cart cookie stays put.
+
+  ```ts
+  // app/providers.tsx
+  const unsubExpired = runner.onExpired(() => {
+    // cart resource gone — start fresh
+    router.push("/cart/new");
+  });
+
+  const unsubSession = runner.onSessionExpired(() => {
+    // session gone, cart preserved — sign back in
+    router.push(`/login?return_to=${encodeURIComponent(location.pathname)}`);
+  });
+  ```
+
+  The session branch throws `CartSessionRequiredError` (re-exported alongside
+  `CartRecoveryNotPossibleError`) and does **not** invoke `recreateAndRun` —
+  recreating the cart on a stale session would discard the buyer's progress.
+
+  **Imperative handling**
+
+  If you handle mutation errors directly (Server Action, custom hook), add one
+  case to your existing switch:
+
+  ```ts
+  switch (err.userErrors[0]?.code) {
+    case "CART_UNAUTHENTICATED":
+      redirect(`/login?return_to=${encodeURIComponent("/checkout")}`);
+      break;
+    case "CART_FORBIDDEN":
+      cookies().delete("cart-id");
+      redirect("/cart/expired");
+      break;
+    // ...existing cases for CART_NOT_FOUND / ALREADY_COMPLETED
+  }
+  ```
+
+  **Migration**
+
+  Additive change — no rename, no signature change. Existing `case 'CART_FORBIDDEN'`
+  branches keep working as before. Opt in to the new code at your own pace; until
+  you add the case, anonymous and cross-customer denials fall into your existing
+  default branch (one will be recoverable, one will not — adding the case lets
+  you distinguish them).
+
 ## 16.0.0
 
 ### Major Changes

package/README.md

@@ -380,12 +380,13 @@ 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 by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `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`. |
 | `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. |
 | `CartComplete` | Finalizes the cart — creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (auto-generated from cartId + minute timestamp if caller omits it). Returns `order` field after completion. Note: `paymentUrl` is intentionally NOT in payload — for hosted gateways (online providers) the storefront calls a separate `paymentCreate` mutation after this returns (check `order.canCreatePayment` first). Errors: `EMAIL_REQUIRED`, `SHIPPING_ADDRESS_REQUIRED`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_REQUIRED`, `INSUFFICIENT_STOCK`, `ALREADY_COMPLETED`. |
-| `PaymentCreate` | Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`. |
+| `PaymentCreate` | Initiates a payment session for an order created by `cartComplete` — call this when `order.canCreatePayment` is `true` (orders with an offline payment method like cash-on-delivery skip this step). `orderId` is required; `returnUrl` / `cancelUrl` are optional and, when supplied, must point to a verified domain of the shop (open-redirect protected). Branch on the returned `payment.flow`: `ONLINE_REDIRECT` → redirect to `payment.redirectUrl`, `ONLINE_EMBEDDED` → render a widget with `payment.clientSecret`, `INSTANT_DIRECT` → already settled, read `payment.status`. Public, but ownership-checked — an authenticated customer cannot pay for another customer's order. **Idempotent** — calling it again for the same order returns the existing still-valid session instead of creating a duplicate (safe to retry). Rate limit: 5 requests/minute. `userErrors[].code`: `ORDER_NOT_FOUND`, `ORDER_ALREADY_PAID`, `ORDER_NOT_PAYABLE`, `PAYMENT_PROVIDER_NOT_CONFIGURED`, `RETURN_URL_INVALID`, `INVALID_ID_FORMAT`, `PAYMENT_FAILED`, `INSTRUMENT_PRESELECTION_FAILED`. `warnings[]` array zawiera `INSTRUMENT_CLEARED_FOR_RETRY` post-auto-clear instrument-specific failure (storefront retry hint: next attempt uses gateway default landing). |
+| `CartClearPaymentSelection` | Clears all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`). Rate limit: 30 requests/minute per IP+shop. |
 
 #### Return Mutations
 
@@ -508,9 +509,11 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step. |
+| `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. |
 | `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. |
 
 #### Shipments / Tracking
 

package/fragments.graphql

@@ -427,6 +427,11 @@ fragment CartLine on CartLine {
   productHandle
   productType
   requiresShipping
+  giftCardRecipient {
+    recipientEmail
+    recipientName
+    message
+  }
 }
 
 # Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored.
@@ -505,6 +510,7 @@ fragment Cart on Cart {
   selectedPaymentMethod {
     ...CartSelectedPaymentMethod
   }
+  selectedPaymentInstrumentCode
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
@@ -695,7 +701,23 @@ fragment ShopConfigFields on Shop {
 # Payment Methods
 # ============================================
 
-# Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step.
+# 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.
+fragment PaymentMethodInstrument on PaymentMethodInstrument {
+  providerCode
+  instrumentCode
+  type
+  displayName
+  displayHint
+  brandImageUrl
+  enabled
+}
+
+# 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.
 fragment PaymentMethod on PaymentMethod {
   id
   name
@@ -706,6 +728,13 @@ fragment PaymentMethod on PaymentMethod {
   isDefault
   supportedCurrencies
   position
+  providersAvailable
+  preferredProvider
+  available
+  unavailableReason
+  instruments {
+    ...PaymentMethodInstrument
+  }
 }
 
 # Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query.
@@ -730,6 +759,13 @@ fragment PaymentSession on PaymentSession {
   expiresAt
 }
 
+# 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.
+fragment PaymentWarning on PaymentWarning {
+  message
+  code
+  retryHint
+}
+
 # ============================================
 # Discount Code Validation
 # ============================================