@loamly/tracker 2.1.0 → 2.4.0

package/src/index.ts

@@ -5,7 +5,7 @@
  * See what AI tells your customers — and track when they click.
  * 
  * @module @loamly/tracker
- * @version 1.8.0
+ * @version 2.1.0
  * @license MIT
  * @see https://github.com/loamly/loamly
  * @see https://loamly.ai

package/src/infrastructure/event-queue.ts

@@ -16,6 +16,7 @@ export interface QueuedEvent {
   id: string
   type: string
   payload: Record<string, unknown>
+  headers?: Record<string, string>
   timestamp: number
   retries: number
 }
@@ -26,6 +27,7 @@ interface EventQueueConfig {
   maxRetries: number
   retryDelayMs: number
   storageKey: string
+  apiKey?: string
 }
 
 const DEFAULT_QUEUE_CONFIG: EventQueueConfig = {
@@ -52,11 +54,12 @@ export class EventQueue {
   /**
    * Add event to queue
    */
-  push(type: string, payload: Record<string, unknown>): void {
+  push(type: string, payload: Record<string, unknown>, headers?: Record<string, string>): void {
     const event: QueuedEvent = {
       id: this.generateId(),
       type,
       payload,
+      headers,
       timestamp: Date.now(),
       retries: 0,
     }
@@ -92,24 +95,31 @@ export class EventQueue {
   flushBeacon(): boolean {
     if (this.queue.length === 0) return true
 
-    const events = this.queue.map(e => ({
-      type: e.type,
-      ...e.payload,
-      _queue_id: e.id,
-      _queue_timestamp: e.timestamp,
-    }))
+    const baseUrl = this.config.apiKey
+      ? `${this.endpoint}?api_key=${encodeURIComponent(this.config.apiKey)}`
+      : this.endpoint
 
-    const success = navigator.sendBeacon?.(
-      this.endpoint,
-      JSON.stringify({ events, beacon: true })
-    ) ?? false
+    let allSent = true
+    for (const event of this.queue) {
+      const payload = {
+        ...event.payload,
+        _queue_id: event.id,
+        _queue_timestamp: event.timestamp,
+      }
 
-    if (success) {
+      const success = navigator.sendBeacon?.(baseUrl, JSON.stringify(payload)) ?? false
+      if (!success) {
+        allSent = false
+        break
+      }
+    }
+
+    if (allSent) {
       this.queue = []
       this.clearStorage()
     }
 
-    return success
+    return allSent
   }
 
   /**
@@ -145,28 +155,44 @@ export class EventQueue {
   private async sendBatch(events: QueuedEvent[]): Promise<void> {
     if (events.length === 0) return
 
-    const payload = {
-      events: events.map(e => ({
-        type: e.type,
-        ...e.payload,
-        _queue_id: e.id,
-        _queue_timestamp: e.timestamp,
-      })),
-      batch: true,
-    }
-
     try {
-      const response = await fetch(this.endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(payload),
-      })
-
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}`)
+      const results = await Promise.allSettled(
+        events.map(async (event) => {
+          const response = await fetch(this.endpoint, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              ...(event.headers || {}),
+            },
+            body: JSON.stringify({
+              ...event.payload,
+              _queue_id: event.id,
+              _queue_timestamp: event.timestamp,
+            }),
+          })
+
+          if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`)
+          }
+        })
+      )
+
+      const failedEvents = events.filter((_, index) => results[index]?.status === 'rejected')
+      if (failedEvents.length > 0) {
+        // Retry failed events only
+        for (const event of failedEvents) {
+          if (event.retries < this.config.maxRetries) {
+            event.retries++
+            this.queue.push(event)
+          }
+        }
+        // Schedule retry with exponential backoff
+        const delay = this.config.retryDelayMs * Math.pow(2, failedEvents[0].retries - 1)
+        setTimeout(() => this.flush(), delay)
       }
+      return
     } catch (error) {
-      // Retry failed events
+      // Retry all events if we hit an unexpected error
       for (const event of events) {
         if (event.retries < this.config.maxRetries) {
           event.retries++

package/src/infrastructure/ping.ts

@@ -32,6 +32,7 @@ export class PingService {
   private config: PingConfig
   private pageLoadTime: number
   private isVisible = true
+  private isFocused = true
   private currentScrollDepth = 0
   private sessionId: string
   private visitorId: string
@@ -47,6 +48,8 @@ export class PingService {
     this.visitorId = visitorId
     this.version = version
     this.pageLoadTime = Date.now()
+    this.isVisible = document.visibilityState === 'visible'
+    this.isFocused = typeof document.hasFocus === 'function' ? document.hasFocus() : true
     this.config = {
       interval: DEFAULT_CONFIG.pingInterval,
       endpoint: '',
@@ -55,6 +58,8 @@ export class PingService {
 
     // Track visibility
     document.addEventListener('visibilitychange', this.handleVisibilityChange)
+    window.addEventListener('focus', this.handleFocusChange)
+    window.addEventListener('blur', this.handleFocusChange)
     
     // Track scroll depth
     window.addEventListener('scroll', this.handleScroll, { passive: true })
@@ -67,13 +72,15 @@ export class PingService {
     if (this.intervalId) return
 
     this.intervalId = setInterval(() => {
-      if (this.isVisible) {
+      if (this.isVisible && this.isFocused) {
         this.ping()
       }
     }, this.config.interval)
 
     // Send initial ping
-    this.ping()
+    if (this.isVisible && this.isFocused) {
+      this.ping()
+    }
   }
 
   /**
@@ -86,6 +93,8 @@ export class PingService {
     }
 
     document.removeEventListener('visibilitychange', this.handleVisibilityChange)
+    window.removeEventListener('focus', this.handleFocusChange)
+    window.removeEventListener('blur', this.handleFocusChange)
     window.removeEventListener('scroll', this.handleScroll)
   }
 
@@ -108,7 +117,7 @@ export class PingService {
       url: window.location.href,
       time_on_page_ms: Date.now() - this.pageLoadTime,
       scroll_depth: this.currentScrollDepth,
-      is_active: this.isVisible,
+      is_active: this.isVisible && this.isFocused,
       tracker_version: this.version,
     }
   }
@@ -137,6 +146,13 @@ export class PingService {
     this.isVisible = document.visibilityState === 'visible'
   }
 
+  private handleFocusChange = (): void => {
+    this.isFocused = typeof document.hasFocus === 'function' ? document.hasFocus() : true
+    if (this.intervalId && this.isVisible && this.isFocused) {
+      this.ping()
+    }
+  }
+
   private handleScroll = (): void => {
     const scrollPercent = Math.round(
       ((window.scrollY + window.innerHeight) / document.documentElement.scrollHeight) * 100

package/src/types.ts

@@ -6,6 +6,9 @@
 export interface LoamlyConfig {
   /** Your Loamly API key (found in dashboard) */
   apiKey?: string
+
+  /** Workspace ID (required when using public tracker key) */
+  workspaceId?: string
   
   /** Custom API host (default: https://app.loamly.ai) */
   apiHost?: string
@@ -126,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
   
@@ -138,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