@virtu3d/event-manager 0.2.7

package/dist/index.d.mts

@@ -0,0 +1,568 @@
+export { TraceContext, extractTraceContext, generateSpanId, generateTraceId, generateTraceparent, getTraceHeaders, getTraceHeadersSync, parseTraceparent, startSpan, withTraceContext } from './context/index.mjs';
+
+/**
+ * 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;
+}
+
+/**
+ * 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';
+/**
+ * Factory registry - maps type names to factory functions
+ */
+declare const factoryRegistry: Map<string, ConnectorFactoryFn<any>>;
+/**
+ * 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;
+/**
+ * Get all registered factory names
+ */
+declare function getRegisteredFactories(): string[];
+/**
+ * Create a connector from type and config
+ */
+declare function createConnector(typeName: string, config: ConnectorConfig): Connector;
+/**
+ * Create connectors from provider configs
+ */
+declare function createConnectorsFromConfig(providers: ProviderConfig[]): 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;
+
+/**
+ * Analytics provider options
+ */
+type AnalyticsProvider = 'mixpanel' | 'posthog' | 'segment' | 'none';
+/**
+ * Observability provider options
+ */
+type ObservabilityProvider = 'otel' | 'datadog' | 'newrelic' | 'none';
+/**
+ * Metrics provider options (for custom business metrics)
+ */
+type MetricsProvider = 'cloudwatch-emf' | 'none';
+/**
+ * Metric mapping configuration for CloudWatch EMF
+ */
+interface MetricMapping {
+    /** CloudWatch metric name */
+    metricName: string;
+    /** Metric unit */
+    unit: 'Count' | 'Milliseconds' | 'Bytes' | 'None' | 'Percent';
+    /** Dimension fields to extract from event payload */
+    dimensions?: string[];
+    /** Field to use as metric value (default: 1 for count) */
+    valueField?: string;
+}
+/**
+ * Provider-specific configurations
+ */
+interface ProviderConfigs {
+    mixpanel?: {
+        token: string;
+        trackFields?: string[];
+        debug?: boolean;
+    };
+    posthog?: {
+        apiKey: string;
+        host?: string;
+        debug?: boolean;
+    };
+    segment?: {
+        writeKey: string;
+        debug?: boolean;
+    };
+    otel?: {
+        serviceName: string;
+        endpoint?: string;
+        debug?: boolean;
+    };
+    datadog?: {
+        clientToken: string;
+        site?: string;
+        service?: string;
+        debug?: boolean;
+    };
+    cloudwatchEmf?: {
+        namespace: string;
+        serviceName: string;
+        region?: string;
+        /** Map event names to metric configurations */
+        metricMappings?: Record<string, MetricMapping>;
+        debug?: boolean;
+    };
+}
+/**
+ * Main telemetry configuration
+ */
+interface TelemetryConfig {
+    /** Application name */
+    app: string;
+    /** Environment (auto-detected if not provided) */
+    environment?: 'browser' | 'node';
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Global metadata added to all events */
+    globalMeta?: Record<string, unknown>;
+    /** Analytics configuration */
+    analytics: {
+        /** Active provider - change this to switch */
+        provider: AnalyticsProvider;
+    } & ProviderConfigs;
+    /** Observability configuration */
+    observability: {
+        /** Active provider - change this to switch */
+        provider: ObservabilityProvider;
+    } & ProviderConfigs;
+    /** Custom metrics configuration */
+    metrics?: {
+        /** Active provider - change this to switch */
+        provider: MetricsProvider;
+    } & ProviderConfigs;
+}
+/**
+ * Validate configuration
+ */
+declare function validateConfig(config: TelemetryConfig): void;
+
+/**
+ * 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>;
+/**
+ * Extract specific fields from an object
+ */
+declare function extractFields<T extends Record<string, unknown>>(obj: T, fields: (keyof T)[]): Partial<T>;
+/**
+ * Flatten a nested object into dot-notation keys
+ */
+declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+/**
+ * Retry a function with exponential backoff
+ */
+declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    factor?: number;
+}): Promise<T>;
+/**
+ * Sleep for a specified duration
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Debounce a function
+ */
+declare function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Batch items and process in chunks
+ */
+declare function processBatch<T, R>(items: T[], processor: (batch: T[]) => Promise<R>, batchSize?: number): Promise<R[]>;
+/**
+ * Create a simple in-memory cache with TTL
+ */
+declare function createCache<T>(defaultTtl?: number): {
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl?: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+};
+
+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;
+}
+
+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;
+
+interface OtelConnectorConfig extends ConnectorConfig {
+    serviceName: string;
+    endpoint?: string;
+    /** Custom span attributes extractor */
+    attributesExtractor?: (event: TelemetryEvent) => Record<string, string | number | boolean>;
+}
+/**
+ * OpenTelemetry connector for distributed tracing
+ */
+declare class OtelConnector extends BaseConnector {
+    name: string;
+    type: "observability";
+    private tracer;
+    private context;
+    private serviceName;
+    private attributesExtractor?;
+    constructor(config: OtelConnectorConfig);
+    protected setup(): Promise<void>;
+    track(event: TelemetryEvent): void;
+    identify(event: IdentifyEvent): void;
+    page(event: PageEvent): void;
+}
+declare function createOtelConnector(config: OtelConnectorConfig): OtelConnector;
+
+interface CloudWatchEmfConnectorConfig extends ConnectorConfig {
+    /** CloudWatch namespace e.g., 'Virtu3D/Application' */
+    namespace: string;
+    /** Service name */
+    serviceName: string;
+    /** AWS Region */
+    region?: string;
+    /** Map event names to metric configurations */
+    metricMappings?: Record<string, MetricMapping>;
+}
+/**
+ * CloudWatch Embedded Metric Format (EMF) Connector
+ *
+ * Outputs structured JSON logs that CloudWatch automatically parses into metrics.
+ * Works with existing Docker awslogs driver - no additional infrastructure needed.
+ *
+ * IMPORTANT: This is for CUSTOM BUSINESS METRICS only.
+ * Application logs already go to CloudWatch via Docker awslogs driver + Pino.
+ * DO NOT use this connector for application logging.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html
+ */
+declare class CloudWatchEmfConnector extends BaseConnector {
+    name: string;
+    type: "metrics";
+    private namespace;
+    private serviceName;
+    private region;
+    private metricMappings;
+    constructor(config: CloudWatchEmfConnectorConfig);
+    protected setup(): void;
+    track(event: TelemetryEvent): void;
+    identify(event: IdentifyEvent): void;
+    /**
+     * Convert event name to CloudWatch metric name
+     * e.g., 'ai_chat_completed' -> 'AiChatCompleted'
+     */
+    private toMetricName;
+}
+declare function createCloudWatchEmfConnector(config: CloudWatchEmfConnectorConfig): CloudWatchEmfConnector;
+
+interface MixpanelConnectorConfig extends ConnectorConfig {
+    token: string;
+    /** Fields to extract from payload for Mixpanel */
+    trackFields?: string[];
+}
+/**
+ * Mixpanel connector for analytics
+ */
+declare class MixpanelConnector extends BaseConnector {
+    name: string;
+    type: "analytics";
+    private client;
+    private token;
+    private trackFields?;
+    constructor(config: MixpanelConnectorConfig);
+    protected setup(): Promise<void>;
+    track(event: TelemetryEvent): void;
+    identify(event: IdentifyEvent): void;
+    page(event: PageEvent): void;
+}
+declare function createMixpanelConnector(config: MixpanelConnectorConfig): MixpanelConnector;
+
+interface PostHogConnectorConfig extends ConnectorConfig {
+    apiKey: string;
+    host?: string;
+}
+/**
+ * PostHog connector for analytics
+ */
+declare class PostHogConnector extends BaseConnector {
+    name: string;
+    type: "analytics";
+    private client;
+    private apiKey;
+    private host;
+    constructor(config: PostHogConnectorConfig);
+    protected setup(): Promise<void>;
+    track(event: TelemetryEvent): void;
+    identify(event: IdentifyEvent): void;
+    page(event: PageEvent): void;
+    shutdown(): Promise<void>;
+}
+declare function createPostHogConnector(config: PostHogConnectorConfig): PostHogConnector;
+
+export { type AnalyticsProvider, BaseConnector, CloudWatchEmfConnector, type CloudWatchEmfConnectorConfig, type Connector, type ConnectorConfig, type ConnectorFactory, type ConnectorFactoryFn, type ConnectorType, type ConnectorTypeName, ConsoleConnector, type ConsoleConnectorConfig, type DispatchResult, type DispatchResults, type IdentifyEvent, type MetricMapping, type MetricsProvider, MixpanelConnector, type MixpanelConnectorConfig, type ObservabilityProvider, OtelConnector, type OtelConnectorConfig, type PageEvent, PostHogConnector, type PostHogConnectorConfig, type ProviderConfig, type ProviderConfigs, type RouterConfig, type RouterPlugin, type TelemetryConfig, type TelemetryEvent, TelemetryRouter, type TelemetryRouterConfig, createCache, createCloudWatchEmfConnector, createConnector, createConnectorsFromConfig, createConsoleConnector, createMixpanelConnector, createOtelConnector, createPostHogConnector, createTelemetryRouter, debounce, deepMerge, detectEnvironment, extractFields, factoryRegistry, flattenObject, generateEventId, generateSessionId, getFactory, getRegisteredFactories, hasFactory, isObject, processBatch, registerFactory, retryWithBackoff, safeStringify, sanitizePayload, sleep, validateConfig };