@crossdelta/cloudevents 0.5.6 → 0.6.0

package/dist/publishing/pubsub.publisher.d.ts

@@ -1,39 +0,0 @@
-import type { ZodTypeAny } from 'zod';
-export 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' } }
- * )
- * ```
- */
-export 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
- */
-export declare function publishRawEvent(topicName: string, eventType: string, eventData: unknown, options?: PublishEventOptions): Promise<string>;

package/dist/publishing/pubsub.publisher.js

@@ -1,84 +0,0 @@
-import { extractTypeFromSchema } from '../domain';
-import { createValidationError, logger } from '../infrastructure';
-/**
- * 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' } }
- * )
- * ```
- */
-export async function publishEvent(topicName, schema, eventData, options) {
-    // Extract event type from schema
-    const eventType = extractTypeFromSchema(schema);
-    if (!eventType) {
-        throw new Error('Could not extract event type from schema. Make sure your schema has proper metadata.');
-    }
-    // Validate the data against the schema
-    const validationResult = schema.safeParse(eventData);
-    if (!validationResult.success) {
-        const validationDetails = validationResult.error.issues.map((issue) => ({
-            code: issue.code,
-            message: issue.message,
-            path: issue.path.filter((p) => typeof p !== 'symbol'),
-            expected: 'expected' in issue ? String(issue.expected) : undefined,
-            received: 'received' in issue ? String(issue.received) : undefined,
-        }));
-        const handlerValidationError = {
-            handlerName: `Publisher:${eventType}`,
-            validationErrors: validationDetails,
-        };
-        throw createValidationError(eventType, [handlerValidationError]);
-    }
-    return publishRawEvent(topicName, eventType, validationResult.data, options);
-}
-/**
- * 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
- */
-export async function publishRawEvent(topicName, eventType, eventData, options) {
-    const { PubSub } = await import('@google-cloud/pubsub');
-    const pubsub = new PubSub({
-        projectId: options?.projectId,
-        keyFilename: options?.keyFilename,
-    });
-    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 }),
-    };
-    const data = JSON.stringify(cloudEvent);
-    const dataBuffer = Buffer.from(data);
-    const topic = pubsub.topic(topicName);
-    const messageId = await topic.publishMessage({
-        data: dataBuffer,
-        attributes: {
-            'content-type': 'application/cloudevents+json',
-            ...options?.attributes,
-        },
-    });
-    logger.debug(`Published CloudEvent ${eventType} with ID: ${messageId}`);
-    return messageId;
-}

package/dist/transports/nats/base-message-processor.d.ts

@@ -1,44 +0,0 @@
-/**
- * Shared message processing logic for NATS Core and JetStream consumers.
- * Abstracts CloudEvent parsing, handler matching, validation, and execution.
- */
-import type { CloudEventV1 } from 'cloudevents';
-import type { EnrichedEvent } from '../../domain';
-import { createProcessingContext, type DlqOptions } from '../../processing/dlq-safe';
-import type { ProcessedHandler } from '../../processing/handler-cache';
-export interface LoggerLike {
-    info(message: string, meta?: unknown): void;
-    warn(message: string, meta?: unknown): void;
-    error(message: string, meta?: unknown): void;
-}
-export interface BaseMessageProcessorDeps {
-    name: string;
-    dlqEnabled: boolean;
-    options: DlqOptions;
-    processedHandlers: ProcessedHandler[];
-    decode: (data: Uint8Array) => string;
-    logger: LoggerLike;
-}
-export type ProcessingContext = ReturnType<typeof createProcessingContext>;
-export type ParseResult<T> = {
-    ok: true;
-    cloudEvent: CloudEventV1<unknown>;
-    enriched: EnrichedEvent<unknown>;
-} | {
-    ok: false;
-    error: unknown;
-    context: ProcessingContext;
-    rawMessage: T;
-};
-/**
- * Creates shared message processing utilities
- */
-export declare function createBaseMessageProcessor(deps: BaseMessageProcessorDeps): {
-    toEnrichedEvent: (ce: CloudEventV1<unknown>) => EnrichedEvent<unknown>;
-    createContext: (event: EnrichedEvent<unknown>, ce?: CloudEventV1<unknown>) => import("../../processing").ProcessingContext;
-    parseCloudEvent: (data: Uint8Array) => CloudEventV1<unknown>;
-    findHandler: (event: EnrichedEvent<unknown>) => ProcessedHandler | undefined;
-    processEvent: (cloudEvent: CloudEventV1<unknown>, enriched: EnrichedEvent<unknown>) => Promise<boolean>;
-    handleParseError: (error: unknown, context: ProcessingContext, redeliveryCount?: number) => Promise<boolean>;
-    handleUnhandledError: (error: unknown, context: ProcessingContext, ackFn?: () => void) => Promise<void>;
-};

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

