@valentine-efagene/qshelter-common 2.0.74 → 2.0.76

package/dist/src/events/notifications/event-publisher.js

@@ -0,0 +1,111 @@
+import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
+import { NotificationChannel } from './notification-enums';
+/**
+ * Get SNS client configured for LocalStack or AWS
+ */
+function createSNSClient(config) {
+    const isLocalStack = process.env.LOCALSTACK_ENDPOINT || process.env.NODE_ENV === 'test';
+    const clientConfig = {
+        region: config.region || process.env.AWS_REGION || 'us-east-1',
+    };
+    if (isLocalStack) {
+        clientConfig.endpoint = config.endpoint || process.env.LOCALSTACK_ENDPOINT || 'http://localhost:4566';
+        clientConfig.credentials = {
+            accessKeyId: 'test',
+            secretAccessKey: 'test',
+        };
+    }
+    return new SNSClient(clientConfig);
+}
+/**
+ * Event Publisher for sending notification events to SNS
+ * Used by all services to publish events to the notifications topic
+ */
+export class EventPublisher {
+    snsClient;
+    topicArn;
+    serviceName;
+    constructor(serviceName, config) {
+        this.serviceName = serviceName;
+        this.snsClient = createSNSClient(config || {});
+        // Topic ARN can be passed directly or constructed from env vars
+        const stage = process.env.STAGE || process.env.NODE_ENV || 'test';
+        const region = config?.region || process.env.AWS_REGION || 'us-east-1';
+        const accountId = process.env.AWS_ACCOUNT_ID || '000000000000';
+        this.topicArn = config?.topicArn ||
+            process.env.NOTIFICATIONS_TOPIC_ARN ||
+            `arn:aws:sns:${region}:${accountId}:qshelter-${stage}-notifications`;
+    }
+    /**
+     * Publish a notification event to SNS
+     */
+    async publish(type, channel, payload, meta) {
+        const event = {
+            type,
+            channel,
+            payload,
+            meta: {
+                source: this.serviceName,
+                timestamp: new Date().toISOString(),
+                correlationId: meta?.correlationId || crypto.randomUUID(),
+                userId: meta?.userId,
+                tenantId: meta?.tenantId,
+            },
+        };
+        const command = new PublishCommand({
+            TopicArn: this.topicArn,
+            Message: JSON.stringify(event),
+            MessageAttributes: {
+                notificationType: {
+                    DataType: 'String',
+                    StringValue: type,
+                },
+                channel: {
+                    DataType: 'String',
+                    StringValue: channel,
+                },
+                source: {
+                    DataType: 'String',
+                    StringValue: this.serviceName,
+                },
+            },
+        });
+        const result = await this.snsClient.send(command);
+        console.log(`[EventPublisher] Published ${type} event to SNS`, {
+            messageId: result.MessageId,
+            type,
+            channel,
+            source: this.serviceName,
+        });
+        return result.MessageId || '';
+    }
+    /**
+     * Convenience method for publishing email notifications
+     */
+    async publishEmail(type, payload, meta) {
+        return this.publish(type, NotificationChannel.EMAIL, payload, meta);
+    }
+    /**
+     * Convenience method for publishing SMS notifications
+     */
+    async publishSMS(type, payload, meta) {
+        return this.publish(type, NotificationChannel.SMS, payload, meta);
+    }
+    /**
+     * Convenience method for publishing push notifications
+     */
+    async publishPush(type, payload, meta) {
+        return this.publish(type, NotificationChannel.PUSH, payload, meta);
+    }
+}
+// Singleton instances per service
+const publisherInstances = new Map();
+/**
+ * Get or create an EventPublisher for a service
+ */
+export function getEventPublisher(serviceName, config) {
+    if (!publisherInstances.has(serviceName)) {
+        publisherInstances.set(serviceName, new EventPublisher(serviceName, config));
+    }
+    return publisherInstances.get(serviceName);
+}

