paisa-mcp 0.0.12 → 0.0.14

package/dist/index.js

@@ -38162,6 +38162,7 @@ class PaisaApiClient {
   constructor(baseUrl, token) {
     this.http = axios_default.create({
       baseURL: baseUrl.replace(/\/$/, ""),
+      timeout: 30000,
       headers: {
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json"
@@ -43081,7 +43082,21 @@ function registerNetWorthTools(server, client) {
       breakdown: exports_external.record(exports_external.string(), exports_external.string()).optional()
     }
   }, async ({ mode, ...body }) => {
-    const data = mode === "auto" ? await client.post("/api/net-worth/auto", { month: body.month, year: body.year }) : await client.post("/api/net-worth", body);
+    let data;
+    if (mode === "auto") {
+      data = await client.post("/api/net-worth/auto", { month: body.month, year: body.year });
+    } else {
+      const liquidCash = parseFloat(body.liquidCash ?? "0");
+      const investments = parseFloat(body.investments ?? "0");
+      const emergencyFund = parseFloat(body.emergencyFund ?? "0");
+      const liabilities = parseFloat(body.liabilities ?? "0");
+      const totalNetWorth = (liquidCash + investments + emergencyFund - liabilities).toFixed(2);
+      data = await client.post("/api/net-worth", {
+        ...body,
+        emergencyFund: body.emergencyFund ?? "0",
+        totalNetWorth
+      });
+    }
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
   });
 }
@@ -45347,6 +45362,368 @@ function settlementEnrichedData(description, type, source) {
     out.settlementCardLast4 = last4;
   return out;
 }
+// ../parsers/src/classify.ts
+var CORPORATE_TOKENS = [
+  "PVT",
+  "PRIVATE",
+  "LIMITED",
+  "LTD",
+  "LLP",
+  "INC",
+  "CORP",
+  "ENTERPRISES",
+  "TECHNOLOGIES",
+  "SOLUTIONS",
+  "SERVICES"
+];
+var CORPORATE_REGEX = new RegExp(`\\b(${CORPORATE_TOKENS.join("|")})\\b`);
+function classifyEntity({ paymentMethod, extractedName }) {
+  if (paymentMethod === "atm")
+    return "merchant";
+  if (paymentMethod === "pos")
+    return "merchant";
+  const upper = (extractedName ?? "").toUpperCase();
+  if (upper && CORPORATE_REGEX.test(upper))
+    return "merchant";
+  if (paymentMethod === "imps")
+    return "person";
+  if (paymentMethod === "upi")
+    return "person";
+  if (paymentMethod === "neft" || paymentMethod === "rtgs")
+    return "merchant";
+  if (paymentMethod === "ach")
+    return "merchant";
+  return "unknown";
+}
+// ../parsers/src/hdfc/narration.ts
+function parseHdfcNarration(narration) {
+  const trimmed = narration.trim();
+  if (trimmed.startsWith("UPI-")) {
+    return parseUpi(trimmed);
+  }
+  if (trimmed.startsWith("NEFT CR-") || trimmed.startsWith("NEFT DR-")) {
+    return parseNeft(trimmed);
+  }
+  if (trimmed.startsWith("ACH D-") || trimmed.startsWith("ACH C-")) {
+    return parseAch(trimmed);
+  }
+  if (trimmed.startsWith("FT-") || trimmed.startsWith("FT -")) {
+    return parseFt(trimmed);
+  }
+  if (trimmed.startsWith("IMPS-") || trimmed.startsWith("IMPS/")) {
+    return parseImps(trimmed);
+  }
+  if (trimmed.startsWith("ATW-") || trimmed.startsWith("ATM-") || trimmed.startsWith("ATM/")) {
+    return {
+      paymentMethod: "atm",
+      name: "ATM Withdrawal",
+      upiId: null,
+      referenceNumber: null,
+      description: trimmed
+    };
+  }
+  if (trimmed.startsWith("POS ")) {
+    return parsePos(trimmed);
+  }
+  return parseFallback(trimmed);
+}
+function parseUpi(narration) {
+  const rest = narration.slice(4);
+  const parts = rest.split("-");
+  if (parts.length < 4) {
+    return {
+      paymentMethod: "upi",
+      name: rest,
+      upiId: null,
+      referenceNumber: null,
+      description: null
+    };
+  }
+  const name = parts[0].trim();
+  const upiId = parts[1]?.trim() || null;
+  const referenceNumber = parts[3]?.trim() || null;
+  const description = parts.length > 4 ? parts.slice(4).join("-").trim() : null;
+  return {
+    paymentMethod: "upi",
+    name: cleanName(name),
+    upiId,
+    referenceNumber,
+    description: description || null
+  };
+}
+function parseNeft(narration) {
+  const isCredit = narration.startsWith("NEFT CR-");
+  const rest = narration.slice(isCredit ? 8 : 8);
+  const parts = rest.split("-");
+  if (parts.length < 2) {
+    return {
+      paymentMethod: "neft",
+      name: rest,
+      upiId: null,
+      referenceNumber: null,
+      description: null
+    };
+  }
+  const companyName = parts[1]?.trim() || parts[0]?.trim() || rest;
+  const referenceNumber = parts[parts.length - 1]?.trim() || null;
+  return {
+    paymentMethod: "neft",
+    name: cleanName(companyName),
+    upiId: null,
+    referenceNumber,
+    description: null
+  };
+}
+function parseAch(narration) {
+  const rest = narration.slice(7).trim();
+  const parts = rest.split("-");
+  const name = parts[0]?.trim() || rest;
+  const referenceNumber = parts.length > 1 ? parts[parts.length - 1]?.trim() : null;
+  return {
+    paymentMethod: "ach",
+    name: cleanName(name),
+    upiId: null,
+    referenceNumber,
+    description: null
+  };
+}
+function parseFt(narration) {
+  const rest = narration.replace(/^FT[\s-]+/, "").trim();
+  const spaceDashParts = rest.split(" - ");
+  if (spaceDashParts.length >= 2) {
+    const namePart = spaceDashParts.find((p2, i2) => i2 > 0 && p2.trim().length > 0);
+    return {
+      paymentMethod: "fund_transfer",
+      name: cleanName(namePart?.trim() || rest),
+      upiId: null,
+      referenceNumber: spaceDashParts[0]?.split("-")[0]?.trim() || null,
+      description: null
+    };
+  }
+  return {
+    paymentMethod: "fund_transfer",
+    name: cleanName(rest),
+    upiId: null,
+    referenceNumber: null,
+    description: null
+  };
+}
+function parseImps(narration) {
+  const rest = narration.replace(/^IMPS[-/]/, "").trim();
+  const parts = rest.split("-");
+  const referenceNumber = parts[0]?.trim() || null;
+  const name = parts.length > 1 ? parts[1]?.trim() : rest;
+  return {
+    paymentMethod: "imps",
+    name: cleanName(name || rest),
+    upiId: null,
+    referenceNumber,
+    description: null
+  };
+}
+function parsePos(narration) {
+  const rest = narration.slice(4).trim();
+  const cleaned = rest.replace(/^[0-9X]{4,}\s*/, "").trim();
+  return {
+    paymentMethod: "pos",
+    name: cleanName(cleaned || rest),
+    upiId: null,
+    referenceNumber: null,
+    description: null
+  };
+}
+function parseFallback(narration) {
+  return {
+    paymentMethod: "other",
+    name: cleanName(narration),
+    upiId: null,
+    referenceNumber: null,
+    description: null
+  };
+}
+function cleanName(raw) {
+  return raw.replace(/\s+(PRIVATE|PVT\.?)\s*\w*/gi, "").replace(/\s+(LIMITED|LTD\.?)(\s|$)/gi, " ").replace(/[\s.-]+$/, "").replace(/\s{2,}/g, " ").trim();
+}
+
+// ../parsers/src/sbi/savings.ts
+function parseSbiNarration(narration) {
+  const upper = narration.toUpperCase();
+  const upiMatch = narration.match(/UPI\/(?:DR|CR)\/(\d+)\/([^/]+)\/([A-Z]{2,6})\/([^/\s]+)/i);
+  if (upiMatch) {
+    const name = upiMatch[2].trim();
+    const upiId = upiMatch[4].trim();
+    return {
+      paymentMethod: "upi",
+      name: name || null,
+      upiId: upiId || null
+    };
+  }
+  if (upper.includes("NEFT")) {
+    const neftMatch = narration.match(/NEFT[-/][\w]+[-/]([\w\s]+?)(?:[-/]|$)/i);
+    return {
+      paymentMethod: "neft",
+      name: neftMatch ? neftMatch[1].trim() : null,
+      upiId: null
+    };
+  }
+  if (upper.includes("RTGS")) {
+    return { paymentMethod: "rtgs", name: null, upiId: null };
+  }
+  if (upper.includes("IMPS")) {
+    return { paymentMethod: "imps", name: null, upiId: null };
+  }
+  if (upper.includes("ATM") || upper.includes("WDL ATM")) {
+    return { paymentMethod: "atm", name: null, upiId: null };
+  }
+  if (upper.includes("POS") || upper.includes("PURCHASE")) {
+    return { paymentMethod: "pos", name: null, upiId: null };
+  }
+  if (upper.includes("INT.COLL") || upper.includes("INTEREST")) {
+    return { paymentMethod: "other", name: "Interest", upiId: null };
+  }
+  return { paymentMethod: null, name: null, upiId: null };
+}
+// src/lib/person-backfill.ts
+function normalizePersonName(name) {
+  return name.toLowerCase().trim().replace(/\s+/g, " ");
+}
+async function loadDecryptedPersons(client, crypto3) {
+  const res = await client.get("/api/persons");
+  const persons = [];
+  for (const p2 of res.data ?? []) {
+    let name = p2.name ?? "";
+    if (crypto3 && p2.cipher) {
+      try {
+        name = (await decryptPersonCipher(p2.cipher, crypto3.key)).name;
+      } catch {}
+    }
+    if (name)
+      persons.push({ id: p2.id, name });
+  }
+  return persons;
+}
+function resolvePersonByName(persons, query) {
+  const q2 = normalizePersonName(query);
+  if (!q2)
+    return null;
+  const exact = persons.filter((p2) => normalizePersonName(p2.name) === q2);
+  if (exact.length === 1)
+    return { personId: exact[0].id };
+  if (exact.length > 1)
+    return { candidates: exact.map((p2) => p2.name) };
+  const partial2 = persons.filter((p2) => normalizePersonName(p2.name).includes(q2));
+  if (partial2.length === 1)
+    return { personId: partial2[0].id };
+  if (partial2.length > 1)
+    return { candidates: partial2.map((p2) => p2.name) };
+  return null;
+}
+function parseNarration(description) {
+  const hdfc = parseHdfcNarration(description);
+  if (hdfc.name && hdfc.paymentMethod)
+    return { name: hdfc.name, upiId: hdfc.upiId, paymentMethod: hdfc.paymentMethod };
+  const sbi = parseSbiNarration(description);
+  if (sbi.name && sbi.paymentMethod)
+    return { name: sbi.name, upiId: sbi.upiId, paymentMethod: sbi.paymentMethod };
+  return {
+    name: hdfc.name || sbi.name,
+    upiId: hdfc.upiId ?? sbi.upiId,
+    paymentMethod: hdfc.paymentMethod ?? sbi.paymentMethod
+  };
+}
+async function backfillPersons(client, crypto3, opts = {}) {
+  const existing = await loadDecryptedPersons(client, crypto3);
+  const personIdByNorm = new Map;
+  for (const p2 of existing)
+    personIdByNorm.set(normalizePersonName(p2.name), p2.id);
+  const candidates = [];
+  let cursor;
+  const MAX_PAGES = 100;
+  for (let page = 0;page < MAX_PAGES; page++) {
+    const params = { limit: 200 };
+    if (cursor)
+      params.cursor = cursor;
+    const res = await client.get("/api/transactions", params);
+    const rows = res.data ?? [];
+    if (crypto3)
+      await decryptTransactionFields(rows, crypto3.key);
+    for (const r2 of rows) {
+      if (!r2.merchantId && !r2.personId && !r2.isTransfer && !r2.isIgnored)
+        candidates.push(r2);
+    }
+    if (!res.hasMore || !res.nextCursor || rows.length === 0)
+      break;
+    cursor = res.nextCursor;
+  }
+  const groups = new Map;
+  for (const t2 of candidates) {
+    const { name, upiId, paymentMethod } = parseNarration(t2.description);
+    if (!name)
+      continue;
+    if (classifyEntity({ paymentMethod, extractedName: name }) !== "person")
+      continue;
+    const norm = normalizePersonName(name);
+    if (!norm)
+      continue;
+    const g2 = groups.get(norm) ?? {
+      displayName: name.trim(),
+      upiHandles: new Set,
+      txnIds: []
+    };
+    if (upiId)
+      g2.upiHandles.add(upiId);
+    g2.txnIds.push(t2.id);
+    groups.set(norm, g2);
+  }
+  const plan = [];
+  const links = [];
+  let created = 0;
+  let reused = 0;
+  for (const [norm, g2] of groups) {
+    const upiHandles = [...g2.upiHandles];
+    let personId = personIdByNorm.get(norm);
+    const action = personId ? "reuse" : "create";
+    plan.push({
+      name: g2.displayName,
+      normalized: norm,
+      txnCount: g2.txnIds.length,
+      upiHandles,
+      action
+    });
+    if (!opts.dryRun) {
+      if (!personId) {
+        const fields = {
+          name: g2.displayName,
+          upiHandles,
+          phoneNumbers: [],
+          relationship: null,
+          notes: null
+        };
+        const body = crypto3 ? await encryptPersonCipher(fields, crypto3.key) : { name: fields.name, upiHandles, phoneNumbers: [], relationship: null, notes: null };
+        const res = await client.post("/api/persons", body);
+        personId = res.data.id;
+        personIdByNorm.set(norm, personId);
+        created++;
+      } else {
+        reused++;
+      }
+      for (const txnId of g2.txnIds)
+        links.push({ transactionId: txnId, personId });
+    } else if (personId) {
+      reused++;
+    } else {
+      created++;
+    }
+  }
+  if (!opts.dryRun && links.length > 0) {
+    const CHUNK = 500;
+    for (let i2 = 0;i2 < links.length; i2 += CHUNK) {
+      await client.post("/api/transactions/bulk-link-entity", { links: links.slice(i2, i2 + CHUNK) });
+    }
+  }
+  return { candidatesScanned: candidates.length, created, reused, linked: links.length, plan };
+}
+
 // src/tools/transactions.ts
 async function importTransactions(client, crypto3, opts) {
   const rows = opts.txns.map((t2) => {
@@ -45387,18 +45764,7 @@ async function runRescan(client, crypto3) {
   const globalMerchants = allMerchants.filter((m2) => !m2.householdId && m2.cleanName).map((m2) => ({ id: m2.id, name: m2.cleanName }));
   const localMerchants = allMerchants.filter((m2) => m2.householdId && m2.cleanName).map((m2) => ({ id: m2.id, name: m2.cleanName }));
   const merchantCategoryById = new Map(allMerchants.filter((m2) => m2.categoryId).map((m2) => [m2.id, m2.categoryId]));
-  const personsRes = await client.get("/api/persons");
-  const persons = [];
-  for (const p2 of personsRes.data ?? []) {
-    let name = p2.name ?? "";
-    if (crypto3 && p2.cipher) {
-      try {
-        name = (await decryptPersonCipher(p2.cipher, crypto3.key)).name;
-      } catch {}
-    }
-    if (name)
-      persons.push({ id: p2.id, name });
-  }
+  const persons = await loadDecryptedPersons(client, crypto3);
   const allRows = [];
   const limit = 200;
   let cursor;
@@ -45444,9 +45810,11 @@ async function runRescan(client, crypto3) {
 }
 function registerTransactionTools(server, client, crypto3) {
   server.registerTool("get_transactions", {
-    description: "Search and filter transactions. Returns paginated results with merchant and category details.",
+    description: "Search and filter transactions. Returns paginated results with merchant and category details. To find everything paid to a specific counterparty, pass `personName` (resolved to a person via the household's persons list) or `personId` directly — this is an indexed lookup, not a description scan. Note: free-text `search` only matches plaintext merchant names, not encrypted descriptions.",
     inputSchema: {
-      search: exports_external.string().optional().describe("Search merchant name or description"),
+      search: exports_external.string().optional().describe("Search merchant name (NOT encrypted descriptions)"),
+      personId: exports_external.string().optional().describe("Filter to one person (exact, indexed)"),
+      personName: exports_external.string().optional().describe("Resolve a counterparty name to a person and filter by it"),
       startDate: exports_external.string().optional().describe("Filter from date (YYYY-MM-DD)"),
       endDate: exports_external.string().optional().describe("Filter to date (YYYY-MM-DD)"),
       owner: exports_external.string().optional(),
@@ -45460,11 +45828,51 @@ function registerTransactionTools(server, client, crypto3) {
       offset: exports_external.number().optional()
     }
   }, async (params) => {
-    const data = await client.get("/api/transactions", Object.fromEntries(Object.entries(params).filter(([, v2]) => v2 !== undefined).map(([k2, v2]) => [k2, String(v2)])));
+    const { personName, ...rest } = params;
+    const apiParams = { ...rest };
+    if (personName && !apiParams.personId) {
+      const persons = await loadDecryptedPersons(client, crypto3);
+      const match = resolvePersonByName(persons, personName);
+      if (!match) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: `No person matches "${personName}". Use list_persons to see known counterparties, or run backfill_persons if persons haven't been extracted yet.`
+              })
+            }
+          ]
+        };
+      }
+      if ("candidates" in match) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: `Ambiguous person "${personName}". Candidates: ${match.candidates.join(", ")}. Re-run with an exact name or personId.`
+              })
+            }
+          ]
+        };
+      }
+      apiParams.personId = match.personId;
+    }
+    const data = await client.get("/api/transactions", Object.fromEntries(Object.entries(apiParams).filter(([, v2]) => v2 !== undefined).map(([k2, v2]) => [k2, String(v2)])));
     if (crypto3 && data.data)
       await decryptTransactionFields(data.data, crypto3.key);
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
   });
