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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.6",
+    "version": "3.5.7",
     "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.26",
         "tango-app-api-middleware": "^3.6.18",
         "winston": "^3.12.0",
         "winston-daily-rotate-file": "^5.0.0",

package/src/controllers/brandsBilling.controller.js

@@ -164,19 +164,93 @@ export async function brandsBillingList( req, res ) {
 
     let allData = await clientService.aggregate( query );
 
-    if ( allData.length == 0 ) {
-      return res.sendError( 'No data', 204 );
-    }
+    // 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' },
+            ],
+            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 };
+    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 };
+      }
+      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,
+      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 +600,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 +641,7 @@ export async function latestDailyPricing( req, res ) {
       proRate: record.proRate,
       count,
       data: storeList,
+      monthlyBillingSummary,
     };
 
     res.sendSuccess( data );
@@ -1305,7 +1410,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;
@@ -1491,7 +1596,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 +1683,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/invoice.controller.js

@@ -17,6 +17,7 @@ import { symbolFor } from '../utils/currency.js';
 import { invoiceStatusEnum } from '../dtos/validation.dtos.js';
 import { findOneApplicationDefault } from '../services/applicationDefault.service.js';
 import * as assignedStoreService from '../services/assignedStore.service.js';
+import { getUsdInrRate } from './brandsBilling.controller.js';
 
 // Pulls CSM + Finance head emails (stored under applicationDefault
 // type=invoice, subType=heads) AND the per-client CSMs assigned via
@@ -1895,35 +1896,42 @@ export async function clientInvoiceList( req, res ) {
       }
     }
 
-    // Card totals — computed over the user's full client scope (findClients),
-    // NOT the currently-filtered/paged view, so the cards stay stable as the
-    // user narrows the list with filters. Outstanding is everything unpaid;
-    // Overdue is the past-due subset; Pending Payment is the approved-but-
-    // unpaid subset. "Outstanding amount" uses totalAmount - paidAmount so a
-    // partially-paid invoice contributes only its remaining balance.
+    // Card totals — computed over the CURRENTLY-FILTERED result set (`count`
+    // holds every invoice matching the active filters, pre-pagination), so the
+    // cards reflect exactly what the filters select. Dollar invoices are
+    // converted to INR at today's rate so all three totals are a single ₹
+    // figure. Outstanding = unpaid remaining (totalAmount - paidAmount);
+    // Overdue = past-due unpaid subset; Pending Payment = approved-but-unpaid.
+    const usdRate = await getUsdInrRate();
     const now = new Date();
