@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/compareTransactions/index.ts

@@ -0,0 +1,228 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../../types/index.js';
+import { parseBankCSV, readCSVFile, autoDetectCSVFormat } from './parser.js';
+import { findMatches } from './matcher.js';
+import { buildComparisonResult } from './formatter.js';
+import type { YNABTransaction } from './types.js';
+
+// Re-export core types for consumers
+export type { BankTransaction, YNABTransaction, TransactionMatch } from './types.js';
+
+/**
+ * Schema for ynab:compare_transactions tool parameters
+ */
+export const CompareTransactionsSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+    csv_file_path: z.string().optional(),
+    csv_data: z.string().optional(),
+    /** @deprecated Currently unused. Originally intended to limit the date range when CSV dates span a very long period. */
+    date_range_days: z.number().min(1).max(365).optional().default(30),
+    amount_tolerance: z.number().min(0).max(1).optional().default(0.01),
+    date_tolerance_days: z.number().min(0).max(7).optional().default(5),
+    enable_chronology_bonus: z.boolean().optional().default(false),
+    statement_start_date: z.string().optional(),
+    statement_date: z.string().optional(),
+    auto_detect_format: z.boolean().optional().default(false),
+    debug: z.boolean().optional().default(false),
+    csv_format: z
+      .object({
+        date_column: z.union([z.string(), z.number()]).optional().default('Date'),
+        amount_column: z.union([z.string(), z.number()]).optional(),
+        debit_column: z.union([z.string(), z.number()]).optional(),
+        credit_column: z.union([z.string(), z.number()]).optional(),
+        description_column: z.union([z.string(), z.number()]).optional().default('Description'),
+        date_format: z.string().optional().default('MM/DD/YYYY'),
+        has_header: z.boolean().optional().default(true),
+        delimiter: z.string().optional().default(','),
+      })
+      .strict()
+      .optional()
+      .default(() => ({
+        date_column: 'Date',
+        amount_column: 'Amount',
+        description_column: 'Description',
+        date_format: 'MM/DD/YYYY',
+        has_header: true,
+        delimiter: ',',
+      })),
+  })
+  .strict()
+  .refine((data) => data.csv_file_path || data.csv_data, {
+    message: 'Either csv_file_path or csv_data must be provided',
+  });
+
+export type CompareTransactionsParams = z.infer<typeof CompareTransactionsSchema>;
+
+/**
+ * Handles the ynab:compare_transactions tool call
+ */
+export async function handleCompareTransactions(
+  ynabAPI: ynab.API,
+  params: CompareTransactionsParams,
+): Promise<CallToolResult> {
+  return await withToolErrorHandling(
+    async () => {
+      // Parse and apply defaults/validation
+      const parsed = CompareTransactionsSchema.parse(params);
+
+      const payeesResponse = await ynabAPI.payees.getPayees(parsed.budget_id);
+      const payees = payeesResponse.data.payees;
+
+      // Get CSV data
+      let csvContent: string;
+      if (parsed.csv_file_path) {
+        csvContent = readCSVFile(parsed.csv_file_path);
+      } else {
+        csvContent = parsed.csv_data!;
+      }
+
+      // Auto-detect format if requested
+      let csvFormat = parsed.csv_format;
+      if (parsed.auto_detect_format) {
+        try {
+          csvFormat = autoDetectCSVFormat(csvContent);
+          if (parsed.debug) {
+            console.warn('Auto-detected CSV format:', csvFormat);
+          }
+        } catch (error) {
+          if (parsed.debug) {
+            console.warn('Auto-detection failed, using provided format:', error);
+          }
+        }
+      }
+
+      // Parse bank transactions from CSV
+      const bankTransactions = parseBankCSV(csvContent, csvFormat, { debug: parsed.debug });
+
+      if (bankTransactions.length === 0) {
+        throw new Error(
+          'No valid transactions found in CSV data. ' +
+            'Check your csv_format parameters or try auto_detect_format: true. ' +
+            `CSV has ${csvContent.split('\n').length} lines.`,
+        );
+      }
+
+      // Calculate date range for YNAB query
+      const bankDates = bankTransactions.map((t) => t.date);
+      const minDate = new Date(Math.min(...bankDates.map((d) => d.getTime())));
+      const maxDate = new Date(Math.max(...bankDates.map((d) => d.getTime())));
+
+      // Add tolerance to date range
+      const startDate = new Date(minDate);
+      startDate.setDate(startDate.getDate() - parsed.date_tolerance_days!);
+      const endDate = new Date(maxDate);
+      endDate.setDate(endDate.getDate() + parsed.date_tolerance_days!);
+
+      // Get YNAB transactions for the account in the date range
+      const sinceDate = startDate.toISOString().split('T')[0];
+      const response = await ynabAPI.transactions.getTransactionsByAccount(
+        parsed.budget_id,
+        parsed.account_id,
+        sinceDate,
+      );
+
+      // Filter YNAB transactions to the extended date range and convert for comparison
+      const ynabTransactions: YNABTransaction[] = response.data.transactions
+        .filter((txn) => {
+          const txnDate = new Date(txn.date);
+          return txnDate >= startDate && txnDate <= endDate && !txn.deleted;
+        })
+        .map((txn) => ({
+          id: txn.id,
+          date: new Date(txn.date),
+          amount: txn.amount,
+          payee_name: txn.payee_name,
+          memo: txn.memo,
+          cleared: txn.cleared,
+          original: txn,
+        }));
+
+      // Filter candidates to statement window if provided
+      let filteredBankTransactions = bankTransactions;
+      let filteredYnabTransactions = ynabTransactions;
+
+      if (parsed.statement_start_date || parsed.statement_date) {
+        filteredBankTransactions = bankTransactions.filter((t) => {
+          const dateStr = t.date.toISOString().split('T')[0]!;
+          if (parsed.statement_start_date && dateStr < parsed.statement_start_date) {
+            return false;
+          }
+          if (parsed.statement_date && dateStr > parsed.statement_date) {
+            return false;
+          }
+          return true;
+        });
+        filteredYnabTransactions = ynabTransactions.filter((t) => {
+          const dateStr = t.date.toISOString().split('T')[0]!;
+          if (parsed.statement_start_date && dateStr < parsed.statement_start_date) {
+            return false;
+          }
+          if (parsed.statement_date && dateStr > parsed.statement_date) {
+            return false;
+          }
+          return true;
+        });
+      }
+
+      // Find matches
+      const matchResults = findMatches(
+        filteredBankTransactions,
+        filteredYnabTransactions,
+        parsed.amount_tolerance!,
+        parsed.date_tolerance_days!,
+        parsed.enable_chronology_bonus!,
+      );
+
+      // Build comparison result - compute date range from filtered transactions when statement window is applied
+      let dateRange: { start: string; end: string };
+      if (parsed.statement_start_date || parsed.statement_date) {
+        // Use filtered bank transactions for date range when statement window filtering is applied
+        const filteredBankDates = filteredBankTransactions.map((t) => t.date);
+        if (filteredBankDates.length > 0) {
+          const filteredMinDate = new Date(Math.min(...filteredBankDates.map((d) => d.getTime())));
+          const filteredMaxDate = new Date(Math.max(...filteredBankDates.map((d) => d.getTime())));
+          dateRange = {
+            start: filteredMinDate.toISOString().split('T')[0] as string,
+            end: filteredMaxDate.toISOString().split('T')[0] as string,
+          };
+        } else {
+          // Fallback to statement window if no filtered transactions
+          dateRange = {
+            start: (parsed.statement_start_date ||
+              parsed.statement_date ||
+              minDate.toISOString().split('T')[0]) as string,
+            end: (parsed.statement_date ||
+              parsed.statement_start_date ||
+              maxDate.toISOString().split('T')[0]) as string,
+          };
+        }
+      } else {
+        // Use original unfiltered date range when no statement window filtering
+        dateRange = {
+          start: minDate.toISOString().split('T')[0] as string,
+          end: maxDate.toISOString().split('T')[0] as string,
+        };
+      }
+
+      const parameters = {
+        amount_tolerance: parsed.amount_tolerance,
+        date_tolerance_days: parsed.date_tolerance_days,
+      };
+
+      return buildComparisonResult(
+        matchResults,
+        filteredBankTransactions,
+        filteredYnabTransactions,
+        payees,
+        parameters,
+        dateRange,
+      );
+    },
+    'ynab:compare_transactions',
+    'comparing bank and YNAB transactions',
+  );
+}

