@drip-apex/sdk 0.1.0 → 0.3.0

package/src/hash.ts

@@ -1,3 +1,11 @@
+import { hashToFloat } from "@drip/shared-runtime/bucketing";
+import { edgeRuntimeActive } from "./edge-runtime";
+
+// The bucketing kernel lives in @drip/shared-runtime/bucketing (#2476). This
+// module keeps re-exporting it so SDK call sites and the holdout gate below
+// stay unchanged.
+export { hashToFloat, murmurhash3_32_gc, variationHashToFloat } from "@drip/shared-runtime/bucketing";
+
 const UID_KEY = "drip_uid";
 
 type StorageMode = "localStorage" | "sessionStorage" | "cookie" | "memory";
@@ -7,62 +15,17 @@ let encodeStorageValues = false;
 let cookieDomain = "";
 let memoryUserId: string | null = null;
 
-export function murmurhash3_32_gc(key: string, seed = 0): number {
-  let remainder = key.length & 3;
-  let bytes = key.length - remainder;
-  let h1 = seed;
-  let c1 = 0xcc9e2d51;
-  let c2 = 0x1b873593;
-  let i = 0;
-
-  while (i < bytes) {
-    let k1 =
-      (key.charCodeAt(i) & 0xff) |
-      ((key.charCodeAt(++i) & 0xff) << 8) |
-      ((key.charCodeAt(++i) & 0xff) << 16) |
-      ((key.charCodeAt(++i) & 0xff) << 24);
-    ++i;
-
-    k1 = Math.imul(k1, c1);
-    k1 = (k1 << 15) | (k1 >>> 17);
-    k1 = Math.imul(k1, c2);
-
-    h1 ^= k1;
-    h1 = (h1 << 13) | (h1 >>> 19);
-    h1 = Math.imul(h1, 5) + 0xe6546b64;
-  }
-
-  let k1 = 0;
-  switch (remainder) {
-    case 3:
-      k1 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
-    case 2:
-      k1 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
-    case 1:
-      k1 ^= key.charCodeAt(i) & 0xff;
-      k1 = Math.imul(k1, c1);
-      k1 = (k1 << 15) | (k1 >>> 17);
-      k1 = Math.imul(k1, c2);
-      h1 ^= k1;
-  }
-
-  h1 ^= key.length;
-  h1 ^= h1 >>> 16;
-  h1 = Math.imul(h1, 0x85ebca6b);
-  h1 ^= h1 >>> 13;
-  h1 = Math.imul(h1, 0xc2b2ae35);
-  h1 ^= h1 >>> 16;
-
-  return h1 >>> 0;
-}
-
-export function hashToFloat(seed: string, value: string): number {
-  const hash = murmurhash3_32_gc(seed + value, 1);
-  return (hash % 10000) / 10000;
+export function isHoldoutVisitor(
+  config: { holdout_v1_enabled?: unknown; holdout_pct?: unknown },
+  visitorId: string,
+): boolean {
+  const pct = config.holdout_pct;
+  return config.holdout_v1_enabled === true && typeof pct === "number" &&
+    pct > 0 && pct <= 10 && hashToFloat("apex:global-holdout:v1", visitorId) < pct / 100;
 }
 
-export function variationHashToFloat(experimentId: string, value: string): number {
-  return hashToFloat(`${experimentId}:variation`, value);
+export function applyHoldoutGate<T>(config: Parameters<typeof isHoldoutVisitor>[0], visitorId: string, values: T[]): T[] {
+  return isHoldoutVisitor(config, visitorId) ? [] : values;
 }
 
 function bytesToHex(bytes: Uint8Array): string {
@@ -195,6 +158,13 @@ function writeCookie(value: string): void {
 
 export function getUserId(provided?: string): string {
   if (provided) return provided;
+  if (edgeRuntimeActive()) {
+    const edgeUserId = readCookie();
+    if (edgeUserId) {
+      if (readStorage() !== edgeUserId) writeStorage(edgeUserId);
+      return edgeUserId;
+    }
+  }
   const existing = readStorage() || readCookie();
   if (existing) return existing;
   const created = generateId();
@@ -203,6 +173,11 @@ export function getUserId(provided?: string): string {
   return created;
 }
 
+/** Reads an existing durable identity without minting or persisting a new one. */
+export function getPersistedUserId(): string | null {
+  return readStorage() || readCookie();
+}
+
 export function getEphemeralUserId(provided?: string): string {
   return provided || generateId();
 }

package/src/holdout.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { applyHoldoutGate, isHoldoutVisitor } from "./hash";
+
+describe("global holdout v1", () => {
+  it("is deterministic and sticky for a visitor", () => {
+    const config = { holdout_v1_enabled: true, holdout_pct: 5 };
+    const first = isHoldoutVisitor(config, "visitor-123");
+    expect(isHoldoutVisitor(config, "visitor-123")).toBe(first);
+    expect(Array.from({ length: 1000 }, (_, i) => isHoldoutVisitor(config, `v-${i}`)).filter(Boolean).length)
+      .toBeGreaterThan(20);
+  });
+
+  it("fails open for disabled, missing, or malformed config", () => {
+    expect(isHoldoutVisitor({}, "visitor")).toBe(false);
+    expect(isHoldoutVisitor({ holdout_v1_enabled: true }, "visitor")).toBe(false);
+    expect(isHoldoutVisitor({ holdout_v1_enabled: true, holdout_pct: 11 }, "visitor")).toBe(false);
+  });
+
+  it("short-circuits every engine input only for holdout visitors", () => {
+    const visitor = Array.from({ length: 1000 }, (_, i) => `v-${i}`).find((id) =>
+      isHoldoutVisitor({ holdout_v1_enabled: true, holdout_pct: 10 }, id));
+    expect(visitor).toBeTruthy();
+    expect(applyHoldoutGate({ holdout_v1_enabled: true, holdout_pct: 10 }, visitor!, ["experiment"])).toEqual([]);
+    expect(applyHoldoutGate({}, visitor!, ["experiment"])).toEqual(["experiment"]);
+  });
+});

package/src/hydration.test.ts

@@ -136,6 +136,50 @@ describe("hydration coexistence gate", () => {
     }
   });
 
+  it("reports head-install delay from the original outer clock", async () => {
+    Object.defineProperty(document, "readyState", { value: "loading", configurable: true });
+    try {
+      const gate = awaitHydration(1_000, { waitForHydration: true });
+      await vi.advanceTimersByTimeAsync(400);
+      document.body.innerHTML = '<div id="__next"></div>';
+      Object.defineProperty(document, "readyState", { value: "interactive", configurable: true });
+      document.dispatchEvent(new Event("DOMContentLoaded"));
+      await vi.advanceTimersByTimeAsync(200);
+      signalHydrated();
+      await expect(gate).resolves.toBeUndefined();
+
+      // The quiet detector may legitimately resolve before the explicit
+      // signal; the outer-clock guarantee is that the delay counts from the
+      // ORIGINAL start (>= 400ms pre-DCL wait). The restarted-clock bug
+      // reported only the post-recursion remainder (~80ms).
+      const applyDelayedMs = (window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf?.apply_delayed_ms;
+      expect(applyDelayedMs).toBeGreaterThanOrEqual(400);
+      expect(applyDelayedMs).toBeLessThanOrEqual(1_000);
+    } finally {
+      Object.defineProperty(document, "readyState", { value: "complete", configurable: true });
+    }
+  });
+
+  it("does not stamp delay metrics for a synchronous-apply teardown gate", async () => {
+    const gate = awaitHydration(500, { waitForHydration: true, recordMetrics: false });
+    signalHydrated();
+    await expect(gate).resolves.toBeUndefined();
+    expect((window as Window & { __dripPerf?: unknown }).__dripPerf).toBeUndefined();
+  });
+
+  it("keeps the first page-load hydration stamps across later gates", async () => {
+    document.body.innerHTML = '<div id="__next"></div>';
+    const first = awaitHydration(1_000);
+    await vi.advanceTimersByTimeAsync(200);
+    signalHydrated();
+    await expect(first).resolves.toBeUndefined();
+    const initial = { ...(window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf };
+
+    await vi.advanceTimersByTimeAsync(300);
+    await expect(awaitHydration(1_000)).resolves.toBeUndefined();
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf).toMatchObject(initial);
+  });
+
   it("fails open at the head-install deadline without a framework marker or DOMContentLoaded", async () => {
     Object.defineProperty(document, "readyState", { value: "loading", configurable: true });
     try {
@@ -162,16 +206,43 @@ describe("hydration coexistence gate", () => {
     await expect(gate).resolves.toBeUndefined();
   });
 
-  it("honors an explicit hydration wait without known framework markers", async () => {
+  it("resolves an explicit markerless hydration wait once the DOM is quiet", async () => {
     const gate = awaitHydration(1_000, { waitForHydration: true });
     let resolved = false;
     void gate.then(() => { resolved = true; });
 
-    await vi.advanceTimersByTimeAsync(200);
+    await vi.advanceTimersByTimeAsync(48);
     expect(resolved).toBe(false);
 
+    await vi.advanceTimersByTimeAsync(32);
+    await expect(gate).resolves.toBeUndefined();
+    expect(resolved).toBe(true);
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf?.hydration_timeout).toBeUndefined();
+  });
+
+  it("bounds a continuously mutating markerless page at the hydration timeout", async () => {
+    const gate = awaitHydration(200, { waitForHydration: true });
+
+    for (let elapsed = 0; elapsed < 200; elapsed += 16) {
+      document.body.toggleAttribute("data-mutating");
+      await Promise.resolve();
+      await vi.advanceTimersByTimeAsync(16);
+    }
+
+    await expect(gate).resolves.toBeUndefined();
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf).toMatchObject({
+      apply_delayed_ms: 200,
+      hydration_timeout: true,
+    });
+  });
+
+  it("resolves a markerless hydration wait immediately on an explicit signal", async () => {
+    const gate = awaitHydration(1_000, { waitForHydration: true });
+
     signalHydrated();
+
     await expect(gate).resolves.toBeUndefined();
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf?.hydration_timeout).toBeUndefined();
   });
 
   it("waits for two quiet frames and at least 50ms after framework mutations", async () => {

package/src/hydration.ts

@@ -12,6 +12,10 @@ function perf(): Record<string, unknown> | null {
   return target.__dripPerf = target.__dripPerf ?? {};
 }
 
+function stampOnce(metrics: Record<string, unknown>, name: string, value: unknown): void {
+  if (!(name in metrics)) metrics[name] = value;
+}
+
 export function detectSsrFramework(): "nuxt" | "next" | "server-rendered" | null {
   if (typeof window === "undefined" || typeof document === "undefined") return null;
   const runtime = window as Window & { __NUXT__?: unknown; __NEXT_DATA__?: unknown; __next_f?: unknown };
@@ -46,9 +50,10 @@ export function signalHydrated(): void {
 
 export function awaitHydration(
   timeoutMs: number,
-  options: { waitForHydration?: boolean } = {},
+  options: { waitForHydration?: boolean; recordMetrics?: boolean } = {},
+  outerStarted = Date.now(),
 ): Promise<void> {
-  const started = Date.now();
+  const started = outerStarted;
   const boundedTimeoutMs = Number.isFinite(timeoutMs)
     ? Math.max(0, Math.min(10_000, timeoutMs))
     : 3_000;
@@ -74,7 +79,7 @@ export function awaitHydration(
         document.removeEventListener("DOMContentLoaded", proceed);
         signals.delete(proceed);
         const remaining = Math.max(0, boundedTimeoutMs - (Date.now() - started));
-        void awaitHydration(remaining, options).then(resolve);
+        void awaitHydration(remaining, options, started).then(resolve);
       };
       document.addEventListener("DOMContentLoaded", proceed, { once: true });
       // A framework can call drip.hydrated() before the parser reaches the
@@ -110,12 +115,12 @@ export function awaitHydration(
         holds = 0;
         console.warn("[drip] Mutation hold timed out; applying fail-open");
       }
-      const metrics = perf();
+      const metrics = options.recordMetrics === false ? undefined : perf();
       if (metrics) {
-        if (needsHydration || hydratedAt) metrics.hydration_detected_at = hydratedAt || Date.now();
-        metrics.apply_delayed_ms = Math.max(0, Date.now() - started);
-        if (hydrationTimeout) metrics.hydration_timeout = true;
-        if (holdTimeout) metrics.hold_timeout = true;
+        if (needsHydration || hydratedAt) stampOnce(metrics, "hydration_detected_at", hydratedAt || Date.now());
+        stampOnce(metrics, "apply_delayed_ms", Math.max(0, Date.now() - started));
+        if (hydrationTimeout) stampOnce(metrics, "hydration_timeout", true);
+        if (holdTimeout) stampOnce(metrics, "hold_timeout", true);
       }
       signals.delete(check);
       clearTimeout(timer);
@@ -148,6 +153,10 @@ export function awaitHydration(
         check();
         return;
       }
+      // requestAnimationFrame is available in supported browsers, but not in
+      // every DOM-like host. Keep the explicit-signal/hard-timeout exits active
+      // rather than throwing when the quiet detector cannot be scheduled.
+      if (typeof requestAnimationFrame === "undefined") return;
       const onRecords: MutationCallback = () => {
         lastMutation = Date.now();
         quietFrames = 0;
@@ -160,7 +169,7 @@ export function awaitHydration(
 
     signals.add(check);
     const timer = setTimeout(() => finish(true), boundedTimeoutMs);
-    if (needsHydration && frameworkDetected) {
+    if (needsHydration) {
       if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", beginQuiet, { once: true });
       else beginQuiet();
     }