logixia 2.0.0 → 2.0.6

package/dist/{gcp.transport-CHV8MGgz.js → gcp.transport-Dy2Lf8FI.js}

@@ -1,12 +1,43 @@
-const require_chunk = require('./chunk-nOFOJqeH.js');
-const require_internal_log = require('./internal-log-BUJYMZbE.js');
-const require_safe_stringify = require('./safe-stringify-DWo3aZp_.js');
-const require_batch_buffer = require('./batch-buffer-BY-mRWIK.js');
-const require_entry_fields = require('./entry-fields-BvOLFlJ4.js');
+const require_secret_config = require("./secret-config-CmK2wVkr.js");
+const require_internal_log = require("./internal-log-By4Govmu.js");
+const require_safe_stringify = require("./safe-stringify-J3sh-7YM.js");
+const require_entry_fields = require("./entry-fields-BSLkzw18.js");
+const require_batch_buffer = require("./batch-buffer-C7Am4Mw-.js");
 let node_https = require("node:https");
-node_https = require_chunk.__toESM(node_https);
-
-//#region src/transports/gcp.transport.ts
+node_https = require_secret_config.__toESM(node_https);
+// src/transports/gcp.transport.ts
+/**
+* logixia — Google Cloud Logging (Stackdriver) transport
+*
+* Maps logixia log entries to the GCP Logging REST API format:
+*   - Maps `level` → `severity` (INFO, WARNING, ERROR, CRITICAL…)
+*   - Injects `logging.googleapis.com/trace` for Cloud Trace correlation
+*   - Sets `traceSampled: true` whenever a trace id is present
+*     (`logging.googleapis.com/spanId` and `sourceLocation` are not populated)
+*   - Supports structured `jsonPayload` and plain `textPayload`
+*
+* Auth: the metadata server on GCE/GKE/Cloud Run, or a service-account key passed
+* as `credentials`. The `GOOGLE_APPLICATION_CREDENTIALS` key-file variable is not
+* read; full ADC is not supported.
+*
+* @example
+* ```ts
+* import { createLogger } from 'logixia';
+* import { GCPTransport } from 'logixia/gcp';
+*
+* const logger = createLogger({
+*   transports: {
+*     custom: [
+*       new GCPTransport({
+*         projectId: process.env.GOOGLE_CLOUD_PROJECT,
+*         logName: 'projects/my-project/logs/api',
+*         resource: { type: 'gce_instance', labels: { instance_id: '123' } },
+*       }),
+*     ],
+*   },
+* });
+* ```
+*/
 function toGcpSeverity(level) {
 	switch (level.toLowerCase()) {
 		case "trace":
@@ -31,6 +62,7 @@ var GCPTransport = class {
 		this.flushTimer = null;
 		this.accessToken = null;
 		this.tokenExpiry = 0;
+		require_secret_config.protectSecrets(this, ["credentials", "accessToken"]);
 		this.projectId = config.projectId ?? process.env["GOOGLE_CLOUD_PROJECT"] ?? process.env["GCLOUD_PROJECT"] ?? "unknown-project";
 		this.logName = config.logName ?? `projects/${this.projectId}/logs/logixia`;
 		this.resource = config.resource ?? { type: "global" };
@@ -38,12 +70,13 @@ var GCPTransport = class {
 		this.batchSize = config.batchSize ?? 200;
 		this.flushInterval = config.flushIntervalMs ?? 5e3;
 		this.level = config.level;
-		this.requestTimeoutMs = config.requestTimeoutMs ?? require_batch_buffer.DEFAULT_REQUEST_TIMEOUT_MS;
+		this.requestTimeoutMs = config.requestTimeoutMs ?? 1e4;
 		this.buffer = new require_batch_buffer.BatchBuffer({
 			name: "GCPTransport",
 			batchSize: this.batchSize,
-			maxBufferSize: config.maxBufferSize ?? require_batch_buffer.DEFAULT_MAX_BUFFER_SIZE,
-			send: (entries) => this.writeEntries(entries)
+			maxBufferSize: config.maxBufferSize ?? 1e4,
+			send: (entries) => this.writeEntries(entries),
+			secrets: () => this.secretValues()
 		});
 		this.flushTimer = setInterval(() => {
 			this.flush().catch(() => {});
@@ -93,7 +126,7 @@ var GCPTransport = class {
 			const token = await this.fetchFromMetadataServer();
 			if (token) {
 				this.accessToken = token;
-				this.tokenExpiry = Date.now() + 3300 * 1e3;
+				this.tokenExpiry = Date.now() + 33e5;
 				return this.accessToken;
 			}
 		} catch {}
@@ -101,7 +134,7 @@ var GCPTransport = class {
 			const token = await this.fetchServiceAccountToken();
 			if (token) {
 				this.accessToken = token;
-				this.tokenExpiry = Date.now() + 3300 * 1e3;
+				this.tokenExpiry = Date.now() + 33e5;
 				return this.accessToken;
 			}
 		} catch (err) {
@@ -167,6 +200,15 @@ var GCPTransport = class {
 			label: "GCP token request"
 		}).then((res) => JSON.parse(res.body).access_token ?? null, () => null);
 	}
+	secretValues(token) {
+		var _this$credentials, _this$credentials2;
+		return [
+			...((_this$credentials = this.credentials) === null || _this$credentials === void 0 ? void 0 : _this$credentials.private_key.split("\n")) ?? [],
+			(_this$credentials2 = this.credentials) === null || _this$credentials2 === void 0 ? void 0 : _this$credentials2.private_key,
+			this.accessToken ?? void 0,
+			token
+		];
+	}
 	async writeEntries(entries) {
 		const token = await this.getAccessToken();
 		if (!token) throw new Error("GCPTransport: no access token available");
@@ -183,16 +225,16 @@ var GCPTransport = class {
 			},
 			body,
 			timeoutMs: this.requestTimeoutMs,
-			label: "GCP Logging API"
+			label: "GCP Logging API",
+			secrets: () => this.secretValues(token)
 		});
 	}
 };
-
-//#endregion
-Object.defineProperty(exports, 'GCPTransport', {
-  enumerable: true,
-  get: function () {
-    return GCPTransport;
-  }
+Object.defineProperty(exports, "GCPTransport", {
+	enumerable: true,
+	get: function() {
+		return GCPTransport;
+	}
 });
-//# sourceMappingURL=gcp.transport-CHV8MGgz.js.map
+
+//# sourceMappingURL=gcp.transport-Dy2Lf8FI.js.map

package/dist/gcp.transport-Dy2Lf8FI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp.transport-Dy2Lf8FI.js","names":["BatchBuffer","mergeCoreFields","https","httpRequest","stringifyForLog"],"sources":["../src/transports/gcp.transport.ts"],"sourcesContent":["/**\n * logixia — Google Cloud Logging (Stackdriver) transport\n *\n * Maps logixia log entries to the GCP Logging REST API format:\n *   - Maps `level` → `severity` (INFO, WARNING, ERROR, CRITICAL…)\n *   - Injects `logging.googleapis.com/trace` for Cloud Trace correlation\n *   - Sets `traceSampled: true` whenever a trace id is present\n *     (`logging.googleapis.com/spanId` and `sourceLocation` are not populated)\n *   - Supports structured `jsonPayload` and plain `textPayload`\n *\n * Auth: the metadata server on GCE/GKE/Cloud Run, or a service-account key passed\n * as `credentials`. The `GOOGLE_APPLICATION_CREDENTIALS` key-file variable is not\n * read; full ADC is not supported.\n *\n * @example\n * ```ts\n * import { createLogger } from 'logixia';\n * import { GCPTransport } from 'logixia/gcp';\n *\n * const logger = createLogger({\n *   transports: {\n *     custom: [\n *       new GCPTransport({\n *         projectId: process.env.GOOGLE_CLOUD_PROJECT,\n *         logName: 'projects/my-project/logs/api',\n *         resource: { type: 'gce_instance', labels: { instance_id: '123' } },\n *       }),\n *     ],\n *   },\n * });\n * ```\n */\n\nimport * as https from 'node:https';\n\nimport type { IAsyncTransport, TransportLogEntry } from '../types/transport.types';\nimport { internalError } from '../utils/internal-log';\nimport { stringifyForLog } from '../utils/safe-stringify';\nimport {\n  BatchBuffer,\n  DEFAULT_MAX_BUFFER_SIZE,\n  DEFAULT_REQUEST_TIMEOUT_MS,\n  httpRequest,\n} from './batch-buffer';\nimport { mergeCoreFields } from './entry-fields';\nimport { protectSecrets } from './secret-config';\n\nexport interface GCPMonitoredResource {\n  type: string;\n  labels?: Record<string, string>;\n}\n\nexport interface GCPTransportConfig {\n  /** GCP project ID. Falls back to `GOOGLE_CLOUD_PROJECT` or `GCLOUD_PROJECT` env vars. */\n  projectId?: string;\n  /**\n   * Full log name, e.g. `'projects/my-project/logs/api'`.\n   * If omitted, defaults to `projects/{projectId}/logs/logixia`.\n   */\n  logName?: string;\n  /** Monitored resource descriptor. Defaults to `global`. */\n  resource?: GCPMonitoredResource;\n  /**\n   * Service account key JSON (parsed). If omitted, only the metadata server\n   * (GCE/GKE/Cloud Run) is tried; the key-file env var is not read.\n   */\n  credentials?: {\n    client_email: string;\n    private_key: string;\n  };\n  /** Number of entries to batch. @default 200 */\n  batchSize?: number;\n  /** Flush interval in ms. @default 5000 */\n  flushIntervalMs?: number;\n  /** Abort a request that has not finished after this many ms. @default 10000 */\n  requestTimeoutMs?: number;\n  /** Max buffered entries; the oldest are dropped past this. @default 10000 */\n  maxBufferSize?: number;\n  level?: string;\n}\n\ntype GcpSeverity =\n  | 'DEFAULT'\n  | 'DEBUG'\n  | 'INFO'\n  | 'NOTICE'\n  | 'WARNING'\n  | 'ERROR'\n  | 'CRITICAL'\n  | 'ALERT'\n  | 'EMERGENCY';\n\nfunction toGcpSeverity(level: string): GcpSeverity {\n  switch (level.toLowerCase()) {\n    case 'trace':\n    case 'verbose':\n    case 'debug':\n      return 'DEBUG';\n    case 'info':\n    case 'log':\n      return 'INFO';\n    case 'warn':\n    case 'warning':\n      return 'WARNING';\n    case 'error':\n      return 'ERROR';\n    case 'critical':\n    case 'fatal':\n      return 'CRITICAL';\n    default:\n      return 'DEFAULT';\n  }\n}\n\n/**\n * Google Cloud Logging transport with trace correlation and GCP severity mapping.\n */\nexport class GCPTransport implements IAsyncTransport {\n  public readonly name = 'gcp';\n  public readonly batchSize: number;\n  public readonly flushInterval: number;\n  public readonly level: string | undefined;\n\n  private readonly buffer: BatchBuffer<TransportLogEntry>;\n  private readonly requestTimeoutMs: number;\n  private flushTimer: NodeJS.Timeout | null = null;\n  private accessToken: string | null = null;\n  private tokenExpiry = 0;\n\n  private readonly projectId: string;\n  private readonly logName: string;\n  private readonly resource: GCPMonitoredResource;\n  private readonly credentials: { client_email: string; private_key: string } | undefined;\n\n  constructor(config: GCPTransportConfig) {\n    protectSecrets(this, ['credentials', 'accessToken']);\n    this.projectId =\n      config.projectId ??\n      process.env['GOOGLE_CLOUD_PROJECT'] ??\n      process.env['GCLOUD_PROJECT'] ??\n      'unknown-project';\n    this.logName = config.logName ?? `projects/${this.projectId}/logs/logixia`;\n    this.resource = config.resource ?? { type: 'global' };\n    this.credentials = config.credentials;\n    this.batchSize = config.batchSize ?? 200;\n    this.flushInterval = config.flushIntervalMs ?? 5000;\n    this.level = config.level;\n    this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;\n    this.buffer = new BatchBuffer<TransportLogEntry>({\n      name: 'GCPTransport',\n      batchSize: this.batchSize,\n      maxBufferSize: config.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE,\n      send: (entries) => this.writeEntries(entries),\n      secrets: () => this.secretValues(),\n    });\n\n    this.flushTimer = setInterval(() => {\n      this.flush().catch(() => {});\n    }, this.flushInterval);\n    if (this.flushTimer.unref) this.flushTimer.unref();\n  }\n\n  write(entry: TransportLogEntry): void {\n    this.buffer.push(entry);\n    this.buffer.flushIfFull();\n  }\n\n  flush(): Promise<void> {\n    return this.buffer.flush();\n  }\n\n  /**\n   * Flush remaining entries and stop the interval timer on shutdown. Without\n   * this the manager's close() skipped the transport (close was undefined) and\n   * buffered entries were lost on deploy. Waits for any in-flight send first.\n   */\n  async close(): Promise<void> {\n    if (this.flushTimer) {\n      clearInterval(this.flushTimer);\n      this.flushTimer = null;\n    }\n    await this.buffer.close();\n  }\n\n  private buildLogEntry(entry: TransportLogEntry): Record<string, unknown> {\n    const gcpEntry: Record<string, unknown> = {\n      logName: this.logName,\n      resource: this.resource,\n      severity: toGcpSeverity(entry.level),\n      timestamp: entry.timestamp ?? new Date().toISOString(),\n      jsonPayload: mergeCoreFields(\n        { message: entry.message, appName: entry.appName, context: entry.context },\n        entry.data\n      ),\n    };\n\n    // GCP Cloud Trace correlation\n    if (entry.traceId) {\n      gcpEntry['trace'] = `projects/${this.projectId}/traces/${entry.traceId}`;\n      gcpEntry['traceSampled'] = true;\n    }\n\n    return gcpEntry;\n  }\n\n  private async getAccessToken(): Promise<string | null> {\n    if (this.accessToken && Date.now() < this.tokenExpiry) return this.accessToken;\n\n    // Try ADC metadata server (GCE/GKE/Cloud Run)\n    try {\n      const token = await this.fetchFromMetadataServer();\n      if (token) {\n        this.accessToken = token;\n        this.tokenExpiry = Date.now() + 55 * 60 * 1000; // 55 minutes\n        return this.accessToken;\n      }\n    } catch {\n      /* fall through to service account */\n    }\n\n    // Try service account key\n    if (this.credentials) {\n      try {\n        const token = await this.fetchServiceAccountToken();\n        if (token) {\n          this.accessToken = token;\n          this.tokenExpiry = Date.now() + 55 * 60 * 1000;\n          return this.accessToken;\n        }\n      } catch (err) {\n        internalError('GCPTransport service account token error', err);\n      }\n    }\n\n    return null;\n  }\n\n  private fetchFromMetadataServer(): Promise<string | null> {\n    return new Promise((resolve, reject) => {\n      const req = https.request(\n        {\n          hostname: 'metadata.google.internal',\n          path: '/computeMetadata/v1/instance/service-accounts/default/token',\n          headers: { 'Metadata-Flavor': 'Google' },\n          timeout: 3000,\n        },\n        (res) => {\n          let raw = '';\n          res.on('data', (c: Buffer) => (raw += c.toString()));\n          res.on('end', () => {\n            if (res.statusCode === 200) {\n              try {\n                const parsed = JSON.parse(raw) as { access_token?: string };\n                resolve(parsed.access_token ?? null);\n              } catch {\n                resolve(null);\n              }\n            } else {\n              resolve(null);\n            }\n          });\n        }\n      );\n      req.on('error', reject);\n      req.on('timeout', () => {\n        req.destroy();\n        reject(new Error('metadata timeout'));\n      });\n      req.end();\n    });\n  }\n\n  private fetchServiceAccountToken(): Promise<string | null> {\n    // Minimal JWT creation for service account — only for environments without\n    // the full Google Auth Library. For production workloads, prefer ADC.\n    if (!this.credentials) return Promise.resolve(null);\n\n    const iat = Math.floor(Date.now() / 1000);\n    const exp = iat + 3600;\n    const scope = 'https://www.googleapis.com/auth/logging.write';\n\n    const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');\n    const payload = Buffer.from(\n      JSON.stringify({\n        iss: this.credentials.client_email,\n        scope,\n        aud: 'https://oauth2.googleapis.com/token',\n        exp,\n        iat,\n      })\n    ).toString('base64url');\n\n    const signingInput = `${header}.${payload}`;\n\n    let signature: string;\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-require-imports\n      const sign = require('node:crypto').createSign('RSA-SHA256');\n      sign.update(signingInput);\n      signature = sign.sign(this.credentials.private_key, 'base64url') as string;\n    } catch {\n      return Promise.resolve(null);\n    }\n\n    const jwt = `${signingInput}.${signature}`;\n    const body = `grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=${jwt}`;\n\n    return httpRequest({\n      url: new URL('https://oauth2.googleapis.com/token'),\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n      body,\n      timeoutMs: this.requestTimeoutMs,\n      label: 'GCP token request',\n    }).then(\n      (res) => (JSON.parse(res.body) as { access_token?: string }).access_token ?? null,\n      () => null\n    );\n  }\n\n  private secretValues(token?: string): (string | undefined)[] {\n    return [\n      ...(this.credentials?.private_key.split('\\n') ?? []),\n      this.credentials?.private_key,\n      this.accessToken ?? undefined,\n      token,\n    ];\n  }\n\n  private async writeEntries(entries: TransportLogEntry[]): Promise<void> {\n    const token = await this.getAccessToken();\n    if (!token) {\n      throw new Error('GCPTransport: no access token available');\n    }\n\n    const body = stringifyForLog({\n      logName: this.logName,\n      resource: this.resource,\n      entries: entries.map((e) => this.buildLogEntry(e)),\n    });\n\n    await httpRequest({\n      url: new URL('https://logging.googleapis.com/v2/entries:write'),\n      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },\n      body,\n      timeoutMs: this.requestTimeoutMs,\n      label: 'GCP Logging API',\n      secrets: () => this.secretValues(token),\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/http-shapes-BnBkJcid.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Structural request/response shapes shared by every framework helper, so Express,
+ * Fastify and Node `http` objects are accepted without importing their types. Every
+ * optional member also accepts `undefined`, which keeps `exactOptionalPropertyTypes`
+ * consumers compiling against real framework types.
+ */
+/** Minimal request shape that Express, Fastify and Node `IncomingMessage` satisfy. */
+interface HttpRequestShape {
+  method?: string | undefined;
+  url?: string | undefined;
+  originalUrl?: string | undefined;
+  headers?: Record<string, string | string[] | undefined> | undefined;
+  body?: unknown;
+  ip?: string | undefined;
+  id?: unknown;
+  socket?: {
+    remoteAddress?: string | undefined;
+  } | undefined;
+}
+/** Minimal response shape that Express, Fastify replies and Node `ServerResponse` satisfy. */
+interface HttpResponseShape {
+  statusCode?: number | undefined;
+  on?: ((event: string, cb: () => void) => void) | undefined;
+  once?: ((event: string, cb: () => void) => void) | undefined;
+  getHeader?: ((name: string) => string | number | string[] | undefined) | undefined;
+  /** Express / Node `res.setHeader`. */
+  setHeader?: ((name: string, value: string) => unknown) | undefined;
+  /** Fastify `reply.header`. */
+  header?: ((name: string, value: string) => unknown) | undefined;
+}
+export { HttpResponseShape as n, HttpRequestShape as t };
+//# sourceMappingURL=http-shapes-BnBkJcid.d.mts.map

package/dist/http-shapes-BnBkJcid.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-shapes-BnBkJcid.d.mts","names":[],"sources":["../src/types/http-shapes.ts"],"mappings":";;;;;;;UAQiB;EACf;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA;IAAW;;;;UAII;EACf;EACA,OAAO,eAAe;EACtB,SAAS,eAAe;EACxB,cAAc;;EAEd,cAAc,cAAc;;EAE5B,WAAW,cAAc"}

package/dist/http-shapes-BnBkJcid.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Structural request/response shapes shared by every framework helper, so Express,
+ * Fastify and Node `http` objects are accepted without importing their types. Every
+ * optional member also accepts `undefined`, which keeps `exactOptionalPropertyTypes`
+ * consumers compiling against real framework types.
+ */
+/** Minimal request shape that Express, Fastify and Node `IncomingMessage` satisfy. */
+interface HttpRequestShape {
+  method?: string | undefined;
+  url?: string | undefined;
+  originalUrl?: string | undefined;
+  headers?: Record<string, string | string[] | undefined> | undefined;
+  body?: unknown;
+  ip?: string | undefined;
+  id?: unknown;
+  socket?: {
+    remoteAddress?: string | undefined;
+  } | undefined;
+}
+/** Minimal response shape that Express, Fastify replies and Node `ServerResponse` satisfy. */
+interface HttpResponseShape {
+  statusCode?: number | undefined;
+  on?: ((event: string, cb: () => void) => void) | undefined;
+  once?: ((event: string, cb: () => void) => void) | undefined;
+  getHeader?: ((name: string) => string | number | string[] | undefined) | undefined;
+  /** Express / Node `res.setHeader`. */
+  setHeader?: ((name: string, value: string) => unknown) | undefined;
+  /** Fastify `reply.header`. */
+  header?: ((name: string, value: string) => unknown) | undefined;
+}
+export { HttpResponseShape as n, HttpRequestShape as t };
+//# sourceMappingURL=http-shapes-BnBkJcid.d.ts.map

package/dist/http-shapes-BnBkJcid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-shapes-BnBkJcid.d.ts","names":[],"sources":["../src/types/http-shapes.ts"],"mappings":";;;;;;;UAQiB;EACf;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA;IAAW;;;;UAII;EACf;EACA,OAAO,eAAe;EACtB,SAAS,eAAe;EACxB,cAAc;;EAEd,cAAc,cAAc;;EAE5B,WAAW,cAAc"}

package/dist/{index-3mw5gaCw.d.mts → index-BSTtFcQ6.d.mts}

@@ -1,6 +1,100 @@
-import { f as TransportConfig } from "./transport.types-BMnurPcc.mjs";
-
-//#region src/types/http.types.d.ts
+import { h as TransportConfig } from "./transport.types-CzJq4IrF.mjs";
+interface LogixiaPlugin {
+  /**
+   * Unique plugin name.
+   * logixia uses this to prevent duplicate registration of the same plugin
+   * on the same logger instance.
+   */
+  name: string;
+  /**
+   * Called once immediately after `logger.use(plugin)` is called.
+   * Use for one-time setup (open connections, allocate buffers, etc.).
+   * Async `onInit` errors are silently swallowed to avoid blocking the logger.
+   */
+  onInit?(): void | Promise<void>;
+  /**
+   * Called for every log entry **after** PII redaction and **before** transport
+   * dispatch. Plugins run in registration order; each receives the (possibly
+   * modified) output of the previous plugin.
+   *
+   * - Return the entry (modified or unchanged) to continue processing.
+   * - Return `null` to **drop** the entry — no transport will receive it.
+   *
+   * Errors thrown inside `onLog` are swallowed so a buggy plugin cannot crash
+   * logging; the chain continues with the previous (un-transformed) entry.
+   */
+  onLog?(entry: LogEntry): LogEntry | null | Promise<LogEntry | null>;
+  /**
+   * Called when a transport write fails (after any configured retries).
+   * Useful for routing transport errors to an alerting or metrics system.
+   * Errors thrown inside `onError` are silently swallowed.
+   */
+  onError?(error: Error, entry?: LogEntry): void | Promise<void>;
+  /**
+   * Called when the logger is closed via `logger.close()` or the process
+   * receives a shutdown signal (when `gracefulShutdown` is enabled).
+   * Errors thrown inside `onShutdown` are silently swallowed.
+   */
+  onShutdown?(): void | Promise<void>;
+}
+/**
+ * Holds an ordered list of `LogixiaPlugin` instances and dispatches lifecycle
+ * events to them. One registry is created per logger instance; a global
+ * singleton is also exported for process-wide registration.
+ */
+declare class PluginRegistry {
+  private readonly _plugins;
+  /**
+   * Register a plugin. Silently skips if a plugin with the same `name` is
+   * already registered on this registry.
+   */
+  register(plugin: LogixiaPlugin): void;
+  /** Remove a previously registered plugin by name. No-op if not found. */
+  unregister(name: string): void;
+  /** Returns `true` if a plugin with the given name is registered. */
+  has(name: string): boolean;
+  /** Number of currently registered plugins. */
+  get size(): number;
+  /**
+   * Run all `onLog` hooks in order.
+   * Returns `null` if any plugin cancels the entry; otherwise returns the
+   * (possibly transformed) entry.
+   */
+  runOnLog(entry: LogEntry): Promise<LogEntry | null>;
+  /**
+   * Notify all `onError` hooks.
+   * Errors thrown inside hooks are swallowed to prevent error cascades.
+   */
+  runOnError(error: Error, entry?: LogEntry): Promise<void>;
+  /** Run all `onShutdown` hooks concurrently. Hook errors are swallowed. */
+  runOnShutdown(): Promise<void>;
+}
+/**
+ * Module-level singleton registry.
+ *
+ * Plugins registered here are automatically copied into every **new** logger
+ * instance created after the registration. Already-created loggers are not
+ * retroactively affected — use `logger.use(plugin)` for per-instance control.
+ */
+declare const globalPluginRegistry: PluginRegistry;
+/**
+ * Register a plugin in the global registry so it applies to every future
+ * logger instance.
+ *
+ * @example
+ * ```ts
+ * import { usePlugin } from 'logixia';
+ *
+ * usePlugin({
+ *   name: 'audit-sink',
+ *   onLog(entry) {
+ *     if (entry.level === 'error') auditQueue.push(entry);
+ *     return entry;
+ *   },
+ * });
+ * ```
+ */
+declare function usePlugin(plugin: LogixiaPlugin): void;
 /**
  * HTTP-related type definitions for Logixia
  */
@@ -50,8 +144,6 @@ interface RequestMetrics {
   ip?: string;
   timestamp: number;
 }
-//#endregion
-//#region src/types/index.d.ts
 declare const LogLevel: {
   readonly ERROR: "error";
   readonly WARN: "warn";
@@ -296,7 +388,9 @@ interface IBaseLogger {
   time(label: string): void;
   timeEnd(label: string): Promise<number | undefined>;
   timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+  /** Set the minimum log level at runtime. Unknown levels are ignored with a warning. */
   setLevel(level: LogLevel | string): void;
+  /** Return the configured minimum log level (not the per-namespace effective one). */
   getLevel(): string;
   setContext(context: string): void;
   getContext(): string | undefined;
@@ -315,17 +409,53 @@ interface IBaseLogger {
   getAvailableTransports(): string[];
   child(context: string, data?: Record<string, unknown>): ILogger;
   close(): Promise<void>;
-  use(plugin: {
-    name: string;
-  }): this;
+  use(plugin: LogixiaPlugin): this;
   unuse(pluginName: string): this;
 }
-type CustomLevelMethods<T extends Record<string, number>> = { [K in keyof T]: (message: string, data?: Record<string, unknown>) => Promise<void> };
+/**
+ * Runtime controls implemented by loggers returned from `createLogger`.
+ * Kept separate from {@link IBaseLogger} and {@link ILogger}, so existing
+ * implementations of those (mocks, adapters) keep compiling.
+ */
+interface ILoggerRuntimeControls {
+  /**
+   * Replace the per-namespace level map at runtime.
+   * @example logger.setNamespaceLevels({ 'db.*': 'debug', '*': 'info' });
+   */
+  setNamespaceLevels(levels: NamespaceLevels): void;
+  /** Merge entries into the existing per-namespace level map at runtime. */
+  patchNamespaceLevels(levels: NamespaceLevels): void;
+  /** Return a copy of the current per-namespace level map. */
+  getNamespaceLevels(): NamespaceLevels;
+  /** Flush buffered entries in all transports without closing them. */
+  flush(): Promise<void>;
+  /** Report whether the transports are healthy. */
+  healthCheck(): Promise<{
+    healthy: boolean;
+    details: Record<string, unknown>;
+  }>;
+}
+/**
+ * Logger member names a custom level must not use: a level with one of these
+ * names would shadow, or be shadowed by, a built-in logger method. The built-in
+ * level methods (`error`, `warn`, `info`, `debug`, `trace`, `verbose`) are valid level names.
+ */
+type ReservedLevelName = Exclude<keyof IBaseLogger | keyof ILoggerRuntimeControls, 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'verbose'>;
+type CustomLevelMethods<T extends Record<string, number>> = { [K in keyof T as K extends ReservedLevelName ? never : K]: (message: string, data?: Record<string, unknown>) => Promise<void>; };
 type ILogger<TLevels extends Record<string, number> = {}> = IBaseLogger & CustomLevelMethods<TLevels>;
 interface ILoggerDefault extends IBaseLogger {}
+/** What `createLogger` returns for a config with custom levels: the logger plus its runtime controls. */
+type LogixiaLoggerInstance<TLevels extends Record<string, number> = {}> = {
+  /** Child loggers carry the runtime controls too. */
+  child(context: string, data?: Record<string, unknown>): LogixiaLoggerInstance<TLevels>;
+} & ILogger<TLevels> & ILoggerRuntimeControls;
+/** What `createLogger` returns for a config without custom levels. */
+interface LogixiaLoggerDefault extends ILoggerDefault, ILoggerRuntimeControls {
+  child(context: string, data?: Record<string, unknown>): LogixiaLoggerDefault;
+}
 type LoggerWithLevels<T extends LoggerConfig<any>> = T['levelOptions'] extends {
   levels: infer L;
-} ? L extends Record<string, number> ? ILogger<L> : ILoggerDefault : ILoggerDefault;
+} ? L extends Record<string, number> ? LogixiaLoggerInstance<L> : LogixiaLoggerDefault : LogixiaLoggerDefault;
 type ExtractLevels<T> = T extends LoggerConfig<infer L> ? L : Record<string, number>;
 interface LogEntry {
   timestamp: string;
@@ -384,6 +514,5 @@ declare const DEFAULT_LOG_COLORS: {
   trace: string;
   verbose: string;
 };
-//#endregion
-export { HttpResponse as A, RequestContext as C, TraceIdExtractorConfig as D, TraceIdConfig as E, RequestTiming as M, HttpError as O, RedactConfig as S, TimingEntry as T, LogLevel as _, DEFAULT_LOG_LEVELS as a, LoggerWithLevels as b, ExtractLevels as c, ILogFormatter as d, ILogger as f, LogFieldKey as g, LogEntry as h, DEFAULT_LOG_COLORS as i, RequestMetrics as j, HttpRequest as k, GracefulShutdownConfig as l, LogColor as m, ContextData as n, Environment as o, ILoggerDefault as p, CustomLevelMethods as r, ErrorSerializationOptions as s, AdaptiveSamplingConfig as t, IBaseLogger as u, LogLevelString as v, SamplingConfig as w, NamespaceLevels as x, LoggerConfig as y };
-//# sourceMappingURL=index-3mw5gaCw.d.mts.map
+export { TraceIdConfig as A, usePlugin as B, LogixiaLoggerInstance as C, ReservedLevelName as D, RequestContext as E, RequestMetrics as F, RequestTiming as I, LogixiaPlugin as L, HttpError as M, HttpRequest as N, SamplingConfig as O, HttpResponse as P, PluginRegistry as R, LogixiaLoggerDefault as S, RedactConfig as T, LogFieldKey as _, DEFAULT_LOG_LEVELS as a, LoggerConfig as b, ExtractLevels as c, ILogFormatter as d, ILogger as f, LogEntry as g, LogColor as h, DEFAULT_LOG_COLORS as i, TraceIdExtractorConfig as j, TimingEntry as k, GracefulShutdownConfig as l, ILoggerRuntimeControls as m, ContextData as n, Environment as o, ILoggerDefault as p, CustomLevelMethods as r, ErrorSerializationOptions as s, AdaptiveSamplingConfig as t, IBaseLogger as u, LogLevel as v, NamespaceLevels as w, LoggerWithLevels as x, LogLevelString as y, globalPluginRegistry as z };
+//# sourceMappingURL=index-BSTtFcQ6.d.mts.map

package/dist/index-BSTtFcQ6.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BSTtFcQ6.d.mts","names":[],"sources":["../src/plugin.ts","../src/types/http.types.ts","../src/types/index.ts"],"mappings":"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"}

package/dist/{index-DhIoploR.d.ts → index-CFDGkI8n.d.ts}

@@ -1,6 +1,100 @@
-import { f as TransportConfig } from "./transport.types-CGoHpWQR.js";
-
-//#region src/types/http.types.d.ts
+import { h as TransportConfig } from "./transport.types-CzJq4IrF.js";
+interface LogixiaPlugin {
+  /**
+   * Unique plugin name.
+   * logixia uses this to prevent duplicate registration of the same plugin
+   * on the same logger instance.
+   */
+  name: string;
+  /**
+   * Called once immediately after `logger.use(plugin)` is called.
+   * Use for one-time setup (open connections, allocate buffers, etc.).
+   * Async `onInit` errors are silently swallowed to avoid blocking the logger.
+   */
+  onInit?(): void | Promise<void>;
+  /**
+   * Called for every log entry **after** PII redaction and **before** transport
+   * dispatch. Plugins run in registration order; each receives the (possibly
+   * modified) output of the previous plugin.
+   *
+   * - Return the entry (modified or unchanged) to continue processing.
+   * - Return `null` to **drop** the entry — no transport will receive it.
+   *
+   * Errors thrown inside `onLog` are swallowed so a buggy plugin cannot crash
+   * logging; the chain continues with the previous (un-transformed) entry.
+   */
+  onLog?(entry: LogEntry): LogEntry | null | Promise<LogEntry | null>;
+  /**
+   * Called when a transport write fails (after any configured retries).
+   * Useful for routing transport errors to an alerting or metrics system.
+   * Errors thrown inside `onError` are silently swallowed.
+   */
+  onError?(error: Error, entry?: LogEntry): void | Promise<void>;
+  /**
+   * Called when the logger is closed via `logger.close()` or the process
+   * receives a shutdown signal (when `gracefulShutdown` is enabled).
+   * Errors thrown inside `onShutdown` are silently swallowed.
+   */
+  onShutdown?(): void | Promise<void>;
+}
+/**
+ * Holds an ordered list of `LogixiaPlugin` instances and dispatches lifecycle
+ * events to them. One registry is created per logger instance; a global
+ * singleton is also exported for process-wide registration.
+ */
+declare class PluginRegistry {
+  private readonly _plugins;
+  /**
+   * Register a plugin. Silently skips if a plugin with the same `name` is
+   * already registered on this registry.
+   */
+  register(plugin: LogixiaPlugin): void;
+  /** Remove a previously registered plugin by name. No-op if not found. */
+  unregister(name: string): void;
+  /** Returns `true` if a plugin with the given name is registered. */
+  has(name: string): boolean;
+  /** Number of currently registered plugins. */
+  get size(): number;
+  /**
+   * Run all `onLog` hooks in order.
+   * Returns `null` if any plugin cancels the entry; otherwise returns the
+   * (possibly transformed) entry.
+   */
+  runOnLog(entry: LogEntry): Promise<LogEntry | null>;
+  /**
+   * Notify all `onError` hooks.
+   * Errors thrown inside hooks are swallowed to prevent error cascades.
+   */
+  runOnError(error: Error, entry?: LogEntry): Promise<void>;
+  /** Run all `onShutdown` hooks concurrently. Hook errors are swallowed. */
+  runOnShutdown(): Promise<void>;
+}
+/**
+ * Module-level singleton registry.
+ *
+ * Plugins registered here are automatically copied into every **new** logger
+ * instance created after the registration. Already-created loggers are not
+ * retroactively affected — use `logger.use(plugin)` for per-instance control.
+ */
+declare const globalPluginRegistry: PluginRegistry;
+/**
+ * Register a plugin in the global registry so it applies to every future
+ * logger instance.
+ *
+ * @example
+ * ```ts
+ * import { usePlugin } from 'logixia';
+ *
+ * usePlugin({
+ *   name: 'audit-sink',
+ *   onLog(entry) {
+ *     if (entry.level === 'error') auditQueue.push(entry);
+ *     return entry;
+ *   },
+ * });
+ * ```
+ */
+declare function usePlugin(plugin: LogixiaPlugin): void;
 /**
  * HTTP-related type definitions for Logixia
  */
@@ -50,8 +144,6 @@ interface RequestMetrics {
   ip?: string;
   timestamp: number;
 }
-//#endregion
-//#region src/types/index.d.ts
 declare const LogLevel: {
   readonly ERROR: "error";
   readonly WARN: "warn";
@@ -296,7 +388,9 @@ interface IBaseLogger {
   time(label: string): void;
   timeEnd(label: string): Promise<number | undefined>;
   timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+  /** Set the minimum log level at runtime. Unknown levels are ignored with a warning. */
   setLevel(level: LogLevel | string): void;
+  /** Return the configured minimum log level (not the per-namespace effective one). */
   getLevel(): string;
   setContext(context: string): void;
   getContext(): string | undefined;
@@ -315,17 +409,53 @@ interface IBaseLogger {
   getAvailableTransports(): string[];
   child(context: string, data?: Record<string, unknown>): ILogger;
   close(): Promise<void>;
-  use(plugin: {
-    name: string;
-  }): this;
+  use(plugin: LogixiaPlugin): this;
   unuse(pluginName: string): this;
 }
-type CustomLevelMethods<T extends Record<string, number>> = { [K in keyof T]: (message: string, data?: Record<string, unknown>) => Promise<void> };
+/**
+ * Runtime controls implemented by loggers returned from `createLogger`.
+ * Kept separate from {@link IBaseLogger} and {@link ILogger}, so existing
+ * implementations of those (mocks, adapters) keep compiling.
+ */
+interface ILoggerRuntimeControls {
+  /**
+   * Replace the per-namespace level map at runtime.
+   * @example logger.setNamespaceLevels({ 'db.*': 'debug', '*': 'info' });
+   */
+  setNamespaceLevels(levels: NamespaceLevels): void;
+  /** Merge entries into the existing per-namespace level map at runtime. */
+  patchNamespaceLevels(levels: NamespaceLevels): void;
+  /** Return a copy of the current per-namespace level map. */
+  getNamespaceLevels(): NamespaceLevels;
+  /** Flush buffered entries in all transports without closing them. */
+  flush(): Promise<void>;
+  /** Report whether the transports are healthy. */
+  healthCheck(): Promise<{
+    healthy: boolean;
+    details: Record<string, unknown>;
+  }>;
+}
+/**
+ * Logger member names a custom level must not use: a level with one of these
+ * names would shadow, or be shadowed by, a built-in logger method. The built-in
+ * level methods (`error`, `warn`, `info`, `debug`, `trace`, `verbose`) are valid level names.
+ */
+type ReservedLevelName = Exclude<keyof IBaseLogger | keyof ILoggerRuntimeControls, 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'verbose'>;
+type CustomLevelMethods<T extends Record<string, number>> = { [K in keyof T as K extends ReservedLevelName ? never : K]: (message: string, data?: Record<string, unknown>) => Promise<void>; };
 type ILogger<TLevels extends Record<string, number> = {}> = IBaseLogger & CustomLevelMethods<TLevels>;
 interface ILoggerDefault extends IBaseLogger {}
+/** What `createLogger` returns for a config with custom levels: the logger plus its runtime controls. */
+type LogixiaLoggerInstance<TLevels extends Record<string, number> = {}> = {
+  /** Child loggers carry the runtime controls too. */
+  child(context: string, data?: Record<string, unknown>): LogixiaLoggerInstance<TLevels>;
+} & ILogger<TLevels> & ILoggerRuntimeControls;
+/** What `createLogger` returns for a config without custom levels. */
+interface LogixiaLoggerDefault extends ILoggerDefault, ILoggerRuntimeControls {
+  child(context: string, data?: Record<string, unknown>): LogixiaLoggerDefault;
+}
 type LoggerWithLevels<T extends LoggerConfig<any>> = T['levelOptions'] extends {
   levels: infer L;
-} ? L extends Record<string, number> ? ILogger<L> : ILoggerDefault : ILoggerDefault;
+} ? L extends Record<string, number> ? LogixiaLoggerInstance<L> : LogixiaLoggerDefault : LogixiaLoggerDefault;
 type ExtractLevels<T> = T extends LoggerConfig<infer L> ? L : Record<string, number>;
 interface LogEntry {
   timestamp: string;
@@ -384,6 +514,5 @@ declare const DEFAULT_LOG_COLORS: {
   trace: string;
   verbose: string;
 };
-//#endregion
-export { HttpResponse as A, RequestContext as C, TraceIdExtractorConfig as D, TraceIdConfig as E, RequestTiming as M, HttpError as O, RedactConfig as S, TimingEntry as T, LogLevel as _, DEFAULT_LOG_LEVELS as a, LoggerWithLevels as b, ExtractLevels as c, ILogFormatter as d, ILogger as f, LogFieldKey as g, LogEntry as h, DEFAULT_LOG_COLORS as i, RequestMetrics as j, HttpRequest as k, GracefulShutdownConfig as l, LogColor as m, ContextData as n, Environment as o, ILoggerDefault as p, CustomLevelMethods as r, ErrorSerializationOptions as s, AdaptiveSamplingConfig as t, IBaseLogger as u, LogLevelString as v, SamplingConfig as w, NamespaceLevels as x, LoggerConfig as y };
-//# sourceMappingURL=index-DhIoploR.d.ts.map
+export { TraceIdConfig as A, usePlugin as B, LogixiaLoggerInstance as C, ReservedLevelName as D, RequestContext as E, RequestMetrics as F, RequestTiming as I, LogixiaPlugin as L, HttpError as M, HttpRequest as N, SamplingConfig as O, HttpResponse as P, PluginRegistry as R, LogixiaLoggerDefault as S, RedactConfig as T, LogFieldKey as _, DEFAULT_LOG_LEVELS as a, LoggerConfig as b, ExtractLevels as c, ILogFormatter as d, ILogger as f, LogEntry as g, LogColor as h, DEFAULT_LOG_COLORS as i, TraceIdExtractorConfig as j, TimingEntry as k, GracefulShutdownConfig as l, ILoggerRuntimeControls as m, ContextData as n, Environment as o, ILoggerDefault as p, CustomLevelMethods as r, ErrorSerializationOptions as s, AdaptiveSamplingConfig as t, IBaseLogger as u, LogLevel as v, NamespaceLevels as w, LoggerWithLevels as x, LogLevelString as y, globalPluginRegistry as z };
+//# sourceMappingURL=index-CFDGkI8n.d.ts.map

package/dist/index-CFDGkI8n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CFDGkI8n.d.ts","names":[],"sources":["../src/plugin.ts","../src/types/http.types.ts","../src/types/index.ts"],"mappings":"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"}