@loamly/tracker 1.8.0 → 2.0.0

package/src/infrastructure/event-queue.ts

@@ -0,0 +1,225 @@
+/**
+ * Event Queue with Batching, Retry & Persistence
+ * 
+ * Production-grade event delivery with:
+ * - Batch processing for network efficiency
+ * - Retry with exponential backoff
+ * - localStorage persistence for offline support
+ * - sendBeacon fallback for unload events
+ * 
+ * @module @loamly/tracker
+ */
+
+import { DEFAULT_CONFIG } from '../config'
+
+export interface QueuedEvent {
+  id: string
+  type: string
+  payload: Record<string, unknown>
+  timestamp: number
+  retries: number
+}
+
+interface EventQueueConfig {
+  batchSize: number
+  batchTimeout: number
+  maxRetries: number
+  retryDelayMs: number
+  storageKey: string
+}
+
+const DEFAULT_QUEUE_CONFIG: EventQueueConfig = {
+  batchSize: DEFAULT_CONFIG.batchSize,
+  batchTimeout: DEFAULT_CONFIG.batchTimeout,
+  maxRetries: 3,
+  retryDelayMs: 1000,
+  storageKey: '_loamly_queue',
+}
+
+export class EventQueue {
+  private queue: QueuedEvent[] = []
+  private batchTimer: ReturnType<typeof setTimeout> | null = null
+  private config: EventQueueConfig
+  private endpoint: string
+  private isFlushing = false
+
+  constructor(endpoint: string, config: Partial<EventQueueConfig> = {}) {
+    this.endpoint = endpoint
+    this.config = { ...DEFAULT_QUEUE_CONFIG, ...config }
+    this.loadFromStorage()
+  }
+
+  /**
+   * Add event to queue
+   */
+  push(type: string, payload: Record<string, unknown>): void {
+    const event: QueuedEvent = {
+      id: this.generateId(),
+      type,
+      payload,
+      timestamp: Date.now(),
+      retries: 0,
+    }
+
+    this.queue.push(event)
+    this.saveToStorage()
+    this.scheduleBatch()
+  }
+
+  /**
+   * Force flush all events immediately
+   */
+  async flush(): Promise<void> {
+    if (this.isFlushing || this.queue.length === 0) return
+
+    this.isFlushing = true
+    this.clearBatchTimer()
+
+    try {
+      const events = [...this.queue]
+      this.queue = []
+      
+      await this.sendBatch(events)
+    } finally {
+      this.isFlushing = false
+      this.saveToStorage()
+    }
+  }
+
+  /**
+   * Flush using sendBeacon (for unload events)
+   */
+  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 success = navigator.sendBeacon?.(
+      this.endpoint,
+      JSON.stringify({ events, beacon: true })
+    ) ?? false
+
+    if (success) {
+      this.queue = []
+      this.clearStorage()
+    }
+
+    return success
+  }
+
+  /**
+   * Get current queue length
+   */
+  get length(): number {
+    return this.queue.length
+  }
+
+  private scheduleBatch(): void {
+    if (this.batchTimer) return
+
+    // Flush immediately if batch size reached
+    if (this.queue.length >= this.config.batchSize) {
+      this.flush()
+      return
+    }
+
+    // Schedule batch flush
+    this.batchTimer = setTimeout(() => {
+      this.batchTimer = null
+      this.flush()
+    }, this.config.batchTimeout)
+  }
+
+  private clearBatchTimer(): void {
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer)
+      this.batchTimer = null
+    }
+  }
+
+  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}`)
+      }
+    } catch (error) {
+      // Retry failed events
+      for (const event of events) {
+        if (event.retries < this.config.maxRetries) {
+          event.retries++
+          this.queue.push(event)
+        }
+      }
+
+      // Schedule retry with exponential backoff
+      if (this.queue.length > 0) {
+        const delay = this.config.retryDelayMs * Math.pow(2, events[0].retries - 1)
+        setTimeout(() => this.flush(), delay)
+      }
+    }
+  }
+
+  private loadFromStorage(): void {
+    try {
+      const stored = localStorage.getItem(this.config.storageKey)
+      if (stored) {
+        const parsed = JSON.parse(stored)
+        if (Array.isArray(parsed)) {
+          // Only restore events less than 24 hours old
+          const cutoff = Date.now() - 24 * 60 * 60 * 1000
+          this.queue = parsed.filter((e: QueuedEvent) => e.timestamp > cutoff)
+        }
+      }
+    } catch {
+      // localStorage not available or corrupted
+    }
+  }
+
+  private saveToStorage(): void {
+    try {
+      if (this.queue.length > 0) {
+        localStorage.setItem(this.config.storageKey, JSON.stringify(this.queue))
+      } else {
+        this.clearStorage()
+      }
+    } catch {
+      // localStorage not available
+    }
+  }
+
+  private clearStorage(): void {
+    try {
+      localStorage.removeItem(this.config.storageKey)
+    } catch {
+      // Ignore
+    }
+  }
+
+  private generateId(): string {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+  }
+}
+

package/src/infrastructure/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Infrastructure Modules
+ * @module @loamly/tracker
+ */
+
+export { EventQueue, type QueuedEvent } from './event-queue'
+export { PingService, type PingData, type PingConfig } from './ping'
+

package/src/infrastructure/ping.ts

@@ -0,0 +1,149 @@
+/**
+ * Real-time Ping Service
+ * 
+ * Heartbeat for active session tracking with:
+ * - Configurable interval (default 30s)
+ * - Visibility-aware (pauses when tab hidden)
+ * - Session metrics aggregation
+ * 
+ * @module @loamly/tracker
+ */
+
+import { DEFAULT_CONFIG } from '../config'
+
+export interface PingData {
+  session_id: string
+  visitor_id: string
+  url: string
+  time_on_page_ms: number
+  scroll_depth: number
+  is_active: boolean
+  tracker_version: string
+}
+
+export interface PingConfig {
+  interval: number
+  endpoint: string
+  onPing?: (data: PingData) => void
+}
+
+export class PingService {
+  private intervalId: ReturnType<typeof setInterval> | null = null
+  private config: PingConfig
+  private pageLoadTime: number
+  private isVisible = true
+  private currentScrollDepth = 0
+  private sessionId: string
+  private visitorId: string
+  private version: string
+
+  constructor(
+    sessionId: string,
+    visitorId: string,
+    version: string,
+    config: Partial<PingConfig> = {}
+  ) {
+    this.sessionId = sessionId
+    this.visitorId = visitorId
+    this.version = version
+    this.pageLoadTime = Date.now()
+    this.config = {
+      interval: DEFAULT_CONFIG.pingInterval,
+      endpoint: '',
+      ...config,
+    }
+
+    // Track visibility
+    document.addEventListener('visibilitychange', this.handleVisibilityChange)
+    
+    // Track scroll depth
+    window.addEventListener('scroll', this.handleScroll, { passive: true })
+  }
+
+  /**
+   * Start the ping service
+   */
+  start(): void {
+    if (this.intervalId) return
+
+    this.intervalId = setInterval(() => {
+      if (this.isVisible) {
+        this.ping()
+      }
+    }, this.config.interval)
+
+    // Send initial ping
+    this.ping()
+  }
+
+  /**
+   * Stop the ping service
+   */
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId)
+      this.intervalId = null
+    }
+
+    document.removeEventListener('visibilitychange', this.handleVisibilityChange)
+    window.removeEventListener('scroll', this.handleScroll)
+  }
+
+  /**
+   * Update scroll depth (called by external scroll tracker)
+   */
+  updateScrollDepth(depth: number): void {
+    if (depth > this.currentScrollDepth) {
+      this.currentScrollDepth = depth
+    }
+  }
+
+  /**
+   * Get current ping data
+   */
+  getData(): PingData {
+    return {
+      session_id: this.sessionId,
+      visitor_id: this.visitorId,
+      url: window.location.href,
+      time_on_page_ms: Date.now() - this.pageLoadTime,
+      scroll_depth: this.currentScrollDepth,
+      is_active: this.isVisible,
+      tracker_version: this.version,
+    }
+  }
+
+  private ping = async (): Promise<void> => {
+    const data = this.getData()
+
+    // Call callback if provided
+    this.config.onPing?.(data)
+
+    // Send to endpoint if configured
+    if (this.config.endpoint) {
+      try {
+        await fetch(this.config.endpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(data),
+        })
+      } catch {
+        // Ping failures are silent
+      }
+    }
+  }
+
+  private handleVisibilityChange = (): void => {
+    this.isVisible = document.visibilityState === 'visible'
+  }
+
+  private handleScroll = (): void => {
+    const scrollPercent = Math.round(
+      ((window.scrollY + window.innerHeight) / document.documentElement.scrollHeight) * 100
+    )
+    if (scrollPercent > this.currentScrollDepth) {
+      this.currentScrollDepth = Math.min(scrollPercent, 100)
+    }
+  }
+}
+

package/src/spa/index.ts

@@ -0,0 +1,7 @@
+/**
+ * SPA Navigation Modules
+ * @module @loamly/tracker
+ */
+
+export { SPARouter, type NavigationEvent, type RouterConfig } from './router'
+

package/src/spa/router.ts

@@ -0,0 +1,147 @@
+/**
+ * SPA Navigation Router
+ * 
+ * Detects client-side navigation in SPAs with support for:
+ * - History API (pushState, replaceState, popstate)
+ * - Hash changes (for hash-based routing)
+ * - Next.js, React Router, Vue Router, etc.
+ * 
+ * @module @loamly/tracker
+ */
+
+export interface NavigationEvent {
+  from_url: string
+  to_url: string
+  navigation_type: 'push' | 'replace' | 'pop' | 'hash' | 'initial'
+  time_on_previous_page_ms: number
+}
+
+export interface RouterConfig {
+  onNavigate?: (event: NavigationEvent) => void
+  ignoreHashChange?: boolean
+}
+
+export class SPARouter {
+  private config: RouterConfig
+  private currentUrl: string
+  private pageEnterTime: number
+  private originalPushState: typeof history.pushState | null = null
+  private originalReplaceState: typeof history.replaceState | null = null
+
+  constructor(config: RouterConfig = {}) {
+    this.config = config
+    this.currentUrl = window.location.href
+    this.pageEnterTime = Date.now()
+  }
+
+  /**
+   * Start listening for navigation events
+   */
+  start(): void {
+    // Patch History API
+    this.patchHistoryAPI()
+
+    // Listen for popstate (back/forward)
+    window.addEventListener('popstate', this.handlePopState)
+
+    // Listen for hash changes
+    if (!this.config.ignoreHashChange) {
+      window.addEventListener('hashchange', this.handleHashChange)
+    }
+  }
+
+  /**
+   * Stop listening and restore original methods
+   */
+  stop(): void {
+    // Restore original History API methods
+    if (this.originalPushState) {
+      history.pushState = this.originalPushState
+    }
+    if (this.originalReplaceState) {
+      history.replaceState = this.originalReplaceState
+    }
+
+    window.removeEventListener('popstate', this.handlePopState)
+    window.removeEventListener('hashchange', this.handleHashChange)
+  }
+
+  /**
+   * Manually trigger a navigation event (for custom routers)
+   */
+  navigate(url: string, type: NavigationEvent['navigation_type'] = 'push'): void {
+    this.emitNavigation(url, type)
+  }
+
+  /**
+   * Get current URL
+   */
+  getCurrentUrl(): string {
+    return this.currentUrl
+  }
+
+  /**
+   * Get time on current page
+   */
+  getTimeOnPage(): number {
+    return Date.now() - this.pageEnterTime
+  }
+
+  private patchHistoryAPI(): void {
+    // Store original methods
+    this.originalPushState = history.pushState.bind(history)
+    this.originalReplaceState = history.replaceState.bind(history)
+
+    // Patch pushState
+    history.pushState = (...args) => {
+      const result = this.originalPushState!(...args)
+      this.handleStateChange('push')
+      return result
+    }
+
+    // Patch replaceState
+    history.replaceState = (...args) => {
+      const result = this.originalReplaceState!(...args)
+      this.handleStateChange('replace')
+      return result
+    }
+  }
+
+  private handleStateChange = (type: 'push' | 'replace'): void => {
+    const newUrl = window.location.href
+    if (newUrl !== this.currentUrl) {
+      this.emitNavigation(newUrl, type)
+    }
+  }
+
+  private handlePopState = (): void => {
+    const newUrl = window.location.href
+    if (newUrl !== this.currentUrl) {
+      this.emitNavigation(newUrl, 'pop')
+    }
+  }
+
+  private handleHashChange = (): void => {
+    const newUrl = window.location.href
+    if (newUrl !== this.currentUrl) {
+      this.emitNavigation(newUrl, 'hash')
+    }
+  }
+
+  private emitNavigation(toUrl: string, type: NavigationEvent['navigation_type']): void {
+    const event: NavigationEvent = {
+      from_url: this.currentUrl,
+      to_url: toUrl,
+      navigation_type: type,
+      time_on_previous_page_ms: Date.now() - this.pageEnterTime,
+    }
+
+    // Update current state
+    this.currentUrl = toUrl
+    this.pageEnterTime = Date.now()
+
+    // Emit event
+    this.config.onNavigate?.(event)
+  }
+}
+