@doswiftly/storefront-operations 7.1.0 → 8.0.0

package/AGENTS.md

@@ -27,10 +27,10 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 7.1.0
+- **Schema version**: 8.0.0
 - **Queries**: 48
 - **Mutations**: 44
-- **Fragments**: 108
+- **Fragments**: 104
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 8.0.0
+
+### Major Changes
+
+- 5f016e2: **BREAKING**: Operations were renamed to match the underlying GraphQL schema field names. If you used codegen against this package, regenerate your hooks and update import paths.
+
+  ### Renamed checkout mutations
+
+  | Old operation name                | New operation name                | New field call                                       |
+  | --------------------------------- | --------------------------------- | ---------------------------------------------------- |
+  | `CheckoutShippingAddressUpdate`   | `CheckoutUpdateShippingAddress`   | `checkoutUpdateShippingAddress(id, shippingAddress)` |
+  | `CheckoutBillingAddressUpdate`    | `CheckoutUpdateBillingAddress`    | `checkoutUpdateBillingAddress(id, billingAddress)`   |
+  | `CheckoutEmailUpdate`             | `CheckoutUpdateEmail`             | `checkoutUpdateEmail(id, email)`                     |
+  | `CheckoutShippingLineUpdate`      | `CheckoutSelectShippingRate`      | `checkoutSelectShippingRate(id, rateId)`             |
+  | `CheckoutDiscountCodeApply`       | `CheckoutApplyDiscountCode`       | `checkoutApplyDiscountCode(id, discountCode)`        |
+  | `CheckoutDiscountCodeRemove`      | `CheckoutRemoveDiscountCode`      | `checkoutRemoveDiscountCode(id, discountCode)`       |
+  | `CheckoutDiscountCodeValidate`    | `CheckoutValidateDiscountCode`    | `checkoutValidateDiscountCode(id, discountCode)`     |
+  | `CheckoutPaymentMethodUpdate`     | `CheckoutSelectPaymentMethod`     | `checkoutSelectPaymentMethod(id, paymentMethodId)`   |
+  | `CheckoutGiftCardApply`           | `CheckoutApplyGiftCard`           | `checkoutApplyGiftCard(id, giftCardCode)`            |
+  | `CheckoutGiftCardRemove`          | `CheckoutRemoveGiftCard`          | `checkoutRemoveGiftCard(id, giftCardCode)`           |
+  | `CheckoutGiftCardRecipientUpdate` | `CheckoutUpdateGiftCardRecipient` | `checkoutUpdateGiftCardRecipient(input)`             |
+
+  ### Argument changes in checkout mutations
+  - Variable `$checkoutId: ID!` → `$id: ID!`
+  - Argument `checkoutId:` → `id:`
+  - In `CheckoutSelectShippingRate`: variable `$shippingRateHandle: String!` → `$rateId: String!`, argument `shippingRateHandle:` → `rateId:`
+
+  Note: `CheckoutCreate` and `CheckoutComplete` were already aligned and are unchanged.
+
+  ### Renamed queries
+
+  | Old query                               | New query           | New field call                    |
+  | --------------------------------------- | ------------------- | --------------------------------- |
+  | `PredictiveSearch` (`predictiveSearch`) | `SearchSuggestions` | `searchSuggestions(query, limit)` |
+  | `AvailableFilters` (`availableFilters`) | `ProductFilters`    | `productFilters(input)`           |
+
+  `Categories` query now uses the `rootsOnly: true` argument and reads `nodes` instead of `roots`. Same data shape, standard Relay-style connection.
+
+  ### Renamed mutations (loyalty)
+
+  | Old mutation field     | New mutation field            |
+  | ---------------------- | ----------------------------- |
+  | `redeemLoyaltyReward`  | `loyaltyRedeemReward`         |
+  | `generateReferralCode` | `loyaltyGenerateReferralCode` |
+
+  Operation names (`RedeemLoyaltyReward`, `GenerateReferralCode`) are unchanged.
+
+  ### Wishlist mutations — argument alignment
+  - `wishlistAddItem(wishlistId, input)` → `wishlistAddItem(id, input)`
+  - `wishlistRemoveItem(wishlistId, itemId)` → `wishlistRemoveItem(id, itemId)`
+  - `wishlistDelete(wishlistId)` → `wishlistDelete(id)`
+
+  The `userErrors` field on every wishlist mutation result now correctly carries the `UserError` sub-selection.
+
+  ### Fragment shape changes
+  - `ProductCard` fragment now reads `categories { id, slug, name }` instead of the removed scalar `category` field. Cards that displayed a single category should now show the first item or join the list.
+  - `AvailableFilters` fragment now reads `activeCount` (was `activeFilterCount`) and `matchCount` (was `totalProducts`).
+  - Variant connections (`product.variants`) now require explicit `nodes { … }` selection — Relay-style.
+  - Loyalty payload fragments (`RedeemRewardPayload`, `GenerateReferralCodePayload`) now require the `UserError` sub-selection on `userErrors`.
+
+  ### Removed fragments
+  - `Price`, `PriceMoney`, `ProductRecommendation`, `CartRecommendation` — unused by any operation in this package. Inline equivalents are available if needed.
+
+  ### Migration
+  1. Regenerate codegen output against the new `schema.graphql` and operation files.
+  2. Update import paths to the new operation/hook names (search-and-replace based on the tables above).
+  3. In your form/UI code, rename the mutation variable `checkoutId` → `id` and update the argument key in the request payload.
+  4. In the shipping-rate flow, rename `shippingRateHandle` → `rateId`.
+  5. In `ProductCard` consumers, switch from `product.category` (string) to the first item of `product.categories` (array of `{ id, slug, name }`).
+  6. In `AvailableFilters` consumers, rename `activeFilterCount` → `activeCount` and `totalProducts` → `matchCount`.
+  7. In any `variants` selection on a product, wrap field selections in `nodes { … }`.
+  8. In `userErrors` reads on loyalty and wishlist mutations, expect the `UserError` shape (no longer a bare scalar).
+
 ## 7.1.0
 
 ### Minor Changes

