first commit

YNAB_MODULE.md

@@ -0,0 +1,129 @@
+# 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
+