@crossdelta/cloudevents 0.5.2 → 0.5.4

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>
 
@@ -343,7 +467,7 @@ const redisStore = {
 await consumeJetStreams({
   streams: ['ORDERS'],
   consumer: 'my-service',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
   idempotencyStore: redisStore,
 })
 ```
@@ -359,7 +483,7 @@ Invalid messages are quarantined, not lost:
 await consumeJetStreams({
   streams: ['ORDERS'],
   consumer: 'my-service',
-  discover: './src/events/**/*.event.ts',
+  discover: './src/events/**/*.handler.ts',
   quarantineTopic: 'events.quarantine',  // For malformed messages
   errorTopic: 'events.errors',            // For handler errors
 })
@@ -377,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>
@@ -390,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/publishing/nats.publisher.d.ts

@@ -1,59 +1,19 @@
 import type { ZodTypeAny } from 'zod';
 import { type RoutingConfig } from '../domain';
 export interface PublishNatsEventOptions {
-    /**
-     * NATS URL(s), e.g., "nats://localhost:4222".
-     * Defaults to `process.env.NATS_URL` or `nats://localhost:4222`.
-     */
     servers?: string;
-    /**
-     * CloudEvent source identifier (e.g., "orderboss://orders-service").
-     */
     source?: string;
-    /**
-     * 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.
- */
-export declare function __resetNatsPublisher(): void;
+export declare const deriveSubjectFromType: (eventType: string, config?: RoutingConfig) => string;
+export declare const deriveStreamFromType: (eventType: string, config?: RoutingConfig) => string | undefined;
+export declare const publishNatsRawEvent: (subjectName: string, eventType: string, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
+export declare const publishNatsEvent: <T extends ZodTypeAny>(subjectName: string, schema: T, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
+export declare const publish: (eventTypeOrContract: string | {
+    type: string;
+    channel?: {
+        subject?: string;
+    };
+}, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
+export declare const __resetNatsPublisher: () => void;

package/dist/publishing/nats.publisher.js

@@ -2,49 +2,59 @@ 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) {
+let natsConnectionPromise = null;
+const pluralize = (word) => {
+    if (word.endsWith('y') && !['a', 'e', 'i', 'o', 'u'].includes(word[word.length - 2])) {
+        return `${word.slice(0, -1)}ies`;
+    }
+    if (word.endsWith('s') || word.endsWith('sh') || word.endsWith('ch') || word.endsWith('x')) {
+        return `${word}es`;
+    }
+    return `${word}s`;
+};
+const deriveSubjectFromEventType = (eventType) => {
+    const parts = eventType.split('.');
+    if (parts.length < 2)
+        return eventType;
+    const domain = parts[0];
+    const action = parts.slice(1).join('.');
+    const pluralDomain = pluralize(domain);
+    return `${pluralDomain}.${action}`;
+};
+const getNatsConnection = async (servers) => {
+    if (!natsConnectionPromise) {
+        const url = servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
+        natsConnectionPromise = connect({ servers: url })
+            .then((connection) => {
+            logger.debug(`[NATS] connected to ${url}`);
+            return connection;
+        })
+            .catch((error) => {
+            logger.error('[NATS] connection error', error);
+            natsConnectionPromise = null;
+            throw error;
+        });
+    }
+    return natsConnectionPromise;
+};
+export const 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) {
+};
+export const 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)) {
@@ -52,25 +62,26 @@ export function deriveStreamFromType(eventType, config) {
         }
     }
     return undefined;
-}
-let natsConnectionPromise = null;
-async function getNatsConnection(servers) {
-    if (!natsConnectionPromise) {
-        const url = servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
-        natsConnectionPromise = connect({ servers: url })
-            .then((connection) => {
-            logger.debug(`[NATS] connected to ${url}`);
-            return connection;
-        })
-            .catch((error) => {
-            logger.error('[NATS] connection error', error);
-            natsConnectionPromise = null;
-            throw error;
-        });
-    }
-    return natsConnectionPromise;
-}
-export async function publishNatsEvent(subjectName, schema, eventData, options) {
+};
+export const publishNatsRawEvent = async (subjectName, eventType, eventData, options) => {
+    const cloudEvent = {
+        specversion: '1.0',
+        type: eventType,
+        source: options?.source || 'hono-service',
+        id: crypto.randomUUID(),
+        time: new Date().toISOString(),
+        datacontenttype: 'application/json',
+        data: eventData,
+        ...(options?.subject && { subject: options.subject }),
+        ...(options?.tenantId && { tenantid: options.tenantId }),
+    };
+    const data = JSON.stringify(cloudEvent);
+    const nc = await getNatsConnection(options?.servers);
+    nc.publish(subjectName, sc.encode(data));
+    logger.debug(`Published CloudEvent ${eventType} to NATS subject ${subjectName} (id=${cloudEvent.id})`);
+    return cloudEvent.id;
+};
+export const publishNatsEvent = async (subjectName, schema, eventData, options) => {
     const eventType = extractTypeFromSchema(schema);
     if (!eventType) {
         throw new Error('Could not extract event type from schema. Make sure your schema has proper metadata.');
@@ -91,39 +102,14 @@ export async function publishNatsEvent(subjectName, schema, eventData, options)
         throw createValidationError(eventType, [handlerValidationError]);
     }
     return publishNatsRawEvent(subjectName, eventType, validationResult.data, options);
-}
-export async function publishNatsRawEvent(subjectName, eventType, eventData, options) {
-    const cloudEvent = {
-        specversion: '1.0',
-        type: eventType,
-        source: options?.source || 'hono-service',
-        id: crypto.randomUUID(),
-        time: new Date().toISOString(),
-        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);
-    nc.publish(subjectName, sc.encode(data));
-    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.
- */
-export function __resetNatsPublisher() {
+};
+export const publish = async (eventTypeOrContract, eventData, options) => {
+    const eventType = typeof eventTypeOrContract === 'string' ? eventTypeOrContract : eventTypeOrContract.type;
+    const natsSubject = typeof eventTypeOrContract === 'string'
+        ? deriveSubjectFromEventType(eventTypeOrContract)
+        : (eventTypeOrContract.channel?.subject ?? eventTypeOrContract.type);
+    return publishNatsRawEvent(natsSubject, eventType, eventData, options);
+};
+export const __resetNatsPublisher = () => {
     natsConnectionPromise = null;
-}
+};

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.2",
+  "version": "0.5.4",
   "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"
     }
   },