@tracelog/lib 0.11.2 → 0.11.4

package/dist/public-api.d.mts

@@ -0,0 +1,913 @@
+type MetadataPrimitive = string | number | boolean;
+type MetadataNestedValue = MetadataPrimitive | string[] | Record<string, MetadataPrimitive>[];
+type MetadataNestedObject = Record<string, MetadataNestedValue>;
+type MetadataType = MetadataPrimitive | string[] | MetadataNestedObject | MetadataNestedObject[];
+
+/**
+ * Element configuration for viewport tracking with optional identifiers
+ */
+interface ViewportElement {
+    /**
+     * CSS selector for the element
+     * @example '.hero' | '.cta-button' | '#pricing'
+     */
+    selector: string;
+    /**
+     * Optional unique identifier for analytics
+     * Used to distinguish between multiple elements with the same selector
+     * @example 'homepage-hero' | 'pricing-cta' | 'customer-testimonials'
+     */
+    id?: string;
+    /**
+     * Optional human-readable name for dashboards and reports
+     * @example 'Homepage Hero Banner' | 'Pricing Page CTA' | 'Customer Testimonials Section'
+     */
+    name?: string;
+}
+/**
+ * Configuration for viewport visibility tracking
+ */
+interface ViewportConfig {
+    /**
+     * Elements to track with optional identifiers
+     * Provides analytics support with business identifiers
+     * @example [{ selector: '.hero', id: 'homepage-hero', name: 'Homepage Hero Banner' }]
+     */
+    elements: ViewportElement[];
+    /**
+     * Minimum percentage of element that must be visible (0-1)
+     * @default 0.5 (50%)
+     */
+    threshold?: number;
+    /**
+     * Minimum time (ms) element must be visible to count as a view
+     * @default 1000 (1 second)
+     */
+    minDwellTime?: number;
+    /**
+     * Cooldown period (ms) before same element can fire visibility event again
+     * Prevents repeated events from carousels, sticky headers, and scrolling patterns
+     * @default 60000 (60 seconds)
+     */
+    cooldownPeriod?: number;
+    /**
+     * Maximum number of elements to track simultaneously (Phase 3)
+     * Prevents memory/server issues with broad selectors
+     * @default 100
+     */
+    maxTrackedElements?: number;
+}
+
+interface Config {
+    /** Session inactivity timeout in milliseconds. @default 900000 */
+    sessionTimeout?: number;
+    /** Metadata appended to every tracked event. */
+    globalMetadata?: Record<string, MetadataType>;
+    /** Query parameters to remove before tracking URLs. */
+    sensitiveQueryParams?: string[];
+    /** Error event sampling rate between 0 and 1. @default 1 */
+    errorSampling?: number;
+    /** Event sampling rate between 0 and 1. @default 1 */
+    samplingRate?: number;
+    /** CSS selector to manually override primary scroll container detection. */
+    primaryScrollSelector?: string;
+    /** Viewport visibility tracking configuration. */
+    viewport?: ViewportConfig;
+    /** Page view throttle duration in milliseconds to prevent rapid navigation spam. @default 1000 */
+    pageViewThrottleMs?: number;
+    /** Click throttle duration in milliseconds to prevent double-clicks and rapid spam. @default 300 */
+    clickThrottleMs?: number;
+    /** Maximum number of same custom event name allowed per minute to prevent infinite loops. @default 60 */
+    maxSameEventPerMinute?: number;
+    /** Optional configuration for third-party integrations. */
+    integrations?: {
+        /** TraceLog integration options. */
+        tracelog?: {
+            /** Required project ID TraceLog SaaS integration. */
+            projectId: string;
+        };
+        /** Custom integration options. */
+        custom?: {
+            /** Endpoint for collecting events. */
+            collectApiUrl: string;
+            /** Allow HTTP URLs (not recommended for production). @default false */
+            allowHttp?: boolean;
+        };
+        /** Google Analytics integration options. */
+        googleAnalytics?: {
+            /** Required measurement ID for Google Analytics. */
+            measurementId: string;
+        };
+    };
+}
+declare enum SpecialApiUrl {
+    Localhost = "localhost:8080",
+    Fail = "localhost:9999"
+}
+
+declare enum DeviceType {
+    Mobile = "mobile",
+    Tablet = "tablet",
+    Desktop = "desktop",
+    Unknown = "unknown"
+}
+
+type SessionEndReason = 'inactivity' | 'page_unload' | 'manual_stop' | 'orphaned_cleanup' | 'tab_closed';
+
+/**
+ * Coordinate information from a click event
+ * Includes absolute and relative positioning
+ */
+type ClickCoordinates = Pick<ClickData, 'x' | 'y' | 'relativeX' | 'relativeY'>;
+/**
+ * Web performance metric types tracked by the library
+ * - LCP: Largest Contentful Paint
+ * - CLS: Cumulative Layout Shift
+ * - INP: Interaction to Next Paint
+ * - FCP: First Contentful Paint
+ * - TTFB: Time to First Byte
+ * - LONG_TASK: Tasks exceeding 50ms
+ */
+type WebVitalType = 'LCP' | 'CLS' | 'INP' | 'FCP' | 'TTFB' | 'LONG_TASK';
+/**
+ * Core event types tracked by TraceLog
+ */
+declare enum EventType {
+    /** Page navigation and view tracking */
+    PAGE_VIEW = "page_view",
+    /** User click interactions */
+    CLICK = "click",
+    /** Scroll depth and behavior */
+    SCROLL = "scroll",
+    /** Session initialization */
+    SESSION_START = "session_start",
+    /** Session termination */
+    SESSION_END = "session_end",
+    /** Custom business events */
+    CUSTOM = "custom",
+    /** Performance metrics */
+    WEB_VITALS = "web_vitals",
+    /** JavaScript errors and rejections */
+    ERROR = "error",
+    /** Element visibility tracking */
+    VIEWPORT_VISIBLE = "viewport_visible"
+}
+/**
+ * Scroll direction indicators
+ */
+declare enum ScrollDirection {
+    /** Scrolling upward */
+    UP = "up",
+    /** Scrolling downward */
+    DOWN = "down"
+}
+/**
+ * JavaScript error classification
+ */
+declare enum ErrorType {
+    /** Runtime JavaScript errors */
+    JS_ERROR = "js_error",
+    /** Unhandled promise rejections */
+    PROMISE_REJECTION = "promise_rejection"
+}
+/**
+ * Scroll event data captured during user scrolling
+ */
+interface ScrollData {
+    /** Current scroll depth as percentage (0-100) */
+    depth: number;
+    /** Direction of scroll movement */
+    direction: ScrollDirection;
+    /** CSS selector of the scrolled container */
+    container_selector: string;
+    /** Whether this is the primary viewport scroll */
+    is_primary: boolean;
+    /** Scroll velocity in pixels per second */
+    velocity: number;
+    /** Maximum scroll depth reached during session (0-100) */
+    max_depth_reached: number;
+}
+/**
+ * Click event data capturing user interaction details
+ */
+interface ClickData {
+    /** Absolute X coordinate in viewport (pixels) */
+    x: number;
+    /** Absolute Y coordinate in viewport (pixels) */
+    y: number;
+    /** Relative X position within element (0-1) */
+    relativeX: number;
+    /** Relative Y position within element (0-1) */
+    relativeY: number;
+    /** Element ID attribute */
+    id?: string;
+    /** Element class attribute */
+    class?: string;
+    /** HTML tag name */
+    tag?: string;
+    /** Element text content (truncated) */
+    text?: string;
+    /** Link href for anchor elements */
+    href?: string;
+    /** Element title attribute */
+    title?: string;
+    /** Image alt text for img elements */
+    alt?: string;
+    /** ARIA role attribute */
+    role?: string;
+    /** ARIA label attribute */
+    ariaLabel?: string;
+    /** Custom data attributes (data-*) */
+    dataAttributes?: Record<string, string>;
+}
+/**
+ * Element data for specialized click tracking
+ * Used for form inputs and interactive elements
+ */
+interface ClickTrackingElementData {
+    /** DOM element being tracked */
+    element: HTMLElement;
+    /** Descriptive name for the element */
+    name: string;
+    /** Element value (for inputs) */
+    value?: string;
+}
+/**
+ * Custom event data for business-specific tracking
+ */
+interface CustomEventData {
+    /** Event name identifier */
+    name: string;
+    /** Additional event metadata */
+    metadata?: Record<string, MetadataType> | Record<string, MetadataType>[];
+}
+/**
+ * Web performance metrics data
+ */
+interface WebVitalsData {
+    /** Type of performance metric */
+    type: WebVitalType;
+    /** Metric value (varies by type) */
+    value: number;
+}
+/**
+ * JavaScript error details
+ */
+interface ErrorData {
+    /** Error classification */
+    type: ErrorType;
+    /** Error message text */
+    message: string;
+    /** Source file where error occurred */
+    filename?: string;
+    /** Line number in source file */
+    line?: number;
+    /** Column number in source file */
+    column?: number;
+}
+/**
+ * UTM campaign tracking parameters
+ */
+interface UTM {
+    /** Campaign source (e.g., google, newsletter) */
+    source?: string;
+    /** Campaign medium (e.g., cpc, email) */
+    medium?: string;
+    /** Campaign name identifier */
+    campaign?: string;
+    /** Campaign search term */
+    term?: string;
+    /** Campaign content variation */
+    content?: string;
+}
+/**
+ * Page view navigation data
+ */
+interface PageViewData {
+    /** Previous page URL */
+    referrer?: string;
+    /** Page title from document */
+    title?: string;
+    /** URL pathname */
+    pathname?: string;
+    /** URL query string */
+    search?: string;
+    /** URL hash fragment */
+    hash?: string;
+}
+/**
+ * Data captured when element becomes visible
+ */
+interface ViewportEventData {
+    /** CSS selector that matched the element */
+    selector: string;
+    /** Optional unique identifier for analytics (if configured) */
+    id?: string;
+    /** Optional human-readable name (if configured) */
+    name?: string;
+    /** Actual time (ms) element was visible before event fired */
+    dwellTime: number;
+    /** Actual visibility ratio when event fired (0-1) */
+    visibilityRatio: number;
+}
+/**
+ * Complete event data structure
+ * All events share base properties with type-specific data
+ */
+interface EventData {
+    /** Unique event identifier */
+    id: string;
+    /** Event type classification */
+    type: EventType;
+    /** Current page URL where event occurred */
+    page_url: string;
+    /** Unix timestamp (milliseconds) */
+    timestamp: number;
+    /** HTTP referrer header */
+    referrer?: string;
+    /** Previous page URL for navigation events */
+    from_page_url?: string;
+    /** Scroll event details (when type is SCROLL) */
+    scroll_data?: ScrollData;
+    /** Click event details (when type is CLICK) */
+    click_data?: ClickData;
+    /** Custom event details (when type is CUSTOM) */
+    custom_event?: CustomEventData;
+    /** Performance metrics (when type is WEB_VITALS) */
+    web_vitals?: WebVitalsData;
+    /** Page view details (when type is PAGE_VIEW) */
+    page_view?: PageViewData;
+    /** Session termination reason (when type is SESSION_END) */
+    session_end_reason?: SessionEndReason;
+    /** Error details (when type is ERROR) */
+    error_data?: ErrorData;
+    /** Viewport visibility details (when type is VIEWPORT_VISIBLE) */
+    viewport_data?: ViewportEventData;
+    /** Campaign tracking parameters */
+    utm?: UTM;
+}
+
+interface EventsQueue {
+    user_id: string;
+    session_id: string;
+    device: DeviceType;
+    events: EventData[];
+    global_metadata?: Record<string, MetadataType>;
+}
+/**
+ * Extended queue structure for localStorage persistence with expiration tracking.
+ */
+interface PersistedEventsQueue extends EventsQueue {
+    timestamp: number;
+}
+
+type EmitterCallback<T = any> = (data: T) => void;
+declare enum EmitterEvent {
+    EVENT = "event",
+    QUEUE = "queue"
+}
+interface EmitterMap {
+    [EmitterEvent.EVENT]: EventData;
+    [EmitterEvent.QUEUE]: EventsQueue;
+}
+
+/**
+ * Custom error types for TraceLog
+ */
+/**
+ * Represents a permanent HTTP error (4xx) that should not be retried
+ * Examples: 400 Bad Request, 403 Forbidden, 404 Not Found
+ */
+declare class PermanentError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+
+/**
+ * Log levels for the dual logging system
+ */
+type LogLevel = 'CLIENT_ERROR' | 'CLIENT_WARN' | 'INFO' | 'ERROR' | 'WARN' | 'DEBUG' | 'VERBOSE';
+
+/**
+ * App modes for the TraceLog Library
+ */
+declare enum Mode {
+    QA = "qa"
+}
+
+type PrimaryScrollEvent = EventData & {
+    type: EventType.SCROLL;
+    scroll_data: ScrollData & {
+        is_primary: true;
+    };
+};
+type SecondaryScrollEvent = EventData & {
+    type: EventType.SCROLL;
+    scroll_data: ScrollData & {
+        is_primary: false;
+    };
+};
+declare function isPrimaryScrollEvent(event: EventData): event is PrimaryScrollEvent;
+declare function isSecondaryScrollEvent(event: EventData): event is SecondaryScrollEvent;
+
+interface State {
+    mode?: Mode;
+    collectApiUrl: string;
+    config: Config;
+    sessionId: string | null;
+    userId: string;
+    device: DeviceType;
+    pageUrl: string;
+    hasStartSession: boolean;
+    suppressNextScroll: boolean;
+    scrollEventCount?: number;
+}
+
+declare class Emitter {
+    private readonly listeners;
+    on<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
+    off<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
+    emit<K extends keyof EmitterMap>(event: K, data: EmitterMap[K]): void;
+    removeAllListeners(): void;
+}
+
+declare abstract class StateManager {
+    protected get<T extends keyof State>(key: T): State[T];
+    protected set<T extends keyof State>(key: T, value: State[T]): void;
+    protected getState(): Readonly<State>;
+}
+
+/**
+ * Manages localStorage and sessionStorage with automatic fallback to in-memory storage.
+ * Provides a consistent interface for storing session data, configuration,
+ * and analytics metadata across browser environments.
+ */
+declare class StorageManager {
+    private readonly storage;
+    private readonly sessionStorageRef;
+    private readonly fallbackStorage;
+    private readonly fallbackSessionStorage;
+    private hasQuotaExceededError;
+    constructor();
+    /**
+     * Retrieves an item from storage
+     */
+    getItem(key: string): string | null;
+    /**
+     * Stores an item in storage
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Removes an item from storage
+     */
+    removeItem(key: string): void;
+    /**
+     * Clears all TracLog-related items from storage
+     */
+    clear(): void;
+    /**
+     * Checks if storage is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Checks if a QuotaExceededError has occurred
+     * This indicates localStorage is full and data may not persist
+     */
+    hasQuotaError(): boolean;
+    /**
+     * Attempts to cleanup old TraceLog data from storage to free up space
+     * Returns true if any data was removed, false otherwise
+     */
+    private cleanupOldData;
+    /**
+     * Initialize storage (localStorage or sessionStorage) with feature detection
+     */
+    private initializeStorage;
+    /**
+     * Retrieves an item from sessionStorage
+     */
+    getSessionItem(key: string): string | null;
+    /**
+     * Stores an item in sessionStorage
+     */
+    setSessionItem(key: string, value: string): void;
+    /**
+     * Removes an item from sessionStorage
+     */
+    removeSessionItem(key: string): void;
+}
+
+declare global {
+    interface Window {
+        gtag?: (...args: unknown[]) => void;
+        dataLayer?: unknown[];
+    }
+}
+declare class GoogleAnalyticsIntegration extends StateManager {
+    private isInitialized;
+    initialize(): Promise<void>;
+    trackEvent(eventName: string, metadata: Record<string, MetadataType> | Record<string, MetadataType>[]): void;
+    cleanup(): void;
+    private isScriptAlreadyLoaded;
+    private loadScript;
+    private configureGtag;
+}
+
+declare class EventManager extends StateManager {
+    private readonly googleAnalytics;
+    private readonly dataSender;
+    private readonly emitter;
+    private eventsQueue;
+    private pendingEventsBuffer;
+    private readonly recentEventFingerprints;
+    private sendIntervalId;
+    private rateLimitCounter;
+    private rateLimitWindowStart;
+    private readonly perEventRateLimits;
+    private sessionEventCounts;
+    private lastSessionId;
+    constructor(storeManager: StorageManager, googleAnalytics?: GoogleAnalyticsIntegration | null, emitter?: Emitter | null);
+    recoverPersistedEvents(): Promise<void>;
+    track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, session_end_reason, viewport_data, }: Partial<EventData>): void;
+    stop(): void;
+    flushImmediately(): Promise<boolean>;
+    flushImmediatelySync(): boolean;
+    getQueueLength(): number;
+    flushPendingEvents(): void;
+    private clearSendInterval;
+    private flushEvents;
+    private sendEventsQueue;
+    private buildEventsPayload;
+    private buildEventPayload;
+    /**
+     * Checks if event is a duplicate using time-based cache
+     * Tracks recent event fingerprints with timestamp-based cleanup
+     */
+    private isDuplicateEvent;
+    /**
+     * Prunes old fingerprints from cache based on timestamp
+     * Removes entries older than 10x the duplicate threshold (5 seconds)
+     */
+    private pruneOldFingerprints;
+    private createEventFingerprint;
+    private createEventSignature;
+    private addToQueue;
+    private startSendInterval;
+    private handleGoogleAnalyticsIntegration;
+    private shouldSample;
+    private checkRateLimit;
+    /**
+     * Checks per-event-name rate limiting to prevent infinite loops in user code
+     * Tracks timestamps per event name and limits to maxSameEventPerMinute per minute
+     */
+    private checkPerEventRateLimit;
+    /**
+     * Gets the per-session limit for a specific event type (Phase 3)
+     */
+    private getTypeLimitForEvent;
+    private removeProcessedEvents;
+    private emitEvent;
+    private emitEventsQueue;
+}
+
+declare class ClickHandler extends StateManager {
+    private readonly eventManager;
+    private readonly lastClickTimes;
+    private clickHandler?;
+    private lastPruneTime;
+    constructor(eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    private shouldIgnoreElement;
+    /**
+     * Checks per-element click throttling to prevent double-clicks and rapid spam
+     * Returns true if the click should be tracked, false if throttled
+     */
+    private checkClickThrottle;
+    /**
+     * Prunes stale entries from the throttle cache to prevent memory leaks
+     * Uses TTL-based eviction (5 minutes) and enforces max size limit
+     * Called during checkClickThrottle with built-in rate limiting (every 30 seconds)
+     */
+    private pruneThrottleCache;
+    /**
+     * Creates a stable signature for an element to track throttling
+     * Priority: id > data-testid > data-tlog-name > DOM path
+     */
+    private getElementSignature;
+    /**
+     * Generates a DOM path for an element (e.g., "body>div>button")
+     */
+    private getElementPath;
+    private findTrackingElement;
+    private getRelevantClickElement;
+    private clamp;
+    private calculateClickCoordinates;
+    private extractTrackingData;
+    private generateClickData;
+    private sanitizeText;
+    private getRelevantText;
+    private extractElementAttributes;
+    private createCustomEventData;
+}
+
+/**
+ * Simplified error handler for tracking JavaScript errors and unhandled promise rejections
+ * Includes PII sanitization and sampling support
+ */
+declare class ErrorHandler extends StateManager {
+    private readonly eventManager;
+    private readonly recentErrors;
+    private errorBurstCounter;
+    private burstWindowStart;
+    private burstBackoffUntil;
+    constructor(eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    /**
+     * Checks sampling rate and burst detection (Phase 3)
+     * Returns false if in cooldown period after burst detection
+     */
+    private shouldSample;
+    private readonly handleError;
+    private readonly handleRejection;
+    private extractRejectionMessage;
+    private sanitize;
+    private shouldSuppressError;
+    private pruneOldErrors;
+}
+
+declare class PageViewHandler extends StateManager {
+    private readonly eventManager;
+    private readonly onTrack;
+    private originalPushState?;
+    private originalReplaceState?;
+    private lastPageViewTime;
+    constructor(eventManager: EventManager, onTrack: () => void);
+    startTracking(): void;
+    stopTracking(): void;
+    private patchHistory;
+    private readonly trackCurrentPage;
+    private trackInitialPageView;
+    private extractPageViewData;
+}
+
+declare class PerformanceHandler extends StateManager {
+    private readonly eventManager;
+    private readonly reportedByNav;
+    private readonly navigationHistory;
+    private readonly observers;
+    private readonly vitalThresholds;
+    private lastLongTaskSentAt;
+    constructor(eventManager: EventManager);
+    startTracking(): Promise<void>;
+    stopTracking(): void;
+    private observeWebVitalsFallback;
+    private initWebVitals;
+    private reportTTFB;
+    private observeLongTasks;
+    private sendVital;
+    private trackWebVital;
+    private getNavigationId;
+    private isObserverSupported;
+    private safeObserve;
+    private shouldSendVital;
+}
+
+declare class ScrollHandler extends StateManager {
+    private readonly eventManager;
+    private readonly containers;
+    private limitWarningLogged;
+    private minDepthChange;
+    private minIntervalMs;
+    private maxEventsPerSession;
+    private containerDiscoveryTimeoutId;
+    constructor(eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    private tryDetectScrollContainers;
+    private applyPrimaryScrollSelectorIfConfigured;
+    private findScrollableElements;
+    private getElementSelector;
+    private determineIfPrimary;
+    private setupScrollContainer;
+    private processScrollEvent;
+    private shouldEmitScrollEvent;
+    private hasReachedSessionLimit;
+    private hasElapsedMinimumInterval;
+    private hasSignificantDepthChange;
+    private logLimitOnce;
+    private applyConfigOverrides;
+    private isWindowScrollable;
+    private clearContainerTimer;
+    private getScrollDirection;
+    private calculateScrollDepth;
+    private calculateScrollData;
+    private getScrollTop;
+    private getViewportHeight;
+    private getScrollHeight;
+    private isElementScrollable;
+    private applyPrimaryScrollSelector;
+    private updateContainerPrimary;
+}
+
+declare class SessionHandler extends StateManager {
+    private readonly eventManager;
+    private readonly storageManager;
+    private sessionManager;
+    private destroyed;
+    constructor(storageManager: StorageManager, eventManager: EventManager);
+    startTracking(): void;
+    private isActive;
+    private cleanupSessionManager;
+    stopTracking(): void;
+    destroy(): void;
+}
+
+/**
+ * Testing bridge interface for E2E tests
+ * Only available when NODE_ENV=development
+ */
+interface TraceLogTestBridge {
+    readonly initialized: boolean;
+    init(config?: Config): Promise<void>;
+    destroy(): void;
+    isInitializing(): boolean;
+    sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[]): void;
+    on(event: string, callback: (data: any) => void): void;
+    off(event: string, callback: (data: any) => void): void;
+    getSessionData(): Record<string, unknown> | null;
+    setSessionTimeout(timeout: number): void;
+    getQueueLength(): number;
+    forceInitLock(enabled?: boolean): void;
+    simulatePersistedEvents(events: any[]): void;
+    get<T extends keyof State>(key: T): State[T];
+    getStorageManager(): StorageManager | null;
+    getEventManager(): EventManager | null;
+    getSessionHandler(): SessionHandler | null;
+    getPageViewHandler(): PageViewHandler | null;
+    getClickHandler(): ClickHandler | null;
+    getScrollHandler(): ScrollHandler | null;
+    getPerformanceHandler(): PerformanceHandler | null;
+    getErrorHandler(): ErrorHandler | null;
+    getGoogleAnalytics(): GoogleAnalyticsIntegration | null;
+}
+
+/**
+ * Custom error classes for TraceLog validation errors
+ * Provides better error handling and consistency across validation layers
+ */
+/**
+ * Base class for all TraceLog validation errors
+ */
+declare abstract class TraceLogValidationError extends Error {
+    readonly errorCode: string;
+    readonly layer: 'config' | 'app' | 'runtime';
+    constructor(message: string, errorCode: string, layer: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when app configuration validation fails
+ */
+declare class AppConfigValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when session timeout validation fails
+ */
+declare class SessionTimeoutValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when sampling rate validation fails
+ */
+declare class SamplingRateValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when integrations validation fails
+ */
+declare class IntegrationValidationError extends TraceLogValidationError {
+    constructor(message: string, layer?: 'config' | 'app' | 'runtime');
+}
+/**
+ * Thrown when initialization exceeds the maximum allowed timeout
+ */
+declare class InitializationTimeoutError extends TraceLogValidationError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, layer?: 'config' | 'app' | 'runtime');
+}
+
+declare global {
+    interface Window {
+        /**
+         * Flag to disable TraceLog initialization
+         * Set to true to prevent the library from running
+         */
+        __traceLogDisabled?: boolean;
+        /**
+         * Testing bridge for E2E tests
+         * Only available when NODE_ENV=development
+         */
+        __traceLogBridge?: TraceLogTestBridge;
+    }
+}
+
+declare const MAX_CUSTOM_EVENT_NAME_LENGTH = 120;
+declare const MAX_CUSTOM_EVENT_STRING_SIZE: number;
+declare const MAX_CUSTOM_EVENT_KEYS = 10;
+declare const MAX_CUSTOM_EVENT_ARRAY_SIZE = 10;
+declare const MAX_NESTED_OBJECT_KEYS = 20;
+declare const MAX_METADATA_NESTING_DEPTH = 1;
+declare const MAX_STRING_LENGTH = 1000;
+declare const MAX_STRING_LENGTH_IN_ARRAY = 500;
+declare const MAX_ARRAY_LENGTH = 100;
+
+declare const PERFORMANCE_CONFIG: {
+    readonly WEB_VITALS_THRESHOLDS: Record<WebVitalType, number>;
+};
+declare const DATA_PROTECTION: {
+    readonly PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+};
+declare const ENGAGEMENT_THRESHOLDS: {
+    readonly LOW_ACTIVITY_EVENT_COUNT: 50;
+    readonly HIGH_ACTIVITY_EVENT_COUNT: 1000;
+    readonly MIN_EVENTS_FOR_DYNAMIC_CALCULATION: 100;
+    readonly MIN_EVENTS_FOR_TREND_ANALYSIS: 30;
+    readonly BOUNCE_RATE_SESSION_THRESHOLD: 1;
+    readonly MIN_ENGAGED_SESSION_DURATION_MS: number;
+    readonly MIN_SCROLL_DEPTH_ENGAGEMENT: 25;
+};
+declare const SESSION_ANALYTICS: {
+    readonly INACTIVITY_TIMEOUT_MS: number;
+    readonly SHORT_SESSION_THRESHOLD_MS: number;
+    readonly MEDIUM_SESSION_THRESHOLD_MS: number;
+    readonly LONG_SESSION_THRESHOLD_MS: number;
+    readonly MAX_REALISTIC_SESSION_DURATION_MS: number;
+};
+declare const DEVICE_ANALYTICS: {
+    readonly MOBILE_MAX_WIDTH: 768;
+    readonly TABLET_MAX_WIDTH: 1024;
+    readonly MOBILE_PERFORMANCE_FACTOR: 1.5;
+    readonly TABLET_PERFORMANCE_FACTOR: 1.2;
+};
+declare const CONTENT_ANALYTICS: {
+    readonly MIN_TEXT_LENGTH_FOR_ANALYSIS: 10;
+    readonly MIN_CLICKS_FOR_HOT_ELEMENT: 10;
+    readonly MIN_SCROLL_COMPLETION_PERCENT: 80;
+    readonly MIN_TIME_ON_PAGE_FOR_READ_MS: number;
+};
+declare const INSIGHT_THRESHOLDS: {
+    readonly SIGNIFICANT_CHANGE_PERCENT: 20;
+    readonly MAJOR_CHANGE_PERCENT: 50;
+    readonly MIN_EVENTS_FOR_INSIGHT: 100;
+    readonly MIN_SESSIONS_FOR_INSIGHT: 10;
+    readonly MIN_CORRELATION_STRENGTH: 0.7;
+    readonly LOW_ERROR_RATE_PERCENT: 1;
+    readonly HIGH_ERROR_RATE_PERCENT: 5;
+    readonly CRITICAL_ERROR_RATE_PERCENT: 10;
+};
+declare const TEMPORAL_ANALYSIS: {
+    readonly SHORT_TERM_TREND_HOURS: 24;
+    readonly MEDIUM_TERM_TREND_DAYS: 7;
+    readonly LONG_TERM_TREND_DAYS: 30;
+    readonly MIN_DATA_POINTS_FOR_TREND: 5;
+    readonly WEEKLY_PATTERN_MIN_WEEKS: 4;
+    readonly DAILY_PATTERN_MIN_DAYS: 14;
+};
+declare const SEGMENTATION_ANALYTICS: {
+    readonly MIN_SEGMENT_SIZE: 10;
+    readonly MIN_COHORT_SIZE: 5;
+    readonly COHORT_ANALYSIS_DAYS: readonly [1, 3, 7, 14, 30];
+    readonly MIN_FUNNEL_EVENTS: 20;
+};
+declare const ANALYTICS_QUERY_LIMITS: {
+    readonly DEFAULT_EVENTS_LIMIT: 5;
+    readonly DEFAULT_SESSIONS_LIMIT: 5;
+    readonly DEFAULT_PAGES_LIMIT: 5;
+    readonly MAX_EVENTS_FOR_DEEP_ANALYSIS: 10000;
+    readonly MAX_TIME_RANGE_DAYS: 365;
+    readonly ANALYTICS_BATCH_SIZE: 1000;
+};
+declare const ANOMALY_DETECTION: {
+    readonly ANOMALY_THRESHOLD_SIGMA: 2.5;
+    readonly STRONG_ANOMALY_THRESHOLD_SIGMA: 3;
+    readonly TRAFFIC_DROP_ALERT_PERCENT: -30;
+    readonly TRAFFIC_SPIKE_ALERT_PERCENT: 200;
+    readonly MIN_BASELINE_DAYS: 7;
+    readonly MIN_EVENTS_FOR_ANOMALY_DETECTION: 50;
+};
+declare const SPECIAL_PAGE_URLS: {
+    readonly PAGE_URL_EXCLUDED: "excluded";
+    readonly PAGE_URL_UNKNOWN: "unknown";
+};
+
+declare const tracelog: {
+    init: (config?: Config) => Promise<void>;
+    event: (name: string, metadata?: Record<string, MetadataType> | Record<string, MetadataType>[]) => void;
+    on: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
+    off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
+    isInitialized: () => boolean;
+    destroy: () => void;
+};
+
+export { ANALYTICS_QUERY_LIMITS, ANOMALY_DETECTION, AppConfigValidationError, CONTENT_ANALYTICS, type ClickCoordinates, type ClickData, type ClickTrackingElementData, type Config, type CustomEventData, DATA_PROTECTION, DEVICE_ANALYTICS, DeviceType, ENGAGEMENT_THRESHOLDS, type EmitterCallback, EmitterEvent, type EmitterMap, type ErrorData, ErrorType, type EventData, EventType, type EventsQueue, INSIGHT_THRESHOLDS, InitializationTimeoutError, IntegrationValidationError, type LogLevel, MAX_ARRAY_LENGTH, MAX_CUSTOM_EVENT_ARRAY_SIZE, MAX_CUSTOM_EVENT_KEYS, MAX_CUSTOM_EVENT_NAME_LENGTH, MAX_CUSTOM_EVENT_STRING_SIZE, MAX_METADATA_NESTING_DEPTH, MAX_NESTED_OBJECT_KEYS, MAX_STRING_LENGTH, MAX_STRING_LENGTH_IN_ARRAY, type MetadataType, Mode, PERFORMANCE_CONFIG, type PageViewData, PermanentError, type PersistedEventsQueue, type PrimaryScrollEvent, SEGMENTATION_ANALYTICS, SESSION_ANALYTICS, SPECIAL_PAGE_URLS, SamplingRateValidationError, type ScrollData, ScrollDirection, type SecondaryScrollEvent, type SessionEndReason, SessionTimeoutValidationError, SpecialApiUrl, type State, TEMPORAL_ANALYSIS, type TraceLogTestBridge, TraceLogValidationError, type UTM, type ViewportConfig, type ViewportElement, type ViewportEventData, type WebVitalType, type WebVitalsData, isPrimaryScrollEvent, isSecondaryScrollEvent, tracelog };