@drarzter/kafka-client 0.8.0 → 0.9.3

package/dist/core.d.ts

@@ -1,5 +1,128 @@
-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_.js';
-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_.js';
+import { q as KafkaLogger, K as KafkaInstrumentation, s as MessageLostContext, F as TtlExpiredContext, T as TopicMapConstraint, C as ClientId, G as GroupId, b as TopicDescriptor, v as SendOptions, M as MessageHeaders, B as BatchMessageItem, d as BatchSendOptions, z as TransactionContext, k as EventEnvelope, a as ConsumerOptions, h as ConsumerHandle, c as BatchMeta, J as WindowMeta, W as WindowConsumerOptions, t as RoutingOptions, A as TransactionalHandlerContext, r as KafkaMetrics } from './consumer.types-fFCag3VJ.js';
+export { e as BeforeConsumeResult, f as CircuitBreakerOptions, g as CompressionType, i as ConsumerInterceptor, D as DeduplicationOptions, j as DlqReason, E as EnvelopeHeaderOptions, H as HEADER_CORRELATION_ID, l as HEADER_EVENT_ID, m as HEADER_LAMPORT_CLOCK, n as HEADER_SCHEMA_VERSION, o as HEADER_TIMESTAMP, p as HEADER_TRACEPARENT, I as InferSchema, R as RetryOptions, S as SchemaLike, u as SchemaParseContext, w as SubscribeRetryOptions, x as TTopicMessageMap, y as TopicsFrom, L as buildEnvelopeHeaders, N as decodeHeaders, O as extractEnvelope, P as getEnvelopeContext, Q as runWithEnvelopeContext, U as topic } from './consumer.types-fFCag3VJ.js';
+import { K as KafkaTransport, I as IKafkaClient, D as DlqReplayOptions, R as ReadSnapshotOptions, t as CheckpointResult, z as RestoreCheckpointOptions, s as CheckpointRestoreResult, r as KafkaHealthResult, u as ConsumerGroupSummary, T as TopicDescription } from './client-CBBUDDtu.js';
+export { C as CheckpointEntry, v as IKafkaAdmin, w as IKafkaConsumer, x as IKafkaLifecycle, y as IKafkaProducer, A as TopicPartitionInfo } from './client-CBBUDDtu.js';
+
+/**
+ * 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;
+    /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
+    strictSchemas?: boolean;
+    /** Custom logger. Defaults to console with `[KafkaClient:<clientId>]` prefix. */
+    logger?: KafkaLogger;
+    /** Number of partitions for auto-created topics. Default: `1`. */
+    numPartitions?: number;
+    /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */
+    instrumentation?: KafkaInstrumentation[];
+    /**
+     * Override the transactional producer ID used by `transaction()`.
+     * Defaults to `${clientId}-tx`.
+     *
+     * The transactional ID must be **unique per producer instance** across the
+     * entire Kafka cluster. Two `KafkaClient` instances with the same ID will
+     * cause Kafka to fence one of the producers — the fenced producer will fail
+     * on the next `transaction()` call. Set a distinct value per replica when
+     * running multiple instances of the same service.
+     */
+    transactionalId?: string;
+    /**
+     * Called when a message is dropped without being sent to a DLQ.
+     * Fires when the handler throws after all retries, or schema validation fails — and `dlq` is not enabled.
+     * Use this to alert, log to external systems, or trigger fallback logic.
+     */
+    onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
+    /**
+     * Called when a message is dropped due to TTL expiration (`messageTtlMs`).
+     * Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
+     * When `dlq: true`, expired messages go to the DLQ and this callback is NOT called.
+     *
+     * **Client-wide fallback**: if `ConsumerOptions.onTtlExpired` is set on the consumer,
+     * it takes precedence over this client-level callback.
+     */
+    onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
+    /**
+     * Called whenever a consumer group rebalance occurs.
+     * - `'assign'` — new partitions were granted to this instance.
+     * - `'revoke'` — partitions were taken away (e.g. another consumer joined).
+     *
+     * Applied to every consumer created by this client. If you need per-consumer
+     * rebalance handling, use separate `KafkaClient` instances.
+     */
+    onRebalance?: (type: "assign" | "revoke", partitions: Array<{
+        topic: string;
+        partition: number;
+    }>) => void;
+    /**
+     * Recover the Lamport clock from the last message in the given topics on `connectProducer()`.
+     *
+     * On startup the producer creates a short-lived consumer, seeks each partition to its
+     * last message (`highWatermark − 1`), reads the `x-lamport-clock` header, then
+     * initialises `_lamportClock` to the maximum value found. This guarantees monotonic
+     * clock values across restarts without an external store.
+     *
+     * Topics that do not exist or are empty are silently skipped.
+     */
+    clockRecovery?: {
+        /** 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;
+}
 
 /**
  * Type-safe Kafka client.
@@ -9,54 +132,8 @@ export { g as BeforeConsumeResult, h as CheckpointEntry, k as CircuitBreakerOpti
  * @typeParam T - Topic-to-message type mapping for compile-time safety.
  */
 declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClient<T> {
-    private readonly kafka;
-    private readonly producer;
-    private txProducer;
-    private txProducerInitPromise;
-    /** Maps transactionalId → Producer for each active retry level consumer. */
-    private readonly retryTxProducers;
-    private readonly consumers;
-    private readonly logger;
-    private readonly autoCreateTopicsEnabled;
-    private readonly strictSchemasEnabled;
-    private readonly numPartitions;
-    private readonly ensuredTopics;
-    /** Pending topic-creation promises keyed by topic name. Prevents duplicate createTopics calls. */
-    private readonly ensureTopicPromises;
-    private readonly defaultGroupId;
-    private readonly schemaRegistry;
-    private readonly runningConsumers;
-    private readonly consumerCreationOptions;
-    /** Maps each main consumer groupId to its companion retry level groupIds. */
-    private readonly companionGroupIds;
-    private readonly instrumentation;
-    private readonly onMessageLost;
-    private readonly onTtlExpired;
-    private readonly onRebalance;
-    /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
-    private readonly txId;
-    /** Monotonically increasing Lamport clock stamped on every outgoing message. */
-    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;
-    private readonly adminOps;
-    private readonly metrics;
-    private readonly inFlight;
     readonly clientId: ClientId;
-    private readonly _producerOpsDeps;
-    private readonly _consumerOpsDeps;
-    private readonly _retryTopicDeps;
-    /** DLQ header keys added by the pipeline — stripped before re-publishing. */
-    private static readonly DLQ_HEADER_KEYS;
+    private readonly ctx;
     /**
      * Create a new KafkaClient.
      * @param clientId Unique client identifier (used in Kafka metadata and logs).
@@ -73,208 +150,35 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
      * ```
      */
     constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
-    /**
-     * Send a single typed message. Accepts a topic key or a `TopicDescriptor`.
-     *
-     * @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 });
-     * ```
-     */
+    /** @inheritDoc */
     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>;
-    /**
-     * Send a null-value (tombstone) message. Used with log-compacted topics to signal
-     * that a key's record should be removed during the next compaction cycle.
-     *
-     * Tombstones skip envelope headers, schema validation, and Lamport clock stamping.
-     * Both `beforeSend` and `afterSend` instrumentation hooks are still called so tracing works correctly.
-     *
-     * @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');
-     * ```
-     */
+    /** @inheritDoc */
     sendTombstone(topic: string, key: string, headers?: MessageHeaders): Promise<void>;
-    /**
-     * Send multiple typed messages in a single Kafka produce request. Accepts a topic key or a `TopicDescriptor`.
-     *
-     * Each item in `messages` can carry its own `key`, `headers`, `correlationId`, and `schemaVersion`.
-     * The `key` is used for partition routing — messages with the same key always land on the same partition.
-     *
-     * @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' },
-     * ]);
-     * ```
-     */
+    /** @inheritDoc */
     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.
-     * @example
-     * ```ts
-     * await kafka.transaction(async (tx) => {
-     *   await tx.send('orders.created', { orderId: '123' });
-     *   await tx.send('inventory.reserved', { itemId: 'a', qty: 1 });
-     * });
-     * ```
-     */
+    /** @inheritDoc */
     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.
-     */
+    /** @inheritDoc */
     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.
-     *
-     * For each topic, fetches partition high-watermarks via admin, creates a
-     * short-lived consumer, seeks every non-empty partition to its last offset
-     * (`highWatermark − 1`), reads one message per partition, and extracts the
-     * maximum `x-lamport-clock` header value. On completion `_lamportClock` is
-     * set to that maximum so the next `++_lamportClock` yields a strictly greater
-     * value than any previously sent clock.
-     *
-     * Topics that are empty or missing are silently skipped.
-     */
-    private recoverLamportClock;
-    /**
-     * @internal Not part of `IKafkaClient` — use `disconnect()` for full teardown.
-     */
+    /** @internal */
     disconnectProducer(): Promise<void>;
-    /**
-     * Subscribe to one or more topics and start consuming messages one at a time.
-     *
-     * Each message is delivered to `handleMessage` as a fully-decoded `EventEnvelope`.
-     * The call blocks until the consumer is connected and the subscription is set up,
-     * then returns a `ConsumerHandle` with a `stop()` method for clean shutdown.
-     *
-     * @param topics Array of topic keys, `TopicDescriptor` objects, or `RegExp` patterns.
-     *   Regex patterns cannot be combined with `retryTopics: true`.
-     * @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();
-     * ```
-     */
+    /** @inheritDoc */
     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>;
-    /**
-     * Subscribe to one or more topics and consume messages in batches.
-     *
-     * `handleBatch` receives an array of decoded `EventEnvelope` objects together with
-     * batch metadata (topic, partition, high-watermark offset). Prefer this over
-     * `startConsumer` when throughput matters more than per-message latency.
-     *
-     * Set `autoCommit: false` in options when the handler calls `resolveOffset()` or
-     * `commitOffsetsIfNecessary()` directly, to avoid offset conflicts.
-     *
-     * @param topics Array of topic keys, `TopicDescriptor` objects, or `RegExp` patterns.
-     * @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 });
-     * ```
-     */
+    /** @inheritDoc */
     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>;
-    /**
-     * Consume messages from a topic as an AsyncIterableIterator.
-     * Use with `for await` — breaking out of the loop automatically stops the consumer.
-     *
-     * @example
-     * for await (const envelope of kafka.consume('my.topic')) {
-     *   console.log(envelope.data);
-     * }
-     */
+    /** @inheritDoc */
     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 });
