elpaypg 0.0.0-stage → 2.0.0

package/src/vendor/core/bank-email-parser.js

@@ -0,0 +1,105 @@
+import { toPaise } from '../common/index.js';
+import { extractIntelligentAmount } from './bank-sms-parser.js';
+
+export { extractIntelligentAmount };
+
+/**
+ * Bank email parser for extracting UPI credit alerts across Indian banks:
+ * HDFC, ICICI, SBI, Axis, Kotak, Paytm Payments Bank, custom alt-account transfers, etc.
+ */
+export class BankEmailParser {
+  /**
+   * Parses raw email subject and body text into a canonical observation payload.
+   * @param {{
+   *   subject: string,
+   *   body: string,
+   *   from?: string,
+   *   date?: Date | string
+   * }} email
+   * @returns {{
+   *   amountPaise: bigint,
+   *   amount: string,
+   *   bankReferenceNumber?: string,
+   *   senderVpa?: string,
+   *   observedAt: Date,
+   *   rawSnippet: string
+   * } | null}
+   */
+  static parse(email) {
+    if (!email) return null;
+    const combinedText = `${email.subject || ''} ${email.body || ''}`.trim();
+    if (!combinedText) return null;
+
+    // Check if email represents an incoming credit/payment. A bare "payment" or "transferred"
+    // without credit context is rejected, but "transferred to your account" and "payment of
+    // Rs 500" are genuine credits and must still be recognised.
+    const creditKeywords = new RegExp(
+      '\\b(?:credited|credit|received|deposit(?:ed)?|payment\\s+received|upi\\/cr' +
+      '|transferred\\s+to\\s+(?:your\\s+)?(?:a\\/c|account|wallet)' +
+      '|payment\\s+of\\s+(?:(?:rs\\b\\.?|inr\\b)\\s*)?[\\d,.]+\\s+(?:has\\s+been\\s+)?made\\s+to\\s+(?:your\\s+)?(?:a\\/c|account|wallet)' +
+      '|added\\s+to\\s+(?:your\\s+)?(?:account|wallet))\\b',
+      'i'
+    );
+    if (!creditKeywords.test(combinedText)) {
+      return null; // Ignore non-credit alerts
+    }
+
+    // Reject debit notifications. A debit that appears before any credit means the message is
+    // about money leaving the account; a debit mentioned after a credit (e.g. "Rs 500 credited.
+    // Rs 10 debited for charges") must not cancel the credit.
+    const debitIdx = combinedText.search(/\b(?:debited|withdrawn|deducted|spent|paid rs|sent rs)\b/i);
+    const creditIdx = combinedText.search(/\b(?:credited|credit|received|deposit|deposited)\b/i);
+    if (debitIdx !== -1 && (creditIdx === -1 || debitIdx < creditIdx)) {
+      return null;
+    }
+
+    // 1. Extract Monetary Amount using Intelligent Multi-Pattern Extractor
+    const extractedAmount = extractIntelligentAmount(combinedText);
+    if (!extractedAmount) {
+      return null;
+    }
+
+    // 2. Extract Bank Reference / UTR Number
+    // Matches: UTR: 123456789012, Ref no: UTR-HDFC-9911, Ref: UTR-GMAIL-777, UPI/CR/123456789/, 12-digit UTR
+    let bankRef;
+    const refMatch = combinedText.match(/(?:utr|ref(?:\s*no)?|txn(?:\s*id)?|rrn)[:\s#]+([a-zA-Z0-9\-_]{6,35})/i);
+    if (refMatch && refMatch[1]) {
+      bankRef = refMatch[1].trim();
+    } else {
+      const upiCrMatch = combinedText.match(/UPI\/CR\/([a-zA-Z0-9\-_]+)/i);
+      if (upiCrMatch && upiCrMatch[1]) {
+        bankRef = upiCrMatch[1].trim();
+      } else {
+        const d12Match = combinedText.match(/\b([0-9]{12})\b/);
+        if (d12Match && d12Match[1]) {
+          bankRef = d12Match[1].trim();
+        }
+      }
+    }
+
+    // 3. Extract Sender VPA
+    let senderVpa;
+    const vpaMatch = combinedText.match(/(?:from|by|vpa)\s+([a-zA-Z0-9.\-_]{2,100}@[a-zA-Z0-9.\-_]{2,64})/i);
+    if (vpaMatch && vpaMatch[1]) {
+      senderVpa = vpaMatch[1].trim().replace(/[.,;]+$/, '');
+    }
+
+    // 4. Timestamp
+    let observedAt = new Date();
+    if (email.date) {
+      const parsedDate = new Date(email.date);
+      if (!isNaN(parsedDate.getTime())) {
+        observedAt = parsedDate;
+      }
+    }
+
+    return {
+      amountPaise: extractedAmount.amountPaise,
+      amount: extractedAmount.amountStr,
+      bankReferenceNumber: bankRef,
+      senderVpa,
+      observedAt,
+      rawSnippet: combinedText.substring(0, 300)
+    };
+  }
+}

package/src/vendor/core/bank-sms-parser.js

@@ -0,0 +1,183 @@
+import { toPaise } from '../common/index.js';
+
+/**
+ * Intelligent Monetary Amount Extractor for Indian UPI & Bank SMS.
+ * Extracts amounts with prefix (Rs. 200, INR 500, ₹50), suffix (20.00 Rs),
+ * proximity words ("20.00 received", "credited with 20.00"),
+ * or standalone decimal amounts ("20.00").
+ * Filters out available balance and credit limit clauses so balance amounts are never confused with payment amounts.
+ * @param {string} text
+ * @returns {{ amountStr: string, amountPaise: bigint } | null}
+ */
+export function extractIntelligentAmount(text) {
+  if (!text || typeof text !== 'string') return null;
+
+  // Collapse runs of whitespace before matching. The amount patterns below chain several
+  // whitespace-matching quantifiers (`\s*` ... `\s*` ... `[\s:=-]*`), which is polynomial
+  // backtracking over a whitespace run: a body of "credited" followed by ~250 spaces took
+  // seconds to scan and blocked the payment event loop. With whitespace collapsed to single
+  // spaces the scan is linear and the cost is bounded by the length of the text.
+  const normalizedText = text.replace(/\s+/g, ' ');
+
+  // 0. Remove balance mentions (e.g. "Avl Bal Rs 10,000", "Bal: INR 5000", "Available limit Rs. 20,000")
+  // to avoid extracting account balance instead of credit amount.
+  const balancePattern = /(?:(?:avl\b|avail\b|available\b|tot\b|total\b|ledger\b|clear\b|curr\b|current\b)\s*(?:bal\b|balance\b|limit\b)?|bal\b|balance\b)[\s:=-]*(?:(?:rs\b\.?|inr\b)|₹)?[\s:=-]*[\d,]+(?:\.\d{1,2})?/gi;
+  const sanitizedText = normalizedText.replace(balancePattern, ' ').trim();
+
+  // Pattern 0: Direct credit proximity phrases (e.g. "credited with Rs. 500", "received ₹200.00", "Rs 499.00 credited")
+  const directCreditMatch = sanitizedText.match(/(?:credited\s*(?:with|by|for)?|received|deposit(?:ed)?)\s*[:=-]?\s*(?:(?:rs\b\.?|inr\b)|₹)?[\s:=-]*([\d,]+(?:\.\d{1,2})?)/i) ||
+    sanitizedText.match(/(?:(?:rs\b\.?|inr\b)|₹)[\s:=-]*([\d,]+(?:\.\d{1,2})?)\s*(?:(?:has\s+been|is)\s+)?(?:credited|received|deposited)/i);
+  if (directCreditMatch && (directCreditMatch[1] || directCreditMatch[2])) {
+    const clean = (directCreditMatch[1] || directCreditMatch[2]).replace(/,/g, '');
+    try {
+      return { amountStr: clean, amountPaise: toPaise(clean) };
+    } catch {}
+  }
+
+  // Pattern 1: Standard currency prefix on sanitized text (e.g. Rs 499, Rs. 499, ₹499, INR 499, Rs. 20.00, ₹1,200.50)
+  const prefixMatch = sanitizedText.match(/(?:(?:rs\b\.?|inr\b)|₹)[\s:=-]*([\d,]+(?:\.\d{1,2})?)/i);
+  if (prefixMatch && prefixMatch[1]) {
+    const clean = prefixMatch[1].replace(/,/g, '');
+    try {
+      return { amountStr: clean, amountPaise: toPaise(clean) };
+    } catch {}
+  }
+
+  // Pattern 2: Standard currency suffix on sanitized text (e.g. 499 Rs, 499.00 INR, 20.00 Rs, 20rs, 500 inr)
+  const suffixMatch = sanitizedText.match(/(?:^|[^\w.])([\d,]+(?:\.\d{1,2})?)[\s:=-]*(?:(?:rs\b\.?|inr\b)|₹)/i);
+  if (suffixMatch && suffixMatch[1]) {
+    const clean = suffixMatch[1].replace(/,/g, '');
+    try {
+      return { amountStr: clean, amountPaise: toPaise(clean) };
+    } catch {}
+  }
+
+  // Pattern 3: Number adjacent to credit keywords
+  const creditProximityMatch = sanitizedText.match(/(?:credited|received|deposit|cr)[\s\w:]*?([\d,]+(?:\.\d{1,2})?)|([\d,]+(?:\.\d{1,2})?)[\s\w:]*?(?:credited|received|deposit|cr)/i);
+  if (creditProximityMatch) {
+    const rawVal = creditProximityMatch[1] || creditProximityMatch[2];
+    if (rawVal) {
+      const clean = rawVal.replace(/,/g, '');
+      if (/^\d+(\.\d{1,2})?$/.test(clean) && Number(clean) < 10000000 && Number(clean) > 0) {
+        try {
+          return { amountStr: clean, amountPaise: toPaise(clean) };
+        } catch {}
+      }
+    }
+  }
+
+  // Pattern 4: Standalone decimal currency number (e.g. 20.00, 150.50, 449.00)
+  const standaloneDecimal = sanitizedText.match(/\b(\d{1,6}\.\d{2})\b/);
+  if (standaloneDecimal && standaloneDecimal[1]) {
+    const clean = standaloneDecimal[1];
+    try {
+      return { amountStr: clean, amountPaise: toPaise(clean) };
+    } catch {}
+  }
+
+  return null;
+}
+
+/**
+ * Bank and UPI SMS parser for Indian financial institutions:
+ * SBI, HDFC, ICICI, Axis, Kotak, PNB, Bank of Baroda, Paytm Payments Bank, PhonePe, GPay, etc.
+ */
+export class BankSmsParser {
+  /**
+   * Parses incoming SMS message text.
+   * @param {{
+   *   text: string,
+   *   sender?: string,
+   *   timestamp?: Date | number | string
+   * }} sms
+   * @returns {{
+   *   amountPaise: bigint,
+   *   amount: string,
+   *   bankReferenceNumber?: string,
+   *   senderVpa?: string,
+   *   observedAt: Date,
+   *   rawText: string
+   * } | null}
+   */
+  static parse(sms) {
+    // Bank credit SMS are short. Capping the text bounds the cost of the reference-extraction
+    // regexes, which are scanned from every start offset and would otherwise let one
+    // oversized message block the event loop (ReDoS / DoS).
+    const MAX_SCAN_CHARS = 4096;
+    const text = (sms.text || '').trim().slice(0, MAX_SCAN_CHARS);
+    if (!text) return null;
+
+    // Check if SMS represents an incoming credit. A bare "payment" or "transferred" without
+    // credit context is rejected, but "transferred to your account" and "payment of Rs 500"
+    // are genuine credits and must still be recognised.
+    const creditKeywords = new RegExp(
+      '\\b(?:credited|received|deposit(?:ed)?|payment\\s+received|money\\s+received|upi\\/cr' +
+      '|transferred\\s+to\\s+(?:your\\s+)?(?:a\\/c|account|wallet)' +
+      '|payment\\s+of\\s+(?:(?:rs\\b\\.?|inr\\b)\\s*)?[\\d,.]+\\s+(?:has\\s+been\\s+)?made\\s+to\\s+(?:your\\s+)?(?:a\\/c|account|wallet)' +
+      '|added\\s+to\\s+(?:your\\s+)?(?:account|wallet))\\b',
+      'i'
+    );
+    if (!creditKeywords.test(text)) {
+      return null;
+    }
+
+    // Reject debit notifications:
+    // A debit indicator that appears before any credit indicator means the message is about
+    // money leaving the account (e.g. "debited ... credited back in 48h"), so it is refused.
+    // A debit mentioned *after* a credit (e.g. "Rs 500 credited. Rs 10 debited for SMS
+    // charges") must not cancel the credit, so ordering is what decides.
+    const debitIdx = text.search(/\b(?:debited|withdrawn|deducted|spent|paid rs|sent rs)\b/i);
+    const creditIdx = text.search(/\b(?:credited|received|deposit|deposited)\b/i);
+    if (debitIdx !== -1 && (creditIdx === -1 || debitIdx < creditIdx)) {
+      return null;
+    }
+
+    // 1. Extract Amount using Intelligent Multi-Pattern Extractor
+    const extractedAmount = extractIntelligentAmount(text);
+    if (!extractedAmount) {
+      return null;
+    }
+
+    // 2. Extract Bank Reference / UTR / RRN (including FamPay Transaction IDs)
+    let bankRef;
+    const utrPatterns = [
+      /(?:upi\s*ref(?:erence)?\s*(?:no\.?|num)?|utr(?:\s*no\.?)?|rrn(?:\s*no\.?)?|txn\s*(?:id|ref|#)?|transaction\s*id|ref\s*no\.?)[\s:=-]+([a-zA-Z0-9\-_]{6,35})/i,
+      /(?:upi\/(?:[0-9]+\/|cr\/)([a-zA-Z0-9\-_]{6,35}))/i,
+      /\b(?:ref(?:\s*(?:no\.?|id|#))?)[:\s#=-]+([a-zA-Z0-9\-_]{6,35})/i,
+      /\b([0-9]{12})\b/
+    ];
+
+    for (const pat of utrPatterns) {
+      const match = text.match(pat);
+      if (match && match[1]) {
+        bankRef = match[1].trim();
+        break;
+      }
+    }
+
+    // 3. Extract Sender VPA (including FamPay formats like "from Rahul (UPI ID: rahul@fam)")
+    let senderVpa;
+    const vpaMatch = text.match(/(?:from|by|vpa|upi\s*id)[\s:]+(?:[a-zA-Z\s]+[\(\[])?([a-zA-Z0-9.\-_]{2,64}@[a-zA-Z0-9.\-_]{2,32})/i);
+    if (vpaMatch && vpaMatch[1]) {
+      senderVpa = vpaMatch[1].trim().replace(/[.,;]+$/, '');
+    }
+
+    // 4. Resolve Observation Timestamp
+    let observedAt = new Date();
+    if (sms.timestamp) {
+      const parsed = new Date(sms.timestamp);
+      if (!isNaN(parsed.getTime())) {
+        observedAt = parsed;
+      }
+    }
+
+    return {
+      amountPaise: extractedAmount.amountPaise,
+      amount: extractedAmount.amountStr,
+      bankReferenceNumber: bankRef,
+      senderVpa,
+      observedAt,
+      rawText: text
+    };
+  }
+}