@crossdelta/cloudevents 0.1.1

package/dist/src/middlewares/cloudevents-middleware.js

@@ -0,0 +1,276 @@
+import { parseEventFromContext } from '../adapters/cloudevents';
+import { handleErrorWithContext, logger } from '../infrastructure';
+import { addProcessedMessage, clearHandlerCache, createCacheKey, createProcessingContext, getCachedHandlers, isDlqSafeMode, isHandlerMatching, publishRecoverableError, quarantineMessage, setupHandlers, throwValidationError, validateEventData, } from '../processing';
+// Export clearHandlerCache for testing
+export { clearHandlerCache };
+/**
+ * Logs middleware initialization status
+ */
+const logInitialization = (options, log) => {
+    if (isDlqSafeMode(options)) {
+        const quarantine = options.quarantineTopic || 'not configured';
+        const errorTopic = options.errorTopic || 'not configured';
+        const projectId = options.projectId || 'default';
+        const source = options.source || 'auto-detected';
+        if (log === 'pretty') {
+            logger.info('DLQ-Safe mode enabled');
+            logger.info(`  • Quarantine topic: ${quarantine}`);
+            logger.info(`  • Error topic: ${errorTopic}`);
+            logger.info(`  • Project ID: ${projectId}`);
+            logger.info(`  • Source: ${source}`);
+        }
+        else {
+            logger.info('CloudEvents middleware initialized', {
+                mode: 'DLQ-Safe',
+                quarantineTopic: quarantine,
+                errorTopic: errorTopic,
+                projectId: projectId,
+                source: source,
+            });
+        }
+    }
+    else {
+        if (log === 'pretty') {
+            logger.info('DLQ-Safe mode disabled - using standard error handling');
+        }
+        else {
+            logger.info('CloudEvents middleware initialized', {
+                mode: 'Standard',
+                note: 'Using standard error handling',
+            });
+        }
+    }
+};
+/**
+ * Executes a single handler with error handling
+ */
+const executeHandler = async (handler, eventData, context) => {
+    try {
+        await handler.handle(eventData, context);
+    }
+    catch (error) {
+        logger.error(`Handler execution failed for ${handler.name}:`, error);
+        throw error;
+    }
+};
+/**
+ * Processes handlers in DLQ-safe or standard mode
+ */
+const processHandlerSafely = async (handler, eventData, ctx, processingContext, options) => {
+    const validationResult = validateEventData(handler, eventData);
+    if ('error' in validationResult) {
+        if (validationResult.shouldSkip) {
+            return; // Skip this handler in safeParse mode
+        }
+        if (isDlqSafeMode(options)) {
+            // Non-blocking quarantine - don't wait for DLQ publishing
+            queueMicrotask(() => {
+                quarantineMessage(processingContext, 'validation_error', options, validationResult.error).catch((error) => {
+                    logger.error('Failed to quarantine validation error:', error);
+                });
+            });
+            return;
+        }
+        throwValidationError(handler.name, validationResult.error);
+    }
+    // Execute handler
+    try {
+        await executeHandler(handler, eventData, ctx);
+    }
+    catch (error) {
+        if (isDlqSafeMode(options)) {
+            // Non-blocking error publishing - don't wait for DLQ publishing
+            queueMicrotask(() => {
+                publishRecoverableError(processingContext, error, options).catch((publishError) => {
+                    logger.error('Failed to publish recoverable error:', publishError);
+                });
+            });
+            return;
+        }
+        throw error;
+    }
+};
+/**
+ * Executes all matching handlers for an event
+ */
+const executeMatchingHandlers = async (handlers, eventType, eventData, ctx, processingContext, options) => {
+    const matchingHandlers = handlers.filter(isHandlerMatching(eventType, eventData, ctx));
+    if (matchingHandlers.length === 0) {
+        const errorMessage = `No handlers found for event type: ${eventType}`;
+        if (isDlqSafeMode(options)) {
+            // Non-blocking quarantine - don't wait for DLQ publishing
+            queueMicrotask(() => {
+                quarantineMessage(processingContext, 'no_handler', options, new Error(errorMessage)).catch((error) => {
+                    logger.error('Failed to quarantine no_handler error:', error);
+                });
+            });
+            return;
+        }
+        throw new Error(errorMessage);
+    }
+    // Process all matching handlers
+    await Promise.all(matchingHandlers.map((handler) => processHandlerSafely(handler, eventData, ctx, processingContext, options)));
+};
+/**
+ * Main CloudEvent processing function
+ */
+const processCloudEvent = async (ctx, options) => {
+    const cacheKey = createCacheKey(options.discover, options.handlers);
+    const handlers = getCachedHandlers(cacheKey);
+    try {
+        const { event, cloudEventData } = await parseEventFromContext(ctx);
+        // Use cloudEventData as primary source, fallback to event
+        const eventData = cloudEventData || event;
+        if (!eventData) {
+            throw new Error('Failed to parse CloudEvent from request');
+        }
+        const eventType = eventData.type;
+        const eventPayload = eventData.data;
+        const context = cloudEventData || {};
+        const messageId = eventData.id || 'unknown';
+        // Deduplication check
+        const dedupeSet = options.processedMessageIds || new Set();
+        if (dedupeSet.has(messageId)) {
+            logger.info(`Duplicate message ${messageId} detected, skipping processing`);
+            return ctx.json({ status: 'duplicate', messageId }, 200);
+        }
+        addProcessedMessage(messageId);
+        dedupeSet.add(messageId);
+        const processingContext = createProcessingContext(eventType, eventPayload, context, event || eventData);
+        if (options.log) {
+            logger.info(`Processing event type: ${eventType}`);
+        }
+        // Execute handlers
+        await executeMatchingHandlers(handlers, eventType, eventPayload, context, processingContext, options);
+        // Return success response
+        return isDlqSafeMode(options)
+            ? ctx.body(null, 204) // Always 204 in DLQ-safe mode
+            : ctx.json({ status: 'processed', eventType, messageId }, 200);
+    }
+    catch (error) {
+        // Handle ValidationError specifically
+        if (error && typeof error === 'object' && 'type' in error && error.type === 'ValidationError') {
+            return ctx.json({ error }, 422);
+        }
+        handleErrorWithContext(error, ctx, { isDlqSafe: isDlqSafeMode(options) });
+        return ctx.json({ error: 'Internal Server Error' }, 500);
+    }
+};
+/**
+ * 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
+ */
+export function cloudEvents(options = {}) {
+    const { discover, handlers = [], log = false } = options;
+    const cacheKey = createCacheKey(discover, handlers);
+    // Setup handlers immediately when middleware is created
+    if (log) {
+        setupHandlers(cacheKey, discover, handlers, log)
+            // Log configuration status based on log format preference
+            .then(() => logInitialization(options, log))
+            .catch((error) => logger.error('Failed to setup handlers during initialization:', error));
+    }
+    return async (ctx, next) => {
+        if (ctx.req.method !== 'POST') {
+            return next();
+        }
+        await setupHandlers(cacheKey, discover, handlers, log);
+        try {
+            return await processCloudEvent(ctx, options);
+        }
+        catch (error) {
+            // In DLQ-safe mode, always return 204 to prevent DLQ
+            if (isDlqSafeMode(options)) {
+                logger.error('Error during request processing (DLQ-safe mode):', error);
+                queueMicrotask(async () => {
+                    try {
+                        const processingContext = createProcessingContext('unknown', null, null, null);
+                        await quarantineMessage(processingContext, 'processing_error', options, error);
+                    }
+                    catch (quarantineError) {
+                        const errorMessage = quarantineError instanceof Error ? quarantineError.message : 'Unknown error';
+                        logger.error(`Failed to quarantine error: ${errorMessage}`);
+                    }
+                });
+                return ctx.body(null, 204);
+            }
+            throw error;
+        }
+    };
+}

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

