@loamly/tracker 1.6.0

package/src/core.ts

@@ -0,0 +1,428 @@
+/**
+ * Loamly Tracker Core
+ * 
+ * Cookie-free, privacy-first analytics with AI traffic detection.
+ * 
+ * @module @loamly/tracker
+ */
+
+import { VERSION, DEFAULT_CONFIG } from './config'
+import { detectNavigationType } from './detection/navigation-timing'
+import { detectAIFromReferrer, detectAIFromUTM } from './detection/referrer'
+import { 
+  getVisitorId, 
+  getSessionId, 
+  extractUTMParams, 
+  truncateText,
+  safeFetch,
+  sendBeacon 
+} from './utils'
+import type { 
+  LoamlyConfig, 
+  LoamlyTracker, 
+  TrackEventOptions, 
+  NavigationTiming,
+  AIDetectionResult 
+} from './types'
+
+// State
+let config: LoamlyConfig & { apiHost: string } = { apiHost: DEFAULT_CONFIG.apiHost }
+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
+
+/**
+ * Debug logger
+ */
+function log(...args: unknown[]): void {
+  if (debugMode) {
+    console.log('[Loamly]', ...args)
+  }
+}
+
+/**
+ * Build API endpoint URL
+ */
+function endpoint(path: string): string {
+  return `${config.apiHost}${path}`
+}
+
+/**
+ * Initialize the tracker
+ */
+function init(userConfig: LoamlyConfig = {}): void {
+  if (initialized) {
+    log('Already initialized')
+    return
+  }
+
+  config = {
+    ...config,
+    ...userConfig,
+    apiHost: userConfig.apiHost || DEFAULT_CONFIG.apiHost,
+  }
+  
+  debugMode = userConfig.debug ?? false
+  
+  log('Initializing Loamly Tracker v' + VERSION)
+  
+  // Get/create visitor ID
+  visitorId = getVisitorId()
+  log('Visitor ID:', visitorId)
+  
+  // Get/create session
+  const session = getSessionId()
+  sessionId = session.sessionId
+  sessionStartTime = Date.now()
+  log('Session ID:', sessionId, session.isNew ? '(new)' : '(existing)')
+  
+  // Detect navigation timing (paste vs click)
+  navigationTiming = detectNavigationType()
+  log('Navigation timing:', navigationTiming)
+  
+  // Detect AI from referrer
+  aiDetection = detectAIFromReferrer(document.referrer) || detectAIFromUTM(window.location.href)
+  if (aiDetection) {
+    log('AI detected:', aiDetection)
+  }
+  
+  initialized = true
+  
+  // Auto pageview unless disabled
+  if (!userConfig.disableAutoPageview) {
+    pageview()
+  }
+  
+  // Set up behavioral tracking unless disabled
+  if (!userConfig.disableBehavioral) {
+    setupBehavioralTracking()
+  }
+  
+  log('Initialization complete')
+}
+
+/**
+ * Track a page view
+ */
+function pageview(customUrl?: string): void {
+  if (!initialized) {
+    log('Not initialized, call init() first')
+    return
+  }
+
+  const url = customUrl || window.location.href
+  const payload = {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    url,
+    referrer: document.referrer || null,
+    title: document.title || null,
+    utm_source: extractUTMParams(url).utm_source || null,
+    utm_medium: extractUTMParams(url).utm_medium || null,
+    utm_campaign: extractUTMParams(url).utm_campaign || null,
+    user_agent: navigator.userAgent,
+    screen_width: window.screen?.width,
+    screen_height: window.screen?.height,
+    language: navigator.language,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    tracker_version: VERSION,
+    navigation_timing: navigationTiming,
+    ai_platform: aiDetection?.platform || null,
+    is_ai_referrer: aiDetection?.isAI || false,
+  }
+
+  log('Pageview:', payload)
+
+  safeFetch(endpoint(DEFAULT_CONFIG.endpoints.visit), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  })
+}
+
+/**
+ * Track a custom event
+ */
+function track(eventName: string, options: TrackEventOptions = {}): void {
+  if (!initialized) {
+    log('Not initialized, call init() first')
+    return
+  }
+
+  const payload = {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    event_name: eventName,
+    event_type: 'custom',
+    properties: options.properties || {},
+    revenue: options.revenue,
+    currency: options.currency || 'USD',
+    url: window.location.href,
+    timestamp: new Date().toISOString(),
+    tracker_version: VERSION,
+  }
+
+  log('Event:', eventName, payload)
+
+  safeFetch(endpoint('/api/ingest/event'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  })
+}
+
+/**
+ * Track a conversion/revenue event
+ */
+function conversion(eventName: string, revenue: number, currency = 'USD'): void {
+  track(eventName, { revenue, currency, properties: { type: 'conversion' } })
+}
+
+/**
+ * Identify a user
+ */
+function identify(userId: string, traits: Record<string, unknown> = {}): void {
+  if (!initialized) {
+    log('Not initialized, call init() first')
+    return
+  }
+
+  log('Identify:', userId, traits)
+
+  const payload = {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    user_id: userId,
+    traits,
+    timestamp: new Date().toISOString(),
+  }
+
+  safeFetch(endpoint('/api/ingest/identify'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  })
+}
+
+/**
+ * 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),
+  })
+}
+
+/**
+ * Get current session ID
+ */
+function getCurrentSessionId(): string | null {
+  return sessionId
+}
+
+/**
+ * Get current visitor ID
+ */
+function getCurrentVisitorId(): string | null {
+  return visitorId
+}
+
+/**
+ * Get AI detection result
+ */
+function getAIDetectionResult(): AIDetectionResult | null {
+  return aiDetection
+}
+
+/**
+ * Get navigation timing result
+ */
+function getNavigationTimingResult(): NavigationTiming | null {
+  return navigationTiming
+}
+
+/**
+ * Check if initialized
+ */
+function isTrackerInitialized(): boolean {
+  return initialized
+}
+
+/**
+ * Reset the tracker
+ */
+function reset(): void {
+  log('Resetting tracker')
+  initialized = false
+  visitorId = null
+  sessionId = null
+  sessionStartTime = null
+  navigationTiming = null
+  aiDetection = null
+  
+  try {
+    sessionStorage.removeItem('loamly_session')
+    sessionStorage.removeItem('loamly_start')
+  } catch {
+    // Ignore
+  }
+}
+
+/**
+ * Enable/disable debug mode
+ */
+function setDebug(enabled: boolean): void {
+  debugMode = enabled
+  log('Debug mode:', enabled ? 'enabled' : 'disabled')
+}
+
+/**
+ * The Loamly Tracker instance
+ */
+export const loamly: LoamlyTracker = {
+  init,
+  pageview,
+  track,
+  conversion,
+  identify,
+  getSessionId: getCurrentSessionId,
+  getVisitorId: getCurrentVisitorId,
+  getAIDetection: getAIDetectionResult,
+  getNavigationTiming: getNavigationTimingResult,
+  isInitialized: isTrackerInitialized,
+  reset,
+  debug: setDebug,
+}
+
+export default loamly
+
+

