@probat/react 0.4.1 → 0.4.3

package/src/components/Experiment.tsx

@@ -1,46 +1,8 @@
 "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 {}
-}
+import React from "react";
+import { useExperiment } from "../hooks/useExperiment";
+import { useTrack } from "../hooks/useTrack";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -81,193 +43,32 @@ export function Experiment({
     fallback = "control",
     debug = false,
 }: ExperimentProps) {
-    const { host, bootstrap, customerId } = 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>(() => {
-        // Defer localStorage read to useEffect to avoid hydration mismatch.
-        if (bootstrap[id]) return bootstrap[id];
-        return "control";
-    });
-    const [resolved, setResolved] = useState<boolean>(() => {
-        return !!bootstrap[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 = customerId ?? 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
+    // ── Assignment (decoupled) ──────────────────────────────────────────────
 
-    // ── Debug logging ──────────────────────────────────────────────────────
+    const { variantKey: rawKey, resolved } = useExperiment(id, { fallback, debug });
 
-    useEffect(() => {
-        if (debug && resolved) {
-            console.log(`[probat] Experiment "${id}" → variant "${variantKey}"`, {
-                instanceId,
-                pageKey: getPageKey(),
-            });
-        }
-    }, [debug, id, variantKey, resolved, instanceId]);
+    // Validate variant key against the ReactNode map
+    const variantKey =
+        rawKey === "control" || rawKey in variants ? rawKey : "control";
 
-    // ── Shared event properties ────────────────────────────────────────────
-
-    const eventProps = useMemo(
-        () => ({
-            experiment_id: id,
-            variant_key: variantKey,
-            component_instance_id: instanceId,
-            ...(customerId ? { distinct_id: customerId } : {}),
-        }),
-        [id, variantKey, instanceId, customerId]
-    );
-
-    // ── 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 }
+    if (debug && rawKey !== variantKey) {
+        console.warn(
+            `[probat] Unknown variant "${rawKey}" for experiment "${id}", falling back to control`
         );
+    }
 
-        observer.observe(el);
+    // ── Tracking (decoupled) ────────────────────────────────────────────────
 
-        return () => {
-            observer.disconnect();
-            if (timer) clearTimeout(timer);
-        };
-    }, [
-        trackImpression,
-        resolved,
-        id,
+    const trackRef = useTrack({
+        experimentId: id,
         variantKey,
-        instanceId,
-        host,
-        impressionEvent,
-        eventProps,
+        componentInstanceId,
+        impression: resolved ? (track?.impression !== false) : false,
+        click: track?.primaryClick !== false,
+        impressionEventName: track?.impressionEventName,
+        clickEventName: track?.clickEventName,
         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 ─────────────────────────────────────────────────────────────
 
@@ -278,8 +79,7 @@ export function Experiment({
 
     return (
         <div
-            ref={containerRef}
-            onClick={handleClick}
+            ref={trackRef as React.RefObject<HTMLDivElement>}
             data-probat-experiment={id}
             data-probat-variant={variantKey}
             style={{

package/src/components/Track.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import React from "react";
+import { useTrack, type UseTrackOptions } from "../hooks/useTrack";
+
+export type TrackProps = UseTrackOptions & {
+    children: React.ReactNode;
+};
+
+/**
+ * Wrapper component that attaches impression and click tracking to its children.
+ * Alternative to the `useTrack` hook when you prefer a component over a ref.
+ *
+ * @example
+ * ```tsx
+ * <Track experimentId="pricing" variantKey="ai_v1">
+ *   <PricingCard />
+ * </Track>
+ * ```
+ */
+export function Track({ children, ...trackOptions }: TrackProps) {
+    const trackRef = useTrack(trackOptions);
+
+    return (
+        <div
+            ref={trackRef as React.RefObject<HTMLDivElement>}
+            data-probat-track={trackOptions.experimentId}
+            data-probat-variant={trackOptions.variantKey ?? "server-resolved"}
+            style={{ display: "contents" }}
+        >
+            {children}
+        </div>
+    );
+}

package/src/hooks/useExperiment.ts

@@ -0,0 +1,118 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useProbatContext } from "../context/ProbatContext";
+import { fetchDecision } from "../utils/api";
+import { getDistinctId } from "../utils/eventContext";
+
+// ── localStorage assignment cache ──────────────────────────────────────────
+
+const ASSIGNMENT_PREFIX = "probat:assignment:";
+
+interface StoredAssignment {
+    variantKey: string;
+    ts: number;
+}
+
+export 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;
+    }
+}
+
+export 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 UseExperimentOptions {
+    /** Behavior when assignment fetch fails: "control" (default) renders control, "suspend" throws */
+    fallback?: "control" | "suspend";
+    /** Log decisions to console */
+    debug?: boolean;
+}
+
+export interface UseExperimentReturn {
+    /** The resolved variant key (e.g. "control", "ai_v1") */
+    variantKey: string;
+    /** Whether the assignment has been resolved (bootstrap, cache, or fetch) */
+    resolved: boolean;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+/**
+ * Resolves the variant assignment for an experiment.
+ * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
+ *
+ * Priority: bootstrap > localStorage cache > fetchDecision.
+ */
+export function useExperiment(
+    id: string,
+    options: UseExperimentOptions = {}
+): UseExperimentReturn {
+    const { fallback = "control", debug = false } = options;
+    const { host, bootstrap, customerId } = useProbatContext();
+
+    const [variantKey, setVariantKey] = useState<string>(() => {
+        if (bootstrap[id]) return bootstrap[id];
+        return "control";
+    });
+    const [resolved, setResolved] = useState<boolean>(() => {
+        return !!bootstrap[id];
+    });
+
+    useEffect(() => {
+        if (bootstrap[id] || readAssignment(id)) {
+            const key = bootstrap[id] ?? readAssignment(id) ?? "control";
+            setVariantKey(key);
+            setResolved(true);
+            return;
+        }
+
+        let cancelled = false;
+
+        (async () => {
+            try {
+                const distinctId = customerId ?? getDistinctId();
+                const key = await fetchDecision(host, id, distinctId);
+                if (cancelled) return;
+
+                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
+
+    useEffect(() => {
+        if (debug && resolved) {
+            console.log(`[probat] Experiment "${id}" -> variant "${variantKey}"`);
+        }
+    }, [debug, id, variantKey, resolved]);
+
+    return { variantKey, resolved };
+}

package/src/hooks/useTrack.ts

@@ -0,0 +1,213 @@
+"use client";
+
+import { useEffect, useRef, useMemo, useCallback } from "react";
+import { useProbatContext } from "../context/ProbatContext";
+import { sendMetric, extractClickMeta } from "../utils/api";
+import { getPageKey } from "../utils/eventContext";
+import { makeDedupeKey, hasSeen, markSeen } from "../utils/dedupeStorage";
+import { useStableInstanceId } from "../utils/stableInstanceId";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface UseTrackBaseOptions {
+    /** Experiment identifier */
+    experimentId: string;
+    /** Stable instance id when multiple instances of the same experiment exist on a page */
+    componentInstanceId?: string;
+    /** Auto-track impressions (default true) */
+    impression?: boolean;
+    /** Auto-track clicks (default true) */
+    click?: boolean;
+    /** Custom impression event name (default "$experiment_exposure") */
+    impressionEventName?: string;
+    /** Custom click event name (default "$experiment_click") */
+    clickEventName?: string;
+    /** Log events to console */
+    debug?: boolean;
+}
+
+/** Explicit mode: pass the variant key directly */
+export interface UseTrackExplicitOptions extends UseTrackBaseOptions {
+    /** The variant key to attach to events */
+    variantKey: string;
+    customerId?: undefined;
+}
+
+/** Customer mode: backend resolves variant from assignment table */
+export interface UseTrackCustomerOptions extends UseTrackBaseOptions {
+    variantKey?: undefined;
+    /** Customer ID to resolve variant server-side. Falls back to provider's customerId. */
+    customerId?: string;
+}
+
+export type UseTrackOptions = UseTrackExplicitOptions | UseTrackCustomerOptions;
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+/**
+ * Attaches impression and click tracking to a DOM element via a ref.
+ *
+ * Two modes:
+ * - **Explicit**: pass `variantKey` directly — stamped on every event.
+ * - **Customer**: omit `variantKey` — backend resolves it from the assignment table
+ *   using `(experimentId, customerId)`.
+ *
+ * @example
+ * ```tsx
+ * // Explicit mode
+ * const trackRef = useTrack({ experimentId: "pricing", variantKey: "ai_v1" });
+ *
+ * // Customer mode (backend resolves variant)
+ * const trackRef = useTrack({ experimentId: "pricing", customerId: "user_123" });
+ * ```
+ */
+export function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement | null> {
+    const {
+        experimentId,
+        componentInstanceId,
+        impression: trackImpression = true,
+        click: trackClick = true,
+        impressionEventName = "$experiment_exposure",
+        clickEventName = "$experiment_click",
+        debug = false,
+    } = options;
+
+    const variantKey = options.variantKey ?? undefined;
+    const explicitCustomerId = "customerId" in options ? options.customerId : undefined;
+
+    const { host, customerId: providerCustomerId } = useProbatContext();
+
+    // In customer mode, use explicit customerId or fall back to provider's
+    const resolvedCustomerId = explicitCustomerId ?? providerCustomerId;
+    const isCustomerMode = !variantKey;
+
+    const autoInstanceId = useStableInstanceId(experimentId);
+    const instanceId = componentInstanceId ?? autoInstanceId;
+
+    const containerRef = useRef<HTMLElement | null>(null);
+    const impressionSent = useRef(false);
+
+    // Runtime warning
+    useEffect(() => {
+        if (isCustomerMode && !resolvedCustomerId && debug) {
+            console.warn(
+                `[probat] useTrack called without variantKey and no customerId ` +
+                `available for "${experimentId}". Events will have no variant attribution.`
+            );
+        }
+    }, [isCustomerMode, resolvedCustomerId, experimentId, debug]);
+
+    const eventProps = useMemo(
+        () => ({
+            experiment_id: experimentId,
+            ...(variantKey ? { variant_key: variantKey } : {}),
+            component_instance_id: instanceId,
+            ...(resolvedCustomerId ? { distinct_id: resolvedCustomerId } : {}),
+        }),
+        [experimentId, variantKey, instanceId, resolvedCustomerId]
+    );
+
+    // ── Impression tracking via IntersectionObserver ────────────────────────
+
+    // In customer mode, use customerId for dedupe instead of variantKey
+    const dedupeVariant = variantKey ?? resolvedCustomerId ?? "__anon__";
+
+    useEffect(() => {
+        if (!trackImpression) return;
+
+        impressionSent.current = false;
+
+        const pageKey = getPageKey();
+        const dedupeKey = makeDedupeKey(experimentId, dedupeVariant, instanceId, pageKey);
+
+        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, impressionEventName, eventProps);
+                if (debug) console.log(`[probat] Impression sent (no IO) for "${experimentId}"`);
+            }
+            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, impressionEventName, eventProps);
+                        if (debug) console.log(`[probat] Impression sent for "${experimentId}"`);
+                        observer.disconnect();
+                    }, 250);
+                } else if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            },
+            { threshold: 0.5 }
+        );
+
+        observer.observe(el);
+
+        return () => {
+            observer.disconnect();
+            if (timer) clearTimeout(timer);
+        };
+    }, [
+        trackImpression,
+        experimentId,
+        dedupeVariant,
+        instanceId,
+        host,
+        impressionEventName,
+        eventProps,
+        debug,
+    ]);
+
+    // ── Click tracking ─────────────────────────────────────────────────────
+
+    const handleClick = useCallback(
+        (e: Event) => {
+            if (!trackClick) return;
+
+            const meta = extractClickMeta(e.target as EventTarget);
+            if (!meta) return;
+
+            sendMetric(host, clickEventName, {
+                ...eventProps,
+                ...meta,
+            });
+            if (debug) {
+                console.log(`[probat] Click tracked for "${experimentId}"`, meta);
+            }
+        },
+        [trackClick, host, clickEventName, eventProps, experimentId, debug]
+    );
+
+    useEffect(() => {
+        const el = containerRef.current;
+        if (!el || !trackClick) return;
+
+        el.addEventListener("click", handleClick);
+        return () => {
+            el.removeEventListener("click", handleClick);
+        };
+    }, [handleClick, trackClick]);
+
+    return containerRef;
+}

package/src/index.ts

@@ -8,10 +8,19 @@ export type { ProbatProviderProps } from "./context/ProbatContext";
 export { Experiment } from "./components/Experiment";
 export type { ExperimentProps, ExperimentTrackOptions } from "./components/Experiment";
 
+// ── Track component ────────────────────────────────────────────────────────
+export { Track } from "./components/Track";
+export type { TrackProps } from "./components/Track";
+
 // ── Hooks ──────────────────────────────────────────────────────────────────
+export { useExperiment } from "./hooks/useExperiment";
+export type { UseExperimentOptions, UseExperimentReturn } from "./hooks/useExperiment";
+export { useTrack } from "./hooks/useTrack";
+export type { UseTrackOptions, UseTrackExplicitOptions, UseTrackCustomerOptions } from "./hooks/useTrack";
 export { useProbatMetrics } from "./hooks/useProbatMetrics";
 export type { UseProbatMetricsReturn } from "./hooks/useProbatMetrics";
 
 // ── Utilities (advanced) ───────────────────────────────────────────────────
 export { sendMetric, fetchDecision } from "./utils/api";
 export type { MetricPayload, DecisionResponse } from "./utils/api";
+export { createExperimentContext } from "./utils/createExperimentContext";