voltlog-io 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,1142 @@
+/**
+ * @module voltlog-io
+ * @description Type definitions for the OCPP-aware structured logger.
+ */
+declare const LogLevel: {
+    readonly TRACE: 10;
+    readonly DEBUG: 20;
+    readonly INFO: 30;
+    readonly WARN: 40;
+    readonly ERROR: 50;
+    readonly FATAL: 60;
+    readonly SILENT: number;
+};
+type LogLevelName = keyof typeof LogLevel;
+/** Numeric log level value */
+type LogLevelValue = (typeof LogLevel)[LogLevelName];
+/** Map from level name (lowercase) to numeric value */
+declare const LogLevelNameMap: Record<string, number>;
+/** Map from numeric value to level name */
+declare const LogLevelValueMap: Record<number, LogLevelName>;
+interface LogEntry<TMeta = Record<string, unknown>> {
+    /** Unique log ID (cuid2) */
+    id: string;
+    /** Numeric log level */
+    level: number;
+    /** Human-readable level name */
+    levelName: LogLevelName;
+    /** Log message */
+    message: string;
+    /** Unix epoch timestamp (ms) */
+    timestamp: number;
+    /** User-defined structured metadata (type-safe via generics) */
+    meta: TMeta;
+    /** Bound context from child logger (e.g. chargePointId, sessionId) */
+    context?: Record<string, unknown>;
+    /** Correlation ID for tracing across async operations */
+    correlationId?: string;
+    /** Error information */
+    error?: LogError;
+}
+interface LogError {
+    message: string;
+    stack?: string;
+    code?: string;
+    name?: string;
+}
+interface OcppExchangeMeta {
+    /** Charge point / station identity */
+    chargePointId?: string;
+    /** OCPP message type */
+    messageType?: "CALL" | "CALLRESULT" | "CALLERROR";
+    /** OCPP action name (e.g. BootNotification) */
+    action?: string;
+    /** Message direction */
+    direction?: "IN" | "OUT";
+    /** Correlation ID for request/response matching */
+    correlationId?: string;
+    /** Negotiated OCPP protocol version */
+    protocol?: string;
+    /** Serialized payload size in bytes */
+    payloadSize?: number;
+    /** Latency in milliseconds */
+    latencyMs?: number;
+    /** Response status (e.g. Accepted, Rejected) */
+    status?: string;
+}
+/**
+ * A Transport receives formatted log entries and delivers them
+ * to a destination (console, file, webhook, database, etc.).
+ *
+ * Transports are async-safe — `write()` can return a Promise.
+ */
+interface Transport<TMeta = Record<string, unknown>> {
+    /** Unique name for this transport */
+    name: string;
+    /** Optional per-transport level filter */
+    level?: LogLevelName;
+    /** Process a log entry */
+    write(entry: LogEntry<TMeta>): void | Promise<void>;
+    /** Flush any buffered entries */
+    flush?(): void | Promise<void>;
+    /** Graceful shutdown */
+    close?(): void | Promise<void>;
+}
+/**
+ * Middleware intercepts log entries before they reach transports.
+ * Used for redaction, sampling, enrichment, alerting, etc.
+ *
+ * Call `next(entry)` to continue the pipeline.
+ * Omit `next()` to drop the entry (e.g. sampling).
+ */
+type LogMiddleware<TMeta = Record<string, unknown>> = (entry: LogEntry<TMeta>, next: (entry: LogEntry<TMeta>) => void) => void;
+/**
+ * Alert rules evaluate log entries and fire callbacks
+ * when configurable conditions are met.
+ */
+interface AlertRule<TMeta = Record<string, unknown>> {
+    /** Alert name (for identification) */
+    name: string;
+    /** Condition — return true if this entry should count toward the alert */
+    when: (entry: LogEntry<TMeta>) => boolean;
+    /** Number of matching entries required to fire (default: 1) */
+    threshold?: number;
+    /** Time window in ms for threshold counting */
+    windowMs?: number;
+    /** Minimum cooldown in ms between alert firings (default: 0) */
+    cooldownMs?: number;
+    /** Callback fired when alert conditions are met */
+    onAlert: (entries: LogEntry<TMeta>[]) => void | Promise<void>;
+}
+interface LoggerOptions<TMeta = Record<string, unknown>> {
+    /** Minimum log level (default: INFO) */
+    level?: LogLevelName;
+    /** Transports for log output */
+    transports?: Transport<TMeta>[];
+    /** Middleware pipeline */
+    middleware?: LogMiddleware<TMeta>[];
+    /** Alert rules */
+    alerts?: AlertRule<TMeta>[];
+    /** Default bound context for all log entries */
+    context?: Record<string, unknown>;
+    /** Field paths to auto-redact (e.g. ['idToken', 'password']) */
+    redact?: string[];
+    /**
+     * When to include error stack traces:
+     * - `true` — always include
+     * - `false` — never include
+     * - `LogLevelName` — include at this level and above
+     * Default: 'ERROR'
+     */
+    includeStack?: boolean | LogLevelName;
+    /**
+     * Exchange log mode:
+     * - `true` — exchange logs alongside normal logs
+     * - `'only'` — only exchange-formatted logs
+     * - `false` — disabled (default)
+     */
+    exchangeLog?: boolean | "only";
+    /** Custom timestamp function (default: Date.now) */
+    timestamp?: () => number;
+}
+interface Logger<TMeta = Record<string, unknown>> {
+    trace(message: string, meta?: Partial<TMeta>): void;
+    debug(message: string, meta?: Partial<TMeta>): void;
+    info(message: string, meta?: Partial<TMeta>): void;
+    warn(message: string, meta?: Partial<TMeta>): void;
+    error(message: string, metaOrError?: Partial<TMeta> | Error, error?: Error): void;
+    fatal(message: string, metaOrError?: Partial<TMeta> | Error, error?: Error): void;
+    /** Create a child logger with additional bound context */
+    child(context: Record<string, unknown>): Logger<TMeta>;
+    /** Add a transport at runtime */
+    addTransport(transport: Transport<TMeta>): void;
+    /** Remove a transport by name */
+    removeTransport(name: string): void;
+    /** Add middleware at runtime */
+    addMiddleware(middleware: LogMiddleware<TMeta>): void;
+    /** Flush all transports */
+    flush(): Promise<void>;
+    /** Close all transports gracefully */
+    close(): Promise<void>;
+}
+
+/**
+ * @module voltlog-io
+ * @description Log level utilities — filtering, comparison, resolution.
+ */
+
+/**
+ * Resolve a level name string to its numeric value.
+ * Case-insensitive. Returns INFO if unrecognized.
+ */
+declare function resolveLevel(level: string | LogLevelName): number;
+/**
+ * Check if a log entry at `entryLevel` passes the `filterLevel`.
+ */
+declare function shouldLog(entryLevel: number, filterLevel: number): boolean;
+/**
+ * Determine whether to include stack trace for a given entry level.
+ */
+declare function shouldIncludeStack(entryLevel: number, includeStack: boolean | LogLevelName): boolean;
+
+/**
+ * @module voltlog-io
+ * @description Core Logger class — zero external dependencies (only cuid2), runtime-agnostic.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createLogger, consoleTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   level: 'INFO',
+ *   transports: [consoleTransport()],
+ * });
+ *
+ * logger.info('Server started', { port: 9000 });
+ * ```
+ *
+ * @example Child logger with bound context
+ * ```ts
+ * const cpLogger = logger.child({ chargePointId: 'CP-101' });
+ * cpLogger.info('BootNotification received');
+ * // → auto-includes context: { chargePointId: 'CP-101' }
+ * ```
+ *
+ * @example Error with stack trace
+ * ```ts
+ * logger.error('Connection failed', new Error('ETIMEDOUT'));
+ * logger.error('Handler crashed', { action: 'BootNotification' }, new Error('null ref'));
+ * ```
+ *
+ * @example With ocpp-ws-io (if user has both packages)
+ * ```ts
+ * import { createLogger } from 'ocpp-ws-io/logger'; // re-export
+ * ```
+ */
+
+/**
+ * Create a new logger instance.
+ *
+ * @example Minimal
+ * ```ts
+ * const logger = createLogger();
+ * logger.info('Hello');
+ * ```
+ *
+ * @example Full options
+ * ```ts
+ * import { createLogger, consoleTransport, prettyTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   level: 'DEBUG',
+ *   transports: [prettyTransport()],
+ *   redact: ['password', 'idToken'],
+ *   includeStack: 'ERROR',
+ * });
+ * ```
+ *
+ * @example OCPP-aware with child loggers
+ * ```ts
+ * import { createLogger, prettyTransport } from 'voltlog-io';
+ * import type { OcppExchangeMeta } from 'voltlog-io';
+ *
+ * const logger = createLogger<OcppExchangeMeta>({
+ *   level: 'INFO',
+ *   transports: [prettyTransport()],
+ * });
+ *
+ * // Per-connection child logger
+ * const cpLog = logger.child({ chargePointId: 'CP-101' });
+ * cpLog.info('OCPP message', {
+ *   messageType: 'CALL',
+ *   action: 'BootNotification',
+ *   direction: 'IN',
+ * });
+ * ```
+ */
+declare function createLogger<TMeta = Record<string, unknown>>(options?: LoggerOptions<TMeta>): Logger<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description AI Enrichment middleware — enriches logs with AI analysis (e.g. error explanation).
+ * @universal Works in all environments (uses `fetch`).
+ *
+ * > **Security Note**: Requires an API Key. Using this in the browser will expose your key to the client.
+ * > Recommended for server-side use only.
+ */
+
+interface AiEnrichmentOptions {
+    /**
+     * Only trigger for logs at or above this level.
+     * Default: ERROR
+     */
+    level?: LogLevelName;
+    /**
+     * Field name to store the analysis result in `entry.meta`.
+     * Default: 'ai_analysis'
+     */
+    targetField?: string;
+    /**
+     * Custom analyzer function.
+     * Return a string (analysis) or object (structured data) to attach to `meta[targetField]`.
+     */
+    analyzer: (entry: LogEntry) => Promise<string | Record<string, unknown> | null>;
+    /**
+     * Timeout in milliseconds for the AI call.
+     * Default: 2000ms (fail fast to avoid blocking for too long)
+     */
+    timeout?: number;
+    /**
+     * If true, errors in the analyzer are swallowed (logged to console.error but don't crash).
+     * Default: true
+     */
+    swallowErrors?: boolean;
+}
+/**
+ * Enriches log entries by calling an asynchronous AI analyzer.
+ * Appends result to `entry.meta[targetField]`.
+ *
+ * @example
+ * ```ts
+ * const ai = aiEnrichmentMiddleware({
+ *   analyzer: createOpenAiErrorAnalyzer(process.env.OPENAI_API_KEY!),
+ *   level: "ERROR",
+ *   targetField: "error_explanation"
+ * });
+ * ```
+ */
+declare function aiEnrichmentMiddleware<TMeta = Record<string, unknown>>(options: AiEnrichmentOptions): LogMiddleware<TMeta>;
+/**
+ * Helper to create an OpenAI-compatible analyzer specifically for Error explanation.
+ */
+declare function createOpenAiErrorAnalyzer(apiKey: string, model?: string, systemPrompt?: string): (entry: LogEntry) => Promise<string | null>;
+
+/**
+ * @module voltlog-io
+ * @description Alert middleware — checks logs against rules and triggers alerts.
+ * @universal Works in all environments.
+ * @example
+ * ```ts
+ * import { createLogger, consoleTransport, alertMiddleware } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   transports: [consoleTransport()],
+ *   middleware: [
+ *     alertMiddleware([
+ *       {
+ *         name: 'error-spike',
+ *         when: (entry) => entry.level >= 50, // ERROR+
+ *         threshold: 10,
+ *         windowMs: 60_000,
+ *         cooldownMs: 300_000,
+ *         onAlert: async (entries) => {
+ *           await sendEmail({ subject: `${entries.length} errors in 1 min` });
+ *         },
+ *       },
+ *       {
+ *         name: 'callerror-alert',
+ *         when: (entry) => entry.meta.messageType === 'CALLERROR',
+ *         threshold: 5,
+ *         windowMs: 60_000,
+ *         onAlert: (entries) => sendSlackNotification(entries),
+ *       },
+ *     ]),
+ *   ],
+ * });
+ * ```
+ */
+
+/**
+ * Create an alert middleware that evaluates rules against every log entry.
+ *
+ * Alerts are non-blocking — `onAlert` failures are silently caught
+ * to never interfere with the logging pipeline.
+ */
+declare function alertMiddleware<TMeta = Record<string, unknown>>(rules: AlertRule<TMeta>[]): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description Correlation ID middleware — adds tracing IDs to logs.
+ * @universal Works in all environments.
+ * Useful for tracking requests across microservices.
+ */
+
+interface CorrelationIdOptions {
+    /**
+     * Header name or meta key to check for existing ID.
+     * Default: 'x-correlation-id' (and checks 'traceId', 'correlationId')
+     */
+    header?: string;
+    /**
+     * Function to generate new IDs.
+     * Default: cuid2
+     */
+    generator?: () => string;
+}
+/**
+ * Middleware that ensures every log entry has a correlation ID.
+ * checks:
+ * 1. entry.correlationId
+ * 2. entry.meta.correlationId
+ * 3. entry.meta.traceId
+ * 4. entry.meta[header]
+ *
+ * If none found, generates a new one.
+ */
+declare function correlationIdMiddleware<TMeta = Record<string, unknown>>(options?: CorrelationIdOptions): LogMiddleware<TMeta>;
+
+/**
+ * Helper to create a type-safe middleware function.
+ *
+ * @example
+ * const myMiddleware = createMiddleware((entry, next) => {
+ *   entry.meta.foo = 'bar';
+ *   next(entry);
+ * });
+ */
+declare function createMiddleware<TMeta = Record<string, unknown>>(fn: LogMiddleware<TMeta>): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description Deduplication middleware — groups identical logs in a time window.
+ * @universal Works in all environments.
+ */
+
+interface DeduplicationOptions<TMeta = Record<string, unknown>> {
+    /**
+     * Time window in ms to group logs.
+     * Logs matching the key within this window will be aggregated.
+     * Default: 1000ms
+     */
+    windowMs?: number;
+    /**
+     * Function to generate a unique key for deduplication.
+     * Default: uses `entry.message` + `entry.level`
+     */
+    keyFn?: (entry: LogEntry<TMeta>) => string;
+}
+/**
+ * Deduplication middleware.
+ * Buffers logs for `windowMs`. If identical logs arrive, increments a counter.
+ * Emits the log once at the end of the window with `meta.duplicateCount`.
+ */
+declare function deduplicationMiddleware<TMeta = Record<string, unknown>>(options?: DeduplicationOptions<TMeta>): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description Heap usage middleware — adds memory stats to logs.
+ * @universal Works in all environments, but only adds data in Node.js/Bun/Deno.
+ * Checks for `process.memoryUsage` presence before execution.
+ */
+
+interface HeapUsageOptions {
+    /**
+     * Field name to store memory stats in `entry.meta`.
+     * Default: 'memory'
+     */
+    fieldName?: string;
+}
+/**
+ * Adds `rss`, `heapTotal`, and `heapUsed` to log metadata.
+ * Only works in environments where `process.memoryUsage` is available (Node.js/Bun/Deno).
+ */
+declare function heapUsageMiddleware<TMeta = Record<string, unknown>>(options?: HeapUsageOptions): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description IP middleware — extracts client IP from headers (x-forwarded-for, etc.).
+ * @universal Works in any environment where headers are available in metadata.
+ */
+
+interface IpMiddlewareOptions {
+    /**
+     * Field name to store the extracted IP in `entry.meta`.
+     * Default: 'ip'
+     */
+    fieldName?: string;
+    /**
+     * Custom list of headers/keys to check for IP address.
+     * Default: ['x-forwarded-for', 'x-real-ip', 'req.ip', 'ip']
+     */
+    headerKeys?: string[];
+}
+/**
+ * Extracts IP address from commonly used headers in `entry.meta`.
+ */
+declare function ipMiddleware<TMeta = Record<string, unknown>>(options?: IpMiddlewareOptions): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description Level Override middleware — allows forcing a log level for specific requests.
+ * @universal Works in all environments.
+ * Useful for debugging specific users/requests in production without changing global config.
+ */
+
+interface LevelOverrideOptions {
+    /**
+     * Header name or meta key to trigger override.
+     * Default: 'x-log-level'
+     */
+    key?: string;
+    /**
+     * If true, removes the trigger key from metadata before logging.
+     * Default: true
+     */
+    cleanup?: boolean;
+}
+/**
+ * Dynamically changes the log entry level if a specific key is found in meta/context.
+ * E.g. passing `x-log-level: DEBUG` allows a specific request to bypass INFO filters.
+ */
+declare function levelOverrideMiddleware<TMeta = Record<string, unknown>>(options?: LevelOverrideOptions): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description OCPP middleware — masks sensitive fields and calculates latency for OCPP messages.
+ * @universal Works in all environments.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, consoleTransport, ocppMiddleware } from 'voltlog-io';
+ * import type { OcppExchangeMeta } from 'voltlog-io';
+ *
+ * const logger = createLogger<OcppExchangeMeta>({
+ *   transports: [consoleTransport()],
+ *   middleware: [ocppMiddleware()],
+ * });
+ *
+ * // The middleware auto-computes payloadSize and adds correlationId to the entry
+ * logger.info('Message received', {
+ *   action: 'BootNotification',
+ *   messageType: 'CALL',
+ *   direction: 'IN',
+ * });
+ * ```
+ */
+
+interface OcppMiddlewareOptions {
+    /**
+     * Automatically compute payload size from meta if not set.
+     * Default: true
+     */
+    autoPayloadSize?: boolean;
+    /**
+     * Propagate correlationId from meta to entry.correlationId.
+     * Default: true
+     */
+    propagateCorrelationId?: boolean;
+}
+/**
+ * Create an OCPP enrichment middleware.
+ * Enriches log entries with computed OCPP metadata.
+ */
+declare function ocppMiddleware(options?: OcppMiddlewareOptions): LogMiddleware<OcppExchangeMeta>;
+
+/**
+ * @module voltlog-io
+ * @description Redaction middleware — masks sensitive data in log entries.
+ * @universal Works in all environments.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, consoleTransport, redactionMiddleware } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   transports: [consoleTransport()],
+ *   middleware: [redactionMiddleware({ paths: ['password', 'idToken', 'authorization'] })],
+ * });
+ *
+ * logger.info('Auth attempt', { password: 's3cret', user: 'admin' });
+ * // → { password: '[REDACTED]', user: 'admin' }
+ * ```
+ */
+
+interface RedactionOptions {
+    /** Field paths to redact (case-insensitive matching) */
+    paths: string[];
+    /** Replacement value (default: '[REDACTED]') */
+    replacement?: string;
+    /** Also redact matching keys in nested objects (default: true) */
+    deep?: boolean;
+}
+/**
+ * Create a redaction middleware that replaces sensitive field values.
+ */
+declare function redactionMiddleware<TMeta = Record<string, unknown>>(options: RedactionOptions): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description Sampling middleware — rate limits or probabilistically samples logs.
+ * @universal Works in all environments.
+ * @example
+ * ```ts
+ * import { createLogger, consoleTransport, samplingMiddleware } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   transports: [consoleTransport()],
+ *   middleware: [
+ *     samplingMiddleware({
+ *       keyFn: (entry) => `${entry.meta.action}:${entry.meta.chargePointId}`,
+ *       maxPerWindow: 10,
+ *       windowMs: 60_000, // 10 logs per minute per action+CP combo
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+interface SamplingOptions<TMeta = Record<string, unknown>> {
+    /**
+     * Function to extract a sampling key from a log entry.
+     * Entries with the same key share a rate limit.
+     * Default: uses `entry.message`
+     */
+    keyFn?: (entry: LogEntry<TMeta>) => string;
+    /** Maximum entries allowed per key per window (default: 100) */
+    maxPerWindow?: number;
+    /** Time window in ms (default: 60000 = 1 minute) */
+    windowMs?: number;
+    /** Probability to keep a log (0 to 1). Default: 1 (keep all) */
+    sampleRate?: number;
+    /** Logs at this level or higher always pass. Default: 40 (WARN) */
+    priorityLevel?: number;
+}
+/**
+ * Create a sampling middleware that drops logs exceeding the rate limit.
+ */
+declare function samplingMiddleware<TMeta = Record<string, unknown>>(options?: SamplingOptions<TMeta>): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description User Agent middleware — parses UA strings into browser/os/device info.
+ * @universal Works in all environments (Server/Browser).
+ * Lightweight regex-based parsing to avoid heavy dependencies.
+ */
+
+interface UserAgentOptions {
+    /**
+     * Field to look for user agent string (source).
+     * Default checks `entry.meta.userAgent`, `entry.meta['user-agent']`, or context.
+     */
+    sourceField?: string;
+    /**
+     * Field to store the parsed info (target).
+     * Default: 'client'
+     */
+    targetField?: string;
+}
+/**
+ * Parses user-agent string into structured data (browser, os).
+ */
+declare function userAgentMiddleware<TMeta = Record<string, unknown>>(options?: UserAgentOptions): LogMiddleware<TMeta>;
+
+/**
+ * @module voltlog-io
+ * @description Batch transformer — wraps another transformer and buffers logs.
+ * @universal Works in all environments.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, batchTransport, consoleTransport } from 'voltlog-io';
+ *
+ * // Batch console output: flush every 100 entries or every 2 seconds
+ * const logger = createLogger({
+ *   transports: [
+ *     batchTransport(consoleTransport(), { batchSize: 100, flushIntervalMs: 2000 }),
+ *   ],
+ * });
+ * ```
+ */
+
+interface BatchTransportOptions {
+    /** Number of entries to buffer before flushing (default: 100) */
+    batchSize?: number;
+    /** Max time in ms to wait before flushing a partial batch (default: 5000) */
+    flushIntervalMs?: number;
+}
+/**
+ * Wrap any transport with batching. Entries are buffered and flushed
+ * either when the batch is full or the timer fires.
+ */
+declare function batchTransport(inner: Transport, options?: BatchTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Browser stream transformer — writes newline-delimited JSON to a WHATWG WritableStream.
+ * @browser-only Depends on WHATWG Streams API (typical in Browsers/Edge).
+ * Useful for streaming logs in browser environments (e.g. to `fetch` streams or ServiceWorkers).
+ */
+
+interface BrowserJsonStreamTransportOptions {
+    /**
+     * Writable stream to output to.
+     * Must be a standard WHATWG WritableStream (available in modern browsers).
+     */
+    stream: WritableStream<string>;
+    /** Per-transport level filter */
+    level?: LogLevelName;
+    /**
+     * Custom serializer. Return the string to write.
+     * Default: JSON.stringify(entry) + '\n'
+     */
+    serializer?: (entry: LogEntry) => string;
+}
+/**
+ * Create a JSON stream transport for browsers that writes to a WritableStream.
+ */
+declare function browserJsonStreamTransport(options: BrowserJsonStreamTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Console transformer — writes to `console.log`, `console.error`, etc.
+ * @universal Works in all environments. Works in Node.js, browsers, and all runtimes.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, consoleTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   transports: [consoleTransport()],
+ * });
+ * ```
+ */
+
+interface ConsoleTransportOptions {
+    /** Per-transport level filter */
+    level?: LogLevelName;
+    /**
+     * Use appropriate console method per level (console.warn, console.error, etc.).
+     * Default: true
+     */
+    useConsoleLevels?: boolean;
+    /**
+     * Format the entry before outputting. Return any value that console.log can handle.
+     * Default: serializes to JSON string.
+     */
+    formatter?: (entry: LogEntry) => unknown;
+}
+/**
+ * Create a console transport. Outputs structured JSON to the console.
+ */
+declare function consoleTransport(options?: ConsoleTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Helper to create custom transports easily.
+ * @universal Works in all environments.
+ */
+
+/**
+ * Helper to build a transport without manually defining the object structure.
+ *
+ * @example
+ * const myTransport = createTransport('my-api', async (entry) => {
+ *   await fetch('https://api.example.com/logs', { body: JSON.stringify(entry) });
+ * });
+ *
+ * @param name - Unique name for the transport
+ * @param write - Function to process log entries
+ * @param options - Optional overrides (level, flush, close)
+ */
+declare function createTransport(name: string, write: (entry: LogEntry) => void | Promise<void>, options?: Partial<Omit<Transport, "name" | "write">>): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Datadog transformer — sends logs directly to Datadog Intake API.
+ * @universal Works in all environments (uses `fetch`).
+ *
+ * > **Security Note**: Using this in the browser will expose your API Key.
+ * > Recommended for server-side use only.
+ */
+
+interface DatadogTransportOptions {
+    /** Datadog API Key */
+    apiKey: string;
+    /** Datadog Site (default: datadoghq.com) */
+    site?: string;
+    /** Service name tag */
+    service?: string;
+    /** Source tag (default: nodejs) */
+    ddSource?: string;
+    /** Hostname override */
+    hostname?: string;
+    /** Tags (comma separated: env:prod,version:1.0) */
+    tags?: string;
+    /** Transport level filter */
+    level?: LogLevelName;
+}
+/**
+ * Sends logs to Datadog via HTTP POST.
+ * Uses built-in batching (not implemented here for brevity, typically would use batchTransport wrapper).
+ * This implementation sends immediately for simplicity or relies on `batchTransport` composition.
+ */
+declare function datadogTransport(options: DatadogTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Discord transformer — sends logs to Discord via Webhook.
+ * @universal Works in all environments (uses `fetch`).
+ *
+ * > **Security Note**: Using this in the browser will expose your Webhook URL.
+ * > Recommended for server-side use only.
+ */
+
+interface DiscordTransportOptions {
+    /** Discord Webhook URL */
+    webhookUrl: string;
+    /** Minimum log level (default: ERROR) */
+    level?: LogLevelName;
+    /** Username override */
+    username?: string;
+    /** Avatar URL override */
+    avatarUrl?: string;
+}
+/**
+ * Sends formatted embeds to Discord.
+ * Best used for Alerts/Errors.
+ */
+declare function discordTransport(options: DiscordTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description File transformer — writes logs to disk with daily rotation.
+ * @server-only
+ * This transport relies on the `node:fs` module to write files to the local filesystem.
+ * Browsers do not have direct access to the filesystem for security reasons.
+ */
+
+interface FileTransportOptions {
+    /** Directory to store logs. Created if missing. */
+    dir: string;
+    /**
+     * Filename pattern. Use `%DATE%` for YYYY-MM-DD.
+     * Default: `app-%DATE%.log`
+     */
+    filename?: string;
+    /** Per-transport level filter */
+    level?: LogLevelName;
+}
+/**
+ * Creates a file transport that writes newline-delimited JSON.
+ * Rotates files daily based on the `%DATE%` pattern.
+ */
+declare function fileTransport(options: FileTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description JSON stream transformer — writes newline-delimited JSON to any writable stream.
+ * @server-only
+ * This transport relies on Node.js-style `Writable` streams (e.g. `process.stdout`, `fs.createWriteStream`).
+ * Browser streams (WHATWG Streams API) use a different interface.
+ *
+ * Useful for file logging, piping to external tools, etc.
+ *
+ * @example Write to file
+ * ```ts
+ * import { createWriteStream } from 'node:fs';
+ * import { createLogger, jsonStreamTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   transports: [
+ *     jsonStreamTransport({ stream: createWriteStream('./app.log', { flags: 'a' }) }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example Write to stdout
+ * ```ts
+ * const logger = createLogger({
+ *   transports: [jsonStreamTransport({ stream: process.stdout })],
+ * });
+ * ```
+ */
+
+interface JsonStreamTransportOptions {
+    /** Writable stream to output to (e.g. fs.createWriteStream, process.stdout) */
+    stream: NodeJS.WritableStream;
+    /** Per-transport level filter */
+    level?: LogLevelName;
+    /**
+     * Custom serializer. Return the string to write.
+     * Default: JSON.stringify(entry) + '\n'
+     */
+    serializer?: (entry: LogEntry) => string;
+}
+/**
+ * Create a JSON stream transport that writes newline-delimited JSON.
+ */
+declare function jsonStreamTransport(options: JsonStreamTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Loki transformer — pushes logs to Grafana Loki.
+ * @universal Works in all environments (uses `fetch`).
+ *
+ * > **Security Note**: Using this in the browser exposes auth details and may face CORS issues.
+ * > Recommended for server-side use.
+ */
+
+interface LokiTransportOptions {
+    /** Loki URL (e.g. http://localhost:3100) */
+    host: string;
+    /** Basic Auth username */
+    basicAuthUser?: string;
+    /** Basic Auth password/token */
+    basicAuthPassword?: string;
+    /** Tenant ID (header X-Scope-OrgID) */
+    tenantId?: string;
+    /** Labels to attach to every stream (e.g. { app: 'volt-server' }) */
+    labels?: Record<string, string>;
+    /** Transport level filter */
+    level?: LogLevelName;
+    /** Batch size (default: 10) */
+    batchSize?: number;
+    /** Batch interval ms (default: 5000) */
+    interval?: number;
+}
+/**
+ * Pushes logs to Grafana Loki via HTTP API.
+ * Uses batching to improve performance.
+ */
+declare function lokiTransport(options: LokiTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Pretty transformer — human-readable colored output with OCPP exchange formatting.
+ * @universal Works in all environments (uses ANSI codes, supported by many browser consoles or stripped).
+ *
+ * @example Dev mode
+ * ```ts
+ * import { createLogger, prettyTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   transports: [prettyTransport()],
+ * });
+ *
+ * logger.info('Server started', { port: 9000 });
+ * // → ℹ 2024-01-15T10:30:00.000Z  INFO  Server started  { port: 9000 }
+ * ```
+ *
+ * @example OCPP exchange logs
+ * ```ts
+ * logger.info('OCPP exchange', {
+ *   chargePointId: 'CP-101',
+ *   action: 'BootNotification',
+ *   messageType: 'CALL',
+ *   direction: 'IN',
+ *   latencyMs: 34,
+ *   status: 'Accepted',
+ * });
+ * // → ⚡ CP-101  →  BootNotification  [IN]  CALL
+ * // → ✔ Accepted  (34ms)
+ * ```
+ */
+
+interface PrettyTransportOptions {
+    /** Per-transport level filter */
+    level?: LogLevelName;
+    /** Show timestamps (default: true) */
+    timestamps?: boolean;
+    /** Use colors in output (default: true) */
+    colors?: boolean;
+}
+/**
+ * Create a pretty-print transport for dev/debug use.
+ * Includes OCPP exchange log prettification.
+ */
+declare function prettyTransport(options?: PrettyTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Redis Streams transformer — publishes log entries to a Redis Stream.
+ * @server-only
+ * Designed for standard Redis clients (like `ioredis`) which use TCP sockets (unavailable in browsers).
+ * For HTTP-based Redis (e.g. Upstash), use a custom transformer or `webhookTransport`.
+ *
+ * Users can then subscribe (XREAD/XREADGROUP) for real-time dashboards, monitoring, etc.
+ *
+ * Requires `ioredis` — user brings their own client instance (no hard dep).
+ *
+ * @example Basic
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { createLogger, redisTransport } from 'voltlog-io';
+ *
+ * const redis = new Redis();
+ * const logger = createLogger({
+ *   transports: [
+ *     redisTransport({ client: redis, streamKey: 'logs:ocpp' }),
+ *   ],
+ * });
+ *
+ * logger.info('CP connected', { chargePointId: 'CP-101' });
+ * // → XADD logs:ocpp * level INFO message "CP connected" ...
+ * ```
+ *
+ * @example With TTL and max stream length
+ * ```ts
+ * redisTransport({
+ *   client: redis,
+ *   streamKey: 'logs:ocpp',
+ *   maxLen: 10_000,        // keep last 10k entries (approximate trim)
+ * })
+ * ```
+ *
+ * @example Subscribing (consumer side)
+ * ```ts
+ * // In your dashboard / monitoring service:
+ * const redis = new Redis();
+ *
+ * // Read new entries from the stream
+ * const entries = await redis.xread('BLOCK', 0, 'STREAMS', 'logs:ocpp', '$');
+ *
+ * // Or use consumer groups for at-least-once delivery:
+ * await redis.xgroup('CREATE', 'logs:ocpp', 'dashboard', '$', 'MKSTREAM');
+ * const entries = await redis.xreadgroup(
+ *   'GROUP', 'dashboard', 'worker-1',
+ *   'BLOCK', 0, 'STREAMS', 'logs:ocpp', '>'
+ * );
+ * ```
+ */
+
+/**
+ * Minimal interface for the Redis client methods we need.
+ * Compatible with `ioredis` — user provides their own instance.
+ */
+interface RedisClient {
+    xadd(...args: (string | number)[]): Promise<string | null>;
+    quit?(): Promise<void>;
+}
+interface RedisTransportOptions {
+    /** Redis client instance (e.g. `new Redis()` from ioredis) */
+    client: RedisClient;
+    /** Redis Stream key to publish to (default: 'logs') */
+    streamKey?: string;
+    /**
+     * Max approximate stream length — older entries are trimmed.
+     * Uses MAXLEN ~ (approximate) to keep the stream bounded.
+     * Default: no limit.
+     */
+    maxLen?: number;
+    /** Per-transport level filter */
+    level?: LogLevelName;
+    /**
+     * Custom field mapper — convert LogEntry to flat key-value pairs for Redis.
+     * Default: serializes the entire entry as JSON under a single 'data' field.
+     */
+    fieldMapper?: (entry: LogEntry) => Record<string, string>;
+}
+/**
+ * Create a Redis Streams transport.
+ *
+ * Publishes each log entry via XADD to a Redis Stream.
+ * Fire-and-forget — errors are silently swallowed to avoid blocking.
+ */
+declare function redisTransport(options: RedisTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Sentry transformer — pushes errors to Sentry.
+ * @universal Works in both Server and Browser (depends on provided Sentry instance).
+ */
+
+/**
+ * Minimal Sentry client interface to avoid hard dependency on @sentry/* packages.
+ * Users pass their Sentry instance (e.g. `import * as Sentry from '@sentry/node'`).
+ */
+interface SentryInstance {
+    captureException(exception: unknown, hint?: unknown): string;
+    captureMessage(message: string, level?: unknown): string;
+    addBreadcrumb(breadcrumb: unknown): void;
+    Severity?: unknown;
+}
+interface SentryTransportOptions {
+    /** Configured Sentry instance/hub */
+    sentry: SentryInstance;
+    /** Minimum level to trigger captureException (default: ERROR) */
+    errorLevel?: LogLevelName;
+    /** Minimum level to send breadcrumbs (default: INFO) */
+    breadcrumbLevel?: LogLevelName;
+}
+/**
+ * Integrates with an existing Sentry instance.
+ * - Logs >= errorLevel -> sent as Exceptions
+ * - Logs >= breadcrumbLevel -> sent as Breadcrumbs
+ */
+declare function sentryTransport(options: SentryTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Slack transformer — sends rich notifications to Slack via Incoming Webhook.
+ * @universal Works in all environments (uses `fetch`).
+ *
+ * > **Security Note**: Using this in the browser will expose your Webhook URL.
+ * > Recommended for server-side use only.
+ * Best used with a filter (e.g. ERROR only) or alert middleware.
+ */
+
+interface SlackTransportOptions {
+    /** Slack Incoming Webhook URL */
+    webhookUrl: string;
+    /** Filter level (default: ERROR) */
+    level?: LogLevelName;
+    /** Custom username (overrides webhook default) */
+    username?: string;
+    /** Custom icon emoji (overrides webhook default) */
+    iconEmoji?: string;
+}
+/**
+ * Sends logs to Slack with formatting.
+ * Best suited for ERROR/FATAL logs or specific alerts.
+ */
+declare function slackTransport(options: SlackTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description Webhook transformer — sends logs via HTTP POST.
+ * @universal Works in all environments (uses `fetch`).
+ * Supports batching for performance.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, webhookTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   transports: [
+ *     webhookTransport({
+ *       url: 'https://my-api.com/logs',
+ *       headers: { Authorization: 'Bearer token123' },
+ *       batchSize: 50,
+ *       flushIntervalMs: 5000,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+interface WebhookTransportOptions {
+    /** Target URL to POST log entries to */
+    url: string;
+    /** HTTP method (default: POST) */
+    method?: string;
+    /** Additional HTTP headers */
+    headers?: Record<string, string>;
+    /** Number of entries to batch before sending (default: 1 = no batching) */
+    batchSize?: number;
+    /** Max time in ms to wait before flushing a partial batch (default: 5000) */
+    flushIntervalMs?: number;
+    /** Per-transport level filter */
+    level?: LogLevelName;
+    /** Custom body serializer. Default: JSON.stringify({ entries: [...] }) */
+    serializer?: (entries: LogEntry[]) => string;
+    /** Retry failed requests (default: false) */
+    retry?: boolean;
+    /** Max retries (default: 3) */
+    maxRetries?: number;
+}
+/**
+ * Create a webhook transport that POSTs log entries to an HTTP endpoint.
+ */
+declare function webhookTransport(options: WebhookTransportOptions): Transport;
+
+export { type AiEnrichmentOptions, type AlertRule, type BatchTransportOptions, type BrowserJsonStreamTransportOptions, type ConsoleTransportOptions, type CorrelationIdOptions, type DatadogTransportOptions, type DeduplicationOptions, type DiscordTransportOptions, type FileTransportOptions, type JsonStreamTransportOptions, type LevelOverrideOptions, type LogEntry, type LogError, LogLevel, type LogLevelName, LogLevelNameMap, type LogLevelValue, LogLevelValueMap, type LogMiddleware, type Logger, type LoggerOptions, type LokiTransportOptions, type OcppExchangeMeta, type OcppMiddlewareOptions, type PrettyTransportOptions, type RedactionOptions, type RedisClient, type RedisTransportOptions, type SamplingOptions, type SentryInstance, type SentryTransportOptions, type SlackTransportOptions, type Transport, type UserAgentOptions, type WebhookTransportOptions, aiEnrichmentMiddleware, alertMiddleware, batchTransport, browserJsonStreamTransport, consoleTransport, correlationIdMiddleware, createLogger, createMiddleware, createOpenAiErrorAnalyzer, createTransport, datadogTransport, deduplicationMiddleware, discordTransport, fileTransport, heapUsageMiddleware, ipMiddleware, jsonStreamTransport, levelOverrideMiddleware, lokiTransport, ocppMiddleware, prettyTransport, redactionMiddleware, redisTransport, resolveLevel, samplingMiddleware, sentryTransport, shouldIncludeStack, shouldLog, slackTransport, userAgentMiddleware, webhookTransport };