tango-app-api-payment-subscription 3.5.27 → 3.5.28

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.27",
+    "version": "3.5.28",
     "description": "paymentSubscription",
     "main": "index.js",
     "type": "module",

package/scripts/test-advanceNewStore.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert';
+import dayjs from 'dayjs';
+import {
+  previousPeriodMonths, isNewStore, proratedAmount,
+  standardPriceFor, buildStepTiersByProduct, stepPriceForPosition,
+} from '../src/utils/advanceNewStore.util.js';
+
+// previousPeriodMonths: quarterly clicked in July 2026 → Apr, May, Jun 2026
+{
+  const today = dayjs('2026-07-15');
+  const r = previousPeriodMonths('quarterly', today);
+  assert.deepStrictEqual(r.months.map((m) => m.label), ['Apr 2026', 'May 2026', 'Jun 2026']);
+  assert.strictEqual(r.months[0].daysInMonth, 30); // April
+  assert.strictEqual(dayjs(r.periodStart).format('YYYY-MM-DD'), '2026-04-01');
+  assert.strictEqual(dayjs(r.periodEnd).format('YYYY-MM-DD'), '2026-06-30');
+}
+// halfyearly → last 6 completed months
+{
+  const r = previousPeriodMonths('halfyearly', dayjs('2026-07-15'));
+  assert.deepStrictEqual(r.months.map((m) => m.label),
+    ['Jan 2026', 'Feb 2026', 'Mar 2026', 'Apr 2026', 'May 2026', 'Jun 2026']);
+}
+// yearly, year-boundary: clicked Feb 2026 → prior 12 months Feb 2025 .. Jan 2026
+{
+  const r = previousPeriodMonths('yearly', dayjs('2026-02-10'));
+  assert.strictEqual(r.months[0].label, 'Feb 2025');
+  assert.strictEqual(r.months[r.months.length - 1].label, 'Jan 2026');
+  assert.strictEqual(r.months.length, 12);
+}
+// quarterly across year boundary: clicked Feb 2026 → Nov 2025, Dec 2025, Jan 2026
+{
+  const r = previousPeriodMonths('quarterly', dayjs('2026-02-10'));
+  assert.deepStrictEqual(r.months.map((m) => m.label), ['Nov 2025', 'Dec 2025', 'Jan 2026']);
+}
+// isNewStore inclusivity
+{
+  const start = dayjs('2026-04-01').toDate();
+  const end = dayjs('2026-06-30').toDate();
+  assert.strictEqual(isNewStore(dayjs('2026-04-01').toDate(), start, end), true);
+  assert.strictEqual(isNewStore(dayjs('2026-06-30').toDate(), start, end), true);
+  assert.strictEqual(isNewStore(dayjs('2026-03-31').toDate(), start, end), false);
+  assert.strictEqual(isNewStore(dayjs('2026-07-01').toDate(), start, end), false);
+  assert.strictEqual(isNewStore(null, start, end), false);
+  assert.strictEqual(isNewStore(undefined, start, end), false);
+}
+// proratedAmount matches annexure math: 3000/31*15 = 1451.6 → 1452
+{
+  assert.strictEqual(proratedAmount(3000, 31, 15), 1452);
+  assert.strictEqual(proratedAmount(3000, 30, 30), 3000); // full month
+  assert.strictEqual(proratedAmount(0, 31, 15), 0);
+}
+// standardPriceFor
+{
+  const std = [{ productName: 'Tango Traffic', negotiatePrice: 1499, basePrice: 1570 }];
+  assert.strictEqual(standardPriceFor(std, 'Tango Traffic'), 1499);
+  assert.strictEqual(standardPriceFor(std, 'Tango Zone'), 0);
+  assert.strictEqual(standardPriceFor([{ productName: 'X', basePrice: 500 }], 'X'), 500); // falls back to basePrice
+}
+// step tiers: position resolution + beyond-range fallback to last tier
+{
+  const tiers = buildStepTiersByProduct([
+    { productName: 'Tango Traffic', storeRange: '101-200', negotiatePrice: 900 },
+    { productName: 'Tango Traffic', storeRange: '1-100', negotiatePrice: 1000 },
+  ]);
+  assert.strictEqual(stepPriceForPosition(tiers, 'Tango Traffic', 50), 1000);  // tier 1
+  assert.strictEqual(stepPriceForPosition(tiers, 'Tango Traffic', 150), 900);  // tier 2
+  assert.strictEqual(stepPriceForPosition(tiers, 'Tango Traffic', 250), 900);  // beyond → last tier
+  assert.strictEqual(stepPriceForPosition(tiers, 'Missing', 1), 0);
+}
+console.log('ALL ADVANCE-NEWSTORE UTIL TESTS PASSED');

