@crossdelta/cloudevents 0.5.7 → 0.6.0

package/dist/index.d.ts

@@ -1,9 +1,812 @@
-export type { EventContext } from './adapters/cloudevents';
-export { parseEventFromContext } from './adapters/cloudevents';
-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';
-export * from './publishing';
-export type { JetStreamConsumerOptions, JetStreamStreamOptions, JetStreamStreamsConsumerOptions, JetStreamStreamsOptions, StreamConfig, StreamDefinition, } from './transports/nats';
-export { consumeJetStreamEvents, consumeJetStreamStreams, consumeJetStreams, consumeNatsEvents, ensureJetStreamStream, ensureJetStreamStreams, ensureJetStreams, } from './transports/nats';
+import { Context } from 'hono';
+import { CloudEventV1 } from 'cloudevents';
+import { ZodTypeAny, z } from 'zod';
+import { ConsumerMessages, Subscription } from 'nats';
+
+/**
+ * Adapter types for external protocols
+ */
+
+/**
+ * Simplified event context for handler consumption
+ *
+ * Provides essential CloudEvent metadata without the complexity of the full CloudEventV1 interface.
+ * This is what handler functions receive as context parameter.
+ */
+interface EventContext {
+    /** Event type identifier (from CloudEvent.type) */
+    eventType: string;
+    /** Event source (from CloudEvent.source) */
+    source: string;
+    /** Optional subject (from CloudEvent.subject) */
+    subject?: string;
+    /** Event timestamp (from CloudEvent.time) */
+    time: string;
+    /** Message ID for deduplication (from CloudEvent.id) */
+    messageId?: string;
+}
+/**
+ * Result of CloudEvent parsing - either CloudEvents SDK object or normalized data
+ */
+interface CloudEventParseResult {
+    event: CloudEventV1<unknown> | null;
+    cloudEventData: CloudEventV1<unknown> | null;
+}
+
+/**
+ * Parses CloudEvent from Hono context with automatic format detection.
+ *
+ * Supports:
+ * 1. Structured CloudEvent (body with specversion)
+ * 2. Pub/Sub push message format (body with message field)
+ * 3. Binary CloudEvent (CloudEvent headers)
+ * 4. Raw event data (fallback)
+ *
+ * Uses dynamic imports to load only necessary parsers for optimal performance.
+ */
+declare const parseEventFromContext: (context: Context) => Promise<CloudEventParseResult>;
+
+/**
+ * Domain Types
+ *
+ * Core business logic types for handlers, events, and domain operations
+ */
+
+/**
+ * Event handler interface
+ */
+interface EventHandler<T = unknown> {
+    handle(payload: T, context?: unknown): Promise<void> | void;
+}
+/**
+ * Constructor type for event handler classes that implement the EventHandler interface
+ */
+type HandlerConstructor<T = unknown> = (new (...args: unknown[]) => EventHandler<T>) & {
+    __eventarcMetadata?: {
+        schema: ZodTypeAny;
+        declaredType?: string;
+        match?: (event: EnrichedEvent<T>) => boolean;
+        safeParse?: boolean;
+    };
+};
+/**
+ * Enriched event with both data and context
+ */
+interface EnrichedEvent<T> extends EventContext {
+    data: T;
+    /** Tenant identifier for multi-tenant event routing */
+    tenantId?: string;
+}
+/**
+ * Match function type for custom event matching
+ */
+type MatchFn<T> = (event: EnrichedEvent<T>) => boolean;
+/**
+ * Channel metadata for NATS JetStream routing
+ */
+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)
+ */
+interface ChannelConfig {
+    /** JetStream stream name (e.g., 'ORDERS') */
+    stream: string;
+    /** NATS subject (optional, defaults to event type) */
+    subject?: string;
+}
+/**
+ * Options for creating event handlers
+ *
+ * Note: In Zod v4, we use a more relaxed schema constraint to allow
+ * contracts defined in external packages to work correctly.
+ */
+interface HandleEventOptions<S = ZodTypeAny> {
+    schema: S;
+    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[];
+    /** Channel metadata for NATS JetStream routing (optional) */
+    channel?: ChannelConfig;
+}
+/**
+ * Routing configuration for type → subject → stream mapping
+ */
+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
+ */
+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
+ */
+type InferEventData<S extends ZodTypeAny> = S['_output'] extends {
+    data: infer D;
+} ? D : S['_output'];
+
+/**
+ * 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
+ * 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(),
+ *   }),
+ * })
+ * ```
+ *
+ * @example
+ * Contract with explicit subject:
+ * ```typescript
+ * export const OrderCreatedContract = createContract({
+ *   type: 'orders.created',
+ *   channel: {
+ *     stream: 'ORDERS',
+ *     subject: 'orders.v1.created', // Override default
+ *   },
+ *   schema: OrderSchema,
+ * })
+ * ```
+ */
+declare function createContract<TSchema extends ZodTypeAny>(options: {
+    type: string;
+    schema: TSchema;
+    match?: HandleEventOptions['match'];
+    safeParse?: boolean;
+    tenantId?: string | string[];
+    channel?: {
+        stream: string;
+        subject?: string;
+    };
+}): HandleEventOptions<TSchema> & {
+    _schema: TSchema;
+    channel?: ChannelMetadata;
+};
+
+/**
+ * Creates an event handler using the handleEvent pattern
+ * Compatible with the new middleware system
+ *
+ * Supports both inline schemas (Basic Mode) and shared contracts (Advanced Mode).
+ *
+ * @example Basic Mode - Data-only schema inline
+ * ```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 Advanced Mode - With shared contract
+ * ```typescript
+ * import { OrderCreatedContract } from '@orderboss/contracts'
+ *
+ * export default handleEvent(OrderCreatedContract, 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)
+ * })
+ * ```
+ */
+declare function handleEvent<TSchema extends ZodTypeAny>(schemaOrOptions: TSchema | HandleEventOptions<TSchema> | HandleEventOptions, 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
+ */
+declare function eventSchema<T extends Record<string, ZodTypeAny>>(schema: T & {
+    type: ZodTypeAny;
+}): z.ZodObject<T & {
+    type: ZodTypeAny;
+} extends infer T_1 ? { -readonly [P in keyof T_1]: T_1[P]; } : never, z.core.$strip>;
+
+/**
+ * Domain Validation
+ *
+ * Core business logic for validating events, handlers, and schemas
+ * Contains no infrastructure concerns - pure domain logic
+ */
+
+/**
+ * Extracts the event type from a Zod schema by looking for a literal 'type' field
+ *
+ * @param schema - Zod schema to extract type from
+ * @returns Event type string or undefined if not found
+ */
+declare const extractTypeFromSchema: (schema: ZodTypeAny) => string | undefined;
+
+/**
+ * Handler Cache Management
+ * Immutable cache operations for CloudEvents handlers
+ */
+
+/**
+ * Clears the handler cache. Useful for testing.
+ * @internal
+ */
+declare const clearHandlerCache: () => void;
+
+/**
+ * Idempotency utilities for CloudEvents processing
+ *
+ * Provides deduplication support to ensure handlers process each message exactly once.
+ * Uses CloudEvent ID as the deduplication key.
+ */
+
+/**
+ * Options for the in-memory idempotency store
+ */
+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/events/**\/*.handler.ts`,
+ *   idempotencyStore: store,
+ * })
+ * ```
+ */
+declare function createInMemoryIdempotencyStore(options?: InMemoryIdempotencyStoreOptions): IdempotencyStore;
+/**
+ * Gets or creates the default idempotency store
+ */
+declare function getDefaultIdempotencyStore(): IdempotencyStore;
+/**
+ * Resets the default idempotency store. Useful for testing.
+ */
+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
+ */
+declare function checkAndMarkProcessed(store: IdempotencyStore, messageId: string, ttlMs?: number): Promise<boolean>;
+
+/**
+ * CloudEvents Middleware for Hono - Simplified Core
+ *
+ * Supports automatic handler discovery and manual registration.
+ * Handles event validation, routing, and safeParse mode for graceful degradation.
+ * Includes optional DLQ-Safe mode for Pub/Sub Push endpoints.
+ */
+
+/**
+ * Configuration options for CloudEvents middleware
+ *
+ * @interface CloudEventsOptions
+ */
+interface CloudEventsOptions {
+    /**
+     * Directory path for automatic handler discovery
+     *
+     * @example './src/events' or './handlers'
+     * @default undefined
+     */
+    discover?: string;
+    /**
+     * Array of handler constructors for manual registration
+     *
+     * @example [CustomerCreatedHandler, OrderProcessedHandler]
+     * @default []
+     */
+    handlers?: HandlerConstructor[];
+    /**
+     * Logging configuration
+     *
+     * - `false`: No logging (production default)
+     * - `true`: Basic structured logging
+     * - `'pretty'`: Human-readable format (development)
+     * - `'structured'`: JSON format (production)
+     *
+     * @default false
+     */
+    log?: boolean | 'pretty' | 'structured';
+    /**
+     * Google Cloud Pub/Sub topic for quarantining invalid messages
+     *
+     * When specified, enables DLQ-Safe mode:
+     * - Always returns HTTP 204 to prevent redelivery
+     * - Quarantines validation errors and malformed events
+     * - Non-blocking background processing
+     *
+     * @example 'projects/my-project/topics/quarantine-topic'
+     * @default undefined
+     */
+    quarantineTopic?: string;
+    /**
+     * Google Cloud Pub/Sub topic for publishing recoverable handler errors
+     *
+     * Used in DLQ-Safe mode to publish errors that can be retried later:
+     * - Handler execution failures
+     * - Temporary processing errors
+     * - Network timeouts
+     *
+     * @example 'projects/my-project/topics/error-topic'
+     * @default undefined
+     */
+    errorTopic?: string;
+    /**
+     * Google Cloud Project ID
+     *
+     * @example 'my-production-project'
+     * @default Detected from environment (GOOGLE_CLOUD_PROJECT, etc.)
+     */
+    projectId?: string;
+    /**
+     * CloudEvent source identifier
+     *
+     * @example 'my-service' or 'https://my-domain.com/service'
+     * @default Auto-detected from environment
+     */
+    source?: string;
+    /**
+     * Set for message deduplication based on CloudEvent ID
+     *
+     * Automatically managed by the middleware to prevent duplicate processing.
+     * Can be provided for custom deduplication logic.
+     *
+     * @default new Set<string>()
+     */
+    processedMessageIds?: Set<string>;
+}
+
+/**
+ * CloudEvents middleware for Hono applications
+ *
+ * Provides automatic CloudEvent processing with handler discovery, validation,
+ * and optional DLQ-Safe mode for Google Cloud Pub/Sub Push endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono'
+ * import { cloudEvents } from '@orderboss/cloudevents'
+ *
+ * const app = new Hono()
+ *
+ * // Basic usage with handler discovery
+ * app.use('*', cloudEvents({
+ *   discover: './src/events/*.event.{ts,js}',
+ *   log: true
+ * }))
+ *
+ * // Manual handler registration
+ * app.use('*', cloudEvents({
+ *   handlers: [CustomerCreatedHandler, OrderProcessedHandler],
+ *   log: 'pretty'
+ * }))
+ *
+ * // DLQ-Safe mode for Pub/Sub Push
+ * app.use('*', cloudEvents({
+ *   discover: './src/events/*.event.{ts,js}',
+ *   quarantineTopic: 'quarantine-topic',
+ *   errorTopic: 'error-topic',
+ *   projectId: 'my-project',
+ *   log: 'structured'
+ * }))
+ * ```
+ *
+ * @param options - Configuration options for the middleware
+ * @param options.discover - Directory path for automatic handler discovery (e.g., './src/events')
+ * @param options.handlers - Array of handler constructors for manual registration
+ * @param options.log - Enable logging: false (default), true, 'pretty' (dev), or 'structured' (prod)
+ * @param options.quarantineTopic - Pub/Sub topic for quarantining invalid messages (enables DLQ-Safe mode)
+ * @param options.errorTopic - Pub/Sub topic for publishing recoverable handler errors
+ * @param options.projectId - Google Cloud Project ID (defaults to environment detection)
+ * @param options.source - CloudEvent source identifier (defaults to auto-detection)
+ * @param options.processedMessageIds - Set for message deduplication (automatically managed)
+ *
+ * @returns Hono middleware function that processes CloudEvents
+ *
+ * @remarks
+ * **Handler Discovery:**
+ * - Automatically discovers handlers in the specified directory
+ * - Handlers must export a class that extends the base handler pattern
+ * - Supports nested directories and TypeScript files
+ *
+ * **Event Format Support:**
+ * - CloudEvents Structured mode (JSON with specversion)
+ * - CloudEvents Binary mode (headers + data)
+ * - Google Pub/Sub Push format
+ * - Raw event data (wrapped in CloudEvent)
+ *
+ * **DLQ-Safe Mode:**
+ * - Activated when `quarantineTopic` is specified
+ * - Always returns HTTP 204 to prevent Pub/Sub redelivery
+ * - Quarantines invalid messages to specified topic
+ * - Publishes handler errors to error topic
+ * - All DLQ operations are non-blocking for optimal performance
+ *
+ * **Standard Mode:**
+ * - Returns HTTP 200 for successful processing
+ * - Returns HTTP 422 for validation errors
+ * - Returns HTTP 500 for handler errors
+ * - Allows Pub/Sub DLQ behavior for unhandled errors
+ *
+ * **Performance Features:**
+ * - Handler caching for improved startup time
+ * - Dynamic parser loading for optimal bundle size
+ * - Message deduplication based on CloudEvent ID
+ * - Background processing for DLQ operations
+ *
+ * @since 1.0.0
+ */
+declare function cloudEvents(options?: CloudEventsOptions): (ctx: Context, next: () => Promise<void>) => Promise<void | Response>;
+
+interface PublishNatsEventOptions {
+    servers?: string;
+    source?: string;
+    subject?: string;
+    tenantId?: string;
+}
+declare const deriveSubjectFromType: (eventType: string, config?: RoutingConfig) => string;
+declare const deriveStreamFromType: (eventType: string, config?: RoutingConfig) => string | undefined;
+declare const publishNatsRawEvent: (subjectName: string, eventType: string, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
+declare const publishNatsEvent: <T extends ZodTypeAny>(subjectName: string, schema: T, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
+declare const publish: (eventTypeOrContract: string | {
+    type: string;
+    channel?: {
+        subject?: string;
+    };
+}, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
+declare const __resetNatsPublisher: () => void;
+
+interface PublishEventOptions {
+    projectId?: string;
+    keyFilename?: string;
+    source?: string;
+    subject?: string;
+    attributes?: Record<string, string>;
+}
+/**
+ * Publishes an event using a Zod schema for validation and type extraction.
+ * Automatically extracts the event type from the schema and creates a CloudEvent.
+ *
+ * @param topicName - PubSub topic name
+ * @param schema - Zod schema that defines the event structure and type
+ * @param eventData - Event data that must match the schema
+ * @param options - Optional PubSub configuration
+ * @returns Promise resolving to the published message ID
+ *
+ * @example
+ * ```typescript
+ * await publishEvent(
+ *   'customer-events',
+ *   CustomerCreatedSchema,
+ *   { customer: { id: '123', email: 'test@example.com' } }
+ * )
+ * ```
+ */
+declare function publishEvent<T extends ZodTypeAny>(topicName: string, schema: T, eventData: unknown, options?: PublishEventOptions): Promise<string>;
+/**
+ * Raw event publisher - bypasses schema validation.
+ * Use this when you need direct control over the event type and data.
+ *
+ * @param topicName - PubSub topic name
+ * @param eventType - Manual event type identifier
+ * @param eventData - Raw event data
+ * @param options - Optional PubSub configuration
+ * @returns Promise resolving to the published message ID
+ */
+declare function publishRawEvent(topicName: string, eventType: string, eventData: unknown, options?: PublishEventOptions): Promise<string>;
+
+/**
+ * Stream configuration options
+ */
+interface StreamConfig {
+    /** Maximum age of messages in the stream (ms). @default 7 days */
+    maxAge?: number;
+    /** Maximum size of the stream in bytes. @default 1GB */
+    maxBytes?: number;
+    /** Number of replicas. @default 1 */
+    replicas?: number;
+}
+/**
+ * Options for creating/ensuring a JetStream stream exists
+ */
+interface JetStreamStreamOptions {
+    /** NATS server URL. Defaults to NATS_URL env or nats://localhost:4222 */
+    servers?: string;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+    /** JetStream stream name */
+    stream: string;
+    /** Subjects to bind to the stream (e.g., ['orders.>', 'payments.>']) */
+    subjects: string[];
+    /** Stream configuration */
+    config?: StreamConfig;
+}
+/**
+ * Stream definition for batch operations
+ */
+interface StreamDefinition {
+    /** JetStream stream name (e.g., 'ORDERS') */
+    stream: string;
+    /** Subjects to bind (e.g., ['orders.*']) */
+    subjects: string[];
+    /** Optional stream-specific config */
+    config?: StreamConfig;
+}
+/**
+ * Options for ensuring multiple JetStream streams exist
+ */
+interface JetStreamStreamsOptions {
+    /** NATS server URL. Defaults to NATS_URL env or nats://localhost:4222 */
+    servers?: string;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+    /** Array of stream definitions */
+    streams: StreamDefinition[];
+}
+/**
+ * JetStream consumer configuration
+ */
+interface JetStreamConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
+    /** NATS server URL. Defaults to NATS_URL env or nats://localhost:4222 */
+    servers?: string;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+    /** JetStream stream name (must already exist or use ensureJetStreamStream first) */
+    stream: string;
+    /** Durable consumer name. Required for persistence across restarts */
+    consumer: string;
+    /**
+     * Optional filter subjects for this consumer.
+     * If specified, consumer only receives messages matching these subjects.
+     * If omitted, consumer receives all messages from the stream.
+     * @example ['orders.created', 'orders.updated']
+     */
+    filterSubjects?: string[];
+    /** Glob pattern to discover event handlers */
+    discover: string;
+    /**
+     * Where to start consuming from on first subscription.
+     * @default 'new' - Only new messages
+     * Options: 'all' | 'new' | 'last' | Date
+     */
+    startFrom?: 'all' | 'new' | 'last' | Date;
+    /**
+     * Max number of messages to buffer for processing
+     * @default 100
+     */
+    maxMessages?: number;
+    /**
+     * Ack wait timeout in milliseconds before message is redelivered
+     * @default 30000 (30 seconds)
+     */
+    ackWait?: number;
+    /**
+     * Max redelivery attempts before message goes to DLQ
+     * @default 3
+     */
+    maxDeliver?: number;
+    /**
+     * 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;
+}
+/**
+ * Ensures a JetStream stream exists with the given configuration.
+ * This is typically called once during application startup or in infrastructure setup.
+ *
+ * @example
+ * ```typescript
+ * // In infrastructure/setup code:
+ * await ensureJetStreamStream({
+ *   stream: 'ORDERS',
+ *   subjects: ['orders.>'],
+ *   config: {
+ *     maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+ *     replicas: 3
+ *   }
+ * })
+ * ```
+ */
+declare function ensureJetStreamStream(options: JetStreamStreamOptions): Promise<void>;
+/**
+ * Ensures multiple JetStream streams exist with a single NATS connection.
+ * More efficient than calling ensureJetStreamStream multiple times.
+ *
+ * @example
+ * ```typescript
+ * await ensureJetStreamStreams({
+ *   streams: [
+ *     { stream: 'ORDERS', subjects: ['orders.*'] },
+ *     { stream: 'CUSTOMERS', subjects: ['customers.*'] },
+ *   ]
+ * })
+ * ```
+ */
+declare function ensureJetStreamStreams(options: JetStreamStreamsOptions): Promise<void>;
+/**
+ * Consume CloudEvents from NATS JetStream with persistence and guaranteed delivery.
+ *
+ * Features:
+ * - Automatic stream and consumer creation
+ * - Durable subscriptions (survive restarts)
+ * - Automatic acknowledgments on successful processing
+ * - Configurable retry with max redelivery
+ * - Dead letter queue support
+ *
+ * @example
+ * ```typescript
+ * await consumeJetStreamEvents({
+ *   stream: 'ORDERS',
+ *   subjects: ['orders.>'],
+ *   consumer: 'notifications',
+ *   discover: `./src/events/**\/*.handler.ts`,
+ * })
+ * ```
+ */
+declare function consumeJetStreamEvents(options: JetStreamConsumerOptions): Promise<ConsumerMessages>;
+/**
+ * Options for consuming from multiple JetStream streams
+ */
+interface JetStreamStreamsConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
+    /** NATS server URL. Defaults to NATS_URL env or nats://localhost:4222 */
+    servers?: string;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+    /** Durable consumer name. Required for persistence across restarts */
+    consumer: string;
+    /** Array of stream names to consume from */
+    streams: string[];
+    /** Glob pattern to discover event handlers */
+    discover: string;
+    /** Where to start consuming from on first subscription. @default 'new' */
+    startFrom?: 'all' | 'new' | 'last' | Date;
+    /** Max number of messages to buffer for processing @default 100 */
+    maxMessages?: number;
+    /** Ack wait timeout in milliseconds @default 30000 */
+    ackWait?: number;
+    /** Max redelivery attempts @default 3 */
+    maxDeliver?: number;
+    /** Idempotency store for deduplication */
+    idempotencyStore?: IdempotencyStore | false;
+    /** TTL for idempotency records in milliseconds @default 86400000 */
+    idempotencyTtl?: number;
+}
+/**
+ * Consume CloudEvents from multiple JetStream streams with a single connection.
+ * More efficient than calling consumeJetStreamEvents multiple times.
+ *
+ * @example
+ * ```typescript
+ * await consumeJetStreamStreams({
+ *   streams: ['ORDERS', 'CUSTOMERS'],
+ *   consumer: 'notifications',
+ *   discover: `./src/events/**\/*.handler.ts`,
+ * })
+ * ```
+ */
+declare function consumeJetStreamStreams(options: JetStreamStreamsConsumerOptions): Promise<ConsumerMessages[]>;
+/**
+ * Alias for ensureJetStreamStreams - shorter name
+ * @see ensureJetStreamStreams
+ */
+declare const ensureJetStreams: typeof ensureJetStreamStreams;
+/**
+ * Alias for consumeJetStreamStreams - shorter name
+ * @see consumeJetStreamStreams
+ */
+declare const consumeJetStreams: typeof consumeJetStreamStreams;
+
+/**
+ * Describes the configuration required to bootstrap the NATS event consumer.
+ *
+ * @property servers - Optional NATS connection string; defaults to `NATS_URL` or the local instance.
+ * @property subject - NATS subject to subscribe to for incoming events.
+ * @property discover - Glob pattern or directory used to discover event handler classes.
+ * @property consumerName - Optional identifier appended to log output and the consumer name.
+ * @property user - Optional NATS username for authentication (can also use `NATS_USER` env var).
+ * @property pass - Optional NATS password for authentication (can also use `NATS_PASSWORD` env var).
+ * @property quarantineTopic - Optional Pub/Sub topic for quarantining malformed messages when DLQ mode is enabled.
+ * @property errorTopic - Optional Pub/Sub topic for recovering handler errors when DLQ mode is enabled.
+ * @property projectId - Optional Google Cloud project identifier used for DLQ publishing.
+ * @property source - Optional CloudEvent source identifier applied to DLQ messages.
+ */
+interface NatsConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
+    servers?: string;
+    subject: string;
+    discover: string;
+    consumerName?: string;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+}
+/**
+ * Connects to NATS, discovers matching event handlers, and processes incoming CloudEvents.
+ *
+ * @param options - Consumer configuration describing connection, discovery, and subscription details.
+ * @returns The active NATS subscription for the configured subject.
+ *
+ * When `quarantineTopic` or `errorTopic` is provided, the consumer forwards malformed messages
+ * and handler failures to the configured DLQ topics instead of throwing errors.
+ */
+declare function consumeNatsEvents(options: NatsConsumerOptions): Promise<Subscription>;
+
+export { type ChannelConfig, type ChannelMetadata, type EnrichedEvent, type EventContext, type HandleEventOptions, type IdempotencyStore, type InferEventData, type JetStreamConsumerOptions, type JetStreamStreamOptions, type JetStreamStreamsConsumerOptions, type JetStreamStreamsOptions, type PublishEventOptions, type PublishNatsEventOptions, type RoutingConfig, type StreamConfig, type StreamDefinition, __resetNatsPublisher, checkAndMarkProcessed, clearHandlerCache, cloudEvents, consumeJetStreamEvents, consumeJetStreamStreams, consumeJetStreams, consumeNatsEvents, createContract, createInMemoryIdempotencyStore, deriveStreamFromType, deriveSubjectFromType, ensureJetStreamStream, ensureJetStreamStreams, ensureJetStreams, eventSchema, extractTypeFromSchema, getDefaultIdempotencyStore, handleEvent, parseEventFromContext, publish, publishEvent, publishNatsEvent, publishNatsRawEvent, publishRawEvent, resetDefaultIdempotencyStore };