@loamly/tracker 2.0.1 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loamly/tracker",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "See every AI bot that visits your website. ChatGPT, Claude, Perplexity, Gemini — know when they crawl or refer traffic.",
   "author": "Loamly <hello@loamly.ai>",
   "license": "MIT",
@@ -46,6 +46,13 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
   "devDependencies": {
     "@types/node": "^20.10.0",
     "tsup": "^8.0.1",
@@ -55,12 +62,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "clean": "rm -rf dist"
   }
-}
+}
+
+

package/src/config.ts

@@ -6,7 +6,7 @@
  * @see https://github.com/loamly/loamly
  */
 
-export const VERSION = '2.0.1'
+export const VERSION = '2.1.0'
 
 export const DEFAULT_CONFIG = {
   apiHost: 'https://app.loamly.ai',

package/src/core.ts

@@ -117,7 +117,22 @@ function init(userConfig: LoamlyConfig = {}): void {
   
   debugMode = userConfig.debug ?? false
   
+  // Feature flags with defaults (all enabled except ping)
+  const features = {
+    scroll: true,
+    time: true,
+    forms: true,
+    spa: true,
+    behavioralML: true,
+    focusBlur: true,
+    agentic: true,
+    eventQueue: true,
+    ping: false, // Opt-in only
+    ...userConfig.features,
+  }
+  
   log('Initializing Loamly Tracker v' + VERSION)
+  log('Features:', features)
   
   // Get/create visitor ID
   visitorId = getVisitorId()
@@ -128,17 +143,19 @@ function init(userConfig: LoamlyConfig = {}): void {
   sessionId = session.sessionId
   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,
-  })
+  // Initialize event queue with batching (if enabled)
+  if (features.eventQueue) {
+    eventQueue = new EventQueue(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
+      batchSize: DEFAULT_CONFIG.batchSize,
+      batchTimeout: DEFAULT_CONFIG.batchTimeout,
+    })
+  }
   
-  // Detect navigation timing (paste vs click)
+  // Detect navigation timing (paste vs click) - always lightweight
   navigationTiming = detectNavigationType()
   log('Navigation timing:', navigationTiming)
   
-  // Detect AI from referrer/UTM
+  // Detect AI from referrer/UTM - always lightweight
   aiDetection = detectAIFromReferrer(document.referrer) || detectAIFromUTM(window.location.href)
   if (aiDetection) {
     log('AI detected:', aiDetection)
@@ -151,33 +168,39 @@ function init(userConfig: LoamlyConfig = {}): void {
     pageview()
   }
   
-  // Set up behavioral tracking unless disabled
+  // Set up behavioral tracking (scroll, time, forms) unless disabled
   if (!userConfig.disableBehavioral) {
-    setupAdvancedBehavioralTracking()
+    setupAdvancedBehavioralTracking(features)
   }
   
-  // Initialize behavioral ML classifier (LOA-180)
-  behavioralClassifier = new BehavioralClassifier(10000) // 10s min session
-  behavioralClassifier.setOnClassify(handleBehavioralClassification)
-  setupBehavioralMLTracking()
-  
-  // Initialize focus/blur analyzer (LOA-182)
-  focusBlurAnalyzer = new FocusBlurAnalyzer()
-  focusBlurAnalyzer.initTracking()
+  // Initialize behavioral ML classifier (LOA-180) - if enabled
+  if (features.behavioralML) {
+    behavioralClassifier = new BehavioralClassifier(10000) // 10s min session
+    behavioralClassifier.setOnClassify(handleBehavioralClassification)
+    setupBehavioralMLTracking()
+  }
   
-  // Analyze focus/blur after 5 seconds
-  setTimeout(() => {
-    if (focusBlurAnalyzer) {
-      handleFocusBlurAnalysis(focusBlurAnalyzer.analyze())
-    }
-  }, 5000)
+  // Initialize focus/blur analyzer (LOA-182) - if enabled
+  if (features.focusBlur) {
+    focusBlurAnalyzer = new FocusBlurAnalyzer()
+    focusBlurAnalyzer.initTracking()
+    
+    // Analyze focus/blur after 5 seconds
+    setTimeout(() => {
+      if (focusBlurAnalyzer) {
+        handleFocusBlurAnalysis(focusBlurAnalyzer.analyze())
+      }
+    }, 5000)
+  }
   
-  // Initialize agentic browser detection (LOA-187)
-  agenticAnalyzer = new AgenticBrowserAnalyzer()
-  agenticAnalyzer.init()
+  // Initialize agentic browser detection (LOA-187) - if enabled
+  if (features.agentic) {
+    agenticAnalyzer = new AgenticBrowserAnalyzer()
+    agenticAnalyzer.init()
+  }
   
-  // Set up ping service
-  if (visitorId && sessionId) {
+  // Set up ping service - if enabled (opt-in)
+  if (features.ping && visitorId && sessionId) {
     pingService = new PingService(sessionId, visitorId, VERSION, {
       interval: DEFAULT_CONFIG.pingInterval,
       endpoint: endpoint(DEFAULT_CONFIG.endpoints.ping),
@@ -194,60 +217,92 @@ function init(userConfig: LoamlyConfig = {}): void {
   // Set up unload handlers
   setupUnloadHandlers()
   
+  // Report health status
+  reportHealth('initialized')
+  
   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()
+interface FeatureFlags {
+  scroll?: boolean
+  time?: boolean
+  forms?: boolean
+  spa?: boolean
+  behavioralML?: boolean
+  focusBlur?: boolean
+  agentic?: boolean
+  eventQueue?: boolean
+  ping?: boolean
+}
+
+function setupAdvancedBehavioralTracking(features: FeatureFlags): void {
+  // Scroll tracker with 30% chunks (if enabled)
+  if (features.scroll) {
+    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,
+  // Time tracker (if enabled)
+  if (features.time) {
+    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 (if enabled)
+  if (features.forms) {
+    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,
         })
-      }
-    },
-  })
-  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()
+      },
+    })
+    formTracker.start()
+  }
+  
+  // SPA router (if enabled)
+  if (features.spa) {
+    spaRouter = new SPARouter({
+      onNavigate: (event: NavigationEvent) => {
+        log('SPA navigation:', event.navigation_type)
+        pageview(event.to_url)
+      },
+    })
+    spaRouter.start()
+  }
   
