@statly/observe 1.0.0 → 1.2.0

package/dist/logger/index.d.ts

@@ -0,0 +1,671 @@
+/**
+ * Logger Types
+ * Type definitions for the Statly Observe logging framework
+ */
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'audit';
+declare const LOG_LEVELS: Record<LogLevel, number>;
+type LevelSet = 'default' | 'extended' | LogLevel[];
+declare const DEFAULT_LEVELS: LogLevel[];
+declare const EXTENDED_LEVELS: LogLevel[];
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: number;
+    loggerName?: string;
+    context?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    source?: {
+        file?: string;
+        line?: number;
+        function?: string;
+    };
+    traceId?: string;
+    spanId?: string;
+    sessionId?: string;
+    environment?: string;
+    release?: string;
+    sdkName?: string;
+    sdkVersion?: string;
+}
+interface ConsoleDestinationConfig {
+    enabled?: boolean;
+    colors?: boolean;
+    format?: 'pretty' | 'json';
+    timestamps?: boolean;
+    levels?: LogLevel[];
+}
+interface FileDestinationConfig {
+    enabled?: boolean;
+    path: string;
+    format?: 'json' | 'text';
+    rotation?: FileRotationConfig;
+    levels?: LogLevel[];
+}
+interface FileRotationConfig {
+    type: 'size' | 'time';
+    maxSize?: string;
+    maxFiles?: number;
+    interval?: 'hourly' | 'daily' | 'weekly';
+    retentionDays?: number;
+    compress?: boolean;
+}
+interface ObserveDestinationConfig {
+    enabled?: boolean;
+    batchSize?: number;
+    flushInterval?: number;
+    sampling?: Partial<Record<LogLevel, number>>;
+    levels?: LogLevel[];
+}
+interface ScrubbingConfig {
+    enabled?: boolean;
+    patterns?: ScrubPattern[];
+    customPatterns?: RegExp[];
+    allowlist?: string[];
+    customScrubber?: (key: string, value: unknown) => unknown;
+}
+type ScrubPattern = 'apiKey' | 'password' | 'token' | 'creditCard' | 'ssn' | 'email' | 'ipAddress' | 'awsKey' | 'privateKey' | 'jwt';
+interface LoggerConfig {
+    dsn?: string;
+    level?: LogLevel;
+    levels?: LevelSet;
+    loggerName?: string;
+    environment?: string;
+    release?: string;
+    destinations?: {
+        console?: ConsoleDestinationConfig;
+        file?: FileDestinationConfig;
+        observe?: ObserveDestinationConfig;
+    };
+    scrubbing?: ScrubbingConfig;
+    context?: Record<string, unknown>;
+    tags?: Record<string, string>;
+}
+interface Destination {
+    name: string;
+    write(entry: LogEntry): void | Promise<void>;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+}
+interface ErrorExplanation {
+    summary: string;
+    possibleCauses: string[];
+    stackAnalysis?: string;
+    relatedDocs?: string[];
+}
+interface FixSuggestion {
+    summary: string;
+    suggestedFixes: Array<{
+        description: string;
+        code?: string;
+        confidence: 'high' | 'medium' | 'low';
+    }>;
+    preventionTips?: string[];
+}
+
+/**
+ * AI Features for Logger
+ * Provides AI-powered error explanation and fix suggestions
+ */
+
+interface AIConfig {
+    enabled?: boolean;
+    apiKey?: string;
+    model?: string;
+    endpoint?: string;
+}
+declare class AIFeatures {
+    private config;
+    private dsn;
+    constructor(dsn: string, config?: AIConfig);
+    /**
+     * Parse DSN to construct AI endpoint
+     */
+    private parseEndpoint;
+    /**
+     * Explain an error using AI
+     */
+    explainError(error: Error | LogEntry | string): Promise<ErrorExplanation>;
+    /**
+     * Suggest fixes for an error using AI
+     */
+    suggestFix(error: Error | LogEntry | string, context?: {
+        code?: string;
+        file?: string;
+        language?: string;
+    }): Promise<FixSuggestion>;
+    /**
+     * Analyze a batch of logs for patterns
+     */
+    analyzePatterns(logs: LogEntry[]): Promise<{
+        patterns: Array<{
+            type: string;
+            description: string;
+            occurrences: number;
+            examples: string[];
+        }>;
+        summary: string;
+        recommendations: string[];
+    }>;
+    /**
+     * Normalize error input to a standard format
+     */
+    private normalizeError;
+    /**
+     * Set API key for AI features
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Enable or disable AI features
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if AI features are enabled
+     */
+    isEnabled(): boolean;
+}
+
+/**
+ * Logger Class
+ * Main entry point for the Statly Observe logging framework
+ */
+
+declare class Logger {
+    private name;
+    private config;
+    private minLevel;
+    private enabledLevels;
+    private destinations;
+    private scrubber;
+    private ai;
+    private context;
+    private tags;
+    private sessionId?;
+    private traceId?;
+    private spanId?;
+    constructor(config?: LoggerConfig);
+    /**
+     * Parse level set configuration
+     */
+    private parseLevelSet;
+    /**
+     * Initialize destinations from config
+     */
+    private initDestinations;
+    /**
+     * Generate a unique ID
+     */
+    private generateId;
+    /**
+     * Check if a level should be logged
+     */
+    private shouldLog;
+    /**
+     * Get source location (if available)
+     */
+    private getSource;
+    /**
+     * Create a log entry
+     */
+    private createEntry;
+    /**
+     * Write to all destinations
+     */
+    private write;
+    /**
+     * Log a trace message
+     */
+    trace(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+    error(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Log a fatal message
+     */
+    fatal(message: string, context?: Record<string, unknown>): void;
+    fatal(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Log an audit message (always logged, never sampled)
+     */
+    audit(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log at a specific level
+     */
+    log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Set persistent context
+     */
+    setContext(context: Record<string, unknown>): void;
+    /**
+     * Clear context
+     */
+    clearContext(): void;
+    /**
+     * Set a tag
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Set multiple tags
+     */
+    setTags(tags: Record<string, string>): void;
+    /**
+     * Clear tags
+     */
+    clearTags(): void;
+    /**
+     * Set trace ID for distributed tracing
+     */
+    setTraceId(traceId: string): void;
+    /**
+     * Set span ID
+     */
+    setSpanId(spanId: string): void;
+    /**
+     * Clear tracing context
+     */
+    clearTracing(): void;
+    /**
+     * Create a child logger with additional context
+     */
+    child(options?: {
+        name?: string;
+        context?: Record<string, unknown>;
+        tags?: Record<string, string>;
+    }): Logger;
+    /**
+     * Explain an error using AI
+     */
+    explainError(error: Error | string): Promise<ErrorExplanation>;
+    /**
+     * Suggest fixes for an error using AI
+     */
+    suggestFix(error: Error | string, context?: {
+        code?: string;
+        file?: string;
+        language?: string;
+    }): Promise<FixSuggestion>;
+    /**
+     * Configure AI features
+     */
+    configureAI(config: AIConfig): void;
+    /**
+     * Add a custom destination
+     */
+    addDestination(destination: Destination): void;
+    /**
+     * Remove a destination by name
+     */
+    removeDestination(name: string): void;
+    /**
+     * Get all destinations
+     */
+    getDestinations(): Destination[];
+    /**
+     * Set minimum log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get current minimum level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Check if a level is enabled
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    /**
+     * Flush all destinations
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the logger and all destinations
+     */
+    close(): Promise<void>;
+    /**
+     * Get logger name
+     */
+    getName(): string;
+    /**
+     * Get session ID
+     */
+    getSessionId(): string | undefined;
+}
+
+/**
+ * Secret Scrubber
+ * Detects and redacts sensitive data from log entries
+ */
+
+declare class Scrubber {
+    private enabled;
+    private patterns;
+    private customPatterns;
+    private allowlist;
+    private customScrubber?;
+    constructor(config?: ScrubbingConfig);
+    /**
+     * Scrub sensitive data from a value
+     */
+    scrub<T>(value: T): T;
+    /**
+     * Scrub a log message string
+     */
+    scrubMessage(message: string): string;
+    /**
+     * Recursively scrub sensitive data
+     */
+    private scrubValue;
+    /**
+     * Scrub sensitive patterns from a string
+     */
+    private scrubString;
+    /**
+     * Scrub sensitive data from an object
+     */
+    private scrubObject;
+    /**
+     * Add a custom pattern at runtime
+     */
+    addPattern(pattern: RegExp): void;
+    /**
+     * Add a key to the allowlist
+     */
+    addToAllowlist(key: string): void;
+    /**
+     * Check if scrubbing is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Enable or disable scrubbing
+     */
+    setEnabled(enabled: boolean): void;
+}
+
+/**
+ * Console Destination
+ * Outputs log entries to the console with formatting and colors
+ */
+
+declare class ConsoleDestination implements Destination {
+    readonly name = "console";
+    private config;
+    private minLevel;
+    constructor(config?: ConsoleDestinationConfig);
+    /**
+     * Write a log entry to the console
+     */
+    write(entry: LogEntry): void;
+    /**
+     * Check if the environment supports colors
+     */
+    private supportsColors;
+    /**
+     * Set minimum log level
+     */
+    setMinLevel(level: LogLevel): void;
+    /**
+     * Enable or disable the destination
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Set color mode
+     */
+    setColors(enabled: boolean): void;
+    /**
+     * Set output format
+     */
+    setFormat(format: 'pretty' | 'json'): void;
+}
+
+/**
+ * Observe Destination
+ * Sends log entries to Statly Observe backend with batching and sampling
+ */
+
+declare class ObserveDestination implements Destination {
+    readonly name = "observe";
+    private config;
+    private dsn;
+    private endpoint;
+    private queue;
+    private isFlushing;
+    private flushTimer?;
+    private minLevel;
+    constructor(dsn: string, config?: ObserveDestinationConfig);
+    /**
+     * Parse DSN to construct endpoint
+     */
+    private parseEndpoint;
+    /**
+     * Start the flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Write a log entry (queues for batching)
+     */
+    write(entry: LogEntry): void;
+    /**
+     * Flush all queued entries to the server
+     */
+    flush(): Promise<void>;
+    /**
+     * Send a batch of entries to the server
+     */
+    private sendBatch;
+    /**
+     * Close the destination
+     */
+    close(): Promise<void>;
+    /**
+     * Set minimum log level
+     */
+    setMinLevel(level: LogLevel): void;
+    /**
+     * Set sampling rate for a level
+     */
+    setSamplingRate(level: LogLevel, rate: number): void;
+    /**
+     * Enable or disable the destination
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Get the current queue size
+     */
+    getQueueSize(): number;
+}
+
+/**
+ * File Destination
+ * Writes log entries to files with rotation support (Node.js only)
+ */
+
+declare class FileDestination implements Destination {
+    readonly name = "file";
+    private config;
+    private minLevel;
+    private buffer;
+    private currentSize;
+    private maxSize;
+    private lastRotation;
+    private rotationInterval;
+    private writePromise;
+    private fs;
+    constructor(config: FileDestinationConfig);
+    /**
+     * Initialize file system operations
+     */
+    private initFileSystem;
+    /**
+     * Get rotation interval in milliseconds
+     */
+    private getRotationInterval;
+    /**
+     * Write a log entry
+     */
+    write(entry: LogEntry): void;
+    /**
+     * Schedule a buffered write
+     */
+    private scheduleWrite;
+    /**
+     * Write buffer to file
+     */
+    private writeBuffer;
+    /**
+     * Check if rotation is needed
+     */
+    private checkRotation;
+    /**
+     * Rotate the log file
+     */
+    private rotate;
+    /**
+     * Clean up old rotated files
+     */
+    private cleanupOldFiles;
+    /**
+     * Flush buffered writes
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the destination
+     */
+    close(): Promise<void>;
+    /**
+     * Set minimum log level
+     */
+    setMinLevel(level: LogLevel): void;
+    /**
+     * Enable or disable the destination
+     */
+    setEnabled(enabled: boolean): void;
+}
+
+/**
+ * Secret Scrubbing Patterns
+ * Built-in regex patterns for detecting and redacting sensitive data
+ */
+
+declare const SENSITIVE_KEYS: Set<string>;
+declare const SCRUB_PATTERNS: Record<ScrubPattern, {
+    regex: RegExp;
+    description: string;
+}>;
+declare const REDACTED = "[REDACTED]";
+/**
+ * Check if a key name indicates sensitive data
+ */
+declare function isSensitiveKey(key: string): boolean;
+
+/**
+ * Console Formatter
+ * Formats log entries for console output with colors
+ */
+
+interface ConsoleFormatOptions {
+    colors?: boolean;
+    timestamps?: boolean;
+    showLevel?: boolean;
+    showLogger?: boolean;
+    showContext?: boolean;
+    showSource?: boolean;
+}
+/**
+ * Format a log entry for pretty console output
+ */
+declare function formatPretty(entry: LogEntry, options?: ConsoleFormatOptions): string;
+/**
+ * Format a log entry as JSON
+ */
+declare function formatJson(entry: LogEntry): string;
+/**
+ * Format a log entry as JSON with pretty printing
+ */
+declare function formatJsonPretty(entry: LogEntry): string;
+/**
+ * Get the native console method for a log level
+ */
+declare function getConsoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error' | 'debug' | 'trace';
+
+/**
+ * Statly Observe Logger
+ *
+ * A comprehensive logging framework with multi-destination output,
+ * secret scrubbing, sampling, and AI-powered analysis.
+ *
+ * @example
+ * ```typescript
+ * import { Logger } from '@statly/observe';
+ *
+ * // Create a logger with default settings
+ * const logger = new Logger({
+ *   dsn: 'https://sk_live_xxx@statly.live/your-org',
+ *   loggerName: 'my-app',
+ *   environment: 'production',
+ *   release: '1.0.0',
+ * });
+ *
+ * // Basic logging
+ * logger.info('Application started');
+ * logger.debug('Processing request', { requestId: '123' });
+ * logger.warn('Deprecated API used', { endpoint: '/old-api' });
+ * logger.error('Failed to process', { error: 'timeout' });
+ *
+ * // Log with Error object
+ * try {
+ *   riskyOperation();
+ * } catch (err) {
+ *   logger.error(err);
+ * }
+ *
+ * // Audit logging (always logged, never sampled)
+ * logger.audit('User login', { userId: '123', ip: '10.0.0.1' });
+ *
+ * // AI-powered analysis
+ * const explanation = await logger.explainError(error);
+ * const fix = await logger.suggestFix(error);
+ *
+ * // Child loggers
+ * const requestLogger = logger.child({
+ *   name: 'request',
+ *   context: { requestId: '456' },
+ * });
+ * requestLogger.info('Handling request');
+ *
+ * // Configure destinations
+ * logger.addDestination(myCustomDestination);
+ *
+ * // Cleanup
+ * await logger.close();
+ * ```
+ */
+
+/**
+ * Get or create the default logger instance
+ */
+declare function getDefaultLogger(): Logger;
+/**
+ * Set the default logger instance
+ */
+declare function setDefaultLogger(logger: Logger): void;
+declare function trace(message: string, context?: Record<string, unknown>): void;
+declare function debug(message: string, context?: Record<string, unknown>): void;
+declare function info(message: string, context?: Record<string, unknown>): void;
+declare function warn(message: string, context?: Record<string, unknown>): void;
+declare function error(messageOrError: string | Error, context?: Record<string, unknown>): void;
+declare function fatal(messageOrError: string | Error, context?: Record<string, unknown>): void;
+declare function audit(message: string, context?: Record<string, unknown>): void;
+
+export { AIFeatures, ConsoleDestination, type ConsoleDestinationConfig, DEFAULT_LEVELS, type Destination, EXTENDED_LEVELS, type ErrorExplanation, FileDestination, type FileDestinationConfig, type FileRotationConfig, type FixSuggestion, LOG_LEVELS, type LevelSet, type LogEntry, type LogLevel, Logger, type LoggerConfig, ObserveDestination, type ObserveDestinationConfig, REDACTED, SCRUB_PATTERNS, SENSITIVE_KEYS, type ScrubPattern, Scrubber, type ScrubbingConfig, audit, debug, error, fatal, formatJson, formatJsonPretty, formatPretty, getConsoleMethod, getDefaultLogger, info, isSensitiveKey, setDefaultLogger, trace, warn };