@probat/react 0.2.1 → 0.3.1

package/README.md

@@ -1,379 +1,68 @@
 # @probat/react
 
-React library for Probat A/B testing and experimentation. This package provides a clean, reusable way to integrate Probat into your React applications without copying entire files into your repository.
+React SDK for Probat A/B testing. Automatic impression and click tracking with zero boilerplate.
 
-## Installation
+## Install
 
 ```bash
 npm install @probat/react
-# or
-yarn add @probat/react
-# or
-pnpm add @probat/react
 ```
 
 ## Quick Start
 
-### 1. Wrap your app with ProbatProvider
+Wrap your app root with the provider (Next.js App Router example):
 
 ```tsx
-import { ProbatProvider } from '@probat/react';
+// app/providers.tsx
+"use client";
+import { ProbatProviderClient } from "@probat/react";
 
-function App() {
+export function Providers({ children }: { children: React.ReactNode }) {
   return (
-    <ProbatProvider clientKey="your-client-key" environment="dev">
-      <YourApp />
-    </ProbatProvider>
+    <ProbatProviderClient userId="your-user-uuid">
+      {children}
+    </ProbatProviderClient>
   );
 }
 ```
 
-### 2. Use experiments in your components
-
-#### Option A: Using the `useExperiment` hook
+Create a thin experiment wrapper — one per experiment:
 
 ```tsx
-import { useExperiment } from '@probat/react';
-
-function MyComponent() {
-  const { variantLabel, isLoading, trackClick } = useExperiment('proposal-id');
-
-  if (isLoading) return <div>Loading...</div>;
+// components/CTAButton/CTAButton.experiment.tsx
+"use client";
+import { Experiment } from "@probat/react";
+import { CTAButton } from "./CTAButton";
+import { CTAButtonAI } from "./CTAButton.ai-v1";
 
+export function CTAButtonExperiment() {
   return (
-    <div onClick={trackClick}>
-      {variantLabel === 'control' ? (
-        <ControlVariant />
-      ) : (
-        <ExperimentVariant />
-      )}
-    </div>
+    <Experiment
+      id="cta-copy-test"
+      control={<CTAButton />}
+      variants={{ ai_v1: <CTAButtonAI /> }}
+    />
   );
 }
 ```
 
-#### Option B: Using the `withExperiment` HOC (backward compatible)
-
-```tsx
-import { withExperiment } from '@probat/react';
-
-const ControlComponent = () => <div>Control</div>;
-const VariantA = () => <div>Variant A</div>;
-const VariantB = () => <div>Variant B</div>;
-
-const ExperimentedComponent = withExperiment(ControlComponent, {
-  proposalId: 'proposal-id',
-  registry: {
-    'variant-a': VariantA,
-    'variant-b': VariantB,
-  },
-});
-```
+That's it. Impressions (50% visible for 250ms) and clicks are tracked automatically.
 
-### 3. Track metrics
+## Custom Metrics
 
 ```tsx
-import { useProbatMetrics } from '@probat/react';
-
-function Button() {
-  const { trackClick, trackMetric } = useProbatMetrics();
-
-  return (
-    <button
-      onClick={(e) => {
-        trackClick(e, {
-          proposalId: 'proposal-id',
-          variantLabel: 'control',
-        });
-      }}
-    >
-      Click me
-    </button>
-  );
-}
+const { capture } = useProbatMetrics();
+capture("purchase", { revenue: 42 });
 ```
 
