@drip-apex/sdk 0.1.0 → 0.3.0

package/src/config-fetch.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { isHoldoutVisitor } from "./hash";
 
 function makeStorage() {
   const map = new Map<string, string>();
@@ -84,6 +85,7 @@ describe("async config fetch contract", () => {
   const originalLocalStorage = (globalThis as any).localStorage;
   const originalSessionStorage = (globalThis as any).sessionStorage;
   const originalCustomEvent = (globalThis as any).CustomEvent;
+  const originalMutationObserver = (globalThis as any).MutationObserver;
   const originalFetch = globalThis.fetch;
   const originalAbortController = (globalThis as any).AbortController;
 
@@ -93,7 +95,12 @@ describe("async config fetch contract", () => {
     vi.setSystemTime(0);
     delete (globalThis as any).__drip;
 
-    const appended: Array<{ id?: string; remove?: () => void }> = [];
+    const appended: Array<{
+      className?: string;
+      id?: string;
+      remove?: () => void;
+      textContent?: string;
+    }> = [];
     const windowStub: Record<string, any> = {
       addEventListener: vi.fn(),
       clearInterval: (id: number) => clearInterval(id),
@@ -122,12 +129,25 @@ describe("async config fetch contract", () => {
     (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(),
-      })),
+      createElement: vi.fn((tag: string) => {
+        const element: {
+          className: string;
+          id: string;
+          remove: () => void;
+          tagName: string;
+          textContent: string;
+        } = {
+          className: "",
+          id: "",
+          remove: vi.fn(() => {
+            const index = appended.indexOf(element);
+            if (index >= 0) appended.splice(index, 1);
+          }),
+          tagName: tag.toUpperCase(),
+          textContent: "",
+        };
+        return element;
+      }),
       dispatchEvent: vi.fn(),
       documentElement: {
         classList: makeClassList(),
@@ -141,7 +161,13 @@ describe("async config fetch contract", () => {
         }),
       },
       querySelector: vi.fn(() => null),
-      querySelectorAll: vi.fn(() => []),
+      querySelectorAll: vi.fn((selector: string) => {
+        if (!selector.startsWith(".")) return [];
+        const className = selector.slice(1);
+        return appended.filter((element) =>
+          String(element.className ?? "").split(/\s+/).includes(className),
+        );
+      }),
       referrer: "",
       removeEventListener: vi.fn(),
       title: "Plain probe",
@@ -160,6 +186,11 @@ describe("async config fetch contract", () => {
         this.detail = init?.detail;
       }
     };
+    (globalThis as any).MutationObserver = class MutationObserver {
+      observe() {}
+      disconnect() {}
+      constructor(_callback: MutationCallback) {}
+    };
     globalThis.fetch = vi.fn(async () => new Response("ok", { status: 202 })) as any;
   });
 
@@ -179,8 +210,10 @@ describe("async config fetch contract", () => {
     (globalThis as any).localStorage = originalLocalStorage;
     (globalThis as any).sessionStorage = originalSessionStorage;
     (globalThis as any).CustomEvent = originalCustomEvent;
+    (globalThis as any).MutationObserver = originalMutationObserver;
     (globalThis as any).AbortController = originalAbortController;
     globalThis.fetch = originalFetch;
+    vi.unstubAllGlobals();
   });
 
   it("bounds fetchWithTimeout when AbortController is unavailable", async () => {
@@ -220,7 +253,69 @@ describe("async config fetch contract", () => {
     expect(aborts).toEqual([700]);
   });
 
+  it("keeps the intended fetch budget when a late boot cannot install a barrier", async () => {
+    vi.stubGlobal("performance", {
+      now: () => 500,
+      getEntriesByType: () => [{ startTime: 0, domContentLoadedEventEnd: 100 }],
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    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,
+      debug: { enabled: true, restrictMode: "always" },
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+    });
+
+    expect(document.getElementById("drip-antiflicker")).toBeNull();
+    expect(logSpy.mock.calls.some(([message]) =>
+      String(message).includes("loaded after the pre-paint window"),
+    )).toBe(true);
+    await vi.advanceTimersByTimeAsync(700);
+    expect(aborts).toEqual([700]);
+  });
+
+  it("latches an early boot so the post-fetch re-arm still installs a barrier", async () => {
+    vi.stubGlobal("performance", {
+      now: () => Date.now(),
+      getEntriesByType: () => [{ startTime: 0, domContentLoadedEventEnd: 100 }],
+    });
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (!String(input).includes("/config")) {
+        return Promise.resolve(new Response("ok", { status: 202 }));
+      }
+      return new Promise<Response>((resolve) => {
+        setTimeout(() => resolve(new Response(JSON.stringify(configPayload()), { status: 200 })), 500);
+      });
+    }) as any;
+    const { init } = await import("./index");
+
+    init({
+      antiFlickerMode: "full",
+      antiFlickerTimeoutMs: 1_000,
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+    });
+    expect(document.head.appendChild).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(500);
+    await flushPromises(10);
+
+    expect(document.head.appendChild).toHaveBeenCalledTimes(2);
+  });
+
   it("skips applying late config by default but writes the config cache", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
     let configCalls = 0;
     globalThis.fetch = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
       if (!String(input).includes("/config")) {
@@ -243,8 +338,9 @@ describe("async config fetch contract", () => {
     const { getDiagnostics, init } = await import("./index");
 
     init({
-      antiFlickerMode: "full",
+      antiFlickerMode: "scoped",
       antiFlickerTimeoutMs: 300,
+      debug: { enabled: true, restrictMode: "always" },
       endpoint: "https://events.test",
       shopId: "shop_123",
     });
@@ -258,6 +354,9 @@ describe("async config fetch contract", () => {
     expect(getDiagnostics().assignments).toHaveLength(0);
     expect(getDiagnostics().initialized).toBe(false);
     expect(getDiagnostics().load.stage).toBe("late_config_skip");
+    expect(logSpy.mock.calls.some(([message]) =>
+      String(message).includes("loaded after the pre-paint window"),
+    )).toBe(false);
     expect(document.dispatchEvent).toHaveBeenCalledWith(expect.objectContaining({
       type: "drip_runtime_status",
       detail: expect.objectContaining({ stage: "late_config_skip", configFetchMs: 850 }),
@@ -322,4 +421,376 @@ describe("async config fetch contract", () => {
     expect(getDiagnostics().configSource).toBe("network");
     expect(getDiagnostics().load.stage).toBe("assignments_ready");
   });
+
+  it("applies holdout gating and cohort tagging from a fetched config", async () => {
+    const holdoutConfigUpdatedAt = "2026-07-27T08:30:00.000Z";
+    const shopifyPublish = vi.fn();
+    (globalThis as any).window.Shopify = {
+      analytics: { publish: shopifyPublish },
+    };
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) {
+        return Promise.resolve(new Response(JSON.stringify({
+          ...configPayload(),
+          holdout_v1_enabled: true,
+          holdout_pct: 10,
+          holdout_config_updated_at: holdoutConfigUpdatedAt,
+        }), { status: 200 }));
+      }
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { flush, getDiagnostics, init, track } = await import("./index");
+    let visitorId = "holdout-config-0";
+    while (!isHoldoutVisitor({ holdout_v1_enabled: true, holdout_pct: 10 }, visitorId)) {
+      visitorId = `holdout-config-${Number(visitorId.split("-").at(-1)) + 1}`;
+    }
+
+    init({ antiFlickerMode: "off", endpoint: "https://events.test", shopId: "shop_123", trackingStart: "immediate", userId: visitorId });
+    await waitFor(() => getDiagnostics().configSource === "network");
+    track("holdout_probe");
+    await flush();
+
+    expect(getDiagnostics().assignments).toHaveLength(0);
+    const eventsRequest = vi.mocked(globalThis.fetch).mock.calls.find(
+      (call) => String(call[0]).endsWith("/events"),
+    );
+    const events = JSON.parse(String(eventsRequest?.[1]?.body)).events;
+    expect(events.find((event: { type: string }) => event.type === "holdout_probe").data.cohort).toBe("holdout");
+    const cached = JSON.parse(String(localStorage.getItem("drip_cfg:shop_123:production")));
+    expect(cached.holdout).toEqual([true, 10, holdoutConfigUpdatedAt]);
+    expect(shopifyPublish).toHaveBeenCalledWith(
+      "drip_assignment_sync",
+      expect.objectContaining({
+        cohort: "holdout",
+        holdoutConfigEpoch: Date.parse(holdoutConfigUpdatedAt),
+      }),
+    );
+  });
+
+  it("restores the holdout configuration epoch from the config cache", async () => {
+    const holdoutConfigUpdatedAt = "2026-07-27T08:30:00.000Z";
+    const shopifyPublish = vi.fn();
+    (globalThis as any).window.Shopify = {
+      analytics: { publish: shopifyPublish },
+    };
+    let visitorId = "cached-epoch-holdout-0";
+    while (!isHoldoutVisitor({ holdout_v1_enabled: true, holdout_pct: 10 }, visitorId)) {
+      visitorId = `cached-epoch-holdout-${Number(visitorId.split("-").at(-1)) + 1}`;
+    }
+    localStorage.setItem("drip_cfg:shop_123:production", JSON.stringify({
+      fetchedAt: Date.now(),
+      hash: "cached-holdout-epoch",
+      experiments: [],
+      holdout: [true, 10, holdoutConfigUpdatedAt],
+    }));
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) {
+        return new Promise<Response>(() => {});
+      }
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { flush, getDiagnostics, init, track } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+      trackingStart: "immediate",
+      userId: visitorId,
+    });
+
+    expect(getDiagnostics().configSource).toBe("cache");
+    track("cached_holdout_epoch_probe");
+    await flush();
+    const eventsRequest = vi.mocked(globalThis.fetch).mock.calls.find(
+      (call) => String(call[0]).endsWith("/events"),
+    );
+    const events = JSON.parse(String(eventsRequest?.[1]?.body)).events;
+    expect(events.find((event: { type: string }) =>
+      event.type === "cached_holdout_epoch_probe"
+    ).data).toMatchObject({
+      cohort: "holdout",
+      holdout_config_epoch: Date.parse(holdoutConfigUpdatedAt),
+    });
+    expect(shopifyPublish).toHaveBeenCalledWith(
+      "drip_assignment_sync",
+      expect.objectContaining({
+        cohort: "holdout",
+        holdoutConfigEpoch: Date.parse(holdoutConfigUpdatedAt),
+      }),
+    );
+  });
+
+  it("hydrates cached geography before evaluating country targeting", async () => {
+    const countryExperiment = {
+      id: "exp_cached_country",
+      status: "running",
+      trafficAllocation: 1,
+      targeting: {
+        segmentRules: [{
+          include: true,
+          rules: {
+            conditions: [{ signal: "geo.country", operator: "equals", value: "DE" }],
+          },
+        }],
+      },
+      variations: [{ id: "var_cached_country", weight: 1, mutations: [] }],
+    };
+    localStorage.setItem("drip_cfg:shop_123:production", JSON.stringify({
+      fetchedAt: Date.now(),
+      hash: "cached-country-config",
+      experiments: [countryExperiment],
+      geo: { country: "DE" },
+    }));
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) return new Promise<Response>(() => {});
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { getDiagnostics, init } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+      userId: "cached-country-visitor",
+    });
+
+    expect(getDiagnostics().configSource).toBe("cache");
+    expect(getDiagnostics().assignments).toEqual([
+      expect.objectContaining({ experimentId: "exp_cached_country" }),
+    ]);
+  });
+
+  it("keeps fresh request geography when cached geography differs", async () => {
+    localStorage.setItem("drip_cfg:shop_123:production", JSON.stringify({
+      fetchedAt: Date.now(),
+      hash: "cached-country-config",
+      experiments: [{
+        id: "exp_fresh_country",
+        status: "running",
+        trafficAllocation: 1,
+        targeting: {
+          segmentRules: [{
+            include: true,
+            rules: {
+              conditions: [{ signal: "geo.country", operator: "equals", value: "US" }],
+            },
+          }],
+        },
+        variations: [{ id: "var_fresh_country", weight: 1, mutations: [] }],
+      }],
+      geo: { country: "DE" },
+    }));
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) return new Promise<Response>(() => {});
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { getDiagnostics, getSignals, init } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      geo: { country: "US" },
+      shopId: "shop_123",
+      userId: "fresh-country-visitor",
+    });
+
+    expect(getDiagnostics().configSource).toBe("cache");
+    expect(getSignals({ markVisitorSeen: false })["geo.country"]).toBe("US");
+    expect(getDiagnostics().assignments).toEqual([
+      expect.objectContaining({ experimentId: "exp_fresh_country" }),
+    ]);
+  });
+
+  it("keeps legacy cached envelopes without geography compatible", async () => {
+    localStorage.setItem("drip_cfg:shop_123:production", JSON.stringify({
+      fetchedAt: Date.now(),
+      hash: "legacy-cached-country-config",
+      experiments: [{
+        id: "exp_legacy_cached_country",
+        status: "running",
+        trafficAllocation: 1,
+        targeting: {
+          segmentRules: [{
+            include: true,
+            rules: {
+              conditions: [{ signal: "geo.country", operator: "equals", value: "DE" }],
+            },
+          }],
+        },
+        variations: [{ id: "var_legacy_cached_country", weight: 1, mutations: [] }],
+      }],
+    }));
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) return new Promise<Response>(() => {});
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { getDiagnostics, init } = await import("./index");
+
+    expect(() => init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+      userId: "legacy-cached-country-visitor",
+    })).not.toThrow();
+    expect(getDiagnostics().configSource).toBe("cache");
+    expect(getDiagnostics().assignments).toHaveLength(0);
+  });
+
+  it("synchronously gates a holdout visitor before applying cached treatments or project code", async () => {
+    const target = { textContent: "Control" };
+    const querySelectorAll = document.querySelectorAll.bind(document);
+    document.querySelectorAll = vi.fn((selector: string) => (
+      selector === "#cached-title"
+        ? [target]
+        : querySelectorAll(selector)
+    )) as typeof document.querySelectorAll;
+
+    let visitorId = "cached-holdout-0";
+    while (!isHoldoutVisitor({ holdout_v1_enabled: true, holdout_pct: 10 }, visitorId)) {
+      visitorId = `cached-holdout-${Number(visitorId.split("-").at(-1)) + 1}`;
+    }
+    const cachedExperiments = [{
+      id: "exp_cached_holdout",
+      status: "running",
+      trafficAllocation: 1,
+      js: "window.__cachedHoldoutExperiment = true;",
+      variations: [{
+        id: "var_cached_holdout",
+        weight: 1,
+        mutations: [{
+          selector: "#cached-title",
+          action: "text",
+          text: "Cached treatment",
+        }],
+        css: "#cached-title { color: red; }",
+        js: "window.__cachedHoldoutTreatment = true;",
+      }],
+    }];
+    localStorage.setItem("drip_cfg:shop_123:production", JSON.stringify({
+      fetchedAt: Date.now(),
+      hash: "cached-holdout-config",
+      experiments: cachedExperiments,
+      runtime: {
+        projectCode: {
+          enabled: true,
+          css: "body { outline: 1px solid red; }",
+          helperJs: "window.__cachedHoldoutProjectHelper = true;",
+          js: "window.__cachedHoldoutProjectStartup = true;",
+        },
+      },
+      holdout: [true, 10],
+    }));
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) {
+        return new Promise<Response>(() => {});
+      }
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { getDiagnostics, init } = await import("./index");
+
+    const assignments = init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      shopId: "shop_123",
+      userId: visitorId,
+    });
+
+    expect(assignments).toHaveLength(0);
+    expect(getDiagnostics().configSource).toBe("cache");
+    expect(target.textContent).toBe("Control");
+    expect((window as any).__cachedHoldoutTreatment).toBeUndefined();
+    expect((window as any).__cachedHoldoutExperiment).toBeUndefined();
+    expect((window as any).__cachedHoldoutProjectHelper).toBeUndefined();
+    expect((window as any).__cachedHoldoutProjectStartup).toBeUndefined();
+    expect(document.getElementById("drip-css-exp_cached_holdout-var_cached")).toBeNull();
+    expect(document.getElementById("drip-project-css")).toBeNull();
+  });
+
+  it("tears down cached treatments when the network config moves the visitor into holdout", async () => {
+    const target = { textContent: "Control" };
+    const querySelectorAll = document.querySelectorAll.bind(document);
+    document.querySelectorAll = vi.fn((selector: string) => (
+      selector === "#cached-title"
+        ? [target]
+        : querySelectorAll(selector)
+    )) as typeof document.querySelectorAll;
+
+    let visitorId = "cached-network-holdout-0";
+    while (!isHoldoutVisitor({ holdout_v1_enabled: true, holdout_pct: 10 }, visitorId)) {
+      visitorId = `cached-network-holdout-${Number(visitorId.split("-").at(-1)) + 1}`;
+    }
+    const cachedExperiments = [{
+      id: "exp_cached",
+      status: "running",
+      trafficAllocation: 1,
+      js: "window.__cachedExperiment = true;",
+      resetJs: "window.__cachedExperiment = false;",
+      variations: [{
+        id: "var_cached",
+        weight: 1,
+        mutations: [{
+          selector: "#cached-title",
+          action: "text",
+          text: "Cached treatment",
+        }],
+        css: "#cached-title { color: red; }",
+        js: "window.__cachedTreatment = true;",
+        resetJs: "window.__cachedTreatment = false;",
+      }],
+    }];
+    localStorage.setItem("drip_cfg:shop_123:production", JSON.stringify({
+      fetchedAt: Date.now(),
+      hash: "cached-active-config",
+      experiments: cachedExperiments,
+      runtime: {
+        projectCode: {
+          enabled: true,
+          css: "body { outline: 1px solid red; }",
+          helperJs: "window.__cachedProjectHelper = true;",
+          js: "window.__cachedProjectStartup = true;",
+        },
+      },
+      holdout: [false, 0],
+    }));
+    let resolveConfig!: (response: Response) => void;
+    globalThis.fetch = vi.fn((input: RequestInfo | URL) => {
+      if (String(input).includes("/config")) {
+        return new Promise<Response>((resolve) => {
+          resolveConfig = resolve;
+        });
+      }
+      return Promise.resolve(new Response("ok", { status: 202 }));
+    }) as any;
+    const { getDiagnostics, init } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      endpoint: "https://events.test",
+      lateConfigPolicy: "apply",
+      shopId: "shop_123",
+      userId: visitorId,
+    });
+    await flushPromises();
+
+    expect(target.textContent).toBe("Cached treatment");
+    expect((window as any).__cachedTreatment).toBe(true);
+    expect((window as any).__cachedExperiment).toBe(true);
+    expect(document.getElementById("drip-css-exp_cached-var_cached")).not.toBeNull();
+    expect(document.getElementById("drip-project-css")).not.toBeNull();
+
+    resolveConfig(new Response(JSON.stringify({
+      experiments: cachedExperiments,
+      holdout_v1_enabled: true,
+      holdout_pct: 10,
+    }), { status: 200 }));
+    await waitFor(() => getDiagnostics().configSource === "network");
+
+    expect(getDiagnostics().assignments).toHaveLength(0);
+    expect(target.textContent).toBe("Control");
+    expect((window as any).__cachedTreatment).toBe(false);
+    expect((window as any).__cachedExperiment).toBe(false);
+    expect(document.getElementById("drip-css-exp_cached-var_cached")).toBeNull();
+    expect(document.getElementById("drip-project-css")).toBeNull();
+  });
 });