@shopify/hydrogen 2026.10.0-preview.2 → 2026.10.0-preview.4

package/dist/client/client.mjs

@@ -1,8 +1,8 @@
+import { normalizeStoreDomain } from "../core/url.mjs";
 import { getHydrogenCacheStatus } from "../core/cache/cache-status.mjs";
 import { createFetchWithCache } from "../core/cache/fetch-with-cache.mjs";
 import { DEFAULT_TIMEOUT_IN_MS, STOREFRONT_API_VERSION } from "../core/constants.mjs";
 import { HYDROGEN_VERSION_HEADER, REQUEST_GROUP_ID_HEADER, SDK_VARIANT_HEADER, SDK_VARIANT_SOURCE_HEADER, SDK_VERSION_HEADER, SHOPIFY_STOREFRONT_S_HEADER, SHOPIFY_STOREFRONT_Y_HEADER, SHOPIFY_UNIQUE_TOKEN_HEADER, SHOPIFY_VISIT_TOKEN_HEADER, STOREFRONT_ACCESS_TOKEN_HEADER, STOREFRONT_BUYER_IP_HEADER, STOREFRONT_ID_HEADER, STOREFRONT_PRIVATE_TOKEN_HEADER } from "../core/headers.mjs";
-import { normalizeStoreDomain } from "../core/url.mjs";
 import { StorefrontApiError, StorefrontTimeoutError } from "./errors.mjs";
 
 //#region src/client/client.ts
