humanbehavior-js 0.4.19 → 0.4.21

package/src/tracker.ts

@@ -4,6 +4,7 @@ import { v1 as uuidv1 } from 'uuid';
 import { HumanBehaviorAPI } from './api';
 import { RedactionManager, RedactionOptions } from './redact';
 import { logger, logError, logWarn, logInfo, logDebug } from './utils/logger';
+import { PropertyManager, Properties } from './utils/property-manager';
 
 // Check if we're in a browser environment
 const isBrowser = typeof window !== 'undefined';
@@ -29,6 +30,7 @@ export class HumanBehaviorTracker {
     private initialized: boolean = false;
     public initializationPromise: Promise<void> | null = null;
     private redactionManager!: RedactionManager;
+    private propertyManager!: PropertyManager;
     
     // Console tracking properties
     private originalConsole: {
@@ -62,7 +64,9 @@ export class HumanBehaviorTracker {
         redactFields?: string[];
         enableAutomaticTracking?: boolean;
         suppressConsoleErrors?: boolean; // New option to control error suppression
-        recordCanvas?: boolean; // Enable canvas recording with PostHog-style protection
+        recordCanvas?: boolean; // Enable canvas recording with protection
+        enableAutomaticProperties?: boolean; // Enable automatic property detection
+        propertyDenylist?: string[]; // Properties to exclude from tracking
         automaticTrackingOptions?: {
             trackButtons?: boolean;
             trackLinks?: boolean;
@@ -138,7 +142,10 @@ export class HumanBehaviorTracker {
         }
 
         // Create new tracker instance
-        const tracker = new HumanBehaviorTracker(apiKey, options?.ingestionUrl);
+        const tracker = new HumanBehaviorTracker(apiKey, options?.ingestionUrl, {
+            enableAutomaticProperties: options?.enableAutomaticProperties,
+            propertyDenylist: options?.propertyDenylist
+        });
         
         // Store canvas recording preference
         tracker.recordCanvas = options?.recordCanvas ?? false;
@@ -161,7 +168,10 @@ export class HumanBehaviorTracker {
         return tracker;
     }
 
-    constructor(apiKey: string | undefined, ingestionUrl?: string) {
+    constructor(apiKey: string | undefined, ingestionUrl?: string, options?: {
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
+    }) {
         if (!apiKey) {
             throw new Error('Human Behavior API Key is required');
         }
@@ -176,6 +186,12 @@ export class HumanBehaviorTracker {
         });
         this.apiKey = apiKey;
         this.redactionManager = new RedactionManager();
+        
+        // Initialize property manager
+        this.propertyManager = new PropertyManager({
+            enableAutomaticProperties: options?.enableAutomaticProperties !== false,
+            propertyDenylist: options?.propertyDenylist || []
+        });
 
         // Handle session restoration with improved continuity
         if (isBrowser) {
@@ -217,7 +233,31 @@ export class HumanBehaviorTracker {
             const userId = this.getCookie(`human_behavior_end_user_id_${this.apiKey}`);
             logDebug(`Initializing with sessionId: ${this.sessionId}, userId: ${userId}`);
             
-            const { sessionId, endUserId } = await this.api.init(this.sessionId, userId);
+            // Get automatic properties for init
+            const automaticProperties = this.propertyManager.getAutomaticProperties();
+            
+            // Create a custom init request with automatic properties
+            const initResponse = await fetch(`${this.api['baseUrl']}/api/ingestion/init`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Referer': document.referrer || ''
+                },
+                body: JSON.stringify({
+                    sessionId: this.sessionId,
+                    endUserId: userId,
+                    entryURL: window.location.href,
+                    referrer: document.referrer,
+                    automaticProperties: automaticProperties
+                })
+            });
+
+            if (!initResponse.ok) {
+                throw new Error(`Failed to initialize: ${initResponse.statusText}`);
+            }
+
+            const { sessionId, endUserId } = await initResponse.json();
             
             // Check if server returned a different session ID (for session continuity)
             if (sessionId !== this.sessionId) {
@@ -232,6 +272,11 @@ export class HumanBehaviorTracker {
             this.endUserId = endUserId;
             this.setCookie(`human_behavior_end_user_id_${this.apiKey}`, endUserId, 365);
 
+            // Send IP information after successful initialization
+            this.api.sendIPInfo(this.sessionId).catch(error => {
+                logWarn('Failed to send IP info:', error);
+            });
+
             // Only setup browser-specific handlers when in browser environment
             if (isBrowser) {
                 this.setupPageUnloadHandler();
@@ -368,6 +413,9 @@ export class HumanBehaviorTracker {
     public async trackPageView(url?: string): Promise<void> {
         if (!this.initialized) return;
 
+        // Update automatic properties for new page
+        this.propertyManager.updateAutomaticProperties();
+
         try {
             const pageViewData = {
                 url: url || window.location.href,
@@ -378,13 +426,16 @@ export class HumanBehaviorTracker {
                 timestamp: new Date().toISOString()
             };
 
+            // Get enhanced properties with automatic properties
+            const enhancedProperties = this.propertyManager.getEventProperties(pageViewData);
+
             // Add pageview event to the main event stream
             await this.addEvent({
                 type: 5, // Custom event type
                 data: {
                     payload: {
                         eventType: 'pageview',
-                        ...pageViewData
+                        ...enhancedProperties
                     }
                 },
                 timestamp: Date.now()
@@ -399,11 +450,14 @@ export class HumanBehaviorTracker {
     public async customEvent(eventName: string, properties?: Record<string, any>): Promise<void> {
         if (!this.initialized) return;
 
+        // Get enhanced properties with automatic properties
+        const enhancedProperties = this.propertyManager.getEventProperties(properties);
+
         try {
             // Send custom event directly to the API
-            await this.api.sendCustomEvent(this.sessionId, eventName, properties);
+            await this.api.sendCustomEvent(this.sessionId, eventName, enhancedProperties);
             
-            logDebug(`Custom event tracked: ${eventName}`, properties);
+            logDebug(`Custom event tracked: ${eventName}`, enhancedProperties);
         } catch (error: any) {
             logError('Failed to track custom event:', error);
             
@@ -422,7 +476,7 @@ export class HumanBehaviorTracker {
             try {
                 const customEventData = {
                     eventName: eventName,
-                    properties: properties || {},
+                    properties: enhancedProperties || {},
                     timestamp: new Date().toISOString(),
                     url: window.location.href,
                     pathname: window.location.pathname
@@ -792,8 +846,27 @@ export class HumanBehaviorTracker {
         
         logDebug('Identifying user:', { userProperties, originalEndUserId, sessionId: this.sessionId });
         
-        // Send user data with the original endUserId
-        await this.api.sendUserData(originalEndUserId!, userProperties, this.sessionId);
+        // Get automatic properties and send with user data
+        const automaticProperties = this.propertyManager.getAutomaticProperties();
+        
+        // Create a custom user request with automatic properties
+        const userResponse = await fetch(`${this.api['baseUrl']}/api/ingestion/user`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`
+            },
+            body: JSON.stringify({
+                userId: originalEndUserId,
+                userAttributes: userProperties,
+                sessionId: this.sessionId,
+                automaticProperties: automaticProperties
+            })
+        });
+
+        if (!userResponse.ok) {
+            throw new Error(`Failed to identify user: ${userResponse.statusText}`);
+        }
         
         // Don't update endUserId - keep it as the original UUID
         
@@ -847,7 +920,7 @@ export class HumanBehaviorTracker {
             inlineStylesheet: true, // Keep styles for proper session replay
             recordCrossOriginIframes: false, // Prevent cross-origin iframe errors
             
-            // ✅ CANVAS RECORDING - PostHog-style protection against overwhelm
+            // ✅ CANVAS RECORDING - protection against overwhelm
             recordCanvas: this.recordCanvas, // Opt-in only
             sampling: this.recordCanvas ? { canvas: 4 } : undefined, // 4 FPS throttle
             dataURLOptions: this.recordCanvas ? { 
@@ -1309,6 +1382,97 @@ export class HumanBehaviorTracker {
             initialized: this.initialized
         };
     }
+
+    // ===== PROPERTY MANAGEMENT METHODS =====
+
+    /**
+     * Set a session property that will be included in all events for this session
+     */
+    public setSessionProperty(key: string, value: any): void {
+        this.propertyManager.setSessionProperty(key, value);
+    }
+
+    /**
+     * Set multiple session properties
+     */
+    public setSessionProperties(properties: Record<string, any>): void {
+        this.propertyManager.setSessionProperties(properties);
+    }
+
+    /**
+     * Get a session property
+     */
+    public getSessionProperty(key: string): any {
+        return this.propertyManager.getSessionProperty(key);
+    }
+
+    /**
+     * Remove a session property
+     */
+    public removeSessionProperty(key: string): void {
+        this.propertyManager.removeSessionProperty(key);
+    }
+
+    /**
+     * Set a user property that will be included in all events
+     */
+    public setUserProperty(key: string, value: any): void {
+        this.propertyManager.setUserProperty(key, value);
+    }
+
+    /**
+     * Set multiple user properties
+     */
+    public setUserProperties(properties: Record<string, any>): void {
+        this.propertyManager.setUserProperties(properties);
+    }
+
+    /**
+     * Get a user property
+     */
+    public getUserProperty(key: string): any {
+        return this.propertyManager.getUserProperty(key);
+    }
+
+    /**
+     * Remove a user property
+     */
+    public removeUserProperty(key: string): void {
+        this.propertyManager.removeUserProperty(key);
+    }
+
+    /**
+     * Set a property only if it hasn't been set before
+     */
+    public setOnce(key: string, value: any, scope: 'session' | 'user' = 'user'): void {
+        this.propertyManager.setOnce(key, value, scope);
+    }
+
+    /**
+     * Clear all session properties
+     */
+    public clearSessionProperties(): void {
+        this.propertyManager.clearSessionProperties();
+    }
+
+    /**
+     * Clear all user properties
+     */
+    public clearUserProperties(): void {
+        this.propertyManager.clearUserProperties();
+    }
+
+    /**
+     * Get all properties for debugging
+     */
+    public getAllProperties(): {
+        automatic: Record<string, any>;
+        session: Record<string, any>;
+        user: Record<string, any>;
+        initial: Record<string, any>;
+    } {
+        return this.propertyManager.getAllProperties();
+    }
 }
 
 // Only expose to window object in browser environments

package/src/utils/ip-detector.ts

@@ -0,0 +1,158 @@
+/**
+ * IP Address Detection Utility
+ * Attempts to get the client's public IP address using multiple methods
+ */
+
+export interface IPInfo {
+    ip: string;
+    method: 'stun' | 'public-service' | 'fallback';
+    timestamp: number;
+}
+
+/**
+ * Get IP address using STUN server (most reliable)
+ */
+async function getIPFromSTUN(): Promise<string | null> {
+    try {
+        const pc = new RTCPeerConnection({
+            iceServers: [
+                { urls: 'stun:stun.l.google.com:19302' },
+                { urls: 'stun:stun1.l.google.com:19302' },
+                { urls: 'stun:stun2.l.google.com:19302' }
+            ]
+        });
+
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                pc.close();
+                resolve(null);
+            }, 5000);
+
+            pc.createDataChannel('');
+            pc.createOffer()
+                .then(offer => pc.setLocalDescription(offer))
+                .catch(() => resolve(null));
+
+            pc.onicecandidate = (event) => {
+                if (event.candidate) {
+                    const candidate = event.candidate.candidate;
+                    const match = candidate.match(/([0-9]{1,3}(\.[0-9]{1,3}){3})/);
+                    if (match) {
+                        clearTimeout(timeout);
+                        pc.close();
+                        resolve(match[1]);
+                    }
+                }
+            };
+        });
+    } catch (error) {
+        return null;
+    }
+}
+
+/**
+ * Get IP address using public IP service (fallback)
+ */
+async function getIPFromPublicService(): Promise<string | null> {
+    try {
+        const response = await fetch('https://api.ipify.org?format=json', {
+            method: 'GET'
+        });
+        
+        if (response.ok) {
+            const data = await response.json();
+            return data.ip;
+        }
+    } catch (error) {
+        // Try alternative service
+        try {
+            const response = await fetch('https://httpbin.org/ip', {
+                method: 'GET'
+            });
+            
+            if (response.ok) {
+                const data = await response.json();
+                return data.origin;
+            }
+        } catch (fallbackError) {
+            // Last resort
+            try {
+                const response = await fetch('https://api.myip.com', {
+                    method: 'GET'
+                });
+                
+                if (response.ok) {
+                    const data = await response.json();
+                    return data.ip;
+                }
+            } catch (lastError) {
+                return null;
+            }
+        }
+    }
+    
+    return null;
+}
+
+/**
+ * Get client's public IP address
+ * Tries STUN first (most reliable), then falls back to public services
+ */
+export async function getClientIP(): Promise<IPInfo | null> {
+    const startTime = Date.now();
+    
+    // Try STUN first (most reliable and privacy-friendly)
+    const stunIP = await getIPFromSTUN();
+    if (stunIP) {
+        return {
+            ip: stunIP,
+            method: 'stun',
+            timestamp: startTime
+        };
+    }
+    
+    // Fallback to public IP service
+    const publicIP = await getIPFromPublicService();
+    if (publicIP) {
+        return {
+            ip: publicIP,
+            method: 'public-service',
+            timestamp: startTime
+        };
+    }
+    
+    return null;
+}
+
+/**
+ * Get IP address with caching to avoid repeated requests
+ */
+let cachedIP: IPInfo | null = null;
+let cacheTimestamp = 0;
+const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
+
+export async function getCachedIP(): Promise<IPInfo | null> {
+    const now = Date.now();
+    
+    // Return cached IP if still valid
+    if (cachedIP && (now - cacheTimestamp) < CACHE_DURATION) {
+        return cachedIP;
+    }
+    
+    // Get fresh IP
+    const ipInfo = await getClientIP();
+    if (ipInfo) {
+        cachedIP = ipInfo;
+        cacheTimestamp = now;
+    }
+    
+    return ipInfo;
+}
+
+/**
+ * Clear IP cache (useful for testing or when network changes)
+ */
+export function clearIPCache(): void {
+    cachedIP = null;
+    cacheTimestamp = 0;
+}