A local-first personal finance app
[AI] Return what a bank sync reconciled from the API's runBankSync (#8998)
Andreaf36804f0460b
diff --git a/packages/api/methods.ts b/packages/api/methods.tsindex 33b0fd76a0..e008627083 100644--- a/packages/api/methods.ts+++ b/packages/api/methods.ts@@ -111,6 +111,12 @@ export async function sync() {return send('api/sync');}+/**+ * Run bank sync for one account, or for every linked account when no+ * `accountId` is given. Resolves with the ids of the transactions the sync+ * reconciled, so callers can tell an idle sync from one that imported+ * something without querying the transaction table themselves.+ */export async function runBankSync(args?: {accountId: APIAccountEntity['id'];}) {diff --git a/packages/docs/docs/api/reference.md b/packages/docs/docs/api/reference.mdindex 47ef90c91c..af4c341e1c 100644--- a/packages/docs/docs/api/reference.md+++ b/packages/docs/docs/api/reference.md@@ -875,10 +875,24 @@ Synchronizes the locally cached budget files with the server's copy.#### `runBankSync`-<Method name="runBankSync" args={[{ properties: [{ name: 'accountId', type: 'string' }] }]} returns="Promise<void>" />+<Method name="runBankSync" args={[{ name: 'args?', properties: [{ name: 'accountId', type: 'string' }] }]} returns="Promise<{ newTransactions: string[]; matchedTransactions: string[]; updatedAccounts: string[] }>" />Run the 3rd party (GoCardless, SimpleFIN) bank sync operation. This will download the transactions and insert them into the ledger.+Omit the argument to sync every linked account. If you pass the argument, include `accountId`.++Resolves with what the sync reconciled, so a caller can tell an idle sync from one that imported something without querying the ledger:++```js+{+ newTransactions: ['id', ...], // transactions the sync added+ matchedTransactions: ['id', ...], // existing transactions it updated+ updatedAccounts: ['id', ...] // accounts the sync added transactions to+}+```++A sync that adds or updates nothing resolves with three empty arrays. Errors still reject, so a resolved promise always means the sync succeeded. When syncing every account, one failing account rejects the whole call, but transactions already imported for the other accounts stay in the ledger and are not reported. After a rejection, check the ledger instead of assuming nothing was imported.+#### `runImport`<Method name="runImport" args={[{ name: 'budgetName', type: 'string' }, { name: 'func', type: 'func' }]} returns="Promise<void>" />diff --git a/packages/loot-core/src/server/accounts/app.ts b/packages/loot-core/src/server/accounts/app.tsindex 1ca2951a4d..276fb99e9f 100644--- a/packages/loot-core/src/server/accounts/app.ts+++ b/packages/loot-core/src/server/accounts/app.ts@@ -1279,7 +1279,7 @@ async function createGoCardlessWebToken({}}-type SyncResponse = {+export type SyncResponse = {newTransactions: Array<TransactionEntity['id']>;matchedTransactions: Array<TransactionEntity['id']>;updatedAccounts: Array<AccountEntity['id']>;diff --git a/packages/loot-core/src/server/api.test.ts b/packages/loot-core/src/server/api.test.tsindex 32f6ed6582..6df5dd7f9a 100644--- a/packages/loot-core/src/server/api.test.ts+++ b/packages/loot-core/src/server/api.test.ts@@ -1,3 +1,4 @@+import type { SyncResponseWithErrors } from '#server/accounts/app';import * as db from '#server/db';import * as sheet from '#server/sheet';import { getBankSyncError } from '#shared/errors';@@ -10,7 +11,7 @@ import { createBudget } from './budget/base';import * as prefs from './prefs';vi.mock('#shared/errors', () => ({- getBankSyncError: vi.fn(error => `Bank sync error: ${error}`),+ getBankSyncError: vi.fn(error => `Bank sync error: ${error.message}`),}));describe('API handlers', () => {@@ -33,10 +34,31 @@ describe('API handlers', () => {});describe('api/bank-sync', () => {+ const syncResult = ({+ newTransactions = [],+ matchedTransactions = [],+ updatedAccounts = [],+ errors = [],+ }: Partial<SyncResponseWithErrors> = {}): SyncResponseWithErrors => ({+ newTransactions,+ matchedTransactions,+ updatedAccounts,+ errors,+ });++ // A real sync error is an object, and the handler reads two fields off it:+ // getBankSyncError(errors[0]) for the message and errors[0].code for the+ // code it attaches. A bare string satisfies neither.+ const syncError = {+ type: 'SyncError' as const,+ accountId: 'account2',+ message: 'connection-failed',+ category: 'ACCOUNT_NEEDS_ATTENTION',+ code: 'ACCOUNT_NEEDS_ATTENTION',+ };+it('should sync a single account when accountId is provided', async () => {- handlers['accounts-bank-sync'] = vi- .fn()- .mockResolvedValue({ errors: [] });+ handlers['accounts-bank-sync'] = vi.fn().mockResolvedValue(syncResult());await handlers['api/bank-sync']({ accountId: 'account1' });expect(handlers['accounts-bank-sync']).toHaveBeenCalledWith({@@ -45,15 +67,110 @@ describe('API handlers', () => {});it('should handle errors in non batch sync', async () => {- handlers['accounts-bank-sync'] = vi.fn().mockResolvedValue({- errors: ['connection-failed'],- });+ handlers['accounts-bank-sync'] = vi+ .fn()+ .mockResolvedValue(syncResult({ errors: [syncError] }));await expect(handlers['api/bank-sync']({ accountId: 'account2' }),).rejects.toThrow('Bank sync error: connection-failed');- expect(getBankSyncError).toHaveBeenCalledWith('connection-failed');+ expect(getBankSyncError).toHaveBeenCalledWith(syncError);+ });++ it('attaches the error code to the thrown error', async () => {+ handlers['accounts-bank-sync'] = vi+ .fn()+ .mockResolvedValue(syncResult({ errors: [syncError] }));++ await expect(+ handlers['api/bank-sync']({ accountId: 'account2' }),+ ).rejects.toMatchObject({ code: 'ACCOUNT_NEEDS_ATTENTION' });+ });++ it('returns what the sync reconciled for a single account', async () => {+ handlers['accounts-bank-sync'] = vi.fn().mockResolvedValue(+ syncResult({+ newTransactions: ['t1', 't2'],+ matchedTransactions: ['t3'],+ updatedAccounts: ['account1'],+ }),+ );++ await expect(+ handlers['api/bank-sync']({ accountId: 'account1' }),+ ).resolves.toEqual({+ newTransactions: ['t1', 't2'],+ matchedTransactions: ['t3'],+ updatedAccounts: ['account1'],+ });+ });++ it('returns empty arrays when a sync reconciled nothing', async () => {+ handlers['accounts-bank-sync'] = vi.fn().mockResolvedValue(syncResult());++ // The caller has to be able to tell this apart from a sync that imported+ // something; both are successful, so an error is not the signal.+ await expect(+ handlers['api/bank-sync']({ accountId: 'account1' }),+ ).resolves.toEqual({+ newTransactions: [],+ matchedTransactions: [],+ updatedAccounts: [],+ });+ });++ it('merges results across both paths of a batch sync', async () => {+ handlers['accounts-get'] = vi.fn().mockResolvedValue([+ { id: 'simplefin1', account_sync_source: 'simpleFin' },+ { id: 'gocardless1', account_sync_source: 'goCardless' },+ ]);+ handlers['simplefin-batch-sync'] = vi.fn().mockResolvedValue([+ {+ accountId: 'simplefin1',+ res: syncResult({+ newTransactions: ['sf1'],+ updatedAccounts: ['simplefin1'],+ }),+ },+ ]);+ handlers['accounts-bank-sync'] = vi.fn().mockResolvedValue(+ syncResult({+ newTransactions: ['gc1'],+ matchedTransactions: ['gc2'],+ updatedAccounts: ['gocardless1'],+ }),+ );++ await expect(handlers['api/bank-sync']()).resolves.toEqual({+ newTransactions: ['sf1', 'gc1'],+ matchedTransactions: ['gc2'],+ updatedAccounts: ['simplefin1', 'gocardless1'],+ });++ // SimpleFIN accounts go through their own batch endpoint and must not be+ // synced a second time by the generic path.+ expect(handlers['accounts-bank-sync']).toHaveBeenCalledWith({+ ids: ['gocardless1'],+ });+ });++ it('still throws on error rather than returning partial results', async () => {+ handlers['accounts-get'] = vi+ .fn()+ .mockResolvedValue([+ { id: 'gocardless1', account_sync_source: 'goCardless' },+ ]);+ handlers['accounts-bank-sync'] = vi.fn().mockResolvedValue(+ syncResult({+ newTransactions: ['gc1'],+ errors: [syncError],+ }),+ );++ await expect(handlers['api/bank-sync']()).rejects.toThrow(+ 'Bank sync error: connection-failed',+ );});});diff --git a/packages/loot-core/src/server/api.ts b/packages/loot-core/src/server/api.tsindex 8939eae493..43d2b1c2f1 100644--- a/packages/loot-core/src/server/api.ts+++ b/packages/loot-core/src/server/api.ts@@ -26,6 +26,7 @@ import type {} from '#types/models';import type { ServerHandlers } from '#types/server-handlers';+import type { SyncResponse } from './accounts/app';import { addTransactions } from './accounts/sync';import {accountGroupModel,@@ -324,13 +325,31 @@ handlers['api/sync'] = async function () {handlers['api/bank-sync'] = async function (args) {const batchSync = args?.accountId == null;const allErrors = [];+ // `accounts-bank-sync` and `simplefin-batch-sync` already reconcile each+ // account and report what that produced. Collect it here so API consumers can+ // tell "synced, nothing new" from "synced, transactions are waiting" without+ // diffing the transaction table themselves.+ const newTransactions = [];+ const matchedTransactions = [];+ const updatedAccounts = [];++ // Appended one at a time rather than spread: these lists are as long as the+ // sync is big, and spreading a large array into push() passes every element+ // as an argument. `allErrors` above is bounded by the account count, so it+ // keeps the spread it already used.+ const collect = (res: SyncResponse) => {+ for (const id of res.newTransactions) newTransactions.push(id);+ for (const id of res.matchedTransactions) matchedTransactions.push(id);+ for (const id of res.updatedAccounts) updatedAccounts.push(id);+ };if (!batchSync) {- const { errors } = await handlers['accounts-bank-sync']({+ const res = await handlers['accounts-bank-sync']({ids: [args.accountId],});- allErrors.push(...errors);+ allErrors.push(...res.errors);+ collect(res);} else {const accountsData = await handlers['accounts-get']();const accountIdsToSync = accountsData.map(a => a.id);@@ -344,20 +363,26 @@ handlers['api/bank-sync'] = async function (args) {ids: simpleFinAccountIds,});- res.forEach(a => allErrors.push(...a.res.errors));+ res.forEach(a => {+ allErrors.push(...a.res.errors);+ collect(a.res);+ });}- const { errors } = await handlers['accounts-bank-sync']({+ const res = await handlers['accounts-bank-sync']({ids: accountIdsToSync.filter(a => !simpleFinAccountIds.includes(a)),});- allErrors.push(...errors);+ allErrors.push(...res.errors);+ collect(res);}const errors = allErrors.filter(e => e != null);if (errors.length > 0) {throw withErrorCode(new Error(getBankSyncError(errors[0])), errors[0].code);}++ return { newTransactions, matchedTransactions, updatedAccounts };};handlers['api/start-import'] = async function ({ budgetName }) {diff --git a/packages/loot-core/src/types/api-handlers.ts b/packages/loot-core/src/types/api-handlers.tsindex 9a209e55b4..5441cb3bda 100644--- a/packages/loot-core/src/types/api-handlers.ts+++ b/packages/loot-core/src/types/api-handlers.ts@@ -1,5 +1,8 @@// @ts-strict-ignore-import type { ImportTransactionsResult } from '#server/accounts/app';+import type {+ ImportTransactionsResult,+ SyncResponse,+} from '#server/accounts/app';import type { PayeeNameNormalization } from '#server/accounts/sync';import type {APIAccountEntity,@@ -142,7 +145,7 @@ export type ApiHandlers = {'api/bank-sync': (arg?: {accountId: APIAccountEntity['id'];- }) => Promise<void>;+ }) => Promise<SyncResponse>;'api/accounts-get': () => Promise<APIAccountEntity[]>;diff --git a/upcoming-release-notes/bank-sync-api-returns-reconciled-ids.md b/upcoming-release-notes/bank-sync-api-returns-reconciled-ids.mdnew file mode 100644index 0000000000..786e48fd47--- /dev/null+++ b/upcoming-release-notes/bank-sync-api-returns-reconciled-ids.md@@ -0,0 +1,6 @@+---+category: Features+authors: [agigante80]+---++The API's `runBankSync` now tells you what the sync did, so tools built on it can stay quiet when nothing new arrived and speak up when transactions are waiting.