FargoImport/README.md

# FargoImport extractor

This utility reads a HAR-style JSON file (for example `posted.dat`), scans:

- `log.entries[*].response.content.text`

It only processes text values that start with:

- `/*WellFargoProprietary%`

For each matching value, it extracts the JSON string between:

- start: `/*WellFargoProprietary%`
- end: `%WellFargoProprietary*/`

Then it parses that extracted string with Python `json.loads` and outputs the resulting Python objects.

## Run

```powershell
python .\main.py --input .\posted.dat
```

Optionally write extracted objects to a file:

```powershell
python .\main.py --input .\posted.dat --output .\extracted.json
```

Show parse/skip errors while extracting:

```powershell
python .\main.py --input .\posted.dat --show-errors
```

For HAR files where the payload is specifically at
`/log/entries/0/response/content/text`, use:

```powershell
python .\main.py --input .\checking.dat --entry0-only --output .\checking_extracted.json
```

## Programmatic usage

```python
from wf_debit_extractor import WellsFargoPayloadExtractor

extractor = WellsFargoPayloadExtractor()
objects = extractor.extract_from_file("posted.dat")

# For entry0-only HAR variants:
# objects = extractor.extract_from_file("checking.dat", entry0_only=True)

# Access converted Python objects.
print(len(objects))
print(extractor.get_objects()[0])

# Optional: review skipped/parse errors.
print(extractor.errors)
```

Legacy imports from `main` still work, but `wf_debit_extractor` is now the preferred module for programmatic use.

## Transaction Processing

Once you've extracted WellsFargo payloads, use `transaction_processor.py` to extract and transform transaction data.

```python
from transaction_processor import TransactionProcessor
from wf_debit_extractor import WellsFargoPayloadExtractor

# Extract payloads
extractor = WellsFargoPayloadExtractor()
payloads = extractor.extract_from_file("posted.dat")

# Process transactions
processor = TransactionProcessor()
transactions = processor.extract_transactions(payloads)

# Each transaction has:
#  - id (string)
#  - transaction_amount_cents (integer, e.g., 9.11 → 911)
#  - transaction_date_timestamp (milliseconds since epoch)
#  - transaction_date_datetime (Python datetime object)
#  - post_date_timestamp (milliseconds since epoch)
#  - post_date_datetime (Python datetime object)
#  - transaction_description (string)

for txn in transactions:
    print(txn["id"], txn["transaction_amount_cents"], txn["transaction_description"])
```

See `example_usage.py` for a working example that also saves all transactions to `processed_transactions.json`.

## YNAB Integration

Use `ynab_client.py` to fetch transactions from your YNAB account. Configuration is loaded from `ynab.yml` which should contain your YNAB token, plan ID, and account IDs to track.

```python
from ynab_client import YNABClient

# Initialize with config file
client = YNABClient("ynab.yml")

# Fetch transactions from past 30 days
transactions = client.get_transactions_for_days(days=30)

# Each transaction includes:
#  - id
#  - date (YYYY-MM-DD)
#  - payee_name
#  - category_name
#  - amount_milliCurrency (in milliCurrency units, divide by 1000 for dollars)
#  - memo
#  - account_id
#  - account_name
#  - cleared (cleared status)

for txn in transactions:
    print(f"{txn['date']} | {txn['payee_name']} | ${txn['amount_milliCurrency'] / 1000:.2f}")

# Get account balance
balance = client.get_account_balance("7282c2e6-0470-423d-9748-ec36e29f5698")
print(f"Balance: ${balance / 1000:.2f}")
```

See `ynab_example.py` for a complete example that also saves all transactions to `ynab_transactions.json`.

### Export YNAB Transactions to CSV

Write transactions from the configured credit and debit accounts for the past 60 days:

```powershell
python .\main.py --record-transactions
```

Set a different lookback (1–240 days) and output path:

```powershell
python .\main.py --record-transactions=90 --transactions-csv .\exports\transactions.csv
```

The default output is `transactions.csv`. It contains only `payee`, `category`, `inflow`, and `outflow` columns. Split transactions are written as one row per subcategory, keeping the parent transaction's payee on each row. The misspelled `--record-trasactions` option is also accepted as an alias.

When importing bank transactions with `--ynab-import`, the importer uses `transactions.csv` and a reusable `category_memory.json` sidecar to suggest categories from similar payees, transaction direction, and amount. Confident suggestions are sent to YNAB; uncertain ones appear with a `?` in the preview and remain uncategorized. Each explicit `--record-transactions` export merges new patterns into the sidecar, so they remain available after older rows leave the CSV. Keep or sync both files between machines; the sidecar contains normalized payee/category/amount patterns but no transaction dates or IDs.

### ynab.yml Format

```yaml
ynab:
  - token: "your_ynab_api_token_here"
    plan_id: "your_budget_id_here"
    accounts:
        - name: "Credit Card"
          id: "account_id_here"
```

## Integration & Reconciliation

Use `reconcile.py` to fetch both WellsFargo and YNAB transactions side-by-side for reconciliation.

```powershell
python .\reconcile.py
```

This will:
1. Extract WellsFargo transactions from posted.dat
2. Fetch YNAB transactions for past 30 days
3. Display summary comparison
4. Save combined report to `reconciliation_report.json`

### Example Output
```
============================================================
RECONCILIATION SUMMARY
============================================================
WellsFargo transactions: 179
WellsFargo total: $5,432.15

YNAB transactions: 42
YNAB total: $3,210.50
============================================================
```

**Note:** Ensure your YNAB API token in `ynab.yml` is valid and has permission to access the budget/plan specified.