logquill 0.2.0 → 0.3.0

package/README.md

@@ -10,23 +10,41 @@ JSON log shape with its Python sibling, [`logquill`](https://pypi.org/project/lo
 (repo: `logquill-python`).
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, the plugin pipeline (with `ContextPlugin`/`RedactPlugin`/
-`SamplingPlugin` built in), `JSONFormatter`, and the built-in transports are
-implemented; non-blocking async dispatch is not yet — see `CHANGELOG.md`
-for what's landed so far.
+filtering, a full plugin pipeline (context/redaction/PII/tamper-evidence/
+sampling/alerting), `JSONFormatter`, and a broad transport catalog —
+console/file/HTTP, SQL, NoSQL, message queues, and cloud-native log
+platforms — are implemented; non-blocking async dispatch is not yet — see
+`CHANGELOG.md` for what's landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` object, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on PyPI](https://pypi.org/project/logquill/)
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> string` for your own
-- **Pluggable transports** — `ConsoleTransport` (colorized, respects `NO_COLOR`, isomorphic), `FileTransport` (rotation), `HTTPTransport` (batched, `fetch`-based); write your own by subclassing `Transport`; `CollectingTransport` ships as an in-memory sink, handy for tests
-- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; `beforeLog`/`afterLog`/`onError` hooks; a throwing plugin can't crash logging
+- **A transport for wherever your logs need to go** — console, file, and HTTP out of the box, plus SQL (SQLite/Postgres/MySQL), NoSQL (MongoDB/DynamoDB/Redis), message queues (Kafka/RabbitMQ/SQS/Pub-Sub), and cloud-native platforms (CloudWatch/Cloud Logging/App Insights/Datadog/Elasticsearch/New Relic) — see [Transports](#transports). Every backend driver is an **optional peer dependency**: install only the one you use, or inject a pre-built client. Write your own by subclassing `Transport`; `CollectingTransport` ships as an in-memory sink, handy for tests
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `PIIRedactPlugin`, tail-based `SamplingPlugin`, `TamperEvidentPlugin`, and `AlertingPlugin` (`SlackAlertPlugin`/`PagerDutyAlertPlugin`/`EmailAlertPlugin`) out of the box; `beforeLog`/`afterLog`/`onError` hooks, or just pass a plain function to `.use()`; a throwing plugin can't crash logging — see [Plugins](#plugins)
 - **Child loggers** — `.child()` inherits level, transports, and plugins, and merges its own `meta` on top
 - **Typed throughout** — TypeScript strict mode, no `any` in the public API
 - **Dual package** — works via both `require()` (CJS) and `import` (ESM) from the same published package
 - *(planned)* non-blocking async dispatch, `AsyncLocalStorage`-based context propagation — see `CHANGELOG.md`
 
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Transports](#transports)
+  - [SQL transports](#sql-transports)
+  - [NoSQL transports](#nosql-transports)
+  - [Message queue transports](#message-queue-transports)
+  - [Cloud-native transports](#cloud-native-transports)
+- [Plugins](#plugins)
+  - [Tail-based sampling](#tail-based-sampling)
+  - [PII redaction](#pii-redaction)
+  - [Tamper-evident logs](#tamper-evident-logs)
+  - [Alerting](#alerting)
+- [Development](#development)
+- [License](#license)
+
 ## Install
 
 ```sh
@@ -90,7 +108,36 @@ a dual build with full TypeScript types.
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously
-(non-blocking dispatch isn't implemented yet):
+(non-blocking dispatch isn't implemented yet). Every backend driver below
+is an **optional peer dependency** — `npm install` only pulls in what you
+actually import; nothing is installed on your behalf.
+
+| Transport | Backend | Peer dependency | Setup |
+|---|---|---|---|
+| `ConsoleTransport` | stdout/stderr via `console.*` | *(none)* | zero-setup, isomorphic |
+| `FileTransport` | local file, with rotation | *(none)* | zero-setup |
+| `HTTPTransport` | any HTTP log endpoint | *(none, uses `fetch`)* | zero-setup |
+| `SQLiteTransport` | SQLite | `better-sqlite3` | zero-setup (file or `:memory:`) |
+| `PostgresTransport` | PostgreSQL | `pg` | needs a server |
+| `MySQLTransport` | MySQL | `mysql2` | needs a server |
+| `MongoDBTransport` | MongoDB | `mongodb` | needs a server |
+| `DynamoDBTransport` | AWS DynamoDB | `@aws-sdk/client-dynamodb` | needs an AWS account |
+| `RedisTransport` | Redis Streams | `redis` | needs a server |
+| `KafkaTransport` | Kafka | `kafkajs` | needs a broker |
+| `RabbitMQTransport` | RabbitMQ | `amqplib` | needs a broker |
+| `SQSTransport` | AWS SQS | `@aws-sdk/client-sqs` | needs an AWS account |
+| `PubSubTransport` | GCP Pub/Sub | `@google-cloud/pubsub` | needs a GCP account |
+| `CloudWatchTransport` | AWS CloudWatch Logs | `@aws-sdk/client-cloudwatch-logs` | needs an AWS account |
+| `CloudLoggingTransport` | GCP Cloud Logging | `@google-cloud/logging` | needs a GCP account |
+| `AppInsightsTransport` | Azure Application Insights | `applicationinsights` | needs an Azure account |
+| `DatadogTransport` | Datadog Logs | *(none, uses `fetch`)* | needs a Datadog account |
+| `ElasticsearchTransport` | Elasticsearch `_bulk` API | *(none, uses `fetch`)* | needs a cluster |
+| `NewRelicTransport` | New Relic Log API | *(none, uses `fetch`)* | needs a New Relic account |
+
+Every transport also accepts an injected client/sender in place of its
+default driver — the pattern every example below and every transport's own
+test suite uses, so you never need a live backend just to test your
+logging setup.
 
 ```ts
 import { ConsoleTransport, FileTransport, HTTPTransport, Logger } from "logquill";
@@ -366,7 +413,94 @@ logger.info("login attempt", { user_id: 42, password: "hunter2" });
 // (unless this call was one of the ~90% sampling dropped, in which case it's null)
 ```
 
-Write your own by implementing `Plugin`; every hook is optional.
+Write your own by implementing `Plugin`; every hook is optional. `.use()`
+also accepts a plain function in place of a `Plugin` — sugar for a
+single-method `beforeLog` plugin, Express/Koa-style:
+
+```ts
+logger.use((record) => {
+  delete record.meta.ssn;
+  return record; // or null to drop the record
+});
+```
+
+### Tail-based sampling
+
+`SamplingPlugin` can do more than flat-rate sampling: pass `transports`
+and it buffers a sampled-out record under its `meta.traceId` instead of
+dropping it outright. If a later record on that same trace reaches
+`elevateAt` (default `ERROR`), the whole trace is flushed — every buffered
+record for it, plus everything from then on — so a request that turned out
+to matter still produces a complete trace, even though most of its steps
+would otherwise have been sampled away.
+
+```ts
+import { CollectingTransport, Logger, SamplingPlugin } from "logquill";
+
+const sink = new CollectingTransport();
+const logger = new Logger("app", {
+  transports: [sink],
+  plugins: [new SamplingPlugin(0.01, { transports: [sink] })], // keep 1%, but never lose an errored trace
+});
+
+logger.info("step 1", { traceId: "req-42" }); // likely dropped...
+logger.info("step 2", { traceId: "req-42" }); // ...and this one too
+logger.error("step 3 failed", { traceId: "req-42" }); // elevates req-42 — steps 1-3 all ship
+```
+
+### PII redaction
+
+`PIIRedactPlugin` complements `RedactPlugin`'s exact-key matching with
+regex-based scanning of `meta` **values** — emails, SSNs, credit-card
+numbers, and phone numbers are redacted wherever they appear, recursively
+through nested objects/arrays, regardless of which key holds them.
+
+```ts
+import { Logger, PIIRedactPlugin } from "logquill";
+
+const logger = new Logger("app", { plugins: [new PIIRedactPlugin()] });
+logger.info("support ticket", { notes: "contact me at jane@example.com" });
+// meta.notes: "contact me at ***"
+```
+
+### Tamper-evident logs
+
+`TamperEvidentPlugin` hash-chains every record — each one's `meta.hash` is
+a SHA-256 digest over its own content plus the previous record's hash — so
+editing, removing, or reordering a written line breaks the chain from that
+point on, detectable later with the static `verifyChain()`. Opt-in: hashing
+every record has a real CPU cost.
+
+```ts
+import { Logger, TamperEvidentPlugin } from "logquill";
+
+const logger = new Logger("app", { plugins: [new TamperEvidentPlugin()] });
+const records = [logger.info("one"), logger.info("two")];
+
+TamperEvidentPlugin.verifyChain(records); // true
+```
+
+### Alerting
+
+`AlertingPlugin` is the base for plugins that fire an external alert on
+ERROR/FATAL (or any configurable `threshold`) without ever blocking the
+log call that triggered it. Repeated matches within a dedupe window
+collapse into a single follow-up alert reporting the total count, instead
+of spamming the destination once per record.
+
+```ts
+import { Logger, SlackAlertPlugin } from "logquill";
+
+const logger = new Logger("app", {
+  plugins: [new SlackAlertPlugin("https://hooks.slack.com/services/...")],
+});
+logger.error("payment webhook failed", { orderId: "o-123" });
+```
+
+`PagerDutyAlertPlugin` (Events API v2, no extra dependency) and
+`EmailAlertPlugin` (SMTP via the optional `nodemailer` peer dependency, or
+inject a `sender`) follow the same shape. Write your own by extending
+`AlertingPlugin` and implementing `sendAlert(record, occurrences)`.
 
 ## Development
 

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var crypto = require('crypto');
 var zlib = require('zlib');
 var fs = require('fs');
 var path = require('path');
@@ -60,6 +61,17 @@ var JSONFormatter = class {
   }
 };
 
+// src/core/plugin.ts
+var FunctionPlugin = class {
+  func;
+  constructor(func) {
+    this.func = func;
+  }
+  beforeLog(record) {
+    return this.func(record);
+  }
+};
+
 // src/plugins/context-plugin.ts
 var ContextPlugin = class {
   context;
@@ -89,19 +101,409 @@ var RedactPlugin = class {
   }
 };
 
+// src/plugins/pii-redact-plugin.ts
+var DEFAULT_PII_PATTERNS = {
+  email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  ssn: /\b\d{3}-\d{2}-\d{4}\b/g,
+  creditCard: /\b(?:\d[ -]?){13,16}\b/g,
+  phone: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g
+};
+var MAX_DEPTH = 50;
+var PIIRedactPlugin = class {
+  patterns;
+  replacement;
+  constructor(options = {}) {
+    this.patterns = options.patterns ?? DEFAULT_PII_PATTERNS;
+    this.replacement = options.replacement ?? "***";
+  }
+  beforeLog(record) {
+    return { ...record, meta: this.redactValue(record.meta, /* @__PURE__ */ new Set(), 0) };
+  }
+  redactValue(value, seen, depth) {
+    if (depth > MAX_DEPTH) {
+      return value;
+    }
+    if (typeof value === "string") {
+      return this.redactText(value);
+    }
+    if (Array.isArray(value)) {
+      if (seen.has(value)) {
+        return value;
+      }
+      const nextSeen = new Set(seen).add(value);
+      return value.map((entry) => this.redactValue(entry, nextSeen, depth + 1));
+    }
+    if (value !== null && typeof value === "object") {
+      if (seen.has(value)) {
+        return value;
+      }
+      const nextSeen = new Set(seen).add(value);
+      const result = {};
+      for (const [key, entryValue] of Object.entries(value)) {
+        result[key] = this.redactValue(entryValue, nextSeen, depth + 1);
+      }
+      return result;
+    }
+    return value;
+  }
+  redactText(text) {
+    let redacted = text;
+    for (const pattern of Object.values(this.patterns)) {
+      const global = pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`);
+      redacted = redacted.replace(global, this.replacement);
+    }
+    return redacted;
+  }
+};
+
 // src/plugins/sampling-plugin.ts
 var SamplingPlugin = class {
   rate;
+  traceKey;
+  elevateAt;
+  transports;
+  maxBufferedRecords;
+  maxTraces;
   rng;
+  buffer = /* @__PURE__ */ new Map();
+  bufferedCount = 0;
+  elevated = /* @__PURE__ */ new Set();
   constructor(rate, options = {}) {
     if (rate < 0 || rate > 1) {
       throw new Error(`rate must be between 0 and 1, got ${String(rate)}`);
     }
     this.rate = rate;
     this.rng = options.rng ?? Math.random;
+    this.traceKey = options.traceKey ?? "traceId";
+    this.elevateAt = parseLevel(options.elevateAt ?? 40 /* ERROR */);
+    this.transports = options.transports;
+    this.maxBufferedRecords = options.maxBufferedRecords ?? 1e3;
+    this.maxTraces = options.maxTraces ?? 200;
   }
   beforeLog(record) {
-    return this.rng() < this.rate ? record : null;
+    const transports = this.transports;
+    if (transports === void 0) {
+      return this.rng() < this.rate ? record : null;
+    }
+    const traceId = record.meta[this.traceKey];
+    if (traceId !== void 0 && this.elevated.has(traceId)) {
+      return record;
+    }
+    const keep = this.rng() < this.rate;
+    const reachedElevateLevel = parseLevel(record.level) >= this.elevateAt;
+    if (traceId !== void 0 && reachedElevateLevel) {
+      this.elevate(traceId, transports);
+      return record;
+    }
+    if (keep) {
+      return record;
+    }
+    if (traceId !== void 0) {
+      this.bufferRecord(traceId, record);
+    }
+    return null;
+  }
+  elevate(traceId, transports) {
+    this.elevated.add(traceId);
+    const buffered = this.buffer.get(traceId) ?? [];
+    this.buffer.delete(traceId);
+    this.bufferedCount -= buffered.length;
+    for (const bufferedRecord of buffered) {
+      for (const transport of transports) {
+        transport.write(transport.format(bufferedRecord), bufferedRecord);
+      }
+    }
+  }
+  bufferRecord(traceId, record) {
+    let records = this.buffer.get(traceId);
+    if (records) {
+      this.buffer.delete(traceId);
+      this.buffer.set(traceId, records);
+    } else {
+      if (this.buffer.size >= this.maxTraces) {
+        this.evictOldestTrace();
+      }
+      records = [];
+      this.buffer.set(traceId, records);
+    }
+    records.push(record);
+    this.bufferedCount += 1;
+    while (this.bufferedCount > this.maxBufferedRecords && this.buffer.size > 0) {
+      this.evictOldestTrace();
+    }
+  }
+  evictOldestTrace() {
+    const oldest = this.buffer.entries().next();
+    if (oldest.done) {
+      return;
+    }
+    const [oldestKey, oldestRecords] = oldest.value;
+    this.buffer.delete(oldestKey);
+    this.bufferedCount -= oldestRecords.length;
+  }
+};
+var GENESIS_HASH = "0".repeat(64);
+function canonicalStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalStringify(entry)).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalStringify(entryValue)}`).join(",")}}`;
+  }
+  if (value === void 0) {
+    return "null";
+  }
+  return JSON.stringify(value);
+}
+function computeHash(record, prevHash) {
+  const restMeta = Object.fromEntries(Object.entries(record.meta).filter(([key]) => key !== "hash" && key !== "prevHash"));
+  const payload = canonicalStringify({
+    timestamp: record.timestamp,
+    level: record.level,
+    logger: record.logger,
+    message: record.message,
+    meta: restMeta
+  });
+  return crypto.createHash("sha256").update(`${prevHash}${payload}`).digest("hex");
+}
+var TamperEvidentPlugin = class {
+  genesisHash;
+  lastHash;
+  constructor(options = {}) {
+    this.genesisHash = options.genesisHash ?? GENESIS_HASH;
+    this.lastHash = this.genesisHash;
+  }
+  beforeLog(record) {
+    const prevHash = this.lastHash;
+    const digest = computeHash(record, prevHash);
+    const next = { ...record, meta: { ...record.meta, prevHash, hash: digest } };
+    this.lastHash = digest;
+    return next;
+  }
+  /**
+   * 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, options = {}) {
+    let prevHash = options.genesisHash ?? GENESIS_HASH;
+    for (const record of records) {
+      const storedHash = record.meta.hash;
+      const storedPrevHash = record.meta.prevHash;
+      if (typeof storedHash !== "string" || storedPrevHash !== prevHash) {
+        return false;
+      }
+      if (computeHash(record, prevHash) !== storedHash) {
+        return false;
+      }
+      prevHash = storedHash;
+    }
+    return true;
+  }
+};
+
+// src/plugins/alerting-plugin.ts
+function defaultDedupeKey(record) {
+  return `${record.level}:${record.logger}:${record.message}`;
+}
+var AlertingPlugin = class {
+  threshold;
+  dedupeWindowMs;
+  maxTrackedKeys;
+  dedupeKeyFn;
+  windows = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.threshold = parseLevel(options.threshold ?? 40 /* ERROR */);
+    this.dedupeWindowMs = options.dedupeWindowMs ?? 3e5;
+    this.dedupeKeyFn = options.dedupeKey ?? defaultDedupeKey;
+    this.maxTrackedKeys = options.maxTrackedKeys ?? 500;
+  }
+  afterLog(record) {
+    if (parseLevel(record.level) < this.threshold) {
+      return;
+    }
+    const key = this.dedupeKeyFn(record);
+    const existing = this.windows.get(key);
+    if (existing) {
+      existing.count += 1;
+      return;
+    }
+    if (this.windows.size >= this.maxTrackedKeys) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      this.flush(key);
+    }, this.dedupeWindowMs);
+    timer.unref();
+    this.windows.set(key, { record, count: 1, timer });
+    this.safeSend(record, 1);
+  }
+  flush(key) {
+    const window = this.windows.get(key);
+    this.windows.delete(key);
+    if (!window || window.count <= 1) {
+      return;
+    }
+    this.safeSend(window.record, window.count);
+  }
+  safeSend(record, occurrences) {
+    Promise.resolve().then(() => this.sendAlert(record, occurrences)).catch((error) => {
+      try {
+        this.onError?.(error, record);
+      } catch {
+      }
+    });
+  }
+  /** Cancel any pending dedupe-window timers. Call on logger shutdown. */
+  close() {
+    const windows = [...this.windows.values()];
+    this.windows.clear();
+    for (const window of windows) {
+      clearTimeout(window.timer);
+    }
+  }
+};
+
+// src/plugins/slack-alert-plugin.ts
+async function fetchSlackSender(webhookUrl, body) {
+  const response = await fetch(webhookUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body
+  });
+  if (!response.ok) {
+    throw new Error(
+      `SlackAlertPlugin: webhook returned HTTP ${String(response.status)} \u2014 check the webhook URL is still valid in Slack's app config`
+    );
+  }
+}
+function formatMessage(record, occurrences) {
+  const suffix = occurrences > 1 ? ` (x${String(occurrences)})` : "";
+  return `[${record.level}] ${record.logger}: ${record.message}${suffix}`;
+}
+var SlackAlertPlugin = class extends AlertingPlugin {
+  webhookUrl;
+  sender;
+  constructor(webhookUrl, options = {}) {
+    super(options);
+    this.webhookUrl = webhookUrl;
+    this.sender = options.sender ?? fetchSlackSender;
+  }
+  async sendAlert(record, occurrences) {
+    const body = JSON.stringify({ text: formatMessage(record, occurrences) });
+    await this.sender(this.webhookUrl, body);
+  }
+};
+
+// src/plugins/pagerduty-alert-plugin.ts
+var ENDPOINT = "https://events.pagerduty.com/v2/enqueue";
+var SEVERITY = { ERROR: "error", FATAL: "critical" };
+async function fetchPagerDutySender(body) {
+  const response = await fetch(ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body
+  });
+  if (!response.ok) {
+    throw new Error(
+      `PagerDutyAlertPlugin: Events API returned HTTP ${String(response.status)} \u2014 check the routing key is a valid Events API v2 integration key`
+    );
+  }
+}
+var PagerDutyAlertPlugin = class extends AlertingPlugin {
+  routingKey;
+  sender;
+  constructor(routingKey, options = {}) {
+    super(options);
+    this.routingKey = routingKey;
+    this.sender = options.sender ?? fetchPagerDutySender;
+  }
+  async sendAlert(record, occurrences) {
+    let summary = `${record.logger}: ${record.message}`;
+    if (occurrences > 1) {
+      summary += ` (x${String(occurrences)})`;
+    }
+    const body = JSON.stringify({
+      routing_key: this.routingKey,
+      event_action: "trigger",
+      payload: {
+        summary,
+        severity: SEVERITY[record.level] ?? "error",
+        source: record.logger,
+        timestamp: record.timestamp,
+        custom_details: { occurrences, ...record.meta }
+      }
+    });
+    await this.sender(body);
+  }
+};
+
+// src/plugins/email-alert-plugin.ts
+var EmailAlertPlugin = class extends AlertingPlugin {
+  smtpHost;
+  smtpPort;
+  fromAddr;
+  toAddrs;
+  username;
+  password;
+  useTls;
+  injectedSender;
+  transporter;
+  constructor(options) {
+    super(options);
+    this.smtpHost = options.smtpHost;
+    this.smtpPort = options.smtpPort;
+    this.fromAddr = options.fromAddr;
+    this.toAddrs = options.toAddrs;
+    this.username = options.username;
+    this.password = options.password;
+    this.useTls = options.useTls ?? true;
+    this.injectedSender = options.sender;
+  }
+  async sendAlert(record, occurrences) {
+    let subject = `[${record.level}] ${record.logger}`;
+    if (occurrences > 1) {
+      subject += ` (x${String(occurrences)})`;
+    }
+    const text = [
+      record.message,
+      "",
+      `occurrences: ${String(occurrences)}`,
+      `timestamp: ${record.timestamp}`,
+      `meta: ${JSON.stringify(record.meta)}`
+    ].join("\n");
+    const message = { from: this.fromAddr, to: this.toAddrs, subject, text };
+    if (this.injectedSender) {
+      await this.injectedSender(message);
+      return;
+    }
+    const transporter = this.transporter ?? await this.importTransporter();
+    await transporter.sendMail({ from: message.from, to: message.to.join(", "), subject: message.subject, text: message.text });
+  }
+  async importTransporter() {
+    let createTransport;
+    try {
+      const moduleName = "nodemailer";
+      const mod = await import(moduleName);
+      const resolved = mod.default?.createTransport ?? mod.createTransport;
+      if (!resolved) {
+        throw new Error("no createTransport export found");
+      }
+      createTransport = resolved;
+    } catch {
+      throw new Error(
+        "EmailAlertPlugin: install `nodemailer` to use this plugin without providing a `sender` \u2014 `npm install nodemailer`"
+      );
+    }
+    this.transporter = createTransport({
+      host: this.smtpHost,
+      port: this.smtpPort,
+      secure: false,
+      requireTLS: this.useTls,
+      auth: this.username && this.password ? { user: this.username, pass: this.password } : void 0
+    });
+    return this.transporter;
   }
 };
 