package/dist/src/events/notifications/notification-enums.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Types of notifications that can be sent
+ * Used by all services to ensure consistent event naming
+ */
+export declare enum NotificationType {
+    WELCOME = "welcome",
+    VERIFY_EMAIL = "verifyEmail",
+    ACCOUNT_VERIFIED = "accountVerified",
+    ACCOUNT_SUSPENDED = "accountSuspended",
+    PASSWORD_RESET = "resetPassword",
+    MISSED_PAYMENT = "missedPayments",
+    WALLET_TOP_UP = "walletTopUp",
+    PAYMENT_RECEIVED = "paymentReceived",
+    PAYMENT_FAILED = "paymentFailed",
+    PAYMENT_REMINDER = "paymentReminder",
+    PROPERTY_ALLOCATION = "propertyAllocation",
+    UPDATED_TERMS = "updatedTermsAndConditions",
+    PREQUALIFICATION_SUBMITTED = "prequalificationSubmitted",
+    PREQUALIFICATION_APPROVED = "prequalificationApproved",
+    PREQUALIFICATION_REJECTED = "prequalificationRejected",
+    CONTRACT_CREATED = "contractCreated",
+    CONTRACT_ACTIVATED = "contractActivated",
+    CONTRACT_TERMINATION_REQUESTED = "contractTerminationRequested",
+    CONTRACT_TERMINATION_APPROVED = "contractTerminationApproved",
+    CONTRACT_TERMINATED = "contractTerminated",
+    OFFER_LETTER_SENT = "offerLetterSent",
+    OFFER_LETTER_SIGNED = "offerLetterSigned",
+    OFFER_LETTER_EXPIRED = "offerLetterExpired",
+    UNDERWRITING_APPROVED = "underwritingApproved",
+    UNDERWRITING_REJECTED = "underwritingRejected",
+    UNDERWRITING_CONDITIONAL = "underwritingConditional",
+    DOCUMENT_APPROVED = "documentApproved",
+    DOCUMENT_REJECTED = "documentRejected",
+    ADMIN_CONTRIBUTION_RECEIVED = "adminContributionReceived",
+    ADMIN_PROPERTY_ALLOCATION = "adminPropertyAllocation",
+    ADMIN_INVITE = "adminInviteAdmin",
+    OTP = "otp"
+}
+/**
+ * Channels through which notifications can be delivered
+ */
+export declare enum NotificationChannel {
+    EMAIL = "email",
+    SMS = "sms",
+    PUSH = "push"
+}

package/dist/src/events/notifications/notification-enums.js

