humanbehavior-js 0.4.20 → 0.4.21

package/dist/types/angular/index.d.ts

@@ -23,6 +23,7 @@ declare class HumanBehaviorTracker {
     private initialized;
     initializationPromise: Promise<void> | null;
     private redactionManager;
+    private propertyManager;
     private originalConsole;
     private consoleTrackingEnabled;
     navigationTrackingEnabled: boolean;
@@ -48,6 +49,8 @@ declare class HumanBehaviorTracker {
         enableAutomaticTracking?: boolean;
         suppressConsoleErrors?: boolean;
         recordCanvas?: boolean;
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
         automaticTrackingOptions?: {
             trackButtons?: boolean;
             trackLinks?: boolean;
@@ -56,7 +59,10 @@ declare class HumanBehaviorTracker {
             includeClasses?: boolean;
         };
     }): HumanBehaviorTracker;
-    constructor(apiKey: string | undefined, ingestionUrl?: string);
+    constructor(apiKey: string | undefined, ingestionUrl?: string, options?: {
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
+    });
     private init;
     private ensureInitialized;
     /**
@@ -217,6 +223,59 @@ declare class HumanBehaviorTracker {
         isPreexistingUser: boolean;
         initialized: boolean;
     };
+    /**
+     * Set a session property that will be included in all events for this session
+     */
+    setSessionProperty(key: string, value: any): void;
+    /**
+     * Set multiple session properties
+     */
+    setSessionProperties(properties: Record<string, any>): void;
+    /**
+     * Get a session property
+     */
+    getSessionProperty(key: string): any;
+    /**
+     * Remove a session property
+     */
+    removeSessionProperty(key: string): void;
+    /**
+     * Set a user property that will be included in all events
+     */
+    setUserProperty(key: string, value: any): void;
+    /**
+     * Set multiple user properties
+     */
+    setUserProperties(properties: Record<string, any>): void;
+    /**
+     * Get a user property
+     */
+    getUserProperty(key: string): any;
+    /**
+     * Remove a user property
+     */
+    removeUserProperty(key: string): void;
+    /**
+     * Set a property only if it hasn't been set before
+     */
+    setOnce(key: string, value: any, scope?: 'session' | 'user'): void;
+    /**
+     * Clear all session properties
+     */
+    clearSessionProperties(): void;
+    /**
+     * Clear all user properties
+     */
+    clearUserProperties(): void;
+    /**
+     * Get all properties for debugging
+     */
+    getAllProperties(): {
+        automatic: Record<string, any>;
+        session: Record<string, any>;
+        user: Record<string, any>;
+        initial: Record<string, any>;
+    };
 }
 
 declare class HumanBehaviorModule {

package/dist/types/index.d.ts

@@ -113,6 +113,7 @@ declare class HumanBehaviorTracker {
     private initialized;
     initializationPromise: Promise<void> | null;
     private redactionManager;
+    private propertyManager;
     private originalConsole;
     private consoleTrackingEnabled;
     navigationTrackingEnabled: boolean;
@@ -138,6 +139,8 @@ declare class HumanBehaviorTracker {
         enableAutomaticTracking?: boolean;
         suppressConsoleErrors?: boolean;
         recordCanvas?: boolean;
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
         automaticTrackingOptions?: {
             trackButtons?: boolean;
             trackLinks?: boolean;
@@ -146,7 +149,10 @@ declare class HumanBehaviorTracker {
             includeClasses?: boolean;
         };
     }): HumanBehaviorTracker;
-    constructor(apiKey: string | undefined, ingestionUrl?: string);
+    constructor(apiKey: string | undefined, ingestionUrl?: string, options?: {
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
+    });
     private init;
     private ensureInitialized;
     /**
@@ -307,6 +313,59 @@ declare class HumanBehaviorTracker {
         isPreexistingUser: boolean;
         initialized: boolean;
     };
+    /**
+     * Set a session property that will be included in all events for this session
+     */
+    setSessionProperty(key: string, value: any): void;
+    /**
+     * Set multiple session properties
+     */
+    setSessionProperties(properties: Record<string, any>): void;
+    /**
+     * Get a session property
+     */
+    getSessionProperty(key: string): any;
+    /**
+     * Remove a session property
+     */
+    removeSessionProperty(key: string): void;
+    /**
+     * Set a user property that will be included in all events
+     */
+    setUserProperty(key: string, value: any): void;
+    /**
+     * Set multiple user properties
+     */
+    setUserProperties(properties: Record<string, any>): void;
+    /**
+     * Get a user property
+     */
+    getUserProperty(key: string): any;
+    /**
+     * Remove a user property
+     */
+    removeUserProperty(key: string): void;
+    /**
+     * Set a property only if it hasn't been set before
+     */
+    setOnce(key: string, value: any, scope?: 'session' | 'user'): void;
+    /**
+     * Clear all session properties
+     */
+    clearSessionProperties(): void;
+    /**
+     * Clear all user properties
+     */
+    clearUserProperties(): void;
+    /**
+     * Get all properties for debugging
+     */
+    getAllProperties(): {
+        automatic: Record<string, any>;
+        session: Record<string, any>;
+        user: Record<string, any>;
+        initial: Record<string, any>;
+    };
 }
 
 declare const MAX_CHUNK_SIZE_BYTES: number;
@@ -324,6 +383,11 @@ declare class HumanBehaviorAPI {
         sessionId: any;
         endUserId: any;
     }>;
+    /**
+     * Send IP address information to the server
+     * This is called after successful initialization
+     */
+    sendIPInfo(sessionId: string): Promise<void>;
     sendEvents(events: any[], sessionId: string, userId: string): Promise<void>;
     sendEventsChunked(events: any[], sessionId: string, userId?: string): Promise<any[]>;
     sendUserData(userId: string, userData: Record<string, any>, sessionId: string): Promise<any>;
@@ -336,6 +400,197 @@ declare class HumanBehaviorAPI {
     }>): Promise<any>;
 }
 
