@nextsparkjs/plugin-amplitude 0.1.0-beta.1

package/hooks/useAmplitudeEvents.ts

@@ -0,0 +1,100 @@
+import { useEffect, useCallback } from 'react';
+import { useRouter } from 'next/router';
+import { useAmplitude } from './useAmplitude';
+import { debounce } from '../utils/debounce';
+import { trackPerformanceMetric } from '../lib/performance';
+import { EventType } from '../types/amplitude.types';
+
+export const useAmplitudeEvents = () => {
+  const { track, identify, setUserProperties, isInitialized, context } = useAmplitude();
+  const router = useRouter();
+
+  // Page View Tracking
+  useEffect(() => {
+    if (!isInitialized || !router) return;
+
+    const handleRouteChange = (url: string) => {
+      const startTime = performance.now();
+      track('Page Viewed' as EventType, { path: url, referrer: document.referrer });
+      const endTime = performance.now();
+      trackPerformanceMetric('page_view_duration', endTime - startTime, 'ms', { path: url });
+    };
+
+    router.events.on('routeChangeComplete', handleRouteChange);
+    return () => {
+      router.events.off('routeChangeComplete', handleRouteChange);
+    };
+  }, [isInitialized, router, track]);
+
+  // Click Tracking
+  const handleClick = useCallback(debounce((event: MouseEvent) => {
+    const target = event.target as HTMLElement;
+    let eventName = 'Click';
+    let properties: Record<string, any> = {};
+
+    if (target.dataset.track) {
+      eventName = target.dataset.track;
+    } else if (target.tagName === 'BUTTON') {
+      eventName = 'Button Click';
+      properties.buttonText = target.innerText.substring(0, 100);
+    } else if (target.tagName === 'A') {
+      eventName = 'Link Click';
+      properties.linkHref = (target as HTMLAnchorElement).href;
+      properties.linkText = target.innerText.substring(0, 100);
+    }
+
+    properties.elementId = target.id;
+    properties.elementClass = target.className;
+    properties.pagePath = router?.asPath;
+
+    if (eventName !== 'Click' || Object.keys(properties).length > 0) {
+      track(eventName as EventType, properties);
+    }
+  }, 300), [track, router]);
+
+  useEffect(() => {
+    if (!isInitialized) return;
+    document.addEventListener('click', handleClick);
+    return () => {
+      document.removeEventListener('click', handleClick);
+    };
+  }, [isInitialized, handleClick]);
+
+  // Form Submission Tracking
+  const handleFormSubmit = useCallback((event: Event) => {
+    const form = event.target as HTMLFormElement;
+    const formName = form.name || form.id || 'Unnamed Form';
+    const properties: Record<string, any> = { formName, pagePath: router?.asPath };
+
+    // Collect form field data, excluding sensitive fields
+    const formData = new FormData(form);
+    formData.forEach((value, key) => {
+      if (typeof value === 'string' && !/password|secret|token/i.test(key)) {
+        properties[`field_${key}`] = value.substring(0, 200);
+      }
+    });
+
+    track('Form Submitted' as EventType, properties);
+  }, [track, router]);
+
+  useEffect(() => {
+    if (!isInitialized) return;
+    document.querySelectorAll('form').forEach(form => {
+      form.addEventListener('submit', handleFormSubmit);
+    });
+    return () => {
+      document.querySelectorAll('form').forEach(form => {
+        form.removeEventListener('submit', handleFormSubmit);
+      });
+    };
+  }, [isInitialized, handleFormSubmit]);
+
+  return {
+    trackPageView: (path: string) => track('Page Viewed' as EventType, { path }),
+    trackClick: (element: string, properties?: Record<string, any>) => 
+      track('Element Click' as EventType, { element, ...properties }),
+    trackFormSubmit: (formName: string, properties?: Record<string, any>) => 
+      track('Form Submitted' as EventType, { formName, ...properties }),
+  };
+};
+

package/hooks/useExperiment.ts

