@nextsparkjs/plugin-amplitude 0.1.0-beta.1

package/lib/performance.ts

@@ -0,0 +1,319 @@
+import { EventType } from '../types/amplitude.types';
+
+export interface PerformanceMetric {
+  name: string;
+  value: number;
+  unit: string;
+  timestamp: number;
+  properties?: Record<string, any>;
+}
+
+export interface PerformanceStats {
+  amplitudeCore: {
+    initTime: number;
+    trackingLatency: number[];
+    errorRate: number;
+    eventQueueSize: number;
+    memoryUsage: number;
+  };
+  webVitals: {
+    cls: number;
+    fid: number;
+    fcp: number;
+    lcp: number;
+    ttfb: number;
+    inp: number;
+  };
+  browserMetrics: {
+    memoryUsage: number;
+    connectionType: string;
+    devicePixelRatio: number;
+    screenResolution: string;
+    viewportSize: string;
+  };
+}
+
+const performanceMetrics: PerformanceMetric[] = [];
+const performanceObservers: PerformanceObserver[] = [];
+const MAX_METRICS = 10000;
+const CLEANUP_THRESHOLD = 12000;
+
+// Internal performance stats
+let amplitudeCoreStats = {
+  initTime: 0,
+  trackingLatency: [] as number[],
+  errorCount: 0,
+  successCount: 0,
+  eventQueueSize: 0,
+  memoryUsage: 0,
+};
+
+export function trackPerformanceMetric(name: EventType | string, value: number, unit: string = 'ms', properties?: Record<string, any>): void {
+  if (typeof window === 'undefined') return;
+
+  const metric: PerformanceMetric = {
+    name: name as string,
+    value,
+    unit,
+    timestamp: Date.now(),
+    properties,
+  };
+
+  performanceMetrics.push(metric);
+
+  // Update internal stats based on metric type
+  updateInternalStats(name as string, value);
+
+  // Cleanup old metrics if we exceed threshold
+  if (performanceMetrics.length > CLEANUP_THRESHOLD) {
+    performanceMetrics.splice(0, performanceMetrics.length - MAX_METRICS);
+  }
+
+  // Log to console in debug mode
+  if (process.env.NODE_ENV === 'development') {
+    console.debug(`[Performance] ${name}: ${value}${unit}`, properties);
+  }
+}
+
+function updateInternalStats(name: string, value: number): void {
+  switch (name) {
+    case 'amplitude_init_success':
+      amplitudeCoreStats.initTime = value;
+      break;
+    case 'amplitude_track_latency':
+      amplitudeCoreStats.trackingLatency.push(value);
+      if (amplitudeCoreStats.trackingLatency.length > 100) {
+        amplitudeCoreStats.trackingLatency = amplitudeCoreStats.trackingLatency.slice(-50);
+      }
+      break;
+    case 'amplitude_track_success':
+    case 'amplitude_identify_success':
+    case 'amplitude_user_properties_success':
+      amplitudeCoreStats.successCount += value;
+      break;
+    case 'amplitude_track_error':
+    case 'amplitude_identify_error':
+    case 'amplitude_user_properties_error':
+    case 'amplitude_init_error':
+      amplitudeCoreStats.errorCount += value;
+      break;
+    case 'amplitude_queue_size':
+      amplitudeCoreStats.eventQueueSize = value;
+      break;
+    case 'amplitude_memory_usage':
+      amplitudeCoreStats.memoryUsage = value;
+      break;
+  }
+}
+
+export function getPerformanceMetrics(): PerformanceMetric[] {
+  return [...performanceMetrics].sort((a, b) => b.timestamp - a.timestamp);
+}
+
+export function getPerformanceStats(): PerformanceStats {
+  const stats: PerformanceStats = {
+    amplitudeCore: {
+      ...amplitudeCoreStats,
+      errorRate: amplitudeCoreStats.errorCount / Math.max(amplitudeCoreStats.successCount + amplitudeCoreStats.errorCount, 1),
+    },
+    webVitals: {
+      cls: 0,
+      fid: 0,
+      fcp: 0,
+      lcp: 0,
+      ttfb: 0,
+      inp: 0,
+    },
+    browserMetrics: {
+      memoryUsage: 0,
+      connectionType: 'unknown',
+      devicePixelRatio: 1,
+      screenResolution: '0x0',
+      viewportSize: '0x0',
+    },
+  };
+
+  if (typeof window !== 'undefined') {
+    // Browser metrics
+    stats.browserMetrics = {
+      memoryUsage: (performance as any).memory?.usedJSHeapSize || 0,
+      connectionType: (navigator as any).connection?.effectiveType || 'unknown',
+      devicePixelRatio: window.devicePixelRatio || 1,
+      screenResolution: `${window.screen.width}x${window.screen.height}`,
+      viewportSize: `${window.innerWidth}x${window.innerHeight}`,
+    };
+
+    // Web Vitals from recent metrics
+    const recentMetrics = performanceMetrics.filter(m => Date.now() - m.timestamp < 60000); // Last minute
+    stats.webVitals = {
+      cls: getLatestMetricValue(recentMetrics, 'CLS') || 0,
+      fid: getLatestMetricValue(recentMetrics, 'FID') || 0,
+      fcp: getLatestMetricValue(recentMetrics, 'FCP') || 0,
+      lcp: getLatestMetricValue(recentMetrics, 'LCP') || 0,
+      ttfb: getLatestMetricValue(recentMetrics, 'TTFB') || 0,
+      inp: getLatestMetricValue(recentMetrics, 'INP') || 0,
+    };
+  }
+
+  return stats;
+}
+
+function getLatestMetricValue(metrics: PerformanceMetric[], name: string): number | null {
+  const metric = metrics.filter(m => m.name === name).sort((a, b) => b.timestamp - a.timestamp)[0];
+  return metric?.value || null;
+}
+
+export function clearPerformanceMetrics(): void {
+  performanceMetrics.length = 0;
+  amplitudeCoreStats = {
+    initTime: 0,
+    trackingLatency: [],
+    errorCount: 0,
+    successCount: 0,
+    eventQueueSize: 0,
+    memoryUsage: 0,
+  };
+}
+
+export function setupPerformanceObservers(): void {
+  if (typeof window === 'undefined' || !window.PerformanceObserver) return;
+
+  try {
+    // Largest Contentful Paint (LCP)
+    const lcpObserver = new PerformanceObserver((entryList) => {
+      for (const entry of entryList.getEntries()) {
+        trackPerformanceMetric('LCP', entry.startTime + entry.duration, 'ms', {
+          element: (entry as any).element?.tagName,
+          url: window.location.href,
+        });
+      }
+    });
+    lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true });
+    performanceObservers.push(lcpObserver);
+
+    // Cumulative Layout Shift (CLS)
+    const clsObserver = new PerformanceObserver((entryList) => {
+      let cls = 0;
+      for (const entry of entryList.getEntries()) {
+        if (!(entry as any).hadRecentInput) {
+          cls += (entry as any).value;
+        }
+      }
+      if (cls > 0) {
+        trackPerformanceMetric('CLS', cls, 'score', { url: window.location.href });
+      }
+    });
+    clsObserver.observe({ type: 'layout-shift', buffered: true });
+    performanceObservers.push(clsObserver);
+
+    // First Contentful Paint (FCP)
+    const fcpObserver = new PerformanceObserver((entryList) => {
+      for (const entry of entryList.getEntries()) {
+        if (entry.name === 'first-contentful-paint') {
+          trackPerformanceMetric('FCP', entry.startTime, 'ms', { url: window.location.href });
+        }
+      }
+    });
+    fcpObserver.observe({ type: 'paint', buffered: true });
+    performanceObservers.push(fcpObserver);
+
+    // Navigation Timing
+    const navigationObserver = new PerformanceObserver((entryList) => {
+      for (const entry of entryList.getEntries()) {
+        const navEntry = entry as PerformanceNavigationTiming;
+        trackPerformanceMetric('TTFB', navEntry.responseStart - navEntry.requestStart, 'ms');
+        trackPerformanceMetric('DOMContentLoaded', navEntry.domContentLoadedEventEnd - navEntry.domContentLoadedEventStart, 'ms');
+        trackPerformanceMetric('Load', navEntry.loadEventEnd - navEntry.loadEventStart, 'ms');
+      }
+    });
+    navigationObserver.observe({ type: 'navigation', buffered: true });
+    performanceObservers.push(navigationObserver);
+
+    // Long Tasks
+    const longTaskObserver = new PerformanceObserver((entryList) => {
+      for (const entry of entryList.getEntries()) {
+        trackPerformanceMetric('Long Task', entry.duration, 'ms', {
+          name: entry.name,
+          startTime: entry.startTime,
+        });
+      }
+    });
+    longTaskObserver.observe({ type: 'longtask', buffered: true });
+    performanceObservers.push(longTaskObserver);
+
+    // Resource Timing
+    const resourceObserver = new PerformanceObserver((entryList) => {
+      for (const entry of entryList.getEntries()) {
+        const resourceEntry = entry as PerformanceResourceTiming;
+        trackPerformanceMetric('Resource Load', entry.duration, 'ms', {
+          name: entry.name,
+          initiatorType: resourceEntry.initiatorType,
+          transferSize: resourceEntry.transferSize,
+          responseStatus: (resourceEntry as any).responseStatus,
+        });
+      }
+    });
+    resourceObserver.observe({ type: 'resource', buffered: true });
+    performanceObservers.push(resourceObserver);
+
+  } catch (error) {
+    console.warn('[Performance] Failed to setup performance observers:', error);
+  }
+}
+
+export function disconnectPerformanceObservers(): void {
+  performanceObservers.forEach(observer => {
+    try {
+      observer.disconnect();
+    } catch (error) {
+      console.warn('[Performance] Failed to disconnect observer:', error);
+    }
+  });
+  performanceObservers.length = 0;
+}
+
+// Memory monitoring
+export function startMemoryMonitoring(intervalMs: number = 30000): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const interval = setInterval(() => {
+    if ((performance as any).memory) {
+      const memory = (performance as any).memory;
+      trackPerformanceMetric('JS Heap Used', memory.usedJSHeapSize, 'bytes');
+      trackPerformanceMetric('JS Heap Total', memory.totalJSHeapSize, 'bytes');
+      trackPerformanceMetric('JS Heap Limit', memory.jsHeapSizeLimit, 'bytes');
+    }
+  }, intervalMs);
+
+  return () => clearInterval(interval);
+}
+
+// Connection monitoring
+export function monitorConnection(): () => void {
+  if (typeof window === 'undefined' || !(navigator as any).connection) return () => {};
+
+  const connection = (navigator as any).connection;
+  
+  const handleConnectionChange = () => {
+    trackPerformanceMetric('Connection Type', 1, 'event', {
+      effectiveType: connection.effectiveType,
+      downlink: connection.downlink,
+      rtt: connection.rtt,
+      saveData: connection.saveData,
+    });
+  };
+
+  connection.addEventListener('change', handleConnectionChange);
+  
+  // Initial reading
+  handleConnectionChange();
+
+  return () => connection.removeEventListener('change', handleConnectionChange);
+}
+
+// Export for cleanup
+export function shutdownPerformanceMonitoring(): void {
+  disconnectPerformanceObservers();
+  clearPerformanceMetrics();
+}
+

