ynab

YNAB API Javascript (Node) Library

NOTE: The YNAB API is currently only available to Early Access users. If you are interested in requesting access before the API is generally available, please fill out this form.

This is the JavaScript (Node) client for the YNAB API. The YNAB API does not have CORS configured so using this client in a browser context is not supported.

Please read the YNAB API documentation for an overview of using the API and a complete list of available resources.

This client is generated using the Swagger Code Generator.

Installation

npm install ynab

Usage

To use this client, you must obtain an access token from the My Account area of the YNAB web application.

const ynab = require("ynab");
const accessToken = "b43439eaafe2_this_is_fake_b43439eaafe2";
const ynabAPI = new ynab.api(accessToken);

(async function() {
  const budgetsResponse = await ynabAPI.budgets.getBudgets();
  const budgets = budgetsResponse.data.budgets;
  for(let budget of budgets) {
    console.log(`Budget Name: ${budget.name}`);
  }
})();

Error Handling

If a response is returned with a code >= 300, instead of returning the response, the response will be "thrown" as an error to be caught.

const ynab = require("ynab");
const accessToken = "invalid_token";
const ynabAPI = new ynab.api(accessToken);

const budgetsResponse = ynabAPI.budgets.getBudgets()
  .then(budgetsResponse => {
    // Won't get here because an error will be thrown
  })
  .catch(e => {
    console.log(e);
    // {
    //   error: {
    //    id: "401",
    //    name: "unauthorized",
    //    detail: "Unauthorized"
    //   }
    // }
  });

Utilities

There are several utilities available on the utils export to make working with ISO dates and milliunits a bit easier.

// Returns the current month (system timezone) in ISO 8601 format (i.e. '2015-12-01')
getCurrentMonthInISOFormat(): string;
// Returns the current date (system timezone) in ISO 8601 format (i.e. '2015-12-15')
getCurrentDateInISOFormat(): string;
// Converts an ISO 8601 formatted string to a JS date object
convertFromISODateString(isoDateString: string): Date;
// Converts a milliunits amount to a currency amount
convertMilliUnitsToCurrencyAmount(milliunits: number, currencyDecimalDigits: number): number;

Examples

See the examples folder for example usage scenarios.

Methods

The following methods are available in this library. For more details on parameters and usage, the TypeScript declaration file can be referenced.

	Method	Description
Budgets	budgets.getBudgets()	Returns budgets list with summary information
	budgets.getBudgetById(id)	Returns a single budget with all related entities
Accounts	accounts.getAccounts(budgetId)	Returns all accounts
	accounts.getAccountById(budgetId, id)	Returns a single account
Categories	categories.getCategories(budgetId)	Returns all categories grouped by category group.
	categories.getCategoryById(budgetId, id)	Returns a single category
Payees	payees.getPayees(budgetId)	Returns all payees
	payees.getPayeeById(budgetId, id)	Returns single payee
Payee Locations	payeeLocations.getPayeeLocations(budgetId)	Returns all payee locations
	payeeLocations.getPayeeLocationById(budgetId, id)	Returns a single payee location
	payeeLocations.getPayeeLocationsByPayee(budgetId, id)	Returns all payee locations for the specified payee
Months	months.getBudgetMonths(budgetId)	Returns all budget months
	months.getBudgetMonth(budgetId, month)	Returns a single budget month
Transactions	transactions.getTransactions(budgetId)	Returns budget transactions
	transactions.getTransactionsByAccount(budgetId, id)	Returns all transactions for a specified account
	transactions.getTransactionsByCategory(budgetId, id)	Returns all transactions for a specified category
	transactions.getTransactionsById(budgetId, id)	Returns a single transaction
	transactions.updateTransaction(budgetId, id, transaction)	Updates a transaction
	transactions.createTransaction(budgetId, transaction)	Creates a new transaction
	transactions.bulkCreateTransactions(budgetId, transactions)	Creates multiple transactions
Scheduled Transactions	scheduledTransactions.getScheduledTransactions(budgetId)	Returns all scheduled transactions
	scheduledTransactions.getScheduledTransactionById(budgetId, id)	Returns a single scheduled transaction

Development

To build and compile:

npm install
npm run build

To run tests:

npm test

License

Copyright (c) 2018 You Need A Budget, LLC

Licensed under the Apache-2.0 license