@valentine-efagene/qshelter-common 2.0.34 → 2.0.36

package/dist/src/events/event-publisher.d.ts

@@ -0,0 +1,41 @@
+import { NotificationMeta } from './notification-event';
+import { NotificationType, NotificationChannel } from './notification-enums';
+/**
+ * Configuration for the event publisher
+ */
+interface EventPublisherConfig {
+    region?: string;
+    endpoint?: string;
+    topicArn?: string;
+}
+/**
+ * Event Publisher for sending notification events to SNS
+ * Used by all services to publish events to the notifications topic
+ */
+export declare class EventPublisher {
+    private readonly snsClient;
+    private readonly topicArn;
+    private readonly serviceName;
+    constructor(serviceName: string, config?: EventPublisherConfig);
+    /**
+     * Publish a notification event to SNS
+     */
+    publish<T>(type: NotificationType, channel: NotificationChannel, payload: T, meta?: Partial<NotificationMeta>): Promise<string>;
+    /**
+     * Convenience method for publishing email notifications
+     */
+    publishEmail<T>(type: NotificationType, payload: T, meta?: Partial<NotificationMeta>): Promise<string>;
+    /**
+     * Convenience method for publishing SMS notifications
+     */
+    publishSMS<T>(type: NotificationType, payload: T, meta?: Partial<NotificationMeta>): Promise<string>;
+    /**
+     * Convenience method for publishing push notifications
+     */
+    publishPush<T>(type: NotificationType, payload: T, meta?: Partial<NotificationMeta>): Promise<string>;
+}
+/**
+ * Get or create an EventPublisher for a service
+ */
+export declare function getEventPublisher(serviceName: string, config?: EventPublisherConfig): EventPublisher;
+export {};

package/dist/src/events/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/index.d.ts

@@ -0,0 +1,3 @@
+export * from './notification-enums';
+export * from './notification-event';
+export * from './event-publisher';

package/dist/src/events/index.js

@@ -0,0 +1,3 @@
+export * from './notification-enums';
+export * from './notification-event';
+export * from './event-publisher';

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

@@ -0,0 +1,38 @@
+/**
+ * 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",
+    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/notification-enums.js

@@ -0,0 +1,48 @@
+/**
+ * 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";
+    // 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/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/notification-event.js

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

package/dist/src/index.d.ts

@@ -7,3 +7,4 @@ export * from '../generated/client/models';
 export * from './prisma/user';
 export * from './prisma/tenant';
 export * from './middleware';
+export * from './events';

package/dist/src/index.js

@@ -7,3 +7,4 @@ export * from '../generated/client/models';
 export * from './prisma/user';
 export * from './prisma/tenant';
 export * from './middleware';
+export * from './events';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.34",
+  "version": "2.0.36",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -29,6 +29,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-secrets-manager": "^3.500.0",
+    "@aws-sdk/client-sns": "^3.500.0",
     "@aws-sdk/client-ssm": "^3.500.0",
     "@prisma/client": "^7.0.0",
     "dotenv": "^17.2.3",