@doswiftly/storefront-operations 9.1.0 → 10.0.0

package/AGENTS.md

@@ -27,10 +27,10 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 9.1.0
+- **Schema version**: 10.0.0
 - **Queries**: 48
-- **Mutations**: 44
-- **Fragments**: 104
+- **Mutations**: 39
+- **Fragments**: 99
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # Changelog
 
+## 10.0.0
+
+### Major Changes
+
+- fcd4c75: Cart GraphQL surface rebuild — Phase 3 Cluster 2 of cart unification.
+
+  **Breaking changes**:
+  - **`cartApplyDiscountCodes` mutation renamed to `cartDiscountCodesUpdate`**. Semantyka pozostaje replace-all (overwrite całej listy discount codes). Migration: change mutation name in your GraphQL queries; arguments + return shape unchanged. Operation name w typed client (`CartApplyDiscountCodes` → `CartDiscountCodesUpdate`).
+  - **`CartApplyDiscountCodesPayload` payload type renamed to `CartDiscountCodesUpdatePayload`**. Schema name + TypeScript type reference both renamed.
+
+  **New mutations** (additive, non-breaking — opt-in for new functionality):
+  - `cartSetShippingAddress(input: CartSetShippingAddressInput): CartSetShippingAddressPayload` — ustaw adres dostawy na koszyku.
+  - `cartSetBillingAddress(input: CartSetBillingAddressInput): CartSetBillingAddressPayload` — ustaw adres do faktury (jeśli różny od shipping).
+  - `cartSelectShippingMethod(input: CartSelectShippingMethodInput): CartSelectShippingMethodPayload` — wybierz metodę wysyłki; argument `shippingMethodId: ID!` (typed UUID, NIE String).
+  - `cartSelectPaymentMethod(input: CartSelectPaymentMethodInput): CartSelectPaymentMethodPayload` — wybierz integration payment provider.
+  - `cartApplyGiftCard(input: CartApplyGiftCardInput): CartApplyGiftCardPayload` — apply gift card code.
+  - `cartRemoveGiftCard(input: CartRemoveGiftCardInput): CartRemoveGiftCardPayload` — remove applied gift card.
+  - `cartUpdateGiftCardRecipient(input: CartUpdateGiftCardRecipientInput): CartUpdateGiftCardRecipientPayload` — set recipient info for a gift card line item (personalised delivery).
+  - `cartComplete(input: CartCompleteInput): CartCompletePayload` — finalize cart → create Order. Returns `{ cart, order, userErrors, warnings }`. Bez `paymentUrl` w response — wywołaj `order(id: ...)` query po `cartComplete` żeby pobrać `canCreatePayment` + `paymentMethodType` signals (cart aware payment provider selection).
+
+  **Extended types**:
+  - `Cart` object dostaje 7 nowych pól reprezentujących cart completion state:
+    - `email: String`
+    - `phone: String`
+    - `shippingAddress: MailingAddress`
+    - `billingAddress: MailingAddress`
+    - `selectedShippingMethod: CartShippingMethod` — typed jako nowy ObjectType `CartShippingMethod` (handle, title, price).
+    - `selectedPaymentMethod: PaymentMethod`
+    - `appliedGiftCards: [CartAppliedGiftCard!]!` — non-null array (empty `[]` gdy zero gift cards applied).
+  - `CartCreateInput` dostaje opcjonalne pola `email: String` + `shippingAddress: CartAddressInput` — pozwala utworzyć cart z initial fulfillment context w jednym round-trip (zamiast cartCreate → cartUpdateBuyerIdentity → cartSetShippingAddress fanout).
+  - `cartUpdateBuyerIdentity` mutation now persists `email` + `phone` fields (previously these were silently ignored — only `customerId` was persisted to the cart). Migration: jeśli storefront wysyła email/phone w `buyerIdentity` input, te wartości będą teraz trwale zapisane.
+
+  **New error codes** w `CartErrorCode` enum:
+  - `SHIPPING_ADDRESS_REQUIRED` — emit przez `cartComplete` gdy adres dostawy nie ustawiony.
+  - `SHIPPING_METHOD_REQUIRED` — emit przez `cartComplete` lub `cartSelectShippingMethod` gdy metoda wymagana.
+  - `PAYMENT_METHOD_REQUIRED` — emit przez `cartComplete` lub `cartSelectPaymentMethod`.
+  - `EMAIL_REQUIRED` — emit przez `cartComplete` gdy email nie ustawiony.
+  - `INVALID_ADDRESS` — emit przez address mutations dla nieprawidłowego adresu.
+  - `GIFT_CARD_NOT_FOUND` / `GIFT_CARD_DEPLETED` / `GIFT_CARD_UNUSABLE` — emit przez gift card mutations.
+
+  **Migration guide**:
+
+  Update GraphQL queries w storefront:
+
+  ```diff
+  - mutation CartApplyDiscountCodes($id: ID!, $discountCodes: [String!]!) {
+  -   cartApplyDiscountCodes(id: $id, discountCodes: $discountCodes) {
+  + mutation CartDiscountCodesUpdate($id: ID!, $discountCodes: [String!]!) {
+  +   cartDiscountCodesUpdate(id: $id, discountCodes: $discountCodes) {
+       cart { ...Cart }
+       userErrors { ...UserError }
+       warnings { ...CartWarning }
+     }
+   }
+  ```
+
+  SDK methods: regenerate typed-document via `pnpm codegen` po update do nowej wersji `@doswiftly/storefront-operations` — `CartApplyDiscountCodesDocument` zostanie zastąpiony `CartDiscountCodesUpdateDocument`. Jeśli używasz typed React hooks, sygnatury hook stays the same (`useCartDiscountCodesUpdateMutation`).
+
+### Minor Changes
+
+- 95a24d3: Cart and customer operations realigned with the backend GraphQL contract + non-blocking `warnings` surface + richer type exports.
+
+  **`@doswiftly/storefront-operations`** — additive:
+  - `fragment Order` now includes `canCreatePayment: Boolean!` and `paymentMethodType: PaymentMethodType!`. After `cartComplete`, the storefront can read these directly from the resulting `Order` (instead of branching on hard-coded provider names) to decide whether to call `paymentCreate` or render a "complete on delivery" message.
+
+  **`@doswiftly/storefront-sdk`** — breaking, action required:
+
+  Cart mutation names, arguments, and result shapes are now aligned with the published GraphQL contract. Previous names worked against an older backend snapshot; the package now ships GraphQL documents the live API actually accepts.
+  - Cart line mutations renamed: `cartLinesAdd` → `cartAddLines`, `cartLinesUpdate` → `cartUpdateLines`, `cartLinesRemove` → `cartRemoveLines`.
+  - Cart attribute mutations renamed: `cartNoteUpdate` → `cartUpdateNote`, `cartBuyerIdentityUpdate` → `cartUpdateBuyerIdentity`.
+  - Cart mutation argument `cartId` renamed to `id` on six mutations: `cartAddLines`, `cartUpdateLines`, `cartRemoveLines`, `cartDiscountCodesUpdate`, `cartUpdateNote`, `cartUpdateBuyerIdentity`. (Phase 3 lifecycle mutations and `cartComplete` keep their typed `*Input!` argument unchanged.)
+  - All 16 cart mutations now return `warnings: [CartWarning!]!` (non-blocking advisory hints — e.g. low stock, partial availability). `CartClient` methods return `{ cart, warnings }` instead of `Cart`; storefronts can render `warnings` as soft notices without aborting the flow. `cartComplete` returns `{ cart, order, warnings }`.
+  - `useCartManager()` React hook methods (`addItem`, `updateItem`, `removeItem`, `updateDiscountCodes`, `updateNote`) now return `CartMutationOutcome` (`{ cart, warnings }`) to match the underlying `CartClient`.
+  - `cartComplete` now requests the full `Order` fragment (with `canCreatePayment` + `paymentMethodType`) — the prior local `OrderMinimal` fragment is removed. The exported `Order` type now mirrors the full fragment shape (`totals`, lifecycle timestamps, `shippingAddress`).
+  - `Customer` type fields match the GraphQL schema: `emailVerified` → `isEmailVerified`, `emailMarketingState` → `emailMarketing`, `ordersCount` → `orderCount`. Customer's `defaultAddress` now includes the computed `name` field.
+  - `CustomerCreateInput` exposes `phone`, `acceptsMarketing`, and `marketingOptInLevel` (`'SINGLE_OPT_IN' | 'CONFIRMED_OPT_IN'`) so signup forms can collect marketing consent without dropping to raw GraphQL.
+  - New types exported from the package root: `CartWarning`, `Order`, `PaymentMethodType`, `CartMutationOutcome`, `CartCompleteOutcome`, all Phase 3 cart-completion input types (`CartAddressInput`, `CartSetShippingAddressInput`, `CartSetBillingAddressInput`, `CartSelectShippingMethodInput`, `CartSelectPaymentMethodInput`, `CartApplyGiftCardInput`, `CartRemoveGiftCardInput`, `CartUpdateGiftCardRecipientInput`, `CartCompleteInput`), and discount-validation types (`DiscountValidationResult`, `DiscountInfo`, `DiscountValidationError`, `DiscountErrorCode`, `DiscountApplicationType`).
+  - `CartBuyerIdentityInput` exposes optional `languageCode` (ISO 639-1, e.g. `'PL'`) to match the backend input shape.
+
+  **Migration**
+
+  ```ts
+  // Before
+  const cart = await cartClient.addItems(cartId, [{ variantId, quantity: 1 }]);
+  //      ^^^^ Cart
+
+  // After
+  const { cart, warnings } = await cartClient.addItems(cartId, [
+    { variantId, quantity: 1 },
+  ]);
+  for (const w of warnings) console.warn(`[${w.code}] ${w.message}`);
+  ```
+
+  If you were writing raw GraphQL operations rather than using `CartClient`, update mutation names and the `cartId` → `id` argument as above, and add a `warnings { message code target }` selection to each cart mutation.
+
+  If you read `customer.emailVerified` / `customer.emailMarketingState` / `customer.ordersCount` anywhere, rename to `isEmailVerified` / `emailMarketing` / `orderCount` respectively.
+
+- ff246df: `PaymentMethodType` trimmed to the categories the API actually returns today.
+
+  `APPLE_PAY`, `GOOGLE_PAY`, and `PAYPAL` were placeholders for wallet providers that aren't deployed yet — they could never appear in a real response. They are removed from `PaymentMethodType` (both as a GraphQL enum value and as a SDK union member). The enum is now `'CARD' | 'BLIK' | 'BANK_TRANSFER' | 'CASH_ON_DELIVERY' | 'OTHER'`.
+
+  **Migration**
+
+  If your storefront branches on these values (`if (order.paymentMethodType === 'APPLE_PAY') { … }`), those branches were dead code — remove them. When wallet providers ship, the corresponding type values will be reintroduced alongside their implementation.
+
+  Unrecognized providers continue to fall through to `OTHER` — your default fallback path is unchanged.
+
+- 270249e: CartClient extension — Phase 6 unify-cart-graphql-surface (additive over major changes from Phase 3 Cluster 2).
+
+  **9 new CartClient methods**:
+  - `cartClient.setShippingAddress(input)` — set shipping address on cart.
+  - `cartClient.setBillingAddress(input)` — set billing address.
+  - `cartClient.selectShippingMethod(input)` — Decision D8 typed `shippingMethodId: ID!`.
+  - `cartClient.selectPaymentMethod(input)` — select integration payment provider.
+  - `cartClient.applyGiftCard(input)` — stackable gift card application (FIFO consumption).
+  - `cartClient.removeGiftCard(input)` — remove applied gift card.
+  - `cartClient.updateGiftCardRecipient(input)` — set recipient info on gift card line item (personalised delivery — required przed `complete` dla gift card SKU).
+  - `cartClient.complete(input)` — finalize cart → Order (returns `{ cart, order }`). Idempotent on `idempotencyKey`. No `paymentUrl` (Decision D4) — caller wywoła osobną mutation if online payment needed.
+  - `cartClient.validateDiscountCode(cartId, code)` — Query (Decision D3 read-only preview). Returns `{ isValid, discount?, error? }`. NIE modifies cart state.
+
+  **Extended SDK types**:
+
+  `Cart` interface extends z fulfillment + payment + gift card fields:
+
+  ```diff
+   interface Cart {
+     id: string;
+     // ... existing fields ...
+  +  email: string | null;
+  +  phone: string | null;
+  +  shippingAddress: MailingAddress | null;
+  +  billingAddress: MailingAddress | null;
+  +  selectedShippingMethod: CartShippingMethod | null;
+  +  selectedPaymentMethod: CartSelectedPaymentMethod | null;
+  +  appliedGiftCards: CartAppliedGiftCard[];
+   }
+  ```
+
+  `CartCreateInput` extends z `email?: string` + `shippingAddress?: CartAddressInput` (Phase 3 Task 3.2 — initial fulfillment context w jednym round-trip).
+
+  New types exported z `@doswiftly/storefront-sdk`:
+  - `MailingAddress`, `CartAddressInput`, `CartShippingMethod`, `CartAppliedGiftCard`, `CartSelectedPaymentMethod`, `PaymentMethodType`
+  - Input types: `CartSetShippingAddressInput`, `CartSetBillingAddressInput`, `CartSelectShippingMethodInput`, `CartSelectPaymentMethodInput`, `CartApplyGiftCardInput`, `CartRemoveGiftCardInput`, `CartUpdateGiftCardRecipientInput`, `CartCompleteInput`
+  - `Order` (minimal shape z `canCreatePayment` + `paymentMethodType` ResolveFields — Phase 4 capability signal)
+  - `DiscountValidationResult`, `DiscountInfo`, `DiscountValidationError`, `DiscountErrorCode`, `DiscountApplicationType`
+
+  **New GraphQL operations** (`@doswiftly/storefront-sdk/operations/cart`):
+
+  8 mutations + 1 Query — `CART_SET_SHIPPING_ADDRESS`, `CART_SET_BILLING_ADDRESS`, `CART_SELECT_SHIPPING_METHOD`, `CART_SELECT_PAYMENT_METHOD`, `CART_APPLY_GIFT_CARD`, `CART_REMOVE_GIFT_CARD`, `CART_UPDATE_GIFT_CARD_RECIPIENT`, `CART_COMPLETE`, `CART_VALIDATE_DISCOUNT_CODE`. Wszystkie inline fragments — zero codegen w SDK.
+
+  **Caching guidance dla `validateDiscountCode`**:
+
+  Read-only Query — możesz cache'ować z TanStack Query lub fetch wrapper. Recommendation: `fetchPolicy: 'network-only'` lub cache key zawierający `cart.subtotal` (discount eligibility może zależeć od minimum order amount).
+
+  **Note for `complete()`**:
+
+  Method zwraca `{ cart, order: Order | null }`. `order.canCreatePayment` signals czy storefront może zainicjować online płatność (false dla COD/manual/bank_transfer/PAID/CANCELLED — pokaż instrukcję manualną; true dla PayU/Stripe online flow — wywołaj `paymentCreate`). `order.paymentMethodType` daje payment category (CARD/BLIK/BANK_TRANSFER/CASH_ON_DELIVERY/PAYPAL/APPLE_PAY/GOOGLE_PAY/OTHER) dla UI iconography.
+
+  **Linked storefront-operations bump**: minor `version-sync, no code change` per linked rule (Phase 3 Cluster 2 + Cluster 3 już dodały wszystkie operations w backend SSOT i synced storefront-operations npm).
+
 ## 9.1.0
 
 ### Minor Changes

