@relaybus/kafka 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,42 @@
-import { RelayBusError, NonRetryableError, EventEnvelope, Duration, Transport, RelayBusLogger, TransportMessageHandler } from '@relaybus/core';
+import { RelayBusError, NonRetryableError, EventEnvelope, EventHeaders, Duration, Transport, RelayBusLogger, TransportMessageHandler, TransportSubscriptionHooks } from '@relaybus/core';
+import { JsonEnvelopeMapping } from '@relaybus/core/internal';
+export { fromHeader, fromPayloadField } from '@relaybus/core/internal';
+
+/** A Kafka record that cannot be turned into an {@link EventEnvelope}. Never retried. */
+declare class InvalidKafkaMessageError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/**
+ * An event that cannot be written to Kafka: its payload is not representable as
+ * JSON (`undefined`, a function, a symbol, a `BigInt`, a circular structure) or
+ * its `occurredAt` is not an RFC 3339 instant (invalid date, year outside 0..9999).
+ * Retrying cannot help, so it is a {@link NonRetryableError}.
+ */
+declare class UnencodableEventError extends NonRetryableError {
+    name: string;
+    readonly code: string;
+}
+/** `publish` did not get a broker ack within `publishTimeout`. The outbox retries it. */
+declare class PublishTimeoutError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/** The transport was closed: it no longer publishes or subscribes. */
+declare class TransportClosedError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/** The consumer did not join its group within `startupTimeout`. */
+declare class GroupJoinTimeoutError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/** A handler failure re-thrown to the Kafka client, stripped of anything that could make it fatal. */
+declare class HandlerFailedError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
 
 /**
  * Structural views of the Kafka client API used by this package.
@@ -97,18 +135,6 @@ interface KafkaClientLike {
     consumer(config: KafkaConsumerConfig): KafkaConsumerLike;
 }
 
-/** A Kafka record that cannot be turned into an {@link EventEnvelope}. Never retried. */
-declare class InvalidKafkaMessageError extends RelayBusError {
-}
-/**
- * An event that cannot be written to Kafka: its payload is not representable as
- * JSON (`undefined`, a function, a symbol, a `BigInt`, a circular structure) or
- * its `occurredAt` is not an RFC 3339 instant (invalid date, year outside 0..9999).
- * Retrying cannot help, so it is a {@link NonRetryableError}.
- */
-declare class UnencodableEventError extends NonRetryableError {
-    name: string;
-}
 /** The wire form of one event: a Kafka record in CloudEvents binary content mode. */
 interface EncodedMessage {
     readonly key: string | null;
@@ -143,6 +169,188 @@ declare function encodeEnvelope(envelope: EventEnvelope): EncodedMessage;
  */
 declare function decodeEnvelope(message: DecodableMessage): EventEnvelope;
 
+/** A consumed record as handed to a {@link KafkaMessageDecoder}. */
+interface KafkaInboundRecord extends DecodableMessage {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: string;
+}
+/**
+ * The event a decoder extracted from a record. `id`, `type` and `payload` are
+ * required; every other field may be left out and is then filled by the
+ * transport: `source` with the topic, `key` with the record key (UTF-8),
+ * `headers` with none, `correlationId` and `causationId` with null, and
+ * `occurredAt` with the record timestamp.
+ */
+interface DecodedEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly source?: string;
+    readonly key?: string | null;
+    readonly headers?: EventHeaders;
+    readonly correlationId?: string | null;
+    readonly causationId?: string | null;
+    readonly occurredAt?: Date;
+}
+/**
+ * Turns a consumed record into an event, for topics written by producers that
+ * do not use relaybus. Must be synchronous and free of side effects: it runs
+ * again on every redelivery, so the same record must always give the same
+ * event, above all the same `id`, which is what the inbox deduplicates on.
+ *
+ * Anything it throws marks the record as malformed: it goes to the transport's
+ * `onInvalidMessage` policy (dead-letter by default) and the consumer moves on.
+ * An event the bus then rejects (empty id, invalid type or time) is
+ * dead-lettered the same way.
+ */
+type KafkaMessageDecoder = (record: KafkaInboundRecord) => DecodedEvent;
+/** A plain JSON record, decoded for the extractor options of {@link plainJsonDecoder}. */
+interface PlainJsonRecord {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: string;
+    /**
+     * The record key as UTF-8 text, base64 when its bytes are not valid UTF-8
+     * (for example a key written by Java's `LongSerializer`), null when absent.
+     */
+    readonly key: string | null;
+    /**
+     * Every record header as text: the last value of a repeated header; a value
+     * that is not valid UTF-8 is left out.
+     */
+    readonly headers: EventHeaders;
+    /** The record value parsed as JSON. */
+    readonly payload: unknown;
+    /** Record timestamp in epoch milliseconds. */
+    readonly timestamp: string | undefined;
+}
+/** Options of {@link plainJsonDecoder}. Extractors returning undefined or `''` select the default. */
+interface PlainJsonDecoderOptions {
+    /**
+     * Event type handlers subscribe to: a fixed name for a topic that carries one
+     * kind of event, or an extractor such as `fromHeader('event-type')` or
+     * `fromPayloadField('type')`. Required; a record without a type is invalid.
+     */
+    readonly type: string | ((record: PlainJsonRecord) => string | undefined);
+    /**
+     * Event id the inbox deduplicates on, for example `fromHeader('message-id')`.
+     * Default, and fallback when the extractor finds none:
+     * `kafka:<topic>:<partition>:<offset>`, which is stable across redeliveries
+     * of the record. Prefer an id set by the producer when it may send the same
+     * event twice: two sends are two offsets, so only a producer id dedupes them.
+     */
+    readonly id?: (record: PlainJsonRecord) => string | undefined;
+    /** Ordering key. Default: the record key. When given, its result is final (undefined means no key). */
+    readonly key?: (record: PlainJsonRecord) => string | null | undefined;
+    /** Logical name of the producer. Default: the topic. */
+    readonly source?: string | ((record: PlainJsonRecord) => string | undefined);
+    /** When the event happened. Default: the record timestamp. */
+    readonly occurredAt?: (record: PlainJsonRecord) => Date | undefined;
+}
+/**
+ * Decodes a CloudEvents 1.0 record in either content mode of the Kafka
+ * protocol binding:
+ * - structured (`content-type: application/cloudevents+json`): the value is
+ *   a JSON object with `specversion`, `id`, `type`, `source` and optionally
+ *   `time`, `subject` (the key, else the record key), `data` (the payload,
+ *   null when absent) and a JSON `datacontenttype`. `data_base64` is refused,
+ *   because relaybus payloads are JSON. Extension attributes with string
+ *   values (`traceparent`, ...) become event headers, as do the record
+ *   headers; `correlationid` and `causationid` fill their envelope fields.
+ * - binary (anything else): exactly {@link decodeEnvelope}, the default decoder.
+ *
+ * @throws InvalidKafkaMessageError for a record that is neither.
+ */
+declare function decodeCloudEvent(record: DecodableMessage): EventEnvelope;
+/**
+ * Creates a decoder for records whose value is plain JSON, as written by a
+ * service that does not use relaybus (a plain kafkajs producer, Spring Kafka's
+ * `JsonSerializer`, a Go service): the value becomes the payload, the record
+ * headers become event headers, and the options say where the event type and
+ * id come from.
+ *
+ * A record that is a CloudEvent anyway (a `ce_specversion` header, or a
+ * structured `application/cloudevents+json` value) is decoded with
+ * {@link decodeCloudEvent} instead, so relaybus and foreign producers can share
+ * a topic. A missing or non-JSON value, a missing or invalid type, and an
+ * extractor returning anything but a string are invalid.
+ *
+ * ```ts
+ * new KafkaTransport({
+ *   kafka,
+ *   groupId: 'billing',
+ *   decode: plainJsonDecoder({ type: fromHeader('event-type'), id: fromHeader('message-id') }),
+ * });
+ * ```
+ *
+ * @throws ConfigurationError when a fixed `type` is not a valid event type.
+ */
+declare function plainJsonDecoder(options: PlainJsonDecoderOptions): KafkaMessageDecoder;
+
+/** The record a codec produces for one event. `timestamp` is epoch milliseconds in a string. */
+type KafkaEncodedRecord = KafkaOutgoingMessage & {
+    readonly timestamp?: string;
+};
+/**
+ * The wire format of a {@link KafkaTransport}: how an event becomes a record
+ * (`encode`, on publish) and a consumed record becomes an event (`decode`).
+ *
+ * Both must be synchronous and free of side effects. What `encode` throws
+ * fails the publish: the outbox retries it, unless it is a `NonRetryableError`
+ * such as {@link UnencodableEventError}. What `decode` throws marks the record
+ * as malformed: it goes to `onInvalidMessage` (dead-letter by default) and the
+ * consumer moves on. See {@link KafkaMessageDecoder} for the decode contract.
+ */
+interface KafkaCodec {
+    readonly encode: (envelope: EventEnvelope) => KafkaEncodedRecord;
+    readonly decode: KafkaMessageDecoder;
+}
+/**
+ * CloudEvents 1.0 binary content mode, the default: the value is the JSON
+ * payload, the attributes travel as `ce_*` headers ({@link encodeEnvelope}).
+ * Decoding is strict: any other record is malformed ({@link decodeEnvelope}).
+ */
+declare const cloudEventsBinary: KafkaCodec;
+/**
+ * CloudEvents 1.0 structured content mode: the value is one
+ * `application/cloudevents+json` document with the attributes and `data`.
+ * Decoding accepts structured and binary mode ({@link decodeCloudEvent}), so a
+ * topic can move from one to the other while both are in flight.
+ */
+declare const cloudEventsStructured: KafkaCodec;
+/**
+ * Where each value of a JSON message lives, for {@link jsonEnvelope}. Besides
+ * `{ body }` and `{ header }`, the id may be `'record-position'`: a consumed
+ * record gets `kafka:<topic>:<partition>:<offset>`, stable across redeliveries
+ * but different for two sends of one event. Records relaybus writes carry the
+ * event id in a `relaybus-event-id` header, which wins on read, so an outbox
+ * retry that sends an event twice is still deduplicated.
+ */
+type KafkaJsonEnvelopeMapping = JsonEnvelopeMapping<'record-position'>;
+/**
+ * A JSON wire format declared by a mapping, in both directions: for topics
+ * shared with services that wrap events in their own envelope
+ * (`{ "eventName": ..., "data": {...} }`, MassTransit) or send the bare
+ * payload. The record key is always the event key; when `occurredAt` is not
+ * mapped, the record timestamp carries it. Event headers that are message
+ * headers are written as they are, so a name the mapping uses for another
+ * field is refused with {@link UnencodableEventError}, as are `content-type`
+ * and `relaybus-event-id`.
+ *
+ * ```ts
+ * codec: jsonEnvelope({
+ *   type: { body: 'eventName' },
+ *   id: { body: 'messageId' },
+ *   payload: { body: 'data' },
+ *   correlationId: { body: 'meta.correlationId' },
+ * })
+ * ```
+ *
+ * @throws ConfigurationError for an incomplete or self-overlapping mapping.
+ */
+declare function jsonEnvelope(mapping: KafkaJsonEnvelopeMapping): KafkaCodec;
+
 /** A record the transport refused to hand to the bus because it is malformed. */
 interface InvalidKafkaMessage {
     readonly topic: string;
@@ -172,14 +380,6 @@ interface InvalidKafkaMessage {
 type InvalidMessagePolicy = 'dead-letter' | 'skip' | ((message: InvalidKafkaMessage) => void | Promise<void>) | {
     readonly deadLetterTopic: string | ((sourceTopic: string) => string);
 };
-/** `publish` did not get a broker ack within `publishTimeout`. The outbox retries it. */
-declare class PublishTimeoutError extends RelayBusError {
-    name: string;
-}
-/** A handler failure re-thrown to the Kafka client, stripped of anything that could make it fatal. */
-declare class HandlerFailedError extends RelayBusError {
-    name: string;
-}
 /** Bounded in-process retries around the inbound handler (the bus's `receive`). */
 interface KafkaProcessingOptions {
     /** Attempts per delivery of a record before the error is handed to the client. Default 5. */
@@ -224,12 +424,33 @@ interface KafkaTransportOptions {
     readonly restart?: KafkaRestartOptions;
     /** Handling of records that cannot be processed for good. Default `'dead-letter'`. */
     readonly onInvalidMessage?: InvalidMessagePolicy;
+    /**
+     * The wire format, both ways: how events become records and consumed records
+     * become events. Default {@link cloudEventsBinary}: CloudEvents binary mode,
+     * strict on read, so any other record is malformed and goes to
+     * `onInvalidMessage`. {@link cloudEventsStructured} writes structured mode
+     * and reads both, {@link jsonEnvelope} maps a JSON format of your own (an
+     * envelope with the payload inside, or the bare payload), and an object with
+     * `encode` and `decode` can do anything else. Whatever a non-default codec's
+     * `decode` throws marks the record as malformed, never crashes the consumer.
+     */
+    readonly codec?: KafkaCodec;
+    /**
+     * How consumed records become events; events are still written in
+     * CloudEvents binary mode.
+     *
+     * @deprecated Use `codec`: `decode: fn` is `codec: { encode: encodeEnvelope, decode: fn }`.
+     * Giving both `decode` and `codec` is a configuration error.
+     */
+    readonly decode?: KafkaMessageDecoder;
     /** Default `console`. */
     readonly logger?: RelayBusLogger;
 }
 /**
  * Kafka {@link Transport}. Events travel as CloudEvents binary-mode records
  * (`ce_*` headers, JSON value), so any CloudEvents-aware consumer can read them.
+ * The `codec` option changes the wire format, for example to read and write
+ * the JSON format of services that do not use relaybus.
  *
  * Publishing: idempotent producer, `acks=-1`, resolves after the broker ack and
  * rejects with {@link PublishTimeoutError} after `publishTimeout`. A timed-out
@@ -251,6 +472,7 @@ interface KafkaTransportOptions {
 declare class KafkaTransport implements Transport {
     #private;
     readonly name: string;
+    readonly system = "kafka";
     constructor(options: KafkaTransportOptions);
     /**
      * True while the consumer is joined to its group, not between a crash or
@@ -275,9 +497,9 @@ declare class KafkaTransport implements Transport {
      * @throws ConfigurationError when `groupId` is missing, `destinations` is empty
      * or the transport already subscribed (create one transport per subscription).
      */
-    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler): Promise<void>;
+    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler, hooks?: TransportSubscriptionHooks): Promise<void>;
     /** Stops consuming and disconnects the consumer and the producer. Safe to call twice. */
     close(): Promise<void>;
 }
 
