@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/analytics/setup.ts

@@ -0,0 +1,41 @@
+// The page's analytics state: the global config, what the integration's
+// `_analytics.ts` reads for every event (user.identify), what only the entry
+// knows (env), and the moment the page is shown (a prerendered page:
+// once activated), when chains start to listen. Every other module reads it
+// here; none runs anything at its top level, so what a setup does not import
+// is left out of the build.
+
+import { reportError } from '../core/health';
+import type { GlobalConfigType } from '../types';
+
+export const state: { g: GlobalConfigType | null } = { g: null };
+/** Read on every event (./user.ts). */
+export const stamps: { user: (() => string | number | null | undefined) | null } = { user: null };
+
+/** A hook of the integration's: its value, or null when it threw (reported). */
+export const call = <T>(f: () => T, where: string): T | null => {
+  try {
+    return f() ?? null;
+  } catch (e) {
+    reportError(where, e);
+    return null;
+  }
+};
+
+/** What only the entry knows: which of the site's services Luma runs here, URL changes, one listing visit. */
+export const env: {
+  owns: (surface: string) => boolean;
+  onUrlChange: (l: (u: URL) => void) => void;
+  visit: (u: URL) => string | null;
+  /** This page's dataLayer pushes the entry kept already (left, then restored from the back/forward cache): not read again. */
+  kept: () => number;
+} = { owns: () => false, onUrlChange: () => {}, visit: () => null, kept: () => 0 };
+
+const waiting: (() => void)[] = [];
+let shown = false;
+/** Now if the page is shown, else once it is (a chain registered as the setup runs listens then). */
+export const whenShown = (f: () => void) => (shown ? f() : void waiting.push(f));
+export const pageShown = () => {
+  shown = true;
+  for (const f of waiting.splice(0)) f();
+};

package/src/analytics/start.ts

@@ -0,0 +1,53 @@
+// Analytics on a page (lbx-analytics: the entry loads it once the page has
+// loaded, or with the first widget, where the integration has an
+// `_analytics.ts`; README "Analytics"). The setup is in this chunk: its chains
+// (./collect.ts, ./triggers.ts) register as it runs, and what it does not
+// import is not built in. Nothing is sent that a chain does not say.
+//
+// To the Luigi's Box AI events API (POST /analytics/v1/events, ./outbox.ts):
+// `pv`, `interaction` (click, add_to_cart), `transaction`, and `list` for a
+// service of the site's own (ours the API records itself). Never anything
+// speculative: a prerendered page counts and sends once shown.
+
+import { reportError } from '../core/health';
+import type { LumaConfigType } from '../types';
+import { flush } from './outbox';
+import { env, pageShown, state } from './setup';
+
+export interface StartOptions {
+  config: LumaConfigType;
+  /** The integration's `_analytics.ts` files (lazy; in this chunk), `_global`'s first. */
+  files: Record<string, () => Promise<any>>;
+  /** Whether Luma runs this service of the site's on this page (`search`, `autocomplete`, `recommender:<name>`). */
+  owns: (surface: string) => boolean;
+  /** One listing visit (a category, a query) is one page, whatever its filters write. */
+  visit: (u: URL) => string | null;
+  onUrlChange: (l: (u: URL) => void) => void;
+  /** This page's dataLayer pushes the entry kept for the next page already (core/kept.ts). */
+  kept: () => number;
+}
+
+let started = false;
+/** The page's analytics (the entry, once per page). */
+export const start = async (o: StartOptions) => {
+  if (started) return;
+  started = true;
+  state.g = o.config._global;
+  env.owns = o.owns;
+  env.visit = o.visit;
+  env.onUrlChange = o.onUrlChange;
+  env.kept = o.kept;
+  // The setup (`_global` first). Its chains register as it runs.
+  for (const [p, f] of Object.entries(o.files).sort(([a], [b]) => (a.includes('/_global/') ? -1 : b.includes('/_global/') ? 1 : 0)))
+    try {
+      await f();
+    } catch (e) {
+      reportError(`analytics ${p}`, e);
+    }
+  const shown = () => {
+    pageShown();
+    void flush();
+  };
+  if ((document as any).prerendering) document.addEventListener('prerenderingchange', shown, { once: true });
+  else shown();
+};

