voltlog-io 1.0.2 → 1.0.4

package/dist/client.d.mts

@@ -0,0 +1,1247 @@
+/**
+ * @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 */
+    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;
+    /** @internal Cached JSON serialization — avoids redundant stringify across transports */
+    _json?: string;
+}
+interface LogError {
+    message: string;
+    stack?: string;
+    code?: string;
+    name?: string;
+    /** Nested cause chain (ES2022 Error.cause support) */
+    cause?: LogError;
+}
+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 TimerResult<TMeta = Record<string, unknown>> {
+    /** End the timer and log the duration */
+    done(message: string, meta?: Partial<TMeta>): void;
+    /** Get elapsed time in ms without logging */
+    elapsed(): number;
+}
+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;
+    /**
+     * Custom ID generator function.
+     * Default: `crypto.randomUUID()` (native, fast).
+     * Set to `false` to disable ID generation entirely for max performance.
+     */
+    idGenerator?: (() => string) | false;
+}
+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;
+    /** Remove middleware by reference */
+    removeMiddleware(middleware: LogMiddleware<TMeta>): void;
+    /** Change the minimum log level at runtime */
+    setLevel(level: LogLevelName): void;
+    /** Get the current minimum log level */
+    getLevel(): LogLevelName;
+    /** Check if a given level would produce output (useful to guard expensive meta computation) */
+    isLevelEnabled(level: LogLevelName): boolean;
+    /** Start a timer — call `.done(msg)` to log elapsed duration */
+    startTimer(level?: LogLevelName): TimerResult<TMeta>;
+    /** 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>;
+
+/**
+ * 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 Universal HTTP middleware builder. Allows integration with Express, Fastify, exact node:http, etc.
+ * without introducing third-party framework dependencies.
+ */
+
+/**
+ * Extracts essential logic from a given raw HTTP Request object
+ * regardless of the underlying framework (Express, Fastify, etc.)
+ */
+interface HttpRequestMapper<TReq = any> {
+    getMethod: (req: TReq) => string;
+    getUrl: (req: TReq) => string;
+    getIp?: (req: TReq) => string | undefined;
+    getUserAgent?: (req: TReq) => string | undefined;
+    /** Extract a particular header value */
+    getHeader?: (req: TReq, name: string) => string | undefined;
+}
+/**
+ * Extracts essential logic from a given raw HTTP Response object
+ */
+interface HttpResponseMapper<TRes = any> {
+    getStatusCode: (res: TRes) => number;
+    /** Execute callback when response is fully sent to the client */
+    onFinish: (res: TRes, callback: () => void) => void;
+}
+/**
+ * Options for configuring the HTTP access logger
+ */
+interface HttpLoggerOptions<TReq = any, TRes = any> {
+    reqMapper: HttpRequestMapper<TReq>;
+    resMapper: HttpResponseMapper<TRes>;
+    /** Log level to use for HTTP requests (default: INFO) */
+    level?: "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
+    /** Extract specific dynamic context values from the request to add to meta */
+    extractContext?: (req: TReq, res: TRes) => Record<string, unknown>;
+    /** Function to skip logging certain requests (e.g., /health) */
+    skip?: (req: TReq) => boolean;
+}
+/**
+ * Common mappers for the raw Node.js `http.IncomingMessage` and `http.ServerResponse`.
+ * Since Express and many others extend these objects, they work universally.
+ */
+declare const nodeHttpMappers: {
+    req: HttpRequestMapper;
+    res: HttpResponseMapper;
+};
+/**
+ * Creates a generic HTTP logging middleware function.
+ * Use this inside Express, Fastify, or custom routers.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createHttpLogger, nodeHttpMappers, createLogger } from 'voltlog-io';
+ *
+ * const app = express();
+ * const logger = createLogger();
+ *
+ * const httpLogger = createHttpLogger(logger, {
+ *   reqMapper: nodeHttpMappers.req,
+ *   resMapper: nodeHttpMappers.res,
+ * });
+ *
+ * app.use((req, res, next) => {
+ *   httpLogger(req, res);
+ *   next();
+ * });
+ * ```
+ */
+declare function createHttpLogger<TReq = any, TRes = any>(logger: Logger, options: HttpLoggerOptions<TReq, TRes>): (req: TReq, res: TRes) => void;
+
+/**
+ * @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 OpenTelemetry middleware — automatically picks up the active trace context.
+ * Works like Winston's @opentelemetry/instrumentation-winston but as a simple middleware.
+ *
+ * @server-only Requires `@opentelemetry/api` as an optional peer dependency.
+ *
+ * When the OpenTelemetry SDK is active (e.g., with SigNoz, Jaeger, Grafana Tempo),
+ * this middleware automatically injects traceId, spanId, and traceFlags into every log entry.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, otelTraceMiddleware, otelTransport } from 'voltlog-io';
+ *
+ * const logger = createLogger({
+ *   middleware: [otelTraceMiddleware()],
+ *   transports: [
+ *     otelTransport({
+ *       endpoint: 'http://localhost:4318',
+ *       serviceName: 'my-app',
+ *     }),
+ *   ],
+ * });
+ *
+ * // If an OTel span is active, every log automatically gets:
+ * // { traceId: "abc123...", spanId: "def456...", traceFlags: 1 }
+ * logger.info("Processing request");
+ * ```
+ */
+
+interface OtelTraceMiddlewareOptions {
+    /**
+     * Custom reference to `@opentelemetry/api` trace module.
+     * If not provided, we attempt `require('@opentelemetry/api')` or dynamic import.
+     * This allows the middleware to work without a hard dependency.
+     */
+    traceApi?: {
+        trace: {
+            getActiveSpan: () => unknown;
+        };
+    };
+}
+/**
+ * Middleware that automatically injects OpenTelemetry trace context into log entries.
+ *
+ * How it works:
+ * 1. On each log call, checks for an active OTel span
+ * 2. If found, extracts traceId, spanId, and traceFlags
+ * 3. Injects them into the log entry's metadata
+ *
+ * This is the equivalent of Winston's @opentelemetry/instrumentation-winston
+ * but implemented as a zero-dependency middleware.
+ */
+declare function otelTraceMiddleware<TMeta = Record<string, unknown>>(options?: OtelTraceMiddlewareOptions): LogMiddleware<TMeta>;
+
+/**
+ * @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 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;
+    /** Static labels to attach to every stream (e.g. { app: 'volt-server' }) */
+    labels?: Record<string, string>;
+    /**
+     * Extract dynamic labels from each log entry.
+     * These are merged with static labels and used as Loki stream labels.
+     * Keep cardinality low — use only a few well-known values.
+     * @example (entry) => ({ level: entry.levelName, service: entry.context?.service })
+     */
+    dynamicLabels?: (entry: LogEntry) => Record<string, string | undefined>;
+    /**
+     * Include context, error, and correlationId in the Loki log payload.
+     * Default: true
+     */
+    includeMetadata?: boolean;
+    /** Transport level filter */
+    level?: LogLevelName;
+    /** Batch size (default: 10) */
+    batchSize?: number;
+    /** Batch interval ms (default: 5000) */
+    interval?: number;
+    /** Enable retry on push failure (default: false) */
+    retry?: boolean;
+    /** Maximum retries (default: 3) */
+    maxRetries?: number;
+}
+/**
+ * Pushes logs to Grafana Loki via HTTP API.
+ * Uses batching to improve performance.
+ */
+declare function lokiTransport(options: LokiTransportOptions): Transport;
+
+/**
+ * @module voltlog-io
+ * @description OpenTelemetry OTLP transport — sends logs via OTLP HTTP/JSON protocol.
+ * @server-only Uses `fetch()` to send logs to an OTLP-compatible collector.
+ *
+ * Compatible with: SigNoz, Jaeger, Grafana Alloy, OpenTelemetry Collector, and any OTLP endpoint.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, otelTraceMiddleware, otelTransport } from 'voltlog-io';
+ *
+ * // SigNoz Cloud
+ * const logger = createLogger({
+ *   middleware: [otelTraceMiddleware()],
+ *   transports: [
+ *     otelTransport({
+ *       endpoint: 'https://ingest.signoz.io',
+ *       headers: { 'signoz-access-token': 'YOUR_TOKEN' },
+ *       serviceName: 'my-app',
+ *     }),
+ *   ],
+ * });
+ *
+ * // Self-hosted OTel Collector
+ * const logger2 = createLogger({
+ *   transports: [
+ *     otelTransport({
+ *       endpoint: 'http://localhost:4318', // OTLP HTTP port
+ *       serviceName: 'volt-csms',
+ *       resource: {
+ *         'deployment.environment': 'production',
+ *         'service.version': '2.0.0',
+ *       },
+ *     }),
+ *   ],
+ * });
+ *
+ * logger.info('Request processed', { userId: 'u-42' });
+ * // → Sent to SigNoz with traceId, spanId, severity, resource attributes
+ * ```
+ */
+
+interface OtelTransportOptions {
+    /**
+     * OTLP HTTP endpoint (e.g. http://localhost:4318 or https://ingest.signoz.io).
+     * The `/v1/logs` path is appended automatically.
+     */
+    endpoint: string;
+    /** Service name reported to the collector */
+    serviceName: string;
+    /** Additional resource attributes (e.g. deployment.environment, service.version) */
+    resource?: Record<string, string>;
+    /** Extra headers (e.g. signoz-access-token, Authorization) */
+    headers?: Record<string, string>;
+    /** Transport level filter */
+    level?: LogLevelName;
+    /** Batch size before flush (default: 20) */
+    batchSize?: number;
+    /** Batch interval in ms (default: 5000) */
+    interval?: number;
+}
+/**
+ * Creates an OTLP HTTP/JSON transport for OpenTelemetry-compatible backends.
+ *
+ * Sends logs using the OTLP Logs protocol:
+ * https://opentelemetry.io/docs/specs/otlp/#otlphttp-request
+ */
+declare function otelTransport(options: OtelTransportOptions): 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;
+    /** Hide meta object in output (default: false) */
+    hideMeta?: boolean;
+    /** Pretty-print meta object with indentation (default: false) */
+    prettyMeta?: 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 Ring buffer transport — stores last N log entries in memory for on-demand retrieval.
+ * @universal Works in all environments.
+ *
+ * Useful for debugging, in-app log viewers, and diagnostic endpoints.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, ringBufferTransport } from 'voltlog-io';
+ *
+ * const ring = ringBufferTransport({ maxSize: 500 });
+ * const logger = createLogger({ transports: [ring] });
+ *
+ * logger.info('Hello');
+ * logger.error('Oops', new Error('fail'));
+ *
+ * // Retrieve buffered entries
+ * const entries = ring.getEntries();
+ * const errors = ring.getEntries({ level: 'ERROR' });
+ * ```
+ */
+
+interface RingBufferTransportOptions {
+    /** Maximum number of entries to keep (default: 1000) */
+    maxSize?: number;
+    /** Per-transport level filter */
+    level?: LogLevelName;
+}
+interface RingBufferQueryOptions {
+    /** Filter by minimum level */
+    level?: LogLevelName;
+    /** Return only entries after this timestamp */
+    since?: number;
+    /** Maximum entries to return (default: all) */
+    limit?: number;
+}
+interface RingBufferTransport extends Transport {
+    /** Retrieve buffered log entries with optional filtering */
+    getEntries(query?: RingBufferQueryOptions): LogEntry[];
+    /** Clear all buffered entries */
+    clear(): void;
+    /** Get current buffer size */
+    size: number;
+}
+/**
+ * Creates a ring buffer (circular buffer) transport.
+ * Stores the most recent `maxSize` entries in memory.
+ * Oldest entries are evicted when the buffer is full.
+ */
+declare function ringBufferTransport(options?: RingBufferTransportOptions): RingBufferTransport;
+
+/**
+ * @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 DatadogTransportOptions, type DeduplicationOptions, type DiscordTransportOptions, type HttpLoggerOptions, type HttpRequestMapper, type HttpResponseMapper, 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 OtelTraceMiddlewareOptions, type OtelTransportOptions, type PrettyTransportOptions, type RedactionOptions, type RingBufferQueryOptions, type RingBufferTransport, type RingBufferTransportOptions, type SamplingOptions, type SentryInstance, type SentryTransportOptions, type SlackTransportOptions, type TimerResult, type Transport, type UserAgentOptions, type WebhookTransportOptions, aiEnrichmentMiddleware, alertMiddleware, batchTransport, browserJsonStreamTransport, consoleTransport, createHttpLogger, createLogger, createMiddleware, createOpenAiErrorAnalyzer, createTransport, datadogTransport, deduplicationMiddleware, discordTransport, heapUsageMiddleware, ipMiddleware, levelOverrideMiddleware, lokiTransport, nodeHttpMappers, ocppMiddleware, otelTraceMiddleware, otelTransport, prettyTransport, redactionMiddleware, resolveLevel, ringBufferTransport, samplingMiddleware, sentryTransport, shouldIncludeStack, shouldLog, slackTransport, userAgentMiddleware, webhookTransport };