@valentine-efagene/qshelter-common 2.0.75 → 2.0.77

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

@@ -0,0 +1,343 @@
+/**
+ * Event Type Seeder
+ *
+ * Utilities for seeding EventChannel, EventType, and EventHandler records.
+ * This allows admins to configure event-driven workflows programmatically.
+ *
+ * Usage:
+ * ```typescript
+ * import { seedContractEventTypes } from '@valentine-efagene/qshelter-common';
+ *
+ * await seedContractEventTypes(prisma, tenantId);
+ * ```
+ */
+/**
+ * Seed event channels
+ */
+export async function seedEventChannels(prisma, tenantId, channels) {
+    for (const channel of channels) {
+        await prisma.eventChannel.upsert({
+            where: {
+                tenantId_code: {
+                    tenantId,
+                    code: channel.code,
+                },
+            },
+            create: {
+                tenantId,
+                code: channel.code,
+                name: channel.name,
+                description: channel.description,
+                enabled: channel.enabled ?? true,
+            },
+            update: {
+                name: channel.name,
+                description: channel.description,
+                enabled: channel.enabled ?? true,
+            },
+        });
+    }
+}
+/**
+ * Seed event types
+ */
+export async function seedEventTypes(prisma, tenantId, eventTypes) {
+    for (const eventType of eventTypes) {
+        // Get the channel
+        const channel = await prisma.eventChannel.findFirst({
+            where: {
+                tenantId,
+                code: eventType.channelCode,
+            },
+        });
+        if (!channel) {
+            throw new Error(`Channel ${eventType.channelCode} not found for tenant ${tenantId}`);
+        }
+        await prisma.eventType.upsert({
+            where: {
+                tenantId_code: {
+                    tenantId,
+                    code: eventType.code,
+                },
+            },
+            create: {
+                tenantId,
+                channelId: channel.id,
+                code: eventType.code,
+                name: eventType.name,
+                description: eventType.description,
+                payloadSchema: eventType.payloadSchema,
+                enabled: eventType.enabled ?? true,
+            },
+            update: {
+                channelId: channel.id,
+                name: eventType.name,
+                description: eventType.description,
+                payloadSchema: eventType.payloadSchema,
+                enabled: eventType.enabled ?? true,
+            },
+        });
+    }
+}
+/**
+ * Seed event handlers
+ */
+export async function seedEventHandlers(prisma, tenantId, handlers) {
+    for (const handler of handlers) {
+        // Get the event type
+        const eventType = await prisma.eventType.findFirst({
+            where: {
+                tenantId,
+                code: handler.eventTypeCode,
+            },
+        });
+        if (!eventType) {
+            throw new Error(`Event type ${handler.eventTypeCode} not found for tenant ${tenantId}`);
+        }
+        // Check if handler already exists
+        const existing = await prisma.eventHandler.findFirst({
+            where: {
+                tenantId,
+                eventTypeId: eventType.id,
+                name: handler.name,
+            },
+        });
+        if (existing) {
+            await prisma.eventHandler.update({
+                where: { id: existing.id },
+                data: {
+                    description: handler.description,
+                    handlerType: handler.handlerType,
+                    config: handler.config,
+                    priority: handler.priority ?? 100,
+                    enabled: handler.enabled ?? true,
+                    maxRetries: handler.maxRetries ?? 3,
+                    retryDelayMs: handler.retryDelayMs ?? 1000,
+                    filterCondition: handler.filterCondition,
+                },
+            });
+        }
+        else {
+            await prisma.eventHandler.create({
+                data: {
+                    tenantId,
+                    eventTypeId: eventType.id,
+                    name: handler.name,
+                    description: handler.description,
+                    handlerType: handler.handlerType,
+                    config: handler.config,
+                    priority: handler.priority ?? 100,
+                    enabled: handler.enabled ?? true,
+                    maxRetries: handler.maxRetries ?? 3,
+                    retryDelayMs: handler.retryDelayMs ?? 1000,
+                    filterCondition: handler.filterCondition,
+                },
+            });
+        }
+    }
+}
+// ============================================================================
+// Contract Event Types (Mortgage Service)
+// ============================================================================
+/**
+ * Contract event channels
+ */
+export const CONTRACT_CHANNELS = [
+    {
+        code: 'CONTRACTS',
+        name: 'Contract Events',
+        description: 'Events related to contract lifecycle (creation, activation, termination)',
+    },
+    {
+        code: 'PAYMENTS',
+        name: 'Payment Events',
+        description: 'Events related to payments and installments',
+    },
+    {
+        code: 'DOCUMENTS',
+        name: 'Document Events',
+        description: 'Events related to document upload, approval, and rejection',
+    },
+    {
+        code: 'WORKFLOW',
+        name: 'Workflow Events',
+        description: 'Events related to workflow steps and phases',
+    },
+];
+/**
+ * Contract event types
+ */
+export const CONTRACT_EVENT_TYPES = [
+    // Contract lifecycle events
+    {
+        code: 'CONTRACT_CREATED',
+        name: 'Contract Created',
+        description: 'Fired when a new contract is created',
+        channelCode: 'CONTRACTS',
+    },
+    {
+        code: 'CONTRACT_ACTIVATED',
+        name: 'Contract Activated',
+        description: 'Fired when a contract is activated',
+        channelCode: 'CONTRACTS',
+    },
+    {
+        code: 'CONTRACT_TERMINATED',
+        name: 'Contract Terminated',
+        description: 'Fired when a contract is terminated',
+        channelCode: 'CONTRACTS',
+    },
+    {
+        code: 'CONTRACT_TERMINATION_REQUESTED',
+        name: 'Contract Termination Requested',
+        description: 'Fired when a contract termination is requested',
+        channelCode: 'CONTRACTS',
+    },
+    {
+        code: 'CONTRACT_TERMINATION_APPROVED',
+        name: 'Contract Termination Approved',
+        description: 'Fired when a contract termination is approved',
+        channelCode: 'CONTRACTS',
+    },
+    // Payment events
+    {
+        code: 'PAYMENT_RECEIVED',
+        name: 'Payment Received',
+        description: 'Fired when a payment is successfully received',
+        channelCode: 'PAYMENTS',
+    },
+    {
+        code: 'PAYMENT_FAILED',
+        name: 'Payment Failed',
+        description: 'Fired when a payment fails',
+        channelCode: 'PAYMENTS',
+    },
+    {
+        code: 'PAYMENT_DUE_REMINDER',
+        name: 'Payment Due Reminder',
+        description: 'Fired to remind buyer of upcoming payment',
+        channelCode: 'PAYMENTS',
+    },
+    {
+        code: 'PAYMENT_OVERDUE',
+        name: 'Payment Overdue',
+        description: 'Fired when a payment is overdue',
+        channelCode: 'PAYMENTS',
+    },
+    // Document events
+    {
+        code: 'DOCUMENT_UPLOADED',
+        name: 'Document Uploaded',
+        description: 'Fired when a document is uploaded',
+        channelCode: 'DOCUMENTS',
+    },
+    {
+        code: 'DOCUMENT_APPROVED',
+        name: 'Document Approved',
+        description: 'Fired when a document is approved',
+        channelCode: 'DOCUMENTS',
+    },
+    {
+        code: 'DOCUMENT_REJECTED',
+        name: 'Document Rejected',
+        description: 'Fired when a document is rejected',
+        channelCode: 'DOCUMENTS',
+    },
+    // Workflow events
+    {
+        code: 'PHASE_ACTIVATED',
+        name: 'Phase Activated',
+        description: 'Fired when a contract phase is activated',
+        channelCode: 'WORKFLOW',
+    },
+    {
+        code: 'PHASE_COMPLETED',
+        name: 'Phase Completed',
+        description: 'Fired when a contract phase is completed',
+        channelCode: 'WORKFLOW',
+    },
+    {
+        code: 'STEP_COMPLETED',
+        name: 'Step Completed',
+        description: 'Fired when a workflow step is completed',
+        channelCode: 'WORKFLOW',
+    },
+    {
+        code: 'STEP_REJECTED',
+        name: 'Step Rejected',
+        description: 'Fired when a workflow step is rejected',
+        channelCode: 'WORKFLOW',
+    },
+];
+/**
+ * Seed all contract event types
+ */
+export async function seedContractEventTypes(prisma, tenantId) {
+    console.log(`Seeding contract event types for tenant ${tenantId}...`);
+    // Seed channels
+    await seedEventChannels(prisma, tenantId, CONTRACT_CHANNELS);
+    console.log(`✓ Seeded ${CONTRACT_CHANNELS.length} event channels`);
+    // Seed event types
+    await seedEventTypes(prisma, tenantId, CONTRACT_EVENT_TYPES);
+    console.log(`✓ Seeded ${CONTRACT_EVENT_TYPES.length} event types`);
+    console.log('✓ Contract event types seeded successfully');
+}
+/**
+ * Seed example email notification handlers
+ *
+ * Note: In production, admins would configure these via the UI.
+ * This is just an example for testing.
+ */
+export async function seedExampleEmailHandlers(prisma, tenantId) {
+    const handlers = [
+        {
+            eventTypeCode: 'CONTRACT_CREATED',
+            name: 'Send Contract Created Email',
+            description: 'Send email notification when contract is created',
+            handlerType: 'SEND_EMAIL',
+            config: {
+                notificationType: 'CONTRACT_CREATED',
+                recipientPath: '$.buyerEmail',
+                templateData: {
+                    contractNumber: '$.contractNumber',
+                    propertyName: '$.propertyName',
+                    totalAmount: '$.totalAmount',
+                },
+            },
+            priority: 100,
+        },
+        {
+            eventTypeCode: 'PAYMENT_RECEIVED',
+            name: 'Send Payment Received Email',
+            description: 'Send email notification when payment is received',
+            handlerType: 'SEND_EMAIL',
+            config: {
+                notificationType: 'PAYMENT_RECEIVED',
+                recipientPath: '$.buyerEmail',
+                templateData: {
+                    contractNumber: '$.contractNumber',
+                    paymentAmount: '$.amount',
+                    paymentReference: '$.reference',
+                },
+            },
+            priority: 100,
+        },
+        {
+            eventTypeCode: 'DOCUMENT_APPROVED',
+            name: 'Send Document Approved Email',
+            description: 'Send email notification when document is approved',
+            handlerType: 'SEND_EMAIL',
+            config: {
+                notificationType: 'DOCUMENT_APPROVED',
+                recipientPath: '$.buyerEmail',
+                templateData: {
+                    documentType: '$.documentType',
+                    stepName: '$.stepName',
+                },
+            },
+            priority: 100,
+        },
+    ];
+    await seedEventHandlers(prisma, tenantId, handlers);
+    console.log(`✓ Seeded ${handlers.length} example email handlers`);
+}

