payservedb 9.0.6 → 9.0.8

package/index.js

@@ -259,6 +259,7 @@ const models = {
   MoveinLandlord: require("./src/models/movein_landlord"),
   MoveinUser: require("./src/models/movein_user"),
   InvoiceWithholdingTax: require("./src/models/InvoiceWithholdingTax"),
+  InvoiceCreditAdjustment: require("./src/models/invoiceCreditAdjustment"),
   // Customer Obsession admin-managed config
   EmailCcConfig: require("./src/models/email_cc_config"),
   AutoReplyRule: require("./src/models/auto_reply_rule"),

package/package.json

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

package/src/models/invoiceCreditAdjustment.js

@@ -0,0 +1,46 @@
+const mongoose = require("mongoose");
+
+const invoiceCreditAdjustmentSchema = new mongoose.Schema(
+  {
+    invoice: {
+      id: { type: mongoose.Schema.Types.ObjectId, ref: "Invoice", required: true },
+      invoiceNumber: { type: String, required: true },
+    },
+    facility: {
+      id: { type: mongoose.Schema.Types.ObjectId, ref: "Facility", required: true },
+      name: { type: String, required: true },
+    },
+    client: {
+      clientId: { type: mongoose.Schema.Types.ObjectId, ref: "Customer", required: true },
+      firstName: { type: String, required: true },
+      lastName: { type: String, required: true },
+    },
+    adjustmentType: {
+      type: String,
+      enum: ["credit", "debit", "opening-balance"],
+      required: true,
+    },
+    previousBalance: { type: Number, required: true },   // balanceBroughtForward before change
+    adjustmentAmount: { type: Number, required: true },  // the actual change (can be negative)
+    newBalance: { type: Number, required: true },        // balanceBroughtForward after change
+    reason: { type: String, required: true },
+    madeBy: {
+      userId: { type: mongoose.Schema.Types.ObjectId, ref: "User", required: true },
+      name: { type: String, required: true },
+      role: { type: String, required: true },
+    },
+  },
+  { timestamps: true }
+);
+
+invoiceCreditAdjustmentSchema.index({ "invoice.id": 1 });
+invoiceCreditAdjustmentSchema.index({ "client.clientId": 1 });
+invoiceCreditAdjustmentSchema.index({ "facility.id": 1 });
+invoiceCreditAdjustmentSchema.index({ adjustmentType: 1 });
+
+const InvoiceCreditAdjustment = mongoose.model(
+  "InvoiceCreditAdjustment",
+  invoiceCreditAdjustmentSchema
+);
+
+module.exports = InvoiceCreditAdjustment;

package/src/models/powerMeterSettings.js

@@ -5,7 +5,7 @@ const powerMeterSettingsSchema = new mongoose.Schema({
         type: mongoose.Schema.Types.ObjectId,
         ref: 'Facility',
         required: true,
-        unique: true // Ensure one settings record per facility
+        unique: true
     },
 
     // Billing Amounts
@@ -79,33 +79,72 @@ const powerMeterSettingsSchema = new mongoose.Schema({
         min: 0
     },
 
-    // GL Account Configuration (following your sample pattern)
+    // Biller Address — stores the selected BillerAddress document ID
+    billerAddressId: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: 'BillerAddress',
+        required: false,
+        default: null
+    },
+
+    // Payment Methods — mirrors the water meter settings pattern
+    paymentMethods: {
+        mobilePayment: {
+            status: {
+                type: Boolean,
+                default: false
+            },
+            paymentId: {
+                type: mongoose.Schema.Types.ObjectId,
+                ref: 'FacilityPaymentDetails',
+                default: null
+            }
+        },
+        bankPayment: {
+            status: {
+                type: Boolean,
+                default: false
+            },
+            paymentId: {
+                type: mongoose.Schema.Types.ObjectId,
+                ref: 'BankDetails',
+                default: null
+            }
+        }
+    },
+
+    // GL Account Configuration
     glAccounts: {
         invoice: {
             debit: {
                 type: mongoose.Schema.Types.ObjectId,
-                ref: "GLAccount",
+                ref: 'GLAccount',
                 required: false,
+                default: null
             },
             credit: {
                 type: mongoose.Schema.Types.ObjectId,
-                ref: "GLAccount",
+                ref: 'GLAccount',
                 required: false,
+                default: null
             }
         },
         payment: {
             debit: {
                 type: mongoose.Schema.Types.ObjectId,
-                ref: "GLAccount",
+                ref: 'GLAccount',
                 required: false,
+                default: null
             },
             credit: {
                 type: mongoose.Schema.Types.ObjectId,
-                ref: "GLAccount",
+                ref: 'GLAccount',
                 required: false,
+                default: null
             }
         }
     },
+
     // Discounts
     discounts: [{
         name: {
@@ -128,12 +167,14 @@ const powerMeterSettingsSchema = new mongoose.Schema({
             required: true
         }
     }],
-    // Other Charges
+
+    // Other Charges (KPLC)
     otherCharges: {
         type: String,
         enum: ['yes', 'no', ''],
         default: ''
     },
+
     // Notifications
     notifications: {
         type: Boolean,

package/src/models/powerMeters.js

@@ -59,6 +59,14 @@ const powerMeterSchema = new mongoose.Schema({
         type: String,
         required: true
     },
+    
+    meterCategory: {
+        type: String,
+        required: true,
+        enum: ['unit', 'common_area', 'bulk'],
+        default: 'unit'
+    },
+
     unitId: {
         type: mongoose.Schema.Types.ObjectId,
         ref: 'Unit',
@@ -68,6 +76,13 @@ const powerMeterSchema = new mongoose.Schema({
         type: String,
         trim: true
     },
+
+    // ─── Common Area / Bulk Meter Fields ──────────────────────────────────────
+    description: {
+        type: String,
+        trim: true
+    },
+
     type: {
         type: String,
         required: true,
@@ -111,6 +126,25 @@ const powerMeterSchema = new mongoose.Schema({
     timestamps: true
 });
 
+powerMeterSchema.virtual('displayName').get(function () {
+    return this.meterCategory === 'unit'
+        ? this.unitName
+        : this.description;
+});
+powerMeterSchema.pre('save', function (next) {
+    if (this.meterCategory === 'unit') {
+        if (!this.unitId || !this.unitName) {
+            return next(new Error('Unit meters require both unitId and unitName.'));
+        }
+    } else {
+        // common_area or bulk
+        if (!this.description) {
+            return next(new Error(`${this.meterCategory} meters require a description.`));
+        }
+    }
+    next();
+});
+
 const PowerMeters = mongoose.model('PowerMeters', powerMeterSchema);
 
-module.exports = PowerMeters;
+module.exports = PowerMeters;

package/src/models/power_invoice.js

@@ -16,6 +16,12 @@ const powerInvoiceSchema = new mongoose.Schema(
       type: String,
       required: true,
     },
+    // Unit reference — stored directly from PowerMeterAccount.unitId / PowerMeters.unitId
+    unitId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'Unit',
+      default: null,
+    },
     yearMonth: {
       type: String,
       required: true,
@@ -40,42 +46,14 @@ const powerInvoiceSchema = new mongoose.Schema(
       // 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'],
+    // ── Biller Address ─────────────────────────────────────────────────────────
+    // Reference to the BillerAddress document configured in PowerMeterSettings.
+    // The sub-document below is a denormalised snapshot captured at invoice time.
+    billerAddressId: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'BillerAddress',
       default: null,
     },
-
-    // ── Biller Address ─────────────────────────────────────────────────────────
     billerAddress: {
       name: {
         type: String,
@@ -110,6 +88,49 @@ const powerInvoiceSchema = new mongoose.Schema(
       },
     },
 
+    // ── Payment Methods ────────────────────────────────────────────────────────
+    // paymentMethods stores the IDs configured in PowerMeterSettings so the
+    // invoice knows which accounts/paybills are available for payment.
+    // paymentMethod (singular) records how this invoice was actually settled.
+    paymentMethods: {
+      mobilePayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+        // References the FacilityPaymentDetails (M-Pesa paybill) configured in settings
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'FacilityPaymentDetails',
+          default: null,
+        },
+      },
+      bankPayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+        // References the BankDetails configured in settings
+        paymentId: {
+          type: mongoose.Schema.Types.ObjectId,
+          ref: 'BankDetails',
+          default: null,
+        },
+      },
+      cashPayment: {
+        status: {
+          type: Boolean,
+          default: false,
+        },
+      },
+    },
+    // How this invoice was actually paid (set during reconciliation)
+    paymentMethod: {
+      type: String,
+      enum: ['mobile', 'bank', 'cash', 'mixed'],
+      default: null,
+    },
+
     // ── Dates ──────────────────────────────────────────────────────────────────
     dateIssued: {
       type: Date,
@@ -167,89 +188,21 @@ const powerInvoiceSchema = new mongoose.Schema(
     },
 
     // ── 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,
-      },
+      tariff: { type: String },
+      yearMonth: { type: String },
+      energyCharge: { type: Number, required: true, default: 0 },
+      fuelCostCharge: { type: Number, default: 0 },
+      forexAdjustment: { type: Number, default: 0 },
+      inflationAdjustment: { type: Number, default: 0 },
+      waterResourceManagementLevy: { type: Number, default: 0 },
+      energyRegulatoryLevy: { type: Number, default: 0 },
+      ruralElectrificationLevy: { type: Number, default: 0 },
+      powerFactorSurcharge: { type: Number, default: 0 },
+      valueAddedTax: { type: Number, default: 0 },
+      vatPercentage: { type: Number, default: 16 },
+      repPercentage: { type: Number, default: 5 },
+      totalCharge: { type: Number, required: true },
     },
 
     // ── Payment & Reconciliation ───────────────────────────────────────────────
@@ -270,60 +223,28 @@ const powerInvoiceSchema = new mongoose.Schema(
       default: 'Unpaid',
     },
 
-    // ── View / Read Status 
+    // ── View / Read Status ─────────────────────────────────────────────────────
     viewStatus: {
-      isOpened: {
-        type: Boolean,
-        default: false,
-      },
-      openedAt: {
-        type: Date,
-        default: null,
-      },
+      isOpened: { type: Boolean, default: false },
+      openedAt: { type: Date, default: null },
     },
 
-    // ── Currency 
+    // ── Currency ───────────────────────────────────────────────────────────────
     currency: {
-      id: {
-        type: mongoose.Schema.Types.ObjectId,
-      },
-      name: {
-        type: String,
-        default: 'Kenyan Shilling',
-      },
-      code: {
-        type: String,
-        default: 'KES',
-      },
-      symbol: {
-        type: String,
-        default: 'KSh',
-      },
+      id: { type: mongoose.Schema.Types.ObjectId },
+      name: { type: String, default: 'Kenyan Shilling' },
+      code: { type: String, default: 'KES' },
+      symbol: { type: String, default: 'KSh' },
     },
 
-    // ── Notification Tracking 
+    // ── 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,
-        },
+        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,
@@ -354,41 +275,18 @@ const powerInvoiceSchema = new mongoose.Schema(
       },
     },
 
-    //   Reconciliation History 
+    // ── 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,
-        },
+        date: { type: Date, default: Date.now },
+        amount: { type: Number, required: true },
+        type: { type: String, default: 'Manual' },
+        paymentReference: { type: String },
+        paymentCompletion: { type: String, default: 'Completed' },
+        sourceInvoice: { type: String },
+        destinationInvoice: { type: String },
+        notes: { type: String },
+        remainingBalance: { type: Number },
       },
     ],
   },
