@drarzter/kafka-client 0.9.4 → 0.10.0

package/dist/core.js

@@ -21,31 +21,50 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var core_exports = {};
 __export(core_exports, {
   HEADER_CORRELATION_ID: () => HEADER_CORRELATION_ID,
+  HEADER_DELAYED_TARGET: () => HEADER_DELAYED_TARGET,
+  HEADER_DELAYED_UNTIL: () => HEADER_DELAYED_UNTIL,
   HEADER_EVENT_ID: () => HEADER_EVENT_ID,
   HEADER_LAMPORT_CLOCK: () => HEADER_LAMPORT_CLOCK,
   HEADER_SCHEMA_VERSION: () => HEADER_SCHEMA_VERSION,
   HEADER_TIMESTAMP: () => HEADER_TIMESTAMP,
   HEADER_TRACEPARENT: () => HEADER_TRACEPARENT,
+  InMemoryDedupStore: () => InMemoryDedupStore,
+  InMemoryOutboxStore: () => InMemoryOutboxStore,
   KafkaClient: () => KafkaClient,
   KafkaProcessingError: () => KafkaProcessingError,
   KafkaRetryExhaustedError: () => KafkaRetryExhaustedError,
   KafkaValidationError: () => KafkaValidationError,
+  SchemaRegistryClient: () => SchemaRegistryClient,
+  awsMskIamProvider: () => awsMskIamProvider,
   buildEnvelopeHeaders: () => buildEnvelopeHeaders,
+  consumerOptionsFromEnv: () => consumerOptionsFromEnv,
   decodeHeaders: () => decodeHeaders,
+  describeRequiredAcls: () => describeRequiredAcls,
   extractEnvelope: () => extractEnvelope,
+  gcpAccessTokenProvider: () => gcpAccessTokenProvider,
   getEnvelopeContext: () => getEnvelopeContext,
+  kafkaClientConfigFromEnv: () => kafkaClientConfigFromEnv,
+  mergeConsumerOptions: () => mergeConsumerOptions,
+  registrySchema: () => registrySchema,
+  resolveSecurityOptions: () => resolveSecurityOptions,
   runWithEnvelopeContext: () => runWithEnvelopeContext,
-  topic: () => topic
+  startOutboxRelay: () => startOutboxRelay,
+  toError: () => toError,
+  toKafkaAclCommands: () => toKafkaAclCommands,
+  toMskIamPolicy: () => toMskIamPolicy,
+  topic: () => topic,
+  versionedSchema: () => versionedSchema
 });
 module.exports = __toCommonJS(core_exports);
 
