@luigisbox/luma 0.1.0 → 0.2.0

package/src/analytics/chain.ts

@@ -0,0 +1,137 @@
+// The builder: `collect.<event>.on(trigger).when(f).throttle(ms).once().read(r)`.
+// A chain is registered as the setup file runs and listens once the page is
+// shown. `.read()` turns the trigger's context into what the event sends: a
+// function of the integration's, or a reader (./from-ga4.ts, ./from-luma.ts),
+// which is a function tagged with the one event it reads for. Where Luma runs
+// that service of the site's on the page (`owns`: our search page, our
+// autocomplete, our recommender of that name), its chain does nothing: theirs
+// is not on the page, ours is tracked by the API.
+
+import { reportError } from '../core/health';
+import { onPage } from './page';
+import { origin } from './outbox';
+import { env, whenShown } from './setup';
+
+/** When a chain's `.read()` runs, and with what (./triggers.ts). */
+export interface Trigger<C = any> {
+  key: string;
+  sub(h: (ctx: C) => void): void;
+}
+
+/** The events a setup collects (`collect.<event>`), as readers name them. */
+export type EventName = 'pageView' | 'click' | 'addToCart' | 'purchase' | 'search' | 'autocomplete' | 'recommender';
+
+/** One add-to-cart: what `collect.addToCart` sends (or a list of them). */
+export interface AddToCart {
+  reference: string;
+  count?: number;
+  price?: number;
+}
+/** A purchase: what `collect.purchase` sends, once per `id`. */
+export interface Purchase {
+  id?: string | number;
+  currency?: string;
+  items: { reference: string; title: string; count: number; total_price: number; was_discounted?: boolean }[];
+}
+/** A list of the site's own service (`collect.search`, `.autocomplete`, `.recommender(name)`). */
+export interface List {
+  query?: { string: string };
+  items: { title?: string; type?: string; reference?: string; position?: number; price?: number; [k: string]: unknown }[];
+  filters?: Record<string, unknown>;
+}
+/** What `.read()` returns, per event (null or undefined: nothing sent). */
+export interface Reads {
+  pageView: string | null | undefined;
+  click: string | { reference: string };
+  addToCart: AddToCart | AddToCart[];
+  purchase: Purchase;
+  search: List;
+  autocomplete: List;
+  recommender: List;
+}
+
+/**
+ * What `.read()` takes for event `E` on context `C`: a function of the
+ * setup's, or a reader of that event (`event`: a reader for another event is
+ * a type error, and an error as the setup runs).
+ */
+export type Read<E extends EventName, C> = ((ctx: C) => Reads[E] | null | undefined) & { event?: E };
+
+/** A reader: `f` for event `event` (its own function: readers may share `f`). Pure: one the setup does not name is left out of the build. */
+export const reader = <E extends EventName, C>(event: E, f: (ctx: C) => Reads[E] | null | undefined) => Object.assign((ctx: C) => f(ctx), { event }) as Read<E, C> & { event: E };
+
+/** `.read(r)` on event `name`: `r`, or an error when it is a reader of another event. */
+export const checked = (name: string, r: { event?: string }) => {
+  const e = name.startsWith('recommender:') ? 'recommender' : name;
+  if (r.event && r.event !== e) throw new Error(`analytics: collect.${e}.read(): a reader of ${r.event}`);
+};
+
+export interface Chain<E extends EventName, C> {
+  /** Only when `f` says so. */
+  when(f: (ctx: C) => boolean): Chain<E, C>;
+  /** At most once per `ms` (the rest dropped). */
+  throttle(ms: number): Chain<E, C>;
+  /** Once per page. */
+  once(): Chain<E, C>;
+  /** What the event sends, read from the trigger's context (null: nothing). */
+  read(r: Read<E, C>): void;
+}
+export interface Surface<E extends EventName> {
+  on<C>(t: Trigger<C>): Chain<E, C>;
+}
+
+/** An event of the site's: `deliver` sends what a chain's `.read()` made. */
+export const surface = <E extends EventName>(name: string, deliver: (p: Reads[E]) => void): Surface<E> => ({
+  on<C>(trigger: Trigger<C>) {
+    let when: ((ctx: C) => boolean) | undefined;
+    let once = false;
+    let every = 0;
+    let last = 0;
+    const b: Chain<E, C> = {
+      when(f) {
+        when = f;
+        return b;
+      },
+      throttle(ms) {
+        every = ms;
+        return b;
+      },
+      once() {
+        once = true;
+        return b;
+      },
+      read(r) {
+        checked(name, r);
+        let fired = false;
+        if (once) onPage(() => (fired = false));
+        whenShown(() =>
+          trigger.sub((ctx) => {
+            if (fired || env.owns(name)) return;
+            if (every) {
+              if (Date.now() - last < every) return;
+              last = Date.now();
+            }
+            try {
+              if (when && !when(ctx)) return;
+              const p = r(ctx);
+              if (p == null) return;
+              fired = once;
+              // A context from earlier (`at`: queued, or kept by the last page) is sent as of then and there.
+              const c = ctx as { url?: string; at?: number };
+              origin.url = typeof c?.at === 'number' ? c.url : undefined;
+              origin.at = typeof c?.at === 'number' ? c.at : undefined;
+              try {
+                deliver(p);
+              } finally {
+                origin.url = origin.at = undefined;
+              }
+            } catch (e) {
+              reportError(`analytics ${name}`, e);
+            }
+          }),
+        );
+      },
+    };
+    return b;
+  },
+});

