@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/client/types.d.mts

@@ -5,106 +5,121 @@ 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>;
 /**
- * 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}.
+ * A GraphQL error from the Storefront API. The result of a GraphQL call lists GraphQL errors
+ * in its `errors` field.
  */
 interface GraphQLFormattedError {
-  /** Human-readable error description. */
+  /** The error message. */
   readonly message: string;
-  /** Source locations in the query where the error originated. */
+  /** The lines and columns in the query where the error occurs. */
   readonly locations?: ReadonlyArray<{
     line: number;
     column: number;
   }>;
-  /** Response path to the field that triggered the error. */
+  /** The path to the response field that failed. */
   readonly path?: ReadonlyArray<string | number>;
-  /** Vendor extensions (e.g. Shopify error codes). */
+  /** Extra details that the Storefront API adds to the error. */
   readonly extensions?: Record<string, unknown>;
 }
 type CommonOptions = {
-  /** 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.
+   * 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;
+  /**
+   * 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.
    */
-  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. */
+  defaultTimeoutInMs?: number;
+  /**
+   * 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 {
-  /** Custom fetch implementation. Falls back to `globalThis.fetch`. */
+  /** The fetch function that the client calls. Defaults to `globalThis.fetch`. `createStorefrontClient` throws an error when neither exists. */
   fetch?: Fetch;
-  /** Public Storefront Access Token. Omit for tokenless access (limited fields). */
+  /** 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 {
-  /** Custom fetch implementation. Falls back to `globalThis.fetch`. */
+  /** The fetch function that the client calls. Defaults to `globalThis.fetch`. `createStorefrontClient` throws an error when neither exists. */
   fetch?: Fetch;
-  /** Private Storefront Access Token. Must never be exposed to browsers. */
+  /** 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 {
-  /** Custom fetch implementation. Falls back to `globalThis.fetch`. */
+  /** The fetch function that the client calls. Defaults to `globalThis.fetch`. `createStorefrontClient` throws an error when neither exists. */
   fetch?: Fetch;
-  /** Private Storefront Access Token. Must never be exposed to browsers. */
+  /** Your private Storefront API access token. Keep the token out of browser code. `createStorefrontClient` throws an error when the token is missing. */
   privateStorefrontToken: string;
 }
-/** Union of all config shapes passed as the `config` field of {@link CreateStorefrontClientArgs}. */
+/**
+ * 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;
 /**
- * Discriminated union accepted by `createStorefrontClient`.
+ * The arguments for createStorefrontClient. Set `type` to choose the client, then pass a request
+ * context and the matching store settings.
  *
- * 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.
+ * 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;
@@ -126,39 +141,41 @@ 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;
-/** Per-call options common to every `storefront.graphql()` invocation. */
+/**
+ * Options that every Storefront API GraphQL call accepts.
+ *
+ * @publicDocs
+ */
 type StorefrontGraphqlOptions = {
-  /** Abort signal forwarded to the underlying fetch. Combined with the request-context signal via `AbortSignal.any`. */signal?: AbortSignal;
+  /**
+   * 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>;
 });
 /**
- * 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`).
+ * 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>>];
 /**
- * Discriminated union returned by `storefront.graphql()`.
- *
- * Discriminated on `errors`:
+ * The result of a GraphQL call, with the data, any GraphQL errors, and the response headers. Check
+ * `errors` before you read `data`.
  *
- * - **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.
+ * 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>;
@@ -169,41 +186,73 @@ 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`.
+ * 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.
  *
- * 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.
+ * @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> = {
-  /** Which client variant was created (`"public"`, `"private"`, or `"private_no_buyer_context"`). */type: Type; /** Resolved i18n config (country + language) used for automatic variable injection. */
+  /** 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"];
   /**
-   * Execute a Storefront API GraphQL operation.
+   * 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.
    *
-   * Accepts a `gql()` document or a plain query string. Variables
-   * declared as `$country` / `$language` are auto-injected from the client's
-   * i18n config.
+   * 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>>>; /** 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. */
+  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;
 };
-/** A {@link StorefrontClient} narrowed to `type: "public"`. */
+/**
+ * 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>;
-/** A {@link StorefrontClient} narrowed to `type: "private"`. Requires a request context with `buyerIp`. */
+/**
+ * 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>;
-/** Convenience alias: a private client whose request context is always the concrete `ShopifyRequestContextWithBuyerIp`. */
+/**
+ * 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>;
-/** A {@link StorefrontClient} narrowed to `type: "private_no_buyer_context"`. Best for background jobs and webhooks. */
+/**
+ * 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>;
 /**
- * Namespace for extracting result and variable types from Storefront API documents.
+ * Type helpers that read the result and variables types of a Storefront API document.
  *
  * @example
  * ```ts
@@ -214,13 +263,14 @@ type PrivateNoBuyerContextStorefrontClient<Extra extends Record<string, unknown>
  * type Product = StorefrontApi.ResultOf<typeof PRODUCT_QUERY>;
  * type Vars = StorefrontApi.VariablesOf<typeof PRODUCT_QUERY>;
  * ```
+ * @publicDocs
  */
 declare namespace StorefrontApi {
-  /** Extracts the typed result shape from a Storefront API document. */
+  /** The result type of a document. */
   type ResultOf<Doc extends DocLike> = StorefrontApiResultOf<Doc>;
-  /** Extracts the typed variables shape from a Storefront API document. */
+  /** The variables type of a document. */
   type VariablesOf<Doc extends DocLike> = StorefrontApiVariablesOf<Doc>;
-  /** A typed Storefront API document — a `gql()` document or a `TadaDocumentNode`. */
+  /** 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,20 +1,29 @@
 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">;
 /**
- * Subscribes to a cart store and publishes analytics events when the cart changes.
+ * Publishes cart analytics events when the server confirms a change to the customer's cart. In React, call `useCartAnalytics`.
  *
- * 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.
+ * 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.
  *
- * @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.
+ * 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

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

@@ -3,18 +3,26 @@ 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.
+* Publishes cart analytics events when the server confirms a change to the customer's cart. In React, call `useCartAnalytics`.
 *
-* 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.
+* 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.
 *
-* @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.
+* 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();

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\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":"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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/events.d.mts

@@ -1,21 +1,27 @@
 //#region src/core/analytics/events.d.ts
 /**
- * Canonical event names for the Hydrogen analytics bus.
+ * The names of the analytics events that Hydrogen supports.
  *
- * 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.
+ * 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,19 +1,28 @@
 //#region src/core/analytics/events.ts
 /**
-* Canonical event names for the Hydrogen analytics bus.
+* The names of the analytics events that Hydrogen supports.
 *
-* 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.
+* 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":["/**\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"}
+{"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"}