@doswiftly/cli 0.2.5 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,899 @@
+# Changelog
+
+## 1.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).
+
+## 0.2.6
+
+### 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.
+
+## 0.2.5
+
+### Patch Changes
+
+- e3174bb: Fix `doswiftly dev` to handle two common papercuts out of the box.
+
+  **Port pre-flight + auto-fallback.** `doswiftly dev` now probes the requested port
+  (default `3000`) before spawning the framework and auto-falls back to the next free
+  port up to `+10` (e.g. `3000 → 3001 → 3002`) — no more `EADDRINUSE` crashes when
+  another process already owns the default port. The banner is printed after the port
+  is reserved, so the advertised URL always matches what the framework actually binds.
+  Pass `--strict-port` (or set `dev.strictPort: true` in `doswiftly.config.ts`) to
+  fail fast instead of falling back.
+
+  **Active profile now wins over `api.url`.** `doswiftly env use <profile>` used to be
+  silently ignored for `doswiftly dev`, `inspect`, and `proxy` when `doswiftly.config.ts`
+  contained an `api.url` (which every scaffold sets). The precedence is now:
+  `DOSWIFTLY_API_URL` / `NEXT_PUBLIC_API_URL` shell env > active profile >
+  `doswiftly.config.ts` `api.url` > `.env.local` > default. `doswiftly deploy`
+  keeps its existing behaviour (project config wins unless `DOSWIFTLY_API_URL` is set).
+
+  Extras shipped alongside the fixes:
+  - `--strict-port` flag on `doswiftly dev`.
+  - The dev banner reports where the API URL came from
+    (e.g. `API: http://localhost:8000 (from profile "dev")`).
+  - `doswiftly env use` prints a one-line hint when the active profile overrides
+    `api.url` from `doswiftly.config.ts`.
+  - A warning when your `package.json` dev script hardcodes a port
+    (e.g. `"dev": "next dev -p 3000"`) that may override the CLI-supplied port.
+
+All notable changes to `@doswiftly/cli` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.4] - 2026-04-20
+
+### Fixed
+
+- **`doswiftly dev` no longer crashes with `EADDRINUSE` when the dev port is in use.**
+  The CLI now probes the requested port (default `3000`) before starting the framework and
+  auto-falls back to the next free port up to `+10` (so `3000 → 3001 → 3002`). The banner is
+  printed after the port is bound, so `Storefront: http://localhost:3001` always matches what
+  actually starts. Opt out with `--strict-port` on the command or `dev.strictPort: true` in
+  `doswiftly.config.ts` to fail fast instead.
+- **`doswiftly env use <profile>` now takes precedence over `api.url` in `doswiftly.config.ts`
+  for `doswiftly dev`, `inspect`, and `proxy`.** Previously, the project config silently
+  overrode the active profile, so switching to a `dev` profile with `API: http://localhost:8000`
+  still hit the production URL configured at scaffold time. Shell env vars (`DOSWIFTLY_API_URL`,
+  `NEXT_PUBLIC_API_URL`) stay on top for CI/CD and ad-hoc overrides. `doswiftly deploy`
+  behaviour is unchanged.
+
+### Added
+
+- **`--strict-port` flag and `dev.strictPort` config field** for `doswiftly dev`. When set,
+  the command fails with an actionable error (including the blocking port and the hint to
+  pass `--port <N>`) instead of auto-falling back.
+- **Banner now reports where the API URL came from** (e.g. `API: http://localhost:8000
+(from profile "dev")`), making it easier to diagnose unexpected target URLs.
+- **`doswiftly env use` surfaces a one-line notice** when the project's `doswiftly.config.ts`
+  hardcodes a different `api.url` than the active profile, so you know the profile is
+  intentionally taking over.
+- **Warning for hardcoded port in your `dev` script.** When `package.json` has
+  `"dev": "next dev -p 3000"` (or similar), the CLI warns in CI logs that the hardcoded port
+  may override `--port` / `PORT` env.
+
+## [0.2.3] - 2026-04-17
+
+### Security
+
+- Bump `axios` to `^1.15.0` to resolve GHSA-3p68-rc4w-qgx5 (NO_PROXY normalization bypass → SSRF) and GHSA-fvcv-3m26-pcqx (cloud metadata exfiltration via header injection).
+
+## [0.2.2] - 2026-04-12
+
+### Changed
+
+- **Default `@doswiftly/storefront-operations` dependency bumped `^1.0.0` → `^5.0.0`.** New storefronts
+  scaffolded via `doswiftly init` / `doswiftly template` now pull the per-location
+  `storeAvailability` surface out of the box. Existing storefronts on older operations keep working —
+  bump the dependency manually and re-run `pnpm install` when you're ready to adopt it.
+- **Storefront template (`storefront-nextjs-shadcn`): BOPIS example in `custom.example.graphql`
+  rewritten to the new API.** The `storeAvailability(first, near, locationType)` field on
+  `ProductVariant` replaces the previous per-location lookup, and the example now demonstrates the
+  `@inContext(preferredLocationId)` operation directive plus a `GetPickupLocations` store picker
+  query.
+
+## [0.2.1] - 2026-04-10
+
+### Fixed
+
+- **Dev proxy: strip Referer header alongside Origin.** The CSRF origin middleware on the
+  production backend validates both `Origin` and `Referer` headers. The proxy was only stripping
+  `Origin`, so the browser's `Referer: http://localhost:3000` was forwarded and rejected as
+  an unknown origin. Now both are stripped, making proxied requests appear as server-to-server.
+
+## [0.2.0] - 2026-04-10
+
+### Added
+
+- **Init: adopt flow for existing projects.** Running `doswiftly init` in a non-empty directory
+  now detects the existing project and offers to connect it to DoSwiftly without copying template
+  files. Creates `doswiftly.config.ts`, merges `.env.local`, and optionally installs SDK packages.
+- **Dev: automatic API proxy for CORS-free development.** `doswiftly dev` now auto-starts a local
+  proxy when the API URL points to a remote server, eliminating CORS errors during local development.
+  The proxy forwards all headers and runs transparently — no code changes needed in the storefront.
+
+### Changed
+
+- **Renamed "Commerce SDK" to "Storefront SDK"** across all CLI output, command descriptions,
+  and help text to match the actual package name (`@doswiftly/storefront-sdk`).
+- **Doctor: accepts `storefront-sdk` OR `storefront-operations`** as valid DoSwiftly dependencies
+  (matching deploy command logic).
+- **Dev: framework-agnostic dev command.** `doswiftly dev` now reads `scripts.dev` from
+  `package.json` instead of hardcoding `next dev`.
+- **Proxy: full header forwarding.** The proxy now forwards all request/response headers
+  (except hop-by-hop), including SDK headers, cookies, and Set-Cookie.
+
+### Removed
+
+- **Deprecated templates `storefront-nextjs` and `storefront-minimal`** removed from the package.
+  Only `storefront-nextjs-shadcn` (Next.js 16 + shadcn/ui) is shipped. These templates had
+  broken dependencies and outdated SDK references.
+- **Dead code:** removed duplicate `sdkVersionCommand` in `types.ts`, removed unused
+  `COMMERCE_SDK_VERSION` placeholder from init and template commands.
+
+### Fixed
+
+- **Verify/Check: fixed `env:generate` → `env generate`** in help text (commands use spaces, not colons).
+
+## [0.1.24] - 2026-04-10
+
+### Fixed
+
+- **Deploy: fix esbuild version detection using `pnpm ls` instead of binary/require().**
+  Both `pnpm exec esbuild --version` and `require('esbuild/package.json')` fail silently
+  in pnpm strict mode for transitive deps. Now uses `pnpm ls esbuild --parseable` which
+  queries pnpm's own dependency graph — works regardless of hoisting or strict mode config.
+- **Deploy: suggest highest installed esbuild version in fix instructions.** Instead of
+  a hardcoded `>=0.17.0`, the error message now suggests the highest esbuild version
+  already in the dependency tree (e.g. `0.25.4` from `@opennextjs/cloudflare`).
+
+## [0.1.23] - 2026-04-10
+
+### Added
+
+- **Deploy: early detection of incompatible esbuild versions.** If a transitive dependency
+  (e.g. `react-email`) pulls in esbuild <0.16.10 (lacks subpath alias support), CLI now
+  detects this before the build and exits with an actionable error message explaining how
+  to add an override. Uses the same `pnpm exec` resolution pattern as wrangler.
+
+### Removed
+
+- Removed auto-override of merchant's `package.json` (0.1.20-0.1.22). The approach was
+  unreliable across pnpm configurations and overstepped CLI's responsibility — dependency
+  management belongs to the project owner, not the deploy tool.
+
+## [0.1.19] - 2026-04-08
+
+### Fixed
+
+- Deploy: improved Cloudflare WAF/Bot protection error diagnostics with CF-Ray ID and hints.
+- Deploy: better error formatting for HTML error pages from Cloudflare.
+
+## [0.1.18] - 2026-04-05
+
+### Added
+
+- Deploy: `[observability]` section in generated `wrangler.toml` — logs persisted in Cloudflare Dashboard.
+- Deploy: `[images]` binding for Next.js `/_next/image` optimization via Cloudflare Images.
+
+## [0.1.17] - 2026-03-28
+
+### Fixed
+
+- Deploy: added Wrangler re-bundle step (`wrangler deploy --dry-run --outdir`) to convert
+  `require()` calls to ESM imports. Without this, CF Workers throw
+  `Dynamic require of "node:crypto" is not supported`.
+- Deploy: CLI now auto-installs `wrangler` if not present in the project.
+- Deploy: only `.js`, `.mjs`, `.wasm` files are copied from Wrangler output (skips `.map`, `README`).
+
+### Changed
+
+- Deploy: CLI generates `wrangler.toml` automatically, overwriting merchant's version to ensure
+  correct worker name, compatibility flags, and ASSETS binding.
+- Deploy: CLI generates `open-next.config.ts` (required by `@opennextjs/cloudflare` 1.17+).
+
+## [0.1.16] - 2026-03-20
+
+### Added
+
+- `doswiftly upgrade` — user-friendly wrapper for template migration commands.
+- `doswiftly migrate check/apply/diff` — template update management.
+
+## [0.1.15] - 2026-03-15
+
+### Added
+
+- `doswiftly auth github` — GitHub account linking via device flow.
+- `doswiftly auth token` — deploy token generation for CI/CD pipelines.
+- `doswiftly template create/register/publish/validate` — SaaS developer template management.
+
+## [0.1.14] - 2026-03-10
+
+### Added
+
+- `doswiftly preview create/list/stop/logs/open` — preview environment management.
+- `doswiftly config domain add/remove/list` — custom domain management.
+
+## [0.1.13] - 2026-03-05
+
+### Added
+
+- `doswiftly deploy run/status/rollback/logs` — Track 2 deployment pipeline.
+- Content-hash manifest for incremental uploads (only changed assets uploaded).
+- Idempotency keys for safe retries.
+
+## [0.1.12] - 2026-02-28
+
+### Added
+
+- `doswiftly env add/use/list/generate/delete/set` — environment profile management.
+- `doswiftly doctor` — project health diagnostics.
+- `doswiftly check` — dependency validation.
+
+## [0.1.11] - 2026-02-20
+
+### Added
+
+- `doswiftly dev` — development server with automatic env injection from API.
+- `doswiftly config pull/show` — configuration management.
+
+## [0.1.10] - 2026-02-15
+
+### Added
+
+- `doswiftly init` — interactive project scaffolding with template selection.
+- `doswiftly auth login/logout` — OAuth authentication.
+- `doswiftly whoami` — current context display.
+- `doswiftly verify` — project verification.