payservedb 9.1.7 → 9.1.9

package/src/models/invoice.js

@@ -1,528 +1,528 @@
-const mongoose = require("mongoose");
-
-const invoiceSchema = new mongoose.Schema(
-  {
-    invoiceNumber: {
-      type: String,
-      required: true,
-      unique: true,
-    },
-    accountNumber: {
-      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,
-      },
-      kraPin: {
-        type: String,
-        default: null,
-      },
-    },
-    facility: {
-      id: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: "Facility",
-        required: true,
-      },
-      name: {
-        type: String,
-        required: true,
-      },
-    },
-    unit: {
-      id: { type: mongoose.Schema.Types.ObjectId, ref: "Unit", required: true },
-      name: { type: String, required: true },
-    },
-    currency: {
-      id: {
-        type: mongoose.Schema.Types.ObjectId,
-        ref: "Currency",
-        required: true,
-      },
-      name: {
-        type: String,
-        required: true,
-      },
-      code: {
-        type: String,
-        required: true,
-        uppercase: true,
-        minlength: 3,
-        maxlength: 3,
-      },
-    },
-    items: [
-      {
-        description: { type: String, required: true },
-        quantity: { type: Number, required: true, min: 1 },
-        unitPrice: { type: Number, required: true, min: 0 },
-      },
-    ],
-    subTotal: {
-      type: Number,
-      required: true,
-    },
-    tax: {
-      type: Number,
-      required: true,
-    },
-    taxes: [
-      {
-        name: { type: String, required: true },  // e.g. "VAT", "Withholding Tax"
-        percentage: { type: Number, required: true },  // e.g. 16
-        amount: { type: Number, required: true },  // e.g. 160.00  (subTotal * percentage / 100)
-      },
-    ],
-    withholdingTaxes: [
-      {
-        name: { type: String, required: true },       // e.g. "withholding"
-        percentage: { type: Number, required: true }, // e.g. 5
-        amount: { type: Number, required: true },     // e.g. 50 (subTotal * percentage / 100)
-      },
-    ],
-    totalWithholdingTax: {
-      type: Number,
-      default: 0,
-    },
-    totalAmount: {
-      type: Number,
-      required: true,
-    },
-    amountPaid: {
-      type: Number,
-      default: 0,
-      min: 0,
-    },
-    // Mark as deprecated, keep for backward compatibility
-    overpay: {
-      type: Number,
-      default: 0,
-      min: 0,
-      deprecated: true,
-    },
-    issueDate: {
-      type: Date,
-      required: true,
-    },
-    dueDate: {
-      type: Date,
-      required: true,
-    },
-    status: {
-      type: String,
-      required: true,
-      enum: [
-        "Unpaid",
-        "Pending",
-        "Paid",
-        "Overdue",
-        "Cancelled",
-        "Partially Paid",
-        "Void",
-      ],
-    },
-    penalty: {
-      type: Number,
-      default: 0,
-    },
-    whatFor: {
-      invoiceType: { type: String, required: true },
-      description: { type: String },
-    },
-    invoiceNote: {
-      type: String,
-      default: null,
-    },
-    balanceBroughtForward: {
-      type: Number,
-      default: 0,
-    },
-    // NEW FIELD 1: Year-Month for easy filtering
-    yearMonth: {
-      type: String,
-      match: /^\d{4}-\d{2}$/, // Validates format like "2025-08"
-      index: true,
-    },
-    // NEW FIELD 2: Simple notification tracking
-    notificationsSent: {
-      sms: {
-        type: Boolean,
-        default: false,
-      },
-      email: {
-        type: Boolean,
-        default: false,
-      },
-      attempts: {
-        type: Number,
-        default: 0,
-      },
-    },
-    voidMetadata: {
-      voidedBy: {
-        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
-        name: { type: String },
-        role: { type: String },
-      },
-      voidedAt: { type: Date },
-      reason: { type: String },
-    },
-    cancelMetadata: {
-      cancelledBy: {
-        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
-        name: { type: String },
-        role: { type: String },
-      },
-      cancelledAt: { type: Date },
-      reason: { type: String },
-    },
-    lastReminderSent: Date,
-    reminderHistory: [
-      {
-        sentAt: Date,
-        reminderId: mongoose.Schema.Types.ObjectId,
-        notificationTypes: [String],
-      },
-    ],
-    reconciliationHistory: [
-      {
-        date: { type: Date, required: true },
-        paymentDate: {
-          type: Date
-        },
-        amount: { type: Number, required: true },
-        type: {
-          type: String,
-          enum: [
-            "payment",
-            "cash",
-            "cheque",
-            "bank-transfer",
-            "mpesa-transfer",
-            "overpay-transfer",
-            "balance-deduction",
-            "overpay-received",
-            "credit-forward",
-            "debit-forward",
-          ],
-          required: true,
-        },
-        sourceInvoice: String,
-        destinationInvoice: String,
-        paymentReference: String,
-        paymentCompletion: String,
-        remainingBalance: Number,
-        notes: String,
-        exchangeRate: {
-          type: Number,
-          default: 1, // For cross-currency reconciliations
-        },
-        originalCurrency: {
-          code: String, // Original currency code if different from invoice currency
-          amount: Number, // Amount in original currency
-        },
-      },
-    ],
-    paymentDetails: {
-      paymentStatus: { type: String, required: true },
-      paymentMethod: { type: String },
-      paymentDate: { type: Date },
-      transactionId: { type: String },
-    },
-    // New field to track when an invoice has been viewed
-    viewStatus: {
-      isOpened: { type: Boolean, default: false },
-      openedAt: { type: Date, default: null },
-      openedBy: {
-        facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
-        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
-        userRole: { type: String },
-      },
-      viewHistory: [
-        {
-          viewedAt: { type: Date, required: true },
-          facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
-          userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
-        },
-      ],
-    },
-    invoiceUrl: {
-      type: String,
-      default: null,
-    },
-    // eTims tax integration fields
-    ticketUrl: {
-      type: String,
-      default: null,
-      description: "QR code URL from eTims/KRA for tax invoice verification",
-    },
-    txsync: {
-      status: {
-        type: String,
-        enum: ["pending", "synced", "failed", "not-applicable"],
-        default: "not-applicable",
-      },
-      syncedAt: {
-        type: Date,
-        default: null,
-      },
-      etimsInvoiceNo: {
-        type: String,
-        default: null,
-      },
-      sdcId: {
-        type: String,
-        default: null,
-      },
-      receiptNo: {
-        type: String,
-        default: null,
-      },
-      errorMessage: {
-        type: String,
-        default: null,
-      },
-      attempts: {
-        type: Number,
-        default: 0,
-      },
-      lastAttemptAt: {
-        type: Date,
-        default: null,
-      },
-    },
-    creditNote: {
-      status: {
-        type: String,
-        enum: ["pending", "synced", "failed"],
-        default: undefined,   // absent until a void triggers one
-      },
-      creditNoteTraderNo: { type: String, default: null },
-      etimsCreditNoteNo: { type: String, default: null },
-      sdcId: { type: String, default: null },
-      receiptNo: { type: String, default: null },
-      verificationUrl: { type: String, default: null },
-      syncedAt: { type: Date, default: null },
-      lastAttemptAt: { type: Date, default: null },
-      errorMessage: { type: String, default: null },
-      attempts: { type: Number, default: 0 },
-    },
-    // New fields for double entry accounts
-    invoiceDoubleEntryAccount: {
-      type: mongoose.Schema.Types.ObjectId,
-      ref: "GLAccountDoubleEntries",
-      required: false,
-    },
-    paymentDoubleEntryAccount: {
-      type: mongoose.Schema.Types.ObjectId,
-      ref: "GLAccountDoubleEntries",
-      required: false,
-    },
-    // GL account details for invoice entries
-    accountdebitedData: {
-      amount: { type: Number },
-      description: { type: String },
-      isActive: { type: Boolean, default: true },
-    },
-    accountcreditedData: {
-      amount: { type: Number },
-      description: { type: String },
-      isActive: { type: Boolean, default: true },
-    },
-  },
-  {
-    timestamps: true,
-  },
-);
-
-// Add indexes for frequently queried fields
-invoiceSchema.index({ accountNumber: 1 });
-invoiceSchema.index({ status: 1 });
-invoiceSchema.index({ "client.clientId": 1, status: 1 });
-invoiceSchema.index({ "reconciliationHistory.paymentReference": 1 });
-invoiceSchema.index({ issueDate: -1 });
-invoiceSchema.index({ "currency.code": 1 }); // Add index for currency code
-invoiceSchema.index({ "currency.id": 1 }); // Add index for currency ID
-invoiceSchema.index({ "currency.code": 1, "client.clientId": 1, status: 1 }); // Compound index for currency-based queries
-invoiceSchema.index({ "client.clientId": 1, balanceBroughtForward: 1 }); // Add index for finding invoices with credit balances
-invoiceSchema.index({ "viewStatus.isOpened": 1 }); // Add index for view status
-invoiceSchema.index({ "viewStatus.openedBy.facilityId": 1 }); // Add index for facility view tracking
-// Add index for double entry accounts
-invoiceSchema.index({ invoiceDoubleEntryAccount: 1 });
-invoiceSchema.index({ paymentDoubleEntryAccount: 1 });
-// NEW INDEXES for new fields
-invoiceSchema.index({ yearMonth: 1 }); // For filtering by year-month
-invoiceSchema.index({ yearMonth: 1, status: 1 }); // Combined index for monthly reports
-invoiceSchema.index({ "notificationsSent.sms": 1 }); // For finding SMS sent/not sent
-invoiceSchema.index({ "notificationsSent.email": 1 }); // For finding email sent/not sent
-// eTims tax sync indexes
-invoiceSchema.index({ "txsync.status": 1 }); // For finding invoices by sync status
-invoiceSchema.index({ "txsync.etimsInvoiceNo": 1 }); // For looking up by eTims invoice number
-
-// Add virtual field for calculating balance
-invoiceSchema.virtual("calculatedBalance").get(function () {
-  const baseBalance = this.totalAmount - (this.amountPaid || 0);
-
-  // Add positive balanceBroughtForward (customer owes money)
-  if (this.balanceBroughtForward > 0) {
-    return baseBalance + this.balanceBroughtForward;
-  }
-
-  // Subtract negative balanceBroughtForward (credit)
-  return baseBalance;
-});
-
-// Add virtual field for credit balance
-invoiceSchema.virtual("creditBalance").get(function () {
-  return this.balanceBroughtForward < 0
-    ? Math.abs(this.balanceBroughtForward)
-    : 0;
-});
-
-// Getter for compatible overpay field
-invoiceSchema.virtual("effectiveOverpay").get(function () {
-  return this.balanceBroughtForward < 0
-    ? Math.abs(this.balanceBroughtForward)
-    : 0;
-});
-
-// Add virtual populate for invoice double entry account
-invoiceSchema.virtual("invoiceDoubleEntry", {
-  ref: "GLAccountDoubleEntries",
-  localField: "invoiceDoubleEntryAccount",
-  foreignField: "_id",
-  justOne: true,
-});
-
-// Add virtual populate for payment double entry account
-invoiceSchema.virtual("paymentDoubleEntry", {
-  ref: "GLAccountDoubleEntries",
-  localField: "paymentDoubleEntryAccount",
-  foreignField: "_id",
-  justOne: true,
-});
-
-// Add method for currency conversion if needed
-invoiceSchema.methods.convertAmount = function (
-  amount,
-  fromCurrency,
-  toCurrency,
-  exchangeRate,
-) {
-  if (fromCurrency === toCurrency) {
-    return amount;
-  }
-  return amount * exchangeRate;
-};
-
-// Add static method to find invoices by currency
-invoiceSchema.statics.findByCurrency = function (currencyCode) {
-  return this.find({ "currency.code": currencyCode.toUpperCase() });
-};
-
-// Add static method to find invoices with credit balance
-invoiceSchema.statics.findWithCreditBalance = function (clientId) {
-  return this.find({
-    "client.clientId": clientId,
-    balanceBroughtForward: { $lt: 0 },
-  }).sort({ updatedAt: -1 });
-};
-
-// Add static method to calculate totals by currency
-invoiceSchema.statics.calculateTotalsByCurrency = function (query = {}) {
-  return this.aggregate([
-    { $match: query },
-    {
-      $group: {
-        _id: "$currency.code",
-        totalAmount: { $sum: "$totalAmount" },
-        totalPaid: { $sum: "$amountPaid" },
-        count: { $sum: 1 },
-      },
-    },
-  ]);
-};
-
-// New static method to find all unviewed invoices
-invoiceSchema.statics.findUnviewedInvoices = function (facilityId) {
-  return this.find({
-    "facility.id": facilityId,
-    "viewStatus.isOpened": false,
-  });
-};
-
-// NEW STATIC METHODS for new fields
-// Find invoices by year-month
-invoiceSchema.statics.findByYearMonth = function (yearMonth) {
-  return this.find({ yearMonth: yearMonth });
-};
-
-// Find invoices where notifications haven't been sent
-invoiceSchema.statics.findPendingNotifications = function (facilityId) {
-  return this.find({
-    "facility.id": facilityId,
-    status: { $in: ["Unpaid", "Overdue"] },
-    $or: [
-      { "notificationsSent.sms": false },
-      { "notificationsSent.email": false },
-    ],
-  });
-};
-
-// Find invoices pending eTims sync
-invoiceSchema.statics.findPendingTaxSync = function (facilityId) {
-  return this.find({
-    "facility.id": facilityId,
-    "txsync.status": "pending",
-  });
-};
-
-// Find invoices with failed eTims sync
-invoiceSchema.statics.findFailedTaxSync = function (facilityId) {
-  return this.find({
-    "facility.id": facilityId,
-    "txsync.status": "failed",
-  });
-};
-
-// Pre-save middleware to ensure overpay and balanceBroughtForward stay in sync during transition
-invoiceSchema.pre("save", function (next) {
-
-  if (this.taxes && this.taxes.length > 0) {
-    this.tax = Math.round(
-      this.taxes.reduce((sum, t) => sum + (t.amount || 0), 0) * 100
-    ) / 100;
-  }
-
-  // If balanceBroughtForward is negative (credit), sync with overpay for backwards compatibility
-  if (this.balanceBroughtForward < 0) {
-    this.overpay = Math.abs(this.balanceBroughtForward);
-  } else {
-    this.overpay = 0; // No overpay if there's no negative balance
-  }
-
-  // NEW: Auto-generate yearMonth from issueDate if not provided
-  if (!this.yearMonth && this.issueDate) {
-    const year = this.issueDate.getFullYear();
-    const month = String(this.issueDate.getMonth() + 1).padStart(2, "0");
-    this.yearMonth = `${year}-${month}`;
-  }
-
-  next();
-});
-
-const Invoice = mongoose.model("Invoice", invoiceSchema);
-
-module.exports = Invoice;
+const mongoose = require("mongoose");
+
+const invoiceSchema = new mongoose.Schema(
+  {
+    invoiceNumber: {
+      type: String,
+      required: true,
+      unique: true,
+    },
+    accountNumber: {
+      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,
+      },
+      kraPin: {
+        type: String,
+        default: null,
+      },
+    },
+    facility: {
+      id: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: "Facility",
+        required: true,
+      },
+      name: {
+        type: String,
+        required: true,
+      },
+    },
+    unit: {
+      id: { type: mongoose.Schema.Types.ObjectId, ref: "Unit", required: true },
+      name: { type: String, required: true },
+    },
+    currency: {
+      id: {
+        type: mongoose.Schema.Types.ObjectId,
+        ref: "Currency",
+        required: true,
+      },
+      name: {
+        type: String,
+        required: true,
+      },
+      code: {
+        type: String,
+        required: true,
+        uppercase: true,
+        minlength: 3,
+        maxlength: 3,
+      },
+    },
+    items: [
+      {
+        description: { type: String, required: true },
+        quantity: { type: Number, required: true, min: 1 },
+        unitPrice: { type: Number, required: true, min: 0 },
+      },
+    ],
+    subTotal: {
+      type: Number,
+      required: true,
+    },
+    tax: {
+      type: Number,
+      required: true,
+    },
+    taxes: [
+      {
+        name: { type: String, required: true },  // e.g. "VAT", "Withholding Tax"
+        percentage: { type: Number, required: true },  // e.g. 16
+        amount: { type: Number, required: true },  // e.g. 160.00  (subTotal * percentage / 100)
+      },
+    ],
+    withholdingTaxes: [
+      {
+        name: { type: String, required: true },       // e.g. "withholding"
+        percentage: { type: Number, required: true }, // e.g. 5
+        amount: { type: Number, required: true },     // e.g. 50 (subTotal * percentage / 100)
+      },
+    ],
+    totalWithholdingTax: {
+      type: Number,
+      default: 0,
+    },
+    totalAmount: {
+      type: Number,
+      required: true,
+    },
+    amountPaid: {
+      type: Number,
+      default: 0,
+      min: 0,
+    },
+    // Mark as deprecated, keep for backward compatibility
+    overpay: {
+      type: Number,
+      default: 0,
+      min: 0,
+      deprecated: true,
+    },
+    issueDate: {
+      type: Date,
+      required: true,
+    },
+    dueDate: {
+      type: Date,
+      required: true,
+    },
+    status: {
+      type: String,
+      required: true,
+      enum: [
+        "Unpaid",
+        "Pending",
+        "Paid",
+        "Overdue",
+        "Cancelled",
+        "Partially Paid",
+        "Void",
+      ],
+    },
+    penalty: {
+      type: Number,
+      default: 0,
+    },
+    whatFor: {
+      invoiceType: { type: String, required: true },
+      description: { type: String },
+    },
+    invoiceNote: {
+      type: String,
+      default: null,
+    },
+    balanceBroughtForward: {
+      type: Number,
+      default: 0,
+    },
+    // NEW FIELD 1: Year-Month for easy filtering
+    yearMonth: {
+      type: String,
+      match: /^\d{4}-\d{2}$/, // Validates format like "2025-08"
+      index: true,
+    },
+    // NEW FIELD 2: Simple notification tracking
+    notificationsSent: {
+      sms: {
+        type: Boolean,
+        default: false,
+      },
+      email: {
+        type: Boolean,
+        default: false,
+      },
+      attempts: {
+        type: Number,
+        default: 0,
+      },
+    },
+    voidMetadata: {
+      voidedBy: {
+        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
+        name: { type: String },
+        role: { type: String },
+      },
+      voidedAt: { type: Date },
+      reason: { type: String },
+    },
+    cancelMetadata: {
+      cancelledBy: {
+        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
+        name: { type: String },
+        role: { type: String },
+      },
+      cancelledAt: { type: Date },
+      reason: { type: String },
+    },
+    lastReminderSent: Date,
+    reminderHistory: [
+      {
+        sentAt: Date,
+        reminderId: mongoose.Schema.Types.ObjectId,
+        notificationTypes: [String],
+      },
+    ],
+    reconciliationHistory: [
+      {
+        date: { type: Date, required: true },
+        paymentDate: {
+          type: Date
+        },
+        amount: { type: Number, required: true },
+        type: {
+          type: String,
+          enum: [
+            "payment",
+            "cash",
+            "cheque",
+            "bank-transfer",
+            "mpesa-transfer",
+            "overpay-transfer",
+            "balance-deduction",
+            "overpay-received",
+            "credit-forward",
+            "debit-forward",
+          ],
+          required: true,
+        },
+        sourceInvoice: String,
+        destinationInvoice: String,
+        paymentReference: String,
+        paymentCompletion: String,
+        remainingBalance: Number,
+        notes: String,
+        exchangeRate: {
+          type: Number,
+          default: 1, // For cross-currency reconciliations
+        },
+        originalCurrency: {
+          code: String, // Original currency code if different from invoice currency
+          amount: Number, // Amount in original currency
+        },
+      },
+    ],
+    paymentDetails: {
+      paymentStatus: { type: String, required: true },
+      paymentMethod: { type: String },
+      paymentDate: { type: Date },
+      transactionId: { type: String },
+    },
+    // New field to track when an invoice has been viewed
+    viewStatus: {
+      isOpened: { type: Boolean, default: false },
+      openedAt: { type: Date, default: null },
+      openedBy: {
+        facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
+        userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
+        userRole: { type: String },
+      },
+      viewHistory: [
+        {
+          viewedAt: { type: Date, required: true },
+          facilityId: { type: mongoose.Schema.Types.ObjectId, ref: "Facility" },
+          userId: { type: mongoose.Schema.Types.ObjectId, ref: "User" },
+        },
+      ],
+    },
+    invoiceUrl: {
+      type: String,
+      default: null,
+    },
+    // eTims tax integration fields
+    ticketUrl: {
+      type: String,
+      default: null,
+      description: "QR code URL from eTims/KRA for tax invoice verification",
+    },
+    txsync: {
+      status: {
+        type: String,
+        enum: ["pending", "synced", "failed", "not-applicable"],
+        default: "not-applicable",
+      },
+      syncedAt: {
+        type: Date,
+        default: null,
+      },
+      etimsInvoiceNo: {
+        type: String,
+        default: null,
+      },
+      sdcId: {
+        type: String,
+        default: null,
+      },
+      receiptNo: {
+        type: String,
+        default: null,
+      },
+      errorMessage: {
+        type: String,
+        default: null,
+      },
+      attempts: {
+        type: Number,
+        default: 0,
+      },
+      lastAttemptAt: {
+        type: Date,
+        default: null,
+      },
+    },
+    creditNote: {
+      status: {
+        type: String,
+        enum: ["pending", "synced", "failed"],
+        default: undefined,   // absent until a void triggers one
+      },
+      creditNoteTraderNo: { type: String, default: null },
+      etimsCreditNoteNo: { type: String, default: null },
+      sdcId: { type: String, default: null },
+      receiptNo: { type: String, default: null },
+      verificationUrl: { type: String, default: null },
+      syncedAt: { type: Date, default: null },
+      lastAttemptAt: { type: Date, default: null },
+      errorMessage: { type: String, default: null },
+      attempts: { type: Number, default: 0 },
+    },
+    // New fields for double entry accounts
+    invoiceDoubleEntryAccount: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "GLAccountDoubleEntries",
+      required: false,
+    },
+    paymentDoubleEntryAccount: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: "GLAccountDoubleEntries",
+      required: false,
+    },
+    // GL account details for invoice entries
+    accountdebitedData: {
+      amount: { type: Number },
+      description: { type: String },
+      isActive: { type: Boolean, default: true },
+    },
+    accountcreditedData: {
+      amount: { type: Number },
+      description: { type: String },
+      isActive: { type: Boolean, default: true },
+    },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+// Add indexes for frequently queried fields
+invoiceSchema.index({ accountNumber: 1 });
+invoiceSchema.index({ status: 1 });
+invoiceSchema.index({ "client.clientId": 1, status: 1 });
+invoiceSchema.index({ "reconciliationHistory.paymentReference": 1 });
+invoiceSchema.index({ issueDate: -1 });
+invoiceSchema.index({ "currency.code": 1 }); // Add index for currency code
+invoiceSchema.index({ "currency.id": 1 }); // Add index for currency ID
+invoiceSchema.index({ "currency.code": 1, "client.clientId": 1, status: 1 }); // Compound index for currency-based queries
+invoiceSchema.index({ "client.clientId": 1, balanceBroughtForward: 1 }); // Add index for finding invoices with credit balances
+invoiceSchema.index({ "viewStatus.isOpened": 1 }); // Add index for view status
+invoiceSchema.index({ "viewStatus.openedBy.facilityId": 1 }); // Add index for facility view tracking
+// Add index for double entry accounts
+invoiceSchema.index({ invoiceDoubleEntryAccount: 1 });
+invoiceSchema.index({ paymentDoubleEntryAccount: 1 });
+// NEW INDEXES for new fields
+invoiceSchema.index({ yearMonth: 1 }); // For filtering by year-month
+invoiceSchema.index({ yearMonth: 1, status: 1 }); // Combined index for monthly reports
+invoiceSchema.index({ "notificationsSent.sms": 1 }); // For finding SMS sent/not sent
+invoiceSchema.index({ "notificationsSent.email": 1 }); // For finding email sent/not sent
+// eTims tax sync indexes
+invoiceSchema.index({ "txsync.status": 1 }); // For finding invoices by sync status
+invoiceSchema.index({ "txsync.etimsInvoiceNo": 1 }); // For looking up by eTims invoice number
+
+// Add virtual field for calculating balance
+invoiceSchema.virtual("calculatedBalance").get(function () {
+  const baseBalance = this.totalAmount - (this.amountPaid || 0);
+
+  // Add positive balanceBroughtForward (customer owes money)
+  if (this.balanceBroughtForward > 0) {
+    return baseBalance + this.balanceBroughtForward;
+  }
+
+  // Subtract negative balanceBroughtForward (credit)
+  return baseBalance;
+});
+
+// Add virtual field for credit balance
+invoiceSchema.virtual("creditBalance").get(function () {
+  return this.balanceBroughtForward < 0
+    ? Math.abs(this.balanceBroughtForward)
+    : 0;
+});
+
+// Getter for compatible overpay field
+invoiceSchema.virtual("effectiveOverpay").get(function () {
+  return this.balanceBroughtForward < 0
+    ? Math.abs(this.balanceBroughtForward)
+    : 0;
+});
+
+// Add virtual populate for invoice double entry account
+invoiceSchema.virtual("invoiceDoubleEntry", {
+  ref: "GLAccountDoubleEntries",
+  localField: "invoiceDoubleEntryAccount",
+  foreignField: "_id",
+  justOne: true,
+});
+
+// Add virtual populate for payment double entry account
+invoiceSchema.virtual("paymentDoubleEntry", {
+  ref: "GLAccountDoubleEntries",
+  localField: "paymentDoubleEntryAccount",
+  foreignField: "_id",
+  justOne: true,
+});
+
+// Add method for currency conversion if needed
+invoiceSchema.methods.convertAmount = function (
+  amount,
+  fromCurrency,
+  toCurrency,
+  exchangeRate,
+) {
+  if (fromCurrency === toCurrency) {
+    return amount;
+  }
+  return amount * exchangeRate;
+};
+
+// Add static method to find invoices by currency
+invoiceSchema.statics.findByCurrency = function (currencyCode) {
+  return this.find({ "currency.code": currencyCode.toUpperCase() });
+};
+
+// Add static method to find invoices with credit balance
+invoiceSchema.statics.findWithCreditBalance = function (clientId) {
+  return this.find({
+    "client.clientId": clientId,
+    balanceBroughtForward: { $lt: 0 },
+  }).sort({ updatedAt: -1 });
+};
+
+// Add static method to calculate totals by currency
+invoiceSchema.statics.calculateTotalsByCurrency = function (query = {}) {
+  return this.aggregate([
+    { $match: query },
+    {
+      $group: {
+        _id: "$currency.code",
+        totalAmount: { $sum: "$totalAmount" },
+        totalPaid: { $sum: "$amountPaid" },
+        count: { $sum: 1 },
+      },
+    },
+  ]);
+};
+
+// New static method to find all unviewed invoices
+invoiceSchema.statics.findUnviewedInvoices = function (facilityId) {
+  return this.find({
+    "facility.id": facilityId,
+    "viewStatus.isOpened": false,
+  });
+};
+
+// NEW STATIC METHODS for new fields
+// Find invoices by year-month
+invoiceSchema.statics.findByYearMonth = function (yearMonth) {
+  return this.find({ yearMonth: yearMonth });
+};
+
+// Find invoices where notifications haven't been sent
+invoiceSchema.statics.findPendingNotifications = function (facilityId) {
+  return this.find({
+    "facility.id": facilityId,
+    status: { $in: ["Unpaid", "Overdue"] },
+    $or: [
+      { "notificationsSent.sms": false },
+      { "notificationsSent.email": false },
+    ],
+  });
+};
+
+// Find invoices pending eTims sync
+invoiceSchema.statics.findPendingTaxSync = function (facilityId) {
+  return this.find({
+    "facility.id": facilityId,
+    "txsync.status": "pending",
+  });
+};
+
+// Find invoices with failed eTims sync
+invoiceSchema.statics.findFailedTaxSync = function (facilityId) {
+  return this.find({
+    "facility.id": facilityId,
+    "txsync.status": "failed",
+  });
+};
+
+// Pre-save middleware to ensure overpay and balanceBroughtForward stay in sync during transition
+invoiceSchema.pre("save", function (next) {
+
+  if (this.taxes && this.taxes.length > 0) {
+    this.tax = Math.round(
+      this.taxes.reduce((sum, t) => sum + (t.amount || 0), 0) * 100
+    ) / 100;
+  }
+
+  // If balanceBroughtForward is negative (credit), sync with overpay for backwards compatibility
+  if (this.balanceBroughtForward < 0) {
+    this.overpay = Math.abs(this.balanceBroughtForward);
+  } else {
+    this.overpay = 0; // No overpay if there's no negative balance
+  }
+
+  // NEW: Auto-generate yearMonth from issueDate if not provided
+  if (!this.yearMonth && this.issueDate) {
+    const year = this.issueDate.getFullYear();
+    const month = String(this.issueDate.getMonth() + 1).padStart(2, "0");
+    this.yearMonth = `${year}-${month}`;
+  }
+
+  next();
+});
+
+const Invoice = mongoose.model("Invoice", invoiceSchema);
+
+module.exports = Invoice;