@occluze/tether 0.6.7 → 0.6.8

package/src/analytics.js

@@ -4,229 +4,349 @@
  *   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, …
+ *     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 analytics: Tether sets up the same event bus Hydrogen uses (window.Shopify.analytics) and
- * loads Shopify's consent script and shopify.js, which build and send the events. Nothing is sent
- * before the Customer Privacy API allows analytics.
+ * 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.js.
  */
-import { cfg, log, reportError } from './config.js';
-import { gql } from './client.js';
+import { cfg, reportError } from './config.js';
 import { sel } from './dom.js';
 import { Cart } from './cart.js';
+import { startShopifyAnalytics } from './analytics-shopify.js';
+/** @import { Money } from './shopify-values.js' */
+/** @import { Product, ProductVariant } from './fragments.js' */
+/** @import { AnalyticsBus, EventPayload } from './analytics-shopify.js' */
+
+/**
+ * cart.js has no types yet; these are the fields of its cart (`fragment TetherCart`) this module reads.
+ *
+ * @typedef {object} LineProduct
+ * @property {string} id
+ * @property {string} title
+ * @property {string} handle
+ * @property {string} vendor
+ * @typedef {{ id: string, title: string, sku: string | null, price: Money, product: LineProduct }} LineVariant
+ * @typedef {{ id: string, quantity: number, merchandise: LineVariant }} CartLine
+ * @typedef {object} AnalyticsCart
+ * @property {{ nodes: CartLine[] }} lines
+ * @property {{ totalAmount: Money }} cost
+ * @property {{ code: string, applicable: boolean }[]} discountCodes
+ */
+
+/**
+ * @typedef {object} ItemProduct What a GA4 item is built from: a product, or a cart line's product.
+ * @property {string} id
+ * @property {string} title
+ * @property {string} [vendor]
+ * @property {string} [productType]
+ * @property {{ minVariantPrice: Money }} [priceRange]
+ */
+/** @typedef {Pick<ProductVariant, 'id' | 'title' | 'sku' | 'price'>} ItemVariant */
+/**
+ * @typedef {object} AnalyticsItem A GA4 ecommerce item.
+ * @property {string} item_id
+ * @property {string} item_name
+ * @property {string | undefined} item_variant
+ * @property {string | undefined} item_brand
+ * @property {string | undefined} item_category
+ * @property {number} price
+ * @property {number} quantity
+ * @property {number} [index]
+ */
+/** @typedef {{ id: string, handle: string, title: string }} ListCollection */
+/** @typedef {{ product: Product, scope: { root: Element, variant: ProductVariant | null } | null }} ProductReadyDetail */
+/** @typedef {{ products: Product[] | undefined, collection: ListCollection | null }} ListReadyDetail */
+/** @typedef {{ cart: AnalyticsCart | null, reason: string }} CartUpdatedDetail */
 
-const num = (m) => (m ? parseFloat(m.amount) : 0);
-const id = (gid) => String(gid || '').split('/').pop();
+/** 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;
 
-// ---------------------------------------------------------------- shapes
+/** @param {Money | null | undefined} money */
+const amountOf = (money) => (money ? parseFloat(money.amount) : 0);
 
