@babelqueue/kafka 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# @babelqueue/kafka
+
+Apache Kafka adapter for [BabelQueue](https://babelqueue.com) — a canonical-envelope
+**publisher** and a URN-routed, **process-then-commit** consumer over
+[KafkaJS](https://kafka.js.org), on `@babelqueue/core`. Implements
+[§6 of the broker-bindings contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#apache-kafka),
+so a Kafka-based Node service speaks the same wire contract as the .NET, Java, Python and Go
+SDKs.
+
+Kafka has **no native** per-message ack, delayed delivery, dead-letter queue, or delivery
+counter — this adapter absorbs all four in the binding layer (the envelope stays
+`schema_version: 1`): the record **value** is the envelope JSON, the contract fields are
+mirrored onto `bq-` headers (route on `bq-job` without decoding the body), the record
+timestamp mirrors `meta.created_at`, **`bq-attempts` is the authoritative retry counter**,
+consume is process-then-commit (manual commit), retry/delay use SDK-owned tiered retry topics
+`<topic>.retry.<n>`, and terminal failures go to an opt-in `<topic>.dlq`.
+
+## Install
+
+```bash
+npm i @babelqueue/kafka kafkajs
+```
+
+`kafkajs` is an optional peer — **you provide the producer/consumer** (a KafkaJS `Producer` /
+`Consumer` satisfies the adapter structurally).
+
+## Use
+
+```ts
+import { Kafka } from "kafkajs";
+import { KafkaPublisher, KafkaConsumer, RetryTopics } from "@babelqueue/kafka";
+
+const kafka = new Kafka({ brokers: ["localhost:9092"] });
+
+// produce
+const producer = kafka.producer();
+await producer.connect();
+const id = await KafkaPublisher.create(producer, "orders")
+  .publish("urn:babel:orders:created", { order_id: 1042 });
+
+// consume (manual commit, process-then-commit)
+const consumer = kafka.consumer({ groupId: "orders-workers" });
+await consumer.connect();
+await consumer.subscribe({ topic: "orders" });
+
+const retry = new RetryTopics("orders", [5_000, 60_000]); // orders.retry.1/.2 + orders.dlq
+const babel = new KafkaConsumer(
+  consumer,
+  {
+    "urn:babel:orders:created": async (env, message) => {
+      console.log(env.data.order_id, env.trace_id, env.attempts);
+    },
+  },
+  { producer, retryTopics: retry, maxTries: 3, onError: (err) => console.error(err) },
+);
+await babel.run(); // poll → process → commit (autoCommit: false)
+```
+
+Delayed delivery: `publish(urn, data, { delayMs: 300_000 })` routes to the matching retry
+tier (requires `KafkaPublisher.withRetryTopics`); on a plain publisher a delay throws. A
+throwing handler republishes to the next `<topic>.retry.<n>` tier with `bq-attempts + 1`, then
+commits; once `maxTries` is reached it goes to `<topic>.dlq` with a `dead_letter` block.
+
+## Contract mapping (§6)
+
+| Envelope | Apache Kafka |
+| :--- | :--- |
+| body | record `value` (byte-identical across SDKs) |
+| `job` (URN) | header `bq-job` (consumer routes on this) |
+| `trace_id` | header `bq-trace-id` |
+| `meta.id` | header `bq-message-id` |
+| `meta.schema_version` | header `bq-schema-version` (`"1"`) |
+| `meta.lang` | header `bq-source-lang` |
+| `meta.created_at` | record `timestamp` (Unix ms) |
+| `attempts` | header `bq-attempts` (**authoritative**; body is the fallback) |
+| reserve / ack | poll → process → **commit offset** (manual) |
+| retry / delay | republish to `<topic>.retry.<n>` (`bq-attempts + 1`) |
+| dead-letter | `<topic>.dlq` + `dead_letter` block |
+
+All header values are UTF-8 strings (integers as decimal strings, e.g. `"1"`). The
+producer/consumer are injected, so the unit tests use fakes — no Kafka, no broker. Dual
+ESM + CJS.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,281 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KafkaConsumer: () => KafkaConsumer,
+  KafkaPublisher: () => KafkaPublisher,
+  RetryTopics: () => RetryTopics,
+  kafkaHeaders: () => kafkaHeaders
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@babelqueue/core");
+function kafkaHeaders(envelope) {
+  const headers = {};
+  if (envelope.job) headers["bq-job"] = envelope.job;
+  if (envelope.trace_id) headers["bq-trace-id"] = envelope.trace_id;
+  if (envelope.meta.id) headers["bq-message-id"] = envelope.meta.id;
+  if (envelope.meta.schema_version != null) headers["bq-schema-version"] = String(envelope.meta.schema_version);
+  if (envelope.meta.lang) headers["bq-source-lang"] = envelope.meta.lang;
+  headers["bq-attempts"] = String(envelope.attempts ?? 0);
+  return headers;
+}
+function headerString(headers, key) {
+  const value = headers?.[key];
+  if (value === void 0) return void 0;
+  const v = Array.isArray(value) ? value[0] : value;
+  if (v === void 0) return void 0;
+  return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
+}
+function headerInt(headers, key, fallback) {
+  const s = headerString(headers, key);
+  if (s === void 0) return fallback;
+  const n = Number.parseInt(s.trim(), 10);
+  return Number.isNaN(n) ? fallback : n;
+}
+var RetryTopics = class {
+  constructor(workTopic, delaysMs = [], dlqTopic = void 0) {
+    this.workTopic = workTopic;
+    this.tiers = [...delaysMs].sort((a, b) => a - b).map((delayMs, i) => ({ topic: `${workTopic}.retry.${i + 1}`, delayMs }));
+    this.dlqTopic = dlqTopic === void 0 ? `${workTopic}.dlq` : dlqTopic;
+  }
+  workTopic;
+  tiers;
+  dlqTopic;
+  hasTiers() {
+    return this.tiers.length > 0;
+  }
+  /** The smallest tier whose delay ≥ `delayMs`; raises if none configured or the delay is too large. */
+  tierForDelay(delayMs) {
+    this.requireTiers();
+    for (const tier of this.tiers) {
+      if (tier.delayMs >= delayMs) return tier;
+    }
+    throw new import_core.BabelQueueError(
+      `Requested Kafka delay ${delayMs}ms exceeds the largest retry tier (${this.tiers[this.tiers.length - 1].delayMs}ms).`
+    );
+  }
+  /** The tier for a retry at `attempt` (0-based), clamped to the largest; raises if none configured. */
+  tierForAttempt(attempt) {
+    this.requireTiers();
+    return this.tiers[Math.min(Math.max(attempt, 0), this.tiers.length - 1)];
+  }
+  requireTiers() {
+    if (!this.tiers.length) {
+      throw new import_core.BabelQueueError(`Kafka retry/delay requires retry topics; none are configured for '${this.workTopic}'.`);
+    }
+  }
+};
+var KafkaPublisher = class _KafkaPublisher {
+  constructor(producer, workTopic, retryTopics) {
+    this.producer = producer;
+    this.workTopic = workTopic;
+    this.retryTopics = retryTopics;
+  }
+  producer;
+  workTopic;
+  retryTopics;
+  /** A publisher onto `topic` with no retry topics (a delay raises). */
+  static create(producer, topic) {
+    return new _KafkaPublisher(producer, topic);
+  }
+  /** A publisher onto the topology's work topic, with delay routed via its retry tiers. */
+  static withRetryTopics(producer, retryTopics) {
+    return new _KafkaPublisher(producer, retryTopics.workTopic, retryTopics);
+  }
+  /** Build + send the canonical envelope; returns the message id (`meta.id`). */
+  async publish(urn, data, options = {}) {
+    const envelope = import_core.EnvelopeCodec.make(urn, data, { queue: this.workTopic, traceId: options.traceId });
+    if (options.delayMs != null && options.delayMs > 0) {
+      if (!this.retryTopics) {
+        throw new import_core.BabelQueueError("Kafka has no native delayed delivery; a delay requires retry topics (none configured).");
+      }
+      const tier = this.retryTopics.tierForDelay(options.delayMs);
+      await this.sendRecord(tier.topic, envelope, options.delayMs, this.workTopic);
+    } else {
+      await this.sendRecord(this.workTopic, envelope);
+    }
+    return envelope.meta.id;
+  }
+  async sendRecord(topic, envelope, delayMs, originalTopic) {
+    const headers = kafkaHeaders(envelope);
+    if (delayMs != null) headers["bq-delay"] = String(delayMs);
+    if (originalTopic != null) headers["bq-original-topic"] = originalTopic;
+    await this.producer.send({
+      topic,
+      messages: [{ value: import_core.EnvelopeCodec.encode(envelope), headers, timestamp: String(envelope.meta.created_at) }]
+    });
+  }
+};
+var KafkaConsumer = class {
+  constructor(consumer, handlers, options = {}) {
+    this.consumer = consumer;
+    this.handlers = handlers;
+    this.options = options;
+    this.maxTries = options.maxTries ?? 3;
+    this.unknownUrn = options.unknownUrn ?? import_core.UnknownUrnStrategy.FAIL;
+  }
+  consumer;
+  handlers;
+  options;
+  maxTries;
+  unknownUrn;
+  /** Start the manual-commit consume loop (`autoCommit: false`); resolves when the consumer stops. */
+  async run() {
+    await this.consumer.run({ autoCommit: false, eachMessage: (payload) => this.handle(payload) });
+  }
+  /** Route + settle one record (process-then-commit). Exposed for testing. */
+  async handle(payload) {
+    const { message } = payload;
+    const raw = message.value ? message.value.toString("utf8") : "";
+    let envelope;
+    try {
+      envelope = this.reconcile(import_core.EnvelopeCodec.decode(raw), message);
+    } catch (decodeError) {
+      this.report(decodeError, null, payload);
+      await this.deadLetterRaw(payload);
+      await this.commit(payload);
+      return;
+    }
+    if (!import_core.EnvelopeCodec.accepts(envelope)) {
+      this.report(new import_core.BabelQueueError("Rejected a non-conformant BabelQueue envelope from Kafka."), envelope, payload);
+      await this.deadLetterRaw(payload);
+      await this.commit(payload);
+      return;
+    }
+    const urn = headerString(message.headers, "bq-job") ?? import_core.EnvelopeCodec.urn(envelope);
+    const handler = this.handlers[urn];
+    if (!handler) {
+      await this.onUnknownUrn(payload, envelope, urn);
+      return;
+    }
+    try {
+      await handler(envelope, message);
+      await this.commit(payload);
+    } catch (error) {
+      this.report(error, envelope, payload);
+      await this.retryOrDeadLetter(payload, envelope, error);
+      await this.commit(payload);
+    }
+  }
+  reconcile(envelope, message) {
+    const body = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+    return { ...envelope, attempts: headerInt(message.headers, "bq-attempts", body) };
+  }
+  async onUnknownUrn(payload, envelope, urn) {
+    switch (this.unknownUrn) {
+      case import_core.UnknownUrnStrategy.DELETE:
+        await this.commit(payload);
+        return;
+      case import_core.UnknownUrnStrategy.DEAD_LETTER:
+        await this.deadLetter(envelope, payload, "unknown_urn");
+        await this.commit(payload);
+        return;
+      case import_core.UnknownUrnStrategy.RELEASE:
+        await this.republishRetry(payload, envelope);
+        await this.commit(payload);
+        return;
+      default: {
+        const error = new import_core.UnknownUrnError(urn);
+        this.report(error, envelope, payload);
+        throw error;
+      }
+    }
+  }
+  async retryOrDeadLetter(payload, envelope, error) {
+    const hasTiers = this.options.retryTopics?.hasTiers() ?? false;
+    const hasDlq = (this.options.retryTopics?.dlqTopic ?? null) !== null;
+    if (!hasTiers && !hasDlq) {
+      void error;
+      throw new import_core.BabelQueueError("Kafka per-record retry requires retry topics and/or a DLQ; neither is configured.");
+    }
+    if (hasTiers && (envelope.attempts ?? 0) + 1 < this.maxTries) {
+      await this.republishRetry(payload, envelope);
+    } else {
+      await this.deadLetter(envelope, payload, "failed", error);
+    }
+  }
+  async republishRetry(payload, envelope) {
+    const topics = this.options.retryTopics;
+    if (!topics || !topics.hasTiers()) {
+      throw new import_core.BabelQueueError("Kafka retry/release requires retry topics; none are configured.");
+    }
+    const tier = topics.tierForAttempt(envelope.attempts ?? 0);
+    const bumped = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };
+    const headers = kafkaHeaders(bumped);
+    headers["bq-delay"] = String(tier.delayMs);
+    headers["bq-original-topic"] = this.originalTopic(payload);
+    await this.produce(tier.topic, bumped, headers);
+  }
+  async deadLetter(envelope, payload, reason, error) {
+    const dlq = this.options.retryTopics?.dlqTopic ?? null;
+    if (!dlq) return;
+    const original = this.originalTopic(payload);
+    const annotated = (0, import_core.annotate)(envelope, reason, original, {
+      attempts: envelope.attempts ?? 0,
+      error: error instanceof Error ? error.message : null,
+      exception: error instanceof Error ? error.name : null
+    });
+    const headers = kafkaHeaders(annotated);
+    headers["bq-original-topic"] = original;
+    await this.produce(dlq, annotated, headers);
+  }
+  async deadLetterRaw(payload) {
+    const dlq = this.options.retryTopics?.dlqTopic ?? null;
+    if (!dlq) return;
+    this.requireProducer();
+    const { message } = payload;
+    await this.options.producer.send({
+      topic: dlq,
+      messages: [{ value: message.value ?? Buffer.alloc(0), timestamp: String(Date.now()) }]
+    });
+  }
+  async produce(topic, envelope, headers) {
+    this.requireProducer();
+    await this.options.producer.send({
+      topic,
+      messages: [{ value: import_core.EnvelopeCodec.encode(envelope), headers, timestamp: String(Date.now()) }]
+    });
+  }
+  async commit(payload) {
+    await this.consumer.commitOffsets([
+      { topic: payload.topic, partition: payload.partition, offset: (Number(payload.message.offset) + 1).toString() }
+    ]);
+  }
+  originalTopic(payload) {
+    return headerString(payload.message.headers, "bq-original-topic") ?? payload.topic;
+  }
+  requireProducer() {
+    if (!this.options.producer) {
+      throw new import_core.BabelQueueError("This Kafka consumer needs a producer to republish (retry/DLQ).");
+    }
+  }
+  report(error, envelope, payload) {
+    this.options.onError?.(error, envelope, payload);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KafkaConsumer,
+  KafkaPublisher,
+  RetryTopics,
+  kafkaHeaders
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Apache Kafka adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed, **process-then-commit** consumer over\n * Apache Kafka (KafkaJS), so a Kafka-based Node service speaks the same contract (envelope\n * shape, URN identity, trace propagation) as the .NET, Java, Python and Go SDKs.\n *\n * Kafka has **no native** per-message ack, delayed delivery, dead-letter queue, or delivery\n * counter — this adapter absorbs all four in the binding layer (the envelope stays\n * `schema_version: 1`): the envelope JSON is the record **value**; the contract fields are\n * mirrored onto `bq-` headers (route on `bq-job` without decoding the body) and the record\n * timestamp mirrors `meta.created_at`; **`bq-attempts` is the authoritative retry counter**;\n * consume is process-then-commit (manual commit, at-least-once); retry/delay use SDK-owned\n * tiered retry topics `<topic>.retry.<n>`; terminal failures go to an opt-in `<topic>.dlq`.\n *\n * This implements §6 of the broker-bindings contract. `kafkajs` is an optional peer — you\n * provide the producer/consumer (a KafkaJS `Producer`/`Consumer` satisfies the adapter\n * structurally).\n */\n\nimport { annotate, BabelQueueError, EnvelopeCodec, UnknownUrnError, UnknownUrnStrategy } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal Kafka shapes (a structural subset of kafkajs) ---------------------\n\n/** Incoming record headers (KafkaJS decodes header values to Buffers). */\nexport type IncomingHeaders = { [key: string]: Buffer | string | (Buffer | string)[] | undefined };\n\n/** A record to produce (structural subset of a KafkaJS message). */\nexport interface KafkaProducerMessage {\n  key?: Buffer | string | null;\n  value: Buffer | string;\n  headers?: { [key: string]: string };\n  timestamp?: string;\n}\n\n/** The subset of the KafkaJS producer this adapter calls. */\nexport interface KafkaProducerClient {\n  send(record: { topic: string; messages: KafkaProducerMessage[] }): Promise<unknown>;\n}\n\n/** A received record (structural subset of a KafkaJS message). */\nexport interface KafkaIncomingMessage {\n  value: Buffer | null;\n  headers?: IncomingHeaders;\n  offset: string;\n  timestamp?: string;\n  key?: Buffer | null;\n}\n\n/** The payload KafkaJS passes to `eachMessage`. */\nexport interface EachMessagePayload {\n  topic: string;\n  partition: number;\n  message: KafkaIncomingMessage;\n}\n\n/** The subset of the KafkaJS consumer this adapter calls (manual commit — `autoCommit: false`). */\nexport interface KafkaConsumerClient {\n  run(config: { autoCommit?: boolean; eachMessage: (payload: EachMessagePayload) => Promise<void> }): Promise<void>;\n  commitOffsets(offsets: { topic: string; partition: number; offset: string }[]): Promise<void>;\n}\n\n// --- Header projection (contract §6.3) -----------------------------------------\n\n/** Project the envelope's contract fields onto Kafka record headers (UTF-8 string values). */\nexport function kafkaHeaders(envelope: Envelope): { [key: string]: string } {\n  const headers: { [key: string]: string } = {};\n  if (envelope.job) headers[\"bq-job\"] = envelope.job;\n  if (envelope.trace_id) headers[\"bq-trace-id\"] = envelope.trace_id;\n  if (envelope.meta.id) headers[\"bq-message-id\"] = envelope.meta.id;\n  if (envelope.meta.schema_version != null) headers[\"bq-schema-version\"] = String(envelope.meta.schema_version);\n  if (envelope.meta.lang) headers[\"bq-source-lang\"] = envelope.meta.lang;\n  headers[\"bq-attempts\"] = String(envelope.attempts ?? 0);\n  return headers;\n}\n\nfunction headerString(headers: IncomingHeaders | undefined, key: string): string | undefined {\n  const value = headers?.[key];\n  if (value === undefined) return undefined;\n  const v = Array.isArray(value) ? value[0] : value;\n  if (v === undefined) return undefined;\n  return Buffer.isBuffer(v) ? v.toString(\"utf8\") : String(v);\n}\n\nfunction headerInt(headers: IncomingHeaders | undefined, key: string, fallback: number): number {\n  const s = headerString(headers, key);\n  if (s === undefined) return fallback;\n  const n = Number.parseInt(s.trim(), 10);\n  return Number.isNaN(n) ? fallback : n;\n}\n\n// --- Retry / delay topology (contract §6.4–§6.5) -------------------------------\n\n/** A single delay tier: the `<topic>.retry.<n>` topic and the delay (ms) it holds for. */\nexport interface Tier {\n  topic: string;\n  delayMs: number;\n}\n\n/**\n * The SDK-owned retry/delay topology for one work topic: tiered delay topics\n * `<topic>.retry.<n>` (ascending) plus an opt-in `<topic>.dlq`. A delay or release with no\n * tiers configured raises rather than silently dropping.\n */\nexport class RetryTopics {\n  readonly tiers: Tier[];\n  readonly dlqTopic: string | null;\n\n  constructor(\n    readonly workTopic: string,\n    delaysMs: number[] = [],\n    dlqTopic: string | null | undefined = undefined,\n  ) {\n    this.tiers = [...delaysMs]\n      .sort((a, b) => a - b)\n      .map((delayMs, i) => ({ topic: `${workTopic}.retry.${i + 1}`, delayMs }));\n    this.dlqTopic = dlqTopic === undefined ? `${workTopic}.dlq` : dlqTopic;\n  }\n\n  hasTiers(): boolean {\n    return this.tiers.length > 0;\n  }\n\n  /** The smallest tier whose delay ≥ `delayMs`; raises if none configured or the delay is too large. */\n  tierForDelay(delayMs: number): Tier {\n    this.requireTiers();\n    for (const tier of this.tiers) {\n      if (tier.delayMs >= delayMs) return tier;\n    }\n    throw new BabelQueueError(\n      `Requested Kafka delay ${delayMs}ms exceeds the largest retry tier (${this.tiers[this.tiers.length - 1]!.delayMs}ms).`,\n    );\n  }\n\n  /** The tier for a retry at `attempt` (0-based), clamped to the largest; raises if none configured. */\n  tierForAttempt(attempt: number): Tier {\n    this.requireTiers();\n    return this.tiers[Math.min(Math.max(attempt, 0), this.tiers.length - 1)]!;\n  }\n\n  private requireTiers(): void {\n    if (!this.tiers.length) {\n      throw new BabelQueueError(`Kafka retry/delay requires retry topics; none are configured for '${this.workTopic}'.`);\n    }\n  }\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link KafkaPublisher.publish}. */\nexport interface PublishOptions {\n  traceId?: string;\n  /** Schedule via a retry tier (requires a {@link RetryTopics}); raises on a plain publisher. */\n  delayMs?: number;\n}\n\n/** Sends canonical-envelope messages to one Kafka work topic with the §6 projection. */\nexport class KafkaPublisher {\n  private constructor(\n    private readonly producer: KafkaProducerClient,\n    private readonly workTopic: string,\n    private readonly retryTopics?: RetryTopics,\n  ) {}\n\n  /** A publisher onto `topic` with no retry topics (a delay raises). */\n  static create(producer: KafkaProducerClient, topic: string): KafkaPublisher {\n    return new KafkaPublisher(producer, topic);\n  }\n\n  /** A publisher onto the topology's work topic, with delay routed via its retry tiers. */\n  static withRetryTopics(producer: KafkaProducerClient, retryTopics: RetryTopics): KafkaPublisher {\n    return new KafkaPublisher(producer, retryTopics.workTopic, retryTopics);\n  }\n\n  /** Build + send the canonical envelope; returns the message id (`meta.id`). */\n  async publish(urn: string, data: Record<string, unknown>, options: PublishOptions = {}): Promise<string> {\n    const envelope = EnvelopeCodec.make(urn, data, { queue: this.workTopic, traceId: options.traceId });\n    if (options.delayMs != null && options.delayMs > 0) {\n      if (!this.retryTopics) {\n        throw new BabelQueueError(\"Kafka has no native delayed delivery; a delay requires retry topics (none configured).\");\n      }\n      const tier = this.retryTopics.tierForDelay(options.delayMs);\n      await this.sendRecord(tier.topic, envelope, options.delayMs, this.workTopic);\n    } else {\n      await this.sendRecord(this.workTopic, envelope);\n    }\n    return envelope.meta.id;\n  }\n\n  private async sendRecord(topic: string, envelope: Envelope, delayMs?: number, originalTopic?: string): Promise<void> {\n    const headers = kafkaHeaders(envelope);\n    if (delayMs != null) headers[\"bq-delay\"] = String(delayMs);\n    if (originalTopic != null) headers[\"bq-original-topic\"] = originalTopic;\n    await this.producer.send({\n      topic,\n      messages: [{ value: EnvelopeCodec.encode(envelope), headers, timestamp: String(envelope.meta.created_at) }],\n    });\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw Kafka message. */\nexport type BabelHandler = (envelope: Envelope, message: KafkaIncomingMessage) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link KafkaConsumer}. */\nexport interface KafkaConsumerOptions {\n  /** The producer used to republish retry/DLQ records (required for retry/DLQ). */\n  producer?: KafkaProducerClient;\n  /** The retry/DLQ topology; enables per-record retry, delay, and dead-lettering. */\n  retryTopics?: RetryTopics;\n  /** Attempts before terminal dead-lettering (default 3). */\n  maxTries?: number;\n  /** Strategy for a URN with no handler (default `fail`). */\n  unknownUrn?: string;\n  /** Called for a poison record, an unmapped URN, or a throwing handler. */\n  onError?: (error: unknown, envelope: IncomingEnvelope | null, payload: EachMessagePayload) => void;\n}\n\n/**\n * Consumes a Kafka work topic in process-then-commit mode: each record is decoded, validated,\n * routed to the handler for its URN (read from `bq-job`), and its offset committed only after\n * the handler returns. A throwing handler republishes to a `<topic>.retry.<n>` tier with\n * `bq-attempts + 1`, then commits; terminal failures go to `<topic>.dlq` with a `dead_letter`\n * block. The `bq-attempts` header is the authoritative counter (the body is the fallback).\n */\nexport class KafkaConsumer {\n  private readonly maxTries: number;\n  private readonly unknownUrn: string;\n\n  constructor(\n    private readonly consumer: KafkaConsumerClient,\n    private readonly handlers: BabelHandlers,\n    private readonly options: KafkaConsumerOptions = {},\n  ) {\n    this.maxTries = options.maxTries ?? 3;\n    this.unknownUrn = options.unknownUrn ?? UnknownUrnStrategy.FAIL;\n  }\n\n  /** Start the manual-commit consume loop (`autoCommit: false`); resolves when the consumer stops. */\n  async run(): Promise<void> {\n    await this.consumer.run({ autoCommit: false, eachMessage: (payload) => this.handle(payload) });\n  }\n\n  /** Route + settle one record (process-then-commit). Exposed for testing. */\n  async handle(payload: EachMessagePayload): Promise<void> {\n    const { message } = payload;\n    const raw = message.value ? message.value.toString(\"utf8\") : \"\";\n\n    let envelope: IncomingEnvelope;\n    try {\n      envelope = this.reconcile(EnvelopeCodec.decode(raw), message);\n    } catch (decodeError) {\n      this.report(decodeError, null, payload);\n      await this.deadLetterRaw(payload);\n      await this.commit(payload);\n      return;\n    }\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      // A non-conformant / poison envelope may be missing the fields needed to annotate, so\n      // forward the raw record to the DLQ rather than building a dead_letter block.\n      this.report(new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from Kafka.\"), envelope, payload);\n      await this.deadLetterRaw(payload);\n      await this.commit(payload);\n      return;\n    }\n\n    const urn = headerString(message.headers, \"bq-job\") ?? EnvelopeCodec.urn(envelope);\n    const handler = this.handlers[urn];\n    if (!handler) {\n      await this.onUnknownUrn(payload, envelope, urn);\n      return;\n    }\n\n    try {\n      await handler(envelope, message);\n      await this.commit(payload);\n    } catch (error) {\n      this.report(error, envelope, payload);\n      await this.retryOrDeadLetter(payload, envelope as Envelope, error);\n      await this.commit(payload);\n    }\n  }\n\n  private reconcile(envelope: IncomingEnvelope, message: KafkaIncomingMessage): IncomingEnvelope {\n    const body = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n    return { ...envelope, attempts: headerInt(message.headers, \"bq-attempts\", body) };\n  }\n\n  private async onUnknownUrn(payload: EachMessagePayload, envelope: IncomingEnvelope, urn: string): Promise<void> {\n    switch (this.unknownUrn) {\n      case UnknownUrnStrategy.DELETE:\n        await this.commit(payload);\n        return;\n      case UnknownUrnStrategy.DEAD_LETTER:\n        await this.deadLetter(envelope as Envelope, payload, \"unknown_urn\");\n        await this.commit(payload);\n        return;\n      case UnknownUrnStrategy.RELEASE:\n        await this.republishRetry(payload, envelope as Envelope);\n        await this.commit(payload);\n        return;\n      default: {\n        // FAIL: surface and do NOT commit — the record redelivers on the next poll.\n        const error = new UnknownUrnError(urn);\n        this.report(error, envelope, payload);\n        throw error;\n      }\n    }\n  }\n\n  private async retryOrDeadLetter(payload: EachMessagePayload, envelope: Envelope, error: unknown): Promise<void> {\n    const hasTiers = this.options.retryTopics?.hasTiers() ?? false;\n    const hasDlq = (this.options.retryTopics?.dlqTopic ?? null) !== null;\n    if (!hasTiers && !hasDlq) {\n      void error; // reported via onError before this; Kafka has nowhere to put the failure\n      throw new BabelQueueError(\"Kafka per-record retry requires retry topics and/or a DLQ; neither is configured.\");\n    }\n    if (hasTiers && (envelope.attempts ?? 0) + 1 < this.maxTries) {\n      await this.republishRetry(payload, envelope);\n    } else {\n      await this.deadLetter(envelope, payload, \"failed\", error);\n    }\n  }\n\n  private async republishRetry(payload: EachMessagePayload, envelope: Envelope): Promise<void> {\n    const topics = this.options.retryTopics;\n    if (!topics || !topics.hasTiers()) {\n      throw new BabelQueueError(\"Kafka retry/release requires retry topics; none are configured.\");\n    }\n    const tier = topics.tierForAttempt(envelope.attempts ?? 0);\n    const bumped: Envelope = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };\n    const headers = kafkaHeaders(bumped);\n    headers[\"bq-delay\"] = String(tier.delayMs);\n    headers[\"bq-original-topic\"] = this.originalTopic(payload);\n    await this.produce(tier.topic, bumped, headers);\n  }\n\n  private async deadLetter(envelope: Envelope, payload: EachMessagePayload, reason: string, error?: unknown): Promise<void> {\n    const dlq = this.options.retryTopics?.dlqTopic ?? null;\n    if (!dlq) return; // dead-lettering disabled → degrade to commit-and-drop\n    const original = this.originalTopic(payload);\n    const annotated = annotate(envelope, reason, original, {\n      attempts: envelope.attempts ?? 0,\n      error: error instanceof Error ? error.message : null,\n      exception: error instanceof Error ? error.name : null,\n    });\n    const headers = kafkaHeaders(annotated);\n    headers[\"bq-original-topic\"] = original;\n    await this.produce(dlq, annotated, headers);\n  }\n\n  private async deadLetterRaw(payload: EachMessagePayload): Promise<void> {\n    const dlq = this.options.retryTopics?.dlqTopic ?? null;\n    if (!dlq) return;\n    this.requireProducer();\n    const { message } = payload;\n    await this.options.producer!.send({\n      topic: dlq,\n      messages: [{ value: message.value ?? Buffer.alloc(0), timestamp: String(Date.now()) }],\n    });\n  }\n\n  private async produce(topic: string, envelope: Envelope, headers: { [key: string]: string }): Promise<void> {\n    this.requireProducer();\n    await this.options.producer!.send({\n      topic,\n      messages: [{ value: EnvelopeCodec.encode(envelope), headers, timestamp: String(Date.now()) }],\n    });\n  }\n\n  private async commit(payload: EachMessagePayload): Promise<void> {\n    await this.consumer.commitOffsets([\n      { topic: payload.topic, partition: payload.partition, offset: (Number(payload.message.offset) + 1).toString() },\n    ]);\n  }\n\n  private originalTopic(payload: EachMessagePayload): string {\n    return headerString(payload.message.headers, \"bq-original-topic\") ?? payload.topic;\n  }\n\n  private requireProducer(): void {\n    if (!this.options.producer) {\n      throw new BabelQueueError(\"This Kafka consumer needs a producer to republish (retry/DLQ).\");\n    }\n  }\n\n  private report(error: unknown, envelope: IncomingEnvelope | null, payload: EachMessagePayload): void {\n    this.options.onError?.(error, envelope, payload);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,163 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Apache Kafka adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed, **process-then-commit** consumer over
+ * Apache Kafka (KafkaJS), so a Kafka-based Node service speaks the same contract (envelope
+ * shape, URN identity, trace propagation) as the .NET, Java, Python and Go SDKs.
+ *
+ * Kafka has **no native** per-message ack, delayed delivery, dead-letter queue, or delivery
+ * counter — this adapter absorbs all four in the binding layer (the envelope stays
+ * `schema_version: 1`): the envelope JSON is the record **value**; the contract fields are
+ * mirrored onto `bq-` headers (route on `bq-job` without decoding the body) and the record
+ * timestamp mirrors `meta.created_at`; **`bq-attempts` is the authoritative retry counter**;
+ * consume is process-then-commit (manual commit, at-least-once); retry/delay use SDK-owned
+ * tiered retry topics `<topic>.retry.<n>`; terminal failures go to an opt-in `<topic>.dlq`.
+ *
+ * This implements §6 of the broker-bindings contract. `kafkajs` is an optional peer — you
+ * provide the producer/consumer (a KafkaJS `Producer`/`Consumer` satisfies the adapter
+ * structurally).
+ */
+
+/** Incoming record headers (KafkaJS decodes header values to Buffers). */
+type IncomingHeaders = {
+    [key: string]: Buffer | string | (Buffer | string)[] | undefined;
+};
+/** A record to produce (structural subset of a KafkaJS message). */
+interface KafkaProducerMessage {
+    key?: Buffer | string | null;
+    value: Buffer | string;
+    headers?: {
+        [key: string]: string;
+    };
+    timestamp?: string;
+}
+/** The subset of the KafkaJS producer this adapter calls. */
+interface KafkaProducerClient {
+    send(record: {
+        topic: string;
+        messages: KafkaProducerMessage[];
+    }): Promise<unknown>;
+}
+/** A received record (structural subset of a KafkaJS message). */
+interface KafkaIncomingMessage {
+    value: Buffer | null;
+    headers?: IncomingHeaders;
+    offset: string;
+    timestamp?: string;
+    key?: Buffer | null;
+}
+/** The payload KafkaJS passes to `eachMessage`. */
+interface EachMessagePayload {
+    topic: string;
+    partition: number;
+    message: KafkaIncomingMessage;
+}
+/** The subset of the KafkaJS consumer this adapter calls (manual commit — `autoCommit: false`). */
+interface KafkaConsumerClient {
+    run(config: {
+        autoCommit?: boolean;
+        eachMessage: (payload: EachMessagePayload) => Promise<void>;
+    }): Promise<void>;
+    commitOffsets(offsets: {
+        topic: string;
+        partition: number;
+        offset: string;
+    }[]): Promise<void>;
+}
+/** Project the envelope's contract fields onto Kafka record headers (UTF-8 string values). */
+declare function kafkaHeaders(envelope: Envelope): {
+    [key: string]: string;
+};
+/** A single delay tier: the `<topic>.retry.<n>` topic and the delay (ms) it holds for. */
+interface Tier {
+    topic: string;
+    delayMs: number;
+}
+/**
+ * The SDK-owned retry/delay topology for one work topic: tiered delay topics
+ * `<topic>.retry.<n>` (ascending) plus an opt-in `<topic>.dlq`. A delay or release with no
+ * tiers configured raises rather than silently dropping.
+ */
+declare class RetryTopics {
+    readonly workTopic: string;
+    readonly tiers: Tier[];
+    readonly dlqTopic: string | null;
+    constructor(workTopic: string, delaysMs?: number[], dlqTopic?: string | null | undefined);
+    hasTiers(): boolean;
+    /** The smallest tier whose delay ≥ `delayMs`; raises if none configured or the delay is too large. */
+    tierForDelay(delayMs: number): Tier;
+    /** The tier for a retry at `attempt` (0-based), clamped to the largest; raises if none configured. */
+    tierForAttempt(attempt: number): Tier;
+    private requireTiers;
+}
+/** Options for {@link KafkaPublisher.publish}. */
+interface PublishOptions {
+    traceId?: string;
+    /** Schedule via a retry tier (requires a {@link RetryTopics}); raises on a plain publisher. */
+    delayMs?: number;
+}
+/** Sends canonical-envelope messages to one Kafka work topic with the §6 projection. */
+declare class KafkaPublisher {
+    private readonly producer;
+    private readonly workTopic;
+    private readonly retryTopics?;
+    private constructor();
+    /** A publisher onto `topic` with no retry topics (a delay raises). */
+    static create(producer: KafkaProducerClient, topic: string): KafkaPublisher;
+    /** A publisher onto the topology's work topic, with delay routed via its retry tiers. */
+    static withRetryTopics(producer: KafkaProducerClient, retryTopics: RetryTopics): KafkaPublisher;
+    /** Build + send the canonical envelope; returns the message id (`meta.id`). */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+    private sendRecord;
+}
+/** A URN handler. Receives the validated envelope and the raw Kafka message. */
+type BabelHandler = (envelope: Envelope, message: KafkaIncomingMessage) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link KafkaConsumer}. */
+interface KafkaConsumerOptions {
+    /** The producer used to republish retry/DLQ records (required for retry/DLQ). */
+    producer?: KafkaProducerClient;
+    /** The retry/DLQ topology; enables per-record retry, delay, and dead-lettering. */
+    retryTopics?: RetryTopics;
+    /** Attempts before terminal dead-lettering (default 3). */
+    maxTries?: number;
+    /** Strategy for a URN with no handler (default `fail`). */
+    unknownUrn?: string;
+    /** Called for a poison record, an unmapped URN, or a throwing handler. */
+    onError?: (error: unknown, envelope: IncomingEnvelope | null, payload: EachMessagePayload) => void;
+}
+/**
+ * Consumes a Kafka work topic in process-then-commit mode: each record is decoded, validated,
+ * routed to the handler for its URN (read from `bq-job`), and its offset committed only after
+ * the handler returns. A throwing handler republishes to a `<topic>.retry.<n>` tier with
+ * `bq-attempts + 1`, then commits; terminal failures go to `<topic>.dlq` with a `dead_letter`
+ * block. The `bq-attempts` header is the authoritative counter (the body is the fallback).
+ */
+declare class KafkaConsumer {
+    private readonly consumer;
+    private readonly handlers;
+    private readonly options;
+    private readonly maxTries;
+    private readonly unknownUrn;
+    constructor(consumer: KafkaConsumerClient, handlers: BabelHandlers, options?: KafkaConsumerOptions);
+    /** Start the manual-commit consume loop (`autoCommit: false`); resolves when the consumer stops. */
+    run(): Promise<void>;
+    /** Route + settle one record (process-then-commit). Exposed for testing. */
+    handle(payload: EachMessagePayload): Promise<void>;
+    private reconcile;
+    private onUnknownUrn;
+    private retryOrDeadLetter;
+    private republishRetry;
+    private deadLetter;
+    private deadLetterRaw;
+    private produce;
+    private commit;
+    private originalTopic;
+    private requireProducer;
+    private report;
+}
+
+export { type BabelHandler, type BabelHandlers, type EachMessagePayload, type IncomingHeaders, KafkaConsumer, type KafkaConsumerClient, type KafkaConsumerOptions, type KafkaIncomingMessage, type KafkaProducerClient, type KafkaProducerMessage, KafkaPublisher, type PublishOptions, RetryTopics, type Tier, kafkaHeaders };

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Apache Kafka adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed, **process-then-commit** consumer over
+ * Apache Kafka (KafkaJS), so a Kafka-based Node service speaks the same contract (envelope
+ * shape, URN identity, trace propagation) as the .NET, Java, Python and Go SDKs.
+ *
+ * Kafka has **no native** per-message ack, delayed delivery, dead-letter queue, or delivery
+ * counter — this adapter absorbs all four in the binding layer (the envelope stays
+ * `schema_version: 1`): the envelope JSON is the record **value**; the contract fields are
+ * mirrored onto `bq-` headers (route on `bq-job` without decoding the body) and the record
+ * timestamp mirrors `meta.created_at`; **`bq-attempts` is the authoritative retry counter**;
+ * consume is process-then-commit (manual commit, at-least-once); retry/delay use SDK-owned
+ * tiered retry topics `<topic>.retry.<n>`; terminal failures go to an opt-in `<topic>.dlq`.
+ *
+ * This implements §6 of the broker-bindings contract. `kafkajs` is an optional peer — you
+ * provide the producer/consumer (a KafkaJS `Producer`/`Consumer` satisfies the adapter
+ * structurally).
+ */
+
+/** Incoming record headers (KafkaJS decodes header values to Buffers). */
+type IncomingHeaders = {
+    [key: string]: Buffer | string | (Buffer | string)[] | undefined;
+};
+/** A record to produce (structural subset of a KafkaJS message). */
+interface KafkaProducerMessage {
+    key?: Buffer | string | null;
+    value: Buffer | string;
+    headers?: {
+        [key: string]: string;
+    };
+    timestamp?: string;
+}
+/** The subset of the KafkaJS producer this adapter calls. */
+interface KafkaProducerClient {
+    send(record: {
+        topic: string;
+        messages: KafkaProducerMessage[];
+    }): Promise<unknown>;
+}
+/** A received record (structural subset of a KafkaJS message). */
+interface KafkaIncomingMessage {
+    value: Buffer | null;
+    headers?: IncomingHeaders;
+    offset: string;
+    timestamp?: string;
+    key?: Buffer | null;
+}
+/** The payload KafkaJS passes to `eachMessage`. */
+interface EachMessagePayload {
+    topic: string;
+    partition: number;
+    message: KafkaIncomingMessage;
+}
+/** The subset of the KafkaJS consumer this adapter calls (manual commit — `autoCommit: false`). */
+interface KafkaConsumerClient {
+    run(config: {
+        autoCommit?: boolean;
+        eachMessage: (payload: EachMessagePayload) => Promise<void>;
+    }): Promise<void>;
+    commitOffsets(offsets: {
+        topic: string;
+        partition: number;
+        offset: string;
+    }[]): Promise<void>;
+}
+/** Project the envelope's contract fields onto Kafka record headers (UTF-8 string values). */
+declare function kafkaHeaders(envelope: Envelope): {
+    [key: string]: string;
+};
+/** A single delay tier: the `<topic>.retry.<n>` topic and the delay (ms) it holds for. */
+interface Tier {
+    topic: string;
+    delayMs: number;
+}
+/**
+ * The SDK-owned retry/delay topology for one work topic: tiered delay topics
+ * `<topic>.retry.<n>` (ascending) plus an opt-in `<topic>.dlq`. A delay or release with no
+ * tiers configured raises rather than silently dropping.
+ */
+declare class RetryTopics {
+    readonly workTopic: string;
+    readonly tiers: Tier[];
+    readonly dlqTopic: string | null;
+    constructor(workTopic: string, delaysMs?: number[], dlqTopic?: string | null | undefined);
+    hasTiers(): boolean;
+    /** The smallest tier whose delay ≥ `delayMs`; raises if none configured or the delay is too large. */
+    tierForDelay(delayMs: number): Tier;
+    /** The tier for a retry at `attempt` (0-based), clamped to the largest; raises if none configured. */
+    tierForAttempt(attempt: number): Tier;
+    private requireTiers;
+}
+/** Options for {@link KafkaPublisher.publish}. */
+interface PublishOptions {
+    traceId?: string;
+    /** Schedule via a retry tier (requires a {@link RetryTopics}); raises on a plain publisher. */
+    delayMs?: number;
+}
+/** Sends canonical-envelope messages to one Kafka work topic with the §6 projection. */
+declare class KafkaPublisher {
+    private readonly producer;
+    private readonly workTopic;
+    private readonly retryTopics?;
+    private constructor();
+    /** A publisher onto `topic` with no retry topics (a delay raises). */
+    static create(producer: KafkaProducerClient, topic: string): KafkaPublisher;
+    /** A publisher onto the topology's work topic, with delay routed via its retry tiers. */
+    static withRetryTopics(producer: KafkaProducerClient, retryTopics: RetryTopics): KafkaPublisher;
+    /** Build + send the canonical envelope; returns the message id (`meta.id`). */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+    private sendRecord;
+}
+/** A URN handler. Receives the validated envelope and the raw Kafka message. */
+type BabelHandler = (envelope: Envelope, message: KafkaIncomingMessage) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link KafkaConsumer}. */
+interface KafkaConsumerOptions {
+    /** The producer used to republish retry/DLQ records (required for retry/DLQ). */
+    producer?: KafkaProducerClient;
+    /** The retry/DLQ topology; enables per-record retry, delay, and dead-lettering. */
+    retryTopics?: RetryTopics;
+    /** Attempts before terminal dead-lettering (default 3). */
+    maxTries?: number;
+    /** Strategy for a URN with no handler (default `fail`). */
+    unknownUrn?: string;
+    /** Called for a poison record, an unmapped URN, or a throwing handler. */
+    onError?: (error: unknown, envelope: IncomingEnvelope | null, payload: EachMessagePayload) => void;
+}
+/**
+ * Consumes a Kafka work topic in process-then-commit mode: each record is decoded, validated,
+ * routed to the handler for its URN (read from `bq-job`), and its offset committed only after
+ * the handler returns. A throwing handler republishes to a `<topic>.retry.<n>` tier with
+ * `bq-attempts + 1`, then commits; terminal failures go to `<topic>.dlq` with a `dead_letter`
+ * block. The `bq-attempts` header is the authoritative counter (the body is the fallback).
+ */
+declare class KafkaConsumer {
+    private readonly consumer;
+    private readonly handlers;
+    private readonly options;
+    private readonly maxTries;
+    private readonly unknownUrn;
+    constructor(consumer: KafkaConsumerClient, handlers: BabelHandlers, options?: KafkaConsumerOptions);
+    /** Start the manual-commit consume loop (`autoCommit: false`); resolves when the consumer stops. */
+    run(): Promise<void>;
+    /** Route + settle one record (process-then-commit). Exposed for testing. */
+    handle(payload: EachMessagePayload): Promise<void>;
+    private reconcile;
+    private onUnknownUrn;
+    private retryOrDeadLetter;
+    private republishRetry;
+    private deadLetter;
+    private deadLetterRaw;
+    private produce;
+    private commit;
+    private originalTopic;
+    private requireProducer;
+    private report;
+}
+
+export { type BabelHandler, type BabelHandlers, type EachMessagePayload, type IncomingHeaders, KafkaConsumer, type KafkaConsumerClient, type KafkaConsumerOptions, type KafkaIncomingMessage, type KafkaProducerClient, type KafkaProducerMessage, KafkaPublisher, type PublishOptions, RetryTopics, type Tier, kafkaHeaders };

package/dist/index.js

@@ -0,0 +1,253 @@
+// src/index.ts
+import { annotate, BabelQueueError, EnvelopeCodec, UnknownUrnError, UnknownUrnStrategy } from "@babelqueue/core";
+function kafkaHeaders(envelope) {
+  const headers = {};
+  if (envelope.job) headers["bq-job"] = envelope.job;
+  if (envelope.trace_id) headers["bq-trace-id"] = envelope.trace_id;
+  if (envelope.meta.id) headers["bq-message-id"] = envelope.meta.id;
+  if (envelope.meta.schema_version != null) headers["bq-schema-version"] = String(envelope.meta.schema_version);
+  if (envelope.meta.lang) headers["bq-source-lang"] = envelope.meta.lang;
+  headers["bq-attempts"] = String(envelope.attempts ?? 0);
+  return headers;
+}
+function headerString(headers, key) {
+  const value = headers?.[key];
+  if (value === void 0) return void 0;
+  const v = Array.isArray(value) ? value[0] : value;
+  if (v === void 0) return void 0;
+  return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
+}
+function headerInt(headers, key, fallback) {
+  const s = headerString(headers, key);
+  if (s === void 0) return fallback;
+  const n = Number.parseInt(s.trim(), 10);
+  return Number.isNaN(n) ? fallback : n;
+}
+var RetryTopics = class {
+  constructor(workTopic, delaysMs = [], dlqTopic = void 0) {
+    this.workTopic = workTopic;
+    this.tiers = [...delaysMs].sort((a, b) => a - b).map((delayMs, i) => ({ topic: `${workTopic}.retry.${i + 1}`, delayMs }));
+    this.dlqTopic = dlqTopic === void 0 ? `${workTopic}.dlq` : dlqTopic;
+  }
+  workTopic;
+  tiers;
+  dlqTopic;
+  hasTiers() {
+    return this.tiers.length > 0;
+  }
+  /** The smallest tier whose delay ≥ `delayMs`; raises if none configured or the delay is too large. */
+  tierForDelay(delayMs) {
+    this.requireTiers();
+    for (const tier of this.tiers) {
+      if (tier.delayMs >= delayMs) return tier;
+    }
+    throw new BabelQueueError(
+      `Requested Kafka delay ${delayMs}ms exceeds the largest retry tier (${this.tiers[this.tiers.length - 1].delayMs}ms).`
+    );
+  }
+  /** The tier for a retry at `attempt` (0-based), clamped to the largest; raises if none configured. */
+  tierForAttempt(attempt) {
+    this.requireTiers();
+    return this.tiers[Math.min(Math.max(attempt, 0), this.tiers.length - 1)];
+  }
+  requireTiers() {
+    if (!this.tiers.length) {
+      throw new BabelQueueError(`Kafka retry/delay requires retry topics; none are configured for '${this.workTopic}'.`);
+    }
+  }
+};
+var KafkaPublisher = class _KafkaPublisher {
+  constructor(producer, workTopic, retryTopics) {
+    this.producer = producer;
+    this.workTopic = workTopic;
+    this.retryTopics = retryTopics;
+  }
+  producer;
+  workTopic;
+  retryTopics;
+  /** A publisher onto `topic` with no retry topics (a delay raises). */
+  static create(producer, topic) {
+    return new _KafkaPublisher(producer, topic);
+  }
+  /** A publisher onto the topology's work topic, with delay routed via its retry tiers. */
+  static withRetryTopics(producer, retryTopics) {
+    return new _KafkaPublisher(producer, retryTopics.workTopic, retryTopics);
+  }
+  /** Build + send the canonical envelope; returns the message id (`meta.id`). */
+  async publish(urn, data, options = {}) {
+    const envelope = EnvelopeCodec.make(urn, data, { queue: this.workTopic, traceId: options.traceId });
+    if (options.delayMs != null && options.delayMs > 0) {
+      if (!this.retryTopics) {
+        throw new BabelQueueError("Kafka has no native delayed delivery; a delay requires retry topics (none configured).");
+      }
+      const tier = this.retryTopics.tierForDelay(options.delayMs);
+      await this.sendRecord(tier.topic, envelope, options.delayMs, this.workTopic);
+    } else {
+      await this.sendRecord(this.workTopic, envelope);
+    }
+    return envelope.meta.id;
+  }
+  async sendRecord(topic, envelope, delayMs, originalTopic) {
+    const headers = kafkaHeaders(envelope);
+    if (delayMs != null) headers["bq-delay"] = String(delayMs);
+    if (originalTopic != null) headers["bq-original-topic"] = originalTopic;
+    await this.producer.send({
+      topic,
+      messages: [{ value: EnvelopeCodec.encode(envelope), headers, timestamp: String(envelope.meta.created_at) }]
+    });
+  }
+};
+var KafkaConsumer = class {
+  constructor(consumer, handlers, options = {}) {
+    this.consumer = consumer;
+    this.handlers = handlers;
+    this.options = options;
+    this.maxTries = options.maxTries ?? 3;
+    this.unknownUrn = options.unknownUrn ?? UnknownUrnStrategy.FAIL;
+  }
+  consumer;
+  handlers;
+  options;
+  maxTries;
+  unknownUrn;
+  /** Start the manual-commit consume loop (`autoCommit: false`); resolves when the consumer stops. */
+  async run() {
+    await this.consumer.run({ autoCommit: false, eachMessage: (payload) => this.handle(payload) });
+  }
+  /** Route + settle one record (process-then-commit). Exposed for testing. */
+  async handle(payload) {
+    const { message } = payload;
+    const raw = message.value ? message.value.toString("utf8") : "";
+    let envelope;
+    try {
+      envelope = this.reconcile(EnvelopeCodec.decode(raw), message);
+    } catch (decodeError) {
+      this.report(decodeError, null, payload);
+      await this.deadLetterRaw(payload);
+      await this.commit(payload);
+      return;
+    }
+    if (!EnvelopeCodec.accepts(envelope)) {
+      this.report(new BabelQueueError("Rejected a non-conformant BabelQueue envelope from Kafka."), envelope, payload);
+      await this.deadLetterRaw(payload);
+      await this.commit(payload);
+      return;
+    }
+    const urn = headerString(message.headers, "bq-job") ?? EnvelopeCodec.urn(envelope);
+    const handler = this.handlers[urn];
+    if (!handler) {
+      await this.onUnknownUrn(payload, envelope, urn);
+      return;
+    }
+    try {
+      await handler(envelope, message);
+      await this.commit(payload);
+    } catch (error) {
+      this.report(error, envelope, payload);
+      await this.retryOrDeadLetter(payload, envelope, error);
+      await this.commit(payload);
+    }
+  }
+  reconcile(envelope, message) {
+    const body = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+    return { ...envelope, attempts: headerInt(message.headers, "bq-attempts", body) };
+  }
+  async onUnknownUrn(payload, envelope, urn) {
+    switch (this.unknownUrn) {
+      case UnknownUrnStrategy.DELETE:
+        await this.commit(payload);
+        return;
+      case UnknownUrnStrategy.DEAD_LETTER:
+        await this.deadLetter(envelope, payload, "unknown_urn");
+        await this.commit(payload);
+        return;
+      case UnknownUrnStrategy.RELEASE:
+        await this.republishRetry(payload, envelope);
+        await this.commit(payload);
+        return;
+      default: {
+        const error = new UnknownUrnError(urn);
+        this.report(error, envelope, payload);
+        throw error;
+      }
+    }
+  }
+  async retryOrDeadLetter(payload, envelope, error) {
+    const hasTiers = this.options.retryTopics?.hasTiers() ?? false;
+    const hasDlq = (this.options.retryTopics?.dlqTopic ?? null) !== null;
+    if (!hasTiers && !hasDlq) {
+      void error;
+      throw new BabelQueueError("Kafka per-record retry requires retry topics and/or a DLQ; neither is configured.");
+    }
+    if (hasTiers && (envelope.attempts ?? 0) + 1 < this.maxTries) {
+      await this.republishRetry(payload, envelope);
+    } else {
+      await this.deadLetter(envelope, payload, "failed", error);
+    }
+  }
+  async republishRetry(payload, envelope) {
+    const topics = this.options.retryTopics;
+    if (!topics || !topics.hasTiers()) {
+      throw new BabelQueueError("Kafka retry/release requires retry topics; none are configured.");
+    }
+    const tier = topics.tierForAttempt(envelope.attempts ?? 0);
+    const bumped = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };
+    const headers = kafkaHeaders(bumped);
+    headers["bq-delay"] = String(tier.delayMs);
+    headers["bq-original-topic"] = this.originalTopic(payload);
+    await this.produce(tier.topic, bumped, headers);
+  }
+  async deadLetter(envelope, payload, reason, error) {
+    const dlq = this.options.retryTopics?.dlqTopic ?? null;
+    if (!dlq) return;
+    const original = this.originalTopic(payload);
+    const annotated = annotate(envelope, reason, original, {
+      attempts: envelope.attempts ?? 0,
+      error: error instanceof Error ? error.message : null,
+      exception: error instanceof Error ? error.name : null
+    });
+    const headers = kafkaHeaders(annotated);
+    headers["bq-original-topic"] = original;
+    await this.produce(dlq, annotated, headers);
+  }
+  async deadLetterRaw(payload) {
+    const dlq = this.options.retryTopics?.dlqTopic ?? null;
+    if (!dlq) return;
+    this.requireProducer();
+    const { message } = payload;
+    await this.options.producer.send({
+      topic: dlq,
+      messages: [{ value: message.value ?? Buffer.alloc(0), timestamp: String(Date.now()) }]
+    });
+  }
+  async produce(topic, envelope, headers) {
+    this.requireProducer();
+    await this.options.producer.send({
+      topic,
+      messages: [{ value: EnvelopeCodec.encode(envelope), headers, timestamp: String(Date.now()) }]
+    });
+  }
+  async commit(payload) {
+    await this.consumer.commitOffsets([
+      { topic: payload.topic, partition: payload.partition, offset: (Number(payload.message.offset) + 1).toString() }
+    ]);
+  }
+  originalTopic(payload) {
+    return headerString(payload.message.headers, "bq-original-topic") ?? payload.topic;
+  }
+  requireProducer() {
+    if (!this.options.producer) {
+      throw new BabelQueueError("This Kafka consumer needs a producer to republish (retry/DLQ).");
+    }
+  }
+  report(error, envelope, payload) {
+    this.options.onError?.(error, envelope, payload);
+  }
+};
+export {
+  KafkaConsumer,
+  KafkaPublisher,
+  RetryTopics,
+  kafkaHeaders
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Apache Kafka adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed, **process-then-commit** consumer over\n * Apache Kafka (KafkaJS), so a Kafka-based Node service speaks the same contract (envelope\n * shape, URN identity, trace propagation) as the .NET, Java, Python and Go SDKs.\n *\n * Kafka has **no native** per-message ack, delayed delivery, dead-letter queue, or delivery\n * counter — this adapter absorbs all four in the binding layer (the envelope stays\n * `schema_version: 1`): the envelope JSON is the record **value**; the contract fields are\n * mirrored onto `bq-` headers (route on `bq-job` without decoding the body) and the record\n * timestamp mirrors `meta.created_at`; **`bq-attempts` is the authoritative retry counter**;\n * consume is process-then-commit (manual commit, at-least-once); retry/delay use SDK-owned\n * tiered retry topics `<topic>.retry.<n>`; terminal failures go to an opt-in `<topic>.dlq`.\n *\n * This implements §6 of the broker-bindings contract. `kafkajs` is an optional peer — you\n * provide the producer/consumer (a KafkaJS `Producer`/`Consumer` satisfies the adapter\n * structurally).\n */\n\nimport { annotate, BabelQueueError, EnvelopeCodec, UnknownUrnError, UnknownUrnStrategy } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal Kafka shapes (a structural subset of kafkajs) ---------------------\n\n/** Incoming record headers (KafkaJS decodes header values to Buffers). */\nexport type IncomingHeaders = { [key: string]: Buffer | string | (Buffer | string)[] | undefined };\n\n/** A record to produce (structural subset of a KafkaJS message). */\nexport interface KafkaProducerMessage {\n  key?: Buffer | string | null;\n  value: Buffer | string;\n  headers?: { [key: string]: string };\n  timestamp?: string;\n}\n\n/** The subset of the KafkaJS producer this adapter calls. */\nexport interface KafkaProducerClient {\n  send(record: { topic: string; messages: KafkaProducerMessage[] }): Promise<unknown>;\n}\n\n/** A received record (structural subset of a KafkaJS message). */\nexport interface KafkaIncomingMessage {\n  value: Buffer | null;\n  headers?: IncomingHeaders;\n  offset: string;\n  timestamp?: string;\n  key?: Buffer | null;\n}\n\n/** The payload KafkaJS passes to `eachMessage`. */\nexport interface EachMessagePayload {\n  topic: string;\n  partition: number;\n  message: KafkaIncomingMessage;\n}\n\n/** The subset of the KafkaJS consumer this adapter calls (manual commit — `autoCommit: false`). */\nexport interface KafkaConsumerClient {\n  run(config: { autoCommit?: boolean; eachMessage: (payload: EachMessagePayload) => Promise<void> }): Promise<void>;\n  commitOffsets(offsets: { topic: string; partition: number; offset: string }[]): Promise<void>;\n}\n\n// --- Header projection (contract §6.3) -----------------------------------------\n\n/** Project the envelope's contract fields onto Kafka record headers (UTF-8 string values). */\nexport function kafkaHeaders(envelope: Envelope): { [key: string]: string } {\n  const headers: { [key: string]: string } = {};\n  if (envelope.job) headers[\"bq-job\"] = envelope.job;\n  if (envelope.trace_id) headers[\"bq-trace-id\"] = envelope.trace_id;\n  if (envelope.meta.id) headers[\"bq-message-id\"] = envelope.meta.id;\n  if (envelope.meta.schema_version != null) headers[\"bq-schema-version\"] = String(envelope.meta.schema_version);\n  if (envelope.meta.lang) headers[\"bq-source-lang\"] = envelope.meta.lang;\n  headers[\"bq-attempts\"] = String(envelope.attempts ?? 0);\n  return headers;\n}\n\nfunction headerString(headers: IncomingHeaders | undefined, key: string): string | undefined {\n  const value = headers?.[key];\n  if (value === undefined) return undefined;\n  const v = Array.isArray(value) ? value[0] : value;\n  if (v === undefined) return undefined;\n  return Buffer.isBuffer(v) ? v.toString(\"utf8\") : String(v);\n}\n\nfunction headerInt(headers: IncomingHeaders | undefined, key: string, fallback: number): number {\n  const s = headerString(headers, key);\n  if (s === undefined) return fallback;\n  const n = Number.parseInt(s.trim(), 10);\n  return Number.isNaN(n) ? fallback : n;\n}\n\n// --- Retry / delay topology (contract §6.4–§6.5) -------------------------------\n\n/** A single delay tier: the `<topic>.retry.<n>` topic and the delay (ms) it holds for. */\nexport interface Tier {\n  topic: string;\n  delayMs: number;\n}\n\n/**\n * The SDK-owned retry/delay topology for one work topic: tiered delay topics\n * `<topic>.retry.<n>` (ascending) plus an opt-in `<topic>.dlq`. A delay or release with no\n * tiers configured raises rather than silently dropping.\n */\nexport class RetryTopics {\n  readonly tiers: Tier[];\n  readonly dlqTopic: string | null;\n\n  constructor(\n    readonly workTopic: string,\n    delaysMs: number[] = [],\n    dlqTopic: string | null | undefined = undefined,\n  ) {\n    this.tiers = [...delaysMs]\n      .sort((a, b) => a - b)\n      .map((delayMs, i) => ({ topic: `${workTopic}.retry.${i + 1}`, delayMs }));\n    this.dlqTopic = dlqTopic === undefined ? `${workTopic}.dlq` : dlqTopic;\n  }\n\n  hasTiers(): boolean {\n    return this.tiers.length > 0;\n  }\n\n  /** The smallest tier whose delay ≥ `delayMs`; raises if none configured or the delay is too large. */\n  tierForDelay(delayMs: number): Tier {\n    this.requireTiers();\n    for (const tier of this.tiers) {\n      if (tier.delayMs >= delayMs) return tier;\n    }\n    throw new BabelQueueError(\n      `Requested Kafka delay ${delayMs}ms exceeds the largest retry tier (${this.tiers[this.tiers.length - 1]!.delayMs}ms).`,\n    );\n  }\n\n  /** The tier for a retry at `attempt` (0-based), clamped to the largest; raises if none configured. */\n  tierForAttempt(attempt: number): Tier {\n    this.requireTiers();\n    return this.tiers[Math.min(Math.max(attempt, 0), this.tiers.length - 1)]!;\n  }\n\n  private requireTiers(): void {\n    if (!this.tiers.length) {\n      throw new BabelQueueError(`Kafka retry/delay requires retry topics; none are configured for '${this.workTopic}'.`);\n    }\n  }\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link KafkaPublisher.publish}. */\nexport interface PublishOptions {\n  traceId?: string;\n  /** Schedule via a retry tier (requires a {@link RetryTopics}); raises on a plain publisher. */\n  delayMs?: number;\n}\n\n/** Sends canonical-envelope messages to one Kafka work topic with the §6 projection. */\nexport class KafkaPublisher {\n  private constructor(\n    private readonly producer: KafkaProducerClient,\n    private readonly workTopic: string,\n    private readonly retryTopics?: RetryTopics,\n  ) {}\n\n  /** A publisher onto `topic` with no retry topics (a delay raises). */\n  static create(producer: KafkaProducerClient, topic: string): KafkaPublisher {\n    return new KafkaPublisher(producer, topic);\n  }\n\n  /** A publisher onto the topology's work topic, with delay routed via its retry tiers. */\n  static withRetryTopics(producer: KafkaProducerClient, retryTopics: RetryTopics): KafkaPublisher {\n    return new KafkaPublisher(producer, retryTopics.workTopic, retryTopics);\n  }\n\n  /** Build + send the canonical envelope; returns the message id (`meta.id`). */\n  async publish(urn: string, data: Record<string, unknown>, options: PublishOptions = {}): Promise<string> {\n    const envelope = EnvelopeCodec.make(urn, data, { queue: this.workTopic, traceId: options.traceId });\n    if (options.delayMs != null && options.delayMs > 0) {\n      if (!this.retryTopics) {\n        throw new BabelQueueError(\"Kafka has no native delayed delivery; a delay requires retry topics (none configured).\");\n      }\n      const tier = this.retryTopics.tierForDelay(options.delayMs);\n      await this.sendRecord(tier.topic, envelope, options.delayMs, this.workTopic);\n    } else {\n      await this.sendRecord(this.workTopic, envelope);\n    }\n    return envelope.meta.id;\n  }\n\n  private async sendRecord(topic: string, envelope: Envelope, delayMs?: number, originalTopic?: string): Promise<void> {\n    const headers = kafkaHeaders(envelope);\n    if (delayMs != null) headers[\"bq-delay\"] = String(delayMs);\n    if (originalTopic != null) headers[\"bq-original-topic\"] = originalTopic;\n    await this.producer.send({\n      topic,\n      messages: [{ value: EnvelopeCodec.encode(envelope), headers, timestamp: String(envelope.meta.created_at) }],\n    });\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw Kafka message. */\nexport type BabelHandler = (envelope: Envelope, message: KafkaIncomingMessage) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link KafkaConsumer}. */\nexport interface KafkaConsumerOptions {\n  /** The producer used to republish retry/DLQ records (required for retry/DLQ). */\n  producer?: KafkaProducerClient;\n  /** The retry/DLQ topology; enables per-record retry, delay, and dead-lettering. */\n  retryTopics?: RetryTopics;\n  /** Attempts before terminal dead-lettering (default 3). */\n  maxTries?: number;\n  /** Strategy for a URN with no handler (default `fail`). */\n  unknownUrn?: string;\n  /** Called for a poison record, an unmapped URN, or a throwing handler. */\n  onError?: (error: unknown, envelope: IncomingEnvelope | null, payload: EachMessagePayload) => void;\n}\n\n/**\n * Consumes a Kafka work topic in process-then-commit mode: each record is decoded, validated,\n * routed to the handler for its URN (read from `bq-job`), and its offset committed only after\n * the handler returns. A throwing handler republishes to a `<topic>.retry.<n>` tier with\n * `bq-attempts + 1`, then commits; terminal failures go to `<topic>.dlq` with a `dead_letter`\n * block. The `bq-attempts` header is the authoritative counter (the body is the fallback).\n */\nexport class KafkaConsumer {\n  private readonly maxTries: number;\n  private readonly unknownUrn: string;\n\n  constructor(\n    private readonly consumer: KafkaConsumerClient,\n    private readonly handlers: BabelHandlers,\n    private readonly options: KafkaConsumerOptions = {},\n  ) {\n    this.maxTries = options.maxTries ?? 3;\n    this.unknownUrn = options.unknownUrn ?? UnknownUrnStrategy.FAIL;\n  }\n\n  /** Start the manual-commit consume loop (`autoCommit: false`); resolves when the consumer stops. */\n  async run(): Promise<void> {\n    await this.consumer.run({ autoCommit: false, eachMessage: (payload) => this.handle(payload) });\n  }\n\n  /** Route + settle one record (process-then-commit). Exposed for testing. */\n  async handle(payload: EachMessagePayload): Promise<void> {\n    const { message } = payload;\n    const raw = message.value ? message.value.toString(\"utf8\") : \"\";\n\n    let envelope: IncomingEnvelope;\n    try {\n      envelope = this.reconcile(EnvelopeCodec.decode(raw), message);\n    } catch (decodeError) {\n      this.report(decodeError, null, payload);\n      await this.deadLetterRaw(payload);\n      await this.commit(payload);\n      return;\n    }\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      // A non-conformant / poison envelope may be missing the fields needed to annotate, so\n      // forward the raw record to the DLQ rather than building a dead_letter block.\n      this.report(new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from Kafka.\"), envelope, payload);\n      await this.deadLetterRaw(payload);\n      await this.commit(payload);\n      return;\n    }\n\n    const urn = headerString(message.headers, \"bq-job\") ?? EnvelopeCodec.urn(envelope);\n    const handler = this.handlers[urn];\n    if (!handler) {\n      await this.onUnknownUrn(payload, envelope, urn);\n      return;\n    }\n\n    try {\n      await handler(envelope, message);\n      await this.commit(payload);\n    } catch (error) {\n      this.report(error, envelope, payload);\n      await this.retryOrDeadLetter(payload, envelope as Envelope, error);\n      await this.commit(payload);\n    }\n  }\n\n  private reconcile(envelope: IncomingEnvelope, message: KafkaIncomingMessage): IncomingEnvelope {\n    const body = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n    return { ...envelope, attempts: headerInt(message.headers, \"bq-attempts\", body) };\n  }\n\n  private async onUnknownUrn(payload: EachMessagePayload, envelope: IncomingEnvelope, urn: string): Promise<void> {\n    switch (this.unknownUrn) {\n      case UnknownUrnStrategy.DELETE:\n        await this.commit(payload);\n        return;\n      case UnknownUrnStrategy.DEAD_LETTER:\n        await this.deadLetter(envelope as Envelope, payload, \"unknown_urn\");\n        await this.commit(payload);\n        return;\n      case UnknownUrnStrategy.RELEASE:\n        await this.republishRetry(payload, envelope as Envelope);\n        await this.commit(payload);\n        return;\n      default: {\n        // FAIL: surface and do NOT commit — the record redelivers on the next poll.\n        const error = new UnknownUrnError(urn);\n        this.report(error, envelope, payload);\n        throw error;\n      }\n    }\n  }\n\n  private async retryOrDeadLetter(payload: EachMessagePayload, envelope: Envelope, error: unknown): Promise<void> {\n    const hasTiers = this.options.retryTopics?.hasTiers() ?? false;\n    const hasDlq = (this.options.retryTopics?.dlqTopic ?? null) !== null;\n    if (!hasTiers && !hasDlq) {\n      void error; // reported via onError before this; Kafka has nowhere to put the failure\n      throw new BabelQueueError(\"Kafka per-record retry requires retry topics and/or a DLQ; neither is configured.\");\n    }\n    if (hasTiers && (envelope.attempts ?? 0) + 1 < this.maxTries) {\n      await this.republishRetry(payload, envelope);\n    } else {\n      await this.deadLetter(envelope, payload, \"failed\", error);\n    }\n  }\n\n  private async republishRetry(payload: EachMessagePayload, envelope: Envelope): Promise<void> {\n    const topics = this.options.retryTopics;\n    if (!topics || !topics.hasTiers()) {\n      throw new BabelQueueError(\"Kafka retry/release requires retry topics; none are configured.\");\n    }\n    const tier = topics.tierForAttempt(envelope.attempts ?? 0);\n    const bumped: Envelope = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };\n    const headers = kafkaHeaders(bumped);\n    headers[\"bq-delay\"] = String(tier.delayMs);\n    headers[\"bq-original-topic\"] = this.originalTopic(payload);\n    await this.produce(tier.topic, bumped, headers);\n  }\n\n  private async deadLetter(envelope: Envelope, payload: EachMessagePayload, reason: string, error?: unknown): Promise<void> {\n    const dlq = this.options.retryTopics?.dlqTopic ?? null;\n    if (!dlq) return; // dead-lettering disabled → degrade to commit-and-drop\n    const original = this.originalTopic(payload);\n    const annotated = annotate(envelope, reason, original, {\n      attempts: envelope.attempts ?? 0,\n      error: error instanceof Error ? error.message : null,\n      exception: error instanceof Error ? error.name : null,\n    });\n    const headers = kafkaHeaders(annotated);\n    headers[\"bq-original-topic\"] = original;\n    await this.produce(dlq, annotated, headers);\n  }\n\n  private async deadLetterRaw(payload: EachMessagePayload): Promise<void> {\n    const dlq = this.options.retryTopics?.dlqTopic ?? null;\n    if (!dlq) return;\n    this.requireProducer();\n    const { message } = payload;\n    await this.options.producer!.send({\n      topic: dlq,\n      messages: [{ value: message.value ?? Buffer.alloc(0), timestamp: String(Date.now()) }],\n    });\n  }\n\n  private async produce(topic: string, envelope: Envelope, headers: { [key: string]: string }): Promise<void> {\n    this.requireProducer();\n    await this.options.producer!.send({\n      topic,\n      messages: [{ value: EnvelopeCodec.encode(envelope), headers, timestamp: String(Date.now()) }],\n    });\n  }\n\n  private async commit(payload: EachMessagePayload): Promise<void> {\n    await this.consumer.commitOffsets([\n      { topic: payload.topic, partition: payload.partition, offset: (Number(payload.message.offset) + 1).toString() },\n    ]);\n  }\n\n  private originalTopic(payload: EachMessagePayload): string {\n    return headerString(payload.message.headers, \"bq-original-topic\") ?? payload.topic;\n  }\n\n  private requireProducer(): void {\n    if (!this.options.producer) {\n      throw new BabelQueueError(\"This Kafka consumer needs a producer to republish (retry/DLQ).\");\n    }\n  }\n\n  private report(error: unknown, envelope: IncomingEnvelope | null, payload: EachMessagePayload): void {\n    this.options.onError?.(error, envelope, payload);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@babelqueue/kafka",
+  "version": "1.0.0",
+  "description": "Apache Kafka adapter for BabelQueue — canonical-envelope publisher and a URN-routed, process-then-commit consumer (SDK-owned retry topics + DLQ).",
+  "keywords": ["babelqueue", "kafka", "apache-kafka", "kafkajs", "queue", "polyglot", "messaging"],
+  "homepage": "https://babelqueue.com",
+  "bugs": {
+    "url": "https://github.com/BabelQueue/babelqueue-node-adapters/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BabelQueue/babelqueue-node-adapters.git",
+    "directory": "packages/kafka"
+  },
+  "license": "MIT",
+  "author": "Muhammet Şafak <info@muhammetsafak.com.tr>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@babelqueue/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "kafkajs": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "kafkajs": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}