@probat/react 0.4.4 → 0.4.6

package/src/utils/eventContext.ts

@@ -1,20 +1,27 @@
 /**
- * Event context helpers: distinct_id, session_id, page info.
- * All browser-safe — no-ops when window is unavailable.
+ * Event context helpers: identity/session/page metadata.
+ * Browser-safe — returns static values on the server.
  */
 
 const DISTINCT_ID_KEY = "probat:distinct_id";
 const SESSION_ID_KEY = "probat:session_id";
+const SESSION_START_AT_KEY = "probat:session_start_at";
+const SESSION_SEQUENCE_KEY = "probat:session_sequence";
+const SESSION_LAST_ACTIVITY_AT_KEY = "probat:session_last_activity_at";
+
+const SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 
 let cachedDistinctId: string | null = null;
 let cachedSessionId: string | null = null;
+let cachedSessionStartAt: string | null = null;
+let cachedSessionSequence = 0;
+let cachedLastActivityAt = 0;
 
 function generateId(): string {
     // crypto.randomUUID where available, else fallback
     if (typeof crypto !== "undefined" && crypto.randomUUID) {
         return crypto.randomUUID();
     }
-    // fallback: random hex
     const bytes = new Uint8Array(16);
     if (typeof crypto !== "undefined" && crypto.getRandomValues) {
         crypto.getRandomValues(bytes);
@@ -24,6 +31,92 @@ function generateId(): string {
     return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+function nowMs(): number {
+    return Date.now();
+}
+
+function startNewSession(tsMs: number): void {
+    if (typeof window === "undefined") return;
+    const sid = `sess_${generateId()}`;
+    const startedAt = new Date(tsMs).toISOString();
+    cachedSessionId = sid;
+    cachedSessionStartAt = startedAt;
+    cachedSessionSequence = 0;
+    cachedLastActivityAt = tsMs;
+    try {
+        sessionStorage.setItem(SESSION_ID_KEY, sid);
+        sessionStorage.setItem(SESSION_START_AT_KEY, startedAt);
+        sessionStorage.setItem(SESSION_SEQUENCE_KEY, "0");
+        sessionStorage.setItem(SESSION_LAST_ACTIVITY_AT_KEY, String(tsMs));
+    } catch {}
+}
+
+function hydrateSessionFromStorage(tsMs: number): void {
+    if (typeof window === "undefined") return;
+
+    if (cachedSessionId && cachedSessionStartAt) {
+        const expiredInMemory =
+            !Number.isFinite(cachedLastActivityAt) ||
+            cachedLastActivityAt <= 0 ||
+            tsMs - cachedLastActivityAt > SESSION_IDLE_TIMEOUT_MS;
+        if (expiredInMemory) {
+            startNewSession(tsMs);
+        }
+        return;
+    }
+
+    try {
+        const sid = sessionStorage.getItem(SESSION_ID_KEY);
+        const startedAt = sessionStorage.getItem(SESSION_START_AT_KEY);
+        const sequenceRaw = sessionStorage.getItem(SESSION_SEQUENCE_KEY);
+        const lastActivityRaw = sessionStorage.getItem(SESSION_LAST_ACTIVITY_AT_KEY);
+        const sequence = Number(sequenceRaw || "0");
+        const lastActivity = Number(lastActivityRaw || "0");
+
+        if (!sid || !startedAt) {
+            startNewSession(tsMs);
+            return;
+        }
+
+        const expired =
+            !Number.isFinite(lastActivity) ||
+            lastActivity <= 0 ||
+            tsMs - lastActivity > SESSION_IDLE_TIMEOUT_MS;
+
+        if (expired) {
+            startNewSession(tsMs);
+            return;
+        }
+
+        cachedSessionId = sid;
+        cachedSessionStartAt = startedAt;
+        cachedSessionSequence = Number.isFinite(sequence) && sequence >= 0 ? sequence : 0;
+        cachedLastActivityAt = lastActivity > 0 ? lastActivity : tsMs;
+    } catch {
+        startNewSession(tsMs);
+    }
+}
+
+function ensureSession(tsMs: number): void {
+    if (typeof window === "undefined") return;
+    hydrateSessionFromStorage(tsMs);
+    if (!cachedSessionId || !cachedSessionStartAt) {
+        startNewSession(tsMs);
+    }
+}
+
+function bumpSequence(tsMs: number): number {
+    if (typeof window === "undefined") return 0;
+    ensureSession(tsMs);
+    cachedSessionSequence += 1;
+    cachedLastActivityAt = tsMs;
+    try {
+        sessionStorage.setItem(SESSION_SEQUENCE_KEY, String(cachedSessionSequence));
+        sessionStorage.setItem(SESSION_LAST_ACTIVITY_AT_KEY, String(tsMs));
+    } catch {}
+    return cachedSessionSequence;
+}
+
 export function getDistinctId(): string {
     if (cachedDistinctId) return cachedDistinctId;
     if (typeof window === "undefined") return "server";
@@ -43,21 +136,15 @@ export function getDistinctId(): string {
 }
 
 export function getSessionId(): string {
-    if (cachedSessionId) return cachedSessionId;
     if (typeof window === "undefined") return "server";
-    try {
-        const stored = sessionStorage.getItem(SESSION_ID_KEY);
-        if (stored) {
-            cachedSessionId = stored;
-            return stored;
-        }
-    } catch {}
-    const id = `sess_${generateId()}`;
-    cachedSessionId = id;
-    try {
-        sessionStorage.setItem(SESSION_ID_KEY, id);
-    } catch {}
-    return id;
+    ensureSession(nowMs());
+    return cachedSessionId || "server";
+}
+
+export function getSessionStartAt(): string {
+    if (typeof window === "undefined") return new Date(0).toISOString();
+    ensureSession(nowMs());
+    return cachedSessionStartAt || new Date(0).toISOString();
 }
 
 export function getPageKey(): string {
@@ -81,14 +168,27 @@ export interface EventContext {
     $page_url: string;
     $pathname: string;
     $referrer: string;
+    $session_sequence: number;
+    $session_start_at: string;
 }
 
 export function buildEventContext(): EventContext {
+    const ts = nowMs();
     return {
         distinct_id: getDistinctId(),
         session_id: getSessionId(),
         $page_url: getPageUrl(),
         $pathname: typeof window !== "undefined" ? window.location.pathname : "",
         $referrer: getReferrer(),
+        $session_sequence: bumpSequence(ts),
+        $session_start_at: getSessionStartAt(),
     };
 }
+
+export function resetEventContextStateForTests(): void {
+    cachedDistinctId = null;
+    cachedSessionId = null;
+    cachedSessionStartAt = null;
+    cachedSessionSequence = 0;
+    cachedLastActivityAt = 0;
+}

package/src/utils/eventQueue.ts

@@ -0,0 +1,157 @@
+import type { StructuredEvent } from "../types/events";
+
+interface BatchBody {
+    events: StructuredEvent[];
+}
+
+export class EventQueue {
+    private queue: StructuredEvent[] = [];
+    private flushTimer: ReturnType<typeof setTimeout> | null = null;
+    private readonly maxBatchSize = 20;
+    private readonly flushIntervalMs = 5000;
+    private readonly endpointBatch: string;
+    private readonly endpointSingle: string;
+    private readonly apiKey?: string;
+
+    constructor(host: string, apiKey?: string) {
+        const normalized = host.replace(/\/$/, "");
+        this.endpointBatch = `${normalized}/experiment/metrics/batch`;
+        this.endpointSingle = `${normalized}/experiment/metrics`;
+        this.apiKey = apiKey;
+    }
+
+    enqueue(event: StructuredEvent): void {
+        this.queue.push(event);
+        if (this.queue.length >= this.maxBatchSize) {
+            this.flush();
+            return;
+        }
+        if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => {
+                this.flush();
+            }, this.flushIntervalMs);
+        }
+    }
+
+    flush(forceBeacon = false): void {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.queue.length === 0) return;
+
+        const batch = this.queue.splice(0, this.maxBatchSize);
+        this.send(batch, forceBeacon);
+
+        if (this.queue.length > 0) {
+            this.flushTimer = setTimeout(() => {
+                this.flush();
+            }, this.flushIntervalMs);
+        }
+    }
+
+    private send(batch: StructuredEvent[], forceBeacon = false): void {
+        const body: BatchBody = { events: batch };
+        const encodedBody = JSON.stringify(body);
+        const headers: Record<string, string> = { "Content-Type": "application/json" };
+        if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+        const canBeacon =
+            typeof navigator !== "undefined" &&
+            typeof navigator.sendBeacon === "function" &&
+            !this.apiKey &&
+            (
+                forceBeacon ||
+                (typeof document !== "undefined" && document.visibilityState === "hidden")
+            );
+
+        if (canBeacon) {
+            navigator.sendBeacon(this.endpointBatch, encodedBody);
+            return;
+        }
+
+        try {
+            if (batch.length === 1) {
+                fetch(this.endpointSingle, {
+                    method: "POST",
+                    headers,
+                    credentials: "include",
+                    body: JSON.stringify(batch[0]),
+                    keepalive: true,
+                }).catch(() => {});
+                return;
+            }
+            fetch(this.endpointBatch, {
+                method: "POST",
+                headers,
+                credentials: "include",
+                body: encodedBody,
+                keepalive: true,
+            }).catch(() => {});
+        } catch {
+            // Deliberately drop failed batches (current behavior parity).
+        }
+    }
+}
+
+const queuesByHost = new Map<string, EventQueue>();
+let lifecycleListenersInstalled = false;
+
+function installLifecycleListeners(): void {
+    if (lifecycleListenersInstalled || typeof window === "undefined") return;
+    lifecycleListenersInstalled = true;
+
+    const flushWithBeacon = () => {
+        for (const queue of queuesByHost.values()) {
+            queue.flush(true);
+        }
+    };
+
+    const flushNormally = () => {
+        for (const queue of queuesByHost.values()) {
+            queue.flush(false);
+        }
+    };
+
+    window.addEventListener("pagehide", flushWithBeacon);
+    window.addEventListener("beforeunload", flushWithBeacon);
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") {
+            flushWithBeacon();
+        } else {
+            flushNormally();
+        }
+    });
+}
+
+function queueKey(host: string, apiKey?: string): string {
+    const normalized = host.replace(/\/$/, "");
+    return apiKey ? `${normalized}::${apiKey}` : `${normalized}::__no_key__`;
+}
+
+export function getEventQueue(host: string, apiKey?: string): EventQueue {
+    const normalized = host.replace(/\/$/, "");
+    const key = queueKey(normalized, apiKey);
+    let queue = queuesByHost.get(key);
+    if (!queue) {
+        queue = new EventQueue(normalized, apiKey);
+        queuesByHost.set(key, queue);
+    }
+    installLifecycleListeners();
+    return queue;
+}
+
+export function flushEventQueue(host: string, forceBeacon = false, apiKey?: string): void {
+    const queue = queuesByHost.get(queueKey(host, apiKey));
+    if (!queue) return;
+    queue.flush(forceBeacon);
+}
+
+export function flushAllEventQueues(forceBeacon = false): void {
+    for (const queue of queuesByHost.values()) {
+        queue.flush(forceBeacon);
+    }
+}
+
+export function resetEventQueuesForTests(): void {
+    queuesByHost.clear();
+}