@shopify/hydrogen 2026.10.0-preview.3 → 2026.10.0-preview.5

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 * Signals that a Storefront API request failed. The client throws the error for an HTTP error\n * status, a network failure, or a response body that isn't a JSON object.\n *\n * GraphQL errors, including `THROTTLED`, don't throw. Read GraphQL errors from the result's\n * `errors` field.\n *\n * When the request context's signal or the call's `signal` aborts before the call, the client\n * throws the abort reason and sends no request. An `AbortError` during the request reaches your\n * code unchanged. Other abort reasons during the request throw a `StorefrontApiError`.\n *\n * @publicDocs\n */\nexport class StorefrontApiError extends Error {\n  /** The `x-request-id` header of the Storefront API response, when the response has one. Include the ID in support requests. */\n  readonly requestId?: string;\n  /** The HTTP status code of the response, when the request reached the server. */\n  readonly status?: number;\n  /** The GraphQL query that failed. Hydrogen sets the value only in development builds. */\n  readonly queryText?: string;\n  /** The variables that the client sent with the request. Hydrogen sets the value only in development builds. */\n  readonly variables?: Record<string, unknown>;\n\n  /** `StorefrontApiError`. `StorefrontTimeoutError` sets its own class name. */\n  declare name: string;\n  /** Describes the failure, such as the HTTP status that the API returned. */\n  declare message: string;\n  /** The stack trace, when the JavaScript runtime records one. */\n  declare stack?: string;\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  /** Makes `Object.prototype.toString` report the error name, such as `[object StorefrontApiError]`. */\n  get [Symbol.toStringTag]() {\n    return this.name;\n  }\n\n  /** Returns the error name, message, request ID, and status for logging. The output leaves out the query text, variables, cause, and stack. */\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 * Signals that a Storefront API request ran longer than the client's `defaultTimeoutInMs` setting.\n * Aborts from the request context or the call's `signal` throw other errors.\n *\n * `StorefrontTimeoutError` extends `StorefrontApiError`. Check for `StorefrontTimeoutError` first when\n * you handle both errors.\n *\n * @publicDocs\n */\nexport class StorefrontTimeoutError extends StorefrontApiError {\n  /** The timeout that the request exceeded, in milliseconds. */\n  readonly timeoutInMs: number;\n\n  /** Always `StorefrontTimeoutError`. */\n  declare name: string;\n  /** States the timeout, such as `\"Storefront API request timed out after 30000ms\"`. */\n  declare message: string;\n  /** The stack trace, when the JavaScript runtime records one. */\n  declare stack?: string;\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":";;;;;;;;;;;;;;AAqBA,IAAa,qBAAb,cAAwC,MAAM;;CAE5C,AAAS;;CAET,AAAS;;CAET,AAAS;;CAET,AAAS;CAST,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;;;CASzB,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;;;;;;;;;;;;AAaL,IAAa,yBAAb,cAA4C,mBAAmB;;CAE7D,AAAS;CAST,YAAY,aAAqB,SAAoD;AACnF,QAAM,0CAA0C,YAAY,KAAK,QAAQ;AACzE,OAAK,OAAO;AACZ,OAAK,cAAc"}

package/dist/client/types.d.mts

@@ -5,83 +5,122 @@ import { AnyStorefrontQueryString, SourceOf, StorefrontQueryString } from "../gr
 import { ResultOf, TadaDocumentNode, VariablesOf } from "gql.tada";
 
 //#region src/client/types.d.ts
+/** A document that the client's GraphQL method accepts, from `gql` or from `gql`.tada. */
 type DocLike = TadaDocumentNode<any, any> | AnyStorefrontQueryString;
+/** The typed document that Hydrogen infers from a plain query string. */
 type InferredDoc<T extends string> = StorefrontQueryString<InferResult<T>, InferVariables<T>, T>;
+/** The typed document for a GraphQL call. Hydrogen infers the types when you pass a plain query string. */
 type ResolveDoc<D> = D extends DocLike ? D : D extends string ? InferredDoc<D> : never;
