@bymax-one/nest-logger 1.0.0

package/dist/server/index.d.cts

@@ -0,0 +1,953 @@
+import * as _nestjs_common from '@nestjs/common';
+import { ModuleMetadata, Type, DynamicModule, INestApplication, LoggerService, OnApplicationShutdown, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler, MiddlewareConsumer, NestMiddleware, CustomDecorator } from '@nestjs/common';
+import { Logger } from 'pino';
+import { Observable } from 'rxjs';
+import { Request, Response, NextFunction } from 'express';
+
+/**
+ * Pino log levels (mirrored to NestJS-compatible names).
+ *
+ * Numeric mapping (Pino):
+ *   - `fatal` 60
+ *   - `error` 50
+ *   - `warn`  40
+ *   - `info`  30
+ *   - `debug` 20
+ *   - `trace` 10
+ *
+ * @example
+ *   const level: LogLevel = 'info'
+ */
+type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
+/**
+ * Pluggable destination contract for the logger.
+ *
+ * Layer: server/interfaces — implemented by every concrete sink
+ * (`DefaultStdoutDestination`, future HTTP / file / queue destinations).
+ * The library owns the JSON serialization; implementations only forward
+ * the already-encoded payload.
+ */
+
+/**
+ * Pluggable destination for log entries.
+ *
+ * Implementations receive the final JSON-serialized payload (with trailing
+ * newline) and write it wherever they want — file, network, queue, etc.
+ *
+ * Implementations MUST be non-blocking and tolerant to errors. A destination
+ * that throws or hangs MUST NOT break the application — the library's
+ * `DestinationRegistry` catches errors and emits a meta-log
+ * (`LOGGER_DESTINATION_WRITE_FAILED`).
+ *
+ * @example
+ *   class FileDestination implements ILogDestination {
+ *     readonly name = 'file'
+ *     write(payload: string): void {
+ *       fs.appendFileSync('/var/log/app.log', payload)
+ *     }
+ *   }
+ */
+interface ILogDestination {
+    /** Unique identifier — used in error logs and registry lookups. */
+    readonly name: string;
+    /**
+     * Minimum log level this destination accepts. Entries below this level
+     * are not written. Undefined means "accept everything".
+     */
+    readonly minLevel?: LogLevel;
+    /**
+     * Write a single log entry. Payload is the already-serialized JSON string
+     * (UTF-8, terminated with `\n`).
+     *
+     * Implementations may:
+     *   - Write synchronously (e.g., `process.stdout`)
+     *   - Buffer and flush periodically (e.g., HTTP batching)
+     *   - Return a Promise for async I/O
+     *
+     * Errors thrown here are caught by the library; the destination may be
+     * temporarily skipped if it consistently fails.
+     *
+     * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
+     */
+    write(payload: string): void | Promise<void>;
+    /**
+     * Optional lifecycle hook — called once during NestJS module init.
+     * Use for opening connections, allocating buffers, scheduling flushers.
+     */
+    onInit?(): void | Promise<void>;
+    /**
+     * Optional lifecycle hook — called during NestJS `onApplicationShutdown`.
+     * MUST flush any pending writes and close resources.
+     *
+     * The library awaits this — graceful shutdown blocks until all destinations
+     * return.
+     */
+    onShutdown?(): void | Promise<void>;
+}
+
+/**
+ * Service metadata propagated to every log entry.
+ *
+ * Aligned with OpenTelemetry semantic conventions for service identity:
+ *   {@link https://opentelemetry.io/docs/specs/semconv/resource/#service}
+ */
+interface ServiceMetadata {
+    /** OTel attribute `service.name` — stable identifier of the running service. */
+    readonly name: string;
+    /** OTel attribute `service.version` — semver, commit SHA, or build tag. */
+    readonly version: string;
+}
+
+/**
+ * Public module-options interfaces for `BymaxLoggerModule`.
+ *
+ * Layer: server/interfaces — the contracts consumed by `forRoot` /
+ * `forRootAsync` plus the nested `HttpOptions` / `OtelOptions` shapes and
+ * the async factory pair. The synchronous and asynchronous variants are
+ * intentionally separate types (not a union) so the dynamic-module helper
+ * can branch on shape without runtime discrimination.
+ */
+
+/**
+ * HTTP module configuration — used by the optional HTTP interceptor and filter.
+ *
+ * Every field is optional; defaults are applied by `applyDefaults`.
+ */
+interface HttpOptions {
+    /** Mount the HTTP interceptor + filter. Default: false. */
+    isEnabled?: boolean;
+    /** Capture unhandled HTTP exceptions and emit `HTTP_EXCEPTION_UNHANDLED`. Default: true. */
+    shouldCaptureExceptions?: boolean;
+    /** Generate `requestId` when the request header is absent. Default: true. */
+    shouldGenerateRequestId?: boolean;
+    /**
+     * Paths that bypass HTTP logging (health checks, metrics). Defaults:
+     * `/health`, `/metrics`.
+     *
+     * SECURITY: each pattern is `.test()`-ed against the (attacker-controllable)
+     * request path on every request. Supply only anchored, linear-time regexes
+     * (e.g. `/^\/health$/`); a pattern with catastrophic backtracking would turn a
+     * crafted URL into a ReDoS vector. The defaults are anchored and safe.
+     */
+    excludePaths?: readonly RegExp[];
+    /** Header name carrying the tenant identifier. Default: `x-tenant-id`. */
+    tenantIdHeader?: string;
+}
+/**
+ * OpenTelemetry integration tuning — applied by `TraceContextMixin` when the
+ * `@opentelemetry/api` peer dependency is installed.
+ */
+interface OtelOptions {
+    /** Inject the active span's trace/span IDs into every log entry. Default: true. */
+    shouldAutoInjectTraceContext?: boolean;
+    /**
+     * Shortcut that derives sensible defaults for `traceIdField` / `spanIdField` /
+     * `traceFlagsField` based on a target casing.
+     *
+     *   - `'camelCase'` (default) → `traceId` / `spanId` / `traceFlags`
+     *   - `'snake_case'`          → `trace_id` / `span_id` / `trace_flags`
+     *     (OTel Logs Data Model wire format)
+     *
+     * Individual `*Field` overrides ALWAYS win over the shortcut.
+     */
+    fieldFormat?: 'camelCase' | 'snake_case';
+    /** Override the field name for the trace ID. */
+    traceIdField?: string;
+    /** Override the field name for the span ID. */
+    spanIdField?: string;
+    /** Override the field name for the trace flags. */
+    traceFlagsField?: string;
+}
+/**
+ * Synchronous configuration for `BymaxLoggerModule.forRoot()`.
+ */
+interface BymaxLoggerModuleOptions {
+    /** Mandatory service metadata — emitted on every log entry. */
+    service: ServiceMetadata;
+    /** Minimum level emitted. Default: `info` in production, `debug` otherwise. */
+    level?: LogLevel;
+    /** Register the module as `@Global()`. Default: true. */
+    isGlobal?: boolean;
+    /**
+     * @deprecated Not read by the module — a module cannot call `app.useLogger()`
+     *   itself (it never sees the `INestApplication`). Call
+     *   `BymaxLoggerModule.useNestLogger(app)` in `main.ts` instead. Default: true.
+     */
+    shouldUseAsNestLogger?: boolean;
+    /** Additional Pino redact paths — merged with `DEFAULT_REDACT_PATHS`. */
+    redactPaths?: readonly string[];
+    /** Censor string written in place of redacted values. Default: `[REDACTED]`. */
+    redactCensor?: string;
+    /** Disable default redact paths (use with caution). Default: false. */
+    shouldDisableDefaultRedact?: boolean;
+    /** Custom destinations beyond `DefaultStdoutDestination`. */
+    destinations?: readonly ILogDestination[];
+    /**
+     * @deprecated Currently inert — a `true` value does not change output on its
+     *   own. For pretty local logs add `new PrettyDevDestination()` to
+     *   `destinations` (and install the optional `pino-pretty` peer dep).
+     *   Default: `NODE_ENV !== 'production'`.
+     */
+    isPretty?: boolean;
+    /** HTTP module configuration. */
+    http?: HttpOptions;
+    /** OpenTelemetry integration tuning. */
+    otel?: OtelOptions;
+    /** Maximum size in bytes per log entry. Default: 65536. */
+    maxEntrySizeBytes?: number;
+    /** Custom Pino serializers, merged with defaults. */
+    serializers?: Record<string, (input: unknown) => unknown>;
+    /** Custom timestamp function. Default: `() => new Date().toISOString()`. */
+    timestamp?: () => string;
+}
+/**
+ * Fully-resolved options after `applyDefaults` runs.
+ *
+ * Every optional field is filled, and the nested `http` / `otel` bags are
+ * deep-required because {@link applyDefaults} populates each of their fields.
+ * This is the precise shape every runtime layer (pino factory, services,
+ * middleware) consumes — distinct from the loosely-typed
+ * `BymaxLoggerModuleOptions` the consumer supplies.
+ */
+type ResolvedBymaxLoggerModuleOptions = Readonly<Required<Omit<BymaxLoggerModuleOptions, 'http' | 'otel'>> & {
+    http: Required<HttpOptions>;
+    otel: Required<OtelOptions>;
+}>;
+/**
+ * Factory interface used by `useExisting` / `useClass` async wiring.
+ *
+ * Implement this interface when the module options depend on providers that are
+ * already in the DI graph (e.g., a `ConfigService`). Pass the class to
+ * `forRootAsync({ useClass: MyFactory })` or the token to `useExisting`.
+ */
+interface BymaxLoggerModuleOptionsFactory {
+    /**
+     * Produce the synchronous or asynchronous module options.
+     *
+     * @returns Resolved or promised `BymaxLoggerModuleOptions`.
+     * @throws Any error thrown here propagates as a module-initialisation failure.
+     */
+    createLoggerOptions(): BymaxLoggerModuleOptions | Promise<BymaxLoggerModuleOptions>;
+}
+/**
+ * Asynchronous configuration for `BymaxLoggerModule.forRootAsync()`.
+ *
+ * Standard NestJS dynamic-module async-options shape — pick `imports` from
+ * `ModuleMetadata` to allow re-using the consumer's providers in the factory.
+ */
+interface BymaxLoggerModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    /**
+     * Factory producing the module options. The `unknown[]` parameter shape
+     * matches the heterogeneous `inject` array — NestJS resolves each token
+     * independently and passes the resolved providers as positional args, so a
+     * tighter generic would force every consumer to widen the signature with
+     * `as` casts at the call site.
+     */
+    useFactory?: (...args: unknown[]) => BymaxLoggerModuleOptions | Promise<BymaxLoggerModuleOptions>;
+    /** Provider tokens NestJS must resolve and forward to `useFactory`. */
+    inject?: readonly (string | symbol | Type<unknown>)[];
+    /** Reuse an existing factory provider already registered in the DI graph. */
+    useExisting?: Type<BymaxLoggerModuleOptionsFactory>;
+    /** Instantiate a factory class and call its `createLoggerOptions()`. */
+    useClass?: Type<BymaxLoggerModuleOptionsFactory>;
+}
+
+/** Extra (non-option) flags accepted by `forRoot` / `forRootAsync`. */
+interface BymaxLoggerModuleExtras {
+    /** Register the module globally. Default: `true`. */
+    isGlobal?: boolean;
+}
+/**
+ * `BymaxLoggerModuleBase` — base class providing the generated `forRoot` /
+ * `forRootAsync` implementations.
+ *
+ * `BUILDER_OPTIONS_TOKEN` — internal DI token for the raw (pre-defaulted)
+ * consumer options; not intended for injection outside this module.
+ *
+ * `OPTIONS_TYPE` / `ASYNC_OPTIONS_TYPE` — `typeof`-only sentinels used as
+ * parameter types in the static factory overrides; never instantiated at
+ * runtime.
+ */
+declare const BymaxLoggerModuleBase: _nestjs_common.ConfigurableModuleCls<BymaxLoggerModuleOptions, "forRoot", "createLoggerOptions", BymaxLoggerModuleExtras>;
+declare const OPTIONS_TYPE: BymaxLoggerModuleOptions & Partial<BymaxLoggerModuleExtras>;
+declare const ASYNC_OPTIONS_TYPE: _nestjs_common.ConfigurableModuleAsyncOptions<BymaxLoggerModuleOptions, "createLoggerOptions"> & Partial<BymaxLoggerModuleExtras>;
+
+declare class BymaxLoggerModule extends BymaxLoggerModuleBase {
+    /**
+     * Synchronous registration.
+     *
+     * @param options - Logger options (plus the `isGlobal` extra).
+     * @returns The configured `DynamicModule`.
+     * @throws Error When the options fail validation.
+     * @example
+     *   BymaxLoggerModule.forRoot({ service: { name: 'api', version: '1.0.0' } })
+     */
+    static forRoot(options: typeof OPTIONS_TYPE): DynamicModule;
+    /**
+     * Asynchronous registration. Options are resolved lazily via the consumer's
+     * factory (`useFactory` + `inject` + `imports`, `useClass`, or `useExisting`);
+     * the Pino instance and the bootstrap log are produced only after they
+     * resolve, never at module-decoration time.
+     *
+     * Note: the destination-registry `onModuleInit` lifecycle hook is managed by
+     * `DestinationRegistry` itself, not by this factory. The destinations array is
+     * registered under `LOGGER_DESTINATIONS_TOKEN`; no built-in destination defines
+     * an `onInit` hook, so nothing is lost.
+     *
+     * HTTP access logging IS supported on this path: the global interceptor slot
+     * is always registered and gated at runtime against the resolved
+     * `http.isEnabled` (see {@link asyncHttpInterceptorProvider}). The catch-all
+     * exception FILTER is intentionally NOT auto-wired here — registering a global
+     * `@Catch()` filter from async config would either interfere with a consumer's
+     * own filters (when disabled) or require unsafe re-throwing. Async consumers who
+     * want it register `HttpExceptionFilter` themselves:
+     * `{ provide: APP_FILTER, useClass: HttpExceptionFilter }`.
+     *
+     * @param options - Async options (factory + inject + imports, or class).
+     * @returns The configured `DynamicModule`.
+     */
+    static forRootAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule;
+    /**
+     * Replace NestJS's internal logger with this library's `PinoLoggerService` and
+     * flush any logs buffered since `NestFactory.create(..., { bufferLogs: true })`.
+     *
+     * Call once in `main.ts` AFTER creating the app and BEFORE `app.listen(...)`.
+     * The module cannot do this itself — a module never sees the
+     * `INestApplication` instance — so this static helper bridges the gap.
+     *
+     * @param app - The Nest application returned by `NestFactory.create()`.
+     * @throws Error When `BymaxLoggerModule` was not imported (no `PinoLoggerService`
+     *   in the container) — a clear message instead of a cryptic DI failure. The
+     *   original DI error is attached as the error `cause` so the underlying
+     *   failure is preserved for debugging.
+     * @example
+     *   const app = await NestFactory.create(AppModule, { bufferLogs: true })
+     *   BymaxLoggerModule.useNestLogger(app)
+     *   await app.listen(3000)
+     */
+    static useNestLogger(app: INestApplication): void;
+}
+
+/**
+ * Pino-backed implementation of the NestJS `LoggerService` contract plus the
+ * structured `MODULE_ACTION_RESULT` API.
+ *
+ * For a per-class context label, inject a CHILD logger already bound to that
+ * context via `@InjectLogger(MyService.name)` — do NOT call `setContext()` per
+ * class: this is a singleton, so a per-class `setContext()` clobbers the label
+ * for every other holder (see {@link PinoLoggerService.setContext}).
+ *
+ * @example
+ *   constructor(
+ *     @InjectLogger(UserService.name) private readonly logger: PinoLoggerService,
+ *   ) {}
+ *   // ...
+ *   this.logger.info('USER_CREATED', 'New user registered', userId, { plan: 'pro' })
+ */
+declare class PinoLoggerService implements LoggerService, OnApplicationShutdown {
+    private readonly pino;
+    private context?;
+    constructor(pino: Logger);
+    /**
+     * NestJS `log` (info level). Last string parameter is treated as the context.
+     *
+     * @param message - The message to log.
+     * @param optionalParams - NestJS trailing params (context as last string).
+     */
+    log(message: unknown, ...optionalParams: unknown[]): void;
+    /**
+     * NestJS `error`. When `message` is an `Error`, routes to the structured
+     * error path (serializing `err`). Otherwise follows the NestJS variadic
+     * contract `error(message, stack?, context?)`, reading the stack and context
+     * positionally so a trailing stack is never mistaken for the context.
+     *
+     * @param message - The message or `Error` to log.
+     * @param optionalParams - NestJS trailing params (`stack` at index 0, `context` at index 1).
+     */
+    error(message: unknown, ...optionalParams: unknown[]): void;
+    /**
+     * NestJS `warn` (warn level).
+     *
+     * @param message - The message to log.
+     * @param optionalParams - NestJS trailing params (context as last string).
+     */
+    warn(message: unknown, ...optionalParams: unknown[]): void;
+    /**
+     * NestJS `debug` (debug level).
+     *
+     * @param message - The message to log.
+     * @param optionalParams - NestJS trailing params (context as last string).
+     */
+    debug(message: unknown, ...optionalParams: unknown[]): void;
+    /**
+     * NestJS `verbose` (mapped to Pino `trace`).
+     *
+     * @param message - The message to log.
+     * @param optionalParams - NestJS trailing params (context as last string).
+     */
+    verbose(message: unknown, ...optionalParams: unknown[]): void;
+    /**
+     * NestJS `fatal` (fatal level). Declared non-optional here: Pino supports
+     * level 60 natively, and widening the optional `LoggerService.fatal?` to a
+     * required method stays type-compatible.
+     *
+     * @param message - The message to log.
+     * @param optionalParams - NestJS trailing params (context as last string).
+     */
+    fatal(message: unknown, ...optionalParams: unknown[]): void;
+    /**
+     * Emit a structured info log.
+     *
+     * @param logKey - Convention key, e.g. `USER_CREATED`.
+     * @param message - Human-readable message.
+     * @param userId - Optional acting user identifier.
+     * @param metadata - Optional extra structured fields.
+     * @example
+     *   logger.info('USER_CREATED', 'New user registered', userId, { plan: 'pro' })
+     */
+    info(logKey: string, message: string, userId?: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Emit a structured warning log.
+     *
+     * @param logKey - Convention key.
+     * @param message - Human-readable message.
+     * @param userId - Optional acting user identifier.
+     * @param metadata - Optional extra structured fields.
+     */
+    warnStructured(logKey: string, message: string, userId?: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Emit a structured error log with a serialized `err` object.
+     *
+     * @param logKey - Convention key.
+     * @param error - The error to serialize (`name` / `message` / `stack`).
+     * @param userId - Optional acting user identifier.
+     * @param metadata - Optional extra structured fields.
+     */
+    errorStructured(logKey: string, error: Error, userId?: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Set the global context label applied to subsequent logs from THIS instance.
+     *
+     * WARNING: `PinoLoggerService` is a singleton. Calling this per class clobbers
+     * the label for every other holder, and calling it at request time is a
+     * cross-request race. For a per-class label use `@InjectLogger(MyClass.name)`
+     * (which binds a child logger instead of mutating shared state); reserve
+     * `setContext()` for a single global / bootstrap label.
+     *
+     * @param context - The context label.
+     */
+    setContext(context: string): void;
+    /**
+     * Access the underlying Pino instance for advanced use cases.
+     *
+     * @returns The wrapped Pino logger.
+     */
+    getRawLogger(): Logger;
+    /**
+     * Create a child logger with additional permanent bindings, inheriting the
+     * current context label.
+     *
+     * @param bindings - Fields merged into every entry of the child logger.
+     * @returns A new `PinoLoggerService` wrapping the Pino child.
+     */
+    child(bindings: Record<string, unknown>): PinoLoggerService;
+    /**
+     * NestJS shutdown hook. Destination flushing is handled by `DestinationRegistry`;
+     * this service has no additional teardown work.
+     */
+    onApplicationShutdown(): void;
+    /**
+     * Serialize an Error into a plain, log-safe object matching Pino's built-in
+     * `err` serializer shape (`type`, `message`, `stack`).
+     *
+     * Reads `error.name` (NOT `error.constructor.name`) for `type`: native
+     * subclasses set `name` to their class name, and a sanitized plain-object error
+     * (from `sanitizeError`) carries the real class name on `name` — whereas its
+     * `constructor.name` would be the unhelpful `'Object'`, breaking `err.type`
+     * dashboards for every exception logged through `HttpExceptionFilter`.
+     */
+    private serializeError;
+    /** Resolve the context: last string param wins, else the instance context. */
+    private resolveContext;
+    /** Emit a structured payload at info or warn level. */
+    private emitStructured;
+    /** Emit a NestJS-style variadic log, dispatching by level without computed indexing. */
+    private emitNestStyle;
+}
+
+/**
+ * Per-request context propagated via AsyncLocalStorage.
+ *
+ * Consumer code may extend with arbitrary keys via
+ * `LogContextService.set(key, value)`; the index signature permits the
+ * extension at the type level.
+ */
+interface LogContext$1 {
+    /** Correlation ID — typically from `x-request-id` header or generated. */
+    requestId?: string;
+    /** Multi-tenant identifier — read from `x-tenant-id` header or auth claim. */
+    tenantId?: string;
+    /** Authenticated user ID. */
+    userId?: string;
+    /** OpenTelemetry trace ID (32 hex chars). Injected by `TraceContextMixin`. */
+    traceId?: string;
+    /** OpenTelemetry span ID (16 hex chars). */
+    spanId?: string;
+    /** Free-form extensions added by application code. */
+    [key: string]: unknown;
+}
+
+/**
+ * Injectable wrapper around `AsyncLocalStorage<LogContext>`.
+ *
+ * A single instance is shared per module (NestJS singleton scope) so the
+ * code that opens a scope and the mixin that reads it operate on the same
+ * storage.
+ *
+ * @example
+ *   logContext.run({ requestId: 'r_1' }, async () => {
+ *     logContext.set('userId', 'u_1')
+ *     await handler() // every log inside carries requestId + userId
+ *   })
+ */
+declare class LogContextService {
+    private readonly als;
+    /**
+     * Run `callback` inside a fresh context scope. Every log emitted
+     * synchronously or asynchronously within the callback inherits `context`.
+     *
+     * @typeParam T - Return type of the callback.
+     * @param context - Initial context bag for the scope.
+     * @param callback - Function executed within the scope.
+     * @returns Whatever `callback` returns.
+     * @example
+     *   logContext.run({ requestId: 'r_1', tenantId: 't_1' }, async () => {
+     *     await userService.create(dto) // logs carry requestId + tenantId
+     *   })
+     */
+    run<T>(context: LogContext$1, callback: () => T): T;
+    /**
+     * Read the active context, or `undefined` when called outside any scope.
+     *
+     * @returns The active `LogContext`, or `undefined`.
+     */
+    getStore(): LogContext$1 | undefined;
+    /**
+     * Add or override a single field on the active context.
+     *
+     * @param key - Field name to set.
+     * @param value - Field value.
+     * @throws Error When called outside a `run()` scope, or with a prototype-polluting key.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Read a single field from the active context.
+     *
+     * @typeParam T - Expected value type (caller-asserted).
+     * @param key - Field name to read.
+     * @returns The value cast to `T`, or `undefined` when unset / out of scope.
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * Strip prototype-polluting keys from a caller-supplied context so an own
+     * `__proto__` / `constructor` / `prototype` key (e.g. from `JSON.parse` of an
+     * untrusted payload) can never reach the store — and, via the trace mixin's
+     * `Object.assign`, the emitted log entry. Mirrors the guard `set()` enforces,
+     * but drops the key rather than throwing: a logging concern must never crash
+     * the request that produced it.
+     *
+     * @param context - The raw context bag passed to `run()`.
+     * @returns A shallow copy with any forbidden keys removed.
+     */
+    private sanitizeContext;
+}
+
+/**
+ * Canonical destination that writes log payloads to `process.stdout`.
+ *
+ * `process.stdout.write` is buffered by Node.js, which makes it safe to call
+ * on the hot path without blocking the event loop. The Pino producer is the
+ * back-pressure boundary — this destination is intentionally a thin sink.
+ */
+declare class DefaultStdoutDestination implements ILogDestination {
+    readonly name = "stdout-json";
+    readonly minLevel?: LogLevel;
+    /**
+     * @param opts.minLevel — Optional minimum level filter. Entries below this
+     *   level are dropped by the destination registry before reaching `write`.
+     *   Omit (or pass `undefined`) to accept every level.
+     */
+    constructor(opts?: {
+        minLevel?: LogLevel;
+    });
+    /**
+     * Write a serialized JSON log entry (terminated with `\n`) to `stdout`.
+     */
+    write(payload: string): void;
+}
+
+/**
+ * Pretty-print destination backed by `pino-pretty`.
+ *
+ * Lifecycle contract (driven by `DestinationRegistry`):
+ *   1. `onInit()` resolves `pino-pretty` and builds the transform (rendering to
+ *      `process.stdout`).
+ *   2. `write()` forwards each serialized line to the transform.
+ *   3. `onShutdown()` flushes and closes the transform.
+ *
+ * @example
+ *   BymaxLoggerModule.forRoot({
+ *     service: { name: 'api', version: '1.0.0' },
+ *     destinations: [new PrettyDevDestination()]
+ *   })
+ */
+declare class PrettyDevDestination implements ILogDestination {
+    readonly name = "pretty-dev";
+    readonly minLevel?: LogLevel;
+    /**
+     * The `pino-pretty` transform stream. Undefined until {@link onInit} succeeds.
+     */
+    private stream?;
+    /**
+     * Set when {@link onInit} fails (e.g. `pino-pretty` absent). Distinguishes a
+     * permanently-failed destination — whose writes are DROPPED, since the registry
+     * dropped it from the active set — from the transient pre-init window, where
+     * {@link write} falls back to raw stdout so a bootstrap log is not lost.
+     */
+    private initFailed;
+    /**
+     * @param opts.minLevel — Optional minimum level filter applied by the
+     *   destination registry's multi-stream wiring. Omit to accept every level.
+     */
+    constructor(opts?: {
+        minLevel?: LogLevel;
+    });
+    /**
+     * Lazily resolve `pino-pretty` and build the colorized transform that renders
+     * each entry to `process.stdout`.
+     *
+     * @throws Error When `pino-pretty` is not installed — with an actionable
+     *   message telling the consumer to install it or drop this destination.
+     */
+    onInit(): Promise<void>;
+    /**
+     * Write a serialized NDJSON entry to the pretty transform.
+     *
+     * Three states:
+     *   - initialized → forward to the pino-pretty transform;
+     *   - init failed → DROP (the destination was removed from the active set, so
+     *     it must not duplicate raw NDJSON to stdout);
+     *   - pre-init (transient window before {@link onInit}, e.g. a bootstrap log)
+     *     → fall back to raw stdout so the entry is not lost.
+     *
+     * @param payload — Newline-terminated JSON entry, UTF-8 encoded.
+     */
+    write(payload: string): void;
+    /**
+     * Flush and close the pretty transform, resolving once the stream has ended.
+     * A no-op when {@link onInit} never ran.
+     */
+    onShutdown(): Promise<void>;
+}
+
+/**
+ * Logs and renders any exception that escapes the request pipeline.
+ */
+declare class HttpExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    /**
+     * @param logger - The structured logger exception entries are written to.
+     *   Injected by token explicitly: the package is bundled without
+     *   `emitDecoratorMetadata`, so implicit class-type injection would not resolve.
+     */
+    constructor(logger: PinoLoggerService);
+    /**
+     * Log the exception at the status-appropriate level and write the JSON
+     * response.
+     *
+     * @param exception - The thrown value (anything).
+     * @param host - The arguments host (switched to HTTP).
+     */
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
+
+/**
+ * Logs the full HTTP request lifecycle through a Pino-backed logger.
+ */
+declare class HttpLoggingInterceptor implements NestInterceptor {
+    private readonly logger;
+    /** Path patterns that bypass HTTP logging entirely (health checks, metrics). */
+    private readonly excludePaths;
+    /**
+     * @param logger - The structured logger the lifecycle entries are written to.
+     *   Injected by token explicitly: the package is bundled without
+     *   `emitDecoratorMetadata`, so implicit class-type injection would not resolve.
+     * @param options - Resolved module options (read for `http.excludePaths`).
+     *   Injected by token for the same bundling reason.
+     */
+    constructor(logger: PinoLoggerService, options: ResolvedBymaxLoggerModuleOptions);
+    /**
+     * Whether a request path bypasses HTTP logging (matches any `excludePaths`).
+     *
+     * @param path - The query-stripped request path.
+     * @returns `true` when the path matches a configured exclude pattern.
+     */
+    private isExcluded;
+    /**
+     * Emit the START entry, then attach success/redirect/error logging to the
+     * downstream observable while always re-propagating any thrown exception.
+     *
+     * @param context - The current execution context (HTTP).
+     * @param next - The downstream call handler.
+     * @returns The (unmodified) response stream.
+     */
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    /**
+     * Log a non-throwing completion: SUCCESS for 2xx, REDIRECT for 3xx, nothing
+     * for any other status (those are surfaced via the error path instead).
+     *
+     * @param statusCode - The final response status code.
+     * @param method - The HTTP method.
+     * @param url - The normalized request URL.
+     * @param userId - The acting user id, when known.
+     * @param duration - The elapsed time in milliseconds.
+     */
+    private logSuccess;
+    /**
+     * Log a thrown completion: SERVER_ERROR (error level, with stack) for 5xx,
+     * CLIENT_ERROR (warn level) for an `HttpException` below 500. A non-`HttpException`
+     * always maps to 500, so it is reported as a server error.
+     *
+     * @param err - The thrown value (anything).
+     * @param method - The HTTP method.
+     * @param url - The normalized request URL.
+     * @param userId - The acting user id, when known.
+     * @param duration - The elapsed time in milliseconds.
+     */
+    private logError;
+}
+
+/**
+ * `applyRequestIdMiddleware` consumer helper.
+ *
+ * Layer: server/middlewares — NestJS requires middleware to be wired in a
+ * module's `configure(consumer)` hook, which the library cannot do on the
+ * consumer's behalf. This helper encapsulates the one-liner so consumers do not
+ * import the middleware class directly.
+ */
+
+/**
+ * Register {@link RequestIdMiddleware} on the given consumer.
+ *
+ * @param consumer - The `MiddlewareConsumer` from the module's `configure` hook.
+ * @param routes - Route pattern(s) to apply the middleware to. Defaults to all.
+ * @example
+ *   import { applyRequestIdMiddleware } from '@bymax-one/nest-logger'
+ *
+ *   @Module({ imports: [BymaxLoggerModule.forRoot({ service, http: { isEnabled: true } })] })
+ *   export class AppModule implements NestModule {
+ *     configure(consumer: MiddlewareConsumer): void {
+ *       applyRequestIdMiddleware(consumer)
+ *     }
+ *   }
+ */
+declare function applyRequestIdMiddleware(consumer: MiddlewareConsumer, routes?: string): void;
+
+/**
+ * Reads (or generates) the correlation id and starts the per-request log
+ * context scope.
+ *
+ * @example
+ *   // Wire it in the consumer's AppModule:
+ *   export class AppModule implements NestModule {
+ *     configure(consumer: MiddlewareConsumer): void {
+ *       applyRequestIdMiddleware(consumer)
+ *     }
+ *   }
+ */
+declare class RequestIdMiddleware implements NestMiddleware {
+    private readonly logContext;
+    /** Header name carrying the tenant id, resolved from module options. */
+    private readonly tenantIdHeader;
+    /** Whether to mint a `requestId` when the inbound header is absent. */
+    private readonly shouldGenerateRequestId;
+    /**
+     * @param logContext - The AsyncLocalStorage-backed context service. Injected by
+     *   token explicitly: the package is bundled without `emitDecoratorMetadata`,
+     *   so implicit class-type injection would not resolve.
+     * @param options - Resolved module options (read for `http.tenantIdHeader` and
+     *   `http.shouldGenerateRequestId`).
+     */
+    constructor(logContext: LogContextService, options: ResolvedBymaxLoggerModuleOptions);
+    /**
+     * Echo or mint the `x-request-id`, expose it on the response, and run the
+     * remainder of the request inside a fresh log-context scope.
+     *
+     * @param req - The incoming Express request.
+     * @param res - The outgoing Express response.
+     * @param next - The next handler in the chain.
+     */
+    use(req: Request, res: Response, next: NextFunction): void;
+}
+
+/**
+ * Inject a logger into a constructor parameter.
+ *
+ * With a `context` the injected logger is a child bound to that context (every
+ * log carries it); without one, the shared `PinoLoggerService` is injected.
+ *
+ * @param context - Optional context label (typically the host class name).
+ * @returns A parameter decorator wiring the injection (and recording the label).
+ * @example
+ *   @Injectable()
+ *   export class UsersService {
+ *     constructor(@InjectLogger('UsersService') private readonly logger: PinoLoggerService) {}
+ *   }
+ *   // every `this.logger.*` entry now carries context: 'UsersService'
+ */
+declare function InjectLogger(context?: string): ParameterDecorator;
+
+/** Reflect-metadata key under which the class context label is stored. */
+declare const LOG_CONTEXT_METADATA_KEY = "bymax_logger:log_context";
+/**
+ * Set the log-context label for a class. All loggers injected within the class
+ * are intended to adopt this label (auto-application requires a wired interceptor).
+ *
+ * @param name - The context label (typically the class name).
+ * @returns A NestJS metadata decorator carrying the label.
+ * @example
+ *   @LogContext('PaymentsService')
+ *   @Injectable()
+ *   export class PaymentsService {}
+ */
+declare const LogContext: (name: string) => CustomDecorator<string>;
+
+/**
+ * Measure and log a method's execution time.
+ *
+ * @param thresholdMs - Duration (ms) above which the call is logged as slow.
+ *   Defaults to {@link DEFAULT_THRESHOLD_MS} (1000).
+ * @returns A method decorator that wraps the original implementation.
+ * @remarks The wrapped method always returns a `Promise` (see the file header):
+ *   apply only to async methods or callers that can await the result.
+ * @example
+ *   class ReportService {
+ *     constructor(@InjectLogger() private readonly logger: PinoLoggerService) {}
+ *
+ *     @LogPerformance(500) // warn if it takes > 500ms
+ *     async generateReport(): Promise<void> {}
+ *   }
+ */
+declare function LogPerformance(thresholdMs?: number): MethodDecorator;
+
+/**
+ * Dependency-injection tokens used by `BymaxLoggerModule`.
+ *
+ * Symbols (rather than strings) are used to guarantee uniqueness across the
+ * entire NestJS DI graph — two consumers cannot collide on the same token by
+ * accident, and accidental string typos cannot resolve a foreign provider.
+ *
+ * This mirrors the pattern established by `@bymax-one/nest-auth` for every
+ * shared Bymax NestJS library.
+ */
+/** Injection token for the resolved `BymaxLoggerModuleOptions` snapshot. */
+declare const LOGGER_OPTIONS_TOKEN: unique symbol;
+/** Injection token for the underlying Pino instance (used by services and mixins). */
+declare const LOGGER_PINO_INSTANCE_TOKEN: unique symbol;
+/** Injection token for the resolved destinations array (read-only at runtime). */
+declare const LOGGER_DESTINATIONS_TOKEN: unique symbol;
+/** Injection token for the per-request AsyncLocalStorage-backed log context. */
+declare const LOG_CONTEXT_TOKEN: unique symbol;
+
+/**
+ * Canonical list of redact paths merged into Pino's `redact.paths` option by
+ * default. Expected length: 27 common fields × 4 depths + 5 absolute = **113**.
+ */
+declare const DEFAULT_REDACT_PATHS: readonly string[];
+
+/**
+ * Shape of a single log entry as serialized to JSON output.
+ *
+ * Used by destinations and downstream parsers (Datadog, Loki, Elastic).
+ * The trailing index signature `[key: string]: unknown` covers arbitrary
+ * structured fields injected by application logs.
+ */
+interface LogEntry {
+    /** Pino numeric level (30 = info, 50 = error, etc.). */
+    level: number;
+    /** ISO 8601 UTC timestamp string OR epoch milliseconds (numeric). */
+    time: string | number;
+    /** Human-readable message. */
+    msg: string;
+    /** Convention key — `MODULE_ACTION_RESULT` format. */
+    logKey?: string;
+    /** Service metadata snapshot — see {@link ServiceMetadata}. */
+    service?: ServiceMetadata;
+    /** Optional NestJS context (typically the emitting class name). */
+    context?: string;
+    /** Optional correlation IDs propagated via AsyncLocalStorage. */
+    requestId?: string;
+    tenantId?: string;
+    userId?: string;
+    /** Optional trace context injected when OpenTelemetry SDK is active. */
+    traceId?: string;
+    spanId?: string;
+    /** Arbitrary additional fields produced by application logs. */
+    [key: string]: unknown;
+}
+
+/**
+ * Regex enforcing the canonical Bymax log-key convention.
+ *
+ * The convention is `MODULE_ACTION_RESULT` (e.g., `USER_CREATED`,
+ * `AUTH_LOGIN_SUCCESS`), but the regex accepts **two or more** uppercase words —
+ * keys in {@link RESERVED_LOG_KEYS} legitimately use four words
+ * (e.g. `HTTP_REQUEST_CLIENT_ERROR`, `LOGGER_DESTINATION_WRITE_FAILED`).
+ *
+ * Pattern: two mandatory uppercase-prefixed groups separated by `_`, plus one
+ * optional third group. Within each group, `[A-Z0-9_]+` allows digits and
+ * underscores after the leading uppercase letter, which enables additional
+ * semantic words inside a group (e.g., `HTTP_REQUEST_CLIENT` is the first group
+ * in `HTTP_REQUEST_CLIENT_ERROR`). As a side-effect, strings with a double
+ * underscore (`HELLO__WORLD`) also pass; this is an accepted edge case.
+ *
+ * Enforcement rules:
+ *   - At least 2 uppercase-prefixed words (`[A-Z][A-Z0-9_]+`)
+ *   - Each pattern group starts with `A-Z`; no lowercase letters permitted
+ *   - No leading or trailing underscores at the top level
+ *
+ * @example
+ *   LOG_KEYS_CONVENTION_REGEX.test('USER_CREATED')              // true
+ *   LOG_KEYS_CONVENTION_REGEX.test('AUTH_LOGIN_SUCCESS')        // true
+ *   LOG_KEYS_CONVENTION_REGEX.test('HTTP_REQUEST_CLIENT_ERROR') // true (4 words)
+ *   LOG_KEYS_CONVENTION_REGEX.test('login_success')             // false (lowercase)
+ *   LOG_KEYS_CONVENTION_REGEX.test('LOGIN')                     // false (single word)
+ */
+declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
+
+/**
+ * Log keys reserved by `@bymax-one/nest-logger` for its own structured events.
+ *
+ * Consumer apps SHOULD NOT use these names for application-level events
+ * to avoid collision in log aggregation queries (Datadog, Loki, Elastic).
+ */
+declare const RESERVED_LOG_KEYS: Readonly<{
+    readonly LOGGER_BOOTSTRAP_OK: "LOGGER_BOOTSTRAP_OK";
+    readonly LOGGER_BOOTSTRAP_WARNING: "LOGGER_BOOTSTRAP_WARNING";
+    readonly LOGGER_SHUTDOWN_OK: "LOGGER_SHUTDOWN_OK";
+    readonly HTTP_REQUEST_START: "HTTP_REQUEST_START";
+    readonly HTTP_REQUEST_SUCCESS: "HTTP_REQUEST_SUCCESS";
+    readonly HTTP_REQUEST_REDIRECT: "HTTP_REQUEST_REDIRECT";
+    readonly HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR";
+    readonly HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR";
+    readonly HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED";
+    readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
+    readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
+    readonly METHOD_EXECUTION: "METHOD_EXECUTION";
+    readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
+    readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
+    readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
+    readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
+}>;
+
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type OtelOptions, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };