@drarzter/kafka-client 0.7.4 → 0.8.0

package/dist/core.d.mts

@@ -1,5 +1,5 @@
-import { T as TopicMapConstraint, I as IKafkaClient, C as ClientId, G as GroupId, a as KafkaClientOptions, c as TopicDescriptor, z as SendOptions, M as MessageHeaders, B as BatchMessageItem, f as BatchSendOptions, O as TransactionContext, o as EventEnvelope, b as ConsumerOptions, k as ConsumerHandle, e as BatchMeta, n as DlqReplayOptions, d as KafkaHealthResult, j as ConsumerGroupSummary, J as TopicDescription, w as KafkaMetrics } from './types-Db7qSbZP.mjs';
-export { g as BeforeConsumeResult, h as CircuitBreakerOptions, i as CompressionType, l as ConsumerInterceptor, D as DeduplicationOptions, m as DlqReason, E as EnvelopeHeaderOptions, H as HEADER_CORRELATION_ID, p as HEADER_EVENT_ID, q as HEADER_LAMPORT_CLOCK, r as HEADER_SCHEMA_VERSION, s as HEADER_TIMESTAMP, t as HEADER_TRACEPARENT, u as InferSchema, K as KafkaInstrumentation, v as KafkaLogger, x as MessageLostContext, R as RetryOptions, S as SchemaLike, y as SchemaParseContext, A as SubscribeRetryOptions, F as TTopicMessageMap, L as TopicPartitionInfo, N as TopicsFrom, P as TtlExpiredContext, Q as buildEnvelopeHeaders, U as decodeHeaders, V as extractEnvelope, W as getEnvelopeContext, X as runWithEnvelopeContext, Y as topic } from './types-Db7qSbZP.mjs';
+import { T as TopicMapConstraint, I as IKafkaClient, C as ClientId, G as GroupId, a as KafkaClientOptions, c as TopicDescriptor, O as SendOptions, M as MessageHeaders, B as BatchMessageItem, f as BatchSendOptions, X as TransactionContext, r as EventEnvelope, b as ConsumerOptions, n as ConsumerHandle, e as BatchMeta, $ as WindowMeta, _ as WindowConsumerOptions, L as RoutingOptions, Y as TransactionalHandlerContext, q as DlqReplayOptions, R as ReadSnapshotOptions, j as CheckpointResult, F as RestoreCheckpointOptions, i as CheckpointRestoreResult, d as KafkaHealthResult, m as ConsumerGroupSummary, U as TopicDescription, z as KafkaMetrics } from './types-CNfeoF3_.mjs';
+export { g as BeforeConsumeResult, h as CheckpointEntry, k as CircuitBreakerOptions, l as CompressionType, o as ConsumerInterceptor, D as DeduplicationOptions, p as DlqReason, E as EnvelopeHeaderOptions, H as HEADER_CORRELATION_ID, s as HEADER_EVENT_ID, t as HEADER_LAMPORT_CLOCK, u as HEADER_SCHEMA_VERSION, v as HEADER_TIMESTAMP, w as HEADER_TRACEPARENT, x as InferSchema, K as KafkaInstrumentation, y as KafkaLogger, A as MessageLostContext, J as RetryOptions, S as SchemaLike, N as SchemaParseContext, P as SubscribeRetryOptions, Q as TTopicMessageMap, V as TopicPartitionInfo, W as TopicsFrom, Z as TtlExpiredContext, a0 as buildEnvelopeHeaders, a1 as decodeHeaders, a2 as extractEnvelope, a3 as getEnvelopeContext, a4 as runWithEnvelopeContext, a5 as topic } from './types-CNfeoF3_.mjs';
 
 /**
  * Type-safe Kafka client.
@@ -39,6 +39,12 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private _lamportClock;
     /** Topics to scan for the highest Lamport clock value on `connectProducer()`. */
     private readonly clockRecoveryTopics;
+    /** Lag-throttle configuration — set when `lagThrottle` is configured. */
+    private readonly lagThrottleOpts;
+    /** `true` while the observed consumer group lag exceeds `lagThrottle.maxLag`. */
+    private _lagThrottled;
+    /** Background polling timer for lag throttle. */
+    private _lagThrottleTimer;
     /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
     private readonly dedupStates;
     private readonly circuitBreaker;
