@drarzter/kafka-client 0.9.4 → 0.11.0

package/dist/client/message/envelope.d.ts

@@ -0,0 +1,105 @@
+import type { MessageHeaders } from "../types";
+export declare const HEADER_EVENT_ID = "x-event-id";
+export declare const HEADER_CORRELATION_ID = "x-correlation-id";
+export declare const HEADER_TIMESTAMP = "x-timestamp";
+export declare const HEADER_SCHEMA_VERSION = "x-schema-version";
+export declare const HEADER_TRACEPARENT = "traceparent";
+/** Monotonically increasing logical clock stamped by the producer for deduplication. */
+export declare const HEADER_LAMPORT_CLOCK = "x-lamport-clock";
+/** Absolute epoch-ms deadline before which a delayed message must not be delivered. */
+export declare const HEADER_DELAYED_UNTIL = "x-delayed-until";
+/** Target topic a delayed message is forwarded to once its deadline passes. */
+export declare const HEADER_DELAYED_TARGET = "x-delayed-target";
+/**
+ * Typed wrapper combining a parsed message payload with Kafka metadata
+ * and envelope headers.
+ *
+ * On **send**, the library auto-generates envelope headers
+ * (`x-event-id`, `x-correlation-id`, `x-timestamp`, `x-schema-version`).
+ *
+ * On **consume**, the library extracts those headers and assembles
+ * an `EventEnvelope` that is passed to the handler.
+ *
+ * @example
+ * ```ts
+ * await kafka.startConsumer(['orders'], async (envelope: EventEnvelope<Order>) => {
+ *   console.log(envelope.payload.orderId);  // typed payload
+ *   console.log(envelope.correlationId);    // auto-propagated
+ *   console.log(envelope.eventId);          // unique message ID
+ * });
+ * ```
+ */
+export interface EventEnvelope<T> {
+    /** Deserialized + validated message body. */
+    payload: T;
+    /** Topic the message was produced to / consumed from. */
+    topic: string;
+    /** Kafka partition (consume-side only, `-1` on send). */
+    partition: number;
+    /** Kafka offset (consume-side only, empty string on send). */
+    offset: string;
+    /** ISO-8601 timestamp set by the producer. */
+    timestamp: string;
+    /** Unique ID for this event (UUID v4). */
+    eventId: string;
+    /** Correlation ID — auto-propagated via AsyncLocalStorage. */
+    correlationId: string;
+    /** Schema version of the payload. */
+    schemaVersion: number;
+    /** W3C Trace Context `traceparent` header (set by OTel instrumentation). */
+    traceparent?: string;
+    /** All decoded Kafka headers for extensibility. */
+    headers: MessageHeaders;
+}
+interface EnvelopeCtx {
+    correlationId: string;
+    traceparent?: string;
+}
+/**
+ * Read the current envelope context (correlationId / traceparent) from ALS.
+ * Returns `undefined` outside of a Kafka consumer handler.
+ * @example
+ * ```ts
+ * const ctx = getEnvelopeContext();
+ * if (ctx) console.log('correlationId:', ctx.correlationId);
+ * ```
+ */
+export declare function getEnvelopeContext(): EnvelopeCtx | undefined;
+/**
+ * Execute `fn` inside an envelope context so nested sends inherit correlationId.
+ * Automatically called by the consumer pipeline — use this in tests or manual flows.
+ * @example
+ * ```ts
+ * await runWithEnvelopeContext({ correlationId: 'abc-123' }, async () => {
+ *   await kafka.sendMessage('orders.created', payload); // inherits correlationId
+ * });
+ * ```
+ */
+export declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
+/** Options accepted by `buildEnvelopeHeaders`. */
+export interface EnvelopeHeaderOptions {
+    correlationId?: string;
+    schemaVersion?: number;
+    eventId?: string;
+    headers?: MessageHeaders;
+}
+/**
+ * Generate envelope headers for the send path.
+ *
+ * Priority for `correlationId`:
+ *   explicit option → ALS context → new UUID.
+ */
+export declare function buildEnvelopeHeaders(options?: EnvelopeHeaderOptions): MessageHeaders;
+/**
+ * Decode kafkajs headers (`Record<string, Buffer | string | undefined>`)
+ * into plain `Record<string, string>`.
+ */
+export declare function decodeHeaders(raw: Record<string, Buffer | string | (Buffer | string)[] | undefined> | undefined): MessageHeaders;
+/**
+ * Build an `EventEnvelope` from a consumed kafkajs message.
+ * Tolerates missing envelope headers — generates defaults so messages
+ * from non-envelope producers still work.
+ */
+export declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic: string, partition: number, offset: string): EventEnvelope<T>;
+export {};
+//# sourceMappingURL=envelope.d.ts.map