package/README.md

@@ -202,11 +202,11 @@ full executable body of each operation.
 | `CustomerProfile` | Lightweight customer profile (no orders, no addresses list). Use for settings / profile pages that only need basic customer info — much cheaper than `Customer`. Returns null if unauthenticated. |
 | `CustomerOrder` | Single order by `orderId`. Returns only orders that belong to the authenticated customer (cross-customer access returns null, not an error). Much cheaper than fetching the full `Customer` payload to access one order. Use on the order detail page. |
 
-#### Checkout
+#### Discount Code Validation
 
 | Operation | Description |
 | --- | --- |
-| `Checkout` | Fetches a checkout session by `id`. **Important**: `checkoutId` and `cartId` are 1:1 — there is no separate "checkout" record, the response is built dynamically from the cart. Returns line items, addresses, selected shipping rate, available shipping rates + payment methods, applied discount/gift cards (gift card codes are masked for security), and totals (`cost`, `tax`, `paymentDue`). Public read; ownership enforced on mutations. Refetch after every checkout mutation. |
+| `CartValidateDiscountCode` | Read-only validation of a discount code against an existing cart — does NOT modify cart state. Returns `{ isValid, discount, error }` (`DiscountValidationResult`) for previewing the effect of a code (inline UI feedback as the user types, before they commit to applying via `cartDiscountCodesUpdate`). Validates: discount existence + active status + customer eligibility + minimum order amount + minimum quantity met. Errors: `NOT_FOUND`, `INACTIVE`, `NOT_STARTED`, `EXPIRED`, `USAGE_LIMIT_REACHED`, `CUSTOMER_USAGE_LIMIT_REACHED`, `CUSTOMER_NOT_ELIGIBLE`, `MINIMUM_ORDER_NOT_MET`, `MINIMUM_QUANTITY_NOT_MET`. |
 
 #### Payment Methods
 
