@sixtyninecommerce/client 0.30.0 → 0.31.0

package/dist/commerce/queries.js

@@ -1,12 +1,54 @@
-// --- Product Queries ---
+import { fragment, withFragments } from '../graphql-document.js';
+// Every document and fragment below is tagged `/* GraphQL */` and read by
+// codegen (codegen.ts), which ERASES `${…}` interpolations: a selection shared
+// between documents is a named `fragment`, composed with `withFragments`.
+// Regenerate `src/generated/shop.ts` after any edit: `pnpm codegen`.
+// --- Catalog fragments ---
+/** The merchant publication state — the same three fields wherever it is read. */
+export const PRODUCT_AVAILABILITY_FRAGMENT = fragment(/* GraphQL */ `
+  fragment ProductAvailability on ProductAvailability {
+    state availableFrom orderable
+  }
+`);
+export const PRICE_TIER_FRAGMENT = fragment(/* GraphQL */ `
+  fragment PriceTier on PriceTier {
+    minQuantity price priceWithTax discountLabel
+  }
+`);
+export const VARIANT_LOCATION_AVAILABILITY_FRAGMENT = fragment(/* GraphQL */ `
+  fragment VariantLocationAvailability on VariantLocationAvailability {
+    locationId locationName inStock
+  }
+`);
+export const FACET_VALUE_FRAGMENT = fragment(/* GraphQL */ `
+  fragment FacetValue on FacetValue {
+    id name code facet { id name code }
+  }
+`);
+/**
+ * A product's collections, as canonical/hreflang resolution reads them.
+ *
+ * The parent's `slug` is load-bearing: a top-level collection is parented to
+ * the `__root_collection__` SENTINEL (Vendure resolves `parent` to null only
+ * when the real parent is PRIVATE), so the slug is what tells "root" from
+ * "nested" — see `isUserFacingRoot`.
+ */
+export const COLLECTION_REF_FRAGMENT = fragment(/* GraphQL */ `
+  fragment CollectionRef on Collection {
+    id name slug position
+    parent { id slug }
+    translations { languageCode name slug }
+    customFields { isRoutable isCanonical }
+  }
+`);
 /**
- * Fragment for `Product.metadata` (vendure-plugin-product-metadata). The
- * server already picks the active-language translation and composes
- * `metaRobots` + `resolvedBotDirectives` — the SDK only needs to validate +
- * type-narrow the JSON-scalar fields at the boundary.
+ * `Product.metadata` (vendure-plugin-product-metadata). The server already
+ * picks the active-language translation and composes `metaRobots` +
+ * `resolvedBotDirectives` — the SDK only validates and type-narrows the
+ * JSON-scalar fields at the boundary (`parseProductMetadata`).
  */
-const PRODUCT_METADATA_FRAGMENT = `
-  metadata {
+export const PRODUCT_METADATA_FRAGMENT = fragment(/* GraphQL */ `
+  fragment ProductMetadata on ProductMetadataShop {
     seoTitle seoDescription canonicalUrl
     socialTitle socialDescription socialImageAlt socialOgType
     socialImage {
@@ -31,73 +73,41 @@ const PRODUCT_METADATA_FRAGMENT = `
     metaRobots resolvedBotDirectives
     includeReviewsInJsonld
   }
-`;
-export const GET_PRODUCT = `
-  query GetProduct($slug: String!) {
-    product(slug: $slug) {
-      id name slug description
-      availability { state availableFrom orderable }
+`);
+/** A variant as the product DETAIL read returns it. */
+export const PRODUCT_VARIANT_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment ProductVariant on ProductVariant {
+      id name sku
+      price priceWithTax currencyCode stockLevel
+      stockOnHand stockAllocated saleable
+      incomingStock projectedSaleable nextExpectedArrival
+      backorderAllowance
+      availability { ...ProductAvailability }
+      forSaleInCurrency
+      priceListName retailPrice retailPriceWithTax taxRateApplied { value }
+      priceTiers { ...PriceTier }
+      availabilityByLocation { ...VariantLocationAvailability }
+      options { id code name group { id name code } }
+      customFields { minOrderQuantity salesUnit position }
       featuredAsset {
         source name width height
         customFields { altText }
-        presets {
-          xxs { url webpUrl } xs { url webpUrl }
-          s { url webpUrl } m { url webpUrl }
-          l { url webpUrl } xl { url webpUrl }
-        }
+        presets { xs { url webpUrl } m { url webpUrl } }
       }
       assets {
         source name width height
         customFields { altText }
-        presets {
-          xs { url webpUrl } m { url webpUrl }
-          l { url webpUrl } xl { url webpUrl }
-        }
-      }
-      variants {
-        id name sku
-        price priceWithTax currencyCode stockLevel
-          stockOnHand stockAllocated saleable
-          incomingStock projectedSaleable nextExpectedArrival
-          backorderAllowance
-          availability { state availableFrom orderable }
-        priceListName retailPrice retailPriceWithTax taxRateApplied { value }
-        priceTiers { minQuantity price priceWithTax discountLabel }
-        availabilityByLocation { locationId locationName inStock }
-        options { id code name group { id name code } }
-        customFields { minOrderQuantity salesUnit position }
-        featuredAsset {
-          source name width height
-          customFields { altText }
-          presets { xs { url webpUrl } m { url webpUrl } }
-        }
-        assets {
-          source name width height
-          customFields { altText }
-          presets { m { url webpUrl } l { url webpUrl } }
-        }
-      }
-      optionGroups { id name code options { id name code } }
-      facetValues { id name code facet { id name code } }
-      translations { languageCode name slug description }
-      collections {
-        id name slug position
-        parent { id slug }
-        translations { languageCode name slug }
-        customFields { isRoutable isCanonical }
-      }
-      documents {
-        id position title description fileUrl fileMimeType fileSize fileName requiresAuth
+        presets { m { url webpUrl } l { url webpUrl } }
       }
-      ${PRODUCT_METADATA_FRAGMENT}
     }
-  }
-`;
-export const GET_PRODUCT_BY_ID = `
-  query GetProductById($id: ID!) {
-    product(id: $id) {
+  `, PRODUCT_AVAILABILITY_FRAGMENT, PRICE_TIER_FRAGMENT, VARIANT_LOCATION_AVAILABILITY_FRAGMENT);
+/** The product DETAIL read (`getProduct`, `getProductById`). */
+export const PRODUCT_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment Product on Product {
       id name slug description
-      availability { state availableFrom orderable }
+      availability { ...ProductAvailability }
       featuredAsset {
         source name width height
         customFields { altText }
@@ -115,80 +125,45 @@ export const GET_PRODUCT_BY_ID = `
           l { url webpUrl } xl { url webpUrl }
         }
       }
+      variants { ...ProductVariant }
+      optionGroups { id name code options { id name code } }
+      facetValues { ...FacetValue }
+      translations { languageCode name slug description }
+      collections { ...CollectionRef }
+      documents {
+        id position title description fileUrl fileMimeType fileSize fileName requiresAuth
+      }
+      metadata { ...ProductMetadata }
+    }
+  `, PRODUCT_AVAILABILITY_FRAGMENT, PRODUCT_VARIANT_FRAGMENT, FACET_VALUE_FRAGMENT, COLLECTION_REF_FRAGMENT, PRODUCT_METADATA_FRAGMENT);
+/** A row of the full product LIST (`getProducts`, the default `detail`). */
+export const PRODUCT_SUMMARY_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment ProductSummary on Product {
+      id name slug description enabled
+      featuredAsset {
+        source name width height
+        customFields { altText }
+        presets { xs { url webpUrl } m { url webpUrl } l { url webpUrl } }
+      }
       variants {
         id name sku
         price priceWithTax currencyCode stockLevel
-          stockOnHand stockAllocated saleable
-          incomingStock projectedSaleable nextExpectedArrival
-          backorderAllowance
-          availability { state availableFrom orderable }
+        stockOnHand stockAllocated saleable
+        incomingStock projectedSaleable nextExpectedArrival
+        backorderAllowance
+        availability { ...ProductAvailability }
+        forSaleInCurrency
         priceListName retailPrice retailPriceWithTax taxRateApplied { value }
-        priceTiers { minQuantity price priceWithTax discountLabel }
-        availabilityByLocation { locationId locationName inStock }
-        options { id code name group { id name code } }
+        priceTiers { ...PriceTier }
+        availabilityByLocation { ...VariantLocationAvailability }
         customFields { minOrderQuantity salesUnit position }
-        featuredAsset {
-          source name width height
-          customFields { altText }
-          presets { xs { url webpUrl } m { url webpUrl } }
-        }
-        assets {
-          source name width height
-          customFields { altText }
-          presets { m { url webpUrl } l { url webpUrl } }
-        }
       }
-      optionGroups { id name code options { id name code } }
-      facetValues { id name code facet { id name code } }
+      facetValues { ...FacetValue }
       translations { languageCode name slug description }
-      collections {
-        id name slug position
-        parent { id slug }
-        translations { languageCode name slug }
-        customFields { isRoutable isCanonical }
-      }
-      documents {
-        id position title description fileUrl fileMimeType fileSize fileName requiresAuth
-      }
-      ${PRODUCT_METADATA_FRAGMENT}
+      collections { ...CollectionRef }
     }
-  }
-`;
-export const LIST_PRODUCTS = `
-  query ListProducts($options: ProductListOptions) {
-    products(options: $options) {
-      items {
-        id name slug description enabled
-        featuredAsset {
-          source name width height
-          customFields { altText }
-          presets { xs { url webpUrl } m { url webpUrl } l { url webpUrl } }
-        }
-        variants {
-          id name sku
-          price priceWithTax currencyCode stockLevel
-          stockOnHand stockAllocated saleable
-          incomingStock projectedSaleable nextExpectedArrival
-          backorderAllowance
-          availability { state availableFrom orderable }
-          priceListName retailPrice retailPriceWithTax taxRateApplied { value }
-          priceTiers { minQuantity price priceWithTax discountLabel }
-          availabilityByLocation { locationId locationName inStock }
-          customFields { minOrderQuantity salesUnit position }
-        }
-        facetValues { id name code facet { id name code } }
-        translations { languageCode name slug description }
-        collections {
-          id name slug position
-          parent { id slug }
-          translations { languageCode name slug }
-          customFields { isRoutable isCanonical }
-        }
-      }
-      totalItems
-    }
-  }
-`;
+  `, PRODUCT_AVAILABILITY_FRAGMENT, PRICE_TIER_FRAGMENT, VARIANT_LOCATION_AVAILABILITY_FRAGMENT, FACET_VALUE_FRAGMENT, COLLECTION_REF_FRAGMENT);
 /**
  * The card selection: what a product GRID tile renders, and nothing else.
  *
@@ -229,9 +204,15 @@ export const LIST_PRODUCTS = `
  *     `customFields.isCanonical` + `parent.slug` + `position`, and its localized
  *     slug from the translations. A card row still satisfies `ProductForSeo`
  *     structurally, so omitting these does not fail to compile — it silently
- *     hands every product the FLAT path. Note these cost bytes, not queries:
- *     Vendure resolves `Product.collections` in one query per product whichever
- *     subfields are asked for.
+ *     hands every product the FLAT path. Cost: a constant number of queries per
+ *     page, not per row. The platform batches `Product.collections` for every
+ *     product of the page into ONE statement and `parent` for every listed
+ *     collection into one more (`services/vendure/src/collection-batching`),
+ *     and `translations` / `customFields` come back in those same rows. Core
+ *     Vendure alone ran one query per product plus one per listed collection
+ *     — measured 419 statements for an 80-product page, 2 with the batching.
+ *     Not batched: `featuredAsset`, `children`, `breadcrumbs` or
+ *     `productVariants` under `collections` still cost a query per collection.
  *   - `priceTiers` — the SDK's own `getPriceDisplay()` reads
  *     `variant.priceTiers?.length ? … : null`, so an ABSENT ladder is
  *     indistinguishable from "this variant has no tiers": a tile would quietly