+/** The query text of a document as a string literal type. A plain string resolves to itself. */
 type SourceText<Doc> = [SourceOf<Doc>] extends [never] ? Doc extends string ? Doc : never : SourceOf<Doc>;
+/** The operation kind of a document, such as `query`. Resolves to `unknown` when the query text isn't a string literal type. */
 type OperationKindOfDoc<Doc> = [SourceText<Doc>] extends [never] ? "unknown" : string extends SourceText<Doc> ? "unknown" : InferOperationKind<SourceText<Doc>>;
+/** Offers the `cache` option only for documents that TypeScript recognizes as queries. */
 type GraphqlExtraOptionsForDoc<Doc, Extra extends Record<string, unknown>> = OperationKindOfDoc<Doc> extends "query" ? Extra : Omit<Extra, "cache">;
+/** The result type of a `gql` document or a `gql`.tada document node. */
 type ResultOfDoc<Doc> = Doc extends StorefrontQueryString<infer Result, infer _Variables, string> ? Result : Doc extends TadaDocumentNode<any, any> ? ResultOf<Doc> : never;
 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>;
+/**
+ * A GraphQL error from the Storefront API. The result of a GraphQL call lists GraphQL errors
+ * in its `errors` field.
+ */
 interface GraphQLFormattedError {
+  /** The error message. */
   readonly message: string;
+  /** The lines and columns in the query where the error occurs. */
   readonly locations?: ReadonlyArray<{
     line: number;
     column: number;
   }>;
+  /** The path to the response field that failed. */
   readonly path?: ReadonlyArray<string | number>;
+  /** Extra details that the Storefront API adds to the error. */
   readonly extensions?: Record<string, unknown>;
 }
 type CommonOptions = {
+  /**
+   * Your store's domain, such as `my-store.myshopify.com`. Hydrogen adds `https://` when the
+   * domain has no protocol, and removes trailing slashes. `createStorefrontClient` throws an error
+   * for an empty domain.
+   */
   storeDomain: string;
   /**
-   * Identifies the Hydrogen storefront making Storefront API requests so Shopify can attribute
-   * cart analytics to the correct storefront.
+   * Your Hydrogen storefront's ID. The client sends the ID in the `Shopify-Storefront-Id` header
+   * of every request.
    */
   storefrontId?: string;
   /**
-   * Storefront API version used in the GraphQL endpoint path (`/api/<version>/graphql.json`).
-   * Defaults to the version baked into the package. To send some queries to a different endpoint
-   * version (e.g. `unstable`), create a second `createStorefrontClient` instance with that
-   * `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.
+   * The Storefront API version that the client queries. Defaults to the version that Hydrogen
+   * bundles. To send some queries to another version, such as `unstable`, create a second client
+   * with that version. Type inference always uses Hydrogen's bundled schema. Write your own types
+   * for fields outside the bundled schema.
    */
   apiVersion?: string;
+  /**
+   * How long a request can run before the client throws a `StorefrontTimeoutError`, in
+   * milliseconds. Defaults to `30000`. Set `0` to turn off the timeout. Stale-while-revalidate
+   * refreshes use the same timeout, or 30,000 when the timeout is `0`. `createStorefrontClient`
+   * throws an error for a negative value.
+   */
   defaultTimeoutInMs?: number;
-  cache?: CacheInstance;
+  /**
+   * The cache that stores query results. The client caches only queries that pass a `cache`
+   * strategy. The client never caches mutations or results with GraphQL errors.
+   */
+  cache?: CacheInstance; /** Keeps the runtime alive while the client writes to the cache in the background, such as a worker's `waitUntil` function. Without the function, each cached query waits for its cache write before it resolves. */
   waitUntil?: WaitUntil;
 };
