@drip-apex/sdk 0.1.0 → 0.2.0

package/src/replay.ts

@@ -0,0 +1,514 @@
+import { normalizeEndpoint } from "./endpoint";
+import {
+  REPLAY_CONTRACT_VERSION,
+  REPLAY_MAX_BLOCKS,
+  REPLAY_MAX_PAYLOAD_B64_CHARS,
+} from "@drip/event-schema/replay-contract";
+import type { Assignment, Experiment } from "./types";
+import { normalizeReplaySignalState } from "./replay-signal-state";
+
+export const REPLAY_RECORDER_FILENAME = "drip.replay-recorder.js";
+export const REPLAY_FLUSH_INTERVAL_MS = 10_000;
+export const REPLAY_UNCOMPRESSED_BLOCK_BYTES = 512 * 1024;
+export const REPLAY_MAX_DURATION_MS = 15 * 60 * 1000;
+export const REPLAY_MAX_COMPRESSED_BYTES = 4 * 1024 * 1024;
+export const REPLAY_SAMPLE_KEY_PREFIX = "drip_rp:";
+export const REPLAY_PROGRESS_KEY_PREFIX = "drip_replay_progress:";
+
+const REPLAY_SCRIPT_ID = "drip-replay-recorder";
+// Shopify and common hosted checkout paths stay excluded until a later unit
+// adds an explicit checkout policy.
+export const REPLAY_EXCLUDED_CHECKOUT_PATHS = [
+  "/checkout",
+  "/checkouts/",
+  "/cart/checkout",
+] as const;
+
+export type ReplayAssignment = {
+  experiment_id: string;
+  variation_id: string;
+};
+
+type ReplayEvent = {
+  type?: number;
+  timestamp?: number;
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+export type ReplayRecorderEmission = {
+  event?: ReplayEvent;
+};
+
+export type ReplayRecorderApi = {
+  start: (options: {
+    emit: (emission: ReplayRecorderEmission) => void;
+    signalState?: ReplaySignals;
+  }) => () => void;
+  compress: (bytes: Uint8Array) => Promise<Uint8Array>;
+  compressSync: (bytes: Uint8Array) => Uint8Array;
+  takeSignals: () => ReplaySignals;
+  version: string;
+};
+
+type ReplayClickSignal = {
+  ts: number;
+  selector: string;
+  x: number;
+  y: number;
+  mut_ms?: number;
+};
+
+export type ReplaySignals = {
+  clicks: ReplayClickSignal[];
+  nav: Array<{ ts: number; url: string }>;
+  errors: Array<{ ts: number; message: string }>;
+  form_focus: Array<{ ts: number; selector: string }>;
+  form_submit: Array<{ ts: number; selector: string }>;
+  scroll_max_pct: number;
+};
+
+export type ReplayEnvelope = {
+  contract: 1;
+  shop_id: string;
+  visitor_id: string;
+  session_id: string;
+  seq: number;
+  first_ts: number;
+  last_ts: number;
+  event_count: number;
+  url: string;
+  environment: string;
+  qa_mode: 0 | 1;
+  qa_session_id?: string;
+  sdk_version: string;
+  assignments: ReplayAssignment[];
+  codec: "deflate";
+  payload_b64: string;
+  signals: ReplaySignals;
+};
+
+export type ReplayController = {
+  stop: (discard?: boolean) => void;
+  isStopped: () => boolean;
+  update: (assignments: Assignment[], experiments: Experiment[]) => void;
+};
+
+type ReplayControllerOptions = {
+  assignments: Assignment[];
+  experiments: Experiment[];
+  recorderUrl: string;
+  endpoint: string;
+  shopId: string;
+  visitorId: string;
+  sessionId: string;
+  environment: string;
+  qaMode: boolean;
+  qaSessionId?: string;
+  sdkVersion: string;
+  ingestSignature?: string;
+  isTrackingBlocked: () => boolean;
+  loadRecorder?: (url: string) => Promise<ReplayRecorderApi>;
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function normalizeReplaySampleRate(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value)
+    ? clamp(value, 0, 1)
+    : 0.05;
+}
+
+function replaySampleKey(assignment: Assignment): string {
+  return `${REPLAY_SAMPLE_KEY_PREFIX}${assignment.experimentId}:${assignment.variationId}`;
+}
+
+function sampledIn(assignment: Assignment, sampleRate: number): boolean {
+  try {
+    const key = replaySampleKey(assignment);
+    const existing = sessionStorage.getItem(key);
+    if (existing === "1") return true;
+    if (existing === "0") return false;
+    const selected = sampleRate >= 1
+      ? true
+      : sampleRate <= 0
+        ? false
+        : Math.random() < sampleRate;
+    sessionStorage.setItem(key, selected ? "1" : "0");
+    return selected;
+  } catch {
+    if (sampleRate >= 1) return true;
+    if (sampleRate <= 0) return false;
+    return Math.random() < sampleRate;
+  }
+}
+
+export function resolveReplayAssignments(
+  assignments: Assignment[],
+  experiments: Experiment[],
+): ReplayAssignment[] {
+  const experimentsById = new Map(experiments.map((experiment) => [experiment.id, experiment]));
+  return assignments.flatMap((assignment) => {
+    const capture = experimentsById.get(assignment.experimentId)?.replayCapture;
+    if (!capture?.enabled) return [];
+    if (!sampledIn(assignment, normalizeReplaySampleRate(capture.sampleRate))) return [];
+    return [{
+      experiment_id: assignment.experimentId,
+      variation_id: assignment.variationId,
+    }];
+  });
+}
+
+export function isReplayCheckoutPath(pathname: string): boolean {
+  const path = pathname.toLowerCase();
+  return REPLAY_EXCLUDED_CHECKOUT_PATHS.some((excluded) =>
+    excluded.endsWith("/") ? path.startsWith(excluded) : path === excluded || path.startsWith(`${excluded}/`),
+  );
+}
+
+export function resolveReplayRecorderUrl(input: {
+  configuredUrl?: string;
+  scriptSrc?: string;
+  pageUrl?: string;
+}): string | null {
+  if (input.configuredUrl) {
+    try {
+      const configuredUrl = new URL(input.configuredUrl);
+      if (configuredUrl.protocol === "http:" || configuredUrl.protocol === "https:") {
+        return configuredUrl.toString();
+      }
+    } catch {}
+  }
+  if (!input.scriptSrc) return null;
+  try {
+    const scriptUrl = new URL(input.scriptSrc, input.pageUrl);
+    if (/^\/sdk\/[^/]+\/[^/]+\.js$/.test(scriptUrl.pathname)) {
+      scriptUrl.pathname = scriptUrl.pathname.replace(/[^/]+\.js$/, REPLAY_RECORDER_FILENAME);
+    } else if (/^\/drip(?:\.[A-Za-z0-9_-]+)*\.js$/.test(scriptUrl.pathname)) {
+      scriptUrl.pathname = scriptUrl.pathname.replace(/[^/]+\.js$/, REPLAY_RECORDER_FILENAME);
+    } else {
+      return null;
+    }
+    scriptUrl.search = "";
+    scriptUrl.hash = "";
+    return scriptUrl.toString();
+  } catch {
+    return null;
+  }
+}
+
+type ReplayRecorderGlobal = typeof globalThis & {
+  __dripReplayRecorder?: ReplayRecorderApi;
+};
+
+export function loadReplayRecorder(
+  recorderUrl: string,
+  documentLike: Document = document,
+): Promise<ReplayRecorderApi> {
+  const existingApi = (globalThis as ReplayRecorderGlobal).__dripReplayRecorder;
+  if (existingApi?.start) return Promise.resolve(existingApi);
+
+  return new Promise((resolve, reject) => {
+    documentLike.getElementById(REPLAY_SCRIPT_ID)?.remove();
+    const script = documentLike.createElement("script");
+    script.id = REPLAY_SCRIPT_ID;
+    script.src = recorderUrl;
+    script.async = true;
+    script.crossOrigin = "anonymous";
+    script.onload = () => {
+      const api = (globalThis as ReplayRecorderGlobal).__dripReplayRecorder;
+      if (!api || typeof api.start !== "function") {
+        script.remove();
+        reject(new Error("Replay recorder did not expose a start function"));
+        return;
+      }
+      resolve(api);
+    };
+    script.onerror = () => {
+      script.remove();
+      reject(new Error("Replay recorder failed to load"));
+    };
+    (documentLike.head || documentLike.documentElement).appendChild(script);
+  });
+}
+
+function eventTimestamp(event: ReplayEvent | undefined, fallback: number): number {
+  return typeof event?.timestamp === "number" && Number.isFinite(event.timestamp)
+    ? event.timestamp
+    : fallback;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += 32_768) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 32_768));
+  }
+  return btoa(binary);
+}
+
+function replayEndpoint(endpoint: string): string {
+  return normalizeEndpoint(endpoint) + "/replay-blocks";
+}
+
+type BufferedReplayBlock = {
+  seq: number;
+  events: ReplayEvent[];
+  signals: ReplaySignals;
+  url: string;
+  assignments: ReplayAssignment[];
+};
+
+type ReplayProgress = ReplaySignals & {
+  nextSeq: number;
+  totalCompressedBytes: number;
+  elapsedMs: number;
+  terminal: boolean;
+};
+
+function finiteNonnegativeInteger(value: unknown): number {
+  return Number.isFinite(value) && (value as number) >= 0 ? Math.floor(value as number) : 0;
+}
+
+function readReplayProgress(key: string): ReplayProgress {
+  let stored: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(sessionStorage.getItem(key) ?? "{}");
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      stored = parsed as Record<string, unknown>;
+    }
+  } catch {}
+  const signalState = normalizeReplaySignalState(stored);
+  return {
+    nextSeq: finiteNonnegativeInteger(stored.nextSeq),
+    totalCompressedBytes: finiteNonnegativeInteger(stored.totalCompressedBytes),
+    elapsedMs: finiteNonnegativeInteger(stored.elapsedMs),
+    terminal: stored.terminal === true,
+    ...signalState,
+  };
+}
+
+export async function startReplayCapture(
+  options: ReplayControllerOptions,
+): Promise<ReplayController | null> {
+  if (options.isTrackingBlocked()) return null;
+  if (typeof location === "undefined" || isReplayCheckoutPath(location.pathname)) return null;
+  let activeAssignments = resolveReplayAssignments(options.assignments, options.experiments);
+  if (activeAssignments.length === 0) return null;
+
+  const progressKey = `${REPLAY_PROGRESS_KEY_PREFIX}${options.sessionId}`;
+  const progress = readReplayProgress(progressKey);
+  const writeProgress = () => {
+    try { sessionStorage.setItem(progressKey, JSON.stringify(progress)); } catch {}
+  };
+  if (
+    progress.terminal
+    || progress.nextSeq >= REPLAY_MAX_BLOCKS
+    || progress.totalCompressedBytes >= REPLAY_MAX_COMPRESSED_BYTES
+    || progress.elapsedMs >= REPLAY_MAX_DURATION_MS
+  ) {
+    progress.terminal = true;
+    writeProgress();
+    return null;
+  }
+
+  const recorder = await (options.loadRecorder ?? loadReplayRecorder)(options.recorderUrl);
+  if (options.isTrackingBlocked() || isReplayCheckoutPath(location.pathname)) return null;
+
+  const encoder = new TextEncoder();
+  let bufferedEvents: ReplayEvent[] = [];
+  let bufferedBytes = 2;
+  let bufferedUrl = location.href.slice(0, 2_000);
+  let stopped = false;
+  let discarded = false;
+  let flushChain = Promise.resolve();
+  const pageStartedAt = Date.now();
+  const elapsedBeforePage = progress.elapsedMs;
+
+  const persistProgress = (terminal = progress.terminal) => {
+    progress.elapsedMs = Math.min(
+      REPLAY_MAX_DURATION_MS,
+      elapsedBeforePage + Math.max(0, Date.now() - pageStartedAt),
+    );
+    progress.terminal = terminal;
+    writeProgress();
+  };
+
+  const postBlock = async (block: BufferedReplayBlock, sync: boolean) => {
+    if (discarded) return;
+    if (options.isTrackingBlocked()) {
+      stop(true);
+      return;
+    }
+    const raw = encoder.encode(JSON.stringify(block.events));
+    const compressed = sync ? recorder.compressSync(raw) : await recorder.compress(raw);
+    if (discarded) return;
+    if (options.isTrackingBlocked()) {
+      stop(true);
+      return;
+    }
+    const payloadB64 = bytesToBase64(compressed);
+    if (payloadB64.length > REPLAY_MAX_PAYLOAD_B64_CHARS) {
+      stop(true);
+      return;
+    }
+    if (progress.totalCompressedBytes + compressed.length > REPLAY_MAX_COMPRESSED_BYTES) {
+      stopForBudget();
+      return;
+    }
+    progress.totalCompressedBytes += compressed.length;
+    persistProgress();
+    const firstTs = eventTimestamp(block.events[0], Date.now());
+    const lastTs = eventTimestamp(block.events[block.events.length - 1], firstTs);
+    const envelope: ReplayEnvelope = {
+      contract: REPLAY_CONTRACT_VERSION,
+      shop_id: options.shopId,
+      visitor_id: options.visitorId,
+      session_id: options.sessionId,
+      seq: block.seq,
+      first_ts: firstTs,
+      last_ts: lastTs,
+      event_count: block.events.length,
+      url: block.url,
+      environment: options.environment,
+      qa_mode: options.qaMode ? 1 : 0,
+      ...(options.qaMode && options.qaSessionId ? { qa_session_id: options.qaSessionId } : {}),
+      sdk_version: options.sdkVersion,
+      assignments: block.assignments,
+      codec: "deflate",
+      payload_b64: payloadB64,
+      signals: block.signals,
+    };
+    const body = JSON.stringify(envelope);
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (options.shopId) headers["X-Drip-Shop"] = options.shopId;
+    if (options.ingestSignature) headers["X-Drip-Signature"] = options.ingestSignature;
+    try {
+      await fetch(replayEndpoint(options.endpoint), {
+        method: "POST",
+        headers,
+        body,
+        keepalive: sync && encoder.encode(body).length < 60_000,
+      });
+    } catch {}
+    if (progress.totalCompressedBytes >= REPLAY_MAX_COMPRESSED_BYTES) stop();
+  };
+
+  const takeBlock = (): BufferedReplayBlock | null => {
+    if (!bufferedEvents.length || progress.nextSeq >= REPLAY_MAX_BLOCKS) return null;
+    const signals = recorder.takeSignals();
+    const block = {
+      seq: progress.nextSeq,
+      events: bufferedEvents,
+      signals,
+      url: bufferedUrl,
+      assignments: [...activeAssignments],
+    };
+    progress.nextSeq += 1;
+    Object.assign(progress, normalizeReplaySignalState(signals));
+    persistProgress();
+    bufferedEvents = [];
+    bufferedBytes = 2;
+    bufferedUrl = location.href.slice(0, 2_000);
+    return block;
+  };
+
+  const flush = (sync = false) => {
+    const block = takeBlock();
+    if (!block) {
+      if (progress.nextSeq >= REPLAY_MAX_BLOCKS) stop();
+      return;
+    }
+    if (sync) {
+      void postBlock(block, true);
+    } else {
+      flushChain = flushChain
+        .then(() => postBlock(block, false))
+        .catch(() => undefined);
+    }
+    if (progress.nextSeq >= REPLAY_MAX_BLOCKS) stop();
+  };
+
+  const onEmission = (emission: ReplayRecorderEmission) => {
+    if (stopped || discarded || !emission.event) return;
+    if (options.isTrackingBlocked() || isReplayCheckoutPath(location.pathname)) {
+      stop(true);
+      return;
+    }
+    if (!bufferedEvents.length) bufferedUrl = location.href.slice(0, 2_000);
+    bufferedBytes += encoder.encode(JSON.stringify(emission.event)).length
+      + (bufferedEvents.length ? 1 : 0);
+    bufferedEvents.push(emission.event);
+    if (bufferedBytes >= REPLAY_UNCOMPRESSED_BLOCK_BYTES) flush();
+  };
+
+  let stopRecorder = recorder.start({
+    emit: onEmission,
+    signalState: normalizeReplaySignalState(progress),
+  });
+  Object.assign(progress, normalizeReplaySignalState(recorder.takeSignals()));
+  persistProgress();
+  const interval = window.setInterval(() => flush(), REPLAY_FLUSH_INTERVAL_MS);
+  const duration = window.setTimeout(() => {
+    flush();
+    stop();
+  }, REPLAY_MAX_DURATION_MS - progress.elapsedMs);
+  const onPageLifecycle = () => {
+    persistProgress();
+    flush(true);
+  };
+  const onVisibilityChange = () => {
+    if (document.visibilityState === "hidden") {
+      persistProgress();
+      flush(true);
+    }
+  };
+  window.addEventListener("pagehide", onPageLifecycle);
+  document.addEventListener("visibilitychange", onVisibilityChange);
+
+  function stopCapture(discard: boolean, terminal: boolean): void {
+    if (discard) {
+      discarded = true;
+      bufferedEvents = [];
+      bufferedBytes = 2;
+    }
+    if (stopped) return;
+    stopped = true;
+    if (!discard || terminal) persistProgress(terminal);
+    window.clearInterval(interval);
+    window.clearTimeout(duration);
+    window.removeEventListener("pagehide", onPageLifecycle);
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+    stopRecorder();
+    stopRecorder = () => {};
+  }
+
+  function stopForBudget(): void {
+    stopCapture(true, true);
+  }
+
+  function stop(discard = false): void {
+    stopCapture(discard, discard ? progress.terminal : true);
+  }
+
+  return {
+    stop,
+    isStopped: () => stopped,
+    update(assignments, experiments) {
+      if (options.isTrackingBlocked()) {
+        stop(true);
+        return;
+      }
+      const known = new Set(activeAssignments.map((assignment) =>
+        `${assignment.experiment_id}:${assignment.variation_id}`));
+      for (const assignment of resolveReplayAssignments(assignments, experiments)) {
+        const key = `${assignment.experiment_id}:${assignment.variation_id}`;
+        if (!known.has(key)) {
+          known.add(key);
+          activeAssignments.push(assignment);
+        }
+      }
+    },
+  };
+}

