@crossdelta/cloudevents 0.5.1 → 0.5.3

package/README.md

@@ -29,7 +29,11 @@ bun add @crossdelta/cloudevents zod@4
 
 ## Quick Start
 
-**1. Create an event handler** (`src/events/orders-created.event.ts`):
+> **Note:** Services **never create streams**. Streams must exist before services consume from them:
+> - **Development**: Use [NATS CLI](https://docs.nats.io/running-a-nats-service/nats_admin/jetstream_admin/streams) or [Platform SDK](https://www.npmjs.com/package/@crossdelta/platform-sdk) (`pf dev` auto-creates from contracts)
+> - **Production**: Use infrastructure-as-code (Pulumi, Terraform) or the [Stream Setup](#stream-setup) function below
+
+**1. Create an event handler** (`src/events/orders-created.handler.ts`):
 
 ```typescript
 import { handleEvent } from '@crossdelta/cloudevents'
@@ -55,17 +59,7 @@ export default handleEvent(
 )
 ```
 
-**2. Ensure stream exists** (once, during setup):
-
-```typescript
-import { ensureJetStreams } from '@crossdelta/cloudevents'
-
-await ensureJetStreams({
-  streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }],
-})
-```
-
-**3. Start consuming:**
+**2. Start consuming:**
 
 ```typescript
 import { consumeJetStreams } from '@crossdelta/cloudevents'
@@ -73,11 +67,11 @@ import { consumeJetStreams } from '@crossdelta/cloudevents'
 consumeJetStreams({
   streams: ['ORDERS'],
   consumer: 'my-service',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
 })
 ```
 
-**4. Publish from another service:**
+**3. Publish from another service:**
 
 ```typescript
 import { publish } from '@crossdelta/cloudevents'
@@ -87,6 +81,10 @@ await publish('orders.created', { orderId: 'ord_123', total: 99.99 })
 
 That's it. Handlers are auto-discovered, validated with Zod, and messages persist in JetStream.
 
+> **Stream creation** is handled by your development environment or infrastructure — not by services:
+> - Development: [NATS CLI](https://docs.nats.io/running-a-nats-service/nats_admin/jetstream_admin/streams), [@crossdelta/platform-sdk](https://www.npmjs.com/package/@crossdelta/platform-sdk), or manual setup
+> - Production: See [Stream Setup](#stream-setup) below for `ensureJetStreams()` usage in infrastructure code
+
 ---
 
 ## Why use this?
@@ -125,10 +123,10 @@ export default handleEvent(
 
 ### Handlers
 
-Drop a `*.event.ts` file anywhere — it's auto-registered:
+Drop a `*.handler.ts` file anywhere — it's auto-registered:
 
 ```typescript
-// src/events/user-signup.event.ts
+// src/events/user-signup.handler.ts
 import { z } from 'zod'
 
 const UserSignupSchema = z.object({ 
@@ -158,7 +156,9 @@ await publish('orders.created', orderData)
 
 ### Stream Setup
 
-Create the stream once during infrastructure setup:
+> **For infrastructure use only** - Services should never call this function.
+
+Create streams during infrastructure setup (Pulumi, deployment scripts):
 
 ```typescript
 import { ensureJetStreams } from '@crossdelta/cloudevents'
@@ -175,6 +175,7 @@ await ensureJetStreams({
     },
   ],
 })
+})
 ```
 
 ### Consuming
@@ -186,13 +187,13 @@ import { consumeJetStreams } from '@crossdelta/cloudevents'
 consumeJetStreams({
   streams: ['ORDERS'],
   consumer: 'billing',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
 })
 
 // Core NATS — fire-and-forget, simpler
 await consumeNatsEvents({
   subjects: ['notifications.*'],
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
 })
 ```
 
@@ -239,7 +240,7 @@ consumeJetStreams({
   // Required
   streams: ['ORDERS'],
   consumer: 'my-service',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
 
   // Optional
   servers: 'nats://localhost:4222',
@@ -254,6 +255,129 @@ consumeJetStreams({
 
 ## Advanced Features
 
+<details>
+<parameter name="summary"><b>Channel Metadata (Infrastructure Integration)</b></summary>
+
+<br />
+
+Contracts can include **channel metadata** to define which NATS JetStream stream they belong to. This enables infrastructure-as-code workflows where streams are materialized from contracts.
+
+### Basic Contract with Channel
+
+```typescript
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  channel: {
+    stream: 'ORDERS',
+    // subject defaults to 'orders.created' if omitted
+  },
+  schema: z.object({
+    orderId: z.string(),
+    total: z.number(),
+  }),
+})
+```
+
+### Channel Configuration
+
+```typescript
+interface ChannelConfig {
+  stream: string    // JetStream stream name (e.g., 'ORDERS')
+  subject?: string  // NATS subject (defaults to event type)
+}
+```
+
+**Subject Defaulting:**
+- If `subject` is **not provided**, it defaults to the event `type`
+- This follows the convention: `orders.created` → subject `orders.created`
+- Override when needed: `subject: 'orders.v1.created'`
+
+### Multiple Events, Same Stream
+
+```typescript
+// orders.created → ORDERS stream
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  channel: { stream: 'ORDERS' },
+  schema: OrderCreatedSchema,
+})
+
+// orders.updated → ORDERS stream (same stream!)
+export const OrdersUpdatedContract = createContract({
+  type: 'orders.updated',
+  channel: { stream: 'ORDERS' },
+  schema: OrderUpdatedSchema,
+})
+```
+
+**Result:** Both events share the `ORDERS` stream with subjects `orders.created` and `orders.updated`.
+
+### Infrastructure Materialization
+
+Channel metadata is **conceptual** - it defines routing, not infrastructure policy.
+
+**Contracts define:**
+- Event type (`orders.created`)
+- Stream routing (`ORDERS`)
+- Subject mapping (`orders.created`)
+
+**Infrastructure defines:**
+- Retention (7 days, 14 days, etc.)
+- Storage (disk, memory)
+- Replicas (1, 3, etc.)
+- Limits (max message size, etc.)
+
+**Example Infrastructure (Pulumi):**
+
+```typescript
+import { collectStreamDefinitions } from './helpers/streams'
+import { ensureJetStreams } from '@crossdelta/cloudevents'
+
+// Collect from contracts
+const streams = collectStreamDefinitions()
+// [{ stream: 'ORDERS', subjects: ['orders.created', 'orders.updated'] }]
+
+// Materialize with policies
+await ensureJetStreams({
+  streams: streams.map(({ stream, subjects }) => ({
+    stream,
+    subjects,
+    config: {
+      maxAge: 14 * 24 * 60 * 60 * 1000, // 14 days
+      replicas: 3,                       // High availability
+      storage: 'file',                   // Persistent
+    },
+  })),
+})
+```
+
+### Development vs. Production
+
+| Environment | Streams | How | Retention |
+|-------------|---------|-----|-----------|
+| **Development** | Ephemeral | Auto-created by services | None (memory) |
+| **Production** | Persistent | Materialized via infrastructure | Explicit (7d, 14d, etc.) |
+
+**Key Principle:** Contracts define **what** and **where**, infrastructure defines **how** and **how long**.
+
+### Backward Compatibility
+
+Channel metadata is **optional** - contracts without `channel` work as before:
+
+```typescript
+// Legacy contract (still works)
+export const LegacyContract = createContract({
+  type: 'legacy.event',
+  schema: LegacySchema,
+  // No channel - handler still works
+})
+```
+
+</details>
+
 <details>
 <summary><b>Shared Contracts</b></summary>
 
@@ -340,8 +464,10 @@ const redisStore = {
   add: (id, ttl) => redis.set(`idem:${id}`, '1', 'PX', ttl),
 }
 
-await consumeJetStreamEvents({
-  // ...
+await consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
   idempotencyStore: redisStore,
 })
 ```
