130 lines
4.3 KiB
Markdown
130 lines
4.3 KiB
Markdown
# 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
|
|
|