package/src/detection/index.ts

@@ -0,0 +1,13 @@
+/**
+ * AI Traffic Detection Module
+ * 
+ * Revolutionary methods for detecting "dark" AI traffic that
+ * traditional analytics miss.
+ * 
+ * @module @loamly/tracker/detection
+ */
+
+export { detectNavigationType } from './navigation-timing'
+export { detectAIFromReferrer, detectAIFromUTM } from './referrer'
+
+

package/src/detection/navigation-timing.ts

@@ -0,0 +1,117 @@
+/**
+ * Navigation Timing API Detection
+ * 
+ * Detects whether the user arrived via paste (from AI chat) vs click
+ * by analyzing Navigation Timing API patterns.
+ * 
+ * @module @loamly/tracker/detection
+ */
+
+import type { NavigationTiming } from '../types'
+
+/**
+ * Analyze Navigation Timing API to detect paste vs click navigation
+ * 
+ * When users paste a URL (common after copying from AI chat), 
+ * the timing patterns are distinctive:
+ * 1. fetchStart is virtually immediate after navigationStart
+ * 2. DNS/connect times are often 0 (cached or direct)
+ * 3. No redirect chain
+ * 4. Uniform timing patterns
+ * 
+ * @returns NavigationTiming result with type and confidence
+ */
+export function detectNavigationType(): NavigationTiming {
+  try {
+    const entries = performance.getEntriesByType('navigation') as PerformanceNavigationTiming[]
+    
+    if (!entries || entries.length === 0) {
+      return { nav_type: 'unknown', confidence: 0, signals: ['no_timing_data'] }
+    }
+
+    const nav = entries[0]
+    const signals: string[] = []
+    let pasteScore = 0
+
+    // Signal 1: fetchStart delta from navigationStart
+    // Paste navigation typically has very small delta (< 5ms)
+    const fetchStartDelta = nav.fetchStart - nav.startTime
+    if (fetchStartDelta < 5) {
+      pasteScore += 0.25
+      signals.push('instant_fetch_start')
+    } else if (fetchStartDelta < 20) {
+      pasteScore += 0.15
+      signals.push('fast_fetch_start')
+    }
+
+    // Signal 2: DNS lookup time
+    // Paste = likely 0 (direct URL entry, no link warmup)
+    const dnsTime = nav.domainLookupEnd - nav.domainLookupStart
+    if (dnsTime === 0) {
+      pasteScore += 0.15
+      signals.push('no_dns_lookup')
+    }
+
+    // Signal 3: TCP connect time
+    // Paste = likely 0 (no preconnect from previous page)
+    const connectTime = nav.connectEnd - nav.connectStart
+    if (connectTime === 0) {
+      pasteScore += 0.15
+      signals.push('no_tcp_connect')
+    }
+
+    // Signal 4: No redirects
+    // Paste URLs are typically direct, no redirects
+    if (nav.redirectCount === 0) {
+      pasteScore += 0.1
+      signals.push('no_redirects')
+    }
+
+    // Signal 5: Timing uniformity check
+    // Paste navigation tends to have more uniform patterns
+    const timingVariance = calculateTimingVariance(nav)
+    if (timingVariance < 10) {
+      pasteScore += 0.15
+      signals.push('uniform_timing')
+    }
+
+    // Signal 6: No referrer (common for paste)
+    if (!document.referrer || document.referrer === '') {
+      pasteScore += 0.1
+      signals.push('no_referrer')
+    }
+
+    // Determine navigation type based on score
+    const confidence = Math.min(pasteScore, 1)
+    const nav_type = pasteScore >= 0.5 ? 'likely_paste' : 'likely_click'
+
+    return {
+      nav_type,
+      confidence: Math.round(confidence * 1000) / 1000,
+      signals,
+    }
+  } catch {
+    return { nav_type: 'unknown', confidence: 0, signals: ['detection_error'] }
+  }
+}
+
+/**
+ * Calculate timing variance to detect paste patterns
+ */
+function calculateTimingVariance(nav: PerformanceNavigationTiming): number {
+  const timings = [
+    nav.fetchStart - nav.startTime,
+    nav.domainLookupEnd - nav.domainLookupStart,
+    nav.connectEnd - nav.connectStart,
+    nav.responseStart - nav.requestStart,
+  ].filter((t) => t >= 0)
+
+  if (timings.length === 0) return 100
+
+  const mean = timings.reduce((a, b) => a + b, 0) / timings.length
+  const variance = timings.reduce((sum, t) => sum + Math.pow(t - mean, 2), 0) / timings.length
+  
+  return Math.sqrt(variance)
+}
+
+