@@ -0,0 +1,59 @@
+/**
+ * Types of notifications that can be sent
+ * Used by all services to ensure consistent event naming
+ */
+export var NotificationType;
+(function (NotificationType) {
+    // User lifecycle
+    NotificationType["WELCOME"] = "welcome";
+    NotificationType["VERIFY_EMAIL"] = "verifyEmail";
+    NotificationType["ACCOUNT_VERIFIED"] = "accountVerified";
+    NotificationType["ACCOUNT_SUSPENDED"] = "accountSuspended";
+    NotificationType["PASSWORD_RESET"] = "resetPassword";
+    // Payments
+    NotificationType["MISSED_PAYMENT"] = "missedPayments";
+    NotificationType["WALLET_TOP_UP"] = "walletTopUp";
+    NotificationType["PAYMENT_RECEIVED"] = "paymentReceived";
+    NotificationType["PAYMENT_FAILED"] = "paymentFailed";
+    NotificationType["PAYMENT_REMINDER"] = "paymentReminder";
+    // Property
+    NotificationType["PROPERTY_ALLOCATION"] = "propertyAllocation";
+    // Terms
+    NotificationType["UPDATED_TERMS"] = "updatedTermsAndConditions";
+    // Prequalification
+    NotificationType["PREQUALIFICATION_SUBMITTED"] = "prequalificationSubmitted";
+    NotificationType["PREQUALIFICATION_APPROVED"] = "prequalificationApproved";
+    NotificationType["PREQUALIFICATION_REJECTED"] = "prequalificationRejected";
+    // Contract
+    NotificationType["CONTRACT_CREATED"] = "contractCreated";
+    NotificationType["CONTRACT_ACTIVATED"] = "contractActivated";
+    NotificationType["CONTRACT_TERMINATION_REQUESTED"] = "contractTerminationRequested";
+    NotificationType["CONTRACT_TERMINATION_APPROVED"] = "contractTerminationApproved";
+    NotificationType["CONTRACT_TERMINATED"] = "contractTerminated";
+    // Offer Letters
+    NotificationType["OFFER_LETTER_SENT"] = "offerLetterSent";
+    NotificationType["OFFER_LETTER_SIGNED"] = "offerLetterSigned";
+    NotificationType["OFFER_LETTER_EXPIRED"] = "offerLetterExpired";
+    // Underwriting
+    NotificationType["UNDERWRITING_APPROVED"] = "underwritingApproved";
+    NotificationType["UNDERWRITING_REJECTED"] = "underwritingRejected";
+    NotificationType["UNDERWRITING_CONDITIONAL"] = "underwritingConditional";
+    // Documents
+    NotificationType["DOCUMENT_APPROVED"] = "documentApproved";
+    NotificationType["DOCUMENT_REJECTED"] = "documentRejected";
+    // Admin
+    NotificationType["ADMIN_CONTRIBUTION_RECEIVED"] = "adminContributionReceived";
+    NotificationType["ADMIN_PROPERTY_ALLOCATION"] = "adminPropertyAllocation";
+    NotificationType["ADMIN_INVITE"] = "adminInviteAdmin";
+    // OTP
+    NotificationType["OTP"] = "otp";
+})(NotificationType || (NotificationType = {}));
+/**
+ * Channels through which notifications can be delivered
+ */
+export var NotificationChannel;
+(function (NotificationChannel) {
+    NotificationChannel["EMAIL"] = "email";
+    NotificationChannel["SMS"] = "sms";
+    NotificationChannel["PUSH"] = "push";
+})(NotificationChannel || (NotificationChannel = {}));

package/dist/src/events/notifications/notification-event.d.ts

@@ -0,0 +1,76 @@
+import { NotificationType, NotificationChannel } from './notification-enums';
+/**
+ * Metadata attached to every notification event for tracing and debugging
+ */
+export interface NotificationMeta {
+    /** Service that published the event */
+    source: string;
+    /** ISO timestamp of when event was created */
+    timestamp: string;
+    /** Correlation ID for distributed tracing */
+    correlationId?: string;
+    /** User ID if applicable */
+    userId?: string;
+    /** Tenant ID if applicable */
+    tenantId?: string;
+}
+/**
+ * Standard notification event payload sent via SNS->SQS
+ * All services must use this interface when publishing notification events
+ */
+export interface NotificationEvent<T = Record<string, unknown>> {
+    /** Type of notification - determines which template/handler to use */
+    type: NotificationType;
+    /** Delivery channel - email, sms, or push */
+    channel: NotificationChannel;
+    /** The actual notification data (varies by type) */
+    payload: T;
+    /** Event metadata for tracing */
+    meta: NotificationMeta;
+}
+/**
+ * Email-specific payload fields that most email templates need
+ */
+export interface EmailPayload {
+    /** Recipient email address */
+    to_email: string;
+    /** Optional subject override (defaults to template title) */
+    subject?: string;
+}
+/**
+ * Verify email payload
+ */
+export interface VerifyEmailPayload extends EmailPayload {
+    homeBuyerName: string;
+    verificationLink: string;
+}
+/**
+ * Password reset payload
+ */
+export interface PasswordResetPayload extends EmailPayload {
+    homeBuyerName: string;
+    otp: string;
+    ttl: number;
+}
+/**
+ * Welcome email payload
+ */
+export interface WelcomePayload extends EmailPayload {
+    homeBuyerName: string;
+    loginLink: string;
+}
+/**
+ * Missed payments payload
+ */
+export interface MissedPaymentsPayload extends EmailPayload {
+    homeBuyerName: string;
+    amount: number;
+    loginLink: string;
+}
+/**
+ * Account verified payload
+ */
+export interface AccountVerifiedPayload extends EmailPayload {
+    homeBuyerName: string;
+    loginLink: string;
+}

