@drarzter/kafka-client 0.9.4 → 0.10.0

package/dist/client/kafka.client/index.d.ts

@@ -0,0 +1,155 @@
+import type { TopicDescriptor } from "../message/topic";
+import type { EventEnvelope } from "../message/envelope";
+import type { ClientId, GroupId, SendOptions, BatchMessageItem, BatchSendOptions, ConsumerOptions, ConsumerHandle, TransactionContext, TopicMapConstraint, IKafkaClient, KafkaClientOptions, BatchMeta, DlqReplayOptions, ConsumerGroupSummary, TopicDescription, MessageHeaders, ReadSnapshotOptions, CheckpointResult, CheckpointRestoreResult, RestoreCheckpointOptions, WindowConsumerOptions, WindowMeta, RoutingOptions, TransactionalHandlerContext } from "../types";
+export * from "../types";
+export { InMemoryDedupStore } from "./infra/dedup.store";
+/**
+ * Type-safe Kafka client.
+ * Wraps @confluentinc/kafka-javascript (librdkafka) with JSON serialization,
+ * retries, DLQ, transactions, and interceptors.
+ *
+ * @typeParam T - Topic-to-message type mapping for compile-time safety.
+ */
+export declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClient<T> {
+    readonly clientId: ClientId;
+    private readonly ctx;
+    /**
+     * Create a new KafkaClient.
+     * @param clientId Unique client identifier (used in Kafka metadata and logs).
+     * @param groupId Default consumer group ID for this client.
+     * @param brokers Array of broker addresses, e.g. `['localhost:9092']`.
+     * @param options Optional client-wide configuration.
+     * @example
+     * ```ts
+     * const kafka = new KafkaClient('my-service', 'my-service-group', ['localhost:9092'], {
+     *   lagThrottle: { maxLag: 10_000 },
+     *   onMessageLost: (ctx) => logger.error('Message lost', ctx),
+     * });
+     * await kafka.connectProducer();
+     * ```
+     */
+    constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
+    /** @inheritDoc */
+    sendMessage<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
+    sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    /** @inheritDoc */
+    sendTombstone(topic: string, key: string, headers?: MessageHeaders): Promise<void>;
+    /** @inheritDoc */
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>, options?: BatchSendOptions): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>, options?: BatchSendOptions): Promise<void>;
+    /** @inheritDoc */
+    transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
+    /** @inheritDoc */
+    connectProducer(): Promise<void>;
+    /** @internal */
+    disconnectProducer(): Promise<void>;
+    /** @inheritDoc */
+    startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (envelope: EventEnvelope<T[K[number]]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (envelope: EventEnvelope<D["__type"]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    /** @inheritDoc */
+    startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (envelopes: EventEnvelope<T[K[number]]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (envelopes: EventEnvelope<D["__type"]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    /** @inheritDoc */
+    consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
+    /** @inheritDoc */
+    startWindowConsumer<K extends keyof T & string>(topic: K, handler: (envelopes: EventEnvelope<T[K]>[], meta: WindowMeta) => Promise<void>, options: WindowConsumerOptions<T>): Promise<ConsumerHandle>;
+    /** @inheritDoc */
+    startRoutedConsumer<K extends Array<keyof T>>(topics: K, routing: RoutingOptions<T[K[number]]>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    /**
+     * Start a relay that delivers messages produced with
+     * `SendOptions.deliverAfterMs` from `<topic>.delayed` to their target topic
+     * once their deadline passes.
+     *
+     * Forwarding is transactional (produce + source-offset commit are atomic),
+     * so no duplicates are relayed even if the relay crashes mid-forward.
+     * Delivery time is a lower bound — the relay must be running for delayed
+     * messages to be delivered at all.
+     *
+     * @param topics Target topic name(s) whose `<topic>.delayed` staging topics to relay.
+     * @param options Optional `groupId` override (default: `<defaultGroupId>-delayed-relay`).
+     *
+     * @example
+     * ```ts
+     * await kafka.startDelayedRelay(['orders.reminder']);
+     * await kafka.sendMessage('orders.reminder', payload, { deliverAfterMs: 60_000 });
+     * // → delivered to orders.reminder ~60 s later
+     * ```
+     */
+    startDelayedRelay(topics: (keyof T & string) | Array<keyof T & string>, options?: {
+        groupId?: string;
+    }): Promise<ConsumerHandle>;
+    /** @inheritDoc */
+    startTransactionalConsumer<K extends Array<keyof T>>(topics: K, handler: (envelope: EventEnvelope<T[K[number]]>, tx: TransactionalHandlerContext<T>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
+    /** @inheritDoc */
+    stopConsumer(groupId?: string): Promise<void>;
+    /** @inheritDoc */
+    pauseConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
+    /** @inheritDoc */
+    resumeConsumer(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>): void;
+    /** @inheritDoc */
+    replayDlq(topic: string, options?: DlqReplayOptions): Promise<{
+        replayed: number;
+        skipped: number;
+    }>;
+    /** @inheritDoc */
+    readSnapshot<K extends keyof T & string>(topic: K, options?: ReadSnapshotOptions): Promise<Map<string, EventEnvelope<T[K]>>>;
+    /** @inheritDoc */
+    checkpointOffsets(groupId: string | undefined, checkpointTopic: string): Promise<CheckpointResult>;
+    /** @inheritDoc */
+    restoreFromCheckpoint(groupId: string | undefined, checkpointTopic: string, options?: RestoreCheckpointOptions): Promise<CheckpointRestoreResult>;
+    /** @inheritDoc */
+    resetOffsets(groupId: string | undefined, topic: string, position: "earliest" | "latest"): Promise<void>;
+    /** @inheritDoc */
+    seekToOffset(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partition: number;
+        offset: string;
+    }>): Promise<void>;
+    /** @inheritDoc */
+    seekToTimestamp(groupId: string | undefined, assignments: Array<{
+        topic: string;
+        partition: number;
+        timestamp: number;
+    }>): Promise<void>;
+    /** @inheritDoc */
+    getConsumerLag(groupId?: string): Promise<Array<{
+        topic: string;
+        partition: number;
+        lag: number;
+    }>>;
+    /** @inheritDoc */
+    checkStatus(): Promise<import("../types").KafkaHealthResult>;
+    /** @inheritDoc */
+    listConsumerGroups(): Promise<ConsumerGroupSummary[]>;
+    /** @inheritDoc */
+    describeTopics(topics?: string[]): Promise<TopicDescription[]>;
+    /** @inheritDoc */
+    deleteRecords(topic: string, partitions: Array<{
+        partition: number;
+        offset: string;
+    }>): Promise<void>;
+    /** @inheritDoc */
+    getCircuitState(topic: string, partition: number, groupId?: string): {
+        status: "closed" | "open" | "half-open";
+        failures: number;
+        windowSize: number;
+    } | undefined;
+    /** @inheritDoc */
+    getMetrics(topic?: string): Readonly<import("../types").KafkaMetrics>;
+    /** @inheritDoc */
+    resetMetrics(topic?: string): void;
+    getClientId(): ClientId;
+    /** @inheritDoc */
+    disconnect(drainTimeoutMs?: number): Promise<void>;
+    /** NestJS lifecycle hook — called automatically on module teardown. */
+    onModuleDestroy(): Promise<void>;
+    /** @inheritDoc */
+    enableGracefulShutdown(signals?: NodeJS.Signals[], drainTimeoutMs?: number): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/client/kafka.client/index.d.ts.map

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

package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts

@@ -0,0 +1,61 @@
+import type { EventEnvelope } from "../../message/envelope";
+import type { CircuitBreakerOptions, KafkaInstrumentation, KafkaLogger } from "../../types";
+type CircuitBreakerDeps = {
+    pauseConsumer: (gid: string, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>) => void;
+    resumeConsumer: (gid: string, assignments: Array<{
+        topic: string;
+        partitions: number[];
+    }>) => void;
+    logger: KafkaLogger;
+    instrumentation: KafkaInstrumentation[];
+};
+/**
+ * Per-consumer-group circuit breaker.
+ * State is tracked per `${gid}:${topic}:${partition}` key using a sliding window.
+ * Drives CLOSED → OPEN → HALF-OPEN → CLOSED transitions and pauses/resumes
+ * topic-partition consumption accordingly.
+ */
+export declare class CircuitBreakerManager {
+    private readonly deps;
+    private readonly states;
+    private readonly configs;
+    constructor(deps: CircuitBreakerDeps);
+    /**
+     * Register or update circuit breaker configuration for a consumer group.
+     * Must be called before the group starts consuming for the config to take effect.
+     * @param gid Consumer group ID.
+     * @param options Circuit breaker thresholds and timing configuration.
+     */
+    setConfig(gid: string, options: CircuitBreakerOptions): void;
+    /**
+     * Returns a snapshot of the circuit breaker state for a given topic-partition.
+     * Returns `undefined` when no state exists for the key.
+     */
+    getState(topic: string, partition: number, gid: string): {
+        status: "closed" | "open" | "half-open";
+        failures: number;
+        windowSize: number;
+    } | undefined;
+    /**
+     * Record a failure for the given envelope and group.
+     * Drives the CLOSED → OPEN and HALF-OPEN → OPEN transitions.
+     */
+    onFailure(envelope: EventEnvelope<any>, gid: string): void;
+    /**
+     * Record a success for the given envelope and group.
+     * Drives the HALF-OPEN → CLOSED transition and updates the success window.
+     */
+    onSuccess(envelope: EventEnvelope<any>, gid: string): void;
+    /**
+     * Remove all circuit state and config for the given group.
+     * Called when a consumer is stopped via `stopConsumer(groupId)`.
+     */
+    removeGroup(gid: string): void;
+    /** Clear all circuit state and config. Called on `disconnect()`. */
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=circuit-breaker.manager.d.ts.map

package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.manager.d.ts","sourceRoot":"","sources":["../../../../src/client/kafka.client/infra/circuit-breaker.manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAS5F,KAAK,kBAAkB,GAAG;IACxB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAClG,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACnG,MAAM,EAAE,WAAW,CAAC;IACpB,eAAe,EAAE,oBAAoB,EAAE,CAAC;CACzC,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,qBAAqB;IAIpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;gBAEvC,IAAI,EAAE,kBAAkB;IAErD;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAI5D;;;OAGG;IACH,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV;QAAE,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAUhG;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IA6D1D;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAkC1D;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAU9B,oEAAoE;IACpE,KAAK,IAAI,IAAI;CAKd"}

package/dist/client/kafka.client/infra/dedup.store.d.ts

@@ -0,0 +1,28 @@
+import type { DedupStore } from "../../types";
+/**
+ * In-memory {@link DedupStore} backed by a nested map:
+ * `groupId` → `"topic:partition"` → last processed Lamport clock.
+ *
+ * This is the default store used when `DeduplicationOptions.store` is not set.
+ * State lives only in the current process and is cleared on `stopConsumer` /
+ * `disconnect` and lost on restart or rebalance. Provide a persistent
+ * `DedupStore` (e.g. Redis-backed) to survive restarts and rebalances.
+ *
+ * The backing map is injected so the client can share a single map across all
+ * consumer groups and clear it during shutdown.
+ *
+ * @example
+ * ```ts
+ * const states = new Map<string, Map<string, number>>();
+ * const store = new InMemoryDedupStore(states);
+ * store.setLastClock('billing', 'orders:0', 42);
+ * store.getLastClock('billing', 'orders:0'); // 42
+ * ```
+ */
+export declare class InMemoryDedupStore implements DedupStore {
+    private readonly states;
+    constructor(states: Map<string, Map<string, number>>);
+    getLastClock(groupId: string, topicPartition: string): number | undefined;
+    setLastClock(groupId: string, topicPartition: string, clock: number): void;
+}
+//# sourceMappingURL=dedup.store.d.ts.map

package/dist/client/kafka.client/infra/dedup.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.store.d.ts","sourceRoot":"","sources":["../../../../src/client/kafka.client/infra/dedup.store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IAEjD,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAG3D,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzE,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAQ3E"}

package/dist/client/kafka.client/infra/inflight.tracker.d.ts

@@ -0,0 +1,22 @@
+/** Tracks in-flight async handlers and provides a drain-wait mechanism. */
+export declare class InFlightTracker {
+    private readonly warn;
+    private inFlightTotal;
+    private readonly drainResolvers;
+    constructor(warn: (msg: string) => void);
+    /**
+     * Wrap an async handler so its lifetime is counted against the in-flight total.
+     * Resolvers registered with `waitForDrain` are notified when the count reaches zero.
+     * @param fn The async function to track.
+     * @returns The same promise returned by `fn`.
+     */
+    track<R>(fn: () => Promise<R>): Promise<R>;
+    /**
+     * Resolve when all tracked handlers have completed, or after `timeoutMs` elapses.
+     * Logs a warning (via the injected `warn` callback) if the timeout is hit before draining.
+     * Returns immediately if there are no in-flight handlers.
+     * @param timeoutMs Maximum time to wait in milliseconds before resolving anyway.
+     */
+    waitForDrain(timeoutMs: number): Promise<void>;
+}
+//# sourceMappingURL=inflight.tracker.d.ts.map

package/dist/client/kafka.client/infra/inflight.tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inflight.tracker.d.ts","sourceRoot":"","sources":["../../../../src/client/kafka.client/infra/inflight.tracker.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;gBAE3B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI;IAExD;;;;;OAKG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAgB1C;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAgB/C"}

package/dist/client/kafka.client/infra/metrics.manager.d.ts

@@ -0,0 +1,67 @@
+import type { EventEnvelope } from "../../message/envelope";
+import type { DlqReason, KafkaInstrumentation, KafkaMetrics } from "../../types";
+export type MetricsManagerDeps = {
+    instrumentation: KafkaInstrumentation[];
+    onCircuitFailure: (envelope: EventEnvelope<any>, gid: string) => void;
+    onCircuitSuccess: (envelope: EventEnvelope<any>, gid: string) => void;
+};
+/**
+ * Maintains per-topic event counters and dispatches instrumentation hooks.
+ * Created once per `KafkaClient` instance and shared across all consumers and producers.
+ */
+export declare class MetricsManager {
+    private readonly deps;
+    private readonly topicMetrics;
+    constructor(deps: MetricsManagerDeps);
+    private metricsFor;
+    /** Fire `afterSend` instrumentation hooks for each message in a batch. */
+    notifyAfterSend(topic: string, count: number): void;
+    /**
+     * Increment the retry counter for the envelope's topic and fire all `onRetry` instrumentation hooks.
+     * @param envelope The message envelope being retried.
+     * @param attempt Current retry attempt number (1-based).
+     * @param maxRetries Maximum number of retries configured for this consumer.
+     */
+    notifyRetry(envelope: EventEnvelope<any>, attempt: number, maxRetries: number): void;
+    /**
+     * Increment the DLQ counter for the envelope's topic and fire all `onDlq` instrumentation hooks.
+     * Circuit breaker failures are recorded separately via `notifyFailure` at the
+     * handler-error boundary — dead-lettering itself is not a circuit event.
+     * @param envelope The message envelope being sent to the DLQ.
+     * @param reason The reason the message is being dead-lettered.
+     */
+    notifyDlq(envelope: EventEnvelope<any>, reason: DlqReason): void;
+    /**
+     * Notify the circuit breaker of a handler failure. Fired on every failed
+     * handler attempt (in-process retries and retry-topic levels included),
+     * independent of whether the message is ultimately dead-lettered.
+     * @param envelope The message envelope whose handler failed.
+     * @param gid Consumer group ID — used to drive circuit breaker state.
+     */
+    notifyFailure(envelope: EventEnvelope<any>, gid: string): void;
+    /**
+     * Increment the deduplication counter for the envelope's topic and fire all `onDuplicate` hooks.
+     * @param envelope The duplicate message envelope.
+     * @param strategy The deduplication strategy applied (`"drop"`, `"dlq"`, or `"topic"`).
+     */
+    notifyDuplicate(envelope: EventEnvelope<any>, strategy: "drop" | "dlq" | "topic"): void;
+    /**
+     * Increment the processed counter for the envelope's topic, fire all `onMessage` hooks,
+     * and notify the circuit breaker of a success (when `gid` is provided).
+     * @param envelope The successfully processed message envelope.
+     * @param gid Consumer group ID — used to drive circuit breaker state.
+     */
+    notifyMessage(envelope: EventEnvelope<any>, gid?: string): void;
+    /**
+     * Return a snapshot of event counters.
+     * @param topic When provided, returns counters for that topic only; otherwise aggregates all topics.
+     * @returns Read-only `KafkaMetrics` snapshot. Returns zero-valued counters if the topic has no events.
+     */
+    getMetrics(topic?: string): Readonly<KafkaMetrics>;
+    /**
+     * Reset event counters to zero.
+     * @param topic When provided, clears counters for that topic only; otherwise clears all topics.
+     */
+    resetMetrics(topic?: string): void;
+}
+//# sourceMappingURL=metrics.manager.d.ts.map

package/dist/client/kafka.client/infra/metrics.manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.manager.d.ts","sourceRoot":"","sources":["../../../../src/client/kafka.client/infra/metrics.manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEjF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,eAAe,EAAE,oBAAoB,EAAE,CAAC;IACxC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACtE,gBAAgB,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACvE,CAAC;AAEF;;;GAGG;AACH,qBAAa,cAAc;IAGb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmC;gBAEnC,IAAI,EAAE,kBAAkB;IAErD,OAAO,CAAC,UAAU;IASlB,0EAA0E;IAC1E,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKnD;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAKpF;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAKhE;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAI9D;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,IAAI;IAKvF;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAM/D;;;;OAIG;IACH,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC;IAelD;;;OAGG;IACH,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;CAOnC"}

package/dist/client/kafka.client/producer/lifecycle.d.ts

@@ -0,0 +1,41 @@
+import type { IProducer } from "../../transport/transport.interface";
+type Producer = IProducer;
+import type { KafkaClientContext } from "../context";
+import type { TopicMapConstraint } from "../../types";
+import { toError } from "../consumer/pipeline";
+/**
+ * Process-level registry of active transactional producer IDs.
+ * Shared across `transactionImpl` (send.ts) and `createRetryTxProducer`.
+ * Cross-process conflicts cannot be detected here — they surface as fencing errors from the broker.
+ */
+export declare const _activeTransactionalIds: Set<string>;
+/**
+ * Ensure a topic exists, creating it if `autoCreateTopics` is enabled.
+ * Concurrent calls for the same topic are deduplicated via a promise cache.
+ */
+export declare function ensureTopic<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, topic: string): Promise<void>;
+/**
+ * Create and connect a transactional producer for EOS routing.
+ * Each retry level consumer uses its own producer with a unique `transactionalId`
+ * so Kafka can fence stale producers on restart without affecting other levels.
+ */
+export declare function createRetryTxProducer<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, transactionalId: string): Promise<Producer>;
+export declare function connectProducerImpl<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>): Promise<void>;
+export declare function disconnectImpl<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, drainTimeoutMs?: number): Promise<void>;
+export declare function startLagThrottlePoller<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>): void;
+/**
+ * Recover the Lamport clock from the last message across the given topics.
+ * Seeks every non-empty partition to its last offset, reads one message per
+ * partition, and extracts the maximum `x-lamport-clock` header value.
+ * Topics that are empty or missing are silently skipped.
+ */
+export declare function recoverLamportClockImpl<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, topics: string[]): Promise<void>;
+/**
+ * Start a timer that logs a warning if `fn` hasn't resolved within `timeoutMs`.
+ * The handler itself is not cancelled — the warning is diagnostic only.
+ */
+export declare function wrapWithTimeoutWarning<R>(logger: {
+    warn: (msg: string) => void;
+}, fn: () => Promise<R>, timeoutMs: number, topic: string): Promise<R>;
+export { toError };
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/client/kafka.client/producer/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/client/kafka.client/producer/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,KAAK,QAAQ,GAAG,SAAS,CAAC;AAE1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,aAAoB,CAAC;AAIzD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAC/D,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAcf;AAID;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACzE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAID,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACvE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,cAAc,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAClE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,cAAc,SAAS,GACtB,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAID,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACpE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,GACzB,IAAI,CA8BN;AAID;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAC3E,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,IAAI,CAAC,CAkIf;AAID;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,CAAC,CAAC,CAWZ;AAGD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/client/kafka.client/producer/ops.d.ts

@@ -0,0 +1,70 @@
+import type { SchemaLike, SchemaParseContext } from "../../message/topic";
+import type { BatchMessageItem, CompressionType, KafkaInstrumentation, KafkaLogger, MessageHeaders } from "../../types";
+/**
+ * Extract the plain topic name string from either a `TopicDescriptor` object or a raw string.
+ * Falls back to `String(topicOrDescriptor)` for any other value.
+ */
+export declare function resolveTopicName(topicOrDescriptor: unknown): string;
+/**
+ * Register the schema attached to a `TopicDescriptor` into the shared schema registry.
+ * If a different schema is already registered for the same topic, logs a warning and
+ * overwrites it — consistent schemas across all call sites avoid silent validation drift.
+ *
+ * @param topicOrDesc A `TopicDescriptor` (with `__schema`) or a plain string. Plain strings are ignored.
+ * @param schemaRegistry Mutable map of topic name → validator shared across the client.
+ * @param logger Optional logger for conflict warnings.
+ */
+export declare function registerSchema(topicOrDesc: any, schemaRegistry: Map<string, SchemaLike>, logger?: KafkaLogger): void;
+/**
+ * Validate `message` against the schema attached to `topicOrDesc` (or looked up from the
+ * registry when `strictSchemasEnabled` is on). Returns the parsed (potentially transformed)
+ * value on success, or throws a `KafkaValidationError` on failure.
+ *
+ * Validation priority:
+ * 1. Inline schema on the `TopicDescriptor` — always applied.
+ * 2. Registry schema — applied only when `strictSchemasEnabled` is `true`.
+ * 3. No schema found — returns `message` unchanged.
+ *
+ * @param topicOrDesc Topic descriptor carrying an inline `__schema`, or a plain topic string.
+ * @param message The raw message payload to validate.
+ * @param deps Schema registry and strict-mode flag.
+ * @param ctx Optional parse context forwarded to the schema (topic name, headers, version).
+ */
+export declare function validateMessage(topicOrDesc: any, message: any, deps: {
+    schemaRegistry: Map<string, SchemaLike>;
+    strictSchemasEnabled: boolean;
+}, ctx?: SchemaParseContext): Promise<any>;
+export type BuildSendPayloadDeps = {
+    schemaRegistry: Map<string, SchemaLike>;
+    strictSchemasEnabled: boolean;
+    instrumentation: KafkaInstrumentation[];
+    logger: KafkaLogger;
+    /** Called once per message to get the next Lamport clock value. Omit to disable clock stamping. */
+    nextLamportClock?: () => number;
+};
+/**
+ * Build the Kafka producer payload from a topic descriptor (or name) and an array of messages.
+ *
+ * For each message the function:
+ * 1. Builds envelope headers (`x-event-id`, `x-correlation-id`, `x-timestamp`, …).
+ * 2. Stamps the Lamport clock header when `deps.nextLamportClock` is provided.
+ * 3. Calls `beforeSend` instrumentation hooks so tracing can inject `traceparent` etc.
+ * 4. Validates the payload against the attached or registry schema.
+ * 5. JSON-serialises the validated value.
+ *
+ * @param topicOrDesc Topic descriptor or plain topic name string.
+ * @param messages Array of outgoing messages with optional key, headers, and metadata.
+ * @param deps Schema registry, strict-mode flag, instrumentation hooks, and Lamport clock factory.
+ * @param compression Optional compression codec to include in the returned payload object.
+ * @returns Kafka producer `send()` payload — `{ topic, messages, compression? }`.
+ */
+export declare function buildSendPayload(topicOrDesc: any, messages: Array<BatchMessageItem<any>>, deps: BuildSendPayloadDeps, compression?: CompressionType): Promise<{
+    topic: string;
+    compression?: CompressionType;
+    messages: Array<{
+        value: string;
+        key: string | null;
+        headers: MessageHeaders;
+    }>;
+}>;
+//# sourceMappingURL=ops.d.ts.map

package/dist/client/kafka.client/producer/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../../../src/client/kafka.client/producer/ops.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,CAUnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,GAAG,EAChB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACvC,MAAM,CAAC,EAAE,WAAW,GACnB,IAAI,CAYN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,GAAG,EAChB,OAAO,EAAE,GAAG,EACZ,IAAI,EAAE;IACJ,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,oBAAoB,EAAE,OAAO,CAAC;CAC/B,EACD,GAAG,CAAC,EAAE,kBAAkB,GACvB,OAAO,CAAC,GAAG,CAAC,CAwBd;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,eAAe,EAAE,oBAAoB,EAAE,CAAC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,GAAG,EAChB,QAAQ,EAAE,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,EACtC,IAAI,EAAE,oBAAoB,EAC1B,WAAW,CAAC,EAAE,eAAe,GAC5B,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,QAAQ,EAAE,KAAK,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,OAAO,EAAE,cAAc,CAAC;KACzB,CAAC,CAAC;CACJ,CAAC,CAuCD"}

package/dist/client/kafka.client/producer/send.d.ts

@@ -0,0 +1,21 @@
+import type { KafkaClientContext } from "../context";
+import type { TopicMapConstraint, SendOptions, BatchMessageItem, BatchSendOptions, TransactionContext, MessageHeaders, CompressionType } from "../../types";
+/**
+ * Build a ProduceRequest payload: register schema, validate, stamp envelope headers.
+ * Shared by sendMessage, sendBatch, and transaction sends.
+ */
+export declare function preparePayload<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, topicOrDesc: any, messages: Array<BatchMessageItem<any>>, compression?: CompressionType): Promise<{
+    topic: string;
+    compression?: CompressionType;
+    messages: Array<{
+        value: string;
+        key: string | null;
+        headers: MessageHeaders;
+    }>;
+}>;
+export declare function sendMessageImpl<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, topicOrDesc: any, message: any, options?: SendOptions): Promise<void>;
+export declare function sendBatchImpl<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, topicOrDesc: any, messages: Array<BatchMessageItem<any>>, options?: BatchSendOptions): Promise<void>;
+export declare function sendTombstoneImpl<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, topic: string, key: string, headers?: MessageHeaders): Promise<void>;
+export declare function transactionImpl<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>, fn: (txCtx: TransactionContext<T>) => Promise<void>): Promise<void>;
+export declare function waitIfThrottled<T extends TopicMapConstraint<T>>(ctx: KafkaClientContext<T>): Promise<void>;
+//# sourceMappingURL=send.d.ts.map

