@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

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

@@ -1 +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\n/**\n * Subscribes to a cart store and publishes analytics events when the cart changes.\n *\n * Emits `cart_updated` whenever a settled cart's `updatedAt` changes, plus\n * `product_added_to_cart` / `product_removed_from_cart` for each line that was\n * added, removed, or changed quantity. Deduplicates on `updatedAt` with an\n * in-memory cursor (within this subscription) and `localStorage` (across full\n * page loads and tabs). A store filled from your own cart query must select\n * `updatedAt`, or deduplication can't work.\n *\n * @throws {Error} If `window.Shopify.analytics` is not set (including on the server).\n *   Render `ShopifyScripts` (or the `getShopifyScriptTags()` output) first.\n * @returns An unsubscribe function that stops tracking.\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 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":";;;;;;;;;;;;;;;;;;AAsCA,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,KAAK,8BAAa,IAAI,MAAM,EAAC,aAAa;;AAGnD,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"}
+{"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\">;\n/** A cart store, or any object with the cart store's `getState()` and `subscribe()` methods. */\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\n/**\n * Publishes cart analytics events when the server confirms a change to the customer's cart. In React, call `useCartAnalytics`.\n *\n * The function publishes `cart_updated` when the cart's update time changes, plus\n * `product_added_to_cart` or `product_removed_from_cart` for each added line, removed\n * line, and quantity change. The function waits until no cart change or reload is in flight.\n * Analytics payloads leave out cart lines without merchandise.\n *\n * The function stores the last published cart update in local storage under `cartLastUpdatedAt`\n * to avoid repeat events across page loads and tabs. A store that you fill from your own cart query\n * must select `updatedAt`. Without the update time, the function publishes on every confirmed cart state.\n * The function also sets `window.Shopify.currency.active` to the cart's currency.\n *\n * The function throws when the Shopify analytics bus isn't available, including during server rendering.\n * Render `ShopifyScripts`, then start tracking in a client-only effect, such as `useEffect` or `onMounted`.\n *\n * @param store The cart store to track.\n * @throws {Error} If `window.Shopify.analytics` isn't set, including on the server.\n *   Render Shopify's script tags first.\n * @returns A function that stops tracking.\n * @publicDocs\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 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":"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"}

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

@@ -1,21 +1,27 @@
 //#region src/core/analytics/events.d.ts
 /**
- * Canonical event names for the Hydrogen analytics bus.
+ * The names of the analytics events that Hydrogen supports.
  *
- * Use these as the `event` argument to `publish()` and a destination's `subscribe()`. Raw string
- * literals are type-checked and narrow the payload the same way; the constants add
- * autocomplete and a single place to rename.
+ * Pass a constant as the event name when you publish an event or subscribe a destination.
+ * TypeScript narrows the payload to match the event name.
+ *
+ * @publicDocs
  */
 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";
+  /** Publish when a customer views a page. Hydrogen fills in the current URL when the payload has none. */PAGE_VIEWED: "page_viewed"; /** Publish when a customer views a product. The payload lists the viewed products. */
+  PRODUCT_VIEWED: "product_viewed"; /** Publish when a customer views a collection. The payload identifies the collection by ID and handle. */
+  COLLECTION_VIEWED: "collection_viewed"; /** Publish when a customer views the cart. The payload carries the current cart. */
+  CART_VIEWED: "cart_viewed"; /** Publish when a customer views search results. The payload carries the search term. */
+  SEARCH_VIEWED: "search_viewed"; /** Cart tracking publishes this event when the cart changes. */
+  CART_UPDATED: "cart_updated"; /** Cart tracking publishes this event when the customer adds a line or raises a line's quantity. */
+  PRODUCT_ADD_TO_CART: "product_added_to_cart"; /** Cart tracking publishes this event when the customer removes a line or lowers a line's quantity. */
   PRODUCT_REMOVED_FROM_CART: "product_removed_from_cart";
 };