@@ -0,0 +1,195 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useAmplitudeContext } from '../providers/AmplitudeProvider';
+import { EventProperties, EventType } from '../types/amplitude.types';
+
+interface ExperimentConfig {
+  id: string;
+  name: string;
+  description: string;
+  status: 'draft' | 'running' | 'paused' | 'completed';
+  variants: ExperimentVariant[];
+  targeting: ExperimentTargeting;
+  metrics: string[];
+  startDate: Date;
+  endDate?: Date;
+  sampleSize?: number;
+  confidenceLevel?: number;
+  minimumDetectableEffect?: number;
+  allocations: Record<string, number>;
+  stickiness: 'user' | 'device' | 'session';
+}
+
+interface ExperimentVariant {
+  id: string;
+  name: string;
+  description: string;
+  allocation: number;
+  isControl: boolean;
+  config: Record<string, any>;
+}
+
+interface ExperimentTargeting {
+  userProperties?: Record<string, any>;
+  geolocation?: string[];
+  deviceType?: string[];
+  timeRange?: { start: string; end: string };
+}
+
+interface ExperimentExposure {
+  experimentId: string;
+  variantId: string;
+  userId?: string;
+  timestamp: number;
+  properties?: EventProperties;
+}
+
+interface ExperimentConversion {
+  experimentId: string;
+  variantId: string;
+  metricId: string;
+  value?: number;
+  userId?: string;
+  timestamp: number;
+}
+
+export const useExperiment = () => {
+  const { amplitude, isInitialized, config, consent, error } = useAmplitudeContext();
+  const [experiments, setExperiments] = useState<Map<string, ExperimentConfig>>(new Map());
+  const [exposures, setExposures] = useState<Map<string, ExperimentExposure>>(new Map());
+  const [conversions, setConversions] = useState<ExperimentConversion[]>([]);
+
+  const canRunExperiments = isInitialized && config?.enableABTesting && consent.experiments;
+
+  const registerExperiment = useCallback((experiment: ExperimentConfig) => {
+    setExperiments(prev => new Map(prev.set(experiment.id, experiment)));
+  }, []);
+
+  const getVariant = useCallback((experimentId: string, userId: string): string | null => {
+    if (!canRunExperiments) return null;
+
+    const experiment = experiments.get(experimentId);
+    if (!experiment || experiment.status !== 'running') return null;
+
+    // Check if user was already assigned
+    const exposureKey = `${experimentId}_${userId}`;
+    const existingExposure = exposures.get(exposureKey);
+    if (existingExposure) {
+      return existingExposure.variantId;
+    }
+
+    // Simple hash-based assignment for deterministic results
+    const hash = Array.from(userId).reduce((acc, char) => acc + char.charCodeAt(0), 0);
+    const totalAllocation = Object.values(experiment.allocations).reduce((sum, val) => sum + val, 0);
+    const assignment = hash % totalAllocation;
+
+    let currentThreshold = 0;
+    for (const [variantId, allocation] of Object.entries(experiment.allocations)) {
+      currentThreshold += allocation;
+      if (assignment < currentThreshold) {
+        return variantId;
+      }
+    }
+
+    // Fallback to control
+    const controlVariant = experiment.variants.find(v => v.isControl);
+    return controlVariant?.id || experiment.variants[0]?.id || null;
+  }, [canRunExperiments, experiments, exposures]);
+
+  const trackExposure = useCallback(async (experimentId: string, variantId?: string, properties?: EventProperties) => {
+    if (!canRunExperiments || !amplitude) return;
+
+    const experiment = experiments.get(experimentId);
+    if (!experiment) {
+      console.warn(`Experiment ${experimentId} not found`);
+      return;
+    }
+
+    const actualVariantId = variantId || getVariant(experimentId, 'current-user');
+    if (!actualVariantId) return;
+
+    const exposureKey = `${experimentId}_current-user`;
+    const exposure: ExperimentExposure = {
+      experimentId,
+      variantId: actualVariantId,
+      userId: 'current-user',
+      timestamp: Date.now(),
+      properties
+    };
+
+    setExposures(prev => new Map(prev.set(exposureKey, exposure)));
+
+    await amplitude.track('Experiment Exposed' as EventType, {
+      experiment_id: experimentId,
+      experiment_name: experiment.name,
+      variant_id: actualVariantId,
+      variant_name: experiment.variants.find(v => v.id === actualVariantId)?.name,
+      is_control: experiment.variants.find(v => v.id === actualVariantId)?.isControl,
+      ...properties
+    });
+  }, [canRunExperiments, amplitude, experiments, getVariant]);
+
+  const trackConversion = useCallback(async (experimentId: string, metricId?: string, value?: number, properties?: EventProperties) => {
+    if (!canRunExperiments || !amplitude) return;
+
+    const exposureKey = `${experimentId}_current-user`;
+    const exposure = exposures.get(exposureKey);
+    
+    if (!exposure) {
+      console.warn(`No exposure found for experiment ${experimentId}. Must track exposure before conversion.`);
+      return;
+    }
+
+    const conversion: ExperimentConversion = {
+      experimentId,
+      variantId: exposure.variantId,
+      metricId: metricId || 'default',
+      value,
+      userId: 'current-user',
+      timestamp: Date.now()
+    };
+
+    setConversions(prev => [...prev, conversion]);
+
+    await amplitude.track('Experiment Converted' as EventType, {
+      experiment_id: experimentId,
+      variant_id: exposure.variantId,
+      metric_id: metricId,
+      conversion_value: value,
+      time_to_conversion: Date.now() - exposure.timestamp,
+      ...properties
+    });
+  }, [canRunExperiments, amplitude, exposures]);
+
+  const isInExperiment = useCallback((experimentId: string, userId: string): boolean => {
+    const variant = getVariant(experimentId, userId);
+    return variant !== null;
+  }, [getVariant]);
+
+  const getExperimentConfig = useCallback((experimentId: string): ExperimentConfig | null => {
+    return experiments.get(experimentId) || null;
+  }, [experiments]);
+
+  const getAllExperiments = useCallback((): ExperimentConfig[] => {
+    return Array.from(experiments.values());
+  }, [experiments]);
+
+  return {
+    // Core functions
+    getVariant,
+    trackExposure,
+    trackConversion,
+    isInExperiment,
+    registerExperiment,
+    
+    // State getters
+    experiments,
+    exposures,
+    conversions,
+    canRunExperiments,
+    
+    // Utility functions
+    getExperimentConfig,
+    getAllExperiments,
+  };
+};
+