+/** A fetch function, or any function with a compatible signature that resolves to a `Response`. */
 type AnyFetch = typeof globalThis.fetch | ((...args: never[]) => Promise<Response>);
 /**
- * Public client — uses a public Storefront Access Token, or tokenless access
- * when `publicStorefrontToken` is omitted.
+ * Options for a public client, which runs in the browser or a mobile app. Pass a public access
+ * token, or omit the token for tokenless access.
  *
- * Best for: browser or mobile requests where the token is safe to expose.
- * Token-based access is required for some Storefront API fields, including
- * product tags, metaobjects, metafields, menus, and customers.
+ * Tokenless access can't read some Storefront API fields, including product tags, metaobjects,
+ * metafields, menus, and customers.
  */
 interface PublicClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  /** The fetch function that the client calls. Defaults to `globalThis.fetch`. `createStorefrontClient` throws an error when neither exists. */
   fetch?: Fetch;
+  /** Your public Storefront API access token. Omit the token for tokenless access. `createStorefrontClient` throws an error for an empty string. */
   publicStorefrontToken?: string | undefined;
 }
 /**
- * Private client — uses a private Storefront Access Token.
- *
- * `buyerIp` must be resolved on the request context before creating the client.
- *
- * Best for: SSR/server-side requests where you control the fetch
- * layer and can forward trusted buyer context.
- * Token-based access is required for some Storefront API fields, including
- * product tags, metaobjects, metafields, menus, and customers.
+ * Options for a private client, which runs during server-side rendering and forwards the
+ * customer's IP address to the Storefront API. Set `buyerIp` on the request context before you
+ * create the client.
  */
 interface PrivateClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  /** The fetch function that the client calls. Defaults to `globalThis.fetch`. `createStorefrontClient` throws an error when neither exists. */
   fetch?: Fetch;
+  /** Your private Storefront API access token. Keep the token out of browser code. `createStorefrontClient` throws an error when the token is missing. */
   privateStorefrontToken: string;
 }
 /**
- * Private client without buyer context — uses a private Storefront Access Token
- * but does NOT forward per-buyer identity.
- *
- * Best for: background jobs, webhooks, or server contexts where no
- * shopper identity is available.
+ * Options for a private client without buyer context, for background jobs, webhooks, and other
+ * server code with no customer. The client sends a private access token and no customer IP address.
  */
 interface PrivateNoBuyerContextClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  /** The fetch function that the client calls. Defaults to `globalThis.fetch`. `createStorefrontClient` throws an error when neither exists. */
   fetch?: Fetch;
+  /** Your private Storefront API access token. Keep the token out of browser code. `createStorefrontClient` throws an error when the token is missing. */
   privateStorefrontToken: string;
 }
+/**
+ * The store settings that you pass as `config` when you create a client. The options depend on the client type.
+ *
+ * @publicDocs
+ */
 type StorefrontClientOptions = PublicClientOptions | PrivateClientOptions | PrivateNoBuyerContextClientOptions;
+/**
+ * The arguments for createStorefrontClient. Set `type` to choose the client, then pass a request
+ * context and the matching store settings.
+ *
+ * A public client takes a public token or none. A private client takes a private token and a
+ * request context with `buyerIp`. A private client without buyer context takes a private token.
+ */
 type CreateStorefrontClientArgs<RequestContext extends ShopifyRequestContext = ShopifyRequestContext, Type extends ClientType = ClientType, CacheConfig extends CacheInstance | undefined = CacheInstance | undefined> = {
   type: "public" & Type;
   requestContext: RequestContext;
@@ -102,17 +141,42 @@ type CreateStorefrontClientArgs<RequestContext extends ShopifyRequestContext = S
   };
 };
 type AutoAddedVariableNames = "country" | "language";
+/** The variables that you pass for a document, without `country` and `language`. The client fills both from the request context. */
 type UserVariables<Doc> = Omit<VariablesOfDoc<Doc>, AutoAddedVariableNames>;
+/** Resolves to `true` when an object type has no required keys. */
 type HasNoRequiredKeys<T> = Record<string, never> extends T ? true : false;
+/**
+ * Options that every Storefront API GraphQL call accepts.
+ *
+ * @publicDocs
+ */
 type StorefrontGraphqlOptions = {
+  /**
+   * Cancels the request when the signal aborts. The request context's signal and the client timeout
+   * also cancel the request. The signal doesn't cancel a stale-while-revalidate refresh.
+   */
   signal?: AbortSignal;
 };
