@loamly/tracker 1.8.0 → 2.0.0

package/src/core.ts

@@ -1,7 +1,18 @@
 /**
  * Loamly Tracker Core
  * 
- * Cookie-free, privacy-first analytics with AI traffic detection.
+ * Cookie-free, privacy-first analytics with comprehensive AI traffic detection.
+ * 
+ * Features:
+ * - Navigation Timing API (paste vs click detection)
+ * - Behavioral ML Classifier (mouse, scroll, interaction patterns)
+ * - Focus/Blur Sequence Analysis (copy-paste detection)
+ * - Agentic Browser Detection (Comet, CDP, teleporting clicks)
+ * - Advanced Scroll Tracking (30% chunk reporting)
+ * - Universal Form Tracking (HubSpot, Typeform, native)
+ * - SPA Navigation Support (History API hooks)
+ * - Event Queue with Retry (offline support)
+ * - Real-time Ping (heartbeat)
  * 
  * @module @loamly/tracker
  */
@@ -17,6 +28,16 @@ import {
   FocusBlurAnalyzer,
   type FocusBlurResult
 } from './detection/focus-blur'
+import {
+  AgenticBrowserAnalyzer,
+  type AgenticDetectionResult
+} from './detection/agentic-browser'
+import { EventQueue } from './infrastructure/event-queue'
+import { PingService } from './infrastructure/ping'
+import { ScrollTracker, type ScrollEvent } from './behavioral/scroll-tracker'
+import { TimeTracker, type TimeEvent } from './behavioral/time-tracker'
+import { FormTracker, type FormEvent } from './behavioral/form-tracker'
+import { SPARouter, type NavigationEvent } from './spa/router'
 import { 
   getVisitorId, 
   getSessionId, 
@@ -41,13 +62,27 @@ let initialized = false
 let debugMode = false
 let visitorId: string | null = null
 let sessionId: string | null = null
-let sessionStartTime: number | null = null
 let navigationTiming: NavigationTiming | null = null
 let aiDetection: AIDetectionResult | null = null
+
+// Detection modules
 let behavioralClassifier: BehavioralClassifier | null = null
 let behavioralMLResult: BehavioralMLResult | null = null
 let focusBlurAnalyzer: FocusBlurAnalyzer | null = null
 let focusBlurResult: FocusBlurMLResult | null = null
+let agenticAnalyzer: AgenticBrowserAnalyzer | null = null
+
+// Infrastructure modules
+let eventQueue: EventQueue | null = null
+let pingService: PingService | null = null
+
+// Behavioral tracking modules
+let scrollTracker: ScrollTracker | null = null
+let timeTracker: TimeTracker | null = null
+let formTracker: FormTracker | null = null
+
+// SPA navigation
+let spaRouter: SPARouter | null = null
 
 /**
  * Debug logger
@@ -91,14 +126,19 @@ function init(userConfig: LoamlyConfig = {}): void {
   // Get/create session
   const session = getSessionId()
   sessionId = session.sessionId
-  sessionStartTime = Date.now()
   log('Session ID:', sessionId, session.isNew ? '(new)' : '(existing)')
   
+  // Initialize event queue with batching
+  eventQueue = new EventQueue(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
+    batchSize: DEFAULT_CONFIG.batchSize,
+    batchTimeout: DEFAULT_CONFIG.batchTimeout,
+  })
+  
   // Detect navigation timing (paste vs click)
   navigationTiming = detectNavigationType()
   log('Navigation timing:', navigationTiming)
   
-  // Detect AI from referrer
+  // Detect AI from referrer/UTM
   aiDetection = detectAIFromReferrer(document.referrer) || detectAIFromUTM(window.location.href)
   if (aiDetection) {
     log('AI detected:', aiDetection)
@@ -113,7 +153,7 @@ function init(userConfig: LoamlyConfig = {}): void {
   
   // Set up behavioral tracking unless disabled
   if (!userConfig.disableBehavioral) {
-    setupBehavioralTracking()
+    setupAdvancedBehavioralTracking()
   }
   
   // Initialize behavioral ML classifier (LOA-180)
@@ -132,9 +172,214 @@ function init(userConfig: LoamlyConfig = {}): void {
     }
   }, 5000)
   
+  // Initialize agentic browser detection (LOA-187)
+  agenticAnalyzer = new AgenticBrowserAnalyzer()
+  agenticAnalyzer.init()
+  
+  // Set up ping service
+  if (visitorId && sessionId) {
+    pingService = new PingService(sessionId, visitorId, VERSION, {
+      interval: DEFAULT_CONFIG.pingInterval,
+      endpoint: endpoint(DEFAULT_CONFIG.endpoints.ping),
+    })
+    pingService.start()
+  }
+  
+  // Set up SPA navigation tracking
+  spaRouter = new SPARouter({
+    onNavigate: handleSPANavigation,
+  })
+  spaRouter.start()
+  
+  // Set up unload handlers
+  setupUnloadHandlers()
+  
   log('Initialization complete')
 }
 
+/**
+ * Set up advanced behavioral tracking with new modules
+ */
+function setupAdvancedBehavioralTracking(): void {
+  // Scroll tracker with 30% chunks
+  scrollTracker = new ScrollTracker({
+    chunks: [30, 60, 90, 100],
+    onChunkReached: (event: ScrollEvent) => {
+      log('Scroll chunk:', event.chunk)
+      queueEvent('scroll_depth', {
+        depth: event.depth,
+        chunk: event.chunk,
+        time_to_reach_ms: event.time_to_reach_ms,
+      })
+    },
+  })
+  scrollTracker.start()
+  
+  // Time tracker
+  timeTracker = new TimeTracker({
+    updateIntervalMs: 10000, // Report every 10 seconds
+    onUpdate: (event: TimeEvent) => {
+      if (event.active_time_ms >= DEFAULT_CONFIG.timeSpentThresholdMs) {
+        queueEvent('time_spent', {
+          active_time_ms: event.active_time_ms,
+          total_time_ms: event.total_time_ms,
+          idle_time_ms: event.idle_time_ms,
+          is_engaged: event.is_engaged,
+        })
+      }
+    },
+  })
+  timeTracker.start()
+  
+  // Form tracker with universal support
+  formTracker = new FormTracker({
+    onFormEvent: (event: FormEvent) => {
+      log('Form event:', event.event_type, event.form_id)
+      queueEvent(event.event_type, {
+        form_id: event.form_id,
+        form_type: event.form_type,
+        field_name: event.field_name,
+        field_type: event.field_type,
+        time_to_submit_ms: event.time_to_submit_ms,
+        is_conversion: event.is_conversion,
+      })
+    },
+  })
+  formTracker.start()
+  
+  // Click tracking for links (basic)
+  document.addEventListener('click', (e) => {
+    const target = e.target as HTMLElement
+    const link = target.closest('a')
+    
+    if (link && link.href) {
+      const isExternal = link.hostname !== window.location.hostname
+      queueEvent('click', {
+        element: 'link',
+        href: truncateText(link.href, 200),
+        text: truncateText(link.textContent || '', 100),
+        is_external: isExternal,
+      })
+    }
+  })
+}
+
+/**
+ * Queue an event for batched sending
+ */
+function queueEvent(eventType: string, data: Record<string, unknown>): void {
+  if (!eventQueue) return
+  
+  eventQueue.push(eventType, {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    event_type: eventType,
+    ...data,
+    url: window.location.href,
+    timestamp: new Date().toISOString(),
+    tracker_version: VERSION,
+  })
+}
+
+/**
+ * Handle SPA navigation
+ */
+function handleSPANavigation(event: NavigationEvent): void {
+  log('SPA navigation:', event.navigation_type, event.to_url)
+  
+  // Flush pending events before navigation
+  eventQueue?.flush()
+  
+  // Update ping service
+  pingService?.updateScrollDepth(0)
+  
+  // Reset scroll tracker for new page
+  scrollTracker?.stop()
+  scrollTracker = new ScrollTracker({
+    chunks: [30, 60, 90, 100],
+    onChunkReached: (scrollEvent: ScrollEvent) => {
+      queueEvent('scroll_depth', {
+        depth: scrollEvent.depth,
+        chunk: scrollEvent.chunk,
+        time_to_reach_ms: scrollEvent.time_to_reach_ms,
+      })
+    },
+  })
+  scrollTracker.start()
+  
+  // Track the virtual pageview
+  pageview(event.to_url)
+  
+  // Queue navigation event
+  queueEvent('spa_navigation', {
+    from_url: event.from_url,
+    to_url: event.to_url,
+    navigation_type: event.navigation_type,
+    time_on_previous_page_ms: event.time_on_previous_page_ms,
+  })
+}
+
+/**
+ * Set up handlers for page unload
+ */
+function setupUnloadHandlers(): void {
+  const handleUnload = (): void => {
+    // Get final scroll depth
+    const scrollEvent = scrollTracker?.getFinalEvent()
+    if (scrollEvent) {
+      sendBeacon(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
+        visitor_id: visitorId,
+        session_id: sessionId,
+        event_type: 'scroll_depth_final',
+        data: scrollEvent,
+        url: window.location.href,
+      })
+    }
+    
+    // Get final time metrics
+    const timeEvent = timeTracker?.getFinalMetrics()
+    if (timeEvent) {
+      sendBeacon(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
+        visitor_id: visitorId,
+        session_id: sessionId,
+        event_type: 'time_spent_final',
+        data: timeEvent,
+        url: window.location.href,
+      })
+    }
+    
+    // Get agentic detection result
+    const agenticResult = agenticAnalyzer?.getResult()
+    if (agenticResult && agenticResult.agenticProbability > 0) {
+      sendBeacon(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
+        visitor_id: visitorId,
+        session_id: sessionId,
+        event_type: 'agentic_detection',
+        data: agenticResult,
+        url: window.location.href,
+      })
+    }
+    
+    // Flush event queue
+    eventQueue?.flushBeacon()
+    
+    // Force classify behavioral ML if not done
+    if (behavioralClassifier && !behavioralClassifier.hasClassified()) {
+      const result = behavioralClassifier.forceClassify()
+      if (result) {
+        handleBehavioralClassification(result)
+      }
+    }
+  }
+  
+  window.addEventListener('beforeunload', handleUnload)
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') {
+      handleUnload()
+    }
+  })
+}
+
 /**
  * Track a page view
  */
