@dizzlkheinz/ynab-mcpb 0.18.4 → 0.19.0

package/dist/tools/transactionTools.js

@@ -1,1501 +1,9 @@
-import { ValidationError, withToolErrorHandling } from '../types/index.js';
-import { createAdapters, createBudgetResolver } from './adapters.js';
-import { ToolAnnotationPresets } from './toolCategories.js';
-import { responseFormatter } from '../server/responseFormatter.js';
-import { amountToMilliunits, milliunitsToAmount } from '../utils/amountUtils.js';
-import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
-import { globalRequestLogger } from '../server/requestLogger.js';
-import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
-import { handleExportTransactions, ExportTransactionsSchema } from './exportTransactions.js';
-import { ListTransactionsSchema, GetTransactionSchema, CreateTransactionSchema, CreateTransactionsSchema, CreateReceiptSplitTransactionSchema, UpdateTransactionSchema, UpdateTransactionsSchema, DeleteTransactionSchema, } from './transactionSchemas.js';
-import { ensureTransaction, appendCategoryIds, collectCategoryIdsFromSources, setsEqual, invalidateTransactionCaches, correlateResults, finalizeResponse, finalizeBulkUpdateResponse, handleTransactionError, toMonthKey, } from './transactionUtils.js';
-export async function handleListTransactions(ynabAPI, deltaFetcherOrParams, maybeParams) {
-    const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
-    return await withToolErrorHandling(async () => {
-        let transactions;
-        let cacheHit = false;
-        let usedDelta = false;
-        if (params.account_id) {
-            const accountsResult = await deltaFetcher.fetchAccounts(params.budget_id);
-            const accountExists = accountsResult.data.some((account) => account.id === params.account_id);
-            if (!accountExists) {
-                throw new Error(`Account ${params.account_id} not found in budget ${params.budget_id}`);
-            }
-            const result = await deltaFetcher.fetchTransactionsByAccount(params.budget_id, params.account_id, params.since_date);
-            transactions = result.data;
-            cacheHit = result.wasCached;
-            usedDelta = result.usedDelta;
-        }
-        else if (params.category_id) {
-            const response = await ynabAPI.transactions.getTransactionsByCategory(params.budget_id, params.category_id, params.since_date);
-            transactions = response.data.transactions;
-        }
-        else {
-            const result = await deltaFetcher.fetchTransactions(params.budget_id, params.since_date, params.type);
-            transactions = result.data;
-            cacheHit = result.wasCached;
-            usedDelta = result.usedDelta;
-        }
-        const estimatedSize = JSON.stringify(transactions).length;
-        const sizeLimit = 90000;
-        if (estimatedSize > sizeLimit) {
-            const preview = transactions.slice(0, 50);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: responseFormatter.format({
-                            message: `Found ${transactions.length} transactions (${Math.round(estimatedSize / 1024)}KB). Too large to display all.`,
-                            suggestion: "Use 'export_transactions' tool to save all transactions to a file.",
-                            showing: `First ${preview.length} transactions:`,
-                            total_count: transactions.length,
-                            estimated_size_kb: Math.round(estimatedSize / 1024),
-                            cached: cacheHit,
-                            cache_info: cacheHit
-                                ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
-                                : 'Fresh data retrieved from YNAB API',
-                            preview_transactions: preview.map((transaction) => ({
-                                id: transaction.id,
-                                date: transaction.date,
-                                amount: milliunitsToAmount(transaction.amount),
-                                memo: transaction.memo,
-                                payee_name: transaction.payee_name,
-                                category_name: transaction.category_name,
-                            })),
-                        }),
-                    },
-                ],
-            };
-        }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format({
-                        total_count: transactions.length,
-                        cached: cacheHit,
-                        cache_info: cacheHit
-                            ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
-                            : 'Fresh data retrieved from YNAB API',
-                        transactions: transactions.map((transaction) => ({
-                            id: transaction.id,
-                            date: transaction.date,
-                            amount: milliunitsToAmount(transaction.amount),
-                            memo: transaction.memo,
-                            cleared: transaction.cleared,
-                            approved: transaction.approved,
-                            flag_color: transaction.flag_color,
-                            account_id: transaction.account_id,
-                            payee_id: transaction.payee_id,
-                            category_id: transaction.category_id,
-                            transfer_account_id: transaction.transfer_account_id,
-                            transfer_transaction_id: transaction.transfer_transaction_id,
-                            matched_transaction_id: transaction.matched_transaction_id,
-                            import_id: transaction.import_id,
-                            deleted: transaction.deleted,
-                        })),
-                    }),
-                },
-            ],
-        };
-    }, 'ynab:list_transactions', 'listing transactions');
-}
-export async function handleGetTransaction(ynabAPI, params) {
-    try {
-        const useCache = process.env['NODE_ENV'] !== 'test';
-        let transaction;
-        let cacheHit = false;
-        if (useCache) {
-            const cacheKey = CacheManager.generateKey('transaction', 'get', params.budget_id, params.transaction_id);
-            cacheHit = cacheManager.has(cacheKey);
-            transaction = await cacheManager.wrap(cacheKey, {
-                ttl: CACHE_TTLS.TRANSACTIONS,
-                loader: async () => {
-                    const response = await ynabAPI.transactions.getTransactionById(params.budget_id, params.transaction_id);
-                    return ensureTransaction(response.data.transaction, 'Transaction not found');
-                },
-            });
-        }
-        else {
-            const response = await ynabAPI.transactions.getTransactionById(params.budget_id, params.transaction_id);
-            transaction = ensureTransaction(response.data.transaction, 'Transaction not found');
-        }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format({
-                        transaction: {
-                            id: transaction.id,
-                            date: transaction.date,
-                            amount: milliunitsToAmount(transaction.amount),
-                            memo: transaction.memo,
-                            cleared: transaction.cleared,
-                            approved: transaction.approved,
-                            flag_color: transaction.flag_color,
-                            account_id: transaction.account_id,
-                            payee_id: transaction.payee_id,
-                            category_id: transaction.category_id,
-                            transfer_account_id: transaction.transfer_account_id,
-                            transfer_transaction_id: transaction.transfer_transaction_id,
-                            matched_transaction_id: transaction.matched_transaction_id,
-                            import_id: transaction.import_id,
-                            deleted: transaction.deleted,
-                            account_name: transaction.account_name,
-                            payee_name: transaction.payee_name,
-                            category_name: transaction.category_name,
-                        },
-                        cached: cacheHit,
-                        cache_info: cacheHit
-                            ? 'Data retrieved from cache for improved performance'
-                            : 'Fresh data retrieved from YNAB API',
-                    }),
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return handleTransactionError(error, 'Failed to get transaction');
-    }
-}
-export async function handleCreateTransaction(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
-    const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
-    try {
-        if (params.dry_run) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: responseFormatter.format({
-                            dry_run: true,
-                            action: 'create_transaction',
-                            request: params,
-                        }),
-                    },
-                ],
-            };
-        }
-        const transactionData = {
-            account_id: params.account_id,
-            amount: params.amount,
-            date: params.date,
-            cleared: params.cleared,
-            flag_color: params.flag_color,
-        };
-        if (params.payee_name !== undefined)
-            transactionData.payee_name = params.payee_name;
-        if (params.payee_id !== undefined)
-            transactionData.payee_id = params.payee_id;
-        if (params.category_id !== undefined)
-            transactionData.category_id = params.category_id;
-        if (params.memo !== undefined)
-            transactionData.memo = params.memo;
-        if (params.approved !== undefined)
-            transactionData.approved = params.approved;
-        if (params.import_id !== undefined)
-            transactionData.import_id = params.import_id;
-        if (params.subtransactions && params.subtransactions.length > 0) {
-            const subtransactions = params.subtransactions.map((subtransaction) => {
-                const mapped = {
-                    amount: subtransaction.amount,
-                };
-                if (subtransaction.payee_name !== undefined)
-                    mapped.payee_name = subtransaction.payee_name;
-                if (subtransaction.payee_id !== undefined)
-                    mapped.payee_id = subtransaction.payee_id;
-                if (subtransaction.category_id !== undefined) {
-                    mapped.category_id = subtransaction.category_id;
-                }
-                if (subtransaction.memo !== undefined)
-                    mapped.memo = subtransaction.memo;
-                return mapped;
-            });
-            transactionData.subtransactions = subtransactions;
-        }
-        const response = await ynabAPI.transactions.createTransaction(params.budget_id, {
-            transaction: transactionData,
-        });
-        const transaction = ensureTransaction(response.data.transaction, 'Transaction creation failed');
-        const affectedAccountIds = new Set([transaction.account_id]);
-        const affectedMonths = new Set([toMonthKey(transaction.date)]);
-        const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
-        invalidateTransactionCaches(deltaCache, knowledgeStore, params.budget_id, response.data.server_knowledge, affectedAccountIds, affectedMonths, {
-            affectedCategoryIds,
-            accountTotalsChanged: true,
-            invalidateMonths: true,
-        });
-        const accountResponse = await ynabAPI.accounts.getAccountById(params.budget_id, transaction.account_id);
-        const account = accountResponse.data.account;
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format({
-                        transaction: {
-                            id: transaction.id,
-                            date: transaction.date,
-                            amount: milliunitsToAmount(transaction.amount),
-                            memo: transaction.memo,
-                            cleared: transaction.cleared,
-                            approved: transaction.approved,
-                            flag_color: transaction.flag_color,
-                            account_id: transaction.account_id,
-                            payee_id: transaction.payee_id,
-                            category_id: transaction.category_id,
-                            transfer_account_id: transaction.transfer_account_id,
-                            transfer_transaction_id: transaction.transfer_transaction_id,
-                            matched_transaction_id: transaction.matched_transaction_id,
-                            import_id: transaction.import_id,
-                            deleted: transaction.deleted,
-                            account_balance: account.balance,
-                            account_cleared_balance: account.cleared_balance,
-                            subtransactions: transaction.subtransactions?.map((subtransaction) => ({
-                                id: subtransaction.id,
-                                transaction_id: subtransaction.transaction_id,
-                                amount: milliunitsToAmount(subtransaction.amount),
-                                memo: subtransaction.memo,
-                                payee_id: subtransaction.payee_id,
-                                payee_name: subtransaction.payee_name,
-                                category_id: subtransaction.category_id,
-                                category_name: subtransaction.category_name,
-                                transfer_account_id: subtransaction.transfer_account_id,
-                                transfer_transaction_id: subtransaction.transfer_transaction_id,
-                                deleted: subtransaction.deleted,
-                            })),
-                        },
-                    }),
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return handleTransactionError(error, 'Failed to create transaction');
-    }
-}
-const BIG_TICKET_THRESHOLD_MILLIUNITS = 50000;
-const COLLAPSE_THRESHOLD = 5;
-const MAX_ITEMS_PER_MEMO = 5;
-const MAX_MEMO_LENGTH = 150;
-function truncateToLength(str, maxLength) {
-    if (str.length <= maxLength) {
-        return str;
-    }
-    const ellipsis = '...';
-    return str.substring(0, maxLength - ellipsis.length) + ellipsis;
-}
-function buildItemMemo(item) {
-    const quantitySuffix = item.quantity ? ` (x${item.quantity})` : '';
-    let result;
-    if (item.memo && item.memo.trim().length > 0) {
-        result = `${item.name}${quantitySuffix} - ${item.memo}`;
-    }
-    else if (quantitySuffix) {
-        result = `${item.name}${quantitySuffix}`;
-    }
-    else {
-        result = item.name;
-    }
-    return truncateToLength(result, MAX_MEMO_LENGTH);
-}
-function applySmartCollapseLogic(categoryCalculations, taxMilliunits) {
-    const specialItems = [];
-    const remainingItemsByCategory = [];
-    for (const category of categoryCalculations) {
-        const categorySpecials = [];
-        const categoryRemaining = [];
-        for (const item of category.items) {
-            const isNegative = item.amount_milliunits < 0;
-            const unitPrice = item.quantity
-                ? item.amount_milliunits / item.quantity
-                : item.amount_milliunits;
-            const isBigTicket = unitPrice > BIG_TICKET_THRESHOLD_MILLIUNITS;
-            if (isNegative || isBigTicket) {
-                categorySpecials.push(item);
-            }
-            else {
-                categoryRemaining.push(item);
-            }
-        }
-        for (const item of categorySpecials) {
-            specialItems.push({
-                item,
-                category_id: category.category_id,
-                category_name: category.category_name,
-            });
-        }
-        if (categoryRemaining.length > 0) {
-            remainingItemsByCategory.push({
-                category_id: category.category_id,
-                category_name: category.category_name,
-                items: categoryRemaining,
-            });
-        }
-    }
-    const totalRemainingItems = remainingItemsByCategory.reduce((sum, cat) => sum + cat.items.length, 0);
-    const shouldCollapse = totalRemainingItems >= COLLAPSE_THRESHOLD;
-    const subtransactions = [];
-    for (const special of specialItems) {
-        const memo = buildItemMemo({
-            name: special.item.name,
-            quantity: special.item.quantity,
-            memo: special.item.memo,
-        });
-        const payload = {
-            amount: -special.item.amount_milliunits,
-            category_id: special.category_id,
-        };
-        if (memo)
-            payload.memo = memo;
-        subtransactions.push(payload);
-    }
-    if (shouldCollapse) {
-        for (const categoryGroup of remainingItemsByCategory) {
-            const collapsedSubtransactions = collapseItemsByCategory(categoryGroup);
-            subtransactions.push(...collapsedSubtransactions);
-        }
-    }
-    else {
-        for (const categoryGroup of remainingItemsByCategory) {
-            for (const item of categoryGroup.items) {
-                const memo = buildItemMemo({
-                    name: item.name,
-                    quantity: item.quantity,
-                    memo: item.memo,
-                });
-                const payload = {
-                    amount: -item.amount_milliunits,
-                    category_id: categoryGroup.category_id,
-                };
-                if (memo)
-                    payload.memo = memo;
-                subtransactions.push(payload);
-            }
-        }
-    }
-    const taxSubtransactions = allocateTax(categoryCalculations, taxMilliunits);
-    subtransactions.push(...taxSubtransactions);
-    return subtransactions;
-}
-function collapseItemsByCategory(categoryGroup) {
-    const subtransactions = [];
-    const items = categoryGroup.items;
-    let currentBatch = [];
-    let currentBatchTotal = 0;
-    for (const item of items) {
-        if (currentBatch.length >= MAX_ITEMS_PER_MEMO) {
-            const memo = buildCollapsedMemo(currentBatch);
-            subtransactions.push({
-                amount: -currentBatchTotal,
-                category_id: categoryGroup.category_id,
-                memo,
-            });
-            currentBatch = [];
-            currentBatchTotal = 0;
-        }
-        const testBatch = [...currentBatch, item];
-        const testMemo = buildCollapsedMemo(testBatch);
-        if (testMemo.length <= MAX_MEMO_LENGTH) {
-            currentBatch.push(item);
-            currentBatchTotal += item.amount_milliunits;
-        }
-        else {
-            if (currentBatch.length > 0) {
-                const memo = buildCollapsedMemo(currentBatch);
-                subtransactions.push({
-                    amount: -currentBatchTotal,
-                    category_id: categoryGroup.category_id,
-                    memo,
-                });
-                currentBatch = [item];
-                currentBatchTotal = item.amount_milliunits;
-            }
-            else {
-                currentBatch = [item];
-                currentBatchTotal = item.amount_milliunits;
-            }
-        }
-    }
-    if (currentBatch.length > 0) {
-        const memo = buildCollapsedMemo(currentBatch);
-        subtransactions.push({
-            amount: -currentBatchTotal,
-            category_id: categoryGroup.category_id,
-            memo,
-        });
-    }
-    return subtransactions;
-}
-function truncateItemName(name, amountSuffix, maxLength) {
-    const ellipsis = '...';
-    const availableForName = maxLength - ellipsis.length - amountSuffix.length;
-    if (availableForName <= 0) {
-        return amountSuffix.substring(0, maxLength);
-    }
-    return name.substring(0, availableForName) + ellipsis + amountSuffix;
-}
-function buildCollapsedMemo(items) {
-    const parts = [];
-    let currentLength = 0;
-    for (let i = 0; i < items.length; i++) {
-        const item = items[i];
-        if (!item)
-            continue;
-        const amount = milliunitsToAmount(item.amount_milliunits);
-        const amountSuffix = ` $${amount.toFixed(2)}`;
-        let itemStr = `${item.name}${amountSuffix}`;
-        const separator = i > 0 ? ', ' : '';
-        if (parts.length === 0 && itemStr.length > MAX_MEMO_LENGTH) {
-            itemStr = truncateItemName(item.name, amountSuffix, MAX_MEMO_LENGTH);
-        }
-        const testLength = currentLength + separator.length + itemStr.length;
-        if (parts.length > 0 && testLength + 4 > MAX_MEMO_LENGTH) {
-            break;
-        }
-        parts.push(itemStr);
-        currentLength = testLength;
-    }
-    let result = parts.join(', ');
-    if (parts.length < items.length) {
-        result += '...';
-    }
-    return result;
-}
-function allocateTax(categoryCalculations, taxMilliunits) {
-    const subtransactions = [];
-    if (taxMilliunits === 0) {
-        return subtransactions;
-    }
-    if (taxMilliunits < 0) {
-        let largestReturnCategory = undefined;
-        let largestReturnAmount = 0;
-        for (const category of categoryCalculations) {
-            const categoryReturnAmount = category.items
-                .filter((item) => item.amount_milliunits < 0)
-                .reduce((sum, item) => sum + Math.abs(item.amount_milliunits), 0);
-            if (categoryReturnAmount > largestReturnAmount) {
-                largestReturnAmount = categoryReturnAmount;
-                largestReturnCategory = category;
-            }
-        }
-        if (!largestReturnCategory) {
-            largestReturnCategory = categoryCalculations[0];
-        }
-        if (largestReturnCategory) {
-            subtransactions.push({
-                amount: -taxMilliunits,
-                category_id: largestReturnCategory.category_id,
-                memo: 'Tax refund',
-            });
-        }
-        return subtransactions;
-    }
-    const positiveCategorySubtotals = categoryCalculations
-        .map((cat) => ({
-        category: cat,
-        positiveSubtotal: cat.items
-            .filter((item) => item.amount_milliunits > 0)
-            .reduce((sum, item) => sum + item.amount_milliunits, 0),
-    }))
-        .filter((x) => x.positiveSubtotal > 0);
-    if (positiveCategorySubtotals.length === 0) {
-        return subtransactions;
-    }
-    const totalPositiveSubtotal = positiveCategorySubtotals.reduce((sum, x) => sum + x.positiveSubtotal, 0);
-    let allocatedTax = 0;
-    const taxAllocations = [];
-    for (let i = 0; i < positiveCategorySubtotals.length; i++) {
-        const entry = positiveCategorySubtotals[i];
-        if (!entry)
-            continue;
-        const { category, positiveSubtotal } = entry;
-        if (i === positiveCategorySubtotals.length - 1) {
-            const taxAmount = taxMilliunits - allocatedTax;
-            if (taxAmount > 0) {
-                taxAllocations.push({ category, taxAmount });
-            }
-        }
-        else {
-            const taxAmount = Math.round((taxMilliunits * positiveSubtotal) / totalPositiveSubtotal);
-            if (taxAmount > 0) {
-                taxAllocations.push({ category, taxAmount });
-                allocatedTax += taxAmount;
-            }
-        }
-    }
-    for (const { category, taxAmount } of taxAllocations) {
-        subtransactions.push({
-            amount: -taxAmount,
-            category_id: category.category_id,
-            memo: `Tax - ${category.category_name ?? 'Uncategorized'}`,
-        });
-    }
-    return subtransactions;
-}
-export async function handleCreateReceiptSplitTransaction(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
-    const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
-    const date = params.date ?? new Date().toISOString().slice(0, 10);
-    const categoryCalculations = params.categories.map((category) => {
-        const items = category.items.map((item) => ({
-            name: item.name,
-            amount_milliunits: amountToMilliunits(item.amount),
-            quantity: item.quantity,
-            memo: item.memo,
-        }));
-        const subtotalMilliunits = items.reduce((sum, item) => sum + item.amount_milliunits, 0);
-        return {
-            category_id: category.category_id,
-            category_name: category.category_name,
-            subtotal_milliunits: subtotalMilliunits,
-            tax_milliunits: 0,
-            items,
-        };
-    });
-    const subtotalMilliunits = categoryCalculations.reduce((sum, category) => sum + category.subtotal_milliunits, 0);
-    const declaredSubtotalMilliunits = params.receipt_subtotal !== undefined ? amountToMilliunits(params.receipt_subtotal) : undefined;
-    if (declaredSubtotalMilliunits !== undefined &&
-        Math.abs(declaredSubtotalMilliunits - subtotalMilliunits) > 1) {
-        throw new Error(`Categorized items subtotal (${milliunitsToAmount(subtotalMilliunits)}) does not match receipt subtotal (${milliunitsToAmount(declaredSubtotalMilliunits)})`);
-    }
-    const taxMilliunits = amountToMilliunits(params.receipt_tax);
-    const totalMilliunits = amountToMilliunits(params.receipt_total);
-    const computedTotal = subtotalMilliunits + taxMilliunits;
-    if (Math.abs(computedTotal - totalMilliunits) > 1) {
-        throw new Error(`Receipt total (${milliunitsToAmount(totalMilliunits)}) does not equal subtotal plus tax (${milliunitsToAmount(computedTotal)})`);
-    }
-    const subtransactions = applySmartCollapseLogic(categoryCalculations, taxMilliunits);
-    if (taxMilliunits > 0) {
-        const positiveSubtotal = categoryCalculations.reduce((sum, cat) => sum + Math.max(0, cat.subtotal_milliunits), 0);
-        if (positiveSubtotal > 0) {
-            let remainingTax = taxMilliunits;
-            const positiveCats = categoryCalculations.filter((cat) => cat.subtotal_milliunits > 0);
-            positiveCats.forEach((cat, index) => {
-                if (index === positiveCats.length - 1) {
-                    cat.tax_milliunits = remainingTax;
-                }
-                else {
-                    const share = Math.round((cat.subtotal_milliunits / positiveSubtotal) * taxMilliunits);
-                    cat.tax_milliunits = share;
-                    remainingTax -= share;
-                }
-            });
-        }
-    }
-    const receiptSummary = {
-        subtotal: milliunitsToAmount(subtotalMilliunits),
-        tax: milliunitsToAmount(taxMilliunits),
-        total: milliunitsToAmount(totalMilliunits),
-        categories: categoryCalculations.map((category) => ({
-            category_id: category.category_id,
-            category_name: category.category_name,
-            items: category.items.map((item) => ({
-                name: item.name,
-                quantity: item.quantity,
-                amount: milliunitsToAmount(item.amount_milliunits),
-                memo: item.memo,
-            })),
-            subtotal: milliunitsToAmount(category.subtotal_milliunits),
-            tax: milliunitsToAmount(category.tax_milliunits),
-            total: milliunitsToAmount(category.subtotal_milliunits + category.tax_milliunits),
-        })),
-    };
-    if (params.dry_run) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format({
-                        dry_run: true,
-                        action: 'create_receipt_split_transaction',
-                        transaction_preview: {
-                            account_id: params.account_id,
-                            payee_name: params.payee_name,
-                            date,
-                            amount: milliunitsToAmount(totalMilliunits),
-                            cleared: params.cleared ?? 'uncleared',
-                        },
-                        receipt_summary: receiptSummary,
-                        subtransactions: subtransactions.map((subtransaction) => ({
-                            amount: milliunitsToAmount(-subtransaction.amount),
-                            category_id: subtransaction.category_id,
-                            memo: subtransaction.memo,
-                        })),
-                    }),
-                },
-            ],
-        };
-    }
-    const createTransactionParams = {
-        budget_id: params.budget_id,
-        account_id: params.account_id,
-        amount: -totalMilliunits,
-        date,
-        payee_name: params.payee_name,
-        memo: params.memo,
-        cleared: params.cleared ?? 'uncleared',
-        flag_color: params.flag_color,
-        subtransactions: subtransactions,
-    };
-    if (params.approved !== undefined) {
-        createTransactionParams.approved = params.approved;
-    }
-    const baseResult = await handleCreateTransaction(ynabAPI, deltaCache, knowledgeStore, createTransactionParams);
-    const firstContent = baseResult.content?.[0];
-    if (!firstContent || firstContent.type !== 'text') {
-        return baseResult;
-    }
-    try {
-        const parsed = JSON.parse(firstContent.text);
-        parsed['receipt_summary'] = receiptSummary;
-        firstContent.text = responseFormatter.format(parsed);
-    }
-    catch {
-    }
-    return baseResult;
-}
-export async function handleUpdateTransaction(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
-    const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
-    try {
-        if (params.dry_run) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: responseFormatter.format({
-                            dry_run: true,
-                            action: 'update_transaction',
-                            request: params,
-                        }),
-                    },
-                ],
-            };
-        }
-        const originalTransactionResponse = await ynabAPI.transactions.getTransactionById(params.budget_id, params.transaction_id);
-        const originalTransaction = ensureTransaction(originalTransactionResponse.data.transaction, 'Original transaction not found');
-        const transactionData = {};
-        if (params.account_id !== undefined) {
-            transactionData.account_id = params.account_id;
-        }
-        if (params.amount !== undefined) {
-            transactionData.amount = params.amount;
-        }
-        if (params.date !== undefined) {
-            transactionData.date = params.date;
-        }
-        if (params.payee_name !== undefined) {
-            transactionData.payee_name = params.payee_name;
-        }
-        if (params.payee_id !== undefined) {
-            transactionData.payee_id = params.payee_id;
-        }
-        if (params.category_id !== undefined) {
-            transactionData.category_id = params.category_id;
-        }
-        if (params.memo !== undefined) {
-            transactionData.memo = params.memo;
-        }
-        if (params.cleared !== undefined) {
-            transactionData.cleared = params.cleared;
-        }
-        if (params.approved !== undefined) {
-            transactionData.approved = params.approved;
-        }
-        if (params.flag_color !== undefined) {
-            transactionData.flag_color = params.flag_color;
-        }
-        const response = await ynabAPI.transactions.updateTransaction(params.budget_id, params.transaction_id, {
-            transaction: transactionData,
-        });
-        const transaction = ensureTransaction(response.data.transaction, 'Transaction update failed');
-        const specificTransactionCacheKey = CacheManager.generateKey('transaction', 'get', params.budget_id, params.transaction_id);
-        cacheManager.delete(specificTransactionCacheKey);
-        const affectedAccountIds = new Set([
-            originalTransaction.account_id,
-            transaction.account_id,
-        ]);
-        if (originalTransaction.transfer_account_id) {
-            affectedAccountIds.add(originalTransaction.transfer_account_id);
-        }
-        if (transaction.transfer_account_id) {
-            affectedAccountIds.add(transaction.transfer_account_id);
-        }
-        const affectedMonths = new Set([
-            toMonthKey(originalTransaction.date),
-            toMonthKey(transaction.date),
-        ]);
-        const originalCategoryIds = collectCategoryIdsFromSources(originalTransaction);
-        const updatedCategoryIds = collectCategoryIdsFromSources(transaction);
-        const affectedCategoryIds = new Set([...originalCategoryIds, ...updatedCategoryIds]);
-        const categoryChanged = !setsEqual(originalCategoryIds, updatedCategoryIds);
-        const amountChanged = transaction.amount !== originalTransaction.amount;
-        const accountChanged = transaction.account_id !== originalTransaction.account_id;
-        const clearedChanged = transaction.cleared !== originalTransaction.cleared;
-        const transferAccountChanged = transaction.transfer_account_id !== originalTransaction.transfer_account_id;
-        const transferLinkChanged = transaction.transfer_transaction_id !== originalTransaction.transfer_transaction_id;
-        const dateChanged = transaction.date !== originalTransaction.date;
-        invalidateTransactionCaches(deltaCache, knowledgeStore, params.budget_id, response.data.server_knowledge, affectedAccountIds, affectedMonths, {
-            affectedCategoryIds,
-            accountTotalsChanged: amountChanged ||
-                accountChanged ||
-                clearedChanged ||
-                transferAccountChanged ||
-                transferLinkChanged,
-            invalidateMonths: amountChanged || categoryChanged || dateChanged,
-        });
-        const accountResponse = await ynabAPI.accounts.getAccountById(params.budget_id, transaction.account_id);
-        const account = accountResponse.data.account;
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format({
-                        transaction: {
-                            id: transaction.id,
-                            date: transaction.date,
-                            amount: milliunitsToAmount(transaction.amount),
-                            memo: transaction.memo,
-                            cleared: transaction.cleared,
-                            approved: transaction.approved,
-                            flag_color: transaction.flag_color,
-                            account_id: transaction.account_id,
-                            payee_id: transaction.payee_id,
-                            category_id: transaction.category_id,
-                            transfer_account_id: transaction.transfer_account_id,
-                            transfer_transaction_id: transaction.transfer_transaction_id,
-                            matched_transaction_id: transaction.matched_transaction_id,
-                            import_id: transaction.import_id,
-                            deleted: transaction.deleted,
-                        },
-                        updated_balance: account.balance,
-                        updated_cleared_balance: account.cleared_balance,
-                    }),
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return handleTransactionError(error, 'Failed to update transaction');
-    }
-}
-export async function handleDeleteTransaction(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
-    const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
-    try {
-        if (params.dry_run) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: responseFormatter.format({
-                            dry_run: true,
-                            action: 'delete_transaction',
-                            request: params,
-                        }),
-                    },
-                ],
-            };
-        }
-        const response = await ynabAPI.transactions.deleteTransaction(params.budget_id, params.transaction_id);
-        const transaction = ensureTransaction(response.data.transaction, 'Transaction deletion failed');
-        const specificTransactionCacheKey = CacheManager.generateKey('transaction', 'get', params.budget_id, params.transaction_id);
-        cacheManager.delete(specificTransactionCacheKey);
-        const affectedAccountIds = new Set([transaction.account_id]);
-        if (transaction.transfer_account_id) {
-            affectedAccountIds.add(transaction.transfer_account_id);
-        }
-        const affectedMonths = new Set([toMonthKey(transaction.date)]);
-        const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
-        invalidateTransactionCaches(deltaCache, knowledgeStore, params.budget_id, response.data.server_knowledge, affectedAccountIds, affectedMonths, {
-            affectedCategoryIds,
-            accountTotalsChanged: true,
-            invalidateMonths: true,
-        });
-        const accountResponse = await ynabAPI.accounts.getAccountById(params.budget_id, transaction.account_id);
-        const account = accountResponse.data.account;
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format({
-                        message: 'Transaction deleted successfully',
-                        transaction: {
-                            id: transaction.id,
-                            deleted: transaction.deleted,
-                        },
-                        updated_balance: account.balance,
-                        updated_cleared_balance: account.cleared_balance,
-                    }),
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return handleTransactionError(error, 'Failed to delete transaction');
-    }
-}
-export async function handleCreateTransactions(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
-    const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
-    return (await withToolErrorHandling(async () => {
-        const validationResult = CreateTransactionsSchema.safeParse(params);
-        if (!validationResult.success) {
-            const issuesByIndex = new Map();
-            const validationIssues = validationResult.error.issues ?? [];
-            for (const issue of validationIssues) {
-                const transactionIndex = issue.path.find((segment) => typeof segment === 'number');
-                const message = issue.message;
-                const issueIndex = transactionIndex !== undefined ? transactionIndex : null;
-                const existing = issuesByIndex.get(issueIndex) ?? [];
-                existing.push(message);
-                issuesByIndex.set(issueIndex, existing);
-            }
-            const details = Array.from(issuesByIndex.entries()).map(([index, errors]) => ({
-                transaction_index: index,
-                errors,
-            }));
-            throw new ValidationError('Bulk transaction validation failed', JSON.stringify(details, null, 2), ['Ensure each transaction includes required fields', 'Limit batches to 100 items']);
-        }
-        const { budget_id, transactions, dry_run } = validationResult.data;
-        const importIdMap = new Map();
-        for (const [index, transaction] of transactions.entries()) {
-            if (transaction.import_id && transaction.import_id.trim().length > 0) {
-                const existing = importIdMap.get(transaction.import_id);
-                if (existing) {
-                    existing.push(index);
-                }
-                else {
-                    importIdMap.set(transaction.import_id, [index]);
-                }
-            }
-        }
-        const duplicates = Array.from(importIdMap.entries())
-            .filter(([, indices]) => indices.length > 1)
-            .map(([importId, indices]) => ({ import_id: importId, indices }));
-        if (duplicates.length > 0) {
-            const details = duplicates.map(({ import_id, indices }) => ({
-                import_id,
-                transaction_indices: indices,
-                count: indices.length,
-            }));
-            throw new ValidationError('Duplicate import_id values detected within batch', JSON.stringify(details, null, 2), [
-                'Ensure each transaction has a unique import_id within the batch',
-                'Remove duplicate import_id values or omit import_id to use hash-based correlation',
-            ]);
-        }
-        if (dry_run) {
-            const totalAmount = transactions.reduce((sum, transaction) => sum + transaction.amount, 0);
-            const accountsAffected = Array.from(new Set(transactions.map((transaction) => transaction.account_id)));
-            const categoriesAffected = Array.from(new Set(transactions
-                .map((transaction) => transaction.category_id)
-                .filter((id) => id !== undefined)));
-            const sortedDates = [...transactions.map((transaction) => transaction.date)].sort();
-            const dateRange = sortedDates.length > 0
-                ? { earliest: sortedDates[0], latest: sortedDates[sortedDates.length - 1] }
-                : undefined;
-            const transactionsPreview = transactions.slice(0, 10).map((transaction, index) => ({
-                request_index: index,
-                account_id: transaction.account_id,
-                date: transaction.date,
-                amount: milliunitsToAmount(transaction.amount),
-                memo: transaction.memo,
-                payee_id: transaction.payee_id,
-                payee_name: transaction.payee_name,
-                category_id: transaction.category_id,
-                import_id: transaction.import_id,
-            }));
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: responseFormatter.format({
-                            dry_run: true,
-                            action: 'create_transactions',
-                            validation: 'passed',
-                            summary: {
-                                total_transactions: transactions.length,
-                                total_amount: milliunitsToAmount(totalAmount),
-                                accounts_affected: accountsAffected,
-                                date_range: dateRange,
-                                categories_affected: categoriesAffected,
-                            },
-                            transactions_preview: transactionsPreview,
-                            note: 'Dry run complete. No transactions created. No caches invalidated. No server_knowledge updated.',
-                        }),
-                    },
-                ],
-            };
-        }
-        const saveTransactions = transactions.map((transaction) => {
-            const payload = {
-                account_id: transaction.account_id,
-                amount: transaction.amount,
-                date: transaction.date,
-            };
-            if (transaction.payee_id !== undefined)
-                payload.payee_id = transaction.payee_id;
-            if (transaction.payee_name !== undefined)
-                payload.payee_name = transaction.payee_name;
-            if (transaction.category_id !== undefined)
-                payload.category_id = transaction.category_id;
-            if (transaction.memo !== undefined)
-                payload.memo = transaction.memo;
-            if (transaction.cleared !== undefined)
-                payload.cleared = transaction.cleared;
-            if (transaction.approved !== undefined)
-                payload.approved = transaction.approved;
-            if (transaction.flag_color !== undefined)
-                payload.flag_color = transaction.flag_color;
-            if (transaction.import_id !== undefined)
-                payload.import_id = transaction.import_id;
-            return payload;
-        });
-        const response = await ynabAPI.transactions.createTransactions(budget_id, {
-            transactions: saveTransactions,
-        });
-        const responseData = response.data;
-        const duplicateImportIds = new Set(responseData.duplicate_import_ids ?? []);
-        const results = correlateResults(transactions, responseData, duplicateImportIds);
-        const summary = {
-            total_requested: transactions.length,
-            created: responseData.transaction_ids?.length ?? 0,
-            duplicates: duplicateImportIds.size,
-            failed: results.filter((result) => result.status === 'failed').length,
-        };
-        const baseResponse = {
-            success: summary.failed === 0,
-            server_knowledge: responseData.server_knowledge,
-            summary,
-            results,
-            transactions: responseData.transactions ?? [],
-            duplicate_import_ids: responseData.duplicate_import_ids ?? [],
-            message: `Processed ${summary.total_requested} transactions: ${summary.created} created, ${summary.duplicates} duplicates, ${summary.failed} failed.`,
-        };
-        const accountIds = new Set(transactions.map((transaction) => transaction.account_id));
-        const affectedMonths = new Set(transactions.map((transaction) => toMonthKey(transaction.date)));
-        const affectedCategoryIds = new Set();
-        for (const created of responseData.transactions ?? []) {
-            appendCategoryIds(created, affectedCategoryIds);
-        }
-        invalidateTransactionCaches(deltaCache, knowledgeStore, budget_id, responseData.server_knowledge, accountIds, affectedMonths, {
-            affectedCategoryIds,
-            accountTotalsChanged: true,
-            invalidateMonths: true,
-        });
-        const finalizedResponse = finalizeResponse(baseResponse);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format(finalizedResponse),
-                },
-            ],
-        };
-    }, 'ynab:create_transactions', 'bulk transaction creation'));
-}
-async function resolveMetadata(ynabAPI, budgetId, transactions, options = {}) {
-    const metadata = new Map();
-    const needsResolution = [];
-    const previewIds = new Set(options.previewTransactionIds ?? []);
-    const previewDetails = new Map();
-    const previewIdsNeedingFetch = new Set(previewIds);
-    for (const transaction of transactions) {
-        if (transaction.original_account_id && transaction.original_date) {
-            metadata.set(transaction.id, {
-                account_id: transaction.original_account_id,
-                date: transaction.original_date,
-            });
-        }
-        else {
-            needsResolution.push(transaction.id);
-        }
-    }
-    if (previewIds.size === 0 && needsResolution.length === 0) {
-        return { metadata, unresolvedIds: [], previewDetails };
-    }
-    const needsResolutionSet = new Set(needsResolution);
-    const cacheLookupIds = new Set([...needsResolution, ...previewIds]);
-    for (const transactionId of cacheLookupIds) {
-        const cacheKey = CacheManager.generateKey('transaction', 'get', budgetId, transactionId);
-        const cached = cacheManager.get(cacheKey);
-        if (!cached) {
-            continue;
-        }
-        if (needsResolutionSet.has(transactionId)) {
-            metadata.set(transactionId, {
-                account_id: cached.account_id,
-                date: cached.date,
-            });
-            needsResolutionSet.delete(transactionId);
-        }
-        if (previewIds.has(transactionId) && !previewDetails.has(transactionId)) {
-            previewDetails.set(transactionId, cached);
-            previewIdsNeedingFetch.delete(transactionId);
-        }
-    }
-    const stillNeedsResolution = Array.from(needsResolutionSet);
-    if (stillNeedsResolution.length === 0 && previewIdsNeedingFetch.size === 0) {
-        return { metadata, unresolvedIds: [], previewDetails };
-    }
-    const MAX_CONCURRENT_FETCHES = 5;
-    const fetchPromises = [];
-    const metadataAwaitingResolution = new Set(stillNeedsResolution);
-    const idsNeedingApiFetch = Array.from(new Set([...stillNeedsResolution, ...previewIdsNeedingFetch]));
-    for (let i = 0; i < idsNeedingApiFetch.length; i += MAX_CONCURRENT_FETCHES) {
-        const batch = idsNeedingApiFetch.slice(i, i + MAX_CONCURRENT_FETCHES);
-        const batchPromises = batch.map(async (transactionId) => {
-            try {
-                const response = await ynabAPI.transactions.getTransactionById(budgetId, transactionId);
-                const transaction = response.data.transaction;
-                if (transaction) {
-                    if (metadataAwaitingResolution.has(transactionId)) {
-                        metadata.set(transactionId, {
-                            account_id: transaction.account_id,
-                            date: transaction.date,
-                        });
-                        metadataAwaitingResolution.delete(transactionId);
-                    }
-                    if (previewIdsNeedingFetch.has(transactionId) && !previewDetails.has(transactionId)) {
-                        previewDetails.set(transactionId, transaction);
-                        previewIdsNeedingFetch.delete(transactionId);
-                    }
-                }
-            }
-            catch {
-                if (metadataAwaitingResolution.has(transactionId)) {
-                    globalRequestLogger.logError('ynab:update_transactions', 'resolve_metadata', { transaction_id: transactionId }, 'Failed to resolve transaction metadata');
-                }
-            }
-        });
-        fetchPromises.push(...batchPromises);
-    }
-    await Promise.all(fetchPromises);
-    return { metadata, unresolvedIds: Array.from(metadataAwaitingResolution), previewDetails };
-}
-export async function handleUpdateTransactions(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams) {
-    const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(deltaCacheOrParams, knowledgeStoreOrParams, maybeParams);
-    return (await withToolErrorHandling(async () => {
-        const validationResult = UpdateTransactionsSchema.safeParse(params);
-        if (!validationResult.success) {
-            const issuesByIndex = new Map();
-            const validationIssues = validationResult.error.issues ?? [];
-            for (const issue of validationIssues) {
-                const transactionIndex = issue.path.find((segment) => typeof segment === 'number');
-                const message = issue.message;
-                const issueIndex = transactionIndex !== undefined ? transactionIndex : null;
-                const existing = issuesByIndex.get(issueIndex) ?? [];
-                existing.push(message);
-                issuesByIndex.set(issueIndex, existing);
-            }
-            const details = Array.from(issuesByIndex.entries()).map(([index, errors]) => ({
-                transaction_index: index,
-                errors,
-            }));
-            throw new ValidationError('Bulk transaction update validation failed', JSON.stringify(details, null, 2), ['Ensure each transaction includes an id field', 'Limit batches to 100 items']);
-        }
-        const { budget_id, transactions, dry_run } = validationResult.data;
-        if (dry_run) {
-            const previewTransactions = transactions.slice(0, 10);
-            const previewTransactionIds = previewTransactions.map((transaction) => transaction.id);
-            const { metadata, unresolvedIds, previewDetails } = await resolveMetadata(ynabAPI, budget_id, transactions, {
-                previewTransactionIds,
-            });
-            const transactionsPreview = [];
-            const unavailablePreviewIds = [];
-            for (const transaction of previewTransactions) {
-                const currentState = previewDetails.get(transaction.id);
-                if (!currentState) {
-                    unavailablePreviewIds.push(transaction.id);
-                    transactionsPreview.push({
-                        transaction_id: transaction.id,
-                        before: 'unavailable',
-                        after: transaction,
-                    });
-                    continue;
-                }
-                const before = {};
-                const after = {};
-                if (transaction.amount !== undefined && transaction.amount !== currentState.amount) {
-                    before['amount'] = milliunitsToAmount(currentState.amount);
-                    after['amount'] = milliunitsToAmount(transaction.amount);
-                }
-                if (transaction.date !== undefined && transaction.date !== currentState.date) {
-                    before['date'] = currentState.date;
-                    after['date'] = transaction.date;
-                }
-                if (transaction.memo !== undefined && transaction.memo !== currentState.memo) {
-                    before['memo'] = currentState.memo;
-                    after['memo'] = transaction.memo;
-                }
-                if (transaction.payee_id !== undefined &&
-                    transaction.payee_id !== currentState.payee_id) {
-                    before['payee_id'] = currentState.payee_id;
-                    after['payee_id'] = transaction.payee_id;
-                }
-                if (transaction.payee_name !== undefined &&
-                    transaction.payee_name !== currentState.payee_name) {
-                    before['payee_name'] = currentState.payee_name;
-                    after['payee_name'] = transaction.payee_name;
-                }
-                if (transaction.category_id !== undefined &&
-                    transaction.category_id !== currentState.category_id) {
-                    before['category_id'] = currentState.category_id;
-                    after['category_id'] = transaction.category_id;
-                }
-                if (transaction.cleared !== undefined && transaction.cleared !== currentState.cleared) {
-                    before['cleared'] = currentState.cleared;
-                    after['cleared'] = transaction.cleared;
-                }
-                if (transaction.approved !== undefined &&
-                    transaction.approved !== currentState.approved) {
-                    before['approved'] = currentState.approved;
-                    after['approved'] = transaction.approved;
-                }
-                if (transaction.flag_color !== undefined &&
-                    transaction.flag_color !== currentState.flag_color) {
-                    before['flag_color'] = currentState.flag_color;
-                    after['flag_color'] = transaction.flag_color;
-                }
-                transactionsPreview.push({
-                    transaction_id: transaction.id,
-                    before,
-                    after,
-                });
-            }
-            const warnings = [];
-            if (unavailablePreviewIds.length > 0 || unresolvedIds.length > 0) {
-                const totalMissing = Math.max(unavailablePreviewIds.length, unresolvedIds.length);
-                const sampleIds = unresolvedIds.length > 0
-                    ? unresolvedIds.slice(0, 10)
-                    : unavailablePreviewIds.slice(0, 10);
-                warnings.push({
-                    code: 'metadata_unavailable',
-                    count: totalMissing,
-                    message: `Unable to fetch prior state for ${totalMissing} transactions`,
-                    sample_ids: sampleIds,
-                });
-            }
-            const accountsAffected = Array.from(new Set(Array.from(metadata.values()).map((m) => m.account_id)));
-            const fieldsToUpdate = new Set();
-            for (const transaction of transactions) {
-                if (transaction.amount !== undefined)
-                    fieldsToUpdate.add('amount');
-                if (transaction.date !== undefined)
-                    fieldsToUpdate.add('date');
-                if (transaction.memo !== undefined)
-                    fieldsToUpdate.add('memo');
-                if (transaction.payee_id !== undefined)
-                    fieldsToUpdate.add('payee_id');
-                if (transaction.payee_name !== undefined)
-                    fieldsToUpdate.add('payee_name');
-                if (transaction.category_id !== undefined)
-                    fieldsToUpdate.add('category_id');
-                if (transaction.cleared !== undefined)
-                    fieldsToUpdate.add('cleared');
-                if (transaction.approved !== undefined)
-                    fieldsToUpdate.add('approved');
-                if (transaction.flag_color !== undefined)
-                    fieldsToUpdate.add('flag_color');
-            }
-            const response = {
-                dry_run: true,
-                action: 'update_transactions',
-                validation: 'passed',
-                summary: {
-                    total_transactions: transactions.length,
-                    accounts_affected: accountsAffected,
-                    fields_to_update: Array.from(fieldsToUpdate),
-                },
-                transactions_preview: transactionsPreview,
-                note: 'Dry run complete. No transactions updated. No caches invalidated. No server_knowledge updated.',
-            };
-            if (warnings.length > 0) {
-                response['warnings'] = warnings;
-            }
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: responseFormatter.format(response),
-                    },
-                ],
-            };
-        }
-        const { metadata, unresolvedIds } = await resolveMetadata(ynabAPI, budget_id, transactions);
-        const missingMetadataRatio = unresolvedIds.length / transactions.length;
-        const METADATA_THRESHOLD = 0.05;
-        if (missingMetadataRatio > METADATA_THRESHOLD) {
-            throw new ValidationError(`METADATA_INCOMPLETE: ${(missingMetadataRatio * 100).toFixed(1)}% of transactions have missing metadata (threshold: ${(METADATA_THRESHOLD * 100).toFixed(0)}%)`, JSON.stringify({
-                unresolved_count: unresolvedIds.length,
-                total_transactions: transactions.length,
-                ratio: (missingMetadataRatio * 100).toFixed(1) + '%',
-                threshold: (METADATA_THRESHOLD * 100).toFixed(0) + '%',
-                sample_unresolved_ids: unresolvedIds.slice(0, 5),
-            }, null, 2), [
-                'Provide original_account_id and original_date for all transactions being updated',
-                'Ensure transactions exist in YNAB before updating them',
-            ]);
-        }
-        if (missingMetadataRatio > 0.01) {
-            globalRequestLogger.logRequest('ynab:update_transactions', 'metadata_resolution_warning', {
-                unresolved_count: unresolvedIds.length,
-                total_transactions: transactions.length,
-                ratio: missingMetadataRatio.toFixed(3),
-                sample_ids: unresolvedIds.slice(0, 5),
-                message: 'Metadata resolution incomplete for some transactions',
-            }, true);
-        }
-        const updateTransactions = transactions.map((transaction) => {
-            const transactionData = {};
-            if (transaction.amount !== undefined) {
-                transactionData.amount = transaction.amount;
-            }
-            if (transaction.date !== undefined) {
-                transactionData.date = transaction.date;
-            }
-            if (transaction.payee_name !== undefined) {
-                transactionData.payee_name = transaction.payee_name;
-            }
-            if (transaction.payee_id !== undefined) {
-                transactionData.payee_id = transaction.payee_id;
-            }
-            if (transaction.category_id !== undefined) {
-                transactionData.category_id = transaction.category_id;
-            }
-            if (transaction.memo !== undefined) {
-                transactionData.memo = transaction.memo;
-            }
-            if (transaction.cleared !== undefined) {
-                transactionData.cleared = transaction.cleared;
-            }
-            if (transaction.approved !== undefined) {
-                transactionData.approved = transaction.approved;
-            }
-            if (transaction.flag_color !== undefined) {
-                transactionData.flag_color = transaction.flag_color;
-            }
-            return {
-                id: transaction.id,
-                transaction: transactionData,
-            };
-        });
-        const response = await ynabAPI.transactions.updateTransactions(budget_id, {
-            transactions: updateTransactions,
-        });
-        const responseData = response.data;
-        const updatedTransactions = responseData.transactions ?? [];
-        const results = [];
-        const updatedIds = new Set(updatedTransactions.map((t) => t.id));
-        for (const [index, transaction] of transactions.entries()) {
-            if (updatedIds.has(transaction.id)) {
-                results.push({
-                    request_index: index,
-                    status: 'updated',
-                    transaction_id: transaction.id,
-                    correlation_key: transaction.id,
-                });
-            }
-            else {
-                results.push({
-                    request_index: index,
-                    status: 'failed',
-                    transaction_id: transaction.id,
-                    correlation_key: transaction.id,
-                    error_code: 'update_failed',
-                    error: 'Transaction was not updated by YNAB API',
-                });
-            }
-        }
-        const summary = {
-            total_requested: transactions.length,
-            updated: updatedTransactions.length,
-            failed: results.filter((r) => r.status === 'failed').length,
-        };
-        const baseResponse = {
-            success: summary.failed === 0,
-            server_knowledge: responseData.server_knowledge,
-            summary,
-            results,
-            transactions: updatedTransactions,
-            message: `Processed ${summary.total_requested} transactions: ${summary.updated} updated, ${summary.failed} failed.`,
-        };
-        for (const transaction of transactions) {
-            cacheManager.delete(CacheManager.generateKey('transaction', 'get', budget_id, transaction.id));
-        }
-        const affectedAccountIds = new Set();
-        const affectedMonthKeys = new Set();
-        const affectedCategoryIds = new Set();
-        let invalidateAllCategories = false;
-        let accountTotalsChanged = false;
-        let monthsImpacted = false;
-        for (const transaction of transactions) {
-            const meta = metadata.get(transaction.id);
-            const amountChanged = transaction.amount !== undefined;
-            const clearedChanged = transaction.cleared !== undefined;
-            const categoryChanged = transaction.category_id !== undefined;
-            const dateChanged = transaction.date !== undefined;
-            if ((amountChanged || clearedChanged) && meta) {
-                affectedAccountIds.add(meta.account_id);
-            }
-            if (amountChanged) {
-                monthsImpacted = true;
-                accountTotalsChanged = true;
-                invalidateAllCategories = true;
-                if (meta) {
-                    affectedMonthKeys.add(toMonthKey(meta.date));
-                }
-            }
-            if (categoryChanged) {
-                monthsImpacted = true;
-                invalidateAllCategories = true;
-                if (transaction.category_id) {
-                    affectedCategoryIds.add(transaction.category_id);
-                }
-                if (meta) {
-                    affectedMonthKeys.add(toMonthKey(meta.date));
-                }
-            }
-            if (dateChanged && meta) {
-                monthsImpacted = true;
-                affectedMonthKeys.add(toMonthKey(meta.date));
-            }
-            if (dateChanged && transaction.date) {
-                affectedMonthKeys.add(toMonthKey(transaction.date));
-            }
-        }
-        invalidateTransactionCaches(deltaCache, knowledgeStore, budget_id, responseData.server_knowledge, affectedAccountIds, affectedMonthKeys, {
-            affectedCategoryIds,
-            invalidateAllCategories,
-            accountTotalsChanged,
-            invalidateMonths: monthsImpacted,
-        });
-        const finalizedResponse = finalizeBulkUpdateResponse(baseResponse);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: responseFormatter.format(finalizedResponse),
-                },
-            ],
-        };
-    }, 'ynab:update_transactions', 'bulk transaction update'));
-}
+import { handleGetTransaction, handleListTransactions, registerTransactionReadTools, } from "./transactionReadTools.js";
+import { handleCreateReceiptSplitTransaction, handleCreateTransaction, handleCreateTransactions, handleDeleteTransaction, handleUpdateTransaction, handleUpdateTransactions, registerTransactionWriteTools, } from "./transactionWriteTools.js";
 export const registerTransactionTools = (registry, context) => {
-    const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
-    const budgetResolver = createBudgetResolver(context);
-    registry.register({
-        name: 'list_transactions',
-        description: 'List transactions for a budget with optional filtering',
-        inputSchema: ListTransactionsSchema,
-        handler: adaptWithDelta(handleListTransactions),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-                title: 'YNAB: List Transactions',
-            },
-        },
-    });
-    registry.register({
-        name: 'export_transactions',
-        description: 'Export all transactions to a JSON file with descriptive filename',
-        inputSchema: ExportTransactionsSchema,
-        handler: adapt(handleExportTransactions),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-                title: 'YNAB: Export Transactions',
-            },
-        },
-    });
-    registry.register({
-        name: 'get_transaction',
-        description: 'Get detailed information for a specific transaction',
-        inputSchema: GetTransactionSchema,
-        handler: adapt(handleGetTransaction),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-                title: 'YNAB: Get Transaction Details',
-            },
-        },
-    });
-    registry.register({
-        name: 'create_transaction',
-        description: 'Create a new transaction in the specified budget and account',
-        inputSchema: CreateTransactionSchema,
-        handler: adaptWrite(handleCreateTransaction),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-                title: 'YNAB: Create Transaction',
-            },
-        },
-    });
-    registry.register({
-        name: 'create_transactions',
-        description: 'Create multiple transactions in a single batch (1-100 items) with duplicate detection, dry-run validation, and automatic response size management with correlation metadata.',
-        inputSchema: CreateTransactionsSchema,
-        handler: adaptWrite(handleCreateTransactions),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-                title: 'YNAB: Create Multiple Transactions',
-            },
-        },
-    });
-    registry.register({
-        name: 'create_receipt_split_transaction',
-        description: 'Create a split transaction from receipt items with proportional tax allocation',
-        inputSchema: CreateReceiptSplitTransactionSchema,
-        handler: adaptWrite(handleCreateReceiptSplitTransaction),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-                title: 'YNAB: Create Split Transaction from Receipt',
-            },
-        },
-    });
-    registry.register({
-        name: 'update_transaction',
-        description: 'Update an existing transaction',
-        inputSchema: UpdateTransactionSchema,
-        handler: adaptWrite(handleUpdateTransaction),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
-                title: 'YNAB: Update Transaction',
-            },
-        },
-    });
-    registry.register({
-        name: 'update_transactions',
-        description: 'Update multiple transactions in a single batch (1-100 items) with dry-run validation, automatic cache invalidation, and response size management. Supports optional original_account_id and original_date metadata for efficient cache invalidation.',
-        inputSchema: UpdateTransactionsSchema,
-        handler: adaptWrite(handleUpdateTransactions),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
-                title: 'YNAB: Update Multiple Transactions',
-            },
-        },
-    });
-    registry.register({
-        name: 'delete_transaction',
-        description: 'Delete a transaction from the specified budget',
-        inputSchema: DeleteTransactionSchema,
-        handler: adaptWrite(handleDeleteTransaction),
-        defaultArgumentResolver: budgetResolver(),
-        metadata: {
-            annotations: {
-                ...ToolAnnotationPresets.WRITE_EXTERNAL_DELETE,
-                title: 'YNAB: Delete Transaction',
-            },
-        },
-    });
+    registerTransactionReadTools(registry, context);
+    registerTransactionWriteTools(registry, context);
 };
