tango-app-api-payment-subscription 3.5.6 → 3.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.6",
+    "version": "3.5.8",
     "description": "paymentSubscription",
     "main": "index.js",
     "type": "module",
@@ -29,7 +29,7 @@
         "nodemon": "^3.1.0",
         "puppeteer": "^24.41.0",
         "swagger-ui-express": "^5.0.0",
-        "tango-api-schema": "^2.6.25",
+        "tango-api-schema": "^2.6.27",
         "tango-app-api-middleware": "^3.6.18",
         "winston": "^3.12.0",
         "winston-daily-rotate-file": "^5.0.0",

package/scripts/seed-payment-reminders.js

@@ -0,0 +1,82 @@
+// One-shot seeder: creates a paymentreminders config for every ACTIVE client
+// (clients.status === 'active'), with a single static recipient email and the
+// app's default template toggles. Idempotent — re-running upserts the same
+// docs, so existing configs are overwritten with the static email + defaults.
+//
+// Usage (from the API project root):
+//   node scripts/seed-payment-reminders.js
+//   node scripts/seed-payment-reminders.js someone@else.com   # override email
+//   node scripts/seed-payment-reminders.js --dry-run          # report only
+//
+// Reads MONGO connection + env from .env (same as the app).
+
+import dotenv from 'dotenv';
+import mongoose from 'mongoose';
+import model from 'tango-api-schema';
+import { getConnection } from '../config/database/database.js';
+
+dotenv.config();
+
+const args = process.argv.slice( 2 );
+const dryRun = args.includes( '--dry-run' );
+const STATIC_EMAIL = args.find( ( a ) => a.includes( '@' ) ) || 'ayyanarkalusulingam13@gmail.com';
+
+// Mirrors the app's DEFAULTS() in paymentReminder.controller.js.
+const DEFAULT_TEMPLATES = {
+  preDue: { enabled: true, daysBefore: 3 },
+  onDue: { enabled: true },
+  onHold: { enabled: true },
+  suspend: { enabled: true },
+  deactivated: { enabled: false },
+};
+
+async function run() {
+  // Reuse the app's own connection builder (reads mongo_* env config).
+  const { uri, options } = getConnection();
+  await mongoose.connect( uri, options );
+  console.log( `Connected. Static recipient: ${STATIC_EMAIL}${dryRun ? '  (DRY RUN — no writes)' : ''}\n` );
+
+  const clients = await model.clientModel.find(
+      { status: 'active' },
+      { clientId: 1, clientName: 1 },
+  ).lean();
+  console.log( `Active clients found: ${clients.length}\n` );
+
+  const summary = { total: clients.length, upserted: 0, skipped: 0 };
+
+  for ( const c of clients ) {
+    if ( !c.clientId ) {
+      summary.skipped++;
+      console.log( `  - skip (no clientId): ${c.clientName || c._id}` );
+      continue;
+    }
+    if ( dryRun ) {
+      summary.upserted++;
+      console.log( `  • would upsert: ${c.clientName || c.clientId}` );
+      continue;
+    }
+    await model.paymentReminderModel.updateOne(
+        { clientId: c.clientId },
+        {
+          $set: {
+            clientId: c.clientId,
+            reminderEmails: [ STATIC_EMAIL ],
+            templates: DEFAULT_TEMPLATES,
+            updatedBy: 'seed-script',
+          },
+        },
+        { upsert: true },
+    );
+    summary.upserted++;
+    console.log( `  ✓ ${c.clientName || c.clientId}` );
+  }
+
+  console.log( `\nDone. ${summary.upserted} upserted, ${summary.skipped} skipped (of ${summary.total} active).` );
+  await mongoose.disconnect();
+  process.exit( 0 );
+}
+
+run().catch( ( err ) => {
+  console.error( 'Failed:', err?.message || err );
+  process.exit( 1 );
+} );

package/scripts/send-reminder-test-emails.js