@@ -51,6 +57,21 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly _retryTopicDeps;
     /** DLQ header keys added by the pipeline — stripped before re-publishing. */
     private static readonly DLQ_HEADER_KEYS;
+    /**
+     * Create a new KafkaClient.
+     * @param clientId Unique client identifier (used in Kafka metadata and logs).
+     * @param groupId Default consumer group ID for this client.
+     * @param brokers Array of broker addresses, e.g. `['localhost:9092']`.
+     * @param options Optional client-wide configuration.
+     * @example
+     * ```ts
+     * const kafka = new KafkaClient('my-service', 'my-service-group', ['localhost:9092'], {
+     *   lagThrottle: { maxLag: 10_000 },
+     *   onMessageLost: (ctx) => logger.error('Message lost', ctx),
+     * });
+     * await kafka.connectProducer();
+     * ```
+     */
     constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
     /**
      * Send a single typed message. Accepts a topic key or a `TopicDescriptor`.
@@ -58,6 +79,10 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @param topic Topic key from the `TopicMessageMap` or a `TopicDescriptor` object.
      * @param message Message payload — validated against the topic schema when one is registered.
      * @param options Optional per-send settings: `key`, `headers`, `correlationId`, `compression`, etc.
+     * @example
+     * ```ts
+     * await kafka.sendMessage('orders.created', { orderId: '123', amount: 99 });
+     * ```
      */
     sendMessage<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
@@ -71,6 +96,10 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @param topic Topic name.
      * @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>;
     /**
@@ -82,16 +111,35 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @param topic Topic key from the `TopicMessageMap` or a `TopicDescriptor` object.
      * @param messages Array of messages to send.
      * @param options Optional batch-level settings: `compression` codec.
+     * @example
+     * ```ts
+     * await kafka.sendBatch('orders.created', [
+     *   { value: { orderId: '1', amount: 10 }, key: 'order-1' },
+     * ]);
+     * ```
      */
     sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>, options?: BatchSendOptions): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
-    /** Execute multiple sends atomically. Commits on success, aborts on error. */
+    /**
+     * Execute multiple sends atomically. Commits on success, aborts on error.
+     * @example
+     * ```ts
+     * await kafka.transaction(async (tx) => {
+     *   await tx.send('orders.created', { orderId: '123' });
+     *   await tx.send('inventory.reserved', { itemId: 'a', qty: 1 });
+     * });
+     * ```
+     */
     transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
     /**
      * Connect the idempotent producer. Called automatically by `KafkaModule.register()`.
      * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
      */
     connectProducer(): Promise<void>;
+    /** Start the background lag-polling loop for producer throttling. */
+    private startLagThrottlePoller;
+    /** Wait until lag drops below the threshold (or maxWaitMs is exceeded). */
+    private waitIfThrottled;
     /**
      * Recover the Lamport clock from the last message across the given topics.
      *
@@ -121,6 +169,13 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @param handleMessage Async handler called for every message. Throw to trigger retries.
      * @param options Consumer configuration — `groupId`, `retry`, `dlq`, `circuitBreaker`, etc.
      * @returns A handle with `{ groupId, stop() }` for managing the consumer lifecycle.
+     * @example
+     * ```ts
+     * const handle = await kafka.startConsumer(['orders.created'], async (envelope) => {
+     *   await processOrder(envelope.payload);
+     * }, { retry: { maxRetries: 3 }, dlq: true });
+     * 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>;
@@ -138,6 +193,13 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @param handleBatch Async handler called with each batch of decoded messages.
      * @param options Consumer configuration — `groupId`, `retry`, `dlq`, `autoCommit`, etc.
      * @returns A handle with `{ groupId, stop() }` for managing the consumer lifecycle.
+     * @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>;
@@ -151,6 +213,55 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * }
      */
     consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