@@ -397,7 +295,7 @@ const powerInvoiceSchema = new mongoose.Schema(
   }
 );
 
-//  Pre-save middleware
+// ── Pre-save middleware ────────────────────────────────────────────────────────
 
 powerInvoiceSchema.pre('save', function (next) {
   // 1. Auto-mark overdue
@@ -409,15 +307,11 @@ powerInvoiceSchema.pre('save', function (next) {
   }
 
   // 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('tariff')) && 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;
-    }
+  if ((this.isNew || this.isModified('yearMonth')) && this.powerCharges && !this.powerCharges.yearMonth) {
+    this.powerCharges.yearMonth = this.yearMonth;
   }
 
   // 3. Update payment method flags from reconciliation history
@@ -434,12 +328,7 @@ powerInvoiceSchema.pre('save', function (next) {
         };
       }
 
-      if (
-        paymentType &&
-        (paymentType.includes('mobile') ||
-          paymentType.includes('mpesa') ||
-          paymentType.includes('m-pesa'))
-      ) {
+      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')) {
@@ -449,7 +338,6 @@ powerInvoiceSchema.pre('save', function (next) {
         this.paymentMethods.cashPayment.status = true;
         this.paymentMethod = 'cash';
       } else {
-        // Default: treat unspecified / manual payments as cash
         this.paymentMethods.cashPayment.status = true;
         this.paymentMethod = 'cash';
       }
@@ -459,12 +347,13 @@ powerInvoiceSchema.pre('save', function (next) {
   next();
 });
 
-// Indexes 
+// ── Indexes ────────────────────────────────────────────────────────────────────
 powerInvoiceSchema.index({ facilityId: 1, yearMonth: -1 });
 powerInvoiceSchema.index({ customerId: 1 });
 powerInvoiceSchema.index({ status: 1 });
 powerInvoiceSchema.index({ meterNumber: 1 });
 powerInvoiceSchema.index({ accountNumber: 1 });
+powerInvoiceSchema.index({ unitId: 1 });
 
 const PowerInvoice = mongoose.model('PowerInvoice', powerInvoiceSchema);
 

package/src/models/suppliers.js

@@ -37,6 +37,11 @@ const supplierSchema = new mongoose.Schema({
             trim: true
         }
     },
+    category: {
+        type: String,
+        trim: true,
+        index: true
+    },
     taxIdentificationNumber: {
         type: String,
         trim: true