@dizzlkheinz/ynab-mcpb 0.18.3 → 0.18.4

package/dist/tools/transactionUtils.js

@@ -0,0 +1,349 @@
+import { createHash } from 'crypto';
+import { ValidationError } from '../types/index.js';
+import { responseFormatter } from '../server/responseFormatter.js';
+import { cacheManager, CacheManager } from '../server/cacheManager.js';
+import { globalRequestLogger } from '../server/requestLogger.js';
+const FULL_RESPONSE_THRESHOLD = 64 * 1024;
+const SUMMARY_RESPONSE_THRESHOLD = 96 * 1024;
+const MAX_RESPONSE_BYTES = 100 * 1024;
+export function ensureTransaction(transaction, errorMessage) {
+    if (!transaction) {
+        throw new Error(errorMessage);
+    }
+    return transaction;
+}
+export 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);
+            }
+        }
+    }
+}
+export function collectCategoryIdsFromSources(...sources) {
+    const result = new Set();
+    for (const source of sources) {
+        appendCategoryIds(source, result);
+    }
+    return result;
+}
+export function setsEqual(a, b) {
+    if (a.size !== b.size) {
+        return false;
+    }
+    for (const value of a) {
+        if (!b.has(value)) {
+            return false;
+        }
+    }
+    return true;
+}
+export const toMonthKey = (date) => `${date.slice(0, 7)}-01`;
+export 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 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;
+}
+export function estimatePayloadSize(payload) {
+    return Buffer.byteLength(JSON.stringify(payload), 'utf8');
+}
+export 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']);
+}
+export 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 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 {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: responseFormatter.format({
+                    error: {
+                        message: errorMessage,
+                    },
+                }),
+            },
+        ],
+    };
+}

package/docs/plans/2025-12-25-transaction-tools-refactor-design.md

