A local-first personal finance app
[Proposal] Enhance transaction import functionality with new Transaction type and type annotations (#4720)
Baruch Odem (Rothkoff)cac318255dde
diff --git a/packages/api/methods.test.ts b/packages/api/methods.test.tsindex 1ba972b00a..b40657aa9d 100644--- a/packages/api/methods.test.ts+++ b/packages/api/methods.test.ts@@ -568,8 +568,20 @@ describe('API CRUD operations', () => {const accountId = await api.createAccount({ name: 'test-account' }, 0);let newTransaction = [- { date: '2023-11-03', imported_id: '11', amount: 100, notes: 'notes' },- { date: '2023-11-03', imported_id: '12', amount: 100, notes: '' },+ {+ account: accountId,+ date: '2023-11-03',+ imported_id: '11',+ amount: 100,+ notes: 'notes',+ },+ {+ account: accountId,+ date: '2023-11-03',+ imported_id: '12',+ amount: 100,+ notes: '',+ },];const addResult = await api.addTransactions(accountId, newTransaction, {@@ -597,9 +609,27 @@ describe('API CRUD operations', () => {expect(transactions).toHaveLength(2);newTransaction = [- { date: '2023-12-03', imported_id: '11', amount: 100, notes: 'notes' },- { date: '2023-12-03', imported_id: '12', amount: 100, notes: 'notes' },- { date: '2023-12-03', imported_id: '22', amount: 200, notes: '' },+ {+ account: accountId,+ date: '2023-12-03',+ imported_id: '11',+ amount: 100,+ notes: 'notes',+ },+ {+ account: accountId,+ date: '2023-12-03',+ imported_id: '12',+ amount: 100,+ notes: 'notes',+ },+ {+ account: accountId,+ date: '2023-12-03',+ imported_id: '22',+ amount: 200,+ notes: '',+ },];const reconciled = await api.importTransactions(accountId, newTransaction);diff --git a/packages/api/methods.ts b/packages/api/methods.tsindex d3f98c3a24..738bd7c0d2 100644--- a/packages/api/methods.ts+++ b/packages/api/methods.ts@@ -1,5 +1,6 @@// @ts-strict-ignoreimport type { Handlers } from 'loot-core/types/handlers';+import type { ImportTransactionEntity } from 'loot-core/types/models/import-transaction';import * as injected from './injected';@@ -98,8 +99,8 @@ export interface ImportTransactionsOpts {}export function importTransactions(- accountId,- transactions,+ accountId: string,+ transactions: ImportTransactionEntity[],opts: ImportTransactionsOpts = {defaultCleared: true,},diff --git a/packages/loot-core/src/server/accounts/app.ts b/packages/loot-core/src/server/accounts/app.tsindex c301bab5c0..482bb3d304 100644--- a/packages/loot-core/src/server/accounts/app.ts+++ b/packages/loot-core/src/server/accounts/app.ts@@ -1074,7 +1074,7 @@ async function simpleFinBatchSync({return retVal;}-type ImportTransactionsResult = bankSync.ReconcileTransactionsResult & {+export type ImportTransactionsResult = bankSync.ReconcileTransactionsResult & {errors: Array<{message: string;}>;diff --git a/packages/loot-core/src/types/api-handlers.ts b/packages/loot-core/src/types/api-handlers.tsindex 7a2c45f398..83e5c1be2e 100644--- a/packages/loot-core/src/types/api-handlers.ts+++ b/packages/loot-core/src/types/api-handlers.ts@@ -1,6 +1,7 @@// @ts-strict-ignoreimport { ImportTransactionsOpts } from '@actual-app/api';+import type { ImportTransactionsResult } from '../server/accounts/app';import type {APIAccountEntity,APICategoryEntity,@@ -85,11 +86,7 @@ export interface ApiHandlers {transactions;isPreview?;opts?: ImportTransactionsOpts;- }) => Promise<{- errors?: { message: string }[];- added;- updated;- }>;+ }) => Promise<ImportTransactionsResult>;'api/transactions-add': (arg: {accountId;diff --git a/packages/loot-core/src/types/models/import-transaction.d.ts b/packages/loot-core/src/types/models/import-transaction.d.tsnew file mode 100644index 0000000000..ea586a6787--- /dev/null+++ b/packages/loot-core/src/types/models/import-transaction.d.ts@@ -0,0 +1,56 @@+/**+ * Represents a transaction object specifically for import operations.+ * This type is used when importing transactions from external sources.+ */+export interface ImportTransactionEntity {+ /** Required. The ID of the account this transaction belongs to */+ account: string;++ /** Required. Transaction date in YYYY-MM-DD format */+ date: string;++ /** A currency amount as an integer representing the value without decimal places.+ * For example, USD amount of $120.30 would be 12030 */+ amount?: number;++ /** In a create/import request, this overrides payee_name.+ * Should be an existing payee ID */+ payee?: string;++ /** If given, a payee will be created with this name.+ * If this matches an already existing payee, that payee will be used.+ * Only available in create/import requests */+ payee_name?: string;++ /** This can be anything. Meant to represent the raw description when importing,+ * allowing the user to see the original value */+ imported_payee?: string;++ /** The ID of the category to assign to this transaction */+ category?: string;++ /** Any additional notes for the transaction */+ notes?: string;++ /** A unique id usually given by the bank, if importing.+ * Use this to avoid duplicate transactions */+ imported_id?: string;++ /** If a transfer, the id of the corresponding transaction in the other account.+ * You should not change this for existing transfers.+ * Only set this when importing */+ transfer_id?: string;++ /** A flag indicating if the transaction has cleared or not */+ cleared?: boolean;++ /** An array of subtransactions for a split transaction.+ * Only available in get or create/import requests.+ * If amounts don't equal total amount, API call will succeed but error will show in app */+ subtransactions?: Array<{+ /** The only required field for subtransactions */+ amount: number;+ category?: string;+ notes?: string;+ }>;+}diff --git a/upcoming-release-notes/4720.md b/upcoming-release-notes/4720.mdnew file mode 100644index 0000000000..5727e30841--- /dev/null+++ b/upcoming-release-notes/4720.md@@ -0,0 +1,6 @@+---+category: Maintenance+authors: [baruchiro]+---++Added TypeScript types for transaction imports