Skip to content

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.ts
index 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.ts
index d3f98c3a24..738bd7c0d2 100644
--- a/packages/api/methods.ts
+++ b/packages/api/methods.ts
@@ -1,5 +1,6 @@
// @ts-strict-ignore
import 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.ts
index 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.ts
index 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-ignore
import { 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.ts
new file mode 100644
index 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.md
new file mode 100644
index 0000000000..5727e30841
--- /dev/null
+++ b/upcoming-release-notes/4720.md
@@ -0,0 +1,6 @@
+---
+category: Maintenance
+authors: [baruchiro]
+---
+
+Added TypeScript types for transaction imports