@doswiftly/storefront-operations 19.2.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.2.0
+- **Schema version**: 20.0.0
 - **Queries**: 52
-- **Mutations**: 41
+- **Mutations**: 44
 - **Fragments**: 104
 <!-- AUTOGEN:STATS:END -->
 

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # 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

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. |

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **19.2.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!`

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.2.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",

package/package.json

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

package/schema.graphql

@@ -1201,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
 
@@ -1365,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`.
   """
@@ -1412,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).
 """
@@ -1574,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"""
@@ -1583,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."""
@@ -4067,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.
   """