@drarzter/kafka-client 0.9.2 → 0.9.4

package/dist/consumer.types-fFCag3VJ.d.mts

@@ -0,0 +1,958 @@
+/**
+ * Mapping of topic names to their message types.
+ * Define this interface to get type-safe publish/subscribe across your app.
+ *
+ * @example
+ * ```ts
+ * // with explicit extends (IDE hints for values)
+ * interface MyTopics extends TTopicMessageMap {
+ *   "orders.created": { orderId: string; amount: number };
+ *   "users.updated": { userId: string; name: string };
+ * }
+ *
+ * // or plain interface / type — works the same
+ * interface MyTopics {
+ *   "orders.created": { orderId: string; amount: number };
+ * }
+ * ```
+ */
+type TTopicMessageMap = {
+    [topic: string]: Record<string, any>;
+};
+/**
+ * Generic constraint for topic-message maps.
+ * Works with both `type` aliases and `interface` declarations.
+ */
+type TopicMapConstraint<T> = {
+    [K in keyof T]: Record<string, any>;
+};
+type ClientId = string;
+type GroupId = string;
+type MessageHeaders = Record<string, string>;
+/**
+ * Message compression codec.
+ * Maps directly to the underlying librdkafka codec values.
+ * - `'none'` — no compression (default)
+ * - `'gzip'` — widely supported, moderate compression ratio
+ * - `'snappy'` — fast, moderate compression ratio
+ * - `'lz4'` — fastest, slightly lower ratio
+ * - `'zstd'` — best ratio, slightly slower
+ */
+type CompressionType = "none" | "gzip" | "snappy" | "lz4" | "zstd";
+/**
+ * Logger interface for KafkaClient.
+ * Compatible with NestJS Logger, console, winston, pino, or any custom logger.
+ *
+ * `debug` is optional — omit it to suppress debug output in production.
+ *
+ * @example
+ * ```ts
+ * // Pass a NestJS logger:
+ * const kafka = new KafkaClient(config, groupId, { logger: this.logger });
+ *
+ * // Or a minimal pino wrapper:
+ * const kafka = new KafkaClient(config, groupId, {
+ *   logger: {
+ *     log:   (msg) => pino.info(msg),
+ *     warn:  (msg, ...a) => pino.warn(msg, ...a),
+ *     error: (msg, ...a) => pino.error(msg, ...a),
+ *     debug: (msg, ...a) => pino.debug(msg, ...a),
+ *   },
+ * });
+ * ```
+ */
+interface KafkaLogger {
+    log(message: string): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    debug?(message: string, ...args: any[]): void;
+}
+/**
+ * Snapshot of internal event counters accumulated since client creation
+ * (or since the last `resetMetrics()` call).
+ */
+interface KafkaMetrics {
+    /** Total messages successfully processed by the consumer handler. */
+    processedCount: number;
+    /** Total retry attempts routed — covers both in-process retries and retry-topic hops. */
+    retryCount: number;
+    /** Total messages sent to a DLQ topic. */
+    dlqCount: number;
+    /** Total duplicate messages detected by the Lamport clock. */
+    dedupCount: number;
+}
+
+/**
+ * Options for sending a single message.
+ *
+ * @example
+ * ```ts
+ * await kafka.sendMessage('orders.created', { orderId: '123', amount: 99 }, {
+ *   key: 'order-123',
+ *   headers: { 'x-source': 'checkout-service' },
+ *   compression: 'snappy',
+ * });
+ * ```
+ */
+interface SendOptions {
+    /** Partition key for message routing. */
+    key?: string;
+    /** Custom headers attached to the message (merged with auto-generated envelope headers). */
+    headers?: MessageHeaders;
+    /** Override the auto-propagated correlation ID (default: inherited from ALS context or new UUID). */
+    correlationId?: string;
+    /** Schema version for the payload. Default: `1`. */
+    schemaVersion?: number;
+    /** Override the auto-generated event ID (UUID v4). */
+    eventId?: string;
+    /**
+     * Compression codec for this message.
+     * Applied at the producer record level — all messages in a single `send` call share the same codec.
+     * Default: `'none'`.
+     */
+    compression?: CompressionType;
+}
+/**
+ * Shape of each item in a `sendBatch` call.
+ *
+ * @example
+ * ```ts
+ * await kafka.sendBatch('orders.created', [
+ *   { value: { orderId: '1', amount: 10 }, key: 'order-1' },
+ *   { value: { orderId: '2', amount: 20 }, key: 'order-2', headers: { 'x-priority': 'high' } },
+ * ]);
+ * ```
+ */
+interface BatchMessageItem<V> {
+    value: V;
+    /**
+     * Kafka partition key for this message.
+     * Kafka hashes the key to deterministically route the message to a partition.
+     * Messages with the same key always land on the same partition — use this to
+     * guarantee ordering per entity (e.g. `userId`, `orderId`).
+     */
+    key?: string;
+    headers?: MessageHeaders;
+    correlationId?: string;
+    schemaVersion?: number;
+    eventId?: string;
+}
+/**
+ * Options for a `sendBatch` call (applies to all messages in the batch).
+ *
+ * @example
+ * ```ts
+ * await kafka.sendBatch('metrics', messages, { compression: 'zstd' });
+ * ```
+ */
+interface BatchSendOptions {
+    /**
+     * Compression codec for this batch.
+     * Applied at the producer record level — all messages in the batch share the same codec.
+     * Default: `'none'`.
+     */
+    compression?: CompressionType;
+}
+
+/**
+ * Context passed as the second argument to `SchemaLike.parse()`.
+ * Enables schema-registry adapters, version-aware migration, and
+ * header-driven parsing without coupling validators to Kafka internals.
+ *
+ * All fields are optional-friendly — validators that don't need the context
+ * can simply ignore the second argument.
+ */
+interface SchemaParseContext {
+    /** Topic the message was produced to / consumed from. */
+    topic: string;
+    /** Decoded message headers (envelope headers included). */
+    headers: MessageHeaders;
+    /** Value of the `x-schema-version` header, defaults to `1`. */
+    version: number;
+}
+/**
+ * Any validation library with a `.parse()` method.
+ * Works with Zod, Valibot, ArkType, or any custom validator.
+ *
+ * The optional `ctx` argument carries topic/header/version metadata so
+ * validators can perform schema-registry lookups or version-aware migrations.
+ * Existing validators that only use the first argument continue to work
+ * unchanged — the second argument is silently ignored.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * const schema: SchemaLike<{ id: string }> = z.object({ id: z.string() });
+ *
+ * // Context-aware validator:
+ * const schema: SchemaLike<MyType> = {
+ *   parse(data, ctx) {
+ *     const version = ctx?.version ?? 1;
+ *     return version >= 2 ? migrateV1toV2(data) : validateV1(data);
+ *   }
+ * };
+ * ```
+ */
+interface SchemaLike<T = any> {
+    parse(data: unknown, ctx?: SchemaParseContext): T | Promise<T>;
+}
+/** Infer the output type from a SchemaLike. */
+type InferSchema<S extends SchemaLike> = S extends SchemaLike<infer T> ? T : never;
+/**
+ * A typed topic descriptor that pairs a topic name with its message type.
+ * Created via the `topic()` factory function.
+ *
+ * @typeParam N - The literal topic name string.
+ * @typeParam M - The message payload type for this topic.
+ */
+interface TopicDescriptor<N extends string = string, M extends Record<string, any> = Record<string, any>> {
+    readonly __topic: N;
+    /** @internal Phantom type — never has a real value at runtime. */
+    readonly __type: M;
+    /** Runtime schema validator. Present only when created via `topic().schema()`. */
+    readonly __schema?: SchemaLike<M>;
+}
+/**
+ * Define a typed topic descriptor.
+ *
+ * @example
+ * ```ts
+ * // Without schema — explicit type via .type<T>():
+ * const OrderCreated = topic('order.created').type<{ orderId: string; amount: number }>();
+ *
+ * // With schema — type inferred from schema:
+ * const OrderCreated = topic('order.created').schema(z.object({
+ *   orderId: z.string(),
+ *   amount: z.number(),
+ * }));
+ *
+ * // Use with KafkaClient:
+ * await kafka.sendMessage(OrderCreated, { orderId: '123', amount: 100 });
+ *
+ * // Use with @SubscribeTo:
+ * @SubscribeTo(OrderCreated)
+ * async handleOrder(msg) { ... }
+ * ```
+ */
+declare function topic<N extends string>(name: N): {
+    /** Provide an explicit message type without a runtime schema. */
+    type: <M extends Record<string, any>>() => TopicDescriptor<N, M>;
+    schema: <S extends SchemaLike<Record<string, any>>>(schema: S) => TopicDescriptor<N, InferSchema<S>>;
+};
+/**
+ * Build a topic-message map type from a union of TopicDescriptors.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created').type<{ orderId: string }>();
+ * const OrderCompleted = topic('order.completed').type<{ completedAt: string }>();
+ *
+ * type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
+ * // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
+ * ```
+ */
+type TopicsFrom<D extends TopicDescriptor<any, any>> = {
+    [K in D as K["__topic"]]: K["__type"];
+};
+
+declare const HEADER_EVENT_ID = "x-event-id";
+declare const HEADER_CORRELATION_ID = "x-correlation-id";
+declare const HEADER_TIMESTAMP = "x-timestamp";
+declare const HEADER_SCHEMA_VERSION = "x-schema-version";
+declare const HEADER_TRACEPARENT = "traceparent";
+/** Monotonically increasing logical clock stamped by the producer for deduplication. */
+declare const HEADER_LAMPORT_CLOCK = "x-lamport-clock";
+/**
+ * Typed wrapper combining a parsed message payload with Kafka metadata
+ * and envelope headers.
+ *
+ * On **send**, the library auto-generates envelope headers
+ * (`x-event-id`, `x-correlation-id`, `x-timestamp`, `x-schema-version`).
+ *
+ * On **consume**, the library extracts those headers and assembles
+ * an `EventEnvelope` that is passed to the handler.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders'], async (envelope: EventEnvelope<Order>) => {
+ *   console.log(envelope.payload.orderId);  // typed payload
+ *   console.log(envelope.correlationId);    // auto-propagated
+ *   console.log(envelope.eventId);          // unique message ID
+ * });
+ * ```
+ */
+interface EventEnvelope<T> {
+    /** Deserialized + validated message body. */
+    payload: T;
+    /** Topic the message was produced to / consumed from. */
+    topic: string;
+    /** Kafka partition (consume-side only, `-1` on send). */
+    partition: number;
+    /** Kafka offset (consume-side only, empty string on send). */
+    offset: string;
+    /** ISO-8601 timestamp set by the producer. */
+    timestamp: string;
+    /** Unique ID for this event (UUID v4). */
+    eventId: string;
+    /** Correlation ID — auto-propagated via AsyncLocalStorage. */
+    correlationId: string;
+    /** Schema version of the payload. */
+    schemaVersion: number;
+    /** W3C Trace Context `traceparent` header (set by OTel instrumentation). */
+    traceparent?: string;
+    /** All decoded Kafka headers for extensibility. */
+    headers: MessageHeaders;
+}
+interface EnvelopeCtx {
+    correlationId: string;
+    traceparent?: string;
+}
+/**
+ * Read the current envelope context (correlationId / traceparent) from ALS.
+ * Returns `undefined` outside of a Kafka consumer handler.
+ * @example
+ * ```ts
+ * const ctx = getEnvelopeContext();
+ * if (ctx) console.log('correlationId:', ctx.correlationId);
+ * ```
+ */
+declare function getEnvelopeContext(): EnvelopeCtx | undefined;
+/**
+ * Execute `fn` inside an envelope context so nested sends inherit correlationId.
+ * Automatically called by the consumer pipeline — use this in tests or manual flows.
+ * @example
+ * ```ts
+ * await runWithEnvelopeContext({ correlationId: 'abc-123' }, async () => {
+ *   await kafka.sendMessage('orders.created', payload); // inherits correlationId
+ * });
+ * ```
+ */
+declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
+/** Options accepted by `buildEnvelopeHeaders`. */
+interface EnvelopeHeaderOptions {
+    correlationId?: string;
+    schemaVersion?: number;
+    eventId?: string;
+    headers?: MessageHeaders;
+}
+/**
+ * Generate envelope headers for the send path.
+ *
+ * Priority for `correlationId`:
+ *   explicit option → ALS context → new UUID.
+ */
+declare function buildEnvelopeHeaders(options?: EnvelopeHeaderOptions): MessageHeaders;
+/**
+ * Decode kafkajs headers (`Record<string, Buffer | string | undefined>`)
+ * into plain `Record<string, string>`.
+ */
+declare function decodeHeaders(raw: Record<string, Buffer | string | (Buffer | string)[] | undefined> | undefined): MessageHeaders;
+/**
+ * Build an `EventEnvelope` from a consumed kafkajs message.
+ * Tolerates missing envelope headers — generates defaults so messages
+ * from non-envelope producers still work.
+ */
+declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic: string, partition: number, offset: string): EventEnvelope<T>;
+
+/**
+ * Metadata exposed to batch consumer handlers.
+ *
+ * @example
+ * ```ts
+ * await kafka.startBatchConsumer(['events'], async (envelopes, meta) => {
+ *   console.log(`Partition ${meta.partition}, HWM ${meta.highWatermark}`);
+ *   await db.insertMany(envelopes.map(e => e.payload));
+ *   meta.resolveOffset(envelopes.at(-1)!.offset);
+ *   await meta.commitOffsetsIfNecessary();
+ * }, { autoCommit: false });
+ * ```
+ */
+interface BatchMeta {
+    /** Partition number for this batch. */
+    partition: number;
+    /**
+     * Highest offset available on the broker for this partition.
+     * `null` when the message is being replayed via a retry topic consumer —
+     * in that path the broker high-watermark is not accessible without an admin
+     * call. Do not use this for lag calculation in the retry path.
+     */
+    highWatermark: string | null;
+    /** Send a heartbeat to the broker to prevent session timeout. */
+    heartbeat(): Promise<void>;
+    /** Mark an offset as processed (for manual offset management). */
+    resolveOffset(offset: string): void;
+    /** Commit offsets if the auto-commit threshold has been reached. */
+    commitOffsetsIfNecessary(): Promise<void>;
+}
+/**
+ * Configuration for consumer retry behavior.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders'], handler, {
+ *   retry: { maxRetries: 5, backoffMs: 500, maxBackoffMs: 10_000 },
+ * });
+ * ```
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts before giving up. */
+    maxRetries: number;
+    /** Base delay for exponential backoff in ms. Default: `1000`. */
+    backoffMs?: number;
+    /** Maximum delay cap for exponential backoff in ms. Default: `30000`. */
+    maxBackoffMs?: number;
+}
+/**
+ * Options for Lamport Clock-based message deduplication.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['payments'], handler, {
+ *   deduplication: { strategy: 'dlq' },
+ *   dlq: true,
+ * });
+ * ```
+ *
+ * The producer stamps every outgoing message with a monotonically increasing
+ * `x-lamport-clock` header. The consumer tracks the last processed value per
+ * `topic:partition` and skips any message whose clock is not strictly greater
+ * than that value.
+ *
+ * Messages that arrive without the `x-lamport-clock` header are passed through
+ * unchanged (backwards-compatible with producers that don't use this library).
+ *
+ * **In-session limitation**: deduplication state lives in memory and is reset
+ * whenever the process restarts or `stopConsumer` is called. After a restart,
+ * previously processed messages with `clock ≤ N` will be re-processed until
+ * their offsets catch up to the high-watermark again. The same applies after a
+ * rebalance: the instance that receives the partition begins with empty state.
+ * This is a fundamental limitation of the in-memory Lamport clock approach —
+ * it provides deduplication only within a single process session.
+ */
+interface DeduplicationOptions {
+    /**
+     * What to do with detected duplicate messages:
+     * - `'drop'`  — silently discard. No routing, no callback. **(default)**
+     * - `'dlq'`   — forward to `<topic>.dlq` with reason metadata headers.
+     *               Requires `dlq: true` on the consumer options.
+     * - `'topic'` — forward to `<topic>.duplicates` (or `duplicatesTopic` if set).
+     */
+    strategy?: "dlq" | "topic" | "drop";
+    /**
+     * Custom destination topic for `strategy: 'topic'`.
+     * Defaults to `<consumedTopic>.duplicates`.
+     */
+    duplicatesTopic?: string;
+}
+/**
+ * Options for the per-partition circuit breaker.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['payments'], handler, {
+ *   circuitBreaker: {
+ *     threshold: 5,
+ *     recoveryMs: 30_000,
+ *     windowSize: 20,
+ *     halfOpenSuccesses: 2,
+ *   },
+ *   dlq: true,
+ * });
+ * ```
+ *
+ * The circuit breaker tracks recent message outcomes in a **sliding window** and
+ * opens (pauses the partition) when too many failures accumulate:
+ *
+ * - **CLOSED** — normal operation. Each DLQ route or successful delivery is recorded
+ *   in the window. When `failuresInWindow >= threshold` the circuit opens.
+ * - **OPEN** — the partition is paused. After `recoveryMs` the circuit moves to HALF-OPEN.
+ * - **HALF-OPEN** — the partition is resumed. If the next `halfOpenSuccesses` messages
+ *   succeed the circuit closes; a new failure immediately re-opens it.
+ */
+interface CircuitBreakerOptions {
+    /**
+     * Number of failures within the sliding window required to open the circuit.
+     * A failure is any message that ends up in the DLQ.
+     * Default: `5`.
+     */
+    threshold?: number;
+    /**
+     * Time (ms) to keep the circuit OPEN before attempting recovery (HALF_OPEN).
+     * Default: `30_000` (30 s).
+     */
+    recoveryMs?: number;
+    /**
+     * Number of outcomes (successes + failures) to keep in the sliding window.
+     * Default: `threshold * 2` (minimum `10`).
+     */
+    windowSize?: number;
+    /**
+     * Number of consecutive successes in HALF-OPEN state required to close the
+     * circuit. Default: `1`.
+     */
+    halfOpenSuccesses?: number;
+}
+/**
+ * Interceptor hooks for consumer message processing.
+ * All methods are optional — implement only what you need.
+ *
+ * Interceptors are per-consumer. For client-wide hooks (e.g. OTel),
+ * use `KafkaInstrumentation` instead.
+ *
+ * @example
+ * ```ts
+ * const logger: ConsumerInterceptor = {
+ *   async before(envelope) { console.log('Processing', envelope.eventId); },
+ *   async after(envelope)  { console.log('Done',       envelope.eventId); },
+ *   async onError(envelope, err) { console.error('Failed', err.message); },
+ * };
+ *
+ * await kafka.startConsumer(['orders'], handler, { interceptors: [logger] });
+ * ```
+ */
+interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+    /** Called before the message handler. */
+    before?(envelope: EventEnvelope<T[keyof T]>): Promise<void> | void;
+    /** Called after the message handler succeeds. */
+    after?(envelope: EventEnvelope<T[keyof T]>): Promise<void> | void;
+    /** Called when the message handler throws. */
+    onError?(envelope: EventEnvelope<T[keyof T]>, error: Error): Promise<void> | void;
+}
+/**
+ * Return value of `KafkaInstrumentation.beforeConsume`.
+ *
+ * - `() => void` — legacy form: a cleanup function called after the handler.
+ * - Object form:
+ *   - `cleanup?()` — called after the handler (same as the legacy function form).
+ *   - `wrap?(fn)` — wraps the handler execution; call `fn()` inside the desired
+ *     async context (e.g. `context.with(spanCtx, fn)` for OpenTelemetry). Multiple
+ *     wraps from different instrumentations are composed in declaration order,
+ *     so the first instrumentation's wrap is the outermost.
+ *
+ * @example
+ * ```ts
+ * // Cleanup-only (legacy form):
+ * beforeConsume(envelope) {
+ *   const timer = startTimer();
+ *   return () => timer.end();
+ * }
+ *
+ * // Wrap form — run handler inside an OTel span context:
+ * beforeConsume(envelope) {
+ *   const ctx = propagator.extract(ROOT_CONTEXT, envelope.headers);
+ *   const span = tracer.startSpan(envelope.topic, {}, ctx);
+ *   return {
+ *     wrap: (fn) => context.with(trace.setSpan(ctx, span), fn),
+ *     cleanup: () => span.end(),
+ *   };
+ * }
+ * ```
+ */
+type BeforeConsumeResult = (() => void) | {
+    cleanup?(): void;
+    wrap?(fn: () => Promise<void>): Promise<void>;
+};
+/**
+ * Reason a message was sent to the DLQ.
+ * - `'handler-error'` — the consumer handler threw after all retry attempts.
+ * - `'validation-error'` — schema validation failed before the handler ran.
+ * - `'lamport-clock-duplicate'` — message was identified as a Lamport-clock duplicate
+ *   and `deduplication.strategy` is `'dlq'`.
+ * - `'ttl-expired'` — message age exceeded `messageTtlMs` before the handler ran.
+ */
+type DlqReason = "handler-error" | "validation-error" | "lamport-clock-duplicate" | "ttl-expired";
+/**
+ * Client-wide instrumentation hooks for both send and consume paths.
+ * Use this for cross-cutting concerns like tracing and metrics.
+ *
+ * @see `otelInstrumentation()` from `@drarzter/kafka-client/otel`
+ *
+ * @example
+ * ```ts
+ * const tracing: KafkaInstrumentation = {
+ *   beforeSend(topic, headers) {
+ *     headers['traceparent'] = getCurrentTraceId();
+ *   },
+ *   beforeConsume(envelope) {
+ *     const span = tracer.startSpan(envelope.topic);
+ *     return { cleanup: () => span.end() };
+ *   },
+ *   onDlq(envelope, reason) {
+ *     metrics.increment('kafka.dlq', { topic: envelope.topic, reason });
+ *   },
+ * };
+ *
+ * const kafka = new KafkaClient(config, groupId, { instrumentation: [tracing] });
+ * ```
+ */
+interface KafkaInstrumentation {
+    /** Called before sending — can mutate `headers` (e.g. inject `traceparent`). */
+    beforeSend?(topic: string, headers: MessageHeaders): void;
+    /** Called after a successful send. */
+    afterSend?(topic: string): void;
+    /**
+     * Called before the consumer handler.
+     * Return a cleanup function (legacy) or a `BeforeConsumeResult` object with
+     * optional `cleanup` and `wrap`. Use `wrap` to run the handler inside a
+     * specific async context (e.g. an active OpenTelemetry span).
+     */
+    beforeConsume?(envelope: EventEnvelope<any>): BeforeConsumeResult | void;
+    /** Called when the consumer handler throws. */
+    onConsumeError?(envelope: EventEnvelope<any>, error: Error): void;
+    /**
+     * Called when a message is queued for retry.
+     * Fires for both in-process retries (before the backoff sleep) and
+     * retry-topic routing (EOS and non-EOS paths).
+     */
+    onRetry?(envelope: EventEnvelope<any>, attempt: number, maxRetries: number): void;
+    /** Called when a message is routed to a DLQ topic. */
+    onDlq?(envelope: EventEnvelope<any>, reason: DlqReason): void;
+    /**
+     * Called when a duplicate message is detected via the Lamport clock.
+     * Fires regardless of the configured `deduplication.strategy`.
+     */
+    onDuplicate?(envelope: EventEnvelope<any>, strategy: "drop" | "dlq" | "topic"): void;
+    /**
+     * Called after the consumer handler successfully processes a message.
+     * Use this as a success counter for error-rate calculations.
+     * Fires for both single-message and batch consumers (once per envelope).
+     */
+    onMessage?(envelope: EventEnvelope<any>): void;
+    /** Called when a partition circuit opens (consumer paused due to DLQ failures). */
+    onCircuitOpen?(topic: string, partition: number): void;
+    /** Called when the circuit moves to half-open (partition resumed for a probe). */
+    onCircuitHalfOpen?(topic: string, partition: number): void;
+    /** Called when the circuit closes (normal operation restored). */
+    onCircuitClose?(topic: string, partition: number): void;
+}
+/**
+ * Context passed to `onTtlExpired` when a message is dropped because it
+ * exceeded `messageTtlMs` and `dlq` is not enabled.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(config, groupId, {
+ *   onTtlExpired: ({ topic, ageMs, messageTtlMs }) => {
+ *     console.warn(`Message on ${topic} expired: age=${ageMs}ms, ttl=${messageTtlMs}ms`);
+ *   },
+ * });
+ * ```
+ */
+interface TtlExpiredContext {
+    /** Topic the message was consumed from. */
+    topic: string;
+    /** Actual age of the message in ms at the time it was dropped. */
+    ageMs: number;
+    /** The configured TTL threshold (`messageTtlMs`). */
+    messageTtlMs: number;
+    /** Original Kafka message headers (correlationId, traceparent, etc.). */
+    headers: MessageHeaders;
+}
+/**
+ * Context passed to `onMessageLost` when a message is silently dropped
+ * (handler threw and `dlq` is not enabled).
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(config, groupId, {
+ *   onMessageLost: ({ topic, error, attempt }) => {
+ *     alerting.fire('kafka.message-lost', { topic, error: error.message, attempt });
+ *   },
+ * });
+ * ```
+ */
+interface MessageLostContext {
+    /** Topic the message was consumed from. */
+    topic: string;
+    /** Error that caused the message to be dropped. */
+    error: Error;
+    /** Number of processing attempts (0 = validation failure, before handler ran). */
+    attempt: number;
+    /** Original Kafka message headers (correlationId, traceparent, etc.). */
+    headers: MessageHeaders;
+}
+/**
+ * Options for consumer subscribe retry when topic doesn't exist yet.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders.created'], handler, {
+ *   subscribeRetry: { retries: 10, backoffMs: 2_000 },
+ * });
+ * ```
+ */
+interface SubscribeRetryOptions {
+    /** Maximum number of subscribe attempts. Default: `5`. */
+    retries?: number;
+    /** Delay between retries in ms. Default: `5000`. */
+    backoffMs?: number;
+}
+/**
+ * Options for configuring a Kafka consumer.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders.created'], handler, {
+ *   groupId: 'billing-service',
+ *   retry: { maxRetries: 5, backoffMs: 1000 },
+ *   dlq: true,
+ *   deduplication: { strategy: 'drop' },
+ *   circuitBreaker: { threshold: 3, recoveryMs: 60_000 },
+ *   interceptors: [loggingInterceptor],
+ * });
+ * ```
+ */
+interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+    /** Override the default consumer group ID from the constructor. */
+    groupId?: string;
+    /** Start reading from earliest offset. Default: `false`. */
+    fromBeginning?: boolean;
+    /** Automatically commit offsets. Default: `true`. */
+    autoCommit?: boolean;
+    /** Retry policy for failed message processing. */
+    retry?: RetryOptions;
+    /** Send failed messages to a Dead Letter Queue (`<topic>.dlq`). */
+    dlq?: boolean;
+    /** Interceptors called before/after each message. */
+    interceptors?: ConsumerInterceptor<T>[];
+    /** @internal Schema map populated by @SubscribeTo when descriptors have schemas. */
+    schemas?: Map<string, SchemaLike>;
+    /** Retry config for `consumer.subscribe()` when the topic doesn't exist yet. */
+    subscribeRetry?: SubscribeRetryOptions;
+    /**
+     * Route failed messages through a Kafka retry topic (`<topic>.retry`) instead of sleeping
+     * in-process between retry attempts. Requires `retry` to be set.
+     *
+     * Benefits over in-process retry:
+     * - Retry messages survive consumer restarts (durable)
+     * - Original consumer is not blocked during retry delay
+     *
+     * A companion consumer on `<topic>.retry` is auto-started with group `<groupId>-retry`.
+     * On exhaustion, messages go to `<topic>.dlq` (if `dlq: true`) or `onMessageLost`.
+     */
+    retryTopics?: boolean;
+    /**
+     * Timeout (ms) for waiting until each retry level consumer receives partition
+     * assignments after `startConsumer` connects. Default: `10000`.
+     * Increase this when the broker is slow to rebalance.
+     */
+    retryTopicAssignmentTimeoutMs?: number;
+    /**
+     * Log a warning if the message handler has not resolved within this window (ms).
+     * The handler is not cancelled — this is a diagnostic aid to surface stuck handlers
+     * before they starve a partition.
+     */
+    handlerTimeoutMs?: number;
+    /**
+     * Enable Lamport Clock deduplication.
+     * Requires the producer to stamp messages with `x-lamport-clock` headers
+     * (done automatically when using this library's send methods).
+     * Messages without the header are passed through unchanged.
+     */
+    deduplication?: DeduplicationOptions;
+    /**
+     * Drop messages older than this threshold, measured in milliseconds from
+     * the `x-timestamp` header set by the producer.
+     *
+     * Expired messages are routed to `{topic}.dlq` when `dlq: true`, otherwise
+     * `onTtlExpired` is called. The handler is never invoked for an expired message.
+     */
+    messageTtlMs?: number;
+    /**
+     * Automatically pause a partition when it accumulates too many consecutive
+     * failures, then resume after a recovery window.
+     *
+     * See `CircuitBreakerOptions` for the sliding-window semantics.
+     */
+    circuitBreaker?: CircuitBreakerOptions;
+    /**
+     * Max number of messages buffered in the `consume()` iterator queue before
+     * the partition is paused. The partition resumes when the queue drains below 50%.
+     * Only applies to `consume()`. Default: unbounded.
+     */
+    queueHighWaterMark?: number;
+    /**
+     * Kafka partition assignment strategy for this consumer group.
+     * - `'cooperative-sticky'` — **(default)** partitions move as little as possible on rebalance.
+     *   Best for horizontal scaling: only the partitions that need to be reassigned are moved.
+     * - `'roundrobin'` — distributes partitions as evenly as possible across consumers.
+     * - `'range'` — assigns contiguous partition ranges; can cause uneven distribution with multiple topics.
+     */
+    partitionAssigner?: "roundrobin" | "range" | "cooperative-sticky";
+    /**
+     * 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.
+     *
+     * **Per-consumer override**: takes precedence over `KafkaClientOptions.onTtlExpired`
+     * when both are set. Use this to handle TTL expiry differently per consumer group.
+     */
+    onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
+    /**
+     * Called when a message is silently dropped after all retries are exhausted
+     * and `dlq` is not enabled.
+     *
+     * **Per-consumer override**: takes precedence over `KafkaClientOptions.onMessageLost`
+     * when both are set. Use this for consumer-specific alerting or dead-message logging.
+     */
+    onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
+    /**
+     * Called before each retry attempt (both in-process and retry-topic paths).
+     *
+     * **Per-consumer override**: fires in addition to any global instrumentation hooks.
+     * Use this for per-consumer retry metrics or structured logging.
+     */
+    onRetry?: (envelope: EventEnvelope<any>, attempt: number, maxRetries: number) => void | Promise<void>;
+}
+/**
+ * Handle returned by `startConsumer` / `startBatchConsumer`.
+ *
+ * @example
+ * ```ts
+ * const handle = await kafka.startConsumer(['orders'], handler);
+ * // later, on shutdown:
+ * await handle.stop();
+ * ```
+ */
+interface ConsumerHandle {
+    /** The consumer group ID this consumer is running under. */
+    groupId: string;
+    /** Stop this consumer. Equivalent to calling `client.stopConsumer(groupId)`. */
+    stop(): Promise<void>;
+    /**
+     * Resolves once the consumer has received its first partition assignment from
+     * the broker (i.e. it has joined the group and is ready to receive messages).
+     *
+     * Use this in tests and startup probes instead of a fixed `setTimeout` delay:
+     *
+     * @example
+     * ```ts
+     * const handle = await kafka.startConsumer(['orders'], handler);
+     * await handle.ready(); // wait for partition assignment — no fixed sleep needed
+     * await kafka.sendMessage('orders', payload);
+     * ```
+     */
+    ready(): Promise<void>;
+}
+/**
+ * Context passed to the `transaction()` callback with type-safe send methods.
+ *
+ * @example
+ * ```ts
+ * await kafka.transaction(async (tx) => {
+ *   await tx.send('inventory.reserved', { itemId: 'a', qty: 1 });
+ *   await tx.sendBatch('audit.log', [
+ *     { value: { action: 'reserve', itemId: 'a' } },
+ *   ]);
+ * });
+ * ```
+ */
+interface TransactionContext<T extends TopicMapConstraint<T>> {
+    send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    send<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>, options?: BatchSendOptions): Promise<void>;
+}
+/**
+ * Transactional context passed to each `startTransactionalConsumer` handler invocation.
+ *
+ * Every call to `send` or `sendBatch` on this object is part of the same Kafka
+ * transaction as the source message offset commit. Either all sends and the offset
+ * commit succeed atomically, or the transaction is aborted and the source message
+ * is redelivered.
+ *
+ * @example
+ * ```ts
+ * await kafka.startTransactionalConsumer(['orders.created'], async (envelope, tx) => {
+ *   await tx.send('inventory.reserved', { orderId: envelope.payload.orderId, qty: 1 });
+ *   await tx.sendBatch('audit.log', [{ value: { action: 'reserve', orderId: envelope.payload.orderId } }]);
+ * });
+ * ```
+ */
+interface TransactionalHandlerContext<T extends TopicMapConstraint<T>> {
+    /**
+     * Send a message as part of this message's transaction.
+     * The send is staged — it only becomes visible to consumers after the transaction commits.
+     */
+    send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    /**
+     * Send multiple messages as part of this message's transaction.
+     * All messages are staged together and become visible only after commit.
+     */
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
+}
+/**
+ * Routing configuration for `startRoutedConsumer`.
+ *
+ * Messages are dispatched to the handler whose key matches the value of `header`.
+ * Unmatched messages are forwarded to `fallback` if provided, or silently skipped.
+ *
+ * @example
+ * ```ts
+ * await kafka.startRoutedConsumer(['events'], {
+ *   header: 'x-event-type',
+ *   routes: {
+ *     'order.created':   async (e) => handleOrderCreated(e.payload),
+ *     'order.cancelled': async (e) => handleOrderCancelled(e.payload),
+ *   },
+ *   fallback: async (e) => logger.warn('Unknown event type', e.headers),
+ * });
+ * ```
+ */
+interface RoutingOptions<E> {
+    /** Header whose value determines which handler is invoked. */
+    header: string;
+    /**
+     * Map of header value → handler.
+     * The handler with the matching key is called for each message.
+     */
+    routes: Record<string, (envelope: EventEnvelope<E>) => Promise<void>>;
+    /**
+     * Called when no route matches the header value (or the header is absent).
+     * If omitted, unmatched messages are silently skipped.
+     */
+    fallback?: (envelope: EventEnvelope<E>) => Promise<void>;
+}
+/**
+ * Metadata passed to the `startWindowConsumer` handler on each flush.
+ *
+ * @example
+ * ```ts
+ * await kafka.startWindowConsumer('events', async (batch, meta) => {
+ *   console.log(`Flush: ${batch.length} events, trigger=${meta.trigger}`);
+ *   console.log(`Window: ${meta.windowEnd - meta.windowStart} ms`);
+ *   await db.insertMany(batch.map(e => e.payload));
+ * }, { maxMessages: 100, maxMs: 5_000 });
+ * ```
+ */
+interface WindowMeta {
+    /** What triggered this flush: accumulated `maxMessages` messages, or the `maxMs` timer. */
+    trigger: "size" | "time";
+    /** Unix timestamp (ms) of the first message that entered the current window. */
+    windowStart: number;
+    /** Unix timestamp (ms) when the flush was initiated. */
+    windowEnd: number;
+}
+/**
+ * Options for `startWindowConsumer`.
+ *
+ * Extends `ConsumerOptions` — all standard consumer settings apply.
+ * `retryTopics`, `retryTopicAssignmentTimeoutMs`, and `queueHighWaterMark`
+ * are excluded: they are incompatible with windowed accumulation.
+ */
+interface WindowConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> extends Omit<ConsumerOptions<T>, "retryTopics" | "retryTopicAssignmentTimeoutMs" | "queueHighWaterMark"> {
+    /**
+     * Maximum number of messages to accumulate before flushing.
+     * When the buffer reaches this size the handler is called immediately,
+     * regardless of how much time has elapsed since the first message.
+     */
+    maxMessages: number;
+    /**
+     * Maximum time (ms) to wait after the first message before flushing.
+     * When this timer expires the handler is called with whatever messages
+     * have accumulated so far — even if the buffer is not full.
+     */
+    maxMs: number;
+}
+
+export { type TransactionalHandlerContext as A, type BatchMessageItem as B, type ClientId as C, type DeduplicationOptions as D, type EnvelopeHeaderOptions as E, type TtlExpiredContext as F, type GroupId as G, HEADER_CORRELATION_ID as H, type InferSchema as I, type WindowMeta as J, type KafkaInstrumentation as K, buildEnvelopeHeaders as L, type MessageHeaders as M, decodeHeaders as N, extractEnvelope as O, getEnvelopeContext as P, runWithEnvelopeContext as Q, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, topic as U, type WindowConsumerOptions as W, type ConsumerOptions as a, type TopicDescriptor as b, type BatchMeta as c, type BatchSendOptions as d, type BeforeConsumeResult as e, type CircuitBreakerOptions as f, type CompressionType as g, type ConsumerHandle as h, type ConsumerInterceptor as i, type DlqReason as j, type EventEnvelope as k, HEADER_EVENT_ID as l, HEADER_LAMPORT_CLOCK as m, HEADER_SCHEMA_VERSION as n, HEADER_TIMESTAMP as o, HEADER_TRACEPARENT as p, type KafkaLogger as q, type KafkaMetrics as r, type MessageLostContext as s, type RoutingOptions as t, type SchemaParseContext as u, type SendOptions as v, type SubscribeRetryOptions as w, type TTopicMessageMap as x, type TopicsFrom as y, type TransactionContext as z };