-function itemFromVariant(p, v, quantity = 1, index) {
-  return {
-    item_id: v?.sku || id(v?.id) || id(p.id),
-    item_name: p.title,
-    item_variant: v?.title === 'Default Title' ? undefined : v?.title,
-    item_brand: p.vendor || undefined,
-    item_category: p.productType || undefined,
-    price: num(v?.price || p.priceRange?.minVariantPrice),
+/**
+ * @param {string | null | undefined} gid
+ * @returns {string} The numeric part of a gid.
+ */
+const numericId = (gid) => (gid ?? '').split('/').pop() ?? '';
+
+/**
+ * @param {ItemProduct} product
+ * @param {ItemVariant | null | undefined} variant
+ * @param {number} [quantity]
+ * @param {number} [index] The position in a list.
+ * @returns {AnalyticsItem}
+ */
+function itemFromVariant(product, variant, quantity = 1, index) {
+  /** @type {AnalyticsItem} */
+  const item = {
+    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,
-    ...(index != null ? { index } : {}),
   };
+  if (index != null) item.index = index;
+  return item;
 }
 
-function itemFromLine(l, quantity = l.quantity) {
-  const m = l.merchandise || {};
-  return itemFromVariant({ ...(m.product || {}), title: m.product?.title }, m, quantity);
+/**
+ * @param {CartLine} line
+ * @param {number} [quantity]
+ */
+const itemFromLine = (line, quantity = line.quantity) =>
+  itemFromVariant(line.merchandise.product, line.merchandise, quantity);
+
+/**
+ * @param {AnalyticsItem[]} items
+ * @returns {number} The items' total, rounded to cents.
+ */
+function totalValue(items) {
+  const total = items.reduce((sum, item) => sum + item.price * (item.quantity || 1), 0);
+  return Math.round(total * CENTS_PER_UNIT) / CENTS_PER_UNIT;
 }
 
-const value = (items) => Math.round(items.reduce((s, i) => s + (i.price || 0) * (i.quantity || 1), 0) * 100) / 100;
+/**
+ * @param {Product} product
+ * @param {ItemVariant} variant
+ * @param {number} [quantity]
+ */
+const productPayload = (product, variant, 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,
+});
 
-// ---------------------------------------------------------------- GA4 / GTM
+/** @param {CartLine} line */
+const linePayload = (line) => ({
+  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,
+    },
+  },
+});
 
-function ga(event, ecommerce) {
-  const name = typeof cfg.analytics.dataLayer === 'string' ? cfg.analytics.dataLayer : 'dataLayer';
-  const dl = (window[name] = window[name] || []);
-  if (ecommerce) dl.push({ ecommerce: null }); // Google: clear the previous ecommerce object first
-  dl.push(ecommerce ? { event, ecommerce } : { event });
+/** @returns {unknown[]} The GA4 / GTM data layer, created when the page has none. */
+function dataLayer() {
+  const { dataLayer: option } = cfg.analytics ?? {};
+  const name = typeof option === 'string' ? option : 'dataLayer';
+  /** @type {unknown} */
+  const existing = Reflect.get(window, name);
+  if (Array.isArray(existing)) return existing;
+  /** @type {unknown[]} */
+  const created = [];
+  Reflect.set(window, name, created);
+  return created;
 }
 
-// ---------------------------------------------------------------- Shopify analytics (Hydrogen's bus)
+/**
+ * @param {string} event
+ * @param {Record<string, unknown> | undefined} ecommerce
+ */
+function pushToDataLayer(event, ecommerce) {
+  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 });
+}
 
+/** @type {AnalyticsBus | null} */
 let bus = null;
+/** @type {Map<string, CartLine> | null} Variant id to line, to turn cart changes into add and remove events. */
+let lastLines = null;
+/** @type {AnalyticsCart | null} */
+let lastCart = null;
+/** @type {WeakSet<Element>} Product roots whose view_item was sent on this page. */
+let viewed = new WeakSet();
 
-function shopifyBus(shopId) {
-  const destinations = [];
-  const buffer = [];
-  const privacy = () => window.Shopify?.customerPrivacy;
-  const canTrack = () => {
-    try {
-      const p = privacy();
-      return p?.consentStatus === 'loaded' && p.currentVisitorConsent?.()?.analytics !== 'no' && Boolean(p.analyticsProcessingAllowed?.());
-    } catch { return false; }
-  };
-  const config = { shop: { shopId, channel: 'headless' }, consent: { mode: cfg.analytics.shopify?.consent || 'no-banner' } };
-  const deliver = () => {
-    if (!canTrack()) return;
-    destinations.forEach((d) => {
-      while (d.next < buffer.length) {
-        const { event, payload } = buffer[d.next++];
-        (d.subs.get(event) || []).forEach((cb) => { try { cb(payload, d.context); } catch (err) { reportError(err, `analytics ${d.name}`); } });
-      }
-    });
-  };
-  const api = {
-    getConfig: () => config,
-    publish(event, payload = {}) {
-      buffer.push({ event, payload: { shop: config.shop, url: window.location.href, ...payload } });
-      if (buffer.length > 500) { buffer.shift(); destinations.forEach((d) => { d.next = Math.max(0, d.next - 1); }); }
-      deliver();
-    },
-    addDestination(dest) {
-      const tag = `hydrogen:${dest.name}`;
-      const d = {
-        name: dest.name, next: 0, subs: new Map(),
-        context: {
-          getTrackingValues: () => {
-            const i = canTrack() ? privacy()?.__internal : null;
-            return { uniqueToken: i?.uniqueToken?.({ generateFallback: true, tag }) ?? '', visitToken: i?.visitToken?.({ generateFallback: true, tag }) ?? '' };
-          },
-        },
-      };
-      const subscribe = (event, cb) => {
-        if (!d.subs.has(event)) d.subs.set(event, new Set());
-        d.subs.get(event).add(cb);
-        return () => d.subs.get(event)?.delete(cb);
-      };
-      Promise.resolve(dest.setup?.({ subscribe, getConfig: api.getConfig })).then(() => { destinations.push(d); deliver(); })
-        .catch((err) => reportError(err, `analytics ${dest.name}`));
-      return () => { const i = destinations.indexOf(d); if (i >= 0) destinations.splice(i, 1); };
-    },
-  };
-  document.addEventListener('consentTrackingApiLoaded', deliver);
-  document.addEventListener('visitorConsentCollected', deliver);
-  return api;
+/**
+ * @param {string} name The GA4 event.
+ * @param {Record<string, unknown>} data
+ * @param {string} [shopifyEvent]
+ * @param {EventPayload} [shopifyPayload]
+ */
+function send(name, data, shopifyEvent, shopifyPayload) {
+  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');
+  }
 }
 
