@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/reconciliation/index.ts

@@ -0,0 +1,400 @@
+/**
+ * Reconciliation tool - Phase 1: Analysis Only
+ * Implements guided reconciliation workflow with conservative matching
+ */
+
+import { z } from 'zod/v4';
+import type * as ynab from 'ynab';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { withToolErrorHandling } from '../../types/index.js';
+import { analyzeReconciliation } from './analyzer.js';
+import type { MatchingConfig } from './types.js';
+import { buildReconciliationPayload } from '../reconcileAdapter.js';
+import {
+  executeReconciliation,
+  type AccountSnapshot,
+  type LegacyReconciliationResult,
+} from './executor.js';
+import { responseFormatter } from '../../server/responseFormatter.js';
+import { extractDateRangeFromCSV, autoDetectCSVFormat } from '../compareTransactions/parser.js';
+import type { DeltaFetcher } from '../deltaFetcher.js';
+import { resolveDeltaFetcherArgs } from '../deltaSupport.js';
+
+// Re-export types for external use
+export type * from './types.js';
+export { analyzeReconciliation } from './analyzer.js';
+export { findMatches, findBestMatch } from './matcher.js';
+export { normalizePayee, normalizedMatch, fuzzyMatch, payeeSimilarity } from './payeeNormalizer.js';
+
+/**
+ * Helper function to determine audit data source based on fetch result
+ */
+function getAuditDataSource(
+  transactionsResult: { usedDelta?: boolean; wasCached?: boolean },
+  forceFullRefresh: boolean,
+): string {
+  if (forceFullRefresh) {
+    return 'full_api_fetch_no_delta';
+  }
+  if (transactionsResult.usedDelta) {
+    return 'delta_fetch_with_merge';
+  }
+  if (transactionsResult.wasCached) {
+    return 'delta_fetch_cache_hit';
+  }
+  return 'delta_fetch_full_refresh';
+}
+
+/**
+ * Helper function to determine data freshness based on fetch result
+ */
+function getDataFreshness(
+  transactionsResult: { wasCached?: boolean },
+  forceFullRefresh: boolean,
+): string {
+  if (forceFullRefresh) {
+    return 'guaranteed_fresh';
+  }
+  if (transactionsResult.wasCached) {
+    return 'cache_validated_via_server_knowledge';
+  }
+  return 'fresh_via_delta_fetch';
+}
+
+/**
+ * Schema for reconcile_account tool
+ */
+export const ReconcileAccountSchema = z
+  .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+
+    // CSV input (one required)
+    csv_file_path: z.string().optional(),
+    csv_data: z.string().optional(),
+
+    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: ',',
+      })),
+
+    // Statement information
+    statement_balance: z.number({
+      message: 'Statement balance is required and must be a number',
+    }),
+    statement_start_date: z.string().optional(),
+    statement_end_date: z.string().optional(),
+    statement_date: z.string().optional(),
+    expected_bank_balance: z.number().optional(),
+    as_of_timezone: z.string().optional(),
+
+    // Matching configuration (optional)
+    date_tolerance_days: z.number().min(0).max(7).optional().default(5),
+    amount_tolerance_cents: z.number().min(0).max(100).optional().default(1),
+    auto_match_threshold: z.number().min(0).max(100).optional().default(90),
+    suggestion_threshold: z.number().min(0).max(100).optional().default(60),
+    amount_tolerance: z.number().min(0).max(1).optional(),
+
+    auto_create_transactions: z.boolean().optional().default(false),
+    auto_update_cleared_status: z.boolean().optional().default(false),
+    auto_unclear_missing: z.boolean().optional().default(true),
+    auto_adjust_dates: z.boolean().optional().default(false),
+    invert_bank_amounts: z.boolean().optional(),
+    dry_run: z.boolean().optional().default(true),
+    balance_verification_mode: z
+      .enum(['ANALYSIS_ONLY', 'GUIDED_RESOLUTION', 'AUTO_RESOLVE'])
+      .optional()
+      .default('ANALYSIS_ONLY'),
+    require_exact_match: z.boolean().optional().default(true),
+    confidence_threshold: z.number().min(0).max(1).optional().default(0.8),
+    max_resolution_attempts: z.number().int().min(1).max(10).optional().default(5),
+
+    // Response options
+    include_structured_data: z.boolean().optional().default(false),
+    force_full_refresh: z.boolean().optional().default(true),
+  })
+  .refine((data) => data.csv_file_path || data.csv_data, {
+    message: 'Either csv_file_path or csv_data must be provided',
+    path: ['csv_data'],
+  });
+
+export type ReconcileAccountRequest = z.infer<typeof ReconcileAccountSchema>;
+
+/**
+ * Handle reconciliation analysis and optional execution
+ *
+ * Provides intelligent transaction matching, insight detection, and optional
+ * execution of reconciliation actions. Returns human-readable narrative and
+ * structured JSON data.
+ */
+export async function handleReconcileAccount(
+  ynabAPI: ynab.API,
+  deltaFetcher: DeltaFetcher,
+  params: ReconcileAccountRequest,
+): Promise<CallToolResult>;
+export async function handleReconcileAccount(
+  ynabAPI: ynab.API,
+  params: ReconcileAccountRequest,
+): Promise<CallToolResult>;
+export async function handleReconcileAccount(
+  ynabAPI: ynab.API,
+  deltaFetcherOrParams: DeltaFetcher | ReconcileAccountRequest,
+  maybeParams?: ReconcileAccountRequest,
+): Promise<CallToolResult> {
+  const { deltaFetcher, params } = resolveDeltaFetcherArgs(
+    ynabAPI,
+    deltaFetcherOrParams,
+    maybeParams,
+  );
+  const forceFullRefresh = params.force_full_refresh ?? true;
+  return await withToolErrorHandling(
+    async () => {
+      // Build matching configuration from parameters
+      const config: MatchingConfig = {
+        dateToleranceDays: params.date_tolerance_days,
+        amountToleranceCents: params.amount_tolerance_cents,
+        descriptionSimilarityThreshold: 0.8, // Fixed for Phase 1
+        autoMatchThreshold: params.auto_match_threshold,
+        suggestionThreshold: params.suggestion_threshold,
+      };
+
+      const accountResult = forceFullRefresh
+        ? await deltaFetcher.fetchAccountsFull(params.budget_id)
+        : await deltaFetcher.fetchAccounts(params.budget_id);
+      const accountData = accountResult.data.find((account) => account.id === params.account_id);
+      if (!accountData) {
+        throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
+      }
+      const accountName = accountData.name;
+      const accountType = accountData.type;
+
+      // For liability accounts (credit cards, loans, debts), statement balance should be negative
+      // A positive balance on a credit card statement means you OWE that amount
+      const accountIsLiability =
+        accountType === 'creditCard' ||
+        accountType === 'lineOfCredit' ||
+        accountType === 'mortgage' ||
+        accountType === 'autoLoan' ||
+        accountType === 'studentLoan' ||
+        accountType === 'personalLoan' ||
+        accountType === 'medicalDebt' ||
+        accountType === 'otherDebt' ||
+        accountType === 'otherLiability';
+
+      // Determine whether to invert bank amounts
+      // If invert_bank_amounts is explicitly set, use that value
+      // Otherwise, default to true for liability accounts (legacy behavior)
+      // Note: Some banks (e.g., Wealthsimple) show charges as negative already, matching YNAB
+      const shouldInvertBankAmounts =
+        params.invert_bank_amounts !== undefined ? params.invert_bank_amounts : accountIsLiability;
+
+      // Negate statement balance for liability accounts
+      const adjustedStatementBalance = accountIsLiability
+        ? -Math.abs(params.statement_balance)
+        : params.statement_balance;
+
+      const budgetResponse = await ynabAPI.budgets.getBudgetById(params.budget_id);
+      const currencyCode = budgetResponse.data.budget?.currency_format?.iso_code ?? 'USD';
+
+      // Fetch YNAB transactions for the account
+      // Auto-detect date range from CSV if not explicitly provided
+      let sinceDate: Date;
+
+      if (params.statement_start_date) {
+        // User provided explicit start date
+        sinceDate = new Date(params.statement_start_date);
+      } else {
+        // Auto-detect from CSV content
+        try {
+          const csvContent = params.csv_data || params.csv_file_path || '';
+          const csvFormat = params.csv_format || autoDetectCSVFormat(csvContent);
+
+          // Convert schema format to parser format
+          const parserFormat = {
+            date_column: csvFormat.date_column || 'Date',
+            amount_column: csvFormat.amount_column,
+            debit_column: csvFormat.debit_column,
+            credit_column: csvFormat.credit_column,
+            description_column: csvFormat.description_column || 'Description',
+            date_format: csvFormat.date_format || 'MM/DD/YYYY',
+            has_header: csvFormat.has_header ?? true,
+            delimiter: csvFormat.delimiter || ',',
+          };
+
+          const { minDate } = extractDateRangeFromCSV(csvContent, parserFormat);
+
+          // Add 7-day buffer before min date for pending transactions
+          const minDateObj = new Date(minDate);
+          minDateObj.setDate(minDateObj.getDate() - 7);
+          sinceDate = minDateObj;
+        } catch {
+          // Fallback to 90 days if CSV parsing fails
+          sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
+        }
+      }
+
+      const sinceDateString = sinceDate.toISOString().split('T')[0];
+      const transactionsResult = forceFullRefresh
+        ? await deltaFetcher.fetchTransactionsByAccountFull(
+            params.budget_id,
+            params.account_id,
+            sinceDateString,
+          )
+        : await deltaFetcher.fetchTransactionsByAccount(
+            params.budget_id,
+            params.account_id,
+            sinceDateString,
+          );
+
+      const ynabTransactions = transactionsResult.data;
+
+      const auditMetadata = {
+        data_freshness: getDataFreshness(transactionsResult, forceFullRefresh),
+        data_source: getAuditDataSource(transactionsResult, forceFullRefresh),
+        server_knowledge: transactionsResult.serverKnowledge,
+        fetched_at: new Date().toISOString(),
+        accounts_count: accountResult.data.length,
+        transactions_count: transactionsResult.data.length,
+        cache_status: {
+          accounts_cached: accountResult.wasCached,
+          transactions_cached: transactionsResult.wasCached,
+          delta_merge_applied: transactionsResult.usedDelta,
+        },
+      };
+
+      // Perform analysis
+      const analysis = analyzeReconciliation(
+        params.csv_data || params.csv_file_path || '',
+        params.csv_file_path,
+        ynabTransactions,
+        adjustedStatementBalance,
+        config,
+        currencyCode,
+        params.account_id,
+        params.budget_id,
+        shouldInvertBankAmounts,
+      );
+
+      const initialAccount: AccountSnapshot = {
+        balance: accountData.balance,
+        cleared_balance: accountData.cleared_balance,
+        uncleared_balance: accountData.uncleared_balance,
+      };
+
+      let executionData: LegacyReconciliationResult | undefined;
+      const wantsBalanceVerification = Boolean(params.statement_date);
+      const shouldExecute =
+        params.auto_create_transactions ||
+        params.auto_update_cleared_status ||
+        params.auto_unclear_missing ||
+        params.auto_adjust_dates ||
+        params.balance_verification_mode !== 'ANALYSIS_ONLY' ||
+        wantsBalanceVerification;
+
+      if (shouldExecute) {
+        executionData = await executeReconciliation({
+          ynabAPI,
+          analysis,
+          params,
+          budgetId: params.budget_id,
+          accountId: params.account_id,
+          initialAccount,
+          currencyCode,
+        });
+      }
+
+      const csvFormatForPayload = mapCsvFormatForPayload(params.csv_format);
+
+      const adapterOptions: Parameters<typeof buildReconciliationPayload>[1] = {
+        accountName,
+        accountId: params.account_id,
+        currencyCode,
+        auditMetadata,
+      };
+      if (csvFormatForPayload !== undefined) {
+        adapterOptions.csvFormat = csvFormatForPayload;
+      }
+
+      const payload = buildReconciliationPayload(analysis, adapterOptions, executionData);
+
+      // Build response payload matching ReconcileAccountOutputSchema
+      // Schema expects: { human: string } OR { human: string, structured: object }
+      const responseData: Record<string, unknown> = {
+        human: payload.human,
+      };
+
+      // Only include structured data if requested (can be very large)
+      if (params.include_structured_data) {
+        responseData['structured'] = payload.structured;
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: responseFormatter.format(responseData),
+          },
+        ],
+      };
+    },
+    'ynab:reconcile_account',
+    'analyzing account reconciliation',
+  );
+}
+
+function mapCsvFormatForPayload(format: ReconcileAccountRequest['csv_format'] | undefined):
+  | {
+      delimiter: string;
+      decimal_separator: string;
+      thousands_separator: string | null;
+      date_format: string;
+      header_row: boolean;
+      date_column: string | null;
+      amount_column: string | null;
+      payee_column: string | null;
+    }
+  | undefined {
+  if (!format) {
+    return undefined;
+  }
+
+  const coerceString = (value: string | number | undefined | null, fallback?: string) => {
+    if (value === undefined || value === null) {
+      return fallback ?? null;
+    }
+    return String(value);
+  };
+
+  const delimiter = coerceString(format.delimiter, ',');
+  const decimalSeparator = '.'; // Default decimal separator
+  const thousandsSeparator = ','; // Default thousands separator
+  const dateFormat = coerceString(format.date_format, 'MM/DD/YYYY');
+
+  return {
+    delimiter: delimiter ?? ',',
+    decimal_separator: decimalSeparator,
+    thousands_separator: thousandsSeparator,
+    date_format: dateFormat ?? 'MM/DD/YYYY',
+    header_row: format.has_header ?? true,
+    date_column: coerceString(format.date_column, '') ?? null,
+    amount_column: coerceString(format.amount_column, '') ?? null,
+    payee_column: coerceString(format.description_column, '') ?? null,
+  };
+}

