@occluze/tether 0.6.7 → 0.7.0

package/src/account-pages.ts

@@ -0,0 +1,81 @@
+/**
+ * Customer account pages, an optional part the account part loads on pages that use them: the order page with
+ * returns, the profile form, addresses and subscriptions. Each operation is one of the Worker's fixed routes, which
+ * checks the input (account/operations.ts).
+ */
+import { reportError } from './config.ts';
+import { qsa, sel } from './dom.ts';
+import { pagesContext } from './account/operations.ts';
+import { renderOrder, showOrderState } from './account/order-page.ts';
+import { renderAddresses } from './account/addresses-view.ts';
+import { renderSubscriptions } from './account/subscriptions-view.ts';
+import { listenToPages } from './account/page-events.ts';
+import { showIn } from './account/markup.ts';
+import type { AccountCustomer } from './account/answers.ts';
+
+export {
+  setup,
+  order,
+  updateProfile,
+  addresses,
+  saveAddress,
+  deleteAddress,
+  subscriptions,
+  subscriptionAction,
+  requestReturn,
+} from './account/operations.ts';
+
+/** The profile fields a `tether-profile-form` is filled with. */
+const PROFILE_FIELDS = ['firstName', 'lastName'] as const;
+
+/** Fills the profile form with the customer's name, leaving a field the visitor has typed in alone. */
+async function renderProfile(form: HTMLElement): Promise<void> {
+  if (!(form instanceof window.HTMLFormElement)) return;
+  let customer: AccountCustomer | null;
+  try {
+    customer = await pagesContext().customer();
+  } catch (error) {
+    // The form stays empty and still saves: only the prefill is missing.
+    reportError(error, 'account');
+    return;
+  }
+  if (!customer) return;
+  const fields = form.elements;
+  PROFILE_FIELDS.forEach((name) => {
+    const input = fields.namedItem(name);
+    const isTextField = input instanceof window.HTMLInputElement || input instanceof window.HTMLTextAreaElement;
+    if (isTextField && !input.dataset['tetherTouched']) input.value = customer[name] ?? '';
+  });
+}
+
+let listening = false;
+
+/** Renders the order page, profile form, addresses and subscriptions in `root`: only what it has. */
+export async function renderPages(root: ParentNode = document): Promise<void> {
+  if (!listening) {
+    listening = true;
+    listenToPages();
+  }
+  await Promise.all([
+    ...qsa(root, sel('order')).map((el) => renderOrder(el)),
+    ...qsa(root, sel('profile-form')).map((form) => renderProfile(form)),
+    renderAddresses(root),
+    renderSubscriptions(root),
+  ]);
+}
+
+/**
+ * The error state of every account page in `root`, for when nobody can say whether a customer is logged in (the
+ * Worker or Shopify can't be reached).
+ */
+export function showUnavailable(root: ParentNode): void {
+  qsa(root, sel('order')).forEach((el) => {
+    showOrderState(el, 'error');
+  });
+  showIn(root, 'show', {
+    'addresses-loading': false,
+    'addresses-error': true,
+    'subscriptions-loading': false,
+    'subscriptions-error': true,
+  });
+}

package/src/account.ts