@@ -333,7 +333,7 @@ full executable body of each operation.
 | `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. |
-| `CartApplyDiscountCodes` | Replaces (NOT appends) the cart's discount codes with the given list. Pass `[]` to clear all codes. Each code is validated against `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`. |
+| `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. |
 | `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. |
 
@@ -369,28 +369,18 @@ full executable body of each operation.
 | `CustomerActivate` | Activates a newly-created account using the 64-hex activation token from the welcome email + a chosen password. Token TTL is 24h, single-use (atomically marked `used_at`). On success: sets `email_verified=true`, transitions status `INACTIVE`→`ACTIVE`, returns a fresh JWT for auto-login. Rate-limited. |
 | `CustomerResetPassword` | Resets the password using the 64-hex reset token from the password-reset email. Token TTL is 1h, single-use (atomically marked `used_at`). On success: updates the password hash and returns a fresh JWT for auto-login (no second login step needed). Rate-limited. |
 
-#### Checkout Mutations
+#### Cart Completion Mutations
 
 | Operation | Description |
 | --- | --- |
-| `CheckoutCreate` | Creates a new checkout session for the given cart (or a fresh cart if `cartId` is omitted). Inherits applied discounts and gift cards from the cart by reference (not snapshot). Errors: `CART_NOT_FOUND`, `EMPTY_CART`, `ALREADY_COMPLETED` (cart already converted to order). NOT idempotent — multiple calls create multiple checkouts. |
-| `CheckoutUpdateShippingAddress` | Sets the shipping address (full replace, not patch). Triggers cart re-pricing. Address format is NOT validated here — full validation runs at `checkoutComplete`. |
-| `CheckoutUpdateBillingAddress` | Sets the billing address (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". |
-| `CheckoutUpdateEmail` | Sets or updates the contact email on the checkout (used for guest checkout, order confirmation, and tracking emails). Validated against a regex; returns `INVALID` for malformed format. |
-| `CheckoutSelectShippingRate` | Selects a shipping method by `rateId` (a stable shipping-method UUID, NOT an opaque per-request token). The id comes from `availableShippingMethods` query, computed for the current address + cart subtotal at request time. |
-| `CheckoutApplyDiscountCode` | Appends a discount code to the cart's `discount_codes` array. Note: while multiple codes can be stored, the pricing engine currently uses **only the first applied code** — codes do not stack. Validated for existence, active status, and customer usage limits. |
-| `CheckoutRemoveDiscountCode` | Removes a code from the cart's `discount_codes` array (filters by exact match). Triggers re-pricing. |
-| `CheckoutValidateDiscountCode` | READ-ONLY validation of a discount code against the current checkout — does NOT modify state. Returns `{ isValid, discount, error }` for previewing the effect (e.g. inline UI feedback as the user types). |
-| `CheckoutSelectPaymentMethod` | Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence and active status; no pre-authorization is performed here. |
-| `CheckoutComplete` | Finalizes the checkout: creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (NOT on the checkout `id`); auto-generated if the caller omits it. The `paymentUrl` field is reserved but is NOT populated here — for hosted gateways (PayU, P24) the storefront calls a separate `paymentCreate` mutation after this returns. |
-
-#### Gift Card Checkout Mutations
-
-| Operation | Description |
-| --- | --- |
-| `CheckoutApplyGiftCard` | 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 `checkoutComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`, `GIFT_CARD_ALREADY_APPLIED`. |
-| `CheckoutRemoveGiftCard` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `checkoutComplete`, removing before completion has no effect on the underlying gift card balance. |
-| `CheckoutUpdateGiftCardRecipient` | Sets per-line-item recipient details (name, email, message, delivery date) for digital gift card products in the cart (variants with `type: GIFT_CARD`). Required before `checkoutComplete` for any line item with a gift-card variant. Recipient details are associated with each gift-card line item and propagated to the resulting order. |
+| `CartSetShippingAddress` | Phase 3 unify-cart-graphql-surface: wszystkie fulfillment + payment + completion operations teraz na Cart aggregate (zamiast Checkout dual-aggregate). Klient robi typowy checkout flow: cart create/add items → setShipping/Billing/Method → selectPayment → (optional) applyGiftCard → cartComplete → Order created. Sets the shipping address on the cart (full replace, not patch). Triggers cart re-pricing (tax recalculation per address country/region). Address format validated against `CartAddressInput` constraints (firstName/lastName/streetLine1/city/country/postalCode required). Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
+| `CartSetBillingAddress` | Sets the billing address on the cart (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". Errors: `INVALID_ADDRESS`, `CART_NOT_FOUND`. |
+| `CartSelectShippingMethod` | Selects a shipping method by `shippingMethodId` (typed `ID!`, a stable shipping-method UUID — NOT a per-request token). The id comes from a list of methods available for the current address + cart subtotal (queryable separately). Errors: `SHIPPING_METHOD_REQUIRED`, `ZIP_CODE_NOT_SUPPORTED`, `CART_NOT_FOUND`. |
+| `CartSelectPaymentMethod` | Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence + active status; no pre-authorization performed here. Errors: `PAYMENT_METHOD_REQUIRED`, `INVALID_PAYMENT`, `CART_NOT_FOUND`. |
+| `CartApplyGiftCard` | Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically at `cartComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`. |
+| `CartRemoveGiftCard` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `cartComplete`, removing before completion has no effect on the underlying gift card balance. |
+| `CartUpdateGiftCardRecipient` | Sets per-line-item recipient details (name, email, message) for digital gift card products in the cart (line items where the variant represents a gift-card SKU). Required before `cartComplete` for any line item with a gift-card variant. Recipient details propagated to the resulting order. |
+| `CartComplete` | Finalizes the cart — creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (auto-generated from cartId + minute timestamp if caller omits it). Returns `order` field after completion. Note: `paymentUrl` is intentionally NOT in payload — for hosted gateways (online providers) the storefront calls a separate `paymentCreate` mutation after this returns (check `order.canCreatePayment` first). Errors: `EMAIL_REQUIRED`, `SHIPPING_ADDRESS_REQUIRED`, `SHIPPING_METHOD_REQUIRED`, `PAYMENT_METHOD_REQUIRED`, `INSUFFICIENT_STOCK`, `ALREADY_COMPLETED`. |
 
 #### Return Mutations
 
@@ -475,7 +465,7 @@ full executable body of each operation.
 | `MailingAddress` | `MailingAddress` | Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Spread on the address book UI and order summaries. |
 | `CustomerAccessToken` | `CustomerAccessToken` | Customer access token returned by `customerLogin` / `customerSignup` / `customerActivate` / `customerResetPassword` / `customerRefreshToken`. The token's JWT TTL is 24h; cookie max-age is 30d. |
 | `Customer` | `Customer` | Customer profile — basic info plus B2B fields (`taxId`, `vatNumber`, `regon`, `companyName`), default address, lifetime stats (`orderCount`, `totalSpent`), marketing preferences. Use on profile / settings pages. |
-| `Order` | `Order` | Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps. Spread on the order list and order detail pages. Line items are not included here. |
+| `Order` | `Order` | Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps, plus payment capability signal (`canCreatePayment` + `paymentMethodType`) the storefront uses to decide post-completion payment flow without hard-coded provider checks. Spread on the order list, order detail, and the `cartComplete` mutation result. Line items are not included here. |
 
 #### Cart
 
@@ -488,7 +478,10 @@ full executable body of each operation.
 | `CartBuyerIdentity` | `CartBuyerIdentity` | Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored. |
 | `CartDiscountCode` | `CartDiscountCode` | Discount code applied to the cart with its `isApplicable` flag — false means the code was kept on the cart but does not currently qualify (e.g. minimum spend not reached). |
 | `CartDiscountAllocation` | `CartDiscountAllocation` | Allocation of a discount code to the cart total — pairs the code with the actual money discounted. Use to show "saved X with code Y" in cart UI. |
-| `Cart` | `Cart` | Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes. Spread on the cart drawer / cart page; refetch after every cart mutation. |
+| `Cart` | `Cart` | Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes, plus fulfillment fields (email/phone/addresses/shipping method/payment method/applied gift cards). Spread on the cart drawer / cart page; refetch after every cart mutation including completion lifecycle. |
+| `CartShippingMethod` | `CartShippingMethod` | Shipping method selected on a cart (D8 term unification — wcześniej ShippingRate). Returned przez `cart.selectedShippingMethod` po `cartSelectShippingMethod` mutation. |
+| `CartAppliedGiftCard` | `CartAppliedGiftCard` | Gift card applied to a cart — masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`. |
+| `CartSelectedPaymentMethod` | `PaymentMethod` | Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon, description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display. |
 
 #### Shop
 
