@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/reconciliation/recommendationEngine.js

@@ -0,0 +1,273 @@
+import { randomUUID } from 'crypto';
+import { toMoneyValueFromDecimal, fromMilli, toMilli } from '../../utils/money.js';
+const RECOMMENDATION_VERSION = '1.0';
+const CONFIDENCE = {
+    CREATE_EXACT_MATCH: 0.95,
+    NEAR_MATCH_REVIEW: 0.7,
+    REPEAT_AMOUNT: 0.75,
+    ANOMALY_REVIEW: 0.5,
+    UNMATCHED_BANK: 0.8,
+    UPDATE_CLEARED: 0.6,
+};
+const PRIORITY_ORDER = { high: 3, medium: 2, low: 1 };
+export function generateRecommendations(context) {
+    const recommendations = [];
+    for (const insight of context.analysis.insights) {
+        const recs = processInsight(insight, context);
+        recommendations.push(...recs);
+    }
+    const unmatchedRecs = processUnmatchedTransactions(context);
+    recommendations.push(...unmatchedRecs);
+    return sortRecommendations(recommendations);
+}
+function processInsight(insight, context) {
+    switch (insight.type) {
+        case 'near_match':
+            return [createNearMatchRecommendation(insight, context)];
+        case 'repeat_amount':
+            return createRepeatAmountRecommendations(insight, context);
+        case 'anomaly':
+            return [createManualReviewRecommendation(insight, context)];
+        default:
+            return [];
+    }
+}
+function createSuggestedMatchRecommendation(match, context) {
+    const bankTxn = match.bank_transaction;
+    if (match.ynab_transaction && match.confidence !== 'none') {
+        return {
+            id: randomUUID(),
+            action_type: 'review_duplicate',
+            priority: 'high',
+            confidence: Math.max(0, Math.min(1, match.confidence_score / 100)),
+            message: `Review possible match: ${bankTxn.payee}`,
+            reason: match.match_reason,
+            estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
+            account_id: context.account_id,
+            metadata: {
+                version: RECOMMENDATION_VERSION,
+                created_at: new Date().toISOString(),
+            },
+            parameters: {
+                candidate_ids: [match.ynab_transaction.id],
+                bank_transaction: bankTxn,
+                suggested_match_id: match.ynab_transaction.id,
+            },
+        };
+    }
+    const isCombinationMatch = match.match_reason === 'combination_match' || (match.candidates?.length ?? 0) > 1;
+    if (isCombinationMatch) {
+        return createCombinationReviewRecommendation(match, context);
+    }
+    const parameters = {
+        account_id: context.account_id,
+        date: bankTxn.date,
+        amount: toMilli(bankTxn.amount),
+        payee_name: bankTxn.payee,
+        cleared: 'cleared',
+        approved: true,
+    };
+    if (bankTxn.memo) {
+        parameters.memo = bankTxn.memo;
+    }
+    return {
+        id: randomUUID(),
+        action_type: 'create_transaction',
+        priority: 'high',
+        confidence: CONFIDENCE.CREATE_EXACT_MATCH,
+        message: `Create transaction for ${bankTxn.payee}`,
+        reason: `This transaction exactly matches your discrepancy`,
+        estimated_impact: toMoneyValueFromDecimal(bankTxn.amount, context.analysis.balance_info.current_cleared.currency),
+        account_id: context.account_id,
+        metadata: {
+            version: RECOMMENDATION_VERSION,
+            created_at: new Date().toISOString(),
+        },
+        parameters,
+    };
+}
+function createCombinationReviewRecommendation(match, context) {
+    const bankTxn = match.bank_transaction;
+    const candidateIds = match.candidates?.map((candidate) => candidate.ynab_transaction.id) ?? [];
+    const candidateTotalAmount = match.candidates?.reduce((sum, candidate) => {
+        const amount = candidate.ynab_transaction.amount;
+        if (!Number.isFinite(amount)) {
+            console.warn(`Invalid candidate amount: ${amount}`);
+            return sum;
+        }
+        return sum + fromMilli(amount);
+    }, 0) ?? 0;
+    return {
+        id: randomUUID(),
+        action_type: 'manual_review',
+        priority: 'medium',
+        confidence: CONFIDENCE.NEAR_MATCH_REVIEW,
+        message: `Review combination match: ${bankTxn.payee}`,
+        reason: match.recommendation ??
+            'Multiple YNAB transactions appear to match this bank transaction. Review before creating anything new.',
+        estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
+        account_id: context.account_id,
+        metadata: {
+            version: RECOMMENDATION_VERSION,
+            created_at: new Date().toISOString(),
+            bank_transaction_amount: toMoneyValueFromDecimal(bankTxn.amount, context.analysis.balance_info.current_cleared.currency),
+            candidate_total_amount: toMoneyValueFromDecimal(candidateTotalAmount, context.analysis.balance_info.current_cleared.currency),
+            candidate_count: match.candidates?.length ?? 0,
+        },
+        parameters: {
+            issue_type: 'complex_match',
+            related_transactions: [
+                {
+                    source: 'bank',
+                    id: bankTxn.id,
+                    description: bankTxn.payee,
+                },
+                ...candidateIds.map((id) => ({
+                    source: 'ynab',
+                    id,
+                    description: match.candidates?.find((c) => c.ynab_transaction.id === id)?.ynab_transaction
+                        .payee_name ?? 'Unknown',
+                })),
+            ],
+        },
+    };
+}
+function createNearMatchRecommendation(insight, context) {
+    return {
+        id: randomUUID(),
+        action_type: 'manual_review',
+        priority: 'medium',
+        confidence: CONFIDENCE.NEAR_MATCH_REVIEW,
+        message: `Review: ${insight.title}`,
+        reason: insight.description,
+        estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
+        account_id: context.account_id,
+        source_insight_id: insight.id,
+        metadata: {
+            version: RECOMMENDATION_VERSION,
+            created_at: new Date().toISOString(),
+            current_discrepancy: context.analysis.balance_info.discrepancy,
+            insight_severity: insight.severity,
+        },
+        parameters: {
+            issue_type: 'complex_match',
+        },
+    };
+}
+function createRepeatAmountRecommendations(insight, context) {
+    return [
+        {
+            id: randomUUID(),
+            action_type: 'manual_review',
+            priority: 'medium',
+            confidence: CONFIDENCE.REPEAT_AMOUNT,
+            message: `Review recurring pattern: ${insight.title}`,
+            reason: insight.description,
+            estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
+            account_id: context.account_id,
+            source_insight_id: insight.id,
+            metadata: {
+                version: RECOMMENDATION_VERSION,
+                created_at: new Date().toISOString(),
+                current_discrepancy: context.analysis.balance_info.discrepancy,
+                insight_severity: insight.severity,
+            },
+            parameters: {
+                issue_type: 'complex_match',
+            },
+        },
+    ];
+}
+function createManualReviewRecommendation(insight, context) {
+    return {
+        id: randomUUID(),
+        action_type: 'manual_review',
+        priority: 'low',
+        confidence: CONFIDENCE.ANOMALY_REVIEW,
+        message: `Review: ${insight.title}`,
+        reason: insight.description,
+        estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
+        account_id: context.account_id,
+        source_insight_id: insight.id,
+        metadata: {
+            version: RECOMMENDATION_VERSION,
+            created_at: new Date().toISOString(),
+            current_discrepancy: context.analysis.balance_info.discrepancy,
+            insight_severity: insight.severity,
+        },
+        parameters: {
+            issue_type: insight.severity === 'critical' ? 'large_discrepancy' : 'unknown',
+        },
+    };
+}
+function processUnmatchedTransactions(context) {
+    const recommendations = [];
+    for (const bankTxn of context.analysis.unmatched_bank) {
+        recommendations.push(createUnmatchedBankRecommendation(bankTxn, context));
+    }
+    for (const match of context.analysis.suggested_matches) {
+        recommendations.push(createSuggestedMatchRecommendation(match, context));
+    }
+    for (const ynabTxn of context.analysis.unmatched_ynab) {
+        if (ynabTxn.cleared === 'uncleared') {
+            recommendations.push(createUpdateClearedRecommendation(ynabTxn, context));
+        }
+    }
+    return recommendations;
+}
+function createUnmatchedBankRecommendation(txn, context) {
+    const parameters = {
+        account_id: context.account_id,
+        date: txn.date,
+        amount: toMilli(txn.amount),
+        payee_name: txn.payee,
+        cleared: 'cleared',
+        approved: true,
+    };
+    if (txn.memo) {
+        parameters.memo = txn.memo;
+    }
+    return {
+        id: randomUUID(),
+        action_type: 'create_transaction',
+        priority: 'medium',
+        confidence: CONFIDENCE.UNMATCHED_BANK,
+        message: `Create missing transaction: ${txn.payee}`,
+        reason: 'Transaction appears on bank statement but not in YNAB',
+        estimated_impact: toMoneyValueFromDecimal(txn.amount, context.analysis.balance_info.current_cleared.currency),
+        account_id: context.account_id,
+        metadata: {
+            version: RECOMMENDATION_VERSION,
+            created_at: new Date().toISOString(),
+        },
+        parameters,
+    };
+}
+function createUpdateClearedRecommendation(txn, context) {
+    return {
+        id: randomUUID(),
+        action_type: 'update_cleared',
+        priority: 'low',
+        confidence: CONFIDENCE.UPDATE_CLEARED,
+        message: `Mark transaction as cleared: ${txn.payee_name || 'Unknown'}`,
+        reason: 'Transaction exists in YNAB but not yet cleared',
+        estimated_impact: toMoneyValueFromDecimal(0, context.analysis.balance_info.current_cleared.currency),
+        account_id: context.account_id,
+        metadata: {
+            version: RECOMMENDATION_VERSION,
+            created_at: new Date().toISOString(),
+        },
+        parameters: {
+            transaction_id: txn.id,
+            cleared: 'cleared',
+        },
+    };
+}
+function sortRecommendations(recommendations) {
+    return recommendations.sort((a, b) => {
+        const priorityDiff = PRIORITY_ORDER[b.priority] - PRIORITY_ORDER[a.priority];
+        if (priorityDiff !== 0)
+            return priorityDiff;
+        return b.confidence - a.confidence;
+    });
+}

