@probat/react 0.4.5 → 0.4.7

package/src/__tests__/utils.test.ts

@@ -1,6 +1,12 @@
 import { describe, it, expect, beforeEach } from "vitest";
 import { makeDedupeKey, hasSeen, markSeen, resetDedupe } from "../utils/dedupeStorage";
-import { getDistinctId, getSessionId, buildEventContext } from "../utils/eventContext";
+import {
+    getDistinctId,
+    getSessionId,
+    getSessionStartAt,
+    buildEventContext,
+    resetEventContextStateForTests,
+} from "../utils/eventContext";
 
 // ── dedupeStorage ──────────────────────────────────────────────────────────
 
@@ -50,6 +56,7 @@ describe("eventContext", () => {
     beforeEach(() => {
         localStorage.clear();
         sessionStorage.clear();
+        resetEventContextStateForTests();
     });
 
     it("getDistinctId returns a stable id", () => {
@@ -68,6 +75,13 @@ describe("eventContext", () => {
         expect(id1).toMatch(/^sess_|^server$/);
     });
 
+    it("getSessionStartAt returns a stable timestamp within session", () => {
+        const s1 = getSessionStartAt();
+        const s2 = getSessionStartAt();
+        expect(s1).toBe(s2);
+        expect(new Date(s1).toString()).not.toBe("Invalid Date");
+    });
+
     it("buildEventContext includes all required fields", () => {
         const ctx = buildEventContext();
         expect(ctx).toHaveProperty("distinct_id");
@@ -75,5 +89,14 @@ describe("eventContext", () => {
         expect(ctx).toHaveProperty("$page_url");
         expect(ctx).toHaveProperty("$pathname");
         expect(ctx).toHaveProperty("$referrer");
+        expect(ctx).toHaveProperty("$session_sequence");
+        expect(ctx).toHaveProperty("$session_start_at");
+    });
+
+    it("increments $session_sequence monotonically", () => {
+        const c1 = buildEventContext();
+        const c2 = buildEventContext();
+        expect(c2.$session_sequence).toBe(c1.$session_sequence + 1);
+        expect(c2.$session_start_at).toBe(c1.$session_start_at);
     });
 });

package/src/context/ProbatContext.tsx

@@ -1,6 +1,7 @@
 "use client";
 
-import React, { createContext, useContext, useMemo } from "react";
+import React, { createContext, useContext, useEffect, useMemo } from "react";
+import { flushMetrics, sendMetric } from "../utils/api";
 
 export interface ProbatContextValue {
     host: string;
@@ -17,9 +18,9 @@ export interface ProbatProviderProps {
     /** Your end-user's ID. When provided, used as the distinct_id for variant
      *  assignment (consistent across devices) and attached to all events. */
     customerId?: string;
-    /** Base URL for the Probat API. Defaults to https://gushi.onrender.com */
+    /** Base URL for the Probat API. Defaults to https://api.probat.app */
     host?: string;
-    /** API key for authenticating SDK requests (probat_sk_...) */
+    /** Publishable API key for authenticating SDK requests (probat_pk_...) */
     apiKey?: string;
     /**
      * Bootstrap assignments to avoid flash on first render.
@@ -27,6 +28,8 @@ export interface ProbatProviderProps {
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
+    /** Automatically send $session_start/$session_end lifecycle events. */
+    trackSessionLifecycle?: boolean;
     children: React.ReactNode;
 }
 
@@ -35,16 +38,35 @@ export function ProbatProvider({
     host = DEFAULT_HOST,
     apiKey,
     bootstrap,
+    trackSessionLifecycle = true,
     children,
 }: ProbatProviderProps) {
+    const normalizedHost = host.replace(/\/$/, "");
+
+    useEffect(() => {
+        if (!trackSessionLifecycle) return;
+        if (typeof window === "undefined") return;
+
+        sendMetric(normalizedHost, "$session_start", {
+            ...(customerId ? { distinct_id: customerId } : {}),
+        }, apiKey);
+
+        return () => {
+            sendMetric(normalizedHost, "$session_end", {
+                ...(customerId ? { distinct_id: customerId } : {}),
+            }, apiKey);
+            flushMetrics(normalizedHost, true, apiKey);
+        };
+    }, [normalizedHost, customerId, trackSessionLifecycle, apiKey]);
+
     const value = useMemo<ProbatContextValue>(
         () => ({
-            host: host.replace(/\/$/, ""),
+            host: normalizedHost,
             apiKey,
             customerId,
             bootstrap: bootstrap ?? {},
         }),
-        [customerId, host, apiKey, bootstrap]
+        [customerId, normalizedHost, apiKey, bootstrap]
     );
 
     return (

package/src/hooks/useExperiment.ts

@@ -52,11 +52,28 @@ export interface UseExperimentReturn {
 
 // ── Hook ───────────────────────────────────────────────────────────────────
 
+/**
+ * Reads the __probat_force query param for a specific experiment ID.
+ * Format: ?__probat_force=<experimentId>:<variantKey>
+ * Used in preview sandboxes to pin a specific variant without an API call.
+ */
+function readForceParam(id: string): string | null {
+    if (typeof window === "undefined") return null;
+    try {
+        const raw = new URLSearchParams(window.location.search).get("__probat_force");
+        if (!raw) return null;
+        const [forceId, forceKey] = raw.split(":");
+        return forceId === id ? (forceKey ?? null) : null;
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Resolves the variant assignment for an experiment.
  * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
  *
- * Priority: bootstrap > localStorage cache > fetchDecision.
+ * Priority: __probat_force URL param > bootstrap > localStorage cache > fetchDecision.
  */
 export function useExperiment(
     id: string,
@@ -66,14 +83,23 @@ export function useExperiment(
     const { host, bootstrap, customerId, apiKey } = useProbatContext();
 
     const [variantKey, setVariantKey] = useState<string>(() => {
+        const forced = readForceParam(id);
+        if (forced) return forced;
         if (bootstrap[id]) return bootstrap[id];
         return "control";
     });
     const [resolved, setResolved] = useState<boolean>(() => {
-        return !!bootstrap[id];
+        return !!(readForceParam(id) || bootstrap[id]);
     });
 
     useEffect(() => {
+        const forced = readForceParam(id);
+        if (forced) {
+            setVariantKey(forced);
+            setResolved(true);
+            return;
+        }
+
         if (bootstrap[id] || readAssignment(id)) {
             const key = bootstrap[id] ?? readAssignment(id) ?? "control";
             setVariantKey(key);

package/src/hooks/useProbatMetrics.ts

@@ -3,6 +3,7 @@
 import { useCallback } from "react";
 import { useProbatContext } from "../context/ProbatContext";
 import { sendMetric } from "../utils/api";
+import type { ProbatEventType } from "../types/events";
 
 export interface UseProbatMetricsReturn {
     /**
@@ -15,7 +16,16 @@ export interface UseProbatMetricsReturn {
      * capture("purchase", { revenue: 42, currency: "USD" });
      * ```
      */
-    capture: (event: string, properties?: Record<string, unknown>) => void;
+    capture: (event: ProbatEventType, properties?: Record<string, unknown>) => void;
+    captureGoal: (
+        funnelId: string,
+        funnelStep: number,
+        properties?: Record<string, unknown>,
+    ) => void;
+    captureFeatureInteraction: (
+        interactionName: string,
+        properties?: Record<string, unknown>,
+    ) => void;
 }
 
 /**
@@ -26,7 +36,7 @@ export function useProbatMetrics(): UseProbatMetricsReturn {
     const { host, customerId, apiKey } = useProbatContext();
 
     const capture = useCallback(
-        (event: string, properties: Record<string, unknown> = {}) => {
+        (event: ProbatEventType, properties: Record<string, unknown> = {}) => {
             sendMetric(host, event, {
                 ...(customerId ? { distinct_id: customerId } : {}),
                 ...properties,
@@ -35,5 +45,39 @@ export function useProbatMetrics(): UseProbatMetricsReturn {
         [host, customerId, apiKey]
     );
 
-    return { capture };
+    const captureGoal = useCallback(
+        (
+            funnelId: string,
+            funnelStep: number,
+            properties: Record<string, unknown> = {},
+        ) => {
+            sendMetric(host, "$goal_reached", {
+                ...(customerId ? { distinct_id: customerId } : {}),
+                $funnel_id: funnelId,
+                $funnel_step: funnelStep,
+                ...properties,
+            });
+        },
+        [host, customerId],
+    );
+
+    const captureFeatureInteraction = useCallback(
+        (
+            interactionName: string,
+            properties: Record<string, unknown> = {},
+        ) => {
+            sendMetric(host, "$feature_interaction", {
+                ...(customerId ? { distinct_id: customerId } : {}),
+                interaction_name: interactionName,
+                ...properties,
+            });
+        },
+        [host, customerId],
+    );
+
+    return {
+        capture,
+        captureGoal,
+        captureFeatureInteraction,
+    };
 }

package/src/index.ts

@@ -19,8 +19,18 @@ export { useTrack } from "./hooks/useTrack";
 export type { UseTrackOptions, UseTrackExplicitOptions, UseTrackCustomerOptions } from "./hooks/useTrack";
 export { useProbatMetrics } from "./hooks/useProbatMetrics";
 export type { UseProbatMetricsReturn } from "./hooks/useProbatMetrics";
+export {
+    PROBAT_ENV_DEV,
+    PROBAT_ENV_PROD,
+} from "./types/events";
+export type {
+    ProbatEnvironment,
+    ProbatEventType,
+    StructuredEvent,
+    StructuredEventProperties,
+} from "./types/events";
 
 // ── Utilities (advanced) ───────────────────────────────────────────────────
-export { sendMetric, fetchDecision } from "./utils/api";
+export { sendMetric, fetchDecision, flushMetrics } from "./utils/api";
 export type { MetricPayload, DecisionResponse } from "./utils/api";
 export { createExperimentContext } from "./utils/createExperimentContext";

package/src/types/events.ts

@@ -0,0 +1,48 @@
+export const PROBAT_ENV_DEV = "dev" as const;
+export const PROBAT_ENV_PROD = "prod" as const;
+export type ProbatEnvironment = typeof PROBAT_ENV_DEV | typeof PROBAT_ENV_PROD;
+
+export type ProbatEventType =
+    | "$experiment_exposure"
+    | "$experiment_click"
+    | "$pageview"
+    | "$pageleave"
+    | "$session_start"
+    | "$session_end"
+    | "$goal_reached"
+    | "$feature_interaction"
+    | string;
+
+export interface StructuredEventProperties {
+    // Always present (auto-injected by SDK)
+    distinct_id: string;
+    session_id: string;
+    $page_url: string;
+    $pathname: string;
+    $referrer: string;
+    captured_at: string;
+    environment: ProbatEnvironment;
+    source: "react-sdk" | "react-native-sdk";
+
+    // Session context
+    $session_sequence: number;
+    $session_start_at: string;
+
+    // Optional context
+    experiment_id?: string;
+    variant_key?: string;
+    component_instance_id?: string;
+
+    // Funnel context
+    $funnel_id?: string;
+    $funnel_step?: number;
+
+    // Custom
+    [key: string]: unknown;
+}
+
+export interface StructuredEvent {
+    event: ProbatEventType;
+    environment: ProbatEnvironment;
+    properties: StructuredEventProperties;
+}

package/src/utils/api.ts

@@ -1,5 +1,12 @@
 import { detectEnvironment } from "./environment";
 import { buildEventContext } from "./eventContext";
+import { getEventQueue, flushEventQueue } from "./eventQueue";
+import type {
+    ProbatEnvironment,
+    ProbatEventType,
+    StructuredEvent,
+    StructuredEventProperties,
+} from "../types/events";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -8,9 +15,9 @@ export interface DecisionResponse {
 }
 
 export interface MetricPayload {
-    event: string;
-    environment: "dev" | "prod";
-    properties: Record<string, unknown>;
+    event: ProbatEventType;
+    environment: ProbatEnvironment;
+    properties: StructuredEventProperties;
 }
 
 // ── Assignment fetching ────────────────────────────────────────────────────
@@ -67,39 +74,44 @@ export async function fetchDecision(
  */
 export function sendMetric(
     host: string,
-    event: string,
+    event: ProbatEventType,
     properties: Record<string, unknown>,
     apiKey?: string
 ): void {
     if (typeof window === "undefined") return;
 
+    const environment = detectEnvironment();
     const ctx = buildEventContext();
     const payload: MetricPayload = {
         event,
-        environment: detectEnvironment(),
+        environment,
         properties: {
             ...ctx,
+            environment,
             source: "react-sdk",
             captured_at: new Date().toISOString(),
             ...properties,
-        },
+        } as StructuredEventProperties,
     };
 
-    try {
-        const url = `${host.replace(/\/$/, "")}/experiment/metrics`;
-        const headers: Record<string, string> = { "Content-Type": "application/json" };
-        if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
-        fetch(url, {
-            method: "POST",
-            headers,
-            credentials: "include",
-            body: JSON.stringify(payload),
-        }).catch(() => {});
-    } catch {
-        // silently drop
+    const queuePayload: StructuredEvent = {
+        event: payload.event,
+        environment: payload.environment,
+        properties: payload.properties,
+    };
+    const queue = getEventQueue(host, apiKey);
+    queue.enqueue(queuePayload);
+
+    // Preserve immediate delivery semantics for core experiment events.
+    if (event === "$experiment_exposure" || event === "$experiment_click") {
+        queue.flush(false);
     }
 }
 
+export function flushMetrics(host: string, forceBeacon = false, apiKey?: string): void {
+    flushEventQueue(host, forceBeacon, apiKey);
+}
+
 // ── Click metadata extraction ──────────────────────────────────────────────
 
 export interface ClickMeta {

package/src/utils/environment.ts

@@ -1,10 +1,12 @@
+import { PROBAT_ENV_DEV, PROBAT_ENV_PROD, type ProbatEnvironment } from "../types/events";
+
 /**
  * Detect if the code is running on localhost (development environment).
  * Returns "dev" for localhost, "prod" for production.
  */
-export function detectEnvironment(): "dev" | "prod" {
+export function detectEnvironment(): ProbatEnvironment {
     if (typeof window === "undefined") {
-        return "prod"; // Server-side, default to prod
+        return PROBAT_ENV_PROD; // Server-side, default to prod
     }
 
     const hostname = window.location.hostname;
@@ -33,9 +35,8 @@ export function detectEnvironment(): "dev" | "prod" {
         hostname.startsWith("172.30.") ||
         hostname.startsWith("172.31.")
     ) {
-        return "dev";
+        return PROBAT_ENV_DEV;
     }
 
-    return "prod";
+    return PROBAT_ENV_PROD;
 }
-

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;
+}