@crossdelta/cloudevents 0.1.1

package/dist/src/domain/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Domain Types
+ *
+ * Core business logic types for handlers, events, and domain operations
+ */
+import type { ZodTypeAny } from 'zod';
+import type { EventContext } from '../adapters/cloudevents/types';
+/**
+ * Event handler interface
+ */
+export interface EventHandler<T = unknown> {
+    handle(payload: T, context?: unknown): Promise<void> | void;
+}
+/**
+ * Constructor type for event handler classes that implement the EventHandler interface
+ */
+export 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
+ */
+export interface EnrichedEvent<T> extends EventContext {
+    data: T;
+}
+/**
+ * Match function type for custom event matching
+ */
+export type MatchFn<T> = (event: EnrichedEvent<T>) => boolean;
+/**
+ * Handler metadata attached to handler constructors
+ */
+export type HandlerMetadata<S extends ZodTypeAny> = {
+    schema: S;
+    declaredType?: string;
+    match?: MatchFn<unknown>;
+    safeParse: boolean;
+};
+/**
+ * Options for creating event handlers
+ */
+export interface HandleEventOptions<S extends ZodTypeAny> {
+    schema: S;
+    type?: string;
+    match?: MatchFn<unknown>;
+    safeParse?: boolean;
+}

package/dist/src/domain/types.js

@@ -0,0 +1,6 @@
+/**
+ * Domain Types
+ *
+ * Core business logic types for handlers, events, and domain operations
+ */
+export {};

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

@@ -0,0 +1,37 @@
+/**
+ * Domain Validation
+ *
+ * Core business logic for validating events, handlers, and schemas
+ * Contains no infrastructure concerns - pure domain logic
+ */
+import type { ZodTypeAny } from 'zod';
+/**
+ * Validation error detail for individual field errors
+ */
+export interface ValidationErrorDetail {
+    code?: string;
+    message: string;
+    path?: (string | number)[];
+    expected?: string;
+    received?: string;
+    validation?: string;
+}
+/**
+ * Handler validation error with handler information
+ */
+export interface HandlerValidationError {
+    handlerName: string;
+    validationErrors: ValidationErrorDetail[];
+}
+/**
+ * Validates whether an exported value is a valid event handler
+ * Checks for either eventarc metadata or a handle method in the prototype
+ */
+export declare function isValidHandler(value: unknown): boolean;
+/**
+ * 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
+ */
+export declare const extractTypeFromSchema: (schema: ZodTypeAny) => string | undefined;

package/dist/src/domain/validation.js

