A local-first personal finance app
[AI] Fix nYNAB import for YNAB plan API wrapper rename (#8184)
Kyle Bremont80c9d05ee41a
diff --git a/packages/docs/docs/migration/nynab.mdx b/packages/docs/docs/migration/nynab.mdxindex 6f087b38ad..5290922396 100644--- a/packages/docs/docs/migration/nynab.mdx+++ b/packages/docs/docs/migration/nynab.mdx@@ -31,7 +31,7 @@ The alternative options all require a YNAB Personal Access Token. Follow these s:::caution-The token is only displayed once. Copy it to a safe place before closing the page. More information about the YNAB API can be found at [api.youneedabudget.com](https://api.youneedabudget.com/).+The token is only displayed once. Copy it to a safe place before closing the page. More information about the YNAB API can be found at [api.ynab.com](https://api.ynab.com/).:::### Options@@ -43,7 +43,7 @@ This method uses YNAB's official API documentation website, which has a built-inBefore you start, [get your YNAB API token](#getting-your-ynab-api-token) if you have not already.-#### Step 1: Get Your Budget ID+#### Step 1: Get Your Plan ID1. Open the [Get All Plans endpoint](https://api.ynab.com/v1#tag/plans/GET/plans) in your browser2. Click **Try it out**, then click **Execute** (or "Test Request")@@ -54,32 +54,22 @@ Before you start, [get your YNAB API token](#getting-your-ynab-api-token) if you-4. In the response body, find the entry for your budget and copy its `id` value (for example, `8800b4e7-937f-4cdb-a7e7-fc35b794f85b`)+4. In the response body, find the entry for your plan and copy its `id` value (for example, `8800b4e7-937f-4cdb-a7e7-fc35b794f85b`)-#### Step 2: Download Your Budget+#### Step 2: Download Your Plan1. Open the [Get a Plan endpoint](https://api.ynab.com/v1#tag/plans/GET/plans/{plan_id}) in your browser2. Click **Try it out**-3. Paste your budget ID into the `plan_id` field and click **Send**+3. Paste your plan ID into the `plan_id` field and click **Send**4. Once the response appears in the Body panel on the right, click **Download** to save the JSON file-#### Step 3: Fix the JSON File--The file from this endpoint uses a slightly different format than what Actual expects. You need to make one small edit before importing.--1. Open the downloaded JSON file in a plain text editor (Notepad on Windows, TextEdit on macOS)-2. At the very start of the file, find the text `"plan"` and change it to `"budget"`-3. Save the file----:::warning-Skipping this step causes a **not-ynab5** error when importing. Make sure the file begins with `{"data": {"budget"` before proceeding.+:::note+If the import later fails with a **not-ynab5** error, you are likely on an older version of Actual. Either update Actual, or open the downloaded file in a plain text editor and change the leading `"plan"` to `"budget"` before importing.:::</TabItem>@@ -146,37 +136,37 @@ When done, your budget file is saved to your Downloads folder with a name like `</TabItem><TabItem value="curl" label="cURL">-If you are comfortable with the command line, you can download your budget directly using `curl`.+If you are comfortable with the command line, you can download your plan directly using `curl`.Before you start, [get your YNAB API token](#getting-your-ynab-api-token) if you have not already.-#### Step 1: Get Your Budget ID+#### Step 1: Get Your Plan IDOpen a terminal window and run the following, replacing `<ACCESS_TOKEN>` with the token you copied:```-curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets+curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.ynab.com/v1/plans```-This returns a list of your budgets. Find the `id` for the budget you want to export.+This returns a list of your plans. Find the `id` for the plan you want to export.:::noteTo format the output more readably, pipe it to `jq` (install with `brew install jq` on macOS):```-curl -sH "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets | jq -r '.data.budgets | sort_by(.last_modified_on) | reverse | .[] | "\(.name): \(.id)"'+curl -sH "Authorization: Bearer <ACCESS_TOKEN>" https://api.ynab.com/v1/plans | jq -r '.data.plans | sort_by(.last_modified_on) | reverse | .[] | "\(.name): \(.id)"'```If you see the error `Invoke-WebRequest : Cannot bind parameter 'Headers'` on Windows, use `curl.exe` instead of `curl`.:::-#### Step 2: Download Your Budget+#### Step 2: Download Your Plan```-curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.youneedabudget.com/v1/budgets/<BUDGET ID> --output budget.json+curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.ynab.com/v1/plans/<PLAN ID> --output plan.json```-Replace `<ACCESS_TOKEN>` and `<BUDGET ID>` with your values.+Replace `<ACCESS_TOKEN>` and `<PLAN ID>` with your values.</TabItem></Tabs>diff --git a/packages/docs/static/img/migrating/nynab-api-ui-json-edit.png b/packages/docs/static/img/migrating/nynab-api-ui-json-edit.pngdeleted file mode 100644index 6b7927f922..0000000000Binary files a/packages/docs/static/img/migrating/nynab-api-ui-json-edit.png and /dev/null differdiff --git a/packages/loot-core/src/server/importers/ynab5.test.ts b/packages/loot-core/src/server/importers/ynab5.test.tsnew file mode 100644index 0000000000..6b232bff59--- /dev/null+++ b/packages/loot-core/src/server/importers/ynab5.test.ts@@ -0,0 +1,33 @@+import { describe, expect, it } from 'vitest';++import { getBudgetName, parseFile } from './ynab5';++function toBuffer(obj: unknown): Buffer {+ return Buffer.from(JSON.stringify(obj));+}++describe('ynab5 parseFile', () => {+ it('unwraps the legacy `budget` wrapper', () => {+ const data = parseFile(+ toBuffer({ data: { budget: { name: 'Legacy', accounts: [] } } }),+ );++ expect(data.name).toBe('Legacy');+ expect(getBudgetName('legacy.json', data)).toBe('Legacy');+ });++ it('unwraps the renamed `plan` wrapper from the current YNAB API', () => {+ const data = parseFile(+ toBuffer({ data: { plan: { name: 'Modern', accounts: [] } } }),+ );++ expect(data.name).toBe('Modern');+ expect(getBudgetName('modern.json', data)).toBe('Modern');+ });++ it('returns an already-unwrapped object unchanged', () => {+ const data = parseFile(toBuffer({ name: 'Bare', accounts: [] }));++ expect(data.name).toBe('Bare');+ });+});diff --git a/packages/loot-core/src/server/importers/ynab5.ts b/packages/loot-core/src/server/importers/ynab5.tsindex 8e4e077629..6584efac9b 100644--- a/packages/loot-core/src/server/importers/ynab5.ts+++ b/packages/loot-core/src/server/importers/ynab5.ts@@ -1150,7 +1150,11 @@ export function parseFile(buffer: Buffer): Budget {if (data.data) {data = data.data;}- if (data.budget) {+ // YNAB renamed the top-level wrapper from `budget` to `plan` (API v1.78+).+ // Older exports and third-party tools still emit `budget`, so accept both.+ if (data.plan) {+ data = data.plan;+ } else if (data.budget) {data = data.budget;}diff --git a/upcoming-release-notes/ynab5-import-plan-key.md b/upcoming-release-notes/ynab5-import-plan-key.mdnew file mode 100644index 0000000000..64f8bcb70e--- /dev/null+++ b/upcoming-release-notes/ynab5-import-plan-key.md@@ -0,0 +1,6 @@+---+category: Bugfix+authors: [kbremont]+---++Fix nYNAB import failing with a not-ynab5 error for exports from YNAB's current API