payservedb 8.9.0 → 8.9.2

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;

package/src/models/power_meter_account.js

@@ -1,81 +1,81 @@
-const mongoose = require('mongoose');
-
-const powerMeterAccountSchema = new mongoose.Schema({
-    facilityId: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: 'Facility',
-        required: true,
-    },
-    account_no: {
-        type: String,
-        required: true,
-        trim: true
-    },
-    customerId: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: 'Customer',
-    },
-    customerName: {
-        type: String,
-        required: true,
-        trim: true
-    },
-    phoneNumber: {
-        type: String,
-        required: true,
-        trim: true
-    },
-    email: {
-        type: String,
-        trim: true
-    },
-    deviceId: {
-        type: String,
-        required: true,
-        unique: true,
-        trim: true
-    },
-    unitId: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: 'Unit',
-    },
-    payment_type: {
-        type: String,
-        required: true,
-        enum: ['Postpaid', 'Prepaid', 'Token Based']
-    },
-    previousReading: {
-        type: Number,
-        required: true,
-        default: 0
-    },
-    currentReading: {
-        type: Number,
-        required: true
-    },
-    status: {
-        type: String,
-        required: true,
-        enum: ['Active', 'Inactive'],
-        default: 'Active'
-    },
-    created_on: {
-        type: Date,
-        required: true,
-        default: Date.now
-    },
-    meterId: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: 'PowerMeters',
-    },
-    accountBalance: {
-        type: Number,
-        default: 0
-    }
-}, {
-    timestamps: true
-});
-
-const PowerMeterAccount = mongoose.model('PowerMeterAccount', powerMeterAccountSchema);
-
-module.exports = PowerMeterAccount;
+const mongoose = require('mongoose');
+
+const powerMeterAccountSchema = new mongoose.Schema({
+    facilityId: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: 'Facility',
+        required: true,
+    },
+    account_no: {
+        type: String,
+        required: true,
+        trim: true
+    },
+    customerId: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: 'Customer',
+    },
+    customerName: {
+        type: String,
+        required: true,
+        trim: true
+    },
+    phoneNumber: {
+        type: String,
+        required: true,
+        trim: true
+    },
+    email: {
+        type: String,
+        trim: true
+    },
+    deviceId: {
+        type: String,
+        required: true,
+        unique: true,
+        trim: true
+    },
+    unitId: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: 'Unit',
+    },
+    payment_type: {
+        type: String,
+        required: true,
+        enum: ['Postpaid', 'Prepaid', 'Token Based']
+    },
+    previousReading: {
+        type: Number,
+        required: true,
+        default: 0
+    },
+    currentReading: {
+        type: Number,
+        required: true
+    },
+    status: {
+        type: String,
+        required: true,
+        enum: ['Active', 'Inactive'],
+        default: 'Active'
+    },
+    created_on: {
+        type: Date,
+        required: true,
+        default: Date.now
+    },
+    meterId: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: 'PowerMeters',
+    },
+    accountBalance: {
+        type: Number,
+        default: 0
+    }
+}, {
+    timestamps: true
+});
+
+const PowerMeterAccount = mongoose.model('PowerMeterAccount', powerMeterAccountSchema);
+
+module.exports = PowerMeterAccount;

package/src/models/power_meter_command_logs.js

@@ -1,30 +1,30 @@
-const mongoose = require('mongoose');
-
-const powerMeterLogSchema = new mongoose.Schema({
-    meterId: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: 'PowerMeters',
-        required: true,
-        index: true
-    },
-    command: {
-        type: String,
-        required: true,
-        trim: true
-    },
-    platform: {
-        type: String,
-        required: true,
-        trim: true
-    },
-    timestamp: {
-        type: Date,
-        default: Date.now
-    }
-}, {
-    timestamps: true 
-});
-
-const PowerMeterLog = mongoose.model('PowerMeterLog', powerMeterLogSchema);
-
-module.exports = PowerMeterLog;
+const mongoose = require('mongoose');
+
+const powerMeterLogSchema = new mongoose.Schema({
+    meterId: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: 'PowerMeters',
+        required: true,
+        index: true
+    },
+    command: {
+        type: String,
+        required: true,
+        trim: true
+    },
+    platform: {
+        type: String,
+        required: true,
+        trim: true
+    },
+    timestamp: {
+        type: Date,
+        default: Date.now
+    }
+}, {
+    timestamps: true 
+});
+
+const PowerMeterLog = mongoose.model('PowerMeterLog', powerMeterLogSchema);
+
+module.exports = PowerMeterLog;