@loamly/tracker 1.7.0 → 1.8.0

package/src/detection/agentic-browser.ts

@@ -0,0 +1,328 @@
+/**
+ * Agentic Browser Detection
+ * 
+ * LOA-187: Detects AI agentic browsers like Perplexity Comet, ChatGPT Atlas,
+ * and other automated browsing agents.
+ * 
+ * Detection methods:
+ * - DOM fingerprinting (Perplexity Comet overlay)
+ * - Mouse movement patterns (teleporting clicks)
+ * - CDP (Chrome DevTools Protocol) automation fingerprint
+ * - navigator.webdriver detection
+ * 
+ * @module @loamly/tracker/detection/agentic-browser
+ * @license MIT
+ */
+
+/**
+ * Agentic detection result
+ */
+export interface AgenticDetectionResult {
+  /** Whether Perplexity Comet DOM element was detected */
+  cometDOMDetected: boolean
+  /** Whether CDP automation was detected */
+  cdpDetected: boolean
+  /** Mouse movement patterns */
+  mousePatterns: {
+    teleportingClicks: number
+    totalMovements: number
+  }
+  /** Overall agentic probability (0-1) */
+  agenticProbability: number
+  /** Detection signals */
+  signals: string[]
+}
+
+/**
+ * Perplexity Comet DOM Detector
+ * 
+ * Detects the Comet browser overlay stop button which is injected
+ * into the DOM when Comet is actively browsing.
+ */
+export class CometDetector {
+  private detected = false
+  private checkComplete = false
+  private observer: MutationObserver | null = null
+
+  /**
+   * Initialize detection
+   * @param timeout - Max time to observe for Comet DOM (default: 5s)
+   */
+  init(timeout = 5000): void {
+    if (typeof document === 'undefined') return
+
+    // Initial check
+    this.check()
+
+    if (!this.detected && document.body) {
+      // Observe for dynamic injection
+      this.observer = new MutationObserver(() => this.check())
+      this.observer.observe(document.body, { childList: true, subtree: true })
+
+      // Stop observing after timeout
+      setTimeout(() => {
+        if (this.observer && !this.detected) {
+          this.observer.disconnect()
+          this.observer = null
+          this.checkComplete = true
+        }
+      }, timeout)
+    }
+  }
+
+  private check(): void {
+    // Perplexity Comet injects an overlay with this class
+    if (document.querySelector('.pplx-agent-overlay-stop-button')) {
+      this.detected = true
+      this.checkComplete = true
+      if (this.observer) {
+        this.observer.disconnect()
+        this.observer = null
+      }
+    }
+  }
+
+  isDetected(): boolean {
+    return this.detected
+  }
+
+  isCheckComplete(): boolean {
+    return this.checkComplete
+  }
+
+  destroy(): void {
+    if (this.observer) {
+      this.observer.disconnect()
+      this.observer = null
+    }
+  }
+}
+
+/**
+ * Mouse Movement Analyzer
+ * 
+ * Detects unnatural mouse movements characteristic of automated browsers:
+ * - Teleporting clicks (instant large movements)
+ * - Perfect linear movements
+ * - No micro-adjustments
+ */
+export class MouseAnalyzer {
+  private lastX = -1
+  private lastY = -1
+  private teleportingClicks = 0
+  private totalMovements = 0
+  private readonly teleportThreshold: number
+
+  /**
+   * @param teleportThreshold - Distance in pixels to consider a teleport (default: 500)
+   */
+  constructor(teleportThreshold = 500) {
+    this.teleportThreshold = teleportThreshold
+  }
+
+  /**
+   * Initialize mouse tracking
+   */
+  init(): void {
+    if (typeof document === 'undefined') return
+
+    document.addEventListener('mousemove', this.handleMove, { passive: true })
+    document.addEventListener('mousedown', this.handleClick, { passive: true })
+  }
+
+  private handleMove = (e: MouseEvent): void => {
+    this.totalMovements++
+    this.lastX = e.clientX
+    this.lastY = e.clientY
+  }
+
+  private handleClick = (e: MouseEvent): void => {
+    if (this.lastX !== -1 && this.lastY !== -1) {
+      const dx = Math.abs(e.clientX - this.lastX)
+      const dy = Math.abs(e.clientY - this.lastY)
+
+      // Large instant movement before click = teleporting
+      if (dx > this.teleportThreshold || dy > this.teleportThreshold) {
+        this.teleportingClicks++
+      }
+    }
+    this.lastX = e.clientX
+    this.lastY = e.clientY
+  }
+
+  getPatterns(): { teleportingClicks: number; totalMovements: number } {
+    return {
+      teleportingClicks: this.teleportingClicks,
+      totalMovements: this.totalMovements,
+    }
+  }
+
+  destroy(): void {
+    if (typeof document === 'undefined') return
+    document.removeEventListener('mousemove', this.handleMove)
+    document.removeEventListener('mousedown', this.handleClick)
+  }
+}
+
+/**
+ * CDP (Chrome DevTools Protocol) Automation Detector
+ * 
+ * Detects headless browsers and automation tools:
+ * - navigator.webdriver (set by Selenium, Puppeteer, Playwright)
+ * - Chrome automation flags
+ * - Missing browser APIs
+ */
+export class CDPDetector {
+  private detected = false
+
+  /**
+   * Run detection checks
+   */
+  detect(): boolean {
+    if (typeof navigator === 'undefined') return false
+
+    // Check 1: navigator.webdriver (Chrome 76+, Firefox 60+)
+    // Set to true by automation frameworks
+    if ((navigator as Navigator & { webdriver?: boolean }).webdriver) {
+      this.detected = true
+      return true
+    }
+
+    // Check 2: Chrome automation extension (legacy check)
+    if (typeof window !== 'undefined') {
+      const win = window as Window & {
+        chrome?: { runtime?: unknown }
+        __webdriver_evaluate?: unknown
+        __selenium_evaluate?: unknown
+        __webdriver_script_function?: unknown
+        __webdriver_script_func?: unknown
+        __webdriver_script_fn?: unknown
+        __fxdriver_evaluate?: unknown
+        __driver_unwrapped?: unknown
+        __webdriver_unwrapped?: unknown
+        __driver_evaluate?: unknown
+        __selenium_unwrapped?: unknown
+        __fxdriver_unwrapped?: unknown
+      }
+
+      // Selenium/WebDriver fingerprints
+      const automationProps = [
+        '__webdriver_evaluate',
+        '__selenium_evaluate',
+        '__webdriver_script_function',
+        '__webdriver_script_func',
+        '__webdriver_script_fn',
+        '__fxdriver_evaluate',
+        '__driver_unwrapped',
+        '__webdriver_unwrapped',
+        '__driver_evaluate',
+        '__selenium_unwrapped',
+        '__fxdriver_unwrapped',
+      ]
+
+      for (const prop of automationProps) {
+        if (prop in win) {
+          this.detected = true
+          return true
+        }
+      }
+    }
+
+    return false
+  }
+
+  isDetected(): boolean {
+    return this.detected
+  }
+}
+
+/**
+ * Agentic Browser Analyzer
+ * 
+ * Combines all detection methods into a unified result.
+ */
+export class AgenticBrowserAnalyzer {
+  private cometDetector: CometDetector
+  private mouseAnalyzer: MouseAnalyzer
+  private cdpDetector: CDPDetector
+  private initialized = false
+
+  constructor() {
+    this.cometDetector = new CometDetector()
+    this.mouseAnalyzer = new MouseAnalyzer()
+    this.cdpDetector = new CDPDetector()
+  }
+
+  /**
+   * Initialize all detectors
+   */
+  init(): void {
+    if (this.initialized) return
+    this.initialized = true
+
+    this.cometDetector.init()
+    this.mouseAnalyzer.init()
+    this.cdpDetector.detect()
+  }
+
+  /**
+   * Get current detection result
+   */
+  getResult(): AgenticDetectionResult {
+    const signals: string[] = []
+    let probability = 0
+
+    // Comet detection (85% confidence)
+    if (this.cometDetector.isDetected()) {
+      signals.push('comet_dom_detected')
+      probability = Math.max(probability, 0.85)
+    }
+
+    // CDP detection (92% confidence)
+    if (this.cdpDetector.isDetected()) {
+      signals.push('cdp_detected')
+      probability = Math.max(probability, 0.92)
+    }
+
+    // Mouse patterns (78% confidence per teleport)
+    const mousePatterns = this.mouseAnalyzer.getPatterns()
+    if (mousePatterns.teleportingClicks > 0) {
+      signals.push(`teleporting_clicks:${mousePatterns.teleportingClicks}`)
+      probability = Math.max(probability, 0.78)
+    }
+
+    return {
+      cometDOMDetected: this.cometDetector.isDetected(),
+      cdpDetected: this.cdpDetector.isDetected(),
+      mousePatterns,
+      agenticProbability: probability,
+      signals,
+    }
+  }
+
+  /**
+   * Cleanup resources
+   */
+  destroy(): void {
+    this.cometDetector.destroy()
+    this.mouseAnalyzer.destroy()
+  }
+}
+
+/**
+ * Create and initialize an agentic browser analyzer
+ */
+export function createAgenticAnalyzer(): AgenticBrowserAnalyzer {
+  const analyzer = new AgenticBrowserAnalyzer()
+
+  if (typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', () => analyzer.init())
+    } else {
+      analyzer.init()
+    }
+  }
+
+  return analyzer
+}
+