package/scripts/test-outstandingLines.mjs

@@ -0,0 +1,36 @@
+import assert from 'node:assert';
+import { groupOutstandingRowsToLines } from '../src/services/outstandingStores.service.js';
+
+// Rows for same product+month sum into one line; storeCount counts the rows,
+// price carries the per-store unit rate.
+{
+  const rows = [
+    { product: 'Tango Traffic', month: 'Apr 2026', amount: 1000, unitPrice: 1499 },
+    { product: 'Tango Traffic', month: 'Apr 2026', amount: 500, unitPrice: 1499 },
+    { product: 'Tango Traffic', month: 'May 2026', amount: 700, unitPrice: 1499 },
+    { product: 'Tango Zone', month: 'Apr 2026', amount: 300, unitPrice: 350 },
+  ];
+  const lines = groupOutstandingRowsToLines(rows);
+  // 3 distinct (product, month) groups.
+  assert.strictEqual(lines.length, 3);
+  const traApril = lines.find((l) => l.productName === 'Tango Traffic' && l.month === 'Apr 2026');
+  assert.strictEqual(traApril.amount, 1500);
+  assert.strictEqual(traApril.storeCount, 2); // two rows merged
+  assert.strictEqual(traApril.price, 750);    // AVERAGE per store: 1500 / 2
+  assert.strictEqual(traApril.description, 'Outstanding Apr 2026');
+  assert.strictEqual(traApril.HsnNumber, '998314');
+  const traMay = lines.find((l) => l.productName === 'Tango Traffic' && l.month === 'May 2026');
+  assert.strictEqual(traMay.amount, 700);
+  assert.strictEqual(traMay.storeCount, 1);
+  assert.strictEqual(traMay.price, 700);      // single store: avg == amount
+  const zoneApr = lines.find((l) => l.productName === 'Tango Zone' && l.month === 'Apr 2026');
+  assert.strictEqual(zoneApr.amount, 300);
+  assert.strictEqual(zoneApr.storeCount, 1);
+  assert.strictEqual(zoneApr.price, 300);     // single store: avg == amount
+}
+// Empty input → [].
+{
+  assert.deepStrictEqual(groupOutstandingRowsToLines([]), []);
+  assert.deepStrictEqual(groupOutstandingRowsToLines(null), []);
+}
+console.log('ALL OUTSTANDING-LINES TESTS PASSED');

package/src/controllers/advanceNewStoreExport.controller.js

