tango-app-api-payment-subscription 3.4.3 → 3.5.0

package/docs/invoice-approval-pipeline.md

@@ -0,0 +1,44 @@
+# 3-Stage Invoice Approval Pipeline
+
+## Overview
+
+Invoices flow through four `status` values:
+
+1. `pendingCsm` (default for new invoices)
+2. `pendingFinance`
+3. `pendingApproval`
+4. `approved` (terminal — `paymentStatus` flow takes over)
+
+## Transitions
+
+| From | To | Endpoint | Permission |
+|---|---|---|---|
+| pendingCsm | pendingFinance | `POST /invoiceapi/approveInvoiceCsm` | `TangoAdmin.csmApproval.isEdit` |
+| pendingFinance | pendingApproval | `POST /invoiceapi/approveInvoiceFinance` | `TangoAdmin.financeApproval.isEdit` |
+| pendingApproval | approved | `POST /invoiceapi/approveInvoiceApproval` | `TangoAdmin.invoiceApproval.isEdit` |
+
+All three accept the same body shape: `{ "invoiceId": "<24-char ObjectId>" }`.
+
+The legacy `POST /invoiceDownload/:invoiceId` flow (with `sendInvoice: true, status: 'approved'`) is still supported BUT now requires the invoice to already be at `pendingApproval`. Earlier stages must use the dedicated advancement endpoints.
+
+## Permission system setup
+
+The `csmApproval` and `financeApproval` modules live under the `TangoAdmin` feature in the user-permission editor. Admin grants them per user via `/manage/users/tango` → Edit → TangoAdmin section → tick the matching Edit checkbox. No separate feature catalogue or seeding is required.
+
+## Auditing
+
+Every successful transition writes one OpenSearch entry with:
+- `logSubType: 'invoiceStatusTransition'`
+- `logType: 'invoice'`
+- `changes: ["Invoice <invoiceNum> advanced from <fromStatus> to <toStatus> by <userEmail>"]`
+
+## Migration
+
+A one-shot script at `scripts/migrate-invoice-status-pipeline.js` migrates existing `pending` invoices to `pendingCsm`. Run it BEFORE deploying the schema enum change in `tango-api-schema`.
+
+## Known limitations
+
+- No rejection / step-back transitions (forward-only).
+- No per-stage timestamps in the schema (use OpenSearch audit log).
+- No email notifications on stage changes.
+- Frontend has not been updated yet — invoices created after this change land at `pendingCsm` and the existing UI cannot advance them. UI feature tracked separately.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.4.3",
+    "version": "3.5.0",
     "description": "paymentSubscription",
     "main": "index.js",
     "type": "module",
