v2.0.0

Overview

v2.0.0 is a major release aligned with the YNAB API v1.79.0 migration from budget terminology to plan terminology. It substantially expands endpoint coverage, adds write support across all major resources, improves type safety in mutation models, and hardens security across the auth layer.

---

Breaking Changes

API path migration: budgets → plans

All client requests now use /plans/{plan_id}/... paths to match YNAB API v1.79.0. The budgets(), defaultBudget(), and Budget model have been removed entirely.

The $budgetId parameter has been renamed to $planId across all YnabClient methods.

Migration: Replace $client->budgets() with $client->plans(), $client->defaultBudget() with $client->defaultPlan(), update $budgetId named arguments to $planId, and replace any Budget type references with Plan.

Mutation model fields now use enums

The following string fields in mutation request models have been replaced with typed PHP 8.1 enums:

Model	Property	Old type	New type
TransactionPayload	$cleared	string	TransactionClearedStatus
TransactionPayload	$flagColor	string	TransactionFlagColor
ScheduledTransactionPayload	$flagColor	string	TransactionFlagColor
ScheduledTransactionPayload	$frequency	string	ScheduledTransactionFrequency
CreateAccountRequest	$type	string	AccountType

Migration: Replace raw strings with the corresponding enum cases, e.g. TransactionClearedStatus::Cleared, TransactionFlagColor::Red, ScheduledTransactionFrequency::Monthly, AccountType::Checking.

Transaction::$isPending removed

This field was not present in the YNAB OpenAPI spec and has been removed.

HTTPS enforced on client base URL

The client now rejects base URLs using http://. All connections must use https://.

ApiKeyAuth and OAuthTokenAuth throw on empty tokens

Constructing either auth class with an empty or whitespace-only string now throws InvalidStringException rather than silently accepting an unusable value.

---

New Endpoints

Read endpoints

• user() — authenticated user info
• plans() / defaultPlan() — plan list and default plan
• plan(string $planId) — single plan detail
• planSettings(string $planId) — plan settings
• account(string $planId, string $accountId) — single account
• payee(string $planId, string $payeeId) — single payee
• categoryGroups(string $planId) — all category groups with categories
• categoryGroup(string $planId, string $groupId) — single category group
• category(string $planId, string $categoryId) — single category
• months(string $planId) — all plan months
• month(string $planId, string $month) — single month detail (includes categories)
• monthCategory(string $planId, string $month, string $categoryId) — category for a specific month
• transaction(string $planId, string $transactionId) — single transaction
• Filtered transaction reads by account, category, payee, and month
• scheduledTransactions(string $planId) / scheduledTransaction(...) — scheduled transaction list and detail
• payeeLocations(string $planId) / payeeLocation(...) — payee location list and detail
• moneyMovements(string $planId) / moneyMovementGroups(string $planId) — money movement data

Write endpoints (new in this release)

Full create/update/delete coverage for:

• Transactions — createTransactions(), importTransactions(), updateTransaction(), patchTransactions(), deleteTransaction()
• Scheduled transactions — createScheduledTransaction(), updateScheduledTransaction(), deleteScheduledTransaction()
• Accounts — createAccount()
• Categories — createCategory(), updateCategory(), updateMonthCategory()
• Category groups — createCategoryGroup(), updateCategoryGroup()
• Payees — updatePayee()

---

Other Improvements

New typed models

User, PlanSettings, Month, CategoryDetail, CategoryGroup, ScheduledTransaction, MoneyMovement, MoneyMovementGroup, PayeeLocation — all mapping directly from YNAB API responses.

Model interface

All identifiable model classes now implement a Model interface declaring getId(): string. The YnabClient::resolveModelId() method accepts Model|string, so you can pass model objects anywhere an ID string is expected.

ResourceCollection is iterable and countable

ResourceCollection now implements IteratorAggregate and Countable, enabling direct use in foreach loops and with count().

Pagination safety limit

ClientConfig accepts a $maxPages parameter (default: 100) that caps automatic page fetches, preventing runaway requests against large datasets.

OAuthClient::generateState()

Convenience method for generating a cryptographically random OAuth CSRF state parameter:

$state = OAuthClient::generateState(); // returns hex-encoded random bytes

OAuth token endpoint validation

OAuthClient now checks the HTTP status code of token endpoint responses before parsing, throwing YnabException on non-2xx responses.

Credential redaction in debug output

ApiKeyAuth, OAuthTokenAuth, OAuthConfig, and OAuthTokens implement __debugInfo() so that var_dump() and print_r() never expose raw API keys, access tokens, or client secrets.

---

Upgrade Guide

1. Replace budgets() / defaultBudget() with plans() / defaultPlan(), and remove any references to the Budget model.
2. Replace $budgetId with $planId in all YnabClient call sites.
3. Update mutation model construction to use enum values instead of raw strings.
4. Remove any references to Transaction::$isPending.
5. Verify your YnabClient base URL uses https://.
6. Wrap ApiKeyAuth / OAuthTokenAuth construction in a try/catch for InvalidStringException if token values can arrive empty.