@occluze/tether 0.6.8 → 0.7.0

package/src/{markets-ui.js → markets-ui.ts}

@@ -1,38 +1,75 @@
 /**
- * Optional part, loaded on first use: market detection, `select[tether-country-select]`, `tether-country-bind` and
- * `Tether.setCountry()`. See markets.js for the detection rules.
+ * Optional part, loaded on first use: market detection, the store's countries (`Tether.getLocalization()`),
+ * `select[tether-country-select]`, `tether-country-bind` and `Tether.setCountry()`. See markets.ts for the detection
+ * rules.
  */
-import { cfg, reportError } from './config.js';
-import { TetherError } from './client.js';
-import { Cart } from './cart.js';
-import { listSelector } from './collection.js';
-import { clearProductCache } from './loader.js';
-import { attr, sel, get, emit } from './dom.js';
-import { within, pruneLive, liveLists, liveProducts, mountedProducts, mountProduct } from './mounting.js';
-import { rememberMarket, getLocalization, clearLocalization } from './markets.js';
-import { toCountry, toLanguage } from './market-codes.js';
-/** @import { LocalizedCountry, Localization } from './markets.js' */
-/** @import { CountryCode } from './market-codes.js' */
-
-export { detectMarket, getLocalization } from './markets.js';
+import { cfg, reportError } from './config.ts';
+import { gql, shaped, TetherError } from './client.ts';
+import { Cart } from './cart.ts';
+import { listSelector } from './collection.ts';
+import { clearProductCache } from './loader.ts';
+import { attr, sel, get, emit } from './dom.ts';
+import { within, pruneLive, liveLists, liveProducts, mountedProducts, mountProduct } from './mounting.ts';
+import { rememberMarket } from './markets.ts';
+import { toCountry, toLanguage } from './market-codes.ts';
+import type { LocalizedCountry, Localization } from './markets.ts';
+import type { CountryCode, LanguageCode } from './market-codes.ts';
+
+export { detectMarket } from './markets.ts';
 
 const DEFAULT_LABEL = '{name} ({currency})';
 const DEFAULT_BIND = 'name';
 
+let localizationPromise: Promise<Localization> | null = null;
+
+/** Forgets the cached localization, for when country names change language. */
+function clearLocalization(): void {
+  localizationPromise = null;
+}
+
+const LOCALIZATION_QUERY = `query TetherLocalization {
+  localization {
+    country { isoCode name currency { isoCode symbol } }
+    language { isoCode name }
+    availableCountries { isoCode name currency { isoCode symbol } availableLanguages { isoCode name } }
+  }
+}`;
+
+/** A country with the code, name and currency the country select and binds read. */
+const COUNTRY = { isoCode: 'string', name: 'string', currency: 'object' } as const;
+const isLocalizationAnswer = shaped<{ localization: Localization }>({
+  localization: { country: COUNTRY, availableCountries: [COUNTRY] },
+});
+
 /**
- * @typedef {object} SetCountryOptions
- * @property {string | null | undefined} [language] A Shopify language; `null` clears it. Default: the
- *   `markets.locales` entry for the country, else unchanged.
- * @property {string | undefined} [locale] The money format. Default: the `markets.locales` entry, else unchanged.
- * @property {boolean | undefined} [remember] Save the choice for the next pages (default true).
+ * The countries the store sells to (Shopify Markets), with their currency. Cached per page; a failed request is not
+ * cached, so the next call tries again.
  */
