@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/tools/compareTransactions/matcher.ts

@@ -1,240 +1,290 @@
-import { BankTransaction, YNABTransaction, TransactionMatch } from './types.js';
+import type {
+	BankTransaction,
+	TransactionMatch,
+	YNABTransaction,
+} from "./types.js";
 
 /**
  * Calculate match score between bank and YNAB transactions
  */
 export function calculateMatchScore(
-  bankTxn: BankTransaction,
-  ynabTxn: YNABTransaction,
-  amountTolerance: number,
-  dateTolerance: number,
+	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 };
+	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)[],
+	transactions: (BankTransaction | YNABTransaction)[],
 ): Map<number, (BankTransaction | YNABTransaction)[]> {
-  const groups = new 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);
-  }
+	for (const txn of transactions) {
+		const amount = txn.amount;
+		if (!groups.has(amount)) {
+			groups.set(amount, []);
+		}
+		groups.get(amount)?.push(txn);
+	}
 
-  return groups;
+	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,
+	bankTxns: BankTransaction[],
+	ynabTxns: YNABTransaction[],
+	_amount: number,
+	amountTolerance: number,
+	dateTolerance: number,
+	enableChronologyBonus = 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;
+	// 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,
+	bankTransactions: BankTransaction[],
+	ynabTransactions: YNABTransaction[],
+	amountTolerance: number,
+	dateTolerance: number,
+	enableChronologyBonus = false,
 ): {
-  matches: TransactionMatch[];
-  unmatched_bank: BankTransaction[];
-  unmatched_ynab: YNABTransaction[];
+	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 };
+	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 };
 }