@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/reconciliation/executor.js

@@ -0,0 +1,611 @@
+import { createHash } from 'crypto';
+import { toMilli, toMoneyValue, toMoneyValueFromDecimal, addMilli } from '../../utils/money.js';
+import { generateCorrelationKey, correlateResults, toCorrelationPayload, } from '../transactionTools.js';
+const MONEY_EPSILON_MILLI = 100;
+const DEFAULT_TOLERANCE_CENTS = 1;
+const CENTS_TO_MILLI = 10;
+const MAX_BULK_CREATE_CHUNK = 100;
+function chunkArray(array, size) {
+    if (size <= 0) {
+        throw new Error('chunk size must be positive');
+    }
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}
+function generateBulkImportId(accountId, date, amountMilli, payee) {
+    const normalizedPayee = (payee ?? '').trim().toLowerCase();
+    const raw = `${accountId}|${date}|${amountMilli}|${normalizedPayee}`;
+    const digest = createHash('sha256').update(raw).digest('hex').slice(0, 24);
+    return `YNAB:bulk:${digest}`;
+}
+export async function executeReconciliation(options) {
+    const { analysis, params, ynabAPI, budgetId, accountId, initialAccount, currencyCode } = options;
+    const actions_taken = [];
+    const summary = {
+        bank_transactions_count: analysis.summary.bank_transactions_count,
+        ynab_transactions_count: analysis.summary.ynab_transactions_count,
+        matches_found: analysis.auto_matches.length,
+        missing_in_ynab: analysis.summary.unmatched_bank,
+        missing_in_bank: analysis.summary.unmatched_ynab,
+        transactions_created: 0,
+        transactions_updated: 0,
+        dates_adjusted: 0,
+        dry_run: params.dry_run,
+    };
+    let afterAccount = { ...initialAccount };
+    let accountSnapshotDirty = false;
+    const statementTargetMilli = resolveStatementBalanceMilli(analysis.balance_info, params.statement_balance);
+    let clearedDeltaMilli = addMilli(initialAccount.cleared_balance ?? 0, -statementTargetMilli);
+    const balanceToleranceMilli = Math.max(0, params.amount_tolerance_cents ?? DEFAULT_TOLERANCE_CENTS) * CENTS_TO_MILLI;
+    let balanceAligned = false;
+    const applyClearedDelta = (delta) => {
+        if (delta === 0)
+            return;
+        clearedDeltaMilli = addMilli(clearedDeltaMilli, delta);
+    };
+    const recordAlignmentIfNeeded = (trigger, { log = true } = {}) => {
+        if (balanceAligned) {
+            return true;
+        }
+        if (Math.abs(clearedDeltaMilli) <= balanceToleranceMilli) {
+            balanceAligned = true;
+            if (log) {
+                const deltaDisplay = toMoneyValue(clearedDeltaMilli, currencyCode).value_display;
+                const toleranceDisplay = toMoneyValue(balanceToleranceMilli, currencyCode).value_display;
+                actions_taken.push({
+                    type: 'balance_checkpoint',
+                    transaction: null,
+                    reason: `Cleared delta ${deltaDisplay} within ±${toleranceDisplay} after ${trigger} - halting newest-to-oldest pass`,
+                });
+            }
+            return true;
+        }
+        return false;
+    };
+    recordAlignmentIfNeeded('initial balance check', { log: false });
+    const orderedUnmatchedBank = params.auto_create_transactions
+        ? sortByDateDescending(analysis.unmatched_bank)
+        : [];
+    const orderedAutoMatches = sortMatchesByBankDateDescending(analysis.auto_matches);
+    const orderedUnmatchedYNAB = sortByDateDescending(analysis.unmatched_ynab);
+    let bulkOperationDetails;
+    if (params.auto_create_transactions && !balanceAligned) {
+        const buildPreparedEntry = (bankTxn) => {
+            const amountMilli = toMilli(bankTxn.amount);
+            const saveTransaction = {
+                account_id: accountId,
+                amount: amountMilli,
+                date: bankTxn.date,
+                payee_name: bankTxn.payee ?? undefined,
+                memo: bankTxn.memo ?? 'Auto-reconciled from bank statement',
+                cleared: 'cleared',
+                approved: true,
+                import_id: generateBulkImportId(accountId, bankTxn.date, amountMilli, bankTxn.payee),
+            };
+            const correlationKey = generateCorrelationKey(toCorrelationPayload(saveTransaction));
+            return {
+                bankTransaction: bankTxn,
+                saveTransaction,
+                amountMilli,
+                correlationKey,
+            };
+        };
+        const recordCreateAction = (args) => {
+            const { entry, createdTxn, chunkIndex, prefix } = args;
+            summary.transactions_created += 1;
+            const action = {
+                type: 'create_transaction',
+                transaction: createdTxn,
+                reason: `${prefix ?? 'Created missing transaction'}: ${entry.bankTransaction.payee ?? 'Unknown'} (${formatDisplay(entry.bankTransaction.amount, currencyCode)})`,
+                correlation_key: entry.correlationKey,
+            };
+            if (chunkIndex !== undefined) {
+                action.bulk_chunk_index = chunkIndex;
+            }
+            actions_taken.push(action);
+        };
+        const processSequentialEntries = async (entries, options = {}) => {
+            let sequentialAttempts = 0;
+            for (const entry of entries) {
+                if (balanceAligned)
+                    break;
+                if (options.fallbackError) {
+                    sequentialAttempts += 1;
+                }
+                try {
+                    const response = await ynabAPI.transactions.createTransaction(budgetId, {
+                        transaction: entry.saveTransaction,
+                    });
+                    const createdTransaction = response.data.transaction ?? null;
+                    const recordArgs = {
+                        entry,
+                        createdTxn: createdTransaction,
+                        prefix: options.fallbackError
+                            ? 'Created missing transaction after bulk fallback'
+                            : 'Created missing transaction',
+                    };
+                    if (options.chunkIndex !== undefined) {
+                        recordArgs.chunkIndex = options.chunkIndex;
+                    }
+                    recordCreateAction(recordArgs);
+                    accountSnapshotDirty = true;
+                    applyClearedDelta(entry.amountMilli);
+                    const trigger = options.chunkIndex
+                        ? `creating ${entry.bankTransaction.payee ?? 'missing transaction'} (chunk ${options.chunkIndex})`
+                        : `creating ${entry.bankTransaction.payee ?? 'missing transaction'}`;
+                    recordAlignmentIfNeeded(trigger);
+                }
+                catch (error) {
+                    if (bulkOperationDetails) {
+                        bulkOperationDetails.transaction_failures += 1;
+                    }
+                    const failureReason = error instanceof Error ? error.message : 'Unknown error occurred';
+                    const failureAction = {
+                        type: 'create_transaction_failed',
+                        transaction: entry.saveTransaction,
+                        reason: options.fallbackError
+                            ? `Bulk fallback failed for ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason})`
+                            : `Failed to create transaction ${entry.bankTransaction.payee ?? 'Unknown'} (${failureReason})`,
+                        correlation_key: entry.correlationKey,
+                    };
+                    if (options.chunkIndex !== undefined) {
+                        failureAction.bulk_chunk_index = options.chunkIndex;
+                    }
+                    actions_taken.push(failureAction);
+                }
+            }
+            if (bulkOperationDetails && options.fallbackError && sequentialAttempts > 0) {
+                bulkOperationDetails.sequential_attempts =
+                    (bulkOperationDetails.sequential_attempts ?? 0) + sequentialAttempts;
+            }
+        };
+        const processBulkChunk = async (chunk, chunkIndex) => {
+            const bulkDetails = bulkOperationDetails;
+            const payload = chunk.map((entry) => entry.saveTransaction);
+            const response = await ynabAPI.transactions.createTransactions(budgetId, {
+                transactions: payload,
+            });
+            const responseData = response.data;
+            const duplicateImportIds = new Set(responseData.duplicate_import_ids ?? []);
+            const correlationRequests = chunk.map((entry) => toCorrelationPayload(entry.saveTransaction));
+            const correlated = correlateResults(correlationRequests, responseData, duplicateImportIds);
+            const transactionMap = new Map();
+            for (const transaction of responseData.transactions ?? []) {
+                if (transaction.id) {
+                    transactionMap.set(transaction.id, transaction);
+                }
+            }
+            for (const result of correlated) {
+                const entry = chunk[result.request_index];
+                if (!entry)
+                    continue;
+                if (result.status === 'created') {
+                    const createdTransaction = result.transaction_id
+                        ? (transactionMap.get(result.transaction_id) ?? null)
+                        : null;
+                    recordCreateAction({
+                        entry,
+                        createdTxn: createdTransaction,
+                        chunkIndex,
+                        prefix: 'Created missing transaction via bulk',
+                    });
+                    accountSnapshotDirty = true;
+                    applyClearedDelta(entry.amountMilli);
+                    recordAlignmentIfNeeded(`creating ${entry.bankTransaction.payee ?? 'missing transaction'} via bulk chunk ${chunkIndex}`);
+                }
+                else if (result.status === 'duplicate') {
+                    bulkDetails.duplicates_detected += 1;
+                    actions_taken.push({
+                        type: 'create_transaction_duplicate',
+                        transaction: {
+                            transaction_id: result.transaction_id ?? null,
+                            import_id: entry.saveTransaction.import_id,
+                        },
+                        reason: `Duplicate import detected for ${entry.bankTransaction.payee ?? 'Unknown'} (import_id ${entry.saveTransaction.import_id})`,
+                        bulk_chunk_index: chunkIndex,
+                        correlation_key: result.correlation_key,
+                        duplicate: true,
+                    });
+                }
+                else {
+                    bulkDetails.transaction_failures += 1;
+                    actions_taken.push({
+                        type: 'create_transaction_failed',
+                        transaction: entry.saveTransaction,
+                        reason: result.error ?? `Bulk create failed for ${entry.bankTransaction.payee ?? 'Unknown'}`,
+                        bulk_chunk_index: chunkIndex,
+                        correlation_key: result.correlation_key,
+                    });
+                }
+            }
+        };
+        if (params.dry_run) {
+            for (const bankTxn of orderedUnmatchedBank) {
+                if (balanceAligned)
+                    break;
+                const entry = buildPreparedEntry(bankTxn);
+                summary.transactions_created += 1;
+                actions_taken.push({
+                    type: 'create_transaction',
+                    transaction: entry.saveTransaction,
+                    reason: `Would create missing transaction: ${bankTxn.payee ?? 'Unknown'} (${formatDisplay(bankTxn.amount, currencyCode)})`,
+                    correlation_key: entry.correlationKey,
+                });
+                applyClearedDelta(entry.amountMilli);
+                recordAlignmentIfNeeded(`creating ${bankTxn.payee ?? 'missing transaction'}`);
+            }
+        }
+        else if (orderedUnmatchedBank.length >= 2) {
+            bulkOperationDetails = {
+                chunks_processed: 0,
+                bulk_successes: 0,
+                sequential_fallbacks: 0,
+                duplicates_detected: 0,
+                failed_transactions: 0,
+                bulk_chunk_failures: 0,
+                transaction_failures: 0,
+            };
+            let nextBankIndex = 0;
+            while (nextBankIndex < orderedUnmatchedBank.length && !balanceAligned) {
+                const batch = [];
+                let projectedDelta = clearedDeltaMilli;
+                while (nextBankIndex < orderedUnmatchedBank.length) {
+                    const bankTxn = orderedUnmatchedBank[nextBankIndex];
+                    if (!bankTxn) {
+                        nextBankIndex += 1;
+                        continue;
+                    }
+                    const entry = buildPreparedEntry(bankTxn);
+                    batch.push(entry);
+                    nextBankIndex += 1;
+                    projectedDelta = addMilli(projectedDelta, entry.amountMilli);
+                    if (Math.abs(projectedDelta) <= balanceToleranceMilli) {
+                        break;
+                    }
+                }
+                if (batch.length === 0) {
+                    break;
+                }
+                const chunks = chunkArray(batch, MAX_BULK_CREATE_CHUNK);
+                for (const chunk of chunks) {
+                    if (balanceAligned)
+                        break;
+                    bulkOperationDetails.chunks_processed += 1;
+                    const chunkIndex = bulkOperationDetails.chunks_processed;
+                    try {
+                        await processBulkChunk(chunk, chunkIndex);
+                        bulkOperationDetails.bulk_successes += 1;
+                    }
+                    catch (error) {
+                        bulkOperationDetails.sequential_fallbacks += 1;
+                        bulkOperationDetails.bulk_chunk_failures += 1;
+                        actions_taken.push({
+                            type: 'bulk_create_fallback',
+                            transaction: null,
+                            reason: `Bulk chunk #${chunkIndex} failed (${error instanceof Error ? error.message : 'unknown error'}) - falling back to sequential creation`,
+                            bulk_chunk_index: chunkIndex,
+                        });
+                        await processSequentialEntries(chunk, { chunkIndex, fallbackError: error });
+                    }
+                }
+            }
+        }
+        else {
+            const entries = orderedUnmatchedBank.map((bankTxn) => buildPreparedEntry(bankTxn));
+            await processSequentialEntries(entries);
+        }
+    }
+    if (!balanceAligned) {
+        const transactionsToUpdate = [];
+        for (const match of orderedAutoMatches) {
+            if (balanceAligned)
+                break;
+            const flags = computeUpdateFlags(match, params);
+            if (!flags.needsClearedUpdate && !flags.needsDateUpdate)
+                continue;
+            if (!match.ynab_transaction)
+                continue;
+            const updatePayload = {
+                id: match.ynab_transaction.id,
+            };
+            if (flags.needsDateUpdate) {
+                updatePayload.date = match.bank_transaction.date;
+            }
+            if (flags.needsClearedUpdate) {
+                updatePayload.cleared = 'cleared';
+            }
+            if (params.dry_run) {
+                summary.transactions_updated += 1;
+                if (flags.needsDateUpdate)
+                    summary.dates_adjusted += 1;
+                actions_taken.push({
+                    type: 'update_transaction',
+                    transaction: {
+                        transaction_id: match.ynab_transaction.id,
+                        new_date: flags.needsDateUpdate ? match.bank_transaction.date : undefined,
+                        cleared: flags.needsClearedUpdate ? 'cleared' : undefined,
+                    },
+                    reason: `Would update transaction: ${updateReason(match, flags, currencyCode)}`,
+                });
+                if (flags.needsClearedUpdate) {
+                    applyClearedDelta(match.ynab_transaction.amount);
+                    if (recordAlignmentIfNeeded(`clearing ${match.ynab_transaction.id ?? 'transaction'} (dry run)`)) {
+                        break;
+                    }
+                }
+            }
+            else {
+                transactionsToUpdate.push(updatePayload);
+                if (flags.needsDateUpdate)
+                    summary.dates_adjusted += 1;
+                if (flags.needsClearedUpdate) {
+                    applyClearedDelta(match.ynab_transaction.amount);
+                    if (recordAlignmentIfNeeded(`clearing ${match.ynab_transaction.id}`)) {
+                        break;
+                    }
+                }
+            }
+        }
+        if (!params.dry_run && transactionsToUpdate.length > 0) {
+            const response = await ynabAPI.transactions.updateTransactions(budgetId, {
+                transactions: transactionsToUpdate,
+            });
+            const updatedTransactions = response.data.transactions ?? [];
+            summary.transactions_updated += updatedTransactions.length;
+            for (const updatedTransaction of updatedTransactions) {
+                const match = orderedAutoMatches.find((m) => m.ynab_transaction?.id === updatedTransaction.id);
+                const flags = match
+                    ? computeUpdateFlags(match, params)
+                    : { needsClearedUpdate: false, needsDateUpdate: false };
+                actions_taken.push({
+                    type: 'update_transaction',
+                    transaction: updatedTransaction,
+                    reason: `Updated transaction: ${match ? updateReason(match, flags, currencyCode) : 'cleared'}`,
+                });
+            }
+            accountSnapshotDirty = true;
+        }
+    }
+    const shouldRunSanityPass = params.auto_unclear_missing && !balanceAligned;
+    if (shouldRunSanityPass) {
+        const transactionsToUnclear = [];
+        for (const ynabTxn of orderedUnmatchedYNAB) {
+            if (ynabTxn.cleared !== 'cleared')
+                continue;
+            if (balanceAligned)
+                break;
+            if (params.dry_run) {
+                summary.transactions_updated += 1;
+                actions_taken.push({
+                    type: 'update_transaction',
+                    transaction: { transaction_id: ynabTxn.id, cleared: 'uncleared' },
+                    reason: `Would mark transaction ${ynabTxn.id} as uncleared - not present on statement`,
+                });
+                applyClearedDelta(-ynabTxn.amount);
+                if (recordAlignmentIfNeeded(`unclearing ${ynabTxn.id} (dry run)`)) {
+                    break;
+                }
+            }
+            else {
+                transactionsToUnclear.push({
+                    id: ynabTxn.id,
+                    cleared: 'uncleared',
+                });
+                applyClearedDelta(-ynabTxn.amount);
+                if (recordAlignmentIfNeeded(`unclearing ${ynabTxn.id}`)) {
+                    break;
+                }
+            }
+        }
+        if (!params.dry_run && transactionsToUnclear.length > 0) {
+            const response = await ynabAPI.transactions.updateTransactions(budgetId, {
+                transactions: transactionsToUnclear,
+            });
+            const updatedTransactions = response.data.transactions ?? [];
+            summary.transactions_updated += updatedTransactions.length;
+            for (const updatedTransaction of updatedTransactions) {
+                actions_taken.push({
+                    type: 'update_transaction',
+                    transaction: updatedTransaction,
+                    reason: `Marked transaction ${updatedTransaction.id} as uncleared - not found on statement`,
+                });
+            }
+            accountSnapshotDirty = true;
+        }
+    }
+    let balance_reconciliation;
+    if (params.statement_balance !== undefined && params.statement_date) {
+        balance_reconciliation = await buildBalanceReconciliation({
+            ynabAPI,
+            budgetId,
+            accountId,
+            statementDate: params.statement_date,
+            statementBalance: params.statement_balance,
+            analysis,
+        });
+    }
+    if (!params.dry_run && accountSnapshotDirty) {
+        afterAccount = await refreshAccountSnapshot(ynabAPI, budgetId, accountId);
+    }
+    const balanceChangeMilli = params.dry_run || !accountSnapshotDirty ? 0 : afterAccount.balance - initialAccount.balance;
+    const recommendations = buildRecommendations({
+        summary,
+        params,
+        analysis,
+        balanceChangeMilli,
+        currencyCode,
+    });
+    const result = {
+        summary,
+        account_balance: {
+            before: initialAccount,
+            after: afterAccount,
+        },
+        actions_taken,
+        recommendations,
+    };
+    if (balance_reconciliation !== undefined) {
+        result.balance_reconciliation = balance_reconciliation;
+    }
+    if (bulkOperationDetails) {
+        bulkOperationDetails.failed_transactions = bulkOperationDetails.transaction_failures;
+        result.bulk_operation_details = bulkOperationDetails;
+    }
+    return result;
+}
+function formatDisplay(amount, currency) {
+    return toMoneyValueFromDecimal(amount, currency).value_display;
+}
+function computeUpdateFlags(match, params) {
+    const ynabTxn = match.ynab_transaction;
+    const bankTxn = match.bank_transaction;
+    if (!ynabTxn) {
+        return { needsClearedUpdate: false, needsDateUpdate: false };
+    }
+    const needsClearedUpdate = Boolean(params.auto_update_cleared_status && ynabTxn.cleared !== 'cleared');
+    const needsDateUpdate = Boolean(params.auto_adjust_dates && ynabTxn.date !== bankTxn.date);
+    return { needsClearedUpdate, needsDateUpdate };
+}
+function updateReason(match, flags, _currency) {
+    const parts = [];
+    if (flags.needsClearedUpdate) {
+        parts.push('marked as cleared');
+    }
+    if (flags.needsDateUpdate) {
+        parts.push(`date adjusted to ${match.bank_transaction.date}`);
+    }
+    return parts.join(', ');
+}
+async function buildBalanceReconciliation(args) {
+    const { ynabAPI, budgetId, accountId, statementDate, statementBalance } = args;
+    const ynabMilli = await clearedBalanceAsOf(ynabAPI, budgetId, accountId, statementDate);
+    const bankMilli = toMilli(statementBalance);
+    const discrepancy = bankMilli - ynabMilli;
+    const status = discrepancy === 0 ? 'PERFECTLY_RECONCILED' : 'DISCREPANCY_FOUND';
+    const precision_calculations = {
+        bank_statement_balance_milliunits: bankMilli,
+        ynab_calculated_balance_milliunits: ynabMilli,
+        discrepancy_milliunits: discrepancy,
+        discrepancy_dollars: discrepancy / 1000,
+    };
+    const discrepancy_analysis = discrepancy === 0 ? undefined : buildLikelyCauses(discrepancy);
+    const result = {
+        status,
+        precision_calculations,
+        final_verification: {
+            balance_matches_exactly: discrepancy === 0,
+            all_transactions_accounted: discrepancy === 0,
+            audit_trail_complete: discrepancy === 0,
+            reconciliation_complete: discrepancy === 0,
+        },
+    };
+    if (discrepancy_analysis !== undefined) {
+        result.discrepancy_analysis = discrepancy_analysis;
+    }
+    return result;
+}
+async function clearedBalanceAsOf(api, budgetId, accountId, dateISO) {
+    const response = await api.transactions.getTransactionsByAccount(budgetId, accountId);
+    const asOf = new Date(dateISO);
+    const cleared = response.data.transactions.filter((txn) => txn.cleared === 'cleared' && new Date(txn.date) <= asOf);
+    const sum = cleared.reduce((acc, txn) => addMilli(acc, txn.amount ?? 0), 0);
+    return sum;
+}
+async function refreshAccountSnapshot(api, budgetId, accountId) {
+    const accountsApi = api.accounts;
+    const response = accountsApi.getAccount
+        ? await accountsApi.getAccount(budgetId, accountId)
+        : await accountsApi.getAccountById(budgetId, accountId);
+    const account = response.data.account;
+    return {
+        balance: account.balance,
+        cleared_balance: account.cleared_balance,
+        uncleared_balance: account.uncleared_balance,
+    };
+}
+function buildLikelyCauses(discrepancyMilli) {
+    const causes = [];
+    const abs = Math.abs(discrepancyMilli);
+    if (abs % 1000 === 0 || abs % 500 === 0) {
+        causes.push({
+            cause_type: 'bank_fee',
+            description: 'Round amount suggests a bank fee or interest adjustment.',
+            confidence: 0.8,
+            amount_milliunits: discrepancyMilli,
+            suggested_resolution: discrepancyMilli < 0
+                ? 'Create bank fee transaction and mark cleared'
+                : 'Record interest income',
+            evidence: [],
+        });
+    }
+    return causes.length > 0
+        ? {
+            confidence_level: Math.max(...causes.map((cause) => cause.confidence)),
+            likely_causes: causes,
+            risk_assessment: 'LOW',
+        }
+        : undefined;
+}
+function buildRecommendations(args) {
+    const { summary, params, analysis, balanceChangeMilli, currencyCode } = args;
+    const recommendations = [];
+    if (summary.dates_adjusted > 0) {
+        recommendations.push(`✅ Adjusted ${summary.dates_adjusted} transaction date(s) to match bank statement dates`);
+    }
+    if (analysis.summary.unmatched_bank > 0 && !params.auto_create_transactions) {
+        recommendations.push(`Consider enabling auto_create_transactions to automatically create ${analysis.summary.unmatched_bank} missing transaction(s)`);
+    }
+    if (!params.auto_adjust_dates && analysis.auto_matches.length > 0) {
+        recommendations.push('Consider enabling auto_adjust_dates to align YNAB dates with bank statement dates');
+    }
+    if (analysis.summary.unmatched_ynab > 0) {
+        recommendations.push(`${analysis.summary.unmatched_ynab} transaction(s) exist in YNAB but not on the bank statement — review for duplicates or pending items`);
+    }
+    if (params.dry_run) {
+        recommendations.push('Dry run only — re-run with dry_run=false to apply these changes');
+    }
+    if (Math.abs(balanceChangeMilli) > MONEY_EPSILON_MILLI) {
+        recommendations.push(`Account balance changed by ${toMoneyValue(balanceChangeMilli, currencyCode).value_display} during reconciliation`);
+    }
+    return recommendations;
+}
+function resolveStatementBalanceMilli(balanceInfo, provided) {
+    if (typeof provided === 'number' && Number.isFinite(provided)) {
+        return toMilli(provided);
+    }
+    return (extractMoneyValue(balanceInfo?.target_statement) ??
+        extractMoneyValue(balanceInfo?.current_cleared) ??
+        0);
+}
+function extractMoneyValue(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return toMilli(value);
+    }
+    if (value &&
+        typeof value === 'object' &&
+        'value_milliunits' in value &&
+        typeof value.value_milliunits === 'number') {
+        return value.value_milliunits;
+    }
+    return undefined;
+}
+function sortByDateDescending(items) {
+    return [...items].sort((a, b) => compareDates(b.date, a.date));
+}
+function sortMatchesByBankDateDescending(matches) {
+    return [...matches].sort((a, b) => compareDates(b.bank_transaction.date, a.bank_transaction.date));
+}
+function compareDates(dateA, dateB) {
+    return toChronoValue(dateA) - toChronoValue(dateB);
+}
+function toChronoValue(date) {
+    const parsed = Date.parse(date);
+    if (!Number.isNaN(parsed)) {
+        return parsed;
+    }
+    const fallback = Date.parse(`${date}T00:00:00Z`);
+    return Number.isNaN(fallback) ? 0 : fallback;
+}

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

