@probat/react 0.2.1 → 0.3.1

package/src/__tests__/setup.ts

@@ -0,0 +1,63 @@
+import "@testing-library/jest-dom/vitest";
+
+// Mock IntersectionObserver
+class MockIntersectionObserver implements IntersectionObserver {
+    readonly root: Element | null = null;
+    readonly rootMargin: string = "";
+    readonly thresholds: ReadonlyArray<number> = [];
+
+    private callback: IntersectionObserverCallback;
+    private elements: Set<Element> = new Set();
+
+    constructor(callback: IntersectionObserverCallback, _options?: IntersectionObserverInit) {
+        this.callback = callback;
+        MockIntersectionObserver._instances.push(this);
+    }
+
+    observe(el: Element) {
+        this.elements.add(el);
+    }
+
+    unobserve(el: Element) {
+        this.elements.delete(el);
+    }
+
+    disconnect() {
+        this.elements.clear();
+    }
+
+    takeRecords(): IntersectionObserverEntry[] {
+        return [];
+    }
+
+    // Test helpers
+    static _instances: MockIntersectionObserver[] = [];
+
+    static _reset() {
+        MockIntersectionObserver._instances = [];
+    }
+
+    _trigger(isIntersecting: boolean) {
+        const entries: IntersectionObserverEntry[] = Array.from(this.elements).map(
+            (el) =>
+                ({
+                    target: el,
+                    isIntersecting,
+                    intersectionRatio: isIntersecting ? 0.6 : 0,
+                    boundingClientRect: {} as DOMRectReadOnly,
+                    intersectionRect: {} as DOMRectReadOnly,
+                    rootBounds: null,
+                    time: Date.now(),
+                }) as IntersectionObserverEntry
+        );
+        this.callback(entries, this);
+    }
+}
+
+Object.defineProperty(globalThis, "IntersectionObserver", {
+    value: MockIntersectionObserver,
+    writable: true,
+});
+
+// Export for test use
+export { MockIntersectionObserver };

package/src/__tests__/utils.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { makeDedupeKey, hasSeen, markSeen, resetDedupe } from "../utils/dedupeStorage";
+import { getDistinctId, getSessionId, buildEventContext } from "../utils/eventContext";
+
+// ── dedupeStorage ──────────────────────────────────────────────────────────
+
+describe("dedupeStorage", () => {
+    beforeEach(() => {
+        sessionStorage.clear();
+        resetDedupe();
+    });
+
+    it("makeDedupeKey produces correct format", () => {
+        const key = makeDedupeKey("exp1", "ai_v1", "inst_1", "/pricing?plan=pro");
+        expect(key).toBe("probat:seen:exp1:ai_v1:inst_1:/pricing?plan=pro");
+    });
+
+    it("hasSeen returns false for unseen keys", () => {
+        expect(hasSeen("probat:seen:new:key:a:b")).toBe(false);
+    });
+
+    it("markSeen + hasSeen round-trips", () => {
+        const key = makeDedupeKey("exp1", "control", "inst_1", "/");
+        expect(hasSeen(key)).toBe(false);
+        markSeen(key);
+        expect(hasSeen(key)).toBe(true);
+    });
+
+    it("resetDedupe clears in-memory set", () => {
+        const key = makeDedupeKey("exp1", "control", "inst_1", "/");
+        markSeen(key);
+        expect(hasSeen(key)).toBe(true);
+        resetDedupe();
+        // sessionStorage still has it, so it should still be seen
+        expect(hasSeen(key)).toBe(true);
+    });
+
+    it("resetDedupe + clear sessionStorage fully resets", () => {
+        const key = makeDedupeKey("exp1", "control", "inst_1", "/");
+        markSeen(key);
+        resetDedupe();
+        sessionStorage.clear();
+        expect(hasSeen(key)).toBe(false);
+    });
+});
+
+// ── eventContext ────────────────────────────────────────────────────────────
+
+describe("eventContext", () => {
+    beforeEach(() => {
+        localStorage.clear();
+        sessionStorage.clear();
+    });
+
+    it("getDistinctId returns a stable id", () => {
+        // Clear the module-level cache by removing from storage and re-importing
+        // Since the module caches in a variable, we just check consistency
+        const id1 = getDistinctId();
+        const id2 = getDistinctId();
+        expect(id1).toBe(id2);
+        expect(id1).toMatch(/^anon_|^server$/);
+    });
+
+    it("getSessionId returns a stable id within session", () => {
+        const id1 = getSessionId();
+        const id2 = getSessionId();
+        expect(id1).toBe(id2);
+        expect(id1).toMatch(/^sess_|^server$/);
+    });
+
+    it("buildEventContext includes all required fields", () => {
+        const ctx = buildEventContext();
+        expect(ctx).toHaveProperty("distinct_id");
+        expect(ctx).toHaveProperty("session_id");
+        expect(ctx).toHaveProperty("$page_url");
+        expect(ctx).toHaveProperty("$pathname");
+        expect(ctx).toHaveProperty("$referrer");
+    });
+});