@@ -0,0 +1,211 @@
+# TransactionTools Refactoring Design
+
+**Date:** 2025-12-25
+**Status:** Completed
+**Reviewed by:** Claude (Opus 4.5), Gemini CLI
+
+## Problem Statement
+
+`src/tools/transactionTools.ts` was 2,995 lines - the largest file in the codebase by 3x. It mixed multiple concerns:
+- Zod schemas and type definitions
+- Cache invalidation utilities
+- Correlation logic for bulk operations
+- 7 CRUD handler functions
+- Receipt split transaction logic
+
+This made the file difficult to navigate and maintain.
+
+## Goals
+
+1. ✅ Reduce `transactionTools.ts` to ~2,000 lines (30% reduction) - **Actual: 2,274 lines (24% reduction)**
+2. ✅ Separate concerns into logical modules
+3. ✅ Maintain backward compatibility (single consumer: `YNABMCPServer.ts`)
+4. ✅ Preserve existing test coverage (5,212 lines of tests)
+5. ✅ Avoid circular dependencies
+
+## Non-Goals
+
+- Full modular directory structure (e.g., `src/tools/transactions/`)
+- Extracting receipt split logic (creates circular dependency with `handleCreateTransaction`)
+- Moving schemas to `src/tools/schemas/` (existing pattern keeps tool-specific schemas near tools)
+
+## Design
+
+### File Structure
+
+```
+src/tools/
+├── transactionTools.ts       # Handlers + registration (2,274 lines)
+├── transactionSchemas.ts     # Schemas + types + interfaces (453 lines)
+└── transactionUtils.ts       # Cache utils + correlation + finalizeResponse (536 lines)
+```
+
+### File Contents
+
+#### `transactionSchemas.ts` (453 lines)
+
+All Zod schemas and their inferred types:
+
+```typescript
+// Schemas
+export const ListTransactionsSchema = z.object({...});
+export const GetTransactionSchema = z.object({...});
+export const CreateTransactionSchema = z.object({...});
+export const CreateTransactionsSchema = z.object({...});
+export const CreateReceiptSplitTransactionSchema = z.object({...});
+export const UpdateTransactionSchema = z.object({...});
+export const UpdateTransactionsSchema = z.object({...});
+export const DeleteTransactionSchema = z.object({...});
+export const BulkUpdateTransactionInputSchema = z.object({...});
+
+// Inferred types
+export type ListTransactionsParams = z.infer<typeof ListTransactionsSchema>;
+export type GetTransactionParams = z.infer<typeof GetTransactionSchema>;
+// ... etc
+
+// Interfaces
+export interface BulkTransactionResult {...}
+export interface BulkCreateResponse {...}
+export interface BulkUpdateResult {...}
+export interface BulkUpdateResponse {...}
+export interface CorrelationPayload {...}
+export interface CorrelationPayloadInput {...}
+```
+
+#### `transactionUtils.ts` (536 lines)
+
+Cache invalidation, correlation, and response utilities:
+
+```typescript
+// Cache invalidation
+export function invalidateTransactionCaches(
+  deltaCache: DeltaCache,
+  knowledgeStore: ServerKnowledgeStore,
+  budgetId: string,
+  serverKnowledge: number | undefined,
+  affectedAccountIds: Set<string>,
+  affectedMonths: Set<string>,
+  options: TransactionCacheInvalidationOptions = {},
+): void;
+
+// Category helpers
+export function appendCategoryIds(source: CategorySource, target: Set<string>): void;
+export function collectCategoryIdsFromSources(...sources: CategorySource[]): Set<string>;
+export function setsEqual<T>(a: Set<T>, b: Set<T>): boolean;
+
+// Correlation for bulk operations
+export function generateCorrelationKey(transaction: {...}): string;
+export function toCorrelationPayload(transaction: CorrelationPayloadInput): CorrelationPayload;
+export function correlateResults(inputs: CorrelationPayloadInput[], results: BulkTransactionResult[]): Map<string, ...>;
+
+// Response utilities
+export function estimatePayloadSize(payload: BulkCreateResponse | BulkUpdateResponse): number;
+export function finalizeResponse(response: BulkCreateResponse): BulkCreateResponse;
+export function finalizeBulkUpdateResponse(response: BulkUpdateResponse): BulkUpdateResponse;
+
+// Error handling
+export function handleTransactionError(error: unknown, defaultMessage: string): CallToolResult;
+```
+
+#### `transactionTools.ts` (2,274 lines)
+
+All handler functions + tool registration:
+
+```typescript
+import {
+  ListTransactionsSchema,
+  CreateTransactionSchema,
+  // ... all schemas
+} from './transactionSchemas.js';
+
+import {
+  invalidateTransactionCaches,
+  correlateResults,
+  // ... all utils
+} from './transactionUtils.js';
+
+// Handler functions (keep all together to avoid circular deps)
+export async function handleListTransactions(...);
+export async function handleGetTransaction(...);
+export async function handleCreateTransaction(...);
+export async function handleCreateReceiptSplitTransaction(...);  // Calls handleCreateTransaction
+export async function handleUpdateTransaction(...);
+export async function handleCreateTransactions(...);
+export async function handleUpdateTransactions(...);
+export async function handleDeleteTransaction(...);
+
+// Receipt split helpers (pure functions, stay here due to tight coupling)
+function truncateToLength(str: string, maxLength: number): string;
+function buildItemMemo(item: {...}): string;
+function applySmartCollapseLogic(...): SaveSubTransaction[];
+function collapseItemsByCategory(...): SaveSubTransaction[];
+function truncateItemName(...): string;
+function buildCollapsedMemo(...): string;
+function allocateTax(...): void;
+
+// Tool registration
+export const registerTransactionTools: ToolFactory = (registry, context) => {...};
+```
+
+### Import Graph
+
+```
+transactionSchemas.ts  ←──┐
+         ↓                │
+transactionUtils.ts ──────┤ (imports types from schemas)
+         ↓                │
+transactionTools.ts ──────┘ (imports both, no cycles)
+```
+
+## Circular Dependency Avoidance
+
+`handleCreateReceiptSplitTransaction` calls `handleCreateTransaction` at line 1665:
+
+```typescript
+const baseResult = await handleCreateTransaction(
+  ynabAPI,
+  deltaCache,
+  knowledgeStore,
+  createTransactionParams,
+);
+```
+
+If receipt split were extracted to its own file, it would need to import `handleCreateTransaction`, while `transactionTools.ts` would import the receipt split handler for registration - creating a cycle.
+
+**Solution:** Keep all handlers in `transactionTools.ts`.
+
+## Migration Strategy
+
+1. Create `transactionSchemas.ts` with all schemas and types
+2. Create `transactionUtils.ts` with cache/correlation utilities
+3. Update `transactionTools.ts` imports
+4. Run tests to verify no regressions
+5. Update any imports in `YNABMCPServer.ts` if needed
+
+## Test Impact
+
+- Existing tests import from `transactionTools.ts`
+- Most tests should continue working with re-exports
+- May need to update imports for tests that directly use schemas/utils
+- No logic changes = no new test requirements
+
+## Rollback Plan
+
+If issues arise, revert the 3-file split back to single file. Git makes this trivial.
+
+## Success Criteria
+
+- [x] `transactionTools.ts` reduced to ~2,000 lines (Actual: 2,274 lines, 24% reduction from 2,995)
+- [x] All 5,212 lines of tests pass
+- [x] No circular dependency warnings
+- [x] Build succeeds with no type errors
+- [x] `npm run lint` passes
+
+## Final Outcome
+
+The refactoring successfully split the 2,995-line file into three focused modules:
+- **transactionTools.ts**: 2,274 lines (handlers and registration)
+- **transactionSchemas.ts**: 453 lines (Zod schemas and types)
+- **transactionUtils.ts**: 536 lines (utilities and helpers)
+
+Total: 3,263 lines (268-line overhead from imports/exports, 9% overhead which is acceptable for improved maintainability)