package/dist/src/events/notifications/notification-event.js

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

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

@@ -0,0 +1,157 @@
+/**
+ * Unified Event Service
+ *
+ * This service bridges WorkflowEventService (database-backed) with EventBusService (transport layer).
+ * It provides a single, unified API for all event emission across services.
+ *
+ * Architecture:
+ * 1. Service emits event → UnifiedEventService
+ * 2. Event stored in DB → WorkflowEvent (audit trail)
+ * 3. Handlers fetched → EventHandler table (admin-configured)
+ * 4. EventBusService delivers → Multi-transport (HTTP/SNS/SQS/EventBridge)
+ * 5. Execution logged → EventHandlerExecution (tracking)
+ *
+ * Usage:
+ * ```typescript
+ * const eventService = createUnifiedEventService(prisma, eventBus);
+ *
+ * await eventService.emit(tenantId, {
+ *   eventType: 'CONTRACT_CREATED',
+ *   payload: { contractId, buyerId, propertyUnitId },
+ *   source: 'contract-service',
+ *   actor: { id: userId, type: 'USER' }
+ * });
+ * ```
+ */
+import { PrismaClient } from '../../../generated/client/client';
+import type { EmitEventInput, WorkflowEventData, ProcessEventResult } from '../workflow/workflow-types';
+import { AutomationRegistry, ServiceRegistry } from '../workflow/workflow-event.service';
+import { NotificationType, NotificationChannel } from '../notifications/notification-enums';
+/**
+ * EventBusService interface
+ * Minimal interface to avoid circular dependencies with EventBusService
+ */
+export interface IEventBusService {
+    publish<T = any>(eventType: string, data: T, options?: {
+        tenantId?: number;
+        source?: string;
+        metadata?: Record<string, any>;
+        correlationId?: string;
+    }): Promise<any[]>;
+}
+/**
+ * Configuration for UnifiedEventService
+ */
+export interface UnifiedEventServiceConfig {
+    /**
+     * Whether to process events immediately (synchronous)
+     * or defer to background worker (asynchronous)
+     * Default: false (async)
+     */
+    processImmediately?: boolean;
+    /**
+     * Whether to publish to EventBus after storing in DB
+     * Default: true
+     */
+    publishToEventBus?: boolean;
+    /**
+     * Whether to use legacy EventPublisher for backwards compatibility
+     * Default: false
+     */
+    useLegacyPublisher?: boolean;
+    /**
+     * Service name for event source attribution
+     */
+    serviceName?: string;
+}
+/**
+ * UnifiedEventService - Single API for all event emission
+ */
+export declare class UnifiedEventService {
+    private prisma;
+    private eventBus?;
+    private config;
+    private workflowEventService;
+    private legacyPublisher?;
+    constructor(prisma: PrismaClient, eventBus?: IEventBusService | undefined, config?: UnifiedEventServiceConfig, automationRegistry?: AutomationRegistry, serviceRegistry?: ServiceRegistry);
+    /**
+     * Emit an event through the unified system
+     *
+     * This method:
+     * 1. Stores event in WorkflowEvent table (audit trail)
+     * 2. Fetches admin-configured handlers from EventHandler table
+     * 3. Executes handlers (optionally via EventBus)
+     * 4. Logs execution results in EventHandlerExecution table
+     *
+     * @param tenantId - Tenant context
+     * @param input - Event details
+     * @returns The created event data
+     */
+    emit(tenantId: string, input: EmitEventInput): Promise<WorkflowEventData>;
+    /**
+     * Process an event (run all handlers)
+     *
+     * This is called either:
+     * - Immediately after emit() if processImmediately=true
+     * - By a background worker for async processing
+     *
+     * @param eventId - The event to process
+     * @returns Processing results
+     */
+    processEvent(eventId: string): Promise<ProcessEventResult>;
+    /**
+     * Register an automation handler
+     *
+     * Automations are custom business logic that can be triggered by events.
+     * Example: calculateLateFee, sendWelcomePackage, archiveContract
+     *
+     * @param name - Automation name (matches EventHandler.config.automationName)
+     * @param handler - The automation function
+     */
+    registerAutomation(name: string, handler: (inputs: Record<string, unknown>, tenantId: string) => Promise<unknown>): void;
+    /**
+     * Convenience method: Emit notification event
+     */
+    publishNotification(params: {
+        type: NotificationType;
+        channel: NotificationChannel;
+        payload: Record<string, unknown>;
+        meta: {
+            source: string;
+            tenantId?: string;
+            correlationId?: string;
+            userId?: string;
+        };
+    }): Promise<void>;
+    /**
+     * Convenience method: Emit email notification
+     */
+    publishEmail(type: NotificationType, payload: Record<string, unknown>, meta: {
+        source: string;
+        tenantId?: string;
+        correlationId?: string;
+        userId?: string;
+    }): Promise<void>;
+    /**
+     * Convenience method: Emit SMS notification
+     */
+    publishSms(type: NotificationType, payload: Record<string, unknown>, meta: {
+        source: string;
+        tenantId?: string;
+        correlationId?: string;
+        userId?: string;
+    }): Promise<void>;
+}
+/**
+ * Factory function to create UnifiedEventService
+ *
+ * @param prisma - Prisma client
+ * @param eventBus - Optional EventBus service for transport-layer delivery
+ * @param config - Configuration options
+ * @returns Configured UnifiedEventService instance
+ */
+export declare function createUnifiedEventService(prisma: PrismaClient, eventBus?: IEventBusService, config?: UnifiedEventServiceConfig): UnifiedEventService;
+/**
+ * Export for backwards compatibility
+ */
+export { NotificationType, NotificationChannel };

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

