@drip-apex/sdk 0.1.0

package/src/track.ts

@@ -0,0 +1,519 @@
+import { cleanUrl, onPageExit } from "./analytics";
+import { lifetimeIdentityStorage } from "./hash";
+import { TrackEvent } from "./types";
+
+type TrackerOptions = {
+  endpoint: string;
+  shopId?: string;
+  ingestShopId?: string;
+  ingestSignature?: string;
+  visitorId?: string;
+  flushIntervalMs?: number;
+  maxBatchSize?: number;
+  /** Returns the active experiment/variation at unload time for page_exit attribution. */
+  getActiveAssignment?: () => { experimentId: string; variationId: string } | null;
+  /** Builds global and experiment-scoped page-exit events without flushing during unload. */
+  buildPageExitEvents?: (type: string, data?: Record<string, unknown>) => TrackEvent[];
+  /** When true, all events are tagged as QA traffic. */
+  qaMode?: boolean;
+  /** Unique QA session identifier for grouping QA events. */
+  qaSessionId?: string;
+  /** Active Apex environment stamped onto every outgoing event. */
+  environment?: string;
+};
+
+const RECOVERY_KEY = "drip_events";
+const VISITOR_SESSIONS_KEY = "drip_visitor_sessions_v1";
+
+function carriesVisitorSessions(type: string): boolean {
+  return /^(experiment_viewed|personalization_rendered|goal|conversion|pageview)$/.test(type);
+}
+
+// Enough remembered session ids that parallel tabs (each with its own
+// per-tab session) cannot ping-pong the counter upward on reloads.
+const VISITOR_SESSIONS_REMEMBERED = 8;
+
+function visitorSessionCount(sessionId: string): number | undefined {
+  try {
+    // Respect the configured storage policy: without a lifetime store
+    // (sessionStorage/memory/cookie modes) a cross-session count would lie
+    // ("new" every session), so the field is simply not stamped.
+    const store = lifetimeIdentityStorage();
+    if (!store) return undefined;
+    const raw = store.getItem(VISITOR_SESSIONS_KEY);
+    let stored: { count?: unknown; lastSessionId?: unknown; recentSessionIds?: unknown } | undefined;
+    try {
+      stored = JSON.parse(raw || "0");
+    } catch {
+      // Malformed state is equivalent to a missing counter and recovers at one.
+    }
+    const storedRecent = stored?.recentSessionIds;
+    const storedLast = stored?.lastSessionId;
+    const recent: string[] = Array.isArray(storedRecent)
+      ? (storedRecent as unknown[]).filter(
+          (id): id is string => typeof id === "string",
+        )
+      : typeof storedLast === "string"
+        ? [storedLast]
+        : [];
+    const storedCount = stored?.count;
+    const count =
+      Number.isInteger(storedCount) && Number(storedCount) > 0 && recent.length > 0
+        ? Number(storedCount)
+        : 0;
+    if (count && recent.includes(sessionId)) return count;
+    const next = count + 1;
+    store.setItem(
+      VISITOR_SESSIONS_KEY,
+      JSON.stringify({
+        count: next,
+        recentSessionIds: [sessionId, ...recent].slice(0, VISITOR_SESSIONS_REMEMBERED),
+      }),
+    );
+    // sessionStorage is per-tab, so parallel tabs mint separate sessions.
+    // This deliberately follows the SDK's existing session model; clearing
+    // browser storage restarts the lifetime counter at one.
+    return next;
+  } catch {
+    return undefined;
+  }
+}
+
+function createEventId(): string {
+  const cryptoApi = globalThis.crypto as Crypto | undefined;
+  if (typeof cryptoApi?.randomUUID === "function") {
+    return cryptoApi.randomUUID();
+  }
+  return [
+    Date.now().toString(36),
+    Math.random().toString(36).slice(2),
+    Math.random().toString(36).slice(2),
+  ].join("-");
+}
+
+export class Tracker {
+  private endpoint: string;
+  private shopId: string;
+  private ingestShopId: string;
+  private ingestSignature: string;
+  private visitorId: string;
+  private sessionId: string;
+  private visitorSessions: number | undefined;
+  private flushIntervalMs: number;
+  private maxBatchSize: number;
+  private queue: TrackEvent[] = [];
+  private activeBatch: TrackEvent[] | null = null;
+  private timer: number | null = null;
+  private flushInFlight = false;
+  private flushPromise: Promise<void> | null = null;
+  private nextFlushAt = 0;
+  private backoffMs = 0;
+  private readonly maxQueueSize = 2000;
+  private getActiveAssignment: (() => { experimentId: string; variationId: string } | null) | null;
+  private buildPageExitEvents: ((type: string, data?: Record<string, unknown>) => TrackEvent[]) | null;
+  private qaMode: boolean;
+  private qaSessionId: string;
+  private environment: string;
+  private pagehideHandler: ((event?: PageTransitionEvent) => void) | null = null;
+  private beforeUnloadHandler: (() => void) | null = null;
+  private pageshowHandler: (() => void) | null = null;
+  private beforeUnloadResetTimer: number | null = null;
+  private visibilityHandler: (() => void) | null = null;
+  private pageLifecycleFlushed = false;
+  private pageTeardownStarted = false;
+
+  constructor(options: TrackerOptions) {
+    this.endpoint = options.endpoint;
+    this.shopId = options.shopId ?? "";
+    this.ingestShopId = options.ingestShopId ?? options.shopId ?? "";
+    this.ingestSignature = options.ingestSignature ?? "";
+    this.visitorId = options.visitorId ?? "";
+    this.sessionId = this.getOrCreateSessionId();
+    this.visitorSessions = visitorSessionCount(this.sessionId);
+    this.flushIntervalMs = options.flushIntervalMs ?? 5000;
+    this.maxBatchSize = options.maxBatchSize ?? 20;
+    this.getActiveAssignment = options.getActiveAssignment ?? null;
+    this.buildPageExitEvents = options.buildPageExitEvents ?? null;
+    this.qaMode = options.qaMode ?? false;
+    this.qaSessionId = options.qaSessionId ?? "";
+    this.environment = options.environment || "production";
+  }
+
+  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 {
+    return this.sessionId;
+  }
+
+  start(): void {
+    if (this.timer !== null) return;
+    this.recoverEvents();
+    this.timer = window.setInterval(() => this.flush(), this.flushIntervalMs);
+    this.listenUnload();
+  }
+
+  stop(): void {
+    if (this.timer !== null) {
+      window.clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.pagehideHandler) window.removeEventListener("pagehide", this.pagehideHandler);
+    if (this.beforeUnloadHandler) window.removeEventListener("beforeunload", this.beforeUnloadHandler);
+    if (this.pageshowHandler) window.removeEventListener("pageshow", this.pageshowHandler);
+    if (this.beforeUnloadResetTimer !== null) window.clearTimeout(this.beforeUnloadResetTimer);
+    this.pagehideHandler = null;
+    this.beforeUnloadHandler = null;
+    this.pageshowHandler = null;
+    this.beforeUnloadResetTimer = null;
+    if (this.visibilityHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+  }
+
+  track(event: TrackEvent): void {
+    const enriched = this.enrichEvent(event);
+    this.queue.push(enriched);
+    // Prevent unbounded growth during outages (Black Friday spikes, offline, ad blockers).
+    if (this.queue.length > this.maxQueueSize) {
+      this.queue.splice(0, this.queue.length - this.maxQueueSize);
+    }
+    if (this.queue.length >= this.maxBatchSize) {
+      void this.flush();
+    }
+  }
+
+  private enrichEvent(event: TrackEvent): TrackEvent {
+    const enriched: TrackEvent = {
+      ...event,
+      event_id:
+        typeof event.event_id === "string" && event.event_id.trim()
+          ? event.event_id
+          : createEventId(),
+      shopId: event.shopId ?? this.shopId,
+      visitorId: event.visitorId ?? this.visitorId,
+      sessionId: event.sessionId ?? this.sessionId,
+      url: event.url ?? (typeof location !== "undefined" ? location.href : ""),
+      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;
+    }
+    return enriched;
+  }
+
+  private scheduleBackoff(ms: number): void {
+    const jitter = Math.floor(Math.random() * 250);
+    this.backoffMs = Math.max(this.backoffMs, ms);
+    this.nextFlushAt = Date.now() + this.backoffMs + jitter;
+  }
+
+  private resetBackoff(): void {
+    this.backoffMs = 0;
+    this.nextFlushAt = 0;
+  }
+
+  private parseRetryAfterSeconds(value: string | null): number | null {
+    if (!value) return null;
+    const n = Number.parseInt(value, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+    return null;
+  }
+
+  async flush(): Promise<void> {
+    if (this.flushPromise) return this.flushPromise;
+    if (!this.queue.length || !this.endpoint) return;
+    if (this.nextFlushAt && Date.now() < this.nextFlushAt) return;
+
+    const flushPromise = this.drainQueue();
+    this.flushPromise = flushPromise;
+    try {
+      await flushPromise;
+    } finally {
+      if (this.flushPromise === flushPromise) {
+        this.flushPromise = null;
+      }
+    }
+  }
+
+  private async drainQueue(): Promise<void> {
+    try {
+      this.flushInFlight = true;
+      while (this.queue.length && this.endpoint) {
+        if (this.nextFlushAt && Date.now() < this.nextFlushAt) return;
+
+        // Never send unbounded payloads. Worker rejects >200 events; keep batches small.
+        const batch = this.queue.splice(0, this.maxBatchSize);
+        this.activeBatch = batch;
+        if (!batch.length) return;
+        const res = await fetch(this.endpoint, {
+          method: "POST",
+          headers: this.buildHeaders(),
+          body: this.buildPayload(batch),
+          keepalive: true,
+        });
+        if (res.ok) {
+          this.removeRecovery(batch);
+          this.activeBatch = null;
+          this.resetBackoff();
+          continue;
+        }
+
+        // Re-queue on any non-2xx response.
+        this.queue.unshift(...batch);
+        this.activeBatch = null;
+        if (this.pageTeardownStarted) this.saveRecovery(batch);
+
+        if (res.status === 429) {
+          const retryAfter = this.parseRetryAfterSeconds(res.headers.get("Retry-After"));
+          const waitMs = retryAfter ? retryAfter * 1000 : 5_000;
+          this.scheduleBackoff(waitMs);
+          return;
+        }
+
+        if (res.status === 401 || res.status === 403) {
+          // Likely expired/invalid signature. Keep events in memory/sessionStorage and retry rarely.
+          this.scheduleBackoff(5 * 60_000);
+          return;
+        }
+
+        if (res.status >= 500) {
+          // Exponential backoff up to 60s.
+          const next = this.backoffMs ? Math.min(60_000, this.backoffMs * 2) : 1_000;
+          this.scheduleBackoff(next);
+          return;
+        }
+
+        // For other 4xx (e.g. bad payload), don't spin. Retry slowly.
+        this.scheduleBackoff(30_000);
+        return;
+      }
+    } catch {
+      // Network failure (offline, blocked, transient). Requeue and back off.
+      if (this.activeBatch?.length) {
+        this.queue.unshift(...this.activeBatch);
+        if (this.pageTeardownStarted) this.saveRecovery(this.activeBatch);
+        this.activeBatch = null;
+      }
+      const next = this.backoffMs ? Math.min(60_000, this.backoffMs * 2) : 1_000;
+      this.scheduleBackoff(next);
+    } finally {
+      this.flushInFlight = false;
+    }
+  }
+
+  private buildPayload(batch: TrackEvent[]): string {
+    const body: Record<string, unknown> = { events: batch };
+    // 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;
+    return JSON.stringify(body);
+  }
+
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (this.ingestShopId) headers["X-Drip-Shop"] = this.ingestShopId;
+    if (this.ingestSignature) headers["X-Drip-Signature"] = this.ingestSignature;
+    return headers;
+  }
+
+  private recoveryEventKey(event: TrackEvent): string | null {
+    const eventId = typeof event.event_id === "string" ? event.event_id.trim() : "";
+    if (!eventId) return null;
+    return JSON.stringify([
+      eventId,
+      event.type,
+      event.experimentId ?? null,
+      event.variationId ?? null,
+      event.environment || "production",
+    ]);
+  }
+
+  private readRecovery(): TrackEvent[] {
+    try {
+      const raw = sessionStorage.getItem(RECOVERY_KEY);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed as TrackEvent[] : [];
+    } catch {
+      return [];
+    }
+  }
+
+  private saveRecovery(events: TrackEvent[]): void {
+    if (!events.length) return;
+    const merged = [...this.readRecovery(), ...events];
+    const keyed = new Map<string, TrackEvent>();
+    const unkeyed: TrackEvent[] = [];
+    for (const event of merged) {
+      const key = this.recoveryEventKey(event);
+      if (key) keyed.set(key, event);
+      else unkeyed.push(event);
+    }
+    const bounded = [...keyed.values(), ...unkeyed].slice(-this.maxQueueSize);
+    try {
+      sessionStorage.setItem(RECOVERY_KEY, JSON.stringify(bounded));
+    } catch {}
+  }
+
+  private removeRecovery(events: TrackEvent[]): void {
+    const deliveredKeys = new Set(
+      events
+        .map((event) => this.recoveryEventKey(event))
+        .filter((key): key is string => key !== null),
+    );
+    if (deliveredKeys.size === 0) return;
+    try {
+      const remaining = this.readRecovery().filter((event) => {
+        const key = this.recoveryEventKey(event);
+        return key === null || !deliveredKeys.has(key);
+      });
+      if (remaining.length) sessionStorage.setItem(RECOVERY_KEY, JSON.stringify(remaining));
+      else sessionStorage.removeItem(RECOVERY_KEY);
+    } catch {}
+  }
+
+  private queuePageExitEvents(): void {
+    const assignment = this.getActiveAssignment?.() ?? null;
+    onPageExit((type, data) => {
+      const events = this.buildPageExitEvents
+        ? this.buildPageExitEvents(type, data)
+        : [{
+            type,
+            data,
+            experimentId: assignment?.experimentId,
+            variationId: assignment?.variationId,
+            url: cleanUrl(),
+          }];
+      this.queue.push(...events.map((event) => this.enrichEvent(event)));
+    });
+  }
+
+  private flushForPageLifecycle(terminal = false): void {
+    const alreadyFlushed = this.pageLifecycleFlushed;
+    if (terminal) this.pageTeardownStarted = true;
+    if (alreadyFlushed && (!terminal || this.queue.length === 0)) return;
+    if (!alreadyFlushed) {
+      this.pageLifecycleFlushed = true;
+      this.queuePageExitEvents();
+    }
+    // drainQueue already handed activeBatch to a keepalive fetch. Sending that
+    // same batch again with beacon creates a guaranteed overlap when both
+    // requests reach the Worker. If the active request later fails, drainQueue
+    // persists its stable event IDs because the page has entered teardown.
+    const lifecycleEvents = this.queue.splice(0);
+    if (!lifecycleEvents.length) return;
+    if (!this.endpoint) {
+      this.saveRecovery(lifecycleEvents);
+      return;
+    }
+
+    while (lifecycleEvents.length) {
+      const batch = lifecycleEvents.splice(0, this.maxBatchSize);
+      const payload = this.buildPayload(batch);
+      let queued = false;
+
+      try {
+        const nav = typeof navigator !== "undefined" ? navigator : undefined;
+        if (typeof nav?.sendBeacon === "function") {
+          queued = nav.sendBeacon(
+            this.endpoint,
+            new Blob([payload], { type: "text/plain" }),
+          );
+        }
+      } catch {
+        queued = false;
+      }
+
+      if (queued) continue;
+
+      try {
+        void fetch(this.endpoint, {
+          method: "POST",
+          headers: this.buildHeaders(),
+          body: payload,
+          keepalive: true,
+        })
+          .then((response) => {
+            if (!response.ok) this.saveRecovery(batch);
+          })
+          .catch(() => {
+            this.saveRecovery(batch);
+          });
+      } catch {
+        this.saveRecovery(batch);
+      }
+    }
+  }
+
+  private recoverEvents(): void {
+    try {
+      const events = this.readRecovery().map((event) => ({
+        ...event,
+        environment: event.environment || this.environment,
+      }));
+      if (events.length) {
+        sessionStorage.removeItem(RECOVERY_KEY);
+        this.queue.unshift(...events);
+      }
+    } catch {}
+  }
+
+  private resetPageLifecycle(): void {
+    this.pageLifecycleFlushed = false;
+    this.pageTeardownStarted = false;
+    this.beforeUnloadResetTimer = null;
+  }
+
+  private listenUnload(): void {
+    if (this.pagehideHandler) return;
+    const onPagehide = (event?: PageTransitionEvent) => {
+      this.flushForPageLifecycle(event?.persisted !== true);
+    };
+    const onBeforeUnload = () => {
+      this.flushForPageLifecycle(true);
+      // A beforeunload prompt can be canceled. A real navigation prevents this
+      // task from running (and pagehide confirms terminal teardown); a live tab
+      // clears the provisional terminal state before later retries.
+      if (this.beforeUnloadResetTimer === null && typeof window.setTimeout === "function") {
+        this.beforeUnloadResetTimer = window.setTimeout(() => this.resetPageLifecycle(), 0);
+      }
+    };
+    const onPageShow = () => this.resetPageLifecycle();
+    this.pagehideHandler = onPagehide;
+    this.beforeUnloadHandler = onBeforeUnload;
+    this.pageshowHandler = onPageShow;
+    window.addEventListener("pagehide", onPagehide);
+    window.addEventListener("beforeunload", onBeforeUnload);
+    window.addEventListener("pageshow", onPageShow);
+    if (typeof document !== "undefined") {
+      const onVisibilityChange = () => {
+        if (document.visibilityState === "hidden") this.flushForPageLifecycle();
+        else this.resetPageLifecycle();
+      };
+      this.visibilityHandler = onVisibilityChange;
+      document.addEventListener("visibilitychange", onVisibilityChange);
+    }
+  }
+}