@drip-apex/sdk 0.1.0

package/src/config-fetch.test.ts

@@ -0,0 +1,325 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+function makeStorage() {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key: string) => (map.has(key) ? map.get(key)! : null),
+    key: (index: number) => Array.from(map.keys())[index] ?? null,
+    removeItem: (key: string) => { map.delete(key); },
+    setItem: (key: string, value: string) => { map.set(key, value); },
+    get length() { return map.size; },
+  };
+}
+
+function makeClassList() {
+  const values = new Set<string>();
+  return {
+    add: (...tokens: string[]) => { tokens.forEach((token) => values.add(token)); },
+    remove: (...tokens: string[]) => { tokens.forEach((token) => values.delete(token)); },
+    contains: (token: string) => values.has(token),
+  };
+}
+
+function configPayload() {
+  return {
+    experiments: [
+      {
+        id: "exp_late",
+        status: "running",
+        trafficAllocation: 1,
+        variations: [
+          { id: "var_late", weight: 1, mutations: [], isControl: false },
+        ],
+      },
+      {
+        id: "exp_late_second",
+        status: "running",
+        trafficAllocation: 1,
+        variations: [
+          {
+            id: "var_late_second",
+            weight: 1,
+            mutations: [],
+            isControl: false,
+          },
+        ],
+      },
+    ],
+    exclusionGroups: [
+      {
+        id: "group_late",
+        name: "Late config group",
+        epoch: 1,
+        members: [
+          { experimentId: "exp_late", share: 0.5 },
+          { experimentId: "exp_late_second", share: 0.5 },
+        ],
+      },
+    ],
+    profile: { platform: "auto", version: 1 },
+  };
+}
+
+async function flushPromises(times = 4) {
+  for (let i = 0; i < times; i += 1) {
+    await Promise.resolve();
+  }
+}
+
+// Wait for an async condition by driving the fake clock — fixed microtask
+// flush counts are scheduler-dependent (Node 22 CI needed more turns than
+// local Node 26) and real setTimeout never fires under fake timers.
+async function waitFor(condition: () => boolean, maxTicks = 200) {
+  for (let i = 0; i < maxTicks && !condition(); i += 1) {
+    await vi.advanceTimersByTimeAsync(10);
+  }
+}
+
+describe("async config fetch contract", () => {
+  const originalWindow = (globalThis as any).window;
+  const originalDocument = (globalThis as any).document;
+  const originalHistory = (globalThis as any).history;
+  const originalLocation = (globalThis as any).location;
+  const originalNavigator = Object.getOwnPropertyDescriptor(globalThis, "navigator");
+  const originalLocalStorage = (globalThis as any).localStorage;
+  const originalSessionStorage = (globalThis as any).sessionStorage;
+  const originalCustomEvent = (globalThis as any).CustomEvent;
+  const originalFetch = globalThis.fetch;
+  const originalAbortController = (globalThis as any).AbortController;
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    delete (globalThis as any).__drip;
+
+    const appended: Array<{ id?: string; remove?: () => void }> = [];
+    const windowStub: Record<string, any> = {
+      addEventListener: vi.fn(),
+      clearInterval: (id: number) => clearInterval(id),
+      clearTimeout: (id: number) => clearTimeout(id),
+      innerHeight: 800,
+      removeEventListener: vi.fn(),
+      setInterval: (fn: TimerHandler, ms?: number) => setInterval(fn, ms),
+      setTimeout: (fn: TimerHandler, ms?: number) => setTimeout(fn, ms),
+    };
+    windowStub.self = windowStub;
+    windowStub.top = windowStub;
+
+    (globalThis as any).window = windowStub;
+    (globalThis as any).location = {
+      hash: "",
+      hostname: "plain.test",
+      href: "https://plain.test/",
+      origin: "https://plain.test",
+      pathname: "/",
+      search: "",
+    };
+    (globalThis as any).history = {
+      pushState: vi.fn(),
+      replaceState: vi.fn(),
+    };
+    (globalThis as any).document = {
+      addEventListener: vi.fn(),
+      body: { scrollHeight: 1200 },
+      createElement: vi.fn((tag: string) => ({
+        id: "",
+        remove: vi.fn(),
+        set textContent(_value: string) {},
+        tagName: tag.toUpperCase(),
+      })),
+      dispatchEvent: vi.fn(),
+      documentElement: {
+        classList: makeClassList(),
+        scrollHeight: 1200,
+      },
+      getElementById: vi.fn((id: string) => appended.find((el) => el.id === id) ?? null),
+      head: {
+        appendChild: vi.fn((el: { id?: string; remove?: () => void }) => {
+          appended.push(el);
+          return el;
+        }),
+      },
+      querySelector: vi.fn(() => null),
+      querySelectorAll: vi.fn(() => []),
+      referrer: "",
+      removeEventListener: vi.fn(),
+      title: "Plain probe",
+    };
+    Object.defineProperty(globalThis, "navigator", {
+      configurable: true,
+      value: { userAgent: "Mozilla/5.0", doNotTrack: "0" },
+    });
+    (globalThis as any).localStorage = makeStorage();
+    (globalThis as any).sessionStorage = makeStorage();
+    (globalThis as any).CustomEvent = class CustomEvent {
+      type: string;
+      detail: unknown;
+      constructor(type: string, init?: { detail?: unknown }) {
+        this.type = type;
+        this.detail = init?.detail;
+      }
+    };
+    globalThis.fetch = vi.fn(async () => new Response("ok", { status: 202 })) as any;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    delete (globalThis as any).__drip;
+    (globalThis as any).window = originalWindow;
+    (globalThis as any).document = originalDocument;
+    (globalThis as any).history = originalHistory;
+    (globalThis as any).location = originalLocation;
+    if (originalNavigator) {
+      Object.defineProperty(globalThis, "navigator", originalNavigator);
+    } else {
+      delete (globalThis as any).navigator;
+    }
+    (globalThis as any).localStorage = originalLocalStorage;
+    (globalThis as any).sessionStorage = originalSessionStorage;
+    (globalThis as any).CustomEvent = originalCustomEvent;
+    (globalThis as any).AbortController = originalAbortController;
+    globalThis.fetch = originalFetch;
+  });
+
+  it("bounds fetchWithTimeout when AbortController is unavailable", async () => {
+    delete (globalThis as any).AbortController;
+    globalThis.fetch = vi.fn(() => new Promise<Response>(() => {})) as any;
+    const { __test } = await import("./index");
+
+    const promise = __test.fetchWithTimeout("https://events.test/config", 25);
+    const expectation = expect(promise).rejects.toMatchObject({ name: "AbortError" });
+    await vi.advanceTimersByTimeAsync(25);
+
+    await expectation;
+    expect(globalThis.fetch).toHaveBeenCalledWith("https://events.test/config");
+  });
+
+  it("uses the anti-flicker timeout as the first config fetch budget when armed", async () => {
+    const aborts: number[] = [];
+    globalThis.fetch = vi.fn((_input: RequestInfo | URL, init?: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        init?.signal?.addEventListener("abort", () => {
+          aborts.push(Date.now());
+          reject(new DOMException("The operation was aborted.", "AbortError"));
+        });
+      })) as any;
+    const { init } = await import("./index");
+
+    init({
+      antiFlickerMode: "full",
+      antiFlickerTimeoutMs: 700,
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+    });
+
+    await vi.advanceTimersByTimeAsync(699);
+    expect(aborts).toEqual([]);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(aborts).toEqual([700]);
+  });
+
+  it("skips applying late config by default but writes the config cache", async () => {
+    let configCalls = 0;
+    globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      if (!String(input).includes("/config")) {
+        return Promise.resolve(new Response("ok", { status: 202 }));
+      }
+      configCalls += 1;
+      if (configCalls === 1) {
+        return new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () => {
+            reject(new DOMException("The operation was aborted.", "AbortError"));
+          });
+        });
+      }
+      return new Promise<Response>((resolve) => {
+        setTimeout(() => {
+          resolve(new Response(JSON.stringify(configPayload()), { status: 200 }));
+        }, 50);
+      });
+    }) as any;
+    const { getDiagnostics, init } = await import("./index");
+
+    init({
+      antiFlickerMode: "full",
+      antiFlickerTimeoutMs: 300,
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+    });
+
+    await vi.advanceTimersByTimeAsync(850);
+    await flushPromises(10);
+
+    const cached = JSON.parse(String(localStorage.getItem("drip_cfg:shop_123:production")));
+    expect(cached.experiments).toHaveLength(2);
+    expect(cached.exclusionGroups).toHaveLength(1);
+    expect(getDiagnostics().assignments).toHaveLength(0);
+    expect(getDiagnostics().initialized).toBe(false);
+    expect(getDiagnostics().load.stage).toBe("late_config_skip");
+    expect(document.dispatchEvent).toHaveBeenCalledWith(expect.objectContaining({
+      type: "drip_runtime_status",
+      detail: expect.objectContaining({ stage: "late_config_skip", configFetchMs: 850 }),
+    }));
+  });
+
+  it("applies late config when lateConfigPolicy is apply", async () => {
+    let configCalls = 0;
+    globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      if (!String(input).includes("/config")) {
+        return Promise.resolve(new Response("ok", { status: 202 }));
+      }
+      configCalls += 1;
+      if (configCalls === 1) {
+        return new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () => {
+            reject(new DOMException("The operation was aborted.", "AbortError"));
+          });
+        });
+      }
+      return new Promise<Response>((resolve) => {
+        setTimeout(() => {
+          resolve(new Response(JSON.stringify(configPayload()), { status: 200 }));
+        }, 50);
+      });
+    }) as any;
+    const { getDiagnostics, init } = await import("./index");
+
+    init({
+      antiFlickerMode: "full",
+      antiFlickerTimeoutMs: 300,
+      endpoint: "https://events.test",
+      lateConfigPolicy: "apply",
+      shopId: "shop_123",
+    });
+
+    await vi.advanceTimersByTimeAsync(850);
+    await flushPromises(10);
+
+    expect(getDiagnostics().assignments).toHaveLength(1);
+    expect(getDiagnostics().configSource).toBe("network");
+  });
+
+  it("keeps on-time config application unchanged", async () => {
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) {
+        return Promise.resolve(new Response(JSON.stringify(configPayload()), { status: 200 }));
+      }
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { getDiagnostics, init } = await import("./index");
+
+    init({
+      antiFlickerMode: "full",
+      antiFlickerTimeoutMs: 1200,
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+    });
+    await waitFor(() => getDiagnostics().assignments.length > 0);
+
+    expect(getDiagnostics().assignments).toHaveLength(1);
+    expect(getDiagnostics().configSource).toBe("network");
+    expect(getDiagnostics().load.stage).toBe("assignments_ready");
+  });
+});