+/**
+ * The name of a supported analytics event, such as `"page_viewed"`.
+ *
+ * @publicDocs
+ */
 type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];
 //#endregion
 export { AnalyticsEvent, AnalyticsEventName };

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

@@ -1,19 +1,28 @@
 //#region src/core/analytics/events.ts
 /**
-* Canonical event names for the Hydrogen analytics bus.
+* The names of the analytics events that Hydrogen supports.
 *
-* Use these as the `event` argument to `publish()` and a destination's `subscribe()`. Raw string
-* literals are type-checked and narrow the payload the same way; the constants add
-* autocomplete and a single place to rename.
+* Pass a constant as the event name when you publish an event or subscribe a destination.
+* TypeScript narrows the payload to match the event name.
+*
+* @publicDocs
 */
 const AnalyticsEvent = {
+	/** Publish when a customer views a page. Hydrogen fills in the current URL when the payload has none. */
 	PAGE_VIEWED: "page_viewed",
+	/** Publish when a customer views a product. The payload lists the viewed products. */
 	PRODUCT_VIEWED: "product_viewed",
+	/** Publish when a customer views a collection. The payload identifies the collection by ID and handle. */
 	COLLECTION_VIEWED: "collection_viewed",
+	/** Publish when a customer views the cart. The payload carries the current cart. */
 	CART_VIEWED: "cart_viewed",
+	/** Publish when a customer views search results. The payload carries the search term. */
 	SEARCH_VIEWED: "search_viewed",
+	/** Cart tracking publishes this event when the cart changes. */
 	CART_UPDATED: "cart_updated",
+	/** Cart tracking publishes this event when the customer adds a line or raises a line's quantity. */
 	PRODUCT_ADD_TO_CART: "product_added_to_cart",
+	/** Cart tracking publishes this event when the customer removes a line or lowers a line's quantity. */
 	PRODUCT_REMOVED_FROM_CART: "product_removed_from_cart"
 };
 

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

