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

package/README.md

@@ -100,13 +100,13 @@ const isLoggedIn = await customerSession.isLoggedIn(
 );
 ```
 
-Customer Account OAuth methods require a public HTTPS origin. The writable session manager should expose the request origin; explicit `origin` options are only needed as overrides. For local development, use a tunnel or trusted local HTTPS through `localHttps` from `@shopify/hydrogen/vite`, and pass the framework's canonical request URL rather than an untrusted forwarded host.
+Customer Account OAuth methods require a public HTTPS origin. The writable session manager should expose the request origin; explicit `origin` options are only needed as overrides. For local development, use a tunnel or trusted local HTTPS through `localHttps` from `@shopify/hydrogen/vite`, which provisions certificates and uses Shopify CLI to push Customer Account URLs outside CI. Pass the framework's canonical request URL rather than an untrusted forwarded host.
 
 Pass `customerSession` to `createCartServerHandlers({customerSession})` to associate newly created carts with the current customer when the session has a usable access token or successfully refreshed access token, and mark checkout URLs in authenticated cart GET responses with `logged_in=true`.
 
 Use `createCustomerAccountServerHandlers({customerSession})` with `handleShopifyRoutes` to install the default `GET /account/login`, `GET /account/authorize`, `GET /account/refresh`, and `POST /account/logout` handlers. Pass those cart server handlers as `cartServerHandlers` to also keep the browser cart's buyer identity in step with the customer session: authorization and refresh attach the customer to the cart, a definitive refresh rejection and logout detach it. Sync is best-effort — a failed cart mutation never blocks the route's redirect; a failed detach during logout or definitive refresh rejection expires the cart cookie instead. `cartServerHandlers` requires the `customerSession` returned by `createCustomerSession` shared by both handler groups. Pass the same request-scoped `requestContext` and `sessionManager` into `handleShopifyRoutes` once alongside the `storefrontClient`. Session managers can be read-only for `isLoggedIn()` / `getAccessToken()` and writable for cart POST handlers configured with `customerSession`, `getOrRefreshAccessToken()`, `prepareLoginUrl()`, `handleOAuthCallback()`, `logout()`, and registered account handlers. `isLoggedIn()` is a read-only UI/session-presence check: it returns true for a usable access token or a refresh token that can attempt to restore one later. `getAccessToken()` still returns only a currently usable access token and never refreshes.
 
-The login handler respects a sanitized `return_to` search parameter and otherwise redirects back to `defaultPostLoginRedirectPathname` (default `/`). The logout handler redirects through Shopify using `postLogoutRedirectUri` (default `/`) when an ID token is present; otherwise, it redirects directly to `postLogoutRedirectUri`. Apps can still implement their own framework routes when they need custom behavior.
+The login handler respects a `return_to` search parameter when it is a same-origin path or URL, such as `/account/orders`, and otherwise redirects back to `defaultPostLoginRedirectPathname` (default `/`). The logout handler redirects through Shopify using `postLogoutRedirectUri` (default `/`) when an ID token is present; otherwise, it redirects directly to `postLogoutRedirectUri`. Apps can still implement their own framework routes when they need custom behavior.
 
 When a writable method can update cookie-backed session state, commit once while finalizing the response and append headers from `await sessionManager.commit?.()` there. After committing session headers, call `requestContext.applyResponseHeaders(response.headers)`. Customer Account session reads and GraphQL calls mark the request context private so the finalizer can prevent public/CDN caching of personalized responses.
 

package/dist/cli/index.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
@@ -444,6 +444,24 @@ function isObjectRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+//#endregion
+//#region src/cli/terminal.ts
+function canPromptInTerminal(env = process.env) {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY) && !env.CI;
+}
+async function confirmInTerminal(question) {
+	const readline = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const answer = (await readline.question(`${question} [Y/n] `)).trim().toLowerCase();
+		return answer === "" || answer === "y" || answer === "yes";
+	} finally {
+		readline.close();
+	}
+}
+
 //#endregion
 //#region src/cli/skills.ts
 const PACKAGE_NAME$1 = "@shopify/hydrogen";
@@ -681,21 +699,6 @@ async function planOrphans(plans, version, confirm) {
 		});
 	}
 }
-function canPromptInTerminal() {
-	return Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI;
-}
-async function confirmInTerminal(question) {
-	const readline = createInterface({
-		input: process.stdin,
-		output: process.stdout
-	});
-	try {
-		const answer = (await readline.question(`${question} [Y/n] `)).trim().toLowerCase();
-		return answer === "" || answer === "y" || answer === "yes";
-	} finally {
-		readline.close();
-	}
-}
 /** Never removes user edits without an answer, so no TTY means keep. */
 function confirmByDefault(question) {
 	return canPromptInTerminal() ? confirmInTerminal(question) : Promise.resolve(false);
@@ -931,13 +934,14 @@ function parsePackageManager(value) {
 		if (value.startsWith(`${packageManager}/`)) return packageManager;
 	}
 }
+function detectPackageManagerFromEnv(env) {
+	return parsePackageManager(env.npm_config_user_agent);
+}
 function detectPackageManager(appRoot, packageJson, env) {
 	const packageJsonManager = parsePackageManager(packageJson.packageManager);
 	if (packageJsonManager) return packageJsonManager;
 	for (const [packageManager, lockfile] of PACKAGE_MANAGER_LOCKFILES) if (existsSync(join(appRoot, lockfile))) return packageManager;
-	const userAgentManager = parsePackageManager(env.npm_config_user_agent);
-	if (userAgentManager) return userAgentManager;
-	throw new Error("Could not detect a package manager. Add a packageManager field or a lockfile before running setup.");
+	return detectPackageManagerFromEnv(env) ?? "npm";
 }
 function hasHydrogenDependency(packageJson) {
 	return Boolean(packageJson.dependencies?.[PACKAGE_NAME] ?? packageJson.devDependencies?.[PACKAGE_NAME]);
@@ -961,17 +965,115 @@ function spawnRunCommand(command, args, options) {
 		});
 	});
 }
-async function setupHydrogen(options = {}) {
-	const appRoot = options.cwd ?? process.cwd();
-	const env = options.env ?? process.env;
-	const runCommand = options.runCommand ?? spawnRunCommand;
-	const log = options.log ?? console.log;
+const TEMPLATE_TARBALL_URL = "https://codeload.github.com/Shopify/hydrogen/tar.gz/dist-preview";
+const TEMPLATE_TARBALL_PREFIX = "hydrogen-dist-preview/templates/react-router/";
+const TEMPLATE_TARBALL_STRIP_COMPONENTS = TEMPLATE_TARBALL_PREFIX.split("/").filter(Boolean).length;
+async function promptSetupChoice(log) {
+	log("\nNo project found in this directory.\n");
+	log("  1) Create a new Hydrogen storefront (React Router)");
+	log("  2) Just install Hydrogen skills\n");
+	const readline = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		while (true) {
+			const answer = (await readline.question("Your choice [1] ")).trim();
+			if (answer === "" || answer === "1") return "scaffold";
+			if (answer === "2") return "skills";
+			log("Please enter \"1\" or \"2\".");
+		}
+	} finally {
+		readline.close();
+	}
+}
+function hasPackageJson(appRoot) {
+	return existsSync(join(appRoot, PACKAGE_JSON_FILE_NAME));
+}
+async function downloadAndExtractTemplate(appRoot, runCommand) {
+	const response = await fetch(TEMPLATE_TARBALL_URL, { signal: AbortSignal.timeout(3e4) });
+	if (!response.ok) throw new Error(`Failed to download template (${response.status}). Check your internet connection.`);
+	const tempDir = mkdtempSync(join(tmpdir(), "hydrogen-template-"));
+	const tempFile = "template.tar.gz";
+	try {
+		writeFileSync(join(tempDir, tempFile), Buffer.from(await response.arrayBuffer()));
+		await runCommand("tar", [
+			"xzf",
+			tempFile,
+			`--strip-components=${TEMPLATE_TARBALL_STRIP_COMPONENTS}`,
+			"-C",
+			appRoot,
+			TEMPLATE_TARBALL_PREFIX
+		], { cwd: tempDir });
+	} finally {
+		rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function updateScaffoldedPackageJson(appRoot) {
+	const packageJsonPath = join(appRoot, PACKAGE_JSON_FILE_NAME);
+	const raw = readFileSync(packageJsonPath, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!isObjectRecord(parsed)) return;
+	parsed.name = basename(appRoot);
+	delete parsed.private;
+	delete parsed.packageManager;
+	writeFileSync(packageJsonPath, JSON.stringify(parsed, null, 2) + "\n");
+}
+async function scaffoldTemplate(appRoot, env, runCommand, log) {
+	log("Downloading Hydrogen template...");
+	await downloadAndExtractTemplate(appRoot, runCommand);
+	updateScaffoldedPackageJson(appRoot);
+	const packageManager = detectPackageManagerFromEnv(env) ?? "npm";
+	log(`Installing dependencies with ${packageManager}...`);
+	try {
+		await runCommand(packageManager, ["install"], { cwd: appRoot });
+	} catch (error) {
+		throw new Error(`Template was created but dependency install failed. Run \`${packageManager} install\` or re-run \`npx @shopify/hydrogen setup\` in ${appRoot} to finish.`, { cause: error });
+	}
+	return packageManager;
+}
+async function ensureHydrogenInstalled(appRoot, env, runCommand, log) {
 	const packageJson = readPackageJson(appRoot);
-	if (!hasHydrogenDependency(packageJson)) {
+	if (hasHydrogenDependency(packageJson) && getInstalledPackageRoot(appRoot)) return;
+	if (hasHydrogenDependency(packageJson)) {
 		const packageManager = detectPackageManager(appRoot, packageJson, env);
-		log(`Installing ${PACKAGE_NAME} with ${packageManager}...`);
-		await installHydrogen(appRoot, packageManager, runCommand);
+		log(`${PACKAGE_NAME} is declared but not installed. Running ${packageManager} install...`);
+		await runCommand(packageManager, ["install"], { cwd: appRoot });
+		return;
 	}
+	const packageManager = detectPackageManager(appRoot, packageJson, env);
+	log(`Installing ${PACKAGE_NAME} with ${packageManager}...`);
+	await installHydrogen(appRoot, packageManager, runCommand);
+}
+function resolveSetupOptions(options) {
+	const env = options.env ?? process.env;
+	return {
+		appRoot: options.cwd ?? process.cwd(),
+		env,
+		runCommand: options.runCommand ?? spawnRunCommand,
+		log: options.log ?? console.log,
+		prompt: options.prompt ?? (canPromptInTerminal(env) ? promptSetupChoice : void 0)
+	};
+}
+const IGNORED_DIRECTORY_ENTRIES = new Set([".git", ".DS_Store"]);
+function isEmptyDirectory(dir) {
+	return readdirSync(dir).every((entry) => IGNORED_DIRECTORY_ENTRIES.has(entry));
+}
+async function setupHydrogen(options = {}) {
+	const { appRoot, env, runCommand, log, prompt } = resolveSetupOptions(options);
+	if (hasPackageJson(appRoot)) await ensureHydrogenInstalled(appRoot, env, runCommand, log);
+	else if (isEmptyDirectory(appRoot)) {
+		let choice;
+		if (prompt) choice = await prompt(log);
+		else {
+			log("No package.json found and no terminal to prompt; installing skills only.");
+			choice = "skills";
+		}
+		if (choice === "scaffold") log(`\nHydrogen storefront created. Run \`${await scaffoldTemplate(appRoot, env, runCommand, log)} run dev\` to start (uses mock.shop by default).\n`);
+	} else throw new Error("No package.json found. Run this command from your project root.");
 	await syncSkills({
 		force: options.force,
 		cwd: appRoot,

package/dist/client/client.mjs

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

package/dist/client/errors.d.mts

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

package/dist/client/errors.mjs

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

package/dist/client/errors.mjs.map

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

package/dist/client/types.d.mts

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

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

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

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

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