logixia 1.3.1 → 1.5.0

package/dist/index.d.ts

@@ -1,8 +1,95 @@
-import { A as RequestMetrics, C as SamplingConfig, D as HttpError, E as TraceIdExtractorConfig, O as HttpRequest, S as RequestContext, T as TraceIdConfig, _ as LogLevelString, a as Environment, b as NamespaceLevels, c as GracefulShutdownConfig, d as ILogger, f as ILoggerDefault, g as LogLevel, h as LogFieldKey, i as DEFAULT_LOG_LEVELS, j as RequestTiming, k as HttpResponse, l as IBaseLogger, m as LogEntry, n as CustomLevelMethods, o as ErrorSerializationOptions, p as LogColor, r as DEFAULT_LOG_COLORS, s as ExtractLevels, t as ContextData, u as ILogFormatter, v as LoggerConfig, w as TimingEntry, x as RedactConfig, y as LoggerWithLevels } from "./index-CHIsdA9n.js";
-import { a as LogixiaOptionsFactory, c as LogixiaLoggerService, i as LogixiaLoggerModule, l as LogixiaLogger, n as LOGIXIA_LOGGER_PREFIX, o as WebSocketTraceInterceptor, r as LogixiaAsyncOptions, s as KafkaTraceInterceptor, t as LOGIXIA_LOGGER_CONFIG, u as createLogger$1 } from "./logitron-logger.module-Bq3_KckP.js";
+import { C as SamplingConfig, E as TraceIdExtractorConfig, G as RequestTiming, H as HttpRequest, S as RequestContext, T as TraceIdConfig, U as HttpResponse, V as HttpError, W as RequestMetrics, _ as LogLevelString, a as Environment, b as NamespaceLevels, c as GracefulShutdownConfig, d as ILogger, f as ILoggerDefault, g as LogLevel, h as LogFieldKey, i as DEFAULT_LOG_LEVELS, l as IBaseLogger, m as LogEntry, n as CustomLevelMethods, o as ErrorSerializationOptions, p as LogColor, r as DEFAULT_LOG_COLORS, s as ExtractLevels, t as ContextData, u as ILogFormatter, v as LoggerConfig, w as TimingEntry, x as RedactConfig, y as LoggerWithLevels } from "./index-t-ActikQ.js";
+import { a as LogixiaOptionsFactory, c as LogixiaLoggerService, d as LogixiaPlugin, f as PluginRegistry, i as LogixiaLoggerModule, l as LogixiaLogger, m as usePlugin, n as LOGIXIA_LOGGER_PREFIX, o as WebSocketTraceInterceptor, p as globalPluginRegistry, r as LogixiaAsyncOptions, s as KafkaTraceInterceptor, t as LOGIXIA_LOGGER_CONFIG, u as createLogger$1 } from "./logitron-logger.module-CMRBDGwm.js";
 import "./search-Cg_OasF-.js";
+import { ArgumentsHost, ExceptionFilter } from "@nestjs/common";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { IncomingMessage, ServerResponse } from "node:http";
 
