@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/reconciliation/index.js

@@ -0,0 +1,249 @@
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../../types/index.js';
+import { analyzeReconciliation } from './analyzer.js';
+import { buildReconciliationPayload } from '../reconcileAdapter.js';
+import { executeReconciliation, } from './executor.js';
+import { responseFormatter } from '../../server/responseFormatter.js';
+import { extractDateRangeFromCSV, autoDetectCSVFormat } from '../compareTransactions/parser.js';
+import { resolveDeltaFetcherArgs } from '../deltaSupport.js';
+export { analyzeReconciliation } from './analyzer.js';
+export { findMatches, findBestMatch } from './matcher.js';
+export { normalizePayee, normalizedMatch, fuzzyMatch, payeeSimilarity } from './payeeNormalizer.js';
+function getAuditDataSource(transactionsResult, forceFullRefresh) {
+    if (forceFullRefresh) {
+        return 'full_api_fetch_no_delta';
+    }
+    if (transactionsResult.usedDelta) {
+        return 'delta_fetch_with_merge';
+    }
+    if (transactionsResult.wasCached) {
+        return 'delta_fetch_cache_hit';
+    }
+    return 'delta_fetch_full_refresh';
+}
+function getDataFreshness(transactionsResult, forceFullRefresh) {
+    if (forceFullRefresh) {
+        return 'guaranteed_fresh';
+    }
+    if (transactionsResult.wasCached) {
+        return 'cache_validated_via_server_knowledge';
+    }
+    return 'fresh_via_delta_fetch';
+}
+export const ReconcileAccountSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+    csv_file_path: z.string().optional(),
+    csv_data: z.string().optional(),
+    csv_format: z
+        .object({
+        date_column: z.union([z.string(), z.number()]).optional().default('Date'),
+        amount_column: z.union([z.string(), z.number()]).optional(),
+        debit_column: z.union([z.string(), z.number()]).optional(),
+        credit_column: z.union([z.string(), z.number()]).optional(),
+        description_column: z.union([z.string(), z.number()]).optional().default('Description'),
+        date_format: z.string().optional().default('MM/DD/YYYY'),
+        has_header: z.boolean().optional().default(true),
+        delimiter: z.string().optional().default(','),
+    })
+        .strict()
+        .optional()
+        .default(() => ({
+        date_column: 'Date',
+        amount_column: 'Amount',
+        description_column: 'Description',
+        date_format: 'MM/DD/YYYY',
+        has_header: true,
+        delimiter: ',',
+    })),
+    statement_balance: z.number({
+        message: 'Statement balance is required and must be a number',
+    }),
+    statement_start_date: z.string().optional(),
+    statement_end_date: z.string().optional(),
+    statement_date: z.string().optional(),
+    expected_bank_balance: z.number().optional(),
+    as_of_timezone: z.string().optional(),
+    date_tolerance_days: z.number().min(0).max(7).optional().default(5),
+    amount_tolerance_cents: z.number().min(0).max(100).optional().default(1),
+    auto_match_threshold: z.number().min(0).max(100).optional().default(90),
+    suggestion_threshold: z.number().min(0).max(100).optional().default(60),
+    amount_tolerance: z.number().min(0).max(1).optional(),
+    auto_create_transactions: z.boolean().optional().default(false),
+    auto_update_cleared_status: z.boolean().optional().default(false),
+    auto_unclear_missing: z.boolean().optional().default(true),
+    auto_adjust_dates: z.boolean().optional().default(false),
+    invert_bank_amounts: z.boolean().optional(),
+    dry_run: z.boolean().optional().default(true),
+    balance_verification_mode: z
+        .enum(['ANALYSIS_ONLY', 'GUIDED_RESOLUTION', 'AUTO_RESOLVE'])
+        .optional()
+        .default('ANALYSIS_ONLY'),
+    require_exact_match: z.boolean().optional().default(true),
+    confidence_threshold: z.number().min(0).max(1).optional().default(0.8),
+    max_resolution_attempts: z.number().int().min(1).max(10).optional().default(5),
+    include_structured_data: z.boolean().optional().default(false),
+    force_full_refresh: z.boolean().optional().default(true),
+})
+    .refine((data) => data.csv_file_path || data.csv_data, {
+    message: 'Either csv_file_path or csv_data must be provided',
+    path: ['csv_data'],
+});
+export async function handleReconcileAccount(ynabAPI, deltaFetcherOrParams, maybeParams) {
+    const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
+    const forceFullRefresh = params.force_full_refresh ?? true;
+    return await withToolErrorHandling(async () => {
+        const config = {
+            dateToleranceDays: params.date_tolerance_days,
+            amountToleranceCents: params.amount_tolerance_cents,
+            descriptionSimilarityThreshold: 0.8,
+            autoMatchThreshold: params.auto_match_threshold,
+            suggestionThreshold: params.suggestion_threshold,
+        };
+        const accountResult = forceFullRefresh
+            ? await deltaFetcher.fetchAccountsFull(params.budget_id)
+            : await deltaFetcher.fetchAccounts(params.budget_id);
+        const accountData = accountResult.data.find((account) => account.id === params.account_id);
+        if (!accountData) {
+            throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
+        }
+        const accountName = accountData.name;
+        const accountType = accountData.type;
+        const accountIsLiability = accountType === 'creditCard' ||
+            accountType === 'lineOfCredit' ||
+            accountType === 'mortgage' ||
+            accountType === 'autoLoan' ||
+            accountType === 'studentLoan' ||
+            accountType === 'personalLoan' ||
+            accountType === 'medicalDebt' ||
+            accountType === 'otherDebt' ||
+            accountType === 'otherLiability';
+        const shouldInvertBankAmounts = params.invert_bank_amounts !== undefined ? params.invert_bank_amounts : accountIsLiability;
+        const adjustedStatementBalance = accountIsLiability
+            ? -Math.abs(params.statement_balance)
+            : params.statement_balance;
+        const budgetResponse = await ynabAPI.budgets.getBudgetById(params.budget_id);
+        const currencyCode = budgetResponse.data.budget?.currency_format?.iso_code ?? 'USD';
+        let sinceDate;
+        if (params.statement_start_date) {
+            sinceDate = new Date(params.statement_start_date);
+        }
+        else {
+            try {
+                const csvContent = params.csv_data || params.csv_file_path || '';
+                const csvFormat = params.csv_format || autoDetectCSVFormat(csvContent);
+                const parserFormat = {
+                    date_column: csvFormat.date_column || 'Date',
+                    amount_column: csvFormat.amount_column,
+                    debit_column: csvFormat.debit_column,
+                    credit_column: csvFormat.credit_column,
+                    description_column: csvFormat.description_column || 'Description',
+                    date_format: csvFormat.date_format || 'MM/DD/YYYY',
+                    has_header: csvFormat.has_header ?? true,
+                    delimiter: csvFormat.delimiter || ',',
+                };
+                const { minDate } = extractDateRangeFromCSV(csvContent, parserFormat);
+                const minDateObj = new Date(minDate);
+                minDateObj.setDate(minDateObj.getDate() - 7);
+                sinceDate = minDateObj;
+            }
+            catch {
+                sinceDate = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
+            }
+        }
+        const sinceDateString = sinceDate.toISOString().split('T')[0];
+        const transactionsResult = forceFullRefresh
+            ? await deltaFetcher.fetchTransactionsByAccountFull(params.budget_id, params.account_id, sinceDateString)
+            : await deltaFetcher.fetchTransactionsByAccount(params.budget_id, params.account_id, sinceDateString);
+        const ynabTransactions = transactionsResult.data;
+        const auditMetadata = {
+            data_freshness: getDataFreshness(transactionsResult, forceFullRefresh),
+            data_source: getAuditDataSource(transactionsResult, forceFullRefresh),
+            server_knowledge: transactionsResult.serverKnowledge,
+            fetched_at: new Date().toISOString(),
+            accounts_count: accountResult.data.length,
+            transactions_count: transactionsResult.data.length,
+            cache_status: {
+                accounts_cached: accountResult.wasCached,
+                transactions_cached: transactionsResult.wasCached,
+                delta_merge_applied: transactionsResult.usedDelta,
+            },
+        };
+        const analysis = analyzeReconciliation(params.csv_data || params.csv_file_path || '', params.csv_file_path, ynabTransactions, adjustedStatementBalance, config, currencyCode, params.account_id, params.budget_id, shouldInvertBankAmounts);
+        const initialAccount = {
+            balance: accountData.balance,
+            cleared_balance: accountData.cleared_balance,
+            uncleared_balance: accountData.uncleared_balance,
+        };
+        let executionData;
+        const wantsBalanceVerification = Boolean(params.statement_date);
+        const shouldExecute = params.auto_create_transactions ||
+            params.auto_update_cleared_status ||
+            params.auto_unclear_missing ||
+            params.auto_adjust_dates ||
+            params.balance_verification_mode !== 'ANALYSIS_ONLY' ||
+            wantsBalanceVerification;
+        if (shouldExecute) {
+            executionData = await executeReconciliation({
+                ynabAPI,
+                analysis,
+                params,
+                budgetId: params.budget_id,
+                accountId: params.account_id,
+                initialAccount,
+                currencyCode,
+            });
+        }
+        const csvFormatForPayload = mapCsvFormatForPayload(params.csv_format);
+        const adapterOptions = {
+            accountName,
+            accountId: params.account_id,
+            currencyCode,
+            auditMetadata,
+        };
+        if (csvFormatForPayload !== undefined) {
+            adapterOptions.csvFormat = csvFormatForPayload;
+        }
+        const payload = buildReconciliationPayload(analysis, adapterOptions, executionData);
+        const responseData = {
+            human: payload.human,
+        };
+        if (params.include_structured_data) {
+            responseData['structured'] = payload.structured;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format(responseData),
+                },
+            ],
+        };
+    }, 'ynab:reconcile_account', 'analyzing account reconciliation');
+}
+function mapCsvFormatForPayload(format) {
+    if (!format) {
+        return undefined;
+    }
+    const coerceString = (value, fallback) => {
+        if (value === undefined || value === null) {
+            return fallback ?? null;
+        }
+        return String(value);
+    };
+    const delimiter = coerceString(format.delimiter, ',');
+    const decimalSeparator = '.';
+    const thousandsSeparator = ',';
+    const dateFormat = coerceString(format.date_format, 'MM/DD/YYYY');
+    return {
+        delimiter: delimiter ?? ',',
+        decimal_separator: decimalSeparator,
+        thousands_separator: thousandsSeparator,
+        date_format: dateFormat ?? 'MM/DD/YYYY',
+        header_row: format.has_header ?? true,
+        date_column: coerceString(format.date_column, '') ?? null,
+        amount_column: coerceString(format.amount_column, '') ?? null,
+        payee_column: coerceString(format.description_column, '') ?? null,
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { BankTransaction, YNABTransaction, TransactionMatch, MatchingConfig } from './types.js';
+export declare function findBestMatch(bankTxn: BankTransaction, ynabTransactions: YNABTransaction[], usedIds: Set<string>, config: MatchingConfig): TransactionMatch;
+export declare function findMatches(bankTransactions: BankTransaction[], ynabTransactions: YNABTransaction[], config?: MatchingConfig): TransactionMatch[];

package/dist/tools/reconciliation/matcher.js

@@ -0,0 +1,160 @@
+import { normalizedMatch, payeeSimilarity } from './payeeNormalizer.js';
+import { DEFAULT_MATCHING_CONFIG } from './types.js';
+function amountsMatch(bankAmount, ynabAmount, toleranceCents) {
+    const ynabDollars = ynabAmount / 1000;
+    const difference = Math.round(Math.abs(bankAmount - ynabDollars) * 100) / 100;
+    const toleranceDollars = toleranceCents / 100;
+    return difference <= toleranceDollars;
+}
+function datesMatch(date1, date2, toleranceDays) {
+    const d1 = new Date(date1);
+    const d2 = new Date(date2);
+    const diffMs = Math.abs(d1.getTime() - d2.getTime());
+    const diffDays = diffMs / (1000 * 60 * 60 * 24);
+    return diffDays <= toleranceDays;
+}
+function calculateMatchScore(bankTxn, ynabTxn, config) {
+    const reasons = [];
+    let score = 0;
+    const amountMatch = amountsMatch(bankTxn.amount, ynabTxn.amount, config.amountToleranceCents);
+    if (!amountMatch) {
+        return { score: 0, reasons: ['Amount does not match'] };
+    }
+    score += 40;
+    reasons.push('Amount matches');
+    const dateWithinTolerance = datesMatch(bankTxn.date, ynabTxn.date, config.dateToleranceDays);
+    if (dateWithinTolerance) {
+        score += 40;
+        const daysDiff = Math.abs((new Date(bankTxn.date).getTime() - new Date(ynabTxn.date).getTime()) / (1000 * 60 * 60 * 24));
+        if (daysDiff === 0) {
+            reasons.push('Exact date match');
+        }
+        else {
+            reasons.push(`Date within ${Math.round(daysDiff)} days`);
+        }
+    }
+    const payeeScore = payeeSimilarity(bankTxn.payee, ynabTxn.payee_name);
+    if (normalizedMatch(bankTxn.payee, ynabTxn.payee_name)) {
+        score += 20;
+        reasons.push('Payee exact match');
+    }
+    else if (payeeScore >= 95) {
+        score += 15;
+        reasons.push(`Payee highly similar (${Math.round(payeeScore)}%)`);
+    }
+    else if (payeeScore >= 80) {
+        score += 10;
+        reasons.push(`Payee similar (${Math.round(payeeScore)}%)`);
+    }
+    else if (payeeScore >= 60) {
+        score += 6;
+        reasons.push(`Payee somewhat similar (${Math.round(payeeScore)}%)`);
+    }
+    return { score: Math.round(score), reasons };
+}
+function getPriority(ynabTxn) {
+    if (ynabTxn.cleared === 'uncleared')
+        return 10;
+    if (ynabTxn.cleared === 'cleared')
+        return 5;
+    if (ynabTxn.cleared === 'reconciled')
+        return 1;
+    return 0;
+}
+function findMatchCandidates(bankTxn, ynabTransactions, usedIds, config) {
+    const candidates = [];
+    for (const ynabTxn of ynabTransactions) {
+        if (usedIds.has(ynabTxn.id))
+            continue;
+        if (bankTxn.amount > 0 !== ynabTxn.amount > 0)
+            continue;
+        const { score, reasons } = calculateMatchScore(bankTxn, ynabTxn, config);
+        if (score >= 30) {
+            candidates.push({
+                ynab_transaction: ynabTxn,
+                confidence: score,
+                match_reason: reasons.join(', '),
+                explanation: buildExplanation(bankTxn, ynabTxn, score, reasons),
+            });
+        }
+    }
+    candidates.sort((a, b) => {
+        if (b.confidence !== a.confidence) {
+            return b.confidence - a.confidence;
+        }
+        const priorityDiff = getPriority(b.ynab_transaction) - getPriority(a.ynab_transaction);
+        if (priorityDiff !== 0)
+            return priorityDiff;
+        const dateProximityA = Math.abs(new Date(bankTxn.date).getTime() - new Date(a.ynab_transaction.date).getTime());
+        const dateProximityB = Math.abs(new Date(bankTxn.date).getTime() - new Date(b.ynab_transaction.date).getTime());
+        return dateProximityA - dateProximityB;
+    });
+    return candidates;
+}
+function buildExplanation(_bankTxn, ynabTxn, score, reasons) {
+    const parts = [];
+    parts.push(`Match confidence: ${score}%`);
+    parts.push(reasons.join(', '));
+    if (ynabTxn.cleared === 'uncleared') {
+        parts.push('(Uncleared - awaiting confirmation)');
+    }
+    return parts.join(' | ');
+}
+export function findBestMatch(bankTxn, ynabTransactions, usedIds, config) {
+    const candidates = findMatchCandidates(bankTxn, ynabTransactions, usedIds, config);
+    if (candidates.length === 0) {
+        return {
+            bank_transaction: bankTxn,
+            confidence: 'none',
+            confidence_score: 0,
+            match_reason: 'No matching transaction found in YNAB',
+            action_hint: 'add_to_ynab',
+            recommendation: 'This transaction appears on bank statement but not in YNAB',
+        };
+    }
+    const bestCandidate = candidates[0];
+    const bestScore = bestCandidate.confidence;
+    if (bestScore >= config.autoMatchThreshold) {
+        return {
+            bank_transaction: bankTxn,
+            ynab_transaction: bestCandidate.ynab_transaction,
+            confidence: 'high',
+            confidence_score: bestScore,
+            match_reason: bestCandidate.match_reason,
+        };
+    }
+    if (bestScore >= config.suggestionThreshold) {
+        return {
+            bank_transaction: bankTxn,
+            ynab_transaction: bestCandidate.ynab_transaction,
+            candidates: candidates.slice(0, 3),
+            confidence: 'medium',
+            confidence_score: bestScore,
+            match_reason: bestCandidate.match_reason,
+            top_confidence: bestScore,
+            action_hint: 'review_and_choose',
+        };
+    }
+    return {
+        bank_transaction: bankTxn,
+        candidates: candidates.slice(0, 3),
+        confidence: 'low',
+        confidence_score: bestScore,
+        match_reason: 'Low confidence match',
+        top_confidence: bestScore,
+        action_hint: 'review_or_add_new',
+        recommendation: 'Consider reviewing candidates or adding as new transaction',
+    };
+}
+export function findMatches(bankTransactions, ynabTransactions, config = DEFAULT_MATCHING_CONFIG) {
+    const matches = [];
+    const usedIds = new Set();
+    for (const bankTxn of bankTransactions) {
+        const match = findBestMatch(bankTxn, ynabTransactions, usedIds, config);
+        matches.push(match);
+        if (match.confidence === 'high' && match.ynab_transaction) {
+            usedIds.add(match.ynab_transaction.id);
+        }
+    }
+    return matches;
+}

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

@@ -0,0 +1,6 @@
+export declare function normalizePayee(payee: string | null | undefined): string;
+export declare function normalizedMatch(payee1: string | null | undefined, payee2: string | null | undefined): boolean;
+export declare function fuzzyMatch(payee1: string | null | undefined, payee2: string | null | undefined): number;
+export declare function tokenBasedSimilarity(payee1: string | null | undefined, payee2: string | null | undefined): number;
+export declare function payeeSimilarity(payee1: string | null | undefined, payee2: string | null | undefined): number;
+export declare function payeeContains(payee: string | null | undefined, substring: string): boolean;

package/dist/tools/reconciliation/payeeNormalizer.js

@@ -0,0 +1,77 @@
+export function normalizePayee(payee) {
+    if (!payee)
+        return '';
+    return payee.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+export function normalizedMatch(payee1, payee2) {
+    const norm1 = normalizePayee(payee1);
+    const norm2 = normalizePayee(payee2);
+    if (!norm1 || !norm2)
+        return false;
+    return norm1 === norm2;
+}
+function levenshteinDistance(str1, str2) {
+    const len1 = str1.length;
+    const len2 = str2.length;
+    const matrix = Array(len1 + 1)
+        .fill(null)
+        .map(() => Array(len2 + 1).fill(0));
+    for (let i = 0; i <= len1; i++)
+        matrix[i][0] = i;
+    for (let j = 0; j <= len2; j++)
+        matrix[0][j] = j;
+    for (let i = 1; i <= len1; i++) {
+        for (let j = 1; j <= len2; j++) {
+            const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[len1][len2];
+}
+export function fuzzyMatch(payee1, payee2) {
+    const norm1 = normalizePayee(payee1);
+    const norm2 = normalizePayee(payee2);
+    if (!norm1 || !norm2)
+        return 0;
+    if (norm1 === norm2)
+        return 100;
+    const distance = levenshteinDistance(norm1, norm2);
+    const maxLen = Math.max(norm1.length, norm2.length);
+    if (maxLen === 0)
+        return 0;
+    const similarity = (1 - distance / maxLen) * 100;
+    return Math.max(0, Math.min(100, similarity));
+}
+export function tokenBasedSimilarity(payee1, payee2) {
+    const norm1 = normalizePayee(payee1);
+    const norm2 = normalizePayee(payee2);
+    if (!norm1 || !norm2)
+        return 0;
+    const tokens1 = norm1.match(/[a-z]+|[0-9]+/g) || [];
+    const tokens2 = norm2.match(/[a-z]+|[0-9]+/g) || [];
+    if (tokens1.length === 0 || tokens2.length === 0)
+        return 0;
+    const set1 = new Set(tokens1);
+    const set2 = new Set(tokens2);
+    let matches = 0;
+    for (const token of set1) {
+        if (set2.has(token))
+            matches++;
+    }
+    const union = new Set([...set1, ...set2]).size;
+    return (matches / union) * 100;
+}
+export function payeeSimilarity(payee1, payee2) {
+    if (normalizedMatch(payee1, payee2))
+        return 100;
+    const fuzzyScore = fuzzyMatch(payee1, payee2);
+    const tokenScore = tokenBasedSimilarity(payee1, payee2);
+    return Math.max(fuzzyScore, tokenScore);
+}
+export function payeeContains(payee, substring) {
+    const norm = normalizePayee(payee);
+    const normSub = normalizePayee(substring);
+    if (!norm || !normSub)
+        return false;
+    return norm.includes(normSub);
+}

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

@@ -0,0 +1,2 @@
+import type { ActionableRecommendation, RecommendationContext } from './types.js';
+export declare function generateRecommendations(context: RecommendationContext): ActionableRecommendation[];