@web-my-money/studio-consumer 1.0.0

package/src/analytics/collector.ts

@@ -0,0 +1,537 @@
+/**
+ * First-party funnel-analytics collector (wmm-studio docs/analytics/01-pipeline.md §5.2).
+ *
+ * Events go to a same-origin route (`/api/analytics/collect`), which forwards
+ * them server-side to Studio's ingest endpoint. That indirection is the whole
+ * point: the ingest token never reaches a browser, and the request the visitor's
+ * browser makes is same-origin, so ad-blockers and third-party cookie policy
+ * don't touch it.
+ *
+ * This is a THIRD sink alongside `dataLayer` (GTM → GA4/Meta) and the GHL event
+ * buffer, and it follows the same rules as `lib/site-events.ts`: additive,
+ * fire-and-forget, and it swallows every error it can produce. GA4 answers "how
+ * much traffic"; this answers "which step of our own form did they leave on",
+ * which nothing off-the-shelf can see.
+ *
+ * Inert unless `NEXT_PUBLIC_FUNNEL_ANALYTICS === "1"`, so it can ship dark and
+ * be switched on per environment.
+ */
+
+import { getAttribution } from "../attribution/store";
+import { resolveVariant, type RunningExperiment } from "./bucketing";
+
+const VISITOR_KEY = "wmm_funnel_visitor";
+const SESSION_KEY = "wmm_funnel_session";
+/** Same key the med-spa funnel and site-events use — one definition of "staff". */
+const INTERNAL_FLAG_KEY = "wmm_internal_traffic";
+
+/** 30 minutes of inactivity ends a session (funnel-analytics-plan §9). */
+const SESSION_IDLE_MS = 30 * 60 * 1000;
+const FLUSH_INTERVAL_MS = 5_000;
+/** Matches the ingest endpoint's batch cap; a fuller queue flushes early. */
+const MAX_QUEUE = 50;
+/**
+ * The same-origin route events are posted to.
+ *
+ * A constant, not configuration. The route is half of a pair — this and the
+ * `createCollectHandler` mounted behind it — and the package documents mounting
+ * it at exactly this path. A mutable module-level override with a public setter
+ * bought nothing (no caller in either repo used it) and could be called AFTER
+ * events were queued, silently redirecting a site's analytics mid-session.
+ */
+const COLLECT_URL = "/api/analytics/collect";
+
+/**
+ * The running experiments, handed over once by `<AbArm>` in the locale layout.
+ *
+ * Module-level rather than React state because `trackFunnelEvent` is called from
+ * places that are not components — a lifecycle listener, a submit handler, the
+ * scroll observer. The list is published content, fixed for the life of a
+ * deploy, so there is nothing to keep in sync.
+ */
+let runningExperiments: RunningExperiment[] = [];
+
+/** Called once, from the layout. Safe to call again; the last list wins. */
+export function registerExperiments(list: RunningExperiment[] | null | undefined): void {
+  runningExperiments = list ?? [];
+}
+
+/**
+ * The A/B arm to stamp on an event, or `undefined` when no test applies.
+ *
+ * Resolved per event from the CURRENT path, not once per page load, because a
+ * client-side navigation moves the visitor between a page under test and one
+ * that is not, and the layout that mounted `<AbArm>` does not re-render when it
+ * happens. Same function, same cookie and same list as the server used to choose
+ * the copy, so the arm recorded is the arm rendered.
+ *
+ * `undefined` unless an experiment actually targets this path — `resolveVariant`
+ * answers `control` for "no test here", and writing that into the column would
+ * make every ordinary page view look like a control-arm measurement. What the
+ * comparison needs is the opposite: `variant` set ONLY where a test was running.
+ */
+function armFor(path: string): string | undefined {
+  if (runningExperiments.length === 0) return undefined;
+  try {
+    const { variant, experimentKey } = resolveVariant(
+      path,
+      cookieVisitorId(),
+      runningExperiments,
+    );
+    return experimentKey ? variant : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A page being previewed inside Studio, rather than visited.
+ *
+ * Studio's click-to-edit workspace frames the real page, so without this every
+ * editing session writes page views, scroll depth and clicks that look exactly
+ * like visitor traffic — and `?wmm-variant=b` would write them into the arm
+ * under test, which is worse than not measuring at all. The rollups already
+ * exclude `internal` sessions, so this is the flag that keeps an editor out of
+ * their own numbers.
+ */
+function isStudioPreview(): boolean {
+  try {
+    const params = new URLSearchParams(window.location?.search ?? "");
+    return params.has("wmm-edit") || params.has("wmm-variant");
+  } catch {
+    return false;
+  }
+}
+
+export type FunnelEventProps = {
+  path?: string;
+  formKey?: string;
+  stepId?: string;
+  stepIndex?: number;
+  msOnStep?: number;
+  /** A field NAME, never its value. See 07-consent-retention.md §2. */
+  field?: string;
+  /** Why a field errored ("required", "invalid"), never what was typed. */
+  errorKind?: string;
+  /** A number carried by the event — a scroll threshold, a count. */
+  value?: number;
+  /**
+   * What was interacted with: a CTA name or a link target. A target NAME, same
+   * rule as `field` — never an element's innerText, which on a personalised page
+   * can contain someone's name or email.
+   */
+  label?: string;
+  /*
+    No `variant` here on purpose. It used to be a caller-supplied string, and
+    `StudioForm` passed `config.variant` — the form's CSS SKIN name — straight
+    into it. So the one column the A/B comparison reads held the value "medspa"
+    on 109 events and null on the other 942, and the arm was never recorded at
+    all: an experiment could run to completion and report "no difference",
+    correctly, forever. The arm is stamped by `armFor()` below, from the same
+    function the server rendered with, and no caller can shadow it.
+  */
+};
+
+type QueuedEvent = FunnelEventProps & {
+  /** The A/B arm, stamped here rather than accepted from a caller. */
+  variant?: string;
+  gaClientId?: string;
+  gaSessionId?: string;
+  eventUid: string;
+  visitorId: string;
+  sessionId: string;
+  name: string;
+  path: string;
+  utm?: Record<string, string>;
+  referrer?: string;
+  deviceType?: string;
+  viewport?: number;
+  locale?: string;
+  internal?: boolean;
+};
+
+function isBrowser(): boolean {
+  return typeof window !== "undefined";
+}
+
+export function funnelAnalyticsEnabled(): boolean {
+  return process.env.NEXT_PUBLIC_FUNNEL_ANALYTICS === "1";
+}
+
+/**
+ * Consent gate (wmm-studio docs/analytics/07-consent-retention.md §3).
+ *
+ * `NEXT_PUBLIC_FUNNEL_CONSENT`:
+ *
+ *  - unset / `"off"` — no gate. This is the DEFAULT and it deliberately matches
+ *    what the rest of this site already does: GA4, GTM, the Meta Pixel and
+ *    Clarity all run today with no banner. Holding our own first-party analytics
+ *    to a stricter rule than the third-party tags on the same page would cost
+ *    measurement without changing the site's actual privacy posture.
+ *  - `"required"` — FAIL CLOSED. Nothing is sent until consent is explicitly
+ *    granted. Absent, unknown or malformed all count as "not granted".
+ *
+ * The state is read from a `wmm_consent` cookie (value `granted`), so a banner
+ * added later only has to write that cookie — there is no second consent model
+ * here to contradict the one the site eventually adopts.
+ *
+ * Which mode is correct is a decision about lawful basis, not a coding choice.
+ * It is recorded as an open question in 07 §3.1 rather than assumed here.
+ */
+export function consentGranted(): boolean {
+  if (process.env.NEXT_PUBLIC_FUNNEL_CONSENT !== "required") return true;
+  if (!isBrowser()) return false;
+  try {
+    return /(?:^|;\s*)wmm_consent=granted(?:;|$)/.test(document.cookie);
+  } catch {
+    // Unreadable cookies means unknown consent, and unknown fails closed.
+    return false;
+  }
+}
+
+// --- Storage, with an in-memory fallback ------------------------------------
+// Safari private mode throws on localStorage. Probe once and remember: probing
+// per call would return null on read and succeed on the memory write, which
+// mints a fresh visitor id on every single event.
+
+let storageWorks: boolean | null = null;
+const memory = new Map<string, string>();
+
+function storageAvailable(): boolean {
+  if (storageWorks !== null) return storageWorks;
+  try {
+    window.localStorage.setItem("wmm_funnel_probe", "1");
+    window.localStorage.removeItem("wmm_funnel_probe");
+    storageWorks = true;
+  } catch {
+    storageWorks = false;
+  }
+  return storageWorks;
+}
+
+function readStore(key: string): string | null {
+  if (!storageAvailable()) return memory.get(key) ?? null;
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return memory.get(key) ?? null;
+  }
+}
+
+function writeStore(key: string, value: string): void {
+  if (!storageAvailable()) {
+    memory.set(key, value);
+    return;
+  }
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    memory.set(key, value);
+  }
+}
+
+/** The ingest endpoint validates `eventUid` as a uuid, so the fallback must be one. */
+function uuid(): string {
+  try {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+  } catch {
+    /* fall through */
+  }
+  const hex = "0123456789abcdef";
+  let out = "";
+  for (let i = 0; i < 36; i++) {
+    if (i === 8 || i === 13 || i === 18 || i === 23) out += "-";
+    else if (i === 14) out += "4";
+    else if (i === 19) out += hex[(Math.random() * 4) | 8]!;
+    else out += hex[(Math.random() * 16) | 0]!;
+  }
+  return out;
+}
+
+/**
+ * The `wmm_vid` cookie the middleware sets, or null.
+ *
+ * The cookie is the AUTHORITATIVE visitor identity, because it is the only one a
+ * server can read — and A/B assignment has to happen server-side to avoid a flash
+ * of the wrong variant (lib/experiments.ts). Preferring it here is what stops the
+ * server and the browser disagreeing about who someone is, which would put a
+ * visitor in one bucket and file their events under another.
+ */
+function cookieVisitorId(): string | null {
+  try {
+    const match = document.cookie.match(/(?:^|;\s*)wmm_vid=([^;]+)/);
+    return match ? decodeURIComponent(match[1]!) : null;
+  } catch {
+    return null;
+  }
+}
+
+function visitorId(): string {
+  const fromCookie = cookieVisitorId();
+  if (fromCookie) return fromCookie;
+
+  // No cookie: middleware has not run for this document (a cached shell, a route
+  // it does not match). Fall back to storage so events are still attributable.
+  const existing = readStore(VISITOR_KEY);
+  if (existing) return existing;
+  const fresh = uuid();
+  writeStore(VISITOR_KEY, fresh);
+  return fresh;
+}
+
+/**
+ * Session id on a 30-minute idle window. Stored with its own last-seen stamp
+ * rather than in sessionStorage, because a session must survive a tab reload
+ * and must expire on idleness — sessionStorage does the opposite of both.
+ */
+function sessionId(now: number): string {
+  const raw = readStore(SESSION_KEY);
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw) as { id?: string; lastSeen?: number };
+      if (
+        typeof parsed.id === "string" &&
+        typeof parsed.lastSeen === "number" &&
+        now - parsed.lastSeen < SESSION_IDLE_MS
+      ) {
+        writeStore(SESSION_KEY, JSON.stringify({ id: parsed.id, lastSeen: now }));
+        return parsed.id;
+      }
+    } catch {
+      /* corrupt value — mint a new session below */
+    }
+  }
+  const fresh = uuid();
+  writeStore(SESSION_KEY, JSON.stringify({ id: fresh, lastSeen: now }));
+  return fresh;
+}
+
+/**
+ * GA4's client id, from the `_ga` cookie it already sets.
+ *
+ * The cookie reads `GA1.1.1234567890.1699999999`; GA4's own client id is the last
+ * two segments joined — that exact string is what the Measurement Protocol needs
+ * to attach an event to the right user, and there is no way to reconstruct it
+ * afterwards.
+ *
+ * Reading it costs nothing and makes our numbers reconcilable with GA4's per
+ * visitor instead of only in aggregate.
+ */
+function gaClientId(): string | undefined {
+  try {
+    const match = document.cookie.match(/(?:^|;\s*)_ga=GA\d+\.\d+\.([\d.]+)/);
+    return match ? match[1] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * GA4's session id, from the per-stream `_ga_<MEASUREMENT_ID>` cookie.
+ *
+ * Matched by prefix because the suffix is the measurement id, which is a Studio
+ * -editable tracking value — hardcoding it here would break the moment someone
+ * changes the GA4 property, silently.
+ *
+ * Google has shipped two value layouts and a container can be on either:
+ *
+ *   GS1.1.1699999999.1.0.1699999999.0.0.0        ← session id is the 3rd segment
+ *   GS2.1.s1699999999$o3$g1$t1699999999$j45$l0   ← session id follows an `s`
+ *
+ * Both are read, because getting this wrong is not a degraded feature — it is a
+ * wrong number. Studio requires a GA4 session id before it will forward a form
+ * event to the Measurement Protocol, precisely because an MP event without one
+ * starts a **new** GA4 session, and an MP-started session has no referrer and no
+ * gclid, so GA4 files it as (direct)/(none). Returning undefined here therefore
+ * means "no GA4 forwarding"; returning a value parsed out of the wrong layout
+ * would mean fabricated sessions in someone's acquisition report.
+ */
+function gaSessionId(): string | undefined {
+  try {
+    const cookie = document.cookie.match(/(?:^|;\s*)_ga_[A-Z0-9]+=(GS[^;]+)/);
+    if (!cookie) return undefined;
+    const value = cookie[1]!;
+    // Try the current layout first; it is the one a new container gets.
+    const current = value.match(/^GS\d+\.\d+\.s(\d+)/);
+    if (current) return current[1];
+    const legacy = value.match(/^GS\d+\.\d+\.(\d+)/);
+    return legacy ? legacy[1] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isInternal(): boolean {
+  return readStore(INTERNAL_FLAG_KEY) === "1";
+}
+
+function deviceType(width: number): string {
+  if (width < 768) return "mobile";
+  if (width < 1024) return "tablet";
+  return "desktop";
+}
+
+/** Last-touch campaign params, from the one attribution store the site already keeps. */
+function utm(): Record<string, string> | undefined {
+  try {
+    const last = getAttribution()?.last;
+    if (!last) return undefined;
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(last)) {
+      if (k.startsWith("utm_") && typeof v === "string" && v) out[k.slice(4)] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// --- Queue ------------------------------------------------------------------
+
+let queue: QueuedEvent[] = [];
+let timer: ReturnType<typeof setTimeout> | null = null;
+let listenersBound = false;
+
+function send(batch: QueuedEvent[]): void {
+  if (batch.length === 0) return;
+  const body = JSON.stringify({ events: batch });
+
+  // `sendBeacon` first: it is the only path that survives the page going away,
+  // which is exactly when an abandon event is emitted.
+  try {
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      const blob = new Blob([body], { type: "application/json" });
+      if (navigator.sendBeacon(COLLECT_URL, blob)) return;
+    }
+  } catch {
+    /* fall through to fetch */
+  }
+
+  try {
+    void fetch(COLLECT_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      keepalive: true,
+    }).catch(() => {
+      /* analytics must never surface an error to the visitor */
+    });
+  } catch {
+    /* nothing further to try — drop the batch */
+  }
+}
+
+export function flushFunnelEvents(): void {
+  if (!consentGranted()) {
+    // Drop what is queued rather than holding it for a later grant: sending it
+    // afterwards would be sending data gathered without a basis.
+    queue = [];
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    return;
+  }
+  if (timer) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  const batch = queue;
+  queue = [];
+  send(batch);
+}
+
+function bindLifecycle(): void {
+  if (listenersBound || !isBrowser() || typeof document === "undefined") return;
+  listenersBound = true;
+  // `visibilitychange`, NOT `unload`: unload does not fire reliably on mobile
+  // Safari, which is precisely where abandons happen.
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flushFunnelEvents();
+  });
+}
+
+/**
+ * Queue one funnel event. Never throws, never blocks, and does nothing at all
+ * when the collector is switched off.
+ */
+export function trackFunnelEvent(name: string, props: FunnelEventProps = {}): void {
+  if (!isBrowser() || !name || !funnelAnalyticsEnabled()) return;
+  // Checked at queue time AND before each flush: consent revoked mid-session
+  // must stop the queue leaving, not merely stop new events joining it.
+  if (!consentGranted()) return;
+  try {
+    const now = Date.now();
+    const width = typeof window.innerWidth === "number" ? window.innerWidth : 0;
+
+    queue.push({
+      eventUid: uuid(),
+      visitorId: visitorId(),
+      sessionId: sessionId(now),
+      name,
+      path: props.path ?? window.location?.pathname ?? "/",
+      ...props,
+      // After `...props`, not before: the arm is not a caller's opinion.
+      variant: armFor(props.path ?? window.location?.pathname ?? "/"),
+      utm: utm(),
+      referrer: document?.referrer || undefined,
+      deviceType: width ? deviceType(width) : undefined,
+      viewport: width || undefined,
+      locale: document?.documentElement?.lang || undefined,
+      internal: isInternal() || isStudioPreview() || undefined,
+      gaClientId: gaClientId(),
+      gaSessionId: gaSessionId(),
+    });
+
+    bindLifecycle();
+
+    if (queue.length >= MAX_QUEUE) {
+      flushFunnelEvents();
+      return;
+    }
+    if (!timer) timer = setTimeout(flushFunnelEvents, FLUSH_INTERVAL_MS);
+  } catch {
+    /* a tracking bug must not break a page */
+  }
+}
+
+/**
+ * The current session id, or null — READ ONLY.
+ *
+ * Used by the lead submit path to stamp `WMM Session ID` on the GHL contact, so
+ * a lead can be traced back to the page, variant and source that produced it
+ * (wmm-studio docs/analytics/03-crm-join.md §3).
+ *
+ * Deliberately does NOT mint a session. An id minted here would be stamped on a
+ * contact while matching no row in `funnel_events` — a session that exists in the
+ * CRM and nowhere else, which is worse than an empty field because it looks like
+ * a resolvable lead that never resolves.
+ */
+export function currentSessionId(): string | null {
+  if (!isBrowser()) return null;
+  try {
+    const raw = readStore(SESSION_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as { id?: string; lastSeen?: number };
+    if (typeof parsed.id !== "string" || typeof parsed.lastSeen !== "number") {
+      return null;
+    }
+    // An expired session is not the one that produced this submit.
+    if (Date.now() - parsed.lastSeen >= SESSION_IDLE_MS) return null;
+    return parsed.id;
+  } catch {
+    return null;
+  }
+}
+
+/** Test-only: drop queue, timer and cached storage probe. */
+export function resetFunnelAnalytics(): void {
+  if (timer) clearTimeout(timer);
+  timer = null;
+  queue = [];
+  listenersBound = false;
+  storageWorks = null;
+  memory.clear();
+}