@@ -0,0 +1,284 @@
+/**
+ * Customer accounts (Shopify Customer Account API), as an optional part: loaded only when `account` is configured
+ * and the page uses it, or a login is coming back, or the visitor may be logged in.
+ *
+ *   window.TETHER_CONFIG = { …, account: { server: '/_tether/account' } }
+ *
+ *   <button tether-account-login>Log in</button>
+ *   <button tether-account-logout tether-show="logged-in">Log out</button>
+ *   <span tether-account-bind="first-name"></span>             first-name, last-name, name, email, address
+ *   <div tether-orders>                                       the customer's orders (first child = template)
+ *     <a tether-order-bind="url"><span tether-order-bind="name"></span> · <span tether-order-bind="date"></span></a>
+ *   </div>
+ *   <p tether-show="logged-out">…</p>
+ *
+ * The site's Worker logs the customer in and holds the tokens (`account/server-client.ts` is this browser's side of
+ * it), so no token is ever in the browser. The order page, profile, addresses, subscriptions and returns are the
+ * `account-pages` part, loaded only on pages that use them.
+ */
+import { cfg, log, reportError } from './config.ts';
+import { TetherError } from './client.ts';
+import { sel, get, qsa, setText, show, emit } from './dom.ts';
+import { Cart } from './cart.ts';
+import { loadPart } from './lazy.ts';
+import type { Parts } from './lazy.ts';
+import {
+  forgetServerLogin,
+  isServerLoggedIn,
+  serverCheckoutUrl,
+  serverFetch,
+  serverLogin,
+  serverLoginRedirect,
+  serverLogout,
+} from './account/server-client.ts';
+import { DEFAULT_ORDER_COUNT, MAX_ORDER_COUNT, isOrderCount, renderOrderList } from './account/order-list.ts';
+import { ownValue } from './account/markup.ts';
+import { toAccountOrders } from './account/answers.ts';
+import type { AccountCustomer } from './account/answers.ts';
+import { isLoginOutcome } from './account-marks.ts';
+import type { AccountOrder } from '../server/src/shared/account-orders.ts';
+import type { AddressFields, ReturnLine } from './account/operations.ts';
+import type {
+  AccountAddress,
+  CustomerAddress,
+  OpenedReturn,
+  OrderDetail,
+  Profile,
+  SubscriptionChange,
+  SubscriptionContract,
+} from './account/page-answers.ts';
+import type { SubscriptionAction } from '../server/src/shared/account-routes.ts';
+
+/**
+ * `unknown` when the Worker or Shopify can't say: the page shows its logged-out content, and the account pages their
+ * error state.
+ */
+type LoginState = { kind: 'logged-in' } | { kind: 'logged-out' } | { kind: 'unknown'; error: unknown };
+
+/** The attributes of the account pages, which are their own part. */
+const PAGE_ATTRIBUTES = ['order', 'addresses', 'subscriptions', 'profile-form', 'address-form'];
+
+/** @returns True when the Worker last said a customer is logged in; false before it has been asked. */
+export const isLoggedIn = isServerLoggedIn;
+
+/**
+ * Through the Worker to Shopify's login page; the visitor comes back to `returnTo`.
+ *
+ * @throws {TetherError} `NOT_CONFIGURED` without `account.server`.
+ */
+export function login({
+  returnTo = window.location.href,
+  locale,
+}: { returnTo?: string; locale?: string } = {}): Promise<void> {
+  // In a promise, so a missing `account.server` rejects as it does for every other account function.
+  return new Promise((resolve) => {
+    serverLoginRedirect({ returnTo, locale });
+    resolve();
+  });
+}
+
+/**
+ * @returns The logged-in customer, `null` when nobody is.
+ * @throws {TetherError} When the Worker can't be reached or fails.
+ */
+export async function customer(): Promise<AccountCustomer | null> {
+  const me = await serverLogin();
+  return me.loggedIn ? me.customer : null;
+}
+
+/**
+ * @param options `first`: a whole number from 1 to `MAX_ORDER_COUNT`.
+ * @returns The customer's most recent orders, newest first; none when nobody is logged in.
+ * @throws {TetherError} `INVALID` for another `first`, which is refused before any request; else when the Worker or
+ *   Shopify can't answer.
+ */
+export async function orders({ first = DEFAULT_ORDER_COUNT }: { first?: number } = {}): Promise<AccountOrder[]> {
+  if (!isOrderCount(first)) {
+    throw new TetherError(`Customer accounts: orders() takes first from 1 to ${String(MAX_ORDER_COUNT)}`, {
+      code: 'INVALID',
+    });
+  }
+  const answer = await serverFetch(`/orders?${new URLSearchParams({ first: String(first) }).toString()}`);
+  return answer.kind === 'logged-out' ? [] : toAccountOrders(answer.data['orders']);
+}
+
+/**
+ * Logs out here and at Shopify, and unlinks the cart. Sends `tether:account-logout`.
+ *
+ * @param options `returnTo`: where Shopify sends the visitor afterwards.
+ */
+export async function logout({
+  returnTo = cfg.account?.logoutUrl || `${window.location.origin}/`,
+}: { returnTo?: string } = {}): Promise<void> {
+  if ((await serverLogout(returnTo)) === 'stayed') await render(document);
+}
+
+async function loginState(): Promise<LoginState> {
+  try {
+    return (await serverLogin()).loggedIn ? { kind: 'logged-in' } : { kind: 'logged-out' };
+  } catch (error) {
+    return { kind: 'unknown', error };
+  }
+}
+
+const usesPages = (root: ParentNode): boolean => PAGE_ATTRIBUTES.some((name) => qsa(root, sel(name)).length > 0);
+
+/**
+ * `tether-account-link`: Shopify's own pages, for what has to stay there: `subscriptions` and `payment`
+ * (`account.subscriptionsUrl` / `paymentUrl`), or the account itself.
+ */
+function linkShopifyPages(root: ParentNode): void {
+  qsa(root, sel('account-link')).forEach((link) => {
+    link.setAttribute('href', shopifyPageUrl(get(link, 'account-link')));
+  });
+}
+
+/**
+ * @param page The `tether-account-link` value.
+ * @returns The configured page for it, else the shop's account.
+ */
+function shopifyPageUrl(page: string | null): string {
+  const account = cfg.account;
+  const fallback = `https://${cfg.domain}/account`;
+  if (page === 'payment') return account?.paymentUrl || account?.subscriptionsUrl || fallback;
+  if (page === 'subscriptions') return account?.subscriptionsUrl || fallback;
+  return fallback;
+}
+
+/**
+ * Fills the account markup in `root`: what shows when logged in or out, the customer, their orders, and the account
+ * pages.
+ */
+export async function render(root: ParentNode = document): Promise<void> {
+  const state = await loginState();
+  if (state.kind === 'unknown') reportError(state.error, 'account');
+  const loggedIn = state.kind === 'logged-in';
+  qsa(root, sel('show')).forEach((el) => {
+    const condition = get(el, 'show');
+    if (condition === 'logged-in') show(el, loggedIn);
+    if (condition === 'logged-out') show(el, !loggedIn);
+  });
+  linkShopifyPages(root);
+  if (state.kind === 'unknown' && usesPages(root)) {
+    (await pages()).showUnavailable(root);
+    return;
+  }
+  if (!loggedIn) return;
+  await bindCustomer(root);
+  await Promise.all([
+    renderOrderList(root, (first) => orders({ first })),
+    usesPages(root) ? pages().then((part) => part.renderPages(root)) : null,
+  ]);
+}
+
+/**
+ * `tether-account-bind`: the customer's name, email, default address. A failure is reported and leaves the binds as
+ * they are.
+ */
+async function bindCustomer(root: ParentNode): Promise<void> {
+  const binds = qsa(root, sel('account-bind'));
+  if (!binds.length) return;
+  let profile: AccountCustomer | null;
+  try {
+    profile = await customer();
+  } catch (error) {
+    reportError(error, 'account');
+    return;
+  }
+  if (!profile) return;
+  const texts: Record<string, string | null | undefined> = {
+    'first-name': profile.firstName,
+    'last-name': profile.lastName,
+    name: profile.displayName,
+    email: profile.emailAddress?.emailAddress,
+    address: profile.defaultAddress?.formatted.join(', '),
+  };
+  binds.forEach((el) => {
+    const text = ownValue(texts, get(el, 'account-bind') ?? '');
+    if (text != null) setText(el, text);
+  });
+}
+
+let pagesPart: Promise<Parts['account-pages']> | null = null;
+
+/** @returns The account pages part, sharing this part's session. */
+function pages(): Promise<Parts['account-pages']> {
+  pagesPart ??= loadPart('account-pages').then((part) => {
+    part.setup({ serverFetch, customer, bindCustomer, reset: forgetServerLogin });
+    return part;
+  });
+  return pagesPart;
+}
+
+/** One of the customer's orders, in full (lines, totals, addresses, fulfillments, returns). */
+export const order = (id: string | number): Promise<OrderDetail | null> => pages().then((part) => part.order(id));
+export const updateProfile = (fields?: { firstName?: string; lastName?: string }): Promise<Profile> =>
+  pages().then((part) => part.updateProfile(fields));
+export const addresses = (): Promise<CustomerAddress[]> => pages().then((part) => part.addresses());
+/** Creates an address, or updates the one with `id`. */
+export const saveAddress = (
+  address: AddressFields | null,
+  options?: { id?: string; isDefault?: boolean },
+): Promise<AccountAddress> => pages().then((part) => part.saveAddress(address, options));
+export const deleteAddress = (id: string): Promise<string> => pages().then((part) => part.deleteAddress(id));
+export const subscriptions = (): Promise<SubscriptionContract[]> => pages().then((part) => part.subscriptions());
+export const subscriptionAction = (id: string | number, action: SubscriptionAction): Promise<SubscriptionChange> =>
+  pages().then((part) => part.subscriptionAction(id, action));
+export const requestReturn = (orderId: string | number, lines: ReturnLine[]): Promise<OpenedReturn> =>
+  pages().then((part) => part.requestReturn(orderId, lines));
+
+function onClick(event: MouseEvent): void {
+  const target = event.target;
+  if (!(target instanceof window.Element)) return;
+  if (target.closest(sel('account-login'))) {
+    event.preventDefault();
+    login().catch((error: unknown) => {
+      reportError(error, 'login');
+    });
+  } else if (target.closest(sel('account-logout'))) {
+    event.preventDefault();
+    logout().catch((error: unknown) => {
+      reportError(error, 'logout');
+    });
+  }
+}
+
+/**
+ * Back from the Worker's login (`?account=`): drops the mark and sends `tether:account-login`, or
+ * `tether:account-error` with the outcome as its `error` when the login didn't finish.
+ */
+function finishServerLogin(): void {
+  const url = new URL(window.location.href);
+  const outcome = url.searchParams.get('account');
+  if (!isLoginOutcome(outcome)) return;
+  url.searchParams.delete('account');
+  window.history.replaceState(window.history.state, '', url);
+  switch (outcome) {
+    case 'in':
+      emit('account-login', {});
+      break;
+    case 'expired':
+    case 'error':
+      emit('account-error', { error: outcome });
+      break;
+  }
+}
+
+let started = false;
+
+/**
+ * Called by the core on mount: on the first one, finishes a login that's coming back and lets the Worker link the
+ * cart at checkout; then fills the page.
+ */
+export async function mountAccount(root: ParentNode = document): Promise<void> {
+  if (started) {
+    await render(root);
+    return;
+  }
+  started = true;
+  document.addEventListener('click', onClick);
+  finishServerLogin();
+  Cart.setCheckoutResolver(serverCheckoutUrl);
+  await render(root);
+  log('account', isLoggedIn() ? 'logged in' : 'logged out');
+}