@@ -0,0 +1,58 @@
+import * as billingService from '../services/billing.service.js';
+import dayjs from 'dayjs';
+import { logger } from 'tango-app-api-middleware';
+import ExcelJS from 'exceljs';
+import { computeOutstandingRows } from '../services/outstandingStores.service.js';
+import { previousPeriodMonths } from '../utils/advanceNewStore.util.js';
+
+const COLUMNS = [
+  { header: 'Store Name', key: 'storeName', width: 28 },
+  { header: 'Store ID', key: 'storeId', width: 16 },
+  { header: 'Product', key: 'product', width: 20 },
+  { header: 'Month', key: 'month', width: 14 },
+  { header: 'Working Days', key: 'workingDays', width: 14 },
+  { header: 'Deployment Date', key: 'deploymentDate', width: 16 },
+  { header: 'Unit Price', key: 'unitPrice', width: 14 },
+  { header: 'Amount', key: 'amount', width: 14 },
+];
+
+function isPeriodAllowed( advancePeriod ) {
+  return [ 'quarterly', 'halfyearly', 'yearly' ].includes( advancePeriod );
+}
+
+export async function advanceNewStoreExport( req, res ) {
+  try {
+    const groupId = req.query?.groupId;
+    if ( !groupId ) {
+      return res.sendError( 'groupId query parameter is required', 400 );
+    }
+    const group = await billingService.findOne( { _id: groupId } );
+    if ( !group ) {
+      return res.sendError( 'Billing group not found', 404 );
+    }
+    if ( !group.advanceInvoice || !isPeriodAllowed( group.advancePeriod ) ) {
+      return res.sendError( 'Group is not on quarterly/halfyearly/yearly advance invoicing', 400 );
+    }
+
+    const { months } = previousPeriodMonths( group.advancePeriod, dayjs() );
+    const rows = await computeOutstandingRows( group, dayjs() );
+
+    const wb = new ExcelJS.Workbook();
+    const ws = wb.addWorksheet( 'New Stores' );
+    ws.columns = COLUMNS;
+    ws.getRow( 1 ).font = { bold: true };
+    for ( const r of rows ) {
+      ws.addRow( r );
+    }
+    const buf = await wb.xlsx.writeBuffer();
+
+    const periodLabel = months.length ? `${months[0].label}_to_${months[months.length - 1].label}`.replace( / /g, '' ) : 'period';
+    const filename = `new-stores-${( group.groupName || 'group' ).replace( /[^a-z0-9]+/gi, '-' )}-${periodLabel}.xlsx`;
+    res.set( 'Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' );
+    res.set( 'Content-Disposition', `attachment; filename="${filename}"` );
+    return res.send( buf );
+  } catch ( error ) {
+    logger.error( { error, function: 'advanceNewStoreExport' } );
+    return res.sendError( error, 500 );
+  }
+}

package/src/controllers/invoice.controller.js

@@ -20,6 +20,7 @@ import * as assignedStoreService from '../services/assignedStore.service.js';
 import * as bankTransactionService from '../services/bankTransaction.service.js';
 import { getInrRate, getAdditionalProducts } from './brandsBilling.controller.js';
 import { applyInvoiceToPurchaseOrder } from './purchaseOrder.controller.js';
+import { computeOutstandingRows, groupOutstandingRowsToLines } from '../services/outstandingStores.service.js';
 
 // Pulls CSM + Finance head emails (stored under applicationDefault
 // type=invoice, subType=heads) AND the per-client CSMs assigned via
@@ -418,6 +419,45 @@ export async function createInvoice( req, res ) {
         logger.error( { error: oneTimeErr, function: 'createInvoice.oneTimeFee', clientId: group.clientId } );
       }
 
+      // Outstanding stores: when this group was flagged in the popup, append the
+      // previous-period new-store charges as grouped line items (one per product
+      // per month, tagged "Outstanding {Month}") so they're billed on this same
+      // invoice and taxed with the rest. Same dataset as the download export.
+      const outstandingGroupIds = ( req.body.outstandingGroupIds || [] ).map( String );
+      // Only append on a genuine ADVANCE invoice run (isAdvance). When an
+      // advance already covers this month we generate a normal monthly REUSE
+      // invoice (advanceCoverProducts set, isAdvance false) — appending here
+      // too would double-bill the same outstanding stores.
+      if ( isAdvance &&
+           outstandingGroupIds.includes( String( group._id ) ) &&
+           [ 'quarterly', 'halfyearly', 'yearly' ].includes( group.advancePeriod ) ) {
+        try {
+          const outRows = await computeOutstandingRows( group, dayjs() );
+          const outLines = groupOutstandingRowsToLines( outRows );
+          for ( const line of outLines ) {
+            products.push( {
+              productName: line.productName,
+              description: line.description,
+              month: line.month,
+              amount: line.amount,
+              // Per-store rate + outstanding store count so the invoice's Rate
+              // and Quantity/Stores columns render (amount stays authoritative —
+              // it's the summed prorated total, not price × count).
+              price: line.price,
+              storeCount: line.storeCount,
+              HsnNumber: line.HsnNumber,
+              totalZoneCount: 0,
+              totalTrafficCameraCount: 0,
+              totalZoneCameraCount: 0,
+              outstanding: true,
+            } );
+          }
+        } catch ( outErr ) {
+          logger.error( { error: outErr, function: 'createInvoice.outstanding', groupId: group._id } );
+          // Non-fatal: never block invoice generation over the outstanding add-on.
+        }
+      }
+
       let amount = products.reduce( ( sum, product ) => sum + product.amount, 0 );
       let taxList = [];
       let totalAmount = 0;

