🏦 VaultParser — Pure Rust Bank Statement Extractor

VaultParser is a high-performance, secure, offline-only library and interactive web service built in pure Rust for extracting tabular transaction ledgers from PDF bank statements.

It is designed to be 100% Python-free, utilizing native Rust parsers and coordinate-clustering engines to process PDF structures with zero external runtimes (including native support for decrypting AES-256 encrypted PDFs with empty passwords using lopdf 0.39.0).

🚀 Key Features

📦 Native Rust Library: Can be integrated directly into other Rust applications.
🛠️ Builder-Pattern Configurations: Programmatic setup of column boundaries, row tolerance margins, page trimming, and transaction row filters.
🏦 Indian Bank Presets: Out-of-the-box templates for:
- HDFC Bank
- State Bank of India (SBI)
- Canara Bank
- Union Bank of India
- UCO Bank
- Indian Bank
- H P State Co-operative Bank (HPSCB)
- ICICI Bank
- Punjab National Bank (PNB)
- Kotak Mahindra Bank
- Axis Bank
- Bank of Baroda (BOB)
- YES Bank
- IDFC FIRST Bank
- IndusInd Bank
✨ Interactive Web UI: Includes a web-based visual dashboard where you can:
- Drag, double-click to add, or right-click to delete vertical column guides over the PDF canvas.
- Crop header/footer regions in real-time.
- Directly override cell values or delete rows with coordinates that persist across exports.
- Instant Copy TSV to Clipboard for pasting directly into Excel / Google Sheets.
💾 Multi-format Exporters: Bulk compile transaction history to .xlsx (Excel), .csv, .tsv, or .json.
⚡ Batch Processing & Format Override: Process whole directories of PDF statements in batch mode or force export formats using --format / -f.

📂 Project Structure

├── src/
│   ├── lib.rs          # Core library entry point
│   ├── config.rs       # Extraction parameter builder (ExtractionConfig)
│   ├── presets.rs      # Native bank column coordinate templates
│   ├── parser.rs       # Core Y-coordinate clustering engine
│   ├── models.rs       # Word, Row, and Table structures
│   ├── exporter.rs     # CSV, TSV, XLSX & JSON exporting utilities
│   ├── error.rs        # Custom library error handling
│   ├── main.rs         # Local web UI server binary
│   └── bin/
│       └── vpcli.rs    # Command line tool binary (supports batch mode & --format)
├── static/             # Frontend assets (HTML, style.css, app.js, pdf.js)
├── temp/               # Temporary parsing folder (automatically cleaned up)
└── Cargo.toml          # Cargo package file

📖 Library Usage Example

Add the library to your own Rust application to parse statements programmatically:

use vaultparser::{ExtractionConfig, BankPreset, extract_from_file};
use vaultparser::exporter::export_to_csv;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Load HDFC preset column coordinates
    let config = BankPreset::Hdfc.config();

    // 2. Natively extract tabular data from statement
    let table = extract_from_file("statement.pdf", &config)?;
    println!("Parsed {} transaction rows!", table.rows.len());

    // 3. Export ledger to CSV bytes
    let csv_bytes = export_to_csv(&table)?;
    std::fs::write("statement_ledger.csv", csv_bytes)?;

    Ok(())
}

💻 Running the CLI Tool

You can run the extraction directly from the command line without opening a browser. The CLI utilizes clap for command-line parsing and option handling:

# Print results to stdout (default CSV, or use -f tsv / -f json):

cargo run --release --bin vpcli -- <input-pdf> <bank-preset> [options]


# Save CSV, TSV, Excel (.xlsx), or JSON results directly to a file:

cargo run --release --bin vpcli -- <input-pdf> <bank-preset> [output-file] [options]


# Batch process an entire folder of PDF statements:

cargo run --release --bin vpcli -- <input-dir> <bank-preset> --format tsv --output <output-dir>

Examples:

# Output HDFC statement directly to stdout as TSV

cargo run --release --bin vpcli -- "hdfc bank.pdf" hdfc -f tsv


# Save Union Bank statement output to statement.tsv

cargo run --release --bin vpcli -- "statement.pdf" union output.tsv


