Socket
Socket
Sign inDemoInstall

ynab

Package Overview
Dependencies
8
Maintainers
3
Versions
68
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

ynab

YNAB API Javascript (Node) Library


Version published
Maintainers
3
Weekly downloads
403
decreased by-34.26%

Weekly downloads

Readme

Source

YNAB API JavaScript Library

Continuous Integration npm version

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

First, install the module with npm (or yarn):

npm install ynab

Then, depending upon your usage context, add a reference to it:

CommonJS / Node

const ynab = require("ynab");

ESM / TypeScript

import * as ynab from "ynab";

Browser

The API supports Cross Origin Resource Sharing (CORS) for asynchronous browser requests from any origin.

The dist/browser/ynab.js file (located in node_modules/ynab after installation) is specifically built to run in a browser / window context and exports ynab variable to global namespace. No other dependencies are needed.

<script src="ynab.js" async></script>
...
<script>
  // This assignment is not necessary but demonstrates that
  // once the library is loaded, the global 'ynab' object will be available.
  var ynab = window.ynab;
</script>
CDN

A simple way to load the library in a browser is by using the unpkg CDN, which is a "fast, global content delivery network for everything on npm". To use it, include a script tag like this in your file:

<script src="https://unpkg.com/ynab@latest/dist/browser/ynab.js" async></script>

Using the "latest" tag will result in a 302 redirect to the latest version tag so it is highly recommended to use a specific version tag such as https://unpkg.com/ynab@1.5.0/dist/browser/ynab.js to avoid this redirect.

Usage

To use this client, you must obtain an access token from the Account Settings 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"
    //   }
    // }
  });

Rate Limiting

The API enforces Rate Limiting.

If the rate limit is exceeded, a 429 Error Response will be returned from the API which will result in an error being thrown in this library.

You can access the rate limiting info through the rateLimit property on a response object. It will contain the value from the X-Rate-Limit response header.

const ynabAPI = new ynab.API(accessToken);
const budgetsResponse = await ynabAPI.budgets.getBudgets();
console.log(budgetsResponse.rateLimit); // ex: "36/200"

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.

MethodDescription
Useruser.getUser()Returns authenticated user information
Budgetsbudgets.getBudgets()Returns budgets list with summary information
budgets.getBudgetById(budget_id)Returns a single budget with all related entities
budgets.getBudgetSettingsById(budget_id)Returns settings for a budget
Accountsaccounts.getAccounts(budget_id)Returns all accounts
accounts.getAccountById(budget_id, account_id)Returns a single account
Categoriescategories.getCategories(budget_id)Returns all categories grouped by category group.
categories.getCategoryById(budget_id, category_id)Returns a single category
categories.updateMonthCategory(budget_id, month, category_id, month_category)Update an existing month category
Payeespayees.getPayees(budget_id)Returns all payees
payees.getPayeeById(budget_id, payee_id)Returns single payee
Payee Locationspayee_locations.getPayeeLocations(budget_id)Returns all payee locations
payee_locations.getPayeeLocationById(budget_id, payee_location_id)Returns a single payee location
payee_locations.getPayeeLocationsByPayee(budget_id, payee_id)Returns all payee locations for the specified payee
Monthsmonths.getBudgetMonths(budget_id)Returns all budget months
months.getBudgetMonth(budget_id, month)Returns a single budget month
months.getMonthCategory_by_id(budget_id, month, category_id)Returns a single category for a specific budget month
Transactionstransactions.getTransactions(budget_id)Returns budget transactions
transactions.getTransactionsByAccount(budget_id, account_id)Returns all transactions for a specified account
transactions.getTransactionsByCategory(budget_id, category_id)Returns all transactions for a specified category
transactions.getTransactionsByType(budget_id, type)Returns all transactions of a specified type ("unapproved" or "uncategorized")
transactions.getTransactionById(budget_id, transaction_id)Returns a single transaction
transactions.createTransaction(budget_id, data)Creates a single transaction
transactions.createTransactions(budget_id, data)Creates multiple transactions
transactions.updateTransaction(budget_id, transaction_id, data)Updates a single transaction
transactions.updateTransactions(budget_id, data)Updates multiple transactions
transactions.deleteTransaction(budget_id, transaction_id)Deletes a transaction
transactions.importTransactions(budget_id)Imports transactions
Scheduled Transactionsscheduled_transactions.getScheduledTransactions(budget_id)Returns all scheduled transactions
scheduled_transactions.getScheduledTransactionById(budget_id, scheduled_transaction_id)Returns a single scheduled transaction

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

License

Copyright (c) 2022 You Need A Budget, LLC

Licensed under the Apache-2.0 license

Keywords

FAQs

Last updated on 15 Feb 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc