india2actual 0.1.0

package/dist/extract/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/extract/types.ts"],"names":[],"mappings":""}

package/dist/extract/xlsx.d.ts

@@ -0,0 +1,2 @@
+import type { Table } from './types.js';
+export declare function extractXlsx(path: string): Promise<Table>;

package/dist/extract/xlsx.js

@@ -0,0 +1,64 @@
+import ExcelJS from 'exceljs';
+/**
+ * Render a cell as the text a human would see.
+ *
+ * Dates are the reason this exists: a date-formatted cell comes back as a
+ * `Date`, and stringifying it naively yields a locale-dependent form that the
+ * day-first date parser would then misread. Emitting ISO makes it unambiguous.
+ */
+function cellText(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return value.toISOString().slice(0, 10);
+    }
+    if (typeof value === 'object') {
+        // Formula cells carry their computed result; hyperlinks and rich text
+        // carry display text.
+        if ('result' in value && value.result !== undefined) {
+            return cellText(value.result);
+        }
+        if ('text' in value && value.text !== undefined) {
+            return String(value.text);
+        }
+        if ('richText' in value && Array.isArray(value.richText)) {
+            return value.richText.map(part => part.text).join('');
+        }
+        if ('hyperlink' in value) {
+            return '';
+        }
+        return '';
+    }
+    return String(value);
+}
+export async function extractXlsx(path) {
+    const workbook = new ExcelJS.Workbook();
+    await workbook.xlsx.readFile(path);
+    // Statement workbooks occasionally carry a cover or summary sheet, so the
+    // densest sheet is a better bet than the first one.
+    let best = null;
+    for (const worksheet of workbook.worksheets) {
+        const rows = [];
+        worksheet.eachRow({ includeEmpty: true }, row => {
+            const cells = [];
+            // `row.cellCount` counts to the last populated cell, which is what keeps
+            // column indexes aligned with the header.
+            for (let column = 1; column <= row.cellCount; column += 1) {
+                cells.push(cellText(row.getCell(column).value).trim());
+            }
+            rows.push(cells);
+        });
+        if (!best || rows.length > best.rows.length) {
+            best = { rows, name: worksheet.name };
+        }
+    }
+    if (!best) {
+        return { rows: [], source: { path, format: 'xlsx' } };
+    }
+    return {
+        rows: best.rows,
+        source: { path, format: 'xlsx', part: best.name },
+    };
+}
+//# sourceMappingURL=xlsx.js.map

package/dist/extract/xlsx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xlsx.js","sourceRoot":"","sources":["../../src/extract/xlsx.ts"],"names":[],"mappings":"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"}

package/dist/interpret/header.d.ts

@@ -0,0 +1,24 @@
+import type { ColumnRole } from './synonyms.js';
+/** Column index for each role we could identify. */
+export type ColumnMap = Partial<Record<ColumnRole, number>>;
+export type HeaderMatch = {
+    /** Row index of the header within the table. */
+    index: number;
+    map: ColumnMap;
+    /** Number of roles identified — used to choose between candidate rows. */
+    score: number;
+};
+/**
+ * A table is only usable if we can find a date, something to use as a payee,
+ * and at least one amount column.
+ */
+export declare function isUsable(map: ColumnMap): boolean;
+/**
+ * Locate the transaction table's header row.
+ *
+ * Indian statements put a variable number of preamble rows above the table
+ * (branch address, account holder, statement period), so the header cannot be
+ * assumed to be row 0. Instead every row in range is scored by how many known
+ * columns it contains, and the best usable row wins.
+ */
+export declare function findHeader(rows: string[][]): HeaderMatch | null;

package/dist/interpret/header.js

