payservedb 8.9.1 → 8.9.2

package/index.js

@@ -196,6 +196,7 @@ const models = {
   FacilityDepartment: require("./src/models/facility_departements"),
   EmailSmsQueue: require("./src/models/email_sms_queue"),
   PurchaseOrderInvoice: require("./src/models/purchaseOrderInvoice"),
+  PowerInvoice: require("./src/models/power_invoice"),
   PowerMeterCustomerBand: require("./src/models/powerMeterCustomerBand"),
   PowerMeterCommunicationProtocol: require("./src/models/powerMeterCommunicationProtocol"),
   PowerMeterDailyReading: require("./src/models/powerMeterDailyReading"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payservedb",
-  "version": "8.9.1",
+  "version": "8.9.2",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

package/src/models/leaseagreement.js

@@ -105,6 +105,12 @@ const leaseAgreementSchema = new mongoose.Schema({
         securityDeposit: { type: Number, required: true },
         balanceBroughtForward: { type: Number, required: true, default: 0 },
         taxEnabled: { type: Boolean, default: false },
+        enabledTaxes: [
+            {
+                type: mongoose.Schema.Types.ObjectId,
+                ref: 'CountryTaxRate'
+            }
+        ],
         penaltyId: {
             type: mongoose.Schema.Types.ObjectId,
             ref: 'Penalty'

package/src/models/levycontract.js

@@ -49,10 +49,12 @@ const LevyContractSchema = new Schema(
             type: Boolean,
             default: true
         },
-        whtEnabled: {
-            type: Boolean,
-            default: false
-        },
+        enabledTaxes: [
+            {
+                type: mongoose.Schema.Types.ObjectId,
+                ref: 'CountryTaxRate'
+            }
+        ],
         paymentFrequency: {
             type: String,
             enum: ['Daily', 'Weekly', 'Bi-Weekly', 'Monthly', 'Quarterly', 'Semi-Annually', 'Annually'],

package/src/models/power_invoice.js

@@ -0,0 +1,471 @@
+const mongoose = require('mongoose');
+
+const powerInvoiceSchema = new mongoose.Schema(
+  {
+    // ── Basic Identifiers ──────────────────────────────────────────────────────
+    invoiceNumber: {
+      type: String,
+      required: true,
+      unique: true,
+    },
+    accountNumber: {
+      type: String,
+      required: true,
+    },
+    unitName: {
+      type: String,
+      required: true,
+    },
+    yearMonth: {
+      type: String,
+      required: true,
+      // Format: "YYYY-MM" e.g. "2025-03"
+    },
+    facilityId: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: true,
+    },
+    customerId: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: true,
+    },
+    billingType: {
+      type: String,
+      enum: ['postpaid'],
+      default: 'postpaid',
+    },
+    balanceBroughtForward: {
+      type: Number,
+      default: 0,
+      // Positive = arrears carried forward; Negative = credit from overpayment
+    },
+
+    // ── Payment Methods ────────────────────────────────────────────────────────
+    paymentMethods: {
+      mobilePayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'FacilityPaymentDetails',
+        },
+      },
+      bankPayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'BankDetails',
+        },
+      },
+      cashPayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+      },
+    },
+    paymentMethod: {
+      type: String,
+      enum: ['mobile', 'bank', 'cash', 'mixed'],
+      default: null,
+    },
+
+    // ── Biller Address ─────────────────────────────────────────────────────────
+    billerAddress: {
+      name: {
+        type: String,
+        required: [true, 'Biller name is required'],
+        trim: true,
+        minlength: [1, 'Biller name must be at least 1 character long'],
+      },
+      email: {
+        type: String,
+        trim: true,
+        lowercase: true,
+        validate: {
+          validator: function (v) {
+            return !v || /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(v);
+          },
+          message: 'Please enter a valid email address',
+        },
+      },
+      phone: {
+        type: String,
+        required: [true, 'Biller phone is required'],
+        trim: true,
+      },
+      address: {
+        type: String,
+        required: [true, 'Biller address is required'],
+        trim: true,
+      },
+      city: {
+        type: String,
+        trim: true,
+      },
+    },
+
+    // ── Dates ──────────────────────────────────────────────────────────────────
+    dateIssued: {
+      type: Date,
+      default: Date.now,
+    },
+    dueDate: {
+      type: Date,
+      required: true,
+    },
+
+    // ── Customer Info (denormalised snapshot) ──────────────────────────────────
+    CustomerInfo: {
+      fullName: {
+        type: String,
+        required: true,
+        trim: true,
+      },
+    },
+
+    // ── Meter & Consumption ────────────────────────────────────────────────────
+    meterNumber: {
+      type: String,
+      required: true,
+    },
+    tariff: {
+      type: String,
+      required: true,
+      // e.g. "Domestic Lifeline", "Domestic Ordinary 1", "Domestic Ordinary 2",
+      //      "Commercial Low Voltage", "Industrial Low Voltage"
+    },
+    meterReadings: {
+      previousReading: {
+        type: Number,
+        required: true,
+      },
+      currentReading: {
+        type: Number,
+        required: true,
+      },
+      usage: {
+        type: Number,
+        required: true,
+        // kWh consumed = currentReading - previousReading
+      },
+    },
+    consumptionPeriod: {
+      startDate: {
+        type: Date,
+        required: true,
+      },
+      endDate: {
+        type: Date,
+        required: true,
+      },
+    },
+
+    // ── Power Charges ──────────────────────────────────────────────────────────
+    // All monetary values are in the invoice currency (default KES).
+    powerCharges: {
+      tariff: {
+        type: String,
+        // Mirror of the top-level tariff field; stored here for invoice snapshot
+      },
+      yearMonth: {
+        type: String,
+        // Mirror of the top-level yearMonth; stored for historical rate lookups
+      },
+
+      // Core energy charge based on units consumed and applicable tariff block
+      energyCharge: {
+        type: Number,
+        required: true,
+        default: 0,
+      },
+
+      // Fuel Cost Charge (FCC) – passed through from EPRA-approved fuel levy
+      fuelCostCharge: {
+        type: Number,
+        default: 0,
+      },
+
+      // Foreign Exchange Fluctuation Adjustment
+      forexAdjustment: {
+        type: Number,
+        default: 0,
+      },
+
+      // Inflation Adjustment Charge
+      inflationAdjustment: {
+        type: Number,
+        default: 0,
+      },
+
+      // Water Resource Management Levy (WRML)
+      waterResourceManagementLevy: {
+        type: Number,
+        default: 0,
+      },
+
+      // Energy Regulatory Levy (ERL)
+      energyRegulatoryLevy: {
+        type: Number,
+        default: 0,
+      },
+
+      // Rural Electrification & Renewable Energy Levy (REL)
+      ruralElectrificationLevy: {
+        type: Number,
+        default: 0,
+      },
+
+      // Power Factor Surcharge (applied to commercial/industrial customers only)
+      powerFactorSurcharge: {
+        type: Number,
+        default: 0,
+      },
+
+      // Value Added Tax amount
+      valueAddedTax: {
+        type: Number,
+        default: 0,
+      },
+
+      // VAT rate applied (%) – captured at time of billing; typically 16
+      vatPercentage: {
+        type: Number,
+        default: 16,
+      },
+
+      // Rural Electrification Programme levy percentage (%) – typically 5
+      repPercentage: {
+        type: Number,
+        default: 5,
+      },
+
+      // Grand total = sum of all charges above
+      totalCharge: {
+        type: Number,
+        required: true,
+      },
+    },
+
+    // ── Payment & Reconciliation ───────────────────────────────────────────────
+    amountPaid: {
+      type: Number,
+      default: 0,
+    },
+
+    // ── Invoice Note & Status ──────────────────────────────────────────────────
+    invoiceNote: {
+      type: String,
+      default: 'Payment is due within 10 days',
+    },
+    status: {
+      type: String,
+      required: true,
+      enum: ['Pending', 'Paid', 'Partially Paid', 'Cancelled', 'Overdue', 'Unpaid'],
+      default: 'Unpaid',
+    },
+
+    // ── View / Read Status 
+    viewStatus: {
+      isOpened: {
+        type: Boolean,
+        default: false,
+      },
+      openedAt: {
+        type: Date,
+        default: null,
+      },
+    },
+
+    // ── Currency 
+    currency: {
+      id: {
+        type: mongoose.Schema.Types.ObjectId,
+      },
+      name: {
+        type: String,
+        default: 'Kenyan Shilling',
+      },
+      code: {
+        type: String,
+        default: 'KES',
+      },
+      symbol: {
+        type: String,
+        default: 'KSh',
+      },
+    },
+
+    // ── Notification Tracking 
+    notificationsSent: {
+      type: {
+        sms: {
+          type: Boolean,
+          default: false,
+        },
+        email: {
+          type: Boolean,
+          default: false,
+        },
+        sentAt: {
+          type: Date,
+          default: null,
+        },
+        lastAttempt: {
+          type: Date,
+          default: null,
+        },
+        attempts: {
+          type: Number,
+          default: 0,
+        },
+        smsDetails: {
+          type: {
+            success: Boolean,
+            error: String,
+            sentAt: Date,
+            phoneNumber: String,
+          },
+          default: null,
+        },
+        emailDetails: {
+          type: {
+            success: Boolean,
+            error: String,
+            sentAt: Date,
+            emailAddress: String,
+          },
+          default: null,
+        },
+      },
+      default: {
+        sms: false,
+        email: false,
+        sentAt: null,
+        lastAttempt: null,
+        attempts: 0,
+        smsDetails: null,
+        emailDetails: null,
+      },
+    },
+
+    //   Reconciliation History 
+    reconciliationHistory: [
+      {
+        date: {
+          type: Date,
+          default: Date.now,
+        },
+        amount: {
+          type: Number,
+          required: true,
+        },
+        type: {
+          type: String,
+          default: 'Manual',
+          // e.g. 'Manual', 'M-Pesa', 'Bank Transfer', 'Cash'
+        },
+        paymentReference: {
+          type: String,
+        },
+        paymentCompletion: {
+          type: String,
+          default: 'Completed',
+        },
+        sourceInvoice: {
+          type: String,
+        },
+        destinationInvoice: {
+          type: String,
+        },
+        notes: {
+          type: String,
+        },
+        remainingBalance: {
+          type: Number,
+        },
+      },
+    ],
+  },
+  {
+    timestamps: true,
+  }
+);
+
+//  Pre-save middleware
+
+powerInvoiceSchema.pre('save', function (next) {
+  // 1. Auto-mark overdue
+  if (this.isModified('dueDate') || this.isNew) {
+    const today = new Date();
+    if (this.dueDate < today && this.status === 'Pending') {
+      this.status = 'Overdue';
+    }
+  }
+
+  // 2. Sync powerCharges snapshot fields with top-level fields
+  if (this.isNew || this.isModified('tariff')) {
+    if (this.powerCharges && !this.powerCharges.tariff) {
+      this.powerCharges.tariff = this.tariff;
+    }
+  }
+  if (this.isNew || this.isModified('yearMonth')) {
+    if (this.powerCharges && !this.powerCharges.yearMonth) {
+      this.powerCharges.yearMonth = this.yearMonth;
+    }
+  }
+
+  // 3. Update payment method flags from reconciliation history
+  if (this.isModified('reconciliationHistory') || this.isNew) {
+    if (this.reconciliationHistory && this.reconciliationHistory.length > 0) {
+      const latestPayment = this.reconciliationHistory[this.reconciliationHistory.length - 1];
+      const paymentType = latestPayment.type?.toLowerCase();
+
+      if (!this.paymentMethods) {
+        this.paymentMethods = {
+          mobilePayment: { status: false },
+          bankPayment: { status: false },
+          cashPayment: { status: false },
+        };
+      }
+
+      if (
+        paymentType &&
+        (paymentType.includes('mobile') ||
+          paymentType.includes('mpesa') ||
+          paymentType.includes('m-pesa'))
+      ) {
+        this.paymentMethods.mobilePayment.status = true;
+        this.paymentMethod = 'mobile';
+      } else if (paymentType && paymentType.includes('bank')) {
+        this.paymentMethods.bankPayment.status = true;
+        this.paymentMethod = 'bank';
+      } else if (paymentType && paymentType.includes('cash')) {
+        this.paymentMethods.cashPayment.status = true;
+        this.paymentMethod = 'cash';
+      } else {
+        // Default: treat unspecified / manual payments as cash
+        this.paymentMethods.cashPayment.status = true;
+        this.paymentMethod = 'cash';
+      }
+    }
+  }
+
+  next();
+});
+
+// Indexes 
+powerInvoiceSchema.index({ facilityId: 1, yearMonth: -1 });
+powerInvoiceSchema.index({ customerId: 1 });
+powerInvoiceSchema.index({ status: 1 });
+powerInvoiceSchema.index({ meterNumber: 1 });
+powerInvoiceSchema.index({ accountNumber: 1 });
+
+const PowerInvoice = mongoose.model('PowerInvoice', powerInvoiceSchema);
+
+module.exports = PowerInvoice;