@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/transactionTools.js

@@ -0,0 +1,1722 @@
+import { z } from 'zod/v4';
+import { createHash } from 'crypto';
+import { ValidationError, withToolErrorHandling } from '../types/index.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';
+function ensureTransaction(transaction, errorMessage) {
+    if (!transaction) {
+        throw new Error(errorMessage);
+    }
+    return transaction;
+}
+const toMonthKey = (date) => `${date.slice(0, 7)}-01`;
+function appendCategoryIds(source, target) {
+    if (!source) {
+        return;
+    }
+    if (source.category_id) {
+        target.add(source.category_id);
+    }
+    if (Array.isArray(source.subtransactions)) {
+        for (const sub of source.subtransactions) {
+            if (sub?.category_id) {
+                target.add(sub.category_id);
+            }
+        }
+    }
+}
+function collectCategoryIdsFromSources(...sources) {
+    const result = new Set();
+    for (const source of sources) {
+        appendCategoryIds(source, result);
+    }
+    return result;
+}
+function setsEqual(a, b) {
+    if (a.size !== b.size) {
+        return false;
+    }
+    for (const value of a) {
+        if (!b.has(value)) {
+            return false;
+        }
+    }
+    return true;
+}
+function invalidateTransactionCaches(deltaCache, knowledgeStore, budgetId, serverKnowledge, affectedAccountIds, affectedMonths, options = {}) {
+    deltaCache.invalidate(budgetId, 'transactions');
+    cacheManager.delete(CacheManager.generateKey('transactions', 'list', budgetId));
+    for (const accountId of affectedAccountIds) {
+        const accountPrefix = CacheManager.generateKey('transactions', 'account', budgetId, accountId);
+        cacheManager.deleteByPrefix(accountPrefix);
+    }
+    const invalidateAccountsList = options.accountTotalsChanged ?? true;
+    if (invalidateAccountsList) {
+        cacheManager.delete(CacheManager.generateKey('accounts', 'list', budgetId));
+    }
+    for (const accountId of affectedAccountIds) {
+        cacheManager.delete(CacheManager.generateKey('account', 'get', budgetId, accountId));
+    }
+    const affectedCategoryIds = options.affectedCategoryIds ?? new Set();
+    const shouldInvalidateCategories = options.invalidateAllCategories || affectedCategoryIds.size > 0;
+    if (shouldInvalidateCategories) {
+        cacheManager.delete(CacheManager.generateKey('categories', 'list', budgetId));
+        for (const categoryId of affectedCategoryIds) {
+            cacheManager.delete(CacheManager.generateKey('category', 'get', budgetId, categoryId));
+        }
+    }
+    const shouldInvalidateMonths = options.invalidateMonths ?? affectedMonths.size > 0;
+    if (shouldInvalidateMonths) {
+        cacheManager.delete(CacheManager.generateKey('months', 'list', budgetId));
+        deltaCache.invalidate(budgetId, 'months');
+        for (const month of affectedMonths) {
+            cacheManager.delete(CacheManager.generateKey('month', 'get', budgetId, month));
+        }
+    }
+    if (serverKnowledge !== undefined) {
+        const transactionCacheKey = CacheManager.generateKey('transactions', 'list', budgetId);
+        knowledgeStore.update(transactionCacheKey, serverKnowledge);
+        if (invalidateAccountsList) {
+            const accountsCacheKey = CacheManager.generateKey('accounts', 'list', budgetId);
+            knowledgeStore.update(accountsCacheKey, serverKnowledge);
+        }
+        if (shouldInvalidateMonths && affectedMonths.size > 0) {
+            const monthsCacheKey = CacheManager.generateKey('months', 'list', budgetId);
+            knowledgeStore.update(monthsCacheKey, serverKnowledge);
+        }
+    }
+}
+export const ListTransactionsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().optional(),
+    category_id: z.string().optional(),
+    since_date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    type: z.enum(['uncategorized', 'unapproved']).optional(),
+})
+    .strict();
+export const GetTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transaction_id: z.string().min(1, 'Transaction ID is required'),
+})
+    .strict();
+export const CreateTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+    amount: z.number().int('Amount must be an integer in milliunits'),
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)'),
+    payee_name: z.string().optional(),
+    payee_id: z.string().optional(),
+    category_id: z.string().optional(),
+    memo: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    import_id: z.string().min(1, 'Import ID cannot be empty').optional(),
+    dry_run: z.boolean().optional(),
+    subtransactions: z
+        .array(z
+        .object({
+        amount: z.number().int('Subtransaction amount must be an integer in milliunits'),
+        payee_name: z.string().optional(),
+        payee_id: z.string().optional(),
+        category_id: z.string().optional(),
+        memo: z.string().optional(),
+    })
+        .strict())
+        .min(1, 'At least one subtransaction is required when provided')
+        .optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    if (data.subtransactions && data.subtransactions.length > 0) {
+        const total = data.subtransactions.reduce((sum, sub) => sum + sub.amount, 0);
+        if (total !== data.amount) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'Amount must equal the sum of subtransaction amounts',
+                path: ['amount'],
+            });
+        }
+    }
+});
+const BulkTransactionInputSchemaBase = CreateTransactionSchema.pick({
+    account_id: true,
+    amount: true,
+    date: true,
+    payee_name: true,
+    payee_id: true,
+    category_id: true,
+    memo: true,
+    cleared: true,
+    approved: true,
+    flag_color: true,
+    import_id: true,
+});
+const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.extend({
+    subtransactions: z.any().optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    if (data.subtransactions !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Subtransactions are not supported in bulk transaction creation',
+            path: ['subtransactions'],
+        });
+    }
+})
+    .transform((data) => {
+    const { subtransactions, ...rest } = data;
+    return rest;
+});
+export const CreateTransactionsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transactions: z
+        .array(BulkTransactionInputSchema)
+        .min(1, 'At least one transaction is required')
+        .max(100, 'A maximum of 100 transactions may be created at once'),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+const FULL_RESPONSE_THRESHOLD = 64 * 1024;
+const SUMMARY_RESPONSE_THRESHOLD = 96 * 1024;
+const MAX_RESPONSE_BYTES = 100 * 1024;
+export function generateCorrelationKey(transaction) {
+    if (transaction.import_id) {
+        return transaction.import_id;
+    }
+    const segments = [
+        `account:${transaction.account_id ?? ''}`,
+        `date:${transaction.date ?? ''}`,
+        `amount:${transaction.amount ?? 0}`,
+        `payee:${transaction.payee_id ?? transaction.payee_name ?? ''}`,
+        `category:${transaction.category_id ?? ''}`,
+        `memo:${transaction.memo ?? ''}`,
+        `cleared:${transaction.cleared ?? ''}`,
+        `approved:${transaction.approved ?? false}`,
+        `flag:${transaction.flag_color ?? ''}`,
+    ];
+    const normalized = segments.join('|');
+    const hash = createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+    return `hash:${hash}`;
+}
+export function toCorrelationPayload(transaction) {
+    const payload = {};
+    if (transaction.account_id !== undefined) {
+        payload.account_id = transaction.account_id;
+    }
+    if (transaction.date !== undefined) {
+        payload.date = transaction.date;
+    }
+    if (transaction.amount !== undefined) {
+        payload.amount = transaction.amount;
+    }
+    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;
+    }
+    payload.payee_id = transaction.payee_id ?? null;
+    payload.payee_name = transaction.payee_name ?? null;
+    payload.category_id = transaction.category_id ?? null;
+    payload.memo = transaction.memo ?? null;
+    payload.import_id = transaction.import_id ?? null;
+    return payload;
+}
+export function correlateResults(requests, responseData, duplicateImportIds) {
+    const createdByImportId = new Map();
+    const createdByHash = new Map();
+    const responseTransactions = responseData.transactions ?? [];
+    const register = (map, key, transactionId) => {
+        const existing = map.get(key);
+        if (existing) {
+            existing.push(transactionId);
+            return;
+        }
+        map.set(key, [transactionId]);
+    };
+    for (const transaction of responseTransactions) {
+        if (!transaction.id) {
+            continue;
+        }
+        const key = generateCorrelationKey(transaction);
+        if (key.startsWith('hash:')) {
+            register(createdByHash, key, transaction.id);
+        }
+        else {
+            register(createdByImportId, key, transaction.id);
+        }
+    }
+    const popId = (map, key) => {
+        const bucket = map.get(key);
+        if (!bucket || bucket.length === 0) {
+            return undefined;
+        }
+        const [transactionId] = bucket.splice(0, 1);
+        if (bucket.length === 0) {
+            map.delete(key);
+        }
+        return transactionId;
+    };
+    const correlatedResults = [];
+    for (const [index, transaction] of requests.entries()) {
+        const normalizedRequest = toCorrelationPayload(transaction);
+        const correlationKey = generateCorrelationKey(normalizedRequest);
+        if (transaction.import_id && duplicateImportIds.has(transaction.import_id)) {
+            correlatedResults.push({
+                request_index: index,
+                status: 'duplicate',
+                correlation_key: correlationKey,
+            });
+            continue;
+        }
+        let transactionId;
+        if (correlationKey.startsWith('hash:')) {
+            transactionId = popId(createdByHash, correlationKey);
+        }
+        else {
+            transactionId = popId(createdByImportId, correlationKey);
+        }
+        if (!transactionId && !correlationKey.startsWith('hash:')) {
+            const hashKey = generateCorrelationKey(toCorrelationPayload({ ...transaction, import_id: undefined }));
+            transactionId = popId(createdByHash, hashKey);
+        }
+        if (transactionId) {
+            const successResult = {
+                request_index: index,
+                status: 'created',
+                correlation_key: correlationKey,
+            };
+            successResult.transaction_id = transactionId;
+            correlatedResults.push(successResult);
+            continue;
+        }
+        globalRequestLogger.logError('ynab:create_transactions', 'correlate_results', {
+            request_index: index,
+            correlation_key: correlationKey,
+            request: {
+                account_id: transaction.account_id,
+                date: transaction.date,
+                amount: transaction.amount,
+                import_id: transaction.import_id,
+            },
+        }, 'correlation_failed');
+        correlatedResults.push({
+            request_index: index,
+            status: 'failed',
+            correlation_key: correlationKey,
+            error_code: 'correlation_failed',
+            error: 'Unable to correlate request transaction with YNAB response',
+        });
+    }
+    return correlatedResults;
+}
+function estimatePayloadSize(payload) {
+    return Buffer.byteLength(JSON.stringify(payload), 'utf8');
+}
+function finalizeResponse(response) {
+    const appendMessage = (message, addition) => {
+        if (!message) {
+            return addition;
+        }
+        if (message.includes(addition)) {
+            return message;
+        }
+        return `${message} ${addition}`;
+    };
+    const fullSize = estimatePayloadSize({ ...response, mode: 'full' });
+    if (fullSize <= FULL_RESPONSE_THRESHOLD) {
+        return { ...response, mode: 'full' };
+    }
+    const { transactions, ...summaryResponse } = response;
+    const summaryPayload = {
+        ...summaryResponse,
+        message: appendMessage(response.message, 'Response downgraded to summary to stay under size limits.'),
+        mode: 'summary',
+    };
+    if (estimatePayloadSize(summaryPayload) <= SUMMARY_RESPONSE_THRESHOLD) {
+        return summaryPayload;
+    }
+    const idsOnlyPayload = {
+        ...summaryPayload,
+        results: summaryResponse.results.map((result) => ({
+            request_index: result.request_index,
+            status: result.status,
+            transaction_id: result.transaction_id,
+            correlation_key: result.correlation_key,
+            error: result.error,
+        })),
+        message: appendMessage(summaryResponse.message, 'Response downgraded to ids_only to meet 100KB limit.'),
+        mode: 'ids_only',
+    };
+    if (estimatePayloadSize(idsOnlyPayload) <= MAX_RESPONSE_BYTES) {
+        return idsOnlyPayload;
+    }
+    throw new ValidationError('RESPONSE_TOO_LARGE: Unable to format bulk create response within 100KB limit', `Batch size: ${response.summary.total_requested} transactions`, ['Reduce the batch size and retry', 'Consider splitting into multiple smaller batches']);
+}
+const ReceiptSplitItemSchema = z
+    .object({
+    name: z.string().min(1, 'Item name is required'),
+    amount: z
+        .number()
+        .finite('Item amount must be a finite number')
+        .refine((value) => value >= 0, 'Item amount must be zero or greater'),
+    quantity: z
+        .number()
+        .finite('Quantity must be a finite number')
+        .positive('Quantity must be greater than zero')
+        .optional(),
+    memo: z.string().optional(),
+})
+    .strict();
+const ReceiptSplitCategorySchema = z
+    .object({
+    category_id: z.string().min(1, 'Category ID is required'),
+    category_name: z.string().optional(),
+    items: z.array(ReceiptSplitItemSchema).min(1, 'Each category must include at least one item'),
+})
+    .strict();
+export const CreateReceiptSplitTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    account_id: z.string().min(1, 'Account ID is required'),
+    payee_name: z.string().min(1, 'Payee name is required'),
+    date: z
+        .string()
+        .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    memo: z.string().optional(),
+    receipt_subtotal: z
+        .number()
+        .finite('Receipt subtotal must be a finite number')
+        .refine((value) => value >= 0, 'Receipt subtotal must be zero or greater')
+        .optional(),
+    receipt_tax: z
+        .number()
+        .finite('Receipt tax must be a finite number')
+        .refine((value) => value >= 0, 'Receipt tax must be zero or greater'),
+    receipt_total: z
+        .number()
+        .finite('Receipt total must be a finite number')
+        .refine((value) => value > 0, 'Receipt total must be greater than zero'),
+    categories: z
+        .array(ReceiptSplitCategorySchema)
+        .min(1, 'At least one categorized group is required to create a split transaction'),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    dry_run: z.boolean().optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    const itemsSubtotal = data.categories
+        .flatMap((category) => category.items)
+        .reduce((sum, item) => sum + item.amount, 0);
+    if (data.receipt_subtotal !== undefined) {
+        const delta = Math.abs(data.receipt_subtotal - itemsSubtotal);
+        if (delta > 0.01) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Receipt subtotal (${data.receipt_subtotal.toFixed(2)}) does not match categorized items total (${itemsSubtotal.toFixed(2)})`,
+                path: ['receipt_subtotal'],
+            });
+        }
+    }
+    const expectedTotal = itemsSubtotal + data.receipt_tax;
+    const deltaTotal = Math.abs(expectedTotal - data.receipt_total);
+    if (deltaTotal > 0.01) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Receipt total (${data.receipt_total.toFixed(2)}) does not match subtotal plus tax (${expectedTotal.toFixed(2)})`,
+            path: ['receipt_total'],
+        });
+    }
+});
+export const UpdateTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transaction_id: z.string().min(1, 'Transaction ID is required'),
+    account_id: z.string().optional(),
+    amount: z.number().int('Amount must be an integer in milliunits').optional(),
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    payee_name: z.string().optional(),
+    payee_id: z.string().optional(),
+    category_id: z.string().optional(),
+    memo: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+const BulkUpdateTransactionInputSchema = z
+    .object({
+    id: z.string().min(1, 'Transaction ID is required'),
+    amount: z.number().int('Amount must be an integer in milliunits').optional(),
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+    payee_name: z.string().optional(),
+    payee_id: z.string().optional(),
+    category_id: z.string().optional(),
+    memo: z.string().optional(),
+    cleared: z.enum(['cleared', 'uncleared', 'reconciled']).optional(),
+    approved: z.boolean().optional(),
+    flag_color: z.enum(['red', 'orange', 'yellow', 'green', 'blue', 'purple']).optional(),
+    original_account_id: z.string().optional(),
+    original_date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in ISO format (YYYY-MM-DD)')
+        .optional(),
+})
+    .strict();
+export const UpdateTransactionsSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transactions: z
+        .array(BulkUpdateTransactionInputSchema)
+        .min(1, 'At least one transaction is required')
+        .max(100, 'A maximum of 100 transactions may be updated at once'),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+export const DeleteTransactionSchema = z
+    .object({
+    budget_id: z.string().min(1, 'Budget ID is required'),
+    transaction_id: z.string().min(1, 'Transaction ID is required'),
+    dry_run: z.boolean().optional(),
+})
+    .strict();
+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 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),
+                            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');
+    }
+}
+function buildItemMemo(item) {
+    const quantitySuffix = item.quantity ? ` (x${item.quantity})` : '';
+    if (item.memo && item.memo.trim().length > 0) {
+        return `${item.name}${quantitySuffix} - ${item.memo}`;
+    }
+    if (quantitySuffix) {
+        return `${item.name}${quantitySuffix}`;
+    }
+    return item.name;
+}
+function distributeTaxProportionally(subtotalMilliunits, totalTaxMilliunits, categories) {
+    if (totalTaxMilliunits === 0) {
+        for (const category of categories)
+            category.tax_milliunits = 0;
+        return;
+    }
+    if (subtotalMilliunits <= 0) {
+        throw new Error('Receipt subtotal must be greater than zero to distribute tax');
+    }
+    let allocated = 0;
+    categories.forEach((category, index) => {
+        if (index === categories.length - 1) {
+            category.tax_milliunits = totalTaxMilliunits - allocated;
+        }
+        else {
+            const proportionalTax = Math.round((totalTaxMilliunits * category.subtotal_milliunits) / subtotalMilliunits);
+            category.tax_milliunits = proportionalTax;
+            allocated += proportionalTax;
+        }
+    });
+}
+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)})`);
+    }
+    distributeTaxProportionally(subtotalMilliunits, taxMilliunits, categoryCalculations);
+    const subtransactions = categoryCalculations.flatMap((category) => {
+        const itemSubtransactions = category.items.map((item) => {
+            const memo = buildItemMemo({ name: item.name, quantity: item.quantity, memo: item.memo });
+            const payload = {
+                amount: -item.amount_milliunits,
+                category_id: category.category_id,
+            };
+            if (memo)
+                payload.memo = memo;
+            return payload;
+        });
+        const taxSubtransaction = category.tax_milliunits > 0
+            ? [
+                {
+                    amount: -category.tax_milliunits,
+                    category_id: category.category_id,
+                    memo: `Tax - ${category.category_name ?? 'Uncategorized'}`,
+                },
+            ]
+            : [];
+        return [...itemSubtransactions, ...taxSubtransaction];
+    });
+    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 };
+}
+function finalizeBulkUpdateResponse(response) {
+    const appendMessage = (message, addition) => {
+        if (!message) {
+            return addition;
+        }
+        if (message.includes(addition)) {
+            return message;
+        }
+        return `${message} ${addition}`;
+    };
+    const fullSize = estimatePayloadSize(response);
+    if (fullSize <= FULL_RESPONSE_THRESHOLD) {
+        return { ...response, mode: 'full' };
+    }
+    const { transactions, ...summaryResponse } = response;
+    const summaryPayload = {
+        ...summaryResponse,
+        message: appendMessage(response.message, 'Response downgraded to summary to stay under size limits.'),
+        mode: 'summary',
+    };
+    if (estimatePayloadSize(summaryPayload) <= SUMMARY_RESPONSE_THRESHOLD) {
+        return summaryPayload;
+    }
+    const idsOnlyPayload = {
+        ...summaryPayload,
+        results: summaryResponse.results.map((result) => {
+            const simplified = {
+                request_index: result.request_index,
+                status: result.status,
+                transaction_id: result.transaction_id,
+                correlation_key: result.correlation_key,
+            };
+            if (result.error) {
+                simplified.error = result.error;
+            }
+            if (result.error_code) {
+                simplified.error_code = result.error_code;
+            }
+            return simplified;
+        }),
+        message: appendMessage(summaryResponse.message, 'Response downgraded to ids_only to meet 100KB limit.'),
+        mode: 'ids_only',
+    };
+    if (estimatePayloadSize(idsOnlyPayload) <= MAX_RESPONSE_BYTES) {
+        return idsOnlyPayload;
+    }
+    throw new ValidationError('RESPONSE_TOO_LARGE: Unable to format bulk update response within 100KB limit', `Batch size: ${response.summary.total_requested} transactions`, ['Reduce the batch size and retry', 'Consider splitting into multiple smaller batches']);
+}
+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'));
+}
+function handleTransactionError(error, defaultMessage) {
+    let errorMessage = defaultMessage;
+    if (error instanceof Error) {
+        if (error.message.includes('401') || error.message.includes('Unauthorized')) {
+            errorMessage = 'Invalid or expired YNAB access token';
+        }
+        else if (error.message.includes('403') || error.message.includes('Forbidden')) {
+            errorMessage = 'Insufficient permissions to access YNAB data';
+        }
+        else if (error.message.includes('404') || error.message.includes('Not Found')) {
+            errorMessage = 'Budget, account, category, or transaction not found';
+        }
+        else if (error.message.includes('429') || error.message.includes('Too Many Requests')) {
+            errorMessage = 'Rate limit exceeded. Please try again later';
+        }
+        else if (error.message.includes('500') || error.message.includes('Internal Server Error')) {
+            errorMessage = 'YNAB service is currently unavailable';
+        }
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: responseFormatter.format({
+                    error: {
+                        message: errorMessage,
+                    },
+                }),
+            },
+        ],
+    };
+}