@shopify/hydrogen 2026.4.4 → 2026.10.0-preview.1

package/dist/client/client.mjs.map

@@ -0,0 +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]);\n\nclass StorefrontCacheConfigError extends Error {}\n\n/**\n * Creates a type-safe Storefront API client.\n *\n * Pick a `type` based on where your code runs and whether buyer context is available:\n *\n * |                 | public                         | private                       | private_no_buyer_context |\n * |-----------------|--------------------------------|-------------------------------|--------------------------|\n * | Runs in         | Browser or mobile              | Server (SSR)                  | Server (background)      |\n * | Token           | Public access token, or none   | Private access token          | Private access token     |\n * | Buyer context   | Browser request context        | You forward trusted `buyerIp` | None                     |\n * | Best for        | Client-side fetches            | SSR with buyer context        | Webhooks, background jobs |\n *\n * Pass `requestContext` so the client's SFAPI requests carry request-scoped\n * headers, follow the incoming request's abort signal, and read the resolved\n * `i18n` used for Storefront API variable injection and localized routes.\n *\n * Token-based access is required for some Storefront API fields, including\n * product tags, metaobjects, metafields, menus, and customers. Use a private\n * client only in trusted server code where the token cannot leak to browsers.\n *\n * @see {@link https://shopify.dev/docs/api/storefront#authentication | Storefront API authentication}\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>;\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    };\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(apiUrl, init, queryText, opts.cache);\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  return {\n    type: clientType,\n    i18n,\n    graphql: graphql as StorefrontClient[\"graphql\"],\n    apiUrl,\n    storeUrl,\n    storefrontId: config.storefrontId,\n    requestContext,\n  };\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): 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      return (\n        typeof body === \"object\" && body != null && !Array.isArray(body) && !(\"errors\" in body)\n      );\n    },\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/errors.d.mts

@@ -0,0 +1,48 @@
+//#region src/client/errors.d.ts
+interface StorefrontApiErrorOptions {
+  requestId?: string;
+  status?: number;
+  cause?: unknown;
+  queryText?: string;
+  variables?: Record<string, unknown>;
+  locations?: ReadonlyArray<{
+    line: number;
+    column: number;
+  }>;
+  path?: ReadonlyArray<string | number>;
+  extensions?: Record<string, unknown>;
+}
+declare class StorefrontApiError extends Error {
+  readonly requestId?: string;
+  readonly status?: number;
+  readonly queryText?: string;
+  readonly variables?: Record<string, unknown>;
+  readonly locations?: ReadonlyArray<{
+    line: number;
+    column: number;
+  }>;
+  readonly path?: ReadonlyArray<string | number>;
+  readonly extensions?: Record<string, unknown>;
+  constructor(message: string, options?: StorefrontApiErrorOptions);
+  get [Symbol.toStringTag](): string;
+  toString(): string;
+  toJSON(): {
+    name: string;
+    message: string;
+    requestId?: string;
+    status?: number;
+    locations?: ReadonlyArray<{
+      line: number;
+      column: number;
+    }>;
+    path?: ReadonlyArray<string | number>;
+    extensions?: Record<string, unknown>;
+  };
+}
+declare class StorefrontTimeoutError extends StorefrontApiError {
+  readonly timeoutInMs: number;
+  constructor(timeoutInMs: number, options?: Omit<StorefrontApiErrorOptions, "cause">);
+}
+//#endregion
+export { StorefrontApiError, StorefrontTimeoutError };
+//# sourceMappingURL=errors.d.mts.map

package/dist/client/errors.mjs

@@ -0,0 +1,52 @@
+//#region src/client/errors.ts
+var StorefrontApiError = class extends Error {
+	requestId;
+	status;
+	queryText;
+	variables;
+	locations;
+	path;
+	extensions;
+	constructor(message, options) {
+		super(message, options?.cause ? { cause: options.cause } : void 0);
+		this.name = "StorefrontApiError";
+		this.requestId = options?.requestId;
+		this.status = options?.status;
+		this.locations = options?.locations;
+		this.path = options?.path;
+		this.extensions = options?.extensions;
+	}
+	get [Symbol.toStringTag]() {
+		return this.name;
+	}
+	toString() {
+		let result = `${this.name}: ${this.message}`;
+		if (this.path) try {
+			result += ` | path: ${JSON.stringify(this.path)}`;
+		} catch {}
+		if (this.extensions) try {
+			result += ` | extensions: ${JSON.stringify(this.extensions)}`;
+		} catch {}
+		return result;
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			...this.requestId != null && { requestId: this.requestId },
+			...this.status != null && { status: this.status }
+		};
+	}
+};
+var StorefrontTimeoutError = class extends StorefrontApiError {
+	timeoutInMs;
+	constructor(timeoutInMs, options) {
+		super(`Storefront API request timed out after ${timeoutInMs}ms`, options);
+		this.name = "StorefrontTimeoutError";
+		this.timeoutInMs = timeoutInMs;
+	}
+};
+
+//#endregion
+export { StorefrontApiError, StorefrontTimeoutError };
+//# sourceMappingURL=errors.mjs.map

package/dist/client/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/client/errors.ts"],"sourcesContent":["interface StorefrontApiErrorOptions {\n  requestId?: string;\n  status?: number;\n  cause?: unknown;\n  queryText?: string;\n  variables?: Record<string, unknown>;\n  locations?: ReadonlyArray<{ line: number; column: number }>;\n  path?: ReadonlyArray<string | number>;\n  extensions?: Record<string, unknown>;\n}\n\nexport class StorefrontApiError extends Error {\n  readonly requestId?: string;\n  readonly status?: number;\n  readonly queryText?: string;\n  readonly variables?: Record<string, unknown>;\n  readonly locations?: ReadonlyArray<{ line: number; column: number }>;\n  readonly path?: ReadonlyArray<string | number>;\n  readonly extensions?: Record<string, unknown>;\n\n  constructor(message: string, options?: StorefrontApiErrorOptions) {\n    super(message, options?.cause ? { cause: options.cause } : undefined);\n    this.name = \"StorefrontApiError\";\n    this.requestId = options?.requestId;\n    this.status = options?.status;\n    this.locations = options?.locations;\n    this.path = options?.path;\n    this.extensions = options?.extensions;\n\n    if (__DEV__) {\n      this.queryText = options?.queryText;\n      this.variables = options?.variables;\n    }\n  }\n\n  get [Symbol.toStringTag]() {\n    return this.name;\n  }\n\n  override toString(): string {\n    let result = `${this.name}: ${this.message}`;\n    if (this.path) {\n      try {\n        result += ` | path: ${JSON.stringify(this.path)}`;\n      } catch {}\n    }\n    if (this.extensions) {\n      try {\n        result += ` | extensions: ${JSON.stringify(this.extensions)}`;\n      } catch {}\n    }\n    return result;\n  }\n\n  toJSON(): {\n    name: string;\n    message: string;\n    requestId?: string;\n    status?: number;\n    locations?: ReadonlyArray<{ line: number; column: number }>;\n    path?: ReadonlyArray<string | number>;\n    extensions?: Record<string, unknown>;\n  } {\n    return {\n      name: this.name,\n      message: this.message,\n      ...(this.requestId != null && { requestId: this.requestId }),\n      ...(this.status != null && { status: this.status }),\n      ...(__DEV__ && this.locations && { locations: this.locations }),\n      ...(__DEV__ && this.path && { path: this.path }),\n      ...(__DEV__ && this.extensions && { extensions: this.extensions }),\n    };\n  }\n}\n\nexport class StorefrontTimeoutError extends StorefrontApiError {\n  readonly timeoutInMs: number;\n\n  constructor(timeoutInMs: number, options?: Omit<StorefrontApiErrorOptions, \"cause\">) {\n    super(`Storefront API request timed out after ${timeoutInMs}ms`, options);\n    this.name = \"StorefrontTimeoutError\";\n    this.timeoutInMs = timeoutInMs;\n  }\n}\n"],"mappings":";AAWA,IAAa,qBAAb,cAAwC,MAAM;CAC5C,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAY,SAAiB,SAAqC;AAChE,QAAM,SAAS,SAAS,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AACrE,OAAK,OAAO;AACZ,OAAK,YAAY,SAAS;AAC1B,OAAK,SAAS,SAAS;AACvB,OAAK,YAAY,SAAS;AAC1B,OAAK,OAAO,SAAS;AACrB,OAAK,aAAa,SAAS;;CAQ7B,KAAK,OAAO,eAAe;AACzB,SAAO,KAAK;;CAGd,AAAS,WAAmB;EAC1B,IAAI,SAAS,GAAG,KAAK,KAAK,IAAI,KAAK;AACnC,MAAI,KAAK,KACP,KAAI;AACF,aAAU,YAAY,KAAK,UAAU,KAAK,KAAK;UACzC;AAEV,MAAI,KAAK,WACP,KAAI;AACF,aAAU,kBAAkB,KAAK,UAAU,KAAK,WAAW;UACrD;AAEV,SAAO;;CAGT,SAQE;AACA,SAAO;GACL,MAAM,KAAK;GACX,SAAS,KAAK;GACd,GAAI,KAAK,aAAa,QAAQ,EAAE,WAAW,KAAK,WAAW;GAC3D,GAAI,KAAK,UAAU,QAAQ,EAAE,QAAQ,KAAK,QAAQ;GAInD;;;AAIL,IAAa,yBAAb,cAA4C,mBAAmB;CAC7D,AAAS;CAET,YAAY,aAAqB,SAAoD;AACnF,QAAM,0CAA0C,YAAY,KAAK,QAAQ;AACzE,OAAK,OAAO;AACZ,OAAK,cAAc"}

package/dist/client/index.d.mts

@@ -0,0 +1,4 @@
+import { I18nConfig } from "../core/request-context.mjs";
+import { StorefrontQueryString } from "../graphql/graphql.mjs";
+import { GraphQLFormattedError, PrivateStorefrontClient, PublicStorefrontClient, RequestScopedPrivateStorefrontClient, StorefrontApi, StorefrontClient, StorefrontGraphqlResult } from "./types.mjs";
+import { createStorefrontClient } from "./client.mjs";

package/dist/client/types.d.mts

@@ -0,0 +1,147 @@
+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 { AnyStorefrontQueryString, SourceOf, StorefrontQueryString } from "../graphql/graphql.mjs";
+import { ResultOf, TadaDocumentNode, VariablesOf } from "gql.tada";
+
+//#region src/client/types.d.ts
+type DocLike = TadaDocumentNode<any, any> | AnyStorefrontQueryString;
+type InferredDoc<T extends string> = StorefrontQueryString<InferResult<T>, InferVariables<T>, T>;
+type ResolveDoc<D> = D extends DocLike ? D : D extends string ? InferredDoc<D> : never;
+type SourceText<Doc> = [SourceOf<Doc>] extends [never] ? Doc extends string ? Doc : never : SourceOf<Doc>;
+type OperationKindOfDoc<Doc> = [SourceText<Doc>] extends [never] ? "unknown" : string extends SourceText<Doc> ? "unknown" : InferOperationKind<SourceText<Doc>>;
+type GraphqlExtraOptionsForDoc<Doc, Extra extends Record<string, unknown>> = OperationKindOfDoc<Doc> extends "query" ? Extra : Omit<Extra, "cache">;
+type ResultOfDoc<Doc> = Doc extends StorefrontQueryString<infer Result, infer _Variables, string> ? Result : Doc extends TadaDocumentNode<any, any> ? ResultOf<Doc> : never;
+type VariablesOfDoc<Doc> = Doc extends StorefrontQueryString<infer _Result, infer Variables, string> ? Variables : Doc extends TadaDocumentNode<any, any> ? VariablesOf<Doc> : never;
+type StorefrontApiResultOf<Doc extends DocLike> = ResultOf<Doc>;
+type StorefrontApiVariablesOf<Doc extends DocLike> = VariablesOf<Doc>;
+interface GraphQLFormattedError {
+  readonly message: string;
+  readonly locations?: ReadonlyArray<{
+    line: number;
+    column: number;
+  }>;
+  readonly path?: ReadonlyArray<string | number>;
+  readonly extensions?: Record<string, unknown>;
+}
+type CommonOptions = {
+  storeDomain: string;
+  /**
+   * Identifies the Hydrogen storefront making Storefront API requests so Shopify can attribute
+   * cart analytics to the correct storefront.
+   */
+  storefrontId?: string;
+  /**
+   * Storefront API version used in the GraphQL endpoint path (`/api/<version>/graphql.json`).
+   * Defaults to the version baked into the package. To send some queries to a different endpoint
+   * version (e.g. `unstable`), create a second `createStorefrontClient` instance with that
+   * `apiVersion` so version routing stays explicit. Hydrogen's bundled gql.tada schema still
+   * controls type inference, so queries against fields outside that schema need their own typing.
+   */
+  apiVersion?: string;
+  defaultTimeoutInMs?: number;
+  cache?: CacheInstance;
+  waitUntil?: WaitUntil;
+};
+type AnyFetch = typeof globalThis.fetch | ((...args: never[]) => Promise<Response>);
+/**
+ * Public client — uses a public Storefront Access Token, or tokenless access
+ * when `publicStorefrontToken` is omitted.
+ *
+ * Best for: browser or mobile requests where the token is safe to expose.
+ * Token-based access is required for some Storefront API fields, including
+ * product tags, metaobjects, metafields, menus, and customers.
+ */
+interface PublicClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  fetch?: Fetch;
+  publicStorefrontToken?: string | undefined;
+}
+/**
+ * Private client — uses a private Storefront Access Token.
+ *
+ * `buyerIp` must be resolved on the request context before creating the client.
+ *
+ * Best for: SSR/server-side requests where you control the fetch
+ * layer and can forward trusted buyer context.
+ * Token-based access is required for some Storefront API fields, including
+ * product tags, metaobjects, metafields, menus, and customers.
+ */
+interface PrivateClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  fetch?: Fetch;
+  privateStorefrontToken: string;
+}
+/**
+ * Private client without buyer context — uses a private Storefront Access Token
+ * but does NOT forward per-buyer identity.
+ *
+ * Best for: background jobs, webhooks, or server contexts where no
+ * shopper identity is available.
+ */
+interface PrivateNoBuyerContextClientOptions<Fetch extends AnyFetch | undefined = typeof globalThis.fetch> extends CommonOptions {
+  fetch?: Fetch;
+  privateStorefrontToken: string;
+}
+type StorefrontClientOptions = PublicClientOptions | PrivateClientOptions | PrivateNoBuyerContextClientOptions;
+type CreateStorefrontClientArgs<RequestContext extends ShopifyRequestContext = ShopifyRequestContext, Type extends ClientType = ClientType, CacheConfig extends CacheInstance | undefined = CacheInstance | undefined> = {
+  type: "public" & Type;
+  requestContext: RequestContext;
+  config: PublicClientOptions<AnyFetch | undefined> & {
+    cache?: CacheConfig;
+  };
+} | {
+  type: "private" & Type;
+  requestContext: RequestContext & ShopifyRequestContextWithBuyerIp;
+  config: PrivateClientOptions<AnyFetch | undefined> & {
+    cache?: CacheConfig;
+  };
+} | {
+  type: "private_no_buyer_context" & Type;
+  requestContext: RequestContext;
+  config: PrivateNoBuyerContextClientOptions<AnyFetch | undefined> & {
+    cache?: CacheConfig;
+  };
+};
+type AutoAddedVariableNames = "country" | "language";
+type UserVariables<Doc> = Omit<VariablesOfDoc<Doc>, AutoAddedVariableNames>;
+type HasNoRequiredKeys<T> = Record<string, never> extends T ? true : false;
+type StorefrontGraphqlOptions = {
+  signal?: AbortSignal;
+};
+type MergedOptions<Doc extends DocLike, Extra extends Record<string, unknown>> = Extra & StorefrontGraphqlOptions & (HasNoRequiredKeys<UserVariables<Doc>> extends true ? {
+  variables?: UserVariables<Doc>;
+} : {
+  variables: UserVariables<Doc>;
+});
+type GqlRestParam<Doc extends DocLike, Extra extends Record<string, unknown> = {}> = HasNoRequiredKeys<MergedOptions<Doc, GraphqlExtraOptionsForDoc<Doc, Extra>>> extends true ? [options?: MergedOptions<Doc, GraphqlExtraOptionsForDoc<Doc, Extra>>] : [options: MergedOptions<Doc, GraphqlExtraOptionsForDoc<Doc, Extra>>];
+type StorefrontGraphqlResult<Doc extends DocLike> = {
+  data: ResultOfDoc<Doc>;
+  errors?: undefined;
+  headers: Headers;
+} | {
+  data: ResultOfDoc<Doc> | null;
+  errors: GraphQLFormattedError[];
+  headers: Headers;
+};
+type StorefrontGraphql = <const Doc extends DocLike | string>(doc: Doc, ...options: GqlRestParam<ResolveDoc<Doc>>) => Promise<StorefrontGraphqlResult<ResolveDoc<Doc>>>;
+type ClientType = /** Public access token or tokenless access. Best for: browser requests. */"public" /** Private token with trusted buyer context. Best for: SSR. */ | "private" /** Private token without buyer context. Best for: background jobs, webhooks. */ | "private_no_buyer_context";
+type StorefrontClient<Extra extends Record<string, unknown> = {}, Type extends ClientType = ClientType, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = {
+  type: Type;
+  i18n: RequestContext["i18n"];
+  graphql: <const Doc extends DocLike | string>(doc: Doc, ...options: GqlRestParam<ResolveDoc<Doc>, Extra>) => Promise<StorefrontGraphqlResult<ResolveDoc<Doc>>>;
+  apiUrl: string;
+  storeUrl: string;
+  storefrontId?: string;
+  requestContext: RequestContext;
+};
+type PublicStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = StorefrontClient<Extra, "public", RequestContext>;
+type PrivateStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContextWithBuyerIp = ShopifyRequestContextWithBuyerIp> = StorefrontClient<Extra, "private", RequestContext>;
+type RequestScopedPrivateStorefrontClient<Extra extends Record<string, unknown> = {}> = PrivateStorefrontClient<Extra, ShopifyRequestContextWithBuyerIp>;
+type PrivateNoBuyerContextStorefrontClient<Extra extends Record<string, unknown> = {}, RequestContext extends ShopifyRequestContext = ShopifyRequestContext> = StorefrontClient<Extra, "private_no_buyer_context", RequestContext>;
+declare namespace StorefrontApi {
+  type ResultOf<Doc extends DocLike> = StorefrontApiResultOf<Doc>;
+  type VariablesOf<Doc extends DocLike> = StorefrontApiVariablesOf<Doc>;
+  type DocumentNode = DocLike;
+}
+//#endregion
+export { ClientType, CreateStorefrontClientArgs, GqlRestParam, GraphQLFormattedError, PrivateClientOptions, PrivateNoBuyerContextClientOptions, PrivateNoBuyerContextStorefrontClient, PrivateStorefrontClient, PublicClientOptions, PublicStorefrontClient, RequestScopedPrivateStorefrontClient, StorefrontApi, StorefrontClient, StorefrontClientOptions, StorefrontGraphql, StorefrontGraphqlOptions, StorefrontGraphqlResult };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1,8 @@
+import { CartStore } from "../cart/cart.mjs";
+
+//#region src/core/analytics/cart-tracker.d.ts
+type CartAnalyticsStore = Pick<CartStore, "getState" | "subscribe">;
+declare function trackCartAnalytics(store: CartAnalyticsStore): () => void;
+//#endregion
+export { trackCartAnalytics };
+//# sourceMappingURL=cart-tracker.d.mts.map

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

