@drarzter/kafka-client 0.6.6 → 0.6.9

package/dist/index.js

@@ -376,7 +376,10 @@ async function sendToDlq(topic2, rawMessage, deps, meta) {
     deps.logger.warn(`Message sent to DLQ: ${payload.topic}`);
   } catch (error) {
     const err = toError(error);
-    deps.logger.error(`Failed to send message to DLQ ${payload.topic}:`, err.stack);
+    deps.logger.error(
+      `Failed to send message to DLQ ${payload.topic}:`,
+      err.stack
+    );
     await deps.onMessageLost?.({
       topic: topic2,
       error: err,
@@ -391,14 +394,9 @@ var RETRY_HEADER_MAX_RETRIES = "x-retry-max-retries";
 var RETRY_HEADER_ORIGINAL_TOPIC = "x-retry-original-topic";
 function buildRetryTopicPayload(originalTopic, rawMessages, attempt, maxRetries, delayMs, originalHeaders) {
   const retryTopic = `${originalTopic}.retry.${attempt}`;
+  const STRIP = /* @__PURE__ */ new Set([RETRY_HEADER_ATTEMPT, RETRY_HEADER_AFTER, RETRY_HEADER_MAX_RETRIES, RETRY_HEADER_ORIGINAL_TOPIC]);
   function buildHeaders(hdr) {
-    const {
-      [RETRY_HEADER_ATTEMPT]: _a,
-      [RETRY_HEADER_AFTER]: _b,
-      [RETRY_HEADER_MAX_RETRIES]: _c,
-      [RETRY_HEADER_ORIGINAL_TOPIC]: _d,
-      ...userHeaders
-    } = hdr;
+    const userHeaders = Object.fromEntries(Object.entries(hdr).filter(([k]) => !STRIP.has(k)));
     return {
       ...userHeaders,
       [RETRY_HEADER_ATTEMPT]: String(attempt),
@@ -454,10 +452,18 @@ function buildDuplicateTopicPayload(sourceTopic, rawMessage, destinationTopic, m
     "x-duplicate-incoming-clock": String(meta?.incomingClock ?? 0),
     "x-duplicate-last-processed-clock": String(meta?.lastProcessedClock ?? 0)
   };
-  return { topic: destinationTopic, messages: [{ value: rawMessage, headers }] };
+  return {
+    topic: destinationTopic,
+    messages: [{ value: rawMessage, headers }]
+  };
 }
 async function sendToDuplicatesTopic(sourceTopic, rawMessage, destinationTopic, deps, meta) {
-  const payload = buildDuplicateTopicPayload(sourceTopic, rawMessage, destinationTopic, meta);
+  const payload = buildDuplicateTopicPayload(
+    sourceTopic,
+    rawMessage,
+    destinationTopic,
+    meta
+  );
   try {
     await deps.producer.send(payload);
     deps.logger.warn(`Duplicate message forwarded to ${destinationTopic}`);
@@ -549,7 +555,21 @@ async function executeWithRetry(fn, ctx, deps) {
       interceptors,
       deps.instrumentation
     );
-    if (!error) return;
+    if (!error) {
+      if (deps.eosCommitOnSuccess) {
+        try {
+          await deps.eosCommitOnSuccess();
+        } catch (commitErr) {
+          deps.logger.error(
+            `EOS offset commit failed after successful handler \u2014 message will be redelivered:`,
+            toError(commitErr).stack
+          );
+          return;
+        }
+      }
+      for (const env of envelopes) deps.onMessage?.(env);
+      return;
+    }
     const isLastAttempt = attempt === maxAttempts;
     const reportedError = isLastAttempt && maxAttempts > 1 ? new KafkaRetryExhaustedError(
       topic2,
@@ -565,15 +585,28 @@ async function executeWithRetry(fn, ctx, deps) {
     if (retryTopics && retry) {
       const cap = Math.min(backoffMs, maxBackoffMs);
       const delay = Math.floor(Math.random() * cap);
-      await sendToRetryTopic(
-        topic2,
-        rawMessages,
-        1,
-        retry.maxRetries,
-        delay,
-        isBatch ? envelopes.map((e) => e.headers) : envelopes[0]?.headers ?? {},
-        deps
-      );
+      if (deps.eosRouteToRetry) {
+        try {
+          await deps.eosRouteToRetry(rawMessages, envelopes, delay);
+          deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
+        } catch (txErr) {
+          deps.logger.error(
+            `EOS routing to retry topic failed \u2014 message will be redelivered:`,
+            toError(txErr).stack
+          );
+        }
+      } else {
+        await sendToRetryTopic(
+          topic2,
+          rawMessages,
+          1,
+          retry.maxRetries,
+          delay,
+          isBatch ? envelopes.map((e) => e.headers) : envelopes[0]?.headers ?? {},
+          deps
+        );
+        deps.onRetry?.(envelopes[0], 1, retry.maxRetries);
+      }
     } else if (isLastAttempt) {
       if (dlq) {
         for (let i = 0; i < rawMessages.length; i++) {
@@ -582,6 +615,7 @@ async function executeWithRetry(fn, ctx, deps) {
             attempt,
             originalHeaders: envelopes[i]?.headers
           });
+          deps.onDlq?.(envelopes[i] ?? envelopes[0], "handler-error");
         }
       } else {
         await deps.onMessageLost?.({
@@ -593,6 +627,7 @@ async function executeWithRetry(fn, ctx, deps) {
       }
     } else {
       const cap = Math.min(backoffMs * 2 ** (attempt - 1), maxBackoffMs);
+      deps.onRetry?.(envelopes[0], attempt, maxAttempts - 1);
       await sleep(Math.floor(Math.random() * cap));
     }
   }
@@ -616,6 +651,7 @@ async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
     deps.logger.warn(
       `Duplicate message on ${envelope.topic}[${envelope.partition}]: clock=${incomingClock} <= last=${lastProcessedClock} \u2014 strategy=${strategy}`
     );
+    deps.onDuplicate?.(envelope, strategy);
     if (strategy === "dlq" && dlq) {
       const augmentedHeaders = {
         ...envelope.headers,
@@ -670,6 +706,43 @@ async function handleEachMessage(payload, opts, deps) {
     timeoutMs,
     wrapWithTimeout
   } = opts;
+  const eos = opts.eosMainContext;
+  const nextOffsetStr = (parseInt(message.offset, 10) + 1).toString();
+  const commitOffset = eos ? async () => {
+    await eos.consumer.commitOffsets([
+      { topic: topic2, partition, offset: nextOffsetStr }
+    ]);
+  } : void 0;
+  const eosRouteToRetry = eos && retry ? async (rawMsgs, envelopes, delay) => {
+    const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
+      topic2,
+      rawMsgs,
+      1,
+      retry.maxRetries,
+      delay,
+      envelopes[0]?.headers ?? {}
+    );
+    const tx = await eos.txProducer.transaction();
+    try {
+      await tx.send({ topic: rtTopic, messages: rtMsgs });
+      await tx.sendOffsets({
+        consumer: eos.consumer,
+        topics: [
+          {
+            topic: topic2,
+            partitions: [{ partition, offset: nextOffsetStr }]
+          }
+        ]
+      });
+      await tx.commit();
+    } catch (txErr) {
+      try {
+        await tx.abort();
+      } catch {
+      }
+      throw txErr;
+    }
+  } : void 0;
   const envelope = await parseSingleMessage(
     message,
     topic2,
@@ -679,7 +752,10 @@ async function handleEachMessage(payload, opts, deps) {
     dlq,
     deps
   );
-  if (envelope === null) return;
+  if (envelope === null) {
+    await commitOffset?.();
+    return;
+  }
   if (opts.deduplication) {
     const isDuplicate = await applyDeduplication(
       envelope,
@@ -688,7 +764,10 @@ async function handleEachMessage(payload, opts, deps) {
       dlq,
       deps
     );
-    if (isDuplicate) return;
+    if (isDuplicate) {
+      await commitOffset?.();
+      return;
+    }
   }
   await executeWithRetry(
     () => {
@@ -709,7 +788,7 @@ async function handleEachMessage(payload, opts, deps) {
       retry,
       retryTopics
     },
-    deps
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitOffset }
   );
 }
 async function handleEachBatch(payload, opts, deps) {
@@ -724,6 +803,50 @@ async function handleEachBatch(payload, opts, deps) {
     timeoutMs,
     wrapWithTimeout
   } = opts;
+  const eos = opts.eosMainContext;
+  const lastRawOffset = batch.messages.length > 0 ? batch.messages[batch.messages.length - 1].offset : void 0;
+  const batchNextOffsetStr = lastRawOffset ? (parseInt(lastRawOffset, 10) + 1).toString() : void 0;
+  const commitBatchOffset = eos && batchNextOffsetStr ? async () => {
+    await eos.consumer.commitOffsets([
+      {
+        topic: batch.topic,
+        partition: batch.partition,
+        offset: batchNextOffsetStr
+      }
+    ]);
+  } : void 0;
+  const eosRouteToRetry = eos && retry && batchNextOffsetStr ? async (rawMsgs, envelopes2, delay) => {
+    const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
+      batch.topic,
+      rawMsgs,
+      1,
+      retry.maxRetries,
+      delay,
+      envelopes2.map((e) => e.headers)
+    );
+    const tx = await eos.txProducer.transaction();
+    try {
+      await tx.send({ topic: rtTopic, messages: rtMsgs });
+      await tx.sendOffsets({
+        consumer: eos.consumer,
+        topics: [
+          {
+            topic: batch.topic,
+            partitions: [
+              { partition: batch.partition, offset: batchNextOffsetStr }
+            ]
+          }
+        ]
+      });
+      await tx.commit();
+    } catch (txErr) {
+      try {
+        await tx.abort();
+      } catch {
+      }
+      throw txErr;
+    }
+  } : void 0;
   const envelopes = [];
   const rawMessages = [];
   for (const message of batch.messages) {
@@ -751,7 +874,10 @@ async function handleEachBatch(payload, opts, deps) {
     envelopes.push(envelope);
     rawMessages.push(message.value.toString());
   }
-  if (envelopes.length === 0) return;
+  if (envelopes.length === 0) {
+    await commitBatchOffset?.();
+    return;
+  }
   const meta = {
     partition: batch.partition,
     highWatermark: batch.highWatermark,
@@ -773,7 +899,7 @@ async function handleEachBatch(payload, opts, deps) {
       isBatch: true,
       retryTopics
     },
-    deps
+    { ...deps, eosRouteToRetry, eosCommitOnSuccess: commitBatchOffset }
   );
 }
 
@@ -819,6 +945,9 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
     producer,
     instrumentation,
     onMessageLost,
+    onRetry,
+    onDlq,
+    onMessage,
     ensureTopic,
     getOrCreateConsumer: getOrCreateConsumer2,
     runningConsumers,
@@ -900,6 +1029,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         instrumentation
       );
       if (!error) {
+        onMessage?.(envelope);
         await consumer.commitOffsets([nextOffset]);
         return;
       }
@@ -932,12 +1062,23 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
           await tx.send({ topic: rtTopic, messages: rtMsgs });
           await tx.sendOffsets({
             consumer,
-            topics: [{ topic: nextOffset.topic, partitions: [{ partition: nextOffset.partition, offset: nextOffset.offset }] }]
+            topics: [
+              {
+                topic: nextOffset.topic,
+                partitions: [
+                  {
+                    partition: nextOffset.partition,
+                    offset: nextOffset.offset
+                  }
+                ]
+              }
+            ]
           });
           await tx.commit();
           logger.warn(
             `Message routed to ${rtTopic} (EOS, level ${nextLevel}/${currentMaxRetries})`
           );
+          onRetry?.(envelope, nextLevel, currentMaxRetries);
         } catch (txErr) {
           try {
             await tx.abort();
@@ -965,10 +1106,21 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
           await tx.send({ topic: dTopic, messages: dMsgs });
           await tx.sendOffsets({
             consumer,
-            topics: [{ topic: nextOffset.topic, partitions: [{ partition: nextOffset.partition, offset: nextOffset.offset }] }]
+            topics: [
+              {
+                topic: nextOffset.topic,
+                partitions: [
+                  {
+                    partition: nextOffset.partition,
+                    offset: nextOffset.offset
+                  }
+                ]
+              }
+            ]
           });
           await tx.commit();
           logger.warn(`Message sent to DLQ: ${dTopic} (EOS)`);
+          onDlq?.(envelope, "handler-error");
         } catch (txErr) {
           try {
             await tx.abort();
@@ -992,7 +1144,12 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
     }
   });
   runningConsumers.set(levelGroupId, "eachMessage");
-  await waitForPartitionAssignment(consumer, levelTopics, logger, assignmentTimeoutMs);
+  await waitForPartitionAssignment(
+    consumer,
+    levelTopics,
+    logger,
+    assignmentTimeoutMs
+  );
   logger.log(
     `Retry level ${level}/${retry.maxRetries} consumer started for: ${originalTopics.join(", ")} (group: ${levelGroupId})`
   );
@@ -1022,7 +1179,8 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
 
 // src/client/kafka.client/index.ts
 var { Kafka: KafkaClass, logLevel: KafkaLogLevel } = import_kafka_javascript.KafkaJS;
-var KafkaClient = class {
+var _activeTransactionalIds = /* @__PURE__ */ new Set();
+var KafkaClient = class _KafkaClient {
   kafka;
   producer;
   txProducer;
@@ -1047,6 +1205,10 @@ var KafkaClient = class {
   instrumentation;
   onMessageLost;
   onRebalance;
+  /** Transactional producer ID — configurable via `KafkaClientOptions.transactionalId`. */
+  txId;
+  /** Per-topic event counters, lazily created on first event. Aggregated by `getMetrics()`. */
+  _topicMetrics = /* @__PURE__ */ new Map();
   /** Monotonically increasing Lamport clock stamped on every outgoing message. */
   _lamportClock = 0;
   /** Per-groupId deduplication state: `"topic:partition"` → last processed clock. */
@@ -1070,6 +1232,7 @@ var KafkaClient = class {
     this.instrumentation = options?.instrumentation ?? [];
     this.onMessageLost = options?.onMessageLost;
     this.onRebalance = options?.onRebalance;
+    this.txId = options?.transactionalId ?? `${clientId}-tx`;
     this.kafka = new KafkaClass({
       kafkaJS: {
         clientId: this.clientId,
@@ -1106,16 +1269,22 @@ var KafkaClient = class {
   /** Execute multiple sends atomically. Commits on success, aborts on error. */
   async transaction(fn) {
     if (!this.txProducerInitPromise) {
+      if (_activeTransactionalIds.has(this.txId)) {
+        this.logger.warn(
+          `transactionalId "${this.txId}" is already in use by another KafkaClient in this process. Kafka will fence one of the producers. Set a unique \`transactionalId\` (or distinct \`clientId\`) per instance.`
+        );
+      }
       const initPromise = (async () => {
         const p = this.kafka.producer({
           kafkaJS: {
             acks: -1,
             idempotent: true,
-            transactionalId: `${this.clientId}-tx`,
+            transactionalId: this.txId,
             maxInFlightRequests: 1
           }
         });
         await p.connect();
+        _activeTransactionalIds.add(this.txId);
         return p;
       })();
       this.txProducerInitPromise = initPromise.catch((err) => {
@@ -1183,10 +1352,20 @@ var KafkaClient = class {
         "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
       );
     }
-    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", options);
+    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachMessage", setupOptions);
     const deps = this.messageDeps;
     const timeoutMs = options.handlerTimeoutMs;
-    const deduplication = this.resolveDeduplicationContext(gid, options.deduplication);
+    const deduplication = this.resolveDeduplicationContext(
+      gid,
+      options.deduplication
+    );
+    let eosMainContext;
+    if (options.retryTopics && retry) {
+      const mainTxId = `${gid}-main-tx`;
+      const txProducer = await this.createRetryTxProducer(mainTxId);
+      eosMainContext = { txProducer, consumer };
+    }
     await consumer.run({
       eachMessage: (payload) => this.trackInFlight(
         () => handleEachMessage(
@@ -1200,7 +1379,8 @@ var KafkaClient = class {
             retryTopics: options.retryTopics,
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication
+            deduplication,
+            eosMainContext
           },
           deps
         )
@@ -1232,15 +1412,26 @@ var KafkaClient = class {
         "retryTopics requires retry to be configured \u2014 set retry.maxRetries to enable the retry topic chain"
       );
     }
-    if (options.autoCommit !== false) {
+    if (options.retryTopics) {
+    } else if (options.autoCommit !== false) {
       this.logger.debug?.(
         `startBatchConsumer: autoCommit is enabled (default true). If your handler calls resolveOffset() or commitOffsetsIfNecessary(), set autoCommit: false to avoid offset conflicts.`
       );
     }
-    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", options);
+    const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
+    const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry } = await this.setupConsumer(topics, "eachBatch", setupOptions);
     const deps = this.messageDeps;
     const timeoutMs = options.handlerTimeoutMs;
-    const deduplication = this.resolveDeduplicationContext(gid, options.deduplication);
+    const deduplication = this.resolveDeduplicationContext(
+      gid,
+      options.deduplication
+    );
+    let eosMainContext;
+    if (options.retryTopics && retry) {
+      const mainTxId = `${gid}-main-tx`;
+      const txProducer = await this.createRetryTxProducer(mainTxId);
+      eosMainContext = { txProducer, consumer };
+    }
     await consumer.run({
       eachBatch: (payload) => this.trackInFlight(
         () => handleEachBatch(
@@ -1254,7 +1445,8 @@ var KafkaClient = class {
             retryTopics: options.retryTopics,
             timeoutMs,
             wrapWithTimeout: this.wrapWithTimeoutWarning.bind(this),
-            deduplication
+            deduplication,
+            eosMainContext
           },
           deps
         )
@@ -1267,7 +1459,7 @@ var KafkaClient = class {
       }
       const handleMessageForRetry = (env) => handleBatch([env], {
         partition: env.partition,
-        highWatermark: env.offset,
+        highWatermark: null,
         heartbeat: async () => {
         },
         resolveOffset: () => {
@@ -1311,6 +1503,18 @@ var KafkaClient = class {
       this.consumerCreationOptions.delete(groupId);
       this.dedupStates.delete(groupId);
       this.logger.log(`Consumer disconnected: group "${groupId}"`);
+      const mainTxId = `${groupId}-main-tx`;
+      const mainTxProducer = this.retryTxProducers.get(mainTxId);
+      if (mainTxProducer) {
+        await mainTxProducer.disconnect().catch(
+          (e) => this.logger.warn(
+            `Error disconnecting main tx producer "${mainTxId}":`,
+            toError(e).message
+          )
+        );
+        _activeTransactionalIds.delete(mainTxId);
+        this.retryTxProducers.delete(mainTxId);
+      }
       const companions = this.companionGroupIds.get(groupId) ?? [];
       for (const cGroupId of companions) {
         const cConsumer = this.consumers.get(cGroupId);
@@ -1335,6 +1539,7 @@ var KafkaClient = class {
               toError(e).message
             )
           );
+          _activeTransactionalIds.delete(txId);
           this.retryTxProducers.delete(txId);
         }
       }
@@ -1360,6 +1565,144 @@ var KafkaClient = class {
       this.logger.log("All consumers disconnected");
     }
   }
+  pauseConsumer(groupId, assignments) {
+    const gid = groupId ?? this.defaultGroupId;
+    const consumer = this.consumers.get(gid);
+    if (!consumer) {
+      this.logger.warn(`pauseConsumer: no active consumer for group "${gid}"`);
+      return;
+    }
+    consumer.pause(
+      assignments.flatMap(
+        ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+      )
+    );
+  }
+  resumeConsumer(groupId, assignments) {
+    const gid = groupId ?? this.defaultGroupId;
+    const consumer = this.consumers.get(gid);
+    if (!consumer) {
+      this.logger.warn(`resumeConsumer: no active consumer for group "${gid}"`);
+      return;
+    }
+    consumer.resume(
+      assignments.flatMap(
+        ({ topic: topic2, partitions }) => partitions.map((p) => ({ topic: topic2, partitions: [p] }))
+      )
+    );
+  }
+  /** DLQ header keys added by `sendToDlq` — stripped before re-publishing. */
+  static DLQ_HEADER_KEYS = /* @__PURE__ */ new Set([
+    "x-dlq-original-topic",
+    "x-dlq-failed-at",
+    "x-dlq-error-message",
+    "x-dlq-error-stack",
+    "x-dlq-attempt-count"
+  ]);
+  async replayDlq(topic2, options = {}) {
+    const dlqTopic = `${topic2}.dlq`;
+    await this.ensureAdminConnected();
+    const partitionOffsets = await this.admin.fetchTopicOffsets(dlqTopic);
+    const activePartitions = partitionOffsets.filter(
+      (p) => parseInt(p.high, 10) > 0
+    );
+    if (activePartitions.length === 0) {
+      this.logger.log(`replayDlq: "${dlqTopic}" is empty \u2014 nothing to replay`);
+      return { replayed: 0, skipped: 0 };
+    }
+    const highWatermarks = new Map(
+      activePartitions.map(({ partition, high }) => [
+        partition,
+        parseInt(high, 10)
+      ])
+    );
+    const processedOffsets = /* @__PURE__ */ new Map();
+    let replayed = 0;
+    let skipped = 0;
+    const tempGroupId = `${dlqTopic}-replay-${Date.now()}`;
+    await new Promise((resolve, reject) => {
+      const consumer = getOrCreateConsumer(
+        tempGroupId,
+        true,
+        true,
+        this.consumerOpsDeps
+      );
+      const cleanup = () => {
+        consumer.disconnect().catch(() => {
+        }).finally(() => {
+          this.consumers.delete(tempGroupId);
+          this.runningConsumers.delete(tempGroupId);
+          this.consumerCreationOptions.delete(tempGroupId);
+        });
+      };
+      consumer.connect().then(
+        () => subscribeWithRetry(consumer, [dlqTopic], this.logger)
+      ).then(
+        () => consumer.run({
+          eachMessage: async ({ partition, message }) => {
+            if (!message.value) return;
+            const offset = parseInt(message.offset, 10);
+            processedOffsets.set(partition, offset);
+            const headers = decodeHeaders(message.headers);
+            const targetTopic = options.targetTopic ?? headers["x-dlq-original-topic"];
+            const originalHeaders = Object.fromEntries(
+              Object.entries(headers).filter(
+                ([k]) => !_KafkaClient.DLQ_HEADER_KEYS.has(k)
+              )
+            );
+            const value = message.value.toString();
+            const shouldProcess = !options.filter || options.filter(headers, value);
+            if (!targetTopic || !shouldProcess) {
+              skipped++;
+            } else if (options.dryRun) {
+              this.logger.log(
+                `[DLQ replay dry-run] Would replay to "${targetTopic}"`
+              );
+              replayed++;
+            } else {
+              await this.producer.send({
+                topic: targetTopic,
+                messages: [{ value, headers: originalHeaders }]
+              });
+              replayed++;
+            }
+            const allDone = Array.from(highWatermarks.entries()).every(
+              ([p, hwm]) => (processedOffsets.get(p) ?? -1) >= hwm - 1
+            );
+            if (allDone) {
+              cleanup();
+              resolve();
+            }
+          }
+        })
+      ).catch((err) => {
+        cleanup();
+        reject(err);
+      });
+    });
+    this.logger.log(
+      `replayDlq: replayed ${replayed}, skipped ${skipped} from "${dlqTopic}"`
+    );
+    return { replayed, skipped };
+  }
+  async resetOffsets(groupId, topic2, position) {
+    const gid = groupId ?? this.defaultGroupId;
+    if (this.runningConsumers.has(gid)) {
+      throw new Error(
+        `resetOffsets: consumer group "${gid}" is still running. Call stopConsumer("${gid}") before resetting offsets.`
+      );
+    }
+    await this.ensureAdminConnected();
+    const partitionOffsets = await this.admin.fetchTopicOffsets(topic2);
+    const partitions = partitionOffsets.map(({ partition, low, high }) => ({
+      partition,
+      offset: position === "earliest" ? low : high
+    }));
+    await this.admin.setOffsets({ groupId: gid, topic: topic2, partitions });
+    this.logger.log(
+      `Offsets reset to ${position} for group "${gid}" on topic "${topic2}"`
+    );
+  }
   /**
    * Query consumer group lag per partition.
    * Lag = broker high-watermark − last committed offset.
@@ -1410,15 +1753,45 @@ var KafkaClient = class {
   getClientId() {
     return this.clientId;
   }
+  getMetrics(topic2) {
+    if (topic2 !== void 0) {
+      const m = this._topicMetrics.get(topic2);
+      return m ? { ...m } : { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
+    }
+    const agg = {
+      processedCount: 0,
+      retryCount: 0,
+      dlqCount: 0,
+      dedupCount: 0
+    };
+    for (const m of this._topicMetrics.values()) {
+      agg.processedCount += m.processedCount;
+      agg.retryCount += m.retryCount;
+      agg.dlqCount += m.dlqCount;
+      agg.dedupCount += m.dedupCount;
+    }
+    return agg;
+  }
+  resetMetrics(topic2) {
+    if (topic2 !== void 0) {
+      this._topicMetrics.delete(topic2);
+      return;
+    }
+    this._topicMetrics.clear();
+  }
   /** Gracefully disconnect producer, all consumers, and admin. */
   async disconnect(drainTimeoutMs = 3e4) {
     await this.waitForDrain(drainTimeoutMs);
     const tasks = [this.producer.disconnect()];
     if (this.txProducer) {
       tasks.push(this.txProducer.disconnect());
+      _activeTransactionalIds.delete(this.txId);
       this.txProducer = void 0;
       this.txProducerInitPromise = void 0;
     }
+    for (const txId of this.retryTxProducers.keys()) {
+      _activeTransactionalIds.delete(txId);
+    }
     for (const p of this.retryTxProducers.values()) {
       tasks.push(p.disconnect());
     }
@@ -1514,6 +1887,38 @@ var KafkaClient = class {
       }
     }
   }
+  metricsFor(topic2) {
+    let m = this._topicMetrics.get(topic2);
+    if (!m) {
+      m = { processedCount: 0, retryCount: 0, dlqCount: 0, dedupCount: 0 };
+      this._topicMetrics.set(topic2, m);
+    }
+    return m;
+  }
+  notifyRetry(envelope, attempt, maxRetries) {
+    this.metricsFor(envelope.topic).retryCount++;
+    for (const inst of this.instrumentation) {
+      inst.onRetry?.(envelope, attempt, maxRetries);
+    }
+  }
+  notifyDlq(envelope, reason) {
+    this.metricsFor(envelope.topic).dlqCount++;
+    for (const inst of this.instrumentation) {
+      inst.onDlq?.(envelope, reason);
+    }
+  }
+  notifyDuplicate(envelope, strategy) {
+    this.metricsFor(envelope.topic).dedupCount++;
+    for (const inst of this.instrumentation) {
+      inst.onDuplicate?.(envelope, strategy);
+    }
+  }
+  notifyMessage(envelope) {
+    this.metricsFor(envelope.topic).processedCount++;
+    for (const inst of this.instrumentation) {
+      inst.onMessage?.(envelope);
+    }
+  }
   /**
    * 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.
@@ -1603,6 +2008,11 @@ var KafkaClient = class {
    * so Kafka can fence stale producers on restart without affecting other levels.
    */
   async createRetryTxProducer(transactionalId) {
+    if (_activeTransactionalIds.has(transactionalId)) {
+      this.logger.warn(
+        `transactionalId "${transactionalId}" is already in use by another KafkaClient in this process. Kafka will fence one of the producers. Set a unique \`transactionalId\` (or distinct \`clientId\`) per instance.`
+      );
+    }
     const p = this.kafka.producer({
       kafkaJS: {
         acks: -1,
@@ -1612,6 +2022,7 @@ var KafkaClient = class {
       }
     });
     await p.connect();
+    _activeTransactionalIds.add(transactionalId);
     this.retryTxProducers.set(transactionalId, p);
     return p;
   }
@@ -1732,7 +2143,11 @@ var KafkaClient = class {
       logger: this.logger,
       producer: this.producer,
       instrumentation: this.instrumentation,
-      onMessageLost: this.onMessageLost
+      onMessageLost: this.onMessageLost,
+      onRetry: this.notifyRetry.bind(this),
+      onDlq: this.notifyDlq.bind(this),
+      onDuplicate: this.notifyDuplicate.bind(this),
+      onMessage: this.notifyMessage.bind(this)
     };
   }
   get retryTopicDeps() {
@@ -1741,6 +2156,9 @@ var KafkaClient = class {
       producer: this.producer,
       instrumentation: this.instrumentation,
       onMessageLost: this.onMessageLost,
+      onRetry: this.notifyRetry.bind(this),
+      onDlq: this.notifyDlq.bind(this),
+      onMessage: this.notifyMessage.bind(this),
       ensureTopic: (t) => this.ensureTopic(t),
       getOrCreateConsumer: (gid, fb, ac) => getOrCreateConsumer(gid, fb, ac, this.consumerOpsDeps),
       runningConsumers: this.runningConsumers,