FargoImport/YNAB_MODULE.md

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:

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
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

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

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