@drarzter/kafka-client 0.9.2 → 0.9.4

package/dist/client-1irhGEu0.d.mts

@@ -0,0 +1,751 @@
+import { M as MessageHeaders, S as SchemaLike, T as TopicMapConstraint, v as SendOptions, b as TopicDescriptor, 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, C as ClientId, r as KafkaMetrics } from './consumer.types-fFCag3VJ.mjs';
+
+/**
+ * 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.
+     * Default: reads the `x-dlq-original-topic` header from each DLQ message.
+     */
+    targetTopic?: string;
+    /**
+     * Dry-run mode — log what would be replayed without actually sending.
+     * Increments the `replayed` counter so you can see what would happen.
+     */
+    dryRun?: boolean;
+    /**
+     * Optional filter — return `false` to skip a message.
+     * @param headers All headers on the DLQ message (including `x-dlq-*` metadata).
+     * @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;
+}
+/** Result returned by `KafkaClient.checkStatus()`. */
+type KafkaHealthResult = {
+    status: "up";
+    clientId: string;
+    topics: string[];
+} | {
+    status: "down";
+    clientId: string;
+    error: string;
+};
+/** Summary of a consumer group returned by `listConsumerGroups`. */
+interface ConsumerGroupSummary {
+    /** Consumer group ID. */
+    groupId: string;
+    /**
+     * Current broker-reported state of the group.
+     * Common values: `'Empty'`, `'Stable'`, `'PreparingRebalance'`, `'CompletingRebalance'`, `'Dead'`.
+     */
+    state: string;
+}
+/** Partition-level metadata for a topic. */
+interface TopicPartitionInfo {
+    /** Partition index (0-based). */
+    partition: number;
+    /** Node ID of the partition leader broker. */
+    leader: number;
+    /** Node IDs of all replica brokers. */
+    replicas: number[];
+    /** Node IDs of in-sync replicas. */
+    isr: number[];
+}
+/** Topic metadata returned by `describeTopics`. */
+interface TopicDescription {
+    /** Topic name. */
+    name: string;
+    /** Per-partition metadata. */
+    partitions: TopicPartitionInfo[];
+}
+
+/** 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 | null;
+    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;
+}
+
+/** Producer methods of `IKafkaClient`. */
+interface IKafkaProducer<T extends TopicMapConstraint<T>> {
+    /**
+     * @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>;
+    sendMessage<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
+    /**
+     * Send a null-value (tombstone) message to a topic.
+     * Tombstones are used with log-compacted topics to signal that a key's record
+     * should be removed during the next compaction cycle.
+     *
+     * Unlike `sendMessage`, tombstones carry no payload, no envelope headers, and
+     * skip schema validation. Only the partition `key` and optional custom `headers`
+     * are forwarded to Kafka.
+     *
+     * @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>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>, 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>;
+}
+
+/** Consumer methods of `IKafkaClient`. */
+interface IKafkaConsumer<T extends TopicMapConstraint<T>> {
+    /**
+     * @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>;
+    /**
+     * Subscribe using regex topic patterns (or a mix of strings and patterns).
+     * Note: type-safety is reduced to the union of all topic payloads when using regex.
+     * 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>;
+    /**
+     * Subscribe using regex topic patterns (or a mix of strings and patterns).
+     * Note: type-safety is reduced to the union of all topic payloads when using regex.
+     * 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 — whichever fires first. On `handle.stop()`, any remaining buffered
+     * messages are flushed before the consumer disconnects.
+     */
+    startWindowConsumer<K extends keyof T & string>(topic: K, handler: (batch: EventEnvelope<T[K]>[], meta: WindowMeta) => Promise<void>, options: WindowConsumerOptions<T>): Promise<ConsumerHandle>;
+    /**
+     * Subscribe to topics and dispatch each message to a handler based on a Kafka header value.
+     * Messages whose header is absent or doesn't match any route key are forwarded to `fallback`
+     * (or silently skipped when no fallback is set).
+     */
+    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;
+     * on handler success the source offset commit and all staged sends are committed
+     * atomically. Incompatible with `retryTopics: true`.
+     *
+     * @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>;
+    /**
+     * Consume messages as an async iterator. Useful for scripts, migrations, and
+     * one-off processing. Breaking out of the loop stops the consumer automatically.
+     * Does **not** support `retryTopics: true`.
+     *
+     * @example
+     * ```ts
+     * for await (const envelope of kafka.consume('orders')) {
+     *   await process(envelope);
+     * }
+     * ```
+     */
+    consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
+    /**
+     * Pause message delivery for specific topic-partitions. The consumer remains
+     * connected; only polling is suspended. Call `resumeConsumer` to restart.
+     *
+     * @example
+     * ```ts
+     * kafka.pauseConsumer(undefined, [{ topic: 'orders.created', partitions: [0, 1] }]);
+     * ```
+     */
+    pauseConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
+    /**
+     * Resume message delivery for previously paused topic-partitions.
+     *
+     * @example
+     * ```ts
+     * kafka.resumeConsumer(undefined, [{ topic: 'orders.created', partitions: [0, 1] }]);
+     * ```
+     */
+    resumeConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
+}
+
+/** Admin, offset-management, and state methods of `IKafkaClient`. */
+interface IKafkaAdmin<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.
+     *
+     * @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.
+     * Omit `topics` to describe all topics visible to this client.
+     *
+     * @example
+     * ```ts
+     * const [desc] = await kafka.describeTopics(['orders.created']);
+     * console.log(desc.partitions.length);
+     * ```
+     */
+    describeTopics(topics?: string[]): Promise<TopicDescription[]>;
+    /**
+     * Delete records from a topic up to (but not including) the specified offsets.
+     *
+     * @example
+     * ```ts
+     * await kafka.deleteRecords('orders.created', [
+     *   { partition: 0, offset: '1000' },
+     *   { partition: 1, offset: '500'  },
+     * ]);
+     * ```
+     */
+    deleteRecords(topic: string, partitions: Array<{
+        partition: number;
+        offset: string;
+    }>): Promise<void>;
+    /**
+     * Query the consumer group lag per partition.
+     * Lag = (broker high-watermark offset) − (last committed offset).
+     *
+     * @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;
+    }>>;
+    /**
+     * Consume all messages in `{topic}.dlq` and re-publish each to its original topic
+     * (or `options.targetTopic`). The DLQ topic itself is not modified.
+     *
+     * @returns `{ replayed, skipped }` counts.
+     *
+     * @example
+     * ```ts
+     * const { replayed } = await kafka.replayDlq('orders.created');
+     * ```
+     */
+    replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
+        replayed: number;
+        skipped: number;
+    }>;
+    /**
+     * Reset committed offsets to `'earliest'` or `'latest'`.
+     * The consumer group must be inactive — call `stopConsumer(groupId)` first.
+     *
+     * @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>;
+    /**
+     * Seek specific partitions to explicit offsets.
+     * The consumer group must be inactive.
+     *
+     * @example
+     * ```ts
+     * await kafka.seekToOffset('billing-service', [
+     *   { topic: 'orders.created', partition: 0, offset: '1000' },
+     * ]);
+     * ```
+     */
+    seekToOffset(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partition: number;
+        offset: string;
+    }>): Promise<void>;
+    /**
+     * Seek partitions to the offset nearest to a given Unix timestamp (ms).
+     * The consumer group must be inactive.
+     *
+     * @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;
+        partition: number;
+        timestamp: number;
+    }>): Promise<void>;
+    /**
+     * Returns the current circuit breaker state for a topic partition.
+     * Returns `undefined` when `circuitBreaker` is not configured or never tripped.
+     *
+     * @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 high-watermark and return a
+     * `Map<key, EventEnvelope<T>>` with the latest value per key.
+     * Tombstone records remove the key from the map.
+     *
+     * @example
+     * ```ts
+     * const orders = await kafka.readSnapshot('orders.state');
+     * // orders.get('order-123') → latest EventEnvelope for that key
+     * ```
+     */
+    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.
+     * Requires `connectProducer()` to have been called.
+     *
+     * @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.
+     * The consumer group must be stopped before calling this method.
+     *
+     * @example
+     * ```ts
+     * await kafka.stopConsumer('billing-service');
+     * const result = await kafka.restoreFromCheckpoint(undefined, 'checkpoints');
+     * ```
+     */
+    restoreFromCheckpoint(groupId: string | undefined, checkpointTopic: string, options?: RestoreCheckpointOptions): Promise<CheckpointRestoreResult>;
+}
+
+/** Lifecycle and observability methods of `IKafkaClient`. */
+interface IKafkaLifecycle {
+    /**
+     * @example
+     * ```ts
+     * const id = kafka.getClientId(); // e.g. 'my-service'
+     * ```
+     */
+    getClientId(): ClientId;
+    /**
+     * Return a snapshot of internal event counters (retry / DLQ / dedup).
+     * - `getMetrics()` — aggregate across all topics.
+     * - `getMetrics(topic)` — counters for a specific topic only; returns all-zero
+     *   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}`);
+     * ```
+     */
+    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();
+     * kafka.resetMetrics('orders.created');
+     * ```
+     */
+    resetMetrics(topic?: string): void;
+    /**
+     * 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;
+}
+
+/**
+ * Full Kafka client interface — the union of all role-specific sub-interfaces.
+ *
+ * Compose sub-interfaces directly when you need a narrower dependency:
+ * ```ts
+ * function sendOrder(producer: IKafkaProducer<MyTopics>) { ... }
+ * function startWorker(consumer: IKafkaConsumer<MyTopics>) { ... }
+ * ```
+ */
+interface IKafkaClient<T extends TopicMapConstraint<T>> extends IKafkaProducer<T>, IKafkaConsumer<T>, IKafkaAdmin<T>, IKafkaLifecycle {
+}
+
+export type { TopicPartitionInfo as A, CheckpointEntry as C, DlqReplayOptions as D, IKafkaClient as I, KafkaTransport as K, ReadSnapshotOptions as R, TopicDescription as T, IAdmin as a, IPartitionWatermarks as b, IGroupTopicOffsets as c, IPartitionOffset as d, IGroupDescription as e, ITopicMetadata as f, IConsumer as g, IConsumerCreationOptions as h, IConsumerRunConfig as i, ITopicPartitions as j, ITopicPartitionOffset as k, ITopicPartition as l, IMessage as m, IProducer as n, IProducerRecord as o, ITransaction as p, IProducerCreationOptions as q, KafkaHealthResult as r, CheckpointRestoreResult as s, CheckpointResult as t, ConsumerGroupSummary as u, IKafkaAdmin as v, IKafkaConsumer as w, IKafkaLifecycle as x, IKafkaProducer as y, RestoreCheckpointOptions as z };