@octaviaflow/logger 1.0.0

package/types/logger.d.ts

@@ -0,0 +1,494 @@
+// ============================================
+// Production-Ready Logger Types
+// ============================================
+
+// ============================================
+// CORE TYPES
+// ============================================
+
+export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+export type LogService = 'engine' | 'backend' | 'ui' | 'worker' | 'scheduler';
+export type LogFormat = 'json' | 'pretty' | 'compact' | 'ecs'; // ECS = Elastic Common Schema
+
+// ============================================
+// CONTEXT & CORRELATION
+// ============================================
+
+export interface CorrelationContext {
+  traceId: string;          // Distributed trace ID
+  spanId: string;           // Current span ID
+  parentSpanId?: string;    // Parent span ID
+  correlationId: string;    // Business correlation ID
+  sessionId?: string;       // User session ID
+}
+
+export interface RequestContext {
+  requestId: string;
+  method: string;
+  url: string;
+  path: string;
+  query?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  body?: unknown;
+  ip: string;
+  userAgent?: string;
+  referer?: string;
+  protocol: string;
+  hostname: string;
+}
+
+export interface UserContext {
+  userId: string;
+  username?: string;
+  email?: string;
+  organizationId: string;
+  projectId?: string;
+  roles?: string[];
+  subscription?: 'free' | 'starter' | 'growth' | 'business' | 'enterprise';
+}
+
+export interface WorkflowContext {
+  workflowId: string;
+  workflowName?: string;
+  executionId?: string;
+  stepId?: string;
+  stepName?: string;
+  triggeredBy?: string;
+  environment?: 'development' | 'staging' | 'production';
+}
+
+// ============================================
+// LOG METADATA
+// ============================================
+
+export interface BaseLogMeta {
+  timestamp: string;        // ISO 8601
+  level: LogLevel;
+  service: LogService;
+  hostname: string;
+  pid: number;
+  version: string;          // App version
+  environment: 'development' | 'staging' | 'production';
+  
+  // Contexts
+  correlation?: CorrelationContext;
+  request?: RequestContext;
+  user?: UserContext;
+  workflow?: WorkflowContext;
+  
+  // Additional metadata
+  [key: string]: unknown;
+}
+
+// ============================================
+// SPECIALIZED LOG TYPES
+// ============================================
+
+export interface SystemLogMeta extends BaseLogMeta {
+  type: 'startup' | 'shutdown' | 'health' | 'config' | 'dependency';
+  component: string;
+  operation: string;
+  details?: {
+    configLoaded?: boolean;
+    connectionsEstablished?: string[];
+    initDuration?: number;
+    memoryUsage?: number;
+    cpuUsage?: number;
+  };
+}
+
+export interface PerformanceLogMeta extends BaseLogMeta {
+  type: 'performance';
+  operation: string;
+  duration: {
+    ms: number;
+    human: string;        // "1.23s", "45ms"
+  };
+  metrics?: {
+    cpu?: number;
+    memory?: number;
+    dbQueries?: number;
+    apiCalls?: number;
+    cacheHits?: number;
+    cacheMisses?: number;
+  };
+  slow?: boolean;         // Flag if exceeds threshold
+}
+
+export interface DatabaseLogMeta extends BaseLogMeta {
+  type: 'database';
+  operation: 'query' | 'transaction' | 'migration' | 'connection';
+  database: string;
+  table?: string;
+  query?: string;          // Sanitized query
+  duration?: number;
+  rowsAffected?: number;
+  transaction?: {
+    id: string;
+    status: 'begin' | 'commit' | 'rollback';
+  };
+}
+
+export interface APILogMeta extends BaseLogMeta {
+  type: 'api';
+  direction: 'inbound' | 'outbound';
+  statusCode?: number;
+  duration?: number;
+  
+  // For outbound
+  target?: {
+    service: string;
+    endpoint: string;
+    method: string;
+  };
+  
+  // Rate limiting
+  rateLimit?: {
+    limit: number;
+    remaining: number;
+    reset: string;
+  };
+}
+
+export interface SecurityLogMeta extends BaseLogMeta {
+  type: 'security';
+  event: 'auth_success' | 'auth_failure' | 'permission_denied' | 'suspicious_activity' | 'rate_limit';
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  threat?: {
+    type: string;
+    description: string;
+    ipAddress?: string;
+    userAgent?: string;
+    attemptCount?: number;
+  };
+  action?: 'blocked' | 'allowed' | 'flagged';
+}
+
+export interface AuditLogMeta extends BaseLogMeta {
+  type: 'audit';
+  action: string;          // 'user.created', 'workflow.deleted', etc.
+  actor: {
+    id: string;
+    type: 'user' | 'system' | 'api';
+    name?: string;
+  };
+  resource: {
+    type: string;
+    id: string;
+    name?: string;
+  };
+  changes?: Array<{
+    field: string;
+    oldValue?: unknown;
+    newValue?: unknown;
+  }>;
+  result: 'success' | 'failure';
+}
+
+export interface ErrorLogMeta extends BaseLogMeta {
+  type: 'error';
+  error: {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    statusCode?: number;
+    originalError?: unknown;
+  };
+  context?: {
+    operation?: string;
+    input?: unknown;
+    component?: string;
+    recoverable?: boolean;
+    retryable?: boolean;
+    retryCount?: number;
+  };
+  handled: boolean;
+}
+
+export interface WorkflowLogMeta extends BaseLogMeta {
+  type: 'workflow';
+  event: 'started' | 'completed' | 'failed' | 'step_started' | 'step_completed' | 'step_failed';
+  workflow: {
+    id: string;
+    name: string;
+    version: string;
+  };
+  execution?: {
+    id: string;
+    attempt: number;
+    trigger: string;
+  };
+  step?: {
+    id: string;
+    name: string;
+    type: string;
+    index: number;
+  };
+  performance?: {
+    duration?: number;
+    recordsProcessed?: number;
+    bytesProcessed?: number;
+  };
+  cost?: {
+    estimated?: number;
+    actual?: number;
+    credits?: number;
+  };
+}
+
+export interface MetricsLogMeta extends BaseLogMeta {
+  type: 'metrics';
+  metrics: {
+    counters?: Record<string, number>;
+    gauges?: Record<string, number>;
+    histograms?: Record<string, number[]>;
+    timers?: Record<string, number>;
+  };
+  aggregation?: {
+    period: string;       // '1m', '5m', '1h'
+    method: 'sum' | 'avg' | 'max' | 'min' | 'p95' | 'p99';
+  };
+}
+
+// ============================================
+// LOGGER CONFIGURATION
+// ============================================
+
+export interface TransportConfig {
+  type: 'console' | 'file' | 'stream' | 'http' | 'syslog' | 'datadog' | 'elasticsearch';
+  enabled: boolean;
+  level?: LogLevel;
+  format?: LogFormat;
+  
+  // File transport
+  file?: {
+    path: string;
+    maxSize: string;      // '10m', '100m', '1g'
+    maxFiles: number;
+    compress?: boolean;
+    datePattern?: string; // 'YYYY-MM-DD'
+  };
+  
+  // Stream transport
+  stream?: {
+    stream: NodeJS.WritableStream;
+  };
+  
+  // HTTP transport
+  http?: {
+    url: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    batchSize?: number;
+    flushInterval?: number;
+    retry?: {
+      attempts: number;
+      delay: number;
+    };
+  };
+  
+  // External services
+  datadog?: {
+    apiKey: string;
+    site: string;
+    service: string;
+    source: string;
+    tags?: string[];
+  };
+  
+  elasticsearch?: {
+    node: string | string[];
+    index: string;
+    type?: string;
+    auth?: {
+      username: string;
+      password: string;
+    };
+  };
+}
+
+export interface SamplingConfig {
+  enabled: boolean;
+  rules: Array<{
+    level?: LogLevel;
+    service?: LogService;
+    rate: number;         // 0.0 to 1.0
+    condition?: (meta: BaseLogMeta) => boolean;
+  }>;
+}
+
+export interface FilterConfig {
+  enabled: boolean;
+  rules: Array<{
+    type: 'include' | 'exclude';
+    field: string;
+    pattern: string | RegExp;
+    action?: 'drop' | 'redact' | 'mask';
+  }>;
+}
+
+export interface BufferConfig {
+  enabled: boolean;
+  size: number;           // Max buffer size
+  flushInterval: number;  // Flush interval in ms
+  dropOnOverflow?: boolean;
+}
+
+export interface LoggerConfig {
+  // Basic
+  service: LogService;
+  environment: 'development' | 'staging' | 'production';
+  version: string;
+  hostname?: string;
+  
+  // Levels
+  level: LogLevel;
+  levels?: Record<string, LogLevel>; // Component-specific levels
+  
+  // Format
+  format: LogFormat;
+  prettyPrint?: boolean;
+  colorize?: boolean;
+  timestamps?: boolean;
+  
+  // Transports
+  transports: TransportConfig[];
+  
+  // Performance
+  buffer?: BufferConfig;
+  sampling?: SamplingConfig;
+  
+  // Security
+  filters?: FilterConfig;
+  sanitize?: {
+    enabled: boolean;
+    fields: string[];     // Fields to sanitize
+    replacement?: string;
+  };
+  
+  // Error handling
+  exitOnError?: boolean;
+  handleExceptions?: boolean;
+  handleRejections?: boolean;
+  
+  // Metadata
+  defaultMeta?: Record<string, unknown>;
+  contextStorage?: 'asynclocal' | 'cls-hooked' | 'none';
+}
+
+// ============================================
+// LOGGER INTERFACE
+// ============================================
+
+export interface Logger {
+  // Basic logging
+  fatal(message: string, meta?: Partial<BaseLogMeta>): void;
+  error(message: string, meta?: Partial<ErrorLogMeta>): void;
+  warn(message: string, meta?: Partial<BaseLogMeta>): void;
+  info(message: string, meta?: Partial<BaseLogMeta>): void;
+  debug(message: string, meta?: Partial<BaseLogMeta>): void;
+  trace(message: string, meta?: Partial<BaseLogMeta>): void;
+  
+  // Specialized logging
+  audit(action: string, meta: Omit<AuditLogMeta, 'type' | 'level'>): void;
+  security(event: SecurityLogMeta['event'], meta: Omit<SecurityLogMeta, 'type' | 'level'>): void;
+  performance(operation: string, duration: number, meta?: Partial<PerformanceLogMeta>): void;
+  metric(name: string, value: number, meta?: Partial<MetricsLogMeta>): void;
+  
+  // Context management
+  child(context: Partial<BaseLogMeta>): Logger;
+  setContext(context: Partial<BaseLogMeta>): void;
+  clearContext(): void;
+  
+  // Workflow logging
+  startWorkflow(workflow: WorkflowContext): void;
+  endWorkflow(success: boolean, meta?: Partial<WorkflowLogMeta>): void;
+  
+  // Request logging
+  startRequest(request: RequestContext): void;
+  endRequest(statusCode: number, duration: number): void;
+  
+  // Utilities
+  profile(id: string): void;
+  startTimer(): () => void;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+
+// ============================================
+// QUERY & SEARCH
+// ============================================
+
+export interface LogQuery {
+  startTime?: Date;
+  endTime?: Date;
+  level?: LogLevel | LogLevel[];
+  service?: LogService | LogService[];
+  userId?: string;
+  requestId?: string;
+  traceId?: string;
+  workflowId?: string;
+  executionId?: string;
+  searchText?: string;
+  limit?: number;
+  offset?: number;
+  sort?: 'asc' | 'desc';
+}
+
+export interface LogEntry {
+  id: string;
+  timestamp: Date;
+  message: string;
+  meta: BaseLogMeta;
+  raw?: string;
+}
+
+export interface LogSearchResult {
+  entries: LogEntry[];
+  total: number;
+  hasMore: boolean;
+  query: LogQuery;
+}
+
+// ============================================
+// ALERTS & NOTIFICATIONS
+// ============================================
+
+export interface LogAlert {
+  id: string;
+  name: string;
+  enabled: boolean;
+  condition: {
+    level?: LogLevel;
+    service?: LogService;
+    pattern?: string | RegExp;
+    threshold?: {
+      count: number;
+      window: string;     // '5m', '1h', '24h'
+    };
+  };
+  notification: {
+    channels: Array<'email' | 'slack' | 'webhook' | 'pagerduty'>;
+    throttle?: string;    // '5m', '1h'
+    recipients?: string[];
+    webhookUrl?: string;
+  };
+}
+
+// ============================================
+// EXPORT UTILITIES
+// ============================================
+
+export type AnyLogMeta = 
+  | SystemLogMeta 
+  | PerformanceLogMeta 
+  | DatabaseLogMeta 
+  | APILogMeta 
+  | SecurityLogMeta 
+  | AuditLogMeta 
+  | ErrorLogMeta 
+  | WorkflowLogMeta 
+  | MetricsLogMeta;
+
+export type LogFunction = (message: string, meta?: Partial<BaseLogMeta>) => void;