@probat/react 0.2.1 → 0.3.0

package/src/hooks/useExperiment.ts

@@ -1,188 +0,0 @@
-"use client";
-
-import { useState, useEffect, useCallback } from "react";
-import type { MouseEvent } from "react";
-import { useProbatContext } from "../context/ProbatContext";
-import { fetchDecision } from "../utils/api";
-import {
-    readChoice,
-    writeChoice,
-    hasTrackedVisit,
-    markTrackedVisit,
-} from "../utils/storage";
-import { sendMetric } from "../utils/api";
-
-export 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;
-    /**
-     * Manually track a click for this experiment
-     */
-    trackClick: (event?: MouseEvent | null) => 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>
- * );
- * ```
- */
-export function useExperiment(
-    proposalId: string,
-    options?: { autoTrackImpression?: boolean }
-): UseExperimentReturn {
-    const context = useProbatContext();
-    const { apiBaseUrl } = context;
-    const [choice, setChoice] = useState<{
-        experiment_id: string;
-        label: string;
-    } | null>(null);
-    const [isLoading, setIsLoading] = useState(true);
-    const [error, setError] = useState<Error | null>(null);
-
-    const autoTrackImpression = options?.autoTrackImpression !== false;
-
-    // Fetch experiment decision
-    useEffect(() => {
-        let alive = true;
-
-        // Detect if we are in heatmap mode
-        const isHeatmapMode = typeof window !== 'undefined' &&
-            new URLSearchParams(window.location.search).get('heatmap') === 'true';
-
-        // HIGH PRIORITY: Check if context is already forcing a specific variant for this proposal
-        // (This happens during Live Heatmap visualization)
-        if (context.proposalId === proposalId && context.variantLabel) {
-            console.log(`[PROBAT] Forced variant from context: ${context.variantLabel}`);
-            setChoice({
-                experiment_id: `forced_${proposalId}`,
-                label: context.variantLabel
-            });
-            setIsLoading(false);
-            return;
-        }
-
-        // If we are in heatmap mode, bypass the cache to avoid showing stale variants
-        const cached = isHeatmapMode ? null : readChoice(proposalId);
-
-        if (cached) {
-            setChoice({ experiment_id: cached.experiment_id, label: cached.label });
-            setIsLoading(false);
-        } else {
-            setIsLoading(true);
-            (async () => {
-                try {
-                    const { experiment_id, label } = await fetchDecision(
-                        apiBaseUrl,
-                        proposalId
-                    );
-                    if (!alive) return;
-
-                    // Only write to choice cache if NOT in heatmap mode
-                    if (!isHeatmapMode) {
-                        writeChoice(proposalId, experiment_id, label);
-                    }
-
-                    setChoice({ experiment_id, label });
-                    setError(null);
-                } catch (e) {
-                    if (!alive) return;
-                    const err = e instanceof Error ? e : new Error(String(e));
-                    setError(err);
-                    setChoice({
-                        experiment_id: `exp_${proposalId}`,
-                        label: "control",
-                    });
-                } finally {
-                    if (alive) {
-                        setIsLoading(false);
-                    }
-                }
-            })();
-        }
-
-        return () => {
-            alive = false;
-        };
-    }, [proposalId, apiBaseUrl, context.proposalId, context.variantLabel]);
-
-    // Track impression when variant is determined
-    useEffect(() => {
-        if (!autoTrackImpression || !choice) return;
-
-        const exp = choice.experiment_id;
-        const lbl = choice.label ?? "control";
-        if (!lbl) return;
-
-        // Only track if we haven't already tracked this visit
-        if (hasTrackedVisit(proposalId, lbl)) return;
-        markTrackedVisit(proposalId, lbl);
-        void sendMetric(apiBaseUrl, proposalId, "visit", lbl, exp);
-    }, [proposalId, choice?.experiment_id, choice?.label, apiBaseUrl, autoTrackImpression]);
-
-    const trackClick = useCallback(
-        (event?: MouseEvent | null) => {
-            const exp = choice?.experiment_id;
-            const lbl = choice?.label ?? "control";
-            const meta = event
-                ? (() => {
-                    const rawTarget = event.target as HTMLElement | null;
-                    if (!rawTarget) return undefined;
-                    const actionable = rawTarget.closest(
-                        "[data-probat-conversion='true'], button, a, [role='button']"
-                    );
-                    if (!actionable) return undefined;
-                    const meta: Record<string, any> = {
-                        target_tag: actionable.tagName,
-                    };
-                    if (actionable.id) meta.target_id = actionable.id;
-                    const attr = actionable.getAttribute("data-probat-conversion");
-                    if (attr) meta.conversion_attr = attr;
-                    const text = actionable.textContent?.trim();
-                    if (text) meta.target_text = text.slice(0, 120);
-                    return meta;
-                })()
-                : undefined;
-
-            void sendMetric(apiBaseUrl, proposalId, "click", lbl, undefined, meta);
-        },
-        [proposalId, choice?.experiment_id, choice?.label, apiBaseUrl]
-    );
-
-    return {
-        variantLabel: choice?.label ?? "control",
-        experimentId: choice?.experiment_id ?? null,
-        isLoading,
-        error,
-        trackClick,
-    };
-}
-

package/src/utils/documentClickTracker.ts

@@ -1,215 +0,0 @@
-/**
- * Document-level click tracking for Probat experiments
- * 
- * This module implements event delegation at the document level to track clicks
- * even when components don't have onClick handlers or when stopPropagation() is called.
- */
-
-import { sendMetric } from './api';
-import { extractClickMeta } from './api';
-
-// Cache for proposal metadata to avoid repeated DOM queries
-const proposalCache = new Map<string, {
-    proposalId: string;
-    experimentId: string | null;
-    variantLabel: string;
-    apiBaseUrl: string;
-}>();
-
-// Track if listener is already attached
-let isListenerAttached = false;
-
-// Rate limiting: prevent duplicate rapid clicks
-const lastClickTime = new Map<string, number>();
-const DEBOUNCE_MS = 100; // Ignore clicks within 100ms of each other
-
-/**
- * Get proposal metadata from DOM element
- * Looks for the nearest [data-probat-proposal] wrapper
- */
-function getProposalMetadata(element: HTMLElement): {
-    proposalId: string;
-    experimentId: string | null;
-    variantLabel: string;
-    apiBaseUrl: string;
-} | null {
-    // Find the nearest probat wrapper
-    const probatWrapper = element.closest('[data-probat-proposal]') as HTMLElement | null;
-
-    if (!probatWrapper) return null;
-
-    const proposalId = probatWrapper.getAttribute('data-probat-proposal');
-    if (!proposalId) return null;
-
-    // Check cache first
-    const cacheKey = `${proposalId}`;
-    const cached = proposalCache.get(cacheKey);
-    if (cached) return cached;
-
-    // Extract metadata from data attributes
-    const experimentId = probatWrapper.getAttribute('data-probat-experiment-id');
-    const variantLabel = probatWrapper.getAttribute('data-probat-variant-label') || 'control';
-    const apiBaseUrl = probatWrapper.getAttribute('data-probat-api-base-url') ||
-        (typeof window !== 'undefined' && (window as any).__PROBAT_API) ||
-        'https://gushi.onrender.com';
-
-    const metadata = {
-        proposalId,
-        experimentId: experimentId || null,
-        variantLabel,
-        apiBaseUrl,
-    };
-
-    // Cache it
-    proposalCache.set(cacheKey, metadata);
-    return metadata;
-}
-
-/**
- * Handle click event at document level
- * Uses capture phase to catch events before stopPropagation()
- */
-function handleDocumentClick(event: MouseEvent): void {
-    const target = event.target as HTMLElement | null;
-    if (!target) return;
-
-    // Get proposal metadata
-    const metadata = getProposalMetadata(target);
-    if (!metadata) {
-        return; // Click outside probat component
-    }
-
-    // Rate limiting: prevent duplicate rapid clicks
-    const now = Date.now();
-    const lastClick = lastClickTime.get(metadata.proposalId) || 0;
-    if (now - lastClick < DEBOUNCE_MS) {
-        return; // Ignore rapid duplicate clicks
-    }
-    lastClickTime.set(metadata.proposalId, now);
-
-    // Extract click metadata (your existing function)
-    const clickMeta = extractClickMeta(event);
-
-    // Determine if we should track this click
-    // Track if:
-    // 1. It's an actionable element (button, link, etc.) - clickMeta exists
-    // 2. Element has data-probat-track attribute
-    // 3. Parent has data-probat-track attribute
-    // 4. ANY click within a probat component (more permissive - track all clicks)
-    const hasTrackAttribute = target.hasAttribute('data-probat-track') ||
-        target.closest('[data-probat-track]') !== null;
-
-    // More permissive: Track ALL clicks within probat components
-    // This ensures we capture clicks even if elements don't have explicit tracking attributes
-    const shouldTrack = clickMeta !== undefined || hasTrackAttribute || true; // Track all clicks in probat components
-
-    if (!shouldTrack) {
-        return;
-    }
-
-    // Build metadata - use clickMeta if available, otherwise create basic metadata
-    const finalMeta = clickMeta || {
-        target_tag: target.tagName,
-        target_class: target.className || '',
-        target_id: target.id || '',
-        clicked_inside_probat: true, // Flag to indicate this was tracked via document-level listener
-    };
-
-    // Send click metric
-    // For control variant, don't send experiment_id (control might be synthetic)
-    // For other variants, send experiment_id if it exists and is valid (not synthetic "exp_" prefix)
-    const experimentId = metadata.variantLabel === 'control'
-        ? undefined
-        : (metadata.experimentId && !metadata.experimentId.startsWith('exp_')
-            ? metadata.experimentId
-            : undefined);
-
-    void sendMetric(
-        metadata.apiBaseUrl,
-        metadata.proposalId,
-        'click',
-        metadata.variantLabel,
-        experimentId,
-        finalMeta
-    );
-
-    // Debug logging (always log for now to help diagnose)
-    console.log('[PROBAT] Click tracked:', {
-        proposalId: metadata.proposalId,
-        variantLabel: metadata.variantLabel,
-        target: target.tagName,
-        targetId: target.id || 'none',
-        targetClass: target.className || 'none',
-        meta: finalMeta,
-    });
-
-    // Also log to help debug if API call fails
-    console.log('[PROBAT] Sending metric to:', `${metadata.apiBaseUrl}/send_metrics/${metadata.proposalId}`);
-}
-
-/**
- * Initialize document-level click tracking
- * Call this once when your app initializes (typically in ProbatProvider)
- */
-export function initDocumentClickTracking(): void {
-    if (isListenerAttached) {
-        console.warn('[PROBAT] Document click listener already attached');
-        return;
-    }
-
-    if (typeof document === 'undefined') {
-        // Server-side rendering - skip
-        return;
-    }
-
-    // Use capture phase (true) to catch events before they bubble
-    // This ensures we catch clicks even if stopPropagation() is called
-    document.addEventListener('click', handleDocumentClick, true);
-
-    isListenerAttached = true;
-    console.log('[PROBAT] Document-level click tracking initialized');
-}
-
-/**
- * Clean up the listener (useful for testing or cleanup)
- */
-export function cleanupDocumentClickTracking(): void {
-    if (!isListenerAttached) return;
-
-    if (typeof document !== 'undefined') {
-        document.removeEventListener('click', handleDocumentClick, true);
-    }
-
-    isListenerAttached = false;
-    proposalCache.clear();
-    lastClickTime.clear();
-}
-
-/**
- * Update proposal metadata cache (call this when proposal data changes)
- * This is useful if you want to update the cache without waiting for DOM queries
- */
-export function updateProposalMetadata(
-    proposalId: string,
-    metadata: {
-        experimentId?: string | null;
-        variantLabel?: string;
-        apiBaseUrl?: string;
-    }
-): void {
-    const existing = proposalCache.get(proposalId);
-    if (existing) {
-        proposalCache.set(proposalId, {
-            ...existing,
-            ...metadata,
-        });
-    }
-}
-
-/**
- * Clear the proposal cache (useful for testing)
- */
-export function clearProposalCache(): void {
-    proposalCache.clear();
-}
-