@drip-apex/sdk 0.1.0 → 0.3.0

package/src/replay-signal-state.ts

@@ -0,0 +1,100 @@
+import type { ReplaySignals } from "./replay";
+
+export const REPLAY_MAX_CLICK_SIGNALS = 100;
+export const REPLAY_MAX_NAV_SIGNALS = 50;
+export const REPLAY_MAX_ERROR_SIGNALS = 20;
+export const REPLAY_MAX_FORM_SIGNALS = 20;
+
+const MAX_SELECTOR_LENGTH = 500;
+const MAX_URL_LENGTH = 2_000;
+const MAX_ERROR_LENGTH = 200;
+const MAX_MUTATION_LATENCY_MS = 3_000;
+
+function finiteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function normalizeClicks(value: unknown): ReplaySignals["clicks"] {
+  if (!Array.isArray(value)) return [];
+  const normalized: ReplaySignals["clicks"] = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const candidate = item as Record<string, unknown>;
+    if (!finiteNumber(candidate.ts) || !finiteNumber(candidate.x) || !finiteNumber(candidate.y)) continue;
+    if (typeof candidate.selector !== "string") continue;
+    const selector = candidate.selector.trim();
+    if (!selector || selector.length > MAX_SELECTOR_LENGTH) continue;
+    const mutMs = candidate.mut_ms;
+    if (mutMs !== undefined && (!finiteNumber(mutMs) || mutMs < 0 || mutMs > MAX_MUTATION_LATENCY_MS)) continue;
+    normalized.push({
+      ts: candidate.ts,
+      selector,
+      x: Math.round(candidate.x),
+      y: Math.round(candidate.y),
+      ...(mutMs === undefined ? {} : { mut_ms: mutMs }),
+    });
+    if (normalized.length >= REPLAY_MAX_CLICK_SIGNALS) break;
+  }
+  return normalized;
+}
+
+function normalizeNav(value: unknown): ReplaySignals["nav"] {
+  if (!Array.isArray(value)) return [];
+  const normalized: ReplaySignals["nav"] = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const candidate = item as Record<string, unknown>;
+    if (!finiteNumber(candidate.ts) || typeof candidate.url !== "string") continue;
+    const url = candidate.url.trim();
+    if (!url || url.length > MAX_URL_LENGTH) continue;
+    normalized.push({ ts: candidate.ts, url });
+    if (normalized.length >= REPLAY_MAX_NAV_SIGNALS) break;
+  }
+  return normalized;
+}
+
+function normalizeErrors(value: unknown): ReplaySignals["errors"] {
+  if (!Array.isArray(value)) return [];
+  const normalized: ReplaySignals["errors"] = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const candidate = item as Record<string, unknown>;
+    if (!finiteNumber(candidate.ts) || typeof candidate.message !== "string") continue;
+    const message = candidate.message.trim();
+    if (!message) continue;
+    normalized.push({ ts: candidate.ts, message: message.slice(0, MAX_ERROR_LENGTH) });
+    if (normalized.length >= REPLAY_MAX_ERROR_SIGNALS) break;
+  }
+  return normalized;
+}
+
+function normalizeForms(value: unknown): ReplaySignals["form_focus"] {
+  if (!Array.isArray(value)) return [];
+  const selectors = new Set<string>();
+  const normalized: ReplaySignals["form_focus"] = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const candidate = item as Record<string, unknown>;
+    if (!finiteNumber(candidate.ts) || typeof candidate.selector !== "string") continue;
+    const selector = candidate.selector.trim();
+    if (!selector || selector.length > MAX_SELECTOR_LENGTH || selectors.has(selector)) continue;
+    selectors.add(selector);
+    normalized.push({ ts: candidate.ts, selector });
+    if (normalized.length >= REPLAY_MAX_FORM_SIGNALS) break;
+  }
+  return normalized;
+}
+
+export function normalizeReplaySignalState(value: Partial<Record<keyof ReplaySignals, unknown>> | undefined): ReplaySignals {
+  const scrollMaxPct = finiteNumber(value?.scroll_max_pct)
+    ? Math.max(0, Math.min(100, value.scroll_max_pct))
+    : 0;
+  return {
+    clicks: normalizeClicks(value?.clicks),
+    nav: normalizeNav(value?.nav),
+    errors: normalizeErrors(value?.errors),
+    form_focus: normalizeForms(value?.form_focus),
+    form_submit: normalizeForms(value?.form_submit),
+    scroll_max_pct: scrollMaxPct,
+  };
+}

