@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/shopify-scripts/types.d.mts

@@ -4,17 +4,23 @@ import { ShopifyGlobal } from "../../globals.mjs";
 import { ConsentConfig, ShopAnalyticsChannel, StorefrontAnalyticsConfig } from "../analytics/types.mjs";
 
 //#region src/core/shopify-scripts/types.d.ts
+/** The sales channel and custom data for the analytics bus. */
 type ShopifyScriptsAnalyticsConfig = {
-  channel?: ShopAnalyticsChannel;
+  /** The sales channel that Shopify attributes analytics to. Defaults to `hydrogen`. */channel?: ShopAnalyticsChannel; /** Extra values that analytics destinations can read from the bus configuration. */
   customData?: StorefrontAnalyticsConfig["customData"];
 };
-type ShopifyScriptsI18n = Pick<I18nConfig, "country" | "language"> & Partial<Pick<I18nConfig, "pathPrefix">> & {
+/** The locale that Shopify's scripts read from the browser's Shopify global. */
+interface ShopifyScriptsI18n extends Pick<I18nConfig, "country" | "language">, Partial<Pick<I18nConfig, "pathPrefix">> {
+  /** The active currency code. Hydrogen converts it to uppercase. */
   currency?: string;
-};
+}
+/** The values of the HTML `crossorigin` attribute. */
 type ShopifyCrossOrigin = "" | "anonymous" | "use-credentials";
+/** Custom `data-*` HTML attributes with string values. */
 type ShopifyDataAttributes = {
   [name: `data-${string}`]: string;
 };
+/** The HTML attributes of a generated script tag, with lowercase attribute names. */
 type ShopifyScriptTagAttributes = ShopifyDataAttributes & Partial<{
   async: boolean;
   crossorigin: ShopifyCrossOrigin;
@@ -24,58 +30,85 @@ type ShopifyScriptTagAttributes = ShopifyDataAttributes & Partial<{
   src: string;
   type: string;
 }>;
+/** The HTML attributes of a generated link tag. */
 type ShopifyLinkTagAttributes = Partial<{
-  as: "script";
-  crossorigin: ShopifyCrossOrigin;
-  href: string;
+  /** The resource type for a prefetch link. Always `script`. */as: "script"; /** The CORS mode for fetching the linked resource. */
+  crossorigin: ShopifyCrossOrigin; /** The URL of the origin to preconnect to, or the script to prefetch. */
+  href: string; /** Whether the link preconnects to an origin or prefetches a script. */
   rel: "preconnect" | "prefetch";
 }>;
+/** A script tag to render in the document head. */
 type ShopifyScriptDescriptor = {
-  tagName: "script";
-  attributes?: ShopifyScriptTagAttributes;
+  /** Always `script` for a script tag. */tagName: "script"; /** The script tag's HTML attributes, such as its source URL and nonce. */
+  attributes?: ShopifyScriptTagAttributes; /** The inline script content, for scripts that have no source URL. */
   innerHTML?: string;
 };
+/** A link tag to render in the document head. */
 type ShopifyLinkDescriptor = {
-  tagName: "link";
-  attributes: ShopifyLinkTagAttributes;
+  /** Always `link` for a link tag. */tagName: "link";
+  attributes: ShopifyLinkTagAttributes; /** Link tags have no content. */
   innerHTML?: never;
 };
+/** A script or link tag to render in the document head. */
 type ShopifyScriptTagDescriptor = ShopifyScriptDescriptor | ShopifyLinkDescriptor;
+/** The generated link and script tags, as separate lists and as one combined list. */
 type ShopifyScriptTagDescriptors = {
   /** Link descriptors for framework head APIs that split links from scripts. */readonly links: readonly ShopifyLinkDescriptor[]; /** Script descriptors for framework head APIs that split scripts from links. */
   readonly scripts: readonly ShopifyScriptDescriptor[]; /** All generated descriptors as a mixed list, with links before scripts. */
   readonly tags: readonly ShopifyScriptTagDescriptor[];
 };
+/** The shop identifiers that Shopify's scripts and analytics use. */
 type ShopifyScriptsShop = {
-  shopId: string;
-  storefrontId: string; /** The shop's permanent `*.myshopify.com` domain, exposed as `window.Shopify.shop`. */
+  /** The shop's ID, as a numeric string or a Shop GID. */shopId: string; /** The Hydrogen storefront's ID. Hydrogen leaves it out of Headless channel analytics. */
+  storefrontId: string; /** The shop's permanent `*.myshopify.com` domain. Hydrogen sets it as `window.Shopify.shop`. */
   myshopifyDomain: string;
 };
+/** The shop details and the features whose scripts to load. */
 type ShopifyScriptTagsOptions = {
   /**
-   * Loads the customer account component. Render `<shopify-account>` where you want the account UI to appear.
-   * @see {@link https://shopify.dev/docs/api/storefront-web-components/components/shopify-account | shopify-account}
+   * Loads the customer account component. Render `shopify-account` where you want the account UI to appear.
+   * @see [shopify-account](https://shopify.dev/docs/api/storefront-web-components/components/shopify-account)
    */
-  account?: boolean;
-  analytics?: ShopifyScriptsAnalyticsConfig;
-  consent?: ConsentConfig;
+  account?: boolean; /** The sales channel and custom data for the analytics bus. */
+  analytics?: ShopifyScriptsAnalyticsConfig; /** Which consent script to load and how the analytics bus waits for consent. */
+  consent?: ConsentConfig; /** Development-only debugging tools. */
   debug?: {
     /** Loads Shopify's standard events inspector in development builds. */standardEventsInspector?: boolean;
-  };
-  i18n?: ShopifyScriptsI18n; /** Loads Inbox. Render `<shopify-chat>` where you want the chat UI to appear. */
+  }; /** The country, language, currency, and path prefix for Shopify's scripts. Defaults to US English. */
+  i18n?: ShopifyScriptsI18n; /** Loads Inbox. Render `shopify-chat` where you want the chat UI to appear. */
   inbox?: boolean;
-  nonce?: string;
-  shop: ShopifyScriptsShop;
+  /**
+   * Adds a `nonce` attribute to every script tag.
+   */
+  nonce?: string; /** The shop's IDs and permanent domain. */
+  shop: ShopifyScriptsShop; /** Loads Shopify's storefront analytics script. Defaults to `true`. */
   shopifyAnalytics?: boolean;
 };
+/**
+ * Route settings for Shopify's scripts: the storefront's route templates and a callback for
+ * client-side navigation.
+ */
 type ShopifyRoutesOptions = {
-  navigate?: ShopifyGlobal["routes"]["navigate"];
+  /**
+   * Navigates to a URL after Shopify's scripts resolve it to your app's route. Defaults to a full
+   * page load. Checkout, cart permalink, buy permalink, and customer account paths always use a full page load.
+   */
+  navigate?: ShopifyGlobal["routes"]["navigate"]; /** Your app's custom route templates, which Shopify's scripts use to match and resolve storefront URLs. */
   routes?: ShopifyRouteTemplates;
 };