-### 4. Heatmap Tracking (Automatic)
-
-Heatmap tracking is automatically enabled when you use `ProbatProvider`. It tracks:
-- **Click events**: User clicks across your website
-- **Cursor movements**: Mouse movement patterns for engagement analysis
-
-The tracking automatically associates data with the active experiment (`proposalId`) and variant (`variantLabel`) based on the experiment context. No additional configuration needed!
-
-```tsx
-// Heatmap tracking is automatically initialized by ProbatProvider
-<ProbatProvider clientKey="your-key" environment="dev">
-  <YourApp />
-</ProbatProvider>
-```
-
-To manually control heatmap tracking:
-
-```tsx
-import { initHeatmapTracking, stopHeatmapTracking } from '@probat/react';
-
-// Initialize with custom config
-initHeatmapTracking({
-  apiBaseUrl: 'https://api.probat.com',
-  batchSize: 10,
-  batchInterval: 5000,
-  trackCursor: true, // Enable cursor movement tracking
-});
-
-// Stop tracking when needed
-stopHeatmapTracking();
-```
-
-## API Reference
-
-### `<ProbatProvider>`
-
-Wraps your app and provides Probat configuration to all child components.
-
-#### Props
-
-- `apiBaseUrl?: 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"`
-- `clientKey?: string` - Client key for identification (optional)
-- `environment?: "dev" | "prod"` - Explicitly set environment. If not provided, will auto-detect based on hostname.
-- `proposalId?: string` - Optional proposal/experiment ID for heatmap tracking segregation
-- `variantLabel?: string` - Optional variant label for heatmap tracking segregation
-- `children: React.ReactNode` - Your app components
-
-**Note**: `proposalId` and `variantLabel` are automatically set from localStorage when experiments are active. You typically don't need to pass these manually.
-
-#### Example
-
-```tsx
-<ProbatProvider
-  apiBaseUrl="https://api.probat.com"
-  clientKey="your-key"
-  environment="prod"
->
-  <App />
-</ProbatProvider>
-```
-
-### `useExperiment(proposalId, options?)`
-
-Hook for fetching and applying experiment variants.
-
-#### Parameters
-
-- `proposalId: string` - The proposal ID for the experiment
-- `options?: { autoTrackImpression?: boolean }` - Optional configuration
-  - `autoTrackImpression` - Automatically track impression when variant is loaded (default: `true`)
-
-#### Returns
-
-- `variantLabel: string` - The current variant label (e.g., "control", "variant-a")
-- `experimentId: string | null` - The experiment ID
-- `isLoading: boolean` - Whether the experiment decision is still loading
-- `error: Error | null` - Any error that occurred while fetching the experiment
-- `trackClick: (event?: React.MouseEvent | null) => void` - Manually track a click for this experiment
-
-#### Example
-
-```tsx
-const { variantLabel, isLoading, trackClick } = useExperiment('proposal-id', {
-  autoTrackImpression: true,
-});
-```
-
-### `useProbatMetrics()`
-
-Hook for tracking Probat metrics (clicks, impressions, custom metrics).
-
-#### Returns
-
-- `trackClick(event?, options?)` - Track a click event
-  - `event?: React.MouseEvent` - Optional React mouse event (will extract metadata automatically)
-  - `options?: { force?: boolean; proposalId?: string; variantLabel?: string; dimensions?: Record<string, any> }`
-- `trackMetric(metricName, proposalId, variantLabel?, dimensions?)` - Track a custom metric
-- `trackImpression(proposalId, variantLabel?, experimentId?)` - Track an impression/view
-
-#### Example
-
-```tsx
-const { trackClick, trackMetric, trackImpression } = useProbatMetrics();
-
-// Track click
-<button onClick={(e) => trackClick(e, { proposalId: 'id', variantLabel: 'control' })}>
-  Click
-</button>
-
-// Track custom metric
-trackMetric('purchase', 'proposal-id', 'variant-a', { amount: 100 });
-
-// Track impression
-trackImpression('proposal-id', 'control', 'experiment-id');
-```
-
-### Heatmap Tracking Functions
-
-#### `initHeatmapTracking(config)`
+## Run the Example
 
