@shopify/hydrogen 2026.10.1 → 2026.10.2

package/dist/cli/index.mjs

@@ -1048,16 +1048,17 @@ async function scaffoldTemplate(appRoot, env, runCommand, log) {
 }
 async function ensureHydrogenInstalled(appRoot, env, runCommand, log) {
 	const packageJson = readPackageJson(appRoot);
-	if (hasHydrogenDependency(packageJson) && getInstalledPackageRoot(appRoot)) return;
+	if (hasHydrogenDependency(packageJson) && getInstalledPackageRoot(appRoot)) return { addedHydrogen: false };
 	if (hasHydrogenDependency(packageJson)) {
 		const packageManager = detectPackageManager(appRoot, packageJson, env);
 		log(`${PACKAGE_NAME} is declared but not installed. Running ${packageManager} install...`);
 		await runCommand(packageManager, ["install"], { cwd: appRoot });
-		return;
+		return { addedHydrogen: false };
 	}
 	const packageManager = detectPackageManager(appRoot, packageJson, env);
 	log(`Installing ${PACKAGE_NAME} with ${packageManager}...`);
 	await installHydrogen(appRoot, packageManager, runCommand);
+	return { addedHydrogen: true };
 }
 function resolveSetupOptions(options) {
 	const env = options.env ?? process.env;
@@ -1075,7 +1076,8 @@ function isEmptyDirectory(dir) {
 }
 async function setupHydrogen(options = {}) {
 	const { appRoot, env, runCommand, log, prompt } = resolveSetupOptions(options);
-	if (hasPackageJson(appRoot)) await ensureHydrogenInstalled(appRoot, env, runCommand, log);
+	let addedHydrogen = false;
+	if (hasPackageJson(appRoot)) ({addedHydrogen} = await ensureHydrogenInstalled(appRoot, env, runCommand, log));
 	else if (isEmptyDirectory(appRoot)) {
 		let choice;
 		if (prompt) choice = await prompt(log);
@@ -1091,6 +1093,7 @@ async function setupHydrogen(options = {}) {
 		packageRoot: options.packageRoot,
 		log
 	});
+	if (addedHydrogen) log("Setup is ready. Next: ask your agent to use the hydrogen-setup skill.");
 }
 
 //#endregion

package/dist/client/client.mjs

@@ -4,10 +4,9 @@ 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 { StorefrontApiError, StorefrontTimeoutError } from "./errors.mjs";
+import { getI18nVariableNames } from "./i18n-variables.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",
@@ -174,8 +173,7 @@ function createStorefrontClient(args) {
 }
 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;
+	for (const name of getI18nVariableNames(queryText)) variables[name] = resolvedI18n[name];
 	return variables;
 }
 function createStorefrontCacheOptions(apiUrl, init, queryText, strategy, shouldCacheResult, backgroundTimeoutInMs) {

package/dist/client/client.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"client.mjs","names":[],"sources":["../../src/client/client.ts"],"sourcesContent":["import type { TadaDocumentNode } from \"gql.tada\";\n\nimport { getHydrogenCacheStatus } from \"../core/cache/cache-status\";\nimport { createFetchWithCache } from \"../core/cache/fetch-with-cache\";\nimport type { FetchCacheOptions, FetchCacheResponseContext } from \"../core/cache/fetch-with-cache\";\nimport type { CacheInstance } from \"../core/cache/run-with-cache\";\nimport type { CachingStrategy } from \"../core/cache/strategies\";\nimport { DEFAULT_TIMEOUT_IN_MS, STOREFRONT_API_VERSION } from \"../core/constants\";\nimport {\n  HYDROGEN_VERSION_HEADER,\n  REQUEST_GROUP_ID_HEADER,\n  SDK_VARIANT_HEADER,\n  SDK_VARIANT_SOURCE_HEADER,\n  SDK_VERSION_HEADER,\n  SHOPIFY_STOREFRONT_S_HEADER,\n  SHOPIFY_STOREFRONT_Y_HEADER,\n  STOREFRONT_ACCESS_TOKEN_HEADER,\n  STOREFRONT_BUYER_IP_HEADER,\n  STOREFRONT_ID_HEADER,\n  STOREFRONT_PRIVATE_TOKEN_HEADER,\n  SHOPIFY_UNIQUE_TOKEN_HEADER,\n  SHOPIFY_VISIT_TOKEN_HEADER,\n} from \"../core/headers\";\nimport type { I18nConfig, ShopifyRequestContext } from \"../core/request-context\";\nimport { normalizeStoreDomain } from \"../core/url\";\nimport type { AnyStorefrontQueryString } from \"../graphql\";\nimport { StorefrontApiError, StorefrontTimeoutError } from \"./errors\";\nimport type {\n  ClientType,\n  CreateStorefrontClientArgs,\n  GraphQLFormattedError,\n  StorefrontClient,\n  StorefrontGraphqlResult,\n} from \"./types\";\n\ntype DocLike = TadaDocumentNode<unknown, unknown> | AnyStorefrontQueryString;\ntype FetchInput = Parameters<typeof globalThis.fetch>[0];\ntype FetchInit = Parameters<typeof globalThis.fetch>[1];\ntype ResolvedStorefrontFetch = (\n  input: FetchInput,\n  init: FetchInit,\n  cacheOptions: FetchCacheOptions | undefined,\n) => Promise<Response>;\n\nconst COUNTRY_VAR_RE = /\\$country\\s*:/;\nconst LANGUAGE_VAR_RE = /\\$language\\s*:/;\nconst REQUEST_CACHE_KEY_HEADERS = new Set([\n  \"content-type\",\n  \"user-agent\",\n  SDK_VARIANT_HEADER.toLowerCase(),\n  SDK_VARIANT_SOURCE_HEADER.toLowerCase(),\n  SDK_VERSION_HEADER.toLowerCase(),\n  HYDROGEN_VERSION_HEADER.toLowerCase(),\n  STOREFRONT_ACCESS_TOKEN_HEADER.toLowerCase(),\n  STOREFRONT_PRIVATE_TOKEN_HEADER.toLowerCase(),\n]);\nconst REQUEST_IDENTITY_HEADERS = new Set([\n  \"cookie\",\n  REQUEST_GROUP_ID_HEADER.toLowerCase(),\n  STOREFRONT_BUYER_IP_HEADER.toLowerCase(),\n  SHOPIFY_UNIQUE_TOKEN_HEADER.toLowerCase(),\n  SHOPIFY_VISIT_TOKEN_HEADER.toLowerCase(),\n  SHOPIFY_STOREFRONT_Y_HEADER.toLowerCase(),\n  SHOPIFY_STOREFRONT_S_HEADER.toLowerCase(),\n]);\nconst CACHE_ENABLED_GRAPHQL_CLIENTS = new WeakSet<StorefrontClient[\"graphql\"]>();\nconst SHOULD_CACHE_RESULT = Symbol();\n\ntype ShouldCacheResult = (body: object) => boolean;\n\nclass StorefrontCacheConfigError extends Error {}\n\nexport function withStorefrontClientCache<TOptions extends object>(\n  client: Pick<StorefrontClient, \"graphql\">,\n  options: TOptions,\n  strategy: CachingStrategy,\n  shouldCacheResult?: ShouldCacheResult,\n): TOptions {\n  if (!CACHE_ENABLED_GRAPHQL_CLIENTS.has(client.graphql)) return options;\n\n  return { ...options, cache: strategy, [SHOULD_CACHE_RESULT]: shouldCacheResult };\n}\n\n/**\n * Creates a Storefront API client that runs typed queries and mutations against your store.\n *\n * Set `type` based on where your code runs and whether customer context is available:\n *\n * |                  | `public`                   | `private`                   | `private_no_buyer_context` |\n * |------------------|------------------------------|-------------------------------|------------------------------|\n * | Runs in          | Browser or mobile            | Server-side rendering         | Background server code    |\n * | Token            | Public access token, or none | Private access token          | Private access token      |\n * | Customer context | Browser request context      | You forward trusted `buyerIp` | None                      |\n * | Best for         | Client-side fetches          | SSR with customer context     | Webhooks, background jobs |\n *\n * Pass a request context from `createShopifyRequestContext`. The client forwards the incoming\n * request's cookies and `Sec-GPC` header to the Storefront API, and fills `$country`\n * and `$language` variables from the context's locale. The client reads the request headers once,\n * when you create the client. Create a client for each incoming request, and create a client at\n * module scope only with a static request context.\n *\n * Keep private clients in server code, where the token can't reach browsers. The function throws an\n * error when you create either private client type in a browser. The function throws a `TypeError`\n * when the request context of a `private` client has no `buyerIp`.\n *\n * @see [Storefront API authentication](https://shopify.dev/docs/api/storefront#authentication)\n * @publicDocs\n */\nexport function createStorefrontClient<\n  const Type extends ClientType,\n  const RequestContext extends ShopifyRequestContext,\n  const CacheConfig extends CacheInstance | undefined = undefined,\n>(\n  args: CreateStorefrontClientArgs<RequestContext, Type, CacheConfig>,\n): StorefrontClient<\n  // Tuple-wrapped to stay non-distributive so an explicit\n  // `CacheInstance | undefined` type argument yields one client type, not a\n  // union. Note a *value* of that type still unlocks cache options: optional\n  // property inference strips `undefined` before it reaches CacheConfig, so\n  // definiteness is undecidable here — the runtime guard rejects cache\n  // options when no cache instance was actually configured.\n  [CacheConfig] extends [CacheInstance] ? { cache?: CachingStrategy } : {},\n  Type,\n  RequestContext\n>;\n/**\n * @param args The client type, request context, and store configuration for the new client.\n * @returns The client, with a `graphql()` method that runs queries and mutations.\n */\nexport function createStorefrontClient(args: CreateStorefrontClientArgs): StorefrontClient {\n  const { config, requestContext, type: clientType } = args;\n\n  if (!config.storeDomain) {\n    throw new Error(\"storeDomain is required and must be non-empty\");\n  }\n\n  const storeUrl = normalizeStoreDomain(config.storeDomain);\n  const apiVersion = config.apiVersion ?? STOREFRONT_API_VERSION;\n  const apiUrl = `${storeUrl}/api/${apiVersion}/graphql.json`;\n\n  const originFetch = config.fetch ?? globalThis.fetch;\n  if (typeof originFetch !== \"function\") {\n    throw new Error(\n      \"No fetch function available. Pass a fetch option or ensure globalThis.fetch exists.\",\n    );\n  }\n  const resolvedFetch = config.cache\n    ? createFetchWithCache({\n        cache: config.cache,\n        waitUntil: config.waitUntil,\n        fetch: originFetch as typeof globalThis.fetch,\n      })\n    : originFetch;\n\n  const timeoutInMs = config.defaultTimeoutInMs ?? DEFAULT_TIMEOUT_IN_MS;\n  if (timeoutInMs < 0 || Number.isNaN(timeoutInMs)) {\n    throw new Error(\"defaultTimeoutInMs must be a non-negative number\");\n  }\n\n  const staticHeaders: Record<string, string> = {\n    \"content-type\": \"application/json\",\n  };\n  if (config.storefrontId) {\n    staticHeaders[STOREFRONT_ID_HEADER] = config.storefrontId;\n  }\n\n  switch (clientType) {\n    case \"private\":\n    case \"private_no_buyer_context\":\n      if (typeof document !== \"undefined\") {\n        throw new Error(\n          \"private storefront tokens cannot be used in a browser context. Use a publicStorefrontToken instead.\",\n        );\n      }\n      if (!config.privateStorefrontToken) {\n        throw new Error(\"privateStorefrontToken is required\");\n      }\n      staticHeaders[STOREFRONT_PRIVATE_TOKEN_HEADER] = config.privateStorefrontToken;\n      break;\n    case \"public\":\n      if (config.publicStorefrontToken !== undefined && !config.publicStorefrontToken) {\n        throw new Error(\"publicStorefrontToken must be non-empty when provided\");\n      }\n      if (config.publicStorefrontToken) {\n        staticHeaders[STOREFRONT_ACCESS_TOKEN_HEADER] = config.publicStorefrontToken;\n      }\n      break;\n    default:\n      clientType satisfies never;\n      throw new Error(`Unsupported client type: ${clientType}`);\n  }\n\n  const i18n = requestContext.i18n;\n  const requestHeaders = new Headers(staticHeaders);\n  requestContext.applyStorefrontRequestHeaders(requestHeaders);\n\n  if (clientType === \"private\") {\n    const { buyerIp } = requestContext;\n    if (!buyerIp) {\n      throw new TypeError(\"requestContext.buyerIp is required for private Storefront API clients\");\n    }\n    requestHeaders.set(STOREFRONT_BUYER_IP_HEADER, buyerIp);\n  }\n\n  async function graphql(\n    doc: DocLike | string,\n    ...rest: [options?: Record<string, unknown>]\n  ): Promise<StorefrontGraphqlResult<DocLike>> {\n    const opts = (rest[0] ?? {}) as {\n      variables?: Record<string, unknown>;\n      signal?: AbortSignal;\n      cache?: CachingStrategy;\n      [SHOULD_CACHE_RESULT]?: ShouldCacheResult;\n    };\n\n    const queryText = typeof doc === \"string\" ? doc : (doc as unknown as string);\n    if (typeof queryText !== \"string\") {\n      throw new StorefrontApiError(\n        \"Expected gql() to return a string at runtime. Check gql.tada version compatibility.\",\n      );\n    }\n\n    if (opts.cache && !config.cache) {\n      throw new StorefrontCacheConfigError(\n        \"Storefront API cache options require a cache configured in createStorefrontClient().\",\n      );\n    }\n\n    if (opts.cache?.mode === \"private\") {\n      throw new StorefrontCacheConfigError(\n        \"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.\",\n      );\n    }\n\n    const variables = buildVariables(queryText, opts.variables, i18n);\n    const externalSignals = [requestContext.signal, opts.signal].filter(\n      (signal): signal is AbortSignal => Boolean(signal),\n    );\n\n    const earlyAbortSignal = externalSignals.find((signal) => signal.aborted);\n    if (earlyAbortSignal) {\n      throw (\n        earlyAbortSignal.reason ??\n        new DOMException(\"signal is aborted without reason\", \"AbortError\")\n      );\n    }\n\n    let requestId: string | undefined;\n    let responseHeaders: Headers;\n    let responseText: string;\n    let status: number;\n    let timeoutSignal: AbortSignal | undefined;\n\n    if (timeoutInMs > 0) {\n      timeoutSignal = AbortSignal.timeout(timeoutInMs);\n      externalSignals.push(timeoutSignal);\n    }\n\n    try {\n      const init: PlainRequestInit = {\n        method: \"POST\",\n        headers: new Headers(requestHeaders),\n        body: JSON.stringify({ query: queryText, variables }),\n        signal: externalSignals.length > 0 ? AbortSignal.any(externalSignals) : undefined,\n      };\n\n      const cacheOptions = createStorefrontCacheOptions(\n        apiUrl,\n        init,\n        queryText,\n        opts.cache,\n        opts[SHOULD_CACHE_RESULT],\n        timeoutInMs > 0 ? timeoutInMs : DEFAULT_TIMEOUT_IN_MS,\n      );\n      const response = await (resolvedFetch as ResolvedStorefrontFetch)(apiUrl, init, cacheOptions);\n\n      responseHeaders = response.headers;\n      const hydrogenCacheStatus = getHydrogenCacheStatus(responseHeaders);\n      if (hydrogenCacheStatus !== \"hit\") {\n        requestContext.captureSubrequestHeaders(responseHeaders);\n      }\n\n      requestId = responseHeaders.get(\"x-request-id\") ?? undefined;\n      status = response.status;\n\n      if (!response.ok) {\n        const bodyHint = await response.text().catch(() => \"\");\n        throw new StorefrontApiError(\n          `SFAPI responded with ${status}${bodyHint ? `: ${bodyHint.slice(0, 200)}` : \"\"}`,\n          { status, requestId, queryText, variables },\n        );\n      }\n\n      responseText = await response.text();\n    } catch (error) {\n      if (error instanceof StorefrontApiError) throw error;\n      if (error instanceof StorefrontTimeoutError) throw error;\n      if (error instanceof StorefrontCacheConfigError) throw error;\n      if (\n        error instanceof DOMException &&\n        error.name === \"TimeoutError\" &&\n        timeoutSignal?.aborted\n      ) {\n        throw new StorefrontTimeoutError(timeoutInMs);\n      }\n      if (error instanceof DOMException && error.name === \"AbortError\") {\n        throw error;\n      }\n      throw new StorefrontApiError(\"SFAPI request failed\", { cause: error });\n    }\n\n    let json: unknown;\n    try {\n      json = JSON.parse(responseText);\n    } catch (cause) {\n      throw new StorefrontApiError(\n        `Failed to parse SFAPI response as JSON (${apiUrl}, status ${status})` +\n          (responseText ? `: ${responseText.slice(0, 200)}` : \"\"),\n        { status, requestId, cause, queryText, variables },\n      );\n    }\n\n    if (typeof json !== \"object\" || json === null || Array.isArray(json)) {\n      throw new StorefrontApiError(\n        `SFAPI returned unexpected JSON type: ${Array.isArray(json) ? \"array\" : typeof json}`,\n        { status, requestId, queryText, variables },\n      );\n    }\n\n    const body = json as { data?: unknown; errors?: GraphQLFormattedError[] };\n    // Branch to populate the two arms of the StorefrontGraphqlResult union: callers\n    // narrowing on `errors` get a non-null `data` only when no errors are present.\n    if (body.errors) {\n      return {\n        data: body.data ?? null,\n        errors: body.errors,\n        headers: responseHeaders,\n      };\n    }\n    return {\n      data: body.data,\n      headers: responseHeaders,\n    };\n  }\n\n  const client: StorefrontClient = {\n    type: clientType,\n    i18n,\n    graphql: graphql as StorefrontClient[\"graphql\"],\n    apiUrl,\n    storeUrl,\n    storefrontId: config.storefrontId,\n    requestContext,\n  };\n\n  if (config.cache) CACHE_ENABLED_GRAPHQL_CLIENTS.add(client.graphql);\n\n  return client;\n}\n\nfunction buildVariables(\n  queryText: string,\n  userVariables: Record<string, unknown> | undefined,\n  resolvedI18n: I18nConfig,\n): Record<string, unknown> {\n  const variables: Record<string, unknown> = { ...userVariables };\n\n  if (COUNTRY_VAR_RE.test(queryText)) {\n    variables.country = resolvedI18n.country;\n  }\n  if (LANGUAGE_VAR_RE.test(queryText)) {\n    variables.language = resolvedI18n.language;\n  }\n\n  return variables;\n}\n\ntype PlainRequestInit = RequestInit & { headers: Headers; body: string; method: string };\n\nfunction createStorefrontCacheOptions(\n  apiUrl: string,\n  init: PlainRequestInit,\n  queryText: string,\n  strategy: CachingStrategy | undefined,\n  shouldCacheResult: ShouldCacheResult | undefined,\n  backgroundTimeoutInMs: number,\n): FetchCacheOptions | undefined {\n  if (!strategy) return undefined;\n\n  // Runtime only needs a safety belt for untyped callers. False positives are\n  // acceptable because they bypass cache rather than risking mutation caching.\n  if (/\\bmutation\\b/.test(queryText)) return undefined;\n\n  return {\n    key: createStorefrontCacheKey(apiUrl, init),\n    strategy,\n    shouldCacheResponse: async ({ json }: FetchCacheResponseContext) => {\n      if (!json) return false;\n\n      const body = await json().catch(() => undefined);\n      if (typeof body !== \"object\" || body == null || Array.isArray(body) || \"errors\" in body) {\n        return false;\n      }\n\n      return shouldCacheResult?.(body) ?? true;\n    },\n    // A refresh outlives the request that triggered it, so request and caller\n    // aborts must not cancel it. It still needs a deadline, even when the caller\n    // disabled the client timeout to own the foreground one.\n    backgroundSignal: () => AbortSignal.timeout(backgroundTimeoutInMs),\n  };\n}\n\nfunction createStorefrontCacheKey(apiUrl: string, init: PlainRequestInit) {\n  return [\n    \"storefront-api\",\n    apiUrl,\n    init.method,\n    init.body,\n    [...init.headers]\n      .filter(([name]) => {\n        const normalized = name.toLowerCase();\n        return (\n          REQUEST_CACHE_KEY_HEADERS.has(normalized) && !REQUEST_IDENTITY_HEADERS.has(normalized)\n        );\n      })\n      .toSorted(([left], [right]) => left.localeCompare(right))\n      .map(([name, value]) => `${name}:${value}`)\n      .join(\"\\n\"),\n  ] as const;\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.mjs","names":[],"sources":["../../src/client/client.ts"],"sourcesContent":["import type { TadaDocumentNode } from \"gql.tada\";\n\nimport { getHydrogenCacheStatus } from \"../core/cache/cache-status\";\nimport { createFetchWithCache } from \"../core/cache/fetch-with-cache\";\nimport type { FetchCacheOptions, FetchCacheResponseContext } from \"../core/cache/fetch-with-cache\";\nimport type { CacheInstance } from \"../core/cache/run-with-cache\";\nimport type { CachingStrategy } from \"../core/cache/strategies\";\nimport { DEFAULT_TIMEOUT_IN_MS, STOREFRONT_API_VERSION } from \"../core/constants\";\nimport {\n  HYDROGEN_VERSION_HEADER,\n  REQUEST_GROUP_ID_HEADER,\n  SDK_VARIANT_HEADER,\n  SDK_VARIANT_SOURCE_HEADER,\n  SDK_VERSION_HEADER,\n  SHOPIFY_STOREFRONT_S_HEADER,\n  SHOPIFY_STOREFRONT_Y_HEADER,\n  STOREFRONT_ACCESS_TOKEN_HEADER,\n  STOREFRONT_BUYER_IP_HEADER,\n  STOREFRONT_ID_HEADER,\n  STOREFRONT_PRIVATE_TOKEN_HEADER,\n  SHOPIFY_UNIQUE_TOKEN_HEADER,\n  SHOPIFY_VISIT_TOKEN_HEADER,\n} from \"../core/headers\";\nimport type { I18nConfig, ShopifyRequestContext } from \"../core/request-context\";\nimport { normalizeStoreDomain } from \"../core/url\";\nimport type { AnyStorefrontQueryString } from \"../graphql\";\nimport { StorefrontApiError, StorefrontTimeoutError } from \"./errors\";\nimport { getI18nVariableNames } from \"./i18n-variables\";\nimport type {\n  ClientType,\n  CreateStorefrontClientArgs,\n  GraphQLFormattedError,\n  StorefrontClient,\n  StorefrontGraphqlResult,\n} from \"./types\";\n\ntype DocLike = TadaDocumentNode<unknown, unknown> | AnyStorefrontQueryString;\ntype FetchInput = Parameters<typeof globalThis.fetch>[0];\ntype FetchInit = Parameters<typeof globalThis.fetch>[1];\ntype ResolvedStorefrontFetch = (\n  input: FetchInput,\n  init: FetchInit,\n  cacheOptions: FetchCacheOptions | undefined,\n) => Promise<Response>;\n\nconst REQUEST_CACHE_KEY_HEADERS = new Set([\n  \"content-type\",\n  \"user-agent\",\n  SDK_VARIANT_HEADER.toLowerCase(),\n  SDK_VARIANT_SOURCE_HEADER.toLowerCase(),\n  SDK_VERSION_HEADER.toLowerCase(),\n  HYDROGEN_VERSION_HEADER.toLowerCase(),\n  STOREFRONT_ACCESS_TOKEN_HEADER.toLowerCase(),\n  STOREFRONT_PRIVATE_TOKEN_HEADER.toLowerCase(),\n]);\nconst REQUEST_IDENTITY_HEADERS = new Set([\n  \"cookie\",\n  REQUEST_GROUP_ID_HEADER.toLowerCase(),\n  STOREFRONT_BUYER_IP_HEADER.toLowerCase(),\n  SHOPIFY_UNIQUE_TOKEN_HEADER.toLowerCase(),\n  SHOPIFY_VISIT_TOKEN_HEADER.toLowerCase(),\n  SHOPIFY_STOREFRONT_Y_HEADER.toLowerCase(),\n  SHOPIFY_STOREFRONT_S_HEADER.toLowerCase(),\n]);\nconst CACHE_ENABLED_GRAPHQL_CLIENTS = new WeakSet<StorefrontClient[\"graphql\"]>();\nconst SHOULD_CACHE_RESULT = Symbol();\n\ntype ShouldCacheResult = (body: object) => boolean;\n\nclass StorefrontCacheConfigError extends Error {}\n\nexport function withStorefrontClientCache<TOptions extends object>(\n  client: Pick<StorefrontClient, \"graphql\">,\n  options: TOptions,\n  strategy: CachingStrategy,\n  shouldCacheResult?: ShouldCacheResult,\n): TOptions {\n  if (!CACHE_ENABLED_GRAPHQL_CLIENTS.has(client.graphql)) return options;\n\n  return { ...options, cache: strategy, [SHOULD_CACHE_RESULT]: shouldCacheResult };\n}\n\n/**\n * Creates a Storefront API client that runs typed queries and mutations against your store.\n *\n * Set `type` based on where your code runs and whether customer context is available:\n *\n * |                  | `public`                   | `private`                   | `private_no_buyer_context` |\n * |------------------|------------------------------|-------------------------------|------------------------------|\n * | Runs in          | Browser or mobile            | Server-side rendering         | Background server code    |\n * | Token            | Public access token, or none | Private access token          | Private access token      |\n * | Customer context | Browser request context      | You forward trusted `buyerIp` | None                      |\n * | Best for         | Client-side fetches          | SSR with customer context     | Webhooks, background jobs |\n *\n * Pass a request context from `createShopifyRequestContext`. The client forwards the incoming\n * request's cookies and `Sec-GPC` header to the Storefront API, and fills `$country`\n * and `$language` variables from the context's locale. The client reads the request headers once,\n * when you create the client. Create a client for each incoming request, and create a client at\n * module scope only with a static request context.\n *\n * Keep private clients in server code, where the token can't reach browsers. The function throws an\n * error when you create either private client type in a browser. The function throws a `TypeError`\n * when the request context of a `private` client has no `buyerIp`.\n *\n * @see [Storefront API authentication](https://shopify.dev/docs/api/storefront#authentication)\n * @publicDocs\n */\nexport function createStorefrontClient<\n  const Type extends ClientType,\n  const RequestContext extends ShopifyRequestContext,\n  const CacheConfig extends CacheInstance | undefined = undefined,\n>(\n  args: CreateStorefrontClientArgs<RequestContext, Type, CacheConfig>,\n): StorefrontClient<\n  // Tuple-wrapped to stay non-distributive so an explicit\n  // `CacheInstance | undefined` type argument yields one client type, not a\n  // union. Note a *value* of that type still unlocks cache options: optional\n  // property inference strips `undefined` before it reaches CacheConfig, so\n  // definiteness is undecidable here — the runtime guard rejects cache\n  // options when no cache instance was actually configured.\n  [CacheConfig] extends [CacheInstance] ? { cache?: CachingStrategy } : {},\n  Type,\n  RequestContext\n>;\n/**\n * @param args The client type, request context, and store configuration for the new client.\n * @returns The client, with a `graphql()` method that runs queries and mutations.\n */\nexport function createStorefrontClient(args: CreateStorefrontClientArgs): StorefrontClient {\n  const { config, requestContext, type: clientType } = args;\n\n  if (!config.storeDomain) {\n    throw new Error(\"storeDomain is required and must be non-empty\");\n  }\n\n  const storeUrl = normalizeStoreDomain(config.storeDomain);\n  const apiVersion = config.apiVersion ?? STOREFRONT_API_VERSION;\n  const apiUrl = `${storeUrl}/api/${apiVersion}/graphql.json`;\n\n  const originFetch = config.fetch ?? globalThis.fetch;\n  if (typeof originFetch !== \"function\") {\n    throw new Error(\n      \"No fetch function available. Pass a fetch option or ensure globalThis.fetch exists.\",\n    );\n  }\n  const resolvedFetch = config.cache\n    ? createFetchWithCache({\n        cache: config.cache,\n        waitUntil: config.waitUntil,\n        fetch: originFetch as typeof globalThis.fetch,\n      })\n    : originFetch;\n\n  const timeoutInMs = config.defaultTimeoutInMs ?? DEFAULT_TIMEOUT_IN_MS;\n  if (timeoutInMs < 0 || Number.isNaN(timeoutInMs)) {\n    throw new Error(\"defaultTimeoutInMs must be a non-negative number\");\n  }\n\n  const staticHeaders: Record<string, string> = {\n    \"content-type\": \"application/json\",\n  };\n  if (config.storefrontId) {\n    staticHeaders[STOREFRONT_ID_HEADER] = config.storefrontId;\n  }\n\n  switch (clientType) {\n    case \"private\":\n    case \"private_no_buyer_context\":\n      if (typeof document !== \"undefined\") {\n        throw new Error(\n          \"private storefront tokens cannot be used in a browser context. Use a publicStorefrontToken instead.\",\n        );\n      }\n      if (!config.privateStorefrontToken) {\n        throw new Error(\"privateStorefrontToken is required\");\n      }\n      staticHeaders[STOREFRONT_PRIVATE_TOKEN_HEADER] = config.privateStorefrontToken;\n      break;\n    case \"public\":\n      if (config.publicStorefrontToken !== undefined && !config.publicStorefrontToken) {\n        throw new Error(\"publicStorefrontToken must be non-empty when provided\");\n      }\n      if (config.publicStorefrontToken) {\n        staticHeaders[STOREFRONT_ACCESS_TOKEN_HEADER] = config.publicStorefrontToken;\n      }\n      break;\n    default:\n      clientType satisfies never;\n      throw new Error(`Unsupported client type: ${clientType}`);\n  }\n\n  const i18n = requestContext.i18n;\n  const requestHeaders = new Headers(staticHeaders);\n  requestContext.applyStorefrontRequestHeaders(requestHeaders);\n\n  if (clientType === \"private\") {\n    const { buyerIp } = requestContext;\n    if (!buyerIp) {\n      throw new TypeError(\"requestContext.buyerIp is required for private Storefront API clients\");\n    }\n    requestHeaders.set(STOREFRONT_BUYER_IP_HEADER, buyerIp);\n  }\n\n  async function graphql(\n    doc: DocLike | string,\n    ...rest: [options?: Record<string, unknown>]\n  ): Promise<StorefrontGraphqlResult<DocLike>> {\n    const opts = (rest[0] ?? {}) as {\n      variables?: Record<string, unknown>;\n      signal?: AbortSignal;\n      cache?: CachingStrategy;\n      [SHOULD_CACHE_RESULT]?: ShouldCacheResult;\n    };\n\n    const queryText = typeof doc === \"string\" ? doc : (doc as unknown as string);\n    if (typeof queryText !== \"string\") {\n      throw new StorefrontApiError(\n        \"Expected gql() to return a string at runtime. Check gql.tada version compatibility.\",\n      );\n    }\n\n    if (opts.cache && !config.cache) {\n      throw new StorefrontCacheConfigError(\n        \"Storefront API cache options require a cache configured in createStorefrontClient().\",\n      );\n    }\n\n    if (opts.cache?.mode === \"private\") {\n      throw new StorefrontCacheConfigError(\n        \"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.\",\n      );\n    }\n\n    const variables = buildVariables(queryText, opts.variables, i18n);\n    const externalSignals = [requestContext.signal, opts.signal].filter(\n      (signal): signal is AbortSignal => Boolean(signal),\n    );\n\n    const earlyAbortSignal = externalSignals.find((signal) => signal.aborted);\n    if (earlyAbortSignal) {\n      throw (\n        earlyAbortSignal.reason ??\n        new DOMException(\"signal is aborted without reason\", \"AbortError\")\n      );\n    }\n\n    let requestId: string | undefined;\n    let responseHeaders: Headers;\n    let responseText: string;\n    let status: number;\n    let timeoutSignal: AbortSignal | undefined;\n\n    if (timeoutInMs > 0) {\n      timeoutSignal = AbortSignal.timeout(timeoutInMs);\n      externalSignals.push(timeoutSignal);\n    }\n\n    try {\n      const init: PlainRequestInit = {\n        method: \"POST\",\n        headers: new Headers(requestHeaders),\n        body: JSON.stringify({ query: queryText, variables }),\n        signal: externalSignals.length > 0 ? AbortSignal.any(externalSignals) : undefined,\n      };\n\n      const cacheOptions = createStorefrontCacheOptions(\n        apiUrl,\n        init,\n        queryText,\n        opts.cache,\n        opts[SHOULD_CACHE_RESULT],\n        timeoutInMs > 0 ? timeoutInMs : DEFAULT_TIMEOUT_IN_MS,\n      );\n      const response = await (resolvedFetch as ResolvedStorefrontFetch)(apiUrl, init, cacheOptions);\n\n      responseHeaders = response.headers;\n      const hydrogenCacheStatus = getHydrogenCacheStatus(responseHeaders);\n      if (hydrogenCacheStatus !== \"hit\") {\n        requestContext.captureSubrequestHeaders(responseHeaders);\n      }\n\n      requestId = responseHeaders.get(\"x-request-id\") ?? undefined;\n      status = response.status;\n\n      if (!response.ok) {\n        const bodyHint = await response.text().catch(() => \"\");\n        throw new StorefrontApiError(\n          `SFAPI responded with ${status}${bodyHint ? `: ${bodyHint.slice(0, 200)}` : \"\"}`,\n          { status, requestId, queryText, variables },\n        );\n      }\n\n      responseText = await response.text();\n    } catch (error) {\n      if (error instanceof StorefrontApiError) throw error;\n      if (error instanceof StorefrontTimeoutError) throw error;\n      if (error instanceof StorefrontCacheConfigError) throw error;\n      if (\n        error instanceof DOMException &&\n        error.name === \"TimeoutError\" &&\n        timeoutSignal?.aborted\n      ) {\n        throw new StorefrontTimeoutError(timeoutInMs);\n      }\n      if (error instanceof DOMException && error.name === \"AbortError\") {\n        throw error;\n      }\n      throw new StorefrontApiError(\"SFAPI request failed\", { cause: error });\n    }\n\n    let json: unknown;\n    try {\n      json = JSON.parse(responseText);\n    } catch (cause) {\n      throw new StorefrontApiError(\n        `Failed to parse SFAPI response as JSON (${apiUrl}, status ${status})` +\n          (responseText ? `: ${responseText.slice(0, 200)}` : \"\"),\n        { status, requestId, cause, queryText, variables },\n      );\n    }\n\n    if (typeof json !== \"object\" || json === null || Array.isArray(json)) {\n      throw new StorefrontApiError(\n        `SFAPI returned unexpected JSON type: ${Array.isArray(json) ? \"array\" : typeof json}`,\n        { status, requestId, queryText, variables },\n      );\n    }\n\n    const body = json as { data?: unknown; errors?: GraphQLFormattedError[] };\n    // Branch to populate the two arms of the StorefrontGraphqlResult union: callers\n    // narrowing on `errors` get a non-null `data` only when no errors are present.\n    if (body.errors) {\n      return {\n        data: body.data ?? null,\n        errors: body.errors,\n        headers: responseHeaders,\n      };\n    }\n    return {\n      data: body.data,\n      headers: responseHeaders,\n    };\n  }\n\n  const client: StorefrontClient = {\n    type: clientType,\n    i18n,\n    graphql: graphql as StorefrontClient[\"graphql\"],\n    apiUrl,\n    storeUrl,\n    storefrontId: config.storefrontId,\n    requestContext,\n  };\n\n  if (config.cache) CACHE_ENABLED_GRAPHQL_CLIENTS.add(client.graphql);\n\n  return client;\n}\n\nfunction buildVariables(\n  queryText: string,\n  userVariables: Record<string, unknown> | undefined,\n  resolvedI18n: I18nConfig,\n): Record<string, unknown> {\n  const variables: Record<string, unknown> = { ...userVariables };\n\n  for (const name of getI18nVariableNames(queryText)) {\n    variables[name] = resolvedI18n[name];\n  }\n\n  return variables;\n}\n\ntype PlainRequestInit = RequestInit & { headers: Headers; body: string; method: string };\n\nfunction createStorefrontCacheOptions(\n  apiUrl: string,\n  init: PlainRequestInit,\n  queryText: string,\n  strategy: CachingStrategy | undefined,\n  shouldCacheResult: ShouldCacheResult | undefined,\n  backgroundTimeoutInMs: number,\n): FetchCacheOptions | undefined {\n  if (!strategy) return undefined;\n\n  // Runtime only needs a safety belt for untyped callers. False positives are\n  // acceptable because they bypass cache rather than risking mutation caching.\n  if (/\\bmutation\\b/.test(queryText)) return undefined;\n\n  return {\n    key: createStorefrontCacheKey(apiUrl, init),\n    strategy,\n    shouldCacheResponse: async ({ json }: FetchCacheResponseContext) => {\n      if (!json) return false;\n\n      const body = await json().catch(() => undefined);\n      if (typeof body !== \"object\" || body == null || Array.isArray(body) || \"errors\" in body) {\n        return false;\n      }\n\n      return shouldCacheResult?.(body) ?? true;\n    },\n    // A refresh outlives the request that triggered it, so request and caller\n    // aborts must not cancel it. It still needs a deadline, even when the caller\n    // disabled the client timeout to own the foreground one.\n    backgroundSignal: () => AbortSignal.timeout(backgroundTimeoutInMs),\n  };\n}\n\nfunction createStorefrontCacheKey(apiUrl: string, init: PlainRequestInit) {\n  return [\n    \"storefront-api\",\n    apiUrl,\n    init.method,\n    init.body,\n    [...init.headers]\n      .filter(([name]) => {\n        const normalized = name.toLowerCase();\n        return (\n          REQUEST_CACHE_KEY_HEADERS.has(normalized) && !REQUEST_IDENTITY_HEADERS.has(normalized)\n        );\n      })\n      .toSorted(([left], [right]) => left.localeCompare(right))\n      .map(([name, value]) => `${name}:${value}`)\n      .join(\"\\n\"),\n  ] as const;\n}\n"],"mappings":"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"}

package/dist/client/i18n-variables.d.mts

@@ -0,0 +1,13 @@
+//#region src/client/i18n-variables.d.ts
+/**
+ * Variables the client fills from `requestContext.i18n`, with the named type
+ * each must be declared as. Same-named variables of any other type belong to
+ * the caller.
+ */
+declare const I18N_VARIABLE_TYPES: {
+  readonly country: "CountryCode";
+  readonly language: "LanguageCode";
+};
+//#endregion
+export { I18N_VARIABLE_TYPES };
+//# sourceMappingURL=i18n-variables.d.mts.map

package/dist/client/i18n-variables.mjs

@@ -0,0 +1,84 @@
+//#region src/client/i18n-variables.ts
+/**
+* Variables the client fills from `requestContext.i18n`, with the named type
+* each must be declared as. Same-named variables of any other type belong to
+* the caller.
+*/
+const I18N_VARIABLE_TYPES = {
+	country: "CountryCode",
+	language: "LanguageCode"
+};
+const TOKEN_RE = /"""(?:\\"""|[^])*?"""|"(?:\\.|[^"\\\n\r])*"|#[^\n\r]*|[_A-Za-z][_0-9A-Za-z]*|[^\s,]/g;
+const NAME_RE = /^[_A-Za-z]/;
+const OPERATION_TYPES = new Set([
+	"query",
+	"mutation",
+	"subscription"
+]);
+const OPENING = new Set([
+	"(",
+	"[",
+	"{"
+]);
+const CLOSING = new Set([
+	")",
+	"]",
+	"}"
+]);
+/**
+* Returns the i18n variables that the document's first operation declares as
+* `$country: CountryCode` or `$language: LanguageCode`, nullable or non-null.
+* This is the same rule the `graphql()` variables type applies.
+*/
+function getI18nVariableNames(source) {
+	const names = [];
+	for (const [name, colon, ...rest] of readFirstOperationVariables(tokenize(source))) {
+		if (colon !== ":" || !isI18nVariableName(name)) continue;
+		const typeEnd = rest.findIndex((token) => token === "=" || token === "@");
+		const type = rest.slice(0, typeEnd === -1 ? void 0 : typeEnd).join("");
+		const expected = I18N_VARIABLE_TYPES[name];
+		if (type === expected || type === `${expected}!`) names.push(name);
+	}
+	return names;
+}
+function isI18nVariableName(name) {
+	return name !== void 0 && Object.hasOwn(I18N_VARIABLE_TYPES, name);
+}
+function* tokenize(source) {
+	for (const [token] of source.matchAll(TOKEN_RE)) if (token[0] !== "#") yield token;
+}
+function readFirstOperationVariables(tokens) {
+	let depth = 0;
+	let inFragment = false;
+	for (const token of tokens) {
+		if (depth === 0 && !inFragment) {
+			if (OPERATION_TYPES.has(token)) return readOperationVariables(tokens);
+			if (token === "{") return [];
+			inFragment = token === "fragment";
+		}
+		if (OPENING.has(token)) depth++;
+		else if (CLOSING.has(token) && --depth === 0 && token === "}") inFragment = false;
+	}
+	return [];
+}
+function readOperationVariables(tokens) {
+	let next = tokens.next().value;
+	if (next && NAME_RE.test(next)) next = tokens.next().value;
+	return next === "(" ? readVariableDefinitions(tokens) : [];
+}
+function readVariableDefinitions(tokens) {
+	const definitions = [];
+	let depth = 0;
+	for (const token of tokens) {
+		if (depth === 0 && token === ")") break;
+		if (depth === 0 && token === "$") definitions.push([]);
+		else definitions.at(-1)?.push(token);
+		if (OPENING.has(token)) depth++;
+		else if (CLOSING.has(token)) depth--;
+	}
+	return definitions;
+}
+
+//#endregion
+export { getI18nVariableNames };
+//# sourceMappingURL=i18n-variables.mjs.map

package/dist/client/i18n-variables.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n-variables.mjs","names":[],"sources":["../../src/client/i18n-variables.ts"],"sourcesContent":["/**\n * Variables the client fills from `requestContext.i18n`, with the named type\n * each must be declared as. Same-named variables of any other type belong to\n * the caller.\n */\nexport const I18N_VARIABLE_TYPES = {\n  country: \"CountryCode\",\n  language: \"LanguageCode\",\n} as const;\n\nexport type I18nVariableName = keyof typeof I18N_VARIABLE_TYPES;\n\n// Significant GraphQL tokens plus comments, which are dropped. Matching whole\n// strings keeps their contents from being read as declarations.\nconst TOKEN_RE =\n  /\"\"\"(?:\\\\\"\"\"|[^])*?\"\"\"|\"(?:\\\\.|[^\"\\\\\\n\\r])*\"|#[^\\n\\r]*|[_A-Za-z][_0-9A-Za-z]*|[^\\s,]/g;\nconst NAME_RE = /^[_A-Za-z]/;\nconst OPERATION_TYPES = new Set([\"query\", \"mutation\", \"subscription\"]);\nconst OPENING = new Set([\"(\", \"[\", \"{\"]);\nconst CLOSING = new Set([\")\", \"]\", \"}\"]);\n\n/**\n * Returns the i18n variables that the document's first operation declares as\n * `$country: CountryCode` or `$language: LanguageCode`, nullable or non-null.\n * This is the same rule the `graphql()` variables type applies.\n */\nexport function getI18nVariableNames(source: string): I18nVariableName[] {\n  const names: I18nVariableName[] = [];\n  for (const [name, colon, ...rest] of readFirstOperationVariables(tokenize(source))) {\n    if (colon !== \":\" || !isI18nVariableName(name)) continue;\n    const typeEnd = rest.findIndex((token) => token === \"=\" || token === \"@\");\n    const type = rest.slice(0, typeEnd === -1 ? undefined : typeEnd).join(\"\");\n    const expected = I18N_VARIABLE_TYPES[name];\n    if (type === expected || type === `${expected}!`) names.push(name);\n  }\n  return names;\n}\n\nfunction isI18nVariableName(name: string | undefined): name is I18nVariableName {\n  return name !== undefined && Object.hasOwn(I18N_VARIABLE_TYPES, name);\n}\n\nfunction* tokenize(source: string): Generator<string> {\n  for (const [token] of source.matchAll(TOKEN_RE)) {\n    if (token[0] !== \"#\") yield token;\n  }\n}\n\nfunction readFirstOperationVariables(tokens: Generator<string>): string[][] {\n  let depth = 0;\n  let inFragment = false;\n  for (const token of tokens) {\n    if (depth === 0 && !inFragment) {\n      if (OPERATION_TYPES.has(token)) return readOperationVariables(tokens);\n      if (token === \"{\") return [];\n      inFragment = token === \"fragment\";\n    }\n    if (OPENING.has(token)) depth++;\n    else if (CLOSING.has(token) && --depth === 0 && token === \"}\") inFragment = false;\n  }\n  return [];\n}\n\nfunction readOperationVariables(tokens: Generator<string>): string[][] {\n  let next = tokens.next().value;\n  if (next && NAME_RE.test(next)) next = tokens.next().value;\n  return next === \"(\" ? readVariableDefinitions(tokens) : [];\n}\n\n// Default values and directive arguments can nest `$` and `)`, so only depth 0 delimits definitions.\nfunction readVariableDefinitions(tokens: Generator<string>): string[][] {\n  const definitions: string[][] = [];\n  let depth = 0;\n  for (const token of tokens) {\n    if (depth === 0 && token === \")\") break;\n    if (depth === 0 && token === \"$\") definitions.push([]);\n    else definitions.at(-1)?.push(token);\n    if (OPENING.has(token)) depth++;\n    else if (CLOSING.has(token)) depth--;\n  }\n  return definitions;\n}\n"],"mappings":";;;;;;AAKA,MAAa,sBAAsB;CACjC,SAAS;CACT,UAAU;CACX;AAMD,MAAM,WACJ;AACF,MAAM,UAAU;AAChB,MAAM,kBAAkB,IAAI,IAAI;CAAC;CAAS;CAAY;CAAe,CAAC;AACtE,MAAM,UAAU,IAAI,IAAI;CAAC;CAAK;CAAK;CAAI,CAAC;AACxC,MAAM,UAAU,IAAI,IAAI;CAAC;CAAK;CAAK;CAAI,CAAC;;;;;;AAOxC,SAAgB,qBAAqB,QAAoC;CACvE,MAAM,QAA4B,EAAE;AACpC,MAAK,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,4BAA4B,SAAS,OAAO,CAAC,EAAE;AAClF,MAAI,UAAU,OAAO,CAAC,mBAAmB,KAAK,CAAE;EAChD,MAAM,UAAU,KAAK,WAAW,UAAU,UAAU,OAAO,UAAU,IAAI;EACzE,MAAM,OAAO,KAAK,MAAM,GAAG,YAAY,KAAK,SAAY,QAAQ,CAAC,KAAK,GAAG;EACzE,MAAM,WAAW,oBAAoB;AACrC,MAAI,SAAS,YAAY,SAAS,GAAG,SAAS,GAAI,OAAM,KAAK,KAAK;;AAEpE,QAAO;;AAGT,SAAS,mBAAmB,MAAoD;AAC9E,QAAO,SAAS,UAAa,OAAO,OAAO,qBAAqB,KAAK;;AAGvE,UAAU,SAAS,QAAmC;AACpD,MAAK,MAAM,CAAC,UAAU,OAAO,SAAS,SAAS,CAC7C,KAAI,MAAM,OAAO,IAAK,OAAM;;AAIhC,SAAS,4BAA4B,QAAuC;CAC1E,IAAI,QAAQ;CACZ,IAAI,aAAa;AACjB,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,UAAU,KAAK,CAAC,YAAY;AAC9B,OAAI,gBAAgB,IAAI,MAAM,CAAE,QAAO,uBAAuB,OAAO;AACrE,OAAI,UAAU,IAAK,QAAO,EAAE;AAC5B,gBAAa,UAAU;;AAEzB,MAAI,QAAQ,IAAI,MAAM,CAAE;WACf,QAAQ,IAAI,MAAM,IAAI,EAAE,UAAU,KAAK,UAAU,IAAK,cAAa;;AAE9E,QAAO,EAAE;;AAGX,SAAS,uBAAuB,QAAuC;CACrE,IAAI,OAAO,OAAO,MAAM,CAAC;AACzB,KAAI,QAAQ,QAAQ,KAAK,KAAK,CAAE,QAAO,OAAO,MAAM,CAAC;AACrD,QAAO,SAAS,MAAM,wBAAwB,OAAO,GAAG,EAAE;;AAI5D,SAAS,wBAAwB,QAAuC;CACtE,MAAM,cAA0B,EAAE;CAClC,IAAI,QAAQ;AACZ,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,UAAU,KAAK,UAAU,IAAK;AAClC,MAAI,UAAU,KAAK,UAAU,IAAK,aAAY,KAAK,EAAE,CAAC;MACjD,aAAY,GAAG,GAAG,EAAE,KAAK,MAAM;AACpC,MAAI,QAAQ,IAAI,MAAM,CAAE;WACf,QAAQ,IAAI,MAAM,CAAE;;AAE/B,QAAO"}

package/dist/client/types.d.mts

@@ -1,7 +1,9 @@
 import { CacheInstance, WaitUntil } from "../core/cache/run-with-cache.mjs";
 import { I18nConfig, ShopifyRequestContext, ShopifyRequestContextWithBuyerIp } from "../core/request-context.mjs";
-import { InferOperationKind, InferResult, InferVariables } from "../graphql/type-resolver.mjs";
+import { introspection } from "../graphql/generated/graphql-env.mjs";
+import { InferOperationKind, InferResult, InferVariableNamesDeclaredAs, InferVariables } from "../graphql/type-resolver.mjs";
 import { AnyStorefrontQueryString, SourceOf, StorefrontQueryString } from "../graphql/graphql.mjs";
+import { I18N_VARIABLE_TYPES } from "./i18n-variables.mjs";
 import { ResultOf, TadaDocumentNode, VariablesOf } from "gql.tada";
 
 //#region src/client/types.d.ts
@@ -140,9 +142,13 @@ type CreateStorefrontClientArgs<RequestContext extends ShopifyRequestContext = S
     cache?: CacheConfig;
   };
 };
-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>;
+type I18nVariableTypes = typeof I18N_VARIABLE_TYPES;
+type I18nEnum<K extends keyof I18nVariableTypes> = introspection["types"][I18nVariableTypes[K]]["enumValues"];
+type IsExactly<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+type I18nVariableNamesByValue<Variables> = { [K in keyof Variables & keyof I18nVariableTypes]-?: IsExactly<NonNullable<Variables[K]>, I18nEnum<K>> extends true ? K : never }[keyof Variables & keyof I18nVariableTypes];
+type I18nVariableNamesOfDoc<Doc> = [SourceText<Doc>] extends [never] ? I18nVariableNamesByValue<VariablesOfDoc<Doc>> : string extends SourceText<Doc> ? I18nVariableNamesByValue<VariablesOfDoc<Doc>> : InferVariableNamesDeclaredAs<SourceText<Doc>, I18nVariableTypes>;
+/** Variables the caller passes: everything except the i18n variables the client injects. */
+type UserVariables<Doc> = Omit<VariablesOfDoc<Doc>, I18nVariableNamesOfDoc<Doc>>;
 /** Resolves to `true` when an object type has no required keys. */
 type HasNoRequiredKeys<T> = Record<string, never> extends T ? true : false;
 /**
@@ -213,8 +219,9 @@ type StorefrontClient<Extra extends Record<string, unknown> = {}, Type extends C
   i18n: RequestContext["i18n"];
   /**
    * 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.
+   * plain query string. When the operation declares `$country: CountryCode` or
+   * `$language: LanguageCode`, the client sets the variable from the request context and overrides
+   * any value you pass. Variables with other types stay caller-owned.
    *
    * 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

package/dist/core/cart/cart.mjs

@@ -203,13 +203,18 @@ function reuseVisibleReferences(previous, next) {
 		pending
 	};
 }
-function derivePending(state, transactions) {
+function getVisiblePendingKeys(store, transaction) {
+	if (transaction.type !== "change_lines_quantity") return transaction.pendingKeys;
+	const ownedKeys = getOwnedSignalKeys(store, transaction);
+	return transaction.pendingKeys.filter((key) => !transaction.signalKeys.includes(key) || ownedKeys.includes(key));
+}
+function derivePending(store, state) {
 	const lines = /* @__PURE__ */ new Set();
 	const discountCodes = /* @__PURE__ */ new Set();
 	let note = false;
 	let attributes = false;
 	let cost = false;
-	for (const transaction of transactions) for (const key of transaction.pendingKeys) {
+	for (const transaction of store.transactions) for (const key of getVisiblePendingKeys(store, transaction)) {
 		if (key === NOTE_KEY) note = true;
 		if (key === ATTRIBUTES_KEY) attributes = true;
 		if (key.startsWith(LINE_KEY_PREFIX)) {
@@ -236,10 +241,13 @@ function derivePending(state, transactions) {
 }
 function projectVisibleState(store) {
 	let state = store.settled;
-	for (const transaction of store.transactions) state = transaction.projectPayload(state);
+	for (const transaction of store.transactions) {
+		const ownedKeys = getOwnedSignalKeys(store, transaction);
+		state = transaction.projectPayload(state, (key) => ownedKeys.includes(key));
+	}
 	state = {
 		...state,
-		pending: derivePending(state, store.transactions)
+		pending: derivePending(store, state)
 	};
 	for (const error of store.projectedErrors) state = error.project(state);
 	if (store.revalidation.visible) state = {
@@ -288,9 +296,9 @@ function createOwner(store, keys) {
 	}
 	return owner;
 }
-function ownsSignalKeys(store, transaction) {
-	if (!transaction.owner) return true;
-	return transaction.signalKeys.every((key) => store.keyedOwners.get(key)?.token === transaction.owner?.token);
+function getOwnedSignalKeys(store, transaction) {
+	if (!transaction.owner) return transaction.signalKeys;
+	return transaction.signalKeys.filter((key) => store.keyedOwners.get(key)?.token === transaction.owner?.token);
 }
 function releaseSignalKeys(store, transaction) {
 	if (!transaction.owner) return;
@@ -413,7 +421,9 @@ function writeNetworkError(state, error, timestampMs) {
 }
 function projectLineErrors(state, failure, lineIds, timestampMs) {
 	if (!failure) return state;
-	const grouped = groupLineErrors(failure, lineIds);
+	return writeLineErrors(state, groupLineErrors(failure, lineIds), timestampMs);
+}
+function writeLineErrors(state, grouped, timestampMs) {
 	return {
 		...state,
 		errors: {
@@ -567,6 +577,22 @@ function mergeServerLine(previous, next) {
 		...merchandise ? { merchandise } : {}
 	};
 }
+function addOwnedLineErrors(failure, lineIds, ownedLineIds, addError) {
+	const grouped = groupLineErrors(failure, lineIds);
+	for (const [lineId, group] of grouped.lines) {
+		if (lineIds.includes(lineId) && !ownedLineIds.has(lineId)) continue;
+		const lines = new Map([[lineId, group]]);
+		addError((current, timestampMs) => writeLineErrors(current, {
+			lines,
+			cart: createEmptyErrorGroup()
+		}, timestampMs), [lineKey(lineId)]);
+	}
+	if (grouped.cart.userErrors.length === 0 && grouped.cart.warnings.length === 0) return;
+	addError((current, timestampMs) => writeLineErrors(current, {
+		lines: /* @__PURE__ */ new Map(),
+		cart: grouped.cart
+	}, timestampMs), [...ownedLineIds].map(lineKey));
+}
 function hasProjectedErrors(result) {
 	return (result?.userErrors?.length ?? 0) > 0 || (result?.warnings?.length ?? 0) > 0;
 }
@@ -579,6 +605,31 @@ function transportAddToCart(payload, signal, updateCart, cartId) {
 		...payload.eventDetail && { event: { detail: payload.eventDetail } }
 	});
 }
+function projectLineQuantity(state, payload) {
+	const previous = getLines(state.data);
+	if (!previous.some((line) => line.id === payload.lineId)) return state;
+	const lines = payload.quantity === 0 ? previous.filter((line) => line.id !== payload.lineId) : previous.map((line) => line.id === payload.lineId ? {
+		...line,
+		quantity: payload.quantity
+	} : line);
+	return {
+		...state,
+		data: reconcileCartLines(state.data, lines)
+	};
+}
+function settleLineQuantity(state, serverLines, payload, requestRevalidation) {
+	const previous = getLines(state.data);
+	const matching = serverLines.find((line) => line.id === payload.lineId);
+	if (!matching && payload.quantity > 0) {
+		requestRevalidation();
+		return state;
+	}
+	const lines = matching ? previous.map((line) => line.id === payload.lineId ? mergeServerLine(line, matching) : line) : previous.filter((line) => line.id !== payload.lineId);
+	return {
+		...state,
+		data: reconcileCartLines(state.data, lines)
+	};
+}
 const CART_TRANSACTION_TYPES = defineTransactionTypes({
 	add_to_cart: {
 		payload: {},
@@ -702,6 +753,22 @@ const CART_TRANSACTION_TYPES = defineTransactionTypes({
 		},
 		getSignalKeys: (_state, payload) => lineKey(payload.lineId)
 	},
+	change_lines_quantity: {
+		payload: {},
+		transport: (payload, signal, updateCart) => updateCart({ lines: payload.lines.map(({ lineId, quantity }) => ({
+			id: lineId,
+			quantity
+		})) }, { signal }),
+		projectPayload: (state, payload, ownsKey) => payload.lines.filter(({ lineId }) => ownsKey(lineKey(lineId))).reduce(projectLineQuantity, state),
+		projectPromise: (state, result, payload, addError, { ownsKey, requestRevalidation }) => {
+			const owned = payload.lines.filter(({ lineId }) => ownsKey(lineKey(lineId)));
+			if (hasProjectedErrors(result)) addOwnedLineErrors(result, payload.lines.map(({ lineId }) => lineId), new Set(owned.map(({ lineId }) => lineId)), addError);
+			if (!result.cart) return state;
+			const serverLines = getLines(cartResponseFromStandardEvent(result.cart));
+			return owned.reduce((current, line) => settleLineQuantity(current, serverLines, line, requestRevalidation), state);
+		},
+		getSignalKeys: (_state, payload) => payload.lines.map(({ lineId }) => lineKey(lineId))
+	},
 	set_discount_codes: {
 		payload: {},
 		transport: (payload, signal, updateCart) => updateCart({ discountCodes: payload.discountCodes }, { signal }),
@@ -844,8 +911,12 @@ function createPendingTransaction(store, type, definition, payload, promise, res
 		requiresRevalidation,
 		owner,
 		promise,
-		projectPayload: (current) => definition.projectPayload(current, payload),
-		projectPromise: (current, result, addError) => definition.projectPromise(current, result, payload, addError, { mergeServerCart: !transaction.requiresRevalidation }),
+		projectPayload: (current, ownsKey) => definition.projectPayload(current, payload, ownsKey),
+		projectPromise: (current, result, addError, ownsKey, requestRevalidation) => definition.projectPromise(current, result, payload, addError, {
+			mergeServerCart: !transaction.requiresRevalidation,
+			ownsKey,
+			requestRevalidation
+		}),
 		trimAfter: (successful) => trimPendingTransaction(store, type, definition, payload, promise, {
 			id,
 			sequence,
@@ -915,15 +986,16 @@ function fulfillTransaction(store, transactionId, result) {
 	const transaction = store.transactions.find((candidate) => candidate.id === transactionId);
 	if (!transaction || transaction.generation !== store.generation) return;
 	store.observedPromises.delete(transaction.promise);
-	if (!ownsSignalKeys(store, transaction)) {
+	const ownedKeys = getOwnedSignalKeys(store, transaction);
+	if (ownedKeys.length === 0 && transaction.signalKeys.length > 0) {
 		removeTransaction(store, transactionId);
 		publishVisibleState(store);
 		revalidateCartWhenIdle(store);
 		return;
 	}
-	store.settled = transaction.projectPromise(store.settled, result, (projector, keys) => addProjectedError(store, keys ?? transaction.errorKeys, projector));
+	store.settled = transaction.projectPromise(store.settled, result, (projector, keys) => addProjectedError(store, keys ?? transaction.errorKeys, projector), (key) => ownedKeys.includes(key), () => requestCartRevalidation(store));
 	store.settled = addSnapshotIdentity(store.settled, result);
-	if (result.cart && !transaction.requiresRevalidation && transaction.sequence >= store.lastSnapshotSequence) {
+	if (result.cart && ownedKeys.length === transaction.signalKeys.length && !transaction.requiresRevalidation && transaction.sequence >= store.lastSnapshotSequence) {
 		store.settled = addSnapshotFields(store.settled, result);
 		store.lastSnapshotSequence = transaction.sequence;
 	}
@@ -943,13 +1015,14 @@ function rejectTransaction(store, transactionId, error) {
 	const transaction = store.transactions.find((candidate) => candidate.id === transactionId);
 	if (!transaction || transaction.generation !== store.generation) return;
 	store.observedPromises.delete(transaction.promise);
-	const owned = ownsSignalKeys(store, transaction);
+	const ownedKeys = getOwnedSignalKeys(store, transaction);
+	const ownsAllKeys = ownedKeys.length === transaction.signalKeys.length;
 	removeTransaction(store, transactionId);
 	releaseSignalKeys(store, transaction);
-	if (owned) {
+	if (ownedKeys.length > 0 || ownsAllKeys) {
 		const failure = extractCartActionFailure(error);
-		if (failure) transaction.projectPromise(store.settled, rejectedResult(failure), (projector, keys) => addProjectedError(store, keys ?? transaction.errorKeys, projector));
-		if (!failure && !isAbortError(error)) addProjectedError(store, transaction.errorKeys, (state, timestampMs) => writeNetworkError(state, error, timestampMs));
+		if (failure) transaction.projectPromise(store.settled, rejectedResult(failure), (projector, keys) => addProjectedError(store, keys ?? transaction.errorKeys, projector), (key) => ownedKeys.includes(key), NOOP);
+		if (!failure && !isAbortError(error)) addProjectedError(store, ownsAllKeys ? transaction.errorKeys : ownedKeys, (state, timestampMs) => writeNetworkError(state, error, timestampMs));
 	}
 	publishVisibleState(store);
 	revalidateCartWhenIdle(store);
@@ -980,7 +1053,11 @@ function enqueueTransaction(store, type, payload, promise, reservedTransaction,
 	promise.then((result) => fulfillTransaction(store, transaction.id, result), (error) => rejectTransaction(store, transaction.id, error));
 }
 function markOverlappingTransactionForRevalidation(store, transaction) {
-	if (store.transactions.length === 0 && !store.revalidation.active && store.activeMutationTransports.size === 0) return;
+	if (store.transactions.length === 0 && !store.revalidation.active && store.activeMutationTransports.size === 0 && !store.activeCartLoad) return;
+	if (store.activeCartLoad) store.settled = {
+		...store.settled,
+		loading: false
+	};
 	transaction.requiresRevalidation = true;
 	for (const pending of store.transactions) pending.requiresRevalidation = true;
 	requestCartRevalidation(store);
@@ -1173,12 +1250,16 @@ function handleLinesEvent(store, event) {
 		enqueueTransaction(store, "add_to_cart", payloadFromAddEvent(event), event.promise, void 0, eventToken);
 		return;
 	}
-	if (event.lines.length !== 1) return;
-	const line = event.lines[0];
-	enqueueTransaction(store, "change_line_quantity", {
+	const lines = event.lines.map((line) => ({
 		lineId: line.id,
 		quantity: line.quantity
-	}, event.promise, void 0, eventToken);
+	}));
+	if (lines.length === 0) return;
+	if (lines.length === 1) {
+		enqueueTransaction(store, "change_line_quantity", lines[0], event.promise, void 0, eventToken);
+		return;
+	}
+	enqueueTransaction(store, "change_lines_quantity", { lines }, event.promise, void 0, eventToken);
 }
 function handleDiscountEvent(store, event) {
 	enqueueTransaction(store, "set_discount_codes", { discountCodes: event.discountCodes.map((discount) => discount.code) }, event.promise, void 0, getTransactionEventToken(event.detail));
@@ -1201,6 +1282,10 @@ function connectCartStore(store, handlers) {
 	document.addEventListener("shopify:cart:note-update", handlers.note);
 	document.addEventListener("shopify:cart:attributes-update", handlers.attributes);
 	getShopifyStandardActions().catch(() => {});
+	if (store.revalidateOnConnect) {
+		store.revalidateOnConnect = false;
+		refreshCartInStore(store);
+	}
 	return true;
 }
 function cancelCartRevalidation(store) {
@@ -1218,7 +1303,6 @@ function clearPendingTransactions(store) {
 	store.transactions = [];
 	store.projectedErrors = [];
 	store.observedPromises.clear();
-	store.activeMutationTransports.clear();
 	store.expectedEvents = [];
 	store.reservation = null;
 	store.identityTransportGate.active = null;
@@ -1227,6 +1311,7 @@ function clearPendingTransactions(store) {
 	cancelCartRevalidation(store);
 }
 function destroyCartStore(store, handlers) {
+	store.revalidateOnConnect ||= store.revalidation.requested || store.revalidation.active !== null;
 	clearPendingTransactions(store);
 	if (typeof document !== "undefined" && store.cartSyncAttached) {
 		document.removeEventListener("shopify:cart:lines-update", handlers.lines);
@@ -1323,6 +1408,7 @@ function resetCartStore(store) {
 	const hadActiveRevalidation = store.revalidation.active !== null;
 	const shouldReloadAfterReset = store.cartSyncAttached && !hadActiveRevalidation && (hadActiveCartLoad || hasLocalCartData(store.observable.state));
 	clearPendingTransactions(store);
+	store.activeMutationTransports.clear();
 	invalidateActiveCartLoad(store);
 	cancelCartRevalidation(store);
 	store.lastSnapshotSequence = 0;
@@ -1435,6 +1521,7 @@ function createCartStore(options = {}) {
 			waiting: []
 		},
 		cartSyncAttached: false,
+		revalidateOnConnect: false,
 		reservation: null,
 		lastSnapshotSequence: 0
 	};