@@ -511,19 +504,6 @@ full executable body of each operation.
 | `PaymentMethod` | `PaymentMethod` | Single payment method enabled for the shop — type (CARD / BANK_TRANSFER / BLIK / PAYPAL / APPLE_PAY / GOOGLE_PAY / CASH_ON_DELIVERY / OTHER), provider, icon, supported currencies, default flag, sort position. Spread on the checkout payment step. |
 | `AvailablePaymentMethods` | `AvailablePaymentMethods` | Active payment methods list with the merchant's `defaultMethod`. Returned by the `availablePaymentMethods` query. |
 
-#### Checkout
-
-| Fragment | On Type | Description |
-| --- | --- | --- |
-| `ShippingRate` | `ShippingRate` | Single shipping rate option — `handle` is the stable id you pass to `checkoutSelectShippingRate` as `rateId`, plus title and price. |
-| `TaxLine` | `TaxLine` | One tax line on the checkout — title, rate (decimal, e.g. 0.23 for 23%), computed amount. Spread on the order summary. |
-| `DiscountAffectedItem` | `DiscountAffectedItem` | Item affected by a discount — the discounted product/variant with original + discounted prices and savings. Used on Buy-X-Get-Y promotions to highlight which items the discount applies to. |
-| `DiscountApplication` | `DiscountApplication` | A discount currently applied to the checkout — code, type, value, plus BXGY (Buy X Get Y) metadata when applicable (`buyQuantity`, `getQuantity`, `getDiscountPercent`, `affectedItems`). Use to render a "Discounts applied" panel. |
-| `DiscountCode` | `DiscountCode` | Lightweight discount code entry on the checkout — code + applicability flag. |
-| `CheckoutLineItem` | `CheckoutLineItem` | Single line item in the checkout — variant snapshot, quantity, unit + total prices, image. Use on the order summary panel. |
-| `AppliedGiftCard` | `AppliedGiftCard` | Gift card applied to the checkout — `maskedCode` (first + last 4 chars), `lastCharacters` (for display matching), the amount applied to this checkout, and remaining balance after this order would complete. |
-| `Checkout` | `Checkout` | Full checkout shape — line items, shipping + billing addresses, selected + available shipping rates, available payment methods, applied discounts + gift cards, tax lines, totals (`cost`, `paymentDue`, `totalGiftCardAmount`). Spread on the checkout flow; refetch after every checkout mutation. `isReady` flips to true when the checkout has all required fields to call `checkoutComplete`. |
-
 #### Shipments / Tracking
 
 | Fragment | On Type | Description |