package/src/css.ts

@@ -0,0 +1,54 @@
+const CSS_CLASS = "drip-css";
+const CSS_LINK_CLASS = "drip-css-link";
+
+export function injectCss(css: string, experimentId: string, variationId: string): void {
+  const id = "drip-css-" + experimentId + "-" + variationId;
+  if (document.getElementById(id)) return;
+  const style = document.createElement("style");
+  style.id = id;
+  style.className = CSS_CLASS;
+  style.textContent = css;
+  (document.head || document.documentElement).appendChild(style);
+}
+
+export function injectExperimentCss(css: string, experimentId: string): void {
+  const id = "drip-css-exp-" + experimentId;
+  let style = document.getElementById(id) as HTMLStyleElement | null;
+  if (!style) {
+    style = document.createElement("style");
+    style.id = id;
+    style.className = CSS_CLASS;
+    (document.head || document.documentElement).appendChild(style);
+  }
+  style.textContent = css;
+}
+
+export function removeCss(experimentId: string, variationId: string): void {
+  const el = document.getElementById("drip-css-" + experimentId + "-" + variationId);
+  if (el) el.remove();
+}
+
+export function injectExternalCss(url: string, experimentId: string, variationId: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const id = "drip-css-link-" + experimentId + "-" + variationId;
+    const previous = document.getElementById(id);
+    if (previous && previous.getAttribute("href") === url) {
+      resolve();
+      return;
+    }
+    if (previous) previous.remove();
+    const link = document.createElement("link");
+    link.id = id;
+    link.className = CSS_LINK_CLASS;
+    link.rel = "stylesheet";
+    link.href = url;
+    link.onload = () => resolve();
+    link.onerror = () => reject(new Error("Failed to load CSS artifact: " + url));
+    (document.head || document.documentElement).appendChild(link);
+  });
+}
+
+export function removeAllCss(): void {
+  document.querySelectorAll("." + CSS_CLASS).forEach((el) => el.remove());
+  document.querySelectorAll("." + CSS_LINK_CLASS).forEach((el) => el.remove());
+}