@@ -0,0 +1,53 @@
+/**
+ * Domain Validation
+ *
+ * Core business logic for validating events, handlers, and schemas
+ * Contains no infrastructure concerns - pure domain logic
+ */
+/**
+ * Type guards for schema shape analysis
+ */
+const hasShape = (schema) => 'shape' in schema &&
+    schema.shape !== null &&
+    schema.shape !== undefined &&
+    typeof schema.shape === 'object';
+const hasTypeField = (shape) => 'type' in shape &&
+    shape.type !== null &&
+    shape.type !== undefined &&
+    typeof shape.type === 'object' &&
+    'value' in shape.type;
+const extractTypeValue = (typeField) => typeof typeField.value === 'string' ? typeField.value : undefined;
+/**
+ * Safely extracts type from schema shape
+ */
+const safeExtractType = (schema) => {
+    if (!hasShape(schema))
+        return undefined;
+    if (!hasTypeField(schema.shape))
+        return undefined;
+    return extractTypeValue(schema.shape.type);
+};
+/**
+ * Validates whether an exported value is a valid event handler
+ * Checks for either eventarc metadata or a handle method in the prototype
+ */
+export function isValidHandler(value) {
+    if (typeof value !== 'function')
+        return false;
+    const handler = value;
+    return !!(handler.__eventarcMetadata || handler.prototype?.handle);
+}
+/**
+ * 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
+ */
+export const extractTypeFromSchema = (schema) => {
+    try {
+        return safeExtractType(schema);
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export type { EventContext } from './adapters/cloudevents';
+export { parseEventFromContext } from './adapters/cloudevents';
+export { eventSchema, extractTypeFromSchema, handleEvent } from './domain';
+export { clearHandlerCache, cloudEvents } from './middlewares';
+export * from './publishing';

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { parseEventFromContext } from './adapters/cloudevents';
+export { eventSchema, extractTypeFromSchema, handleEvent } from './domain';
+export { clearHandlerCache, cloudEvents } from './middlewares';
+export * from './publishing';

package/dist/src/infrastructure/errors.d.ts

@@ -0,0 +1,53 @@
+import type { Context } from 'hono';
+import type { HandlerValidationError } from '../domain';
+export type ErrorResponse = {
+    error: {
+        type: string;
+        message: string;
+        timestamp: string;
+        details?: unknown;
+    };
+};
+export type SuccessResponse = {
+    message: string;
+    timestamp: string;
+};
+export type ValidationError = {
+    type: 'ValidationError';
+    eventType: string;
+    message: string;
+    details: HandlerValidationError[];
+};
+export type NoHandlerFoundError = {
+    type: 'NoHandlerFoundError';
+    eventType: string;
+    message: string;
+};
+export type CloudEventParseError = {
+    type: 'CloudEventParseError';
+    message: string;
+    cause?: Error;
+};
+/**
+ * Handles errors with full context logging
+ */
+export declare const handleErrorWithContext: (error: Error, context: Context, additionalInfo?: Record<string, unknown>) => {
+    message: string;
+    stack: string | undefined;
+    url: string;
+    method: string;
+    headers: {
+        [k: string]: string;
+    };
+};
+/**
+ * Converts an error to a standardized response format
+ */
+export declare const errorToResponse: (error: Error, type?: string) => ErrorResponse;
+/**
+ * Creates a standardized error response
+ */
+export declare const createErrorResponse: (type: string, message: string, details?: unknown) => ErrorResponse;
+export declare const createValidationError: (eventType: string, details: HandlerValidationError[]) => ValidationError;
+export declare const createNoHandlerFoundError: (eventType: string) => NoHandlerFoundError;
+export declare const createCloudEventParseError: (message: string, cause?: Error) => CloudEventParseError;

package/dist/src/infrastructure/errors.js

@@ -0,0 +1,54 @@
+// HTTP Response Functions
+/**
+ * Handles errors with full context logging
+ */
+export const handleErrorWithContext = (error, context, additionalInfo) => {
+    const errorInfo = {
+        message: error.message,
+        stack: error.stack,
+        url: context.req.url,
+        method: context.req.method,
+        headers: Object.fromEntries(context.req.raw.headers.entries()),
+        ...additionalInfo,
+    };
+    console.error('[Error Handler]', JSON.stringify(errorInfo, null, 2));
+    return errorInfo;
+};
+/**
+ * Converts an error to a standardized response format
+ */
+export const errorToResponse = (error, type = 'InternalError') => ({
+    error: {
+        type,
+        message: error.message,
+        timestamp: new Date().toISOString(),
+    },
+});
+/**
+ * Creates a standardized error response
+ */
+export const createErrorResponse = (type, message, details) => ({
+    error: {
+        type,
+        message,
+        timestamp: new Date().toISOString(),
+        details,
+    },
+});
+// Application Error Factory Functions
+export const createValidationError = (eventType, details) => ({
+    type: 'ValidationError',
+    eventType,
+    message: `Validation failed for event type: ${eventType}`,
+    details,
+});
+export const createNoHandlerFoundError = (eventType) => ({
+    type: 'NoHandlerFoundError',
+    eventType,
+    message: `No handler found for event type: ${eventType}`,
+});
+export const createCloudEventParseError = (message, cause) => ({
+    type: 'CloudEventParseError',
+    message,
+    cause,
+});

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

@@ -0,0 +1,4 @@
+export type { CloudEventParseError, ErrorResponse, NoHandlerFoundError, SuccessResponse, ValidationError, } from './errors';
+export { createCloudEventParseError, createErrorResponse, createNoHandlerFoundError, createValidationError, errorToResponse, handleErrorWithContext, } from './errors';
+export type { Logger } from './logging';
+export { createLogger, logger } from './logging';

package/dist/src/infrastructure/index.js

@@ -0,0 +1,2 @@
+export { createCloudEventParseError, createErrorResponse, createNoHandlerFoundError, createValidationError, errorToResponse, handleErrorWithContext, } from './errors';
+export { createLogger, logger } from './logging';

package/dist/src/infrastructure/logging.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Logger interface for structured logging
+ */
+export interface Logger {
+    log: (message: string, args?: unknown) => void;
+    info: (message: string, args?: unknown) => void;
+    warn: (message: string, error?: unknown) => void;
+    error: (message: string, error?: unknown) => void;
+    debug: (message: string, args?: unknown) => void;
+}
+/**
+ * Creates a logger with configurable output based on enabled flag
+ */
+export declare const createLogger: (enabled: boolean) => Logger;
+/**
+ * Default logger instance (enabled by default)
+ */
+export declare const logger: Logger;

package/dist/src/infrastructure/logging.js

@@ -0,0 +1,27 @@
+/**
+ * Logging Infrastructure
+ *
+ * Provides structured logging with configurable output levels
+ * and CloudEvents-specific logging utilities
+ */
+const LOG_PREFIX = 'cloudevents';
+/**
+ * Creates a logger with configurable output based on enabled flag
+ */
+export const createLogger = (enabled) => {
+    const logWithArgs = (consoleFn, message, args) => {
+        const formattedMessage = `[${LOG_PREFIX}] ${message}`;
+        args !== undefined ? consoleFn(formattedMessage, args) : consoleFn(formattedMessage);
+    };
+    return {
+        log: (message, args) => enabled && logWithArgs(console.log, message, args),
+        info: (message, args) => enabled && logWithArgs(console.info, message, args),
+        warn: (message, error) => enabled && logWithArgs(console.warn, message, error),
+        error: (message, error) => logWithArgs(console.error, message, error),
+        debug: (message, args) => logWithArgs(console.debug, message, args),
+    };
+};
+/**
+ * Default logger instance (enabled by default)
+ */
+export const logger = createLogger(true);

package/dist/src/middlewares/cloudevents-middleware.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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.
+ */
+import type { Context } from 'hono';
+import type { HandlerConstructor } from '../domain';
+import { clearHandlerCache } from '../processing';
+/**
+ * Configuration options for CloudEvents middleware
+ *
+ * @interface CloudEventsOptions
+ */
+export 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>;
+}
+export { clearHandlerCache };
+/**
+ * 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 declare function cloudEvents(options?: CloudEventsOptions): (ctx: Context, next: () => Promise<void>) => Promise<void | Response>;