refund-radar

# refund-radar

Scan bank statements to detect recurring charges, flag suspicious transactions, identify duplicates and fees, draft refund request templates, and generate an interactive HTML audit report.

## Triggers

- "scan my bank statement for refunds"
- "analyze my credit card transactions"
- "find recurring charges in my statement"
- "check for duplicate or suspicious charges"
- "help me dispute a charge"
- "generate a refund request"
- "audit my subscriptions"

## Workflow

### 1. Get Transaction Data

Ask user for bank/card CSV export or pasted text. Common sources:

- Apple Card: Wallet → Card Balance → Export
- Chase: Accounts → Download activity → CSV
- Mint: Transactions → Export
- Any bank: Download as CSV from transaction history

Or accept pasted text format:
```
2026-01-03 Spotify -11.99 USD
2026-01-15 Salary +4500 USD
```

### 2. Parse and Normalize

Run the parser on their data:

```bash
python -m refund_radar analyze --csv statement.csv --month 2026-01
```

Or for pasted text:
```bash
python -m refund_radar analyze --stdin --month 2026-01 --default-currency USD
```

The parser auto-detects:
- Delimiter (comma, semicolon, tab)
- Date format (YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY)
- Amount format (single column or debit/credit)
- Currency

### 3. Review Recurring Charges

Tool identifies recurring subscriptions by:
- Same merchant >= 2 times in 90 days
- Similar amounts (within 5% or $2)
- Consistent cadence (weekly, monthly, yearly)
- Known subscription keywords (Netflix, Spotify, etc.)

Output shows:
- Merchant name
- Average amount and cadence
- Last charge date
- Next expected charge

### 4. Flag Suspicious Charges

Tool automatically flags:

| Flag Type | Trigger | Severity |
|-----------|---------|----------|
| Duplicate | Same merchant + amount within 2 days | HIGH |
| Amount Spike | > 1.8x baseline, delta > $25 | HIGH |
| New Merchant | First time + amount > $30 | MEDIUM |
| Fee-like | Keywords (FEE, ATM, OVERDRAFT) + > $3 | LOW |
| Currency Anomaly | Unusual currency or DCC | LOW |

### 5. Clarify with User

For flagged items, ask in batches of 5-10:

- Is this charge legitimate?
- Should I mark this merchant as expected?
- Do you want a refund template for this?

Update state based on answers:
```bash
python -m refund_radar mark-expected --merchant "Costco"
python -m refund_radar mark-recurring --merchant "Netflix"
```

### 6. Generate HTML Report

Report saved to `~/.refund_radar/reports/YYYY-MM.html`

Copy [template.html](assets/template.html) structure. Sections:
- **Summary**: Transaction count, total spent, recurring count, flagged count
- **Recurring Charges**: Table with merchant, amount, cadence, next expected
- **Unexpected Charges**: Flagged items with severity and reason
- **Duplicates**: Same-day duplicate charges
- **Fee-like Charges**: ATM fees, FX fees, service charges
- **Refund Templates**: Ready-to-copy email/chat/dispute messages

Features:
- Privacy toggle (blur merchant names)
- Dark/light mode
- Collapsible sections
- Copy buttons on templates
- Auto-hide empty sections

### 7. Draft Refund Requests

For each flagged charge, generate three template types:
- **Email**: Formal refund request
- **Chat**: Quick message for live support
- **Dispute**: Bank dispute form text

Three tone variants each:
- Concise (default)
- Firm (assertive)
- Friendly (polite)

Templates include:
- Merchant name and date
- Charge amount
- Dispute reason based on flag type
- Placeholders for card last 4, reference number

**Important**: No apostrophes in any generated text.

## CLI Reference

```bash
# Analyze statement
python -m refund_radar analyze --csv file.csv --month 2026-01

# Analyze from stdin
python -m refund_radar analyze --stdin --month 2026-01 --default-currency CHF

# Mark merchant as expected
python -m refund_radar mark-expected --merchant "Amazon"

# Mark merchant as recurring
python -m refund_radar mark-recurring --merchant "Netflix"

# List expected merchants
python -m refund_radar expected

# Reset learned state
python -m refund_radar reset-state

# Export month data
python -m refund_radar export --month 2026-01 --out data.json
```

## Files Written

| Path | Purpose |
|------|---------|
| `~/.refund_radar/state.json` | Learned preferences, merchant history |
| `~/.refund_radar/reports/YYYY-MM.html` | Interactive audit report |
| `~/.refund_radar/reports/YYYY-MM.json` | Raw analysis data |

## Privacy

- **No network calls.** Everything runs locally.
- **No external APIs.** No Plaid, no cloud services.
- **Your data stays on your machine.**
- **Privacy toggle in reports.** Blur merchant names with one click.

## Requirements

- Python 3.9+
- No external dependencies

## Repository

https://github.com/andreolf/refund-radar