@@ -0,0 +1,144 @@
+import { AnalyticsEvent } from "./events.mjs";
+import { flattenConnection } from "./utils/flatten-connection.mjs";
+
+//#region src/core/analytics/cart-tracker.ts
+function trackCartAnalytics(store) {
+	const analytics = getGlobalAnalytics();
+	const state = {
+		prevCart: toAnalyticsCart(store.getState()),
+		lastEventId: null
+	};
+	if (state.prevCart) syncShopifyCurrency(state.prevCart);
+	return store.subscribe((cartState) => {
+		const cart = toAnalyticsCart(cartState);
+		if (!cart) return;
+		trackCartChange(analytics, state, cart);
+	});
+}
+function trackCartChange(analytics, state, cart) {
+	if (!cart || !cart.updatedAt) return;
+	syncShopifyCurrency(cart);
+	if (cart.updatedAt === state.prevCart?.updatedAt) return;
+	let cartLastUpdatedAt;
+	try {
+		cartLastUpdatedAt = JSON.parse(localStorage.getItem("cartLastUpdatedAt") || "");
+	} catch {
+		cartLastUpdatedAt = null;
+	}
+	if (cart.id === cartLastUpdatedAt?.id && cart.updatedAt === cartLastUpdatedAt?.updatedAt) {
+		state.prevCart = cart;
+		return;
+	}
+	if (cart.updatedAt === state.lastEventId) return;
+	state.lastEventId = cart.updatedAt;
+	const config = analytics.getConfig();
+	const payload = {
+		eventTimestamp: Date.now(),
+		cart,
+		prevCart: state.prevCart,
+		shop: config.shop,
+		customData: config.customData
+	};
+	analytics.publish(AnalyticsEvent.CART_UPDATED, payload);
+	try {
+		localStorage.setItem("cartLastUpdatedAt", JSON.stringify({
+			id: cart.id,
+			updatedAt: cart.updatedAt
+		}));
+	} catch {}
+	const previousCartLines = flattenConnection(state.prevCart?.lines);
+	const currentCartLines = flattenConnection(cart.lines);
+	previousCartLines.forEach((prevLine) => {
+		const matchedLineId = currentCartLines.filter((line) => prevLine.id === line.id);
+		if (matchedLineId.length === 1) {
+			const matchedLine = matchedLineId[0];
+			if (prevLine.quantity < matchedLine.quantity) analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {
+				...payload,
+				prevLine,
+				currentLine: matchedLine
+			});
+			else if (prevLine.quantity > matchedLine.quantity) analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {
+				...payload,
+				prevLine,
+				currentLine: matchedLine
+			});
+		} else analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {
+			...payload,
+			prevLine
+		});
+	});
+	currentCartLines.forEach((line) => {
+		const matchedLineId = previousCartLines.filter((previousLine) => line.id === previousLine.id);
+		if (!matchedLineId || matchedLineId.length === 0) analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {
+			...payload,
+			currentLine: line
+		});
+	});
+	state.prevCart = cart;
+}
+function getGlobalAnalytics() {
+	const analytics = typeof window !== "undefined" ? window.Shopify?.analytics : void 0;
+	if (!analytics) throw new Error("Shopify analytics bus is not available. Render ShopifyScripts before calling trackCartAnalytics().");
+	return analytics;
+}
+function toAnalyticsCart(state) {
+	const cart = state.data;
+	if (!cart.id || hasPendingCartWork(state)) return null;
+	return {
+		id: cart.id,
+		updatedAt: getCartUpdatedAt(cart),
+		cost: cart.cost,
+		lines: { nodes: cart.lines.nodes.flatMap((line) => {
+			const merchandise = line.merchandise;
+			if (!merchandise) return [];
+			const product = merchandise.product;
+			const productId = typeof product.id === "string" ? product.id : "";
+			const vendor = typeof product.vendor === "string" ? product.vendor : "";
+			const productType = typeof product.productType === "string" ? product.productType : void 0;
+			return [{
+				id: line.id,
+				quantity: line.quantity,
+				merchandise: {
+					id: merchandise.id,
+					title: merchandise.title ?? product.title,
+					price: line.cost.amountPerQuantity,
+					sku: typeof merchandise.sku === "string" ? merchandise.sku : null,
+					product: {
+						id: productId,
+						title: product.title,
+						vendor,
+						productType,
+						handle: product.handle
+					}
+				}
+			}];
+		}) }
+	};
+}
+function hasPendingCartWork({ pending, revalidating }) {
+	const hasPendingCost = pending.cost ?? (pending.lines.size > 0 || pending.discountCodes.size > 0);
+	return revalidating === true || hasPendingCost || pending.note || pending.attributes;
+}
+function getCartUpdatedAt(cart) {
+	return typeof cart.updatedAt === "string" ? cart.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
+}
+function syncShopifyCurrency(cart) {
+	if (typeof window === "undefined") return;
+	const currencyCode = getCartCurrencyCode(cart);
+	if (!currencyCode) return;
+	const normalizedCurrencyCode = currencyCode.toUpperCase();
+	const shopifyWindow = window;
+	const shopify = shopifyWindow.Shopify ??= {};
+	if (shopify.currency?.active === normalizedCurrencyCode) return;
+	shopify.currency = { active: normalizedCurrencyCode };
+}
+function getCartCurrencyCode(cart) {
+	return nonEmptyCurrencyCode(cart.cost?.totalAmount?.currencyCode) ?? nonEmptyCurrencyCode(cart.cost?.subtotalAmount?.currencyCode) ?? flattenConnection(cart.lines).find((line) => line.merchandise.price.currencyCode)?.merchandise.price.currencyCode;
+}
+function nonEmptyCurrencyCode(currencyCode) {
+	return currencyCode || void 0;
+}
+
+//#endregion
+export { trackCartAnalytics };
+//# sourceMappingURL=cart-tracker.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cart-tracker.mjs","names":[],"sources":["../../../src/core/analytics/cart-tracker.ts"],"sourcesContent":["import type { CartStore } from \"../cart/cart\";\nimport type { CartData, CartState } from \"../cart/state\";\nimport { AnalyticsEvent } from \"./events\";\nimport type {\n  AnalyticsCart,\n  AnalyticsCartLine,\n  CartUpdatePayload,\n  StorefrontAnalytics,\n} from \"./types\";\nimport { flattenConnection } from \"./utils/flatten-connection\";\n\ntype CartTrackerAnalytics = Pick<StorefrontAnalytics, \"publish\" | \"getConfig\">;\ntype CartAnalyticsStore = Pick<CartStore, \"getState\" | \"subscribe\">;\n\ntype CartStorage = {\n  updatedAt: string;\n  id: string;\n};\n\ntype CartTrackerState = {\n  prevCart: AnalyticsCart | null;\n  lastEventId: string | null;\n};\n\nexport function trackCartAnalytics(store: CartAnalyticsStore): () => void {\n  const analytics = getGlobalAnalytics();\n  const state: CartTrackerState = {\n    prevCart: toAnalyticsCart(store.getState()),\n    lastEventId: null,\n  };\n\n  if (state.prevCart) syncShopifyCurrency(state.prevCart);\n\n  return store.subscribe((cartState) => {\n    const cart = toAnalyticsCart(cartState);\n    if (!cart) return;\n\n    trackCartChange(analytics, state, cart);\n  });\n}\n\nfunction trackCartChange(\n  analytics: CartTrackerAnalytics,\n  state: CartTrackerState,\n  cart: AnalyticsCart,\n): void {\n  if (!cart || !cart.updatedAt) return;\n\n  syncShopifyCurrency(cart);\n\n  if (cart.updatedAt === state.prevCart?.updatedAt) return;\n\n  let cartLastUpdatedAt: CartStorage | null;\n  try {\n    cartLastUpdatedAt = JSON.parse(localStorage.getItem(\"cartLastUpdatedAt\") || \"\");\n  } catch {\n    cartLastUpdatedAt = null;\n  }\n\n  if (cart.id === cartLastUpdatedAt?.id && cart.updatedAt === cartLastUpdatedAt?.updatedAt) {\n    state.prevCart = cart;\n    return;\n  }\n\n  if (cart.updatedAt === state.lastEventId) return;\n  state.lastEventId = cart.updatedAt;\n\n  const config = analytics.getConfig();\n  const payload: CartUpdatePayload = {\n    eventTimestamp: Date.now(),\n    cart,\n    prevCart: state.prevCart,\n    shop: config.shop,\n    customData: config.customData,\n  };\n\n  analytics.publish(AnalyticsEvent.CART_UPDATED, payload);\n\n  try {\n    localStorage.setItem(\n      \"cartLastUpdatedAt\",\n      JSON.stringify({ id: cart.id, updatedAt: cart.updatedAt }),\n    );\n  } catch {\n    // Safari private browsing or storage quota exceeded; analytics\n    // deduplication will rely on in-memory prevCart only for this session.\n  }\n\n  const previousCartLines = flattenConnection<AnalyticsCartLine>(state.prevCart?.lines);\n  const currentCartLines = flattenConnection<AnalyticsCartLine>(cart.lines);\n\n  previousCartLines.forEach((prevLine) => {\n    const matchedLineId = currentCartLines.filter((line) => prevLine.id === line.id);\n    if (matchedLineId.length === 1) {\n      const matchedLine = matchedLineId[0];\n      if (prevLine.quantity < matchedLine.quantity) {\n        analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {\n          ...payload,\n          prevLine,\n          currentLine: matchedLine,\n        });\n      } else if (prevLine.quantity > matchedLine.quantity) {\n        analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {\n          ...payload,\n          prevLine,\n          currentLine: matchedLine,\n        });\n      }\n    } else {\n      analytics.publish(AnalyticsEvent.PRODUCT_REMOVED_FROM_CART, {\n        ...payload,\n        prevLine,\n      });\n    }\n  });\n\n  currentCartLines.forEach((line) => {\n    const matchedLineId = previousCartLines.filter((previousLine) => line.id === previousLine.id);\n    if (!matchedLineId || matchedLineId.length === 0) {\n      analytics.publish(AnalyticsEvent.PRODUCT_ADD_TO_CART, {\n        ...payload,\n        currentLine: line,\n      });\n    }\n  });\n\n  state.prevCart = cart;\n}\n\nfunction getGlobalAnalytics(): CartTrackerAnalytics {\n  const analytics = typeof window !== \"undefined\" ? window.Shopify?.analytics : undefined;\n  if (!analytics) {\n    throw new Error(\n      \"Shopify analytics bus is not available. Render ShopifyScripts before calling trackCartAnalytics().\",\n    );\n  }\n\n  return analytics;\n}\n\nfunction toAnalyticsCart(state: CartState): AnalyticsCart | null {\n  const cart = state.data;\n  if (!cart.id || hasPendingCartWork(state)) return null;\n\n  return {\n    id: cart.id,\n    updatedAt: getCartUpdatedAt(cart),\n    cost: cart.cost,\n    lines: {\n      nodes: cart.lines.nodes.flatMap((line): AnalyticsCartLine[] => {\n        const merchandise = line.merchandise;\n        if (!merchandise) return [];\n\n        const product = merchandise.product;\n        const productId = typeof product.id === \"string\" ? product.id : \"\";\n        const vendor = typeof product.vendor === \"string\" ? product.vendor : \"\";\n        const productType =\n          typeof product.productType === \"string\" ? product.productType : undefined;\n\n        return [\n          {\n            id: line.id,\n            quantity: line.quantity,\n            merchandise: {\n              id: merchandise.id,\n              title: merchandise.title ?? product.title,\n              price: line.cost.amountPerQuantity,\n              sku: typeof merchandise.sku === \"string\" ? merchandise.sku : null,\n              product: {\n                id: productId,\n                title: product.title,\n                vendor,\n                productType,\n                handle: product.handle,\n              },\n            },\n          },\n        ];\n      }),\n    },\n  };\n}\n\nfunction hasPendingCartWork({ pending, revalidating }: CartState): boolean {\n  const hasPendingCost = pending.cost ?? (pending.lines.size > 0 || pending.discountCodes.size > 0);\n  return revalidating === true || hasPendingCost || pending.note || pending.attributes;\n}\n\nfunction getCartUpdatedAt(cart: CartData): string {\n  return typeof cart.updatedAt === \"string\" ? cart.updatedAt : new Date().toISOString();\n}\n\nfunction syncShopifyCurrency(cart: AnalyticsCart): void {\n  if (typeof window === \"undefined\") return;\n\n  const currencyCode = getCartCurrencyCode(cart);\n  if (!currencyCode) return;\n\n  const normalizedCurrencyCode = currencyCode.toUpperCase();\n  const shopifyWindow: { Shopify?: { currency?: { active: string } } } = window;\n  const shopify = (shopifyWindow.Shopify ??= {});\n  if (shopify.currency?.active === normalizedCurrencyCode) return;\n\n  shopify.currency = { active: normalizedCurrencyCode };\n}\n\nfunction getCartCurrencyCode(cart: AnalyticsCart): string | undefined {\n  return (\n    nonEmptyCurrencyCode(cart.cost?.totalAmount?.currencyCode) ??\n    nonEmptyCurrencyCode(cart.cost?.subtotalAmount?.currencyCode) ??\n    flattenConnection<AnalyticsCartLine>(cart.lines).find(\n      (line) => line.merchandise.price.currencyCode,\n    )?.merchandise.price.currencyCode\n  );\n}\n\nfunction nonEmptyCurrencyCode(currencyCode: string | undefined): string | undefined {\n  return currencyCode || undefined;\n}\n"],"mappings":";;;;AAwBA,SAAgB,mBAAmB,OAAuC;CACxE,MAAM,YAAY,oBAAoB;CACtC,MAAM,QAA0B;EAC9B,UAAU,gBAAgB,MAAM,UAAU,CAAC;EAC3C,aAAa;EACd;AAED,KAAI,MAAM,SAAU,qBAAoB,MAAM,SAAS;AAEvD,QAAO,MAAM,WAAW,cAAc;EACpC,MAAM,OAAO,gBAAgB,UAAU;AACvC,MAAI,CAAC,KAAM;AAEX,kBAAgB,WAAW,OAAO,KAAK;GACvC;;AAGJ,SAAS,gBACP,WACA,OACA,MACM;AACN,KAAI,CAAC,QAAQ,CAAC,KAAK,UAAW;AAE9B,qBAAoB,KAAK;AAEzB,KAAI,KAAK,cAAc,MAAM,UAAU,UAAW;CAElD,IAAI;AACJ,KAAI;AACF,sBAAoB,KAAK,MAAM,aAAa,QAAQ,oBAAoB,IAAI,GAAG;SACzE;AACN,sBAAoB;;AAGtB,KAAI,KAAK,OAAO,mBAAmB,MAAM,KAAK,cAAc,mBAAmB,WAAW;AACxF,QAAM,WAAW;AACjB;;AAGF,KAAI,KAAK,cAAc,MAAM,YAAa;AAC1C,OAAM,cAAc,KAAK;CAEzB,MAAM,SAAS,UAAU,WAAW;CACpC,MAAM,UAA6B;EACjC,gBAAgB,KAAK,KAAK;EAC1B;EACA,UAAU,MAAM;EAChB,MAAM,OAAO;EACb,YAAY,OAAO;EACpB;AAED,WAAU,QAAQ,eAAe,cAAc,QAAQ;AAEvD,KAAI;AACF,eAAa,QACX,qBACA,KAAK,UAAU;GAAE,IAAI,KAAK;GAAI,WAAW,KAAK;GAAW,CAAC,CAC3D;SACK;CAKR,MAAM,oBAAoB,kBAAqC,MAAM,UAAU,MAAM;CACrF,MAAM,mBAAmB,kBAAqC,KAAK,MAAM;AAEzE,mBAAkB,SAAS,aAAa;EACtC,MAAM,gBAAgB,iBAAiB,QAAQ,SAAS,SAAS,OAAO,KAAK,GAAG;AAChF,MAAI,cAAc,WAAW,GAAG;GAC9B,MAAM,cAAc,cAAc;AAClC,OAAI,SAAS,WAAW,YAAY,SAClC,WAAU,QAAQ,eAAe,qBAAqB;IACpD,GAAG;IACH;IACA,aAAa;IACd,CAAC;YACO,SAAS,WAAW,YAAY,SACzC,WAAU,QAAQ,eAAe,2BAA2B;IAC1D,GAAG;IACH;IACA,aAAa;IACd,CAAC;QAGJ,WAAU,QAAQ,eAAe,2BAA2B;GAC1D,GAAG;GACH;GACD,CAAC;GAEJ;AAEF,kBAAiB,SAAS,SAAS;EACjC,MAAM,gBAAgB,kBAAkB,QAAQ,iBAAiB,KAAK,OAAO,aAAa,GAAG;AAC7F,MAAI,CAAC,iBAAiB,cAAc,WAAW,EAC7C,WAAU,QAAQ,eAAe,qBAAqB;GACpD,GAAG;GACH,aAAa;GACd,CAAC;GAEJ;AAEF,OAAM,WAAW;;AAGnB,SAAS,qBAA2C;CAClD,MAAM,YAAY,OAAO,WAAW,cAAc,OAAO,SAAS,YAAY;AAC9E,KAAI,CAAC,UACH,OAAM,IAAI,MACR,qGACD;AAGH,QAAO;;AAGT,SAAS,gBAAgB,OAAwC;CAC/D,MAAM,OAAO,MAAM;AACnB,KAAI,CAAC,KAAK,MAAM,mBAAmB,MAAM,CAAE,QAAO;AAElD,QAAO;EACL,IAAI,KAAK;EACT,WAAW,iBAAiB,KAAK;EACjC,MAAM,KAAK;EACX,OAAO,EACL,OAAO,KAAK,MAAM,MAAM,SAAS,SAA8B;GAC7D,MAAM,cAAc,KAAK;AACzB,OAAI,CAAC,YAAa,QAAO,EAAE;GAE3B,MAAM,UAAU,YAAY;GAC5B,MAAM,YAAY,OAAO,QAAQ,OAAO,WAAW,QAAQ,KAAK;GAChE,MAAM,SAAS,OAAO,QAAQ,WAAW,WAAW,QAAQ,SAAS;GACrE,MAAM,cACJ,OAAO,QAAQ,gBAAgB,WAAW,QAAQ,cAAc;AAElE,UAAO,CACL;IACE,IAAI,KAAK;IACT,UAAU,KAAK;IACf,aAAa;KACX,IAAI,YAAY;KAChB,OAAO,YAAY,SAAS,QAAQ;KACpC,OAAO,KAAK,KAAK;KACjB,KAAK,OAAO,YAAY,QAAQ,WAAW,YAAY,MAAM;KAC7D,SAAS;MACP,IAAI;MACJ,OAAO,QAAQ;MACf;MACA;MACA,QAAQ,QAAQ;MACjB;KACF;IACF,CACF;IACD,EACH;EACF;;AAGH,SAAS,mBAAmB,EAAE,SAAS,gBAAoC;CACzE,MAAM,iBAAiB,QAAQ,SAAS,QAAQ,MAAM,OAAO,KAAK,QAAQ,cAAc,OAAO;AAC/F,QAAO,iBAAiB,QAAQ,kBAAkB,QAAQ,QAAQ,QAAQ;;AAG5E,SAAS,iBAAiB,MAAwB;AAChD,QAAO,OAAO,KAAK,cAAc,WAAW,KAAK,6BAAY,IAAI,MAAM,EAAC,aAAa;;AAGvF,SAAS,oBAAoB,MAA2B;AACtD,KAAI,OAAO,WAAW,YAAa;CAEnC,MAAM,eAAe,oBAAoB,KAAK;AAC9C,KAAI,CAAC,aAAc;CAEnB,MAAM,yBAAyB,aAAa,aAAa;CACzD,MAAM,gBAAiE;CACvE,MAAM,UAAW,cAAc,YAAY,EAAE;AAC7C,KAAI,QAAQ,UAAU,WAAW,uBAAwB;AAEzD,SAAQ,WAAW,EAAE,QAAQ,wBAAwB;;AAGvD,SAAS,oBAAoB,MAAyC;AACpE,QACE,qBAAqB,KAAK,MAAM,aAAa,aAAa,IAC1D,qBAAqB,KAAK,MAAM,gBAAgB,aAAa,IAC7D,kBAAqC,KAAK,MAAM,CAAC,MAC9C,SAAS,KAAK,YAAY,MAAM,aAClC,EAAE,YAAY,MAAM;;AAIzB,SAAS,qBAAqB,cAAsD;AAClF,QAAO,gBAAgB"}