package/dist/client/message/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/client/message/envelope.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI/C,eAAO,MAAM,eAAe,eAAe,CAAC;AAC5C,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAC9C,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AACtD,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AACtD,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAIxD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,6CAA6C;IAC7C,OAAO,EAAE,CAAC,CAAC;IACX,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,OAAO,EAAE,cAAc,CAAC;CACzB;AAID,UAAU,WAAW;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,GAAG,SAAS,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE1E;AAID,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAuBhB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EACC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,SAAS,CAAC,GACjE,SAAS,GACZ,cAAc,CAehB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,aAAa,CAAC,CAAC,CAAC,CAalB"}

package/dist/client/message/schema-registry.d.ts

@@ -0,0 +1,124 @@
+import type { SchemaLike } from "./topic";
+/** A schema registered in a Confluent-compatible Schema Registry. */
+export interface RegisteredSchema {
+    /** Globally unique schema id assigned by the registry. */
+    id: number;
+    /** Version of the schema within its subject. */
+    version: number;
+    /** The schema definition string (JSON Schema / Avro / Protobuf source). */
+    schema: string;
+}
+/** Options for `SchemaRegistryClient`. */
+export interface SchemaRegistryClientOptions {
+    /** Registry base URL, e.g. `http://localhost:8081` or a Confluent Cloud SR endpoint. */
+    baseUrl: string;
+    /** HTTP Basic credentials (Confluent Cloud SR API key/secret). */
+    auth?: {
+        username: string;
+        password: string;
+    };
+    /** Cache TTL for subject lookups in ms. Default: `300_000` (5 min). */
+    cacheTtlMs?: number;
+    /** Injectable fetch implementation (tests). Default: global `fetch`. */
+    fetchFn?: typeof fetch;
+}
+/** Schema type accepted by Confluent-compatible registries. */
+export type RegistrySchemaType = "JSON" | "AVRO" | "PROTOBUF";
+/**
+ * Minimal, dependency-free client for the Confluent Schema Registry REST API
+ * (works with Confluent Platform/Cloud, Redpanda, Karapace, AWS Glue SR proxy).
+ *
+ * Scope: subject/version management, compatibility checks, and id->schema
+ * lookups. Used to keep locally-defined schemas in lockstep with a central
+ * registry, and as the backing lookup for the Avro/Protobuf serdes in
+ * `@drarzter/kafka-client/serde` (which handle the wire-format framing).
+ *
+ * @example
+ * ```ts
+ * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });
+ * const { id } = await registry.registerSchema(
+ *   'order.created-value',
+ *   JSON.stringify(orderJsonSchema),
+ *   'JSON',
+ * );
+ * ```
+ */
+export declare class SchemaRegistryClient {
+    private readonly options;
+    private readonly fetchFn;
+    private readonly cacheTtlMs;
+    private readonly latestCache;
+    /**
+     * `id → schema` cache. Schema ids are immutable in a Confluent-compatible
+     * registry (a given id always maps to the same schema string), so entries
+     * are cached for the lifetime of the client with no TTL.
+     */
+    private readonly byIdCache;
+    constructor(options: SchemaRegistryClientOptions);
+    private headers;
+    private request;
+    /** Fetch the latest schema registered under `subject`. Cached for `cacheTtlMs`. */
+    getLatestSchema(subject: string): Promise<RegisteredSchema>;
+    /**
+     * Fetch a schema by its globally unique registry id (`GET /schemas/ids/{id}`).
+     *
+     * Used by the Avro/Protobuf serdes on the deserialize path: the writer schema
+     * id is read from the Confluent wire-format prefix, then resolved here. Results
+     * are cached forever (schema ids are immutable), so a given id triggers exactly
+     * one registry round-trip regardless of how many messages reference it.
+     */
+    getSchemaById(id: number): Promise<{
+        id: number;
+        schema: string;
+        schemaType?: string;
+    }>;
+    /** Fetch a specific schema version of a subject. */
+    getSchemaVersion(subject: string, version: number): Promise<RegisteredSchema>;
+    /**
+     * Register a schema under `subject` (idempotent — re-registering the same
+     * schema returns the existing id). Returns the registry-assigned schema id.
+     */
+    registerSchema(subject: string, schema: string, schemaType?: RegistrySchemaType): Promise<{
+        id: number;
+    }>;
+    /**
+     * Test `schema` against the subject's compatibility policy without registering.
+     * Returns `true` when the registry reports the schema as compatible.
+     */
+    checkCompatibility(subject: string, schema: string, schemaType?: RegistrySchemaType): Promise<boolean>;
+}
+/** Options for `registrySchema()`. */
+export interface RegistrySchemaOptions<T> {
+    /**
+     * Local structural validator (Zod/Valibot/…) applied to every message.
+     * The registry governs schema *evolution*; this governs runtime *shape*.
+     */
+    validator?: SchemaLike<T>;
+    /**
+     * When `true` (default), the message's `x-schema-version` must not be newer
+     * than the latest version registered for the subject — a producer publishing
+     * an unregistered version fails loudly instead of drifting silently.
+     */
+    enforceVersion?: boolean;
+}
+/**
+ * Bridge a Schema Registry subject to this library's `SchemaLike` seam.
+ *
+ * On each `parse` the adapter resolves the subject's latest registered version
+ * (cached), optionally verifies the message's schema version does not exceed
+ * it, and delegates structural validation to the provided local validator.
+ * Attach the result to a `TopicDescriptor` like any other schema:
+ *
+ * @example
+ * ```ts
+ * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });
+ *
+ * const OrderCreated = topic('order.created').schema(
+ *   registrySchema(registry, 'order.created-value', {
+ *     validator: z.object({ orderId: z.string() }),
+ *   }),
+ * );
+ * ```
+ */
+export declare function registrySchema<T = any>(client: SchemaRegistryClient, subject: string, options?: RegistrySchemaOptions<T>): SchemaLike<T>;
+//# sourceMappingURL=schema-registry.d.ts.map

