humanbehavior-js 0.4.16 → 0.4.17

package/package/dist/types/install-wizard.d.ts

@@ -0,0 +1,156 @@
+/**
+ * HumanBehavior SDK Auto-Installation Wizard
+ *
+ * This wizard automatically detects the user's framework and modifies their codebase
+ * to integrate the SDK with minimal user intervention.
+ */
+interface FrameworkInfo {
+    name: string;
+    type: 'react' | 'vue' | 'angular' | 'svelte' | 'nextjs' | 'nuxt' | 'remix' | 'vanilla' | 'astro' | 'gatsby' | 'node' | 'auto';
+    bundler?: 'vite' | 'webpack' | 'esbuild' | 'rollup';
+    packageManager?: 'npm' | 'yarn' | 'pnpm';
+    hasTypeScript?: boolean;
+    hasRouter?: boolean;
+    projectRoot?: string;
+    version?: string;
+    majorVersion?: number;
+    features?: {
+        hasReact18?: boolean;
+        hasVue3?: boolean;
+        hasNuxt3?: boolean;
+        hasAngularStandalone?: boolean;
+        hasNextAppRouter?: boolean;
+        hasSvelteKit?: boolean;
+    };
+}
+interface CodeModification {
+    filePath: string;
+    action: 'create' | 'modify' | 'append';
+    content: string;
+    description: string;
+}
+interface InstallationResult {
+    success: boolean;
+    framework: FrameworkInfo;
+    modifications: CodeModification[];
+    errors: string[];
+    nextSteps: string[];
+}
+declare class AutoInstallationWizard {
+    protected apiKey: string;
+    protected projectRoot: string;
+    protected framework: FrameworkInfo | null;
+    constructor(apiKey: string, projectRoot?: string);
+    /**
+     * Simple version comparison utility
+     */
+    private compareVersions;
+    private isVersionGte;
+    private getMajorVersion;
+    /**
+     * Main installation method - detects framework and auto-installs
+     */
+    install(): Promise<InstallationResult>;
+    /**
+     * Detect the current framework and project setup
+     */
+    detectFramework(): Promise<FrameworkInfo>;
+    /**
+     * Install the SDK package
+     */
+    protected installPackage(): Promise<void>;
+    /**
+     * Generate code modifications based on framework
+     */
+    protected generateModifications(): Promise<CodeModification[]>;
+    /**
+     * Generate React-specific modifications
+     */
+    private generateReactModifications;
+    /**
+     * Generate Next.js-specific modifications
+     */
+    private generateNextJSModifications;
+    /**
+     * Generate Astro-specific modifications
+     */
+    private generateAstroModifications;
+    /**
+     * Generate Nuxt-specific modifications
+     */
+    private generateNuxtModifications;
+    /**
+     * Generate Remix-specific modifications
+     */
+    private generateRemixModifications;
+    /**
+     * Generate Vue-specific modifications
+     */
+    private generateVueModifications;
+    /**
+     * Generate Angular-specific modifications
+     */
+    private generateAngularModifications;
+    /**
+     * Generate Svelte-specific modifications
+     */
+    private generateSvelteModifications;
+    /**
+     * Generate vanilla JS/TS modifications
+     */
+    private generateVanillaModifications;
+    /**
+     * Generate Gatsby-specific modifications
+     */
+    private generateGatsbyModifications;
+    /**
+     * Apply modifications to the codebase
+     */
+    protected applyModifications(modifications: CodeModification[]): Promise<void>;
+    /**
+     * Generate next steps for the user
+     */
+    private generateNextSteps;
+    private findReactAppFile;
+    private findVueMainFile;
+    private findSvelteMainFile;
+    private findHTMLFile;
+    private injectReactProvider;
+    private injectNextJSAppRouter;
+    private injectNextJSPagesRouter;
+    private injectRemixProvider;
+    private injectVuePlugin;
+    private injectAngularModule;
+    private injectAngularStandaloneInit;
+    private injectSvelteStore;
+    private injectSvelteKitLayout;
+    private injectVanillaScript;
+    /**
+     * Inject Astro layout with HumanBehavior component
+     */
+    private injectAstroLayout;
+    private injectNuxtConfig;
+    private injectGatsbyLayout;
+    private injectGatsbyBrowser;
+    /**
+     * Helper method to find the best environment file for a framework
+     */
+    private findBestEnvFile;
+    /**
+     * Helper method to create or append to environment files
+     */
+    private createEnvironmentModification;
+}
+/**
+ * Browser-based auto-installation wizard
+ */
+declare class BrowserAutoInstallationWizard {
+    private apiKey;
+    constructor(apiKey: string);
+    install(): Promise<InstallationResult>;
+    private detectFramework;
+    private generateBrowserModifications;
+}
+
+export { AutoInstallationWizard, BrowserAutoInstallationWizard };
+export type { CodeModification, FrameworkInfo, InstallationResult };

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

