@zenuinebit/gst-return-reconcile

From purchases to a return: read a GSTR-2B download, match it with your purchase register, work out the input credit the filing supports, and lay out a GSTR-3B style worksheet. Builds on @zenuinebit/purchase-gst. Amounts are integers in minor units (paise); dates are "YYYY-MM-DD".

Review everything. The GSTR-2B reader follows the portal's JSON as commonly documented (data.docdata.b2b and cdnr), and that format changes over time, so check it against a real download. Which credit may be claimed is decided by GST law, not by this package. Treat the results as working figures to go through with your accountant.

import { parseGstr2b, reconcileWith2B, gstr3bWorksheet } from "@zenuinebit/gst-return-reconcile";
import { computePurchase } from "@zenuinebit/purchase-gst";
import { generateReport } from "@zenuinebit/gst-report";

const books = purchases.map((p) => computePurchase(p, "27AAPFU0939F1ZV"));   // your register
const twoB = parseGstr2b(await fs.readFile("GSTR2B_042025.json", "utf8"));

const rec = reconcileWith2B(books, twoB, { tolerance: 100 });     // differences up to 1.00 still match
rec.matched; rec.mismatched; rec.missingInSupplierFiling; rec.missingInBooks;     // as in purchase-gst
rec.credit.booked;            // eligible credit in your register, per head (cgst, sgst, igst)
rec.credit.supported;         // the part the supplier filing backs up
rec.credit.atRisk;            // booked - supported
rec.credit.unbookedAvailable; // in 2B and marked available, but not in your books: maybe a forgotten entry
rec.credit.notes;             // supplier credit notes (lower) and debit notes (raise), net
rec.credit.blockedByPortal;   // invoices the portal marks "ITC not available"

const sales = generateReport(invoices, { supplier: "27AAPFU0939F1ZV" });
const sheet = gstr3bWorksheet({
  outward: sales.totals,
  itcClaimed: rec.credit.supported,          // or whatever you decide to claim
  itcReversed: { cgst: 0, sgst: 0, igst: 0 },
  openingCredit: lastMonth.carryForward,
});
sheet.cashPayable; sheet.totalCashPayable; sheet.carryForward;

How it works

• parseGstr2b accepts the JSON object or its text. Invoice amounts are summed from the items; rupees become minor units; dd-mm-yyyy dates become ISO. Invoices the portal marks itcavl: "N" are flagged.
• reconcileWith2B uses the matching in purchase-gst (supplier GSTIN plus invoice number, ignoring case and punctuation). The credit it counts as supported is the lower of your booked credit and the filed tax for each head, and zero for invoices the portal marks as not available.
• gstr3bWorksheet sets credit off the usual way: IGST credit first (against IGST, then CGST, then SGST), then CGST credit (against CGST, then IGST), then SGST credit (against SGST, then IGST). Credit used plus credit carried forward always equals credit available.

Not included: imports, ISD and reverse-charge sections of 2B, amended invoices, interest and late fees, the exact GSTR-3B table layout and JSON, GSTR-1 versus books comparison, and any rule about which credit is blocked or must be reversed.