DOCSEARCHbyAlgolia
Submit Docs

YNAB JavaScript SDK

repository·main·Indexed 42 days ago

https://github.com/ynab/ynab-sdk-js

Official JavaScript client for the YNAB API, generated from server specification version 1.85.0. This type-safe library supports Node.js, TypeScript, and browser environments, providing organized namespaces for managing accounts, categories, transactions, and budget plans.

Tokens
98.3K
Snippets
293
Records
344
Agent score
53%

What's inside YNAB

  1. Manage transactions with TransactionsApi

    main

    The TransactionsApi class provides methods to create, retrieve, update, and delete transactions within a YNAB plan. All requests require a planId. You can use special identifiers like "last-used" or "default" for the planId to simplify targeting the user's active plan.

    Available methods include:

    • createTransaction: Create one or many transactions.
    • deleteTransaction: Remove a specific transaction.
    • getTransactionById: Retrieve details for a single transaction.
    • getTransactions: List transactions for a plan.
    • getTransactionsByAccount: List transactions for a specific account.
    • getTransactionsByCategory: List transactions for a specific category.
    • getTransactionsByMonth: List transactions for a specific month.
    • getTransactionsByPayee: List transactions for a specific payee.
    • importTransactions: Import transactions.
    • updateTransaction: Update a single transaction.
    • updateTransactions: Update multiple transactions via PATCH.

  2. Handle errors and rate limiting

    main

    Error Handling

    If the API returns a response code $\ge 300$, the SDK will throw an error instead of returning the response. You should use .catch() or try/catch blocks to handle these errors.

    An error object typically follows this structure:

    {
  "error": {
    "id": "401",
    "name": "unauthorized",
    "detail": "Unauthorized"
  }
}

    Rate Limiting

    The YNAB API enforces rate limits. If you exceed these limits, the API returns a 429 error, which the SDK will surface as a thrown error.

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

ynabAPI.plans
  .getPlans()
  .then(plansResponse => {
    // This block will not execute on error
  })
  .catch(e => {
    console.log(e);
    // Error structure: { error: { id: "401", name: "unauthorized", detail: "Unauthorized" } }
  });

  4. Understand the CategoryGroup model

    main

    The CategoryGroup type represents a grouping of categories within YNAB. It contains metadata about the group's identity, visibility, and status.

    import type { CategoryGroup } from ''

const example: CategoryGroup = {
  id: "string",
  name: "string",
  hidden: true,
  internal: false,
  deleted: false,
}

  5. Understand the PlanSettingsResponseData structure

    main

    PlanSettingsResponseData is a response data model used to represent the settings of a YNAB plan. It contains a single property, settings, which holds a PlanSettings object.

    import type { PlanSettingsResponseData } from ''

const example: PlanSettingsResponseData = {
  "settings": { /* PlanSettings object */ }
}

  6. Use the PlanSettings model

    main

    The PlanSettings model is used to define the formatting preferences for a YNAB plan, specifically regarding how dates and currencies are displayed. It contains the following properties:

    • date_format: A value of type DateFormat specifying the date display format.
    • currency_format: A value of type CurrencyFormat specifying the currency display format.
    import type { PlanSettings } from ''

const example = {
  "date_format": null,
  "currency_format": null,
} satisfies PlanSettings

  9. Understand YNAB SDK versioning and API compatibility

    main

    The YNAB SDK follows semantic versioning (SemVer) and is maintained independently of the YNAB API version.

    To ensure compatibility, check the package.json file of the installed package. The description field in package.json specifies which version of the YNAB API specification was used to generate the client. This is important because the SDK version and the API spec version do not necessarily align.

  10. Understand the MonthDetailBase model

    main

    The MonthDetailBase type represents the core data structure for month-level details in YNAB. It contains summary financial figures for a specific month, such as income, budgeted amounts, and activity, along with a list of categories associated with that month.

    Properties

    NameTypeDescription
    monthstringThe month identifier.
    notestringA note associated with the month.
    incomenumberTotal income for the month.
    budgetednumberTotal amount budgeted for the month.
    activitynumberTotal activity for the month.
    to_be_budgetednumberThe amount remaining to be budgeted.
    age_of_moneynumberThe age of money metric.
    deletedbooleanIndicates if the month has been deleted.
    categoriesArray<CategoryBase>An array of CategoryBase objects representing the categories in this month.

  11. Understand the HybridTransactionsResponse model

    main

    The HybridTransactionsResponse is a data model used in the YNAB API to represent a response containing transaction data. It follows a standard envelope pattern where the actual payload is contained within a data property.

    Properties

    NameTypeDescription
    dataHybridTransactionsResponseDataThe core transaction data payload.

    Refer to HybridTransactionsResponseData for the specific structure of the transaction information.