@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/reconciliation/reportFormatter.ts

@@ -0,0 +1,363 @@
+/**
+ * Human-readable report formatting for reconciliation results
+ * Implements Phase 3 of dual-channel output improvements
+ */
+
+import type {
+  ReconciliationAnalysis,
+  TransactionMatch,
+  BankTransaction,
+  YNABTransaction,
+  ReconciliationInsight,
+  BalanceInfo,
+} from './types.js';
+import type { LegacyReconciliationResult } from './executor.js';
+import type { MoneyValue } from '../../utils/money.js';
+
+/**
+ * Options for report formatting
+ */
+export interface ReportFormatterOptions {
+  accountName?: string | undefined;
+  accountId?: string | undefined;
+  currencyCode?: string | undefined;
+  includeDetailedMatches?: boolean | undefined;
+  maxUnmatchedToShow?: number | undefined;
+  maxInsightsToShow?: number | undefined;
+}
+
+/**
+ * Format the main human-readable reconciliation report
+ */
+export function formatHumanReadableReport(
+  analysis: ReconciliationAnalysis,
+  options: ReportFormatterOptions = {},
+  execution?: LegacyReconciliationResult,
+): string {
+  const accountLabel = options.accountName ?? 'Account';
+  const sections: string[] = [];
+
+  // Header
+  sections.push(formatHeader(accountLabel, analysis));
+
+  // Balance check section
+  sections.push(formatBalanceSection(analysis.balance_info, analysis.summary));
+
+  // Transaction analysis section
+  sections.push(formatTransactionAnalysisSection(analysis, options));
+
+  // Insights section (if any)
+  if (analysis.insights.length > 0) {
+    sections.push(formatInsightsSection(analysis.insights, options.maxInsightsToShow));
+  }
+
+  // Execution summary (if any)
+  if (execution) {
+    sections.push(formatExecutionSection(execution));
+  }
+
+  // Recommendations/Next steps
+  sections.push(formatRecommendationsSection(analysis, execution));
+
+  return sections.join('\n\n');
+}
+
+/**
+ * Format the report header
+ */
+function formatHeader(accountName: string, analysis: ReconciliationAnalysis): string {
+  const lines: string[] = [];
+  lines.push(`📊 ${accountName} Reconciliation Report`);
+  lines.push('═'.repeat(60));
+  lines.push(`Statement Period: ${analysis.summary.statement_date_range}`);
+  return lines.join('\n');
+}
+
+/**
+ * Format the balance check section
+ */
+function formatBalanceSection(
+  balanceInfo: BalanceInfo,
+  summary: ReconciliationAnalysis['summary'],
+): string {
+  const lines: string[] = [];
+  lines.push('BALANCE CHECK');
+  lines.push('═'.repeat(60));
+
+  // Current balances
+  lines.push(`✓ YNAB Cleared Balance:  ${summary.current_cleared_balance.value_display}`);
+  lines.push(`✓ Statement Balance:     ${summary.target_statement_balance.value_display}`);
+  lines.push('');
+
+  // Discrepancy status
+  const discrepancyMilli = balanceInfo.discrepancy.value_milliunits;
+  if (discrepancyMilli === 0) {
+    lines.push('✅ BALANCES MATCH PERFECTLY');
+  } else {
+    const direction = discrepancyMilli > 0 ? 'ynab_higher' : 'bank_higher';
+    const directionLabel =
+      direction === 'ynab_higher'
+        ? 'YNAB shows MORE than statement'
+        : 'Statement shows MORE than YNAB';
+
+    lines.push(`❌ DISCREPANCY: ${balanceInfo.discrepancy.value_display}`);
+    lines.push(`   Direction: ${directionLabel}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format the transaction analysis section
+ */
+function formatTransactionAnalysisSection(
+  analysis: ReconciliationAnalysis,
+  options: ReportFormatterOptions,
+): string {
+  const lines: string[] = [];
+  lines.push('TRANSACTION ANALYSIS');
+  lines.push('═'.repeat(60));
+
+  const summary = analysis.summary;
+  lines.push(
+    `✓ Automatically matched:  ${summary.auto_matched} of ${summary.bank_transactions_count} transactions`,
+  );
+  lines.push(`✓ Suggested matches:      ${summary.suggested_matches}`);
+  lines.push(`✓ Unmatched bank:         ${summary.unmatched_bank}`);
+  lines.push(`✓ Unmatched YNAB:         ${summary.unmatched_ynab}`);
+
+  // Show unmatched bank transactions (if any)
+  if (analysis.unmatched_bank.length > 0) {
+    lines.push('');
+    lines.push('❌ UNMATCHED BANK TRANSACTIONS:');
+    const maxToShow = options.maxUnmatchedToShow ?? 5;
+    const toShow = analysis.unmatched_bank.slice(0, maxToShow);
+
+    for (const txn of toShow) {
+      lines.push(formatBankTransactionLine(txn));
+    }
+
+    if (analysis.unmatched_bank.length > maxToShow) {
+      lines.push(`   ... and ${analysis.unmatched_bank.length - maxToShow} more`);
+    }
+  }
+
+  // Show suggested matches (if any)
+  if (analysis.suggested_matches.length > 0) {
+    lines.push('');
+    lines.push('💡 SUGGESTED MATCHES:');
+    const maxToShow = options.maxUnmatchedToShow ?? 3;
+    const toShow = analysis.suggested_matches.slice(0, maxToShow);
+
+    for (const match of toShow) {
+      lines.push(formatSuggestedMatchLine(match));
+    }
+
+    if (analysis.suggested_matches.length > maxToShow) {
+      lines.push(`   ... and ${analysis.suggested_matches.length - maxToShow} more suggestions`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a bank transaction line
+ */
+function formatBankTransactionLine(txn: BankTransaction): string {
+  const amountStr = formatAmount(txn.amount);
+  return `   ${txn.date} - ${txn.payee.substring(0, 40).padEnd(40)} ${amountStr}`;
+}
+
+/**
+ * Format a suggested match line
+ */
+function formatSuggestedMatchLine(match: TransactionMatch): string {
+  const bankTxn = match.bank_transaction;
+  const amountStr = formatAmount(bankTxn.amount);
+  const confidenceStr = `${match.confidence_score}%`;
+  return `   ${bankTxn.date} - ${bankTxn.payee.substring(0, 35).padEnd(35)} ${amountStr} (${confidenceStr} confidence)`;
+}
+
+/**
+ * Format an amount for display
+ */
+function formatAmount(amount: number): string {
+  const sign = amount >= 0 ? '+' : '-';
+  const absAmount = Math.abs(amount);
+  return `${sign}$${absAmount.toFixed(2)}`.padStart(10);
+}
+
+/**
+ * Format the insights section
+ */
+function formatInsightsSection(insights: ReconciliationInsight[], maxToShow: number = 3): string {
+  const lines: string[] = [];
+  lines.push('KEY INSIGHTS');
+  lines.push('═'.repeat(60));
+
+  const toShow = insights.slice(0, maxToShow);
+  for (const insight of toShow) {
+    const severityIcon = getSeverityIcon(insight.severity);
+    lines.push(`${severityIcon} ${insight.title}`);
+    lines.push(`   ${insight.description}`);
+
+    // Show evidence summary if available
+    if (insight.evidence && Object.keys(insight.evidence).length > 0) {
+      const evidenceSummary = formatEvidenceSummary(insight.evidence);
+      if (evidenceSummary) {
+        lines.push(`   Evidence: ${evidenceSummary}`);
+      }
+    }
+
+    lines.push('');
+  }
+
+  if (insights.length > maxToShow) {
+    lines.push(`... and ${insights.length - maxToShow} more insights (see structured output)`);
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+/**
+ * Get emoji icon for severity level
+ */
+function getSeverityIcon(severity: string): string {
+  switch (severity) {
+    case 'critical':
+      return '🚨';
+    case 'warning':
+      return '⚠️';
+    case 'info':
+      return 'ℹ️';
+    default:
+      return '•';
+  }
+}
+
+/**
+ * Format evidence summary from insight evidence object
+ */
+function formatEvidenceSummary(evidence: Record<string, unknown>): string | null {
+  // Handle common evidence patterns
+  if ('transaction_count' in evidence) {
+    return `${evidence['transaction_count']} transactions`;
+  }
+  if ('amount' in evidence && typeof evidence['amount'] === 'object') {
+    const amount = evidence['amount'] as MoneyValue;
+    return amount.value_display;
+  }
+  if ('transaction_ids' in evidence && Array.isArray(evidence['transaction_ids'])) {
+    return `${evidence['transaction_ids'].length} transactions involved`;
+  }
+  return null;
+}
+
+/**
+ * Format the execution section
+ */
+function formatExecutionSection(execution: LegacyReconciliationResult): string {
+  const lines: string[] = [];
+  lines.push('EXECUTION SUMMARY');
+  lines.push('═'.repeat(60));
+
+  const summary = execution.summary;
+  lines.push(`• Transactions created:  ${summary.transactions_created}`);
+  lines.push(`• Transactions updated:  ${summary.transactions_updated}`);
+  lines.push(`• Date adjustments:      ${summary.dates_adjusted}`);
+
+  // Show top recommendations if any
+  if (execution.recommendations.length > 0) {
+    lines.push('');
+    lines.push('Recommendations:');
+    const maxRecs = 3;
+    const toShow = execution.recommendations.slice(0, maxRecs);
+    for (const rec of toShow) {
+      lines.push(`  • ${rec}`);
+    }
+    if (execution.recommendations.length > maxRecs) {
+      lines.push(`  ... and ${execution.recommendations.length - maxRecs} more`);
+    }
+  }
+
+  lines.push('');
+  if (summary.dry_run) {
+    lines.push('⚠️  Dry run only — no YNAB changes were applied.');
+  } else {
+    lines.push('✅ Changes applied to YNAB. Review structured output for action details.');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format the recommendations/next steps section
+ */
+function formatRecommendationsSection(
+  analysis: ReconciliationAnalysis,
+  execution?: LegacyReconciliationResult,
+): string {
+  const lines: string[] = [];
+  lines.push('RECOMMENDED ACTIONS');
+  lines.push('═'.repeat(60));
+
+  // If we have execution results, recommendations are already shown
+  if (execution && !execution.summary.dry_run) {
+    lines.push('All recommended actions have been applied.');
+    return lines.join('\n');
+  }
+
+  // Show next steps from analysis
+  if (analysis.next_steps.length > 0) {
+    for (const step of analysis.next_steps) {
+      lines.push(`• ${step}`);
+    }
+  } else {
+    lines.push('• No specific actions recommended.');
+    lines.push('• Review the structured output for detailed match information.');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a balance section (helper for backward compatibility)
+ */
+export function formatBalanceInfo(balance: BalanceInfo): string {
+  const lines: string[] = [];
+  lines.push(`Current Cleared:  ${balance.current_cleared.value_display}`);
+  lines.push(`Current Total:    ${balance.current_total.value_display}`);
+  lines.push(`Target Statement: ${balance.target_statement.value_display}`);
+  lines.push(`Discrepancy:      ${balance.discrepancy.value_display}`);
+  return lines.join('\n');
+}
+
+/**
+ * Format transaction list (helper for detailed reports)
+ */
+export function formatTransactionList(
+  transactions: BankTransaction[] | YNABTransaction[],
+  maxItems: number = 10,
+): string {
+  const lines: string[] = [];
+  const toShow = transactions.slice(0, maxItems);
+
+  for (const txn of toShow) {
+    if ('payee' in txn) {
+      // Bank transaction
+      lines.push(formatBankTransactionLine(txn));
+    } 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)}`);
+    }
+  }
+
+  if (transactions.length > maxItems) {
+    lines.push(`   ... and ${transactions.length - maxItems} more`);
+  }
+
+  return lines.join('\n');
+}