@@ -245,74 +226,64 @@ export const LIST_PRODUCTS = `
  * Reached with `getProducts(..., { detail: 'card' })`. The default stays
  * `LIST_PRODUCTS`, so no existing caller changes behaviour.
  */
-export const LIST_PRODUCT_CARDS = `
-  query ListProductCards($options: ProductListOptions) {
-    products(options: $options) {
-      items {
-        id name slug enabled
-        featuredAsset {
-          source name width height
-          customFields { altText }
-          presets { xs { url webpUrl } m { url webpUrl } l { url webpUrl } }
-        }
-        variants {
-          id name sku
-          price priceWithTax currencyCode stockLevel saleable backorderAllowance
-          availability { state availableFrom orderable }
-          priceListName retailPrice retailPriceWithTax taxRateApplied { value }
-          priceTiers { minQuantity price priceWithTax discountLabel }
-          customFields { minOrderQuantity salesUnit position }
-        }
-        facetValues { id name code facet { id name code } }
-        translations { languageCode name slug }
-        collections {
-          id name slug position
-          parent { id slug }
-          translations { languageCode name slug }
-          customFields { isRoutable isCanonical }
-        }
+export const PRODUCT_CARD_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment ProductCard on Product {
+      id name slug enabled
+      featuredAsset {
+        source name width height
+        customFields { altText }
+        presets { xs { url webpUrl } m { url webpUrl } l { url webpUrl } }
       }
-      totalItems
-    }
-  }
-`;
-export const LIST_FACETS = `
-  query ListFacets {
-    facets {
-      items {
-        id name code
-        values { id name code }
+      variants {
+        id name sku
+        price priceWithTax currencyCode stockLevel saleable backorderAllowance
+        availability { ...ProductAvailability }
+        forSaleInCurrency
+        priceListName retailPrice retailPriceWithTax taxRateApplied { value }
+        priceTiers { ...PriceTier }
+        customFields { minOrderQuantity salesUnit position }
       }
-      totalItems
-    }
-  }
-`;
-// --- Collection Queries ---
-export const LIST_COLLECTIONS = `
-  query ListCollections($options: CollectionListOptions) {
-    collections(options: $options) {
-      items {
-        id name slug description
-        breadcrumbs { id name slug }
-        featuredAsset {
-          source width height
-          presets { xs { url webpUrl } m { url webpUrl } }
-        }
-        parent { id name slug }
-        children { id name slug }
+      facetValues { ...FacetValue }
+      translations { languageCode name slug }
+      collections { ...CollectionRef }
+    }
+  `, PRODUCT_AVAILABILITY_FRAGMENT, PRICE_TIER_FRAGMENT, FACET_VALUE_FRAGMENT, COLLECTION_REF_FRAGMENT);
+export const FACET_FRAGMENT = fragment(/* GraphQL */ `
+  fragment Facet on Facet {
+    id name code
+    values { id name code }
+  }
+`);
+export const BREADCRUMB_FRAGMENT = fragment(/* GraphQL */ `
+  fragment Breadcrumb on CollectionBreadcrumb {
+    id name slug
+  }
+`);
+/** A row of the collection LIST (`getCollections`). */
+export const COLLECTION_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment Collection on Collection {
+      id name slug description
+      breadcrumbs { ...Breadcrumb }
+      featuredAsset {
+        source width height
+        presets { xs { url webpUrl } m { url webpUrl } }
       }
-      totalItems
+      parent { id name slug }
+      children { id name slug }
     }
-  }
-`;
-/** The collection-detail selection, shared by the slug and the id lookup. */
-const COLLECTION_DETAIL_FIELDS = `
+  `, BREADCRUMB_FRAGMENT);
+/** The collection DETAIL read, shared by the slug and the id lookup. */
+export const COLLECTION_DETAIL_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment CollectionDetail on Collection {
       id name slug description position
       featuredAsset {
         source width height
         presets { l { url webpUrl } xl { url webpUrl } }
       }
-      breadcrumbs { id name slug }
+      breadcrumbs { ...Breadcrumb }
       parent { id }
       children { id name slug }
       customFields {
@@ -349,146 +320,324 @@ const COLLECTION_DETAIL_FIELDS = `
           stockOnHand stockAllocated saleable
           incomingStock projectedSaleable nextExpectedArrival
           backorderAllowance
-          availability { state availableFrom orderable }
+          availability { ...ProductAvailability }
+          forSaleInCurrency
           priceListName retailPrice retailPriceWithTax taxRateApplied { value }
-          priceTiers { minQuantity price priceWithTax discountLabel }
-          availabilityByLocation { locationId locationName inStock }
+          priceTiers { ...PriceTier }
+          availabilityByLocation { ...VariantLocationAvailability }
           customFields { minOrderQuantity salesUnit position }
         }
         totalItems
       }
-`;
-export const GET_COLLECTION = `
-  query GetCollection($slug: String!) {
-    collection(slug: $slug) {${COLLECTION_DETAIL_FIELDS}    }
-  }
-`;
-export const GET_COLLECTION_BY_ID = `
-  query GetCollectionById($id: ID!) {
-    collection(id: $id) {${COLLECTION_DETAIL_FIELDS}    }
-  }
-`;
-// --- Search Query ---
-export const SEARCH_PRODUCTS = `
-  query SearchProducts($input: SearchInput!) {
-    search(input: $input) {
-      items {
-        productId productVariantId productName slug description
-        price { ... on SinglePrice { value } ... on PriceRange { min max } }
-        priceWithTax { ... on SinglePrice { value } ... on PriceRange { min max } }
-        currencyCode
-        productAsset { preview focalPoint { x y } }
-        collectionIds
-        inStock
-        availability { state availableFrom orderable }
-      }
+    }
+  `, BREADCRUMB_FRAGMENT, PRODUCT_AVAILABILITY_FRAGMENT, PRICE_TIER_FRAGMENT, VARIANT_LOCATION_AVAILABILITY_FRAGMENT);
+/**
+ * One search hit. `productVariantId` is the orderable id (never pass
+ * `productId` to `addToCart`); `availability` is null for a document indexed
+ * before the attribute existed, until the channel is fully reindexed.
+ */
+export const SEARCH_RESULT_ITEM_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment SearchResultItem on SearchResult {
+      productId productVariantId productName slug description
+      price { ... on SinglePrice { value } ... on PriceRange { min max } }
+      priceWithTax { ... on SinglePrice { value } ... on PriceRange { min max } }
+      currencyCode
+      productAsset { preview focalPoint { x y } }
+      collectionIds
+      inStock
+      availability { ...ProductAvailability }
+      forSaleInCurrency
+    }
+  `, PRODUCT_AVAILABILITY_FRAGMENT);
+export const SEARCH_RESULT_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment SearchResult on SearchResponse {
+      items { ...SearchResultItem }
       totalItems
-      facetValues { facetValue { id name code facet { id name code } } count }
+      facetValues { facetValue { ...FacetValue } count }
     }
+  `, SEARCH_RESULT_ITEM_FRAGMENT, FACET_VALUE_FRAGMENT);
+// --- Product Queries ---
+export const GET_PRODUCT = withFragments(
+/* GraphQL */ `
+    query GetProduct($slug: String!) {
+      product(slug: $slug) { ...Product }
+    }
+  `, PRODUCT_FRAGMENT);
+export const GET_PRODUCT_BY_ID = withFragments(
+/* GraphQL */ `
+    query GetProductById($id: ID!) {
+      product(id: $id) { ...Product }
+    }
+  `, PRODUCT_FRAGMENT);
+/**
+ * A storefront-visible metafield as it arrives ON an entity: the
+ * `storefront: read` values an app or the store published (headless spec
+ * §8.13). `value` is whatever the definition's type describes.
+ */
+export const METAFIELD_FRAGMENT = fragment(/* GraphQL */ `
+  fragment Metafield on Metafield {
+    namespace key value
   }
-`;
+`);
+/**
+ * OPT-IN product reads, chosen by `getProduct(slug, { metafields })` and
+ * `getProductById(id, { metafields })`: the default `Product` selection plus
+ * the product's own metafields and every variant's, `$namespace` narrowing
+ * both to one app (`null` is every namespace).
+ *
+ * Separate documents, never a `metafields` selection in `PRODUCT_FRAGMENT`
+ * (the rule `ORDER_FULFILLMENT_PARCELS_FRAGMENT` follows): `Product.metafields`
+ * is an additive Shop API field, and an engine without it fails the WHOLE
+ * document at validation. Selected by default, an SDK upgraded ahead of the
+ * engine deploy would 400 every product page; selected here, only a caller
+ * that asked for metafields needs the newer engine. GraphQL merges this
+ * `variants` selection with the fragment's, so each variant still comes back
+ * whole.
+ *
+ * The server reads every product's (and every variant's) metafields of the
+ * request in one statement per owner type, so the variant selection costs one
+ * read, not one per variant.
+ */
+export const GET_PRODUCT_WITH_METAFIELDS = withFragments(
+/* GraphQL */ `
+    query GetProductWithMetafields($slug: String!, $namespace: String) {
+      product(slug: $slug) {
+        ...Product
+        metafields(namespace: $namespace) { ...Metafield }
+        variants { id metafields(namespace: $namespace) { ...Metafield } }
+      }
+    }
+  `, PRODUCT_FRAGMENT, METAFIELD_FRAGMENT);
+/** {@link GET_PRODUCT_WITH_METAFIELDS} by id. */
+export const GET_PRODUCT_BY_ID_WITH_METAFIELDS = withFragments(
+/* GraphQL */ `
+    query GetProductByIdWithMetafields($id: ID!, $namespace: String) {
+      product(id: $id) {
+        ...Product
+        metafields(namespace: $namespace) { ...Metafield }
+        variants { id metafields(namespace: $namespace) { ...Metafield } }
+      }
+    }
+  `, PRODUCT_FRAGMENT, METAFIELD_FRAGMENT);
+export const LIST_PRODUCTS = withFragments(
+/* GraphQL */ `
+    query ListProducts($options: ProductListOptions) {
+      products(options: $options) {
+        items { ...ProductSummary }
+        totalItems
+      }
+    }
+  `, PRODUCT_SUMMARY_FRAGMENT);
+export const LIST_PRODUCT_CARDS = withFragments(
+/* GraphQL */ `
+    query ListProductCards($options: ProductListOptions) {
+      products(options: $options) {
+        items { ...ProductCard }
+        totalItems
+      }
+    }
+  `, PRODUCT_CARD_FRAGMENT);
+export const LIST_FACETS = withFragments(
+/* GraphQL */ `
+    query ListFacets {
+      facets {
+        items { ...Facet }
+        totalItems
+      }
+    }
+  `, FACET_FRAGMENT);
+// --- Collection Queries ---
+export const LIST_COLLECTIONS = withFragments(
+/* GraphQL */ `
+    query ListCollections($options: CollectionListOptions) {
+      collections(options: $options) {
+        items { ...Collection }
+        totalItems
+      }
+    }
+  `, COLLECTION_FRAGMENT);
+export const GET_COLLECTION = withFragments(
+/* GraphQL */ `
+    query GetCollection($slug: String!) {
+      collection(slug: $slug) { ...CollectionDetail }
+    }
+  `, COLLECTION_DETAIL_FRAGMENT);
+export const GET_COLLECTION_BY_ID = withFragments(
+/* GraphQL */ `
+    query GetCollectionById($id: ID!) {
+      collection(id: $id) { ...CollectionDetail }
+    }
+  `, COLLECTION_DETAIL_FRAGMENT);
+/**
+ * OPT-IN collection reads with the collection's own metafields, chosen by
+ * `getCollection(slug, { metafields })` and `getCollectionById(id, {
+ * metafields })`. Separate documents for the reason
+ * {@link GET_PRODUCT_WITH_METAFIELDS} gives.
+ */
+export const GET_COLLECTION_WITH_METAFIELDS = withFragments(
+/* GraphQL */ `
+    query GetCollectionWithMetafields($slug: String!, $namespace: String) {
+      collection(slug: $slug) {
+        ...CollectionDetail
+        metafields(namespace: $namespace) { ...Metafield }
+      }
+    }
+  `, COLLECTION_DETAIL_FRAGMENT, METAFIELD_FRAGMENT);
+/** {@link GET_COLLECTION_WITH_METAFIELDS} by id. */
+export const GET_COLLECTION_BY_ID_WITH_METAFIELDS = withFragments(
+/* GraphQL */ `
+    query GetCollectionByIdWithMetafields($id: ID!, $namespace: String) {
+      collection(id: $id) {
+        ...CollectionDetail
+        metafields(namespace: $namespace) { ...Metafield }
+      }
+    }
+  `, COLLECTION_DETAIL_FRAGMENT, METAFIELD_FRAGMENT);
+// --- Search Query ---
+export const SEARCH_PRODUCTS = withFragments(
+/* GraphQL */ `
+    query SearchProducts($input: SearchInput!) {
+      search(input: $input) { ...SearchResult }
+    }
+  `, SEARCH_RESULT_FRAGMENT);
 // --- Cart Mutations ---
 // Shared selection set for full Order objects. Used by ACTIVE_ORDER, ADD_TO_CART,
 // ADJUST_ORDER_LINE, REMOVE_ORDER_LINE, APPLY_COUPON, REMOVE_COUPON, ORDER_BY_CODE.
 // Keep in one place so adding fields (e.g. discounts) lands everywhere consistently.
-const ORDER_FIELDS = `
-  id code state active
-  createdAt orderPlacedAt
-  totalQuantity
-  subTotal subTotalWithTax
-  shipping shippingWithTax
-  total totalWithTax
-  currencyCode
-  lines {
-    id quantity
-    unitPrice unitPriceWithTax taxRate
-    linePrice linePriceWithTax
-    discountedLinePrice discountedLinePriceWithTax
+const ORDER_FRAGMENT = fragment(/* GraphQL */ `
+  fragment Order on Order {
+    id code state active
+    createdAt orderPlacedAt
+    totalQuantity
+    subTotal subTotalWithTax
+    shipping shippingWithTax
+    total totalWithTax
+    currencyCode
+    lines {
+      id quantity
+      unitPrice unitPriceWithTax taxRate
+      linePrice linePriceWithTax
+      discountedLinePrice discountedLinePriceWithTax
+      discounts { adjustmentSource type description amount amountWithTax }
+      productVariant {
+        id name sku saleable
+        product { id name slug }
+        options { id name group { name } }
+      }
+      featuredAsset { source presets { xs { url webpUrl } } }
+    }
     discounts { adjustmentSource type description amount amountWithTax }
-    productVariant {
-      id name sku saleable
-      product { id name slug }
-      options { id name group { name } }
-    }
-    featuredAsset { source presets { xs { url webpUrl } } }
-  }
-  discounts { adjustmentSource type description amount amountWithTax }
-  taxSummary { description taxRate taxBase taxTotal }
-  promotions { id name couponCode description }
-  shippingLines { shippingMethod { id name code } priceWithTax }
-  payments { id method amount state transactionId }
-  shippingAddress { fullName company streetLine1 streetLine2 city province postalCode countryCode phoneNumber }
-  billingAddress { fullName company streetLine1 streetLine2 city province postalCode countryCode phoneNumber }
-  customer { id firstName lastName emailAddress }
-  couponCodes
-`;
+    taxSummary { description taxRate taxBase taxTotal }
+    promotions { id name couponCode description }
+    shippingLines { shippingMethod { id name code } priceWithTax }
+    payments { id method amount state transactionId }
+    shippingAddress { fullName company streetLine1 streetLine2 city province postalCode countryCode phoneNumber }
+    billingAddress { fullName company streetLine1 streetLine2 city province postalCode countryCode phoneNumber }
+    customer { id firstName lastName emailAddress }
+    couponCodes
+  }
+`);
 /**
- * Fulfillment/tracking selection for placed orders. Kept out of ORDER_FIELDS
+ * Fulfillment/tracking selection for placed orders. Kept out of ORDER_FRAGMENT
  * so cart mutations don't pay for it — active carts have no fulfillments.
  * `trackingCode` feeds `trackShipment(barcode, postalCode)`.
  *
  * `externalShipments` is the carrier-agnostic list pushed by an external
  * fulfilment system, and is the right thing to render for tracking: one
  * fulfilment can cover SEVERAL parcels, which a single `trackingCode` cannot
- * express. Render `reference` as a link when `isLink` is true and as a text block
- * otherwise — a pallet carrier's reference or ex-works pickup instructions are
- * prose, not URLs. The flag is derived server-side so the storefront never has
- * to guess.
+ * express — though `fulfillments[].trackingCodes` does for a carrier we book
+ * ourselves (see {@link ORDER_FULFILLMENT_PARCELS_FRAGMENT}). Render
+ * `reference` as a link when `isLink` is true and as a text block otherwise — a
+ * pallet carrier's reference or ex-works pickup instructions are prose, not
+ * URLs. The flag is derived server-side so the storefront never has to guess.
  */
-const ORDER_FULFILLMENTS_FRAGMENT = `
-  fulfillments {
-    id state method trackingCode createdAt updatedAt
-    lines { orderLineId quantity }
+const ORDER_FULFILLMENTS_FRAGMENT = fragment(/* GraphQL */ `
+  fragment OrderFulfillments on Order {
+    fulfillments {
+      id state method trackingCode createdAt updatedAt
+      lines { orderLineId quantity }
+    }
+    externalShipments {
+      carrier reference isLink shippedAt deliveryNumber
+    }
   }
-  externalShipments {
-    carrier reference isLink shippedAt deliveryNumber
+`);
+/**
+ * OPTIONAL per-parcel barcodes, selected by the two PLACED-order reads
+ * (`ORDER_BY_CODE`, `GET_CUSTOMER_ORDERS`) and nowhere else — the same rule
+ * `lines { backorderedQuantity }` and `customFields { paymentIntent }` follow.
+ *
+ * `Fulfillment.trackingCodes` is an additive Shop API field that only an engine
+ * shipping the MyParcel plugin's multi-parcel release answers. In the shared
+ * `ORDER_FULFILLMENTS_FRAGMENT` it also reached `ORDER_SUMMARY_FRAGMENT` and so
+ * `GET_CURRENT_CUSTOMER` — the customer-session read every page makes. An SDK
+ * upgrade ahead of the engine deploy would then 400 the whole document at
+ * GraphQL validation and log every customer out of their account area, for a
+ * field that only enriches a tracking list. GraphQL merges this `fulfillments`
+ * selection with the fragment's, so the fulfillment still comes back whole.
+ *
+ * Needs the engine release named in this package's changeset; against an older
+ * one these two reads fail validation while the rest of the SDK keeps working.
+ */
+const ORDER_FULFILLMENT_PARCELS_FRAGMENT = fragment(/* GraphQL */ `
+  fragment OrderFulfillmentParcels on Order {
+    fulfillments { id trackingCodes }
   }
-`;
+`);
 /** Immutable payment condition captured when a placed order was accepted. */
-const ORDER_PAYMENT_TERMS_FRAGMENT = `
-  paymentTerms {
-    source managedExternally status
-    conditionCode conditionDescription summary classification
-    paymentDays paymentEndOfMonths paymentMethod percentage
-    discountPaymentDays discountPercentage paymentDiscountType
-    stale syncedAt error
-    resolvedAt remoteConditionCode remoteConfirmedAt remoteMismatch
-  }
-`;
+const ORDER_PAYMENT_TERMS_FRAGMENT = fragment(/* GraphQL */ `
+  fragment OrderPaymentTerms on Order {
+    paymentTerms {
+      source managedExternally status
+      conditionCode conditionDescription summary classification
+      paymentDays paymentEndOfMonths paymentMethod percentage
+      discountPaymentDays discountPercentage paymentDiscountType
+      stale syncedAt error
+      resolvedAt remoteConditionCode remoteConfirmedAt remoteMismatch
+    }
+  }
+`);
 /** Immutable delivery terms captured when a placed order was accepted. */
-const ORDER_DELIVERY_TERMS_FRAGMENT = `
-  deliveryTerms {
-    source managedExternally status shippingMethodStatus policyStatus summary selectionSource
-    selectedShippingMethodId selectedShippingMethodCode selectedShippingMethodName
-    platformShippingMethodCode platformShippingMethodName platformShippingMethodDescription
-    platformShippingPrice platformShippingPriceWithTax
-    preferredShippingMethodId
-    incotermStatus incotermCode incotermVersion incotermAddress incotermDescription
-    shippingLeadDays deliveryAdvice stale syncedAt warning resolvedAt
-    remoteShippingMethodCode remoteShippingMethodName
-    remoteIncotermCode remoteIncotermVersion remoteIncotermAddress remoteDeliveryDate
-    remoteConfirmedAt remoteMismatch
+const ORDER_DELIVERY_TERMS_FRAGMENT = fragment(/* GraphQL */ `
+  fragment OrderDeliveryTerms on Order {
+    deliveryTerms {
+      source managedExternally status shippingMethodStatus policyStatus summary selectionSource
+      selectedShippingMethodId selectedShippingMethodCode selectedShippingMethodName
+      platformShippingMethodCode platformShippingMethodName platformShippingMethodDescription
+      platformShippingPrice platformShippingPriceWithTax
+      preferredShippingMethodId
+      incotermStatus incotermCode incotermVersion incotermAddress incotermDescription
+      shippingLeadDays deliveryAdvice stale syncedAt warning resolvedAt
+      remoteShippingMethodCode remoteShippingMethodName
+      remoteIncotermCode remoteIncotermVersion remoteIncotermAddress remoteDeliveryDate
+      remoteConfirmedAt remoteMismatch
+    }
   }
-`;
+`);
 /**
  * Order-history list-item selection (customer order history). Enriched beyond a
  * bare line count so a storefront can render thumbnails + per-line totals
  * without a follow-up fetch. Shared by GET_CURRENT_CUSTOMER and
  * GET_CUSTOMER_ORDERS — both map to OrderSummary.
  */
-const ORDER_SUMMARY_FIELDS = `
-  id code state total totalWithTax currencyCode createdAt
-  lines {
-    id quantity linePriceWithTax
-    productVariant {
-      id name sku
-      product { slug featuredAsset { preview presets { xs { webpUrl } } } }
+const ORDER_SUMMARY_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment OrderSummary on Order {
+      id code state total totalWithTax currencyCode createdAt
+      lines {
+        id quantity linePriceWithTax
+        productVariant {
+          id name sku
+          product { slug featuredAsset { preview presets { xs { webpUrl } } } }
+        }
+      }
+      ...OrderFulfillments
+      ...OrderPaymentTerms
+      ...OrderDeliveryTerms
     }
-  }
-  ${ORDER_FULFILLMENTS_FRAGMENT}
-  ${ORDER_PAYMENT_TERMS_FRAGMENT}
-  ${ORDER_DELIVERY_TERMS_FRAGMENT}
-`;
+  `, ORDER_FULFILLMENTS_FRAGMENT, ORDER_PAYMENT_TERMS_FRAGMENT, ORDER_DELIVERY_TERMS_FRAGMENT);
 /**
  * The structured half of a placement rejection, selected wherever the Shop API
  * can answer one.
@@ -499,28 +648,30 @@ const ORDER_SUMMARY_FIELDS = `
  * are populated per code and null otherwise, so selecting all of them costs
  * one flat response object and saves a second round of documents per feature.
  */
-const PLACEMENT_FIELDS = `
-  code
-  customerMessage
-  linesTruncated
-  requiredAmount
-  currencyCode
-  amountBasis
-  requiredQuantity
-  priceListName
-  salesUnit
-  minimumAge
-  lines {
-    orderLineId
-    productVariantId
-    sku
-    productName
-    productVariantName
-    quantityRequested
-    quantityAvailable
-  }
-  details { field code message }
-`;
+const PLACEMENT_REJECTION_FRAGMENT = fragment(/* GraphQL */ `
+  fragment PlacementRejection on PlacementRejection {
+    code
+    customerMessage
+    linesTruncated
+    requiredAmount
+    currencyCode
+    amountBasis
+    requiredQuantity
+    priceListName
+    salesUnit
+    minimumAge
+    lines {
+      orderLineId
+      productVariantId
+      sku
+      productName
+      productVariantName
+      quantityRequested
+      quantityAvailable
+    }
+    details { field code message }
+  }
+`);
 /**
  * WHICH line an `InsufficientStockError` is about.
  *
@@ -530,124 +681,157 @@ const PLACEMENT_FIELDS = `
  * — an error raised outside the overridden cart mutations answers null to all
  * of them. `inputIndex` is only ever non-null inside `addItemsToOrder`.
  */
-const INSUFFICIENT_STOCK_FIELDS = `
-  errorCode message quantityAvailable
-  productVariantId orderLineId sku productName productVariantName
-  quantityRequested inputIndex
-`;
-export const ACTIVE_ORDER = `
-  query ActiveOrder {
-    activeOrder { ${ORDER_FIELDS} }
-  }
-`;
-export const ADD_TO_CART = `
-  mutation AddToCart($variantId: ID!, $quantity: Int!) {
-    addItemToOrder(productVariantId: $variantId, quantity: $quantity) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on OrderModificationError { errorCode message }
-      ... on OrderLimitError { errorCode message maxItems }
-      ... on NegativeQuantityError { errorCode message }
-      ... on InsufficientStockError { ${INSUFFICIENT_STOCK_FIELDS} order { id } }
+const INSUFFICIENT_STOCK_ERROR_FRAGMENT = fragment(/* GraphQL */ `
+  fragment InsufficientStockError on InsufficientStockError {
+    errorCode message quantityAvailable
+    productVariantId orderLineId sku productName productVariantName
+    quantityRequested inputIndex
+  }
+`);
+export const ACTIVE_ORDER = withFragments(
+/* GraphQL */ `
+    query ActiveOrder {
+      activeOrder { ...Order }
+    }
+  `, ORDER_FRAGMENT);
+export const ADD_TO_CART = withFragments(
+/* GraphQL */ `
+    mutation AddToCart($variantId: ID!, $quantity: Int!) {
+      addItemToOrder(productVariantId: $variantId, quantity: $quantity) {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+        ... on OrderLimitError { errorCode message maxItems }
+        ... on NegativeQuantityError { errorCode message }
+        ... on InsufficientStockError { ...InsufficientStockError order { id } }
+      }
     }
-  }
-`;
-export const ADJUST_ORDER_LINE = `
-  mutation AdjustOrderLine($lineId: ID!, $quantity: Int!) {
-    adjustOrderLine(orderLineId: $lineId, quantity: $quantity) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on OrderModificationError { errorCode message }
-      ... on OrderLimitError { errorCode message maxItems }
-      ... on NegativeQuantityError { errorCode message }
-      ... on InsufficientStockError { ${INSUFFICIENT_STOCK_FIELDS} }
+  `, ORDER_FRAGMENT, INSUFFICIENT_STOCK_ERROR_FRAGMENT);
+export const ADJUST_ORDER_LINE = withFragments(
+/* GraphQL */ `
+    mutation AdjustOrderLine($lineId: ID!, $quantity: Int!) {
+      adjustOrderLine(orderLineId: $lineId, quantity: $quantity) {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+        ... on OrderLimitError { errorCode message maxItems }
+        ... on NegativeQuantityError { errorCode message }
+        ... on InsufficientStockError { ...InsufficientStockError }
+      }
     }
-  }
-`;
-export const REMOVE_ORDER_LINE = `
-  mutation RemoveOrderLine($lineId: ID!) {
-    removeOrderLine(orderLineId: $lineId) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on OrderModificationError { errorCode message }
+  `, ORDER_FRAGMENT, INSUFFICIENT_STOCK_ERROR_FRAGMENT);
+export const REMOVE_ORDER_LINE = withFragments(
+/* GraphQL */ `
+    mutation RemoveOrderLine($lineId: ID!) {
+      removeOrderLine(orderLineId: $lineId) {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+      }
     }
-  }
-`;
-export const APPLY_COUPON = `
-  mutation ApplyCoupon($code: String!) {
-    applyCouponCode(couponCode: $code) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on CouponCodeExpiredError { errorCode message couponCode }
-      ... on CouponCodeInvalidError { errorCode message couponCode }
-      ... on CouponCodeLimitError { errorCode message couponCode limit }
+  `, ORDER_FRAGMENT);
+export const APPLY_COUPON = withFragments(
+/* GraphQL */ `
+    mutation ApplyCoupon($code: String!) {
+      applyCouponCode(couponCode: $code) {
+        ... on Order { ...Order }
+        ... on CouponCodeExpiredError { errorCode message couponCode }
+        ... on CouponCodeInvalidError { errorCode message couponCode }
+        ... on CouponCodeLimitError { errorCode message couponCode limit }
+      }
     }
-  }
-`;
-export const REMOVE_COUPON = `
-  mutation RemoveCoupon($code: String!) {
-    removeCouponCode(couponCode: $code) { ${ORDER_FIELDS} }
-  }
-`;
-export const REMOVE_ALL_ORDER_LINES = `
-  mutation RemoveAllOrderLines {
-    removeAllOrderLines {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on OrderModificationError { errorCode message }
+  `, ORDER_FRAGMENT);
+export const REMOVE_COUPON = withFragments(
+/* GraphQL */ `
+    mutation RemoveCoupon($code: String!) {
+      removeCouponCode(couponCode: $code) { ...Order }
+    }
+  `, ORDER_FRAGMENT);
+export const REMOVE_ALL_ORDER_LINES = withFragments(
+/* GraphQL */ `
+    mutation RemoveAllOrderLines {
+      removeAllOrderLines {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+      }
     }
-  }
-`;
+  `, ORDER_FRAGMENT);
 /**
  * Bulk add (favourite-box bundles). `addItemsToOrder` returns
  * UpdateMultipleOrderItemsResult: a single resulting Order plus a per-input
  * `errorResults` list — partial success is possible, so surface both.
  */
-export const ADD_ITEMS_TO_CART = `
-  mutation AddItemsToCart($inputs: [AddItemInput!]!) {
-    addItemsToOrder(inputs: $inputs) {
-      order { ${ORDER_FIELDS} }
-      errorResults {
-        ... on OrderModificationError { errorCode message }
-        ... on OrderLimitError { errorCode message maxItems }
-        ... on NegativeQuantityError { errorCode message }
-        ... on InsufficientStockError { ${INSUFFICIENT_STOCK_FIELDS} }
-        ... on OrderInterceptorError { errorCode message interceptorError }
+export const ADD_ITEMS_TO_CART = withFragments(
+/* GraphQL */ `
+    mutation AddItemsToCart($inputs: [AddItemInput!]!) {
+      addItemsToOrder(inputs: $inputs) {
+        order { ...Order }
+        errorResults {
+          ... on OrderModificationError { errorCode message }
+          ... on OrderLimitError { errorCode message maxItems }
+          ... on NegativeQuantityError { errorCode message }
+          ... on InsufficientStockError { ...InsufficientStockError }
+          ... on OrderInterceptorError { errorCode message interceptorError }
+        }
       }
     }
-  }
-`;
+  `, ORDER_FRAGMENT, INSUFFICIENT_STOCK_ERROR_FRAGMENT);
 // --- Checkout Mutations ---
-export const SET_CUSTOMER = `
-  mutation SetCustomer($input: CreateCustomerInput!) {
-    setCustomerForOrder(input: $input) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on AlreadyLoggedInError { errorCode message }
-      ... on EmailAddressConflictError { errorCode message }
-      ... on GuestCheckoutError { errorCode message }
-      ... on NoActiveOrderError { errorCode message }
+export const SET_CUSTOMER = withFragments(
+/* GraphQL */ `
+    mutation SetCustomer($input: CreateCustomerInput!) {
+      setCustomerForOrder(input: $input) {
+        ... on Order { ...Order }
+        ... on AlreadyLoggedInError { errorCode message }
+        ... on EmailAddressConflictError { errorCode message }
+        ... on GuestCheckoutError { errorCode message }
+        ... on NoActiveOrderError { errorCode message }
+      }
     }
-  }
-`;
-export const SET_SHIPPING_ADDRESS = `
-  mutation SetShippingAddress($input: CreateAddressInput!) {
-    setOrderShippingAddress(input: $input) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on NoActiveOrderError { errorCode message }
+  `, ORDER_FRAGMENT);
+export const SET_SHIPPING_ADDRESS = withFragments(
+/* GraphQL */ `
+    mutation SetShippingAddress($input: CreateAddressInput!) {
+      setOrderShippingAddress(input: $input) {
+        ... on Order { ...Order }
+        ... on NoActiveOrderError { errorCode message }
+      }
     }
-  }
-`;
-export const SET_BILLING_ADDRESS = `
-  mutation SetBillingAddress($input: CreateAddressInput!) {
-    setOrderBillingAddress(input: $input) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on NoActiveOrderError { errorCode message }
+  `, ORDER_FRAGMENT);
+export const SET_BILLING_ADDRESS = withFragments(
+/* GraphQL */ `
+    mutation SetBillingAddress($input: CreateAddressInput!) {
+      setOrderBillingAddress(input: $input) {
+        ... on Order { ...Order }
+        ... on NoActiveOrderError { errorCode message }
+      }
     }
-  }
-`;
-export const ELIGIBLE_SHIPPING_METHODS = `
+  `, ORDER_FRAGMENT);
+export const ELIGIBLE_SHIPPING_METHODS = /* GraphQL */ `
   query ShippingMethods {
     eligibleShippingMethods {
       id name description price priceWithTax metadata isPreferred isDeliveryTermsEligible
     }
   }
 `;
-export const MY_DELIVERY_TERMS = `
+/** Every platform method and every app rate the active order can ship with (`shipping.rates`). */
+export const ELIGIBLE_SHIPPING_RATES = /* GraphQL */ `
+  query ShippingRates {
+    eligibleShippingRates {
+      shippingMethodId code rateCode name description price priceWithTax source appSlug selected
+      isPreferred isDeliveryTermsEligible
+    }
+  }
+`;
+export const SET_SHIPPING_RATE = withFragments(
+/* GraphQL */ `
+    mutation SetShippingRate($shippingMethodId: ID!, $rateCode: String) {
+      setOrderShippingRate(shippingMethodId: $shippingMethodId, rateCode: $rateCode) {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+        ... on IneligibleShippingMethodError { errorCode message }
+        ... on NoActiveOrderError { errorCode message }
+      }
+    }
+  `, ORDER_FRAGMENT);
+export const MY_DELIVERY_TERMS = /* GraphQL */ `
   query MyDeliveryTerms {
     myDeliveryTerms {
       customerId source managedExternally status shippingMethodStatus policyStatus summary
@@ -659,44 +843,161 @@ export const MY_DELIVERY_TERMS = `
     }
   }
 `;
-export const SET_SHIPPING_METHOD = `
-  mutation SetShippingMethod($ids: [ID!]!) {
-    selectOrderDeliveryMethod(shippingMethodIds: $ids) {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on OrderModificationError { errorCode message }
-      ... on IneligibleShippingMethodError { errorCode message }
-      ... on NoActiveOrderError { errorCode message }
+export const SET_SHIPPING_METHOD = withFragments(
+/* GraphQL */ `
+    mutation SetShippingMethod($ids: [ID!]!) {
+      selectOrderDeliveryMethod(shippingMethodIds: $ids) {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+        ... on IneligibleShippingMethodError { errorCode message }
+        ... on NoActiveOrderError { errorCode message }
+      }
     }
-  }
-`;
-export const APPLY_PREFERRED_SHIPPING_METHOD = `
-  mutation ApplyPreferredShippingMethod {
-    applyPreferredDeliveryMethod {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on OrderModificationError { errorCode message }
-      ... on IneligibleShippingMethodError { errorCode message }
-      ... on NoActiveOrderError { errorCode message }
+  `, ORDER_FRAGMENT);
+export const APPLY_PREFERRED_SHIPPING_METHOD = withFragments(
+/* GraphQL */ `
+    mutation ApplyPreferredShippingMethod {
+      applyPreferredDeliveryMethod {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+        ... on IneligibleShippingMethodError { errorCode message }
+        ... on NoActiveOrderError { errorCode message }
+      }
     }
-  }
-`;
-export const ELIGIBLE_PAYMENT_METHODS = `
+  `, ORDER_FRAGMENT);
+export const ELIGIBLE_PAYMENT_METHODS = /* GraphQL */ `
   query PaymentMethods {
     eligiblePaymentMethods {
       id name code description isEligible eligibilityMessage
     }
   }
 `;
-export const TRANSITION_TO_ARRANGING_PAYMENT = `
-  mutation TransitionToArrangingPayment {
-    transitionOrderToState(state: "ArrangingPayment") {
-      ... on Order { ${ORDER_FIELDS} }
-      ... on OrderStateTransitionError {
-        errorCode message transitionError
-        placement { ${PLACEMENT_FIELDS} }
+export const TRANSITION_TO_ARRANGING_PAYMENT = withFragments(
+/* GraphQL */ `
+    mutation TransitionToArrangingPayment {
+      transitionOrderToState(state: "ArrangingPayment") {
+        ... on Order { ...Order }
+        ... on OrderStateTransitionError {
+          errorCode message transitionError
+          placement { ...PlacementRejection }
+        }
+      }
+    }
+  `, ORDER_FRAGMENT, PLACEMENT_REJECTION_FRAGMENT);
+/**
+ * `TRANSITION_TO_ARRANGING_PAYMENT` with the target state as a variable. The
+ * engine's order process and its placement guards decide which targets a
+ * shopper may reach; the document only carries the request.
+ */
+export const TRANSITION_ORDER = withFragments(
+/* GraphQL */ `
+    mutation TransitionOrder($state: String!) {
+      transitionOrderToState(state: $state) {
+        ... on Order { ...Order }
+        ... on OrderStateTransitionError {
+          errorCode message transitionError
+          placement { ...PlacementRejection }
+        }
       }
     }
+  `, ORDER_FRAGMENT, PLACEMENT_REJECTION_FRAGMENT);
+export const NEXT_ORDER_STATES = /* GraphQL */ `
+  query NextOrderStates {
+    nextOrderStates
   }
 `;
+/**
+ * Every payment method enabled on the channel, whatever the active order.
+ * `customFields` is NOT selected: it is a raw JSON passthrough of the entity's
+ * custom fields, which are all private on this platform.
+ */
+const PUBLIC_PAYMENT_METHOD_FRAGMENT = fragment(/* GraphQL */ `
+  fragment PublicPaymentMethod on PublicPaymentMethod {
+    id code name description
+  }
+`);
+export const ACTIVE_PAYMENT_METHODS = withFragments(
+/* GraphQL */ `
+    query ActivePaymentMethods {
+      activePaymentMethods { ...PublicPaymentMethod }
+    }
+  `, PUBLIC_PAYMENT_METHOD_FRAGMENT);
+const PUBLIC_SHIPPING_METHOD_FRAGMENT = fragment(/* GraphQL */ `
+  fragment PublicShippingMethod on PublicShippingMethod {
+    id code name description
+  }
+`);
+/** Every shipping method offered on the channel's storefront, whatever the active order. */
+export const ACTIVE_SHIPPING_METHODS = withFragments(
+/* GraphQL */ `
+    query ActiveShippingMethods {
+      activeShippingMethods { ...PublicShippingMethod }
+    }
+  `, PUBLIC_SHIPPING_METHOD_FRAGMENT);
+/**
+ * The order custom fields the Shop API lets a shopper write — exactly the
+ * members of `UpdateOrderCustomFieldsInput` (public, not read-only) — selected
+ * back on `setOrderCustomFields` so the caller sees what the engine stored.
+ *
+ * Selected on that ONE document: the shared `ORDER_FRAGMENT` stays free of
+ * custom fields, so an engine that predates one of these fields fails only the
+ * call that writes them, never every cart read.
+ */
+const ORDER_WRITABLE_CUSTOM_FIELDS_FRAGMENT = fragment(/* GraphQL */ `
+  fragment OrderWritableCustomFields on OrderCustomFields {
+    isGift giftNote hidePricesOnPackingSlip
+    poNumber requestedDeliveryDate orderNotes
+    snTid snUtmSource snUtmMedium snUtmCampaign snFlowId snEnrollmentId snStepId
+  }
+`);
+export const SET_ORDER_CUSTOM_FIELDS = withFragments(
+/* GraphQL */ `
+    mutation SetOrderCustomFields($input: UpdateOrderInput!) {
+      setOrderCustomFields(input: $input) {
+        ... on Order {
+          ...Order
+          customFields { ...OrderWritableCustomFields }
+        }
+        ... on NoActiveOrderError { errorCode message }
+      }
+    }
+  `, ORDER_FRAGMENT, ORDER_WRITABLE_CUSTOM_FIELDS_FRAGMENT);
+export const UNSET_SHIPPING_ADDRESS = withFragments(
+/* GraphQL */ `
+    mutation UnsetShippingAddress {
+      unsetOrderShippingAddress {
+        ... on Order { ...Order }
+        ... on NoActiveOrderError { errorCode message }
+      }
+    }
+  `, ORDER_FRAGMENT);
+export const UNSET_BILLING_ADDRESS = withFragments(
+/* GraphQL */ `
+    mutation UnsetBillingAddress {
+      unsetOrderBillingAddress {
+        ... on Order { ...Order }
+        ... on NoActiveOrderError { errorCode message }
+      }
+    }
+  `, ORDER_FRAGMENT);
+/**
+ * `setCurrencyCodeForOrder` answers `UpdateOrderItemsResult`, so every member of
+ * that union is selected: an unselected member comes back as `{}`, which
+ * carries no `errorCode` and would read as success.
+ */
+export const SET_ORDER_CURRENCY = withFragments(
+/* GraphQL */ `
+    mutation SetOrderCurrency($currencyCode: CurrencyCode!) {
+      setCurrencyCodeForOrder(currencyCode: $currencyCode) {
+        ... on Order { ...Order }
+        ... on OrderModificationError { errorCode message }
+        ... on OrderLimitError { errorCode message maxItems }
+        ... on NegativeQuantityError { errorCode message }
+        ... on InsufficientStockError { ...InsufficientStockError }
+        ... on OrderInterceptorError { errorCode message interceptorError }
+      }
+    }
+  `, ORDER_FRAGMENT, INSUFFICIENT_STOCK_ERROR_FRAGMENT);
 /**
  * Record how the buyer intends to pay AND re-price the order in one round trip.
  *
@@ -708,85 +1009,91 @@ export const TRANSITION_TO_ARRANGING_PAYMENT = `
  * the pay-now discount.
  *
  * `customFields { paymentIntent }` is selected HERE and nowhere else, and that
- * is deliberate. Putting it in the shared `ORDER_FIELDS` would make every order
+ * is deliberate. Putting it in the shared `ORDER_FRAGMENT` would make every order
  * query and cart mutation in this client fail GraphQL validation against an
  * engine that predates the field — one missing feature would take the whole cart
  * down. Confined to this document, only the call that needs the field is
  * coupled to an engine that has it.
  */
-export const SET_PAYMENT_INTENT = `
-  mutation SetOrderPaymentIntent($intent: OrderPaymentIntent!) {
-    setOrderPaymentIntent(intent: $intent) {
-      ... on Order {
-        ${ORDER_FIELDS}
-        customFields { paymentIntent }
+export const SET_PAYMENT_INTENT = withFragments(
+/* GraphQL */ `
+    mutation SetOrderPaymentIntent($intent: OrderPaymentIntent!) {
+      setOrderPaymentIntent(intent: $intent) {
+        ... on Order {
+          ...Order
+          customFields { paymentIntent }
+        }
+        ... on NoActiveOrderError { errorCode message }
       }
-      ... on NoActiveOrderError { errorCode message }
     }
-  }
-`;
-export const ADD_PAYMENT = `
-  mutation AddPayment($input: PaymentInput!) {
-    addPaymentToOrder(input: $input) {
-      ... on Order {
-        ${ORDER_FIELDS}
-        ${ORDER_PAYMENT_TERMS_FRAGMENT}
-        ${ORDER_DELIVERY_TERMS_FRAGMENT}
-      }
-      ... on OrderPaymentStateError { errorCode message }
-      ... on IneligiblePaymentMethodError { errorCode message }
-      ... on PaymentFailedError {
-        errorCode message paymentErrorMessage
-        placement { ${PLACEMENT_FIELDS} }
-      }
-      ... on PaymentDeclinedError {
-        errorCode message paymentErrorMessage
-        placement { ${PLACEMENT_FIELDS} }
-      }
-      ... on OrderStateTransitionError {
-        errorCode message transitionError
-        placement { ${PLACEMENT_FIELDS} }
+  `, ORDER_FRAGMENT);
+export const ADD_PAYMENT = withFragments(
+/* GraphQL */ `
+    mutation AddPayment($input: PaymentInput!) {
+      addPaymentToOrder(input: $input) {
+        ... on Order {
+          ...Order
+          ...OrderPaymentTerms
+          ...OrderDeliveryTerms
+        }
+        ... on OrderPaymentStateError { errorCode message }
+        ... on IneligiblePaymentMethodError { errorCode message }
+        ... on PaymentFailedError {
+          errorCode message paymentErrorMessage
+          placement { ...PlacementRejection }
+        }
+        ... on PaymentDeclinedError {
+          errorCode message paymentErrorMessage
+          placement { ...PlacementRejection }
+        }
+        ... on OrderStateTransitionError {
+          errorCode message transitionError
+          placement { ...PlacementRejection }
+        }
+        ... on NoActiveOrderError { errorCode message }
       }
-      ... on NoActiveOrderError { errorCode message }
     }
-  }
-`;
+  `, ORDER_FRAGMENT, ORDER_PAYMENT_TERMS_FRAGMENT, ORDER_DELIVERY_TERMS_FRAGMENT, PLACEMENT_REJECTION_FRAGMENT);
 // --- Carrier-agnostic pickup locations (vendure-plugin-myparcel Phase 6) ---
-const PICKUP_LOCATION_FIELDS = `
-  provider
-  carrier
-  locationCode
-  name
-  address {
-    streetLine1
-    number
-    postalCode
-    city
-    countryCode
-    region
-  }
-  openingHours {
-    weekday
-    open
-    close
-  }
-  details
-`;
-export const PICKUP_LOCATIONS = `
-  query PickupLocations($input: PickupLocationSearchInput!) {
-    pickupLocations(input: $input) {
-      ${PICKUP_LOCATION_FIELDS}
+const PICKUP_LOCATION_FRAGMENT = fragment(/* GraphQL */ `
+  fragment PickupLocation on PickupLocation {
+    provider
+    carrier
+    locationCode
+    name
+    address {
+      streetLine1
+      number
+      postalCode
+      city
+      countryCode
+      region
+    }
+    openingHours {
+      weekday
+      open
+      close
+    }
+    details
+  }
+`);
+export const PICKUP_LOCATIONS = withFragments(
+/* GraphQL */ `
+    query PickupLocations($input: PickupLocationSearchInput!) {
+      pickupLocations(input: $input) {
+        ...PickupLocation
+      }
     }
-  }
-`;
-export const ACTIVE_ORDER_PICKUP_LOCATION = `
-  query ActiveOrderPickupLocation {
-    activeOrderPickupLocation {
-      ${PICKUP_LOCATION_FIELDS}
+  `, PICKUP_LOCATION_FRAGMENT);
+export const ACTIVE_ORDER_PICKUP_LOCATION = withFragments(
+/* GraphQL */ `
+    query ActiveOrderPickupLocation {
+      activeOrderPickupLocation {
+        ...PickupLocation
+      }
     }
-  }
-`;
-export const SET_ACTIVE_ORDER_PICKUP_LOCATION = `
+  `, PICKUP_LOCATION_FRAGMENT);
+export const SET_ACTIVE_ORDER_PICKUP_LOCATION = /* GraphQL */ `
   mutation SetActiveOrderPickupLocation($location: StoredPickupLocationInput!) {
     setActiveOrderPickupLocation(location: $location) {
       __typename
@@ -801,13 +1108,13 @@ export const SET_ACTIVE_ORDER_PICKUP_LOCATION = `
   }
 `;
 // --- Stripe (@vendure-community/stripe-plugin) ---
-export const CREATE_STRIPE_PAYMENT_INTENT = `
+export const CREATE_STRIPE_PAYMENT_INTENT = /* GraphQL */ `
   mutation CreateStripePaymentIntent {
     createStripePaymentIntent
   }
 `;
 // --- Mollie (@vendure-community/mollie-plugin) ---
-export const MOLLIE_PAYMENT_METHODS = `
+export const MOLLIE_PAYMENT_METHODS = /* GraphQL */ `
   query MolliePaymentMethods($input: MolliePaymentMethodsInput!) {
     molliePaymentMethods(input: $input) {
       id
@@ -820,7 +1127,7 @@ export const MOLLIE_PAYMENT_METHODS = `
     }
   }
 `;
-export const ORDERED_MOLLIE_PAYMENT_METHODS = `
+export const ORDERED_MOLLIE_PAYMENT_METHODS = /* GraphQL */ `
   query OrderedMolliePaymentMethods($paymentMethodCode: String!) {
     orderedMolliePaymentMethods(paymentMethodCode: $paymentMethodCode) {
       id
@@ -831,7 +1138,7 @@ export const ORDERED_MOLLIE_PAYMENT_METHODS = `
     }
   }
 `;
-export const CREATE_MOLLIE_PAYMENT_INTENT = `
+export const CREATE_MOLLIE_PAYMENT_INTENT = /* GraphQL */ `
   mutation CreateMolliePaymentIntent($input: MolliePaymentIntentInput!) {
     createMolliePaymentIntent(input: $input) {
       ... on MolliePaymentIntent { url }
@@ -839,7 +1146,7 @@ export const CREATE_MOLLIE_PAYMENT_INTENT = `
     }
   }
 `;
-export const SYNC_MOLLIE_PAYMENT_STATUS = `
+export const SYNC_MOLLIE_PAYMENT_STATUS = /* GraphQL */ `
   mutation SyncMolliePaymentStatus($orderCode: String!) {
     syncMolliePaymentStatus(orderCode: $orderCode) {
       id
@@ -848,8 +1155,101 @@ export const SYNC_MOLLIE_PAYMENT_STATUS = `
     }
   }
 `;
+// --- Parked (held) orders ---
+/**
+ * The money on a held order, as the storefront sees it: what it bills, what is
+ * covered, what is left, and the currency all three are in. Narrower than the
+ * merchant's own view of the same order — settled-vs-authorized and per-payment
+ * refunds are bookkeeping a shopper is not shown.
+ */
+const PARKED_ORDER_FRAGMENT = fragment(/* GraphQL */ `
+  fragment ParkedOrder on ParkedOrder {
+    id
+    code
+    state
+    position { total covered outstanding currencyCode }
+    reason
+  }
+`);
+export const PARKED_ORDERS_QUERY = withFragments(
+/* GraphQL */ `
+    query ParkedOrders {
+      parkedOrders {
+        ...ParkedOrder
+      }
+    }
+  `, PARKED_ORDER_FRAGMENT);
+export const PAY_PARKED_ORDER_MUTATION = /* GraphQL */ `
+  mutation PayParkedOrder(
+    $orderCode: String!
+    $input: PayParkedOrderInput!
+    $idempotencyKey: String
+  ) {
+    payParkedOrder(orderCode: $orderCode, input: $input, idempotencyKey: $idempotencyKey) {
+      order { id code state }
+      payment { id state amount method metadata }
+      position { total covered outstanding currencyCode }
+      settled
+    }
+  }
+`;
+export const CREATE_PARKED_ORDER_PAYMENT_INTENT_MUTATION = /* GraphQL */ `
+  mutation CreateParkedOrderPaymentIntent(
+    $orderCode: String!
+    $input: ParkedOrderPaymentIntentInput!
+    $idempotencyKey: String
+  ) {
+    createParkedOrderPaymentIntent(
+      orderCode: $orderCode
+      input: $input
+      idempotencyKey: $idempotencyKey
+    ) {
+      provider
+      url
+      clientSecret
+      amount
+      currencyCode
+    }
+  }
+`;
+/**
+ * A deposit paid in checkout, which parks the active order (W8-13).
+ *
+ * `order` selects exactly what `ADD_PAYMENT` selects for its `Order` member, so
+ * `addPayment(input, { amount })` — which routes here — resolves to the same
+ * type whether it paid in full or paid a deposit. No `idempotencyKey` argument:
+ * like `addPaymentToOrder`, this mutation is keyed by the `Idempotency-Key`
+ * header (the W8-12 contract), unlike the parked-order calls above.
+ */
+export const PAY_DEPOSIT_MUTATION = withFragments(
+/* GraphQL */ `
+    mutation PayDeposit($input: PayDepositInput!) {
+      payDeposit(input: $input) {
+        order {
+          ...Order
+          ...OrderPaymentTerms
+          ...OrderDeliveryTerms
+        }
+        payment { id state amount method metadata }
+        position { total covered outstanding currencyCode }
+        settled
+      }
+    }
+  `, ORDER_FRAGMENT, ORDER_PAYMENT_TERMS_FRAGMENT, ORDER_DELIVERY_TERMS_FRAGMENT);
+/** A card (Mollie) deposit in checkout; keyed by the header, as `PAY_DEPOSIT_MUTATION`. */
+export const CREATE_DEPOSIT_PAYMENT_INTENT_MUTATION = /* GraphQL */ `
+  mutation CreateDepositPaymentIntent($input: DepositPaymentIntentInput!) {
+    createDepositPaymentIntent(input: $input) {
+      provider
+      url
+      clientSecret
+      amount
+      currencyCode
+    }
+  }
+`;
 // --- Customer Queries/Mutations ---
-export const LOGIN = `
+export const LOGIN = /* GraphQL */ `
   mutation Login($email: String!, $password: String!) {
     login(username: $email, password: $password) {
       ... on CurrentUser { id identifier }
@@ -859,7 +1259,29 @@ export const LOGIN = `
     }
   }
 `;
-export const REGISTER = `
+const CURRENT_USER_FRAGMENT = fragment(/* GraphQL */ `
+  fragment CurrentUser on CurrentUser {
+    id identifier
+  }
+`);
+/**
+ * Sign in through a named authentication strategy (`native` is the only one the
+ * engine registers today). Every `AuthenticationResult` member is selected, and
+ * `authenticationError` with it: the engine's native strategy reports an
+ * imported account with no password (`PASSWORD_RESET_REQUIRED`) or an
+ * unverified one (`ACCOUNT_NOT_VERIFIED`) there, not as an error type.
+ */
+export const AUTHENTICATE = withFragments(
+/* GraphQL */ `
+    mutation Authenticate($input: AuthenticationInput!, $rememberMe: Boolean) {
+      authenticate(input: $input, rememberMe: $rememberMe) {
+        ... on CurrentUser { ...CurrentUser }
+        ... on InvalidCredentialsError { errorCode message authenticationError }
+        ... on NotVerifiedError { errorCode message }
+      }
+    }
+  `, CURRENT_USER_FRAGMENT);
+export const REGISTER = /* GraphQL */ `
   mutation Register($input: RegisterCustomerInput!) {
     registerCustomerAccount(input: $input) {
       ... on Success { success }
@@ -869,58 +1291,62 @@ export const REGISTER = `
     }
   }
 `;
-export const GET_CURRENT_CUSTOMER = `
-  query Me {
-    activeCustomer {
-      id firstName lastName emailAddress phoneNumber
-      groups { id name }
-      isB2B
-      addresses {
-        id fullName streetLine1 streetLine2 city province postalCode
-        country { code name }
-        defaultShippingAddress defaultBillingAddress
-      }
-      orders(options: { take: 10, sort: { createdAt: DESC } }) {
-        items {
-          ${ORDER_SUMMARY_FIELDS}
+export const GET_CURRENT_CUSTOMER = withFragments(
+/* GraphQL */ `
+    query Me {
+      activeCustomer {
+        id firstName lastName emailAddress phoneNumber
+        groups { id name }
+        isB2B
+        hasPassword
+        addresses {
+          id fullName streetLine1 streetLine2 city province postalCode
+          country { code name }
+          defaultShippingAddress defaultBillingAddress
+        }
+        orders(options: { take: 10, sort: { createdAt: DESC } }) {
+          items {
+            ...OrderSummary
+          }
+          totalItems
         }
-        totalItems
       }
     }
-  }
-`;
-export const ACTIVE_CUSTOMER_PRICE_LISTS = `
+  `, ORDER_SUMMARY_FRAGMENT);
+export const ACTIVE_CUSTOMER_PRICE_LISTS = /* GraphQL */ `
   query ActiveCustomerPriceLists {
     activeCustomerPriceLists { id name isContract }
   }
 `;
-export const GET_CUSTOMER_ORDERS = `
-  query CustomerOrders($options: OrderListOptions) {
-    activeCustomer {
-      orders(options: $options) {
-        items {
-          ${ORDER_SUMMARY_FIELDS}
-          lines { id backorderedQuantity }
+export const GET_CUSTOMER_ORDERS = withFragments(
+/* GraphQL */ `
+    query CustomerOrders($options: OrderListOptions) {
+      activeCustomer {
+        orders(options: $options) {
+          items {
+            ...OrderSummary
+            lines { id backorderedQuantity }
+            ...OrderFulfillmentParcels
+          }
+          totalItems
         }
-        totalItems
       }
     }
-  }
-`;
-export const LOGOUT = `
+  `, ORDER_FULFILLMENT_PARCELS_FRAGMENT, ORDER_SUMMARY_FRAGMENT);
+export const LOGOUT = /* GraphQL */ `
   mutation Logout {
     logout { success }
   }
 `;
 // --- Customer Account Management ---
-export const UPDATE_CUSTOMER = `
+export const UPDATE_CUSTOMER = /* GraphQL */ `
   mutation UpdateCustomer($input: UpdateCustomerInput!) {
     updateCustomer(input: $input) {
       id firstName lastName emailAddress phoneNumber
     }
   }
 `;
-export const UPDATE_PASSWORD = `
+export const UPDATE_PASSWORD = /* GraphQL */ `
   mutation UpdatePassword($currentPassword: String!, $newPassword: String!) {
     updateCustomerPassword(currentPassword: $currentPassword, newPassword: $newPassword) {
       ... on Success { success }
@@ -930,7 +1356,24 @@ export const UPDATE_PASSWORD = `
     }
   }
 `;
-export const REQUEST_PASSWORD_RESET = `
+/**
+ * The signed-in customer's FIRST password, for an account that signed in by
+ * email link or code and has none (`updatePassword` needs the current one).
+ * Every member is selected: an unselected error member arrives as `{}` and the
+ * wrapper would read a refused password as set.
+ */
+export const SET_CUSTOMER_PASSWORD = /* GraphQL */ `
+  mutation SetCustomerPassword($newPassword: String!) {
+    setCustomerPassword(newPassword: $newPassword) {
+      ... on Success { success }
+      ... on PasswordValidationError { errorCode message validationErrorMessage }
+      ... on PasswordAlreadySetError { errorCode message }
+      ... on NativeAuthStrategyError { errorCode message }
+      ... on SetPasswordRequiresEmailSignInError { errorCode message }
+    }
+  }
+`;
+export const REQUEST_PASSWORD_RESET = /* GraphQL */ `
   mutation RequestPasswordReset($emailAddress: String!) {
     requestPasswordReset(emailAddress: $emailAddress) {
       ... on Success { success }
@@ -938,7 +1381,7 @@ export const REQUEST_PASSWORD_RESET = `
     }
   }
 `;
-export const RESET_PASSWORD = `
+export const RESET_PASSWORD = /* GraphQL */ `
   mutation ResetPassword($token: String!, $password: String!) {
     resetPassword(token: $token, password: $password) {
       ... on CurrentUser { id identifier }
@@ -950,15 +1393,18 @@ export const RESET_PASSWORD = `
     }
   }
 `;
-export const REQUEST_MAGIC_LINK = `
-  mutation RequestMagicLink($emailAddress: String!) {
-    requestMagicLink(emailAddress: $emailAddress) {
+// `MagicLinkRateLimitedError` must stay selected: an unselected union member
+// comes back as `{}`, which carries no `errorCode` and reads as success.
+export const REQUEST_MAGIC_LINK = /* GraphQL */ `
+  mutation RequestMagicLink($emailAddress: String!, $portal: MagicLinkPortal) {
+    requestMagicLink(emailAddress: $emailAddress, portal: $portal) {
       ... on Success { success }
       ... on NativeAuthStrategyError { errorCode message }
+      ... on MagicLinkRateLimitedError { errorCode message retryAfterSeconds }
     }
   }
 `;
-export const LOGIN_WITH_MAGIC_LINK = `
+export const LOGIN_WITH_MAGIC_LINK = /* GraphQL */ `
   mutation LoginWithMagicLink($token: String!) {
     loginWithMagicLink(token: $token) {
       ... on CurrentUser { id identifier }
@@ -970,7 +1416,7 @@ export const LOGIN_WITH_MAGIC_LINK = `
     }
   }
 `;
-export const LOGIN_WITH_MAGIC_CODE = `
+export const LOGIN_WITH_MAGIC_CODE = /* GraphQL */ `
   mutation LoginWithMagicCode($emailAddress: String!, $code: String!) {
     loginWithMagicCode(emailAddress: $emailAddress, code: $code) {
       ... on CurrentUser { id identifier }
@@ -982,7 +1428,7 @@ export const LOGIN_WITH_MAGIC_CODE = `
     }
   }
 `;
-export const REQUEST_EMAIL_UPDATE = `
+export const REQUEST_EMAIL_UPDATE = /* GraphQL */ `
   mutation RequestEmailUpdate($password: String!, $newEmailAddress: String!) {
     requestUpdateCustomerEmailAddress(password: $password, newEmailAddress: $newEmailAddress) {
       ... on Success { success }
@@ -994,7 +1440,7 @@ export const REQUEST_EMAIL_UPDATE = `
     }
   }
 `;
-export const UPDATE_EMAIL = `
+export const UPDATE_EMAIL = /* GraphQL */ `
   mutation UpdateEmail($token: String!) {
     updateCustomerEmailAddress(token: $token) {
       ... on Success { success }
@@ -1004,7 +1450,7 @@ export const UPDATE_EMAIL = `
     }
   }
 `;
-export const VERIFY_ACCOUNT = `
+export const VERIFY_ACCOUNT = /* GraphQL */ `
   mutation VerifyAccount($token: String!, $password: String) {
     verifyCustomerAccount(token: $token, password: $password) {
       ... on CurrentUser { id identifier }
@@ -1017,7 +1463,7 @@ export const VERIFY_ACCOUNT = `
     }
   }
 `;
-export const REFRESH_VERIFICATION = `
+export const REFRESH_VERIFICATION = /* GraphQL */ `
   mutation RefreshVerification($emailAddress: String!) {
     refreshCustomerVerification(emailAddress: $emailAddress) {
       ... on Success { success }
@@ -1026,7 +1472,7 @@ export const REFRESH_VERIFICATION = `
   }
 `;
 // --- Address Management ---
-export const CREATE_ADDRESS = `
+export const CREATE_ADDRESS = /* GraphQL */ `
   mutation CreateAddress($input: CreateAddressInput!) {
     createCustomerAddress(input: $input) {
       id fullName streetLine1 streetLine2 city province postalCode
@@ -1035,7 +1481,7 @@ export const CREATE_ADDRESS = `
     }
   }
 `;
-export const UPDATE_ADDRESS = `
+export const UPDATE_ADDRESS = /* GraphQL */ `
   mutation UpdateAddress($input: UpdateAddressInput!) {
     updateCustomerAddress(input: $input) {
       id fullName streetLine1 streetLine2 city province postalCode
@@ -1044,7 +1490,7 @@ export const UPDATE_ADDRESS = `
     }
   }
 `;
-export const DELETE_ADDRESS = `
+export const DELETE_ADDRESS = /* GraphQL */ `
   mutation DeleteAddress($id: ID!) {
     deleteCustomerAddress(id: $id) {
       success
@@ -1052,7 +1498,7 @@ export const DELETE_ADDRESS = `
   }
 `;
 // --- Utility Queries ---
-export const AVAILABLE_COUNTRIES = `
+export const AVAILABLE_COUNTRIES = /* GraphQL */ `
   query AvailableCountries {
     availableCountries {
       id code name
@@ -1062,30 +1508,38 @@ export const AVAILABLE_COUNTRIES = `
 /**
  * `lines { backorderedQuantity }` is selected HERE and on `GET_CUSTOMER_ORDERS`,
  * and nowhere else — the same rule `customFields { paymentIntent }` follows
- * below. In the shared `ORDER_FIELDS` fragment it would make every cart read
+ * below. In the shared `ORDER_FRAGMENT` fragment it would make every cart read
  * and mutation fail validation against an engine that predates the backorders
  * plugin, taking the whole cart down for a field a cart line never carries a
  * value for (the stamp is written at placement). GraphQL merges this `lines`
  * selection with the fragment's, so the line still comes back whole.
+ *
+ * `customFields { chargedParcelCount }` follows the same rule: frozen when the
+ * order leaves the cart, so it belongs to this placed-order read alone. It
+ * does make this document need an engine with the extra-parcel charge: a
+ * client release carrying it publishes after that engine is deployed.
  */