-type InitializeShopifyScriptsOptions = ShopifyRoutesOptions & {
-  /** Pass the same consent configuration used to render the script tags. Setup runs once per bus. */consent?: ConsentConfig;
+/** The route, consent, and WebMCP settings for starting Shopify's scripts in the browser. */
+interface InitializeShopifyScriptsOptions extends ShopifyRoutesOptions {
+  /** The consent configuration that you passed to the script tags. The bus runs the setup callback once. */
+  consent?: ConsentConfig;
+  /** Loads Shopify WebMCP tools when the browser supports WebMCP. Defaults to `true`. */
   webMcp?: boolean;
-};
+}
+/**
+ * Options for both `getShopifyScriptTags` and `initializeShopifyScripts`. Build one object and pass
+ * it to both functions.
+ *
+ * @publicDocs
+ */
 type ShopifyScriptsOptions = ShopifyScriptTagsOptions & InitializeShopifyScriptsOptions;
 //#endregion
 export { InitializeShopifyScriptsOptions, ShopifyRoutesOptions, ShopifyScriptTagDescriptor, ShopifyScriptTagDescriptors, ShopifyScriptTagsOptions, ShopifyScriptsAnalyticsConfig, ShopifyScriptsI18n, ShopifyScriptsOptions, ShopifyScriptsShop };

package/dist/core/standard-routes/build.d.mts

@@ -2,21 +2,19 @@ import { ShopifyRouteTemplates } from "./types.mjs";
 
 //#region src/core/standard-routes/build.d.ts
 /**
- * Creates a typed map of custom route templates for Shopify standard storefront routes.
+ * Tells Hydrogen where your app serves products, collections, and other Shopify resources. Pass
+ * the returned object to `handleShopifyRoutes`, `handleShopifyRedirects`, the `ShopifyScripts` `routes`
+ * option, and the predictive search URL helpers.
  *
- * Use the returned object anywhere Hydrogen needs to understand the app's URL shape for
- * Shopify resources and utility pages: `handleShopifyRedirects({routeTemplates})`, `ShopifyScripts`
- * `routes={routeTemplates}`, and predictive search URL helpers.
+ * Add a key only for a route that your app serves at a non-standard path. Hydrogen uses Shopify's
+ * default path for each key that you leave out. Pass an empty object when your app serves every
+ * route at its default path. Each template starts with `/` and includes the handle placeholders
+ * for its route. Leave the locale path prefix out of templates. Hydrogen adds the prefix for you.
  *
- * Each key represents a Shopify standard route identity, while each value is the app's custom
- * pathname template. Templates must start with `/` and include the required named handle
- * placeholders for routes that identify a resource. Do not include an i18n path prefix in the
- * template; Hydrogen applies `i18n.pathPrefix` separately when resolving routes. Pass an empty
- * object when the app uses standard storefront routes so there is still one app-owned routing
- * manifest to update if routes change later. When matching the current page, standard storefront
- * routes retain their page-template identities even if a configured template resolves another
- * route to the same pathname.
+ * TypeScript checks the shape of each template. The function returns the object that you pass.
  *
+ * @param routes The non-standard paths that your app serves, keyed by standard route name.
+ * @returns The route templates, typed for Hydrogen's route, redirect, and URL helpers.
  * @example
  * ```ts
  * const routeTemplates = createShopifyRouteTemplates({
@@ -27,6 +25,7 @@ import { ShopifyRouteTemplates } from "./types.mjs";
  *   policy: "/legal/:policyHandle",
  * });
  * ```
+ * @publicDocs
  */
 declare function createShopifyRouteTemplates<const TRoutes extends ShopifyRouteTemplates>(routes: TRoutes): TRoutes;
 //#endregion

package/dist/core/standard-routes/build.mjs

