tango-app-api-payment-subscription 3.5.22 → 3.5.24

package/src/controllers/brandsBilling.controller.js

@@ -8,7 +8,7 @@ import * as basePriceService from '../services/basePrice.service.js';
 import * as cameraService from '../services/camera.service.js';
 import * as planogramService from '../services/planogram.service.js';
 import dayjs from 'dayjs';
-import { logger, checkFileExist, signedUrl, download, insertOpenSearchData, getOpenSearchData } from 'tango-app-api-middleware';
+import { logger, checkFileExist, signedUrl, download, insertOpenSearchData, getOpenSearchData, searchOpenSearchData, scrollResponse, clearScroll } from 'tango-app-api-middleware';
 import * as XLSX from 'xlsx';
 import ExcelJS from 'exceljs';
 import { bulkUpdateBillingGroupRowSchema } from '../dtos/validation.dtos.js';
@@ -428,6 +428,15 @@ export async function brandInvoiceList( req, res ) {
       },
     } ];
 
+    // Invoice type sub-toggle: 'advance' shows only advance invoices (invoice #
+    // starts with 'TINV-'); 'all' shows only regular invoices (NOT TINV-*).
+    // Applied to the whole pipeline so list, count, summary and cards match.
+    if ( req.body.invoiceType === 'advance' ) {
+      query.push( { $match: { invoice: { $regex: '^TINV-' } } } );
+    } else if ( req.body.invoiceType === 'all' ) {
+      query.push( { $match: { invoice: { $not: { $regex: '^TINV-' } } } } );
+    }
+
     // Client users only ever see APPROVED invoices — the approval pipeline
     // (pendingCsm/pendingFinance/pendingApproval/pending) is internal to tango
     // and must not be exposed to clients, even in the raw list response.
@@ -580,16 +589,18 @@ export async function brandInvoiceList( req, res ) {
     }
 
     // Footer totals are shown in a single ₹ figure, but individual invoices may