package/src/amounts.ts

@@ -0,0 +1,64 @@
+/**
+ * Arithmetic on Shopify's money amounts, which are decimal strings (`'27.50'`). Comparisons go digit by digit, as
+ * integers of the smallest unit present, so two amounts that differ only past float precision aren't misjudged. Sums
+ * and differences are taken in the currency's own smallest unit, so JPY stays whole and KWD keeps its three digits.
+ */
+import type { Money } from './shopify-values.ts';
+
+const DECIMAL = /^(-?)(\d+)(?:\.(\d+))?$/;
+
+/**
+ * @param fractionDigits Digits after the point to scale to.
+ * @returns The amount in units of 10^-fractionDigits, `null` when it isn't a decimal number.
+ */
+function toScaledInteger(amount: string, fractionDigits: number): bigint | null {
+  const match = DECIMAL.exec(amount.trim());
+  if (!match) return null;
+  const [, sign = '', whole = '0', fraction = ''] = match;
+  const digits = BigInt(`${whole}${fraction.padEnd(fractionDigits, '0')}`);
+  return sign === '-' ? -digits : digits;
+}
+
+const fractionLength = (amount: string) => amount.split('.')[1]?.length ?? 0;
+
+/** @returns True when both are decimal numbers and `amount` is the larger one. */
+export function isGreaterAmount(amount: string | null | undefined, other: string | null | undefined): boolean {
+  if (amount == null || other == null) return false;
+  const fractionDigits = Math.max(fractionLength(amount.trim()), fractionLength(other.trim()));
+  const scaled = toScaledInteger(amount, fractionDigits);
+  const scaledOther = toScaledInteger(other, fractionDigits);
+  if (scaled === null || scaledOther === null) return false;
+  return scaled > scaledOther;
+}
+
+/** For a currency code Intl doesn't know: most currencies have two digits, and `formatMoney` then shows two too. */
+const DEFAULT_FRACTION_DIGITS = 2;
+
+/** Currency code → its fraction digits, which never change on a page. */
+const fractionDigitsByCurrency = new Map<string, number>();
+
+/** @returns The digits after the point the currency has: 0 for JPY, 2 for EUR, 3 for KWD. */
+function currencyFractionDigits(currencyCode: string): number {
+  const known = fractionDigitsByCurrency.get(currencyCode);
+  if (known !== undefined) return known;
+  let digits = DEFAULT_FRACTION_DIGITS;
+  try {
+    const format = new Intl.NumberFormat('en', { style: 'currency', currency: currencyCode });
+    digits = format.resolvedOptions().maximumFractionDigits ?? DEFAULT_FRACTION_DIGITS;
+  } catch {
+    // A code Intl doesn't know (RangeError): see DEFAULT_FRACTION_DIGITS.
+  }
+  fractionDigitsByCurrency.set(currencyCode, digits);
+  return digits;
+}
+
+/** @returns The amount in the currency's smallest unit (cents, yen, fils), rounded to a whole one. */
+export function toMinorUnits(money: Money): number {
+  return Math.round(parseFloat(money.amount) * 10 ** currencyFractionDigits(money.currencyCode));
+}
+
+/** @returns The amount written with the currency's own number of digits. */
+export function fromMinorUnits(minorUnits: number, currencyCode: string): Money {
+  const digits = currencyFractionDigits(currencyCode);
+  return { amount: (minorUnits / 10 ** digits).toFixed(digits), currencyCode };
+}