package/src/router.test.ts

@@ -1,5 +1,5 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { observeRouteChanges } from "./router";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { observePollingChanges, observeRouteChanges } from "./router";
 
 describe("route observer", () => {
   const originalWindow = (globalThis as any).window;
@@ -40,15 +40,53 @@ describe("route observer", () => {
       removeEventListener(type: string, listener: () => void) {
         listeners.get(type)?.delete(listener);
       },
+      clearInterval(id: number) { globalThis.clearInterval(id); },
+      setInterval(callback: TimerHandler, ms?: number) {
+        return globalThis.setInterval(callback, ms);
+      },
     };
   });
 
   afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
     (globalThis as any).window = originalWindow;
     (globalThis as any).location = originalLocation;
     (globalThis as any).history = originalHistory;
   });
 
+  it("observes URL changes without a History event and stops after unsubscribe", async () => {
+    vi.useFakeTimers();
+    const events: string[] = [];
+    const stop = observePollingChanges((event) => events.push(event.nextUrl), 25);
+
+    setLocation("https://example.test/collections/all");
+    await vi.advanceTimersByTimeAsync(25);
+    expect(events).toEqual(["https://example.test/collections/all"]);
+
+    stop();
+    setLocation("https://example.test/pages/about");
+    await vi.advanceTimersByTimeAsync(50);
+    expect(events).toHaveLength(1);
+  });
+
+  it("shares URL comparison between History and polling detectors", async () => {
+    vi.useFakeTimers();
+    const events: string[] = [];
+    const stop = observeRouteChanges(
+      "history",
+      (event) => events.push(event.reason),
+      { pollingIntervalMs: 25 },
+    );
+
+    setLocation("https://example.test/collections/all");
+    (globalThis as any).history.pushState({}, "", "/collections/all");
+    await vi.advanceTimersByTimeAsync(25);
+
+    expect(events).toEqual(["pushState"]);
+    stop();
+  });
+
   it("observes pure hashchange events when history does not emit popstate", () => {
     const events: Array<{
       previousUrl: string;
@@ -75,4 +113,25 @@ describe("route observer", () => {
     dispatch("hashchange");
     expect(events).toHaveLength(1);
   });
+
+  it("contains observer failures and continues delivering later history changes", () => {
+    const events: string[] = [];
+    const errors: unknown[] = [];
+    const stop = observeRouteChanges("history", (event) => {
+      events.push(event.nextUrl);
+      if (events.length === 1) throw new Error("route observer failed");
+    }, { onObserverError: (error) => errors.push(error) });
+
+    setLocation("https://example.test/collections/first");
+    expect(() => (globalThis as any).history.pushState({}, "", "/collections/first")).not.toThrow();
+    setLocation("https://example.test/collections/second");
+    expect(() => (globalThis as any).history.pushState({}, "", "/collections/second")).not.toThrow();
+
+    expect(events).toEqual([
+      "https://example.test/collections/first",
+      "https://example.test/collections/second",
+    ]);
+    expect(errors).toHaveLength(1);
+    stop();
+  });
 });