@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/dist/tools/transactionWriteTools.js

@@ -0,0 +1,1342 @@
+import { CacheManager, cacheManager } from "../server/cacheManager.js";
+import { globalRequestLogger } from "../server/requestLogger.js";
+import { responseFormatter } from "../server/responseFormatter.js";
+import { ValidationError, withToolErrorHandling } from "../types/index.js";
+import { amountToMilliunits, milliunitsToAmount, } from "../utils/amountUtils.js";
+import { createAdapters, createBudgetResolver } from "./adapters.js";
+import { resolveDeltaWriteArgs } from "./deltaSupport.js";
+import { ToolAnnotationPresets } from "./toolCategories.js";
+import { CreateReceiptSplitTransactionSchema, CreateTransactionSchema, CreateTransactionsSchema, DeleteTransactionSchema, UpdateTransactionSchema, UpdateTransactionsSchema, } from "./transactionSchemas.js";
+import { appendCategoryIds, collectCategoryIdsFromSources, correlateResults, ensureTransaction, finalizeBulkUpdateResponse, finalizeResponse, handleTransactionError, invalidateTransactionCaches, setsEqual, toMonthKey, } from "./transactionUtils.js";
+export async function handleCreateTransaction(ynabAPI, deltaCacheOrParams, knowledgeStoreOrParams, maybeParams, _errorHandler) {
+    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, _errorHandler) {
+    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, _errorHandler) {
+    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, _errorHandler) {
+    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, errorHandler) {
+    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", errorHandler));
+}
+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, errorHandler) {
+    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", errorHandler));
+}
+export function registerTransactionWriteTools(registry, context) {
+    const { adaptWrite } = createAdapters(context);
+    const budgetResolver = createBudgetResolver(context);
+    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",
+            },
+        },
+    });
+}