@@ -1,118 +0,0 @@
-/**
- * Shared message processing logic for NATS Core and JetStream consumers.
- * Abstracts CloudEvent parsing, handler matching, validation, and execution.
- */
-import { createProcessingContext, publishRecoverableError, quarantineMessage, } from '../../processing/dlq-safe';
-import { throwValidationError, validateEventData } from '../../processing/validation';
-/**
- * Extracts tenantId from CloudEvent extensions
- * Supports both 'tenantid' (CloudEvents spec lowercase) and 'tenantId' variants
- */
-function extractTenantId(ce) {
-    const extensions = ce;
-    return (extensions.tenantid ?? extensions.tenantId ?? extensions.tenant_id);
-}
-/**
- * Creates shared message processing utilities
- */
-export function createBaseMessageProcessor(deps) {
-    const { name, dlqEnabled, options, processedHandlers, decode, logger } = deps;
-    const toEnrichedEvent = (ce) => ({
-        eventType: ce.type,
-        source: ce.source,
-        subject: ce.subject,
-        time: ce.time ?? new Date().toISOString(),
-        messageId: ce.id,
-        data: ce.data,
-        tenantId: extractTenantId(ce),
-    });
-    const createContext = (event, ce) => createProcessingContext(event.eventType, event.data, event, ce);
-    const parseCloudEvent = (data) => {
-        return JSON.parse(decode(data));
-    };
-    const findHandler = (event) => processedHandlers.find((handler) => handler.type === event.eventType && (!handler.match || handler.match(event)));
-    const handleMissingHandler = async (context, eventType) => {
-        logger.warn(`[${name}] no handler for event type: ${eventType}`);
-        if (dlqEnabled) {
-            await quarantineMessage(context, 'no_handler', options, new Error(`No handler for event type ${eventType}`));
-        }
-        // Ack - no point in retrying if there's no handler
-        return { handled: true, shouldAck: true };
-    };
-    const handleValidationFailure = async (validationResult, handler, context) => {
-        // Log validation errors with full details for debugging
-        logger.error(`[${name}] validation failed for handler ${handler.name}`, JSON.stringify(validationResult.error, null, 2));
-        if (dlqEnabled) {
-            await quarantineMessage(context, 'validation_error', options, validationResult.error);
-            return { handled: true, shouldAck: true };
-        }
-        if (validationResult.shouldSkip) {
-            return { handled: true, shouldAck: true };
-        }
-        // Throw to trigger retry
-        throwValidationError(handler.name, validationResult.error);
-        return { handled: true, shouldAck: false }; // Never reached
-    };
-    const executeHandler = async (handler, enriched, context) => {
-        try {
-            await handler.handle(enriched.data, enriched);
-            return { success: true };
-        }
-        catch (error) {
-            if (dlqEnabled) {
-                await publishRecoverableError(context, error, options);
-                return { success: true }; // Ack after publishing to error topic
-            }
-            throw error; // Will trigger retry
-        }
-    };
-    /**
-     * Process a parsed CloudEvent message
-     * @returns true if message was handled successfully (should ack), false for retry (should nak)
-     */
-    const processEvent = async (cloudEvent, enriched) => {
-        const context = createContext(enriched, cloudEvent);
-        const handler = findHandler(enriched);
-        if (!handler) {
-            const result = await handleMissingHandler(context, enriched.eventType);
-            return result.shouldAck;
-        }
-        const validationResult = validateEventData(handler, enriched.data);
-        if ('error' in validationResult) {
-            const result = await handleValidationFailure(validationResult, handler, context);
-            return result.shouldAck;
-        }
-        const result = await executeHandler(handler, enriched, context);
-        return result.success;
-    };
-    const handleParseError = async (error, context, redeliveryCount = 0) => {
-        logger.error(`[${name}] failed to parse CloudEvent (attempt ${redeliveryCount + 1})`, error);
-        if (dlqEnabled) {
-            await quarantineMessage(context, 'parse_error', options, error);
-            return true; // Ack after quarantine
-        }
-        // After max retries, ack to prevent infinite loop
-        return redeliveryCount >= 2;
-    };
-    const handleUnhandledError = async (error, context, ackFn) => {
-        logger.error(`[${name}] unhandled processing error`, error);
-        if (dlqEnabled) {
-            try {
-                await quarantineMessage(context, 'unhandled_error', options, error);
-                ackFn?.();
-            }
-            catch (quarantineError) {
-                logger.error(`[${name}] failed to quarantine unhandled error`, quarantineError);
-            }
-        }
-    };
-    return {
-        toEnrichedEvent,
-        createContext,
-        parseCloudEvent,
-        findHandler,
-        processEvent,
-        handleParseError,
-        handleUnhandledError,
-    };
-}

package/dist/transports/nats/index.d.ts

@@ -1,5 +0,0 @@
-export * from './base-message-processor';
-export * from './jetstream-consumer';
-export { createJetStreamMessageProcessor, type JetStreamMessageProcessor, type JetStreamMessageProcessorDeps, } from './jetstream-message-processor';
-export * from './nats-consumer';
-export * from './nats-message-processor';

package/dist/transports/nats/index.js

@@ -1,5 +0,0 @@
-export * from './base-message-processor';
-export * from './jetstream-consumer';
-export { createJetStreamMessageProcessor, } from './jetstream-message-processor';
-export * from './nats-consumer';
-export * from './nats-message-processor';

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

@@ -1,217 +0,0 @@
-import { type ConsumerMessages } from 'nats';
-import { type IdempotencyStore } from '../../domain';
-import type { CloudEventsOptions } from '../../middlewares/cloudevents-middleware';
-/**
- * Stream configuration options
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- *   }
- * })
- * ```
- */
-export 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.*'] },
- *   ]
- * })
- * ```
- */
-export 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`,
- * })
- * ```
- */
-export declare function consumeJetStreamEvents(options: JetStreamConsumerOptions): Promise<ConsumerMessages>;
-/**
- * Options for consuming from multiple JetStream streams
- */
-export 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`,
- * })
- * ```
- */
-export declare function consumeJetStreamStreams(options: JetStreamStreamsConsumerOptions): Promise<ConsumerMessages[]>;
-/**
- * Alias for ensureJetStreamStreams - shorter name
- * @see ensureJetStreamStreams
- */
-export declare const ensureJetStreams: typeof ensureJetStreamStreams;
-/**
- * Alias for consumeJetStreamStreams - shorter name
- * @see consumeJetStreamStreams
- */
-export declare const consumeJetStreams: typeof consumeJetStreamStreams;