@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/product/state.d.mts

@@ -1,107 +1,130 @@
 //#region src/core/product/state.d.ts
-/** Monetary amount in a specific currency, mirroring the Storefront API `MoneyV2` type. */
+/** An amount and its currency, matching the Storefront API `MoneyV2` type. */
 interface Money {
   amount: string;
   currencyCode: string;
 }
-/** Minimum and maximum variant prices for a product, mirroring the Storefront API `ProductPriceRange` type. */
+/** Lowest and highest variant prices for a product, matching the Storefront API product price range. */
 interface ProductPriceRange {
+  /** Lowest variant price. */
   minVariantPrice: Money;
-  /** Optional so queries that only select `minVariantPrice` still type-check. */
+  /** Highest variant price. Leave the field out of queries that need only the lowest price. */
   maxVariantPrice?: Money;
 }
-/** A single selected product option, e.g. `{ name: "Color", value: "Red" }`. */
+/** A single selected product option, such as `{ name: "Color", value: "Red" }`. */
 interface SelectedOption {
+  /** Option name, such as "Color". */
   name: string;
+  /** Value chosen for the option, such as "Red". */
   value: string;
 }
 /**
- * Minimum variant shape that the product form system requires.
+ * Variant fields that the product form needs from your Storefront API query.
  *
- * Consumers typically pass a wider type from their Storefront API query —
- * `ProductVariantInput` declares only the fields the form logic reads.
+ * Pass your full query type, which can include more fields.
  */
 interface ProductVariantInput {
+  /** Variant ID that the product form adds to the cart. */
   id: string;
+  /** Variant title. The cart shows the title on an added line before the server responds. */
   title: string;
+  /** Whether the customer can buy the variant. Option value availability falls back to this field when your query doesn't select the encoded variant availability. */
   availableForSale: boolean;
+  /** Option names and values that make up the variant. */
   selectedOptions: SelectedOption[];
+  /** Variant price. The cart shows the price on an added line before the server responds. */
   price: Money;
-  /** Merchant-set compare-at price, typically shown struck-through when higher than `price`. `null` when unset; `undefined` when not queried. */
+  /** Compare-at price, or `null` when the variant has none. */
   compareAtPrice?: Money | null;
+  /** Variant image. The cart shows the image on an added line before the server responds. */
   image?: unknown;
+  /** Handle and title of the variant's product. A handle that differs from the current product marks a variant of another product in a combined listing. */
   product?: {
     handle: string;
     title?: string | null;
   } | null;
+  /** Variant SKU. */
   sku?: string | null;
 }
-/** A product option (e.g. "Size" or "Color") and its available values. */
+/** A product option, such as "Size" or "Color", and its values. */
 interface ProductOptionInput<TVariant extends ProductVariantInput = ProductVariantInput> {
+  /** Option name, such as "Size" or "Color". */
   name: string;
+  /** Option values in the order that the Storefront API returns them. Keep that order, because the encoded variant fields refer to values by position. */
   optionValues: Array<ProductOptionValueInput<TVariant>>;
 }
-/** A single option value (e.g. "Small", "Red") within a {@link ProductOptionInput}. */
+/** A single option value, such as "Small" or "Red", within a product option. */
 interface ProductOptionValueInput<TVariant extends ProductVariantInput = ProductVariantInput> {
+  /** Option value name, such as "Small" or "Red". */
   name: string;
-  /** The variant combining this value with the lowest-position values of every other option (SFAPI). Strongly recommended: it seeds the variant cache used for `exists`/`selectedOptions` and combined-listing detection. */
+  /** Variant that combines this value with the lowest-position values of every other option. Include this field in your query. The store uses the variant to resolve option values and to find values that belong to other products in a combined listing. */
   firstSelectableVariant?: TVariant | null;
+  /** Swatch data from your query. The option value state returns the swatch unchanged. */
   swatch?: unknown;
 }
 /**
- * Minimum product shape that `createProductFormStore` requires.
+ * Product fields that the product form store needs from your Storefront API query.
  *
- * Fields mirror the Storefront API `Product` object. Consumers typically
- * pass a wider query result — this interface declares only what the
- * product form logic reads.
+ * The fields match the Storefront API product object. Pass your full query type, which can include more fields.
  */
 interface ProductInput<TVariant extends ProductVariantInput = ProductVariantInput> {
+  /** Product ID. The product provider reloads the product into the store when this ID or the selected variant's ID changes. */
   id: string;
+  /** Product title. */
   title: string;
+  /** Product handle for option value links. Variants with a different handle belong to other products in a combined listing. */
   handle: string;
+  /** Product vendor. */
   vendor?: string | null;
+  /** Lowest and highest variant prices. Show the range until the selection resolves to a variant. */
   priceRange?: ProductPriceRange;
-  /** When `true`, the product cannot be added to cart without a selling plan. */
+  /** When `true`, the customer can't add the product to the cart without a selling plan. */
   requiresSellingPlan?: boolean | null;
-  /** Encoded representation of which option-value combinations map to real variants. Consumers should treat this as opaque. */
+  /** Encoded list of the option value combinations that exist as variants. Pass the field unchanged from your query. */
   encodedVariantExistence?: string | null;
-  /** Encoded representation of which existing variants are currently available for sale. Consumers should treat this as opaque. */
+  /** Encoded list of the variants that are available for sale. Pass the field unchanged from your query. */
   encodedVariantAvailability?: string | null;
+  /** Product options and their values. The option state keeps this order. */
   options: ProductOptionInput<TVariant>[];
-  /** SFAPI `selectedOrFirstAvailableVariant`: the variant matching the query's `selectedOptions` argument, else the first available variant, else the first variant (which may be unavailable). */
+  /** The variant that matches the query's `selectedOptions` argument, or else the first available variant, or else the first variant, which can be unavailable. The store starts with this variant selected. */
   selectedOrFirstAvailableVariant: TVariant | null;
-  /** Variants adjacent to the selected variant — used to resolve option values without a full variant list. */
+  /** Variants that differ from the selected variant by one option value. The store resolves option values from these variants, and you don't need to query every variant. */
   adjacentVariants: TVariant[];
 }
-/** Extracts the concrete variant type from a {@link ProductInput} subtype. */
+/** Variant type from your product query type. */
 type ProductVariantFrom<TProduct extends ProductInput> = TProduct extends ProductInput<infer TVariant> ? TVariant : ProductVariantInput;
-/** Extracts the concrete option-value type from a {@link ProductInput} subtype. */
+/** Option value type from your product query type. */
 type ProductOptionValueFrom<TProduct extends ProductInput> = TProduct["options"][number]["optionValues"][number];
 /**
- * Computed state for a single option value (e.g. "Red" under "Color").
+ * State of one option value, such as "Red" under "Color", for the current selection.
  *
- * Derived each time the selection changes — fields reflect the current
- * selection context, not static product data.
+ * Render the value's control and link from this state.
  */
 interface VariantOptionValueState<TVariant extends ProductVariantInput = ProductVariantInput, TOptionValue extends ProductOptionValueInput = ProductOptionValueInput> {
+  /** Option value name, such as "Red". */
   name: string;
+  /** Swatch data from the option value in your query. */
   swatch?: TOptionValue["swatch"];
-  /** Whether this value is the current selection for its option. */
+  /** Whether the customer has selected the value. */
   selected: boolean;
-  /** Whether a variant exists for the target selection. Falls back to `true` when `encodedVariantExistence` wasn't queried. */
+  /** Whether a variant exists for the selection that the value targets. Defaults to `true` when your query doesn't select the encoded variant existence field. */
   exists: boolean;
-  /** Whether the target selection is available for sale. Uses `encodedVariantAvailability` when queried, otherwise the loaded variant's `availableForSale` (`false` if not loaded). */
+  /** Whether the variant for the targeted selection is available for sale. Without the encoded variant availability in your query, the value comes from the loaded variant, or reads `false` when your query didn't load that variant. */
   available: boolean;
-  /** The loaded variant for the target selection, or `null` if the selection is partial or that variant wasn't part of the query result. */
+  /** Variant for the targeted selection, or `null` when the selection is partial or your query didn't load that variant. */
   variant: TVariant | null;
-  /** The selection this value targets. Use for link building; `selectOption()` is the source of truth for the resulting selection. */
+  /** Selection that the value targets. Build the option link from this selection. Selecting the value can produce a different selection. */
   selectedOptions: SelectedOption[];
-  /** Product handle, useful for building navigation links to combined-listing child products. */
+  /** Product handle for the option link. A value from another product in a combined listing uses that product's handle. Selected values use the current product's handle. */
   handle: string;
 }
