@drarzter/kafka-client 0.7.4 → 0.9.2

package/dist/{types-Db7qSbZP.d.mts → types-4XNxkici.d.mts}

@@ -1,3 +1,212 @@
+/** A topic-partition pair. */
+type ITopicPartition = {
+    topic: string;
+    partition: number;
+};
+/** A topic-partition pair with an absolute offset string. */
+type ITopicPartitionOffset = {
+    topic: string;
+    partition: number;
+    offset: string;
+};
+/** Pause / resume assignment shape: one topic + its partition list. */
+type ITopicPartitions = {
+    topic: string;
+    partitions: number[];
+};
+/** A single message in a produce request. */
+type IProducerMessage = {
+    value: string | null;
+    key?: string;
+    headers?: Record<string, string | Buffer | string[]>;
+};
+/** Produce request payload for one topic. */
+type IProducerRecord = {
+    topic: string;
+    messages: IProducerMessage[];
+};
+/** Options for creating a producer. */
+type IProducerCreationOptions = {
+    /** When set, the producer uses idempotent + exactly-once semantics. */
+    transactionalId?: string;
+    /** Enable idempotent writes (required for `transactionalId`). */
+    idempotent?: boolean;
+};
+/** An open Kafka transaction. */
+interface ITransaction {
+    send(record: IProducerRecord): Promise<void>;
+    /**
+     * Atomically commit offsets for `consumer` as part of this transaction.
+     * The `consumer` parameter must be the `IConsumer` whose offsets are being committed.
+     */
+    sendOffsets(options: {
+        consumer: IConsumer;
+        topics: Array<{
+            topic: string;
+            partitions: Array<{
+                partition: number;
+                offset: string;
+            }>;
+        }>;
+    }): Promise<void>;
+    commit(): Promise<void>;
+    abort(): Promise<void>;
+}
+/** A Kafka producer. */
+interface IProducer {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    send(record: IProducerRecord): Promise<void>;
+    transaction(): Promise<ITransaction>;
+}
+/** A single message in an `eachMessage` callback. */
+type IMessage = {
+    value: Buffer | null;
+    /** Header map as returned by librdkafka — values may be arrays. */
+    headers: Record<string, any>;
+    offset: string;
+    key?: Buffer | null;
+};
+/** Payload passed to the `eachMessage` handler. */
+type IEachMessagePayload = {
+    topic: string;
+    partition: number;
+    message: IMessage;
+};
+/** A batch of messages from one topic-partition. */
+type IMessageBatch = {
+    topic: string;
+    partition: number;
+    messages: IMessage[];
+    highWatermark?: string;
+};
+/** Payload passed to the `eachBatch` handler. */
+type IEachBatchPayload = {
+    batch: IMessageBatch;
+    /** Send a heartbeat to the broker to prevent session timeout. */
+    heartbeat: () => Promise<void>;
+    /** Mark `offset` as processed (without committing). */
+    resolveOffset: (offset: string) => void;
+    /** Commit if the auto-commit threshold has been reached. */
+    commitOffsetsIfNecessary: () => Promise<void>;
+};
+/** Configuration passed to `IConsumer.run()`. */
+type IConsumerRunConfig = {
+    eachMessage?: (payload: IEachMessagePayload) => Promise<void>;
+    eachBatch?: (payload: IEachBatchPayload) => Promise<void>;
+};
+/** Options for creating a consumer. */
+type IConsumerCreationOptions = {
+    groupId: string;
+    fromBeginning?: boolean;
+    autoCommit?: boolean;
+    partitionAssigner?: "cooperative-sticky" | "roundrobin" | "range";
+    /** Fired on every partition assign/revoke. */
+    onRebalance?: (type: "assign" | "revoke", assignments: ITopicPartition[]) => void;
+};
+/** A Kafka consumer. */
+interface IConsumer {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(options: {
+        topics: (string | RegExp)[];
+    }): Promise<void>;
+    run(config: IConsumerRunConfig): Promise<void>;
+    pause(assignments: ITopicPartitions[]): void;
+    resume(assignments: ITopicPartitions[]): void;
+    /** Seek a partition to an explicit offset. */
+    seek(options: ITopicPartitionOffset): void;
+    /** Current partition assignment for this consumer. */
+    assignment(): ITopicPartition[];
+    commitOffsets(offsets: ITopicPartitionOffset[]): Promise<void>;
+    /** Stop processing (alias for disconnect in some usages). */
+    stop(): Promise<void>;
+}
+/** Low/current/high watermark offsets for one partition. */
+type IPartitionWatermarks = {
+    partition: number;
+    low: string;
+    high: string;
+};
+/** A partition → offset pair. */
+type IPartitionOffset = {
+    partition: number;
+    offset: string;
+};
+/** Committed offsets for a group's topic. */
+type IGroupTopicOffsets = {
+    topic: string;
+    partitions: IPartitionOffset[];
+};
+/** A consumer group descriptor. */
+type IGroupDescription = {
+    groupId: string;
+    state?: string;
+};
+/** Partition metadata. */
+type IPartitionMetadata = {
+    partitionId?: number;
+    partition?: number;
+    leader?: number;
+    replicas?: (number | {
+        nodeId: number;
+    })[];
+    isr?: (number | {
+        nodeId: number;
+    })[];
+};
+/** Topic metadata. */
+type ITopicMetadata = {
+    name: string;
+    partitions: IPartitionMetadata[];
+};
+/** A Kafka admin client. */
+interface IAdmin {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    createTopics(options: {
+        topics: Array<{
+            topic: string;
+            numPartitions: number;
+        }>;
+    }): Promise<void>;
+    fetchTopicOffsets(topic: string): Promise<IPartitionWatermarks[]>;
+    fetchTopicOffsetsByTimestamp(topic: string, timestamp: number): Promise<IPartitionOffset[]>;
+    fetchOffsets(options: {
+        groupId: string;
+    }): Promise<IGroupTopicOffsets[]>;
+    setOffsets(options: {
+        groupId: string;
+        topic: string;
+        partitions: IPartitionOffset[];
+    }): Promise<void>;
+    listTopics(): Promise<string[]>;
+    listGroups(): Promise<{
+        groups: IGroupDescription[];
+    }>;
+    fetchTopicMetadata(options?: {
+        topics?: string[];
+    }): Promise<{
+        topics: ITopicMetadata[];
+    }>;
+    deleteGroups(groupIds: string[]): Promise<void>;
+    deleteTopicRecords(options: {
+        topic: string;
+        partitions: IPartitionOffset[];
+    }): Promise<void>;
+}
+/**
+ * Factory that creates connected Kafka primitives.
+ * The default implementation wraps `@confluentinc/kafka-javascript` via
+ * `ConfluentTransport`. Inject a custom transport (e.g. a fake) via
+ * `KafkaClientOptions.transport` for testing or alternative broker support.
+ */
+interface KafkaTransport {
+    producer(options?: IProducerCreationOptions): IProducer;
+    consumer(options: IConsumerCreationOptions): IConsumer;
+    admin(): IAdmin;
+}
+
 /**
  * Context passed as the second argument to `SchemaLike.parse()`.
  * Enables schema-registry adapters, version-aware migration, and
@@ -115,6 +324,15 @@ declare const HEADER_LAMPORT_CLOCK = "x-lamport-clock";
  *
  * On **consume**, the library extracts those headers and assembles
  * an `EventEnvelope` that is passed to the handler.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders'], async (envelope: EventEnvelope<Order>) => {
+ *   console.log(envelope.payload.orderId);  // typed payload
+ *   console.log(envelope.correlationId);    // auto-propagated
+ *   console.log(envelope.eventId);          // unique message ID
+ * });
+ * ```
  */
 interface EventEnvelope<T> {
     /** Deserialized + validated message body. */
@@ -142,9 +360,26 @@ interface EnvelopeCtx {
     correlationId: string;
     traceparent?: string;
 }
-/** Read the current envelope context (correlationId / traceparent) from ALS. */
+/**
+ * Read the current envelope context (correlationId / traceparent) from ALS.
+ * Returns `undefined` outside of a Kafka consumer handler.
+ * @example
+ * ```ts
+ * const ctx = getEnvelopeContext();
+ * if (ctx) console.log('correlationId:', ctx.correlationId);
+ * ```
+ */
 declare function getEnvelopeContext(): EnvelopeCtx | undefined;
-/** Execute `fn` inside an envelope context so nested sends inherit correlationId. */
+/**
+ * Execute `fn` inside an envelope context so nested sends inherit correlationId.
+ * Automatically called by the consumer pipeline — use this in tests or manual flows.
+ * @example
+ * ```ts
+ * await runWithEnvelopeContext({ correlationId: 'abc-123' }, async () => {
+ *   await kafka.sendMessage('orders.created', payload); // inherits correlationId
+ * });
+ * ```
+ */
 declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
 /** Options accepted by `buildEnvelopeHeaders`. */
 interface EnvelopeHeaderOptions {
@@ -213,7 +448,18 @@ type MessageHeaders = Record<string, string>;
  * - `'zstd'` — best ratio, slightly slower
  */
 type CompressionType = "none" | "gzip" | "snappy" | "lz4" | "zstd";
-/** Options for sending a single message. */
+/**
+ * Options for sending a single message.
+ *
+ * @example
+ * ```ts
+ * await kafka.sendMessage('orders.created', { orderId: '123', amount: 99 }, {
+ *   key: 'order-123',
+ *   headers: { 'x-source': 'checkout-service' },
+ *   compression: 'snappy',
+ * });
+ * ```
+ */
 interface SendOptions {
     /** Partition key for message routing. */
     key?: string;
@@ -232,7 +478,17 @@ interface SendOptions {
      */
     compression?: CompressionType;
 }
-/** Shape of each item in a `sendBatch` call. */
+/**
+ * Shape of each item in a `sendBatch` call.
+ *
+ * @example
+ * ```ts
+ * await kafka.sendBatch('orders.created', [
+ *   { value: { orderId: '1', amount: 10 }, key: 'order-1' },
+ *   { value: { orderId: '2', amount: 20 }, key: 'order-2', headers: { 'x-priority': 'high' } },
+ * ]);
+ * ```
+ */
 interface BatchMessageItem<V> {
     value: V;
     /**
@@ -247,7 +503,14 @@ interface BatchMessageItem<V> {
     schemaVersion?: number;
     eventId?: string;
 }
-/** Options for a `sendBatch` call (applies to all messages in the batch). */
+/**
+ * Options for a `sendBatch` call (applies to all messages in the batch).
+ *
+ * @example
+ * ```ts
+ * await kafka.sendBatch('metrics', messages, { compression: 'zstd' });
+ * ```
+ */
 interface BatchSendOptions {
     /**
      * Compression codec for this batch.
@@ -256,7 +519,19 @@ interface BatchSendOptions {
      */
     compression?: CompressionType;
 }
-/** Metadata exposed to batch consumer handlers. */
+/**
+ * Metadata exposed to batch consumer handlers.
+ *
+ * @example
+ * ```ts
+ * await kafka.startBatchConsumer(['events'], async (envelopes, meta) => {
+ *   console.log(`Partition ${meta.partition}, HWM ${meta.highWatermark}`);
+ *   await db.insertMany(envelopes.map(e => e.payload));
+ *   meta.resolveOffset(envelopes.at(-1)!.offset);
+ *   await meta.commitOffsetsIfNecessary();
+ * }, { autoCommit: false });
+ * ```
+ */
 interface BatchMeta {
     /** Partition number for this batch. */
     partition: number;
@@ -277,6 +552,14 @@ interface BatchMeta {
 /**
  * Options for Lamport Clock-based message deduplication.
  *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['payments'], handler, {
+ *   deduplication: { strategy: 'dlq' },
+ *   dlq: true,
+ * });
+ * ```
+ *
  * The producer stamps every outgoing message with a monotonically increasing
  * `x-lamport-clock` header. The consumer tracks the last processed value per
  * `topic:partition` and skips any message whose clock is not strictly greater
@@ -311,6 +594,19 @@ interface DeduplicationOptions {
 /**
  * Options for the per-partition circuit breaker.
  *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['payments'], handler, {
+ *   circuitBreaker: {
+ *     threshold: 5,
+ *     recoveryMs: 30_000,
+ *     windowSize: 20,
+ *     halfOpenSuccesses: 2,
+ *   },
+ *   dlq: true,
+ * });
+ * ```
+ *
  * The circuit breaker tracks recent message outcomes in a **sliding window** and
  * opens (pauses the partition) when too many failures accumulate:
  *
@@ -343,7 +639,21 @@ interface CircuitBreakerOptions {
      */
     halfOpenSuccesses?: number;
 }
-/** Options for configuring a Kafka consumer. */
+/**
+ * Options for configuring a Kafka consumer.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders.created'], handler, {
+ *   groupId: 'billing-service',
+ *   retry: { maxRetries: 5, backoffMs: 1000 },
+ *   dlq: true,
+ *   deduplication: { strategy: 'drop' },
+ *   circuitBreaker: { threshold: 3, recoveryMs: 60_000 },
+ *   interceptors: [loggingInterceptor],
+ * });
+ * ```
+ */
 interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
     /** Override the default consumer group ID from the constructor. */
     groupId?: string;
@@ -430,8 +740,32 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * when both are set. Use this to handle TTL expiry differently per consumer group.
      */
     onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
+    /**
+     * Called when a message is silently dropped after all retries are exhausted
+     * and `dlq` is not enabled.
+     *
+     * **Per-consumer override**: takes precedence over `KafkaClientOptions.onMessageLost`
+     * when both are set. Use this for consumer-specific alerting or dead-message logging.
+     */
+    onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
+    /**
+     * Called before each retry attempt (both in-process and retry-topic paths).
+     *
+     * **Per-consumer override**: fires in addition to any global instrumentation hooks.
+     * Use this for per-consumer retry metrics or structured logging.
+     */
+    onRetry?: (envelope: EventEnvelope<any>, attempt: number, maxRetries: number) => void | Promise<void>;
 }
-/** Configuration for consumer retry behavior. */
+/**
+ * Configuration for consumer retry behavior.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders'], handler, {
+ *   retry: { maxRetries: 5, backoffMs: 500, maxBackoffMs: 10_000 },
+ * });
+ * ```
+ */
 interface RetryOptions {
     /** Maximum number of retry attempts before giving up. */
     maxRetries: number;
@@ -446,6 +780,17 @@ interface RetryOptions {
  *
  * Interceptors are per-consumer. For client-wide hooks (e.g. OTel),
  * use `KafkaInstrumentation` instead.
+ *
+ * @example
+ * ```ts
+ * const logger: ConsumerInterceptor = {
+ *   async before(envelope) { console.log('Processing', envelope.eventId); },
+ *   async after(envelope)  { console.log('Done',       envelope.eventId); },
+ *   async onError(envelope, err) { console.error('Failed', err.message); },
+ * };
+ *
+ * await kafka.startConsumer(['orders'], handler, { interceptors: [logger] });
+ * ```
  */
 interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap> {
     /** Called before the message handler. */
@@ -465,6 +810,25 @@ interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap
  *     async context (e.g. `context.with(spanCtx, fn)` for OpenTelemetry). Multiple
  *     wraps from different instrumentations are composed in declaration order,
  *     so the first instrumentation's wrap is the outermost.
+ *
+ * @example
+ * ```ts
+ * // Cleanup-only (legacy form):
+ * beforeConsume(envelope) {
+ *   const timer = startTimer();
+ *   return () => timer.end();
+ * }
+ *
+ * // Wrap form — run handler inside an OTel span context:
+ * beforeConsume(envelope) {
+ *   const ctx = propagator.extract(ROOT_CONTEXT, envelope.headers);
+ *   const span = tracer.startSpan(envelope.topic, {}, ctx);
+ *   return {
+ *     wrap: (fn) => context.with(trace.setSpan(ctx, span), fn),
+ *     cleanup: () => span.end(),
+ *   };
+ * }
+ * ```
  */
 type BeforeConsumeResult = (() => void) | {
     cleanup?(): void;
@@ -479,7 +843,80 @@ type BeforeConsumeResult = (() => void) | {
  * - `'ttl-expired'` — message age exceeded `messageTtlMs` before the handler ran.
  */
 type DlqReason = "handler-error" | "validation-error" | "lamport-clock-duplicate" | "ttl-expired";
-/** Options for `replayDlq`. */
+/**
+ * Options for `readSnapshot`.
+ *
+ * @example
+ * ```ts
+ * const snapshot = await kafka.readSnapshot('users.state', {
+ *   schema: UserSchema,
+ *   onTombstone: (key) => console.log(`Key ${key} was compacted away`),
+ * });
+ * ```
+ */
+interface ReadSnapshotOptions {
+    /**
+     * Schema to validate each message payload against (Zod, Valibot, ArkType, or any `.parse()` shape).
+     * Messages that fail validation are skipped with a warning log — they do not throw.
+     */
+    schema?: SchemaLike;
+    /**
+     * Called when a tombstone record (null-value message) is encountered.
+     * The corresponding key is removed from the snapshot automatically.
+     * Use this for auditing or logging which keys were compacted away.
+     */
+    onTombstone?: (key: string) => void;
+}
+/** A single partition offset entry stored in a checkpoint record. */
+interface CheckpointEntry {
+    topic: string;
+    partition: number;
+    offset: string;
+}
+/** Result returned by a successful `checkpointOffsets` call. */
+interface CheckpointResult {
+    /** Consumer group whose offsets were saved. */
+    groupId: string;
+    /** Topics included in the checkpoint. */
+    topics: string[];
+    /** Total number of topic-partition pairs saved. */
+    partitionCount: number;
+    /** Unix timestamp (ms) when the checkpoint was created. */
+    savedAt: number;
+}
+/** Options for `restoreFromCheckpoint`. */
+interface RestoreCheckpointOptions {
+    /**
+     * Target Unix timestamp (ms). The newest checkpoint whose `savedAt` is **≤ this value**
+     * is selected. Defaults to the latest available checkpoint when omitted.
+     */
+    timestamp?: number;
+}
+/** Result returned by a successful `restoreFromCheckpoint` call. */
+interface CheckpointRestoreResult {
+    /** Consumer group that was repositioned. */
+    groupId: string;
+    /** The committed offsets restored from the checkpoint. */
+    offsets: CheckpointEntry[];
+    /** Unix timestamp (ms) recorded when the checkpoint was originally saved. */
+    restoredAt: number;
+    /** Age of the restored checkpoint in milliseconds (now − `restoredAt`). */
+    checkpointAge: number;
+}
+/**
+ * Options for `replayDlq`.
+ *
+ * @example
+ * ```ts
+ * await kafka.replayDlq('orders.created', {
+ *   targetTopic: 'orders.retry-manual',
+ *   dryRun: false,
+ *   filter: (headers, value) =>
+ *     headers['x-dlq-reason'] === 'handler-error' &&
+ *     JSON.parse(value).amount > 0,
+ * });
+ * ```
+ */
 interface DlqReplayOptions {
     /**
      * Override the target topic to re-publish to.
@@ -497,6 +934,13 @@ interface DlqReplayOptions {
      * @param value Raw message value (JSON string).
      */
     filter?: (headers: MessageHeaders, value: string) => boolean;
+    /**
+     * Seek to the earliest available offset before consuming, regardless of any
+     * previously committed offsets for the replay consumer group.
+     * Default: `true` — full replay of all DLQ messages on every call.
+     * Set to `false` to replay only messages added since the previous `replayDlq` call.
+     */
+    fromBeginning?: boolean;
 }
 /**
  * Snapshot of internal event counters accumulated since client creation
@@ -517,6 +961,24 @@ interface KafkaMetrics {
  * Use this for cross-cutting concerns like tracing and metrics.
  *
  * @see `otelInstrumentation()` from `@drarzter/kafka-client/otel`
+ *
+ * @example
+ * ```ts
+ * const tracing: KafkaInstrumentation = {
+ *   beforeSend(topic, headers) {
+ *     headers['traceparent'] = getCurrentTraceId();
+ *   },
+ *   beforeConsume(envelope) {
+ *     const span = tracer.startSpan(envelope.topic);
+ *     return { cleanup: () => span.end() };
+ *   },
+ *   onDlq(envelope, reason) {
+ *     metrics.increment('kafka.dlq', { topic: envelope.topic, reason });
+ *   },
+ * };
+ *
+ * const kafka = new KafkaClient(config, groupId, { instrumentation: [tracing] });
+ * ```
  */
 interface KafkaInstrumentation {
     /** Called before sending — can mutate `headers` (e.g. inject `traceparent`). */
@@ -558,19 +1020,155 @@ interface KafkaInstrumentation {
     /** Called when the circuit closes (normal operation restored). */
     onCircuitClose?(topic: string, partition: number): void;
 }
-/** Context passed to the `transaction()` callback with type-safe send methods. */
+/**
+ * Context passed to the `transaction()` callback with type-safe send methods.
+ *
+ * @example
+ * ```ts
+ * await kafka.transaction(async (tx) => {
+ *   await tx.send('inventory.reserved', { itemId: 'a', qty: 1 });
+ *   await tx.sendBatch('audit.log', [
+ *     { value: { action: 'reserve', itemId: 'a' } },
+ *   ]);
+ * });
+ * ```
+ */
 interface TransactionContext<T extends TopicMapConstraint<T>> {
     send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
     send<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
     sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>, options?: BatchSendOptions): Promise<void>;
 }
-/** Handle returned by `startConsumer` / `startBatchConsumer`. */
+/**
+ * Transactional context passed to each `startTransactionalConsumer` handler invocation.
+ *
+ * Every call to `send` or `sendBatch` on this object is part of the same Kafka
+ * transaction as the source message offset commit. Either all sends and the offset
+ * commit succeed atomically, or the transaction is aborted and the source message
+ * is redelivered.
+ *
+ * @example
+ * ```ts
+ * await kafka.startTransactionalConsumer(['orders.created'], async (envelope, tx) => {
+ *   await tx.send('inventory.reserved', { orderId: envelope.payload.orderId, qty: 1 });
+ *   await tx.sendBatch('audit.log', [{ value: { action: 'reserve', orderId: envelope.payload.orderId } }]);
+ * });
+ * ```
+ */
+interface TransactionalHandlerContext<T extends TopicMapConstraint<T>> {
+    /**
+     * Send a message as part of this message's transaction.
+     * The send is staged — it only becomes visible to consumers after the transaction commits.
+     */
+    send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    /**
+     * Send multiple messages as part of this message's transaction.
+     * All messages are staged together and become visible only after commit.
+     */
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
+}
+/**
+ * Routing configuration for `startRoutedConsumer`.
+ *
+ * Messages are dispatched to the handler whose key matches the value of `header`.
+ * Unmatched messages are forwarded to `fallback` if provided, or silently skipped.
+ *
+ * @example
+ * ```ts
+ * await kafka.startRoutedConsumer(['events'], {
+ *   header: 'x-event-type',
+ *   routes: {
+ *     'order.created':   async (e) => handleOrderCreated(e.payload),
+ *     'order.cancelled': async (e) => handleOrderCancelled(e.payload),
+ *   },
+ *   fallback: async (e) => logger.warn('Unknown event type', e.headers),
+ * });
+ * ```
+ */
+interface RoutingOptions<E> {
+    /** Header whose value determines which handler is invoked. */
+    header: string;
+    /**
+     * Map of header value → handler.
+     * The handler with the matching key is called for each message.
+     */
+    routes: Record<string, (envelope: EventEnvelope<E>) => Promise<void>>;
+    /**
+     * Called when no route matches the header value (or the header is absent).
+     * If omitted, unmatched messages are silently skipped.
+     */
+    fallback?: (envelope: EventEnvelope<E>) => Promise<void>;
+}
+/**
+ * Metadata passed to the `startWindowConsumer` handler on each flush.
+ *
+ * @example
+ * ```ts
+ * await kafka.startWindowConsumer('events', async (batch, meta) => {
+ *   console.log(`Flush: ${batch.length} events, trigger=${meta.trigger}`);
+ *   console.log(`Window: ${meta.windowEnd - meta.windowStart} ms`);
+ *   await db.insertMany(batch.map(e => e.payload));
+ * }, { maxMessages: 100, maxMs: 5_000 });
+ * ```
+ */
+interface WindowMeta {
+    /** What triggered this flush: accumulated `maxMessages` messages, or the `maxMs` timer. */
+    trigger: "size" | "time";
+    /** Unix timestamp (ms) of the first message that entered the current window. */
+    windowStart: number;
+    /** Unix timestamp (ms) when the flush was initiated. */
+    windowEnd: number;
+}
+/**
+ * Options for `startWindowConsumer`.
+ *
+ * Extends `ConsumerOptions` — all standard consumer settings apply.
+ * `retryTopics`, `retryTopicAssignmentTimeoutMs`, and `queueHighWaterMark`
+ * are excluded: they are incompatible with windowed accumulation.
+ */
+interface WindowConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> extends Omit<ConsumerOptions<T>, "retryTopics" | "retryTopicAssignmentTimeoutMs" | "queueHighWaterMark"> {
+    /**
+     * Maximum number of messages to accumulate before flushing.
+     * When the buffer reaches this size the handler is called immediately,
+     * regardless of how much time has elapsed since the first message.
+     */
+    maxMessages: number;
+    /**
+     * Maximum time (ms) to wait after the first message before flushing.
+     * When this timer expires the handler is called with whatever messages
+     * have accumulated so far — even if the buffer is not full.
+     */
+    maxMs: number;
+}
+/**
+ * Handle returned by `startConsumer` / `startBatchConsumer`.
+ *
+ * @example
+ * ```ts
+ * const handle = await kafka.startConsumer(['orders'], handler);
+ * // later, on shutdown:
+ * await handle.stop();
+ * ```
+ */
 interface ConsumerHandle {
     /** The consumer group ID this consumer is running under. */
     groupId: string;
     /** Stop this consumer. Equivalent to calling `client.stopConsumer(groupId)`. */
     stop(): Promise<void>;
+    /**
+     * Resolves once the consumer has received its first partition assignment from
+     * the broker (i.e. it has joined the group and is ready to receive messages).
+     *
+     * Use this in tests and startup probes instead of a fixed `setTimeout` delay:
+     *
+     * @example
+     * ```ts
+     * const handle = await kafka.startConsumer(['orders'], handler);
+     * await handle.ready(); // wait for partition assignment — no fixed sleep needed
+     * await kafka.sendMessage('orders', payload);
+     * ```
+     */
+    ready(): Promise<void>;
 }
 /** Result returned by `KafkaClient.checkStatus()`. */
 type KafkaHealthResult = {
@@ -612,15 +1210,34 @@ interface TopicDescription {
 }
 /** Interface describing all public methods of the Kafka client. */
 interface IKafkaClient<T extends TopicMapConstraint<T>> {
+    /**
+     * @example
+     * ```ts
+     * const status = await kafka.checkStatus();
+     * if (status.status === 'down') console.error(status.error);
+     * ```
+     */
     checkStatus(): Promise<KafkaHealthResult>;
     /**
      * List all consumer groups known to the broker.
      * @returns Array of `{ groupId, state }` summaries.
+     *
+     * @example
+     * ```ts
+     * const groups = await kafka.listConsumerGroups();
+     * console.log(groups.map(g => `${g.groupId}: ${g.state}`));
+     * ```
      */
     listConsumerGroups(): Promise<ConsumerGroupSummary[]>;
     /**
      * Describe topics — returns partition layout, leader, replicas, and ISR for each topic.
      * @param topics Topic names to describe. Omit to describe all topics visible to this client.
+     *
+     * @example
+     * ```ts
+     * const [desc] = await kafka.describeTopics(['orders.created']);
+     * console.log(desc.partitions.length); // number of partitions
+     * ```
      */
     describeTopics(topics?: string[]): Promise<TopicDescription[]>;
     /**
@@ -630,6 +1247,14 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      *
      * @param topic Topic name.
      * @param partitions Array of `{ partition, offset }` — records before each offset are deleted.
+     *
+     * @example
+     * ```ts
+     * await kafka.deleteRecords('orders.created', [
+     *   { partition: 0, offset: '1000' },
+     *   { partition: 1, offset: '500'  },
+     * ]);
+     * ```
      */
     deleteRecords(topic: string, partitions: Array<{
         partition: number;
@@ -640,12 +1265,30 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      * Lag = (broker high-watermark offset) − (last committed offset).
      * - A committed offset of `-1` (no offset committed yet) counts as full lag.
      * - Defaults to the client's default `groupId` when none is provided.
+     *
+     * @example
+     * ```ts
+     * const lag = await kafka.getConsumerLag();
+     * const total = lag.reduce((sum, p) => sum + p.lag, 0);
+     * console.log(`Total lag: ${total} messages`);
+     * ```
      */
     getConsumerLag(groupId?: string): Promise<Array<{
         topic: string;
         partition: number;
         lag: number;
     }>>;
+    /**
+     * @example
+     * ```ts
+     * const handle = await kafka.startConsumer(['orders.created'], async (envelope) => {
+     *   await processOrder(envelope.payload);
+     * }, { retry: { maxRetries: 3 }, dlq: true });
+     *
+     * // on shutdown:
+     * await handle.stop();
+     * ```
+     */
     startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (envelope: EventEnvelope<T[K[number]]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (envelope: EventEnvelope<D["__type"]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     /**
@@ -654,6 +1297,15 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      * Incompatible with `retryTopics: true`.
      */
     startConsumer(topics: (string | RegExp)[], handleMessage: (envelope: EventEnvelope<T[keyof T]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    /**
+     * @example
+     * ```ts
+     * await kafka.startBatchConsumer(['metrics'], async (envelopes, meta) => {
+     *   await db.insertMany(envelopes.map(e => e.payload));
+     *   meta.resolveOffset(envelopes.at(-1)!.offset);
+     * }, { autoCommit: false });
+     * ```
+     */
     startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (envelopes: EventEnvelope<T[K[number]]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (envelopes: EventEnvelope<D["__type"]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     /**
@@ -662,12 +1314,101 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      * Incompatible with `retryTopics: true`.
      */
     startBatchConsumer(topics: (string | RegExp)[], handleBatch: (envelopes: EventEnvelope<T[keyof T]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    /**
+     * Subscribe to a topic and accumulate messages into a window, flushing the handler
+     * when **either** `maxMessages` messages have accumulated **or** `maxMs` milliseconds
+     * have elapsed since the first message in the current window — whichever fires first.
+     *
+     * This is semantically different from `startBatchConsumer`, which delivers
+     * broker-sized batches of unpredictable size. A window consumer gives you control
+     * over both the size and the latency of each batch — useful for micro-batching
+     * writes to a database, aggregating events before processing, or rate-limiting a
+     * downstream API.
+     *
+     * On `handle.stop()`, any messages remaining in the buffer are flushed before the
+     * consumer disconnects, so no messages are lost on clean shutdown.
+     *
+     * @param topic Topic to consume.
+     * @param handler Called with each flushed window and a `WindowMeta` describing the trigger.
+     * @param options Window size/timeout and standard consumer options.
+     *
+     * @example
+     * ```ts
+     * await kafka.startWindowConsumer('events', async (batch, meta) => {
+     *   console.log(`Flushing ${batch.length} events (trigger: ${meta.trigger})`);
+     *   await db.insertMany(batch.map(e => e.payload));
+     * }, { maxMessages: 100, maxMs: 5_000 });
+     * ```
+     */
+    startWindowConsumer<K extends keyof T & string>(topic: K, handler: (envelopes: EventEnvelope<T[K]>[], meta: WindowMeta) => Promise<void>, options: WindowConsumerOptions<T>): Promise<ConsumerHandle>;
+    /**
+     * Subscribe to one or more topics and dispatch each message to a handler based
+     * on the value of a specific Kafka header. Eliminates boilerplate `if/switch`
+     * statements inside a catch-all handler when one topic carries multiple event types.
+     *
+     * Messages whose header value does not match any route key are forwarded to `fallback`
+     * if provided, or silently skipped otherwise.
+     *
+     * Accepts the same `ConsumerOptions` as `startConsumer` — retry, DLQ, deduplication,
+     * circuit breaker, interceptors, etc. all apply to every route.
+     *
+     * @param topics Array of topic keys or `RegExp` patterns.
+     * @param routing Header name, route map, and optional fallback handler.
+     * @param options Standard consumer options.
+     * @returns A handle with `{ groupId, stop() }`.
+     *
+     * @example
+     * ```ts
+     * await kafka.startRoutedConsumer(['domain.events'], {
+     *   header: 'x-event-type',
+     *   routes: {
+     *     'order.created':   async (e) => handleOrderCreated(e.payload),
+     *     'order.cancelled': async (e) => handleOrderCancelled(e.payload),
+     *   },
+     *   fallback: async (e) => logger.warn('Unknown event type', e.headers),
+     * });
+     * ```
+     */
+    startRoutedConsumer<K extends Array<keyof T>>(topics: K, routing: RoutingOptions<T[K[number]]>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    /**
+     * Subscribe to topics and consume messages with **exactly-once semantics** for
+     * read-process-write pipelines.
+     *
+     * Each message is processed inside a Kafka transaction: the handler receives a
+     * `TransactionalHandlerContext` with `send` / `sendBatch` methods that stage
+     * outgoing messages inside the transaction. When the handler resolves, the source
+     * offset commit and all staged sends are committed atomically. A handler error
+     * aborts the transaction and the source message is redelivered — no sends become
+     * visible to downstream consumers.
+     *
+     * Incompatible with `retryTopics: true` — throws at startup if set.
+     * `autoCommit` is always `false` (managed by the transaction).
+     *
+     * @param topics Array of topic keys.
+     * @param handler Called for each message with the decoded envelope and a transaction context.
+     * @param options Standard consumer options (`retry`, `dlq`, `deduplication`, etc.).
+     * @returns A handle with `{ groupId, stop() }`.
+     *
+     * @example
+     * ```ts
+     * await kafka.startTransactionalConsumer(['orders.created'], async (envelope, tx) => {
+     *   await tx.send('inventory.reserved', { orderId: envelope.payload.orderId, qty: 1 });
+     * });
+     * ```
+     */
+    startTransactionalConsumer<K extends Array<keyof T>>(topics: K, handler: (envelope: EventEnvelope<T[K[number]]>, tx: TransactionalHandlerContext<T>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
     /**
      * Stop consumer(s).
      * - `stopConsumer(groupId)` — disconnect and remove the consumer for a specific group.
      * - `stopConsumer()` — disconnect and remove all consumers.
      */
     stopConsumer(groupId?: string): Promise<void>;
+    /**
+     * @example
+     * ```ts
+     * await kafka.sendMessage('orders.created', { orderId: '123', amount: 99 });
+     * ```
+     */
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
     /**
      * Send a null-value (tombstone) message to a topic.
@@ -681,10 +1422,39 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      * @param topic Topic name or descriptor.
      * @param key Partition key identifying the record to tombstone.
      * @param headers Optional custom Kafka headers.
+     *
+     * @example
+     * ```ts
+     * await kafka.sendTombstone('users.state', 'user-42');
+     * ```
      */
     sendTombstone(topic: string, key: string, headers?: MessageHeaders): Promise<void>;
+    /**
+     * @example
+     * ```ts
+     * await kafka.sendBatch('orders.created', [
+     *   { value: { orderId: '1', amount: 10 }, key: 'order-1' },
+     *   { value: { orderId: '2', amount: 20 }, key: 'order-2' },
+     * ]);
+     * ```
+     */
     sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
+    /**
+     * @example
+     * ```ts
+     * await kafka.transaction(async (tx) => {
+     *   await tx.send('orders.created',    { orderId: '123', amount: 99 });
+     *   await tx.send('inventory.reserved', { itemId: 'a',  qty: 1 });
+     * });
+     * ```
+     */
     transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
+    /**
+     * @example
+     * ```ts
+     * const id = kafka.getClientId(); // e.g. 'my-service'
+     * ```
+     */
     getClientId(): ClientId;
     /**
      * Return a snapshot of internal event counters (retry / DLQ / dedup).
@@ -693,12 +1463,26 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      *   if no events have been observed for that topic yet.
      *
      * Counters accumulate since client creation or the last `resetMetrics()` call.
+     *
+     * @example
+     * ```ts
+     * const { processedCount, dlqCount, retryCount } = kafka.getMetrics();
+     * console.log(`Processed: ${processedCount}, DLQ: ${dlqCount}`);
+     *
+     * const topicMetrics = kafka.getMetrics('orders.created');
+     * ```
      */
     getMetrics(topic?: string): Readonly<KafkaMetrics>;
     /**
      * Reset internal event counters to zero.
      * - `resetMetrics()` — reset all topics.
      * - `resetMetrics(topic)` — reset a single topic only.
+     *
+     * @example
+     * ```ts
+     * kafka.resetMetrics();                   // reset all
+     * kafka.resetMetrics('orders.created');   // reset one topic
+     * ```
      */
     resetMetrics(topic?: string): void;
     /**
@@ -709,6 +1493,18 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      * itself is not modified — messages remain there after replay.
      *
      * @returns `{ replayed, skipped }` — counts of re-published vs skipped messages.
+     *
+     * @example
+     * ```ts
+     * const { replayed, skipped } = await kafka.replayDlq('orders.created');
+     * console.log(`Replayed ${replayed}, skipped ${skipped}`);
+     *
+     * // dry-run with filter:
+     * await kafka.replayDlq('orders.created', {
+     *   dryRun: true,
+     *   filter: (headers) => headers['x-dlq-reason'] === 'handler-error',
+     * });
+     * ```
      */
     replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
         replayed: number;
@@ -725,6 +1521,12 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      * @param topic Topic to reset.
      * @param position `'earliest'` seeks to the first available offset; `'latest'`
      *   seeks past the last message (consumer will only see new messages).
+     *
+     * @example
+     * ```ts
+     * await kafka.stopConsumer('billing-service');
+     * await kafka.resetOffsets('billing-service', 'orders.created', 'earliest');
+     * ```
      */
     resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
     /**
@@ -736,6 +1538,14 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      *
      * @param groupId Consumer group to seek. Defaults to the client's default groupId.
      * @param assignments Array of `{ topic, partition, offset }` tuples.
+     *
+     * @example
+     * ```ts
+     * await kafka.seekToOffset('billing-service', [
+     *   { topic: 'orders.created', partition: 0, offset: '1000' },
+     *   { topic: 'orders.created', partition: 1, offset: '500'  },
+     * ]);
+     * ```
      */
     seekToOffset(groupId: string | undefined, assignments: Array<{
         topic: string;
@@ -752,6 +1562,14 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      *
      * @param groupId Consumer group to seek. Defaults to the client's default groupId.
      * @param assignments Array of `{ topic, partition, timestamp }` tuples (Unix ms).
+     *
+     * @example
+     * ```ts
+     * const midnight = new Date('2025-01-01').getTime();
+     * await kafka.seekToTimestamp('billing-service', [
+     *   { topic: 'orders.created', partition: 0, timestamp: midnight },
+     * ]);
+     * ```
      */
     seekToTimestamp(groupId: string | undefined, assignments: Array<{
         topic: string;
@@ -766,12 +1584,84 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      * @param topic Topic name.
      * @param partition Partition index.
      * @param groupId Consumer group. Defaults to the client's default groupId.
+     *
+     * @example
+     * ```ts
+     * const state = kafka.getCircuitState('orders.created', 0);
+     * if (state?.status === 'open') console.warn('Circuit open!', state.failures);
+     * ```
      */
     getCircuitState(topic: string, partition: number, groupId?: string): {
         status: "closed" | "open" | "half-open";
         failures: number;
         windowSize: number;
     } | undefined;
+    /**
+     * Read a compacted topic from the beginning to its current high-watermark and
+     * return a `Map<key, EventEnvelope<T>>` with the **latest** value per key.
+     *
+     * Tombstone records (null-value messages) remove the key from the map —
+     * consistent with log-compaction semantics.
+     *
+     * Useful for bootstrapping in-memory state at service startup without an external cache:
+     * ```ts
+     * const orders = await kafka.readSnapshot('orders.state');
+     * // orders.get('order-123') → EventEnvelope with the latest payload for that key
+     * ```
+     *
+     * @param topic Topic to read. Must be a log-compacted topic (or any topic you want a key → latest-value index for).
+     * @param options Optional schema validation and tombstone callback.
+     * @returns Map keyed by the Kafka message key string; value is the last seen `EventEnvelope`.
+     */
+    readSnapshot<K extends keyof T & string>(topic: K, options?: ReadSnapshotOptions): Promise<Map<string, EventEnvelope<T[K]>>>;
+    /**
+     * Snapshot the current committed offsets of a consumer group into a Kafka topic.
+     *
+     * Each call appends a new checkpoint record keyed by `groupId`. The checkpoint topic
+     * acts as an append-only audit log — use a non-compacted topic to retain history.
+     * Use `restoreFromCheckpoint` to rewind the group to any saved point in time.
+     *
+     * Requires `connectProducer()` to have been called.
+     *
+     * @param groupId Consumer group whose offsets to checkpoint. Defaults to the client's default group.
+     * @param checkpointTopic Topic where checkpoint records are written.
+     * @returns Summary of the saved checkpoint.
+     *
+     * @example
+     * ```ts
+     * const result = await kafka.checkpointOffsets(undefined, 'checkpoints');
+     * console.log(`Saved ${result.partitionCount} offsets at ${result.savedAt}`);
+     * ```
+     */
+    checkpointOffsets(groupId: string | undefined, checkpointTopic: string): Promise<CheckpointResult>;
+    /**
+     * Restore a consumer group's committed offsets from the nearest checkpoint stored in `checkpointTopic`.
+     *
+     * Reads all checkpoint records for the group, selects the newest checkpoint whose `savedAt`
+     * timestamp is ≤ `options.timestamp` (or the latest checkpoint if no timestamp is given),
+     * then calls `admin.setOffsets` for every topic-partition in that checkpoint.
+     *
+     * **The consumer group must be stopped before calling this method** — throws if any consumer
+     * in the group is currently running.
+     *
+     * @param groupId Consumer group to reposition. Defaults to the client's default group.
+     * @param checkpointTopic Topic where checkpoints were written by `checkpointOffsets`.
+     * @param options.timestamp Target Unix ms. Omit to restore the latest checkpoint.
+     * @throws If no checkpoint exists for the group, or if the group is still running.
+     *
+     * @example
+     * ```ts
+     * await kafka.stopConsumer('billing-service');
+     * const result = await kafka.restoreFromCheckpoint(undefined, 'checkpoints');
+     * console.log(`Restored from checkpoint saved ${result.checkpointAge}ms ago`);
+     *
+     * // restore to the state before a specific deployment:
+     * await kafka.restoreFromCheckpoint(undefined, 'checkpoints', {
+     *   timestamp: new Date('2025-06-01T00:00:00Z').getTime(),
+     * });
+     * ```
+     */
+    restoreFromCheckpoint(groupId: string | undefined, checkpointTopic: string, options?: RestoreCheckpointOptions): Promise<CheckpointRestoreResult>;
     /**
      * Consume messages as an async iterator. Useful for scripts, migrations, and
      * one-off processing where the full `startConsumer` lifecycle is unnecessary.
@@ -799,6 +1689,13 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      *
      * @param groupId Consumer group to pause. Defaults to the client's default groupId.
      * @param assignments Topic-partition pairs to pause.
+     *
+     * @example
+     * ```ts
+     * kafka.pauseConsumer(undefined, [{ topic: 'orders.created', partitions: [0, 1] }]);
+     * // ... do some backpressure work ...
+     * kafka.resumeConsumer(undefined, [{ topic: 'orders.created', partitions: [0, 1] }]);
+     * ```
      */
     pauseConsumer(groupId: string | undefined, assignments: Array<{
         topic: string;
@@ -809,6 +1706,11 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
      *
      * @param groupId Consumer group to resume. Defaults to the client's default groupId.
      * @param assignments Topic-partition pairs to resume.
+     *
+     * @example
+     * ```ts
+     * kafka.resumeConsumer(undefined, [{ topic: 'orders.created', partitions: [0, 1] }]);
+     * ```
      */
     resumeConsumer(groupId: string | undefined, assignments: Array<{
         topic: string;
@@ -817,12 +1719,22 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
     /**
      * Drain in-flight handlers, then disconnect all producers, consumers, and admin.
      * @param drainTimeoutMs Max ms to wait for in-flight handlers (default 30 000).
+     *
+     * @example
+     * ```ts
+     * await kafka.disconnect();
+     * ```
      */
     disconnect(drainTimeoutMs?: number): Promise<void>;
     /**
      * Register SIGTERM / SIGINT signal handlers that drain in-flight messages before
      * disconnecting. Call once after constructing the client in non-NestJS apps.
      * NestJS apps get drain automatically via `onModuleDestroy` → `disconnect()`.
+     *
+     * @example
+     * ```ts
+     * kafka.enableGracefulShutdown(['SIGTERM', 'SIGINT'], 30_000);
+     * ```
      */
     enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
 }
@@ -831,6 +1743,22 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
  * Compatible with NestJS Logger, console, winston, pino, or any custom logger.
  *
  * `debug` is optional — omit it to suppress debug output in production.
+ *
+ * @example
+ * ```ts
+ * // Pass a NestJS logger:
+ * const kafka = new KafkaClient(config, groupId, { logger: this.logger });
+ *
+ * // Or a minimal pino wrapper:
+ * const kafka = new KafkaClient(config, groupId, {
+ *   logger: {
+ *     log:   (msg) => pino.info(msg),
+ *     warn:  (msg, ...a) => pino.warn(msg, ...a),
+ *     error: (msg, ...a) => pino.error(msg, ...a),
+ *     debug: (msg, ...a) => pino.debug(msg, ...a),
+ *   },
+ * });
+ * ```
  */
 interface KafkaLogger {
     log(message: string): void;
@@ -841,6 +1769,15 @@ interface KafkaLogger {
 /**
  * Context passed to `onTtlExpired` when a message is dropped because it
  * exceeded `messageTtlMs` and `dlq` is not enabled.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(config, groupId, {
+ *   onTtlExpired: ({ topic, ageMs, messageTtlMs }) => {
+ *     console.warn(`Message on ${topic} expired: age=${ageMs}ms, ttl=${messageTtlMs}ms`);
+ *   },
+ * });
+ * ```
  */
 interface TtlExpiredContext {
     /** Topic the message was consumed from. */
@@ -855,6 +1792,15 @@ interface TtlExpiredContext {
 /**
  * Context passed to `onMessageLost` when a message is silently dropped
  * (handler threw and `dlq` is not enabled).
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(config, groupId, {
+ *   onMessageLost: ({ topic, error, attempt }) => {
+ *     alerting.fire('kafka.message-lost', { topic, error: error.message, attempt });
+ *   },
+ * });
+ * ```
  */
 interface MessageLostContext {
     /** Topic the message was consumed from. */
@@ -866,7 +1812,20 @@ interface MessageLostContext {
     /** Original Kafka message headers (correlationId, traceparent, etc.). */
     headers: MessageHeaders;
 }
-/** Options for `KafkaClient` constructor. */
+/**
+ * Options for `KafkaClient` constructor.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(kafkaConfig, 'my-service', {
+ *   transactionalId: `my-service-tx-${replicaIndex}`,
+ *   lagThrottle: { maxLag: 10_000, pollIntervalMs: 3_000 },
+ *   clockRecovery: { topics: ['orders.created'] },
+ *   onMessageLost: (ctx) => alerting.fire('kafka.message-lost', ctx),
+ *   instrumentation: [otelInstrumentation()],
+ * });
+ * ```
+ */
 interface KafkaClientOptions {
     /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, or `transaction` for each topic. Useful for development — not recommended in production. */
     autoCreateTopics?: boolean;
@@ -930,8 +1889,59 @@ interface KafkaClientOptions {
         /** Topic names to scan for the highest Lamport clock. */
         topics: string[];
     };
+    /**
+     * Delay `sendMessage` / `sendBatch` / `sendTombstone` when the observed lag of a
+     * consumer group exceeds `maxLag`. Resumes immediately when lag drops below the threshold.
+     *
+     * Lag is polled via `getConsumerLag()` every `pollIntervalMs` in the background;
+     * no admin call is made on each individual send.
+     *
+     * When `maxWaitMs` is exceeded the send is unblocked with a warning — this is
+     * best-effort throttling, not hard back-pressure.
+     *
+     * Requires `connectProducer()` to have been called to start the polling loop.
+     */
+    lagThrottle?: {
+        /** Consumer group whose lag is monitored. Defaults to the client's default group. */
+        groupId?: string;
+        /** Lag threshold (number of messages) above which sends are delayed. */
+        maxLag: number;
+        /** How often to poll `getConsumerLag()`. Default: `5000` ms. */
+        pollIntervalMs?: number;
+        /**
+         * Maximum time (ms) a send will wait while throttled before proceeding anyway.
+         * Default: `30_000` ms.
+         */
+        maxWaitMs?: number;
+    };
+    /**
+     * Custom transport implementation.
+     *
+     * By default `KafkaClient` uses `ConfluentTransport` which wraps
+     * `@confluentinc/kafka-javascript` (librdkafka). Inject a different
+     * `KafkaTransport` to target an alternative broker library, or to supply
+     * a deterministic fake in unit tests without mocking the confluentinc module.
+     *
+     * @example
+     * ```ts
+     * // In tests — no jest.mock() needed
+     * const kafka = new KafkaClient('svc', 'grp', [], {
+     *   transport: new FakeTransport(),
+     * });
+     * ```
+     */
+    transport?: KafkaTransport;
 }
-/** Options for consumer subscribe retry when topic doesn't exist yet. */
+/**
+ * Options for consumer subscribe retry when topic doesn't exist yet.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders.created'], handler, {
+ *   subscribeRetry: { retries: 10, backoffMs: 2_000 },
+ * });
+ * ```
+ */
 interface SubscribeRetryOptions {
     /** Maximum number of subscribe attempts. Default: `5`. */
     retries?: number;
@@ -939,4 +1949,4 @@ interface SubscribeRetryOptions {
     backoffMs?: number;
 }
 
-export { type SubscribeRetryOptions as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, type TTopicMessageMap as F, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, type TopicDescription as J, type KafkaInstrumentation as K, type TopicPartitionInfo as L, type MessageHeaders as M, type TopicsFrom as N, type TransactionContext as O, type TtlExpiredContext as P, buildEnvelopeHeaders as Q, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, decodeHeaders as U, extractEnvelope as V, getEnvelopeContext as W, runWithEnvelopeContext as X, topic as Y, type KafkaClientOptions as a, type ConsumerOptions as b, type TopicDescriptor as c, type KafkaHealthResult as d, type BatchMeta as e, type BatchSendOptions as f, type BeforeConsumeResult as g, type CircuitBreakerOptions as h, type CompressionType as i, type ConsumerGroupSummary as j, type ConsumerHandle as k, type ConsumerInterceptor as l, type DlqReason as m, type DlqReplayOptions as n, type EventEnvelope as o, HEADER_EVENT_ID as p, HEADER_LAMPORT_CLOCK as q, HEADER_SCHEMA_VERSION as r, HEADER_TIMESTAMP as s, HEADER_TRACEPARENT as t, type InferSchema as u, type KafkaLogger as v, type KafkaMetrics as w, type MessageLostContext as x, type SchemaParseContext as y, type SendOptions as z };
+export { type KafkaMetrics as $, type CheckpointRestoreResult as A, type BatchMessageItem as B, type ClientId as C, type CheckpointResult as D, type CircuitBreakerOptions as E, type CompressionType as F, type GroupId as G, type ConsumerGroupSummary as H, type IKafkaClient as I, type ConsumerHandle as J, type KafkaInstrumentation as K, type ConsumerInterceptor as L, type DeduplicationOptions as M, type DlqReason as N, type DlqReplayOptions as O, type EnvelopeHeaderOptions as P, type EventEnvelope as Q, HEADER_CORRELATION_ID as R, type SchemaLike as S, type TopicMapConstraint as T, HEADER_EVENT_ID as U, HEADER_LAMPORT_CLOCK as V, HEADER_SCHEMA_VERSION as W, HEADER_TIMESTAMP as X, HEADER_TRACEPARENT as Y, type InferSchema as Z, type KafkaLogger as _, type IAdmin as a, type MessageHeaders as a0, type MessageLostContext as a1, type ReadSnapshotOptions as a2, type RestoreCheckpointOptions as a3, type RetryOptions as a4, type RoutingOptions as a5, type SchemaParseContext as a6, type SendOptions as a7, type SubscribeRetryOptions as a8, type TTopicMessageMap as a9, type TopicDescription as aa, type TopicPartitionInfo as ab, type TopicsFrom as ac, type TransactionContext as ad, type TransactionalHandlerContext as ae, type TtlExpiredContext as af, type WindowConsumerOptions as ag, type WindowMeta as ah, buildEnvelopeHeaders as ai, decodeHeaders as aj, extractEnvelope as ak, getEnvelopeContext as al, runWithEnvelopeContext as am, topic as an, type IPartitionWatermarks as b, type IGroupTopicOffsets as c, type IPartitionOffset as d, type IGroupDescription as e, type ITopicMetadata as f, type IConsumer as g, type IConsumerCreationOptions as h, type IConsumerRunConfig as i, type ITopicPartitions as j, type ITopicPartitionOffset as k, type ITopicPartition as l, type IMessage as m, type IProducer as n, type IProducerRecord as o, type ITransaction as p, type IProducerCreationOptions as q, type KafkaTransport as r, type KafkaClientOptions as s, type ConsumerOptions as t, type TopicDescriptor as u, type KafkaHealthResult as v, type BatchMeta as w, type BatchSendOptions as x, type BeforeConsumeResult as y, type CheckpointEntry as z };