-export const ORDER_BY_CODE = `
-  query OrderByCode($code: String!) {
-    orderByCode(code: $code) {
-      ${ORDER_FIELDS}
-      lines { id backorderedQuantity }
-      ${ORDER_FULFILLMENTS_FRAGMENT}
-      ${ORDER_PAYMENT_TERMS_FRAGMENT}
-      ${ORDER_DELIVERY_TERMS_FRAGMENT}
+export const ORDER_BY_CODE = withFragments(
+/* GraphQL */ `
+    query OrderByCode($code: String!) {
+      orderByCode(code: $code) {
+        ...Order
+        lines { id backorderedQuantity }
+        customFields { chargedParcelCount }
+        ...OrderFulfillments
+        ...OrderFulfillmentParcels
+        ...OrderPaymentTerms
+        ...OrderDeliveryTerms
+      }
     }
-  }
-`;
+  `, ORDER_FRAGMENT, ORDER_FULFILLMENTS_FRAGMENT, ORDER_FULFILLMENT_PARCELS_FRAGMENT, ORDER_PAYMENT_TERMS_FRAGMENT, ORDER_DELIVERY_TERMS_FRAGMENT);
 // --- Favorites ---
-export const FAVORITE_VARIANT_IDS = `
+export const FAVORITE_VARIANT_IDS = /* GraphQL */ `
   query FavoriteVariantIds {
     favoriteProductVariantIds
   }
 `;
-export const MY_FAVORITES = `
+export const MY_FAVORITES = /* GraphQL */ `
   query MyFavorites($options: FavoriteListOptions) {
     myFavorites(options: $options) {
       items {
@@ -1118,12 +1572,12 @@ export const MY_FAVORITES = `
     }
   }
 `;
-export const TOGGLE_FAVORITE = `
+export const TOGGLE_FAVORITE = /* GraphQL */ `
   mutation ToggleFavorite($productVariantId: ID!) {
     toggleFavorite(productVariantId: $productVariantId)
   }
 `;