package/dist/core/analytics/events.d.mts

@@ -0,0 +1,15 @@
+//#region src/core/analytics/events.d.ts
+declare const AnalyticsEvent: {
+  PAGE_VIEWED: "page_viewed";
+  PRODUCT_VIEWED: "product_viewed";
+  COLLECTION_VIEWED: "collection_viewed";
+  CART_VIEWED: "cart_viewed";
+  SEARCH_VIEWED: "search_viewed";
+  CART_UPDATED: "cart_updated";
+  PRODUCT_ADD_TO_CART: "product_added_to_cart";
+  PRODUCT_REMOVED_FROM_CART: "product_removed_from_cart";
+};
+type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];
+//#endregion
+export { AnalyticsEvent, AnalyticsEventName };
+//# sourceMappingURL=events.d.mts.map

package/dist/core/analytics/events.mjs

@@ -0,0 +1,15 @@
+//#region src/core/analytics/events.ts
+const AnalyticsEvent = {
+	PAGE_VIEWED: "page_viewed",
+	PRODUCT_VIEWED: "product_viewed",
+	COLLECTION_VIEWED: "collection_viewed",
+	CART_VIEWED: "cart_viewed",
+	SEARCH_VIEWED: "search_viewed",
+	CART_UPDATED: "cart_updated",
+	PRODUCT_ADD_TO_CART: "product_added_to_cart",
+	PRODUCT_REMOVED_FROM_CART: "product_removed_from_cart"
+};
+
+//#endregion
+export { AnalyticsEvent };
+//# sourceMappingURL=events.mjs.map

