YNAB SDK JS

https://github.com/ynab/ynab-sdk-js
Admin
A JavaScript client library for interacting with the YNAB (You Need A Budget) API, allowing...
Tokens:4,851
Snippets:22
Trust Score:8.7
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Development Setup

Source: https://github.com/ynab/ynab-sdk-js/blob/main/DEVELOPMENT.md

Installs project dependencies and the OpenAPI Generator tool required for development.

```shell
npm install
```

```shell
brew install openapi-generator
```

--------------------------------

### Install YNAB SDK

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Installs the YNAB SDK using npm. This is the first step to integrate the YNAB API into your JavaScript project.

```shell
npm install ynab
```

--------------------------------

### Handle API Errors

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Demonstrates how the YNAB SDK handles API errors by throwing them. This example shows catching an error, likely due to an invalid access token.

```typescript
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);
    // Expected error structure:
    // {
    //   error: {
    //    id: "401",
    //    name: "unauthorized",
    //    detail: "Unauthorized"
    //   }
    // }
  });
```

--------------------------------

### Initialize YNAB API Client

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Initializes the YNAB API client with an access token and demonstrates fetching budgets. Requires an access token obtained from YNAB account settings.

```typescript
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}`);
  }
})();
```

--------------------------------

### Build and Test

Source: https://github.com/ynab/ynab-sdk-js/blob/main/DEVELOPMENT.md

Commands to build the project and run automated tests.

```shell
npm run build && npm run test
```

--------------------------------

### Load YNAB SDK in Browser (CDN)

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Loads the YNAB SDK from a CDN (unpkg) for browser usage. It's recommended to use a specific version tag instead of 'latest' for stability.

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

--------------------------------

### Load YNAB SDK in Browser (Script Tag)

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Loads the YNAB SDK directly in a browser environment using a script tag. The library exports the 'ynab' variable to the global namespace.

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

--------------------------------

### Import YNAB SDK (CommonJS/Node)

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Imports the YNAB SDK for use in CommonJS environments, typically Node.js projects.

```javascript
const ynab = require("ynab");
```

--------------------------------

### Generate API Client

Source: https://github.com/ynab/ynab-sdk-js/blob/main/DEVELOPMENT.md

Generates the API client code from the OpenAPI specification.

```shell
npm run generate
```

--------------------------------

### Publish SDK

Source: https://github.com/ynab/ynab-sdk-js/blob/main/DEVELOPMENT.md

Triggers the GitHub Actions workflow to build, version, and publish the SDK.

```github-actions
Run the "Publish" GitHub Actions workflow
```

--------------------------------

### Import YNAB SDK (ESM/TypeScript)

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Imports the YNAB SDK for use in ECMAScript Module (ESM) environments, common in modern JavaScript and TypeScript projects.

```typescript
import * as ynab from "ynab";
```

--------------------------------

### YNAB SDK JS Utilities

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Provides utility functions for date formatting and currency conversion, leveraging ISO 8601 and milliunits. These utilities simplify common data manipulation tasks within the YNAB SDK, making it easier to work with YNAB's date and currency formats.

```APIDOC
utils.getCurrentMonthInISOFormat(): string
  - Returns the current month (system timezone) in ISO 8601 format (i.e. '2015-12-01').
  - Parameters: None
  - Returns: string (ISO 8601 formatted month)

utils.getCurrentDateInISOFormat(): string
  - Returns the current date (system timezone) in ISO 8601 format (i.e. '2015-12-15').
  - Parameters: None
  - Returns: string (ISO 8601 formatted date)

utils.convertFromISODateString(isoDateString: string): Date
  - Converts an ISO 8601 formatted string to a JavaScript Date object.
  - Parameters:
    - isoDateString: string - The date string in ISO 8601 format.
  - Returns: Date (JavaScript Date object)

utils.convertMilliUnitsToCurrencyAmount(milliunits: number, currencyDecimalDigits: number): number
  - Converts an amount represented in milliunits to a standard currency amount.
  - Parameters:
    - milliunits: number - The amount in milliunits.
    - currencyDecimalDigits: number - The number of decimal digits for the currency.
  - Returns: number (The converted currency amount)