@@ -0,0 +1,70 @@
+// One-shot tester: renders all 5 payment-reminder templates with sample
+// invoice data and emails each one to a single recipient, so you can see
+// exactly what every reminder stage looks like. Uses the real SES setup
+// (reads AWS_CONFIG / SES from .env, same as the app).
+//
+// Usage (from the API project root):
+//   node scripts/send-reminder-test-emails.js
+//   node scripts/send-reminder-test-emails.js someone@else.com
+//
+// The recipient defaults to the address below; pass an arg to override.
+
+import dotenv from 'dotenv';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import Handlebars from '../src/utils/validations/helper/handlebar.helper.js';
+import { sendEmailWithSES } from 'tango-app-api-middleware';
+
+dotenv.config();
+
+const TO = process.argv[2] || 'ayyanarkalusulingam13@gmail.com';
+
+const __dirname = path.dirname( fileURLToPath( import.meta.url ) );
+const HBS_DIR = path.resolve( __dirname, '../src/hbs' );
+Handlebars.registerPartial(
+    'invoiceSummaryTable',
+    fs.readFileSync( `${HBS_DIR}/partials/invoiceSummaryTable.hbs`, 'utf8' ),
+);
+
+// Sample data — a representative client with two unpaid invoices.
+const data = {
+  clientName: 'Cashify',
+  companyName: 'Team Tango',
+  dueDate: '17 Jun 2026',
+  totalDue: '₹ 2,70,106.00',
+  logo: `${JSON.parse( process.env.URL ).apiDomain}/logo.png`,
+  invoices: [
+    { invoiceNumber: 'INV-26-27-00210', invoiceDate: '02 Jun 2026', dueDate: '17 Jun 2026', amountDue: '₹ 1,42,947.00' },
+    { invoiceNumber: 'INV-26-27-00205', invoiceDate: '02 May 2026', dueDate: '17 May 2026', amountDue: '₹ 1,27,159.00' },
+  ],
+};
+
+const STAGES = [
+  { file: 'reminderBeforeDue.hbs', subject: `[TEST] Payment reminder — due on ${data.dueDate}` },
+  { file: 'reminderOnDue.hbs', subject: `[TEST] Payment due today — ${data.totalDue} outstanding` },
+  { file: 'reminderOnHold.hbs', subject: '[TEST] Action needed: payment overdue — your account is on hold' },
+  { file: 'reminderSuspended.hbs', subject: '[TEST] Important: account suspended — payment 30+ days overdue' },
+  { file: 'reminderDeactivated.hbs', subject: '[TEST] Final notice: account deactivated — payment 60+ days overdue' },
+];
+
+async function run() {
+  const SES = JSON.parse( process.env.SES );
+  const fromEmail = SES.accountsEmail || SES.adminEmail;
+  console.log( `Sending ${STAGES.length} reminder emails to ${TO} (from ${fromEmail})\n` );
+
+  for ( const stage of STAGES ) {
+    const tpl = Handlebars.compile( fs.readFileSync( `${HBS_DIR}/${stage.file}`, 'utf8' ) );
+    const html = tpl( data );
+    try {
+      await sendEmailWithSES( TO, stage.subject, html, '', fromEmail );
+      console.log( `  ✓ sent: ${stage.file}` );
+    } catch ( err ) {
+      console.error( `  ✗ failed: ${stage.file} —`, err?.message || err );
+    }
+  }
+  console.log( '\nDone.' );
+  process.exit( 0 );
+}
+
+run();

package/src/controllers/brandsBilling.controller.js