@@ -0,0 +1 @@
+export { clearHandlerCache, cloudEvents } from './cloudevents-middleware';

package/dist/src/middlewares/index.js

@@ -0,0 +1 @@
+export { clearHandlerCache, cloudEvents } from './cloudevents-middleware';

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

@@ -0,0 +1,34 @@
+/**
+ * DLQ-Safe mode utilities
+ * Handles quarantine and error publishing for CloudEvents processing
+ */
+export interface ProcessingContext {
+    messageId: string;
+    eventType: string;
+    eventData: unknown;
+    eventContext: unknown;
+    timestamp: string;
+    originalCloudEvent: unknown;
+}
+export interface DlqOptions {
+    quarantineTopic?: string;
+    errorTopic?: string;
+    projectId?: string;
+    source?: string;
+}
+/**
+ * Checks if DLQ-Safe mode is enabled
+ */
+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>;
+/**
+ * Publishes recoverable processing errors to the error topic
+ */
+export declare const publishRecoverableError: (processingContext: ProcessingContext, error: unknown, options: DlqOptions) => Promise<void>;
+/**
+ * Creates processing context from event data
+ */
+export declare const createProcessingContext: (eventType: string, eventData: unknown, context: unknown, originalCloudEvent: unknown) => ProcessingContext;