-  // Click tracking for links (basic)
+  // Click tracking for links (always enabled, lightweight)
   document.addEventListener('click', (e) => {
     const target = e.target as HTMLElement
     const link = target.closest('a')
@@ -678,6 +733,50 @@ function isTrackerInitialized(): boolean {
   return initialized
 }
 
+/**
+ * Report tracker health status
+ * Used for monitoring and debugging
+ */
+function reportHealth(status: 'initialized' | 'error' | 'ready', errorMessage?: string): void {
+  if (!config.apiKey) return
+  
+  try {
+    const healthData = {
+      workspace_id: config.apiKey,
+      status,
+      error_message: errorMessage || null,
+      version: VERSION,
+      url: typeof window !== 'undefined' ? window.location.href : null,
+      user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : null,
+      timestamp: new Date().toISOString(),
+      features: {
+        scroll_tracker: !!scrollTracker,
+        time_tracker: !!timeTracker,
+        form_tracker: !!formTracker,
+        spa_router: !!spaRouter,
+        behavioral_ml: !!behavioralClassifier,
+        focus_blur: !!focusBlurAnalyzer,
+        agentic: !!agenticAnalyzer,
+        ping_service: !!pingService,
+        event_queue: !!eventQueue,
+      },
+    }
+    
+    // Fire and forget
+    safeFetch(endpoint(DEFAULT_CONFIG.endpoints.health), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(healthData),
+    }).catch(() => {
+      // Ignore health reporting errors
+    })
+    
+    log('Health reported:', status)
+  } catch {
+    // Ignore
+  }
+}
+
 /**
  * Reset the tracker
  */
@@ -729,7 +828,10 @@ function setDebug(enabled: boolean): void {
 /**
  * The Loamly Tracker instance
  */
-export const loamly: LoamlyTracker & { getAgentic: () => AgenticDetectionResult | null } = {
+export const loamly: LoamlyTracker & { 
+  getAgentic: () => AgenticDetectionResult | null 
+  reportHealth: (status: 'initialized' | 'error' | 'ready', errorMessage?: string) => void
+} = {
   init,
   pageview,
   track,
@@ -745,6 +847,7 @@ export const loamly: LoamlyTracker & { getAgentic: () => AgenticDetectionResult
   isInitialized: isTrackerInitialized,
   reset,
   debug: setDebug,
+  reportHealth,
 }
 
 export default loamly

package/src/types.ts

@@ -21,6 +21,31 @@ export interface LoamlyConfig {
   
   /** Custom session timeout in milliseconds (default: 30 minutes) */
   sessionTimeout?: number
+  
+  /**
+   * Feature flags for lightweight mode
+   * Set to false to reduce initialization overhead
+   */
+  features?: {
+    /** Scroll depth tracking (default: true) */
+    scroll?: boolean
+    /** Time on page tracking (default: true) */
+    time?: boolean
+    /** Form interaction tracking (default: true) */
+    forms?: boolean
+    /** SPA navigation support (default: true) */
+    spa?: boolean
+    /** Behavioral ML classification (default: true) */
+    behavioralML?: boolean
+    /** Focus/blur paste detection (default: true) */
+    focusBlur?: boolean
+    /** Agentic browser detection (default: true) */
+    agentic?: boolean
+    /** Event queue with retry (default: true) */
+    eventQueue?: boolean
+    /** Heartbeat ping service (default: false - opt-in) */
+    ping?: boolean
+  }
 }
 
 export interface TrackEventOptions {

package/LICENSE

@@ -1,23 +0,0 @@
-MIT License
-
-Copyright (c) 2025-present Loamly
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-