Skip to content

A local-first personal finance app

[AI] Expose parent transaction fields to split rule formulas (#8898)

Krzysztof Wójt93508bc6a3af
diff --git a/packages/desktop-client/src/components/formula/formulaBadgeRanges.ts b/packages/desktop-client/src/components/formula/formulaBadgeRanges.ts
index 75cdb52ca4..4172b4ee8e 100644
--- a/packages/desktop-client/src/components/formula/formulaBadgeRanges.ts
+++ b/packages/desktop-client/src/components/formula/formulaBadgeRanges.ts
@@ -93,6 +93,10 @@ const transactionNamedExpressionBadges: Record<string, string> = {
reconciled: 'reconciled',
balance: 'balance',
parent_amount: 'parent_amount',
+ parent_notes: 'parent_notes',
+ parent_imported_payee: 'parent_imported_payee',
+ parent_payee: 'parent_payee',
+ parent_account: 'parent_account',
};
const queryNameFunctions = new Set([
diff --git a/packages/desktop-client/src/components/formula/formulaCatalog.ts b/packages/desktop-client/src/components/formula/formulaCatalog.ts
index 8680076f11..32484cbfae 100644
--- a/packages/desktop-client/src/components/formula/formulaCatalog.ts
+++ b/packages/desktop-client/src/components/formula/formulaCatalog.ts
@@ -1456,6 +1456,42 @@ export function getRuleFieldCompletions(): Completion[] {
'The amount of the parent transaction in cents in split transactions.\n\nExample: =(parent_amount / 100) * .05',
),
},
+ {
+ label: 'parent_notes',
+ type: 'variable',
+ section: ruleFieldSection,
+ boost: 5,
+ info: t(
+ 'Notes of the parent transaction in split rules. Empty when absent.',
+ ),
+ },
+ {
+ label: 'parent_imported_payee',
+ type: 'variable',
+ section: ruleFieldSection,
+ boost: 5,
+ info: t(
+ 'Imported payee text of the parent transaction in split rules. Empty when absent.',
+ ),
+ },
+ {
+ label: 'parent_payee',
+ type: 'variable',
+ section: ruleFieldSection,
+ boost: 5,
+ info: t(
+ 'Payee ID of the parent transaction in split rules. Empty when absent.',
+ ),
+ },
+ {
+ label: 'parent_account',
+ type: 'variable',
+ section: ruleFieldSection,
+ boost: 5,
+ info: t(
+ 'Account ID of the parent transaction in split rules. Empty when absent.',
+ ),
+ },
];
}
diff --git a/packages/loot-core/src/server/accounts/split-formula-import.test.ts b/packages/loot-core/src/server/accounts/split-formula-import.test.ts
new file mode 100644
index 0000000000..cca9c1990b
--- /dev/null
+++ b/packages/loot-core/src/server/accounts/split-formula-import.test.ts
@@ -0,0 +1,168 @@
+import * as db from '#server/db';
+import { loadMappings } from '#server/db/mappings';
+import { createSchedule } from '#server/schedules/app';
+import { insertRule, loadRules } from '#server/transactions/transaction-rules';
+
+import { reconcileTransactions } from './sync';
+
+beforeEach(async () => {
+ await global.emptyDatabase()();
+ await loadMappings();
+ await loadRules();
+});
+
+test('import keeps one parent, matches its schedule and transfers only the formula split', async () => {
+ await db.insertAccount({ id: 'source', name: 'Source', offbudget: 0 });
+ await db.insertAccount({
+ id: 'destination',
+ name: 'Destination',
+ offbudget: 1,
+ });
+ await db.insertPayee({
+ id: 'transfer-source',
+ name: '',
+ transfer_acct: 'source',
+ });
+ await db.insertPayee({
+ id: 'transfer-destination',
+ name: '',
+ transfer_acct: 'destination',
+ });
+ await db.insertPayee({ id: 'bank', name: 'Bank' });
+ await db.insertCategoryGroup({ id: 'group', name: 'Expenses', is_income: 0 });
+ await db.insertCategory({
+ id: 'category',
+ name: 'Payment',
+ cat_group: 'group',
+ is_income: 0,
+ });
+
+ const schedule = await createSchedule({
+ schedule: { name: 'Payment', posts_transaction: false },
+ conditions: [
+ { field: 'account', op: 'is', value: 'source' },
+ { field: 'amount', op: 'isapprox', value: -3000 },
+ {
+ field: 'date',
+ op: 'isapprox',
+ value: { start: '2024-01-15', frequency: 'monthly', patterns: [] },
+ },
+ { field: 'notes', op: 'contains', value: 'ITEM:' },
+ ],
+ });
+ await insertRule({
+ stage: 'pre',
+ conditionsOp: 'and',
+ conditions: [
+ { field: 'account', op: 'is', value: 'source' },
+ { field: 'notes', op: 'contains', value: 'ITEM:' },
+ ],
+ actions: [
+ {
+ op: 'set-split-amount',
+ value: null,
+ options: {
+ splitIndex: 1,
+ method: 'formula',
+ formula:
+ '=-VALUE(MID(parent_notes, SEARCH("ITEM: ", parent_notes)+6, SEARCH("USD", parent_notes, SEARCH("ITEM: ", parent_notes))-SEARCH("ITEM: ", parent_notes)-6))',
+ },
+ },
+ {
+ op: 'set',
+ field: 'payee',
+ value: 'transfer-destination',
+ options: { splitIndex: 1 },
+ },
+ {
+ op: 'set',
+ field: 'category',
+ value: 'category',
+ options: { splitIndex: 1 },
+ },
+ {
+ op: 'set-split-amount',
+ value: null,
+ options: { splitIndex: 2, method: 'remainder' },
+ },
+ { op: 'set', field: 'payee', value: 'bank', options: { splitIndex: 2 } },
+ {
+ op: 'set',
+ field: 'category',
+ value: 'category',
+ options: { splitIndex: 2 },
+ },
+ ],
+ });
+
+ const imported = {
+ date: '2024-01-15',
+ amount: -3000,
+ imported_id: 'bank-import-id',
+ notes: 'Payment in USD: ITEM: 25.50USD FEE: 4.50USD',
+ imported_payee: 'Imported bank',
+ cleared: true,
+ };
+ await reconcileTransactions('source', [imported]);
+ const read = () =>
+ db.all<db.DbViewTransactionInternal>(
+ 'SELECT * FROM v_transactions_internal',
+ );
+ const rows = await read();
+ const parent = rows.find(row => row.is_parent);
+ if (!parent) throw new Error('Missing split parent');
+ expect(parent).toMatchObject({
+ account: 'source',
+ imported_id: imported.imported_id,
+ notes: imported.notes,
+ imported_payee: imported.imported_payee,
+ amount: -3000,
+ cleared: 1,
+ schedule,
+ });
+ const children = rows.filter(row => row.parent_id === parent.id);
+ expect(children).toHaveLength(2);
+ expect(children).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ amount: -2550,
+ payee: 'transfer-destination',
+ category: 'category',
+ cleared: 1,
+ }),
+ expect.objectContaining({
+ amount: -450,
+ payee: 'bank',
+ category: 'category',
+ cleared: 1,
+ }),
+ ]),
+ );
+ expect(children.reduce((sum, row) => sum + row.amount, 0)).toBe(
+ parent.amount,
+ );
+ const destination = rows.filter(row => row.account === 'destination');
+ expect(destination).toHaveLength(1);
+ expect(destination[0]).toMatchObject({
+ amount: 2550,
+ transfer_id: children.find(row => row.amount === -2550)?.id,
+ });
+ expect(rows).toHaveLength(4);
+
+ // A repeated bank import must preserve identity and not create another transfer.
+ await reconcileTransactions('source', [imported]);
+ const reimported = await read();
+ expect(reimported.map(row => row.id).sort()).toEqual(
+ rows.map(row => row.id).sort(),
+ );
+ expect(reimported.find(row => row.id === parent.id)).toMatchObject({
+ imported_id: imported.imported_id,
+ notes: imported.notes,
+ schedule,
+ });
+ expect(
+ reimported
+ .filter(row => row.account === 'destination')
+ .reduce((sum, row) => sum + row.amount, 0),
+ ).toBe(2550);
+});
diff --git a/packages/loot-core/src/server/rules/action.ts b/packages/loot-core/src/server/rules/action.ts
index 1fa741939c..4882abf977 100644
--- a/packages/loot-core/src/server/rules/action.ts
+++ b/packages/loot-core/src/server/rules/action.ts
@@ -343,6 +343,11 @@ export class Action {
} else {
cellValue = fieldValues[key];
}
+ // Parent text is data, even when it looks like a spreadsheet formula,
+ // date or number. The apostrophe is HyperFormula's literal-text escape.
+ if (key.startsWith('parent_') && typeof cellValue === 'string') {
+ cellValue = `'${cellValue}`;
+ }
hfInstance.addNamedExpression(key, cellValue);
}
hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [
diff --git a/packages/loot-core/src/server/rules/rule.ts b/packages/loot-core/src/server/rules/rule.ts
index 465170f3da..9d5deebed5 100644
--- a/packages/loot-core/src/server/rules/rule.ts
+++ b/packages/loot-core/src/server/rules/rule.ts
@@ -43,7 +43,16 @@ function execSplitActions(actions: Action[], transaction) {
const { data } = addSplitTransaction(newTransactions, transaction.id);
newTransactions = data;
}
+ // Keep parent data separate from the child fields changed by split actions.
newTransactions[splitTransactionIndex].parent_amount = transaction.amount;
+ newTransactions[splitTransactionIndex].parent_notes =
+ transaction.notes ?? '';
+ newTransactions[splitTransactionIndex].parent_imported_payee =
+ transaction.imported_payee ?? '';
+ newTransactions[splitTransactionIndex].parent_payee =
+ transaction.payee ?? '';
+ newTransactions[splitTransactionIndex].parent_account =
+ transaction.account ?? '';
newTransactions[splitTransactionIndex].balance = transaction.balance;
newTransactions[splitTransactionIndex]._balanceOfPrefetched =
transaction._balanceOfPrefetched;
diff --git a/packages/loot-core/src/server/rules/split-parent-context.test.ts b/packages/loot-core/src/server/rules/split-parent-context.test.ts
new file mode 100644
index 0000000000..1a65f38937
--- /dev/null
+++ b/packages/loot-core/src/server/rules/split-parent-context.test.ts
@@ -0,0 +1,121 @@
+import { finalizeTransactionForRules } from '#server/transactions/transaction-rules';
+
+import { Rule } from './rule';
+
+function splitRule(formula: string) {
+ return new Rule({
+ conditionsOp: 'and',
+ conditions: [{ field: 'amount', op: 'lt', value: 0 }],
+ actions: [
+ {
+ op: 'set',
+ field: 'notes',
+ value: 'child notes',
+ options: { splitIndex: 1 },
+ },
+ {
+ op: 'set-split-amount',
+ field: 'amount',
+ value: 0,
+ options: { splitIndex: 1, method: 'formula', formula },
+ },
+ {
+ op: 'set-split-amount',
+ field: 'amount',
+ value: 0,
+ options: { splitIndex: 2, method: 'remainder' },
+ },
+ ],
+ });
+}
+
+const parent = {
+ id: 'parent',
+ account: 'source-account',
+ payee: 'source-payee',
+ amount: -3000,
+ notes: 'ITEM: 25.50USD FEE: 4.50USD',
+ imported_payee: 'Imported bank',
+ imported_id: 'bank-id',
+ cleared: true,
+ schedule: 'schedule-id',
+ date: '2024-01-15',
+};
+
+describe('split parent formula context', () => {
+ test('keeps parent_amount in cents', () => {
+ expect(
+ splitRule('=INTEGER_TO_AMOUNT(parent_amount) / 2').exec(parent),
+ ).toMatchObject({
+ subtransactions: [{ amount: -1500 }, { amount: -1500 }],
+ });
+ });
+
+ test('reads parent notes independently of child notes', () => {
+ expect(
+ splitRule('=IF(parent_notes="' + parent.notes + '", -1, -2)').exec(
+ parent,
+ ),
+ ).toMatchObject({
+ subtransactions: [
+ { amount: -100, notes: 'child notes' },
+ { amount: -2900 },
+ ],
+ });
+ });
+
+ test('parses a decimal amount from parent notes using native functions', async () => {
+ const result = splitRule(
+ '=-VALUE(MID(parent_notes, SEARCH("ITEM: ", parent_notes)+6, SEARCH("USD", parent_notes, SEARCH("ITEM: ", parent_notes))-SEARCH("ITEM: ", parent_notes)-6))',
+ ).apply(parent);
+ expect(result).toMatchObject({
+ ...parent,
+ payee: null,
+ is_parent: true,
+ subtransactions: [{ amount: -2550 }, { amount: -450 }],
+ });
+ const finalized = await finalizeTransactionForRules(result);
+ for (const transaction of [finalized, ...finalized.subtransactions]) {
+ expect(
+ Object.keys(transaction).filter(key => key.startsWith('parent_')),
+ ).toEqual(transaction.is_child ? ['parent_id'] : []);
+ }
+ });
+
+ test.each([
+ 'parent_imported_payee',
+ 'parent_payee',
+ 'parent_account',
+ ] as const)('exposes %s without overwriting child fields', field => {
+ const original = {
+ parent_imported_payee: parent.imported_payee,
+ parent_payee: parent.payee,
+ parent_account: parent.account,
+ };
+ expect(
+ splitRule(`=IF(${field}="${original[field]}", -1, -2)`).exec(parent),
+ ).toMatchObject({
+ subtransactions: [{ amount: -100 }, { amount: -2900 }],
+ });
+ });
+
+ test.each(['=1+1', '00123', '2024-01-15', "'quoted"])(
+ 'treats parent text %s literally',
+ notes => {
+ expect(
+ splitRule(`=IF(parent_notes="${notes}", -1, -2)`).exec({
+ ...parent,
+ notes,
+ }),
+ ).toMatchObject({
+ subtransactions: [{ amount: -100 }, { amount: -2900 }],
+ });
+ },
+ );
+
+ test('absent parent text is empty', () => {
+ expect(
+ splitRule('=IF(parent_notes="", -1, -2)').exec({ amount: -300 }),
+ ).toMatchObject({ subtransactions: [{ amount: -100 }, { amount: -200 }] });
+ });
+});
diff --git a/packages/loot-core/src/server/transactions/transaction-rules.ts b/packages/loot-core/src/server/transactions/transaction-rules.ts
index 843a986a40..f4efc50a60 100644
--- a/packages/loot-core/src/server/transactions/transaction-rules.ts
+++ b/packages/loot-core/src/server/transactions/transaction-rules.ts
@@ -1005,6 +1005,10 @@ export type TransactionForRules = TransactionEntity & {
/** The transaction's category's group id; see prepareTransactionForRules */
category_group?: string;
parent_amount?: number;
+ parent_notes?: string;
+ parent_imported_payee?: string;
+ parent_payee?: string;
+ parent_account?: string;
/** Prefetched cent balances for BALANCE_OF("…") in rule formulas; cleared in finalize */
_balanceOfPrefetched?: Map<string, number>;
};
@@ -1197,8 +1201,16 @@ export async function finalizeTransactionForRules(
delete trans._balanceOfPrefetched;
}
- if ('parent_amount' in trans) {
- delete trans.parent_amount;
+ for (const field of [
+ 'parent_amount',
+ 'parent_notes',
+ 'parent_imported_payee',
+ 'parent_payee',
+ 'parent_account',
+ ] as const) {
+ if (field in trans) {
+ delete trans[field];
+ }
}
if (trans.subtransactions?.length) {
@@ -1211,8 +1223,16 @@ export async function finalizeTransactionForRules(
delete stx._balanceOfPrefetched;
}
- if ('parent_amount' in stx) {
- delete stx.parent_amount;
+ for (const field of [
+ 'parent_amount',
+ 'parent_notes',
+ 'parent_imported_payee',
+ 'parent_payee',
+ 'parent_account',
+ ] as const) {
+ if (field in stx) {
+ delete stx[field];
+ }
}
});
}
diff --git a/upcoming-release-notes/split-parent-formula-context.md b/upcoming-release-notes/split-parent-formula-context.md
new file mode 100644
index 0000000000..c3cb588752
--- /dev/null
+++ b/upcoming-release-notes/split-parent-formula-context.md
@@ -0,0 +1,6 @@
+---
+category: Enhancements
+authors: [krzysztofwojt]
+---
+
+Allow split rule formulas to read the parent transaction's notes, imported payee, payee, and account.