package/src/analytics/triggers.ts

@@ -0,0 +1,239 @@
+// Triggers of the builder (./chain.ts): when a chain's `.read()` runs, with
+// what. Luma's own (lumaPages, lumaClicks, lumaCarts) and the site's (dl,
+// domClick, urlChange, manual, mutationOf, xhrMatching). Each is its own export: a setup brings only the ones it imports (the
+// XMLHttpRequest and fetch wrapper, the mutation observer, the click
+// listeners only where a chain uses them).
+
+import { reportError } from '../core/health';
+import { session } from '../core/storage';
+import { TILES, type TileEvent } from '../core/tiles';
+import type { Trigger } from './chain';
+import { onDl } from './datalayer';
+import { onPage, type Page } from './page';
+import { env } from './setup';
+
+export interface DlContext {
+  event: string;
+  /** The same as `event`. */
+  eventType: string;
+  /** The entry as pushed (gtag's: `{ event, ...params }`). */
+  data: Record<string, any>;
+  /** GA4's ecommerce object (gtag's: its parameters), or null. */
+  ecommerce: Record<string, any> | null;
+  /** A push of a page left before analytics ran there: that page, and when (the event is sent as of them). */
+  url?: string;
+  at?: number;
+}
+/** The site's dataLayer event `name` (object or gtag form), the ones pushed before Luma loaded too. */
+export const dl = (name: string): Trigger<DlContext> => ({
+  key: `dl:${name}`,
+  sub: (h) => onDl(name, (e) => h({ ...e, eventType: e.event })),
+});
+
+export interface DomClickContext {
+  /** The element matching `selector` (the click's target or an ancestor). */
+  element: Element;
+  event: MouseEvent;
+}
+/** A click (or a middle click) on an element of the site's matching `selector`: never on ours (`lumaClicks()`). */
+export const domClick = (selector: string): Trigger<DomClickContext> => ({
+  key: `domClick:${selector}`,
+  sub: (h) => {
+    const on = (e: Event) => {
+      const me = e as MouseEvent;
+      if (e.type === 'auxclick' && me.button !== 1) return;
+      const t = e.composedPath()[0];
+      const el = t instanceof Element ? t.closest(selector) : null;
+      if (el && !el.closest('[data-lbx]')) h({ element: el, event: me });
+    };
+    addEventListener('click', on, true);
+    addEventListener('auxclick', on, true);
+  },
+});
+
+export interface UrlChangeContext {
+  url: string;
+  previousUrl: string;
+}
+/** The page's URL changed (an SPA navigation, ours too). */
+export const urlChange = (): Trigger<UrlChangeContext> => ({
+  key: 'url',
+  sub: (h) => {
+    let previousUrl = location.href;
+    env.onUrlChange((u) => {
+      h({ url: u.href, previousUrl });
+      previousUrl = u.href;
+    });
+  },
+});
+
+/**
+ * Luma's pages, as analytics counts them (./page.ts): the first once shown, an
+ * SPA's next page, a back/forward cache restore; not our own filters or sort.
+ * The context is the page, `{ url, referrer }`: `collect.pageView.on(lumaPages())`.
+ */
+export const lumaPages = (): Trigger<Page> => ({ key: 'pages', sub: (h) => onPage(h) });
+
+/**
+ * Luma's own tiles (core/tiles.ts): a product click on them (`lumaClicks()`,
+ * the autocomplete's picks too), an add-to-cart by their `[data-lbx-cart]`
+ * (`lumaCarts()`). The context is a TileEvent, `{ reference, result, index,
+ * list, count?, price?, url, at }`, read by fromLuma.click / .addToCart.
+ * Every one, whenever it happened: queued before analytics listened (on this
+ * page or the last), claimed now, sent as of its page and time.
+ */
+const tiles = (kind: TileEvent['kind']): Trigger<TileEvent> => ({
+  key: `tiles:${kind}`,
+  sub: (h) => {
+    // Claimed from the queue (core/tiles.ts): each once, whenever analytics listens.
+    const claim = (id: string) => {
+      const q = session.get<TileEvent[]>(TILES) ?? [];
+      const i = q.findIndex((x) => x.id === id);
+      if (i < 0) return false;
+      q.splice(i, 1);
+      session.set(TILES, q.length ? q : undefined);
+      return true;
+    };
+    for (const d of session.get<TileEvent[]>(TILES) ?? []) if (d.kind === kind && claim(d.id)) h(d);
+    document.addEventListener('lbx:tile', (e) => {
+      const d = (e as CustomEvent<TileEvent>).detail;
+      if (d.kind === kind && claim(d.id)) h(d);
+    });
+  },
+});
+export const lumaClicks = () => tiles('click');
+export const lumaCarts = () => tiles('add_to_cart');
+
+export interface MutationContext {
+  /** The element matching the selector: added, or with nodes added inside it. */
+  element: Element;
+}
+/**
+ * The site's element `selector`, once in the page and each time it (or what
+ * is inside it) is added: a service of theirs that renders its results with
+ * no dataLayer event. Read when the browser is idle (the render has settled);
+ * never ours. `root`: only inside the first element it matches (default the document).
+ */
+export const mutationOf = (selector: string, opts?: { root?: string }): Trigger<MutationContext> => ({
+  key: `mutation:${selector}:${opts?.root ?? ''}`,
+  sub: (h) => {
+    const due = new Set<Element>();
+    let asked = false;
+    const fire = () => {
+      asked = false;
+      const els = [...due];
+      due.clear();
+      for (const element of els) if (element.isConnected) h({ element });
+    };
+    const add = (el: Element | null) => {
+      if (!el || el.closest('[data-lbx]')) return;
+      due.add(el);
+      if (asked) return;
+      asked = true;
+      if (typeof requestIdleCallback === 'function') requestIdleCallback(fire, { timeout: 1000 });
+      else setTimeout(fire, 50);
+    };
+    const look = (n: Node) => {
+      if (!(n instanceof Element)) return;
+      if (n.matches(selector)) add(n);
+      n.querySelectorAll(selector).forEach(add);
+    };
+    const root = (opts?.root && document.querySelector(opts.root)) || document.documentElement;
+    new MutationObserver((ms) => {
+      for (const m of ms) {
+        if (!m.addedNodes.length) continue;
+        add(m.target instanceof Element ? m.target.closest(selector) : null);
+        m.addedNodes.forEach(look);
+      }
+    }).observe(root, { childList: true, subtree: true });
+    root.querySelectorAll(selector).forEach(add);
+  },
+});
+
+export interface XhrContext {
+  url: string;
+  method: string;
+  /** Its JSON body (the text, where it is not JSON). */
+  response: any;
+}
+type XhrTest = (r: { url: string; method: string }) => boolean;
+const xhrs: { test: XhrTest; h: (c: XhrContext) => void }[] = [];
+const matching = (url: string, method: string) =>
+  xhrs.filter((x) => {
+    try {
+      return x.test({ url, method });
+    } catch (e) {
+      reportError('analytics xhrMatching', e);
+      return false;
+    }
+  });
+const answered = (hs: typeof xhrs, url: string, method: string, text: string) => {
+  let response: any = text;
+  try {
+    response = JSON.parse(text);
+  } catch {}
+  for (const x of hs) x.h({ url, method, response });
+};
+let wrapped = false;
+/** XMLHttpRequest and fetch, watched once: only a response a trigger asks for is read. */
+const wrapXhr = () => {
+  if (wrapped) return;
+  wrapped = true;
+  const open = XMLHttpRequest.prototype.open;
+  XMLHttpRequest.prototype.open = function (this: XMLHttpRequest, method: string, url: string | URL, ...rest: unknown[]) {
+    const u = new URL(url, location.href).href;
+    const m = method.toUpperCase();
+    this.addEventListener('load', () => {
+      const hs = this.status >= 200 && this.status < 300 ? matching(u, m) : [];
+      if (!hs.length) return;
+      const t = this.responseType === '' || this.responseType === 'text' ? this.responseText : this.responseType === 'json' ? JSON.stringify(this.response) : null;
+      if (t != null) answered(hs, u, m, t);
+    });
+    return (open as (...a: unknown[]) => void).call(this, method, url, ...rest);
+  } as typeof open;
+  const f = window.fetch;
+  window.fetch = function (input: RequestInfo | URL, init?: RequestInit) {
+    const p = f.call(window, input, init);
+    const u = new URL(input instanceof Request ? input.url : String(input), location.href).href;
+    const m = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    const hs = matching(u, m);
+    if (hs.length)
+      p.then((r) => (r.ok ? r.clone().text() : null))
+        .then((t) => t != null && answered(hs, u, m, t))
+        .catch(() => {});
+    return p;
+  };
+};
+/**
+ * A response to one of the site's own requests (XMLHttpRequest or fetch)
+ * that `test` matches (`url` absolute, `method` upper case): a service of
+ * theirs that asks its own API (their suggestions). Requests made before the
+ * page loaded are not seen.
+ */
+export const xhrMatching = (test: XhrTest): Trigger<XhrContext> => ({
+  key: 'xhr',
+  sub: (h) => {
+    wrapXhr();
+    xhrs.push({ test, h });
+  },
+});
+
+export interface ManualContext<D = any> {
+  data: D;
+}
+/** A trigger the integration fires itself: `const { trigger, fire } = manual(); …on(trigger)…; fire(data)`. */
+export const manual = <D = any>(): { trigger: Trigger<ManualContext<D>>; fire(data?: D): void } => {
+  const hs: ((c: ManualContext<D>) => void)[] = [];
+  return {
+    trigger: { key: 'manual', sub: (h) => void hs.push(h) },
+    fire: (data = {} as D) =>
+      hs.forEach((h) => {
+        try {
+          h({ data });
+        } catch (e) {
+          reportError('analytics manual', e);
+        }
+      }),
+  };
+};
+