package/src/analytics/collect.ts

@@ -0,0 +1,64 @@
+// The events (`collect.<event>` in _analytics.ts): each its own export, so a
+// setup brings only those it uses. What each sends:
+// - pageView: `pv` per page (./pageview.ts);
+// - search, autocomplete, recommender(name): a `list` event of the site's own
+//   service (`{ query?, items, filters? }`; ours the API records itself);
+// - click: an `interaction` click (a reference, or `{ reference }`);
+// - addToCart: `interaction` add_to_cart per item (`{ reference, count?, price? }` or a list);
+// - purchase: a `transaction` (`{ id?, currency?, items }`), once per id.
+
+import { emit } from './outbox';
+import { state } from './setup';
+import { surface, type AddToCart, type List, type Purchase } from './chain';
+import { isRef } from './wire';
+
+export { pageView } from './pageview';
+
+/** On an add-to-cart our tiles made (fromLuma.addToCart): the site's own push its cart then makes is the same one. */
+export const OURS = '__lbxOurs';
+
+const list = (name: string) => (p: List) => Array.isArray(p?.items) && emit({ type: 'list', list_name: name, listing_ab_test: false, ...p });
+
+/** The site's own search results: a `list` event. */
+export const search = /* @__PURE__ */ surface<'search'>('search', /* @__PURE__ */ list('Search'));
+/** The site's own suggestions: a `list` event. */
+export const autocomplete = /* @__PURE__ */ surface<'autocomplete'>('autocomplete', /* @__PURE__ */ list('Autocomplete'));
+/** The site's own recommender `name` (silent where ours of that name runs): a `list` event. */
+export const recommender = (name: string) => surface<'recommender'>(`recommender:${name}`, list('Recommendation'));
+
+/** A product click: the reference (or `{ reference }`). */
+export const click = /* @__PURE__ */ surface<'click'>('click', (p) => {
+  const reference = typeof p === 'string' ? p : p?.reference;
+  if (isRef(reference)) emit({ type: 'interaction', interaction_type: 'click', listing_ab_test: false, reference });
+});
+
+const currency = () => state.g?.currency;
+/** When the last add-to-cart on our tiles was: the site's own push its cart then makes is the same one. */
+let ourCart = 0;
+const OUR_CART_MS = 10_000;
+/** Add-to-cart: `{ reference, count?, price? }` or a list of them. */
+export const addToCart = /* @__PURE__ */ surface<'addToCart'>('addToCart', (p) => {
+  const all: (AddToCart & { [OURS]?: true })[] = Array.isArray(p) ? p : [p];
+  if (all.some((x) => x?.[OURS])) ourCart = Date.now();
+  else if (Date.now() - ourCart < OUR_CART_MS) return void (ourCart = 0);
+  for (const x of all) {
+    if (!isRef(x?.reference)) continue;
+    emit({ type: 'interaction', interaction_type: 'add_to_cart', listing_ab_test: false, reference: x.reference, ...(x.count ? { count: x.count } : {}), ...(x.price != null && x.price >= 0 ? { price: x.price } : {}), ...(currency() ? { currency: currency() } : {}) });
+  }
+});
+
+const TX = 'lbx:tx';
+const seenTx = (id: string) => {
+  try {
+    const ids: string[] = JSON.parse(localStorage.getItem(TX) ?? '[]');
+    if (ids.includes(id)) return true;
+    localStorage.setItem(TX, JSON.stringify([...ids, id].slice(-20)));
+  } catch {}
+  return false;
+};
+/** A purchase: `{ id?, currency?, items: [{ reference, title, count, total_price }] }`, once per id (a reloaded thank-you page keeps its push). */
+export const purchase = /* @__PURE__ */ surface<'purchase'>('purchase', (p: Purchase) => {
+  if (!Array.isArray(p.items) || !p.items.length || (p.id != null && seenTx(String(p.id)))) return;
+  const cur = p.currency ?? currency();
+  emit({ type: 'transaction', listing_ab_test: false, items: p.items, ...(cur ? { currency: cur } : {}) });
+});

