gmail2wallet

Personal finance automation tool that fetches bank transaction emails from Gmail, parses them, and auto-adds entries to Wallet by BudgetBakers via browser automation.

How It Works

Gmail API → fetch emails → detect bank → parse transaction → store in SQLite → sync to Wallet

1. Fetch — Connects to Gmail via OAuth2, fetches transaction alert emails using bank-specific labels
2. Parse — Detects bank from sender domain, extracts amount, merchant, date, and other details
3. Store — Deduplicates by Gmail message ID and saves to SQLite with Drizzle ORM
4. Sync — Opens Wallet in a headless browser (Playwright), logs in via Google, and fills the add-record form for each pending transaction

Supported Banks

Bank	Types
MTB (Mutual Trust Bank)	Card transactions, fund transfers
EBL (Eastern Bank Limited)	Card alerts, Skybanking transfers
BRAC Bank	Debit notifications
City Bank	ATM, deposits, card transactions, reversals

Prerequisites

• Bun runtime
• Google Cloud project with Gmail API enabled and OAuth 2.0 credentials
• Gmail labels set up for each bank (e.g., banking-mtb, banking-ebl)
• A Wallet account with Google Sign-in

Setup

1. Install dependencies

   bun install

2. Configure environment

   cp .env.example .env

   Fill in your Google OAuth credentials:

   GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your_client_secret
   OAUTH_PORT=8080
   

3. Initialize the database

   bun run db:push

4. Authenticate Gmail

   Run any fetch command — it will open a browser for OAuth consent on first run and save tokens to .tokens.json.

Usage

# Fetch and store bank emails (uses last sync date by default)
bun run fetch-all

# Fetch specific banks only
bun src/cli.ts fetch-all -b mtb,ebl

# Fetch with date range
bun src/cli.ts fetch-all --after 2024-01-01 --before 2024-12-31

# Sync pending transactions to Wallet
bun run wallet-sync

# Debug: fetch raw emails without parsing
bun run sync -q "label:banking-mtb" -n 5

# Debug: fetch and parse without saving to DB
bun run parse -q "label:banking-ebl"

Database Management

bun run db:push      # Apply schema migrations
bun run db:studio    # Open Drizzle Studio (visual DB browser)

Tech Stack

• Runtime: Bun + TypeScript
• Database: SQLite (bun:sqlite) + Drizzle ORM
• Gmail: googleapis (OAuth2, gmail.readonly scope)
• Wallet Automation: Playwright (persistent Chrome profile, Google Sign-in)
• CLI: Commander
• Validation: Zod

Adding a New Bank Parser

1. Create src/parsers/<bank>.ts exporting a function (EmailMessage) → ParsedTransaction | null
2. Add the bank name to the BankName enum in src/schemas/index.ts
3. Register the sender domain mapping in src/parsers/index.ts
4. Set up a Gmail label (banking-<bank>) and filter for the bank's notification emails

License

MIT