@@ -238,143 +483,8 @@ function identify(userId: string, traits: Record<string, unknown> = {}): void {
   })
 }
 
-/**
- * Set up behavioral tracking (scroll, time spent, etc.)
- */
-function setupBehavioralTracking(): void {
-  let maxScrollDepth = 0
-  let lastScrollUpdate = 0
-  let lastTimeUpdate = Date.now()
-
-  // Scroll tracking with requestAnimationFrame throttling
-  let scrollTicking = false
-  
-  window.addEventListener('scroll', () => {
-    if (!scrollTicking) {
-      requestAnimationFrame(() => {
-        const scrollPercent = Math.round(
-          ((window.scrollY + window.innerHeight) / document.documentElement.scrollHeight) * 100
-        )
-        
-        if (scrollPercent > maxScrollDepth) {
-          maxScrollDepth = scrollPercent
-          
-          // Report at milestones (25%, 50%, 75%, 100%)
-          const milestones = [25, 50, 75, 100]
-          for (const milestone of milestones) {
-            if (scrollPercent >= milestone && lastScrollUpdate < milestone) {
-              lastScrollUpdate = milestone
-              sendBehavioralEvent('scroll_depth', { depth: milestone })
-            }
-          }
-        }
-        
-        scrollTicking = false
-      })
-      scrollTicking = true
-    }
-  })
-
-  // Time spent tracking (every 5 seconds minimum)
-  const trackTimeSpent = (): void => {
-    const now = Date.now()
-    const delta = now - lastTimeUpdate
-    
-    if (delta >= DEFAULT_CONFIG.timeSpentThresholdMs) {
-      lastTimeUpdate = now
-      sendBehavioralEvent('time_spent', { 
-        seconds: Math.round(delta / 1000),
-        total_seconds: Math.round((now - (sessionStartTime || now)) / 1000)
-      })
-    }
-  }
-
-  // Track on visibility change
-  document.addEventListener('visibilitychange', () => {
-    if (document.visibilityState === 'hidden') {
-      trackTimeSpent()
-    }
-  })
-
-  // Track on page unload
-  window.addEventListener('beforeunload', () => {
-    trackTimeSpent()
-    
-    // Send final scroll depth
-    if (maxScrollDepth > 0) {
-      sendBeacon(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
-        visitor_id: visitorId,
-        session_id: sessionId,
-        event_type: 'scroll_depth_final',
-        data: { depth: maxScrollDepth },
-        url: window.location.href,
-      })
-    }
-  })
-
-  // Form interaction tracking
-  document.addEventListener('focusin', (e) => {
-    const target = e.target as HTMLElement
-    if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.tagName === 'SELECT') {
-      sendBehavioralEvent('form_focus', {
-        field_type: target.tagName.toLowerCase(),
-        field_name: (target as HTMLInputElement).name || (target as HTMLInputElement).id || 'unknown',
-      })
-    }
-  })
-
-  // Form submit tracking
-  document.addEventListener('submit', (e) => {
-    const form = e.target as HTMLFormElement
-    sendBehavioralEvent('form_submit', {
-      form_id: form.id || form.name || 'unknown',
-      form_action: form.action ? new URL(form.action).pathname : 'unknown',
-    })
-  })
-
-  // Click tracking for links
-  document.addEventListener('click', (e) => {
-    const target = e.target as HTMLElement
-    const link = target.closest('a')
-    
-    if (link && link.href) {
-      const isExternal = link.hostname !== window.location.hostname
-      sendBehavioralEvent('click', {
-        element: 'link',
-        href: truncateText(link.href, 200),
-        text: truncateText(link.textContent || '', 100),
-        is_external: isExternal,
-      })
-    }
-  })
-}
-
-/**
- * Send a behavioral event
- */
-function sendBehavioralEvent(eventType: string, data: Record<string, unknown>): void {
-  const payload = {
-    visitor_id: visitorId,
-    session_id: sessionId,
-    event_type: eventType,
-    data,
-    url: window.location.href,
-    timestamp: new Date().toISOString(),
-    tracker_version: VERSION,
-  }
-
-  log('Behavioral:', eventType, data)
-
-  safeFetch(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(payload),
-  })
-}
-
 /**
  * Set up behavioral ML signal collection (LOA-180)
- * Collects mouse, scroll, and interaction signals for Naive Bayes classification
  */
 function setupBehavioralMLTracking(): void {
   if (!behavioralClassifier) return
@@ -427,16 +537,6 @@ function setupBehavioralMLTracking(): void {
     }
   }, { passive: true })
   