-export const REMOVE_FAVORITE = `
+export const REMOVE_FAVORITE = /* GraphQL */ `
   mutation RemoveFavorite($productVariantId: ID!) {
     removeFavorite(productVariantId: $productVariantId)
   }
@@ -1135,8 +1589,8 @@ export const REMOVE_FAVORITE = `
  * in types.ts and the `public: true` Channel customFields configured on
  * the Vendure side.
  */
-const CHANNEL_CUSTOM_FIELDS_FRAGMENT = `
-  customFields {
+const CHANNEL_CUSTOM_FIELDS_FRAGMENT = fragment(/* GraphQL */ `
+  fragment ChannelCustomFields on ChannelCustomFields {
     businessName businessDescription
     logoAssetId darkLogoAssetId coverAssetId faviconAssetId
     websiteUrl primaryColor
@@ -1152,57 +1606,68 @@ const CHANNEL_CUSTOM_FIELDS_FRAGMENT = `
     returnsEnabled returnWindowDays
     taxDisplayDefault taxDisplayB2b taxExclusiveCountries
   }
-`;
-export const GET_ACTIVE_CHANNEL = `
-  query ActiveChannel {
-    activeChannel {
-      id code
-      defaultLanguageCode
-      availableLanguageCodes
-      defaultCurrencyCode
-      availableCurrencyCodes
-      ${CHANNEL_CUSTOM_FIELDS_FRAGMENT}
+`);
+export const GET_ACTIVE_CHANNEL = withFragments(
+/* GraphQL */ `
+    query ActiveChannel {
+      activeChannel {
+        id code
+        defaultLanguageCode
+        availableLanguageCodes
+        defaultCurrencyCode
+        availableCurrencyCodes
+        customFields { ...ChannelCustomFields }
+      }
     }
-  }
-`;
+  `, CHANNEL_CUSTOM_FIELDS_FRAGMENT);
 // --- Product Properties ---
-export const PROPERTY_GROUPS = `
-  query PropertyGroups {
-    productPropertyGroups {
+/** Every property group, with each property's full config (`getPropertyGroups`). */
+export const PROPERTY_GROUP_FRAGMENT = fragment(/* GraphQL */ `
+  fragment PropertyGroup on PropertyGroup {
+    id position
+    translations { id languageCode name }
+    properties {
+      id slug fieldType isFilterable isRequired position
+      config { options { value label } min max maxLength allowedCollectionIds filterableFieldSlugs }
+      facetId
+      fieldFacets { fieldSlug fieldType facetId }
+      translations { id languageCode name helpText }
+    }
+  }
+`);
+/** One product's values per group (`getProductProperties`); the group config is narrower. */
+export const PRODUCT_PROPERTY_GROUP_VALUES_FRAGMENT = fragment(/* GraphQL */ `
+  fragment ProductPropertyGroupValues on ProductPropertyGroupValues {
+    group {
       id position
       translations { id languageCode name }
       properties {
         id slug fieldType isFilterable isRequired position
-        config { options { value label } min max maxLength allowedCollectionIds filterableFieldSlugs }
+        config { options { value label } min max maxLength }
         facetId
         fieldFacets { fieldSlug fieldType facetId }
         translations { id languageCode name helpText }
       }
     }
+    values { id propertyId languageCode value }
   }
-`;
-export const PRODUCT_PROPERTIES = `
-  query ProductProperties($productId: ID!) {
-    productPropertyValues(productId: $productId) {
-      group {
-        id position
-        translations { id languageCode name }
-        properties {
-          id slug fieldType isFilterable isRequired position
-          config { options { value label } min max maxLength }
-          facetId
-          fieldFacets { fieldSlug fieldType facetId }
-          translations { id languageCode name helpText }
-        }
-      }
-      values { id propertyId languageCode value }
+`);
+export const PROPERTY_GROUPS = withFragments(
+/* GraphQL */ `
+    query PropertyGroups {
+      productPropertyGroups { ...PropertyGroup }
     }
-  }
-`;
+  `, PROPERTY_GROUP_FRAGMENT);
+export const PRODUCT_PROPERTIES = withFragments(
+/* GraphQL */ `
+    query ProductProperties($productId: ID!) {
+      productPropertyValues(productId: $productId) { ...ProductPropertyGroupValues }
+    }
+  `, PRODUCT_PROPERTY_GROUP_VALUES_FRAGMENT);
 // --- Product Recommendations ---
-export const GET_PRODUCT_RECOMMENDATIONS = `
-  query ProductRecommendations($productId: ID!, $groupSlug: String) {
-    productRecommendations(productId: $productId, groupSlug: $groupSlug) {
+export const RECOMMENDED_PRODUCT_GROUP_FRAGMENT = fragment(
+/* GraphQL */ `
+    fragment RecommendedProductGroup on RecommendedProducts {
       groupName
       groupSlug
       products {
@@ -1218,18 +1683,26 @@ export const GET_PRODUCT_RECOMMENDATIONS = `
           stockOnHand stockAllocated saleable
           incomingStock projectedSaleable nextExpectedArrival
           backorderAllowance
-          availability { state availableFrom orderable }
+          availability { ...ProductAvailability }
+          forSaleInCurrency
           priceListName retailPrice retailPriceWithTax taxRateApplied { value }
-          priceTiers { minQuantity price priceWithTax discountLabel }
-          availabilityByLocation { locationId locationName inStock }
+          priceTiers { ...PriceTier }
+          availabilityByLocation { ...VariantLocationAvailability }
           customFields { minOrderQuantity salesUnit position }
         }
       }
     }
-  }
-`;
+  `, PRODUCT_AVAILABILITY_FRAGMENT, PRICE_TIER_FRAGMENT, VARIANT_LOCATION_AVAILABILITY_FRAGMENT);
+export const GET_PRODUCT_RECOMMENDATIONS = withFragments(
+/* GraphQL */ `
+    query ProductRecommendations($productId: ID!, $groupSlug: String) {
+      productRecommendations(productId: $productId, groupSlug: $groupSlug) {
+        ...RecommendedProductGroup
+      }
+    }
+  `, RECOMMENDED_PRODUCT_GROUP_FRAGMENT);
 // --- Exchange Rates ---
-export const GET_EXCHANGE_RATES = `
+export const GET_EXCHANGE_RATES = /* GraphQL */ `
   query ExchangeRates {
     exchangeRates {
       baseCurrency targetCurrency rate inverseRate rateDate
@@ -1237,38 +1710,43 @@ export const GET_EXCHANGE_RATES = `
   }
 `;
 // Shared selection for the exchange-rates plugin's ConvertedAmount type.
-const CONVERTED_AMOUNT_FIELDS = `
-  originalAmount originalCurrency convertedAmount targetCurrency rate rateDate
-`;
-export const CONVERT_CURRENCY = `
-  query ConvertCurrency($amount: String!, $from: String!, $to: String!) {
-    convertCurrency(amount: $amount, fromCurrency: $from, toCurrency: $to) {
-      ${CONVERTED_AMOUNT_FIELDS}
+const CONVERTED_AMOUNT_FRAGMENT = fragment(/* GraphQL */ `
+  fragment ConvertedAmount on ConvertedAmount {
+    originalAmount originalCurrency convertedAmount targetCurrency rate rateDate
+  }
+`);
+export const CONVERT_CURRENCY = withFragments(
+/* GraphQL */ `
+    query ConvertCurrency($amount: String!, $from: String!, $to: String!) {
+      convertCurrency(amount: $amount, fromCurrency: $from, toCurrency: $to) {
+        ...ConvertedAmount
+      }
     }
-  }
-`;
-export const GET_EXCHANGE_RATE = `
+  `, CONVERTED_AMOUNT_FRAGMENT);
+export const GET_EXCHANGE_RATE = /* GraphQL */ `
   query ExchangeRate($targetCurrency: String!) {
     exchangeRate(targetCurrency: $targetCurrency) {
       baseCurrency targetCurrency rate inverseRate rateDate
     }
   }
 `;
-export const CONVERT_FROM_BASE = `
-  query ConvertFromBase($amount: String!, $targetCurrency: String!) {
-    convertFromBase(amount: $amount, targetCurrency: $targetCurrency) {
-      ${CONVERTED_AMOUNT_FIELDS}
+export const CONVERT_FROM_BASE = withFragments(
+/* GraphQL */ `
+    query ConvertFromBase($amount: String!, $targetCurrency: String!) {
+      convertFromBase(amount: $amount, targetCurrency: $targetCurrency) {
+        ...ConvertedAmount
+      }
     }
-  }
-`;
-export const CONVERT_TO_BASE = `
-  query ConvertToBase($amount: String!, $sourceCurrency: String!) {
-    convertToBase(amount: $amount, sourceCurrency: $sourceCurrency) {
-      ${CONVERTED_AMOUNT_FIELDS}
+  `, CONVERTED_AMOUNT_FRAGMENT);
+export const CONVERT_TO_BASE = withFragments(
+/* GraphQL */ `
+    query ConvertToBase($amount: String!, $sourceCurrency: String!) {
+      convertToBase(amount: $amount, sourceCurrency: $sourceCurrency) {
+        ...ConvertedAmount
+      }
     }
-  }
-`;
-export const CONVERT_TO_MULTIPLE = `
+  `, CONVERTED_AMOUNT_FRAGMENT);
+export const CONVERT_TO_MULTIPLE = /* GraphQL */ `
   query ConvertToMultiple($amount: String!, $from: String!, $to: [String!]!) {
     convertToMultiple(amount: $amount, fromCurrency: $from, toCurrencies: $to) {
       currency amount rate
@@ -1277,69 +1755,106 @@ export const CONVERT_TO_MULTIPLE = `
 `;
 // --- B2B Quotes ---
 /**
- * Per-line tax + product identity. These fields reach the Shop API with the
+ * Per-line tax + product identity (`productName sku taxRate unitPriceWithTax
+ * lineTotal lineTotalWithTax`). These fields reach the Shop API with the
  * `vendure-plugin-quotes` release that introduced them, and the SDK can be
  * upgraded before a tenant's Vendure is: an older server rejects the WHOLE
  * document at validation ("Cannot query field ..."), taking the quote page
  * down rather than dropping a column. So every quote document has a legacy
- * twin without them, and `createQuotesMethods` retries with it once — see
- * the fallback there. Keep the twins identical apart from this line.
+ * twin spreading `QuoteLegacy` instead, and `createQuotesMethods` retries with
+ * it once — see the fallback there. Keep the two fragments identical apart
+ * from that line, and each legacy document identical to its twin apart from
+ * the fragment it spreads and its `Legacy` operation name.
  */
-const QUOTE_LINE_TAX_FIELDS = 'productName sku taxRate unitPriceWithTax lineTotal lineTotalWithTax';
-const quoteFields = (lineTaxFields) => `
-  id code channelId customerId currencyCode status
-  expiresAt salesRepUserId customerNotes convertedOrderId
-  createdAt updatedAt
-  lines {
-    id productVariantId quantity unitPrice discountType discountValue discountLabel position
-    ${lineTaxFields}
+const QUOTE_FRAGMENT = fragment(/* GraphQL */ `
+  fragment Quote on Quote {
+    id code channelId customerId currencyCode status
+    expiresAt salesRepUserId customerNotes convertedOrderId
     createdAt updatedAt
-  }
-`;
-const QUOTE_FIELDS = quoteFields(QUOTE_LINE_TAX_FIELDS);
-const QUOTE_FIELDS_LEGACY = quoteFields('');
-const myQuotesDocument = (fields) => `
-  query MyQuotes($options: QuoteListOptions) {
-    myQuotes(options: $options) {
-      items { ${fields} }
-      totalItems
+    lines {
+      id productVariantId quantity unitPrice discountType discountValue discountLabel position
+      productName sku taxRate unitPriceWithTax lineTotal lineTotalWithTax
+      createdAt updatedAt
     }
   }
-`;
-const myQuoteDocument = (fields) => `
-  query MyQuote($id: ID!) {
-    myQuote(id: $id) { ${fields} }
-  }
-`;
-const createQuoteRequestDocument = (fields) => `
-  mutation CreateQuoteRequest($input: CreateQuoteRequestInput!) {
-    createQuoteRequest(input: $input) { ${fields} }
-  }
-`;
-const cancelMyQuoteDocument = (fields) => `
-  mutation CancelMyQuote($id: ID!, $reason: String) {
-    cancelMyQuote(id: $id, reason: $reason) { ${fields} }
-  }
-`;
-export const MY_QUOTES = myQuotesDocument(QUOTE_FIELDS);
-export const MY_QUOTES_LEGACY = myQuotesDocument(QUOTE_FIELDS_LEGACY);
-export const MY_QUOTE = myQuoteDocument(QUOTE_FIELDS);
-export const MY_QUOTE_LEGACY = myQuoteDocument(QUOTE_FIELDS_LEGACY);
-export const CREATE_QUOTE_REQUEST = createQuoteRequestDocument(QUOTE_FIELDS);
-export const CREATE_QUOTE_REQUEST_LEGACY = createQuoteRequestDocument(QUOTE_FIELDS_LEGACY);
-export const ACCEPT_QUOTE = `
-  mutation AcceptQuote($id: ID!) {
-    acceptQuote(id: $id) { ${ORDER_FIELDS} }
+`);
+const QUOTE_LEGACY_FRAGMENT = fragment(/* GraphQL */ `
+  fragment QuoteLegacy on Quote {
+    id code channelId customerId currencyCode status
+    expiresAt salesRepUserId customerNotes convertedOrderId
+    createdAt updatedAt
+    lines {
+      id productVariantId quantity unitPrice discountType discountValue discountLabel position
+      createdAt updatedAt
+    }
   }
-`;
-export const CANCEL_MY_QUOTE = cancelMyQuoteDocument(QUOTE_FIELDS);
-export const CANCEL_MY_QUOTE_LEGACY = cancelMyQuoteDocument(QUOTE_FIELDS_LEGACY);
+`);
+export const MY_QUOTES = withFragments(
+/* GraphQL */ `
+    query MyQuotes($options: QuoteListOptions) {
+      myQuotes(options: $options) {
+        items { ...Quote }
+        totalItems
+      }
+    }
+  `, QUOTE_FRAGMENT);
+export const MY_QUOTES_LEGACY = withFragments(
+/* GraphQL */ `
+    query MyQuotesLegacy($options: QuoteListOptions) {
+      myQuotes(options: $options) {
+        items { ...QuoteLegacy }
+        totalItems
+      }
+    }
+  `, QUOTE_LEGACY_FRAGMENT);
+export const MY_QUOTE = withFragments(
+/* GraphQL */ `
+    query MyQuote($id: ID!) {
+      myQuote(id: $id) { ...Quote }
+    }
+  `, QUOTE_FRAGMENT);
+export const MY_QUOTE_LEGACY = withFragments(
+/* GraphQL */ `
+    query MyQuoteLegacy($id: ID!) {
+      myQuote(id: $id) { ...QuoteLegacy }
+    }
+  `, QUOTE_LEGACY_FRAGMENT);
+export const CREATE_QUOTE_REQUEST = withFragments(
+/* GraphQL */ `
+    mutation CreateQuoteRequest($input: CreateQuoteRequestInput!) {
+      createQuoteRequest(input: $input) { ...Quote }
+    }
+  `, QUOTE_FRAGMENT);
+export const CREATE_QUOTE_REQUEST_LEGACY = withFragments(
+/* GraphQL */ `
+    mutation CreateQuoteRequestLegacy($input: CreateQuoteRequestInput!) {
+      createQuoteRequest(input: $input) { ...QuoteLegacy }
+    }
+  `, QUOTE_LEGACY_FRAGMENT);
+export const ACCEPT_QUOTE = withFragments(
+/* GraphQL */ `
+    mutation AcceptQuote($id: ID!) {
+      acceptQuote(id: $id) { ...Order }
+    }
+  `, ORDER_FRAGMENT);
+export const CANCEL_MY_QUOTE = withFragments(
+/* GraphQL */ `
+    mutation CancelMyQuote($id: ID!, $reason: String) {
+      cancelMyQuote(id: $id, reason: $reason) { ...Quote }
+    }
+  `, QUOTE_FRAGMENT);
+export const CANCEL_MY_QUOTE_LEGACY = withFragments(
+/* GraphQL */ `
+    mutation CancelMyQuoteLegacy($id: ID!, $reason: String) {
+      cancelMyQuote(id: $id, reason: $reason) { ...QuoteLegacy }
+    }
+  `, QUOTE_LEGACY_FRAGMENT);
 /**
  * Single-roundtrip branding query. activeChannel + fontResources (with
  * resolved file Assets) + brandingAssets for the channel-level logo, favicon,
  * and cover IDs already on ctx.channel.customFields.
  */
-export const GET_BRANDING = `
+export const GET_BRANDING = /* GraphQL */ `
   query GetBranding($ids: [ID!]!) {
     activeChannel {
       id
@@ -1369,7 +1884,7 @@ export const GET_BRANDING = `
   }
 `;
 // --- Order constraints (inline order-constraints plugin) ---
-export const ACTIVE_CHANNEL_ORDER_CONSTRAINTS = `
+export const ACTIVE_CHANNEL_ORDER_CONSTRAINTS = /* GraphQL */ `
   query ActiveChannelOrderConstraints {
     activeChannelOrderConstraints {
       minOrderAmountGross
@@ -1382,76 +1897,104 @@ export const ACTIVE_CHANNEL_ORDER_CONSTRAINTS = `
   }
 `;
 // --- Customer invoices (vendure-plugin-order-documents shop surface) ---
-export const MY_ORDER_INVOICES = `
+export const MY_ORDER_INVOICES = /* GraphQL */ `
   query MyOrderInvoices($orderCode: String!) {
     myOrderInvoices(orderCode: $orderCode) {
       id invoiceNumber invoicedOn totalWithTax currencyCode languageCode createdAt
     }
   }
 `;
-export const MY_INVOICE_PDF = `
+export const MY_INVOICE_PDF = /* GraphQL */ `
   query MyInvoicePdf($invoiceId: ID!) {
     myInvoicePdf(invoiceId: $invoiceId) {
       base64 filename invoiceNumber
     }
   }
 `;
-// --- Order returns (vendure-plugin-returns shop surface) ---
-/**
- * Shared selection set for customer-facing OrderReturn objects. The Shop API
- * never exposes the admin-only fields (`adminNote`, `history`) — do not add
- * them here. Money values are Int minor units.
- */
-const RETURN_FIELDS = `
-  id code state
-  orderId orderCode currencyCode
-  preferredSettlementMethod settlementMethod
-  shippingRefundAmount settledAmount
-  customerNote requestedAt resolvedAt createdAt
-  lines {
-    id orderLineId
-    productVariantId productVariantName productVariantSku
-    requestedQty approvedQty receivedQty restockQty writeOffQty
-    reasonCode reasonNote
-    unitPriceWithTax unitPriceWithTaxUnrounded refundAmount
+export const CREATE_INVOICE_DOWNLOAD_URL = /* GraphQL */ `
+  mutation CreateInvoiceDownloadUrl($invoiceId: ID!) {
+    createInvoiceDownloadUrl(invoiceId: $invoiceId) {
+      url expiresAt filename invoiceNumber
+    }
   }
 `;
-export const MY_RETURNS = `
-  query MyReturns($take: Int, $skip: Int) {
-    myReturns(options: { take: $take, skip: $skip }) {
-      items { ${RETURN_FIELDS} }
-      totalItems
+// --- Customer credit notes (vendure-plugin-order-documents shop surface) ---
+export const MY_ORDER_CREDIT_NOTES = /* GraphQL */ `
+  query MyOrderCreditNotes($orderCode: String!) {
+    myOrderCreditNotes(orderCode: $orderCode) {
+      id creditNoteNumber issuedOn totalWithTax currencyCode kind reason invoiceNumber createdAt
     }
   }
 `;
-export const MY_RETURN = `
-  query MyReturn($id: ID!) {
-    myReturn(id: $id) { ${RETURN_FIELDS} }
+export const CREATE_CREDIT_NOTE_DOWNLOAD_URL = /* GraphQL */ `
+  mutation CreateCreditNoteDownloadUrl($creditNoteId: ID!) {
+    createCreditNoteDownloadUrl(creditNoteId: $creditNoteId) {
+      url expiresAt filename creditNoteNumber
+    }
   }
 `;
-export const REQUEST_RETURN = `
-  mutation RequestReturn(
-    $orderId: ID!
-    $lines: [ReturnRequestLineInput!]!
-    $customerNote: String
-    $preferredSettlementMethod: OrderReturnSettlementMethod
-  ) {
-    requestReturn(
-      input: {
-        orderId: $orderId
-        lines: $lines
-        customerNote: $customerNote
-        preferredSettlementMethod: $preferredSettlementMethod
+// --- Order returns (vendure-plugin-returns shop surface) ---
+/**
+ * Shared selection set for customer-facing OrderReturn objects. The Shop API
+ * never exposes the admin-only fields (`adminNote`, `history`) — do not add
+ * them here. Money values are Int minor units.
+ */
+const CUSTOMER_RETURN_FRAGMENT = fragment(/* GraphQL */ `
+  fragment CustomerReturn on OrderReturn {
+    id code state
+    orderId orderCode currencyCode
+    preferredSettlementMethod settlementMethod
+    shippingRefundAmount settledAmount
+    customerNote requestedAt resolvedAt createdAt
+    lines {
+      id orderLineId
+      productVariantId productVariantName productVariantSku
+      requestedQty approvedQty receivedQty restockQty writeOffQty
+      reasonCode reasonNote
+      unitPriceWithTax unitPriceWithTaxUnrounded refundAmount
+    }
+  }
+`);
+export const MY_RETURNS = withFragments(
+/* GraphQL */ `
+    query MyReturns($take: Int, $skip: Int) {
+      myReturns(options: { take: $take, skip: $skip }) {
+        items { ...CustomerReturn }
+        totalItems
       }
-    ) { ${RETURN_FIELDS} }
-  }
-`;
-export const CANCEL_MY_RETURN = `
-  mutation CancelMyReturn($id: ID!) {
-    cancelMyReturn(id: $id) { ${RETURN_FIELDS} }
-  }
-`;
-export const RETURNABLE_LINES_FOR_ORDER = `
+    }
+  `, CUSTOMER_RETURN_FRAGMENT);
+export const MY_RETURN = withFragments(
+/* GraphQL */ `
+    query MyReturn($id: ID!) {
+      myReturn(id: $id) { ...CustomerReturn }
+    }
+  `, CUSTOMER_RETURN_FRAGMENT);
+export const REQUEST_RETURN = withFragments(
+/* GraphQL */ `
+    mutation RequestReturn(
+      $orderId: ID!
+      $lines: [ReturnRequestLineInput!]!
+      $customerNote: String
+      $preferredSettlementMethod: OrderReturnSettlementMethod
+    ) {
+      requestReturn(
+        input: {
+          orderId: $orderId
+          lines: $lines
+          customerNote: $customerNote
+          preferredSettlementMethod: $preferredSettlementMethod
+        }
+      ) { ...CustomerReturn }
+    }
+  `, CUSTOMER_RETURN_FRAGMENT);
+export const CANCEL_MY_RETURN = withFragments(
+/* GraphQL */ `
+    mutation CancelMyReturn($id: ID!) {
+      cancelMyReturn(id: $id) { ...CustomerReturn }
+    }
+  `, CUSTOMER_RETURN_FRAGMENT);
+export const RETURNABLE_LINES_FOR_ORDER = /* GraphQL */ `
   query ReturnableLinesForOrder($orderId: ID!) {
     returnableLinesForOrder(orderId: $orderId) {
       orderId eligible reason returnWindowEndsAt