@doswiftly/cli 0.2.6 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,655 @@
 # Changelog
 
+## 1.0.1
+
+### Patch Changes
+
+- f7cf33f: **Fixed**: deploy via GitHub Actions failed with `Wrangler requires at least Node.js v22.0.0` because workflow templates pinned `node-version: 20` while `wrangler@latest` (installed mid-deploy for worker re-bundling) requires Node ≥22.
+  - `deploy.yml`, `preview.yml`, `build-template.yml` now use `node-version: 22` (LTS since April 2024, cached on `ubuntu-latest` so no extra download)
+  - `wrangler@^4` is now pinned at the install site — previously installed as `latest`, which silently picked up newer majors that could bump the Node floor again
+  - Scaffolded `package.json` declares `engines.node: ">=22.0.0"` so local `npm install` warns developers running an unsupported Node version
+
+  Existing projects (scaffolded with a previous CLI release) keep their `node-version: 20` until they re-run `doswiftly init` or manually edit the workflow file. The CLI cannot upgrade workflows in-place; consider running `doswiftly init` in a fresh directory and copying the workflow file across, or simply replace `node-version: 20` with `22` and re-commit.
+
+## 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

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AA4EA,KAAK,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAG3D,UAAU,aAAa;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+cD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI,CAkErE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,iBAua9D;AAGD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,kBA4B1C;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,iBAkD9D;AAwDD;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,YAAY,CAAC,EAAE,MAAM,iBAuDhE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,YAAY,EAAE,MAAM,iBA4E3D"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AA4EA,KAAK,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAG3D,UAAU,aAAa;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+cD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI,CAkErE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,iBA4a9D;AAGD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,kBA4B1C;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,iBAkD9D;AAwDD;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,YAAY,CAAC,EAAE,MAAM,iBAuDhE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,YAAY,EAAE,MAAM,iBA4E3D"}

package/dist/commands/deploy.js

@@ -677,7 +677,12 @@ export async function deployCommand(options = {}) {
                 catch {
                     console.log(chalk.cyan('  Installing wrangler...\n'));
                     const addCmd = pm === 'pnpm' ? 'pnpm add -D' : pm === 'yarn' ? 'yarn add -D' : 'npm install -D';
-                    execSync(`${addCmd} wrangler`, { stdio: 'inherit', timeout: 120_000 });
+                    // Pin to wrangler 4.x. Without explicit major range a new wrangler 5+ release
+                    // could bump the Node version floor again (4.x already requires Node ≥22 —
+                    // catching merchants on `node-version: 20` runners until they upgrade the
+                    // generated workflow). Pinning keeps the CLI deterministic across runs;
+                    // bump the range deliberately when CLI is tested on a new wrangler major.
+                    execSync(`${addCmd} wrangler@^4`, { stdio: 'inherit', timeout: 120_000 });
                 }
                 console.log(chalk.cyan('  Re-bundling worker with Wrangler for CF Workers compatibility...\n'));
                 const bundledDir = join('.open-next', '_wrangler_out');