@valentine-efagene/qshelter-common 2.0.66 → 2.0.68

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

@@ -0,0 +1,315 @@
+/**
+ * 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 (webhook, internal call, etc.)
+ * 4. WorkflowEvent - Actual event instances (audit log)
+ * 5. EventHandlerExecution - Log of handler executions
+ */
+export type { EventHandlerType, ActorType, WorkflowEventStatus, ExecutionStatus, } from '../../generated/client/enums';
+/**
+ * Configuration for INTERNAL handler type
+ * Calls an internal service method
+ */
+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>;
+}
+/**
+ * Configuration for WEBHOOK handler type
+ * Sends HTTP request to external URL
+ */
+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;
+}
+/**
+ * Configuration for WORKFLOW handler type
+ * Triggers or advances a workflow
+ */
+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>;
+}
+/**
+ * Configuration for NOTIFICATION handler type
+ * Sends notifications via various channels (internal handling)
+ */
+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';
+}
+/**
+ * Configuration for SNS handler type
+ * Publishes to SNS topic, which triggers the notification-service via SQS
+ * Uses the NotificationEvent format expected by notification-service
+ */
+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>;
+    /**
+     * Static payload fields to merge with mapped payload
+     */
+    staticPayload?: Record<string, unknown>;
+    /**
+     * Email recipient field path in the event payload (e.g., $.user.email)
+     */
+    recipientPath?: string;
+}
+/**
+ * Configuration for SCRIPT handler type
+ * Executes custom logic
+ */
+export interface ScriptHandlerConfig {
+    type: 'SCRIPT';
+    /** Script language */
+    language: 'jsonata' | 'javascript';
+    /** The script/expression to execute */
+    script: string;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Union type for all handler configurations
+ */
+export type HandlerConfig = InternalHandlerConfig | WebhookHandlerConfig | WorkflowHandlerConfig | NotificationHandlerConfig | SnsHandlerConfig | ScriptHandlerConfig;
+/**
+ * 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
+ */
+export interface CreateEventHandlerInput {
+    eventTypeId: string;
+    name: string;
+    description?: string;
+    handlerType: 'INTERNAL' | 'WEBHOOK' | 'WORKFLOW' | 'NOTIFICATION' | 'SCRIPT';
+    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-types.js

@@ -0,0 +1,14 @@
+/**
+ * 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 (webhook, internal call, etc.)
+ * 4. WorkflowEvent - Actual event instances (audit log)
+ * 5. EventHandlerExecution - Log of handler executions
+ */
+export {};

package/package.json

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

package/prisma/migrations/20260105151535_add_event_workflow_system/migration.sql

@@ -0,0 +1,132 @@
+-- CreateTable
+CREATE TABLE `event_channels` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `code` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `enabled` BOOLEAN NOT NULL DEFAULT true,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `event_channels_tenantId_idx`(`tenantId`),
+    UNIQUE INDEX `event_channels_tenantId_code_key`(`tenantId`, `code`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `event_types` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `channelId` VARCHAR(191) NOT NULL,
+    `code` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `payloadSchema` JSON NULL,
+    `enabled` BOOLEAN NOT NULL DEFAULT true,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `event_types_tenantId_idx`(`tenantId`),
+    INDEX `event_types_channelId_idx`(`channelId`),
+    UNIQUE INDEX `event_types_tenantId_code_key`(`tenantId`, `code`),
+    UNIQUE INDEX `event_types_channelId_code_key`(`channelId`, `code`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `event_handlers` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `eventTypeId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `handlerType` ENUM('INTERNAL', 'WEBHOOK', 'WORKFLOW', 'NOTIFICATION', 'SCRIPT') NOT NULL,
+    `config` JSON NOT NULL,
+    `priority` INTEGER NOT NULL DEFAULT 100,
+    `enabled` BOOLEAN NOT NULL DEFAULT true,
+    `maxRetries` INTEGER NOT NULL DEFAULT 3,
+    `retryDelayMs` INTEGER NOT NULL DEFAULT 1000,
+    `filterCondition` TEXT NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `event_handlers_tenantId_idx`(`tenantId`),
+    INDEX `event_handlers_eventTypeId_idx`(`eventTypeId`),
+    INDEX `event_handlers_handlerType_idx`(`handlerType`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `workflow_events` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `eventTypeId` VARCHAR(191) NOT NULL,
+    `payload` JSON NOT NULL,
+    `correlationId` VARCHAR(191) NULL,
+    `causationId` VARCHAR(191) NULL,
+    `source` VARCHAR(191) NOT NULL,
+    `actorId` VARCHAR(191) NULL,
+    `actorType` ENUM('USER', 'API_KEY', 'SYSTEM', 'WEBHOOK') NOT NULL DEFAULT 'SYSTEM',
+    `status` ENUM('PENDING', 'PROCESSING', 'COMPLETED', 'FAILED', 'SKIPPED') NOT NULL DEFAULT 'PENDING',
+    `error` TEXT NULL,
+    `processedAt` DATETIME(3) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `workflow_events_tenantId_idx`(`tenantId`),
+    INDEX `workflow_events_eventTypeId_idx`(`eventTypeId`),
+    INDEX `workflow_events_correlationId_idx`(`correlationId`),
+    INDEX `workflow_events_causationId_idx`(`causationId`),
+    INDEX `workflow_events_status_idx`(`status`),
+    INDEX `workflow_events_createdAt_idx`(`createdAt`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `event_handler_executions` (
+    `id` VARCHAR(191) NOT NULL,
+    `eventId` VARCHAR(191) NOT NULL,
+    `handlerId` VARCHAR(191) NOT NULL,
+    `status` ENUM('PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'RETRYING', 'SKIPPED') NOT NULL DEFAULT 'PENDING',
+    `attempt` INTEGER NOT NULL DEFAULT 1,
+    `input` JSON NULL,
+    `output` JSON NULL,
+    `error` TEXT NULL,
+    `errorCode` VARCHAR(191) NULL,
+    `startedAt` DATETIME(3) NULL,
+    `completedAt` DATETIME(3) NULL,
+    `durationMs` INTEGER NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `event_handler_executions_eventId_idx`(`eventId`),
+    INDEX `event_handler_executions_handlerId_idx`(`handlerId`),
+    INDEX `event_handler_executions_status_idx`(`status`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `event_channels` ADD CONSTRAINT `event_channels_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `event_types` ADD CONSTRAINT `event_types_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `event_types` ADD CONSTRAINT `event_types_channelId_fkey` FOREIGN KEY (`channelId`) REFERENCES `event_channels`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `event_handlers` ADD CONSTRAINT `event_handlers_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `event_handlers` ADD CONSTRAINT `event_handlers_eventTypeId_fkey` FOREIGN KEY (`eventTypeId`) REFERENCES `event_types`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `workflow_events` ADD CONSTRAINT `workflow_events_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `workflow_events` ADD CONSTRAINT `workflow_events_eventTypeId_fkey` FOREIGN KEY (`eventTypeId`) REFERENCES `event_types`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `event_handler_executions` ADD CONSTRAINT `event_handler_executions_eventId_fkey` FOREIGN KEY (`eventId`) REFERENCES `workflow_events`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `event_handler_executions` ADD CONSTRAINT `event_handler_executions_handlerId_fkey` FOREIGN KEY (`handlerId`) REFERENCES `event_handlers`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;