-    const remaining = { $subtract: [
-      { $ifNull: [ '$totalAmount', { $ifNull: [ '$amount', 0 ] } ] },
-      { $ifNull: [ '$paidAmount', 0 ] },
-    ] };
-    const cardsAggregate = await invoiceService.aggregate( [
-      { $match: { clientId: { $in: findClients }, paymentStatus: { $ne: 'paid' } } },
-      { $group: {
-        _id: null,
-        outstandingAmount: { $sum: remaining },
-        outstandingCount: { $sum: 1 },
-        overdueAmount: { $sum: { $cond: [ { $lt: [ '$dueDate', now ] }, remaining, 0 ] } },
-        overdueCount: { $sum: { $cond: [ { $lt: [ '$dueDate', now ] }, 1, 0 ] } },
-        pendingPaymentAmount: { $sum: { $cond: [ { $eq: [ '$status', 'approved' ] }, remaining, 0 ] } },
-        pendingPaymentCount: { $sum: { $cond: [ { $eq: [ '$status', 'approved' ] }, 1, 0 ] } },
-      } },
-    ] );
-    const cards = cardsAggregate[0] || {
+    const cards = {
       outstandingAmount: 0, outstandingCount: 0,
       overdueAmount: 0, overdueCount: 0,
       pendingPaymentAmount: 0, pendingPaymentCount: 0,
     };
-    delete cards._id;
+    for ( const inv of count ) {
+      if ( inv.paymentStatus === 'paid' ) {
+        continue;
+      }
+      const fx = inv.currency === 'dollar' ? usdRate : 1;
+      const total = Number( inv.totalAmount ) || Number( inv.amount ) || 0;
+      const paid = Number( inv.paidAmount ) || 0;
+      const remaining = Math.max( 0, total - paid ) * fx;
+
+      cards.outstandingAmount += remaining;
+      cards.outstandingCount += 1;
+      if ( inv.dueDate && new Date( inv.dueDate ) < now ) {
+        cards.overdueAmount += remaining;
+        cards.overdueCount += 1;
+      }
+      if ( inv.status === 'approved' ) {
+        cards.pendingPaymentAmount += remaining;
+        cards.pendingPaymentCount += 1;
+      }
+    }
+    cards.outstandingAmount = Math.round( cards.outstandingAmount * 100 ) / 100;
+    cards.overdueAmount = Math.round( cards.overdueAmount * 100 ) / 100;
+    cards.pendingPaymentAmount = Math.round( cards.pendingPaymentAmount * 100 ) / 100;
 
     res.sendSuccess( { count: count.length, data: invoiceList, cards } );
   } catch ( error ) {

package/src/controllers/paymentReminder.controller.js

@@ -0,0 +1,81 @@
+import * as paymentReminderService from '../services/paymentReminder.service.js';
+import { logger } from 'tango-app-api-middleware';
+
+// Payment reminder config (Billing Settings page). One document per brand
+// (clientId): recipient emails + five toggleable reminder templates. Returns
+// sensible defaults when a brand has no config saved yet.
+const DEFAULTS = () => ( {
+  reminderEmails: [],
+  templates: {
+    preDue: { enabled: true, daysBefore: 3 },
+    onDue: { enabled: true },
+    onHold: { enabled: true },
+    suspend: { enabled: true },
+    deactivated: { enabled: false },
+  },
+} );
+
+export async function getPaymentReminder( req, res ) {
+  try {
+    const clientId = req.params.clientId || req.query.clientId;
+    if ( !clientId ) {
+      return res.sendError( 'clientId is required', 400 );
+    }
+    const existing = await paymentReminderService.findOne( { clientId } );
+    if ( !existing ) {
+      return res.sendSuccess( { clientId, ...DEFAULTS(), isDefault: true } );
+    }
+    return res.sendSuccess( existing );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'getPaymentReminder' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+export async function savePaymentReminder( req, res ) {
+  try {
+    const b = req.body || {};
+    if ( !b.clientId ) {
+      return res.sendError( 'clientId is required', 400 );
+    }
+
+    // Normalize recipients: trim, drop blanks, de-dupe.
+    const emails = Array.isArray( b.reminderEmails ) ? b.reminderEmails : [];
+    const reminderEmails = [ ...new Set(
+        emails.map( ( e ) => String( e || '' ).trim() ).filter( Boolean ),
+    ) ];
+
+    const t = b.templates || {};
+    const bool = ( v, d ) => ( typeof v === 'boolean' ? v : d );
+    let daysBefore = Number( t.preDue?.daysBefore );
+    if ( !Number.isFinite( daysBefore ) ) {
+      daysBefore = 3;
+    }
+    daysBefore = Math.min( 365, Math.max( 1, Math.round( daysBefore ) ) );
+
+    const templates = {
+      preDue: { enabled: bool( t.preDue?.enabled, true ), daysBefore },
+      onDue: { enabled: bool( t.onDue?.enabled, true ) },
+      onHold: { enabled: bool( t.onHold?.enabled, true ) },
+      suspend: { enabled: bool( t.suspend?.enabled, true ) },
+      deactivated: { enabled: bool( t.deactivated?.enabled, false ) },
+    };
+
+    await paymentReminderService.upsert(
+        { clientId: b.clientId },
+        {
+          clientId: b.clientId,
+          reminderEmails,
+          templates,
+          updatedBy: req.user?.email || req.user?.userName || '',
+        },
+    );
+
+    const saved = await paymentReminderService.findOne( { clientId: b.clientId } );
+    logger.info?.( { function: 'savePaymentReminder', clientId: b.clientId } );
+    return res.sendSuccess( saved );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'savePaymentReminder' } );
+    return res.sendError( error, 500 );
+  }
+}

package/src/routes/billing.routes.js

@@ -1,6 +1,7 @@
 import express from 'express';
 export const billingRouter = express.Router();
 import { accessVerification, isAllowedSessionHandler, validate } from 'tango-app-api-middleware';
+import { getPaymentReminder, savePaymentReminder } from '../controllers/paymentReminder.controller.js';
 import { createBillingGroup, deleteBillingGroup, getAllBillingGroups, getBillingGroups, getClientProducts, getInvoices, getLeadProducts, onetimePayment, subscribedStoreList, updateBillingGroup, gstinLookup } from '../controllers/billing.controllers.js';
 import { billingGroupSchema, clientProductsValid, createBillingGroupsSchema, deleteBillingGroupsSchema, getBillingGroupsSchema, getInvoiceSchema, leadProductsValid, onetimeFeeValid, subscribedStoreListSchema, updateBillingGroupsSchema } from '../dtos/validation.dtos.js';
 
@@ -28,3 +29,7 @@ billingRouter.get( '/getClientProducts/:id', isAllowedSessionHandler, validate(
 
 
 billingRouter.get( '/gst-lookup/:gstin', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), gstinLookup );
+
+// Payment reminder config (Billing Settings page), one document per brand.
+billingRouter.get( '/payment-reminder/:clientId', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), getPaymentReminder );
+billingRouter.post( '/payment-reminder', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), savePaymentReminder );

package/src/routes/brandsBilling.routes.js

@@ -14,4 +14,5 @@ brandsBillingRouter.put( '/updateDailyPricingStoreField', isAllowedSessionHandle
 brandsBillingRouter.post( '/getClientBillingInfo', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), getClientBillingInfo );
 brandsBillingRouter.get( '/bulk-download-billing-groups', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), bulkDownloadBillingGroups );
 brandsBillingRouter.post( '/bulk-update-billing-groups', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), bulkUpdateBillingGroups );
+brandsBillingRouter.post( '/billingSummary', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), billingSummary );
 brandsBillingRouter.get( '/billingSummary', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), billingSummary );

package/src/services/paymentReminder.service.js

@@ -0,0 +1,9 @@
+import model from 'tango-api-schema';
+
+export const findOne = async ( query = {}, projection = {} ) => {
+  return await model.paymentReminderModel.findOne( query, projection );
+};
+
+export const upsert = async ( filter, update ) => {
+  return await model.paymentReminderModel.updateOne( filter, { $set: update }, { upsert: true } );
+};