logquill 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -54,6 +54,21 @@ interface Plugin {
     /** Called when one of this plugin's own hooks throws. */
     onError?(error: unknown, record: LogRecord): void;
 }
+/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
+type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+/**
+ * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
+ * builds one of these automatically when given a function instead of a
+ * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
+ * read the `Plugin` interface first. There's no `next()` chaining: the
+ * pipeline already calls hooks in sequence, so this is sugar for a
+ * single-method `Plugin`, not a new execution model.
+ */
+declare class FunctionPlugin implements Plugin {
+    private readonly func;
+    constructor(func: MiddlewareFunc);
+    beforeLog(record: LogRecord): LogRecord | null;
+}
 
 /**
  * Injects fixed key/value pairs into every record's `meta`.
@@ -78,15 +93,44 @@ declare class RedactPlugin implements Plugin {
     beforeLog(record: LogRecord): LogRecord;
 }
 
-interface SamplingPluginOptions {
-    rng?: () => number;
+/**
+ * Syntactic (not semantic) patterns — matched on shape, so both false
+ * positives (a random 9-digit number) and false negatives (anything that
+ * doesn't look like these shapes) are expected. Override via `patterns`
+ * for anything stricter.
+ */
+declare const DEFAULT_PII_PATTERNS: Readonly<Record<string, RegExp>>;
+interface PIIRedactPluginOptions {
+    patterns?: Readonly<Record<string, RegExp>>;
+    replacement?: string;
 }
