@valentine-efagene/qshelter-common 2.0.69 → 2.0.72

package/dist/src/events/workflow-types.d.ts

@@ -7,121 +7,162 @@
  * Architecture:
  * 1. EventChannel - Logical grouping of events (e.g., "CONTRACTS", "PAYMENTS")
  * 2. EventType - Specific event types (e.g., "DOCUMENT_UPLOADED", "STEP_COMPLETED")
- * 3. EventHandler - What to do when an event fires (webhook, internal call, etc.)
+ * 3. EventHandler - What to do when an event fires (send email, call webhook, etc.)
  * 4. WorkflowEvent - Actual event instances (audit log)
  * 5. EventHandlerExecution - Log of handler executions
+ *
+ * Handler types are business-friendly so non-technical admins can configure them:
+ * - SEND_EMAIL: Send an email to someone
+ * - SEND_SMS: Send a text message
+ * - SEND_PUSH: Send a push notification
+ * - CALL_WEBHOOK: Call an external API
+ * - ADVANCE_WORKFLOW: Move workflow forward
+ * - RUN_AUTOMATION: Execute business logic
  */
 export type { EventHandlerType, ActorType, WorkflowEventStatus, ExecutionStatus, } from '../../generated/client/enums';
 /**
- * Configuration for INTERNAL handler type
- * Calls an internal service method
+ * Configuration for SEND_EMAIL handler type
+ * Sends an email notification to specified recipients
  */
