@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.1

package/README.md

@@ -1,22 +1,82 @@
-<div align="center">
-
 # Hydrogen
 
-[![MIT License](https://img.shields.io/github/license/shopify/hydrogen)](LICENSE.md)
-[![npm downloads](https://img.shields.io/npm/dm/@shopify/hydrogen.svg?sanitize=true)](https://npmcharts.com/compare/@shopify/hydrogen?minimal=true)
+Framework agnostic Shopify storefront SDK and packaged agent skills.
 
-Hydrogen is Shopify’s stack for headless commerce. It provides a set of tools, utilities, and best-in-class examples for building dynamic and performant commerce applications. Hydrogen is designed to dovetail with [Remix](https://remix.run/), Shopify’s full stack web framework, but it also provides a React library portable to other supporting frameworks.
+## Setup
 
-**Create a Hydrogen app**
+Run the setup CLI in a storefront project.
 
 ```bash
-npm create @shopify/hydrogen@latest
+npx @shopify/hydrogen setup
+```
+
+The setup command installs `@shopify/hydrogen` into the local project using the detected package manager, then copies the packaged skills into local agent skill directories.
+
+## GraphQL Tooling
+
+Enable Storefront and Customer Account API editor diagnostics with Hydrogen's packed TypeScript plugin:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [{"name": "@shopify/hydrogen/ts-plugin"}]
+  }
+}
+```
+
+Run the same GraphQL validation headlessly with `npx @shopify/hydrogen gql check --fail-on-warn`, or use `hydrogen gql check --fail-on-warn` in a package script. Both commands use the Shopify schemas packaged with Hydrogen.
+
+The editor plugin generates `storefront-graphql-env.d.ts` and `customer-account-graphql-env.d.ts` at the project root. Add both files to `.gitignore`.
+
+## Customer Account API
+
+Use `@shopify/hydrogen/customer-account` for type-safe Customer Account API requests from server code:
+
+```ts
+import { createShopifyRequestContext } from "@shopify/hydrogen";
+import * as CAAPI from "@shopify/hydrogen/customer-account";
+
+const CUSTOMER_QUERY = CAAPI.gql(`query { customer { firstName emailAddress { emailAddress } } }`);
+const requestContext = createShopifyRequestContext({
+  request,
+  i18n: { country: "US", language: "EN" },
+});
+
+const customerAccount = CAAPI.createCustomerAccountClient({
+  shopId: env.SHOP_ID,
+  requestContext,
+});
+
+const accessToken = await getAccessTokenFromYourServerSession(request);
+const customerResult = await customerAccount.graphql(CUSTOMER_QUERY, {
+  accessToken,
+});
+```
+
+Use a numeric Shopify shop ID string from `SHOP_ID`, not a Shop GID or domain. The GraphQL client intentionally receives only the access token that your server-side auth flow has already obtained.
+
+Hydrogen also ships framework-neutral Customer Account OAuth/session helpers. Construct `createCustomerSession()` at module scope with `SHOP_ID` and `PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID`, then pass request-scoped session managers into its methods:
+
+```ts
+const customerSession = CAAPI.createCustomerSession({
+  shopId: env.SHOP_ID,
+  customerAccountApiClientId: env.PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID,
+});
+
+const isLoggedIn = await customerSession.isLoggedIn(
+  sessionManager,
+  requestContext,
+);
 ```
 
- </div>
+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.
+
+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.
+
+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.
 
-- Interested in contributing to Hydrogen? [Read our contributing guide](../../CONTRIBUTING.md)
-- Want to learn more? [Check out the Hydrogen docs on Shopify.dev](https://shopify.dev/custom-storefronts/hydrogen)
-- Questions? Feedback? Feature requests? [Discussions](https://github.com/Shopify/hydrogen/discussions)
-- Upgrading from a previous version? [View the Changelog](./packages/hydrogen/CHANGELOG.md)
-- Looking for Hydrogen v1? [The source code has been moved](https://github.com/Shopify/hydrogen-v1)
+Use the GraphQL client from server or edge routes only. Keep Customer Account tokens in protected server session storage or encrypted HttpOnly cookies, not browser-readable storage. Pass the same Shopify request context used by the Storefront client so the Customer Account client can derive the `Origin` header, default language, and final response cache policy from request-scoped data. Keep GraphQL documents static and pass user input through variables. Do not retry Customer Account mutations after a timeout unless the operation is externally idempotent.

package/bin/hydrogen.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+// Keep this wrapper checked in: pnpm links the `hydrogen` command before `dist`
+// exists in a clean workspace. `.mjs` keeps its ESM format independent of package settings.
+import { runCli } from "../dist/cli/index.mjs";
+
+runCli();

package/dist/cli/index.mjs

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { dirname, join, parse, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+//#region src/graphql/plugin-config.ts
+const STOREFRONT_SCHEMA_FILE_NAME = "storefront.schema.json";
+const CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME = "customer-account.schema.json";
+const STOREFRONT_OUTPUT_FILE_NAME = "storefront-graphql-env.d.ts";
+const CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME = "customer-account-graphql-env.d.ts";
+function createGraphQLPluginConfig(schemaDirectory) {
+	return {
+		name: "gql.tada/ts-plugin",
+		schemas: [{
+			name: "storefront",
+			schema: join(schemaDirectory, STOREFRONT_SCHEMA_FILE_NAME),
+			tadaOutputLocation: STOREFRONT_OUTPUT_FILE_NAME
+		}, {
+			name: "customer-account",
+			schema: join(schemaDirectory, CUSTOMER_ACCOUNT_SCHEMA_FILE_NAME),
+			tadaOutputLocation: CUSTOMER_ACCOUNT_OUTPUT_FILE_NAME
+		}],
+		trackFieldUsage: false
+	};
+}
+
+//#endregion
+//#region src/cli/gql.ts
+const GQL_TADA_CLI_PATH_FROM_PACKAGE_ROOT = "bin/cli.js";
+const PACKAGE_ROOT_FROM_CLI_MODULE$1 = "../../";
+const SUCCESS_EXIT_CODE$1 = 0;
+const TSCONFIG_FILE_NAME = "tsconfig.json";
+const TEMPORARY_TSCONFIG_PREFIX = ".hydrogen-gql-";
+const CHECK_LEVELS = new Set([
+	"info",
+	"warn",
+	"error"
+]);
+function findTsconfig(cwd, configuredPath) {
+	if (configuredPath) return resolve(cwd, configuredPath);
+	let directory = cwd;
+	const root = parse(directory).root;
+	while (directory !== root) {
+		const candidate = join(directory, TSCONFIG_FILE_NAME);
+		if (existsSync(candidate)) return candidate;
+		directory = dirname(directory);
+	}
+	const rootCandidate = join(root, TSCONFIG_FILE_NAME);
+	if (existsSync(rootCandidate)) return rootCandidate;
+	throw new Error(`Could not find ${TSCONFIG_FILE_NAME}.`);
+}
+function spawnRunCommand$1(command, args, options) {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			stdio: "inherit"
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === SUCCESS_EXIT_CODE$1) {
+				resolvePromise();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`Command failed with exit code ${code}: ${command} ${args.join(" ")}`));
+		});
+	});
+}
+function getPackageRoot$1() {
+	return resolve(import.meta.dirname, PACKAGE_ROOT_FROM_CLI_MODULE$1);
+}
+function getGqlTadaCliPath() {
+	return join(dirname(createRequire(import.meta.url).resolve("gql.tada/package.json")), GQL_TADA_CLI_PATH_FROM_PACKAGE_ROOT);
+}
+function parseCheckArgs(args) {
+	const { values } = parseArgs({
+		args,
+		options: {
+			"fail-on-warn": {
+				type: "boolean",
+				short: "w",
+				default: false
+			},
+			level: {
+				type: "string",
+				short: "l",
+				default: "info"
+			},
+			tsconfig: {
+				type: "string",
+				short: "c"
+			}
+		},
+		strict: true
+	});
+	if (!CHECK_LEVELS.has(values.level)) throw new Error(`Invalid diagnostic level: ${values.level}`);
+	return values;
+}
+async function checkGraphQL(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const packageRoot = options.packageRoot ?? getPackageRoot$1();
+	const gqlTadaCliPath = options.gqlTadaCliPath ?? getGqlTadaCliPath();
+	const runCommand = options.runCommand ?? spawnRunCommand$1;
+	const values = parseCheckArgs(options.args ?? []);
+	const tsconfigPath = findTsconfig(cwd, values.tsconfig);
+	const temporaryTsconfigPath = join(dirname(tsconfigPath), `${TEMPORARY_TSCONFIG_PREFIX}${randomUUID()}.json`);
+	const pluginConfig = createGraphQLPluginConfig(join(packageRoot, "dist"));
+	writeFileSync(temporaryTsconfigPath, JSON.stringify({
+		extends: tsconfigPath,
+		compilerOptions: { plugins: [pluginConfig] }
+	}), { flag: "wx" });
+	const cliArgs = [
+		gqlTadaCliPath,
+		"check",
+		"--tsconfig",
+		temporaryTsconfigPath,
+		"--level",
+		values.level
+	];
+	if (values["fail-on-warn"]) cliArgs.push("--fail-on-warn");
+	const cleanup = () => rmSync(temporaryTsconfigPath, { force: true });
+	process.once("exit", cleanup);
+	try {
+		await runCommand(process.execPath, cliArgs, { cwd });
+	} finally {
+		process.off("exit", cleanup);
+		cleanup();
+	}
+}
+
+//#endregion
+//#region src/core/utils/record.ts
+function isObjectRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+//#endregion
+//#region src/cli/setup.ts
+const PACKAGE_NAME = "@shopify/hydrogen";
+const PACKAGE_INSTALL_SPEC = `${PACKAGE_NAME}@preview`;
+const PACKAGE_ROOT_FROM_CLI_MODULE = "../../";
+const SKILLS_DIRECTORY_NAME = "skills";
+const CLAUDE_DIRECTORY_NAME = ".claude";
+const AGENTS_DIRECTORY_NAME = ".agents";
+const NODE_MODULES_DIRECTORY_NAME = "node_modules";
+const PACKAGE_JSON_FILE_NAME = "package.json";
+const SUCCESS_EXIT_CODE = 0;
+const PACKAGE_MANAGER_LOCKFILES = [
+	["pnpm", "pnpm-lock.yaml"],
+	["yarn", "yarn.lock"],
+	["npm", "package-lock.json"],
+	["bun", "bun.lockb"],
+	["bun", "bun.lock"]
+];
+const INSTALL_ARGS = {
+	pnpm: ["add", PACKAGE_INSTALL_SPEC],
+	npm: ["install", PACKAGE_INSTALL_SPEC],
+	yarn: ["add", PACKAGE_INSTALL_SPEC],
+	bun: ["add", PACKAGE_INSTALL_SPEC]
+};
+function getStringRecord(value) {
+	if (!isObjectRecord(value)) return void 0;
+	const entries = Object.entries(value);
+	if (entries.some(([, entryValue]) => typeof entryValue !== "string")) return void 0;
+	return Object.fromEntries(entries);
+}
+function readPackageJson(appRoot) {
+	const packageJsonPath = join(appRoot, PACKAGE_JSON_FILE_NAME);
+	if (!existsSync(packageJsonPath)) throw new Error(`No ${PACKAGE_JSON_FILE_NAME} found. Run this command from the app root.`);
+	const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+	if (!isObjectRecord(parsed)) throw new Error(`${PACKAGE_JSON_FILE_NAME} must contain a JSON object.`);
+	return {
+		packageManager: typeof parsed.packageManager === "string" ? parsed.packageManager : void 0,
+		dependencies: getStringRecord(parsed.dependencies),
+		devDependencies: getStringRecord(parsed.devDependencies)
+	};
+}
+function parsePackageManager(value) {
+	if (!value) return void 0;
+	for (const packageManager of Object.keys(INSTALL_ARGS)) {
+		if (value === packageManager) return packageManager;
+		if (value.startsWith(`${packageManager}@`)) return packageManager;
+		if (value.startsWith(`${packageManager}/`)) return packageManager;
+	}
+}
+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.");
+}
+function hasHydrogenDependency(packageJson) {
+	return Boolean(packageJson.dependencies?.[PACKAGE_NAME] ?? packageJson.devDependencies?.[PACKAGE_NAME]);
+}
+async function installHydrogen(appRoot, packageManager, runCommand) {
+	await runCommand(packageManager, [...INSTALL_ARGS[packageManager]], { cwd: appRoot });
+}
+function assertDirectory(directoryPath, message) {
+	if (!existsSync(directoryPath) || !statSync(directoryPath).isDirectory()) throw new Error(message);
+}
+function getSkillsDestinationRoots(appRoot) {
+	const destinationRoots = [];
+	const claudeDirectory = join(appRoot, CLAUDE_DIRECTORY_NAME);
+	if (existsSync(claudeDirectory)) {
+		assertDirectory(claudeDirectory, `${CLAUDE_DIRECTORY_NAME} exists but is not a directory.`);
+		destinationRoots.push(join(claudeDirectory, SKILLS_DIRECTORY_NAME));
+	}
+	const agentsDirectory = join(appRoot, AGENTS_DIRECTORY_NAME);
+	if (existsSync(agentsDirectory)) {
+		assertDirectory(agentsDirectory, `${AGENTS_DIRECTORY_NAME} exists but is not a directory.`);
+		destinationRoots.push(join(agentsDirectory, SKILLS_DIRECTORY_NAME));
+	}
+	return destinationRoots.length > 0 ? destinationRoots : [join(appRoot, AGENTS_DIRECTORY_NAME, SKILLS_DIRECTORY_NAME)];
+}
+function getSkillNames(sourceSkillsRoot) {
+	assertDirectory(sourceSkillsRoot, `No packaged skills found at ${sourceSkillsRoot}.`);
+	return readdirSync(sourceSkillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+function findConflictingSkills(destinationRoot, skillNames) {
+	return skillNames.filter((skillName) => existsSync(join(destinationRoot, skillName, "SKILL.md")));
+}
+function removeIncompleteSkills(destinationRoot, skillNames) {
+	for (const skillName of skillNames) {
+		const destinationPath = join(destinationRoot, skillName);
+		if (!existsSync(destinationPath)) continue;
+		if (existsSync(join(destinationPath, "SKILL.md"))) continue;
+		rmSync(destinationPath, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function copySkills(packageRoot, appRoot) {
+	const sourceSkillsRoot = join(packageRoot, SKILLS_DIRECTORY_NAME);
+	const destinationRoots = getSkillsDestinationRoots(appRoot);
+	const skillNames = getSkillNames(sourceSkillsRoot);
+	const conflictingSkills = destinationRoots.flatMap((destinationRoot) => findConflictingSkills(destinationRoot, skillNames).map((skillName) => join(destinationRoot, skillName)));
+	if (conflictingSkills.length > 0) throw new Error(`Skill directories already exist: ${conflictingSkills.join(", ")}. Remove them and rerun setup.`);
+	for (const destinationRoot of destinationRoots) {
+		removeIncompleteSkills(destinationRoot, skillNames);
+		mkdirSync(destinationRoot, { recursive: true });
+		for (const skillName of skillNames) cpSync(join(sourceSkillsRoot, skillName), join(destinationRoot, skillName), {
+			recursive: true,
+			errorOnExist: true,
+			force: false
+		});
+	}
+	return {
+		destinationRoots,
+		copiedCount: skillNames.length * destinationRoots.length
+	};
+}
+function getPackageRoot() {
+	return fileURLToPath(new URL(PACKAGE_ROOT_FROM_CLI_MODULE, import.meta.url));
+}
+function getLocalPackageRoot(appRoot) {
+	const localPackageRoot = join(appRoot, NODE_MODULES_DIRECTORY_NAME, PACKAGE_NAME);
+	if (!existsSync(localPackageRoot)) return void 0;
+	assertDirectory(localPackageRoot, `${localPackageRoot} exists but is not a directory.`);
+	return realpathSync(localPackageRoot);
+}
+function spawnRunCommand(command, args, options) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			stdio: "inherit"
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === SUCCESS_EXIT_CODE) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`Command failed with exit code ${code}: ${command} ${args.join(" ")}`));
+		});
+	});
+}
+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 packageJson = readPackageJson(appRoot);
+	if (!hasHydrogenDependency(packageJson)) {
+		const packageManager = detectPackageManager(appRoot, packageJson, env);
+		log(`Installing ${PACKAGE_NAME} with ${packageManager}...`);
+		await installHydrogen(appRoot, packageManager, runCommand);
+	}
+	const result = copySkills(options.packageRoot ?? getLocalPackageRoot(appRoot) ?? getPackageRoot(), appRoot);
+	log(`Copied ${result.copiedCount} Hydrogen skills to ${result.destinationRoots.join(", ")}.`);
+}
+
+//#endregion
+//#region src/cli/index.ts
+const CLI_ARGUMENTS_INDEX = 2;
+const FAILURE_EXIT_CODE = 1;
+const COMMANDS = [{
+	path: ["setup"],
+	run: async (_args) => setupHydrogen()
+}, {
+	path: ["gql", "check"],
+	run: async (args) => checkGraphQL({ args })
+}];
+function commandMatches(path, args) {
+	return path.every((segment, index) => args[index] === segment);
+}
+function runCli() {
+	const args = process.argv.slice(CLI_ARGUMENTS_INDEX);
+	const command = COMMANDS.find(({ path }) => commandMatches(path, args));
+	if (!command) {
+		const commandName = args.join(" ");
+		const availableCommands = COMMANDS.map(({ path }) => path.join(" ")).join(", ");
+		console.error(commandName ? `Unknown command: ${commandName}` : "No command specified.");
+		console.error(`Available commands: ${availableCommands}`);
+		process.exit(FAILURE_EXIT_CODE);
+	}
+	command.run(args.slice(command.path.length)).catch((error) => {
+		console.error(error instanceof Error ? error.message : "An unexpected error occurred");
+		process.exit(FAILURE_EXIT_CODE);
+	});
+}
+if (process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) runCli();
+
+//#endregion
+export { runCli };

package/dist/client/client.d.mts

@@ -0,0 +1,34 @@
+import { CachingStrategy } from "../core/cache/strategies.mjs";
+import { CacheInstance } from "../core/cache/run-with-cache.mjs";
+import { ShopifyRequestContext } from "../core/request-context.mjs";
+import { ClientType, CreateStorefrontClientArgs, StorefrontClient } from "./types.mjs";
+
+//#region src/client/client.d.ts
+/**
+ * Creates a type-safe Storefront API client.
+ *
+ * Pick a `type` based on where your code runs and whether buyer context is available:
+ *
+ * |                 | public                         | private                       | private_no_buyer_context |
+ * |-----------------|--------------------------------|-------------------------------|--------------------------|
+ * | Runs in         | Browser or mobile              | Server (SSR)                  | Server (background)      |
+ * | Token           | Public access token, or none   | Private access token          | Private access token     |
+ * | Buyer context   | Browser request context        | You forward trusted `buyerIp` | None                     |
+ * | Best for        | Client-side fetches            | SSR with buyer context        | Webhooks, background jobs |
+ *
+ * Pass `requestContext` so the client's SFAPI requests carry request-scoped
+ * headers, follow the incoming request's abort signal, and read the resolved
+ * `i18n` used for Storefront API variable injection and localized routes.
+ *
+ * Token-based access is required for some Storefront API fields, including
+ * product tags, metaobjects, metafields, menus, and customers. Use a private
+ * client only in trusted server code where the token cannot leak to browsers.
+ *
+ * @see {@link https://shopify.dev/docs/api/storefront#authentication | Storefront API authentication}
+ */
+declare function createStorefrontClient<const Type extends ClientType, const RequestContext extends ShopifyRequestContext, const CacheConfig extends CacheInstance | undefined = undefined>(args: CreateStorefrontClientArgs<RequestContext, Type, CacheConfig>): StorefrontClient<[CacheConfig] extends [CacheInstance] ? {
+  cache?: CachingStrategy;
+} : {}, Type, RequestContext>;
+//#endregion
+export { createStorefrontClient };
+//# sourceMappingURL=client.d.mts.map

package/dist/client/client.mjs

@@ -0,0 +1,193 @@
+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 { 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 { StorefrontApiError, StorefrontTimeoutError } from "./errors.mjs";
+
+//#region src/client/client.ts
+const COUNTRY_VAR_RE = /\$country\s*:/;
+const LANGUAGE_VAR_RE = /\$language\s*:/;
+const REQUEST_CACHE_KEY_HEADERS = new Set([
+	"content-type",
+	"user-agent",
+	SDK_VARIANT_HEADER.toLowerCase(),
+	SDK_VARIANT_SOURCE_HEADER.toLowerCase(),
+	SDK_VERSION_HEADER.toLowerCase(),
+	HYDROGEN_VERSION_HEADER.toLowerCase(),
+	STOREFRONT_ACCESS_TOKEN_HEADER.toLowerCase(),
+	STOREFRONT_PRIVATE_TOKEN_HEADER.toLowerCase()
+]);
+const REQUEST_IDENTITY_HEADERS = new Set([
+	"cookie",
+	REQUEST_GROUP_ID_HEADER.toLowerCase(),
+	STOREFRONT_BUYER_IP_HEADER.toLowerCase(),
+	SHOPIFY_UNIQUE_TOKEN_HEADER.toLowerCase(),
+	SHOPIFY_VISIT_TOKEN_HEADER.toLowerCase(),
+	SHOPIFY_STOREFRONT_Y_HEADER.toLowerCase(),
+	SHOPIFY_STOREFRONT_S_HEADER.toLowerCase()
+]);
+var StorefrontCacheConfigError = class extends Error {};
+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 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({
+		cache: config.cache,
+		waitUntil: config.waitUntil,
+		fetch: originFetch
+	}) : originFetch;
+	const timeoutInMs = config.defaultTimeoutInMs ?? 3e4;
+	if (timeoutInMs < 0 || Number.isNaN(timeoutInMs)) throw new Error("defaultTimeoutInMs must be a non-negative number");
+	const staticHeaders = { "content-type": "application/json" };
+	if (config.storefrontId) staticHeaders[STOREFRONT_ID_HEADER] = config.storefrontId;
+	switch (clientType) {
+		case "private":
+		case "private_no_buyer_context":
+			if (typeof document !== "undefined") throw new Error("private storefront tokens cannot be used in a browser context. Use a publicStorefrontToken instead.");
+			if (!config.privateStorefrontToken) throw new Error("privateStorefrontToken is required");
+			staticHeaders[STOREFRONT_PRIVATE_TOKEN_HEADER] = config.privateStorefrontToken;
+			break;
+		case "public":
+			if (config.publicStorefrontToken !== void 0 && !config.publicStorefrontToken) throw new Error("publicStorefrontToken must be non-empty when provided");
+			if (config.publicStorefrontToken) staticHeaders[STOREFRONT_ACCESS_TOKEN_HEADER] = config.publicStorefrontToken;
+			break;
+		default: throw new Error(`Unsupported client type: ${clientType}`);
+	}
+	const i18n = requestContext.i18n;
+	const requestHeaders = new Headers(staticHeaders);
+	requestContext.applyStorefrontRequestHeaders(requestHeaders);
+	if (clientType === "private") {
+		const { buyerIp } = requestContext;
+		if (!buyerIp) throw new TypeError("requestContext.buyerIp is required for private Storefront API clients");
+		requestHeaders.set(STOREFRONT_BUYER_IP_HEADER, buyerIp);
+	}
+	async function graphql(doc, ...rest) {
+		const opts = rest[0] ?? {};
+		const queryText = typeof doc === "string" ? doc : doc;
+		if (typeof queryText !== "string") throw new StorefrontApiError("Expected gql() to return a string at runtime. Check gql.tada version compatibility.");
+		if (opts.cache && !config.cache) throw new StorefrontCacheConfigError("Storefront API cache options require a cache configured in createStorefrontClient().");
+		if (opts.cache?.mode === "private") throw new StorefrontCacheConfigError("Storefront API cache mode 'private' is not supported yet. Use Cache() without private mode, or cache buyer-specific work with createRunWithCache() and an explicit private key.");
+		const variables = buildVariables(queryText, opts.variables, i18n);
+		const externalSignals = [requestContext.signal, opts.signal].filter((signal) => Boolean(signal));
+		const earlyAbortSignal = externalSignals.find((signal) => signal.aborted);
+		if (earlyAbortSignal) throw earlyAbortSignal.reason ?? new DOMException("signal is aborted without reason", "AbortError");
+		let requestId;
+		let responseHeaders;
+		let responseText;
+		let status;
+		let timeoutSignal;
+		if (timeoutInMs > 0) {
+			timeoutSignal = AbortSignal.timeout(timeoutInMs);
+			externalSignals.push(timeoutSignal);
+		}
+		try {
+			const init = {
+				method: "POST",
+				headers: new Headers(requestHeaders),
+				body: JSON.stringify({
+					query: queryText,
+					variables
+				}),
+				signal: externalSignals.length > 0 ? AbortSignal.any(externalSignals) : void 0
+			};
+			const response = await resolvedFetch(apiUrl, init, createStorefrontCacheOptions(apiUrl, init, queryText, opts.cache));
+			responseHeaders = response.headers;
+			if (getHydrogenCacheStatus(responseHeaders) !== "hit") requestContext.captureSubrequestHeaders(responseHeaders);
+			requestId = responseHeaders.get("x-request-id") ?? void 0;
+			status = response.status;
+			if (!response.ok) {
+				const bodyHint = await response.text().catch(() => "");
+				throw new StorefrontApiError(`SFAPI responded with ${status}${bodyHint ? `: ${bodyHint.slice(0, 200)}` : ""}`, {
+					status,
+					requestId,
+					queryText,
+					variables
+				});
+			}
+			responseText = await response.text();
+		} catch (error) {
+			if (error instanceof StorefrontApiError) throw error;
+			if (error instanceof StorefrontTimeoutError) throw error;
+			if (error instanceof StorefrontCacheConfigError) throw error;
+			if (error instanceof DOMException && error.name === "TimeoutError" && timeoutSignal?.aborted) throw new StorefrontTimeoutError(timeoutInMs);
+			if (error instanceof DOMException && error.name === "AbortError") throw error;
+			throw new StorefrontApiError("SFAPI request failed", { cause: error });
+		}
+		let json;
+		try {
+			json = JSON.parse(responseText);
+		} catch (cause) {
+			throw new StorefrontApiError(`Failed to parse SFAPI response as JSON (${apiUrl}, status ${status})` + (responseText ? `: ${responseText.slice(0, 200)}` : ""), {
+				status,
+				requestId,
+				cause,
+				queryText,
+				variables
+			});
+		}
+		if (typeof json !== "object" || json === null || Array.isArray(json)) throw new StorefrontApiError(`SFAPI returned unexpected JSON type: ${Array.isArray(json) ? "array" : typeof json}`, {
+			status,
+			requestId,
+			queryText,
+			variables
+		});
+		const body = json;
+		if (body.errors) return {
+			data: body.data ?? null,
+			errors: body.errors,
+			headers: responseHeaders
+		};
+		return {
+			data: body.data,
+			headers: responseHeaders
+		};
+	}
+	return {
+		type: clientType,
+		i18n,
+		graphql,
+		apiUrl,
+		storeUrl,
+		storefrontId: config.storefrontId,
+		requestContext
+	};
+}
+function buildVariables(queryText, userVariables, resolvedI18n) {
+	const variables = { ...userVariables };
+	if (COUNTRY_VAR_RE.test(queryText)) variables.country = resolvedI18n.country;
+	if (LANGUAGE_VAR_RE.test(queryText)) variables.language = resolvedI18n.language;
+	return variables;
+}
+function createStorefrontCacheOptions(apiUrl, init, queryText, strategy) {
+	if (!strategy) return void 0;
+	if (/\bmutation\b/.test(queryText)) return void 0;
+	return {
+		key: createStorefrontCacheKey(apiUrl, init),
+		strategy,
+		shouldCacheResponse: async ({ json }) => {
+			if (!json) return false;
+			const body = await json().catch(() => void 0);
+			return typeof body === "object" && body != null && !Array.isArray(body) && !("errors" in body);
+		}
+	};
+}
+function createStorefrontCacheKey(apiUrl, init) {
+	return [
+		"storefront-api",
+		apiUrl,
+		init.method,
+		init.body,
+		[...init.headers].filter(([name]) => {
+			const normalized = name.toLowerCase();
+			return REQUEST_CACHE_KEY_HEADERS.has(normalized) && !REQUEST_IDENTITY_HEADERS.has(normalized);
+		}).toSorted(([left], [right]) => left.localeCompare(right)).map(([name, value]) => `${name}:${value}`).join("\n")
+	];
+}
+
+//#endregion
+export { createStorefrontClient };
+//# sourceMappingURL=client.mjs.map