-function loadScript(src) {
-  const s = document.createElement('script');
-  s.src = src;
-  s.async = true;
-  document.head.appendChild(s);
+/** @returns {unknown} The scope of the page's own product: a product root outside every list. */
+function mainProduct() {
+  const el = document.querySelector(sel('product'));
+  if (!el || el.closest(`${sel('collection')},${sel('products')},${sel('recommendations')}`)) return null;
+  /** @type {unknown} */
+  const tether = Reflect.get(window, 'Tether');
+  // The core sets window.Tether before it loads this part.
+  return /** @type {{ getScope: (el: Element) => unknown }} */ (tether).getScope(el);
 }
 
-async function startShopify() {
-  if (window.Shopify?.analytics) { bus = window.Shopify.analytics; return; } // already set up (e.g. by the theme)
-  const data = await gql('query TetherShopId { shop { id } }', {}, { context: false });
-  const country = String(cfg.country || 'US').toUpperCase();
-  const S = (window.Shopify = window.Shopify || {});
-  Object.assign(S, {
-    country,
-    locale: (cfg.locale || 'en').split('-')[0].toLowerCase(), // required by Shopify's script
-    shop: cfg.domain,
-    routes: { root: '/', match: () => ({ pageTemplateName: mainProduct() ? 'product' : 'page' }), ...(S.routes || {}) },
+/** @param {ProductReadyDetail} detail */
+function onProductReady({ product, scope }) {
+  if (!scope || 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,
   });
-  const proxy = cfg.analytics.shopify?.proxy; // same-origin Storefront API path, for exact visitor counts
-  S.customerPrivacy = {
-    ...(S.customerPrivacy || {}),
-    config: proxy
-      ? { isHeadless: true, asyncConsent: true, asyncVisitorState: true, consentDomain: window.location.host }
-      : { isHeadless: true, storefrontAccessToken: cfg.token, checkoutRootDomain: cfg.domain },
-  };
-  bus = shopifyBus(data.shop.id);
-  S.analytics = bus;
-  loadScript(cfg.analytics.shopify?.consent === 'default-banner'
-    ? 'https://cdn.shopify.com/shopifycloud/privacy-banner/storefront-banner.js'
-    : 'https://cdn.shopify.com/shopifycloud/consent-tracking-api/v0.2/consent-tracking-api.js');
-  loadScript('https://cdn.shopify.com/storefront/analytics/shopify.js');
-  log('shopify analytics ready', data.shop.id);
 }
 
-const productPayload = (p, v, quantity = 1) => ({
-  id: p.id, title: p.title, price: v.price, vendor: p.vendor || '', variantId: v.id, variantTitle: v.title,
-  quantity, sku: v.sku || undefined, productType: p.productType || undefined,
-});
-
-function analyticsLine(l) {
-  const m = l.merchandise || {};
-  return { id: l.id, quantity: l.quantity, merchandise: { id: m.id, title: m.title, price: m.price, sku: m.sku, product: { id: m.product?.id, title: m.product?.title, vendor: m.product?.vendor || '', handle: m.product?.handle } } };
+/** @param {ListReadyDetail} detail */
+function onListReady({ products = [], collection }) {
+  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 },
+  });
 }
 
-// ---------------------------------------------------------------- what happened on the page
+/**
+ * @param {AnalyticsCart | null} cart
+ * @param {Map<string, CartLine>} now
+ * @param {Map<string, CartLine>} before
+ */
+function sendCartChanges(cart, now, before) {
+  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 mainProduct() {
-  const el = document.querySelector(sel('product'));
-  return el && !el.closest(`${sel('collection')},${sel('products')},${sel('recommendations')}`) ? window.Tether?.getScope(el) : null;
+/** @param {CartUpdatedDetail} detail */
+function onCartUpdated({ cart, reason }) {
+  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;
 }
 
-const send = (name, data, shopifyEvent, shopifyPayload) => {
-  if (cfg.analytics.dataLayer) ga(name, data);
-  if (bus && shopifyEvent) bus.publish(shopifyEvent, shopifyPayload);
-  try { cfg.analytics.onEvent?.(name, data); } catch (err) { reportError(err, 'analytics onEvent'); }
-};
+function onCartOpened() {
+  const items = Cart.lines.map((line) => itemFromLine(line));
+  send('view_cart', { currency: Cart.state?.cost.totalAmount.currencyCode, value: totalValue(items), items });
+}
 
-let lastLines = null; // variant id -> line, to turn cart changes into add/remove events
-let viewed = new WeakSet();
+/** @param {{ cart: AnalyticsCart }} detail */
+function onCheckout({ cart }) {
+  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,
+  });
+}
 
-function handle(e) {
-  const name = e.type.slice(cfg.prefix.length + 1);
-  const d = e.detail || {};
-  if (name === 'product-ready') {
-    const scope = d.scope;
-    if (!scope || viewed.has(scope.root) || mainProduct() !== scope) return;
-    viewed.add(scope.root);
-    const v = scope.variant || d.product.variants.nodes[0];
-    const items = [itemFromVariant(d.product, v)];
-    send('view_item', { currency: v?.price?.currencyCode, value: value(items), items }, 'product_viewed', { products: [productPayload(d.product, v)] });
-  } else if (name === 'list-ready') {
-    const items = (d.products || []).slice(0, 200).map((p, i) => itemFromVariant(p, p.variants?.nodes?.[0], 1, i));
-    const list = { item_list_id: d.collection?.handle || 'products', item_list_name: d.collection?.title || 'Products' };
-    send('view_item_list', { ...list, items }, d.collection ? 'collection_viewed' : null, d.collection ? { collection: { id: d.collection.id, handle: d.collection.handle } } : null);
-  } else if (name === 'cart-updated') {
-    const cart = d.cart;
-    const now = new Map((cart?.lines?.nodes || []).map((l) => [l.merchandise?.id, l]));
-    if (lastLines && d.reason !== 'load' && d.reason !== 'pending') {
-      const currency = cart?.cost?.totalAmount?.currencyCode;
-      now.forEach((l, k) => {
-        const diff = l.quantity - (lastLines.get(k)?.quantity || 0);
-        if (diff > 0) {
-          const items = [itemFromLine(l, diff)];
-          send('add_to_cart', { currency, value: value(items), items }, 'product_added_to_cart', {
-            cart, prevCart: lastCart, currentLine: analyticsLine(l), prevLine: lastLines.get(k) ? analyticsLine(lastLines.get(k)) : undefined,
-          });
-        }
-      });
-      lastLines.forEach((l, k) => {
-        const diff = l.quantity - (now.get(k)?.quantity || 0);
-        if (diff > 0) { const items = [itemFromLine(l, diff)]; send('remove_from_cart', { currency, value: value(items), items }); }
-      });
+/**
+ * Turns one Tether event into analytics events. The details are Tether's own (`emit`), typed per event here.
+ *
+ * @param {Event} event `<prefix>:<name>`.
+ */
+function handle(event) {
+  const name = event.type.slice(cfg.prefix.length + 1);
+  /** @type {unknown} */
+  const detail = Reflect.get(event, 'detail');
+  switch (name) {
+    case 'product-ready':
+      onProductReady(/** @type {ProductReadyDetail} */ (detail));
+      break;
+    case 'list-ready':
+      onListReady(/** @type {ListReadyDetail} */ (detail));
+      break;
+    case 'cart-updated':
+      onCartUpdated(/** @type {CartUpdatedDetail} */ (detail));
+      break;
+    case 'cart-toggled':
+      if (/** @type {{ open: boolean }} */ (detail).open) onCartOpened();
+      break;
+    case 'checkout':
+      onCheckout(/** @type {{ cart: AnalyticsCart }} */ (detail));
+      break;
+    case 'search': {
+      const { term } = /** @type {{ term: string }} */ (detail);
+      if (term) send('search', { search_term: term }, 'search_viewed', { searchTerm: term });
+      break;
     }
-    lastLines = now;
-    lastCart = cart;
-  } else if (name === 'cart-toggled' && d.open) {
-    const items = Cart.lines.map((l) => itemFromLine(l));
-    send('view_cart', { currency: Cart.state?.cost?.totalAmount?.currencyCode, value: value(items), items });
-  } else if (name === 'checkout') {
-    const items = (d.cart?.lines?.nodes || []).map((l) => itemFromLine(l));
-    const coupon = (d.cart?.discountCodes || []).filter((c) => c.applicable).map((c) => c.code).join(',') || undefined;
-    send('begin_checkout', { currency: d.cart?.cost?.totalAmount?.currencyCode, value: value(items), coupon, items });
-  } else if (name === 'search' && d.term) {
-    send('search', { search_term: d.term }, 'search_viewed', { searchTerm: d.term });
-  } else if (name === 'page') {
-    viewed = new WeakSet();
-    if (bus) bus.publish('page_viewed', {});
+    case 'page':
+      viewed = new WeakSet();
+      bus?.publish('page_viewed', {});
+      break;
+    default:
+      break;
   }
 }
-let lastCart = null;
 
-/** Called by the core with the events it buffered while this part loaded. */
+/**
+ * Called by the core with the events it buffered while this part loaded; the queue then handles events as they come.
+ *
+ * @param {Event[]} queue
+ */
 export async function startAnalytics(queue) {
-  if (cfg.analytics.shopify) await startShopify().catch((err) => reportError(err, 'shopify analytics'));
-  if (bus) bus.publish('page_viewed', {});
+  if (cfg.analytics?.shopify) {
+    bus = await startShopifyAnalytics(() => mainProduct() != null).catch((/** @type {unknown} */ error) => {
+      reportError(error, 'shopify analytics');
+      return null;
+    });
+  }
+  bus?.publish('page_viewed', {});
   queue.splice(0).forEach(handle);
-  queue.push = (e) => { handle(e); return 0; }; // from now on, handle events as they come
+  queue.push = (...events) => {
+    events.forEach(handle);
+    return queue.length;
+  };
 }

package/src/api-version.js

@@ -1,35 +1,85 @@
 /**
- * Shopify API versions are quarterly (YYYY-01, -04, -07, -10) and supported for 12 months.
- * Tether pins a dated version and never targets `unstable` (it changes without notice).
+ * Shopify API versions are quarterly (YYYY-01, -04, -07, -10) and supported for 12 months. Tether pins a dated version
+ * and never targets `unstable` (it changes without notice). Used by the diagnose part and the release scripts.
  */
 
-const parse = (v) => {
-  const m = /^(\d{4})-(01|04|07|10)$/.exec(String(v || ''));
-  return m ? { y: +m[1], m: +m[2] } : null;
-};
-const fmt = (y, m) => `${y}-${String(m).padStart(2, '0')}`;
+const QUARTERLY_VERSION = /^(\d{4})-(01|04|07|10)$/;
+const MONTHS_PER_QUARTER = 3;
+const QUARTERS_PER_YEAR = 4;
+const MONTHS_SUPPORTED = 12;
+/** Months left at which the status starts asking for an upgrade. */
+const UPGRADE_WARNING_MONTHS = 3;
+const AVERAGE_MONTH_MS = 30.44 * 24 * 3600 * 1000;
 
-export const isDatedVersion = (v) => Boolean(parse(v));
+/**
+ * @typedef {object} ApiVersionStatus
+ * @property {string} version
+ * @property {boolean} ok Released and still supported.
+ * @property {string} note What to do about it, for people.
+ * @property {number} [monthsLeft] Months of support left, rounded; negative once support ended.
+ * @property {string} [next] The version after this one.
+ */
 
-/** '2026-07' -> '2026-10', '2026-10' -> '2027-01'. */
-export function nextApiVersion(v, steps = 1) {
-  const p = parse(v);
-  if (!p) throw new Error(`not a quarterly Shopify API version: ${v}`);
-  const q = p.y * 4 + (p.m - 1) / 3 + steps;
-  return fmt(Math.floor(q / 4), (q % 4) * 3 + 1);
+/**
+ * @param {unknown} version
+ * @returns {{ year: number, month: number } | null}
+ */
+function parseVersion(version) {
+  const match = QUARTERLY_VERSION.exec(typeof version === 'string' ? version : '');
+  if (!match) return null;
+  return { year: Number(match[1]), month: Number(match[2]) };
 }
 
-/** Support window of a version, relative to `now`. */
+/**
+ * @param {number} year
+ * @param {number} month 1 to 12.
+ */
+const formatVersion = (year, month) => `${year}-${String(month).padStart(2, '0')}`;
+
+/**
+ * `'2026-07'` → `'2026-10'`, `'2026-10'` → `'2027-01'`.
+ *
+ * @param {string} version
+ * @param {number} [steps] Quarters ahead.
+ * @returns {string}
+ * @throws {Error} When `version` isn't a quarterly version.
+ */
+export function nextApiVersion(version, steps = 1) {
+  const parsed = parseVersion(version);
+  if (!parsed) throw new Error(`not a quarterly Shopify API version: ${version}`);
+  const quarter = parsed.year * QUARTERS_PER_YEAR + (parsed.month - 1) / MONTHS_PER_QUARTER + steps;
+  return formatVersion(Math.floor(quarter / QUARTERS_PER_YEAR), (quarter % QUARTERS_PER_YEAR) * MONTHS_PER_QUARTER + 1);
+}
+
+/**
+ * The support window of `version`, relative to `now`.
+ *
+ * @param {string} version
+ * @param {Date} [now]
+ * @returns {ApiVersionStatus}
+ */
 export function apiVersionStatus(version, now = new Date()) {
-  if (version === 'unstable') return { version, ok: false, note: '"unstable" changes without notice: pin a dated version such as 2026-07' };
-  const p = parse(version);
-  if (!p) return { version, ok: false, note: 'not a quarterly version (YYYY-01, -04, -07 or -10)' };
-  const released = new Date(Date.UTC(p.y, p.m - 1, 1));
-  const supportedUntil = new Date(Date.UTC(p.y + 1, p.m - 1, 1));
-  const monthsLeft = (supportedUntil - now) / (30.44 * 24 * 3600 * 1000);
+  if (version === 'unstable') {
+    return { version, ok: false, note: '"unstable" changes without notice: pin a dated version such as 2026-07' };
+  }
+  const parsed = parseVersion(version);
+  if (!parsed) return { version, ok: false, note: 'not a quarterly version (YYYY-01, -04, -07 or -10)' };
+  const released = new Date(Date.UTC(parsed.year, parsed.month - 1, 1));
+  const supportedUntil = new Date(Date.UTC(parsed.year, parsed.month - 1 + MONTHS_SUPPORTED, 1));
+  const monthsLeft = (supportedUntil.getTime() - now.getTime()) / AVERAGE_MONTH_MS;
+  const isReleased = released <= now;
   let note = `supported until about ${supportedUntil.toISOString().slice(0, 7)}`;
-  if (released > now) note = 'not released yet (release candidate at best)';
-  else if (monthsLeft <= 0) note = 'no longer supported: Shopify falls back to the oldest supported version. Upgrade (see README)';
-  else if (monthsLeft < 3) note = `${note}: plan the upgrade to ${nextApiVersion(version)} or later (see README)`;
-  return { version, ok: released <= now && monthsLeft > 0, monthsLeft: Math.round(monthsLeft), next: nextApiVersion(version), note };
+  if (!isReleased) note = 'not released yet (release candidate at best)';
+  else if (monthsLeft <= 0) {
+    note = 'no longer supported: Shopify falls back to the oldest supported version. Upgrade (see README)';
+  } else if (monthsLeft < UPGRADE_WARNING_MONTHS) {
+    note = `${note}: plan the upgrade to ${nextApiVersion(version)} or later (see README)`;
+  }
+  return {
+    version,
+    ok: isReleased && monthsLeft > 0,
+    monthsLeft: Math.round(monthsLeft),
+    next: nextApiVersion(version),
+    note,
+  };
 }