@occluze/tether 0.6.8 → 0.7.0

package/src/{analytics-shopify.js → analytics-shopify.ts}

@@ -3,58 +3,75 @@
  * (`window.Shopify.analytics`) and loads Shopify's consent script and shopify.js, which build and send the events.
  * Nothing is delivered before the Customer Privacy API allows analytics.
  */
-import { cfg, log, reportError } from './config.js';
-import { gql } from './client.js';
-
-/** @typedef {Record<string, unknown>} EventPayload */
-/** @typedef {{ uniqueToken: string, visitToken: string }} TrackingValues */
-/** @typedef {{ getTrackingValues: () => TrackingValues }} DestinationContext */
-/** @typedef {(payload: EventPayload, context: DestinationContext) => void} Subscriber */
-/** @typedef {(event: string, subscriber: Subscriber) => () => void} Subscribe */
-/** @typedef {{ shop: { shopId: string, channel: 'headless' }, consent: { mode: string } }} BusConfig */
-/**
- * @typedef {object} DestinationSpec What shopify.js registers.
- * @property {string} name
- * @property {(api: { subscribe: Subscribe, getConfig: () => BusConfig }) => unknown} [setup]
- */
-/**
- * @typedef {object} AnalyticsBus Hydrogen's `window.Shopify.analytics`.
- * @property {() => BusConfig} getConfig
- * @property {(event: string, payload?: EventPayload) => void} publish
- * @property {(destination: DestinationSpec) => () => void} addDestination
- */
+import { cfg, log, reportError } from './config.ts';
+import { gql, shaped } from './client.ts';
+import type { AnalyticsConfig } from './config.ts';
 
-/**
- * The parts of Shopify's Customer Privacy API (`window.Shopify.customerPrivacy`) that decide tracking.
- *
- * @typedef {object} CustomerPrivacy
- * @property {string} [consentStatus]
- * @property {() => { analytics?: string } | undefined} [currentVisitorConsent]
- * @property {() => boolean} [analyticsProcessingAllowed]
- * @property {{ uniqueToken?: TokenReader, visitToken?: TokenReader }} [__internal]
- * @property {object} [config]
- */
-/** @typedef {(options: { generateFallback: boolean, tag: string }) => string} TokenReader */
-/**
- * `window.Shopify`, which Shopify's scripts read and extend.
- *
- * @typedef {object} ShopifyGlobal
- * @property {AnalyticsBus} [analytics]
- * @property {CustomerPrivacy} [customerPrivacy]
- * @property {string} [country]
- * @property {string} [locale]
- * @property {string} [shop]
- * @property {object} [routes]
- */
+export type EventPayload = Record<string, unknown>;
 
-/** @typedef {{ event: string, payload: EventPayload }} BufferedEvent */
-/**
- * @typedef {object} Destination
- * @property {string} name
- * @property {number} next The index of the next buffered event it gets.
- * @property {Map<string, Set<Subscriber>>} subscribers
- * @property {DestinationContext} context
- */
+interface TrackingValues {
+  uniqueToken: string;
+  visitToken: string;
+}
+
+interface DestinationContext {
+  getTrackingValues: () => TrackingValues;
+}
+
+type Subscriber = (payload: EventPayload, context: DestinationContext) => void;
+type Subscribe = (event: string, subscriber: Subscriber) => () => void;
+
+interface BusConfig {
+  shop: { shopId: string; channel: 'headless' };
+  consent: { mode: string };
+}
+
+/** What shopify.js registers. */
+interface DestinationSpec {
+  name: string;
+  setup?: (api: { subscribe: Subscribe; getConfig: () => BusConfig }) => unknown;
+}
+
+/** Hydrogen's `window.Shopify.analytics`. */
+export interface AnalyticsBus {
+  getConfig: () => BusConfig;
+  publish: (event: string, payload?: EventPayload) => void;
+  addDestination: (destination: DestinationSpec) => () => void;
+}
+
+type TokenReader = (options: { generateFallback: boolean; tag: string }) => string;
+
+/** The parts of Shopify's Customer Privacy API (`window.Shopify.customerPrivacy`) that decide tracking. */
+interface CustomerPrivacy {
+  consentStatus?: string;
+  currentVisitorConsent?: () => { analytics?: string } | undefined;
+  analyticsProcessingAllowed?: () => boolean;
+  __internal?: { uniqueToken?: TokenReader; visitToken?: TokenReader };
+  config?: object;
+}
+
+/** `window.Shopify`, which Shopify's scripts read and extend. */
+interface ShopifyGlobal {
+  analytics?: AnalyticsBus;
+  customerPrivacy?: CustomerPrivacy;
+  country?: string;
+  locale?: string;
+  shop?: string;
+  routes?: object;
+}
+
+interface BufferedEvent {
+  event: string;
+  payload: EventPayload;
+}
+
+interface Destination {
+  name: string;
+  /** The index of the next buffered event it gets. */
+  next: number;
+  subscribers: Map<string, Set<Subscriber>>;
+  context: DestinationContext;
+}
 
 /** Events kept for destinations that register late (shopify.js loads after the first page view). */
 const BUFFER_SIZE = 500;