package/dist/client/message/schema-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-registry.d.ts","sourceRoot":"","sources":["../../../src/client/message/schema-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,SAAS,CAAC;AAE9D,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,2BAA2B;IAC1C,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,IAAI,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAoB;IAiBnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGxB;IACJ;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGtB;gBAEyB,OAAO,EAAE,2BAA2B;IAQjE,OAAO,CAAC,OAAO;YAYD,OAAO;IAoBrB,mFAAmF;IAC7E,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoBjE;;;;;;;OAOG;IACG,aAAa,CACjB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAY/D,oDAAoD;IAC9C,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC;IAY5B;;;OAGG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,kBAA2B,GACtC,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAS1B;;;OAGG;IACG,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,kBAA2B,GACtC,OAAO,CAAC,OAAO,CAAC;CAQpB;AAED,sCAAsC;AACtC,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,GAAG,EACpC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,UAAU,CAAC,CAAC,CAAC,CAkBf"}

package/dist/client/message/serde.d.ts

@@ -0,0 +1,68 @@
+import type { MessageHeaders } from "../types";
+/**
+ * Context passed to `MessageSerde.serialize` / `deserialize`.
+ *
+ * Carries the topic name, decoded message headers, and which side of the
+ * record is being (de)serialized. A Confluent Schema Registry serde uses
+ * `topic` + `isKey` to derive the subject name (`<topic>-value` / `<topic>-key`)
+ * and reads the schema id from the header/magic-byte prefix on `data`.
+ */
+export interface SerdeContext {
+    /** Topic the message is produced to / consumed from. */
+    topic: string;
+    /** Decoded message headers (envelope headers included). */
+    headers: MessageHeaders;
+    /**
+     * Which side of the Kafka record this call is (de)serializing.
+     * `false` / omitted → the value (default); `true` → the key.
+     * Used by schema-registry serdes to pick the `value` vs `key` subject.
+     */
+    isKey?: boolean;
+}
+/**
+ * Pluggable serialization layer for message payloads.
+ *
+ * A `MessageSerde` converts a validated payload object to the wire form
+ * (`Buffer` or `string`) on produce, and back to an object on consume.
+ * The default is {@link JsonSerde}, which reproduces the client's historical
+ * `JSON.stringify` / `JSON.parse` behaviour exactly.
+ *
+ * Serde only touches the message VALUE. Envelope metadata
+ * (`x-event-id`, `x-correlation-id`, `x-lamport-clock`, `traceparent`, …)
+ * always travels in headers and is never serialized through this layer.
+ *
+ * Set a client-wide serde via `KafkaClientOptions.serde`, or a per-topic
+ * override via `topic(...).serde(mySerde)` — the per-topic serde wins for
+ * that topic.
+ *
+ * @example
+ * ```ts
+ * const kafka = new KafkaClient(id, group, brokers, { serde: new JsonSerde() });
+ * ```
+ */
+export interface MessageSerde {
+    /**
+     * Serialize a validated payload object to wire bytes (`Buffer`) or a
+     * `string`. Validation has already run on `value` before this is called.
+     */
+    serialize(value: unknown, ctx: SerdeContext): Buffer | string | Promise<Buffer | string>;
+    /**
+     * Deserialize raw wire bytes into a payload object. Schema validation
+     * (if any) runs on the returned object afterwards.
+     */
+    deserialize(data: Buffer, ctx: SerdeContext): unknown | Promise<unknown>;
+}
+/**
+ * Default {@link MessageSerde}: JSON via `JSON.stringify` / `JSON.parse`.
+ *
+ * Byte-for-byte identical to the client's historical serialization, so it is
+ * a zero-behaviour-change default. Produces a UTF-8 `string` on serialize and
+ * decodes UTF-8 bytes on deserialize.
+ */
+export declare class JsonSerde implements MessageSerde {
+    /** JSON-stringify the validated payload. Returns a UTF-8 string. */
+    serialize(value: unknown): string;
+    /** JSON-parse UTF-8 wire bytes into an object. */
+    deserialize(data: Buffer): unknown;
+}
+//# sourceMappingURL=serde.d.ts.map

