@valentine-efagene/qshelter-common 2.0.69 → 2.0.72

package/dist/generated/client/models/StepEventAttachment.js

@@ -0,0 +1 @@
+export {};

package/dist/generated/client/models.d.ts

@@ -29,6 +29,7 @@ export type * from './models/PropertyPaymentMethod.js';
 export type * from './models/PropertyPaymentMethodLink.js';
 export type * from './models/PropertyPaymentMethodPhase.js';
 export type * from './models/PaymentMethodPhaseStep.js';
+export type * from './models/StepEventAttachment.js';
 export type * from './models/PaymentMethodPhaseDocument.js';
 export type * from './models/Contract.js';
 export type * from './models/ContractPhase.js';

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

@@ -35,7 +35,14 @@ import { PrismaClient } from '../../generated/client/client';
 import type { EmitEventInput, WorkflowEventData, ProcessEventResult } from './workflow-types';
 import { EventPublisher } from './event-publisher';
 /**
- * Service registry interface for internal handlers
+ * 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;
@@ -43,16 +50,16 @@ export interface ServiceRegistry {
 }
 export declare class WorkflowEventService {
     private prisma;
-    private serviceRegistry;
+    private automationRegistry;
     private eventPublisher;
-    constructor(prisma: PrismaClient, serviceRegistry?: ServiceRegistry, eventPublisher?: EventPublisher);
+    constructor(prisma: PrismaClient, automationRegistry?: AutomationRegistry, eventPublisher?: EventPublisher);
     /**
-     * Register a service for internal event handlers
+     * Register an automation for RUN_AUTOMATION handlers
      *
-     * Services can be called by INTERNAL handler type configurations.
-     * The service should expose methods that match the handler config.
+     * Automations are business logic functions that can be triggered by events.
+     * Example: "calculateLateFee", "sendWelcomePackage", "archiveContract"
      */
-    registerService(name: string, service: any): void;
+    registerAutomation(name: string, handler: (inputs: Record<string, unknown>, tenantId: string) => Promise<unknown>): void;
     /**
      * Emit an event
      *
@@ -116,10 +123,10 @@ export declare class WorkflowEventService {
             id: string;
             createdAt: Date;
             status: import("./workflow-types").ExecutionStatus;
+            handlerId: string;
             completedAt: Date | null;
             error: string | null;
             eventId: string;
-            handlerId: string;
             attempt: number;
             input: import("@prisma/client/runtime/client").JsonValue | null;
             output: import("@prisma/client/runtime/client").JsonValue | null;
@@ -144,44 +151,63 @@ export declare class WorkflowEventService {
     }) | 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 an internal service method
+     * Execute SEND_EMAIL handler
+     *
+     * Sends an email via the notification service using SNS → SQS → SES.
+     * Business users configure: template, recipient, and template data.
      */
-    private executeInternalHandler;
+    private executeSendEmailHandler;
     /**
-     * Execute a webhook handler
+     * Execute SEND_SMS handler
+     *
+     * Sends an SMS via the notification service.
+     * Business users configure: template, recipient phone, and template data.
      */
-    private executeWebhookHandler;
+    private executeSendSmsHandler;
     /**
-     * Execute a workflow handler
+     * Execute SEND_PUSH handler
      *
-     * This emits a new event that the workflow service can pick up,
-     * creating loose coupling between event system and workflow engine.
+     * Sends a push notification via the notification service.
+     * Business users configure: template, recipient user, and template data.
      */
-    private executeWorkflowHandler;
+    private executeSendPushHandler;
     /**
-     * Execute a notification handler
-     *
-     * This would integrate with a notification service.
-     * Returns what would be sent for logging purposes.
+     * Build notification payload from config and event payload
      */
-    private executeNotificationHandler;
+    private buildNotificationPayload;
     /**
-     * Execute an SNS handler
+     * Execute CALL_WEBHOOK handler
      *
-     * Publishes to SNS topic using the EventPublisher, which triggers
-     * the notification-service via SNS->SQS subscription.
+     * Makes an HTTP request to an external URL.
+     * Business users configure: URL, method, headers, and body mapping.
+     */
+    private executeCallWebhookHandler;
+    /**
+     * Execute ADVANCE_WORKFLOW handler
      *
-     * The config specifies the notification type, channel, and how to
-     * map the event payload to the notification payload.
+     * Advances or modifies workflow state.
+     * Business users configure: action (approve/reject/skip), step path, and data.
      */
-    private executeSnsHandler;
+    private executeAdvanceWorkflowHandler;
     /**
-     * Build the notification payload for SNS from config and event payload
+     * 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 buildSnsPayload;
+    private executeRunAutomationHandler;
     /**
      * Evaluate a filter condition against the payload
      */
@@ -194,12 +220,11 @@ export declare class WorkflowEventService {
      * Resolve a dot-notation path in an object
      */
     private resolvePath;
-    /**
-     * Resolve recipients from config, potentially using payload variables
-     */
-    private resolveRecipients;
 }
 /**
  * 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, serviceRegistry?: ServiceRegistry): WorkflowEventService;
+export declare function createWorkflowEventService(prisma: PrismaClient, automationRegistry?: AutomationRegistry): WorkflowEventService;

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

@@ -32,7 +32,19 @@
  * ```
  */
 import { EventPublisher } from './event-publisher';
