@drip-apex/sdk 0.1.0 → 0.2.0

package/src/track.test.ts

@@ -18,6 +18,7 @@ describe("Tracker flush resilience", () => {
   const realSessionStorage = (globalThis as any).sessionStorage;
   const realLocalStorage = (globalThis as any).localStorage;
   const realNavigatorDescriptor = Object.getOwnPropertyDescriptor(globalThis, "navigator");
+  const realLocationDescriptor = Object.getOwnPropertyDescriptor(globalThis, "location");
 
   function setNavigator(value: unknown): void {
     Object.defineProperty(globalThis, "navigator", {
@@ -39,6 +40,10 @@ describe("Tracker flush resilience", () => {
       addEventListener: () => {},
       removeEventListener: () => {},
     };
+    Object.defineProperty(globalThis, "location", {
+      configurable: true,
+      value: new URL("https://store.example/"),
+    });
   });
 
   afterEach(() => {
@@ -51,6 +56,8 @@ describe("Tracker flush resilience", () => {
     } else {
       delete (globalThis as any).navigator;
     }
+    if (realLocationDescriptor) Object.defineProperty(globalThis, "location", realLocationDescriptor);
+    else delete (globalThis as any).location;
     (globalThis as any).sessionStorage = realSessionStorage;
     (globalThis as any).localStorage = realLocalStorage;
     vi.restoreAllMocks();
@@ -71,6 +78,73 @@ describe("Tracker flush resilience", () => {
     }
   });
 
+  it("tags both holdout and active events when program holdout is enabled", async () => {
+    const bodies: string[] = [];
+    globalThis.fetch = vi.fn(async (_url, init) => {
+      bodies.push(String(init?.body));
+      return new Response(null, { status: 202 });
+    }) as typeof fetch;
+    const holdout = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "s",
+      cohort: "holdout",
+      holdoutConfigEpoch: 1_785_104_515_000,
+      maxBatchSize: 1,
+    });
+    holdout.track({ type: "pageview", data: {} });
+    await holdout.flush();
+    const active = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "s",
+      cohort: "active",
+      holdoutConfigEpoch: 1_785_104_515_000,
+      maxBatchSize: 1,
+    });
+    active.track({ type: "pageview", data: {} });
+    await active.flush();
+    expect(bodies[0]).toContain('"cohort":"holdout"');
+    expect(bodies[0]).toContain('"holdout_config_epoch":1785104515000');
+    expect(bodies[1]).toContain('"cohort":"active"');
+    expect(bodies[1]).toContain('"holdout_config_epoch":1785104515000');
+  });
+
+  it("keeps SDK cohort metadata ahead of the Worker property cap", async () => {
+    let eventData: Record<string, unknown> | undefined;
+    globalThis.fetch = vi.fn(async (_url, init) => {
+      const payload = JSON.parse(String(init?.body)) as {
+        events: Array<{ data?: Record<string, unknown> }>;
+      };
+      eventData = payload.events[0]?.data;
+      return new Response(null, { status: 202 });
+    }) as typeof fetch;
+    const merchantData = Object.fromEntries(
+      Array.from({ length: 85 }, (_, index) => [`merchant_${index}`, index]),
+    );
+    const tracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "s",
+      cohort: "holdout",
+      holdoutConfigEpoch: 1_785_104_515_000,
+      maxBatchSize: 1,
+    });
+
+    tracker.track({
+      type: "custom",
+      data: { ...merchantData, cohort: "merchant-override" },
+    });
+    await tracker.flush();
+
+    expect(eventData?.cohort).toBe("holdout");
+    expect(eventData?.holdout_config_epoch).toBe(1_785_104_515_000);
+    expect(Object.keys(eventData ?? {})[0]).toBe("cohort");
+    const workerCappedData = Object.fromEntries(
+      Object.entries(eventData ?? {}).slice(0, 80),
+    );
+    expect(workerCappedData.cohort).toBe("holdout");
+    expect(workerCappedData.holdout_config_epoch).toBe(1_785_104_515_000);
+    expect(workerCappedData.merchant_84).toBeUndefined();
+  });
+
   it("counts lifetime visitor sessions without double-counting tracker re-initialization", () => {
     sessionStorage.setItem("drip_sid", "session-one");
 
@@ -792,6 +866,79 @@ describe("Tracker flush resilience", () => {
     expect(payload.events[0]).toMatchObject({ type: "checkout_started" });
   });
 
+  it("uses the Shopify proxy and does not direct-send after a 2xx", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 202 }));
+    globalThis.fetch = fetchMock as typeof fetch;
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s", maxBatchSize: 1, proxyEventDelivery: { enabled: true } });
+    tracker.track({ type: "pageview" });
+    await tracker.flush();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(String(fetchMock.mock.calls[0]?.[0])).toContain("/apps/apex/events");
+  });
+
+  it("rejects an absolute proxy path and keeps delivery on the storefront origin", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 202 }));
+    globalThis.fetch = fetchMock as typeof fetch;
+    const tracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "s",
+      maxBatchSize: 1,
+      proxyEventDelivery: { enabled: true, path: "https://evil.example/events" },
+    });
+    tracker.track({ type: "pageview" });
+    await tracker.flush();
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("https://store.example/apps/apex/events");
+  });
+
+  it("retries the same proxy batch directly once with a downgrade marker", async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(new Response(null, { status: 502 }))
+      .mockResolvedValueOnce(new Response(null, { status: 202 }));
+    globalThis.fetch = fetchMock as typeof fetch;
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s", maxBatchSize: 1, proxyEventDelivery: { enabled: true } });
+    tracker.track({ type: "pageview", data: { original: true } });
+    await tracker.flush();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[1]?.[0]).toBe("https://e.test/events");
+    expect(String(fetchMock.mock.calls[1]?.[1]?.body)).toContain('"delivery_downgrade":"proxy_failed"');
+  });
+
+  it("marks every event after an asset fallback", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 202 }));
+    globalThis.fetch = fetchMock as typeof fetch;
+    const tracker = new Tracker({ endpoint: "https://e.test/events", shopId: "s", maxBatchSize: 2, assetFallback: true });
+    tracker.track({ type: "sdk_perf" });
+    tracker.track({ type: "pageview", data: { asset_fallback: false } });
+    await tracker.flush();
+    const payload = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body));
+    expect(payload.events).toHaveLength(2);
+    expect(payload.events.every((event: { data: Record<string, unknown> }) => event.data.asset_fallback === true)).toBe(true);
+  });
+
+  it("falls back synchronously to the direct beacon when the proxy unload beacon is refused", () => {
+    let pagehide: (() => void) | undefined;
+    (globalThis as any).window.addEventListener = (name: string, handler: () => void) => {
+      if (name === "pagehide") pagehide = handler;
+    };
+    const sendBeacon = vi.fn()
+      .mockReturnValueOnce(false)
+      .mockReturnValueOnce(true);
+    setNavigator({ sendBeacon });
+    const tracker = new Tracker({
+      endpoint: "https://e.test/events",
+      shopId: "s",
+      proxyEventDelivery: { enabled: true },
+    });
+    tracker.start();
+    tracker.track({ type: "pageview" });
+    pagehide?.();
+
+    expect(sendBeacon).toHaveBeenCalledTimes(2);
+    expect(sendBeacon.mock.calls[0]?.[0]).toBe("https://store.example/apps/apex/events");
+    expect(sendBeacon.mock.calls[1]?.[0]).toBe("https://e.test/events");
+    expect(sendBeacon.mock.calls[1]?.[1]).toBeInstanceOf(Blob);
+  });
+
   it("removes unload listeners when stopped", () => {
     const addEventListener = vi.fn();
     const removeEventListener = vi.fn();

package/src/track.ts

@@ -4,6 +4,8 @@ import { TrackEvent } from "./types";
 
 type TrackerOptions = {
   endpoint: string;
+  proxyEventDelivery?: { enabled: boolean; path?: string };
+  assetFallback?: boolean;
   shopId?: string;
   ingestShopId?: string;
   ingestSignature?: string;
@@ -20,8 +22,24 @@ type TrackerOptions = {
   qaSessionId?: string;
   /** Active Apex environment stamped onto every outgoing event. */
   environment?: string;
+  /** Global cohort stamped on every event while program holdout is enabled. */
+  cohort?: "holdout" | "active";
+  /** Reporting epoch of the configuration that produced the global cohort. */
+  holdoutConfigEpoch?: number;
 };
 
+export function getOrCreateSessionId(): string {
+  try {
+    const existing = sessionStorage.getItem("drip_sid");
+    if (existing) return existing;
+    const id = Math.random().toString(36).slice(2) + Date.now().toString(36);
+    sessionStorage.setItem("drip_sid", id);
+    return id;
+  } catch {
+    return Math.random().toString(36).slice(2) + Date.now().toString(36);
+  }
+}
+
 const RECOVERY_KEY = "drip_events";
 const VISITOR_SESSIONS_KEY = "drip_visitor_sessions_v1";
 
@@ -79,7 +97,7 @@ function visitorSessionCount(sessionId: string): number | undefined {
   }
 }
 
-function createEventId(): string {
+export function createEventId(): string {
   const cryptoApi = globalThis.crypto as Crypto | undefined;
   if (typeof cryptoApi?.randomUUID === "function") {
     return cryptoApi.randomUUID();
@@ -93,6 +111,7 @@ function createEventId(): string {
 
 export class Tracker {
   private endpoint: string;
+  private proxyEndpoint: string | null;
   private shopId: string;
   private ingestShopId: string;
   private ingestSignature: string;
@@ -114,6 +133,9 @@ export class Tracker {
   private qaMode: boolean;
   private qaSessionId: string;
   private environment: string;
+  private cohort: "holdout" | "active" | undefined;
+  private holdoutConfigEpoch: number | undefined;
+  private assetFallback: boolean;
   private pagehideHandler: ((event?: PageTransitionEvent) => void) | null = null;
   private beforeUnloadHandler: (() => void) | null = null;
   private pageshowHandler: (() => void) | null = null;
@@ -124,11 +146,12 @@ export class Tracker {
 
   constructor(options: TrackerOptions) {
     this.endpoint = options.endpoint;
+    this.proxyEndpoint = resolveProxyEventEndpoint(options.proxyEventDelivery);
     this.shopId = options.shopId ?? "";
     this.ingestShopId = options.ingestShopId ?? options.shopId ?? "";
     this.ingestSignature = options.ingestSignature ?? "";
     this.visitorId = options.visitorId ?? "";
-    this.sessionId = this.getOrCreateSessionId();
+    this.sessionId = getOrCreateSessionId();
     this.visitorSessions = visitorSessionCount(this.sessionId);
     this.flushIntervalMs = options.flushIntervalMs ?? 5000;
     this.maxBatchSize = options.maxBatchSize ?? 20;
@@ -137,20 +160,16 @@ export class Tracker {
     this.qaMode = options.qaMode ?? false;
     this.qaSessionId = options.qaSessionId ?? "";
     this.environment = options.environment || "production";
+    this.cohort = options.cohort;
+    this.holdoutConfigEpoch =
+      Number.isSafeInteger(options.holdoutConfigEpoch) &&
+      (options.holdoutConfigEpoch ?? 0) > 0
+        ? options.holdoutConfigEpoch
+        : undefined;
+    this.assetFallback = options.assetFallback === true;
   }
 
-  private getOrCreateSessionId(): string {
-    const key = "drip_sid";
-    try {
-      const existing = sessionStorage.getItem(key);
-      if (existing) return existing;
-      const id = Math.random().toString(36).slice(2) + Date.now().toString(36);
-      sessionStorage.setItem(key, id);
-      return id;
-    } catch {
-      return Math.random().toString(36).slice(2) + Date.now().toString(36);
-    }
-  }
+
 
   /** Public accessor for the session ID (used by the Shopify pixel bridge). */
   getSessionId(): string {
@@ -196,8 +215,32 @@ export class Tracker {
   }
 
   private enrichEvent(event: TrackEvent): TrackEvent {
+    const systemData: Record<string, unknown> = {};
+    if (this.assetFallback) systemData.asset_fallback = true;
+    if (this.cohort) {
+      systemData.cohort = this.cohort;
+      if (this.holdoutConfigEpoch) {
+        systemData.holdout_config_epoch = this.holdoutConfigEpoch;
+      }
+    }
+    if (
+      this.visitorSessions &&
+      carriesVisitorSessions(event.type) &&
+      !("visitor_sessions" in (event.data ?? {}))
+    ) {
+      systemData.visitor_sessions = this.visitorSessions;
+    }
     const enriched: TrackEvent = {
       ...event,
+      ...(Object.keys(systemData).length > 0
+        ? {
+            // Worker sanitization retains the first 80 insertion-ordered
+            // properties. Insert trusted SDK fields before merchant data, then
+            // re-stamp them so user input cannot override their values without
+            // moving their insertion position behind the cap.
+            data: { ...systemData, ...event.data, ...systemData },
+          }
+        : {}),
       event_id:
         typeof event.event_id === "string" && event.event_id.trim()
           ? event.event_id
@@ -209,13 +252,6 @@ export class Tracker {
       ts: event.ts ?? Date.now(),
       environment: this.environment,
     };
-    if (
-      this.visitorSessions &&
-      carriesVisitorSessions(event.type) &&
-      !("visitor_sessions" in (event.data ?? {}))
-    ) {
-      enriched.data = { ...event.data, visitor_sessions: this.visitorSessions };
-    }
     if (this.qaMode) {
       enriched.qa_mode = true;
       if (this.qaSessionId) enriched.qa_session_id = this.qaSessionId;
@@ -267,10 +303,31 @@ export class Tracker {
         const batch = this.queue.splice(0, this.maxBatchSize);
         this.activeBatch = batch;
         if (!batch.length) return;
-        const res = await fetch(this.endpoint, {
+        const payload = this.buildPayload(batch);
+        let res: Response;
+        if (this.proxyEndpoint) {
+          try {
+            res = await fetch(this.proxyEndpoint, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: payload,
+              keepalive: true,
+            });
+          } catch {
+            res = new Response(null, { status: 503 });
+          }
+          if (!res.ok) {
+            res = await fetch(this.endpoint, {
+              method: "POST",
+              headers: this.buildHeaders(),
+              body: this.buildPayload(batch, "proxy_failed"),
+              keepalive: true,
+            });
+          }
+        } else res = await fetch(this.endpoint, {
           method: "POST",
           headers: this.buildHeaders(),
-          body: this.buildPayload(batch),
+          body: payload,
           keepalive: true,
         });
         if (res.ok) {
@@ -323,8 +380,11 @@ export class Tracker {
     }
   }
 
-  private buildPayload(batch: TrackEvent[]): string {
-    const body: Record<string, unknown> = { events: batch };
+  private buildPayload(batch: TrackEvent[], deliveryDowngrade?: string): string {
+    const events = deliveryDowngrade
+      ? batch.map((event) => ({ ...event, data: { ...event.data, delivery_downgrade: deliveryDowngrade } }))
+      : batch;
+    const body: Record<string, unknown> = { events };
     // Include auth in payload body so sendBeacon (which can't set headers) works.
     if (this.ingestShopId) body._shopId = this.ingestShopId;
     if (this.ingestSignature) body._signature = this.ingestSignature;
@@ -431,9 +491,27 @@ export class Tracker {
 
     while (lifecycleEvents.length) {
       const batch = lifecycleEvents.splice(0, this.maxBatchSize);
-      const payload = this.buildPayload(batch);
+      let payload = this.buildPayload(batch);
       let queued = false;
 
+      if (this.proxyEndpoint) {
+        try {
+          const nav = typeof navigator !== "undefined" ? navigator : undefined;
+          if (typeof nav?.sendBeacon === "function") {
+            queued = nav.sendBeacon(
+              this.proxyEndpoint,
+              new Blob([payload], { type: "text/plain" }),
+            );
+          }
+        } catch {
+          queued = false;
+        }
+        if (queued) continue;
+        // Fall through to the established direct unload lane with an explicit
+        // downgrade marker when the same-origin proxy beacon cannot be queued.
+        payload = this.buildPayload(batch, "proxy_failed");
+      }
+
       try {
         const nav = typeof navigator !== "undefined" ? navigator : undefined;
         if (typeof nav?.sendBeacon === "function") {
@@ -517,3 +595,24 @@ export class Tracker {
     }
   }
 }
+
+function resolveProxyEventEndpoint(config: TrackerOptions["proxyEventDelivery"]): string | null {
+  if (!config?.enabled || typeof location === "undefined") return null;
+  const host = location.hostname.toLowerCase();
+  if (
+    host === "app.drip-apex.com"
+    || host === "app-staging.drip-apex.com"
+    || host === "commerce.drip-apex.com"
+    || host === "preview.drip-apex.com"
+    || host.endsWith(".workers.dev")
+  ) return null;
+  const configuredPath = config.path?.trim();
+  const path = configuredPath && configuredPath.startsWith("/") && !configuredPath.startsWith("//")
+    ? configuredPath
+    : "/apps/apex/events";
+  try {
+    return new URL(path, location.origin).toString();
+  } catch {
+    return null;
+  }
+}