@seekora-ai/search-sdk 1.0.0 → 1.0.2

package/dist/src/context-collector.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Context Collector for Seekora SDK
+ *
+ * Collects browser context, device information, and fingerprinting
+ * for enriching analytics events with comprehensive user environment data.
+ *
+ * Uses FingerprintJS Open Source for industry-standard device fingerprinting
+ * with 50+ browser signals for high accuracy cross-session identification.
+ */
+/**
+ * Browser and device context collected for analytics enrichment
+ */
+export interface BrowserContext {
+    screen_width: number;
+    screen_height: number;
+    viewport_width: number;
+    viewport_height: number;
+    color_depth: number;
+    pixel_ratio: number;
+    browser_name: string;
+    browser_version: string;
+    browser_language: string;
+    browser_languages: string[];
+    timezone: string;
+    timezone_offset: number;
+    page_url: string;
+    page_path: string;
+    page_title: string;
+    page_referrer: string;
+    document_visibility: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    connection_type?: string;
+    connection_effective_type?: string;
+    connection_downlink?: number;
+    connection_rtt?: number;
+    device_fingerprint?: string;
+    platform: string;
+    is_mobile: boolean;
+    is_tablet: boolean;
+    is_touch_device: boolean;
+    hardware_concurrency?: number;
+    max_touch_points?: number;
+    device_memory?: number;
+}
+/**
+ * Configuration for context collection
+ */
+export interface ContextCollectorConfig {
+    /**
+     * Enable device fingerprinting (generates a stable device ID)
+     * @default true
+     */
+    enableFingerprinting?: boolean;
+    /**
+     * Use FingerprintJS library for high-accuracy fingerprinting (recommended)
+     * Falls back to manual implementation if FingerprintJS is not available
+     * @default true
+     */
+    useFingerprintJS?: boolean;
+    /**
+     * Enable canvas fingerprinting (only used in manual mode)
+     * @default true
+     */
+    enableCanvasFingerprint?: boolean;
+    /**
+     * Enable WebGL fingerprinting (only used in manual mode)
+     * @default true
+     */
+    enableWebGLFingerprint?: boolean;
+    /**
+     * Enable audio fingerprinting (only used in manual mode)
+     * @default false
+     */
+    enableAudioFingerprint?: boolean;
+    /**
+     * Automatically collect context on initialization
+     * @default true
+     */
+    autoCollect?: boolean;
+    /**
+     * Cache context for this many milliseconds (0 = no caching)
+     * @default 30000 (30 seconds)
+     */
+    cacheDuration?: number;
+    /**
+     * Storage key for fingerprint persistence
+     * @default 'seekora_device_fp'
+     */
+    fingerprintStorageKey?: string;
+    /**
+     * Enable extended fingerprint components for higher uniqueness
+     * Includes fonts, plugins, and other signals
+     * @default true
+     */
+    enableExtendedComponents?: boolean;
+}
+/**
+ * ContextCollector class for gathering browser and device context
+ *
+ * Uses FingerprintJS Open Source for industry-standard fingerprinting
+ * with automatic fallback to manual implementation if unavailable.
+ */
+export declare class ContextCollector {
+    private config;
+    private cachedContext;
+    private cacheTimestamp;
+    private cachedFingerprint;
+    private fingerprintJSAgent;
+    private fingerprintJSLoading;
+    private usingFingerprintJS;
+    constructor(config?: ContextCollectorConfig);
+    /**
+     * Initialize FingerprintJS agent (async, non-blocking)
+     */
+    private initFingerprintJS;
+    /**
+     * Get FingerprintJS agent, waiting for initialization if needed
+     */
+    private getFingerprintJSAgent;
+    /**
+     * Check if running in browser environment
+     */
+    private isBrowser;
+    /**
+     * Collect complete browser context
+     */
+    collect(): Promise<BrowserContext>;
+    /**
+     * Collect fresh context without caching
+     */
+    private collectFresh;
+    /**
+     * Get server-side context (for Node.js environments)
+     */
+    private getServerContext;
+    /**
+     * Get viewport width
+     */
+    private getViewportWidth;
+    /**
+     * Get viewport height
+     */
+    private getViewportHeight;
+    /**
+     * Get document visibility state
+     */
+    private getDocumentVisibility;
+    /**
+     * Get timezone name
+     */
+    private getTimezone;
+    /**
+     * Parse UTM parameters from URL
+     */
+    private parseUTMParameters;
+    /**
+     * Get connection information from Network Information API
+     */
+    private getConnectionInfo;
+    /**
+     * Parse browser name and version from user agent
+     */
+    private parseBrowserInfo;
+    /**
+     * Detect platform from user agent
+     */
+    private detectPlatform;
+    /**
+     * Check if device is mobile
+     */
+    private isMobile;
+    /**
+     * Check if device is tablet
+     */
+    private isTablet;
+    /**
+     * Check if device supports touch
+     */
+    private isTouchDevice;
+    /**
+     * Sanitize URL to remove sensitive query parameters
+     */
+    private sanitizeUrl;
+    /**
+     * Load cached fingerprint from storage
+     */
+    private loadCachedFingerprint;
+    /**
+     * Get or generate device fingerprint
+     */
+    private getOrGenerateFingerprint;
+    /**
+     * Generate device fingerprint using FingerprintJS or manual fallback
+     *
+     * FingerprintJS provides ~99.5% accuracy with 50+ browser signals
+     * Manual fallback provides ~70% accuracy with 15+ signals
+     */
+    private generateFingerprint;
+    /**
+     * Generate fingerprint manually using browser characteristics
+     * Used as fallback when FingerprintJS is not available
+     */
+    private generateManualFingerprint;
+    /**
+     * Get audio fingerprint using AudioContext
+     */
+    private getAudioFingerprint;
+    /**
+     * Get font fingerprint by testing font availability
+     */
+    private getFontFingerprint;
+    /**
+     * Get additional WebGL parameters for fingerprinting
+     */
+    private getWebGLParameters;
+    /**
+     * Get canvas fingerprint
+     */
+    private getCanvasFingerprint;
+    /**
+     * Get WebGL fingerprint
+     */
+    private getWebGLFingerprint;
+    /**
+     * Hash array of components into a fingerprint string
+     */
+    private hashComponents;
+    /**
+     * Simple hash function (djb2 variant)
+     */
+    private simpleHash;
+    /**
+     * Clear cached context
+     */
+    clearCache(): void;
+    /**
+     * Clear cached fingerprint (both in memory and storage)
+     */
+    clearFingerprint(): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<ContextCollectorConfig>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<ContextCollectorConfig>): void;
+    /**
+     * Check if using FingerprintJS (vs manual implementation)
+     */
+    isUsingFingerprintJS(): boolean;
+    /**
+     * Get fingerprint info including method used and confidence
+     */
+    getFingerprintInfo(): Promise<{
+        fingerprint: string;
+        method: 'fingerprintjs' | 'manual';
+        confidence?: number;
+        componentsCount?: number;
+    }>;
+}
+/**
+ * Get or create the default context collector
+ */
+export declare function getDefaultContextCollector(config?: ContextCollectorConfig): ContextCollector;
+/**
+ * Collect browser context using the default collector
+ */
+export declare function collectBrowserContext(config?: ContextCollectorConfig): Promise<BrowserContext>;