@probat/react 0.4.4 → 0.4.6

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/components/Experiment.tsx

@@ -63,7 +63,8 @@ export function Experiment({
         experimentId: id,
         variantKey,
         componentInstanceId,
-        impression: resolved ? (track?.impression !== false) : false,
+        resolved,
+        impression: track?.impression !== false,
         click: track?.primaryClick !== false,
         impressionEventName: track?.impressionEventName,
         clickEventName: track?.clickEventName,

package/src/context/ProbatContext.tsx

@@ -1,45 +1,72 @@
 "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;
+    apiKey?: string;
     customerId?: string;
     bootstrap: Record<string, string>;
 }
 
 const ProbatContext = createContext<ProbatContextValue | null>(null);
 
-const DEFAULT_HOST = "https://gushi.onrender.com";
+const DEFAULT_HOST = "https://api.probat.app";
 
 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;
+    /** Publishable API key for authenticating SDK requests (probat_pk_...) */
+    apiKey?: string;
     /**
      * Bootstrap assignments to avoid flash on first render.
      * Map of experiment id → variant key.
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
+    /** Automatically send $session_start/$session_end lifecycle events. */
+    trackSessionLifecycle?: boolean;
     children: React.ReactNode;
 }
 
 export function ProbatProvider({
     customerId,
     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, bootstrap]
+        [customerId, normalizedHost, apiKey, bootstrap]
     );
 
     return (

package/src/hooks/useExperiment.ts

@@ -52,28 +52,50 @@ export interface UseExperimentReturn {
 
 // ── Hook ───────────────────────────────────────────────────────────────────
 
+/**
+ * Reads the __probat_force query param from the current URL.
+ * Used in preview sandboxes to pin a specific variant without an API call.
+ */
+function readForceParam(): string | null {
+    if (typeof window === "undefined") return null;
+    try {
+        return new URLSearchParams(window.location.search).get("__probat_force");
+    } 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,
     options: UseExperimentOptions = {}
 ): UseExperimentReturn {
     const { fallback = "control", debug = false } = options;
-    const { host, bootstrap, customerId } = useProbatContext();
+    const { host, bootstrap, customerId, apiKey } = useProbatContext();
 
     const [variantKey, setVariantKey] = useState<string>(() => {
+        const forced = readForceParam();
+        if (forced) return forced;
         if (bootstrap[id]) return bootstrap[id];
         return "control";
     });
     const [resolved, setResolved] = useState<boolean>(() => {
-        return !!bootstrap[id];
+        return !!(readForceParam() || bootstrap[id]);
     });
 
     useEffect(() => {
+        const forced = readForceParam();
+        if (forced) {
+            setVariantKey(forced);
+            setResolved(true);
+            return;
+        }
+
         if (bootstrap[id] || readAssignment(id)) {
             const key = bootstrap[id] ?? readAssignment(id) ?? "control";
             setVariantKey(key);
@@ -86,7 +108,7 @@ export function useExperiment(
         (async () => {
             try {
                 const distinctId = customerId ?? getDistinctId();
-                const key = await fetchDecision(host, id, distinctId);
+                const key = await fetchDecision(host, id, distinctId, apiKey);
                 if (cancelled) return;
 
                 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;
 }
 
 /**
@@ -23,17 +33,51 @@ export interface UseProbatMetricsReturn {
  * that sends events to the Probat backend using the provider's host config.
  */
 export function useProbatMetrics(): UseProbatMetricsReturn {
-    const { host, customerId } = useProbatContext();
+    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,
+            }, apiKey);
+        },
+        [host, customerId, apiKey]
+    );
+
+    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]
+        [host, customerId],
     );
 
-    return { capture };
+    return {
+        capture,
+        captureGoal,
+        captureFeatureInteraction,
+    };
 }

package/src/hooks/useTrack.ts

@@ -14,6 +14,8 @@ interface UseTrackBaseOptions {
     experimentId: string;
     /** Stable instance id when multiple instances of the same experiment exist on a page */
     componentInstanceId?: string;
+    /** Whether the variant assignment has been resolved. When false, all tracking is suppressed. */
+    resolved?: boolean;
     /** Auto-track impressions (default true) */
     impression?: boolean;
     /** Auto-track clicks (default true) */
@@ -65,6 +67,7 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
     const {
         experimentId,
         componentInstanceId,
+        resolved = true,
         impression: trackImpression = true,
         click: trackClick = true,
         impressionEventName = "$experiment_exposure",
@@ -75,7 +78,7 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
     const variantKey = options.variantKey ?? undefined;
     const explicitCustomerId = "customerId" in options ? options.customerId : undefined;
 
-    const { host, customerId: providerCustomerId } = useProbatContext();
+    const { host, customerId: providerCustomerId, apiKey } = useProbatContext();
 
     // In customer mode, use explicit customerId or fall back to provider's
     const resolvedCustomerId = explicitCustomerId ?? providerCustomerId;
@@ -113,7 +116,7 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
     const dedupeVariant = variantKey ?? resolvedCustomerId ?? "__anon__";
 
     useEffect(() => {
-        if (!trackImpression) return;
+        if (!trackImpression || !resolved) return;
 
         impressionSent.current = false;
 
@@ -133,7 +136,7 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
             if (!impressionSent.current) {
                 impressionSent.current = true;
                 markSeen(dedupeKey);
-                sendMetric(host, impressionEventName, eventProps);
+                sendMetric(host, impressionEventName, eventProps, apiKey);
                 if (debug) console.log(`[probat] Impression sent (no IO) for "${experimentId}"`);
             }
             return;
@@ -150,7 +153,7 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
                         if (impressionSent.current) return;
                         impressionSent.current = true;
                         markSeen(dedupeKey);
-                        sendMetric(host, impressionEventName, eventProps);
+                        sendMetric(host, impressionEventName, eventProps, apiKey);
                         if (debug) console.log(`[probat] Impression sent for "${experimentId}"`);
                         observer.disconnect();
                     }, 250);
@@ -170,6 +173,7 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
         };
     }, [
         trackImpression,
+        resolved,
         experimentId,
         dedupeVariant,
         instanceId,
@@ -183,7 +187,7 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
 
     const handleClick = useCallback(
         (e: Event) => {
-            if (!trackClick) return;
+            if (!trackClick || !resolved) return;
 
             const meta = extractClickMeta(e.target as EventTarget);
             if (!meta) return;
@@ -191,12 +195,12 @@ export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement
             sendMetric(host, clickEventName, {
                 ...eventProps,
                 ...meta,
-            });
+            }, apiKey);
             if (debug) {
                 console.log(`[probat] Click tracked for "${experimentId}"`, meta);
             }
         },
-        [trackClick, host, clickEventName, eventProps, experimentId, debug]
+        [trackClick, resolved, host, clickEventName, eventProps, experimentId, debug]
     );
 
     useEffect(() => {

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 ────────────────────────────────────────────────────
@@ -25,7 +32,8 @@ const pendingDecisions = new Map<string, Promise<string>>();
 export async function fetchDecision(
     host: string,
     experimentId: string,
-    distinctId: string
+    distinctId: string,
+    apiKey?: string
 ): Promise<string> {
     const existing = pendingDecisions.get(experimentId);
     if (existing) return existing;
@@ -33,12 +41,14 @@ export async function fetchDecision(
     const promise = (async () => {
         try {
             const url = `${host.replace(/\/$/, "")}/experiment/decide`;
+            const headers: Record<string, string> = {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            };
+            if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
             const res = await fetch(url, {
                 method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    Accept: "application/json",
-                },
+                headers,
                 credentials: "include",
                 body: JSON.stringify({
                     experiment_id: experimentId,
@@ -64,36 +74,44 @@ export async function fetchDecision(
  */
 export function sendMetric(
     host: string,
-    event: string,
-    properties: Record<string, unknown>
+    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`;
-        fetch(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            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;
 }
-