package/dist/client/message/serde.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serde.d.ts","sourceRoot":"","sources":["../../../src/client/message/serde.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,OAAO,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CACP,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,YAAY,GAChB,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9C;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,oEAAoE;IACpE,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAIjC,kDAAkD;IAClD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGnC"}

package/dist/client/message/topic.d.ts

@@ -0,0 +1,159 @@
+import type { MessageHeaders } from "../types";
+import type { MessageSerde } from "./serde";
+/**
+ * Context passed as the second argument to `SchemaLike.parse()`.
+ * Enables schema-registry adapters, version-aware migration, and
+ * header-driven parsing without coupling validators to Kafka internals.
+ *
+ * All fields are optional-friendly — validators that don't need the context
+ * can simply ignore the second argument.
+ */
+export interface SchemaParseContext {
+    /** Topic the message was produced to / consumed from. */
+    topic: string;
+    /** Decoded message headers (envelope headers included). */
+    headers: MessageHeaders;
+    /** Value of the `x-schema-version` header, defaults to `1`. */
+    version: number;
+}
+/**
+ * Any validation library with a `.parse()` method.
+ * Works with Zod, Valibot, ArkType, or any custom validator.
+ *
+ * The optional `ctx` argument carries topic/header/version metadata so
+ * validators can perform schema-registry lookups or version-aware migrations.
+ * Existing validators that only use the first argument continue to work
+ * unchanged — the second argument is silently ignored.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * const schema: SchemaLike<{ id: string }> = z.object({ id: z.string() });
+ *
+ * // Context-aware validator:
+ * const schema: SchemaLike<MyType> = {
+ *   parse(data, ctx) {
+ *     const version = ctx?.version ?? 1;
+ *     return version >= 2 ? migrateV1toV2(data) : validateV1(data);
+ *   }
+ * };
+ * ```
+ */
+export interface SchemaLike<T = any> {
+    parse(data: unknown, ctx?: SchemaParseContext): T | Promise<T>;
+}
+/** Infer the output type from a SchemaLike. */
+export type InferSchema<S extends SchemaLike> = S extends SchemaLike<infer T> ? T : never;
+/**
+ * A typed topic descriptor that pairs a topic name with its message type.
+ * Created via the `topic()` factory function.
+ *
+ * @typeParam N - The literal topic name string.
+ * @typeParam M - The message payload type for this topic.
+ */
+export interface TopicDescriptor<N extends string = string, M extends Record<string, any> = Record<string, any>> {
+    readonly __topic: N;
+    /** @internal Phantom type — never has a real value at runtime. */
+    readonly __type: M;
+    /** Runtime schema validator. Present only when created via `topic().schema()`. */
+    readonly __schema?: SchemaLike<M>;
+    /**
+     * Per-topic serialization override. Present only when created via `.serde()`.
+     * When set, this serde is used for produce/consume on this topic instead of
+     * the client-wide `KafkaClientOptions.serde`.
+     */
+    readonly __serde?: MessageSerde;
+    /**
+     * Partition-key extractor. Present only when created via `.key()`.
+     * Applied on every send through this descriptor unless an explicit
+     * `key` is passed in `SendOptions` / the batch item.
+     *
+     * Declared with method syntax (not a function property) so `M` stays
+     * bivariant — otherwise narrow descriptors would stop being assignable
+     * to `TopicDescriptor<string, Record<string, any>>` parameters.
+     */
+    __key?(message: M): string;
+}
+/**
+ * A `TopicDescriptor` that can still be extended with a `.key()` extractor or
+ * a `.serde()` override. Returned by `topic().type()` and `topic().schema()` —
+ * usable directly as a descriptor, or chained further to declare partition
+ * affinity and/or a custom serializer.
+ */
+export type KeyableTopicDescriptor<N extends string, M extends Record<string, any>> = TopicDescriptor<N, M> & {
+    /**
+     * Declare a partition-key extractor for this topic. The extractor runs on
+     * the ORIGINAL (pre-validation) payload of every message sent through this
+     * descriptor, so messages with the same logical key always land on the same
+     * partition without passing `key` at each call site.
+     *
+     * An explicit `SendOptions.key` / batch-item `key` always wins.
+     *
+     * @example
+     * ```ts
+     * const OrderCreated = topic('order.created')
+     *   .type<{ orderId: string; amount: number }>()
+     *   .key((m) => m.orderId);
+     *
+     * await kafka.sendMessage(OrderCreated, { orderId: '42', amount: 100 });
+     * // → produced with key '42'
+     * ```
+     */
+    key(extractor: (message: M) => string): KeyableTopicDescriptor<N, M>;
+    /**
+     * Declare a per-topic serialization override. The given {@link MessageSerde}
+     * is used for produce/consume on this topic instead of the client-wide
+     * `KafkaClientOptions.serde`. Chainable with `.key()`.
+     *
+     * @example
+     * ```ts
+     * const OrderCreated = topic('order.created')
+     *   .schema(OrderSchema)
+     *   .serde(new AvroSerde(OrderAvroSchema));
+     * ```
+     */
+    serde(serde: MessageSerde): KeyableTopicDescriptor<N, M>;
+};
+/**
+ * Define a typed topic descriptor.
+ *
+ * @example
+ * ```ts
+ * // Without schema — explicit type via .type<T>():
+ * const OrderCreated = topic('order.created').type<{ orderId: string; amount: number }>();
+ *
+ * // With schema — type inferred from schema:
+ * const OrderCreated = topic('order.created').schema(z.object({
+ *   orderId: z.string(),
+ *   amount: z.number(),
+ * }));
+ *
+ * // Use with KafkaClient:
+ * await kafka.sendMessage(OrderCreated, { orderId: '123', amount: 100 });
+ *
+ * // Use with @SubscribeTo:
+ * @SubscribeTo(OrderCreated)
+ * async handleOrder(msg) { ... }
+ * ```
+ */
+export declare function topic<N extends string>(name: N): {
+    /** Provide an explicit message type without a runtime schema. */
+    type: <M extends Record<string, any>>() => KeyableTopicDescriptor<N, M>;
+    schema: <S extends SchemaLike<Record<string, any>>>(schema: S) => KeyableTopicDescriptor<N, InferSchema<S>>;
+};
+/**
+ * Build a topic-message map type from a union of TopicDescriptors.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created').type<{ orderId: string }>();
+ * const OrderCompleted = topic('order.completed').type<{ completedAt: string }>();
+ *
+ * type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
+ * // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
+ * ```
+ */
+export type TopicsFrom<D extends TopicDescriptor<any, any>> = {
+    [K in D as K["__topic"]]: K["__type"];
+};
+//# sourceMappingURL=topic.d.ts.map

