@dizzlkheinz/ynab-mcpb 0.18.2 → 0.18.4

package/dist/tools/transactionTools.js

@@ -1,5 +1,3 @@
-import { z } from 'zod/v4';
-import { createHash } from 'crypto';
 import { ValidationError, withToolErrorHandling } from '../types/index.js';
 import { createAdapters, createBudgetResolver } from './adapters.js';
 import { ToolAnnotationPresets } from './toolCategories.js';
@@ -9,483 +7,8 @@ import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.j
 import { globalRequestLogger } from '../server/requestLogger.js';
 import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
 import { handleExportTransactions, ExportTransactionsSchema } from './exportTransactions.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.strict();
-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'),
-    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'),
-    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();
+import { ListTransactionsSchema, GetTransactionSchema, CreateTransactionSchema, CreateTransactionsSchema, CreateReceiptSplitTransactionSchema, UpdateTransactionSchema, UpdateTransactionsSchema, DeleteTransactionSchema, } from './transactionSchemas.js';
+import { ensureTransaction, appendCategoryIds, collectCategoryIdsFromSources, setsEqual, invalidateTransactionCaches, correlateResults, finalizeResponse, finalizeBulkUpdateResponse, handleTransactionError, toMonthKey, } from './transactionUtils.js';
 export async function handleListTransactions(ynabAPI, deltaFetcherOrParams, maybeParams) {
     const { deltaFetcher, params } = resolveDeltaFetcherArgs(ynabAPI, deltaFetcherOrParams, maybeParams);
     return await withToolErrorHandling(async () => {
@@ -749,20 +272,31 @@ export async function handleCreateTransaction(ynabAPI, deltaCacheOrParams, knowl
         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) {
-        return `${item.name}${quantitySuffix} - ${item.memo}`;
+        result = `${item.name}${quantitySuffix} - ${item.memo}`;
     }
-    if (quantitySuffix) {
-        return `${item.name}${quantitySuffix}`;
+    else if (quantitySuffix) {
+        result = `${item.name}${quantitySuffix}`;
     }
-    return item.name;
+    else {
+        result = item.name;
+    }
+    return truncateToLength(result, MAX_MEMO_LENGTH);
 }
-const BIG_TICKET_THRESHOLD_MILLIUNITS = 50000;
-const COLLAPSE_THRESHOLD = 5;
-const MAX_ITEMS_PER_MEMO = 5;
-const MAX_MEMO_LENGTH = 150;
 function applySmartCollapseLogic(categoryCalculations, taxMilliunits) {
     const specialItems = [];
     const remainingItemsByCategory = [];
@@ -891,6 +425,14 @@ function collapseItemsByCategory(categoryGroup) {
     }
     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;
@@ -899,8 +441,12 @@ function buildCollapsedMemo(items) {
         if (!item)
             continue;
         const amount = milliunitsToAmount(item.amount_milliunits);
-        const itemStr = `${item.name} $${amount.toFixed(2)}`;
+        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;
@@ -1522,54 +1068,6 @@ async function resolveMetadata(ynabAPI, budgetId, transactions, options = {}) {
     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 () => {
@@ -1878,38 +1376,6 @@ export async function handleUpdateTransactions(ynabAPI, deltaCacheOrParams, know
         };
     }, '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,
-                    },
-                }),
-            },
-        ],
-    };
-}
 export const registerTransactionTools = (registry, context) => {
     const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
     const budgetResolver = createBudgetResolver(context);
@@ -2031,3 +1497,5 @@ export const registerTransactionTools = (registry, context) => {
         },
     });
 };
+export { ListTransactionsSchema, GetTransactionSchema, CreateTransactionSchema, CreateTransactionsSchema, CreateReceiptSplitTransactionSchema, UpdateTransactionSchema, UpdateTransactionsSchema, DeleteTransactionSchema, } from './transactionSchemas.js';
+export { generateCorrelationKey, toCorrelationPayload, correlateResults, estimatePayloadSize, finalizeResponse, finalizeBulkUpdateResponse, handleTransactionError, toMonthKey, ensureTransaction, appendCategoryIds, collectCategoryIdsFromSources, setsEqual, invalidateTransactionCaches, } from './transactionUtils.js';

package/dist/tools/transactionUtils.d.ts

@@ -0,0 +1,31 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import type { SaveTransactionsResponseData } from 'ynab/dist/models/SaveTransactionsResponseData.js';
+import type { DeltaCache } from '../server/deltaCache.js';
+import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import type { CategorySource, TransactionCacheInvalidationOptions, CorrelationPayload, CorrelationPayloadInput, BulkTransactionInput, BulkTransactionResult, BulkCreateResponse, BulkUpdateResponse } from './transactionSchemas.js';
+export declare function ensureTransaction<T>(transaction: T | undefined, errorMessage: string): T;
+export declare function appendCategoryIds(source: CategorySource | undefined, target: Set<string>): void;
+export declare function collectCategoryIdsFromSources(...sources: (CategorySource | undefined)[]): Set<string>;
+export declare function setsEqual<T>(a: Set<T>, b: Set<T>): boolean;
+export declare const toMonthKey: (date: string) => string;
+export declare function invalidateTransactionCaches(deltaCache: DeltaCache, knowledgeStore: ServerKnowledgeStore, budgetId: string, serverKnowledge: number | undefined, affectedAccountIds: Set<string>, affectedMonths: Set<string>, options?: TransactionCacheInvalidationOptions): void;
+export declare function generateCorrelationKey(transaction: {
+    account_id?: string;
+    date?: string;
+    amount?: number;
+    payee_id?: string | null;
+    payee_name?: string | null;
+    category_id?: string | null;
+    memo?: string | null;
+    cleared?: ynab.TransactionClearedStatus;
+    approved?: boolean;
+    flag_color?: ynab.TransactionFlagColor | null;
+    import_id?: string | null;
+}): string;
+export declare function toCorrelationPayload(transaction: CorrelationPayloadInput): CorrelationPayload;
+export declare function correlateResults(requests: BulkTransactionInput[], responseData: SaveTransactionsResponseData, duplicateImportIds: Set<string>): BulkTransactionResult[];
+export declare function estimatePayloadSize(payload: BulkCreateResponse | BulkUpdateResponse): number;
+export declare function finalizeResponse(response: BulkCreateResponse): BulkCreateResponse;
+export declare function finalizeBulkUpdateResponse(response: BulkUpdateResponse): BulkUpdateResponse;
+export declare function handleTransactionError(error: unknown, defaultMessage: string): CallToolResult;