@doswiftly/storefront-operations 5.5.0 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,783 @@
 # Changelog
 
+## 6.1.0
+
+### Minor Changes
+
+- fbc6a94: Rozszerzono `CustomerUpdateInput` w GraphQL Storefront API o pełen kontrakt B2B — storefront developer może teraz zaktualizować dane firmowe klienta (nazwa firmy, NIP, VAT UE, REGON) oraz typ klienta (osoba fizyczna / firma) bezpośrednio przez mutację `customerUpdate`. Wcześniej te pola były dostępne wyłącznie z poziomu panelu administratora.
+
+  **Nowe pola Input**:
+  - `customerType: CustomerType` — `INDIVIDUAL` (B2C) lub `COMPANY` (B2B). Opcjonalne — gdy pominięte, backend dokona inteligentnej inferencji (patrz „Strict hybrid" niżej).
+  - `companyName: String` — nazwa firmy (wymagana dla `COMPANY`).
+  - `taxId: String` — polski NIP (10 cyfr z sumą kontrolną).
+  - `vatNumber: String` — numer VAT UE (np. `PL5260250274`, `DE123456789`).
+  - `regon: String` — polski REGON (9 lub 14 cyfr z sumą kontrolną).
+
+  **Nowe pola czytelne na typie `Customer`** (dostępne automatycznie przez fragment `Customer`):
+  - `customerType`, `companyName`, `taxId`, `vatNumber`, `regon`.
+
+  **Strict hybrid — kontrakt aktualizacji typu klienta**:
+  1. Jeśli `customerType` jest w payloadzie, wygrywa explicit (nawet jeśli inne pola sugerowałyby co innego).
+  2. Jeśli `customerType` jest pominięty, backend dokonuje implicit upgrade `INDIVIDUAL → COMPANY` tylko gdy podano niepuste pole firmowe. Implicit downgrade nigdy się nie zdarza — wymaga jawnego `customerType: INDIVIDUAL`.
+  3. Każde efektywne `COMPANY` (jawne lub przez inferencję) wymaga niepustej `companyName` — w przeciwnym razie mutacja zwraca `userErrors` z kodem `CUSTOMER_UPDATE_FAILED`.
+  4. `undefined` w payloadzie = brak zmiany pola; `null` = świadome czyszczenie wartości.
+
+  **Walidacja format**: NIP, VAT UE i REGON walidowane przez wspólny dekorator (regex + algorytm sumy kontrolnej). Niepoprawny format → błąd walidacji input'u GraphQL.
+
+  **Concurrency safety**: `customerUpdate` używa optimistic locking — równoczesne aktualizacje tego samego klienta (np. profil w wielu zakładkach) zwracają `userErrors` z message o konflikcie wersji zamiast cichego nadpisania.
+
+  **Use cases dla storefront-developera**:
+  - Strona „moje dane" w sklepie — pełen formularz B2C/B2B z radio pickerem typu klienta.
+  - Checkout pre-fill — możliwość uzupełnienia danych do faktury bez wchodzenia do panelu sklepu.
+  - Rejestracja firm / sole-trader scenarios — implicit upgrade gdy klient wpisze NIP w polu opcjonalnym.
+
+  **Test coverage**: 8 service-level scenariuszy (każda z 4 reguł strict hybrid + concurrency conflict + audit trail + EventEmitter) + 3 GraphQL surface scenariusze (full B2B payload, error mapping, format validation).
+
+- c91b700: Rozszerzono storefront GraphQL API o pełną obsługę zgód marketingowych — storefront-developer może teraz zbudować checkbox marketingu przy rejestracji, toggle preferencji w panelu klienta, oraz widget „zapisz się do newslettera" w stopce sklepu. Wszystkie 3 use case'y działają end-to-end (z double opt-in dla anonimowego widget'u i audit trail dla zgodności z RODO).
+
+  **Nowe pola Input (signup)** — `CustomerCreateInput`:
+  - `acceptsMarketing: Boolean` — checkbox marketingu przy `customerSignup`. `true` → state SUBSCRIBED bezpośrednio (signup = adres potwierdzony). `false`/`null` → bez zmian (NOT_SUBSCRIBED).
+  - `marketingOptInLevel: MarketingOptInLevel` (`SINGLE_OPT_IN | CONFIRMED_OPT_IN | UNKNOWN`) — opcjonalny override. Ustaw `CONFIRMED_OPT_IN` aby wymusić double opt-in (state PENDING + automatyczny email z linkiem potwierdzającym).
+
+  **Nowe pole Input (panel klienta)** — `CustomerUpdateInput`:
+  - `acceptsMarketing: Boolean` — toggle dla zalogowanego klienta. `true` → SUBSCRIBED, `false` → UNSUBSCRIBED. Działa tylko z access tokenem (auth-required mutation).
+
+  **Nowe mutacje (newsletter widget — guest, bez auth)**:
+  - `customerSubscribeToMarketing(input: { email, marketingOptInLevel? }): SubscribeToMarketingPayload` — anonimowy opt-in. Backend zawsze stosuje double opt-in (state PENDING → email z linkiem → klik → SUBSCRIBED) niezależnie od `marketingOptInLevel` w input — bez tego ktoś mógłby zapisywać cudze adresy.
+  - `customerUnsubscribeFromMarketing(input: { email }): UnsubscribeFromMarketingPayload` — anonimowy opt-out, idempotent.
+
+  **Payloady — `accepted: Boolean!` semantyka (anti-enumeration)**: obie mutacje guest zwracają `accepted: true` niezależnie od stanu emaila (registered / nieistniejący / już SUBSCRIBED). Storefront-developer dostaje deterministyczny shape response — atakujący nie może przez to API enumerate'ować adresów ani odróżnić invalid email format od valid (orzeczenie: też swallowed jako `accepted: true`). Stan końcowy zawsze widoczny przez `Customer.emailMarketing` (gdy klient autoryzowany).
+
+  **Mutacje C są throttlowane per IP** (limit 10/min) i pod botprotection guardem — storefront powinien zintegrować odpowiedni captcha provider. Email-bombing przez wpisywanie cudzego adresu w widget'cie blokowany dodatkowo na poziomie backendu (max 1 email potwierdzenia na adres na dobę).
+
+  **Strict-hybrid kontrakt update'u**:
+  - Brak pola w Input = no-op dla tego pola (zachowanie back-compat dla istniejących storefrontów bez nowych pól).
+  - `acceptsMarketing: null` na auth'd customer = explicit no-change (nie unsubscribe — do unsubscribe użyj `false`).
+
+  **Double opt-in dla widget'u — co dzieje się po kliknięciu „Zapisz"**:
+  1. Mutation `customerSubscribeToMarketing` → backend zapisuje stan PENDING + uruchamia wysłanie maila potwierdzającego.
+  2. Email idzie z domeny sklepu (per-shop branding — `From: "Sklep <noreply@shop-domain>"`) z CTA buttonem prowadzącym pod URL potwierdzający (token JWT 24h).
+  3. Klient klika link → backend transitionuje stan z PENDING na SUBSCRIBED.
+  4. Po SUBSCRIBED storefront może wysyłać maile marketingowe (gate consent jest egzekwowane przez backend pre-send).
+
+  **Read surface — `Customer.emailMarketing: EmailMarketingState!`** (pole już istniejące, dla auth'd customer): storefront odczytuje `NOT_SUBSCRIBED | PENDING | SUBSCRIBED | UNSUBSCRIBED | INVALID | REDACTED` aby zdecydować jak renderować checkbox/toggle w UI (np. PENDING = pokaż „sprawdź email", SUBSCRIBED = checkbox zaznaczony).
+
+  **Use cases**:
+  - Strona `/auth/register` — checkbox „Chcę otrzymywać newsletter" zapisany razem z signupem.
+  - Strona `/account/preferences` — toggle marketing on/off dla zalogowanego klienta.
+  - Stopka layoutu sklepu — input email + button „Zapisz się" → mutation guest subscribe → automatyczny email z linkiem potwierdzającym.
+
+  **Suppression list awareness**: jeśli adres trafił wcześniej na suppression list (hard bounce / complaint feedback), kolejna subskrypcja zwraca `accepted: true` ale email potwierdzający nie wychodzi. Klient pozostanie w stanie PENDING — admin sklepu musi ręcznie odblokować adres przez panel administracyjny.
+
+## 6.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).
+
+### Minor Changes
+
+- e2e23ee: Wave 3.1/3.2 — Customer email flows end-to-end: welcome email po rejestracji + URL-based activation + URL-based password reset.
+
+  **Nowe mutations**:
+  - `customerActivateByUrl(activationUrl: String!, password: String!): CustomerActivateByUrlPayload!` — admin tworzy customer'a bez hasła → email aktywacyjny → klient klika link → ustawia hasło → auto-login.
+  - `customerResetByUrl(resetUrl: String!, password: String!): CustomerResetByUrlPayload!` — modern UX dla password reset (klik link w mailu zamiast ręcznego kopiowania tokenu).
+
+  **Nowe error codes** (`CustomerErrorCode` enum):
+  - `TOKEN_USED` — token został już wykorzystany (one-shot semantics).
+  - `INVALID_URL` — URL aktywacji/resetu malformed.
+
+  **Welcome email po `customerCreate`**: rejestracja triggeruje branded per-shop welcome email — outbox-driven, fully async (resolver odpowiada natychmiast, email queued via worker).
+
+  **Password reset email**: dokończenie `customerRecover` flow (wcześniej był TODO line 499). Plaintext token NIE przechodzi przez RabbitMQ — worker generuje token po consume outbox event.
+
+  **Bezpieczeństwo**:
+  - 256-bit random tokens (`CryptoHelper.generateToken(32)`), SHA-256 hash storage w `customer_activation_tokens` table.
+  - TTL 24h dla activation, 1h dla password reset.
+  - Atomic UPDATE z `AND used_at IS NULL` zapobiega replay attack (race condition).
+  - `customerResetByUrl` + `customerReset` (legacy) bindują token do customer ID — defense vs forged URL pairing valid token z innym customer'em.
+  - Rate limiting (`@Throttle` 10 req/10min prod, bot protection guard) na nowych mutations.
+  - Anti-enumeration: `customerRecover` nieistniejący email → ZERO outbox events (silent fake-success).
+
+  **Architektura** (per `event-driven.md` + `feedback_outbox_docs_first.md`):
+  - `TenantOutboxService.append({ tx })` w `prisma.$transaction` z domain mutations (atomic — żadnych orphaned emails na rollback).
+  - 3 nowe outbox event types: `CUSTOMER_REGISTERED`, `CUSTOMER_ACTIVATION_REQUESTED`, `CUSTOMER_PASSWORD_RESET_REQUESTED`.
+  - `CustomerEventWorker` (RabbitMQ consumer) z `processed_customer_events` idempotency dedup + `OnModuleDestroy` graceful drain.
+  - `CommerceEmailService` extended o `sendCustomerWelcome` + `sendCustomerActivation` (per-shop branded, suppression/consent/rate limit reused).
+
+  **Nowe templates** w `templates/commerce/`: `customer_welcome.hbs`, `customer_account_activation.hbs`, `customer_password_reset.hbs` — 30+ i18n keys (PL+EN).
+
+  **Test coverage**: 6 nowych integration specs, 40 scenariuszy (registration outbox, welcome worker, activation E2E z security cases, reset URL z token mismatch + race, worker edge cases, email service contract). Plus 2 nowe scenariusze w istniejącym `customer.graphql.spec.ts` dla outbox event assertion.
+
+  **Wymagania storefront-developera**: dwie nowe strony `/account/activate` i `/account/reset` które parsują `window.location.href` i wywołują odpowiednie mutation z całym URL-em jako argument.
+
+- 0048bf9: Dodano pole `tags: [String!]!` na typie `Customer` w GraphQL Storefront API — segmentacja klientów po stronie storefront-developera.
+
+  **Nowe pole**:
+  - `Customer.tags` — array tagów segmentacyjnych (np. `["vip", "wholesale", "b2b"]`). Backend ma już kolumnę `customers.tags` z GIN index dla performance.
+
+  **Use case dla storefront-developera**:
+  - Warunkowy rendering UI w `/account` — badge "VIP" gdy `tags.includes('vip')`.
+  - Cart pricing logic — dostęp do private/wholesale produktów dla klientów z odpowiednim tagiem.
+  - Customer-specific banners / promocje na storefront.
+
+  **Side fix**:
+  - Fragment `Customer` używa teraz `numberOfOrders: UnsignedInt64!` (zgodnie ze schema po Wave 2.6) zamiast nieaktualnego `ordersCount`.
+
+  **Test coverage**: 4 nowe E2E integration tests (empty array dla nowo utworzonego, single tag, multi-tag w prawidłowej kolejności, auth boundary — brak leak'u tagów dla unauthenticated requests).
+
+- 9a4a447: Dodano `predictiveSearch(query, limit)` query do GraphQL Storefront API — typeahead suggestions dla search bara w storefront UI.
+
+  **Nowa query**:
+  - `predictiveSearch(query: String!, limit: Int = 10): PredictiveSearchResult!`
+  - Returns: `{ products: [Product!]!, queries: [SearchQuerySuggestion!]! }` gdzie `SearchQuerySuggestion = { text, styledText }`
+  - `styledText` zawiera `<mark>` highlights dla query matching (gotowe do `dangerouslySetInnerHTML` po stronie storefronta)
+
+  **Use case dla storefront-developera**:
+  - Search bar typeahead — debounce 200ms client-side, server respondzie <50ms (wykorzystuje istniejący PostgreSQL FTS GIN index)
+  - 10 produktów + 5 query suggestions per call (server-side cap)
+  - Fallback gdy 0 wyników: pokaz `queries[]` jako "did you mean" suggestions
+
+  **Bezpieczeństwo**:
+  - Query length capped na 100 chars (DoS protection)
+  - `styledText` HTML-escaped — tylko `<mark>`/`</mark>` dozwolone (XSS guard, defense-in-depth)
+  - Tylko `ACTIVE` + `PUBLIC` visibility produkty surfaced (no leak of HIDDEN/BUNDLE_ONLY)
+
+  **Test coverage**: 10 E2E integration scenariuszy (prefix match, polskie znaki, multi-word AND, empty query, limit cap, visibility/status filters, XSS safety, dedup).
+
 ## 5.5.0
 
 ### Minor Changes