package/src/replay-signals.test.ts

@@ -0,0 +1,249 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from "vitest";
+import { normalizeReplaySignalState } from "./replay-signal-state";
+import { createReplaySignalDeriver } from "./replay-signals";
+
+describe("replay signal derivation", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <form id="checkout-form">
+        <input id="email" />
+        <button id="buy" type="submit"><span data-test="buy-label">Buy</span></button>
+      </form>
+    `;
+    history.replaceState(null, "", "/products/example");
+  });
+
+  it("derives clustered clicks and mutation latency from rrweb events", () => {
+    const tracker = createReplaySignalDeriver();
+    const button = document.querySelector("#buy")!;
+    for (const [timestamp, x, y] of [
+      [1_000, 100, 100],
+      [1_500, 112, 110],
+      [2_100, 118, 116],
+    ]) {
+      tracker.accept(
+        { type: 3, timestamp, data: { source: 2, type: 2, x, y } },
+        button,
+      );
+    }
+    tracker.accept({ type: 3, timestamp: 2_500, data: { source: 0 } }, null);
+
+    const signals = tracker.snapshot();
+    expect(signals.clicks).toHaveLength(3);
+    expect(signals.clicks.at(-1)).toMatchObject({
+      selector: "button#buy",
+      x: 118,
+      y: 116,
+      mut_ms: 400,
+    });
+    expect(signals.clicks[0].mut_ms).toBe(1_500);
+    expect(signals.form_submit).toEqual([
+      { ts: 1_000, selector: "form#checkout-form" },
+    ]);
+  });
+
+  it("saturates session signal caps, keeps the oldest entries, and carries scroll maximum", () => {
+    const tracker = createReplaySignalDeriver(undefined, 50);
+    const button = document.querySelector("#buy")!;
+    const input = document.querySelector("#email")!;
+    Object.defineProperty(document.body, "scrollHeight", { configurable: true, value: 2_000 });
+    Object.defineProperty(window, "innerHeight", { configurable: true, value: 500 });
+
+    for (let index = 0; index < 105; index += 1) {
+      tracker.accept({
+        type: 3,
+        timestamp: index,
+        data: { source: 2, type: 2, x: index, y: index },
+      }, button);
+    }
+    for (let index = 0; index < 25; index += 1) {
+      tracker.accept({ type: 3, timestamp: 200 + index, data: { source: 2, type: 5 } }, input);
+      tracker.error(`error-${index}`, 300 + index);
+    }
+    for (let index = 0; index < 60; index += 1) {
+      history.pushState(null, "", `/products/${index}`);
+      tracker.accept({ type: 4, timestamp: 400 + index, data: { href: location.href } }, null);
+    }
+    tracker.accept({ type: 3, timestamp: 500, data: { source: 3, id: 1, y: 1_000 } }, null);
+    tracker.accept({ type: 3, timestamp: 600, data: { source: 3, id: 1, y: 1_500 } }, null);
+
+    const signals = tracker.snapshot();
+    expect(signals.clicks).toHaveLength(100);
+    expect(signals.clicks[0]?.x).toBe(0);
+    expect(signals.clicks.at(-1)?.x).toBe(99);
+    expect(signals.nav).toHaveLength(50);
+    expect(signals.nav[0]).toEqual({ ts: 50, url: "http://localhost:3000/products/example" });
+    expect(signals.nav.at(-1)?.url).toBe("http://localhost:3000/products/48");
+    expect(signals.form_submit).toHaveLength(1);
+    expect(signals.form_focus).toEqual([{ ts: 200, selector: "form#checkout-form" }]);
+    expect(signals.errors).toHaveLength(20);
+    expect(signals.errors.at(-1)?.message).toBe("error-19");
+    expect(signals.scroll_max_pct).toBe(100);
+    expect(tracker.snapshot()).toMatchObject({
+      clicks: signals.clicks,
+      nav: signals.nav,
+      errors: signals.errors,
+      form_focus: [{ ts: 200, selector: "form#checkout-form" }],
+      form_submit: [{ ts: 0, selector: "form#checkout-form" }],
+      scroll_max_pct: 100,
+    });
+  });
+
+  it("uses the matching stable selector attribute and finds nested submit controls", () => {
+    const tracker = createReplaySignalDeriver();
+    const label = document.querySelector("[data-test='buy-label']")!;
+
+    tracker.accept({
+      type: 3,
+      timestamp: 1_000,
+      data: { source: 2, type: 2, x: 10, y: 20 },
+    }, label);
+
+    const signals = tracker.snapshot();
+    expect(signals.clicks[0]?.selector).toBe('span[data-test="buy-label"]');
+    expect(signals.form_submit).toEqual([
+      { ts: 1_000, selector: "form#checkout-form" },
+    ]);
+  });
+
+  it("ignores nested-element scroll offsets and counts document scroll depth", () => {
+    const tracker = createReplaySignalDeriver();
+    Object.defineProperty(document.body, "scrollHeight", { configurable: true, value: 2_000 });
+    Object.defineProperty(window, "innerHeight", { configurable: true, value: 500 });
+
+    tracker.accept({ type: 3, timestamp: 1_000, data: { source: 3, id: 42, y: 1_500 } }, null);
+    expect(tracker.snapshot().scroll_max_pct).toBe(0);
+
+    tracker.accept({ type: 3, timestamp: 1_100, data: { source: 3, id: 1, y: 500 } }, null);
+    expect(tracker.snapshot().scroll_max_pct).toBe(50);
+  });
+
+  it("updates a boundary click mutation latency in the next cumulative snapshot", () => {
+    const tracker = createReplaySignalDeriver(undefined, 900);
+    const button = document.querySelector("#buy")!;
+
+    tracker.accept({
+      type: 3,
+      timestamp: 1_000,
+      data: { source: 2, type: 2, x: 10, y: 20 },
+    }, button);
+
+    const first = tracker.snapshot(1_000);
+    expect(first.clicks).toEqual([{
+      ts: 1_000,
+      selector: "button#buy",
+      x: 10,
+      y: 20,
+    }]);
+
+    tracker.accept({ type: 3, timestamp: 1_150, data: { source: 0 } }, null);
+
+    const second = tracker.snapshot(1_150);
+    expect(second.clicks).toEqual([
+      expect.objectContaining({
+        ts: 1_000,
+        selector: "button#buy",
+        mut_ms: 150,
+      }),
+    ]);
+    expect(first.clicks[0]?.mut_ms).toBeUndefined();
+  });
+
+  it("returns cumulative supersets across consecutive snapshots", () => {
+    const tracker = createReplaySignalDeriver(undefined, 900);
+    const button = document.querySelector("#buy")!;
+
+    tracker.accept({
+      type: 3,
+      timestamp: 1_000,
+      data: { source: 2, type: 2, x: 10, y: 20 },
+    }, button);
+    tracker.error("first", 1_050);
+    const first = tracker.snapshot();
+
+    history.pushState(null, "", "/products/next");
+    tracker.accept({
+      type: 3,
+      timestamp: 2_000,
+      data: { source: 2, type: 2, x: 30, y: 40 },
+    }, button);
+    tracker.error("second", 2_050);
+    const second = tracker.snapshot();
+
+    expect(second.clicks.slice(0, first.clicks.length)).toEqual(first.clicks);
+    expect(second.nav.slice(0, first.nav.length)).toEqual(first.nav);
+    expect(second.errors.slice(0, first.errors.length)).toEqual(first.errors);
+    expect(second.clicks).toHaveLength(2);
+    expect(second.nav).toHaveLength(2);
+    expect(second.errors).toHaveLength(2);
+  });
+
+  it("seeds navigation with the entry URL and records an A-to-B-to-A u-turn", () => {
+    const tracker = createReplaySignalDeriver(undefined, 1_000);
+
+    history.pushState(null, "", "/products/next");
+    tracker.accept({ type: 4, timestamp: 2_000, data: { href: location.href } }, null);
+    history.pushState(null, "", "/products/example");
+    tracker.accept({ type: 4, timestamp: 3_000, data: { href: location.href } }, null);
+
+    expect(tracker.snapshot().nav).toEqual([
+      { ts: 1_000, url: "http://localhost:3000/products/example" },
+      { ts: 2_000, url: "http://localhost:3000/products/next" },
+      { ts: 3_000, url: "http://localhost:3000/products/example" },
+    ]);
+  });
+
+  it("keeps page-one form focus in later snapshots without duplicating it", () => {
+    const tracker = createReplaySignalDeriver({
+      clicks: [],
+      nav: [{ ts: 50, url: "https://shop.example.test/entry" }],
+      errors: [],
+      form_focus: [{ ts: 100, selector: "form#checkout-form" }],
+      form_submit: [],
+      scroll_max_pct: 0,
+    });
+    const input = document.querySelector("#email")!;
+
+    tracker.accept({ type: 3, timestamp: 200, data: { source: 2, type: 5 } }, input);
+
+    expect(tracker.snapshot()).toMatchObject({
+      form_focus: [{ ts: 100, selector: "form#checkout-form" }],
+      form_submit: [],
+    });
+    expect(tracker.snapshot()).toMatchObject({
+      form_focus: [{ ts: 100, selector: "form#checkout-form" }],
+      form_submit: [],
+    });
+  });
+
+  it("validates, deduplicates, and caps persisted signal state", () => {
+    const form_focus = Array.from({ length: 25 }, (_, index) => ({
+      ts: index,
+      selector: `form#${index}`,
+    }));
+    form_focus.splice(1, 0,
+      { ts: 50, selector: "form#0" },
+      { ts: Number.NaN, selector: "form#invalid" },
+      { ts: 51, selector: "x".repeat(501) },
+    );
+
+    const normalized = normalizeReplaySignalState({
+      clicks: [{ ts: 1, selector: " button#buy ", x: 1.2, y: 2.8 }],
+      nav: [{ ts: 1, url: " https://shop.example.test/entry " }],
+      errors: [{ ts: 1, message: "x".repeat(250) }],
+      form_focus,
+      form_submit: [{ ts: 1, selector: "  " }, { ts: 2, selector: "form#valid" }],
+      scroll_max_pct: 120,
+    });
+
+    expect(normalized.clicks).toEqual([{ ts: 1, selector: "button#buy", x: 1, y: 3 }]);
+    expect(normalized.nav).toEqual([{ ts: 1, url: "https://shop.example.test/entry" }]);
+    expect(normalized.errors[0]?.message).toHaveLength(200);
+    expect(normalized.form_focus).toHaveLength(20);
+    expect(normalized.form_focus[0]).toEqual({ ts: 0, selector: "form#0" });
+    expect(new Set(normalized.form_focus.map(({ selector }) => selector)).size).toBe(20);
+    expect(normalized.form_submit).toEqual([{ ts: 2, selector: "form#valid" }]);
+    expect(normalized.scroll_max_pct).toBe(100);
+  });
+});