package/src/tools/compareTransactions/matcher.ts

@@ -0,0 +1,240 @@
+import { BankTransaction, YNABTransaction, TransactionMatch } from './types.js';
+
+/**
+ * Calculate match score between bank and YNAB transactions
+ */
+export function calculateMatchScore(
+  bankTxn: BankTransaction,
+  ynabTxn: YNABTransaction,
+  amountTolerance: number,
+  dateTolerance: number,
+): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  let score = 0;
+
+  // Date matching (40 points max)
+  const dateDiff = Math.abs(bankTxn.date.getTime() - ynabTxn.date.getTime());
+  const daysDiff = dateDiff / (1000 * 60 * 60 * 24);
+
+  if (daysDiff === 0) {
+    score += 40;
+    reasons.push('Exact date match');
+  } else if (daysDiff <= dateTolerance) {
+    score += Math.max(20, 40 - daysDiff * 10);
+    reasons.push(`Date within ${daysDiff.toFixed(1)} days`);
+  }
+
+  // Amount matching (50 points max)
+  const amountDiff = Math.abs(bankTxn.amount - ynabTxn.amount);
+  const amountDiffPercent = amountDiff / Math.abs(bankTxn.amount);
+
+  if (amountDiff === 0) {
+    score += 50;
+    reasons.push('Exact amount match');
+  } else if (amountDiffPercent <= amountTolerance) {
+    score += Math.max(25, 50 - amountDiffPercent * 1000);
+    reasons.push(`Amount within ${(amountDiffPercent * 100).toFixed(2)}% tolerance`);
+  }
+
+  // Description/payee matching (10 points max)
+  const bankDesc = bankTxn.description.toLowerCase();
+  const ynabPayee = (ynabTxn.payee_name || '').toLowerCase();
+  const ynabMemo = (ynabTxn.memo || '').toLowerCase();
+
+  if (bankDesc && ynabPayee && (ynabPayee.includes(bankDesc) || bankDesc.includes(ynabPayee))) {
+    score += 10;
+    reasons.push('Payee name similarity');
+  } else if (bankDesc && ynabMemo && (ynabMemo.includes(bankDesc) || bankDesc.includes(ynabMemo))) {
+    score += 5;
+    reasons.push('Memo similarity');
+  }
+
+  return { score, reasons };
+}
+
+/**
+ * Group transactions by amount to detect duplicates
+ */
+export function groupTransactionsByAmount(
+  transactions: (BankTransaction | YNABTransaction)[],
+): Map<number, (BankTransaction | YNABTransaction)[]> {
+  const groups = new Map<number, (BankTransaction | YNABTransaction)[]>();
+
+  for (const txn of transactions) {
+    const amount = txn.amount;
+    if (!groups.has(amount)) {
+      groups.set(amount, []);
+    }
+    groups.get(amount)!.push(txn);
+  }
+
+  return groups;
+}
+
+/**
+ * Match duplicate amounts using sequential date-based approach
+ */
+export function matchDuplicateAmounts(
+  bankTxns: BankTransaction[],
+  ynabTxns: YNABTransaction[],
+  _amount: number,
+  amountTolerance: number,
+  dateTolerance: number,
+  enableChronologyBonus: boolean = false,
+): TransactionMatch[] {
+  // Sort both arrays by date for sequential matching
+  const sortedBank = [...bankTxns].sort((a, b) => a.date.getTime() - b.date.getTime());
+  const sortedYnab = [...ynabTxns].sort((a, b) => a.date.getTime() - b.date.getTime());
+
+  const matches: TransactionMatch[] = [];
+  const usedYnabIds = new Set<string>();
+
+  // For each bank transaction, find the best available YNAB transaction
+  // considering both score and chronological order
+  for (const bankTxn of sortedBank) {
+    let bestMatch: { ynab: YNABTransaction; score: number; reasons: string[] } | null = null;
+
+    for (const ynabTxn of sortedYnab) {
+      if (usedYnabIds.has(ynabTxn.id)) continue;
+
+      const { score, reasons } = calculateMatchScore(
+        bankTxn,
+        ynabTxn,
+        amountTolerance,
+        dateTolerance,
+      );
+
+      // Apply chronology bonus if enabled (for duplicates, heavily prefer chronological order)
+      let chronologyBonus = 0;
+      if (enableChronologyBonus) {
+        const daysDiff =
+          Math.abs(bankTxn.date.getTime() - ynabTxn.date.getTime()) / (1000 * 60 * 60 * 24);
+        chronologyBonus = daysDiff <= 1 ? 15 : daysDiff <= 3 ? 10 : 0;
+      }
+      const adjustedScore = score + chronologyBonus;
+
+      if (adjustedScore >= 30 && (!bestMatch || adjustedScore > bestMatch.score)) {
+        const enhancedReasons = [...reasons];
+        if (chronologyBonus > 0) {
+          enhancedReasons.push(`Chronological order bonus (+${chronologyBonus})`);
+        }
+        bestMatch = { ynab: ynabTxn, score: adjustedScore, reasons: enhancedReasons };
+      }
+    }
+
+    if (bestMatch) {
+      matches.push({
+        bank_transaction: bankTxn,
+        ynab_transaction: bestMatch.ynab,
+        match_score: bestMatch.score,
+        match_reasons: bestMatch.reasons,
+      });
+      usedYnabIds.add(bestMatch.ynab.id);
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Find the best matches between bank and YNAB transactions
+ */
+export function findMatches(
+  bankTransactions: BankTransaction[],
+  ynabTransactions: YNABTransaction[],
+  amountTolerance: number,
+  dateTolerance: number,
+  enableChronologyBonus: boolean = false,
+): {
+  matches: TransactionMatch[];
+  unmatched_bank: BankTransaction[];
+  unmatched_ynab: YNABTransaction[];
+} {
+  const matches: TransactionMatch[] = [];
+  const usedYnabIds = new Set<string>();
+  const usedBankIndices = new Set<number>();
+
+  // Group transactions by amount to detect duplicates
+  const bankByAmount = groupTransactionsByAmount(bankTransactions);
+  const ynabByAmount = groupTransactionsByAmount(ynabTransactions);
+
+  // Find amounts that appear multiple times (duplicates)
+  const duplicateAmounts = new Set<number>();
+  for (const [amount, txns] of bankByAmount) {
+    if (txns.length > 1 || (ynabByAmount.get(amount)?.length || 0) > 1) {
+      duplicateAmounts.add(amount);
+    }
+  }
+
+  // Handle duplicate amounts with special sequential matching
+  for (const amount of duplicateAmounts) {
+    const bankDuplicates =
+      bankByAmount
+        .get(amount)
+        ?.filter(
+          (txn): txn is BankTransaction =>
+            'raw_amount' in txn && !usedBankIndices.has(bankTransactions.indexOf(txn)),
+        ) || [];
+    const ynabDuplicates =
+      ynabByAmount
+        .get(amount)
+        ?.filter((txn): txn is YNABTransaction => 'id' in txn && !usedYnabIds.has(txn.id)) || [];
+
+    if (bankDuplicates.length > 0 && ynabDuplicates.length > 0) {
+      const duplicateMatches = matchDuplicateAmounts(
+        bankDuplicates,
+        ynabDuplicates,
+        amount,
+        amountTolerance,
+        dateTolerance,
+        enableChronologyBonus,
+      );
+
+      for (const match of duplicateMatches) {
+        matches.push(match);
+        usedYnabIds.add(match.ynab_transaction.id);
+        usedBankIndices.add(bankTransactions.indexOf(match.bank_transaction));
+      }
+    }
+  }
+
+  // Handle non-duplicate amounts with original algorithm
+  for (let i = 0; i < bankTransactions.length; i++) {
+    const bankTxn = bankTransactions[i];
+    if (!bankTxn || usedBankIndices.has(i) || duplicateAmounts.has(bankTxn.amount)) continue;
+
+    let bestMatch: { ynab: YNABTransaction; score: number; reasons: string[] } | null = null;
+
+    for (const ynabTxn of ynabTransactions) {
+      if (usedYnabIds.has(ynabTxn.id) || duplicateAmounts.has(ynabTxn.amount)) continue;
+
+      const { score, reasons } = calculateMatchScore(
+        bankTxn,
+        ynabTxn,
+        amountTolerance,
+        dateTolerance,
+      );
+
+      if (score >= 30 && (!bestMatch || score > bestMatch.score)) {
+        bestMatch = { ynab: ynabTxn, score, reasons };
+      }
+    }
+
+    if (bestMatch) {
+      matches.push({
+        bank_transaction: bankTxn,
+        ynab_transaction: bestMatch.ynab,
+        match_score: bestMatch.score,
+        match_reasons: bestMatch.reasons,
+      });
+      usedYnabIds.add(bestMatch.ynab.id);
+      usedBankIndices.add(i);
+    }
+  }
+
+  // Collect unmatched transactions
+  const unmatched_bank = bankTransactions.filter((_, i) => !usedBankIndices.has(i));
+  const unmatched_ynab = ynabTransactions.filter((txn) => !usedYnabIds.has(txn.id));
+
+  return { matches, unmatched_bank, unmatched_ynab };
+}