@woovi/kafka 1.0.4 → 1.0.8

package/README.md

@@ -184,6 +184,61 @@ await consumer.pause(['events']);   // Pause specific topics
 await consumer.resume();           // Resume all topics
 ```
 
+## Event Envelope
+
+Wrap event data with standardized metadata using the event envelope pattern:
+
+```typescript
+import { createEventEnvelope } from '@woovi/kafka';
+
+const envelope = createEventEnvelope({
+  eventType: 'pix-out.compliance.approved',
+  operationType: 'update',
+  source: 'woovi-compliance',
+  data: { movementId: '123', pixOutId: '456' },
+  extraMetadata: { correlationId: 'abc-123', traceId: 'xyz-789' },
+});
+
+await producer.publish({ data: envelope });
+```
+
+The envelope has the shape:
+
+```typescript
+{
+  metadata: {
+    eventId: string;      // auto-generated UUID
+    eventType: string;    // e.g. "pix-out.compliance.approved"
+    eventTime: string;    // auto-generated ISO 8601 timestamp
+    operationType?: string; // e.g. "insert", "update", "delete"
+    source: string;       // e.g. "woovi-compliance"
+    // ...any extra metadata fields
+  },
+  data: T;
+}
+```
+
+### Parsing Event Envelopes (Consumer Side)
+
+Use `parseEventEnvelope` to validate and unwrap envelope-wrapped messages in your consumer handlers:
+
+```typescript
+import type { ConsumerMessage, EventEnvelope } from '@woovi/kafka';
+import { parseEventEnvelope } from '@woovi/kafka';
+
+const handler = async (message: ConsumerMessage<EventEnvelope<MyEvent>>) => {
+  const { metadata, data } = parseEventEnvelope(message);
+
+  console.log(metadata.eventId);    // UUID
+  console.log(metadata.eventType);  // e.g. "pix-out.compliance.approved"
+  console.log(metadata.eventTime);  // ISO 8601 timestamp
+  console.log(metadata.source);     // e.g. "woovi-compliance"
+  console.log(data);                // typed as MyEvent
+};
+```
+
+Throws with a descriptive error if the message does not follow the envelope pattern (missing metadata, missing data, or malformed metadata fields).
+
 ## Health Check
 
 ```typescript
