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

package/src/controllers/estimate.controller.js

@@ -1,12 +1,77 @@
 import * as estimateService from '../services/estimate.service.js';
 import * as clientService from '../services/clientPayment.services.js';
+import * as billingService from '../services/billing.service.js';
 import dayjs from 'dayjs';
-import { logger, download } from 'tango-app-api-middleware';
+import { logger, download, sendEmailWithSES } from 'tango-app-api-middleware';
 import Handlebars from '../utils/validations/helper/handlebar.helper.js';
 import fs from 'fs';
 import path from 'path';
 import htmlpdf from 'html-pdf-node';
 import { symbolFor } from '../utils/currency.js';
+import { getInvoiceCcEmails } from './invoice.controller.js';
+
+// Build the estimate PDF buffer + the template data + a safe filename. Shared
+// by the download and send flows so both render the identical document.
+async function buildEstimatePdf( estimate ) {
+  const e = estimate._doc || estimate;
+  const currencyType = symbolFor( e.currency );
+  const fmt = ( n ) => Number( n || 0 ).toLocaleString( 'en-IN', { minimumFractionDigits: 2, maximumFractionDigits: 2 } );
+
+  const products = ( e.products || [] ).map( ( p, i ) => {
+    let name = String( p.productName || '' ).replace( /([a-z])([A-Z])/g, '$1 $2' );
+    name = name.charAt( 0 ).toUpperCase() + name.slice( 1 );
+    return {
+      index: i + 1,
+      productName: name,
+      description: p.description || '',
+      hsn: p.hsn || p.hsnCode || '998314',
+      storeCount: p.storeCount || e.stores || '',
+      price: fmt( p.price ),
+      amount: fmt( p.amount ),
+    };
+  } );
+  const tax = ( e.tax || [] ).map( ( t ) => ( {
+    type: t.type || t.taxName || t.name || 'GST',
+    value: t.value ?? t.taxPercentage ?? t.percentage ?? '',
+    taxAmount: fmt( t.taxAmount ),
+  } ) );
+
+  const statusLabelMap = { pending: 'Pending', sent: 'Sent', accepted: 'Accepted', declined: 'Declined', expired: 'Expired' };
+  const data = {
+    estimate: e.estimate,
+    status: e.status,
+    statusLabel: statusLabelMap[e.status] || e.status,
+    companyName: e.companyName || '',
+    companyAddress: e.companyAddress || '',
+    GSTNumber: e.GSTNumber || '',
+    PlaceOfSupply: e.PlaceOfSupply || '',
+    groupName: e.groupName || '',
+    period: e.period || '',
+    createdDate: e.createdDate ? dayjs( e.createdDate ).format( 'DD/MM/YYYY' ) : '',
+    validTill: e.validTill ? dayjs( e.validTill ).format( 'DD/MM/YYYY' ) : '',
+    currencyType,
+    amount: fmt( e.amount ),
+    totalAmount: fmt( e.totalAmount ),
+    products,
+    tax,
+    notes: e.notes || '',
+    logo: `${JSON.parse( process.env.URL ).apiDomain}/logo.png`,
+  };
+
+  const templateHtml = fs.readFileSync( path.resolve( path.dirname( '' ) ) + '/src/hbs/estimatePdf.hbs', 'utf8' );
+  const html = Handlebars.compile( templateHtml )( data );
+  const options = {
+    executablePath: '/usr/bin/chromium',
+    args: [ '--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--no-zygote', '--single-process' ],
+    format: 'A4',
+    margin: { top: '0.5in', right: '0.5in', bottom: '0.5in', left: '0.5in' },
+    printBackground: true,
+    preferCSSPageSize: true,
+  };
+  const pdfBuffer = await htmlpdf.generatePdf( { content: html }, options );
+  const filename = ( e.estimate + '-' + ( e.companyName || 'estimate' ) + '.pdf' ).split( '/' ).join( '_' ).split( '"' ).join( '' ).trim();
+  return { pdfBuffer, filename, data };
+}
 
 // ---------------------------------------------------------------------------
 // Estimates (quotations). A lightweight pre-invoice document with its own