@@ -1 +1 @@
-{"version":3,"file":"events.mjs","names":[],"sources":["../../../../src/core/analytics/events.ts"],"sourcesContent":["/**\n * Canonical event names for the Hydrogen analytics bus.\n *\n * Use these as the `event` argument to `publish()` and a destination's `subscribe()`. Raw string\n * literals are type-checked and narrow the payload the same way; the constants add\n * autocomplete and a single place to rename.\n */\nexport 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":";;;;;;;;AAOA,MAAa,iBAAiB;CAC5B,aAAa;CACb,gBAAgB;CAChB,mBAAmB;CACnB,aAAa;CACb,eAAe;CAEf,cAAc;CACd,qBAAqB;CACrB,2BAA2B;CAC5B"}
+{"version":3,"file":"events.mjs","names":[],"sources":["../../../../src/core/analytics/events.ts"],"sourcesContent":["/**\n * The names of the analytics events that Hydrogen supports.\n *\n * Pass a constant as the event name when you publish an event or subscribe a destination.\n * TypeScript narrows the payload to match the event name.\n *\n * @publicDocs\n */\nexport const AnalyticsEvent = {\n  /** Publish when a customer views a page. Hydrogen fills in the current URL when the payload has none. */\n  PAGE_VIEWED: \"page_viewed\" as const,\n  /** Publish when a customer views a product. The payload lists the viewed products. */\n  PRODUCT_VIEWED: \"product_viewed\" as const,\n  /** Publish when a customer views a collection. The payload identifies the collection by ID and handle. */\n  COLLECTION_VIEWED: \"collection_viewed\" as const,\n  /** Publish when a customer views the cart. The payload carries the current cart. */\n  CART_VIEWED: \"cart_viewed\" as const,\n  /** Publish when a customer views search results. The payload carries the search term. */\n  SEARCH_VIEWED: \"search_viewed\" as const,\n\n  /** Cart tracking publishes this event when the cart changes. */\n  CART_UPDATED: \"cart_updated\" as const,\n  /** Cart tracking publishes this event when the customer adds a line or raises a line's quantity. */\n  PRODUCT_ADD_TO_CART: \"product_added_to_cart\" as const,\n  /** Cart tracking publishes this event when the customer removes a line or lowers a line's quantity. */\n  PRODUCT_REMOVED_FROM_CART: \"product_removed_from_cart\" as const,\n};\n\n/** The analytics event constants, keyed by constant name. */\ntype AnalyticsEventMap = typeof AnalyticsEvent;\n\n/**\n * The names of the analytics events that Hydrogen supports. Pass a value as the event name when you publish an event or subscribe a destination. TypeScript narrows the payload to match the event name.\n *\n * @publicDocs\n */\nexport interface AnalyticsEventForDocs extends AnalyticsEventMap {}\n\n/**\n * The name of a supported analytics event, such as `\"page_viewed\"`.\n *\n * @publicDocs\n */\nexport type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];\n"],"mappings":";;;;;;;;;AAQA,MAAa,iBAAiB;;CAE5B,aAAa;;CAEb,gBAAgB;;CAEhB,mBAAmB;;CAEnB,aAAa;;CAEb,eAAe;;CAGf,cAAc;;CAEd,qBAAqB;;CAErB,2BAA2B;CAC5B"}

package/dist/development/core/analytics/types.d.mts

@@ -1,54 +1,74 @@
+import { MoneyV2 } from "../../graphql/generated/storefront-api-types.mjs";
 import { AnalyticsEventName } from "./events.mjs";
 import { ShopifyScriptsShop } from "../shopify-scripts/types.mjs";
 
 //#region src/core/analytics/types.d.ts
+/** The shop ID that every analytics payload carries. */
 type ShopAnalyticsBase = Pick<ShopifyScriptsShop, "shopId">;
-/** Discriminant for the analytics channel a storefront is running under. */
+/** The sales channel that Shopify attributes a storefront's analytics to. */
 type ShopAnalyticsChannel = "hydrogen" | "headless";
 /**
- * Identifies the shop and channel for every analytics payload.
+ * Identifies the shop and sales channel in every analytics payload.
  *
- * The `"hydrogen"` variant carries the Hydrogen sales channel's `storefrontId`;
- * the `"headless"` variant omits it, because analytics for the Headless channel
- * isn't attributed to a specific storefront.
+ * The `hydrogen` channel carries the storefront ID. The `headless` channel
+ * omits the storefront ID.
+ *
+ * @publicDocs
  */
-type ShopAnalytics = (ShopAnalyticsBase & {
-  /** The storefront is served by the Hydrogen sales channel. */channel: "hydrogen"; /** ID of the Hydrogen storefront that analytics are attributed to. */
+type ShopAnalytics = HydrogenShopAnalytics | HeadlessShopAnalytics;
+/** The shop and storefront for a storefront on the Hydrogen sales channel. */
+interface HydrogenShopAnalytics extends ShopAnalyticsBase {
+  /** The Hydrogen sales channel serves the storefront. */
+  channel: "hydrogen";
+  /** The Hydrogen storefront's ID. */
   storefrontId: ShopifyScriptsShop["storefrontId"];
-}) | (ShopAnalyticsBase & {
-  /** The storefront uses the generic Headless sales channel. */channel: "headless";
+}
+/** The shop for a storefront on the Headless sales channel. */
+interface HeadlessShopAnalytics extends ShopAnalyticsBase {
+  /** The Headless sales channel serves the storefront. */
+  channel: "headless";
+  /** Leave the storefront ID out. The Headless sales channel has no storefront ID. */
   storefrontId?: never;
-});
+}
+/**
+ * The consent choices that a custom consent setup passes to
+ * `window.Shopify.customerPrivacy.setTrackingConsent()`.
+ *
+ * @publicDocs
+ */
 type ConsentPreferences = {
-  analytics: boolean;
-  marketing: boolean;
-  preferences: boolean;
+  /** Whether the customer allows analytics tracking. */analytics: boolean; /** Whether the customer allows marketing tracking. */
+  marketing: boolean; /** Whether the customer allows the storefront to remember their preferences. */
+  preferences: boolean; /** Whether the customer allows the sale or sharing of their data. */
   sale_of_data: boolean;
 };
 /**
- * Connects a consent provider once per analytics bus, after Shopify's consent API has loaded.
- * Use window.Shopify.customerPrivacy to synchronize consent.
- * Resolve only after the provider has a saved choice or the shopper interacts, and that
- * consent has been synchronized with Shopify. Hydrogen then checks consent and replays
- * allowed events. Rejection keeps delivery blocked. The integration stays active
- * across component unmounts.
+ * Connects a third-party consent provider to Shopify's Customer Privacy API. Hydrogen calls the
+ * function once, after the Customer Privacy API loads. Pass the provider's choice to
+ * `window.Shopify.customerPrivacy`, and resolve after Shopify receives the choice. Hydrogen then
+ * delivers the events that consent allows. When the promise rejects, Hydrogen logs the error,
+ * keeps events blocked, and doesn't call the function again.
+ */
+type ConsentSetup =
+/**
+ * @returns A promise that resolves after consent syncs with Shopify, or rejects to keep delivery blocked.
  */
-type ConsentSetup = () => Promise<void>;
+() => Promise<void>;
 /**
- * Chooses which Shopify consent script `ShopifyScripts` loads and when the
- * analytics bus releases events to destinations.
+ * Chooses which Shopify consent script loads and when the analytics bus
+ * releases events to destinations.
  *
- * - `"default-banner"` loads Shopify's hosted privacy banner. If the visitor
- *   must see the banner, destinations wait until they accept or decline;
- *   otherwise events are released as soon as the consent API loads.
- * - `"custom-banner"` loads only the Customer Privacy API and requires a
+ * - `default-banner` loads Shopify's hosted privacy banner. When the customer
+ *   must see the banner, destinations wait until the customer accepts or
+ *   declines. Otherwise, events release as soon as the consent API loads.
+ * - `custom-banner` loads only the Customer Privacy API and requires a
  *   `setup` callback that integrates a third-party consent provider.
- *   Events release once the `setup` callback resolves.
- * - `"no-banner"` (or omitted) loads only the Customer Privacy API and
- *   releases events once it loads.
+ *   Events release once the callback resolves.
+ * - `no-banner` loads only the Customer Privacy API and releases events
+ *   once the API loads. Omitting the mode has the same effect.
  *
- * In every mode, destinations only receive events while analytics processing is
- * allowed.
+ * In every mode, destinations receive events only while the Customer Privacy
+ * API allows analytics processing.
  */
 type ConsentConfig = {
   mode?: "no-banner";
@@ -60,28 +80,22 @@ type ConsentConfig = {
   mode: "custom-banner";
   setup: ConsentSetup;
 };
-/**
- * Lightweight cart line shape for analytics payloads.
- *
- * Mirrors the Storefront API `CartLine` fields needed for tracking without
- * depending on the cart store's `CartData` type, so the analytics bus stays
- * framework-agnostic.
- */
+/** A cart line in an analytics payload, with the Storefront API fields that cart tracking reads. */
 type AnalyticsCartLine = {
-  id: string;
-  quantity: number;
+  /** The cart line ID. */id: string; /** The number of units on the line. */
+  quantity: number; /** The variant on the line, with its product. */
   merchandise: {
-    id: string;
+    /** The variant ID. */id: string;
     /**
-     * Variant title (`"Default Title"` for single-variant products).
-     * `trackCartAnalytics` falls back to the product title only when the cart
-     * fragment doesn't select it.
+     * The variant title, which is `"Default Title"` for single-variant products.
+     * Cart tracking uses the product title when the cart fragment doesn't select
+     * the variant title.
      */
-    title: string; /** Per-unit price (`CartLine.cost.amountPerQuantity`). */
+    title: string; /** The price of one unit, from the cart line's cost per quantity. */
     price: {
       amount: string;
       currencyCode?: string;
-    };
+    }; /** The variant's SKU. Cart tracking sets `null` when the variant has no SKU. */
     sku?: string | null;
     product: {
       id: string;
@@ -93,17 +107,16 @@ type AnalyticsCartLine = {
   };
 };
 /**
- * Lightweight cart snapshot included in cart analytics payloads.
+ * A cart snapshot in cart analytics payloads.
  *
- * Accepts both `nodes` and `edges` connection shapes so the analytics layer
- * works regardless of which Storefront API query pattern the storefront uses.
+ * @publicDocs
  */
 type AnalyticsCart = {
-  id: string;
+  /** The cart ID. */id: string;
   /**
-   * `Cart.updatedAt` (ISO 8601), used to deduplicate cart events.
+   * The time of the cart's last update, as an ISO 8601 string.
    */
-  updatedAt: string;
+  updatedAt: string; /** The currency codes of the cart's subtotal and total. */
   cost?: {
     subtotalAmount?: {
       currencyCode?: string;
@@ -111,7 +124,7 @@ type AnalyticsCart = {
     totalAmount?: {
       currencyCode?: string;
     };
-  }; /** Cart lines in Storefront API connection format. */
+  }; /** The cart lines, as a `nodes` list or an `edges` list. Cart tracking fills `nodes`. */
   lines: {
     nodes?: AnalyticsCartLine[];
     edges?: Array<{
@@ -120,75 +133,125 @@ type AnalyticsCart = {
   };
   [key: string]: unknown;
 };
-/** Index signature that allows arbitrary extra keys on a payload. */
+/**
+ * Extra keys that a payload can carry. Cart tracking adds `eventTimestamp`, the publish time
+ * in milliseconds.
+ *
+ * @publicDocs
+ */
 type OtherData = {
   [key: string]: unknown;
 };
+/** The shop and custom data that every analytics event payload carries. */
 type BasePayload = {
-  shop?: ShopAnalytics | null;
+  /**
+   * The shop and sales channel. The bus fills in the configured shop when the payload omits
+   * the key, and normalizes the shop ID to a Shop GID.
+   */
+  shop?: ShopAnalytics | null; /** Custom values for destinations. Cart tracking copies the bus configuration's custom data here. */
   customData?: Record<string, unknown>;
 };
+/** The page URL that every view event payload carries. */
 type UrlPayload = {
-  url?: string;
+  /** The page URL. For view events, the bus fills in the current URL when the payload omits it. */url?: string;
 };
-/** Describes a single product for `product_viewed` payloads. */
+/**
+ * A product in a product view payload.
+ *
+ * @publicDocs
+ */
 type ProductPayload = {
-  id: string;
-  title: string; /** Decimal amount string for the selected variant (e.g. `"19.99"`). */
-  price: string;
-  vendor: string;
-  variantId: string;
-  variantTitle: string;
-  quantity: number;
-  sku?: string | null;
+  /** The product ID. */id: string; /** The product title. */
+  title: string; /** The selected variant's price. */
+  price: MoneyV2; /** The product vendor. */
+  vendor: string; /** The selected variant's ID. */
+  variantId: string; /** The selected variant's title. */
+  variantTitle: string; /** The selected quantity. */
+  quantity: number; /** The selected variant's SKU, or `null` when the variant has none. */
+  sku?: string | null; /** The product type. */
   productType?: string;
 };
+/** The products in a `product_viewed` event. */
 type ProductsPayload = {
-  products: Array<ProductPayload & OtherData>;
+  /** The products that the customer views. */products: Array<ProductPayload & OtherData>;
 };
+/** The collection in a `collection_viewed` event. */
 type CollectionPayload = {
-  collection: {
+  /** The ID and handle of the collection that the customer views. */collection: {
     id: string;
     handle: string;
   };
 };
+/** The search term and results in a `search_viewed` event. */
 type SearchPayload = {
-  searchTerm: string;
+  /** The customer's search query. */searchTerm: string; /** The search results, in any shape that your destinations read. */
   searchResults?: unknown;
 };
+/** The current cart in a cart event. */
 type CartPayload = {
-  cart: AnalyticsCart | null;
+  /** The current cart. */cart: AnalyticsCart | null;
 };
-type CartChangePayload = CartPayload & {
+/** The current cart and the cart before the change, in a cart update or cart line event. */
+interface CartChangePayload extends CartPayload {
+  /** The cart before the change, or `null` when cart tracking has no earlier snapshot. */
   prevCart: AnalyticsCart | null;
-};
+}
+/** The cart line before and after the change, in a `product_added_to_cart` or `product_removed_from_cart` event. */
 type CartLinePayload = {
-  prevLine?: AnalyticsCartLine;
+  /** The line before the change. */prevLine?: AnalyticsCartLine; /** The line after the change. */
   currentLine?: AnalyticsCartLine;
 };
-/** Payload for `page_viewed` events. */
+/**
+ * The data for a `page_viewed` event. The payload has only the fields that every view event shares.
+ *
+ * @publicDocs
+ */
 type PageViewPayload = UrlPayload & BasePayload;
-/** Payload for `product_viewed` events. */
+/**
+ * The data for a `product_viewed` event. The payload lists the products that the customer views.
+ *
+ * @publicDocs
+ */
 type ProductViewPayload = ProductsPayload & UrlPayload & BasePayload;
-/** Payload for `collection_viewed` events. */
+/**
+ * The data for a `collection_viewed` event. The payload has the ID and handle of the collection that the customer views.
+ *
+ * @publicDocs
+ */
 type CollectionViewPayload = CollectionPayload & UrlPayload & BasePayload;
-/** Payload for `cart_viewed` events. */
+/**
+ * The data for a `cart_viewed` event. The payload has the current cart.
+ *
+ * @publicDocs
+ */
 type CartViewPayload = CartPayload & UrlPayload & BasePayload;
-/** Payload for `search_viewed` events. */
+/**
+ * The data for a `search_viewed` event. The payload has the customer's search term and optional search results in any shape that your destinations read.
+ *
+ * @publicDocs
+ */
 type SearchViewPayload = SearchPayload & UrlPayload & BasePayload;
-/** Payload for `cart_updated` events. `prevCart` is `null` when there was no earlier snapshot. */
+/**
+ * The data for a `cart_updated` event. Cart tracking sends the current cart, the cart before the change, the shop, the custom data from the bus configuration, and the publish time. The previous cart is `null` when cart tracking has no earlier snapshot.
+ *
+ * @publicDocs
+ */
 type CartUpdatePayload = CartChangePayload & BasePayload & OtherData;
 /**
- * Payload for `product_added_to_cart` and `product_removed_from_cart` events.
- * New lines have only `currentLine`, removed lines have only `prevLine`, and
- * quantity changes have both.
+ * The data for `product_added_to_cart` and `product_removed_from_cart` events. The payload has the same fields as a cart update, plus the line before and after the change.
+ * New lines have only the current line, removed lines have only the previous
+ * line, and quantity changes have both.
+ *
+ * @publicDocs
  */
 type CartLineUpdatePayload = CartLinePayload & CartChangePayload & BasePayload & OtherData;
 /**
  * Maps each analytics event name to its payload type.
  *
- * TypeScript uses this to infer the correct payload when you call
- * `publish()` or a destination's `subscribe()` with a specific event name.
+ * TypeScript uses the map to infer the payload when you publish an event or
+ * subscribe a destination to a specific event name.
+ *
+ * @publicDocs
  */
 interface AnalyticsEventMap {
   page_viewed: PageViewPayload;
@@ -200,78 +263,104 @@ interface AnalyticsEventMap {
   product_added_to_cart: CartLineUpdatePayload;
   product_removed_from_cart: CartLineUpdatePayload;
 }
-/** Resolves the payload type for a supported analytics event name. */
+/**
+ * Resolves the payload type for a supported analytics event name.
+ *
+ * @publicDocs
+ */
 type PayloadFor<E extends AnalyticsEventName> = AnalyticsEventMap[E];
+/** The payload argument for publishing an event. It's optional when every payload field is optional. */
 type PublishPayloadArgs<E extends AnalyticsEventName> = {} extends PayloadFor<E> ? [payload?: PayloadFor<E>] : [payload: PayloadFor<E>];
 /**
- * Analytics bus configuration, built by `ShopifyScripts` from its `shop`,
- * `consent`, and `analytics` options.
+ * The analytics bus configuration. Hydrogen builds it from the shop, consent, and analytics
+ * options of the Shopify script tags.
+ *
+ * @publicDocs
  */
 type StorefrontAnalyticsConfig = {
-  /** Shop identity and channel for analytics payloads. */shop: ShopAnalytics | null; /** Serializable consent settings. The provider setup callback stays in the client bundle. */
+  /** The shop and sales channel for analytics payloads. */shop: ShopAnalytics | null; /** The consent mode, without the setup callback. */
   consent: Pick<ConsentConfig, "mode">;
   /**
-   * Extra key-value pairs accessible to destinations via `getConfig().customData`.
-   * Not added to events you publish.
+   * Extra key-value pairs that destinations read from the bus configuration. Cart tracking
+   * copies them into cart event payloads. The bus doesn't add them to events that you publish.
    */
   customData?: Record<string, unknown>;
 };
 /**
- * Visitor identifiers from Shopify's Customer Privacy API, used to correlate
- * analytics events. See `getTrackingValues` for when they are empty.
+ * Visitor identifiers from Shopify's Customer Privacy API. Destinations use them to correlate
+ * analytics events. Both identifiers are empty strings when the values are unavailable.
+ *
+ * @publicDocs
  */
 type AnalyticsTrackingValues = {
-  /** Long-lived browser identifier; persists across visits. */uniqueToken: string; /** Session identifier (30-minute rolling expiry). */
+  /** The browser's unique visitor identifier. */uniqueToken: string; /** The session identifier. */
   visitToken: string;
 };
-/** Context provided to destination callbacks alongside each event payload. */
+/**
+ * The context that a destination callback receives with each event payload.
+ *
+ * @publicDocs
+ */
 type StorefrontAnalyticsDestinationEventContext = {
   /**
-   * Reads current tokens from the consent API. Returns empty strings when tokens are
-   * unavailable or analytics tracking is not currently allowed.
+   * Returns the current visitor tokens from the Customer Privacy API. The function checks consent
+   * on every call, and returns empty strings when the tokens are unavailable or consent blocks tracking.
    */
   getTrackingValues: () => AnalyticsTrackingValues;
 };
-/** Context passed into a destination's `setup()` function. */
+/**
+ * The context that a destination's setup function receives.
+ *
+ * @publicDocs
+ */
 type StorefrontAnalyticsDestinationSetupContext = {
-  /** Subscribe to an analytics event. Returns an unsubscribe function. */subscribe: <E extends AnalyticsEventName>(event: E, callback: (payload: PayloadFor<E>, context: StorefrontAnalyticsDestinationEventContext) => void) => () => void; /** Returns the current analytics bus configuration. */
+  /**
+   * Subscribes a callback to an analytics event and returns a function that unsubscribes it.
+   * The bus warns and ignores unsupported event names.
+   */
+  subscribe: <E extends AnalyticsEventName>(event: E, callback: (payload: PayloadFor<E>, context: StorefrontAnalyticsDestinationEventContext) => void) => () => void; /** Returns the current analytics bus configuration. */
   getConfig: () => StorefrontAnalyticsConfig;
 };
 /**
- * A consent-gated analytics integration that receives events after consent is granted.
+ * An analytics integration that receives events once consent allows tracking.
+ *
+ * Subscribe to events in the setup function. After consent allows tracking, the destination
+ * receives the earlier events from the buffer and then new events. Return a cleanup function
+ * from setup to undo side effects when you remove the destination.
  *
- * Destinations subscribe to events during `setup()` and receive live delivery
- * plus replayed buffered events once tracking is allowed. Return a cleanup
- * function from `setup()` to tear down side effects when the destination is
- * removed via the function returned by `addDestination()`. The bus itself lives
- * for the page's lifetime.
+ * @publicDocs
  */
 type StorefrontAnalyticsDestination = {
-  /** Unique name for this destination — duplicates are rejected with a warning. */name: string;
+  /** A unique name. The bus warns and ignores a destination that reuses the name of an active destination. */name: string;
   /**
-   * Runs immediately when the destination is added, before consent is known, so
-   * don't load third-party scripts or set cookies here. Subscribe via the context.
-   * May be async: buffered events replay after it resolves (once tracking is
-   * allowed). If it throws or rejects, the destination is removed.
+   * Runs as soon as you add the destination, which can happen before the customer consents.
+   * Subscribe to events through the context. Don't load third-party scripts or set cookies in
+   * setup. The function can be async. The bus replays buffered events after setup resolves and
+   * consent allows tracking. When setup throws or rejects, the bus logs the error and removes
+   * the destination.
    */
   setup: (context: StorefrontAnalyticsDestinationSetupContext) => void | (() => void) | Promise<void | (() => void)>;
 };
 /**
- * The framework-agnostic analytics event bus that `ShopifyScripts` exposes on
- * `window.Shopify.analytics`.
+ * The analytics event bus that the Shopify script tags create at `window.Shopify.analytics`.
+ *
+ * Storefronts publish events such as page views, product views, and cart changes. Tracking
+ * integrations register as destinations and receive events once consent allows tracking.
  *
- * Storefronts publish events (page views, product views, cart changes) via
- * `publish()`. Consent-gated tracking integrations register through
- * `addDestination()` and receive buffered events once consent is granted.
+ * @publicDocs
  */
 type StorefrontAnalytics = {
   /**
-   * Emits an event to destinations while tracking is allowed. Otherwise the
-   * event goes into a bounded replay buffer. Fills in `shop` and (for view
-   * events) `url` when omitted.
+   * Publishes an event. The bus delivers the event to destinations while consent allows
+   * tracking, and records the event in a replay buffer for destinations that you add later.
+   * The buffer keeps the latest 500 events. When consent completes without allowing tracking,
+   * the bus clears the buffer and stops recording until consent allows tracking.
+   *
+   * The bus fills in the shop when the payload omits it, and the current URL for view events.
+   * The bus warns and drops events with unsupported names.
    */
-  publish: <E extends AnalyticsEventName>(event: E, ...payload: PublishPayloadArgs<E>) => void; /** Register a consent-gated destination integration. Returns a removal function. */
-  addDestination: (destination: StorefrontAnalyticsDestination) => () => void; /** Returns the bus configuration; `shop.shopId` is normalized to a Shop GID. */
+  publish: <E extends AnalyticsEventName>(event: E, ...payload: PublishPayloadArgs<E>) => void; /** Adds a destination and returns a function that removes it. Removing a destination runs its cleanup function. */
+  addDestination: (destination: StorefrontAnalyticsDestination) => () => void; /** Returns the bus configuration, with the shop ID normalized to a Shop GID. */
   getConfig: () => StorefrontAnalyticsConfig;
 };
 //#endregion