package/src/detection/referrer.ts

@@ -0,0 +1,98 @@
+/**
+ * Referrer-based AI Detection
+ * 
+ * Detects when users arrive from known AI platforms
+ * based on the document.referrer header.
+ * 
+ * @module @loamly/tracker/detection
+ */
+
+import { AI_PLATFORMS } from '../config'
+import type { AIDetectionResult } from '../types'
+
+/**
+ * Detect AI platform from referrer URL
+ * 
+ * @param referrer - The document.referrer value
+ * @returns AI detection result or null if no AI detected
+ */
+export function detectAIFromReferrer(referrer: string): AIDetectionResult | null {
+  if (!referrer) {
+    return null
+  }
+
+  try {
+    const url = new URL(referrer)
+    const hostname = url.hostname.toLowerCase()
+
+    // Check against known AI platforms
+    for (const [pattern, platform] of Object.entries(AI_PLATFORMS)) {
+      if (hostname.includes(pattern) || referrer.includes(pattern)) {
+        return {
+          isAI: true,
+          platform,
+          confidence: 0.95, // High confidence when referrer matches
+          method: 'referrer',
+        }
+      }
+    }
+
+    return null
+  } catch {
+    // Invalid URL, try pattern matching on raw string
+    for (const [pattern, platform] of Object.entries(AI_PLATFORMS)) {
+      if (referrer.toLowerCase().includes(pattern.toLowerCase())) {
+        return {
+          isAI: true,
+          platform,
+          confidence: 0.85,
+          method: 'referrer',
+        }
+      }
+    }
+    return null
+  }
+}
+
+/**
+ * Extract AI platform from UTM parameters
+ * 
+ * @param url - The current page URL
+ * @returns AI platform name or null
+ */
+export function detectAIFromUTM(url: string): AIDetectionResult | null {
+  try {
+    const params = new URL(url).searchParams
+    
+    // Check utm_source for AI platforms
+    const utmSource = params.get('utm_source')?.toLowerCase()
+    if (utmSource) {
+      for (const [pattern, platform] of Object.entries(AI_PLATFORMS)) {
+        if (utmSource.includes(pattern.split('.')[0])) {
+          return {
+            isAI: true,
+            platform,
+            confidence: 0.99, // Very high confidence from explicit UTM
+            method: 'referrer',
+          }
+        }
+      }
+      
+      // Generic AI source patterns
+      if (utmSource.includes('ai') || utmSource.includes('llm') || utmSource.includes('chatbot')) {
+        return {
+          isAI: true,
+          platform: utmSource,
+          confidence: 0.9,
+          method: 'referrer',
+        }
+      }
+    }
+
+    return null
+  } catch {
+    return null
+  }
+}
+
+

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Loamly Tracker
+ * 
+ * Open-source AI traffic detection for websites.
+ * See what AI tells your customers — and track when they click.
+ * 
+ * @module @loamly/tracker
+ * @license MIT
+ * @see https://loamly.ai
+ */
+
+// Core tracker
+export { loamly, loamly as default } from './core'
+
+// Types
+export type {
+  LoamlyConfig,
+  LoamlyTracker,
+  TrackEventOptions,
+  NavigationTiming,
+  AIDetectionResult,
+} from './types'
+
+// Detection utilities (for advanced usage)
+export { detectNavigationType } from './detection/navigation-timing'
+export { detectAIFromReferrer, detectAIFromUTM } from './detection/referrer'
+
+// Configuration
+export { VERSION, AI_PLATFORMS, AI_BOT_PATTERNS } from './config'
+
+