package/hooks/useSessionReplay.ts

@@ -0,0 +1,238 @@
+import { useEffect, useState, useCallback } from 'react';
+import { useAmplitudeContext } from '../providers/AmplitudeProvider';
+
+interface RecordingState {
+  isRecording: boolean;
+  isPaused: boolean;
+  duration: number;
+  eventsCount: number;
+  sessionId: string | null;
+  recordingSize: number;
+}
+
+interface PrivacyControls {
+  maskAllInputs: boolean;
+  maskAllText: boolean;
+  blockSelectors: string[];
+  maskSelectors: string[];
+  ignoredPages: string[];
+  recordingSampleRate: number;
+}
+
+interface SessionReplayConfig {
+  enabled: boolean;
+  privacyMode: 'strict' | 'balanced' | 'permissive';
+  sampleRate: number;
+  maxDurationMs: number;
+  maxEventsPerSession: number;
+  blockClass: string;
+  maskClass: string;
+  ignoredPages: string[];
+}
+
+export const useSessionReplay = () => {
+  const { isInitialized, config, consent, error } = useAmplitudeContext();
+  
+  const [recordingState, setRecordingState] = useState<RecordingState>({
+    isRecording: false,
+    isPaused: false,
+    duration: 0,
+    eventsCount: 0,
+    sessionId: null,
+    recordingSize: 0,
+  });
+
+  const [privacyControls, setPrivacyControls] = useState<PrivacyControls>({
+    maskAllInputs: true,
+    maskAllText: false,
+    blockSelectors: [
+      '[data-private]',
+      '.sensitive-data',
+      '#credit-card-form',
+      'input[type="password"]',
+      'input[type="email"]',
+      '.user-details'
+    ],
+    maskSelectors: [
+      'input[type="text"]',
+      'textarea',
+      '[data-mask]'
+    ],
+    ignoredPages: ['/admin', '/payment', '/settings'],
+    recordingSampleRate: 0.1, // 10%
+  });
+
+  const canRecord = isInitialized && 
+                   config?.enableSessionReplay && 
+                   consent.sessionReplay && 
+                   !error;
+
+  const isCurrentPageIgnored = useCallback(() => {
+    if (typeof window === 'undefined') return true;
+    const currentPath = window.location.pathname;
+    return privacyControls.ignoredPages.some(page => currentPath.includes(page));
+  }, [privacyControls.ignoredPages]);
+
+  const shouldSample = useCallback(() => {
+    return Math.random() < privacyControls.recordingSampleRate;
+  }, [privacyControls.recordingSampleRate]);
+
+  const generateSessionId = useCallback(() => {
+    return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }, []);
+
+  const startRecording = useCallback(async (): Promise<boolean> => {
+    if (!canRecord || isCurrentPageIgnored() || !shouldSample()) {
+      return false;
+    }
+
+    if (recordingState.isRecording) {
+      console.warn('Session replay is already recording');
+      return true;
+    }
+
+    try {
+      const sessionId = generateSessionId();
+      
+      // Initialize session replay (this would integrate with actual Amplitude Session Replay SDK)
+      console.log(`[Session Replay] Starting recording with session ID: ${sessionId}`);
+      
+      setRecordingState(prev => ({
+        ...prev,
+        isRecording: true,
+        isPaused: false,
+        sessionId,
+        duration: 0,
+        eventsCount: 0,
+        recordingSize: 0,
+      }));
+
+      // Store session info
+      localStorage.setItem('amplitude_session_replay_id', sessionId);
+      localStorage.setItem('amplitude_session_replay_start', Date.now().toString());
+
+      return true;
+    } catch (error) {
+      console.error('[Session Replay] Failed to start recording:', error);
+      return false;
+    }
+  }, [canRecord, isCurrentPageIgnored, shouldSample, recordingState.isRecording, generateSessionId]);
+
+  const stopRecording = useCallback(async (): Promise<void> => {
+    if (!recordingState.isRecording) {
+      console.warn('Session replay is not currently recording');
+      return;
+    }
+
+    try {
+      console.log(`[Session Replay] Stopping recording for session: ${recordingState.sessionId}`);
+      
+      setRecordingState(prev => ({
+        ...prev,
+        isRecording: false,
+        isPaused: false,
+      }));
+
+      // Clean up session info
+      localStorage.removeItem('amplitude_session_replay_id');
+      localStorage.removeItem('amplitude_session_replay_start');
+
+    } catch (error) {
+      console.error('[Session Replay] Failed to stop recording:', error);
+    }
+  }, [recordingState.isRecording, recordingState.sessionId]);
+
+  const pauseRecording = useCallback(() => {
+    if (!recordingState.isRecording || recordingState.isPaused) {
+      return;
+    }
+
+    console.log('[Session Replay] Pausing recording');
+    setRecordingState(prev => ({
+      ...prev,
+      isPaused: true,
+    }));
+  }, [recordingState.isRecording, recordingState.isPaused]);
+
+  const resumeRecording = useCallback(() => {
+    if (!recordingState.isRecording || !recordingState.isPaused) {
+      return;
+    }
+
+    console.log('[Session Replay] Resuming recording');
+    setRecordingState(prev => ({
+      ...prev,
+      isPaused: false,
+    }));
+  }, [recordingState.isRecording, recordingState.isPaused]);
+
+  const updatePrivacyControls = useCallback((updates: Partial<PrivacyControls>) => {
+    setPrivacyControls(prev => ({
+      ...prev,
+      ...updates,
+    }));
+  }, []);
+
+  // Auto-start recording when conditions are met
+  useEffect(() => {
+    if (canRecord && !recordingState.isRecording && !isCurrentPageIgnored()) {
+      startRecording();
+    }
+  }, [canRecord, recordingState.isRecording, isCurrentPageIgnored, startRecording]);
+
+  // Update recording duration
+  useEffect(() => {
+    if (!recordingState.isRecording || recordingState.isPaused) return;
+
+    const interval = setInterval(() => {
+      setRecordingState(prev => ({
+        ...prev,
+        duration: prev.duration + 1000,
+      }));
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, [recordingState.isRecording, recordingState.isPaused]);
+
+  // Page visibility handling
+  useEffect(() => {
+    const handleVisibilityChange = () => {
+      if (document.hidden && recordingState.isRecording && !recordingState.isPaused) {
+        pauseRecording();
+      } else if (!document.hidden && recordingState.isRecording && recordingState.isPaused) {
+        resumeRecording();
+      }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', handleVisibilityChange);
+  }, [recordingState.isRecording, recordingState.isPaused, pauseRecording, resumeRecording]);
+
+  // Clean up on unmount
+  useEffect(() => {
+    return () => {
+      if (recordingState.isRecording) {
+        stopRecording();
+      }
+    };
+  }, [recordingState.isRecording, stopRecording]);
+
+  return {
+    // Core functions
+    startRecording,
+    stopRecording,
+    pauseRecording,
+    resumeRecording,
+    
+    // State
+    isRecording: recordingState.isRecording,
+    canRecord,
+    recordingState,
+    privacyControls,
+    
+    // Privacy controls
+    updatePrivacyControls,
+    isCurrentPageIgnored,
+  };
+};
+