@horizon-republic/nestjs-jetstream 2.7.1 → 2.9.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ModuleMetadata, FactoryProvider, Type, Logger, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
-import { MsgHdrs, StreamConfig, ConsumerConfig, ConsumeOptions, DeliverPolicy, ReplayPolicy, ConnectionOptions, NatsConnection, Status, JetStreamManager, JetStreamClient, ConsumerInfo, JsMsg, Msg } from 'nats';
+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 { Observable } from 'rxjs';
 
@@ -116,6 +117,14 @@ interface JetstreamHealthStatus {
     latency: number | null;
 }
 
+/**
+ * Stream config overrides exposed to users.
+ *
+ * `retention` is excluded because it is controlled by the transport layer
+ * (Workqueue for events/commands, Limits for broadcast/ordered).
+ * Any `retention` value provided at runtime is silently stripped.
+ */
+type StreamConfigOverrides = Partial<Omit<StreamConfig, 'retention'>>;
 /**
  * RPC transport configuration.
  *
@@ -135,7 +144,7 @@ type RpcConfig = {
     /** Handler timeout in ms. Default: 180_000 (3 min). */
     timeout?: number;
     /** Raw NATS StreamConfig overrides for the command stream. */
-    stream?: Partial<StreamConfig>;
+    stream?: StreamConfigOverrides;
     /** Raw NATS ConsumerConfig overrides for the command consumer. */
     consumer?: Partial<ConsumerConfig>;
     /** Options passed to the nats.js `consumer.consume()` call for the command consumer. */
