{"id":14986757,"url":"https://github.com/ynab/ynab-sdk-js","last_synced_at":"2025-05-15T12:02:09.017Z","repository":{"id":28689936,"uuid":"110977616","full_name":"ynab/ynab-sdk-js","owner":"ynab","description":"Official JavaScript client for the YNAB API","archived":false,"fork":false,"pushed_at":"2025-03-24T13:16:44.000Z","size":2622,"stargazers_count":224,"open_issues_count":1,"forks_count":21,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-14T19:59:18.124Z","etag":null,"topics":["api","budgeting","finance","nodejs","rest-api","typescript","ynab","ynab-api"],"latest_commit_sha":null,"homepage":"https://api.ynab.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ynab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-11-16T13:55:16.000Z","updated_at":"2025-03-24T13:16:49.000Z","dependencies_parsed_at":"2023-11-07T17:31:12.014Z","dependency_job_id":"f9783c15-bceb-43ac-9534-bef43dc35080","html_url":"https://github.com/ynab/ynab-sdk-js","commit_stats":{"total_commits":575,"total_committers":10,"mean_commits":57.5,"dds":"0.17739130434782613","last_synced_commit":"2d11a355782bda3ba78fb69aec44fddca2732f7a"},"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynab%2Fynab-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynab%2Fynab-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynab%2Fynab-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynab%2Fynab-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ynab","download_url":"https://codeload.github.com/ynab/ynab-sdk-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","budgeting","finance","nodejs","rest-api","typescript","ynab","ynab-api"],"created_at":"2024-09-24T14:13:28.636Z","updated_at":"2025-05-15T12:02:08.937Z","avatar_url":"https://github.com/ynab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YNAB API JavaScript Library\n\n[![Build](https://github.com/ynab/ynab-sdk-js/actions/workflows/build-test.yml/badge.svg)](https://github.com/ynab/ynab-sdk-js/actions/workflows/build-test.yml)\n[![npm version](https://badge.fury.io/js/ynab.svg?icon=si%3Anpm)](https://badge.fury.io/js/ynab)\n\nPlease read the [YNAB API documentation](https://api.ynab.com) for an overview of using the API and a complete list of available resources.\n\nThis client is generated using the [OpenAPI Generator](https://openapi-generator.tech/).\n\n## Installation\n\nFirst, install the module with npm:\n\n```shell\nnpm install ynab\n```\n\nThen, depending upon your usage context, add a reference to it:\n\n### CommonJS / Node\n\n```\nconst ynab = require(\"ynab\");\n```\n\n### ESM / TypeScript\n\n```\nimport * as ynab from \"ynab\";\n```\n\n### Browser\n\nThe API supports [Cross Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for asynchronous browser requests from any origin.\n\nThe `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.\n\n```\n\u003cscript src=\"ynab.js\" async\u003e\u003c/script\u003e\n...\n\u003cscript\u003e\n  // This assignment is not necessary but demonstrates that\n  // once the library is loaded, the global 'ynab' object will be available.\n  var ynab = window.ynab;\n\u003c/script\u003e\n```\n\n#### CDN\n\nA simple way to load the library in a browser is by using the [unpkg](https://unpkg.com/) CDN, which is a\n\"fast, global content delivery network for everything on npm\".  To use it, include a script tag like this in your file:\n\n```\n\u003cscript src=\"https://unpkg.com/ynab@latest/dist/browser/ynab.js\" async\u003e\u003c/script\u003e\n```\n\nUsing 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.\n\n## Usage\n\nTo use this client, you must\n[obtain an access token](https://api.ynab.com/#authentication) from\nthe [Account Settings](https://app.ynab.com/settings) area of the YNAB web\napplication.\n\n```typescript\nconst ynab = require(\"ynab\");\nconst accessToken = \"b43439eaafe2_this_is_fake_b43439eaafe2\";\nconst ynabAPI = new ynab.API(accessToken);\n\n(async function() {\n  const budgetsResponse = await ynabAPI.budgets.getBudgets();\n  const budgets = budgetsResponse.data.budgets;\n  for (let budget of budgets) {\n    console.log(`Budget Name: ${budget.name}`);\n  }\n})();\n```\n\n### Error Handling\n\nIf a response is returned with a code \u003e= 300, instead of returning the response,\nthe response will be thrown as an error to be caught.\n\n```typescript\nconst ynab = require(\"ynab\");\nconst accessToken = \"invalid_token\";\nconst ynabAPI = new ynab.API(accessToken);\n\nconst budgetsResponse = ynabAPI.budgets\n  .getBudgets()\n  .then(budgetsResponse =\u003e {\n    // Won't get here because an error will be thrown\n  })\n  .catch(e =\u003e {\n    console.log(e);\n    // {\n    //   error: {\n    //    id: \"401\",\n    //    name: \"unauthorized\",\n    //    detail: \"Unauthorized\"\n    //   }\n    // }\n  });\n```\n\n### Rate Limiting\n\nThe API enforces [Rate Limiting](https://api.ynab.com/#rate-limiting).\n\nIf the rate limit is exceeded, a `429` [Error Response](https://api.ynab.com/#errors) will be returned from the API which will result in an [error being thrown](https://github.com/ynab/ynab-sdk-js#error-handling) in this library.\n\n\n## Examples\n\nSee the [examples](https://github.com/ynab/ynab-sdk-js/tree/main/examples)\nfolder for example usage scenarios.\n\n## Methods\n\nThe following methods are available in this library.\n\n|                            | Method                                                                                                                                                         | Description                                           |\n|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|\n| **User**                   | [user.getUser()](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/UserApi.d.ts)                                                                         | Returns authenticated user information                |\n| **Budgets**                | [budgets.getBudgets()](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/BudgetsApi.d.ts)                                                                | Returns budgets list with summary information         |\n|                            | [budgets.getBudgetById(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/BudgetsApi.d.ts)                                                    | Returns a single budget with all related entities     |\n|                            | [budgets.getBudgetSettingsById(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/BudgetsApi.d.ts)                                            | Returns settings for a budget                         |\n| **Accounts**               | [accounts.getAccounts(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/AccountsApi.d.ts)                                                    | Returns all accounts                                  |\n|                            | [accounts.getAccountById(budget_id, account_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/AccountsApi.d.ts)                                     | Returns a single account                              |\n| **Categories**             | [categories.getCategories(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/CategoriesApi.d.ts)                                              | Returns all categories grouped by category group.     |\n|                            | [categories.getCategoryById(budget_id, category_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/CategoriesApi.d.ts)                               | Returns a single category                             |\n|                            | [categories.getMonthCategoryById(budget_id, month, category_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/CategoriesApi.d.ts)                   | Returns a single category for a specific budget month |\n|                            | [categories.updateCategory(budget_id, category_id, category)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/CategoriesApi.d.ts)    | Update an existing category                     |\n|                            | [categories.updateMonthCategory(budget_id, month, category_id, month_category)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/CategoriesApi.d.ts)    | Update an existing month category                     |\n| **Payees**                 | [payees.getPayees(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/PayeesApi.d.ts)                                                          | Returns all payees                                    |\n|                            | [payees.getPayeeById(budget_id, payee_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/PayeesApi.d.ts)                                             | Returns single payee                                  |\n| **Payee Locations**        | [payee_locations.getPayeeLocations(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/PayeeLocationsApi.d.ts)                                 | Returns all payee locations                           |\n|                            | [payee_locations.getPayeeLocationById(budget_id, payee_location_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/PayeeLocationsApi.d.ts)           | Returns a single payee location                       |\n|                            | [payee_locations.getPayeeLocationsByPayee(budget_id, payee_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/PayeeLocationsApi.d.ts)                | Returns all payee locations for the specified payee   |\n| **Months**                 | [months.getBudgetMonths(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/MonthsApi.d.ts)                                                    | Returns all budget months                             |\n|                            | [months.getBudgetMonth(budget_id, month)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/MonthsApi.d.ts)                                              | Returns a single budget month                         |\n| **Transactions**           | [transactions.getTransactions(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                                        | Returns budget transactions                           |\n|                            | [transactions.getTransactionsByAccount(budget_id, account_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                   | Returns all transactions for a specified account      |\n|                            | [transactions.getTransactionsByCategory(budget_id, category_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                 | Returns all transactions for a specified category     |\n|                            | [transactions.getTransactionsByMonth(budget_id, month)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                          | Returns all transactions for a specified month     |\n|                            | [transactions.getTransactionsByType(budget_id, type)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                            | Returns all transactions of a specified type (\"unapproved\" or \"uncategorized\")     |\n|                            | [transactions.getTransactionById(budget_id, transaction_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                     | Returns a single transaction                          |\n|                            | [transactions.createTransaction(budget_id, data)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                                | Creates a single transaction                          |\n|                            | [transactions.createTransactions(budget_id, data)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                               | Creates multiple transactions                         |\n|                            | [transactions.updateTransaction(budget_id, transaction_id, data)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                | Updates a single transaction                          |\n|                            | [transactions.updateTransactions(budget_id, data)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                               | Updates multiple transactions                         |\n|                            | [transactions.deleteTransaction(budget_id, transaction_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                      | Deletes a transaction                                 |\n|                            | [transactions.importTransactions(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/TransactionsApi.d.ts)                                     | Imports transactions                                  |\n| **Scheduled Transactions** | [scheduled_transactions.getScheduledTransactions(budget_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/ScheduledTransactionsApi.d.ts)            | Returns all scheduled transactions                    |\n|                            | [scheduled_transactions.getScheduledTransactionById(budget_id, scheduled_transaction_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/ScheduledTransactionsApi.d.ts) | Returns a single scheduled transaction          |\n|                            | [scheduled_transactions.createScheduledTransaction(budget_id, data)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/ScheduledTransactionsApi.d.ts)    | Creates a single scheduled transaction          |\n|                            | [scheduled_transactions.updateScheduledTransaction(budget_id, scheduled_transaction_id, data)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/ScheduledTransactionsApi.d.ts)    | Updates a single scheduled transaction          |\n|                            | [scheduled_transactions.deleteScheduledTransaction(budget_id, scheduled_transaction_id)](https://github.com/ynab/ynab-sdk-js/blob/main/dist/apis/ScheduledTransactionsApi.d.ts)    | Deletes a single scheduled transaction          |\n\n### Utilities\n\nThere are several utilities available on the `utils` export to make working\nwith [ISO dates and milliunits](https://api.ynab.com/#formats) a bit\neasier.\n\n```typescript\n// Returns the current month (system timezone) in ISO 8601 format (i.e. '2015-12-01')\nutils.getCurrentMonthInISOFormat(): string;\n// Returns the current date (system timezone) in ISO 8601 format (i.e. '2015-12-15')\nutils.getCurrentDateInISOFormat(): string;\n// Converts an ISO 8601 formatted string to a JS date object\nutils.convertFromISODateString(isoDateString: string): Date;\n// Converts a milliunits amount to a currency amount\nutils.convertMilliUnitsToCurrencyAmount(milliunits: number, currencyDecimalDigits: number): number;\n```\n\n## Versioning\n\nThe version of this client is defined in the `package.json` file and follows [semantic versioning](https://semver.org/).  The version of this client is maintained independently and does not align with the the version of YNAB API itself (which is defined in the [OpenAPI spec](https://api.ynab.com/papi/open_api_spec.yaml)).  To determine which spec version of the YNAB API was used when generating this client you can refer to the \"description\" field in the `package.json` file.\n\n## License\n\nCopyright (c) 2022 You Need A Budget, LLC\n\nLicensed under the Apache-2.0 license\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fynab%2Fynab-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fynab%2Fynab-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fynab%2Fynab-sdk-js/lists"}