package/dist/src/processing/dlq-safe.js

@@ -0,0 +1,91 @@
+/**
+ * DLQ-Safe mode utilities
+ * Handles quarantine and error publishing for CloudEvents processing
+ */
+import { logger } from '../infrastructure';
+import { publishRawEvent } from '../publishing';
+/**
+ * Checks if DLQ-Safe mode is enabled
+ */
+export const isDlqSafeMode = (options) => {
+    return !!(options.quarantineTopic || options.errorTopic);
+};
+/**
+ * Publishes a message to the quarantine topic for "poison messages" that can't be processed
+ */
+export const quarantineMessage = async (processingContext, reason, options, error) => {
+    if (!options.quarantineTopic) {
+        logger.warn('No quarantine topic configured, skipping quarantine');
+        return;
+    }
+    try {
+        const quarantineData = {
+            originalMessageId: processingContext.messageId,
+            originalEventType: processingContext.eventType,
+            originalEventData: processingContext.eventData,
+            originalEventContext: processingContext.eventContext,
+            originalCloudEvent: processingContext.originalCloudEvent,
+            quarantinedAt: new Date().toISOString(),
+            quarantineReason: reason,
+            error: error ? String(error) : undefined,
+        };
+        await publishRawEvent(options.quarantineTopic, 'hono.cloudevents.quarantined', quarantineData, {
+            projectId: options.projectId,
+            subject: `quarantine.${reason}`,
+            source: options.source || 'hono-cloudevents',
+            attributes: {
+                'quarantine-reason': reason,
+            },
+        });
+        logger.info(`Message ${processingContext.messageId} quarantined: ${reason}`);
+    }
+    catch (publishError) {
+        const errorMessage = publishError instanceof Error ? publishError.message : 'Unknown error';
+        logger.error(`Failed to quarantine message ${processingContext.messageId}: ${errorMessage}`);
+    }
+};
+/**
+ * Publishes recoverable processing errors to the error topic
+ */
+export const publishRecoverableError = async (processingContext, error, options) => {
+    if (!options.errorTopic) {
+        logger.warn('No error topic configured, skipping error publishing');
+        return;
+    }
+    try {
+        const errorData = {
+            originalMessageId: processingContext.messageId,
+            originalEventType: processingContext.eventType,
+            originalEventData: processingContext.eventData,
+            originalEventContext: processingContext.eventContext,
+            originalCloudEvent: processingContext.originalCloudEvent,
+            errorTimestamp: new Date().toISOString(),
+            error: {
+                message: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+                type: error instanceof Error ? error.constructor.name : typeof error,
+            },
+        };
+        await publishRawEvent(options.errorTopic, 'hono.cloudevents.processing-error', errorData, {
+            projectId: options.projectId,
+            subject: 'processing.error',
+            source: options.source || 'hono-cloudevents',
+        });
+        logger.info(`Processing error published for message ${processingContext.messageId}`);
+    }
+    catch (publishError) {
+        const errorMessage = publishError instanceof Error ? publishError.message : 'Unknown error';
+        logger.error(`Failed to publish error for message ${processingContext.messageId}: ${errorMessage}`);
+    }
+};
+/**
+ * Creates processing context from event data
+ */
+export const createProcessingContext = (eventType, eventData, context, originalCloudEvent) => ({
+    messageId: context?.messageId || 'unknown',
+    eventType,
+    eventData,
+    eventContext: context,
+    timestamp: new Date().toISOString(),
+    originalCloudEvent,
+});