@@ -0,0 +1,57 @@
+import { roleForHeader } from './synonyms.js';
+/** How far into the file to look before giving up. */
+const MAX_HEADER_SCAN = 40;
+/**
+ * A table is only usable if we can find a date, something to use as a payee,
+ * and at least one amount column.
+ */
+export function isUsable(map) {
+    const hasDate = map.date !== undefined || map.valueDate !== undefined;
+    const hasDescription = map.description !== undefined;
+    const hasAmount = map.debit !== undefined ||
+        map.credit !== undefined ||
+        map.amount !== undefined;
+    return hasDate && hasDescription && hasAmount;
+}
+function mapRow(row) {
+    const map = {};
+    for (const [index, cell] of row.entries()) {
+        const role = roleForHeader(cell);
+        // First occurrence wins: ICICI repeats `Value Date` and `Transaction
+        // Date`, and the leftmost match is the one the bank leads with.
+        if (role && map[role] === undefined) {
+            map[role] = index;
+        }
+    }
+    return map;
+}
+/**
+ * Locate the transaction table's header row.
+ *
+ * Indian statements put a variable number of preamble rows above the table
+ * (branch address, account holder, statement period), so the header cannot be
+ * assumed to be row 0. Instead every row in range is scored by how many known
+ * columns it contains, and the best usable row wins.
+ */
+export function findHeader(rows) {
+    let best = null;
+    const limit = Math.min(rows.length, MAX_HEADER_SCAN);
+    for (let index = 0; index < limit; index += 1) {
+        const row = rows[index];
+        if (!row) {
+            continue;
+        }
+        const map = mapRow(row);
+        if (!isUsable(map)) {
+            continue;
+        }
+        const score = Object.keys(map).length;
+        // Strictly greater, so the earliest of equally-good rows wins. Some banks
+        // repeat the header on every page; the first one is the real table start.
+        if (!best || score > best.score) {
+            best = { index, map, score };
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=header.js.map

package/dist/interpret/header.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.js","sourceRoot":"","sources":["../../src/interpret/header.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAc9C,sDAAsD;AACtD,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAc;IACrC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC;IACtE,MAAM,cAAc,GAAG,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC;IACrD,MAAM,SAAS,GACb,GAAG,CAAC,KAAK,KAAK,SAAS;QACvB,GAAG,CAAC,MAAM,KAAK,SAAS;QACxB,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC;IAE3B,OAAO,OAAO,IAAI,cAAc,IAAI,SAAS,CAAC;AAChD,CAAC;AAED,SAAS,MAAM,CAAC,GAAa;IAC3B,MAAM,GAAG,GAAc,EAAE,CAAC;IAE1B,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACjC,qEAAqE;QACrE,gEAAgE;QAChE,IAAI,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB;IACzC,IAAI,IAAI,GAAuB,IAAI,CAAC;IAEpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACrD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,SAAS;QACX,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACtC,0EAA0E;QAC1E,0EAA0E;QAC1E,IAAI,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/interpret/roundtrip.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Read this tool's own CSV output back in, so a reviewed and hand-corrected CSV
+ * can be pushed.
+ *
+ * Generic header detection requires a description column, and neither `Payee`
+ * nor `Notes` matches any bank's narration vocabulary, so without this path the
+ * tool cannot read its own output.
+ *
+ * Adding `payee`/`notes` to that vocabulary instead would feed the Notes column
+ * back through narration parsing and overwrite the Payee column, discarding the
+ * manual corrections. Hence an exact-header match with payees kept verbatim.
+ */
+import type { Table } from '../extract/types.js';
+import type { Interpreted } from './rows.js';
+/**
+ * Does this table look like output this tool produced?
+ *
+ * Strict by design: an exact header match, in order. A bank CSV that happens to
+ * have a `Payee` column must still take the generic path so its narration gets
+ * parsed.
+ */
+export declare function isConvertedOutput(table: Table): boolean;
+/**
+ * Interpret converted output, taking every field at face value.
+ *
+ * The amount is already signed, the date already ISO, and the payee already
+ * resolved, possibly by hand. Nothing here re-derives any of it.
+ */
+export declare function interpretConvertedOutput(table: Table): Interpreted;

package/dist/interpret/roundtrip.js

@@ -0,0 +1,89 @@
+/**
+ * Read this tool's own CSV output back in, so a reviewed and hand-corrected CSV
+ * can be pushed.
+ *
+ * Generic header detection requires a description column, and neither `Payee`
+ * nor `Notes` matches any bank's narration vocabulary, so without this path the
+ * tool cannot read its own output.
+ *
+ * Adding `payee`/`notes` to that vocabulary instead would feed the Notes column
+ * back through narration parsing and overwrite the Payee column, discarding the
+ * manual corrections. Hence an exact-header match with payees kept verbatim.
+ */
+import { parseAmount, parseStatementDate } from './values.js';
+/** The header `toCsv` writes. Must stay in step with `COLUMNS` there. */
+const CONVERTED_HEADER = ['date', 'payee', 'notes', 'amount', 'reference'];
+/** For reporting only. `description: 2` is Notes, though it is not re-parsed. */
+const CONVERTED_MAP = {
+    date: 0,
+    description: 2,
+    amount: 3,
+    ref: 4,
+};
+function normalize(cell) {
+    return cell.trim().toLowerCase();
+}
+/**
+ * Does this table look like output this tool produced?
+ *
+ * Strict by design: an exact header match, in order. A bank CSV that happens to
+ * have a `Payee` column must still take the generic path so its narration gets
+ * parsed.
+ */
+export function isConvertedOutput(table) {
+    const header = table.rows[0];
+    if (!header) {
+        return false;
+    }
+    const cells = header.map(normalize);
+    return (cells.length >= CONVERTED_HEADER.length &&
+        CONVERTED_HEADER.every((name, index) => cells[index] === name));
+}
+/**
+ * Interpret converted output, taking every field at face value.
+ *
+ * The amount is already signed, the date already ISO, and the payee already
+ * resolved, possibly by hand. Nothing here re-derives any of it.
+ */
+export function interpretConvertedOutput(table) {
+    const transactions = [];
+    const skipped = [];
+    for (let index = 1; index < table.rows.length; index += 1) {
+        const row = table.rows[index];
+        if (!row || row.every(value => !value.trim())) {
+            continue;
+        }
+        const date = parseStatementDate(row[0] ?? '', 'ymd');
+        if (!date) {
+            skipped.push({ index, reason: 'no parseable date', row });
+            continue;
+        }
+        const amount = parseAmount(row[3] ?? '');
+        if (amount === null) {
+            skipped.push({ index, reason: 'no parseable amount', row });
+            continue;
+        }
+        const notes = (row[2] ?? '').trim();
+        const payee = (row[1] ?? '').trim();
+        const ref = (row[4] ?? '').trim();
+        transactions.push({
+            date,
+            amount,
+            // A blanked-out Payee still needs a value; same fallback as the parser.
+            payee: payee || notes || 'Unknown',
+            raw: notes,
+            // Already-converted rows carry no narration to classify, and the kind is
+            // only used for reporting.
+            kind: 'other',
+            ...(ref ? { ref } : {}),
+        });
+    }
+    return {
+        transactions,
+        skipped,
+        header: { index: 0, map: CONVERTED_MAP },
+        // References were already checked for uniqueness when the CSV was written.
+        droppedRefs: 0,
+    };
+}
+//# sourceMappingURL=roundtrip.js.map

package/dist/interpret/roundtrip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roundtrip.js","sourceRoot":"","sources":["../../src/interpret/roundtrip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE9D,yEAAyE;AACzE,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AAE3E,iFAAiF;AACjF,MAAM,aAAa,GAAc;IAC/B,IAAI,EAAE,CAAC;IACP,WAAW,EAAE,CAAC;IACd,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;CACP,CAAC;AAEF,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAY;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,CACL,KAAK,CAAC,MAAM,IAAI,gBAAgB,CAAC,MAAM;QACvC,gBAAgB,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAY;IACnD,MAAM,YAAY,GAA2B,EAAE,CAAC;IAChD,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9C,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAAC,CAAC;YAC1D,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,CAAC,CAAC;YAC5D,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAElC,YAAY,CAAC,IAAI,CAAC;YAChB,IAAI;YACJ,MAAM;YACN,wEAAwE;YACxE,KAAK,EAAE,KAAK,IAAI,KAAK,IAAI,SAAS;YAClC,GAAG,EAAE,KAAK;YACV,yEAAyE;YACzE,2BAA2B;YAC3B,IAAI,EAAE,OAAO;YACb,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxB,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,YAAY;QACZ,OAAO;QACP,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE;QACxC,2EAA2E;QAC3E,WAAW,EAAE,CAAC;KACf,CAAC;AACJ,CAAC"}

package/dist/interpret/rows.d.ts

@@ -0,0 +1,54 @@
+import type { Table } from '../extract/types.js';
+import type { MerchantRule } from '../narration/merchants.js';
+import type { NarrationKind } from '../narration/types.js';
+import type { ColumnMap } from './header.js';
+import type { DateOrder } from './values.js';
+export type StatementTransaction = {
+    /** `YYYY-MM-DD`. */
+    date: string;
+    /** Signed rupees: negative for money out. */
+    amount: number;
+    /** Cleaned merchant, for Actual's `payee_name`. */
+    payee: string;
+    /** Original narration, for Actual's `imported_payee`. */
+    raw: string;
+    kind: NarrationKind;
+    /** Only set when safe to use as `imported_id` — see `dropRepeatedRefs`. */
+    ref?: string;
+    /** Running balance, when the statement has one. Used only for validation. */
+    balance?: number;
+};
+export type SkippedRow = {
+    /** Row index in the original table. */
+    index: number;
+    reason: string;
+    row: string[];
+};
+export type InterpretResult = {
+    transactions: StatementTransaction[];
+    skipped: SkippedRow[];
+    header: {
+        index: number;
+        map: ColumnMap;
+    };
+};
+export type InterpretOptions = {
+    dateOrder?: DateOrder;
+    merchantRules?: MerchantRule[];
+    /** Force a column map instead of detecting one (per-bank override). */
+    columnMap?: ColumnMap;
+    /** Force the header row index. */
+    headerIndex?: number;
+};
+export type Interpreted = InterpretResult & {
+    /** How many references were discarded as non-unique. */
+    droppedRefs: number;
+};
+/**
+ * Turn an extracted table into transactions.
+ *
+ * Rows that lack a parseable date or amount are skipped rather than guessed
+ * at — that is what removes statement preambles, page headers repeated
+ * mid-file, and footer totals without needing to know how many there are.
+ */
+export declare function interpretTable(table: Table, options?: InterpretOptions): Interpreted | null;

package/dist/interpret/rows.js

@@ -0,0 +1,151 @@
+import { parseNarration } from '../narration/parse.js';
+import { findHeader } from './header.js';
+import { parseAmount, parseStatementDate } from './values.js';
+function cell(row, index) {
+    if (index === undefined) {
+        return '';
+    }
+    return row[index] ?? '';
+}
+/**
+ * A zero in a Withdrawal/Deposit pair means "not this side", not a zero-rupee
+ * transaction, so it is treated as absent.
+ */
+function presentAmount(value) {
+    if (value === null || value === 0) {
+        return null;
+    }
+    return value;
+}
+function resolveAmount(row, map) {
+    const debit = presentAmount(parseAmount(cell(row, map.debit)));
+    const credit = presentAmount(parseAmount(cell(row, map.credit)));
+    if (map.debit !== undefined || map.credit !== undefined) {
+        if (credit !== null) {
+            return Math.abs(credit);
+        }
+        if (debit !== null) {
+            return -Math.abs(debit);
+        }
+        // Fall through: some banks carry both a Dr/Cr pair and a single amount
+        // column, and only populate one of them.
+    }
+    const amount = presentAmount(parseAmount(cell(row, map.amount)));
+    if (amount === null) {
+        return null;
+    }
+    // An explicit indicator column overrides whatever sign the amount carried.
+    const indicator = cell(row, map.drcr).trim().toLowerCase();
+    if (indicator) {
+        if (/^d/.test(indicator)) {
+            return -Math.abs(amount);
+        }
+        if (/^c/.test(indicator)) {
+            return Math.abs(amount);
+        }
+    }
+    return amount;
+}
+/** Reference-column values that carry no information. */
+function usableColumnRef(value) {
+    const trimmed = value.trim();
+    if (trimmed.length < 6) {
+        return null;
+    }
+    // `0`, `000000`, `-`, `NA`.
+    if (/^[0\s\-.]*$/.test(trimmed) || /^na$/i.test(trimmed)) {
+        return null;
+    }
+    return trimmed;
+}
+/**
+ * Strip references that occur more than once in the file.
+ *
+ * A genuine bank reference is unique per transaction, so a repeat means we
+ * picked up something else — an account number, a padded placeholder, a
+ * recurring mandate id. Leaving it in place would make Actual treat distinct
+ * transactions as the same one and silently drop them, which is strictly worse
+ * than having no reference at all (where Actual's date+amount fuzzy matching
+ * takes over).
+ */
+function dropRepeatedRefs(transactions) {
+    const counts = new Map();
+    for (const transaction of transactions) {
+        if (transaction.ref) {
+            counts.set(transaction.ref, (counts.get(transaction.ref) ?? 0) + 1);
+        }
+    }
+    let dropped = 0;
+    for (const transaction of transactions) {
+        if (transaction.ref && (counts.get(transaction.ref) ?? 0) > 1) {
+            delete transaction.ref;
+            dropped += 1;
+        }
+    }
+    return dropped;
+}
+/**
+ * Turn an extracted table into transactions.
+ *
+ * Rows that lack a parseable date or amount are skipped rather than guessed
+ * at — that is what removes statement preambles, page headers repeated
+ * mid-file, and footer totals without needing to know how many there are.
+ */
+export function interpretTable(table, options = {}) {
+    let headerIndex = options.headerIndex;
+    let map = options.columnMap;
+    if (headerIndex === undefined || !map) {
+        const detected = findHeader(table.rows);
+        if (!detected) {
+            return null;
+        }
+        headerIndex = headerIndex ?? detected.index;
+        map = map ?? detected.map;
+    }
+    const transactions = [];
+    const skipped = [];
+    for (let index = headerIndex + 1; index < table.rows.length; index += 1) {
+        const row = table.rows[index];
+        if (!row || row.every(value => !value.trim())) {
+            continue;
+        }
+        const dateCell = cell(row, map.date) || cell(row, map.valueDate);
+        const date = parseStatementDate(dateCell, options.dateOrder);
+        if (!date) {
+            skipped.push({ index, reason: 'no parseable date', row });
+            continue;
+        }
+        const amount = resolveAmount(row, map);
+        if (amount === null) {
+            skipped.push({ index, reason: 'no parseable amount', row });
+            continue;
+        }
+        const narration = cell(row, map.description);
+        const parsed = parseNarration(narration, {
+            ...(options.merchantRules
+                ? { merchantRules: options.merchantRules }
+                : {}),
+        });
+        // The narration's UTR is the most trustworthy reference; the reference
+        // column is a fallback and is subject to the uniqueness guard below.
+        const ref = parsed.ref ?? usableColumnRef(cell(row, map.ref));
+        const balance = parseAmount(cell(row, map.balance));
+        transactions.push({
+            date,
+            amount,
+            payee: parsed.merchant,
+            raw: parsed.raw,
+            kind: parsed.kind,
+            ...(ref ? { ref } : {}),
+            ...(balance !== null ? { balance } : {}),
+        });
+    }
+    const droppedRefs = dropRepeatedRefs(transactions);
+    return {
+        transactions,
+        skipped,
+        header: { index: headerIndex, map },
+        droppedRefs,
+    };
+}
+//# sourceMappingURL=rows.js.map

package/dist/interpret/rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.js","sourceRoot":"","sources":["../../src/interpret/rows.ts"],"names":[],"mappings":"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"}

package/dist/interpret/synonyms.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Column vocabulary for Indian bank statements.
+ *
+ * Every Indian bank ships variations of the same seven columns, which is what
+ * makes a generic interpreter viable instead of an adapter per bank:
+ *
+ *   HDFC    Date | Narration | Chq./Ref.No. | Value Dt | Withdrawal Amt. | Deposit Amt. | Closing Balance
+ *   ICICI   S No. | Value Date | Transaction Date | Cheque Number | Transaction Remarks | Withdrawal Amount (INR) | Deposit Amount (INR) | Balance (INR)
+ *   SBI     Txn Date | Value Date | Description | Ref No./Cheque No. | Debit | Credit | Balance
+ *   Axis    Tran Date | CHQNO | PARTICULARS | DR | CR | BAL
+ *
+ * Matching is done on a normalised header cell (lowercased, non-alphanumerics
+ * stripped), so `Withdrawal Amt.` becomes `withdrawalamt` and
+ * `Deposit Amount (INR)` becomes `depositamountinr`. Prefix/substring patterns
+ * then cover the variants without enumerating every spelling.
+ */
+export type ColumnRole = 'date' | 'valueDate' | 'description' | 'debit' | 'credit' | 'amount' | 'drcr' | 'balance' | 'ref';
+/**
+ * Order is significant — the first pattern to match a header cell wins.
+ *
+ * `valueDate` precedes `date` because `Value Date` also ends in "date", and
+ * `drcr` precedes `debit`/`credit` because a `DR/CR` indicator column would
+ * otherwise be mistaken for an amount column.
+ */
+export declare const COLUMN_PATTERNS: Array<[ColumnRole, RegExp]>;
+export declare function normalizeHeader(cell: string): string;
+export declare function roleForHeader(cell: string): ColumnRole | null;

package/dist/interpret/synonyms.js

@@ -0,0 +1,55 @@
+/**
+ * Column vocabulary for Indian bank statements.
+ *
+ * Every Indian bank ships variations of the same seven columns, which is what
+ * makes a generic interpreter viable instead of an adapter per bank:
+ *
+ *   HDFC    Date | Narration | Chq./Ref.No. | Value Dt | Withdrawal Amt. | Deposit Amt. | Closing Balance
+ *   ICICI   S No. | Value Date | Transaction Date | Cheque Number | Transaction Remarks | Withdrawal Amount (INR) | Deposit Amount (INR) | Balance (INR)
+ *   SBI     Txn Date | Value Date | Description | Ref No./Cheque No. | Debit | Credit | Balance
+ *   Axis    Tran Date | CHQNO | PARTICULARS | DR | CR | BAL
+ *
+ * Matching is done on a normalised header cell (lowercased, non-alphanumerics
+ * stripped), so `Withdrawal Amt.` becomes `withdrawalamt` and
+ * `Deposit Amount (INR)` becomes `depositamountinr`. Prefix/substring patterns
+ * then cover the variants without enumerating every spelling.
+ */
+/**
+ * Order is significant — the first pattern to match a header cell wins.
+ *
+ * `valueDate` precedes `date` because `Value Date` also ends in "date", and
+ * `drcr` precedes `debit`/`credit` because a `DR/CR` indicator column would
+ * otherwise be mistaken for an amount column.
+ */
+export const COLUMN_PATTERNS = [
+    ['valueDate', /^value(date|dt)$/],
+    ['drcr', /^(drcr|crdr|debitcredit|drcrindicator)$/],
+    ['drcr', /^(transaction)?type$/],
+    [
+        'date',
+        /^(txn|tran|transaction|posting|post|entry|booking|trade)?d(ate|t)$/,
+    ],
+    ['date', /^dateoftransaction$/],
+    ['description', /(narration|particular|description|remark|detail|narrative)/],
+    ['debit', /^(withdrawal|debit|dr)/],
+    ['credit', /^(deposit|credit|cr)/],
+    ['balance', /(balance|^bal$)/],
+    ['amount', /^(amount|amt|txnamount|transactionamount)/],
+    ['ref', /(chq|cheque|refno|reference|utr|rrn|transactionid)/],
+];
+export function normalizeHeader(cell) {
+    return cell.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+export function roleForHeader(cell) {
+    const normalized = normalizeHeader(cell);
+    if (!normalized) {
+        return null;
+    }
+    for (const [role, pattern] of COLUMN_PATTERNS) {
+        if (pattern.test(normalized)) {
+            return role;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=synonyms.js.map

package/dist/interpret/synonyms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synonyms.js","sourceRoot":"","sources":["../../src/interpret/synonyms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgC;IAC1D,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACjC,CAAC,MAAM,EAAE,yCAAyC,CAAC;IACnD,CAAC,MAAM,EAAE,sBAAsB,CAAC;IAChC;QACE,MAAM;QACN,oEAAoE;KACrE;IACD,CAAC,MAAM,EAAE,qBAAqB,CAAC;IAC/B,CAAC,aAAa,EAAE,4DAA4D,CAAC;IAC7E,CAAC,OAAO,EAAE,wBAAwB,CAAC;IACnC,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAClC,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAC9B,CAAC,QAAQ,EAAE,2CAA2C,CAAC;IACvD,CAAC,KAAK,EAAE,oDAAoD,CAAC;CAC9D,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,eAAe,EAAE,CAAC;QAC9C,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/interpret/validate.d.ts

@@ -0,0 +1,27 @@
+import type { StatementTransaction } from './rows.js';
+export type ValidationStatus = 'passed' | 'failed' | 'skipped';
+export type Validation = {
+    status: ValidationStatus;
+    /** Row order the balance column implies, when it could be determined. */
+    order?: 'ascending' | 'descending';
+    /** Number of consecutive pairs checked. */
+    checked: number;
+    matched: number;
+    issues: string[];
+};
+/**
+ * Verify parsed amounts against the statement's running balance.
+ *
+ * Almost every Indian statement carries a closing-balance column, which makes
+ * the parse self-checkable: each transaction must equal the change in balance
+ * it caused. This is the difference between "the numbers look plausible" and
+ * "the numbers are provably right", and it catches precisely the failure modes
+ * of geometric PDF extraction — inverted debit/credit signs, dropped rows, and
+ * columns read one position across.
+ *
+ * Statements come in both date orders, so both interpretations are scored and
+ * the better one wins:
+ *   ascending  (oldest first): amount[i] === balance[i] - balance[i-1]
+ *   descending (newest first): amount[i] === balance[i] - balance[i+1]
+ */
+export declare function validateBalances(transactions: StatementTransaction[]): Validation;