@krizpoon/hangseng-statement-extractor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# Hang Seng Statement Extractor
+
+Extract transaction history from Hang Seng Bank statement PDFs using a small TypeScript library and a CLI. The core extractor is importable for use in other projects, and the CLI is a thin wrapper around it.
+
+## Features
+- Extracts transactions from statement PDFs with position-aware parsing.
+- Works as both a library and a CLI.
+- Outputs CSV with statement date and account type included.
+
+## Requirements
+- Node.js 18+ (ESM).
+- Python 3 with `pdfminer.six` installed:
+  - `pip install pdfminer.six`
+
+## Install
+```bash
+npm install hangseng-statement-extractor
+```
+
+## CLI
+The CLI requires all paths to be provided explicitly.
+
+```bash
+hangseng-statement-extractor \
+  --input /path/to/statement.pdf \
+  --account savings \
+  --output /path/to/output.csv
+```
+
+Process a directory of PDFs:
+```bash
+hangseng-statement-extractor \
+  --input /path/to/statements/ \
+  --account savings \
+  --output /path/to/output.csv
+```
+
+Notes:
+- `--output` is optional; if omitted, CSV is printed to stdout.
+- `--account` accepts `savings` or `current`.
+
+## Library Usage
+```ts
+import { extractStatement, formatTransactionsAsCsv } from "hangseng-statement-extractor"
+import { fileURLToPath } from "node:url"
+import { dirname, join } from "node:path"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const pdfPath = "/path/to/statement.pdf"
+const pythonPath = "/usr/bin/python3"
+const scriptPath = join(
+  here,
+  "../node_modules/hangseng-statement-extractor/scripts/pdf-extract-positions.py",
+)
+
+const result = extractStatement({
+  pdfPath,
+  scriptPath,
+  pythonPath,
+  accountType: "savings",
+})
+
+const csv = formatTransactionsAsCsv([result])
+console.log(csv)
+```
+
+### API
+- `extractStatement(options)`
+  - `options.pdfPath` (string)
+  - `options.scriptPath` (string)
+  - `options.pythonPath` (string)
+  - `options.accountType` ("savings" | "current")
+  - `options.logger` (optional)
+  - Returns `{ statementDate, accountType, transactions }`
+
+- `formatTransactionsAsCsv(results)`
+  - Accepts an array of statement results and returns CSV text.
+
+## CSV Output
+Columns:
+```
+Date,Details,Deposit,Withdrawal,Balance,Account Type,Statement Date
+```
+
+## Development
+```bash
+npm install
+npm run build
+```
+
+## License
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { Option, program } from "commander";
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { extractStatement, formatTransactionsAsCsv } from "./index.js";
+const execFileAsync = promisify(execFile);
+const SCRIPT_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts", "pdf-extract-positions.py");
+async function findPython() {
+    for (const candidate of ["python3", "python"]) {
+        try {
+            await execFileAsync(candidate, ["--version"]);
+            return candidate;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    throw new Error("Python not found. Install Python or specify its path with --python.");
+}
+function collectPdfFiles(inputPath) {
+    const stat = fs.statSync(inputPath);
+    if (stat.isDirectory()) {
+        return fs
+            .readdirSync(inputPath)
+            .filter((file) => file.toLowerCase().endsWith(".pdf"))
+            .map((file) => path.join(inputPath, file))
+            .sort();
+    }
+    return [inputPath];
+}
+program
+    .name("hangseng-statement-extractor")
+    .description("Extract transaction history from Hang Seng Bank statement PDFs")
+    .requiredOption("-i, --input <path>", "Input PDF file or directory containing PDFs")
+    .option("--python <path>", "Path to python executable")
+    .option("-o, --output <path>", "Output CSV file (prints to stdout if omitted)")
+    .addOption(new Option("-a, --account <type>", "Account type to extract: savings or current")
+    .choices(["savings", "current"])
+    .default("savings"))
+    .option("-v, --verbose", "Enable verbose logging")
+    .action(async (options) => {
+    const inputPath = path.resolve(options.input);
+    const scriptPath = SCRIPT_PATH;
+    const pythonPath = options.python
+        ? path.resolve(options.python)
+        : await findPython();
+    const logger = options.verbose ? console : undefined;
+    const pdfFiles = collectPdfFiles(inputPath);
+    if (pdfFiles.length === 0) {
+        console.error("No PDF files found");
+        process.exitCode = 1;
+        return;
+    }
+    const results = [];
+    let errorCount = 0;
+    for (const pdfFile of pdfFiles) {
+        if (options.verbose) {
+            console.error(`Processing: ${path.basename(pdfFile)}`);
+        }
+        try {
+            const result = await extractStatement({
+                pdfPath: pdfFile,
+                scriptPath,
+                pythonPath,
+                accountType: options.account,
+                logger,
+            });
+            results.push(result);
+        }
+        catch (error) {
+            errorCount += 1;
+            console.error(`Error processing ${pdfFile}:`, error);
+        }
+    }
+    if (results.length === 0) {
+        console.error("No transactions extracted");
+        process.exitCode = 1;
+        return;
+    }
+    const csv = formatTransactionsAsCsv(results);
+    if (options.output) {
+        fs.writeFileSync(options.output, `${csv}\n`);
+        console.error(`Output written to: ${options.output}`);
+    }
+    else {
+        process.stdout.write(`${csv}\n`);
+    }
+    if (errorCount > 0) {
+        process.exitCode = 1;
+    }
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { extractStatement } from "./lib/extractor.js";
+export { formatTransactionsAsCsv } from "./lib/csv.js";
+export type { AccountType, Logger, StatementResult, TextElement, Transaction, } from "./lib/types.js";
+export type { ExtractStatementOptions } from "./lib/extractor.js";
+export type { PdfMinerOptions } from "./lib/pdfminer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EACV,WAAW,EACX,MAAM,EACN,eAAe,EACf,WAAW,EACX,WAAW,GACZ,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AACjE,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { extractStatement } from "./lib/extractor.js";
+export { formatTransactionsAsCsv } from "./lib/csv.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA"}

package/dist/lib/csv.d.ts

@@ -0,0 +1,3 @@
+import { StatementResult } from "./types.js";
+export declare function formatTransactionsAsCsv(results: StatementResult[]): string;
+//# sourceMappingURL=csv.d.ts.map

package/dist/lib/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/lib/csv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAS5C,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAuB1E"}

package/dist/lib/csv.js

@@ -0,0 +1,23 @@
+function escapeCsvField(value) {
+    if (value.includes('"') || value.includes(",") || value.includes("\n")) {
+        return `"${value.replace(/\"/g, '""')}"`;
+    }
+    return value;
+}
+export function formatTransactionsAsCsv(results) {
+    const header = "Date,Details,Deposit,Withdrawal,Balance,Account Type,Statement Date";
+    const rows = [];
+    for (const result of results) {
+        for (const transaction of result.transactions) {
+            const deposit = transaction.deposit !== null ? transaction.deposit.toFixed(2) : "";
+            const withdrawal = transaction.withdrawal !== null ? transaction.withdrawal.toFixed(2) : "";
+            const balance = transaction.balance.toFixed(2);
+            const details = escapeCsvField(transaction.details);
+            const accountType = result.accountType;
+            const statementDate = escapeCsvField(result.statementDate);
+            rows.push(`${transaction.date},${details},${deposit},${withdrawal},${balance},${accountType},${statementDate}`);
+        }
+    }
+    return [header, ...rows].join("\n");
+}
+//# sourceMappingURL=csv.js.map

package/dist/lib/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.js","sourceRoot":"","sources":["../../src/lib/csv.ts"],"names":[],"mappings":"AAEA,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAA;IAC1C,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAA0B;IAChE,MAAM,MAAM,GACV,qEAAqE,CAAA;IACvE,MAAM,IAAI,GAAa,EAAE,CAAA;IAEzB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YAC9C,MAAM,OAAO,GACX,WAAW,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;YACpE,MAAM,UAAU,GACd,WAAW,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;YAC1E,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;YAC9C,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;YACnD,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAA;YACtC,MAAM,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,aAAa,CAAC,CAAA;YAE1D,IAAI,CAAC,IAAI,CACP,GAAG,WAAW,CAAC,IAAI,IAAI,OAAO,IAAI,OAAO,IAAI,UAAU,IAAI,OAAO,IAAI,WAAW,IAAI,aAAa,EAAE,CACrG,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACrC,CAAC"}

package/dist/lib/extractor.d.ts

@@ -0,0 +1,8 @@
+import { PdfMinerOptions } from "./pdfminer.js";
+import { AccountType, Logger, StatementResult } from "./types.js";
+export interface ExtractStatementOptions extends PdfMinerOptions {
+    accountType: AccountType;
+    logger?: Logger;
+}
+export declare function extractStatement(options: ExtractStatementOptions): Promise<StatementResult>;
+//# sourceMappingURL=extractor.d.ts.map

package/dist/lib/extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/lib/extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,eAAe,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,WAAW,EAAE,WAAW,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

package/dist/lib/extractor.js

@@ -0,0 +1,14 @@
+import { extractTextElements } from "./pdfminer.js";
+import { findStatementDate, formatDateIso, parseTransactions } from "./parser.js";
+export async function extractStatement(options) {
+    const elements = await extractTextElements(options);
+    const statementDateRaw = findStatementDate(elements);
+    const statementDate = formatDateIso(statementDateRaw);
+    const transactions = parseTransactions(elements, options.accountType, statementDateRaw, options.logger);
+    return {
+        statementDate,
+        accountType: options.accountType,
+        transactions,
+    };
+}
+//# sourceMappingURL=extractor.js.map

package/dist/lib/extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.js","sourceRoot":"","sources":["../../src/lib/extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAmB,MAAM,eAAe,CAAA;AAEpE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAOjF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;IACnD,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAA;IACpD,MAAM,aAAa,GAAG,aAAa,CAAC,gBAAgB,CAAC,CAAA;IACrD,MAAM,YAAY,GAAG,iBAAiB,CACpC,QAAQ,EACR,OAAO,CAAC,WAAW,EACnB,gBAAgB,EAChB,OAAO,CAAC,MAAM,CACf,CAAA;IAED,OAAO;QACL,aAAa;QACb,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,YAAY;KACb,CAAA;AACH,CAAC"}

package/dist/lib/parser.d.ts

@@ -0,0 +1,5 @@
+import { AccountType, Logger, TextElement, Transaction } from "./types.js";
+export declare function formatDateIso(dateStr: string): string;
+export declare function findStatementDate(elements: TextElement[]): string;
+export declare function parseTransactions(elements: TextElement[], accountType: AccountType, statementDate: string, logger?: Logger): Transaction[];
+//# sourceMappingURL=parser.d.ts.map

package/dist/lib/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/lib/parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAmD1E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKrD;AAsHD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,CAgBjE;AAuDD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EAAE,EACvB,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,EAAE,CA4Ff"}

package/dist/lib/parser.js

@@ -0,0 +1,248 @@
+const MONTHS = {
+    Jan: 1, Feb: 2, Mar: 3, Apr: 4, May: 5, Jun: 6,
+    Jul: 7, Aug: 8, Sep: 9, Oct: 10, Nov: 11, Dec: 12,
+};
+function parseStatementDate(statementDate) {
+    const match = statementDate.match(/^(\d{1,2})\s+(\w{3})\s+(\d{4})$/);
+    if (!match) {
+        throw new Error(`Invalid statement date format: "${statementDate}"`);
+    }
+    const day = Number.parseInt(match[1], 10);
+    const month = MONTHS[match[2]];
+    const year = Number.parseInt(match[3], 10);
+    if (!month) {
+        throw new Error(`Unknown month in statement date: "${match[2]}"`);
+    }
+    return { year, month, day };
+}
+function resolveTransactionDate(shortDate, stmtYear, stmtMonth, stmtDay) {
+    const match = shortDate.match(/^(\d{1,2})\s+(\w{3})$/);
+    if (!match) {
+        throw new Error(`Invalid transaction date format: "${shortDate}"`);
+    }
+    const txDay = Number.parseInt(match[1], 10);
+    const txMonth = MONTHS[match[2]];
+    if (!txMonth) {
+        throw new Error(`Unknown month in transaction date: "${match[2]}"`);
+    }
+    // Assign the statement's year, then check if the date falls after the statement date.
+    // If so, the transaction must belong to the previous year (year boundary crossing).
+    let txYear = stmtYear;
+    const txNumeric = txYear * 10000 + txMonth * 100 + txDay;
+    const stmtNumeric = stmtYear * 10000 + stmtMonth * 100 + stmtDay;
+    if (txNumeric > stmtNumeric) {
+        txYear -= 1;
+    }
+    const mm = String(txMonth).padStart(2, "0");
+    const dd = String(txDay).padStart(2, "0");
+    return `${txYear}-${mm}-${dd}`;
+}
+export function formatDateIso(dateStr) {
+    const { year, month, day } = parseStatementDate(dateStr);
+    const mm = String(month).padStart(2, "0");
+    const dd = String(day).padStart(2, "0");
+    return `${year}-${mm}-${dd}`;
+}
+const COLUMNS = {
+    DATE: { min: 55, max: 105 },
+    DETAILS: { min: 105, max: 345 },
+    DEPOSIT: { min: 345, max: 420 },
+    WITHDRAWAL: { min: 420, max: 490 },
+    BALANCE: { min: 490, max: 550 },
+};
+function parseNumber(str) {
+    if (!str || str.trim() === "")
+        return null;
+    const cleaned = str.replace(/,/g, "").trim();
+    const num = Number.parseFloat(cleaned);
+    return Number.isNaN(num) ? null : num;
+}
+function detectColumn(x0) {
+    if (x0 >= COLUMNS.DATE.min && x0 < COLUMNS.DATE.max)
+        return "date";
+    if (x0 >= COLUMNS.DETAILS.min && x0 < COLUMNS.DETAILS.max)
+        return "details";
+    if (x0 >= COLUMNS.DEPOSIT.min && x0 < COLUMNS.DEPOSIT.max)
+        return "deposit";
+    if (x0 >= COLUMNS.WITHDRAWAL.min && x0 < COLUMNS.WITHDRAWAL.max)
+        return "withdrawal";
+    if (x0 >= COLUMNS.BALANCE.min && x0 < COLUMNS.BALANCE.max)
+        return "balance";
+    return null;
+}
+function groupIntoRows(elements) {
+    const rows = new Map();
+    const tolerance = 2;
+    for (const el of elements) {
+        let rowY = null;
+        for (const y of rows.keys()) {
+            if (Math.abs(y - el.y0) <= tolerance) {
+                rowY = y;
+                break;
+            }
+        }
+        if (rowY !== null) {
+            rows.get(rowY).push(el);
+        }
+        else {
+            rows.set(el.y0, [el]);
+        }
+    }
+    return rows;
+}
+function groupIntoRowsArray(elements) {
+    const rowMap = groupIntoRows(elements);
+    const sortedYs = Array.from(rowMap.keys()).sort((a, b) => a - b);
+    return sortedYs.map((y) => rowMap.get(y));
+}
+function parseRow(elements) {
+    const row = {
+        date: null,
+        details: null,
+        deposit: null,
+        withdrawal: null,
+        balance: null,
+    };
+    elements.sort((a, b) => a.x0 - b.x0);
+    for (const el of elements) {
+        const col = detectColumn(el.x0);
+        const text = el.text.trim();
+        switch (col) {
+            case "date":
+                row.date = text;
+                break;
+            case "details":
+                row.details = text;
+                break;
+            case "deposit":
+                row.deposit = parseNumber(text);
+                break;
+            case "withdrawal":
+                row.withdrawal = parseNumber(text);
+                break;
+            case "balance":
+                row.balance = parseNumber(text);
+                break;
+        }
+    }
+    return row;
+}
+function findElementWithText(elements, text, startPage = 0, startY = 0) {
+    return (elements.find((el) => (el.page > startPage || (el.page === startPage && el.y0 >= startY)) &&
+        el.text.includes(text)) || null);
+}
+export function findStatementDate(elements) {
+    for (const el of elements) {
+        if (el.text.match(/^\d{1,2}\s+\w{3}\s+\d{4}$/)) {
+            const prevEl = elements.find((e) => e.page === el.page &&
+                Math.abs(e.y0 - el.y0) < 3 &&
+                e.text.includes("Statement Date"));
+            if (prevEl) {
+                return el.text;
+            }
+        }
+    }
+    return "Unknown";
+}
+function findTransactionsSection(elements, accountType) {
+    const start = findElementWithText(elements, accountType === "savings"
+        ? "Integrated Account Statement Savings"
+        : "Integrated Account Current");
+    if (!start)
+        return { start: null, end: null };
+    const rowStart = findElementWithText(elements, "DR=Debit", start.page, start.y1);
+    if (!rowStart)
+        return { start: null, end: null };
+    const end = findElementWithText(elements, "Transaction Summary", rowStart.page, rowStart.y1);
+    if (!end)
+        return { start: null, end: null };
+    return {
+        start: {
+            page: rowStart.page,
+            y0: rowStart.y1,
+        },
+        end: {
+            page: end.page,
+            y0: end.y0,
+        },
+    };
+}
+function getElementsInSection(start, end, elements) {
+    return elements.filter((el) => {
+        if (el.page < start.page || el.page > end.page)
+            return false;
+        if (el.page === start.page && el.y0 < start.y0)
+            return false;
+        if (el.page === end.page && el.y0 >= end.y0)
+            return false;
+        return true;
+    });
+}
+export function parseTransactions(elements, accountType, statementDate, logger) {
+    const stmt = parseStatementDate(statementDate);
+    const { start, end } = findTransactionsSection(elements, accountType);
+    if (!start || !end) {
+        throw new Error("Could not find transactions section in PDF");
+    }
+    logger?.debug?.(`Transaction section: start page ${start.page} y ${start.y0}, end page ${end.page} y ${end.y0}`);
+    const sectionElements = getElementsInSection(start, end, elements);
+    const rows = groupIntoRowsArray(sectionElements);
+    let openingBalance = null;
+    let lastDate = "";
+    const desc = [];
+    const transactions = [];
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        const parsedRow = parseRow(row);
+        const date = parsedRow.date ?? lastDate;
+        if (parsedRow.date) {
+            lastDate = parsedRow.date;
+        }
+        if (parsedRow.deposit !== null || parsedRow.withdrawal !== null) {
+            if (!date) {
+                throw new Error(`Could not determine date for transaction at row ${i + 1}`);
+            }
+            if (openingBalance === null) {
+                throw new Error(`Transaction found before opening balance at row ${i + 1}`);
+            }
+            const previousTransaction = transactions[transactions.length - 1];
+            const previousBalance = previousTransaction
+                ? previousTransaction.balance
+                : openingBalance;
+            const balance = parsedRow.balance ??
+                previousBalance + (parsedRow.deposit ?? 0) - (parsedRow.withdrawal ?? 0);
+            if (parsedRow.balance !== null && balance !== parsedRow.balance) {
+                throw new Error(`Balance mismatch at row ${i + 1}: calculated ${balance}, found ${parsedRow.balance}`);
+            }
+            const details = [...desc, parsedRow.details ?? ""].join(" ").trim();
+            desc.length = 0;
+            transactions.push({
+                date: resolveTransactionDate(date, stmt.year, stmt.month, stmt.day),
+                details,
+                deposit: parsedRow.deposit,
+                withdrawal: parsedRow.withdrawal,
+                balance,
+            });
+        }
+        else {
+            if (!parsedRow.details) {
+                throw new Error(`Found non-transaction row without details at row ${i + 1}`);
+            }
+            if (parsedRow.details === "B/F BALANCE") {
+                if (parsedRow.balance === null) {
+                    throw new Error(`Opening balance row missing balance amount at row ${i + 1}`);
+                }
+                if (transactions.length > 0) {
+                    throw new Error(`Opening balance row found after transactions at row ${i + 1}`);
+                }
+                logger?.debug?.(`Opening balance detected: ${parsedRow.balance}`);
+                openingBalance = parsedRow.balance;
+            }
+            else {
+                desc.push(parsedRow.details.trim());
+            }
+        }
+    }
+    return transactions;
+}
+//# sourceMappingURL=parser.js.map

package/dist/lib/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/lib/parser.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAA2B;IACrC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;IAC9C,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE;CAClD,CAAA;AAED,SAAS,kBAAkB,CAAC,aAAqB;IAC/C,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAA;IACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,mCAAmC,aAAa,GAAG,CAAC,CAAA;IACtE,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAA;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAA;IAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAA;IAC3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,qCAAqC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACnE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AAC7B,CAAC;AAED,SAAS,sBAAsB,CAC7B,SAAiB,EACjB,QAAgB,EAChB,SAAiB,EACjB,OAAe;IAEf,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAA;IACtD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,qCAAqC,SAAS,GAAG,CAAC,CAAA;IACpE,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAA;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAA;IACjC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uCAAuC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACrE,CAAC;IAED,sFAAsF;IACtF,oFAAoF;IACpF,IAAI,MAAM,GAAG,QAAQ,CAAA;IACrB,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,GAAG,GAAG,KAAK,CAAA;IACxD,MAAM,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,GAAG,GAAG,OAAO,CAAA;IAChE,IAAI,SAAS,GAAG,WAAW,EAAE,CAAC;QAC5B,MAAM,IAAI,CAAC,CAAA;IACb,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAC3C,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACzC,OAAO,GAAG,MAAM,IAAI,EAAE,IAAI,EAAE,EAAE,CAAA;AAChC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IACxD,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACzC,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACvC,OAAO,GAAG,IAAI,IAAI,EAAE,IAAI,EAAE,EAAE,CAAA;AAC9B,CAAC;AAED,MAAM,OAAO,GAAG;IACd,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE;IAC3B,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;IAC/B,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;IAC/B,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;IAClC,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;CAChC,CAAA;AAUD,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IAC1C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;IACtC,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA;AACvC,CAAC;AAED,SAAS,YAAY,CACnB,EAAU;IAEV,IAAI,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAA;IAClE,IAAI,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG;QAAE,OAAO,SAAS,CAAA;IAC3E,IAAI,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG;QAAE,OAAO,SAAS,CAAA;IAC3E,IAAI,EAAE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG;QAC7D,OAAO,YAAY,CAAA;IACrB,IAAI,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG;QAAE,OAAO,SAAS,CAAA;IAC3E,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,aAAa,CAAC,QAAuB;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAA;IAC7C,MAAM,SAAS,GAAG,CAAC,CAAA;IAEnB,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,IAAI,GAAkB,IAAI,CAAA;QAC9B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;gBACrC,IAAI,GAAG,CAAC,CAAA;gBACR,MAAK;YACP,CAAC;QACH,CAAC;QAED,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC1B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QACvB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,kBAAkB,CAAC,QAAuB;IACjD,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;IACtC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IAChE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAA;AAC5C,CAAC;AAED,SAAS,QAAQ,CAAC,QAAuB;IACvC,MAAM,GAAG,GAAY;QACnB,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,IAAI;QAChB,OAAO,EAAE,IAAI;KACd,CAAA;IAED,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAA;IAEpC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;QAC/B,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;QAE3B,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,MAAM;gBACT,GAAG,CAAC,IAAI,GAAG,IAAI,CAAA;gBACf,MAAK;YACP,KAAK,SAAS;gBACZ,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;gBAClB,MAAK;YACP,KAAK,SAAS;gBACZ,GAAG,CAAC,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;gBAC/B,MAAK;YACP,KAAK,YAAY;gBACf,GAAG,CAAC,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;gBAClC,MAAK;YACP,KAAK,SAAS;gBACZ,GAAG,CAAC,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;gBAC/B,MAAK;QACT,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,mBAAmB,CAC1B,QAAuB,EACvB,IAAY,EACZ,SAAS,GAAG,CAAC,EACb,MAAM,GAAG,CAAC;IAEV,OAAO,CACL,QAAQ,CAAC,IAAI,CACX,CAAC,EAAE,EAAE,EAAE,CACL,CAAC,EAAE,CAAC,IAAI,GAAG,SAAS,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,CAAC,EAAE,IAAI,MAAM,CAAC,CAAC;QACnE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CACzB,IAAI,IAAI,CACV,CAAA;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,2BAA2B,CAAC,EAAE,CAAC;YAC/C,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAC1B,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI;gBAClB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC;gBAC1B,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CACpC,CAAA;YACD,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,EAAE,CAAC,IAAI,CAAA;YAChB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,SAAS,uBAAuB,CAC9B,QAAuB,EACvB,WAAwB;IAExB,MAAM,KAAK,GAAG,mBAAmB,CAC/B,QAAQ,EACR,WAAW,KAAK,SAAS;QACvB,CAAC,CAAC,sCAAsC;QACxC,CAAC,CAAC,4BAA4B,CACjC,CAAA;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;IAE7C,MAAM,QAAQ,GAAG,mBAAmB,CAClC,QAAQ,EACR,UAAU,EACV,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,EAAE,CACT,CAAA;IACD,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;IAEhD,MAAM,GAAG,GAAG,mBAAmB,CAC7B,QAAQ,EACR,qBAAqB,EACrB,QAAQ,CAAC,IAAI,EACb,QAAQ,CAAC,EAAE,CACZ,CAAA;IACD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;IAE3C,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,EAAE,EAAE,QAAQ,CAAC,EAAE;SAChB;QACD,GAAG,EAAE;YACH,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,EAAE,EAAE,GAAG,CAAC,EAAE;SACX;KACF,CAAA;AACH,CAAC;AAED,SAAS,oBAAoB,CAC3B,KAAmC,EACnC,GAAiC,EACjC,QAAuB;IAEvB,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE;QAC5B,IAAI,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI;YAAE,OAAO,KAAK,CAAA;QAC5D,IAAI,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE;YAAE,OAAO,KAAK,CAAA;QAC5D,IAAI,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,CAAC,EAAE;YAAE,OAAO,KAAK,CAAA;QACzD,OAAO,IAAI,CAAA;IACb,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,QAAuB,EACvB,WAAwB,EACxB,aAAqB,EACrB,MAAe;IAEf,MAAM,IAAI,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAA;IAC9C,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,uBAAuB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;IACrE,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;IAC/D,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,CACb,mCAAmC,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,EAAE,cAAc,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,EAAE,CAChG,CAAA;IAED,MAAM,eAAe,GAAG,oBAAoB,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAA;IAClE,MAAM,IAAI,GAAG,kBAAkB,CAAC,eAAe,CAAC,CAAA;IAEhD,IAAI,cAAc,GAAkB,IAAI,CAAA;IACxC,IAAI,QAAQ,GAAG,EAAE,CAAA;IACjB,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,MAAM,YAAY,GAAkB,EAAE,CAAA;IAEtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAA;QACpB,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;QAE/B,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,IAAI,QAAQ,CAAA;QACvC,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;YACnB,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAA;QAC3B,CAAC;QAED,IAAI,SAAS,CAAC,OAAO,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAChE,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CACb,mDAAmD,CAAC,GAAG,CAAC,EAAE,CAC3D,CAAA;YACH,CAAC;YACD,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,mDAAmD,CAAC,GAAG,CAAC,EAAE,CAC3D,CAAA;YACH,CAAC;YAED,MAAM,mBAAmB,GAAG,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;YACjE,MAAM,eAAe,GAAG,mBAAmB;gBACzC,CAAC,CAAC,mBAAmB,CAAC,OAAO;gBAC7B,CAAC,CAAC,cAAc,CAAA;YAElB,MAAM,OAAO,GACX,SAAS,CAAC,OAAO;gBACjB,eAAe,GAAG,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC,CAAA;YAE1E,IAAI,SAAS,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;gBAChE,MAAM,IAAI,KAAK,CACb,2BAA2B,CAAC,GAAG,CAAC,gBAAgB,OAAO,WAAW,SAAS,CAAC,OAAO,EAAE,CACtF,CAAA;YACH,CAAC;YAED,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;YACnE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAA;YAEf,YAAY,CAAC,IAAI,CAAC;gBAChB,IAAI,EAAE,sBAAsB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC;gBACnE,OAAO;gBACP,OAAO,EAAE,SAAS,CAAC,OAAO;gBAC1B,UAAU,EAAE,SAAS,CAAC,UAAU;gBAChC,OAAO;aACR,CAAC,CAAA;QACJ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,oDAAoD,CAAC,GAAG,CAAC,EAAE,CAC5D,CAAA;YACH,CAAC;YAED,IAAI,SAAS,CAAC,OAAO,KAAK,aAAa,EAAE,CAAC;gBACxC,IAAI,SAAS,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;oBAC/B,MAAM,IAAI,KAAK,CACb,qDAAqD,CAAC,GAAG,CAAC,EAAE,CAC7D,CAAA;gBACH,CAAC;gBACD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CACb,uDAAuD,CAAC,GAAG,CAAC,EAAE,CAC/D,CAAA;gBACH,CAAC;gBACD,MAAM,EAAE,KAAK,EAAE,CAAC,6BAA6B,SAAS,CAAC,OAAO,EAAE,CAAC,CAAA;gBACjE,cAAc,GAAG,SAAS,CAAC,OAAO,CAAA;YACpC,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAA;AACrB,CAAC"}

package/dist/lib/pdfminer.d.ts

@@ -0,0 +1,8 @@
+import { TextElement } from "./types.js";
+export interface PdfMinerOptions {
+    pdfPath: string;
+    scriptPath: string;
+    pythonPath: string;
+}
+export declare function extractTextElements(options: PdfMinerOptions): Promise<TextElement[]>;
+//# sourceMappingURL=pdfminer.d.ts.map

package/dist/lib/pdfminer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdfminer.d.ts","sourceRoot":"","sources":["../../src/lib/pdfminer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAIxC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAO1F"}

package/dist/lib/pdfminer.js

@@ -0,0 +1,11 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function extractTextElements(options) {
+    const { stdout } = await execFileAsync(options.pythonPath, [options.scriptPath, options.pdfPath], {
+        encoding: "utf-8",
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return JSON.parse(stdout);
+}
+//# sourceMappingURL=pdfminer.js.map

package/dist/lib/pdfminer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdfminer.js","sourceRoot":"","sources":["../../src/lib/pdfminer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAGrC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;AAQzC,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAwB;IAChE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE;QAChG,QAAQ,EAAE,OAAO;QACjB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;KAC5B,CAAC,CAAA;IAEF,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAkB,CAAA;AAC5C,CAAC"}

package/dist/lib/types.d.ts

@@ -0,0 +1,28 @@
+export interface Transaction {
+    date: string;
+    details: string;
+    deposit: number | null;
+    withdrawal: number | null;
+    balance: number;
+}
+export interface TextElement {
+    page: number;
+    text: string;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+export type AccountType = "savings" | "current";
+export interface StatementResult {
+    statementDate: string;
+    accountType: AccountType;
+    transactions: Transaction[];
+}
+export interface Logger {
+    debug?: (message: string) => void;
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAA;AAE/C,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,WAAW,CAAA;IACxB,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAClC"}

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@krizpoon/hangseng-statement-extractor",
+  "version": "0.1.0",
+  "description": "Extract transaction history from Hang Seng Bank statement PDFs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "hangseng-statement-extractor": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "hang-seng",
+    "pdf",
+    "statement",
+    "banking",
+    "parser"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/pdf-extract-positions.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+Extract text with positions from a PDF file using pdfminer.
+Outputs JSON with text elements and their bounding boxes.
+"""
+
+import sys
+import json
+from pdfminer.high_level import extract_pages
+from pdfminer.layout import LTTextBoxHorizontal, LTTextLineHorizontal, LTChar, LAParams
+
+
+def extract_text_with_positions(pdf_path: str) -> list[dict]:
+    """Extract text elements with their positions from a PDF."""
+    elements = []
+
+    laparams = LAParams(
+        line_margin=0.3,  # Smaller margin to keep lines separate
+        word_margin=0.1,
+        char_margin=2.0,
+        boxes_flow=0.5,
+    )
+
+    for page_num, page_layout in enumerate(extract_pages(pdf_path, laparams=laparams)):
+        page_height = page_layout.height
+
+        for element in page_layout:
+            if isinstance(element, LTTextBoxHorizontal):
+                for line in element:
+                    if isinstance(line, LTTextLineHorizontal):
+                        text = line.get_text().strip()
+                        if text:
+                            # PDF coordinates have origin at bottom-left
+                            # Convert to top-left origin for easier processing
+                            elements.append({
+                                "page": page_num + 1,
+                                "text": text,
+                                "x0": round(line.x0, 2),
+                                "y0": round(page_height - line.y1, 2),  # Convert to top-left origin
+                                "x1": round(line.x1, 2),
+                                "y1": round(page_height - line.y0, 2),
+                            })
+
+    # Sort by page, then by y position (top to bottom), then by x position (left to right)
+    elements.sort(key=lambda e: (e["page"], e["y0"], e["x0"]))
+
+    return elements
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: pdf-extract-positions.py <pdf_path>", file=sys.stderr)
+        sys.exit(1)
+
+    pdf_path = sys.argv[1]
+
+    try:
+        elements = extract_text_with_positions(pdf_path)
+        print(json.dumps(elements, ensure_ascii=False, indent=2))
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()