package/src/tools/reconciliation/types.ts

@@ -0,0 +1,314 @@
+/**
+ * Type definitions for the reconciliation tool
+ * Based on the 2025-10-31 reconciliation redesign specification
+ */
+
+import type { MoneyValue } from '../../utils/money.js';
+
+/**
+ * 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
+ */
+export interface MatchCandidate {
+  ynab_transaction: YNABTransaction;
+  confidence: number;
+  match_reason: string;
+  explanation: string;
+}
+
+/**
+ * Transaction match result
+ */
+export interface TransactionMatch {
+  bank_transaction: BankTransaction;
+  /** Best matched YNAB transaction (if any) */
+  ynab_transaction?: YNABTransaction;
+  /** Alternative candidates for suggested matches */
+  candidates?: MatchCandidate[];
+  /** Confidence level */
+  confidence: MatchConfidence;
+  /** Confidence score 0-100 */
+  confidence_score: number;
+  /** Reason for the match */
+  match_reason: string;
+  /** Top confidence from candidates */
+  top_confidence?: number;
+  /** Action hint for user */
+  action_hint?: string;
+  /** Recommendation text */
+  recommendation?: string;
+}
+
+/**
+ * Balance information with structured monetary values
+ */
+export interface BalanceInfo {
+  current_cleared: MoneyValue;
+  current_uncleared: MoneyValue;
+  current_total: MoneyValue;
+  target_statement: MoneyValue;
+  discrepancy: MoneyValue;
+  on_track: boolean;
+}
+
+/**
+ * Reconciliation summary statistics with structured monetary values
+ */
+export interface ReconciliationSummary {
+  statement_date_range: string;
+  bank_transactions_count: number;
+  ynab_transactions_count: number;
+  auto_matched: number;
+  suggested_matches: number;
+  unmatched_bank: number;
+  unmatched_ynab: number;
+  current_cleared_balance: MoneyValue;
+  target_statement_balance: MoneyValue;
+  discrepancy: MoneyValue;
+  discrepancy_explanation: string;
+}
+
+/**
+ * Insight severity levels
+ */
+export type InsightSeverity = 'info' | 'warning' | 'critical';
+
+/**
+ * Insight types for reconciliation analysis
+ */
+export type InsightKind = 'repeat_amount' | 'near_match' | 'anomaly';
+
+/**
+ * Reconciliation insight - highlights important findings that help explain discrepancies
+ */
+export interface ReconciliationInsight {
+  id: string;
+  type: InsightKind;
+  severity: InsightSeverity;
+  title: string;
+  description: string;
+  evidence?: Record<string, unknown>;
+}
+
+/**
+ * Analysis phase result
+ */
+export interface ReconciliationAnalysis {
+  success: true;
+  phase: 'analysis';
+  summary: ReconciliationSummary;
+  auto_matches: TransactionMatch[];
+  suggested_matches: TransactionMatch[];
+  unmatched_bank: BankTransaction[];
+  unmatched_ynab: YNABTransaction[];
+  balance_info: BalanceInfo;
+  next_steps: string[];
+  insights: ReconciliationInsight[];
+  recommendations?: ActionableRecommendation[];
+}
+
+/**
+ * Reconciliation action types
+ */
+export type ReconciliationActionType = 'match' | 'add' | 'unclear' | 'delete' | 'ignore';
+
+/**
+ * Reconciliation action
+ */
+export interface ReconciliationAction {
+  type: ReconciliationActionType;
+  bank_txn_id?: string;
+  ynab_txn_id?: string;
+  mark_cleared?: boolean;
+  create_as_cleared?: boolean;
+  reason?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Matching algorithm configuration
+ */
+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;
+}
+
+/**
+ * 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,
+};
+
+/**
+ * Parsed CSV data from compareTransactions
+ */
+export interface ParsedCSVData {
+  transactions: BankTransaction[];
+  format_detected: string;
+  delimiter: string;
+  total_rows: number;
+  valid_rows: number;
+  errors: string[];
+}
+
+/**
+ * Priority levels for actionable recommendations
+ */
+export type RecommendationPriority = 'high' | 'medium' | 'low';
+
+/**
+ * Base fields common to all recommendation types
+ */
+export interface BaseRecommendation {
+  /** Unique identifier for this recommendation */
+  id: string;
+  /** Priority level for execution */
+  priority: RecommendationPriority;
+  /** Confidence score 0-1 (higher = more confident) */
+  confidence: number;
+  /** Human-readable message describing the recommendation */
+  message: string;
+  /** Explanation of why this recommendation was generated */
+  reason: string;
+  /** Estimated impact on reconciliation balance */
+  estimated_impact: MoneyValue;
+  /** YNAB account ID this recommendation applies to */
+  account_id: string;
+  /** Optional link to the insight that generated this recommendation */
+  source_insight_id?: string;
+  /** Additional metadata (version, timestamps, etc.) */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Recommendation to create a new YNAB transaction
+ */
+export interface CreateTransactionRecommendation extends BaseRecommendation {
+  action_type: 'create_transaction';
+  parameters: {
+    account_id: string;
+    date: string;
+    amount: number;
+    payee_name: string;
+    memo?: string;
+    cleared: 'cleared' | 'uncleared';
+    approved: boolean;
+    category_id?: string;
+  };
+}
+
+/**
+ * Recommendation to update a transaction's cleared status
+ */
+export interface UpdateClearedRecommendation extends BaseRecommendation {
+  action_type: 'update_cleared';
+  parameters: {
+    transaction_id: string;
+    cleared: 'cleared' | 'uncleared' | 'reconciled';
+  };
+}
+
+/**
+ * Recommendation to review potential duplicate transactions
+ */
+export interface ReviewDuplicateRecommendation extends BaseRecommendation {
+  action_type: 'review_duplicate';
+  parameters: {
+    candidate_ids: string[];
+    bank_transaction?: BankTransaction;
+    suggested_match_id?: string;
+  };
+}
+
+/**
+ * Related transaction reference for manual review
+ */
+export interface RelatedTransaction {
+  source: 'bank' | 'ynab';
+  id: string;
+  description: string;
+}
+
+/**
+ * Recommendation requiring manual investigation
+ */
+export interface ManualReviewRecommendation extends BaseRecommendation {
+  action_type: 'manual_review';
+  parameters: {
+    issue_type: 'complex_match' | 'large_discrepancy' | 'unknown';
+    related_transactions?: RelatedTransaction[];
+  };
+}
+
+/**
+ * Union type of all possible recommendation types (discriminated by action_type)
+ */
+export type ActionableRecommendation =
+  | CreateTransactionRecommendation
+  | UpdateClearedRecommendation
+  | ReviewDuplicateRecommendation
+  | ManualReviewRecommendation;
+
+/**
+ * Context passed to recommendation engine for generating recommendations
+ */
+export interface RecommendationContext {
+  /** Account ID for the recommendations */
+  account_id: string;
+  /** Budget ID (reserved for future category suggestions) */
+  budget_id: string;
+  /** The reconciliation analysis results */
+  analysis: ReconciliationAnalysis;
+  /** Matching configuration used during analysis */
+  matching_config: MatchingConfig;
+}