@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/reconcileAdapter.ts

@@ -0,0 +1,312 @@
+import { toMoneyValue, toMoneyValueFromDecimal } from '../utils/money.js';
+import type {
+  ReconciliationAnalysis,
+  TransactionMatch,
+  BankTransaction,
+  YNABTransaction,
+  ReconciliationInsight,
+} from './reconciliation/types.js';
+import type { LegacyReconciliationResult, AccountSnapshot } from './reconciliation/executor.js';
+import {
+  formatHumanReadableReport,
+  type ReportFormatterOptions,
+} from './reconciliation/reportFormatter.js';
+
+const OUTPUT_VERSION = '2.0';
+const SCHEMA_URL =
+  'https://raw.githubusercontent.com/dizzlkheinz/ynab-mcp-mcpb/master/docs/schemas/reconciliation-v2.json';
+
+interface AdapterOptions {
+  accountName?: string;
+  accountId?: string;
+  currencyCode?: string;
+  csvFormat?: CsvFormatPayload;
+  auditMetadata?: Record<string, unknown>;
+}
+
+interface DualChannelPayload {
+  human: string;
+  structured: Record<string, unknown>;
+}
+
+interface CsvFormatPayload {
+  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;
+}
+
+interface LegacyPrecisionCalculations {
+  bank_statement_balance_milliunits: number;
+  ynab_calculated_balance_milliunits: number;
+  discrepancy_milliunits: number;
+  discrepancy_dollars: number;
+}
+
+interface LegacyLikelyCause {
+  cause_type: string;
+  description: string;
+  confidence: number;
+  amount_milliunits: number;
+  suggested_resolution: string;
+  evidence: unknown[];
+}
+
+interface LegacyBalanceReconciliation {
+  status: string;
+  precision_calculations?: LegacyPrecisionCalculations;
+  discrepancy_analysis?:
+    | {
+        confidence_level: number;
+        likely_causes: LegacyLikelyCause[];
+        risk_assessment: string;
+      }
+    | undefined;
+  final_verification?: {
+    balance_matches_exactly: boolean;
+    all_transactions_accounted: boolean;
+    audit_trail_complete: boolean;
+    reconciliation_complete: boolean;
+  };
+}
+
+const toBankTransactionView = (txn: BankTransaction, currency: string) => ({
+  ...txn,
+  amount_money: toMoneyValueFromDecimal(txn.amount, currency),
+});
+
+const toYNABTransactionView = (txn: YNABTransaction, currency: string) => ({
+  ...txn,
+  amount_money: toMoneyValue(txn.amount, currency),
+});
+
+const convertMatch = (match: TransactionMatch, currency: string) => ({
+  ...match,
+  bank_transaction: toBankTransactionView(match.bank_transaction, currency),
+  ynab_transaction: match.ynab_transaction
+    ? toYNABTransactionView(match.ynab_transaction, currency)
+    : undefined,
+  candidates: match.candidates?.map((candidate) => ({
+    ...candidate,
+    ynab_transaction: toYNABTransactionView(candidate.ynab_transaction, currency),
+  })),
+});
+
+const convertInsight = (insight: ReconciliationInsight) => ({
+  id: insight.id,
+  type: insight.type,
+  severity: insight.severity,
+  title: insight.title,
+  description: insight.description,
+  evidence: insight.evidence ?? {},
+});
+
+const convertSummary = (analysis: ReconciliationAnalysis) => ({
+  statement_date_range: analysis.summary.statement_date_range,
+  bank_transactions_count: analysis.summary.bank_transactions_count,
+  ynab_transactions_count: analysis.summary.ynab_transactions_count,
+  auto_matched: analysis.summary.auto_matched,
+  suggested_matches: analysis.summary.suggested_matches,
+  unmatched_bank: analysis.summary.unmatched_bank,
+  unmatched_ynab: analysis.summary.unmatched_ynab,
+  current_cleared_balance: analysis.summary.current_cleared_balance,
+  target_statement_balance: analysis.summary.target_statement_balance,
+  discrepancy: analysis.summary.discrepancy,
+  discrepancy_explanation: analysis.summary.discrepancy_explanation,
+});
+
+const convertBalanceInfo = (analysis: ReconciliationAnalysis) => {
+  const discrepancyMilli = analysis.balance_info.discrepancy.value_milliunits;
+  const direction =
+    discrepancyMilli === 0 ? 'balanced' : discrepancyMilli > 0 ? 'ynab_higher' : 'bank_higher';
+
+  return {
+    current_cleared: analysis.balance_info.current_cleared,
+    current_uncleared: analysis.balance_info.current_uncleared,
+    current_total: analysis.balance_info.current_total,
+    target_statement: analysis.balance_info.target_statement,
+    discrepancy: analysis.balance_info.discrepancy,
+    discrepancy_direction: direction,
+    on_track: analysis.balance_info.on_track,
+  };
+};
+
+const convertAccountSnapshot = (snapshot: AccountSnapshot, currency: string) => ({
+  balance: toMoneyValue(snapshot.balance, currency),
+  cleared_balance: toMoneyValue(snapshot.cleared_balance, currency),
+  uncleared_balance: toMoneyValue(snapshot.uncleared_balance, currency),
+});
+
+const convertPrecisionCalculations = (
+  precision: LegacyPrecisionCalculations,
+  currency: string,
+) => ({
+  bank_statement_balance: toMoneyValue(precision.bank_statement_balance_milliunits, currency),
+  ynab_calculated_balance: toMoneyValue(precision.ynab_calculated_balance_milliunits, currency),
+  discrepancy: toMoneyValue(precision.discrepancy_milliunits, currency),
+  discrepancy_decimal: toMoneyValueFromDecimal(precision.discrepancy_dollars, currency),
+});
+
+const convertLikelyCausesLegacy = (
+  analysis: NonNullable<LegacyBalanceReconciliation['discrepancy_analysis']>,
+  currency: string,
+) => ({
+  confidence_level: analysis.confidence_level,
+  risk_assessment: analysis.risk_assessment,
+  likely_causes: analysis.likely_causes.map((cause) => ({
+    type: cause.cause_type.toLowerCase(),
+    description: cause.description,
+    confidence: cause.confidence,
+    suggested_action: cause.suggested_resolution,
+    amount: toMoneyValue(cause.amount_milliunits, currency),
+    evidence: cause.evidence,
+  })),
+});
+
+const convertBalanceReconciliationLegacy = (
+  balance: LegacyBalanceReconciliation | undefined,
+  currency: string,
+) => {
+  if (!balance) return undefined;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result: any = {
+    status: balance.status,
+  };
+
+  if (balance.precision_calculations) {
+    result.precision_calculations = convertPrecisionCalculations(
+      balance.precision_calculations,
+      currency,
+    );
+  }
+
+  if (balance.discrepancy_analysis) {
+    result.discrepancy_analysis = convertLikelyCausesLegacy(balance.discrepancy_analysis, currency);
+  }
+
+  if (balance.final_verification) {
+    result.final_verification = balance.final_verification;
+  }
+
+  return result;
+};
+
+interface ConvertedExecutionResult {
+  summary: LegacyReconciliationResult['summary'];
+  account_balance: {
+    before: ReturnType<typeof convertAccountSnapshot>;
+    after: ReturnType<typeof convertAccountSnapshot>;
+  };
+  actions_taken: LegacyReconciliationResult['actions_taken'];
+  recommendations: LegacyReconciliationResult['recommendations'];
+  balance_reconciliation?: ReturnType<typeof convertBalanceReconciliationLegacy>;
+  bulk_operation_details?: LegacyReconciliationResult['bulk_operation_details'];
+}
+
+const convertExecution = (
+  execution: LegacyReconciliationResult,
+  currency: string,
+): ConvertedExecutionResult => {
+  const result: ConvertedExecutionResult = {
+    summary: execution.summary,
+    account_balance: {
+      before: convertAccountSnapshot(execution.account_balance.before, currency),
+      after: convertAccountSnapshot(execution.account_balance.after, currency),
+    },
+    actions_taken: execution.actions_taken,
+    recommendations: execution.recommendations,
+  };
+
+  if (execution.balance_reconciliation) {
+    result.balance_reconciliation = convertBalanceReconciliationLegacy(
+      execution.balance_reconciliation,
+      currency,
+    );
+  }
+
+  if (execution.bulk_operation_details) {
+    result.bulk_operation_details = execution.bulk_operation_details;
+  }
+
+  return result;
+};
+
+// Helper functions for converting data structures (kept for structured output)
+
+/**
+ * Build human-readable narrative using the comprehensive report formatter
+ */
+const buildHumanNarrative = (
+  analysis: ReconciliationAnalysis,
+  options: AdapterOptions,
+  execution?: LegacyReconciliationResult,
+): string => {
+  const formatterOptions: ReportFormatterOptions = {
+    accountName: options.accountName,
+    accountId: options.accountId,
+    currencyCode: options.currencyCode,
+    includeDetailedMatches: false,
+    maxUnmatchedToShow: 5,
+    maxInsightsToShow: 3,
+  };
+
+  return formatHumanReadableReport(analysis, formatterOptions, execution);
+};
+
+export const buildReconciliationPayload = (
+  analysis: ReconciliationAnalysis,
+  options: AdapterOptions = {},
+  execution?: LegacyReconciliationResult,
+): DualChannelPayload => {
+  const currency = options.currencyCode ?? 'USD';
+  const executionView = execution ? convertExecution(execution, currency) : undefined;
+
+  const structured: Record<string, unknown> = {
+    version: OUTPUT_VERSION,
+    schema_url: SCHEMA_URL,
+    generated_at: new Date().toISOString(),
+    account: {
+      id: options.accountId,
+      name: options.accountName,
+    },
+    summary: convertSummary(analysis),
+    balance: convertBalanceInfo(analysis),
+    insights: analysis.insights.map(convertInsight),
+    next_steps: analysis.next_steps,
+    matches: {
+      auto: analysis.auto_matches.map((match) => convertMatch(match, currency)),
+      suggested: analysis.suggested_matches.map((match) => convertMatch(match, currency)),
+    },
+    unmatched: {
+      bank: analysis.unmatched_bank.map((txn) => toBankTransactionView(txn, currency)),
+      ynab: analysis.unmatched_ynab.map((txn) => toYNABTransactionView(txn, currency)),
+    },
+  };
+
+  // Include recommendations if available
+  if (analysis.recommendations && analysis.recommendations.length > 0) {
+    structured['recommendations'] = analysis.recommendations;
+  }
+
+  if (options.csvFormat) {
+    structured['csv_format'] = options.csvFormat;
+  }
+
+  if (executionView) {
+    structured['execution'] = executionView;
+  }
+
+  if (options.auditMetadata) {
+    structured['audit'] = options.auditMetadata;
+  }
+
+  return {
+    human: buildHumanNarrative(analysis, options, execution),
+    structured,
+  };
+};