-export { type DecodableMessage, type EncodedMessage, HandlerFailedError, type InvalidKafkaMessage, InvalidKafkaMessageError, type InvalidMessagePolicy, type KafkaBytes, type KafkaClientLike, type KafkaConsumerConfig, type KafkaConsumerEvent, type KafkaConsumerEventNames, type KafkaConsumerLike, type KafkaEachMessagePayload, type KafkaIncomingHeaders, type KafkaIncomingMessage, type KafkaOutgoingHeaders, type KafkaOutgoingMessage, type KafkaProcessingOptions, type KafkaProducerConfig, type KafkaProducerLike, type KafkaProducerRecord, type KafkaRestartOptions, type KafkaRunConfig, KafkaTransport, type KafkaTransportOptions, PublishTimeoutError, UnencodableEventError, decodeEnvelope, encodeEnvelope };
+export { type DecodableMessage, type DecodedEvent, type EncodedMessage, GroupJoinTimeoutError, HandlerFailedError, type InvalidKafkaMessage, InvalidKafkaMessageError, type InvalidMessagePolicy, type KafkaBytes, type KafkaClientLike, type KafkaCodec, type KafkaConsumerConfig, type KafkaConsumerEvent, type KafkaConsumerEventNames, type KafkaConsumerLike, type KafkaEachMessagePayload, type KafkaEncodedRecord, type KafkaInboundRecord, type KafkaIncomingHeaders, type KafkaIncomingMessage, type KafkaJsonEnvelopeMapping, type KafkaMessageDecoder, type KafkaOutgoingHeaders, type KafkaOutgoingMessage, type KafkaProcessingOptions, type KafkaProducerConfig, type KafkaProducerLike, type KafkaProducerRecord, type KafkaRestartOptions, type KafkaRunConfig, KafkaTransport, type KafkaTransportOptions, type PlainJsonDecoderOptions, type PlainJsonRecord, PublishTimeoutError, TransportClosedError, UnencodableEventError, cloudEventsBinary, cloudEventsStructured, decodeCloudEvent, decodeEnvelope, encodeEnvelope, jsonEnvelope, plainJsonDecoder };

