@doswiftly/storefront-sdk 4.7.2 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,796 @@
 # Changelog
 
+## 7.0.0
+
+### Major Changes
+
+- 1efbaab: # Storefront SDK 7.0 — sync z `@doswiftly/storefront-operations@7.0.0`
+
+  Major bump synchronizujący SDK z schematem GraphQL 7.0. Od tej wersji oba pakiety są publishowane synchronicznie — masz zainstalowaną tę samą wersję obu, niezgodne kombinacje są blokowane.
+
+  ## Breaking changes
+
+  ### Cart cost — `Money` zamiast `PriceMoney`, dodany `checkoutCharge`
+
+  Pola w `CartCost` i `CartLineCost` zwracają teraz `Money` (default scalar — `amount`, `currencyCode`) zamiast `PriceMoney` (currency-conversion transparency: `baseAmount`, `exchangeRate`, `marginApplied`, etc.). Konwersja waluty pozostaje w opt-in `*WithConversion` polach po stronie serwera dla potrzebujących UI'ów (storefront landing page price, hero promo).
+
+  Plus `CartCost` dostał nowe nullable pole `checkoutCharge: Money` — kwota pre-auth dla bramek płatniczych z separate authorization step.
+
+  ### Cart lines — Relay Connection (edges/nodes/pageInfo/totalCount)
+
+  `Cart.lines` zwraca teraz `CartLineConnection` zamiast flat `[CartLine!]`. Klienci czytają `cart.lines.nodes` (preferowane) lub iterują `cart.lines.edges[].node`.
+
+  ```typescript
+  // Przed (5.x)
+  for (const line of cart.lines) { ... }
+  const count = cart.lines.length;
+
+  // Po (7.0)
+  for (const line of cart.lines.nodes) { ... }
+  const count = cart.lines.totalCount;
+  ```
+
+  ### Cart line input/output — `variantId` zamiast `merchandiseId`, `variant` zamiast `merchandise`
+
+  ```typescript
+  // Przed (5.x)
+  await cartClient.addItems(cartId, [{ merchandiseId: "var-1", quantity: 1 }]);
+  console.log(cart.lines[0].merchandise.title);
+
+  // Po (7.0)
+  await cartClient.addItems(cartId, [{ variantId: "var-1", quantity: 1 }]);
+  console.log(cart.lines.nodes[0].variant.title);
+  ```
+
+  ### Cart cost field rename — bezsufiksowo
+
+  | 5.x                                       | 7.0                               |
+  | ----------------------------------------- | --------------------------------- |
+  | `CartCost.totalAmount`                    | `total`                           |
+  | `CartCost.subtotalAmount`                 | `subtotal`                        |
+  | `CartCost.totalTaxAmount`                 | `totalTax`                        |
+  | `CartCost.totalDutyAmount`                | `totalDuty`                       |
+  | (brak)                                    | `checkoutCharge` (nowe, nullable) |
+  | `CartLineCost.amountPerQuantity`          | `pricePerUnit`                    |
+  | `CartLineCost.subtotalAmount`             | `subtotal`                        |
+  | `CartLineCost.totalAmount`                | `total`                           |
+  | `CartLineCost.compareAtAmountPerQuantity` | `compareAtPricePerUnit`           |
+
+  ```typescript
+  // Przed
+  const total = cart.cost.totalAmount.amount;
+  const linePrice = cart.lines[0].cost.amountPerQuantity.amount;
+
+  // Po
+  const total = cart.cost.total.amount;
+  const linePrice = cart.lines.nodes[0].cost.pricePerUnit.amount;
+  ```
+
+  ### ProductVariant — przebudowane pola
+
+  | 5.x                                       | 7.0                                                                           |
+  | ----------------------------------------- | ----------------------------------------------------------------------------- |
+  | `available: boolean`                      | `isAvailable: boolean`                                                        |
+  | `quantityAvailable: number`               | `availableStock: number`                                                      |
+  | `position: number`                        | `sortOrder: number`                                                           |
+  | `weight: number` (scalar)                 | `weight: { value: number, unit: string }`                                     |
+  | `image: Image` (custom shape)             | `image: ImageThumbnail` (spread `id, url, altText, width, height, thumbhash`) |
+  | `originalPrice`, `originalCompareAtPrice` | (usunięte — opt-in `*WithConversion` jeśli potrzebujesz konwersji)            |
+
+  ### CartLine — dodane `attributeSelections`
+
+  Customer-filled konfigurator (`AttributeType` z surcharge snapshot — Faza 1 R5). Distinct od `attributes` (raw key/value Line Item Properties).
+
+  ```typescript
+  const line = cart.lines.nodes[0];
+  console.log(line.attributes); // [{ key: 'gift_message', value: '...' }]
+  console.log(line.attributeSelections); // [{ attributeName, optionLabel, surchargeAmount, ... }]
+  ```
+
+  ### CartDiscountCode — `isApplicable` zamiast `applicable`
+
+  ```typescript
+  // Przed
+  if (code.applicable) { ... }
+
+  // Po
+  if (code.isApplicable) { ... }
+  ```
+
+  ### Auth mutations — sync z domeną backend
+
+  Mutacje GraphQL nazewnictwo zmienione zgodne z naszą domeną:
+
+  | 5.x mutation                | 7.0 mutation           |
+  | --------------------------- | ---------------------- |
+  | `customerAccessTokenCreate` | `customerLogin`        |
+  | `customerAccessTokenDelete` | `customerLogout`       |
+  | `customerAccessTokenRenew`  | `customerRefreshToken` |
+  | `customerCreate`            | `customerSignup`       |
+
+  Używając wysokopoziomowego API (`authClient.login()`, `authClient.register()`) — **nie wymaga zmian** w Twoim kodzie. Surowe queries przez `client.mutate(QUERY_STRING)` — wymagają update'u nazw mutacji.
+
+  ### Method rename — `renewToken` → `refreshToken`
+
+  ```typescript
+  // Przed
+  await authClient.renewToken();
+  const { renewToken, isRenewingToken } = useAuth();
+
+  // Po
+  await authClient.refreshToken();
+  const { refreshToken, isRefreshingToken } = useAuth();
+  ```
+
+  Typ `TokenRenewResult` → `TokenRefreshResult`.
+
+  ### `AuthClient.getCustomer()` — drop `accessToken` argument
+
+  Już od 5.x auth context resolved server-side z httpOnly cookie / `Authorization: Bearer`. W 5.x `getCustomer(accessToken)` był legacy override z 4.x — w 7.0 usunięty całkowicie:
+
+  ```typescript
+  // Przed (5.x — działało, ale ignorowało argument)
+  const customer = await authClient.getCustomer(accessToken);
+
+  // Po (7.0)
+  const customer = await authClient.getCustomer();
+  ```
+
+  ## Compatibility matrix
+
+  | SDK | Backend (operations)       |
+  | --- | -------------------------- |
+  | 7.x | 7.x (linked synchroniczne) |
+  | 5.x | 4.x, 5.x, 6.x              |
+  | 4.x | 4.x                        |
+
+  Eksporty SDK (`@doswiftly/storefront-sdk`, `/react`, `/react/server`, `/cache`) bez zmian. Provider API (StorefrontProvider, store factories, middleware pipeline) bez zmian.
+
+  ## Nowe eksporty typów
+
+  Dodatkowe typy publicznie dostępne dla template'ów które chcą strict typing po cart sub-strukturach:
+
+  `CartLineEdge`, `CartLineConnection`, `ProductVariant`, `ProductVariantWeight`, `ImageThumbnail`, `PageInfo`, `AttributeSelection`, `CartAttributeSelectionInput`, `SelectedOption`.
+
+## 5.0.0
+
+### Major Changes
+
+- d51eb03: Storefront API: cookie-first authentication + comprehensive typing fixes.
+
+  **⚠️ Breaking changes — migration required**
+
+  ### Authentication: cookie-first, drop `customerAccessToken` argument
+
+  The storefront API no longer accepts `customerAccessToken` as a query/mutation argument.
+  Authentication context is now resolved per-request from (in priority order):
+  1. **httpOnly cookie `customerAccessToken`** — set automatically by the API after `customerAccessTokenCreate` / `customerCreate` / `customerAccessTokenRenew` / `customerActivateByUrl` / `customerResetByUrl` / `customerReset`. Browser-based storefronts gain XSS-safe auth out of the box.
+  2. **`Authorization: Bearer <token>` header** — for non-browser clients (mobile native, server-to-server, OAuth integrations per RFC 6750).
+
+  `customerAccessTokenDelete` (logout) clears the cookie via `Set-Cookie: customerAccessToken=; Max-Age=0`.
+
+  **Affected operations** (drop `customerAccessToken: String!` arg + value pass-through):
+  - Queries: `customer`, `customerOrder`, `shipment`, `return`, `returnsByOrder`
+  - Mutations: `customerAccessTokenDelete`, `customerAccessTokenRenew`, `customerUpdate`, `customerAddressCreate`, `customerAddressUpdate`, `customerAddressDelete`, `customerDefaultAddressUpdate`, `returnCreate`, `returnCancel`
+
+  **Migration**:
+
+  ```graphql
+  # Before (4.x)
+  query Customer($customerAccessToken: String!) {
+    customer(customerAccessToken: $customerAccessToken) { ... }
+  }
+
+  # After (5.x)
+  query Customer {
+    customer { ... }
+  }
+  ```
+
+  For a browser, send the request with `credentials: 'include'` so the httpOnly cookie travels along. For non-browser clients, set `Authorization: Bearer <jwt>` on each request. The `accessToken` field in mutation responses (`customerAccessTokenCreate.customerAccessToken.accessToken`) is still present for non-browser clients that manage their own token storage.
+
+  ### `LANGUAGE_HEADER_NAME` constant renamed `X-Lang` → `X-Language`
+
+  Storefronts importing this constant from `@doswiftly/storefront-sdk` will pick up the new value at rebuild time. The previous value did not match the API reader and silently fell through to `Accept-Language` auto-detection — explicit per-request language switching now works as documented.
+
+  ### `@inContext` directive accepts new arguments
+
+  `@inContext` previously exposed only `preferredLocationId`. It now also accepts `country: String`, `language: String`, `currency: String`, and `buyer: BuyerInput { customerAccessToken, companyLocationId }`. Resolution priority: `directive > request header > cookie > Accept-Language auto-detect > shop default`. All five layers are independent — pick whichever matches your routing/SSR architecture.
+
+  ### `Shop.primaryDomain` is now a `Domain` object
+
+  ```graphql
+  # Before
+  type Shop {
+    primaryDomain: String # "https://example.com"
+    primaryDomainObject: Domain! # { host, url, sslEnabled }
+  }
+
+  # After
+  type Shop {
+    primaryDomain: Domain! # { host, url, sslEnabled }
+  }
+  ```
+
+  Update the `Shop` fragment to query the structured fields:
+
+  ```graphql
+  fragment Shop on Shop {
+    primaryDomain { host url sslEnabled }
+    ...
+  }
+  ```
+
+  ### Removed redundant fields
+  - `Menu.itemsCount` — drop. Use `items.length` in the client (the count was always equal to the array length).
+  - `GiftCard.lastCharacters` — drop. Compute from `maskedCode.slice(-4)` in the client.
+
+  ### Stronger types — `Date`, enums, structured errors
+
+  Several fields previously returned `String` (ISO 8601) or untyped error arrays — now properly typed:
+  - **DateTime**: `Order.processedAt`, `BlogPost.{publishedAt,createdAt,updatedAt}`, `ShopPage.{publishedAt,createdAt,updatedAt}`, `LoyaltyMember.{lastActivityAt,enrolledAt}`, `LoyaltyTransaction.{createdAt,expiresAt}`, `LoyaltyPointsSummary.nextExpiryDate`, `CustomerAccessToken.expiresAt`. Codegen now emits `Date | string` (or your codegen's date type).
+  - **Enums**: `Customer.emailMarketingState` is `EmailMarketingState!`, `ProductAttributeDefinition.fillingMode/billingMode` are typed enums, `ProductAttributeOption.surchargeType` is `AttributeOptionSurchargeType`, `Shop.currencyCode` / `paymentCurrencies` / `supportedCurrencies` use `CurrencyCode`, `Shop.defaultLanguage` / `supportedLanguages` use `LanguageCode`, `Currency.code` is `CurrencyCode`, `Currency.symbolPosition` is the new `CurrencySymbolPosition` enum (`BEFORE` / `AFTER`).
+  - **Structured errors**: `WishlistPayload.userErrors`, `RedeemRewardPayload.userErrors`, `GenerateReferralCodePayload.userErrors` are now `[UserError!]!` (`{ message, code, field }`) instead of `[String!]!`. Replace `userErrors[0]` with `userErrors[0].message` in your error handling.
+
+  ### New: `ProductReview.unhelpfulCount`
+
+  Storefronts can now render upvote/downvote counts side-by-side without computing one from the other.
+
+  ### Cross-domain cookie auth — `credentials: 'include'`
+
+  The SDK GraphQL transport now sends `credentials: 'include'` on every request. If your storefront runs on a domain different from the API and uses cookie auth, the API CORS configuration must allow your origin (with `Access-Control-Allow-Credentials: true`). Same-origin deployments are unaffected.
+
+  ### Auth store no longer persists `accessToken` to localStorage (XSS hardening)
+
+  `useAuthStore` only persists `customer` and `isAuthenticated` to localStorage. The token lives in the httpOnly cookie (browser auto-sent) plus in-memory store state (set by login flow). After a page refresh, browser-based storefronts call `GET /api/auth/whoami` (new BFF route shipped with the template) to rehydrate `customer` info — the cookie continues to authenticate every subsequent GraphQL request transparently.
+
+  The `auth-storage` localStorage version bumps from `v2` to `v3`; the migrate handler clears legacy persisted tokens on first load.
+
+  ### New: `createWhoamiHandler()` factory
+
+  Exports from `@doswiftly/storefront-sdk`. Pair with the `app/api/auth/whoami/route.ts` example shipped with the CLI template:
+
+  ```typescript
+  // app/api/auth/whoami/route.ts
+  import { createWhoamiHandler } from "@doswiftly/storefront-sdk";
+  export const GET = createWhoamiHandler({
+    apiUrl: process.env.NEXT_PUBLIC_API_URL,
+    shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG,
+  });
+  ```
+
+  ### `AuthClient` (low-level core API) — drop token argument
+
+  ```typescript
+  // Before
+  authClient.logout(token);
+  authClient.renewToken(token);
+  authClient.getCustomer(token);
+
+  // After
+  authClient.logout(); // auth via cookie/Bearer in middleware
+  authClient.renewToken();
+  authClient.getCustomer();
+  ```
+
+  ### Template (`@doswiftly/cli` scaffolded storefront)
+
+  The Next.js template now uses cookie-first auth end-to-end:
+  - `lib/graphql/hooks.ts` — query/mutation hooks no longer pass `customerAccessToken`
+  - `lib/graphql/server.ts` — server-side helper reads `customerAccessToken` cookie via `next/headers` and forwards as `Authorization: Bearer`
+  - `app/api/auth/whoami/route.ts` (new) — BFF route for `customer` rehydration after page refresh
+  - `hooks/use-auth-sync.ts` — rewritten to use the whoami endpoint instead of token desync detection
+  - Auth-gated React components/pages now check `isAuthenticated` instead of `accessToken`
+
+  ### Wishlist pagination + GiftCard read surface
+  - **`wishlists`** is now a paginated **`WishlistConnection`** (Relay pattern). Replace direct array selection with `nodes` (shortcut) or `edges { cursor node { ... } }`. Supports `first: Int = 20` and `after: String` cursor arguments.
+
+  ```graphql
+  # Before (4.x)
+  query Wishlists {
+    wishlists {
+      id
+      name
+      itemCount
+      items {
+        id
+        productId
+      }
+    }
+  }
+
+  # After (5.x)
+  query Wishlists($first: Int = 20, $after: String) {
+    wishlists(first: $first, after: $after) {
+      nodes {
+        id
+        name
+        itemCount
+        items {
+          id
+          productId
+        }
+      }
+      pageInfo {
+        hasNextPage
+        hasPreviousPage
+        startCursor
+        endCursor
+      }
+      totalCount
+    }
+  }
+  ```
+
+  - **`giftCard(code)`** read query no longer wraps result in `GiftCardPayload`. Returns nullable `GiftCard` directly (`null` = not found). The wrapper pattern `{ giftCard, userErrors }` is reserved for mutations only.
+
+  ```graphql
+  # Before (4.x)
+  query GiftCard($code: String!) {
+    giftCard(code: $code) {
+      giftCard {
+        id
+        maskedCode
+        balance {
+          amount
+          currencyCode
+        }
+      }
+      userErrors {
+        message
+        code
+      }
+    }
+  }
+
+  # After (5.x)
+  query GiftCard($code: String!) {
+    giftCard(code: $code) {
+      id
+      maskedCode
+      balance {
+        amount
+        currencyCode
+      }
+    }
+  }
+  ```
+
+  - **`GiftCard.transactions`** field removed from storefront API entirely. The field always returned `[]` (PII safety: transactions contain `orderId` / `customerId` not safe to expose at anonymous code-lookup endpoint). Schema now rejects the selection at validation time. Storefronts that selected this field will get a clear schema error instead of an always-empty array.
+
+  ### Filter scalars + structured Weight type
+  - **`Filter.id` and `FilterValue.id`** are now `ID!` (previously `String!`). Codegen treats `ID` identically to `String` in TypeScript, but downstream client tooling (Relay-style caches, normalized stores) gains proper identity semantics for entity deduplication.
+  - **`FilterValue.input`** changed from `String!` (JSON-stringified payload) to **`JSON!`** (new opaque structured scalar). Storefronts no longer need to `JSON.parse(filterValue.input)` before passing it to the `filters` argument — the value arrives as a structured object ready to use:
+
+  ```graphql
+  # Before (4.x) — client-side parsing required
+  filterValue.input  # "{\"variantOption\":{\"name\":\"Color\",\"value\":\"Red\"}}"
+  JSON.parse(filterValue.input)
+
+  # After (5.x) — directly passable as filters arg element
+  filterValue.input  # { variantOption: { name: "Color", value: "Red" } }
+  ```
+
+  - **`ProductVariant.weight`** changed from `Float` (raw grams, implicit unit per docs) to **`Weight { value: Float!, unit: WeightUnit! }`** structured type with the new `WeightUnit` enum (`GRAMS | KILOGRAMS | OUNCES | POUNDS`). The API always returns `unit: GRAMS` (canonical storage unit). Storefronts can convert to the preferred unit for shipping or checkout UI without hardcoding "grams" anywhere in the codebase:
+
+  ```graphql
+  # Before (4.x)
+  variant { weight }  # 250 (Float, "grams" implicit per docs)
+
+  # After (5.x)
+  variant { weight { value unit } }  # { value: 250, unit: GRAMS }
+  ```
+
+  ### Removed: legacy `x-customer-access-token` header
+
+  The legacy `x-customer-access-token` header reader (which never had a matching SDK middleware) is removed from the API. If a custom integration was relying on it, switch to `Authorization: Bearer <token>`.
+
+  ### Field & mutation naming sweep
+
+  Several renames have landed in this release. Update queries and variables accordingly:
+  - **Cart mutations**: `cartLinesAdd` → `cartAddLines`, `cartLinesUpdate` → `cartUpdateLines`, `cartLinesRemove` → `cartRemoveLines`, `cartNoteUpdate` → `cartUpdateNote`, `cartAttributesUpdate` → `cartUpdateAttributes`, `cartBuyerIdentityUpdate` → `cartUpdateBuyerIdentity`, `cartDiscountCodesUpdate` → `cartApplyDiscountCodes`. Resource-id arg renamed `cartId` → `id` on mutations (the foreign-key `CheckoutCreateInput.cartId` keeps its name).
+  - **Checkout mutations**: `checkoutId` → `id`. `checkoutSelectShippingRate` arg `shippingRateHandle` → `rateId`.
+  - **Wishlist mutations**: `wishlistId` → `id`.
+  - **Field renames on output types**:
+    - `Product.productType` → `Product.category` (free-text classification field; the `Product.type: ProductTypeEnum` enum field is unchanged)
+    - `ProductVariant.quantityAvailable` → `availableStock` (disambiguates effective availability from raw inventory)
+    - `ProductOption.position` / `ProductOptionValue.position` → `sortOrder`
+    - `Customer.numberOfOrders` → `orderCount`
+    - `WishlistItem.priceAtAdd` → `priceWhenAdded`
+    - `Shop.primaryDomain.sslEnabled` → `isSslEnabled` (boolean prefix convention)
+    - `Shipment.estimatedDeliveryDate` → `estimatedDeliveryAt`
+    - `StoreAvailability.pickUpTime` → `pickupTime`
+    - `Location.pickupEnabled` → `supportsPickup`
+    - `ShopPage.bodySummary` → `excerpt`
+  - **New field**: `ProductReview.unhelpfulCount` — render upvote/downvote counts side-by-side without computing one from the other.
+  - **`UserError`/payload selection set** is now required on `WishlistPayload.userErrors` (and other payloads switched to typed `[UserError!]!`). Bare `userErrors` selection without a sub-selection is rejected by schema validation.
+  - **Error code stability**: typed error codes (e.g. `CART_NOT_FOUND`, `CUSTOMER_TOKEN_INVALID`) are now locale-agnostic — they remain stable across language responses (in earlier versions the mapping silently regressed when a translated message lost a specific English keyword).
+
+  ### Unified `UserError` across all mutation payloads
+
+  Per-domain user-error types (`CartUserError`, `CheckoutUserError`, `CustomerUserError`) have been replaced by the single generic `UserError` type used everywhere. Error codes remain unique per domain (e.g. `CART_NOT_FOUND` vs `CUSTOMER_NOT_FOUND` vs `CHECKOUT_PAYMENT_FAILED`) — string comparison on the `code` field gives the same branching power without per-domain type proliferation.
+
+  Customer mutation payloads also rename the error field from `customerUserErrors` to `userErrors` for consistency with cart, checkout, wishlist, and other payloads:
+
+  ```graphql
+  # Before (4.x)
+  mutation CartCreate {
+    cartCreate {
+      userErrors {
+        ...CartUserError
+      }
+    }
+  }
+  mutation CustomerLogin {
+    customerLogin {
+      customerUserErrors {
+        ...CustomerUserError
+      }
+    }
+  }
+  mutation CheckoutCreate {
+    checkoutCreate {
+      userErrors {
+        ...CheckoutUserError
+      }
+    }
+  }
+
+  # After (5.x)
+  mutation CartCreate {
+    cartCreate {
+      userErrors {
+        ...UserError
+      }
+    }
+  }
+  mutation CustomerLogin {
+    customerLogin {
+      userErrors {
+        ...UserError
+      }
+    }
+  }
+  mutation CheckoutCreate {
+    checkoutCreate {
+      userErrors {
+        ...UserError
+      }
+    }
+  }
+  ```
+
+  Update the shared `UserError` fragment as the only error fragment you need:
+
+  ```graphql
+  fragment UserError on UserError {
+    message
+    code # namespaced string — e.g. "CART_NOT_FOUND", "CUSTOMER_TOKEN_INVALID"
+    field # path to the input field that caused the error
+  }
+  ```
+
+  Client TypeScript change after codegen: `userErrors[i].code` is now `string | null` instead of a strongly-typed enum (`CartErrorCode` / `CheckoutErrorCode` / `CustomerErrorCode`). Switch from `code === CartErrorCode.CART_NOT_FOUND` to `code === 'CART_NOT_FOUND'`. The full list of namespaced codes per domain is documented in the schema descriptions on each payload's `userErrors` field.
+
+  ### Address `country` field — `CountryCode` enum on inputs
+
+  Address input types (`MailingAddressInput`, `CheckoutAddressInput`, `ShippingAddressInput`) now use the `CountryCode` enum for the `country` field instead of `String` with regex validation. This matches the pattern already used by output types (`MailingAddress.countryCode: CountryCode`) and gives client codegen a strongly-typed enum value instead of a free-form string:
+
+  ```graphql
+  # Before (4.x)
+  input CheckoutAddressInput {
+    country: String! # validated server-side via @Matches(/^[A-Z]{2}$/)
+  }
+
+  # After (5.x)
+  input CheckoutAddressInput {
+    country: CountryCode! # GraphQL enum — invalid values rejected at validation
+  }
+  ```
+
+  Output types keep two distinct fields where applicable: `country` (display name, e.g. "Polska") + `countryCode` (typed enum, e.g. `PL`).
+
+  ### Address fields — international naming
+
+  `MailingAddress`, `LocationAddress`, `ShopAddress`, and the address inputs (`MailingAddressInput`, `CheckoutAddressInput`) now use international neutral terminology instead of US/Canadian-centric field names. The new names match common international postal conventions and the underlying database column names:
+
+  | Before (4.x)   | After (5.x)   |
+  | -------------- | ------------- |
+  | `address1`     | `streetLine1` |
+  | `address2`     | `streetLine2` |
+  | `province`     | `state`       |
+  | `provinceCode` | `stateCode`   |
+  | `zip`          | `postalCode`  |
+
+  ```graphql
+  # Before (4.x)
+  fragment MailingAddress on MailingAddress {
+    address1
+    address2
+    province
+    zip
+  }
+
+  # After (5.x)
+  fragment MailingAddress on MailingAddress {
+    streetLine1
+    streetLine2
+    state
+    postalCode
+  }
+
+  # Mutation input
+  mutation AddAddress($input: MailingAddressInput!) {
+    customerAddAddress(input: $input) { ... }
+  }
+  # variables (4.x): { address1: "...", province: "...", zip: "..." }
+  # variables (5.x): { streetLine1: "...", state: "...", postalCode: "..." }
+  ```
+
+  **Backward-compat for existing orders**: `Order.shippingAddress` and `Order.billingAddress` are stored as JSONB snapshots at order placement time. Snapshots created under the previous API contain `address1` / `province` / `zip`; new snapshots use `streetLine1` / `state` / `postalCode`. The `MailingAddress` resolver reads new field names first and falls back to legacy names — historical orders continue to render correctly. Frontend codegen will emit the new field names; templates rendering historical orders gain the new schema without data migration. Backward-compat fallback is scheduled for removal once historical snapshots reach end-of-life (~2-3 years).
+
+  **`MailingAddress.formatted`** (country-aware ordered lines) continues to work — internal helper updated to use new field names. Storefronts rendering addresses via `formatted` need no changes.
+
+  ### Costs and totals — nested wrappers everywhere
+
+  Cart, Checkout, and Order now expose monetary breakdowns via dedicated wrapper types instead of flat fields on the parent. This adds a single hop in selections but makes adding new cost dimensions (duty, fees, surcharges) non-breaking, and brings symmetry across the three checkout-flow stages:
+
+  ```graphql
+  # CartCost — drop "Amount" suffix from field names (Money type implies amount)
+  fragment CartCost on CartCost {
+    subtotal {
+      ...Money
+    } # was: subtotalAmount
+    total {
+      ...Money
+    } # was: totalAmount
+    totalTax {
+      ...Money
+    } # was: totalTaxAmount
+    totalDuty {
+      ...Money
+    } # was: totalDutyAmount
+    checkoutCharge {
+      ...Money
+    } # was: checkoutChargeAmount
+  }
+
+  # CartLineCost — drop "Amount" suffix + "amountPerQuantity" → "pricePerUnit"
+  fragment CartLineCost on CartLineCost {
+    pricePerUnit {
+      ...Money
+    } # was: amountPerQuantity
+    subtotal {
+      ...Money
+    } # was: subtotalAmount
+    total {
+      ...Money
+    } # was: totalAmount
+    compareAtPricePerUnit {
+      ...Money
+    } # was: compareAtAmountPerQuantity
+  }
+
+  # CheckoutCost — NEW wrapper, replaces flat checkout fields
+  query Checkout {
+    checkout {
+      cost {
+        subtotal {
+          ...Money
+        } # was: Checkout.subtotalPrice
+        total {
+          ...Money
+        } # was: Checkout.totalPrice
+        totalTax {
+          ...Money
+        } # was: Checkout.totalTax (now nested)
+        totalShipping {
+          ...Money
+        } # was: Checkout.totalShippingPrice
+        totalDiscounts {
+          ...Money
+        } # was: Checkout.totalDiscounts (now nested)
+      }
+    }
+  }
+
+  # OrderTotals — NEW wrapper, replaces flat order fields
+  query CustomerOrder {
+    customerOrder {
+      totals {
+        subtotal {
+          ...Money
+        } # was: Order.subtotalPrice
+        total {
+          ...Money
+        } # was: Order.totalPrice
+        totalTax {
+          ...Money
+        } # was: Order.totalTax (now nested)
+        totalShipping {
+          ...Money
+        } # was: Order.totalShipping (now nested)
+      }
+    }
+  }
+
+  # CheckoutLineItem — line price field renames
+  fragment CheckoutLineItem on CheckoutLineItem {
+    pricePerUnit {
+      ...Money
+    } # was: unitPrice
+    total {
+      ...Money
+    } # was: totalPrice
+  }
+  ```
+
+  Conversion-transparency opt-in fields (`*WithConversion`) are renamed in lockstep:
+  - `subtotalAmountWithConversion` → `subtotalWithConversion`
+  - `totalAmountWithConversion` → `totalWithConversion`
+  - `amountPerQuantityWithConversion` → `pricePerUnitWithConversion`
+  - ...and so on.
+
+  ### Cart line: simplified shape — `variant` replaces `merchandise` union
+
+  `CartLine.merchandise: Merchandise!` (a union currently with only `ProductVariant` member) and the `BaseCartLine` interface have been removed. `CartLine` is now a concrete type with a direct `variant: ProductVariant!` field — no union wrapper, no inline fragments needed:
+
+  ```graphql
+  # Before (4.x)
+  fragment CartLine on CartLine {
+    id
+    quantity
+    merchandise {
+      ... on ProductVariant {
+        id
+        title
+        price { amount currencyCode }
+      }
+    }
+    cost { ... }
+  }
+
+  # After (5.x) — direct field, no union/inline fragment
+  fragment CartLine on CartLine {
+    id
+    quantity
+    variant {
+      id
+      title
+      price { amount currencyCode }
+    }
+    cost { ... }
+  }
+  ```
+
+  Cart connection types renamed for the same reason: `BaseCartLineConnection` / `BaseCartLineEdge` → `CartLineConnection` / `CartLineEdge`. Update fragment selections accordingly:
+
+  ```graphql
+  # Before (4.x)
+  query Cart($id: ID!) {
+    cart(id: $id) {
+      lines(first: 10) {
+        edges {
+          node {
+            ... on CartLine {
+              id
+            }
+          }
+        }
+        nodes {
+          ... on CartLine {
+            id
+          }
+        }
+      }
+    }
+  }
+
+  # After (5.x)
+  query Cart($id: ID!) {
+    cart(id: $id) {
+      lines(first: 10) {
+        edges {
+          node {
+            id
+          }
+        }
+        nodes {
+          id
+        }
+      }
+    }
+  }
+  ```
+
+  Cart line input renamed `merchandiseId` → `variantId` (consistent with the output field):
+
+  ```graphql
+  # Before (4.x)
+  mutation CartAddLines($id: ID!, $lines: [CartLineInput!]!) {
+    cartAddLines(id: $id, lines: $lines) { ... }
+  }
+  # variables: { lines: [{ merchandiseId: "uuid", quantity: 1 }] }
+
+  # After (5.x)
+  mutation CartAddLines($id: ID!, $lines: [CartLineInput!]!) {
+    cartAddLines(id: $id, lines: $lines) { ... }
+  }
+  # variables: { lines: [{ variantId: "uuid", quantity: 1 }] }
+  ```
+
+  The `variantId` name also matches the `userErrors[].field` path returned for input-related errors (e.g. `field: ["lines", "variantId"]`).
+
+  ### Recommendations: top-level queries replaced by field resolvers
+
+  Two top-level queries were removed. Use the field resolvers on the parent entity instead — they return identical payloads with automatic context inheritance, cleaner cache invalidation, and a clearer parent-not-found vs empty-recommendations distinction:
+
+  ```graphql
+  # Before (4.x)
+  query SimilarProducts($productId: String!, $first: Int) {
+    similarProducts(productId: $productId, first: $first) {
+      items {
+        product {
+          id
+          title
+        }
+        type
+        score
+      }
+      totalCount
+    }
+  }
+  query CartRecommendations($cartId: String!, $first: Int) {
+    cartRecommendations(cartId: $cartId, first: $first) {
+      frequentlyBoughtTogether {
+        product {
+          id
+        }
+      }
+      youMayAlsoLike {
+        product {
+          id
+        }
+      }
+    }
+  }
+
+  # After (5.x) — same payloads, parent-scoped
+  query Product($id: ID!, $first: Int) {
+    product(id: $id) {
+      recommendations(first: $first) {
+        items {
+          product {
+            id
+            title
+          }
+          type
+          score
+        }
+        totalCount
+      }
+    }
+  }
+  query Cart($id: ID!, $first: Int) {
+    cart(id: $id) {
+      recommendations(first: $first) {
+        frequentlyBoughtTogether {
+          product {
+            id
+          }
+        }
+        youMayAlsoLike {
+          product {
+            id
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  For broader product-scoped recommendations driven by intent (`SIMILAR | COMPLEMENTARY | UPSELL`), use the existing top-level `productRecommendations(productId, intent, limit)` query, which returns a flat `[Product!]!` payload — separate surface from the rich `Product.recommendations` field (which carries metadata `type`, `score`, `reason` per item).
+
 ## 4.7.2
 
 ### Patch Changes