@@ -42,7 +42,7 @@ function createStorefrontClient(args) {
 	const { config, requestContext, type: clientType } = args;
 	if (!config.storeDomain) throw new Error("storeDomain is required and must be non-empty");
 	const storeUrl = normalizeStoreDomain(config.storeDomain);
-	const apiUrl = `${storeUrl}/api/${config.apiVersion ?? "2026-04"}/graphql.json`;
+	const apiUrl = `${storeUrl}/api/${config.apiVersion ?? "2026-10"}/graphql.json`;
 	const originFetch = config.fetch ?? globalThis.fetch;
 	if (typeof originFetch !== "function") throw new Error("No fetch function available. Pass a fetch option or ensure globalThis.fetch exists.");
 	const resolvedFetch = config.cache ? createFetchWithCache({

package/dist/client/errors.d.mts

@@ -5,41 +5,41 @@ interface StorefrontApiErrorOptions {
   cause?: unknown;
   queryText?: string;
   variables?: Record<string, unknown>;
-  locations?: ReadonlyArray<{
-    line: number;
-    column: number;
-  }>;
-  path?: ReadonlyArray<string | number>;
-  extensions?: Record<string, unknown>;
 }
+/**
+ * Thrown when a Storefront API request fails — HTTP error, network failure,
+ * or an unparseable or unexpected response body.
+ *
+ * In development, `queryText` and `variables` are attached when available.
+ * GraphQL errors (including `THROTTLED`) are not thrown; read them from `result.errors`.
+ */
 declare class StorefrontApiError extends Error {
+  /** Shopify `x-request-id` header, when available. Useful for support requests. */
   readonly requestId?: string;
+  /** HTTP response status code, when the request reached the server. */
   readonly status?: number;
+  /** The GraphQL query text. Only populated in development builds. */
   readonly queryText?: string;
+  /** The variables sent with the request. Only populated in development builds. */
   readonly variables?: Record<string, unknown>;
-  readonly locations?: ReadonlyArray<{
-    line: number;
-    column: number;
-  }>;
-  readonly path?: ReadonlyArray<string | number>;
-  readonly extensions?: Record<string, unknown>;
   constructor(message: string, options?: StorefrontApiErrorOptions);
   get [Symbol.toStringTag](): string;
-  toString(): string;
+  /** Serializes the error. `queryText`, `variables`, `cause`, and `stack` are always omitted. */
   toJSON(): {
     name: string;
     message: string;
     requestId?: string;
     status?: number;
-    locations?: ReadonlyArray<{
-      line: number;
-      column: number;
-    }>;
-    path?: ReadonlyArray<string | number>;
-    extensions?: Record<string, unknown>;
   };
 }
+/**
+ * Thrown when a Storefront API request exceeds the configured `defaultTimeoutInMs`.
+ *
+ * Subclass of {@link StorefrontApiError}, so catching `StorefrontApiError` also handles timeouts.
+ * Aborts from the request context or a per-call `signal` are rethrown as-is, not wrapped.
+ */
 declare class StorefrontTimeoutError extends StorefrontApiError {
+  /** The timeout threshold that was exceeded, in milliseconds. */
   readonly timeoutInMs: number;
   constructor(timeoutInMs: number, options?: Omit<StorefrontApiErrorOptions, "cause">);
 }

package/dist/client/errors.mjs

@@ -1,34 +1,30 @@
 //#region src/client/errors.ts
+/**
+* Thrown when a Storefront API request fails — HTTP error, network failure,
+* or an unparseable or unexpected response body.
+*
+* In development, `queryText` and `variables` are attached when available.
+* GraphQL errors (including `THROTTLED`) are not thrown; read them from `result.errors`.
+*/
 var StorefrontApiError = class extends Error {
+	/** Shopify `x-request-id` header, when available. Useful for support requests. */
 	requestId;
+	/** HTTP response status code, when the request reached the server. */
 	status;
+	/** The GraphQL query text. Only populated in development builds. */
 	queryText;
+	/** The variables sent with the request. Only populated in development builds. */
 	variables;
-	locations;
-	path;
-	extensions;
 	constructor(message, options) {
 		super(message, options?.cause ? { cause: options.cause } : void 0);
 		this.name = "StorefrontApiError";
 		this.requestId = options?.requestId;
 		this.status = options?.status;
-		this.locations = options?.locations;
-		this.path = options?.path;
-		this.extensions = options?.extensions;
 	}
 	get [Symbol.toStringTag]() {
 		return this.name;
 	}
-	toString() {
-		let result = `${this.name}: ${this.message}`;
-		if (this.path) try {
-			result += ` | path: ${JSON.stringify(this.path)}`;
-		} catch {}
-		if (this.extensions) try {
-			result += ` | extensions: ${JSON.stringify(this.extensions)}`;
-		} catch {}
-		return result;
-	}
+	/** Serializes the error. `queryText`, `variables`, `cause`, and `stack` are always omitted. */
 	toJSON() {
 		return {
 			name: this.name,
@@ -38,7 +34,14 @@ var StorefrontApiError = class extends Error {
 		};
 	}
 };
+/**
+* Thrown when a Storefront API request exceeds the configured `defaultTimeoutInMs`.
+*
+* Subclass of {@link StorefrontApiError}, so catching `StorefrontApiError` also handles timeouts.
+* Aborts from the request context or a per-call `signal` are rethrown as-is, not wrapped.
+*/
 var StorefrontTimeoutError = class extends StorefrontApiError {
+	/** The timeout threshold that was exceeded, in milliseconds. */
 	timeoutInMs;
 	constructor(timeoutInMs, options) {
 		super(`Storefront API request timed out after ${timeoutInMs}ms`, options);

package/dist/client/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/client/errors.ts"],"sourcesContent":["interface StorefrontApiErrorOptions {\n  requestId?: string;\n  status?: number;\n  cause?: unknown;\n  queryText?: string;\n  variables?: Record<string, unknown>;\n  locations?: ReadonlyArray<{ line: number; column: number }>;\n  path?: ReadonlyArray<string | number>;\n  extensions?: Record<string, unknown>;\n}\n\nexport class StorefrontApiError extends Error {\n  readonly requestId?: string;\n  readonly status?: number;\n  readonly queryText?: string;\n  readonly variables?: Record<string, unknown>;\n  readonly locations?: ReadonlyArray<{ line: number; column: number }>;\n  readonly path?: ReadonlyArray<string | number>;\n  readonly extensions?: Record<string, unknown>;\n\n  constructor(message: string, options?: StorefrontApiErrorOptions) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"StorefrontApiError\";\n    this.requestId = options?.requestId;\n    this.status = options?.status;\n    this.locations = options?.locations;\n    this.path = options?.path;\n    this.extensions = options?.extensions;\n\n    if (__DEV__) {\n      this.queryText = options?.queryText;\n      this.variables = options?.variables;\n    }\n  }\n\n  get [Symbol.toStringTag]() {\n    return this.name;\n  }\n\n  override toString(): string {\n    let result = `${this.name}: ${this.message}`;\n    if (this.path) {\n      try {\n        result += ` | path: ${JSON.stringify(this.path)}`;\n      } catch {}\n    }\n    if (this.extensions) {\n      try {\n        result += ` | extensions: ${JSON.stringify(this.extensions)}`;\n      } catch {}\n    }\n    return result;\n  }\n\n  toJSON(): {\n    name: string;\n    message: string;\n    requestId?: string;\n    status?: number;\n    locations?: ReadonlyArray<{ line: number; column: number }>;\n    path?: ReadonlyArray<string | number>;\n    extensions?: Record<string, unknown>;\n  } {\n    return {\n      name: this.name,\n      message: this.message,\n      ...(this.requestId != null && { requestId: this.requestId }),\n      ...(this.status != null && { status: this.status }),\n      ...(__DEV__ && this.locations && { locations: this.locations }),\n      ...(__DEV__ && this.path && { path: this.path }),\n      ...(__DEV__ && this.extensions && { extensions: this.extensions }),\n    };\n  }\n}\n\nexport class StorefrontTimeoutError extends StorefrontApiError {\n  readonly timeoutInMs: number;\n\n  constructor(timeoutInMs: number, options?: Omit<StorefrontApiErrorOptions, \"cause\">) {\n    super(`Storefront API request timed out after ${timeoutInMs}ms`, options);\n    this.name = \"StorefrontTimeoutError\";\n    this.timeoutInMs = timeoutInMs;\n  }\n}\n"],"mappings":";AAWA,IAAa,qBAAb,cAAwC,MAAM;CAC5C,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAY,SAAiB,SAAqC;AAChE,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,YAAY,SAAS;AAC1B,OAAK,SAAS,SAAS;AACvB,OAAK,YAAY,SAAS;AAC1B,OAAK,OAAO,SAAS;AACrB,OAAK,aAAa,SAAS;;CAQ7B,KAAK,OAAO,eAAe;AACzB,SAAO,KAAK;;CAGd,AAAS,WAAmB;EAC1B,IAAI,SAAS,GAAG,KAAK,KAAK,IAAI,KAAK;AACnC,MAAI,KAAK,KACP,KAAI;AACF,aAAU,YAAY,KAAK,UAAU,KAAK,KAAK;UACzC;AAEV,MAAI,KAAK,WACP,KAAI;AACF,aAAU,kBAAkB,KAAK,UAAU,KAAK,WAAW;UACrD;AAEV,SAAO;;CAGT,SAQE;AACA,SAAO;GACL,MAAM,KAAK;GACX,SAAS,KAAK;GACd,GAAI,KAAK,aAAa,QAAQ,EAAE,WAAW,KAAK,WAAW;GAC3D,GAAI,KAAK,UAAU,QAAQ,EAAE,QAAQ,KAAK,QAAQ;GAInD;;;AAIL,IAAa,yBAAb,cAA4C,mBAAmB;CAC7D,AAAS;CAET,YAAY,aAAqB,SAAoD;AACnF,QAAM,0CAA0C,YAAY,KAAK,QAAQ;AACzE,OAAK,OAAO;AACZ,OAAK,cAAc"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/client/errors.ts"],"sourcesContent":["interface StorefrontApiErrorOptions {\n  requestId?: string;\n  status?: number;\n  cause?: unknown;\n  queryText?: string;\n  variables?: Record<string, unknown>;\n}\n\n/**\n * Thrown when a Storefront API request fails — HTTP error, network failure,\n * or an unparseable or unexpected response body.\n *\n * In development, `queryText` and `variables` are attached when available.\n * GraphQL errors (including `THROTTLED`) are not thrown; read them from `result.errors`.\n */\nexport class StorefrontApiError extends Error {\n  /** Shopify `x-request-id` header, when available. Useful for support requests. */\n  readonly requestId?: string;\n  /** HTTP response status code, when the request reached the server. */\n  readonly status?: number;\n  /** The GraphQL query text. Only populated in development builds. */\n  readonly queryText?: string;\n  /** The variables sent with the request. Only populated in development builds. */\n  readonly variables?: Record<string, unknown>;\n\n  constructor(message: string, options?: StorefrontApiErrorOptions) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"StorefrontApiError\";\n    this.requestId = options?.requestId;\n    this.status = options?.status;\n\n    if (__DEV__) {\n      this.queryText = options?.queryText;\n      this.variables = options?.variables;\n    }\n  }\n\n  get [Symbol.toStringTag]() {\n    return this.name;\n  }\n\n  /** Serializes the error. `queryText`, `variables`, `cause`, and `stack` are always omitted. */\n  toJSON(): { name: string; message: string; requestId?: string; status?: number } {\n    return {\n      name: this.name,\n      message: this.message,\n      ...(this.requestId != null && { requestId: this.requestId }),\n      ...(this.status != null && { status: this.status }),\n    };\n  }\n}\n\n/**\n * Thrown when a Storefront API request exceeds the configured `defaultTimeoutInMs`.\n *\n * Subclass of {@link StorefrontApiError}, so catching `StorefrontApiError` also handles timeouts.\n * Aborts from the request context or a per-call `signal` are rethrown as-is, not wrapped.\n */\nexport class StorefrontTimeoutError extends StorefrontApiError {\n  /** The timeout threshold that was exceeded, in milliseconds. */\n  readonly timeoutInMs: number;\n\n  constructor(timeoutInMs: number, options?: Omit<StorefrontApiErrorOptions, \"cause\">) {\n    super(`Storefront API request timed out after ${timeoutInMs}ms`, options);\n    this.name = \"StorefrontTimeoutError\";\n    this.timeoutInMs = timeoutInMs;\n  }\n}\n"],"mappings":";;;;;;;;AAeA,IAAa,qBAAb,cAAwC,MAAM;;CAE5C,AAAS;;CAET,AAAS;;CAET,AAAS;;CAET,AAAS;CAET,YAAY,SAAiB,SAAqC;AAChE,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,YAAY,SAAS;AAC1B,OAAK,SAAS,SAAS;;CAQzB,KAAK,OAAO,eAAe;AACzB,SAAO,KAAK;;;CAId,SAAiF;AAC/E,SAAO;GACL,MAAM,KAAK;GACX,SAAS,KAAK;GACd,GAAI,KAAK,aAAa,QAAQ,EAAE,WAAW,KAAK,WAAW;GAC3D,GAAI,KAAK,UAAU,QAAQ,EAAE,QAAQ,KAAK,QAAQ;GACnD;;;;;;;;;AAUL,IAAa,yBAAb,cAA4C,mBAAmB;;CAE7D,AAAS;CAET,YAAY,aAAqB,SAAoD;AACnF,QAAM,0CAA0C,YAAY,KAAK,QAAQ;AACzE,OAAK,OAAO;AACZ,OAAK,cAAc"}

package/dist/client/types.d.mts

@@ -15,17 +15,27 @@ type ResultOfDoc<Doc> = Doc extends StorefrontQueryString<infer Result, infer _V
 type VariablesOfDoc<Doc> = Doc extends StorefrontQueryString<infer _Result, infer Variables, string> ? Variables : Doc extends TadaDocumentNode<any, any> ? VariablesOf<Doc> : never;
 type StorefrontApiResultOf<Doc extends DocLike> = ResultOf<Doc>;
 type StorefrontApiVariablesOf<Doc extends DocLike> = VariablesOf<Doc>;
+/**
+ * Minimal shape matching the GraphQL spec's error format, defined locally to
+ * avoid a runtime dependency on the `graphql` package.
+ *
+ * Present on the `errors` arm of {@link StorefrontGraphqlResult}.
+ */
 interface GraphQLFormattedError {
+  /** Human-readable error description. */
   readonly message: string;
+  /** Source locations in the query where the error originated. */
   readonly locations?: ReadonlyArray<{
     line: number;
     column: number;
   }>;
+  /** Response path to the field that triggered the error. */
   readonly path?: ReadonlyArray<string | number>;
+  /** Vendor extensions (e.g. Shopify error codes). */
   readonly extensions?: Record<string, unknown>;
 }
 type CommonOptions = {
-  storeDomain: string;
+  /** Shopify store domain — e.g. `"my-store.myshopify.com"`. Normalized internally. */storeDomain: string;
   /**
    * Identifies the Hydrogen storefront making Storefront API requests so Shopify can attribute
    * cart analytics to the correct storefront.
@@ -38,9 +48,9 @@ type CommonOptions = {
    * `apiVersion` so version routing stays explicit. Hydrogen's bundled gql.tada schema still
    * controls type inference, so queries against fields outside that schema need their own typing.
    */
-  apiVersion?: string;
-  defaultTimeoutInMs?: number;
-  cache?: CacheInstance;
+  apiVersion?: string; /** Per-request timeout in milliseconds. `0` disables the timeout. Defaults to 30,000 ms. */
+  defaultTimeoutInMs?: number; /** Shared cache instance that enables per-query caching via the `cache` option on `graphql()`. */
+  cache?: CacheInstance; /** Worker-style `waitUntil` to extend the request lifetime for background cache writes. */
   waitUntil?: WaitUntil;
 };
 type AnyFetch = typeof globalThis.fetch | ((...args: never[]) => Promise<Response>);
@@ -53,7 +63,9 @@ type AnyFetch = typeof globalThis.fetch | ((...args: never[]) => Promise<Respons
  * product tags, metaobjects, metafields, menus, and customers.
  */
 interface PublicClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  /** Custom fetch implementation. Falls back to `globalThis.fetch`. */
   fetch?: Fetch;
+  /** Public Storefront Access Token. Omit for tokenless access (limited fields). */
   publicStorefrontToken?: string | undefined;
 }
 /**
@@ -67,7 +79,9 @@ interface PublicClientOptions<Fetch extends AnyFetch | undefined = typeof global
  * product tags, metaobjects, metafields, menus, and customers.
  */
 interface PrivateClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  /** Custom fetch implementation. Falls back to `globalThis.fetch`. */
   fetch?: Fetch;
+  /** Private Storefront Access Token. Must never be exposed to browsers. */
   privateStorefrontToken: string;
 }
 /**
@@ -78,10 +92,20 @@ interface PrivateClientOptions<Fetch extends AnyFetch | undefined = typeof globa
  * shopper identity is available.
  */
 interface PrivateNoBuyerContextClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  /** Custom fetch implementation. Falls back to `globalThis.fetch`. */
   fetch?: Fetch;
+  /** Private Storefront Access Token. Must never be exposed to browsers. */
   privateStorefrontToken: string;
 }
+/** Union of all config shapes passed as the `config` field of {@link CreateStorefrontClientArgs}. */
 type StorefrontClientOptions = PublicClientOptions | PrivateClientOptions | PrivateNoBuyerContextClientOptions;
+/**
+ * Discriminated union accepted by `createStorefrontClient`.
+ *
+ * Discriminated on `type`: `"public"` requires a public (or no) token,
+ * `"private"` requires a private token plus a request context with `buyerIp`,
+ * and `"private_no_buyer_context"` requires a private token; `buyerIp` is not forwarded.
+ */
 type CreateStorefrontClientArgs<RequestContext extends ShopifyRequestContext = ShopifyRequestContext, Type extends ClientType = ClientType, CacheConfig extends CacheInstance | undefined = CacheInstance | undefined> = {
   type: "public" & Type;
   requestContext: RequestContext;
@@ -104,15 +128,38 @@ type CreateStorefrontClientArgs<RequestContext extends ShopifyRequestContext = S
 type AutoAddedVariableNames = "country" | "language";
 type UserVariables<Doc> = Omit<VariablesOfDoc<Doc>, AutoAddedVariableNames>;
 type HasNoRequiredKeys<T> = Record<string, never> extends T ? true : false;
+/** Per-call options common to every `storefront.graphql()` invocation. */
 type StorefrontGraphqlOptions = {
-  signal?: AbortSignal;
+  /** Abort signal forwarded to the underlying fetch. Combined with the request-context signal via `AbortSignal.any`. */signal?: AbortSignal;
 };
 type MergedOptions<Doc extends DocLike, Extra extends Record<string, unknown>> = Extra & StorefrontGraphqlOptions & (HasNoRequiredKeys<UserVariables<Doc>> extends true ? {
   variables?: UserVariables<Doc>;
 } : {
   variables: UserVariables<Doc>;
 });
+/**
+ * Rest-parameter tuple for `storefront.graphql()`.
+ *
+ * Resolves to `[options]` (required) when the document declares required
+ * variables, or `[options?]` (optional) when all variables are optional or
+ * auto-injected (e.g. `$country`, `$language`).
+ */
 type GqlRestParam<Doc extends DocLike, Extra extends Record<string, unknown> = {}> = HasNoRequiredKeys<MergedOptions<Doc, GraphqlExtraOptionsForDoc<Doc, Extra>>> extends true ? [options?: MergedOptions<Doc, GraphqlExtraOptionsForDoc<Doc, Extra>>] : [options: MergedOptions<Doc, GraphqlExtraOptionsForDoc<Doc, Extra>>];
+/**
+ * Discriminated union returned by `storefront.graphql()`.
+ *
+ * Discriminated on `errors`:
+ *
+ * - **No `errors`** — `data` is non-null and fully typed by the document.
+ * - **`errors` present** — `data` may be `null` (request-level error, or a non-null
+ *   field error that propagated to the root) or
+ *   partial (field-level error absorbed by a nullable ancestor). Always
+ *   inspect `errors` first.
+ *
+ * `Partial` is deliberately not used: a non-null `data` never has absent
+ * top-level keys — failures surface as `null` values already covered by the
+ * schema types.
+ */
 type StorefrontGraphqlResult<Doc extends DocLike> = {
   data: ResultOfDoc<Doc>;
   errors?: undefined;
@@ -122,24 +169,58 @@ type StorefrontGraphqlResult<Doc extends DocLike> = {
   errors: GraphQLFormattedError[];
   headers: Headers;
 };
+/** Base callable signature of `StorefrontClient.graphql` without per-client extra options. Accepts a `gql()` document or a plain string. */
 type StorefrontGraphql = <const Doc extends DocLike | string>(doc: Doc, ...options: GqlRestParam<ResolveDoc<Doc>>) => Promise<StorefrontGraphqlResult<ResolveDoc<Doc>>>;
 type ClientType = /** Public access token or tokenless access. Best for: browser requests. */"public" /** Private token with trusted buyer context. Best for: SSR. */ | "private" /** Private token without buyer context. Best for: background jobs, webhooks. */ | "private_no_buyer_context";
+/**
+ * A type-safe Storefront API client returned by `createStorefrontClient`.
+ *
+ * Call `client.graphql(doc, options?)` to execute a query or mutation against
+ * the Storefront API. The result is typed by the document you pass in.
+ */
 type StorefrontClient<Extra extends Record<string, unknown> = {}, Type extends ClientType = ClientType, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = {
-  type: Type;
+  /** Which client variant was created (`"public"`, `"private"`, or `"private_no_buyer_context"`). */type: Type; /** Resolved i18n config (country + language) used for automatic variable injection. */
   i18n: RequestContext["i18n"];
-  graphql: <const Doc extends DocLike | string>(doc: Doc, ...options: GqlRestParam<ResolveDoc<Doc>, Extra>) => Promise<StorefrontGraphqlResult<ResolveDoc<Doc>>>;
-  apiUrl: string;
-  storeUrl: string;
-  storefrontId?: string;
+  /**
+   * Execute a Storefront API GraphQL operation.
+   *
+   * Accepts a `gql()` document or a plain query string. Variables
+   * declared as `$country` / `$language` are auto-injected from the client's
+   * i18n config.
+   */
+  graphql: <const Doc extends DocLike | string>(doc: Doc, ...options: GqlRestParam<ResolveDoc<Doc>, Extra>) => Promise<StorefrontGraphqlResult<ResolveDoc<Doc>>>; /** Full Storefront API GraphQL endpoint URL. */
+  apiUrl: string; /** Normalized store URL (e.g. `"https://my-store.myshopify.com"`). */
+  storeUrl: string; /** Storefront identifier for cart analytics attribution, when provided. */
+  storefrontId?: string; /** The request context used for request-scoped headers, abort signals, and i18n. */
   requestContext: RequestContext;
 };
+/** A {@link StorefrontClient} narrowed to `type: "public"`. */
 type PublicStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = StorefrontClient<Extra, "public", RequestContext>;
+/** A {@link StorefrontClient} narrowed to `type: "private"`. Requires a request context with `buyerIp`. */
 type PrivateStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContextWithBuyerIp = ShopifyRequestContextWithBuyerIp> = StorefrontClient<Extra, "private", RequestContext>;
+/** Convenience alias: a private client whose request context is always the concrete `ShopifyRequestContextWithBuyerIp`. */
 type RequestScopedPrivateStorefrontClient<Extra extends Record<string, unknown> = {}> = PrivateStorefrontClient<Extra, ShopifyRequestContextWithBuyerIp>;
+/** A {@link StorefrontClient} narrowed to `type: "private_no_buyer_context"`. Best for background jobs and webhooks. */
 type PrivateNoBuyerContextStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = StorefrontClient<Extra, "private_no_buyer_context", RequestContext>;
+/**
+ * Namespace for extracting result and variable types from Storefront API documents.
+ *
+ * @example
+ * ```ts
+ * import { gql, type StorefrontApi } from "@shopify/hydrogen";
+ *
+ * const PRODUCT_QUERY = gql(`query Product($handle: String!) { product(handle: $handle) { title } }`);
+ *
+ * type Product = StorefrontApi.ResultOf<typeof PRODUCT_QUERY>;
+ * type Vars = StorefrontApi.VariablesOf<typeof PRODUCT_QUERY>;
+ * ```
+ */
 declare namespace StorefrontApi {
+  /** Extracts the typed result shape from a Storefront API document. */
   type ResultOf<Doc extends DocLike> = StorefrontApiResultOf<Doc>;
+  /** Extracts the typed variables shape from a Storefront API document. */
   type VariablesOf<Doc extends DocLike> = StorefrontApiVariablesOf<Doc>;
+  /** A typed Storefront API document — a `gql()` document or a `TadaDocumentNode`. */
   type DocumentNode = DocLike;
 }
 //#endregion

package/dist/core/analytics/cart-tracker.d.mts

@@ -2,6 +2,20 @@ import { CartStore } from "../cart/cart.mjs";
 
 //#region src/core/analytics/cart-tracker.d.ts
 type CartAnalyticsStore = Pick<CartStore, "getState" | "subscribe">;
+/**
+ * Subscribes to a cart store and publishes analytics events when the cart changes.
+ *
+ * Emits `cart_updated` whenever a settled cart's `updatedAt` changes, plus
+ * `product_added_to_cart` / `product_removed_from_cart` for each line that was
+ * added, removed, or changed quantity. Deduplicates on `updatedAt` with an
+ * in-memory cursor (within this subscription) and `localStorage` (across full
+ * page loads and tabs). A store filled from your own cart query must select
+ * `updatedAt`, or deduplication can't work.
+ *
+ * @throws {Error} If `window.Shopify.analytics` is not set (including on the server).
+ *   Render `ShopifyScripts` (or the `getShopifyScriptTags()` output) first.
+ * @returns An unsubscribe function that stops tracking.
+ */
 declare function trackCartAnalytics(store: CartAnalyticsStore): () => void;
 //#endregion
 export { trackCartAnalytics };

package/dist/core/analytics/cart-tracker.mjs

@@ -2,6 +2,20 @@ import { AnalyticsEvent } from "./events.mjs";
 import { flattenConnection } from "./utils/flatten-connection.mjs";
 
 //#region src/core/analytics/cart-tracker.ts
+/**
+* Subscribes to a cart store and publishes analytics events when the cart changes.
+*
+* Emits `cart_updated` whenever a settled cart's `updatedAt` changes, plus
+* `product_added_to_cart` / `product_removed_from_cart` for each line that was
+* added, removed, or changed quantity. Deduplicates on `updatedAt` with an
+* in-memory cursor (within this subscription) and `localStorage` (across full
+* page loads and tabs). A store filled from your own cart query must select
+* `updatedAt`, or deduplication can't work.
+*
+* @throws {Error} If `window.Shopify.analytics` is not set (including on the server).
+*   Render `ShopifyScripts` (or the `getShopifyScriptTags()` output) first.
+* @returns An unsubscribe function that stops tracking.
+*/
 function trackCartAnalytics(store) {
 	const analytics = getGlobalAnalytics();
 	const state = {
@@ -120,7 +134,7 @@ function hasPendingCartWork({ pending, revalidating }) {
 	return revalidating === true || hasPendingCost || pending.note || pending.attributes;
 }
 function getCartUpdatedAt(cart) {
-	return typeof cart.updatedAt === "string" ? cart.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
+	return cart.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
 }
 function syncShopifyCurrency(cart) {
 	if (typeof window === "undefined") return;

package/dist/core/analytics/cart-tracker.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cart-tracker.mjs","names":[],"sources":["../../../src/core/analytics/cart-tracker.ts"],"sourcesContent":["import type { CartStore } from \"../cart/cart\";\nimport type { CartData, CartState } from \"../cart/state\";\nimport { AnalyticsEvent } from \"./events\";\nimport type {\n  AnalyticsCart,\n  AnalyticsCartLine,\n  CartUpdatePayload,\n  StorefrontAnalytics,\n} from \"./types\";\nimport { flattenConnection } from \"./utils/flatten-connection\";\n\ntype CartTrackerAnalytics = Pick<StorefrontAnalytics, \"publish\" | \"getConfig\">;\ntype CartAnalyticsStore = Pick<CartStore, \"getState\" | \"subscribe\">;\n\ntype CartStorage = {\n  updatedAt: string;\n  id: string;\n};\n\ntype CartTrackerState = {\n  prevCart: AnalyticsCart | null;\n  lastEventId: string | null;\n};\n\nexport function trackCartAnalytics(store: CartAnalyticsStore): () => void {\n  const analytics = getGlobalAnalytics();\n  const state: CartTrackerState = {\n    prevCart: toAnalyticsCart(store.getState()),\n    lastEventId: null,\n  };\n\n  if (state.prevCart) syncShopifyCurrency(state.prevCart);\n\n  return store.subscribe((cartState) => {\n    const cart = toAnalyticsCart(cartState);\n    if (!cart) return;\n\n    trackCartChange(analytics, state, cart);\n  });\n}\n\nfunction trackCartChange(\n  analytics: CartTrackerAnalytics,\n  state: CartTrackerState,\n  cart: AnalyticsCart,\n): void {\n  if (!cart || !cart.updatedAt) return;\n\n  syncShopifyCurrency(cart);\n\n  if (cart.updatedAt === state.prevCart?.updatedAt) return;\n\n  let cartLastUpdatedAt: CartStorage | null;\n  try {\n    cartLastUpdatedAt = JSON.parse(localStorage.getItem(\"cartLastUpdatedAt\") || \"\");\n  } catch {\n    cartLastUpdatedAt = null;\n  }\n\n  if (cart.id === cartLastUpdatedAt?.id && cart.updatedAt === cartLastUpdatedAt?.updatedAt) {\n    state.prevCart = cart;\n    return;\n  }\n\n  if (cart.updatedAt === state.lastEventId) return;\n  state.lastEventId = cart.updatedAt;\n\n  const config = analytics.getConfig();\n  const payload: CartUpdatePayload = {\n    eventTimestamp: Date.now(),\n    cart,\n    prevCart: state.prevCart,\n    shop: config.shop,\n    customData: config.customData,\n  };\n\n  analytics.publish(AnalyticsEvent.CART_UPDATED, payload);\n\n  try {\n    localStorage.setItem(\n      \"cartLastUpdatedAt\",\n      JSON.stringify({ id: cart.id, updatedAt: cart.updatedAt }),\n    );\n  } catch {\n    // Safari private browsing or storage quota exceeded; analytics\n    // deduplication will rely on in-memory prevCart only for this session.\n  }\n\n  const previousCartLines = flattenConnection<AnalyticsCartLine>(state.prevCart?.lines);\n  const currentCartLines = flattenConnection<AnalyticsCartLine>(cart.lines);\n\n  previousCartLines.forEach((prevLine) => {\n    const matchedLineId = currentCartLines.filter((line) => prevLine.id === line.id);\n    if (matchedLineId.length === 1) {\n      const matchedLine = matchedLineId[0];\n      if (prevLine.quantity < matchedLine.quantity) {\n        analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {\n          ...payload,\n          prevLine,\n          currentLine: matchedLine,\n        });\n      } else if (prevLine.quantity > matchedLine.quantity) {\n        analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {\n          ...payload,\n          prevLine,\n          currentLine: matchedLine,\n        });\n      }\n    } else {\n      analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {\n        ...payload,\n        prevLine,\n      });\n    }\n  });\n\n  currentCartLines.forEach((line) => {\n    const matchedLineId = previousCartLines.filter((previousLine) => line.id === previousLine.id);\n    if (!matchedLineId || matchedLineId.length === 0) {\n      analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {\n        ...payload,\n        currentLine: line,\n      });\n    }\n  });\n\n  state.prevCart = cart;\n}\n\nfunction getGlobalAnalytics(): CartTrackerAnalytics {\n  const analytics = typeof window !== \"undefined\" ? window.Shopify?.analytics : undefined;\n  if (!analytics) {\n    throw new Error(\n      \"Shopify analytics bus is not available. Render ShopifyScripts before calling trackCartAnalytics().\",\n    );\n  }\n\n  return analytics;\n}\n\nfunction toAnalyticsCart(state: CartState): AnalyticsCart | null {\n  const cart = state.data;\n  if (!cart.id || hasPendingCartWork(state)) return null;\n\n  return {\n    id: cart.id,\n    updatedAt: getCartUpdatedAt(cart),\n    cost: cart.cost,\n    lines: {\n      nodes: cart.lines.nodes.flatMap((line): AnalyticsCartLine[] => {\n        const merchandise = line.merchandise;\n        if (!merchandise) return [];\n\n        const product = merchandise.product;\n        const productId = typeof product.id === \"string\" ? product.id : \"\";\n        const vendor = typeof product.vendor === \"string\" ? product.vendor : \"\";\n        const productType =\n          typeof product.productType === \"string\" ? product.productType : undefined;\n\n        return [\n          {\n            id: line.id,\n            quantity: line.quantity,\n            merchandise: {\n              id: merchandise.id,\n              title: merchandise.title ?? product.title,\n              price: line.cost.amountPerQuantity,\n              sku: typeof merchandise.sku === \"string\" ? merchandise.sku : null,\n              product: {\n                id: productId,\n                title: product.title,\n                vendor,\n                productType,\n                handle: product.handle,\n              },\n            },\n          },\n        ];\n      }),\n    },\n  };\n}\n\nfunction hasPendingCartWork({ pending, revalidating }: CartState): boolean {\n  const hasPendingCost = pending.cost ?? (pending.lines.size > 0 || pending.discountCodes.size > 0);\n  return revalidating === true || hasPendingCost || pending.note || pending.attributes;\n}\n\nfunction getCartUpdatedAt(cart: CartData): string {\n  return typeof cart.updatedAt === \"string\" ? cart.updatedAt : new Date().toISOString();\n}\n\nfunction syncShopifyCurrency(cart: AnalyticsCart): void {\n  if (typeof window === \"undefined\") return;\n\n  const currencyCode = getCartCurrencyCode(cart);\n  if (!currencyCode) return;\n\n  const normalizedCurrencyCode = currencyCode.toUpperCase();\n  const shopifyWindow: { Shopify?: { currency?: { active: string } } } = window;\n  const shopify = (shopifyWindow.Shopify ??= {});\n  if (shopify.currency?.active === normalizedCurrencyCode) return;\n\n  shopify.currency = { active: normalizedCurrencyCode };\n}\n\nfunction getCartCurrencyCode(cart: AnalyticsCart): string | undefined {\n  return (\n    nonEmptyCurrencyCode(cart.cost?.totalAmount?.currencyCode) ??\n    nonEmptyCurrencyCode(cart.cost?.subtotalAmount?.currencyCode) ??\n    flattenConnection<AnalyticsCartLine>(cart.lines).find(\n      (line) => line.merchandise.price.currencyCode,\n    )?.merchandise.price.currencyCode\n  );\n}\n\nfunction nonEmptyCurrencyCode(currencyCode: string | undefined): string | undefined {\n  return currencyCode || undefined;\n}\n"],"mappings":"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"}
+{"version":3,"file":"cart-tracker.mjs","names":[],"sources":["../../../src/core/analytics/cart-tracker.ts"],"sourcesContent":["import type { CartStore } from \"../cart/cart\";\nimport type { CartData, CartState } from \"../cart/state\";\nimport { AnalyticsEvent } from \"./events\";\nimport type {\n  AnalyticsCart,\n  AnalyticsCartLine,\n  CartUpdatePayload,\n  StorefrontAnalytics,\n} from \"./types\";\nimport { flattenConnection } from \"./utils/flatten-connection\";\n\ntype CartTrackerAnalytics = Pick<StorefrontAnalytics, \"publish\" | \"getConfig\">;\ntype CartAnalyticsStore = Pick<CartStore, \"getState\" | \"subscribe\">;\n\ntype CartStorage = {\n  updatedAt: string;\n  id: string;\n};\n\ntype CartTrackerState = {\n  prevCart: AnalyticsCart | null;\n  lastEventId: string | null;\n};\n\n/**\n * Subscribes to a cart store and publishes analytics events when the cart changes.\n *\n * Emits `cart_updated` whenever a settled cart's `updatedAt` changes, plus\n * `product_added_to_cart` / `product_removed_from_cart` for each line that was\n * added, removed, or changed quantity. Deduplicates on `updatedAt` with an\n * in-memory cursor (within this subscription) and `localStorage` (across full\n * page loads and tabs). A store filled from your own cart query must select\n * `updatedAt`, or deduplication can't work.\n *\n * @throws {Error} If `window.Shopify.analytics` is not set (including on the server).\n *   Render `ShopifyScripts` (or the `getShopifyScriptTags()` output) first.\n * @returns An unsubscribe function that stops tracking.\n */\nexport function trackCartAnalytics(store: CartAnalyticsStore): () => void {\n  const analytics = getGlobalAnalytics();\n  const state: CartTrackerState = {\n    prevCart: toAnalyticsCart(store.getState()),\n    lastEventId: null,\n  };\n\n  if (state.prevCart) syncShopifyCurrency(state.prevCart);\n\n  return store.subscribe((cartState) => {\n    const cart = toAnalyticsCart(cartState);\n    if (!cart) return;\n\n    trackCartChange(analytics, state, cart);\n  });\n}\n\nfunction trackCartChange(\n  analytics: CartTrackerAnalytics,\n  state: CartTrackerState,\n  cart: AnalyticsCart,\n): void {\n  if (!cart || !cart.updatedAt) return;\n\n  syncShopifyCurrency(cart);\n\n  if (cart.updatedAt === state.prevCart?.updatedAt) return;\n\n  let cartLastUpdatedAt: CartStorage | null;\n  try {\n    cartLastUpdatedAt = JSON.parse(localStorage.getItem(\"cartLastUpdatedAt\") || \"\");\n  } catch {\n    cartLastUpdatedAt = null;\n  }\n\n  if (cart.id === cartLastUpdatedAt?.id && cart.updatedAt === cartLastUpdatedAt?.updatedAt) {\n    state.prevCart = cart;\n    return;\n  }\n\n  if (cart.updatedAt === state.lastEventId) return;\n  state.lastEventId = cart.updatedAt;\n\n  const config = analytics.getConfig();\n  const payload: CartUpdatePayload = {\n    eventTimestamp: Date.now(),\n    cart,\n    prevCart: state.prevCart,\n    shop: config.shop,\n    customData: config.customData,\n  };\n\n  analytics.publish(AnalyticsEvent.CART_UPDATED, payload);\n\n  try {\n    localStorage.setItem(\n      \"cartLastUpdatedAt\",\n      JSON.stringify({ id: cart.id, updatedAt: cart.updatedAt }),\n    );\n  } catch {\n    // Safari private browsing or storage quota exceeded; analytics\n    // deduplication will rely on in-memory prevCart only for this session.\n  }\n\n  const previousCartLines = flattenConnection<AnalyticsCartLine>(state.prevCart?.lines);\n  const currentCartLines = flattenConnection<AnalyticsCartLine>(cart.lines);\n\n  previousCartLines.forEach((prevLine) => {\n    const matchedLineId = currentCartLines.filter((line) => prevLine.id === line.id);\n    if (matchedLineId.length === 1) {\n      const matchedLine = matchedLineId[0];\n      if (prevLine.quantity < matchedLine.quantity) {\n        analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {\n          ...payload,\n          prevLine,\n          currentLine: matchedLine,\n        });\n      } else if (prevLine.quantity > matchedLine.quantity) {\n        analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {\n          ...payload,\n          prevLine,\n          currentLine: matchedLine,\n        });\n      }\n    } else {\n      analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {\n        ...payload,\n        prevLine,\n      });\n    }\n  });\n\n  currentCartLines.forEach((line) => {\n    const matchedLineId = previousCartLines.filter((previousLine) => line.id === previousLine.id);\n    if (!matchedLineId || matchedLineId.length === 0) {\n      analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {\n        ...payload,\n        currentLine: line,\n      });\n    }\n  });\n\n  state.prevCart = cart;\n}\n\nfunction getGlobalAnalytics(): CartTrackerAnalytics {\n  const analytics = typeof window !== \"undefined\" ? window.Shopify?.analytics : undefined;\n  if (!analytics) {\n    throw new Error(\n      \"Shopify analytics bus is not available. Render ShopifyScripts before calling trackCartAnalytics().\",\n    );\n  }\n\n  return analytics;\n}\n\nfunction toAnalyticsCart(state: CartState): AnalyticsCart | null {\n  const cart = state.data;\n  if (!cart.id || hasPendingCartWork(state)) return null;\n\n  return {\n    id: cart.id,\n    updatedAt: getCartUpdatedAt(cart),\n    cost: cart.cost,\n    lines: {\n      nodes: cart.lines.nodes.flatMap((line): AnalyticsCartLine[] => {\n        const merchandise = line.merchandise;\n        if (!merchandise) return [];\n\n        const product = merchandise.product;\n        const productId = typeof product.id === \"string\" ? product.id : \"\";\n        const vendor = typeof product.vendor === \"string\" ? product.vendor : \"\";\n        const productType =\n          typeof product.productType === \"string\" ? product.productType : undefined;\n\n        return [\n          {\n            id: line.id,\n            quantity: line.quantity,\n            merchandise: {\n              id: merchandise.id,\n              title: merchandise.title ?? product.title,\n              price: line.cost.amountPerQuantity,\n              sku: typeof merchandise.sku === \"string\" ? merchandise.sku : null,\n              product: {\n                id: productId,\n                title: product.title,\n                vendor,\n                productType,\n                handle: product.handle,\n              },\n            },\n          },\n        ];\n      }),\n    },\n  };\n}\n\nfunction hasPendingCartWork({ pending, revalidating }: CartState): boolean {\n  const hasPendingCost = pending.cost ?? (pending.lines.size > 0 || pending.discountCodes.size > 0);\n  return revalidating === true || hasPendingCost || pending.note || pending.attributes;\n}\n\nfunction getCartUpdatedAt(cart: CartData): string {\n  return cart.updatedAt ?? new Date().toISOString();\n}\n\nfunction syncShopifyCurrency(cart: AnalyticsCart): void {\n  if (typeof window === \"undefined\") return;\n\n  const currencyCode = getCartCurrencyCode(cart);\n  if (!currencyCode) return;\n\n  const normalizedCurrencyCode = currencyCode.toUpperCase();\n  const shopifyWindow: { Shopify?: { currency?: { active: string } } } = window;\n  const shopify = (shopifyWindow.Shopify ??= {});\n  if (shopify.currency?.active === normalizedCurrencyCode) return;\n\n  shopify.currency = { active: normalizedCurrencyCode };\n}\n\nfunction getCartCurrencyCode(cart: AnalyticsCart): string | undefined {\n  return (\n    nonEmptyCurrencyCode(cart.cost?.totalAmount?.currencyCode) ??\n    nonEmptyCurrencyCode(cart.cost?.subtotalAmount?.currencyCode) ??\n    flattenConnection<AnalyticsCartLine>(cart.lines).find(\n      (line) => line.merchandise.price.currencyCode,\n    )?.merchandise.price.currencyCode\n  );\n}\n\nfunction nonEmptyCurrencyCode(currencyCode: string | undefined): string | undefined {\n  return currencyCode || undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAsCA,SAAgB,mBAAmB,OAAuC;CACxE,MAAM,YAAY,oBAAoB;CACtC,MAAM,QAA0B;EAC9B,UAAU,gBAAgB,MAAM,UAAU,CAAC;EAC3C,aAAa;EACd;AAED,KAAI,MAAM,SAAU,qBAAoB,MAAM,SAAS;AAEvD,QAAO,MAAM,WAAW,cAAc;EACpC,MAAM,OAAO,gBAAgB,UAAU;AACvC,MAAI,CAAC,KAAM;AAEX,kBAAgB,WAAW,OAAO,KAAK;GACvC;;AAGJ,SAAS,gBACP,WACA,OACA,MACM;AACN,KAAI,CAAC,QAAQ,CAAC,KAAK,UAAW;AAE9B,qBAAoB,KAAK;AAEzB,KAAI,KAAK,cAAc,MAAM,UAAU,UAAW;CAElD,IAAI;AACJ,KAAI;AACF,sBAAoB,KAAK,MAAM,aAAa,QAAQ,oBAAoB,IAAI,GAAG;SACzE;AACN,sBAAoB;;AAGtB,KAAI,KAAK,OAAO,mBAAmB,MAAM,KAAK,cAAc,mBAAmB,WAAW;AACxF,QAAM,WAAW;AACjB;;AAGF,KAAI,KAAK,cAAc,MAAM,YAAa;AAC1C,OAAM,cAAc,KAAK;CAEzB,MAAM,SAAS,UAAU,WAAW;CACpC,MAAM,UAA6B;EACjC,gBAAgB,KAAK,KAAK;EAC1B;EACA,UAAU,MAAM;EAChB,MAAM,OAAO;EACb,YAAY,OAAO;EACpB;AAED,WAAU,QAAQ,eAAe,cAAc,QAAQ;AAEvD,KAAI;AACF,eAAa,QACX,qBACA,KAAK,UAAU;GAAE,IAAI,KAAK;GAAI,WAAW,KAAK;GAAW,CAAC,CAC3D;SACK;CAKR,MAAM,oBAAoB,kBAAqC,MAAM,UAAU,MAAM;CACrF,MAAM,mBAAmB,kBAAqC,KAAK,MAAM;AAEzE,mBAAkB,SAAS,aAAa;EACtC,MAAM,gBAAgB,iBAAiB,QAAQ,SAAS,SAAS,OAAO,KAAK,GAAG;AAChF,MAAI,cAAc,WAAW,GAAG;GAC9B,MAAM,cAAc,cAAc;AAClC,OAAI,SAAS,WAAW,YAAY,SAClC,WAAU,QAAQ,eAAe,qBAAqB;IACpD,GAAG;IACH;IACA,aAAa;IACd,CAAC;YACO,SAAS,WAAW,YAAY,SACzC,WAAU,QAAQ,eAAe,2BAA2B;IAC1D,GAAG;IACH;IACA,aAAa;IACd,CAAC;QAGJ,WAAU,QAAQ,eAAe,2BAA2B;GAC1D,GAAG;GACH;GACD,CAAC;GAEJ;AAEF,kBAAiB,SAAS,SAAS;EACjC,MAAM,gBAAgB,kBAAkB,QAAQ,iBAAiB,KAAK,OAAO,aAAa,GAAG;AAC7F,MAAI,CAAC,iBAAiB,cAAc,WAAW,EAC7C,WAAU,QAAQ,eAAe,qBAAqB;GACpD,GAAG;GACH,aAAa;GACd,CAAC;GAEJ;AAEF,OAAM,WAAW;;AAGnB,SAAS,qBAA2C;CAClD,MAAM,YAAY,OAAO,WAAW,cAAc,OAAO,SAAS,YAAY;AAC9E,KAAI,CAAC,UACH,OAAM,IAAI,MACR,qGACD;AAGH,QAAO;;AAGT,SAAS,gBAAgB,OAAwC;CAC/D,MAAM,OAAO,MAAM;AACnB,KAAI,CAAC,KAAK,MAAM,mBAAmB,MAAM,CAAE,QAAO;AAElD,QAAO;EACL,IAAI,KAAK;EACT,WAAW,iBAAiB,KAAK;EACjC,MAAM,KAAK;EACX,OAAO,EACL,OAAO,KAAK,MAAM,MAAM,SAAS,SAA8B;GAC7D,MAAM,cAAc,KAAK;AACzB,OAAI,CAAC,YAAa,QAAO,EAAE;GAE3B,MAAM,UAAU,YAAY;GAC5B,MAAM,YAAY,OAAO,QAAQ,OAAO,WAAW,QAAQ,KAAK;GAChE,MAAM,SAAS,OAAO,QAAQ,WAAW,WAAW,QAAQ,SAAS;GACrE,MAAM,cACJ,OAAO,QAAQ,gBAAgB,WAAW,QAAQ,cAAc;AAElE,UAAO,CACL;IACE,IAAI,KAAK;IACT,UAAU,KAAK;IACf,aAAa;KACX,IAAI,YAAY;KAChB,OAAO,YAAY,SAAS,QAAQ;KACpC,OAAO,KAAK,KAAK;KACjB,KAAK,OAAO,YAAY,QAAQ,WAAW,YAAY,MAAM;KAC7D,SAAS;MACP,IAAI;MACJ,OAAO,QAAQ;MACf;MACA;MACA,QAAQ,QAAQ;MACjB;KACF;IACF,CACF;IACD,EACH;EACF;;AAGH,SAAS,mBAAmB,EAAE,SAAS,gBAAoC;CACzE,MAAM,iBAAiB,QAAQ,SAAS,QAAQ,MAAM,OAAO,KAAK,QAAQ,cAAc,OAAO;AAC/F,QAAO,iBAAiB,QAAQ,kBAAkB,QAAQ,QAAQ,QAAQ;;AAG5E,SAAS,iBAAiB,MAAwB;AAChD,QAAO,KAAK,8BAAa,IAAI,MAAM,EAAC,aAAa;;AAGnD,SAAS,oBAAoB,MAA2B;AACtD,KAAI,OAAO,WAAW,YAAa;CAEnC,MAAM,eAAe,oBAAoB,KAAK;AAC9C,KAAI,CAAC,aAAc;CAEnB,MAAM,yBAAyB,aAAa,aAAa;CACzD,MAAM,gBAAiE;CACvE,MAAM,UAAW,cAAc,YAAY,EAAE;AAC7C,KAAI,QAAQ,UAAU,WAAW,uBAAwB;AAEzD,SAAQ,WAAW,EAAE,QAAQ,wBAAwB;;AAGvD,SAAS,oBAAoB,MAAyC;AACpE,QACE,qBAAqB,KAAK,MAAM,aAAa,aAAa,IAC1D,qBAAqB,KAAK,MAAM,gBAAgB,aAAa,IAC7D,kBAAqC,KAAK,MAAM,CAAC,MAC9C,SAAS,KAAK,YAAY,MAAM,aAClC,EAAE,YAAY,MAAM;;AAIzB,SAAS,qBAAqB,cAAsD;AAClF,QAAO,gBAAgB"}

package/dist/core/analytics/custom-consent.mjs

@@ -0,0 +1,12 @@
+//#region src/core/analytics/custom-consent.ts
+const CUSTOM_CONSENT = Symbol.for("shopify.hydrogen.custom-consent");
+function initializeCustomConsent(setup) {
+	if (typeof window === "undefined") return;
+	const initialize = (window.Shopify?.analytics)?.[CUSTOM_CONSENT];
+	if (!initialize) throw new Error("Custom consent requires Shopify script tags rendered with consent.mode = \"custom-banner\".");
+	initialize(setup);
+}
+
+//#endregion
+export { initializeCustomConsent };
+//# sourceMappingURL=custom-consent.mjs.map

package/dist/core/analytics/custom-consent.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-consent.mjs","names":[],"sources":["../../../src/core/analytics/custom-consent.ts"],"sourcesContent":["import type { ConsentSetup, StorefrontAnalytics } from \"./types\";\n\n// The inline bus and hydrated app are separate bundles. This private hook passes\n// the app's setup callback to the bus without serializing it into HTML.\nexport const CUSTOM_CONSENT = Symbol.for(\"shopify.hydrogen.custom-consent\");\n\ntype AnalyticsWithCustomConsent = StorefrontAnalytics & {\n  [CUSTOM_CONSENT]?: (setup: ConsentSetup) => void;\n};\n\nexport function initializeCustomConsent(setup: ConsentSetup): void {\n  if (typeof window === \"undefined\") return;\n\n  const analytics: AnalyticsWithCustomConsent | undefined = window.Shopify?.analytics;\n  const initialize = analytics?.[CUSTOM_CONSENT];\n  if (!initialize) {\n    throw new Error(\n      'Custom consent requires Shopify script tags rendered with consent.mode = \"custom-banner\".',\n    );\n  }\n  initialize(setup);\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,OAAO,IAAI,kCAAkC;AAM3E,SAAgB,wBAAwB,OAA2B;AACjE,KAAI,OAAO,WAAW,YAAa;CAGnC,MAAM,cADoD,OAAO,SAAS,aAC3C;AAC/B,KAAI,CAAC,WACH,OAAM,IAAI,MACR,8FACD;AAEH,YAAW,MAAM"}

package/dist/core/analytics/events.d.mts

@@ -1,4 +1,11 @@
 //#region src/core/analytics/events.d.ts
+/**
+ * Canonical event names for the Hydrogen analytics bus.
+ *
+ * Use these as the `event` argument to `publish()` and a destination's `subscribe()`. Raw string
+ * literals are type-checked and narrow the payload the same way; the constants add
+ * autocomplete and a single place to rename.
+ */
 declare const AnalyticsEvent: {
   PAGE_VIEWED: "page_viewed";
   PRODUCT_VIEWED: "product_viewed";

package/dist/core/analytics/events.mjs

@@ -1,4 +1,11 @@
 //#region src/core/analytics/events.ts
+/**
+* Canonical event names for the Hydrogen analytics bus.
+*
+* Use these as the `event` argument to `publish()` and a destination's `subscribe()`. Raw string
+* literals are type-checked and narrow the payload the same way; the constants add
+* autocomplete and a single place to rename.
+*/
 const AnalyticsEvent = {
 	PAGE_VIEWED: "page_viewed",
 	PRODUCT_VIEWED: "product_viewed",

package/dist/core/analytics/events.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.mjs","names":[],"sources":["../../../src/core/analytics/events.ts"],"sourcesContent":["export const AnalyticsEvent = {\n  PAGE_VIEWED: \"page_viewed\" as const,\n  PRODUCT_VIEWED: \"product_viewed\" as const,\n  COLLECTION_VIEWED: \"collection_viewed\" as const,\n  CART_VIEWED: \"cart_viewed\" as const,\n  SEARCH_VIEWED: \"search_viewed\" as const,\n\n  CART_UPDATED: \"cart_updated\" as const,\n  PRODUCT_ADD_TO_CART: \"product_added_to_cart\" as const,\n  PRODUCT_REMOVED_FROM_CART: \"product_removed_from_cart\" as const,\n};\n\nexport type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];\n"],"mappings":";AAAA,MAAa,iBAAiB;CAC5B,aAAa;CACb,gBAAgB;CAChB,mBAAmB;CACnB,aAAa;CACb,eAAe;CAEf,cAAc;CACd,qBAAqB;CACrB,2BAA2B;CAC5B"}
+{"version":3,"file":"events.mjs","names":[],"sources":["../../../src/core/analytics/events.ts"],"sourcesContent":["/**\n * Canonical event names for the Hydrogen analytics bus.\n *\n * Use these as the `event` argument to `publish()` and a destination's `subscribe()`. Raw string\n * literals are type-checked and narrow the payload the same way; the constants add\n * autocomplete and a single place to rename.\n */\nexport const AnalyticsEvent = {\n  PAGE_VIEWED: \"page_viewed\" as const,\n  PRODUCT_VIEWED: \"product_viewed\" as const,\n  COLLECTION_VIEWED: \"collection_viewed\" as const,\n  CART_VIEWED: \"cart_viewed\" as const,\n  SEARCH_VIEWED: \"search_viewed\" as const,\n\n  CART_UPDATED: \"cart_updated\" as const,\n  PRODUCT_ADD_TO_CART: \"product_added_to_cart\" as const,\n  PRODUCT_REMOVED_FROM_CART: \"product_removed_from_cart\" as const,\n};\n\nexport type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];\n"],"mappings":";;;;;;;;AAOA,MAAa,iBAAiB;CAC5B,aAAa;CACb,gBAAgB;CAChB,mBAAmB;CACnB,aAAa;CACb,eAAe;CAEf,cAAc;CACd,qBAAqB;CACrB,2BAA2B;CAC5B"}

package/dist/core/analytics/index.d.mts

@@ -1,3 +1,3 @@
 import { trackCartAnalytics } from "./cart-tracker.mjs";
 import { AnalyticsEvent, AnalyticsEventName } from "./events.mjs";
-import { AnalyticsCart, AnalyticsCartLine, AnalyticsEventMap, CartLineUpdatePayload, CartUpdatePayload, CartViewPayload, CollectionViewPayload, ConsentConfig, EventPayloads, OtherData, PageViewPayload, PayloadFor, ProductPayload, ProductViewPayload, SearchViewPayload, ShopAnalytics, StorefrontAnalytics, StorefrontAnalyticsConfig, StorefrontAnalyticsDestination, StorefrontAnalyticsDestinationSetupContext } from "./types.mjs";
+import { AnalyticsCart, AnalyticsCartLine, AnalyticsEventMap, AnalyticsTrackingValues, CartLineUpdatePayload, CartUpdatePayload, CartViewPayload, CollectionViewPayload, ConsentConfig, ConsentPreferences, ConsentSetup, OtherData, PageViewPayload, PayloadFor, ProductPayload, ProductViewPayload, SearchViewPayload, ShopAnalytics, StorefrontAnalytics, StorefrontAnalyticsConfig, StorefrontAnalyticsDestination, StorefrontAnalyticsDestinationEventContext, StorefrontAnalyticsDestinationSetupContext } from "./types.mjs";