@drarzter/kafka-client 0.9.4 → 0.11.0

package/dist/{consumer.types-fFCag3VJ.d.mts → client/types/consumer.types.d.ts}

@@ -1,359 +1,8 @@
-/**
- * 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>;
-
+import type { TTopicMessageMap, TopicMapConstraint, MessageHeaders } from "./common";
+import type { SendOptions, BatchMessageItem, BatchSendOptions } from "./producer.types";
+import type { DedupStore } from "./dedup.types";
+import type { TopicDescriptor, SchemaLike } from "../message/topic";
+import type { EventEnvelope } from "../message/envelope";
 /**
  * Metadata exposed to batch consumer handlers.
  *
@@ -367,7 +16,7 @@ declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic:
  * }, { autoCommit: false });
  * ```
  */
-interface BatchMeta {
+export interface BatchMeta {
     /** Partition number for this batch. */
     partition: number;
     /**
@@ -394,7 +43,7 @@ interface BatchMeta {
  * });
  * ```
  */
-interface RetryOptions {
+export interface RetryOptions {
     /** Maximum number of retry attempts before giving up. */
     maxRetries: number;
     /** Base delay for exponential backoff in ms. Default: `1000`. */
@@ -421,15 +70,15 @@ interface RetryOptions {
  * 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.
+ * **In-session limitation (default store)**: with the built-in in-memory store,
+ * deduplication state 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. Provide a persistent `store` (e.g. Redis-backed) to
+ * make deduplication survive both restarts and rebalances.
  */
-interface DeduplicationOptions {
+export interface DeduplicationOptions {
     /**
      * What to do with detected duplicate messages:
      * - `'drop'`  — silently discard. No routing, no callback. **(default)**
@@ -443,6 +92,18 @@ interface DeduplicationOptions {
      * Defaults to `<consumedTopic>.duplicates`.
      */
     duplicatesTopic?: string;
+    /**
+     * Pluggable backing store for the per-partition last-processed clock.
+     *
+     * When omitted, an in-memory store is used — state is per-client, keyed by
+     * `groupId`, and cleared on `stopConsumer` / `disconnect`. Provide a
+     * persistent `DedupStore` (e.g. Redis-backed) so deduplication survives
+     * process restarts and consumer group rebalances.
+     *
+     * Store errors are handled fail-open: on a thrown/rejected read or write the
+     * error is logged and the message is treated as not a duplicate.
+     */
+    store?: DedupStore;
 }
 /**
  * Options for the per-partition circuit breaker.
@@ -469,7 +130,7 @@ interface DeduplicationOptions {
  * - **HALF-OPEN** — the partition is resumed. If the next `halfOpenSuccesses` messages
  *   succeed the circuit closes; a new failure immediately re-opens it.
  */
-interface CircuitBreakerOptions {
+export 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.
@@ -510,7 +171,7 @@ interface CircuitBreakerOptions {
  * await kafka.startConsumer(['orders'], handler, { interceptors: [logger] });
  * ```
  */
-interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+export 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. */
@@ -548,7 +209,7 @@ interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap
  * }
  * ```
  */
-type BeforeConsumeResult = (() => void) | {
+export type BeforeConsumeResult = (() => void) | {
     cleanup?(): void;
     wrap?(fn: () => Promise<void>): Promise<void>;
 };
@@ -560,7 +221,7 @@ type BeforeConsumeResult = (() => void) | {
  *   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";
+export 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.
@@ -585,7 +246,7 @@ type DlqReason = "handler-error" | "validation-error" | "lamport-clock-duplicate
  * const kafka = new KafkaClient(config, groupId, { instrumentation: [tracing] });
  * ```
  */
-interface KafkaInstrumentation {
+export interface KafkaInstrumentation {
     /** Called before sending — can mutate `headers` (e.g. inject `traceparent`). */
     beforeSend?(topic: string, headers: MessageHeaders): void;
     /** Called after a successful send. */
@@ -638,7 +299,7 @@ interface KafkaInstrumentation {
  * });
  * ```
  */
-interface TtlExpiredContext {
+export interface TtlExpiredContext {
     /** Topic the message was consumed from. */
     topic: string;
     /** Actual age of the message in ms at the time it was dropped. */
@@ -661,7 +322,7 @@ interface TtlExpiredContext {
  * });
  * ```
  */
-interface MessageLostContext {
+export interface MessageLostContext {
     /** Topic the message was consumed from. */
     topic: string;
     /** Error that caused the message to be dropped. */
@@ -681,7 +342,7 @@ interface MessageLostContext {
  * });
  * ```
  */
-interface SubscribeRetryOptions {
+export interface SubscribeRetryOptions {
     /** Maximum number of subscribe attempts. Default: `5`. */
     retries?: number;
     /** Delay between retries in ms. Default: `5000`. */
@@ -702,7 +363,7 @@ interface SubscribeRetryOptions {
  * });
  * ```
  */
-interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
+export 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`. */
@@ -779,6 +440,25 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
      * - `'range'` — assigns contiguous partition ranges; can cause uneven distribution with multiple topics.
      */
     partitionAssigner?: "roundrobin" | "range" | "cooperative-sticky";
+    /**
+     * Static group membership id (`group.instance.id`).
+     *
+     * A member that restarts within the broker's `session.timeout.ms` rejoins
+     * the group with the same partitions and **no rebalance** — useful for k8s
+     * rolling restarts and short redeploys. Must be unique per member within
+     * the consumer group (e.g. derive from the pod ordinal / hostname).
+     *
+     * Not propagated to retry-chain companion consumers (they run in their own
+     * groups and rebalance independently).
+     *
+     * @example
+     * ```ts
+     * await kafka.startConsumer(['orders'], handler, {
+     *   groupInstanceId: `orders-svc-${process.env.HOSTNAME}`,
+     * });
+     * ```
+     */
+    groupInstanceId?: string;
     /**
      * Called when a message is dropped due to TTL expiration (`messageTtlMs`).
      * Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
@@ -814,7 +494,7 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
  * await handle.stop();
  * ```
  */
-interface ConsumerHandle {
+export interface ConsumerHandle {
     /** The consumer group ID this consumer is running under. */
     groupId: string;
     /** Stop this consumer. Equivalent to calling `client.stopConsumer(groupId)`. */
@@ -847,7 +527,7 @@ interface ConsumerHandle {
  * });
  * ```
  */
-interface TransactionContext<T extends TopicMapConstraint<T>> {
+export 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>;
@@ -869,7 +549,7 @@ interface TransactionContext<T extends TopicMapConstraint<T>> {
  * });
  * ```
  */
-interface TransactionalHandlerContext<T extends TopicMapConstraint<T>> {
+export 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.
@@ -899,7 +579,7 @@ interface TransactionalHandlerContext<T extends TopicMapConstraint<T>> {
  * });
  * ```
  */
-interface RoutingOptions<E> {
+export interface RoutingOptions<E> {
     /** Header whose value determines which handler is invoked. */
     header: string;
     /**
@@ -925,7 +605,7 @@ interface RoutingOptions<E> {
  * }, { maxMessages: 100, maxMs: 5_000 });
  * ```
  */
-interface WindowMeta {
+export 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. */
@@ -940,7 +620,7 @@ interface WindowMeta {
  * `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"> {
+export 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,
@@ -954,5 +634,4 @@ interface WindowConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageM
      */
     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 };
+//# sourceMappingURL=consumer.types.d.ts.map

package/dist/client/types/consumer.types.d.ts.map

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

package/dist/client/types/dedup.types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pluggable backing store for Lamport-clock deduplication.
+ *
+ * By default deduplication state is held in memory (`InMemoryDedupStore`) and is
+ * reset on process restart or rebalance. Provide a custom `DedupStore` — backed
+ * by Redis, a database, or any external system — to make deduplication survive
+ * restarts and rebalances.
+ *
+ * The store is keyed by consumer `groupId` and `"topic:partition"`. Both methods
+ * may run synchronously or return a promise; `applyDeduplication` always awaits
+ * the result.
+ *
+ * **Failure semantics (fail-open):** if `getLastClock` or `setLastClock` throws
+ * or rejects, the error is logged and the message is treated as **not** a
+ * duplicate. This biases towards at-least-once delivery — a transient store
+ * outage never silently drops messages, it only weakens deduplication until the
+ * store recovers.
+ *
+ * @example
+ * ```ts
+ * // Minimal Redis-backed store (generic redis client pseudocode).
+ * class RedisDedupStore implements DedupStore {
+ *   constructor(private readonly redis: RedisClient) {}
+ *
+ *   private key(groupId: string, topicPartition: string): string {
+ *     return `dedup:${groupId}:${topicPartition}`;
+ *   }
+ *
+ *   async getLastClock(groupId: string, topicPartition: string): Promise<number | undefined> {
+ *     const raw = await this.redis.get(this.key(groupId, topicPartition));
+ *     return raw === null ? undefined : Number(raw);
+ *   }
+ *
+ *   async setLastClock(groupId: string, topicPartition: string, clock: number): Promise<void> {
+ *     await this.redis.set(this.key(groupId, topicPartition), String(clock));
+ *   }
+ * }
+ *
+ * await kafka.startConsumer(['payments'], handler, {
+ *   deduplication: { strategy: 'drop', store: new RedisDedupStore(redis) },
+ * });
+ * ```
+ */
+export interface DedupStore {
+    /** Return the last processed Lamport clock for a group+topic:partition, or undefined if none. */
+    getLastClock(groupId: string, topicPartition: string): number | undefined | Promise<number | undefined>;
+    /** Persist the last processed Lamport clock for a group+topic:partition. */
+    setLastClock(groupId: string, topicPartition: string, clock: number): void | Promise<void>;
+}
+//# sourceMappingURL=dedup.types.d.ts.map

package/dist/client/types/dedup.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.types.d.ts","sourceRoot":"","sources":["../../../src/client/types/dedup.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,UAAU;IACzB,iGAAiG;IACjG,YAAY,CACV,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GACrB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACpD,4EAA4E;IAC5E,YAAY,CACV,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}