@relaybus/kafka 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # @relaybus/kafka
 
+@relaybus/kafka is the Apache Kafka transport of relaybus, a reliable, storage-agnostic event bus for NestJS and Node.js: it forwards committed outbox events to Kafka topics and stores consumed events once in an idempotent inbox, so events are not lost between your database and Kafka.
+
 Apache Kafka transport for [relaybus](../../README.md). It forwards committed
 outbox events to Kafka topics and feeds events consumed from Kafka into the
 bus inbox, with at-least-once delivery and idempotent storage.
@@ -51,25 +53,26 @@ const consuming = transport.isConsuming();
 
 ## Options
 
-| Option                         | Default         | Meaning                                                                                                                                                                                          |
-| ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `kafka`                        | required        | A `kafkajs` `Kafka` or Confluent `KafkaJS.Kafka` instance. It is the producer/consumer factory.                                                                                                  |
-| `name`                         | `'kafka'`       | Transport name used by routes and subscriptions.                                                                                                                                                 |
-| `groupId`                      | none            | Consumer group. Required as soon as `subscribe` is used; publish-only services can omit it.                                                                                                      |
-| `fromBeginning`                | `true`          | Where a group without committed offsets starts. `true` so events published before the first start are not skipped.                                                                               |
-| `maxInFlightRequests`          | `1`             | Producer in-flight requests, 1 to 5. `1` keeps retries from reordering events of one key.                                                                                                        |
-| `producerConfig`               | `{}`            | Extra producer settings (partitioner, compression, ...). `idempotent` and `maxInFlightRequests` always win.                                                                                      |
-| `consumerConfig`               | `{}`            | Extra consumer settings (`sessionTimeout`, `retry`, `heartbeatInterval`, ...). `groupId` always wins.                                                                                            |
-| `processing.maxAttempts`       | `5`             | In-process attempts per delivery of a record.                                                                                                                                                    |
-| `processing.initialBackoff`    | `'200ms'`       | Delay before attempt 2, doubling per attempt.                                                                                                                                                    |
-| `processing.maxBackoff`        | `'5s'`          | Upper bound of the delay between attempts.                                                                                                                                                       |
-| `processing.heartbeatInterval` | `'1s'`          | Heartbeat interval while sleeping between attempts, so a long backoff never exceeds `sessionTimeout`.                                                                                            |
-| `startupTimeout`               | `'30s'`         | How long `subscribe` waits for the group join. A failed start-up disconnects the consumer it started.                                                                                            |
-| `publishTimeout`               | `'30s'`         | How long `publish` waits for the broker ack before rejecting with `PublishTimeoutError`.                                                                                                         |
-| `restart.initialBackoff`       | `'1s'`          | First delay of the consumer restart loop after an unrecoverable crash; doubles per failure.                                                                                                      |
-| `restart.maxBackoff`           | `'30s'`         | Upper bound of the restart delay.                                                                                                                                                                |
-| `onInvalidMessage`             | `'dead-letter'` | `'dead-letter'` (to `<topic>.dead`), `{ deadLetterTopic: string \| (sourceTopic) => string }`, a callback `(message) => void \| Promise<void>`, or `'skip'` (drops the record; explicit opt-in). |
-| `logger`                       | `console`       | `log`, `warn`, `error`. Messages start with `[KafkaTransport](method)`.                                                                                                                          |
+| Option                         | Default            | Meaning                                                                                                                                                                                                                                                                                                |
+| ------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `kafka`                        | required           | A `kafkajs` `Kafka` or Confluent `KafkaJS.Kafka` instance. It is the producer/consumer factory.                                                                                                                                                                                                        |
+| `name`                         | `'kafka'`          | Transport name used by routes and subscriptions.                                                                                                                                                                                                                                                       |
+| `groupId`                      | none               | Consumer group. Required as soon as `subscribe` is used; publish-only services can omit it.                                                                                                                                                                                                            |
+| `fromBeginning`                | `true`             | Where a group without committed offsets starts. `true` so events published before the first start are not skipped.                                                                                                                                                                                     |
+| `maxInFlightRequests`          | `1`                | Producer in-flight requests, 1 to 5. `1` keeps retries from reordering events of one key.                                                                                                                                                                                                              |
+| `producerConfig`               | `{}`               | Extra producer settings (partitioner, compression, ...). `idempotent` and `maxInFlightRequests` always win.                                                                                                                                                                                            |
+| `consumerConfig`               | `{}`               | Extra consumer settings (`sessionTimeout`, `retry`, `heartbeatInterval`, ...). `groupId` always wins.                                                                                                                                                                                                  |
+| `processing.maxAttempts`       | `5`                | In-process attempts per delivery of a record.                                                                                                                                                                                                                                                          |
+| `processing.initialBackoff`    | `'200ms'`          | Delay before attempt 2, doubling per attempt.                                                                                                                                                                                                                                                          |
+| `processing.maxBackoff`        | `'5s'`             | Upper bound of the delay between attempts.                                                                                                                                                                                                                                                             |
+| `processing.heartbeatInterval` | `'1s'`             | Heartbeat interval while sleeping between attempts, so a long backoff never exceeds `sessionTimeout`.                                                                                                                                                                                                  |
+| `startupTimeout`               | `'30s'`            | How long `subscribe` waits for the group join. A failed start-up disconnects the consumer it started.                                                                                                                                                                                                  |
+| `publishTimeout`               | `'30s'`            | How long `publish` waits for the broker ack before rejecting with `PublishTimeoutError`.                                                                                                                                                                                                               |
+| `restart.initialBackoff`       | `'1s'`             | First delay of the consumer restart loop after an unrecoverable crash; doubles per failure.                                                                                                                                                                                                            |
+| `restart.maxBackoff`           | `'30s'`            | Upper bound of the restart delay.                                                                                                                                                                                                                                                                      |
+| `onInvalidMessage`             | `'dead-letter'`    | `'dead-letter'` (to `<topic>.dead`), `{ deadLetterTopic: string \| (sourceTopic) => string }`, a callback `(message) => void \| Promise<void>`, or `'skip'` (drops the record; explicit opt-in).                                                                                                       |
+| `decode`                       | strict binary mode | How consumed records become events. `decodeCloudEvent` (binary and structured mode), `plainJsonDecoder({...})` (plain JSON from producers without relaybus) or your own function. See [Interoperating with services that do not use relaybus](#interoperating-with-services-that-do-not-use-relaybus). |
+| `logger`                       | `console`          | `log`, `warn`, `error`. Messages start with `[KafkaTransport](method)`.                                                                                                                                                                                                                                |
 
 ## Wire format
 
@@ -102,6 +105,85 @@ RFC 3339), are rejected on publish with `UnencodableEventError`, a `NonRetryable
 retrying cannot help. `Date` payload values become ISO strings. A header named `__proto__` is kept
 as ordinary data by the codec (kafkajs itself drops it when it builds the consumer's header object).
 
+## Interoperating with services that do not use relaybus
+
+**relaybus producer, other consumer.** Any Kafka client reads the record as is: the value is the
+JSON payload (UTF-8), the key is the event key, and the `ce_*` headers above carry the attributes.
+A plain consumer only needs `JSON.parse(value)` and the `ce_type` / `ce_id` headers. CloudEvents
+SDKs decode the record natively, because it is CloudEvents binary mode of the Kafka protocol
+binding: Java `io.cloudevents:cloudevents-kafka` (`CloudEventDeserializer`), Go `sdk-go`
+(`protocol/kafka_sarama`), and Spring Cloud Function / Spring Cloud Stream, which read the
+`ce_`-prefixed headers. Use `ce_id` to deduplicate: an outbox delivers at least once.
+
+**Other producer, relaybus consumer.** By default the transport accepts only binary-mode
+CloudEvents; anything else is malformed and dead-lettered, so a misconfigured producer cannot
+slip events in. Opt in per transport (one transport is one subscription) with `decode`:
+
+```ts
+import {
+  KafkaTransport,
+  decodeCloudEvent,
+  fromHeader,
+  fromPayloadField,
+  plainJsonDecoder,
+  type KafkaMessageDecoder,
+} from '@relaybus/kafka';
+
+// A Spring / Go / plain kafkajs producer writing JSON values with an `event-type` header.
+const transport = new KafkaTransport({
+  kafka,
+  groupId: 'billing',
+  decode: plainJsonDecoder({ type: fromHeader('event-type'), id: fromHeader('message-id') }),
+});
+
+// A topic that carries one kind of event; the ordering key from the payload.
+const oneEventType = plainJsonDecoder({
+  type: 'order.placed.v1',
+  key: fromPayloadField('orderId'),
+});
+
+// A CloudEvents SDK producer in structured mode (`content-type: application/cloudevents+json`).
+const cloudEvents: KafkaMessageDecoder = decodeCloudEvent;
+
+// Different formats per topic: switch on the record.
+const perTopic: KafkaMessageDecoder = (record) =>
+  record.topic === 'legacy.orders' ? oneEventType(record) : decodeCloudEvent(record);
+```
+
+| Decoder                    | Accepts                                                                                                                                                                                                                                        |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| default (`decodeEnvelope`) | Binary-mode CloudEvents only, strictly as described above. Unchanged.                                                                                                                                                                          |
+| `decodeCloudEvent`         | Binary mode as the default, plus structured mode: a JSON value with `specversion` `1.0`, `id`, `type`, `source`, optional `time` (else the record timestamp), `subject` (else the record key), `data` (the payload; `data_base64` is refused). |
+| `plainJsonDecoder(opts)`   | Any JSON value. A record that is a CloudEvent anyway (a `ce_specversion` header or a structured content type) goes through `decodeCloudEvent`, so relaybus and foreign producers can share a topic.                                            |
+| your function              | `(record) => ({ id, type, payload, ...optional })`. Missing fields are filled: `source` = topic, `key` = record key, `occurredAt` = record timestamp, `headers` = `{}`.                                                                        |
+
+`plainJsonDecoder` options (each extractor gets `{ topic, partition, offset, key, headers, payload, timestamp }`;
+an extractor returning `undefined` or `''` selects the default):
+
+| Option       | Default                              | Meaning                                                                                                                        |
+| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `type`       | required                             | A fixed event type, or an extractor such as `fromHeader('event-type')` or `fromPayloadField('type')`.                          |
+| `id`         | `kafka:<topic>:<partition>:<offset>` | Inbox dedup id. The default is stable across redeliveries of the record. Prefer a producer id when it may send an event twice. |
+| `key`        | the record key                       | Ordering key. A key that is not UTF-8 (Java `LongSerializer`) is base64-encoded.                                               |
+| `source`     | the topic                            | Fixed text or an extractor.                                                                                                    |
+| `occurredAt` | the record timestamp                 | Extractor returning a `Date`.                                                                                                  |
+
+Every record header becomes an event header (the last value of a repeated header; a value that is
+not valid UTF-8 is left out, so binary ids can never collide).
+
+**Guarantees stay the same.** Decoding runs again on every redelivery and must be deterministic;
+the inbox deduplicates on the id, so a redelivered record is stored and handled once. A record that
+cannot be decoded (not JSON, a tombstone, no type, an invalid type, an extractor returning a
+non-string) and anything a custom decoder throws go to `onInvalidMessage` (dead-letter by default)
+with the reason in `relaybus-invalid-reason`; the consumer keeps running. Per-key order is the
+Kafka partition order, as for relaybus producers.
+
+**Limits.** The derived id assumes offsets are never reused: deleting and recreating a topic
+restarts its offsets, so records after a recreation could collide with ids already in the inbox
+(within its retention). Two sends of one event by a producer are two offsets; only an id set by the
+producer (`id: fromHeader(...)`) dedupes them. Payloads must be JSON (Avro or Protobuf need your own
+decoder function, which must stay synchronous).
+
 ## Partitioning and ordering
 
 The key decides the partition. Events with the same key are consumed in publish order; events
@@ -214,3 +296,28 @@ kafkajs as the supported client.
   transport recovered it. Repeated `Restart failed` logs mean the broker or credentials are the problem.
 - `PublishTimeoutError`: no broker ack within `publishTimeout`; the outbox retries.
 - Events appear twice in logs but handlers run once: expected, the inbox deduplicates on the id.
+
+## When to use @relaybus/kafka, and when not to
+
+Use it to send events between services through Kafka without a dual write between your database and the broker. It is a transport, not a store: it needs `@relaybus/core` and a store, and `@confluentinc/kafka-javascript` support is experimental and untested.
+
+Documentation: <https://berkcansavur.github.io/relaybus/packages/kafka>
+
+### relaybus vs alternatives
+
+<!-- relaybus:snippet:comparison -->
+
+|                                                                      | What it is                                                                                                                                                | Survives a restart                | Written in your database transaction                                      | Choose it when                                                                                                       |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **relaybus**                                                         | Event bus built on the transactional outbox: PostgreSQL and MongoDB stores, Kafka and RabbitMQ transports, per-handler deliveries                         | Yes, events live in your database | Yes                                                                       | Events must never be lost or phantom, and handlers need retries, dead letters and ordering keys                      |
+| [`@nestjs/event-emitter`](https://docs.nestjs.com/techniques/events) | In-process event emitter built on `eventemitter2`                                                                                                         | No persistence is documented      | No                                                                        | Simple in-process notifications where losing an event on restart is acceptable                                       |
+| [`@nestjs/cqrs`](https://docs.nestjs.com/recipes/cqrs)               | CommandBus, QueryBus, EventBus and sagas; the docs say sagas and event handlers run in memory                                                             | No built-in persistence           | No                                                                        | You want CQRS structure; it can sit on top of an outbox                                                              |
+| [`@nestjs/outbox`](https://github.com/nestjs/outbox)                 | Transactional outbox module from the NestJS organisation: PostgreSQL, MySQL and in-memory stores, relay with leases and retries, dead-letter table, inbox | Yes with the database stores      | Yes                                                                       | You need MySQL, or a NestJS-organisation module; compare features with relaybus before choosing                      |
+| [BullMQ](https://docs.bullmq.io/)                                    | Job queue on Redis with retries, delayed jobs and flows; at-least-once in the worst case                                                                  | Yes, in Redis                     | No, jobs are stored in Redis and cannot join a SQL or MongoDB transaction | Your stack is Redis-based and background jobs matter more than event atomicity                                       |
+| [pg-boss](https://github.com/timgit/pg-boss)                         | Job queue on PostgreSQL using `SKIP LOCKED`, with retries, dead letter queues, scheduling and pub/sub; jobs can be created in your own transaction        | Yes, in PostgreSQL                | Yes, through its database adapters                                        | You want a PostgreSQL job queue with scheduling; relaybus is an event bus with per-handler deliveries and transports |
+| Kafka client directly                                                | A distributed log; the idempotent producer and transactions give exactly-once within Kafka                                                                | Yes, in Kafka                     | No, producing to Kafka is a second write                                  | You consume and produce only inside Kafka; add an outbox when a database write must be announced                     |
+
+This table summarises the vendors' own documentation as of October 2026; check their docs for current details.
+Full comparison and sources: <https://berkcansavur.github.io/relaybus/comparison>.
+
+<!-- relaybus:end -->

package/dist/index.cjs

@@ -149,17 +149,20 @@ function resolveTime(text, recordTimestamp) {
   if (text !== void 0 && text.length > 0) {
     return parseTime(text);
   }
-  const milliseconds = Number(recordTimestamp);
-  const time = new Date(milliseconds);
-  if (recordTimestamp === void 0 || recordTimestamp === "" || Number.isNaN(time.getTime())) {
+  const time = readRecordTimestamp(recordTimestamp);
+  if (time === void 0) {
     throw invalid(`${HEADER.time} is missing and the record has no usable timestamp`);
   }
   return time;
 }
-function parseTime(text) {
+function readRecordTimestamp(recordTimestamp) {
+  const time = new Date(Number(recordTimestamp));
+  return recordTimestamp === void 0 || recordTimestamp === "" || Number.isNaN(time.getTime()) ? void 0 : time;
+}
+function parseTime(text, label = HEADER.time) {
   const time = new Date(text);
   if (!RFC3339_PATTERN.test(text) || Number.isNaN(time.getTime())) {
-    throw invalid(`${HEADER.time} is not an RFC 3339 timestamp: '${text}'`);
+    throw invalid(`${label} is not an RFC 3339 timestamp: '${text}'`);
   }
   return time;
 }
@@ -175,12 +178,15 @@ function parsePayload(value) {
   }
 }
 function resolveKey(subject, recordKey) {
-  const keyText = recordKey === null ? null : decodeText(recordKey, true, "Message key");
+  const keyText = readRecordKey(recordKey);
   if (subject !== void 0 && keyText !== null && subject !== keyText) {
     throw invalid(`${HEADER.subject} does not match the message key`);
   }
   return subject ?? keyText;
 }
+function readRecordKey(recordKey) {
+  return recordKey === null ? null : decodeText(recordKey, true, "Message key");
+}
 function collectUserHeaders(headers) {
   const entries = [];
   for (const [name, value] of headers) {
@@ -208,6 +214,219 @@ function toOutgoingHeaders(incoming) {
 function toBufferOrString(value) {
   return typeof value === "string" ? value : Buffer.from(value);
 }
+var STRUCTURED_MEDIA_TYPE = "application/cloudevents+json";
+var exactUtf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+var SPEC_VERSION2 = "1.0";
+var SPEC_VERSION_HEADER = "ce_specversion";
+var STRUCTURED_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "specversion",
+  "id",
+  "type",
+  "source",
+  "time",
+  "subject",
+  "datacontenttype",
+  "dataschema",
+  "data",
+  "data_base64",
+  "correlationid",
+  "causationid"
+]);
+function decodeCloudEvent(record) {
+  const headers = readHeaders(record.headers);
+  if (mediaTypeOf(headers.get(CONTENT_TYPE)) !== STRUCTURED_MEDIA_TYPE) {
+    return decodeEnvelope(record);
+  }
+  const body = parsePayload(record.value);
+  if (!isJsonObject(body)) {
+    throw invalid("A structured CloudEvent must be a JSON object");
+  }
+  if (body["specversion"] !== SPEC_VERSION2) {
+    throw invalid(`specversion must be '${SPEC_VERSION2}'`);
+  }
+  const type = requiredAttribute(body, "type");
+  assertValidType(type, "type");
+  assertJsonDataContentType(optionalAttribute(body, "datacontenttype"));
+  if (Object.hasOwn(body, "data_base64")) {
+    throw invalid("data_base64 is not supported: relaybus payloads are JSON, send them as data");
+  }
+  const time = optionalAttribute(body, "time");
+  return {
+    id: requiredAttribute(body, "id"),
+    type,
+    source: requiredAttribute(body, "source"),
+    key: optionalAttribute(body, "subject") ?? readRecordKey(record.key),
+    payload: Object.hasOwn(body, "data") ? body["data"] : null,
+    headers: { ...collectUserHeaders(headers), ...extensionAttributes(body) },
+    correlationId: optionalAttribute(body, "correlationid") ?? null,
+    causationId: optionalAttribute(body, "causationid") ?? null,
+    occurredAt: time === void 0 ? requireRecordTimestamp(record) : parseTime(time, "time")
+  };
+}
+function plainJsonDecoder(options) {
+  if (typeof options.type === "string") {
+    core.assertEventType(options.type);
+  }
+  return (record) => {
+    const headers = readHeadersLeniently(record.headers);
+    if (record.headers?.[SPEC_VERSION_HEADER] !== void 0 || mediaTypeOf(headers[CONTENT_TYPE]) === STRUCTURED_MEDIA_TYPE) {
+      return decodeCloudEvent(record);
+    }
+    const plain = {
+      topic: record.topic,
+      partition: record.partition,
+      offset: record.offset,
+      key: readKeyLeniently(record.key),
+      headers,
+      payload: parsePayload(record.value),
+      timestamp: record.timestamp
+    };
+    const type = resolveText(options.type, plain, "type");
+    if (type === void 0) {
+      throw invalid("Record has no event type: the type option found none");
+    }
+    assertValidType(type, "The event type");
+    return {
+      id: resolveText(options.id, plain, "id") ?? `kafka:${record.topic}:${record.partition}:${record.offset}`,
+      type,
+      source: resolveText(options.source, plain, "source") ?? record.topic,
+      key: options.key === void 0 ? plain.key : resolveText(options.key, plain, "key") ?? null,
+      payload: plain.payload,
+      headers,
+      correlationId: null,
+      causationId: null,
+      occurredAt: resolveOccurredAt(options.occurredAt, plain, record)
+    };
+  };
+}
+function completeDecodedEvent(decoded, record) {
+  if (typeof decoded !== "object" || decoded === null) {
+    throw invalid("The decoder must return an event object synchronously");
+  }
+  if ("then" in decoded) {
+    observeRejection(decoded);
+    throw invalid("The decoder must return an event object synchronously");
+  }
+  const event = decoded;
+  return {
+    id: event.id,
+    type: event.type,
+    source: event.source ?? record.topic,
+    key: event.key === void 0 ? readRecordKey(record.key) : event.key,
+    payload: event.payload,
+    headers: event.headers ?? {},
+    correlationId: event.correlationId ?? null,
+    causationId: event.causationId ?? null,
+    occurredAt: event.occurredAt ?? requireRecordTimestamp(record)
+  };
+}
+function mediaTypeOf(contentType) {
+  return contentType?.split(";")[0]?.trim().toLowerCase();
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalAttribute(body, name) {
+  const value = body[name];
+  if (value !== void 0 && typeof value !== "string") {
+    throw invalid(`Attribute '${name}' must be a string`);
+  }
+  return value;
+}
+function requiredAttribute(body, name) {
+  const value = optionalAttribute(body, name);
+  if (value === void 0 || value.length === 0) {
+    throw invalid(`Attribute '${name}' is missing or empty`);
+  }
+  return value;
+}
+function assertValidType(type, label) {
+  try {
+    core.assertEventType(type);
+  } catch (error) {
+    throw invalid(`${label} is not a valid event type: ${error.message}`);
+  }
+}
+function assertJsonDataContentType(dataContentType) {
+  const mediaType = mediaTypeOf(dataContentType);
+  if (mediaType !== void 0 && mediaType !== "application/json" && mediaType !== "text/json" && !mediaType.endsWith("+json")) {
+    throw invalid(`datacontenttype must be JSON, received '${dataContentType}'`);
+  }
+}
+function extensionAttributes(body) {
+  return Object.fromEntries(
+    Object.entries(body).filter(
+      (entry) => !STRUCTURED_ATTRIBUTES.has(entry[0]) && typeof entry[1] === "string"
+    )
+  );
+}
+function requireRecordTimestamp(record) {
+  const time = readRecordTimestamp(record.timestamp);
+  if (time === void 0) {
+    throw invalid("The event has no time and the record has no usable timestamp");
+  }
+  return time;
+}
+function readHeadersLeniently(incoming) {
+  const entries = [];
+  for (const [name, raw] of Object.entries(incoming ?? {})) {
+    const value = Array.isArray(raw) ? raw.at(-1) : raw;
+    const text = value === void 0 ? void 0 : decodeUtf8OrUndefined(value);
+    if (text !== void 0) {
+      entries.push([name, text]);
+    }
+  }
+  return Object.fromEntries(entries);
+}
+function decodeUtf8OrUndefined(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return exactUtf8.decode(value);
+  } catch {
+    return void 0;
+  }
+}
+function readKeyLeniently(key) {
+  if (key === null) {
+    return null;
+  }
+  try {
+    return readRecordKey(key);
+  } catch {
+    return Buffer.from(key).toString("base64");
+  }
+}
+function resolveText(option, record, name) {
+  const value = typeof option === "function" ? option(record) : option;
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    observeRejection(value);
+    throw invalid(`The ${name} option returned ${typeof value}, expected a string`);
+  }
+  return value.length === 0 ? void 0 : value;
+}
+function resolveOccurredAt(option, plain, record) {
+  const value = option?.(plain);
+  if (value === void 0) {
+    return requireRecordTimestamp(record);
+  }
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    observeRejection(value);
+    throw invalid("The occurredAt option returned no valid Date");
+  }
+  return value;
+}
+function observeRejection(value) {
+  if (typeof value === "object" && value !== null && "then" in value) {
+    Promise.resolve(value).catch(() => void 0);
+  }
+}
+
+// src/kafka-transport.ts
 var PublishTimeoutError = class extends core.RelayBusError {
   name = "PublishTimeoutError";
 };
@@ -235,6 +454,7 @@ var KafkaTransport = class {
   #producerConfig;
   #consumerConfig;
   #invalidPolicy;
+  #decode;
   #logger;
   #settings;
   #sleepers = /* @__PURE__ */ new Set();
@@ -262,6 +482,7 @@ var KafkaTransport = class {
     this.#producerConfig = options.producerConfig ?? {};
     this.#consumerConfig = options.consumerConfig ?? {};
     this.#invalidPolicy = options.onInvalidMessage ?? "dead-letter";
+    this.#decode = options.decode;
     this.#logger = options.logger ?? console;
     this.#settings = resolveSettings(options);
   }
@@ -443,16 +664,13 @@ var KafkaTransport = class {
   async #handleMessage(payload, onMessage) {
     let envelope;
     try {
-      envelope = decodeEnvelope(payload.message);
+      envelope = this.#decodeRecord(payload);
     } catch (error) {
-      if (!(error instanceof InvalidKafkaMessageError)) {
+      if (this.#decode === void 0 && !(error instanceof InvalidKafkaMessageError)) {
         throw toHandlerFailure(error);
       }
-      await this.#withRetries(
-        payload,
-        "handleInvalid",
-        () => this.#handleInvalid(payload, error.message)
-      );
+      const reason = core.toErrorInfo(error).message;
+      await this.#withRetries(payload, "handleInvalid", () => this.#handleInvalid(payload, reason));
       return;
     }
     await this.#withRetries(payload, "deliver", async () => {
@@ -466,6 +684,21 @@ var KafkaTransport = class {
       }
     });
   }
+  #decodeRecord({ topic, partition, message }) {
+    if (this.#decode === void 0) {
+      return decodeEnvelope(message);
+    }
+    const record = {
+      topic,
+      partition,
+      offset: message.offset,
+      key: message.key,
+      value: message.value,
+      headers: message.headers,
+      timestamp: message.timestamp
+    };
+    return completeDecodedEvent(this.#decode(record), record);
+  }
   async #handleInvalid(payload, reason) {
     const { topic, partition, message } = payload;
     const location = `topic=${topic} partition=${partition} offset=${message.offset}`;
@@ -707,13 +940,44 @@ function toHandlerFailure(error) {
   const { name, message } = core.toErrorInfo(error);
   return new HandlerFailedError(`${name}: ${message}`);
 }
+function fromHeader(name) {
+  if (name.length === 0) {
+    throw new core.ConfigurationError("fromHeader needs a header name");
+  }
+  return (message) => Object.hasOwn(message.headers, name) ? message.headers[name] : void 0;
+}
+function fromPayloadField(path) {
+  const segments = path.split(".");
+  if (segments.some((segment) => segment.length === 0)) {
+    throw new core.ConfigurationError(
+      `fromPayloadField needs a dotted path of non-empty names, received '${path}'`
+    );
+  }
+  return (message) => {
+    let value = message.payload;
+    for (const segment of segments) {
+      if (typeof value !== "object" || value === null || !Object.hasOwn(value, segment)) {
+        return void 0;
+      }
+      value = value[segment];
+    }
+    if (typeof value === "string") {
+      return value;
+    }
+    return Number.isSafeInteger(value) ? String(value) : void 0;
+  };
+}
 
 exports.HandlerFailedError = HandlerFailedError;
 exports.InvalidKafkaMessageError = InvalidKafkaMessageError;
 exports.KafkaTransport = KafkaTransport;
 exports.PublishTimeoutError = PublishTimeoutError;
 exports.UnencodableEventError = UnencodableEventError;
+exports.decodeCloudEvent = decodeCloudEvent;
 exports.decodeEnvelope = decodeEnvelope;
 exports.encodeEnvelope = encodeEnvelope;
+exports.fromHeader = fromHeader;
+exports.fromPayloadField = fromPayloadField;
+exports.plainJsonDecoder = plainJsonDecoder;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map