package/README.md

@@ -172,7 +172,7 @@ full executable body of each operation.
 | `ProductConfigurator` | Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). `fillingMode: "CUSTOMER"` returns only customer-facing attributes; pass `"BOTH"` to also include attributes shared with the merchant admin. Single round-trip — saves a separate `attributes` query. |
 | `Products` | Paginated product list (Relay Connection, default page size 20, max 100). The `query` argument supports a structured search syntax — `tag:summer`, `vendor:foo`, `product_type:shirts`, `variants.price:>10`, plus `AND`/`OR`/`NOT` — falling back to free-text title/content search. The `filters[]` array uses multi-filter logic: same field name appears multiple times → OR; different fields → AND. Sort: `RELEVANCE`, `TITLE`, `PRICE`, `NEWEST`, `OLDEST`, `BEST_SELLING`. The response includes a `filters` block for faceted navigation (counts per filterable attribute value). |
 | `ProductSearch` | Full-text product search — `$query` is required. Functionally equivalent to `Products` with `$query` set, minus the `sortKey` argument (search defaults to relevance ranking). Use for the search results page; combine with `filters[]` for guided refinement. |
-| `PredictiveSearch` | Type-ahead suggestions for the storefront search input. Returns up to `$limit` matching products (hard cap 50) plus up to 5 styled query suggestions with `<mark>` tags around matched spans. Polish-language aware (handles morphology in suggestions). Run on each keystroke (debounce 200-300ms). The `$query` is capped at 100 characters server-side. |
+| `SearchSuggestions` | Type-ahead suggestions for the storefront search input. Returns up to `$limit` matching products (hard cap 50) plus up to 5 styled query suggestions with `<mark>` tags around matched spans. Polish-language aware (handles morphology in suggestions). Run on each keystroke (debounce 200-300ms). The `$query` is capped at 100 characters server-side. |
 
 #### Collections
 
