@virtu3d/event-manager 0.2.7

package/dist/browser/index.d.mts

@@ -0,0 +1,631 @@
+/**
+ * Base telemetry event structure
+ */
+interface TelemetryEvent {
+    /** Event name e.g., 'button_click', 'checkout', 'page_view' */
+    name: string;
+    /** Event payload - any key-value data */
+    payload: Record<string, unknown>;
+    /** ISO timestamp - auto-generated if not provided */
+    timestamp?: string;
+    /** Optional metadata */
+    meta?: {
+        sessionId?: string;
+        userId?: string;
+        orgId?: string;
+        traceId?: string;
+        spanId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * User identification event
+ */
+interface IdentifyEvent {
+    userId: string;
+    traits?: Record<string, unknown>;
+    timestamp?: string;
+}
+/**
+ * Page view event
+ */
+interface PageEvent {
+    name?: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+}
+/**
+ * Connector types
+ */
+type ConnectorType = 'observability' | 'analytics' | 'metrics' | 'custom';
+/**
+ * Connector interface - all connectors must implement this
+ */
+interface Connector {
+    /** Unique connector name e.g., 'otel', 'mixpanel', 'cloudwatch-emf' */
+    name: string;
+    /** Connector category */
+    type: ConnectorType;
+    /** Initialize connector (load scripts, setup clients) */
+    init?(): Promise<void> | void;
+    /** Handle track events */
+    track(event: TelemetryEvent): Promise<void> | void;
+    /** Handle identify events */
+    identify?(event: IdentifyEvent): Promise<void> | void;
+    /** Handle page view events */
+    page?(event: PageEvent): Promise<void> | void;
+    /** Cleanup resources */
+    shutdown?(): Promise<void> | void;
+    /** Check if connector is ready */
+    isReady?(): boolean;
+}
+/**
+ * Connector configuration base
+ */
+interface ConnectorConfig {
+    /** Enable/disable connector */
+    enabled?: boolean;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Factory interface for creating connectors
+ */
+interface ConnectorFactory<TConfig extends ConnectorConfig = ConnectorConfig> {
+    /** Factory identifier */
+    name: string;
+    /** Factory type */
+    type: ConnectorType;
+    /** Create a connector instance */
+    create(config: TConfig): Connector;
+}
+/**
+ * Router configuration
+ */
+interface RouterConfig {
+    /** Application name */
+    app?: string;
+    /** Debug mode - logs all events to console */
+    debug?: boolean;
+    /** Global metadata added to all events */
+    globalMeta?: Record<string, unknown>;
+    /** Plugins/middleware */
+    plugins?: RouterPlugin[];
+}
+/**
+ * Plugin interface for middleware functionality
+ */
+interface RouterPlugin {
+    name: string;
+    /** Called before event is dispatched to connectors */
+    beforeDispatch?(event: TelemetryEvent): TelemetryEvent | null;
+    /** Called after all connectors have processed */
+    afterDispatch?(event: TelemetryEvent, results: DispatchResult[]): void;
+}
+/**
+ * Result of dispatching to a single connector
+ */
+interface DispatchResult {
+    connector: string;
+    success: boolean;
+    error?: Error;
+    duration?: number;
+}
+/**
+ * Result of dispatching to all connectors
+ */
+interface DispatchResults {
+    event: TelemetryEvent;
+    results: DispatchResult[];
+    timestamp: string;
+}
+
+declare abstract class BaseConnector implements Connector {
+    abstract name: string;
+    abstract type: ConnectorType;
+    protected config: ConnectorConfig;
+    protected ready: boolean;
+    constructor(config?: ConnectorConfig);
+    init(): Promise<void>;
+    /**
+     * Override this to implement connector-specific setup
+     */
+    protected abstract setup(): Promise<void> | void;
+    abstract track(event: TelemetryEvent): Promise<void> | void;
+    identify?(event: IdentifyEvent): Promise<void> | void;
+    page?(event: PageEvent): Promise<void> | void;
+    shutdown(): Promise<void>;
+    isReady(): boolean;
+    protected log(message: string, data?: unknown): void;
+}
+
+/**
+ * Browser OpenTelemetry Connector
+ *
+ * Provides OTEL tracing capabilities for browser environments.
+ * Uses @opentelemetry/sdk-trace-web for browser-optimized tracing.
+ */
+
+interface BrowserOtelConnectorConfig extends ConnectorConfig {
+    /** Service name for this application */
+    serviceName: string;
+    /** OTEL collector endpoint for sending traces */
+    collectorUrl?: string;
+    /** URLs to propagate trace context to (supports strings and RegExp) */
+    propagateToUrls?: (string | RegExp)[];
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string>;
+    /** Whether to auto-instrument fetch/XHR (default: false - use interceptors instead) */
+    autoInstrument?: boolean;
+}
+/**
+ * Browser-optimized OpenTelemetry connector
+ *
+ * @example
+ * ```typescript
+ * const connector = new BrowserOtelConnector({
+ *   serviceName: 'my-web-app',
+ *   collectorUrl: 'http://localhost:4318/v1/traces',
+ *   propagateToUrls: [/api\.example\.com/, /localhost:3000/],
+ * });
+ * ```
+ */
+declare class BrowserOtelConnector extends BaseConnector {
+    name: string;
+    type: "observability";
+    private tracer;
+    private provider;
+    private otelConfig;
+    constructor(config: BrowserOtelConnectorConfig);
+    protected setup(): Promise<void>;
+    track(event: TelemetryEvent): void;
+    identify(event: IdentifyEvent): void;
+    page(event: PageEvent): void;
+    shutdown(): Promise<void>;
+    /**
+     * Get the underlying tracer for advanced use cases
+     */
+    getTracer(): any;
+    /**
+     * Get the provider for advanced configuration
+     */
+    getProvider(): any;
+}
+/**
+ * Factory function to create a BrowserOtelConnector
+ */
+declare function createBrowserOtelConnector(config: BrowserOtelConnectorConfig): BrowserOtelConnector;
+
+/**
+ * Browser HTTP Interceptors
+ *
+ * Provides fetch and XMLHttpRequest interceptors for automatic
+ * trace context propagation in browser environments.
+ */
+/**
+ * Configuration for the fetch interceptor
+ */
+interface FetchInterceptorConfig {
+    /** URLs to propagate trace context to (matches if URL contains string or matches RegExp) */
+    propagateToUrls: (string | RegExp)[];
+    /** URLs to exclude from trace propagation (matches if URL contains string or matches RegExp) */
+    excludeUrls?: (string | RegExp)[];
+    /** Original fetch function (defaults to globalThis.fetch) */
+    originalFetch?: typeof fetch;
+    /** Whether to create spans for fetch requests (requires OTEL to be initialized) */
+    createSpans?: boolean;
+    /** Service name for span creation */
+    serviceName?: string;
+}
+/**
+ * Create a traced fetch function that automatically injects trace context headers.
+ *
+ * @example
+ * ```typescript
+ * const tracedFetch = createTracedFetch({
+ *   propagateToUrls: [/api\.example\.com/, 'localhost:3000'],
+ * });
+ *
+ * // Use directly
+ * const response = await tracedFetch('/api/data');
+ *
+ * // Or replace global fetch
+ * globalThis.fetch = tracedFetch;
+ * ```
+ */
+declare function createTracedFetch(config: FetchInterceptorConfig): typeof fetch;
+/**
+ * Install the fetch interceptor globally.
+ * This replaces `globalThis.fetch` with a traced version.
+ *
+ * @example
+ * ```typescript
+ * installFetchInterceptor({
+ *   propagateToUrls: [/api\.example\.com/, 'localhost:3000'],
+ *   excludeUrls: [/google-analytics/, /sentry\.io/],
+ *   createSpans: true,
+ * });
+ *
+ * // All subsequent fetch calls will have trace context
+ * const response = await fetch('/api/data');
+ * ```
+ */
+declare function installFetchInterceptor(config: FetchInterceptorConfig): void;
+/**
+ * Restore the original fetch function.
+ * Call this to uninstall the fetch interceptor.
+ *
+ * @param originalFetch - Optional: pass the original fetch function.
+ *                        If not provided, uses the stored original from installFetchInterceptor.
+ */
+declare function uninstallFetchInterceptor(originalFetch?: typeof fetch): void;
+/**
+ * Configuration for XMLHttpRequest interceptor
+ */
+interface XHRInterceptorConfig {
+    /** URLs to propagate trace context to */
+    propagateToUrls: (string | RegExp)[];
+    /** URLs to exclude from trace propagation */
+    excludeUrls?: (string | RegExp)[];
+    /** Whether to create spans for XHR requests */
+    createSpans?: boolean;
+    /** Service name for span creation */
+    serviceName?: string;
+}
+/**
+ * Install XMLHttpRequest interceptor for automatic trace context propagation.
+ *
+ * @example
+ * ```typescript
+ * installXHRInterceptor({
+ *   propagateToUrls: [/api\.example\.com/],
+ * });
+ *
+ * const xhr = new XMLHttpRequest();
+ * xhr.open('GET', 'https://api.example.com/data');
+ * xhr.send(); // Trace headers will be automatically added
+ * ```
+ */
+declare function installXHRInterceptor(config: XHRInterceptorConfig): void;
+/**
+ * Configuration for axios interceptor
+ */
+interface AxiosInterceptorConfig {
+    /** URLs to propagate trace context to (matches if URL contains string or matches RegExp) */
+    propagateToUrls: (string | RegExp)[];
+    /** URLs to exclude from trace propagation (matches if URL contains string or matches RegExp) */
+    excludeUrls?: (string | RegExp)[];
+}
+/**
+ * Create an axios interceptor for trace context propagation.
+ * Use this with axios.interceptors.request.use()
+ *
+ * @example
+ * ```typescript
+ * import axios from 'axios';
+ *
+ * axios.interceptors.request.use(
+ *   createAxiosTraceInterceptor({
+ *     propagateToUrls: [/api\.example\.com/, 'localhost:3000'],
+ *     excludeUrls: [/google-analytics/, /sentry\.io/],
+ *   })
+ * );
+ * ```
+ */
+declare function createAxiosTraceInterceptor(config: AxiosInterceptorConfig): (axiosConfig: any) => Promise<any>;
+/**
+ * Install axios interceptor globally on an axios instance.
+ * Convenience function that wraps createAxiosTraceInterceptor.
+ *
+ * @example
+ * ```typescript
+ * import axios from 'axios';
+ *
+ * installAxiosInterceptor(axios, {
+ *   propagateToUrls: [/api\.example\.com/],
+ *   excludeUrls: [/google-analytics/],
+ * });
+ * ```
+ */
+declare function installAxiosInterceptor(axiosInstance: {
+    interceptors: {
+        request: {
+            use: (fn: (config: any) => Promise<any>) => number;
+        };
+    };
+}, config: AxiosInterceptorConfig): number;
+/**
+ * Create headers with trace context for manual injection.
+ * Useful when you need to add trace context to custom HTTP clients.
+ *
+ * @example
+ * ```typescript
+ * const headers = await getTracedHeaders({ 'Content-Type': 'application/json' });
+ * // headers now includes traceparent and any existing headers
+ * ```
+ */
+declare function getTracedHeaders(existingHeaders?: Record<string, string>): Promise<Record<string, string>>;
+
+/**
+ * Context Propagation Utilities
+ *
+ * Works in both Node.js and Browser environments.
+ * Uses @opentelemetry/api for trace context propagation.
+ */
+/**
+ * Trace context structure
+ */
+interface TraceContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+/**
+ * Get current trace headers for manual injection into HTTP requests.
+ * Returns headers like { traceparent: '00-abc123...', tracestate: '...' }
+ *
+ * If there's an active OTEL span, uses its context.
+ * Otherwise, generates a new traceparent to enable backend trace correlation.
+ *
+ * @example
+ * ```typescript
+ * const headers = getTraceHeaders();
+ * fetch('/api/data', { headers });
+ * ```
+ */
+declare function getTraceHeaders(): Promise<Record<string, string>>;
+/**
+ * Synchronous version of getTraceHeaders (requires OTEL to be pre-loaded)
+ * Use this when you know OTEL is already initialized.
+ *
+ * If there's an active OTEL span, uses its context.
+ * Otherwise, generates a new traceparent to enable backend trace correlation.
+ */
+declare function getTraceHeadersSync(): Record<string, string>;
+/**
+ * Extract trace context from incoming headers.
+ * Use this in middleware to link incoming requests to their parent trace.
+ *
+ * @example
+ * ```typescript
+ * // Express middleware
+ * app.use((req, res, next) => {
+ *   const traceContext = extractTraceContext(req.headers);
+ *   if (traceContext) {
+ *     req.traceId = traceContext.traceId;
+ *   }
+ *   next();
+ * });
+ * ```
+ */
+declare function extractTraceContext(headers: Record<string, string | string[] | undefined>): Promise<TraceContext | null>;
+/**
+ * Run a function within an extracted trace context.
+ * This ensures any spans created within the function are linked to the parent trace.
+ *
+ * @example
+ * ```typescript
+ * await withTraceContext(req.headers, async () => {
+ *   // Any spans created here will be children of the incoming trace
+ *   await processRequest();
+ * });
+ * ```
+ */
+declare function withTraceContext<T>(headers: Record<string, string | string[] | undefined>, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Create a new span for tracking an operation.
+ * The span will automatically be linked to the current trace context.
+ *
+ * @example
+ * ```typescript
+ * const span = await startSpan('fetch-user-data');
+ * try {
+ *   const user = await fetchUser(id);
+ *   span.setAttribute('user.id', id);
+ *   span.setStatus({ code: SpanStatusCode.OK });
+ * } catch (error) {
+ *   span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+ *   throw error;
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+declare function startSpan(name: string, serviceName?: string): Promise<any>;
+/**
+ * Parse a traceparent header string into its components.
+ * Format: version-traceId-spanId-traceFlags (e.g., "00-abc123...-def456...-01")
+ */
+declare function parseTraceparent(traceparent: string): {
+    version: string;
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+} | null;
+/**
+ * Generate a traceparent header string.
+ * Useful for creating custom trace contexts.
+ */
+declare function generateTraceparent(traceId: string, spanId: string, traceFlags?: number): string;
+/**
+ * Generate a random trace ID (32 hex characters)
+ */
+declare function generateTraceId(): string;
+/**
+ * Generate a random span ID (16 hex characters)
+ */
+declare function generateSpanId(): string;
+
+/**
+ * Connector Factory Registry
+ *
+ * Maps connector type strings to their factory functions.
+ * This allows the router to auto-instantiate connectors from config.
+ */
+
+/**
+ * Factory function type
+ */
+type ConnectorFactoryFn<TConfig extends ConnectorConfig = ConnectorConfig> = (config: TConfig) => Connector;
+/**
+ * Provider configuration for router
+ */
+interface ProviderConfig {
+    /** Unique name for this provider instance */
+    name: string;
+    /** Provider type - maps to factory */
+    type: ConnectorTypeName;
+    /** Enable/disable this provider */
+    enabled?: boolean;
+    /** Provider-specific configuration */
+    config?: ConnectorConfig;
+}
+/**
+ * Built-in connector type names
+ */
+type ConnectorTypeName = 'console' | 'otel' | 'otel-browser' | 'cloudwatch-emf' | 'mixpanel' | 'posthog';
+/**
+ * Register a connector factory
+ */
+declare function registerFactory<TConfig extends ConnectorConfig>(typeName: string, factory: ConnectorFactoryFn<TConfig>): void;
+/**
+ * Get a factory by type name
+ */
+declare function getFactory(typeName: string): ConnectorFactoryFn | undefined;
+/**
+ * Check if a factory is registered
+ */
+declare function hasFactory(typeName: string): boolean;
+/**
+ * Create a connector from type and config
+ */
+declare function createConnector(typeName: string, config: ConnectorConfig): Connector;
+
+/**
+ * Extended router config with providers support
+ */
+interface TelemetryRouterConfig extends RouterConfig {
+    /** Provider configurations - auto-registered on construction */
+    providers?: ProviderConfig[];
+}
+declare class TelemetryRouter {
+    private connectors;
+    private plugins;
+    private config;
+    private initialized;
+    constructor(config?: TelemetryRouterConfig);
+    /**
+     * Initialize all registered connectors
+     */
+    init(): Promise<void>;
+    /**
+     * Register a connector instance directly
+     */
+    registerConnector(connector: Connector): this;
+    /**
+     * Register connector using a factory
+     */
+    use<TConfig extends ConnectorConfig>(factory: ConnectorFactory<TConfig>, config: TConfig): this;
+    /**
+     * Unregister a connector by name
+     */
+    unregisterConnector(name: string): this;
+    /**
+     * Add a plugin
+     */
+    addPlugin(plugin: RouterPlugin): this;
+    /**
+     * Track a custom event
+     */
+    track(eventName: string, payload?: Record<string, unknown>): Promise<DispatchResults>;
+    /**
+     * Identify a user
+     */
+    identify(userId: string, traits?: Record<string, unknown>): Promise<DispatchResults>;
+    /**
+     * Track a page view
+     */
+    page(name?: string, properties?: Record<string, unknown>): Promise<DispatchResults>;
+    /**
+     * Core dispatch method - sends to all connectors in parallel
+     */
+    private dispatch;
+    /**
+     * Get all registered connector names
+     */
+    getConnectors(): string[];
+    /**
+     * Get connectors by type
+     */
+    getConnectorsByType(type: Connector['type']): string[];
+    /**
+     * Shutdown all connectors
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Internal logger
+     */
+    private log;
+}
+/**
+ * Create a new TelemetryRouter instance
+ */
+declare function createTelemetryRouter(config?: RouterConfig): TelemetryRouter;
+
+interface ConsoleConnectorConfig extends ConnectorConfig {
+    prefix?: string;
+}
+/**
+ * Console connector for debugging during development
+ */
+declare class ConsoleConnector extends BaseConnector {
+    name: string;
+    type: "custom";
+    private prefix;
+    constructor(config?: ConsoleConnectorConfig);
+    protected setup(): void;
+    track(event: TelemetryEvent): void;
+    identify(event: IdentifyEvent): void;
+    page(event: PageEvent): void;
+}
+declare function createConsoleConnector(config?: ConsoleConnectorConfig): ConsoleConnector;
+
+/**
+ * Telemetry Utilities
+ *
+ * Common helper functions for telemetry operations.
+ */
+/**
+ * Detect current environment (browser or node)
+ */
+declare function detectEnvironment(): 'browser' | 'node';
+/**
+ * Generate a unique session ID
+ */
+declare function generateSessionId(): string;
+/**
+ * Generate a unique event ID
+ */
+declare function generateEventId(): string;
+/**
+ * Safely stringify an object (handles circular references)
+ */
+declare function safeStringify(obj: unknown, space?: number): string;
+/**
+ * Deep merge two objects
+ */
+declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
+/**
+ * Check if value is a plain object
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Sanitize sensitive fields from payload
+ */
+declare function sanitizePayload(payload: Record<string, unknown>, sensitiveFields?: string[]): Record<string, unknown>;
+/**
+ * Debounce a function
+ */
+declare function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+
+export { type AxiosInterceptorConfig, BaseConnector, BrowserOtelConnector, type BrowserOtelConnectorConfig, type Connector, type ConnectorConfig, type ConnectorFactoryFn, type ConnectorType, ConsoleConnector, type ConsoleConnectorConfig, type DispatchResult, type DispatchResults, type FetchInterceptorConfig, type IdentifyEvent, type PageEvent, type ProviderConfig, type RouterConfig, type RouterPlugin, type TelemetryEvent, TelemetryRouter, type TelemetryRouterConfig, type TraceContext, type XHRInterceptorConfig, createAxiosTraceInterceptor, createBrowserOtelConnector, createConnector, createConsoleConnector, createTelemetryRouter, createTracedFetch, debounce, deepMerge, detectEnvironment, extractTraceContext, generateEventId, generateSessionId, generateSpanId, generateTraceId, generateTraceparent, getFactory, getTraceHeaders, getTraceHeadersSync, getTracedHeaders, hasFactory, installAxiosInterceptor, installFetchInterceptor, installXHRInterceptor, isObject, parseTraceparent, registerFactory, safeStringify, sanitizePayload, startSpan, uninstallFetchInterceptor, withTraceContext };