package/dist/client/message/topic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.d.ts","sourceRoot":"","sources":["../../../src/client/message/topic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,OAAO,EAAE,cAAc,CAAC;IACxB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,GAAG;IACjC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,kBAAkB,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChE;AAED,+CAA+C;AAC/C,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,IAC1C,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAEnD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,CAChC,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAC3B,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC1B;;;;;;;;;;;;;;;;;OAiBG;IACH,GAAG,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,GAAG,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC;IAE3C,iEAAiE;WAC1D,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAK,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;aAM5D,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,UACxC,CAAC,KACR,sBAAsB,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;EAO/C;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI;KAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;CACtC,CAAC"}

package/dist/client/message/versioned-schema.d.ts

@@ -0,0 +1,53 @@
+import type { SchemaLike } from "./topic";
+/**
+ * Options for `versionedSchema()`.
+ * @typeParam T - The (latest) output type produced after parsing and migration.
+ */
+export interface VersionedSchemaOptions<T> {
+    /**
+     * Called after a message parsed with a non-latest schema version.
+     * Receives the parsed data, the version it was parsed with, and the latest
+     * registered version. Must return the data in its latest shape.
+     *
+     * When omitted, older versions are returned as parsed — callers must handle
+     * shape differences themselves.
+     */
+    migrate?: (data: any, fromVersion: number, latestVersion: number) => T | Promise<T>;
+}
+/**
+ * Compose per-version validators into a single `SchemaLike` that dispatches on
+ * the message's `x-schema-version` header (via `SchemaParseContext.version`).
+ *
+ * - Consume path: the version comes from the `x-schema-version` header
+ *   (defaults to `1` when absent).
+ * - Send path: the version comes from `SendOptions.schemaVersion`
+ *   (defaults to `1`).
+ * - No parse context at all (direct `.parse(data)` call): the latest
+ *   registered version is assumed.
+ *
+ * Throws when a message carries a version with no registered schema — a
+ * misconfigured producer fails loudly instead of validating against the
+ * wrong shape.
+ *
+ * @typeParam T - The latest message shape (post-migration).
+ * @param versions Map of version number → validator for that version.
+ * @param options Optional migration hook to upgrade old shapes to the latest.
+ *
+ * @example
+ * ```ts
+ * const OrderSchema = versionedSchema<{ orderId: string; amountMinor: number }>(
+ *   {
+ *     1: z.object({ orderId: z.string(), amount: z.number() }),
+ *     2: z.object({ orderId: z.string(), amountMinor: z.number().int() }),
+ *   },
+ *   {
+ *     migrate: (data, from) =>
+ *       from === 1 ? { orderId: data.orderId, amountMinor: Math.round(data.amount * 100) } : data,
+ *   },
+ * );
+ *
+ * const OrderCreated = topic('order.created').schema(OrderSchema);
+ * ```
+ */
+export declare function versionedSchema<T = any>(versions: Record<number, SchemaLike<any>>, options?: VersionedSchemaOptions<T>): SchemaLike<T>;
+//# sourceMappingURL=versioned-schema.d.ts.map

package/dist/client/message/versioned-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-schema.d.ts","sourceRoot":"","sources":["../../../src/client/message/versioned-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,SAAS,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CACR,IAAI,EAAE,GAAG,EACT,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,KAClB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,GAAG,EACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,EACzC,OAAO,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAClC,UAAU,CAAC,CAAC,CAAC,CA6Bf"}

package/dist/client/outbox/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./outbox.types";
+export * from "./outbox.store";
+export * from "./outbox.relay";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/outbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/outbox/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/client/outbox/outbox.relay.d.ts

@@ -0,0 +1,90 @@
+import type { TopicMapConstraint } from "../types";
+import type { OutboxProducer, OutboxRelayHandle, OutboxRelayOptions, OutboxStore } from "./outbox.types";
+/**
+ * Start a transactional-outbox relay.
+ *
+ * The outbox pattern decouples "write my business state" from "publish an event"
+ * so the two can never diverge: application code writes an event row into an
+ * outbox table **in the same DB transaction** as its business writes; this relay
+ * polls that table and publishes the rows to Kafka, marking them published only
+ * after Kafka has acked them.
+ *
+ * ## Poll loop
+ * Every `pollIntervalMs` the relay calls {@link OutboxStore.fetchUnpublished}
+ * with `batchSize`. An empty result means there is nothing to do — it waits for
+ * the next tick. A non-empty batch is published **entirely inside one Kafka
+ * transaction** (`kafka.transaction`, one `tx.send` per message), and only after
+ * that transaction commits does it call {@link OutboxStore.markPublished} with
+ * the row ids.
+ *
+ * ## Delivery guarantee: at-least-once
+ * If the process crashes **after** the Kafka transaction commits but **before**
+ * `markPublished` runs, those rows are still unpublished in the store and will be
+ * re-published on the next poll. This produces **duplicates**, but each duplicate
+ * carries the **same** `x-event-id` (when {@link OutboxMessage.eventId} is set on
+ * the row), so consumers can deduplicate — either via this library's Lamport-clock
+ * deduplication or an application-level idempotency check keyed on the event id.
+ * Persist a stable `eventId` on each outbox row to make this work.
+ *
+ * ## Failure handling
+ * The loop never dies and never leaks an unhandled rejection:
+ * - If the publishing transaction throws, `onError` fires, the batch is **not**
+ *   marked published, and it is retried on the next tick.
+ * - If the store throws (either `fetchUnpublished` or `markPublished`), same
+ *   behaviour: `onError`, no marking, retried next tick.
+ *
+ * Note the one asymmetry: if `markPublished` throws *after* a successful Kafka
+ * commit, the batch is re-published next tick — an intentional consequence of
+ * the at-least-once guarantee above.
+ *
+ * ## Concurrency
+ * Iterations never overlap. If an iteration runs longer than `pollIntervalMs`,
+ * intervening ticks are skipped (a guard flag) rather than stacked.
+ *
+ * ## Shutdown
+ * `handle.stop()` clears the timer and awaits any in-flight iteration before
+ * resolving, so no publish is left half-done. It is idempotent.
+ *
+ * @param kafka  Any producer exposing `transaction()` — a `KafkaClient<T>` or
+ *               `IKafkaProducer<T>`. Its producer must already be connected.
+ * @param store  Your DB-backed {@link OutboxStore} implementation.
+ * @param options Tuning and observability — see {@link OutboxRelayOptions}.
+ *
+ * @example
+ * ```ts
+ * // Pseudo-Postgres outbox store.
+ * const store: OutboxStore = {
+ *   async fetchUnpublished(limit) {
+ *     const { rows } = await pool.query(
+ *       `SELECT id, topic, payload, key, correlation_id AS "correlationId",
+ *               event_id AS "eventId", headers
+ *          FROM outbox
+ *         WHERE published_at IS NULL
+ *         ORDER BY created_at ASC
+ *         LIMIT $1`,
+ *       [limit],
+ *     );
+ *     return rows;
+ *   },
+ *   async markPublished(ids) {
+ *     await pool.query(
+ *       `UPDATE outbox SET published_at = now() WHERE id = ANY($1)`,
+ *       [ids],
+ *     );
+ *   },
+ * };
+ *
+ * await kafka.connectProducer();
+ * const relay = startOutboxRelay(kafka, store, {
+ *   pollIntervalMs: 500,
+ *   batchSize: 200,
+ *   onPublished: (n) => metrics.increment('outbox.published', n),
+ * });
+ *
+ * // On shutdown:
+ * await relay.stop();
+ * await kafka.disconnect();
+ * ```
+ */
+export declare function startOutboxRelay<T extends TopicMapConstraint<T>>(kafka: OutboxProducer<T>, store: OutboxStore, options?: OutboxRelayOptions): OutboxRelayHandle;
+//# sourceMappingURL=outbox.relay.d.ts.map

package/dist/client/outbox/outbox.relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.relay.d.ts","sourceRoot":"","sources":["../../../src/client/outbox/outbox.relay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,KAAK,EAEV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAOxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAC9D,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAwEnB"}