+  server.registerTool("backfill_persons", {
+    description: "Extract UPI/IMPS counterparties from unlinked transactions, create person records for them (deduped by name), and link transactions via personId — so you can later filter all payments to a person. Idempotent: re-running reuses existing persons and skips already-linked rows. Pass dryRun to preview without writing.",
+    inputSchema: {
+      dryRun: exports_external.boolean().optional().describe("Preview the persons that would be created/reused without writing")
+    }
+  }, async ({ dryRun }) => {
+    const result = await backfillPersons(client, crypto3, { dryRun });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  });
   server.registerTool("update_transaction", {
     description: "Update a transaction's category, merchant, owner, notes, or flags.",
     inputSchema: {
@@ -45482,6 +45890,16 @@ function registerTransactionTools(server, client, crypto3) {
     const body = { ...updates };
     if (crypto3 && body.notes)
       body.notes = await encryptField(body.notes, crypto3.key);
+    if (body.categorySlug) {
+      const cats = await client.get("/api/categories");
+      const allCats = cats.data.flatMap((c2) => [c2, ...c2.children ?? []]);
+      const cat = allCats.find((c2) => c2.slug === body.categorySlug);
+      if (cat) {
+        body.categoryId = cat.id;
+        body.categoryType = cat.type;
+      }
+      delete body.categorySlug;
+    }
     const data = await client.patch(`/api/transactions/${id}`, body);
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
   });
@@ -45607,6 +46025,49 @@ function registerTransactionTools(server, client, crypto3) {
       ]
     };
   });