+/** The options for a GraphQL call. The call needs `variables` only when the document declares a required variable. */
 type MergedOptions<Doc extends DocLike, Extra extends Record<string, unknown>> = Extra & StorefrontGraphqlOptions & (HasNoRequiredKeys<UserVariables<Doc>> extends true ? {
   variables?: UserVariables<Doc>;
 } : {
   variables: UserVariables<Doc>;
 });
+/**
+ * The options argument of a GraphQL call. Pass the options argument when the document declares a
+ * required variable. You can leave the options argument out when every variable is optional, or
+ * when the only required variables are `$country` and `$language`, which the client fills.
+ */
 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>>];
+/**
+ * The result of a GraphQL call, with the data, any GraphQL errors, and the response headers. Check
+ * `errors` before you read `data`.
+ *
+ * Without errors, `data` holds the full result, typed from your document. With errors, `data` is
+ * `null` after a request error or after a failed non-null field at the root. Otherwise, `data`
+ * holds a partial result, and `null` replaces each failed field or its nearest nullable parent.
+ */
 type StorefrontGraphqlResult<Doc extends DocLike> = {
   data: ResultOfDoc<Doc>;
   errors?: undefined;
@@ -122,24 +186,91 @@ type StorefrontGraphqlResult<Doc extends DocLike> = {
   errors: GraphQLFormattedError[];
   headers: Headers;
 };
-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";
+/**
+ * Runs a Storefront API query or mutation. Pass a `gql` document or a plain query string.
+ *
+ * @publicDocs
+ */
+type StorefrontGraphql =
+/**
+ * @param doc - The `gql` document or query string to run.
+ * @param options - The variables and abort signal for the call. Pass the options when the document declares a required variable.
+ * @returns The response data, any GraphQL errors, and the response headers.
+ */
+<const Doc extends DocLike | string>(doc: Doc, ...options: GqlRestParam<ResolveDoc<Doc>>) => Promise<StorefrontGraphqlResult<ResolveDoc<Doc>>>;
+/**
+ * Chooses the kind of Storefront API client to create. Use `public` in the browser, with a public access token or none. Use `private` during server-side rendering, with a private token and the customer's IP address. Use `private_no_buyer_context` in background jobs and webhooks, with a private token and no customer.
+ *
+ * @publicDocs
+ */
+type ClientType = /** Runs in the browser with a public access token or none. */"public" /** Runs during server-side rendering with a private token and the customer's IP address. */ | "private" /** Runs in background jobs and webhooks with a private token and no customer. */ | "private_no_buyer_context";
+/**
+ * A Storefront API client. Call `graphql()` with a document to run a query or mutation and get a
+ * typed result.
+ */
 type StorefrontClient<Extra extends Record<string, unknown> = {}, Type extends ClientType = ClientType, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = {
-  type: Type;
+  /** The client type that you passed to `createStorefrontClient`. */type: Type; /** The country and language that the client sends for `$country` and `$language` variables. */
   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;
+  /**
+   * Runs a Storefront API query or mutation and returns a typed result. Pass a `gql` document or a
+   * plain query string. When the operation declares `$country` or `$language`, the client sets the
+   * variable from the request context and overrides any value you pass.
+   *
+   * The method throws an error when a query passes a `cache` strategy and the client has no cache,
+   * or when the strategy uses `private` mode. A catch block for `StorefrontApiError` doesn't catch
+   * this configuration error. To cache customer-specific data, use `createRunWithCache` with a key
+   * unique to the customer.
+   */
+  graphql: <const Doc extends DocLike | string>(doc: Doc, ...options: GqlRestParam<ResolveDoc<Doc>, Extra>) => Promise<StorefrontGraphqlResult<ResolveDoc<Doc>>>; /** The Storefront API GraphQL endpoint that the client calls. */
+  apiUrl: string; /** Your store's URL with its protocol, such as `https://my-store.myshopify.com`. */
+  storeUrl: string; /** The storefront ID from the client options. */
+  storefrontId?: string; /** The request context that you passed to `createStorefrontClient`. */
   requestContext: RequestContext;
 };
+/**
+ * The type of a client that you create with `type: "public"`.
+ *
+ * @publicDocs
+ */
 type PublicStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = StorefrontClient<Extra, "public", RequestContext>;
+/**
+ * The type of a client that you create with `type: "private"`. The client's request context includes `buyerIp`.
+ *
+ * @publicDocs
+ */
 type PrivateStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContextWithBuyerIp = ShopifyRequestContextWithBuyerIp> = StorefrontClient<Extra, "private", RequestContext>;
+/**
+ * The type of a private client with the default request context. Use the type to annotate a private client without naming your request context type.
+ *
+ * @publicDocs
+ */
 type RequestScopedPrivateStorefrontClient<Extra extends Record<string, unknown> = {}> = PrivateStorefrontClient<Extra, ShopifyRequestContextWithBuyerIp>;
+/**
+ * The type of a client that you create with `type: "private_no_buyer_context"`, for background jobs and webhooks.
+ *
+ * @publicDocs
+ */
 type PrivateNoBuyerContextStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = StorefrontClient<Extra, "private_no_buyer_context", RequestContext>;
+/**
+ * Type helpers that read the result and variables types of a Storefront API document.
+ *
+ * @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>;
+ * ```
+ * @publicDocs
+ */
 declare namespace StorefrontApi {
+  /** The result type of a document. */
   type ResultOf<Doc extends DocLike> = StorefrontApiResultOf<Doc>;
+  /** The variables type of a document. */
   type VariablesOf<Doc extends DocLike> = StorefrontApiVariablesOf<Doc>;
+  /** A typed Storefront API document from `gql`, or a gql.tada document node. */
   type DocumentNode = DocLike;
 }
 //#endregion

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

@@ -1,7 +1,30 @@
 import { CartStore } from "../cart/cart.mjs";
 
 //#region src/core/analytics/cart-tracker.d.ts
+/** A cart store, or any object with the cart store's `getState()` and `subscribe()` methods. */
 type CartAnalyticsStore = Pick<CartStore, "getState" | "subscribe">;
+/**
+ * Publishes cart analytics events when the server confirms a change to the customer's cart. In React, call `useCartAnalytics`.
+ *
+ * The function publishes `cart_updated` when the cart's update time changes, plus
+ * `product_added_to_cart` or `product_removed_from_cart` for each added line, removed
+ * line, and quantity change. The function waits until no cart change or reload is in flight.
+ * Analytics payloads leave out cart lines without merchandise.
+ *
+ * The function stores the last published cart update in local storage under `cartLastUpdatedAt`
+ * to avoid repeat events across page loads and tabs. A store that you fill from your own cart query
+ * must select `updatedAt`. Without the update time, the function publishes on every confirmed cart state.
+ * The function also sets `window.Shopify.currency.active` to the cart's currency.
+ *
+ * The function throws when the Shopify analytics bus isn't available, including during server rendering.
+ * Render `ShopifyScripts`, then start tracking in a client-only effect, such as `useEffect` or `onMounted`.
+ *
+ * @param store The cart store to track.
+ * @throws {Error} If `window.Shopify.analytics` isn't set, including on the server.
+ *   Render Shopify's script tags first.
+ * @returns A function that stops tracking.
+ * @publicDocs
+ */
 declare function trackCartAnalytics(store: CartAnalyticsStore): () => void;
 //#endregion
 export { trackCartAnalytics };

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

@@ -2,6 +2,28 @@ import { AnalyticsEvent } from "./events.mjs";
 import { flattenConnection } from "./utils/flatten-connection.mjs";
 
 //#region src/core/analytics/cart-tracker.ts
+/**
+* Publishes cart analytics events when the server confirms a change to the customer's cart. In React, call `useCartAnalytics`.
+*
+* The function publishes `cart_updated` when the cart's update time changes, plus
+* `product_added_to_cart` or `product_removed_from_cart` for each added line, removed
+* line, and quantity change. The function waits until no cart change or reload is in flight.
+* Analytics payloads leave out cart lines without merchandise.
+*
+* The function stores the last published cart update in local storage under `cartLastUpdatedAt`
+* to avoid repeat events across page loads and tabs. A store that you fill from your own cart query
+* must select `updatedAt`. Without the update time, the function publishes on every confirmed cart state.
+* The function also sets `window.Shopify.currency.active` to the cart's currency.
+*
+* The function throws when the Shopify analytics bus isn't available, including during server rendering.
+* Render `ShopifyScripts`, then start tracking in a client-only effect, such as `useEffect` or `onMounted`.
+*
+* @param store The cart store to track.
+* @throws {Error} If `window.Shopify.analytics` isn't set, including on the server.
+*   Render Shopify's script tags first.
+* @returns A function that stops tracking.
+* @publicDocs
+*/
 function trackCartAnalytics(store) {
 	const analytics = getGlobalAnalytics();
 	const state = {
@@ -120,7 +142,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\">;\n/** A cart store, or any object with the cart store's `getState()` and `subscribe()` methods. */\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 * Publishes cart analytics events when the server confirms a change to the customer's cart. In React, call `useCartAnalytics`.\n *\n * The function publishes `cart_updated` when the cart's update time changes, plus\n * `product_added_to_cart` or `product_removed_from_cart` for each added line, removed\n * line, and quantity change. The function waits until no cart change or reload is in flight.\n * Analytics payloads leave out cart lines without merchandise.\n *\n * The function stores the last published cart update in local storage under `cartLastUpdatedAt`\n * to avoid repeat events across page loads and tabs. A store that you fill from your own cart query\n * must select `updatedAt`. Without the update time, the function publishes on every confirmed cart state.\n * The function also sets `window.Shopify.currency.active` to the cart's currency.\n *\n * The function throws when the Shopify analytics bus isn't available, including during server rendering.\n * Render `ShopifyScripts`, then start tracking in a client-only effect, such as `useEffect` or `onMounted`.\n *\n * @param store The cart store to track.\n * @throws {Error} If `window.Shopify.analytics` isn't set, including on the server.\n *   Render Shopify's script tags first.\n * @returns A function that stops tracking.\n * @publicDocs\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":"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"}

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,14 +1,27 @@
 //#region src/core/analytics/events.d.ts
+/**
+ * The names of the analytics events that Hydrogen supports.
+ *
+ * Pass a constant as the event name when you publish an event or subscribe a destination.
+ * TypeScript narrows the payload to match the event name.
+ *
+ * @publicDocs
+ */
 declare const AnalyticsEvent: {
-  PAGE_VIEWED: "page_viewed";
-  PRODUCT_VIEWED: "product_viewed";
-  COLLECTION_VIEWED: "collection_viewed";
-  CART_VIEWED: "cart_viewed";
-  SEARCH_VIEWED: "search_viewed";
-  CART_UPDATED: "cart_updated";
-  PRODUCT_ADD_TO_CART: "product_added_to_cart";
+  /** Publish when a customer views a page. Hydrogen fills in the current URL when the payload has none. */PAGE_VIEWED: "page_viewed"; /** Publish when a customer views a product. The payload lists the viewed products. */
+  PRODUCT_VIEWED: "product_viewed"; /** Publish when a customer views a collection. The payload identifies the collection by ID and handle. */
+  COLLECTION_VIEWED: "collection_viewed"; /** Publish when a customer views the cart. The payload carries the current cart. */
+  CART_VIEWED: "cart_viewed"; /** Publish when a customer views search results. The payload carries the search term. */
+  SEARCH_VIEWED: "search_viewed"; /** Cart tracking publishes this event when the cart changes. */
+  CART_UPDATED: "cart_updated"; /** Cart tracking publishes this event when the customer adds a line or raises a line's quantity. */
+  PRODUCT_ADD_TO_CART: "product_added_to_cart"; /** Cart tracking publishes this event when the customer removes a line or lowers a line's quantity. */
   PRODUCT_REMOVED_FROM_CART: "product_removed_from_cart";
 };
+/**
+ * The name of a supported analytics event, such as `"page_viewed"`.
+ *
+ * @publicDocs
+ */
 type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];
 //#endregion
 export { AnalyticsEvent, AnalyticsEventName };

package/dist/core/analytics/events.mjs

@@ -1,12 +1,28 @@
 //#region src/core/analytics/events.ts
+/**
+* The names of the analytics events that Hydrogen supports.
+*
+* Pass a constant as the event name when you publish an event or subscribe a destination.
+* TypeScript narrows the payload to match the event name.
+*
+* @publicDocs
+*/
 const AnalyticsEvent = {
+	/** Publish when a customer views a page. Hydrogen fills in the current URL when the payload has none. */
 	PAGE_VIEWED: "page_viewed",
+	/** Publish when a customer views a product. The payload lists the viewed products. */
 	PRODUCT_VIEWED: "product_viewed",
+	/** Publish when a customer views a collection. The payload identifies the collection by ID and handle. */
 	COLLECTION_VIEWED: "collection_viewed",
+	/** Publish when a customer views the cart. The payload carries the current cart. */
 	CART_VIEWED: "cart_viewed",
+	/** Publish when a customer views search results. The payload carries the search term. */
 	SEARCH_VIEWED: "search_viewed",
+	/** Cart tracking publishes this event when the cart changes. */
 	CART_UPDATED: "cart_updated",
+	/** Cart tracking publishes this event when the customer adds a line or raises a line's quantity. */
 	PRODUCT_ADD_TO_CART: "product_added_to_cart",
+	/** Cart tracking publishes this event when the customer removes a line or lowers a line's quantity. */
 	PRODUCT_REMOVED_FROM_CART: "product_removed_from_cart"
 };
 

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 * The names of the analytics events that Hydrogen supports.\n *\n * Pass a constant as the event name when you publish an event or subscribe a destination.\n * TypeScript narrows the payload to match the event name.\n *\n * @publicDocs\n */\nexport const AnalyticsEvent = {\n  /** Publish when a customer views a page. Hydrogen fills in the current URL when the payload has none. */\n  PAGE_VIEWED: \"page_viewed\" as const,\n  /** Publish when a customer views a product. The payload lists the viewed products. */\n  PRODUCT_VIEWED: \"product_viewed\" as const,\n  /** Publish when a customer views a collection. The payload identifies the collection by ID and handle. */\n  COLLECTION_VIEWED: \"collection_viewed\" as const,\n  /** Publish when a customer views the cart. The payload carries the current cart. */\n  CART_VIEWED: \"cart_viewed\" as const,\n  /** Publish when a customer views search results. The payload carries the search term. */\n  SEARCH_VIEWED: \"search_viewed\" as const,\n\n  /** Cart tracking publishes this event when the cart changes. */\n  CART_UPDATED: \"cart_updated\" as const,\n  /** Cart tracking publishes this event when the customer adds a line or raises a line's quantity. */\n  PRODUCT_ADD_TO_CART: \"product_added_to_cart\" as const,\n  /** Cart tracking publishes this event when the customer removes a line or lowers a line's quantity. */\n  PRODUCT_REMOVED_FROM_CART: \"product_removed_from_cart\" as const,\n};\n\n/** The analytics event constants, keyed by constant name. */\ntype AnalyticsEventMap = typeof AnalyticsEvent;\n\n/**\n * The names of the analytics events that Hydrogen supports. Pass a value as the event name when you publish an event or subscribe a destination. TypeScript narrows the payload to match the event name.\n *\n * @publicDocs\n */\nexport interface AnalyticsEventForDocs extends AnalyticsEventMap {}\n\n/**\n * The name of a supported analytics event, such as `\"page_viewed\"`.\n *\n * @publicDocs\n */\nexport type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];\n"],"mappings":";;;;;;;;;AAQA,MAAa,iBAAiB;;CAE5B,aAAa;;CAEb,gBAAgB;;CAEhB,mBAAmB;;CAEnB,aAAa;;CAEb,eAAe;;CAGf,cAAc;;CAEd,qBAAqB;;CAErB,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";