@@ -1320,7 +1722,10 @@ var Logger = class _Logger {
     this.name = name;
     this.currentLevel = parseLevel(options.level ?? 20 /* INFO */);
     this.transports = options.transports ? [...options.transports] : [];
-    this.plugins = options.plugins ? [...options.plugins] : [];
+    this.plugins = [];
+    for (const plugin of options.plugins ?? []) {
+      this.use(plugin);
+    }
     this.baseMeta = options.meta ? { ...options.meta } : {};
   }
   get level() {
@@ -1329,9 +1734,14 @@ var Logger = class _Logger {
   setLevel(level) {
     this.currentLevel = parseLevel(level);
   }
-  /** Register a plugin. Returns `this` so calls can be chained. */
+  /**
+   * 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) {
-    this.plugins.push(plugin);
+    this.plugins.push(typeof plugin === "function" ? new FunctionPlugin(plugin) : plugin);
     return this;
   }
   /** Close every attached transport. Call on shutdown to flush buffered writes. */
@@ -1411,8 +1821,9 @@ var Logger = class _Logger {
 };
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
+exports.AlertingPlugin = AlertingPlugin;
 exports.AppInsightsTransport = AppInsightsTransport;
 exports.BaseQueueTransport = BaseQueueTransport;
 exports.BaseSQLTransport = BaseSQLTransport;
@@ -1422,11 +1833,15 @@ exports.CloudWatchTransport = CloudWatchTransport;
 exports.CollectingTransport = CollectingTransport;
 exports.ConsoleTransport = ConsoleTransport;
 exports.ContextPlugin = ContextPlugin;
+exports.DEFAULT_PII_PATTERNS = DEFAULT_PII_PATTERNS;
 exports.DEFAULT_REDACTED_KEYS = DEFAULT_REDACTED_KEYS;
 exports.DatadogTransport = DatadogTransport;
 exports.DynamoDBTransport = DynamoDBTransport;
 exports.ElasticsearchTransport = ElasticsearchTransport;
+exports.EmailAlertPlugin = EmailAlertPlugin;
 exports.FileTransport = FileTransport;
+exports.FunctionPlugin = FunctionPlugin;
+exports.GENESIS_HASH = GENESIS_HASH;
 exports.HTTPTransport = HTTPTransport;
 exports.JSONFormatter = JSONFormatter;
 exports.KafkaTransport = KafkaTransport;
@@ -1435,6 +1850,8 @@ exports.Logger = Logger;
 exports.MongoDBTransport = MongoDBTransport;
 exports.MySQLTransport = MySQLTransport;
 exports.NewRelicTransport = NewRelicTransport;
+exports.PIIRedactPlugin = PIIRedactPlugin;
+exports.PagerDutyAlertPlugin = PagerDutyAlertPlugin;
 exports.PostgresTransport = PostgresTransport;
 exports.PubSubTransport = PubSubTransport;
 exports.RabbitMQTransport = RabbitMQTransport;
@@ -1443,6 +1860,8 @@ exports.RedisTransport = RedisTransport;
 exports.SQLiteTransport = SQLiteTransport;
 exports.SQSTransport = SQSTransport;
 exports.SamplingPlugin = SamplingPlugin;
+exports.SlackAlertPlugin = SlackAlertPlugin;
+exports.TamperEvidentPlugin = TamperEvidentPlugin;
 exports.Transport = Transport;
 exports.VERSION = VERSION;
 exports.createRecord = createRecord;