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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.5",
+    "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.9",
+        "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/bankTransaction.controller.js

@@ -0,0 +1,617 @@
+import * as bankTransactionService from '../services/bankTransaction.service.js';
+import * as invoiceService from '../services/invoice.service.js';
+import * as clientService from '../services/clientPayment.services.js';
+import dayjs from 'dayjs';
+import { logger } from 'tango-app-api-middleware';
+
+// ---------------------------------------------------------------------------
+// Bank-statement upload + reconciliation list (billing "Transactions" tab).
+//
+// The frontend parses the statement file (CSV/XLSX) with SheetJS and POSTs
+// the sheet as a JSON array-of-arrays — no file bytes reach the API. All
+// validation, normalization and classification happen here.
+//
+// Classification (per business rules):
+//   reconciled   — payer matches an invoice companyName AND the transaction
+//                  amount equals (amount excl. GST − TDS) + GST for TDS of
+//                  0%, 2% or 10%. The matched invoice is closed as paid.
+//   needs_review — payer matches an unpaid invoice's companyName but no
+//                  amount match at any TDS rate.
+//   unmatched    — a payer name was extracted but matches no invoice
+//                  companyName.
+//   excluded     — everything else (no payer in the narration: inward
+//                  remittances, interest credits, penny-drop validations).
+// ---------------------------------------------------------------------------
+
+const TDS_RATES = [ 0, 0.02, 0.10 ];
+// Banks round TDS differently than we do; a rupee of slack avoids false
+// "needs review" on paise-level rounding while never crossing TDS slabs.
+const AMOUNT_TOLERANCE = 1.0;
+const MAX_ROWS = 10000;
+
+// Counterparty name from a statement narration. Bank narrations pack the
+// payer between dashes in several formats (NEFT CR-IFSC-NAME-..., IMPS,
+// FT-, TPT, plain "ref-NAME"), so rather than one regex per bank we take
+// the longest dash-separated segment that looks like a company name and
+// is not our own entity (TANGO...) or a transaction-type keyword.
+export function extractPayer( narration ) {
+  const n = String( narration || '' ).trim();
+  if ( !n || /^INW\b/i.test( n ) || /^INT\./i.test( n ) || /BAV VALIDATION/i.test( n ) ) {
+    return '';
+  }
+  const segments = n.split( '-' ).map( ( s ) => s.trim() );
+  const candidates = segments.filter( ( s ) =>
+    /^[A-Za-z][A-Za-z .&()',]*$/.test( s ) &&
+    s.length >= 4 &&
+    !/TANGO/i.test( s ) &&
+    !/^(NEFT CR|RTGS CR|IMPS|TPT|OPERATIONS|EXPENSE ACCOUNT|CMS|FT)$/i.test( s ),
+  );
+  if ( !candidates.length ) {
+    return '';
+  }
+  return candidates.reduce( ( a, b ) => ( b.length > a.length ? b : a ), '' );
+}
+
+// Company-name normalization for matching bank narrations against invoice
+// companyName. Banks truncate mid-word ("...PRIVATE LIMITE", "...PRIVATE
+// LIMIT") and abbreviate (PVT/LTD), so fold every truncation of the legal
+// suffixes and strip punctuation (which also folds "NAME - Karnataka" style
+// state suffixes into plain trailing tokens).
+export function normalizeCompany( name ) {
+  return String( name || '' )
+      .toUpperCase()
+      .replace( /[^A-Z0-9 ]/g, ' ' )
+      .replace( /\bPRIVATE?\b/g, 'PVT' ) // PRIVATE, PRIVAT
+      .replace( /\bLIMITE?D?\b/g, 'LTD' ) // LIMITED, LIMITE, LIMIT
+      .replace( /\bCOMPANY\b/g, 'CO' )
+      .replace( /\s+/g, ' ' )
+      .trim();
+}
+
+// Token-level prefix match: every token of the shorter name must equal the
+// corresponding token of the longer one, except the LAST token which may be
+// a truncated prefix (banks cut narrations mid-word). The longer name may
+// carry extra trailing tokens — invoice names like "APOLLO PHARMAPRODUCTS
+// PVT LTD KARNATAKA" still match the bank's "APOLLO PHARMAPRODUCTS PVT LTD".
+function tokenPrefixMatch( shortTokens, longTokens ) {
+  if ( !shortTokens.length || shortTokens.length > longTokens.length ) {
+    return false;
+  }
+  for ( let i = 0; i < shortTokens.length; i++ ) {
+    if ( i === shortTokens.length - 1 ) {
+      if ( !longTokens[i].startsWith( shortTokens[i] ) ) {
+        return false;
+      }
+    } else if ( shortTokens[i] !== longTokens[i] ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// Truncation-tolerant company match (min 8 matched chars so "PVT LTD" alone
+// can never link two unrelated companies). Tried in both directions because
+// either side can be the longer one.
+export function companyMatches( a, b ) {
+  if ( !a || !b ) {
+    return false;
+  }
+  if ( a === b ) {
+    return true;
+  }
+  const shorter = a.length < b.length ? a : b;
+  const longer = a.length < b.length ? b : a;
+  if ( shorter.length < 8 ) {
+    return false;
+  }
+  if ( tokenPrefixMatch( shorter.split( ' ' ), longer.split( ' ' ) ) ) {
+    return true;
+  }
+  // Spacing differences — banks write "THE WOODEN STREET FURNITURES" where
+  // the registered name is "THE WOODENSTREET FURNITURES". Compare with all
+  // spaces removed, prefix-tolerant for the usual narration truncation.
+  const aSquashed = a.replace( / /g, '' );
+  const bSquashed = b.replace( / /g, '' );
+  const shortSquashed = aSquashed.length < bSquashed.length ? aSquashed : bSquashed;
+  const longSquashed = aSquashed.length < bSquashed.length ? bSquashed : aSquashed;
+  return shortSquashed.length >= 8 && longSquashed.startsWith( shortSquashed );
+}
+
+// DD/MM/YY or DD/MM/YYYY -> Date (UTC midnight). Returns null when the cell
+// is not a date — that's how header/separator/footer rows get skipped.
+function parseStatementDate( value ) {
+  const s = String( value || '' ).trim();
+  const m = s.match( /^(\d{1,2})\/(\d{1,2})\/(\d{2,4})$/ );
+  if ( !m ) {
+    return null;
+  }
+  const year = m[3].length === 2 ? 2000 + Number( m[3] ) : Number( m[3] );
+  const d = new Date( Date.UTC( year, Number( m[2] ) - 1, Number( m[1] ) ) );
+  return isNaN( d.getTime() ) ? null : d;
+}
+
+function parseAmount( value ) {
+  const n = parseFloat( String( value ?? '' ).replace( /,/g, '' ) );
+  return Number.isFinite( n ) ? n : 0;
+}
+
+function round2( n ) {
+  return Math.round( n * 100 ) / 100;
+}
+
+// Classify one parsed transaction against the unpaid-invoice index.
+// `consumed` tracks invoices already closed in this batch so two statement
+// lines can never settle the same invoice.
+export function classifyTransaction( txn, unpaidInvoices, consumed ) {
+  if ( !txn.payer ) {
+    // Inward dollar remittances carry no payer name (INW ... USD4140.0@92.5),
+    // but when the USD value matches a dollar invoice — or the INR credit
+    // matches any invoice — it is very likely a customer payment: surface it
+    // for review instead of excluding it.
+    const usdMatch = String( txn.narration || '' ).match( /USD\s*([\d,]+(?:\.\d+)?)/i );
+    if ( usdMatch ) {
+      const usd = parseFloat( usdMatch[1].replace( /,/g, '' ) );
+      const hit = unpaidInvoices.find( ( inv ) => {
+        if ( consumed.has( inv.invoice ) ) {
+          return false;
+        }
+        const outstanding = round2( ( inv.totalAmount || 0 ) - ( inv.paidAmount || 0 ) );
+        if ( inv.currency === 'dollar' && Math.abs( usd - outstanding ) <= AMOUNT_TOLERANCE ) {
+          return true;
+        }
+        return Math.abs( txn.amount - outstanding ) <= AMOUNT_TOLERANCE;
+      } );
+      if ( hit ) {
+        return {
+          status: 'needs_review',
+          identifiedClientId: String( hit.clientId ?? '' ),
+          identifiedClientName: hit.brandName || hit.companyName,
+          resultNote: `Inward remittance USD ${usd} matches ${hit.invoice} — confirm and resolve manually`,
+        };
+      }
+    }
+    return { status: 'excluded', resultNote: 'No payer name in narration — not a customer payment' };
+  }
+  const payerNorm = normalizeCompany( txn.payer );
+  const matches = unpaidInvoices.filter( ( inv ) => companyMatches( payerNorm, inv.companyNorm ) );
+  if ( !matches.length ) {
+    return { status: 'unmatched', resultNote: `Payer "${txn.payer}" does not match any invoice company` };
+  }
+
+  for ( const inv of matches ) {
+    if ( consumed.has( inv.invoice ) ) {
+      continue;
+    }
+    const gst = round2( ( inv.totalAmount || 0 ) - ( inv.amount || 0 ) );
+    for ( const tds of TDS_RATES ) {
+      const expected = round2( ( inv.amount || 0 ) * ( 1 - tds ) + gst );
+      if ( Math.abs( txn.amount - expected ) <= AMOUNT_TOLERANCE ) {
+        return {
+          status: 'reconciled',
+          invoice: inv.invoice,
+          invoiceId: String( inv._id ?? '' ),
+          identifiedClientId: String( inv.clientId ?? '' ),
+          identifiedClientName: inv.brandName || inv.companyName,
+          tdsRate: tds,
+          matchedInvoice: inv,
+          resultNote: `Fully matched to ${inv.invoice} · TDS ${tds * 100}%`,
+        };
+      }
+    }
+  }
+
+  const first = matches[0];
+  return {
+    status: 'needs_review',
+    identifiedClientId: String( first.clientId ?? '' ),
+    identifiedClientName: first.brandName || first.companyName,
+    resultNote: `Company matched (${matches.length} unpaid invoice${matches.length === 1 ? '' : 's'}) · amount does not equal any invoice after TDS 0% / 2% / 10%`,
+  };
+}
+
+export async function uploadBankStatement( req, res ) {
+  try {
+    // The sheet arrives as JSON rows (array of arrays) parsed client-side.
+    const rows = req.body?.rows;
+    const fileName = req.body?.fileName || 'statement';
+    if ( !Array.isArray( rows ) || rows.length === 0 ) {
+      return res.sendError( 'rows must be a non-empty array (parsed statement sheet)', 400 );
+    }
+    if ( rows.length > MAX_ROWS ) {
+      return res.sendError( `Too many rows (max ${MAX_ROWS})`, 413 );
+    }
+    if ( !rows.every( ( r ) => Array.isArray( r ) ) ) {
+      return res.sendError( 'Each row must be an array of cells', 400 );
+    }
+
+    // Locate the header row and map column indexes by header text, so column
+    // order changes between bank exports don't break the import.
+    let headerIdx = -1;
+    const col = { date: -1, narration: -1, ref: -1, valueDate: -1, withdrawal: -1, deposit: -1 };
+    for ( let i = 0; i < Math.min( rows.length, 30 ); i++ ) {
+      const cells = rows[i].map( ( c ) => String( c ).toLowerCase().trim() );
+      const dateIdx = cells.findIndex( ( c ) => c === 'date' );
+      const narrIdx = cells.findIndex( ( c ) => c.startsWith( 'narration' ) );
+      if ( dateIdx !== -1 && narrIdx !== -1 ) {
+        headerIdx = i;
+        col.date = dateIdx;
+        col.narration = narrIdx;
+        col.ref = cells.findIndex( ( c ) => c.includes( 'ref' ) || c.includes( 'chq' ) );
+        col.valueDate = cells.findIndex( ( c ) => c.startsWith( 'value' ) );
+        col.withdrawal = cells.findIndex( ( c ) => c.includes( 'withdrawal' ) );
+        col.deposit = cells.findIndex( ( c ) => c.includes( 'deposit' ) );
+        break;
+      }
+    }
+    if ( headerIdx === -1 ) {
+      return res.sendError( 'Could not find the statement header row (expected "Date" and "Narration" columns)', 400 );
+    }
+
+    const parsed = [];
+    for ( let i = headerIdx + 1; i < rows.length; i++ ) {
+      const r = rows[i];
+      const date = parseStatementDate( r[col.date] );
+      const narration = String( r[col.narration] || '' ).trim();
+      // Skips the asterisk separator line, blank lines and the footer block
+      // (GSTN notes, "--- End Of Statement ---") in one go.
+      if ( !date || !narration || /^\*+$/.test( narration ) ) {
+        continue;
+      }
+      const withdrawalAmt = col.withdrawal !== -1 ? parseAmount( r[col.withdrawal] ) : 0;
+      const depositAmt = col.deposit !== -1 ? parseAmount( r[col.deposit] ) : 0;
+      parsed.push( {
+        date,
+        valueDate: col.valueDate !== -1 ? ( parseStatementDate( r[col.valueDate] ) || date ) : date,
+        narration,
+        refNo: col.ref !== -1 ? String( r[col.ref] || '' ).trim() : '',
+        withdrawalAmt,
+        depositAmt,
+        amount: round2( depositAmt - withdrawalAmt ),
+        payer: extractPayer( narration ),
+        source: 'bank',
+        fileName,
+        uploadedBy: req.user?.email || req.user?.userName || '',
+      } );
+    }
+
+    if ( !parsed.length ) {
+      return res.sendError( 'No transaction rows found in the file', 400 );
+    }
+
+    // Re-uploading the same statement must not duplicate rows (or re-close
+    // invoices): a line is a duplicate when refNo AND amount already exist.
+    const refNos = [ ...new Set( parsed.map( ( p ) => p.refNo ).filter( Boolean ) ) ];
+    const existing = await bankTransactionService.find(
+        { refNo: { $in: refNos } },
+        { refNo: 1, amount: 1, _id: 0 },
+    );
+    const existingKeys = new Set( existing.map( ( e ) => `${e.refNo}|${e.amount}` ) );
+    const fresh = parsed.filter( ( p ) => !p.refNo || !existingKeys.has( `${p.refNo}|${p.amount}` ) );
+
+    // ---- Classification ----
+    // One query for the whole batch: every unpaid invoice with a registered
+    // company name, matched in memory against each transaction's payer.
+    const unpaidRaw = await invoiceService.find(
+        { paymentStatus: { $ne: 'paid' }, companyName: { $exists: true, $nin: [ '', null ] } },
+        { invoice: 1, companyName: 1, amount: 1, totalAmount: 1, paidAmount: 1, clientId: 1, currency: 1 },
+    );
+    // The UI shows the brand name (clientName), not the registered entity —
+    // resolve each invoice's clientId to its brand once for the whole batch.
+    const clientIds = [ ...new Set( unpaidRaw.map( ( i ) => i.clientId ).filter( ( x ) => x != null ) ) ];
+    const clients = await clientService.find( { clientId: { $in: clientIds } }, { clientId: 1, clientName: 1 } );
+    const brandByClient = new Map( clients.map( ( c ) => [ String( c.clientId ), c.clientName ] ) );
+    const unpaidInvoices = unpaidRaw.map( ( inv ) => ( {
+      ...( inv.toObject ? inv.toObject() : inv ),
+      companyNorm: normalizeCompany( inv.companyName ),
+      brandName: brandByClient.get( String( inv.clientId ) ) || inv.companyName,
+    } ) );
+
+    const consumed = new Set();
+    const summary = { reconciled: 0, needs_review: 0, unmatched: 0, excluded: 0 };
+    const closedInvoices = [];
+
+    for ( const txn of fresh ) {
+      const verdict = classifyTransaction( txn, unpaidInvoices, consumed );
+      txn.status = verdict.status;
+      txn.resultNote = verdict.resultNote;
+      txn.invoice = verdict.invoice || '';
+      txn.invoiceId = verdict.invoiceId || '';
+      txn.identifiedClientId = verdict.identifiedClientId || '';
+      txn.identifiedClientName = verdict.identifiedClientName || '';
+      summary[verdict.status]++;
+
+      if ( verdict.status === 'reconciled' ) {
+        consumed.add( verdict.invoice );
+        // Close the invoice — same field shape as recordPayment so the rest
+        // of the billing UI (paid badges, pending notes) just works. TDS is
+        // withheld by the customer, so paidAmount is what actually landed.
+        await invoiceService.invoiceUpdateOne(
+            { invoice: verdict.invoice },
+            {
+              $set: {
+                paymentStatus: 'paid',
+                paidDate: new Date(),
+                paidAmount: round2( ( Number( verdict.matchedInvoice.paidAmount ) || 0 ) + txn.amount ),
+              },
+              $push: {
+                paymentHistory: {
+                  amount: txn.amount,
+                  date: txn.valueDate,
+                  method: 'bank-statement',
+                  reference: txn.refNo || undefined,
+                  notes: `Auto-reconciled from "${fileName}" · TDS ${verdict.tdsRate * 100}%`,
+                  recordedBy: req.user?.email || req.user?.userName || 'bank-reconciliation',
+                  recordedAt: new Date(),
+                },
+              },
+            },
+        );
+        closedInvoices.push( verdict.invoice );
+      }
+    }
+
+    if ( fresh.length ) {
+      await bankTransactionService.insertMany( fresh );
+    }
+
+    logger.info?.( { function: 'uploadBankStatement', fileName, totalRows: parsed.length, inserted: fresh.length, summary, closedInvoices } );
+    return res.sendSuccess( {
+      totalRows: parsed.length,
+      inserted: fresh.length,
+      duplicates: parsed.length - fresh.length,
+      summary,
+      closedInvoices,
+    } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'uploadBankStatement' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+// Dropdown data for the "Resolve & reconcile" popup: unpaid invoices grouped
+// by client, with the brand name the UI shows. One aggregation does the
+// filter, grouping and client join inside MongoDB — the old two-query +
+// in-JS grouping hydrated every unpaid invoice document and was slow on
+// large invoice collections. Per-client invoice lists are capped: nobody
+// reconciles against the 101st-oldest open invoice from a dropdown.
+const RESOLVE_INVOICES_PER_CLIENT = 100;
+export async function resolveOptions( req, res ) {
+  try {
+    const data = await invoiceService.aggregate( [
+      { $match: { paymentStatus: { $ne: 'paid' } } },
+      { $project: {
+        invoice: 1,
+        clientId: 1,
+        dueDate: 1,
+        companyName: 1,
+        outstanding: { $max: [ 0, { $subtract: [
+          { $ifNull: [ '$totalAmount', 0 ] },
+          { $ifNull: [ '$paidAmount', 0 ] },
+        ] } ] },
+      } },
+      // Newest due date first so the slice keeps the invoices people
+      // actually reconcile against.
+      { $sort: { dueDate: -1 } },
+      { $group: {
+        _id: '$clientId',
+        anyCompany: { $first: '$companyName' },
+        invoices: { $push: {
+          _id: '$_id',
+          invoice: '$invoice',
+          outstanding: '$outstanding',
+          dueDate: '$dueDate',
+        } },
+      } },
+      { $project: {
+        _id: 0,
+        clientId: { $toString: '$_id' },
+        anyCompany: 1,
+        invoices: { $slice: [ '$invoices', RESOLVE_INVOICES_PER_CLIENT ] },
+      } },
+      { $lookup: {
+        from: 'clients',
+        let: { cidRaw: '$clientId' },
+        pipeline: [
+          { $match: { $expr: { $eq: [ { $toString: '$clientId' }, '$$cidRaw' ] } } },
+          { $project: { clientName: 1, _id: 0 } },
+        ],
+        as: 'client',
+      } },
+      { $addFields: { brandName: { $ifNull: [ { $arrayElemAt: [ '$client.clientName', 0 ] }, '$anyCompany' ] } } },
+      { $project: { client: 0, anyCompany: 0 } },
+      { $sort: { brandName: 1 } },
+    ] );
+    return res.sendSuccess( data );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'resolveOptions' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+// Manual resolution from the popup. Three actions, mirroring the prototype:
+//   reconcile — apply the payment to the chosen invoice (exact -> paid,
+//               short -> partial, excess -> settled + follow-up note).
+//   contact   — keep in needs_review, flag "reaching out to customer".
+//   exclude   — mark as not to be considered.
+export async function resolveBankTransaction( req, res ) {
+  try {
+    const { txnId, action } = req.body || {};
+    if ( !txnId || ![ 'reconcile', 'contact', 'exclude' ].includes( action ) ) {
+      return res.sendError( 'txnId and a valid action (reconcile | contact | exclude) are required', 400 );
+    }
+    const txns = await bankTransactionService.find( { _id: txnId } );
+    const txn = txns[0];
+    if ( !txn ) {
+      return res.sendError( 'Transaction not found', 404 );
+    }
+
+    if ( action === 'exclude' ) {
+      await bankTransactionService.updateOne( { _id: txnId }, { $set: {
+        status: 'excluded',
+        contacted: false,
+        resultNote: 'Marked as not to be considered',
+      } } );
+      return res.sendSuccess( { status: 'excluded', note: 'Marked as not to be considered' } );
+    }
+
+    if ( action === 'contact' ) {
+      const clientName = req.body?.clientName || txn.identifiedClientName || 'customer';
+      await bankTransactionService.updateOne( { _id: txnId }, { $set: {
+        status: 'needs_review',
+        contacted: true,
+        identifiedClientId: req.body?.clientId || txn.identifiedClientId || '',
+        identifiedClientName: clientName,
+        resultNote: `Reaching out to ${clientName} to confirm this payment — in progress`,
+      } } );
+      return res.sendSuccess( { status: 'needs_review', contacted: true } );
+    }
+
+    // ---- reconcile ----
+    const invoiceId = req.body?.invoiceId;
+    if ( !invoiceId ) {
+      return res.sendError( 'invoiceId is required to reconcile', 400 );
+    }
+    const invoice = await invoiceService.findOne( { _id: invoiceId } );
+    if ( !invoice ) {
+      return res.sendError( 'Invoice not found', 404 );
+    }
+
+    const prevPaid = Number( invoice.paidAmount ) || 0;
+    const totalAmount = Number( invoice.totalAmount ) || 0;
+    const outstanding = round2( totalAmount - prevPaid );
+    const diff = round2( txn.amount - outstanding );
+
+    let note;
+    let newStatus;
+    if ( Math.abs( diff ) <= AMOUNT_TOLERANCE ) {
+      newStatus = 'paid';
+      note = `Manually reconciled to ${invoice.invoice} — invoice marked Paid`;
+    } else if ( diff < 0 ) {
+      newStatus = 'partial';
+      note = `Partial — ${round2( -diff )} balance remains on ${invoice.invoice}`;
+    } else {
+      newStatus = 'paid';
+      note = `Overpayment — ${invoice.invoice} settled, ${round2( diff )} excess to follow up`;
+    }
+    const newPaid = round2( prevPaid + txn.amount );
+
+    await invoiceService.invoiceUpdateOne(
+        { _id: invoice._id },
+        {
+          $set: {
+            paymentStatus: newStatus,
+            paidAmount: newPaid,
+            ...( newStatus === 'paid' ? { paidDate: new Date() } : {} ),
+          },
+          $push: {
+            paymentHistory: {
+              amount: txn.amount,
+              date: txn.valueDate || new Date(),
+              method: 'bank-statement',
+              reference: txn.refNo || undefined,
+              notes: `Manually reconciled from "${txn.fileName || 'statement'}"`,
+              recordedBy: req.user?.email || req.user?.userName || 'bank-reconciliation',
+              recordedAt: new Date(),
+            },
+          },
+        },
+    );
+
+    // Brand name for the table's Brand Name column.
+    const client = await clientService.findOne( { clientId: invoice.clientId }, { clientName: 1 } );
+    await bankTransactionService.updateOne( { _id: txnId }, { $set: {
+      status: 'reconciled',
+      contacted: false,
+      invoice: invoice.invoice,
+      invoiceId: String( invoice._id ),
+      identifiedClientId: String( invoice.clientId ?? '' ),
+      identifiedClientName: client?.clientName || invoice.companyName || '',
+      resultNote: note,
+    } } );
+
+    return res.sendSuccess( { status: 'reconciled', note, invoice: invoice.invoice } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'resolveBankTransaction' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+export async function bankTransactionList( req, res ) {
+  try {
+    // Scope filters (date range + source) apply to the cards AND the rows;
+    // the status tab and search narrow only the rows, so the bucket counts
+    // stay stable while the user moves between tabs.
+    const scope = {};
+    if ( req.body?.from || req.body?.to ) {
+      scope.valueDate = {};
+      if ( req.body.from ) {
+        scope.valueDate.$gte = new Date( dayjs( req.body.from ).startOf( 'day' ).toISOString() );
+      }
+      if ( req.body.to ) {
+        scope.valueDate.$lte = new Date( dayjs( req.body.to ).endOf( 'day' ).toISOString() );
+      }
+    }
+    if ( req.body?.source && req.body.source !== 'all' ) {
+      scope.source = req.body.source;
+    }
+
+    const cardsAggregate = await bankTransactionService.aggregate( [
+      { $match: scope },
+      { $group: {
+        _id: '$status',
+        count: { $sum: 1 },
+        amount: { $sum: '$amount' },
+      } },
+    ] );
+    const cards = {
+      reconciled: { count: 0, amount: 0 },
+      needs_review: { count: 0, amount: 0 },
+      unmatched: { count: 0, amount: 0 },
+      excluded: { count: 0, amount: 0 },
+      total: 0,
+    };
+    cardsAggregate.forEach( ( c ) => {
+      if ( cards[c._id] ) {
+        cards[c._id] = { count: c.count, amount: Math.round( c.amount * 100 ) / 100 };
+      }
+      cards.total += c.count;
+    } );
+
+    const match = { ...scope };
+    if ( req.body?.status && req.body.status !== 'all' ) {
+      match.status = req.body.status;
+    }
+    if ( req.body?.searchValue ) {
+      match.$or = [
+        { narration: { $regex: req.body.searchValue, $options: 'i' } },
+        { refNo: { $regex: req.body.searchValue, $options: 'i' } },
+        { payer: { $regex: req.body.searchValue, $options: 'i' } },
+        { identifiedClientName: { $regex: req.body.searchValue, $options: 'i' } },
+        { invoice: { $regex: req.body.searchValue, $options: 'i' } },
+      ];
+    }
+
+    const sortCol = req.body?.sortColumName || 'valueDate';
+    const sortBy = req.body?.sortBy === 1 ? 1 : -1;
+    const query = [
+      { $match: match },
+      { $sort: { [sortCol]: sortBy, _id: 1 } },
+    ];
+
+    const countResult = await bankTransactionService.aggregate( [ ...query, { $count: 'n' } ] );
+    const count = countResult[0]?.n || 0;
+
+    if ( req.body?.limit && req.body?.offset ) {
+      query.push(
+          { $skip: ( req.body.offset - 1 ) * req.body.limit },
+          { $limit: Number( req.body.limit ) },
+      );
+    }
+    const data = await bankTransactionService.aggregate( query );
+
+    return res.sendSuccess( { count, data, cards } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'bankTransactionList' } );
+    return res.sendError( error, 500 );
+  }
+}