package/src/analytics/user.ts

@@ -0,0 +1,12 @@
+// user.identify(fn): the signed-in shopper's own id, read on every event and
+// sent as `user_id` (omitted when null).
+//
+//   user.identify(() => window.shop?.customerId ?? null);
+
+import { stamps } from './setup';
+
+export const user = {
+  identify(fn: () => string | number | null | undefined) {
+    stamps.user = fn;
+  },
+};

package/src/analytics/wire.ts

@@ -0,0 +1,67 @@
+// What analytics events are made of, without the page: object references,
+// the site's dataLayer entries, the page a URL is (one pageview per page, not per filter). Pure: unit-tested
+// (test/unit/analytics-wire.test.ts).
+//
+// The wire format is the Luigi's Box AI events API
+// (docs.luigisbox.ai/analytics/event-reference): `interaction` (click,
+// add_to_cart), `transaction`, and, as the legacy Luma sends them, `pv` and
+// `list` (an original service's results: ours the API records itself).
+
+import { P, TRACKING, withoutTracking } from '../core/routes';
+
+/**
+ * An object reference, `<type>/<field>:<value>`
+ * (docs.luigisbox.ai/analytics/references). An `@id` value carries its type
+ * ("product/123"): a bare one is prefixed.
+ */
+export const ref = (type: string, field: string, value: unknown) => {
+  const v = String(value);
+  return `${type}/${field}:${field === '@id' && !v.startsWith(`${type}/`) ? `${type}/${v}` : v}`;
+};
+
+/** A reference as the API accepts it: three non-empty parts, no `/` or `:` in the first two. */
+export const isRef = (r: unknown): r is string => typeof r === 'string' && /^[^/:]+\/[^/:]+:.+/.test(r);
+
+/** An event of the site's dataLayer, read (object form or gtag's). */
+export interface DlEntry {
+  event: string;
+  data: Record<string, any>;
+  ecommerce: Record<string, any> | null;
+  /** A push of a page left before analytics ran there: that page, and when it was left. */
+  url?: string;
+  at?: number;
+}
+
+/** gtag's `arguments` (or one kept by a page left before analytics ran: `{ 0: 'event', 1: … }`). */
+const isArgs = (x: any): x is ArrayLike<any> => !!x && typeof x === 'object' && typeof x[0] === 'string';
+
+/**
+ * `{ event: 'purchase', ecommerce: {…} }` (GTM) or `gtag('event', 'purchase',
+ * {…})` (an `arguments` object: gtag's parameters are the ecommerce data).
+ */
+export const readDl = (x: any): DlEntry | null => {
+  if (isArgs(x)) {
+    if (x[0] === 'event' && typeof x[1] === 'string') {
+      const params = x[2] && typeof x[2] === 'object' ? x[2] : {};
+      return { event: x[1], data: { event: x[1], ...params }, ecommerce: params };
+    }
+    return null;
+  }
+  if (x && typeof x === 'object' && typeof x.event === 'string') return { event: x.event, data: x, ecommerce: x.ecommerce && typeof x.ecommerce === 'object' ? x.ecommerce : null };
+  return null;
+};
+
+const IGNORE = new RegExp(`${TRACKING}|^${P.replace('.', '\\.')}`);
+/**
+ * The page a URL shows, for pageviews: without tracking params, the hash and
+ * our own `lbx.*` (a filter, a sort on our listing is the same page). A
+ * listing's own visit (its category, its query: the caller's `visit`) is one
+ * page whatever its filters write into the site's params.
+ */
+export const pageOf = (href: string, visit?: (u: URL) => string | null) => {
+  const u = withoutTracking(href, IGNORE);
+  return visit?.(u) ?? u.href;
+};
+
+/** The URL sent with events: without tracking params (gclid, utm_…) and the hash. */
+export const eventUrl = (href: string) => withoutTracking(href).href;