-    // be in USD ($). Convert dollar invoices to INR at today's rate before
-    // summing so the ₹ total is correct (mirrors the table's per-invoice symbol
-    // → one combined rupee total).
-    const usdRate = await getUsdInrRate();
-    const toInr = ( inv, value ) => ( inv.currency === 'dollar' ? ( Number( value ) || 0 ) * usdRate : ( Number( value ) || 0 ) );
+    // be in a foreign currency ($, €, S$, AED). Convert each to INR at today's
+    // rate (per-currency, not just USD) before summing so the ₹ total is correct.
+    const rateByCurrency = {};
+    for ( const cur of new Set( allInvoices.map( ( c ) => String( c.currency || 'inr' ) ) ) ) {
+      rateByCurrency[cur] = await getInrRate( cur );
+    }
+    const toInr = ( inv, value ) => ( Number( value ) || 0 ) * ( rateByCurrency[String( inv.currency || 'inr' )] || 1 );
     let summary = {
       totalInvoices: allInvoices.length,
       totalInvoiced: Math.round( allInvoices.reduce( ( sum, inv ) => sum + toInr( inv, inv.totalAmount ), 0 ) ),
       // Footer totals over the FULL filtered set (not just the current page):
-      // stores, amount excl. GST and amount incl. GST (USD → INR converted).
+      // stores, amount excl. GST and amount incl. GST (foreign → INR converted).
       totalStores: allInvoices.reduce( ( sum, inv ) => sum + ( inv.stores || 0 ), 0 ),
       totalAmountExclGst: Math.round( allInvoices.reduce( ( sum, inv ) => sum + toInr( inv, inv.amount ), 0 ) ),
       totalAmountInclGst: Math.round( allInvoices.reduce( ( sum, inv ) => sum + toInr( inv, inv.totalAmount ), 0 ) ),
@@ -598,6 +609,41 @@ export async function brandInvoiceList( req, res ) {
       paid: allInvoices.filter( ( inv ) => inv.paymentStatus === 'paid' ).length,
     };
 
+    // Header cards — Outstanding / Overdue / Pending Payment — each split into a
+    // GST excl (sum of `amount`) and incl (sum of `totalAmount`) figure, all
+    // converted to INR. Same shape/semantics as the All Invoices page cards.
+    const nowDate = new Date();
+    const cards = {
+      outstandingExclAmount: 0, outstandingInclAmount: 0, outstandingCount: 0,
+      overdueExclAmount: 0, overdueInclAmount: 0, overdueCount: 0,
+      pendingPaymentExclAmount: 0, pendingPaymentInclAmount: 0, pendingPaymentCount: 0,
+    };
+    for ( const inv of allInvoices ) {
+      if ( inv.paymentStatus === 'paid' ) {
+        continue;
+      }
+      const excl = toInr( inv, inv.amount );
+      const incl = toInr( inv, inv.totalAmount || inv.amount );
+      cards.outstandingExclAmount += excl;
+      cards.outstandingInclAmount += incl;
+      cards.outstandingCount += 1;
+      if ( inv.dueDate && new Date( inv.dueDate ) < nowDate ) {
+        cards.overdueExclAmount += excl;
+        cards.overdueInclAmount += incl;
+        cards.overdueCount += 1;
+      }
+      if ( inv.status === 'approved' ) {
+        cards.pendingPaymentExclAmount += excl;
+        cards.pendingPaymentInclAmount += incl;
+        cards.pendingPaymentCount += 1;
+      }
+    }
+    for ( const k of Object.keys( cards ) ) {
+      if ( k.endsWith( 'Amount' ) ) {
+        cards[k] = Math.round( cards[k] );
+      }
+    }
+
     if ( req.body.export ) {
       // Mirror the on-screen table exactly: same columns (excl. GST and incl.
       // GST as separate amounts), same currency symbol, and the same status
@@ -653,7 +699,7 @@ export async function brandInvoiceList( req, res ) {
     clientInfo.totalStores = billingGroups.reduce( ( sum, bg ) => sum + ( bg.stores ? bg.stores.length : 0 ), 0 );
     clientInfo.totalGroups = billingGroups.length;
 
-    res.sendSuccess( { clientInfo, summary, count, data: invoiceList } );
+    res.sendSuccess( { clientInfo, summary, cards, count, data: invoiceList } );
   } catch ( error ) {
     logger.error( { error: error, function: 'brandInvoiceList' } );
     return res.sendError( error, 500 );
@@ -688,6 +734,27 @@ export async function latestDailyPricing( req, res ) {
     let stores = record.stores || [];
     let count = stores.length;
 
+    // The daily-pricing store objects don't carry the store's country — it lives
+    // in the stores collection under storeProfile.country. Build a
+    // storeId → country map for this client and stamp `country` onto each store
+    // so the UI can show it as a column and filter by it.
+    const countryByStore = new Map();
+    try {
+      const storeDocs = await storeService.find(
+          { clientId: req.body.clientId },
+          { 'storeId': 1, 'storeProfile.country': 1 },
+      );
+      for ( const s of ( storeDocs || [] ) ) {
+        countryByStore.set( String( s.storeId ), s?.storeProfile?.country || '' );
+      }
+    } catch ( cErr ) {
+      logger.error( { error: cErr, function: 'latestDailyPricing.country', clientId: req.body.clientId } );
+    }
+    stores = stores.map( ( s ) => {
+      const base = s._doc || s;
+      return { ...base, country: countryByStore.get( String( base.storeId ) ) || '' };
+    } );
+
     // statusFilter may be an array (multi-select) or a legacy string. An empty
     // value / empty array means "all statuses".
     const statusFilterList = Array.isArray( req.body.statusFilter ) ?
@@ -698,6 +765,15 @@ export async function latestDailyPricing( req, res ) {
       stores = stores.filter( ( s ) => allowed.has( s.status ) );
     }
 
+    // countryFilter may be an array (multi-select) or a string; empty = all.
+    const countryFilterList = Array.isArray( req.body.countryFilter ) ?
+      req.body.countryFilter.filter( Boolean ) :
+      ( req.body.countryFilter ? [ req.body.countryFilter ] : [] );
+    if ( countryFilterList.length ) {
+      const allowedCountries = new Set( countryFilterList );
+      stores = stores.filter( ( s ) => allowedCountries.has( s.country ) );
+    }
+
     if ( req.body.searchValue && req.body.searchValue !== '' ) {
       const searchRegex = new RegExp( req.body.searchValue, 'i' );
       stores = stores.filter( ( s ) => searchRegex.test( s.storeName ) || searchRegex.test( s.storeId ) );
@@ -928,6 +1004,11 @@ export async function latestDailyPricing( req, res ) {
         .sort( ( a, b ) => a.firstFileDate.localeCompare( b.firstFileDate ) );
     const newlyOnboardedStores = newlyOnboardedStoreList.length;
 
+    // Unique, sorted, non-empty countries across ALL of the client's stores
+    // (from the map above) — feeds the Country filter dropdown independent of
+    // the current page / status / country selection.
+    const countries = [ ...new Set( [ ...countryByStore.values() ].filter( Boolean ) ) ].sort();
+
     let data = {
       clientId: record.clientId,
       brandName: record.brandName,
@@ -938,6 +1019,7 @@ export async function latestDailyPricing( req, res ) {
       status: record.status,
       proRate: record.proRate,
       count,
+      countries,
       newlyOnboardedStores,
       newlyOnboardedStoreList,
       data: storeList,
@@ -1709,30 +1791,60 @@ export async function bulkUpdateBillingGroups( req, res ) {
 // including the current. Filtering/sorting happen client-side (the dataset
 // is one row per client).
 // ---------------------------------------------------------------------------
+// Live USD-based FX rates (cached 6h) from open.er-api.com. The response gives
+// every currency relative to USD (rates.INR, rates.EUR, rates.SGD, …), so we
+// cache the whole table and derive any currency→INR rate as rates.INR / rates.X.
+let fxRatesCache = { rates: null, at: 0 };
+async function getUsdRates() {
+  if ( fxRatesCache.rates && ( Date.now() - fxRatesCache.at ) < 6 * 60 * 60 * 1000 ) {
+    return fxRatesCache.rates;
+  }
+  try {
+    const resp = await fetch( 'https://open.er-api.com/v6/latest/USD', { signal: AbortSignal.timeout( 4000 ) } );
+    const body = await resp.json();
+    if ( body?.rates && Number( body.rates.INR ) > 0 ) {
+      fxRatesCache = { rates: body.rates, at: Date.now() };
+      return body.rates;
+    }
+  } catch ( err ) {
+    logger.error( { error: err, function: 'getUsdRates' } );
+  }
+  return fxRatesCache.rates; // may be null on cold-start failure
+}
+
 // Today's USD->INR rate for dollar-priced clients. Live rate (cached 6h)
 // 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 };
 export async function getUsdInrRate() {
   const override = Number( process.env.USD_INR_RATE );
   if ( override > 0 ) {
     return override;
   }
-  if ( usdRateCache.rate && ( Date.now() - usdRateCache.at ) < 6 * 60 * 60 * 1000 ) {
-    return usdRateCache.rate;
+  const rates = await getUsdRates();
+  const rate = Number( rates?.INR );
+  return rate > 0 ? rate : 83.33;
+}
+
+// The app's own currency codes → ISO codes used by the FX API.
+const CURRENCY_ISO = { inr: 'INR', dollar: 'USD', usd: 'USD', euro: 'EUR', eur: 'EUR', singaporedollar: 'SGD', sgd: 'SGD', aed: 'AED' };
+// Static last-resort rates (currency→INR) if the FX API is unreachable on a
+// cold start. Approximate; only used so totals aren't wildly wrong.
+const FALLBACK_INR = { INR: 1, USD: 83.33, EUR: 90, SGD: 62, AED: 22.7 };
+
+// Multiplier to convert an amount in `currency` to INR. INR → 1. Unknown
+// currencies fall back to 1 (treated as already-INR) so nothing is dropped.
+export async function getInrRate( currency ) {
+  const iso = CURRENCY_ISO[String( currency || '' ).toLowerCase()];
+  if ( !iso || iso === 'INR' ) {
+    return 1;
   }
-  try {
-    const resp = await fetch( 'https://open.er-api.com/v6/latest/USD', { signal: AbortSignal.timeout( 4000 ) } );
-    const body = await resp.json();
-    const rate = Number( body?.rates?.INR );
-    if ( rate > 0 ) {
-      usdRateCache = { rate, at: Date.now() };
-      return rate;
-    }
-  } catch ( err ) {
-    logger.error( { error: err, function: 'getUsdInrRate' } );
+  const rates = await getUsdRates();
+  const inr = Number( rates?.INR );
+  const cur = Number( rates?.[iso] );
+  if ( inr > 0 && cur > 0 ) {
+    return inr / cur; // 1 <currency> = (INR per USD) / (currency per USD) INR
   }
-  return usdRateCache.rate || 83.33;
+  return FALLBACK_INR[iso] || 1;
 }
 
 export async function billingSummary( req, res ) {
@@ -2185,6 +2297,11 @@ const ADDITIONAL_PRODUCT_PRICES = {
   planogram: 770,
   aiManager: 500,
 };
+// Product Lambda Function URLs (VMS / Run AI). Each returns the list of billable
+// store IDs for a client; used both for the detailed export and for the invoice
+// additional-products quantity (scoped to a billing group's stores).
+const RUN_AI_LAMBDA_URL = 'https://mdm3mf7wuficgv3jjspkws2nu40azlsc.lambda-url.ap-south-1.on.aws/';
+const VMS_LAMBDA_URL = 'https://ppf3l3mxc2lorh5hkrsj6zwyim0bupxw.lambda-url.ap-south-1.on.aws/';
 // OpenSearch index holding extra billed products (VMS, Run AI, etc.). Each
 // record is a daily snapshot carrying its own quantity + price per product.
 const BILLING_DETAILS_INDEX = ( () => {
@@ -2199,12 +2316,37 @@ const BILLING_DETAILS_INDEX = ( () => {
 // that has none (currently only clientId 11). Shared by the Billing Breakdown
 // table (additionalProducts controller) AND invoice generation, so both stay in
 // sync. Each entry: { productName, quantity, price, total }.
-export async function getAdditionalProducts( clientId ) {
+//
+// storeIds (optional): when a non-empty array is passed, the Eyetest / Planogram
+// / AI Manager quantities are restricted to those stores only — used by invoice
+// generation so a billing group is billed for its assigned stores, not the whole
+// brand. When omitted (e.g. the brand-wide Billing Breakdown endpoint) the counts
+// stay client-wide.
+//
+// Run AI / VMS are sourced by caller: invoice generation (storeIds passed) uses
+// the product Lambdas (called brand-wide, then intersected with the group's
+// stores locally); the brand-wide Billing Breakdown (no storeIds) uses the
+// billing_details snapshot instead.
+//
+// Remote Optum is store-scoped for invoices too: its quantity becomes the count
+// of remote_optom_steps_summary records for the group over the latest inserted
+// month in that index (see remoteOptumRecordCount). Factory is dropped from
+// invoices entirely. The brand-wide Billing Breakdown keeps taking Remote Optum /
+// Factory from the billing_details snapshot as-is.
+export async function getAdditionalProducts( clientId, storeIds ) {
   clientId = String( clientId ?? '' );
   if ( clientId !== ADDITIONAL_PRODUCTS_CLIENT_ID ) {
     return [];
   }
 
+  // Restrict the Mongo aggregations to the billing group's stores when provided.
+  // group.stores holds storeIds, matched via $in against each collection's
+  // storeId field (top-level for cameras/planograms, stores.storeId once
+  // unwound for daily-pricing).
+  const scopeStores = Array.isArray( storeIds ) && storeIds.length;
+  const storeMatch = scopeStores ? { storeId: { $in: storeIds } } : {};
+  const unwoundStoreMatch = scopeStores ? { 'stores.storeId': { $in: storeIds } } : {};
+
   // Eyetest: distinct stores in the cameras collection that have an eye-test
   // stream with a QR code.
   const eyetestRows = await cameraService.aggregate( [
@@ -2212,6 +2354,7 @@ export async function getAdditionalProducts( clientId ) {
       { clientId: clientId },
       { isEyeTestStream: true },
       { qrCode: { $exists: true } },
+      storeMatch,
     ] } },
     { $group: { _id: '$storeId' } },
     { $count: 'stores' },
@@ -2220,7 +2363,7 @@ export async function getAdditionalProducts( clientId ) {
 
   // Planogram: distinct storeName in the planograms collection.
   const planogramRows = await planogramService.aggregate( [
-    { $match: { clientId: clientId } },
+    { $match: { clientId: clientId, ...storeMatch } },
     { $group: { _id: null, storecount: { $addToSet: '$storeName' } } },
     { $project: { count: { $size: '$storecount' } } },
   ] );
@@ -2234,6 +2377,7 @@ export async function getAdditionalProducts( clientId ) {
     { $sort: { dateISO: -1 } },
     { $limit: 1 },
     { $unwind: '$stores' },
+    ...( scopeStores ? [ { $match: unwoundStoreMatch } ] : [] ),
     { $unwind: '$stores.products' },
     { $match: { 'stores.products.productName': 'tangoTraffic', 'stores.products.workingdays': { $gt: 1 } } },
     { $group: { _id: '$stores.storeId' } },
@@ -2254,10 +2398,45 @@ export async function getAdditionalProducts( clientId ) {
     build( 'AI Manager', aiManagerQty, ADDITIONAL_PRODUCT_PRICES.aiManager ),
   ];
 
+  // Run AI and VMS quantities come from two different sources depending on the
+  // caller:
+  //   - Invoice generation (storeIds passed): use the product Lambdas. The
+  //     Lambda's own store_ids filter is unreliable, so lambdaStoreCount calls it
+  //     brand-wide and intersects the returned store list with the group's stores
+  //     locally — giving a per-group scoped count. Unit price from billing_details.
+  //   - Brand-wide Billing Breakdown (no storeIds): use the billing_details
+  //     OpenSearch snapshot instead (handled by the loop below), same as Remote
+  //     Optum / Factory.
+  // lambdaSourced marks which productNames the loop below must skip so they are
+  // not counted twice — only populated in the invoice (scoped) case.
+  const lambdaSourced = new Set();
+  if ( scopeStores ) {
+    const [ runAiQty, vmsQty, runAiPrice, vmsPrice, optumQty, optumPrice ] = await Promise.all( [
+      lambdaStoreCount( clientId, RUN_AI_LAMBDA_URL, storeIds ),
+      lambdaStoreCount( clientId, VMS_LAMBDA_URL, storeIds ),
+      billingDetailsPrice( clientId, 'Run AI' ),
+      billingDetailsPrice( clientId, 'VMS' ),
+      remoteOptumRecordCount( clientId, storeIds ),
+      billingDetailsPrice( clientId, 'Remote Optum' ),
+    ] );
+    products.push( build( 'Run AI', runAiQty, runAiPrice ) );
+    products.push( build( 'VMS', vmsQty, vmsPrice ) );
+    products.push( build( 'Remote Optum', optumQty, optumPrice ) );
+    // Skipped in the billing_details loop below so they are not counted twice.
+    lambdaSourced.add( 'run ai' );
+    lambdaSourced.add( 'vms' );
+    lambdaSourced.add( 'remote optum' );
+  }
+
   // Extra products from the billing_details OpenSearch index — the LATEST daily
   // snapshot for this client. quantity/price are stored as strings, so coerce
-  // them. If OpenSearch is unreachable we just skip these rows rather than
-  // failing the whole list.
+  // them. In the invoice (scoped) case VMS / Run AI / Remote Optum are skipped
+  // here (already added store-scoped above) to avoid double-counting; in the
+  // brand-wide case they are taken from this snapshot like the other extra
+  // products. If OpenSearch is unreachable we just skip these rows rather than
+  // failing the whole list. Factory is excluded from invoices (scoped) but still
+  // shown in the brand-wide Billing Breakdown table.
+  const invoiceExcluded = scopeStores ? new Set( [ 'factory' ] ) : new Set();
   try {
     const osRes = await getOpenSearchData( BILLING_DETAILS_INDEX, {
       size: 1,
@@ -2267,6 +2446,10 @@ export async function getAdditionalProducts( clientId ) {
     const hits = osRes?.body?.hits?.hits || osRes?.hits?.hits || [];
     const osProducts = hits[0]?._source?.products || [];
     for ( const p of osProducts ) {
+      const nameKey = String( p.productName ).toLowerCase();
+      if ( lambdaSourced.has( nameKey ) || invoiceExcluded.has( nameKey ) ) {
+        continue;
+      }
       const quantity = Number( p.quantity ) || 0;
       const price = Number( p.price ) || 0;
       products.push( build( p.productName, quantity, price ) );
@@ -2281,8 +2464,13 @@ export async function getAdditionalProducts( clientId ) {
 export async function additionalProducts( req, res ) {
   try {
     const clientId = String( req.query?.clientId ?? req.body?.clientId ?? '' );
-    const products = await getAdditionalProducts( clientId );
-    return res.sendSuccess( { currency: 'inr', products } );
+    const [ products, billingDate ] = await Promise.all( [
+      getAdditionalProducts( clientId ),
+      billingDetailsDate( clientId ),
+    ] );
+    // billingDate (YYYY-MM-DD) is the billing_details snapshot behind the counts;
+    // the UI passes it back to the export endpoint so exports match the cards.
+    return res.sendSuccess( { currency: 'inr', products, billingDate } );
   } catch ( error ) {
     logger.error( { error: error, function: 'additionalProducts' } );
     return res.sendError( error, 500 );
@@ -2309,6 +2497,35 @@ async function lamdaServiceCall( url, data ) {
   }
 }
 
+// Date (YYYY-MM-DD) of the latest billing_details OpenSearch snapshot for a
+// client — the snapshot whose product counts back the Additional Products cards.
+// The UI passes this back to the export endpoint so the export reflects the same
+// day as the card. Returns '' if unavailable; date_string is normalised to
+// YYYY-MM-DD (it may be stored as DD-MM-YYYY).
+async function billingDetailsDate( clientId ) {
+  try {
+    const osRes = await getOpenSearchData( BILLING_DETAILS_INDEX, {
+      size: 1,
+      query: { term: { 'client_id': clientId } },
+      sort: [ { date_string: { order: 'desc' } } ],
+    } );
+    const hits = osRes?.body?.hits?.hits || osRes?.hits?.hits || [];
+    const raw = String( hits[0]?._source?.date_string || '' ).trim();
+    if ( !raw ) {
+      return '';
+    }
+    // Accept DD-MM-YYYY or YYYY-MM-DD; return YYYY-MM-DD.
+    const ddmmyyyy = raw.match( /^(\d{2})-(\d{2})-(\d{4})$/ );
+    if ( ddmmyyyy ) {
+      return `${ddmmyyyy[3]}-${ddmmyyyy[2]}-${ddmmyyyy[1]}`;
+    }
+    return raw;
+  } catch ( osErr ) {
+    logger.error( { error: osErr, function: 'billingDetailsDate', clientId } );
+    return '';
+  }
+}
+
 // Unit price for a product from the latest billing_details OpenSearch record.
 // productName match is case-insensitive. Returns 0 if not found / unavailable.
 async function billingDetailsPrice( clientId, productName ) {
@@ -2328,13 +2545,82 @@ async function billingDetailsPrice( clientId, productName ) {
   }
 }
 
+// Date (YYYY-MM-DD) of the most recent record in the remote_optom_steps_summary
+// index — the latest day audit data was inserted. Date is a keyword so it sorts
+// lexically. Returns '' if the index is empty / unreachable.
+async function remoteOptumLatestDate() {
+  try {
+    const osRes = await getOpenSearchData( 'remote_optom_steps_summary', {
+      size: 1,
+      _source: [ 'Date' ],
+      sort: [ { 'Date': { order: 'desc' } } ],
+    } );
+    const hits = osRes?.body?.hits?.hits || osRes?.hits?.hits || [];
+    return String( hits[0]?._source?.Date || '' ).trim();
+  } catch ( osErr ) {
+    logger.error( { error: osErr, function: 'remoteOptumLatestDate' } );
+    return '';
+  }
+}
+
+// Remote Optum billed quantity for a billing group = number of audit records in
+// the remote_optom_steps_summary index that belong to the group's stores, over
+// the range [to_date's month-start .. to_date], where to_date is the latest
+// record date in the index (e.g. to_date 2026-06-30 → from_date 2026-06-01). That
+// index keys by store NAME (no storeId), so group.stores (storeIds) are first
+// mapped to names via the stores collection, then matched with a terms filter on
+// storeName.keyword. Date is a keyword (YYYY-MM-DD per record), so the range is
+// lexical. size:0 + track_total_hits gives the exact count without paging past
+// the 10k window. Returns 0 on any failure or when the group has no matching
+// store names / the index is empty.
+async function remoteOptumRecordCount( clientId, storeIds ) {
+  try {
+    if ( !Array.isArray( storeIds ) || !storeIds.length ) {
+      return 0;
+    }
+    const toDate = await remoteOptumLatestDate();
+    if ( !toDate ) {
+      return 0;
+    }
+    const fromDate = dayjs( toDate ).startOf( 'month' ).format( 'YYYY-MM-DD' );
+    const stores = await storeService.find(
+        { clientId: clientId, storeId: { $in: storeIds } },
+        { storeName: 1 },
+    );
+    const storeNames = [ ...new Set(
+        stores.map( ( s ) => String( s.storeName || '' ).trim() ).filter( Boolean ),
+    ) ];
+    if ( !storeNames.length ) {
+      return 0;
+    }
+    const osRes = await getOpenSearchData( 'remote_optom_steps_summary', {
+      size: 0,
+      track_total_hits: true,
+      query: { bool: { filter: [
+        { range: { 'Date': { gte: fromDate, lte: toDate } } },
+        { terms: { 'storeName.keyword': storeNames } },
+      ] } },
+    } );
+    const total = osRes?.body?.hits?.total?.value ?? osRes?.hits?.total?.value ?? 0;
+    return Number( total ) || 0;
+  } catch ( osErr ) {
+    logger.error( { error: osErr, function: 'remoteOptumRecordCount', clientId } );
+    return 0;
+  }
+}
+
 // Build the Lambda-backed export rows (VMS / Run AI / etc.). Calls the product's
 // Lambda for store_names (storeIds), maps them to the stores collection for
 // name + country (Zone), with current-month days and the billing_details price.
-async function lambdaStoreExport( clientId, lambdaUrl, billingProductName ) {
-  const toDate = dayjs().format( 'DD-MM-YYYY' );
+// reqDate (YYYY-MM-DD, optional) is the billing_details snapshot date the UI
+// picked so the export matches the card count; it is sent to the Lambda as
+// to_date (DD-MM-YYYY). Defaults to today when absent.
+async function lambdaStoreExport( clientId, lambdaUrl, billingProductName, reqDate ) {
+  // reqDate is ISO YYYY-MM-DD, which dayjs parses natively; reformat to the
+  // Lambda's DD-MM-YYYY. Fall back to today when absent / unparseable.
+  const parsed = reqDate ? dayjs( reqDate ) : null;
+  const toDate = parsed && parsed.isValid() ? parsed.format( 'DD-MM-YYYY' ) : dayjs().format( 'DD-MM-YYYY' );
   const lambdaResult = await lamdaServiceCall( lambdaUrl, { to_date: toDate, client_id: clientId } );
-  console.log( '🚀 ~ lambdaStoreExport ~ lambdaResult:', lambdaResult );
   // These Lambdas return the storeIds under either `store_ids` (Run AI) or
   // `store_names` (VMS) with no status_code. Accept whichever is present; data
   // availability = a non-empty array.
@@ -2362,6 +2648,33 @@ async function lambdaStoreExport( clientId, lambdaUrl, billingProductName ) {
   } );
 }
 
+// Count the billable stores a product Lambda (VMS / Run AI) reports, optionally
+// scoped to a billing group's stores. The Lambda's own store_ids request filter
+// is unreliable — passing store_ids returns 0 even for IDs it itself reports as
+// billable — so we always call it BRAND-WIDE (client only) to get the true store
+// list, then intersect that list with the group's stores locally. Both sides use
+// the same `clientId-n` storeId format (e.g. `11-2911`), matching how the Mongo
+// aggregations scope by group.stores. Returns 0 on any failure (Lambda
+// unreachable / empty), so the caller just omits the line rather than failing the
+// whole invoice.
+async function lambdaStoreCount( clientId, lambdaUrl, storeIds ) {
+  const toDate = dayjs().format( 'DD-MM-YYYY' );
+  const lambdaResult = await lamdaServiceCall( lambdaUrl, { to_date: toDate, client_id: clientId } );
+  // The Lambdas return the storeIds under either `store_ids` (Run AI) or
+  // `store_names` (VMS); accept whichever is present.
+  const rawIds = ( lambdaResult && Array.isArray( lambdaResult.store_ids ) ) ? lambdaResult.store_ids :
+    ( ( lambdaResult && Array.isArray( lambdaResult.store_names ) ) ? lambdaResult.store_names : [] );
+  const ids = rawIds.map( ( s ) => String( s ) );
+  // Scope to the billing group's stores when provided; otherwise (brand-wide
+  // Billing Breakdown) count every store the Lambda reports.
+  const scope = Array.isArray( storeIds ) && storeIds.length ? storeIds.map( ( s ) => String( s ) ) : null;
+  if ( scope ) {
+    const allowed = new Set( scope );
+    return ids.filter( ( id ) => allowed.has( id ) ).length;
+  }
+  return ids.length;
+}
+
 // tangoTraffic working days per store, from the latest daily-pricing doc.
 // Map<storeId, workingdays>; stores with no tangoTraffic record are absent.
 async function tangoTrafficDaysByStore( clientId ) {
@@ -2531,8 +2844,9 @@ export async function additionalProductExport( req, res ) {
     if ( product === 'vms' ) {
       const exportData = await lambdaStoreExport(
           clientId,
-          'https://ppf3l3mxc2lorh5hkrsj6zwyim0bupxw.lambda-url.ap-south-1.on.aws/',
+          VMS_LAMBDA_URL,
           'VMS',
+          reqDate,
       );
       if ( !exportData.length ) {
         return res.sendError( 'No data', 204 );
@@ -2544,10 +2858,10 @@ export async function additionalProductExport( req, res ) {
     if ( product === 'runai' ) {
       const exportData = await lambdaStoreExport(
           clientId,
-          'https://mdm3mf7wuficgv3jjspkws2nu40azlsc.lambda-url.ap-south-1.on.aws/',
+          RUN_AI_LAMBDA_URL,
           'Run AI',
+          reqDate,
       );
-      console.log( '🚀 ~ additionalProductExport ~ exportData:', exportData );
       if ( !exportData.length ) {
         return res.sendError( 'No data', 204 );
       }
@@ -2556,56 +2870,103 @@ export async function additionalProductExport( req, res ) {
     }
 
     if ( product === 'remoteoptum' ) {
-      // Detailed optom-audit export from the remote_optom_steps_summary index
-      // for the given date (passed from the UI, defaults to today). Each record
-      // is one row; the nested `steps` object is flattened into TRUE/FALSE
-      // columns in a fixed (alphabetical) order.
+      // Detailed optom-audit export from the remote_optom_steps_summary index.
+      // to_date is the date from the payload (reqDate); from_date is the first
+      // day of that date's month — so the export covers month-start through the
+      // requested date. Each record is one row; the nested `steps` object is
+      // flattened into TRUE/FALSE columns in a fixed (alphabetical) order.
       const STEP_COLUMNS = [
         'Adjust-Phoropter', 'DuoChrome-Test', 'Explanation', 'Final-Prescription',
         'Handover', 'History-Taking', 'JCC', 'Near-Vision', 'Personal-Intro',
         'Subjective-Refraction', 'Trial-Frame', 'VA-Check',
       ];
-      let optomHits = [];
+      const fromDate = dayjs( reqDate ).startOf( 'month' ).format( 'YYYY-MM-DD' );
+      const HEADER_COLUMNS = [
+        'storeName', 'engagementId', 'queue_id', 'optm_name', 'optm_id',
+        'optm_Emailid', 'Date', 'StartTime', 'EndTime', 'Duration (min)',
+        ...STEP_COLUMNS,
+      ];
+      // Flatten one OpenSearch hit into a row array aligned with HEADER_COLUMNS.
+      const hitToRow = ( h ) => {
+        const s = h._source || {};
+        const steps = s.steps || {};
+        return [
+          s.storeName || '', s.engagementId || '', s.queue_id || '',
+          s.optm_name || '', s.optm_id || '', s.optm_Emailid || '',
+          s.Date || '', s.StartTime || '', s.EndTime || '',
+          s['Duration (min)'] != null ? s['Duration (min)'] : '',
+          ...STEP_COLUMNS.map( ( col ) => ( steps[col] === true ? 'TRUE' : 'FALSE' ) ),
+        ];
+      };
+
+      // NOTE: do NOT sort on StartTime — it's an analyzed text field, and sorting
+      // on it makes OpenSearch return ZERO hits. Date is a keyword (YYYY-MM-DD),
+      // so the month-to-date span is a lexical range; rows come back in index
+      // order. A whole month can be hundreds of thousands of records, so we scroll
+      // through pages AND stream each page straight into an ExcelJS streaming
+      // workbook — building the full .xlsx in memory (the old excel4node path)
+      // blew the heap / gateway timeout at this scale, causing 502s.
+      let firstRes;
       try {
-        const osRes = await getOpenSearchData( 'remote_optom_steps_summary', {
-          // A single day is well under the 10k window; pull up to the cap.
-          // NOTE: do NOT sort on StartTime — it's an analyzed text field, and
-          // sorting on it makes OpenSearch return ZERO hits. The day filter is
-          // enough; rows come back in index order.
+        firstRes = await searchOpenSearchData( 'remote_optom_steps_summary', {
           size: 10000,
-          query: { term: { 'Date': reqDate } },
+          query: { range: { 'Date': { gte: fromDate, lte: reqDate } } },
         } );
-        optomHits = osRes?.body?.hits?.hits || osRes?.hits?.hits || [];
       } catch ( osErr ) {
         logger.error( { error: osErr, function: 'additionalProductExport.remoteOptum', clientId } );
         return res.sendError( 'Failed to fetch Remote Optum data', 502 );
       }
-
-      const exportData = optomHits.map( ( h ) => {
-        const s = h._source || {};
-        const steps = s.steps || {};
-        const row = {
-          'storeName': s.storeName || '',
-          'engagementId': s.engagementId || '',
-          'queue_id': s.queue_id || '',
-          'optm_name': s.optm_name || '',
-          'optm_id': s.optm_id || '',
-          'optm_Emailid': s.optm_Emailid || '',
-          'Date': s.Date || '',
-          'StartTime': s.StartTime || '',
-          'EndTime': s.EndTime || '',
-          'Duration (min)': s['Duration (min)'] != null ? s['Duration (min)'] : '',
-        };
-        for ( const col of STEP_COLUMNS ) {
-          row[col] = steps[col] === true ? 'TRUE' : 'FALSE';
+      let body = firstRes?.body || firstRes;
+      let hits = body?.hits?.hits || [];
+      let scrollId = body?._scroll_id;
+      // Nothing to export — respond BEFORE any stream headers are sent.
+      if ( !hits.length ) {
+        if ( scrollId ) {
+          try {
+            await clearScroll( scrollId );
+          } catch ( clearErr ) {
+            logger.error( { error: clearErr, function: 'additionalProductExport.remoteOptum.clearScroll' } );
+          }
         }
-        return row;
-      } );
-
-      if ( !exportData.length ) {
         return res.sendError( 'No data', 204 );
       }
-      await download( exportData, res );
+
+      // From here the response is a streamed workbook; headers are committed, so
+      // a mid-stream failure can only abort the connection, not send a new status.
+      res.setHeader( 'Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' );
+      res.setHeader( 'Content-Disposition', `attachment; filename="Remote Optum-${clientId}.xlsx"` );
+      const workbook = new ExcelJS.stream.xlsx.WorkbookWriter( { stream: res, useStyles: false } );
+      const ws = workbook.addWorksheet( 'Worksheet Name' );
+      ws.addRow( HEADER_COLUMNS ).commit();
+      try {
+        while ( hits.length ) {
+          for ( const h of hits ) {
+            ws.addRow( hitToRow( h ) ).commit();
+          }
+          if ( !scrollId ) {
+            break;
+          }
+          const osRes = await scrollResponse( scrollId );
+          body = osRes?.body || osRes;
+          hits = body?.hits?.hits || [];
+          scrollId = body?._scroll_id || scrollId;
+        }
+        ws.commit();
+        await workbook.commit();
+      } catch ( streamErr ) {
+        // Headers are already sent — log and tear down the connection so the
+        // client sees a failed/aborted download rather than a truncated file.
+        logger.error( { error: streamErr, function: 'additionalProductExport.remoteOptum.stream', clientId } );
+        res.destroy( streamErr );
+      } finally {
+        if ( scrollId ) {
+          try {
+            await clearScroll( scrollId );
+          } catch ( clearErr ) {
+            logger.error( { error: clearErr, function: 'additionalProductExport.remoteOptum.clearScroll' } );
+          }
+        }
+      }
       return;
     }