@@ -64,15 +81,13 @@ const CONSENT_SCRIPTS = {
 };
 const ANALYTICS_SCRIPT = 'https://cdn.shopify.com/storefront/analytics/shopify.js';
 
-/** @returns {ShopifyGlobal | undefined} `window.Shopify`, whose shape Shopify's scripts define. */
-function shopifyGlobal() {
-  /** @type {unknown} */
-  const shopify = Reflect.get(window, 'Shopify');
-  return /** @type {ShopifyGlobal | undefined} */ (shopify);
-}
+/** The page, where Shopify's scripts keep `window.Shopify` in the shape they define. */
+const page = (): Window & { Shopify?: ShopifyGlobal } => window;
 
-/** @returns {{ consent?: string, proxy?: string }} The `analytics.shopify` options; `true` sets none. */
-function shopifyOptions() {
+const shopifyGlobal = (): ShopifyGlobal | undefined => page().Shopify;
+
+/** The `analytics.shopify` options; `true` sets none. */
+function shopifyOptions(): Exclude<NonNullable<AnalyticsConfig['shopify']>, boolean> {
   const shopify = cfg.analytics?.shopify;
   return typeof shopify === 'object' ? shopify : {};
 }
@@ -80,10 +95,8 @@ function shopifyOptions() {
 /**
  * Shopify's privacy API can throw while its script is still setting up. An answer it can't give counts as "not
  * allowed", so nothing is sent without consent; the next consent event asks again.
- *
- * @returns {boolean}
  */
-function trackingAllowed() {
+function trackingAllowed(): boolean {
   try {
     const privacy = shopifyGlobal()?.customerPrivacy;
     return (
@@ -96,11 +109,8 @@ function trackingAllowed() {
   }
 }
 
-/**
- * @param {string} name The destination's name, Hydrogen tags its tokens with it.
- * @returns {DestinationContext}
- */
-function destinationContext(name) {
+/** @param name The destination's name, Hydrogen tags its tokens with it. */
+function destinationContext(name: string): DestinationContext {
   const tag = `hydrogen:${name}`;
   return {
     getTrackingValues: () => {
@@ -113,28 +123,20 @@ function destinationContext(name) {
   };
 }
 
-/**
- * @param {Destination} destination
- * @returns {Subscribe}
- */
-const subscriberOf = (destination) => (event, subscriber) => {
-  const subscribers = destination.subscribers.get(event) ?? new Set();
-  destination.subscribers.set(event, subscribers);
-  subscribers.add(subscriber);
-  return () => destination.subscribers.get(event)?.delete(subscriber);
-};
+const subscriberOf =
+  (destination: Destination): Subscribe =>
+  (event, subscriber) => {
+    const subscribers = destination.subscribers.get(event) ?? new Set();
+    destination.subscribers.set(event, subscribers);
+    subscribers.add(subscriber);
+    return () => destination.subscribers.get(event)?.delete(subscriber);
+  };
 
-/**
- * @param {string} shopId
- * @returns {AnalyticsBus} A bus that buffers events and delivers them to each destination once consent allows.
- */
-function createBus(shopId) {
-  /** @type {Destination[]} */
-  const destinations = [];
-  /** @type {BufferedEvent[]} */
-  const buffer = [];
-  /** @type {BusConfig} */
-  const config = {
+/** A bus that buffers events and delivers them to each destination once consent allows. */
+function createBus(shopId: string): AnalyticsBus {
+  const destinations: Destination[] = [];
+  const buffer: BufferedEvent[] = [];
+  const config: BusConfig = {
     shop: { shopId, channel: 'headless' },
     consent: { mode: shopifyOptions().consent || 'no-banner' },
   };
@@ -147,8 +149,7 @@ function createBus(shopId) {
       }
     }
   };
-  /** @type {AnalyticsBus} */
-  const bus = {
+  const bus: AnalyticsBus = {
     getConfig: () => config,
     publish(event, payload = {}) {
       buffer.push({ event, payload: { shop: config.shop, url: window.location.href, ...payload } });
@@ -159,14 +160,18 @@ function createBus(shopId) {
       deliver();
     },
     addDestination(spec) {
-      /** @type {Destination} */
-      const destination = { name: spec.name, next: 0, subscribers: new Map(), context: destinationContext(spec.name) };
+      const destination: Destination = {
+        name: spec.name,
+        next: 0,
+        subscribers: new Map(),
+        context: destinationContext(spec.name),
+      };
       Promise.resolve(spec.setup?.({ subscribe: subscriberOf(destination), getConfig: bus.getConfig }))
         .then(() => {
           destinations.push(destination);
           deliver();
         })
-        .catch((/** @type {unknown} */ error) => {
+        .catch((error: unknown) => {
           reportError(error, `analytics ${spec.name}`);
         });
       return () => {
@@ -180,11 +185,7 @@ function createBus(shopId) {
   return bus;
 }
 
-/**
- * @param {Destination} destination
- * @param {BufferedEvent} buffered
- */
-function deliverTo(destination, { event, payload }) {
+function deliverTo(destination: Destination, { event, payload }: BufferedEvent): void {
   destination.subscribers.get(event)?.forEach((subscriber) => {
     try {
       subscriber(payload, destination.context);
@@ -194,8 +195,7 @@ function deliverTo(destination, { event, payload }) {
   });
 }
 
-/** @param {string} src */
-function loadScript(src) {
+function loadScript(src: string): void {
   const script = document.createElement('script');
   script.src = src;
   script.async = true;
@@ -205,19 +205,24 @@ function loadScript(src) {
 /**
  * Sets up `window.Shopify` for Shopify's scripts and loads them.
  *
- * @param {() => boolean} isProductPage Asked by Shopify's script for the page template.
- * @returns {Promise<AnalyticsBus>} The bus, the page's own when a theme already set one up.
+ * @param isProductPage Asked by Shopify's script for the page template.
+ * @returns The bus, the page's own when a theme already set one up.
  */
-export async function startShopifyAnalytics(isProductPage) {
+export async function startShopifyAnalytics(isProductPage: () => boolean): Promise<AnalyticsBus> {
   const existing = shopifyGlobal();
   if (existing?.analytics) return existing.analytics;
-  /** @type {{ shop: { id: string } }} */
-  const data = await gql('query TetherShopId { shop { id } }', {}, { context: false });
+  const data = await gql(
+    'query TetherShopId { shop { id } }',
+    {},
+    shaped<{ shop: { id: string } }>({ shop: { id: 'string' } }),
+    { context: false },
+  );
   const shopify = shopifyGlobal() ?? {};
-  Reflect.set(window, 'Shopify', shopify);
-  shopify.country = (cfg.country || 'US').toUpperCase();
+  page().Shopify = shopify;
+  shopify.country = cfg.country ?? 'US';
   // Shopify's script requires a language, not a full locale.
-  shopify.locale = (cfg.locale || 'en').split('-')[0]?.toLowerCase() ?? 'en';
+  const [language = 'en'] = (cfg.locale || 'en').split('-');
+  shopify.locale = language.toLowerCase();
   shopify.shop = cfg.domain;
   shopify.routes = {
     root: '/',

package/src/analytics.ts

@@ -0,0 +1,315 @@
+/**
+ * Analytics, as an optional part (loaded when config.analytics is set).
+ *
+ *   analytics: {
+ *     dataLayer: true,        // GA4 / Google Tag Manager ecommerce events (window.dataLayer)
+ *     shopify: true,          // Shopify's own analytics (experimental, see docs/analytics.md)
+ *     onEvent(name, data) {}, // any other tool: Meta, TikTok, Plausible
+ *   }
+ *
+ * Events: view_item (the page's product), view_item_list (lists), add_to_cart / remove_from_cart (from the cart's
+ * changes, so quick +/- and JS calls count too), view_cart (cart opened), begin_checkout, search (search as you type).
+ * Purchases happen on Shopify's checkout: use Shopify's Google & YouTube app or a checkout pixel for those.
+ * Shopify's analytics are set up in analytics-shopify.ts.
+ */
+import { cfg, reportError } from './config.ts';
+import { ANALYTICS_EVENTS, isOwnEvent, sel } from './dom.ts';
+import { Cart } from './cart.ts';
+import { scopes } from './product.ts';
+import { startShopifyAnalytics } from './analytics-shopify.ts';
+import type { Money } from './shopify-values.ts';
+import type { Product, ProductVariant } from './fragments.ts';
+import type { AnalyticsBus, EventPayload } from './analytics-shopify.ts';
+import type { ProductScope } from './product.ts';
+import type { AnalyticsEventName, TetherEvents } from './markup.ts';
+
+/** The fields of the cart's product (`fragment TetherCart`) this module reads. */
+interface LineProduct {
+  id: string;
+  title: string;
+  handle: string;
+  vendor: string;
+}
+
+interface LineVariant {
+  id: string;
+  title: string;
+  sku: string | null;
+  price: Money;
+  product: LineProduct;
+}
+
+interface CartLine {
+  id: string;
+  quantity: number;
+  merchandise: LineVariant;
+}
+
+/** The fields of the cart (`fragment TetherCart`) this module reads. */
+interface AnalyticsCart {
+  lines: { nodes: CartLine[] };
+  cost: { totalAmount: Money };
+  discountCodes: { code: string; applicable: boolean }[];
+}
+
+/** What a GA4 item is built from: a product, or a cart line's product. */
+interface ItemProduct {
+  id: string;
+  title: string;
+  vendor?: string;
+  productType?: string;
+  priceRange?: { minVariantPrice: Money };
+}
+
+type ItemVariant = Pick<ProductVariant, 'id' | 'title' | 'sku' | 'price'>;
+
+/** A GA4 ecommerce item. */
+interface AnalyticsItem {
+  item_id: string;
+  item_name: string;
+  item_variant: string | undefined;
+  item_brand: string | undefined;
+  item_category: string | undefined;
+  price: number;
+  quantity: number;
+  index?: number;
+}
+
+/** Shopify's title for the one variant of a product without options. */
+const DEFAULT_VARIANT_TITLE = 'Default Title';
+const CENTS_PER_UNIT = 100;
+/** GA4 drops an event with more items than this. */
+const MAX_LIST_ITEMS = 200;
+
+const amountOf = (money: Money | null | undefined): number => (money ? parseFloat(money.amount) : 0);
+
+/** The numeric part of a gid. */
+const numericId = (gid: string | null | undefined): string => (gid ?? '').split('/').pop() ?? '';
+
+/** @param index The position in a list. */
+function itemFromVariant(
+  product: ItemProduct,
+  variant: ItemVariant | null | undefined,
+  quantity = 1,
+  index?: number,
+): AnalyticsItem {
+  const item: AnalyticsItem = {
+    item_id: variant?.sku || numericId(variant?.id) || numericId(product.id),
+    item_name: product.title,
+    item_variant: variant?.title === DEFAULT_VARIANT_TITLE ? undefined : variant?.title,
+    item_brand: product.vendor || undefined,
+    item_category: product.productType || undefined,
+    price: amountOf(variant?.price ?? product.priceRange?.minVariantPrice),
+    quantity,
+  };
+  if (index != null) item.index = index;
+  return item;
+}
+
+const itemFromLine = (line: CartLine, quantity = line.quantity) =>
+  itemFromVariant(line.merchandise.product, line.merchandise, quantity);
+
+/** The items' total, rounded to cents. */
+function totalValue(items: AnalyticsItem[]): number {
+  const total = items.reduce((sum, item) => sum + item.price * (item.quantity || 1), 0);
+  return Math.round(total * CENTS_PER_UNIT) / CENTS_PER_UNIT;
+}
+
+const productPayload = (product: Product, variant: ItemVariant, quantity = 1) => ({
+  id: product.id,
+  title: product.title,
+  price: variant.price,
+  vendor: product.vendor || '',
+  variantId: variant.id,
+  variantTitle: variant.title,
+  quantity,
+  sku: variant.sku || undefined,
+  productType: product.productType || undefined,
+});
+
+const linePayload = (line: CartLine) => ({
+  id: line.id,
+  quantity: line.quantity,
+  merchandise: {
+    id: line.merchandise.id,
+    title: line.merchandise.title,
+    price: line.merchandise.price,
+    sku: line.merchandise.sku,
+    product: {
+      id: line.merchandise.product.id,
+      title: line.merchandise.product.title,
+      vendor: line.merchandise.product.vendor || '',
+      handle: line.merchandise.product.handle,
+    },
+  },
+});
+
+/** The GA4 / GTM data layer, created when the page has none. */
+function dataLayer(): unknown[] {
+  const { dataLayer: option } = cfg.analytics ?? {};
+  const name = typeof option === 'string' ? option : 'dataLayer';
+  const existing: unknown = Reflect.get(window, name);
+  if (Array.isArray(existing)) return existing;
+  const created: unknown[] = [];
+  Reflect.set(window, name, created);
+  return created;
+}
+
+function pushToDataLayer(event: string, ecommerce: Record<string, unknown> | undefined): void {
+  const layer = dataLayer();
+  if (!ecommerce) {
+    layer.push({ event });
+    return;
+  }
+  // Google asks for the previous ecommerce object to be cleared first.
+  layer.push({ ecommerce: null });
+  layer.push({ event, ecommerce });
+}
+
+let bus: AnalyticsBus | null = null;
+/** Variant id to line, to turn cart changes into add and remove events. */
+let lastLines: Map<string, CartLine> | null = null;
+let lastCart: AnalyticsCart | null = null;
+/** Product roots whose view_item was sent on this page. */
+let viewed = new WeakSet<Element>();
+
+/** @param name The GA4 event. */
+function send(name: string, data: Record<string, unknown>, shopifyEvent?: string, shopifyPayload?: EventPayload): void {
+  if (cfg.analytics?.dataLayer) pushToDataLayer(name, data);
+  if (bus && shopifyEvent) bus.publish(shopifyEvent, shopifyPayload);
+  try {
+    cfg.analytics?.onEvent?.(name, data);
+  } catch (error) {
+    reportError(error, 'analytics onEvent');
+  }
+}
+
+/** The scope of the page's own product: a product root outside every list. */
+function mainProduct(): ProductScope | null {
+  const el = document.querySelector(sel('product'));
+  if (!el || el.closest(`${sel('collection')},${sel('products')},${sel('recommendations')}`)) return null;
+  return scopes.get(el) ?? null;
+}
+
+function onProductReady({ product, scope }: TetherEvents['product-ready']): void {
+  if (viewed.has(scope.root) || mainProduct() !== scope) return;
+  viewed.add(scope.root);
+  const variant = scope.variant ?? product.variants.nodes[0];
+  const items = [itemFromVariant(product, variant)];
+  const products = variant ? [productPayload(product, variant)] : [];
+  send('view_item', { currency: variant?.price.currencyCode, value: totalValue(items), items }, 'product_viewed', {
+    products,
+  });
+}
+
+function onListReady({ products, collection }: TetherEvents['list-ready']): void {
+  const items = products
+    .slice(0, MAX_LIST_ITEMS)
+    .map((product, index) => itemFromVariant(product, product.variants.nodes[0], 1, index));
+  const list = { item_list_id: collection?.handle || 'products', item_list_name: collection?.title || 'Products' };
+  if (!collection) {
+    send('view_item_list', { ...list, items });
+    return;
+  }
+  send('view_item_list', { ...list, items }, 'collection_viewed', {
+    collection: { id: collection.id, handle: collection.handle },
+  });
+}
+
+function sendCartChanges(cart: AnalyticsCart | null, now: Map<string, CartLine>, before: Map<string, CartLine>): void {
+  const currency = cart?.cost.totalAmount.currencyCode;
+  now.forEach((line, variantId) => {
+    const previous = before.get(variantId);
+    const added = line.quantity - (previous?.quantity ?? 0);
+    if (added <= 0) return;
+    const items = [itemFromLine(line, added)];
+    send('add_to_cart', { currency, value: totalValue(items), items }, 'product_added_to_cart', {
+      cart,
+      prevCart: lastCart,
+      currentLine: linePayload(line),
+      prevLine: previous ? linePayload(previous) : undefined,
+    });
+  });
+  before.forEach((line, variantId) => {
+    const removed = line.quantity - (now.get(variantId)?.quantity ?? 0);
+    if (removed <= 0) return;
+    const items = [itemFromLine(line, removed)];
+    send('remove_from_cart', { currency, value: totalValue(items), items });
+  });
+}
+
+function onCartUpdated({ cart, reason }: TetherEvents['cart-updated']): void {
+  const now = new Map((cart?.lines.nodes ?? []).map((line) => [line.merchandise.id, line]));
+  // Loading the saved cart and showing a pending change aren't changes the visitor made.
+  if (lastLines && reason !== 'load' && reason !== 'pending') sendCartChanges(cart, now, lastLines);
+  lastLines = now;
+  lastCart = cart;
+}
+
+function onCartOpened(): void {
+  const items = Cart.lines.map((line) => itemFromLine(line));
+  send('view_cart', { currency: Cart.state?.cost.totalAmount.currencyCode, value: totalValue(items), items });
+}
+
+function onCheckout({ cart }: TetherEvents['checkout']): void {
+  if (!cart) return;
+  const items = cart.lines.nodes.map((line) => itemFromLine(line));
+  const coupons = cart.discountCodes.filter((discount) => discount.applicable).map((discount) => discount.code);
+  send('begin_checkout', {
+    currency: cart.cost.totalAmount.currencyCode,
+    value: totalValue(items),
+    coupon: coupons.join(',') || undefined,
+    items,
+  });
+}
+
+/** What each event `ANALYTICS_EVENTS` names sends: one entry per name, so the list and this table can't diverge. */
+const REPORTERS: { [Name in AnalyticsEventName]: (detail: TetherEvents[Name]) => void } = {
+  'product-ready': onProductReady,
+  'list-ready': onListReady,
+  'cart-updated': onCartUpdated,
+  'cart-toggled': ({ open }) => {
+    if (open) onCartOpened();
+  },
+  checkout: onCheckout,
+  search: ({ term }) => {
+    if (term) send('search', { search_term: term }, 'search_viewed', { searchTerm: term });
+  },
+};
+
+/** @param event The event Tether created as `name`. */
+function report<Name extends AnalyticsEventName>(event: CustomEvent<TetherEvents[Name]>, name: Name): void {
+  REPORTERS[name](event.detail);
+}
+
+/**
+ * Turns one buffered event into analytics events: a Tether event from `ANALYTICS_EVENTS`, or Astro's `astro:page-load`
+ * for a client-side navigation, which starts a new page view. Only events Tether created count (`isOwnEvent`): a
+ * look-alike another script dispatches, whatever its detail, sends nothing.
+ */
+function handle(event: Event): void {
+  if (event.type === 'astro:page-load') {
+    viewed = new WeakSet();
+    bus?.publish('page_viewed', {});
+    return;
+  }
+  ANALYTICS_EVENTS.forEach((name) => {
+    if (isOwnEvent(event, name)) report(event, name);
+  });
+}
+
+/** Called by the core with the events it buffered while this part loaded; the queue then handles events as they come. */
+export async function startAnalytics(queue: Event[]): Promise<void> {
+  if (cfg.analytics?.shopify) {
+    bus = await startShopifyAnalytics(() => mainProduct() != null).catch((error: unknown) => {
+      reportError(error, 'shopify analytics');
+      return null;
+    });
+  }
+  bus?.publish('page_viewed', {});
+  queue.splice(0).forEach(handle);
+  queue.push = (...events) => {
+    events.forEach(handle);
+    return queue.length;
+  };
+}