@valentine-efagene/qshelter-common 2.0.66 → 2.0.67

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

@@ -0,0 +1,189 @@
+/**
+ * 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';
+/**
+ * Service registry interface for internal handlers
+ */
+export interface ServiceRegistry {
+    get(serviceName: string): any | undefined;
+    register(serviceName: string, service: any): void;
+}
+export declare class WorkflowEventService {
+    private prisma;
+    private serviceRegistry;
+    constructor(prisma: PrismaClient, serviceRegistry?: ServiceRegistry);
+    /**
+     * Register a service for internal event handlers
+     *
+     * Services can be called by INTERNAL handler type configurations.
+     * The service should expose methods that match the handler config.
+     */
+    registerService(name: string, service: any): 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;
+            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;
+            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
+     */
+    private executeHandler;
+    /**
+     * Execute an internal service method
+     */
+    private executeInternalHandler;
+    /**
+     * Execute a webhook handler
+     */
+    private executeWebhookHandler;
+    /**
+     * Execute a workflow handler
+     *
+     * This emits a new event that the workflow service can pick up,
+     * creating loose coupling between event system and workflow engine.
+     */
+    private executeWorkflowHandler;
+    /**
+     * Execute a notification handler
+     *
+     * This would integrate with a notification service.
+     * Returns what would be sent for logging purposes.
+     */
+    private executeNotificationHandler;
+    /**
+     * 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;
+    /**
+     * Resolve recipients from config, potentially using payload variables
+     */
+    private resolveRecipients;
+}
+/**
+ * Create a workflow event service instance
+ */
+export declare function createWorkflowEventService(prisma: PrismaClient, serviceRegistry?: ServiceRegistry): WorkflowEventService;