package/src/replay-signals.ts

@@ -0,0 +1,151 @@
+import type { ReplaySignals } from "./replay";
+import {
+  normalizeReplaySignalState,
+  REPLAY_MAX_CLICK_SIGNALS,
+  REPLAY_MAX_ERROR_SIGNALS,
+  REPLAY_MAX_FORM_SIGNALS,
+  REPLAY_MAX_NAV_SIGNALS,
+} from "./replay-signal-state";
+
+const EVENT_META = 4;
+const EVENT_INCREMENTAL = 3;
+const SOURCE_MUTATION = 0;
+const SOURCE_MOUSE_INTERACTION = 2;
+const SOURCE_SCROLL = 3;
+const RRWEB_DOCUMENT_ID = 1;
+const MOUSE_CLICK = 2;
+const MOUSE_FOCUS = 5;
+
+type RrwebEvent = {
+  type?: number;
+  timestamp?: number;
+  data?: Record<string, unknown>;
+};
+
+function selectorFor(element: Element): string {
+  const parts: string[] = [];
+  let current: Element | null = element;
+  while (current && current !== document.documentElement && parts.length < 4) {
+    const tag = current.tagName.toLowerCase();
+    const id = current.id && /^[A-Za-z][\w-]{0,80}$/.test(current.id) ? `#${current.id}` : "";
+    if (id) {
+      parts.unshift(`${tag}${id}`);
+      break;
+    }
+    const stableAttribute = ["data-testid", "data-test", "data-drip-id"]
+      .map((name) => ({ name, value: current?.getAttribute(name) }))
+      .find(({ value }) => value && /^[\w-]{1,80}$/.test(value));
+    if (stableAttribute?.value) {
+      parts.unshift(`${tag}[${stableAttribute.name}="${stableAttribute.value}"]`);
+      break;
+    }
+    let nth = 1;
+    let sibling = current.previousElementSibling;
+    while (sibling) {
+      if (sibling.tagName === current.tagName) nth += 1;
+      sibling = sibling.previousElementSibling;
+    }
+    parts.unshift(`${tag}:nth-of-type(${nth})`);
+    current = current.parentElement;
+  }
+  return parts.join(" > ").slice(0, 500);
+}
+
+function formFor(target: Element | null): Element | null {
+  if (!target) return null;
+  return target.tagName.toLowerCase() === "form" ? target : target.closest("form");
+}
+
+function submitTarget(target: Element | null): boolean {
+  if (!target) return false;
+  const control = target.closest("button,input");
+  if (!control) return false;
+  const tag = control.tagName.toLowerCase();
+  if (tag === "button") return (control.getAttribute("type") || "submit").toLowerCase() === "submit";
+  return tag === "input" && control.getAttribute("type")?.toLowerCase() === "submit";
+}
+
+export function createReplaySignalDeriver(signalState?: ReplaySignals, captureStartedAt?: number): {
+  accept: (event: RrwebEvent, target: Element | null) => void;
+  error: (message: string, ts?: number) => void;
+  snapshot: (now?: number) => ReplaySignals;
+  submit: (target: Element | null, ts?: number) => void;
+};
+export function createReplaySignalDeriver(signalState?: ReplaySignals, captureStartedAt = Date.now()) {
+  const signals = normalizeReplaySignalState(signalState);
+  const currentUrl = typeof location !== "undefined" ? location.href : "";
+  // Array.prototype.at is ES2022 — the SDK targets ES2018 browsers and
+  // esbuild does not polyfill it, so index access is required here (it also
+  // broke build:types declaration emit in the Commerce Lab promotion lane).
+  const previousUrl = signals.nav[signals.nav.length - 1]?.url ?? "";
+  if (currentUrl && currentUrl !== previousUrl && signals.nav.length < REPLAY_MAX_NAV_SIGNALS) {
+    signals.nav.push({ ts: captureStartedAt, url: currentUrl.slice(0, 2_000) });
+  }
+  let lastUrl = currentUrl || previousUrl;
+  const focusedForms = new Set(signals.form_focus.map((signal) => signal.selector));
+  const submittedForms = new Set(signals.form_submit.map((signal) => signal.selector));
+  const submit = (target: Element | null, ts = Date.now()) => {
+    const form = formFor(target);
+    const selector = form ? selectorFor(form) : "";
+    if (selector && !submittedForms.has(selector) && signals.form_submit.length < REPLAY_MAX_FORM_SIGNALS) {
+      submittedForms.add(selector);
+      signals.form_submit.push({ ts, selector });
+    }
+  };
+  const accept = (event: RrwebEvent, target: Element | null) => {
+    const ts = typeof event.timestamp === "number" ? event.timestamp : Date.now();
+    const currentUrl = typeof location !== "undefined" ? location.href : "";
+    if (currentUrl && currentUrl !== lastUrl) {
+      lastUrl = currentUrl;
+      if (signals.nav.length < REPLAY_MAX_NAV_SIGNALS) signals.nav.push({ ts, url: currentUrl.slice(0, 2_000) });
+    }
+    if (event.type === EVENT_META && typeof event.data?.href === "string" && event.data.href !== lastUrl) {
+      lastUrl = event.data.href;
+      if (signals.nav.length < REPLAY_MAX_NAV_SIGNALS) signals.nav.push({ ts, url: event.data.href.slice(0, 2_000) });
+    }
+    if (event.type !== EVENT_INCREMENTAL) return;
+    if (event.data?.source === SOURCE_MUTATION) {
+      for (const click of signals.clicks) {
+        const elapsed = ts - click.ts;
+        if (elapsed >= 0 && elapsed <= 3_000 && click.mut_ms === undefined) click.mut_ms = elapsed;
+      }
+      return;
+    }
+    if (event.data?.source === SOURCE_SCROLL) {
+      if (event.data.id !== RRWEB_DOCUMENT_ID) return;
+      const y = typeof event.data.y === "number" ? event.data.y : window.scrollY;
+      const height = Math.max(1, document.body?.scrollHeight ?? 0, document.documentElement?.scrollHeight ?? 0);
+      signals.scroll_max_pct = Math.max(signals.scroll_max_pct, Math.max(0, Math.min(100, Math.round(((y + Math.max(1, window.innerHeight)) / height) * 100))));
+      return;
+    }
+    if (event.data?.source !== SOURCE_MOUSE_INTERACTION || !target) return;
+    if (event.data.type === MOUSE_CLICK) {
+      if (signals.clicks.length >= REPLAY_MAX_CLICK_SIGNALS) return;
+      const click = {
+        ts,
+        selector: selectorFor(target),
+        x: Math.round(typeof event.data.x === "number" ? event.data.x : 0),
+        y: Math.round(typeof event.data.y === "number" ? event.data.y : 0),
+      };
+      signals.clicks.push(click);
+      if (submitTarget(target)) submit(target, ts);
+    } else if (event.data.type === MOUSE_FOCUS) {
+      const form = formFor(target);
+      if (!form || signals.form_focus.length >= REPLAY_MAX_FORM_SIGNALS) return;
+      const selector = selectorFor(form);
+      if (!focusedForms.has(selector)) {
+        focusedForms.add(selector);
+        signals.form_focus.push({ ts, selector });
+      }
+    }
+  };
+  const snapshot = (_now = Date.now()) => normalizeReplaySignalState(signals);
+  return {
+    accept,
+    error(message: string, ts = Date.now()) {
+      if (signals.errors.length < REPLAY_MAX_ERROR_SIGNALS) signals.errors.push({ ts, message: message.slice(0, 200) });
+    },
+    snapshot,
+    submit,
+  };
+}