package/dist/src/events/workflow/workflow-event.service.d.ts

@@ -0,0 +1,230 @@
+/**
+ * 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 { PrismaClient } from '../../../generated/client/client';
+import type { EmitEventInput, WorkflowEventData, ProcessEventResult } from './workflow-types';
+import { EventPublisher } from '../notifications/event-publisher';
+/**
+ * Automation registry interface for RUN_AUTOMATION handlers
+ */
+export interface AutomationRegistry {
+    get(automationName: string): ((inputs: Record<string, unknown>, tenantId: string) => Promise<unknown>) | undefined;
+    register(automationName: string, handler: (inputs: Record<string, unknown>, tenantId: string) => Promise<unknown>): void;
+}
+/**
+ * Service registry interface for internal handlers (legacy support)
+ */
+export interface ServiceRegistry {
+    get(serviceName: string): any | undefined;
+    register(serviceName: string, service: any): void;
+}
+export declare class WorkflowEventService {
+    private prisma;
+    private automationRegistry;
+    private eventPublisher;
+    constructor(prisma: PrismaClient, automationRegistry?: AutomationRegistry, eventPublisher?: EventPublisher);
+    /**
+     * Register an automation for RUN_AUTOMATION handlers
+     *
+     * Automations are business logic functions that can be triggered by events.
+     * Example: "calculateLateFee", "sendWelcomePackage", "archiveContract"
+     */
+    registerAutomation(name: string, handler: (inputs: Record<string, unknown>, tenantId: string) => Promise<unknown>): void;
+    /**
+     * 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)
+     */
+    emit(tenantId: string, input: EmitEventInput, processImmediately?: boolean): Promise<WorkflowEventData>;
+    /**
+     * 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.
+     */
+    processEvent(eventId: string): Promise<ProcessEventResult>;
+    /**
+     * Get pending events for processing (for worker/queue)
+     */
+    getPendingEvents(tenantId?: string, limit?: number): Promise<WorkflowEventData[]>;
+    /**
+     * Get events by correlation ID (for tracing related events)
+     */
+    getEventsByCorrelation(tenantId: string, correlationId: string): Promise<WorkflowEventData[]>;
+    /**
+     * Get event with executions (for debugging/auditing)
+     */
+    getEventWithExecutions(tenantId: string, eventId: string): Promise<({
+        eventType: {
+            channel: {
+                name: string;
+                id: string;
+                tenantId: string;
+                createdAt: Date;
+                updatedAt: Date;
+                description: string | null;
+                enabled: boolean;
+                code: string;
+            };
+        } & {
+            name: string;
+            id: string;
+            tenantId: string;
+            createdAt: Date;
+            updatedAt: Date;
+            description: string | null;
+            enabled: boolean;
+            code: string;
+            channelId: string;
+            payloadSchema: import("@prisma/client/runtime/client").JsonValue | null;
+        };
+        executions: ({
+            handler: {
+                name: string;
+                id: string;
+                handlerType: import("./workflow-types").EventHandlerType;
+            };
+        } & {
+            id: string;
+            createdAt: Date;
+            status: import("./workflow-types").ExecutionStatus;
+            handlerId: string;
+            completedAt: Date | null;
+            error: string | null;
+            eventId: string;
+            attempt: number;
+            input: import("@prisma/client/runtime/client").JsonValue | null;
+            output: import("@prisma/client/runtime/client").JsonValue | null;
+            errorCode: string | null;
+            startedAt: Date | null;
+            durationMs: number | null;
+        })[];
+    } & {
+        id: string;
+        tenantId: string;
+        createdAt: Date;
+        status: import("./workflow-types").WorkflowEventStatus;
+        processedAt: Date | null;
+        actorId: string | null;
+        actorType: import("./workflow-types").ActorType;
+        eventTypeId: string;
+        payload: import("@prisma/client/runtime/client").JsonValue;
+        correlationId: string | null;
+        causationId: string | null;
+        source: string;
+        error: string | null;
+    }) | null>;
+    /**
+     * Execute a handler based on its type
+     *
+     * Handler types are business-friendly names that abstract the underlying implementation:
+     * - SEND_EMAIL: Send email via notification service (SNS → SQS → SES)
+     * - SEND_SMS: Send SMS via notification service
+     * - SEND_PUSH: Send push notification via notification service
+     * - CALL_WEBHOOK: Make HTTP request to external URL
+     * - ADVANCE_WORKFLOW: Move workflow steps forward/backward
+     * - RUN_AUTOMATION: Execute registered business logic automation
+     */
+    private executeHandler;
+    /**
+     * Execute SEND_EMAIL handler
+     *
+     * Sends an email via the notification service using SNS → SQS → SES.
+     * Business users configure: template, recipient, and template data.
+     */
+    private executeSendEmailHandler;
+    /**
+     * Execute SEND_SMS handler
+     *
+     * Sends an SMS via the notification service.
+     * Business users configure: template, recipient phone, and template data.
+     */
+    private executeSendSmsHandler;
+    /**
+     * Execute SEND_PUSH handler
+     *
+     * Sends a push notification via the notification service.
+     * Business users configure: template, recipient user, and template data.
+     */
+    private executeSendPushHandler;
+    /**
+     * Build notification payload from config and event payload
+     */
+    private buildNotificationPayload;
+    /**
+     * Execute CALL_WEBHOOK handler
+     *
+     * Makes an HTTP request to an external URL.
+     * Business users configure: URL, method, headers, and body mapping.
+     */
+    private executeCallWebhookHandler;
+    /**
+     * Execute ADVANCE_WORKFLOW handler
+     *
+     * Advances or modifies workflow state.
+     * Business users configure: action (approve/reject/skip), step path, and data.
+     */
+    private executeAdvanceWorkflowHandler;
+    /**
+     * Execute RUN_AUTOMATION handler
+     *
+     * Runs a registered business logic automation.
+     * Business users select from pre-defined automations like
+     * "Calculate Mortgage Payment", "Generate Contract", etc.
+     */
+    private executeRunAutomationHandler;
+    /**
+     * Evaluate a filter condition against the payload
+     */
+    private evaluateFilterCondition;
+    /**
+     * Transform payload using a mapping
+     */
+    private transformPayload;
+    /**
+     * Resolve a dot-notation path in an object
+     */
+    private resolvePath;
+}
+/**
+ * Create a workflow event service instance
+ *
+ * @param prisma - Prisma client for database access
+ * @param automationRegistry - Optional registry of business automations
+ */
+export declare function createWorkflowEventService(prisma: PrismaClient, automationRegistry?: AutomationRegistry): WorkflowEventService;