package/dist/client/kafka.client/producer/send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../../src/client/kafka.client/producer/send.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,eAAe,EAChB,MAAM,aAAa,CAAC;AAUrB;;;GAGG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAClE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,WAAW,EAAE,GAAG,EAChB,QAAQ,EAAE,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,EACtC,WAAW,CAAC,EAAE,eAAe;;;;;;;;GAW9B;AAyBD,wBAAsB,eAAe,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACnE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,WAAW,EAAE,GAAG,EAChB,OAAO,EAAE,GAAG,EACZ,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,wBAAsB,aAAa,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACjE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,WAAW,EAAE,GAAG,EAChB,QAAQ,EAAE,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,EACtC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACrE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,eAAe,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACnE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC1B,EAAE,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC,CAqCf;AA0DD,wBAAsB,eAAe,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EACnE,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/client/kafka.client/validate-options.d.ts

@@ -0,0 +1,11 @@
+import type { KafkaClientOptions } from "../types";
+/**
+ * Fail-fast validation of `KafkaClient` constructor arguments.
+ * Collects every problem and throws a single error listing all of them, so a
+ * misconfigured client fails at construction with a clear message instead of
+ * surfacing as a confusing driver error on first use.
+ *
+ * @throws Error listing every invalid argument/option found.
+ */
+export declare function validateClientOptions(clientId: string, groupId: string, brokers: string[], options?: KafkaClientOptions): void;
+//# sourceMappingURL=validate-options.d.ts.map

package/dist/client/kafka.client/validate-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-options.d.ts","sourceRoot":"","sources":["../../../src/client/kafka.client/validate-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,IAAI,CA0EN"}