package/src/api/ai.ts

@@ -0,0 +1,98 @@
+// Luigi's Box AI discovery client: the requests (search, facets, recommend).
+// Authentication (publishable key -> browser token, the visitor id) is
+// ./token.ts, in the entry so that every page mints the token at boot.
+//
+// Every discovery call carries X-Lbx-Visitor-Id: Luma's first-party
+// `_lbx_vid` cookie, so requests and analytics events join on one visitor.
+//
+// Also runs in Node (the edge render service): there the
+// storefront origin is sent explicitly and nothing touches the DOM.
+
+import { health } from '../core/health';
+import type { GlobalConfigType } from '../types';
+import type { Api, FacetData, Hit, Page } from '.';
+import { fetchJson, TIMEOUT_MS, tokensFor, untilAborted, visitorId } from './token';
+
+export { untilAborted };
+
+export const aiApi = (g: GlobalConfigType, origin?: string): Api => {
+  const tk = tokensFor(g, origin);
+  const { API, originHeaders } = tk;
+  const getToken = tk.get;
+
+  // A 401 re-mints, but not on every request when a fresh token is refused too
+  // (an origin the key does not allow): at most once a minute. A request whose
+  // token was already replaced (a parallel one re-minted) just retries once.
+  let reminted = -Infinity;
+  const post = async (path: string, params: Record<string, string>, body: unknown, signal?: AbortSignal, retried = false): Promise<any> => {
+    health.apiCalls++;
+    // The caller's signal bounds the wait for a token too (a server render's budget).
+    const t = await untilAborted(getToken(), signal);
+    const qs = new URLSearchParams(params).toString();
+    const r = await fetchJson(
+      `${API}/discovery/v1/${path}?${qs}`,
+      {
+        method: 'POST',
+        headers: { ...originHeaders, Authorization: `Bearer ${t}`, 'X-Lbx-Visitor-Id': visitorId(), 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+      TIMEOUT_MS,
+      signal,
+    );
+    if (r.status === 401 && !retried) {
+      if (tk.current() !== t) return post(path, params, body, signal, true);
+      if (Date.now() - reminted > 60e3) {
+        // Expired or revoked early: mint a new one.
+        reminted = Date.now();
+        tk.clear();
+        return post(path, params, body, signal, true);
+      }
+    }
+    if (!r.ok) throw new Error(`${path}: HTTP ${r.status} ${r.body.slice(0, 300)}`);
+    if (r.json == null) throw new Error(`${path}: not JSON`);
+    return r.json;
+  };
+
+  /** Drops undefined fields: unknown or empty ones are a 422. */
+  const compact = (o: Record<string, unknown>) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+  const nonEmpty = (f?: Record<string, unknown>) => (f && Object.keys(f).length ? f : undefined);
+
+  return {
+    warm: () => void getToken().catch(() => {}),
+
+    search: async (r, signal): Promise<Page> => {
+      const body = compact({
+        type: r.type,
+        size: r.size,
+        query: r.endpoint === 'search' ? (r.query ?? '') : undefined,
+        collection_filters: r.endpoint === 'collections' ? nonEmpty(r.scope) : undefined,
+        filters: nonEmpty(r.filters),
+        sort: r.sort,
+        cursor: r.cursor || undefined,
+        return_fields: r.fields?.length ? r.fields : undefined,
+      });
+      const j = await post(r.endpoint, { channel_id: g.channelId, surface_id: r.surface }, body, signal);
+      return { hits: j.hits ?? [], total: j.total ?? j.total_approx ?? 0, guid: j.guid, cursor: j.next_page_cursor ?? null, status: j.pagination_status ?? 'exhausted' };
+    },
+
+    facets: async (guid, facets, signal): Promise<Record<string, FacetData>> =>
+      (await post('facets', { channel_id: g.channelId }, { guid, facets: facets.map((f) => compact(f)) }, signal)).facets ?? {},
+
+    recommend: async (r, signal): Promise<Hit[]> =>
+      (
+        await post(
+          'recommender',
+          { channel_id: g.channelId, surface_id: r.surface },
+          compact({
+            type: r.type,
+            size: r.size,
+            anchor_ids: r.anchors.length ? r.anchors.slice(0, 50) : undefined,
+            exclude_ids: r.exclude?.length ? r.exclude.slice(0, 50) : undefined,
+            filters: nonEmpty(r.filters),
+            return_fields: r.fields?.length ? r.fields : undefined,
+          }),
+          signal,
+        )
+      ).hits ?? [],
+  };
+};

package/src/api/index.ts

@@ -0,0 +1,87 @@
+// The data API behind every widget: Luigi's Box AI discovery
+// (api.<region>.luigisbox.ai/discovery/v1). Widgets only see this interface;
+// the implementation (./ai.ts) owns authentication (publishable key ->
+// browser token), the visitor id and the wire format.
+
+import type { GlobalConfigType } from '../types';
+import { aiApi } from './ai';
+
+/** A catalog object as discovery returns it: flat, `@id` and `@type` always present. */
+export interface Hit {
+  '@id': string;
+  '@type': string;
+  [field: string]: any;
+}
+
+/** A discovery filter tree: condition and group nodes. */
+export type FilterNode = Record<string, unknown>;
+
+export interface Sort {
+  field: string;
+  direction: 'asc' | 'desc';
+}
+
+/** One page of /search or /collections. */
+export interface Page {
+  hits: Hit[];
+  /** Exact when known, else the API's approximation. */
+  total: number;
+  /** Identifies the result set; /facets takes it. */
+  guid: string;
+  /** Cursor of the next page; null when there is none (see status). */
+  cursor: string | null;
+  /** more | exhausted | unsupported | unavailable */
+  status: string;
+}
+
+export interface ListingRequest {
+  /** search: a query; collections: a scope (collection_filters). */
+  endpoint: 'search' | 'collections';
+  surface: string;
+  type: string;
+  query?: string;
+  scope?: FilterNode;
+  filters?: FilterNode;
+  sort?: Sort;
+  size: number;
+  /** From the previous page; every other field must be unchanged. */
+  cursor?: string;
+  fields?: string[];
+}
+
+export interface FacetData {
+  field: string;
+  type: 'terms' | 'range' | 'hierarchy' | string;
+  values?: any[];
+  min?: number;
+  max?: number;
+}
+
+export interface RecoRequest {
+  surface: string;
+  type: string;
+  /** Typed identities ("product/<id>") the slate is about; [] = none. */
+  anchors: string[];
+  exclude?: string[];
+  size: number;
+  filters?: FilterNode;
+  fields?: string[];
+}
+
+export interface Api {
+  search(r: ListingRequest, signal?: AbortSignal): Promise<Page>;
+  /** Facets of a result set (its guid): values, no counts. */
+  facets(guid: string, facets: { field: string; size?: number }[], signal?: AbortSignal): Promise<Record<string, FacetData>>;
+  recommend(r: RecoRequest, signal?: AbortSignal): Promise<Hit[]>;
+  /** Mint the browser token now, so the first request does not wait for it. */
+  warm(): void;
+}
+
+const apis = new Map<string, Api>();
+/** `origin`: the storefront origin, for server-side callers (browsers send their own). */
+export const getApi = (g: GlobalConfigType, origin?: string): Api => {
+  const k = `${g.channelId}|${g.region ?? 'eu1'}|${origin ?? ''}`;
+  let api = apis.get(k);
+  if (!api) apis.set(k, (api = aiApi(g, origin)));
+  return api;
+};

package/src/api/token-key.ts

@@ -0,0 +1,42 @@
+// Where the browser token is kept (sessionStorage), and whether a fresh one is
+// there: the entry asks this at boot and loads the minting code (./token.ts,
+// its own chunk) only when there is none. No DOM.
+
+import { session } from '../core/storage';
+import type { GlobalConfigType } from '../types';
+
+export interface StoredToken {
+  token: string;
+  /** ms epoch; refreshed 30 s early. */
+  exp: number;
+}
+
+/** Per key too: a rotated publishable key must not keep using a stored token of the old one. */
+export const tokenKey = (g: GlobalConfigType) => `lbx:tok:${g.publishableKey}:${g.channelId}:${g.region ?? 'eu1'}`;
+
+/** The stored token of this channel while it is valid. */
+export const storedToken = (g: GlobalConfigType): StoredToken | null => {
+  const t = session.get<StoredToken>(tokenKey(g));
+  return t && t.exp > Date.now() ? t : null;
+};
+
+const challenges = new Map<string, Promise<Response>>();
+/** The browser challenge of this channel's key. */
+export const challengeUrl = (g: GlobalConfigType) => `https://auth.${g.region ?? 'eu1'}.luigisbox.ai/browser-challenge?api_key=${encodeURIComponent(g.publishableKey)}`;
+/**
+ * The challenge asked by the entry (main.ts warm()) while the minting code,
+ * its own chunk, loads: the mint starts a round trip earlier. Taken once by
+ * ./token.ts (a challenge expires in seconds).
+ */
+export const askChallenge = (g: GlobalConfigType) => {
+  const url = challengeUrl(g);
+  if (challenges.has(url)) return;
+  const p = fetch(url);
+  p.catch(() => {}); // the mint that takes it reports a failure
+  challenges.set(url, p);
+};
+export const takeChallenge = (url: string) => {
+  const p = challenges.get(url);
+  challenges.delete(url);
+  return p;
+};