@probat/react 0.2.1 → 0.3.0

package/dist/index.d.mts

@@ -1,274 +1,103 @@
-import React, { MouseEvent } from 'react';
+import React from 'react';
 
-declare global {
-    interface Window {
-        __PROBAT_API?: string;
-    }
-}
-interface ProbatContextValue {
-    apiBaseUrl: string;
-    environment: "dev" | "prod";
-    clientKey?: string;
-    repoFullName?: string;
-    proposalId?: string;
-    variantLabel?: string;
-}
 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;
 }
-declare function ProbatProvider({ apiBaseUrl, clientKey, environment: explicitEnvironment, repoFullName: explicitRepoFullName, proposalId, variantLabel, children, }: ProbatProviderProps): React.JSX.Element;
-declare function useProbatContext(): ProbatContextValue;
 
 /**
- * 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
- */
-declare function ProbatProviderClient(props: ProbatProviderProps): React.FunctionComponentElement<ProbatProviderProps>;
-
-interface UseProbatMetricsReturn {
-    /**
-     * Track a click event
-     * @param event - Optional React mouse event (will extract metadata automatically)
-     * @param options - Optional configuration
-     * @param options.force - Force tracking even if no actionable element is found
-     * @param options.proposalId - Override the proposal ID (usually not needed)
-     * @param options.variantLabel - Override the variant label (usually not needed)
-     * @param options.dimensions - Additional dimensions to include
-     */
-    trackClick: (event?: MouseEvent | null, options?: {
-        force?: boolean;
-        proposalId?: string;
-        variantLabel?: string;
-        dimensions?: Record<string, any>;
-    }) => boolean;
-    /**
-     * Track a custom metric
-     * @param metricName - Name of the metric
-     * @param proposalId - Proposal ID
-     * @param variantLabel - Variant label (defaults to "control")
-     * @param dimensions - Additional dimensions
-     */
-    trackMetric: (metricName: string, proposalId: string, variantLabel?: string, dimensions?: Record<string, any>) => void;
-    /**
-     * Track an impression/view
-     * @param proposalId - Proposal ID
-     * @param variantLabel - Variant label (defaults to "control")
-     * @param experimentId - Optional experiment ID
-     */
-    trackImpression: (proposalId: string, variantLabel?: string, experimentId?: string) => void;
-}
-/**
- * Hook for tracking Probat metrics (clicks, impressions, custom metrics)
+ * Client-only provider for Next.js App Router.
+ * Import this in your layout/providers file.
  *
  * @example
  * ```tsx
- * const { trackClick, trackImpression } = useProbatMetrics();
- *
- * // Track click on button
- * <button onClick={(e) => trackClick(e)}>Click me</button>
+ * // app/providers.tsx
+ * "use client";
+ * import { ProbatProviderClient } from "@probat/react";
  *
- * // Track impression
- * useEffect(() => {
- *   trackImpression(proposalId, variantLabel, experimentId);
- * }, [proposalId, variantLabel, experimentId]);
+ * export function Providers({ children }) {
+ *   return (
+ *     <ProbatProviderClient userId="your-user-uuid">
+ *       {children}
+ *     </ProbatProviderClient>
+ *   );
+ * }
  * ```
  */
-declare function useProbatMetrics(): UseProbatMetricsReturn;
+declare function ProbatProviderClient(props: ProbatProviderProps): React.FunctionComponentElement<ProbatProviderProps>;
 
-interface UseExperimentReturn {
-    /**
-     * The current variant label (e.g., "control", "variant-a")
-     */
-    variantLabel: string;
-    /**
-     * The experiment ID
-     */
-    experimentId: string | null;
-    /**
-     * Whether the experiment decision is still loading
-     */
-    isLoading: boolean;
-    /**
-     * Any error that occurred while fetching the experiment
-     */
-    error: Error | null;
+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;
+}
+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;
+}
+declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React.JSX.Element;
+
+interface UseProbatMetricsReturn {
     /**
-     * Manually track a click for this experiment
+     * Send a custom event with arbitrary properties.
+     * Never throws — failures are silently dropped.
+     *
+     * @example
+     * ```tsx
+     * const { capture } = useProbatMetrics();
+     * capture("purchase", { revenue: 42, currency: "USD" });
+     * ```
      */
-    trackClick: (event?: MouseEvent | null) => void;
+    capture: (event: string, properties?: Record<string, unknown>) => void;
 }
 /**
- * Hook for fetching and applying experiment variants
- *
- * @param proposalId - The proposal ID for the experiment
- * @param options - Optional configuration
- * @param options.autoTrackImpression - Automatically track impression when variant is loaded (default: true)
- *
- * @example
- * ```tsx
- * const { variantLabel, isLoading, trackClick } = useExperiment("proposal-id");
- *
- * if (isLoading) return <div>Loading...</div>;
- *
- * return (
- *   <div onClick={trackClick}>
- *     {variantLabel === "control" ? <ControlComponent /> : <VariantComponent />}
- *   </div>
- * );
- * ```
+ * Minimal metrics hook. Provides a single `capture(event, props)` function
+ * that sends events to the Probat backend using the provider's host config.
  */