@@ -13,22 +13,27 @@
     "author": "praveenraj",
     "license": "ISC",
     "dependencies": {
+        "archiver": "^7.0.1",
         "aws-sdk": "^2.1572.0",
         "axios": "^1.6.8",
         "dayjs": "^1.11.10",
         "dotenv": "^16.4.5",
+        "exceljs": "^4.4.0",
         "express": "^4.18.3",
         "handlebars": "^4.7.8",
         "html-pdf-node": "^1.0.8",
         "joi-to-swagger": "^6.2.0",
         "jsdom": "^24.0.0",
         "mongodb": "^6.4.0",
+        "multer": "^1.4.5-lts.1",
         "nodemon": "^3.1.0",
+        "puppeteer": "^24.41.0",
         "swagger-ui-express": "^5.0.0",
-        "tango-api-schema": "^2.5.73",
+        "tango-api-schema": "^2.5.77",
         "tango-app-api-middleware": "^3.6.18",
         "winston": "^3.12.0",
-        "winston-daily-rotate-file": "^5.0.0"
+        "winston-daily-rotate-file": "^5.0.0",
+        "xlsx": "^0.18.5"
     },
     "devDependencies": {
         "eslint": "^8.57.0",

package/scripts/grant-tango-approval-permissions.js

@@ -0,0 +1,84 @@
+// One-shot permission migration: ensures every tango user's `rolespermission`
+// has the new `csmApproval` and `financeApproval` modules under TangoAdmin
+// with `isEdit: true` granted. Idempotent — re-running it on already-migrated
+// users is a no-op.
+//
+// Usage:
+//   MONGO_URI="mongodb://..." node scripts/grant-tango-approval-permissions.js
+//
+// Run this AFTER deploying the route guard change (Billing.* → TangoAdmin.*)
+// so existing tango admins don't lose access to the approval pipeline.
+
+import mongoose from 'mongoose';
+import 'dotenv/config';
+
+const FEATURE_NAME = 'TangoAdmin';
+const NEW_MODULES = [ 'csmApproval', 'financeApproval' ];
+
+async function run() {
+  const uri = process.env.MONGO_URI;
+  if ( !uri ) {
+    console.error( 'MONGO_URI env var is required' );
+    process.exit( 1 );
+  }
+
+  await mongoose.connect( uri );
+  const User = mongoose.model(
+      '_migrateUser',
+      new mongoose.Schema( {}, { strict: false } ),
+      'users',
+  );
+
+  const tangoUsers = await User.find( { userType: 'tango' } ).lean();
+  console.log( `Found ${tangoUsers.length} tango user(s) to inspect` );
+
+  let modifiedCount = 0;
+  let alreadyOk = 0;
+  let needsTangoAdmin = 0;
+
+  for ( const user of tangoUsers ) {
+    const rolespermission = Array.isArray( user.rolespermission ) ? user.rolespermission : [];
+    let tangoAdmin = rolespermission.find( ( f ) => f && f.featureName === FEATURE_NAME );
+    let changed = false;
+
+    if ( !tangoAdmin ) {
+      // User has no TangoAdmin feature block at all — create one with just
+      // the two new modules. Other TangoAdmin modules (invoiceApproval etc.)
+      // stay unset so we don't accidentally grant unrelated access.
+      tangoAdmin = { featureName: FEATURE_NAME, modules: [] };
+      rolespermission.push( tangoAdmin );
+      needsTangoAdmin++;
+      changed = true;
+    }
+
+    if ( !Array.isArray( tangoAdmin.modules ) ) {
+      tangoAdmin.modules = [];
+    }
+
+    for ( const moduleName of NEW_MODULES ) {
+      if ( !tangoAdmin.modules.some( ( m ) => m && m.name === moduleName ) ) {
+        tangoAdmin.modules.push( { name: moduleName, isAdd: false, isEdit: true } );
+        changed = true;
+      }
+    }
+
+    if ( changed ) {
+      await User.updateOne( { _id: user._id }, { $set: { rolespermission } } );
+      modifiedCount++;
+    } else {
+      alreadyOk++;
+    }
+  }
+
+  console.log( '' );
+  console.log( `Modified:                ${modifiedCount} user(s)` );
+  console.log( `Already up to date:      ${alreadyOk} user(s)` );
+  console.log( `New TangoAdmin blocks:   ${needsTangoAdmin} (users that previously had no TangoAdmin feature)` );
+
+  await mongoose.disconnect();
+}
+
+run().catch( ( err ) => {
+  console.error( err );
+  process.exit( 1 );
+} );

package/scripts/migrate-invoice-status-pipeline.js

@@ -0,0 +1,61 @@
+// One-shot migration: maps legacy invoice status 'pending' to the new
+// pipeline starting stage 'pendingCsm'. Idempotent — safe to re-run.
+//
+// Usage:
+//   MONGO_URI="mongodb://..." node scripts/migrate-invoice-status-pipeline.js
+//
+// Sequencing: MUST run BEFORE deploying the schema enum change in
+// tango-api-schema, otherwise in-flight writes that still set status:'pending'
+// will throw ValidationError.
+
+import mongoose from 'mongoose';
+import 'dotenv/config';
+
+const VALID_STATUSES = [ 'pendingCsm', 'pendingFinance', 'pendingApproval', 'approved' ];
+
+async function run() {
+  const uri = process.env.MONGO_URI;
+  if ( !uri ) {
+    console.error( 'MONGO_URI env var is required' );
+    process.exit( 1 );
+  }
+
+  await mongoose.connect( uri );
+  // Use strict:false so we don't depend on a particular schema package version
+  // for this script — it operates on raw documents.
+  const Invoice = mongoose.model(
+      '_migrateInvoice',
+      new mongoose.Schema( {}, { strict: false } ),
+      'invoices',
+  );
+
+  // 1. Map legacy 'pending' rows to 'pendingCsm'.
+  const pendingResult = await Invoice.updateMany(
+      { status: 'pending' },
+      { $set: { status: 'pendingCsm' } },
+  );
+  console.log( `Migrated ${pendingResult.modifiedCount} invoice(s) from 'pending' → 'pendingCsm'` );
+
+  // 2. Surface any rows whose status isn't in the new enum (for manual review).
+  const stray = await Invoice.find(
+      { status: { $nin: VALID_STATUSES } },
+      { _id: 1, invoice: 1, status: 1 },
+  ).lean();
+
+  if ( stray.length > 0 ) {
+    console.warn( `\n${stray.length} invoice(s) have a status outside the new enum:` );
+    for ( const s of stray ) {
+      console.warn( `  _id=${s._id} invoice=${s.invoice} status=${JSON.stringify( s.status )}` );
+    }
+    console.warn( '\nReview these manually before deploying the schema change.' );
+  } else {
+    console.log( '\nAll invoice rows are in a known state. Safe to publish schema.' );
+  }
+
+  await mongoose.disconnect();
+}
+
+run().catch( ( err ) => {
+  console.error( err );
+  process.exit( 1 );
+} );

package/src/controllers/applicationDefault.controllers.js

@@ -0,0 +1,51 @@
+import { logger, insertOpenSearchData } from 'tango-app-api-middleware';
+import { findOneApplicationDefault, upsertApplicationDefault } from '../services/applicationDefault.service.js';
+
+const INVOICE_HEADS_QUERY = { type: 'invoice', subType: 'heads' };
+
+export async function getInvoiceHeads( req, res ) {
+  try {
+    const doc = await findOneApplicationDefault( INVOICE_HEADS_QUERY );
+    const data = ( doc && Array.isArray( doc.data ) ) ? doc.data : [];
+    return res.sendSuccess( { data } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'getInvoiceHeads' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+export async function updateInvoiceHeads( req, res ) {
+  try {
+    if ( req.user?.role !== 'superadmin' ) {
+      return res.sendError( 'Only superadmin can update invoice settings', 403 );
+    }
+
+    const data = req.body.data;
+    const payload = {
+      type: 'invoice',
+      subType: 'heads',
+      data,
+      active: true,
+    };
+
+    await upsertApplicationDefault( INVOICE_HEADS_QUERY, payload );
+
+    insertOpenSearchData( JSON.parse( process.env.OPENSEARCH ).activityLog, {
+      userName: req.user?.userName,
+      email: req.user?.email,
+      clientId: '',
+      logSubType: 'invoiceSettingsUpdate',
+      logType: 'applicationDefault',
+      date: new Date(),
+      changes: [ `Invoice heads updated by ${req.user?.email}: ${JSON.stringify( data )}` ],
+      eventType: '',
+      timestamp: new Date(),
+      showTo: [ 'tango' ],
+    } );
+
+    return res.sendSuccess( { data } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'updateInvoiceHeads' } );
+    return res.sendError( error, 500 );
+  }
+}

package/src/controllers/billing.controllers.js

@@ -9,6 +9,7 @@ import { leadGet } from '../services/lead.service.js';
 import { findOneClient } from '../services/clientPayment.services.js';
 import * as billingService from '../services/billing.service.js';
 import * as storeService from '../services/store.service.js';
+import { symbolFor } from '../utils/currency.js';
 export const subscribedStoreList = async ( req, res ) => {
   try {
     const matchStage = {
@@ -819,7 +820,7 @@ export const onetimePayment = async ( req, res ) => {
 
     await invoiceService.invoiceUpdateOne( { invoice: invoice.invoice }, { $set: { 'tax': invoice._doc.tax, 'amount': invoice._doc.amount, 'totalAmount': invoice._doc.totalAmount } } );
     let getgroup = await billingService.findOne( { _id: invoice.groupId } );
-    let currency= getgroup.currency==='inr'?'₹':'$';
+    let currency = symbolFor( getgroup.currency );
     let logObj = {
       userName: req.user?.userName,
       email: req.user?.email,