package/src/tools/reconciliation/__tests__/adapter.causes.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import type { ReconciliationAnalysis } from '../types.js';
+import { buildReconciliationPayload } from '../../reconcileAdapter.js';
+import type { LegacyReconciliationResult } from '../executor.js';
+
+const baseAnalysis: ReconciliationAnalysis = {
+  success: true,
+  phase: 'analysis',
+  summary: {
+    statement_date_range: '2025-10-01 to 2025-10-31',
+    bank_transactions_count: 1,
+    ynab_transactions_count: 1,
+    auto_matched: 0,
+    suggested_matches: 0,
+    unmatched_bank: 0,
+    unmatched_ynab: 0,
+    current_cleared_balance: -899.02,
+    target_statement_balance: -921.24,
+    discrepancy: 22.22,
+    discrepancy_explanation: 'Need to investigate discrepancy',
+  },
+  auto_matches: [],
+  suggested_matches: [],
+  unmatched_bank: [],
+  unmatched_ynab: [],
+  balance_info: {
+    current_cleared: -899.02,
+    current_uncleared: 0,
+    current_total: -899.02,
+    target_statement: -921.24,
+    discrepancy: 22.22,
+    on_track: false,
+  },
+  next_steps: [],
+  insights: [],
+};
+
+const execution: LegacyReconciliationResult = {
+  summary: {
+    bank_transactions_count: 1,
+    ynab_transactions_count: 1,
+    matches_found: 0,
+    missing_in_ynab: 0,
+    missing_in_bank: 0,
+    transactions_created: 0,
+    transactions_updated: 0,
+    dates_adjusted: 0,
+    dry_run: false,
+  },
+  account_balance: {
+    before: { balance: -899020, cleared_balance: -899020, uncleared_balance: 0 },
+    after: { balance: -921240, cleared_balance: -921240, uncleared_balance: 0 },
+  },
+  actions_taken: [],
+  recommendations: [],
+  balance_reconciliation: {
+    status: 'DISCREPANCY_FOUND',
+    precision_calculations: {
+      bank_statement_balance_milliunits: -921240,
+      ynab_calculated_balance_milliunits: -899020,
+      discrepancy_milliunits: -22220,
+      discrepancy_dollars: -22.22,
+    },
+    discrepancy_analysis: {
+      confidence_level: 0.8,
+      risk_assessment: 'MEDIUM',
+      likely_causes: [
+        {
+          cause_type: 'BANK_FEE',
+          description: 'Monthly service fee detected',
+          confidence: 0.7,
+          amount_milliunits: -1500,
+          suggested_resolution: 'Record bank fee',
+          evidence: [],
+        },
+        {
+          cause_type: 'INTEREST',
+          description: 'Interest credit',
+          confidence: 0.5,
+          amount_milliunits: 500,
+          suggested_resolution: 'Record interest income',
+          evidence: [],
+        },
+      ],
+    },
+    final_verification: {
+      balance_matches_exactly: false,
+      all_transactions_accounted: false,
+      audit_trail_complete: false,
+      reconciliation_complete: false,
+    },
+  },
+};
+
+describe('buildReconciliationPayload discrepancy causes mapping', () => {
+  it('maps legacy causes to MoneyValue entries with CAD currency', () => {
+    const payload = buildReconciliationPayload(
+      baseAnalysis,
+      {
+        accountId: 'acct-123',
+        accountName: 'CAD Checking',
+        currencyCode: 'CAD',
+      },
+      execution,
+    );
+
+    const structured = payload.structured as Record<string, any>;
+    const discrepancyAnalysis = structured.execution?.balance_reconciliation?.discrepancy_analysis;
+    expect(discrepancyAnalysis).toBeDefined();
+    expect(discrepancyAnalysis.likely_causes).toHaveLength(2);
+
+    for (const cause of discrepancyAnalysis.likely_causes as Record<string, any>[]) {
+      expect(cause.amount).toMatchObject({ currency: 'CAD' });
+      expect(typeof cause.suggested_action).toBe('string');
+    }
+    const [bankFee, interest] = discrepancyAnalysis.likely_causes;
+    expect(bankFee.type).toBe('bank_fee');
+    expect(interest.type).toBe('interest');
+    expect(bankFee.suggested_action).toBe('Record bank fee');
+    expect(interest.suggested_action).toBe('Record interest income');
+  });
+});