-// src/client/kafka.client/confluent-transport.ts
+// src/client/transport/confluent.transport.ts
 var import_kafka_javascript = require("@confluentinc/kafka-javascript");
 var { Kafka: KafkaClass, logLevel: KafkaLogLevel, PartitionAssigners } = import_kafka_javascript.KafkaJS;
 var ConfluentTransaction = class {
   constructor(tx) {
     this.tx = tx;
   }
+  tx;
   async send(record) {
     await this.tx.send(record);
   }
@@ -67,10 +86,17 @@ var ConfluentProducer = class {
   constructor(producer) {
     this.producer = producer;
   }
+  producer;
+  connectPromise;
   async connect() {
-    await this.producer.connect();
+    this.connectPromise ??= this.producer.connect().catch((err) => {
+      this.connectPromise = void 0;
+      throw err;
+    });
+    return this.connectPromise;
   }
   async disconnect() {
+    this.connectPromise = void 0;
     await this.producer.disconnect();
   }
   async send(record) {
@@ -85,6 +111,7 @@ var ConfluentConsumer = class {
   constructor(consumer) {
     this.consumer = consumer;
   }
+  consumer;
   /** Returns the underlying KafkaJS.Consumer — used by ConfluentTransaction.sendOffsets. */
   getNative() {
     return this.consumer;
@@ -124,6 +151,7 @@ var ConfluentAdmin = class {
   constructor(admin) {
     this.admin = admin;
   }
+  admin;
   async connect() {
     await this.admin.connect();
   }
@@ -137,7 +165,7 @@ var ConfluentAdmin = class {
     return this.admin.fetchTopicOffsets(topic2);
   }
   async fetchTopicOffsetsByTimestamp(topic2, timestamp) {
-    return this.admin.fetchTopicOffsetsByTime(topic2, timestamp);
+    return this.admin.fetchTopicOffsetsByTimestamp(topic2, timestamp);
   }
   async fetchOffsets(options) {
     return this.admin.fetchOffsets(options);
@@ -163,10 +191,29 @@ var ConfluentAdmin = class {
 };
 var ConfluentTransport = class {
   kafka;
-  constructor(clientId, brokers) {
-    this.kafka = new KafkaClass({
-      kafkaJS: { clientId, brokers, logLevel: KafkaLogLevel.ERROR }
-    });
+  constructor(clientId, brokers, security) {
+    const kafkaJS = { clientId, brokers, logLevel: KafkaLogLevel.ERROR };
+    if (security?.ssl !== void 0) kafkaJS.ssl = security.ssl;
+    if (security?.sasl) {
+      if (security.sasl.mechanism === "oauthbearer") {
+        const provider = security.sasl.oauthBearerProvider;
+        kafkaJS.sasl = {
+          mechanism: "oauthbearer",
+          oauthBearerProvider: async () => {
+            const token = await provider();
+            return {
+              value: token.value,
+              principal: token.principal ?? "kafka-client",
+              lifetime: token.lifetimeMs ?? Date.now() + 15 * 6e4,
+              ...token.extensions && { extensions: token.extensions }
+            };
+          }
+        };
+      } else {
+        kafkaJS.sasl = security.sasl;
+      }
+    }
+    this.kafka = new KafkaClass({ kafkaJS });
   }
   producer(options) {
     const native = this.kafka.producer({
@@ -193,6 +240,9 @@ var ConfluentTransport = class {
         partitionAssigners: [assigner]
       }
     };
+    if (options.groupInstanceId) {
+      config["group.instance.id"] = options.groupInstanceId;
+    }
     if (options.onRebalance) {
       const cb = options.onRebalance;
       config.rebalance_cb = (err, assignment) => {
@@ -210,6 +260,25 @@ var ConfluentTransport = class {
   }
 };
 
+// src/client/kafka.client/infra/dedup.store.ts
+var InMemoryDedupStore = class {
+  constructor(states) {
+    this.states = states;
+  }
+  states;
+  getLastClock(groupId, topicPartition) {
+    return this.states.get(groupId)?.get(topicPartition);
+  }
+  setLastClock(groupId, topicPartition, clock) {
+    let group = this.states.get(groupId);
+    if (!group) {
+      group = /* @__PURE__ */ new Map();
+      this.states.set(groupId, group);
+    }
+    group.set(topicPartition, clock);
+  }
+};
+
 // src/client/message/envelope.ts
 var import_node_async_hooks = require("async_hooks");
 var import_node_crypto = require("crypto");
@@ -219,6 +288,8 @@ var HEADER_TIMESTAMP = "x-timestamp";
 var HEADER_SCHEMA_VERSION = "x-schema-version";
 var HEADER_TRACEPARENT = "traceparent";
 var HEADER_LAMPORT_CLOCK = "x-lamport-clock";
+var HEADER_DELAYED_UNTIL = "x-delayed-until";
+var HEADER_DELAYED_TARGET = "x-delayed-target";
 var envelopeStorage = new import_node_async_hooks.AsyncLocalStorage();
 function getEnvelopeContext() {
   return envelopeStorage.getStore();
@@ -273,6 +344,9 @@ function extractEnvelope(payload, headers, topic2, partition, offset) {
 }
 
 // src/client/errors.ts
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
 var KafkaProcessingError = class extends Error {
   constructor(message, topic2, originalMessage, options) {
     super(message, options);
@@ -281,6 +355,8 @@ var KafkaProcessingError = class extends Error {
     this.name = "KafkaProcessingError";
     if (options?.cause) this.cause = options.cause;
   }
+  topic;
+  originalMessage;
 };
 var KafkaValidationError = class extends Error {
   constructor(topic2, originalMessage, options) {
@@ -290,6 +366,8 @@ var KafkaValidationError = class extends Error {
     this.name = "KafkaValidationError";
     if (options?.cause) this.cause = options.cause;
   }
+  topic;
+  originalMessage;
 };
 var KafkaRetryExhaustedError = class extends KafkaProcessingError {
   constructor(topic2, originalMessage, attempts, options) {
@@ -302,6 +380,7 @@ var KafkaRetryExhaustedError = class extends KafkaProcessingError {
     this.attempts = attempts;
     this.name = "KafkaRetryExhaustedError";
   }
+  attempts;
 };
 
 // src/client/kafka.client/producer/ops.ts
@@ -374,7 +453,9 @@ async function buildSendPayload(topicOrDesc, messages, deps, compression) {
         value: JSON.stringify(
           await validateMessage(topicOrDesc, m.value, deps, sendCtx)
         ),
-        key: m.key ?? null,
+        // Explicit key wins; otherwise fall back to the descriptor's .key()
+        // extractor (runs on the original, pre-validation payload).
+        key: m.key ?? topicOrDesc?.__key?.(m.value) ?? null,
         headers: envelopeHeaders
       };
     })
@@ -383,7 +464,7 @@ async function buildSendPayload(topicOrDesc, messages, deps, compression) {
 }
 
 // src/client/kafka.client/consumer/ops.ts
-function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partitionAssigner, onFirstAssignment) {
+function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partitionAssigner, onFirstAssignment, groupInstanceId) {
   const { consumers, consumerCreationOptions, transport, onRebalance, logger } = deps;
   if (consumers.has(groupId)) {
     const prev = consumerCreationOptions.get(groupId);
@@ -416,6 +497,7 @@ function getOrCreateConsumer(groupId, fromBeginning, autoCommit, deps, partition
     fromBeginning,
     autoCommit,
     partitionAssigner: partitionAssigner ?? "cooperative-sticky",
+    groupInstanceId,
     onRebalance: (type, assignments) => {
       if (type === "assign") fireOnAssignment();
       else if (type === "revoke") scheduleSettle();
@@ -461,6 +543,7 @@ var AdminOps = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   isConnected = false;
   /** Underlying admin client — used by index.ts for topic validation. */
   get admin() {
@@ -567,7 +650,10 @@ var AdminOps = class {
           const found = results.find(
             (r) => r.partition === partition
           );
-          return { partition, offset: found?.offset ?? "-1" };
+          if (found) return { partition, offset: found.offset };
+          const topicOffsets = await this.deps.admin.fetchTopicOffsets(topic2);
+          const po = topicOffsets.find((o) => o.partition === partition);
+          return { partition, offset: po?.high ?? "0" };
         })
       );
       await this.deps.admin.setOffsets({ groupId: gid, topic: topic2, partitions: offsets });
@@ -648,7 +734,8 @@ var AdminOps = class {
       name: t.name,
       partitions: t.partitions.map((p) => ({
         partition: p.partitionId ?? p.partition ?? 0,
-        leader: p.leader ?? 0,
+        // -1 is Kafka's own "no leader" sentinel; 0 is a valid broker id
+        leader: p.leader ?? -1,
         replicas: (p.replicas ?? []).map(
           (r) => typeof r === "number" ? r : r.nodeId
         ),
@@ -732,9 +819,6 @@ var AdminOps = class {
 };
 
 // src/client/kafka.client/consumer/pipeline.ts
-function toError(error) {
-  return error instanceof Error ? error : new Error(String(error));
-}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1018,6 +1102,7 @@ async function executeWithRetry(fn, ctx, deps) {
       for (const env of envelopes) deps.onMessage?.(env);
       return;
     }
+    deps.onFailure?.(envelopes[0]);
     const isLastAttempt = attempt === maxAttempts;
     const reportedError = isLastAttempt && maxAttempts > 1 ? new KafkaRetryExhaustedError(
       topic2,
@@ -1102,8 +1187,13 @@ async function subscribeWithRetry(consumer, topics, logger, retryOpts) {
   }
 }
 
-// src/client/kafka.client/consumer/dlq-replay.ts
+// src/client/kafka.client/consumer/features/dlq-replay.ts
 async function replayDlqTopic(topic2, deps, options = {}) {
+  if (topic2.endsWith(".dlq")) {
+    throw new Error(
+      `replayDlq: pass the ORIGINAL topic name \u2014 "${topic2}" already ends in ".dlq" (the ".dlq" suffix is appended internally, so this would read "${topic2}.dlq")`
+    );
+  }
   const dlqTopic = `${topic2}.dlq`;
   const partitionOffsets = await deps.fetchTopicOffsets(dlqTopic);
   const activePartitions = partitionOffsets.filter(
@@ -1169,6 +1259,7 @@ var MetricsManager = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   topicMetrics = /* @__PURE__ */ new Map();
   metricsFor(topic2) {
     let m = this.topicMetrics.get(topic2);
@@ -1194,16 +1285,25 @@ var MetricsManager = class {
     for (const inst of this.deps.instrumentation) inst.onRetry?.(envelope, attempt, maxRetries);
   }
   /**
-   * Increment the DLQ counter for the envelope's topic, fire all `onDlq` instrumentation hooks,
-   * and notify the circuit breaker of a failure (when `gid` is provided).
+   * 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.
-   * @param gid Consumer group ID — used to drive circuit breaker state.
    */
-  notifyDlq(envelope, reason, gid) {
+  notifyDlq(envelope, reason) {
     this.metricsFor(envelope.topic).dlqCount++;
     for (const inst of this.deps.instrumentation) inst.onDlq?.(envelope, reason);
-    if (gid) this.deps.onCircuitFailure(envelope, gid);
+  }
+  /**
+   * 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, gid) {
+    this.deps.onCircuitFailure(envelope, gid);
   }
   /**
    * Increment the deduplication counter for the envelope's topic and fire all `onDuplicate` hooks.
@@ -1262,6 +1362,7 @@ var InFlightTracker = class {
   constructor(warn) {
     this.warn = warn;
   }
+  warn;
   inFlightTotal = 0;
   drainResolvers = [];
   /**
@@ -1272,10 +1373,16 @@ var InFlightTracker = class {
    */
   track(fn) {
     this.inFlightTotal++;
-    return fn().finally(() => {
+    const done = () => {
       this.inFlightTotal--;
       if (this.inFlightTotal === 0) this.drainResolvers.splice(0).forEach((r) => r());
-    });
+    };
+    try {
+      return fn().finally(done);
+    } catch (err) {
+      done();
+      throw err;
+    }
   }
   /**
    * Resolve when all tracked handlers have completed, or after `timeoutMs` elapses.
@@ -1309,6 +1416,7 @@ var CircuitBreakerManager = class {
   constructor(deps) {
     this.deps = deps;
   }
+  deps;
   states = /* @__PURE__ */ new Map();
   configs = /* @__PURE__ */ new Map();
   /**
@@ -1453,6 +1561,9 @@ var AsyncQueue = class {
     this.onFull = onFull;
     this.onDrained = onDrained;
   }
+  highWaterMark;
+  onFull;
+  onDrained;
   items = [];
   waiting = [];
   closed = false;
@@ -1464,6 +1575,7 @@ var AsyncQueue = class {
    * @param item The value to enqueue.
    */
   push(item) {
+    if (this.closed) return;
     if (this.waiting.length > 0) {
       this.waiting.shift().resolve({ value: item, done: false });
     } else {
@@ -1514,6 +1626,101 @@ var AsyncQueue = class {
   }
 };
 
+// src/client/kafka.client/validate-options.ts
+function validateClientOptions(clientId, groupId, brokers, options) {
+  const problems = [];
+  if (typeof clientId !== "string" || clientId.trim() === "") {
+    problems.push("clientId must be a non-empty string");
+  }
+  if (typeof groupId !== "string" || groupId.trim() === "") {
+    problems.push("groupId must be a non-empty string");
+  }
+  if (!Array.isArray(brokers) || brokers.length === 0 && !options?.transport) {
+    problems.push("brokers must be a non-empty array of broker addresses");
+  } else if (brokers.some((b) => typeof b !== "string" || b.trim() === "")) {
+    problems.push("brokers must not contain empty entries");
+  }
+  if (options) {
+    const {
+      numPartitions,
+      transactionalId,
+      clockRecovery,
+      lagThrottle
+    } = options;
+    if (numPartitions !== void 0 && (!Number.isInteger(numPartitions) || numPartitions < 1)) {
+      problems.push(
+        `numPartitions must be a positive integer (got ${numPartitions})`
+      );
+    }
+    if (transactionalId !== void 0 && transactionalId.trim() === "") {
+      problems.push("transactionalId must be a non-empty string when set");
+    }
+    if (clockRecovery) {
+      if (!Array.isArray(clockRecovery.topics)) {
+        problems.push("clockRecovery.topics must be an array of topic names");
+      }
+      if (clockRecovery.timeoutMs !== void 0 && !(clockRecovery.timeoutMs > 0)) {
+        problems.push(
+          `clockRecovery.timeoutMs must be > 0 (got ${clockRecovery.timeoutMs})`
+        );
+      }
+    }
+    if (lagThrottle) {
+      if (!(lagThrottle.maxLag >= 0)) {
+        problems.push(`lagThrottle.maxLag must be >= 0 (got ${lagThrottle.maxLag})`);
+      }
+      if (lagThrottle.pollIntervalMs !== void 0 && !(lagThrottle.pollIntervalMs > 0)) {
+        problems.push(
+          `lagThrottle.pollIntervalMs must be > 0 (got ${lagThrottle.pollIntervalMs})`
+        );
+      }
+      if (lagThrottle.maxWaitMs !== void 0 && !(lagThrottle.maxWaitMs >= 0)) {
+        problems.push(
+          `lagThrottle.maxWaitMs must be >= 0 (got ${lagThrottle.maxWaitMs})`
+        );
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `KafkaClient: invalid configuration:
+- ${problems.join("\n- ")}`
+    );
+  }
+}
+
+// src/client/security/resolve-security.ts
+var LOCAL_HOST_PATTERNS = [
+  /^localhost(:\d+)?$/i,
+  /^127\.\d+\.\d+\.\d+(:\d+)?$/,
+  /^\[?::1\]?(:\d+)?$/,
+  /^0\.0\.0\.0(:\d+)?$/,
+  /^host\.docker\.internal(:\d+)?$/i
+];
+function isLocalBroker(broker) {
+  return LOCAL_HOST_PATTERNS.some((re) => re.test(broker.trim()));
+}
+function resolveSecurityOptions(security, brokers, logger) {
+  const hasRemoteBroker = brokers.some((b) => !isLocalBroker(b));
+  if (!security?.sasl && security?.ssl !== true) {
+    if (hasRemoteBroker && !security?.allowInsecure) {
+      logger.warn(
+        "Connecting to non-local brokers without TLS or SASL \u2014 traffic and payloads travel in plaintext. Configure `security: { ssl, sasl }` for production clusters, or set `security: { allowInsecure: true }` to acknowledge an intentionally insecure setup."
+      );
+    }
+    return security;
+  }
+  if (security.sasl && security.ssl === void 0) {
+    return { ...security, ssl: true };
+  }
+  if (security.sasl && security.ssl === false) {
+    logger.warn(
+      "SASL credentials are configured with `ssl: false` \u2014 credentials will be sent over plaintext. This is only safe on fully trusted networks."
+    );
+  }
+  return security;
+}
+
 // src/client/kafka.client/producer/lifecycle.ts
 var _activeTransactionalIds = /* @__PURE__ */ new Set();
 async function ensureTopic(ctx, topic2) {
@@ -1647,6 +1854,7 @@ async function recoverLamportClockImpl(ctx, topics) {
     const remaining = new Set(
       partitionsToRead.map((p) => `${p.topic}:${p.partition}`)
     );
+    let settled = false;
     const cleanup = () => {
       consumer.disconnect().catch(() => {
       }).finally(() => {
@@ -1654,6 +1862,16 @@ async function recoverLamportClockImpl(ctx, topics) {
         });
       });
     };
+    const timeoutTimer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      ctx.logger.warn(
+        `Clock recovery: timed out after ${ctx.clockRecoveryTimeoutMs} ms with ${remaining.size} partition(s) unread \u2014 proceeding with partial result`
+      );
+      cleanup();
+      resolve();
+    }, ctx.clockRecoveryTimeoutMs);
+    timeoutTimer.unref?.();
     consumer.connect().then(async () => {
       const uniqueTopics = [
         ...new Set(partitionsToRead.map((p) => p.topic))
@@ -1674,13 +1892,18 @@ async function recoverLamportClockImpl(ctx, topics) {
             const clock = Number(raw);
             if (!Number.isNaN(clock) && clock > maxClock) maxClock = clock;
           }
-          if (remaining.size === 0) {
+          if (remaining.size === 0 && !settled) {
+            settled = true;
+            clearTimeout(timeoutTimer);
             cleanup();
             resolve();
           }
         }
       })
     ).catch((err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
       cleanup();
       reject(err);
     });
@@ -1721,6 +1944,15 @@ async function preparePayload(ctx, topicOrDesc, messages, compression) {
   await ensureTopic(ctx, payload.topic);
   return payload;
 }
+async function redirectToDelayed(ctx, payload, deliverAfterMs) {
+  const until = String(Date.now() + deliverAfterMs);
+  for (const m of payload.messages) {
+    m.headers[HEADER_DELAYED_UNTIL] = until;
+    m.headers[HEADER_DELAYED_TARGET] = payload.topic;
+  }
+  payload.topic = `${payload.topic}.delayed`;
+  await ensureTopic(ctx, payload.topic);
+}
 async function sendMessageImpl(ctx, topicOrDesc, message, options = {}) {
   await waitIfThrottled(ctx);
   const payload = await preparePayload(
@@ -1738,6 +1970,9 @@ async function sendMessageImpl(ctx, topicOrDesc, message, options = {}) {
     ],
     options.compression
   );
+  if (options.deliverAfterMs && options.deliverAfterMs > 0) {
+    await redirectToDelayed(ctx, payload, options.deliverAfterMs);
+  }
   await ctx.producer.send(payload);
   ctx.metrics.notifyAfterSend(payload.topic, payload.messages.length);
 }
@@ -1749,6 +1984,9 @@ async function sendBatchImpl(ctx, topicOrDesc, messages, options) {
     messages,
     options?.compression
   );
+  if (options?.deliverAfterMs && options.deliverAfterMs > 0) {
+    await redirectToDelayed(ctx, payload, options.deliverAfterMs);
+  }
   await ctx.producer.send(payload);
   ctx.metrics.notifyAfterSend(payload.topic, payload.messages.length);
 }
@@ -1785,6 +2023,17 @@ async function transactionImpl(ctx, fn) {
     });
   }
   ctx.txProducer = await ctx.txProducerInitPromise;
+  const prev = ctx._txChain;
+  let release;
+  ctx._txChain = new Promise((r) => release = r);
+  await prev;
+  try {
+    await runTransaction(ctx, fn);
+  } finally {
+    release();
+  }
+}
+async function runTransaction(ctx, fn) {
   const tx = await ctx.txProducer.transaction();
   try {
     const txCtx = {
@@ -1952,6 +2201,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         await consumer.commitOffsets([nextOffset]);
         return;
       }
+      deps.onFailure?.(envelope);
       const exhausted = level >= currentMaxRetries;
       const reportedError = exhausted && currentMaxRetries > 1 ? new KafkaRetryExhaustedError(
         originalTopic,
@@ -2167,7 +2417,8 @@ async function setupConsumer(ctx, topics, mode, options) {
     options.autoCommit ?? true,
     ctx.consumerOpsDeps,
     options.partitionAssigner,
-    resolveReady
+    resolveReady,
+    options.groupInstanceId
   );
   const schemaMap = buildSchemaMap(
     stringTopics,
@@ -2179,6 +2430,9 @@ async function setupConsumer(ctx, topics, mode, options) {
   const subscribeTopics = [...topicNames, ...regexTopics];
   await ensureConsumerTopics(ctx, topicNames, dlq, options.deduplication);
   await consumer.connect();
+  if (dlq || options.retryTopics || options.deduplication) {
+    await ctx.producer.connect();
+  }
   await subscribeWithRetry(
     consumer,
     subscribeTopics,
@@ -2193,9 +2447,8 @@ async function setupConsumer(ctx, topics, mode, options) {
 }
 function resolveDeduplicationContext(ctx, groupId, options) {
   if (!options) return void 0;
-  if (!ctx.dedupStates.has(groupId))
-    ctx.dedupStates.set(groupId, /* @__PURE__ */ new Map());
-  return { options, state: ctx.dedupStates.get(groupId) };
+  const store = options.store ?? new InMemoryDedupStore(ctx.dedupStates);
+  return { options, store, groupId };
 }
 function messageDepsFor(ctx, gid, options) {
   const notifyRetry = ctx.metrics.notifyRetry.bind(ctx.metrics);
@@ -2209,9 +2462,10 @@ function messageDepsFor(ctx, gid, options) {
       notifyRetry(envelope, attempt, max);
       return options.onRetry(envelope, attempt, max);
     } : notifyRetry,
-    onDlq: (envelope, reason) => ctx.metrics.notifyDlq(envelope, reason, gid),
+    onDlq: (envelope, reason) => ctx.metrics.notifyDlq(envelope, reason),
     onDuplicate: ctx.metrics.notifyDuplicate.bind(ctx.metrics),
-    onMessage: (envelope) => ctx.metrics.notifyMessage(envelope, gid)
+    onMessage: (envelope) => ctx.metrics.notifyMessage(envelope, gid),
+    onFailure: (envelope) => ctx.metrics.notifyFailure(envelope, gid)
   };
 }
 function buildRetryTopicDeps(ctx) {
@@ -2250,6 +2504,11 @@ async function launchRetryChain(ctx, gid, topicNames, handleMessage, opts) {
     schemaMap,
     {
       ...ctx.retryTopicDeps,
+      // Bind circuit breaker events to the MAIN consumer group so failures and
+      // successes inside the retry chain drive the same breaker as the main
+      // consumer (the retry chain has no breaker config of its own).
+      onFailure: (envelope) => ctx.metrics.notifyFailure(envelope, gid),
+      onMessage: (envelope) => ctx.metrics.notifyMessage(envelope, gid),
       onLevelStarted: (levelGroupId) => {
         ctx.companionGroupIds.get(gid).push(levelGroupId);
       }
@@ -2265,7 +2524,15 @@ async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
   const incomingClock = Number(clockRaw);
   if (Number.isNaN(incomingClock)) return false;
   const stateKey = `${envelope.topic}:${envelope.partition}`;
-  const lastProcessedClock = dedup.state.get(stateKey) ?? -1;
+  let lastProcessedClock;
+  try {
+    lastProcessedClock = await dedup.store.getLastClock(dedup.groupId, stateKey) ?? -1;
+  } catch (err) {
+    deps.logger.error(
+      `Dedup store getLastClock failed on ${envelope.topic}[${envelope.partition}] \u2014 treating message as not a duplicate (fail-open): ${err.message}`
+    );
+    return false;
+  }
   if (incomingClock <= lastProcessedClock) {
     const meta = {
       incomingClock,
@@ -2295,7 +2562,13 @@ async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
     }
     return true;
   }
-  dedup.state.set(stateKey, incomingClock);
+  try {
+    await dedup.store.setLastClock(dedup.groupId, stateKey, incomingClock);
+  } catch (err) {
+    deps.logger.error(
+      `Dedup store setLastClock failed on ${envelope.topic}[${envelope.partition}] \u2014 processing message anyway (fail-open): ${err.message}`
+    );
+  }
   return false;
 }
 async function parseSingleMessage(message, topic2, partition, schemaMap, interceptors, dlq, deps) {
@@ -2908,7 +3181,7 @@ function stopConsumerByGid(ctx, gid) {
   return stopConsumerImpl(ctx, gid);
 }
 
-// src/client/kafka.client/consumer/window.ts
+// src/client/kafka.client/consumer/features/window.ts
 async function startWindowConsumerImpl(ctx, topic2, handler, options) {
   const { maxMessages, maxMs, ...consumerOptions } = options;
   if (maxMessages <= 0)
@@ -2922,6 +3195,7 @@ async function startWindowConsumerImpl(ctx, topic2, handler, options) {
   const buffer = [];
   let flushTimer = null;
   let windowStart = 0;
+  const onLost = consumerOptions.onMessageLost ?? ctx.onMessageLost;
   const flush = async (trigger) => {
     if (flushTimer !== null) {
       clearTimeout(flushTimer);
@@ -2929,17 +3203,32 @@ async function startWindowConsumerImpl(ctx, topic2, handler, options) {
     }
     if (buffer.length === 0) return;
     const envelopes = buffer.splice(0);
-    await handler(envelopes, { trigger, windowStart, windowEnd: Date.now() });
+    try {
+      await handler(envelopes, { trigger, windowStart, windowEnd: Date.now() });
+    } catch (err) {
+      const error = toError(err);
+      ctx.logger.error(
+        `startWindowConsumer: ${trigger}-triggered flush failed \u2014 window of ${envelopes.length} message(s) lost:`,
+        error.stack
+      );
+      for (const envelope of envelopes) {
+        await Promise.resolve(
+          onLost?.({
+            topic: envelope.topic,
+            error,
+            attempt: 0,
+            headers: envelope.headers
+          })
+        ).catch(() => {
+        });
+      }
+    }
   };
   const scheduleFlush = () => {
     if (flushTimer !== null) return;
     flushTimer = setTimeout(() => {
       flushTimer = null;
-      flush("time").catch((err) => {
-        ctx.logger.warn(
-          `startWindowConsumer: time-triggered flush error \u2014 ${toError(err).message}`
-        );
-      });
+      void flush("time");
     }, maxMs);
   };
   const handle = await startConsumerImpl(
@@ -2955,40 +3244,13 @@ async function startWindowConsumerImpl(ctx, topic2, handler, options) {
   );
   const originalStop = handle.stop.bind(handle);
   handle.stop = async () => {
-    if (flushTimer !== null) {
-      clearTimeout(flushTimer);
-      flushTimer = null;
-    }
-    if (buffer.length > 0) {
-      const envelopes = buffer.splice(0);
-      await handler(envelopes, {
-        trigger: "time",
-        windowStart,
-        windowEnd: Date.now()
-      }).catch(async (err) => {
-        const error = toError(err);
-        ctx.logger.warn(
-          `startWindowConsumer: shutdown flush error \u2014 ${error.message}`
-        );
-        for (const envelope of envelopes) {
-          await Promise.resolve(
-            ctx.onMessageLost?.({
-              topic: envelope.topic,
-              error,
-              attempt: 0,
-              headers: envelope.headers
-            })
-          ).catch(() => {
-          });
-        }
-      });
-    }
+    await flush("time");
     return originalStop();
   };
   return handle;
 }
 
-// src/client/kafka.client/consumer/routed.ts
+// src/client/kafka.client/consumer/features/routed.ts
 async function startRoutedConsumerImpl(ctx, topics, routing, options) {
   const { header, routes, fallback } = routing;
   const handleMessage = async (envelope) => {
@@ -3003,7 +3265,118 @@ async function startRoutedConsumerImpl(ctx, topics, routing, options) {
   return startConsumerImpl(ctx, topics, handleMessage, options);
 }
 
-// src/client/kafka.client/consumer/snapshot.ts
+// src/client/kafka.client/consumer/features/delayed.ts
+function delayedTopicName(topic2) {
+  return `${topic2}.delayed`;
+}
+async function startDelayedRelayImpl(ctx, topics, options) {
+  if (topics.length === 0) {
+    throw new Error("startDelayedRelay: at least one topic is required");
+  }
+  const gid = options?.groupId ?? `${ctx.defaultGroupId}-delayed-relay`;
+  if (ctx.runningConsumers.has(gid)) {
+    throw new Error(
+      `startDelayedRelay("${gid}") called twice \u2014 this group is already consuming. Call stopConsumer("${gid}") first or pass a different groupId.`
+    );
+  }
+  const delayedTopics = topics.map(delayedTopicName);
+  for (const t of delayedTopics) await ensureTopic(ctx, t);
+  const txProducer = await createRetryTxProducer(ctx, `${gid}-tx`);
+  let resolveReady;
+  const readyPromise = new Promise((resolve) => {
+    resolveReady = resolve;
+  });
+  const consumer = getOrCreateConsumer(
+    gid,
+    false,
+    false,
+    ctx.consumerOpsDeps,
+    void 0,
+    resolveReady
+  );
+  await consumer.connect();
+  await subscribeWithRetry(consumer, delayedTopics, ctx.logger);
+  await consumer.run({
+    eachMessage: async ({ topic: stagingTopic, partition, message }) => {
+      const nextOffset = {
+        topic: stagingTopic,
+        partition,
+        offset: (parseInt(message.offset, 10) + 1).toString()
+      };
+      if (!message.value) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      const headers = decodeHeaders(message.headers);
+      const target = headers[HEADER_DELAYED_TARGET] ?? stagingTopic.replace(/\.delayed$/, "");
+      const until = parseInt(
+        headers[HEADER_DELAYED_UNTIL] ?? "0",
+        10
+      );
+      const remaining = until - Date.now();
+      if (remaining > 0) {
+        consumer.pause([{ topic: stagingTopic, partitions: [partition] }]);
+        await sleep(remaining);
+        consumer.resume([{ topic: stagingTopic, partitions: [partition] }]);
+      }
+      const forwardHeaders = Object.fromEntries(
+        Object.entries(headers).filter(
+          ([k]) => k !== HEADER_DELAYED_UNTIL && k !== HEADER_DELAYED_TARGET
+        )
+      );
+      const tx = await txProducer.transaction();
+      try {
+        await tx.send({
+          topic: target,
+          messages: [
+            {
+              value: message.value.toString(),
+              key: message.key ? message.key.toString() : null,
+              headers: forwardHeaders
+            }
+          ]
+        });
+        await tx.sendOffsets({
+          consumer,
+          topics: [
+            {
+              topic: nextOffset.topic,
+              partitions: [
+                { partition: nextOffset.partition, offset: nextOffset.offset }
+              ]
+            }
+          ]
+        });
+        await tx.commit();
+        ctx.logger.debug?.(
+          `Delayed message relayed to "${target}" (deadline ${new Date(until).toISOString()})`
+        );
+      } catch (txErr) {
+        try {
+          await tx.abort();
+        } catch {
+        }
+        ctx.logger.error(
+          `Delayed relay to "${target}" failed \u2014 message will be redelivered:`,
+          toError(txErr).stack
+        );
+      }
+    }
+  });
+  ctx.runningConsumers.set(gid, "eachMessage");
+  ctx.logger.log(
+    `Delayed relay started for: ${delayedTopics.join(", ")} (group: ${gid})`
+  );
+  return {
+    groupId: gid,
+    ready: () => readyPromise,
+    stop: async () => {
+      await stopConsumerImpl(ctx, gid);
+    }
+  };
+}
+
+// src/client/kafka.client/consumer/features/snapshot.ts
 async function readSnapshotImpl(ctx, topic2, options = {}) {
   await ctx.adminOps.ensureConnected();
   let offsets;
@@ -3269,6 +3642,7 @@ var KafkaClient = class {
    * ```
    */
   constructor(clientId, groupId, brokers, options) {
+    validateClientOptions(clientId, groupId, brokers, options);
     this.clientId = clientId;
     const logger = options?.logger ?? {
       log: (msg) => console.log(`[KafkaClient:${clientId}] ${msg}`),
@@ -3276,7 +3650,8 @@ var KafkaClient = class {
       error: (msg, ...args) => console.error(`[KafkaClient:${clientId}] ${msg}`, ...args),
       debug: (msg, ...args) => console.debug(`[KafkaClient:${clientId}] ${msg}`, ...args)
     };
-    const transport = options?.transport ?? new ConfluentTransport(clientId, brokers);
+    const security = resolveSecurityOptions(options?.security, brokers, logger);
+    const transport = options?.transport ?? new ConfluentTransport(clientId, brokers, security);
     const producer = transport.producer();
     const runningConsumers = /* @__PURE__ */ new Map();
     const consumers = /* @__PURE__ */ new Map();
@@ -3310,6 +3685,7 @@ var KafkaClient = class {
       numPartitions: options?.numPartitions ?? 1,
       txId: options?.transactionalId ?? `${clientId}-tx`,
       clockRecoveryTopics: options?.clockRecovery?.topics ?? [],
+      clockRecoveryTimeoutMs: options?.clockRecovery?.timeoutMs ?? 3e4,
       lagThrottleOpts: options?.lagThrottle,
       instrumentation: options?.instrumentation ?? [],
       onMessageLost: options?.onMessageLost,
@@ -3319,6 +3695,7 @@ var KafkaClient = class {
       producer,
       txProducer: void 0,
       txProducerInitPromise: void 0,
+      _txChain: Promise.resolve(),
       retryTxProducers: /* @__PURE__ */ new Map(),
       consumers,
       runningConsumers,
@@ -3442,6 +3819,31 @@ var KafkaClient = class {
   startRoutedConsumer(topics, routing, options) {
     return startRoutedConsumerImpl(this.ctx, topics, routing, options);
   }
+  // ── Consumer: delayed delivery relay ──────────────────────────────
+  /**
+   * 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
+   * ```
+   */
+  async startDelayedRelay(topics, options) {
+    const list = Array.isArray(topics) ? topics : [topics];
+    return startDelayedRelayImpl(this.ctx, list, options);
+  }
   // ── Consumer: transactional EOS ───────────────────────────────────
   /** @inheritDoc */
   async startTransactionalConsumer(topics, handler, options = {}) {
@@ -3587,34 +3989,884 @@ var KafkaClient = class {
 function topic(name) {
   return {
     /** Provide an explicit message type without a runtime schema. */
-    type: () => ({
+    type: () => keyable({
       __topic: name,
       __type: void 0
     }),
-    schema: (schema) => ({
+    schema: (schema) => keyable({
       __topic: name,
       __type: void 0,
       __schema: schema
     })
   };
 }
+function keyable(desc) {
+  return {
+    ...desc,
+    key: (extractor) => ({
+      ...desc,
+      __key: extractor
+    })
+  };
+}
+
+// src/client/message/versioned-schema.ts
+function versionedSchema(versions, options) {
+  const registered = Object.keys(versions).map(Number).filter((v) => Number.isInteger(v) && v > 0).sort((a, b) => a - b);
+  if (registered.length === 0) {
+    throw new Error(
+      "versionedSchema: at least one schema version must be registered (keys must be positive integers)"
+    );
+  }
+  const latestVersion = registered[registered.length - 1];
+  return {
+    async parse(data, ctx) {
+      const version = ctx?.version ?? latestVersion;
+      const schema = versions[version];
+      if (!schema) {
+        throw new Error(
+          `versionedSchema: no schema registered for version ${version}${ctx?.topic ? ` (topic "${ctx.topic}")` : ""} \u2014 registered versions: ${registered.join(", ")}`
+        );
+      }
+      const parsed = await schema.parse(data, ctx);
+      if (version < latestVersion && options?.migrate) {
+        return options.migrate(parsed, version, latestVersion);
+      }
+      return parsed;
+    }
+  };
+}
+
+// src/client/message/schema-registry.ts
+var SchemaRegistryClient = class {
+  constructor(options) {
+    this.options = options;
+    if (!options.baseUrl) {
+      throw new Error("SchemaRegistryClient: baseUrl is required");
+    }
+    this.fetchFn = options.fetchFn ?? fetch;
+    this.cacheTtlMs = options.cacheTtlMs ?? 3e5;
+  }
+  options;
+  fetchFn;
+  cacheTtlMs;
+  latestCache = /* @__PURE__ */ new Map();
+  headers() {
+    const h = {
+      "Content-Type": "application/vnd.schemaregistry.v1+json"
+    };
+    if (this.options.auth) {
+      const { username, password } = this.options.auth;
+      h["Authorization"] = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+    }
+    return h;
+  }
+  async request(method, path, body) {
+    const url = `${this.options.baseUrl.replace(/\/$/, "")}${path}`;
+    const res = await this.fetchFn(url, {
+      method,
+      headers: this.headers(),
+      ...body !== void 0 && { body: JSON.stringify(body) }
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `SchemaRegistry ${method} ${path} failed: ${res.status} ${res.statusText}${text ? ` \u2014 ${text}` : ""}`
+      );
+    }
+    return await res.json();
+  }
+  /** Fetch the latest schema registered under `subject`. Cached for `cacheTtlMs`. */
+  async getLatestSchema(subject) {
+    const cached = this.latestCache.get(subject);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    const raw = await this.request("GET", `/subjects/${encodeURIComponent(subject)}/versions/latest`);
+    const value = {
+      id: raw.id,
+      version: raw.version,
+      schema: raw.schema
+    };
+    this.latestCache.set(subject, {
+      value,
+      expiresAt: Date.now() + this.cacheTtlMs
+    });
+    return value;
+  }
+  /** Fetch a specific schema version of a subject. */
+  async getSchemaVersion(subject, version) {
+    const raw = await this.request(
+      "GET",
+      `/subjects/${encodeURIComponent(subject)}/versions/${version}`
+    );
+    return { id: raw.id, version: raw.version, schema: raw.schema };
+  }
+  /**
+   * Register a schema under `subject` (idempotent — re-registering the same
+   * schema returns the existing id). Returns the registry-assigned schema id.
+   */
+  async registerSchema(subject, schema, schemaType = "JSON") {
+    this.latestCache.delete(subject);
+    return this.request(
+      "POST",
+      `/subjects/${encodeURIComponent(subject)}/versions`,
+      { schema, schemaType }
+    );
+  }
+  /**
+   * Test `schema` against the subject's compatibility policy without registering.
+   * Returns `true` when the registry reports the schema as compatible.
+   */
+  async checkCompatibility(subject, schema, schemaType = "JSON") {
+    const res = await this.request(
+      "POST",
+      `/compatibility/subjects/${encodeURIComponent(subject)}/versions/latest`,
+      { schema, schemaType }
+    );
+    return res.is_compatible;
+  }
+};
+function registrySchema(client, subject, options) {
+  const enforceVersion = options?.enforceVersion ?? true;
+  return {
+    async parse(data, ctx) {
+      const latest = await client.getLatestSchema(subject);
+      if (enforceVersion && ctx?.version !== void 0 && ctx.version > latest.version) {
+        throw new Error(
+          `registrySchema: message version ${ctx.version} for subject "${subject}" is newer than the latest registered version ${latest.version} \u2014 register the schema before producing with it`
+        );
+      }
+      if (options?.validator) {
+        return options.validator.parse(data, ctx);
+      }
+      return data;
+    }
+  };
+}
+
+// src/client/outbox/outbox.store.ts
+var InMemoryOutboxStore = class {
+  /** Insertion-ordered rows. `published` flips to true after `markPublished`. */
+  rows = [];
+  /**
+   * Append a message to the outbox. In a real store this INSERT would run inside
+   * the same DB transaction as the corresponding business write.
+   */
+  add(message) {
+    this.rows.push({ message, published: false });
+  }
+  async fetchUnpublished(limit) {
+    const out = [];
+    for (const row of this.rows) {
+      if (row.published) continue;
+      out.push(row.message);
+      if (out.length >= limit) break;
+    }
+    return out;
+  }
+  async markPublished(ids) {
+    const idSet = new Set(ids);
+    for (const row of this.rows) {
+      if (idSet.has(row.message.id)) row.published = true;
+    }
+  }
+  /** Test helper: count of rows not yet marked published. */
+  get pendingCount() {
+    return this.rows.filter((r) => !r.published).length;
+  }
+  /** Test helper: count of rows marked published. */
+  get publishedCount() {
+    return this.rows.filter((r) => r.published).length;
+  }
+};
+
+// src/client/outbox/outbox.relay.ts
+function toError2(e) {
+  return e instanceof Error ? e : new Error(String(e));
+}
+function startOutboxRelay(kafka, store, options = {}) {
+  const pollIntervalMs = options.pollIntervalMs ?? 1e3;
+  const batchSize = options.batchSize ?? 100;
+  const onError = options.onError ?? ((error, batch) => {
+    console.error(
+      `[outbox] batch of ${batch.length} message(s) failed \u2014 will retry:`,
+      error
+    );
+  });
+  const onPublished = options.onPublished;
+  let stopped = false;
+  let running = false;
+  let inFlight = Promise.resolve();
+  const iterate = async () => {
+    let batch = [];
+    try {
+      batch = await store.fetchUnpublished(batchSize);
+      if (batch.length === 0) return;
+      await kafka.transaction(async (tx) => {
+        for (const msg of batch) {
+          await tx.send(msg.topic, msg.payload, {
+            key: msg.key,
+            headers: msg.headers,
+            correlationId: msg.correlationId,
+            eventId: msg.eventId
+          });
+        }
+      });
+      await store.markPublished(batch.map((m) => m.id));
+      onPublished?.(batch.length);
+    } catch (err) {
+      onError(toError2(err), batch);
+    }
+  };
+  const tick = () => {
+    if (stopped || running) return;
+    running = true;
+    inFlight = iterate().finally(() => {
+      running = false;
+    });
+  };
+  const timer = setInterval(tick, pollIntervalMs);
+  timer.unref?.();
+  return {
+    stop: async () => {
+      stopped = true;
+      clearInterval(timer);
+      await inFlight;
+    }
+  };
+}
+
+// src/client/security/providers.ts
+var defaultImport = (specifier) => import(specifier);
+function awsMskIamProvider(options) {
+  const importFn = options.importFn ?? defaultImport;
+  return async () => {
+    let signer;
+    try {
+      signer = await importFn("aws-msk-iam-sasl-signer-js");
+    } catch {
+      throw new Error(
+        "awsMskIamProvider: package 'aws-msk-iam-sasl-signer-js' is not installed. Run `npm install aws-msk-iam-sasl-signer-js` to enable MSK IAM authentication."
+      );
+    }
+    const { token, expiryTime } = await signer.generateAuthToken({
+      region: options.region
+    });
+    return {
+      value: token,
+      principal: "msk-iam",
+      // expiryTime is epoch ms per the signer's contract
+      lifetimeMs: expiryTime
+    };
+  };
+}
+function gcpAccessTokenProvider(options = {}) {
+  const importFn = options.importFn ?? defaultImport;
+  const ttlMs = options.tokenTtlMs ?? 50 * 6e4;
+  return async () => {
+    let lib;
+    try {
+      lib = await importFn("google-auth-library");
+    } catch {
+      throw new Error(
+        "gcpAccessTokenProvider: package 'google-auth-library' is not installed. Run `npm install google-auth-library` to enable GCP authentication."
+      );
+    }
+    const auth = new lib.GoogleAuth({
+      scopes: options.scopes ?? ["https://www.googleapis.com/auth/cloud-platform"]
+    });
+    const token = await auth.getAccessToken();
+    if (!token) {
+      throw new Error(
+        "gcpAccessTokenProvider: google-auth-library returned no access token \u2014 check Application Default Credentials."
+      );
+    }
+    return {
+      value: token,
+      principal: options.principal ?? "gcp",
+      lifetimeMs: Date.now() + ttlMs
+    };
+  };
+}
+
+// src/client/security/acl.ts
+function addResource(out, r) {
+  const key = `${r.resourceType}:${r.patternType}:${r.name}`;
+  const existing = out.get(key);
+  if (existing) {
+    for (const op of r.operations)
+      if (!existing.operations.includes(op)) existing.operations.push(op);
+    if (!existing.reason.includes(r.reason))
+      existing.reason += `; ${r.reason}`;
+  } else {
+    out.set(key, { ...r, operations: [...r.operations] });
+  }
+}
+function describeRequiredAcls(input) {
+  const out = /* @__PURE__ */ new Map();
+  const f = input.features ?? {};
+  const produce = input.produceTopics ?? [];
+  const consume = input.consumeTopics ?? [];
+  const groups = input.groupIds ?? [];
+  for (const t of produce) {
+    addResource(out, {
+      resourceType: "topic",
+      patternType: "literal",
+      name: t,
+      operations: ["WRITE", "DESCRIBE"],
+      reason: "sendMessage/sendBatch"
+    });
+  }
+  for (const t of consume) {
+    addResource(out, {
+      resourceType: "topic",
+      patternType: "literal",
+      name: t,
+      operations: ["READ", "DESCRIBE"],
+      reason: "startConsumer"
+    });
+  }
+  for (const g of groups) {
+    addResource(out, {
+      resourceType: "group",
+      patternType: "literal",
+      name: g,
+      operations: ["READ", "DESCRIBE"],
+      reason: "consumer group membership + offset commits"
+    });
+  }
+  if (f.dlq) {
+    for (const t of consume) {
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: `${t}.dlq`,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "dlq: true \u2014 failed messages routed to DLQ"
+      });
+    }
+  }
+  if (f.retryTopics) {
+    for (const t of consume) {
+      for (let level = 1; level <= f.retryTopics.maxRetries; level++) {
+        addResource(out, {
+          resourceType: "topic",
+          patternType: "literal",
+          name: `${t}.retry.${level}`,
+          operations: ["READ", "WRITE", "DESCRIBE"],
+          reason: "retryTopics \u2014 retry chain produce + companion consume"
+        });
+      }
+    }
+    for (const g of groups) {
+      addResource(out, {
+        resourceType: "group",
+        patternType: "prefixed",
+        name: `${g}-retry.`,
+        operations: ["READ", "DESCRIBE"],
+        reason: "retryTopics \u2014 companion retry-level consumer groups"
+      });
+      addResource(out, {
+        resourceType: "transactional-id",
+        patternType: "prefixed",
+        name: `${g}-`,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "retryTopics \u2014 EOS routing transactions per retry level"
+      });
+    }
+  }
+  if (f.delayedDelivery) {
+    for (const t of [.../* @__PURE__ */ new Set([...produce, ...consume])]) {
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: `${t}.delayed`,
+        operations: ["READ", "WRITE", "DESCRIBE"],
+        reason: "deliverAfterMs staging + startDelayedRelay consume"
+      });
+    }
+    for (const g of groups) {
+      addResource(out, {
+        resourceType: "group",
+        patternType: "literal",
+        name: `${g}-delayed-relay`,
+        operations: ["READ", "DESCRIBE"],
+        reason: "startDelayedRelay consumer group"
+      });
+      addResource(out, {
+        resourceType: "transactional-id",
+        patternType: "literal",
+        name: `${g}-delayed-relay-tx`,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "startDelayedRelay transactional forwarding"
+      });
+    }
+  }
+  if (f.duplicatesTopic) {
+    if (typeof f.duplicatesTopic === "string") {
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: f.duplicatesTopic,
+        operations: ["WRITE", "DESCRIBE"],
+        reason: "deduplication.strategy 'topic' \u2014 custom duplicates topic"
+      });
+    } else {
+      for (const t of consume) {
+        addResource(out, {
+          resourceType: "topic",
+          patternType: "literal",
+          name: `${t}.duplicates`,
+          operations: ["WRITE", "DESCRIBE"],
+          reason: "deduplication.strategy 'topic'"
+        });
+      }
+    }
+  }
+  if (f.dlqReplay) {
+    for (const t of consume) {
+      addResource(out, {
+        resourceType: "group",
+        patternType: "prefixed",
+        name: `${t}.dlq-replay`,
+        operations: ["READ", "DESCRIBE", "DELETE"],
+        reason: "replayDlq \u2014 ephemeral/stable replay groups (deleted after use)"
+      });
+      addResource(out, {
+        resourceType: "topic",
+        patternType: "literal",
+        name: `${t}.dlq`,
+        operations: ["READ", "DESCRIBE"],
+        reason: "replayDlq \u2014 reads the DLQ"
+      });
+    }
+  }
+  if (f.snapshots) {
+    addResource(out, {
+      resourceType: "group",
+      patternType: "prefixed",
+      name: `${input.clientId}-snapshot-`,
+      operations: ["READ", "DESCRIBE", "DELETE"],
+      reason: "readSnapshot \u2014 timestamped ephemeral groups (deleted after use)"
+    });
+  }
+  if (f.clockRecovery) {
+    addResource(out, {
+      resourceType: "group",
+      patternType: "prefixed",
+      name: `${input.clientId}-clock-recovery-`,
+      operations: ["READ", "DESCRIBE", "DELETE"],
+      reason: "clockRecovery \u2014 timestamped ephemeral groups (deleted after use)"
+    });
+  }
+  if (f.transactions) {
+    addResource(out, {
+      resourceType: "transactional-id",
+      patternType: "literal",
+      name: `${input.clientId}-tx`,
+      operations: ["WRITE", "DESCRIBE"],
+      reason: "transaction() \u2014 default transactionalId (override-aware: adjust if you set one)"
+    });
+  }
+  if (f.autoCreateTopics) {
+    addResource(out, {
+      resourceType: "cluster",
+      patternType: "literal",
+      name: "kafka-cluster",
+      operations: ["CREATE"],
+      reason: "autoCreateTopics: true \u2014 not recommended in production"
+    });
+  }
+  return [...out.values()];
+}
+function toKafkaAclCommands(resources, principal, bootstrapServer = "<bootstrap-server>") {
+  return resources.map((r) => {
+    const ops = r.operations.map((o) => `--operation ${o}`).join(" ");
+    const resourceFlag = r.resourceType === "topic" ? `--topic '${r.name}'` : r.resourceType === "group" ? `--group '${r.name}'` : r.resourceType === "transactional-id" ? `--transactional-id '${r.name}'` : "--cluster";
+    const pattern = r.patternType === "prefixed" ? " --resource-pattern-type prefixed" : "";
+    return `kafka-acls.sh --bootstrap-server ${bootstrapServer} --add --allow-principal '${principal}' ${ops} ${resourceFlag}${pattern}  # ${r.reason}`;
+  });
+}
+var MSK_TOPIC_ACTIONS = {
+  READ: ["kafka-cluster:ReadData", "kafka-cluster:DescribeTopic"],
+  WRITE: ["kafka-cluster:WriteData", "kafka-cluster:DescribeTopic"],
+  DESCRIBE: ["kafka-cluster:DescribeTopic"],
+  CREATE: ["kafka-cluster:CreateTopic"],
+  DELETE: ["kafka-cluster:DeleteTopic"]
+};
+var MSK_GROUP_ACTIONS = {
+  READ: ["kafka-cluster:AlterGroup", "kafka-cluster:DescribeGroup"],
+  DESCRIBE: ["kafka-cluster:DescribeGroup"],
+  DELETE: ["kafka-cluster:DeleteGroup"]
+};
+var MSK_TX_ACTIONS = {
+  WRITE: [
+    "kafka-cluster:AlterTransactionalId",
+    "kafka-cluster:DescribeTransactionalId"
+  ],
+  DESCRIBE: ["kafka-cluster:DescribeTransactionalId"]
+};
+function toMskIamPolicy(resources, cluster) {
+  const { region, accountId, clusterName, clusterUuid } = cluster;
+  const arn = (type, name) => `arn:aws:kafka:${region}:${accountId}:${type}/${clusterName}/${clusterUuid}/${name}`;
+  const statements = [
+    {
+      Sid: "Connect",
+      Effect: "Allow",
+      Action: ["kafka-cluster:Connect"],
+      Resource: [
+        `arn:aws:kafka:${region}:${accountId}:cluster/${clusterName}/${clusterUuid}`
+      ]
+    }
+  ];
+  let sid = 0;
+  for (const r of resources) {
+    const suffix = r.patternType === "prefixed" ? `${r.name}*` : r.name;
+    let actions = [];
+    let resource;
+    if (r.resourceType === "topic") {
+      actions = [...new Set(r.operations.flatMap((o) => MSK_TOPIC_ACTIONS[o] ?? []))];
+      resource = arn("topic", suffix);
+    } else if (r.resourceType === "group") {
+      actions = [...new Set(r.operations.flatMap((o) => MSK_GROUP_ACTIONS[o] ?? []))];
+      resource = arn("group", suffix);
+    } else if (r.resourceType === "transactional-id") {
+      actions = [...new Set(r.operations.flatMap((o) => MSK_TX_ACTIONS[o] ?? []))];
+      resource = arn("transactional-id", suffix);
+    } else {
+      actions = ["kafka-cluster:CreateTopic"];
+      resource = `arn:aws:kafka:${region}:${accountId}:topic/${clusterName}/${clusterUuid}/*`;
+    }
+    if (actions.length === 0 || !resource) continue;
+    statements.push({
+      Sid: `Acl${sid++}`,
+      Effect: "Allow",
+      Action: actions,
+      Resource: [resource]
+    });
+  }
+  return { Version: "2012-10-17", Statement: statements };
+}
+
+// src/client/config/from-env.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["true", "1", "yes"]);
+var FALSE_VALUES = /* @__PURE__ */ new Set(["false", "0", "no"]);
+function parseBool(name, raw) {
+  const normalized = raw.trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+  throw new Error(
+    `Invalid boolean for ${name}: "${raw}". Use one of true/false, 1/0, yes/no (case-insensitive).`
+  );
+}
+function parseNum(name, raw) {
+  const value = Number(raw.trim());
+  if (Number.isNaN(value)) {
+    throw new Error(`Invalid number for ${name}: "${raw}".`);
+  }
+  return value;
+}
+function parseList(raw) {
+  return raw.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+}
+function parseEnum(name, raw, allowed) {
+  const value = raw.trim();
+  if (!allowed.includes(value)) {
+    throw new Error(
+      `Invalid value for ${name}: "${raw}". Allowed: ${allowed.join(", ")}.`
+    );
+  }
+  return value;
+}
+function readVar(env, key, apply) {
+  const raw = env[key];
+  if (raw === void 0 || raw.trim() === "") return;
+  apply(raw);
+}
+function kafkaClientConfigFromEnv(env = process.env, prefix = "KAFKA_") {
+  const options = {};
+  const result = { options };
+  readVar(env, `${prefix}CLIENT_ID`, (raw) => {
+    result.clientId = raw.trim();
+  });
+  readVar(env, `${prefix}GROUP_ID`, (raw) => {
+    result.groupId = raw.trim();
+  });
+  readVar(env, `${prefix}BROKERS`, (raw) => {
+    result.brokers = parseList(raw);
+  });
+  readVar(env, `${prefix}AUTO_CREATE_TOPICS`, (raw) => {
+    options.autoCreateTopics = parseBool(`${prefix}AUTO_CREATE_TOPICS`, raw);
+  });
+  readVar(env, `${prefix}STRICT_SCHEMAS`, (raw) => {
+    options.strictSchemas = parseBool(`${prefix}STRICT_SCHEMAS`, raw);
+  });
+  readVar(env, `${prefix}NUM_PARTITIONS`, (raw) => {
+    options.numPartitions = parseNum(`${prefix}NUM_PARTITIONS`, raw);
+  });
+  readVar(env, `${prefix}TRANSACTIONAL_ID`, (raw) => {
+    options.transactionalId = raw.trim();
+  });
+  readVar(env, `${prefix}CLOCK_RECOVERY_TOPICS`, (raw) => {
+    const topics = parseList(raw);
+    if (topics.length === 0) return;
+    options.clockRecovery = { topics };
+  });
+  readVar(env, `${prefix}CLOCK_RECOVERY_TIMEOUT_MS`, (raw) => {
+    const timeoutMs = parseNum(`${prefix}CLOCK_RECOVERY_TIMEOUT_MS`, raw);
+    if (options.clockRecovery) {
+      options.clockRecovery.timeoutMs = timeoutMs;
+    }
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_MAX_LAG`, (raw) => {
+    options.lagThrottle = {
+      maxLag: parseNum(`${prefix}LAG_THROTTLE_MAX_LAG`, raw)
+    };
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_GROUP_ID`, (raw) => {
+    if (options.lagThrottle) options.lagThrottle.groupId = raw.trim();
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_POLL_INTERVAL_MS`, (raw) => {
+    if (options.lagThrottle) {
+      options.lagThrottle.pollIntervalMs = parseNum(
+        `${prefix}LAG_THROTTLE_POLL_INTERVAL_MS`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}LAG_THROTTLE_MAX_WAIT_MS`, (raw) => {
+    if (options.lagThrottle) {
+      options.lagThrottle.maxWaitMs = parseNum(
+        `${prefix}LAG_THROTTLE_MAX_WAIT_MS`,
+        raw
+      );
+    }
+  });
+  const security = securityFromEnv(env, prefix);
+  if (security) options.security = security;
+  return result;
+}
+function securityFromEnv(env, prefix) {
+  let ssl;
+  let allowInsecure;
+  let mechanism;
+  let username;
+  let password;
+  readVar(env, `${prefix}SSL`, (raw) => {
+    ssl = parseBool(`${prefix}SSL`, raw);
+  });
+  readVar(env, `${prefix}ALLOW_INSECURE`, (raw) => {
+    allowInsecure = parseBool(`${prefix}ALLOW_INSECURE`, raw);
+  });
+  readVar(env, `${prefix}SASL_MECHANISM`, (raw) => {
+    mechanism = parseEnum(`${prefix}SASL_MECHANISM`, raw, [
+      "plain",
+      "scram-sha-256",
+      "scram-sha-512"
+    ]);
+  });
+  readVar(env, `${prefix}SASL_USERNAME`, (raw) => {
+    username = raw.trim();
+  });
+  readVar(env, `${prefix}SASL_PASSWORD`, (raw) => {
+    password = raw;
+  });
+  if (ssl === void 0 && allowInsecure === void 0 && mechanism === void 0 && username === void 0 && password === void 0) {
+    return void 0;
+  }
+  const security = {};
+  if (ssl !== void 0) security.ssl = ssl;
+  if (allowInsecure !== void 0) security.allowInsecure = allowInsecure;
+  if (mechanism !== void 0 || username !== void 0 || password !== void 0) {
+    if (mechanism === void 0 || username === void 0 || password === void 0) {
+      throw new Error(
+        `Incomplete SASL configuration: ${prefix}SASL_MECHANISM, ${prefix}SASL_USERNAME, and ${prefix}SASL_PASSWORD must all be set together (oauthbearer must be configured in code).`
+      );
+    }
+    const sasl = { mechanism, username, password };
+    security.sasl = sasl;
+  }
+  return security;
+}
+function consumerOptionsFromEnv(env = process.env, prefix = "KAFKA_CONSUMER_") {
+  const options = {};
+  readVar(env, `${prefix}GROUP_ID`, (raw) => {
+    options.groupId = raw.trim();
+  });
+  readVar(env, `${prefix}FROM_BEGINNING`, (raw) => {
+    options.fromBeginning = parseBool(`${prefix}FROM_BEGINNING`, raw);
+  });
+  readVar(env, `${prefix}AUTO_COMMIT`, (raw) => {
+    options.autoCommit = parseBool(`${prefix}AUTO_COMMIT`, raw);
+  });
+  readVar(env, `${prefix}DLQ`, (raw) => {
+    options.dlq = parseBool(`${prefix}DLQ`, raw);
+  });
+  readVar(env, `${prefix}RETRY_MAX_RETRIES`, (raw) => {
+    const retry = {
+      maxRetries: parseNum(`${prefix}RETRY_MAX_RETRIES`, raw)
+    };
+    options.retry = retry;
+  });
+  readVar(env, `${prefix}RETRY_BACKOFF_MS`, (raw) => {
+    if (options.retry) {
+      options.retry.backoffMs = parseNum(`${prefix}RETRY_BACKOFF_MS`, raw);
+    }
+  });
+  readVar(env, `${prefix}RETRY_MAX_BACKOFF_MS`, (raw) => {
+    if (options.retry) {
+      options.retry.maxBackoffMs = parseNum(`${prefix}RETRY_MAX_BACKOFF_MS`, raw);
+    }
+  });
+  readVar(env, `${prefix}RETRY_TOPICS`, (raw) => {
+    options.retryTopics = parseBool(`${prefix}RETRY_TOPICS`, raw);
+  });
+  readVar(env, `${prefix}RETRY_TOPIC_ASSIGNMENT_TIMEOUT_MS`, (raw) => {
+    options.retryTopicAssignmentTimeoutMs = parseNum(
+      `${prefix}RETRY_TOPIC_ASSIGNMENT_TIMEOUT_MS`,
+      raw
+    );
+  });
+  readVar(env, `${prefix}HANDLER_TIMEOUT_MS`, (raw) => {
+    options.handlerTimeoutMs = parseNum(`${prefix}HANDLER_TIMEOUT_MS`, raw);
+  });
+  readVar(env, `${prefix}MESSAGE_TTL_MS`, (raw) => {
+    options.messageTtlMs = parseNum(`${prefix}MESSAGE_TTL_MS`, raw);
+  });
+  readVar(env, `${prefix}DEDUPLICATION_STRATEGY`, (raw) => {
+    const strategy = parseEnum(`${prefix}DEDUPLICATION_STRATEGY`, raw, [
+      "drop",
+      "dlq",
+      "topic"
+    ]);
+    const dedup = { strategy };
+    options.deduplication = dedup;
+  });
+  readVar(env, `${prefix}DEDUPLICATION_TOPIC`, (raw) => {
+    if (options.deduplication) {
+      options.deduplication.duplicatesTopic = raw.trim();
+    }
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_THRESHOLD`, (raw) => {
+    const cb = {
+      threshold: parseNum(`${prefix}CIRCUIT_BREAKER_THRESHOLD`, raw)
+    };
+    options.circuitBreaker = cb;
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_RECOVERY_MS`, (raw) => {
+    if (options.circuitBreaker) {
+      options.circuitBreaker.recoveryMs = parseNum(
+        `${prefix}CIRCUIT_BREAKER_RECOVERY_MS`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_WINDOW_SIZE`, (raw) => {
+    if (options.circuitBreaker) {
+      options.circuitBreaker.windowSize = parseNum(
+        `${prefix}CIRCUIT_BREAKER_WINDOW_SIZE`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}CIRCUIT_BREAKER_HALF_OPEN_SUCCESSES`, (raw) => {
+    if (options.circuitBreaker) {
+      options.circuitBreaker.halfOpenSuccesses = parseNum(
+        `${prefix}CIRCUIT_BREAKER_HALF_OPEN_SUCCESSES`,
+        raw
+      );
+    }
+  });
+  readVar(env, `${prefix}QUEUE_HIGH_WATER_MARK`, (raw) => {
+    options.queueHighWaterMark = parseNum(`${prefix}QUEUE_HIGH_WATER_MARK`, raw);
+  });
+  readVar(env, `${prefix}PARTITION_ASSIGNER`, (raw) => {
+    options.partitionAssigner = parseEnum(`${prefix}PARTITION_ASSIGNER`, raw, [
+      "roundrobin",
+      "range",
+      "cooperative-sticky"
+    ]);
+  });
+  readVar(env, `${prefix}GROUP_INSTANCE_ID`, (raw) => {
+    options.groupInstanceId = raw.trim();
+  });
+  readVar(env, `${prefix}SUBSCRIBE_RETRY_RETRIES`, (raw) => {
+    const subscribeRetry = {
+      retries: parseNum(`${prefix}SUBSCRIBE_RETRY_RETRIES`, raw)
+    };
+    options.subscribeRetry = subscribeRetry;
+  });
+  readVar(env, `${prefix}SUBSCRIBE_RETRY_DELAY_MS`, (raw) => {
+    if (options.subscribeRetry) {
+      options.subscribeRetry.backoffMs = parseNum(
+        `${prefix}SUBSCRIBE_RETRY_DELAY_MS`,
+        raw
+      );
+    }
+  });
+  return options;
+}
+var NESTED_CONSUMER_KEYS = [
+  "retry",
+  "deduplication",
+  "circuitBreaker",
+  "subscribeRetry"
+];
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeConsumerOptions(...layers) {
+  const result = {};
+  for (const layer of layers) {
+    if (!layer) continue;
+    for (const [key, value] of Object.entries(layer)) {
+      if (value === void 0) continue;
+      if (NESTED_CONSUMER_KEYS.includes(key) && isPlainObject(value) && isPlainObject(result[key])) {
+        result[key] = {
+          ...result[key],
+          ...value
+        };
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HEADER_CORRELATION_ID,
+  HEADER_DELAYED_TARGET,
+  HEADER_DELAYED_UNTIL,
   HEADER_EVENT_ID,
   HEADER_LAMPORT_CLOCK,
   HEADER_SCHEMA_VERSION,
   HEADER_TIMESTAMP,
   HEADER_TRACEPARENT,
+  InMemoryDedupStore,
+  InMemoryOutboxStore,
   KafkaClient,
   KafkaProcessingError,
   KafkaRetryExhaustedError,
   KafkaValidationError,
+  SchemaRegistryClient,
+  awsMskIamProvider,
   buildEnvelopeHeaders,
+  consumerOptionsFromEnv,
   decodeHeaders,
+  describeRequiredAcls,
   extractEnvelope,
+  gcpAccessTokenProvider,
   getEnvelopeContext,
+  kafkaClientConfigFromEnv,
+  mergeConsumerOptions,
+  registrySchema,
+  resolveSecurityOptions,
   runWithEnvelopeContext,
-  topic
+  startOutboxRelay,
+  toError,
+  toKafkaAclCommands,
+  toMskIamPolicy,
+  topic,
+  versionedSchema
 });
 //# sourceMappingURL=core.js.map