@doswiftly/storefront-operations 19.1.0 → 20.0.0

package/AGENTS.md

@@ -27,9 +27,9 @@ 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**: 19.1.0
+- **Schema version**: 20.0.0
 - **Queries**: 52
-- **Mutations**: 41
+- **Mutations**: 44
 - **Fragments**: 104
 <!-- AUTOGEN:STATS:END -->
 

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # Changelog
 
+## 20.0.0
+
+### Major Changes
+
+- 486afc8: Cart access is now capability-based: a cart is reached with its id **and** a one-time secret instead of being tied to the signed-in customer. This fixes two long-standing cart bugs — a guest inheriting a previous visitor's cart id getting "cart not found", and a signed-in buyer being told to sign in again on their own cart — and aligns the cart contract with the industry norm.
+
+  **Why**: the `cart-id` cookie outlives the auth session and is shared across tabs and workers, so gating cart writes on the customer made carts brittle. The cart token is now a bearer capability; the customer link is enrichment only. There are no more "unauthenticated"/"forbidden" cart errors — a missing or expired cart, or a missing or wrong secret, returns a single `CART_NOT_FOUND`, which the SDK already auto-recovers from by creating a fresh cart.
+
+  **The SDK handles the secret for you.** `useCartManager`, the browser cart cookie store, and the client/server middleware read and persist it automatically. The breaking points below matter only if you read the `cart-id` cookie yourself, run server-side cart reads, or built on the removed session-error path.
+
+  **Breaking**
+  1. **Composite cart cookie.** The `cart-id` cookie value is now `"<cartId>.<secret>"`. If you read it directly (for example in a Server Component), parse it with the new `parseCartCookieValue()` / `readCartCredentials()` instead of treating the raw value as the cart id. A legacy plain-id cookie still parses (with `cartSecret: null`) and degrades to a fresh cart on the next write.
+  2. **Server-side cart reads must forward the secret.** SSR / edge cart reads now need the secret header or they come back empty. Add `serverCartSecretMiddleware(await readCartCredentials())` to your server client middleware (next to your currency / language middleware).
+  3. **The cart session-error path is removed.** `CART_UNAUTHENTICATED` no longer exists in the contract, and with it the recovery runner's `onSessionExpired` listener, the `CartSessionRequiredError` class, the `isCartSessionError` predicate and the `CART_SESSION_ERROR_CODES` constant. If you handled a "cart needs sign-in" signal, remove it — a stale or unreachable cart now flows through the normal `CART_NOT_FOUND` recovery you already have. (The auth-level session refresh — `sessionRetryMiddleware`, `useSessionExpired`, `createSessionExpiredEmitter` — is unchanged; it handles the customer token, not the cart.)
+  4. **`ensureCart` shape.** A custom `ensureCart` passed to `createCartRecoveryRunner` must now return `{ cart, secret }` (the create outcome) rather than just the cart, so the runner can persist the secret.
+
+  **New**
+  - `CartClient.create()` now returns the one-time `secret` alongside the cart.
+  - `CartClient.merge(guestCartId)` — on login, fold the customer's prior cart into the guest cart (quantities sum per variant, guest checkout fields win, the guest cart id and secret are kept so the stored cookie stays valid). Requires an authenticated request.
+  - `CartClient.downgradeOnLogout(cartId)` — on logout, clear the customer link, contact details, addresses and saved-payment selection while keeping items, coupons, shipping method, currency, notes and the secret. `useLogout` now calls this automatically before signing out, so customer details do not linger in the cart on a shared device.
+  - `CartClient.recoveryRedeem(token)` — redeem a signed cart-recovery link; the cart secret is rotated and the new one is revealed once (persist it into the cookie).
+  - `cartSecretMiddleware`, `serverCartSecretMiddleware`, `readCartCredentials`, `parseCartCookieValue`, `formatCartCookieValue` and the `CartCredentials` type for working with the secret directly.
+
+### Patch Changes
+
+- 17f4832: Two cart-cookie robustness fixes for capability-based carts:
+  - **A malformed `cart-id` cookie no longer breaks the GraphQL client.** A corrupt cookie value (for example a stray `%` left by another tool, or a hand-crafted bad value) made `getCookie` throw while reading the cart secret on every request, taking down the whole request pipeline for that browser until the cookie was cleared. The cookie is now treated as absent when it can't be decoded, so a fresh cart is created as intended.
+  - **A server-known cart seed can now carry the cart secret.** When you seed a cart id from the server (via `useCartManager({ initialCartId })`, `<CartManagerProvider initialCartId>`, or `createCartRecoveryRunner({ initialCartId })`), you can pass the composite `"<cartId>.<secret>"` value — the same value stored in the `cart-id` cookie — instead of a bare id. The seed is persisted as a composite cookie so reads and writes send the secret and reach the seeded cart. This unblocks magic-link checkout, embedded-iframe, customer-service "view this cart", and server-side dev-seed flows where the cart id is known up front.
+
+  Migration: no changes required for existing code. A bare-id seed keeps its previous behaviour (it degrades to a fresh cart on the first write, since the secret is required to reach an existing cart). To make a seeded cart reachable, read the raw `cart-id` cookie server-side and pass it through unchanged, or build the value with `formatCartCookieValue({ cartId, cartSecret })`.
+
+- 933492b: Deprecate the `createCartStore` cart-state system in favour of `useCartManager`.
+
+  `createCartStore` — and its `CartProvider` / `useCartStore` / `useCartStoreApi`
+  helpers — predate capability-based carts: the store does not carry the cart secret,
+  so mutations against a capability cart fail. These exports are now marked
+  `@deprecated` and will be removed in a future major release.
+
+  Migration: switch to `useCartManager` (React), which manages the cart secret, the
+  `cart-id` cookie, and stale-cart recovery automatically and exposes the full cart +
+  checkout lifecycle. For a framework-agnostic core, use `createCartRecoveryRunner`.
+  No runtime behaviour changes in this release — the deprecation only adds IDE hints.
+
+- 486afc8: `Order` now actually returns the `discountAllocations` breakdown it documents. The per-code discount allocations were added to the order contract previously, but the SDK's `Order` selection did not request the field, so it always came back empty. The order confirmation page can now render the same per-code discount rows the buyer saw on the cart.
+
+## 19.2.0
+
+### Minor Changes
+
+- b60dcaf: Discount codes now report real per-code applicability and reasons on the cart and order.
+
+  **Why**: a recognised discount code previously always showed `isApplicable: true` even when it
+  reduced nothing — minimum-order not met, code expired, or no cart items within the code's product
+  scope — and `discountAllocations` only ever reflected the first code. The contract now tells the
+  truth per code, so a storefront can show the buyer exactly which codes apply and why the others do
+  not, and the order carries the same breakdown the buyer saw in the cart.
+
+  **Additive (backward-compatible)**:
+  1. `Cart.discountCodes[].isApplicable` is computed per code — `true` only when the code reduces the
+     price or grants free shipping — instead of being hard-coded to `true`.
+  2. `Cart.discountAllocations` contains one entry per applicable code, not just the first.
+  3. `cartDiscountCodesUpdate` returns a `warning` per non-applicable code
+     (`CartWarningCode.DISCOUNT_CODE_NOT_APPLICABLE`) whose localized message explains the reason. The
+     code stays on the cart, so adding a qualifying product can still activate it.
+  4. New `DiscountErrorCode.NOT_APPLICABLE_TO_CART` — the code is valid but no cart items fall within
+     its product/collection/category scope.
+  5. New `Order.discountAllocations` — the per-code breakdown frozen onto the order at checkout
+     (parity with `Cart.discountAllocations`), so a confirmation page renders the same rows.
+  6. `cartValidateDiscountCode` (the read-only preview) now mirrors the apply result: a code that is
+     recognised but out of scope for the cart returns `isValid: false` with
+     `error.code: NOT_APPLICABLE_TO_CART`. Inline "is this code valid?" feedback no longer reports a code
+     as valid when applying it would reduce nothing — preview and apply always agree.
+
+  **Usage example**:
+
+  ```ts
+  const { cart, warnings } = await cartDiscountCodesUpdate({
+    id,
+    discountCodes: ["SUMMER20"],
+  });
+
+  for (const entry of cart.discountCodes) {
+    if (!entry.isApplicable) {
+      // The code is recognised but not reducing the price — explain why.
+      const reason = warnings.find((w) => w.target === entry.code)?.message;
+      showInlineHint(entry.code, reason);
+    }
+  }
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] If you render a discount chip, branch on `discountCodes[].isApplicable` instead of assuming the code applied.
+  - [ ] Surface `cartDiscountCodesUpdate.warnings` (code `DISCOUNT_CODE_NOT_APPLICABLE`) next to the chip to tell the buyer why a code is inactive.
+  - [ ] Sum `discountAllocations[].amount` to display a per-code discount breakdown; it equals the cart/order discount total.
+  - [ ] Optionally read `Order.discountAllocations` on the confirmation page for the same breakdown after checkout.
+  - [ ] If you preview codes with `cartValidateDiscountCode`, handle `isValid: false` + `NOT_APPLICABLE_TO_CART` — don't show "valid" for a scope-mismatch code (the preview now matches what apply returns).
+
+- d7b0185: Add `pickupConfig` to `AvailableShippingMethod` — render carrier pickup-point pickers at checkout
+
+  Shipping methods that deliver to a pickup point (`deliveryType` `LOCKER` or `PICKUP_POINT`) now expose a `pickupConfig` object with everything the storefront needs to let the buyer choose a collection point:
+  - `selectionMode: WIDGET` — render the carrier map widget. `widgetToken` (a public, domain-scoped browser token, e.g. the InPost Geowidget token — never a carrier API secret) and `scriptUrl` (the widget script to load) are provided.
+  - `selectionMode: SEARCH` — no browser widget; look points up server-side and render your own list. `widgetToken` and `scriptUrl` are `null` for this mode.
+
+  `pickupConfig` is `null` for `HOME` (street-address) delivery and when the merchant has not yet configured the carrier's public widget token — do not render a map in that case. The `AvailableShippingMethod` fragment now includes `pickupConfig`, so queries that spread it pick the new field up automatically once you regenerate your types.
+
+  Flow: render the picker from `pickupConfig`, then send the chosen point with `cartSetShippingAddress({ pickupPoint })` before `cartSelectShippingMethod` — the latter rejects a pickup method selected without a point (`PICKUP_POINT_REQUIRED`).
+
+- 88cd617: Expose pickup-point configuration on shipping methods, so a storefront can render the carrier point picker directly from the cart's available shipping methods.
+
+  `availableShippingMethods` now returns a `pickupConfig` for methods whose `deliveryType` is `PICKUP_POINT` or `LOCKER`:
+  - `provider` — carrier code the config belongs to (e.g. `"inpost"`).
+  - `selectionMode` — `WIDGET` (render the carrier map) or `SEARCH` (query points server-side and render your own list).
+  - `widgetToken` — public, domain-scoped widget token (e.g. the InPost Geowidget token) used to initialise the map. **Never** a carrier API secret. Null in `SEARCH` mode and when the merchant has not configured the public token.
+  - `scriptUrl` — CDN URL of the carrier widget script to load before rendering the map. Null in `SEARCH` mode.
+
+  `pickupConfig` is `null` for `HOME` delivery methods.
+
+  **Additive (backward-compatible)** — existing code that does not read `pickupConfig` keeps working unchanged.
+
 ## 19.1.0
 
 ### Minor Changes

package/README.md

@@ -333,12 +333,15 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `CartCreate` | Creates a new cart and optionally pre-populates it with line items. Cart ID is a UUID stored by the SDK in the `cart-id` cookie (30-day TTL); the cart itself expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path. |
+| `CartCreate` | Creates a new cart and optionally pre-populates it with line items. Returns a one-time `secret` (the cart access capability) alongside the cart — the SDK persists it in the `cart-id` cookie and sends it as the `x-cart-secret` header on later cart operations; a direct API caller must store it immediately, as it cannot be retrieved again. The cart ID is a UUID; the cart expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path. |
 | `CartAddLines` | Adds line items to a cart. Each line is `{ merchandiseId, quantity, attributes?, attributeSelections? }`. If the same variant + identical attributes are added twice, quantities merge into one row instead of duplicating. Validates stock (`INSUFFICIENT_STOCK`) and configurator attributes (`ATTRIBUTE_REQUIRED`, `ATTRIBUTE_OPTION_INVALID`). Triggers cart re-pricing including discount recalculation. |
 | `CartUpdateLines` | Updates quantity and/or attributes of existing cart lines by `id`. Setting `quantity: 0` auto-deletes the line. Passing `attributes: []` clears them; omitting the field preserves existing values. Re-validates stock and re-prices the cart after each update. |
 | `CartRemoveLines` | Removes specific lines from cart by `lineIds[]`. Internally delegates to `cartUpdateLines` with `quantity: 0` — both endpoints are functionally equivalent; this one exists for API ergonomics when intent is explicit removal. Triggers cart re-pricing. |
 | `CartDiscountCodesUpdate` | Replaces (NOT appends) the cart's discount codes with the given list. Pass `[]` to clear all codes. Each code is validated against the discounts table (existence, active status); invalid codes appear in `userErrors[]` as `DISCOUNT_CODE_INVALID`. Triggers cart re-pricing — discount allocations are recomputed and stored in `cart.discountAmount`. Single canonical replace-all entry point — prior append/single-remove variants were removed in favor of this explicit caller-controlled list semantics. |
-| `CartUpdateBuyerIdentity` | Associates a customer with the cart. Despite the input shape accepting `email`, `phone`, `countryCode`, `languageCode`, only `customerId` is currently persisted — other fields are silently ignored. Does NOT trigger tax / shipping recalculation; pure cart-to-customer linking. Use during login or guest-to-account upgrade. |
+| `CartUpdateBuyerIdentity` | Set the buyer's email and phone on the cart (guest checkout contact details). The cart is bound to a customer automatically from the authenticated session — there is no `customerId` input, so a guest cannot claim another shopper's account. Sign in and the cart attaches to that customer (re-binding overwrites, last-write-wins); the `customerId` is then readable on `cart.buyerIdentity`. Use during guest checkout to capture contact info and after login to attach the buyer. Does not trigger tax / shipping recalculation. |
+| `CartMerge` | Merge a guest cart into the signed-in customer's existing cart right after login. Pass the guest cart id; its secret travels in the cart credential header and the customer is taken from the authenticated session (never the client). Line quantities are summed per variant, the buyer's in-session checkout fields win, and the prior customer cart is discarded. The returned cart keeps the SAME id and secret as the guest cart, so the stored cart-id stays valid — no cookie re-issue. Requires authentication (returns `CART_MERGE_REQUIRES_AUTH` otherwise) and refuses carts held in different currencies (`CART_CURRENCY_MISMATCH`). |
+| `CartDowngradeOnLogout` | Downgrade a cart to guest on logout. Pass the cart id (its secret travels in the cart credential header). Clears the customer association, contact details, addresses and payment selection, but keeps line items, discount codes, the selected shipping method, currency and notes. The cart id and secret are unchanged (no rotation), so the stored cart-id stays valid and the buyer keeps their items as a guest. Call from the logout flow before tearing down the auth session so the next person on a shared device sees none of the previous buyer's data. Gated by the cart secret only (no auth) — a missing/wrong secret returns `CART_NOT_FOUND`. |
+| `CartRecoveryRedeem` | Redeem a signed cart recovery link (from an abandoned-cart email). Pass the token taken from the link's query parameter. On success the cart is recovered (made active again) and its access secret is ROTATED — the NEW secret is returned once in `secret` (persist it immediately; the previous secret stops working), and the SDK sets the cart-id cookie to the recovered cart. Buyer self-service: the merchant only sends the link, never takes over the cart. A bad link returns `CART_RECOVERY_LINK_EXPIRED` or `CART_RECOVERY_LINK_INVALID` without exposing any cart content; `CART_NOT_FOUND` if the cart no longer exists. |
 | `CartUpdateNote` | Sets a free-text note on the cart (gift message, special instructions). Pass empty string to clear. Stored on the `Cart` row, propagated to the `Order` at checkout completion, visible to merchant in admin. |
 
 #### Customer Auth Mutations
@@ -380,7 +383,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 `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`. |
+| `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`. |
 | `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. |
