A local-first personal finance app
[AI] Add api.importBudget() and api.exportBudget() (#8414)
Matiss Janis Aboltins168fe0d68b87
diff --git a/packages/api/methods.test.ts b/packages/api/methods.test.tsindex 0f3e084d98..b747381c0c 100644--- a/packages/api/methods.test.ts+++ b/packages/api/methods.test.ts@@ -75,6 +75,92 @@ describe('API setup and teardown', () => {});});+describe('API budget import/export', () => {+ const importedBudgetIds = new Set<string>();++ beforeEach(async () => {+ await api.loadBudget(budgetName);+ });++ afterEach(async () => {+ // Close any budget loaded by an import before removing its files+ await api.shutdown();++ for (const id of importedBudgetIds) {+ await fs.rm(path.join(__dirname, '/mocks/budgets/', id), {+ force: true,+ recursive: true,+ });+ }+ importedBudgetIds.clear();+ });++ // apis: exportBudget, importBudget+ test('exportBudget returns bytes that importBudget loads back', async () => {+ const accountId = await api.createAccount({ name: 'round-trip' }, 0);+ await api.addTransactions(accountId, [+ { date: '2023-10-01', amount: 1234, notes: 'round-trip transaction' },+ ]);++ const data = await api.exportBudget();+ expect(data).toBeInstanceOf(Uint8Array);+ expect(data.length).toBeGreaterThan(0);++ const { id } = await api.importBudget(data);+ expect(id).toBeTruthy();+ importedBudgetIds.add(id);++ // The imported budget is now the loaded one; verify the data+ // survived the round-trip+ const accounts = await api.getAccounts();+ expect(accounts).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ id: accountId, name: 'round-trip' }),+ ]),+ );++ const transactions = await api.getTransactions(+ accountId,+ '2023-10-01',+ '2023-10-31',+ );+ expect(transactions).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ amount: 1234,+ notes: 'round-trip transaction',+ }),+ ]),+ );+ });++ // apis: exportBudget, importBudget+ test('importBudget imports from a file path', async () => {+ const data = await api.exportBudget();+ const filepath = path.join(__dirname, '/mocks/budgets/', 'export.zip');+ await fs.writeFile(filepath, data);++ try {+ const { id } = await api.importBudget(filepath);+ expect(id).toBeTruthy();+ importedBudgetIds.add(id);+ } finally {+ await fs.rm(filepath, { force: true });+ }+ });++ // apis: importBudget+ test('importBudget rejects with an Error on failure', async () => {+ await expect(api.importBudget('/does/not/exist.zip')).rejects.toThrow(+ /^Error importing budget:/,+ );++ await expect(api.importBudget(new Uint8Array([1, 2, 3]))).rejects.toThrow(+ /^Error importing budget:/,+ );+ });+});+describe('API CRUD operations', () => {beforeEach(async () => {// load test budgetdiff --git a/packages/api/methods.ts b/packages/api/methods.tsindex a5188f57d7..8eb219af3c 100644--- a/packages/api/methods.ts+++ b/packages/api/methods.ts@@ -8,6 +8,7 @@ import type {APIScheduleEntity,APITagEntity,} from '@actual-app/core/server/api-models';+import type { ImportableBudgetType } from '@actual-app/core/server/importers/index';import type { Query } from '@actual-app/core/shared/query';import type { ImportTransactionsOpts } from '@actual-app/core/types/api-handlers';import type {@@ -49,6 +50,61 @@ export async function getBudgets() {return send('api/get-budgets');}+/**+ * Import a budget from an exported file — an Actual `.zip` export, or a+ * YNAB4/YNAB5 export. Accepts either a path to the file on the engine's+ * filesystem, or the raw file contents. Loads the imported budget and+ * returns its id.+ */+export async function importBudget(+ input: string | ArrayBuffer | Uint8Array,+ {+ type = 'actual',+ filename,+ }: { type?: ImportableBudgetType; filename?: string } = {},+): Promise<{ id: string }> {+ const result =+ typeof input === 'string'+ ? await send('import-budget', { filepath: input, type })+ : await send('import-budget', {+ buffer: toArrayBuffer(input),+ filename,+ type,+ });++ if (result.error) {+ throw new Error(`Error importing budget: ${result.error}`);+ }+ if (!result.id) {+ throw new Error('Error importing budget: no budget was loaded');+ }+ return { id: result.id };+}++/** Export the currently-loaded budget as a zip buffer. */+export async function exportBudget(): Promise<Uint8Array> {+ const result = await send('export-budget');++ if ('error' in result) {+ throw new Error(`Error exporting budget: ${result.error}`);+ }+ if (!result.data) {+ throw new Error('Error exporting budget: no data was returned');+ }+ return new Uint8Array(result.data);+}++function toArrayBuffer(data: ArrayBuffer | Uint8Array): ArrayBuffer {+ if (data instanceof Uint8Array) {+ // Copy into a fresh ArrayBuffer so that views into a larger (possibly+ // shared) buffer are not sent across the worker boundary as-is.+ const copy = new Uint8Array(data.byteLength);+ copy.set(data);+ return copy.buffer;+ }+ return data;+}+export async function sync() {return send('api/sync');}diff --git a/packages/api/models.ts b/packages/api/models.tsindex c4c753fb92..be383a120b 100644--- a/packages/api/models.ts+++ b/packages/api/models.ts@@ -1,2 +1,3 @@export type * from '@actual-app/core/server/api-models';+export type { ImportableBudgetType } from '@actual-app/core/server/importers/index';export type { SyncedPrefs as Preferences } from '@actual-app/core/types/prefs';diff --git a/packages/docs/docs/api/reference.md b/packages/docs/docs/api/reference.mdindex 59cb12c40e..f684aee1eb 100644--- a/packages/docs/docs/api/reference.md+++ b/packages/docs/docs/api/reference.md@@ -103,6 +103,8 @@ import APIList from './APIList';"getBudgets","loadBudget","downloadBudget",+"importBudget",+"exportBudget","batchBudgetUpdates","runQuery","getIDByName",@@ -820,6 +822,18 @@ Load a locally cached budget file.Load a budget file. If the file exists locally, it will load from there. Otherwise, it will download the file from the server.+#### `importBudget`++<Method name="importBudget" args={[{ name: 'input', type: 'string | ArrayBuffer | Uint8Array' }, { name: 'options', type: "{ type?: 'actual' | 'ynab4' | 'ynab5', filename?: string }?" }]} returns="Promise<{ id: string }>" />++Import a budget from an exported file and load it. `input` is either a path to the file or the raw file contents. By default the file is treated as an Actual export (a `.zip` file containing `db.sqlite` and `metadata.json`); pass `type: 'ynab4'` or `type: 'ynab5'` to import a YNAB export instead. When passing raw contents, you can supply the original file name with `filename` — some import types use it to derive the budget name. Returns the id of the imported budget, which is now the loaded budget.++#### `exportBudget`++<Method name="exportBudget" args={[]} returns="Promise<Uint8Array>" />++Export the currently loaded budget as raw bytes in the zip format. You can save the bytes to a `.zip` file, or pass them back to `importBudget` to restore the budget later.+#### `batchBudgetUpdates`<Method name="batchBudgetUpdates" args={[{ name: 'func', type: 'func' }]} returns="Promise<void>" />diff --git a/packages/loot-core/src/server/budgetfiles/app.ts b/packages/loot-core/src/server/budgetfiles/app.tsindex 8d841945d3..da6fbce9b9 100644--- a/packages/loot-core/src/server/budgetfiles/app.ts+++ b/packages/loot-core/src/server/budgetfiles/app.ts@@ -467,19 +467,44 @@ async function createBudget({async function importBudget({filepath,+ buffer,+ filename,type,}: {- filepath: string;type: ImportableBudgetType;-}): Promise<{ error?: string }> {+ /** Path to the file to import, on the engine's filesystem. */+ filepath?: string;+ /** Raw contents of the file to import; alternative to `filepath`. */+ buffer?: ArrayBuffer;+ /**+ * Original name of the imported file; only used together with `buffer`,+ * to derive the budget name for some import types.+ */+ filename?: string;+}): Promise<{ error?: string; id?: string }> {try {- if (!(await fs.exists(filepath))) {- throw new Error(`File not found at the provided path: ${filepath}`);+ let contents: Buffer;+ let name: string;+ if (filepath != null) {+ if (!(await fs.exists(filepath))) {+ throw new Error(`File not found at the provided path: ${filepath}`);+ }++ contents = Buffer.from(await fs.readFile(filepath, 'binary'));+ name = filepath;+ } else if (buffer != null) {+ contents = Buffer.from(buffer);+ name = filename || 'budget-import';+ } else {+ throw new Error('Either `filepath` or `buffer` must be given');}- const buffer = Buffer.from(await fs.readFile(filepath, 'binary'));- const results = await handleBudgetImport(type, filepath, buffer);- return results || {};+ const results = await handleBudgetImport(type, name, contents);+ if (results && results.error) {+ return results;+ }+ // A successful import leaves the imported budget loaded+ return { id: prefs.getPrefs()?.id };} catch (err) {err.message = 'Error importing budget: ' + err.message;captureException(err);diff --git a/upcoming-release-notes/add-api-import-export-budget.md b/upcoming-release-notes/add-api-import-export-budget.mdnew file mode 100644index 0000000000..e645066abe--- /dev/null+++ b/upcoming-release-notes/add-api-import-export-budget.md@@ -0,0 +1,6 @@+---+category: Enhancements+authors: [MatissJanis]+---++Add importBudget and exportBudget functions to the API for importing and exporting budget files directly