@@ -186,7 +186,7 @@ full executable body of each operation.
 | Operation | Description |
 | --- | --- |
 | `Category` | Fetches a single category by `id` or `slug` with its parent and immediate children. Use for breadcrumbs and sub-navigation. Nested queries on `parent` / `children` are batched server-side — safe to use in lists without N+1 concerns. |
-| `Categories` | Returns active categories for the shop. Each category exposes its `parent` and `children` — build the tree client-side by walking those fields (server batches the lookups, no N+1). The hierarchy is not depth-capped server-side. Use for nav mega-menus and category pages. |
+| `Categories` | Returns active root categories for the shop. Each root exposes its `children` — build the tree client-side by walking those fields (server batches the lookups, no N+1). The hierarchy is not depth-capped server-side. Use for nav mega-menus and category pages. |
 
 #### Cart
 
@@ -246,7 +246,7 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `AvailableFilters` | Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages. |
+| `ProductFilters` | Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages. |
 
 #### Loyalty Program
 
@@ -374,23 +374,23 @@ full executable body of each operation.
 | Operation | Description |
 | --- | --- |
 | `CheckoutCreate` | Creates a new checkout session for the given cart (or a fresh cart if `cartId` is omitted). Inherits applied discounts and gift cards from the cart by reference (not snapshot). Errors: `CART_NOT_FOUND`, `EMPTY_CART`, `ALREADY_COMPLETED` (cart already converted to order). NOT idempotent — multiple calls create multiple checkouts. |