package/src/analytics/datalayer.ts

@@ -0,0 +1,67 @@
+// The site's dataLayer (`_global.dataLayer`, default `dataLayer`), for the
+// `dl()` trigger: its push wrapped once (any push already there, GTM's,
+// chained), and what was pushed before we were here read too: on this page,
+// and on pages left before analytics ran there (the entry keeps their pushes,
+// `lbx:dl`: replayed first, as of their page and time).
+
+import { reportError } from '../core/health';
+import { session } from '../core/storage';
+import { KEPT } from '../core/kept';
+import { env, state } from './setup';
+import { readDl, type DlEntry } from './wire';
+
+const handlers = new Set<(e: DlEntry) => void>();
+const layer = (): any[] => {
+  const w = window as any;
+  const name = state.g?.dataLayer ?? 'dataLayer';
+  return Array.isArray(w[name]) ? w[name] : (w[name] = []);
+};
+/** Pushes of pages left before analytics ran (main.ts): read once, then gone from storage. */
+interface Kept {
+  /** The page. */
+  u: string;
+  /** When it was left. */
+  t: number;
+  /** Its pushes. */
+  e: unknown[];
+}
+let kept: Kept[] | null = null;
+const heard = (x: any) => {
+  const e = readDl(x);
+  if (e)
+    for (const h of handlers)
+      try {
+        h(e);
+      } catch (err) {
+        reportError(`analytics ${e.event}`, err);
+      }
+};
+
+/** The site's dataLayer event `name` (object or gtag form) from now on, and what was pushed before. */
+export const onDl = (name: string, h: (e: DlEntry) => void) => {
+  const dl = layer();
+  if (!(dl as any).__lbx) {
+    const prev = Object.prototype.hasOwnProperty.call(dl, 'push') ? dl.push : null;
+    dl.push = function (...items: any[]) {
+      const n = prev ? prev.apply(dl, items) : Array.prototype.push.apply(dl, items);
+      for (const x of items) heard(x);
+      return n;
+    };
+    (dl as any).__lbx = true;
+  }
+  const f = (e: DlEntry) => e.event === name && h(e);
+  handlers.add(f);
+  if (!kept) {
+    kept = session.get<Kept[]>(KEPT) ?? [];
+    session.set(KEPT, undefined);
+  }
+  for (const k of kept)
+    for (const x of k.e) {
+      const e = readDl(x);
+      if (e) f({ ...e, url: k.u, at: k.t });
+    }
+  for (const x of dl.slice(env.kept())) {
+    const e = readDl(x);
+    if (e) f(e);
+  }
+};

package/src/analytics/from-ga4.ts