package/src/components/Experiment.tsx

@@ -0,0 +1,291 @@
+"use client";
+
+import React, {
+    useEffect,
+    useRef,
+    useState,
+    useCallback,
+    useMemo,
+} from "react";
+import { useProbatContext } from "../context/ProbatContext";
+import { fetchDecision, sendMetric, extractClickMeta } from "../utils/api";
+import { getDistinctId, getPageKey } from "../utils/eventContext";
+import { makeDedupeKey, hasSeen, markSeen } from "../utils/dedupeStorage";
+import { useStableInstanceId } from "../utils/stableInstanceId";
+
+// ── localStorage assignment cache ──────────────────────────────────────────
+
+const ASSIGNMENT_PREFIX = "probat:assignment:";
+
+interface StoredAssignment {
+    variantKey: string;
+    ts: number;
+}
+
+function readAssignment(id: string): string | null {
+    if (typeof window === "undefined") return null;
+    try {
+        const raw = localStorage.getItem(ASSIGNMENT_PREFIX + id);
+        if (!raw) return null;
+        const parsed: StoredAssignment = JSON.parse(raw);
+        return parsed.variantKey ?? null;
+    } catch {
+        return null;
+    }
+}
+
+function writeAssignment(id: string, variantKey: string): void {
+    if (typeof window === "undefined") return;
+    try {
+        const entry: StoredAssignment = { variantKey, ts: Date.now() };
+        localStorage.setItem(ASSIGNMENT_PREFIX + id, JSON.stringify(entry));
+    } catch {}
+}
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface ExperimentTrackOptions {
+    /** Auto-track impressions (default true) */
+    impression?: boolean;
+    /** Auto-track clicks (default true) */
+    primaryClick?: boolean;
+    /** Custom impression event name (default "$experiment_exposure") */
+    impressionEventName?: string;
+    /** Custom click event name (default "$experiment_click") */
+    clickEventName?: string;
+}
+
+export interface ExperimentProps {
+    /** Experiment key / identifier */
+    id: string;
+    /** Control variant ReactNode */
+    control: React.ReactNode;
+    /** Named variant ReactNodes, keyed by variant key (e.g. { ai_v1: <MyVariant /> }) */
+    variants: Record<string, React.ReactNode>;
+    /** Tracking configuration */
+    track?: ExperimentTrackOptions;
+    /** Stable instance id when multiple instances of the same experiment exist on a page */
+    componentInstanceId?: string;
+    /** Behavior when assignment fetch fails: "control" (default) renders control, "suspend" throws */
+    fallback?: "control" | "suspend";
+    /** Log decisions + events to console */
+    debug?: boolean;
+}
+
+export function Experiment({
+    id,
+    control,
+    variants,
+    track,
+    componentInstanceId,
+    fallback = "control",
+    debug = false,
+}: ExperimentProps) {
+    const { host, bootstrap } = useProbatContext();
+
+    // Stable instance id (useId + sessionStorage for cross-mount stability)
+    const autoInstanceId = useStableInstanceId(id);
+    const instanceId = componentInstanceId ?? autoInstanceId;
+
+    // Track options with defaults
+    const trackImpression = track?.impression !== false;
+    const trackClick = track?.primaryClick !== false;
+    const impressionEvent = track?.impressionEventName ?? "$experiment_exposure";
+    const clickEvent = track?.clickEventName ?? "$experiment_click";
+
+    // ── Assignment resolution ──────────────────────────────────────────────
+
+    const [variantKey, setVariantKey] = useState<string>(() => {
+        // Sync resolution order: bootstrap → localStorage → "control"
+        if (bootstrap[id]) return bootstrap[id];
+        const cached = readAssignment(id);
+        if (cached) return cached;
+        return "control";
+    });
+    const [resolved, setResolved] = useState<boolean>(() => {
+        return !!(bootstrap[id] || readAssignment(id));
+    });
+
+    useEffect(() => {
+        // Already resolved from bootstrap or cache
+        if (bootstrap[id] || readAssignment(id)) {
+            // Ensure state is synced (StrictMode may re-mount)
+            const key = bootstrap[id] ?? readAssignment(id) ?? "control";
+            setVariantKey(key);
+            setResolved(true);
+            return;
+        }
+
+        let cancelled = false;
+
+        (async () => {
+            try {
+                const distinctId = getDistinctId();
+                const key = await fetchDecision(host, id, distinctId);
+                if (cancelled) return;
+
+                // Validate variant key
+                if (key !== "control" && !(key in variants)) {
+                    if (debug) {
+                        console.warn(
+                            `[probat] Unknown variant "${key}" for experiment "${id}", falling back to control`
+                        );
+                    }
+                    setVariantKey("control");
+                } else {
+                    setVariantKey(key);
+                    writeAssignment(id, key);
+                }
+            } catch (err) {
+                if (cancelled) return;
+                if (debug) {
+                    console.error(`[probat] fetchDecision failed for "${id}":`, err);
+                }
+                if (fallback === "suspend") throw err;
+                setVariantKey("control");
+            } finally {
+                if (!cancelled) setResolved(true);
+            }
+        })();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [id, host]); // eslint-disable-line react-hooks/exhaustive-deps
+
+    // ── Debug logging ──────────────────────────────────────────────────────
+
+    useEffect(() => {
+        if (debug && resolved) {
+            console.log(`[probat] Experiment "${id}" → variant "${variantKey}"`, {
+                instanceId,
+                pageKey: getPageKey(),
+            });
+        }
+    }, [debug, id, variantKey, resolved, instanceId]);
+
+    // ── Shared event properties ────────────────────────────────────────────
+
+    const eventProps = useMemo(
+        () => ({
+            experiment_id: id,
+            variant_key: variantKey,
+            component_instance_id: instanceId,
+        }),
+        [id, variantKey, instanceId]
+    );
+
+    // ── Impression tracking via IntersectionObserver ────────────────────────
+
+    const containerRef = useRef<HTMLDivElement>(null);
+    const impressionSent = useRef(false);
+
+    useEffect(() => {
+        if (!trackImpression || !resolved) return;
+
+        // Reset on re-mount (StrictMode safety)
+        impressionSent.current = false;
+
+        const pageKey = getPageKey();
+        const dedupeKey = makeDedupeKey(id, variantKey, instanceId, pageKey);
+
+        // Already seen this session
+        if (hasSeen(dedupeKey)) {
+            impressionSent.current = true;
+            return;
+        }
+
+        const el = containerRef.current;
+        if (!el) return;
+
+        // Fallback: no IntersectionObserver (SSR, old browser)
+        if (typeof IntersectionObserver === "undefined") {
+            if (!impressionSent.current) {
+                impressionSent.current = true;
+                markSeen(dedupeKey);
+                sendMetric(host, impressionEvent, eventProps);
+                if (debug) console.log(`[probat] Impression sent (no IO) for "${id}"`);
+            }
+            return;
+        }
+
+        let timer: ReturnType<typeof setTimeout> | null = null;
+
+        const observer = new IntersectionObserver(
+            ([entry]) => {
+                if (!entry || impressionSent.current) return;
+
+                if (entry.isIntersecting) {
+                    timer = setTimeout(() => {
+                        if (impressionSent.current) return;
+                        impressionSent.current = true;
+                        markSeen(dedupeKey);
+                        sendMetric(host, impressionEvent, eventProps);
+                        if (debug) console.log(`[probat] Impression sent for "${id}"`);
+                        observer.disconnect();
+                    }, 250);
+                } else if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            },
+            { threshold: 0.5 }
+        );
+
+        observer.observe(el);
+
+        return () => {
+            observer.disconnect();
+            if (timer) clearTimeout(timer);
+        };
+    }, [
+        trackImpression,
+        resolved,
+        id,
+        variantKey,
+        instanceId,
+        host,
+        impressionEvent,
+        eventProps,
+        debug,
+    ]);
+
+    // ── Click tracking ─────────────────────────────────────────────────────
+
+    const handleClick = useCallback(
+        (e: React.MouseEvent) => {
+            if (!trackClick) return;
+
+            const meta = extractClickMeta(e.target as EventTarget);
+            if (!meta) return;
+
+            sendMetric(host, clickEvent, {
+                ...eventProps,
+                ...meta,
+            });
+            if (debug) {
+                console.log(`[probat] Click tracked for "${id}"`, meta);
+            }
+        },
+        [trackClick, host, clickEvent, eventProps, id, debug]
+    );
+
+    // ── Render ─────────────────────────────────────────────────────────────
+
+    const content =
+        variantKey === "control" || !(variantKey in variants)
+            ? control
+            : variants[variantKey];
+
+    return (
+        <div
+            ref={containerRef}
+            onClick={handleClick}
+            data-probat-experiment={id}
+            data-probat-variant={variantKey}
+            style={{ display: "block", margin: 0, padding: 0 }}
+        >
+            {content}
+        </div>
+    );
+}

package/src/components/ProbatProviderClient.tsx

@@ -1,18 +1,30 @@
 "use client";
 
 import React from "react";
-import { ProbatProvider as BaseProbatProvider } from "../context/ProbatContext";
+import { ProbatProvider } from "../context/ProbatContext";
 import type { ProbatProviderProps } from "../context/ProbatContext";
 
 /**
- * ProbatProviderClient - Can be imported directly in Next.js Server Components
- * This is a re-export with "use client" directive to ensure it works in Server Components
+ * Client-only provider for Next.js App Router.
+ * Import this in your layout/providers file.
+ *
+ * @example
+ * ```tsx
+ * // app/providers.tsx
+ * "use client";
+ * import { ProbatProviderClient } from "@probat/react";
+ *
+ * export function Providers({ children }) {
+ *   return (
+ *     <ProbatProviderClient userId="your-user-uuid">
+ *       {children}
+ *     </ProbatProviderClient>
+ *   );
+ * }
+ * ```
  */
 export function ProbatProviderClient(props: ProbatProviderProps) {
-    return React.createElement(BaseProbatProvider, props);
+    return React.createElement(ProbatProvider, props);
 }
 
-// Also export as ProbatProvider for convenience
-export { ProbatProviderClient as ProbatProvider };
 export type { ProbatProviderProps };
-

package/src/context/ProbatContext.tsx

@@ -1,181 +1,59 @@
 "use client";
 
-import React, { createContext, useContext, useMemo, useEffect } from "react";
-import { detectEnvironment } from "../utils/environment";
-import { initHeatmapTracking, stopHeatmapTracking } from "../utils/heatmapTracker";
-
-declare global {
-    interface Window {
-        __PROBAT_API?: string;
-    }
-}
+import React, { createContext, useContext, useMemo } from "react";
 
 export interface ProbatContextValue {
-    apiBaseUrl: string;
-    environment: "dev" | "prod";
-    clientKey?: string;
-    repoFullName?: string; // Repository full name (e.g., "owner/repo") for component-based experiments
-    proposalId?: string;
-    variantLabel?: string;
+    host: string;
+    userId: string;
+    bootstrap: Record<string, string>;
 }
 
 const ProbatContext = createContext<ProbatContextValue | null>(null);
 
+const DEFAULT_HOST = "https://gushi.onrender.com";
+
 export interface ProbatProviderProps {
+    /** Gushi user ID (UUID) — used to scope SDK requests to a customer */
+    userId: string;
+    /** Base URL for the Probat API. Defaults to https://gushi.onrender.com */
+    host?: string;
     /**
-     * The base URL for the Probat API.
-     * If not provided, will try to read from:
-     * - VITE_PROBAT_API (Vite)
-     * - NEXT_PUBLIC_PROBAT_API (Next.js)
-     * - window.__PROBAT_API
-     * - Default: "https://gushi.onrender.com"
-     */
-    apiBaseUrl?: string;
-    /**
-     * Optional: proposal/experiment id for heatmap segregation
-     */
-    proposalId?: string;
-    /**
-     * Optional: variant label for heatmap segregation
-     */
-    variantLabel?: string;
-    /**
-     * Client key for identification (optional)
-     */
-    clientKey?: string;
-    /**
-     * Explicitly set environment. If not provided, will auto-detect based on hostname.
-     * "dev" for localhost, "prod" for production.
-     */
-    environment?: "dev" | "prod";
-    /**
-     * Repository full name (e.g., "owner/repo") for component-based experiments.
-     * If not provided, will try to read from:
-     * - NEXT_PUBLIC_PROBAT_REPO (Next.js)
-     * - VITE_PROBAT_REPO (Vite)
-     * - window.__PROBAT_REPO
+     * Bootstrap assignments to avoid flash on first render.
+     * Map of experiment id → variant key.
+     * e.g. { "cta-copy-test": "ai_v1" }
      */
-    repoFullName?: string;
+    bootstrap?: Record<string, string>;
     children: React.ReactNode;
 }
 
 export function ProbatProvider({
-    apiBaseUrl,
-    clientKey,
-    environment: explicitEnvironment,
-    repoFullName: explicitRepoFullName,
-    proposalId,
-    variantLabel,
+    userId,
+    host = DEFAULT_HOST,
+    bootstrap,
     children,
 }: ProbatProviderProps) {
-    // Fallback to localStorage for experiment info if props are not provided
-    const storedProposalId =
-        typeof window !== "undefined"
-            ? window.localStorage.getItem("probat_active_proposal_id") || undefined
-            : undefined;
-    const storedVariantLabel =
-        typeof window !== "undefined"
-            ? window.localStorage.getItem("probat_active_variant_label") || undefined
-            : undefined;
-
-    const contextValue = useMemo<ProbatContextValue>(() => {
-        // Determine API base URL
-        const resolvedApiBaseUrl =
-            apiBaseUrl ||
-            (typeof import.meta !== "undefined" &&
-                (import.meta as any).env?.VITE_PROBAT_API) ||
-            (typeof globalThis !== "undefined" &&
-                (globalThis as any).process?.env?.NEXT_PUBLIC_PROBAT_API) ||
-            (typeof window !== "undefined" && window.__PROBAT_API) ||
-            "https://gushi.onrender.com";
-
-        // Determine environment
-        const environment = explicitEnvironment || detectEnvironment();
-
-        // Determine repo full name
-        const resolvedRepoFullName =
-            explicitRepoFullName ||
-            (typeof globalThis !== "undefined" &&
-                (globalThis as any).process?.env?.NEXT_PUBLIC_PROBAT_REPO) ||
-            (typeof import.meta !== "undefined" &&
-                (import.meta as any).env?.VITE_PROBAT_REPO) ||
-            (typeof window !== "undefined" && (window as any).__PROBAT_REPO) ||
-            undefined;
-
-        // Check for URL overrides (used for Live Heatmap visualization)
-        const params = (typeof window !== "undefined") ? new URLSearchParams(window.location.search) : null;
-        const isHeatmapMode = params?.get('heatmap') === 'true';
-
-        let urlProposalId: string | undefined;
-        let urlVariantLabel: string | undefined;
-
-        if (isHeatmapMode && params) {
-            urlProposalId = params.get('proposal_id') || undefined;
-            urlVariantLabel = params.get('variant_label') || undefined;
-            console.log('[PROBAT] Heatmap mode: Overriding variant from URL', { urlProposalId, urlVariantLabel });
-        }
-
-        // Priority Logic:
-        // 1. URL params (if in heatmap mode)
-        // 2. Explicit props passed to Provider
-        // 3. Stored values in localStorage (ONLY if NOT in heatmap mode)
-        const finalProposalId = urlProposalId || proposalId || (!isHeatmapMode ? storedProposalId : undefined);
-        const finalVariantLabel = urlVariantLabel || variantLabel || (!isHeatmapMode ? storedVariantLabel : undefined);
-
-        return {
-            apiBaseUrl: resolvedApiBaseUrl,
-            environment,
-            clientKey,
-            repoFullName: resolvedRepoFullName,
-            proposalId: finalProposalId,
-            variantLabel: finalVariantLabel,
-        };
-    }, [apiBaseUrl, clientKey, explicitEnvironment, explicitRepoFullName, proposalId, variantLabel, storedProposalId, storedVariantLabel]);
-
-    // Initialize heatmap tracking when provider mounts
-    useEffect(() => {
-        // Only initialize on client-side
-        if (typeof window !== 'undefined') {
-            initHeatmapTracking({
-                apiBaseUrl: contextValue.apiBaseUrl,
-                batchSize: 10,
-                batchInterval: 5000,
-                enabled: true,
-                excludeSelectors: [
-                    '[data-heatmap-exclude]',
-                    'input[type="password"]',
-                    'input[type="email"]',
-                    'textarea',
-                ],
-                // Explicitly enable cursor tracking with sensible defaults
-                trackCursor: true,
-                cursorThrottle: 100,    // capture every 100ms
-                cursorBatchSize: 50,    // send every 50 movements (or after batchInterval)
-                proposalId: contextValue.proposalId,
-                variantLabel: contextValue.variantLabel,
-            });
-        }
-
-        // Cleanup on unmount
-        return () => {
-            stopHeatmapTracking();
-        };
-    }, [contextValue.apiBaseUrl, contextValue.proposalId, contextValue.variantLabel]);
+    const value = useMemo<ProbatContextValue>(
+        () => ({
+            host: host.replace(/\/$/, ""),
+            userId,
+            bootstrap: bootstrap ?? {},
+        }),
+        [userId, host, bootstrap]
+    );
 
     return (
-        <ProbatContext.Provider value={contextValue}>
+        <ProbatContext.Provider value={value}>
             {children}
         </ProbatContext.Provider>
     );
 }
 
 export function useProbatContext(): ProbatContextValue {
-    const context = useContext(ProbatContext);
-    if (!context) {
+    const ctx = useContext(ProbatContext);
+    if (!ctx) {
         throw new Error(
-            "useProbatContext must be used within a ProbatProvider. Please wrap your app with <ProbatProvider>."
+            "useProbatContext must be used within <ProbatProviderClient>. Wrap your app with <ProbatProviderClient userId={...}>."
         );
     }
-    return context;
+    return ctx;
 }
-