package/src/cwv.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+describe("CWV self-measurement", () => {
+  afterEach(async () => {
+    const { resetCwvMeasurement } = await import("./cwv");
+    resetCwvMeasurement();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    vi.resetModules();
+  });
+
+  it("feature-detects unsupported PerformanceObserver without throwing", async () => {
+    vi.stubGlobal("PerformanceObserver", undefined);
+    const { getCwvMetrics, startCwvMeasurement } = await import("./cwv");
+
+    expect(() => startCwvMeasurement()).not.toThrow();
+    expect(getCwvMetrics()).toEqual({ cls_total: 0, cls_after_reveal: 0 });
+  });
+
+  it("resets without constructing an observer when measurement is disabled", async () => {
+    const observer = vi.fn();
+    vi.stubGlobal("PerformanceObserver", observer);
+    const { getCwvMetrics, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
+
+    startCwvMeasurement(true);
+
+    expect(observer).not.toHaveBeenCalled();
+    await expect(waitForCwvMetrics()).resolves.toBeNull();
+    expect(getCwvMetrics()).toEqual({ cls_total: 0, cls_after_reveal: 0 });
+  });
+
+  it("accumulates layout shifts and splits shifts after reveal", async () => {
+    vi.useFakeTimers();
+    let callback: PerformanceObserverCallback | null = null;
+    const disconnect = vi.fn();
+    const observe = vi.fn();
+    vi.stubGlobal("PerformanceObserver", class PerformanceObserver {
+      constructor(cb: PerformanceObserverCallback) { callback = cb; }
+      observe = observe;
+      disconnect = disconnect;
+      takeRecords = vi.fn(() => []);
+    });
+    vi.spyOn(performance, "now").mockReturnValue(100);
+    const { getCwvMetrics, markCwvReveal, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
+    startCwvMeasurement();
+    markCwvReveal();
+    const finalized = waitForCwvMetrics();
+
+    callback?.({
+      getEntries: () => [
+        { startTime: 50, value: 0.1, hadRecentInput: false },
+        { startTime: 150, value: 0.2, hadRecentInput: false },
+        { startTime: 160, value: 0.4, hadRecentInput: true },
+      ],
+    } as unknown as PerformanceObserverEntryList, {} as PerformanceObserver);
+
+    expect(observe).toHaveBeenCalledWith({ type: "layout-shift", buffered: true });
+    expect(getCwvMetrics()).toEqual({ cls_total: 0.3, cls_after_reveal: 0.2 });
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(disconnect).toHaveBeenCalled();
+    await expect(finalized).resolves.toEqual({ cls_total: 0.3, cls_after_reveal: 0.2 });
+  });
+
+  it("finalizes the prior route and resets metrics when a new route starts", async () => {
+    vi.useFakeTimers();
+    const callbacks: PerformanceObserverCallback[] = [];
+    const observes: ReturnType<typeof vi.fn>[] = [];
+    vi.stubGlobal("PerformanceObserver", class PerformanceObserver {
+      observe = vi.fn();
+      disconnect = vi.fn();
+      takeRecords = vi.fn(() => []);
+      constructor(callback: PerformanceObserverCallback) {
+        callbacks.push(callback);
+        observes.push(this.observe);
+      }
+    });
+    vi.spyOn(performance, "now").mockReturnValue(100);
+    const { getCwvMetrics, markCwvReveal, startCwvMeasurement, waitForCwvMetrics } = await import("./cwv");
+
+    startCwvMeasurement();
+    markCwvReveal();
+    const firstRoute = waitForCwvMetrics();
+    callbacks[0]?.({
+      getEntries: () => [{ startTime: 150, value: 0.25, hadRecentInput: false }],
+    } as unknown as PerformanceObserverEntryList, {} as PerformanceObserver);
+
+    startCwvMeasurement();
+
+    await expect(firstRoute).resolves.toEqual({ cls_total: 0.25, cls_after_reveal: 0.25 });
+    expect(getCwvMetrics()).toEqual({ cls_total: 0, cls_after_reveal: 0 });
+    expect(observes[0]).toHaveBeenCalledWith({ type: "layout-shift", buffered: true });
+    expect(observes[1]).toHaveBeenCalledWith({ type: "layout-shift", buffered: false });
+  });
+});

package/src/cwv.ts

@@ -0,0 +1,129 @@
+type LayoutShiftEntry = PerformanceEntry & {
+  value?: number;
+  hadRecentInput?: boolean;
+};
+
+type CwvMetrics = {
+  cls_total: number;
+  cls_after_reveal: number;
+};
+
+type Measurement = {
+  observer: PerformanceObserver;
+  revealAt: number | null;
+  disconnectTimer: ReturnType<typeof setTimeout> | null;
+  total: number;
+  afterReveal: number;
+  promise: Promise<CwvMetrics | null>;
+  resolve: (metrics: CwvMetrics | null) => void;
+  finalized: boolean;
+};
+
+let current: Measurement | null = null;
+let lastMetrics: CwvMetrics = { cls_total: 0, cls_after_reveal: 0 };
+let lastCompletion: Promise<CwvMetrics | null> = Promise.resolve(null);
+let measurementStarted = false;
+
+function snapshot(measurement: Measurement): CwvMetrics {
+  return {
+    cls_total: Math.round(measurement.total * 100_000) / 100_000,
+    cls_after_reveal: Math.round(measurement.afterReveal * 100_000) / 100_000,
+  };
+}
+
+function consume(measurement: Measurement, entries: PerformanceEntry[]): void {
+  for (const rawEntry of entries) {
+    const entry = rawEntry as LayoutShiftEntry;
+    if (entry.hadRecentInput || typeof entry.value !== "number") continue;
+    measurement.total += entry.value;
+    if (measurement.revealAt !== null && entry.startTime > measurement.revealAt) {
+      measurement.afterReveal += entry.value;
+    }
+  }
+}
+
+function finish(measurement = current): void {
+  if (!measurement || measurement.finalized) return;
+  measurement.finalized = true;
+  if (measurement.disconnectTimer !== null) {
+    clearTimeout(measurement.disconnectTimer);
+    measurement.disconnectTimer = null;
+  }
+  try {
+    consume(measurement, measurement.observer.takeRecords());
+  } catch {}
+  measurement.observer.disconnect();
+  const metrics = snapshot(measurement);
+  lastMetrics = metrics;
+  measurement.resolve(metrics);
+  if (current === measurement) current = null;
+}
+
+export function startCwvMeasurement(disabled?: boolean): void {
+  finish(current);
+  lastMetrics = { cls_total: 0, cls_after_reveal: 0 };
+
+  if (disabled || typeof PerformanceObserver === "undefined") {
+    lastCompletion = Promise.resolve(null);
+    return;
+  }
+  try {
+    let resolve!: (metrics: CwvMetrics | null) => void;
+    const promise = new Promise<CwvMetrics | null>((done) => { resolve = done; });
+    let measurement!: Measurement;
+    const observer = new PerformanceObserver((list) => {
+      if (!measurement.finalized) consume(measurement, list.getEntries());
+    });
+    measurement = {
+      observer,
+      revealAt: null,
+      disconnectTimer: null,
+      total: 0,
+      afterReveal: 0,
+      promise,
+      resolve,
+      finalized: false,
+    };
+    current = measurement;
+    lastCompletion = promise;
+    // Buffered entries belong to the initial document only. Replaying them
+    // into later SPA route observers would mix prior-route CLS into the new
+    // route's telemetry window.
+    observer.observe({ type: "layout-shift", buffered: !measurementStarted });
+    measurementStarted = true;
+    // Empty-project and non-visual routes may not call markCwvReveal(). Bound
+    // every route measurement anyway so finalized telemetry is guaranteed.
+    measurement.disconnectTimer = setTimeout(() => finish(measurement), 5_000);
+  } catch {
+    current?.observer.disconnect();
+    current?.resolve(null);
+    current = null;
+    lastCompletion = Promise.resolve(null);
+  }
+}
+
+export function markCwvReveal(): void {
+  if (!current || current.revealAt !== null) return;
+  current.revealAt = typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : 0;
+  if (current.disconnectTimer !== null) clearTimeout(current.disconnectTimer);
+  const measurement = current;
+  measurement.disconnectTimer = setTimeout(() => finish(measurement), 5_000);
+}
+
+export function getCwvMetrics(): CwvMetrics {
+  return current ? snapshot(current) : lastMetrics;
+}
+
+export function waitForCwvMetrics(): Promise<CwvMetrics | null> {
+  return current?.promise ?? lastCompletion;
+}
+
+export function resetCwvMeasurement(): void {
+  finish(current);
+  current = null;
+  measurementStarted = false;
+  lastMetrics = { cls_total: 0, cls_after_reveal: 0 };
+  lastCompletion = Promise.resolve(null);
+}

package/src/data-layer-normalize.ts

@@ -0,0 +1,21 @@
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function normalizeDataLayerEntry(
+  item: unknown,
+): Record<string, unknown> | null {
+  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+
+  const record = item as Record<PropertyKey, unknown>;
+  if (typeof record.event === "string") {
+    return item as Record<string, unknown>;
+  }
+
+  if (record[0] !== "event" || typeof record[1] !== "string") return null;
+
+  const params = isPlainObject(record[2]) ? record[2] : {};
+  return { ...params, event: record[1] };
+}