# Save Union Bank statement output directly to Excel

cargo run --release --bin vpcli -- "statement.pdf" union output.xlsx


# Auto-detect bank preset, decrypt with password, and save output

cargo run --release --bin vpcli -- secure_statement.pdf auto output.csv --password "secret123"


# Batch process a folder of PDFs into TSV format

cargo run --release --bin vpcli -- ./statements/ sbi -f tsv --output ./converted/

🏃 Running the Web UI

Make sure you have the Rust toolchain installed.
Start the local server:
```
cargo run --release
```
Open your browser and navigate to: http://localhost:8000/

📋 Step-by-Step Usage Guide

A. Using the Web Dashboard (Interactive Visual Extraction)

Upload Statement: Drag and drop your PDF bank statement into the upload zone.
Apply Preset: Select your bank (e.g. HDFC Bank) from the Preset Selector dropdown. The vertical column guides will automatically overlay on the PDF preview.
Refine Columns:
- Move: Drag existing vertical red lines to match the statement's columns.
- Add: Double-click anywhere on the PDF canvas to add a new vertical guide.
- Remove: Right-click on any guide to delete it.
Trim Headers & Footers: Adjust the Top Trim and Bottom Trim slider percentages to exclude running page headers, summaries, or footers.
Review & Override Data:
- Edit cells: Double-click any cell in the live preview table to correct typos.
- Delete rows: Click the red ✕ on any row to delete headers or background noise.
- Note: Manual edits are locked to PDF coordinates and persist when you switch pages or export!
Download Ledger: Click Export to Excel (.xlsx) or Export to CSV to save the formatted ledger.

B. Integrating the Rust Library in Your Code

Add Cargo Dependency: Add vaultparser to your project's Cargo.toml. To include the visual Web UI server and its async framework dependencies, enable the optional web feature:
```
 [dependencies]

 vaultparser = "0.2.5"

 # Or with the optional web UI:

 # vaultparser = { version = "0.2.5", features = ["web"] }
```

Define Configuration: Use pre-configured bank presets or customize via the builder pattern (which returns a Result for validation since v0.1.6):

// Option A: Using a pre-configured bank preset
let config = vaultparser::BankPreset::Hdfc.config();

// Option B: Custom configuration with validation
let config = vaultparser::ExtractionConfig::builder()
    .col_guides(vec![0.11, 0.42, 0.52, 0.62, 0.75, 0.88])
    .col_mappings(vec![
        "date".to_string(),
        "description".to_string(),
        "reference".to_string(),
        "skip".to_string(),
        "debit".to_string(),
        "credit".to_string(),
        "balance".to_string(),
    ])
    .y_top_trim(0.0)
    .y_bottom_trim(1.0)
    .build()?;

Run Extraction: Pass the PDF file path or byte buffer to the parser:

let table = vaultparser::extract_from_file("my_statement.pdf", &config)?;

Save Export: Output the transaction data directly:

let csv_data = vaultparser::exporter::export_to_csv(&table)?;
std::fs::write("statement.csv", csv_data)?;

🧪 Testing

To run the built-in unit and integration test suite:

cargo test -- --nocapture

This runs coordinate/amount parsing tests, an extraction check against the sample HDFC statement, and a full integration extraction check on the user's statement hdfc bank.pdf to verify native decryption.

🪵 Logging & Diagnostics

The library utilizes the standard tracing crate for diagnostic logging. Both the Web UI and CLI binaries are pre-configured to output formatted logs to stdout.

You can control the log verbosity using the RUST_LOG environment variable:

Show only start-up and high-level extraction counts (default):

# Windows PowerShell
$env:RUST_LOG="info"
cargo run --bin vpcli -- "hdfc bank.pdf" hdfc

# Linux/macOS

export RUST_LOG=info

cargo run --bin vpcli -- "hdfc bank.pdf" hdfc

Show page-by-page word counts and layout details (debug):

$env:RUST_LOG="debug"
cargo run --bin vpcli -- "hdfc bank.pdf" hdfc

🛡️ License

Distributed under the GNU Affero General Public License v3.0 (AGPL-3.0). Offline-only, secure, and private by design.

vaultparser 0.3.0