package/dist/core/analytics/events.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.mjs","names":[],"sources":["../../../src/core/analytics/events.ts"],"sourcesContent":["export const AnalyticsEvent = {\n  PAGE_VIEWED: \"page_viewed\" as const,\n  PRODUCT_VIEWED: \"product_viewed\" as const,\n  COLLECTION_VIEWED: \"collection_viewed\" as const,\n  CART_VIEWED: \"cart_viewed\" as const,\n  SEARCH_VIEWED: \"search_viewed\" as const,\n\n  CART_UPDATED: \"cart_updated\" as const,\n  PRODUCT_ADD_TO_CART: \"product_added_to_cart\" as const,\n  PRODUCT_REMOVED_FROM_CART: \"product_removed_from_cart\" as const,\n};\n\nexport type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];\n"],"mappings":";AAAA,MAAa,iBAAiB;CAC5B,aAAa;CACb,gBAAgB;CAChB,mBAAmB;CACnB,aAAa;CACb,eAAe;CAEf,cAAc;CACd,qBAAqB;CACrB,2BAA2B;CAC5B"}

package/dist/core/analytics/index.d.mts

@@ -0,0 +1,3 @@
+import { trackCartAnalytics } from "./cart-tracker.mjs";
+import { AnalyticsEvent, AnalyticsEventName } from "./events.mjs";
+import { AnalyticsCart, AnalyticsCartLine, AnalyticsEventMap, CartLineUpdatePayload, CartUpdatePayload, CartViewPayload, CollectionViewPayload, ConsentConfig, EventPayloads, OtherData, PageViewPayload, PayloadFor, ProductPayload, ProductViewPayload, SearchViewPayload, ShopAnalytics, StorefrontAnalytics, StorefrontAnalyticsConfig, StorefrontAnalyticsDestination, StorefrontAnalyticsDestinationSetupContext } from "./types.mjs";