@jayeshsadhwani/telemetry-sdk/dist/index.d.mts

A lightweight, configurable telemetry tracking library for JavaScript/TypeScript applications with comprehensive error handling, event batching, and graceful degradation

declare enum LogLevel {
    ERROR = 0,
    WARN = 1,
    INFO = 2,
    DEBUG = 3,
    SILENT = 4
}
interface LoggerConfig {
    level?: LogLevel;
    enableConsole?: boolean;
    enableTimestamp?: boolean;
    prefix?: string;
    formatter?: (level: LogLevel, message: string, meta?: Record<string, unknown>) => string;
}
interface Logger {
    error(message: string, meta?: Record<string, unknown>): void;
    warn(message: string, meta?: Record<string, unknown>): void;
    info(message: string, meta?: Record<string, unknown>): void;
    debug(message: string, meta?: Record<string, unknown>): void;
    setLevel(level: LogLevel): void;
    setConfig(config: Partial<LoggerConfig>): void;
}

type TelemetryEvent<T = Record<string, unknown>> = {
    eventType: string;
    eventName: string;
    payload: T;
    timestamp: string;
    sessionId?: string;
    userId?: string;
};

type TelemetryExporter = {
    export(events: TelemetryEvent[], endpoint?: string): Promise<void>;
};

type TelemetryPlugin = {
    /** Called once, passing in the manager to call `.capture(...)` on */
    initialize(manager: {
        capture(event: {
            eventType: string;
            eventName: string;
            payload: Record<string, unknown>;
            timestamp: string;
        }): void;
    }): void;
    /** Optional cleanup hook */
    teardown?(): void;
    /** Destroy the plugin and clean up all resources */
    destroy?(): void;
};

declare enum ExporterType {
    HYPERLOOK = "hyperlook",
    HTTP = "http"
}

type TelemetryConfig = {
    endpoint?: string;
    hyperlookApiKey?: string;
    exporters?: ExporterType[];
    enablePageViews?: boolean;
    enableClicks?: boolean;
    enableLogs?: boolean;
    enableNetwork?: boolean;
    enablePerformance?: boolean;
    enableErrors?: boolean;
    batchSize?: number;
    flushInterval?: number;
    maxRetries?: number;
    retryDelay?: number;
    samplingRate?: number;
    logging?: LoggerConfig;
    sessionId?: string;
    userId?: string;
    enableCustomEvents?: boolean;
};

declare enum TelemetryState {
    INITIALIZING = "initializing",
    RUNNING = "running",
    SHUTTING_DOWN = "shutting_down",
    SHUTDOWN = "shutdown",
    ERROR = "error"
}

declare class TelemetryManager {
    private state;
    private logger;
    private sessionId;
    private userId?;
    private flushTimer;
    private flushInterval;
    private failedEvents;
    private maxFailedEvents;
    private pluginManager;
    private eventProcessor;
    private exportManager;
    constructor(config: TelemetryConfig);
    register(plugin: TelemetryPlugin): void;
    capture(event: TelemetryEvent): void;
    private processEventQueueAsync;
    private flushAsync;
    private startFlushTimer;
    flush(): Promise<void>;
    shutdown(): Promise<void>;
    destroy(): void;
    retryFailedEvents(): void;
    getFailedEventsCount(): number;
    getQueuedEventsCount(): number;
    getBufferedEventsCount(): number;
    getState(): TelemetryState;
    isShutdown(): boolean;
    identify(userId: string, traits?: Record<string, unknown>): void;
    getSessionId(): string;
    getUserId(): string | undefined;
    getCustomEventsPlugin(): CustomEventsPlugin | undefined;
    getEndpoint(): string;
    private processEarlyEventQueue;
}

declare class HTTPExporter implements TelemetryExporter {
    private logger;
    constructor();
    export(events: TelemetryEvent[], endpoint?: string): Promise<void>;
}

declare function getLogger(): Logger;
declare function setLogger(logger: Logger): void;
declare function createLogger(config?: LoggerConfig): Logger;

declare abstract class BasePlugin {
    protected manager: TelemetryManager;
    protected logger: Logger;
    protected isEnabled: boolean;
    protected isInitialized: boolean;
    protected isDestroyed: boolean;
    constructor();
    initialize(manager: TelemetryManager): void;
    protected abstract isSupported(): boolean;
    protected abstract setup(): void;
    protected safeCapture(event: TelemetryEvent): void;
    teardown?(): void;
    destroy(): void;
    isPluginEnabled(): boolean;
}

declare class ClickPlugin extends BasePlugin {
    private handler;
    protected isSupported(): boolean;
    protected setup(): void;
    teardown(): void;
}

declare class LogPlugin extends BasePlugin {
    private originals;
    protected isSupported(): boolean;
    protected setup(): void;
    teardown(): void;
}

declare class NetworkPlugin extends BasePlugin {
    private originalFetch;
    private originalXHROpen;
    private originalXHRSend;
    private unregister;
    private telemetryEndpoint;
    private xhrHandlers;
    private patchedXHRs;
    private cleanupInterval;
    protected isSupported(): boolean;
    constructor();
    initialize(manager: TelemetryManager): void;
    protected setup(): void;
    private setupCleanupInterval;
    private cleanupDeadXHRs;
    teardown(): void;
    private cleanupAllXHRHandlers;
}

declare class PerformancePlugin extends BasePlugin {
    private hasCapturedInitialMetrics;
    private longTaskObserver;
    private layoutShiftObserver;
    private pageLoadTimeout;
    protected isSupported(): boolean;
    private capturePerformanceMetrics;
    protected setup(): void;
    teardown(): void;
}

declare class CustomEventsPlugin extends BasePlugin {
    private readonly MAX_EVENT_TYPE_LENGTH;
    private readonly MAX_EVENT_NAME_LENGTH;
    private readonly MAX_PAYLOAD_SIZE;
    private readonly RESERVED_EVENT_TYPES;
    protected isSupported(): boolean;
    private validateEventType;
    private validateEventName;
    private validatePayload;
    /**
     * Capture a custom event with the specified type, name, and payload
     */
    captureCustomEvent<T = Record<string, unknown>>(eventType: string, eventName: string, payload: T): void;
    /**
     * Capture a custom event with a pre-built TelemetryEvent object
     */
    captureEvent<T = Record<string, unknown>>(event: TelemetryEvent<T>): void;
    protected setup(): void;
}

declare class PageViewPlugin extends BasePlugin {
    private hasCapturedInitialPageView;
    private lastUrl;
    private lastTitle;
    private popstateListener;
    private navigationTimeout;
    private originalPushState;
    private originalReplaceState;
    private domContentLoadedListener;
    private loadListener;
    private navigationListener;
    constructor();
    protected isSupported(): boolean;
    private capturePageView;
    private captureInitialPageView;
    private handleNavigation;
    protected setup(): void;
    private setupNavigationTracking;
    private setupHistoryTracking;
    teardown(): void;
}

declare class ErrorPlugin extends BasePlugin {
    private errorHandler;
    private unhandledRejectionHandler;
    protected isSupported(): boolean;
    protected setup(): void;
    teardown(): void;
}

declare function initTelemetry(config?: Partial<TelemetryConfig>): TelemetryManager;

export { BasePlugin, ClickPlugin, CustomEventsPlugin, ErrorPlugin, HTTPExporter, LogLevel, LogPlugin, type Logger, type LoggerConfig, NetworkPlugin, PageViewPlugin, PerformancePlugin, type TelemetryConfig, type TelemetryEvent, type TelemetryExporter, TelemetryManager, type TelemetryPlugin, createLogger, getLogger, initTelemetry, setLogger };