@bymax-one/nest-core 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -3,13 +3,6 @@ import { DynamicModule, ExceptionFilter, ArgumentsHost, NestInterceptor, Executi
 import { HttpAdapterHost } from '@nestjs/core';
 import { Observable } from 'rxjs';
 
-/**
- * @fileoverview Public configuration surface for `BymaxCoreModule` plus the
- * resolution pipeline that merges consumer options over the documented defaults
- * and deep-freezes the result. Every feature reads its effective configuration
- * from the resolved snapshot, never from the raw consumer input.
- * @layer Config
- */
 /** Error-envelope exception-filter configuration. */
 interface EnvelopeOptions {
     /** Register the global exception filter. Default: `true`. */
@@ -35,6 +28,104 @@ interface HealthOptions {
     path?: string;
     /** Per-indicator timeout before a check is reported as down. Default: `5000`. */
     indicatorTimeoutMs?: number;
+    /**
+     * Aggregate every provider marked with `@BymaxHealthIndicator()`, anywhere in
+     * the application, in addition to those registered under
+     * `BYMAX_HEALTH_INDICATORS`. Default: `false`.
+     *
+     * Off by default because it changes which failures can take an application out
+     * of rotation: a library the application merely imports gains the ability to
+     * fail its readiness probe. That is exactly the point once it is on — the
+     * dependency understands its own health better than the application does — but
+     * it is a decision the application makes, not one it inherits.
+     */
+    autoDiscover?: boolean;
+    /**
+     * Include the failing indicator's message in the readiness response under
+     * `details.error`. Never enable in production. Default: `false`.
+     *
+     * Readiness is typically unauthenticated and reachable by whatever probes it,
+     * and an indicator usually does not author its own failure message — it lets a
+     * driver's error propagate, and driver errors carry hosts, ports and sometimes
+     * credentials. With this off, the response names which indicator is down and
+     * nothing else; the message goes to the logger, where access is already
+     * controlled.
+     */
+    exposeIndicatorErrors?: boolean;
+}
+/** One entry of the OpenAPI document's `servers` list. */
+interface OpenApiServerDescriptor {
+    /** Absolute base URL the API is served from. */
+    url: string;
+    /** Human-readable label for the server, shown in the UI's selector. */
+    description?: string;
+}
+/**
+ * A single OpenAPI security scheme, kept as an open record rather than a closed
+ * union. The specification allows several shapes (HTTP, API key, OAuth2, OpenID
+ * Connect), each with its own required fields, and this package neither
+ * validates nor interprets them: it copies them into the document's components
+ * so the consumer's declaration reaches the UI unchanged.
+ */
+type OpenApiSecurityScheme = Readonly<Record<string, unknown>>;
+/**
+ * OpenAPI document configuration.
+ *
+ * The document and its UI are development-only. Enabling this in a production
+ * runtime does not serve them: the resolver forces the feature off and records
+ * why, and the bootstrap helper refuses to mount independently. See
+ * {@link ResolvedOpenApiOptions.suppressedInProduction}.
+ */
+interface OpenApiOptions {
+    /**
+     * Build and serve the OpenAPI document. Default: `false`. Ignored in a
+     * production runtime, where the feature is always off.
+     */
+    enabled?: boolean;
+    /** Route the interactive UI is served from. Default: `'docs'`. */
+    path?: string;
+    /** Route the raw JSON document is served from. Default: `'docs-json'`. */
+    jsonPath?: string;
+    /** Document title. Default: `'API'`. */
+    title?: string;
+    /** Document description. Default: `''`. */
+    description?: string;
+    /** Document version, independent of the package version. Default: `'1.0.0'`. */
+    version?: string;
+    /** Servers advertised by the document. Default: `[]`. */
+    servers?: readonly OpenApiServerDescriptor[];
+    /** Security schemes added to the document's components. Default: `{}`. */
+    securitySchemes?: Readonly<Record<string, OpenApiSecurityScheme>>;
+    /**
+     * Contribute the schemas this package owns — the error envelope, the health
+     * response, and the pagination shapes — to the document's components.
+     * Default: `true`.
+     */
+    includeCoreSchemas?: boolean;
+}
+/** Trace-correlation configuration. */
+interface TelemetryOptions {
+    /**
+     * Read the active OpenTelemetry span and carry its identifiers into the
+     * request-timing sample and, when {@link TelemetryOptions.exposeTraceId} is
+     * set, the error envelope. Default: `false`.
+     *
+     * This package never creates a span, configures an SDK, or installs an
+     * exporter: it reads what the instrumentation already running produces.
+     */
+    enabled?: boolean;
+    /**
+     * Include `traceId` in the error-envelope body served to the client.
+     * Default: `false`.
+     *
+     * A trace id is not a secret, but it is internal: published in a response it
+     * tells a caller that a tracing backend exists and gives them an identifier
+     * that correlates their request with everything else in that trace. Support
+     * teams often want exactly that; the default is off so it is a decision rather
+     * than a side effect. With this off, the identifiers still reach the timing
+     * sample and, through it, the logs.
+     */
+    exposeTraceId?: boolean;
 }
 /** Prometheus metrics endpoint configuration. */
 interface MetricsOptions {
@@ -60,6 +151,10 @@ interface BymaxCoreModuleOptions {
     health?: HealthOptions;
     /** Prometheus metrics endpoint. Default: disabled. */
     metrics?: MetricsOptions;
+    /** OpenAPI document and UI. Default: disabled, and never served in production. */
+    openapi?: OpenApiOptions;
+    /** Trace correlation. Default: disabled. */
+    telemetry?: TelemetryOptions;
 }
 /** Fully-resolved envelope options. */
 interface ResolvedEnvelopeOptions {
@@ -76,6 +171,13 @@ interface ResolvedHealthOptions {
     enabled: boolean;
     path: string;
     indicatorTimeoutMs: number;
+    exposeIndicatorErrors: boolean;
+    autoDiscover: boolean;
+}
+/** Fully-resolved telemetry options. */
+interface ResolvedTelemetryOptions {
+    enabled: boolean;
+    exposeTraceId: boolean;
 }
 /** Fully-resolved metrics options. */
 interface ResolvedMetricsOptions {
@@ -84,6 +186,30 @@ interface ResolvedMetricsOptions {
     collectDefaultMetrics: boolean;
     defaultLabels: Record<string, string>;
 }
+/** Fully-resolved OpenAPI options. */
+interface ResolvedOpenApiOptions {
+    /**
+     * Whether the document is actually served. This is the consumer's request
+     * intersected with the runtime: it is always `false` in production, whatever
+     * the consumer asked for.
+     */
+    enabled: boolean;
+    /**
+     * `true` when the consumer asked for the document and the production guard
+     * refused it. Carried in the snapshot so the bootstrap helper can tell "the
+     * operator never wanted this" apart from "the operator wanted this and we
+     * declined", and warn only in the second case.
+     */
+    suppressedInProduction: boolean;
+    path: string;
+    jsonPath: string;
+    title: string;
+    description: string;
+    version: string;
+    servers: readonly OpenApiServerDescriptor[];
+    securitySchemes: Readonly<Record<string, OpenApiSecurityScheme>>;
+    includeCoreSchemas: boolean;
+}
 /**
  * The effective, defaults-applied configuration exposed under
  * `BYMAX_CORE_OPTIONS`. Fields with a documented default are always present;
@@ -95,6 +221,8 @@ interface ResolvedCoreOptions {
     timing: ResolvedTimingOptions;
     health: ResolvedHealthOptions;
     metrics: ResolvedMetricsOptions;
+    openapi: ResolvedOpenApiOptions;
+    telemetry: ResolvedTelemetryOptions;
 }
 
 /** Non-option extras accepted by `forRoot` / `forRootAsync`. */
@@ -181,6 +309,12 @@ declare const BYMAX_HEALTH_INDICATORS: unique symbol;
  * lazily and only when the metrics feature is enabled.
  */
 declare const BYMAX_METRICS_REGISTRY: unique symbol;
+/**
+ * Provide the `ITraceContextProvider` that reads the active span's identifiers.
+ * Bound on every path: the real reader when telemetry is enabled, a no-op that
+ * resolves nothing otherwise.
+ */
+declare const BYMAX_TRACE_CONTEXT: unique symbol;
 
 /**
  * @fileoverview Correlation-id contract consumed by the error envelope. The
@@ -202,10 +336,51 @@ interface ICorrelationIdProvider {
     getCorrelationId(): string | undefined;
 }
 
+/**
+ * @fileoverview Reading the active trace, and nothing else.
+ *
+ * When a tracer is running, every log line, error response and timing sample of
+ * a request can carry the same identifiers, which is what turns three separate
+ * signals into one story. This package reads those identifiers; it never starts
+ * a span, never configures an SDK, and never installs an exporter. That belongs
+ * to whatever instrumentation the operator already runs, and duplicating it here
+ * would produce two spans per request.
+ *
+ * `@opentelemetry/api` is an optional peer, but unlike the other two it is read
+ * on every request, so it cannot be imported lazily at the point of use. It is
+ * loaded once while the module resolves and then held: the dynamic import runs
+ * during bootstrap, and only when the feature is enabled.
+ * @layer Provider
+ */
+
+/** The identifiers of the span a request is currently running under. */
+interface TraceContext {
+    /** The trace this request belongs to, as a 32-character hex string. */
+    readonly traceId: string;
+    /** The span currently active, as a 16-character hex string. */
+    readonly spanId: string;
+}
+/**
+ * Resolves the current request's trace identifiers.
+ *
+ * Bound under `BYMAX_TRACE_CONTEXT`. Implementations must be cheap and must
+ * never throw: they run on the error path and on the timing path, where a
+ * failure would replace a real error with a telemetry one.
+ */
+interface ITraceContextProvider {
+    /**
+     * Resolve the identifiers of the currently active span.
+     *
+     * @returns The active trace context, or `undefined` when nothing is traced.
+     */
+    getTraceContext(): TraceContext | undefined;
+}
+
 /**
  * Neutral view of the current request handed to {@link BymaxExceptionFilter}
  * mappers and to the {@link BymaxExceptionFilter.onUnexpectedError} seam. It
- * exposes only the framework-agnostic surface (path, method, correlation id).
+ * exposes only the framework-agnostic surface (path, method, correlation id,
+ * trace id).
  */
 interface FilterErrorContext {
     /** HTTP method, read through the adapter (Express and Fastify neutral). */
@@ -214,6 +389,13 @@ interface FilterErrorContext {
     readonly path: string;
     /** Correlation id for the current request; absent when no provider resolves one. */
     readonly correlationId?: string;
+    /**
+     * Trace the request ran under; absent when telemetry is off or nothing was
+     * recording. Present here whatever `telemetry.exposeTraceId` says: the seam
+     * feeds a logging pipeline, where the id is exactly what makes an error
+     * findable, and only the response body is gated by that option.
+     */
+    readonly traceId?: string;
 }
 /**
  * Global exception filter emitting the stable error envelope. Registered as the
@@ -227,6 +409,8 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
     private readonly now;
     /** The resolved correlation provider, or the no-op fallback when none is bound. */
     private readonly correlation;
+    /** The resolved trace-context provider, or the no-op fallback when none is bound. */
+    private readonly traceContext;
     /**
      * @param options - Resolved core options; drives the `exposeInternals` switch.
      * @param correlation - Provider resolving the current request's correlation id.
@@ -236,7 +420,7 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      *   nothing is bound, this falls back to a no-op that omits `correlationId`.
      * @param adapterHost - Host of the live HTTP adapter, resolved lazily per catch.
      */
-    constructor(options: ResolvedCoreOptions, correlation: ICorrelationIdProvider | undefined, adapterHost: HttpAdapterHost);
+    constructor(options: ResolvedCoreOptions, correlation: ICorrelationIdProvider | undefined, adapterHost: HttpAdapterHost, traceContext?: ITraceContextProvider);
     /**
      * Format the exception into the stable envelope and reply with it.
      *
@@ -246,6 +430,28 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      * @param exception - The error that escaped the handler.
      * @param host - The arguments host for the current execution context.
      */
+    /**
+     * Resolve one optional annotation for the envelope, treating any failure as
+     * "absent".
+     *
+     * Both annotations this filter attaches — the correlation id and the trace id
+     * — come from providers it does not own: one is supplied by the consumer, the
+     * other reads a third-party API. Their contracts say they do not throw, but
+     * this filter is the last thing standing between an error and the client, and
+     * a guarantee that depends on someone else's good behavior is not one. A
+     * failed lookup costs an optional field; an unguarded one would cost the whole
+     * response.
+     *
+     * The failure is deliberately silent, and the same reasoning applies as for
+     * the {@link BymaxExceptionFilter.onUnexpectedError} seam a few lines below:
+     * this runs while an error is already being formatted, so reporting a
+     * telemetry failure here would replace the failure the caller actually needs
+     * to see.
+     *
+     * @param read - The lookup to attempt.
+     * @returns The resolved value, or `undefined` when absent or on failure.
+     */
+    private readAnnotation;
     catch(exception: unknown, host: ArgumentsHost): void;
     /**
      * Select the mapping rule for the exception and build its envelope. An
@@ -326,6 +532,8 @@ type ErrorDetails = readonly unknown[] | Readonly<Record<string, unknown>>;
  * - `details` is present only when structured context exists (validation issues
  *   or, in development, the collapsed internal error).
  * - `correlationId` is present only when a correlation provider resolves an id.
+ * - `traceId` is present only when telemetry is enabled, a span was recording,
+ *   and `telemetry.exposeTraceId` opted into publishing it.
  */
 interface ErrorEnvelope {
     /** HTTP status code of the response. Always present. */
@@ -338,6 +546,8 @@ interface ErrorEnvelope {
     readonly details?: ErrorDetails;
     /** Correlation id for the current request. Present only when a provider resolves one. */
     readonly correlationId?: string;
+    /** Trace this request ran under. Present only when publishing it was opted into. */
+    readonly traceId?: string;
     /** ISO 8601 instant the error was formatted. Always present. */
     readonly timestamp: string;
     /** Request URL path. Always present. */
@@ -359,6 +569,8 @@ interface BuildErrorEnvelopeInput {
     readonly details?: ErrorDetails;
     /** Correlation id. Omit when none is bound; never pass `undefined`. */
     readonly correlationId?: string;
+    /** Trace id. Omit when absent or not opted into; never pass `undefined`. */
+    readonly traceId?: string;
     /** Request URL path. */
     readonly path: string;
     /** Injectable clock; called once to stamp the ISO 8601 timestamp. */
@@ -420,6 +632,14 @@ interface RequestTimingSample {
     durationMs: number;
     /** Whether the sample exceeded the configured slow-request threshold. */
     slow: boolean;
+    /**
+     * Trace this request ran under. Present only when telemetry is enabled and a
+     * span was recording, so a sink can correlate the sample with the trace
+     * without deciding what "no trace" looks like.
+     */
+    traceId?: string;
+    /** Span active when the request completed. Present under the same conditions. */
+    spanId?: string;
 }
 /**
  * Receive request-timing samples. Implementations must never throw: a sink
@@ -446,6 +666,8 @@ declare class TimingInterceptor implements NestInterceptor {
     private readonly clock;
     /** The bound timing sink, or the no-op fallback when none resolves. */
     private readonly sink;
+    /** The bound trace-context provider, or the no-op fallback when none resolves. */
+    private readonly traceContext;
     /**
      * @param options - Resolved core options; supplies `slowRequestThresholdMs`.
      * @param sink - The bound timing sink; its `record` failures are swallowed.
@@ -456,8 +678,12 @@ declare class TimingInterceptor implements NestInterceptor {
      * @param clock - Monotonic clock seam; defaults to `performance.now()`, and
      *   is bound explicitly through {@link BYMAX_TIMING_CLOCK} so tests inject a
      *   stub advancing by controlled amounts.
+     * @param traceContext - Reads the active span's identifiers. Injected with
+     *   `@Optional()` so this interceptor stays constructible on its own; when
+     *   nothing resolves, a no-op resolves no trace and the sample simply omits
+     *   the fields.
      */
-    constructor(options: ResolvedCoreOptions, sink: ITimingSink | undefined, clock?: MonotonicClock);
+    constructor(options: ResolvedCoreOptions, sink: ITimingSink | undefined, clock?: MonotonicClock, traceContext?: ITraceContextProvider);
     /**
      * Measure the handler chain and record exactly one sample per completed
      * request, on the success path and on the error path alike.
@@ -547,4 +773,4 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type MetricsOptions, type RequestTimingSample, type ResolvedCoreOptions, TimingInterceptor, type TimingOptions, buildErrorEnvelope, codeForStatus };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiOptions, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, buildErrorEnvelope, codeForStatus };