vr-models 1.0.56 → 1.0.57

package/dist/models/devicePaymentPlan.models.d.ts

@@ -2,6 +2,7 @@ import { Model, InferAttributes, InferCreationAttributes, CreationOptional, NonA
 import type { Device } from "./device.models";
 import type { User } from "./user.models";
 import type { Installment } from "./installment.models";
+import { Payment } from "./payment.models";
 export type PaymentPlanStatus = "ACTIVE" | "COMPLETED" | "DEFAULTED" | "CANCELLED";
 export declare const PAYMENT_PLAN_STATUS: readonly ["ACTIVE", "COMPLETED", "DEFAULTED", "CANCELLED"];
 export interface DevicePaymentPlanAttributes {
@@ -19,6 +20,7 @@ export interface DevicePaymentPlanAttributes {
     devices?: Device[];
     user: User;
     installments?: Installment[];
+    payment?: Payment;
 }
 export interface DevicePaymentPlanCreationAttributes extends Omit<DevicePaymentPlanAttributes, "id" | "createdAt" | "updatedAt" | "paidAmount" | "outstandingAmount" | "lastPaymentAt" | "nextInstallmentDueAt" | "status" | "completedAt" | "devices" | "installments"> {
     id?: string;
@@ -41,6 +43,7 @@ export declare class DevicePaymentPlan extends Model<InferAttributes<DevicePayme
     devices?: NonAttribute<Device[]>;
     user: NonAttribute<User>;
     installments?: NonAttribute<Installment[]>;
+    payment?: NonAttribute<Payment>;
     static initialize(sequelize: any): void;
     static associate(models: Record<string, ModelStatic<Model>>): void;
     updateProgress(): Promise<void>;

package/dist/models/devicePaymentPlan.models.js

@@ -91,6 +91,13 @@ class DevicePaymentPlan extends vr_migrations_1.Model {
             onDelete: "SET NULL", // ← This is SET NULL, not CASCADE
             onUpdate: "CASCADE",
         });
+        // One-to-One with Payment (down payment/full payment upfront)
+        this.hasOne(models.Payment, {
+            foreignKey: "devicePaymentPlanId",
+            as: "downPayment", // DevicePaymentPlan.getDownPayment()
+            onDelete: "SET NULL",
+            onUpdate: "CASCADE",
+        });
     }
     // Custom instance methods
     async updateProgress() {

package/dist/models/index.d.ts

@@ -7,10 +7,10 @@ export * from "./payment.models";
 export * from "./pricing.models";
 export * from "./product.models";
 export * from "./securityClearance.models";
-export * from "./transaction.models";
+export * from "./paymentEventLog.models";
 export * from "./installment.models";
 export * from "./ban.models";
 export * from "./suspension.models";
 export * from "./appSpecs.models";
 export * from "./phoneContact.models";
-export type { UserModel, TransactionModel, SecurityClearanceModel, ProductModel, PricingModel, PaymentModel, IdempotencyRecordModel, EventLogModel, DevicePaymentPlanModel, DeviceModel, InstallmentModel, BanModel, SuspensionModel, AppSpecsModel, PhoneContactModel, } from "./types";
+export type { UserModel, SecurityClearanceModel, ProductModel, PricingModel, PaymentModel, PaymentEventLogModel, IdempotencyRecordModel, EventLogModel, DevicePaymentPlanModel, DeviceModel, InstallmentModel, BanModel, SuspensionModel, AppSpecsModel, PhoneContactModel, } from "./types";

package/dist/models/index.js

@@ -23,7 +23,7 @@ __exportStar(require("./payment.models"), exports);
 __exportStar(require("./pricing.models"), exports);
 __exportStar(require("./product.models"), exports);
 __exportStar(require("./securityClearance.models"), exports);
-__exportStar(require("./transaction.models"), exports);
+__exportStar(require("./paymentEventLog.models"), exports);
 __exportStar(require("./installment.models"), exports);
 __exportStar(require("./ban.models"), exports);
 __exportStar(require("./suspension.models"), exports);

package/dist/models/payment.models.d.ts

@@ -1,65 +1,84 @@
 import { Model, InferAttributes, InferCreationAttributes, CreationOptional, NonAttribute, ModelStatic } from "vr-migrations";
 import type { User } from "./user.models";
 import type { DevicePaymentPlan } from "./devicePaymentPlan.models";
-import type { Transaction } from "./transaction.models";
+import type { Installment } from "./installment.models";
 import type { IdempotencyRecord } from "./idempotencyRecord.models";
-export type PaymentProvider = "mtn_momo" | "airtel_money";
-export type PaymentStatus = "PENDING" | "SUCCESSFUL" | "FAILED";
-export declare const PAYMENT_PROVIDER: readonly ["mtn_momo", "airtel_money"];
-export declare const PAYMENT_STATUS: readonly ["PENDING", "SUCCESSFUL", "FAILED"];
+import { PaymentEventLog } from "./paymentEventLog.models";
+export type PaymentProvider = "MTN_MOMO" | "AIRTEL_MONEY" | "DPO" | "FLUTTERWAVE";
+export type PaymentStatus = "PENDING" | "SUCCESSFUL" | "FAILED" | "REFUNDED";
+export declare const PAYMENT_PROVIDER: readonly ["MTN_MOMO", "AIRTEL_MONEY", "DPO", "FLUTTERWAVE"];
+export declare const PAYMENT_STATUS: readonly ["PENDING", "SUCCESSFUL", "FAILED", "REFUNDED"];
 export interface PaymentAttributes {
     id: string;
     userId: string;
-    devicePaymentPlanId: string;
-    transactionId: string | null;
+    devicePaymentPlanId: string | null;
+    installmentId: string | null;
     idempotencyKeyId: string | null;
     amount: number;
+    currency: string;
     provider: PaymentProvider;
     providerReference: string | null;
     status: PaymentStatus;
+    customerPhone: string;
+    customerName: string | null;
+    failureReason: string | null;
     metadata: Record<string, any>;
+    settledAt: Date | null;
     createdAt: Date;
     updatedAt: Date;
     user?: User;
     devicePaymentPlan?: DevicePaymentPlan;
-    transaction?: Transaction;
+    installment?: Installment;
     idempotencyKey?: IdempotencyRecord;
+    paymentEventLogs?: PaymentEventLog[];
 }
-export interface PaymentCreationAttributes extends Omit<PaymentAttributes, "id" | "createdAt" | "updatedAt" | "status" | "providerReference" | "metadata" | "transactionId" | "idempotencyKeyId"> {
+export interface PaymentCreationAttributes extends Omit<PaymentAttributes, "id" | "createdAt" | "updatedAt" | "status" | "providerReference" | "failureReason" | "settledAt" | "metadata"> {
     id?: string;
     status?: PaymentStatus;
     providerReference?: string | null;
+    failureReason?: string | null;
+    settledAt?: Date | null;
     metadata?: Record<string, any>;
-    transactionId?: string | null;
-    idempotencyKeyId?: string | null;
 }
 export declare class Payment extends Model<InferAttributes<Payment>, InferCreationAttributes<Payment>> implements PaymentAttributes {
     id: CreationOptional<string>;
     userId: string;
-    devicePaymentPlanId: string;
-    transactionId: CreationOptional<string | null>;
+    devicePaymentPlanId: CreationOptional<string | null>;
+    installmentId: CreationOptional<string | null>;
     idempotencyKeyId: CreationOptional<string | null>;
     amount: number;
+    currency: string;
     provider: PaymentProvider;
     providerReference: CreationOptional<string | null>;
     status: PaymentStatus;
+    customerPhone: string;
+    customerName: CreationOptional<string | null>;
+    failureReason: CreationOptional<string | null>;
     metadata: CreationOptional<Record<string, any>>;
+    settledAt: CreationOptional<Date | null>;
     readonly createdAt: CreationOptional<Date>;
     readonly updatedAt: CreationOptional<Date>;
     user?: NonAttribute<User>;
     devicePaymentPlan?: NonAttribute<DevicePaymentPlan>;
-    transaction?: NonAttribute<Transaction>;
+    installment?: NonAttribute<Installment>;
     idempotencyKey?: NonAttribute<IdempotencyRecord>;
+    paymentEventLogs?: NonAttribute<PaymentEventLog[]>;
     static initialize(sequelize: any): void;
     static associate(models: Record<string, ModelStatic<Model>>): void;
-    markAsSucceeded(providerReference: string, metadata?: Record<string, any>): Promise<void>;
+    markAsSuccessful(providerReference: string, metadata?: Record<string, any>): Promise<void>;
     markAsFailed(reason: string, metadata?: Record<string, any>): Promise<void>;
-    process(transactionId: string, idempotencyKeyId?: string): Promise<void>;
+    markAsRefunded(metadata?: Record<string, any>): Promise<void>;
+    markAsSettled(settledAt?: Date): Promise<void>;
     isSuccessful(): boolean;
     isPending(): boolean;
     isFailed(): boolean;
-    getProviderDisplayName(): string;
+    isRefunded(): boolean;
+    getFormattedAmount(): string;
+    getTargetType(): "payment_plan" | "installment";
+    getTargetId(): string;
     static getUserPayments(userId: string, limit?: number): Promise<Payment[]>;
-    static getPaymentPlanPayments(devicePaymentPlanId: string): Promise<Payment[]>;
+    static getPlanPayments(planId: string): Promise<Payment[]>;
+    static getInstallmentPayments(installmentId: string): Promise<Payment[]>;
+    static getPendingPayments(): Promise<Payment[]>;
 }
 export type PaymentModel = typeof Payment;

package/dist/models/payment.models.js

@@ -1,10 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Payment = exports.PAYMENT_STATUS = exports.PAYMENT_PROVIDER = void 0;
+// src/models/payment.models.ts
 const vr_migrations_1 = require("vr-migrations");
-// TYPES AS CONSTANTS
-exports.PAYMENT_PROVIDER = ["mtn_momo", "airtel_money"];
-exports.PAYMENT_STATUS = ["PENDING", "SUCCESSFUL", "FAILED"];
+exports.PAYMENT_PROVIDER = [
+    "MTN_MOMO",
+    "AIRTEL_MONEY",
+    "DPO",
+    "FLUTTERWAVE",
+];
+exports.PAYMENT_STATUS = [
+    "PENDING",
+    "SUCCESSFUL",
+    "FAILED",
+    "REFUNDED",
+];
 class Payment extends vr_migrations_1.Model {
     // Static initialization method
     static initialize(sequelize) {
@@ -14,43 +24,115 @@ class Payment extends vr_migrations_1.Model {
                 defaultValue: vr_migrations_1.DataTypes.UUIDV4,
                 primaryKey: true,
             },
-            userId: { type: vr_migrations_1.DataTypes.UUID, allowNull: false },
-            devicePaymentPlanId: { type: vr_migrations_1.DataTypes.UUID, allowNull: false },
-            transactionId: { type: vr_migrations_1.DataTypes.UUID, allowNull: true },
-            idempotencyKeyId: { type: vr_migrations_1.DataTypes.UUID, allowNull: true },
+            userId: {
+                type: vr_migrations_1.DataTypes.UUID,
+                allowNull: false,
+            },
+            devicePaymentPlanId: {
+                type: vr_migrations_1.DataTypes.UUID,
+                allowNull: true,
+            },
+            installmentId: {
+                type: vr_migrations_1.DataTypes.UUID,
+                allowNull: true,
+            },
+            idempotencyKeyId: {
+                type: vr_migrations_1.DataTypes.UUID,
+                allowNull: true,
+            },
             amount: {
-                type: vr_migrations_1.DataTypes.FLOAT,
+                type: vr_migrations_1.DataTypes.DECIMAL(10, 2),
                 allowNull: false,
                 validate: { min: 1 },
             },
+            currency: {
+                type: vr_migrations_1.DataTypes.STRING(3),
+                allowNull: false,
+                defaultValue: "RWF",
+            },
             provider: {
-                type: vr_migrations_1.DataTypes.ENUM("mtn_momo", "airtel_money"),
+                type: vr_migrations_1.DataTypes.ENUM("MTN_MOMO", "AIRTEL_MONEY", "DPO", "FLUTTERWAVE"),
                 allowNull: false,
             },
-            providerReference: { type: vr_migrations_1.DataTypes.STRING, allowNull: true },
+            providerReference: {
+                type: vr_migrations_1.DataTypes.STRING(255),
+                allowNull: true,
+            },
             status: {
-                type: vr_migrations_1.DataTypes.ENUM("PENDING", "SUCCESSFUL", "FAILED"),
+                type: vr_migrations_1.DataTypes.ENUM("PENDING", "SUCCESSFUL", "FAILED", "REFUNDED"),
                 allowNull: false,
                 defaultValue: "PENDING",
             },
+            customerPhone: {
+                type: vr_migrations_1.DataTypes.STRING(20),
+                allowNull: false,
+            },
+            customerName: {
+                type: vr_migrations_1.DataTypes.STRING(100),
+                allowNull: true,
+            },
+            failureReason: {
+                type: vr_migrations_1.DataTypes.TEXT,
+                allowNull: true,
+            },
             metadata: {
                 type: vr_migrations_1.DataTypes.JSONB,
                 allowNull: false,
                 defaultValue: {},
             },
-            createdAt: { type: vr_migrations_1.DataTypes.DATE, defaultValue: vr_migrations_1.DataTypes.NOW },
-            updatedAt: { type: vr_migrations_1.DataTypes.DATE, defaultValue: vr_migrations_1.DataTypes.NOW },
+            settledAt: {
+                type: vr_migrations_1.DataTypes.DATE,
+                allowNull: true,
+            },
+            createdAt: {
+                type: vr_migrations_1.DataTypes.DATE,
+                defaultValue: vr_migrations_1.DataTypes.NOW,
+            },
+            updatedAt: {
+                type: vr_migrations_1.DataTypes.DATE,
+                defaultValue: vr_migrations_1.DataTypes.NOW,
+            },
         }, {
             sequelize,
-            tableName: "payments",
             modelName: "Payment",
-            hooks: {
-                beforeUpdate: (payment) => {
-                    if (payment.status === "SUCCESSFUL" && !payment.providerReference) {
-                        throw new Error("providerReference is required for successful payments");
+            tableName: "payments",
+            timestamps: true,
+            freezeTableName: true,
+            validate: {
+                exactlyOneTarget() {
+                    const hasPlan = !!this.devicePaymentPlanId;
+                    const hasInstallment = !!this.installmentId;
+                    if ((hasPlan && hasInstallment) || (!hasPlan && !hasInstallment)) {
+                        throw new Error("Payment must belong to exactly one: devicePaymentPlanId OR installmentId");
                     }
                 },
             },
+            indexes: [
+                {
+                    fields: ["userId"],
+                    name: "payment_user_idx",
+                },
+                {
+                    fields: ["devicePaymentPlanId"],
+                    name: "payment_plan_idx",
+                },
+                {
+                    fields: ["installmentId"],
+                    name: "payment_installment_idx",
+                },
+                {
+                    fields: ["status"],
+                    name: "payment_status_idx",
+                },
+                {
+                    fields: ["providerReference"],
+                    name: "payment_provider_ref_idx",
+                },
+                {
+                    fields: ["createdAt"],
+                    name: "payment_created_at_idx",
+                },
+            ],
         });
     }
     // Static association method
@@ -64,12 +146,12 @@ class Payment extends vr_migrations_1.Model {
         this.belongsTo(models.DevicePaymentPlan, {
             foreignKey: "devicePaymentPlanId",
             as: "devicePaymentPlan",
-            onDelete: "RESTRICT",
+            onDelete: "SET NULL",
             onUpdate: "CASCADE",
         });
-        this.belongsTo(models.Transaction, {
-            foreignKey: "transactionId",
-            as: "transaction",
+        this.belongsTo(models.Installment, {
+            foreignKey: "installmentId",
+            as: "installment",
             onDelete: "SET NULL",
             onUpdate: "CASCADE",
         });
@@ -79,33 +161,49 @@ class Payment extends vr_migrations_1.Model {
             onDelete: "SET NULL",
             onUpdate: "CASCADE",
         });
+        this.hasMany(models.PaymentEventLog, {
+            foreignKey: "paymentId",
+            as: "eventLogs", // Payment.getEventLogs()
+            onDelete: "SET NULL",
+        });
     }
     // Custom instance methods
-    async markAsSucceeded(providerReference, metadata) {
+    async markAsSuccessful(providerReference, metadata) {
         this.status = "SUCCESSFUL";
         this.providerReference = providerReference;
         if (metadata) {
             this.metadata = { ...this.metadata, ...metadata };
         }
         await this.save();
+        // If this payment is for an installment, mark it as paid
+        if (this.installmentId) {
+            const Installment = this.constructor.sequelize.models
+                .Installment;
+            const installment = await Installment.findByPk(this.installmentId);
+            if (installment && installment.status !== "PAID") {
+                await installment.markAsPaid(this.id);
+            }
+        }
     }
     async markAsFailed(reason, metadata) {
         this.status = "FAILED";
-        const failureMetadata = {
-            failureReason: reason,
-            failedAt: new Date().toISOString(),
-            ...metadata,
-        };
-        this.metadata = { ...this.metadata, ...failureMetadata };
+        this.failureReason = reason;
+        if (metadata) {
+            this.metadata = { ...this.metadata, ...metadata };
+        }
         await this.save();
     }
-    async process(transactionId, idempotencyKeyId) {
-        this.transactionId = transactionId;
-        if (idempotencyKeyId) {
-            this.idempotencyKeyId = idempotencyKeyId;
+    async markAsRefunded(metadata) {
+        this.status = "REFUNDED";
+        if (metadata) {
+            this.metadata = { ...this.metadata, ...metadata };
         }
         await this.save();
     }
+    async markAsSettled(settledAt = new Date()) {
+        this.settledAt = settledAt;
+        await this.save();
+    }
     isSuccessful() {
         return this.status === "SUCCESSFUL";
     }
@@ -115,26 +213,42 @@ class Payment extends vr_migrations_1.Model {
     isFailed() {
         return this.status === "FAILED";
     }
-    getProviderDisplayName() {
-        switch (this.provider) {
-            case "mtn_momo":
-                return "MTN Mobile Money";
-            case "airtel_money":
-                return "Airtel Money";
-            default:
-                return this.provider;
-        }
+    isRefunded() {
+        return this.status === "REFUNDED";
+    }
+    getFormattedAmount() {
+        return `${this.currency} ${this.amount.toLocaleString()}`;
+    }
+    getTargetType() {
+        return this.devicePaymentPlanId ? "payment_plan" : "installment";
     }
+    getTargetId() {
+        return (this.devicePaymentPlanId || this.installmentId);
+    }
+    // Static methods
     static async getUserPayments(userId, limit = 50) {
         return await this.findAll({
             where: { userId },
             order: [["createdAt", "DESC"]],
             limit,
+            include: ["devicePaymentPlan", "installment"],
+        });
+    }
+    static async getPlanPayments(planId) {
+        return await this.findAll({
+            where: { devicePaymentPlanId: planId },
+            order: [["createdAt", "ASC"]],
+        });
+    }
+    static async getInstallmentPayments(installmentId) {
+        return await this.findAll({
+            where: { installmentId },
+            order: [["createdAt", "ASC"]],
         });
     }
-    static async getPaymentPlanPayments(devicePaymentPlanId) {
+    static async getPendingPayments() {
         return await this.findAll({
-            where: { devicePaymentPlanId },
+            where: { status: "PENDING" },
             order: [["createdAt", "ASC"]],
         });
     }

package/dist/models/paymentEventLog.models.d.ts

@@ -0,0 +1,69 @@
+import { Model, InferAttributes, InferCreationAttributes, CreationOptional, ModelStatic, NonAttribute } from "vr-migrations";
+import type { Payment } from "./payment.models";
+export type EventDirection = "OUTGOING_REQUEST" | "INCOMING_WEBHOOK";
+export type EventStatus = "PENDING" | "SUCCESS" | "FAILED" | "RETRIED";
+export declare const EVENT_DIRECTION: readonly ["OUTGOING_REQUEST", "INCOMING_WEBHOOK"];
+export declare const EVENT_STATUS: readonly ["PENDING", "SUCCESS", "FAILED", "RETRIED"];
+export interface PaymentEventLogAttributes {
+    id: string;
+    paymentId: string | null;
+    provider: string;
+    direction: EventDirection;
+    action: string;
+    externalId: string | null;
+    requestPayload: Record<string, any> | null;
+    responsePayload: Record<string, any> | null;
+    statusCode: number | null;
+    status: EventStatus;
+    error: string | null;
+    durationMs: number | null;
+    retryCount: number;
+    nextRetryAt: Date | null;
+    processedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface PaymentEventLogCreationAttributes extends Omit<PaymentEventLogAttributes, "id" | "createdAt" | "updatedAt" | "status" | "error" | "retryCount" | "nextRetryAt" | "processedAt" | "durationMs"> {
+    id?: string;
+    status?: EventStatus;
+    error?: string | null;
+    retryCount?: number;
+    nextRetryAt?: Date | null;
+    processedAt?: Date | null;
+    durationMs?: number | null;
+    payment?: Payment;
+}
+export declare class PaymentEventLog extends Model<InferAttributes<PaymentEventLog>, InferCreationAttributes<PaymentEventLog>> implements PaymentEventLogAttributes {
+    id: CreationOptional<string>;
+    paymentId: CreationOptional<string | null>;
+    provider: string;
+    direction: EventDirection;
+    action: string;
+    externalId: CreationOptional<string | null>;
+    requestPayload: CreationOptional<Record<string, any> | null>;
+    responsePayload: CreationOptional<Record<string, any> | null>;
+    statusCode: CreationOptional<number | null>;
+    status: EventStatus;
+    error: CreationOptional<string | null>;
+    durationMs: CreationOptional<number | null>;
+    retryCount: CreationOptional<number>;
+    nextRetryAt: CreationOptional<Date | null>;
+    processedAt: CreationOptional<Date | null>;
+    payment?: NonAttribute<Payment>;
+    readonly createdAt: CreationOptional<Date>;
+    readonly updatedAt: CreationOptional<Date>;
+    static initialize(sequelize: any): void;
+    static associate(models: Record<string, ModelStatic<Model>>): void;
+    markAsSuccess(durationMs?: number): Promise<void>;
+    markAsFailed(error: string, durationMs?: number): Promise<void>;
+    scheduleRetry(retryAfterSeconds: number): Promise<void>;
+    isPending(): boolean;
+    isSuccess(): boolean;
+    isFailed(): boolean;
+    isRetryable(): boolean;
+    static getUnprocessedWebhooks(limit?: number): Promise<PaymentEventLog[]>;
+    static getPendingRetries(): Promise<PaymentEventLog[]>;
+    static getPaymentEvents(paymentId: string): Promise<PaymentEventLog[]>;
+    static getProviderEvents(provider: string, externalId: string): Promise<PaymentEventLog[]>;
+}
+export type PaymentEventLogModel = typeof PaymentEventLog;

package/dist/models/paymentEventLog.models.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentEventLog = exports.EVENT_STATUS = exports.EVENT_DIRECTION = void 0;
+// src/models/paymentEventLog.models.ts
+const vr_migrations_1 = require("vr-migrations");
+exports.EVENT_DIRECTION = [
+    "OUTGOING_REQUEST",
+    "INCOMING_WEBHOOK",
+];
+exports.EVENT_STATUS = [
+    "PENDING",
+    "SUCCESS",
+    "FAILED",
+    "RETRIED",
+];
+class PaymentEventLog extends vr_migrations_1.Model {
+    // Static initialization method
+    static initialize(sequelize) {
+        this.init({
+            id: {
+                type: vr_migrations_1.DataTypes.UUID,
+                defaultValue: vr_migrations_1.DataTypes.UUIDV4,
+                primaryKey: true,
+            },
+            paymentId: {
+                type: vr_migrations_1.DataTypes.UUID,
+                allowNull: true,
+                references: {
+                    model: "payments",
+                    key: "id",
+                },
+            },
+            provider: {
+                type: vr_migrations_1.DataTypes.STRING(50),
+                allowNull: false,
+            },
+            direction: {
+                type: vr_migrations_1.DataTypes.ENUM("OUTGOING_REQUEST", "INCOMING_WEBHOOK"),
+                allowNull: false,
+            },
+            action: {
+                type: vr_migrations_1.DataTypes.STRING(50),
+                allowNull: false,
+            },
+            externalId: {
+                type: vr_migrations_1.DataTypes.STRING(255),
+                allowNull: true,
+            },
+            requestPayload: {
+                type: vr_migrations_1.DataTypes.JSONB,
+                allowNull: true,
+            },
+            responsePayload: {
+                type: vr_migrations_1.DataTypes.JSONB,
+                allowNull: true,
+            },
+            statusCode: {
+                type: vr_migrations_1.DataTypes.INTEGER,
+                allowNull: true,
+            },
+            status: {
+                type: vr_migrations_1.DataTypes.ENUM("PENDING", "SUCCESS", "FAILED", "RETRIED"),
+                allowNull: false,
+                defaultValue: "PENDING",
+            },
+            error: {
+                type: vr_migrations_1.DataTypes.TEXT,
+                allowNull: true,
+            },
+            durationMs: {
+                type: vr_migrations_1.DataTypes.INTEGER,
+                allowNull: true,
+            },
+            retryCount: {
+                type: vr_migrations_1.DataTypes.INTEGER,
+                allowNull: false,
+                defaultValue: 0,
+            },
+            nextRetryAt: {
+                type: vr_migrations_1.DataTypes.DATE,
+                allowNull: true,
+            },
+            processedAt: {
+                type: vr_migrations_1.DataTypes.DATE,
+                allowNull: true,
+            },
+            createdAt: {
+                type: vr_migrations_1.DataTypes.DATE,
+                defaultValue: vr_migrations_1.DataTypes.NOW,
+            },
+            updatedAt: {
+                type: vr_migrations_1.DataTypes.DATE,
+                defaultValue: vr_migrations_1.DataTypes.NOW,
+            },
+        }, {
+            sequelize,
+            modelName: "PaymentEventLog",
+            tableName: "payment_event_logs",
+            timestamps: true,
+            freezeTableName: true,
+            indexes: [
+                {
+                    fields: ["paymentId"],
+                    name: "payment_event_payment_idx",
+                },
+                {
+                    fields: ["provider", "externalId"],
+                    name: "payment_event_provider_external_idx",
+                },
+                {
+                    fields: ["status", "nextRetryAt"],
+                    name: "payment_event_retry_idx",
+                },
+                {
+                    fields: ["createdAt"],
+                    name: "payment_event_created_at_idx",
+                },
+                {
+                    fields: ["direction", "action"],
+                    name: "payment_event_direction_action_idx",
+                },
+            ],
+        });
+    }
+    // Static association method
+    static associate(models) {
+        this.belongsTo(models.Payment, {
+            foreignKey: "paymentId",
+            as: "payment",
+            onDelete: "SET NULL",
+            onUpdate: "CASCADE",
+        });
+    }
+    // Custom instance methods
+    async markAsSuccess(durationMs) {
+        this.status = "SUCCESS";
+        this.processedAt = new Date();
+        if (durationMs !== undefined) {
+            this.durationMs = durationMs;
+        }
+        await this.save();
+    }
+    async markAsFailed(error, durationMs) {
+        this.status = "FAILED";
+        this.error = error;
+        this.processedAt = new Date();
+        if (durationMs !== undefined) {
+            this.durationMs = durationMs;
+        }
+        await this.save();
+    }
+    async scheduleRetry(retryAfterSeconds) {
+        this.status = "RETRIED";
+        this.retryCount += 1;
+        this.nextRetryAt = new Date(Date.now() + retryAfterSeconds * 1000);
+        await this.save();
+    }
+    isPending() {
+        return this.status === "PENDING";
+    }
+    isSuccess() {
+        return this.status === "SUCCESS";
+    }
+    isFailed() {
+        return this.status === "FAILED";
+    }
+    isRetryable() {
+        return this.status === "FAILED" && this.retryCount < 5;
+    }
+    // Static methods
+    static async getUnprocessedWebhooks(limit = 100) {
+        return await this.findAll({
+            where: {
+                direction: "INCOMING_WEBHOOK",
+                status: "PENDING",
+                processedAt: null,
+            },
+            limit,
+            order: [["createdAt", "ASC"]],
+        });
+    }
+    static async getPendingRetries() {
+        return await this.findAll({
+            where: {
+                status: "RETRIED",
+                nextRetryAt: { [vr_migrations_1.Op.lte]: new Date() },
+            },
+            order: [["nextRetryAt", "ASC"]],
+        });
+    }
+    static async getPaymentEvents(paymentId) {
+        return await this.findAll({
+            where: { paymentId },
+            order: [["createdAt", "ASC"]],
+        });
+    }
+    static async getProviderEvents(provider, externalId) {
+        return await this.findAll({
+            where: { provider, externalId },
+            order: [["createdAt", "ASC"]],
+        });
+    }
+}
+exports.PaymentEventLog = PaymentEventLog;

package/dist/models/types.d.ts

@@ -1,5 +1,4 @@
 export type { UserModel } from "./user.models";
-export type { TransactionModel } from "./transaction.models";
 export type { SecurityClearanceModel } from "./securityClearance.models";
 export type { ProductModel } from "./product.models";
 export type { PricingModel } from "./pricing.models";
@@ -13,3 +12,4 @@ export type { BanModel } from "./ban.models";
 export type { SuspensionModel } from "./suspension.models";
 export type { AppSpecsModel } from "./appSpecs.models";
 export type { PhoneContactModel } from "./phoneContact.models";
+export type { PaymentEventLogModel } from "./paymentEventLog.models";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vr-models",
-  "version": "1.0.56",
+  "version": "1.0.57",
   "description": "Shared database models package for VR applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/models/transaction.models.d.ts

@@ -1,44 +0,0 @@
-import { Model, InferAttributes, InferCreationAttributes, CreationOptional, NonAttribute, ModelStatic } from "vr-migrations";
-import type { Payment } from "./payment.models";
-import type { User } from "./user.models";
-export type TransactionStatus = "succeeded" | "failed";
-export interface TransactionAttributes {
-    id: string;
-    userId: string;
-    paymentId: string;
-    amount: number;
-    status: TransactionStatus;
-    providerReference: string;
-    metadata: Record<string, any>;
-    createdAt: Date;
-    updatedAt: Date;
-    payment?: Payment;
-    user?: User;
-}
-export interface TransactionCreationAttributes extends Omit<TransactionAttributes, "id" | "createdAt" | "updatedAt" | "metadata"> {
-    id?: string;
-    metadata?: Record<string, any>;
-}
-export declare class Transaction extends Model<InferAttributes<Transaction>, InferCreationAttributes<Transaction>> implements TransactionAttributes {
-    id: CreationOptional<string>;
-    userId: string;
-    paymentId: string;
-    amount: number;
-    status: TransactionStatus;
-    providerReference: string;
-    metadata: CreationOptional<Record<string, any>>;
-    readonly createdAt: CreationOptional<Date>;
-    readonly updatedAt: CreationOptional<Date>;
-    payment?: NonAttribute<Payment>;
-    user?: NonAttribute<User>;
-    static initialize(sequelize: any): void;
-    static associate(models: Record<string, ModelStatic<Model>>): void;
-    markAsSucceeded(metadata?: Record<string, any>): Promise<void>;
-    markAsFailed(reason: string, metadata?: Record<string, any>): Promise<void>;
-    isSuccessful(): boolean;
-    isFailed(): boolean;
-    getFormattedAmount(): string;
-    static getUserTransactions(userId: string, limit?: number): Promise<Transaction[]>;
-    static getPaymentTransactions(paymentId: string): Promise<Transaction[]>;
-}
-export type TransactionModel = typeof Transaction;

package/dist/models/transaction.models.js

@@ -1,97 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Transaction = void 0;
-const vr_migrations_1 = require("vr-migrations");
-class Transaction extends vr_migrations_1.Model {
-    // Static initialization method
-    static initialize(sequelize) {
-        this.init({
-            id: {
-                type: vr_migrations_1.DataTypes.UUID,
-                defaultValue: vr_migrations_1.DataTypes.UUIDV4,
-                primaryKey: true,
-            },
-            userId: { type: vr_migrations_1.DataTypes.UUID, allowNull: false },
-            paymentId: { type: vr_migrations_1.DataTypes.UUID, allowNull: false },
-            amount: {
-                type: vr_migrations_1.DataTypes.FLOAT,
-                allowNull: false,
-                validate: { min: 1 },
-            },
-            status: {
-                type: vr_migrations_1.DataTypes.ENUM("succeeded", "failed"),
-                allowNull: false,
-            },
-            providerReference: { type: vr_migrations_1.DataTypes.STRING, allowNull: false },
-            metadata: {
-                type: vr_migrations_1.DataTypes.JSONB,
-                allowNull: false,
-                defaultValue: {},
-            },
-            createdAt: { type: vr_migrations_1.DataTypes.DATE, defaultValue: vr_migrations_1.DataTypes.NOW },
-            updatedAt: { type: vr_migrations_1.DataTypes.DATE, defaultValue: vr_migrations_1.DataTypes.NOW },
-        }, {
-            sequelize,
-            tableName: "transactions",
-            modelName: "Transaction",
-            timestamps: true,
-        });
-    }
-    // Static association method
-    static associate(models) {
-        this.belongsTo(models.Payment, {
-            foreignKey: "paymentId",
-            as: "payment",
-            onDelete: "SET NULL", // ← This is SET NULL, not CASCADE
-            onUpdate: "CASCADE",
-        });
-        this.belongsTo(models.User, {
-            foreignKey: "userId",
-            as: "user",
-            onDelete: "RESTRICT",
-            onUpdate: "CASCADE",
-        });
-    }
-    // Custom instance methods
-    async markAsSucceeded(metadata) {
-        this.status = "succeeded";
-        if (metadata) {
-            this.metadata = { ...this.metadata, ...metadata };
-        }
-        await this.save();
-    }
-    async markAsFailed(reason, metadata) {
-        this.status = "failed";
-        const failureMetadata = {
-            failureReason: reason,
-            failedAt: new Date().toISOString(),
-            ...metadata,
-        };
-        this.metadata = { ...this.metadata, ...failureMetadata };
-        await this.save();
-    }
-    isSuccessful() {
-        return this.status === "succeeded";
-    }
-    isFailed() {
-        return this.status === "failed";
-    }
-    getFormattedAmount() {
-        return `RWF ${this.amount.toLocaleString()}`;
-    }
-    static async getUserTransactions(userId, limit = 50) {
-        return await this.findAll({
-            where: { userId },
-            order: [["createdAt", "DESC"]],
-            limit,
-            include: ["payment"],
-        });
-    }
-    static async getPaymentTransactions(paymentId) {
-        return await this.findAll({
-            where: { paymentId },
-            order: [["createdAt", "DESC"]],
-        });
-    }
-}
-exports.Transaction = Transaction;