@@ -3,21 +3,19 @@ import { prependPathPrefix } from "./path.mjs";
 
 //#region src/core/standard-routes/build.ts
 /**
-* Creates a typed map of custom route templates for Shopify standard storefront routes.
+* Tells Hydrogen where your app serves products, collections, and other Shopify resources. Pass
+* the returned object to `handleShopifyRoutes`, `handleShopifyRedirects`, the `ShopifyScripts` `routes`
+* option, and the predictive search URL helpers.
 *
-* Use the returned object anywhere Hydrogen needs to understand the app's URL shape for
-* Shopify resources and utility pages: `handleShopifyRedirects({routeTemplates})`, `ShopifyScripts`
-* `routes={routeTemplates}`, and predictive search URL helpers.
+* Add a key only for a route that your app serves at a non-standard path. Hydrogen uses Shopify's
+* default path for each key that you leave out. Pass an empty object when your app serves every
+* route at its default path. Each template starts with `/` and includes the handle placeholders
+* for its route. Leave the locale path prefix out of templates. Hydrogen adds the prefix for you.
 *
-* Each key represents a Shopify standard route identity, while each value is the app's custom
-* pathname template. Templates must start with `/` and include the required named handle
-* placeholders for routes that identify a resource. Do not include an i18n path prefix in the
-* template; Hydrogen applies `i18n.pathPrefix` separately when resolving routes. Pass an empty
-* object when the app uses standard storefront routes so there is still one app-owned routing
-* manifest to update if routes change later. When matching the current page, standard storefront
-* routes retain their page-template identities even if a configured template resolves another
-* route to the same pathname.
+* TypeScript checks the shape of each template. The function returns the object that you pass.
 *
+* @param routes The non-standard paths that your app serves, keyed by standard route name.
+* @returns The route templates, typed for Hydrogen's route, redirect, and URL helpers.
 * @example
 * ```ts
 * const routeTemplates = createShopifyRouteTemplates({
@@ -28,6 +26,7 @@ import { prependPathPrefix } from "./path.mjs";
 *   policy: "/legal/:policyHandle",
 * });
 * ```
+* @publicDocs
 */
 function createShopifyRouteTemplates(routes) {
 	return routes;

package/dist/core/standard-routes/build.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"build.mjs","names":[],"sources":["../../../src/core/standard-routes/build.ts"],"sourcesContent":["import { DEFAULT_STANDARD_ROUTES, isStandardRouteParamName } from \"./defaults\";\nimport { prependPathPrefix } from \"./path\";\nimport type {\n  ShopifyRouteTemplates,\n  StandardRouteName,\n  StandardRouteOptions,\n  StandardRouteParams,\n  StandardRouteParamsByName,\n} from \"./types\";\n\n/**\n * Creates a typed map of custom route templates for Shopify standard storefront routes.\n *\n * Use the returned object anywhere Hydrogen needs to understand the app's URL shape for\n * Shopify resources and utility pages: `handleShopifyRedirects({routeTemplates})`, `ShopifyScripts`\n * `routes={routeTemplates}`, and predictive search URL helpers.\n *\n * Each key represents a Shopify standard route identity, while each value is the app's custom\n * pathname template. Templates must start with `/` and include the required named handle\n * placeholders for routes that identify a resource. Do not include an i18n path prefix in the\n * template; Hydrogen applies `i18n.pathPrefix` separately when resolving routes. Pass an empty\n * object when the app uses standard storefront routes so there is still one app-owned routing\n * manifest to update if routes change later. When matching the current page, standard storefront\n * routes retain their page-template identities even if a configured template resolves another\n * route to the same pathname.\n *\n * @example\n * ```ts\n * const routeTemplates = createShopifyRouteTemplates({\n *   product: \"/p/:productHandle\",\n *   collection: \"/c/:collectionHandle\",\n *   article: \"/journal/:blogHandle/:articleHandle\",\n *   cart: \"/basket\",\n *   policy: \"/legal/:policyHandle\",\n * });\n * ```\n */\nexport function createShopifyRouteTemplates<const TRoutes extends ShopifyRouteTemplates>(\n  routes: TRoutes,\n): TRoutes {\n  return routes;\n}\n\nexport function getStandardRoute<const TRoute extends StandardRouteName>(\n  routeTemplates: ShopifyRouteTemplates,\n  route: TRoute,\n  params: StandardRouteParamsByName[TRoute],\n  options: StandardRouteOptions = {},\n): string {\n  const target = routeTemplates[route] ?? DEFAULT_STANDARD_ROUTES[route][0];\n\n  return buildStandardRouteTarget(target, params, options.pathPrefix);\n}\n\n/**\n * Builds a pathname from a route template, handle params, and optional i18n path prefix.\n */\nexport function buildStandardRouteTarget(\n  template: string,\n  params: StandardRouteParams,\n  pathPrefix: string | undefined,\n): string {\n  return prependPathPrefix(interpolateRouteTemplate(template, params), pathPrefix);\n}\n\nfunction interpolateRouteTemplate(template: string, params: StandardRouteParams): string {\n  return template.replace(/:([A-Za-z][A-Za-z0-9_]*)/g, (placeholder, name: string) => {\n    if (!isStandardRouteParamName(name)) return placeholder;\n\n    const value = params[name];\n    return value === undefined ? placeholder : encodeURIComponent(value);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,4BACd,QACS;AACT,QAAO;;AAGT,SAAgB,iBACd,gBACA,OACA,QACA,UAAgC,EAAE,EAC1B;AAGR,QAAO,yBAFQ,eAAe,UAAU,wBAAwB,OAAO,IAE/B,QAAQ,QAAQ,WAAW;;;;;AAMrE,SAAgB,yBACd,UACA,QACA,YACQ;AACR,QAAO,kBAAkB,yBAAyB,UAAU,OAAO,EAAE,WAAW;;AAGlF,SAAS,yBAAyB,UAAkB,QAAqC;AACvF,QAAO,SAAS,QAAQ,8BAA8B,aAAa,SAAiB;AAClF,MAAI,CAAC,yBAAyB,KAAK,CAAE,QAAO;EAE5C,MAAM,QAAQ,OAAO;AACrB,SAAO,UAAU,SAAY,cAAc,mBAAmB,MAAM;GACpE"}
+{"version":3,"file":"build.mjs","names":[],"sources":["../../../src/core/standard-routes/build.ts"],"sourcesContent":["import { DEFAULT_STANDARD_ROUTES, isStandardRouteParamName } from \"./defaults\";\nimport { prependPathPrefix } from \"./path\";\nimport type {\n  ShopifyRouteTemplates,\n  StandardRouteName,\n  StandardRouteOptions,\n  StandardRouteParams,\n  StandardRouteParamsByName,\n} from \"./types\";\n\n/**\n * Tells Hydrogen where your app serves products, collections, and other Shopify resources. Pass\n * the returned object to `handleShopifyRoutes`, `handleShopifyRedirects`, the `ShopifyScripts` `routes`\n * option, and the predictive search URL helpers.\n *\n * Add a key only for a route that your app serves at a non-standard path. Hydrogen uses Shopify's\n * default path for each key that you leave out. Pass an empty object when your app serves every\n * route at its default path. Each template starts with `/` and includes the handle placeholders\n * for its route. Leave the locale path prefix out of templates. Hydrogen adds the prefix for you.\n *\n * TypeScript checks the shape of each template. The function returns the object that you pass.\n *\n * @param routes The non-standard paths that your app serves, keyed by standard route name.\n * @returns The route templates, typed for Hydrogen's route, redirect, and URL helpers.\n * @example\n * ```ts\n * const routeTemplates = createShopifyRouteTemplates({\n *   product: \"/p/:productHandle\",\n *   collection: \"/c/:collectionHandle\",\n *   article: \"/journal/:blogHandle/:articleHandle\",\n *   cart: \"/basket\",\n *   policy: \"/legal/:policyHandle\",\n * });\n * ```\n * @publicDocs\n */\nexport function createShopifyRouteTemplates<const TRoutes extends ShopifyRouteTemplates>(\n  routes: TRoutes,\n): TRoutes {\n  return routes;\n}\n\nexport function getStandardRoute<const TRoute extends StandardRouteName>(\n  routeTemplates: ShopifyRouteTemplates,\n  route: TRoute,\n  params: StandardRouteParamsByName[TRoute],\n  options: StandardRouteOptions = {},\n): string {\n  const target = routeTemplates[route] ?? DEFAULT_STANDARD_ROUTES[route][0];\n\n  return buildStandardRouteTarget(target, params, options.pathPrefix);\n}\n\n/**\n * Builds a pathname from a route template, handle params, and optional i18n path prefix.\n */\nexport function buildStandardRouteTarget(\n  template: string,\n  params: StandardRouteParams,\n  pathPrefix: string | undefined,\n): string {\n  return prependPathPrefix(interpolateRouteTemplate(template, params), pathPrefix);\n}\n\nfunction interpolateRouteTemplate(template: string, params: StandardRouteParams): string {\n  return template.replace(/:([A-Za-z][A-Za-z0-9_]*)/g, (placeholder, name: string) => {\n    if (!isStandardRouteParamName(name)) return placeholder;\n\n    const value = params[name];\n    return value === undefined ? placeholder : encodeURIComponent(value);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,4BACd,QACS;AACT,QAAO;;AAGT,SAAgB,iBACd,gBACA,OACA,QACA,UAAgC,EAAE,EAC1B;AAGR,QAAO,yBAFQ,eAAe,UAAU,wBAAwB,OAAO,IAE/B,QAAQ,QAAQ,WAAW;;;;;AAMrE,SAAgB,yBACd,UACA,QACA,YACQ;AACR,QAAO,kBAAkB,yBAAyB,UAAU,OAAO,EAAE,WAAW;;AAGlF,SAAS,yBAAyB,UAAkB,QAAqC;AACvF,QAAO,SAAS,QAAQ,8BAA8B,aAAa,SAAiB;AAClF,MAAI,CAAC,yBAAyB,KAAK,CAAE,QAAO;EAE5C,MAAM,QAAQ,OAAO;AACrB,SAAO,UAAU,SAAY,cAAc,mBAAmB,MAAM;GACpE"}

package/dist/core/standard-routes/types.d.mts

@@ -1,75 +1,78 @@
 //#region src/core/standard-routes/types.d.ts
+/** A path template that starts with `/` and includes the named handle placeholder. */
 type StandardRouteTemplateWithParam<Param extends string> = `/${string}:${Param}` | `/${string}:${Param}/${string}`;
+/** A path template that starts with `/`. */
 type StandardRouteTemplate = `/${string}`;
+/** Your app's custom path templates for Shopify standard storefront routes, keyed by route name. */
 type ShopifyRouteTemplates = {
   /**
-   * Redirects Shopify article routes, for example
-   * `/blogs/news/snowboard-guide`, to the app's custom article route.
+   * The app's article path. Hydrogen redirects Shopify article paths, such as
+   * `/blogs/news/snowboard-guide`, to this template.
    *
    * @example "/journal/:blogHandle/:articleHandle"
    */
   article?: StandardRouteTemplateWithParam<"blogHandle"> & StandardRouteTemplateWithParam<"articleHandle">;
   /**
-   * Redirects Shopify blog routes, for example `/blogs/news`, to the app's
-   * custom blog route.
+   * The app's blog path. Hydrogen redirects Shopify blog paths, such as
+   * `/blogs/news`, to this template.
    *
    * @example "/journal/:blogHandle"
    */
   blog?: StandardRouteTemplateWithParam<"blogHandle">;
   /**
-   * Redirects Shopify's `/cart` route to the app's custom cart route.
+   * The app's cart path. Hydrogen redirects Shopify's `/cart` path to this template.
    *
    * @example "/basket"
    */
   cart?: StandardRouteTemplate;
   /**
-   * Redirects Shopify collection routes, for example `/collections/winter`,
-   * to the app's custom collection route.
+   * The app's collection path. Hydrogen redirects Shopify collection paths, such as
+   * `/collections/winter`, to this template.
    *
    * @example "/c/:collectionHandle"
    */
   collection?: StandardRouteTemplateWithParam<"collectionHandle">;
   /**
-   * Redirects Shopify's collection-listing routes, `/collections` and the
-   * legacy `/products`, to the app's custom collection-listing route.
+   * The app's collection list path. Hydrogen redirects Shopify's `/collections`
+   * path and the legacy `/products` path to this template.
    *
    * @example "/catalog"
    */
   collectionList?: StandardRouteTemplate;
   /**
-   * Redirects Shopify page routes, for example `/pages/about-us`, to the app's
-   * custom page route.
+   * The app's page path. Hydrogen redirects Shopify page paths, such as
+   * `/pages/about-us`, to this template.
    *
    * @example "/content/:pageHandle"
    */
   page?: StandardRouteTemplateWithParam<"pageHandle">;
   /**
-   * Redirects Shopify policy routes, for example `/policies/privacy-policy`,
-   * to the app's custom policy route.
+   * The app's policy path. Hydrogen redirects Shopify policy paths, such as
+   * `/policies/privacy-policy`, to this template.
    *
    * @example "/legal/:policyHandle"
    */
   policy?: StandardRouteTemplateWithParam<"policyHandle">;
   /**
-   * Redirects Shopify product routes, for example `/products/snowboard`,
-   * to the app's custom product route.
+   * The app's product path. Hydrogen redirects Shopify product paths, such as
+   * `/products/snowboard`, to this template.
    *
    * @example "/p/:productHandle"
    */
   product?: StandardRouteTemplateWithParam<"productHandle">;
   /**
-   * Redirects Shopify collection-scoped product routes, for example
-   * `/collections/winter/products/snowboard`, to the app's custom product route.
+   * The app's path for products inside a collection. Hydrogen redirects Shopify
+   * paths such as `/collections/winter/products/snowboard` to this template.
    *
-   * Must include `:productHandle`. May include `:collectionHandle` when the
-   * app's custom product route is also collection-scoped.
+   * The template must include `:productHandle`. Add `:collectionHandle` when the
+   * app's product path also names the collection.
    *
    * @example "/p/:productHandle"
    * @example "/c/:collectionHandle/p/:productHandle"
    */
   productInCollection?: StandardRouteTemplateWithParam<"productHandle">;
   /**
-   * Redirects Shopify's `/search` route to the app's custom search route.
+   * The app's search path. Hydrogen redirects Shopify's `/search` path to this template.
    *
    * @example "/find"
    */
@@ -77,14 +80,17 @@ type ShopifyRouteTemplates = {
 };
 type StandardRouteName = keyof ShopifyRouteTemplates;
 type ShopifyStandardRouteName = StandardRouteName | "index";
+/** The page template name for a standard route. Collection-scoped products use `product`, and the collection list uses `list-collections`. */
 type ShopifyPageTemplateName<TRoute extends ShopifyStandardRouteName = ShopifyStandardRouteName> = TRoute extends "productInCollection" ? "product" : TRoute extends "collectionList" ? "list-collections" : TRoute;
 type StandardRouteParamName = "articleHandle" | "blogHandle" | "collectionHandle" | "pageHandle" | "policyHandle" | "productHandle";
+/** The handle values that fill a route template's placeholders, keyed by placeholder name. */
 type StandardRouteParams = Partial<Record<StandardRouteParamName, string>>;
+/** The standard route that a storefront URL matches, with its handles, page template name, and templates. */
 type ShopifyStandardRouteMatch<TRoute extends ShopifyStandardRouteName = ShopifyStandardRouteName> = {
-  standardPathname: string;
-  params: StandardRouteParams;
-  route: TRoute;
-  pageTemplateName: ShopifyPageTemplateName<TRoute>;
+  /** Shopify's default path for the matched resource, with the locale path prefix applied. */standardPathname: string; /** The decoded handle values from the matched URL. */
+  params: StandardRouteParams; /** The standard route name that the URL matched, or `index` for the home page. */
+  route: TRoute; /** The page template name for the matched route, such as `product` or `list-collections`. */
+  pageTemplateName: ShopifyPageTemplateName<TRoute>; /** Shopify's default template for the matched route and your app's custom template, which falls back to the default. */
   templates: {
     standard: string;
     custom: string;

package/dist/core/url.mjs

@@ -24,6 +24,7 @@ const CUSTOMER_ACCOUNT_HANDOFF_PATHS = new Set(Object.values(CUSTOMER_ACCOUNT_PA
 function isHydrogenServerHandoffPath(pathname) {
 	return CHECKOUT_RE.test(pathname) || CART_PERMALINK_RE.test(pathname) || BUY_PERMALINK_RE.test(pathname) || CUSTOMER_ACCOUNT_HANDOFF_PATHS.has(pathname);
 }
+const UCP_RE = /^\/\.well-known\/ucp$/;
 /**
 * Allowlisted `.well-known` resources proxied to the Online Store origin:
 * - `apple-developer-merchantid-domain-association` — Apple Pay domain verification.
@@ -57,5 +58,5 @@ function normalizeStoreDomain(domain) {
 }
 
 //#endregion
-export { AJAX_CART_RE, BUY_PERMALINK_RE, CHECKOUT_RE, CUSTOMER_ACCOUNT_PATHS, MCP_RE, SFAPI_RE, SHOPIFY_API_PROXY_PREFIX, SHOPIFY_API_PROXY_RE, UCP_MCP_RE, WELL_KNOWN_RE, getSameOriginPath, isHydrogenServerHandoffPath, normalizeStoreDomain };
+export { AJAX_CART_RE, BUY_PERMALINK_RE, CHECKOUT_RE, CUSTOMER_ACCOUNT_PATHS, MCP_RE, SFAPI_RE, SHOPIFY_API_PROXY_PREFIX, SHOPIFY_API_PROXY_RE, UCP_MCP_RE, UCP_RE, WELL_KNOWN_RE, getSameOriginPath, isHydrogenServerHandoffPath, normalizeStoreDomain };
 //# sourceMappingURL=url.mjs.map

package/dist/core/url.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"url.mjs","names":[],"sources":["../../src/core/url.ts"],"sourcesContent":["export const SFAPI_RE = /^\\/api\\/(unstable|2\\d{3}-\\d{2})\\/graphql\\.json$/;\nexport const SHOPIFY_API_PROXY_PREFIX = \"/__shopify\";\nexport const SHOPIFY_API_PROXY_RE = /^\\/__shopify(?:\\/|$)/;\nexport const MCP_RE = /^\\/api\\/mcp$/;\nexport const UCP_MCP_RE = /^\\/api\\/ucp\\/mcp$/;\nexport const CHECKOUT_RE = /^\\/checkout$/;\nexport const CART_PERMALINK_RE = /^\\/cart\\/\\d+:\\d+(?:,\\d+:\\d+)*$/;\nconst BUY_ITEM_PAIR = String.raw`(?:[A-Za-z0-9._-]+|~[A-Za-z0-9_-]+):[1-9]\\d*`;\n// Items are required so a storefront's own /buy pages keep routing to the app.\nexport const BUY_PERMALINK_RE = new RegExp(`^/buy/${BUY_ITEM_PAIR}(?:,${BUY_ITEM_PAIR})*$`);\nexport const CUSTOMER_ACCOUNT_PATHS = {\n  authorize: \"/account/authorize\",\n  login: \"/account/login\",\n  logout: \"/account/logout\",\n  refresh: \"/account/refresh\",\n} as const;\n\nconst CUSTOMER_ACCOUNT_HANDOFF_PATHS: ReadonlySet<string> = new Set(\n  Object.values(CUSTOMER_ACCOUNT_PATHS),\n);\n\n/**\n * Returns whether the pathname conventionally represents a Hydrogen document-level server handoff.\n *\n * Keep this aligned with the routes intercepted before framework routing. API and protocol\n * interceptors are intentionally excluded because they are not browser navigation destinations.\n */\nexport function isHydrogenServerHandoffPath(pathname: string): boolean {\n  return (\n    CHECKOUT_RE.test(pathname) ||\n    CART_PERMALINK_RE.test(pathname) ||\n    BUY_PERMALINK_RE.test(pathname) ||\n    CUSTOMER_ACCOUNT_HANDOFF_PATHS.has(pathname)\n  );\n}\n\n/**\n * Allowlisted `.well-known` resources proxied to the Online Store origin:\n * - `apple-developer-merchantid-domain-association` — Apple Pay domain verification.\n * - `shopify/fec/produce` — Frontend Event Collector ingress. On the Online\n *   Store the myshopify.com edge forwards this first-party path to the\n *   collector; headless storefronts have no such edge, so Hydrogen proxies it\n *   to the same origin (used by WebMCP's Event Refinery client).\n */\nexport const WELL_KNOWN_RE =\n  /^\\/\\.well-known\\/(?:apple-developer-merchantid-domain-association|shopify\\/fec\\/produce)$/;\nexport const AJAX_CART_RE =\n  /^(?:\\/[a-z]{2}(?:-[a-z]{2})?)?\\/cart(?:\\.(?:js|json)|\\/(?:add|update|change|clear)(?:\\.(?:js|json))?)$/i;\n\n/**\n * Normalizes `target` to a path on `origin` that is safe to use as a redirect location.\n * Returns `undefined` unless `target` is a path starting with `/` or an absolute URL,\n * stays on `origin`, and its normalized pathname does not start with `//`.\n */\nexport function getSameOriginPath(\n  target: string | null | undefined,\n  origin: string,\n): string | undefined {\n  if (!target) return undefined;\n\n  try {\n    // Parse absolute URLs without a base so scheme-relative forms like `https:evil.example`\n    // resolve to their own host, as a browser would, instead of onto `origin`.\n    const url = target.startsWith(\"/\") ? new URL(target, origin) : new URL(target);\n    if (url.origin !== origin) return undefined;\n    const path = `${url.pathname}${url.search}${url.hash}`;\n    // The parsed pathname can itself start with `//` (e.g. from `/x/..//evil`),\n    // which a redirect would resolve as a protocol-relative URL to another host.\n    return path.startsWith(\"//\") ? undefined : path;\n  } catch {\n    return undefined;\n  }\n}\n\nexport function normalizeStoreDomain(domain: string): string {\n  if (!domain) {\n    throw new Error(\"Storefront `storeDomain` is required.\");\n  }\n\n  if (domain.startsWith(\"http://\") || domain.startsWith(\"https://\")) {\n    return domain.replace(/\\/+$/, \"\");\n  }\n  return `https://${domain}`.replace(/\\/+$/, \"\");\n}\n"],"mappings":";AAAA,MAAa,WAAW;AACxB,MAAa,2BAA2B;AACxC,MAAa,uBAAuB;AACpC,MAAa,SAAS;AACtB,MAAa,aAAa;AAC1B,MAAa,cAAc;AAC3B,MAAa,oBAAoB;AACjC,MAAM,gBAAgB,OAAO,GAAG;AAEhC,MAAa,mBAAmB,IAAI,OAAO,SAAS,cAAc,MAAM,cAAc,KAAK;AAC3F,MAAa,yBAAyB;CACpC,WAAW;CACX,OAAO;CACP,QAAQ;CACR,SAAS;CACV;AAED,MAAM,iCAAsD,IAAI,IAC9D,OAAO,OAAO,uBAAuB,CACtC;;;;;;;AAQD,SAAgB,4BAA4B,UAA2B;AACrE,QACE,YAAY,KAAK,SAAS,IAC1B,kBAAkB,KAAK,SAAS,IAChC,iBAAiB,KAAK,SAAS,IAC/B,+BAA+B,IAAI,SAAS;;;;;;;;;;AAYhD,MAAa,gBACX;AACF,MAAa,eACX;;;;;;AAOF,SAAgB,kBACd,QACA,QACoB;AACpB,KAAI,CAAC,OAAQ,QAAO;AAEpB,KAAI;EAGF,MAAM,MAAM,OAAO,WAAW,IAAI,GAAG,IAAI,IAAI,QAAQ,OAAO,GAAG,IAAI,IAAI,OAAO;AAC9E,MAAI,IAAI,WAAW,OAAQ,QAAO;EAClC,MAAM,OAAO,GAAG,IAAI,WAAW,IAAI,SAAS,IAAI;AAGhD,SAAO,KAAK,WAAW,KAAK,GAAG,SAAY;SACrC;AACN;;;AAIJ,SAAgB,qBAAqB,QAAwB;AAC3D,KAAI,CAAC,OACH,OAAM,IAAI,MAAM,wCAAwC;AAG1D,KAAI,OAAO,WAAW,UAAU,IAAI,OAAO,WAAW,WAAW,CAC/D,QAAO,OAAO,QAAQ,QAAQ,GAAG;AAEnC,QAAO,WAAW,SAAS,QAAQ,QAAQ,GAAG"}
+{"version":3,"file":"url.mjs","names":[],"sources":["../../src/core/url.ts"],"sourcesContent":["export const SFAPI_RE = /^\\/api\\/(unstable|2\\d{3}-\\d{2})\\/graphql\\.json$/;\nexport const SHOPIFY_API_PROXY_PREFIX = \"/__shopify\";\nexport const SHOPIFY_API_PROXY_RE = /^\\/__shopify(?:\\/|$)/;\nexport const MCP_RE = /^\\/api\\/mcp$/;\nexport const UCP_MCP_RE = /^\\/api\\/ucp\\/mcp$/;\nexport const CHECKOUT_RE = /^\\/checkout$/;\nexport const CART_PERMALINK_RE = /^\\/cart\\/\\d+:\\d+(?:,\\d+:\\d+)*$/;\nconst BUY_ITEM_PAIR = String.raw`(?:[A-Za-z0-9._-]+|~[A-Za-z0-9_-]+):[1-9]\\d*`;\n// Items are required so a storefront's own /buy pages keep routing to the app.\nexport const BUY_PERMALINK_RE = new RegExp(`^/buy/${BUY_ITEM_PAIR}(?:,${BUY_ITEM_PAIR})*$`);\nexport const CUSTOMER_ACCOUNT_PATHS = {\n  authorize: \"/account/authorize\",\n  login: \"/account/login\",\n  logout: \"/account/logout\",\n  refresh: \"/account/refresh\",\n} as const;\n\nconst CUSTOMER_ACCOUNT_HANDOFF_PATHS: ReadonlySet<string> = new Set(\n  Object.values(CUSTOMER_ACCOUNT_PATHS),\n);\n\n/**\n * Returns whether the pathname conventionally represents a Hydrogen document-level server handoff.\n *\n * Keep this aligned with the routes intercepted before framework routing. API and protocol\n * interceptors are intentionally excluded because they are not browser navigation destinations.\n */\nexport function isHydrogenServerHandoffPath(pathname: string): boolean {\n  return (\n    CHECKOUT_RE.test(pathname) ||\n    CART_PERMALINK_RE.test(pathname) ||\n    BUY_PERMALINK_RE.test(pathname) ||\n    CUSTOMER_ACCOUNT_HANDOFF_PATHS.has(pathname)\n  );\n}\n\n// UCP profiles need JSON validation and caching separate from the other well-known resources.\nexport const UCP_RE = /^\\/\\.well-known\\/ucp$/;\n\n/**\n * Allowlisted `.well-known` resources proxied to the Online Store origin:\n * - `apple-developer-merchantid-domain-association` — Apple Pay domain verification.\n * - `shopify/fec/produce` — Frontend Event Collector ingress. On the Online\n *   Store the myshopify.com edge forwards this first-party path to the\n *   collector; headless storefronts have no such edge, so Hydrogen proxies it\n *   to the same origin (used by WebMCP's Event Refinery client).\n */\nexport const WELL_KNOWN_RE =\n  /^\\/\\.well-known\\/(?:apple-developer-merchantid-domain-association|shopify\\/fec\\/produce)$/;\nexport const AJAX_CART_RE =\n  /^(?:\\/[a-z]{2}(?:-[a-z]{2})?)?\\/cart(?:\\.(?:js|json)|\\/(?:add|update|change|clear)(?:\\.(?:js|json))?)$/i;\n\n/**\n * Normalizes `target` to a path on `origin` that is safe to use as a redirect location.\n * Returns `undefined` unless `target` is a path starting with `/` or an absolute URL,\n * stays on `origin`, and its normalized pathname does not start with `//`.\n */\nexport function getSameOriginPath(\n  target: string | null | undefined,\n  origin: string,\n): string | undefined {\n  if (!target) return undefined;\n\n  try {\n    // Parse absolute URLs without a base so scheme-relative forms like `https:evil.example`\n    // resolve to their own host, as a browser would, instead of onto `origin`.\n    const url = target.startsWith(\"/\") ? new URL(target, origin) : new URL(target);\n    if (url.origin !== origin) return undefined;\n    const path = `${url.pathname}${url.search}${url.hash}`;\n    // The parsed pathname can itself start with `//` (e.g. from `/x/..//evil`),\n    // which a redirect would resolve as a protocol-relative URL to another host.\n    return path.startsWith(\"//\") ? undefined : path;\n  } catch {\n    return undefined;\n  }\n}\n\nexport function normalizeStoreDomain(domain: string): string {\n  if (!domain) {\n    throw new Error(\"Storefront `storeDomain` is required.\");\n  }\n\n  if (domain.startsWith(\"http://\") || domain.startsWith(\"https://\")) {\n    return domain.replace(/\\/+$/, \"\");\n  }\n  return `https://${domain}`.replace(/\\/+$/, \"\");\n}\n"],"mappings":";AAAA,MAAa,WAAW;AACxB,MAAa,2BAA2B;AACxC,MAAa,uBAAuB;AACpC,MAAa,SAAS;AACtB,MAAa,aAAa;AAC1B,MAAa,cAAc;AAC3B,MAAa,oBAAoB;AACjC,MAAM,gBAAgB,OAAO,GAAG;AAEhC,MAAa,mBAAmB,IAAI,OAAO,SAAS,cAAc,MAAM,cAAc,KAAK;AAC3F,MAAa,yBAAyB;CACpC,WAAW;CACX,OAAO;CACP,QAAQ;CACR,SAAS;CACV;AAED,MAAM,iCAAsD,IAAI,IAC9D,OAAO,OAAO,uBAAuB,CACtC;;;;;;;AAQD,SAAgB,4BAA4B,UAA2B;AACrE,QACE,YAAY,KAAK,SAAS,IAC1B,kBAAkB,KAAK,SAAS,IAChC,iBAAiB,KAAK,SAAS,IAC/B,+BAA+B,IAAI,SAAS;;AAKhD,MAAa,SAAS;;;;;;;;;AAUtB,MAAa,gBACX;AACF,MAAa,eACX;;;;;;AAOF,SAAgB,kBACd,QACA,QACoB;AACpB,KAAI,CAAC,OAAQ,QAAO;AAEpB,KAAI;EAGF,MAAM,MAAM,OAAO,WAAW,IAAI,GAAG,IAAI,IAAI,QAAQ,OAAO,GAAG,IAAI,IAAI,OAAO;AAC9E,MAAI,IAAI,WAAW,OAAQ,QAAO;EAClC,MAAM,OAAO,GAAG,IAAI,WAAW,IAAI,SAAS,IAAI;AAGhD,SAAO,KAAK,WAAW,KAAK,GAAG,SAAY;SACrC;AACN;;;AAIJ,SAAgB,qBAAqB,QAAwB;AAC3D,KAAI,CAAC,OACH,OAAM,IAAI,MAAM,wCAAwC;AAG1D,KAAI,OAAO,WAAW,UAAU,IAAI,OAAO,WAAW,WAAW,CAC/D,QAAO,OAAO,QAAQ,QAAQ,GAAG;AAEnC,QAAO,WAAW,SAAS,QAAQ,QAAQ,GAAG"}

package/dist/customer-account/client.d.mts

@@ -4,72 +4,55 @@ import { AnyCustomerAccountDocument, CustomerAccountDocument } from "./graphql.m
 
 //#region src/customer-account/client.d.ts
 /**
- * Options for {@link createCustomerAccountClient}.
- *
- * The client validates `shopId`, `customerApiVersion`, and `defaultTimeoutInMs`
- * at construction time and throws synchronously on invalid values.
+ * Options for creating a Customer Account API client.
  */
 type CreateCustomerAccountClientOptions = {
-  /** Numeric Shopify shop ID as a string (e.g. `"12345"`). Validated against `/^\d+$/`. */shopId: string;
+  /** Numeric Shopify shop ID as a string of digits, such as `12345`. */shopId: string;
   /**
-   * Customer Account API version in `YYYY-MM` format.
-   * Defaults to {@link CUSTOMER_ACCOUNT_API_VERSION}.
+   * Customer Account API version in `YYYY-MM` format. Defaults to `2026-10`.
    */
   customerApiVersion?: string;
   /**
-   * Request-scoped context created by `createShopifyRequestContext`. Must
-   * have a `url` property (throws at construction when missing or non-HTTPS;
-   * `http://localhost`, `127.0.0.1` and `::1` are accepted and sent as
-   * HTTPS). Supplies the i18n language for automatic `$language` variable
-   * injection, an abort signal that propagates request cancellation, and a
-   * personalization marker (sets `private, no-store` and removes CDN cache
-   * headers).
+   * The context for the current request, from `createShopifyRequestContext`.
+   *
+   * The context's URL must use HTTPS, or creating the client throws. Local `http://` URLs on localhost, 127.0.0.1, and ::1 also work for development.
+   *
+   * The client fills `$language` from the context's language and stops requests when the context's signal aborts.
    */
-  requestContext: ShopifyRequestContext; /** Custom `fetch` implementation. Falls back to `globalThis.fetch`. */
+  requestContext: ShopifyRequestContext; /** Custom fetch implementation. Defaults to the global fetch. */
   fetch?: typeof globalThis.fetch;
   /**
-   * Per-request timeout in milliseconds. Must be a positive safe integer no
-   * greater than 2,147,483,647. Defaults to 30,000 ms.
+   * Timeout for each request in milliseconds. Must be a positive integer no greater than 2,147,483,647. Defaults to `30000`.
    */
   defaultTimeoutInMs?: number;
 };
 /**
- * Per-call options passed to {@link CustomerAccountClient.graphql}.
- * See `variables` for automatic `$language` injection.
+ * Options for a single Customer Account API request.
  */
 type CustomerAccountGraphqlOptions<Variables = Record<string, unknown>> = {
-  /** Customer Account API access token, e.g. from `CustomerSession.getAccessToken()` or `getOrRefreshAccessToken()`. */accessToken: string;
+  /** The customer's access token, such as one from the customer session's `getOrRefreshAccessToken()` method. */accessToken: string;
   /**
-   * Query variables. When the GraphQL document declares a `$language` variable
-   * and you omit it here, the client injects it automatically from
-   * `requestContext.i18n.language`.
+   * The document's variables. When the document declares `$language` and you omit it, the client fills the variable from the request context's language.
    */
   variables?: Variables;
   /**
-   * Optional abort signal. Combined with the request context signal and the
-   * per-request timeout signal via `AbortSignal.any`, so cancellation from any
-   * source stops the request.
+   * Stops this request when the signal aborts. The request also stops when the request context's signal aborts or the timeout passes.
    */
   signal?: AbortSignal;
 };
 type ResultOfDoc<Doc> = Doc extends CustomerAccountDocument<infer Result, never, string> ? Result : never;
+/** The variables that a Customer Account document declares. */
 type VariablesOfDoc<Doc> = Doc extends CustomerAccountDocument<unknown, infer Variables, string> ? Variables : never;
+/** An optional `language` variable for a document that declares `$language`. The client fills a missing value from the request context. */
 type OptionalAutoVariables<Variables> = "language" extends keyof Variables ? {
   language?: Variables["language"];
 } : {};
 type UserVariables<Doc> = Omit<VariablesOfDoc<Doc>, "language"> & OptionalAutoVariables<VariablesOfDoc<Doc>>;
 type HasNoRequiredKeys<T> = Record<string, never> extends T ? true : false;
 /**
- * Discriminated union returned by {@link CustomerAccountClient.graphql}.
- *
- * Discriminate on the presence of `errors`, not via `Partial`:
+ * Result of a Customer Account API request. Check `errors` to tell the outcomes apart.
  *
- * - **Success:** `data` is always present, `errors` is `undefined`.
- * - **Partial or error:** `errors` is a non-empty array of
- *   {@link GraphQLFormattedError}, and `data` may be `null`.
- *
- * Both arms expose the raw response `headers` for inspecting
- * `x-request-id` or rate-limit metadata.
+ * On success, `data` holds the result and `errors` is `undefined`. When the response has GraphQL errors, `errors` holds them and `data` can be `null`. Every result includes the raw response headers.
  */
 type CustomerAccountGraphqlResult<Result = unknown> = {
   data: Result;
@@ -81,44 +64,29 @@ type CustomerAccountGraphqlResult<Result = unknown> = {
   headers: Headers;
 };
 /**
- * Conditional rest parameter for {@link CustomerAccountClient.graphql}.
+ * The options argument for a Customer Account API request.
  *
- * When the document has no required user variables (after `language` is
- * excluded from the requirement), `options.variables` is optional. When the
- * document declares required variables, the type forces the caller to supply
- * them, turning a missing-variables bug into a compile error.
+ * Pass `variables` when the document declares a required variable other than `language`. TypeScript reports an error when a required variable is missing.
  */
 type CustomerAccountGqlRestParam<Doc extends AnyCustomerAccountDocument> = HasNoRequiredKeys<UserVariables<Doc>> extends true ? [options: CustomerAccountGraphqlOptions<UserVariables<Doc>>] : [options: CustomerAccountGraphqlOptions<UserVariables<Doc>> & {
   variables: UserVariables<Doc>;
 }];
 /**
- * A server-side GraphQL client for the Shopify Customer Account API.
- *
- * Created by {@link createCustomerAccountClient}. Each call to `graphql()`
- * validates that the document was produced by `gql()` (runtime branded with a
- * private Symbol), validates the access token, auto-injects the `language`
- * variable from i18n context when applicable, and marks the response as
- * personalized so the app response is sent with private, no-store cache headers.
+ * A client that sends Customer Account API requests from your server for the current request.
  */
 type CustomerAccountClient = {
-  /** Constructed endpoint: `https://shopify.com/{shopId}/account/customer/api/{version}/graphql`. */readonly apiUrl: string;
+  /** The GraphQL endpoint, `https://shopify.com/{shopId}/account/customer/api/{version}/graphql`. */readonly apiUrl: string;
   /**
-   * Send a GraphQL request to the Customer Account API.
+   * Sends a Customer Account API query or mutation with the customer's access token, and returns the data, any GraphQL errors, and the response headers. Pass a document from the Customer Account `gql` function.
+   *
+   * The request makes the final response private and uncacheable when you call `applyResponseHeaders()`. When the document declares `$language` and you omit it, the client fills the variable from the request context's language.
    *
-   * The document must be created by `gql()`. At call time the client:
-   * 1. Validates the document brand and options object.
-   * 2. Marks the response as personalized (sets `private, no-store`).
-   * 3. Validates the access token.
-   * 4. Throws if a signal is already aborted.
-   * 5. Combines the request context signal, the caller's signal, and a timeout
-   *    signal via `AbortSignal.any`.
-   * 6. Auto-injects the `language` variable from `requestContext.i18n.language`
-   *    when the document declares `$language` and the caller omits it.
+   * The method throws a `TypeError` for a document from any other `gql` function, including the Storefront API `gql` function, and for variables that aren't an object. When a signal aborts, the method throws the signal's reason. A missing or malformed access token throws `CustomerAccountAuthenticationError`, a timeout throws `CustomerAccountTimeoutError`, and other request failures throw `CustomerAccountApiError`.
    *
-   * @throws {TypeError} When the document is not a branded `gql()` result.
-   * @throws {CustomerAccountAuthenticationError} When the access token fails pre-flight validation.
-   * @throws {CustomerAccountTimeoutError} When the request exceeds `defaultTimeoutInMs`.
-   * @throws {CustomerAccountApiError} On non-OK HTTP status, unparseable JSON, or missing `data`.
+   * @throws {TypeError} When another gql function created the document, or when the variables aren't an object.
+   * @throws {CustomerAccountAuthenticationError} When the options object is missing or the access token fails validation.
+   * @throws {CustomerAccountTimeoutError} When the request exceeds the client's timeout.
+   * @throws {CustomerAccountApiError} On a non-OK HTTP status, unparseable JSON, a response without data, or a network failure.
    *
    * @example
    * ```ts
@@ -137,13 +105,9 @@ type CustomerAccountClient = {
   graphql: <const Doc extends AnyCustomerAccountDocument>(document: Doc, ...options: CustomerAccountGqlRestParam<Doc>) => Promise<CustomerAccountGraphqlResult<ResultOfDoc<Doc>>>;
 };
 /**
- * Creates a server-only {@link CustomerAccountClient} for the Shopify Customer
- * Account API.
+ * Creates a client that sends Customer Account API requests from your server. Create the client with the current request's context.
  *
- * Validates `shopId`, `customerApiVersion`, and `defaultTimeoutInMs` at
- * construction time. The returned client auto-injects the `language` variable
- * from `requestContext.i18n.language` when applicable, composes abort signals,
- * and marks responses as personalized (sets `private, no-store` cache headers).
+ * The function throws when the shop ID, API version, or timeout is invalid, when the request context has no HTTPS URL, when no fetch implementation is available, and when the function runs in a browser.
  *
  * @example
  * ```ts
@@ -160,7 +124,10 @@ type CustomerAccountClient = {
  * );
  * ```
  *
- * @throws {Error} When called in a browser context, when `shopId`, `customerApiVersion`, or `defaultTimeoutInMs` is invalid, when no `fetch` is available, or when `requestContext.url` is missing or not HTTPS.
+ * @param options - The shop ID, the API version, the request context, a custom fetch, and the request timeout.
+ * @returns A client with the GraphQL endpoint URL and a `graphql()` method for Customer Account API requests.
+ * @throws {Error} When called in a browser, when the shop ID, API version, or timeout is invalid, when no fetch is available, or when the request context URL is missing or not HTTPS.
+ * @publicDocs
  */
 declare function createCustomerAccountClient({
   shopId,