+//#region src/core/nestjs-extras.d.ts
+
+/**
+ * Inject the Logixia logger registered in the current NestJS DI container.
+ *
+ * Equivalent to `@Inject(LOGIXIA_LOGGER_TOKEN)` but without needing to import
+ * the internal token constant yourself.
+ *
+ * @example
+ * ```ts
+ * constructor(@InjectLogger() private readonly logger: LogixiaLoggerService) {}
+ * ```
+ */
+declare const InjectLogger: () => ParameterDecorator;
+interface LogMethodOptions {
+  /**
+   * Log level to use for entry / exit messages.
+   * @default 'debug'
+   */
+  level?: 'debug' | 'info' | 'verbose';
+  /**
+   * Whether to log the arguments passed to the method.
+   * Disable for high-throughput hot paths.
+   * @default true
+   */
+  logArgs?: boolean;
+  /**
+   * Whether to log the return value of the method.
+   * @default false
+   */
+  logResult?: boolean;
+  /**
+   * Whether to log error stack traces for thrown errors.
+   * @default true
+   */
+  logErrors?: boolean;
+  /**
+   * Custom label used in log messages instead of the auto-detected class.method name.
+   */
+  label?: string;
+}
+/**
+ * Method decorator that auto-logs entry, exit, duration, and errors.
+ *
+ * Works on both async and sync methods. Attaches to the logger found on the
+ * class instance via a `logger` property (the conventional NestJS name).
+ *
+ * @example
+ * ```ts
+ * @LogMethod({ level: 'info', logArgs: true })
+ * async processPayment(orderId: string): Promise<void> { … }
+ * ```
+ */
+declare function LogMethod(options?: LogMethodOptions): MethodDecorator;
+/**
+ * Global NestJS exception filter that converts any exception into the standard
+ * `LogixiaErrorResponse` wire format and logs it with full request context.
+ *
+ * Handles three exception types in priority order:
+ *  1. `LogixiaException`     — typed fields used directly
+ *  2. NestJS `HttpException` — status + message extracted
+ *  3. Unknown / plain Error  — falls back to 500 `server_error`
+ *
+ * **Debug stripping in production:**
+ * The `debug` block is automatically stripped when `NODE_ENV === 'production'`.
+ *
+ * **Trace ID headers:**
+ * `X-Trace-ID` and `X-Request-ID` are echoed back on every error response so
+ * clients can correlate with server logs.
+ *
+ * **Retry-After header:**
+ * Automatically added for `429` responses (`Retry-After: 60`).
+ *
+ * Register in `main.ts`:
+ * ```ts
+ * const logger = app.get(LogixiaLoggerService);
+ * app.useGlobalFilters(new LogixiaExceptionFilter(logger));
+ * ```
+ */
+declare class LogixiaExceptionFilter implements ExceptionFilter {
+  private readonly logger?;
+  constructor(logger?: LogixiaLoggerService | undefined);
+  catch(exception: unknown, host: ArgumentsHost): void;
+}
+//#endregion
 //#region src/formatters/json.formatter.d.ts
 declare class JsonFormatter implements ILogFormatter {
   private includeTimestamp;
@@ -71,6 +158,118 @@ declare function isError(value: unknown): value is Error;
  */
 declare function normalizeError(error: unknown): Error;
 //#endregion
+//#region src/utils/otel.d.ts
+/**
+ * logixia — OpenTelemetry auto trace-log correlation
+ *
+ * Zero-config: if `@opentelemetry/api` is installed, logixia automatically
+ * reads the active span context and injects `traceId`, `spanId`, and
+ * `traceFlags` into every log entry. No manual wiring needed.
+ *
+ * The integration is completely optional — if `@opentelemetry/api` is absent
+ * (or the OTel SDK is not initialised), all helpers return `undefined` silently.
+ *
+ * Additionally exposes a `createOtelLogExporter()` factory that routes every
+ * logixia log entry through the active OTel LoggerProvider (OTLP export).
+ *
+ * @example Auto bridge (zero config)
+ * ```ts
+ * import { createLogger } from 'logixia';
+ * import { initOtelBridge } from 'logixia';
+ *
+ * // Call once at app startup, after your OTel SDK is initialised
+ * initOtelBridge();
+ *
+ * const logger = createLogger({ appName: 'api' });
+ * // Every logger.info / warn / error call now auto-injects traceId + spanId
+ * // from the currently active OTel span — no per-call code needed.
+ * ```
+ *
+ * @example Manual span context injection
+ * ```ts
+ * import { getActiveOtelContext } from 'logixia';
+ *
+ * const ctx = getActiveOtelContext();
+ * await logger.info('Payment processed', { ...ctx, orderId: 'ord_123' });
+ * // → { traceId: 'abc...', spanId: 'def...', traceFlags: 1, orderId: 'ord_123' }
+ * ```
+ */
+interface OtelSpanContext {
+  /** W3C 32-hex-char trace ID */
+  traceId: string;
+  /** W3C 16-hex-char span ID */
+  spanId: string;
+  /** W3C trace-flags integer (1 = sampled) */
+  traceFlags: number;
+  /** Whether this context is from a valid, sampled span */
+  isSampled: boolean;
+}
+interface OtelBridgeOptions {
+  /**
+   * Field name written to log entries for the trace ID.
+   * @default 'traceId'
+   */
+  traceIdField?: string;
+  /**
+   * Field name written to log entries for the span ID.
+   * @default 'spanId'
+   */
+  spanIdField?: string;
+  /**
+   * Field name written to log entries for trace flags.
+   * @default 'traceFlags'
+   */
+  traceFlagsField?: string;
+  /**
+   * Only inject context when the span is sampled (traceFlags bit 1 set).
+   * @default false
+   */
+  sampledOnly?: boolean;
+}
+/**
+ * Read the currently active OTel span context (if any) and return its fields
+ * in a plain object suitable for spreading into a log entry.
+ *
+ * Returns `undefined` when:
+ * - `@opentelemetry/api` is not installed
+ * - No active span exists (root context)
+ * - The span context is invalid (all-zeros)
+ */
+declare function getActiveOtelContext(opts?: OtelBridgeOptions): OtelSpanContext | undefined;
+/**
+ * Returns a metadata object with OTel context fields ready to merge into a log call,
+ * using the configured field names.
+ *
+ * Returns `{}` when no active span exists (safe to spread unconditionally).
+ *
+ * @example
+ * ```ts
+ * await logger.info('Payment processed', {
+ *   ...getOtelMetaFields(),
+ *   orderId: 'ord_123',
+ * });
+ * ```
+ */
+declare function getOtelMetaFields(opts?: OtelBridgeOptions): Record<string, unknown>;
+/**
+ * Initialise the global OTel bridge.
+ *
+ * Once called, logixia's internal log pipeline checks for an active OTel span
+ * on **every** log call and automatically merges the span context into the
+ * entry's metadata — no per-call wiring needed.
+ *
+ * Call once at app startup, **after** the OTel SDK has been initialised:
+ * ```ts
+ * import { initOtelBridge } from 'logixia';
+ * initOtelBridge();
+ * ```
+ */
+declare function initOtelBridge(opts?: OtelBridgeOptions): void;
+/**
+ * Disable the OTel bridge (useful for tests).
+ */
+declare function disableOtelBridge(): void;
+//#endregion
 //#region src/utils/redact.utils.d.ts
 /**
  * Deep-clone and redact an object according to the given RedactConfig.
@@ -173,6 +372,106 @@ declare const DEFAULT_TRACE_HEADERS: string[];
  */
 declare function createTraceMiddleware(config: TraceIdConfig): (req: unknown, res: unknown, next: () => void) => void;
 //#endregion
+//#region src/utils/typed-logger.d.ts
+/**
+ * logixia — TypeScript typed log fields
+ *
+ * Solves the type-safety gap: standard `Record<string, unknown>` metadata gives
+ * zero IDE autocomplete and lets typos slip silently into production logs.
+ *
+ * Two complementary utilities:
+ *
+ * 1. `createTypedLogger<TFields>()` — wraps any IBaseLogger so that the second
+ *    argument of every log method is constrained to `TFields` (a typed object).
+ *    Compile-time safety, zero runtime overhead.
+ *
+ * 2. `defineLogSchema<TFields>(schema)` — declares expected fields with optional
+ *    validators. In development (NODE_ENV !== 'production') every log call is
+ *    validated against the schema and a warning is emitted for missing required
+ *    fields or type mismatches.
+ *
+ * @example
+ * ```ts
+ * import { createTypedLogger, defineLogSchema } from 'logixia';
+ *
+ * interface OrderFields {
+ *   orderId: string;
+ *   userId: string;
+ *   amount?: number;
+ *   currency?: string;
+ * }
+ *
+ * const schema = defineLogSchema<OrderFields>({
+ *   orderId: { type: 'string', required: true },
+ *   userId:  { type: 'string', required: true },
+ *   amount:  { type: 'number' },
+ *   currency: { type: 'string' },
+ * });
+ *
+ * const orderLogger = createTypedLogger<OrderFields>(baseLogger, schema);
+ * await orderLogger.info('Order created', { orderId: 'ord_123', userId: 'usr_456', amount: 99.99 });
+ * //                                       ^^^^ fully typed autocomplete ^^^^
+ * ```
+ */
+type LogFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+interface LogFieldDef {
+  type: LogFieldType;
+  /** Emit a warning when this field is missing from the log call. Default: false */
+  required?: boolean;
+  /** Custom validator — return a string to emit it as a warning message. */
+  validate?: (value: unknown) => string | undefined;
+}
+type LogSchema<TFields extends Record<string, unknown>> = { [K in keyof TFields]: LogFieldDef };
+interface CompiledSchema<TFields extends Record<string, unknown>> {
+  readonly fields: LogSchema<TFields>;
+  /**
+   * Validate a payload against the schema.
+   * Returns an array of warning strings (empty = pass).
+   * Only runs in non-production environments.
+   */
+  validate(payload: Partial<TFields>): string[];
+}
+/**
+ * Define a typed schema for a category of log entries.
+ *
+ * Call this once at module initialisation and pass it to `createTypedLogger`.
+ * In development, every log call is validated against the schema.
+ */
+declare function defineLogSchema<TFields extends Record<string, unknown>>(fields: LogSchema<TFields>): CompiledSchema<TFields>;
+/** IBaseLogger-compatible subset used by TypedLogger */
+interface LoggerLike {
+  error(message: string | Error, data?: Record<string, unknown>): Promise<void>;
+  warn(message: string, data?: Record<string, unknown>): Promise<void>;
+  info(message: string, data?: Record<string, unknown>): Promise<void>;
+  debug(message: string, data?: Record<string, unknown>): Promise<void>;
+  verbose?(message: string, data?: Record<string, unknown>): Promise<void>;
+  trace?(message: string, data?: Record<string, unknown>): Promise<void>;
+}
+/**
+ * A logger whose metadata is typed to `TFields`.
+ *
+ * The `error` overload still accepts a plain `Error` object as the first arg
+ * (with optional `TFields` data) so the typed logger remains a drop-in replacement.
+ */
+interface TypedLogger<TFields extends Record<string, unknown>> {
+  error(error: Error, data?: Partial<TFields>): Promise<void>;
+  error(message: string, data?: Partial<TFields>): Promise<void>;
+  warn(message: string, data?: Partial<TFields>): Promise<void>;
+  info(message: string, data?: Partial<TFields>): Promise<void>;
+  debug(message: string, data?: Partial<TFields>): Promise<void>;
+  verbose(message: string, data?: Partial<TFields>): Promise<void>;
+  trace(message: string, data?: Partial<TFields>): Promise<void>;
+  /** Access the underlying untyped logger if needed. */
+  readonly raw: LoggerLike;
+}
+/**
+ * Wrap any logixia logger with a type-safe field interface.
+ *
+ * @param logger  Any object that implements `IBaseLogger` (e.g. the result of `createLogger()`)
+ * @param schema  Optional schema for dev-time validation. Created with `defineLogSchema()`.
+ */
+declare function createTypedLogger<TFields extends Record<string, unknown>>(logger: LoggerLike, schema?: CompiledSchema<TFields>): TypedLogger<TFields>;
+//#endregion
 //#region src/context/async-context.d.ts
 interface LogContext {
   requestId?: string;
@@ -259,6 +558,438 @@ interface SamplingStats {
   windowStart: number;
 }
 //#endregion
+//#region src/exceptions/types.d.ts
+/**
+ * Unified error response shape for logixia.
+ *
+ * Design-inspired by Stripe (`type` + `code` + `param`), GitHub (`details[]`),
+ * Twilio (`doc_url`), and Cloudflare (`success: false` envelope).
+ *
+ * The shape is intentionally framework-agnostic — it works for HTTP, WebSocket,
+ * Queue/RPC, and any other transport. Your exception filter is responsible for
+ * serialising it onto the wire.
+ *
+ * @template TCode - Union of valid error code strings you define (e.g. `'PE-AUTH-001' | 'PE-USR-001'`).
+ *                   Defaults to `string` for untyped usage.
+ * @template TType - Union of valid error type strings you define (e.g. `'authentication_error' | 'validation_error'`).
+ *                   Defaults to `string` for untyped usage.
+ *
+ * @example Fully typed usage
+ * ```ts
+ * type AppCode = 'PE-AUTH-001' | 'PE-VAL-001';
+ * type AppType = 'authentication_error' | 'validation_error';
+ *
+ * const response: LogixiaErrorResponse<AppCode, AppType> = { ... };
+ * ```
+ */
+interface LogixiaErrorResponse<TCode extends string = string, TType extends string = string> {
+  /** Always `false` — allows `if (response.success)` branching on the client. */
+  success: false;
+  error: {
+    /**
+     * Broad category that tells the client **how** to handle this error.
+     * e.g. `'validation_error'` → show field errors; `'authentication_error'` → redirect to login.
+     */
+    type: TType;
+    /**
+     * Machine-readable, stable error identifier.
+     * e.g. `'PE-AUTH-001'` — never changes; safe to switch/match on.
+     */
+    code: TCode;
+    /**
+     * Human-readable message shown to the end-user.
+     * May change between releases — do not rely on it programmatically.
+     */
+    message: string;
+    /**
+     * The specific request field that caused this error (Stripe pattern).
+     * e.g. `'email'` | `'metadata.name'`
+     */
+    param?: string;
+    /**
+     * Array of field-level errors for batch validation failures (GitHub pattern).
+     * Only present when more than one field is invalid.
+     */
+    details?: ErrorDetail[];
+    /**
+     * Documentation URL for this specific error (Twilio pattern).
+     * e.g. `'https://docs.example.com/errors/PE-AUTH-001'`
+     */
+    doc_url?: string;
+  };
+  meta: {
+    /** ULID / UUID-based request identifier for log correlation. */
+    request_id: string;
+    /** ISO 8601 timestamp of when the error was produced. */
+    timestamp: string;
+    /** Request path that caused the error. e.g. `'/api/v1/auth/login'` */
+    path: string;
+    /** HTTP status code mirrored in the body for clients that can't read headers. */
+    status: number;
+  };
+  /**
+   * Developer / diagnostic context.
+   *
+   * ⚠️ **Strip this in production.** The `ErrorResponseBuilder` always populates it
+   * (when possible); your exception filter should call `delete response.debug` before
+   * sending the response when `NODE_ENV === 'production'`.
+   */
+  debug?: {
+    /** Full stack trace of the underlying error. */
+    stack?: string;
+    /** Serialised `error.cause` (ES 2022 chained errors). */
+    cause?: string;
+    /** Originating micro-service name. e.g. `'gatekeeper'` | `'worker'` */
+    service?: string;
+    /** Wall-clock time in ms from `request.startTime` to error handling. */
+    duration_ms?: number;
+  };
+}
+/**
+ * A single field-level validation error (GitHub pattern).
+ *
+ * @example
+ * ```ts
+ * { field: 'email', message: 'must be a valid email address', code: 'invalid_format' }
+ * { field: 'password', message: 'required',                   code: 'required'       }
+ * ```
+ */
+interface ErrorDetail {
+  /** Dot-notation field path. e.g. `'email'` | `'user.address.zip'` */
+  field: string;
+  /** Human-readable reason this field failed. */
+  message: string;
+  /**
+   * Machine-readable failure code for this field.
+   * Suggested values: `'required'` | `'invalid_format'` | `'too_long'` | `'too_short'` |
+   * `'out_of_range'` | `'invalid_enum_value'` | `'duplicate'`
+   */
+  code: string;
+}
+//#endregion
+//#region src/exceptions/builder.d.ts
+/** Input parameters for `ErrorResponseBuilder.build`. */
+interface BuildParams {
+  /** The caught exception — any type. */
+  exception: unknown;
+  /**
+   * Request / correlation ID to embed in `meta.request_id`.
+   * If omitted a UUID-based ID is auto-generated: `req_<uuid without dashes>`.
+   */
+  requestId?: string | undefined;
+  /** Request path. e.g. `'/api/v1/auth/login'` */
+  path: string;
+  /**
+   * Originating service name for `debug.service`.
+   * e.g. `process.env.SERVICE_NAME` → `'gatekeeper'`
+   */
+  service?: string | undefined;
+  /**
+   * `Date.now()` captured at the start of the request.
+   * When present, `debug.duration_ms` is computed automatically.
+   */
+  startTime?: number | undefined;
+}
+/**
+ * Generates a `req_` prefixed request ID using Node's built-in `crypto.randomUUID`.
+ * No extra dependencies required.
+ *
+ * @example `'req_550e8400e29b41d4a716446655440000'`
+ */
+declare function generateRequestId(): string;
+declare class ErrorResponseBuilder {
+  /**
+   * Build a `LogixiaErrorResponse` from any thrown value.
+   *
+   * @param params - See `BuildParams`.
+   * @returns The unified error response and the HTTP status code to send.
+   *
+   * @example In a NestJS exception filter
+   * ```ts
+   * const { response, httpStatus } = ErrorResponseBuilder.build<AppCode, AppType>({
+   *   exception,
+   *   requestId: request.headers['x-trace-id'] as string | undefined,
+   *   path:      request.url,
+   *   service:   process.env.SERVICE_NAME,
+   *   startTime: request.startTime,
+   * });
+   *
+   * if (process.env.NODE_ENV === 'production') delete response.debug;
+   * response.setHeader('X-Trace-ID', response.meta.request_id);
+   * response.status(httpStatus).json(response);
+   * ```
+   */
+  static build<TCode extends string = string, TType extends string = string>(params: BuildParams): {
+    response: LogixiaErrorResponse<TCode, TType>;
+    httpStatus: number;
+  };
+}
+//#endregion
+//#region src/exceptions/exception.d.ts
+/**
+ * Constructor options for `LogixiaException`.
+ *
+ * All user-supplied fields — logixia only owns the wire format.
+ */
+interface LogixiaExceptionOptions<TCode extends string = string, TType extends string = string> {
+  /**
+   * Machine-readable, stable error code.
+   * e.g. `'PE-AUTH-001'`
+   */
+  code: TCode;
+  /**
+   * Broad error type category.
+   * e.g. `'authentication_error'` | `'validation_error'` | `'rate_limit_error'`
+   */
+  type: TType;
+  /**
+   * HTTP status code to send on the wire.
+   * e.g. `401` | `400` | `429` | `500`
+   */
+  httpStatus: number;
+  /**
+   * Human-readable message for the end-user.
+   * This IS sent in the response body — keep it safe (no internal paths, etc.).
+   */
+  message: string;
+  /**
+   * The specific request field that caused this error (Stripe pattern).
+   * e.g. `'email'` | `'metadata.name'`
+   */
+  param?: string;
+  /**
+   * Array of per-field validation errors (GitHub pattern).
+   * Typically used for `400` / `422` validation failures.
+   */
+  details?: ErrorDetail[];
+  /**
+   * Documentation URL for this error (Twilio pattern).
+   * e.g. `'https://docs.example.com/errors/PE-AUTH-001'`
+   */
+  docUrl?: string;
+  /**
+   * Original error for ES 2022 cause chaining.
+   * Serialised into `debug.cause` by the `ErrorResponseBuilder`.
+   * Never sent to the client in production.
+   */
+  cause?: Error;
+  /**
+   * Arbitrary metadata for logging purposes only.
+   * This is **never** included in the HTTP response — it is passed to your
+   * logger / monitoring integrations through the exception object.
+   *
+   * @example
+   * ```ts
+   * metadata: { userId: 'u_abc', attemptCount: 3 }
+   * ```
+   */
+  metadata?: Record<string, unknown>;
+}
+declare class LogixiaException<TCode extends string = string, TType extends string = string> extends Error {
+  /** @readonly The machine-readable error code supplied by the caller. */
+  readonly errorCode: TCode;
+  /** @readonly The error type category supplied by the caller. */
+  readonly errorType: TType;
+  /** @readonly HTTP status code to respond with. */
+  readonly httpStatus: number;
+  /** @readonly Field pointer that caused this error (Stripe pattern). */
+  readonly param: string | undefined;
+  /** @readonly Field-level validation errors (GitHub pattern). */
+  readonly details: ErrorDetail[] | undefined;
+  /** @readonly Documentation URL for this error (Twilio pattern). */
+  readonly docUrl: string | undefined;
+  /**
+   * @readonly Extra context for your logger — never serialised into the HTTP response.
+   */
+  readonly metadata: Record<string, unknown> | undefined;
+  constructor(options: LogixiaExceptionOptions<TCode, TType>);
+}
+/**
+ * Returns `true` when `value` is a `LogixiaException` instance.
+ *
+ * Useful in exception filters or middleware that need to distinguish a
+ * `LogixiaException` from a plain `Error` or a framework `HttpException`.
+ *
+ * @example
+ * ```ts
+ * if (isLogixiaException(err)) {
+ *   console.log(err.errorCode, err.httpStatus);
+ * }
+ * ```
+ */
+declare function isLogixiaException<TCode extends string = string, TType extends string = string>(value?: unknown): value is LogixiaException<TCode, TType>;
+//#endregion
+//#region src/metrics.d.ts
+/**
+ * Increment a counter on each matching log entry.
+ *
+ * @example Count every error entry, labelled by context:
+ * ```ts
+ * error_count: { type: 'counter', levelFilter: 'error', labels: ['context'] }
+ * ```
+ *
+ * @example Count entries where payload.event === 'checkout':
+ * ```ts
+ * checkout_events: { type: 'counter', field: 'event', value: 'checkout' }
+ * ```
+ */
+interface CounterConfig {
+  type: 'counter';
+  /** Only increment when `entry.level` equals this value. Omit to count all entries. */
+  levelFilter?: string;
+  /**
+   * Only increment when `entry.payload[field] === value`.
+   * If omitted, every entry (matching `levelFilter`) is counted.
+   */
+  field?: string;
+  value?: unknown;
+  /** `entry.payload` fields used as Prometheus label dimensions. `'level'` is also valid. */
+  labels?: string[];
+  help?: string;
+}
+/**
+ * Observe a numeric payload field and bucket it into a Prometheus histogram.
+ *
+ * @example Duration histogram labelled by HTTP method and status code:
+ * ```ts
+ * http_request_duration: {
+ *   type: 'histogram',
+ *   field: 'duration',
+ *   labels: ['method', 'statusCode'],
+ *   buckets: [10, 25, 50, 100, 250, 500, 1000],
+ * }
+ * ```
+ */
+interface HistogramConfig {
+  type: 'histogram';
+  /** The `entry.payload` field containing the numeric value to observe. */
+  field: string;
+  /** `entry.payload` fields used as Prometheus label dimensions. */
+  labels?: string[];
+  help?: string;
+  /**
+   * Bucket upper bounds (inclusive). Sorted automatically.
+   * Default: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]
+   */
+  buckets?: number[];
+}
+/**
+ * Track the most recent numeric value of a payload field as a gauge.
+ *
+ * @example Track live connection count:
+ * ```ts
+ * active_connections: { type: 'gauge', field: 'connections' }
+ * ```
+ */
+interface GaugeConfig {
+  type: 'gauge';
+  /** The `entry.payload` field containing the numeric value. */
+  field: string;
+  /** `entry.payload` fields used as Prometheus label dimensions. */
+  labels?: string[];
+  help?: string;
+}
+type MetricConfig = CounterConfig | HistogramConfig | GaugeConfig;
+type MetricsMap = Record<string, MetricConfig>;
+/**
+ * A logixia plugin that extracts Prometheus-compatible metrics from log entries.
+ *
+ * Implements `LogixiaPlugin` — pass directly to `logger.use()`:
+ * ```ts
+ * const metrics = new MetricsPlugin({ ... });
+ * logger.use(metrics);
+ * ```
+ *
+ * Or use the `createMetricsPlugin()` factory (preferred):
+ * ```ts
+ * const metrics = createMetricsPlugin({ ... });
+ * logger.use(metrics);
+ * ```
+ */
+declare class MetricsPlugin implements LogixiaPlugin {
+  readonly name = "logixia-metrics";
+  private readonly map;
+  private readonly metricState;
+  constructor(map: MetricsMap);
+  onInit(): void;
+  onLog(entry: LogEntry): LogEntry;
+  /**
+   * Render all registered metrics in the Prometheus text exposition format
+   * (version 0.0.4).
+   *
+   * All metric names are prefixed with `logixia_`.
+   *
+   * @example
+   * ```
+   * # HELP logixia_error_count Total error log entries
+   * # TYPE logixia_error_count counter
+   * logixia_error_count{context="OrderService"} 7
+   * ```
+   */
+  render(): string;
+  /**
+   * Reset all metric counters and observations back to zero.
+   * Useful between test runs or on a scheduled reset interval.
+   */
+  reset(): void;
+  /**
+   * Express route handler — call `app.get('/metrics', metrics.expressHandler())`.
+   *
+   * @example
+   * ```ts
+   * import express from 'express';
+   * const app = express();
+   * app.get('/metrics', metrics.expressHandler());
+   * ```
+   */
+  expressHandler(): (req: unknown, res: {
+    set(k: string, v: string): unknown;
+    end(body: string): void;
+  }) => void;
+  /**
+   * Raw Node.js `http` server handler.
+   * Responds to `GET /metrics` with the Prometheus text payload.
+   *
+   * @example Start a dedicated metrics server on the standard port:
+   * ```ts
+   * import http from 'node:http';
+   * const server = http.createServer(metrics.httpHandler());
+   * server.listen(9464); // Prometheus default port for custom exporters
+   * ```
+   */
+  httpHandler(): (req: IncomingMessage, res: ServerResponse) => void;
+  private initAllState;
+  private initSingleState;
+}
+/**
+ * Create a `MetricsPlugin` from a metrics map and return it ready for
+ * `logger.use()`.
+ *
+ * @example
+ * ```ts
+ * import { createMetricsPlugin } from 'logixia';
+ *
+ * const metrics = createMetricsPlugin({
+ *   http_request_duration: {
+ *     type: 'histogram',
+ *     field: 'duration',
+ *     labels: ['method', 'statusCode'],
+ *     help: 'HTTP request duration in milliseconds',
+ *   },
+ *   error_count: {
+ *     type: 'counter',
+ *     levelFilter: 'error',
+ *     labels: ['context'],
+ *     help: 'Total error log entries',
+ *   },
+ * });
+ *
+ * logger.use(metrics);
+ * app.get('/metrics', metrics.expressHandler());
+ * ```
+ */
+declare function createMetricsPlugin(map: MetricsMap): MetricsPlugin;
+//#endregion
 //#region src/index.d.ts
 /**
  * Default configuration for Logixia logger
@@ -345,5 +1076,5 @@ declare const logger: LogixiaLogger<{
   outputs: string[];
 }>;
 //#endregion
-export { ContextData, CustomLevelMethods, DEFAULT_CONFIG, DEFAULT_LOG_COLORS, DEFAULT_LOG_LEVELS, DEFAULT_TRACE_HEADERS, Environment, ErrorSerializationOptions, ExtractLevels, FlushOnExitOptions, GracefulShutdownConfig, HttpError, HttpRequest, HttpResponse, IBaseLogger, ILogFormatter, ILogger, ILoggerDefault, JsonFormatter, KafkaTraceInterceptor, LOGIXIA_LOGGER_CONFIG, LOGIXIA_LOGGER_PREFIX, LogColor, type LogContext, LogEntry, LogFieldKey, LogLevel, LogLevelString, LoggerConfig, LoggerConfig as LoggerConfigInterface, LoggerWithLevels, LogixiaAsyncOptions, LogixiaContext, LogixiaLogger, LogixiaLoggerModule, LogixiaLoggerService, LogixiaOptionsFactory, NamespaceLevels, type RedactConfig, RequestContext, RequestMetrics, RequestTiming, SamplingConfig, type SamplingStats, TextFormatter, TimingEntry, TraceIdConfig, TraceIdExtractorConfig, WebSocketTraceInterceptor, applyRedaction, createExpressContextMiddleware, createFastifyContextHook, createLogger, createLoggerService, createTraceMiddleware, deregisterFromShutdown, extractTraceId, flushOnExit, generateTraceId, getCurrentTraceId, isError, logger, normalizeError, redactObject, registerForShutdown, resetShutdownHandlers, runWithTraceId, serializeError, setTraceId, traceStorage };
+export { type BuildParams, type CompiledSchema, ContextData, type CounterConfig, CustomLevelMethods, DEFAULT_CONFIG, DEFAULT_LOG_COLORS, DEFAULT_LOG_LEVELS, DEFAULT_TRACE_HEADERS, Environment, type ErrorDetail, ErrorResponseBuilder, ErrorSerializationOptions, ExtractLevels, FlushOnExitOptions, type GaugeConfig, GracefulShutdownConfig, type HistogramConfig, HttpError, HttpRequest, HttpResponse, IBaseLogger, ILogFormatter, ILogger, ILoggerDefault, InjectLogger, JsonFormatter, KafkaTraceInterceptor, LOGIXIA_LOGGER_CONFIG, LOGIXIA_LOGGER_PREFIX, LogColor, type LogContext, LogEntry, type LogFieldDef, LogFieldKey, type LogFieldType, LogLevel, LogLevelString, LogMethod, type LogMethodOptions, type LogSchema, LoggerConfig, LoggerConfig as LoggerConfigInterface, type LoggerLike, LoggerWithLevels, LogixiaAsyncOptions, LogixiaContext, type LogixiaErrorResponse, LogixiaException, LogixiaExceptionFilter, type LogixiaExceptionOptions, LogixiaLogger, LogixiaLoggerModule, LogixiaLoggerService, LogixiaOptionsFactory, type LogixiaPlugin, type MetricConfig, type MetricsMap, MetricsPlugin, NamespaceLevels, type OtelBridgeOptions, type OtelSpanContext, PluginRegistry, type RedactConfig, RequestContext, RequestMetrics, RequestTiming, SamplingConfig, type SamplingStats, TextFormatter, TimingEntry, TraceIdConfig, TraceIdExtractorConfig, type TypedLogger, WebSocketTraceInterceptor, applyRedaction, createExpressContextMiddleware, createFastifyContextHook, createLogger, createLoggerService, createMetricsPlugin, createTraceMiddleware, createTypedLogger, defineLogSchema, deregisterFromShutdown, disableOtelBridge, extractTraceId, flushOnExit, generateRequestId, generateTraceId, getActiveOtelContext, getCurrentTraceId, getOtelMetaFields, globalPluginRegistry, initOtelBridge, isError, isLogixiaException, logger, normalizeError, redactObject, registerForShutdown, resetShutdownHandlers, runWithTraceId, serializeError, setTraceId, traceStorage, usePlugin };
 //# sourceMappingURL=index.d.ts.map