-     * ```
-     */
+    /** @inheritDoc */
     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),
-     *   },
-     * });
-     * ```
-     */
+    /** @inheritDoc */
     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 });
-     * });
-     * ```
-     */
+    /** @inheritDoc */
     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.
-     *
-     * If `groupId` is unspecified, all active consumers are stopped.
-     * 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
-     * ```
-     */
+    /** @inheritDoc */
     stopConsumer(groupId?: string): Promise<void>;
     /** @inheritDoc */
     pauseConsumer(groupId: string | undefined, assignments: Array<{
@@ -286,60 +190,16 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
         topic: string;
         partitions: number[];
     }>): void;
-    /** Pause all assigned partitions of a topic for a consumer group (used for queue backpressure). */
-    private pauseTopicAllPartitions;
-    /** Resume all assigned partitions of a topic for a consumer group (used for queue backpressure). */
-    private resumeTopicAllPartitions;
-    /**
-     * Re-publish messages from a dead letter queue back to the original topic.
-     *
-     * Messages are consumed from `<topic>.dlq` and re-published to `<topic>`.
-     * The original topic is determined by the `x-dlq-original-topic` header.
-     * The `x-dlq-*` headers are stripped before re-publishing.
-     *
-     * @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');
-     * ```
-     */
+    /** @inheritDoc */
     replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
         replayed: number;
         skipped: number;
     }>;