package/dist/index.d.ts

@@ -1,4 +1,42 @@
-import { RelayBusError, NonRetryableError, EventEnvelope, Duration, Transport, RelayBusLogger, TransportMessageHandler } from '@relaybus/core';
+import { RelayBusError, NonRetryableError, EventEnvelope, EventHeaders, Duration, Transport, RelayBusLogger, TransportMessageHandler, TransportSubscriptionHooks } from '@relaybus/core';
+import { JsonEnvelopeMapping } from '@relaybus/core/internal';
+export { fromHeader, fromPayloadField } from '@relaybus/core/internal';
+
+/** A Kafka record that cannot be turned into an {@link EventEnvelope}. Never retried. */
+declare class InvalidKafkaMessageError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/**
+ * An event that cannot be written to Kafka: its payload is not representable as
+ * JSON (`undefined`, a function, a symbol, a `BigInt`, a circular structure) or
+ * its `occurredAt` is not an RFC 3339 instant (invalid date, year outside 0..9999).
+ * Retrying cannot help, so it is a {@link NonRetryableError}.
+ */
+declare class UnencodableEventError extends NonRetryableError {
+    name: string;
+    readonly code: string;
+}
+/** `publish` did not get a broker ack within `publishTimeout`. The outbox retries it. */
+declare class PublishTimeoutError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/** The transport was closed: it no longer publishes or subscribes. */
+declare class TransportClosedError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/** The consumer did not join its group within `startupTimeout`. */
+declare class GroupJoinTimeoutError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
+/** A handler failure re-thrown to the Kafka client, stripped of anything that could make it fatal. */
+declare class HandlerFailedError extends RelayBusError {
+    name: string;
+    readonly code: string;
+}
 
 /**
  * Structural views of the Kafka client API used by this package.
@@ -97,18 +135,6 @@ interface KafkaClientLike {
     consumer(config: KafkaConsumerConfig): KafkaConsumerLike;
 }
 
-/** A Kafka record that cannot be turned into an {@link EventEnvelope}. Never retried. */
-declare class InvalidKafkaMessageError extends RelayBusError {
-}
-/**
- * An event that cannot be written to Kafka: its payload is not representable as
- * JSON (`undefined`, a function, a symbol, a `BigInt`, a circular structure) or
- * its `occurredAt` is not an RFC 3339 instant (invalid date, year outside 0..9999).
- * Retrying cannot help, so it is a {@link NonRetryableError}.
- */
-declare class UnencodableEventError extends NonRetryableError {
-    name: string;
-}
 /** The wire form of one event: a Kafka record in CloudEvents binary content mode. */
 interface EncodedMessage {
     readonly key: string | null;
@@ -143,6 +169,188 @@ declare function encodeEnvelope(envelope: EventEnvelope): EncodedMessage;
  */
 declare function decodeEnvelope(message: DecodableMessage): EventEnvelope;
 
+/** A consumed record as handed to a {@link KafkaMessageDecoder}. */
+interface KafkaInboundRecord extends DecodableMessage {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: string;
+}
+/**
+ * The event a decoder extracted from a record. `id`, `type` and `payload` are
+ * required; every other field may be left out and is then filled by the
+ * transport: `source` with the topic, `key` with the record key (UTF-8),
+ * `headers` with none, `correlationId` and `causationId` with null, and
+ * `occurredAt` with the record timestamp.
+ */
+interface DecodedEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly source?: string;
+    readonly key?: string | null;
+    readonly headers?: EventHeaders;
+    readonly correlationId?: string | null;
+    readonly causationId?: string | null;
+    readonly occurredAt?: Date;
+}
+/**
+ * Turns a consumed record into an event, for topics written by producers that
+ * do not use relaybus. Must be synchronous and free of side effects: it runs
+ * again on every redelivery, so the same record must always give the same
+ * event, above all the same `id`, which is what the inbox deduplicates on.
+ *
+ * Anything it throws marks the record as malformed: it goes to the transport's
+ * `onInvalidMessage` policy (dead-letter by default) and the consumer moves on.
+ * An event the bus then rejects (empty id, invalid type or time) is
+ * dead-lettered the same way.
+ */
+type KafkaMessageDecoder = (record: KafkaInboundRecord) => DecodedEvent;
+/** A plain JSON record, decoded for the extractor options of {@link plainJsonDecoder}. */
+interface PlainJsonRecord {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: string;
+    /**
+     * The record key as UTF-8 text, base64 when its bytes are not valid UTF-8
+     * (for example a key written by Java's `LongSerializer`), null when absent.
+     */
+    readonly key: string | null;
+    /**
+     * Every record header as text: the last value of a repeated header; a value
+     * that is not valid UTF-8 is left out.
+     */
+    readonly headers: EventHeaders;
+    /** The record value parsed as JSON. */
+    readonly payload: unknown;
+    /** Record timestamp in epoch milliseconds. */
+    readonly timestamp: string | undefined;
+}
+/** Options of {@link plainJsonDecoder}. Extractors returning undefined or `''` select the default. */
+interface PlainJsonDecoderOptions {
+    /**
+     * Event type handlers subscribe to: a fixed name for a topic that carries one
+     * kind of event, or an extractor such as `fromHeader('event-type')` or
+     * `fromPayloadField('type')`. Required; a record without a type is invalid.
+     */
+    readonly type: string | ((record: PlainJsonRecord) => string | undefined);
+    /**
+     * Event id the inbox deduplicates on, for example `fromHeader('message-id')`.
+     * Default, and fallback when the extractor finds none:
+     * `kafka:<topic>:<partition>:<offset>`, which is stable across redeliveries
+     * of the record. Prefer an id set by the producer when it may send the same
+     * event twice: two sends are two offsets, so only a producer id dedupes them.
+     */
+    readonly id?: (record: PlainJsonRecord) => string | undefined;
+    /** Ordering key. Default: the record key. When given, its result is final (undefined means no key). */
+    readonly key?: (record: PlainJsonRecord) => string | null | undefined;
+    /** Logical name of the producer. Default: the topic. */
+    readonly source?: string | ((record: PlainJsonRecord) => string | undefined);
+    /** When the event happened. Default: the record timestamp. */
+    readonly occurredAt?: (record: PlainJsonRecord) => Date | undefined;
+}
+/**
+ * Decodes a CloudEvents 1.0 record in either content mode of the Kafka
+ * protocol binding:
+ * - structured (`content-type: application/cloudevents+json`): the value is
+ *   a JSON object with `specversion`, `id`, `type`, `source` and optionally
+ *   `time`, `subject` (the key, else the record key), `data` (the payload,
+ *   null when absent) and a JSON `datacontenttype`. `data_base64` is refused,
+ *   because relaybus payloads are JSON. Extension attributes with string
+ *   values (`traceparent`, ...) become event headers, as do the record
+ *   headers; `correlationid` and `causationid` fill their envelope fields.
+ * - binary (anything else): exactly {@link decodeEnvelope}, the default decoder.
+ *
+ * @throws InvalidKafkaMessageError for a record that is neither.
+ */
+declare function decodeCloudEvent(record: DecodableMessage): EventEnvelope;
+/**
+ * Creates a decoder for records whose value is plain JSON, as written by a
+ * service that does not use relaybus (a plain kafkajs producer, Spring Kafka's
+ * `JsonSerializer`, a Go service): the value becomes the payload, the record
+ * headers become event headers, and the options say where the event type and
+ * id come from.
+ *
+ * A record that is a CloudEvent anyway (a `ce_specversion` header, or a
+ * structured `application/cloudevents+json` value) is decoded with
+ * {@link decodeCloudEvent} instead, so relaybus and foreign producers can share
+ * a topic. A missing or non-JSON value, a missing or invalid type, and an
+ * extractor returning anything but a string are invalid.
+ *
+ * ```ts
+ * new KafkaTransport({
+ *   kafka,
+ *   groupId: 'billing',
+ *   decode: plainJsonDecoder({ type: fromHeader('event-type'), id: fromHeader('message-id') }),
+ * });
+ * ```
+ *
+ * @throws ConfigurationError when a fixed `type` is not a valid event type.
+ */
+declare function plainJsonDecoder(options: PlainJsonDecoderOptions): KafkaMessageDecoder;
+
+/** The record a codec produces for one event. `timestamp` is epoch milliseconds in a string. */
+type KafkaEncodedRecord = KafkaOutgoingMessage & {
+    readonly timestamp?: string;
+};
+/**
+ * The wire format of a {@link KafkaTransport}: how an event becomes a record
+ * (`encode`, on publish) and a consumed record becomes an event (`decode`).
+ *
+ * Both must be synchronous and free of side effects. What `encode` throws
+ * fails the publish: the outbox retries it, unless it is a `NonRetryableError`
+ * such as {@link UnencodableEventError}. What `decode` throws marks the record
+ * as malformed: it goes to `onInvalidMessage` (dead-letter by default) and the
+ * consumer moves on. See {@link KafkaMessageDecoder} for the decode contract.
+ */
+interface KafkaCodec {
+    readonly encode: (envelope: EventEnvelope) => KafkaEncodedRecord;
+    readonly decode: KafkaMessageDecoder;
+}
+/**
+ * CloudEvents 1.0 binary content mode, the default: the value is the JSON
+ * payload, the attributes travel as `ce_*` headers ({@link encodeEnvelope}).
+ * Decoding is strict: any other record is malformed ({@link decodeEnvelope}).
+ */
+declare const cloudEventsBinary: KafkaCodec;
+/**
+ * CloudEvents 1.0 structured content mode: the value is one
+ * `application/cloudevents+json` document with the attributes and `data`.
+ * Decoding accepts structured and binary mode ({@link decodeCloudEvent}), so a
+ * topic can move from one to the other while both are in flight.
+ */
+declare const cloudEventsStructured: KafkaCodec;
+/**
+ * Where each value of a JSON message lives, for {@link jsonEnvelope}. Besides
+ * `{ body }` and `{ header }`, the id may be `'record-position'`: a consumed
+ * record gets `kafka:<topic>:<partition>:<offset>`, stable across redeliveries
+ * but different for two sends of one event. Records relaybus writes carry the
+ * event id in a `relaybus-event-id` header, which wins on read, so an outbox
+ * retry that sends an event twice is still deduplicated.
+ */
+type KafkaJsonEnvelopeMapping = JsonEnvelopeMapping<'record-position'>;
+/**
+ * A JSON wire format declared by a mapping, in both directions: for topics
+ * shared with services that wrap events in their own envelope
+ * (`{ "eventName": ..., "data": {...} }`, MassTransit) or send the bare
+ * payload. The record key is always the event key; when `occurredAt` is not
+ * mapped, the record timestamp carries it. Event headers that are message
+ * headers are written as they are, so a name the mapping uses for another
+ * field is refused with {@link UnencodableEventError}, as are `content-type`
+ * and `relaybus-event-id`.
+ *
+ * ```ts
+ * codec: jsonEnvelope({
+ *   type: { body: 'eventName' },
+ *   id: { body: 'messageId' },
+ *   payload: { body: 'data' },
+ *   correlationId: { body: 'meta.correlationId' },
+ * })
+ * ```
+ *
+ * @throws ConfigurationError for an incomplete or self-overlapping mapping.
+ */
+declare function jsonEnvelope(mapping: KafkaJsonEnvelopeMapping): KafkaCodec;
+
 /** A record the transport refused to hand to the bus because it is malformed. */
 interface InvalidKafkaMessage {
     readonly topic: string;
@@ -172,14 +380,6 @@ interface InvalidKafkaMessage {
 type InvalidMessagePolicy = 'dead-letter' | 'skip' | ((message: InvalidKafkaMessage) => void | Promise<void>) | {
     readonly deadLetterTopic: string | ((sourceTopic: string) => string);
 };
-/** `publish` did not get a broker ack within `publishTimeout`. The outbox retries it. */
-declare class PublishTimeoutError extends RelayBusError {
-    name: string;
-}
-/** A handler failure re-thrown to the Kafka client, stripped of anything that could make it fatal. */
-declare class HandlerFailedError extends RelayBusError {
-    name: string;
-}
 /** Bounded in-process retries around the inbound handler (the bus's `receive`). */
 interface KafkaProcessingOptions {
     /** Attempts per delivery of a record before the error is handed to the client. Default 5. */
@@ -224,12 +424,33 @@ interface KafkaTransportOptions {
     readonly restart?: KafkaRestartOptions;
     /** Handling of records that cannot be processed for good. Default `'dead-letter'`. */
     readonly onInvalidMessage?: InvalidMessagePolicy;
+    /**
+     * The wire format, both ways: how events become records and consumed records
+     * become events. Default {@link cloudEventsBinary}: CloudEvents binary mode,
+     * strict on read, so any other record is malformed and goes to
+     * `onInvalidMessage`. {@link cloudEventsStructured} writes structured mode
+     * and reads both, {@link jsonEnvelope} maps a JSON format of your own (an
+     * envelope with the payload inside, or the bare payload), and an object with
+     * `encode` and `decode` can do anything else. Whatever a non-default codec's
+     * `decode` throws marks the record as malformed, never crashes the consumer.
+     */
+    readonly codec?: KafkaCodec;
+    /**
+     * How consumed records become events; events are still written in
+     * CloudEvents binary mode.
+     *
+     * @deprecated Use `codec`: `decode: fn` is `codec: { encode: encodeEnvelope, decode: fn }`.
+     * Giving both `decode` and `codec` is a configuration error.
+     */
+    readonly decode?: KafkaMessageDecoder;
     /** Default `console`. */
     readonly logger?: RelayBusLogger;
 }
 /**
  * Kafka {@link Transport}. Events travel as CloudEvents binary-mode records
  * (`ce_*` headers, JSON value), so any CloudEvents-aware consumer can read them.
+ * The `codec` option changes the wire format, for example to read and write
+ * the JSON format of services that do not use relaybus.
  *
  * Publishing: idempotent producer, `acks=-1`, resolves after the broker ack and
  * rejects with {@link PublishTimeoutError} after `publishTimeout`. A timed-out
@@ -251,6 +472,7 @@ interface KafkaTransportOptions {
 declare class KafkaTransport implements Transport {
     #private;
     readonly name: string;
+    readonly system = "kafka";
     constructor(options: KafkaTransportOptions);
     /**
      * True while the consumer is joined to its group, not between a crash or
@@ -275,9 +497,9 @@ declare class KafkaTransport implements Transport {
      * @throws ConfigurationError when `groupId` is missing, `destinations` is empty
      * or the transport already subscribed (create one transport per subscription).
      */
-    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler): Promise<void>;
+    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler, hooks?: TransportSubscriptionHooks): Promise<void>;
     /** Stops consuming and disconnects the consumer and the producer. Safe to call twice. */
     close(): Promise<void>;
 }
 