@@ -0,0 +1,68 @@
+// Readers of the site's GA4 ecommerce (`.read(fromGa4.<event>)`), one export
+// each: a setup brings only those it names.
+//
+//   collect.addToCart.on(dl('add_to_cart')).read(fromGa4.addToCart);
+//   collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
+//   collect.click.on(dl('select_item')).read(fromGa4.click);
+//   collect.pageView.on(dl('view_item')).read(fromGa4.pageView);
+//   collect.search.on(dl('view_item_list')).read(fromGa4.search);
+//
+// The ecommerce is the push's `ecommerce` (GTM; gtag's parameters, as dl()
+// hands them), else the push itself when its `items` are on it. Items are
+// referenced by `ref.product(item_id)` (ref.product.by() for the field).
+
+import { reader, type AddToCart, type List } from './chain';
+import { ref } from './ref';
+
+interface Ctx {
+  data?: Record<string, any>;
+  ecommerce?: Record<string, any> | null;
+}
+const ecommerceOf = (ctx: Ctx): Record<string, any> => (ctx.ecommerce?.items ? ctx.ecommerce : ctx.data?.items ? ctx.data : (ctx.ecommerce ?? ctx.data ?? {}));
+/** Its items with an id (one without: no reference, not sent). */
+const itemsOf = (ctx: Ctx): Record<string, any>[] => {
+  const items = ecommerceOf(ctx).items;
+  return Array.isArray(items) ? items.filter((i) => i?.item_id != null) : [];
+};
+const num = (x: unknown) => {
+  const n = typeof x === 'string' ? Number(x.replace(',', '.')) : x;
+  return typeof n === 'number' && Number.isFinite(n) ? n : undefined;
+};
+const count = (x: unknown) => Math.max(1, Math.round(num(x) ?? 1));
+const product = (i: Record<string, any>) => ref.product(String(i.item_id));
+const first = (ctx: Ctx) => {
+  const [i] = itemsOf(ctx);
+  return i ? product(i) : null;
+};
+const list = (ctx: Ctx): List | null => {
+  const e = ecommerceOf(ctx);
+  const items = itemsOf(ctx).map((i, n) => ({ title: String(i.item_name ?? i.item_id), type: 'product', reference: product(i), position: (num(i.index) ?? n) + 1, ...(num(i.price) != null ? { price: num(i.price) } : {}) }));
+  return items.length ? { ...(e.search_term ? { query: { string: String(e.search_term) } } : {}), items } : null;
+};
+
+/** add_to_cart: one add-to-cart per item, its quantity and unit price. */
+export const addToCart = /* @__PURE__ */ reader('addToCart', (ctx: Ctx) =>
+  itemsOf(ctx).map((i): AddToCart => {
+    const price = num(i.price);
+    return { reference: product(i), count: count(i.quantity), ...(price! >= 0 ? { price } : {}) };
+  }),
+);
+/** purchase: the order, its lines' totals (not unit prices), discounted lines, the transaction id (sent once). */
+export const purchase = /* @__PURE__ */ reader('purchase', (ctx: Ctx) => {
+  const e = ecommerceOf(ctx);
+  const items = itemsOf(ctx).map((i) => {
+    const n = count(i.quantity);
+    return { reference: product(i), title: String(i.item_name ?? i.item_id), count: n, total_price: Math.round((num(i.price) ?? 0) * n * 100) / 100, ...(num(i.discount)! > 0 ? { was_discounted: true } : {}) };
+  });
+  return items.length ? { id: e.transaction_id, currency: e.currency, items } : null;
+});
+/** select_item: the product clicked. */
+export const click = /* @__PURE__ */ reader('click', first);
+/** view_item: the page's product. */
+export const pageView = /* @__PURE__ */ reader('pageView', first);
+/** view_item_list of their search: its items, the query from search_term. */
+export const search = /* @__PURE__ */ reader('search', list);
+/** view_item_list of their suggestions. */
+export const autocomplete = /* @__PURE__ */ reader('autocomplete', list);
+/** view_item_list of their recommender. */
+export const recommender = /* @__PURE__ */ reader('recommender', list);

package/src/analytics/from-luma.ts

@@ -0,0 +1,21 @@
+// Readers of Luma's own events (`.read(fromLuma.<event>)`), one export each:
+// what Luma saw is what the event sends.
+//
+//   collect.pageView.on(lumaPages()).read(fromLuma.pageView);
+//   collect.click.on(lumaClicks()).read(fromLuma.click);
+//   collect.addToCart.on(lumaCarts()).read(fromLuma.addToCart);
+//
+// Our tiles' references are their results' `@id`s (every result has one),
+// whatever ref.product.by() says for the site's own data.
+
+import type { TileEvent } from '../core/tiles';
+import { reader } from './chain';
+import { OURS } from './collect';
+import type { Page } from './page';
+
+/** A page: no reference of its own. */
+export const pageView = /* @__PURE__ */ reader('pageView', (_: Page) => null);
+/** A click on one of our tiles: the product clicked. */
+export const click = /* @__PURE__ */ reader('click', (t: TileEvent) => t.reference);
+/** `[data-lbx-cart]` on one of our tiles: the product, its quantity and price (the site's own push its cart then makes is the same one). */
+export const addToCart = /* @__PURE__ */ reader('addToCart', (t: TileEvent) => ({ reference: t.reference, count: t.count ?? 1, ...(t.price != null ? { price: t.price } : {}), [OURS]: true as const }));