-declare function useExperiment(proposalId: string, options?: {
-    autoTrackImpression?: boolean;
-}): UseExperimentReturn;
+declare function useProbatMetrics(): UseProbatMetricsReturn;
 
-interface WithExperimentOptions {
-    componentPath?: string;
-    repoFullName?: string;
-    proposalId?: string;
-    registry?: Record<string, React.ComponentType<any>>;
+interface DecisionResponse {
+    variant_key: string;
+}
+interface MetricPayload {
+    event: string;
+    properties: Record<string, unknown>;
 }
 /**
- * Higher-Order Component for wrapping components with experiment variants
- */
-declare function withExperiment<P = any>(Control: React.ComponentType<P>, options: WithExperimentOptions): React.ComponentType<P & {
-    probat?: {
-        trackClick: () => void;
-    };
-}>;
-
-/**
- * Detect if the code is running on localhost (development environment).
- * Returns "dev" for localhost, "prod" for production.
- */
-declare function detectEnvironment(): "dev" | "prod";
-
-type RetrieveResponse = {
-    proposal_id: string;
-    experiment_id: string | null;
-    label: string | null;
-};
-declare function fetchDecision(baseUrl: string, proposalId: string): Promise<{
-    experiment_id: string;
-    label: string;
-}>;
-declare function sendMetric(baseUrl: string, proposalId: string, metricName: "visit" | "click" | string, variantLabel?: string, experimentId?: string, dimensions?: Record<string, any>): Promise<void>;
-declare function extractClickMeta(event?: {
-    target?: EventTarget | null;
-} | null): Record<string, any> | undefined;
-
-/**
- * Universal Heatmap Tracker for User Websites
- *
- * Tracks all clicks across the entire user website for heatmap visualization.
- * This is injected into user websites via the probat-react package.
+ * Fetch the variant assignment for an experiment.
+ * Returns the variant key string (e.g. "control", "ai_v1").
+ * Deduplicates concurrent calls for the same experiment.
  */
-interface HeatmapConfig {
-    apiBaseUrl: string;
-    batchSize?: number;
-    batchInterval?: number;
-    enabled?: boolean;
-    excludeSelectors?: string[];
-    trackCursor?: boolean;
-    cursorThrottle?: number;
-    cursorBatchSize?: number;
-    proposalId?: string;
-    variantLabel?: string;
-}
-declare class HeatmapTracker {
-    private clicks;
-    private movements;
-    private sessionId;
-    private config;
-    private batchTimer;
-    private cursorBatchTimer;
-    private lastCursorTime;
-    private isInitialized;
-    constructor(config: HeatmapConfig);
-    private getOrCreateSessionId;
-    private shouldExcludeElement;
-    private extractElementInfo;
-    private handleMouseMove;
-    private scheduleCursorBatchSend;
-    private sendCursorBatch;
-    private handleClick;
-    private scheduleBatchSend;
-    private sendBatch;
-    init(): void;
-    stop(): void;
-    /**
-     * Enable visualization mode
-     */
-    /**
-     * Enable visualization mode
-     */
-    private enableVisualization;
-    /**
-     * Render heatmap overlay on valid points
-     */
-    private renderHeatmapOverlay;
-    /**
-     * Draw points on canvas
-     */
-    private renderPoints;
-    /**
-     * Get heatmap color based on intensity
-     */
-    private getHeatmapColor;
-    /**
-     * Convert RGB to RGBA
-     */
-    private rgbToRgba;
-}
+declare function fetchDecision(host: string, experimentId: string, distinctId: string): Promise<string>;
 /**
- * Initialize heatmap tracking for user websites
- * Called automatically by ProbatProvider
+ * Fire-and-forget metric send. Never throws.
  */
-declare function initHeatmapTracking(config: HeatmapConfig): HeatmapTracker;
-declare function getHeatmapTracker(): HeatmapTracker | null;
-declare function stopHeatmapTracking(): void;
-
-type Choice = {
-    experiment_id: string;
-    label: string;
-    ts: number;
-};
-declare function readChoice(proposalId: string): Choice | null;
-declare function writeChoice(proposalId: string, experiment_id: string, label: string): void;
-declare function hasTrackedVisit(proposalId: string, label: string): boolean;
-declare function markTrackedVisit(proposalId: string, label: string): void;
+declare function sendMetric(host: string, event: string, properties: Record<string, unknown>): void;
 
-export { type Choice, type ProbatContextValue, ProbatProvider, ProbatProviderClient, type ProbatProviderProps as ProbatProviderClientProps, type ProbatProviderProps, type RetrieveResponse, type UseExperimentReturn, type UseProbatMetricsReturn, type WithExperimentOptions, detectEnvironment, extractClickMeta, fetchDecision, getHeatmapTracker, hasTrackedVisit, initHeatmapTracking, markTrackedVisit, readChoice, sendMetric, stopHeatmapTracking, useExperiment, useProbatContext, useProbatMetrics, withExperiment, writeChoice };
+export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, type UseProbatMetricsReturn, fetchDecision, sendMetric, useProbatMetrics };