@doswiftly/storefront-sdk 9.0.0 → 10.0.0

package/CHANGELOG.md

@@ -1,5 +1,185 @@
 # Changelog
 
+## 10.0.0
+
+### Major 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.
+
+- 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
+
+- 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
+
+- f2ad734: **Version-sync release**: align `@doswiftly/storefront-operations` and `@doswiftly/storefront-sdk` back to the same version (`9.1.0`) as required by their linked package contract.
+
+  ### Why this release
+
+  A prior release sequence left the two linked packages on different majors (`@doswiftly/storefront-operations@8.0.0` + `@doswiftly/storefront-sdk@9.0.0`). The linked contract guarantees consumers a "matching set of operation names ↔ SDK runtime" — desynced majors break that guarantee and confuse downstream codegen consumers.
+
+  This release re-aligns both to `9.1.0`. **No API surface change**, no operation rename, no SDK behavior change. Pure version-sync.
+
+  ### Migration
+
+  None. If you have either package on `^8.x` or `^9.x`, upgrade both to `9.1.0` to stay on a supported linked pair. Subsequent releases ship from this aligned baseline.
+
+  ### Reference
+
+  Linked semantics in `.changeset/config.json`: changesets calculates `max(versions across linked pair) + bump-type` and applies it to every member. With `operations@8.0.0` and `sdk@9.0.0` already published, `max = 9.0.0`; a minor bump on both yields `9.1.0` for both. Future major releases (real BREAKING changes) jump from this aligned baseline organically.
+
 ## 9.0.0
 
 ### Major Changes

package/dist/core/auth/types.d.ts