package/src/routes/billing.routes.js

@@ -6,12 +6,15 @@ import { triggerPaymentReminders } from '../controllers/paymentReminderTrigger.c
 import { createPurchaseOrder, getPurchaseOrders, updatePurchaseOrder, deletePurchaseOrder } from '../controllers/purchaseOrder.controller.js';
 import { createBillingGroup, deleteBillingGroup, getAllBillingGroups, getBillingGroups, getClientProducts, getInvoices, getLeadProducts, getBaseProducts, 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';
+import { advanceNewStoreExport } from '../controllers/advanceNewStoreExport.controller.js';
 
 
 billingRouter.post( '/get-subscribed-store-list', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), validate( subscribedStoreListSchema ), subscribedStoreList );
 
 billingRouter.get( '/get-all-billing-groups', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), validate( getBillingGroupsSchema ), getAllBillingGroups );
 
+billingRouter.get( '/advance-newstore-export', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), advanceNewStoreExport );
+
 billingRouter.post( '/create-group', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), validate( createBillingGroupsSchema ), createBillingGroup );
 
 billingRouter.put( '/update-group', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'Global', name: 'Billing', permissions: [ 'isAdd' ] } ] } ), validate( updateBillingGroupsSchema ), updateBillingGroup );

package/src/services/outstandingStores.service.js

