@dizzlkheinz/ynab-mcpb 0.17.1 → 0.18.1

package/src/tools/reconciliation/__tests__/executor.progress.test.ts

@@ -0,0 +1,462 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type * as ynab from 'ynab';
+import type { ProgressCallback } from '../../../server/toolRegistry.js';
+import type { ReconciliationAnalysis, TransactionMatch, BankTransaction } from '../types.js';
+import type { ReconcileAccountRequest } from '../index.js';
+import { executeReconciliation, type ExecutionOptions } from '../executor.js';
+
+/**
+ * Unit tests for progress notification functionality in reconciliation executor
+ */
+describe('Reconciliation Progress Notifications', () => {
+  let mockYnabAPI: Partial<ynab.API>;
+  let mockProgressCallback: ProgressCallback;
+  let progressCalls: { progress: number; total?: number; message?: string }[];
+
+  const createMockTransaction = (
+    overrides: Partial<ynab.TransactionDetail> = {},
+  ): ynab.TransactionDetail => ({
+    id: 'txn-1',
+    date: '2024-01-15',
+    amount: -25000,
+    memo: 'Test transaction',
+    cleared: 'uncleared' as ynab.TransactionClearedStatus,
+    approved: true,
+    flag_color: null,
+    flag_name: null,
+    account_id: 'acc-1',
+    account_name: 'Test Account',
+    payee_id: 'payee-1',
+    payee_name: 'Test Payee',
+    category_id: 'cat-1',
+    category_name: 'Test Category',
+    transfer_account_id: null,
+    transfer_transaction_id: null,
+    matched_transaction_id: null,
+    import_id: null,
+    import_payee_name: null,
+    import_payee_name_original: null,
+    debt_transaction_type: null,
+    deleted: false,
+    subtransactions: [],
+    ...overrides,
+  });
+
+  const createBankTransaction = (overrides: Partial<BankTransaction> = {}): BankTransaction => ({
+    date: '2024-01-15',
+    amount: -25000,
+    payee: 'Test Payee',
+    memo: 'Bank memo',
+    ...overrides,
+  });
+
+  const createMatch = (
+    bankTxn: BankTransaction,
+    ynabTxn: ynab.TransactionDetail,
+    score = 0.95,
+  ): TransactionMatch => ({
+    bankTransaction: bankTxn,
+    ynabTransaction: ynabTxn,
+    score,
+    matchType: 'exact',
+    matchDetails: {
+      amount_match: true,
+      date_match: true,
+      payee_similarity: 1.0,
+    },
+  });
+
+  beforeEach(() => {
+    progressCalls = [];
+    mockProgressCallback = vi.fn().mockImplementation(async (params) => {
+      progressCalls.push(params);
+    });
+
+    mockYnabAPI = {
+      transactions: {
+        createTransaction: vi.fn().mockResolvedValue({
+          data: { transaction: createMockTransaction() },
+        }),
+        createTransactions: vi.fn().mockResolvedValue({
+          data: {
+            transactions: [createMockTransaction()],
+            duplicate_import_ids: [],
+          },
+        }),
+        updateTransactions: vi.fn().mockResolvedValue({
+          data: { transactions: [createMockTransaction({ cleared: 'cleared' })] },
+        }),
+      } as unknown as ynab.TransactionsApi,
+      accounts: {
+        getAccountById: vi.fn().mockResolvedValue({
+          data: {
+            account: {
+              balance: 100000,
+              cleared_balance: 100000,
+              uncleared_balance: 0,
+            },
+          },
+        }),
+      } as unknown as ynab.AccountsApi,
+    };
+  });
+
+  describe('progress callback invocation', () => {
+    it('should call progress callback during bulk transaction creation', async () => {
+      const unmatchedBank: BankTransaction[] = [
+        createBankTransaction({ payee: 'Payee 1', amount: -10000 }),
+        createBankTransaction({ payee: 'Payee 2', amount: -20000 }),
+        createBankTransaction({ payee: 'Payee 3', amount: -30000 }),
+      ];
+
+      const analysis: ReconciliationAnalysis = {
+        summary: {
+          bank_transactions_count: 3,
+          ynab_transactions_count: 0,
+          matches: 0,
+          unmatched_bank: 3,
+          unmatched_ynab: 0,
+          match_rate: 0,
+          statement_date_range: '2024-01-01 to 2024-01-31',
+        },
+        auto_matches: [],
+        unmatched_bank: unmatchedBank,
+        unmatched_ynab: [],
+        balance_info: {
+          current_cleared: 100000,
+          target_statement: 40000,
+        },
+      };
+
+      const params: ReconcileAccountRequest = {
+        account_id: 'acc-1',
+        csv_data: 'date,amount,payee\n2024-01-15,-10,Payee 1',
+        dry_run: false,
+        auto_create_transactions: true,
+      };
+
+      const options: ExecutionOptions = {
+        ynabAPI: mockYnabAPI as ynab.API,
+        analysis,
+        params,
+        budgetId: 'budget-1',
+        accountId: 'acc-1',
+        initialAccount: { balance: 100000, cleared_balance: 100000, uncleared_balance: 0 },
+        currencyCode: 'USD',
+        sendProgress: mockProgressCallback,
+      };
+
+      await executeReconciliation(options);
+
+      expect(mockProgressCallback).toHaveBeenCalled();
+      expect(progressCalls.length).toBeGreaterThan(0);
+
+      // Verify progress structure
+      for (const call of progressCalls) {
+        expect(call).toHaveProperty('progress');
+        expect(call).toHaveProperty('total');
+        expect(call).toHaveProperty('message');
+        expect(typeof call.progress).toBe('number');
+        expect(typeof call.total).toBe('number');
+      }
+    });
+
+    it('should report progress during sequential fallback', async () => {
+      const unmatchedBank: BankTransaction[] = [
+        createBankTransaction({ payee: 'Single Payee', amount: -10000 }),
+      ];
+
+      const analysis: ReconciliationAnalysis = {
+        summary: {
+          bank_transactions_count: 1,
+          ynab_transactions_count: 0,
+          matches: 0,
+          unmatched_bank: 1,
+          unmatched_ynab: 0,
+          match_rate: 0,
+          statement_date_range: '2024-01-01 to 2024-01-31',
+        },
+        auto_matches: [],
+        unmatched_bank: unmatchedBank,
+        unmatched_ynab: [],
+        balance_info: {
+          current_cleared: 100000,
+          target_statement: 90000,
+        },
+      };
+
+      const params: ReconcileAccountRequest = {
+        account_id: 'acc-1',
+        csv_data: 'date,amount,payee\n2024-01-15,-10,Single Payee',
+        dry_run: false,
+        auto_create_transactions: true,
+      };
+
+      const options: ExecutionOptions = {
+        ynabAPI: mockYnabAPI as ynab.API,
+        analysis,
+        params,
+        budgetId: 'budget-1',
+        accountId: 'acc-1',
+        initialAccount: { balance: 100000, cleared_balance: 100000, uncleared_balance: 0 },
+        currencyCode: 'USD',
+        sendProgress: mockProgressCallback,
+      };
+
+      await executeReconciliation(options);
+
+      // With only 1 transaction, it goes through sequential path
+      expect(mockProgressCallback).toHaveBeenCalled();
+    });
+
+    it('should not call progress callback when not provided', async () => {
+      const analysis: ReconciliationAnalysis = {
+        summary: {
+          bank_transactions_count: 1,
+          ynab_transactions_count: 0,
+          matches: 0,
+          unmatched_bank: 1,
+          unmatched_ynab: 0,
+          match_rate: 0,
+          statement_date_range: '2024-01-01 to 2024-01-31',
+        },
+        auto_matches: [],
+        unmatched_bank: [createBankTransaction()],
+        unmatched_ynab: [],
+        balance_info: {
+          current_cleared: 100000,
+          target_statement: 75000,
+        },
+      };
+
+      const params: ReconcileAccountRequest = {
+        account_id: 'acc-1',
+        csv_data: 'date,amount,payee\n2024-01-15,-25,Test',
+        dry_run: false,
+        auto_create_transactions: true,
+      };
+
+      const options: ExecutionOptions = {
+        ynabAPI: mockYnabAPI as ynab.API,
+        analysis,
+        params,
+        budgetId: 'budget-1',
+        accountId: 'acc-1',
+        initialAccount: { balance: 100000, cleared_balance: 100000, uncleared_balance: 0 },
+        currencyCode: 'USD',
+        // No sendProgress callback
+      };
+
+      // Should not throw when no callback provided
+      await expect(executeReconciliation(options)).resolves.toBeDefined();
+    });
+
+    it('should report progress during transaction updates', async () => {
+      const ynabTxn = createMockTransaction({ cleared: 'uncleared' });
+      const bankTxn = createBankTransaction();
+      const match = createMatch(bankTxn, ynabTxn);
+
+      const analysis: ReconciliationAnalysis = {
+        summary: {
+          bank_transactions_count: 1,
+          ynab_transactions_count: 1,
+          matches: 1,
+          unmatched_bank: 0,
+          unmatched_ynab: 0,
+          match_rate: 1,
+          statement_date_range: '2024-01-01 to 2024-01-31',
+        },
+        auto_matches: [match],
+        unmatched_bank: [],
+        unmatched_ynab: [],
+        balance_info: {
+          current_cleared: 75000,
+          target_statement: 100000,
+        },
+      };
+
+      const params: ReconcileAccountRequest = {
+        account_id: 'acc-1',
+        csv_data: 'date,amount,payee\n2024-01-15,-25,Test',
+        dry_run: false,
+        auto_update_cleared_status: true,
+      };
+
+      const options: ExecutionOptions = {
+        ynabAPI: mockYnabAPI as ynab.API,
+        analysis,
+        params,
+        budgetId: 'budget-1',
+        accountId: 'acc-1',
+        initialAccount: { balance: 100000, cleared_balance: 75000, uncleared_balance: 25000 },
+        currencyCode: 'USD',
+        sendProgress: mockProgressCallback,
+      };
+
+      await executeReconciliation(options);
+
+      expect(mockProgressCallback).toHaveBeenCalled();
+    });
+  });
+
+  describe('progress calculation accuracy', () => {
+    it('should exclude skipped matches from total count', async () => {
+      // Create a match that won't need updating (already cleared, same date)
+      const clearedTxn = createMockTransaction({ cleared: 'cleared' });
+      const bankTxn = createBankTransaction();
+      const matchNoUpdate = createMatch(bankTxn, clearedTxn);
+
+      // Create a match that will need updating
+      const unclearedTxn = createMockTransaction({ cleared: 'uncleared', id: 'txn-2' });
+      const bankTxn2 = createBankTransaction({ payee: 'Payee 2' });
+      const matchNeedsUpdate = createMatch(bankTxn2, unclearedTxn);
+
+      const analysis: ReconciliationAnalysis = {
+        summary: {
+          bank_transactions_count: 2,
+          ynab_transactions_count: 2,
+          matches: 2,
+          unmatched_bank: 0,
+          unmatched_ynab: 0,
+          match_rate: 1,
+          statement_date_range: '2024-01-01 to 2024-01-31',
+        },
+        auto_matches: [matchNoUpdate, matchNeedsUpdate],
+        unmatched_bank: [],
+        unmatched_ynab: [],
+        balance_info: {
+          current_cleared: 75000,
+          target_statement: 100000,
+        },
+      };
+
+      const params: ReconcileAccountRequest = {
+        account_id: 'acc-1',
+        csv_data: 'date,amount,payee\n2024-01-15,-25,Test',
+        dry_run: false,
+        auto_update_cleared_status: true,
+      };
+
+      const options: ExecutionOptions = {
+        ynabAPI: mockYnabAPI as ynab.API,
+        analysis,
+        params,
+        budgetId: 'budget-1',
+        accountId: 'acc-1',
+        initialAccount: { balance: 100000, cleared_balance: 75000, uncleared_balance: 25000 },
+        currencyCode: 'USD',
+        sendProgress: mockProgressCallback,
+      };
+
+      await executeReconciliation(options);
+
+      // The total should only count the match that needs updating (1), not both (2)
+      if (progressCalls.length > 0) {
+        const lastCall = progressCalls[progressCalls.length - 1]!;
+        // Total should be 1 (only the uncleared transaction needs updating)
+        expect(lastCall.total).toBe(1);
+      }
+    });
+
+    it('should include all operation types in total count', async () => {
+      const unmatchedBank = [createBankTransaction({ payee: 'New Payee' })];
+      const unclearedTxn = createMockTransaction({ cleared: 'uncleared' });
+      const matchNeedsUpdate = createMatch(createBankTransaction(), unclearedTxn);
+      const unmatchedYnab = [createMockTransaction({ id: 'unmatched-ynab', cleared: 'cleared' })];
+
+      const analysis: ReconciliationAnalysis = {
+        summary: {
+          bank_transactions_count: 2,
+          ynab_transactions_count: 2,
+          matches: 1,
+          unmatched_bank: 1,
+          unmatched_ynab: 1,
+          match_rate: 0.5,
+          statement_date_range: '2024-01-01 to 2024-01-31',
+        },
+        auto_matches: [matchNeedsUpdate],
+        unmatched_bank: unmatchedBank,
+        unmatched_ynab: unmatchedYnab,
+        balance_info: {
+          current_cleared: 75000,
+          target_statement: 50000,
+        },
+      };
+
+      const params: ReconcileAccountRequest = {
+        account_id: 'acc-1',
+        csv_data: 'date,amount,payee\n2024-01-15,-25,Test',
+        dry_run: false,
+        auto_create_transactions: true,
+        auto_update_cleared_status: true,
+        auto_unclear_missing: true,
+      };
+
+      const options: ExecutionOptions = {
+        ynabAPI: mockYnabAPI as ynab.API,
+        analysis,
+        params,
+        budgetId: 'budget-1',
+        accountId: 'acc-1',
+        initialAccount: { balance: 100000, cleared_balance: 75000, uncleared_balance: 25000 },
+        currencyCode: 'USD',
+        sendProgress: mockProgressCallback,
+      };
+
+      await executeReconciliation(options);
+
+      // Total should be: 1 (create) + 1 (update match) + 1 (unclear) = 3
+      if (progressCalls.length > 0) {
+        const anyCall = progressCalls.find((c) => c.total !== undefined);
+        expect(anyCall?.total).toBe(3);
+      }
+    });
+  });
+
+  describe('dry run behavior', () => {
+    it('should not call progress callback during dry run', async () => {
+      const analysis: ReconciliationAnalysis = {
+        summary: {
+          bank_transactions_count: 1,
+          ynab_transactions_count: 0,
+          matches: 0,
+          unmatched_bank: 1,
+          unmatched_ynab: 0,
+          match_rate: 0,
+          statement_date_range: '2024-01-01 to 2024-01-31',
+        },
+        auto_matches: [],
+        unmatched_bank: [createBankTransaction()],
+        unmatched_ynab: [],
+        balance_info: {
+          current_cleared: 100000,
+          target_statement: 75000,
+        },
+      };
+
+      const params: ReconcileAccountRequest = {
+        account_id: 'acc-1',
+        csv_data: 'date,amount,payee\n2024-01-15,-25,Test',
+        dry_run: true, // Dry run mode
+        auto_create_transactions: true,
+      };
+
+      const options: ExecutionOptions = {
+        ynabAPI: mockYnabAPI as ynab.API,
+        analysis,
+        params,
+        budgetId: 'budget-1',
+        accountId: 'acc-1',
+        initialAccount: { balance: 100000, cleared_balance: 100000, uncleared_balance: 0 },
+        currencyCode: 'USD',
+        sendProgress: mockProgressCallback,
+      };
+
+      await executeReconciliation(options);
+
+      // In dry run, no actual operations happen, so no progress should be reported
+      // (Progress is only reported after successful API calls)
+      expect(mockYnabAPI.transactions?.createTransaction).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/tools/reconciliation/__tests__/executor.test.ts

@@ -484,9 +484,10 @@ describe('executeReconciliation - bulk create mode', () => {
         account_id: txn.account_id,
         amount: txn.amount,
         date: txn.date,
+        payee_name: txn.payee_name,
+        memo: txn.memo,
         cleared: 'cleared',
         approved: true,
-        import_id: txn.import_id, // Include import_id for correlation
       }));
       return { data: { transactions, duplicate_import_ids: [] } };
     });
@@ -638,11 +639,12 @@ describe('executeReconciliation - bulk create mode', () => {
         account_id: txn.account_id,
         amount: txn.amount,
         date: txn.date,
+        payee_name: txn.payee_name,
+        memo: txn.memo,
         cleared: 'cleared',
         approved: true,
-        import_id: txn.import_id, // Include import_id for correlation
       }));
-      return { data: { transactions } };
+      return { data: { transactions, duplicate_import_ids: [] } };
     });
 
     const result = await executeReconciliation({
@@ -690,33 +692,35 @@ describe('executeReconciliation - bulk create mode', () => {
     ).rejects.toMatchObject({ status: 404 });
   });
 
-  it('flags duplicate transactions returned by YNAB API', async () => {
-    const analysis = buildBulkAnalysis(3, 7);
+  it('creates all transactions without import_id (no YNAB-side duplicate detection)', async () => {
+    // Note: import_id is intentionally omitted from reconciliation-created transactions
+    // so they can match with bank-imported transactions. This means YNAB won't detect
+    // duplicates via import_id - the reconciliation matcher is responsible for that.
+    // Use amount of 100 to avoid early balance halting (tolerance is 10 milliunits)
+    const analysis = buildBulkAnalysis(3, 100);
     const params = buildBulkParams(analysis.summary.target_statement_balance);
     const initialAccount = { ...defaultAccountSnapshot };
     const { api, mocks } = createMockYnabAPI(initialAccount);
 
     mocks.createTransactions.mockImplementation(async (_budgetId, body: any) => {
-      const transactions = (body.transactions ?? []).map((txn: any, index: number) => {
-        if (index === 1) {
-          return undefined;
-        }
-        return {
-          id: `created-${index}`,
-          account_id: txn.account_id,
-          amount: txn.amount,
-          date: txn.date,
-          cleared: 'cleared',
-          approved: true,
-          import_id: txn.import_id, // Include import_id for correlation
-        };
-      });
-      const filtered = transactions.filter(Boolean);
-      const duplicateImportId = body.transactions?.[1]?.import_id;
+      const transactions = (body.transactions ?? []).map((txn: any, index: number) => ({
+        id: `created-${index}`,
+        account_id: txn.account_id,
+        amount: txn.amount,
+        date: txn.date,
+        payee_name: txn.payee_name,
+        memo: txn.memo,
+        cleared: 'cleared',
+        approved: true,
+      }));
+      // Verify no import_id is being sent
+      for (const txn of body.transactions ?? []) {
+        expect(txn.import_id).toBeUndefined();
+      }
       return {
         data: {
-          transactions: filtered,
-          duplicate_import_ids: duplicateImportId ? [duplicateImportId] : [],
+          transactions,
+          duplicate_import_ids: [],
         },
       };
     });
@@ -731,10 +735,9 @@ describe('executeReconciliation - bulk create mode', () => {
       currencyCode: 'USD',
     });
 
-    const duplicateActions = result.actions_taken.filter((action) => action.duplicate === true);
-    expect(duplicateActions).toHaveLength(1);
-    expect(result.bulk_operation_details?.duplicates_detected).toBe(1);
-    expect(result.summary.transactions_created).toBe(2);
+    // Without import_id, YNAB creates all transactions (no duplicate detection)
+    expect(result.bulk_operation_details?.duplicates_detected).toBe(0);
+    expect(result.summary.transactions_created).toBe(3);
   });
 
   it('honors halting logic when balance aligns mid-batch', async () => {
@@ -749,11 +752,12 @@ describe('executeReconciliation - bulk create mode', () => {
         account_id: txn.account_id,
         amount: txn.amount,
         date: txn.date,
+        payee_name: txn.payee_name,
+        memo: txn.memo,
         cleared: 'cleared',
         approved: true,
-        import_id: txn.import_id, // Include import_id for correlation
       }));
-      return { data: { transactions } };
+      return { data: { transactions, duplicate_import_ids: [] } };
     });
 
     const result = await executeReconciliation({
@@ -794,11 +798,12 @@ describe('executeReconciliation - bulk create mode', () => {
         account_id: txn.account_id,
         amount: txn.amount,
         date: txn.date,
+        payee_name: txn.payee_name,
+        memo: txn.memo,
         cleared: 'cleared',
         approved: true,
-        import_id: txn.import_id,
       }));
-      return { data: { transactions } };
+      return { data: { transactions, duplicate_import_ids: [] } };
     });
 
     const result = await executeReconciliation({