# BAC Statement Tools

Tools for processing BAC Costa Rica credit card statement PDFs.

## Dependencies

- Python 3.10+
- pdfplumber (>=0.10.0)
- matplotlib (>=3.5.0) - optional, for graphs

## Extraction

Extract transactions from statement PDFs to JSON.

```bash
python bac_extract.py <pdf_file> [options]
```

**Options:**
- `-o, --output`: Output JSON path (default: transactions.json)
- `--pretty`: Pretty-print JSON output
- `-v, --verbose`: Enable debug logging

**Examples:**
```bash
python bac_extract.py statement.pdf --pretty
python bac_extract.py statement.pdf -o output.json -v
```

## Analysis

Analyze extracted transactions with category breakdowns and graphs.

```bash
python bac_analyze.py <json_files...> [options]
```

**Options:**
- `--graph {bar,pie,timeline,all}`: Generate graph(s)
- `-o, --output`: Output file for graph (default: spending_<type>.png)
- `--show`: Display graph interactively
- `--categories`: Custom categories file (default: categories.json)

**Examples:**
```bash
# Text summary
python bac_analyze.py transactions.json

# Analyze multiple statements
python bac_analyze.py *.json

# Generate all graphs
python bac_analyze.py *.json --graph all

# Generate bar chart with custom output
python bac_analyze.py *.json --graph bar -o spending.png

# Use custom categories
python bac_analyze.py *.json --categories my_categories.json
```

## Categories

Create a `categories.json` file to customize spending categories. Each category maps to a list of merchant name patterns (case-insensitive substring match).

```json
{
  "Groceries": ["SUPERMARKET", "WALMART", "FRESH MARKET"],
  "Gas": ["SERVICENTRO", "DELTA", "SHELL"],
  "Restaurants": ["RESTAURANT", "CAFE", "PIZZA", "SUSHI"],
  "Transportation": ["UBER", "TAXI", "PARKING"],
  "Entertainment": ["CINEMA", "NETFLIX", "STEAM"],
  "Utilities": ["ELECTRIC", "WATER", "INTERNET"],
  "Subscriptions": ["SPOTIFY", "YOUTUBE", "CHATGPT"]
}
```

Transactions not matching any pattern are categorized as "Other".

## Output Format

```json
{
  "metadata": {
    "source_file": "statement.pdf",
    "extraction_date": "2025-01-15T12:00:00Z",
    "statement_date": "2025-01-10",
    "total_transactions": 5
  },
  "card_holders": [
    {
      "card_suffix": "1234",
      "name": "CARD HOLDER NAME"
    }
  ],
  "purchases": [
    {
      "reference": "123456789012",
      "date": "2025-01-09",
      "description": "EXAMPLE STORE",
      "location": null,
      "currency": "CRC",
      "amount_crc": 1234.56,
      "amount_usd": null
    }
  ],
  "other_charges": [],
  "voluntary_services": [],
  "summary": {
    "purchases": { "total_crc": 50000.00, "total_usd": 0.00, "count": 5 },
    "other_charges": { "total_crc": 0.00, "total_usd": 0.00, "count": 0 },
    "voluntary_services": { "total_crc": 0.00, "total_usd": 0.00, "count": 0 }
  }
}
```