@@ -0,0 +1,125 @@
+import * as clientService from './clientPayment.services.js';
+import * as dailyPriceService from './dailyPrice.service.js';
+import * as storeService from './store.service.js';
+import * as basePriceService from './basePrice.service.js';
+import dayjs from 'dayjs';
+import { logger } from 'tango-app-api-middleware';
+import {
+  previousPeriodMonths, isNewStore, proratedAmount,
+  standardPriceFor, buildStepTiersByProduct, stepPriceForPosition,
+} from '../utils/advanceNewStore.util.js';
+
+function isPeriodAllowed( advancePeriod ) {
+  return [ 'quarterly', 'halfyearly', 'yearly' ].includes( advancePeriod );
+}
+
+// Per-(store × product × month) outstanding rows for a group's previous period.
+// This is the SAME dataset the Excel export renders — kept here so the export
+// and invoice generation share one source of truth.
+export async function computeOutstandingRows( group, today = dayjs() ) {
+  if ( !group || !group.advanceInvoice || !isPeriodAllowed( group.advancePeriod ) ) {
+    return [];
+  }
+
+  const { months, periodStart, periodEnd } = previousPeriodMonths( group.advancePeriod, today );
+  const groupStoreIds = ( group.stores || [] ).map( String );
+
+  // New stores: group stores whose edge.firstFileDate is within the period.
+  const storeDocs = groupStoreIds.length ?
+    await storeService.find(
+        { storeId: { $in: groupStoreIds } },
+        { 'storeId': 1, 'storeName': 1, 'edge.firstFileDate': 1 },
+    ) : [];
+  const newStores = storeDocs.filter(
+      ( s ) => isNewStore( s?.edge?.firstFileDate, periodStart, periodEnd ) );
+  const newStoreById = new Map( newStores.map( ( s ) => [ String( s.storeId ), s ] ) );
+
+  // Pricing: standard flat + step tiers, keyed by product. priceType from client.
+  const bp = await basePriceService.findOne(
+      { clientId: group.clientId }, { standard: 1, step: 1, currency: 1 } );
+  const client = await clientService.findOne( { clientId: group.clientId }, { priceType: 1 } );
+  const isStep = client?.priceType === 'step';
+  const stepTiers = isStep ? buildStepTiersByProduct( bp?.step ) : {};
+
+  const rows = [];
+  for ( const m of months ) {
+    // Last dailyPricing snapshot within this month for the client.
+    const snap = ( await dailyPriceService.find(
+        { clientId: group.clientId, dateISO: { $gte: m.start, $lte: m.end } },
+    ) ).sort( ( a, b ) => new Date( b.dateISO ) - new Date( a.dateISO ) )[0];
+    if ( !snap ) {
+      logger.error( { function: 'computeOutstandingRows', msg: 'no snapshot', month: m.label } );
+      continue;
+    }
+    // Step-tier position is 1-based PER PRODUCT, counting only stores that run
+    // that product, in snapshot iteration order — mirrors the per-product
+    // counter in brandsBilling.controller.js (positionByProduct++), not a
+    // fixed group-array index. Reset per month/snapshot.
+    const positionByProduct = {};
+    for ( const store of ( snap.stores || [] ) ) {
+      const ns = newStoreById.get( String( store.storeId ) );
+      for ( const p of ( store.products || [] ) ) {
+        // Advance the per-product position for EVERY store carrying the
+        // product (new or not) so tier positions match the full store set.
+        const pos = ( positionByProduct[p.productName] = ( positionByProduct[p.productName] || 0 ) + 1 );
+        if ( !ns ) {
+          continue; // count position, but only new stores get rows
+        }
+        const workingDays = Number( p.workingdays ) || 0;
+        if ( workingDays <= 0 ) {
+          continue;
+        }
+        const unitPrice = isStep ?
+          stepPriceForPosition( stepTiers, p.productName, pos ) :
+          standardPriceFor( bp?.standard, p.productName );
+        rows.push( {
+          storeName: ns.storeName || store.storeName || '',
+          storeId: String( store.storeId ),
+          product: p.productName || '',
+          month: m.label,
+          workingDays,
+          deploymentDate: ns?.edge?.firstFileDate ? dayjs( ns.edge.firstFileDate ).format( 'YYYY-MM-DD' ) : '',
+          unitPrice,
+          amount: proratedAmount( unitPrice, m.daysInMonth, workingDays ),
+        } );
+      }
+    }
+  }
+  return rows;
+}
+
+// Collapse per-(store × product × month) rows into invoice line items:
+// one line per (productName, month). Amount is the summed prorated total;
+// storeCount is the number of outstanding stores; price is the AVERAGE per-store
+// amount (amount / storeCount), shown in the "Rate" column. Tagged
+// "Outstanding {Month}". Amount is the authoritative billed value; because it
+// sums per-store PRORATED amounts (stores have differing working days), the
+// average rate is a blended figure rather than the flat unit price.
+export function groupOutstandingRowsToLines( rows ) {
+  const byKey = new Map();
+  for ( const r of ( rows || [] ) ) {
+    const key = `${r.product}||${r.month}`;
+    const existing = byKey.get( key );
+    if ( existing ) {
+      existing.amount += Number( r.amount ) || 0;
+      existing.storeCount += 1;
+    } else {
+      byKey.set( key, {
+        productName: r.product,
+        month: r.month,
+        amount: Number( r.amount ) || 0,
+        // Number of outstanding stores billed on this line (the "Quantity"/
+        // "Stores" column).
+        storeCount: 1,
+        description: `Outstanding ${r.month}`,
+        HsnNumber: '998314',
+      } );
+    }
+  }
+  // Rate column = average per-store amount (blended). Computed after summing.
+  const lines = Array.from( byKey.values() );
+  for ( const line of lines ) {
+    line.price = line.storeCount > 0 ? Math.round( line.amount / line.storeCount ) : 0;
+  }
+  return lines;
+}