package/dist/src/processing/handler-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Handler Cache Management
+ * Immutable cache operations for CloudEvents handlers
+ */
+import type { ZodTypeAny } from 'zod';
+import { type EnrichedEvent, type HandlerConstructor } from '../domain';
+export interface ProcessedHandler {
+    type: string;
+    name: string;
+    schema: ZodTypeAny;
+    handle: (payload: unknown, context?: unknown) => Promise<void>;
+    match?: (event: EnrichedEvent<unknown>) => boolean;
+    safeParse?: boolean;
+}
+/**
+ * Clears the handler cache. Useful for testing.
+ * @internal
+ */
+export declare const clearHandlerCache: () => void;
+export declare const getCachedHandlers: (key: string) => ProcessedHandler[];
+export declare const setCachedHandlers: (key: string, handlers: ProcessedHandler[]) => void;
+export declare const hasCachedHandlers: (key: string) => boolean;
+export declare const isMessageProcessed: (messageId: string) => boolean;
+export declare const addProcessedMessage: (messageId: string) => void;
+/**
+ * Converts HandlerConstructor to ProcessedHandler
+ */
+export declare const processHandler: (HandlerClass: HandlerConstructor) => ProcessedHandler | null;
+/**
+ * Creates a cache key from configuration with environment awareness
+ */
+export declare const createCacheKey: (discover?: string, handlers?: HandlerConstructor[]) => string;
+/**
+ * Setup handlers with caching
+ */
+export declare const setupHandlers: (cacheKey: string, discover?: string, handlers?: HandlerConstructor[], log?: boolean | "pretty" | "structured") => Promise<void>;

package/dist/src/processing/handler-cache.js

@@ -0,0 +1,94 @@
+/**
+ * Handler Cache Management
+ * Immutable cache operations for CloudEvents handlers
+ */
+import { discoverHandlers, extractTypeFromSchema } from '../domain';
+import { logger } from '../infrastructure/logging';
+const createEmptyCache = () => new Map();
+const createEmptyMessageIds = () => new Set();
+// Global state (necessary for middleware persistence)
+let handlerCache = createEmptyCache();
+let processedMessageIds = createEmptyMessageIds();
+/**
+ * Clears the handler cache. Useful for testing.
+ * @internal
+ */
+export const clearHandlerCache = () => {
+    handlerCache = createEmptyCache();
+    processedMessageIds = createEmptyMessageIds();
+};
+// Pure cache operations
+export const getCachedHandlers = (key) => handlerCache.get(key) || [];
+export const setCachedHandlers = (key, handlers) => {
+    handlerCache = new Map(handlerCache).set(key, handlers);
+};
+export const hasCachedHandlers = (key) => handlerCache.has(key);
+export const isMessageProcessed = (messageId) => processedMessageIds.has(messageId);
+export const addProcessedMessage = (messageId) => {
+    processedMessageIds = new Set(processedMessageIds).add(messageId);
+};
+/**
+ * Converts HandlerConstructor to ProcessedHandler
+ */
+export const processHandler = (HandlerClass) => {
+    const metadata = HandlerClass.__eventarcMetadata;
+    if (!metadata)
+        return null;
+    const instance = new HandlerClass();
+    const eventType = metadata.declaredType || extractTypeFromSchema(metadata.schema);
+    if (!eventType)
+        return null;
+    return {
+        type: eventType,
+        name: HandlerClass.name,
+        schema: metadata.schema,
+        handle: async (payload, context) => {
+            await Promise.resolve(instance.handle(payload, context));
+        },
+        match: metadata.match,
+        safeParse: metadata.safeParse || false,
+    };
+};
+/**
+ * Creates a cache key from configuration with environment awareness
+ */
+export const createCacheKey = (discover, handlers = []) => {
+    const discoverKey = discover || 'no-discover';
+    const handlersKey = handlers
+        .map((h) => h.name)
+        .sort()
+        .join(',') || 'no-handlers';
+    const envKey = process.env.NODE_ENV || 'development';
+    return `${envKey}:${discoverKey}:${handlersKey}`;
+};
+/**
+ * Setup handlers with caching
+ */
+export const setupHandlers = async (cacheKey, discover, handlers = [], log = false) => {
+    if (hasCachedHandlers(cacheKey))
+        return;
+    try {
+        const allHandlers = discover ? await discoverHandlers(discover, { log: !!log }) : handlers;
+        const processedHandlers = allHandlers.map(processHandler).filter(Boolean);
+        setCachedHandlers(cacheKey, processedHandlers);
+        if (log && processedHandlers.length > 0) {
+            if (log === 'pretty') {
+                logger.info(`Discovered ${processedHandlers.length} handler${processedHandlers.length === 1 ? '' : 's'}:`);
+                for (const handler of processedHandlers) {
+                    logger.info(`  • ${handler.name}`);
+                }
+            }
+            else {
+                // structured or true
+                logger.info('Handler discovery completed', {
+                    handlerCount: processedHandlers.length,
+                    handlers: processedHandlers.map((h) => h.name),
+                });
+            }
+        }
+    }
+    catch (error) {
+        logger.error('Failed to setup handlers:', error);
+        setCachedHandlers(cacheKey, []);
+    }
+};

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

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