+  server.registerTool("bulk_categorize_transactions", {
+    description: "Set categories on multiple transactions at once without needing to link them to a merchant or person. " + "Pass an array of {transactionId, categoryId} pairs. Runs PATCH /api/transactions/{id} for each link in parallel batches. " + "Use this when you have category UUIDs and want to bulk-categorize uncategorized transactions directly.",
+    inputSchema: {
+      links: exports_external.array(exports_external.object({
+        transactionId: exports_external.string().describe("Transaction UUID"),
+        categoryId: exports_external.string().describe("Category UUID")
+      })).min(1).max(500)
+    }
+  }, async ({ links }) => {
+    const catsRes = await client.get("/api/categories");
+    const allCats = catsRes.data.flatMap((c2) => [c2, ...c2.children ?? []]);
+    const typeById = new Map(allCats.map((c2) => [c2.id, c2.type]));
+    const groups = new Map;
+    for (const { transactionId, categoryId } of links) {
+      const arr = groups.get(categoryId) ?? [];
+      arr.push(transactionId);
+      groups.set(categoryId, arr);
+    }
+    const CHUNK = 200;
+    let succeeded = 0;
+    const failed = [];
+    await Promise.allSettled([...groups.entries()].flatMap(([categoryId, ids]) => {
+      const categoryType = typeById.get(categoryId);
+      const chunks = [];
+      for (let i2 = 0;i2 < ids.length; i2 += CHUNK)
+        chunks.push(ids.slice(i2, i2 + CHUNK));
+      return chunks.map((chunk) => client.patch("/api/transactions/bulk", {
+        ids: chunk,
+        categoryId,
+        ...categoryType ? { categoryType } : {}
+      }).then((r2) => {
+        succeeded += r2.updated ?? chunk.length;
+      }).catch((e2) => failed.push({ categoryId, error: String(e2) })));
+    }));
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ succeeded, failedCount: failed.length, failed })
+        }
+      ]
+    };
+  });
   server.registerTool("delete_transactions", {
     description: "Hard-delete transactions. This is PERMANENT and cannot be undone. " + "Provide exactly one of: `id` (single transaction), `ids` (a list of transactions), " + "or `filters` (deletes all matching transactions). Returns the number of deleted transactions " + "for the bulk paths.",
     inputSchema: {
@@ -45696,7 +46157,7 @@ async function main() {
       console.error("Error: PAISA_USER_ID is required when PAISA_PIN is set.");
       process.exit(1);
     }
-    const cryptoMeta = await client.get("/auth-crypto").catch(() => null);
+    const cryptoMeta = await client.get("/api/auth-crypto").catch(() => null);
     if (cryptoMeta && (cryptoMeta.kdfVersion ?? 1) >= 2 && cryptoMeta.kdfSalt && cryptoMeta.wrappedDek) {
       const kek = await deriveKEK(pin, cryptoMeta.kdfSalt);
       const dek = await unwrapDEK(cryptoMeta.wrappedDek, kek);
@@ -45746,5 +46207,5 @@ main().catch((err) => {
   process.exit(1);
 });
 
-//# debugId=2A5FB457B4850D1E64756E2164756E21
+//# debugId=52C61062ED34DC2364756E2164756E21
 //# sourceMappingURL=index.js.map