@doswiftly/storefront-sdk 4.7.1 → 5.0.0

package/CHANGELOG.md

@@ -0,0 +1,788 @@
+# Changelog
+
+## 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
+
+- 7846bdb: Fix `doswiftly dev` port pre-flight on Windows (and any host where another
+  process binds the port on IPv6 `::` only): the probe now checks IPv4 and
+  IPv6 in parallel and requires BOTH free before marking a port as available.
+  Previously an IPv6-only conflict (common on Windows, where Next.js binds
+  `::` by default) slipped past the IPv4-only probe — the banner advertised
+  `http://localhost:3000` and the framework immediately crashed with
+  `EADDRINUSE :::3000`. With this fix `doswiftly dev` falls back to the next
+  free port (3001, 3002, …) as documented.
+
+  Also ship `CHANGELOG.md` inside the npm tarball. Previous releases packed
+  only `dist`/`bin`/`templates` (and `schema.graphql`/operations for
+  `storefront-operations`, `dist` for `storefront-sdk`), so consumers who
+  `npm install @doswiftly/cli` got a version number with no user-visible
+  release notes.
+
+Wszystkie istotne zmiany w `@doswiftly/storefront-sdk` sa dokumentowane w tym pliku.
+Format oparty na [Keep a Changelog](https://keepachangelog.com/pl/1.1.0/).
+Wersjonowanie zgodne z [Semantic Versioning](https://semver.org/).
+
+## [4.7.1] - 2026-04-17
+
+### Security
+
+- Bump `next` devDependency range to `^16.2.3` (GHSA-q4gf-8mx6-v5v3 — Next.js DoS via Server Components). Brak zmian API SDK.
+
+## [4.7.0] - 2026-04-14
+
+### Added
+
+- **`CartAttributeSelectionInput`** — nowy typ mirrorujący GraphQL `AttributeSelectionInput` dla konfiguratorów produktu (Faza 1 Unified Product Configurator).
+- **`CartLineInput.attributeSelections`** — opcjonalne customer-filled atrybuty (Finiszer, nr telefonu serwisu itp.). Backend waliduje i snapshotuje pole `surcharge_amount` / `tax_rate`.
+- **`CartLineUpdateInput.attributeSelections`** — update selekcji po stronie koszyka (`null` = preserve, `[]` = clear, tablica = replace).
+
+### Changed
+
+- Mutacje `cartLinesAdd` / `cartLinesUpdate` przekazują teraz `attributeSelections` przez GraphQL variables (bez zmian w treści mutacji — typ po stronie schematu backendu).
+
+## [4.6.0] - 2026-04-11
+
+### Breaking Changes
+
+- **Image fragment**: `url` field now includes `transform: { maxWidth: 300 }` argument — cart images return CDN-resized thumbnails instead of full-size originals
+- **ImageData interface**: added `thumbhash?: string | null` field
+- **CartLineMerchandise.image**: added `thumbhash` field to image shape
+
+### Added
+
+- **Image transforms in cart operations**: CDN serves correctly-sized thumbnails (300px) instead of full originals. Reduces bandwidth ~10x for cart page.
+- **ThumbHash support**: `Image` fragment now requests `thumbhash` field — base64-encoded perceptual placeholder (~40 chars). Decode with `thumbHashToDataURL()` for instant blur previews.
+- **`thumbHashToDataURL(base64Hash)`**: New export from core — decodes ThumbHash to `data:image/bmp;base64,...` URL for Next.js `blurDataURL` prop. Pure math, zero deps, framework-agnostic.
+- **AVIF auto-negotiation**: No `preferredContentType` hardcoded — imgproxy auto-serves AVIF/WEBP based on browser `Accept` header.
+
+## [4.5.0] - 2026-04-11
+
+### Breaking Changes
+
+- **CartClient types**: `CartCost` and `CartLineCost` price fields changed from `Money` to `PriceMoney` (adds `baseAmount`, `baseCurrencyCode`, `exchangeRate`, `marginApplied`, `rateTimestamp`, `isConverted`)
+- **Cart.lines**: changed from `{ edges: Array<{ node: CartLine }> }` to `CartLine[]` (flat array — matches backend schema)
+- **CartDiscountAllocation**: field `discountedAmount` renamed to `amount`, added `discountCode` field
+
+### Fixed
+
+- CartClient GraphQL operations now match SSOT (backend `storefront-graphql/operations/`)
+- Cart fragment no longer uses `edges`/`nodes` connection pattern for `lines` — backend returns flat array
+- `CartDiscountAllocation` uses correct field name `amount` (was `discountedAmount`) and includes `discountCode`
+- `CartCost` and `CartLineCost` use `PriceMoney` fragment (was `Money`) — enables currency conversion transparency
+- `CartLineCost` includes `subtotalAmount` field (was missing)
+- `CartLine` includes `productType` field (was missing)
+- `CartLineMerchandise` now uses full `ProductVariant` fragment (was inline subset) — includes `originalPrice`, `originalCompareAtPrice`, `available`, `quantityAvailable`, `selectedOptions`, `barcode`, `weight`, `position`
+
+### Added
+
+- `PriceMoney` interface in cart types — full currency conversion metadata
+- `SelectedOption` interface in cart types
+- `scripts/validate-cart-operations.cjs` — validates SDK cart fragments match SSOT
+- `pnpm validate:cart` script — runs validation in strict mode
+- Contract test `cart-operations-drift.test.ts` — 40 tests verifying fragment fields, spreads, and structural invariants
+
+## [4.4.0] - 2026-03-29
+
+### Removed
+
+- **Image loader usuniety**: `storefrontImageLoader`, `createImageLoader`, `ImageLoaderParams`, `ImageFormat`, `PRESET_WIDTHS` — GraphQL API zwraca gotowe CDN URL-e z `url(transform: { maxWidth: 800 })`. Client-side loader zbedny.
+- Zachowany: `ImageData` type (uzywany przez template do typowania danych z GraphQL)
+
+## [4.3.0] - 2026-03-29
+
+### Changed
+
+- **Image loader**: imgproxy path-based URLs zamiast query params
+- `createImageLoader()` przyjmuje konfigurowalny `format` (webp/avif/jpeg/auto)
+- `storefrontImageLoader` uzywa nowego path-based schematu
+
+## [4.2.0] - 2026-03-28
+
+### Added
+
+- `storefrontImageLoader` jako globalny image loader dla Next.js (`next.config.ts loaderFile`)
+- Kwantyzacja szerokosc do presetow [150, 320, 640, 750, 828, 1080, 1200, 1600, 1920, 2048]
+
+## [4.1.0] - 2026-03-27
+
+### Added
+
+- `createImageLoader()` — factory do custom image loaderow z konfiguracja baseUrl/format
+- Usunieto HMAC signing (Shopify pattern — imgproxy nie wymaga podpisu w path-based mode)
+
+## [4.0.0] - 2026-03-20
+
+### Breaking Changes
+
+- **Layered architecture**: split na `core/` (framework-agnostic) + `react/` (adapter)
+- Nowe export paths: `.`, `./react`, `./react/server`, `./cache`
+- ESM-only (usuniete CJS)
+- Usuniety re-export `@tanstack/react-query` — hooki React Query generowane lokalnie w template
+- Store pattern zmieniony na Context-based (zustand/vanilla + React Context)
+- Usuniety module-level singleton pattern
+
+### Added
+
+- `createStorefrontClient()` — transport factory z composable middleware pipeline
+- Middleware: `authMiddleware`, `currencyMiddleware`, `languageMiddleware`, `botProtectionMiddleware`, `retryMiddleware`, `timeoutMiddleware`, `errorMiddleware`
+- `CartClient`, `AuthClient` — plain async clients (0 deps, framework-agnostic)
+- `StorefrontError` — zunifikowana klasa bledow z ErrorCodes
+- `StorefrontProvider` — root kompozycji (tworzy store instances via useRef)
+- `createStoreContext()` — generyczny helper Context+Zustand
+- `createCartStore()` z DI pattern (`getActions` getter)
+- `useAuth()`, `useCartManager()`, `useCurrency()`, `useStorefrontClient()`
+- `useHydrated()`, `useAuthHydrated()`, `useDebouncedValue()`
+- `createSetTokenHandler()`, `createClearTokenHandler()` — Web API fabryki
+- `createAuthTokenClient()` — client-side fetch helpers
+- `matchesRoute()` — route protection utility
+- `formatPrice`, `formatPriceRange`, `formatAmount`, `formatDate`, `formatDateTime`, `formatNumber`, `formatPercentage`, `getCurrencySymbol`
+- `sanitizeHtml`, `normalizeConnection`, `assertNoUserErrors`
+- Cache strategies: `cacheNone`, `cacheShort`, `cacheLong`, `cachePrivate`, `cacheCustom`
+- Bot protection: `createBotProtectionManager`, `FallbackBotProtectionManager`, `TurnstileManager`, `EuCaptchaManager`
+- Cookie configs: `AUTH_COOKIE_NAME`, `CURRENCY_COOKIE_NAME`, `LANGUAGE_COOKIE_NAME`, `CART_COOKIE_NAME`
+- `getStorefrontClient()` — server-side factory (react/server)
+
+### Removed
+
+- Runtime deps: `graphql-request`, `graphql`, `graphql-tag`, `@graphql-typed-document-node/core`, `@tanstack/react-query`
+- Module-level store singletons (zastapione Context pattern)