package/dist/src/processing/index.js

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

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

@@ -0,0 +1,41 @@
+/**
+ * Validation utilities for CloudEvents processing
+ */
+import type { HandlerValidationError } from '../domain';
+import type { ProcessedHandler } from './handler-cache';
+/**
+ * Creates validation details from Zod error
+ */
+export declare const createValidationDetails: (error: {
+    issues: Array<{
+        code: string;
+        message: string;
+        path: Array<string | number>;
+        expected?: unknown;
+        received?: unknown;
+    }>;
+}) => {
+    code: string;
+    message: string;
+    path: (string | number)[];
+    expected: string;
+    received: string;
+}[];
+/**
+ * Validates event data against handler schema
+ * Returns structured result for both normal and safeParse modes
+ */
+export declare const validateEventData: (handler: ProcessedHandler, eventData: unknown) => {
+    success: true;
+} | {
+    error: HandlerValidationError;
+    shouldSkip: boolean;
+};
+/**
+ * Checks if handler matches event
+ */
+export declare const isHandlerMatching: (eventType: string, eventData: unknown, context: unknown) => (handler: ProcessedHandler) => boolean;
+/**
+ * Throws validation error in standard mode
+ */
+export declare const throwValidationError: (handlerType: string, error: HandlerValidationError) => never;

package/dist/src/processing/validation.js

@@ -0,0 +1,48 @@
+import { createValidationError } from '../infrastructure';
+/**
+ * Creates validation details from Zod error
+ */
+export const createValidationDetails = (error) => error.issues.map((issue) => ({
+    code: issue.code,
+    message: issue.message,
+    path: issue.path,
+    expected: String(issue.expected),
+    received: String(issue.received),
+}));
+/**
+ * Validates event data against handler schema
+ * Returns structured result for both normal and safeParse modes
+ */
+export const validateEventData = (handler, eventData) => {
+    const result = handler.schema.safeParse(eventData);
+    if (!result.success) {
+        const validationDetails = createValidationDetails(result.error);
+        const handlerValidationError = {
+            handlerName: handler.name,
+            validationErrors: validationDetails,
+        };
+        return {
+            error: handlerValidationError,
+            shouldSkip: handler.safeParse || false,
+        };
+    }
+    return { success: true };
+};
+/**
+ * Checks if handler matches event
+ */
+export const isHandlerMatching = (eventType, eventData, context) => (handler) => {
+    if (handler.type !== eventType)
+        return false;
+    if (handler.match) {
+        const enrichedEvent = { data: eventData, ...context };
+        return handler.match(enrichedEvent);
+    }
+    return true;
+};
+/**
+ * Throws validation error in standard mode
+ */
+export const throwValidationError = (handlerType, error) => {
+    throw createValidationError(handlerType, [error]);
+};

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

@@ -0,0 +1,2 @@
+export * from './nats.publisher';
+export * from './pubsub.publisher';

package/dist/src/publishing/index.js

@@ -0,0 +1,2 @@
+export * from './nats.publisher';
+export * from './pubsub.publisher';

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

@@ -0,0 +1,22 @@
+import type { ZodTypeAny } from 'zod';
+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;
+}
+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>;
+/**
+ * @internal Resets the cached NATS connection. Intended for testing only.
+ */
+export declare function __resetNatsPublisher(): void;