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

npm install @krizpoon/hangseng-statement-extractor

CLI

Run directly with npx (no install needed):

npx @krizpoon/hangseng-statement-extractor \
  --input /path/to/statement.pdf \
  --account savings \
  --output /path/to/output.csv

Process a directory of PDFs:

npx @krizpoon/hangseng-statement-extractor \
  --input /path/to/statements/ \
  --account savings \
  --output /path/to/output.csv

Options:

• --input (required) — PDF file or directory containing PDFs.
• --account — savings (default) or current.
• --output — Output CSV file. If omitted, CSV is printed to stdout.
• --python — Path to Python executable. Auto-detected if not specified.
• --verbose — Enable verbose logging.

Library Usage

import { extractStatement, formatTransactionsAsCsv } from "@krizpoon/hangseng-statement-extractor"

const result = await extractStatement({
  pdfPath: "/path/to/statement.pdf",
  scriptPath: "/path/to/pdf-extract-positions.py",
  pythonPath: "python3",
  accountType: "savings",
})

const csv = formatTransactionsAsCsv([result])
console.log(csv)

API

• extractStatement(options) — Returns Promise<StatementResult>

  • 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

npm install
npm run build

License

MIT