package/src/analytics/index.ts

@@ -0,0 +1,24 @@
+// The analytics API of an integration's `_analytics.ts` (README "Analytics").
+// Every event sent is a `collect.<event>` chain, nothing else is:
+//
+//   import { collect, dl, fromGa4, fromLuma, lumaPages, ref } from '@/analytics';
+//   ref.product.by('sku');
+//   collect.pageView.on(lumaPages()).read(fromLuma.pageView);
+//   collect.addToCart.on(dl('add_to_cart')).read(fromGa4.addToCart);
+//   collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
+//
+// One chunk, lbx-analytics, with the setup in it: every event, trigger and
+// reader is its own export (collect, fromGa4 and fromLuma are namespaces:
+// `fromGa4.purchase` is static, the rest of fromGa4 left out), so the chunk
+// holds what the setup names (yarn analytics:weight measures each).
+
+export * as collect from './collect';
+export * as fromGa4 from './from-ga4';
+export * as fromLuma from './from-luma';
+export { user } from './user';
+export { ref } from './ref';
+export { dl, domClick, lumaCarts, lumaClicks, lumaPages, manual, mutationOf, urlChange, xhrMatching } from './triggers';
+export type { DlContext, DomClickContext, ManualContext, MutationContext, UrlChangeContext, XhrContext } from './triggers';
+export type { AddToCart, List, Purchase, Read, Trigger } from './chain';
+export type { Page } from './page';
+export type { TileEvent } from '../core/tiles';

package/src/analytics/outbox.ts