@@ -150,7 +159,7 @@ type RpcConfig = {
 };
 /** Overrides for JetStream stream and consumer configuration. */
 interface StreamConsumerOverrides {
-    stream?: Partial<StreamConfig>;
+    stream?: StreamConfigOverrides;
     consumer?: Partial<ConsumerConfig>;
     /**
      * Options passed to the nats.js `consumer.consume()` call.
@@ -194,7 +203,7 @@ interface StreamConsumerOverrides {
  */
 interface OrderedEventOverrides {
     /** Stream overrides (e.g. `max_age`, `max_bytes`). */
-    stream?: Partial<StreamConfig>;
+    stream?: StreamConfigOverrides;
     /**
      * Where to start reading when the consumer is (re)created.
      * @default DeliverPolicy.All
@@ -214,6 +223,38 @@ interface OrderedEventOverrides {
      */
     replayPolicy?: ReplayPolicy;
 }
+/**
+ * Configuration for the handler metadata KV registry.
+ *
+ * When any handler has `meta` in its extras, the transport writes metadata
+ * entries to a NATS KV bucket at startup. External services (API gateways,
+ * dashboards) can watch the bucket for service discovery.
+ *
+ * All fields are optional — sensible defaults are applied.
+ */
+interface MetadataRegistryOptions {
+    /**
+     * KV bucket name.
+     * @default 'handler_registry'
+     */
+    bucket?: string;
+    /**
+     * Number of KV bucket replicas. Must be an odd number (1, 3, 5, 7, ...).
+     * Requires a NATS cluster with at least this many nodes.
+     * @default 1
+     */
+    replicas?: number;
+    /**
+     * KV bucket TTL in milliseconds.
+     *
+     * Entries expire automatically unless refreshed by a heartbeat.
+     * The transport refreshes entries every `ttl / 2` while the pod is alive.
+     * When the pod stops (graceful or crash), entries expire after this duration.
+     *
+     * @default 30_000 (30 seconds)
+     */
+    ttl?: number;
+}
 /**
  * Root module configuration for `JetstreamModule.forRoot()`.
  *
@@ -282,12 +323,62 @@ interface JetstreamModuleOptions {
      * ```
      */
     onDeadLetter?(info: DeadLetterInfo): Promise<void>;
+    /**
+     * Dead-letter queue (DLQ) configuration.
+     * DLQ is a separate stream used to store messages that have exhausted all delivery attempts.
+     * @example
+     * ```typescript
+     * JetstreamModule.forRootAsync({
+     *   name: 'my-service',
+     *   servers: ['nats://localhost:4222'],
+     *   dlq: {
+     *     stream: {
+     *       max_age: toNanos(30, 'days'),
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    dlq?: {
+        stream?: StreamConfigOverrides;
+    };
     /**
      * Graceful shutdown timeout in ms.
      * Handlers exceeding this are abandoned.
      * @default 10_000
      */
     shutdownTimeout?: number;
+    /**
+     * Allow destructive stream migration when immutable config changes are detected.
+     *
+     * When `true`, the transport will recreate streams (via blue-green sourcing)
+     * if immutable properties like `storage` differ from the running stream.
+     * Messages are preserved during migration.
+     *
+     * `retention` is NOT migratable — it is controlled by the transport
+     * (Workqueue for events, Limits for broadcast/ordered) and a mismatch
+     * is always treated as an error regardless of this flag.
+     *
+     * When `false` (default), immutable conflicts are logged as warnings and
+     * the stream continues with its existing configuration.
+     *
+     * @default false
+     */
+    allowDestructiveMigration?: boolean;
+    /**
+     * Handler metadata KV registry configuration.
+     *
+     * When any handler has `meta` in its `@EventPattern` / `@MessagePattern` extras,
+     * the transport writes metadata to a NATS KV bucket at startup.
+     * External services (API gateways, dashboards, CLI tools) can read or watch
+     * the bucket for dynamic service discovery.
+     *
+     * Auto-enabled when any handler has `meta`. Set to customize bucket name,
+     * replicas, or TTL.
+     *
+     * @see MetadataRegistryOptions
+     */
+    metadata?: MetadataRegistryOptions;
     /**
      * Raw NATS ConnectionOptions pass-through for advanced connection config.
      * Allows setting tls, auth, reconnect behavior, maxReconnectAttempts, etc.
@@ -354,6 +445,12 @@ declare enum StreamKind {
  */
 type SubjectKind = Exclude<StreamKind, StreamKind.Broadcast>;
 
+/** Options for one-shot delayed delivery via NATS 2.12 message scheduling. */
+interface ScheduleRecordOptions {
+    /** When to deliver the message. Must be in the future. */
+    at: Date;
+}
+
 /** @internal Grouped pattern lists by stream kind, used for stream/consumer setup. */
 interface PatternsByKind {
     /** Workqueue event patterns. */
@@ -485,6 +582,7 @@ declare class ConnectionProvider {
      * 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. */
@@ -508,6 +606,7 @@ declare class PatternRegistry {
     private _hasCommands;
     private _hasBroadcasts;
     private _hasOrdered;
+    private _hasMetadata;
     constructor(options: JetstreamModuleOptions);
     /**
      * Register all handlers from the NestJS strategy.
@@ -525,11 +624,21 @@ declare class PatternRegistry {
     hasOrderedHandlers(): boolean;
     /** Get fully-qualified NATS subjects for ordered handlers. */
     getOrderedSubjects(): string[];
+    /** Check if any registered handler has metadata. */
+    hasMetadata(): boolean;
+    /**
+     * Get handler metadata entries for KV publishing.
+     *
+     * Returns a map of KV key -> metadata object for all handlers that have `meta`.
+     * Key format: `{serviceName}.{kind}.{pattern}`.
+     */
+    getMetadataEntries(): Map<string, Record<string, unknown>>;
     /** Get patterns grouped by kind (cached after registration). */
     getPatternsByKind(): PatternsByKind;
     /** Normalize a full NATS subject back to the user-facing pattern. */
     normalizeSubject(subject: string): string;
     private buildPatternsByKind;
+    private resolveStreamKind;
     private logSummary;
 }
 
@@ -574,12 +683,14 @@ declare class StreamProvider {
     private readonly options;
     private readonly connection;
     private readonly logger;
+    private readonly migration;
     constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
     /**
      * Ensure all required streams exist with correct configuration.
      *
      * @param kinds Which stream kinds to create. Determined by the module based
      *              on RPC mode and registered handler patterns.
+     * If the dlq option is enabled, also ensures the DLQ stream exists.
      */
     ensureStreams(kinds: StreamKind[]): Promise<void>;
     /** Get the stream name for a given kind. */
@@ -588,12 +699,32 @@ declare class StreamProvider {
     getSubjects(kind: StreamKind): string[];
     /** Ensure a single stream exists, creating or updating as needed. */
     private ensureStream;
+    /** Ensure a dead-letter queue stream exists, creating or updating as needed. */
+    private ensureDlqStream;
+    private handleExistingStream;
+    private buildMutableOnlyConfig;
+    private logChanges;
     /** Build the full stream config by merging defaults with user overrides. */
     private buildConfig;
+    /**
+     * Build the stream configuration for the Dead-Letter Queue (DLQ).
+     *
+     * Merges the library default DLQ config with user-provided overrides.
+     * Ensures transport-controlled settings like retention are safely decoupled.
+     */
+    private buildDlqConfig;
     /** Get default config for a stream kind. */
     private getDefaults;
-    /** Get user-provided overrides for a stream kind. */
+    /** Check if scheduling is enabled for a stream kind via `allow_msg_schedules` override. */
+    private isSchedulingEnabled;
+    /** Get user-provided overrides for a stream kind, stripping transport-controlled properties. */
     private getOverrides;
+    /**
+     * Remove transport-controlled properties from user overrides.
+     * `retention` is managed by the transport (Workqueue/Limits per stream kind)
+     * and silently stripped to protect users from misconfiguration.
+     */
+    private stripTransportControlled;
 }
 
 /**
@@ -605,6 +736,11 @@ declare class StreamProvider {
  * **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;
@@ -614,9 +750,11 @@ declare class EventRouter {
     private readonly deadLetterConfig?;
     private readonly processingConfig?;
     private readonly ackWaitMap?;
+    private readonly connection?;
+    private readonly options?;
     private readonly logger;
     private readonly subscriptions;
-    constructor(messageProvider: MessageProvider, patternRegistry: PatternRegistry, codec: Codec, eventBus: EventBus, deadLetterConfig?: DeadLetterConfig | undefined, processingConfig?: EventProcessingConfig | undefined, ackWaitMap?: Map<StreamKind, number> | undefined);
+    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.
      * Called after consumers are ensured so the DLQ map reflects reality.
@@ -641,6 +779,30 @@ declare class EventRouter {
     /** 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.
+     */
+    private fallbackToOnDeadLetterCallback;
+    /**
+     * Publish a dead letter to the configured Dead-Letter Queue (DLQ) stream.
+     *
+     * Appends diagnostic metadata headers to the original message and preserves
+     * the primary payload. If publishing succeeds, it notifies the standard
+     * `onDeadLetter` callback and terminates the message. If it fails, it falls
+     * back to the callback entirely to prevent silent data loss.
+     */
+    private publishToDlq;
+    /**
+     * Orchestrates the handling of a message that has exhausted delivery limits.
+     *
+     * Emits a system event and delegates either to the robust DLQ stream publisher
+     * or directly to the fallback callback based on the active module configuration.
+     */
     private handleDeadLetter;
 }
 
@@ -704,8 +866,36 @@ declare class ConsumerProvider {
     ensureConsumers(kinds: StreamKind[]): Promise<Map<StreamKind, ConsumerInfo>>;
     /** Get the consumer name for a given kind. */
     getConsumerName(kind: StreamKind): string;
-    /** Ensure a single consumer exists, creating if needed. */
-    private ensureConsumer;
+    /**
+     * Ensure a single consumer exists with the desired config.
+     * Used at **startup** — creates or updates the consumer to match
+     * the current pod's configuration.
+     */
+    ensureConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
+    /**
+     * Recover a consumer that disappeared during runtime.
+     * Used by **self-healing** — creates if missing, but NEVER updates config.
+     *
+     * If a migration backup stream exists, another pod is mid-migration — we
+     * throw so the self-healing retry loop waits with backoff until migration
+     * completes and the backup is cleaned up.
+     *
+     * This prevents old pods from:
+     * - Overwriting a newer pod's consumer config during rolling updates
+     * - Creating consumers during migration (which would consume and delete
+     *   workqueue messages while they're being restored)
+     */
+    recoverConsumer(jsm: Awaited<ReturnType<ConnectionProvider['getJetStreamManager']>>, kind: StreamKind): Promise<ConsumerInfo>;
+    /**
+     * Throw if a migration backup stream exists for this stream.
+     * The self-healing retry loop catches the error and retries with backoff,
+     * naturally waiting until the migrating pod finishes and cleans up the backup.
+     */
+    private assertNoMigrationInProgress;
+    /**
+     * Create a consumer, handling the race where another pod creates it first.
+     */
+    private createConsumer;
     /** Build consumer config by merging defaults with user overrides. */
     private buildConfig;
     /** Get default config for a consumer kind. */
@@ -714,6 +904,8 @@ declare class ConsumerProvider {
     private getOverrides;
 }
 
+/** Callback to recreate a consumer when it disappears. */
+type ConsumerRecoveryFn = (kind: StreamKind) => Promise<ConsumerInfo>;
 /**
  * Manages pull-based message consumption from JetStream consumers.
  *
@@ -727,6 +919,7 @@ declare class MessageProvider {
     private readonly connection;
     private readonly eventBus;
     private readonly consumeOptionsMap;
+    private readonly consumerRecoveryFn?;
     private readonly logger;
     private readonly activeIterators;
     private orderedReadyResolve;
@@ -736,7 +929,7 @@ declare class MessageProvider {
     private commandMessages$;
     private broadcastMessages$;
     private orderedMessages$;
-    constructor(connection: ConnectionProvider, eventBus: EventBus, consumeOptionsMap?: Map<StreamKind, Partial<ConsumeOptions>>);
+    constructor(connection: ConnectionProvider, eventBus: EventBus, consumeOptionsMap?: Map<StreamKind, Partial<ConsumeOptions>>, consumerRecoveryFn?: ConsumerRecoveryFn | undefined);
     /** Observable stream of workqueue event messages. */
     get events$(): Observable<JsMsg>;
     /** Observable stream of RPC command messages (jetstream mode). */
@@ -769,6 +962,14 @@ declare class MessageProvider {
     private createFlow;
     /** Single iteration: get consumer -> pull messages -> emit to subject. */
     private consumeOnce;
+    /**
+     * Detect "consumer not found" errors from `js.consumers.get()`.
+     *
+     * Unlike JetStream Manager calls (which throw `JetStreamApiError`),
+     * the JetStream client's `consumers.get()` throws a plain `Error`
+     * with the error code embedded in the message text.
+     */
+    private isConsumerNotFound;
     /** Get the target subject for a consumer kind. */
     private getTargetSubject;
     /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
@@ -781,6 +982,57 @@ declare class MessageProvider {
     private consumeOrderedOnce;
 }
 
+/**
+ * Publishes handler metadata to a NATS KV bucket for external service discovery.
+ *
+ * Uses TTL + heartbeat to manage entry lifecycle:
+ * - Entries are written on startup and refreshed every `ttl / 2`
+ * - When the pod stops (graceful or crash), heartbeat stops → entries expire via TTL
+ * - No explicit delete needed — NATS handles expiry automatically
+ *
+ * This provider is fully decoupled from stream/consumer infrastructure —
+ * it only depends on the NATS connection and module options.
+ */
+declare class MetadataProvider {
+    private readonly connection;
+    private readonly logger;
+    private readonly bucketName;
+    private readonly replicas;
+    private readonly ttl;
+    private currentEntries?;
+    private heartbeatTimer?;
+    private cachedKv?;
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider);
+    /**
+     * Write handler metadata entries to the KV bucket and start heartbeat.
+     *
+     * Creates the bucket if it doesn't exist (idempotent).
+     * Skips silently when entries map is empty.
+     * Starts a heartbeat interval that refreshes entries every `ttl / 2`
+     * to prevent TTL expiry while the pod is alive.
+     *
+     * Non-critical — errors are logged but do not prevent transport startup.
+     *
+     * @param entries Map of KV key → metadata object.
+     */
+    publish(entries: Map<string, Record<string, unknown>>): Promise<void>;
+    /**
+     * Stop the heartbeat timer.
+     *
+     * After this call, entries will expire via TTL once the heartbeat window passes.
+     * Called during transport shutdown (strategy.close()).
+     */
+    destroy(): void;
+    /** Write entries to KV with per-entry error handling. */
+    private writeEntries;
+    /** Start heartbeat interval that refreshes entries every ttl/2. */
+    private startHeartbeat;
+    /** Refresh all current entries in KV (heartbeat tick). */
+    private refreshEntries;
+    /** Create or open the KV bucket (cached after first call). */
+    private openBucket;
+}
+
 /**
  * NestJS custom transport strategy for NATS JetStream.
  *
@@ -803,17 +1055,18 @@ declare class JetstreamStrategy extends Server implements CustomTransportStrateg
     private readonly rpcRouter;
     private readonly coreRpcServer;
     private readonly ackWaitMap;
+    private readonly metadataProvider?;
     readonly transportId: symbol;
     private readonly listeners;
     private started;
-    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer, ackWaitMap?: Map<StreamKind, number>);
+    constructor(options: JetstreamModuleOptions, connection: ConnectionProvider, patternRegistry: PatternRegistry, streamProvider: StreamProvider, consumerProvider: ConsumerProvider, messageProvider: MessageProvider, eventRouter: EventRouter, rpcRouter: RpcRouter, coreRpcServer: CoreRpcServer, ackWaitMap?: Map<StreamKind, number>, metadataProvider?: MetadataProvider | undefined);
     /**
      * Start the transport: register handlers, create infrastructure, begin consumption.
      *
      * Called by NestJS when `connectMicroservice()` is used, or internally by the module.
      */
     listen(callback: () => void): Promise<void>;
-    /** Stop all consumers, routers, and subscriptions. Called during shutdown. */
+    /** Stop all consumers, routers, subscriptions, and metadata heartbeat. Called during shutdown. */
     close(): void;
     /**
      * Register event listener (required by Server base class).
@@ -848,22 +1101,30 @@ interface Stoppable {
  * Shutdown sequence:
  * 1. Emit onShutdownStart hook
  * 2. Stop accepting new messages (close subscriptions, stop consumers)
- * 3. Wait for in-flight handlers to complete (up to timeout)
- * 4. Drain and close NATS connection
- * 5. Emit onShutdownComplete hook
+ * 3. Drain and close NATS connection (with timeout safety net)
+ * 4. Emit onShutdownComplete hook
+ *
+ * Idempotent — concurrent or repeated calls return the same promise.
+ * This is critical because NestJS may call `onApplicationShutdown` on
+ * multiple module instances (forRoot + forFeature) that share this
+ * singleton, and the call order is not guaranteed.
  */
 declare class ShutdownManager {
     private readonly connection;
     private readonly eventBus;
     private readonly timeout;
     private readonly logger;
+    private shutdownPromise?;
     constructor(connection: ConnectionProvider, eventBus: EventBus, timeout: number);
     /**
      * Execute the full shutdown sequence.
      *
+     * Idempotent — concurrent or repeated calls return the same promise.
+     *
      * @param strategy Optional stoppable to close (stops consumers and subscriptions).
      */
     shutdown(strategy?: Stoppable): Promise<void>;
+    private doShutdown;
 }
 
 /**
@@ -997,7 +1258,9 @@ declare class JetstreamClient extends ClientProxy {
      * Publish a fire-and-forget event to JetStream.
      *
      * Events are published to either the workqueue stream or broadcast stream
-     * depending on the subject prefix.
+     * 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>;
     /**
@@ -1023,8 +1286,20 @@ declare class JetstreamClient extends ClientProxy {
     private buildEventSubject;
     /** Build NATS headers merging custom headers with transport headers. */
     private buildHeaders;
-    /** Extract data, headers, and timeout from raw packet data or JetstreamRecord. */
+    /** 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;
 }
 
@@ -1053,6 +1328,10 @@ declare class JetstreamRecord<TData = unknown> {
     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, 
@@ -1061,7 +1340,11 @@ declare class JetstreamRecord<TData = unknown> {
     /** Per-request RPC timeout override in ms. */
     timeout?: number | undefined, 
     /** Custom message ID for JetStream deduplication. */
-    messageId?: string | undefined);
+    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.
@@ -1074,6 +1357,8 @@ declare class JetstreamRecordBuilder<TData = unknown> {
     private readonly headers;
     private timeout;
     private messageId;
+    private scheduleOptions;
+    private ttlDuration;
     constructor(data?: TData);
     /**
      * Set the message payload.
@@ -1121,6 +1406,41 @@ declare class JetstreamRecordBuilder<TData = unknown> {
      * @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}.
      *
@@ -1132,10 +1452,10 @@ declare class JetstreamRecordBuilder<TData = unknown> {
 }
 
 /**
- * Default JSON codec wrapping the nats.js JSONCodec.
+ * Default JSON codec using native `TextEncoder`/`TextDecoder`.
  *
- * Serializes to/from JSON using the native NATS implementation
- * which handles `TextEncoder`/`TextDecoder` internally.
+ * Serializes values to JSON via `JSON.stringify` and encodes the
+ * resulting string into a `Uint8Array`. Decoding reverses the process.
  *
  * @example
  * ```typescript
@@ -1145,7 +1465,6 @@ declare class JetstreamRecordBuilder<TData = unknown> {
  * ```
  */
 declare class JsonCodec implements Codec {
-    private readonly inner;
     encode(data: unknown): Uint8Array;
     decode(data: Uint8Array): unknown;
 }
@@ -1170,7 +1489,7 @@ type NatsMessage = JsMsg | Msg;
  *     return;
  *   }
  *   if (!this.isReady()) {
- *     ctx.retry({ delay: 5000 });
+ *     ctx.retry({ delayMs: 5000 });
  *     return;
  *   }
  *   await this.process(data);
@@ -1288,9 +1607,14 @@ declare class JetstreamHealthIndicator {
      * Returns `{ [key]: { status: 'up', ... } }` on success.
      * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
      *
+     * The thrown error sets `isHealthCheckError: true` and `causes` — the
+     * duck-type contract that Terminus `HealthCheckExecutor` uses to distinguish
+     * health failures from unexpected exceptions. Works with both Terminus v10
+     * (`instanceof HealthCheckError`) and v11+ (`error?.isHealthCheckError`).
+     *
      * @param key - Health indicator key (default: `'jetstream'`).
      * @returns Object with status, server, and latency under the given key.
-     * @throws Error with `{ [key]: { status: 'down' } }` when disconnected.
+     * @throws Error with `isHealthCheckError`, `causes`, and `{ [key]: { status: 'down' } }`.
      */
     isHealthy(key?: string): Promise<Record<string, Record<string, unknown>>>;
 }
@@ -1335,6 +1659,25 @@ type TimeUnit = 'ms' | 'seconds' | 'minutes' | 'hours' | 'days';
  * ```
  */
 declare const toNanos: (value: number, unit: TimeUnit) => number;
+/** Default KV bucket name for handler metadata. */
+declare const DEFAULT_METADATA_BUCKET = "handler_registry";
+/** Default number of KV bucket replicas. */
+declare const DEFAULT_METADATA_REPLICAS = 1;
+/** Default KV bucket history depth (latest value only). */
+declare const DEFAULT_METADATA_HISTORY = 1;
+/** Default KV bucket TTL in milliseconds (entries expire unless refreshed). */
+declare const DEFAULT_METADATA_TTL = 30000;
+/** Minimum allowed metadata TTL in milliseconds. Prevents tight heartbeat loops. */
+declare const MIN_METADATA_TTL = 5000;
+/**
+ * Build a KV key for a handler's metadata entry.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @param kind - Handler's stream kind ({@link StreamKind}).
+ * @param pattern - The message pattern (e.g. `'order.created'`).
+ * @returns KV key (e.g. `orders.ev.order.created`).
+ */
+declare const metadataKey: (serviceName: string, kind: StreamKind, pattern: string) => string;
 /**
  * NATS headers managed by the transport.
  *
@@ -1354,6 +1697,18 @@ declare enum JetstreamHeader {
     /** Set to `'true'` on error responses so the client can distinguish success from failure. */
     Error = "x-error"
 }
+declare enum JetstreamDlqHeader {
+    /** Reason for the message being sent to the DLQ (error message or 'max_deliver_exceeded') */
+    DeadLetterReason = "x-dead-letter-reason",
+    /** Original NATS subject the message was originally published to */
+    OriginalSubject = "x-original-subject",
+    /** Source stream name */
+    OriginalStream = "x-original-stream",
+    /** ISO timestamp of when the message was moved to DLQ */
+    FailedAt = "x-failed-at",
+    /** Number of times the message has been delivered */
+    DeliveryCount = "x-delivery-count"
+}
 /**
  * Build the internal service name with microservice suffix.
  *
@@ -1365,24 +1720,38 @@ declare const internalName: (name: string) => string;
  * Build a fully-qualified NATS subject for workqueue events, RPC commands, or ordered events.
  *
  * @param serviceName - Target service name.
- * @param kind - Subject kind (`'ev'`, `'cmd'`, or `'ordered'`).
+ * @param kind - Subject kind ({@link StreamKind.Event}, {@link StreamKind.Command}, or {@link StreamKind.Ordered}).
  * @param pattern - The message pattern (e.g. `'user.created'`).
  * @returns `{serviceName}__microservice.{kind}.{pattern}`
  */
 declare const buildSubject: (serviceName: string, kind: SubjectKind, pattern: string) => string;
+/**
+ * Build a broadcast subject.
+ *
+ * @param pattern - The message pattern (e.g. `'config.updated'`).
+ * @returns `broadcast.{pattern}`
+ */
+declare const buildBroadcastSubject: (pattern: string) => string;
 /**
  * Build the JetStream stream name for a given service and kind.
  *
  * @param serviceName - Service name from `forRoot({ name })`.
- * @param kind - Stream kind (`'ev'`, `'cmd'`, or `'broadcast'`).
+ * @param kind - Stream kind ({@link StreamKind}).
  * @returns Stream name (e.g. `orders__microservice_ev-stream` or `broadcast-stream`).
  */
 declare const streamName: (serviceName: string, kind: StreamKind) => string;
+/**
+ * Build the JetStream dead-letter queue stream name for a given service.
+ *
+ * @param serviceName - Service name from `forRoot({ name })`.
+ * @returns DLQ Stream name (e.g. `orders__microservice_dlq-stream`).
+ */
+declare const dlqStreamName: (serviceName: string) => string;
 /**
  * Build the JetStream consumer name for a given service and kind.
  *
  * @param serviceName - Service name from `forRoot({ name })`.
- * @param kind - Stream kind (`'ev'`, `'cmd'`, or `'broadcast'`).
+ * @param kind - Stream kind ({@link StreamKind}).
  * @returns Consumer name (e.g. `orders__microservice_ev-consumer`).
  */
 declare const consumerName: (serviceName: string, kind: StreamKind) => string;
@@ -1401,4 +1770,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, type DeadLetterInfo, EventBus, JETSTREAM_CODEC, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS, JetstreamClient, type JetstreamFeatureOptions, JetstreamHeader, JetstreamHealthIndicator, type JetstreamHealthStatus, JetstreamModule, type JetstreamModuleAsyncOptions, type JetstreamModuleOptions, JetstreamRecord, JetstreamRecordBuilder, JetstreamStrategy, JsonCodec, MessageKind, type OrderedEventOverrides, PatternPrefix, type RpcConfig, RpcContext, type StreamConsumerOverrides, StreamKind, TransportEvent, type TransportHooks, buildSubject, consumerName, getClientToken, internalName, isCoreRpcMode, isJetStreamRpcMode, streamName, toNanos };
+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 };