-export { type DecodableMessage, type EncodedMessage, HandlerFailedError, type InvalidKafkaMessage, InvalidKafkaMessageError, type InvalidMessagePolicy, type KafkaBytes, type KafkaClientLike, type KafkaConsumerConfig, type KafkaConsumerEvent, type KafkaConsumerEventNames, type KafkaConsumerLike, type KafkaEachMessagePayload, type KafkaIncomingHeaders, type KafkaIncomingMessage, type KafkaOutgoingHeaders, type KafkaOutgoingMessage, type KafkaProcessingOptions, type KafkaProducerConfig, type KafkaProducerLike, type KafkaProducerRecord, type KafkaRestartOptions, type KafkaRunConfig, KafkaTransport, type KafkaTransportOptions, PublishTimeoutError, UnencodableEventError, decodeEnvelope, encodeEnvelope };
+export { type DecodableMessage, type DecodedEvent, type EncodedMessage, GroupJoinTimeoutError, HandlerFailedError, type InvalidKafkaMessage, InvalidKafkaMessageError, type InvalidMessagePolicy, type KafkaBytes, type KafkaClientLike, type KafkaCodec, type KafkaConsumerConfig, type KafkaConsumerEvent, type KafkaConsumerEventNames, type KafkaConsumerLike, type KafkaEachMessagePayload, type KafkaEncodedRecord, type KafkaInboundRecord, type KafkaIncomingHeaders, type KafkaIncomingMessage, type KafkaJsonEnvelopeMapping, type KafkaMessageDecoder, type KafkaOutgoingHeaders, type KafkaOutgoingMessage, type KafkaProcessingOptions, type KafkaProducerConfig, type KafkaProducerLike, type KafkaProducerRecord, type KafkaRestartOptions, type KafkaRunConfig, KafkaTransport, type KafkaTransportOptions, type PlainJsonDecoderOptions, type PlainJsonRecord, PublishTimeoutError, TransportClosedError, UnencodableEventError, cloudEventsBinary, cloudEventsStructured, decodeCloudEvent, decodeEnvelope, encodeEnvelope, jsonEnvelope, plainJsonDecoder };