@@ -0,0 +1,118 @@
+// Delivery: every event goes into an outbox in sessionStorage first (in the
+// task of the click), then one keepalive POST each to the Luigi's Box AI
+// events API (POST /analytics/v1/events), so a click that leaves the page is
+// not lost: what did not get out is sent by the next page. The API dedupes a
+// re-sent event by its event_id. Consent is the loader's: once Luma runs,
+// events are sent (consent_granted: true).
+
+import { mark, reportError } from '../core/health';
+import { session } from '../core/storage';
+import { call, stamps, state } from './setup';
+import { eventUrl } from './wire';
+
+const BOX = 'lbx:ev';
+const MAX_BOX = 50;
+const MAX_AGE_MS = 60 * 60e3;
+interface Out {
+  b: Record<string, any>;
+  /** Tries so far. */
+  n: number;
+  at: number;
+  /** Not before (ms epoch): a retry's. */
+  t?: number;
+}
+const box = () => session.get<Out[]>(BOX) ?? [];
+const save = (o: Out[]) => session.set(BOX, o.length ? o.slice(-MAX_BOX) : undefined);
+
+/** Where and when what is being sent happened, when not here and now (./chain.ts: a queued tile event, a dataLayer push the last page kept). */
+export const origin: { url?: string; at?: number } = {};
+
+/** One event: into the outbox now, sent at once (a prerendered page's once shown). */
+export const emit = (b: Record<string, any>) => {
+  const o = box();
+  o.push({ b: { event_id: crypto.randomUUID(), event_timestamp: Math.floor((origin.at ?? Date.now()) / 1000), url: eventUrl(origin.url ?? location.href), ...b }, n: 0, at: Date.now() });
+  save(o);
+  mark(`analytics: ${b.type}${b.interaction_type ? ` ${b.interaction_type}` : ''}`);
+  void flush();
+};
+
+let token: Promise<typeof import('../api/token')> | null = null;
+/** Events being sent; `posted`: their keepalive request is out (it outlives the page). */
+const sending = new Set<string>();
+const posted = new Set<string>();
+const SEND_MS = 8000;
+const RETRY_MS = 2000;
+let later = 0;
+/** Send what the outbox holds and is due: each event at once, on its own. */
+export const flush = async () => {
+  const g = state.g;
+  // A prerendered page sends nothing until it is shown (./start.ts flushes then).
+  if (!g || (document as any).prerendering) return;
+  const now = Date.now();
+  const o = box().filter((x) => now - x.at < MAX_AGE_MS && !sending.has(x.b.event_id));
+  const due = o.filter((x) => (x.t ?? 0) <= now);
+  // A retry waiting (this page's, or the last page's): its turn.
+  const next = Math.min(...o.map((x) => x.t ?? Infinity));
+  if (next > now && next < Infinity) {
+    clearTimeout(later);
+    later = window.setTimeout(flush, next - now + 10);
+  }
+  if (!due.length) return;
+  for (const x of due) sending.add(x.b.event_id);
+  let send: (x: Out) => Promise<number>;
+  try {
+    const t = await (token ??= import('../api/token'));
+    const tk = t.tokensFor(g);
+    const bearer = await tk.get();
+    const headers = { Authorization: `Bearer ${bearer}`, 'X-Lbx-Visitor-Id': t.visitorId(), 'Content-Type': 'application/json' };
+    const uid = stamps.user ? call(stamps.user, 'analytics user') : null;
+    send = async (x) => {
+      const c = new AbortController();
+      const timer = setTimeout(() => c.abort(), SEND_MS);
+      try {
+        const body = { channel_id: g.channelId, consent_granted: true, ...(uid != null && uid !== '' ? { user_id: String(uid) } : {}), ...x.b };
+        const p = fetch(`${tk.API}/analytics/v1/events`, { method: 'POST', headers, body: JSON.stringify(body), keepalive: true, signal: c.signal });
+        posted.add(x.b.event_id);
+        const status = (await p).status;
+        if (status === 401 && tk.current() === bearer) tk.clear();
+        return status;
+      } catch {
+        return 0;
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+  } catch (e) {
+    // No token (a failed mint backs off by itself), its chunk did not load: the next event or page tries again.
+    token = null;
+    for (const x of due) sending.delete(x.b.event_id);
+    return mark(`analytics: not sent (${e instanceof Error ? e.message : e})`);
+  }
+  await Promise.all(due.map(async (x) => settle(x, await send(x))));
+};
+
+/** An event's answer: out of the outbox (taken, or refused for good), or tried once more later. */
+const settle = (x: Out, status: number) => {
+  const id = x.b.event_id;
+  sending.delete(id);
+  posted.delete(id);
+  const o = box();
+  const at = o.findIndex((y) => y.b.event_id === id);
+  if (at < 0) return;
+  const refused = status >= 400 && status < 500 && status !== 401 && status !== 408 && status !== 429;
+  if (refused) reportError('analytics', `${x.b.type} refused: HTTP ${status}`);
+  if ((status >= 200 && status < 300) || refused || x.n + 1 >= 2) o.splice(at, 1);
+  else {
+    // Once more (the API's advice: one retry, the same event_id), later.
+    o[at].n = x.n + 1;
+    o[at].t = Date.now() + RETRY_MS;
+  }
+  save(o);
+  if (o[at]?.b.event_id === id) void flush(); // schedules the retry
+};
+
+// The page goes (a click on a product): what is posted already travels on its
+// own (keepalive); what is not stays for the next page.
+addEventListener('pagehide', () => {
+  if (posted.size) save(box().filter((x) => !posted.has(x.b.event_id)));
+});

package/src/analytics/page.ts

@@ -0,0 +1,46 @@
+// A page, as analytics counts them: the first once shown (a prerendered page
+// at activation), an SPA's next page, a restore from the back/forward cache.
+// Not our own filters or sort: one listing visit is one page (the entry's
+// `visit`), nor tracking params or the hash (wire.ts pageOf). For pageviews
+// (./pageview.ts) and `.once()` (per page, ./chain.ts).
+
+import { env, whenShown } from './setup';
+import { eventUrl, pageOf } from './wire';
+
+export interface Page {
+  /** The page's URL as events carry it (tracking params stripped). */
+  url: string;
+  /** The page before it (an SPA's), else document.referrer. */
+  referrer: string;
+}
+const subs: ((p: Page) => void)[] = [];
+let current: Page | null = null;
+let key = '';
+let lastHref = '';
+const check = () => {
+  const k = pageOf(location.href, env.visit);
+  if (k === key) return;
+  key = k;
+  const referrer = lastHref || document.referrer;
+  lastHref = location.href;
+  current = { url: eventUrl(location.href), referrer: referrer && eventUrl(referrer) };
+  for (const f of subs) f(current);
+};
+let started = false;
+/** `f` on each new page: the current one at once (once shown), then the next ones. */
+export const onPage = (f: (p: Page) => void) => {
+  subs.push(f);
+  if (current) f(current);
+  if (started) return;
+  started = true;
+  whenShown(() => {
+    check();
+    env.onUrlChange(check);
+    // A page the browser restores from its back/forward cache is viewed again.
+    addEventListener('pageshow', (e) => {
+      if (!e.persisted) return;
+      key = '';
+      check();
+    });
+  });
+};

package/src/analytics/pageview.ts

@@ -0,0 +1,82 @@
+// collect.pageView: a `pv` event per page (./page.ts), with the page's object
+// when the chain reads one:
+//
+//   collect.pageView.on(lumaPages()).read(fromLuma.pageView);         // every page
+//   collect.pageView.on(lumaPages()).read(() => ref.product(window.sku)); // its reference, read at the page
+//   collect.pageView.on(dl('view_item')).timeout(1500).read(fromGa4.pageView);
+//                    // every page, its reference from a trigger, waited for (default 1000 ms, then without)
+//
+// One pageView chain per setup: a second one is an error, not a second pageview.
+
+import { reportError } from '../core/health';
+import { checked, type Read, type Trigger } from './chain';
+import { emit } from './outbox';
+import { onPage, type Page } from './page';
+import { whenShown } from './setup';
+import { isRef } from './wire';
+
+let chained = false;
+const send = (p: Page, reference?: string | null) => emit({ type: 'pv', url: p.url, ...(p.referrer ? { referrer: p.referrer } : {}), ...(isRef(reference) ? { reference } : {}) });
+
+export interface PageViewChain<C> {
+  /** lumaPages(): only the pages `f` says (the rest send none). Another trigger: only a context `f` says is the page's. */
+  when(f: (ctx: C) => boolean): PageViewChain<C>;
+  /** How long a page waits for its reference from the trigger (default 1000 ms), then goes without. Not for lumaPages(). */
+  timeout(ms: number): PageViewChain<C>;
+  /** The page's reference, read from the trigger's context (null: the page without one). */
+  read(r: Read<'pageView', C>): void;
+}
+
+export const pageView = {
+  on<C>(t: Trigger<C>): PageViewChain<C> {
+    let when: ((ctx: C) => boolean) | undefined;
+    let ms = 1000;
+    const b: PageViewChain<C> = {
+      when(f) {
+        when = f;
+        return b;
+      },
+      timeout(n) {
+        ms = n;
+        return b;
+      },
+      read(r) {
+        checked('pageView', r);
+        if (chained) throw new Error('analytics: one collect.pageView chain per setup');
+        chained = true;
+        const ref = (ctx: C) => {
+          try {
+            return r(ctx);
+          } catch (e) {
+            reportError('analytics pageView', e);
+            return null;
+          }
+        };
+        // lumaPages(): the page is the context, sent at once.
+        if (t.key === 'pages') return void t.sub((p) => (!when || when(p)) && send(p as Page, ref(p)));
+        /** The pageview waiting for its reference, if any. */
+        let waiting: ((r?: string | null) => void) | null = null;
+        onPage((p) => {
+          waiting?.(); // the previous page's, still waiting: sent without one
+          const timer = setTimeout(() => waiting?.(), ms);
+          waiting = (x) => {
+            clearTimeout(timer);
+            waiting = null;
+            send(p, x);
+          };
+        });
+        // After the first page waits (onPage's own whenShown runs first): what the
+        // trigger has already, the dataLayer's earlier pushes, completes it.
+        whenShown(() =>
+          t.sub((ctx) => {
+            // Not from another page (the last page's dataLayer, kept for us: `at`).
+            if (!waiting || typeof (ctx as { at?: unknown })?.at === 'number' || (when && !when(ctx))) return;
+            const x = ref(ctx);
+            if (x != null) waiting(x);
+          }),
+        );
+      },
+    };
+    return b;
+  },
+};

package/src/analytics/ref.ts

@@ -0,0 +1,19 @@
+// References (docs.luigisbox.ai/analytics/references), `<type>/<field>:<value>`:
+//
+//   ref.product('1234')           // product/@id:product/1234 (the type's field, default @id)
+//   ref.product('ean', '4006…')   // product/ean:4006…
+//   ref.product.by('id');         // the field ref.product(value) uses from now on
+//
+// Types: product, variant, category, brand.
+
+import { ref as reference } from './wire';
+
+const make = (type: string) => {
+  let field = '@id';
+  const f = (a: unknown, b?: unknown) => (b === undefined ? reference(type, field, a) : reference(type, String(a), b));
+  /** The catalog field `ref.<type>(value)` uses (default `@id`). */
+  f.by = (attribute: string) => void (field = attribute);
+  return f;
+};
+
+export const ref = { product: make('product'), variant: make('variant'), category: make('category'), brand: make('brand') };