-  // Force classification on page unload
-  window.addEventListener('beforeunload', () => {
-    if (behavioralClassifier && !behavioralClassifier.hasClassified()) {
-      const result = behavioralClassifier.forceClassify()
-      if (result) {
-        handleBehavioralClassification(result)
-      }
-    }
-  })
-  
   // Also try to classify after 30 seconds as backup
   setTimeout(() => {
     if (behavioralClassifier && !behavioralClassifier.hasClassified()) {
@@ -462,7 +562,7 @@ function handleBehavioralClassification(result: BehavioralClassificationResult):
   }
   
   // Send to backend
-  sendBehavioralEvent('ml_classification', {
+  queueEvent('ml_classification', {
     classification: result.classification,
     human_probability: result.humanProbability,
     ai_probability: result.aiProbability,
@@ -500,7 +600,7 @@ function handleFocusBlurAnalysis(result: FocusBlurResult): void {
   }
   
   // Send to backend
-  sendBehavioralEvent('focus_blur_analysis', {
+  queueEvent('focus_blur_analysis', {
     nav_type: result.nav_type,
     confidence: result.confidence,
     signals: result.signals,
@@ -564,6 +664,13 @@ function getFocusBlurResult(): FocusBlurMLResult | null {
   return focusBlurResult
 }
 
+/**
+ * Get agentic browser detection result
+ */
+function getAgenticResult(): AgenticDetectionResult | null {
+  return agenticAnalyzer?.getResult() || null
+}
+
 /**
  * Check if initialized
  */
@@ -576,16 +683,32 @@ function isTrackerInitialized(): boolean {
  */
 function reset(): void {
   log('Resetting tracker')
+  
+  // Stop all services
+  pingService?.stop()
+  scrollTracker?.stop()
+  timeTracker?.stop()
+  formTracker?.stop()
+  spaRouter?.stop()
+  agenticAnalyzer?.destroy()
+  
+  // Reset state
   initialized = false
   visitorId = null
   sessionId = null
-  sessionStartTime = null
   navigationTiming = null
   aiDetection = null
   behavioralClassifier = null
   behavioralMLResult = null
   focusBlurAnalyzer = null
   focusBlurResult = null
+  agenticAnalyzer = null
+  eventQueue = null
+  pingService = null
+  scrollTracker = null
+  timeTracker = null
+  formTracker = null
+  spaRouter = null
   
   try {
     sessionStorage.removeItem('loamly_session')
@@ -606,7 +729,7 @@ function setDebug(enabled: boolean): void {
 /**
  * The Loamly Tracker instance
  */
-export const loamly: LoamlyTracker = {
+export const loamly: LoamlyTracker & { getAgentic: () => AgenticDetectionResult | null } = {
   init,
   pageview,
   track,
@@ -618,11 +741,10 @@ export const loamly: LoamlyTracker = {
   getNavigationTiming: getNavigationTimingResult,
   getBehavioralML: getBehavioralMLResult,
   getFocusBlur: getFocusBlurResult,
+  getAgentic: getAgenticResult,
   isInitialized: isTrackerInitialized,
   reset,
   debug: setDebug,
 }
 
 export default loamly
-
-