-/** Keeps roughly `rate` of records (0.0-1.0), dropping the rest. */
-declare class SamplingPlugin implements Plugin {
-    readonly rate: number;
-    private readonly rng;
-    constructor(rate: number, options?: SamplingPluginOptions);
-    beforeLog(record: LogRecord): LogRecord | null;
+/**
+ * Regex-based PII redaction over `meta` **values**, not just keys.
+ *
+ * Complements `RedactPlugin`, which redacts by exact key match —
+ * `PIIRedactPlugin` scans string values (recursively through nested
+ * objects/arrays) for emails, SSNs, credit-card numbers, and phone
+ * numbers, and redacts matches wherever they appear, regardless of which
+ * key holds them (a `notes` field containing a stray SSN is still caught).
+ *
+ * Detection is pattern-based: fast and dependency-free, but it matches on
+ * syntactic shape, not meaning — a random 9-digit number can false-positive
+ * as an SSN, and anything that doesn't fit these shapes (a name, a street
+ * address) is a false negative. Pass your own `patterns` to extend or
+ * replace the defaults.
+ *
+ * Recursion into nested `meta` structures is depth- and cycle-bounded, so a
+ * circular reference or a pathologically deep structure can't hang or
+ * crash the caller — it's left unredacted past the bound rather than
+ * throwing.
+ */
+declare class PIIRedactPlugin implements Plugin {
+    readonly patterns: Readonly<Record<string, RegExp>>;
+    readonly replacement: string;
+    constructor(options?: PIIRedactPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+    private redactValue;
+    private redactText;
 }
 
 /**
@@ -110,6 +154,1022 @@ declare class CollectingTransport extends Transport {
     close(): void;
 }
 
+interface SamplingPluginOptions {
+    rng?: () => number;
+    /** `meta` key holding the trace/run id used to group buffered records. Default `"traceId"`. */
+    traceKey?: string;
+    /** A record at or above this level elevates its whole trace. Default `Level.ERROR`. */
+    elevateAt?: LevelInput;
+    /** Enables tail-based elevation, writing straight to these transports on elevation. Omit to disable and get plain rate-based sampling. */
+    transports?: Transport[];
+    /** Total buffered records allowed across every trace before the oldest trace is evicted. Default 1000. */
+    maxBufferedRecords?: number;
+    /** Distinct trace ids held at once before the oldest is evicted. Default 200. */
+    maxTraces?: number;
+}
+/**
+ * Keeps roughly `rate` of records (0.0-1.0), dropping the rest.
+ *
+ * With `transports` set, sampling becomes tail-based per trace: a record
+ * that would otherwise be dropped is buffered under its `meta[traceKey]`
+ * value instead of discarded outright. If any later record sharing that
+ * trace id reaches `elevateAt` or above, the whole trace is "elevated" —
+ * every buffered record for that trace id is flushed straight to
+ * `transports`, and every subsequent record for that trace id ships
+ * unconditionally. This is what lets a sampled-out request still produce a
+ * complete trace once it turns out to matter (it errored).
+ *
+ * Flushing writes buffered records directly to `transports` — pass the
+ * same array given to the `Logger`. This bypasses `beforeLog`/`afterLog`/
+ * `onError` for any plugin *after* `SamplingPlugin` in the pipeline (the
+ * plugins before it already ran, since that's how the buffered record was
+ * built); put `SamplingPlugin` last if that matters for your pipeline.
+ *
+ * Without `transports`, tail-based elevation is inactive and this behaves
+ * exactly like plain rate-based sampling (the original behavior) — a
+ * record without `meta[traceKey]` is also just rate-sampled, since there's
+ * no trace to buffer it under.
+ *
+ * Buffering is bounded: at most `maxBufferedRecords` records total and
+ * `maxTraces` distinct trace ids are held at once. Once either limit is
+ * hit, the oldest buffered trace is evicted (and its records are lost, not
+ * flushed) — a deliberate bounded-memory trade-off, not a bug: an
+ * unbounded per-trace buffer would let a single pathologically long-lived
+ * or high-cardinality trace grow memory without limit.
+ */
+declare class SamplingPlugin implements Plugin {
+    readonly rate: number;
+    readonly traceKey: string;
+    readonly elevateAt: Level;
+    readonly transports: Transport[] | undefined;
+    readonly maxBufferedRecords: number;
+    readonly maxTraces: number;
+    private readonly rng;
+    private readonly buffer;
+    private bufferedCount;
+    private readonly elevated;
+    constructor(rate: number, options?: SamplingPluginOptions);
+    beforeLog(record: LogRecord): LogRecord | null;
+    private elevate;
+    private bufferRecord;
+    private evictOldestTrace;
+}
+
+declare const GENESIS_HASH: string;
+interface TamperEvidentPluginOptions {
+    genesisHash?: string;
+}
+/**
+ * Hash-chains every record so tampering with a written log can be
+ * detected after the fact.
+ *
+ * Each record gets `meta.hash` — a SHA-256 hex digest over the record's
+ * own content plus the previous record's hash (`meta.prevHash`) — the same
+ * hash-chain construction used by tamper-evident/append-only logs: editing
+ * or deleting any one line breaks every hash after it in the chain, even
+ * if the tamperer edits the file directly and not through this plugin.
+ * Opt-in — hashing every record has a real, measurable CPU cost, so it
+ * isn't part of the default pipeline.
+ *
+ * Verify a previously-written log with `TamperEvidentPlugin.verifyChain`,
+ * which re-derives each record's hash from its content and confirms it
+ * matches both the stored `meta.hash` and the chain built from the records
+ * before it, in order.
+ */
+declare class TamperEvidentPlugin implements Plugin {
+    private readonly genesisHash;
+    private lastHash;
+    constructor(options?: TamperEvidentPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+    /**
+     * Returns `true` iff every record's hash matches its content plus the
+     * previous record's hash, in the given order. Returns `false` at the
+     * first break in the chain (an edited, removed, or reordered record).
+     */
+    static verifyChain(records: Iterable<Pick<LogRecord, "timestamp" | "level" | "logger" | "message" | "meta">>, options?: TamperEvidentPluginOptions): boolean;
+}
+
+interface AlertingPluginOptions {
+    /** A record at or above this level fires an alert. Default `Level.ERROR`. */
+    threshold?: LevelInput;
+    /** How long a dedupe window stays open before a collapsed follow-up alert (if any) fires. Default 300_000 (5 minutes). */
+    dedupeWindowMs?: number;
+    /** Groups records into the same dedupe window. Default: `level:logger:message`. */
+    dedupeKey?: (record: LogRecord) => string;
+    /** Distinct concurrent dedupe keys tracked at once; beyond this, new keys are dropped rather than tracked. Default 500. */
+    maxTrackedKeys?: number;
+}
+/**
+ * Base class for plugins that fire an external alert on ERROR/FATAL (or any
+ * configurable `threshold`).
+ *
+ * A concrete subclass implements only `sendAlert(record, occurrences)` —
+ * everything else (thresholding, deduplication, never blocking the caller,
+ * never letting a broken destination crash logging) lives here.
+ *
+ * The first record at or above `threshold` for a given dedupe key (by
+ * default: level + logger + message) fires `sendAlert` right away, without
+ * awaiting it — so the log call that triggered it is never blocked on a
+ * webhook, SMTP handshake, or any other I/O, even if the destination is
+ * slow or unreachable. This stands in for the shared async dispatch queue
+ * a later phase will introduce; once that queue exists, `AlertingPlugin`
+ * can route through it instead of firing its own unawaited call per alert.
+ *
+ * Any further record matching the same dedupe key within
+ * `dedupeWindowMs` of the first is *not* sent again — it just increments a
+ * counter. When the window closes, if more than one record matched,
+ * exactly one follow-up alert is sent with the total occurrence count,
+ * instead of spamming the destination once per record. Tracking is bounded
+ * to `maxTrackedKeys` distinct concurrent dedupe keys; beyond that, new
+ * keys are dropped rather than tracked (alerting degrades under extreme
+ * cardinality, logging itself never does).
+ *
+ * `sendAlert` is always called without being awaited, and any rejection is
+ * routed to this plugin's own `onError`, the same as any other plugin hook
+ * that throws.
+ */
+declare abstract class AlertingPlugin implements Plugin {
+    readonly threshold: Level;
+    readonly dedupeWindowMs: number;
+    readonly maxTrackedKeys: number;
+    private readonly dedupeKeyFn;
+    private readonly windows;
+    constructor(options?: AlertingPluginOptions);
+    afterLog(record: LogRecord): void;
+    private flush;
+    private safeSend;
+    /**
+     * Send one alert for `record`, representing `occurrences` collapsed
+     * duplicates (1 on first occurrence; the deduped total on a follow-up
+     * flush). Override in a concrete subclass — never call this directly,
+     * `AlertingPlugin` calls it without awaiting it.
+     */
+    protected abstract sendAlert(record: LogRecord, occurrences: number): void | Promise<void>;
+    onError?(error: unknown, record: LogRecord): void;
+    /** Cancel any pending dedupe-window timers. Call on logger shutdown. */
+    close(): void;
+}
+
+/** Posts one alert body to a Slack incoming webhook URL. Swap in a fake for tests. */
+type SlackSender = (webhookUrl: string, body: string) => Promise<void> | void;
+interface SlackAlertPluginOptions extends AlertingPluginOptions {
+    sender?: SlackSender;
+}
+/**
+ * Sends deduplicated `AlertingPlugin` alerts to a Slack incoming webhook.
+ *
+ * `webhookUrl` is the full "Incoming Webhook" URL from Slack's app config.
+ * Uses `fetch` — no extra dependency required. Pass `sender` to swap in a
+ * fake for tests or an alternate backend.
+ */
+declare class SlackAlertPlugin extends AlertingPlugin {
+    readonly webhookUrl: string;
+    private readonly sender;
+    constructor(webhookUrl: string, options?: SlackAlertPluginOptions);
+    protected sendAlert(record: LogRecord, occurrences: number): Promise<void>;
+}
+
+/** POSTs one PagerDuty Events API v2 payload. Swap in a fake for tests. */
+type PagerDutySender = (body: string) => Promise<void> | void;
+interface PagerDutyAlertPluginOptions extends AlertingPluginOptions {
+    sender?: PagerDutySender;
+}
+/**
+ * Sends deduplicated `AlertingPlugin` alerts to PagerDuty via the Events
+ * API v2 (`POST https://events.pagerduty.com/v2/enqueue`).
+ *
+ * `routingKey` is an Events API v2 integration key from a PagerDuty
+ * service. Uses `fetch` — no extra dependency required. Pass `sender` to
+ * swap in a fake for tests or an alternate backend.
+ */
+declare class PagerDutyAlertPlugin extends AlertingPlugin {
+    readonly routingKey: string;
+    private readonly sender;
+    constructor(routingKey: string, options?: PagerDutyAlertPluginOptions);
+    protected sendAlert(record: LogRecord, occurrences: number): Promise<void>;
+}
+
+interface EmailMessage {
+    from: string;
+    to: string[];
+    subject: string;
+    text: string;
+}
+/** Sends one email message. Swap in a fake for tests. */
+type EmailSender = (message: EmailMessage) => Promise<void> | void;
+/** The subset of a `nodemailer` transporter that `EmailAlertPlugin` needs. */
+interface NodemailerTransporterLike {
+    sendMail(message: {
+        from: string;
+        to: string;
+        subject: string;
+        text: string;
+    }): Promise<unknown>;
+}
+interface EmailAlertPluginOptions extends AlertingPluginOptions {
+    smtpHost: string;
+    smtpPort: number;
+    fromAddr: string;
+    toAddrs: string[];
+    username?: string;
+    password?: string;
+    /** `false` for an SMTP server that doesn't support STARTTLS (e.g. a local relay). Default `true`. */
+    useTls?: boolean;
+    /** Pre-built sender, e.g. for tests. Skips the `nodemailer` auto-import entirely. */
+    sender?: EmailSender;
+}
+/**
+ * Sends deduplicated `AlertingPlugin` alerts by email over SMTP.
+ *
+ * `nodemailer` is an optional peer dependency: install it yourself, or
+ * pass `sender` to swap in a fake for tests or an alternate backend —
+ * `username`/`password` are only used if both are set.
+ */
+declare class EmailAlertPlugin extends AlertingPlugin {
+    readonly smtpHost: string;
+    readonly smtpPort: number;
+    readonly fromAddr: string;
+    readonly toAddrs: string[];
+    private readonly username;
+    private readonly password;
+    private readonly useTls;
+    private readonly injectedSender;
+    private transporter;
+    constructor(options: EmailAlertPluginOptions);
+    protected sendAlert(record: LogRecord, occurrences: number): Promise<void>;
+    private importTransporter;
+}
+
+interface BatchingTransportOptions {
+    formatter?: Formatter;
+    /** Flush once the buffer holds this many items. Default 100. */
+    maxRecords?: number;
+    /** Flush once the buffer's estimated byte size reaches this many bytes. Default 1_000_000 (1MB). */
+    maxBytes?: number;
+}
+/**
+ * Shared base for every batching sink transport (SQL, NoSQL, message queues,
+ * batching cloud-native transports). Buffers items and flushes once either
+ * `maxRecords` or `maxBytes` is reached, so no batching transport can grow
+ * its buffer unboundedly under a sustained burst.
+ *
+ * `write()`/`close()` stay non-blocking from the caller's perspective: a
+ * failed `sendBatch()` is reported via `console.error` rather than thrown,
+ * matching `HTTPTransport`'s contract.
+ */
+declare abstract class BatchingTransport<T = LogRecord> extends Transport {
+    readonly maxRecords: number;
+    readonly maxBytes: number;
+    private buffer;
+    private bufferBytes;
+    constructor(options?: BatchingTransportOptions);
+    /** Converts a written record into the buffered item type. Defaults to the record itself. */
+    protected toItem(formatted: string, record: LogRecord): T;
+    /** Estimated byte size of one buffered item, used for the `maxBytes` bound. */
+    protected sizeOf(item: T): number;
+    write(formatted: string, record: LogRecord): void;
+    /** Send the current batch now, even if it hasn't reached a bound. */
+    flush(): void;
+    close(): void;
+    /** Deliver one batch to the backend. Always called with a non-empty batch. */
+    protected abstract sendBatch(batch: readonly T[]): Promise<void> | void;
+}
+
+/** One row of the fixed `logs` table schema shared across every SQL transport. */
+interface SQLLogRow {
+    timestamp: string;
+    level: string;
+    logger: string;
+    message: string;
+    /** `record.meta`, JSON-serialized — every SQL dialect can store this as TEXT/JSON/JSONB. */
+    meta: string;
+    runId: string | null;
+    spanId: string | null;
+    parentSpanId: string | null;
+    traceId: string | null;
+}
+interface BaseSQLTransportOptions extends BatchingTransportOptions {
+    /** Table to write into. Default `"logs"`. */
+    tableName?: string;
+    /**
+     * Dev/test convenience only: run `createTableSQL()` before the first insert.
+     * Production schema/migrations are the caller's responsibility — never
+     * auto-create schema unless this is explicitly set. Default `false`.
+     */
+    ensureSchema?: boolean;
+}
+/**
+ * Abstract base for every SQL transport (`SQLiteTransport`, `PostgresTransport`,
+ * `MySQLTransport`, ...). Owns the fixed schema and the record → row mapping;
+ * each driver-specific subclass only implements `ensureTable()`/`insertRows()`.
+ * Inserts are always batched — never one query per log call.
+ */
+declare abstract class BaseSQLTransport extends BatchingTransport<SQLLogRow> {
+    readonly tableName: string;
+    readonly ensureSchema: boolean;
+    private schemaEnsured;
+    constructor(options?: BaseSQLTransportOptions);
+    protected toItem(_formatted: string, record: LogRecord): SQLLogRow;
+    protected sizeOf(row: SQLLogRow): number;
+    /**
+     * Minimal, dialect-generic `CREATE TABLE IF NOT EXISTS` for dev/test use via
+     * `ensureSchema: true`. Production deployments should manage this table with
+     * a real migration instead — override in a subclass for dialect-correct
+     * column types (e.g. `JSONB` on Postgres).
+     */
+    createTableSQL(): string;
+    protected sendBatch(rows: readonly SQLLogRow[]): Promise<void>;
+    /** Only invoked when `ensureSchema: true` was explicitly passed. */
+    protected abstract ensureTable(): Promise<void>;
+    /** Always-batched insert of every row in `rows` — never one query per row. */
+    protected abstract insertRows(rows: readonly SQLLogRow[]): Promise<void>;
+}
+
+/** The subset of a `better-sqlite3` prepared statement that `SQLiteTransport` needs. */
+interface SQLiteStatementLike {
+    run(...params: unknown[]): unknown;
+}
+/** The subset of a `better-sqlite3` `Database` that `SQLiteTransport` needs. Inject a fake in tests. */
+interface SQLiteClientLike {
+    exec(sql: string): unknown;
+    prepare(sql: string): SQLiteStatementLike;
+    transaction<Args extends unknown[]>(fn: (...args: Args) => void): (...args: Args) => void;
+}
+interface SQLiteTransportOptions extends BaseSQLTransportOptions {
+    /** Pre-built client, e.g. for tests. Skips the `better-sqlite3` auto-import entirely. */
+    client?: SQLiteClientLike;
+    /** Passed to `better-sqlite3` when no `client` is injected. Default `":memory:"`. */
+    filename?: string;
+}
+/**
+ * Zero-setup SQL sink — no server process, just a local (or in-memory) file
+ * via `better-sqlite3`. Useful for local dev and pairs with the CLI trace
+ * viewer (v2.0), which can read this file directly.
+ *
+ * `better-sqlite3` is an optional peer dependency: install it yourself, or
+ * inject a `client` (e.g. a fake, or an already-open `Database` instance).
+ */
+declare class SQLiteTransport extends BaseSQLTransport {
+    private readonly injectedClient;
+    private readonly filename;
+    private client;
+    constructor(options?: SQLiteTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    protected ensureTable(): Promise<void>;
+    protected insertRows(rows: readonly SQLLogRow[]): Promise<void>;
+}
+
+/** The subset of a `pg` `Pool`/`Client` that `PostgresTransport` needs. Inject a fake in tests. */
+interface PgClientLike {
+    query(text: string, values: unknown[]): Promise<unknown>;
+}
+interface PostgresTransportOptions extends BaseSQLTransportOptions {
+    /** Pre-built client/pool, e.g. for tests, or an already-open `pg.Pool`/`pg.Client`. Skips the `pg` auto-import entirely. */
+    client?: PgClientLike;
+    /** Passed to `pg.Pool` when no `client` is injected, e.g. `"postgres://user:pass@host:5432/db"`. */
+    connectionString?: string;
+    /** Passed to `pg.Pool` when no `client` is injected and `connectionString` isn't used. */
+    connectionConfig?: Record<string, unknown>;
+}
+/**
+ * SQL sink backed by Postgres via `pg`. Builds one parameterized multi-row
+ * `INSERT` per batch — never one query per log call — matching the
+ * always-batched contract every `BaseSQLTransport` subclass shares.
+ *
+ * `pg` is an optional peer dependency: install it yourself, or inject a
+ * `client` (e.g. a fake, or an already-open `Pool`/`Client` instance).
+ */
+declare class PostgresTransport extends BaseSQLTransport {
+    private readonly injectedClient;
+    private readonly connectionString;
+    private readonly connectionConfig;
+    private client;
+    constructor(options?: PostgresTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    /** Postgres-correct `CREATE TABLE IF NOT EXISTS`: `SERIAL` primary key, `JSONB` for `meta`. */
+    createTableSQL(): string;
+    protected ensureTable(): Promise<void>;
+    protected insertRows(rows: readonly SQLLogRow[]): Promise<void>;
+}
+
+/** The subset of a `mysql2/promise` connection/pool that `MySQLTransport` needs. Inject a fake in tests. */
+interface MySQLClientLike {
+    execute(sql: string, values: unknown[]): Promise<unknown>;
+}
+interface MySQLTransportOptions extends BaseSQLTransportOptions {
+    /** Pre-built client/pool, e.g. for tests, or an already-open `mysql2/promise` `Pool`/`Connection`. Skips the `mysql2` auto-import entirely. */
+    client?: MySQLClientLike;
+    /** Passed to `mysql2/promise`'s `createPool` when no `client` is injected, e.g. `"mysql://user:pass@host:3306/db"`. */
+    connectionString?: string;
+    /** Passed to `mysql2/promise`'s `createPool` when no `client` is injected and `connectionString` isn't used. */
+    connectionConfig?: Record<string, unknown>;
+}
+/**
+ * SQL sink backed by MySQL via `mysql2`. Builds one parameterized multi-row
+ * `INSERT` per batch — never one query per log call — matching the
+ * always-batched contract every `BaseSQLTransport` subclass shares.
+ *
+ * `mysql2` is an optional peer dependency: install it yourself, or inject a
+ * `client` (e.g. a fake, or an already-open pool/connection from
+ * `mysql2/promise`).
+ */
+declare class MySQLTransport extends BaseSQLTransport {
+    private readonly injectedClient;
+    private readonly connectionString;
+    private readonly connectionConfig;
+    private client;
+    constructor(options?: MySQLTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    /** MySQL-correct `CREATE TABLE IF NOT EXISTS`: `AUTO_INCREMENT` primary key, `JSON` column type for `meta`. */
+    createTableSQL(): string;
+    protected ensureTable(): Promise<void>;
+    protected insertRows(rows: readonly SQLLogRow[]): Promise<void>;
+}
+
+/** The subset of a `mongodb` `Collection` that `MongoDBTransport` needs. Inject a fake in tests. */
+interface MongoCollectionLike {
+    insertMany(docs: readonly unknown[]): Promise<unknown>;
+}
+/** The subset of a `mongodb` `MongoClient` that `MongoDBTransport` needs to lazily connect. */
+interface MongoClientLike {
+    connect(): Promise<unknown>;
+    db(name: string): {
+        collection(name: string): MongoCollectionLike;
+    };
+}
+interface MongoDBTransportOptions extends BatchingTransportOptions {
+    /** Pre-built collection, e.g. for tests, or an already-connected app. Skips the `mongodb` auto-import entirely. */
+    collection?: MongoCollectionLike;
+    /** `mongodb` connection string, used when no `collection` is injected. Required in that case. */
+    connectionString?: string;
+    /** Database to write into when connecting via `connectionString`. Default `"logquill"`. */
+    database?: string;
+    /** Collection to write into when connecting via `connectionString`. Default `"logs"`. */
+    collectionName?: string;
+}
+/**
+ * Sink for MongoDB. Records map 1:1 to documents — no JSON-in-a-column
+ * workaround needed, unlike the SQL transports.
+ *
+ * `mongodb` is an optional peer dependency: install it yourself, or inject a
+ * `collection` (e.g. a fake, or a `Collection` from a client your app already
+ * manages).
+ */
+declare class MongoDBTransport extends BatchingTransport {
+    private readonly injectedCollection;
+    private readonly connectionString;
+    private readonly database;
+    private readonly collectionName;
+    private collection;
+    constructor(options?: MongoDBTransportOptions);
+    /** Synchronously available collection, if one was injected or already connected — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedCollection;
+    private importCollection;
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+}
+
+/** One item written to DynamoDB: `runId` is the partition key, `timestamp` is the sort key. */
+interface DynamoLogItem {
+    runId: string;
+    timestamp: string;
+    level: string;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+    spanId?: string;
+    parentSpanId?: string;
+    traceId?: string;
+}
+/**
+ * The subset of DynamoDB write access `DynamoDBTransport` needs, deliberately
+ * narrower than the AWS SDK v3 command pattern (`send(command)`): one
+ * `BatchWriteItem`-equivalent call per sub-batch, already capped at
+ * `DYNAMO_BATCH_LIMIT` items by the caller. This keeps fake-based tests
+ * trivial — a fake just needs to record `(tableName, items)` calls, not
+ * emulate a `DynamoDBClient`. Inject a fake in tests, or rely on the built-in
+ * `@aws-sdk/client-dynamodb` wrapper by not injecting a `client`.
+ */
+interface DynamoClientLike {
+    batchWriteItems(tableName: string, items: readonly DynamoLogItem[]): Promise<unknown>;
+}
+interface DynamoDBTransportOptions extends BatchingTransportOptions {
+    /** Pre-built client, e.g. for tests, or a custom wrapper. Skips the `@aws-sdk/client-dynamodb` auto-import entirely. */
+    client?: DynamoClientLike;
+    /** Table to write into. Default `"logs"`. */
+    tableName?: string;
+    /** AWS region, used when no `client` is injected. Falls back to the SDK's own credential-chain resolution when omitted. */
+    region?: string;
+}
+/**
+ * Sink for Amazon DynamoDB. Partition key is `runId`/`traceId` (whichever is
+ * present on `record.meta`, `runId` taking priority), falling back to the
+ * logger name when neither is set, so every record always lands under some
+ * partition even before `RunPlugin`/`TraceContextPlugin` are wired up. Sort
+ * key is `timestamp`.
+ *
+ * DynamoDB's actual `BatchWriteItem` API caps a call at 25 items, so
+ * `sendBatch()` chunks a larger batch into sub-batches of 25 — matching how
+ * `SQSTransport` respects `SendMessageBatch`'s 10-item cap.
+ *
+ * `@aws-sdk/client-dynamodb` is an optional peer dependency: install it
+ * yourself, or inject a `client` (e.g. a fake, or a custom wrapper around a
+ * `DynamoDBClient` your app already manages).
+ */
+declare class DynamoDBTransport extends BatchingTransport {
+    private readonly injectedClient;
+    private readonly tableName;
+    private readonly region;
+    private client;
+    constructor(options?: DynamoDBTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    /** `meta.runId`, else `meta.traceId`, else the logger name — see the class doc for why. */
+    private partitionKey;
+    private toDynamoItem;
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+}
+
+/** The subset of a `redis` (node-redis v4) client that `RedisTransport` needs. Inject a fake in tests. */
+interface RedisClientLike {
+    xAdd(stream: string, id: string, fields: Record<string, string>): Promise<unknown>;
+}
+interface RedisTransportOptions extends BatchingTransportOptions {
+    /** Pre-built, already-connected client, e.g. for tests. Skips the `redis` auto-import entirely. */
+    client?: RedisClientLike;
+    /** `redis` connection URL, used when no `client` is injected. Default `"redis://localhost:6379"`. */
+    url?: string;
+    /** Stream key to `XADD` into. Default `"logquill:logs"`. */
+    stream?: string;
+}
+/**
+ * Sink for Redis, via Redis Streams (`XADD`) — as CLAUDE.md's spec puts it,
+ * "a fast local buffer, a different use case from durable storage, not a
+ * replacement for the others." Reach for this when you want a low-latency
+ * local tail (e.g. feeding a `redis-cli XREAD`-based live viewer) rather than
+ * a system of record.
+ *
+ * Streams has no true multi-entry `XADD`, so unlike the other batching
+ * transports this issues one `XADD` per record within the batch rather than
+ * one network call per batch — batching here still bounds memory and reduces
+ * GC/buffer churn, but it is honestly not a network-call batch the way
+ * `MongoDBTransport.insertMany()` or `DynamoDBTransport`'s `BatchWriteItem`
+ * chunks are.
+ *
+ * `redis` is an optional peer dependency: install it yourself, or inject a
+ * `client` (e.g. a fake, or an already-connected client your app manages).
+ */
+declare class RedisTransport extends BatchingTransport {
+    private readonly injectedClient;
+    private readonly url;
+    private readonly stream;
+    private client;
+    constructor(options?: RedisTransportOptions);
+    /** Synchronously available client, if one was injected or already connected — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    private toFields;
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+}
+
+interface BaseQueueTransportOptions extends BatchingTransportOptions {
+    /**
+     * Destination name on the backend — a Kafka topic, a RabbitMQ queue name,
+     * an SQS queue URL, or a GCP Pub/Sub topic. One generic option name so the
+     * base class's orchestration stays backend-agnostic; each subclass's own
+     * docs use its backend's own vocabulary for what this means.
+     */
+    topic: string;
+}
+/**
+ * Abstract base for every message-queue transport (`KafkaTransport`,
+ * `RabbitMQTransport`, `SQSTransport`, `PubSubTransport`). Owns the "always
+ * batch, never publish one message per log call" contract shared across
+ * every queue backend — buffering itself is inherited from
+ * `BatchingTransport`; each concrete subclass only implements
+ * `publishBatch()` against its own driver's publish API.
+ */
+declare abstract class BaseQueueTransport extends BatchingTransport {
+    readonly topic: string;
+    constructor(options: BaseQueueTransportOptions);
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+    /** Deliver one batch of records to the queue backend. Always called with a non-empty batch. */
+    protected abstract publishBatch(records: readonly LogRecord[]): Promise<void>;
+}
+
+/** The subset of a `kafkajs` `Producer` that `KafkaTransport` needs. Inject a fake in tests. */
+interface KafkaProducerLike {
+    /** Optional: some injected producers (or fakes) are already connected. */
+    connect?(): Promise<void>;
+    send(record: {
+        topic: string;
+        messages: {
+            key: string | null;
+            value: string;
+        }[];
+    }): Promise<unknown>;
+}
+interface KafkaTransportOptions extends BaseQueueTransportOptions {
+    /** Pre-built producer, e.g. for tests, or an already-configured kafkajs `Producer`. Skips the `kafkajs` auto-import entirely. */
+    client?: KafkaProducerLike;
+    /** Broker addresses passed to `kafkajs`'s `Kafka({ brokers })` when no `client` is injected. Default `["localhost:9092"]`. */
+    brokers?: string[];
+}
+/**
+ * Publishes batches to a Kafka topic via `kafkajs`. Each message's `key` is
+ * set to `meta.runId` (falling back to `meta.traceId`, then `null`), so
+ * kafkajs's default partitioner keeps every message from the same agent
+ * run/trace on one partition — preserving per-trace ordering, per the
+ * message-queue contract in the project spec.
+ *
+ * `kafkajs` is an optional peer dependency: install it yourself, or inject a
+ * `client` (e.g. a fake, or an already-configured `Producer`).
+ */
+declare class KafkaTransport extends BaseQueueTransport {
+    private readonly injectedClient;
+    private readonly brokers;
+    private client;
+    constructor(options: KafkaTransportOptions);
+    /** Synchronously available producer, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    /**
+     * Builds the real `kafkajs` producer and connects it. Connection happens
+     * here, once, as part of acquiring the driver — not on every
+     * `publishBatch()` call — so an injected `client` (tests, or a caller's
+     * own already-connected producer) is trusted to already be ready and is
+     * never re-connected.
+     */
+    private importClient;
+    protected publishBatch(records: readonly LogRecord[]): Promise<void>;
+}
+
+/** The subset of an `amqplib` `Channel` that `RabbitMQTransport` needs. Inject a fake in tests. */
+interface AmqpChannelLike {
+    /** Optional: only called once, and only when provided, to ensure the queue exists. */
+    assertQueue?(queue: string, options?: unknown): Promise<unknown>;
+    sendToQueue(queue: string, content: Buffer, options?: unknown): boolean;
+}
+interface RabbitMQTransportOptions extends BaseQueueTransportOptions {
+    /** Pre-built channel, e.g. for tests, or an already-open amqplib `Channel`. Skips the `amqplib` auto-import entirely. */
+    client?: AmqpChannelLike;
+    /** Connection URL passed to `amqplib.connect()` when no `client` is injected. Default `"amqp://localhost"`. */
+    url?: string;
+}
+/**
+ * Publishes batches to a RabbitMQ queue via `amqplib`. RabbitMQ's core API
+ * has no native multi-message batch primitive — there is no
+ * `sendToQueue`-equivalent that takes an array — so `publishBatch()` loops
+ * one `sendToQueue()` call per record. The "batch" LogQuill promises is at
+ * the buffering level: `maxRecords`/`maxBytes` still governs how often that
+ * loop runs, so this transport never makes one network round trip per log
+ * call; it just can't make one round trip per *batch* either, honestly,
+ * since RabbitMQ itself doesn't offer that primitive.
+ *
+ * `amqplib` is an optional peer dependency: install it yourself, or inject a
+ * `client` (e.g. a fake, or an already-open `Channel`).
+ */
+declare class RabbitMQTransport extends BaseQueueTransport {
+    private readonly injectedClient;
+    private readonly url;
+    private client;
+    constructor(options: RabbitMQTransportOptions);
+    /** Synchronously available channel, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    /**
+     * Opens the real `amqplib` connection/channel and asserts the queue
+     * exists. Both happen here, once, as part of acquiring the driver — not on
+     * every `publishBatch()` call — so an injected `client` (tests, or a
+     * caller's own already-open channel) is trusted to already have its queue
+     * set up and is never re-asserted.
+     */
+    private importClient;
+    protected publishBatch(records: readonly LogRecord[]): Promise<void>;
+}
+
+/**
+ * The subset of AWS SDK v3's SQS client that `SQSTransport` needs, narrowed
+ * to a plain `sendMessageBatch(queueUrl, entries)` method rather than
+ * modeling the full `@aws-sdk/client-sqs` command/client pattern — simpler
+ * to fake in tests, and the only shape this transport actually calls. Inject
+ * a fake in tests, or wrap a real `SQSClient` to match this shape.
+ */
+interface SQSClientLike {
+    sendMessageBatch(queueUrl: string, entries: {
+        id: string;
+        body: string;
+    }[]): Promise<unknown>;
+}
+interface SQSTransportOptions extends BaseQueueTransportOptions {
+    /** Pre-built client, e.g. for tests, or a thin wrapper around `@aws-sdk/client-sqs`'s `SQSClient`. Skips the `@aws-sdk/client-sqs` auto-import entirely. */
+    client?: SQSClientLike;
+    /** AWS region passed to `@aws-sdk/client-sqs` when no `client` is injected. */
+    region?: string;
+}
+/**
+ * Publishes batches to an SQS queue via `@aws-sdk/client-sqs`'s
+ * `SendMessageBatch`. That API caps a single request at 10 messages, so
+ * `publishBatch()` chunks any larger batch into sub-batches of 10 —
+ * LogQuill's own `maxRecords`/`maxBytes` buffering can flush more than 10
+ * records at once; this transport is responsible for respecting SQS's own
+ * limit underneath, per the message-queue contract in the project spec.
+ *
+ * `@aws-sdk/client-sqs` is an optional peer dependency: install it
+ * yourself, or inject a `client` (e.g. a fake, or a wrapped `SQSClient`).
+ */
+declare class SQSTransport extends BaseQueueTransport {
+    private readonly injectedClient;
+    private readonly region;
+    private client;
+    constructor(options: SQSTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    protected publishBatch(records: readonly LogRecord[]): Promise<void>;
+}
+
+/**
+ * The subset of a `@google-cloud/pubsub` `Topic` that `PubSubTransport`
+ * needs. Inject a fake in tests, or an already-resolved `Topic` instance.
+ */
+interface PubSubTopicLike {
+    publishMessage(message: {
+        data: Buffer;
+    }): Promise<string>;
+}
+interface PubSubTransportOptions extends BaseQueueTransportOptions {
+    /** Pre-built topic reference, e.g. for tests, or an already-resolved `@google-cloud/pubsub` `Topic`. Skips the `@google-cloud/pubsub` auto-import entirely. */
+    client?: PubSubTopicLike;
+    /** GCP project ID passed to `@google-cloud/pubsub` when no `client` is injected. */
+    projectId?: string;
+}
+/**
+ * Publishes batches to a GCP Pub/Sub topic via `@google-cloud/pubsub`. The
+ * real client already does its own internal batching/flow-control underneath
+ * `publishMessage()` — this transport doesn't reimplement that. What it does
+ * own is LogQuill's own bounded-memory contract: `publishBatch()` only runs
+ * once per buffer flush (`maxRecords`/`maxBytes`), so the driver is never
+ * invoked once per individual log call.
+ *
+ * `@google-cloud/pubsub` is an optional peer dependency: install it
+ * yourself, or inject a `client` (e.g. a fake, or a resolved `Topic`).
+ */
+declare class PubSubTransport extends BaseQueueTransport {
+    private readonly injectedClient;
+    private readonly projectId;
+    private client;
+    constructor(options: PubSubTransportOptions);
+    /** Synchronously available topic reference, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    protected publishBatch(records: readonly LogRecord[]): Promise<void>;
+}
+
+/** One CloudWatch Logs event: epoch-milliseconds timestamp plus a single log line. */
+interface CloudWatchLogEvent {
+    timestamp: number;
+    message: string;
+}
+/**
+ * The subset of the AWS SDK v3 CloudWatch Logs client that `CloudWatchTransport`
+ * needs. Deliberately narrower than the SDK's full command pattern (build a
+ * `PutLogEventsCommand`, `.send()` it, track the deprecated sequence-token
+ * dance) — modeling just this one operation keeps the injectable-fake surface
+ * small for tests; `importClient()` builds the real adapter around it.
+ */
+interface CloudWatchClientLike {
+    putLogEvents(logGroupName: string, logStreamName: string, events: readonly CloudWatchLogEvent[]): Promise<unknown>;
+}
+interface CloudWatchTransportOptions extends BatchingTransportOptions {
+    /** CloudWatch Logs log group to write into. */
+    logGroupName: string;
+    /** CloudWatch Logs log stream, within `logGroupName`, to write into. */
+    logStreamName: string;
+    /** AWS region, e.g. `"us-east-1"`. Passed to the real SDK client; ignored when `client` is injected. */
+    region?: string;
+    /** Pre-built client, e.g. for tests. Skips the `@aws-sdk/client-cloudwatch-logs` auto-import entirely. */
+    client?: CloudWatchClientLike;
+}
+/**
+ * Ships batched records to AWS CloudWatch Logs via the AWS SDK v3
+ * (`@aws-sdk/client-cloudwatch-logs`). Each buffered record becomes one log
+ * event; CloudWatch requires events within a single `PutLogEvents` call to be
+ * sorted by timestamp ascending, which `sendBatch()` does before sending.
+ *
+ * `@aws-sdk/client-cloudwatch-logs` is an optional peer dependency: install
+ * it yourself, or inject a `client` (e.g. a fake, or an already-configured
+ * `CloudWatchLogsClient` wrapped to match `CloudWatchClientLike`).
+ */
+declare class CloudWatchTransport extends BatchingTransport {
+    readonly logGroupName: string;
+    readonly logStreamName: string;
+    readonly region: string | undefined;
+    private readonly injectedClient;
+    private client;
+    constructor(options: CloudWatchTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+}
+
+/** One GCP Cloud Logging entry, shaped for `Log#write`. */
+interface CloudLoggingEntry {
+    severity: string;
+    timestamp: string;
+    jsonPayload: Record<string, unknown>;
+}
+/**
+ * The subset of the `@google-cloud/logging` client that `CloudLoggingTransport`
+ * needs. Deliberately narrower than the SDK's full `Log`/`Entry` object model —
+ * `importClient()` builds the real adapter around `logging.log(name).write(entries)`.
+ */
+interface CloudLoggingClientLike {
+    writeLogEntries(entries: readonly CloudLoggingEntry[]): Promise<unknown>;
+}
+interface CloudLoggingTransportOptions extends BatchingTransportOptions {
+    /** GCP log name (the last segment of the log resource path). Default `"logquill"`. */
+    logName?: string;
+    /** GCP project ID. Passed to the real SDK client; ignored when `client` is injected — omit to use Application Default Credentials' project. */
+    projectId?: string;
+    /** Pre-built client, e.g. for tests. Skips the `@google-cloud/logging` auto-import entirely. */
+    client?: CloudLoggingClientLike;
+}
+/**
+ * Ships batched records to Google Cloud Logging via `@google-cloud/logging`.
+ * Each record becomes one structured entry (`jsonPayload`), with `level`
+ * mapped onto Cloud Logging's `severity` enum.
+ *
+ * `@google-cloud/logging` is an optional peer dependency: install it
+ * yourself, or inject a `client` (e.g. a fake, or an already-configured
+ * `Log` wrapped to match `CloudLoggingClientLike`).
+ */
+declare class CloudLoggingTransport extends BatchingTransport {
+    readonly logName: string;
+    readonly projectId: string | undefined;
+    private readonly injectedClient;
+    private client;
+    constructor(options?: CloudLoggingTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+}
+
+/** One Application Insights trace: a message plus its `SeverityLevel`. */
+interface AppInsightsTrace {
+    message: string;
+    severity: number;
+}
+/**
+ * The subset of Application Insights telemetry that `AppInsightsTransport`
+ * needs.
+ *
+ * `trackTraceBatch` is LogQuill's own batching contract, not a native
+ * `applicationinsights` SDK method — the real SDK only exposes a single-record
+ * `trackTrace()` plus an async `flush()`. The real-client adapter built by
+ * `importClient()` loops `trackTrace()` calls inside `trackTraceBatch` and
+ * flushes once at the end, so batching happens at the LogQuill buffering
+ * level (bounded by `maxRecords`/`maxBytes`), not as a real network-level
+ * batch call — Application Insights doesn't offer one.
+ */
+interface AppInsightsClientLike {
+    trackTraceBatch(traces: readonly AppInsightsTrace[]): Promise<unknown>;
+}
+interface AppInsightsTransportOptions extends BatchingTransportOptions {
+    /** Azure Application Insights connection string. Passed to the real SDK client; ignored when `client` is injected. */
+    connectionString?: string;
+    /** Pre-built client, e.g. for tests. Skips the `applicationinsights` auto-import entirely. */
+    client?: AppInsightsClientLike;
+}
+/**
+ * Ships batched records to Azure Application Insights via `applicationinsights`,
+ * as trace telemetry with `level` mapped onto Application Insights' severity
+ * scale. See `AppInsightsClientLike` for why "batch" means LogQuill-side
+ * buffering plus a loop of single `trackTrace()` calls, not one network batch
+ * request — the underlying SDK has no batch-track API.
+ *
+ * `applicationinsights` is an optional peer dependency: install it yourself,
+ * or inject a `client` (e.g. a fake, or an already-configured `TelemetryClient`
+ * wrapped to match `AppInsightsClientLike`).
+ */
+declare class AppInsightsTransport extends BatchingTransport {
+    readonly connectionString: string | undefined;
+    private readonly injectedClient;
+    private client;
+    constructor(options?: AppInsightsTransportOptions);
+    /** Synchronously available client, if one was injected or already imported — avoids an unnecessary microtask hop on the hot path. */
+    private resolvedClient;
+    private importClient;
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+}
+
+/** Sends one batch of formatted lines to Datadog's Logs intake API at `url`. Swap in a fake for tests. */
+type DatadogSender = (url: string, apiKey: string, batch: readonly string[]) => Promise<void> | void;
+interface DatadogTransportOptions extends BatchingTransportOptions {
+    /** Datadog API key, sent in the `DD-API-KEY` header. */
+    apiKey: string;
+    /**
+     * Datadog site (region), e.g. `"datadoghq.com"` (US1, default),
+     * `"datadoghq.eu"` (EU), `"us3.datadoghq.com"`, `"us5.datadoghq.com"`,
+     * `"ap1.datadoghq.com"`. Never hardcode this — sending to the wrong
+     * region's intake host silently fails to deliver logs to your account.
+     */
+    site?: string;
+    sender?: DatadogSender;
+}
+/**
+ * Batches records and POSTs them as a JSON array to Datadog's Logs intake
+ * API (`https://http-intake.logs.<site>/api/v2/logs`) via `fetch`. Pass
+ * `sender` to swap in a fake for tests, or a different delivery mechanism.
+ */
+declare class DatadogTransport extends BatchingTransport {
+    readonly url: string;
+    readonly apiKey: string;
+    readonly site: string;
+    private readonly sender;
+    constructor(options: DatadogTransportOptions);
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void> | void;
+}
+
+/** Sends one pre-built NDJSON `_bulk` body to `url` with the given headers. Swap in a fake for tests. */
+type ElasticsearchSender = (url: string, headers: Readonly<Record<string, string>>, body: string) => Promise<void> | void;
+interface ElasticsearchTransportOptions extends BatchingTransportOptions {
+    /** Cluster base URL, e.g. `"https://localhost:9200"`. */
+    node: string;
+    /** Index to write into. Default `"logs"`. */
+    index?: string;
+    /** Elasticsearch API key (base64 `id:api_key`), sent as `Authorization: ApiKey <apiKey>`. Omit to send no auth header (e.g. behind a proxy that adds its own). */
+    apiKey?: string;
+    sender?: ElasticsearchSender;
+}
+/**
+ * Batches records and POSTs them to Elasticsearch's `_bulk` API
+ * (`<node>/_bulk`) via `fetch`, as newline-delimited action+source pairs —
+ * no client dependency needed, just NDJSON body construction. Pass `sender`
+ * to swap in a fake for tests, or a different delivery mechanism.
+ */
+declare class ElasticsearchTransport extends BatchingTransport {
+    readonly url: string;
+    readonly index: string;
+    private readonly apiKey;
+    private readonly sender;
+    constructor(options: ElasticsearchTransportOptions);
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void> | void;
+}
+
+/** Which New Relic ingest region to send to — determines the Log API host. */
+type NewRelicRegion = "US" | "EU";
+/** What `NewRelicSender` reports back about one delivery attempt, so the transport can drive its own 429 backoff logic. */
+interface NewRelicSenderResult {
+    ok: boolean;
+    status: number;
+    /** The raw `Retry-After` response header value, if present — either a number of seconds or an HTTP-date, per RFC 9110. */
+    retryAfter: string | null;
+}
+/** Sends one gzip-compressed batch to New Relic's Log API at `url`. Swap in a fake for tests. */
+type NewRelicSender = (url: string, headers: Readonly<Record<string, string>>, body: Buffer) => Promise<NewRelicSenderResult> | NewRelicSenderResult;
+interface NewRelicTransportOptions extends BatchingTransportOptions {
+    /** New Relic license key, sent in the `Api-Key` header. */
+    licenseKey: string;
+    /**
+     * New Relic account region — selects the ingest host
+     * (`log-api.newrelic.com` for US, `log-api.eu.newrelic.com` for EU).
+     * Never hardcode this: an EU-region license key sent to the US host (or
+     * vice versa) is rejected. Default `"US"`.
+     */
+    region?: NewRelicRegion;
+    sender?: NewRelicSender;
+    /** Injectable clock for the 429 backoff window, matching `SamplingPlugin`'s injectable `rng`. Default `Date.now`. */
+    clock?: () => number;
+}
+/**
+ * Batches records and POSTs them, gzip-compressed, to New Relic's Log API
+ * (`log-api.newrelic.com` / `log-api.eu.newrelic.com`, region-configurable)
+ * via `fetch`. Strips the reserved `meta.eventType` key (New Relic drops
+ * records carrying it) and honors 429 responses by reading `Retry-After`
+ * and pausing further sends until it elapses, rather than hammering an
+ * account that's already been rate-limited for the rest of the minute.
+ *
+ * Pass `sender` to swap in a fake for tests, and `clock` to control time in
+ * backoff tests without waiting on a real clock.
+ */
+declare class NewRelicTransport extends BatchingTransport {
+    readonly url: string;
+    readonly region: NewRelicRegion;
+    private readonly licenseKey;
+    private readonly sender;
+    private readonly clock;
+    private pausedUntil;
+    constructor(options: NewRelicTransportOptions);
+    protected sendBatch(batch: readonly LogRecord[]): Promise<void>;
+}
+
 /** The subset of `console` this transport needs — swap in a fake for tests. */
 interface ConsoleLike {
     log(message: string): void;
@@ -176,7 +1236,7 @@ declare class HTTPTransport extends Transport {
 interface LoggerOptions {
     level?: LevelInput;
     transports?: Transport[];
-    plugins?: Plugin[];
+    plugins?: (Plugin | MiddlewareFunc)[];
     meta?: Record<string, unknown>;
 }
 declare class Logger {
@@ -188,8 +1248,13 @@ declare class Logger {
     constructor(name: string, options?: LoggerOptions);
     get level(): Level;
     setLevel(level: LevelInput): void;
-    /** Register a plugin. Returns `this` so calls can be chained. */
-    use(plugin: Plugin): this;
+    /**
+     * Register a plugin, or a plain `beforeLog`-style function. A function is
+     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+     * same middleware ergonomics as Express/Koa, without needing to read the
+     * `Plugin` interface first. Returns `this` so calls can be chained.
+     */
+    use(plugin: Plugin | MiddlewareFunc): this;
     /** Close every attached transport. Call on shutdown to flush buffered writes. */
     close(): void;
     /** A logger scoped under this one, inheriting its level, transports, and plugins. */
@@ -204,6 +1269,6 @@ declare class Logger {
     fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
 }
 
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.3.0";
 
-export { CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_REDACTED_KEYS, FileTransport, type FileTransportOptions, type Formatter, HTTPTransport, type HTTPTransportOptions, JSONFormatter, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type Plugin, RedactPlugin, type RedactPluginOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, type Formatter, FunctionPlugin, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, JSONFormatter, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MiddlewareFunc, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, type Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };