@drarzter/kafka-client 0.3.1 → 0.5.0

package/dist/{types-CtwJihJ3.d.ts → envelope-QK1trQu4.d.ts}

@@ -104,8 +104,23 @@ type MessageHeaders = Record<string, string>;
 interface SendOptions {
     /** Partition key for message routing. */
     key?: string;
-    /** Custom headers attached to the message. */
+    /** Custom headers attached to the message (merged with auto-generated envelope headers). */
     headers?: MessageHeaders;
+    /** Override the auto-propagated correlation ID (default: inherited from ALS context or new UUID). */
+    correlationId?: string;
+    /** Schema version for the payload. Default: `1`. */
+    schemaVersion?: number;
+    /** Override the auto-generated event ID (UUID v4). */
+    eventId?: string;
+}
+/** Shape of each item in a `sendBatch` call. */
+interface BatchMessageItem<V> {
+    value: V;
+    key?: string;
+    headers?: MessageHeaders;
+    correlationId?: string;
+    schemaVersion?: number;
+    eventId?: string;
 }
 /** Metadata exposed to batch consumer handlers. */
 interface BatchMeta {
@@ -149,46 +164,53 @@ interface RetryOptions {
 /**
  * Interceptor hooks for consumer message processing.
  * All methods are optional — implement only what you need.
+ *
+ * Interceptors are per-consumer. For client-wide hooks (e.g. OTel),
+ * use `KafkaInstrumentation` instead.
  */
 interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap> {
     /** Called before the message handler. */
-    before?(message: T[keyof T], topic: string): Promise<void> | void;
+    before?(envelope: EventEnvelope<T[keyof T]>): Promise<void> | void;
     /** Called after the message handler succeeds. */
-    after?(message: T[keyof T], topic: string): Promise<void> | void;
+    after?(envelope: EventEnvelope<T[keyof T]>): Promise<void> | void;
     /** Called when the message handler throws. */
-    onError?(message: T[keyof T], topic: string, error: Error): Promise<void> | void;
+    onError?(envelope: EventEnvelope<T[keyof T]>, error: Error): Promise<void> | void;
+}
+/**
+ * Client-wide instrumentation hooks for both send and consume paths.
+ * Use this for cross-cutting concerns like tracing and metrics.
+ *
+ * @see `otelInstrumentation()` from `@drarzter/kafka-client/otel`
+ */
+interface KafkaInstrumentation {
+    /** Called before sending — can mutate `headers` (e.g. inject `traceparent`). */
+    beforeSend?(topic: string, headers: MessageHeaders): void;
+    /** Called after a successful send. */
+    afterSend?(topic: string): void;
+    /** Called before the consumer handler. Return a cleanup function called after the handler. */
+    beforeConsume?(envelope: EventEnvelope<any>): (() => void) | void;
+    /** Called when the consumer handler throws. */
+    onConsumeError?(envelope: EventEnvelope<any>, error: Error): void;
 }
 /** Context passed to the `transaction()` callback with type-safe send methods. */
 interface TransactionContext<T extends TopicMapConstraint<T>> {
     send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
     send<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
-    sendBatch<K extends keyof T>(topic: K, messages: Array<{
-        value: T[K];
-        key?: string;
-        headers?: MessageHeaders;
-    }>): Promise<void>;
-    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<{
-        value: D["__type"];
-        key?: string;
-        headers?: MessageHeaders;
-    }>): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>): Promise<void>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<BatchMessageItem<D["__type"]>>): Promise<void>;
 }
 /** Interface describing all public methods of the Kafka client. */
 interface IKafkaClient<T extends TopicMapConstraint<T>> {
     checkStatus(): Promise<{
         topics: string[];
     }>;
-    startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (message: T[K[number]], topic: K[number]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
-    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (message: D["__type"], topic: D["__topic"]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
-    startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (messages: T[K[number]][], topic: K[number], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
-    startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (messages: D["__type"][], topic: D["__topic"], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (envelope: EventEnvelope<T[K[number]]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (envelope: EventEnvelope<D["__type"]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (envelopes: EventEnvelope<T[K[number]]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (envelopes: EventEnvelope<D["__type"]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
     stopConsumer(): Promise<void>;
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
-    sendBatch<K extends keyof T>(topic: K, messages: Array<{
-        value: T[K];
-        key?: string;
-        headers?: MessageHeaders;
-    }>): Promise<void>;
+    sendBatch<K extends keyof T>(topic: K, messages: Array<BatchMessageItem<T[K]>>): Promise<void>;
     transaction(fn: (ctx: TransactionContext<T>) => Promise<void>): Promise<void>;
     getClientId: () => ClientId;
     disconnect(): Promise<void>;
@@ -212,6 +234,8 @@ interface KafkaClientOptions {
     logger?: KafkaLogger;
     /** Number of partitions for auto-created topics. Default: `1`. */
     numPartitions?: number;
+    /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */
+    instrumentation?: KafkaInstrumentation[];
 }
 /** Options for consumer subscribe retry when topic doesn't exist yet. */
 interface SubscribeRetryOptions {
@@ -221,4 +245,75 @@ interface SubscribeRetryOptions {
     backoffMs?: number;
 }
 
-export { type BatchMeta as B, type ClientId as C, type GroupId as G, type IKafkaClient as I, type KafkaClientOptions as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type ConsumerOptions as a, type TopicDescriptor as b, type ConsumerInterceptor as c, type InferSchema as d, type KafkaLogger as e, type SendOptions as f, type SubscribeRetryOptions as g, type TTopicMessageMap as h, type TopicsFrom as i, type TransactionContext as j, topic as t };
+declare const HEADER_EVENT_ID = "x-event-id";
+declare const HEADER_CORRELATION_ID = "x-correlation-id";
+declare const HEADER_TIMESTAMP = "x-timestamp";
+declare const HEADER_SCHEMA_VERSION = "x-schema-version";
+declare const HEADER_TRACEPARENT = "traceparent";
+/**
+ * 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.
+ */
+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. */
+declare function getEnvelopeContext(): EnvelopeCtx | undefined;
+/** Execute `fn` inside an envelope context so nested sends inherit correlationId. */
+declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
+/** Options accepted by `buildEnvelopeHeaders`. */
+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.
+ */
+declare function buildEnvelopeHeaders(options?: EnvelopeHeaderOptions): MessageHeaders;
+/**
+ * Decode kafkajs headers (`Record<string, Buffer | string | undefined>`)
+ * into plain `Record<string, string>`.
+ */
+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.
+ */
+declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic: string, partition: number, offset: string): EventEnvelope<T>;
+
+export { type BatchMessageItem as B, type ClientId as C, type EnvelopeHeaderOptions as E, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, type KafkaInstrumentation as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type ConsumerOptions as a, type TopicDescriptor as b, type BatchMeta as c, type ConsumerInterceptor as d, type EventEnvelope as e, HEADER_EVENT_ID as f, HEADER_SCHEMA_VERSION as g, HEADER_TIMESTAMP as h, HEADER_TRACEPARENT as i, type InferSchema as j, type KafkaClientOptions as k, type KafkaLogger as l, type SendOptions as m, type SubscribeRetryOptions as n, type TTopicMessageMap as o, type TopicsFrom as p, type TransactionContext as q, buildEnvelopeHeaders as r, decodeHeaders as s, extractEnvelope as t, getEnvelopeContext as u, runWithEnvelopeContext as v, topic as w };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { KafkaClient } from './core.mjs';
 export { KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError } from './core.mjs';
-import { T as TopicMapConstraint, C as ClientId, G as GroupId, S as SchemaLike, a as ConsumerOptions, b as TopicDescriptor } from './types-CtwJihJ3.mjs';
-export { B as BatchMeta, c as ConsumerInterceptor, I as IKafkaClient, d as InferSchema, K as KafkaClientOptions, e as KafkaLogger, M as MessageHeaders, R as RetryOptions, f as SendOptions, g as SubscribeRetryOptions, h as TTopicMessageMap, i as TopicsFrom, j as TransactionContext, t as topic } from './types-CtwJihJ3.mjs';
+import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, S as SchemaLike, a as ConsumerOptions, b as TopicDescriptor } from './envelope-QK1trQu4.mjs';
+export { B as BatchMessageItem, c as BatchMeta, d as ConsumerInterceptor, E as EnvelopeHeaderOptions, e as EventEnvelope, H as HEADER_CORRELATION_ID, f as HEADER_EVENT_ID, g as HEADER_SCHEMA_VERSION, h as HEADER_TIMESTAMP, i as HEADER_TRACEPARENT, I as IKafkaClient, j as InferSchema, k as KafkaClientOptions, l as KafkaLogger, M as MessageHeaders, R as RetryOptions, m as SendOptions, n as SubscribeRetryOptions, o as TTopicMessageMap, p as TopicsFrom, q as TransactionContext, r as buildEnvelopeHeaders, s as decodeHeaders, t as extractEnvelope, u as getEnvelopeContext, v as runWithEnvelopeContext, w as topic } from './envelope-QK1trQu4.mjs';
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 
@@ -19,6 +19,12 @@ interface KafkaModuleOptions {
     isGlobal?: boolean;
     /** Auto-create topics via admin on first use (send/consume). Useful for development. */
     autoCreateTopics?: boolean;
+    /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
+    strictSchemas?: boolean;
+    /** Number of partitions for auto-created topics. Default: `1`. */
+    numPartitions?: number;
+    /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */
+    instrumentation?: KafkaInstrumentation[];
 }
 /** Async configuration for `KafkaModule.registerAsync()` with dependency injection. */
 interface KafkaModuleAsyncOptions {
@@ -88,4 +94,4 @@ declare class KafkaHealthIndicator {
     check<T extends TopicMapConstraint<T>>(client: KafkaClient<T>): Promise<KafkaHealthResult>;
 }
 
-export { ClientId, ConsumerOptions, GroupId, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, type KafkaSubscriberMetadata, SchemaLike, SubscribeTo, TopicDescriptor, TopicMapConstraint, getKafkaClientToken };
+export { ClientId, ConsumerOptions, GroupId, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaInstrumentation, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, type KafkaSubscriberMetadata, SchemaLike, SubscribeTo, TopicDescriptor, TopicMapConstraint, getKafkaClientToken };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { KafkaClient } from './core.js';
 export { KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError } from './core.js';
-import { T as TopicMapConstraint, C as ClientId, G as GroupId, S as SchemaLike, a as ConsumerOptions, b as TopicDescriptor } from './types-CtwJihJ3.js';
-export { B as BatchMeta, c as ConsumerInterceptor, I as IKafkaClient, d as InferSchema, K as KafkaClientOptions, e as KafkaLogger, M as MessageHeaders, R as RetryOptions, f as SendOptions, g as SubscribeRetryOptions, h as TTopicMessageMap, i as TopicsFrom, j as TransactionContext, t as topic } from './types-CtwJihJ3.js';
+import { T as TopicMapConstraint, C as ClientId, G as GroupId, K as KafkaInstrumentation, S as SchemaLike, a as ConsumerOptions, b as TopicDescriptor } from './envelope-QK1trQu4.js';
+export { B as BatchMessageItem, c as BatchMeta, d as ConsumerInterceptor, E as EnvelopeHeaderOptions, e as EventEnvelope, H as HEADER_CORRELATION_ID, f as HEADER_EVENT_ID, g as HEADER_SCHEMA_VERSION, h as HEADER_TIMESTAMP, i as HEADER_TRACEPARENT, I as IKafkaClient, j as InferSchema, k as KafkaClientOptions, l as KafkaLogger, M as MessageHeaders, R as RetryOptions, m as SendOptions, n as SubscribeRetryOptions, o as TTopicMessageMap, p as TopicsFrom, q as TransactionContext, r as buildEnvelopeHeaders, s as decodeHeaders, t as extractEnvelope, u as getEnvelopeContext, v as runWithEnvelopeContext, w as topic } from './envelope-QK1trQu4.js';
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 
@@ -19,6 +19,12 @@ interface KafkaModuleOptions {
     isGlobal?: boolean;
     /** Auto-create topics via admin on first use (send/consume). Useful for development. */
     autoCreateTopics?: boolean;
+    /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
+    strictSchemas?: boolean;
+    /** Number of partitions for auto-created topics. Default: `1`. */
+    numPartitions?: number;
+    /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */
+    instrumentation?: KafkaInstrumentation[];
 }
 /** Async configuration for `KafkaModule.registerAsync()` with dependency injection. */
 interface KafkaModuleAsyncOptions {
@@ -88,4 +94,4 @@ declare class KafkaHealthIndicator {
     check<T extends TopicMapConstraint<T>>(client: KafkaClient<T>): Promise<KafkaHealthResult>;
 }
 
-export { ClientId, ConsumerOptions, GroupId, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, type KafkaSubscriberMetadata, SchemaLike, SubscribeTo, TopicDescriptor, TopicMapConstraint, getKafkaClientToken };
+export { ClientId, ConsumerOptions, GroupId, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaInstrumentation, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, type KafkaSubscriberMetadata, SchemaLike, SubscribeTo, TopicDescriptor, TopicMapConstraint, getKafkaClientToken };