-/** Computed state for a product option (e.g. "Color"), grouping its {@link VariantOptionValueState} entries. */
+/**
+ * State of one product option, such as "Color", and its values.
+ */
 interface VariantOptionState<TVariant extends ProductVariantInput = ProductVariantInput, TOptionValue extends ProductOptionValueInput = ProductOptionValueInput> {
+  /** Option name, such as "Color". */
   name: string;
+  /** State of each value, in the product's value order. */
   values: VariantOptionValueState<TVariant, TOptionValue>[];
 }
 //#endregion

package/dist/core/product/url.d.mts

@@ -2,25 +2,24 @@ import { SelectedOption } from "./state.mjs";
 
 //#region src/core/product/url.d.ts
 /**
- * Controls how variant selection is encoded in URL search params.
+ * How a product URL encodes the customer's variant selection.
  *
- * - `"options"` — one param per option, e.g. `?Color=Red&Size=M`.
- * - `"variant"` — a single `?variant=<numeric id>` param (Liquid parity).
+ * - `options`: one param per option, such as `?Color=Red&Size=M`.
+ * - `variant`: a single `?variant=<numeric id>` param that matches Liquid storefront URLs.
  */
 type ProductSelectionLinkStyle = "options" | "variant";
 /**
- * Builds the search params for a product-page link representing a variant selection.
+ * Builds the search params for a product URL that holds the customer's variant selection.
  *
- * Existing `base` params are preserved (`?ref=campaign` survives navigation), except the
- * reserved `variant` param and every param named in `optionNames` or `selectedOptions`,
- * which are always removed before the new selection is written. This keeps stale selection
- * state from leaking between navigations, including across combined-listing products.
+ * The function keeps unrelated params from the base params, such as `?ref=campaign`, and replaces any earlier selection. Pass the current product's option names to clear the current product's params when you link to another product in a combined listing.
  *
- * Two link styles:
- * - `"options"` (default): one param per selected option, e.g. `?Color=Red&Size=M`.
- * - `"variant"`: a single `?variant=<numeric id>` param (Liquid parity), for shareable
- *   links. Falls back to option params when `variant` is absent — a partial selection has
- *   no matching variant, so a variant link is not constructible.
+ * The default options style writes one param per option. The variant style writes a single numeric variant ID param for shareable links.
+ * The variant style falls back to option params when you pass no variant or when the variant ID isn't a numeric product variant GID.
+ * The `handleShopifyRoutes` handler redirects variant links to option param URLs.
+ *
+ * @param input The selected options, the current product's option names, and an optional variant, link style, and base params.
+ *
+ * @returns New search params that hold the kept base params and the selection.
  *
  * @example
  * ```ts
@@ -32,6 +31,7 @@ type ProductSelectionLinkStyle = "options" | "variant";
  * });
  * const url = `/products/${handle}${searchParams.size ? `?${searchParams}` : ""}`;
  * ```
+ * @publicDocs
  */
 declare function buildProductSelectionSearchParams({
   style,
@@ -40,11 +40,17 @@ declare function buildProductSelectionSearchParams({
   optionNames,
   base
 }: {
+  /**
+   * Link style for the selection. Defaults to `"options"`.
+   */
   style?: ProductSelectionLinkStyle;
   selectedOptions: readonly SelectedOption[];
   variant?: {
     id: string;
   } | null;
+  /**
+   * Option names of the current product. The function clears the param for each name.
+   */
   optionNames: readonly string[];
   base?: URLSearchParams;
 }): URLSearchParams;

package/dist/core/product/url.mjs

@@ -26,18 +26,17 @@ function getVariantSearchParamValue(variantId) {
 	return /^\d+$/.test(numericId) ? numericId : null;
 }
 /**
-* Builds the search params for a product-page link representing a variant selection.
+* Builds the search params for a product URL that holds the customer's variant selection.
 *
-* Existing `base` params are preserved (`?ref=campaign` survives navigation), except the
-* reserved `variant` param and every param named in `optionNames` or `selectedOptions`,
-* which are always removed before the new selection is written. This keeps stale selection
-* state from leaking between navigations, including across combined-listing products.
+* The function keeps unrelated params from the base params, such as `?ref=campaign`, and replaces any earlier selection. Pass the current product's option names to clear the current product's params when you link to another product in a combined listing.
 *
-* Two link styles:
-* - `"options"` (default): one param per selected option, e.g. `?Color=Red&Size=M`.
-* - `"variant"`: a single `?variant=<numeric id>` param (Liquid parity), for shareable
-*   links. Falls back to option params when `variant` is absent — a partial selection has
-*   no matching variant, so a variant link is not constructible.
+* The default options style writes one param per option. The variant style writes a single numeric variant ID param for shareable links.
+* The variant style falls back to option params when you pass no variant or when the variant ID isn't a numeric product variant GID.
+* The `handleShopifyRoutes` handler redirects variant links to option param URLs.
+*
+* @param input The selected options, the current product's option names, and an optional variant, link style, and base params.
+*
+* @returns New search params that hold the kept base params and the selection.
 *
 * @example
 * ```ts
@@ -49,6 +48,7 @@ function getVariantSearchParamValue(variantId) {
 * });
 * const url = `/products/${handle}${searchParams.size ? `?${searchParams}` : ""}`;
 * ```
+* @publicDocs
 */
 function buildProductSelectionSearchParams({ style = "options", selectedOptions, variant, optionNames, base }) {
 	const searchParams = new URLSearchParams(base);

package/dist/core/product/url.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"url.mjs","names":[],"sources":["../../../src/core/product/url.ts"],"sourcesContent":["import type { SelectedOption } from \"./state\";\n\nconst VARIANT_GID_PREFIX = \"gid://shopify/ProductVariant/\";\n\n/**\n * Reserved product-page search param carrying a numeric variant id (`?variant=41820371452004`),\n * matching Liquid storefront URLs. Never treated as a product option name.\n */\nexport const VARIANT_SEARCH_PARAM = \"variant\";\n\n/**\n * Converts a `?variant=` search param value into a variant id (gid).\n *\n * Anything that is not a plain positive integer of a plausible length is treated as absent\n * (`null`) so malformed links degrade to the default variant instead of producing invalid\n * API lookups or log spam.\n */\nexport function parseVariantSearchParam(value: string | null): string | null {\n  if (!value || !/^\\d{1,30}$/.test(value)) return null;\n  return `${VARIANT_GID_PREFIX}${value}`;\n}\n\n/**\n * Extracts the numeric `?variant=` search param value from a variant id (gid).\n * Returns `null` for ids that are not canonical `gid://shopify/ProductVariant/<numeric>` ids.\n */\nexport function getVariantSearchParamValue(variantId: string): string | null {\n  if (!variantId.startsWith(VARIANT_GID_PREFIX)) return null;\n\n  const numericId = variantId.slice(VARIANT_GID_PREFIX.length);\n  return /^\\d+$/.test(numericId) ? numericId : null;\n}\n\n/**\n * Controls how variant selection is encoded in URL search params.\n *\n * - `\"options\"` — one param per option, e.g. `?Color=Red&Size=M`.\n * - `\"variant\"` — a single `?variant=<numeric id>` param (Liquid parity).\n */\nexport type ProductSelectionLinkStyle = \"options\" | \"variant\";\n\n/**\n * Builds the search params for a product-page link representing a variant selection.\n *\n * Existing `base` params are preserved (`?ref=campaign` survives navigation), except the\n * reserved `variant` param and every param named in `optionNames` or `selectedOptions`,\n * which are always removed before the new selection is written. This keeps stale selection\n * state from leaking between navigations, including across combined-listing products.\n *\n * Two link styles:\n * - `\"options\"` (default): one param per selected option, e.g. `?Color=Red&Size=M`.\n * - `\"variant\"`: a single `?variant=<numeric id>` param (Liquid parity), for shareable\n *   links. Falls back to option params when `variant` is absent — a partial selection has\n *   no matching variant, so a variant link is not constructible.\n *\n * @example\n * ```ts\n * const searchParams = buildProductSelectionSearchParams({\n *   selectedOptions: result.selectedOptions,\n *   variant: result.selectedVariant,\n *   optionNames: product.options.map((option) => option.name),\n *   base: new URLSearchParams(location.search),\n * });\n * const url = `/products/${handle}${searchParams.size ? `?${searchParams}` : \"\"}`;\n * ```\n */\nexport function buildProductSelectionSearchParams({\n  style = \"options\",\n  selectedOptions,\n  variant,\n  optionNames,\n  base,\n}: {\n  style?: ProductSelectionLinkStyle;\n  selectedOptions: readonly SelectedOption[];\n  variant?: { id: string } | null;\n  optionNames: readonly string[];\n  base?: URLSearchParams;\n}): URLSearchParams {\n  const searchParams = new URLSearchParams(base);\n\n  searchParams.delete(VARIANT_SEARCH_PARAM);\n  for (const name of optionNames) searchParams.delete(name);\n  for (const option of selectedOptions) searchParams.delete(option.name);\n\n  const variantSearchParamValue =\n    style === \"variant\" && variant ? getVariantSearchParamValue(variant.id) : null;\n\n  if (variantSearchParamValue) {\n    searchParams.set(VARIANT_SEARCH_PARAM, variantSearchParamValue);\n    return searchParams;\n  }\n\n  for (const option of selectedOptions) {\n    searchParams.set(option.name, option.value);\n  }\n\n  return searchParams;\n}\n"],"mappings":";AAEA,MAAM,qBAAqB;;;;;AAM3B,MAAa,uBAAuB;;;;;;;;AASpC,SAAgB,wBAAwB,OAAqC;AAC3E,KAAI,CAAC,SAAS,CAAC,aAAa,KAAK,MAAM,CAAE,QAAO;AAChD,QAAO,GAAG,qBAAqB;;;;;;AAOjC,SAAgB,2BAA2B,WAAkC;AAC3E,KAAI,CAAC,UAAU,WAAW,mBAAmB,CAAE,QAAO;CAEtD,MAAM,YAAY,UAAU,MAAM,GAA0B;AAC5D,QAAO,QAAQ,KAAK,UAAU,GAAG,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC/C,SAAgB,kCAAkC,EAChD,QAAQ,WACR,iBACA,SACA,aACA,QAOkB;CAClB,MAAM,eAAe,IAAI,gBAAgB,KAAK;AAE9C,cAAa,OAAO,qBAAqB;AACzC,MAAK,MAAM,QAAQ,YAAa,cAAa,OAAO,KAAK;AACzD,MAAK,MAAM,UAAU,gBAAiB,cAAa,OAAO,OAAO,KAAK;CAEtE,MAAM,0BACJ,UAAU,aAAa,UAAU,2BAA2B,QAAQ,GAAG,GAAG;AAE5E,KAAI,yBAAyB;AAC3B,eAAa,IAAI,sBAAsB,wBAAwB;AAC/D,SAAO;;AAGT,MAAK,MAAM,UAAU,gBACnB,cAAa,IAAI,OAAO,MAAM,OAAO,MAAM;AAG7C,QAAO"}
+{"version":3,"file":"url.mjs","names":[],"sources":["../../../src/core/product/url.ts"],"sourcesContent":["import type { SelectedOption } from \"./state\";\n\nconst VARIANT_GID_PREFIX = \"gid://shopify/ProductVariant/\";\n\n/**\n * Reserved product-page search param carrying a numeric variant id (`?variant=41820371452004`),\n * matching Liquid storefront URLs. Never treated as a product option name.\n */\nexport const VARIANT_SEARCH_PARAM = \"variant\";\n\n/**\n * Converts a `?variant=` search param value into a variant id (gid).\n *\n * Anything that is not a plain positive integer of a plausible length is treated as absent\n * (`null`) so malformed links degrade to the default variant instead of producing invalid\n * API lookups or log spam.\n */\nexport function parseVariantSearchParam(value: string | null): string | null {\n  if (!value || !/^\\d{1,30}$/.test(value)) return null;\n  return `${VARIANT_GID_PREFIX}${value}`;\n}\n\n/**\n * Extracts the numeric `?variant=` search param value from a variant id (gid).\n * Returns `null` for ids that are not canonical `gid://shopify/ProductVariant/<numeric>` ids.\n */\nexport function getVariantSearchParamValue(variantId: string): string | null {\n  if (!variantId.startsWith(VARIANT_GID_PREFIX)) return null;\n\n  const numericId = variantId.slice(VARIANT_GID_PREFIX.length);\n  return /^\\d+$/.test(numericId) ? numericId : null;\n}\n\n/**\n * How a product URL encodes the customer's variant selection.\n *\n * - `options`: one param per option, such as `?Color=Red&Size=M`.\n * - `variant`: a single `?variant=<numeric id>` param that matches Liquid storefront URLs.\n */\nexport type ProductSelectionLinkStyle = \"options\" | \"variant\";\n\n/**\n * Builds the search params for a product URL that holds the customer's variant selection.\n *\n * The function keeps unrelated params from the base params, such as `?ref=campaign`, and replaces any earlier selection. Pass the current product's option names to clear the current product's params when you link to another product in a combined listing.\n *\n * The default options style writes one param per option. The variant style writes a single numeric variant ID param for shareable links.\n * The variant style falls back to option params when you pass no variant or when the variant ID isn't a numeric product variant GID.\n * The `handleShopifyRoutes` handler redirects variant links to option param URLs.\n *\n * @param input The selected options, the current product's option names, and an optional variant, link style, and base params.\n *\n * @returns New search params that hold the kept base params and the selection.\n *\n * @example\n * ```ts\n * const searchParams = buildProductSelectionSearchParams({\n *   selectedOptions: result.selectedOptions,\n *   variant: result.selectedVariant,\n *   optionNames: product.options.map((option) => option.name),\n *   base: new URLSearchParams(location.search),\n * });\n * const url = `/products/${handle}${searchParams.size ? `?${searchParams}` : \"\"}`;\n * ```\n * @publicDocs\n */\nexport function buildProductSelectionSearchParams({\n  style = \"options\",\n  selectedOptions,\n  variant,\n  optionNames,\n  base,\n}: {\n  /**\n   * Link style for the selection. Defaults to `\"options\"`.\n   */\n  style?: ProductSelectionLinkStyle;\n  selectedOptions: readonly SelectedOption[];\n  variant?: { id: string } | null;\n  /**\n   * Option names of the current product. The function clears the param for each name.\n   */\n  optionNames: readonly string[];\n  base?: URLSearchParams;\n}): URLSearchParams {\n  const searchParams = new URLSearchParams(base);\n\n  searchParams.delete(VARIANT_SEARCH_PARAM);\n  for (const name of optionNames) searchParams.delete(name);\n  for (const option of selectedOptions) searchParams.delete(option.name);\n\n  const variantSearchParamValue =\n    style === \"variant\" && variant ? getVariantSearchParamValue(variant.id) : null;\n\n  if (variantSearchParamValue) {\n    searchParams.set(VARIANT_SEARCH_PARAM, variantSearchParamValue);\n    return searchParams;\n  }\n\n  for (const option of selectedOptions) {\n    searchParams.set(option.name, option.value);\n  }\n\n  return searchParams;\n}\n"],"mappings":";AAEA,MAAM,qBAAqB;;;;;AAM3B,MAAa,uBAAuB;;;;;;;;AASpC,SAAgB,wBAAwB,OAAqC;AAC3E,KAAI,CAAC,SAAS,CAAC,aAAa,KAAK,MAAM,CAAE,QAAO;AAChD,QAAO,GAAG,qBAAqB;;;;;;AAOjC,SAAgB,2BAA2B,WAAkC;AAC3E,KAAI,CAAC,UAAU,WAAW,mBAAmB,CAAE,QAAO;CAEtD,MAAM,YAAY,UAAU,MAAM,GAA0B;AAC5D,QAAO,QAAQ,KAAK,UAAU,GAAG,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoC/C,SAAgB,kCAAkC,EAChD,QAAQ,WACR,iBACA,SACA,aACA,QAakB;CAClB,MAAM,eAAe,IAAI,gBAAgB,KAAK;AAE9C,cAAa,OAAO,qBAAqB;AACzC,MAAK,MAAM,QAAQ,YAAa,cAAa,OAAO,KAAK;AACzD,MAAK,MAAM,UAAU,gBAAiB,cAAa,OAAO,OAAO,KAAK;CAEtE,MAAM,0BACJ,UAAU,aAAa,UAAU,2BAA2B,QAAQ,GAAG,GAAG;AAE5E,KAAI,yBAAyB;AAC3B,eAAa,IAAI,sBAAsB,wBAAwB;AAC/D,SAAO;;AAGT,MAAK,MAAM,UAAU,gBACnB,cAAa,IAAI,OAAO,MAAM,OAAO,MAAM;AAG7C,QAAO"}

package/dist/core/request-context.d.mts

@@ -2,19 +2,31 @@ import { CountryCode, LanguageCode } from "../graphql/generated/customer-account
 import { CountryCode as CountryCode$1, LanguageCode as LanguageCode$1 } from "../graphql/generated/storefront-api-types.mjs";
 
 //#region src/core/request-context.d.ts
+/** The incoming request's headers, plus its method, abort signal, and URL when the framework provides them. */
 type StorefrontRequest = Pick<Request, "headers"> & Partial<Pick<Request, "method" | "signal" | "url">>;
+/** A language code that both the Storefront API and the Customer Account API accept. */
 type ShopifyLanguageCode = Extract<LanguageCode$1, LanguageCode>;
+/** A country code that both the Storefront API and the Customer Account API accept. */
 type ShopifyCountryCode = Extract<CountryCode$1, CountryCode>;
+/** The language, country, and optional localized path prefix for a request. */
 type I18nConfig = {
-  language: ShopifyLanguageCode;
-  country: ShopifyCountryCode; /** Optional app route prefix for localized paths, for example "/es-es". */
+  /** The request's language. */language: ShopifyLanguageCode; /** The request's country. */
+  country: ShopifyCountryCode;
+  /**
+   * The URL prefix for localized routes, such as `/es-es`. Hydrogen adds the prefix to standard route redirects and product variant URLs.
+   */
   pathPrefix?: string;
 };
+/** The request's locale, with a path prefix that starts with `/` or is an empty string. */
 type NormalizedI18nConfig<I18n extends I18nConfig = I18nConfig> = Omit<I18n, "pathPrefix"> & {
   pathPrefix: string;
 };
+/** The incoming request and its locale. */
 type ShopifyRequestContextInputBase<I18n extends I18nConfig = I18nConfig> = {
-  request: StorefrontRequest;
+  /**
+   * The incoming request from your framework. When the framework exposes no request, such as during prerendering, pass `{ headers: new Headers() }`.
+   */
+  request: StorefrontRequest; /** The request's language, country, and optional localized path prefix. */
   i18n: I18n;
 };
 type ShopifyRequestContextInput<I18n extends I18nConfig = I18nConfig> = ShopifyRequestContextInputBase<I18n> & {
@@ -23,54 +35,100 @@ type ShopifyRequestContextInput<I18n extends I18nConfig = I18nConfig> = ShopifyR
 type ShopifyRequestContextWithBuyerIpInput<I18n extends I18nConfig = I18nConfig> = ShopifyRequestContextInputBase<I18n> & {
   buyerIp: string;
 };
+/** The fields and methods on every request context. */
 type ShopifyRequestContextBase = {
   /**
-   * Compile-time brand so callers use createShopifyRequestContext().
+   * A type-only marker. Create request contexts only with `createShopifyRequestContext`.
+   * @internal
+   */
+  readonly __hydrogenShopifyRequestContextBrand: never;
+  /**
+   * The incoming request's `Cookie` header. Hydrogen forwards the header to the Storefront API.
+   * @internal
+   */
+  cookie?: string;
+  /**
+   * The customer's trusted IP address. Private Storefront API clients require it.
+   * @internal
+   */
+  readonly buyerIp?: string;
+  /**
+   * The ID that groups this request's Shopify API calls. Hydrogen reads the ID from the request headers or generates one.
+   * @internal
+   */
+  requestGroupId: string;
+  /**
+   * The incoming request's abort signal. Hydrogen's API clients stop their requests when the signal aborts.
+   * @internal
+   */
+  signal?: AbortSignal;
+  /**
+   * The incoming request's URL.
+   * @internal
+   */
+  url?: string;
+  /**
+   * The origin of the incoming request's URL. Hydrogen forwards the origin to the Storefront API.
    * @internal
    */
-  readonly __hydrogenShopifyRequestContextBrand: never; /** @internal */
-  cookie?: string; /** @internal */
-  readonly buyerIp?: string; /** @internal */
-  requestGroupId: string; /** @internal */
-  signal?: AbortSignal; /** @internal */
-  url?: string; /** @internal */
   storefrontOrigin?: string;
   /**
-   * Apply request-scoped headers required by every Shopify storefront subrequest.
+   * Adds the Hydrogen SDK headers and the customer's cookie, privacy, and origin headers to a
+   * Storefront API request. The Storefront API client and the API proxies call the method for you.
    * @internal
    */
   applyStorefrontRequestHeaders(headers: Headers): void;
   /**
-   * Capture cookies from the first fresh storefront response that sets them for replay.
+   * Saves the cookies from the first Storefront API response that sets cookies. The Storefront API
+   * client calls the method for you, and `applyResponseHeaders()` can add the cookies to your response.
    * @internal
    */
   captureSubrequestHeaders(headers: Headers): void;
   /**
-   * Consume storefront proxy cookies for gated replay onto the final app response.
+   * Saves the cookies from a proxied Storefront API response and removes the `set-cookie` header
+   * from that response. The API proxies in `handleShopifyRoutes` call the method for you.
    * @internal
    */
   consumeStorefrontResponseHeaders(headers: Headers): void;
   /**
-   * Mark the final app response as influenced by private customer state.
+   * Marks the final response as private and uncacheable because the response holds customer data.
+   * The Customer Account API client and the customer session call the method for you.
    * @internal
    */
   markResponseAsPersonalized(reason: string): void;
   /**
-   * Mark this request as a sanctioned session-establishing endpoint (like the
-   * consent flow), permitting Shopify state to return even on a cold session.
+   * Lets the final response set Shopify cookies before the customer has a Shopify session, and
+   * marks the response as private and uncacheable. The UCP MCP proxy calls the method for you.
    * @internal
    */
-  markResponseAsSessionEstablishing(reason: string): void;
-  i18n: NormalizedI18nConfig; /** Return incoming request headers plus request lifecycle headers for proxy/origin handoff. */
-  getForwardedRequestHeaders(): Headers; /** Apply important response headers for the correct functioning of Hydrogen storefronts. */
+  markResponseAsSessionEstablishing(reason: string): void; /** The request's language, country, and path prefix. The path prefix starts with `/` and has no trailing slash, or is an empty string when you don't set one. */
+  i18n: NormalizedI18nConfig; /** Returns the incoming request's headers with Shopify's request headers added. Pass the headers when you forward the request to a proxy or another origin. */
+  getForwardedRequestHeaders(): Headers;
+  /**
+   * Adds the headers that a Hydrogen storefront needs to the final response. Call the method on each response that your app builds. Responses from `handleShopifyRoutes` and `handleShopifyRedirects` already carry these headers.
+   *
+   * Append your committed session headers before you call the method. The method makes any response that sets a cookie private and uncacheable. The method also sets the `powered-by` header, makes responses that hold customer data private and uncacheable, and adds eligible Shopify cookies only to non-document responses for methods other than `GET` and `HEAD`.
+   */
   applyResponseHeaders(headers: Headers): void;
 };
+/** The context for one request. Pass the context to Hydrogen's API clients and route handlers for that request. */
 type ShopifyRequestContext<I18n extends I18nConfig = I18nConfig> = ShopifyRequestContextBase & {
   i18n: NormalizedI18nConfig<I18n>;
 };
+/** A request context that includes the customer's IP address. Private Storefront API clients require this context. */
 type ShopifyRequestContextWithBuyerIp<I18n extends I18nConfig = I18nConfig> = ShopifyRequestContext<I18n> & {
   readonly buyerIp: string;
 };
+/**
+ * Creates the context for one incoming request. Pass the same context to the Storefront API
+ * client, the Customer Account API client, and `handleShopifyRoutes`. The context forwards the
+ * customer's cookies, locale, and privacy signal to Shopify, and adds Shopify's cookies and cache
+ * headers to your response.
+ *
+ * Call `applyResponseHeaders()` on each response that your app builds. Pass `buyerIp` with the customer's trusted IP address when you use a private Storefront API client. The function throws when `i18n` lacks a country or language, and when `buyerIp` is an empty string.
+ *
+ * @publicDocs
+ */
 declare function createShopifyRequestContext<const I18n extends I18nConfig>(input: ShopifyRequestContextWithBuyerIpInput<I18n>): ShopifyRequestContextWithBuyerIp<I18n>;
 declare function createShopifyRequestContext<const I18n extends I18nConfig>(input: ShopifyRequestContextInput<I18n>): ShopifyRequestContext<I18n>;
 //#endregion

package/dist/core/request-context.mjs

@@ -4,6 +4,10 @@ import { CONSENT_MANAGEMENT_HEADER, HYDROGEN_VERSION_HEADER, REQUEST_GROUP_ID_HE
 
 //#region src/core/request-context.ts
 const SHOPIFY_ESSENTIAL_COOKIE = "_shopify_essential";
+/**
+* @param input The incoming request, its locale, and the customer's IP address for private Storefront API clients.
+* @returns The context to pass to Hydrogen's API clients and route handlers for this request.
+*/
 function createShopifyRequestContext(input) {
 	const { request } = input;
 	if (!input.i18n?.country || !input.i18n?.language) throw new Error("i18n with country and language is required for Shopify request contexts.");
@@ -80,7 +84,7 @@ function applyStorefrontRequestHeaders(context, headers) {
 	headers.set(SDK_VARIANT_HEADER, "hydrogen");
 	headers.set(SDK_VARIANT_SOURCE_HEADER, "kit");
 	headers.set(SDK_VERSION_HEADER, STOREFRONT_API_VERSION);
-	headers.set(HYDROGEN_VERSION_HEADER, "2026.10.0-preview.4");
+	headers.set(HYDROGEN_VERSION_HEADER, "2026.10.0");
 	headers.set(REQUEST_GROUP_ID_HEADER, context.requestGroupId);
 	if (context.cookie) headers.set("cookie", context.cookie);
 	else headers.delete("cookie");

package/dist/core/request-context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.mjs","names":[],"sources":["../../src/core/request-context.ts"],"sourcesContent":["import type {\n  CountryCode as CustomerAccountCountryCode,\n  LanguageCode as CustomerAccountLanguageCode,\n} from \"../graphql/generated/customer-account-api-types\";\nimport type {\n  CountryCode as StorefrontCountryCode,\n  LanguageCode as StorefrontLanguageCode,\n} from \"../graphql/generated/storefront-api-types\";\nimport { STOREFRONT_API_VERSION } from \"./constants\";\nimport {\n  applyPrivateResponseCacheHeaders,\n  CONSENT_MANAGEMENT_HEADER,\n  HYDROGEN_VERSION_HEADER,\n  REQUEST_GROUP_ID_HEADER,\n  SDK_VARIANT_HEADER,\n  SDK_VARIANT_SOURCE_HEADER,\n  SDK_VERSION_HEADER,\n  SEC_GPC_HEADER,\n  SHOPIFY_STOREFRONT_ORIGIN_HEADER,\n  STOREFRONT_URL_HEADER,\n} from \"./headers\";\nimport { normalizePathPrefix } from \"./standard-routes/path\";\n\nconst SHOPIFY_ESSENTIAL_COOKIE = \"_shopify_essential\";\n\ntype StorefrontRequest = Pick<Request, \"headers\"> &\n  Partial<Pick<Request, \"method\" | \"signal\" | \"url\">>;\n\nexport type ShopifyLanguageCode = Extract<StorefrontLanguageCode, CustomerAccountLanguageCode>;\nexport type ShopifyCountryCode = Extract<StorefrontCountryCode, CustomerAccountCountryCode>;\n\nexport type I18nConfig = {\n  language: ShopifyLanguageCode;\n  country: ShopifyCountryCode;\n  /** Optional app route prefix for localized paths, for example \"/es-es\". */\n  pathPrefix?: string;\n};\n\ntype NormalizedI18nConfig<I18n extends I18nConfig = I18nConfig> = Omit<I18n, \"pathPrefix\"> & {\n  pathPrefix: string;\n};\n\ntype ShopifyRequestContextInputBase<I18n extends I18nConfig = I18nConfig> = {\n  request: StorefrontRequest;\n  i18n: I18n;\n};\n\ntype ShopifyRequestContextInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp?: never };\n\ntype ShopifyRequestContextWithBuyerIpInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp: string };\n\ntype ShopifyRequestContextBase = {\n  // -- Private fields --\n  /**\n   * Compile-time brand so callers use createShopifyRequestContext().\n   * @internal\n   */\n  readonly __hydrogenShopifyRequestContextBrand: never;\n  /** @internal */\n  cookie?: string;\n  /** @internal */\n  readonly buyerIp?: string;\n  /** @internal */\n  requestGroupId: string;\n  /** @internal */\n  signal?: AbortSignal;\n  /** @internal */\n  url?: string;\n  /** @internal */\n  storefrontOrigin?: string;\n  /**\n   * Apply request-scoped headers required by every Shopify storefront subrequest.\n   * @internal\n   */\n  applyStorefrontRequestHeaders(headers: Headers): void;\n  /**\n   * Capture cookies from the first fresh storefront response that sets them for replay.\n   * @internal\n   */\n  captureSubrequestHeaders(headers: Headers): void;\n  /**\n   * Consume storefront proxy cookies for gated replay onto the final app response.\n   * @internal\n   */\n  consumeStorefrontResponseHeaders(headers: Headers): void;\n  /**\n   * Mark the final app response as influenced by private customer state.\n   * @internal\n   */\n  markResponseAsPersonalized(reason: string): void;\n  /**\n   * Mark this request as a sanctioned session-establishing endpoint (like the\n   * consent flow), permitting Shopify state to return even on a cold session.\n   * @internal\n   */\n  markResponseAsSessionEstablishing(reason: string): void;\n\n  // -- Public fields --\n  i18n: NormalizedI18nConfig;\n  /** Return incoming request headers plus request lifecycle headers for proxy/origin handoff. */\n  getForwardedRequestHeaders(): Headers;\n  /** Apply important response headers for the correct functioning of Hydrogen storefronts. */\n  applyResponseHeaders(headers: Headers): void;\n};\n\nexport type ShopifyRequestContext<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextBase & {\n    i18n: NormalizedI18nConfig<I18n>;\n  };\n\nexport type ShopifyRequestContextWithBuyerIp<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContext<I18n> & { readonly buyerIp: string };\n\ntype Context<I18n extends I18nConfig = I18nConfig> = {\n  cookie?: string;\n  globalPrivacyControl?: string;\n  buyerIp?: string;\n  requestGroupId: string;\n  signal?: AbortSignal;\n  url?: string;\n  storefrontOrigin?: string;\n  i18n: NormalizedI18nConfig<I18n>;\n  documentRequest?: boolean;\n};\n\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextWithBuyerIpInput<I18n>,\n): ShopifyRequestContextWithBuyerIp<I18n>;\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInput<I18n>,\n): ShopifyRequestContext<I18n>;\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInputBase<I18n> & { buyerIp?: string },\n): ShopifyRequestContext<I18n> {\n  const { request } = input;\n\n  if (!input.i18n?.country || !input.i18n?.language) {\n    throw new Error(\"i18n with country and language is required for Shopify request contexts.\");\n  }\n\n  if (input.buyerIp !== undefined && !input.buyerIp) {\n    throw new Error(\"buyerIp must be non-empty when provided\");\n  }\n\n  const requestMethod = request.method?.toUpperCase();\n  const i18n = normalizeI18n(input.i18n);\n  const cookieHeader = request.headers.get(\"cookie\") || undefined;\n  const inboundCookies = parseCookieHeader(cookieHeader);\n  const hasEssentialCookie = inboundCookies.has(SHOPIFY_ESSENTIAL_COOKIE);\n  const isConsentManagementRequest = request.headers.get(CONSENT_MANAGEMENT_HEADER) === \"1\";\n  const url = request.url ?? request.headers.get(STOREFRONT_URL_HEADER) ?? undefined;\n  const storefrontOrigin = getUrlOrigin(url);\n  const context = {\n    ...(cookieHeader && { cookie: cookieHeader }),\n    globalPrivacyControl: request.headers.get(SEC_GPC_HEADER) ?? undefined,\n    i18n,\n    ...(url && { url }),\n    ...(storefrontOrigin && { storefrontOrigin }),\n    ...(input.buyerIp && { buyerIp: input.buyerIp }),\n    requestGroupId:\n      request.headers.get(REQUEST_GROUP_ID_HEADER) ??\n      request.headers.get(\"x-request-id\") ??\n      request.headers.get(\"request-id\") ??\n      crypto.randomUUID(),\n    ...(isDocumentRequest(request) && { documentRequest: true }),\n    ...(request.signal && { signal: request.signal }),\n  } as Context<I18n>;\n\n  let capturedCookies: string[] | undefined;\n  let personalizedResponseReason: string | undefined;\n  let sessionEstablishingReason: string | undefined;\n\n  const captureSubrequestHeaders = (headers: Headers): void => {\n    // Capture the first fresh response cookies to increase the\n    // chance of returning them from the main server response. The main response\n    // needs headers set at send time, while the body can stream later, so this\n    // may not be used if subrequests finish after the main response is sent.\n    const cookies = headers.getSetCookie();\n    if (cookies.length > 0) capturedCookies ??= cookies;\n  };\n\n  return {\n    ...context,\n    getForwardedRequestHeaders() {\n      const headers = new Headers(request.headers);\n      applyStorefrontRequestHeaders(context, headers);\n      if (context.url) headers.set(STOREFRONT_URL_HEADER, context.url);\n      return headers;\n    },\n    applyStorefrontRequestHeaders(headers) {\n      applyStorefrontRequestHeaders(context, headers);\n    },\n    captureSubrequestHeaders,\n    consumeStorefrontResponseHeaders(headers) {\n      captureSubrequestHeaders(headers);\n      headers.delete(\"set-cookie\");\n    },\n    markResponseAsPersonalized(reason) {\n      personalizedResponseReason ??= reason;\n    },\n    markResponseAsSessionEstablishing(reason) {\n      sessionEstablishingReason ??= reason;\n    },\n    applyResponseHeaders(headers) {\n      headers.set(\"powered-by\", \"Shopify, Hydrogen\");\n\n      // Documents may be shared or streamed, so they must not carry buyer-specific state.\n      const isDocumentResponse =\n        context.documentRequest || (headers.get(\"content-type\")?.startsWith(\"text/html\") ?? false);\n\n      // Keep GET and HEAD responses cacheable, and fail closed when the request method is unknown.\n      // Cold sessions may only be established by the explicitly marked consent request.\n      const mayReturnShopifyState =\n        requestMethod !== undefined &&\n        requestMethod !== \"GET\" &&\n        requestMethod !== \"HEAD\" &&\n        !isDocumentResponse &&\n        (hasEssentialCookie ||\n          isConsentManagementRequest ||\n          sessionEstablishingReason !== undefined);\n\n      // Replay cookies captured from fresh SFAPI and proxy responses when allowed.\n      if (capturedCookies && mayReturnShopifyState) {\n        const existingSetCookies = new Set(headers.getSetCookie());\n        for (const value of capturedCookies) {\n          if (existingSetCookies.has(value)) continue;\n          headers.append(\"set-cookie\", value);\n          existingSetCookies.add(value);\n        }\n      }\n\n      // Consent/session responses can contain private state in the body without setting cookies.\n      if (\n        personalizedResponseReason ||\n        isConsentManagementRequest ||\n        sessionEstablishingReason !== undefined ||\n        headers.has(\"set-cookie\")\n      ) {\n        applyPrivateResponseCacheHeaders(headers);\n      }\n    },\n  } as ShopifyRequestContext<I18n>;\n}\n\nfunction normalizeI18n<I18n extends I18nConfig>(i18n: I18n): NormalizedI18nConfig<I18n> {\n  return {\n    ...i18n,\n    pathPrefix: normalizePathPrefix(i18n.pathPrefix),\n  } as NormalizedI18nConfig<I18n>;\n}\n\nfunction applyStorefrontRequestHeaders(context: Context, headers: Headers): void {\n  headers.set(SDK_VARIANT_HEADER, \"hydrogen\");\n  headers.set(SDK_VARIANT_SOURCE_HEADER, \"kit\");\n  headers.set(SDK_VERSION_HEADER, STOREFRONT_API_VERSION);\n  headers.set(HYDROGEN_VERSION_HEADER, __HYDROGEN_VERSION__);\n  headers.set(REQUEST_GROUP_ID_HEADER, context.requestGroupId);\n\n  if (context.cookie) headers.set(\"cookie\", context.cookie);\n  else headers.delete(\"cookie\");\n  if (context.globalPrivacyControl !== undefined) {\n    headers.set(SEC_GPC_HEADER, context.globalPrivacyControl);\n  } else headers.delete(SEC_GPC_HEADER);\n  if (context.storefrontOrigin) {\n    headers.set(SHOPIFY_STOREFRONT_ORIGIN_HEADER, context.storefrontOrigin);\n  } else headers.delete(SHOPIFY_STOREFRONT_ORIGIN_HEADER);\n}\n\nfunction getUrlOrigin(url: string | undefined): string | undefined {\n  if (!url) return undefined;\n  try {\n    return new URL(url).origin;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction isDocumentRequest(request: StorefrontRequest): boolean {\n  if (request.method && request.method !== \"GET\" && request.method !== \"HEAD\") return false;\n\n  const destination = request.headers.get(\"sec-fetch-dest\");\n  if (destination === \"document\") return true;\n\n  return request.headers.get(\"accept\")?.includes(\"text/html\") ?? false;\n}\n\nfunction parseCookieHeader(cookieHeader: string | undefined): Map<string, string> {\n  const cookies = new Map<string, string>();\n  if (!cookieHeader) return cookies;\n\n  for (const cookie of cookieHeader.split(\";\")) {\n    const separator = cookie.indexOf(\"=\");\n    if (separator < 0) continue;\n\n    const name = cookie.slice(0, separator).trim();\n    if (!cookies.has(name)) cookies.set(name, cookie.slice(separator + 1));\n  }\n\n  return cookies;\n}\n"],"mappings":"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"}
+{"version":3,"file":"request-context.mjs","names":[],"sources":["../../src/core/request-context.ts"],"sourcesContent":["import type {\n  CountryCode as CustomerAccountCountryCode,\n  LanguageCode as CustomerAccountLanguageCode,\n} from \"../graphql/generated/customer-account-api-types\";\nimport type {\n  CountryCode as StorefrontCountryCode,\n  LanguageCode as StorefrontLanguageCode,\n} from \"../graphql/generated/storefront-api-types\";\nimport { STOREFRONT_API_VERSION } from \"./constants\";\nimport {\n  applyPrivateResponseCacheHeaders,\n  CONSENT_MANAGEMENT_HEADER,\n  HYDROGEN_VERSION_HEADER,\n  REQUEST_GROUP_ID_HEADER,\n  SDK_VARIANT_HEADER,\n  SDK_VARIANT_SOURCE_HEADER,\n  SDK_VERSION_HEADER,\n  SEC_GPC_HEADER,\n  SHOPIFY_STOREFRONT_ORIGIN_HEADER,\n  STOREFRONT_URL_HEADER,\n} from \"./headers\";\nimport { normalizePathPrefix } from \"./standard-routes/path\";\n\nconst SHOPIFY_ESSENTIAL_COOKIE = \"_shopify_essential\";\n\n/** The incoming request's headers, plus its method, abort signal, and URL when the framework provides them. */\ntype StorefrontRequest = Pick<Request, \"headers\"> &\n  Partial<Pick<Request, \"method\" | \"signal\" | \"url\">>;\n\n/** A language code that both the Storefront API and the Customer Account API accept. */\nexport type ShopifyLanguageCode = Extract<StorefrontLanguageCode, CustomerAccountLanguageCode>;\n/** A country code that both the Storefront API and the Customer Account API accept. */\nexport type ShopifyCountryCode = Extract<StorefrontCountryCode, CustomerAccountCountryCode>;\n\n/** The language, country, and optional localized path prefix for a request. */\nexport type I18nConfig = {\n  /** The request's language. */\n  language: ShopifyLanguageCode;\n  /** The request's country. */\n  country: ShopifyCountryCode;\n  /**\n   * The URL prefix for localized routes, such as `/es-es`. Hydrogen adds the prefix to standard route redirects and product variant URLs.\n   */\n  pathPrefix?: string;\n};\n\n/** The request's locale, with a path prefix that starts with `/` or is an empty string. */\ntype NormalizedI18nConfig<I18n extends I18nConfig = I18nConfig> = Omit<I18n, \"pathPrefix\"> & {\n  pathPrefix: string;\n};\n\n/** The incoming request and its locale. */\ntype ShopifyRequestContextInputBase<I18n extends I18nConfig = I18nConfig> = {\n  /**\n   * The incoming request from your framework. When the framework exposes no request, such as during prerendering, pass `{ headers: new Headers() }`.\n   */\n  request: StorefrontRequest;\n  /** The request's language, country, and optional localized path prefix. */\n  i18n: I18n;\n};\n\ntype ShopifyRequestContextInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp?: never };\n\ntype ShopifyRequestContextWithBuyerIpInput<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextInputBase<I18n> & { buyerIp: string };\n\n/** The fields and methods on every request context. */\ntype ShopifyRequestContextBase = {\n  // -- Private fields --\n  /**\n   * A type-only marker. Create request contexts only with `createShopifyRequestContext`.\n   * @internal\n   */\n  readonly __hydrogenShopifyRequestContextBrand: never;\n  /**\n   * The incoming request's `Cookie` header. Hydrogen forwards the header to the Storefront API.\n   * @internal\n   */\n  cookie?: string;\n  /**\n   * The customer's trusted IP address. Private Storefront API clients require it.\n   * @internal\n   */\n  readonly buyerIp?: string;\n  /**\n   * The ID that groups this request's Shopify API calls. Hydrogen reads the ID from the request headers or generates one.\n   * @internal\n   */\n  requestGroupId: string;\n  /**\n   * The incoming request's abort signal. Hydrogen's API clients stop their requests when the signal aborts.\n   * @internal\n   */\n  signal?: AbortSignal;\n  /**\n   * The incoming request's URL.\n   * @internal\n   */\n  url?: string;\n  /**\n   * The origin of the incoming request's URL. Hydrogen forwards the origin to the Storefront API.\n   * @internal\n   */\n  storefrontOrigin?: string;\n  /**\n   * Adds the Hydrogen SDK headers and the customer's cookie, privacy, and origin headers to a\n   * Storefront API request. The Storefront API client and the API proxies call the method for you.\n   * @internal\n   */\n  applyStorefrontRequestHeaders(headers: Headers): void;\n  /**\n   * Saves the cookies from the first Storefront API response that sets cookies. The Storefront API\n   * client calls the method for you, and `applyResponseHeaders()` can add the cookies to your response.\n   * @internal\n   */\n  captureSubrequestHeaders(headers: Headers): void;\n  /**\n   * Saves the cookies from a proxied Storefront API response and removes the `set-cookie` header\n   * from that response. The API proxies in `handleShopifyRoutes` call the method for you.\n   * @internal\n   */\n  consumeStorefrontResponseHeaders(headers: Headers): void;\n  /**\n   * Marks the final response as private and uncacheable because the response holds customer data.\n   * The Customer Account API client and the customer session call the method for you.\n   * @internal\n   */\n  markResponseAsPersonalized(reason: string): void;\n  /**\n   * Lets the final response set Shopify cookies before the customer has a Shopify session, and\n   * marks the response as private and uncacheable. The UCP MCP proxy calls the method for you.\n   * @internal\n   */\n  markResponseAsSessionEstablishing(reason: string): void;\n\n  // -- Public fields --\n  /** The request's language, country, and path prefix. The path prefix starts with `/` and has no trailing slash, or is an empty string when you don't set one. */\n  i18n: NormalizedI18nConfig;\n  /** Returns the incoming request's headers with Shopify's request headers added. Pass the headers when you forward the request to a proxy or another origin. */\n  getForwardedRequestHeaders(): Headers;\n  /**\n   * Adds the headers that a Hydrogen storefront needs to the final response. Call the method on each response that your app builds. Responses from `handleShopifyRoutes` and `handleShopifyRedirects` already carry these headers.\n   *\n   * Append your committed session headers before you call the method. The method makes any response that sets a cookie private and uncacheable. The method also sets the `powered-by` header, makes responses that hold customer data private and uncacheable, and adds eligible Shopify cookies only to non-document responses for methods other than `GET` and `HEAD`.\n   */\n  applyResponseHeaders(headers: Headers): void;\n};\n\n/** The context for one request. Pass the context to Hydrogen's API clients and route handlers for that request. */\nexport type ShopifyRequestContext<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContextBase & {\n    i18n: NormalizedI18nConfig<I18n>;\n  };\n\n/** A request context that includes the customer's IP address. Private Storefront API clients require this context. */\nexport type ShopifyRequestContextWithBuyerIp<I18n extends I18nConfig = I18nConfig> =\n  ShopifyRequestContext<I18n> & { readonly buyerIp: string };\n\n/** The values that the request context reads from the incoming request. */\ntype Context<I18n extends I18nConfig = I18nConfig> = {\n  /** The incoming request's `Cookie` header. */\n  cookie?: string;\n  /** The incoming request's `Sec-GPC` header value, which carries the customer's Global Privacy Control signal. */\n  globalPrivacyControl?: string;\n  /** The customer's trusted IP address. */\n  buyerIp?: string;\n  /** The ID that groups this request's Shopify API calls. Hydrogen reads the ID from the request headers or generates one. */\n  requestGroupId: string;\n  /** The incoming request's abort signal. */\n  signal?: AbortSignal;\n  /** The incoming request's URL. */\n  url?: string;\n  /** The origin of the incoming request's URL. */\n  storefrontOrigin?: string;\n  /** The request's language, country, and path prefix. */\n  i18n: NormalizedI18nConfig<I18n>;\n  /** Whether the incoming request asks for an HTML document. */\n  documentRequest?: boolean;\n};\n\n/**\n * Creates the context for one incoming request. Pass the same context to the Storefront API\n * client, the Customer Account API client, and `handleShopifyRoutes`. The context forwards the\n * customer's cookies, locale, and privacy signal to Shopify, and adds Shopify's cookies and cache\n * headers to your response.\n *\n * Call `applyResponseHeaders()` on each response that your app builds. Pass `buyerIp` with the customer's trusted IP address when you use a private Storefront API client. The function throws when `i18n` lacks a country or language, and when `buyerIp` is an empty string.\n *\n * @publicDocs\n */\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextWithBuyerIpInput<I18n>,\n): ShopifyRequestContextWithBuyerIp<I18n>;\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInput<I18n>,\n): ShopifyRequestContext<I18n>;\n/**\n * @param input The incoming request, its locale, and the customer's IP address for private Storefront API clients.\n * @returns The context to pass to Hydrogen's API clients and route handlers for this request.\n */\nexport function createShopifyRequestContext<const I18n extends I18nConfig>(\n  input: ShopifyRequestContextInputBase<I18n> & { buyerIp?: string },\n): ShopifyRequestContext<I18n> {\n  const { request } = input;\n\n  if (!input.i18n?.country || !input.i18n?.language) {\n    throw new Error(\"i18n with country and language is required for Shopify request contexts.\");\n  }\n\n  if (input.buyerIp !== undefined && !input.buyerIp) {\n    throw new Error(\"buyerIp must be non-empty when provided\");\n  }\n\n  const requestMethod = request.method?.toUpperCase();\n  const i18n = normalizeI18n(input.i18n);\n  const cookieHeader = request.headers.get(\"cookie\") || undefined;\n  const inboundCookies = parseCookieHeader(cookieHeader);\n  const hasEssentialCookie = inboundCookies.has(SHOPIFY_ESSENTIAL_COOKIE);\n  const isConsentManagementRequest = request.headers.get(CONSENT_MANAGEMENT_HEADER) === \"1\";\n  const url = request.url ?? request.headers.get(STOREFRONT_URL_HEADER) ?? undefined;\n  const storefrontOrigin = getUrlOrigin(url);\n  const context = {\n    ...(cookieHeader && { cookie: cookieHeader }),\n    globalPrivacyControl: request.headers.get(SEC_GPC_HEADER) ?? undefined,\n    i18n,\n    ...(url && { url }),\n    ...(storefrontOrigin && { storefrontOrigin }),\n    ...(input.buyerIp && { buyerIp: input.buyerIp }),\n    requestGroupId:\n      request.headers.get(REQUEST_GROUP_ID_HEADER) ??\n      request.headers.get(\"x-request-id\") ??\n      request.headers.get(\"request-id\") ??\n      crypto.randomUUID(),\n    ...(isDocumentRequest(request) && { documentRequest: true }),\n    ...(request.signal && { signal: request.signal }),\n  } as Context<I18n>;\n\n  let capturedCookies: string[] | undefined;\n  let personalizedResponseReason: string | undefined;\n  let sessionEstablishingReason: string | undefined;\n\n  const captureSubrequestHeaders = (headers: Headers): void => {\n    // Capture the first fresh response cookies to increase the\n    // chance of returning them from the main server response. The main response\n    // needs headers set at send time, while the body can stream later, so this\n    // may not be used if subrequests finish after the main response is sent.\n    const cookies = headers.getSetCookie();\n    if (cookies.length > 0) capturedCookies ??= cookies;\n  };\n\n  return {\n    ...context,\n    getForwardedRequestHeaders() {\n      const headers = new Headers(request.headers);\n      applyStorefrontRequestHeaders(context, headers);\n      if (context.url) headers.set(STOREFRONT_URL_HEADER, context.url);\n      return headers;\n    },\n    applyStorefrontRequestHeaders(headers) {\n      applyStorefrontRequestHeaders(context, headers);\n    },\n    captureSubrequestHeaders,\n    consumeStorefrontResponseHeaders(headers) {\n      captureSubrequestHeaders(headers);\n      headers.delete(\"set-cookie\");\n    },\n    markResponseAsPersonalized(reason) {\n      personalizedResponseReason ??= reason;\n    },\n    markResponseAsSessionEstablishing(reason) {\n      sessionEstablishingReason ??= reason;\n    },\n    applyResponseHeaders(headers) {\n      headers.set(\"powered-by\", \"Shopify, Hydrogen\");\n\n      // Documents may be shared or streamed, so they must not carry buyer-specific state.\n      const isDocumentResponse =\n        context.documentRequest || (headers.get(\"content-type\")?.startsWith(\"text/html\") ?? false);\n\n      // Keep GET and HEAD responses cacheable, and fail closed when the request method is unknown.\n      // Cold sessions may only be established by the explicitly marked consent request.\n      const mayReturnShopifyState =\n        requestMethod !== undefined &&\n        requestMethod !== \"GET\" &&\n        requestMethod !== \"HEAD\" &&\n        !isDocumentResponse &&\n        (hasEssentialCookie ||\n          isConsentManagementRequest ||\n          sessionEstablishingReason !== undefined);\n\n      // Replay cookies captured from fresh SFAPI and proxy responses when allowed.\n      if (capturedCookies && mayReturnShopifyState) {\n        const existingSetCookies = new Set(headers.getSetCookie());\n        for (const value of capturedCookies) {\n          if (existingSetCookies.has(value)) continue;\n          headers.append(\"set-cookie\", value);\n          existingSetCookies.add(value);\n        }\n      }\n\n      // Consent/session responses can contain private state in the body without setting cookies.\n      if (\n        personalizedResponseReason ||\n        isConsentManagementRequest ||\n        sessionEstablishingReason !== undefined ||\n        headers.has(\"set-cookie\")\n      ) {\n        applyPrivateResponseCacheHeaders(headers);\n      }\n    },\n  } as ShopifyRequestContext<I18n>;\n}\n\nfunction normalizeI18n<I18n extends I18nConfig>(i18n: I18n): NormalizedI18nConfig<I18n> {\n  return {\n    ...i18n,\n    pathPrefix: normalizePathPrefix(i18n.pathPrefix),\n  } as NormalizedI18nConfig<I18n>;\n}\n\nfunction applyStorefrontRequestHeaders(context: Context, headers: Headers): void {\n  headers.set(SDK_VARIANT_HEADER, \"hydrogen\");\n  headers.set(SDK_VARIANT_SOURCE_HEADER, \"kit\");\n  headers.set(SDK_VERSION_HEADER, STOREFRONT_API_VERSION);\n  headers.set(HYDROGEN_VERSION_HEADER, __HYDROGEN_VERSION__);\n  headers.set(REQUEST_GROUP_ID_HEADER, context.requestGroupId);\n\n  if (context.cookie) headers.set(\"cookie\", context.cookie);\n  else headers.delete(\"cookie\");\n  if (context.globalPrivacyControl !== undefined) {\n    headers.set(SEC_GPC_HEADER, context.globalPrivacyControl);\n  } else headers.delete(SEC_GPC_HEADER);\n  if (context.storefrontOrigin) {\n    headers.set(SHOPIFY_STOREFRONT_ORIGIN_HEADER, context.storefrontOrigin);\n  } else headers.delete(SHOPIFY_STOREFRONT_ORIGIN_HEADER);\n}\n\nfunction getUrlOrigin(url: string | undefined): string | undefined {\n  if (!url) return undefined;\n  try {\n    return new URL(url).origin;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction isDocumentRequest(request: StorefrontRequest): boolean {\n  if (request.method && request.method !== \"GET\" && request.method !== \"HEAD\") return false;\n\n  const destination = request.headers.get(\"sec-fetch-dest\");\n  if (destination === \"document\") return true;\n\n  return request.headers.get(\"accept\")?.includes(\"text/html\") ?? false;\n}\n\nfunction parseCookieHeader(cookieHeader: string | undefined): Map<string, string> {\n  const cookies = new Map<string, string>();\n  if (!cookieHeader) return cookies;\n\n  for (const cookie of cookieHeader.split(\";\")) {\n    const separator = cookie.indexOf(\"=\");\n    if (separator < 0) continue;\n\n    const name = cookie.slice(0, separator).trim();\n    if (!cookies.has(name)) cookies.set(name, cookie.slice(separator + 1));\n  }\n\n  return cookies;\n}\n"],"mappings":"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"}

package/dist/core/request-routing/handle-shopify-redirects.d.mts

@@ -2,14 +2,22 @@ import { StorefrontClient } from "../../client/types.mjs";
 import { ShopifyRouteTemplates } from "../standard-routes/types.mjs";
 
 //#region src/core/request-routing/handle-shopify-redirects.d.ts
+/** The unmatched request, the Storefront API client, and your app's route templates. */
 type RedirectOptions = {
-  request: Request;
-  storefrontClient: StorefrontClient;
+  /** The request that your framework's router answered with a `404` response. */request: Request; /** The Storefront API client for the current request. Hydrogen looks up the store's URL redirects with the client, and reads the locale path prefix from the client's request context. */
+  storefrontClient: StorefrontClient; /** Your app's route templates. Hydrogen redirects Shopify's default resource paths to these templates. */
   routeTemplates: ShopifyRouteTemplates;
 };
 /**
- * Resolves Shopify redirects after framework routing returns a 404. Matched
- * responses already include request-context response headers.
+ * Finds the Shopify redirect for a request that your framework's router can't match. Call the
+ * function when the router returns a `404` response, and return that `404` response when the function
+ * resolves to `null`.
+ *
+ * The function checks these redirects in order and returns the first match as a `301` response: `/admin` to the store's admin, Shopify's default resource paths to your route templates, same-origin `return_to` and `redirect` query parameters, and the store's URL redirects. The response already carries the request context's headers. When a redirect lookup fails, the function logs the error and resolves to `null`.
+ *
+ * @param options The unmatched request, the Storefront API client, and your app's route templates.
+ * @returns A promise for the matched redirect response, or `null` when no redirect matches.
+ * @publicDocs
  */
 declare function handleShopifyRedirects(options: RedirectOptions): Promise<Response | null>;
 //#endregion

package/dist/core/request-routing/handle-shopify-redirects.mjs

@@ -8,8 +8,15 @@ import { safeApplyResponseHeaders } from "./safe-apply-response-headers.mjs";
 //#region src/core/request-routing/handle-shopify-redirects.ts
 const log = getLogger("redirects");
 /**
-* Resolves Shopify redirects after framework routing returns a 404. Matched
-* responses already include request-context response headers.
+* Finds the Shopify redirect for a request that your framework's router can't match. Call the
+* function when the router returns a `404` response, and return that `404` response when the function
+* resolves to `null`.
+*
+* The function checks these redirects in order and returns the first match as a `301` response: `/admin` to the store's admin, Shopify's default resource paths to your route templates, same-origin `return_to` and `redirect` query parameters, and the store's URL redirects. The response already carries the request context's headers. When a redirect lookup fails, the function logs the error and resolves to `null`.
+*
+* @param options The unmatched request, the Storefront API client, and your app's route templates.
+* @returns A promise for the matched redirect response, or `null` when no redirect matches.
+* @publicDocs
 */
 async function handleShopifyRedirects(options) {
 	const { request, storefrontClient } = options;