+    /**
+     * Accumulate messages into a window and flush the handler when either
+     * `maxMessages` is reached or `maxMs` has elapsed — whichever fires first.
+     * Remaining messages are flushed before the consumer disconnects on `stop()`.
+     * @example
+     * ```ts
+     * await kafka.startWindowConsumer('events', async (batch, meta) => {
+     *   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 topics and dispatch each message to a handler based on the value
+     * of a specific Kafka header. A thin, zero-overhead wrapper over `startConsumer`.
+     *
+     * All `ConsumerOptions` (retry, DLQ, deduplication, circuit breaker, etc.) apply
+     * uniformly across every route.
+     * @example
+     * ```ts
+     * await kafka.startRoutedConsumer(['domain.events'], {
+     *   header: 'x-event-type',
+     *   routes: {
+     *     'order.created': async (e) => handleOrderCreated(e.payload),
+     *   },
+     * });
+     * ```
+     */
+    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 handled inside a dedicated Kafka transaction.
+     * The handler receives a `TransactionalHandlerContext` whose `send` / `sendBatch`
+     * methods stage outgoing messages inside that transaction. On handler success the
+     * source offset commit and all staged sends are committed atomically. On handler
+     * failure the transaction is aborted and the source message is redelivered — no
+     * partial writes become visible to downstream consumers.
+     *
+     * Incompatible with `retryTopics: true` — throws at startup if set.
+     * @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 all consumers or a specific group.
      *
@@ -158,24 +269,19 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * If `groupId` is specified, only the consumer with that group ID is stopped.
      *
      * @throws {Error} if the consumer fails to disconnect.
+     * @example
+     * ```ts
+     * await kafka.stopConsumer('billing-service'); // stop one group
+     * await kafka.stopConsumer();                  // stop all
+     * ```
      */
     stopConsumer(groupId?: string): Promise<void>;
-    /**
-     * Temporarily stop delivering messages from specific partitions without disconnecting the consumer.
-     *
-     * @param groupId Consumer group to pause. Defaults to the client's default groupId.
-     * @param assignments Topic-partition pairs to pause.
-     */
+    /** @inheritDoc */
     pauseConsumer(groupId: string | undefined, assignments: Array<{
         topic: string;
         partitions: number[];
     }>): void;