@@ -0,0 +1,177 @@
+/**
+ * Unified Event Service
+ *
+ * This service bridges WorkflowEventService (database-backed) with EventBusService (transport layer).
+ * It provides a single, unified API for all event emission across services.
+ *
+ * Architecture:
+ * 1. Service emits event → UnifiedEventService
+ * 2. Event stored in DB → WorkflowEvent (audit trail)
+ * 3. Handlers fetched → EventHandler table (admin-configured)
+ * 4. EventBusService delivers → Multi-transport (HTTP/SNS/SQS/EventBridge)
+ * 5. Execution logged → EventHandlerExecution (tracking)
+ *
+ * Usage:
+ * ```typescript
+ * const eventService = createUnifiedEventService(prisma, eventBus);
+ *
+ * await eventService.emit(tenantId, {
+ *   eventType: 'CONTRACT_CREATED',
+ *   payload: { contractId, buyerId, propertyUnitId },
+ *   source: 'contract-service',
+ *   actor: { id: userId, type: 'USER' }
+ * });
+ * ```
+ */
+import { WorkflowEventService } from '../workflow/workflow-event.service';
+import { EventPublisher } from '../notifications/event-publisher';
+import { NotificationType, NotificationChannel } from '../notifications/notification-enums';
+/**
+ * UnifiedEventService - Single API for all event emission
+ */
+export class UnifiedEventService {
+    prisma;
+    eventBus;
+    config;
+    workflowEventService;
+    legacyPublisher;
+    constructor(prisma, eventBus, config = {}, automationRegistry, serviceRegistry) {
+        this.prisma = prisma;
+        this.eventBus = eventBus;
+        this.config = config;
+        // Initialize WorkflowEventService (database-backed)
+        this.workflowEventService = new WorkflowEventService(prisma, automationRegistry, config.useLegacyPublisher ? new EventPublisher(config.serviceName || 'unified-event-service') : undefined);
+        // Optionally initialize legacy publisher for backwards compatibility
+        if (config.useLegacyPublisher) {
+            this.legacyPublisher = new EventPublisher(config.serviceName || 'unified-event-service');
+        }
+    }
+    /**
+     * Emit an event through the unified system
+     *
+     * This method:
+     * 1. Stores event in WorkflowEvent table (audit trail)
+     * 2. Fetches admin-configured handlers from EventHandler table
+     * 3. Executes handlers (optionally via EventBus)
+     * 4. Logs execution results in EventHandlerExecution table
+     *
+     * @param tenantId - Tenant context
+     * @param input - Event details
+     * @returns The created event data
+     */
+    async emit(tenantId, input) {
+        const processImmediately = this.config.processImmediately ?? false;
+        // 1. Store event in database (WorkflowEvent)
+        const event = await this.workflowEventService.emit(tenantId, input, false);
+        // 2. Optionally publish to EventBus for transport-layer delivery
+        if (this.config.publishToEventBus !== false && this.eventBus) {
+            try {
+                await this.eventBus.publish(input.eventType, input.payload, {
+                    tenantId: Number(tenantId),
+                    source: input.source,
+                    correlationId: input.correlationId || event.id,
+                    metadata: {
+                        eventId: event.id,
+                        actorId: input.actor?.id,
+                        actorType: input.actor?.type,
+                    },
+                });
+            }
+            catch (error) {
+                console.error('Failed to publish to EventBus:', error);
+                // Don't fail the entire operation if EventBus publish fails
+                // The event is already in the database and can be retried
+            }
+        }
+        // 3. Process event handlers (if immediate processing is enabled)
+        if (processImmediately) {
+            await this.processEvent(event.id);
+        }
+        return event;
+    }
+    /**
+     * Process an event (run all handlers)
+     *
+     * This is called either:
+     * - Immediately after emit() if processImmediately=true
+     * - By a background worker for async processing
+     *
+     * @param eventId - The event to process
+     * @returns Processing results
+     */
+    async processEvent(eventId) {
+        return this.workflowEventService.processEvent(eventId);
+    }
+    /**
+     * Register an automation handler
+     *
+     * Automations are custom business logic that can be triggered by events.
+     * Example: calculateLateFee, sendWelcomePackage, archiveContract
+     *
+     * @param name - Automation name (matches EventHandler.config.automationName)
+     * @param handler - The automation function
+     */
+    registerAutomation(name, handler) {
+        this.workflowEventService.registerAutomation(name, handler);
+    }
+    /**
+     * Convenience method: Emit notification event
+     */
+    async publishNotification(params) {
+        const tenantId = params.meta.tenantId;
+        if (!tenantId) {
+            throw new Error('tenantId is required for publishNotification');
+        }
+        // Map legacy notification to WorkflowEvent
+        await this.emit(tenantId, {
+            eventType: `NOTIFICATION_${params.type}`,
+            payload: {
+                notificationType: params.type,
+                channel: params.channel,
+                ...params.payload,
+            },
+            source: params.meta.source,
+            actor: params.meta.userId
+                ? { id: params.meta.userId, type: 'USER' }
+                : undefined,
+            correlationId: params.meta.correlationId,
+        });
+    }
+    /**
+     * Convenience method: Emit email notification
+     */
+    async publishEmail(type, payload, meta) {
+        return this.publishNotification({
+            type,
+            channel: NotificationChannel.EMAIL,
+            payload,
+            meta,
+        });
+    }
+    /**
+     * Convenience method: Emit SMS notification
+     */
+    async publishSms(type, payload, meta) {
+        return this.publishNotification({
+            type,
+            channel: NotificationChannel.SMS,
+            payload,
+            meta,
+        });
+    }
+}
+/**
+ * Factory function to create UnifiedEventService
+ *
+ * @param prisma - Prisma client
+ * @param eventBus - Optional EventBus service for transport-layer delivery
+ * @param config - Configuration options
+ * @returns Configured UnifiedEventService instance
+ */
+export function createUnifiedEventService(prisma, eventBus, config = {}) {
+    return new UnifiedEventService(prisma, eventBus, config);
+}
+/**
+ * Export for backwards compatibility
+ */
+export { NotificationType, NotificationChannel };