@@ -266,6 +321,29 @@ it('publishes a user event', async () => {
 });
 ```
 
+### Asserting Event Envelopes
+
+Use `kafkaAssertEventEnvelope` to assert messages published with the event envelope pattern:
+
+```typescript
+import { kafkaAssertEventEnvelope, clearAllMocks } from '@woovi/kafka/test-utils';
+
+beforeEach(() => clearAllMocks());
+
+it('publishes a compliance event', async () => {
+  await myService.approveCompliance({ movementId: '123' });
+
+  kafkaAssertEventEnvelope({
+    topic: 'pix-out.compliance.approved',
+    eventType: 'pix-out.compliance.approved',
+    source: 'woovi-compliance',
+    data: { movementId: '123', pixOutId: '456' },
+  });
+});
+```
+
+This validates the full envelope structure (metadata with `eventId`, `eventType`, `eventTime`, `source`) and checks that the data is a subset match.
+
 ## License
 
 ISC

package/dist/index.cjs

@@ -38,11 +38,13 @@ __webpack_require__.d(__webpack_exports__, {
     produceLatency: ()=>produceLatency,
     createConsumer: ()=>createConsumer,
     getKafka: ()=>getKafka,
+    parseEventEnvelope: ()=>parseEventEnvelope,
     resetMetrics: ()=>resetMetrics,
-    disableTracing: ()=>disableTracing,
     getMetricsContentType: ()=>getMetricsContentType,
+    disableTracing: ()=>disableTracing,
     WooviProducer: ()=>WooviProducer,
     enableDefaultMetrics: ()=>enableDefaultMetrics,
+    createEventEnvelope: ()=>createEventEnvelope,
     messagesProducedTotal: ()=>messagesProducedTotal,
     messageProcessingDuration: ()=>messageProcessingDuration,
     createProducer: ()=>createProducer,
@@ -1085,6 +1087,33 @@ class WooviConsumer {
 function createConsumer(config) {
     return new WooviConsumer(config);
 }
+const external_node_crypto_namespaceObject = require("node:crypto");
+const createEventEnvelope = (args)=>({
+        metadata: {
+            eventId: (0, external_node_crypto_namespaceObject.randomUUID)(),
+            eventType: args.eventType,
+            eventTime: new Date().toISOString(),
+            operationType: args.operationType,
+            source: args.source,
+            ...args.extraMetadata
+        },
+        data: args.data
+    });
+const isValidMetadata = (metadata)=>{
+    if ('object' != typeof metadata || null === metadata) return false;
+    const m = metadata;
+    return 'string' == typeof m.eventId && 'string' == typeof m.eventType && 'string' == typeof m.eventTime && 'string' == typeof m.source;
+};
+const parseEventEnvelope = (message)=>{
+    const envelope = message.data;
+    if (!envelope || 'object' != typeof envelope) throw new Error(`Invalid event envelope: message data is not an object. Topic: ${message.topic}, offset: ${message.offset}`);
+    if (!isValidMetadata(envelope.metadata)) throw new Error(`Invalid event envelope: missing or malformed metadata. Expected eventId, eventType, eventTime, and source. Topic: ${message.topic}, offset: ${message.offset}`);
+    if (!('data' in envelope) || void 0 === envelope.data) throw new Error(`Invalid event envelope: missing data field. Topic: ${message.topic}, offset: ${message.offset}`);
+    return {
+        metadata: envelope.metadata,
+        data: envelope.data
+    };
+};
 exports.Kafka = __webpack_exports__.Kafka;
 exports.WooviConsumer = __webpack_exports__.WooviConsumer;
 exports.WooviProducer = __webpack_exports__.WooviProducer;
@@ -1092,6 +1121,7 @@ exports.batchProcessingDuration = __webpack_exports__.batchProcessingDuration;
 exports.batchSize = __webpack_exports__.batchSize;
 exports.consumerLag = __webpack_exports__.consumerLag;
 exports.createConsumer = __webpack_exports__.createConsumer;
+exports.createEventEnvelope = __webpack_exports__.createEventEnvelope;
 exports.createKafka = __webpack_exports__.createKafka;
 exports.createKafkaFromEnv = __webpack_exports__.createKafkaFromEnv;
 exports.createProducer = __webpack_exports__.createProducer;
@@ -1115,6 +1145,7 @@ exports.messagesFailedTotal = __webpack_exports__.messagesFailedTotal;
 exports.messagesProcessedTotal = __webpack_exports__.messagesProcessedTotal;
 exports.messagesProducedTotal = __webpack_exports__.messagesProducedTotal;
 exports.onShutdown = __webpack_exports__.onShutdown;
+exports.parseEventEnvelope = __webpack_exports__.parseEventEnvelope;
 exports.produceLatency = __webpack_exports__.produceLatency;
 exports.resetMetrics = __webpack_exports__.resetMetrics;
 exports.setMockKafkaForTestMode = __webpack_exports__.setMockKafkaForTestMode;
@@ -1126,6 +1157,7 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "batchSize",
     "consumerLag",
     "createConsumer",
+    "createEventEnvelope",
     "createKafka",
     "createKafkaFromEnv",
     "createProducer",
@@ -1149,6 +1181,7 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "messagesProcessedTotal",
     "messagesProducedTotal",
     "onShutdown",
+    "parseEventEnvelope",
     "produceLatency",
     "resetMetrics",
     "setMockKafkaForTestMode"

package/dist/index.d.ts

@@ -85,6 +85,36 @@ declare interface Context {
  */
 export declare function createConsumer(config: WooviConsumerConfig): WooviConsumer;
 
+/**
+ * Creates an event envelope wrapping data with standardized metadata.
+ * Extra metadata fields can be passed to extend the envelope dynamically.
+ *
+ * @example
+ * ```typescript
+ * const envelope = createEventEnvelope({
+ *   eventType: 'pix-out.compliance.approved',
+ *   operationType: 'update',
+ *   source: 'woovi-compliance',
+ *   data: { movementId: '123', pixOutId: '456' },
+ *   extraMetadata: { correlationId: 'abc-123', traceId: 'xyz-789' },
+ * });
+ * ```
+ */
+export declare const createEventEnvelope: <T>(args: CreateEventEnvelopeArgs<T>) => EventEnvelope<T>;
+
+declare interface CreateEventEnvelopeArgs<T> {
+    /** Type/name of the event (e.g. "pix-out.compliance.approved") */
+    eventType: string;
+    /** Type of operation that triggered the event (e.g. "insert", "update", "delete") */
+    operationType?: string;
+    /** Source system that produced the event (e.g. "woovi-compliance") */
+    source: string;
+    /** The event payload data */
+    data: T;
+    /** Additional custom metadata fields to include in the envelope */
+    extraMetadata?: Record<string, unknown>;
+}
+
 export declare function createKafka(config: KafkaConfig): Kafka;
 
 export declare function createKafkaFromEnv(clientId: string): Kafka;
@@ -130,6 +160,47 @@ export declare interface ErrorHandler<T = unknown> {
     (error: Error, message: ConsumerMessage<T>): Promise<void>;
 }
 
+/**
+ * Generic event envelope that wraps event data with standardized metadata.
+ *
+ * @example
+ * ```typescript
+ * const envelope: EventEnvelope<UserCreatedData> = {
+ *   metadata: {
+ *     eventId: "9e28d9f6-693e-4aff-92f5-0d85faa06442",
+ *     eventType: "user.created",
+ *     eventTime: "2026-02-08T12:33:02.470Z",
+ *     operationType: "insert",
+ *     source: "user-service",
+ *   },
+ *   data: { userId: "123", name: "John" },
+ * };
+ * ```
+ */
+export declare interface EventEnvelope<T> {
+    metadata: EventMetadata;
+    data: T;
+}
+
+/**
+ * Standard event metadata following the event envelope pattern.
+ * Can be extended with additional fields via index signature.
+ */
+export declare interface EventMetadata {
+    /** Unique identifier for the event (UUID) */
+    eventId: string;
+    /** Type/name of the event (e.g. "pix-out.compliance.approved") */
+    eventType: string;
+    /** ISO 8601 timestamp of when the event was created */
+    eventTime: string;
+    /** Type of operation that triggered the event (e.g. "insert", "update", "delete") */
+    operationType?: string;
+    /** Source system that produced the event (e.g. "woovi-compliance") */
+    source: string;
+    /** Additional custom metadata fields */
+    [key: string]: unknown;
+}
+
 /**
  * Extract trace context from Kafka message headers.
  * Returns a Context that can be used to create child spans.
@@ -216,6 +287,26 @@ export declare const messagesProducedTotal: Counter<"topic" | "status">;
 
 export declare function onShutdown(callback: () => Promise<void>): void;
 
+declare interface ParsedEventEnvelope<T> {
+    metadata: EventMetadata;
+    data: T;
+}
+
+/**
+ * Validates and unwraps an event envelope from a consumed message.
+ * Throws if the message does not follow the event envelope pattern.
+ *
+ * @example
+ * ```typescript
+ * const handler = async (message: ConsumerMessage<EventEnvelope<MyEvent>>) => {
+ *   const { metadata, data } = parseEventEnvelope<MyEvent>(message);
+ *   console.log(metadata.eventType, metadata.source);
+ *   console.log(data); // typed as MyEvent
+ * };
+ * ```
+ */
+export declare const parseEventEnvelope: <T>(message: ConsumerMessage<EventEnvelope<T>>) => ParsedEventEnvelope<T>;
+
 export declare const produceLatency: Histogram<"topic">;
 
 export declare interface PublishArgs<T = unknown> {

package/dist/index.js

@@ -1,6 +1,7 @@
 import { Kafka, logLevel } from "kafkajs";
 import { logger } from "@woovi/logger";
 import { Counter, Gauge, Histogram, Registry, collectDefaultMetrics } from "prom-client";
+import { randomUUID } from "node:crypto";
 let kafkaInstance = null;
 let testMode = false;
 const shutdownCallbacks = [];
@@ -1025,4 +1026,30 @@ class WooviConsumer {
 function createConsumer(config) {
     return new WooviConsumer(config);
 }
-export { Kafka, WooviConsumer, WooviProducer, batchProcessingDuration, batchSize, consumerLag, createConsumer, createKafka, createKafkaFromEnv, createProducer, disableTestMode, disableTracing, enableDefaultMetrics, enableTestMode, extractContextFromHeaders, getKafka, getMetrics, getMetricsContentType, healthCheck, initializeTracing, injectContextIntoHeaders, isTestMode, kafkaRegistry, lastMessageTimestamp, logLevel, messageProcessingDuration, messagesFailedTotal, messagesProcessedTotal, messagesProducedTotal, onShutdown, produceLatency, resetMetrics, setMockKafkaForTestMode };
+const createEventEnvelope = (args)=>({
+        metadata: {
+            eventId: randomUUID(),
+            eventType: args.eventType,
+            eventTime: new Date().toISOString(),
+            operationType: args.operationType,
+            source: args.source,
+            ...args.extraMetadata
+        },
+        data: args.data
+    });
+const isValidMetadata = (metadata)=>{
+    if ('object' != typeof metadata || null === metadata) return false;
+    const m = metadata;
+    return 'string' == typeof m.eventId && 'string' == typeof m.eventType && 'string' == typeof m.eventTime && 'string' == typeof m.source;
+};
+const parseEventEnvelope = (message)=>{
+    const envelope = message.data;
+    if (!envelope || 'object' != typeof envelope) throw new Error(`Invalid event envelope: message data is not an object. Topic: ${message.topic}, offset: ${message.offset}`);
+    if (!isValidMetadata(envelope.metadata)) throw new Error(`Invalid event envelope: missing or malformed metadata. Expected eventId, eventType, eventTime, and source. Topic: ${message.topic}, offset: ${message.offset}`);
+    if (!('data' in envelope) || void 0 === envelope.data) throw new Error(`Invalid event envelope: missing data field. Topic: ${message.topic}, offset: ${message.offset}`);
+    return {
+        metadata: envelope.metadata,
+        data: envelope.data
+    };
+};
+export { Kafka, WooviConsumer, WooviProducer, batchProcessingDuration, batchSize, consumerLag, createConsumer, createEventEnvelope, createKafka, createKafkaFromEnv, createProducer, disableTestMode, disableTracing, enableDefaultMetrics, enableTestMode, extractContextFromHeaders, getKafka, getMetrics, getMetricsContentType, healthCheck, initializeTracing, injectContextIntoHeaders, isTestMode, kafkaRegistry, lastMessageTimestamp, logLevel, messageProcessingDuration, messagesFailedTotal, messagesProcessedTotal, messagesProducedTotal, onShutdown, parseEventEnvelope, produceLatency, resetMetrics, setMockKafkaForTestMode };

package/dist/test-utils.cjs

@@ -33,14 +33,15 @@ __webpack_require__.d(__webpack_exports__, {
     mockConsumer: ()=>mockConsumer,
     kafkaAssert: ()=>kafkaAssert,
     Kafka: ()=>Kafka,
+    kafkaAssertEventEnvelope: ()=>kafkaAssertEventEnvelope,
     kafkaAssertLength: ()=>kafkaAssertLength,
     mockProducerSend: ()=>mockProducerSend,
-    mockTransaction: ()=>mockTransaction,
     mockProducerSendBatch: ()=>mockProducerSendBatch,
-    mockTransactionSend: ()=>mockTransactionSend,
+    mockTransaction: ()=>mockTransaction,
     KafkaJSNonRetriableError: ()=>KafkaJSNonRetriableError,
-    setupKafkaTest: ()=>setupKafkaTest,
+    mockTransactionSend: ()=>mockTransactionSend,
     CompressionTypes: ()=>CompressionTypes,
+    setupKafkaTest: ()=>setupKafkaTest,
     mockProducer: ()=>mockProducer
 });
 const getMockFn = ()=>{
@@ -221,6 +222,39 @@ const kafkaAssert = (args)=>{
         throw error;
     }
 };
+const kafkaAssertEventEnvelope_isSubset = (subset, superset)=>{
+    for (const key of Object.keys(subset)){
+        const subValue = subset[key];
+        const superValue = superset[key];
+        if ('object' == typeof subValue && null !== subValue && 'object' == typeof superValue && null !== superValue) {
+            if (!kafkaAssertEventEnvelope_isSubset(subValue, superValue)) return false;
+        } else if (subValue !== superValue) return false;
+    }
+    return true;
+};
+const kafkaAssertEventEnvelope = (args)=>{
+    const { topic, eventType, source, data } = args;
+    const kafkaMessages = getKafkaMessages();
+    const topicMessages = kafkaMessages.filter((m)=>m.topic === topic);
+    if (0 === topicMessages.length) {
+        const error = new Error(`No messages found for topic: ${topic}`);
+        Error.captureStackTrace(error, kafkaAssertEventEnvelope);
+        throw error;
+    }
+    const parsedMessages = topicMessages.flatMap((m)=>m.messages.map((msg)=>JSON.parse(msg.value)));
+    const found = parsedMessages.some((envelope)=>{
+        if (!envelope.metadata || !envelope.data) return false;
+        if (envelope.metadata.eventType !== eventType) return false;
+        if (envelope.metadata.source !== source) return false;
+        if (!envelope.metadata.eventId || !envelope.metadata.eventTime) return false;
+        return kafkaAssertEventEnvelope_isSubset(data, envelope.data);
+    });
+    if (!found) {
+        const error = new Error(`Event envelope not found in topic "${topic}".\nExpected eventType: ${eventType}\nExpected source: ${source}\nExpected data: ${JSON.stringify(data, null, 2)}\nReceived: ${JSON.stringify(parsedMessages, null, 2)}`);
+        Error.captureStackTrace(error, kafkaAssertEventEnvelope);
+        throw error;
+    }
+};
 const kafkaAssertLength = (args)=>{
     const { topic, length } = args;
     const kafkaMessages = getKafkaMessages();
@@ -256,6 +290,7 @@ exports.clearAllMocks = __webpack_exports__.clearAllMocks;
 exports.createMockKafka = __webpack_exports__.createMockKafka;
 exports.getKafkaMessages = __webpack_exports__.getKafkaMessages;
 exports.kafkaAssert = __webpack_exports__.kafkaAssert;
+exports.kafkaAssertEventEnvelope = __webpack_exports__.kafkaAssertEventEnvelope;
 exports.kafkaAssertLength = __webpack_exports__.kafkaAssertLength;
 exports.logLevel = __webpack_exports__.logLevel;
 exports.mockAdmin = __webpack_exports__.mockAdmin;
@@ -275,6 +310,7 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "createMockKafka",
     "getKafkaMessages",
     "kafkaAssert",
+    "kafkaAssertEventEnvelope",
     "kafkaAssertLength",
     "logLevel",
     "mockAdmin",

package/dist/test-utils.d.ts

@@ -33,6 +33,29 @@ declare type KafkaAssertArgs = {
     message: Record<string, unknown>;
 };
 
+/**
+ * Asserts that a message with the event envelope pattern was published to a topic.
+ * Validates the envelope structure (metadata + data) and checks the data content.
+ *
+ * @example
+ * ```typescript
+ * kafkaAssertEventEnvelope({
+ *   topic: 'pix-out.compliance.approved',
+ *   eventType: 'pix-out.compliance.approved',
+ *   source: 'woovi-compliance',
+ *   data: { movementId: '123', pixOutId: '456' },
+ * });
+ * ```
+ */
+export declare const kafkaAssertEventEnvelope: (args: KafkaAssertEventEnvelopeArgs) => void;
+
+declare type KafkaAssertEventEnvelopeArgs = {
+    topic: string;
+    eventType: string;
+    source: string;
+    data: Record<string, unknown>;
+};
+
 export declare const kafkaAssertLength: (args: KafkaAssertLengthArgs) => void;
 
 declare type KafkaAssertLengthArgs = {

package/dist/test-utils.js

@@ -176,6 +176,39 @@ const kafkaAssert = (args)=>{
         throw error;
     }
 };
+const kafkaAssertEventEnvelope_isSubset = (subset, superset)=>{
+    for (const key of Object.keys(subset)){
+        const subValue = subset[key];
+        const superValue = superset[key];
+        if ('object' == typeof subValue && null !== subValue && 'object' == typeof superValue && null !== superValue) {
+            if (!kafkaAssertEventEnvelope_isSubset(subValue, superValue)) return false;
+        } else if (subValue !== superValue) return false;
+    }
+    return true;
+};
+const kafkaAssertEventEnvelope = (args)=>{
+    const { topic, eventType, source, data } = args;
+    const kafkaMessages = getKafkaMessages();
+    const topicMessages = kafkaMessages.filter((m)=>m.topic === topic);
+    if (0 === topicMessages.length) {
+        const error = new Error(`No messages found for topic: ${topic}`);
+        Error.captureStackTrace(error, kafkaAssertEventEnvelope);
+        throw error;
+    }
+    const parsedMessages = topicMessages.flatMap((m)=>m.messages.map((msg)=>JSON.parse(msg.value)));
+    const found = parsedMessages.some((envelope)=>{
+        if (!envelope.metadata || !envelope.data) return false;
+        if (envelope.metadata.eventType !== eventType) return false;
+        if (envelope.metadata.source !== source) return false;
+        if (!envelope.metadata.eventId || !envelope.metadata.eventTime) return false;
+        return kafkaAssertEventEnvelope_isSubset(data, envelope.data);
+    });
+    if (!found) {
+        const error = new Error(`Event envelope not found in topic "${topic}".\nExpected eventType: ${eventType}\nExpected source: ${source}\nExpected data: ${JSON.stringify(data, null, 2)}\nReceived: ${JSON.stringify(parsedMessages, null, 2)}`);
+        Error.captureStackTrace(error, kafkaAssertEventEnvelope);
+        throw error;
+    }
+};
 const kafkaAssertLength = (args)=>{
     const { topic, length } = args;
     const kafkaMessages = getKafkaMessages();
@@ -203,4 +236,4 @@ function setupKafkaTest() {
         testMode: true
     };
 }
-export { CompressionTypes, Kafka, KafkaJSNonRetriableError, KafkaJSProtocolError, clearAllMocks, createMockKafka, getKafkaMessages, kafkaAssert, kafkaAssertLength, logLevel, mockAdmin, mockConsumer, mockProducer, mockProducerSend, mockProducerSendBatch, mockTransaction, mockTransactionSend, setupKafkaTest };
+export { CompressionTypes, Kafka, KafkaJSNonRetriableError, KafkaJSProtocolError, clearAllMocks, createMockKafka, getKafkaMessages, kafkaAssert, kafkaAssertEventEnvelope, kafkaAssertLength, logLevel, mockAdmin, mockConsumer, mockProducer, mockProducerSend, mockProducerSendBatch, mockTransaction, mockTransactionSend, setupKafkaTest };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@woovi/kafka",
   "description": "Kafka setup and utilities for Woovi microservices",
-  "version": "1.0.4",
+  "version": "1.0.8",
   "author": "",
   "type": "module",
   "dependencies": {
@@ -47,10 +47,10 @@
   ],
   "license": "ISC",
   "main": "./dist/index.cjs",
+  "packageManager": "pnpm@10.14.0",
   "publishConfig": {
     "access": "public"
   },
-  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rslib build",
     "test": "vitest",
@@ -63,5 +63,6 @@
     "release:major": "npm version major && git push --follow-tags",
     "release:minor": "npm version minor && git push --follow-tags",
     "release:patch": "npm version patch && git push --follow-tags"
-  }
-}
+  },
+  "types": "./dist/index.d.ts"
+}