@@ -354,13 +480,17 @@ await consumeJetStreamEvents({
 Invalid messages are quarantined, not lost:
 
 ```typescript
-await consumeJetStreamEvents({
-  // ...
-  quarantineTopic: 'events.quarantine',
-  errorTopic: 'events.errors',
+await consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.handler.ts',
+  quarantineTopic: 'events.quarantine',  // For malformed messages
+  errorTopic: 'events.errors',            // For handler errors
 })
 ```
 
+Messages that fail validation go to `quarantineTopic`, messages that crash handlers go to `errorTopic`.
+
 </details>
 
 <details>
@@ -371,7 +501,7 @@ import { Hono } from 'hono'
 import { cloudEvents } from '@crossdelta/cloudevents'
 
 const app = new Hono()
-app.use('/events', cloudEvents({ discover: 'src/events/**/*.event.ts' }))
+app.use('/events', cloudEvents({ discover: 'src/events/**/*.handler.ts' }))
 ```
 
 </details>
@@ -384,9 +514,8 @@ app.use('/events', cloudEvents({ discover: 'src/events/**/*.event.ts' }))
 |----------|---------|
 | `handleEvent(options, handler)` | Create a handler |
 | `createContract(options)` | Create shared event contract |
-| `ensureJetStreams(options)` | Create/update JetStream streams (preferred) |
-| `consumeJetStreams(options)` | Consume from multiple streams (preferred) |
-| `consumeJetStreamEvents(options)` | Consume single stream (legacy) |
+| `ensureJetStreams(options)` | Create/update JetStream streams |
+| `consumeJetStreams(options)` | Consume from multiple streams |
 | `consumeNatsEvents(options)` | Consume fire-and-forget |
 | `publish(type, data)` | Publish event |
 

package/dist/domain/contract-helper.d.ts

@@ -1,26 +1,50 @@
 import type { ZodTypeAny } from 'zod';
-import type { HandleEventOptions } from './types';
+import type { ChannelMetadata, HandleEventOptions } from './types';
 /**
- * Creates a type-safe event contract for Advanced Mode
+ * Creates a type-safe event contract with optional channel metadata
  *
  * This helper ensures proper type inference when using contracts
  * with handleEvent across package boundaries.
  *
  * @example
+ * Basic contract without channel:
  * ```typescript
- * import { createContract } from '@crossdelta/cloudevents'
- * import { z } from 'zod'
+ * export const OrderCreatedContract = createContract({
+ *   type: 'orders.created',
+ *   schema: z.object({
+ *     orderId: z.string(),
+ *     total: z.number(),
+ *   }),
+ * })
+ * ```
  *
+ * @example
+ * Contract with channel metadata:
+ * ```typescript
  * export const OrderCreatedContract = createContract({
  *   type: 'orders.created',
+ *   channel: {
+ *     stream: 'ORDERS',
+ *     // subject defaults to 'orders.created' if omitted
+ *   },
  *   schema: z.object({
  *     orderId: z.string(),
  *     total: z.number(),
  *   }),
  * })
+ * ```
  *
- * // Type is inferred: { orderId: string, total: number }
- * export type OrderCreatedData = typeof OrderCreatedContract._schema._output
+ * @example
+ * Contract with explicit subject:
+ * ```typescript
+ * export const OrderCreatedContract = createContract({
+ *   type: 'orders.created',
+ *   channel: {
+ *     stream: 'ORDERS',
+ *     subject: 'orders.v1.created', // Override default
+ *   },
+ *   schema: OrderSchema,
+ * })
  * ```
  */
 export declare function createContract<TSchema extends ZodTypeAny>(options: {
@@ -29,6 +53,11 @@ export declare function createContract<TSchema extends ZodTypeAny>(options: {
     match?: HandleEventOptions['match'];
     safeParse?: boolean;
     tenantId?: string | string[];
+    channel?: {
+        stream: string;
+        subject?: string;
+    };
 }): HandleEventOptions<TSchema> & {
     _schema: TSchema;
+    channel?: ChannelMetadata;
 };

package/dist/domain/contract-helper.js

@@ -1,29 +1,61 @@
 /**
- * Creates a type-safe event contract for Advanced Mode
+ * Creates a type-safe event contract with optional channel metadata
  *
  * This helper ensures proper type inference when using contracts
  * with handleEvent across package boundaries.
  *
  * @example
+ * Basic contract without channel:
  * ```typescript
- * import { createContract } from '@crossdelta/cloudevents'
- * import { z } from 'zod'
+ * export const OrderCreatedContract = createContract({
+ *   type: 'orders.created',
+ *   schema: z.object({
+ *     orderId: z.string(),
+ *     total: z.number(),
+ *   }),
+ * })
+ * ```
  *
+ * @example
+ * Contract with channel metadata:
+ * ```typescript
  * export const OrderCreatedContract = createContract({
  *   type: 'orders.created',
+ *   channel: {
+ *     stream: 'ORDERS',
+ *     // subject defaults to 'orders.created' if omitted
+ *   },
  *   schema: z.object({
  *     orderId: z.string(),
  *     total: z.number(),
  *   }),
  * })
+ * ```
  *
- * // Type is inferred: { orderId: string, total: number }
- * export type OrderCreatedData = typeof OrderCreatedContract._schema._output
+ * @example
+ * Contract with explicit subject:
+ * ```typescript
+ * export const OrderCreatedContract = createContract({
+ *   type: 'orders.created',
+ *   channel: {
+ *     stream: 'ORDERS',
+ *     subject: 'orders.v1.created', // Override default
+ *   },
+ *   schema: OrderSchema,
+ * })
  * ```
  */
 export function createContract(options) {
+    // Resolve channel metadata: default subject to type if not provided
+    const resolvedChannel = options.channel
+        ? {
+            stream: options.channel.stream,
+            subject: options.channel.subject ?? options.type,
+        }
+        : undefined;
     return {
         ...options,
         _schema: options.schema,
+        channel: resolvedChannel,
     };
 }

package/dist/domain/discovery.d.ts

@@ -2,17 +2,17 @@ import type { HandlerConstructor } from './types';
 /**
  * Discovers event handlers from files matching the given glob pattern.
  *
- * @param pattern - Glob pattern to match handler files (e.g., 'events/*.event.ts')
+ * @param pattern - Glob pattern to match handler files (e.g., 'events/*.handler.ts')
  * @param options - Configuration options
  * @returns Promise resolving to array of discovered handler constructors
  *
  * @example
  * ```typescript
  * // Discover all handlers in events directory
- * const handlers = await discoverHandlers('events/*.event.ts')
+ * const handlers = await discoverHandlers('events/*.handler.ts')
  *
  * // With filtering and logging
- * const handlers = await discoverHandlers('events/*.event.ts', {
+ * const handlers = await discoverHandlers('events/*.handler.ts', {
  *   filter: (name, handler) => name.includes('Customer'),
  *   log: true
  * })

package/dist/domain/discovery.js

@@ -144,17 +144,17 @@ const discoverFiles = async (pattern, basePath, preferCompiled) => {
 /**
  * Discovers event handlers from files matching the given glob pattern.
  *
- * @param pattern - Glob pattern to match handler files (e.g., 'events/*.event.ts')
+ * @param pattern - Glob pattern to match handler files (e.g., 'events/*.handler.ts')
  * @param options - Configuration options
  * @returns Promise resolving to array of discovered handler constructors
  *
  * @example
  * ```typescript
  * // Discover all handlers in events directory
- * const handlers = await discoverHandlers('events/*.event.ts')
+ * const handlers = await discoverHandlers('events/*.handler.ts')
  *
  * // With filtering and logging
- * const handlers = await discoverHandlers('events/*.event.ts', {
+ * const handlers = await discoverHandlers('events/*.handler.ts', {
  *   filter: (name, handler) => name.includes('Customer'),
  *   log: true
  * })

package/dist/domain/index.d.ts

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

package/dist/domain/index.js

@@ -1,4 +1,4 @@
-export { discoverHandlers } from './discovery';
 export { createContract } from './contract-helper';
+export { discoverHandlers } from './discovery';
 export { eventSchema, handleEvent } from './handler-factory';
 export { extractTypeFromSchema, isValidHandler } from './validation';

package/dist/domain/types.d.ts

@@ -43,6 +43,24 @@ export type HandlerMetadata<S extends ZodTypeAny> = {
     match?: MatchFn<unknown>;
     safeParse: boolean;
 };
+/**
+ * Channel metadata for NATS JetStream routing
+ */
+export interface ChannelMetadata {
+    /** JetStream stream name (e.g., 'ORDERS') */
+    stream: string;
+    /** NATS subject (defaults to event type if not specified) */
+    subject: string;
+}
+/**
+ * Channel configuration input (subject is optional, defaults to type)
+ */
+export interface ChannelConfig {
+    /** JetStream stream name (e.g., 'ORDERS') */
+    stream: string;
+    /** NATS subject (optional, defaults to event type) */
+    subject?: string;
+}
 /**
  * Options for creating event handlers
  *
@@ -56,6 +74,8 @@ export interface HandleEventOptions<S = ZodTypeAny> {
     safeParse?: boolean;
     /** Filter events by tenant ID(s). If set, only events matching these tenant(s) are processed. */
     tenantId?: string | string[];
+    /** Channel metadata for NATS JetStream routing (optional) */
+    channel?: ChannelConfig;
 }
 /**
  * Routing configuration for type → subject → stream mapping

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { EventContext } from './adapters/cloudevents';
 export { parseEventFromContext } from './adapters/cloudevents';
-export type { EnrichedEvent, HandleEventOptions, IdempotencyStore, InferEventData, RoutingConfig } from './domain';
+export type { ChannelConfig, ChannelMetadata, EnrichedEvent, HandleEventOptions, IdempotencyStore, InferEventData, RoutingConfig, } from './domain';
 export { createContract, eventSchema, extractTypeFromSchema, handleEvent } from './domain';
 export { clearHandlerCache, cloudEvents } from './middlewares';
 export { checkAndMarkProcessed, createInMemoryIdempotencyStore, getDefaultIdempotencyStore, resetDefaultIdempotencyStore, } from './processing/idempotency';

package/dist/processing/idempotency.d.ts

@@ -28,7 +28,7 @@ export interface InMemoryIdempotencyStoreOptions {
  *   stream: 'ORDERS',
  *   subjects: ['orders.>'],
  *   consumer: 'notifications',
- *   discover: './src/handlers/**\/*.event.ts',
+ *   discover: `./src/events/**\/*.handler.ts`,
  *   idempotencyStore: store,
  * })
  * ```

package/dist/processing/idempotency.js

@@ -18,7 +18,7 @@
  *   stream: 'ORDERS',
  *   subjects: ['orders.>'],
  *   consumer: 'notifications',
- *   discover: './src/handlers/**\/*.event.ts',
+ *   discover: `./src/events/**\/*.handler.ts`,
  *   idempotencyStore: store,
  * })
  * ```

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

@@ -157,7 +157,7 @@ export declare function ensureJetStreamStreams(options: JetStreamStreamsOptions)
  *   stream: 'ORDERS',
  *   subjects: ['orders.>'],
  *   consumer: 'notifications',
- *   discover: './src/handlers/**\/*.event.ts',
+ *   discover: `./src/events/**\/*.handler.ts`,
  * })
  * ```
  */
@@ -200,7 +200,7 @@ export interface JetStreamStreamsConsumerOptions extends Pick<CloudEventsOptions
  * await consumeJetStreamStreams({
  *   streams: ['ORDERS', 'CUSTOMERS'],
  *   consumer: 'notifications',
- *   discover: './src/events/**\/*.event.ts',
+ *   discover: `./src/events/**\/*.handler.ts`,
  * })
  * ```
  */

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

@@ -167,7 +167,7 @@ async function ensureConsumer(jsm, streamName, consumerName, options) {
  *   stream: 'ORDERS',
  *   subjects: ['orders.>'],
  *   consumer: 'notifications',
- *   discover: './src/handlers/**\/*.event.ts',
+ *   discover: `./src/events/**\/*.handler.ts`,
  * })
  * ```
  */
@@ -264,7 +264,7 @@ export async function consumeJetStreamEvents(options) {
  * await consumeJetStreamStreams({
  *   streams: ['ORDERS', 'CUSTOMERS'],
  *   consumer: 'notifications',
- *   discover: './src/events/**\/*.event.ts',
+ *   discover: `./src/events/**\/*.handler.ts`,
  * })
  * ```
  */

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

@@ -44,7 +44,7 @@ export async function consumeNatsEvents(options) {
     const pass = options.pass ?? process.env.NATS_PASSWORD;
     // Cleanup existing consumer with same name (handles hot-reload)
     await cleanupConsumer(name);
-    // 1) Discover handler classes from *.event.ts files
+    // 1) Discover handler classes from *.handler.ts files
     const handlerConstructors = await discoverHandlers(options.discover);
     const processedHandlers = handlerConstructors
         .map(processHandler)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "CloudEvents toolkit for TypeScript - Zod validation, handler discovery, NATS JetStream",
   "author": "crossdelta",
   "license": "MIT",
@@ -23,15 +23,15 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.js",
-      "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./transports/nats": {
+      "types": "./dist/src/transports/nats/index.d.ts",
       "import": "./dist/src/transports/nats/index.js",
       "require": "./dist/src/transports/nats/index.js",
-      "types": "./dist/src/transports/nats/index.d.ts",
       "default": "./dist/src/transports/nats/index.js"
     }
   },