Struct Client 

pub struct Client { /* private fields */ }

Client is the YNAB API client. Use Client::new() to create one.

Implementations

impl Client

pub fn get_accounts(&self, plan_id: PlanId) -> GetAccountsBuilder<'_>

Returns a builder for fetching all accounts. Chain .with_server_knowledge() for a delta request.

pub async fn get_account( &self, plan_id: PlanId, account_id: Uuid, ) -> Result<Account, Error>

Returns a single account.

impl Client

pub async fn create_account( &self, plan_id: PlanId, account: SaveAccount, ) -> Result<Account, Error>

Creates a new account.

impl Client

pub fn get_categories(&self, plan_id: PlanId) -> GetCategoriesBuilder<'_>

Returns a builder for fetching all categories grouped by category group. Chain .with_server_knowledge() for a delta request.

pub async fn get_category( &self, plan_id: PlanId, cat_id: Uuid, ) -> Result<Category, Error>

Returns a single category. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).

pub async fn get_category_for_month( &self, plan_id: PlanId, month: NaiveDate, cat_id: Uuid, ) -> Result<Category, Error>

Returns a single category for a specific plan month. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).

impl Client

pub async fn create_category( &self, plan_id: PlanId, category: NewCategory, ) -> Result<(Category, i64), Error>

Creates a new category.

pub async fn create_category_group( &self, plan_id: PlanId, category_group: SaveCategoryGroup, ) -> Result<(CategoryGroup, i64), Error>

Creates a new category group.

pub async fn update_category( &self, plan_id: PlanId, category_id: Uuid, category: SaveCategory, ) -> Result<(Category, i64), Error>

Update a category.

pub async fn update_category_for_month( &self, plan_id: PlanId, month: NaiveDate, category_id: Uuid, category: SaveMonthCategory, ) -> Result<(Category, i64), Error>