package/src/detection/focus-blur.ts

@@ -0,0 +1,251 @@
+/**
+ * Focus/Blur Event Sequence Analysis
+ * 
+ * LOA-182: Detects paste vs click navigation patterns by analyzing
+ * the sequence of focus and blur events when a page loads.
+ * 
+ * Research: 55-65% accuracy (improves when combined with other signals)
+ * 
+ * @module @loamly/tracker/detection/focus-blur
+ */
+
+/**
+ * Focus/blur event record
+ */
+export interface FocusBlurEvent {
+  type: 'focus' | 'blur' | 'window_focus' | 'window_blur'
+  target: string
+  timestamp: number
+}
+
+/**
+ * Focus/blur analysis result
+ */
+export interface FocusBlurResult {
+  /** Navigation pattern type */
+  nav_type: 'likely_paste' | 'likely_click' | 'unknown'
+  /** Confidence score (0-1) */
+  confidence: number
+  /** Detection signals */
+  signals: string[]
+  /** Event sequence (last 10 events) */
+  sequence: FocusBlurEvent[]
+  /** Time from page load to first interaction */
+  time_to_first_interaction_ms: number | null
+}
+
+/**
+ * Focus/Blur Sequence Analyzer
+ * 
+ * Tracks focus and blur events to detect paste navigation patterns.
+ * Paste navigation typically shows:
+ * 1. Early window focus event
+ * 2. Body focus without prior link navigation
+ * 3. No referrer blur pattern
+ */
+export class FocusBlurAnalyzer {
+  private sequence: FocusBlurEvent[] = []
+  private pageLoadTime: number
+  private firstInteractionTime: number | null = null
+  private analyzed = false
+  private result: FocusBlurResult | null = null
+
+  constructor() {
+    this.pageLoadTime = performance.now()
+  }
+
+  /**
+   * Initialize event tracking
+   * Must be called after DOM is ready
+   */
+  initTracking(): void {
+    // Track focus events (use capturing phase to catch all events)
+    document.addEventListener('focus', (e) => {
+      this.recordEvent('focus', e.target as HTMLElement)
+    }, true)
+
+    document.addEventListener('blur', (e) => {
+      this.recordEvent('blur', e.target as HTMLElement)
+    }, true)
+
+    // Track window focus/blur
+    window.addEventListener('focus', () => {
+      this.recordEvent('window_focus', null)
+    })
+
+    window.addEventListener('blur', () => {
+      this.recordEvent('window_blur', null)
+    })
+
+    // Track first click/keypress as first interaction
+    const recordFirstInteraction = () => {
+      if (this.firstInteractionTime === null) {
+        this.firstInteractionTime = performance.now()
+      }
+    }
+    document.addEventListener('click', recordFirstInteraction, { once: true, passive: true })
+    document.addEventListener('keydown', recordFirstInteraction, { once: true, passive: true })
+  }
+
+  /**
+   * Record a focus/blur event
+   */
+  private recordEvent(type: FocusBlurEvent['type'], target: HTMLElement | null): void {
+    const event: FocusBlurEvent = {
+      type,
+      target: target?.tagName || 'WINDOW',
+      timestamp: performance.now()
+    }
+    
+    this.sequence.push(event)
+    
+    // Keep only last 20 events to limit memory
+    if (this.sequence.length > 20) {
+      this.sequence = this.sequence.slice(-20)
+    }
+  }
+
+  /**
+   * Analyze the focus/blur sequence for paste patterns
+   */
+  analyze(): FocusBlurResult {
+    if (this.analyzed && this.result) {
+      return this.result
+    }
+
+    const signals: string[] = []
+    let confidence = 0
+    
+    // Get early events (first 500ms after page load)
+    const earlyEvents = this.sequence.filter(e => e.timestamp < this.pageLoadTime + 500)
+    
+    // Pattern 1: Window focus as first event
+    const hasEarlyWindowFocus = earlyEvents.some(e => e.type === 'window_focus')
+    if (hasEarlyWindowFocus) {
+      signals.push('early_window_focus')
+      confidence += 0.15
+    }
+    
+    // Pattern 2: Body focus early (paste causes immediate body focus)
+    const hasEarlyBodyFocus = earlyEvents.some(
+      e => e.type === 'focus' && e.target === 'BODY'
+    )
+    if (hasEarlyBodyFocus) {
+      signals.push('early_body_focus')
+      confidence += 0.15
+    }
+    
+    // Pattern 3: No link/anchor focus (would indicate click navigation)
+    const hasLinkFocus = this.sequence.some(
+      e => e.type === 'focus' && e.target === 'A'
+    )
+    if (!hasLinkFocus) {
+      signals.push('no_link_focus')
+      confidence += 0.10
+    }
+    
+    // Pattern 4: First focus is on document/body (not a specific element)
+    const firstFocus = this.sequence.find(e => e.type === 'focus')
+    if (firstFocus && (firstFocus.target === 'BODY' || firstFocus.target === 'HTML')) {
+      signals.push('first_focus_body')
+      confidence += 0.10
+    }
+    
+    // Pattern 5: No rapid tab switching (common in human navigation)
+    const windowEvents = this.sequence.filter(
+      e => e.type === 'window_focus' || e.type === 'window_blur'
+    )
+    if (windowEvents.length <= 2) {
+      signals.push('minimal_window_switches')
+      confidence += 0.05
+    }
+    
+    // Pattern 6: Time to first interaction
+    // Paste users often have longer time before first interaction
+    // (reading content they copied from AI)
+    if (this.firstInteractionTime !== null) {
+      const timeToInteraction = this.firstInteractionTime - this.pageLoadTime
+      if (timeToInteraction > 3000) {
+        signals.push('delayed_first_interaction')
+        confidence += 0.10
+      }
+    }
+    
+    // Cap confidence based on research (55-65% accuracy)
+    confidence = Math.min(confidence, 0.65)
+    
+    // Determine navigation type
+    let navType: FocusBlurResult['nav_type']
+    if (confidence >= 0.35) {
+      navType = 'likely_paste'
+    } else if (signals.length === 0) {
+      navType = 'unknown'
+    } else {
+      navType = 'likely_click'
+    }
+    
+    this.result = {
+      nav_type: navType,
+      confidence,
+      signals,
+      sequence: this.sequence.slice(-10),
+      time_to_first_interaction_ms: this.firstInteractionTime 
+        ? Math.round(this.firstInteractionTime - this.pageLoadTime)
+        : null
+    }
+    
+    this.analyzed = true
+    return this.result
+  }
+
+  /**
+   * Get current result (analyze if not done)
+   */
+  getResult(): FocusBlurResult {
+    return this.analyze()
+  }
+
+  /**
+   * Check if analysis has been performed
+   */
+  hasAnalyzed(): boolean {
+    return this.analyzed
+  }
+
+  /**
+   * Get the raw sequence for debugging
+   */
+  getSequence(): FocusBlurEvent[] {
+    return [...this.sequence]
+  }
+
+  /**
+   * Reset the analyzer
+   */
+  reset(): void {
+    this.sequence = []
+    this.pageLoadTime = performance.now()
+    this.firstInteractionTime = null
+    this.analyzed = false
+    this.result = null
+  }
+}
+
+/**
+ * Create a new focus/blur analyzer
+ */
+export function createFocusBlurAnalyzer(): FocusBlurAnalyzer {
+  const analyzer = new FocusBlurAnalyzer()
+  
+  // Initialize tracking when DOM is ready
+  if (typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', () => analyzer.initTracking())
+    } else {
+      analyzer.initTracking()
+    }
+  }
+  
+  return analyzer
+}
+