package/fragments.graphql

@@ -256,6 +256,7 @@ fragment MailingAddress on MailingAddress {
   countryCode
   firstName
   lastName
+  name
   phone
   state
   stateCode
@@ -296,7 +297,7 @@ fragment Customer on Customer {
   updatedAt
 }
 
-# Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps. Spread on the order list and order detail pages. Line items are not included here.
+# Order summary — number, totals (cost / tax / shipping), payment + fulfillment status, shipping address, item count, lifecycle timestamps, plus payment capability signal (`canCreatePayment` + `paymentMethodType`) the storefront uses to decide post-completion payment flow without hard-coded provider checks. Spread on the order list, order detail, and the `cartComplete` mutation result. Line items are not included here.
 fragment Order on Order {
   id
   orderNumber
@@ -325,6 +326,8 @@ fragment Order on Order {
     ...MailingAddress
   }
   itemCount
+  canCreatePayment
+  paymentMethodType
 }
 
 # ============================================
@@ -427,7 +430,7 @@ fragment CartDiscountAllocation on CartDiscountAllocation {
   }
 }
 
-# Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes. Spread on the cart drawer / cart page; refetch after every cart mutation.
+# Full cart shape — totals, line items (paginated up to 100), buyer identity, applied discount codes + allocations, note, custom attributes, plus fulfillment fields (email/phone/addresses/shipping method/payment method/applied gift cards). Spread on the cart drawer / cart page; refetch after every cart mutation including completion lifecycle.
 fragment Cart on Cart {
   id
   checkoutUrl
@@ -468,10 +471,61 @@ fragment Cart on Cart {
     key
     value
   }
+  email
+  phone
+  shippingAddress {
+    ...MailingAddress
+  }
+  billingAddress {
+    ...MailingAddress
+  }
+  selectedShippingMethod {
+    ...CartShippingMethod
+  }
+  selectedPaymentMethod {
+    ...CartSelectedPaymentMethod
+  }
+  appliedGiftCards {
+    ...CartAppliedGiftCard
+  }
   createdAt
   updatedAt
 }
 