package/src/analytics-shopify.ts

@@ -0,0 +1,246 @@
+/**
+ * Shopify's own analytics for the analytics part. 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 delivered before the Customer Privacy API allows analytics.
+ */
+import { cfg, log, reportError } from './config.ts';
+import { gql, shaped } from './client.ts';
+import type { AnalyticsConfig } from './config.ts';
+
+export type EventPayload = Record<string, unknown>;
+
+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;
+const CONSENT_SCRIPTS = {
+  'default-banner': 'https://cdn.shopify.com/shopifycloud/privacy-banner/storefront-banner.js',
+  other: 'https://cdn.shopify.com/shopifycloud/consent-tracking-api/v0.2/consent-tracking-api.js',
+};
+const ANALYTICS_SCRIPT = 'https://cdn.shopify.com/storefront/analytics/shopify.js';
+
+/** The page, where Shopify's scripts keep `window.Shopify` in the shape they define. */
+const page = (): Window & { Shopify?: ShopifyGlobal } => window;
+
+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 : {};
+}
+
+/**
+ * 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.
+ */
+function trackingAllowed(): boolean {
+  try {
+    const privacy = shopifyGlobal()?.customerPrivacy;
+    return (
+      privacy?.consentStatus === 'loaded' &&
+      privacy.currentVisitorConsent?.()?.analytics !== 'no' &&
+      Boolean(privacy.analyticsProcessingAllowed?.())
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** @param name The destination's name, Hydrogen tags its tokens with it. */
+function destinationContext(name: string): DestinationContext {
+  const tag = `hydrogen:${name}`;
+  return {
+    getTrackingValues: () => {
+      const internal = trackingAllowed() ? shopifyGlobal()?.customerPrivacy?.__internal : undefined;
+      return {
+        uniqueToken: internal?.uniqueToken?.({ generateFallback: true, tag }) ?? '',
+        visitToken: internal?.visitToken?.({ generateFallback: true, tag }) ?? '',
+      };
+    },
+  };
+}
+
+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);
+  };
+
+/** 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' },
+  };
+  const deliver = () => {
+    if (!trackingAllowed()) return;
+    for (const destination of destinations) {
+      for (; destination.next < buffer.length; destination.next += 1) {
+        const buffered = buffer[destination.next];
+        if (buffered) deliverTo(destination, buffered);
+      }
+    }
+  };
+  const bus: AnalyticsBus = {
+    getConfig: () => config,
+    publish(event, payload = {}) {
+      buffer.push({ event, payload: { shop: config.shop, url: window.location.href, ...payload } });
+      if (buffer.length > BUFFER_SIZE) {
+        buffer.shift();
+        for (const destination of destinations) destination.next = Math.max(0, destination.next - 1);
+      }
+      deliver();
+    },
+    addDestination(spec) {
+      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((error: unknown) => {
+          reportError(error, `analytics ${spec.name}`);
+        });
+      return () => {
+        const index = destinations.indexOf(destination);
+        if (index >= 0) destinations.splice(index, 1);
+      };
+    },
+  };
+  document.addEventListener('consentTrackingApiLoaded', deliver);
+  document.addEventListener('visitorConsentCollected', deliver);
+  return bus;
+}
+
+function deliverTo(destination: Destination, { event, payload }: BufferedEvent): void {
+  destination.subscribers.get(event)?.forEach((subscriber) => {
+    try {
+      subscriber(payload, destination.context);
+    } catch (error) {
+      reportError(error, `analytics ${destination.name}`);
+    }
+  });
+}
+
+function loadScript(src: string): void {
+  const script = document.createElement('script');
+  script.src = src;
+  script.async = true;
+  document.head.appendChild(script);
+}
+
+/**
+ * Sets up `window.Shopify` for Shopify's scripts and loads them.
+ *
+ * @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: () => boolean): Promise<AnalyticsBus> {
+  const existing = shopifyGlobal();
+  if (existing?.analytics) return existing.analytics;
+  const data = await gql(
+    'query TetherShopId { shop { id } }',
+    {},
+    shaped<{ shop: { id: string } }>({ shop: { id: 'string' } }),
+    { context: false },
+  );
+  const shopify = shopifyGlobal() ?? {};
+  page().Shopify = shopify;
+  shopify.country = cfg.country ?? 'US';
+  // Shopify's script requires a language, not a full locale.
+  const [language = 'en'] = (cfg.locale || 'en').split('-');
+  shopify.locale = language.toLowerCase();
+  shopify.shop = cfg.domain;
+  shopify.routes = {
+    root: '/',
+    match: () => ({ pageTemplateName: isProductPage() ? 'product' : 'page' }),
+    ...shopify.routes,
+  };
+  // A same-origin Storefront API path gives Shopify exact visitor counts.
+  const { proxy, consent } = shopifyOptions();
+  shopify.customerPrivacy = {
+    ...shopify.customerPrivacy,
+    config: proxy
+      ? { isHeadless: true, asyncConsent: true, asyncVisitorState: true, consentDomain: window.location.host }
+      : { isHeadless: true, storefrontAccessToken: cfg.token, checkoutRootDomain: cfg.domain },
+  };
+  const bus = createBus(data.shop.id);
+  shopify.analytics = bus;
+  loadScript(consent === 'default-banner' ? CONSENT_SCRIPTS['default-banner'] : CONSENT_SCRIPTS.other);
+  loadScript(ANALYTICS_SCRIPT);
+  log('shopify analytics ready', data.shop.id);
+  return bus;
+}