@@ -43,7 +108,7 @@ async function nextEstimateNumber() {
 // flips to 'expired' so the list reflects reality without a cron.
 async function expireOverdue( clientId ) {
   await estimateService.updateOne(
-      { clientId, status: { $in: [ 'draft', 'sent' ] }, validTill: { $lt: new Date() } },
+      { clientId, status: { $in: [ 'pending', 'sent' ] }, validTill: { $lt: new Date() } },
       { $set: { status: 'expired' } },
   );
 }
@@ -119,7 +184,7 @@ export async function estimateList( req, res ) {
       { $match: { clientId } },
       { $group: { _id: '$status', count: { $sum: 1 } } },
     ] );
-    const counts = { draft: 0, sent: 0, accepted: 0, declined: 0, expired: 0, total: 0 };
+    const counts = { pending: 0, sent: 0, accepted: 0, declined: 0, expired: 0, total: 0 };
     statusAgg.forEach( ( s ) => {
       if ( counts[s._id] != null ) {
         counts[s._id] = s.count;
@@ -175,7 +240,7 @@ export async function createEstimate( req, res ) {
       amount,
       totalAmount,
       currency: b.currency || ( client?.paymentInvoice?.currencyType === 'dollar' ? 'dollar' : 'inr' ),
-      status: b.status === 'sent' ? 'sent' : 'draft',
+      status: b.status === 'sent' ? 'sent' : 'pending',
       createdDate,
       validTill,
       createdBy: req.user?.email || req.user?.userName || '',
@@ -240,7 +305,7 @@ export async function updateEstimate( req, res ) {
       update.period = b.period;
     }
     // Allow a status nudge (e.g. draft → sent) on save, but never to accepted.
-    if ( b.status && [ 'draft', 'sent' ].includes( b.status ) ) {
+    if ( b.status && [ 'pending', 'sent' ].includes( b.status ) ) {
       update.status = b.status;
     }
 
@@ -270,7 +335,7 @@ export async function getEstimate( req, res ) {
 export async function estimateStatusUpdate( req, res ) {
   try {
     const { estimateId, status } = req.body || {};
-    const allowed = [ 'draft', 'sent', 'accepted', 'declined', 'expired' ];
+    const allowed = [ 'pending', 'sent', 'accepted', 'declined', 'expired' ];
     if ( !estimateId || !allowed.includes( status ) ) {
       return res.sendError( 'estimateId and a valid status are required', 400 );
     }
@@ -293,66 +358,7 @@ export async function downloadEstimate( req, res ) {
     if ( !estimate ) {
       return res.sendError( 'Estimate not found', 404 );
     }
-    const e = estimate._doc || estimate;
-    const currencyType = symbolFor( e.currency );
-    const fmt = ( n ) => Number( n || 0 ).toLocaleString( 'en-IN', { minimumFractionDigits: 2, maximumFractionDigits: 2 } );
-
-    const products = ( e.products || [] ).map( ( p, i ) => {
-      let name = String( p.productName || '' ).replace( /([a-z])([A-Z])/g, '$1 $2' );
-      name = name.charAt( 0 ).toUpperCase() + name.slice( 1 );
-      return {
-        index: i + 1,
-        productName: name,
-        description: p.description || '',
-        hsn: p.hsn || p.hsnCode || '998314',
-        storeCount: p.storeCount || e.stores || '',
-        price: fmt( p.price ),
-        amount: fmt( p.amount ),
-      };
-    } );
-    const tax = ( e.tax || [] ).map( ( t ) => ( {
-      type: t.type || t.taxName || t.name || 'GST',
-      value: t.value ?? t.taxPercentage ?? t.percentage ?? '',
-      taxAmount: fmt( t.taxAmount ),
-    } ) );
-
-    const statusLabelMap = { draft: 'Draft', sent: 'Sent', accepted: 'Accepted', declined: 'Declined', expired: 'Expired' };
-    const data = {
-      estimate: e.estimate,
-      status: e.status,
-      statusLabel: statusLabelMap[e.status] || e.status,
-      companyName: e.companyName || '',
-      companyAddress: e.companyAddress || '',
-      GSTNumber: e.GSTNumber || '',
-      PlaceOfSupply: e.PlaceOfSupply || '',
-      groupName: e.groupName || '',
-      period: e.period || '',
-      createdDate: e.createdDate ? dayjs( e.createdDate ).format( 'DD/MM/YYYY' ) : '',
-      validTill: e.validTill ? dayjs( e.validTill ).format( 'DD/MM/YYYY' ) : '',
-      currencyType,
-      amount: fmt( e.amount ),
-      totalAmount: fmt( e.totalAmount ),
-      products,
-      tax,
-      notes: e.notes || '',
-      logo: `${JSON.parse( process.env.URL ).apiDomain}/logo.png`,
-    };
-
-    const templateHtml = fs.readFileSync( path.resolve( path.dirname( '' ) ) + '/src/hbs/estimatePdf.hbs', 'utf8' );
-    const template = Handlebars.compile( templateHtml );
-    const html = template( data );
-    const file = { content: html };
-    const options = {
-      executablePath: '/usr/bin/chromium',
-      args: [ '--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--no-zygote', '--single-process' ],
-      format: 'A4',
-      margin: { top: '0.5in', right: '0.5in', bottom: '0.5in', left: '0.5in' },
-      printBackground: true,
-      preferCSSPageSize: true,
-    };
-    const pdfBuffer = await htmlpdf.generatePdf( file, options );
-
-    const filename = ( e.estimate + '-' + ( e.companyName || 'estimate' ) + '.pdf' ).split( '/' ).join( '_' ).split( '"' ).join( '' ).trim();
+    const { pdfBuffer, filename } = await buildEstimatePdf( estimate );
     res.set( 'Content-Type', 'application/pdf' );
     res.set( 'Content-Disposition', `attachment; filename="${filename}"` );
     return res.send( pdfBuffer );
@@ -362,6 +368,71 @@ export async function downloadEstimate( req, res ) {
   }
 }
 
+// Approve & send an estimate: render the PDF, email it (with the PDF attached)
+// to the billing group's recipients — same recipient logic as invoice send —
+// then flip the status to 'sent'. Triggered by the Approve action's confirm.
+export async function sendEstimate( req, res ) {
+  try {
+    const estimateId = req.body?.estimateId || req.params?.estimateId;
+    if ( !estimateId ) {
+      return res.sendError( 'estimateId is required', 400 );
+    }
+    const estimate = await estimateService.findOne( { _id: estimateId } );
+    if ( !estimate ) {
+      return res.sendError( 'Estimate not found', 404 );
+    }
+    const e = estimate._doc || estimate;
+    if ( e.status === 'accepted' ) {
+      return res.sendError( 'An accepted estimate cannot be re-sent.', 409 );
+    }
+
+    // Recipients: billing group's generateInvoiceTo (TO) + invoice heads /
+    // assigned CSMs (CC) — identical to the invoice send flow.
+    let toEmails = [];
+    if ( e.groupId ) {
+      const group = await billingService.findOne( { _id: e.groupId } );
+      toEmails = ( group?.generateInvoiceTo || [] ).map( ( x ) => String( x || '' ).trim() ).filter( Boolean );
+    }
+    toEmails = [ ...new Set( toEmails ) ];
+    if ( !toEmails.length ) {
+      return res.sendError( 'To Email not Found — configure recipients on the billing group.', 400 );
+    }
+    const ccRaw = await getInvoiceCcEmails( e.clientId );
+    const toSet = new Set( toEmails.map( ( x ) => x.toLowerCase() ) );
+    const ccEmails = [ ...new Set( ( ccRaw || [] ).map( ( x ) => String( x || '' ).trim() ).filter( Boolean ) ) ]
+        .filter( ( x ) => !toSet.has( x.toLowerCase() ) );
+
+    const { pdfBuffer, filename, data } = await buildEstimatePdf( estimate );
+
+    const client = await clientService.findOne( { clientId: e.clientId }, { clientName: 1 } );
+    const emailData = {
+      ...data,
+      clientName: client?.clientName || e.companyName || 'Customer',
+      // The email is sent FROM Tango, so the sign-off is the sender — not the
+      // client's registered company name carried on the estimate.
+      companyName: 'Team Tango',
+    };
+    const emailHtml = Handlebars.compile(
+        fs.readFileSync( path.resolve( path.dirname( '' ) ) + '/src/hbs/estimateEmail.hbs', 'utf8' ),
+    )( emailData );
+
+    const SES = JSON.parse( process.env.SES );
+    const fromEmail = SES.accountsEmail || SES.adminEmail;
+    const subject = `Estimate ${e.estimate} - Tango/${client?.clientName || e.companyName || ''}`;
+    const attachment = { filename, content: pdfBuffer, contentType: 'application/pdf' };
+
+    await sendEmailWithSES( toEmails, subject, emailHtml, attachment, fromEmail, ccEmails.length ? ccEmails : undefined );
+
+    // Mark sent only after a successful send.
+    await estimateService.updateOne( { _id: estimateId }, { $set: { status: 'sent' } } );
+    logger.info?.( { function: 'sendEstimate', estimateId, to: toEmails, cc: ccEmails } );
+    return res.sendSuccess( { estimateId, status: 'sent', sentTo: toEmails } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'sendEstimate' } );
+    return res.sendError( error, 500 );
+  }
+}
+
 export async function deleteEstimate( req, res ) {
   try {
     const estimate = await estimateService.findOne( { _id: req.params.estimateId } );
@@ -371,8 +442,10 @@ export async function deleteEstimate( req, res ) {
     if ( estimate.status === 'accepted' ) {
       return res.sendError( 'An accepted estimate cannot be deleted.', 409 );
     }
-    await estimateService.updateOne( { _id: req.params.estimateId }, { $set: { status: 'declined' } } );
-    return res.sendSuccess( 'Estimate removed' );
+    // Hard delete — remove the document from the collection (not a soft
+    // status change).
+    await estimateService.deleteOne( { _id: req.params.estimateId } );
+    return res.sendSuccess( 'Estimate deleted' );
   } catch ( error ) {
     logger.error( { error: error, function: 'deleteEstimate' } );
     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 * as bankTransactionService from '../services/bankTransaction.service.js';
 import { getUsdInrRate } from './brandsBilling.controller.js';
 
 // Pulls CSM + Finance head emails (stored under applicationDefault
@@ -24,7 +25,7 @@ import { getUsdInrRate } from './brandsBilling.controller.js';
 // userAssignedStore (clientId + tangoUserType:'csm'). Returns a flat de-duped
 // array suitable for the SES CC field. Returns [] on any failure — invoice
 // email send should never fail because of missing settings or DB hiccups.
-async function getInvoiceCcEmails( clientId ) {
+export async function getInvoiceCcEmails( clientId ) {
   const collected = [];
 
   // 1. Configured heads (global, applies to every invoice).
@@ -136,6 +137,35 @@ export async function createInvoice( req, res ) {
         invoiceNo = invoiceNo.toString().padStart( 5, '0' );
       }
       const baseDate = req.body.billingDate ? dayjs( req.body.billingDate ) : dayjs();
+      let customProducts = Array.isArray( req.body.products ) ? req.body.products : [];
+
+      // Advance billing: monthly = 1, half-yearly = 6, yearly = 12. For a
+      // multi-month advance invoice, each month becomes its own line item —
+      // every posted product is repeated once per month, labelled with that
+      // month, so one invoice bills the whole period upfront (same logic as
+      // the auto-generated advance invoices).
+      const customAdvanceMonths = req.body.advanceInvoice ?
+        ( { quarterly: 3, halfyearly: 6, yearly: 12 }[req.body.advancePeriod] || 1 ) : 1;
+      if ( customAdvanceMonths > 1 ) {
+        const expanded = [];
+        for ( let m = 0; m < customAdvanceMonths; m++ ) {
+          const monthLabel = baseDate.add( m, 'month' ).format( 'MMM YYYY' );
+          for ( const p of customProducts ) {
+            expanded.push( { ...p, month: monthLabel } );
+          }
+        }
+        customProducts = expanded;
+      }
+      // Recompute totals from the (possibly expanded) line items so a
+      // multi-month advance invoice bills the full period.
+      const customAmount = customAdvanceMonths > 1 ?
+        Math.round( customProducts.reduce( ( s, p ) => s + ( Number( p.amount ) || 0 ), 0 ) ) :
+        Math.round( Number( req.body.amount ) || 0 );
+      const customTotal = customAdvanceMonths > 1 ?
+        Math.round( customProducts.reduce( ( s, p ) => s + ( Number( p.amount ) || 0 ), 0 ) +
+          ( Array.isArray( req.body.tax ) ? req.body.tax.reduce( ( s, t ) => s + ( Number( t.taxAmount ) || 0 ) * customAdvanceMonths, 0 ) : 0 ) ) :
+        Math.round( Number( req.body.totalAmount ) || 0 );
+
       const data = {
         invoice: `INV-${Finacialyear}-${invoiceNo}`,
         invoiceIndex: invoiceNo,
@@ -147,10 +177,10 @@ export async function createInvoice( req, res ) {
         companyAddress: req.body.companyAddress || '',
         GSTNumber: req.body.GSTNumber || '',
         PlaceOfSupply: req.body.PlaceOfSupply || '',
-        products: Array.isArray( req.body.products ) ? req.body.products : [],
+        products: customProducts,
         tax: Array.isArray( req.body.tax ) ? req.body.tax : [],
-        amount: Math.round( Number( req.body.amount ) || 0 ),
-        totalAmount: Math.round( Number( req.body.totalAmount ) || 0 ),
+        amount: customAmount,
+        totalAmount: customTotal,
         stores: Number( req.body.stores ) || 0,
         currency: req.body.currency || 'inr',
         billingDate: baseDate.toDate(),
@@ -159,6 +189,9 @@ export async function createInvoice( req, res ) {
         paymentMethod: 'Online',
         status: 'pendingCsm',
         paymentStatus: 'unpaid',
+        advanceInvoice: req.body.advanceInvoice || false,
+        advancePeriod: req.body.advanceInvoice ? ( req.body.advancePeriod || 'monthly' ) : undefined,
+        advanceMonths: customAdvanceMonths,
       };
       const created = await invoiceService.create( data );
       const logObj = {
@@ -207,6 +240,32 @@ export async function createInvoice( req, res ) {
       } else {
         products = await stepPrice( group, getClient );
       }
+
+      // Billing horizon in months. Advance and normal cycle are independent —
+      // only one drives the span per generation:
+      //   advanceInvoice ON  -> advancePeriod (advance future billing)
+      //   advanceInvoice OFF -> paymentCycle  (normal billing cycle)
+      // For a multi-month span, each month becomes its own line item: every
+      // product is repeated once per month, labelled with that month, at the
+      // normal monthly amount. One invoice then bills the whole period.
+      // (advancePeriod uses 'halfyearly'; paymentCycle uses 'quarter'/'halfYearly'
+      // — map both spellings.)
+      const advancePeriodMonths = { quarterly: 3, halfyearly: 6, yearly: 12 };
+      const paymentCycleMonths = { quarter: 3, quarterly: 3, halfYearly: 6, halfyearly: 6, yearly: 12 };
+      const advanceMonths = group.advanceInvoice ?
+        ( advancePeriodMonths[group.advancePeriod] || 1 ) :
+        ( paymentCycleMonths[group.paymentCycle] || 1 );
+      if ( advanceMonths > 1 ) {
+        const expanded = [];
+        for ( let m = 0; m < advanceMonths; m++ ) {
+          const monthLabel = baseDate.add( m, 'month' ).format( 'MMM YYYY' );
+          for ( const p of products ) {
+            expanded.push( { ...p, month: monthLabel } );
+          }
+        }
+        products = expanded;
+      }
+
       let amount = products.reduce( ( sum, product ) => sum + product.amount, 0 );
       let taxList = [];
       let totalAmount = 0;
@@ -273,9 +332,15 @@ export async function createInvoice( req, res ) {
 
       ] );
 
-      let invoicedate = req.body.invoiceId ? dayjs( findInvoice.billingDate ).format( 'YYYY-MM-DD' ) : baseDate.format( 'YYYY-MM-DD' );
+      // billingDate is the actual invoice (creation) date — even for advance
+      // invoices. The advance MONTH is reflected only in the product lines /
+      // monthOfbilling (driven by baseDate), not in the billing date itself.
+      // (Regenerate keeps the original invoice's billingDate.)
+      const creationDate = dayjs();
+      let invoicedate = req.body.invoiceId ? dayjs( findInvoice.billingDate ).format( 'YYYY-MM-DD' ) : creationDate.format( 'YYYY-MM-DD' );
       let daysExtend = group?.paymentTerm ? group?.paymentTerm : 30;
-      let dueDate = baseDate.add( daysExtend, 'days' );
+      // Due date is relative to the billing (creation) date.
+      let dueDate = creationDate.add( daysExtend, 'days' );
       console.log( 'group.currencygroup.currency', group.currency );
       let data = {
         groupName: group.groupName,
@@ -299,6 +364,8 @@ export async function createInvoice( req, res ) {
         monthOfbilling: baseDate.format( 'MM' ),
         dueDate: dueDate,
         advanceInvoice: group.advanceInvoice || false,
+        advancePeriod: group.advanceInvoice ? ( group.advancePeriod || 'monthly' ) : undefined,
+        advanceMonths: advanceMonths,
       };
 
       if ( req.body.invoiceId ) {
@@ -842,6 +909,24 @@ export async function invoiceDownloadBulk( req, res ) {
   }
 }
 
+// Bank/beneficiary details for the invoice preview. Fixed beneficiary account
+// — hardcoded to match the PDF exactly (NOT read from the DB).
+export async function invoiceBankDetails( req, res ) {
+  try {
+    return res.sendSuccess( {
+      beneficiaryName: 'Tango IT Solutions India Private Limited',
+      accountNumber: '50200027441433',
+      ifsc: 'HDFC0000386',
+      swift: 'HDFCINBBCHE',
+      branch: 'Santhome, Chennai',
+      paymentType: 'Online',
+    } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'invoiceBankDetails', invoiceId: req.params.invoiceId } );
+    return res.sendError( error, 500 );
+  }
+}
+
 export async function invoiceAnnexure( req, res ) {
   try {
     const invoiceInfo = await invoiceService.findOne( { _id: req.params.invoiceId } );
@@ -2187,6 +2272,18 @@ export async function migrateInvoice( req, res ) {
 export async function PaymentStatusChange( req, res ) {
   try {
     let invoice = await invoiceService.findOne( { invoice: req.body.invoiceId } );
+    if ( !invoice ) {
+      return res.sendError( 'Invoice not found', 404 );
+    }
+    // Payment can only be recorded on an APPROVED invoice — block while it's
+    // still in the approval pipeline.
+    if ( invoice.status !== 'approved' ) {
+      return res.sendError( 'Payment status can be changed only after the invoice is approved.', 409 );
+    }
+    // A paid invoice is locked — its payment status cannot be changed.
+    if ( invoice.paymentStatus === 'paid' ) {
+      return res.sendError( 'This invoice is already paid; its payment status cannot be changed.', 409 );
+    }
     let updateInvoice = await invoiceService.updateOne( { invoice: req.body.invoiceId }, { paymentStatus: req.body.status } );
     let logObj = {
       userName: req.user?.userName,
@@ -2231,6 +2328,14 @@ export async function recordPayment( req, res ) {
     if ( !invoice ) {
       return res.sendError( 'Invoice not found', 404 );
     }
+    // Payment can only be recorded on an APPROVED invoice.
+    if ( invoice.status !== 'approved' ) {
+      return res.sendError( 'Payment can be recorded only after the invoice is approved.', 409 );
+    }
+    // A paid invoice is locked — no further payment / status change.
+    if ( invoice.paymentStatus === 'paid' ) {
+      return res.sendError( 'This invoice is already paid; its payment status cannot be changed.', 409 );
+    }
 
     const previousPaid = Number( invoice.paidAmount ) || 0;
     const newPaid = Math.round( ( previousPaid + amountNum ) * 100 ) / 100;
@@ -2281,6 +2386,32 @@ export async function recordPayment( req, res ) {
     const result = await invoiceService.invoiceUpdateOne( { invoice: invoiceId }, update );
     logger.info?.( { function: 'recordPayment', invoiceId, matched: result?.matchedCount, modified: result?.modifiedCount } );
 
+    // Mirror the manual payment into the Transactions section as a reconciled
+    // row with source 'manual', so manually-recorded payments are visible
+    // alongside bank/VA/gateway transactions.
+    try {
+      const clientForName = await clientService.findOne( { clientId: invoice.clientId }, { clientName: 1 } );
+      await bankTransactionService.insertMany( [ {
+        valueDate: historyEntry.date,
+        narration: notes || `Manual payment recorded for ${invoiceId}`,
+        refNo: reference || '',
+        amount: amountNum,
+        payer: clientForName?.clientName || invoice.companyName || '',
+        source: 'manual',
+        status: 'reconciled',
+        identifiedClientId: String( invoice.clientId ?? '' ),
+        identifiedClientName: clientForName?.clientName || invoice.companyName || '',
+        invoice: invoice.invoice,
+        invoiceId: String( invoice._id ),
+        appliedInvoices: [ { invoiceId: String( invoice._id ), invoice: invoice.invoice, amount: amountNum } ],
+        resultNote: `Manually recorded - ${derivedStatus === 'paid' ? 'invoice marked Paid' : 'partial payment'}`,
+        fileName: 'manual-entry',
+      } ] );
+    } catch ( txnErr ) {
+      // Non-fatal: the payment is already recorded; the mirror row is best-effort.
+      logger.error( { error: txnErr, function: 'recordPayment.mirrorTransaction', invoiceId } );
+    }
+
     try {
       const logObj = {
         userName: req.user?.userName,

package/src/dtos/validation.dtos.js

@@ -329,6 +329,7 @@ export const createBillingGroupBody = joi.object(
       attachAnnexure: joi.boolean().optional(),
       isPrimary: joi.boolean().optional(),
       advanceInvoice: joi.boolean().optional(),
+      advancePeriod: joi.string().valid( 'monthly', 'quarterly', 'halfyearly', 'yearly' ).optional().allow( '' ),
       products: joi.array().items( joi.object( {
         productName: joi.string().required(),
         billingMethod: joi.string().valid( 'eachStore', 'overallStore' ).required(),
@@ -368,6 +369,7 @@ export const updateBillingGroupBody = joi.object(
       attachAnnexure: joi.boolean().optional(),
       isPrimary: joi.boolean().optional(),
       advanceInvoice: joi.boolean().optional(),
+      advancePeriod: joi.string().valid( 'monthly', 'quarterly', 'halfyearly', 'yearly' ).optional().allow( '' ),
       products: joi.array().items( joi.object( {
         _id: joi.any().optional(),
         productName: joi.string().required(),
@@ -401,6 +403,7 @@ export const bulkUpdateBillingGroupRowSchema = joi.object( {
   isInstallationOneTime: joi.boolean().optional(),
   attachAnnexure: joi.boolean().optional(),
   advanceInvoice: joi.boolean().optional(),
+  advancePeriod: joi.string().valid( 'monthly', 'quarterly', 'halfyearly', 'yearly' ).optional().allow( '' ),
   storeId: joi.string().allow( '' ).optional(),
 } );
 

package/src/hbs/estimateEmail.hbs

@@ -0,0 +1,78 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Estimate</title>
+</head>
+<body style="margin:0;padding:0;background-color:#dbe5ea;font-family:'Inter',Arial,sans-serif;">
+  <table border="0" cellpadding="0" cellspacing="0" width="100%" style="padding:0 10px;">
+    <tr>
+      <td style="padding:32px 10px 0 10px;">
+        <table border="0" cellpadding="0" cellspacing="0" width="100%" style="max-width:680px;margin:0 auto;" align="center">
+          <tr>
+            <td style="background-color:#ffffff;padding:24px 24px 0 18px;">
+              <img src="{{logo}}" width="200" height="100" alt="Tango Eye" style="vertical-align:middle;border:0;height:auto;">
+            </td>
+          </tr>
+          <tr>
+            <td style="background-color:#ffffff;padding:0 24px;">
+              <p style="border-top:1px solid #CBD5E1;margin:0;"></p>
+            </td>
+          </tr>
+          <tr>
+            <td style="background-color:#ffffff;padding:18px 24px 6px 30px;">
+              <span style="font-weight:700;color:#121A26;font-size:22px;line-height:32px;">Your estimate {{estimate}}</span>
+            </td>
+          </tr>
+          <tr>
+            <td style="background-color:#ffffff;padding:14px 24px 4px 30px;font-size:16px;line-height:150%;color:#384860;">
+              <p style="margin:0;">Hi {{clientName}},</p>
+            </td>
+          </tr>
+          <tr>
+            <td style="background-color:#ffffff;padding:10px 24px 6px 30px;font-size:16px;line-height:150%;color:#384860;">
+              <p style="margin:0;">Please find attached the estimate <strong>{{estimate}}</strong>{{#if period}} for <strong>{{period}}</strong>{{/if}}. A summary is shown below; the attached PDF has the full breakdown.</p>
+            </td>
+          </tr>
+
+          <tr>
+            <td style="background-color:#ffffff;padding:14px 24px 6px 30px;">
+              <table border="0" cellpadding="0" cellspacing="0" width="100%" style="border:1px solid #E2E8F0;border-radius:8px;border-collapse:separate;overflow:hidden;">
+                <tr style="background-color:#F1F5F9;">
+                  <td style="padding:10px 14px;font-size:13px;color:#64748B;font-weight:600;">Estimate Number</td>
+                  <td style="padding:10px 14px;font-size:13px;color:#121A26;font-weight:700;text-align:right;">{{estimate}}</td>
+                </tr>
+                <tr>
+                  <td style="padding:10px 14px;font-size:13px;color:#64748B;font-weight:600;border-top:1px solid #E2E8F0;">Total Amount</td>
+                  <td style="padding:10px 14px;font-size:13px;color:#121A26;font-weight:700;text-align:right;border-top:1px solid #E2E8F0;">{{currencyType}} {{totalAmount}}</td>
+                </tr>
+                <tr>
+                  <td style="padding:10px 14px;font-size:13px;color:#64748B;font-weight:600;border-top:1px solid #E2E8F0;">Valid Till</td>
+                  <td style="padding:10px 14px;font-size:13px;color:#121A26;font-weight:700;text-align:right;border-top:1px solid #E2E8F0;">{{validTill}}</td>
+                </tr>
+              </table>
+            </td>
+          </tr>
+
+          <tr>
+            <td style="background-color:#ffffff;padding:14px 24px 6px 30px;font-size:16px;line-height:150%;color:#384860;">
+              <p style="margin:0;">This is an estimate, not a tax invoice. Prices are subject to the terms agreed in the final subscription. If you'd like to proceed or have any questions, please reply to this email.</p>
+            </td>
+          </tr>
+          <tr>
+            <td style="background-color:#ffffff;padding:14px 24px 24px 30px;font-size:16px;line-height:150%;color:#384860;">
+              <p style="margin:0;">Best regards,<br>{{companyName}}</p>
+            </td>
+          </tr>
+          <tr>
+            <td style="background-color:#ffffff;padding:10px 24px 18px 30px;font-size:12px;color:#202B3C;line-height:150%;">
+              <p style="margin:0;">© Tango Eye. All rights reserved.</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>