package/src/detection/index.ts

@@ -5,6 +5,7 @@
  * traditional analytics miss.
  * 
  * @module @loamly/tracker/detection
+ * @license MIT
  */
 
 export { detectNavigationType } from './navigation-timing'
@@ -15,3 +16,17 @@ export {
   type BehavioralSignal,
   type BehavioralClassificationResult 
 } from './behavioral-classifier'
+export {
+  FocusBlurAnalyzer,
+  createFocusBlurAnalyzer,
+  type FocusBlurEvent,
+  type FocusBlurResult
+} from './focus-blur'
+export {
+  AgenticBrowserAnalyzer,
+  CometDetector,
+  MouseAnalyzer,
+  CDPDetector,
+  createAgenticAnalyzer,
+  type AgenticDetectionResult
+} from './agentic-browser'

package/src/index.ts

@@ -5,7 +5,9 @@
  * See what AI tells your customers — and track when they click.
  * 
  * @module @loamly/tracker
+ * @version 1.8.0
  * @license MIT
+ * @see https://github.com/loamly/loamly
  * @see https://loamly.ai
  */
 
@@ -24,6 +26,11 @@ export type {
 // Detection utilities (for advanced usage)
 export { detectNavigationType } from './detection/navigation-timing'
 export { detectAIFromReferrer, detectAIFromUTM } from './detection/referrer'
+export { 
+  AgenticBrowserAnalyzer,
+  createAgenticAnalyzer,
+  type AgenticDetectionResult
+} from './detection/agentic-browser'
 
 // Configuration
 export { VERSION, AI_PLATFORMS, AI_BOT_PATTERNS } from './config'

package/src/types.ts

@@ -77,6 +77,20 @@ export interface BehavioralMLResult {
   sessionDurationMs: number
 }
 
+/**
+ * Focus/Blur analysis result
+ */
+export interface FocusBlurMLResult {
+  /** Navigation pattern type */
+  navType: 'likely_paste' | 'likely_click' | 'unknown'
+  /** Confidence score (0-1) */
+  confidence: number
+  /** Detection signals */
+  signals: string[]
+  /** Time to first interaction in ms */
+  timeToFirstInteractionMs: number | null
+}
+
 export interface LoamlyTracker {
   /** Initialize the tracker with configuration */
   init: (config: LoamlyConfig) => void
@@ -108,6 +122,9 @@ export interface LoamlyTracker {
   /** Get behavioral ML classification result */
   getBehavioralML: () => BehavioralMLResult | null
   
+  /** Get focus/blur analysis result */
+  getFocusBlur: () => FocusBlurMLResult | null
+  
   /** Check if tracker is initialized */
   isInitialized: () => boolean