-    /**
-     * 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;
-     * ```
-     */
+    /** @inheritDoc */
     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`);
-     * ```
-     */
+    /** @inheritDoc */
     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');
-     * ```
-     */
+    /** @inheritDoc */
     restoreFromCheckpoint(groupId: string | undefined, checkpointTopic: string, options?: RestoreCheckpointOptions): Promise<CheckpointRestoreResult>;
     /** @inheritDoc */
     resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
@@ -355,43 +215,7 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
         partition: number;
         timestamp: number;
     }>): Promise<void>;
-    /**
-     * Returns the current circuit breaker state for a specific topic partition.
-     * Returns `undefined` when no circuit state exists — either `circuitBreaker` is not
-     * configured for the group, or the circuit has never been tripped.
-     *
-     * @param topic Topic name.
-     * @param partition Partition index.
-     * @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";
-        failures: number;
-        windowSize: number;
-    } | undefined;
-    /**
-     * Query consumer group lag per partition.
-     * Lag = broker high-watermark − last committed offset.
-     * A committed offset of -1 (nothing committed yet) counts as full lag.
-     *
-     * Returns an empty array when the consumer group has never committed any
-     * offsets (freshly created group, `autoCommit: false` with no manual commits,
-     * 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);
-     * ```
-     */
+    /** @inheritDoc */
     getConsumerLag(groupId?: string): Promise<Array<{
         topic: string;
         partition: number;
@@ -408,75 +232,23 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
         partition: number;
         offset: string;
     }>): Promise<void>;
