@valentine-efagene/qshelter-common 2.0.83 → 2.0.84

package/dist/src/events/index.d.ts

@@ -1,5 +1,7 @@
 export * from './notifications/notification-enums';
 export * from './notifications/notification-event';
 export * from './notifications/event-publisher';
+export * from './payments/payment-event';
+export * from './payments/payment-publisher';
 export * from './bus/event-bus.types';
 export * from './bus/event-bus.service';

package/dist/src/events/index.js

@@ -2,6 +2,9 @@
 export * from './notifications/notification-enums';
 export * from './notifications/notification-event';
 export * from './notifications/event-publisher';
+// Payment events and publisher (SNS-based)
+export * from './payments/payment-event';
+export * from './payments/payment-publisher';
 // Event bus (multi-transport delivery)
 export * from './bus/event-bus.types';
 export * from './bus/event-bus.service';

package/dist/src/events/payments/index.d.ts

@@ -0,0 +1,2 @@
+export * from './payment-event';
+export * from './payment-publisher';

package/dist/src/events/payments/index.js

@@ -0,0 +1,2 @@
+export * from './payment-event';
+export * from './payment-publisher';

package/dist/src/events/payments/payment-event.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Payment event types for the payment service queue
+ * These are internal service events, not user-facing notifications
+ */
+export declare enum PaymentEventType {
+    WALLET_CREDITED = "wallet.credited",
+    WALLET_DEBITED = "wallet.debited",
+    WALLET_CREATED = "wallet.created",
+    ALLOCATE_TO_INSTALLMENTS = "payment.allocate_to_installments",
+    PROCESS_INSTALLMENT_PAYMENT = "payment.process_installment",
+    REFUND_PAYMENT = "payment.refund",
+    VIRTUAL_ACCOUNT_FUNDED = "virtualaccount.funded"
+}
+/**
+ * Metadata for payment events
+ */
+export interface PaymentEventMeta {
+    /** 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 */
+    userId?: string;
+    /** Tenant ID */
+    tenantId?: string;
+}
+/**
+ * Base payment event structure
+ */
+export interface PaymentEvent<T = Record<string, unknown>> {
+    type: PaymentEventType;
+    payload: T;
+    meta: PaymentEventMeta;
+}
+/**
+ * Payload when wallet is credited
+ */
+export interface WalletCreditedPayload {
+    walletId: string;
+    userId: string;
+    transactionId: string;
+    amount: number;
+    currency: string;
+    newBalance: number;
+    reference: string;
+    source: 'virtual_account' | 'manual' | 'refund';
+}
+/**
+ * Payload for allocating funds to installments
+ */
+export interface AllocateToInstallmentsPayload {
+    userId: string;
+    walletId: string;
+    /** Optional: limit to specific contract */
+    contractId?: string;
+    /** Optional: limit to specific amount */
+    maxAmount?: number;
+}
+/**
+ * Payload for processing an installment payment
+ */
+export interface ProcessInstallmentPaymentPayload {
+    installmentId: string;
+    amount: number;
+    walletId: string;
+    userId: string;
+    reference: string;
+}

package/dist/src/events/payments/payment-event.js

@@ -0,0 +1,18 @@
+/**
+ * Payment event types for the payment service queue
+ * These are internal service events, not user-facing notifications
+ */
+export var PaymentEventType;
+(function (PaymentEventType) {
+    // Wallet events (published by payment service)
+    PaymentEventType["WALLET_CREDITED"] = "wallet.credited";
+    PaymentEventType["WALLET_DEBITED"] = "wallet.debited";
+    PaymentEventType["WALLET_CREATED"] = "wallet.created";
+    // Allocation commands (published by mortgage service or after wallet credit)
+    PaymentEventType["ALLOCATE_TO_INSTALLMENTS"] = "payment.allocate_to_installments";
+    // Payment commands (published by mortgage service)
+    PaymentEventType["PROCESS_INSTALLMENT_PAYMENT"] = "payment.process_installment";
+    PaymentEventType["REFUND_PAYMENT"] = "payment.refund";
+    // Virtual account events
+    PaymentEventType["VIRTUAL_ACCOUNT_FUNDED"] = "virtualaccount.funded";
+})(PaymentEventType || (PaymentEventType = {}));

package/dist/src/events/payments/payment-publisher.d.ts

