# YNAB Client Module Summary

## Overview
A Python module (`ynab_client.py`) that authenticates with YNAB using the official SDK and retrieves transactions from configured accounts.

## Files Created

### `ynab_client.py` - Main Module
- **YNABClient class**: Main interface for YNAB API interactions
  - `__init__(config_path)`: Initialize from YAML config file
  - `get_transactions_for_days(days=30)`: Fetch transactions for past N days
  - `get_account_balance(account_id)`: Get current balance for an account

- **YNABTransaction TypedDict**: Defines transaction data structure
  - `id`: Transaction ID
  - `date`: Transaction date (YYYY-MM-DD)
  - `payee_name`: Payee name
  - `category_name`: Category name
  - `amount_milliCurrency`: Amount in milliCurrency units (divide by 1000 for dollars)
  - `memo`: Transaction memo
  - `account_id`: YNAB account ID
  - `account_name`: Account name
  - `cleared`: Cleared status

### `ynab_example.py` - Example Usage
Demonstrates how to:
- Load YNAB client from config
- Fetch transactions for past 30 days
- Display transactions in human-readable format
- Save transactions to JSON file (`ynab_transactions.json`)

### `ynab.yml` - Configuration File
Contains:
- YNAB API token
- Budget/Plan ID
- List of accounts to track (name, ID, and extractor)

## Configuration File

Create a `ynab.yml` file in the project root using the following structure:

```yaml
ynab:
  - token: "your-ynab-api-token"
    plan_id: "your-budget-id"
    accounts:
        - name: "Credit Card"
          id: "account-uuid"
          extractor: "wf_credit_extractor"
        - name: "Debit Card"
          id: "account-uuid"
          extractor: "wf_debit_extractor"
```

### Field Reference

| Field | Required | Description |
|-------|----------|-------------|
| `ynab` | ✓ | Top-level key. Contains a list of YNAB configurations (one per budget). |
| `token` | ✓ | Your YNAB Personal Access Token. Generate one at **YNAB → Account Settings → Developer Settings**. Keep this secret — treat it like a password. |
| `plan_id` | ✓ | The UUID of your YNAB budget. Find it in the URL when viewing your budget: `https://app.ynab.com/<plan_id>/budget`. |
| `accounts` | ✓ | List of bank accounts to sync. Each entry maps a YNAB account to a Wells Fargo data extractor. |
| `accounts[].name` | ✓ | A human-readable label for the account (used in report output only). |
| `accounts[].id` | ✓ | The UUID of the YNAB account. Find it in the URL when viewing the account in YNAB, or via the YNAB API. |
| `accounts[].extractor` | ✓ | Which Wells Fargo extractor to use for this account. Must be one of: `wf_credit_extractor` (for credit cards) or `wf_debit_extractor` (for checking/debit accounts). |

### How to Find Your IDs

**API Token**
1. Log in to [app.ynab.com](https://app.ynab.com)
2. Go to **Account Settings → Developer Settings**
3. Click **New Token**, give it a name, and copy the value

**Budget (plan_id)**
- Open your budget in YNAB — the UUID is in the URL:
  `https://app.ynab.com/`**`dc25f923-e6b4-45f5-8d42-65e53eed1f1e`**`/budget`

**Account ID**
- Click on an account in YNAB — the UUID appears in the URL after `/accounts/`
- Or use the YNAB API Explorer at `https://api.ynab.com/v1/budgets/<plan_id>/accounts`

## Dependencies
- `ynab` (v2.1.0) - Official YNAB Python SDK
- `pyyaml` (v6.0.3) - YAML file parsing

## Usage

### Basic Usage
```python
from ynab_client import YNABClient

# Initialize client
client = YNABClient("ynab.yml")

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

# Access transaction data
for txn in transactions:
    amount_dollars = txn["amount_milliCurrency"] / 1000
    print(f"{txn['date']} | {txn['payee_name']} | ${amount_dollars:.2f}")
```

### Run Example
```powershell
python .\ynab_example.py
```

This will:
1. Load credentials from `ynab.yml`
2. Fetch transactions from configured accounts
3. Display first 10 transactions
4. Save all transactions to `ynab_transactions.json`

## Key Features
- ✓ Configuration from YAML file
- ✓ Automatic date filtering (past X days)
- ✓ Category name lookup
- ✓ Account name mapping
- ✓ Error handling for network/API issues
- ✓ Both timestamp and formatted date fields
- ✓ Balance retrieval for accounts

## Status
- ✓ Module created and tested
- ✓ Configuration loading verified
- ✓ Dependencies installed
- ✓ No static errors