package/src/tools/reconciliation/matcher.ts

@@ -0,0 +1,269 @@
+/**
+ * Transaction matching algorithm for reconciliation
+ * Implements confidence-based matching with auto-match and suggestion tiers
+ */
+
+import { normalizedMatch, payeeSimilarity } from './payeeNormalizer.js';
+import { DEFAULT_MATCHING_CONFIG } from './types.js';
+import type {
+  BankTransaction,
+  YNABTransaction,
+  TransactionMatch,
+  MatchCandidate,
+  MatchingConfig,
+} from './types.js';
+
+/**
+ * Check if two amounts match within tolerance
+ */
+function amountsMatch(bankAmount: number, ynabAmount: number, toleranceCents: number): boolean {
+  // Convert YNAB milliunits to dollars
+  const ynabDollars = ynabAmount / 1000;
+
+  // Round to avoid floating point precision issues
+  const difference = Math.round(Math.abs(bankAmount - ynabDollars) * 100) / 100;
+  const toleranceDollars = toleranceCents / 100;
+
+  return difference <= toleranceDollars;
+}
+
+/**
+ * Check if two dates match within tolerance
+ */
+function datesMatch(date1: string, date2: string, toleranceDays: number): boolean {
+  const d1 = new Date(date1);
+  const d2 = new Date(date2);
+
+  const diffMs = Math.abs(d1.getTime() - d2.getTime());
+  const diffDays = diffMs / (1000 * 60 * 60 * 24);
+
+  return diffDays <= toleranceDays;
+}
+
+/**
+ * Calculate match confidence score between bank and YNAB transaction
+ * Returns score 0-100 and match reasons
+ */
+function calculateMatchScore(
+  bankTxn: BankTransaction,
+  ynabTxn: YNABTransaction,
+  config: MatchingConfig,
+): { score: number; reasons: string[] } {
+  const reasons: string[] = [];
+  let score = 0;
+
+  // Amount match (40% weight) - REQUIRED
+  const amountMatch = amountsMatch(bankTxn.amount, ynabTxn.amount, config.amountToleranceCents);
+  if (!amountMatch) {
+    return { score: 0, reasons: ['Amount does not match'] };
+  }
+  score += 40;
+  reasons.push('Amount matches');
+
+  // Date match (40% weight)
+  const dateWithinTolerance = datesMatch(bankTxn.date, ynabTxn.date, config.dateToleranceDays);
+  if (dateWithinTolerance) {
+    score += 40;
+    const daysDiff = Math.abs(
+      (new Date(bankTxn.date).getTime() - new Date(ynabTxn.date).getTime()) / (1000 * 60 * 60 * 24),
+    );
+    if (daysDiff === 0) {
+      reasons.push('Exact date match');
+    } else {
+      reasons.push(`Date within ${Math.round(daysDiff)} days`);
+    }
+  }
+
+  // Payee match (20% weight)
+  const payeeScore = payeeSimilarity(bankTxn.payee, ynabTxn.payee_name);
+
+  if (normalizedMatch(bankTxn.payee, ynabTxn.payee_name)) {
+    score += 20;
+    reasons.push('Payee exact match');
+  } else if (payeeScore >= 95) {
+    score += 15;
+    reasons.push(`Payee highly similar (${Math.round(payeeScore)}%)`);
+  } else if (payeeScore >= 80) {
+    score += 10;
+    reasons.push(`Payee similar (${Math.round(payeeScore)}%)`);
+  } else if (payeeScore >= 60) {
+    score += 6;
+    reasons.push(`Payee somewhat similar (${Math.round(payeeScore)}%)`);
+  }
+
+  return { score: Math.round(score), reasons };
+}
+
+/**
+ * Priority scoring for YNAB transactions
+ * Uncleared transactions get higher priority than cleared ones
+ */
+function getPriority(ynabTxn: YNABTransaction): number {
+  // Uncleared transactions are expecting bank confirmation
+  if (ynabTxn.cleared === 'uncleared') return 10;
+  if (ynabTxn.cleared === 'cleared') return 5;
+  if (ynabTxn.cleared === 'reconciled') return 1;
+  return 0;
+}
+
+/**
+ * Find all matching candidates for a bank transaction
+ */
+function findMatchCandidates(
+  bankTxn: BankTransaction,
+  ynabTransactions: YNABTransaction[],
+  usedIds: Set<string>,
+  config: MatchingConfig,
+): MatchCandidate[] {
+  const candidates: MatchCandidate[] = [];
+
+  for (const ynabTxn of ynabTransactions) {
+    // Skip already matched transactions
+    if (usedIds.has(ynabTxn.id)) continue;
+
+    // Skip opposite-signed transactions (refunds vs purchases)
+    if (bankTxn.amount > 0 !== ynabTxn.amount > 0) continue;
+
+    // Calculate match score
+    const { score, reasons } = calculateMatchScore(bankTxn, ynabTxn, config);
+
+    // Only include candidates with minimum score
+    if (score >= 30) {
+      candidates.push({
+        ynab_transaction: ynabTxn,
+        confidence: score,
+        match_reason: reasons.join(', '),
+        explanation: buildExplanation(bankTxn, ynabTxn, score, reasons),
+      });
+    }
+  }
+
+  // Sort by confidence (desc), then priority (desc), then date proximity
+  candidates.sort((a, b) => {
+    if (b.confidence !== a.confidence) {
+      return b.confidence - a.confidence;
+    }
+    const priorityDiff = getPriority(b.ynab_transaction) - getPriority(a.ynab_transaction);
+    if (priorityDiff !== 0) return priorityDiff;
+
+    // Date proximity as tiebreaker
+    const dateProximityA = Math.abs(
+      new Date(bankTxn.date).getTime() - new Date(a.ynab_transaction.date).getTime(),
+    );
+    const dateProximityB = Math.abs(
+      new Date(bankTxn.date).getTime() - new Date(b.ynab_transaction.date).getTime(),
+    );
+    return dateProximityA - dateProximityB;
+  });
+
+  return candidates;
+}
+
+/**
+ * Build human-readable explanation for a match
+ */
+function buildExplanation(
+  _bankTxn: BankTransaction,
+  ynabTxn: YNABTransaction,
+  score: number,
+  reasons: string[],
+): string {
+  const parts: string[] = [];
+
+  parts.push(`Match confidence: ${score}%`);
+  parts.push(reasons.join(', '));
+
+  if (ynabTxn.cleared === 'uncleared') {
+    parts.push('(Uncleared - awaiting confirmation)');
+  }
+
+  return parts.join(' | ');
+}
+
+/**
+ * Find best match for a single bank transaction
+ */
+export function findBestMatch(
+  bankTxn: BankTransaction,
+  ynabTransactions: YNABTransaction[],
+  usedIds: Set<string>,
+  config: MatchingConfig,
+): TransactionMatch {
+  const candidates = findMatchCandidates(bankTxn, ynabTransactions, usedIds, config);
+
+  if (candidates.length === 0) {
+    // No match found
+    return {
+      bank_transaction: bankTxn,
+      confidence: 'none',
+      confidence_score: 0,
+      match_reason: 'No matching transaction found in YNAB',
+      action_hint: 'add_to_ynab',
+      recommendation: 'This transaction appears on bank statement but not in YNAB',
+    };
+  }
+
+  const bestCandidate = candidates[0]!; // Safe: we checked candidates.length > 0
+  const bestScore = bestCandidate.confidence;
+
+  // HIGH confidence: Auto-match candidate (≥90%)
+  if (bestScore >= config.autoMatchThreshold) {
+    return {
+      bank_transaction: bankTxn,
+      ynab_transaction: bestCandidate.ynab_transaction,
+      confidence: 'high',
+      confidence_score: bestScore,
+      match_reason: bestCandidate.match_reason,
+    };
+  }
+
+  // MEDIUM confidence: Suggested match (60-89%)
+  if (bestScore >= config.suggestionThreshold) {
+    return {
+      bank_transaction: bankTxn,
+      ynab_transaction: bestCandidate.ynab_transaction,
+      candidates: candidates.slice(0, 3), // Top 3 candidates
+      confidence: 'medium',
+      confidence_score: bestScore,
+      match_reason: bestCandidate.match_reason,
+      top_confidence: bestScore,
+      action_hint: 'review_and_choose',
+    };
+  }
+
+  // LOW confidence: Show as possible match but don't auto-suggest (30-59%)
+  return {
+    bank_transaction: bankTxn,
+    candidates: candidates.slice(0, 3),
+    confidence: 'low',
+    confidence_score: bestScore,
+    match_reason: 'Low confidence match',
+    top_confidence: bestScore,
+    action_hint: 'review_or_add_new',
+    recommendation: 'Consider reviewing candidates or adding as new transaction',
+  };
+}
+
+/**
+ * Find matches for all bank transactions
+ */
+export function findMatches(
+  bankTransactions: BankTransaction[],
+  ynabTransactions: YNABTransaction[],
+  config: MatchingConfig = DEFAULT_MATCHING_CONFIG as MatchingConfig,
+): TransactionMatch[] {
+  const matches: TransactionMatch[] = [];
+  const usedIds = new Set<string>();
+
+  for (const bankTxn of bankTransactions) {
+    const match = findBestMatch(bankTxn, ynabTransactions, usedIds, config);
+    matches.push(match);
+
+    // Mark high-confidence matches as used to prevent duplicate matching
+    if (match.confidence === 'high' && match.ynab_transaction) {
+      usedIds.add(match.ynab_transaction.id);
+    }
+  }
+
+  return matches;
+}