+/**
+ * Automatic Property Detection for HumanBehavior SDK
+ * Captures device type, location, and initial referrer information
+ */
+interface DeviceInfo {
+    device_type: string;
+    browser: string;
+    browser_version: string;
+    os: string;
+    os_version: string;
+    device_model?: string;
+    screen_resolution: string;
+    viewport_size: string;
+    color_depth: number;
+    timezone: string;
+    language: string;
+    languages: string[];
+    raw_user_agent?: string;
+}
+interface LocationInfo {
+    current_url: string;
+    pathname: string;
+    search: string;
+    hash: string;
+    title: string;
+    referrer: string;
+    referrer_domain: string;
+    initial_referrer: string;
+    initial_referrer_domain: string;
+    initial_host?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+}
+interface AutomaticProperties extends DeviceInfo, LocationInfo {
+}
+/**
+ * Get device information
+ */
+declare function getDeviceInfo(): DeviceInfo;
+/**
+ * Get location information
+ */
+declare function getLocationInfo(): LocationInfo;
+/**
+ * Get all automatic properties
+ */
+declare function getAutomaticProperties(): AutomaticProperties;
+/**
+ * Get initial properties that should be captured once per session
+ */
+declare function getInitialProperties(): Record<string, any>;
+/**
+ * Get current page properties (changes with navigation)
+ */
+declare function getCurrentPageProperties(): Record<string, any>;
+
+/**
+ * Property Manager for HumanBehavior SDK
+ * Handles automatic properties, session properties, and user properties
+ */
+interface Properties {
+    [key: string]: any;
+}
+interface PropertyManagerConfig {
+    enableAutomaticProperties?: boolean;
+    enableSessionProperties?: boolean;
+    enableUserProperties?: boolean;
+    propertyDenylist?: string[];
+}
+declare class PropertyManager {
+    private config;
+    private automaticProperties;
+    private sessionProperties;
+    private userProperties;
+    private initialProperties;
+    private isInitialized;
+    constructor(config?: PropertyManagerConfig);
+    /**
+     * Initialize the property manager
+     */
+    private initialize;
+    /**
+     * Get all properties for an event
+     */
+    getEventProperties(eventProperties?: Properties): Properties;
+    /**
+     * Get automatic properties
+     */
+    getAutomaticProperties(): Properties;
+    /**
+     * Get automatic properties with GeoIP data merged in
+     */
+    getAutomaticPropertiesWithGeoIP(geoIPProperties?: Record<string, any>): Properties;
+    /**
+     * Set a session property
+     */
+    setSessionProperty(key: string, value: any): void;
+    /**
+     * Set multiple session properties
+     */
+    setSessionProperties(properties: Properties): void;
+    /**
+     * Get a session property
+     */
+    getSessionProperty(key: string): any;
+    /**
+     * Remove a session property
+     */
+    removeSessionProperty(key: string): void;
+    /**
+     * Set a user property
+     */
+    setUserProperty(key: string, value: any): void;
+    /**
+     * Set multiple user properties
+     */
+    setUserProperties(properties: Properties): void;
+    /**
+     * Get a user property
+     */
+    getUserProperty(key: string): any;
+    /**
+     * Remove a user property
+     */
+    removeUserProperty(key: string): void;
+    /**
+     * Set a property only if it hasn't been set before
+     */
+    setOnce(key: string, value: any, scope?: 'session' | 'user'): void;
+    /**
+     * Clear all session properties
+     */
+    clearSessionProperties(): void;
+    /**
+     * Clear all user properties
+     */
+    clearUserProperties(): void;
+    /**
+     * Reset all properties
+     */
+    reset(): void;
+    /**
+     * Load session properties from sessionStorage
+     */
+    private loadSessionProperties;
+    /**
+     * Save session properties to sessionStorage
+     */
+    private saveSessionProperties;
+    /**
+     * Apply property denylist
+     */
+    private applyDenylist;
+    /**
+     * Update automatic properties (call when page changes)
+     */
+    updateAutomaticProperties(): void;
+    /**
+     * Get all properties for debugging
+     */
+    getAllProperties(): {
+        automatic: Properties;
+        session: Properties;
+        user: Properties;
+        initial: Properties;
+    };
+}
+
+/**
+ * IP Address Detection Utility
+ * Attempts to get the client's public IP address using multiple methods
+ */
+interface IPInfo {
+    ip: string;
+    method: 'stun' | 'public-service' | 'fallback';
+    timestamp: number;
+}
+/**
+ * Get client's public IP address
+ * Tries STUN first (most reliable), then falls back to public services
+ */
+declare function getClientIP(): Promise<IPInfo | null>;
+declare function getCachedIP(): Promise<IPInfo | null>;
+/**
+ * Clear IP cache (useful for testing or when network changes)
+ */
+declare function clearIPCache(): void;
+
 declare enum LogLevel {
     NONE = 0,
     ERROR = 1,
@@ -369,5 +624,5 @@ declare const logWarn: (message: string, ...args: any[]) => void;
 declare const logInfo: (message: string, ...args: any[]) => void;
 declare const logDebug: (message: string, ...args: any[]) => void;
 
-export { HumanBehaviorAPI, HumanBehaviorTracker, LogLevel, MAX_CHUNK_SIZE_BYTES, RedactionManager, isChunkSizeExceeded, logDebug, logError, logInfo, logWarn, logger, redactionManager, splitLargeEvent, validateSingleEventSize };
-export type { LoggerConfig, RedactionOptions };
+export { HumanBehaviorAPI, HumanBehaviorTracker, LogLevel, MAX_CHUNK_SIZE_BYTES, PropertyManager, RedactionManager, clearIPCache, getAutomaticProperties, getCachedIP, getClientIP, getCurrentPageProperties, getDeviceInfo, getInitialProperties, getLocationInfo, isChunkSizeExceeded, logDebug, logError, logInfo, logWarn, logger, redactionManager, splitLargeEvent, validateSingleEventSize };
+export type { AutomaticProperties, DeviceInfo, IPInfo, LocationInfo, LoggerConfig, Properties, PropertyManagerConfig, RedactionOptions };

package/dist/types/react/index.d.ts

@@ -25,6 +25,7 @@ declare class HumanBehaviorTracker {
     private initialized;
     initializationPromise: Promise<void> | null;
     private redactionManager;
+    private propertyManager;
     private originalConsole;
     private consoleTrackingEnabled;
     navigationTrackingEnabled: boolean;
@@ -50,6 +51,8 @@ declare class HumanBehaviorTracker {
         enableAutomaticTracking?: boolean;
         suppressConsoleErrors?: boolean;
         recordCanvas?: boolean;
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
         automaticTrackingOptions?: {
             trackButtons?: boolean;
             trackLinks?: boolean;
@@ -58,7 +61,10 @@ declare class HumanBehaviorTracker {
             includeClasses?: boolean;
         };
     }): HumanBehaviorTracker;
-    constructor(apiKey: string | undefined, ingestionUrl?: string);
+    constructor(apiKey: string | undefined, ingestionUrl?: string, options?: {
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
+    });
     private init;
     private ensureInitialized;
     /**
@@ -219,6 +225,59 @@ declare class HumanBehaviorTracker {
         isPreexistingUser: boolean;
         initialized: boolean;
     };
+    /**
+     * Set a session property that will be included in all events for this session
+     */
+    setSessionProperty(key: string, value: any): void;
+    /**
+     * Set multiple session properties
+     */
+    setSessionProperties(properties: Record<string, any>): void;
+    /**
+     * Get a session property
+     */
+    getSessionProperty(key: string): any;
+    /**
+     * Remove a session property
+     */
+    removeSessionProperty(key: string): void;
+    /**
+     * Set a user property that will be included in all events
+     */
+    setUserProperty(key: string, value: any): void;
+    /**
+     * Set multiple user properties
+     */
+    setUserProperties(properties: Record<string, any>): void;
+    /**
+     * Get a user property
+     */
+    getUserProperty(key: string): any;
+    /**
+     * Remove a user property
+     */
+    removeUserProperty(key: string): void;
+    /**
+     * Set a property only if it hasn't been set before
+     */
+    setOnce(key: string, value: any, scope?: 'session' | 'user'): void;
+    /**
+     * Clear all session properties
+     */
+    clearSessionProperties(): void;
+    /**
+     * Clear all user properties
+     */
+    clearUserProperties(): void;
+    /**
+     * Get all properties for debugging
+     */
+    getAllProperties(): {
+        automatic: Record<string, any>;
+        session: Record<string, any>;
+        user: Record<string, any>;
+        initial: Record<string, any>;
+    };
 }
 
 interface HumanBehaviorProviderProps {

package/dist/types/remix/index.d.ts

@@ -26,6 +26,7 @@ declare class HumanBehaviorTracker {
     private initialized;
     initializationPromise: Promise<void> | null;
     private redactionManager;
+    private propertyManager;
     private originalConsole;
     private consoleTrackingEnabled;
     navigationTrackingEnabled: boolean;
@@ -51,6 +52,8 @@ declare class HumanBehaviorTracker {
         enableAutomaticTracking?: boolean;
         suppressConsoleErrors?: boolean;
         recordCanvas?: boolean;
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
         automaticTrackingOptions?: {
             trackButtons?: boolean;
             trackLinks?: boolean;
@@ -59,7 +62,10 @@ declare class HumanBehaviorTracker {
             includeClasses?: boolean;
         };
     }): HumanBehaviorTracker;
-    constructor(apiKey: string | undefined, ingestionUrl?: string);
+    constructor(apiKey: string | undefined, ingestionUrl?: string, options?: {
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
+    });
     private init;
     private ensureInitialized;
     /**
@@ -220,6 +226,59 @@ declare class HumanBehaviorTracker {
         isPreexistingUser: boolean;
         initialized: boolean;
     };
+    /**
+     * Set a session property that will be included in all events for this session
+     */
+    setSessionProperty(key: string, value: any): void;
+    /**
+     * Set multiple session properties
+     */
+    setSessionProperties(properties: Record<string, any>): void;
+    /**
+     * Get a session property
+     */
+    getSessionProperty(key: string): any;
+    /**
+     * Remove a session property
+     */
+    removeSessionProperty(key: string): void;
+    /**
+     * Set a user property that will be included in all events
+     */
+    setUserProperty(key: string, value: any): void;
+    /**
+     * Set multiple user properties
+     */
+    setUserProperties(properties: Record<string, any>): void;
+    /**
+     * Get a user property
+     */
+    getUserProperty(key: string): any;
+    /**
+     * Remove a user property
+     */
+    removeUserProperty(key: string): void;
+    /**
+     * Set a property only if it hasn't been set before
+     */
+    setOnce(key: string, value: any, scope?: 'session' | 'user'): void;
+    /**
+     * Clear all session properties
+     */
+    clearSessionProperties(): void;
+    /**
+     * Clear all user properties
+     */
+    clearUserProperties(): void;
+    /**
+     * Get all properties for debugging
+     */
+    getAllProperties(): {
+        automatic: Record<string, any>;
+        session: Record<string, any>;
+        user: Record<string, any>;
+        initial: Record<string, any>;
+    };
 }
 
 interface HumanBehaviorProviderProps {

package/dist/types/svelte/index.d.ts

@@ -23,6 +23,7 @@ declare class HumanBehaviorTracker {
     private initialized;
     initializationPromise: Promise<void> | null;
     private redactionManager;
+    private propertyManager;
     private originalConsole;
     private consoleTrackingEnabled;
     navigationTrackingEnabled: boolean;
@@ -48,6 +49,8 @@ declare class HumanBehaviorTracker {
         enableAutomaticTracking?: boolean;
         suppressConsoleErrors?: boolean;
         recordCanvas?: boolean;
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
         automaticTrackingOptions?: {
             trackButtons?: boolean;
             trackLinks?: boolean;
@@ -56,7 +59,10 @@ declare class HumanBehaviorTracker {
             includeClasses?: boolean;
         };
     }): HumanBehaviorTracker;
-    constructor(apiKey: string | undefined, ingestionUrl?: string);
+    constructor(apiKey: string | undefined, ingestionUrl?: string, options?: {
+        enableAutomaticProperties?: boolean;
+        propertyDenylist?: string[];
+    });
     private init;
     private ensureInitialized;
     /**
@@ -217,6 +223,59 @@ declare class HumanBehaviorTracker {
         isPreexistingUser: boolean;
         initialized: boolean;
     };
+    /**
+     * Set a session property that will be included in all events for this session
+     */
+    setSessionProperty(key: string, value: any): void;
+    /**
+     * Set multiple session properties
+     */
+    setSessionProperties(properties: Record<string, any>): void;
+    /**
+     * Get a session property
+     */
+    getSessionProperty(key: string): any;
+    /**
+     * Remove a session property
+     */
+    removeSessionProperty(key: string): void;
+    /**
+     * Set a user property that will be included in all events
+     */
+    setUserProperty(key: string, value: any): void;
+    /**
+     * Set multiple user properties
+     */
+    setUserProperties(properties: Record<string, any>): void;
+    /**
+     * Get a user property
+     */
+    getUserProperty(key: string): any;
+    /**
+     * Remove a user property
+     */
+    removeUserProperty(key: string): void;
+    /**
+     * Set a property only if it hasn't been set before
+     */
+    setOnce(key: string, value: any, scope?: 'session' | 'user'): void;
+    /**
+     * Clear all session properties
+     */
+    clearSessionProperties(): void;
+    /**
+     * Clear all user properties
+     */
+    clearUserProperties(): void;
+    /**
+     * Get all properties for debugging
+     */
+    getAllProperties(): {
+        automatic: Record<string, any>;
+        session: Record<string, any>;
+        user: Record<string, any>;
+        initial: Record<string, any>;
+    };
 }
 
 declare const humanBehaviorStore: {

package/package/canvas-recording-demo.html

@@ -53,7 +53,7 @@
             tracker = HumanBehaviorTracker.init('13c3e029-ca45-4a3c-a33b-f5dcb297e31c', {
                 logLevel: 'warn',
                 suppressConsoleErrors: true,
-                recordCanvas: enableCanvas // PostHog-style protection
+                recordCanvas: enableCanvas // protection
             });
             
             updateStatus();

package/package/simple-spa.html

@@ -581,7 +581,7 @@
                 addLog(`endUserId changed: ${originalEndUserId !== newEndUserId ? 'YES (BAD)' : 'NO (GOOD)'}`);
                 addLog(`User authenticated: ${userId}`);
                 
-                // The endUserId should stay the same, but posthogName will be updated with email
+                // The endUserId should stay the same, but user name will be updated
                 addLog('✅ endUserId maintained for session continuity');
                 addLog('✅ posthogName will be updated with email for UI display');
                 

package/package/src/angular/index.ts

@@ -8,7 +8,7 @@ export class HumanBehaviorModule {
     logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
     redactFields?: string[];
     suppressConsoleErrors?: boolean;
-    recordCanvas?: boolean; // Enable canvas recording with PostHog-style protection
+    recordCanvas?: boolean; // Enable canvas recording with protection
   }) {
     return {
       ngModule: HumanBehaviorModule,
@@ -44,7 +44,7 @@ export class HumanBehaviorService {
     logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
     redactFields?: string[];
     suppressConsoleErrors?: boolean;
-    recordCanvas?: boolean; // Enable canvas recording with PostHog-style protection
+    recordCanvas?: boolean; // Enable canvas recording with protection
   }) {
     this.tracker = HumanBehaviorTracker.init(apiKey, options);
   }
@@ -73,7 +73,7 @@ export function initializeHumanBehavior(apiKey: string, options?: {
   logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
   redactFields?: string[];
   suppressConsoleErrors?: boolean;
-  recordCanvas?: boolean; // Enable canvas recording with PostHog-style protection
+  recordCanvas?: boolean; // Enable canvas recording with protection
 }): HumanBehaviorTracker {
   return HumanBehaviorTracker.init(apiKey, options);
 }