-Initialize heatmap tracking with custom configuration.
-
-##### Parameters
-
-- `config: HeatmapConfig` - Configuration object:
-  - `apiBaseUrl: string` - Base URL for the heatmap API (default: from ProbatProvider)
-  - `batchSize?: number` - Number of clicks to batch before sending (default: `10`)
-  - `batchInterval?: number` - Time in ms to wait before sending batch (default: `5000`)
-  - `trackCursor?: boolean` - Enable cursor movement tracking (default: `true`)
-  - `cursorThrottle?: number` - Throttle cursor events in ms (default: `100`)
-  - `cursorBatchSize?: number` - Number of cursor movements to batch (default: `50`)
-  - `enabled?: boolean` - Enable/disable tracking (default: `true`)
-  - `excludeSelectors?: string[]` - CSS selectors to exclude from tracking
-  - `excludedOrigins?: string[]` - Origins to exclude from tracking
-
-##### Example
-
-```tsx
-import { initHeatmapTracking } from '@probat/react';
-
-initHeatmapTracking({
-  apiBaseUrl: 'https://api.probat.com',
-  batchSize: 20,
-  trackCursor: true,
-  cursorThrottle: 100,
-});
-```
-
-#### `stopHeatmapTracking()`
-
-Stop heatmap tracking and send any pending batches.
-
-##### Example
-
-```tsx
-import { stopHeatmapTracking } from '@probat/react';
-
-stopHeatmapTracking();
-```
-
-#### `getHeatmapTracker()`
-
-Get the current heatmap tracker instance (for advanced usage).
-
-##### Returns
-
-- `HeatmapTracker | null` - The tracker instance or null if not initialized
-
-### `withExperiment(Control, options)`
-
-Higher-Order Component for wrapping components with experiment variants (backward compatible with old injection pattern).
-
-#### Parameters
-
-- `Control: React.ComponentType` - The control/default component
-- `options: { proposalId: string; registry: Record<string, React.ComponentType> }`
-  - `proposalId` - The proposal ID
-  - `registry` - Map of variant labels to component types
-
-#### Returns
-
-A wrapped component that automatically selects and renders the correct variant.
-
-#### Example
-
-```tsx
-const ExperimentedComponent = withExperiment(ControlComponent, {
-  proposalId: 'proposal-id',
-  registry: {
-    'variant-a': VariantA,
-    'variant-b': VariantB,
-  },
-});
-```
-
-## Environment Detection
-
-The library automatically detects whether you're running in development or production based on the hostname:
-
-- **Development**: `localhost`, `127.0.0.1`, or local IP addresses (192.168.x.x, 10.x.x.x, 172.16-31.x.x)
-- **Production**: Everything else
-
-You can override this by passing the `environment` prop to `ProbatProvider`.
-
-## Configuration
-
-### Environment Variables
-
-You can configure the API base URL using environment variables:
-
-- **Vite**: `VITE_PROBAT_API=https://api.probat.com`
-- **Next.js**: `NEXT_PUBLIC_PROBAT_API=https://api.probat.com`
-- **Browser**: `window.__PROBAT_API = 'https://api.probat.com'`
-
-### TypeScript
-
-The package includes TypeScript definitions. No additional `@types` package needed.
-
-## Testing Locally
-
-1. Build the package:
-   ```bash
-   cd packages/probat-react
-   npm run build
-   ```
-
-2. Link it locally (optional, for testing in other projects):
-   ```bash
-   npm link
-   ```
-
-3. In your test project:
-   ```bash
-   npm link @probat/react
-   ```
-
-## Migration from Injected Files
-
-If you're currently using the injected file pattern, you can migrate gradually:
-
-1. Install the package: `npm install @probat/react`
-2. Wrap your app with `<ProbatProvider>`
-3. Replace `withExperiment` imports:
-   ```tsx
-   // Old
-   import { withExperiment } from '../../probat/runtime';
-   
-   // New
-   import { withExperiment } from '@probat/react';
-   ```
-4. Remove the `probat/` directory from your repo
-5. Update your component exports to use the new import
-
-## Next.js Support
-
-The package is fully compatible with Next.js 13+ App Router and Pages Router. See [NEXTJS_GUIDE.md](./NEXTJS_GUIDE.md) for detailed Next.js integration instructions.
-
-### Quick Next.js Example
-
-```tsx
-// app/layout.tsx (App Router)
-import { ProbatProvider } from '@probat/react';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <ProbatProvider clientKey="..." environment="dev">
-          {children}
-        </ProbatProvider>
-      </body>
-    </html>
-  );
-}
+```bash
+cd packages/probat-react/example
+node mocks/server.ts &     # mock API on :3001
+npx next dev                # app on :3000
 ```
 
-## License
-
-MIT
+## Docs
 
+See [SPEC.md](./SPEC.md) for the full event schemas, assignment rules, dedupe logic, and edge cases.