@@ -0,0 +1,255 @@
+import React, { ReactNode } from 'react';
+
+interface RedactionOptions {
+    redactedText?: string;
+    excludeSelectors?: string[];
+    userFields?: string[];
+}
+
+declare global {
+    interface Window {
+        HumanBehaviorTracker: typeof HumanBehaviorTracker;
+        __humanBehaviorGlobalTracker?: HumanBehaviorTracker;
+    }
+}
+declare class HumanBehaviorTracker {
+    private eventIngestionQueue;
+    private sessionId;
+    private userProperties;
+    private isProcessing;
+    private flushInterval;
+    private readonly FLUSH_INTERVAL_MS;
+    private api;
+    private endUserId;
+    private apiKey;
+    private initialized;
+    initializationPromise: Promise<void> | null;
+    private redactionManager;
+    private originalConsole;
+    private consoleTrackingEnabled;
+    navigationTrackingEnabled: boolean;
+    private currentUrl;
+    private previousUrl;
+    private originalPushState;
+    private originalReplaceState;
+    private navigationListeners;
+    private _connectionBlocked;
+    private recordInstance;
+    private sessionStartTime;
+    private rrwebRecord;
+    private fullSnapshotTimeout;
+    private recordCanvas;
+    /**
+     * Initialize the HumanBehavior tracker
+     * This is the main entry point - call this once per page
+     */
+    static init(apiKey: string, options?: {
+        ingestionUrl?: string;
+        logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        redactFields?: string[];
+        enableAutomaticTracking?: boolean;
+        suppressConsoleErrors?: boolean;
+        recordCanvas?: boolean;
+        automaticTrackingOptions?: {
+            trackButtons?: boolean;
+            trackLinks?: boolean;
+            trackForms?: boolean;
+            includeText?: boolean;
+            includeClasses?: boolean;
+        };
+    }): HumanBehaviorTracker;
+    constructor(apiKey: string | undefined, ingestionUrl?: string);
+    private init;
+    private ensureInitialized;
+    /**
+     * Setup navigation event tracking for SPA navigation
+     */
+    private setupNavigationTracking;
+    /**
+     * Track navigation events and send custom events
+     */
+    trackNavigationEvent(type: string, fromUrl: string, toUrl: string): Promise<void>;
+    trackPageView(url?: string): Promise<void>;
+    customEvent(eventName: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Setup automatic tracking for buttons, links, and forms
+     */
+    private setupAutomaticTracking;
+    /**
+     * Setup automatic button tracking
+     */
+    private setupAutomaticButtonTracking;
+    /**
+     * Setup automatic link tracking
+     */
+    private setupAutomaticLinkTracking;
+    /**
+     * Setup automatic form tracking
+     */
+    private setupAutomaticFormTracking;
+    /**
+     * Cleanup navigation tracking
+     */
+    private cleanupNavigationTracking;
+    static logToStorage(message: string): void;
+    /**
+     * Configure logging behavior for the SDK
+     * @param config Logger configuration options
+     */
+    static configureLogging(config: {
+        level?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        enableConsole?: boolean;
+        enableStorage?: boolean;
+    }): void;
+    /**
+     * Enable console event tracking
+     */
+    enableConsoleTracking(): void;
+    /**
+     * Disable console event tracking
+     */
+    disableConsoleTracking(): void;
+    private trackConsoleEvent;
+    private setupPageUnloadHandler;
+    viewLogs(): void;
+    /**
+     * Add user identification information to the tracker
+     * If userId is not provided, will use userProperties.email as the userId (if present)
+     */
+    identifyUser({ userProperties }: {
+        userProperties: Record<string, any>;
+    }): Promise<string>;
+    /**
+     * Get current user attributes
+     */
+    getUserAttributes(): Record<string, any>;
+    start(): Promise<void>;
+    /**
+     * Manually trigger a FullSnapshot (for navigation events)
+     * Delays snapshot to avoid capturing mid-animation states
+     */
+    private takeFullSnapshot;
+    stop(): Promise<void>;
+    /**
+     * Add an event to the ingestion queue
+     * Events are sent directly without processing to avoid corruption
+     */
+    addEvent(event: any): Promise<void>;
+    /**
+     * Flush events to the ingestion server
+     * Events are sent in chunks to handle large payloads efficiently
+     */
+    private flush;
+    private setCookie;
+    getCookie(name: string): string | null;
+    /**
+     * Delete a cookie by setting its expiration date to the past
+     * @param name The name of the cookie to delete
+     */
+    private deleteCookie;
+    /**
+     * Clear user data and reset session when user signs out of the site
+     * This should be called when a user logs out of your application to prevent
+     * data contamination between different users
+     */
+    logout(): void;
+    /**
+     * Start redaction functionality for sensitive input fields
+     * @param options Optional configuration for redaction behavior
+     */
+    redact(options?: RedactionOptions): Promise<void>;
+    /**
+     * Set specific fields to be redacted during session recording
+     * Uses rrweb's built-in masking instead of custom redaction processing
+     * @param fields Array of CSS selectors for fields to redact (e.g., ['input[type="password"]', '#email-field'])
+     */
+    setRedactedFields(fields: string[]): void;
+    private restartWithNewRedaction;
+    /**
+     * Check if redaction is currently active
+     */
+    isRedactionActive(): boolean;
+    /**
+     * Get the currently selected fields for redaction
+     */
+    getRedactedFields(): string[];
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Get the current URL being tracked
+     */
+    getCurrentUrl(): string;
+    /**
+     * Get current snapshot frequency info
+     * Uses configured values (5 minutes, 1000 events)
+     */
+    getSnapshotFrequencyInfo(): {
+        sessionDuration: number;
+        currentInterval: number;
+        currentThreshold: number;
+        phase: string;
+    };
+    /**
+     * Test if the tracker can reach the ingestion server
+     */
+    testConnection(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get connection status and recommendations
+     */
+    getConnectionStatus(): {
+        blocked: boolean;
+        recommendations: string[];
+    };
+    /**
+     * Check if the current user is a preexisting user
+     * Returns true if the user has an existing endUserId cookie from a previous session
+     */
+    isPreexistingUser(): boolean;
+    /**
+     * Get user information including whether they are preexisting
+     */
+    getUserInfo(): {
+        endUserId: string | null;
+        sessionId: string;
+        isPreexistingUser: boolean;
+        initialized: boolean;
+    };
+}
+
+interface HumanBehaviorProviderProps {
+    apiKey?: string;
+    client?: HumanBehaviorTracker;
+    children: ReactNode;
+    options?: {
+        ingestionUrl?: string;
+        logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        redactFields?: string[];
+        suppressConsoleErrors?: boolean;
+        recordCanvas?: boolean;
+    };
+}
+declare const HumanBehaviorProvider: ({ apiKey, client, children, options }: HumanBehaviorProviderProps) => React.JSX.Element;
+declare const useHumanBehavior: () => HumanBehaviorTracker;
+declare const useRedaction: () => {
+    setRedactedFields: (fields: string[]) => void;
+    isRedactionActive: () => boolean;
+    getRedactedFields: () => string[];
+};
+declare const useUserTracking: () => {
+    identifyUser: ({ userProperties }: {
+        userProperties: Record<string, any>;
+    }) => Promise<{
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: unknown;
+    }>;
+};
+
+export { HumanBehaviorProvider, HumanBehaviorTracker, useHumanBehavior, useRedaction, useUserTracking };

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

@@ -0,0 +1,246 @@
+import { LoaderFunctionArgs } from '@remix-run/node';
+import React, { ReactNode } from 'react';
+
+interface RedactionOptions {
+    redactedText?: string;
+    excludeSelectors?: string[];
+    userFields?: string[];
+}
+
+declare global {
+    interface Window {
+        HumanBehaviorTracker: typeof HumanBehaviorTracker;
+        __humanBehaviorGlobalTracker?: HumanBehaviorTracker;
+    }
+}
+declare class HumanBehaviorTracker {
+    private eventIngestionQueue;
+    private sessionId;
+    private userProperties;
+    private isProcessing;
+    private flushInterval;
+    private readonly FLUSH_INTERVAL_MS;
+    private api;
+    private endUserId;
+    private apiKey;
+    private initialized;
+    initializationPromise: Promise<void> | null;
+    private redactionManager;
+    private originalConsole;
+    private consoleTrackingEnabled;
+    navigationTrackingEnabled: boolean;
+    private currentUrl;
+    private previousUrl;
+    private originalPushState;
+    private originalReplaceState;
+    private navigationListeners;
+    private _connectionBlocked;
+    private recordInstance;
+    private sessionStartTime;
+    private rrwebRecord;
+    private fullSnapshotTimeout;
+    private recordCanvas;
+    /**
+     * Initialize the HumanBehavior tracker
+     * This is the main entry point - call this once per page
+     */
+    static init(apiKey: string, options?: {
+        ingestionUrl?: string;
+        logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        redactFields?: string[];
+        enableAutomaticTracking?: boolean;
+        suppressConsoleErrors?: boolean;
+        recordCanvas?: boolean;
+        automaticTrackingOptions?: {
+            trackButtons?: boolean;
+            trackLinks?: boolean;
+            trackForms?: boolean;
+            includeText?: boolean;
+            includeClasses?: boolean;
+        };
+    }): HumanBehaviorTracker;
+    constructor(apiKey: string | undefined, ingestionUrl?: string);
+    private init;
+    private ensureInitialized;
+    /**
+     * Setup navigation event tracking for SPA navigation
+     */
+    private setupNavigationTracking;
+    /**
+     * Track navigation events and send custom events
+     */
+    trackNavigationEvent(type: string, fromUrl: string, toUrl: string): Promise<void>;
+    trackPageView(url?: string): Promise<void>;
+    customEvent(eventName: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Setup automatic tracking for buttons, links, and forms
+     */
+    private setupAutomaticTracking;
+    /**
+     * Setup automatic button tracking
+     */
+    private setupAutomaticButtonTracking;
+    /**
+     * Setup automatic link tracking
+     */
+    private setupAutomaticLinkTracking;
+    /**
+     * Setup automatic form tracking
+     */
+    private setupAutomaticFormTracking;
+    /**
+     * Cleanup navigation tracking
+     */
+    private cleanupNavigationTracking;
+    static logToStorage(message: string): void;
+    /**
+     * Configure logging behavior for the SDK
+     * @param config Logger configuration options
+     */
+    static configureLogging(config: {
+        level?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        enableConsole?: boolean;
+        enableStorage?: boolean;
+    }): void;
+    /**
+     * Enable console event tracking
+     */
+    enableConsoleTracking(): void;
+    /**
+     * Disable console event tracking
+     */
+    disableConsoleTracking(): void;
+    private trackConsoleEvent;
+    private setupPageUnloadHandler;
+    viewLogs(): void;
+    /**
+     * Add user identification information to the tracker
+     * If userId is not provided, will use userProperties.email as the userId (if present)
+     */
+    identifyUser({ userProperties }: {
+        userProperties: Record<string, any>;
+    }): Promise<string>;
+    /**
+     * Get current user attributes
+     */
+    getUserAttributes(): Record<string, any>;
+    start(): Promise<void>;
+    /**
+     * Manually trigger a FullSnapshot (for navigation events)
+     * Delays snapshot to avoid capturing mid-animation states
+     */
+    private takeFullSnapshot;
+    stop(): Promise<void>;
+    /**
+     * Add an event to the ingestion queue
+     * Events are sent directly without processing to avoid corruption
+     */
+    addEvent(event: any): Promise<void>;
+    /**
+     * Flush events to the ingestion server
+     * Events are sent in chunks to handle large payloads efficiently
+     */
+    private flush;
+    private setCookie;
+    getCookie(name: string): string | null;
+    /**
+     * Delete a cookie by setting its expiration date to the past
+     * @param name The name of the cookie to delete
+     */
+    private deleteCookie;
+    /**
+     * Clear user data and reset session when user signs out of the site
+     * This should be called when a user logs out of your application to prevent
+     * data contamination between different users
+     */
+    logout(): void;
+    /**
+     * Start redaction functionality for sensitive input fields
+     * @param options Optional configuration for redaction behavior
+     */
+    redact(options?: RedactionOptions): Promise<void>;
+    /**
+     * Set specific fields to be redacted during session recording
+     * Uses rrweb's built-in masking instead of custom redaction processing
+     * @param fields Array of CSS selectors for fields to redact (e.g., ['input[type="password"]', '#email-field'])
+     */
+    setRedactedFields(fields: string[]): void;
+    private restartWithNewRedaction;
+    /**
+     * Check if redaction is currently active
+     */
+    isRedactionActive(): boolean;
+    /**
+     * Get the currently selected fields for redaction
+     */
+    getRedactedFields(): string[];
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Get the current URL being tracked
+     */
+    getCurrentUrl(): string;
+    /**
+     * Get current snapshot frequency info
+     * Uses configured values (5 minutes, 1000 events)
+     */
+    getSnapshotFrequencyInfo(): {
+        sessionDuration: number;
+        currentInterval: number;
+        currentThreshold: number;
+        phase: string;
+    };
+    /**
+     * Test if the tracker can reach the ingestion server
+     */
+    testConnection(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get connection status and recommendations
+     */
+    getConnectionStatus(): {
+        blocked: boolean;
+        recommendations: string[];
+    };
+    /**
+     * Check if the current user is a preexisting user
+     * Returns true if the user has an existing endUserId cookie from a previous session
+     */
+    isPreexistingUser(): boolean;
+    /**
+     * Get user information including whether they are preexisting
+     */
+    getUserInfo(): {
+        endUserId: string | null;
+        sessionId: string;
+        isPreexistingUser: boolean;
+        initialized: boolean;
+    };
+}
+
+interface HumanBehaviorProviderProps {
+    apiKey?: string;
+    client?: HumanBehaviorTracker;
+    children: ReactNode;
+    options?: {
+        ingestionUrl?: string;
+        logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+        redactFields?: string[];
+        suppressConsoleErrors?: boolean;
+        recordCanvas?: boolean;
+    };
+}
+declare const HumanBehaviorProvider: ({ apiKey, client, children, options }: HumanBehaviorProviderProps) => React.JSX.Element;
+declare const useHumanBehavior: () => HumanBehaviorTracker;
+
+declare function createHumanBehaviorLoader(): ({ request }: LoaderFunctionArgs) => Promise<{
+    ENV: {
+        HUMANBEHAVIOR_API_KEY: string | undefined;
+    };
+}>;
+
+export { HumanBehaviorProvider, createHumanBehaviorLoader, useHumanBehavior };