package/lib/queue.ts

@@ -0,0 +1,389 @@
+import { EventType, EventProperties } from '../types/amplitude.types';
+import { trackPerformanceMetric } from './performance';
+
+interface QueuedEvent {
+  id: string;
+  eventType: EventType;
+  properties?: EventProperties;
+  timestamp: number;
+  retries: number;
+  priority: 'low' | 'normal' | 'high' | 'critical';
+  userId?: string;
+}
+
+interface QueueOptions {
+  flushInterval?: number;
+  batchSize?: number;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  maxQueueSize?: number;
+  persistenceEnabled?: boolean;
+  priorityEnabled?: boolean;
+}
+
+export class EventQueue {
+  private queue: QueuedEvent[] = [];
+  private isProcessing = false;
+  private flushInterval: number;
+  private batchSize: number;
+  private maxRetries: number;
+  private retryDelayMs: number;
+  private maxQueueSize: number;
+  private flushTimer: NodeJS.Timeout | null = null;
+  private sendBatchCallback: (events: QueuedEvent[]) => Promise<void>;
+  private persistenceEnabled: boolean;
+  private priorityEnabled: boolean;
+  private storageKey = 'amplitude_event_queue';
+
+  constructor(
+    sendBatchCallback: (events: QueuedEvent[]) => Promise<void>,
+    options: QueueOptions = {}
+  ) {
+    this.sendBatchCallback = sendBatchCallback;
+    this.flushInterval = options.flushInterval || 10000; // 10 seconds
+    this.batchSize = options.batchSize || 30;
+    this.maxRetries = options.maxRetries || 3;
+    this.retryDelayMs = options.retryDelayMs || 1000;
+    this.maxQueueSize = options.maxQueueSize || 10000;
+    this.persistenceEnabled = options.persistenceEnabled || true;
+    this.priorityEnabled = options.priorityEnabled || true;
+
+    this.loadPersistedEvents();
+    this.startFlushTimer();
+    this.setupOnlineListener();
+  }
+
+  public enqueue(
+    eventType: EventType, 
+    properties?: EventProperties, 
+    priority: 'low' | 'normal' | 'high' | 'critical' = 'normal',
+    userId?: string
+  ): string {
+    const event: QueuedEvent = {
+      id: this.generateEventId(),
+      eventType,
+      properties,
+      timestamp: Date.now(),
+      retries: 0,
+      priority,
+      userId,
+    };
+
+    // Check queue size limit
+    if (this.queue.length >= this.maxQueueSize) {
+      this.removeOldestLowPriorityEvent();
+    }
+
+    // Insert based on priority if enabled
+    if (this.priorityEnabled) {
+      this.insertByPriority(event);
+    } else {
+      this.queue.push(event);
+    }
+
+    // Persist to storage
+    if (this.persistenceEnabled) {
+      this.persistEvents();
+    }
+
+    // Track queue metrics
+    trackPerformanceMetric('amplitude_queue_size', this.queue.length, 'count');
+
+    // Trigger immediate processing for critical events
+    if (priority === 'critical') {
+      this.processQueue();
+    } else {
+      // Normal processing
+      this.scheduleProcessing();
+    }
+
+    return event.id;
+  }
+
+  private generateEventId(): string {
+    return `${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private insertByPriority(event: QueuedEvent): void {
+    const priorityOrder = { critical: 0, high: 1, normal: 2, low: 3 };
+    const eventPriority = priorityOrder[event.priority];
+
+    let insertIndex = this.queue.length;
+    for (let i = 0; i < this.queue.length; i++) {
+      const queuePriority = priorityOrder[this.queue[i].priority];
+      if (eventPriority < queuePriority) {
+        insertIndex = i;
+        break;
+      }
+    }
+
+    this.queue.splice(insertIndex, 0, event);
+  }
+
+  private removeOldestLowPriorityEvent(): void {
+    // Find and remove the oldest low priority event
+    for (let i = this.queue.length - 1; i >= 0; i--) {
+      if (this.queue[i].priority === 'low') {
+        this.queue.splice(i, 1);
+        return;
+      }
+    }
+
+    // If no low priority events, remove oldest normal priority
+    for (let i = this.queue.length - 1; i >= 0; i--) {
+      if (this.queue[i].priority === 'normal') {
+        this.queue.splice(i, 1);
+        return;
+      }
+    }
+
+    // Fallback: remove oldest event
+    if (this.queue.length > 0) {
+      this.queue.shift();
+    }
+  }
+
+  private scheduleProcessing(): void {
+    // Don't schedule if already processing or if queue is small
+    if (this.isProcessing || this.queue.length < this.batchSize) {
+      return;
+    }
+
+    // Use setTimeout for immediate processing to avoid blocking
+    setTimeout(() => this.processQueue(), 0);
+  }
+
+  private startFlushTimer(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    this.flushTimer = setInterval(() => this.processQueue(true), this.flushInterval);
+  }
+
+  private stopFlushTimer(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+
+  private async processQueue(forceFlush = false): Promise<void> {
+    if (this.isProcessing) return;
+
+    // Don't process if offline (will be handled by online listener)
+    if (!navigator.onLine && !forceFlush) return;
+
+    // Don't process small queues unless forced
+    if (this.queue.length === 0 || (this.queue.length < this.batchSize && !forceFlush)) {
+      return;
+    }
+
+    this.isProcessing = true;
+    const startTime = Date.now();
+
+    try {
+      // Take events to process (prioritize critical/high priority)
+      const eventsToSend = this.selectEventsForBatch();
+      
+      if (eventsToSend.length === 0) {
+        return;
+      }
+
+      // Remove from queue before sending
+      this.removeEventsFromQueue(eventsToSend.map(e => e.id));
+
+      // Send batch
+      await this.sendBatchCallback(eventsToSend);
+
+      // Track successful batch
+      trackPerformanceMetric('amplitude_batch_sent', eventsToSend.length, 'count');
+      trackPerformanceMetric('amplitude_batch_latency', Date.now() - startTime, 'ms');
+
+      console.debug(`[Event Queue] Successfully sent ${eventsToSend.length} events`);
+
+    } catch (error) {
+      console.error('[Event Queue] Failed to send event batch:', error);
+      
+      // Re-queue events that failed, with retry logic
+      const failedEvents = this.queue.splice(-this.batchSize); // Get last batch that was attempted
+      await this.handleFailedEvents(failedEvents);
+
+      // Track failed batch
+      trackPerformanceMetric('amplitude_batch_error', 1, 'count');
+      
+    } finally {
+      this.isProcessing = false;
+      
+      // Update persisted events
+      if (this.persistenceEnabled) {
+        this.persistEvents();
+      }
+
+      // Continue processing if there are more events
+      if (this.queue.length > 0) {
+        setTimeout(() => this.processQueue(), 100);
+      }
+    }
+  }
+
+  private selectEventsForBatch(): QueuedEvent[] {
+    const batch: QueuedEvent[] = [];
+    const criticalAndHigh = this.queue.filter(e => e.priority === 'critical' || e.priority === 'high');
+    
+    // Prioritize critical and high priority events
+    if (criticalAndHigh.length > 0) {
+      batch.push(...criticalAndHigh.slice(0, this.batchSize));
+    }
+
+    // Fill remaining space with normal/low priority events
+    const remaining = this.batchSize - batch.length;
+    if (remaining > 0) {
+      const normalAndLow = this.queue.filter(e => e.priority === 'normal' || e.priority === 'low');
+      batch.push(...normalAndLow.slice(0, remaining));
+    }
+
+    return batch;
+  }
+
+  private removeEventsFromQueue(eventIds: string[]): void {
+    this.queue = this.queue.filter(event => !eventIds.includes(event.id));
+  }
+
+  private async handleFailedEvents(failedEvents: QueuedEvent[]): Promise<void> {
+    for (const event of failedEvents) {
+      event.retries += 1;
+
+      if (event.retries < this.maxRetries) {
+        // Calculate exponential backoff delay
+        const delay = this.retryDelayMs * Math.pow(2, event.retries - 1);
+        
+        setTimeout(() => {
+          // Re-add to queue with priority adjustment
+          const adjustedPriority = event.retries >= 2 ? 'low' : event.priority;
+          this.queue.unshift({ ...event, priority: adjustedPriority });
+          
+          if (this.persistenceEnabled) {
+            this.persistEvents();
+          }
+        }, delay);
+        
+        console.debug(`[Event Queue] Retrying event ${event.id} in ${delay}ms (attempt ${event.retries})`);
+      } else {
+        console.warn(`[Event Queue] Discarding event ${event.id} after ${this.maxRetries} retries`);
+        trackPerformanceMetric('amplitude_event_discarded', 1, 'count');
+      }
+    }
+  }
+
+  private loadPersistedEvents(): void {
+    if (!this.persistenceEnabled || typeof localStorage === 'undefined') return;
+
+    try {
+      const stored = localStorage.getItem(this.storageKey);
+      if (stored) {
+        const events = JSON.parse(stored) as QueuedEvent[];
+        this.queue = events.filter(event => {
+          // Remove very old events (older than 24 hours)
+          return Date.now() - event.timestamp < 24 * 60 * 60 * 1000;
+        });
+        console.debug(`[Event Queue] Loaded ${this.queue.length} persisted events`);
+      }
+    } catch (error) {
+      console.warn('[Event Queue] Failed to load persisted events:', error);
+      // Clear corrupted storage
+      localStorage.removeItem(this.storageKey);
+    }
+  }
+
+  private persistEvents(): void {
+    if (!this.persistenceEnabled || typeof localStorage === 'undefined') return;
+
+    try {
+      // Only persist recent events to avoid storage bloat
+      const recentEvents = this.queue.filter(event => 
+        Date.now() - event.timestamp < 12 * 60 * 60 * 1000 // 12 hours
+      );
+      localStorage.setItem(this.storageKey, JSON.stringify(recentEvents));
+    } catch (error) {
+      console.warn('[Event Queue] Failed to persist events:', error);
+    }
+  }
+
+  private setupOnlineListener(): void {
+    if (typeof window === 'undefined') return;
+
+    const handleOnline = () => {
+      console.debug('[Event Queue] Connection restored, processing queued events');
+      if (this.queue.length > 0) {
+        setTimeout(() => this.processQueue(true), 1000); // Give connection a moment to stabilize
+      }
+    };
+
+    const handleOffline = () => {
+      console.debug('[Event Queue] Connection lost, events will be queued');
+    };
+
+    window.addEventListener('online', handleOnline);
+    window.addEventListener('offline', handleOffline);
+  }
+
+  public getQueueSize(): number {
+    return this.queue.length;
+  }
+
+  public getQueueStats(): {
+    total: number;
+    byPriority: Record<string, number>;
+    oldestTimestamp: number | null;
+    averageAge: number;
+  } {
+    const byPriority = { critical: 0, high: 0, normal: 0, low: 0 };
+    let oldestTimestamp: number | null = null;
+    let totalAge = 0;
+
+    for (const event of this.queue) {
+      byPriority[event.priority]++;
+      if (!oldestTimestamp || event.timestamp < oldestTimestamp) {
+        oldestTimestamp = event.timestamp;
+      }
+      totalAge += Date.now() - event.timestamp;
+    }
+
+    return {
+      total: this.queue.length,
+      byPriority,
+      oldestTimestamp,
+      averageAge: this.queue.length > 0 ? totalAge / this.queue.length : 0,
+    };
+  }
+
+  public clear(): void {
+    this.queue = [];
+    if (this.persistenceEnabled && typeof localStorage !== 'undefined') {
+      localStorage.removeItem(this.storageKey);
+    }
+    trackPerformanceMetric('amplitude_queue_cleared', 1, 'count');
+  }
+
+  public shutdown(): void {
+    this.stopFlushTimer();
+    
+    // Attempt to send any remaining critical events
+    const criticalEvents = this.queue.filter(e => e.priority === 'critical');
+    if (criticalEvents.length > 0) {
+      console.debug(`[Event Queue] Flushing ${criticalEvents.length} critical events before shutdown`);
+      // Fire and forget - don't wait for completion
+      this.sendBatchCallback(criticalEvents).catch(error => 
+        console.warn('[Event Queue] Failed to send critical events during shutdown:', error)
+      );
+    }
+
+    // Persist remaining events
+    if (this.persistenceEnabled) {
+      this.persistEvents();
+    }
+
+    console.debug('[Event Queue] Shutdown complete');
+  }
+}
+