youeduc-sdk-messaging 0.0.0 → 0.5.0

package/dist/consumer-client.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Kafka client contract used by {@link Consumer} (`consumer.ts`) and its default implementation
+ * over the callback (librdkafka) API of `@confluentinc/kafka-javascript` (`KafkaConsumer`).
+ *
+ * Why the callback API and not `KafkaJS.Consumer.run()`: `run()` owns the poll loop and swallows
+ * fetch errors (it always restarts, so fatal poll errors could never stop the consumer), applies
+ * `seek`/`pause`/`resume` only as deferred "pending operations" at worker barriers (no
+ * synchronous HOLD at a record boundary) and defers `unassign` on revoke until its workers stop.
+ * The callback API gives the primitives of aiokafka's `getmany` model that the Python SDK uses:
+ * `consume(n)` batches, explicit `commit`, `seek`, `pause`/`resume`, `committed` and a
+ * `rebalance_cb` whose `assign`/`unassign` the application calls itself.
+ *
+ * Guarantees of {@link ConfluentConsumerClient} (what makes the at-least-once model hold):
+ *
+ * - **Assignment never changes during a `consume()`**: librdkafka invokes `rebalance_cb` from
+ *   inside `consume()` (worker thread) and the binding only enqueues the event to JS; the adapter
+ *   applies it (listener + `assign`/`unassign`) only after the in-flight `consume()` returned,
+ *   and `poll()` does not start a new `consume()` while a rebalance is being applied. Every batch
+ *   therefore comes from a single assignment, contiguous with the fetch positions.
+ * - **Revoke**: `listener.onPartitionsRevoked` is awaited **before** `unassign()` (the consumer
+ *   drains at the next record boundary and commits there, like aiokafka's listener). A revoke
+ *   served during a `consume()` that already collected records runs right after it returns, so
+ *   the listener may finish before the consumer takes that batch (and before `unassign()`): the
+ *   consumer then drops the revoked partitions' records of that batch itself.
+ * - **Assign**: `listener.onPartitionsAssigned` is awaited **before** `assign()`; a `seekToEnd`
+ *   issued for those partitions during the callback becomes their start offset (`OFFSET_END`),
+ *   so the `latest` reset never races a fetch. Partitions start resumed (aiokafka semantics).
+ * - **Eager protocol only** (`partition.assignment.strategy=roundrobin`, set by the consumer):
+ *   a revoke always covers the whole assignment, so draining every partition is correct.
+ * - **Commits**: `commit()` queues an explicit-offset commit (`commitCb`); the broker result is
+ *   reported asynchronously through `offset_commit_cb` → `hooks.onCommitFailed` (a failed commit
+ *   only means redelivery). librdkafka's `close()` waits for outstanding commits.
+ * - **Close**: during `disconnect()` a revoke from librdkafka's close is applied immediately.
+ */
+import type { ClientConfig } from './config.js';
+import type { RawHeaders } from './headers.js';
+export interface TopicPartition {
+    readonly topic: string;
+    readonly partition: number;
+}
+export interface TopicPartitionOffset extends TopicPartition {
+    readonly offset: number;
+}
+/** A fetched record (key/value bytes untouched, headers as received). */
+export interface ConsumerRecord {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: number;
+    readonly key: Buffer | null;
+    readonly value: Buffer | null;
+    readonly headers: RawHeaders;
+}
+/** Awaited by the client around assignment changes (aiokafka's `ConsumerRebalanceListener`). */
+export interface RebalanceListener {
+    onPartitionsRevoked(partitions: TopicPartition[]): Promise<void>;
+    onPartitionsAssigned(partitions: TopicPartition[]): Promise<void>;
+}
+export interface ConsumerClientHooks {
+    /** A commit accepted by `commit()` failed later at the broker (the record will be redelivered). */
+    onCommitFailed(error: unknown): void;
+}
+/** What the consumer needs from a Kafka client (the confluent adapter or a test fake). */
+export interface KafkaConsumerClient {
+    connect(): Promise<void>;
+    /** After `connect()`. `pattern` is a regex source starting with `^`. */
+    subscribe(pattern: string, listener: RebalanceListener): void;
+    /**
+     * Up to `maxRecords` records, waiting up to `timeoutMs` for the first one. Errors reject.
+     * Records belong to the current assignment and are contiguous with the fetch position: a
+     * client never returns records fetched under a previous assignment of the partition.
+     */
+    poll(options: {
+        maxRecords: number;
+        timeoutMs: number;
+    }): Promise<ConsumerRecord[]>;
+    /** Commits the given next offsets (`offset` = next record to read). */
+    commit(offsets: TopicPartitionOffset[]): Promise<void>;
+    /** Committed offset of the group, or `null` when there is none. */
+    committed(partition: TopicPartition): Promise<number | null>;
+    /** Next fetch of the partition starts at `offset`. Rejects when the partition is not assigned. */
+    seek(partition: TopicPartition, offset: number): Promise<void>;
+    seekToEnd(partitions: TopicPartition[]): Promise<void>;
+    /** Throws when a partition is not assigned. */
+    pause(partitions: TopicPartition[]): void;
+    /** Throws when a partition is not assigned. */
+    resume(partitions: TopicPartition[]): void;
+    assignment(): TopicPartition[];
+    /** Leaves the group and releases the client. */
+    disconnect(): Promise<void>;
+}
+/** Builds a client from the final librdkafka configuration (sync or async). */
+export type ConsumerClientFactory = (config: ClientConfig, hooks: ConsumerClientHooks) => KafkaConsumerClient | Promise<KafkaConsumerClient>;
+/** `topic:partition` (`:` never appears in a Kafka topic name). */
+export declare function partitionKey(tp: TopicPartition): string;
+/** A message as returned by `KafkaConsumer.consume()` of `@confluentinc/kafka-javascript`. */
+export interface RdKafkaMessage {
+    topic: string;
+    partition: number;
+    offset: number;
+    key?: Buffer | string | null | undefined;
+    value: Buffer | null;
+    headers?: Array<Record<string, Buffer | string>> | undefined;
+}
+type ErrorCallback = (error?: unknown) => void;
+/** Subset of the callback-based `KafkaConsumer` used by the adapter. */
+export interface RdKafkaConsumerLike {
+    connect(metadataOptions: null, cb: ErrorCallback): unknown;
+    disconnect(cb: ErrorCallback): unknown;
+    isConnected(): boolean;
+    subscribe(topics: string[]): unknown;
+    consume(count: number, cb: (error: unknown, messages: RdKafkaMessage[]) => void): void;
+    setDefaultConsumeTimeout(timeoutMs: number): void;
+    setDefaultIsTimeoutOnlyForFirstMessage?(value: boolean): void;
+    commitCb(offsets: TopicPartitionOffset[], cb: ErrorCallback): unknown;
+    committed(partitions: TopicPartition[], timeoutMs: number, cb: (error: unknown, offsets: Array<{
+        offset?: number;
+        error?: unknown;
+    }>) => void): unknown;
+    seek(partition: TopicPartitionOffset, timeoutMs: number, cb: ErrorCallback): unknown;
+    pause(partitions: TopicPartition[]): unknown;
+    resume(partitions: TopicPartition[]): unknown;
+    assign(partitions: Array<TopicPartition | TopicPartitionOffset>): unknown;
+    unassign(): unknown;
+    incrementalAssign?(partitions: Array<TopicPartition | TopicPartitionOffset>): unknown;
+    incrementalUnassign?(partitions: TopicPartition[]): unknown;
+    rebalanceProtocol?(): string;
+    assignments(): TopicPartition[];
+}
+/** Creates the raw consumer from the configuration (with the adapter's callbacks added). */
+export type RdKafkaConsumerConstructor = (config: Record<string, unknown>) => RdKafkaConsumerLike;
+/** Adapter of the callback `KafkaConsumer` to {@link KafkaConsumerClient} (guarantees in the header). */
+export declare class ConfluentConsumerClient implements KafkaConsumerClient {
+    #private;
+    constructor(config: ClientConfig, hooks: ConsumerClientHooks, create: RdKafkaConsumerConstructor);
+    connect(): Promise<void>;
+    subscribe(pattern: string, listener: RebalanceListener): void;
+    poll(options: {
+        maxRecords: number;
+        timeoutMs: number;
+    }): Promise<ConsumerRecord[]>;
+    commit(offsets: TopicPartitionOffset[]): Promise<void>;
+    committed(partition: TopicPartition): Promise<number | null>;
+    seek(partition: TopicPartition, offset: number): Promise<void>;
+    seekToEnd(partitions: TopicPartition[]): Promise<void>;
+    pause(partitions: TopicPartition[]): void;
+    resume(partitions: TopicPartition[]): void;
+    assignment(): TopicPartition[];
+    disconnect(): Promise<void>;
+}
+/**
+ * Default factory: the callback `KafkaConsumer` of `@confluentinc/kafka-javascript` wrapped by
+ * {@link ConfluentConsumerClient}. The native module is loaded on first use.
+ */
+export declare const createConfluentConsumer: ConsumerClientFactory;
+export {};

package/dist/consumer-client.js

@@ -0,0 +1,299 @@
+/**
+ * Kafka client contract used by {@link Consumer} (`consumer.ts`) and its default implementation
+ * over the callback (librdkafka) API of `@confluentinc/kafka-javascript` (`KafkaConsumer`).
+ *
+ * Why the callback API and not `KafkaJS.Consumer.run()`: `run()` owns the poll loop and swallows
+ * fetch errors (it always restarts, so fatal poll errors could never stop the consumer), applies
+ * `seek`/`pause`/`resume` only as deferred "pending operations" at worker barriers (no
+ * synchronous HOLD at a record boundary) and defers `unassign` on revoke until its workers stop.
+ * The callback API gives the primitives of aiokafka's `getmany` model that the Python SDK uses:
+ * `consume(n)` batches, explicit `commit`, `seek`, `pause`/`resume`, `committed` and a
+ * `rebalance_cb` whose `assign`/`unassign` the application calls itself.
+ *
+ * Guarantees of {@link ConfluentConsumerClient} (what makes the at-least-once model hold):
+ *
+ * - **Assignment never changes during a `consume()`**: librdkafka invokes `rebalance_cb` from
+ *   inside `consume()` (worker thread) and the binding only enqueues the event to JS; the adapter
+ *   applies it (listener + `assign`/`unassign`) only after the in-flight `consume()` returned,
+ *   and `poll()` does not start a new `consume()` while a rebalance is being applied. Every batch
+ *   therefore comes from a single assignment, contiguous with the fetch positions.
+ * - **Revoke**: `listener.onPartitionsRevoked` is awaited **before** `unassign()` (the consumer
+ *   drains at the next record boundary and commits there, like aiokafka's listener). A revoke
+ *   served during a `consume()` that already collected records runs right after it returns, so
+ *   the listener may finish before the consumer takes that batch (and before `unassign()`): the
+ *   consumer then drops the revoked partitions' records of that batch itself.
+ * - **Assign**: `listener.onPartitionsAssigned` is awaited **before** `assign()`; a `seekToEnd`
+ *   issued for those partitions during the callback becomes their start offset (`OFFSET_END`),
+ *   so the `latest` reset never races a fetch. Partitions start resumed (aiokafka semantics).
+ * - **Eager protocol only** (`partition.assignment.strategy=roundrobin`, set by the consumer):
+ *   a revoke always covers the whole assignment, so draining every partition is correct.
+ * - **Commits**: `commit()` queues an explicit-offset commit (`commitCb`); the broker result is
+ *   reported asynchronously through `offset_commit_cb` → `hooks.onCommitFailed` (a failed commit
+ *   only means redelivery). librdkafka's `close()` waits for outstanding commits.
+ * - **Close**: during `disconnect()` a revoke from librdkafka's close is applied immediately.
+ */
+/** `topic:partition` (`:` never appears in a Kafka topic name). */
+export function partitionKey(tp) {
+    return `${tp.topic}:${tp.partition}`;
+}
+// librdkafka constants (rdkafka.h).
+const ERR__ASSIGN_PARTITIONS = -175;
+const ERR__REVOKE_PARTITIONS = -174;
+const ERR__NO_OFFSET = -168;
+const OFFSET_END = -1;
+const SEEK_TIMEOUT_MS = 5_000;
+const COMMITTED_TIMEOUT_MS = 10_000;
+function plain(tp) {
+    return { topic: tp.topic, partition: tp.partition };
+}
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === 'number' ? code : undefined;
+}
+function toRecord(message) {
+    const key = message.key;
+    const headers = [];
+    for (const header of message.headers ?? []) {
+        for (const [name, value] of Object.entries(header))
+            headers.push([name, value]);
+    }
+    return {
+        topic: message.topic,
+        partition: message.partition,
+        offset: message.offset,
+        key: key === null || key === undefined ? null : typeof key === 'string' ? Buffer.from(key, 'utf8') : key,
+        value: message.value ?? null,
+        headers,
+    };
+}
+/** Adapter of the callback `KafkaConsumer` to {@link KafkaConsumerClient} (guarantees in the header). */
+export class ConfluentConsumerClient {
+    #raw;
+    #hooks;
+    #listener = null;
+    /** Settles when the in-flight `consume()` returned (never rejects). */
+    #consuming = null;
+    /** Serialized rebalance applications. */
+    #rebalanceTail = Promise.resolve();
+    #closing = false;
+    /** Partitions being assigned (inside `onPartitionsAssigned`) and their requested start offsets. */
+    #assigning = null;
+    constructor(config, hooks, create) {
+        this.#hooks = hooks;
+        this.#raw = create({
+            ...config,
+            rebalance_cb: (error, assignment) => this.#onRebalance(error, assignment ?? []),
+            offset_commit_cb: (error) => this.#onOffsetCommit(error),
+        });
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            this.#raw.connect(null, (error) => (error ? reject(error) : resolve()));
+        });
+    }
+    subscribe(pattern, listener) {
+        this.#listener = listener;
+        this.#raw.subscribe([pattern]);
+    }
+    async poll(options) {
+        // Never consume while a rebalance is pending or being applied.
+        for (;;) {
+            const tail = this.#rebalanceTail;
+            await tail;
+            if (tail === this.#rebalanceTail)
+                break;
+        }
+        // A poll abandoned by a cancelled loop must not consume on a closing client.
+        if (this.#closing)
+            return [];
+        let done = () => undefined;
+        this.#consuming = new Promise((resolve) => {
+            done = resolve;
+        });
+        try {
+            const messages = await new Promise((resolve, reject) => {
+                try {
+                    this.#raw.setDefaultConsumeTimeout(options.timeoutMs);
+                    this.#raw.setDefaultIsTimeoutOnlyForFirstMessage?.(true);
+                    this.#raw.consume(options.maxRecords, (error, batch) => error ? reject(error) : resolve(batch ?? []));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            return messages.map(toRecord);
+        }
+        finally {
+            this.#consuming = null;
+            done();
+        }
+    }
+    commit(offsets) {
+        if (offsets.length === 0)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            try {
+                this.#raw.commitCb(offsets.map((o) => ({ topic: o.topic, partition: o.partition, offset: o.offset })), (error) => (error ? reject(error) : resolve()));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    committed(partition) {
+        return new Promise((resolve, reject) => {
+            try {
+                this.#raw.committed([plain(partition)], COMMITTED_TIMEOUT_MS, (error, offsets) => {
+                    const entry = offsets?.[0];
+                    if (error)
+                        reject(error);
+                    else if (entry?.error)
+                        reject(entry.error);
+                    else
+                        resolve(typeof entry?.offset === 'number' && entry.offset >= 0 ? entry.offset : null);
+                });
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    seek(partition, offset) {
+        return new Promise((resolve, reject) => {
+            try {
+                this.#raw.seek({ ...plain(partition), offset }, SEEK_TIMEOUT_MS, (error) => error ? reject(error) : resolve());
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    async seekToEnd(partitions) {
+        const assigning = this.#assigning;
+        const direct = [];
+        for (const tp of partitions) {
+            const key = partitionKey(tp);
+            // Not assigned yet: becomes the start offset passed to assign() (no fetch race).
+            if (assigning?.keys.has(key))
+                assigning.starts.set(key, OFFSET_END);
+            else
+                direct.push(tp);
+        }
+        await Promise.all(direct.map((tp) => this.seek(tp, OFFSET_END)));
+    }
+    pause(partitions) {
+        this.#raw.pause(partitions.map(plain));
+    }
+    resume(partitions) {
+        this.#raw.resume(partitions.map(plain));
+    }
+    assignment() {
+        try {
+            return this.#raw.assignments().map(plain);
+        }
+        catch {
+            return []; // not connected
+        }
+    }
+    async disconnect() {
+        this.#closing = true;
+        await this.#rebalanceTail;
+        if (!this.#raw.isConnected())
+            return;
+        await new Promise((resolve) => {
+            this.#raw.disconnect(() => resolve());
+        });
+    }
+    // ---------------------------------------------------------------------------- rebalance
+    #onRebalance(error, assignment) {
+        const code = errorCode(error);
+        if (code !== ERR__ASSIGN_PARTITIONS && code !== ERR__REVOKE_PARTITIONS)
+            return;
+        const partitions = assignment.map(plain);
+        if (this.#closing) {
+            // librdkafka's close() waits for this (un)assign: apply it now.
+            this.#applyAssignment(code, partitions, undefined);
+            return;
+        }
+        this.#rebalanceTail = this.#rebalanceTail
+            .then(async () => {
+            while (this.#consuming !== null)
+                await this.#consuming;
+            if (this.#closing)
+                this.#applyAssignment(code, partitions, undefined);
+            else
+                await this.#handleRebalance(code, partitions);
+        })
+            .catch(() => undefined);
+    }
+    async #handleRebalance(code, partitions) {
+        const listener = this.#listener;
+        if (code === ERR__REVOKE_PARTITIONS) {
+            try {
+                await listener?.onPartitionsRevoked(partitions);
+            }
+            catch {
+                // The listener is the consumer's own code and never throws; unassign regardless.
+            }
+            finally {
+                this.#applyAssignment(code, partitions, undefined);
+            }
+            return;
+        }
+        const starts = new Map();
+        this.#assigning = { keys: new Set(partitions.map(partitionKey)), starts };
+        try {
+            await listener?.onPartitionsAssigned(partitions);
+        }
+        catch {
+            // Same as above: always complete the assignment.
+        }
+        finally {
+            this.#assigning = null;
+            this.#applyAssignment(code, partitions, starts);
+        }
+    }
+    #applyAssignment(code, partitions, starts) {
+        try {
+            const cooperative = this.#raw.rebalanceProtocol?.() === 'COOPERATIVE';
+            if (code === ERR__ASSIGN_PARTITIONS) {
+                const list = partitions.map((tp) => {
+                    const offset = starts?.get(partitionKey(tp));
+                    return offset === undefined ? plain(tp) : { ...plain(tp), offset };
+                });
+                if (cooperative && this.#raw.incrementalAssign)
+                    this.#raw.incrementalAssign(list);
+                else
+                    this.#raw.assign(list);
+                // Newly assigned partitions start resumed (a pause from a previous ownership must not stick).
+                if (partitions.length > 0)
+                    this.#raw.resume(partitions);
+            }
+            else if (cooperative && this.#raw.incrementalUnassign) {
+                this.#raw.incrementalUnassign(partitions);
+            }
+            else {
+                this.#raw.unassign();
+            }
+        }
+        catch {
+            // Not connected anymore: nothing to (un)assign.
+        }
+    }
+    #onOffsetCommit(error) {
+        if (error === null || error === undefined)
+            return;
+        if (errorCode(error) === ERR__NO_OFFSET)
+            return;
+        this.#hooks.onCommitFailed(error);
+    }
+}
+/**
+ * Default factory: the callback `KafkaConsumer` of `@confluentinc/kafka-javascript` wrapped by
+ * {@link ConfluentConsumerClient}. The native module is loaded on first use.
+ */
+export const createConfluentConsumer = async (config, hooks) => {
+    const kafka = (await import('@confluentinc/kafka-javascript')).default;
+    return new ConfluentConsumerClient(config, hooks, (conf) => new kafka.KafkaConsumer(conf));
+};
+//# sourceMappingURL=consumer-client.js.map

package/dist/consumer-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer-client.js","sourceRoot":"","sources":["../src/consumer-client.ts"],"names":[],"mappings":"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"}

package/dist/consumer.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Kafka consumer with retry through the group's retry topics, DLQ, deduplication and manual
+ * commits (spec §5). Mirrors Python's `consumer.py` step by step.
+ *
+ * Topology (per consumer group):
+ *
+ *     {domain}.events.{version}                       main topic (shared)
+ *     {main}.{group}.retry.{30s,5m,1h,12h}            group retry topics (read back by the group)
+ *     {main}.{group}.dlq                              group DLQ
+ *
+ * With `resourcePrefix` (spec §2.7) the main topic becomes `{prefix}.{domain}.events.{version}` and
+ * the group id `{prefix}.{group}`; retry and DLQ derive from the prefixed main topic and the bare
+ * group. Telemetry, logs and the getters (`group`, `mainTopic`...) show the full names.
+ *
+ * The group subscribes by regex (`naming.retryTopicPattern`) to the main topic and to **every**
+ * retry topic of the group, including delays that left the `RetryPolicy`. A retry is processed
+ * straight from its retry topic when due (`x-retry-due-at`); it is never republished to the main
+ * topic. The next attempt always follows the CURRENT policy, by `x-retry-count`.
+ *
+ * Kafka client: the callback (librdkafka) API of `@confluentinc/kafka-javascript`, wrapped by
+ * `ConfluentConsumerClient` (`consumer-client.ts`, which documents why `KafkaJS.Consumer.run()`
+ * cannot implement §5 and how rebalances are serialized with `consume()`). Mapping to the spec:
+ *
+ * - §5.1 config: `enable.auto.commit=false`, `enable.auto.offset.store=false`,
+ *   `auto.offset.reset=earliest` (always; the user's `latest` is applied on assignment, §5.7),
+ *   `max.poll.interval.ms` (also librdkafka's rebalance timeout), eager `roundrobin` assignor.
+ * - Poll loop = Python's `getmany` loop: `client.poll({maxRecords, timeoutMs})` → batch grouped
+ *   by partition → processed under the batch lock: partitions concurrently
+ *   (`Promise.allSettled`), records of a partition sequentially by offset (§5.4).
+ * - Each record ends in ADVANCE (final outcome, or retry/DLQ send acknowledged) or HOLD. HOLD =
+ *   `pause` + `seek(offset)` + resume timer (§5.4); the rest of the partition's batch is skipped.
+ *   A seek that fails while the partition is still ours is retried before resuming, so a
+ *   partition never resumes from an unknown position.
+ * - End of batch: commit `last contiguous ADVANCE + 1` per partition, only for partitions still
+ *   assigned (`offset_commit_skipped_unassigned`); failure → `offset_commit_failed` (§5.4).
+ * - Not-due retry (§5.5): HOLD for `min(due − now, topic delay)` (10 ms floor), nothing recorded.
+ * - Routing failure (§5.6): retriable → pending route cache (target + headers) + HOLD for
+ *   `routingFailureBackoffMs`, resent without re-running the handler; non-retriable retry send →
+ *   DLQ `routing_failed` with the handler's error; non-retriable DLQ send → one shrunk attempt
+ *   (`x-last-error` ≤ 256 code points, no trace context, nothing injected) → then fatal.
+ * - Dedup (§8): checked before the payload is decoded, marked only after handler success.
+ * - Processing timeout (§7): the handler's `AbortSignal` is aborted at `processingTimeoutMs`,
+ *   then it gets the same time again; still running → `message_handler_abandoned`, detached.
+ * - Lifecycle (§5.7): `stop()` drains at the record boundary, commits and closes; after
+ *   `drainTimeoutMs` the loop is cancelled (every await of the pipeline is raced against the
+ *   cancellation; handlers are aborted) and the unfinished offset is not committed. Revoke asks
+ *   the partitions to stop at the next record boundary and waits for the batch lock (the batch
+ *   commits what it finished), then drops timers/pending routes of the revoked partitions.
+ *   `latest`: main-topic partitions without a committed offset move to the end when assigned (the
+ *   confluent client turns it into the assign start offset); records fetched before that reset
+ *   are dropped. The reset serial is read right after each poll returns (as in Python, after
+ *   `getmany`), so a record fetched after the reset is never dropped (§5.7).
+ *   Fatal poll errors (codes 29, 30, 31, 35, 58, authentication, fatal/stopped client, or any
+ *   non-Kafka error) stop the consumer and `wait()` rethrows; others log `consumer_poll_failed`
+ *   and wait `routingFailureBackoffMs`.
+ *
+ * A handler may run more than once for the same message (crash before commit, failed commit,
+ * rebalance): handlers must be idempotent or use a `DuplicateChecker`. A record may take up to
+ * `2 × processingTimeoutMs`.
+ */
+import type { ClientConfig, KafkaConfig } from './config.js';
+import { type ConsumerClientFactory, type TopicPartition } from './consumer-client.js';
+import { type Logger } from './logger.js';
+import { RetryPolicy } from './retry.js';
+import { type DuplicateChecker, type MessageHandler, type MessageSender, type PayloadValidator, type Telemetry } from './types.js';
+export type AutoOffsetReset = 'earliest' | 'latest';
+/** `event_type` → async handler (plain object or `Map`). */
+export type ConsumerHandlers = Readonly<Record<string, MessageHandler>> | ReadonlyMap<string, MessageHandler>;
+export interface ConsumerOptions {
+    /** Consumer group (kebab-case); also the Kafka `group.id`. */
+    group: string;
+    domain: string;
+    version: string;
+    /** Non-empty map `event_type` → `async` handler. Event types without a handler are skipped. */
+    handlers: ConsumerHandlers;
+    validator: PayloadValidator;
+    /** Producer used to route retries/DLQ (the facade injects the shared one). */
+    sender: MessageSender;
+    /** Default `new RetryPolicy()`. */
+    retryPolicy?: RetryPolicy | undefined;
+    /** Default: no deduplication. */
+    duplicateChecker?: DuplicateChecker | null | undefined;
+    /** Default {@link NoopTelemetry}. */
+    telemetry?: Telemetry | undefined;
+    /** Finite `> 0` and `2 × processingTimeoutMs < maxPollIntervalMs`. Default: no timeout. */
+    processingTimeoutMs?: number | null | undefined;
+    /** Default 100. */
+    maxPollRecords?: number | undefined;
+    /** Default 300 000 (also the rebalance timeout). */
+    maxPollIntervalMs?: number | undefined;
+    /** Default 1000. */
+    pollTimeoutMs?: number | undefined;
+    /** HOLD after a routing failure, and wait after a non-fatal poll error. Default 5000. */
+    routingFailureBackoffMs?: number | undefined;
+    /** Default `earliest`; `latest` applies only to main-topic partitions without a committed offset. */
+    autoOffsetReset?: AutoOffsetReset | undefined;
+    /** Kafka client factory (tests inject fakes). Default {@link createConfluentConsumer}. */
+    consumerFactory?: ConsumerClientFactory | undefined;
+    /** Clock in epoch milliseconds (`x-retry-due-at`, `x-first-failed-at`). Default `Date.now`. */
+    clock?: (() => number) | undefined;
+    /** Default: the SDK default logger. */
+    logger?: Logger | undefined;
+    /**
+     * Resource prefix (spec §2.7): main topic `{prefix}.{domain}.events.{version}`, group id
+     * `{prefix}.{group}`; retry/DLQ derive from the prefixed main topic and the bare group.
+     * Default: none.
+     */
+    resourcePrefix?: string | null | undefined;
+}
+/** Whether a poll error stops the consumer: any non-Kafka error, a fatal code or `isFatal`. */
+export declare function isFatalPollError(error: unknown): boolean;
+/** @internal Test seam (not exported by the package index): mirrors the private state Python tests read. */
+export interface ConsumerInternals {
+    resumeTimers(): ReadonlyMap<string, {
+        readonly delayMs: number;
+        readonly cancelled: boolean;
+    }>;
+    pendingRoutes(): ReadonlyMap<string, unknown>;
+    resumePartition(tp: TopicPartition): Promise<void>;
+    setHandler(eventType: string, handler: unknown): void;
+}
+/** @internal */
+export declare function consumerInternals(consumer: Consumer): ConsumerInternals;
+/**
+ * Consumes the domain's main topic and the group's retry topics.
+ *
+ * Handler contract: resolving = success; rejecting with `PermanentProcessingError` = DLQ; any
+ * other rejection (including the processing timeout) = retry, until `retryPolicy` is exhausted.
+ */
+export declare class Consumer {
+    #private;
+    constructor(config: KafkaConfig, options: ConsumerOptions);
+    get mainTopic(): string;
+    /** Retry topics of the current policy (targets of new retries). */
+    get retryTopics(): string[];
+    /** Subscribed regex (source): main topic + every retry topic of the group. */
+    get subscriptionPattern(): string;
+    get dlqTopic(): string;
+    /** Effective Kafka group id (with the resource prefix, if any). */
+    get group(): string;
+    get resourcePrefix(): string | null;
+    get running(): boolean;
+    /** Final librdkafka configuration handed to the client factory. */
+    consumerConfig(): ClientConfig;
+    start(): Promise<void>;
+    /**
+     * Graceful shutdown: the in-flight record of each partition finishes and the progress is
+     * committed. After `drainTimeoutMs` the loop is cancelled (the in-flight handler is aborted)
+     * and the unfinished offset is not committed: it will be redelivered. Idempotent.
+     */
+    stop(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    /** Waits for the loop to end; rethrows the fatal error that stopped it, if any. */
+    wait(): Promise<void>;
+}