@valentine-efagene/qshelter-common 2.0.66 → 2.0.68

package/dist/src/events/workflow-event.service.js

@@ -0,0 +1,660 @@
+/**
+ * Workflow Event Service
+ *
+ * Handles emission and processing of workflow events.
+ * Events are stored in the database and processed by registered handlers.
+ *
+ * Design principles:
+ * 1. Events are immutable once emitted
+ * 2. Handlers are configured by admins, not hardcoded
+ * 3. Each handler execution is logged for audit
+ * 4. Failed handlers can be retried
+ * 5. Events can be correlated for tracing
+ *
+ * Usage:
+ * ```typescript
+ * const eventService = new WorkflowEventService(prisma);
+ *
+ * // Emit an event
+ * const event = await eventService.emit(tenantId, {
+ *   eventType: 'DOCUMENT_UPLOADED',
+ *   payload: {
+ *     contractId: 'ctr_123',
+ *     stepId: 'step_456',
+ *     documentUrl: 'https://...',
+ *   },
+ *   source: 'contract-service',
+ *   actor: { id: 'user_789', type: 'USER' },
+ * });
+ *
+ * // Process the event (run all handlers)
+ * const result = await eventService.processEvent(event.id);
+ * ```
+ */
+import { EventPublisher } from './event-publisher';
+import { NotificationType, NotificationChannel } from './notification-enums';
+/**
+ * Simple in-memory service registry
+ */
+class InMemoryServiceRegistry {
+    services = new Map();
+    get(serviceName) {
+        return this.services.get(serviceName);
+    }
+    register(serviceName, service) {
+        this.services.set(serviceName, service);
+    }
+}
+export class WorkflowEventService {
+    prisma;
+    serviceRegistry;
+    eventPublisher;
+    constructor(prisma, serviceRegistry, eventPublisher) {
+        this.prisma = prisma;
+        this.serviceRegistry = serviceRegistry || new InMemoryServiceRegistry();
+        this.eventPublisher = eventPublisher || new EventPublisher('workflow-event-service');
+    }
+    /**
+     * Register a service for internal event handlers
+     *
+     * Services can be called by INTERNAL handler type configurations.
+     * The service should expose methods that match the handler config.
+     */
+    registerService(name, service) {
+        this.serviceRegistry.register(name, service);
+    }
+    /**
+     * Emit an event
+     *
+     * This creates an event record and optionally processes it immediately
+     * or leaves it for async processing by a worker.
+     *
+     * @param tenantId - Tenant context
+     * @param input - Event details
+     * @param processImmediately - Whether to process handlers now (default: false)
+     */
+    async emit(tenantId, input, processImmediately = false) {
+        // Look up the event type by code
+        const eventType = await this.prisma.eventType.findFirst({
+            where: {
+                tenantId,
+                code: input.eventType.toUpperCase(),
+                enabled: true,
+                channel: { enabled: true },
+            },
+            include: {
+                channel: true,
+            },
+        });
+        if (!eventType) {
+            throw new Error(`Event type '${input.eventType}' not found or not enabled for tenant`);
+        }
+        // TODO: Validate payload against schema if defined
+        // if (eventType.payloadSchema) {
+        //   validateJsonSchema(input.payload, eventType.payloadSchema);
+        // }
+        // Create the event record
+        const event = await this.prisma.workflowEvent.create({
+            data: {
+                tenantId,
+                eventTypeId: eventType.id,
+                payload: input.payload,
+                source: input.source,
+                actorId: input.actor?.id,
+                actorType: input.actor?.type || 'SYSTEM',
+                correlationId: input.correlationId,
+                causationId: input.causationId,
+                status: 'PENDING',
+            },
+            include: {
+                eventType: {
+                    include: { channel: true },
+                },
+            },
+        });
+        const result = {
+            id: event.id,
+            tenantId: event.tenantId,
+            eventTypeId: event.eventTypeId,
+            eventTypeCode: event.eventType.code,
+            channelCode: event.eventType.channel.code,
+            payload: event.payload,
+            source: event.source,
+            actorId: event.actorId,
+            actorType: event.actorType,
+            status: event.status,
+            correlationId: event.correlationId,
+            causationId: event.causationId,
+            error: event.error,
+            processedAt: event.processedAt,
+            createdAt: event.createdAt,
+        };
+        // Process immediately if requested
+        if (processImmediately) {
+            await this.processEvent(event.id);
+        }
+        return result;
+    }
+    /**
+     * Process an event by executing all registered handlers
+     *
+     * This is typically called by a worker/queue processor,
+     * but can also be called synchronously for simple cases.
+     */
+    async processEvent(eventId) {
+        // Fetch the event with its type and handlers
+        const event = await this.prisma.workflowEvent.findUnique({
+            where: { id: eventId },
+            include: {
+                eventType: {
+                    include: {
+                        handlers: {
+                            where: { enabled: true },
+                            orderBy: { priority: 'asc' },
+                        },
+                    },
+                },
+            },
+        });
+        if (!event) {
+            throw new Error(`Event ${eventId} not found`);
+        }
+        // Mark as processing
+        await this.prisma.workflowEvent.update({
+            where: { id: eventId },
+            data: { status: 'PROCESSING' },
+        });
+        const handlers = event.eventType.handlers;
+        const errors = [];
+        let handlersSucceeded = 0;
+        let handlersFailed = 0;
+        // Execute each handler in priority order
+        for (const handler of handlers) {
+            // Check filter condition
+            if (handler.filterCondition) {
+                const shouldRun = this.evaluateFilterCondition(handler.filterCondition, event.payload);
+                if (!shouldRun) {
+                    // Log as skipped
+                    await this.prisma.eventHandlerExecution.create({
+                        data: {
+                            eventId: event.id,
+                            handlerId: handler.id,
+                            status: 'SKIPPED',
+                            input: event.payload,
+                        },
+                    });
+                    continue;
+                }
+            }
+            // Create execution record
+            const execution = await this.prisma.eventHandlerExecution.create({
+                data: {
+                    eventId: event.id,
+                    handlerId: handler.id,
+                    status: 'RUNNING',
+                    input: event.payload,
+                    startedAt: new Date(),
+                },
+            });
+            try {
+                // Execute the handler based on type
+                const output = await this.executeHandler(handler.handlerType, handler.config, event.payload, event.tenantId);
+                // Mark as completed
+                const completedAt = new Date();
+                await this.prisma.eventHandlerExecution.update({
+                    where: { id: execution.id },
+                    data: {
+                        status: 'COMPLETED',
+                        output: output,
+                        completedAt,
+                        durationMs: completedAt.getTime() - execution.startedAt.getTime(),
+                    },
+                });
+                handlersSucceeded++;
+            }
+            catch (error) {
+                // Mark as failed
+                const completedAt = new Date();
+                await this.prisma.eventHandlerExecution.update({
+                    where: { id: execution.id },
+                    data: {
+                        status: 'FAILED',
+                        error: error.message,
+                        errorCode: error.code,
+                        completedAt,
+                        durationMs: completedAt.getTime() - execution.startedAt.getTime(),
+                    },
+                });
+                errors.push({
+                    handlerId: handler.id,
+                    handlerName: handler.name,
+                    error: error.message,
+                });
+                handlersFailed++;
+                // TODO: Implement retry logic based on handler.maxRetries and handler.retryDelayMs
+            }
+        }
+        // Update event status
+        const finalStatus = handlersFailed > 0
+            ? handlersSucceeded > 0
+                ? 'COMPLETED' // Partial success still counts as completed
+                : 'FAILED'
+            : 'COMPLETED';
+        await this.prisma.workflowEvent.update({
+            where: { id: eventId },
+            data: {
+                status: finalStatus,
+                processedAt: new Date(),
+                error: errors.length > 0 ? JSON.stringify(errors) : null,
+            },
+        });
+        return {
+            eventId,
+            status: finalStatus,
+            handlersExecuted: handlers.length,
+            handlersSucceeded,
+            handlersFailed,
+            errors,
+        };
+    }
+    /**
+     * Get pending events for processing (for worker/queue)
+     */
+    async getPendingEvents(tenantId, limit = 100) {
+        const events = await this.prisma.workflowEvent.findMany({
+            where: {
+                status: 'PENDING',
+                ...(tenantId && { tenantId }),
+            },
+            include: {
+                eventType: {
+                    include: { channel: true },
+                },
+            },
+            orderBy: { createdAt: 'asc' },
+            take: limit,
+        });
+        return events.map((event) => ({
+            id: event.id,
+            tenantId: event.tenantId,
+            eventTypeId: event.eventTypeId,
+            eventTypeCode: event.eventType.code,
+            channelCode: event.eventType.channel.code,
+            payload: event.payload,
+            source: event.source,
+            actorId: event.actorId,
+            actorType: event.actorType,
+            status: event.status,
+            correlationId: event.correlationId,
+            causationId: event.causationId,
+            error: event.error,
+            processedAt: event.processedAt,
+            createdAt: event.createdAt,
+        }));
+    }
+    /**
+     * Get events by correlation ID (for tracing related events)
+     */
+    async getEventsByCorrelation(tenantId, correlationId) {
+        const events = await this.prisma.workflowEvent.findMany({
+            where: { tenantId, correlationId },
+            include: {
+                eventType: {
+                    include: { channel: true },
+                },
+            },
+            orderBy: { createdAt: 'asc' },
+        });
+        return events.map((event) => ({
+            id: event.id,
+            tenantId: event.tenantId,
+            eventTypeId: event.eventTypeId,
+            eventTypeCode: event.eventType.code,
+            channelCode: event.eventType.channel.code,
+            payload: event.payload,
+            source: event.source,
+            actorId: event.actorId,
+            actorType: event.actorType,
+            status: event.status,
+            correlationId: event.correlationId,
+            causationId: event.causationId,
+            error: event.error,
+            processedAt: event.processedAt,
+            createdAt: event.createdAt,
+        }));
+    }
+    /**
+     * Get event with executions (for debugging/auditing)
+     */
+    async getEventWithExecutions(tenantId, eventId) {
+        const event = await this.prisma.workflowEvent.findFirst({
+            where: { id: eventId, tenantId },
+            include: {
+                eventType: {
+                    include: { channel: true },
+                },
+                executions: {
+                    include: {
+                        handler: {
+                            select: { id: true, name: true, handlerType: true },
+                        },
+                    },
+                    orderBy: { createdAt: 'asc' },
+                },
+            },
+        });
+        return event;
+    }
+    // ==========================================
+    // HANDLER EXECUTION
+    // ==========================================
+    /**
+     * Execute a handler based on its type
+     */
+    async executeHandler(handlerType, config, payload, tenantId) {
+        switch (handlerType) {
+            case 'INTERNAL':
+                return this.executeInternalHandler(config, payload, tenantId);
+            case 'WEBHOOK':
+                return this.executeWebhookHandler(config, payload);
+            case 'WORKFLOW':
+                return this.executeWorkflowHandler(config, payload, tenantId);
+            case 'NOTIFICATION':
+                return this.executeNotificationHandler(config, payload, tenantId);
+            case 'SNS':
+                return this.executeSnsHandler(config, payload, tenantId);
+            case 'SCRIPT':
+                // TODO: Implement script execution (sandboxed)
+                throw new Error('Script handlers not yet implemented');
+            default:
+                throw new Error(`Unknown handler type: ${handlerType}`);
+        }
+    }
+    /**
+     * Execute an internal service method
+     */
+    async executeInternalHandler(config, payload, tenantId) {
+        // Get the service from the registry
+        const service = this.serviceRegistry.get(config.service);
+        if (!service) {
+            throw new Error(`Service '${config.service}' not found in registry`);
+        }
+        // Get the method
+        const method = service[config.method];
+        if (typeof method !== 'function') {
+            throw new Error(`Method '${config.method}' not found on service '${config.service}'`);
+        }
+        // Transform payload if mapping is defined
+        const transformedPayload = config.payloadMapping
+            ? this.transformPayload(payload, config.payloadMapping)
+            : payload;
+        // Call the method with tenantId and payload
+        return method.call(service, tenantId, transformedPayload);
+    }
+    /**
+     * Execute a webhook handler
+     */
+    async executeWebhookHandler(config, payload) {
+        const transformedPayload = config.payloadMapping
+            ? this.transformPayload(payload, config.payloadMapping)
+            : payload;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), config.timeoutMs || 30000);
+        try {
+            const response = await fetch(config.url, {
+                method: config.method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...config.headers,
+                },
+                body: config.method !== 'GET' ? JSON.stringify(transformedPayload) : undefined,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Webhook returned ${response.status}: ${errorText}`);
+            }
+            // Try to parse JSON response, fall back to empty object
+            try {
+                return await response.json();
+            }
+            catch {
+                return {};
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Execute a workflow handler
+     *
+     * This emits a new event that the workflow service can pick up,
+     * creating loose coupling between event system and workflow engine.
+     */
+    async executeWorkflowHandler(config, payload, tenantId) {
+        // Return the workflow action data
+        // The workflow service should listen for WORKFLOW handler results
+        return {
+            action: config.action,
+            workflowId: config.workflowId,
+            phaseId: config.phaseId,
+            stepId: config.stepId,
+            data: { ...config.data, ...payload },
+            tenantId,
+        };
+    }
+    /**
+     * Execute a notification handler
+     *
+     * This would integrate with a notification service.
+     * Returns what would be sent for logging purposes.
+     */
+    async executeNotificationHandler(config, payload, tenantId) {
+        // TODO: Integrate with actual notification service
+        // For now, return the notification data for logging
+        return {
+            template: config.template,
+            channels: config.channels,
+            recipients: this.resolveRecipients(config.recipients, payload),
+            priority: config.priority || 'normal',
+            data: payload,
+            tenantId,
+        };
+    }
+    /**
+     * Execute an SNS handler
+     *
+     * Publishes to SNS topic using the EventPublisher, which triggers
+     * the notification-service via SNS->SQS subscription.
+     *
+     * The config specifies the notification type, channel, and how to
+     * map the event payload to the notification payload.
+     */
+    async executeSnsHandler(config, payload, tenantId) {
+        // Build the notification payload from config
+        const notificationPayload = this.buildSnsPayload(config, payload);
+        // Map channel string to NotificationChannel enum
+        const channelMap = {
+            email: NotificationChannel.EMAIL,
+            sms: NotificationChannel.SMS,
+            push: NotificationChannel.PUSH,
+        };
+        const channel = channelMap[config.channel] || NotificationChannel.EMAIL;
+        // Validate notification type is a valid enum value
+        const notificationType = config.notificationType;
+        if (!Object.values(NotificationType).includes(notificationType)) {
+            throw new Error(`Invalid notification type: ${config.notificationType}`);
+        }
+        // Publish to SNS via EventPublisher
+        const messageId = await this.eventPublisher.publish(notificationType, channel, notificationPayload, {
+            tenantId,
+            correlationId: payload.correlationId || undefined,
+            userId: payload.userId || payload.actorId || undefined,
+        });
+        return {
+            success: true,
+            messageId,
+            notificationType: config.notificationType,
+            channel: config.channel,
+            payload: notificationPayload,
+            tenantId,
+        };
+    }
+    /**
+     * Build the notification payload for SNS from config and event payload
+     */
+    buildSnsPayload(config, payload) {
+        const result = {};
+        // Apply static payload first
+        if (config.staticPayload) {
+            Object.assign(result, config.staticPayload);
+        }
+        // Apply payload mapping (map from event payload to notification payload)
+        if (config.payloadMapping) {
+            for (const [targetField, sourcePath] of Object.entries(config.payloadMapping)) {
+                const value = this.resolvePath(payload, sourcePath.replace(/^\$\./, ''));
+                if (value !== undefined) {
+                    result[targetField] = value;
+                }
+            }
+        }
+        // If recipientPath is specified, extract the recipient email
+        if (config.recipientPath) {
+            const email = this.resolvePath(payload, config.recipientPath.replace(/^\$\./, ''));
+            if (email && typeof email === 'string') {
+                result.to_email = email;
+            }
+        }
+        return result;
+    }
+    // ==========================================
+    // UTILITY METHODS
+    // ==========================================
+    /**
+     * Evaluate a filter condition against the payload
+     */
+    evaluateFilterCondition(condition, payload) {
+        try {
+            // Simple JSONPath-like evaluation
+            // Supports: $.field == 'value', $.field != 'value', $.field > 10, etc.
+            // Equality: $.field == 'value'
+            const eqMatch = condition.match(/^\$\.(\w+(?:\.\w+)*)\s*==\s*['"](.+)['"]$/);
+            if (eqMatch) {
+                const [, path, value] = eqMatch;
+                return this.resolvePath(payload, path) === value;
+            }
+            // Inequality: $.field != 'value'
+            const neqMatch = condition.match(/^\$\.(\w+(?:\.\w+)*)\s*!=\s*['"](.+)['"]$/);
+            if (neqMatch) {
+                const [, path, value] = neqMatch;
+                return this.resolvePath(payload, path) !== value;
+            }
+            // Numeric comparison: $.field > 10
+            const numMatch = condition.match(/^\$\.(\w+(?:\.\w+)*)\s*([<>=!]+)\s*(\d+(?:\.\d+)?)$/);
+            if (numMatch) {
+                const [, path, op, numStr] = numMatch;
+                const fieldValue = this.resolvePath(payload, path);
+                const num = parseFloat(numStr);
+                if (typeof fieldValue !== 'number')
+                    return false;
+                switch (op) {
+                    case '>':
+                        return fieldValue > num;
+                    case '>=':
+                        return fieldValue >= num;
+                    case '<':
+                        return fieldValue < num;
+                    case '<=':
+                        return fieldValue <= num;
+                    case '==':
+                        return fieldValue === num;
+                    case '!=':
+                        return fieldValue !== num;
+                    default:
+                        return true;
+                }
+            }
+            // Existence check: $.field (truthy check)
+            const existsMatch = condition.match(/^\$\.(\w+(?:\.\w+)*)$/);
+            if (existsMatch) {
+                const [, path] = existsMatch;
+                return !!this.resolvePath(payload, path);
+            }
+            // If we can't parse, run the handler (fail open)
+            return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    /**
+     * Transform payload using a mapping
+     */
+    transformPayload(payload, mapping) {
+        const result = {};
+        for (const [targetKey, sourcePath] of Object.entries(mapping)) {
+            result[targetKey] = this.resolvePath(payload, sourcePath);
+        }
+        return result;
+    }
+    /**
+     * Resolve a dot-notation path in an object
+     */
+    resolvePath(obj, path) {
+        const parts = path.replace(/^\$\./, '').split('.');
+        let current = obj;
+        for (const part of parts) {
+            if (current == null)
+                return undefined;
+            current = current[part];
+        }
+        return current;
+    }
+    /**
+     * Resolve recipients from config, potentially using payload variables
+     */
+    resolveRecipients(recipients, payload) {
+        if (!recipients)
+            return undefined;
+        const resolved = {};
+        // Resolve email recipients
+        if (recipients.email) {
+            resolved.email = recipients.email.map((addr) => {
+                if (addr.startsWith('$.')) {
+                    const value = this.resolvePath(payload, addr);
+                    return typeof value === 'string' ? value : addr;
+                }
+                return addr;
+            });
+        }
+        // Resolve phone recipients
+        if (recipients.phone) {
+            resolved.phone = recipients.phone.map((phone) => {
+                if (phone.startsWith('$.')) {
+                    const value = this.resolvePath(payload, phone);
+                    return typeof value === 'string' ? value : phone;
+                }
+                return phone;
+            });
+        }
+        // Resolve userId recipients
+        if (recipients.userId) {
+            resolved.userId = recipients.userId.map((id) => {
+                if (id.startsWith('$.')) {
+                    const value = this.resolvePath(payload, id);
+                    return typeof value === 'string' ? value : id;
+                }
+                return id;
+            });
+        }
+        return resolved;
+    }
+}
+/**
+ * Create a workflow event service instance
+ */
+export function createWorkflowEventService(prisma, serviceRegistry) {
+    return new WorkflowEventService(prisma, serviceRegistry);
+}