-export { ListTransactionsSchema, GetTransactionSchema, CreateTransactionSchema, CreateTransactionsSchema, CreateReceiptSplitTransactionSchema, UpdateTransactionSchema, UpdateTransactionsSchema, DeleteTransactionSchema, } from './transactionSchemas.js';
-export { generateCorrelationKey, toCorrelationPayload, correlateResults, estimatePayloadSize, finalizeResponse, finalizeBulkUpdateResponse, handleTransactionError, toMonthKey, ensureTransaction, appendCategoryIds, collectCategoryIdsFromSources, setsEqual, invalidateTransactionCaches, } from './transactionUtils.js';
+export { handleListTransactions, handleGetTransaction, handleCreateTransaction, handleCreateReceiptSplitTransaction, handleUpdateTransaction, handleDeleteTransaction, handleCreateTransactions, handleUpdateTransactions, };
+export { ListTransactionsSchema, GetTransactionSchema, CreateTransactionSchema, CreateTransactionsSchema, CreateReceiptSplitTransactionSchema, UpdateTransactionSchema, UpdateTransactionsSchema, DeleteTransactionSchema, } from "./transactionSchemas.js";
+export { generateCorrelationKey, toCorrelationPayload, correlateResults, estimatePayloadSize, finalizeResponse, finalizeBulkUpdateResponse, handleTransactionError, toMonthKey, ensureTransaction, appendCategoryIds, collectCategoryIdsFromSources, setsEqual, invalidateTransactionCaches, } from "./transactionUtils.js";