@@ -0,0 +1,54 @@
+import { z } from 'zod/v4';
+import type * as ynab from 'ynab';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { DeltaFetcher } from '../deltaFetcher.js';
+export type * from './types.js';
+export { analyzeReconciliation } from './analyzer.js';
+export { findMatches, findBestMatch } from './matcher.js';
+export { normalizePayee, normalizedMatch, fuzzyMatch, payeeSimilarity } from './payeeNormalizer.js';
+export declare const ReconcileAccountSchema: z.ZodObject<{
+    budget_id: z.ZodString;
+    account_id: z.ZodString;
+    csv_file_path: z.ZodOptional<z.ZodString>;
+    csv_data: z.ZodOptional<z.ZodString>;
+    csv_format: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        date_column: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        amount_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        debit_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        credit_column: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        description_column: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        date_format: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        has_header: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        delimiter: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strict>>>;
+    statement_balance: z.ZodNumber;
+    statement_start_date: z.ZodOptional<z.ZodString>;
+    statement_end_date: z.ZodOptional<z.ZodString>;
+    statement_date: z.ZodOptional<z.ZodString>;
+    expected_bank_balance: z.ZodOptional<z.ZodNumber>;
+    as_of_timezone: z.ZodOptional<z.ZodString>;
+    date_tolerance_days: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    amount_tolerance_cents: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    auto_match_threshold: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    suggestion_threshold: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    amount_tolerance: z.ZodOptional<z.ZodNumber>;
+    auto_create_transactions: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    auto_update_cleared_status: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    auto_unclear_missing: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    auto_adjust_dates: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    invert_bank_amounts: z.ZodOptional<z.ZodBoolean>;
+    dry_run: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    balance_verification_mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        ANALYSIS_ONLY: "ANALYSIS_ONLY";
+        GUIDED_RESOLUTION: "GUIDED_RESOLUTION";
+        AUTO_RESOLVE: "AUTO_RESOLVE";
+    }>>>;
+    require_exact_match: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    confidence_threshold: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    max_resolution_attempts: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    include_structured_data: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    force_full_refresh: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type ReconcileAccountRequest = z.infer<typeof ReconcileAccountSchema>;
+export declare function handleReconcileAccount(ynabAPI: ynab.API, deltaFetcher: DeltaFetcher, params: ReconcileAccountRequest): Promise<CallToolResult>;
+export declare function handleReconcileAccount(ynabAPI: ynab.API, params: ReconcileAccountRequest): Promise<CallToolResult>;