boa-statement-parser

A production-ready Node.js library and CLI for parsing Bank of America bank statement PDFs into clean, normalized, categorized JSON with full JSON Schema validation.


Features

- Multi-format support — Checking, savings, and credit card statements
- Batch processing — Process entire directories with smart deduplication
- 70+ categorization rules — Priority-ordered with confidence tiers
- ML categorization — Optional TensorFlow.js hybrid approach
- Channel detection — CHECKCARD, ATM, Zelle, Online Banking, etc.
- Multiple export formats — JSON, CSV, OFX
- Schema validation — AJV (Draft 2020-12) + Zod
- Integrations — Supabase persistence, Plaid live banking
- TypeScript-first — Full type safety with strict mode

Installation

``bash
npm install -g boa-statement-parser # global
npm install boa-statement-parser # local
`

Quick Start

`bash


Initialize project (creates .env, ML model, statements dir)

parse-boa init

Parse a single PDF

parse-boa ./statement.pdf --out result.json

Batch process a directory

parse-boa --inputDir ./statements --out result.json --verbose
`

`typescript
import { parseStatementFile } from 'boa-statement-parser';

const result = await parseStatementFile('./statement.pdf', {
strict: true,
verbose: false,
});
console.log(result.statement.transactions);
`

Documentation

| Guide | Description |
|-------|-------------|
| CLI Reference | All commands, options, and usage examples |
| Programmatic Usage | Library API, advanced usage, and code examples |
| Output Schema | JSON schema structure, v1/v2 versioning, deduplication |
| Categorization | Rule-based and ML categorization, training |
| Channels & References | Transaction channel types and bank reference extraction |
| Recurring Transactions | Subscription and recurring payment detection |
| Export Formats | CSV and OFX export details |
| Supabase Integration | Database storage, analytics views, RLS |
| Plaid Integration | Live banking sync, reconciliation, webhooks |
| Environment Variables | All configuration options |
| Architecture | Project structure, parsing pipeline, extensibility |

Development

`bash
pnpm build # Build
pnpm test # Run all tests
pnpm test:watch # Watch mode
pnpm test:coverage # With coverage
pnpm lint # Check for issues
pnpm lint:fix # Auto-fix
pnpm format # Format with Prettier
`

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run pnpm lint && pnpm test`
5. Submit a pull request