```

--------------------------------

### YNAB Budgets API: getBudgets, getBudgetById, getBudgetSettingsById

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Provides methods to fetch budget data. This includes retrieving a list of all budgets, a specific budget by its ID, and the settings for a particular budget.

```APIDOC
Budgets API:
  getBudgets()
    - Returns budgets list with summary information.
    - Parameters: None
    - Returns: Array of BudgetSummary objects

  getBudgetById(budget_id)
    - Returns a single budget with all related entities.
    - Parameters:
      - budget_id: string - The ID of the budget to retrieve.
    - Returns: Budget object

  getBudgetSettingsById(budget_id)
    - Returns settings for a budget.
    - Parameters:
      - budget_id: string - The ID of the budget to retrieve settings for.
    - Returns: BudgetSettings object
```

--------------------------------

### YNAB Payees API: getPayees, getPayeeById

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Methods for retrieving payee information. This includes fetching all payees for a budget or a specific payee by its ID.

```APIDOC
Payees API:
  getPayees(budget_id)
    - Returns all payees for a given budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
    - Returns: Array of Payee objects

  getPayeeById(budget_id, payee_id)
    - Returns a single payee by its ID within a budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - payee_id: string - The ID of the payee to retrieve.
    - Returns: Payee object
```

--------------------------------

### YNAB Months API

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Provides methods to retrieve budget month data from the YNAB API. This includes fetching a specific budget month's details.

```APIDOC
MonthsApi:
  getBudgetMonth(budget_id: string, month: string)
    - Returns a single budget month.
    - Parameters:
      - budget_id: The ID of the budget.
      - month: The month to retrieve (YYYY-MM-DD format).
```

--------------------------------

### YNAB Accounts API: getAccounts, getAccountById

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Methods for managing accounts within a budget. Allows fetching all accounts or a specific account by its ID.

```APIDOC
Accounts API:
  getAccounts(budget_id)
    - Returns all accounts for a given budget.
    - Parameters:
      - budget_id: string - The ID of the budget to retrieve accounts from.
    - Returns: Array of Account objects

  getAccountById(budget_id, account_id)
    - Returns a single account by its ID within a specific budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - account_id: string - The ID of the account to retrieve.
    - Returns: Account object
```

--------------------------------

### YNAB User API: getUser

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Retrieves information about the authenticated user. This method is part of the User API and requires authentication.

```APIDOC
User API:
  getUser()
    - Returns authenticated user information.
    - Parameters: None
    - Returns: User object
```

--------------------------------

### YNAB Categories API: getCategories, getCategoryById, getMonthCategoryById, updateCategory, updateMonthCategory

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Handles category-related operations. This includes fetching categories grouped by category group, retrieving a specific category or month category, and updating existing categories.

```APIDOC
Categories API:
  getCategories(budget_id)
    - Returns all categories grouped by category group for a budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
    - Returns: Categories object

  getCategoryById(budget_id, category_id)
    - Returns a single category by its ID within a budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - category_id: string - The ID of the category to retrieve.
    - Returns: Category object

  getMonthCategoryById(budget_id, month, category_id)
    - Returns a single category for a specific budget month.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - month: string - The month in YYYY-MM-DD format.
      - category_id: string - The ID of the category to retrieve.
    - Returns: MonthCategory object

  updateCategory(budget_id, category_id, category)
    - Update an existing category.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - category_id: string - The ID of the category to update.
      - category: object - The updated category data.
    - Returns: Updated Category object

  updateMonthCategory(budget_id, month, category_id, month_category)
    - Update an existing month category.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - month: string - The month in YYYY-MM-DD format.
      - category_id: string - The ID of the category to update.
      - month_category: object - The updated month category data.
    - Returns: Updated MonthCategory object
```

--------------------------------

### YNAB Payee Locations API: getPayeeLocations, getPayeeLocationById, getPayeeLocationsByPayee

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Provides functionality to manage payee locations. This includes fetching all payee locations, a specific location by its ID, or locations associated with a particular payee.

```APIDOC
Payee Locations API:
  getPayeeLocations(budget_id)
    - Returns all payee locations for a given budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
    - Returns: Array of PayeeLocation objects

  getPayeeLocationById(budget_id, payee_location_id)
    - Returns a single payee location by its ID within a budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - payee_location_id: string - The ID of the payee location to retrieve.
    - Returns: PayeeLocation object

  getPayeeLocationsByPayee(budget_id, payee_id)
    - Returns all payee locations for a specified payee within a budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
      - payee_id: string - The ID of the payee.
    - Returns: Array of PayeeLocation objects