@@ -550,7 +553,7 @@ full executable body of each operation.
 | `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. |
+| `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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step. |
 
 #### Attribute Filters
 

package/fragments.graphql

@@ -339,6 +339,12 @@ fragment Order on Order {
     ...MailingAddress
   }
   itemCount
+  discountAllocations {
+    discountCode
+    amount {
+      ...Money
+    }
+  }
   canCreatePayment
   paymentMethodType
 }
@@ -1016,12 +1022,18 @@ fragment FreeShippingProgress on FreeShippingProgress {
   message
 }
 
-# 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.
+# 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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step.
 fragment AvailableShippingMethod on AvailableShippingMethod {
   id
   name
   description
   deliveryType
+  pickupConfig {
+    provider
+    selectionMode
+    widgetToken
+    scriptUrl
+  }
   carrier {
     ...ShippingCarrier
   }

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **19.1.0**
-> 52 queries · 41 mutations · 104 fragments
+> Schema version: **20.0.0**
+> 52 queries · 44 mutations · 104 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -1385,7 +1385,7 @@ query Location($id: ID!) {
 
 **Section**: Cart Mutations
 
-**Description**: Creates a new cart and optionally pre-populates it with line items. Cart ID is a UUID stored by the SDK in the `cart-id` cookie (30-day TTL); the cart itself expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.
+**Description**: Creates a new cart and optionally pre-populates it with line items. Returns a one-time `secret` (the cart access capability) alongside the cart — the SDK persists it in the `cart-id` cookie and sends it as the `x-cart-secret` header on later cart operations; a direct API caller must store it immediately, as it cannot be retrieved again. The cart ID is a UUID; the cart expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.
 
 **Variables**:
 - `$input`: `CartCreateInput`
@@ -1399,6 +1399,7 @@ mutation CartCreate($input: CartCreateInput) {
     cart {
       ...Cart
     }
+    secret
     userErrors {
       ...UserError
     }
@@ -1529,7 +1530,7 @@ mutation CartDiscountCodesUpdate($id: ID!, $discountCodes: [String!]!) {
 
 **Section**: Cart Mutations
 
-**Description**: Associates a customer with the cart. Despite the input shape accepting `email`, `phone`, `countryCode`, `languageCode`, only `customerId` is currently persisted — other fields are silently ignored. Does NOT trigger tax / shipping recalculation; pure cart-to-customer linking. Use during login or guest-to-account upgrade.
+**Description**: Set the buyer's email and phone on the cart (guest checkout contact details). The cart is bound to a customer automatically from the authenticated session — there is no `customerId` input, so a guest cannot claim another shopper's account. Sign in and the cart attaches to that customer (re-binding overwrites, last-write-wins); the `customerId` is then readable on `cart.buyerIdentity`. Use during guest checkout to capture contact info and after login to attach the buyer. Does not trigger tax / shipping recalculation.
 
 **Variables**:
 - `$id`: `ID!`
@@ -1554,6 +1555,91 @@ mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInpu
 }
 ```
 
+### Mutation: `CartMerge`
+
+**Section**: Cart Mutations
+
+**Description**: Merge a guest cart into the signed-in customer's existing cart right after login. Pass the guest cart id; its secret travels in the cart credential header and the customer is taken from the authenticated session (never the client). Line quantities are summed per variant, the buyer's in-session checkout fields win, and the prior customer cart is discarded. The returned cart keeps the SAME id and secret as the guest cart, so the stored cart-id stays valid — no cookie re-issue. Requires authentication (returns `CART_MERGE_REQUIRES_AUTH` otherwise) and refuses carts held in different currencies (`CART_CURRENCY_MISMATCH`).
+
+**Variables**:
+- `$guestCartId`: `ID!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartMerge($guestCartId: ID!) {
+  cartMerge(guestCartId: $guestCartId) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartDowngradeOnLogout`
+
+**Section**: Cart Mutations
+
+**Description**: Downgrade a cart to guest on logout. Pass the cart id (its secret travels in the cart credential header). Clears the customer association, contact details, addresses and payment selection, but keeps line items, discount codes, the selected shipping method, currency and notes. The cart id and secret are unchanged (no rotation), so the stored cart-id stays valid and the buyer keeps their items as a guest. Call from the logout flow before tearing down the auth session so the next person on a shared device sees none of the previous buyer's data. Gated by the cart secret only (no auth) — a missing/wrong secret returns `CART_NOT_FOUND`.
+
+**Variables**:
+- `$cartId`: `ID!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartDowngradeOnLogout($cartId: ID!) {
+  cartDowngradeOnLogout(cartId: $cartId) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
+### Mutation: `CartRecoveryRedeem`
+
+**Section**: Cart Mutations
+
+**Description**: Redeem a signed cart recovery link (from an abandoned-cart email). Pass the token taken from the link's query parameter. On success the cart is recovered (made active again) and its access secret is ROTATED — the NEW secret is returned once in `secret` (persist it immediately; the previous secret stops working), and the SDK sets the cart-id cookie to the recovered cart. Buyer self-service: the merchant only sends the link, never takes over the cart. A bad link returns `CART_RECOVERY_LINK_EXPIRED` or `CART_RECOVERY_LINK_INVALID` without exposing any cart content; `CART_NOT_FOUND` if the cart no longer exists.
+
+**Variables**:
+- `$token`: `String!`
+
+**Fragments used**: `Cart`, `CartWarning`, `UserError`
+
+**GraphQL**:
+```graphql
+mutation CartRecoveryRedeem($token: String!) {
+  cartRecoveryRedeem(token: $token) {
+    cart {
+      ...Cart
+    }
+    secret
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+```
+
 ### Mutation: `CartUpdateNote`
 
 **Section**: Cart Mutations
@@ -1975,7 +2061,7 @@ mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
 
 **Section**: Cart Completion Mutations
 
-**Description**: 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`.
+**Description**: 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`.
 
 **Variables**:
 - `$input`: `CartSelectPaymentMethodInput!`
@@ -2961,6 +3047,12 @@ fragment Order on Order {
     ...MailingAddress
   }
   itemCount
+  discountAllocations {
+    discountCode
+    amount {
+      ...Money
+    }
+  }
   canCreatePayment
   paymentMethodType
 }
@@ -3982,7 +4074,7 @@ fragment FreeShippingProgress on FreeShippingProgress {
 
 **Section**: Shipping Methods
 
-**Description**: 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.
+**Description**: 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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step.
 
 **Uses fragments**: `DeliveryEstimate`, `FreeShippingProgress`, `Money`, `ShippingCarrier`
 
@@ -3993,6 +4085,12 @@ fragment AvailableShippingMethod on AvailableShippingMethod {
   name
   description
   deliveryType
+  pickupConfig {
+    provider
+    selectionMode
+    widgetToken
+    scriptUrl
+  }
   carrier {
     ...ShippingCarrier
   }

package/mutations.graphql

@@ -7,12 +7,13 @@
 # Cart Mutations
 # ============================================
 
-# Creates a new cart and optionally pre-populates it with line items. Cart ID is a UUID stored by the SDK in the `cart-id` cookie (30-day TTL); the cart itself expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.
+# Creates a new cart and optionally pre-populates it with line items. Returns a one-time `secret` (the cart access capability) alongside the cart — the SDK persists it in the `cart-id` cookie and sends it as the `x-cart-secret` header on later cart operations; a direct API caller must store it immediately, as it cannot be retrieved again. The cart ID is a UUID; the cart expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.
 mutation CartCreate($input: CartCreateInput) {
   cartCreate(input: $input) {
     cart {
       ...Cart
     }
+    secret
     userErrors {
       ...UserError
     }
@@ -82,7 +83,7 @@ mutation CartDiscountCodesUpdate($id: ID!, $discountCodes: [String!]!) {
   }
 }
 
-# Associates a customer with the cart. Despite the input shape accepting `email`, `phone`, `countryCode`, `languageCode`, only `customerId` is currently persisted — other fields are silently ignored. Does NOT trigger tax / shipping recalculation; pure cart-to-customer linking. Use during login or guest-to-account upgrade.
+# Set the buyer's email and phone on the cart (guest checkout contact details). The cart is bound to a customer automatically from the authenticated session — there is no `customerId` input, so a guest cannot claim another shopper's account. Sign in and the cart attaches to that customer (re-binding overwrites, last-write-wins); the `customerId` is then readable on `cart.buyerIdentity`. Use during guest checkout to capture contact info and after login to attach the buyer. Does not trigger tax / shipping recalculation.
 mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
   cartUpdateBuyerIdentity(id: $id, buyerIdentity: $buyerIdentity) {
     cart {
@@ -97,6 +98,52 @@ mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInpu
   }
 }
 
+# Merge a guest cart into the signed-in customer's existing cart right after login. Pass the guest cart id; its secret travels in the cart credential header and the customer is taken from the authenticated session (never the client). Line quantities are summed per variant, the buyer's in-session checkout fields win, and the prior customer cart is discarded. The returned cart keeps the SAME id and secret as the guest cart, so the stored cart-id stays valid — no cookie re-issue. Requires authentication (returns `CART_MERGE_REQUIRES_AUTH` otherwise) and refuses carts held in different currencies (`CART_CURRENCY_MISMATCH`).
+mutation CartMerge($guestCartId: ID!) {
+  cartMerge(guestCartId: $guestCartId) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+
+# Downgrade a cart to guest on logout. Pass the cart id (its secret travels in the cart credential header). Clears the customer association, contact details, addresses and payment selection, but keeps line items, discount codes, the selected shipping method, currency and notes. The cart id and secret are unchanged (no rotation), so the stored cart-id stays valid and the buyer keeps their items as a guest. Call from the logout flow before tearing down the auth session so the next person on a shared device sees none of the previous buyer's data. Gated by the cart secret only (no auth) — a missing/wrong secret returns `CART_NOT_FOUND`.
+mutation CartDowngradeOnLogout($cartId: ID!) {
+  cartDowngradeOnLogout(cartId: $cartId) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+
+# Redeem a signed cart recovery link (from an abandoned-cart email). Pass the token taken from the link's query parameter. On success the cart is recovered (made active again) and its access secret is ROTATED — the NEW secret is returned once in `secret` (persist it immediately; the previous secret stops working), and the SDK sets the cart-id cookie to the recovered cart. Buyer self-service: the merchant only sends the link, never takes over the cart. A bad link returns `CART_RECOVERY_LINK_EXPIRED` or `CART_RECOVERY_LINK_INVALID` without exposing any cart content; `CART_NOT_FOUND` if the cart no longer exists.
+mutation CartRecoveryRedeem($token: String!) {
+  cartRecoveryRedeem(token: $token) {
+    cart {
+      ...Cart
+    }
+    secret
+    userErrors {
+      ...UserError
+    }
+    warnings {
+      ...CartWarning
+    }
+  }
+}
+
 # Sets a free-text note on the cart (gift message, special instructions). Pass empty string to clear. Stored on the `Cart` row, propagated to the `Order` at checkout completion, visible to merchant in admin.
 mutation CartUpdateNote($id: ID!, $note: String!) {
   cartUpdateNote(id: $id, note: $note) {
@@ -333,7 +380,7 @@ mutation CartSelectShippingMethod($input: CartSelectShippingMethodInput!) {
 # 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`.
+# Errors: `PAYMENT_METHOD_REQUIRED`, `CART_NOT_FOUND`.
 mutation CartSelectPaymentMethod($input: CartSelectPaymentMethodInput!) {
   cartSelectPaymentMethod(input: $input) {
     cart {

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "19.1.0",
+  "schemaVersion": "20.0.0",
   "queries": [
     {
       "name": "Shop",
@@ -1079,7 +1079,7 @@
       "name": "CartCreate",
       "kind": "mutation",
       "section": "Cart Mutations",
-      "description": "Creates a new cart and optionally pre-populates it with line items. Cart ID is a UUID stored by the SDK in the `cart-id` cookie (30-day TTL); the cart itself expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.",
+      "description": "Creates a new cart and optionally pre-populates it with line items. Returns a one-time `secret` (the cart access capability) alongside the cart — the SDK persists it in the `cart-id` cookie and sends it as the `x-cart-secret` header on later cart operations; a direct API caller must store it immediately, as it cannot be retrieved again. The cart ID is a UUID; the cart expires server-side after 72 hours of inactivity. The `warnings` field is reserved for non-blocking issues — current implementation returns it empty in this path.",
       "variables": [
         {
           "name": "input",
@@ -1092,7 +1092,7 @@
         "CartWarning",
         "UserError"
       ],
-      "body": "mutation CartCreate($input: CartCreateInput) {\n  cartCreate(input: $input) {\n    cart {\n      ...Cart\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
+      "body": "mutation CartCreate($input: CartCreateInput) {\n  cartCreate(input: $input) {\n    cart {\n      ...Cart\n    }\n    secret\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
     },
     {
       "name": "CartAddLines",
@@ -1194,7 +1194,7 @@
       "name": "CartUpdateBuyerIdentity",
       "kind": "mutation",
       "section": "Cart Mutations",
-      "description": "Associates a customer with the cart. Despite the input shape accepting `email`, `phone`, `countryCode`, `languageCode`, only `customerId` is currently persisted — other fields are silently ignored. Does NOT trigger tax / shipping recalculation; pure cart-to-customer linking. Use during login or guest-to-account upgrade.",
+      "description": "Set the buyer's email and phone on the cart (guest checkout contact details). The cart is bound to a customer automatically from the authenticated session — there is no `customerId` input, so a guest cannot claim another shopper's account. Sign in and the cart attaches to that customer (re-binding overwrites, last-write-wins); the `customerId` is then readable on `cart.buyerIdentity`. Use during guest checkout to capture contact info and after login to attach the buyer. Does not trigger tax / shipping recalculation.",
       "variables": [
         {
           "name": "id",
@@ -1214,6 +1214,63 @@
       ],
       "body": "mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInput!) {\n  cartUpdateBuyerIdentity(id: $id, buyerIdentity: $buyerIdentity) {\n    cart {\n      ...Cart\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
     },
+    {
+      "name": "CartMerge",
+      "kind": "mutation",
+      "section": "Cart Mutations",
+      "description": "Merge a guest cart into the signed-in customer's existing cart right after login. Pass the guest cart id; its secret travels in the cart credential header and the customer is taken from the authenticated session (never the client). Line quantities are summed per variant, the buyer's in-session checkout fields win, and the prior customer cart is discarded. The returned cart keeps the SAME id and secret as the guest cart, so the stored cart-id stays valid — no cookie re-issue. Requires authentication (returns `CART_MERGE_REQUIRES_AUTH` otherwise) and refuses carts held in different currencies (`CART_CURRENCY_MISMATCH`).",
+      "variables": [
+        {
+          "name": "guestCartId",
+          "type": "ID!",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "Cart",
+        "CartWarning",
+        "UserError"
+      ],
+      "body": "mutation CartMerge($guestCartId: ID!) {\n  cartMerge(guestCartId: $guestCartId) {\n    cart {\n      ...Cart\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
+    },
+    {
+      "name": "CartDowngradeOnLogout",
+      "kind": "mutation",
+      "section": "Cart Mutations",
+      "description": "Downgrade a cart to guest on logout. Pass the cart id (its secret travels in the cart credential header). Clears the customer association, contact details, addresses and payment selection, but keeps line items, discount codes, the selected shipping method, currency and notes. The cart id and secret are unchanged (no rotation), so the stored cart-id stays valid and the buyer keeps their items as a guest. Call from the logout flow before tearing down the auth session so the next person on a shared device sees none of the previous buyer's data. Gated by the cart secret only (no auth) — a missing/wrong secret returns `CART_NOT_FOUND`.",
+      "variables": [
+        {
+          "name": "cartId",
+          "type": "ID!",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "Cart",
+        "CartWarning",
+        "UserError"
+      ],
+      "body": "mutation CartDowngradeOnLogout($cartId: ID!) {\n  cartDowngradeOnLogout(cartId: $cartId) {\n    cart {\n      ...Cart\n    }\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
+    },
+    {
+      "name": "CartRecoveryRedeem",
+      "kind": "mutation",
+      "section": "Cart Mutations",
+      "description": "Redeem a signed cart recovery link (from an abandoned-cart email). Pass the token taken from the link's query parameter. On success the cart is recovered (made active again) and its access secret is ROTATED — the NEW secret is returned once in `secret` (persist it immediately; the previous secret stops working), and the SDK sets the cart-id cookie to the recovered cart. Buyer self-service: the merchant only sends the link, never takes over the cart. A bad link returns `CART_RECOVERY_LINK_EXPIRED` or `CART_RECOVERY_LINK_INVALID` without exposing any cart content; `CART_NOT_FOUND` if the cart no longer exists.",
+      "variables": [
+        {
+          "name": "token",
+          "type": "String!",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "Cart",
+        "CartWarning",
+        "UserError"
+      ],
+      "body": "mutation CartRecoveryRedeem($token: String!) {\n  cartRecoveryRedeem(token: $token) {\n    cart {\n      ...Cart\n    }\n    secret\n    userErrors {\n      ...UserError\n    }\n    warnings {\n      ...CartWarning\n    }\n  }\n}"
+    },
     {
       "name": "CartUpdateNote",
       "kind": "mutation",
@@ -1518,7 +1575,7 @@
       "name": "CartSelectPaymentMethod",
       "kind": "mutation",
       "section": "Cart Completion Mutations",
-      "description": "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`.",
+      "description": "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`.",
       "variables": [
         {
           "name": "input",
@@ -2096,7 +2153,7 @@
         "MailingAddress",
         "Money"
       ],
-      "body": "fragment Order on Order {\n  id\n  orderNumber\n  accessToken\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  canCreatePayment\n  paymentMethodType\n}",
+      "body": "fragment Order on Order {\n  id\n  orderNumber\n  accessToken\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  discountAllocations {\n    discountCode\n    amount {\n      ...Money\n    }\n  }\n  canCreatePayment\n  paymentMethodType\n}",
       "onType": "Order"
     },
     {
@@ -2597,7 +2654,7 @@
       "name": "AvailableShippingMethod",
       "kind": "fragment",
       "section": "Shipping Methods",
-      "description": "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.",
+      "description": "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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step.",
       "variables": [],
       "fragmentRefs": [
         "DeliveryEstimate",
@@ -2605,7 +2662,7 @@
         "Money",
         "ShippingCarrier"
       ],
-      "body": "fragment AvailableShippingMethod on AvailableShippingMethod {\n  id\n  name\n  description\n  deliveryType\n  carrier {\n    ...ShippingCarrier\n  }\n  price {\n    ...Money\n  }\n  isFree\n  estimatedDelivery {\n    ...DeliveryEstimate\n  }\n  freeShippingProgress {\n    ...FreeShippingProgress\n  }\n  sortOrder\n}",
+      "body": "fragment AvailableShippingMethod on AvailableShippingMethod {\n  id\n  name\n  description\n  deliveryType\n  pickupConfig {\n    provider\n    selectionMode\n    widgetToken\n    scriptUrl\n  }\n  carrier {\n    ...ShippingCarrier\n  }\n  price {\n    ...Money\n  }\n  isFree\n  estimatedDelivery {\n    ...DeliveryEstimate\n  }\n  freeShippingProgress {\n    ...FreeShippingProgress\n  }\n  sortOrder\n}",
       "onType": "AvailableShippingMethod"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "19.1.0",
+  "version": "20.0.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/schema.graphql

@@ -453,6 +453,11 @@ type AvailableShippingMethod {
   """Display name of the method (e.g. "DPD Standard")."""
   name: String!
 
+  """
+  Pickup-point selection config — present only for pickup methods (deliveryType LOCKER / PICKUP_POINT) whose carrier exposes a public pickup mechanism. Null for HOME delivery and when the merchant has not configured the carrier's public widget token. Carries only browser-safe data (e.g. the InPost Geowidget public token), never the carrier API secret.
+  """
+  pickupConfig: ShippingPickupConfig
+
   """
   Cost of the method for the current cart (in the buyer preferred currency).
   """
@@ -1196,11 +1201,6 @@ input CartBuyerIdentityInput {
   """
   countryCode: CountryCode
 
-  """
-  ID of a signed-in customer that owns this cart. Pass to bind a guest cart to a customer record.
-  """
-  customerId: ID
-
   """Buyer email address. Persisted to the order at checkout completion."""
   email: String
 
@@ -1360,6 +1360,11 @@ type CartCreatePayload {
   """The created cart on success; null when `userErrors` is non-empty."""
   cart: Cart
 
+  """
+  One-time cart access secret, returned only here on creation. The SDK persists it for you; if you call the API directly, store it immediately — it cannot be retrieved again.
+  """
+  secret: String
+
   """
   Business / validation errors. Each entry carries a stable `code` (e.g. `CART_NOT_FOUND`, `NOT_ENOUGH_IN_STOCK`, `INVALID_MERCHANDISE_LINE`) — branch on `code`, never on `message`.
   """
@@ -1407,6 +1412,22 @@ type CartDiscountCodesUpdatePayload {
   warnings: [CartWarning!]!
 }
 
+"""Result of `cartDowngradeOnLogout`."""
+type CartDowngradeOnLogoutPayload {
+  """
+  The downgraded cart on success — same id and secret (no rotation), with the customer association, contact details, addresses and payment selection cleared but line items kept. Null when `userErrors` is non-empty.
+  """
+  cart: Cart
+
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code` (e.g. `CART_NOT_FOUND`).
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal advisories — the mutation itself succeeded."""
+  warnings: [CartWarning!]!
+}
+
 """
 A single line item in the cart — one variant, a quantity and the data attached to it (cost, attributes, configurator selections).
 """
@@ -1569,6 +1590,22 @@ input CartLineUpdateInput {
   quantity: Int!
 }
 
+"""Result of `cartMerge`."""
+type CartMergePayload {
+  """
+  The merged cart on success — it keeps the same id and secret as the guest cart passed in, so the stored cart-id cookie stays valid. Null when `userErrors` is non-empty.
+  """
+  cart: Cart
+
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code` — e.g. `CART_NOT_FOUND`, `CART_CURRENCY_MISMATCH`, `CART_MERGE_REQUIRES_AUTH`.
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal advisories — the mutation itself succeeded."""
+  warnings: [CartWarning!]!
+}
+
 """Recommendations based on cart contents"""
 type CartRecommendations {
   """Products frequently bought together with cart items"""
@@ -1578,6 +1615,27 @@ type CartRecommendations {
   youMayAlsoLike: [ProductRecommendation!]!
 }
 
+"""Result of `cartRecoveryRedeem`."""
+type CartRecoveryRedeemPayload {
+  """
+  The recovered cart on success. Null when `userErrors` is non-empty (invalid / expired link).
+  """
+  cart: Cart
+
+  """
+  The NEW cart access secret, returned only here on a successful redemption (the link rotates the secret). Persist it immediately — it cannot be retrieved again; the previous secret no longer works.
+  """
+  secret: String
+
+  """
+  Business / validation errors carrying a stable `CartErrorCode` in `code` — `CART_RECOVERY_LINK_EXPIRED` / `CART_RECOVERY_LINK_INVALID` (bad or expired link), `CART_NOT_FOUND` (the cart is gone or already completed — create a fresh one) or `CART_RECOVERY_REDEEM_FAILED` (unexpected failure). No cart content is exposed on failure.
+  """
+  userErrors: [UserError!]!
+
+  """Non-fatal advisories — the mutation itself succeeded."""
+  warnings: [CartWarning!]!
+}
+
 """Input for `cartRemoveGiftCard`."""
 input CartRemoveGiftCardInput {
   """ID of the cart to update."""
@@ -1882,6 +1940,7 @@ type CartWarning {
 Stable, machine-readable codes for non-fatal cart warnings. The mutation succeeded; the storefront can surface a toast or stay silent based on the code.
 """
 enum CartWarningCode {
+  DISCOUNT_CODE_NOT_APPLICABLE
   MERCHANDISE_NOT_AVAILABLE
   MERCHANDISE_NOT_ENOUGH_STOCK
   PAYMENTS_AMOUNT_REGION_MISMATCH
@@ -2893,6 +2952,7 @@ enum DiscountErrorCode {
   INACTIVE
   MINIMUM_ORDER_NOT_MET
   MINIMUM_QUANTITY_NOT_MET
+  NOT_APPLICABLE_TO_CART
   NOT_FOUND
   NOT_STARTED
   SHOP_NOT_FOUND
@@ -4060,6 +4120,30 @@ type Mutation {
     id: ID!
   ): CartDiscountCodesUpdatePayload!
 
+  """
+  Downgrade a cart to guest on logout — clears the customer association, contact details, addresses and payment selection, but keeps the line items, discount codes, selected shipping method, currency and notes. The cart id and secret are unchanged (no rotation), so the stored cart-id stays valid and the buyer keeps their items as a guest. Call from the logout flow (with the cart secret) before tearing down the auth session; the next person on a shared device then sees none of the previous buyer's data.
+  """
+  cartDowngradeOnLogout(
+    """UUID of the cart to downgrade to guest."""
+    cartId: ID!
+  ): CartDowngradeOnLogoutPayload!
+
+  """
+  Merge a guest cart into the signed-in customer's existing cart on login. Call right after authenticating, passing the guest cart id (its secret travels in the cart credential header). Line quantities are summed per variant and the buyer's in-session checkout fields win. The returned cart keeps the SAME id and secret as the guest cart, so the stored cart-id stays valid. Requires authentication (`CART_MERGE_REQUIRES_AUTH` otherwise); refuses carts in different currencies (`CART_CURRENCY_MISMATCH`).
+  """
+  cartMerge(
+    """UUID of the guest cart to merge from and keep (the survivor)."""
+    guestCartId: ID!
+  ): CartMergePayload!
+
+  """
+  Redeem a signed cart recovery link (from an abandoned-cart email). Pass the token from the link; on success the cart is recovered and its access secret is ROTATED — the NEW secret is returned once in `secret` (persist it; the previous one no longer works), and the SDK sets the cart-id cookie to the recovered cart. Buyer self-service: the merchant sends the link, never takes over the cart. Returns `CART_RECOVERY_LINK_EXPIRED` / `CART_RECOVERY_LINK_INVALID` for a bad link (no cart content is exposed) and `CART_NOT_FOUND` when the cart no longer exists.
+  """
+  cartRecoveryRedeem(
+    """The signed recovery token taken from the recovery link."""
+    token: String!
+  ): CartRecoveryRedeemPayload!
+
   """
   Remove a previously applied gift card from the cart by its `CartAppliedGiftCard.id`. The storefront never has to handle the full gift card code on the client.
   """
@@ -4430,6 +4514,11 @@ type Order implements Node {
   """
   confirmedAt: DateTime
 
+  """
+  Per-code discount allocations on the order (parity with `Cart.discountAllocations`). One entry per code that reduced the price; empty when no discount applied. The sum of `amount` equals the order-level discount.
+  """
+  discountAllocations: [OrderDiscountAllocation!]!
+
   """
   When the order expired (e.g. pending payment timed out). Null when not expired.
   """
@@ -4515,6 +4604,17 @@ type OrderConnection {
   totalCount: Int!
 }
 
+"""
+Per-code discount applied to an order. Mirrors a cart discount allocation; the sum across allocations equals the order-level discount.
+"""
+type OrderDiscountAllocation {
+  """Amount discounted by this code on the order, in the order currency."""
+  amount: Money!
+
+  """The discount code that produced this allocation."""
+  discountCode: String!
+}
+
 """Order edge for pagination"""
 type OrderEdge {
   """Cursor"""
@@ -5032,6 +5132,21 @@ input PickupPointInput {
   provider: String!
 }
 
+"""
+How the buyer selects a pickup point for a shipping method that requires one.
+"""
+enum PickupSelectionMode {
+  """
+  No browser widget — query points server-side (by city / postal code) and render your own list. `widgetToken` / `scriptUrl` are null for this mode.
+  """
+  SEARCH
+
+  """
+  Render the carrier map widget (e.g. InPost Geowidget) initialised with `pickupConfig.widgetToken` + `pickupConfig.scriptUrl`. The buyer picks a point on the map.
+  """
+  WIDGET
+}
+
 """Points estimate for an order"""
 type PointsEstimate {
   """Base points to earn"""
@@ -6911,6 +7026,31 @@ type ShippingCarrier {
   serviceCode: String
 }
 
+"""
+Pickup-point selection config for a shipping method whose `deliveryType` is LOCKER or PICKUP_POINT. Contains ONLY public, browser-safe data — for InPost this is the domain-scoped Geowidget token, never the ShipX API secret. Use it to render the carrier map (`selectionMode = WIDGET`) or to drive a server-side point search (`selectionMode = SEARCH`).
+"""
+type ShippingPickupConfig {
+  """
+  Carrier code this config belongs to (e.g. "inpost"). Matches `carrier.serviceCode`'s provider.
+  """
+  provider: String!
+
+  """
+  CDN URL of the carrier widget script to load before rendering the map. Null for SEARCH mode.
+  """
+  scriptUrl: String
+
+  """
+  How to let the buyer pick a point — WIDGET (carrier map) or SEARCH (server-side point lookup).
+  """
+  selectionMode: PickupSelectionMode!
+
+  """
+  PUBLIC widget token used to initialise the carrier map (InPost Geowidget domain-scoped token). Never the carrier API secret. Null for SEARCH mode and when the merchant has not configured the public token (do not render the map — offer SEARCH or hide the method).
+  """
+  widgetToken: String
+}
+
 """Shop information"""
 type Shop {
   """Shop physical address"""