@rawnodes/logger 2.7.1 → 2.7.2

package/README.md

@@ -134,6 +134,19 @@ const logger = Logger.create({
 
 This is useful for sending only critical errors to alerting systems while keeping verbose logs in console.
 
+#### Level precedence
+
+When deciding whether to emit a log entry, the following order applies — **most specific wins**:
+
+1. **Global override** from `setLevelOverride(...)` or the top-level `level.rules` array
+2. **Per-transport rule** (a matching entry in `console.rules` / `file.rules` / etc.)
+3. **Per-transport level** (`console.level`, `file.level`, …)
+4. **Global default level** (`level` or `level.default`)
+
+Practically: a matching `setLevelOverride({ userId: 123 }, 'debug')` will surface debug logs to **every** transport, even one whose own `level` is set to `info`. This is intentional — dynamic overrides are for targeted troubleshooting, and they wouldn't be useful if a downstream transport could silently swallow the messages they just enabled.
+
+If you need a transport to stay narrow while overrides are active, use `rules` on that transport (level 2), not the plain `level` field.
+
 ### Per-Transport Rules
 
 Each transport can have its own filtering rules. Use `level: 'off'` with rules to create a whitelist pattern:
@@ -635,6 +648,43 @@ const masker = createMasker({
 
 **Default masked patterns:** `password`, `secret`, `token`, `apikey`, `api_key`, `api-key`, `auth`, `credential`, `private`
 
+## Error logging
+
+`error()` accepts an error value as the **first** argument. This keeps call sites short in the common case — you forward whatever `catch` produced without pre-normalizing it.
+
+```typescript
+try {
+  await doWork();
+} catch (err) {
+  // err: unknown — passes straight through, no cast needed
+  logger.error(err, 'doWork failed', { userId });
+}
+```
+
+Supported shapes:
+
+```typescript
+logger.error('something broke');                       // message only
+logger.error('something broke', { retries: 3 });       // message + meta
+logger.error(err);                                     // error only (uses err.message)
+logger.error(err, 'doWork failed');                    // error + message
+logger.error(err, { userId });                         // error + meta
+logger.error(err, 'doWork failed', { userId });        // error + message + meta
+```
+
+The first argument is interpreted as an error whenever it is **not a string**. That includes anything TypeScript's `catch` clause can produce (`Error`, plain objects, primitives, `null`, `undefined`). Non-`Error` values are normalized via `serializeError`:
+
+| Input                                 | Log fields extracted                                  |
+|---------------------------------------|-------------------------------------------------------|
+| `new Error('boom')`                   | `errorMessage`, `stack`, `errorName` (if not `Error`) |
+| `'string value'`                      | `errorMessage: 'string value'`                        |
+| axios error                           | `errorMessage`, `stack`, `http: { status, url, … }`   |
+| fetch-style `{ response, config }`    | Same, extracted heuristically                         |
+| `{ message: 'x', code: 'ECONN' }`     | `errorMessage`, `errorCode`                           |
+| `null` / `undefined`                  | `errorMessage: 'Unknown error'`                       |
+
+String-as-first-arg is always a message, never an error. If you want to log a string *as* an error, wrap it: `logger.error(new Error(str))`.
+
 ## Logfmt Utilities
 
 Helper functions for logfmt format:
@@ -661,7 +711,11 @@ class Logger<TContext> {
   getStore(): LoggerStore<TContext>;
 
   // Logging
-  error(message: string, error?: Error, meta?: Meta): void;
+  // error() accepts an error value as the first argument — including `unknown`
+  // (what `catch (err)` produces under TypeScript's strict mode). Non-Error
+  // values are normalized via `serializeError` so logs still get a sensible
+  // `errorMessage` / `stack` / HTTP payload. See "Error logging" below.
+  error(errorOrMessage: Error | string | unknown, messageOrMeta?: string | Meta, meta?: Meta): void;
   warn(message: string, meta?: Meta): void;
   info(message: string, meta?: Meta): void;
   http(message: string, meta?: Meta): void;

package/dist/index.d.mts

@@ -1,4 +1,3 @@
-import { EventEmitter } from 'events';
 import { z } from 'zod';
 
 declare const LOG_LEVELS: {
@@ -45,6 +44,47 @@ interface HttpTransportBaseConfig {
     flushInterval?: number;
     maxRetries?: number;
     retryDelay?: number;
+    /**
+     * Maximum number of messages the in-memory queue will hold before dropping.
+     * Provides a hard upper bound on memory usage when a transport is degraded
+     * or offline — without this, a failing transport + steady log volume grows
+     * the queue until OOM. Default: unbounded.
+     *
+     * Recommended for production: `10_000` — enough to absorb transient blips,
+     * small enough to avoid runaway memory.
+     */
+    maxQueueSize?: number;
+    /**
+     * Policy applied when the queue is full.
+     * - `'drop-oldest'` (default): prefers keeping recent events — during an
+     *   outage old logs are usually stale.
+     * - `'drop-newest'`: prefers preserving historical context — useful if you
+     *   care more about the events leading up to the outage than the noise
+     *   happening during it.
+     */
+    dropPolicy?: 'drop-oldest' | 'drop-newest';
+    /**
+     * Called when messages are dropped due to queue overflow. Receives only the
+     * messages that were discarded. If not provided, drops are silent.
+     *
+     * Callback MUST NOT throw; if it does, the exception is swallowed.
+     */
+    onDrop?: (droppedMessages: unknown[]) => void;
+    /**
+     * Called when a batch fails after all retries and messages are dropped.
+     * If not provided, the error is logged to stderr.
+     *
+     * The callback MUST NOT throw; if it does, the failure is swallowed and a
+     * stderr fallback is used. This is intentional — a logger must never
+     * propagate its own transport errors back into the host application.
+     */
+    onError?: (error: Error, droppedMessages: unknown[]) => void;
+    /**
+     * Timeout in milliseconds for a single outbound HTTP request. Default:
+     * `10_000`. Applies to Discord/Telegram `fetch`. CloudWatch uses the AWS
+     * SDK's own timeout configuration.
+     */
+    requestTimeout?: number;
 }
 interface DiscordConfig extends HttpTransportBaseConfig {
     webhookUrl: string;
@@ -73,6 +113,20 @@ interface LogStreamTemplateConfig {
     template: string;
 }
 type LogStreamName = string | LogStreamPatternConfig | LogStreamTemplateConfig;
+interface RelayConfig {
+    /** URL of the relay API (e.g., https://relay.example.com) */
+    apiUrl: string;
+    /** Authentication token for the relay server */
+    token: string;
+    /** Polling interval in ms (default: 30000) */
+    pollInterval?: number;
+    /** Ring buffer capacity - max logs held during reconnect (default: 1000) */
+    bufferSize?: number;
+    /** WebSocket reconnect base delay in ms (default: 1000) */
+    reconnectDelay?: number;
+    /** Max reconnect delay in ms (default: 30000) */
+    maxReconnectDelay?: number;
+}
 interface CloudWatchConfig extends HttpTransportBaseConfig {
     logGroupName: string;
     /** Log stream name - string, pattern config, or template config. Defaults to hostname pattern */
@@ -113,6 +167,8 @@ interface LoggerConfig {
     discord?: DiscordConfig | DiscordConfig[];
     telegram?: TelegramConfig | TelegramConfig[];
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[];
+    /** Relay transport config — streams logs to a remote server via WebSocket (runs in worker thread) */
+    relay?: RelayConfig;
     /** Enable caller info (file:line) in logs. Pass true for defaults or CallerConfig for options */
     caller?: boolean | CallerConfig;
     /** Hostname to include in all log entries. Defaults to os.hostname() if not specified */
@@ -140,7 +196,7 @@ declare class LoggerStore<TContext extends LoggerContext = LoggerContext> {
 declare class Logger<TContext extends LoggerContext = LoggerContext> {
     private state;
     private context;
-    private profileTimers;
+    private profileTimers?;
     private constructor();
     static create<TContext extends LoggerContext = LoggerContext>(config: LoggerConfig, store?: LoggerStore<TContext>): Logger<TContext>;
     for(context: string): Logger<TContext>;
@@ -152,10 +208,29 @@ declare class Logger<TContext extends LoggerContext = LoggerContext> {
     /**
      * Gracefully shutdown the logger, flushing all pending messages.
      * Should be called before process exit to ensure no logs are lost.
+     *
+     * `timeoutMs` is forwarded to each transport's `close()` as a per-transport
+     * cap; it prevents a dead transport from blocking the whole shutdown.
+     * Default: 5000ms. Pass `Infinity` for legacy unbounded behaviour.
      */
-    shutdown(): Promise<void>;
+    shutdown(timeoutMs?: number): Promise<void>;
     profile(id: string, meta?: object): void;
-    error(errorOrMessage: Error | string, messageOrMeta?: string | Meta, meta?: Meta): void;
+    /**
+     * Log an error. Supported shapes:
+     *   error(message: string)
+     *   error(message: string, meta)
+     *   error(error: Error | unknown)
+     *   error(error: Error | unknown, message: string)
+     *   error(error: Error | unknown, meta)
+     *   error(error: Error | unknown, message: string, meta)
+     *
+     * The first argument is treated as an error value whenever it is not a string.
+     * Non-Error values (plain objects, numbers, etc. — e.g. anything caught by
+     * TypeScript's `catch (err)` clause, which is typed as `unknown`) are passed
+     * through `serializeError` so they produce a sensible `errorMessage` and, when
+     * possible, a `stack` / HTTP diagnostic payload.
+     */
+    error(errorOrMessage: Error | string | unknown, messageOrMeta?: string | Meta, meta?: Meta): void;
     warn(message: string, meta?: Meta): void;
     info(message: string, meta?: Meta): void;
     http(message: string, meta?: Meta): void;
@@ -185,6 +260,7 @@ interface BufferedMessage {
     context?: string;
     meta?: Record<string, unknown>;
 }
+type DropPolicy = 'drop-oldest' | 'drop-newest';
 interface BufferOptions {
     batchSize: number;
     flushInterval: number;
@@ -192,6 +268,25 @@ interface BufferOptions {
     retryDelay: number;
     onFlush: (messages: BufferedMessage[]) => Promise<void>;
     onError?: (error: Error, messages: BufferedMessage[]) => void;
+    /**
+     * Maximum number of messages the queue will hold before dropping. When the
+     * queue is full, behaviour follows `dropPolicy`. Default: unbounded.
+     */
+    maxQueueSize?: number;
+    /**
+     * Policy applied when the queue is at `maxQueueSize` and a new message
+     * arrives. Default: `'drop-oldest'` — prefers keeping recent events, since
+     * during an outage the old ones are usually stale anyway.
+     */
+    dropPolicy?: DropPolicy;
+    /**
+     * Called when messages are dropped due to queue overflow. Receives the
+     * messages that were discarded (not the remaining queue). If not provided,
+     * the drop is silent — consumers can still track it via buffer metrics.
+     *
+     * Callback MUST NOT throw; if it does, the exception is swallowed.
+     */
+    onDrop?: (droppedMessages: BufferedMessage[]) => void;
 }
 declare class MessageBuffer {
     private options;
@@ -199,10 +294,24 @@ declare class MessageBuffer {
     private timer;
     private flushing;
     private closed;
+    private droppedCount;
     constructor(options: BufferOptions);
     add(message: BufferedMessage): void;
     flush(): Promise<void>;
-    close(): Promise<void>;
+    /**
+     * Stops accepting new messages and attempts to flush what's already buffered.
+     * Returns when the queue is drained OR when `timeoutMs` elapses. A timeout
+     * is essential during graceful shutdown — without it, a dead transport would
+     * block process exit indefinitely, and orchestrators like Kubernetes would
+     * escalate to SIGKILL after their grace period.
+     *
+     * Default timeout: 5 seconds. Pass `Infinity` to preserve legacy behaviour.
+     */
+    close(timeoutMs?: number): Promise<void>;
+    /** Current number of messages waiting in the queue. */
+    get size(): number;
+    /** Total number of messages dropped due to queue overflow since creation. */
+    get droppedTotal(): number;
     private scheduleFlush;
     private clearTimer;
     private sendWithRetry;
@@ -214,12 +323,35 @@ interface BaseHttpTransportOptions {
     flushInterval?: number;
     maxRetries?: number;
     retryDelay?: number;
+    maxQueueSize?: number;
+    dropPolicy?: DropPolicy;
+    onDrop?: (droppedMessages: BufferedMessage[]) => void;
+    /**
+     * Called when a batch fails after all retries and messages are dropped.
+     * If not provided, the error is logged to stderr.
+     *
+     * The callback MUST NOT throw; if it does, the failure is swallowed and a
+     * stderr fallback is used. A logger must never propagate transport errors
+     * back into the host application.
+     */
+    onError?: (error: Error, droppedMessages: BufferedMessage[]) => void;
 }
-declare abstract class BaseHttpTransport extends EventEmitter {
+declare abstract class BaseHttpTransport {
     protected buffer: MessageBuffer;
+    private onErrorCallback?;
     constructor(opts?: BaseHttpTransportOptions);
     log(info: Record<string, unknown>, callback: () => void): void;
-    close(): Promise<void>;
+    /**
+     * Stop accepting new messages and flush what's buffered. `timeoutMs` caps
+     * how long the flush may take; after that the remaining queue is discarded
+     * so shutdown can complete. Default 5000ms.
+     */
+    close(timeoutMs?: number): Promise<void>;
+    /** Current buffered message count and total drops since creation. */
+    getMetrics(): {
+        queueSize: number;
+        droppedTotal: number;
+    };
     protected transformMessage(info: Record<string, unknown>): BufferedMessage;
     protected handleError(error: Error, messages: BufferedMessage[]): void;
     protected abstract sendBatch(messages: BufferedMessage[]): Promise<void>;
@@ -231,6 +363,7 @@ declare function matchesContext(storeContext: LoggerContext | undefined, loggerC
 
 declare class DiscordTransport extends BaseHttpTransport {
     private config;
+    private requestTimeout;
     constructor(config: DiscordConfig);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private sendEmbedBatch;
@@ -246,6 +379,7 @@ declare class DiscordTransport extends BaseHttpTransport {
 declare class TelegramTransport extends BaseHttpTransport {
     private config;
     private apiUrl;
+    private requestTimeout;
     constructor(config: TelegramConfig);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private formatBatchMessage;
@@ -412,6 +546,7 @@ declare const LoggerConfigSchema: z.ZodObject<{
     discord: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>, z.ZodArray<z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>>]>>;
     telegram: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>, z.ZodArray<z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>>]>>;
     cloudwatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>, z.ZodArray<z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>>]>>;
+    relay: z.ZodOptional<z.ZodType<RelayConfig, unknown, z.core.$ZodTypeInternals<RelayConfig, unknown>>>;
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
     autoShutdown: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<AutoShutdownConfig, unknown, z.core.$ZodTypeInternals<AutoShutdownConfig, unknown>>]>>;
@@ -424,6 +559,7 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     discord?: DiscordConfig | DiscordConfig[] | undefined;
     telegram?: TelegramConfig | TelegramConfig[] | undefined;
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[] | undefined;
+    relay?: RelayConfig | undefined;
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
     autoShutdown?: boolean | AutoShutdownConfig | undefined;

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import { EventEmitter } from 'events';
 import { z } from 'zod';
 
 declare const LOG_LEVELS: {
@@ -45,6 +44,47 @@ interface HttpTransportBaseConfig {
     flushInterval?: number;
     maxRetries?: number;
     retryDelay?: number;
+    /**
+     * Maximum number of messages the in-memory queue will hold before dropping.
+     * Provides a hard upper bound on memory usage when a transport is degraded
+     * or offline — without this, a failing transport + steady log volume grows
+     * the queue until OOM. Default: unbounded.
+     *
+     * Recommended for production: `10_000` — enough to absorb transient blips,
+     * small enough to avoid runaway memory.
+     */
+    maxQueueSize?: number;
+    /**
+     * Policy applied when the queue is full.
+     * - `'drop-oldest'` (default): prefers keeping recent events — during an
+     *   outage old logs are usually stale.
+     * - `'drop-newest'`: prefers preserving historical context — useful if you
+     *   care more about the events leading up to the outage than the noise
+     *   happening during it.
+     */
+    dropPolicy?: 'drop-oldest' | 'drop-newest';
+    /**
+     * Called when messages are dropped due to queue overflow. Receives only the
+     * messages that were discarded. If not provided, drops are silent.
+     *
+     * Callback MUST NOT throw; if it does, the exception is swallowed.
+     */
+    onDrop?: (droppedMessages: unknown[]) => void;
+    /**
+     * Called when a batch fails after all retries and messages are dropped.
+     * If not provided, the error is logged to stderr.
+     *
+     * The callback MUST NOT throw; if it does, the failure is swallowed and a
+     * stderr fallback is used. This is intentional — a logger must never
+     * propagate its own transport errors back into the host application.
+     */
+    onError?: (error: Error, droppedMessages: unknown[]) => void;
+    /**
+     * Timeout in milliseconds for a single outbound HTTP request. Default:
+     * `10_000`. Applies to Discord/Telegram `fetch`. CloudWatch uses the AWS
+     * SDK's own timeout configuration.
+     */
+    requestTimeout?: number;
 }
 interface DiscordConfig extends HttpTransportBaseConfig {
     webhookUrl: string;
@@ -73,6 +113,20 @@ interface LogStreamTemplateConfig {
     template: string;
 }
 type LogStreamName = string | LogStreamPatternConfig | LogStreamTemplateConfig;
+interface RelayConfig {
+    /** URL of the relay API (e.g., https://relay.example.com) */
+    apiUrl: string;
+    /** Authentication token for the relay server */
+    token: string;
+    /** Polling interval in ms (default: 30000) */
+    pollInterval?: number;
+    /** Ring buffer capacity - max logs held during reconnect (default: 1000) */
+    bufferSize?: number;
+    /** WebSocket reconnect base delay in ms (default: 1000) */
+    reconnectDelay?: number;
+    /** Max reconnect delay in ms (default: 30000) */
+    maxReconnectDelay?: number;
+}
 interface CloudWatchConfig extends HttpTransportBaseConfig {
     logGroupName: string;
     /** Log stream name - string, pattern config, or template config. Defaults to hostname pattern */
@@ -113,6 +167,8 @@ interface LoggerConfig {
     discord?: DiscordConfig | DiscordConfig[];
     telegram?: TelegramConfig | TelegramConfig[];
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[];
+    /** Relay transport config — streams logs to a remote server via WebSocket (runs in worker thread) */
+    relay?: RelayConfig;
     /** Enable caller info (file:line) in logs. Pass true for defaults or CallerConfig for options */
     caller?: boolean | CallerConfig;
     /** Hostname to include in all log entries. Defaults to os.hostname() if not specified */
@@ -140,7 +196,7 @@ declare class LoggerStore<TContext extends LoggerContext = LoggerContext> {
 declare class Logger<TContext extends LoggerContext = LoggerContext> {
     private state;
     private context;
-    private profileTimers;
+    private profileTimers?;
     private constructor();
     static create<TContext extends LoggerContext = LoggerContext>(config: LoggerConfig, store?: LoggerStore<TContext>): Logger<TContext>;
     for(context: string): Logger<TContext>;
@@ -152,10 +208,29 @@ declare class Logger<TContext extends LoggerContext = LoggerContext> {
     /**
      * Gracefully shutdown the logger, flushing all pending messages.
      * Should be called before process exit to ensure no logs are lost.
+     *
+     * `timeoutMs` is forwarded to each transport's `close()` as a per-transport
+     * cap; it prevents a dead transport from blocking the whole shutdown.
+     * Default: 5000ms. Pass `Infinity` for legacy unbounded behaviour.
      */
-    shutdown(): Promise<void>;
+    shutdown(timeoutMs?: number): Promise<void>;
     profile(id: string, meta?: object): void;
-    error(errorOrMessage: Error | string, messageOrMeta?: string | Meta, meta?: Meta): void;
+    /**
+     * Log an error. Supported shapes:
+     *   error(message: string)
+     *   error(message: string, meta)
+     *   error(error: Error | unknown)
+     *   error(error: Error | unknown, message: string)
+     *   error(error: Error | unknown, meta)
+     *   error(error: Error | unknown, message: string, meta)
+     *
+     * The first argument is treated as an error value whenever it is not a string.
+     * Non-Error values (plain objects, numbers, etc. — e.g. anything caught by
+     * TypeScript's `catch (err)` clause, which is typed as `unknown`) are passed
+     * through `serializeError` so they produce a sensible `errorMessage` and, when
+     * possible, a `stack` / HTTP diagnostic payload.
+     */
+    error(errorOrMessage: Error | string | unknown, messageOrMeta?: string | Meta, meta?: Meta): void;
     warn(message: string, meta?: Meta): void;
     info(message: string, meta?: Meta): void;
     http(message: string, meta?: Meta): void;
@@ -185,6 +260,7 @@ interface BufferedMessage {
     context?: string;
     meta?: Record<string, unknown>;
 }
+type DropPolicy = 'drop-oldest' | 'drop-newest';
 interface BufferOptions {
     batchSize: number;
     flushInterval: number;
@@ -192,6 +268,25 @@ interface BufferOptions {
     retryDelay: number;
     onFlush: (messages: BufferedMessage[]) => Promise<void>;
     onError?: (error: Error, messages: BufferedMessage[]) => void;
+    /**
+     * Maximum number of messages the queue will hold before dropping. When the
+     * queue is full, behaviour follows `dropPolicy`. Default: unbounded.
+     */
+    maxQueueSize?: number;
+    /**
+     * Policy applied when the queue is at `maxQueueSize` and a new message
+     * arrives. Default: `'drop-oldest'` — prefers keeping recent events, since
+     * during an outage the old ones are usually stale anyway.
+     */
+    dropPolicy?: DropPolicy;
+    /**
+     * Called when messages are dropped due to queue overflow. Receives the
+     * messages that were discarded (not the remaining queue). If not provided,
+     * the drop is silent — consumers can still track it via buffer metrics.
+     *
+     * Callback MUST NOT throw; if it does, the exception is swallowed.
+     */
+    onDrop?: (droppedMessages: BufferedMessage[]) => void;
 }
 declare class MessageBuffer {
     private options;
@@ -199,10 +294,24 @@ declare class MessageBuffer {
     private timer;
     private flushing;
     private closed;
+    private droppedCount;
     constructor(options: BufferOptions);
     add(message: BufferedMessage): void;
     flush(): Promise<void>;
-    close(): Promise<void>;
+    /**
+     * Stops accepting new messages and attempts to flush what's already buffered.
+     * Returns when the queue is drained OR when `timeoutMs` elapses. A timeout
+     * is essential during graceful shutdown — without it, a dead transport would
+     * block process exit indefinitely, and orchestrators like Kubernetes would
+     * escalate to SIGKILL after their grace period.
+     *
+     * Default timeout: 5 seconds. Pass `Infinity` to preserve legacy behaviour.
+     */
+    close(timeoutMs?: number): Promise<void>;
+    /** Current number of messages waiting in the queue. */
+    get size(): number;
+    /** Total number of messages dropped due to queue overflow since creation. */
+    get droppedTotal(): number;
     private scheduleFlush;
     private clearTimer;
     private sendWithRetry;
@@ -214,12 +323,35 @@ interface BaseHttpTransportOptions {
     flushInterval?: number;
     maxRetries?: number;
     retryDelay?: number;
+    maxQueueSize?: number;
+    dropPolicy?: DropPolicy;
+    onDrop?: (droppedMessages: BufferedMessage[]) => void;
+    /**
+     * Called when a batch fails after all retries and messages are dropped.
+     * If not provided, the error is logged to stderr.
+     *
+     * The callback MUST NOT throw; if it does, the failure is swallowed and a
+     * stderr fallback is used. A logger must never propagate transport errors
+     * back into the host application.
+     */
+    onError?: (error: Error, droppedMessages: BufferedMessage[]) => void;
 }
-declare abstract class BaseHttpTransport extends EventEmitter {
+declare abstract class BaseHttpTransport {
     protected buffer: MessageBuffer;
+    private onErrorCallback?;
     constructor(opts?: BaseHttpTransportOptions);
     log(info: Record<string, unknown>, callback: () => void): void;
-    close(): Promise<void>;
+    /**
+     * Stop accepting new messages and flush what's buffered. `timeoutMs` caps
+     * how long the flush may take; after that the remaining queue is discarded
+     * so shutdown can complete. Default 5000ms.
+     */
+    close(timeoutMs?: number): Promise<void>;
+    /** Current buffered message count and total drops since creation. */
+    getMetrics(): {
+        queueSize: number;
+        droppedTotal: number;
+    };
     protected transformMessage(info: Record<string, unknown>): BufferedMessage;
     protected handleError(error: Error, messages: BufferedMessage[]): void;
     protected abstract sendBatch(messages: BufferedMessage[]): Promise<void>;
@@ -231,6 +363,7 @@ declare function matchesContext(storeContext: LoggerContext | undefined, loggerC
 
 declare class DiscordTransport extends BaseHttpTransport {
     private config;
+    private requestTimeout;
     constructor(config: DiscordConfig);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private sendEmbedBatch;
@@ -246,6 +379,7 @@ declare class DiscordTransport extends BaseHttpTransport {
 declare class TelegramTransport extends BaseHttpTransport {
     private config;
     private apiUrl;
+    private requestTimeout;
     constructor(config: TelegramConfig);
     protected sendBatch(messages: BufferedMessage[]): Promise<void>;
     private formatBatchMessage;
@@ -412,6 +546,7 @@ declare const LoggerConfigSchema: z.ZodObject<{
     discord: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>, z.ZodArray<z.ZodType<DiscordConfig, unknown, z.core.$ZodTypeInternals<DiscordConfig, unknown>>>]>>;
     telegram: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>, z.ZodArray<z.ZodType<TelegramConfig, unknown, z.core.$ZodTypeInternals<TelegramConfig, unknown>>>]>>;
     cloudwatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>, z.ZodArray<z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>>]>>;
+    relay: z.ZodOptional<z.ZodType<RelayConfig, unknown, z.core.$ZodTypeInternals<RelayConfig, unknown>>>;
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
     autoShutdown: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<AutoShutdownConfig, unknown, z.core.$ZodTypeInternals<AutoShutdownConfig, unknown>>]>>;
@@ -424,6 +559,7 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     discord?: DiscordConfig | DiscordConfig[] | undefined;
     telegram?: TelegramConfig | TelegramConfig[] | undefined;
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[] | undefined;
+    relay?: RelayConfig | undefined;
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
     autoShutdown?: boolean | AutoShutdownConfig | undefined;