package/src/utils/advanceNewStore.util.js

@@ -0,0 +1,89 @@
+import dayjs from 'dayjs';
+
+export const PERIOD_MONTHS = { monthly: 1, quarterly: 3, halfyearly: 6, yearly: 12 };
+
+// The last N completed months ending LAST month (relative to `today`), where N
+// is driven by the advance period. Returns month labels ('MMM YYYY') plus each
+// month's start/end Date and actual day count, and the overall period range.
+export function previousPeriodMonths( advancePeriod, today = dayjs() ) {
+  const n = PERIOD_MONTHS[advancePeriod] || 1;
+  const base = dayjs( today );
+  const months = [];
+  // i = n (oldest) .. 1 (last month). month = base minus i months.
+  for ( let i = n; i >= 1; i-- ) {
+    const m = base.subtract( i, 'month' );
+    months.push( {
+      label: m.format( 'MMM YYYY' ),
+      start: m.startOf( 'month' ).toDate(),
+      end: m.endOf( 'month' ).toDate(),
+      daysInMonth: m.daysInMonth(),
+    } );
+  }
+  return {
+    months,
+    periodStart: months.length ? months[0].start : null,
+    periodEnd: months.length ? months[months.length - 1].end : null,
+  };
+}
+
+export function isNewStore( firstFileDate, periodStart, periodEnd ) {
+  if ( !firstFileDate ) {
+    return false;
+  }
+  const d = dayjs( firstFileDate );
+  return ( d.isSame( periodStart ) || d.isAfter( periodStart ) ) &&
+         ( d.isSame( periodEnd ) || d.isBefore( periodEnd ) );
+}
+
+export function proratedAmount( unitPrice, daysInMonth, workingDays ) {
+  const price = Number( unitPrice ) || 0;
+  const days = Number( daysInMonth ) || 0;
+  const wd = Number( workingDays ) || 0;
+  if ( !price || !days ) {
+    return 0;
+  }
+  return Math.round( ( price / days ) * wd );
+}
+
+export function standardPriceFor( standardArr, productName ) {
+  const p = ( standardArr || [] ).find( ( x ) => x.productName === productName );
+  if ( !p ) {
+    return 0;
+  }
+  return Number( p.negotiatePrice ) || Number( p.basePrice ) || 0;
+}
+
+export function buildStepTiersByProduct( stepArr ) {
+  const byProduct = {};
+  for ( const p of ( stepArr || [] ) ) {
+    if ( !p.productName ) {
+      continue;
+    }
+    ( byProduct[p.productName] = byProduct[p.productName] || [] ).push( p );
+  }
+  for ( const name of Object.keys( byProduct ) ) {
+    byProduct[name].sort( ( a, b ) => {
+      const aStart = parseInt( String( a.storeRange || '0' ).split( '-' )[0], 10 ) || 0;
+      const bStart = parseInt( String( b.storeRange || '0' ).split( '-' )[0], 10 ) || 0;
+      return aStart - bStart;
+    } );
+  }
+  return byProduct;
+}
+
+// 1-based position within the product's stores → tier rate; beyond the defined
+// ranges falls back to the last tier (mirrors invoice/brandsBilling stepPrice).
+export function stepPriceForPosition( stepTiersByProduct, productName, positionInProduct ) {
+  const tiers = ( stepTiersByProduct || {} )[productName] || [];
+  if ( !tiers.length ) {
+    return 0;
+  }
+  for ( const tier of tiers ) {
+    const [ min, max ] = String( tier.storeRange || '' ).split( '-' ).map( Number );
+    if ( positionInProduct >= min && positionInProduct <= max ) {
+      return Number( tier.negotiatePrice ) || Number( tier.basePrice ) || 0;
+    }
+  }
+  const last = tiers[tiers.length - 1];
+  return Number( last.negotiatePrice ) || Number( last.basePrice ) || 0;
+}