+export function getLocalization(): Promise<Localization> {
+  localizationPromise ??= gql(LOCALIZATION_QUERY, {}, isLocalizationAnswer).then(
+    (data) => data.localization,
+    (error: unknown) => {
+      localizationPromise = null;
+      throw error;
+    },
+  );
+  return localizationPromise;
+}
+
+interface SetCountryOptions {
+  /** A Shopify language; `null` clears it. Default: the `markets.locales` entry for the country, else unchanged. */
+  language?: string | null | undefined;
+  /** The money format. Default: the `markets.locales` entry, else unchanged. */
+  locale?: string | undefined;
+  /** Save the choice for the next pages (default true). */
+  remember?: boolean | undefined;
+}
 
 /**
- * @param {LocalizedCountry} country
- * @param {string} field A `tether-country-bind` value or a label placeholder: `name`, `code`, `currency`, `symbol`.
- * @returns {string} `''` for any other field.
+ * @param field A `tether-country-bind` value or a label placeholder: `name`, `code`, `currency`, `symbol`.
+ * @returns `''` for any other field.
  */
-function countryField(country, field) {
+function countryField(country: LocalizedCountry, field: string): string {
   switch (field) {
     case 'name':
       return country.name;
@@ -47,21 +84,15 @@ function countryField(country, field) {
   }
 }
 
-/**
- * @param {string} template `tether-country-label`, e.g. `{name} ({currency})`.
- * @param {LocalizedCountry} country
- */
-const fillLabel = (template, country) =>
-  template.replace(/\{(name|code|currency|symbol)\}/g, (_match, /** @type {string} */ field) =>
-    countryField(country, field),
-  );
+/** @param template `tether-country-label`, e.g. `{name} ({currency})`. */
+const fillLabel = (template: string, country: LocalizedCountry) =>
+  template.replace(/\{(name|code|currency|symbol)\}/g, (_match, field: string) => countryField(country, field));
 
 /**
- * @param {HTMLSelectElement} select
- * @param {LocalizedCountry[]} countries The store's countries, sorted by name.
- * @param {string} current The country in use.
+ * @param countries The store's countries, sorted by name.
+ * @param current The country in use.
  */
-function fillCountrySelect(select, countries, current) {
+function fillCountrySelect(select: HTMLSelectElement, countries: LocalizedCountry[], current: string): void {
   const template = select.getAttribute(attr('country-label')) || DEFAULT_LABEL;
   // tether-countries="NL,DE,BE": only these, in that order; otherwise every country of the store.
   const only = (select.getAttribute(attr('countries')) || '')
@@ -80,12 +111,7 @@ function fillCountrySelect(select, countries, current) {
   select.disabled = listed.length < 2 && !select.hasAttribute(attr('always-enabled'));
 }
 
-/**
- * @param {HTMLSelectElement[]} selects
- * @param {HTMLElement[]} binds
- * @param {Localization} localization
- */
-function fillCountries(selects, binds, localization) {
+function fillCountries(selects: HTMLSelectElement[], binds: HTMLElement[], localization: Localization): void {
   const current = (cfg.country || localization.country.isoCode).toUpperCase();
   const countries = [...localization.availableCountries].sort((a, b) =>
     a.name.localeCompare(b.name, cfg.locale || undefined),
@@ -103,36 +129,34 @@ function fillCountries(selects, binds, localization) {
  * Fills `select[tether-country-select]` with the countries the store sells to (Shopify Markets), and
  * `tether-country-bind="name|code|currency|symbol"` with the current country. `tether-country-label` sets the option
  * text from `{name}`, `{code}`, `{currency}` and `{symbol}`. A failure is reported, never thrown.
- *
- * @param {ParentNode} [root]
- * @returns {Promise<void>}
  */
-export function renderCountrySelects(root = document) {
-  const selects = /** @type {HTMLSelectElement[]} */ (within(root, `select${sel('country-select')}`));
+export function renderCountrySelects(root: ParentNode = document): Promise<void> {
+  // The selector matches `select` elements only.
+  const selects = within(root, `select${sel('country-select')}`) as HTMLSelectElement[];
   const binds = within(root, sel('country-bind'));
   if (!selects.length && !binds.length) return Promise.resolve();
   return getLocalization()
     .then((localization) => {
       fillCountries(selects, binds, localization);
     })
-    .catch((/** @type {unknown} */ error) => {
+    .catch((error: unknown) => {
       reportError(error, 'country select');
     });
 }
 
-/**
- * @param {CountryCode} country
- * @returns {{ country?: string, language?: string, locale?: string } | undefined} The `markets.locales` entry for it.
- */
-const localeEntryFor = (country) =>
+/** The `markets.locales` entry for `country`. */
+const localeEntryFor = (country: CountryCode) =>
   Object.values(cfg.markets?.locales ?? {}).find((entry) => toCountry(entry.country) === country);
 
 /**
- * @param {string | null | undefined} language The `setCountry()` option.
- * @param {{ language?: string } | undefined} entry The `markets.locales` entry for the country.
- * @returns {string | null | undefined} The option, else the entry's language (which may have none), else unchanged.
+ * @param language The `setCountry()` option.
+ * @param entry The `markets.locales` entry for the country.
+ * @returns The option, else the entry's language (which may have none), else unchanged.
  */
-function languageFor(language, entry) {
+function languageFor(
+  language: string | null | undefined,
+  entry: { language?: string } | undefined,
+): LanguageCode | null | undefined {
   if (language !== undefined) return toLanguage(language);
   if (!entry) return cfg.language;
   return entry.language ? toLanguage(entry.language) : undefined;
@@ -141,17 +165,15 @@ function languageFor(language, entry) {
 /**
  * Loads every live product and list again in the market `cfg` now holds, and moves an existing cart to `country`.
  *
- * @param {CountryCode} country
- * @returns {Promise<unknown>[]} The cart update and the list loads.
+ * @returns The cart update and the list loads.
  */
-function rerenderInMarket(country) {
+function rerenderInMarket(country: CountryCode): Promise<unknown>[] {
   clearProductCache();
-  /** @type {Promise<unknown>[]} */
-  const jobs = [];
+  const jobs: Promise<unknown>[] = [];
   // Only an existing cart moves; switching country never creates one.
   if (Cart.id()) {
     jobs.push(
-      Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((/** @type {unknown} */ error) => {
+      Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((error: unknown) => {
         reportError(error, 'cart country');
       }),
     );
@@ -173,19 +195,20 @@ function rerenderInMarket(country) {
  *
  *   Tether.setCountry('DE')            Tether.setCountry('BE', { language: 'FR' })
  *
- * @param {string} code
- * @param {SetCountryOptions} [options]
- * @returns {Promise<typeof Cart.state>} The cart once everything is in the new market.
+ * @returns The cart once everything is in the new market.
  * @throws {TetherError} `INVALID_COUNTRY` for anything that isn't a country code.
  */
-export async function setCountry(code, { language, locale, remember = true } = {}) {
+export async function setCountry(
+  code: string,
+  { language, locale, remember = true }: SetCountryOptions = {},
+): Promise<typeof Cart.state> {
   const country = toCountry(code);
   if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
   const entry = localeEntryFor(country);
   const ownLocale = locale || entry?.locale;
   const nextLocale = ownLocale || cfg.locale;
   const nextLanguage = languageFor(language, entry);
-  const changed = country !== cfg.country?.toUpperCase() || nextLanguage !== cfg.language || nextLocale !== cfg.locale;
+  const changed = country !== cfg.country || nextLanguage !== cfg.language || nextLocale !== cfg.locale;
   cfg.country = country;
   cfg.language = nextLanguage || undefined;
   cfg.locale = nextLocale;

package/src/markets.ts

@@ -0,0 +1,246 @@
+/**
+ * Markets: which country and language prices, currency and translations follow.
+ *
+ *   markets: {
+ *     detect: true,                       // or a list: ['saved', 'server', 'webflow']
+ *     locales: {                          // Webflow Localization: locale subdirectory or <html lang>
+ *       de: { country: 'DE', language: 'DE', locale: 'de-DE' },
+ *       'fr-be': { country: 'BE', language: 'FR' },
+ *     },
+ *     cookie: 'tether_country',           // a cookie your server or Worker sets (from cf-ipcountry)
+ *     remember: true,                     // keep the visitor's tether-country-select choice
+ *   }
+ *
+ * Sources, first match wins per field:
+ *   saved   the visitor's own choice (localStorage), from tether-country-select / Tether.setCountry()
+ *   server  window.TETHER_COUNTRY, <meta name="tether-country" content="DE">, or the cookie
+ *   webflow locale subdirectory (/de/...) or <html lang="de-DE">, through `locales`
+ * then the static `country` / `language` config. Without `detect`, only `saved` applies, so a country select keeps
+ * working across pages; `detect: false` turns even that off. Tether never calls an IP lookup service: a country from
+ * the visitor's IP only comes from the site's own server (see README).
+ */
+import { MARKET_SOURCES, cfg, parseMarkets } from './config.ts';
+import { toCountry, toLanguage } from './market-codes.ts';
+import { getStored, setStored } from './storage.ts';
+import type { MarketsConfig } from './config.ts';
+import type { CountryCode, LanguageCode } from './market-codes.ts';
+
+/** A market a visitor chose, as `setCountry()` stores it. */
+export interface Market {
+  country: CountryCode;
+  language: LanguageCode | undefined;
+  /** An `Intl` locale for money and dates. */
+  locale: string | undefined;
+}
+
+export type MarketSource = 'saved' | 'server' | 'webflow';
+type MarketField = 'country' | 'language' | 'locale';
+type MarketSources = Partial<Record<MarketField, MarketSource>>;
+
+/** The fields detection found, and the source each came from. */
+export interface DetectedMarket {
+  country?: CountryCode;
+  language?: LanguageCode;
+  locale?: string;
+  /** Absent when `detect: false` turns detection off. */
+  sources?: MarketSources;
+}
+
+/** What detection reads, passed in so it runs on any document. */
+interface MarketEnv {
+  document: Pick<Document, 'cookie' | 'querySelector' | 'documentElement'> | null;
+  location: Pick<Location, 'pathname'> | null;
+  /** `localStorage`, read through `getStored`, which finds nothing where the browser blocks it. */
+  storage: Pick<Storage, 'getItem'>;
+  /** Where `TETHER_COUNTRY` and `TETHER_LANGUAGE` are read from (`window`). */
+  global: object;
+}
+
+/** A source's raw values. */
+interface MarketHint {
+  country?: unknown;
+  language?: unknown;
+  locale?: unknown;
+}
+
+interface NamedCode {
+  isoCode: string;
+  name: string;
+}
+
+interface Currency {
+  isoCode: string;
+  symbol: string;
+}
+
+export type LocalizedCountry = NamedCode & { currency: Currency };
+
+/** The store's markets, from the Storefront API's `localization`. */
+export interface Localization {
+  /** The country of the current `@inContext`. */
+  country: LocalizedCountry;
+  language: NamedCode;
+  availableCountries: (LocalizedCountry & { availableLanguages: NamedCode[] })[];
+}
+
+const DEFAULT_COOKIE = 'tether_country';
+
+/** The localStorage key of the visitor's market: `<prefix>:market:<domain>`. */
+export const storageKey = (): string => `${cfg.prefix}:market:${cfg.domain}`;
+
+const pageStorage: Pick<Storage, 'getItem'> = { getItem: (key) => getStored(key) };
+
+/** The page this script runs on. */
+function pageEnv(): MarketEnv {
+  const hasWindow = typeof window !== 'undefined';
+  return {
+    document: typeof document !== 'undefined' ? document : null,
+    location: hasWindow ? window.location : null,
+    storage: pageStorage,
+    global: hasWindow ? window : {},
+  };
+}
+
+/** The JSON value of `text`, `null` for text that isn't JSON (a key another script wrote). */
+function parseJsonOrNull(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+
+/** `value` as a market, when it has a valid country. A language or locale that isn't valid is left out. */
+function toMarket(value: unknown): Market | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const country = toCountry(Reflect.get(value, 'country'));
+  if (!country) return null;
+  const locale: unknown = Reflect.get(value, 'locale');
+  return {
+    country,
+    language: toLanguage(Reflect.get(value, 'language')) ?? undefined,
+    locale: typeof locale === 'string' && locale ? locale : undefined,
+  };
+}
+
+/**
+ * The visitor's saved market (`setCountry()`, `tether-country-select`), validated: storage is written by other tabs,
+ * older versions and other scripts too.
+ *
+ * @param storage Default `localStorage`.
+ * @returns `null` when nothing valid is saved.
+ */
+export function readSavedMarket(storage: Pick<Storage, 'getItem'> = pageStorage): Market | null {
+  const text = storage.getItem(storageKey());
+  return text ? toMarket(parseJsonOrNull(text)) : null;
+}
+
+function readCookie(doc: Pick<Document, 'cookie'> | null, name: string): string | null {
+  if (!doc || !name) return null;
+  const cookie = doc.cookie
+    .split(';')
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${name}=`));
+  return cookie ? decodeURIComponent(cookie.slice(name.length + 1)) : null;
+}
+
+/** The entry of `locales` for `key`, ignoring case. */
+function lookupLocale(locales: MarketsConfig['locales'], key: string | undefined): MarketHint | null {
+  if (!locales || !key) return null;
+  const wanted = key.toLowerCase();
+  const found = Object.keys(locales).find((name) => name.toLowerCase() === wanted);
+  return found ? (locales[found] ?? null) : null;
+}
+
+function readServerHint(markets: MarketsConfig, env: MarketEnv): MarketHint {
+  const meta = (name: string) => env.document?.querySelector(`meta[name="${name}"]`)?.getAttribute('content');
+  const globalCountry: unknown = Reflect.get(env.global, 'TETHER_COUNTRY');
+  const globalLanguage: unknown = Reflect.get(env.global, 'TETHER_LANGUAGE');
+  const pageCountry = meta('tether-country') || readCookie(env.document, markets.cookie || DEFAULT_COOKIE);
+  return {
+    country: globalCountry || pageCountry,
+    language: globalLanguage || meta('tether-language'),
+  };
+}
+
+function readWebflowLocale(markets: MarketsConfig, env: MarketEnv): MarketHint | null {
+  const segment = (env.location?.pathname ?? '/').split('/').find((part) => part !== '');
+  const fromPath = lookupLocale(markets.locales, segment);
+  if (fromPath) return fromPath;
+  const lang = env.document?.documentElement.getAttribute('lang');
+  if (!lang) return null;
+  const mapped = lookupLocale(markets.locales, lang) ?? lookupLocale(markets.locales, lang.split('-')[0]);
+  if (mapped) return { locale: lang, ...mapped };
+  if (markets.locales && markets.strict) return null;
+  // Unmapped: the language from <html lang>, a country only from a region subtag (de-CH -> CH).
+  const region = lang.split('-')[1];
+  return { language: lang, country: region?.length === 2 ? region : null, locale: lang };
+}
+
+function readSource(source: MarketSource, markets: MarketsConfig, env: MarketEnv): MarketHint | null {
+  switch (source) {
+    case 'saved':
+      return markets.remember === false ? null : readSavedMarket(env.storage);
+    case 'server':
+      return readServerHint(markets, env);
+    case 'webflow':
+      return readWebflowLocale(markets, env);
+  }
+}
+
+/**
+ * @param detect Validated: a list holds only known sources.
+ * @returns Without `detect`, only the visitor's own choice from a country select.
+ */
+function sourcesFor(detect: MarketsConfig['detect']): readonly MarketSource[] {
+  if (!detect) return ['saved'];
+  return detect === true ? MARKET_SOURCES : detect;
+}
+
+/**
+ * The market the page's sources point to. Reads the DOM and storage only, so it can run on any `env`.
+ *
+ * @returns Only the fields found; `{}` with `detect: false`.
+ */
+export function detectMarket(
+  markets: MarketsConfig | null | undefined = cfg.markets,
+  env: MarketEnv = pageEnv(),
+): DetectedMarket {
+  // The config's own `markets` was validated by `configure()`; one passed in by the site's code is validated here.
+  const config = (markets === cfg.markets ? markets : parseMarkets(markets)) ?? {};
+  if (config.detect === false) return {};
+  const sources: MarketSources = {};
+  const found: DetectedMarket = { sources };
+  for (const source of sourcesFor(config.detect)) {
+    const hint = readSource(source, config, env);
+    if (!hint) continue;
+    const country = toCountry(hint.country);
+    const language = toLanguage(hint.language);
+    const locale = typeof hint.locale === 'string' && hint.locale ? hint.locale : null;
+    if (country && !found.country) {
+      found.country = country;
+      sources.country = source;
+    }
+    if (language && !found.language) {
+      found.language = language;
+      sources.language = source;
+    }
+    if (locale && !found.locale) {
+      found.locale = locale;
+      sources.locale = source;
+    }
+  }
+  return found;
+}
+
+/** Saves the visitor's choice for the next pages, unless `markets.remember` is false. */
+export function rememberMarket(market: {
+  country: CountryCode;
+  language?: string | null | undefined;
+  locale?: string | null | undefined;
+}): void {
+  if (cfg.markets?.remember === false) return;
+  const saved = { country: market.country, language: market.language || undefined, locale: market.locale || undefined };
+  setStored(storageKey(), JSON.stringify(saved));
+}

package/src/markup.ts

@@ -0,0 +1,127 @@
+/**
+ * How Tether finds its markup: attribute names carry the configured prefix (`tether-product`, or `wfs-product` with
+ * `prefix: 'wfs'`), and so do the selectors and the DOM events built from them.
+ */
+import { cfg } from './config.ts';
+import type { ShopifyCart } from './cart/store.ts';
+import type { CartLineInput } from './cart/mutations.ts';
+import type { CartWarning } from './config.ts';
+import type { Product, ProductVariant } from './fragments.ts';
+import type { Collection } from './loader.ts';
+import type { ProductScope } from './product.ts';
+import type { Purchase } from './product-state.ts';
+import type { SearchResults } from './search.ts';
+
+/** @returns The prefixed attribute name: `product` → `tether-product`. */
+export const attr = (name: string): string => `${cfg.prefix}-${name}`;
+
+/** @returns A selector for the attribute, with that exact value when given. */
+export const sel = (name: string, value?: string): string =>
+  value === undefined ? `[${attr(name)}]` : `[${attr(name)}="${value}"]`;
+
+export const get = (el: Element, name: string): string | null => el.getAttribute(attr(name));
+
+export const has = (el: Element, name: string): boolean => el.hasAttribute(attr(name));
+
+/**
+ * Tether's attributes go on HTML elements, so matches are typed as such. An SVG element that carries one still has
+ * the `style`, `dataset` and attribute methods Tether uses.
+ *
+ * @returns The matches in `root`, none without a root.
+ */
+export function qsa(root: ParentNode | null | undefined, selector: string): HTMLElement[] {
+  if (!root) return [];
+  return [...root.querySelectorAll<HTMLElement>(selector)];
+}
+
+/** @returns Matches in `root` whose nearest `scopeSelector` ancestor is `root` itself, not a nested scope. */
+export const scoped = (root: Element | null | undefined, selector: string, scopeSelector: string): HTMLElement[] =>
+  qsa(root, selector).filter((el) => el.closest(scopeSelector) === root);
+
+/**
+ * The events Tether dispatches, as `<prefix>:<name>` (`tether:cart-updated`), bubbling up to `document`, with the
+ * detail each carries. `emit` takes only these, and `Tether.on()` passes on only the events `emit` dispatched, so a listener gets the
+ * detail its event really has.
+ */
+export interface TetherEvents {
+  ready: { cart: ShopifyCart | null };
+  'product-ready': { product: Product; scope: ProductScope };
+  'product-updated': { product: Product; scope: ProductScope };
+  /** `key` is null when the scope names no product; `source` is what it named. */
+  'product-not-found': { key: string | null; source: string };
+  'variant-changed': {
+    product: Product;
+    variant: ProductVariant;
+    selected: Record<string, string>;
+    purchase: Purchase['kind'];
+    sellingPlanId: string | null;
+  };
+  'product-added': { product: Product; variant: ProductVariant; line: CartLineInput };
+  added: { cart: ShopifyCart; lines: CartLineInput[] };
+  'group-added': { group: string | null; lines: CartLineInput[] };
+  'cart-warning': { warnings: readonly CartWarning[] };
+  'cart-updated': { cart: ShopifyCart | null; reason: string };
+  'cart-toggled': { open: boolean };
+  'cart-error': { error: unknown };
+  checkout: { url: string; cart: ShopifyCart | null };
+  'list-ready': { products: Product[]; collection: Collection | null };
+  /** A list's cards were drawn (again): `container` holds them. */
+  'list-rendered': { container: Element };
+  /** The search part's suggestions for `term`. */
+  search: SearchResults & { term: string };
+  'country-changed': { country: string; language: string | undefined };
+  'discount-applied': { code: string };
+  'discount-invalid': { code: string };
+  'layout-changed': { reason: string };
+  error: { error: unknown; context: string; key?: string | null };
+  'account-login': Record<string, never>;
+  'account-logout': Record<string, never>;
+  /** A login that failed: `expired` (it took too long, or came back to another browser) or `error`. */
+  'account-error': { error: 'expired' | 'error' };
+  'account-updated': { what: 'profile' | 'addresses' | 'subscriptions' | 'orders' };
+}
+
+/** The events the analytics part reports, which the core buffers from `init()` until the part has loaded. */
+export const ANALYTICS_EVENTS = [
+  'product-ready',
+  'list-ready',
+  'cart-updated',
+  'cart-toggled',
+  'checkout',
+  'search',
+] as const satisfies readonly (keyof TetherEvents)[];
+
+export type AnalyticsEventName = (typeof ANALYTICS_EVENTS)[number];
+
+/**
+ * The events Tether created, with the name each was created under. Any script can dispatch a `<prefix>:<name>` event
+ * with any detail; only an event in here carries the detail `TetherEvents` gives its name.
+ */
+const ownEvents = new WeakMap<Event, keyof TetherEvents>();
+
+/** @returns The bubbling event `<prefix>:<name>`, known to `isOwnEvent`. */
+export function ownEvent<Name extends keyof TetherEvents>(
+  name: Name,
+  detail: TetherEvents[Name],
+): CustomEvent<TetherEvents[Name]> {
+  const event = new CustomEvent(`${cfg.prefix}:${name}`, { detail, bubbles: true });
+  ownEvents.set(event, name);
+  return event;
+}
+
+/** @returns True for an event `ownEvent` created as `name`, false for any other, such as one another script dispatched. */
+export function isOwnEvent<Name extends keyof TetherEvents>(
+  event: Event,
+  name: Name,
+): event is CustomEvent<TetherEvents[Name]> {
+  return ownEvents.get(event) === name;
+}
+
+/** Dispatches the bubbling event `<prefix>:<name>`. */
+export function emit<Name extends keyof TetherEvents>(
+  name: Name,
+  detail: TetherEvents[Name],
+  target: EventTarget = document,
+): void {
+  target.dispatchEvent(ownEvent(name, detail));
+}