@@ -12,10 +12,10 @@ export interface Customer {
     lastName: string | null;
     displayName: string | null;
     phone: string | null;
-    emailVerified: boolean;
-    emailMarketingState: string | null;
+    isEmailVerified: boolean;
+    emailMarketing: string | null;
     defaultAddress: MailingAddress | null;
-    ordersCount: number;
+    orderCount: number;
     totalSpent: {
         amount: string;
         currencyCode: string;
@@ -33,6 +33,8 @@ export interface MailingAddress {
     countryCode: string | null;
     firstName: string | null;
     lastName: string | null;
+    /** Computed full name (`firstName + " " + lastName`). */
+    name: string | null;
     phone: string | null;
     state: string | null;
     stateCode: string | null;
@@ -49,5 +51,10 @@ export interface CustomerCreateInput {
     password: string;
     firstName?: string;
     lastName?: string;
+    phone?: string;
+    /** Opt-in to email marketing. `true` → SUBSCRIBED (lub PENDING gdy CONFIRMED_OPT_IN). */
+    acceptsMarketing?: boolean;
+    /** Marketing opt-in level — `'SINGLE_OPT_IN'` (default) lub `'CONFIRMED_OPT_IN'` (double opt-in via email). */
+    marketingOptInLevel?: 'SINGLE_OPT_IN' | 'CONFIRMED_OPT_IN';
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/core/auth/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yDAAyD;IACzD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+GAA+G;IAC/G,mBAAmB,CAAC,EAAE,eAAe,GAAG,kBAAkB,CAAC;CAC5D"}

package/dist/core/cart/cart-client.d.ts

@@ -4,18 +4,43 @@
  * Wraps StorefrontClient.mutate/query with typed operations.
  * Auto-throws on userErrors via assertNoUserErrors.
  *
+ * Each mutation returns `{ cart, warnings }` — `warnings` is non-blocking advisory
+ * hints (low stock, partial availability) the storefront UI may render as soft
+ * notices. `userErrors` causes the call to throw before returning.
+ *
  * @example
  * ```typescript
  * const cartClient = new CartClient(storefrontClient);
  *
- * const cart = await cartClient.create();
- * const updated = await cartClient.addItem(cart.id, [
+ * const { cart } = await cartClient.create();
+ * const { cart: updated, warnings } = await cartClient.addItems(cart.id, [
  *   { variantId: 'variant-123', quantity: 1 }
  * ]);
+ * for (const w of warnings) {
+ *   console.warn(`[${w.code}] ${w.message}`);
+ * }
  * ```
  */
 import type { StorefrontClient } from '../client/types';
-import type { Cart, CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput } from './types';
+import type { Cart, CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartSetShippingAddressInput, CartSetBillingAddressInput, CartSelectShippingMethodInput, CartSelectPaymentMethodInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartUpdateGiftCardRecipientInput, CartCompleteInput, CartWarning, Order, DiscountValidationResult } from './types';
+/**
+ * Standard mutation return shape — `cart` is non-null on success (userErrors
+ * cause assertNoUserErrors to throw), `warnings` may be empty.
+ */
+export interface CartMutationOutcome {
+    cart: Cart;
+    warnings: CartWarning[];
+}
+/**
+ * cartComplete result — `order` may be null while backend resolver Phase 4
+ * follow-up lands (currently storefront should fallback to `order(id)` query
+ * if null). `cart` is the final post-completion state.
+ */
+export interface CartCompleteOutcome {
+    cart: Cart;
+    order: Order | null;
+    warnings: CartWarning[];
+}
 export declare class CartClient {
     private readonly client;
     constructor(client: StorefrontClient);
@@ -27,31 +52,91 @@ export declare class CartClient {
     /**
      * Create a new cart, optionally with initial lines.
      */
-    create(input?: CartCreateInput): Promise<Cart>;
+    create(input?: CartCreateInput): Promise<CartMutationOutcome>;
     /**
      * Add line items to an existing cart.
      */
-    addItems(cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    addItems(cartId: string, lines: CartLineInput[]): Promise<CartMutationOutcome>;
     /**
      * Update line items (quantity, attributes).
      */
-    updateItems(cartId: string, lines: CartLineUpdateInput[]): Promise<Cart>;
+    updateItems(cartId: string, lines: CartLineUpdateInput[]): Promise<CartMutationOutcome>;
     /**
      * Remove line items by their line IDs.
      */
-    removeItems(cartId: string, lineIds: string[]): Promise<Cart>;
+    removeItems(cartId: string, lineIds: string[]): Promise<CartMutationOutcome>;
     /**
      * Update discount codes (replaces all existing codes).
      * Pass empty array to clear discounts.
      */
-    updateDiscountCodes(cartId: string, discountCodes: string[]): Promise<Cart>;
+    updateDiscountCodes(cartId: string, discountCodes: string[]): Promise<CartMutationOutcome>;
     /**
      * Update cart note / gift message.
      */
-    updateNote(cartId: string, note: string): Promise<Cart>;
+    updateNote(cartId: string, note: string): Promise<CartMutationOutcome>;
+    /**
+     * Update buyer identity (email, phone, country, customer link, languageCode).
+     */
+    updateBuyerIdentity(cartId: string, buyerIdentity: CartBuyerIdentityInput): Promise<CartMutationOutcome>;
+    /**
+     * Set shipping address on the cart. Full replace (not patch). Triggers cart
+     * re-pricing (tax recalculation per address country/region).
+     */
+    setShippingAddress(input: CartSetShippingAddressInput): Promise<CartMutationOutcome>;
+    /**
+     * Set billing address on the cart (independent z shipping address — pass
+     * even when "billing same as shipping").
+     */
+    setBillingAddress(input: CartSetBillingAddressInput): Promise<CartMutationOutcome>;
+    /**
+     * Select shipping method on the cart (Decision D8 term unification — typed
+     * `shippingMethodId` jako ID, NIE String).
+     */
+    selectShippingMethod(input: CartSelectShippingMethodInput): Promise<CartMutationOutcome>;
+    /**
+     * Select payment method on the cart. Validates existence + active status;
+     * no pre-authorization.
+     */
+    selectPaymentMethod(input: CartSelectPaymentMethodInput): Promise<CartMutationOutcome>;
+    /**
+     * Apply gift card to cart (stackable z discount codes, FIFO consumption).
+     * Balance NOT debited yet — actual deduction at cartComplete.
+     */
+    applyGiftCard(input: CartApplyGiftCardInput): Promise<CartMutationOutcome>;
+    /**
+     * Remove applied gift card from cart. Re-calculates FIFO amounts dla
+     * pozostałych cards.
+     */
+    removeGiftCard(input: CartRemoveGiftCardInput): Promise<CartMutationOutcome>;
+    /**
+     * Update gift card recipient info na line item (personalised delivery —
+     * recipientEmail, recipientName, message). Required przed cartComplete
+     * dla każdego gift card line item.
+     */
+    updateGiftCardRecipient(input: CartUpdateGiftCardRecipientInput): Promise<CartMutationOutcome>;
+    /**
+     * Complete cart → create Order. Returns `{ cart, order, warnings }`.
+     * Idempotent on `idempotencyKey` (auto-generated z cartId + minute timestamp
+     * jeśli omitted).
+     *
+     * Order zawiera `canCreatePayment` + `paymentMethodType` (po extend fragment
+     * Order w SSOT) — storefront czyta żeby zdecydować payment flow. paymentUrl
+     * celowo NIE w response (Decision D4) — storefront inicjuje payment osobnym
+     * `paymentCreate` mutation (po sprawdzeniu order.canCreatePayment).
+     *
+     * Backend resolver może obecnie zwrócić `order: null` (Phase 4 follow-up) —
+     * storefront powinien fallback do `order(id, orderNumber)` query.
+     */
+    complete(input: CartCompleteInput): Promise<CartCompleteOutcome>;
     /**
-     * Update buyer identity (email, phone, country, customer link).
+     * Validate discount code preview (Decision D3) — read-only Query, NIE
+     * mutation. Doesn't modify cart state. Returns `{ isValid, discount?, error? }`
+     * — storefront UI używa do inline feedback gdy klient wpisuje kod.
+     *
+     * Caching: storefront powinien używać `fetchPolicy: 'network-only'` lub
+     * cache key z `cart.subtotal` (discount eligibility może zależeć od minimum
+     * order amount).
      */
-    updateBuyerIdentity(cartId: string, buyerIdentity: CartBuyerIdentityInput): Promise<Cart>;
+    validateDiscountCode(cartId: string, discountCode: string): Promise<DiscountValidationResult>;
 }
 //# sourceMappingURL=cart-client.d.ts.map

package/dist/core/cart/cart-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cart-client.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EACV,IAAI,EACJ,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AA0BjB,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAQ/C;;OAEG;IACG,MAAM,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASrE;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9E;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASnE;;;OAGG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASjF;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;CAQhG"}
+{"version":3,"file":"cart-client.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-client.ts"],"names":[],"mappings":"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"}

package/dist/core/cart/cart-client.js

@@ -4,18 +4,25 @@
  * Wraps StorefrontClient.mutate/query with typed operations.
  * Auto-throws on userErrors via assertNoUserErrors.
  *
+ * Each mutation returns `{ cart, warnings }` — `warnings` is non-blocking advisory
+ * hints (low stock, partial availability) the storefront UI may render as soft
+ * notices. `userErrors` causes the call to throw before returning.
+ *
  * @example
  * ```typescript
  * const cartClient = new CartClient(storefrontClient);
  *
- * const cart = await cartClient.create();
- * const updated = await cartClient.addItem(cart.id, [
+ * const { cart } = await cartClient.create();
+ * const { cart: updated, warnings } = await cartClient.addItems(cart.id, [
  *   { variantId: 'variant-123', quantity: 1 }
  * ]);
+ * for (const w of warnings) {
+ *   console.warn(`[${w.code}] ${w.message}`);
+ * }
  * ```
  */
 import { assertNoUserErrors } from '../helpers/assert-no-user-errors';
-import { CART_QUERY, CART_CREATE, CART_LINES_ADD, CART_LINES_UPDATE, CART_LINES_REMOVE, CART_DISCOUNT_CODES_UPDATE, CART_NOTE_UPDATE, CART_BUYER_IDENTITY_UPDATE, } from '../operations/cart';
+import { CART_QUERY, CART_CREATE, CART_ADD_LINES, CART_UPDATE_LINES, CART_REMOVE_LINES, CART_DISCOUNT_CODES_UPDATE, CART_UPDATE_NOTE, CART_UPDATE_BUYER_IDENTITY, 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, } from '../operations/cart';
 export class CartClient {
     client;
     constructor(client) {
@@ -35,55 +42,157 @@ export class CartClient {
     async create(input) {
         const data = await this.client.mutate(CART_CREATE, { input: input ?? {} });
         assertNoUserErrors(data.cartCreate);
-        return data.cartCreate.cart;
+        return { cart: data.cartCreate.cart, warnings: data.cartCreate.warnings ?? [] };
     }
     /**
      * Add line items to an existing cart.
      */
     async addItems(cartId, lines) {
-        const data = await this.client.mutate(CART_LINES_ADD, { cartId, lines });
-        assertNoUserErrors(data.cartLinesAdd);
-        return data.cartLinesAdd.cart;
+        const data = await this.client.mutate(CART_ADD_LINES, { id: cartId, lines });
+        assertNoUserErrors(data.cartAddLines);
+        return { cart: data.cartAddLines.cart, warnings: data.cartAddLines.warnings ?? [] };
     }
     /**
      * Update line items (quantity, attributes).
      */
     async updateItems(cartId, lines) {
-        const data = await this.client.mutate(CART_LINES_UPDATE, { cartId, lines });
-        assertNoUserErrors(data.cartLinesUpdate);
-        return data.cartLinesUpdate.cart;
+        const data = await this.client.mutate(CART_UPDATE_LINES, { id: cartId, lines });
+        assertNoUserErrors(data.cartUpdateLines);
+        return { cart: data.cartUpdateLines.cart, warnings: data.cartUpdateLines.warnings ?? [] };
     }
     /**
      * Remove line items by their line IDs.
      */
     async removeItems(cartId, lineIds) {
-        const data = await this.client.mutate(CART_LINES_REMOVE, { cartId, lineIds });
-        assertNoUserErrors(data.cartLinesRemove);
-        return data.cartLinesRemove.cart;
+        const data = await this.client.mutate(CART_REMOVE_LINES, { id: cartId, lineIds });
+        assertNoUserErrors(data.cartRemoveLines);
+        return { cart: data.cartRemoveLines.cart, warnings: data.cartRemoveLines.warnings ?? [] };
     }
     /**
      * Update discount codes (replaces all existing codes).
      * Pass empty array to clear discounts.
      */
     async updateDiscountCodes(cartId, discountCodes) {
-        const data = await this.client.mutate(CART_DISCOUNT_CODES_UPDATE, { cartId, discountCodes });
+        const data = await this.client.mutate(CART_DISCOUNT_CODES_UPDATE, { id: cartId, discountCodes });
         assertNoUserErrors(data.cartDiscountCodesUpdate);
-        return data.cartDiscountCodesUpdate.cart;
+        return { cart: data.cartDiscountCodesUpdate.cart, warnings: data.cartDiscountCodesUpdate.warnings ?? [] };
     }
     /**
      * Update cart note / gift message.
      */
     async updateNote(cartId, note) {
-        const data = await this.client.mutate(CART_NOTE_UPDATE, { cartId, note });
-        assertNoUserErrors(data.cartNoteUpdate);
-        return data.cartNoteUpdate.cart;
+        const data = await this.client.mutate(CART_UPDATE_NOTE, { id: cartId, note });
+        assertNoUserErrors(data.cartUpdateNote);
+        return { cart: data.cartUpdateNote.cart, warnings: data.cartUpdateNote.warnings ?? [] };
     }
     /**
-     * Update buyer identity (email, phone, country, customer link).
+     * Update buyer identity (email, phone, country, customer link, languageCode).
      */
     async updateBuyerIdentity(cartId, buyerIdentity) {
-        const data = await this.client.mutate(CART_BUYER_IDENTITY_UPDATE, { cartId, buyerIdentity });
-        assertNoUserErrors(data.cartBuyerIdentityUpdate);
-        return data.cartBuyerIdentityUpdate.cart;
+        const data = await this.client.mutate(CART_UPDATE_BUYER_IDENTITY, { id: cartId, buyerIdentity });
+        assertNoUserErrors(data.cartUpdateBuyerIdentity);
+        return { cart: data.cartUpdateBuyerIdentity.cart, warnings: data.cartUpdateBuyerIdentity.warnings ?? [] };
+    }
+    // -------------------------------------------------------------------------
+    // Phase 3 — Cart completion lifecycle methods
+    // -------------------------------------------------------------------------
+    /**
+     * Set shipping address on the cart. Full replace (not patch). Triggers cart
+     * re-pricing (tax recalculation per address country/region).
+     */
+    async setShippingAddress(input) {
+        const data = await this.client.mutate(CART_SET_SHIPPING_ADDRESS, { input });
+        assertNoUserErrors(data.cartSetShippingAddress);
+        return { cart: data.cartSetShippingAddress.cart, warnings: data.cartSetShippingAddress.warnings ?? [] };
+    }
+    /**
+     * Set billing address on the cart (independent z shipping address — pass
+     * even when "billing same as shipping").
+     */
+    async setBillingAddress(input) {
+        const data = await this.client.mutate(CART_SET_BILLING_ADDRESS, { input });
+        assertNoUserErrors(data.cartSetBillingAddress);
+        return { cart: data.cartSetBillingAddress.cart, warnings: data.cartSetBillingAddress.warnings ?? [] };
+    }
+    /**
+     * Select shipping method on the cart (Decision D8 term unification — typed
+     * `shippingMethodId` jako ID, NIE String).
+     */
+    async selectShippingMethod(input) {
+        const data = await this.client.mutate(CART_SELECT_SHIPPING_METHOD, { input });
+        assertNoUserErrors(data.cartSelectShippingMethod);
+        return { cart: data.cartSelectShippingMethod.cart, warnings: data.cartSelectShippingMethod.warnings ?? [] };
+    }
+    /**
+     * Select payment method on the cart. Validates existence + active status;
+     * no pre-authorization.
+     */
+    async selectPaymentMethod(input) {
+        const data = await this.client.mutate(CART_SELECT_PAYMENT_METHOD, { input });
+        assertNoUserErrors(data.cartSelectPaymentMethod);
+        return { cart: data.cartSelectPaymentMethod.cart, warnings: data.cartSelectPaymentMethod.warnings ?? [] };
+    }
+    /**
+     * Apply gift card to cart (stackable z discount codes, FIFO consumption).
+     * Balance NOT debited yet — actual deduction at cartComplete.
+     */
+    async applyGiftCard(input) {
+        const data = await this.client.mutate(CART_APPLY_GIFT_CARD, { input });
+        assertNoUserErrors(data.cartApplyGiftCard);
+        return { cart: data.cartApplyGiftCard.cart, warnings: data.cartApplyGiftCard.warnings ?? [] };
+    }
+    /**
+     * Remove applied gift card from cart. Re-calculates FIFO amounts dla
+     * pozostałych cards.
+     */
+    async removeGiftCard(input) {
+        const data = await this.client.mutate(CART_REMOVE_GIFT_CARD, { input });
+        assertNoUserErrors(data.cartRemoveGiftCard);
+        return { cart: data.cartRemoveGiftCard.cart, warnings: data.cartRemoveGiftCard.warnings ?? [] };
+    }
+    /**
+     * Update gift card recipient info na line item (personalised delivery —
+     * recipientEmail, recipientName, message). Required przed cartComplete
+     * dla każdego gift card line item.
+     */
+    async updateGiftCardRecipient(input) {
+        const data = await this.client.mutate(CART_UPDATE_GIFT_CARD_RECIPIENT, { input });
+        assertNoUserErrors(data.cartUpdateGiftCardRecipient);
+        return { cart: data.cartUpdateGiftCardRecipient.cart, warnings: data.cartUpdateGiftCardRecipient.warnings ?? [] };
+    }
+    /**
+     * Complete cart → create Order. Returns `{ cart, order, warnings }`.
+     * Idempotent on `idempotencyKey` (auto-generated z cartId + minute timestamp
+     * jeśli omitted).
+     *
+     * Order zawiera `canCreatePayment` + `paymentMethodType` (po extend fragment
+     * Order w SSOT) — storefront czyta żeby zdecydować payment flow. paymentUrl
+     * celowo NIE w response (Decision D4) — storefront inicjuje payment osobnym
+     * `paymentCreate` mutation (po sprawdzeniu order.canCreatePayment).
+     *
+     * Backend resolver może obecnie zwrócić `order: null` (Phase 4 follow-up) —
+     * storefront powinien fallback do `order(id, orderNumber)` query.
+     */
+    async complete(input) {
+        const data = await this.client.mutate(CART_COMPLETE, { input });
+        assertNoUserErrors(data.cartComplete);
+        return {
+            cart: data.cartComplete.cart,
+            order: data.cartComplete.order,
+            warnings: data.cartComplete.warnings ?? [],
+        };
+    }
+    /**
+     * Validate discount code preview (Decision D3) — read-only Query, NIE
+     * mutation. Doesn't modify cart state. Returns `{ isValid, discount?, error? }`
+     * — storefront UI używa do inline feedback gdy klient wpisuje kod.
+     *
+     * Caching: storefront powinien używać `fetchPolicy: 'network-only'` lub
+     * cache key z `cart.subtotal` (discount eligibility może zależeć od minimum
+     * order amount).
+     */
+    async validateDiscountCode(cartId, discountCode) {
+        const data = await this.client.query(CART_VALIDATE_DISCOUNT_CODE, { cartId, discountCode });
+        return data.cartValidateDiscountCode;
     }
 }