-export interface InternalHandlerConfig {
-    type: 'INTERNAL';
-    /** Service name (e.g., "contract", "payment") */
-    service: string;
-    /** Method to call on the service */
-    method: string;
-    /** Optional payload transformation (JSONPath mapping) */
-    payloadMapping?: Record<string, string>;
+export interface SendEmailHandlerConfig {
+    type: 'SEND_EMAIL';
+    /** Email template name (e.g., "documentApproved", "paymentReminder") */
+    template: string;
+    /**
+     * Notification type for the notification service.
+     * This maps to templates in the notification service.
+     */
+    notificationType: string;
+    /**
+     * Who to send the email to. Use JSONPath to extract from event payload.
+     * Examples: "$.buyer.email", "$.user.email"
+     */
+    recipientPath: string;
+    /**
+     * Map event payload fields to template variables
+     * Example: { "userName": "$.buyer.firstName", "amount": "$.payment.amount" }
+     */
+    templateData?: Record<string, string>;
+    /** Static data to always include in template */
+    staticData?: Record<string, unknown>;
+    /** Priority level */
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
 }
 /**
- * Configuration for WEBHOOK handler type
- * Sends HTTP request to external URL
+ * Configuration for SEND_SMS handler type
+ * Sends an SMS text message
  */
-export interface WebhookHandlerConfig {
-    type: 'WEBHOOK';
-    /** Target URL */
-    url: string;
-    /** HTTP method */
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /** Optional headers */
-    headers?: Record<string, string>;
-    /** Optional payload transformation */
-    payloadMapping?: Record<string, string>;
-    /** Timeout in milliseconds */
-    timeoutMs?: number;
-    /** Whether to include event metadata in request */
-    includeMetadata?: boolean;
+export interface SendSmsHandlerConfig {
+    type: 'SEND_SMS';
+    /** SMS template name */
+    template: string;
+    /**
+     * Notification type for the notification service.
+     */
+    notificationType: string;
+    /**
+     * Phone number path in event payload
+     * Example: "$.buyer.phone"
+     */
+    recipientPath: string;
+    /** Map event payload fields to template variables */
+    templateData?: Record<string, string>;
+    /** Static data to always include in template */
+    staticData?: Record<string, unknown>;
 }
 /**
- * Configuration for WORKFLOW handler type
- * Triggers or advances a workflow
+ * Configuration for SEND_PUSH handler type
+ * Sends a push notification to user's device
  */
-export interface WorkflowHandlerConfig {
-    type: 'WORKFLOW';
-    /** Target workflow/phase ID */
-    workflowId?: string;
-    phaseId?: string;
-    stepId?: string;
-    /** Action to perform */
-    action: 'start' | 'advance' | 'complete' | 'fail' | 'skip';
-    /** Optional data to pass */
-    data?: Record<string, unknown>;
+export interface SendPushHandlerConfig {
+    type: 'SEND_PUSH';
+    /** Push notification title */
+    title: string;
+    /** Push notification body (can use {{variables}}) */
+    body: string;
+    /**
+     * Notification type for the notification service.
+     */
+    notificationType: string;
+    /**
+     * User ID path in event payload (to find their device)
+     * Example: "$.buyer.id"
+     */
+    recipientPath: string;
+    /** Deep link to open in app */
+    deepLink?: string;
+    /** Map event payload fields to notification variables */
+    templateData?: Record<string, string>;
+    /** Static data to always include in notification */
+    staticData?: Record<string, unknown>;
 }
 /**
- * Configuration for NOTIFICATION handler type
- * Sends notifications via various channels (internal handling)
+ * Configuration for CALL_WEBHOOK handler type
+ * Calls an external API endpoint
  */
-export interface NotificationHandlerConfig {
-    type: 'NOTIFICATION';
-    /** Notification template ID or inline template */
-    template: string;
-    /** Channels to send through */
-    channels: ('email' | 'sms' | 'push' | 'in_app')[];
-    /** Recipients (can use payload variables like $.user.email) */
-    recipients?: {
-        email?: string[];
-        phone?: string[];
-        userId?: string[];
-    };
-    /** Priority */
-    priority?: 'low' | 'normal' | 'high' | 'urgent';
+export interface CallWebhookHandlerConfig {
+    type: 'CALL_WEBHOOK';
+    /** The URL to call */
+    url: string;
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Optional headers to include */
+    headers?: Record<string, string>;
+    /**
+     * Map event payload fields to request body
+     * Example: { "orderId": "$.contract.id", "status": "$.status" }
+     */
+    bodyMapping?: Record<string, string>;
+    /** Timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
 }
 /**
- * Configuration for SNS handler type
- * Publishes to SNS topic, which triggers the notification-service via SQS
- * Uses the NotificationEvent format expected by notification-service
+ * Configuration for ADVANCE_WORKFLOW handler type
+ * Advances or modifies a workflow step
  */
-export interface SnsHandlerConfig {
-    type: 'SNS';
-    /** SNS Topic ARN (optional - defaults to notifications topic) */
-    topicArn?: string;
-    /** Notification type (from NotificationType enum) */
-    notificationType: string;
-    /** Notification channel (email, sms, push) */
-    channel: 'email' | 'sms' | 'push';
-    /**
-     * Payload mapping - maps event payload to notification payload
-     * Uses JSONPath-like expressions (e.g., $.user.email -> to_email)
-     */
-    payloadMapping?: Record<string, string>;
+export interface AdvanceWorkflowHandlerConfig {
+    type: 'ADVANCE_WORKFLOW';
+    /** What action to take */
+    action: 'complete_step' | 'skip_step' | 'fail_step' | 'activate_phase';
     /**
-     * Static payload fields to merge with mapped payload
+     * Step ID path in event payload (if action targets a specific step)
+     * Example: "$.stepId"
      */
-    staticPayload?: Record<string, unknown>;
+    stepIdPath?: string;
     /**
-     * Email recipient field path in the event payload (e.g., $.user.email)
+     * Phase ID path in event payload (if action targets a phase)
+     * Example: "$.phaseId"
      */
-    recipientPath?: string;
+    phaseIdPath?: string;
+    /** Static step ID (if not using path) */
+    stepId?: string;
+    /** Static workflow ID */
+    workflowId?: string;
+    /** Static phase ID */
+    phaseId?: string;
+    /** Additional data to pass to the action */
+    data?: Record<string, unknown>;
+    /** Reason to record for the action */
+    reason?: string;
 }
 /**
- * Configuration for SCRIPT handler type
- * Executes custom logic
+ * Configuration for RUN_AUTOMATION handler type
+ * Executes internal business logic
  */
-export interface ScriptHandlerConfig {
-    type: 'SCRIPT';
-    /** Script language */
-    language: 'jsonata' | 'javascript';
-    /** The script/expression to execute */
-    script: string;
-    /** Timeout in milliseconds */
-    timeoutMs?: number;
+export interface RunAutomationHandlerConfig {
+    type: 'RUN_AUTOMATION';
+    /** The automation to run (registered automation name) */
+    automation: string;
+    /**
+     * Map event payload fields to automation inputs
+     * Example: { "contractId": "$.contract.id", "amount": "$.payment.amount" }
+     */
+    inputMapping?: Record<string, string>;
 }
 /**
  * Union type for all handler configurations
  */
-export type HandlerConfig = InternalHandlerConfig | WebhookHandlerConfig | WorkflowHandlerConfig | NotificationHandlerConfig | SnsHandlerConfig | ScriptHandlerConfig;
+export type HandlerConfig = SendEmailHandlerConfig | SendSmsHandlerConfig | SendPushHandlerConfig | CallWebhookHandlerConfig | AdvanceWorkflowHandlerConfig | RunAutomationHandlerConfig;
 /**
  * Input for emitting an event
  */
@@ -216,12 +257,20 @@ export interface UpdateEventTypeInput {
 }
 /**
  * Input for creating an event handler
+ *
+ * Handler types are business-friendly names:
+ * - SEND_EMAIL: Send email notification
+ * - SEND_SMS: Send SMS text message
+ * - SEND_PUSH: Send push notification
+ * - CALL_WEBHOOK: Call external API
+ * - ADVANCE_WORKFLOW: Move workflow forward
+ * - RUN_AUTOMATION: Execute business logic
  */
 export interface CreateEventHandlerInput {
     eventTypeId: string;
     name: string;
     description?: string;
-    handlerType: 'INTERNAL' | 'WEBHOOK' | 'WORKFLOW' | 'NOTIFICATION' | 'SCRIPT';
+    handlerType: 'SEND_EMAIL' | 'SEND_SMS' | 'SEND_PUSH' | 'CALL_WEBHOOK' | 'ADVANCE_WORKFLOW' | 'RUN_AUTOMATION';
     config: HandlerConfig;
     priority?: number;
     enabled?: boolean;

package/dist/src/events/workflow-types.js

@@ -7,8 +7,16 @@
  * Architecture:
  * 1. EventChannel - Logical grouping of events (e.g., "CONTRACTS", "PAYMENTS")
  * 2. EventType - Specific event types (e.g., "DOCUMENT_UPLOADED", "STEP_COMPLETED")
- * 3. EventHandler - What to do when an event fires (webhook, internal call, etc.)
+ * 3. EventHandler - What to do when an event fires (send email, call webhook, etc.)
  * 4. WorkflowEvent - Actual event instances (audit log)
  * 5. EventHandlerExecution - Log of handler executions
+ *
+ * Handler types are business-friendly so non-technical admins can configure them:
+ * - SEND_EMAIL: Send an email to someone
+ * - SEND_SMS: Send a text message
+ * - SEND_PUSH: Send a push notification
+ * - CALL_WEBHOOK: Call an external API
+ * - ADVANCE_WORKFLOW: Move workflow forward
+ * - RUN_AUTOMATION: Execute business logic
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.69",
+  "version": "2.0.72",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/prisma/migrations/20260106003757_business_friendly_handler_types/migration.sql

@@ -0,0 +1,28 @@
+/*
+  Warnings:
+
+  - The values [INTERNAL,WEBHOOK,WORKFLOW,NOTIFICATION,SNS,SCRIPT] on the enum `event_handlers_handlerType` will be removed. If these variants are still used in the database, this will fail.
+
+*/
+
+-- First, migrate existing data to new enum values
+-- INTERNAL -> RUN_AUTOMATION (internal service calls are now automations)
+-- WEBHOOK -> CALL_WEBHOOK (external API calls)
+-- WORKFLOW -> ADVANCE_WORKFLOW (workflow state changes)
+-- NOTIFICATION -> SEND_EMAIL (general notifications default to email)
+-- SNS -> SEND_EMAIL (SNS was for email notifications)
+-- SCRIPT -> RUN_AUTOMATION (custom scripts are automations)
+
+-- Add new enum values first (MySQL requires this approach)
+ALTER TABLE `event_handlers` MODIFY `handlerType` ENUM('INTERNAL', 'WEBHOOK', 'WORKFLOW', 'NOTIFICATION', 'SNS', 'SCRIPT', 'SEND_EMAIL', 'SEND_SMS', 'SEND_PUSH', 'CALL_WEBHOOK', 'ADVANCE_WORKFLOW', 'RUN_AUTOMATION') NOT NULL;
+
+-- Migrate data
+UPDATE `event_handlers` SET `handlerType` = 'RUN_AUTOMATION' WHERE `handlerType` = 'INTERNAL';
+UPDATE `event_handlers` SET `handlerType` = 'CALL_WEBHOOK' WHERE `handlerType` = 'WEBHOOK';
+UPDATE `event_handlers` SET `handlerType` = 'ADVANCE_WORKFLOW' WHERE `handlerType` = 'WORKFLOW';
+UPDATE `event_handlers` SET `handlerType` = 'SEND_EMAIL' WHERE `handlerType` = 'NOTIFICATION';
+UPDATE `event_handlers` SET `handlerType` = 'SEND_EMAIL' WHERE `handlerType` = 'SNS';
+UPDATE `event_handlers` SET `handlerType` = 'RUN_AUTOMATION' WHERE `handlerType` = 'SCRIPT';
+
+-- Now remove old enum values
+ALTER TABLE `event_handlers` MODIFY `handlerType` ENUM('SEND_EMAIL', 'SEND_SMS', 'SEND_PUSH', 'CALL_WEBHOOK', 'ADVANCE_WORKFLOW', 'RUN_AUTOMATION') NOT NULL;

package/prisma/schema.prisma

@@ -84,6 +84,15 @@ enum StepStatus {
   AWAITING_REVIEW // Submitted, waiting for admin/system review
 }
 
+/// When a step event attachment should trigger
+enum StepTrigger {
+  ON_COMPLETE // When step is approved/completed
+  ON_REJECT // When step is rejected
+  ON_SUBMIT // When step is submitted for review
+  ON_RESUBMIT // When step is resubmitted after rejection
+  ON_START // When step transitions to IN_PROGRESS
+}
+
 enum InstallmentStatus {
   PENDING
   PAID
@@ -190,13 +199,14 @@ enum OfferLetterStatus {
 // =============================================================================
 
 /// Handler Type - What kind of action the handler performs
+/// These are business-friendly names that admins can understand
 enum EventHandlerType {
-  INTERNAL     // Call an internal service method
-  WEBHOOK      // Send a webhook to an external URL
-  WORKFLOW     // Trigger or advance a workflow
-  NOTIFICATION // Send a notification (email, SMS, push) - internal
-  SNS          // Publish to SNS topic (for notification-service)
-  SCRIPT       // Execute a custom script/expression
+  SEND_EMAIL       // Send an email notification to recipient(s)
+  SEND_SMS         // Send an SMS text message
+  SEND_PUSH        // Send a push notification
+  CALL_WEBHOOK     // Call an external API/webhook
+  ADVANCE_WORKFLOW // Advance or complete a workflow step
+  RUN_AUTOMATION   // Execute internal business logic
 }
 
 /// Actor Type - Who triggered an event
@@ -946,10 +956,42 @@ model PaymentMethodPhaseStep {
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
+  // Event attachments - handlers that fire on step transitions
+  eventAttachments StepEventAttachment[]
+
   @@index([phaseId])
   @@map("payment_method_phase_steps")
 }
 
+/// Step Event Attachment - Links event handlers to step template triggers
+/// When a step transitions (complete, reject, etc.), attached handlers fire
+model StepEventAttachment {
+  id     String @id @default(cuid())
+  stepId String
+  step   PaymentMethodPhaseStep @relation(fields: [stepId], references: [id], onDelete: Cascade)
+
+  /// When this handler should fire
+  trigger StepTrigger
+
+  /// The event handler to execute
+  handlerId String
+  handler   EventHandler @relation(fields: [handlerId], references: [id], onDelete: Cascade)
+
+  /// Order of execution (lower = first)
+  priority Int @default(100)
+
+  /// Whether this attachment is active
+  enabled Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([stepId, handlerId, trigger])
+  @@index([stepId])
+  @@index([handlerId])
+  @@map("step_event_attachments")
+}
+
 // Required document within a DOCUMENTATION phase
 model PaymentMethodPhaseDocument {
   id      String                     @id @default(cuid())
@@ -1788,6 +1830,9 @@ model EventHandler {
   /// Handler execution logs
   executions EventHandlerExecution[]
 
+  /// Step attachments - steps that have attached this handler
+  stepAttachments StepEventAttachment[]
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt