@horizon-republic/nestjs-jetstream 2.9.0 → 2.10.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { ModuleMetadata, FactoryProvider, Type, Logger, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
-import { MsgHdrs, ConnectionOptions, NatsConnection, Status, Msg } from '@nats-io/transport-node';
-import { StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg } from '@nats-io/jetstream';
-import { MessageHandler, Server, CustomTransportStrategy, ClientProxy, ReadPacket, WritePacket, BaseRpcContext } from '@nestjs/microservices';
+import { Logger, ModuleMetadata, FactoryProvider, Type, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
+import { MsgHdrs, NatsConnection, Status, ConnectionOptions, Msg } from '@nats-io/transport-node';
+import { JetStreamManager, JetStreamClient, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, ConsumerInfo, JsMsg } from '@nats-io/jetstream';
+import { Span } from '@opentelemetry/api';
+import { ClientProxy, ReadPacket, WritePacket, MessageHandler, Server, CustomTransportStrategy, BaseRpcContext } from '@nestjs/microservices';
 import { Observable } from 'rxjs';
 
 /**
@@ -117,6 +118,689 @@ interface JetstreamHealthStatus {
     latency: number | null;
 }
 
+/**
+ * Instrumentation scope name reported on every span the library emits.
+ * Matches the npm package name — the convention used by
+ * `@opentelemetry/instrumentation-*` and most third-party instrumentations.
+ */
+declare const TRACER_NAME = "@horizon-republic/nestjs-jetstream";
+
+/**
+ * Enumeration of OpenTelemetry trace kinds this library can emit.
+ *
+ * Each identifier is toggleable via `otel.traces`. Functional kinds (publish,
+ * consume, RPC client round-trip, dead letter) are enabled by default;
+ * infrastructure kinds (connection lifecycle, self-healing, provisioning,
+ * migration, shutdown) are opt-in.
+ *
+ * @example
+ *   JetstreamModule.forRoot({
+ *     otel: {
+ *       traces: [JetstreamTrace.Publish, JetstreamTrace.Consume, JetstreamTrace.ConnectionLifecycle],
+ *     },
+ *   })
+ */
+declare enum JetstreamTrace {
+    /** `PRODUCER` span around each `emit()` / `send()` publish operation. Default: ON. */
+    Publish = "publish",
+    /**
+     * `CONSUMER` span around each message delivery to a handler. Retries
+     * produce separate spans with `messaging.nats.message.delivery_count > 1`.
+     * Default: ON.
+     */
+    Consume = "consume",
+    /**
+     * `CLIENT` span covering a full RPC round-trip on the caller side
+     * (`client.send()` → reply received). Wraps the inner publish.
+     * Default: ON.
+     */
+    RpcClientSend = "rpc.client.send",
+    /**
+     * `INTERNAL` span emitted when a message exhausts `maxDeliver` and is
+     * dead-lettered. Captures the duration of the `onDeadLetter` callback.
+     * Default: ON.
+     */
+    DeadLetter = "dead_letter",
+    /**
+     * `INTERNAL` span spanning one NATS connection session. Emits events on
+     * connect, reconnect, disconnect. Default: OFF.
+     */
+    ConnectionLifecycle = "connection.lifecycle",
+    /**
+     * `INTERNAL` span per consumer recovery attempt following a transient
+     * failure (deleted consumer, missed heartbeat). Default: OFF.
+     */
+    SelfHealing = "self_healing",
+    /** `INTERNAL` span per stream or consumer provisioning / update at startup. Default: OFF. */
+    Provisioning = "provisioning",
+    /** `INTERNAL` span covering a destructive migration flow. Default: OFF. */
+    Migration = "migration",
+    /** `INTERNAL` span covering the graceful shutdown sequence. Default: OFF. */
+    Shutdown = "shutdown"
+}
+/**
+ * The set of trace kinds enabled when `otel.traces` is not configured
+ * (or set to `'default'`). Covers message-flow operations; infrastructure
+ * spans are opt-in.
+ */
+declare const DEFAULT_TRACES: readonly JetstreamTrace[];
+
+/**
+ * Central event bus for transport lifecycle notifications.
+ *
+ * Dispatches events to user-provided hooks. Events without a
+ * registered hook are silently ignored — no default logging.
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus(logger, {
+ *   [TransportEvent.Error]: (err) => sentry.captureException(err),
+ * });
+ *
+ * bus.emit(TransportEvent.Error, new Error('timeout'), 'rpc-router');
+ * // → calls sentry
+ *
+ * bus.emit(TransportEvent.Connect, 'nats://localhost:4222');
+ * // → no-op (no hook registered)
+ * ```
+ */
+declare class EventBus {
+    private readonly hooks;
+    private readonly logger;
+    constructor(logger: Logger, hooks?: Partial<TransportHooks>);
+    /**
+     * Emit a lifecycle event. Dispatches to custom hook if registered, otherwise no-op.
+     *
+     * @param event - The {@link TransportEvent} to emit.
+     * @param args - Arguments matching the hook signature for this event.
+     */
+    emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
+    /**
+     * Hot-path optimized emit for MessageRouted events.
+     * Avoids rest/spread overhead of the generic `emit()`.
+     */
+    emitMessageRouted(subject: string, kind: MessageKind): void;
+    /**
+     * Check whether a hook is registered for the given event.
+     *
+     * Used by the routing hot path to elide the emit call entirely when the
+     * transport owner did not register a listener.
+     */
+    hasHook(event: keyof TransportHooks): boolean;
+    private callHook;
+}
+
+/**
+ * Manages the lifecycle of a single NATS connection shared across the application.
+ *
+ * Provides both Promise-based and Observable-based access to the connection:
+ * - `connect()` / `getConnection()` — async/await for one-time setup
+ * - `nc$` — cached observable (shareReplay) for reactive consumers
+ * - `status$` — live connection status event stream
+ *
+ * One instance per application, created by `JetstreamModule.forRoot()`.
+ */
+declare class ConnectionProvider {
+    private readonly options;
+    private readonly eventBus;
+    /** Cached observable that replays the established connection to new subscribers. */
+    readonly nc$: Observable<NatsConnection>;
+    /** Live stream of connection status events (no replay). */
+    readonly status$: Observable<Status>;
+    private readonly logger;
+    private connection;
+    private connectionPromise;
+    private jsClient;
+    private jsmInstance;
+    private jsmPromise;
+    private readonly otel;
+    private readonly otelServiceName;
+    private readonly otelEndpoint;
+    private lifecycleSpan;
+    constructor(options: JetstreamModuleOptions, eventBus: EventBus);
+    /**
+     * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
+     *
+     * @throws Error if connection is refused (fail fast).
+     */
+    getConnection(): Promise<NatsConnection>;
+    /**
+     * Get the JetStream manager. Cached after first call.
+     *
+     * @returns The JetStreamManager for stream/consumer administration.
+     */
+    getJetStreamManager(): Promise<JetStreamManager>;
+    /**
+     * Get a cached JetStream client.
+     *
+     * Invalidated automatically on reconnect and shutdown so consumers always
+     * operate against the live connection.
+     *
+     * @returns The cached JetStreamClient.
+     * @throws Error if the connection has not been established yet.
+     */
+    getJetStreamClient(): JetStreamClient;
+    /** Direct access to the raw NATS connection, or `null` if not yet connected. */
+    get unwrap(): NatsConnection | null;
+    /**
+     * Gracefully shut down the connection.
+     *
+     * Sequence: drain → wait for close. Falls back to force-close on error.
+     */
+    shutdown(): Promise<void>;
+    private initJetStreamManager;
+    /** Internal: establish the physical connection with reconnect monitoring. */
+    private establish;
+    /** Handle a single `nc.status()` event, emitting hooks and span events. */
+    private handleStatusEvent;
+    /** Subscribe to connection status events and emit hooks. */
+    private monitorStatus;
+}
+
+/**
+ * NestJS ClientProxy implementation for the JetStream transport.
+ *
+ * Supports two operational modes:
+ * - **Core mode** (default): Uses `nc.request()` for RPC, `nc.publish()` for events.
+ * - **JetStream mode**: Uses `js.publish()` for RPC commands + inbox for responses.
+ *
+ * Events always go through JetStream publish for guaranteed delivery.
+ * The mode only affects RPC (request/reply) behavior.
+ *
+ * Clients are lightweight — they share the NATS connection from `forRoot()`.
+ */
+declare class JetstreamClient extends ClientProxy {
+    private readonly rootOptions;
+    private readonly connection;
+    private readonly codec;
+    private readonly eventBus;
+    private readonly logger;
+    /** Target service name this client sends messages to. */
+    private readonly targetName;
+    /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
+    private readonly callerName;
+    /**
+     * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
+     * per stream kind this client may publish to. Built once in the constructor
+     * so producing a full subject is a single string concat with the user pattern.
+     */
+    private readonly eventSubjectPrefix;
+    private readonly commandSubjectPrefix;
+    private readonly orderedSubjectPrefix;
+    /**
+     * RPC configuration snapshots. The values are derived from rootOptions at
+     * construction time so the publish hot path never has to re-run
+     * isCoreRpcMode / getRpcTimeout on every call.
+     */
+    private readonly isCoreMode;
+    private readonly defaultRpcTimeout;
+    /** Resolved OpenTelemetry configuration, computed once in the constructor. */
+    private readonly otel;
+    /** Server endpoint parts used for `server.address` / `server.port` span attributes. */
+    private readonly serverEndpoint;
+    /** Shared inbox for JetStream-mode RPC responses. */
+    private inbox;
+    private inboxSubscription;
+    /** Pending JetStream-mode RPC callbacks, keyed by correlation ID. */
+    private readonly pendingMessages;
+    /** Pending JetStream-mode RPC timeouts, keyed by correlation ID. */
+    private readonly pendingTimeouts;
+    /** Subscription to connection status events for disconnect handling. */
+    private statusSubscription;
+    /**
+     * Cached readiness flag. Once `connect()` has wired the inbox and status
+     * subscription, subsequent publishes skip the `await connect()` microtask
+     * and reach for the underlying connection synchronously instead.
+     */
+    private readyForPublish;
+    constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
+    /**
+     * Establish connection. Called automatically by NestJS on first use.
+     *
+     * Sets up the JetStream RPC inbox (if in JetStream mode) and subscribes
+     * to connection status events for fail-fast disconnect handling.
+     *
+     * @returns The underlying NATS connection.
+     */
+    connect(): Promise<NatsConnection>;
+    /** Clean up resources: reject pending RPCs, unsubscribe from status events. */
+    close(): Promise<void>;
+    /**
+     * Direct access to the raw NATS connection.
+     *
+     * @throws Error if not connected.
+     */
+    unwrap<T = NatsConnection>(): T;
+    /**
+     * Publish a fire-and-forget event to JetStream.
+     *
+     * Events are published to either the workqueue stream or broadcast stream
+     * depending on the subject prefix. When a schedule is present the message
+     * is published to a `_sch` subject within the same stream, with the target
+     * set to the original event subject.
+     */
+    protected dispatchEvent<T = unknown>(packet: ReadPacket): Promise<T>;
+    /**
+     * Publish an RPC command and register callback for response.
+     *
+     * Core mode: uses nc.request() with timeout.
+     * JetStream mode: publishes to stream + waits for inbox response.
+     */
+    protected publish(packet: ReadPacket, callback: (p: WritePacket) => void): () => void;
+    /** Core mode: nc.request() with timeout. */
+    private publishCoreRpc;
+    /** JetStream mode: publish to stream + wait for inbox response. */
+    private publishJetStreamRpc;
+    /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
+    private handleDisconnect;
+    /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
+    private rejectPendingRpcs;
+    /** Setup shared inbox subscription for JetStream RPC responses. */
+    private setupInbox;
+    /** Route an inbox reply to the matching pending callback. */
+    private routeInboxReply;
+    /**
+     * Resolve a user pattern to a fully-qualified NATS subject, dispatching
+     * between the event, broadcast, and ordered prefixes.
+     *
+     * The leading-char check short-circuits the `startsWith` comparisons for
+     * patterns that cannot possibly carry a broadcast/ordered marker, which is
+     * the overwhelmingly common case.
+     */
+    private buildEventSubject;
+    /** Build NATS headers merging custom headers with transport headers. */
+    private buildHeaders;
+    /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
+    private extractRecordData;
+    /**
+     * Build a schedule-holder subject for NATS message scheduling.
+     *
+     * The schedule-holder subject resides in the same stream as the target but
+     * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
+     * NATS holds the message and publishes it to the target subject after the delay.
+     *
+     * Examples:
+     * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
+     * - `broadcast.config.updated` → `broadcast._sch.config.updated`
+     */
+    private buildScheduleSubject;
+}
+
+/**
+ * Immutable message record for JetStream transport.
+ *
+ * Compatible with NestJS record builder pattern (like RmqRecord, NatsRecord).
+ * Pass as the second argument to `client.send()` or `client.emit()`.
+ *
+ * @example
+ * ```typescript
+ * const record = new JetstreamRecordBuilder({ id: 1 })
+ *   .setHeader('x-tenant', 'acme')
+ *   .setTimeout(5000)
+ *   .build();
+ *
+ * client.send('get.user', record);
+ * ```
+ */
+declare class JetstreamRecord<TData = unknown> {
+    /** Message payload. */
+    readonly data: TData;
+    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
+    readonly headers: ReadonlyMap<string, string>;
+    /** Per-request RPC timeout override in ms. */
+    readonly timeout?: number | undefined;
+    /** Custom message ID for JetStream deduplication. */
+    readonly messageId?: string | undefined;
+    /** Schedule options for delayed delivery. */
+    readonly schedule?: ScheduleRecordOptions | undefined;
+    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
+    readonly ttl?: string | undefined;
+    constructor(
+    /** Message payload. */
+    data: TData, 
+    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
+    headers: ReadonlyMap<string, string>, 
+    /** Per-request RPC timeout override in ms. */
+    timeout?: number | undefined, 
+    /** Custom message ID for JetStream deduplication. */
+    messageId?: string | undefined, 
+    /** Schedule options for delayed delivery. */
+    schedule?: ScheduleRecordOptions | undefined, 
+    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
+    ttl?: string | undefined);
+}
+/**
+ * Fluent builder for constructing JetstreamRecord instances.
+ *
+ * Protected headers (`correlation-id`, `reply-to`, `error`) cannot be
+ * set by the user — attempting to do so throws an error at build time.
+ */
+declare class JetstreamRecordBuilder<TData = unknown> {
+    private data;
+    private readonly headers;
+    private timeout;
+    private messageId;
+    private scheduleOptions;
+    private ttlDuration;
+    constructor(data?: TData);
+    /**
+     * Set the message payload.
+     *
+     * @param data - Payload to serialize via the configured {@link Codec}.
+     */
+    setData(data: TData): this;
+    /**
+     * Set a single custom header.
+     *
+     * @param key - Header name (e.g. `'x-tenant'`).
+     * @param value - Header value.
+     * @throws Error if the header name is reserved by the transport.
+     */
+    setHeader(key: string, value: string): this;
+    /**
+     * Set multiple custom headers at once.
+     *
+     * @param headers - Key-value pairs to set as headers.
+     * @throws Error if any header name is reserved by the transport.
+     */
+    setHeaders(headers: Record<string, string>): this;
+    /**
+     * Set a custom message ID for JetStream deduplication.
+     *
+     * NATS JetStream uses this ID to detect duplicate publishes within the
+     * stream's `duplicate_window`. If two messages with the same ID arrive
+     * within the window, the second is silently dropped.
+     *
+     * When not set, a random UUID is generated automatically.
+     *
+     * @param id - Unique message identifier (e.g. order ID, idempotency key).
+     *
+     * @example
+     * ```typescript
+     * new JetstreamRecordBuilder(data)
+     *   .setMessageId(`order-${order.id}`)
+     *   .build();
+     * ```
+     */
+    setMessageId(id: string): this;
+    /**
+     * Set per-request RPC timeout.
+     *
+     * @param ms - Timeout in milliseconds. Overrides the global RPC timeout for this request only.
+     */
+    setTimeout(ms: number): this;
+    /**
+     * Schedule one-shot delayed delivery.
+     *
+     * The message is held by NATS and delivered to the event consumer
+     * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
+     * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
+     *
+     * Only meaningful for events (`client.emit()`). If used with RPC
+     * (`client.send()`), a warning is logged and the schedule is ignored.
+     *
+     * @param date - Delivery time. Must be in the future.
+     * @throws Error if the date is not in the future.
+     */
+    scheduleAt(date: Date): this;
+    /**
+     * Set per-message TTL (time-to-live).
+     *
+     * The message expires individually after the specified duration,
+     * independent of the stream's `max_age`. Requires NATS >= 2.11 and
+     * `allow_msg_ttl: true` on the stream.
+     *
+     * Only meaningful for events (`client.emit()`). If used with RPC
+     * (`client.send()`), a warning is logged and the TTL is ignored.
+     *
+     * @param nanos - TTL in nanoseconds. Use {@link toNanos} for human-readable values.
+     *
+     * @example
+     * ```typescript
+     * import { toNanos } from '@horizon-republic/nestjs-jetstream';
+     *
+     * new JetstreamRecordBuilder(payload).ttl(toNanos(30, 'minutes')).build();
+     * new JetstreamRecordBuilder(payload).ttl(toNanos(24, 'hours')).build();
+     * ```
+     */
+    ttl(nanos: number): this;
+    /**
+     * Build the immutable {@link JetstreamRecord}.
+     *
+     * @returns A frozen record ready to pass to `client.send()` or `client.emit()`.
+     */
+    build(): JetstreamRecord<TData>;
+    /**
+     * Validate that a header key is not reserved. NATS treats header names
+     * case-insensitively, so the check is against the lowercase form to keep
+     * `'X-Correlation-ID'`, `'x-correlation-id'`, and any other casing in
+     * lockstep. `RESERVED_HEADERS` is defined as an all-lowercase set.
+     */
+    private validateHeaderKey;
+}
+
+/** Tag attached to every outgoing publish span so consumers can distinguish event / RPC / broadcast / ordered flows. */
+declare enum PublishKind {
+    Event = "event",
+    RpcRequest = "rpc.request",
+    Broadcast = "broadcast",
+    Ordered = "ordered"
+}
+/** Tag attached to every incoming consume span. `Rpc` covers both Core and JetStream RPC handlers. */
+declare enum ConsumeKind {
+    Event = "event",
+    Rpc = "rpc",
+    Broadcast = "broadcast",
+    Ordered = "ordered"
+}
+/**
+ * Handler metadata for the dispatched message. `pattern` is always set;
+ * `className` / `methodName` come from NestJS reflection when available.
+ */
+interface HandlerMetadata {
+    readonly pattern: string;
+    readonly className?: string;
+    readonly methodName?: string;
+}
+/**
+ * Host / port pair surfaced as `server.address` / `server.port` span
+ * attributes. `port` is optional — OTel semconv makes it conditional on
+ * being different from the protocol default, and we'd rather emit nothing
+ * than invent a number the user never configured.
+ */
+interface ServerEndpoint {
+    readonly host: string;
+    readonly port?: number;
+}
+/**
+ * Minimum message shape the consume span helper requires. Both `JsMsg`
+ * (JetStream) and Core NATS `Msg` satisfy it structurally; JetStream-only
+ * delivery metadata (`info`) is read separately and omitted on the Core
+ * RPC path.
+ */
+interface ConsumeSourceMsg {
+    readonly subject: string;
+    readonly data: Uint8Array;
+    readonly headers?: MsgHdrs;
+}
+/** Context passed to {@link OtelOptions.publishHook} for an outgoing publish. */
+interface JetstreamPublishContext {
+    /** Fully-resolved subject the message is being published to. */
+    readonly subject: string;
+    /** The record being published (payload, headers, builder-supplied options). */
+    readonly record: JetstreamRecord;
+    /** Classification of the outgoing operation. */
+    readonly kind: PublishKind;
+}
+/** Context passed to {@link OtelOptions.consumeHook} for an incoming dispatch. */
+interface JetstreamConsumeContext {
+    /** Fully-resolved subject of the incoming message. */
+    readonly subject: string;
+    /**
+     * The incoming NATS message. JetStream messages (events, broadcast,
+     * ordered, JetStream RPC) satisfy `JsMsg`; Core RPC messages satisfy
+     * the looser {@link ConsumeSourceMsg} shape only. Narrow on `kind` to
+     * decide which fields are safe to access.
+     */
+    readonly msg: ConsumeSourceMsg;
+    /** Handler metadata; see {@link HandlerMetadata}. */
+    readonly handlerMetadata: HandlerMetadata;
+    /** Classification of the incoming operation. */
+    readonly kind: ConsumeKind;
+}
+/** Context passed to {@link OtelOptions.responseHook} once an outcome is known, just before the span ends. */
+interface JetstreamResponseContext {
+    /** Subject the operation targeted. */
+    readonly subject: string;
+    /** Wall-clock duration of the operation in milliseconds. */
+    readonly durationMs: number;
+    /** Decoded reply payload for RPC client spans when available. */
+    readonly reply?: unknown;
+    /** Error instance if the operation failed. */
+    readonly error?: Error;
+}
+/**
+ * Classification outcome for a thrown error. Affects span status and
+ * attributes only — reply envelopes and internal logging are unchanged.
+ */
+type ErrorClassification = 'expected' | 'unexpected';
+/** Object form of {@link OtelOptions.captureBody}. */
+interface CaptureBodyOptions {
+    /**
+     * Maximum number of bytes to capture. Payloads longer than this are
+     * truncated; a `messaging.nats.message.body.truncated` attribute is
+     * added to indicate truncation occurred.
+     *
+     * @default 4096
+     */
+    readonly maxBytes?: number;
+    /**
+     * Only capture body for subjects matching these glob patterns. Each
+     * pattern supports `*` wildcards and an optional leading `!` for
+     * exclusion. When omitted, body capture applies to all subjects.
+     */
+    readonly subjectAllowlist?: readonly string[];
+}
+/**
+ * OpenTelemetry configuration for `JetstreamModule.forRoot({ otel: … })`.
+ * All fields are optional; when the host app has not registered an OTel
+ * SDK, every call made by the library is a no-op regardless of config.
+ */
+interface OtelOptions {
+    /**
+     * Global kill switch. When `false`, no spans are emitted, no propagation
+     * is attempted, and no hooks fire.
+     *
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /**
+     * Which trace kinds to emit.
+     *
+     * - `'default'` — publish, consume, RPC client round-trip, dead letter
+     * - `'all'` — every trace kind defined in {@link JetstreamTrace}
+     * - `'none'` — emit no spans at all (useful with `enabled: true` for
+     *   pure trace-context propagation without the span overhead)
+     * - `JetstreamTrace[]` — explicit selection
+     *
+     * @default 'default'
+     */
+    readonly traces?: readonly JetstreamTrace[] | 'default' | 'all' | 'none';
+    /**
+     * Header names to capture as span attributes (`messaging.header.<name>`).
+     * Match is case-insensitive. Glob wildcards (`*`) and negation (`!prefix-*`)
+     * are supported in the per-pattern form.
+     *
+     * SECURITY / GDPR: headers may contain authentication tokens, session
+     * identifiers, or other sensitive data. Captured values are exported to
+     * the configured OTel backend. Use an explicit allowlist in production.
+     * Setting this to `true` captures every header and is intended for
+     * development environments only.
+     *
+     * Transport-internal headers (`x-correlation-id`, `x-reply-to`, `x-error`,
+     * `x-subject`, `x-caller-name`) and propagator-owned headers
+     * (`traceparent`, `tracestate`, `baggage`, `sentry-trace`, `b3`, …) are
+     * always suppressed regardless of the allowlist.
+     *
+     * @default ['x-request-id']
+     */
+    readonly captureHeaders?: readonly string[] | boolean;
+    /**
+     * Capture the message payload as the `messaging.nats.message.body` span
+     * attribute. Defaults to `false` for privacy and cost reasons.
+     *
+     * Passing `true` captures up to 4 KiB per message. Use the object form
+     * for finer control over size and subject scope.
+     *
+     * SECURITY / GDPR: payloads commonly contain PII, credentials, financial
+     * data, or content regulated by HIPAA / PCI-DSS. Enabling body capture
+     * in production is almost always a policy violation. Prefer enabling
+     * only in development, or pair with a custom `SpanProcessor` that
+     * scrubs or drops the attribute before export.
+     *
+     * @default false
+     */
+    readonly captureBody?: boolean | CaptureBodyOptions;
+    /**
+     * Invoked after a publish span has been started and before the actual
+     * publish call executes. Use to enrich the span with custom attributes.
+     * Must be synchronous — thrown errors are caught and logged at debug
+     * level without affecting the publish path.
+     */
+    publishHook?(span: Span, ctx: JetstreamPublishContext): void;
+    /**
+     * Invoked after a consume span has been started and before the handler
+     * is dispatched. Use to enrich the span with custom attributes derived
+     * from the incoming message or handler metadata.
+     */
+    consumeHook?(span: Span, ctx: JetstreamConsumeContext): void;
+    /**
+     * Invoked once an operation's outcome is known (success, error, or
+     * timeout) and the span status has been set, just before the span ends.
+     * Fires for publish, consume, and RPC client spans.
+     */
+    responseHook?(span: Span, ctx: JetstreamResponseContext): void;
+    /**
+     * Predicate evaluated at the top of every outgoing publish. Returning
+     * `false` skips span creation for that publish; propagation of trace
+     * context through headers still occurs, so downstream consumers are
+     * unaffected. Useful for suppressing noise from health-check or
+     * internal-only subjects.
+     */
+    shouldTracePublish?(subject: string, record: JetstreamRecord): boolean;
+    /**
+     * Predicate evaluated at the top of every incoming message delivery.
+     * Returning `false` skips span creation for that delivery; the handler
+     * still executes normally and trace context is still extracted from
+     * headers for downstream calls.
+     */
+    shouldTraceConsume?(subject: string, msg: ConsumeSourceMsg): boolean;
+    /**
+     * Classify a thrown error as `'expected'` (business error, part of the
+     * RPC contract) or `'unexpected'` (infrastructure failure or bug). Drives
+     * OpenTelemetry span status and attributes only.
+     *
+     * - `'expected'` → span status `OK` with `jetstream.rpc.reply.has_error`
+     *   and `jetstream.rpc.reply.error.code` attributes
+     * - `'unexpected'` → span status `ERROR` with `span.recordException(err)`
+     *
+     * Reply envelopes delivered to RPC clients are identical in both cases.
+     * This classification affects only the observability artifact.
+     *
+     * The default recognizes NestJS-idiomatic primitives for business errors:
+     * `RpcException` and `HttpException`. Teams with custom error hierarchies
+     * override to recognize their own types.
+     *
+     * @example
+     *   errorClassifier: (err) => {
+     *     if (err instanceof MyDomainError) return 'expected';
+     *     if (err?.code?.startsWith('BIZ_')) return 'expected';
+     *     return 'unexpected';
+     *   }
+     */
+    errorClassifier?(err: unknown): ErrorClassification;
+}
+
 /**
  * Stream config overrides exposed to users.
  *
@@ -385,6 +1069,16 @@ interface JetstreamModuleOptions {
      * Merged with `name` and `servers` — those take precedence.
      */
     connectionOptions?: Partial<ConnectionOptions>;
+    /**
+     * OpenTelemetry integration. When omitted, sensible defaults are applied:
+     * tracing is enabled, default trace kinds are emitted, only standard
+     * correlation headers are captured. If no OTel SDK is registered in the
+     * consuming application, all tracer calls are no-ops — there is no
+     * runtime cost.
+     *
+     * @see OtelOptions
+     */
+    otel?: OtelOptions;
 }
 /** Options for `JetstreamModule.forFeature()`. */
 interface JetstreamFeatureOptions {
@@ -490,105 +1184,6 @@ interface RpcRouterOptions {
     ackExtension?: boolean | number;
 }
 
-/**
- * Central event bus for transport lifecycle notifications.
- *
- * Dispatches events to user-provided hooks. Events without a
- * registered hook are silently ignored — no default logging.
- *
- * @example
- * ```typescript
- * const bus = new EventBus(logger, {
- *   [TransportEvent.Error]: (err) => sentry.captureException(err),
- * });
- *
- * bus.emit(TransportEvent.Error, new Error('timeout'), 'rpc-router');
- * // → calls sentry
- *
- * bus.emit(TransportEvent.Connect, 'nats://localhost:4222');
- * // → no-op (no hook registered)
- * ```
- */
-declare class EventBus {
-    private readonly hooks;
-    private readonly logger;
-    constructor(logger: Logger, hooks?: Partial<TransportHooks>);
-    /**
-     * Emit a lifecycle event. Dispatches to custom hook if registered, otherwise no-op.
-     *
-     * @param event - The {@link TransportEvent} to emit.
-     * @param args - Arguments matching the hook signature for this event.
-     */
-    emit<K extends keyof TransportHooks>(event: K, ...args: Parameters<TransportHooks[K]>): void;
-    /**
-     * Hot-path optimized emit for MessageRouted events.
-     * Avoids rest/spread overhead of the generic `emit()`.
-     */
-    emitMessageRouted(subject: string, kind: MessageKind): void;
-    private callHook;
-}
-
-/**
- * Manages the lifecycle of a single NATS connection shared across the application.
- *
- * Provides both Promise-based and Observable-based access to the connection:
- * - `connect()` / `getConnection()` — async/await for one-time setup
- * - `nc$` — cached observable (shareReplay) for reactive consumers
- * - `status$` — live connection status event stream
- *
- * One instance per application, created by `JetstreamModule.forRoot()`.
- */
-declare class ConnectionProvider {
-    private readonly options;
-    private readonly eventBus;
-    /** Cached observable that replays the established connection to new subscribers. */
-    readonly nc$: Observable<NatsConnection>;
-    /** Live stream of connection status events (no replay). */
-    readonly status$: Observable<Status>;
-    private readonly logger;
-    private connection;
-    private connectionPromise;
-    private jsClient;
-    private jsmInstance;
-    private jsmPromise;
-    constructor(options: JetstreamModuleOptions, eventBus: EventBus);
-    /**
-     * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
-     *
-     * @throws Error if connection is refused (fail fast).
-     */
-    getConnection(): Promise<NatsConnection>;
-    /**
-     * Get the JetStream manager. Cached after first call.
-     *
-     * @returns The JetStreamManager for stream/consumer administration.
-     */
-    getJetStreamManager(): Promise<JetStreamManager>;
-    /**
-     * Get a cached JetStream client.
-     *
-     * Invalidated automatically on reconnect and shutdown so consumers always
-     * operate against the live connection.
-     *
-     * @returns The cached JetStreamClient.
-     * @throws Error if the connection has not been established yet.
-     */
-    getJetStreamClient(): JetStreamClient;
-    /** Direct access to the raw NATS connection, or `null` if not yet connected. */
-    get unwrap(): NatsConnection | null;
-    /**
-     * Gracefully shut down the connection.
-     *
-     * Sequence: drain → wait for close. Falls back to force-close on error.
-     */
-    shutdown(): Promise<void>;
-    private initJetStreamManager;
-    /** Internal: establish the physical connection with reconnect monitoring. */
-    private establish;
-    /** Subscribe to connection status events and emit hooks. */
-    private monitorStatus;
-}
-
 /**
  * Registry mapping NATS subjects to NestJS message handlers.
  *
@@ -651,13 +1246,15 @@ declare class PatternRegistry {
  * This is the default RPC mode — lowest latency, no persistence overhead.
  */
 declare class CoreRpcServer {
-    private readonly options;
     private readonly connection;
     private readonly patternRegistry;
     private readonly codec;
     private readonly eventBus;
     private readonly logger;
     private subscription;
+    private readonly otel;
+    private readonly serviceName;
+    private readonly serverEndpoint;
     constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus);
     /** Start listening for RPC requests on the command subject. */
     start(): Promise<void>;
@@ -684,6 +1281,9 @@ declare class StreamProvider {
     private readonly connection;
     private readonly logger;
     private readonly migration;
+    private readonly otel;
+    private readonly otelServiceName;
+    private readonly otelEndpoint;
     constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
     /**
      * Ensure all required streams exist with correct configuration.
@@ -727,21 +1327,6 @@ declare class StreamProvider {
     private stripTransportControlled;
 }
 
-/**
- * Routes incoming event messages (workqueue, broadcast, and ordered) to NestJS handlers.
- *
- * **Workqueue & Broadcast** — at-least-once delivery:
- * - Success -> ack | Error -> nak (retry) | Dead letter -> term
- *
- * **Ordered** — strict sequential delivery:
- * - No ack/nak/DLQ — nats.js auto-acknowledges ordered consumer messages.
- * - Handler errors are logged but do not affect delivery.
- *
- * **Dead-Letter Queue (DLQ) - for handling failed message deliveries**
- * - If `options.dlq` is configured, messages that exhaust their max delivery attempts are published to a DLQ stream.
- * - The DLQ stream name is derived from the service name (e.g., `orders__microservice_dlq-stream`).
- * - Original message data and metadata are preserved in the DLQ message, with additional headers indicating the reason for failure.
- */
 declare class EventRouter {
     private readonly messageProvider;
     private readonly patternRegistry;
@@ -754,6 +1339,9 @@ declare class EventRouter {
     private readonly options?;
     private readonly logger;
     private readonly subscriptions;
+    private readonly otel;
+    private readonly serviceName;
+    private readonly serverEndpoint;
     constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined, connection?: ConnectionProvider | undefined, options?: JetstreamModuleOptions | undefined);
     /**
      * Update the max_deliver thresholds from actual NATS consumer configs.
@@ -764,28 +1352,15 @@ declare class EventRouter {
     start(): void;
     /** Stop routing and unsubscribe from all streams. */
     destroy(): void;
-    /** Subscribe to a message stream and route each message. */
+    /** Subscribe to a message stream and route each message to its handler. */
     private subscribeToStream;
     private getConcurrency;
     private getAckExtensionConfig;
-    /** Handle a single event message with error isolation. */
-    private handleSafe;
-    /** Handle an ordered message with error isolation. */
-    private handleOrderedSafe;
-    /** Resolve handler, decode payload, and build context. Returns null on failure. */
-    private decodeMessage;
-    /** Execute handler, then ack on success or nak/dead-letter on failure. */
-    private executeHandler;
-    /** Check if the message has exhausted all delivery attempts. */
-    private isDeadLetter;
-    /** Handle a dead letter: invoke callback, then term or nak based on result. */
-    /**
-     * Fallback execution for a dead letter when DLQ is disabled, or when
-     * publishing to the DLQ stream fails (due to network or NATS errors).
-     *
-     * Triggers the user-provided `onDeadLetter` hook for logging/alerting.
-     * On success, terminates the message. On error, leaves it unacknowledged (nak)
-     * so NATS can retry the delivery on the next cycle.
+    /**
+     * Last-resort path for a dead letter: invoke `onDeadLetter`, then `term` on
+     * success or `nak` on hook failure so NATS retries on the next delivery
+     * cycle. Used when DLQ stream isn't configured, or when publishing to it
+     * failed and we still have to surface the message somewhere observable.
      */
     private fallbackToOnDeadLetterCallback;
     /**
@@ -832,17 +1407,16 @@ declare class RpcRouter {
     private resolvedAckExtensionInterval;
     private subscription;
     private cachedNc;
-    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, rpcOptions?: RpcRouterOptions | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
+    private readonly otel;
+    private readonly serviceName;
+    private readonly serverEndpoint;
+    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, connection: ConnectionProvider, codec: Codec, eventBus: EventBus, rpcOptions?: RpcRouterOptions | undefined, ackWaitMap?: Map<StreamKind, number> | undefined, options?: JetstreamModuleOptions);
     /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
     private get ackExtensionInterval();
     /** Start routing command messages to handlers. */
     start(): Promise<void>;
     /** Stop routing and unsubscribe. */
     destroy(): void;
-    /** Handle a single RPC command message with error isolation. */
-    private handleSafe;
-    /** Execute handler, publish response, settle message. */
-    private executeHandler;
 }
 
 /**
@@ -857,6 +1431,9 @@ declare class ConsumerProvider {
     private readonly streamProvider;
     private readonly patternRegistry;
     private readonly logger;
+    private readonly otel;
+    private readonly otelServiceName;
+    private readonly otelEndpoint;
     constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, streamProvider: StreamProvider, patternRegistry: PatternRegistry);
     /**
      * Ensure consumers exist for the specified kinds.
@@ -978,7 +1555,7 @@ declare class MessageProvider {
     private createOrderedFlow;
     /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
     private createSelfHealingFlow;
-    /** Single iteration: create ordered consumer -> iterate messages. */
+    /** Single iteration: create ordered consumer -> push messages into the subject. */
     private consumeOrderedOnce;
 }
 
@@ -1033,6 +1610,21 @@ declare class MetadataProvider {
     private openBucket;
 }
 
+/**
+ * NATS JetStream API error codes used by the transport.
+ *
+ * Ref: https://github.com/nats-io/nats-server (server error definitions)
+ * Verified on NATS 2.12.6 via integration tests (2026-04-02).
+ */
+declare enum NatsErrorCode {
+    /** Consumer does not exist on the specified stream. */
+    ConsumerNotFound = 10014,
+    /** Consumer name already in use with different configuration (race condition on create). */
+    ConsumerAlreadyExists = 10148,
+    /** Stream does not exist. */
+    StreamNotFound = 10059
+}
+
 /**
  * NestJS custom transport strategy for NATS JetStream.
  *
@@ -1206,265 +1798,65 @@ declare class JetstreamModule implements OnApplicationShutdown {
 }
 
 /**
- * NestJS ClientProxy implementation for the JetStream transport.
- *
- * Supports two operational modes:
- * - **Core mode** (default): Uses `nc.request()` for RPC, `nc.publish()` for events.
- * - **JetStream mode**: Uses `js.publish()` for RPC commands + inbox for responses.
- *
- * Events always go through JetStream publish for guaranteed delivery.
- * The mode only affects RPC (request/reply) behavior.
- *
- * Clients are lightweight — they share the NATS connection from `forRoot()`.
- */
-declare class JetstreamClient extends ClientProxy {
-    private readonly rootOptions;
-    private readonly connection;
-    private readonly codec;
-    private readonly eventBus;
-    private readonly logger;
-    /** Target service name this client sends messages to. */
-    private readonly targetName;
-    /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
-    private readonly callerName;
-    /** Shared inbox for JetStream-mode RPC responses. */
-    private inbox;
-    private inboxSubscription;
-    /** Pending JetStream-mode RPC callbacks, keyed by correlation ID. */
-    private readonly pendingMessages;
-    /** Pending JetStream-mode RPC timeouts, keyed by correlation ID. */
-    private readonly pendingTimeouts;
-    /** Subscription to connection status events for disconnect handling. */
-    private statusSubscription;
-    constructor(rootOptions: JetstreamModuleOptions, targetServiceName: string, connection: ConnectionProvider, codec: Codec, eventBus: EventBus);
-    /**
-     * Establish connection. Called automatically by NestJS on first use.
-     *
-     * Sets up the JetStream RPC inbox (if in JetStream mode) and subscribes
-     * to connection status events for fail-fast disconnect handling.
-     *
-     * @returns The underlying NATS connection.
-     */
-    connect(): Promise<NatsConnection>;
-    /** Clean up resources: reject pending RPCs, unsubscribe from status events. */
-    close(): Promise<void>;
-    /**
-     * Direct access to the raw NATS connection.
-     *
-     * @throws Error if not connected.
-     */
-    unwrap<T = NatsConnection>(): T;
-    /**
-     * Publish a fire-and-forget event to JetStream.
-     *
-     * Events are published to either the workqueue stream or broadcast stream
-     * depending on the subject prefix. When a schedule is present the message
-     * is published to a `_sch` subject within the same stream, with the target
-     * set to the original event subject.
-     */
-    protected dispatchEvent<T = unknown>(packet: ReadPacket): Promise<T>;
-    /**
-     * Publish an RPC command and register callback for response.
-     *
-     * Core mode: uses nc.request() with timeout.
-     * JetStream mode: publishes to stream + waits for inbox response.
-     */
-    protected publish(packet: ReadPacket, callback: (p: WritePacket) => void): () => void;
-    /** Core mode: nc.request() with timeout. */
-    private publishCoreRpc;
-    /** JetStream mode: publish to stream + wait for inbox response. */
-    private publishJetStreamRpc;
-    /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
-    private handleDisconnect;
-    /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
-    private rejectPendingRpcs;
-    /** Setup shared inbox subscription for JetStream RPC responses. */
-    private setupInbox;
-    /** Route an inbox reply to the matching pending callback. */
-    private routeInboxReply;
-    /** Build event subject — workqueue, broadcast, or ordered. */
-    private buildEventSubject;
-    /** Build NATS headers merging custom headers with transport headers. */
-    private buildHeaders;
-    /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
-    private extractRecordData;
-    /**
-     * Build a schedule-holder subject for NATS message scheduling.
-     *
-     * The schedule-holder subject resides in the same stream as the target but
-     * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
-     * NATS holds the message and publishes it to the target subject after the delay.
-     *
-     * Examples:
-     * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
-     * - `broadcast.config.updated` → `broadcast._sch.config.updated`
-     */
-    private buildScheduleSubject;
-    private getRpcTimeout;
-}
-
-/**
- * Immutable message record for JetStream transport.
+ * Default JSON codec using native `TextEncoder`/`TextDecoder`.
  *
- * Compatible with NestJS record builder pattern (like RmqRecord, NatsRecord).
- * Pass as the second argument to `client.send()` or `client.emit()`.
+ * Serializes values to JSON via `JSON.stringify` and encodes the
+ * resulting string into a `Uint8Array`. Decoding reverses the process.
  *
  * @example
  * ```typescript
- * const record = new JetstreamRecordBuilder({ id: 1 })
- *   .setHeader('x-tenant', 'acme')
- *   .setTimeout(5000)
- *   .build();
- *
- * client.send('get.user', record);
+ * const codec = new JsonCodec();
+ * const bytes = codec.encode({ hello: 'world' });
+ * const data = codec.decode(bytes); // { hello: 'world' }
  * ```
  */
-declare class JetstreamRecord<TData = unknown> {
-    /** Message payload. */
-    readonly data: TData;
-    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
-    readonly headers: ReadonlyMap<string, string>;
-    /** Per-request RPC timeout override in ms. */
-    readonly timeout?: number | undefined;
-    /** Custom message ID for JetStream deduplication. */
-    readonly messageId?: string | undefined;
-    /** Schedule options for delayed delivery. */
-    readonly schedule?: ScheduleRecordOptions | undefined;
-    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
-    readonly ttl?: string | undefined;
-    constructor(
-    /** Message payload. */
-    data: TData, 
-    /** Custom headers set via {@link JetstreamRecordBuilder.setHeader}. */
-    headers: ReadonlyMap<string, string>, 
-    /** Per-request RPC timeout override in ms. */
-    timeout?: number | undefined, 
-    /** Custom message ID for JetStream deduplication. */
-    messageId?: string | undefined, 
-    /** Schedule options for delayed delivery. */
-    schedule?: ScheduleRecordOptions | undefined, 
-    /** Per-message TTL as Go duration string (e.g. "30s", "5m"). */
-    ttl?: string | undefined);
+declare class JsonCodec implements Codec {
+    encode(data: unknown): Uint8Array;
+    decode(data: Uint8Array): unknown;
 }
+
 /**
- * Fluent builder for constructing JetstreamRecord instances.
+ * Minimal shape of a `msgpackr` `Packr` instance used by {@link MsgpackCodec}.
  *
- * Protected headers (`correlation-id`, `reply-to`, `error`) cannot be
- * set by the user — attempting to do so throws an error at build time.
+ * Typed locally so consumers who do not use MessagePack encoding never pay
+ * for a `msgpackr` import.
  */
-declare class JetstreamRecordBuilder<TData = unknown> {
-    private data;
-    private readonly headers;
-    private timeout;
-    private messageId;
-    private scheduleOptions;
-    private ttlDuration;
-    constructor(data?: TData);
-    /**
-     * Set the message payload.
-     *
-     * @param data - Payload to serialize via the configured {@link Codec}.
-     */
-    setData(data: TData): this;
-    /**
-     * Set a single custom header.
-     *
-     * @param key - Header name (e.g. `'x-tenant'`).
-     * @param value - Header value.
-     * @throws Error if the header name is reserved by the transport.
-     */
-    setHeader(key: string, value: string): this;
-    /**
-     * Set multiple custom headers at once.
-     *
-     * @param headers - Key-value pairs to set as headers.
-     * @throws Error if any header name is reserved by the transport.
-     */
-    setHeaders(headers: Record<string, string>): this;
-    /**
-     * Set a custom message ID for JetStream deduplication.
-     *
-     * NATS JetStream uses this ID to detect duplicate publishes within the
-     * stream's `duplicate_window`. If two messages with the same ID arrive
-     * within the window, the second is silently dropped.
-     *
-     * When not set, a random UUID is generated automatically.
-     *
-     * @param id - Unique message identifier (e.g. order ID, idempotency key).
-     *
-     * @example
-     * ```typescript
-     * new JetstreamRecordBuilder(data)
-     *   .setMessageId(`order-${order.id}`)
-     *   .build();
-     * ```
-     */
-    setMessageId(id: string): this;
-    /**
-     * Set per-request RPC timeout.
-     *
-     * @param ms - Timeout in milliseconds. Overrides the global RPC timeout for this request only.
-     */
-    setTimeout(ms: number): this;
-    /**
-     * Schedule one-shot delayed delivery.
-     *
-     * The message is held by NATS and delivered to the event consumer
-     * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
-     * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
-     *
-     * Only meaningful for events (`client.emit()`). If used with RPC
-     * (`client.send()`), a warning is logged and the schedule is ignored.
-     *
-     * @param date - Delivery time. Must be in the future.
-     * @throws Error if the date is not in the future.
-     */
-    scheduleAt(date: Date): this;
-    /**
-     * Set per-message TTL (time-to-live).
-     *
-     * The message expires individually after the specified duration,
-     * independent of the stream's `max_age`. Requires NATS >= 2.11 and
-     * `allow_msg_ttl: true` on the stream.
-     *
-     * Only meaningful for events (`client.emit()`). If used with RPC
-     * (`client.send()`), a warning is logged and the TTL is ignored.
-     *
-     * @param nanos - TTL in nanoseconds. Use {@link toNanos} for human-readable values.
-     *
-     * @example
-     * ```typescript
-     * import { toNanos } from '@horizon-republic/nestjs-jetstream';
-     *
-     * new JetstreamRecordBuilder(payload).ttl(toNanos(30, 'minutes')).build();
-     * new JetstreamRecordBuilder(payload).ttl(toNanos(24, 'hours')).build();
-     * ```
-     */
-    ttl(nanos: number): this;
-    /**
-     * Build the immutable {@link JetstreamRecord}.
-     *
-     * @returns A frozen record ready to pass to `client.send()` or `client.emit()`.
-     */
-    build(): JetstreamRecord<TData>;
-    /** Validate that a header key is not reserved. */
-    private validateHeaderKey;
+interface PackrLike {
+    pack(data: unknown): Uint8Array;
+    unpack(data: Uint8Array): unknown;
 }
-
 /**
- * Default JSON codec using native `TextEncoder`/`TextDecoder`.
+ * MessagePack codec backed by a caller-provided `msgpackr` `Packr` instance.
  *
- * Serializes values to JSON via `JSON.stringify` and encodes the
- * resulting string into a `Uint8Array`. Decoding reverses the process.
+ * Use this codec when publishing structured payloads larger than roughly
+ * 1–2 KB — below that size the default {@link JsonCodec} wins on per-call
+ * constant overhead. Above it, MessagePack encodes and decodes several times
+ * faster and produces smaller wire frames. The format is cross-language, so
+ * Node producers and non-Node consumers (Python, Go, Java, Rust, ...) stay
+ * interoperable.
+ *
+ * Requires installing the optional `msgpackr` peer dependency:
+ *
+ * ```bash
+ * npm install msgpackr
+ * # or: pnpm add msgpackr
+ * ```
  *
  * @example
  * ```typescript
- * const codec = new JsonCodec();
- * const bytes = codec.encode({ hello: 'world' });
- * const data = codec.decode(bytes); // { hello: 'world' }
+ * import { JetstreamModule, MsgpackCodec } from '@horizon-republic/nestjs-jetstream';
+ * import { Packr } from 'msgpackr';
+ *
+ * JetstreamModule.forRoot({
+ *   name: 'orders',
+ *   servers: ['nats://localhost:4222'],
+ *   codec: new MsgpackCodec(new Packr()),
+ * });
  * ```
  */
-declare class JsonCodec implements Codec {
+declare class MsgpackCodec implements Codec {
+    private readonly packr;
+    constructor(packr: PackrLike);
     encode(data: unknown): Uint8Array;
     decode(data: Uint8Array): unknown;
 }
@@ -1625,8 +2017,6 @@ declare const JETSTREAM_OPTIONS: unique symbol;
 declare const JETSTREAM_CONNECTION: unique symbol;
 /** Token for the global Codec instance. */
 declare const JETSTREAM_CODEC: unique symbol;
-/** Token for the EventBus instance. */
-declare const JETSTREAM_EVENT_BUS: unique symbol;
 /**
  * Generate the injection token for a `forFeature()` client.
  *
@@ -1659,6 +2049,28 @@ type TimeUnit = 'ms' | 'seconds' | 'minutes' | 'hours' | 'days';
  * ```
  */
 declare const toNanos: (value: number, unit: TimeUnit) => number;
+/** Default config for workqueue event streams. */
+declare const DEFAULT_EVENT_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for RPC command streams (jetstream mode only). */
+declare const DEFAULT_COMMAND_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for broadcast event streams. */
+declare const DEFAULT_BROADCAST_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for ordered event streams (Limits retention). */
+declare const DEFAULT_ORDERED_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for dead-letter queue (DLQ) streams. */
+declare const DEFAULT_DLQ_STREAM_CONFIG: Partial<StreamConfig>;
+/** Default config for workqueue event consumers. */
+declare const DEFAULT_EVENT_CONSUMER_CONFIG: Partial<ConsumerConfig>;
+/** Default config for RPC command consumers (jetstream mode only). */
+declare const DEFAULT_COMMAND_CONSUMER_CONFIG: Partial<ConsumerConfig>;
+/** Default config for broadcast event consumers. */
+declare const DEFAULT_BROADCAST_CONSUMER_CONFIG: Partial<ConsumerConfig>;
+/** Default RPC timeout for Core mode (30 seconds). */
+declare const DEFAULT_RPC_TIMEOUT = 30000;
+/** Default RPC timeout for JetStream mode (3 minutes). */
+declare const DEFAULT_JETSTREAM_RPC_TIMEOUT = 180000;
+/** Default graceful shutdown timeout (10 seconds). */
+declare const DEFAULT_SHUTDOWN_TIMEOUT = 10000;
 /** Default KV bucket name for handler metadata. */
 declare const DEFAULT_METADATA_BUCKET = "handler_registry";
 /** Default number of KV bucket replicas. */
@@ -1698,7 +2110,7 @@ declare enum JetstreamHeader {
     Error = "x-error"
 }
 declare enum JetstreamDlqHeader {
-    /** Reason for the message being sent to the DLQ (error message or 'max_deliver_exceeded') */
+    /** Reason for the message being sent to the DLQ — the last handler error message. */
     DeadLetterReason = "x-dead-letter-reason",
     /** Original NATS subject the message was originally published to */
     OriginalSubject = "x-original-subject",
@@ -1709,6 +2121,8 @@ declare enum JetstreamDlqHeader {
     /** Number of times the message has been delivered */
     DeliveryCount = "x-delivery-count"
 }
+/** Set of header names that are reserved and cannot be set by users. */
+declare const RESERVED_HEADERS: Set<string>;
 /**
  * Build the internal service name with microservice suffix.
  *
@@ -1770,4 +2184,4 @@ declare const isJetStreamRpcMode: (rpc: RpcConfig | undefined) => boolean;
 /** Check if the RPC config specifies Core mode (default). */
 declare const isCoreRpcMode: (rpc: RpcConfig | undefined) => boolean;
 
-export { type Codec, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, type DeadLetterInfo, EventBus, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, JetstreamClient, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, type OrderedEventOverrides, PatternPrefix, type RpcConfig, RpcContext, type ScheduleRecordOptions, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };
+export { type CaptureBodyOptions, type Codec, ConsumeKind, type ConsumeSourceMsg, DEFAULT_BROADCAST_CONSUMER_CONFIG, DEFAULT_BROADCAST_STREAM_CONFIG, DEFAULT_COMMAND_CONSUMER_CONFIG, DEFAULT_COMMAND_STREAM_CONFIG, DEFAULT_DLQ_STREAM_CONFIG, DEFAULT_EVENT_CONSUMER_CONFIG, DEFAULT_EVENT_STREAM_CONFIG, DEFAULT_JETSTREAM_RPC_TIMEOUT, DEFAULT_METADATA_BUCKET, DEFAULT_METADATA_HISTORY, DEFAULT_METADATA_REPLICAS, DEFAULT_METADATA_TTL, DEFAULT_ORDERED_STREAM_CONFIG, DEFAULT_RPC_TIMEOUT, DEFAULT_SHUTDOWN_TIMEOUT, DEFAULT_TRACES, type DeadLetterInfo, type ErrorClassification, type HandlerMetadata, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_OPTIONS, JetstreamClient, type JetstreamConsumeContext, JetstreamDlqHeader, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, type JetstreamPublishContext, JetstreamRecord, JetstreamRecordBuilder, type JetstreamResponseContext, JetstreamStrategy, JetstreamTrace, JsonCodec, MIN_METADATA_TTL, MessageKind, type MetadataRegistryOptions, MsgpackCodec, NatsErrorCode, type OrderedEventOverrides, type OtelOptions, PatternPrefix, PublishKind, RESERVED_HEADERS, type RpcConfig, RpcContext, type ScheduleRecordOptions, type ServerEndpoint, type StreamConfigOverrides, type StreamConsumerOverrides, StreamKind, TRACER_NAME, TransportEvent, type TransportHooks, buildBroadcastSubject, buildSubject, consumerName, dlqStreamName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, metadataKey, streamName, toNanos };