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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.mdnew file mode 100644index 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.