@@ -15,6 +15,12 @@ export async function brandsBillingList( req, res ) {
   try {
     let query = [];
 
+    // Billing-store count is taken from dailyPricing for the current billing
+    // month: a store counts only if it actually RAN on more than one day in
+    // the month (a store that appears on a single day is transient — e.g. a
+    // late onboard or a one-off reading — and isn't billed for the period).
+    const billingMonthStart = new Date( dayjs().startOf( 'month' ).toISOString() );
+
     if ( req.body.status && req.body.status.length > 0 ) {
       query.push( {
         $match: {
@@ -38,9 +44,15 @@ export async function brandsBillingList( req, res ) {
             let: { clientId: '$clientId' },
             pipeline: [
               {
+                // Count only ACTIVE stores — the 'stores' collection also holds
+                // deactive/suspended docs which inflated the No. of Stores
+                // column and made it inconsistent with Billing Stores.
                 $match: {
                   $expr: {
-                    $eq: [ '$clientId', '$$clientId' ],
+                    $and: [
+                      { $eq: [ '$clientId', '$$clientId' ] },
+                      { $eq: [ '$status', 'active' ] },
+                    ],
                   },
                 },
               },
@@ -66,7 +78,6 @@ export async function brandsBillingList( req, res ) {
               {
                 $group: {
                   _id: null,
-                  billingStores: { $sum: { $size: { $ifNull: [ '$stores', [] ] } } },
                   products: { $addToSet: '$products' },
                   nextBillingDate: { $min: '$nextBillingDate' },
                 },
@@ -75,6 +86,35 @@ export async function brandsBillingList( req, res ) {
             as: 'billingData',
           },
         },
+        {
+          // Billing stores from dailyPricing: distinct active stores that ran
+          // on MORE THAN ONE day in the current billing month. We unwind the
+          // per-day store rows, keep active ones, collect the distinct dates
+          // each store was active, then count only the stores seen on >1 day.
+          $lookup: {
+            from: 'dailypricings',
+            let: { clientId: '$clientId' },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: [ '$clientId', '$$clientId' ] },
+                  dateISO: { $gte: billingMonthStart },
+                },
+              },
+              { $unwind: { path: '$stores', preserveNullAndEmptyArrays: false } },
+              { $match: { 'stores.status': 'active' } },
+              {
+                $group: {
+                  _id: '$stores.storeId',
+                  days: { $addToSet: { $dateToString: { format: '%Y-%m-%d', date: '$dateISO' } } },
+                },
+              },
+              { $match: { $expr: { $gt: [ { $size: '$days' }, 1 ] } } },
+              { $count: 'billingStores' },
+            ],
+            as: 'dailyBillingData',
+          },
+        },
         {
           $lookup: {
             from: 'invoices',
@@ -91,9 +131,14 @@ export async function brandsBillingList( req, res ) {
                 },
               },
               {
+                // Split unpaid totals by currency so dollar invoices can be
+                // converted to INR after aggregation (the $lookup can't call
+                // getUsdInrRate). Invoice totalAmount is stored in NATIVE
+                // currency, so summing blindly mislabelled USD as INR.
                 $group: {
                   _id: null,
-                  totalDue: { $sum: '$totalAmount' },
+                  dueInr: { $sum: { $cond: [ { $eq: [ '$currency', 'dollar' ] }, 0, '$totalAmount' ] } },
+                  dueUsd: { $sum: { $cond: [ { $eq: [ '$currency', 'dollar' ] }, '$totalAmount', 0 ] } },
                 },
               },
             ],
@@ -106,13 +151,16 @@ export async function brandsBillingList( req, res ) {
         {
           $unwind: { path: '$billingData', preserveNullAndEmptyArrays: true },
         },
+        {
+          $unwind: { path: '$dailyBillingData', preserveNullAndEmptyArrays: true },
+        },
         {
           $unwind: { path: '$invoiceData', preserveNullAndEmptyArrays: true },
         },
         {
           $addFields: {
             totalStores: { $ifNull: [ '$storeData.totalStores', 0 ] },
-            billingStores: { $ifNull: [ '$billingData.billingStores', 0 ] },
+            billingStores: { $ifNull: [ '$dailyBillingData.billingStores', 0 ] },
             productsAdded: {
               $size: {
                 $filter: {
@@ -122,7 +170,8 @@ export async function brandsBillingList( req, res ) {
                 },
               },
             },
-            billAmountDue: { $ifNull: [ '$invoiceData.totalDue', 0 ] },
+            dueInr: { $ifNull: [ '$invoiceData.dueInr', 0 ] },
+            dueUsd: { $ifNull: [ '$invoiceData.dueUsd', 0 ] },
             nextBillingDate: { $ifNull: [ '$billingData.nextBillingDate', null ] },
           },
         },
@@ -135,7 +184,8 @@ export async function brandsBillingList( req, res ) {
             totalStores: 1,
             billingStores: 1,
             productsAdded: 1,
-            billAmountDue: 1,
+            dueInr: 1,
+            dueUsd: 1,
             status: 1,
             paymentStatus: '$planDetails.paymentStatus',
             nextBillingDate: 1,
@@ -164,19 +214,106 @@ export async function brandsBillingList( req, res ) {
 
     let allData = await clientService.aggregate( query );
 
-    if ( allData.length == 0 ) {
-      return res.sendError( 'No data', 204 );
+    // Bill Amount Due in INR: dollar invoice totals converted at today's rate
+    // and added to the INR totals, so the column and the ₹-labelled Total Bill
+    // Due chip are a single, additive currency. (Previously USD was shown as ₹
+    // and the grand total summed INR+USD raw.)
+    const billDueRate = await getUsdInrRate();
+    for ( const c of allData ) {
+      c.billAmountDue = Math.round( ( ( c.dueInr || 0 ) + ( c.dueUsd || 0 ) * billDueRate ) * 100 ) / 100;
+      delete c.dueInr;
+      delete c.dueUsd;
     }
 
+    // Lifecycle + payment counts over the FULL client population (no status /
+    // paymentStatus filter), so the overview cards stay stable regardless of
+    // which lifecycle tab is selected — and so Hold / Suspended / Deactive
+    // show even when the default Active tab has zero rows. trialPaid is the
+    // derived "paid plan with at least one product still on trial" bucket.
+    // Bucket every client into ONE mutually-exclusive payment bucket so the
+    // pills (Paid / Trial / Paid-Trial / Free) sum to their lifecycle tab
+    // total. trialPaid = paid plan that still has a product on trial; such a
+    // client is trialPaid, NOT also paid.
+    const payBucketExpr = {
+      $let: {
+        vars: {
+          ps: '$planDetails.paymentStatus',
+          hasTrialProduct: { $gt: [ { $size: { $filter: {
+            input: { $ifNull: [ '$planDetails.product', [] ] },
+            as: 'p',
+            cond: { $eq: [ '$$p.status', 'trial' ] },
+          } } }, 0 ] },
+        },
+        in: {
+          $switch: {
+            branches: [
+              { case: { $eq: [ '$$ps', 'trial' ] }, then: 'trial' },
+              { case: { $eq: [ '$$ps', 'free' ] }, then: 'free' },
+              { case: { $and: [ { $eq: [ '$$ps', 'paid' ] }, '$$hasTrialProduct' ] }, then: 'trialPaid' },
+              { case: { $eq: [ '$$ps', 'paid' ] }, then: 'paid' },
+              { case: { $eq: [ '$$ps', 'unbilled' ] }, then: 'unbilled' },
+            ],
+            default: 'other',
+          },
+        },
+      },
+    };
+    const matrixAgg = await clientService.aggregate( [
+      { $project: { status: 1, payBucket: payBucketExpr } },
+      { $group: { _id: { status: '$status', pay: '$payBucket' }, count: { $sum: 1 } } },
+    ] );
+
+    // Lifecycle totals + a status×payment matrix. Counts are over the FULL
+    // population (no filter) so the overview cards and pills stay stable
+    // regardless of the selected tab, and show even when the Active tab is
+    // empty.
+    const lifecycle = { active: 0, hold: 0, suspended: 0, deactive: 0 };
+    const payTotals = { trial: 0, paid: 0, free: 0, trialPaid: 0, unbilled: 0 };
+    const paymentByStatus = {};
+    let totalBrands = 0;
+    matrixAgg.forEach( ( row ) => {
+      const st = row._id.status || 'active';
+      const pay = row._id.pay;
+      const n = row.count || 0;
+      totalBrands += n;
+      if ( lifecycle[st] != null ) {
+        lifecycle[st] += n;
+      }
+      if ( payTotals[pay] != null ) {
+        payTotals[pay] += n;
+      }
+      if ( !paymentByStatus[st] ) {
+        paymentByStatus[st] = { trial: 0, paid: 0, free: 0, trialPaid: 0, unbilled: 0 };
+      }
+      if ( paymentByStatus[st][pay] != null ) {
+        paymentByStatus[st][pay] += n;
+      }
+    } );
+
     let summary = {
-      totalBrands: allData.length,
-      active: allData.filter( ( c ) => c.status === 'active' ).length,
-      trial: allData.filter( ( c ) => c.paymentStatus === 'trial' ).length,
-      paid: allData.filter( ( c ) => c.paymentStatus === 'paid' ).length,
+      totalBrands,
+      active: lifecycle.active,
+      hold: lifecycle.hold,
+      suspended: lifecycle.suspended,
+      deactive: lifecycle.deactive,
+      trial: payTotals.trial,
+      paid: payTotals.paid,
+      free: payTotals.free,
+      trialPaid: payTotals.trialPaid,
+      unbilled: payTotals.unbilled,
+      paymentByStatus,
+      // Money/store totals stay tied to the filtered view so they match the
+      // rows on screen.
       totalBillDue: allData.reduce( ( sum, c ) => sum + ( c.billAmountDue || 0 ), 0 ),
       storesUnderBilling: allData.reduce( ( sum, c ) => sum + ( c.billingStores || 0 ), 0 ),
     };
 
+    if ( allData.length == 0 ) {
+      // Still return the population summary so the overview cards populate even
+      // when the current lifecycle tab is empty.
+      return res.sendSuccess( { summary, count: 0, data: [] } );
+    }
+
     if ( req.body.export ) {
       const exportdata = [];
       allData.forEach( ( element ) => {
@@ -526,6 +663,36 @@ export async function latestDailyPricing( req, res ) {
       storeList = stores.slice( skip, skip + Number( req.body.limit ) );
     }
 
+    // Monthly Billing Summary — one row per month of the brand's invoice
+    // history (stores billed + invoice amount), newest first. The UI tags the
+    // current/last-generated rows and computes month-over-month deltas.
+    // billingDate is a Date on most rows but a string on some legacy ones, so
+    // coerce before extracting year/month.
+    const monthlyBillingSummary = await invoiceService.aggregate( [
+      { $match: { clientId: req.body.clientId } },
+      { $addFields: { billingDateD: { $cond: [
+        { $eq: [ { $type: '$billingDate' }, 'date' ] },
+        '$billingDate',
+        { $toDate: '$billingDate' },
+      ] } } },
+      { $match: { billingDateD: { $ne: null } } },
+      { $group: {
+        _id: { year: { $year: '$billingDateD' }, month: { $month: '$billingDateD' } },
+        storesBilled: { $sum: { $ifNull: [ '$stores', 0 ] } },
+        invoiceAmount: { $sum: { $ifNull: [ '$totalAmount', 0 ] } },
+        currency: { $last: { $ifNull: [ '$currency', 'inr' ] } },
+      } },
+      { $sort: { '_id.year': -1, '_id.month': -1 } },
+      { $project: {
+        _id: 0,
+        year: '$_id.year',
+        month: '$_id.month',
+        storesBilled: 1,
+        invoiceAmount: { $round: [ '$invoiceAmount', 2 ] },
+        currency: 1,
+      } },
+    ] );
+
     let data = {
       clientId: record.clientId,
       brandName: record.brandName,
@@ -537,6 +704,7 @@ export async function latestDailyPricing( req, res ) {
       proRate: record.proRate,
       count,
       data: storeList,
+      monthlyBillingSummary,
     };
 
     res.sendSuccess( data );
@@ -1305,7 +1473,7 @@ export async function bulkUpdateBillingGroups( req, res ) {
 // with an env override (USD_INR_RATE) and a last-known/static fallback so
 // the summary never fails because a rate API is down.
 let usdRateCache = { rate: null, at: 0 };
-async function getUsdInrRate() {
+export async function getUsdInrRate() {
   const override = Number( process.env.USD_INR_RATE );
   if ( override > 0 ) {
     return override;
@@ -1371,6 +1539,12 @@ export async function billingSummary( req, res ) {
         installationInr: { $sum: { $cond: [ '$isDollar', 0, '$installation' ] } },
         installationUsd: { $sum: { $cond: [ '$isDollar', '$installation', 0 ] } },
         companyName: { $last: '$companyName' },
+        // Track the actual invoice currencies so the row currency reflects how
+        // the client is really billed — not the (sometimes stale)
+        // paymentInvoice.currencyType. e.g. Sundora is flagged 'dollar' but
+        // every invoice is INR.
+        dollarInvoices: { $sum: { $cond: [ '$isDollar', 1, 0 ] } },
+        inrInvoices: { $sum: { $cond: [ '$isDollar', 0, 1 ] } },
       } },
     ] );
 
@@ -1451,11 +1625,15 @@ export async function billingSummary( req, res ) {
           // to (status 'live') — trials are excluded.
           liveProductSet: new Set( products.filter( ( p ) => p.status === 'live' )
               .map( ( p ) => String( p.productName || '' ).toLowerCase() ) ),
+          // Fallback only — overridden below from actual invoice currencies
+          // when the client has invoices.
           currency: c?.paymentInvoice?.currencyType === 'dollar' ? 'dollar' : 'inr',
           csm: [ ...( csmByClient.get( key ) || [] ) ].join( ', ' ),
           revenueMonths: {},
           billedStoresMonths: {},
           installationFee: 0,
+          invDollar: 0,
+          invInr: 0,
         } );
       }
       return rows.get( key );
@@ -1466,11 +1644,37 @@ export async function billingSummary( req, res ) {
       r.revenueMonths[inv._id.ym] = Math.round( ( ( inv.revenueInr || 0 ) + ( inv.revenueUsd || 0 ) * usdRate ) * 100 ) / 100;
       r.billedStoresMonths[inv._id.ym] = inv.stores || 0;
       r.installationFee += ( inv.installationInr || 0 ) + ( inv.installationUsd || 0 ) * usdRate;
+      r.invDollar += ( inv.dollarInvoices || 0 );
+      r.invInr += ( inv.inrInvoices || 0 );
       if ( inv.companyName ) {
         r.registeredEntity = inv.companyName;
       }
     }
 
+    // Resolve each row's currency from its actual invoices: 'dollar' only when
+    // the client has dollar invoices and NO inr invoices; otherwise 'inr'. The
+    // paymentInvoice.currencyType fallback set above stands only for clients
+    // with no invoices in the window.
+    for ( const r of rows.values() ) {
+      if ( r.invDollar > 0 || r.invInr > 0 ) {
+        r.currency = ( r.invDollar > 0 && r.invInr === 0 ) ? 'dollar' : 'inr';
+      }
+      delete r.invDollar;
+      delete r.invInr;
+    }
+
+    // A client may be actively billing yet have no invoice in the 5-month
+    // window (e.g. invoice for the running month not generated yet). Seed a
+    // row for any client that has a current-month store reading in
+    // dailyPricing, so the list reflects every brand under billing — not just
+    // the ones with a recent invoice. (Without this, brands silently vanish
+    // from the summary until their next invoice lands.)
+    for ( const [ clientId ] of curStoresByClient ) {
+      if ( clientById.has( clientId ) ) {
+        rowOf( clientId );
+      }
+    }
+
     const curKey = months[4].key;
     const prevKey = months[3].key;
     const data = [ ...rows.values() ].map( ( r ) => {
@@ -1491,7 +1695,12 @@ export async function billingSummary( req, res ) {
       }
       let pricePerStore = null;
       const pdoc = pricingByClient.get( r.clientId );
-      const isLive = ( name ) => r.liveProductSet.has( String( name || '' ).toLowerCase() );
+      // Price/Store counts only subscribed products — and never the one-time
+      // installationFee line, which isn't a per-store recurring price.
+      const isLive = ( name ) => {
+        const n = String( name || '' ).toLowerCase();
+        return n !== 'installationfee' && r.liveProductSet.has( n );
+      };
       if ( pdoc?.standard?.length ) {
         const liveRows = pdoc.standard.filter( ( p ) => isLive( p.productName ) );
         pricePerStore = liveRows.length ?
@@ -1573,7 +1782,44 @@ export async function billingSummary( req, res ) {
       };
     } ).sort( ( a, b ) => ( b.revCur || 0 ) - ( a.revCur || 0 ) );
 
-    return res.sendSuccess( { months, data, usdRate } );
+    // Server-side filters (GET query or POST body). CSM / Product / Variance /
+    // search narrow the per-client rows after they're computed, since those
+    // fields are derived during the merge above.
+    const f = { ...( req.query || {} ), ...( req.body || {} ) };
+    const csm = f.csm && f.csm !== 'All' ? String( f.csm ) : '';
+    const product = f.product && f.product !== 'All' ? String( f.product ) : '';
+    const variance = f.variance && f.variance !== 'All' ? String( f.variance ) : '';
+    const search = f.search ? String( f.search ).toLowerCase().trim() : '';
+
+    let filtered = data;
+    if ( csm ) {
+      filtered = filtered.filter( ( r ) => ( r.csm || '' ).split( ', ' ).includes( csm ) );
+    }
+    if ( product ) {
+      filtered = filtered.filter( ( r ) => ( r.products || [] ).includes( product ) );
+    }
+    if ( variance === 'growth' ) {
+      filtered = filtered.filter( ( r ) => r.variance > 0 );
+    } else if ( variance === 'decline' ) {
+      filtered = filtered.filter( ( r ) => r.variance < 0 );
+    } else if ( variance === 'flat' ) {
+      filtered = filtered.filter( ( r ) => r.variance === 0 );
+    }
+    if ( search ) {
+      filtered = filtered.filter( ( r ) =>
+        ( r.clientName || '' ).toLowerCase().includes( search ) ||
+        ( r.registeredEntity || '' ).toLowerCase().includes( search ) ||
+        String( r.clientId || '' ).includes( search ),
+      );
+    }
+
+    // Distinct option lists for the filter popover are derived from the FULL
+    // result set (not the filtered slice) so the dropdowns don't shrink as
+    // filters are applied.
+    const csmOptions = [ ...new Set( data.flatMap( ( r ) => String( r.csm || '' ).split( ', ' ).filter( Boolean ) ) ) ].sort();
+    const productOptions = [ ...new Set( data.flatMap( ( r ) => r.products || [] ) ) ].sort();
+
+    return res.sendSuccess( { months, data: filtered, total: data.length, csmOptions, productOptions, usdRate } );
   } catch ( error ) {
     logger.error( { error: error, function: 'billingSummary' } );
     return res.sendError( error, 500 );

package/src/controllers/estimate.controller.js

@@ -191,6 +191,69 @@ export async function createEstimate( req, res ) {
   }
 }
 
+export async function updateEstimate( req, res ) {
+  try {
+    const b = req.body || {};
+    const estimateId = b._id || b.estimateId || req.params.estimateId;
+    if ( !estimateId ) {
+      return res.sendError( 'estimateId is required', 400 );
+    }
+
+    const existing = await estimateService.findOne( { _id: estimateId } );
+    if ( !existing ) {
+      return res.sendError( 'Estimate not found', 404 );
+    }
+    // Accepted estimates are locked — mirrors the delete guard.
+    if ( ( existing._doc || existing ).status === 'accepted' ) {
+      return res.sendError( 'An accepted estimate cannot be edited.', 409 );
+    }
+
+    const amount = Math.round( Number( b.amount ) || 0 );
+    let totalAmount = Math.round( Number( b.totalAmount ) || 0 );
+    if ( !totalAmount && amount ) {
+      totalAmount = Math.round( amount * 1.18 );
+    }
+
+    // Only the editable fields are updated. The estimate number, index,
+    // clientId and createdDate are immutable so the document keeps its
+    // identity and financial-year sequence.
+    const update = {
+      companyName: b.companyName ?? existing.companyName,
+      companyAddress: b.companyAddress ?? existing.companyAddress,
+      PlaceOfSupply: b.PlaceOfSupply ?? existing.PlaceOfSupply,
+      GSTNumber: b.GSTNumber ?? existing.GSTNumber,
+      groupId: b.groupId || existing.groupId,
+      groupName: b.groupName || existing.groupName,
+      stores: Number( b.stores ) || 0,
+      products: Array.isArray( b.products ) ? b.products : existing.products,
+      tax: Array.isArray( b.tax ) ? b.tax : existing.tax,
+      amount,
+      totalAmount,
+      currency: b.currency || existing.currency,
+      notes: b.notes ?? existing.notes,
+      updatedBy: req.user?.email || req.user?.userName || '',
+    };
+    if ( b.validTill ) {
+      update.validTill = new Date( b.validTill );
+    }
+    if ( b.period ) {
+      update.period = b.period;
+    }
+    // Allow a status nudge (e.g. draft → sent) on save, but never to accepted.
+    if ( b.status && [ 'draft', 'sent' ].includes( b.status ) ) {
+      update.status = b.status;
+    }
+
+    await estimateService.updateOne( { _id: estimateId }, { $set: update } );
+    const saved = await estimateService.findOne( { _id: estimateId } );
+    logger.info?.( { function: 'updateEstimate', estimateId } );
+    return res.sendSuccess( saved );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'updateEstimate' } );
+    return res.sendError( error, 500 );
+  }
+}
+
 export async function getEstimate( req, res ) {
   try {
     const estimate = await estimateService.findOne( { _id: req.params.estimateId } );