-| `CheckoutShippingAddressUpdate` | Sets the shipping address (full replace, not patch). Triggers cart re-pricing. Address format is NOT validated here — full validation runs at `checkoutComplete` (`validateOrderReadiness`). |
-| `CheckoutBillingAddressUpdate` | Sets the billing address (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". |
-| `CheckoutEmailUpdate` | Sets or updates the contact email on the checkout (used for guest checkout, order confirmation, and tracking emails). Validated against a regex; returns `INVALID` for malformed format. |
-| `CheckoutShippingLineUpdate` | Selects a shipping method by `shippingRateHandle` (a stable shipping-method UUID, NOT an opaque per-request token). The id comes from `availableShippingMethods` query, computed for the current address + cart subtotal at request time. |
-| `CheckoutDiscountCodeApply` | Appends a discount code to the cart's `discount_codes` array. Note: while multiple codes can be stored, the pricing engine currently uses **only the first applied code** — codes do not stack. Validated for existence, active status, and customer usage limits via `discountService.validateDiscount`. |
-| `CheckoutDiscountCodeRemove` | Removes a code from the cart's `discount_codes` array (filters by exact match). Triggers re-pricing. |
-| `CheckoutDiscountCodeValidate` | READ-ONLY validation of a discount code against the current checkout — does NOT modify state. Returns `{ isValid, discount, error }` for previewing the effect (e.g. inline UI feedback as the user types). |
-| `CheckoutPaymentMethodUpdate` | Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence and active status; no pre-authorization is performed here. |
-| `CheckoutComplete` | Finalizes the checkout: creates the `Order`, marks the cart `CONVERTED`, deducts gift cards, emits `ORDER_CREATED` (and `ORDER_CONFIRMED` for COD) — all in a single serializable transaction. **Idempotent on `idempotencyKey`** (NOT on `checkoutId`); auto-generated from `cartId + timestamp` if the caller omits it. The `paymentUrl` field is reserved but is NOT populated here — for hosted gateways (PayU, P24) the storefront calls a separate `paymentCreate` mutation after this returns. |
+| `CheckoutUpdateShippingAddress` | Sets the shipping address (full replace, not patch). Triggers cart re-pricing. Address format is NOT validated here — full validation runs at `checkoutComplete`. |
+| `CheckoutUpdateBillingAddress` | Sets the billing address (full replace). Independent of shipping address — pass it explicitly even when "billing same as shipping". |
+| `CheckoutUpdateEmail` | Sets or updates the contact email on the checkout (used for guest checkout, order confirmation, and tracking emails). Validated against a regex; returns `INVALID` for malformed format. |
+| `CheckoutSelectShippingRate` | Selects a shipping method by `rateId` (a stable shipping-method UUID, NOT an opaque per-request token). The id comes from `availableShippingMethods` query, computed for the current address + cart subtotal at request time. |
+| `CheckoutApplyDiscountCode` | Appends a discount code to the cart's `discount_codes` array. Note: while multiple codes can be stored, the pricing engine currently uses **only the first applied code** — codes do not stack. Validated for existence, active status, and customer usage limits. |
+| `CheckoutRemoveDiscountCode` | Removes a code from the cart's `discount_codes` array (filters by exact match). Triggers re-pricing. |
+| `CheckoutValidateDiscountCode` | READ-ONLY validation of a discount code against the current checkout — does NOT modify state. Returns `{ isValid, discount, error }` for previewing the effect (e.g. inline UI feedback as the user types). |
+| `CheckoutSelectPaymentMethod` | Selects a payment method by `paymentMethodId` (UUID from `availablePaymentMethods` query). Validates existence and active status; no pre-authorization is performed here. |
+| `CheckoutComplete` | Finalizes the checkout: creates the `Order`, deducts gift cards, sends order-created confirmation — all atomically. **Idempotent on `idempotencyKey`** (NOT on the checkout `id`); auto-generated if the caller omits it. The `paymentUrl` field is reserved but is NOT populated here — for hosted gateways (PayU, P24) the storefront calls a separate `paymentCreate` mutation after this returns. |
 
 #### Gift Card Checkout Mutations
 
 | Operation | Description |
 | --- | --- |
-| `CheckoutGiftCardApply` | Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically inside the `checkoutComplete` transaction. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`, `GIFT_CARD_ALREADY_APPLIED`. |
-| `CheckoutGiftCardRemove` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `checkoutComplete`, removing before completion has no effect on the underlying gift card balance. |
-| `CheckoutGiftCardRecipientUpdate` | Sets per-line-item recipient details (name, email, message, delivery date) for digital gift card products in the cart (variants with `type: GIFT_CARD`). Required before `checkoutComplete` for any line item with a gift-card variant. Recipient details are associated with each gift-card line item and propagated to the resulting order. |
+| `CheckoutApplyGiftCard` | Applies a gift card to the cart, stackable with discount codes. Consumption is FIFO: each card consumes `min(remainingBalance, paymentDue)` against the current cart total in the order they were applied. The gift card balance is NOT debited yet — actual deduction happens atomically at `checkoutComplete`. Errors: `GIFT_CARD_NOT_FOUND`, `GIFT_CARD_DEPLETED`, `GIFT_CARD_UNUSABLE`, `GIFT_CARD_ALREADY_APPLIED`. |
+| `CheckoutRemoveGiftCard` | Removes a gift card from the applied list and recalculates FIFO `appliedAmount` for the remaining cards. Since gift card balances are only debited at `checkoutComplete`, removing before completion has no effect on the underlying gift card balance. |
+| `CheckoutUpdateGiftCardRecipient` | Sets per-line-item recipient details (name, email, message, delivery date) for digital gift card products in the cart (variants with `type: GIFT_CARD`). Required before `checkoutComplete` for any line item with a gift-card variant. Recipient details are associated with each gift-card line item and propagated to the resulting order. |
 
 #### Return Mutations
 
@@ -419,9 +419,9 @@ full executable body of each operation.
 | Operation | Description |
 | --- | --- |
 | `WishlistCreate` | Creates a new wishlist for the logged-in customer. `name` is optional (defaults to "My Wishlist"); name uniqueness is NOT enforced — customers can have multiple lists with the same name. Setting `isPublic: true` generates a 16-byte hex `shareToken` for public sharing. |
-| `WishlistAddItem` | Adds an item by `productId` (and optional `variantId`) to a wishlist. Idempotent on the `(wishlist_id, product_id, variant_id)` unique constraint — adding an already-present item is a silent no-op (`ON CONFLICT DO NOTHING`). Captures `priceAtAdd` for price-drop notifications. |
+| `WishlistAddItem` | Adds an item by `productId` (and optional `variantId`) to a wishlist. Idempotent on the `(wishlist_id, product_id, variant_id)` unique constraint — adding an already-present item is a silent no-op. Captures `priceAtAdd` for price-drop notifications. |
 | `WishlistRemoveItem` | Hard-deletes a wishlist item by `itemId` (the `WishlistItem` row id, NOT the product id). |
-| `WishlistDelete` | Hard-deletes the wishlist row. All `WishlistItem` rows are removed via FK cascade. No soft-delete; cannot be undone. |
+| `WishlistDelete` | Hard-deletes the wishlist row. All wishlist items are removed via cascade. No soft-delete; cannot be undone. |
 
 #### Cart Attributes
 
@@ -445,8 +445,6 @@ full executable body of each operation.
 | `ImageCard` | `Image` | Card — product cards, collection / category tiles, blog post previews (rendered ~400px, transform delivers up to 800px for 2x DPI). Includes `thumbhash` placeholder. |
 | `ImageFull` | `Image` | Full — product detail gallery, hero banners (rendered ~800px, transform delivers up to 1600px for 2x DPI). Includes `thumbhash` placeholder. |
 | `Money` | `Money` | Plain `{ amount, currencyCode }` price. Use for `compareAtPrice`, totals, and any field where currency conversion transparency is not needed. `amount` is a String. |
-| `Price` | `PriceMoney` | Lightweight price for listing views (cards, grids, search results) — same shape as `Money`. Spread when full conversion metadata is overkill. |
-| `PriceMoney` | `PriceMoney` | Full price with currency-conversion transparency — adds `baseAmount`, `baseCurrencyCode`, `exchangeRate`, `marginApplied`, `rateTimestamp`, `isConverted`. Spread on PDP / cart / checkout where the customer needs to see the original price + applied conversion. |
 | `SelectedOption` | `SelectedOption` | Selected variant option (e.g. `{ name: "Color", value: "Red" }`) on a `ProductVariant`. Use to render variant labels in cart / order summaries. |
 
 #### Products
@@ -517,7 +515,7 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `ShippingRate` | `ShippingRate` | Single shipping rate option — `handle` is the stable id you pass to `checkoutShippingLineUpdate`, plus title and price. |
+| `ShippingRate` | `ShippingRate` | Single shipping rate option — `handle` is the stable id you pass to `checkoutSelectShippingRate` as `rateId`, plus title and price. |
 | `TaxLine` | `TaxLine` | One tax line on the checkout — title, rate (decimal, e.g. 0.23 for 23%), computed amount. Spread on the order summary. |
 | `DiscountAffectedItem` | `DiscountAffectedItem` | Item affected by a discount — the discounted product/variant with original + discounted prices and savings. Used on Buy-X-Get-Y promotions to highlight which items the discount applies to. |
 | `DiscountApplication` | `DiscountApplication` | A discount currently applied to the checkout — code, type, value, plus BXGY (Buy X Get Y) metadata when applicable (`buyQuantity`, `getQuantity`, `getDiscountPercent`, `affectedItems`). Use to render a "Discounts applied" panel. |
@@ -573,7 +571,7 @@ full executable body of each operation.
 | `AttributeDefinition` | `AttributeDefinition` | Filterable attribute exposed on the storefront — name, type (SELECT / CHECKBOX / SLIDER / etc.), filterability flags, display order, and either discrete `filterValues[]` or numeric `rangeBounds`. Spread inside `availableFilters.attributes[]`. |
 | `PriceRangeFilter` | `PriceRange` | Min / max price range across products in the current listing context. Use to bound the price slider. |
 | `CategoryFilterOption` | `CategoryFilterOption` | One category option in the categories filter — id, name, slug, count of products in this category within the current listing context, level + parentId for tree rendering. |
-| `AvailableFilters` | `AvailableFilters` | Full result of the `availableFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars. |
+| `AvailableFilters` | `AvailableFilters` | Full result of the `productFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars. |
 
 #### Loyalty Program
 
@@ -590,8 +588,8 @@ full executable body of each operation.
 | `LoyaltyAction` | `LoyaltyAction` | One earn action configured in the loyalty program — type (`PURCHASE` / `SIGNUP` / `REFERRAL` / `REVIEW` / `BIRTHDAY`), enabled flag, points granted. |
 | `LoyaltySettings` | `LoyaltySettings` | Loyalty program configuration — `isEnabled` (use to gate UI rendering), points name (e.g. "stars"), earn rate, expiry policy, available actions, referral settings. Returned by `loyaltySettings`. |
 | `ReferralStats` | `ReferralStats` | Customer referral statistics — code, share URL, counts of referred / completed / pending, lifetime points earned. Returned by `referralStats`. |
-| `RedeemRewardPayload` | `RedeemRewardPayload` | Result of `redeemLoyaltyReward` — depending on the reward type, exactly one of `discountCode`, `productDiscountCode`, `giftCardCode` is populated. Apply the returned code on cart/checkout. |
-| `GenerateReferralCodePayload` | `GenerateReferralCodePayload` | Result of `generateReferralCode` — the customer's referral code and shareable URL. |
+| `RedeemRewardPayload` | `RedeemRewardPayload` | Result of `loyaltyRedeemReward` — depending on the reward type, exactly one of `discountCode`, `productDiscountCode`, `giftCardCode` is populated. Apply the returned code on cart/checkout. |
+| `GenerateReferralCodePayload` | `GenerateReferralCodePayload` | Result of `loyaltyGenerateReferralCode` — the customer's referral code and shareable URL. |
 
 #### Reviews
 
@@ -615,13 +613,6 @@ full executable body of each operation.
 | `BlogTag` | `BlogTag` | Blog tag — name, slug, post count. Spread on tag clouds and post tag labels. |
 | `BlogPost` | `BlogPost` | Full blog post — title, slug, excerpt, content (with `contentFormat` indicating HTML/Markdown), featured image, author, category, tags, publish date, reading time, view + comment counts, SEO metadata. Spread on the post detail page. |
 
-#### Recommendations
-
-| Fragment | On Type | Description |
-| --- | --- | --- |
-| `ProductRecommendation` | `ProductRecommendation` | One recommended product — the product itself (card-level), recommendation type (e.g. SIMILAR / FREQUENTLY_BOUGHT_TOGETHER), score (0-100), human reason text. Spread on PDP "You may also like" sections. |
-| `CartRecommendation` | `CartRecommendations` | Recommendations bundle for the cart drawer — `frequentlyBoughtTogether` (cross-sell) and `youMayAlsoLike` (related). Each entry has the same shape as `ProductRecommendation`. |
-
 #### Store Availability (BOPIS / multi-location)
 
 | Fragment | On Type | Description |

package/fragments.graphql

@@ -74,23 +74,6 @@ fragment Money on Money {
   currencyCode
 }
 
-# Lightweight price for listing views (cards, grids, search results) — same shape as `Money`. Spread when full conversion metadata is overkill.
-fragment Price on PriceMoney {
-  amount
-  currencyCode
-}
-
-# Full price with currency-conversion transparency — adds `baseAmount`, `baseCurrencyCode`, `exchangeRate`, `marginApplied`, `rateTimestamp`, `isConverted`. Spread on PDP / cart / checkout where the customer needs to see the original price + applied conversion.
-fragment PriceMoney on PriceMoney {
-  ...Price
-  baseAmount
-  baseCurrencyCode
-  exchangeRate
-  marginApplied
-  rateTimestamp
-  isConverted
-}
-
 # Selected variant option (e.g. `{ name: "Color", value: "Red" }`) on a `ProductVariant`. Use to render variant labels in cart / order summaries.
 fragment SelectedOption on SelectedOption {
   name
@@ -134,7 +117,11 @@ fragment ProductCard on Product {
   handle
   title
   vendor
-  category
+  categories {
+    id
+    slug
+    name
+  }
   isAvailable
   averageRating
   reviewCount
@@ -635,7 +622,7 @@ fragment AvailablePaymentMethods on AvailablePaymentMethods {
 # Checkout
 # ============================================
 
-# Single shipping rate option — `handle` is the stable id you pass to `checkoutShippingLineUpdate`, plus title and price.
+# Single shipping rate option — `handle` is the stable id you pass to `checkoutSelectShippingRate` as `rateId`, plus title and price.
 fragment ShippingRate on ShippingRate {
   handle
   title
@@ -1106,7 +1093,7 @@ fragment CategoryFilterOption on CategoryFilterOption {
   parentId
 }
 
-# Full result of the `availableFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars.
+# Full result of the `productFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars.
 fragment AvailableFilters on AvailableFilters {
   attributes {
     ...AttributeDefinition
@@ -1117,8 +1104,8 @@ fragment AvailableFilters on AvailableFilters {
   categories {
     ...CategoryFilterOption
   }
-  activeFilterCount
-  totalProducts
+  activeCount
+  matchCount
 }
 
 # ============================================
@@ -1269,21 +1256,25 @@ fragment ReferralStats on ReferralStats {
   totalPointsEarned
 }
 
-# Result of `redeemLoyaltyReward` — depending on the reward type, exactly one of `discountCode`, `productDiscountCode`, `giftCardCode` is populated. Apply the returned code on cart/checkout.
+# Result of `loyaltyRedeemReward` — depending on the reward type, exactly one of `discountCode`, `productDiscountCode`, `giftCardCode` is populated. Apply the returned code on cart/checkout.
 fragment RedeemRewardPayload on RedeemRewardPayload {
   success
   discountCode
   productDiscountCode
   giftCardCode
-  userErrors
+  userErrors {
+    ...UserError
+  }
 }
 
-# Result of `generateReferralCode` — the customer's referral code and shareable URL.
+# Result of `loyaltyGenerateReferralCode` — the customer's referral code and shareable URL.
 fragment GenerateReferralCodePayload on GenerateReferralCodePayload {
   success
   referralCode
   shareUrl
-  userErrors
+  userErrors {
+    ...UserError
+  }
 }
 
 # ============================================
@@ -1415,39 +1406,6 @@ fragment BlogPost on BlogPost {
   updatedAt
 }
 
-# ============================================
-# Recommendations
-# ============================================
-
-# One recommended product — the product itself (card-level), recommendation type (e.g. SIMILAR / FREQUENTLY_BOUGHT_TOGETHER), score (0-100), human reason text. Spread on PDP "You may also like" sections.
-fragment ProductRecommendation on ProductRecommendation {
-  product {
-    ...ProductCard
-  }
-  type
-  score
-  reason
-}
-
-# Recommendations bundle for the cart drawer — `frequentlyBoughtTogether` (cross-sell) and `youMayAlsoLike` (related). Each entry has the same shape as `ProductRecommendation`.
-fragment CartRecommendation on CartRecommendations {
-  frequentlyBoughtTogether {
-    product {
-      ...ProductCard
-    }
-    type
-    score
-    reason
-  }
-  youMayAlsoLike {
-    product {
-      ...ProductCard
-    }
-    type
-    score
-    reason
-  }
-}
 
 # ============================================
 # Store Availability (BOPIS / multi-location)