package/src/tools/reconciliation/__tests__/adapter.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildReconciliationPayload,
+  type LegacyReconciliationResult,
+} from '../../reconcileAdapter.js';
+import type { ReconciliationAnalysis } from '../types.js';
+
+const makeMoney = (value: number, currency = 'USD') => ({
+  value_milliunits: Math.round(value * 1000),
+  value,
+  value_display: value < 0 ? `-$${Math.abs(value).toFixed(2)}` : `$${value.toFixed(2)}`,
+  currency,
+  direction: (value === 0 ? 'balanced' : value > 0 ? 'credit' : 'debit') as
+    | 'balanced'
+    | 'credit'
+    | 'debit',
+});
+
+const buildAnalysis = (): ReconciliationAnalysis => ({
+  success: true,
+  phase: 'analysis',
+  summary: {
+    statement_date_range: '2025-10-01 to 2025-10-31',
+    bank_transactions_count: 3,
+    ynab_transactions_count: 4,
+    auto_matched: 2,
+    suggested_matches: 1,
+    unmatched_bank: 1,
+    unmatched_ynab: 1,
+    current_cleared_balance: makeMoney(-899.02),
+    target_statement_balance: makeMoney(-921.24),
+    discrepancy: makeMoney(22.22),
+    discrepancy_explanation: 'Need to add 1 missing transaction',
+  },
+  auto_matches: [
+    {
+      bank_transaction: {
+        id: 'bank-1',
+        date: '2025-10-15',
+        amount: -45.23,
+        payee: 'Shell Gas',
+        original_csv_row: 2,
+      },
+      ynab_transaction: {
+        id: 'ynab-1',
+        date: '2025-10-14',
+        amount: -45230,
+        payee_name: 'Shell',
+        category_name: 'Auto',
+        cleared: 'uncleared',
+        approved: true,
+      },
+      candidates: [],
+      confidence: 'high',
+      confidence_score: 97,
+      match_reason: 'exact_amount_and_date',
+      top_confidence: 97,
+      action_hint: 'mark_cleared',
+    },
+  ],
+  suggested_matches: [
+    {
+      bank_transaction: {
+        id: 'bank-2',
+        date: '2025-10-20',
+        amount: -60,
+        payee: 'Amazon',
+        original_csv_row: 5,
+      },
+      candidates: [
+        {
+          ynab_transaction: {
+            id: 'ynab-2',
+            date: '2025-10-19',
+            amount: -60000,
+            payee_name: 'Amazon Online',
+            category_name: 'Shopping',
+            cleared: 'uncleared',
+            approved: true,
+          },
+          confidence: 75,
+          match_reason: 'amount_and_date_fuzzy_payee',
+          explanation: 'Amount matches, date off by 1 day',
+        },
+      ],
+      confidence: 'medium',
+      confidence_score: 75,
+      match_reason: 'amount_and_date_fuzzy_payee',
+      top_confidence: 75,
+    },
+  ],
+  unmatched_bank: [
+    {
+      id: 'bank-3',
+      date: '2025-10-25',
+      amount: 22.22,
+      payee: 'EvoCarShare',
+      original_csv_row: 7,
+    },
+  ],
+  unmatched_ynab: [
+    {
+      id: 'ynab-3',
+      date: '2025-10-26',
+      amount: -15000,
+      payee_name: 'Coffee Shop',
+      category_name: 'Dining',
+      cleared: 'cleared',
+      approved: true,
+    },
+  ],
+  balance_info: {
+    current_cleared: makeMoney(-899.02),
+    current_uncleared: makeMoney(-45.23),
+    current_total: makeMoney(-944.25),
+    target_statement: makeMoney(-921.24),
+    discrepancy: makeMoney(22.22),
+    on_track: false,
+  },
+  next_steps: ['Review 2 auto-matched transactions', 'Add missing bank transaction'],
+  insights: [
+    {
+      id: 'repeat-22.22',
+      type: 'repeat_amount',
+      severity: 'warning',
+      title: '1 unmatched transaction at $22.22',
+      description: 'Matches statement discrepancy',
+      evidence: { csv_rows: [7] },
+    },
+  ],
+});
+
+describe('buildReconciliationPayload', () => {
+  it('returns human narrative and structured payload with MoneyValue fields', () => {
+    const payload = buildReconciliationPayload(buildAnalysis(), {
+      accountName: 'K TD FCT VISA',
+      accountId: 'account-123',
+      currencyCode: 'USD',
+    });
+
+    expect(payload.human).toContain('K TD FCT VISA Reconciliation Report');
+    expect(payload.human.toUpperCase()).toContain('DISCREPANCY');
+
+    const structured = payload.structured as Record<string, any>;
+    expect(structured.version).toBe('2.0');
+    expect(structured.summary.current_cleared_balance.value_display).toBe('-$899.02');
+    expect(structured.summary.current_cleared_balance.currency).toBe('USD');
+    expect(structured.balance.discrepancy.direction).toBeDefined();
+    expect(structured.matches.auto[0].bank_transaction.amount_money.value_milliunits).toBe(-45230);
+  });
+
+  it('includes execution data when provided', () => {
+    const execution: LegacyReconciliationResult = {
+      summary: {
+        bank_transactions_count: 3,
+        ynab_transactions_count: 4,
+        matches_found: 2,
+        missing_in_ynab: 1,
+        missing_in_bank: 1,
+        transactions_created: 1,
+        transactions_updated: 1,
+        dates_adjusted: 0,
+        dry_run: false,
+      },
+      account_balance: {
+        before: { balance: -899020, cleared_balance: -899020, uncleared_balance: 0 },
+        after: { balance: -921240, cleared_balance: -921240, uncleared_balance: 0 },
+      },
+      actions_taken: [
+        {
+          type: 'create_transaction',
+          transaction: { id: 'txn-1' },
+          reason: 'Created missing transaction',
+        },
+      ],
+      matches: [],
+      missing_in_ynab: [],
+      missing_in_bank: [],
+      recommendations: ['Review EvoCarShare discrepancy'],
+      balance_reconciliation: {
+        status: 'DISCREPANCY_FOUND',
+        precision_calculations: {
+          bank_statement_balance_milliunits: -921240,
+          ynab_calculated_balance_milliunits: -899020,
+          discrepancy_milliunits: -22220,
+          discrepancy_dollars: -22.22,
+        },
+        discrepancy_analysis: {
+          confidence_level: 0.95,
+          likely_causes: [
+            {
+              cause_type: 'MISSING_TRANSACTION',
+              description: 'EvoCarShare transaction missing in YNAB',
+              confidence: 0.95,
+              amount_milliunits: 22220,
+              suggested_resolution: 'Create transaction and mark cleared',
+              evidence: [],
+            },
+          ],
+          risk_assessment: 'LOW',
+        },
+        final_verification: {
+          balance_matches_exactly: false,
+          all_transactions_accounted: false,
+          audit_trail_complete: false,
+          reconciliation_complete: false,
+        },
+      },
+    };
+
+    const payload = buildReconciliationPayload(
+      buildAnalysis(),
+      {
+        accountName: 'K TD FCT VISA',
+        accountId: 'account-123',
+        currencyCode: 'CAD',
+      },
+      execution,
+    );
+
+    const structured = payload.structured as Record<string, any>;
+    expect(structured.execution).toBeDefined();
+    expect(structured.execution.summary.transactions_created).toBe(1);
+    expect(structured.execution.account_balance.after.cleared_balance.value_milliunits).toBe(
+      -921240,
+    );
+    expect(structured.execution.account_balance.after.cleared_balance.currency).toBe('CAD');
+    expect(
+      structured.execution.balance_reconciliation?.precision_calculations?.discrepancy
+        .value_display,
+    ).toBe('-CA$22.22');
+    expect(payload.human).toContain('Changes applied to YNAB');
+  });
+});