@valentine-efagene/qshelter-common 2.0.74 → 2.0.76

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

@@ -0,0 +1,364 @@
+/**
+ * Event-Driven Workflow Types
+ *
+ * These types define the structure for a configurable event system
+ * where admins can define event types, channels, and handlers.
+ *
+ * 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 (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 SEND_EMAIL handler type
+ * Sends an email notification to specified recipients
+ */
+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 SEND_SMS handler type
+ * Sends an SMS text message
+ */
+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 SEND_PUSH handler type
+ * Sends a push notification to user's device
+ */
+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 CALL_WEBHOOK handler type
+ * Calls an external API endpoint
+ */
+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 ADVANCE_WORKFLOW handler type
+ * Advances or modifies a workflow step
+ */
+export interface AdvanceWorkflowHandlerConfig {
+    type: 'ADVANCE_WORKFLOW';
+    /** What action to take */
+    action: 'complete_step' | 'skip_step' | 'fail_step' | 'activate_phase';
+    /**
+     * Step ID path in event payload (if action targets a specific step)
+     * Example: "$.stepId"
+     */
+    stepIdPath?: string;
+    /**
+     * Phase ID path in event payload (if action targets a phase)
+     * Example: "$.phaseId"
+     */
+    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 RUN_AUTOMATION handler type
+ * Executes internal business logic
+ */
+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 = SendEmailHandlerConfig | SendSmsHandlerConfig | SendPushHandlerConfig | CallWebhookHandlerConfig | AdvanceWorkflowHandlerConfig | RunAutomationHandlerConfig;
+/**
+ * Input for emitting an event
+ */
+export interface EmitEventInput {
+    /** Event type code (e.g., "DOCUMENT_UPLOADED") */
+    eventType: string;
+    /** Event payload */
+    payload: Record<string, unknown>;
+    /** Source of the event (service name) */
+    source: string;
+    /** Actor information */
+    actor?: {
+        id: string;
+        type: 'USER' | 'API_KEY' | 'SYSTEM' | 'WEBHOOK';
+    };
+    /** Correlation ID for tracing related events */
+    correlationId?: string;
+    /** Causation ID (which event caused this one) */
+    causationId?: string;
+}
+/**
+ * Event with full metadata (returned from queries)
+ */
+export interface WorkflowEventData {
+    id: string;
+    tenantId: string;
+    eventTypeId: string;
+    eventTypeCode: string;
+    channelCode: string;
+    payload: Record<string, unknown>;
+    source: string;
+    actorId: string | null;
+    actorType: 'USER' | 'API_KEY' | 'SYSTEM' | 'WEBHOOK';
+    status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'SKIPPED';
+    correlationId: string | null;
+    causationId: string | null;
+    error: string | null;
+    processedAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Result of processing an event
+ */
+export interface ProcessEventResult {
+    eventId: string;
+    status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'SKIPPED';
+    handlersExecuted: number;
+    handlersSucceeded: number;
+    handlersFailed: number;
+    errors: Array<{
+        handlerId: string;
+        handlerName: string;
+        error: string;
+    }>;
+}
+/**
+ * Input for creating an event channel
+ */
+export interface CreateEventChannelInput {
+    code: string;
+    name: string;
+    description?: string;
+    enabled?: boolean;
+}
+/**
+ * Input for updating an event channel
+ */
+export interface UpdateEventChannelInput {
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+}
+/**
+ * Input for creating an event type
+ */
+export interface CreateEventTypeInput {
+    channelId: string;
+    code: string;
+    name: string;
+    description?: string;
+    payloadSchema?: Record<string, unknown>;
+    enabled?: boolean;
+}
+/**
+ * Input for updating an event type
+ */
+export interface UpdateEventTypeInput {
+    name?: string;
+    description?: string;
+    payloadSchema?: Record<string, unknown>;
+    enabled?: boolean;
+}
+/**
+ * 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: 'SEND_EMAIL' | 'SEND_SMS' | 'SEND_PUSH' | 'CALL_WEBHOOK' | 'ADVANCE_WORKFLOW' | 'RUN_AUTOMATION';
+    config: HandlerConfig;
+    priority?: number;
+    enabled?: boolean;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    filterCondition?: string;
+}
+/**
+ * Input for updating an event handler
+ */
+export interface UpdateEventHandlerInput {
+    name?: string;
+    description?: string;
+    config?: HandlerConfig;
+    priority?: number;
+    enabled?: boolean;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    filterCondition?: string;
+}
+/**
+ * Event channel with related data
+ */
+export interface EventChannelWithTypes {
+    id: string;
+    tenantId: string;
+    code: string;
+    name: string;
+    description: string | null;
+    enabled: boolean;
+    eventTypes: Array<{
+        id: string;
+        code: string;
+        name: string;
+        enabled: boolean;
+    }>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Event type with related data
+ */
+export interface EventTypeWithHandlers {
+    id: string;
+    tenantId: string;
+    channelId: string;
+    channel: {
+        code: string;
+        name: string;
+    };
+    code: string;
+    name: string;
+    description: string | null;
+    payloadSchema: Record<string, unknown> | null;
+    enabled: boolean;
+    handlers: Array<{
+        id: string;
+        name: string;
+        handlerType: string;
+        enabled: boolean;
+    }>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Event handler with related data
+ */
+export interface EventHandlerWithType {
+    id: string;
+    tenantId: string;
+    eventTypeId: string;
+    eventType: {
+        code: string;
+        name: string;
+        channel: {
+            code: string;
+            name: string;
+        };
+    };
+    name: string;
+    description: string | null;
+    handlerType: string;
+    config: HandlerConfig;
+    priority: number;
+    enabled: boolean;
+    maxRetries: number;
+    retryDelayMs: number;
+    filterCondition: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Event-Driven Workflow Types
+ *
+ * These types define the structure for a configurable event system
+ * where admins can define event types, channels, and handlers.
+ *
+ * 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 (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.74",
+  "version": "2.0.76",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -29,11 +29,14 @@
   ],
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.962.0",
+    "@aws-sdk/client-eventbridge": "^3.700.0",
     "@aws-sdk/client-secrets-manager": "^3.500.0",
     "@aws-sdk/client-sns": "^3.500.0",
+    "@aws-sdk/client-sqs": "^3.700.0",
     "@aws-sdk/client-ssm": "^3.500.0",
     "@aws-sdk/util-dynamodb": "^3.962.0",
     "@prisma/client": "^7.0.0",
+    "axios": "^1.13.2",
     "dotenv": "^17.2.3",
     "prisma": "^7.0.0"
   },

package/prisma/schema.prisma

@@ -211,12 +211,12 @@ enum OfferLetterStatus {
 /// Handler Type - What kind of action the handler performs
 /// These are business-friendly names that admins can understand
 enum EventHandlerType {
-  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
+  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
+  RUN_AUTOMATION // Execute internal business logic
 }
 
 /// Actor Type - Who triggered an event
@@ -430,33 +430,33 @@ model Tenant {
 // =============================================================================
 
 model ApiKey {
-  id          String    @id @default(cuid())
-  tenantId    String
-  tenant      Tenant    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
 
   // Identification
-  name        String                // Human-readable name (e.g., "Paystack Integration")
-  description String?   @db.Text    // Optional description
-  provider    String                // Partner/vendor name (e.g., "paystack", "flutterwave")
+  name        String // Human-readable name (e.g., "Paystack Integration")
+  description String? @db.Text // Optional description
+  provider    String // Partner/vendor name (e.g., "paystack", "flutterwave")
 
   // Secret management (NEVER store raw secret in DB)
-  secretRef   String                // AWS Secrets Manager ARN or name
+  secretRef String // AWS Secrets Manager ARN or name
 
   // Permissions - scopes this API key is allowed to request
   // Examples: ["contract:read", "payment:*", "property:read"]
-  scopes      Json                  // JSON array of scope strings
+  scopes Json // JSON array of scope strings
 
   // Lifecycle
-  enabled     Boolean   @default(true)
-  expiresAt   DateTime?             // Optional expiration date
-  lastUsedAt  DateTime?             // Updated on each token exchange
-  revokedAt   DateTime?             // Set when key is revoked
-  revokedBy   String?               // User ID who revoked
+  enabled    Boolean   @default(true)
+  expiresAt  DateTime? // Optional expiration date
+  lastUsedAt DateTime? // Updated on each token exchange
+  revokedAt  DateTime? // Set when key is revoked
+  revokedBy  String? // User ID who revoked
 
   // Audit
-  createdBy   String?               // User ID who created
-  createdAt   DateTime  @default(now())
-  updatedAt   DateTime  @updatedAt
+  createdBy String? // User ID who created
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
   @@index([tenantId])
   @@index([provider])
@@ -994,7 +994,7 @@ model PaymentMethodPhaseStep {
 /// 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())
+  id     String                 @id @default(cuid())
   stepId String
   step   PaymentMethodPhaseStep @relation(fields: [stepId], references: [id], onDelete: Cascade)
 
@@ -1104,7 +1104,6 @@ model Contract {
   phases       ContractPhase[]
   documents    ContractDocument[]
   payments     ContractPayment[]
-  events       ContractEvent[]
   terminations ContractTermination[]
   offerLetters OfferLetter[]
 
@@ -1121,6 +1120,9 @@ model Contract {
   // Transfer requests where this contract is the target (created after approval)
   incomingTransferRequests PropertyTransferRequest[] @relation("TargetContract")
 
+  // Audit trail
+  events ContractEvent[]
+
   @@index([tenantId])
   @@index([propertyUnitId])
   @@index([buyerId])
@@ -1212,6 +1214,44 @@ model ContractPhase {
   @@map("contract_phases")
 }
 
+// =============================================================================
+// CONTRACT EVENTS - Audit trail for contract lifecycle
+// =============================================================================
+// Tracks all significant events in a contract's lifecycle for audit, compliance,
+// and debugging. Unlike DomainEvent (which is for inter-service communication),
+// ContractEvent is purely for historical tracking and state machine transitions.
+// =============================================================================
+model ContractEvent {
+  id         String   @id @default(cuid())
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  // Event classification
+  eventType  String // STATE.TRANSITION, PHASE.ACTIVATED, PAYMENT.COMPLETED, CONTRACT.CREATED, etc.
+  eventGroup String? // STATE_CHANGE, PAYMENT, DOCUMENT, NOTIFICATION (for filtering)
+
+  // For state transitions (optional - only populated for STATE.TRANSITION events)
+  fromState String?
+  toState   String?
+  trigger   String?
+
+  // Event payload (all event-specific data)
+  data Json?
+
+  // Actor tracking
+  actorId   String?
+  actorType String? // USER, SYSTEM, WEBHOOK
+
+  // Timing
+  occurredAt DateTime @default(now())
+
+  @@index([contractId])
+  @@index([eventType])
+  @@index([eventGroup])
+  @@index([occurredAt])
+  @@map("contract_events")
+}
+
 // Steps within a DOCUMENTATION phase (FSM for document collection/approval)
 model DocumentationStep {
   id      String        @id @default(cuid())
@@ -1403,38 +1443,6 @@ model ContractDocument {
   @@map("contract_documents")
 }
 
-// Contract domain events (FSM transitions, payments, documents, etc.)
-model ContractEvent {
-  id         String   @id @default(cuid())
-  contractId String
-  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
-
-  // Event classification
-  eventType  String // STATE.TRANSITION, PHASE.ACTIVATED, PAYMENT.COMPLETED, etc.
-  eventGroup String? // STATE_CHANGE, PAYMENT, DOCUMENT, NOTIFICATION (for filtering)
-
-  // For state transitions (optional - only populated for STATE.TRANSITION events)
-  fromState String?
-  toState   String?
-  trigger   String?
-
-  // Event payload (all event-specific data)
-  data Json?
-
-  // Actor tracking
-  actorId   String?
-  actorType String? // USER, SYSTEM, WEBHOOK
-
-  // Timing
-  occurredAt DateTime @default(now())
-
-  @@index([contractId])
-  @@index([eventType])
-  @@index([eventGroup])
-  @@index([occurredAt])
-  @@map("contract_events")
-}
-
 // =============================================================================
 // OFFER LETTERS - Provisional and Final offer documents
 // =============================================================================
@@ -1760,9 +1768,9 @@ model DocumentRequirementRule {
 /// Event Channel - A logical grouping of events
 /// Channels help organize events and route them to appropriate handlers
 model EventChannel {
-  id          String  @id @default(cuid())
-  tenantId    String
-  tenant      Tenant  @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
 
   /// Unique code for the channel (e.g., "CONTRACTS", "PAYMENTS")
   code        String
@@ -1772,7 +1780,7 @@ model EventChannel {
   description String? @db.Text
 
   /// Whether this channel is active
-  enabled     Boolean @default(true)
+  enabled Boolean @default(true)
 
   /// Event types that belong to this channel
   eventTypes EventType[]
@@ -1788,9 +1796,9 @@ model EventChannel {
 /// Event Type - Defines a type of event that can occur
 /// Each event type belongs to a channel and can have multiple handlers
 model EventType {
-  id          String  @id @default(cuid())
-  tenantId    String
-  tenant      Tenant  @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
 
   /// The channel this event type belongs to
   channelId String
@@ -1828,9 +1836,9 @@ model EventType {
 /// Event Handler - Defines what should happen when an event fires
 /// Handlers can be internal (call a service), external (webhook), or workflow triggers
 model EventHandler {
-  id          String  @id @default(cuid())
-  tenantId    String
-  tenant      Tenant  @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
 
   /// The event type this handler responds to
   eventTypeId String
@@ -2053,7 +2061,7 @@ model PropertyTransferRequest {
   sourceTotalAmount Float? // Original contract total
   targetTotalAmount Float? // New contract total (based on target property)
   priceAdjustment   Float? // Difference (positive = buyer owes more)
-  paymentsMigrated  Int?   // Number of payments migrated
+  paymentsMigrated  Int? // Number of payments migrated
 
   // Result - new contract created after approval
   targetContractId String?
@@ -2078,21 +2086,21 @@ model PropertyTransferRequest {
 // =============================================================================
 
 enum ApprovalRequestType {
-  PROPERTY_TRANSFER    // Property unit transfer between contracts
-  PROPERTY_UPDATE      // Property/unit listing update requiring approval
-  USER_WORKFLOW        // User workflow step approval
-  CREDIT_CHECK         // Credit check result review
+  PROPERTY_TRANSFER // Property unit transfer between contracts
+  PROPERTY_UPDATE // Property/unit listing update requiring approval
+  USER_WORKFLOW // User workflow step approval
+  CREDIT_CHECK // Credit check result review
   CONTRACT_TERMINATION // Contract termination approval
-  REFUND_APPROVAL      // Refund request approval
+  REFUND_APPROVAL // Refund request approval
 }
 
 enum ApprovalRequestStatus {
-  PENDING      // Awaiting review
-  IN_REVIEW    // Assigned to reviewer
-  APPROVED     // Approved by reviewer
-  REJECTED     // Rejected by reviewer
-  CANCELLED    // Cancelled by requestor
-  EXPIRED      // Auto-expired (if TTL configured)
+  PENDING // Awaiting review
+  IN_REVIEW // Assigned to reviewer
+  APPROVED // Approved by reviewer
+  REJECTED // Rejected by reviewer
+  CANCELLED // Cancelled by requestor
+  EXPIRED // Auto-expired (if TTL configured)
 }
 
 enum ApprovalRequestPriority {
@@ -2119,7 +2127,7 @@ model ApprovalRequest {
 
   // Request metadata
   title       String  @db.VarChar(255) // Human-readable title for the request
-  description String? @db.Text        // Detailed description
+  description String? @db.Text // Detailed description
 
   // Payload for any additional context (JSON)
   payload Json? // Flexible data storage for type-specific details
@@ -2137,7 +2145,7 @@ model ApprovalRequest {
   reviewedBy   User?   @relation("ApprovalReviewer", fields: [reviewedById], references: [id])
 
   // Review details
-  reviewNotes String? @db.Text // Reviewer's notes/comments
+  reviewNotes String?           @db.Text // Reviewer's notes/comments
   decision    ApprovalDecision? // APPROVED, REJECTED, REQUEST_CHANGES
 
   // Expiration