Update a category for a specific month. Only budgeted (assigned) amount can be updated.`

pub async fn update_category_group( &self, plan_id: PlanId, category_group_id: Uuid, category_group: SaveCategoryGroup, ) -> Result<(CategoryGroup, i64), Error>

Update a category group.

impl Client

pub fn new(api_key: impl Into<String>) -> Result<Self, Error>

Creates a new client with the given Personal Access Token.

Examples

use rust_ynab::Client;

let client = Client::new(&std::env::var("YNAB_TOKEN")?)?;

pub fn with_timeout(self, timeout: Duration) -> Result<Self, Error>

Sets the request timeout. Returns self for chaining.

Examples

use rust_ynab::Client;
use std::time::Duration;

let client = Client::new(&std::env::var("YNAB_TOKEN")?)?
    .with_timeout(Duration::from_secs(30))?;

pub fn with_base_url(self, base_url: impl AsRef<str>) -> Result<Self, Error>

Overrides the base URL. Primarily useful for testing.

pub fn with_rate_limiter( self, requests_per_hour: usize, burst_volume: Option<usize>, ) -> Result<Self, Error>

Configures a token bucket rate limiter on the client. Returns self for chaining.

requests_per_hour is the total allowed requests per hour. burst_volume optionally allows a number of requests to be made immediately before throttling begins. The effective sustained rate becomes requests_per_hour - burst_volume to account for burst consumption. If None, no burst is allowed and the full rate is sustained evenly.

Examples

use rust_ynab::Client;
use std::time::Duration;

let client = Client::new(&std::env::var("YNAB_TOKEN")?)?
    .with_rate_limiter(200, Some(10))?  // 10 burst, then 190/hr
    .with_timeout(Duration::from_secs(30))?;

impl Client

pub fn get_months(&self, plan_id: PlanId) -> GetMonthsBuilder<'_>

Returns a builder for fetching all plan months. Chain .with_server_knowledge() for a delta request.

pub async fn get_month( &self, plan_id: PlanId, month: NaiveDate, ) -> Result<Month, Error>

Returns a single plan month.

impl Client

pub fn get_money_movements( &self, plan_id: PlanId, ) -> GetMoneyMovementsBuilder<'_>

Returns a builder for fetching all money movements. Chain .with_server_knowledge() for a delta request.

pub async fn get_money_movements_by_month( &self, plan_id: PlanId, month: NaiveDate, ) -> Result<(Vec<MoneyMovement>, i64), Error>

Returns all money movements for a specific month. The second return value is server knowledge for delta requests.

pub fn get_money_movement_groups( &self, plan_id: PlanId, ) -> GetMoneyMovementGroupsBuilder<'_>

Returns a builder for fetching all money movement groups. Chain .with_server_knowledge() for a delta request.

pub async fn get_money_movement_groups_by_month( &self, plan_id: PlanId, month: NaiveDate, ) -> Result<(Vec<MoneyMovementGroup>, i64), Error>

Returns all money movement groups for a specific month. The second return value is server knowledge for delta requests.

impl Client

pub fn get_payees(&self, plan_id: PlanId) -> GetPayeesBuilder<'_>

Returns a builder for fetching all payees. Chain .with_server_knowledge() for a delta request.

pub async fn get_payee( &self, plan_id: PlanId, payee_id: Uuid, ) -> Result<Payee, Error>

Returns a single payee.

pub async fn get_payee_locations( &self, plan_id: PlanId, ) -> Result<Vec<PayeeLocation>, Error>

Returns all payee locations.

pub async fn get_payee_locations_by_payee( &self, plan_id: PlanId, payee_id: Uuid, ) -> Result<Vec<PayeeLocation>, Error>

Returns all payee locations for a specified payee.

pub async fn get_payee_location( &self, plan_id: PlanId, location_id: Uuid, ) -> Result<PayeeLocation, Error>

Returns a single payee location.

impl Client

pub async fn create_payee( &self, plan_id: PlanId, payee: PostPayee, ) -> Result<(Payee, i64), Error>

Creates a new payee. Returns the created payee and server knowledge for delta requests.

pub async fn update_payee( &self, plan_id: PlanId, payee_id: Uuid, payee: SavePayee, ) -> Result<(Payee, i64), Error>

Updates an existing payee. Returns the updated payee and server knowledge for delta requests.

impl Client

pub fn get_plans(&self) -> GetPlansBuilder<'_>

Returns a builder for fetching all plans. Chain .include_accounts() to embed account details inline.

Examples

let client = Client::new(&std::env::var("YNAB_TOKEN")?)?;
let plans = client.get_plans().include_accounts().send().await?;
for plan in &plans {
    println!("{}: {} accounts", plan.name, plan.accounts.len());
}

pub async fn get_plan_settings( &self, plan_id: PlanId, ) -> Result<PlanSettings, Error>

Returns settings for a plan.

pub fn get_plan(&self, plan_id: PlanId) -> GetPlanBuilder<'_>

Returns a builder for fetching a single plan with all related entities (a full plan export). Chain .with_server_knowledge() for a delta request.

impl Client

pub fn get_transactions(&self, plan_id: PlanId) -> GetTransactionsBuilder<'_>

Returns a builder for fetching transactions. Chain .with_server_knowledge(), .since_date(), or .transaction_type() before calling .send().

Examples

// Full fetch
let (transactions, server_knowledge) = client
    .get_transactions(PlanId::LastUsed)
    .send()
    .await?;

// Delta request — only changes since last sync
let (changes, new_sk) = client
    .get_transactions(PlanId::LastUsed)
    .with_server_knowledge(server_knowledge)
    .send()
    .await?;

pub async fn get_transaction( &self, plan_id: PlanId, transaction_id: &Uuid, ) -> Result<(Transaction, i64), Error>

Returns a single transaction.

pub fn get_transactions_by_account( &self, plan_id: PlanId, account_id: Uuid, ) -> GetTransactionsBuilder<'_>

Returns a builder for fetching transactions for a specified account.

pub fn get_transactions_by_category( &self, plan_id: PlanId, category_id: Uuid, ) -> GetTransactionsBuilder<'_>

Returns a builder for fetching transactions for a specified category.

pub fn get_transactions_by_payee( &self, plan_id: PlanId, payee_id: Uuid, ) -> GetTransactionsBuilder<'_>

Returns a builder for fetching transactions for a specified payee.

pub fn get_transactions_by_month( &self, plan_id: PlanId, month: NaiveDate, ) -> GetTransactionsBuilder<'_>

Returns a builder for fetching transactions for a specified month.

impl Client

pub fn get_scheduled_transactions( &self, plan_id: PlanId, ) -> GetScheduledTransactionsBuilder<'_>

Returns a builder for fetching all scheduled transactions. Chain .with_server_knowledge() for a delta request.

pub async fn get_scheduled_transaction( &self, plan_id: PlanId, transaction_id: Uuid, ) -> Result<ScheduledTransaction, Error>

Returns a single scheduled transaction.

impl Client

pub async fn delete_transaction( &self, plan_id: PlanId, tx_id: Uuid, ) -> Result<(Transaction, i64), Error>

Delete a transaction. Returns deleted transaction and server_knowledge for delta requests

pub async fn import_transactions( &self, plan_id: PlanId, ) -> Result<Vec<Uuid>, Error>

Imports available transactions on all linked accounts for the given plan. The response for this endpoint contains the transaction ids that have been imported.

impl Client

pub async fn create_transaction( &self, plan_id: PlanId, transaction: NewTransaction, ) -> Result<SaveTransactionsResponse, Error>

Creates a single transaction. Returns the full save response including server knowledge.

Examples

let resp = client.create_transaction(PlanId::LastUsed, NewTransaction {
    account_id,
    date: chrono::Local::now().date_naive(),
    amount: Some(-15000), // -$15.00
    memo: Some("Coffee".to_string()),
    cleared: Some(ClearedStatus::Cleared),
    approved: Some(true),
    payee_id: None,
    payee_name: None,
    category_id: None,
    flag_color: None,
    import_id: None,
    subtransactions: None,
}).await?;
let tx_id = resp.transaction.unwrap().id;

pub async fn create_transactions( &self, plan_id: PlanId, transactions: Vec<NewTransaction>, ) -> Result<SaveTransactionsResponse, Error>

Creates multiple transactions. Returns the full save response including server knowledge.

pub async fn update_transactions( &self, plan_id: PlanId, transactions: Vec<SaveTransactionWithIdOrImportId>, ) -> Result<SaveTransactionsResponse, Error>

Updates multiple transactions. Returns the full save response including server knowledge.

pub async fn update_transaction( &self, plan_id: PlanId, tx_id: Uuid, transaction: ExistingTransaction, ) -> Result<(Transaction, i64), Error>

Updates a single transaction. Returns the updated transaction and server knowledge.

pub async fn create_scheduled_transaction( &self, plan_id: PlanId, scheduled_transaction: SaveScheduledTransaction, ) -> Result<ScheduledTransaction, Error>

Creates a scheduled transaction.

pub async fn update_scheduled_transaction( &self, plan_id: PlanId, scheduled_transaction_id: Uuid, scheduled_transaction: SaveScheduledTransaction, ) -> Result<ScheduledTransaction, Error>

Updates a scheduled transaction.

pub async fn delete_scheduled_transaction( &self, plan_id: PlanId, scheduled_transaction_id: Uuid, ) -> Result<ScheduledTransaction, Error>

Deletes a scheduled transaction.

impl Client

pub async fn get_user(&self) -> Result<User, Error>

Returns authenticated user information.

Trait Implementations

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.