@crossdelta/cloudevents 0.1.13 → 0.2.1

package/README.md

@@ -1,288 +1,248 @@
 # @crossdelta/cloudevents
 
-[![npm version](https://img.shields.io/npm/v/@crossdelta/cloudevents.svg)](https://www.npmjs.com/package/@crossdelta/cloudevents)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-
-A TypeScript toolkit for [CloudEvents](https://cloudevents.io/) over [NATS](https://nats.io/).
-
-Publish events from one service, consume them in another — with automatic handler discovery, type-safe validation, and guaranteed delivery via JetStream.
+Type-safe event-driven microservices with [NATS](https://nats.io) and [Zod](https://zod.dev) validation, using the [CloudEvents](https://cloudevents.io) specification.
 
 ```
-┌─────────────────┐       NATS        ┌─────────────────┐
-│  orders-service │ ──── publish ───► │  JetStream      │
-└─────────────────┘    CloudEvent     │  (persistent)   │
-                                      └────────┬────────┘
-                                               │
-                       ┌───────────────────────┼───────────────────────┐
-                       ▼                       ▼                       ▼
-              ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-              │  notifications  │     │  billing        │     │  analytics      │
-              │  service        │     │  service        │     │  service        │
-              └─────────────────┘     └─────────────────┘     └─────────────────┘
-                   consume               consume                  consume
+                         NATS JetStream
+                        ┌──────────────┐
+  ┌──────────────┐      │              │      ┌──────────────┐
+  │    Service   │      │   Stream:    │      │   Service    │
+  │   (publish)  │─────▶│   ORDERS     │─────▶│  (consume)   │
+  └──────────────┘      │              │      └──────────────┘
+                        └──────────────┘
+        │                                            │
+        │  publishNatsRawEvent(...)                  │  handleEvent(...)
+        ▼                                            ▼
+  ┌──────────────┐                            ┌──────────────┐
+  │ { orderId,   │                            │ Zod schema   │
+  │   total }    │                            │ validates    │
+  └──────────────┘                            └──────────────┘
 ```
 
-## Why this library?
-
-Event-driven microservices are hard: messages get lost when services restart, handlers are scattered across files, validation is inconsistent.
-
-| Feature | Benefit |
-|---------|---------|
-| 🔍 **Auto-discovery** | Drop a `*.event.ts` file, it's registered automatically |
-| 🛡️ **Type-safe handlers** | Zod schemas ensure runtime validation matches TypeScript |
-| 🔄 **JetStream persistence** | Messages survive restarts, get retried on failure |
-| 🏥 **DLQ-safe processing** | Invalid messages are quarantined, not lost |
-
-## Installation
-
 ```bash
-bun add @crossdelta/cloudevents
+bun add @crossdelta/cloudevents zod
 ```
 
-## Configuration
-
-### NATS Connection
-
-All NATS functions use this fallback chain for the server URL:
-
-1. **`servers` option** (explicit) → `{ servers: 'nats://my-server:4222' }`
-2. **`NATS_URL` env var** → `export NATS_URL=nats://my-server:4222`
-3. **Default** → `nats://localhost:4222`
+> **Prerequisites:** A running [NATS server](https://docs.nats.io/running-a-nats-service/introduction) with JetStream enabled.
 
-For most deployments, just set the `NATS_URL` environment variable — no code changes needed.
+## Quick Start
 
-## Getting Started
-
-A minimal example: `orders-service` publishes an event, `notifications-service` consumes it.
-
-### 1. Publish an Event (orders-service)
+**1. Create an event handler** (`src/handlers/order-created.event.ts`):
 
 ```typescript
-// orders-service/src/index.ts
-import { publishNatsEvent } from '@crossdelta/cloudevents'
-
-// When an order is created...
-await publishNatsEvent({
-  type: 'com.acme.orders.created',
-  source: '/orders-service',
-  data: {
-    orderId: 'ord_123',
-    customerId: 'cust_456',
-    total: 99.99,
-  },
-})
-```
-
-### 2. Define a Handler (notifications-service)
-
-```typescript
-// notifications-service/src/handlers/order-created.event.ts
-import { z } from 'zod'
 import { handleEvent } from '@crossdelta/cloudevents'
+import { z } from 'zod'
 
 export default handleEvent({
-  type: 'com.acme.orders.created',
+  type: 'orders.created',
   schema: z.object({
     orderId: z.string(),
-    customerId: z.string(),
     total: z.number(),
   }),
-  async handle(data) {
-    console.log(`📧 Sending confirmation for order ${data.orderId}`)
-    // Send email, push notification, etc.
-  },
+}, async (data) => {
+  console.log(`New order: ${data.orderId}, total: ${data.total}`)
 })
 ```
 
-### 3. Start Consuming (notifications-service)
+**2. Start consuming:**
 
 ```typescript
-// notifications-service/src/index.ts
 import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
 
 await consumeJetStreamEvents({
-  stream: 'ORDERS',
-  subjects: ['com.acme.orders.>'],
-  consumer: 'notifications-service',
-  discover: './src/handlers/**/*.event.ts',  // Auto-discovers handlers
+  stream: 'ORDERS',                         // Auto-created if not exists
+  subjects: ['orders.*'],
+  consumer: 'my-service',
+  discover: './src/handlers/**/*.event.ts',
 })
+```
 
-console.log('🎧 Listening for order events...')
+**3. Publish from another service:**
+
+```typescript
+import { publish } from '@crossdelta/cloudevents'
+
+await publish('orders.created', { orderId: 'ord_123', total: 99.99 })
 ```
 
-**That's it.** The handler is discovered automatically, events are persisted in JetStream, and failed messages are retried.
+That's it. Handlers are auto-discovered, validated with Zod, and messages persist in JetStream.
 
-## Consuming Events
+---
 
-### NATS Core (Fire & Forget)
+## Why use this?
 
-For high-throughput scenarios where occasional message loss is acceptable:
+| Problem | Solution |
+|---------|----------|
+| Messages lost on restart | JetStream persists messages |
+| Scattered handler registration | Auto-discovery via glob patterns |
+| Runtime type errors | Zod validation with TypeScript inference |
+| Poison messages crash services | DLQ quarantines invalid messages |
 
-```typescript
-import { consumeNatsEvents } from '@crossdelta/cloudevents'
+---
 
-await consumeNatsEvents({
-  subject: 'telemetry.>',
-  discover: './src/handlers/**/*.event.ts',
+## Core Concepts
+
+### Handlers
+
+Drop a `*.event.ts` file anywhere — it's auto-registered:
+
+```typescript
+// src/handlers/user-signup.event.ts
+export default handleEvent({
+  type: 'users.signup',
+  schema: z.object({ email: z.string().email() }),
+}, async (data) => {
+  await sendWelcomeEmail(data.email)
 })
 ```
 
-### NATS JetStream (Guaranteed Delivery)
-
-For critical business events that must not be lost:
+### Publishing
 
 ```typescript
-import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
+await publish('orders.created', orderData)
+```
+
+### Consuming
 
+```typescript
+// JetStream (recommended) — persistent, retries, exactly-once
 await consumeJetStreamEvents({
-  // Stream configuration
   stream: 'ORDERS',
-  subjects: ['orders.>'],
-  
-  // Consumer configuration
-  consumer: 'billing-service',
+  subjects: ['orders.*'],
+  consumer: 'billing',
+  discover: './src/handlers/**/*.event.ts',
+})
+
+// Core NATS — fire-and-forget, simpler
+await consumeNatsEvents({
+  subjects: ['notifications.*'],
   discover: './src/handlers/**/*.event.ts',
-  
-  // Optional: Stream settings
-  streamConfig: {
-    maxAge: 7 * 24 * 60 * 60 * 1_000_000_000, // 7 days retention
-    maxBytes: 1024 * 1024 * 1024,              // 1 GB max
-    numReplicas: 3,                            // For HA clusters
-  },
-  
-  // Optional: Consumer settings
-  ackWait: 30_000,   // 30s to process before retry
-  maxDeliver: 5,     // Max retry attempts
-  startFrom: 'all',  // 'new' | 'all' | 'last' | Date
 })
 ```
 
-## Handler Patterns
+---
 
-### Data-Only Schema (Recommended)
+## Configuration
+
+### Environment Variables
+
+```bash
+NATS_URL=nats://localhost:4222
+NATS_USER=myuser        # optional
+NATS_PASSWORD=mypass    # optional
+```
 
-The simplest pattern — just validate the `data` field:
+### Consumer Options
 
 ```typescript
-export default handleEvent({
-  type: 'com.example.users.created',
-  schema: z.object({
-    userId: z.string().uuid(),
-    email: z.string().email(),
-  }),
-  async handle(data) {
-    // data is typed as { userId: string, email: string }
-  },
+await consumeJetStreamEvents({
+  // Required
+  stream: 'ORDERS',
+  subjects: ['orders.*'],
+  consumer: 'my-service',
+  discover: './src/handlers/**/*.event.ts',
+
+  // Optional
+  servers: 'nats://localhost:4222',
+  maxDeliver: 5,           // Retry attempts
+  ackWait: 30_000,         // Timeout per attempt (ms)
+  quarantineTopic: 'dlq',  // For poison messages
 })
 ```
 
-### Full CloudEvent Schema
+---
+
+## Advanced Features
+
+<details>
+<summary><b>Multi-Tenancy</b></summary>
 
-When you need access to CloudEvent metadata:
+Filter events by tenant:
 
 ```typescript
 export default handleEvent({
-  type: 'com.example.orders.shipped',
-  schema: z.object({
-    data: z.object({
-      orderId: z.string(),
-      trackingNumber: z.string(),
-    }),
-    source: z.string(),
-    subject: z.string().optional(),
-  }),
-  async handle(event) {
-    // event.data, event.source, event.subject all available
-  },
-})
+  type: 'orders.created',
+  schema: OrderSchema,
+  tenantId: 'tenant-a',  // Only process tenant-a events
+}, async (data) => { ... })
 ```
 
-### Conditional Matching
+</details>
+
+<details>
+<summary><b>Custom Matching</b></summary>
 
-Process only specific events:
+Add custom filter logic:
 
 ```typescript
 export default handleEvent({
-  type: 'com.example.orders.*',
+  type: 'orders.created',
   schema: OrderSchema,
-  match: (event) => event.data.region === 'EU',
-  async handle(data) {
-    // Only EU orders
-  },
-})
+  match: (event) => event.data.total > 100,  // Only high-value orders
+}, async (data) => { ... })
 ```
 
-## Publishing
+</details>
+
+<details>
+<summary><b>Idempotency</b></summary>
 
-### To NATS
+Deduplication is built-in. For distributed systems, provide a Redis store:
 
 ```typescript
-import { publishNatsEvent, publishNatsRawEvent } from '@crossdelta/cloudevents'
-
-// Structured CloudEvent
-await publishNatsEvent({
-  type: 'com.example.orders.created',
-  source: '/orders-service',
-  subject: 'order-123',
-  data: { orderId: '123', total: 99.99 },
-})
+const redisStore = {
+  has: (id) => redis.exists(`idem:${id}`),
+  add: (id, ttl) => redis.set(`idem:${id}`, '1', 'PX', ttl),
+}
 
-// Raw data (auto-wrapped in CloudEvent)
-await publishNatsRawEvent('orders.created', {
-  orderId: '123',
-  total: 99.99,
+await consumeJetStreamEvents({
+  // ...
+  idempotencyStore: redisStore,
 })
 ```
 
-### To Google Pub/Sub
+</details>
 
-```typescript
-import { publishEvent } from '@crossdelta/cloudevents'
+<details>
+<summary><b>Dead Letter Queue</b></summary>
+
+Invalid messages are quarantined, not lost:
 
-await publishEvent('orders-topic', {
-  type: 'com.example.orders.created',
-  data: { orderId: '123' },
+```typescript
+await consumeJetStreamEvents({
+  // ...
+  quarantineTopic: 'events.quarantine',
+  errorTopic: 'events.errors',
 })
 ```
 
-## Hono Middleware
+</details>
 
-For HTTP-based event ingestion:
+<details>
+<summary><b>HTTP Ingestion (Hono)</b></summary>
 
 ```typescript
 import { Hono } from 'hono'
 import { cloudEvents } from '@crossdelta/cloudevents'
 
 const app = new Hono()
-
-app.use('/events', cloudEvents({
-  discover: 'src/handlers/**/*.event.ts',
-  dlqEnabled: true,
-}))
+app.use('/events', cloudEvents({ discover: 'src/handlers/**/*.event.ts' }))
 ```
 
-## API Reference
-
-| Function | Description |
-|----------|-------------|
-| `handleEvent(config)` | Create a discoverable event handler |
-| `consumeJetStreamEvents(options)` | Subscribe with guaranteed delivery |
-| `consumeNatsEvents(options)` | Subscribe with fire-and-forget |
-| `publishNatsEvent(event)` | Publish structured CloudEvent to NATS |
-| `publishNatsRawEvent(subject, data)` | Publish raw data to NATS |
-| `cloudEvents(options)` | Hono middleware for HTTP ingestion |
-| `clearHandlerCache()` | Reset handler discovery cache |
-
-## Why JetStream?
-
-| Scenario | Core NATS | JetStream |
-|----------|-----------|-----------|
-| Service restarts | ❌ Messages lost | ✅ Messages replayed |
-| Handler crashes | ❌ Message lost | ✅ Auto-retry with backoff |
-| Multiple consumers | ❌ All receive same msg | ✅ Load balanced |
-| Message history | ❌ None | ✅ Configurable retention |
-| Exactly-once | ❌ At-most-once | ✅ With deduplication |
+</details>
+
+---
+
+## API
+
+| Function | Purpose |
+|----------|---------|
+| `handleEvent(options, handler)` | Create a handler |
+| `consumeJetStreamEvents(options)` | Consume with persistence |
+| `consumeNatsEvents(options)` | Consume fire-and-forget |
+| `publish(type, data)` | Publish event |
+
+---
 
 ## License
 

package/dist/src/domain/handler-factory.d.ts

@@ -1,14 +1,32 @@
 import { type ZodTypeAny, z } from 'zod';
 import type { EventContext } from '../adapters/cloudevents';
-import type { HandlerConstructor } from './types';
+import type { HandleEventOptions, HandlerConstructor } from './types';
 /**
  * Creates an event handler using the handleEvent pattern
  * Compatible with the new middleware system
+ *
+ * @example Data-only schema
+ * ```typescript
+ * export default handleEvent({
+ *   type: 'orderboss.orders.created',
+ *   schema: z.object({ orderId: z.string(), total: z.number() }),
+ * }, async (data) => {
+ *   console.log('Order created:', data.orderId)
+ * })
+ * ```
+ *
+ * @example With tenant filtering
+ * ```typescript
+ * export default handleEvent({
+ *   type: 'orderboss.orders.created',
+ *   schema: OrderSchema,
+ *   tenantId: ['tenant-a', 'tenant-b'],
+ * }, async (data, context) => {
+ *   console.log(`Order for tenant ${context?.tenantId}:`, data)
+ * })
+ * ```
  */
-export declare function handleEvent<TSchema extends ZodTypeAny>(schemaOrOptions: TSchema | {
-    schema: TSchema;
-    type?: string;
-}, handler: (payload: TSchema['_output'], context?: EventContext) => Promise<void> | void, eventType?: string): HandlerConstructor;
+export declare function handleEvent<TSchema extends ZodTypeAny>(schemaOrOptions: TSchema | HandleEventOptions<TSchema>, handler: (payload: TSchema['_output'], context?: EventContext) => Promise<void> | void, eventType?: string): HandlerConstructor;
 /**
  * Creates an event schema with type inference
  * Automatically enforces the presence of a 'type' field

package/dist/src/domain/handler-factory.js

@@ -1,28 +1,118 @@
 import { z } from 'zod';
+/**
+ * Extracts type value from Zod v4+ value getter
+ */
+function extractFromValueGetter(typeField) {
+    if ('value' in typeField && typeof typeField.value === 'string') {
+        return typeField.value;
+    }
+    return undefined;
+}
+/**
+ * Extracts type value from Zod _def (v3 and v4)
+ */
+function extractFromTypeDef(typeField) {
+    if (!('_def' in typeField))
+        return undefined;
+    const typeDef = typeField._def;
+    // Try _def.values array (Zod v4)
+    if (Array.isArray(typeDef.values) && typeDef.values.length > 0) {
+        return String(typeDef.values[0]);
+    }
+    // Fallback to _def.value (Zod v3)
+    if (typeof typeDef.value === 'string') {
+        return typeDef.value;
+    }
+    return undefined;
+}
+/**
+ * Extracts event type from a schema's type field
+ */
+function extractFromTypeField(shape) {
+    const typeField = shape.type;
+    if (!typeField || typeof typeField !== 'object' || typeField === null) {
+        return undefined;
+    }
+    const field = typeField;
+    return extractFromValueGetter(field) ?? extractFromTypeDef(field);
+}
 /**
  * Extracts event type from schema
+ * Supports both old Zod (_def.value) and new Zod (_def.values / value getter)
  */
 function extractEventTypeFromSchema(schema) {
-    if ('shape' in schema && schema.shape && typeof schema.shape === 'object') {
-        const shape = schema.shape;
-        if (shape.type && typeof shape.type === 'object' && shape.type !== null && '_def' in shape.type) {
-            const typeDef = shape.type._def;
-            return typeDef?.value;
-        }
+    if (!('shape' in schema) || !schema.shape || typeof schema.shape !== 'object') {
+        return undefined;
     }
-    return undefined;
+    return extractFromTypeField(schema.shape);
+}
+/**
+ * Creates a tenant match function from tenant ID configuration
+ */
+function createTenantMatcher(tenantId) {
+    const tenantIds = Array.isArray(tenantId) ? tenantId : [tenantId];
+    return (event) => {
+        if (!event.tenantId)
+            return false;
+        return tenantIds.includes(event.tenantId);
+    };
+}
+/**
+ * Combines multiple match functions with AND logic
+ */
+function combineMatchers(matchers) {
+    return (event) => matchers.every((matcher) => matcher(event));
 }
 /**
  * Creates an event handler using the handleEvent pattern
  * Compatible with the new middleware system
+ *
+ * @example Data-only schema
+ * ```typescript
+ * export default handleEvent({
+ *   type: 'orderboss.orders.created',
+ *   schema: z.object({ orderId: z.string(), total: z.number() }),
+ * }, async (data) => {
+ *   console.log('Order created:', data.orderId)
+ * })
+ * ```
+ *
+ * @example With tenant filtering
+ * ```typescript
+ * export default handleEvent({
+ *   type: 'orderboss.orders.created',
+ *   schema: OrderSchema,
+ *   tenantId: ['tenant-a', 'tenant-b'],
+ * }, async (data, context) => {
+ *   console.log(`Order for tenant ${context?.tenantId}:`, data)
+ * })
+ * ```
  */
 export function handleEvent(schemaOrOptions, handler, eventType) {
     // Handle both API formats
     let schema;
     let finalEventType = eventType;
+    let matchFn;
+    let safeParse = false;
     if (schemaOrOptions && typeof schemaOrOptions === 'object' && 'schema' in schemaOrOptions) {
-        schema = schemaOrOptions.schema;
-        finalEventType = schemaOrOptions.type || eventType;
+        const options = schemaOrOptions;
+        schema = options.schema;
+        finalEventType = options.type || eventType;
+        safeParse = options.safeParse ?? false;
+        // Build match function from options
+        const matchers = [];
+        if (options.tenantId) {
+            matchers.push(createTenantMatcher(options.tenantId));
+        }
+        if (options.match) {
+            matchers.push(options.match);
+        }
+        if (matchers.length === 1) {
+            matchFn = matchers[0];
+        }
+        else if (matchers.length > 1) {
+            matchFn = combineMatchers(matchers);
+        }
     }
     else {
         schema = schemaOrOptions;
@@ -45,6 +135,8 @@ export function handleEvent(schemaOrOptions, handler, eventType) {
         static __eventarcMetadata = {
             schema,
             declaredType: finalEventType,
+            match: matchFn,
+            safeParse,
         };
         async handle(payload, context) {
             await Promise.resolve(handler(payload, context));

package/dist/src/domain/index.d.ts

@@ -1,5 +1,5 @@
 export { discoverHandlers } from './discovery';
 export { eventSchema, handleEvent } from './handler-factory';
-export type { EnrichedEvent, EventHandler, HandleEventOptions, HandlerConstructor, HandlerMetadata, MatchFn, } from './types';
+export type { EnrichedEvent, EventHandler, HandleEventOptions, HandlerConstructor, HandlerMetadata, IdempotencyStore, InferEventData, MatchFn, RoutingConfig, } from './types';
 export type { HandlerValidationError, ValidationErrorDetail } from './validation';
 export { extractTypeFromSchema, isValidHandler } from './validation';

package/dist/src/domain/types.d.ts

@@ -27,6 +27,8 @@ export type HandlerConstructor<T = unknown> = (new (...args: unknown[]) => Event
  */
 export interface EnrichedEvent<T> extends EventContext {
     data: T;
+    /** Tenant identifier for multi-tenant event routing */
+    tenantId?: string;
 }
 /**
  * Match function type for custom event matching
@@ -49,4 +51,35 @@ export interface HandleEventOptions<S extends ZodTypeAny> {
     type?: string;
     match?: MatchFn<unknown>;
     safeParse?: boolean;
+    /** Filter events by tenant ID(s). If set, only events matching these tenant(s) are processed. */
+    tenantId?: string | string[];
 }
+/**
+ * Routing configuration for type → subject → stream mapping
+ */
+export interface RoutingConfig {
+    /** Map event type prefix to NATS subject prefix, e.g., { 'orderboss.orders': 'orders' } */
+    typeToSubjectMap?: Record<string, string>;
+    /** Map event type prefix to stream name, e.g., { 'orderboss.orders': 'ORDERS' } */
+    typeToStreamMap?: Record<string, string>;
+    /** Default subject prefix when no mapping found */
+    defaultSubjectPrefix?: string;
+}
+/**
+ * Idempotency store interface for deduplication
+ */
+export interface IdempotencyStore {
+    /** Check if a message has already been processed */
+    has(messageId: string): Promise<boolean> | boolean;
+    /** Mark a message as processed */
+    add(messageId: string, ttlMs?: number): Promise<void> | void;
+    /** Clear the store (useful for testing) */
+    clear?(): Promise<void> | void;
+}
+/**
+ * Type helper to extract data type from a Zod schema
+ * Handles both data-only schemas and full CloudEvent schemas with a 'data' field
+ */
+export type InferEventData<S extends ZodTypeAny> = S['_output'] extends {
+    data: infer D;
+} ? D : S['_output'];

package/dist/src/index.d.ts

@@ -1,5 +1,7 @@
 export type { EventContext } from './adapters/cloudevents';
 export { parseEventFromContext } from './adapters/cloudevents';
+export type { EnrichedEvent, IdempotencyStore, InferEventData, RoutingConfig } from './domain';
 export { eventSchema, extractTypeFromSchema, handleEvent } from './domain';
 export { clearHandlerCache, cloudEvents } from './middlewares';
+export { checkAndMarkProcessed, createInMemoryIdempotencyStore, getDefaultIdempotencyStore, resetDefaultIdempotencyStore, } from './processing/idempotency';
 export * from './publishing';

package/dist/src/index.js

@@ -1,4 +1,5 @@
 export { parseEventFromContext } from './adapters/cloudevents';
 export { eventSchema, extractTypeFromSchema, handleEvent } from './domain';
 export { clearHandlerCache, cloudEvents } from './middlewares';
+export { checkAndMarkProcessed, createInMemoryIdempotencyStore, getDefaultIdempotencyStore, resetDefaultIdempotencyStore, } from './processing/idempotency';
 export * from './publishing';

package/dist/src/processing/dlq-safe.d.ts

@@ -2,6 +2,54 @@
  * DLQ-Safe mode utilities
  * Handles quarantine and error publishing for CloudEvents processing
  */
+/**
+ * Reason codes for quarantined messages
+ */
+export type QuarantineReason = 'parse_error' | 'no_handler' | 'validation_error' | 'unhandled_error' | 'processing_error';
+/**
+ * Structure of messages published to the quarantine topic
+ */
+export interface QuarantineMessage {
+    /** Original CloudEvent ID */
+    originalMessageId: string;
+    /** Original CloudEvent type */
+    originalEventType: string;
+    /** Original event data payload */
+    originalEventData: unknown;
+    /** Original event context/metadata */
+    originalEventContext: unknown;
+    /** Full original CloudEvent if available */
+    originalCloudEvent: unknown;
+    /** ISO timestamp when message was quarantined */
+    quarantinedAt: string;
+    /** Reason for quarantine */
+    quarantineReason: QuarantineReason;
+    /** Error message if applicable */
+    error?: string;
+}
+/**
+ * Structure of messages published to the error topic (recoverable errors)
+ */
+export interface ErrorMessage {
+    /** Original CloudEvent ID */
+    originalMessageId: string;
+    /** Original CloudEvent type */
+    originalEventType: string;
+    /** Original event data payload */
+    originalEventData: unknown;
+    /** Original event context/metadata */
+    originalEventContext: unknown;
+    /** Full original CloudEvent if available */
+    originalCloudEvent: unknown;
+    /** ISO timestamp when error occurred */
+    errorTimestamp: string;
+    /** Error details */
+    error: {
+        message: string;
+        stack?: string;
+        type: string;
+    };
+}
 export interface ProcessingContext {
     messageId: string;
     eventType: string;
@@ -23,7 +71,7 @@ export declare const isDlqSafeMode: (options: DlqOptions) => boolean;
 /**
  * Publishes a message to the quarantine topic for "poison messages" that can't be processed
  */
-export declare const quarantineMessage: (processingContext: ProcessingContext, reason: string, options: DlqOptions, error?: unknown) => Promise<void>;
+export declare const quarantineMessage: (processingContext: ProcessingContext, reason: QuarantineReason, options: DlqOptions, error?: unknown) => Promise<void>;
 /**
  * Publishes recoverable processing errors to the error topic
  */

package/dist/src/processing/idempotency.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Idempotency utilities for CloudEvents processing
+ *
+ * Provides deduplication support to ensure handlers process each message exactly once.
+ * Uses CloudEvent ID as the deduplication key.
+ */
+import type { IdempotencyStore } from '../domain/types';
+/**
+ * Options for the in-memory idempotency store
+ */
+export interface InMemoryIdempotencyStoreOptions {
+    /** Maximum number of message IDs to store (LRU eviction). @default 10000 */
+    maxSize?: number;
+    /** Default TTL for entries in milliseconds. @default 86400000 (24 hours) */
+    defaultTtlMs?: number;
+}
+/**
+ * Creates an in-memory idempotency store with LRU eviction and TTL support.
+ *
+ * Suitable for single-instance deployments or development. For production
+ * multi-instance deployments, use a Redis-based store.
+ *
+ * @example
+ * ```typescript
+ * const store = createInMemoryIdempotencyStore({ maxSize: 5000, defaultTtlMs: 3600000 })
+ *
+ * await consumeJetStreamEvents({
+ *   stream: 'ORDERS',
+ *   subjects: ['orders.>'],
+ *   consumer: 'notifications',
+ *   discover: './src/handlers/**\/*.event.ts',
+ *   idempotencyStore: store,
+ * })
+ * ```
+ */
+export declare function createInMemoryIdempotencyStore(options?: InMemoryIdempotencyStoreOptions): IdempotencyStore;
+/**
+ * Gets or creates the default idempotency store
+ */
+export declare function getDefaultIdempotencyStore(): IdempotencyStore;
+/**
+ * Resets the default idempotency store. Useful for testing.
+ */
+export declare function resetDefaultIdempotencyStore(): void;
+/**
+ * Checks if a message should be processed (not a duplicate)
+ * and marks it as processed if so.
+ *
+ * @returns true if the message should be processed, false if it's a duplicate
+ */
+export declare function checkAndMarkProcessed(store: IdempotencyStore, messageId: string, ttlMs?: number): Promise<boolean>;

package/dist/src/processing/idempotency.js

@@ -0,0 +1,112 @@
+/**
+ * Idempotency utilities for CloudEvents processing
+ *
+ * Provides deduplication support to ensure handlers process each message exactly once.
+ * Uses CloudEvent ID as the deduplication key.
+ */
+/**
+ * Creates an in-memory idempotency store with LRU eviction and TTL support.
+ *
+ * Suitable for single-instance deployments or development. For production
+ * multi-instance deployments, use a Redis-based store.
+ *
+ * @example
+ * ```typescript
+ * const store = createInMemoryIdempotencyStore({ maxSize: 5000, defaultTtlMs: 3600000 })
+ *
+ * await consumeJetStreamEvents({
+ *   stream: 'ORDERS',
+ *   subjects: ['orders.>'],
+ *   consumer: 'notifications',
+ *   discover: './src/handlers/**\/*.event.ts',
+ *   idempotencyStore: store,
+ * })
+ * ```
+ */
+export function createInMemoryIdempotencyStore(options = {}) {
+    const { maxSize = 10_000, defaultTtlMs = 24 * 60 * 60 * 1000 } = options;
+    // Use Map for insertion-order iteration (LRU approximation)
+    const cache = new Map();
+    const evictExpired = () => {
+        const now = Date.now();
+        for (const [key, entry] of cache) {
+            if (entry.expiresAt <= now) {
+                cache.delete(key);
+            }
+        }
+    };
+    const evictOldest = (count) => {
+        const keysToDelete = [...cache.keys()].slice(0, count);
+        for (const key of keysToDelete) {
+            cache.delete(key);
+        }
+    };
+    return {
+        has(messageId) {
+            const entry = cache.get(messageId);
+            if (!entry)
+                return false;
+            // Check if expired
+            if (entry.expiresAt <= Date.now()) {
+                cache.delete(messageId);
+                return false;
+            }
+            // Move to end for LRU (re-insert)
+            cache.delete(messageId);
+            cache.set(messageId, entry);
+            return true;
+        },
+        add(messageId, ttlMs) {
+            // Evict expired entries periodically
+            if (cache.size >= maxSize) {
+                evictExpired();
+            }
+            // If still at capacity, evict oldest entries
+            if (cache.size >= maxSize) {
+                const evictCount = Math.max(1, Math.floor(maxSize * 0.1)); // Evict 10%
+                evictOldest(evictCount);
+            }
+            cache.set(messageId, {
+                expiresAt: Date.now() + (ttlMs ?? defaultTtlMs),
+            });
+        },
+        clear() {
+            cache.clear();
+        },
+    };
+}
+/**
+ * Default idempotency store instance.
+ * Used when no custom store is provided to consumers.
+ */
+let defaultStore = null;
+/**
+ * Gets or creates the default idempotency store
+ */
+export function getDefaultIdempotencyStore() {
+    if (!defaultStore) {
+        defaultStore = createInMemoryIdempotencyStore();
+    }
+    return defaultStore;
+}
+/**
+ * Resets the default idempotency store. Useful for testing.
+ */
+export function resetDefaultIdempotencyStore() {
+    defaultStore?.clear?.();
+    defaultStore = null;
+}
+/**
+ * Checks if a message should be processed (not a duplicate)
+ * and marks it as processed if so.
+ *
+ * @returns true if the message should be processed, false if it's a duplicate
+ */
+export async function checkAndMarkProcessed(store, messageId, ttlMs) {
+    const isDuplicate = await store.has(messageId);
+    if (isDuplicate) {
+        return false;
+    }
+    await store.add(messageId, ttlMs);
+    return true;
+}

package/dist/src/processing/index.d.ts

@@ -1,3 +1,4 @@
 export * from './dlq-safe';
 export * from './handler-cache';
+export * from './idempotency';
 export * from './validation';

package/dist/src/processing/index.js

@@ -1,3 +1,4 @@
 export * from './dlq-safe';
 export * from './handler-cache';
+export * from './idempotency';
 export * from './validation';

package/dist/src/publishing/nats.publisher.d.ts

@@ -1,4 +1,5 @@
 import type { ZodTypeAny } from 'zod';
+import { type RoutingConfig } from '../domain';
 export interface PublishNatsEventOptions {
     /**
      * NATS URL(s), e.g., "nats://localhost:4222".
@@ -13,9 +14,45 @@ export interface PublishNatsEventOptions {
      * Optional CloudEvent subject (e.g., an order ID). Not to be confused with the NATS subject.
      */
     subject?: string;
+    /**
+     * Tenant identifier for multi-tenant event routing.
+     * Will be added as a CloudEvent extension attribute.
+     */
+    tenantId?: string;
 }
+/**
+ * Derives a NATS subject from a CloudEvent type using routing configuration.
+ *
+ * @example
+ * ```typescript
+ * const config: RoutingConfig = {
+ *   typeToSubjectMap: { 'orderboss.orders': 'orders' },
+ *   defaultSubjectPrefix: 'events',
+ * }
+ *
+ * deriveSubjectFromType('orderboss.orders.created', config)
+ * // Returns: 'orders.created'
+ *
+ * deriveSubjectFromType('unknown.event.type', config)
+ * // Returns: 'events.unknown.event.type'
+ * ```
+ */
+export declare function deriveSubjectFromType(eventType: string, config?: RoutingConfig): string;
+/**
+ * Derives a JetStream stream name from a CloudEvent type using routing configuration.
+ */
+export declare function deriveStreamFromType(eventType: string, config?: RoutingConfig): string | undefined;
 export declare function publishNatsEvent<T extends ZodTypeAny>(subjectName: string, schema: T, eventData: unknown, options?: PublishNatsEventOptions): Promise<string>;
 export declare function publishNatsRawEvent(subjectName: string, eventType: string, eventData: unknown, options?: PublishNatsEventOptions): Promise<string>;
+/**
+ * Simplified publish function where subject equals event type.
+ *
+ * @example
+ * ```typescript
+ * await publish('orders.created', { orderId: '123', total: 99.99 })
+ * ```
+ */
+export declare function publish(eventType: string, eventData: unknown, options?: PublishNatsEventOptions): Promise<string>;
 /**
  * @internal Resets the cached NATS connection. Intended for testing only.
  */

package/dist/src/publishing/nats.publisher.js

@@ -2,6 +2,57 @@ import { connect, StringCodec } from 'nats';
 import { extractTypeFromSchema } from '../domain';
 import { createValidationError, logger } from '../infrastructure';
 const sc = StringCodec();
+/**
+ * Derives a NATS subject from a CloudEvent type using routing configuration.
+ *
+ * @example
+ * ```typescript
+ * const config: RoutingConfig = {
+ *   typeToSubjectMap: { 'orderboss.orders': 'orders' },
+ *   defaultSubjectPrefix: 'events',
+ * }
+ *
+ * deriveSubjectFromType('orderboss.orders.created', config)
+ * // Returns: 'orders.created'
+ *
+ * deriveSubjectFromType('unknown.event.type', config)
+ * // Returns: 'events.unknown.event.type'
+ * ```
+ */
+export function deriveSubjectFromType(eventType, config) {
+    if (!config?.typeToSubjectMap) {
+        // No mapping configured, use type as-is (replace dots with dots is a no-op)
+        return config?.defaultSubjectPrefix ? `${config.defaultSubjectPrefix}.${eventType}` : eventType;
+    }
+    // Find the longest matching prefix
+    const sortedPrefixes = Object.keys(config.typeToSubjectMap).sort((a, b) => b.length - a.length);
+    for (const prefix of sortedPrefixes) {
+        if (eventType.startsWith(prefix)) {
+            const suffix = eventType.slice(prefix.length);
+            const mappedPrefix = config.typeToSubjectMap[prefix];
+            // Remove leading dot from suffix if present
+            const cleanSuffix = suffix.startsWith('.') ? suffix.slice(1) : suffix;
+            return cleanSuffix ? `${mappedPrefix}.${cleanSuffix}` : mappedPrefix;
+        }
+    }
+    // No match found, use default prefix or type as-is
+    return config.defaultSubjectPrefix ? `${config.defaultSubjectPrefix}.${eventType}` : eventType;
+}
+/**
+ * Derives a JetStream stream name from a CloudEvent type using routing configuration.
+ */
+export function deriveStreamFromType(eventType, config) {
+    if (!config?.typeToStreamMap)
+        return undefined;
+    // Find the longest matching prefix
+    const sortedPrefixes = Object.keys(config.typeToStreamMap).sort((a, b) => b.length - a.length);
+    for (const prefix of sortedPrefixes) {
+        if (eventType.startsWith(prefix)) {
+            return config.typeToStreamMap[prefix];
+        }
+    }
+    return undefined;
+}
 let natsConnectionPromise = null;
 async function getNatsConnection(servers) {
     if (!natsConnectionPromise) {
@@ -51,6 +102,7 @@ export async function publishNatsRawEvent(subjectName, eventType, eventData, opt
         datacontenttype: 'application/json',
         data: eventData,
         ...(options?.subject && { subject: options.subject }),
+        ...(options?.tenantId && { tenantid: options.tenantId }), // CloudEvents extension (lowercase)
     };
     const data = JSON.stringify(cloudEvent);
     const nc = await getNatsConnection(options?.servers);
@@ -58,6 +110,17 @@ export async function publishNatsRawEvent(subjectName, eventType, eventData, opt
     logger.debug(`Published CloudEvent ${eventType} to NATS subject ${subjectName} (id=${cloudEvent.id})`);
     return cloudEvent.id;
 }
+/**
+ * Simplified publish function where subject equals event type.
+ *
+ * @example
+ * ```typescript
+ * await publish('orders.created', { orderId: '123', total: 99.99 })
+ * ```
+ */
+export async function publish(eventType, eventData, options) {
+    return publishNatsRawEvent(eventType, eventType, eventData, options);
+}
 /**
  * @internal Resets the cached NATS connection. Intended for testing only.
  */

package/dist/src/transports/nats/base-message-processor.js

@@ -4,6 +4,14 @@
  */
 import { createProcessingContext, publishRecoverableError, quarantineMessage, } from '../../processing/dlq-safe';
 import { throwValidationError, validateEventData } from '../../processing/validation';
+/**
+ * Extracts tenantId from CloudEvent extensions
+ * Supports both 'tenantid' (CloudEvents spec lowercase) and 'tenantId' variants
+ */
+function extractTenantId(ce) {
+    const extensions = ce;
+    return (extensions.tenantid ?? extensions.tenantId ?? extensions.tenant_id);
+}
 /**
  * Creates shared message processing utilities
  */
@@ -16,6 +24,7 @@ export function createBaseMessageProcessor(deps) {
         time: ce.time ?? new Date().toISOString(),
         messageId: ce.id,
         data: ce.data,
+        tenantId: extractTenantId(ce),
     });
     const createContext = (event, ce) => createProcessingContext(event.eventType, event.data, event, ce);
     const parseCloudEvent = (data) => {

package/dist/src/transports/nats/jetstream-consumer.d.ts

@@ -1,4 +1,5 @@
 import { type ConsumerMessages } from 'nats';
+import { type IdempotencyStore } from '../../domain';
 import type { CloudEventsOptions } from '../../middlewares/cloudevents-middleware';
 /**
  * Stream configuration options
@@ -52,6 +53,16 @@ export interface JetStreamConsumerOptions extends Pick<CloudEventsOptions, 'quar
     maxDeliver?: number;
     /** Stream configuration (only used when auto-creating) */
     streamConfig?: StreamConfig;
+    /**
+     * Idempotency store for deduplication. Defaults to in-memory store.
+     * Pass `false` to disable idempotency checks entirely.
+     */
+    idempotencyStore?: IdempotencyStore | false;
+    /**
+     * TTL for idempotency records in milliseconds.
+     * @default 86400000 (24 hours)
+     */
+    idempotencyTtl?: number;
 }
 /**
  * Consume CloudEvents from NATS JetStream with persistence and guaranteed delivery.

package/dist/src/transports/nats/jetstream-consumer.js

@@ -2,6 +2,7 @@ import { AckPolicy, connect, DeliverPolicy, ReplayPolicy, RetentionPolicy, Stora
 import { discoverHandlers } from '../../domain';
 import { logger } from '../../infrastructure/logging';
 import { processHandler } from '../../processing/handler-cache';
+import { checkAndMarkProcessed, getDefaultIdempotencyStore } from '../../processing/idempotency';
 import { createJetStreamMessageProcessor } from './jetstream-message-processor';
 const sc = StringCodec();
 // Use globalThis to persist across hot-reloads
@@ -155,6 +156,9 @@ export async function consumeJetStreamEvents(options) {
     const abortController = new AbortController();
     getJetStreamRegistry().set(name, { messages, connection: nc, abortController });
     const dlqEnabled = Boolean(options.quarantineTopic || options.errorTopic);
+    // Setup idempotency store
+    const idempotencyStore = options.idempotencyStore === false ? null : (options.idempotencyStore ?? getDefaultIdempotencyStore());
+    const idempotencyTtl = options.idempotencyTtl;
     const { handleMessage, handleUnhandledProcessingError } = createJetStreamMessageProcessor({
         name,
         dlqEnabled,
@@ -163,25 +167,42 @@ export async function consumeJetStreamEvents(options) {
         decode: (data) => sc.decode(data),
         logger,
     });
+    // Check idempotency and skip duplicates
+    const checkIdempotency = async (msg) => {
+        if (!idempotencyStore)
+            return true;
+        const messageId = `${msg.info.stream}:${msg.seq}`;
+        const shouldProcess = await checkAndMarkProcessed(idempotencyStore, messageId, idempotencyTtl);
+        if (!shouldProcess) {
+            logger.debug(`[${name}] skipping duplicate message: ${messageId}`);
+            msg.ack();
+        }
+        return shouldProcess;
+    };
+    // Process a single message
+    const processSingleMessage = async (msg) => {
+        const shouldProcess = await checkIdempotency(msg);
+        if (!shouldProcess)
+            return;
+        try {
+            const success = await handleMessage(msg);
+            if (success) {
+                msg.ack();
+            }
+            else {
+                msg.nak();
+            }
+        }
+        catch (error) {
+            await handleUnhandledProcessingError(msg, error);
+        }
+    };
     // Process messages
     const processMessages = async () => {
         for await (const msg of messages) {
             if (abortController.signal.aborted)
                 break;
-            try {
-                const success = await handleMessage(msg);
-                if (success) {
-                    msg.ack();
-                }
-                else {
-                    // Handler returned false, negative ack for retry
-                    msg.nak();
-                }
-            }
-            catch (error) {
-                await handleUnhandledProcessingError(msg, error);
-                // Don't ack - message will be redelivered after ack_wait
-            }
+            await processSingleMessage(msg);
         }
     };
     processMessages().catch((err) => {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.1.13",
-  "description": "CloudEvents toolkit for TypeScript - handler discovery, DLQ-safe processing, NATS streaming",
+  "version": "0.2.1",
+  "description": "CloudEvents toolkit for TypeScript - Zod validation, handler discovery, NATS JetStream",
   "author": "crossdelta",
   "license": "MIT",
   "keywords": [
     "cloudevents",
     "nats",
+    "zod",
     "pubsub",
     "event-driven",
     "typescript",