@drip-apex/sdk 0.1.0

package/src/track.test.ts

@@ -0,0 +1,817 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { Tracker } from "./track";
+import { configureIdentityStorage } from "./hash";
+
+function makeSessionStorage() {
+  const map = new Map<string, string>();
+  return {
+    getItem: (k: string) => (map.has(k) ? map.get(k)! : null),
+    setItem: (k: string, v: string) => { map.set(k, v); },
+    removeItem: (k: string) => { map.delete(k); },
+  };
+}
+
+describe("Tracker flush resilience", () => {
+  const realFetch = globalThis.fetch;
+  const realWindow = globalThis.window;
+  const realDocument = globalThis.document;
+  const realSessionStorage = (globalThis as any).sessionStorage;
+  const realLocalStorage = (globalThis as any).localStorage;
+  const realNavigatorDescriptor = Object.getOwnPropertyDescriptor(globalThis, "navigator");
+
+  function setNavigator(value: unknown): void {
+    Object.defineProperty(globalThis, "navigator", {
+      configurable: true,
+      value,
+    });
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    (globalThis as any).sessionStorage = makeSessionStorage();
+    (globalThis as any).localStorage = makeSessionStorage();
+    (globalThis as any).window = {
+      setInterval: (fn: any, _ms: number) => {
+        // keep tests deterministic: don't run interval automatically
+        return 1;
+      },
+      clearInterval: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+    };
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    globalThis.fetch = realFetch;
+    (globalThis as any).window = realWindow;
+    (globalThis as any).document = realDocument;
+    if (realNavigatorDescriptor) {
+      Object.defineProperty(globalThis, "navigator", realNavigatorDescriptor);
+    } else {
+      delete (globalThis as any).navigator;
+    }
+    (globalThis as any).sessionStorage = realSessionStorage;
+    (globalThis as any).localStorage = realLocalStorage;
+    vi.restoreAllMocks();
+  });
+
+  it("never persists or stamps the session count without a lifetime store", () => {
+    configureIdentityStorage({ storageMode: "sessionStorage" });
+    try {
+      const tracker = new Tracker("shop", "https://worker.example");
+      tracker.track({ type: "pageview", data: {} });
+      expect(localStorage.getItem("drip_visitor_sessions_v1")).toBeNull();
+      const stored = JSON.parse(localStorage.getItem("drip_events") ?? sessionStorage.getItem("drip_events") ?? "[]");
+      for (const event of stored) {
+        expect(event?.data?.visitor_sessions).toBeUndefined();
+      }
+    } finally {
+      configureIdentityStorage({ storageMode: "localStorage" });
+    }
+  });
+
+  it("counts lifetime visitor sessions without double-counting tracker re-initialization", () => {
+    sessionStorage.setItem("drip_sid", "session-one");
+
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    expect(JSON.parse(String(localStorage.getItem("drip_visitor_sessions_v1")))).toEqual({
+      count: 1,
+      recentSessionIds: ["session-one"],
+    });
+
+    sessionStorage.setItem("drip_sid", "session-two");
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    expect(JSON.parse(String(localStorage.getItem("drip_visitor_sessions_v1")))).toEqual({
+      count: 2,
+      recentSessionIds: ["session-two", "session-one"],
+    });
+  });
+
+  it("does not re-count remembered sessions when parallel tabs alternate", () => {
+    // Tab A (session-one) and tab B (session-two) each count once…
+    sessionStorage.setItem("drip_sid", "session-one");
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    sessionStorage.setItem("drip_sid", "session-two");
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    // …and a reload of tab A must not increment again.
+    sessionStorage.setItem("drip_sid", "session-one");
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+
+    expect(JSON.parse(String(localStorage.getItem("drip_visitor_sessions_v1")))).toEqual({
+      count: 2,
+      recentSessionIds: ["session-two", "session-one"],
+    });
+  });
+
+  it("migrates a legacy lastSessionId record without re-counting it", () => {
+    localStorage.setItem(
+      "drip_visitor_sessions_v1",
+      JSON.stringify({ count: 3, lastSessionId: "legacy-session" }),
+    );
+    sessionStorage.setItem("drip_sid", "legacy-session");
+
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+
+    expect(
+      JSON.parse(String(localStorage.getItem("drip_visitor_sessions_v1"))).count,
+    ).toBe(3);
+  });
+
+  it("restarts the visitor session count after storage is cleared", () => {
+    localStorage.setItem(
+      "drip_visitor_sessions_v1",
+      JSON.stringify({ count: 7, lastSessionId: "old-session" }),
+    );
+    localStorage.removeItem("drip_visitor_sessions_v1");
+    sessionStorage.setItem("drip_sid", "new-session");
+
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+
+    expect(JSON.parse(String(localStorage.getItem("drip_visitor_sessions_v1")))).toEqual({
+      count: 1,
+      recentSessionIds: ["new-session"],
+    });
+  });
+
+  it("recovers malformed visitor session storage at one", () => {
+    localStorage.setItem("drip_visitor_sessions_v1", "not-json");
+    sessionStorage.setItem("drip_sid", "recovered-session");
+
+    new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+
+    expect(JSON.parse(String(localStorage.getItem("drip_visitor_sessions_v1")))).toEqual({
+      count: 1,
+      recentSessionIds: ["recovered-session"],
+    });
+  });
+
+  it("stamps result-relevant events without overwriting merchant data", async () => {
+    const bodies: Array<{ events: Array<{ type: string; data?: Record<string, unknown> }> }> = [];
+    globalThis.fetch = vi.fn(async (_url: string, init: RequestInit) => {
+      bodies.push(JSON.parse(String(init.body)));
+      return new Response("ok", { status: 202 });
+    }) as any;
+    sessionStorage.setItem("drip_sid", "session-one");
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+
+    tracker.track({ type: "experiment_viewed", data: {} });
+    tracker.track({ type: "personalization_rendered", data: {} });
+    tracker.track({ type: "goal", data: { goalId: "signup" } });
+    tracker.track({ type: "conversion" });
+    tracker.track({ type: "pageview", data: { path: "/" } });
+    tracker.track({ type: "custom", data: {} });
+    tracker.track({ type: "goal", data: { visitor_sessions: 99 } });
+    await tracker.flush();
+
+    expect(bodies[0].events.map((event) => [event.type, event.data?.visitor_sessions])).toEqual([
+      ["experiment_viewed", 1],
+      ["personalization_rendered", 1],
+      ["goal", 1],
+      ["conversion", 1],
+      ["pageview", 1],
+      ["custom", undefined],
+      ["goal", 99],
+    ]);
+  });
+
+  it("keeps sending events without visitor_sessions when localStorage throws", async () => {
+    (globalThis as any).localStorage = {
+      getItem: () => { throw new Error("storage denied"); },
+      setItem: () => { throw new Error("storage denied"); },
+    };
+    const bodies: Array<{ events: Array<{ data?: Record<string, unknown> }> }> = [];
+    globalThis.fetch = vi.fn(async (_url: string, init: RequestInit) => {
+      bodies.push(JSON.parse(String(init.body)));
+      return new Response("ok", { status: 202 });
+    }) as any;
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    tracker.track({ type: "pageview", data: { path: "/" } });
+
+    await tracker.flush();
+
+    expect(bodies[0].events[0].data).toEqual({ path: "/" });
+  });
+
+  it("re-queues events on 429 and respects Retry-After backoff", async () => {
+    const fetchMock = vi.fn(async () => new Response("rate limit", {
+      status: 429,
+      headers: { "Retry-After": "2" },
+    }));
+    globalThis.fetch = fetchMock as any;
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    tracker.start();
+    tracker.track({ type: "pageview", data: {} } as any);
+
+    await tracker.flush();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Immediate second flush should be skipped due to backoff.
+    await tracker.flush();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // After >2s, flush should attempt again.
+    // Backoff includes small jitter; advance enough to clear it.
+    vi.advanceTimersByTime(3000);
+    await tracker.flush();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("drains queued events in bounded batches before awaited flush resolves", async () => {
+    const seenCounts: number[] = [];
+    const fetchMock = vi.fn(async (_url: string, init: any) => {
+      const body = JSON.parse(init.body);
+      seenCounts.push(Array.isArray(body.events) ? body.events.length : 0);
+      return new Response("ok", { status: 202 });
+    });
+    globalThis.fetch = fetchMock as any;
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s", maxBatchSize: 100 });
+    tracker.start();
+    for (let i = 0; i < 60; i++) tracker.track({ type: "pageview", data: { i } } as any);
+    (tracker as any).maxBatchSize = 20;
+
+    await tracker.flush();
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(seenCounts).toEqual([20, 20, 20]);
+  });
+
+  it("adds event IDs before sending and preserves caller-provided non-blank IDs", async () => {
+    const bodies: Array<{ events: Array<{ event_id?: string; type: string }> }> = [];
+    const fetchMock = vi.fn(async (_url: string, init: any) => {
+      bodies.push(JSON.parse(init.body));
+      return new Response("ok", { status: 202 });
+    });
+    globalThis.fetch = fetchMock as any;
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    tracker.start();
+    tracker.track({ type: "pageview", data: {} } as any);
+    tracker.track({ type: "blank_id", event_id: "", data: {} } as any);
+    tracker.track({ type: "lead_submitted", event_id: "evt_known", data: {} } as any);
+
+    await tracker.flush();
+
+    expect(bodies).toHaveLength(1);
+    expect(bodies[0].events[0].event_id).toEqual(expect.any(String));
+    expect(bodies[0].events[0].event_id).not.toBe("");
+    expect(bodies[0].events[1].event_id).toEqual(expect.any(String));
+    expect(bodies[0].events[1].event_id).not.toBe("");
+    expect(bodies[0].events[2]).toMatchObject({
+      type: "lead_submitted",
+      event_id: "evt_known",
+    });
+  });
+
+  it("awaits an in-flight automatic flush before resolving an explicit flush", async () => {
+    const seenCounts: number[] = [];
+    let resolveFirst: (() => void) | null = null;
+    const firstResponse = new Promise<Response>((resolve) => {
+      resolveFirst = () => resolve(new Response("ok", { status: 202 }));
+    });
+    let callCount = 0;
+    const fetchMock = vi.fn(async (_url: string, init: any) => {
+      const body = JSON.parse(init.body);
+      seenCounts.push(Array.isArray(body.events) ? body.events.length : 0);
+      callCount += 1;
+      if (callCount === 1) return firstResponse;
+      return new Response("ok", { status: 202 });
+    });
+    globalThis.fetch = fetchMock as any;
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s", maxBatchSize: 20 });
+    tracker.start();
+    for (let i = 0; i < 20; i++) tracker.track({ type: "pageview", data: { i } } as any);
+    await Promise.resolve();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    for (let i = 20; i < 25; i++) tracker.track({ type: "pageview", data: { i } } as any);
+    let resolved = false;
+    const joined = tracker.flush().then(() => {
+      resolved = true;
+    });
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+
+    resolveFirst?.();
+    await joined;
+    expect(resolved).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(seenCounts).toEqual([20, 5]);
+  });
+
+  it("flushes pagehide events with sendBeacon and does not resend them later", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const sendBeacon = vi.fn(() => true);
+    const fetchMock = vi.fn(async () => new Response("ok", { status: 202 }));
+    setNavigator({ sendBeacon });
+    globalThis.fetch = fetchMock as any;
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "shop_public",
+      ingestShopId: "shop_ingest",
+      ingestSignature: "sig_1",
+    });
+    tracker.start();
+    tracker.track({ type: "checkout_started", data: {} } as any);
+
+    windowListeners.pagehide?.();
+    await tracker.flush();
+
+    expect(sendBeacon).toHaveBeenCalledTimes(1);
+    expect(fetchMock).not.toHaveBeenCalled();
+    const [, body] = sendBeacon.mock.calls[0];
+    expect(body).toBeInstanceOf(Blob);
+    expect((body as Blob).type).toBe("text/plain");
+    const payload = JSON.parse(await (body as Blob).text());
+    expect(payload).toMatchObject({
+      _shopId: "shop_ingest",
+      _signature: "sig_1",
+    });
+    expect(payload.events).toHaveLength(1);
+    expect(payload.events[0]).toMatchObject({ type: "checkout_started" });
+  });
+
+  it("persists page-exit batches when beacon is refused and keepalive fetch rejects", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const sendBeacon = vi.fn(() => false);
+    const fetchMock = vi.fn()
+      .mockRejectedValueOnce(new Error("network unavailable"))
+      .mockResolvedValueOnce(new Response("ok", { status: 202 }));
+    setNavigator({ sendBeacon });
+    globalThis.fetch = fetchMock as any;
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "shop_public",
+      environment: "staging",
+    });
+    tracker.start();
+    tracker.track({ type: "checkout_started", data: {} } as any);
+
+    windowListeners.pagehide?.();
+    await vi.waitFor(() => expect(sessionStorage.getItem("drip_events")).not.toBeNull());
+
+    const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+    expect(recovered).toHaveLength(1);
+    expect(recovered[0]).toMatchObject({ type: "checkout_started", environment: "staging" });
+
+    const nextTracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "shop_public",
+      environment: "production",
+    });
+    nextTracker.start();
+    await nextTracker.flush();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const payload = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body));
+    expect(payload.events).toHaveLength(1);
+    expect(payload.events[0]).toMatchObject({
+      type: "checkout_started",
+      event_id: recovered[0].event_id,
+      environment: "staging",
+    });
+    expect(sessionStorage.getItem("drip_events")).toBeNull();
+  });
+
+  it("merges reverse-order unload failures without dropping parallel batches", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const rejectors: Array<(error: Error) => void> = [];
+    setNavigator({ sendBeacon: vi.fn(() => false) });
+    globalThis.fetch = vi.fn(() => new Promise<Response>((_resolve, reject) => {
+      rejectors.push(reject);
+    })) as any;
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "shop_public",
+      maxBatchSize: 100,
+    });
+    tracker.start();
+    for (let i = 0; i < 5; i++) {
+      tracker.track({ type: "checkout_step", event_id: `evt_${i}`, data: { i } } as any);
+    }
+    (tracker as any).maxBatchSize = 2;
+
+    windowListeners.pagehide?.();
+    expect(rejectors).toHaveLength(3);
+    rejectors[2](new Error("third failed"));
+    await Promise.resolve();
+    rejectors[0](new Error("first failed"));
+    await Promise.resolve();
+    rejectors[1](new Error("second failed"));
+    await vi.waitFor(() => {
+      const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+      expect(recovered).toHaveLength(5);
+    });
+
+    const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+    expect(new Set(recovered.map((event: { event_id: string }) => event.event_id))).toEqual(
+      new Set(["evt_0", "evt_1", "evt_2", "evt_3", "evt_4"]),
+    );
+  });
+
+  it("keeps differently typed recovery events with the same scoped event ID", () => {
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop" });
+    (tracker as any).saveRecovery([
+      { type: "goal", event_id: "evt_shared", experimentId: "exp", variationId: "var" },
+      { type: "revenue", event_id: "evt_shared", experimentId: "exp", variationId: "var" },
+    ]);
+
+    const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+    expect(recovered.map((event: { type: string }) => event.type)).toEqual(["goal", "revenue"]);
+  });
+
+  it("keeps recovery events from different environments with the same scoped event ID", () => {
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop" });
+    (tracker as any).saveRecovery([
+      {
+        type: "goal",
+        event_id: "evt_shared",
+        experimentId: "exp",
+        variationId: "var",
+        environment: "production",
+      },
+      {
+        type: "goal",
+        event_id: "evt_shared",
+        experimentId: "exp",
+        variationId: "var",
+        environment: "staging",
+      },
+    ]);
+
+    const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+    expect(recovered.map((event: { environment: string }) => event.environment)).toEqual([
+      "production",
+      "staging",
+    ]);
+  });
+
+  it("recovers an active in-flight batch when its keepalive request fails after pagehide", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const rejectors: Array<(error: Error) => void> = [];
+    setNavigator({ sendBeacon: vi.fn(() => false) });
+    globalThis.fetch = vi.fn(() => new Promise<Response>((_resolve, reject) => {
+      rejectors.push(reject);
+    })) as any;
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop", maxBatchSize: 2 });
+    tracker.start();
+    tracker.track({ type: "goal", event_id: "evt_parallel", experimentId: "exp_a", variationId: "var_a" } as any);
+    tracker.track({ type: "goal", event_id: "evt_parallel", experimentId: "exp_b", variationId: "var_b" } as any);
+    await Promise.resolve();
+    expect(rejectors).toHaveLength(1);
+
+    windowListeners.pagehide?.();
+    expect(rejectors).toHaveLength(1);
+    rejectors[0](new Error("original failed"));
+    await vi.waitFor(() => {
+      const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+      expect(recovered).toHaveLength(2);
+    });
+
+    const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+    expect(recovered.map((event: { experimentId: string }) => event.experimentId).sort()).toEqual([
+      "exp_a",
+      "exp_b",
+    ]);
+  });
+
+  it("recovers an active keepalive batch when the Worker rejects it after pagehide", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    let resolveRequest: ((response: Response) => void) | null = null;
+    globalThis.fetch = vi.fn(() => new Promise<Response>((resolve) => {
+      resolveRequest = resolve;
+    })) as any;
+    setNavigator({ sendBeacon: vi.fn(() => true) });
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop", maxBatchSize: 1 });
+    tracker.start();
+    tracker.track({ type: "goal", event_id: "evt_rejected" } as any);
+    await Promise.resolve();
+
+    windowListeners.pagehide?.();
+    resolveRequest?.(new Response("unavailable", { status: 503 }));
+    await tracker.flush();
+
+    const recovered = JSON.parse(String(sessionStorage.getItem("drip_events")));
+    expect(recovered).toEqual([expect.objectContaining({ event_id: "evt_rejected" })]);
+  });
+
+  it("clears terminal recovery after the surviving page later receives an acknowledgement", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(new Response("unavailable", { status: 503 }))
+      .mockResolvedValueOnce(new Response("accepted", { status: 202 }));
+    globalThis.fetch = fetchMock as any;
+    setNavigator({ sendBeacon: vi.fn(() => true) });
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop", maxBatchSize: 1 });
+    tracker.start();
+    tracker.track({ type: "goal", event_id: "evt_survived" } as any);
+    windowListeners.pagehide?.();
+    await tracker.flush();
+    expect(sessionStorage.getItem("drip_events")).not.toBeNull();
+
+    vi.advanceTimersByTime(2_000);
+    await tracker.flush();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(sessionStorage.getItem("drip_events")).toBeNull();
+  });
+
+  it("does not duplicate an active keepalive batch when its request succeeds after pagehide", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const resolvers: Array<(response: Response) => void> = [];
+    const fetchMock = vi.fn(() => new Promise<Response>((resolve) => {
+      resolvers.push(resolve);
+    }));
+    setNavigator({ sendBeacon: vi.fn(() => false) });
+    globalThis.fetch = fetchMock as any;
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop" });
+    tracker.start();
+    tracker.track({ type: "goal", event_id: "evt_pagehide", experimentId: "exp", variationId: "var" } as any);
+    const originalFlush = tracker.flush();
+    await Promise.resolve();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    windowListeners.pagehide?.();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const originalPayload = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(originalPayload.events[0]).toMatchObject({
+      event_id: "evt_pagehide",
+      experimentId: "exp",
+      variationId: "var",
+    });
+
+    resolvers[0](new Response("ok", { status: 202 }));
+    await originalFlush;
+    await vi.waitFor(() => expect(sessionStorage.getItem("drip_events")).toBeNull());
+  });
+
+  it("does not persist a recovery copy when the active keepalive request succeeds", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const pending: Array<{
+      resolve: (response: Response) => void;
+      reject: (error: Error) => void;
+    }> = [];
+    const fetchMock = vi.fn(() => new Promise<Response>((resolve, reject) => {
+      pending.push({ resolve, reject });
+    }));
+    setNavigator({ sendBeacon: vi.fn(() => false) });
+    globalThis.fetch = fetchMock as any;
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop" });
+    tracker.start();
+    tracker.track({ type: "goal", event_id: "evt_mixed", experimentId: "exp", variationId: "var" } as any);
+    const originalFlush = tracker.flush();
+    await Promise.resolve();
+
+    windowListeners.pagehide?.();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    pending[0].resolve(new Response("ok", { status: 202 }));
+    await originalFlush;
+
+    expect(sessionStorage.getItem("drip_events")).toBeNull();
+  });
+
+  it("flushes only once across hidden, pagehide, and beforeunload signals", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    const documentListeners: Record<string, () => void> = {};
+    const sendBeacon = vi.fn(() => true);
+    setNavigator({ sendBeacon });
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+    (globalThis as any).document = {
+      visibilityState: "hidden",
+      addEventListener: (name: string, handler: () => void) => {
+        documentListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "shop",
+    });
+    tracker.start();
+    tracker.track({ type: "page_exit", event_id: "evt_exit" } as any);
+
+    documentListeners.visibilitychange?.();
+    windowListeners.pagehide?.();
+    windowListeners.beforeunload?.();
+
+    expect(sendBeacon).toHaveBeenCalledTimes(1);
+    const payload = JSON.parse(await (sendBeacon.mock.calls[0][1] as Blob).text());
+    expect(payload.events).toEqual([expect.objectContaining({ event_id: "evt_exit" })]);
+
+    (document as any).visibilityState = "visible";
+    documentListeners.visibilitychange?.();
+    tracker.track({ type: "page_exit", event_id: "evt_next_exit" } as any);
+    (document as any).visibilityState = "hidden";
+    documentListeners.visibilitychange?.();
+
+    expect(sendBeacon).toHaveBeenCalledTimes(2);
+    const nextPayload = JSON.parse(await (sendBeacon.mock.calls[1][1] as Blob).text());
+    expect(nextPayload.events).toEqual([expect.objectContaining({ event_id: "evt_next_exit" })]);
+  });
+
+  it("does not persist an active failure when pagehide enters the back-forward cache", async () => {
+    const windowListeners: Record<string, (event?: { persisted?: boolean }) => void> = {};
+    let rejectRequest: ((error: Error) => void) | null = null;
+    globalThis.fetch = vi.fn(() => new Promise<Response>((_resolve, reject) => {
+      rejectRequest = reject;
+    })) as any;
+    setNavigator({ sendBeacon: vi.fn(() => true) });
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: (name: string, handler: (event?: { persisted?: boolean }) => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop", maxBatchSize: 1 });
+    tracker.start();
+    tracker.track({ type: "goal", event_id: "evt_bfcache" } as any);
+    await Promise.resolve();
+
+    windowListeners.pagehide?.({ persisted: true });
+    rejectRequest?.(new Error("network unavailable"));
+    await tracker.flush();
+
+    windowListeners.pageshow?.({ persisted: true });
+    expect(sessionStorage.getItem("drip_events")).toBeNull();
+  });
+
+  it("resets provisional teardown state when beforeunload is canceled", async () => {
+    const windowListeners: Record<string, () => void> = {};
+    let rejectRequest: ((error: Error) => void) | null = null;
+    globalThis.fetch = vi.fn(() => new Promise<Response>((_resolve, reject) => {
+      rejectRequest = reject;
+    })) as any;
+    setNavigator({ sendBeacon: vi.fn(() => true) });
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      setTimeout: (handler: () => void, ms: number) => globalThis.setTimeout(handler, ms),
+      clearTimeout: (id: number) => globalThis.clearTimeout(id),
+      addEventListener: (name: string, handler: () => void) => {
+        windowListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop", maxBatchSize: 1 });
+    tracker.start();
+    tracker.track({ type: "goal", event_id: "evt_canceled" } as any);
+    await Promise.resolve();
+
+    windowListeners.beforeunload?.();
+    await vi.runOnlyPendingTimersAsync();
+    rejectRequest?.(new Error("network unavailable"));
+    await tracker.flush();
+
+    expect(sessionStorage.getItem("drip_events")).toBeNull();
+  });
+
+  it("falls back to keepalive fetch on visibilitychange hidden when beacon is unavailable", async () => {
+    const documentListeners: Record<string, () => void> = {};
+    const fetchMock = vi.fn(async () => new Response("ok", { status: 202 }));
+    globalThis.fetch = fetchMock as any;
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+    };
+    (globalThis as any).document = {
+      visibilityState: "hidden",
+      addEventListener: (name: string, handler: () => void) => {
+        documentListeners[name] = handler;
+      },
+      removeEventListener: () => {},
+    };
+    setNavigator({ sendBeacon: undefined });
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "shop_public" });
+    tracker.start();
+    tracker.track({ type: "checkout_started", data: {} } as any);
+
+    documentListeners.visibilitychange?.();
+    await tracker.flush();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://e.test/events",
+      expect.objectContaining({
+        method: "POST",
+        keepalive: true,
+      }),
+    );
+    const payload = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(payload.events).toHaveLength(1);
+    expect(payload.events[0]).toMatchObject({ type: "checkout_started" });
+  });
+
+  it("removes unload listeners when stopped", () => {
+    const addEventListener = vi.fn();
+    const removeEventListener = vi.fn();
+    (globalThis as any).window = {
+      setInterval: () => 1,
+      clearInterval: () => {},
+      addEventListener,
+      removeEventListener,
+    };
+
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s" });
+    tracker.start();
+    tracker.stop();
+
+    expect(addEventListener).toHaveBeenCalledWith("pagehide", expect.any(Function));
+    expect(addEventListener).toHaveBeenCalledWith("beforeunload", expect.any(Function));
+    expect(addEventListener).toHaveBeenCalledWith("pageshow", expect.any(Function));
+    expect(removeEventListener).toHaveBeenCalledWith("pagehide", expect.any(Function));
+    expect(removeEventListener).toHaveBeenCalledWith("beforeunload", expect.any(Function));
+    expect(removeEventListener).toHaveBeenCalledWith("pageshow", expect.any(Function));
+    expect(removeEventListener.mock.calls[0][1]).toBe(addEventListener.mock.calls[0][1]);
+  });
+});