package/dist/tools/reconciliation/reportFormatter.d.ts

@@ -0,0 +1,13 @@
+import type { ReconciliationAnalysis, BankTransaction, YNABTransaction, BalanceInfo } from './types.js';
+import type { LegacyReconciliationResult } from './executor.js';
+export interface ReportFormatterOptions {
+    accountName?: string | undefined;
+    accountId?: string | undefined;
+    currencyCode?: string | undefined;
+    includeDetailedMatches?: boolean | undefined;
+    maxUnmatchedToShow?: number | undefined;
+    maxInsightsToShow?: number | undefined;
+}
+export declare function formatHumanReadableReport(analysis: ReconciliationAnalysis, options?: ReportFormatterOptions, execution?: LegacyReconciliationResult): string;
+export declare function formatBalanceInfo(balance: BalanceInfo): string;
+export declare function formatTransactionList(transactions: BankTransaction[] | YNABTransaction[], maxItems?: number): string;

package/dist/tools/reconciliation/reportFormatter.js

@@ -0,0 +1,214 @@
+export function formatHumanReadableReport(analysis, options = {}, execution) {
+    const accountLabel = options.accountName ?? 'Account';
+    const sections = [];
+    sections.push(formatHeader(accountLabel, analysis));
+    sections.push(formatBalanceSection(analysis.balance_info, analysis.summary));
+    sections.push(formatTransactionAnalysisSection(analysis, options));
+    if (analysis.insights.length > 0) {
+        sections.push(formatInsightsSection(analysis.insights, options.maxInsightsToShow));
+    }
+    if (execution) {
+        sections.push(formatExecutionSection(execution));
+    }
+    sections.push(formatRecommendationsSection(analysis, execution));
+    return sections.join('\n\n');
+}
+function formatHeader(accountName, analysis) {
+    const lines = [];
+    lines.push(`📊 ${accountName} Reconciliation Report`);
+    lines.push('═'.repeat(60));
+    lines.push(`Statement Period: ${analysis.summary.statement_date_range}`);
+    return lines.join('\n');
+}
+function formatBalanceSection(balanceInfo, summary) {
+    const lines = [];
+    lines.push('BALANCE CHECK');
+    lines.push('═'.repeat(60));
+    lines.push(`✓ YNAB Cleared Balance:  ${summary.current_cleared_balance.value_display}`);
+    lines.push(`✓ Statement Balance:     ${summary.target_statement_balance.value_display}`);
+    lines.push('');
+    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');
+}
+function formatTransactionAnalysisSection(analysis, options) {
+    const lines = [];
+    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}`);
+    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`);
+        }
+    }
+    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');
+}
+function formatBankTransactionLine(txn) {
+    const amountStr = formatAmount(txn.amount);
+    return `   ${txn.date} - ${txn.payee.substring(0, 40).padEnd(40)} ${amountStr}`;
+}
+function formatSuggestedMatchLine(match) {
+    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)`;
+}
+function formatAmount(amount) {
+    const sign = amount >= 0 ? '+' : '-';
+    const absAmount = Math.abs(amount);
+    return `${sign}$${absAmount.toFixed(2)}`.padStart(10);
+}
+function formatInsightsSection(insights, maxToShow = 3) {
+    const lines = [];
+    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}`);
+        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();
+}
+function getSeverityIcon(severity) {
+    switch (severity) {
+        case 'critical':
+            return '🚨';
+        case 'warning':
+            return '⚠️';
+        case 'info':
+            return 'ℹ️';
+        default:
+            return '•';
+    }
+}
+function formatEvidenceSummary(evidence) {
+    if ('transaction_count' in evidence) {
+        return `${evidence['transaction_count']} transactions`;
+    }
+    if ('amount' in evidence && typeof evidence['amount'] === 'object') {
+        const amount = evidence['amount'];
+        return amount.value_display;
+    }
+    if ('transaction_ids' in evidence && Array.isArray(evidence['transaction_ids'])) {
+        return `${evidence['transaction_ids'].length} transactions involved`;
+    }
+    return null;
+}
+function formatExecutionSection(execution) {
+    const lines = [];
+    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}`);
+    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');
+}
+function formatRecommendationsSection(analysis, execution) {
+    const lines = [];
+    lines.push('RECOMMENDED ACTIONS');
+    lines.push('═'.repeat(60));
+    if (execution && !execution.summary.dry_run) {
+        lines.push('All recommended actions have been applied.');
+        return lines.join('\n');
+    }
+    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');
+}
+export function formatBalanceInfo(balance) {
+    const lines = [];
+    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');
+}
+export function formatTransactionList(transactions, maxItems = 10) {
+    const lines = [];
+    const toShow = transactions.slice(0, maxItems);
+    for (const txn of toShow) {
+        if ('payee' in txn) {
+            lines.push(formatBankTransactionLine(txn));
+        }
+        else {
+            const amount = txn.amount / 1000;
+            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/dist/tools/reconciliation/types.d.ts

@@ -0,0 +1,172 @@
+import type { MoneyValue } from '../../utils/money.js';
+export type MatchConfidence = 'high' | 'medium' | 'low' | 'none';
+export interface BankTransaction {
+    id: string;
+    date: string;
+    amount: number;
+    payee: string;
+    memo?: string;
+    original_csv_row: number;
+}
+export interface YNABTransaction {
+    id: string;
+    date: string;
+    amount: number;
+    payee_name: string | null;
+    category_name: string | null;
+    cleared: 'cleared' | 'uncleared' | 'reconciled';
+    approved: boolean;
+    memo?: string | null;
+}
+export interface MatchCandidate {
+    ynab_transaction: YNABTransaction;
+    confidence: number;
+    match_reason: string;
+    explanation: string;
+}
+export interface TransactionMatch {
+    bank_transaction: BankTransaction;
+    ynab_transaction?: YNABTransaction;
+    candidates?: MatchCandidate[];
+    confidence: MatchConfidence;
+    confidence_score: number;
+    match_reason: string;
+    top_confidence?: number;
+    action_hint?: string;
+    recommendation?: string;
+}
+export interface BalanceInfo {
+    current_cleared: MoneyValue;
+    current_uncleared: MoneyValue;
+    current_total: MoneyValue;
+    target_statement: MoneyValue;
+    discrepancy: MoneyValue;
+    on_track: boolean;
+}
+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;
+}
+export type InsightSeverity = 'info' | 'warning' | 'critical';
+export type InsightKind = 'repeat_amount' | 'near_match' | 'anomaly';
+export interface ReconciliationInsight {
+    id: string;
+    type: InsightKind;
+    severity: InsightSeverity;
+    title: string;
+    description: string;
+    evidence?: Record<string, unknown>;
+}
+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[];
+}
+export type ReconciliationActionType = 'match' | 'add' | 'unclear' | 'delete' | 'ignore';
+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>;
+}
+export interface MatchingConfig {
+    dateToleranceDays: number;
+    amountToleranceCents: number;
+    descriptionSimilarityThreshold: number;
+    autoMatchThreshold: number;
+    suggestionThreshold: number;
+}
+export declare const DEFAULT_MATCHING_CONFIG: {
+    dateToleranceDays: number;
+    amountToleranceCents: number;
+    descriptionSimilarityThreshold: number;
+    autoMatchThreshold: number;
+    suggestionThreshold: number;
+};
+export interface ParsedCSVData {
+    transactions: BankTransaction[];
+    format_detected: string;
+    delimiter: string;
+    total_rows: number;
+    valid_rows: number;
+    errors: string[];
+}
+export type RecommendationPriority = 'high' | 'medium' | 'low';
+export interface BaseRecommendation {
+    id: string;
+    priority: RecommendationPriority;
+    confidence: number;
+    message: string;
+    reason: string;
+    estimated_impact: MoneyValue;
+    account_id: string;
+    source_insight_id?: string;
+    metadata?: Record<string, unknown>;
+}
+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;
+    };
+}
+export interface UpdateClearedRecommendation extends BaseRecommendation {
+    action_type: 'update_cleared';
+    parameters: {
+        transaction_id: string;
+        cleared: 'cleared' | 'uncleared' | 'reconciled';
+    };
+}
+export interface ReviewDuplicateRecommendation extends BaseRecommendation {
+    action_type: 'review_duplicate';
+    parameters: {
+        candidate_ids: string[];
+        bank_transaction?: BankTransaction;
+        suggested_match_id?: string;
+    };
+}
+export interface RelatedTransaction {
+    source: 'bank' | 'ynab';
+    id: string;
+    description: string;
+}
+export interface ManualReviewRecommendation extends BaseRecommendation {
+    action_type: 'manual_review';
+    parameters: {
+        issue_type: 'complex_match' | 'large_discrepancy' | 'unknown';
+        related_transactions?: RelatedTransaction[];
+    };
+}
+export type ActionableRecommendation = CreateTransactionRecommendation | UpdateClearedRecommendation | ReviewDuplicateRecommendation | ManualReviewRecommendation;
+export interface RecommendationContext {
+    account_id: string;
+    budget_id: string;
+    analysis: ReconciliationAnalysis;
+    matching_config: MatchingConfig;
+}

package/dist/tools/reconciliation/types.js

@@ -0,0 +1,7 @@
+export const DEFAULT_MATCHING_CONFIG = {
+    dateToleranceDays: 2,
+    amountToleranceCents: 1,
+    descriptionSimilarityThreshold: 0.8,
+    autoMatchThreshold: 90,
+    suggestionThreshold: 60,
+};