-    /**
-     * Resume message delivery for previously paused topic-partitions.
-     *
-     * @param {string|undefined} groupId Consumer group to resume. Defaults to the client's default groupId.
-     * @param {Array<{ topic: string; partitions: number[] }>} assignments Topic-partition pairs to resume.
-     */
+    /** @inheritDoc */
     resumeConsumer(groupId: string | undefined, assignments: Array<{
         topic: string;
         partitions: number[];
@@ -194,30 +300,56 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @param topic - The topic to replay from `<topic>.dlq`
      * @param options - Options for replay
      * @returns { replayed: number; skipped: number } - counts of re-published vs skipped messages
+     * @example
+     * ```ts
+     * const { replayed, skipped } = await kafka.replayDlq('orders.created');
+     * ```
      */
     replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
         replayed: number;
         skipped: number;
     }>;
-    resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
     /**
-     * Seek specific topic-partition pairs to explicit offsets for a stopped consumer group.
-     * Throws if the group is still running — call `stopConsumer(groupId)` first.
-     * Assignments are grouped by topic and committed via `admin.setOffsets`.
+     * Read a compacted topic from the beginning to its current high-watermark.
+     * Returns a `Map<key, EventEnvelope>` with the latest value per key.
+     * Tombstone messages (null value) remove the key from the map.
+     * @example
+     * ```ts
+     * const snapshot = await kafka.readSnapshot('users.state');
+     * const user = snapshot.get('user-42')?.payload;
+     * ```
      */
+    readSnapshot<K extends keyof T & string>(topic: K, options?: ReadSnapshotOptions): Promise<Map<string, EventEnvelope<T[K]>>>;
+    private applySnapshotMessage;
+    /**
+     * Snapshot the current committed offsets of a consumer group into a Kafka topic.
+     * Each call appends a new record — the checkpoint topic is an append-only audit log.
+     * @example
+     * ```ts
+     * const result = await kafka.checkpointOffsets(undefined, 'checkpoints');
+     * console.log(`Saved ${result.partitionCount} offsets`);
+     * ```
+     */
+    checkpointOffsets(groupId: string | undefined, checkpointTopic: string): Promise<CheckpointResult>;
+    /**
+     * Restore a consumer group's committed offsets from the nearest checkpoint in `checkpointTopic`.
+     * Requires the consumer group to be stopped.
+     * @example
+     * ```ts
+     * await kafka.stopConsumer();
+     * await kafka.restoreFromCheckpoint(undefined, 'checkpoints');
+     * ```
+     */
+    restoreFromCheckpoint(groupId: string | undefined, checkpointTopic: string, options?: RestoreCheckpointOptions): Promise<CheckpointRestoreResult>;
+    /** @inheritDoc */
+    resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
+    /** @inheritDoc */
     seekToOffset(groupId: string | undefined, assignments: Array<{
         topic: string;
         partition: number;
         offset: string;
     }>): Promise<void>;
-    /**
-     * Seek specific topic-partition pairs to the offset nearest to a given timestamp
-     * (in milliseconds) for a stopped consumer group.
-     * Throws if the group is still running — call `stopConsumer(groupId)` first.
-     * Assignments are grouped by topic and committed via `admin.setOffsets`.
-     * If no offset exists at the requested timestamp (e.g. empty partition or
-     * future timestamp), the partition falls back to `-1` (end of topic — new messages only).
-     */
+    /** @inheritDoc */
     seekToTimestamp(groupId: string | undefined, assignments: Array<{
         topic: string;
         partition: number;
@@ -233,6 +365,11 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * @param groupId Consumer group. Defaults to the client's default groupId.
      *
      * @returns `{ status, failures, windowSize }` snapshot for a given partition or `undefined` if no state exists.
+     * @example
+     * ```ts
+     * const state = kafka.getCircuitState('orders.created', 0);
+     * if (state?.status === 'open') console.warn('Circuit open!');
+     * ```
      */
     getCircuitState(topic: string, partition: number, groupId?: string): {
         status: "closed" | "open" | "half-open";
@@ -249,33 +386,35 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * or group not yet assigned). This is a Kafka protocol limitation:
      * `fetchOffsets` only returns data for topic-partitions that have at least one
      * committed offset. Use `checkStatus()` to verify broker connectivity in that case.
+     * @example
+     * ```ts
+     * const lag = await kafka.getConsumerLag();
+     * const total = lag.reduce((sum, p) => sum + p.lag, 0);
+     * ```
      */
     getConsumerLag(groupId?: string): Promise<Array<{
         topic: string;
         partition: number;
         lag: number;
     }>>;
-    /** Check broker connectivity. Never throws — returns a discriminated union. */
+    /** @inheritDoc */
     checkStatus(): Promise<KafkaHealthResult>;
-    /**
-     * List all consumer groups known to the broker.
-     * Useful for monitoring which groups are active and their current state.
-     */
+    /** @inheritDoc */
     listConsumerGroups(): Promise<ConsumerGroupSummary[]>;
-    /**
-     * Describe topics — returns partition layout, leader, replicas, and ISR.
-     * @param topics Topic names to describe. Omit to describe all topics.
-     */
+    /** @inheritDoc */
     describeTopics(topics?: string[]): Promise<TopicDescription[]>;
-    /**
-     * Delete records from a topic up to (but not including) the given offsets.
-     * All messages with offsets **before** the given offset are deleted.
-     */
+    /** @inheritDoc */
     deleteRecords(topic: string, partitions: Array<{
         partition: number;
         offset: string;
     }>): Promise<void>;
-    /** Return the client ID provided during `KafkaClient` construction. */
+    /**
+     * Return the client ID provided during `KafkaClient` construction.
+     * @example
+     * ```ts
+     * const id = kafka.getClientId(); // e.g. 'my-service'
+     * ```
+     */
     getClientId(): ClientId;
     /**
      * Return a snapshot of internal event counters accumulated since client creation
@@ -285,15 +424,16 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      *   aggregated across all topics. If the topic has no recorded events yet, returns
      *   a zero-valued snapshot.
      * @returns Read-only `KafkaMetrics` snapshot: `processedCount`, `retryCount`, `dlqCount`, `dedupCount`.
+     * @example
+     * ```ts
+     * const { processedCount, dlqCount } = kafka.getMetrics();
+     * const topicMetrics = kafka.getMetrics('orders.created');
+     * ```
      */
     getMetrics(topic?: string): Readonly<KafkaMetrics>;
-    /**
-     * Reset internal event counters to zero.
-     *
-     * @param topic Topic name to reset. When omitted, all topics are reset.
-     */
+    /** @inheritDoc */
     resetMetrics(topic?: string): void;
-    /** Gracefully disconnect producer, all consumers, and admin. */
+    /** @inheritDoc */
     disconnect(drainTimeoutMs?: number): Promise<void>;
     /**
      * NestJS lifecycle hook — called automatically when the host module is torn down.
@@ -301,11 +441,7 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * `KafkaModule` relies on this method; no separate destroy provider is needed.
      */
     onModuleDestroy(): Promise<void>;
-    /**
-     * Register SIGTERM / SIGINT handlers that drain in-flight messages before
-     * disconnecting. Call this once after constructing the client in non-NestJS apps.
-     * NestJS apps get drain for free via `onModuleDestroy` → `disconnect()`.
-     */
+    /** @inheritDoc */
     enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
     private preparePayload;
     /**
@@ -331,6 +467,8 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private resolveDeduplicationContext;
     /** Guard checks shared by startConsumer and startBatchConsumer. */
     private validateTopicConsumerOpts;
+    /** Ensure all required topics exist for a consumer: base, DLQ, and dedup topics. */
+    private ensureConsumerTopics;
     /** Create EOS transactional producer context for atomic main → retry.1 routing. */
     private makeEosMainContext;
     /** Start companion retry-level consumers and register them under the main groupId. */
@@ -341,7 +479,20 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private buildRetryTopicDeps;
 }
 
-/** Error thrown when a consumer message handler fails. */
+/**
+ * Error thrown when a consumer message handler fails.
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders'], async (envelope) => {
+ *   try { await process(envelope); }
+ *   catch (err) {
+ *     if (err instanceof KafkaProcessingError) {
+ *       console.error(err.topic, err.originalMessage);
+ *     }
+ *   }
+ * });
+ * ```
+ */
 declare class KafkaProcessingError extends Error {
     readonly topic: string;
     readonly originalMessage: unknown;
@@ -350,7 +501,18 @@ declare class KafkaProcessingError extends Error {
         cause?: Error;
     });
 }
-/** Error thrown when schema validation fails on send or consume. */
+/**
+ * Error thrown when schema validation fails on send or consume.
+ * @example
+ * ```ts
+ * try { await kafka.sendMessage('orders.created', invalidPayload); }
+ * catch (err) {
+ *   if (err instanceof KafkaValidationError) {
+ *     console.error('Validation failed for topic:', err.topic);
+ *   }
+ * }
+ * ```
+ */
 declare class KafkaValidationError extends Error {
     readonly topic: string;
     readonly originalMessage: unknown;
@@ -359,7 +521,17 @@ declare class KafkaValidationError extends Error {
         cause?: Error;
     });
 }
-/** Error thrown when all retry attempts are exhausted for a message. */
+/**
+ * Error thrown when all retry attempts are exhausted for a message.
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(config, groupId, { onMessageLost: (ctx) => {
+ *   if (ctx.error instanceof KafkaRetryExhaustedError) {
+ *     console.error(`Exhausted after ${ctx.error.attempts} attempts on ${ctx.error.topic}`);
+ *   }
+ * }});
+ * ```
+ */
 declare class KafkaRetryExhaustedError extends KafkaProcessingError {
     readonly attempts: number;
     constructor(topic: string, originalMessage: unknown, attempts: number, options?: {
@@ -367,4 +539,4 @@ declare class KafkaRetryExhaustedError extends KafkaProcessingError {
     });
 }
 
-export { BatchMessageItem, BatchMeta, BatchSendOptions, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, KafkaClientOptions, KafkaHealthResult, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext };
+export { BatchMessageItem, BatchMeta, BatchSendOptions, CheckpointRestoreResult, CheckpointResult, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, KafkaClientOptions, KafkaHealthResult, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, ReadSnapshotOptions, RestoreCheckpointOptions, RoutingOptions, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext, TransactionalHandlerContext, WindowConsumerOptions, WindowMeta };