+# Shipping method selected on a cart (D8 term unification — wcześniej ShippingRate). Returned przez `cart.selectedShippingMethod` po `cartSelectShippingMethod` mutation.
+fragment CartShippingMethod on CartShippingMethod {
+  handle
+  title
+  price {
+    ...Money
+  }
+}
+
+# Gift card applied to a cart — masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`.
+fragment CartAppliedGiftCard on CartAppliedGiftCard {
+  maskedCode
+  lastCharacters
+  appliedAmount {
+    ...Money
+  }
+  remainingBalance {
+    ...Money
+  }
+}
+
+# Payment method (integration provider) selected on a cart — id, name, provider code, type category (CARD/BLIK/BANK_TRANSFER/etc.), icon, description, isDefault, supportedCurrencies. Storefront UI używa do iconography + selection display.
+fragment CartSelectedPaymentMethod on PaymentMethod {
+  id
+  name
+  provider
+  type
+  icon
+  description
+  isDefault
+  supportedCurrencies
+  position
+}
+
 # ============================================
 # Shop
 # ============================================
@@ -619,161 +673,14 @@ fragment AvailablePaymentMethods on AvailablePaymentMethods {
 }
 
 # ============================================
-# Checkout
+# Discount Code Validation
 # ============================================
-
-# Single shipping rate option — `handle` is the stable id you pass to `checkoutSelectShippingRate` as `rateId`, plus title and price.
-fragment ShippingRate on ShippingRate {
-  handle
-  title
-  price {
-    ...Money
-  }
-}
-
-# One tax line on the checkout — title, rate (decimal, e.g. 0.23 for 23%), computed amount. Spread on the order summary.
-fragment TaxLine on TaxLine {
-  title
-  rate
-  price {
-    ...Money
-  }
-}
-
-# Item affected by a discount — the discounted product/variant with original + discounted prices and savings. Used on Buy-X-Get-Y promotions to highlight which items the discount applies to.
-fragment DiscountAffectedItem on DiscountAffectedItem {
-  productId
-  variantId
-  title
-  quantity
-  originalPrice {
-    ...Money
-  }
-  discountedPrice {
-    ...Money
-  }
-  savings {
-    ...Money
-  }
-  isFreeItem
-}
-
-# A discount currently applied to the checkout — code, type, value, plus BXGY (Buy X Get Y) metadata when applicable (`buyQuantity`, `getQuantity`, `getDiscountPercent`, `affectedItems`). Use to render a "Discounts applied" panel.
-fragment DiscountApplication on DiscountApplication {
-  code
-  isApplicable
-  type
-  value {
-    ...Money
-  }
-  title
-  affectedItems {
-    ...DiscountAffectedItem
-  }
-  buyQuantity
-  getQuantity
-  getDiscountPercent
-}
-
-# Lightweight discount code entry on the checkout — code + applicability flag.
-fragment DiscountCode on DiscountCode {
-  code
-  isApplicable
-}
-
-# Single line item in the checkout — variant snapshot, quantity, unit + total prices, image. Use on the order summary panel.
-fragment CheckoutLineItem on CheckoutLineItem {
-  id
-  title
-  variantTitle
-  quantity
-  pricePerUnit {
-    ...Money
-  }
-  total {
-    ...Money
-  }
-  variantId
-  productId
-  sku
-  image {
-    ...ImageThumbnail
-  }
-}
-
-# Gift card applied to the checkout — `maskedCode` (first + last 4 chars), `lastCharacters` (for display matching), the amount applied to this checkout, and remaining balance after this order would complete.
-fragment AppliedGiftCard on AppliedGiftCard {
-  maskedCode
-  lastCharacters
-  appliedAmount {
-    ...Money
-  }
-  remainingBalance {
-    ...Money
-  }
-}
-
-# Full checkout shape — line items, shipping + billing addresses, selected + available shipping rates, available payment methods, applied discounts + gift cards, tax lines, totals (`cost`, `paymentDue`, `totalGiftCardAmount`). Spread on the checkout flow; refetch after every checkout mutation. `isReady` flips to true when the checkout has all required fields to call `checkoutComplete`.
-fragment Checkout on Checkout {
-  id
-  isReady
-  isCompleted
-  completedOrderId
-  webUrl
-  lineItems {
-    ...CheckoutLineItem
-  }
-  totalQuantity
-  shippingAddress {
-    ...MailingAddress
-  }
-  billingAddress {
-    ...MailingAddress
-  }
-  shippingLine {
-    ...ShippingRate
-  }
-  availableShippingRates {
-    ...ShippingRate
-  }
-  shippingRatesReady
-  email
-  phone
-  customerId
-  discountCodes {
-    ...DiscountCode
-  }
-  discountApplications {
-    ...DiscountApplication
-  }
-  availablePaymentMethods {
-    ...PaymentMethod
-  }
-  selectedPaymentMethodId
-  cost {
-    subtotal { ...Money }
-    total { ...Money }
-    totalTax { ...Money }
-    totalShipping { ...Money }
-    totalDiscounts { ...Money }
-  }
-  taxLines {
-    ...TaxLine
-  }
-  appliedGiftCards {
-    ...AppliedGiftCard
-  }
-  totalGiftCardAmount {
-    ...Money
-  }
-  paymentDue {
-    ...Money
-  }
-  currencyCode
-  note
-  createdAt
-  updatedAt
-}
+#
+# Phase 3 unify-cart-graphql-surface: Checkout/CheckoutLineItem/AppliedGiftCard/
+# ShippingRate/TaxLine fragments usunięte wraz z `Checkout` aggregate (Cluster 3).
+# Cart now exposes wszystkie te informacje bezpośrednio (przez `Cart` fragment),
+# bez sztucznej dualnosci. Sprawdź `Cart` fragment dla cart line items, addresses,
+# shipping method (rename z rate per D8), gift cards, discount applications.
 
 # ============================================
 # Shipments / Tracking