-import { NotificationType, NotificationChannel } from './notification-enums';
+import { NotificationChannel } from './notification-enums';
+/**
+ * Simple in-memory automation registry
+ */
+class InMemoryAutomationRegistry {
+    automations = new Map();
+    get(automationName) {
+        return this.automations.get(automationName);
+    }
+    register(automationName, handler) {
+        this.automations.set(automationName, handler);
+    }
+}
 /**
  * Simple in-memory service registry
  */
@@ -47,21 +59,21 @@ class InMemoryServiceRegistry {
 }
 export class WorkflowEventService {
     prisma;
-    serviceRegistry;
+    automationRegistry;
     eventPublisher;
-    constructor(prisma, serviceRegistry, eventPublisher) {
+    constructor(prisma, automationRegistry, eventPublisher) {
         this.prisma = prisma;
-        this.serviceRegistry = serviceRegistry || new InMemoryServiceRegistry();
+        this.automationRegistry = automationRegistry || new InMemoryAutomationRegistry();
         this.eventPublisher = eventPublisher || new EventPublisher('workflow-event-service');
     }
     /**
-     * Register a service for internal event handlers
+     * Register an automation for RUN_AUTOMATION handlers
      *
-     * Services can be called by INTERNAL handler type configurations.
-     * The service should expose methods that match the handler config.
+     * Automations are business logic functions that can be triggered by events.
+     * Example: "calculateLateFee", "sendWelcomePackage", "archiveContract"
      */
-    registerService(name, service) {
-        this.serviceRegistry.register(name, service);
+    registerAutomation(name, handler) {
+        this.automationRegistry.register(name, handler);
     }
     /**
      * Emit an event
@@ -350,53 +362,155 @@ export class WorkflowEventService {
     // ==========================================
     /**
      * 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
      */
     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');
+            case 'SEND_EMAIL':
+                return this.executeSendEmailHandler(config, payload, tenantId);
+            case 'SEND_SMS':
+                return this.executeSendSmsHandler(config, payload, tenantId);
+            case 'SEND_PUSH':
+                return this.executeSendPushHandler(config, payload, tenantId);
+            case 'CALL_WEBHOOK':
+                return this.executeCallWebhookHandler(config, payload);
+            case 'ADVANCE_WORKFLOW':
+                return this.executeAdvanceWorkflowHandler(config, payload, tenantId);
+            case 'RUN_AUTOMATION':
+                return this.executeRunAutomationHandler(config, payload, tenantId);
             default:
                 throw new Error(`Unknown handler type: ${handlerType}`);
         }
     }
     /**
-     * Execute an internal service method
+     * Execute SEND_EMAIL handler
+     *
+     * Sends an email via the notification service using SNS → SQS → SES.
+     * Business users configure: template, recipient, and template data.
      */
-    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`);
+    async executeSendEmailHandler(config, payload, tenantId) {
+        // Build the notification payload
+        const notificationPayload = this.buildNotificationPayload(config, payload);
+        // Resolve recipient email from the payload
+        if (config.recipientPath) {
+            const email = this.resolvePath(payload, config.recipientPath.replace(/^\$\./, ''));
+            if (email && typeof email === 'string') {
+                notificationPayload.to_email = email;
+            }
         }
-        // Get the method
-        const method = service[config.method];
-        if (typeof method !== 'function') {
-            throw new Error(`Method '${config.method}' not found on service '${config.service}'`);
+        // Publish to SNS via EventPublisher
+        const messageId = await this.eventPublisher.publish(config.notificationType, NotificationChannel.EMAIL, notificationPayload, {
+            tenantId,
+            correlationId: payload.correlationId || undefined,
+            userId: payload.userId || payload.actorId || undefined,
+        });
+        return {
+            success: true,
+            messageId,
+            notificationType: config.notificationType,
+            channel: 'email',
+            payload: notificationPayload,
+            tenantId,
+        };
+    }
+    /**
+     * Execute SEND_SMS handler
+     *
+     * Sends an SMS via the notification service.
+     * Business users configure: template, recipient phone, and template data.
+     */
+    async executeSendSmsHandler(config, payload, tenantId) {
+        // Build the notification payload
+        const notificationPayload = this.buildNotificationPayload(config, payload);
+        // Resolve recipient phone from the payload
+        if (config.recipientPath) {
+            const phone = this.resolvePath(payload, config.recipientPath.replace(/^\$\./, ''));
+            if (phone && typeof phone === 'string') {
+                notificationPayload.to_phone = phone;
+            }
         }
-        // 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);
+        // Publish to SNS via EventPublisher
+        const messageId = await this.eventPublisher.publish(config.notificationType, NotificationChannel.SMS, notificationPayload, {
+            tenantId,
+            correlationId: payload.correlationId || undefined,
+            userId: payload.userId || payload.actorId || undefined,
+        });
+        return {
+            success: true,
+            messageId,
+            notificationType: config.notificationType,
+            channel: 'sms',
+            payload: notificationPayload,
+            tenantId,
+        };
+    }
+    /**
+     * Execute SEND_PUSH handler
+     *
+     * Sends a push notification via the notification service.
+     * Business users configure: template, recipient user, and template data.
+     */
+    async executeSendPushHandler(config, payload, tenantId) {
+        // Build the notification payload
+        const notificationPayload = this.buildNotificationPayload(config, payload);
+        // Resolve recipient user ID from the payload
+        if (config.recipientPath) {
+            const userId = this.resolvePath(payload, config.recipientPath.replace(/^\$\./, ''));
+            if (userId && typeof userId === 'string') {
+                notificationPayload.to_user_id = userId;
+            }
+        }
+        // Publish to SNS via EventPublisher
+        const messageId = await this.eventPublisher.publish(config.notificationType, NotificationChannel.PUSH, notificationPayload, {
+            tenantId,
+            correlationId: payload.correlationId || undefined,
+            userId: payload.userId || payload.actorId || undefined,
+        });
+        return {
+            success: true,
+            messageId,
+            notificationType: config.notificationType,
+            channel: 'push',
+            payload: notificationPayload,
+            tenantId,
+        };
+    }
+    /**
+     * Build notification payload from config and event payload
+     */
+    buildNotificationPayload(config, payload) {
+        const result = {};
+        // Apply static template data first
+        if (config.staticData) {
+            Object.assign(result, config.staticData);
+        }
+        // Apply template data mapping (map from event payload to notification payload)
+        if (config.templateData) {
+            for (const [targetField, sourcePath] of Object.entries(config.templateData)) {
+                const value = this.resolvePath(payload, sourcePath.replace(/^\$\./, ''));
+                if (value !== undefined) {
+                    result[targetField] = value;
+                }
+            }
+        }
+        return result;
     }
     /**
-     * Execute a webhook handler
+     * Execute CALL_WEBHOOK handler
+     *
+     * Makes an HTTP request to an external URL.
+     * Business users configure: URL, method, headers, and body mapping.
      */
-    async executeWebhookHandler(config, payload) {
-        const transformedPayload = config.payloadMapping
-            ? this.transformPayload(payload, config.payloadMapping)
+    async executeCallWebhookHandler(config, payload) {
+        const transformedPayload = config.bodyMapping
+            ? this.transformPayload(payload, config.bodyMapping)
             : payload;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), config.timeoutMs || 30000);
@@ -428,106 +542,50 @@ export class WorkflowEventService {
         }
     }
     /**
-     * Execute a workflow handler
+     * Execute ADVANCE_WORKFLOW handler
      *
-     * This emits a new event that the workflow service can pick up,
-     * creating loose coupling between event system and workflow engine.
+     * Advances or modifies workflow state.
+     * Business users configure: action (approve/reject/skip), step path, and data.
      */
-    async executeWorkflowHandler(config, payload, tenantId) {
+    async executeAdvanceWorkflowHandler(config, payload, tenantId) {
+        // Resolve step ID from payload if path is provided
+        let stepId = config.stepId;
+        if (config.stepIdPath) {
+            const resolved = this.resolvePath(payload, config.stepIdPath.replace(/^\$\./, ''));
+            if (resolved && typeof resolved === 'string') {
+                stepId = resolved;
+            }
+        }
         // Return the workflow action data
-        // The workflow service should listen for WORKFLOW handler results
+        // The workflow service should listen for ADVANCE_WORKFLOW handler results
         return {
             action: config.action,
             workflowId: config.workflowId,
             phaseId: config.phaseId,
-            stepId: config.stepId,
+            stepId,
             data: { ...config.data, ...payload },
             tenantId,
         };
     }
     /**
-     * Execute a notification handler
+     * Execute RUN_AUTOMATION handler
      *
-     * This would integrate with a notification service.
-     * Returns what would be sent for logging purposes.
+     * Runs a registered business logic automation.
+     * Business users select from pre-defined automations like
+     * "Calculate Mortgage Payment", "Generate Contract", etc.
      */
-    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}`);
+    async executeRunAutomationHandler(config, payload, tenantId) {
+        // Get the automation function from the registry
+        const automationFn = this.automationRegistry.get(config.automation);
+        if (!automationFn) {
+            throw new Error(`Automation '${config.automation}' not found in registry`);
         }
-        // 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;
+        // Transform payload if mapping is defined
+        const transformedPayload = config.inputMapping
+            ? this.transformPayload(payload, config.inputMapping)
+            : payload;
+        // Call the automation function with inputs and tenantId
+        return automationFn(transformedPayload, tenantId);
     }
     // ==========================================
     // UTILITY METHODS
@@ -612,49 +670,13 @@ export class WorkflowEventService {
         }
         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
+ *
+ * @param prisma - Prisma client for database access
+ * @param automationRegistry - Optional registry of business automations
  */
-export function createWorkflowEventService(prisma, serviceRegistry) {
-    return new WorkflowEventService(prisma, serviceRegistry);
+export function createWorkflowEventService(prisma, automationRegistry) {
+    return new WorkflowEventService(prisma, automationRegistry);
 }