```

--------------------------------

### YNAB Months API: getBudgetMonths

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Retrieves information about budget months. This method returns all months associated with a specific budget.

```APIDOC
Months API:
  getBudgetMonths(budget_id)
    - Returns all budget months for a given budget.
    - Parameters:
      - budget_id: string - The ID of the budget.
    - Returns: Array of Month objects
```

--------------------------------

### YNAB Transactions API

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Manages financial transactions within a YNAB budget. Supports retrieving, creating, updating, deleting, and importing transactions, with filtering capabilities by account, category, or month.

```APIDOC
TransactionsApi:
  getTransactions(budget_id: string)
    - Returns budget transactions.
    - Parameters:
      - budget_id: The ID of the budget.

  getTransactionsByAccount(budget_id: string, account_id: string)
    - Returns all transactions for a specified account.
    - Parameters:
      - budget_id: The ID of the budget.
      - account_id: The ID of the account.

  getTransactionsByCategory(budget_id: string, category_id: string)
    - Returns all transactions for a specified category.
    - Parameters:
      - budget_id: The ID of the budget.
      - category_id: The ID of the category.

  getTransactionsByMonth(budget_id: string, month: string)
    - Returns all transactions for a specified month.
    - Parameters:
      - budget_id: The ID of the budget.
      - month: The month to retrieve (YYYY-MM-DD format).

  getTransactionsByType(budget_id: string, type: 'unapproved' | 'uncategorized')
    - Returns all transactions of a specified type.
    - Parameters:
      - budget_id: The ID of the budget.
      - type: The type of transactions to retrieve ('unapproved' or 'uncategorized').

  getTransactionById(budget_id: string, transaction_id: string)
    - Returns a single transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - transaction_id: The ID of the transaction.

  createTransaction(budget_id: string, data: object)
    - Creates a single transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - data: The transaction data object.

  createTransactions(budget_id: string, data: object)
    - Creates multiple transactions.
    - Parameters:
      - budget_id: The ID of the budget.
      - data: An array of transaction data objects.

  updateTransaction(budget_id: string, transaction_id: string, data: object)
    - Updates a single transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - transaction_id: The ID of the transaction to update.
      - data: The updated transaction data object.

  updateTransactions(budget_id: string, data: object)
    - Updates multiple transactions.
    - Parameters:
      - budget_id: The ID of the budget.
      - data: An array of transaction data objects with transaction IDs.

  deleteTransaction(budget_id: string, transaction_id: string)
    - Deletes a transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - transaction_id: The ID of the transaction to delete.

  importTransactions(budget_id: string)
    - Imports transactions. This typically refers to importing transactions from linked accounts.
    - Parameters:
      - budget_id: The ID of the budget.
```

--------------------------------

### YNAB Scheduled Transactions API

Source: https://github.com/ynab/ynab-sdk-js/blob/main/README.md

Manages scheduled transactions within a YNAB budget. This includes retrieving, creating, updating, and deleting recurring transactions.

```APIDOC
ScheduledTransactionsApi:
  getScheduledTransactions(budget_id: string)
    - Returns all scheduled transactions.
    - Parameters:
      - budget_id: The ID of the budget.

  getScheduledTransactionById(budget_id: string, scheduled_transaction_id: string)
    - Returns a single scheduled transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - scheduled_transaction_id: The ID of the scheduled transaction.

  createScheduledTransaction(budget_id: string, data: object)
    - Creates a single scheduled transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - data: The scheduled transaction data object.

  updateScheduledTransaction(budget_id: string, scheduled_transaction_id: string, data: object)
    - Updates a single scheduled transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - scheduled_transaction_id: The ID of the scheduled transaction to update.
      - data: The updated scheduled transaction data object.

  deleteScheduledTransaction(budget_id: string, scheduled_transaction_id: string)
    - Deletes a single scheduled transaction.
    - Parameters:
      - budget_id: The ID of the budget.
      - scheduled_transaction_id: The ID of the scheduled transaction to delete.
```
Tokens:
Raw