@bymax-one/nest-logger 1.0.0

package/dist/server/index.mjs

@@ -0,0 +1,1452 @@
+import { Injectable, Inject, HttpStatus, Catch, ConfigurableModuleBuilder, Module, HttpException, SetMetadata } from '@nestjs/common';
+import { APP_INTERCEPTOR, APP_FILTER } from '@nestjs/core';
+import { tap, catchError, throwError } from 'rxjs';
+import pino from 'pino';
+import { createRequire } from 'module';
+import { join } from 'path';
+import { Writable } from 'stream';
+import { AsyncLocalStorage } from 'async_hooks';
+import { randomUUID } from 'crypto';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/server/config/default-options.ts
+var DEFAULT_HTTP = {
+  isEnabled: false,
+  shouldCaptureExceptions: true,
+  shouldGenerateRequestId: true,
+  excludePaths: [/^\/health$/, /^\/metrics$/],
+  tenantIdHeader: "x-tenant-id"
+};
+var DEFAULT_OTEL = {
+  shouldAutoInjectTraceContext: true,
+  fieldFormat: "camelCase",
+  traceIdField: "traceId",
+  spanIdField: "spanId",
+  traceFlagsField: "traceFlags"
+};
+var DEFAULT_MAX_ENTRY_SIZE_BYTES = 65536;
+function applyOtelFieldFormat(merged, user) {
+  if (merged.fieldFormat === "snake_case") {
+    return {
+      ...merged,
+      traceIdField: user?.traceIdField ?? "trace_id",
+      spanIdField: user?.spanIdField ?? "span_id",
+      traceFlagsField: user?.traceFlagsField ?? "trace_flags"
+    };
+  }
+  return merged;
+}
+function applyDefaults(options) {
+  const isProduction = process.env["NODE_ENV"] === "production";
+  const http = { ...DEFAULT_HTTP, ...options.http ?? {} };
+  const otel = applyOtelFieldFormat(
+    { ...DEFAULT_OTEL, ...options.otel ?? {} },
+    options.otel
+  );
+  const merged = {
+    service: Object.freeze({ ...options.service }),
+    level: options.level ?? (isProduction ? "info" : "debug"),
+    isGlobal: options.isGlobal ?? true,
+    shouldUseAsNestLogger: options.shouldUseAsNestLogger ?? true,
+    redactPaths: Object.freeze([...options.redactPaths ?? []]),
+    redactCensor: options.redactCensor ?? "[REDACTED]",
+    shouldDisableDefaultRedact: options.shouldDisableDefaultRedact ?? false,
+    destinations: Object.freeze([...options.destinations ?? []]),
+    isPretty: options.isPretty ?? !isProduction,
+    http: Object.freeze({
+      ...http,
+      excludePaths: Object.freeze([...http.excludePaths])
+    }),
+    otel: Object.freeze(otel),
+    maxEntrySizeBytes: options.maxEntrySizeBytes ?? DEFAULT_MAX_ENTRY_SIZE_BYTES,
+    serializers: Object.freeze({ ...options.serializers ?? {} }),
+    timestamp: options.timestamp ?? (() => (/* @__PURE__ */ new Date()).toISOString())
+  };
+  return Object.freeze(merged);
+}
+
+// src/server/constants/log-levels.constants.ts
+var PINO_LEVEL_NUMBERS = Object.freeze({
+  fatal: 60,
+  error: 50,
+  warn: 40,
+  info: 30,
+  debug: 20,
+  trace: 10
+});
+Object.freeze(
+  Object.fromEntries(
+    Object.entries(PINO_LEVEL_NUMBERS).map(([name, num]) => [num, name])
+    // keys of PINO_LEVEL_NUMBERS are always LogLevel
+  )
+  // Object.fromEntries infers Record<string, V>; numeric index is intentional for level lookups
+);
+var LOG_LEVEL_PRIORITY = Object.freeze([
+  "trace",
+  "debug",
+  "info",
+  "warn",
+  "error",
+  "fatal"
+]);
+
+// src/server/config/validate-options.ts
+function validateOptions(options) {
+  if (!options.service) {
+    throw new Error("[BymaxLoggerModule] options.service is required");
+  }
+  if (typeof options.service.name !== "string" || options.service.name.trim() === "") {
+    throw new Error("[BymaxLoggerModule] options.service.name must be a non-empty string");
+  }
+  if (typeof options.service.version !== "string" || options.service.version.trim() === "") {
+    throw new Error("[BymaxLoggerModule] options.service.version must be a non-empty string");
+  }
+  if (options.level !== void 0 && !LOG_LEVEL_PRIORITY.includes(options.level)) {
+    throw new Error(
+      `[BymaxLoggerModule] options.level must be one of: ${LOG_LEVEL_PRIORITY.join(
+        ", "
+      )}. Got: ${String(options.level)}`
+    );
+  }
+  if (options.maxEntrySizeBytes !== void 0 && options.maxEntrySizeBytes <= 0) {
+    throw new Error("[BymaxLoggerModule] options.maxEntrySizeBytes must be > 0");
+  }
+}
+
+// src/server/constants/injection-tokens.constants.ts
+var LOGGER_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_LOGGER_OPTIONS");
+var LOGGER_PINO_INSTANCE_TOKEN = /* @__PURE__ */ Symbol("BYMAX_LOGGER_PINO_INSTANCE");
+var LOGGER_DESTINATIONS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_LOGGER_DESTINATIONS");
+var LOG_CONTEXT_TOKEN = /* @__PURE__ */ Symbol("BYMAX_LOGGER_LOG_CONTEXT");
+var PinoLoggerService = class {
+  constructor(pino2) {
+    this.pino = pino2;
+  }
+  // ─── NestJS LoggerService variadic interface ──────────────────────────────
+  /**
+   * 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, ...optionalParams) {
+    this.emitNestStyle("info", message, optionalParams);
+  }
+  /**
+   * 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, ...optionalParams) {
+    if (message instanceof Error) {
+      this.pino.error(
+        { context: this.resolveContext(optionalParams), err: this.serializeError(message) },
+        message.message
+      );
+      return;
+    }
+    const stack = typeof optionalParams[0] === "string" ? optionalParams[0] : void 0;
+    const context = typeof optionalParams[1] === "string" ? optionalParams[1] : this.context;
+    const payload = { context };
+    if (stack !== void 0) {
+      payload["stack"] = stack;
+    }
+    this.pino.error(payload, typeof message === "string" ? message : String(message));
+  }
+  /**
+   * NestJS `warn` (warn level).
+   *
+   * @param message - The message to log.
+   * @param optionalParams - NestJS trailing params (context as last string).
+   */
+  warn(message, ...optionalParams) {
+    this.emitNestStyle("warn", message, optionalParams);
+  }
+  /**
+   * NestJS `debug` (debug level).
+   *
+   * @param message - The message to log.
+   * @param optionalParams - NestJS trailing params (context as last string).
+   */
+  debug(message, ...optionalParams) {
+    this.emitNestStyle("debug", message, optionalParams);
+  }
+  /**
+   * NestJS `verbose` (mapped to Pino `trace`).
+   *
+   * @param message - The message to log.
+   * @param optionalParams - NestJS trailing params (context as last string).
+   */
+  verbose(message, ...optionalParams) {
+    this.emitNestStyle("trace", message, optionalParams);
+  }
+  /**
+   * 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, ...optionalParams) {
+    this.emitNestStyle("fatal", message, optionalParams);
+  }
+  // ─── Structured API (MODULE_ACTION_RESULT convention) ─────────────────────
+  /**
+   * 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, message, userId, metadata) {
+    this.emitStructured("info", logKey, message, userId, metadata);
+  }
+  /**
+   * 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, message, userId, metadata) {
+    this.emitStructured("warn", logKey, message, userId, metadata);
+  }
+  /**
+   * 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, error, userId, metadata) {
+    this.pino.error(
+      { ...metadata, logKey, userId, context: this.context, err: this.serializeError(error) },
+      error.message
+    );
+  }
+  // ─── Helpers / escape hatches ─────────────────────────────────────────────
+  /**
+   * 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) {
+    this.context = context;
+  }
+  /**
+   * Access the underlying Pino instance for advanced use cases.
+   *
+   * @returns The wrapped Pino logger.
+   */
+  getRawLogger() {
+    return this.pino;
+  }
+  /**
+   * 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) {
+    const childService = new PinoLoggerService(this.pino.child(bindings));
+    if (this.context !== void 0) {
+      childService.setContext(this.context);
+    }
+    return childService;
+  }
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
+  /**
+   * NestJS shutdown hook. Destination flushing is handled by `DestinationRegistry`;
+   * this service has no additional teardown work.
+   */
+  onApplicationShutdown() {
+  }
+  // ─── Private ──────────────────────────────────────────────────────────────
+  /**
+   * 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`.
+   */
+  serializeError(error) {
+    return { type: error.name, message: error.message, stack: error.stack };
+  }
+  /** Resolve the context: last string param wins, else the instance context. */
+  resolveContext(optionalParams) {
+    const last = optionalParams[optionalParams.length - 1];
+    return typeof last === "string" ? last : this.context;
+  }
+  /** Emit a structured payload at info or warn level. */
+  emitStructured(level, logKey, message, userId, metadata) {
+    const payload = {
+      ...metadata,
+      logKey,
+      userId,
+      context: this.context
+    };
+    if (level === "info") {
+      this.pino.info(payload, message);
+    } else {
+      this.pino.warn(payload, message);
+    }
+  }
+  /** Emit a NestJS-style variadic log, dispatching by level without computed indexing. */
+  emitNestStyle(level, message, optionalParams) {
+    const payload = { context: this.resolveContext(optionalParams) };
+    const msg = typeof message === "string" ? message : String(message);
+    switch (level) {
+      case "info":
+        this.pino.info(payload, msg);
+        break;
+      case "warn":
+        this.pino.warn(payload, msg);
+        break;
+      case "debug":
+        this.pino.debug(payload, msg);
+        break;
+      case "trace":
+        this.pino.trace(payload, msg);
+        break;
+      case "fatal":
+        this.pino.fatal(payload, msg);
+        break;
+    }
+  }
+};
+PinoLoggerService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(LOGGER_PINO_INSTANCE_TOKEN))
+], PinoLoggerService);
+
+// src/server/decorators/inject-logger.provider.ts
+var contextTokens = /* @__PURE__ */ new Map();
+function getContextLoggerToken(context) {
+  const existing = contextTokens.get(context);
+  if (existing !== void 0) {
+    return existing;
+  }
+  const token = /* @__PURE__ */ Symbol(`INJECTED_LOGGER_${context}`);
+  contextTokens.set(context, token);
+  return token;
+}
+function createContextLoggerProvider(context) {
+  return {
+    provide: getContextLoggerToken(context),
+    useFactory: (rootLogger) => rootLogger.child({ context }),
+    inject: [PinoLoggerService]
+  };
+}
+function collectContextLoggerProviders() {
+  return Array.from(contextTokens.keys(), (context) => createContextLoggerProvider(context));
+}
+function collectContextLoggerTokens() {
+  return Array.from(contextTokens.values());
+}
+var DefaultStdoutDestination = class {
+  /**
+   * @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 = {}) {
+    this.name = "stdout-json";
+    if (opts.minLevel !== void 0) {
+      this.minLevel = opts.minLevel;
+    }
+  }
+  /**
+   * Write a serialized JSON log entry (terminated with `\n`) to `stdout`.
+   */
+  write(payload) {
+    process.stdout.write(payload);
+  }
+};
+DefaultStdoutDestination = __decorateClass([
+  Injectable()
+], DefaultStdoutDestination);
+
+// src/shared/constants/reserved-log-keys.constants.ts
+var RESERVED_LOG_KEYS = Object.freeze({
+  LOGGER_BOOTSTRAP_OK: "LOGGER_BOOTSTRAP_OK",
+  LOGGER_BOOTSTRAP_WARNING: "LOGGER_BOOTSTRAP_WARNING",
+  LOGGER_SHUTDOWN_OK: "LOGGER_SHUTDOWN_OK",
+  HTTP_REQUEST_START: "HTTP_REQUEST_START",
+  HTTP_REQUEST_SUCCESS: "HTTP_REQUEST_SUCCESS",
+  HTTP_REQUEST_REDIRECT: "HTTP_REQUEST_REDIRECT",
+  HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR",
+  HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR",
+  HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED",
+  HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
+  HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
+  METHOD_EXECUTION: "METHOD_EXECUTION",
+  METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
+  LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
+  LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED",
+  LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED"
+});
+
+// src/server/utils/normalize-url.util.ts
+var UUID_REGEX = /\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?![0-9a-f])/gi;
+var ULID_REGEX = /\/[0-9A-HJKMNP-TV-Z]{26}(?![0-9A-HJKMNP-TV-Z])/g;
+var NANOID_REGEX = /\/[A-Za-z0-9_-]{21}(?![A-Za-z0-9_-])/g;
+var NUMERIC_ID_REGEX = /\/\d+/g;
+var ID_PLACEHOLDER = "/:id";
+function normalizeUrl(url) {
+  return stripQueryString(url).replace(UUID_REGEX, ID_PLACEHOLDER).replace(ULID_REGEX, ID_PLACEHOLDER).replace(NANOID_REGEX, ID_PLACEHOLDER).replace(NUMERIC_ID_REGEX, ID_PLACEHOLDER);
+}
+function stripQueryString(url) {
+  const queryStart = url.indexOf("?");
+  return queryStart === -1 ? url : url.slice(0, queryStart);
+}
+
+// src/server/utils/sanitize-error.util.ts
+var DEFAULT_MAX_CAUSE_DEPTH = 3;
+var MAX_AGGREGATE_ERRORS = 10;
+var CIRCULAR_SENTINEL = "[Circular]";
+function sanitizeError(err, options) {
+  const maxCauseDepth = DEFAULT_MAX_CAUSE_DEPTH;
+  return toSanitizedError(err, /* @__PURE__ */ new WeakSet(), 0, maxCauseDepth);
+}
+function toSanitizedError(value, seen, depth2, maxDepth) {
+  try {
+    if (!(value instanceof Error)) {
+      return { name: "UnknownError", message: String(value) };
+    }
+    seen.add(value);
+    const result = { name: value.name, message: value.message };
+    if (value.stack !== void 0) {
+      result.stack = scrubStack(value.stack);
+    }
+    const isAtDepthLimit = depth2 >= maxDepth;
+    if (value.cause !== void 0) {
+      result.cause = isAtDepthLimit ? createDepthMarker() : toSanitizedChild(value.cause, seen, depth2 + 1, maxDepth);
+    }
+    const aggregated = readAggregatedErrors(value);
+    if (aggregated !== void 0) {
+      const capped = aggregated.slice(0, MAX_AGGREGATE_ERRORS);
+      result.errors = capped.map(
+        (inner) => isAtDepthLimit ? createDepthMarker() : toSanitizedChild(inner, seen, depth2 + 1, maxDepth)
+      );
+      if (aggregated.length > MAX_AGGREGATE_ERRORS) {
+        result.errors.push(createWidthMarker(aggregated.length - MAX_AGGREGATE_ERRORS));
+      }
+    }
+    return result;
+  } catch {
+    return { name: "SanitizeFailed", message: "Failed to sanitize the thrown value" };
+  }
+}
+function toSanitizedChild(value, seen, depth2, maxDepth) {
+  if (isObject(value) && seen.has(value)) {
+    return CIRCULAR_SENTINEL;
+  }
+  return toSanitizedError(value, seen, depth2, maxDepth);
+}
+function readAggregatedErrors(value) {
+  const candidate = value.errors;
+  return Array.isArray(candidate) ? candidate : void 0;
+}
+function scrubStack(stack) {
+  return stack.split("\n").filter((line) => !line.includes("node_modules")).join("\n");
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function createDepthMarker() {
+  return { _truncated: true, _reason: "cause-depth-exceeded" };
+}
+function createWidthMarker(omitted) {
+  return { _truncated: true, _reason: "aggregate-width-exceeded", _omitted: omitted };
+}
+
+// src/server/filters/http-exception.filter.ts
+var INTERNAL_ERROR_BODY = {
+  statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+  message: "Internal server error"
+};
+var HttpExceptionFilter = class {
+  /**
+   * @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) {
+    this.logger = logger;
+  }
+  /**
+   * 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, host) {
+    const ctx = host.switchToHttp();
+    const res = ctx.getResponse();
+    const req = ctx.getRequest();
+    const userId = req.user?.id;
+    const url = stripQueryString(req.url);
+    if (exception instanceof HttpException) {
+      const status2 = exception.getStatus();
+      const metadata = { method: req.method, url, status: status2 };
+      if (status2 >= HttpStatus.INTERNAL_SERVER_ERROR) {
+        this.logger.errorStructured(
+          RESERVED_LOG_KEYS.HTTP_EXCEPTION_UNHANDLED,
+          sanitizeError(exception),
+          userId,
+          metadata
+        );
+      } else {
+        this.logger.warnStructured(
+          RESERVED_LOG_KEYS.HTTP_EXCEPTION_HANDLED,
+          exception.message,
+          userId,
+          metadata
+        );
+      }
+      res.status(status2).json(exception.getResponse());
+      return;
+    }
+    const status = HttpStatus.INTERNAL_SERVER_ERROR;
+    this.logger.errorStructured(
+      RESERVED_LOG_KEYS.HTTP_EXCEPTION_UNHANDLED,
+      sanitizeError(exception),
+      userId,
+      {
+        method: req.method,
+        url,
+        status
+      }
+    );
+    res.status(status).json(INTERNAL_ERROR_BODY);
+  }
+};
+HttpExceptionFilter = __decorateClass([
+  Catch(),
+  __decorateParam(0, Inject(PinoLoggerService))
+], HttpExceptionFilter);
+var HTTP_SUCCESS_MIN = 200;
+var HTTP_REDIRECT_MIN = 300;
+var HTTP_CLIENT_ERROR_MIN = 400;
+var HTTP_SERVER_ERROR_MIN = 500;
+var UNKNOWN_USER_AGENT = "unknown";
+var HttpLoggingInterceptor = class {
+  /**
+   * @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, options) {
+    this.logger = logger;
+    this.excludePaths = options.http.excludePaths;
+  }
+  /**
+   * 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.
+   */
+  isExcluded(path) {
+    return this.excludePaths.some((pattern) => pattern.test(path));
+  }
+  /**
+   * 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, next) {
+    const http = context.switchToHttp();
+    const req = http.getRequest();
+    const res = http.getResponse();
+    const { method, url, ip } = req;
+    if (this.isExcluded(stripQueryString(url))) {
+      return next.handle();
+    }
+    const rawUserAgent = req.headers["user-agent"];
+    const userAgent = typeof rawUserAgent === "string" ? rawUserAgent : UNKNOWN_USER_AGENT;
+    const userId = req.user?.id;
+    const normalizedUrl = normalizeUrl(url);
+    const start = Date.now();
+    this.logger.info(RESERVED_LOG_KEYS.HTTP_REQUEST_START, `${method} ${normalizedUrl}`, userId, {
+      method,
+      url: normalizedUrl,
+      // Query string stripped: it may carry secrets (reset tokens, OAuth codes)
+      // that Pino's path-based redaction cannot scrub from a string value. The
+      // raw (un-normalized) path is kept for per-request debugging.
+      fullUrl: stripQueryString(url),
+      ip,
+      userAgent
+    });
+    return next.handle().pipe(
+      tap(() => {
+        this.logSuccess(res.statusCode, method, normalizedUrl, userId, Date.now() - start);
+      }),
+      catchError((err) => {
+        this.logError(err, method, normalizedUrl, userId, Date.now() - start);
+        return throwError(() => err);
+      })
+    );
+  }
+  /**
+   * 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.
+   */
+  logSuccess(statusCode, method, url, userId, duration) {
+    if (statusCode >= HTTP_SUCCESS_MIN && statusCode < HTTP_REDIRECT_MIN) {
+      this.logger.info(
+        RESERVED_LOG_KEYS.HTTP_REQUEST_SUCCESS,
+        `${method} ${url} \u2192 ${statusCode} (${duration}ms)`,
+        userId,
+        { method, url, statusCode, duration }
+      );
+    } else if (statusCode >= HTTP_REDIRECT_MIN && statusCode < HTTP_CLIENT_ERROR_MIN) {
+      this.logger.info(
+        RESERVED_LOG_KEYS.HTTP_REQUEST_REDIRECT,
+        `${method} ${url} \u2192 ${statusCode}`,
+        userId,
+        { method, url, statusCode, duration }
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  logError(err, method, url, userId, duration) {
+    if (err instanceof HttpException) {
+      const statusCode = err.getStatus();
+      if (statusCode >= HTTP_SERVER_ERROR_MIN) {
+        this.logger.errorStructured(RESERVED_LOG_KEYS.HTTP_REQUEST_SERVER_ERROR, err, userId, {
+          method,
+          url,
+          statusCode,
+          duration
+        });
+      } else {
+        this.logger.warnStructured(
+          RESERVED_LOG_KEYS.HTTP_REQUEST_CLIENT_ERROR,
+          `${method} ${url} \u2192 ${statusCode}`,
+          userId,
+          { method, url, statusCode, duration, errorMessage: err.message }
+        );
+      }
+      return;
+    }
+    this.logger.errorStructured(
+      RESERVED_LOG_KEYS.HTTP_REQUEST_SERVER_ERROR,
+      err instanceof Error ? err : new Error(String(err)),
+      userId,
+      { method, url, statusCode: HttpStatus.INTERNAL_SERVER_ERROR, duration }
+    );
+  }
+};
+HttpLoggingInterceptor = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(PinoLoggerService)),
+  __decorateParam(1, Inject(LOGGER_OPTIONS_TOKEN))
+], HttpLoggingInterceptor);
+var PassThroughInterceptor = class {
+  /**
+   * Forward the downstream stream without observing or modifying it.
+   *
+   * @param _context - The execution context (unused).
+   * @param next - The downstream call handler.
+   * @returns The unmodified downstream stream.
+   */
+  intercept(_context, next) {
+    return next.handle();
+  }
+};
+PassThroughInterceptor = __decorateClass([
+  Injectable()
+], PassThroughInterceptor);
+var {
+  ConfigurableModuleClass: BymaxLoggerModuleBase,
+  MODULE_OPTIONS_TOKEN: BUILDER_OPTIONS_TOKEN,
+  OPTIONS_TYPE,
+  ASYNC_OPTIONS_TYPE
+} = new ConfigurableModuleBuilder().setClassMethodName("forRoot").setFactoryMethodName("createLoggerOptions").setExtras({ isGlobal: true }, (definition, extras) => ({
+  ...definition,
+  // `setExtras` merges the `{ isGlobal: true }` default before this runs, so
+  // `isGlobal` is always defined; `!== false` keeps "global unless explicitly
+  // disabled" without a dead nullish branch.
+  global: extras.isGlobal !== false
+})).build();
+function detectOtelTraceApi() {
+  try {
+    const requireFromCwd = createRequire(join(process.cwd(), "noop.cjs"));
+    const mod = requireFromCwd("@opentelemetry/api");
+    return mod.trace;
+  } catch {
+    return void 0;
+  }
+}
+function isValidTraceId(traceId) {
+  return /^[0-9a-f]{32}$/.test(traceId) && !/^0+$/.test(traceId);
+}
+function isValidSpanId(spanId) {
+  return /^[0-9a-f]{16}$/.test(spanId) && !/^0+$/.test(spanId);
+}
+
+// src/server/mixins/trace-context.mixin.ts
+function createTraceContextMixin(logContext, opts) {
+  const traceApi = opts.shouldAutoInjectTraceContext ? detectOtelTraceApi() : void 0;
+  return function mixin(_mergeObject, _level, _logger) {
+    const merged = {};
+    const store = logContext.getStore();
+    if (store) {
+      Object.assign(merged, store);
+    }
+    if (traceApi) {
+      const span = traceApi.getActiveSpan();
+      if (span) {
+        const ctx = span.spanContext();
+        if (isValidTraceId(ctx.traceId) && isValidSpanId(ctx.spanId)) {
+          Reflect.set(merged, opts.traceIdField, ctx.traceId);
+          Reflect.set(merged, opts.spanIdField, ctx.spanId);
+          if (typeof ctx.traceFlags === "number") {
+            const flagsByte = ctx.traceFlags & 255;
+            Reflect.set(merged, opts.traceFlagsField, flagsByte.toString(16).padStart(2, "0"));
+          }
+        }
+      }
+    }
+    return merged;
+  };
+}
+
+// src/server/constants/default-redact-paths.constants.ts
+var REDACT_MAX_DEPTH = 4;
+var WILDCARD_PREFIXES = Array.from(
+  { length: REDACT_MAX_DEPTH },
+  (_, idx) => "*" + ".*".repeat(idx)
+);
+var depth = (field) => WILDCARD_PREFIXES.map((prefix) => `${prefix}.${field}`);
+var REDACT_COMMON_FIELDS = [
+  // Passwords (5)
+  "password",
+  "passwordHash",
+  "passwordConfirm",
+  "newPassword",
+  "oldPassword",
+  // Tokens (6)
+  "token",
+  "accessToken",
+  "refreshToken",
+  "idToken",
+  "apiKey",
+  "apiSecret",
+  // MFA (3)
+  "mfaSecret",
+  "mfaRecoveryCodes",
+  "totpSecret",
+  // Payment / PCI DSS (5)
+  "cardNumber",
+  "cardCvv",
+  "cvv",
+  "cvc",
+  "cardExpiry",
+  // Personal documents — BR / LGPD (3)
+  "cpf",
+  "cnpj",
+  "rg",
+  // Generic secrets (4) — the most common short-form credential field names
+  "secret",
+  "clientSecret",
+  "signingSecret",
+  "privateKey",
+  // Conservative PII (1) — consumer can disable if logging email is justified
+  "email"
+];
+var REDACT_ABSOLUTE_PATHS = [
+  "req.headers.authorization",
+  "req.headers.cookie",
+  'req.headers["x-api-key"]',
+  'req.headers["x-auth-token"]',
+  'res.headers["set-cookie"]'
+];
+var DEFAULT_REDACT_PATHS = [
+  ...REDACT_COMMON_FIELDS.flatMap((field) => depth(field)),
+  ...REDACT_ABSOLUTE_PATHS
+];
+
+// src/server/utils/compile-redact-paths.util.ts
+function compileRedactPaths(extraPaths, shouldSkipDefaults) {
+  const sources = shouldSkipDefaults ? [extraPaths] : [DEFAULT_REDACT_PATHS, extraPaths];
+  return Array.from(new Set(sources.flat()));
+}
+function reportWriteFailure(name, cause) {
+  const err = cause instanceof Error ? { type: cause.name, message: cause.message } : { type: "UnknownError", message: String(cause) };
+  try {
+    process.stderr.write(
+      JSON.stringify({
+        level: "error",
+        logKey: RESERVED_LOG_KEYS.LOGGER_DESTINATION_WRITE_FAILED,
+        destination: name,
+        err,
+        msg: `Log destination "${name}" failed to write; the entry was dropped`
+      }) + "\n"
+    );
+  } catch {
+  }
+}
+function destinationToStream(destination) {
+  return new Writable({
+    // Keep string chunks as strings (Node's default re-encodes them to Buffers
+    // before `_write`): the common Pino path emits NDJSON strings, so this skips
+    // a string→Buffer→string round-trip on the hot logging path.
+    decodeStrings: false,
+    write(chunk, _encoding, callback) {
+      const onFailure = (cause) => {
+        reportWriteFailure(destination.name, cause);
+        callback();
+      };
+      try {
+        const payload = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+        const result = destination.write(payload);
+        if (result instanceof Promise) {
+          result.then(() => callback(), onFailure);
+        } else {
+          callback();
+        }
+      } catch (cause) {
+        onFailure(cause);
+      }
+    }
+  });
+}
+
+// src/server/utils/truncate-large-entries.ts
+var PREVIEW_LENGTH = 200;
+function createSizeBoundedSerializer(baseSerializer, maxBytes) {
+  return (input) => {
+    const serialized = baseSerializer(input);
+    let json;
+    try {
+      json = JSON.stringify(serialized);
+    } catch {
+      return serialized;
+    }
+    if (json === void 0) {
+      return serialized;
+    }
+    const byteSize = Buffer.byteLength(json, "utf-8");
+    if (byteSize > maxBytes) {
+      return {
+        _truncated: true,
+        _logKey: RESERVED_LOG_KEYS.LOGGER_ENTRY_TRUNCATED,
+        _originalSize: byteSize,
+        _preview: json.slice(0, PREVIEW_LENGTH)
+      };
+    }
+    return serialized;
+  };
+}
+
+// src/server/pino-factory.ts
+function buildPinoInstance(options, logContext, destinations) {
+  const maxBytes = options.maxEntrySizeBytes;
+  const serializers = {
+    err: createSizeBoundedSerializer(pino.stdSerializers.err, maxBytes),
+    ...Object.fromEntries(
+      Object.entries(options.serializers).map(
+        ([key, serializer]) => [
+          key,
+          createSizeBoundedSerializer(serializer, maxBytes)
+        ]
+      )
+    )
+  };
+  const pinoOptions = {
+    level: options.level,
+    redact: {
+      paths: compileRedactPaths(options.redactPaths, options.shouldDisableDefaultRedact),
+      censor: options.redactCensor
+    },
+    base: { service: options.service },
+    // Pino requires the timestamp fn to emit the `,"time":"..."` fragment.
+    timestamp: () => `,"time":"${options.timestamp()}"`,
+    formatters: {
+      // Emit the level as a string label instead of the numeric code — easier
+      // for log aggregators. Trace context is injected via `mixin`, never via
+      // `formatters.log` (which cannot see ambient ALS / OTel state).
+      level: (label) => ({ level: label })
+    },
+    serializers,
+    mixin: createTraceContextMixin(logContext, options.otel)
+  };
+  const streams = destinations.map((destination) => ({
+    level: destination.minLevel ?? options.level,
+    stream: destinationToStream(destination)
+  }));
+  return pino(pinoOptions, pino.multistream(streams));
+}
+var DestinationRegistry = class {
+  /**
+   * @param registered - Every destination declared under
+   *   `LOGGER_DESTINATIONS_TOKEN`. Injected by token explicitly because the
+   *   package is bundled without `emitDecoratorMetadata`.
+   * @param logger - Structured logger used to report init failures. Injected by
+   *   token explicitly for the same bundling reason.
+   */
+  constructor(registered, logger) {
+    this.registered = registered;
+    this.logger = logger;
+    /**
+     * Destinations that initialized successfully, in registration order.
+     *
+     * Note: the Pino multistream is built from the full registered list, and the
+     * write path is independently fail-soft (see `destinationToStream`). This set
+     * is the authoritative record of init success — it drives reverse-order
+     * shutdown — but is not currently used to remove a failed-init sink from the
+     * write fan-out; a sink that failed `onInit` still receives writes, contained
+     * fail-soft by the wrapper.
+     */
+    this.active = [];
+  }
+  /**
+   * Initialize every registered destination. A destination whose `onInit`
+   * rejects is skipped (not added to the active set) and reported — it must not
+   * block application bootstrap.
+   */
+  async onModuleInit() {
+    for (const destination of this.registered) {
+      try {
+        await destination.onInit?.();
+        this.active.push(destination);
+      } catch (cause) {
+        this.logger.errorStructured(
+          RESERVED_LOG_KEYS.LOGGER_DESTINATION_INIT_FAILED,
+          cause instanceof Error ? cause : new Error(String(cause)),
+          void 0,
+          { destination: destination.name }
+        );
+      }
+    }
+  }
+  /**
+   * Flush and close active destinations in REVERSE registration order, so a
+   * destination registered first (e.g. stdout) closes last. Failures are written
+   * directly to stderr: `PinoLoggerService` may already be torn down at this
+   * point in the shutdown sequence.
+   */
+  async onApplicationShutdown() {
+    for (const destination of [...this.active].reverse()) {
+      try {
+        await destination.onShutdown?.();
+      } catch (cause) {
+        const detail = cause instanceof Error ? cause.stack ?? cause.message : String(cause);
+        process.stderr.write(
+          `[DestinationRegistry] Shutdown failed for "${destination.name}": ${detail}
+`
+        );
+      }
+    }
+  }
+  /**
+   * The destinations that initialized successfully.
+   *
+   * @returns A read-only view of the active destination set.
+   */
+  getActive() {
+    return this.active;
+  }
+};
+DestinationRegistry = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(LOGGER_DESTINATIONS_TOKEN)),
+  __decorateParam(1, Inject(PinoLoggerService))
+], DestinationRegistry);
+var FORBIDDEN_CONTEXT_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var LogContextService = class {
+  constructor() {
+    this.als = new AsyncLocalStorage();
+  }
+  /**
+   * 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(context, callback) {
+    return this.als.run(this.sanitizeContext(context), callback);
+  }
+  /**
+   * Read the active context, or `undefined` when called outside any scope.
+   *
+   * @returns The active `LogContext`, or `undefined`.
+   */
+  getStore() {
+    return this.als.getStore();
+  }
+  /**
+   * 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, value) {
+    const store = this.als.getStore();
+    if (!store) {
+      throw new Error("[LogContextService] set() called outside run() scope");
+    }
+    if (FORBIDDEN_CONTEXT_KEYS.has(key)) {
+      throw new Error(`[LogContextService] Refusing to set unsafe context key: ${key}`);
+    }
+    Reflect.set(store, key, value);
+  }
+  /**
+   * 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(key) {
+    const store = this.als.getStore();
+    if (!store) {
+      return void 0;
+    }
+    return Reflect.get(store, key);
+  }
+  /**
+   * 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.
+   */
+  sanitizeContext(context) {
+    const safe = {};
+    for (const key of Object.keys(context)) {
+      if (!FORBIDDEN_CONTEXT_KEYS.has(key)) {
+        Reflect.set(safe, key, Reflect.get(context, key));
+      }
+    }
+    return safe;
+  }
+};
+LogContextService = __decorateClass([
+  Injectable()
+], LogContextService);
+
+// src/server/logger.module.ts
+var LOGGER_BOOTSTRAP_TOKEN = /* @__PURE__ */ Symbol("BYMAX_LOGGER_BOOTSTRAP");
+function resolveDestinations(options) {
+  return options.destinations.length > 0 ? options.destinations : [new DefaultStdoutDestination()];
+}
+function bootstrapProvider() {
+  return {
+    provide: LOGGER_BOOTSTRAP_TOKEN,
+    useFactory: (logger) => {
+      logger.info(RESERVED_LOG_KEYS.LOGGER_BOOTSTRAP_OK, "BymaxLoggerModule initialized");
+      return true;
+    },
+    inject: [PinoLoggerService]
+  };
+}
+function buildCommonProviders() {
+  return [
+    LogContextService,
+    { provide: LOG_CONTEXT_TOKEN, useExisting: LogContextService },
+    {
+      provide: LOGGER_PINO_INSTANCE_TOKEN,
+      useFactory: (options, logContext, destinations) => buildPinoInstance(options, logContext, destinations),
+      inject: [LOGGER_OPTIONS_TOKEN, LogContextService, LOGGER_DESTINATIONS_TOKEN]
+    },
+    {
+      provide: LOGGER_DESTINATIONS_TOKEN,
+      useFactory: (options) => resolveDestinations(options),
+      inject: [LOGGER_OPTIONS_TOKEN]
+    },
+    PinoLoggerService,
+    // Internal lifecycle owner for destinations (onInit / onShutdown). Not
+    // exported — consumers never inject it directly.
+    DestinationRegistry,
+    // One child-logger provider per context discovered from @InjectLogger(context).
+    ...collectContextLoggerProviders(),
+    bootstrapProvider()
+  ];
+}
+function asyncHttpInterceptorProvider() {
+  return {
+    provide: APP_INTERCEPTOR,
+    useFactory: (options, logger) => options.http.isEnabled ? new HttpLoggingInterceptor(logger, options) : new PassThroughInterceptor(),
+    inject: [LOGGER_OPTIONS_TOKEN, PinoLoggerService]
+  };
+}
+function augmentLoggerModule(base, providers) {
+  return {
+    ...base,
+    module: BymaxLoggerModule,
+    providers: [...base.providers ?? [], ...providers],
+    exports: [
+      ...base.exports ?? [],
+      LOGGER_OPTIONS_TOKEN,
+      LOGGER_PINO_INSTANCE_TOKEN,
+      LOGGER_DESTINATIONS_TOKEN,
+      LOG_CONTEXT_TOKEN,
+      LogContextService,
+      PinoLoggerService,
+      // Export the per-context child-logger tokens so consumer modules can inject
+      // them (the module is global, so only exported providers are visible).
+      ...collectContextLoggerTokens()
+    ]
+  };
+}
+var BymaxLoggerModule = class 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) {
+    validateOptions(options);
+    const resolved = applyDefaults(options);
+    const providers = [
+      { provide: LOGGER_OPTIONS_TOKEN, useValue: resolved },
+      ...buildCommonProviders()
+    ];
+    if (resolved.http.isEnabled) {
+      providers.push({ provide: APP_INTERCEPTOR, useClass: HttpLoggingInterceptor });
+      if (resolved.http.shouldCaptureExceptions) {
+        providers.push({ provide: APP_FILTER, useClass: HttpExceptionFilter });
+      }
+    }
+    return augmentLoggerModule(super.forRoot(options), providers);
+  }
+  /**
+   * 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) {
+    const providers = [
+      {
+        provide: LOGGER_OPTIONS_TOKEN,
+        useFactory: (raw) => {
+          validateOptions(raw);
+          return applyDefaults(raw);
+        },
+        inject: [BUILDER_OPTIONS_TOKEN]
+      },
+      ...buildCommonProviders(),
+      // Access-log interceptor with parity to the sync path: always registered,
+      // gated at runtime against the async-resolved `http.isEnabled`.
+      asyncHttpInterceptorProvider()
+    ];
+    return augmentLoggerModule(super.forRootAsync(options), providers);
+  }
+  /**
+   * 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) {
+    let logger;
+    try {
+      logger = app.get(PinoLoggerService, { strict: false });
+    } catch (cause) {
+      throw new Error(
+        "[BymaxLoggerModule] useNestLogger(app) called but BymaxLoggerModule was not imported",
+        { cause }
+      );
+    }
+    app.useLogger(logger);
+    app.flushLogs();
+  }
+};
+BymaxLoggerModule = __decorateClass([
+  Module({})
+], BymaxLoggerModule);
+
+// src/server/destinations/pretty-dev.destination.ts
+var PrettyDevDestination = class {
+  /**
+   * @param opts.minLevel — Optional minimum level filter applied by the
+   *   destination registry's multi-stream wiring. Omit to accept every level.
+   */
+  constructor(opts = {}) {
+    this.name = "pretty-dev";
+    /**
+     * 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.
+     */
+    this.initFailed = false;
+    if (opts.minLevel !== void 0) {
+      this.minLevel = opts.minLevel;
+    }
+  }
+  /**
+   * 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.
+   */
+  async onInit() {
+    try {
+      const { build } = await import('pino-pretty');
+      this.stream = build({
+        colorize: true,
+        translateTime: "SYS:HH:MM:ss.l",
+        ignore: "pid,hostname,service",
+        singleLine: false,
+        destination: process.stdout
+      });
+    } catch {
+      this.initFailed = true;
+      throw new Error(
+        "[PrettyDevDestination] pino-pretty is not installed. Install it as a peer dependency (`pnpm add -D pino-pretty`) or remove PrettyDevDestination from `destinations`."
+      );
+    }
+  }
+  /**
+   * 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) {
+    if (this.stream !== void 0) {
+      this.stream.write(payload);
+      return;
+    }
+    if (this.initFailed) {
+      return;
+    }
+    process.stdout.write(payload);
+  }
+  /**
+   * Flush and close the pretty transform, resolving once the stream has ended.
+   * A no-op when {@link onInit} never ran.
+   */
+  async onShutdown() {
+    const stream = this.stream;
+    if (stream === void 0) {
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      stream.once("error", reject);
+      stream.end(resolve);
+    });
+  }
+};
+var REQUEST_ID_HEADER = "x-request-id";
+var MAX_CORRELATION_ID_LENGTH = 256;
+function isAcceptableHeaderValue(value) {
+  return typeof value === "string" && value.length <= MAX_CORRELATION_ID_LENGTH;
+}
+var RequestIdMiddleware = class {
+  /**
+   * @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, options) {
+    this.logContext = logContext;
+    this.tenantIdHeader = options.http.tenantIdHeader;
+    this.shouldGenerateRequestId = options.http.shouldGenerateRequestId;
+  }
+  /**
+   * 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, res, next) {
+    const incoming = Reflect.get(req.headers, REQUEST_ID_HEADER);
+    const fromHeader = isAcceptableHeaderValue(incoming) ? incoming : void 0;
+    const requestId = fromHeader ?? (this.shouldGenerateRequestId ? randomUUID() : void 0);
+    const context = {};
+    if (requestId !== void 0) {
+      res.setHeader(REQUEST_ID_HEADER, requestId);
+      context.requestId = requestId;
+    }
+    const rawTenantId = Reflect.get(req.headers, this.tenantIdHeader);
+    if (isAcceptableHeaderValue(rawTenantId)) {
+      context.tenantId = rawTenantId;
+    }
+    this.logContext.run(context, () => next());
+  }
+};
+RequestIdMiddleware = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(LogContextService)),
+  __decorateParam(1, Inject(LOGGER_OPTIONS_TOKEN))
+], RequestIdMiddleware);
+
+// src/server/middlewares/apply-request-id-middleware.ts
+var ALL_ROUTES = "*";
+function applyRequestIdMiddleware(consumer, routes = ALL_ROUTES) {
+  consumer.apply(RequestIdMiddleware).forRoutes(routes);
+}
+var INJECT_LOGGER_CONTEXT_METADATA_KEY = "bymax_logger:context";
+function InjectLogger(context) {
+  return (target, propertyKey, parameterIndex) => {
+    if (context === void 0) {
+      Inject(PinoLoggerService)(target, propertyKey, parameterIndex);
+      return;
+    }
+    Inject(getContextLoggerToken(context))(target, propertyKey, parameterIndex);
+    Reflect.defineMetadata(
+      INJECT_LOGGER_CONTEXT_METADATA_KEY,
+      context,
+      target,
+      `${String(propertyKey)}:${parameterIndex}`
+    );
+  };
+}
+var LOG_CONTEXT_METADATA_KEY = "bymax_logger:log_context";
+var LogContext = (name) => SetMetadata(LOG_CONTEXT_METADATA_KEY, name);
+
+// src/server/decorators/log-performance.decorator.ts
+var DEFAULT_THRESHOLD_MS = 1e3;
+function emitTimingLog(logger, method, duration, thresholdMs) {
+  if (duration > thresholdMs) {
+    logger.warnStructured(
+      RESERVED_LOG_KEYS.METHOD_SLOW_EXECUTION,
+      `${method} took ${duration}ms (threshold ${thresholdMs}ms)`,
+      void 0,
+      { method, duration, thresholdMs }
+    );
+  } else {
+    logger.info(RESERVED_LOG_KEYS.METHOD_EXECUTION, `${method} completed`, void 0, {
+      method,
+      duration
+    });
+  }
+}
+function LogPerformance(thresholdMs = DEFAULT_THRESHOLD_MS) {
+  return (target, propertyKey, descriptor) => {
+    const original = descriptor.value;
+    const method = `${target.constructor.name}.${String(propertyKey)}`;
+    descriptor.value = async function(...args) {
+      const start = Date.now();
+      try {
+        return await original.apply(this, args);
+      } finally {
+        const duration = Date.now() - start;
+        if (this.logger) {
+          try {
+            emitTimingLog(this.logger, method, duration, thresholdMs);
+          } catch {
+          }
+        }
+      }
+    };
+    return descriptor;
+  };
+}
+
+// src/shared/constants/log-keys-convention.constants.ts
+var LOG_KEYS_CONVENTION_REGEX = /^[A-Z][A-Z0-9_]+_[A-Z][A-Z0-9_]+(_[A-Z][A-Z0-9_]+)?$/;
+
+export { BymaxLoggerModule, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, LogContextService, LogPerformance, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RequestIdMiddleware, applyRequestIdMiddleware };