@dizzlkheinz/ynab-mcpb 0.13.1 → 0.15.0

package/src/tools/reconciliation/reportFormatter.ts

@@ -173,16 +173,17 @@ function formatBankTransactionLine(txn: BankTransaction): string {
  * Format a suggested match line
  */
 function formatSuggestedMatchLine(match: TransactionMatch): string {
-  const bankTxn = match.bank_transaction;
+  const bankTxn = match.bankTransaction;
   const amountStr = formatAmount(bankTxn.amount);
-  const confidenceStr = `${match.confidence_score}%`;
+  const confidenceStr = `${match.confidenceScore}%`;
   return `   ${bankTxn.date} - ${bankTxn.payee.substring(0, 35).padEnd(35)} ${amountStr} (${confidenceStr} confidence)`;
 }
 
 /**
- * Format an amount for display
+ * Format an amount for display (input in milliunits)
  */
-function formatAmount(amount: number): string {
+function formatAmount(amountMilli: number): string {
+  const amount = amountMilli / 1000;
   const sign = amount >= 0 ? '+' : '-';
   const absAmount = Math.abs(amount);
   return `${sign}$${absAmount.toFixed(2)}`.padStart(10);
@@ -336,6 +337,8 @@ export function formatBalanceInfo(balance: BalanceInfo): string {
 /**
  * Format transaction list (helper for detailed reports)
  */
+type FormattableYnabTransaction = YNABTransaction & { payee_name?: string | null };
+
 export function formatTransactionList(
   transactions: BankTransaction[] | YNABTransaction[],
   maxItems: number = 10,
@@ -344,14 +347,16 @@ export function formatTransactionList(
   const toShow = transactions.slice(0, maxItems);
 
   for (const txn of toShow) {
-    if ('payee' in txn) {
-      // Bank transaction
-      lines.push(formatBankTransactionLine(txn));
+    if ('cleared' in txn) {
+      // YNAB transaction (normalized)
+      const ynabTxn = txn as FormattableYnabTransaction;
+      const payee = ynabTxn.payee_name ?? ynabTxn.payee ?? 'Unknown';
+      lines.push(
+        `   ${ynabTxn.date} - ${payee.substring(0, 40).padEnd(40)} ${formatAmount(ynabTxn.amount)}`,
+      );
     } else {
-      // YNAB transaction
-      const amount = txn.amount / 1000; // Convert milliunits to dollars
-      const payee = txn.payee_name ?? 'Unknown';
-      lines.push(`   ${txn.date} - ${payee.substring(0, 40).padEnd(40)} ${formatAmount(amount)}`);
+      // Bank transaction
+      lines.push(formatBankTransactionLine(txn as BankTransaction));
     }
   }
 

package/src/tools/reconciliation/signDetector.ts

@@ -0,0 +1,117 @@
+/**
+ * Smart sign detection for bank transaction imports
+ *
+ * Analyzes a sample of bank and YNAB transactions to determine if
+ * bank amounts need to be inverted to match YNAB's sign convention.
+ */
+
+import type { BankTransaction, NormalizedYNABTransaction } from '../../types/reconciliation.js';
+
+interface SignMatch {
+  bankAmount: number;
+  ynabAmount: number;
+  oppositeSign: boolean;
+}
+
+/**
+ * Detects whether bank transaction amounts need to be inverted
+ * to match YNAB's sign convention.
+ *
+ * Algorithm:
+ * 1. Find matching transactions based on date/amount proximity
+ * 2. For each match, check if signs are opposite
+ * 3. If >50% of matches have opposite signs, return true (needs inversion)
+ *
+ * @param bankTransactions - Raw bank transactions from CSV
+ * @param ynabTransactions - Normalized YNAB transactions
+ * @returns true if bank amounts should be inverted, false otherwise
+ */
+export function detectSignInversion(
+  bankTransactions: BankTransaction[],
+  ynabTransactions: NormalizedYNABTransaction[],
+): boolean {
+  // Edge cases: empty lists
+  if (bankTransactions.length === 0 || ynabTransactions.length === 0) {
+    return false; // Conservative default: don't invert
+  }
+
+  // Sample up to 20 transactions for performance
+  const sampleSize = Math.min(20, bankTransactions.length);
+  const sample = bankTransactions.slice(0, sampleSize);
+
+  const matches: SignMatch[] = [];
+
+  // Try to find matches for each bank transaction
+  for (const bankTxn of sample) {
+    const match = findClosestMatch(bankTxn, ynabTransactions);
+    if (match) {
+      matches.push(match);
+    }
+  }
+
+  // Need at least 1 match to make a determination
+  if (matches.length === 0) {
+    return false; // Conservative default: don't invert
+  }
+
+  // Count how many matches have opposite signs
+  const oppositeSignCount = matches.filter((m) => m.oppositeSign).length;
+  const oppositeSignRatio = oppositeSignCount / matches.length;
+
+  // If more than 50% have opposite signs, inversion is needed
+  return oppositeSignRatio > 0.5;
+}
+
+/**
+ * Find the closest matching YNAB transaction for a bank transaction
+ */
+function findClosestMatch(
+  bankTxn: BankTransaction,
+  ynabTransactions: NormalizedYNABTransaction[],
+): SignMatch | null {
+  const bankDate = new Date(bankTxn.date);
+  const bankAbsAmount = Math.abs(bankTxn.amount);
+
+  let bestMatch: SignMatch | null = null;
+  let bestScore = 0;
+
+  for (const ynabTxn of ynabTransactions) {
+    const ynabDate = new Date(ynabTxn.date);
+    const ynabAbsAmount = Math.abs(ynabTxn.amount);
+
+    // Check if amounts match (within tolerance)
+    const amountDiff = Math.abs(bankAbsAmount - ynabAbsAmount);
+    const amountTolerance = 100; // 10 cents in milliunits
+    if (amountDiff > amountTolerance) {
+      continue; // Amounts too different
+    }
+
+    // Check date proximity
+    const daysDiff = Math.abs(bankDate.getTime() - ynabDate.getTime()) / (1000 * 60 * 60 * 24);
+    if (daysDiff > 7) {
+      continue; // Dates too far apart
+    }
+
+    // Calculate match score (closer = higher score)
+    const amountScore = amountDiff === 0 ? 100 : Math.max(0, 100 - amountDiff / 10);
+    const dateScore = daysDiff === 0 ? 100 : Math.max(0, 100 - daysDiff * 10);
+    const score = amountScore * 0.7 + dateScore * 0.3;
+
+    if (score > bestScore) {
+      bestScore = score;
+
+      // Check if signs are opposite
+      const bankSign = Math.sign(bankTxn.amount);
+      const ynabSign = Math.sign(ynabTxn.amount);
+      const oppositeSign = bankSign !== 0 && ynabSign !== 0 && bankSign !== ynabSign;
+
+      bestMatch = {
+        bankAmount: bankTxn.amount,
+        ynabAmount: ynabTxn.amount,
+        oppositeSign,
+      };
+    }
+  }
+
+  return bestMatch;
+}

package/src/tools/reconciliation/types.ts

@@ -1,48 +1,28 @@
 /**
  * Type definitions for the reconciliation tool
  * Based on the 2025-10-31 reconciliation redesign specification
+ *
+ * IMPORTANT UNIT CONVENTION:
+ * BankTransaction.amount is in MILLIUNITS (integers) in V2 architecture (formerly dollars).
+ * YNABTransaction.amount is in MILLIUNITS (integers).
+ * All internal calculations use milliunits to avoid floating-point errors.
  */
 
 import type { MoneyValue } from '../../utils/money.js';
+import type {
+  BankTransaction as CanonicalBankTransaction,
+  NormalizedYNABTransaction as CanonicalYNABTransaction,
+} from '../../types/reconciliation.js';
+
+// Re-export canonical types as the standard types
+export type BankTransaction = CanonicalBankTransaction;
+export type YNABTransaction = CanonicalYNABTransaction;
 
 /**
  * Matching confidence levels
  */
 export type MatchConfidence = 'high' | 'medium' | 'low' | 'none';
 
-/**
- * Bank transaction parsed from CSV
- */
-export interface BankTransaction {
-  /** Generated UUID for tracking */
-  id: string;
-  /** Transaction date in YYYY-MM-DD format */
-  date: string;
-  /** Amount in dollars */
-  amount: number;
-  /** Payee/merchant name */
-  payee: string;
-  /** Optional memo/description */
-  memo?: string;
-  /** Original CSV row number for debugging */
-  original_csv_row: number;
-}
-
-/**
- * YNAB transaction (simplified from API)
- */
-export interface YNABTransaction {
-  id: string;
-  date: string;
-  /** Amount in milliunits */
-  amount: number;
-  payee_name: string | null;
-  category_name: string | null;
-  cleared: 'cleared' | 'uncleared' | 'reconciled';
-  approved: boolean;
-  memo?: string | null;
-}
-
 /**
  * Match candidate with confidence score
  */
@@ -57,21 +37,21 @@ export interface MatchCandidate {
  * Transaction match result
  */
 export interface TransactionMatch {
-  bank_transaction: BankTransaction;
+  bankTransaction: BankTransaction;
   /** Best matched YNAB transaction (if any) */
-  ynab_transaction?: YNABTransaction;
+  ynabTransaction?: YNABTransaction;
   /** Alternative candidates for suggested matches */
   candidates?: MatchCandidate[];
   /** Confidence level */
   confidence: MatchConfidence;
   /** Confidence score 0-100 */
-  confidence_score: number;
+  confidenceScore: number;
   /** Reason for the match */
-  match_reason: string;
+  matchReason: string;
   /** Top confidence from candidates */
-  top_confidence?: number;
+  topConfidence?: number;
   /** Action hint for user */
-  action_hint?: string;
+  actionHint?: string;
   /** Recommendation text */
   recommendation?: string;
 }
@@ -163,31 +143,29 @@ export interface ReconciliationAction {
 }
 
 /**
- * Matching algorithm configuration
+ * Matching algorithm configuration (V2)
  */
 export interface MatchingConfig {
-  /** Date tolerance in days */
-  dateToleranceDays: number;
-  /** Amount tolerance in cents */
-  amountToleranceCents: number;
-  /** Description similarity threshold (0-1) */
-  descriptionSimilarityThreshold: number;
-  /** Confidence threshold for auto-matching (0-100) */
-  autoMatchThreshold: number;
-  /** Confidence threshold for suggestions (0-100) */
-  suggestionThreshold: number;
-}
+  weights: {
+    amount: number; // Recommended: 0.50
+    date: number; // Recommended: 0.15
+    payee: number; // Recommended: 0.35
+  };
 
-/**
- * Default matching configuration (not type-only for use in code)
- */
-export const DEFAULT_MATCHING_CONFIG = {
-  dateToleranceDays: 2,
-  amountToleranceCents: 1,
-  descriptionSimilarityThreshold: 0.8,
-  autoMatchThreshold: 90,
-  suggestionThreshold: 60,
-};
+  // Tolerances (in MILLIUNITS for amount)
+  amountToleranceMilliunits: number; // Default: 10 (1 cent)
+  dateToleranceDays: number; // Default: 7
+
+  // Thresholds
+  autoMatchThreshold: number; // Default: 85
+  suggestedMatchThreshold: number; // Default: 60
+  minimumCandidateScore: number; // Default: 40
+
+  // Bonuses for perfect matches
+  exactAmountBonus: number; // Default: 10
+  exactDateBonus: number; // Default: 5
+  exactPayeeBonus: number; // Default: 10
+}
 
 /**
  * Parsed CSV data from compareTransactions

package/src/tools/reconciliation/ynabAdapter.ts

@@ -0,0 +1,33 @@
+import type * as ynab from 'ynab';
+import type { NormalizedYNABTransaction } from '../../types/reconciliation.js';
+
+/**
+ * Convert YNAB SDK transaction to normalized format for matching.
+ *
+ * This adapter keeps the YNAB SDK dependency isolated from the
+ * reconciliation core logic.
+ *
+ * NOTE: Amount stays in milliunits - no conversion needed since
+ * YNAB API already uses milliunits natively.
+ */
+export function normalizeYNABTransaction(txn: ynab.TransactionDetail): NormalizedYNABTransaction {
+  return {
+    id: txn.id,
+    date: txn.date,
+    amount: txn.amount, // Already in milliunits - no conversion!
+    payee: txn.payee_name ?? null,
+    memo: txn.memo ?? null,
+    categoryName: txn.category_name ?? null,
+    cleared: txn.cleared,
+    approved: txn.approved,
+  };
+}
+
+/**
+ * Batch convert YNAB transactions.
+ */
+export function normalizeYNABTransactions(
+  txns: ynab.TransactionDetail[],
+): NormalizedYNABTransaction[] {
+  return txns.map(normalizeYNABTransaction);
+}

package/src/types/reconciliation.ts

@@ -0,0 +1,49 @@
+/**
+ * Canonical bank transaction type used throughout reconciliation.
+ *
+ * AMOUNTS ARE IN MILLIUNITS (integers, 1000 = $1.00).
+ * This matches YNAB's native format and allows exact integer comparison.
+ */
+export interface BankTransaction {
+  /** UUID generated for tracking */
+  id: string;
+  /** ISO date string YYYY-MM-DD */
+  date: string;
+  /** Amount in MILLIUNITS (negative = outflow, positive = inflow) */
+  amount: number;
+  /** Merchant/payee name from CSV */
+  payee: string;
+  /** Optional memo/description */
+  memo?: string;
+  /** Original CSV row number (1-indexed, after header) */
+  sourceRow: number;
+  /** Raw values from CSV for debugging */
+  raw: {
+    date: string;
+    amount: string;
+    description: string;
+  };
+  /** Parser warnings (e.g., ambiguous debit/credit) */
+  warnings?: string[];
+}
+
+/**
+ * YNAB transaction normalized for comparison.
+ *
+ * This interface is intentionally SDK-agnostic. Use the adapter
+ * function in ynabAdapter.ts to convert from ynab.TransactionDetail.
+ *
+ * AMOUNTS ARE IN MILLIUNITS - same as YNAB API native format.
+ * No conversion needed from the SDK.
+ */
+export interface NormalizedYNABTransaction {
+  id: string;
+  date: string; // YYYY-MM-DD
+  /** Amount in MILLIUNITS (same as YNAB API) */
+  amount: number;
+  payee: string | null;
+  memo: string | null;
+  categoryName: string | null;
+  cleared: 'cleared' | 'uncleared' | 'reconciled';
+  approved: boolean;
+}