-    /**
-     * 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
-     * (or since the last `resetMetrics()` call).
-     *
-     * @param topic Topic name to scope the snapshot to. When omitted, counters are
-     *   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');
-     * ```
-     */
+    /** @inheritDoc */
+    getCircuitState(topic: string, partition: number, groupId?: string): {
+        status: "closed" | "open" | "half-open";
+        failures: number;
+        windowSize: number;
+    } | undefined;
+    /** @inheritDoc */
     getMetrics(topic?: string): Readonly<KafkaMetrics>;
     /** @inheritDoc */
     resetMetrics(topic?: string): void;
+    getClientId(): ClientId;
     /** @inheritDoc */
     disconnect(drainTimeoutMs?: number): Promise<void>;
-    /**
-     * NestJS lifecycle hook — called automatically when the host module is torn down.
-     * Drains in-flight handlers and disconnects all producers, consumers, and admin.
-     * `KafkaModule` relies on this method; no separate destroy provider is needed.
-     */
+    /** NestJS lifecycle hook — called automatically on module teardown. */
     onModuleDestroy(): Promise<void>;
     /** @inheritDoc */
     enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
-    private preparePayload;
-    /**
-     * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
-     * The handler itself is not cancelled — the warning is diagnostic only.
-     */
-    private wrapWithTimeoutWarning;
-    /**
-     * Create and connect a transactional producer for EOS retry routing.
-     * Each retry level consumer gets its own producer with a unique `transactionalId`
-     * so Kafka can fence stale producers on restart without affecting other levels.
-     */
-    private createRetryTxProducer;
-    /**
-     * Ensure that a topic exists by creating it if it doesn't already exist.
-     * If `autoCreateTopics` is disabled, returns immediately.
-     * Concurrent calls for the same topic are deduplicated.
-     */
-    private ensureTopic;
-    /** Shared consumer setup: groupId check, schema map, connect, subscribe. */
-    private setupConsumer;
-    /** Create or retrieve the deduplication context for a consumer group. */
-    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. */
-    private launchRetryChain;
-    /** Build MessageHandlerDeps with circuit breaker callbacks bound to the given groupId. */
-    private messageDepsFor;
-    /** Build the deps object passed to retry topic consumers. */
-    private buildRetryTopicDeps;
 }
 
 /**
@@ -539,4 +311,4 @@ declare class KafkaRetryExhaustedError extends KafkaProcessingError {
     });
 }
 
-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 };
+export { BatchMessageItem, BatchMeta, BatchSendOptions, CheckpointRestoreResult, CheckpointResult, ClientId, ConsumerGroupSummary, ConsumerHandle, ConsumerOptions, DlqReplayOptions, EventEnvelope, GroupId, IKafkaClient, KafkaClient, type KafkaClientOptions, KafkaHealthResult, KafkaInstrumentation, KafkaLogger, KafkaMetrics, KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError, MessageHeaders, MessageLostContext, ReadSnapshotOptions, RestoreCheckpointOptions, RoutingOptions, SendOptions, TopicDescription, TopicDescriptor, TopicMapConstraint, TransactionContext, TransactionalHandlerContext, TtlExpiredContext, WindowConsumerOptions, WindowMeta };