@loamly/tracker 2.1.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loamly/tracker",
-  "version": "2.1.1",
+  "version": "2.4.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",

package/src/behavioral/form-tracker.ts

@@ -13,6 +13,14 @@
  * @module @loamly/tracker
  */
 
+// LOA-482: Form field data (privacy-safe)
+export interface FormFieldData {
+  name: string
+  type: string
+  // Value is included only for non-sensitive fields, truncated for privacy
+  value?: string
+}
+
 export interface FormEvent {
   event_type: 'form_start' | 'form_field' | 'form_submit' | 'form_success'
   form_id: string
@@ -22,6 +30,10 @@ export interface FormEvent {
   time_to_submit_ms?: number
   is_conversion?: boolean
   submit_source?: 'submit' | 'click' | 'thank_you'
+  // LOA-482: Captured form field data (privacy-safe)
+  fields?: FormFieldData[]
+  // LOA-482: Extracted email if found in form
+  email_submitted?: string
 }
 
 export interface FormTrackerConfig {
@@ -31,6 +43,10 @@ export interface FormTrackerConfig {
   trackableFields: string[]
   // Patterns for thank-you page detection
   thankYouPatterns: RegExp[]
+  // LOA-482: Whether to capture form field values on submission
+  captureFieldValues: boolean
+  // LOA-482: Maximum length for field values (truncate for privacy)
+  maxFieldValueLength: number
   // Callback for form events
   onFormEvent?: (event: FormEvent) => void
 }
@@ -41,10 +57,12 @@ const DEFAULT_CONFIG: FormTrackerConfig = {
     'credit', 'card', 'cvv', 'cvc',
     'ssn', 'social',
     'secret', 'token', 'key',
+    'pin', 'security', 'answer',
   ],
   trackableFields: [
     'email', 'name', 'phone', 'company',
     'first', 'last', 'city', 'country',
+    'domain', 'website', 'url', 'organization',
   ],
   thankYouPatterns: [
     /thank[-_]?you/i,
@@ -53,6 +71,9 @@ const DEFAULT_CONFIG: FormTrackerConfig = {
     /submitted/i,
     /complete/i,
   ],
+  // LOA-482: Enable field value capture by default
+  captureFieldValues: true,
+  maxFieldValueLength: 200,
 }
 
 export class FormTracker {
@@ -146,6 +167,9 @@ export class FormTracker {
 
     const formId = this.getFormId(form)
     const startTime = this.formStartTimes.get(formId)
+    
+    // LOA-482: Capture form field values with privacy sanitization
+    const { fields, emailSubmitted } = this.captureFormFields(form)
 
     this.emitEvent({
       event_type: 'form_submit',
@@ -154,18 +178,93 @@ export class FormTracker {
       time_to_submit_ms: startTime ? Date.now() - startTime : undefined,
       is_conversion: true,
       submit_source: 'submit',
+      fields: fields.length > 0 ? fields : undefined,
+      email_submitted: emailSubmitted,
     })
   }
+  
+  /**
+   * LOA-482: Capture form field values with privacy-safe sanitization
+   * - Never captures sensitive fields (password, credit card, etc.)
+   * - Truncates values to maxFieldValueLength
+   * - Extracts email if found
+   */
+  private captureFormFields(form: HTMLFormElement): { fields: FormFieldData[], emailSubmitted?: string } {
+    const fields: FormFieldData[] = []
+    let emailSubmitted: string | undefined
+    
+    if (!this.config.captureFieldValues) {
+      return { fields, emailSubmitted }
+    }
+    
+    try {
+      const formData = new FormData(form)
+      
+      for (const [name, value] of formData.entries()) {
+        // Skip sensitive fields entirely
+        if (this.isSensitiveField(name)) {
+          continue
+        }
+        
+        // Get the input element to determine type
+        const input = form.elements.namedItem(name) as HTMLInputElement | null
+        const inputType = input?.type || 'text'
+        
+        // Skip file inputs
+        if (inputType === 'file' || value instanceof File) {
+          continue
+        }
+        
+        const stringValue = String(value)
+        
+        // Check for email field
+        if (this.isEmailField(name, stringValue)) {
+          emailSubmitted = stringValue.substring(0, 254) // Max email length
+        }
+        
+        // Truncate value for privacy
+        const truncatedValue = stringValue.length > this.config.maxFieldValueLength
+          ? stringValue.substring(0, this.config.maxFieldValueLength) + '...'
+          : stringValue
+        
+        fields.push({
+          name: this.sanitizeFieldName(name),
+          type: inputType,
+          value: truncatedValue,
+        })
+      }
+    } catch (err) {
+      // Silent fail - don't break form submission
+      console.warn('[Loamly] Failed to capture form fields:', err)
+    }
+    
+    return { fields, emailSubmitted }
+  }
+  
+  /**
+   * Check if a field contains an email
+   */
+  private isEmailField(fieldName: string, value: string): boolean {
+    const lowerName = fieldName.toLowerCase()
+    // Check if field name suggests email
+    const isEmailName = lowerName.includes('email') || lowerName === 'e-mail'
+    // Simple email validation regex
+    const isEmailValue = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+    return isEmailName && isEmailValue
+  }
 
   private handleClick = (e: Event): void => {
     const target = e.target as HTMLElement
     
     // Check for HubSpot submit button
     if (target.closest('.hs-button') || target.closest('[type="submit"]')) {
-      const form = target.closest('form')
+      const form = target.closest('form') as HTMLFormElement | null
       if (form && form.classList.contains('hs-form')) {
         const formId = this.getFormId(form)
         const startTime = this.formStartTimes.get(formId)
+        
+        // LOA-482: Capture form field values for HubSpot forms
+        const { fields, emailSubmitted } = this.captureFormFields(form)
 
         this.emitEvent({
           event_type: 'form_submit',
@@ -174,6 +273,8 @@ export class FormTracker {
           time_to_submit_ms: startTime ? Date.now() - startTime : undefined,
           is_conversion: true,
           submit_source: 'click',
+          fields: fields.length > 0 ? fields : undefined,
+          email_submitted: emailSubmitted,
         })
       }
     }

package/src/config.ts

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

package/src/core.ts

@@ -17,44 +17,44 @@
  * @module @loamly/tracker
  */
 
-import { VERSION, DEFAULT_CONFIG } from './config'
-import { detectNavigationType } from './detection/navigation-timing'
-import { detectAIFromReferrer, detectAIFromUTM } from './detection/referrer'
-import { 
-  BehavioralClassifier, 
-  type BehavioralClassificationResult 
+import { FormTracker, type FormEvent } from './behavioral/form-tracker'
+import { ScrollTracker, type ScrollEvent } from './behavioral/scroll-tracker'
+import { TimeTracker, type TimeEvent } from './behavioral/time-tracker'
+import { DEFAULT_CONFIG, VERSION } from './config'
+import {
+    AgenticBrowserAnalyzer,
+    type AgenticDetectionResult
+} from './detection/agentic-browser'
+import {
+    BehavioralClassifier,
+    type BehavioralClassificationResult
 } from './detection/behavioral-classifier'
 import {
-  FocusBlurAnalyzer,
-  type FocusBlurResult
+    FocusBlurAnalyzer,
+    type FocusBlurResult
 } from './detection/focus-blur'
-import {
-  AgenticBrowserAnalyzer,
-  type AgenticDetectionResult
-} from './detection/agentic-browser'
+import { detectNavigationType } from './detection/navigation-timing'
+import { detectAIFromReferrer, detectAIFromUTM } from './detection/referrer'
 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, 
-  extractUTMParams, 
-  truncateText,
-  safeFetch,
-  sendBeacon 
-} from './utils'
-import type { 
-  LoamlyConfig, 
-  LoamlyTracker, 
-  TrackEventOptions, 
-  NavigationTiming,
-  AIDetectionResult,
-  BehavioralMLResult,
-  FocusBlurMLResult
+import type {
+    AIDetectionResult,
+    BehavioralMLResult,
+    FocusBlurMLResult,
+    LoamlyConfig,
+    LoamlyTracker,
+    NavigationTiming,
+    TrackEventOptions
 } from './types'
+import {
+    extractUTMParams,
+    getSessionId,
+    getVisitorId,
+    safeFetch,
+    sendBeacon,
+    truncateText
+} from './utils'
 
 // State
 let config: LoamlyConfig & { apiHost: string } = { apiHost: DEFAULT_CONFIG.apiHost }
@@ -423,6 +423,9 @@ function setupAdvancedBehavioralTracking(features: FeatureFlags): void {
           submit_source: submitSource,
           is_inferred: isSuccessEvent,
           time_to_submit_seconds: event.time_to_submit_ms ? Math.round(event.time_to_submit_ms / 1000) : null,
+          // LOA-482: Include captured form field values
+          fields: event.fields || null,
+          email_submitted: event.email_submitted || null,
         })
       },
     })
@@ -1037,20 +1040,59 @@ function setDebug(enabled: boolean): void {
   log('Debug mode:', enabled ? 'enabled' : 'disabled')
 }
 
+/**
+ * Track a behavioral event (for use by secondary modules/plugins)
+ * 
+ * This is the recommended way for secondary tracking modules to send events.
+ * It automatically includes workspace_id, visitor_id, session_id, and handles
+ * batching, queueing, and retry logic.
+ * 
+ * @param eventType - The type of event (e.g., 'outbound_click', 'button_click')
+ * @param eventData - Additional data for the event
+ * 
+ * @example
+ * ```js
+ * Loamly.trackBehavioral('outbound_click', {
+ *   url: 'https://example.com',
+ *   text: 'Click here',
+ *   hostname: 'example.com'
+ * });
+ * ```
+ */
+function trackBehavioral(eventType: string, eventData: Record<string, unknown>): void {
+  if (!initialized) {
+    log('Not initialized, trackBehavioral skipped:', eventType)
+    return
+  }
+  queueEvent(eventType, eventData)
+}
+
+/**
+ * Get the current workspace ID
+ * For internal use by secondary modules
+ */
+function getCurrentWorkspaceId(): string | null {
+  return workspaceId
+}
+
 /**
  * The Loamly Tracker instance
  */
 export const loamly: LoamlyTracker & { 
   getAgentic: () => AgenticDetectionResult | null 
   reportHealth: (status: 'initialized' | 'error' | 'ready', errorMessage?: string) => void
+  trackBehavioral: (eventType: string, eventData: Record<string, unknown>) => void
+  getWorkspaceId: () => string | null
 } = {
   init,
   pageview,
   track,
+  trackBehavioral,  // NEW: For secondary modules/plugins
   conversion,
   identify,
   getSessionId: getCurrentSessionId,
   getVisitorId: getCurrentVisitorId,
+  getWorkspaceId: getCurrentWorkspaceId,  // NEW: For debugging/introspection
   getAIDetection: getAIDetectionResult,
   getNavigationTiming: getNavigationTimingResult,
   getBehavioralML: getBehavioralMLResult,

package/src/types.ts

@@ -129,6 +129,23 @@ export interface LoamlyTracker {
   /** Track a custom event */
   track: (eventName: string, options?: TrackEventOptions) => void
   
+  /**
+   * Track a behavioral event (for secondary modules/plugins)
+   * 
+   * This is the recommended way for secondary tracking modules to send events.
+   * It automatically includes workspace_id, visitor_id, session_id, and handles
+   * batching, queueing, and retry logic.
+   * 
+   * @example
+   * ```js
+   * Loamly.trackBehavioral('outbound_click', {
+   *   url: 'https://example.com',
+   *   text: 'Click here'
+   * });
+   * ```
+   */
+  trackBehavioral: (eventType: string, eventData: Record<string, unknown>) => void
+  
   /** Track a conversion/revenue event */
   conversion: (eventName: string, revenue: number, currency?: string) => void
   
@@ -141,6 +158,9 @@ export interface LoamlyTracker {
   /** Get the current visitor ID */
   getVisitorId: () => string | null
   
+  /** Get the current workspace ID */
+  getWorkspaceId: () => string | null
+  
   /** Get AI detection result for current page */
   getAIDetection: () => AIDetectionResult | null