@@ -0,0 +1,46 @@
+import { PaymentEventType, PaymentEventMeta } from './payment-event';
+/**
+ * Configuration for the payment event publisher
+ */
+interface PaymentPublisherConfig {
+    region?: string;
+    endpoint?: string;
+    topicArn?: string;
+}
+/**
+ * Payment Event Publisher for sending payment events to SNS
+ * Used by payment-service and mortgage-service to communicate
+ */
+export declare class PaymentEventPublisher {
+    private readonly snsClient;
+    private readonly topicArn;
+    private readonly serviceName;
+    constructor(serviceName: string, config?: PaymentPublisherConfig);
+    /**
+     * Publish a payment event to SNS
+     */
+    publish<T>(type: PaymentEventType, payload: T, meta?: Partial<PaymentEventMeta>): Promise<string>;
+    /**
+     * Publish wallet credited event
+     */
+    publishWalletCredited(payload: {
+        walletId: string;
+        userId: string;
+        transactionId: string;
+        amount: number;
+        currency: string;
+        newBalance: number;
+        reference: string;
+        source: 'virtual_account' | 'manual' | 'refund';
+    }, meta?: Partial<PaymentEventMeta>): Promise<string>;
+    /**
+     * Publish allocate to installments command
+     */
+    publishAllocateToInstallments(payload: {
+        userId: string;
+        walletId: string;
+        contractId?: string;
+        maxAmount?: number;
+    }, meta?: Partial<PaymentEventMeta>): Promise<string>;
+}
+export {};

package/dist/src/events/payments/payment-publisher.js

@@ -0,0 +1,90 @@
+import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
+import { PaymentEventType, } from './payment-event';
+/**
+ * Get SNS client configured for LocalStack or AWS
+ */
+function createSNSClient(config) {
+    const endpoint = config.endpoint || process.env.LOCALSTACK_ENDPOINT;
+    const region = config.region || process.env.AWS_REGION || 'us-east-1';
+    const clientConfig = { region };
+    // For LocalStack, set custom endpoint
+    if (endpoint) {
+        clientConfig.endpoint = endpoint;
+    }
+    return new SNSClient(clientConfig);
+}
+/**
+ * Payment Event Publisher for sending payment events to SNS
+ * Used by payment-service and mortgage-service to communicate
+ */
+export class PaymentEventPublisher {
+    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.PAYMENTS_TOPIC_ARN ||
+            `arn:aws:sns:${region}:${accountId}:qshelter-${stage}-payments`;
+    }
+    /**
+     * Publish a payment event to SNS
+     */
+    async publish(type, payload, meta) {
+        const event = {
+            type,
+            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: {
+                eventType: {
+                    DataType: 'String',
+                    StringValue: type,
+                },
+                source: {
+                    DataType: 'String',
+                    StringValue: this.serviceName,
+                },
+            },
+        });
+        const result = await this.snsClient.send(command);
+        console.log(`[PaymentEventPublisher] Published ${type} event to SNS`, {
+            topicArn: this.topicArn,
+            messageId: result.MessageId,
+            correlationId: event.meta.correlationId,
+        });
+        return result.MessageId || '';
+    }
+    /**
+     * Publish wallet credited event
+     */
+    async publishWalletCredited(payload, meta) {
+        return this.publish(PaymentEventType.WALLET_CREDITED, payload, {
+            ...meta,
+            userId: payload.userId,
+        });
+    }
+    /**
+     * Publish allocate to installments command
+     */
+    async publishAllocateToInstallments(payload, meta) {
+        return this.publish(PaymentEventType.ALLOCATE_TO_INSTALLMENTS, payload, {
+            ...meta,
+            userId: payload.userId,
+        });
+    }
+}

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.83",
+  "version": "2.0.84",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "generate:prisma": "prisma generate && node scripts/generate-models-index.mjs",
+    "postgenerate": "node scripts/generate-models-index.mjs",
+    "migrate:dev": "prisma migrate dev",
+    "patch": "npm version patch && npm run build && npm publish --access public",
+    "prepublishOnly": "npm run build",
+    "publish:public": "npm publish --access public"
+  },
   "keywords": [
     "qshelter",
     "common",
@@ -47,14 +57,5 @@
     "@types/node": "^25.0.3",
     "typescript": "^5.7.3",
     "zod": "^4.0.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "generate:prisma": "prisma generate && node scripts/generate-models-index.mjs",
-    "postgenerate": "node scripts/generate-models-index.mjs",
-    "migrate:dev": "prisma migrate dev",
-    "patch": "npm version patch && npm run build && npm publish --access public",
-    "publish:public": "npm publish --access public"
   }
-}
+}