@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/development/client/errors.d.mts

@@ -7,24 +7,37 @@ interface StorefrontApiErrorOptions {
   variables?: Record<string, unknown>;
 }
 /**
- * Thrown when a Storefront API request fails — HTTP error, network failure,
- * or an unparseable or unexpected response body.
+ * Signals that a Storefront API request failed. The client throws the error for an HTTP error
+ * status, a network failure, or a response body that isn't a JSON object.
  *
- * In development, `queryText` and `variables` are attached when available.
- * GraphQL errors (including `THROTTLED`) are not thrown; read them from `result.errors`.
+ * GraphQL errors, including `THROTTLED`, don't throw. Read GraphQL errors from the result's
+ * `errors` field.
+ *
+ * When the request context's signal or the call's `signal` aborts before the call, the client
+ * throws the abort reason and sends no request. An `AbortError` during the request reaches your
+ * code unchanged. Other abort reasons during the request throw a `StorefrontApiError`.
+ *
+ * @publicDocs
  */
 declare class StorefrontApiError extends Error {
-  /** Shopify `x-request-id` header, when available. Useful for support requests. */
+  /** The `x-request-id` header of the Storefront API response, when the response has one. Include the ID in support requests. */
   readonly requestId?: string;
-  /** HTTP response status code, when the request reached the server. */
+  /** The HTTP status code of the response, when the request reached the server. */
   readonly status?: number;
-  /** The GraphQL query text. Only populated in development builds. */
+  /** The GraphQL query that failed. Hydrogen sets the value only in development builds. */
   readonly queryText?: string;
-  /** The variables sent with the request. Only populated in development builds. */
+  /** The variables that the client sent with the request. Hydrogen sets the value only in development builds. */
   readonly variables?: Record<string, unknown>;
+  /** `StorefrontApiError`. `StorefrontTimeoutError` sets its own class name. */
+  name: string;
+  /** Describes the failure, such as the HTTP status that the API returned. */
+  message: string;
+  /** The stack trace, when the JavaScript runtime records one. */
+  stack?: string;
   constructor(message: string, options?: StorefrontApiErrorOptions);
+  /** Makes `Object.prototype.toString` report the error name, such as `[object StorefrontApiError]`. */
   get [Symbol.toStringTag](): string;
-  /** Serializes the error. `queryText`, `variables`, `cause`, and `stack` are always omitted. */
+  /** Returns the error name, message, request ID, and status for logging. The output leaves out the query text, variables, cause, and stack. */
   toJSON(): {
     name: string;
     message: string;
@@ -33,14 +46,23 @@ declare class StorefrontApiError extends Error {
   };
 }
 /**
- * Thrown when a Storefront API request exceeds the configured `defaultTimeoutInMs`.
+ * Signals that a Storefront API request ran longer than the client's `defaultTimeoutInMs` setting.
+ * Aborts from the request context or the call's `signal` throw other errors.
+ *
+ * `StorefrontTimeoutError` extends `StorefrontApiError`. Check for `StorefrontTimeoutError` first when
+ * you handle both errors.
  *
- * Subclass of {@link StorefrontApiError}, so catching `StorefrontApiError` also handles timeouts.
- * Aborts from the request context or a per-call `signal` are rethrown as-is, not wrapped.
+ * @publicDocs
  */
 declare class StorefrontTimeoutError extends StorefrontApiError {
-  /** The timeout threshold that was exceeded, in milliseconds. */
+  /** The timeout that the request exceeded, in milliseconds. */
   readonly timeoutInMs: number;
+  /** Always `StorefrontTimeoutError`. */
+  name: string;
+  /** States the timeout, such as `"Storefront API request timed out after 30000ms"`. */
+  message: string;
+  /** The stack trace, when the JavaScript runtime records one. */
+  stack?: string;
   constructor(timeoutInMs: number, options?: Omit<StorefrontApiErrorOptions, "cause">);
 }
 //#endregion

package/dist/development/client/errors.mjs

@@ -1,19 +1,25 @@
 //#region src/client/errors.ts
 /**
-* Thrown when a Storefront API request fails — HTTP error, network failure,
-* or an unparseable or unexpected response body.
+* Signals that a Storefront API request failed. The client throws the error for an HTTP error
+* status, a network failure, or a response body that isn't a JSON object.
 *
-* In development, `queryText` and `variables` are attached when available.
-* GraphQL errors (including `THROTTLED`) are not thrown; read them from `result.errors`.
+* GraphQL errors, including `THROTTLED`, don't throw. Read GraphQL errors from the result's
+* `errors` field.
+*
+* When the request context's signal or the call's `signal` aborts before the call, the client
+* throws the abort reason and sends no request. An `AbortError` during the request reaches your
+* code unchanged. Other abort reasons during the request throw a `StorefrontApiError`.
+*
+* @publicDocs
 */
 var StorefrontApiError = class extends Error {
-	/** Shopify `x-request-id` header, when available. Useful for support requests. */
+	/** The `x-request-id` header of the Storefront API response, when the response has one. Include the ID in support requests. */
 	requestId;
-	/** HTTP response status code, when the request reached the server. */
+	/** The HTTP status code of the response, when the request reached the server. */
 	status;
-	/** The GraphQL query text. Only populated in development builds. */
+	/** The GraphQL query that failed. Hydrogen sets the value only in development builds. */
 	queryText;
-	/** The variables sent with the request. Only populated in development builds. */
+	/** The variables that the client sent with the request. Hydrogen sets the value only in development builds. */
 	variables;
 	constructor(message, options) {
 		super(message, options?.cause ? { cause: options.cause } : void 0);
@@ -23,10 +29,11 @@ var StorefrontApiError = class extends Error {
 		this.queryText = options?.queryText;
 		this.variables = options?.variables;
 	}
+	/** Makes `Object.prototype.toString` report the error name, such as `[object StorefrontApiError]`. */
 	get [Symbol.toStringTag]() {
 		return this.name;
 	}
-	/** Serializes the error. `queryText`, `variables`, `cause`, and `stack` are always omitted. */
+	/** Returns the error name, message, request ID, and status for logging. The output leaves out the query text, variables, cause, and stack. */
 	toJSON() {
 		return {
 			name: this.name,
@@ -37,13 +44,16 @@ var StorefrontApiError = class extends Error {
 	}
 };
 /**
-* Thrown when a Storefront API request exceeds the configured `defaultTimeoutInMs`.
+* Signals that a Storefront API request ran longer than the client's `defaultTimeoutInMs` setting.
+* Aborts from the request context or the call's `signal` throw other errors.
+*
+* `StorefrontTimeoutError` extends `StorefrontApiError`. Check for `StorefrontTimeoutError` first when
+* you handle both errors.
 *
-* Subclass of {@link StorefrontApiError}, so catching `StorefrontApiError` also handles timeouts.
-* Aborts from the request context or a per-call `signal` are rethrown as-is, not wrapped.
+* @publicDocs
 */
 var StorefrontTimeoutError = class extends StorefrontApiError {
-	/** The timeout threshold that was exceeded, in milliseconds. */
+	/** The timeout that the request exceeded, in milliseconds. */
 	timeoutInMs;
 	constructor(timeoutInMs, options) {
 		super(`Storefront API request timed out after ${timeoutInMs}ms`, options);

package/dist/development/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}\n\n/**\n * Thrown when a Storefront API request fails — HTTP error, network failure,\n * or an unparseable or unexpected response body.\n *\n * In development, `queryText` and `variables` are attached when available.\n * GraphQL errors (including `THROTTLED`) are not thrown; read them from `result.errors`.\n */\nexport class StorefrontApiError extends Error {\n  /** Shopify `x-request-id` header, when available. Useful for support requests. */\n  readonly requestId?: string;\n  /** HTTP response status code, when the request reached the server. */\n  readonly status?: number;\n  /** The GraphQL query text. Only populated in development builds. */\n  readonly queryText?: string;\n  /** The variables sent with the request. Only populated in development builds. */\n  readonly variables?: Record<string, unknown>;\n\n  constructor(message: string, options?: StorefrontApiErrorOptions) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"StorefrontApiError\";\n    this.requestId = options?.requestId;\n    this.status = options?.status;\n\n    if (__DEV__) {\n      this.queryText = options?.queryText;\n      this.variables = options?.variables;\n    }\n  }\n\n  get [Symbol.toStringTag]() {\n    return this.name;\n  }\n\n  /** Serializes the error. `queryText`, `variables`, `cause`, and `stack` are always omitted. */\n  toJSON(): { name: string; message: string; requestId?: string; status?: number } {\n    return {\n      name: this.name,\n      message: this.message,\n      ...(this.requestId != null && { requestId: this.requestId }),\n      ...(this.status != null && { status: this.status }),\n    };\n  }\n}\n\n/**\n * Thrown when a Storefront API request exceeds the configured `defaultTimeoutInMs`.\n *\n * Subclass of {@link StorefrontApiError}, so catching `StorefrontApiError` also handles timeouts.\n * Aborts from the request context or a per-call `signal` are rethrown as-is, not wrapped.\n */\nexport class StorefrontTimeoutError extends StorefrontApiError {\n  /** The timeout threshold that was exceeded, in milliseconds. */\n  readonly timeoutInMs: number;\n\n  constructor(timeoutInMs: number, options?: Omit<StorefrontApiErrorOptions, \"cause\">) {\n    super(`Storefront API request timed out after ${timeoutInMs}ms`, options);\n    this.name = \"StorefrontTimeoutError\";\n    this.timeoutInMs = timeoutInMs;\n  }\n}\n"],"mappings":";;;;;;;;AAeA,IAAa,qBAAb,cAAwC,MAAM;;CAE5C,AAAS;;CAET,AAAS;;CAET,AAAS;;CAET,AAAS;CAET,YAAY,SAAiB,SAAqC;AAChE,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,YAAY,SAAS;AAC1B,OAAK,SAAS,SAAS;AAGrB,OAAK,YAAY,SAAS;AAC1B,OAAK,YAAY,SAAS;;CAI9B,KAAK,OAAO,eAAe;AACzB,SAAO,KAAK;;;CAId,SAAiF;AAC/E,SAAO;GACL,MAAM,KAAK;GACX,SAAS,KAAK;GACd,GAAI,KAAK,aAAa,QAAQ,EAAE,WAAW,KAAK,WAAW;GAC3D,GAAI,KAAK,UAAU,QAAQ,EAAE,QAAQ,KAAK,QAAQ;GACnD;;;;;;;;;AAUL,IAAa,yBAAb,cAA4C,mBAAmB;;CAE7D,AAAS;CAET,YAAY,aAAqB,SAAoD;AACnF,QAAM,0CAA0C,YAAY,KAAK,QAAQ;AACzE,OAAK,OAAO;AACZ,OAAK,cAAc"}
+{"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;AAGrB,OAAK,YAAY,SAAS;AAC1B,OAAK,YAAY,SAAS;;;CAK9B,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/development/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/development/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/development/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();