@siglo/kafka 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Jerico de guzman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,299 @@
-# Temporary Holding Version
+# @siglo/kafka Adapter Guide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@siglo/kafka` provides an enterprise event streaming consumer adapter for executing `Siglo` workflows from Apache Kafka topics. It handles binary and JSON payload deserialization, partition offset tracking, distributed idempotency deduplication, header-based tenant namespace routing, and graceful error recovery.
+
+---
+
+## 1. Overview & Architecture
+
+In an event-driven architecture, Kafka delivers partitioned event streams to consumer groups. The `@siglo/kafka` adapter handles incoming messages, ensures exactly-once semantics via an `IdempotencyStore`, and executes the workflow within configured timeout bounds:
+
+```mermaid
+flowchart TD
+    Broker["Kafka Broker / Topic"] -->|Record: key, value, headers, offset| Consumer["KafkaJS Consumer"]
+    Consumer -->|eachMessage| Handler["createKafkaMessageHandler<br/>• Parse JSON / Buffer<br/>• Generate Idemp Key: kafka:topic:key|off<br/>• Claim Idempotency Key<br/>• Extract x-namespace"]
+    Handler --> WF["Siglo Workflow<br/>• Sagas & Compensations<br/>• Timeout Deadlines"]
+    WF -->|On Success| Success["Complete Claim (idempotencyStore)<br/>Commit Offset"]
+    WF -->|On Failure| Failure["Fail Claim (idempotencyStore)<br/>Re-throw / DLQ"]
+```
+
+---
+
+## 2. Execution Model: In-Process vs. Distributed Step Execution
+
+A common question in distributed event-driven systems is:
+
+> **"If I have a 10-step workflow, will those 10 steps run across different consumer servers?"**
+
+### Direct Answer: **No. By default, all 10 steps execute in-process on the single consumer server that pulled the Kafka message.**
+
+`Siglo` is an **in-process orchestrator** rather than a multi-machine RPC scheduler (such as Temporal or AWS Step Functions).
+
+When an instance of your consumer service pulls a Kafka record, the entire 10-step pipeline runs in-memory on that node:
+
+```mermaid
+flowchart TD
+    Broker["Kafka Broker"] -->|Topic Partition 0| Server["Consumer Server 1"]
+    Server -->|createKafkaMessageHandler| S1["Step 1 (Validate)"]
+    S1 -->|Direct in-memory promise| S2["Step 2 (Enrich)"]
+    S2 --> Dots["..."]
+    Dots --> S10["Step 10 (Audit)"]
+    S10 --> Commit["Commit Kafka Offset"]
+```
+
+### Why In-Process Execution is Vastly Superior for 90%+ of Workloads
+
+| Dimension | In-Process Orchestration (`Siglo`) | Distributed Step Orchestration (Temporal / Step Functions) |
+| :--- | :--- | :--- |
+| **Step-to-Step Latency** | **Microseconds** ($\approx 1\text{–}5\ \mu\text{s}$) &mdash; Direct async promise resolution. | **Milliseconds** ($\approx 15\text{–}100\ \text{ms}$) &mdash; Every step requires network RPC, queue write, and DB commit. |
+| **End-to-End Latency (10 Steps)** | $\approx \mathbf{5\text{–}20\ \text{ms}}$ (pure business logic time) | $\approx \mathbf{200\text{–}1000\ \text{ms}}$ (dominated by orchestration network latency) |
+| **Throughput per Node** | **10,000+ msgs/sec** (bounded only by CPU and I/O) | Typically 500–2,000 ops/sec (queue/database bottlenecks) |
+| **Payload Limitations** | **None** &mdash; Pass TypeScript domain models, Buffers, Maps, or Streams in memory. | **Strict Limits** &mdash; Payloads must serialize to JSON (e.g., SQS 256 KB, Temporal 2 MB limits). |
+| **Infrastructure Overhead** | **Zero** &mdash; Runs directly inside your application container. | **Heavy** &mdash; Requires external clusters (History, Matching, Frontend engines, Cassandra/Postgres). |
+| **Debugging & Local Testing** | **Trivial** &mdash; Set standard debugger breakpoints stepping from Step 1 to Step 2. | **Difficult** &mdash; Requires cross-machine distributed trace correlation and event replay. |
+| **Saga Rollback Latency** | **Immediate** &mdash; Atomic reverse rollback in local memory if Step 8 fails. | **Delayed** &mdash; Rollback messages queue behind other cluster tasks. |
+
+#### 1. The "10 Network Hops" Tax
+In systems that distribute every individual step to different servers:
+$$\text{Total Overhead} = 10 \times (\text{JSON Serialization} + \text{Queue Network Write} + \text{Broker Scheduling} + \text{Queue Network Read} + \text{Deserialization})$$
+In such systems, **95% of total workflow duration is spent waiting for network hops and queue contention**, and only 5% executing real code. In `Siglo`, Step 1 immediately yields to Step 2 in memory with zero serialization penalty.
+
+#### 2. How High-Throughput Scaling Actually Works
+Work is scaled horizontally by **Kafka Partitions (Message-Level Distribution)**, not by splitting individual steps across machines:
+
+```mermaid
+flowchart TD
+    Topic["Kafka: orders Topic (4 Partitions)"]
+    Topic --> P0["Partition 0"]
+    Topic --> P1["Partition 1"]
+    Topic --> P2["Partition 2"]
+    Topic --> P3["Partition 3"]
+
+    P0 --> S0["Server 1<br/>(Runs steps 1-10 for Msg A)"]
+    P1 --> S1["Server 2<br/>(Runs steps 1-10 for Msg B)"]
+    P2 --> S2["Server 3<br/>(Runs steps 1-10 for Msg C)"]
+    P3 --> S3["Server 4<br/>(Runs steps 1-10 for Msg D)"]
+```
+
+Each consumer server processes independent messages in parallel at full hardware capability with maximum CPU cache locality.
+
+---
+
+## 3. How to Distribute Steps Across Different Servers (When Needed)
+
+Distributing individual steps across physically separate machines is only necessary in specific architectural scenarios:
+1. **Heterogeneous Compute**: Steps 1–3 run on standard Node.js CPU instances, but Step 4 requires dedicated GPU worker nodes (e.g. AI model inference).
+2. **Distinct Microservice Boundaries**: Steps 1–3 belong to the *Checkout Team*, while Steps 4–7 belong to the *Fulfillment Team*.
+3. **Multi-Hour Uninterruptible Tasks**: Tasks taking hours where a crash cannot afford restarting from Step 1.
+
+For these cases, implement **Event-Driven Choreography** using intermediate Kafka topics:
+
+```mermaid
+flowchart LR
+    subgraph Stage1["STAGE 1: Order Service (Server A)"]
+        T1["Topic 1: orders.created"] --> SF1["Subflow 1<br/>(Steps 1 - 3)"]
+    end
+
+    subgraph Stage2["STAGE 2: AI GPU Worker (Server B)"]
+        T2["Topic 2: orders.validated"] --> SF2["Subflow 2<br/>(Steps 4 - 7)"]
+    end
+
+    subgraph Stage3["STAGE 3: Ledger Service (Server C)"]
+        T3["Topic 3: images.rendered"] --> SF3["Subflow 3<br/>(Steps 8 - 10)"]
+    end
+
+    SF1 -->|Produce to orders.validated| T2
+    SF2 -->|Produce to images.rendered| T3
+```
+
+### Pattern Example: Chaining Workflows Across Topics
+
+```typescript
+// --- SERVICE A: Order Service (Runs Steps 1 to 3) ---
+const step1 = Step.create('validate', async (order: any) => ({ valid: true, order }));
+const step2 = Step.create('checkCredit', async (ctx: any) => ({ creditApproved: true }));
+const step3_publish = Step.create('publishValidated', async (ctx: any) => {
+    // Produce message to intermediate topic for Service B
+    await kafkaProducer.send({
+        topic: 'orders.validated',
+        messages: [{ key: ctx.order.id, value: JSON.stringify(ctx) }],
+    });
+    return { published: true };
+});
+
+const stage1Flow = flow(step1, step2, step3_publish);
+const stage1Handler = createKafkaMessageHandler(stage1Flow);
+
+
+// --- SERVICE B: GPU Processing Service (Runs Steps 4 to 6) ---
+const step4 = Step.create('generateAssets', async (ctx: any) => ({ assetUrl: 'https://...' }));
+const step5 = Step.create('renderVideo', async (ctx: any) => ({ videoRendered: true }));
+const step6_publish = Step.create('publishRendered', async (ctx: any) => {
+    await kafkaProducer.send({
+        topic: 'images.rendered',
+        messages: [{ key: ctx.order.id, value: JSON.stringify(ctx) }],
+    });
+    return { dispatched: true };
+});
+
+const stage2Flow = flow(step4, step5, step6_publish);
+const stage2Handler = createKafkaMessageHandler(stage2Flow);
+```
+
+---
+
+## 4. Crash Recovery, Rebalances & Failure Semantics
+
+What happens if Server 1 is executing **Step 6** of 10 and the process crashes?
+
+1. **Uncommitted Offset**: The `@siglo/kafka` adapter only returns and acknowledges the Kafka record after the workflow completes. Because Step 6 failed or the process died, the offset is **never committed**.
+2. **Kafka Partition Rebalance**: Kafka detects consumer heartbeat loss and reassigns that topic partition to another consumer (Server 2).
+3. **Idempotency Protection**: Server 2 re-receives the message from the last committed offset. When it calls `createKafkaMessageHandler`, the configured `IdempotencyStore` (`@siglo/redis` or `@siglo/postgres`) ensures external payments or mutations aren't duplicated.
+4. **Durable Resumption**: If durable execution was used with `@siglo/postgres`, state saved from prior checkpoints can be loaded via `restoreCheckpoint()`.
+
+---
+
+## 5. Installation & Requirements
+
+Install `@siglo/kafka` and `kafkajs`:
+
+```bash
+npm install @siglo/core @siglo/kafka kafkajs
+```
+
+Peer dependency matrix:
+- `Siglo`: `*` (v1.0.0+)
+- `kafkajs`: `^2.0.0`
+
+---
+
+## 6. API Reference
+
+### `createKafkaMessageHandler(workflow, options)`
+
+Creates an asynchronous message consumer handler:
+
+```typescript
+function createKafkaMessageHandler<TInput = any, TOutput = any>(
+    workflow: Flow<TInput, TOutput>,
+    options?: SigloKafkaOptions<TInput, TOutput>
+): (payload: { topic: string; partition: number; message: SigloKafkaMessage }) => Promise<any>;
+```
+
+### `SigloKafkaMessage` Interface
+
+```typescript
+export interface SigloKafkaMessage {
+    key?: Buffer | string | null;
+    value?: Buffer | string | null;
+    partition: number;
+    topic: string;
+    offset: string;
+    headers?: Record<string, Buffer | string | undefined>;
+}
+```
+
+---
+
+## 7. Configuration Options (`SigloKafkaOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `input` | `(message: SigloKafkaMessage) => Promise<TInput> \| TInput` | JSON parser on `message.value` | Custom transformer converting Kafka record into workflow input. |
+| `output` | `(result: any, message: SigloKafkaMessage) => Promise<TOutput> \| TOutput` | `result` | Custom post-processor formatting the workflow output. |
+| `idempotencyStore` | `IdempotencyStore` | `undefined` | Distributed store (e.g., `RedisIdempotencyStore` or `PostgresIdempotencyStore`) to prevent duplicate processing. |
+| `idempotencyTtlMs` | `number` | `86400000` (24h) | Time-to-live for idempotency claim lock. |
+| `timeout` | `number` | `undefined` | SLA execution timeout in milliseconds. |
+| `namespace` | `string \| ((message: SigloKafkaMessage) => string \| undefined)` | `message.headers['x-namespace']` | Namespace identifier for tenant partitioning. |
+
+---
+
+## 8. Idempotency Key Semantics
+
+Kafka guarantees at-least-once message delivery under network failures or consumer rebalances. `@siglo/kafka` constructs an idempotency key using the message record's natural identity:
+
+$$\text{idempKey} = \text{kafka}:\langle\text{topic}\rangle:\langle\text{key} \lor (\text{partition}:\text{offset})\rangle$$
+
+- If `message.key` is defined (e.g., `user_8819`), the key is `kafka:orders:user_8819`.
+- If `message.key` is null, the key falls back to partition and offset: `kafka:orders:2:104921`.
+
+### Claim States:
+1. `'completed'`: The message was already processed in a previous attempt. The adapter immediately returns the cached result without executing the workflow.
+2. `'in-progress'`: Throws `Error('Kafka message ... is already being processed concurrently')`, preventing duplicate parallel writes.
+3. `'claimed'`: Executes workflow. On completion, saves result; on error, calls `store.fail()` so subsequent retries are permitted.
+
+---
+
+## 9. Complete Production Consumer Example
+
+```typescript
+import { Kafka } from 'kafkajs';
+import { Step, flow } from '@siglo/core';
+import { createKafkaMessageHandler } from '@siglo/kafka';
+import { PostgresIdempotencyStore } from '@siglo/postgres';
+import { Pool } from 'pg';
+
+// 1. Database & Idempotency Store
+const pgPool = new Pool({ connectionString: process.env.DATABASE_URL });
+const idempotencyStore = new PostgresIdempotencyStore({ client: pgPool });
+await idempotencyStore.ensureTable();
+
+// 2. Define Transaction Processing Workflow
+interface PaymentEvent {
+    paymentId: string;
+    accountId: string;
+    amount: number;
+    currency: string;
+}
+
+const validateAccount = Step.create('validateAccount', async (param: PaymentEvent) => {
+    console.log(`Checking account ${param.accountId} balance for payment ${param.paymentId}`);
+    return { accountValid: true };
+});
+
+const debitAccount = Step.create('debitAccount', async (param: any) => {
+    console.log(`Debiting ${param.amount} ${param.currency} from ${param.accountId}`);
+    return { ledgerEntryId: `led_${Date.now()}`, debited: true };
+});
+
+const paymentPipeline = flow(validateAccount, debitAccount);
+
+// 3. Setup Kafka Consumer
+const kafka = new Kafka({
+    clientId: 'payment-consumer-service',
+    brokers: ['localhost:9092'],
+});
+
+const consumer = kafka.consumer({ groupId: 'payment-engine-group' });
+
+const messageHandler = createKafkaMessageHandler(paymentPipeline, {
+    idempotencyStore,
+    idempotencyTtlMs: 3600000, // 1 hour claim lock
+    timeout: 5000,             // 5s execution SLA
+    namespace: (msg) => String(msg.headers?.['x-tenant-id'] || 'default'),
+});
+
+await consumer.connect();
+await consumer.subscribe({ topic: 'payments.inbound', fromBeginning: false });
+
+await consumer.run({
+    eachMessage: async (payload) => {
+        try {
+            const result = await messageHandler(payload);
+            console.log(`Processed payment message offset ${payload.message.offset}:`, result);
+        } catch (err: any) {
+            console.error(`Failed processing message at offset ${payload.message.offset}: ${err.message}`);
+            // Depending on architecture: push to Dead Letter Queue (DLQ) or let consumer retry
+            throw err;
+        }
+    },
+});
+
+// 4. Graceful Shutdown
+process.on('SIGTERM', async () => {
+    console.log('Disconnecting Kafka consumer...');
+    await consumer.disconnect();
+    await pgPool.end();
+    process.exit(0);
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { Flow, IdempotencyStore } from '@siglo/core';
+export interface SigloKafkaMessage {
+    key?: Buffer | string | null;
+    value?: Buffer | string | null;
+    partition: number;
+    topic: string;
+    offset: string;
+    headers?: Record<string, Buffer | string | undefined>;
+}
+export interface SigloKafkaOptions<TInput = any, TOutput = any> {
+    input?: (message: SigloKafkaMessage) => Promise<TInput> | TInput;
+    output?: (result: any, message: SigloKafkaMessage) => Promise<TOutput> | TOutput;
+    idempotencyStore?: IdempotencyStore;
+    idempotencyTtlMs?: number;
+    timeout?: number;
+    namespace?: string | ((message: SigloKafkaMessage) => string | undefined);
+}
+/**
+ * Creates a Kafka message consumer handler for executing a rivulet workflow.
+ */
+export declare function createKafkaMessageHandler<TInput = any, TOutput = any>(workflow: Flow<TInput, TOutput>, options?: SigloKafkaOptions<TInput, TOutput>): (payload: {
+    topic: string;
+    partition: number;
+    message: SigloKafkaMessage;
+}) => Promise<any>;
+export type RivuletKafkaMessage = SigloKafkaMessage;
+export type RivuletKafkaOptions<TInput = any, TOutput = any> = SigloKafkaOptions<TInput, TOutput>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAoB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAC1D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACjE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACjF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,iBAAiB,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;CAC7E;AAiBD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,EACjE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,GAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAM,aAEzB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,KAAG,OAAO,CAAC,GAAG,CAAC,CA+DzG;AAGD,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AACpD,MAAM,MAAM,mBAAmB,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/index.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKafkaMessageHandler = createKafkaMessageHandler;
+function unwrapContext(obj) {
+    if (!obj || typeof obj !== 'object') {
+        return obj;
+    }
+    const clean = {};
+    for (const key of Object.keys(obj)) {
+        if (key.startsWith('$')) {
+            continue;
+        }
+        const val = typeof obj[key] === 'function' ? (obj[key].val !== undefined ? obj[key].val : (obj[key].length === 0 ? obj[key]() : obj[key])) : obj[key];
+        clean[key] = val;
+    }
+    return clean;
+}
+/**
+ * Creates a Kafka message consumer handler for executing a rivulet workflow.
+ */
+function createKafkaMessageHandler(workflow, options = {}) {
+    return async (payload) => {
+        const { message, topic, partition } = payload;
+        const msgKey = message.key ? String(message.key) : `${topic}:${partition}:${message.offset}`;
+        const idempKey = `kafka:${topic}:${msgKey}`;
+        if (options.idempotencyStore) {
+            const status = await options.idempotencyStore.claim(idempKey, options.idempotencyTtlMs);
+            if (status === 'completed') {
+                return options.idempotencyStore.getResult?.(idempKey) ?? { deduplicated: true };
+            }
+            if (status === 'in-progress') {
+                throw new Error(`Kafka message ${idempKey} is already being processed concurrently`);
+            }
+        }
+        try {
+            let parsedValue = {};
+            if (options.input) {
+                parsedValue = await options.input(message);
+            }
+            else if (message.value) {
+                const str = Buffer.isBuffer(message.value)
+                    ? message.value.toString('utf-8')
+                    : (typeof message.value === 'string' ? message.value : String(message.value));
+                try {
+                    parsedValue = JSON.parse(str);
+                }
+                catch {
+                    parsedValue = { raw: str };
+                }
+            }
+            let namespace;
+            if (typeof options.namespace === 'function') {
+                namespace = options.namespace(message);
+            }
+            else if (options.namespace) {
+                namespace = options.namespace;
+            }
+            else if (message.headers?.['x-namespace']) {
+                namespace = String(message.headers['x-namespace']);
+            }
+            const execOptions = {
+                timeout: options.timeout,
+                namespace,
+            };
+            const rawResult = await workflow.run(parsedValue, execOptions);
+            const cleanResult = unwrapContext(rawResult);
+            if (options.idempotencyStore) {
+                await options.idempotencyStore.complete(idempKey, cleanResult);
+            }
+            if (options.output) {
+                return await options.output(cleanResult, message);
+            }
+            return cleanResult;
+        }
+        catch (err) {
+            if (options.idempotencyStore) {
+                await options.idempotencyStore.fail(idempKey, err);
+            }
+            throw err;
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@siglo/kafka",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Kafka consumer message handler and event streaming adapter for Siglo workflows",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && mocha -r tsx 'src/**/*.test.ts'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsoftgem/siglo.git",
+    "directory": "packages/kafka"
+  },
+  "author": "Jerico de Guzman",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jsoftgem/siglo/issues"
+  },
+  "homepage": "https://github.com/jsoftgem/siglo#readme",
+  "dependencies": {
+    "@siglo/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "kafkajs": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "kafkajs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^26.6.5",
+    "chai": "^3.5.0",
+    "mocha": "^12.0.3",
+    "tsx": "^4.23.15",
+    "typescript": "~5.7.0"
+  }
+}