logquill 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -1,3 +1,979 @@
-declare const VERSION = "0.1.0";
+/** Log levels, shared by name and numeric weight with the logquill-python contract. */
+declare enum Level {
+    TRACE = 5,
+    DEBUG = 10,
+    INFO = 20,
+    WARN = 30,
+    ERROR = 40,
+    FATAL = 50
+}
+/** A level given as a `Level`, a level name (any case), or its numeric weight. */
+type LevelInput = Level | number | string;
+/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
+declare function levelName(level: Level): string;
+/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
+declare function parseLevel(level: LevelInput): Level;
 
-export { VERSION };
+/** The cross-language record shape shared with logquill-python. */
+interface LogRecord {
+    timestamp: string;
+    level: string;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}
+/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
+declare function utcTimestamp(): string;
+declare function createRecord(params: {
+    level: Level;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}): LogRecord;
+
+/** `format(record) -> string`, per the transport contract shared with logquill-python. */
+interface Formatter {
+    format(record: LogRecord): string;
+}
+/** Serializes a record to the canonical JSON line shape. */
+declare class JSONFormatter implements Formatter {
+    format(record: LogRecord): string;
+}
+
+/**
+ * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
+ * `afterLog`, `onError`. All hooks are optional — implement only what you need.
+ * A hook that throws cannot crash logging: the pipeline catches it, routes it
+ * to `onError`, and moves on.
+ */
+interface Plugin {
+    /** Return a (possibly modified) record, or `null` to drop it. */
+    beforeLog?(record: LogRecord): LogRecord | null;
+    /** Called after the record has been dispatched to every transport. */
+    afterLog?(record: LogRecord): void;
+    /** Called when one of this plugin's own hooks throws. */
+    onError?(error: unknown, record: LogRecord): void;
+}
+
+/**
+ * Injects fixed key/value pairs into every record's `meta`.
+ * A value already present in a record's own `meta` wins over the fixed context.
+ */
+declare class ContextPlugin implements Plugin {
+    readonly context: Record<string, unknown>;
+    constructor(context: Record<string, unknown>);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+declare const DEFAULT_REDACTED_KEYS: readonly string[];
+interface RedactPluginOptions {
+    keys?: readonly string[];
+    replacement?: string;
+}
+/** Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder. */
+declare class RedactPlugin implements Plugin {
+    private readonly keys;
+    readonly replacement: string;
+    constructor(options?: RedactPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+interface SamplingPluginOptions {
+    rng?: () => number;
+}
+/** 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;
+}
+
+/**
+ * Sink for log records, per the cross-language transport contract:
+ * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
+ */
+declare abstract class Transport {
+    formatter: Formatter;
+    constructor(formatter?: Formatter);
+    format(record: LogRecord): string;
+    abstract write(formatted: string, record: LogRecord): void;
+    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
+    close(): void;
+}
+/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
+declare class CollectingTransport extends Transport {
+    readonly formatted: string[];
+    readonly records: LogRecord[];
+    closed: boolean;
+    write(formatted: string, record: LogRecord): void;
+    close(): void;
+}
+
+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;
+    error(message: string): void;
+}
+interface ConsoleTransportOptions {
+    formatter?: Formatter;
+    colorize?: boolean;
+    console?: ConsoleLike;
+}
+/**
+ * Writes to `console.log`, routing ERROR/FATAL to `console.error`, colorized by
+ * level. Uses the global `console` rather than Node's `process.stdout`/`stderr`
+ * so this transport works unmodified in a browser bundle.
+ */
+declare class ConsoleTransport extends Transport {
+    colorize: boolean;
+    private readonly out;
+    constructor(options?: ConsoleTransportOptions);
+    write(formatted: string, record: LogRecord): void;
+    private applyColor;
+}
+
+interface FileTransportOptions {
+    formatter?: Formatter;
+    maxBytes?: number;
+    backupCount?: number;
+}
+/** Appends formatted records to a file, rotating when it exceeds `maxBytes`. */
+declare class FileTransport extends Transport {
+    readonly path: string;
+    readonly maxBytes: number;
+    readonly backupCount: number;
+    private fd;
+    constructor(path: string, options?: FileTransportOptions);
+    write(formatted: string): void;
+    private rotate;
+    close(): void;
+}
+
+/** Sends one batch of formatted lines to `url`. Swap in a fake for tests. */
+type Sender = (url: string, batch: readonly string[]) => Promise<void> | void;
+interface HTTPTransportOptions {
+    formatter?: Formatter;
+    batchSize?: number;
+    sender?: Sender;
+}
+/**
+ * Batches formatted records and POSTs them as newline-delimited JSON via `fetch`.
+ * Pass `sender` to swap in a fake for tests, or a different backend.
+ */
+declare class HTTPTransport extends Transport {
+    readonly url: string;
+    readonly batchSize: number;
+    private readonly sender;
+    private batch;
+    constructor(url: string, options?: HTTPTransportOptions);
+    write(formatted: string): void;
+    /** Send the current batch now, even if it hasn't reached `batchSize`. */
+    flush(): void;
+    close(): void;
+}
+
+interface LoggerOptions {
+    level?: LevelInput;
+    transports?: Transport[];
+    plugins?: Plugin[];
+    meta?: Record<string, unknown>;
+}
+declare class Logger {
+    readonly name: string;
+    readonly transports: Transport[];
+    readonly plugins: Plugin[];
+    private currentLevel;
+    private readonly baseMeta;
+    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;
+    /** 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. */
+    child(name: string, meta?: Record<string, unknown>): Logger;
+    private notifyError;
+    private dispatch;
+    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
+}
+
+declare const VERSION = "0.2.0";
+
+export { 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_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, FileTransport, type FileTransportOptions, type Formatter, HTTPTransport, type HTTPTransportOptions, JSONFormatter, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, 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, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };