@dizzlkheinz/ynab-mcpb 0.12.2 → 0.13.1

package/src/tools/__tests__/categoryTools.test.ts

@@ -9,6 +9,7 @@ import {
   UpdateCategorySchema,
 } from '../categoryTools.js';
 import { createDeltaFetcherMock, createRejectingDeltaFetcherMock } from './deltaTestUtils.js';
+import { CacheKeys } from '../../server/cacheKeys.js';
 
 // Mock the cache manager
 vi.mock('../../server/cacheManager.js', () => ({
@@ -60,9 +61,22 @@ describe('Category Tools', () => {
       },
     );
     (cacheManager.has as ReturnType<typeof vi.fn>).mockReturnValue(false);
-    (CacheManager.generateKey as ReturnType<typeof vi.fn>).mockImplementation(
-      (prefix: string, ...parts: (string | number | boolean | undefined)[]) =>
-        [prefix, ...parts.filter((part) => part !== undefined)].join(':'),
+    (CacheManager.generateKey as any).mockImplementation(
+      (prefix: string, type: string, budgetId: string, id?: string) => {
+        if (prefix === CacheKeys.CATEGORIES && type === 'list') {
+          return `categories:list:${budgetId}`;
+        }
+        if (prefix === CacheKeys.CATEGORIES && type === 'get' && id) {
+          return `categories:get:${budgetId}:${id}`;
+        }
+        if (prefix === CacheKeys.MONTHS && type === 'list') {
+          return `months:list:${budgetId}`;
+        }
+        if (prefix === CacheKeys.MONTHS && type === 'get' && id) {
+          return `months:get:${budgetId}:${id}`;
+        }
+        return `${prefix}:${type}:${budgetId}:${id || ''}`;
+      },
     );
   });
 
@@ -450,34 +464,38 @@ describe('Category Tools', () => {
         data: { category: mockUpdatedCategory },
       });
 
-      const mockCacheKeys = [
-        'categories:list:budget-1:generated-key',
-        'category:get:budget-1:category-1:generated-key',
-      ];
-      (CacheManager.generateKey as any)
-        .mockReturnValueOnce(mockCacheKeys[0])
-        .mockReturnValueOnce(mockCacheKeys[1]);
-
-      const result = await handleUpdateCategory(mockYnabAPI, {
+      await handleUpdateCategory(mockYnabAPI, {
         budget_id: 'budget-1',
         category_id: 'category-1',
         budgeted: 60000,
       });
 
       // Verify cache was invalidated for both category list and specific category
-      expect(CacheManager.generateKey).toHaveBeenCalledWith('categories', 'list', 'budget-1');
       expect(CacheManager.generateKey).toHaveBeenCalledWith(
-        'category',
+        CacheKeys.CATEGORIES,
+        'list',
+        'budget-1',
+      );
+      expect(CacheManager.generateKey).toHaveBeenCalledWith(
+        CacheKeys.CATEGORIES,
         'get',
         'budget-1',
         'category-1',
       );
-      expect(cacheManager.delete).toHaveBeenCalledWith(mockCacheKeys[0]);
-      expect(cacheManager.delete).toHaveBeenCalledWith(mockCacheKeys[1]);
+      expect(cacheManager.delete).toHaveBeenCalledWith(`categories:list:budget-1`);
+      expect(cacheManager.delete).toHaveBeenCalledWith(`categories:get:budget-1:category-1`);
 
-      expect(result.content).toHaveLength(1);
-      const parsedContent = JSON.parse(result.content[0].text);
-      expect(parsedContent.category.budgeted).toBe(60);
+      // Verify month-related caches were invalidated
+      expect(CacheManager.generateKey).toHaveBeenCalledWith(CacheKeys.MONTHS, 'list', 'budget-1');
+      expect(CacheManager.generateKey).toHaveBeenCalledWith(
+        CacheKeys.MONTHS,
+        'get',
+        'budget-1',
+        expect.stringMatching(/^\d{4}-\d{2}-01$/),
+      );
+      const currentMonth = `${new Date().getFullYear()}-${String(new Date().getMonth() + 1).padStart(2, '0')}-01`;
+      expect(cacheManager.delete).toHaveBeenCalledWith(`months:list:budget-1`);
+      expect(cacheManager.delete).toHaveBeenCalledWith(`months:get:budget-1:${currentMonth}`);
     });
 
     it('should not invalidate cache on dry_run category update', async () => {

package/src/tools/__tests__/transactionTools.test.ts

@@ -352,6 +352,61 @@ describe('transactionTools', () => {
       const response = JSON.parse(result.content[0].text);
       expect(response.error.message).toBe('Failed to list transactions');
     });
+
+    it('should include cached property in large response path', async () => {
+      // Create large transaction list (> 90KB)
+      const largeTransactionList: ynab.TransactionDetail[] = [];
+      for (let i = 0; i < 5000; i++) {
+        largeTransactionList.push({
+          id: `transaction-${i}`,
+          date: '2025-01-01',
+          amount: -10000,
+          memo: 'Test transaction with long memo to increase size '.repeat(10),
+          cleared: 'cleared',
+          approved: true,
+          flag_color: null,
+          account_id: 'test-account',
+          payee_id: null,
+          category_id: null,
+          transfer_account_id: null,
+          transfer_transaction_id: null,
+          matched_transaction_id: null,
+          import_id: null,
+          import_payee_name: null,
+          import_payee_name_original: null,
+          debt_transaction_type: null,
+          deleted: false,
+          account_name: 'Test Account',
+          payee_name: 'Test Payee',
+          category_name: 'Test Category',
+          subtransactions: [],
+        } as ynab.TransactionDetail);
+      }
+
+      const mockResponse = {
+        data: {
+          transactions: largeTransactionList,
+        },
+      };
+
+      (mockYnabAPI.transactions.getTransactionsByAccount as any).mockResolvedValue(mockResponse);
+
+      const result = await handleListTransactions(mockYnabAPI, {
+        budget_id: 'test-budget',
+        account_id: 'test-account',
+      });
+
+      const content = result.content?.[0];
+      expect(content).toBeDefined();
+      expect(content?.type).toBe('text');
+
+      const parsedResponse = JSON.parse(content!.text);
+
+      // Should have cached property even in large response path
+      expect(parsedResponse.cached).toBeDefined();
+      expect(parsedResponse.cached).toBe(false);
+      expect(parsedResponse.cache_info).toBeDefined();
+    });
   });
 
   describe('GetTransactionSchema', () => {
@@ -1852,8 +1907,9 @@ describe('transactionTools', () => {
       const result = CreateTransactionsSchema.safeParse(params);
       expect(result.success).toBe(false);
       if (!result.success) {
-        const issue = result.error.issues.find((i) => i.path.includes('subtransactions'));
-        expect(issue?.message).toContain('Subtransactions are not supported');
+        const issue = result.error.issues.find((i) => i.code === 'unrecognized_keys');
+        expect(issue).toBeDefined();
+        expect((issue as any)?.keys).toContain('subtransactions');
       }
     });
 

package/src/tools/accountTools.ts

@@ -8,6 +8,7 @@ import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.j
 import type { DeltaFetcher } from './deltaFetcher.js';
 import type { DeltaCache } from '../server/deltaCache.js';
 import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
 
 /**
@@ -139,7 +140,7 @@ export async function handleGetAccount(
     async () => {
       // Use enhanced CacheManager wrap method
       const cacheKey = CacheManager.generateKey(
-        'account',
+        CacheKeys.ACCOUNTS,
         'get',
         params.budget_id,
         params.account_id,
@@ -248,10 +249,14 @@ export async function handleCreateAccount(
       const account = response.data.account;
 
       // Invalidate accounts list cache after successful account creation
-      const accountsListCacheKey = CacheManager.generateKey('accounts', 'list', params.budget_id);
+      const accountsListCacheKey = CacheManager.generateKey(
+        CacheKeys.ACCOUNTS,
+        'list',
+        params.budget_id,
+      );
       cacheManager.delete(accountsListCacheKey);
 
-      deltaCache.invalidate(params.budget_id, 'accounts');
+      deltaCache.invalidate(params.budget_id, CacheKeys.ACCOUNTS);
 
       return {
         content: [

package/src/tools/categoryTools.ts

@@ -8,6 +8,7 @@ import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.j
 import type { DeltaFetcher } from './deltaFetcher.js';
 import type { DeltaCache } from '../server/deltaCache.js';
 import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
+import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
 
 /**
@@ -158,7 +159,7 @@ export async function handleGetCategory(
     async () => {
       // Use enhanced CacheManager wrap method
       const cacheKey = CacheManager.generateKey(
-        'category',
+        CacheKeys.CATEGORIES,
         'get',
         params.budget_id,
         params.category_id,
@@ -271,9 +272,13 @@ export async function handleUpdateCategory(
     const category = response.data.category;
 
     // Invalidate category-related caches after successful update
-    const categoriesListCacheKey = CacheManager.generateKey('categories', 'list', params.budget_id);
+    const categoriesListCacheKey = CacheManager.generateKey(
+      CacheKeys.CATEGORIES,
+      'list',
+      params.budget_id,
+    );
     const specificCategoryCacheKey = CacheManager.generateKey(
-      'category',
+      CacheKeys.CATEGORIES,
       'get',
       params.budget_id,
       params.category_id,
@@ -282,9 +287,9 @@ export async function handleUpdateCategory(
     cacheManager.delete(specificCategoryCacheKey);
 
     // Invalidate month-related caches as category budget changes affect month data
-    const monthsListCacheKey = CacheManager.generateKey('months', 'list', params.budget_id);
+    const monthsListCacheKey = CacheManager.generateKey(CacheKeys.MONTHS, 'list', params.budget_id);
     const currentMonthCacheKey = CacheManager.generateKey(
-      'month',
+      CacheKeys.MONTHS,
       'get',
       params.budget_id,
       currentMonth,
@@ -292,8 +297,8 @@ export async function handleUpdateCategory(
     cacheManager.delete(monthsListCacheKey);
     cacheManager.delete(currentMonthCacheKey);
 
-    deltaCache.invalidate(params.budget_id, 'categories');
-    deltaCache.invalidate(params.budget_id, 'months');
+    deltaCache.invalidate(params.budget_id, CacheKeys.CATEGORIES);
+    deltaCache.invalidate(params.budget_id, CacheKeys.MONTHS);
     const serverKnowledge = response.data.server_knowledge;
     if (typeof serverKnowledge === 'number') {
       knowledgeStore.update(categoriesListCacheKey, serverKnowledge);

package/src/tools/monthTools.ts

@@ -6,6 +6,7 @@ import { responseFormatter } from '../server/responseFormatter.js';
 import { milliunitsToAmount } from '../utils/amountUtils.js';
 import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
 import type { DeltaFetcher } from './deltaFetcher.js';
+import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs } from './deltaSupport.js';
 
 /**
@@ -42,7 +43,12 @@ export async function handleGetMonth(
   return await withToolErrorHandling(
     async () => {
       // Always use cache
-      const cacheKey = CacheManager.generateKey('month', 'get', params.budget_id, params.month);
+      const cacheKey = CacheManager.generateKey(
+        CacheKeys.MONTHS,
+        'get',
+        params.budget_id,
+        params.month,
+      );
       const wasCached = cacheManager.has(cacheKey);
       const month = await cacheManager.wrap<ynab.MonthDetail>(cacheKey, {
         ttl: CACHE_TTLS.MONTHS,

package/src/tools/payeeTools.ts

@@ -5,6 +5,7 @@ import { withToolErrorHandling } from '../types/index.js';
 import { responseFormatter } from '../server/responseFormatter.js';
 import { cacheManager, CACHE_TTLS, CacheManager } from '../server/cacheManager.js';
 import type { DeltaFetcher } from './deltaFetcher.js';
+import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs } from './deltaSupport.js';
 
 /**
@@ -104,7 +105,12 @@ export async function handleGetPayee(
   return await withToolErrorHandling(
     async () => {
       // Use enhanced CacheManager wrap method
-      const cacheKey = CacheManager.generateKey('payee', 'get', params.budget_id, params.payee_id);
+      const cacheKey = CacheManager.generateKey(
+        CacheKeys.PAYEES,
+        'get',
+        params.budget_id,
+        params.payee_id,
+      );
       const wasCached = cacheManager.has(cacheKey);
       const payee = await cacheManager.wrap<ynab.Payee>(cacheKey, {
         ttl: CACHE_TTLS.PAYEES,

package/src/tools/reconciliation/__tests__/executor.integration.test.ts

@@ -40,7 +40,7 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
         await ynabAPI.transactions.deleteTransaction(budgetId, transactionId);
       });
     }
-  });
+  }, 60000); // 60 second timeout for cleanup of bulk transactions
 
   it(
     'creates 10 transactions via bulk mode',
@@ -67,6 +67,7 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
         this,
       );
       if (!result) return;
+      if (containsRateLimitFailure(result)) return;
 
       trackCreatedTransactions(result);
       expect(result.summary.transactions_created).toBe(10);
@@ -117,6 +118,7 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
         this,
       );
       if (!duplicateAttempt) return;
+      if (containsRateLimitFailure(duplicateAttempt)) return;
 
       const duplicateActions = duplicateAttempt.actions_taken.filter(
         (action) => action.duplicate === true,
@@ -153,6 +155,7 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
         this,
       );
       if (!result) return;
+      if (containsRateLimitFailure(result)) return;
       trackCreatedTransactions(result);
 
       expect(result.summary.transactions_created).toBe(150);
@@ -187,6 +190,7 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
         this,
       );
       if (!result) return;
+      if (containsRateLimitFailure(result)) return;
       trackCreatedTransactions(result);
 
       const duration = Date.now() - start;
@@ -249,6 +253,17 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
       }
     }
   }
+
+  function containsRateLimitFailure(result: Awaited<ReturnType<typeof executeReconciliation>>) {
+    return result.actions_taken.some((action) => {
+      const reason = typeof action.reason === 'string' ? action.reason.toLowerCase() : '';
+      return (
+        reason.includes('429') ||
+        reason.includes('too many requests') ||
+        reason.includes('rate limit')
+      );
+    });
+  }
 });
 
 async function resolveDefaultBudgetId(api: ynab.API): Promise<string> {
@@ -291,7 +306,12 @@ function buildIntegrationAnalysis(
   const clearedDollars = snapshot.cleared_balance / 1000;
   const totalDelta = transactionAmount * count;
   const statementBalance = clearedDollars + totalDelta;
-  const baseDate = Date.parse('2025-12-01');
+
+  // Choose a base date safely in the past so YNAB accepts the transactions (no future dates),
+  // and include a nonce in payee names to avoid duplicate collisions across test runs.
+  const dayMs = 24 * 60 * 60 * 1000;
+  const baseDate = Date.now() - (count + 1) * dayMs;
+  const runNonce = Date.now().toString();
 
   return {
     success: true,
@@ -312,12 +332,12 @@ function buildIntegrationAnalysis(
     auto_matches: [],
     suggested_matches: [],
     unmatched_bank: Array.from({ length: count }, (_, index) => {
-      const date = new Date(baseDate + index * 24 * 60 * 60 * 1000);
+      const date = new Date(baseDate + index * dayMs);
       return {
-        id: `integration-bank-${index}`,
+        id: `integration-bank-${index}-${runNonce}`,
         date: date.toISOString().slice(0, 10),
         amount: transactionAmount,
-        payee: `Integration Payee ${index}`,
+        payee: `Integration Payee ${index}-${runNonce}`,
         memo: `Integration memo ${index}`,
         original_csv_row: index + 1,
       };

package/src/tools/reconciliation/__tests__/executor.test.ts

@@ -574,6 +574,29 @@ describe('executeReconciliation - bulk create mode', () => {
     );
   });
 
+  it('propagates rate-limit error payloads with status codes from bulk create', async () => {
+    const analysis = buildBulkAnalysis(3, 7);
+    const params = buildBulkParams(analysis.summary.target_statement_balance);
+    const initialAccount = { ...defaultAccountSnapshot };
+    const { api, mocks } = createMockYnabAPI(initialAccount);
+
+    mocks.createTransactions.mockRejectedValue({
+      error: { id: '429', name: 'too_many_requests', detail: 'Too many requests' },
+    });
+
+    await expect(
+      executeReconciliation({
+        ynabAPI: api,
+        analysis,
+        params,
+        budgetId: params.budget_id,
+        accountId: params.account_id,
+        initialAccount,
+        currencyCode: 'USD',
+      }),
+    ).rejects.toMatchObject({ status: 429 });
+  });
+
   it('splits large batches into 100-transaction chunks', async () => {
     const analysis = buildBulkAnalysis(150, 5);
     const params = buildBulkParams(analysis.summary.target_statement_balance);
@@ -617,6 +640,29 @@ describe('executeReconciliation - bulk create mode', () => {
     );
   });
 
+  it('throws on fatal sequential creation errors surfaced as objects', async () => {
+    const analysis = buildBulkAnalysis(1, 5);
+    const params = buildBulkParams(analysis.summary.target_statement_balance);
+    const initialAccount = { ...defaultAccountSnapshot };
+    const { api, mocks } = createMockYnabAPI(initialAccount);
+
+    mocks.createTransaction.mockRejectedValue({
+      error: { id: '404', name: 'not_found', detail: 'Account not found' },
+    });
+
+    await expect(
+      executeReconciliation({
+        ynabAPI: api,
+        analysis,
+        params,
+        budgetId: params.budget_id,
+        accountId: params.account_id,
+        initialAccount,
+        currencyCode: 'USD',
+      }),
+    ).rejects.toMatchObject({ status: 404 });
+  });
+
   it('flags duplicate transactions returned by YNAB API', async () => {
     const analysis = buildBulkAnalysis(3, 7);
     const params = buildBulkParams(analysis.summary.target_statement_balance);

package/src/tools/reconciliation/executor.ts

@@ -270,10 +270,11 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
             : `creating ${entry.bankTransaction.payee ?? 'missing transaction'}`;
           recordAlignmentIfNeeded(trigger);
         } catch (error) {
+          const ynabError = normalizeYnabError(error);
           if (bulkOperationDetails) {
             bulkOperationDetails.transaction_failures += 1; // Canonical counter for per-transaction failures
           }
-          const failureReason = error instanceof Error ? error.message : 'Unknown error occurred';
+          const failureReason = ynabError.message || 'Unknown error occurred';
           const failureAction: ExecutionActionRecord = {
             type: 'create_transaction_failed',
             transaction: entry.saveTransaction as unknown as Record<string, unknown>,
@@ -286,6 +287,10 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
             failureAction.bulk_chunk_index = options.chunkIndex;
           }
           actions_taken.push(failureAction);
+
+          if (shouldPropagateYnabError(ynabError)) {
+            throw attachStatusToError(ynabError);
+          }
         }
       }
       // Update sequential_attempts metric if this was a fallback operation
@@ -420,17 +425,23 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
             await processBulkChunk(chunk, chunkIndex);
             bulkOperationDetails.bulk_successes += 1;
           } catch (error) {
-            bulkOperationDetails.sequential_fallbacks += 1;
+            const ynabError = normalizeYnabError(error);
+            const failureReason = ynabError.message || 'unknown error';
             bulkOperationDetails.bulk_chunk_failures += 1; // API-level failure (entire chunk failed)
+
+            if (shouldPropagateYnabError(ynabError)) {
+              bulkOperationDetails.transaction_failures += chunk.length;
+              throw attachStatusToError(ynabError);
+            }
+
+            bulkOperationDetails.sequential_fallbacks += 1;
             actions_taken.push({
               type: 'bulk_create_fallback',
               transaction: null,
-              reason: `Bulk chunk #${chunkIndex} failed (${
-                error instanceof Error ? error.message : 'unknown error'
-              }) - falling back to sequential creation`,
+              reason: `Bulk chunk #${chunkIndex} failed (${failureReason}) - falling back to sequential creation`,
               bulk_chunk_index: chunkIndex,
             });
-            await processSequentialEntries(chunk, { chunkIndex, fallbackError: error });
+            await processSequentialEntries(chunk, { chunkIndex, fallbackError: ynabError });
           }
         }
       }
@@ -630,6 +641,98 @@ export async function executeReconciliation(options: ExecutionOptions): Promise<
   return result;
 }
 
+interface NormalizedYnabError {
+  status?: number;
+  name?: string;
+  message: string;
+  detail?: string;
+}
+
+const FATAL_YNAB_STATUS_CODES = new Set([400, 401, 403, 404, 429, 500]);
+
+function normalizeYnabError(error: unknown): NormalizedYnabError {
+  const parseStatus = (value: unknown): number | undefined => {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string') {
+      const numeric = Number(value);
+      if (Number.isFinite(numeric)) return numeric;
+    }
+    return undefined;
+  };
+
+  if (error instanceof Error) {
+    const status = parseStatus((error as { status?: unknown }).status);
+    const detailSource = (error as { detail?: unknown }).detail;
+    const detail =
+      typeof detailSource === 'string' && detailSource.trim().length > 0 ? detailSource : undefined;
+
+    const result: NormalizedYnabError = {
+      name: error.name,
+      message: error.message || 'Unknown error occurred',
+    };
+
+    if (status !== undefined) result.status = status;
+    if (detail !== undefined) result.detail = detail;
+
+    return result;
+  }
+
+  if (error && typeof error === 'object') {
+    const errObj = (error as { error?: unknown }).error ?? error;
+    const status = parseStatus(
+      (errObj as { id?: unknown }).id ?? (errObj as { status?: unknown }).status,
+    );
+    const detailCandidate =
+      (errObj as { detail?: unknown }).detail ??
+      (errObj as { message?: unknown }).message ??
+      (errObj as { name?: unknown }).name;
+    const detail =
+      typeof detailCandidate === 'string' && detailCandidate.trim().length > 0
+        ? detailCandidate
+        : undefined;
+    const message =
+      detail ??
+      (typeof errObj === 'string' && errObj.trim().length > 0 ? errObj : 'Unknown error occurred');
+    const name =
+      typeof (errObj as { name?: unknown }).name === 'string'
+        ? ((errObj as { name: string }).name as string)
+        : undefined;
+
+    const result: NormalizedYnabError = { message };
+
+    if (status !== undefined) result.status = status;
+    if (name !== undefined) result.name = name;
+    if (detail !== undefined) result.detail = detail;
+
+    return result;
+  }
+
+  if (typeof error === 'string') {
+    return { message: error };
+  }
+
+  return { message: 'Unknown error occurred' };
+}
+
+function shouldPropagateYnabError(error: NormalizedYnabError): boolean {
+  return error.status !== undefined && FATAL_YNAB_STATUS_CODES.has(error.status);
+}
+
+function attachStatusToError(error: NormalizedYnabError): Error {
+  const message = error.message || 'YNAB API error';
+  const err = new Error(message);
+  if (error.status !== undefined) {
+    (err as { status?: number }).status = error.status;
+  }
+  if (error.name) {
+    err.name = error.name;
+  }
+  if (error.detail && !message.includes(error.detail)) {
+    err.message = `${message} (${error.detail})`;
+  }
+  return err;
+}
+
 function formatDisplay(amount: number, currency: string): string {
   return toMoneyValueFromDecimal(amount, currency).value_display;
 }

package/src/tools/schemas/outputs/utilityOutputs.ts

@@ -293,7 +293,7 @@ export const DeltaInfoSchema = z.object({
  *   timestamp: "2025-01-17T12:34:56.789Z",
  *   server: {
  *     name: "ynab-mcp-server",
- *     version: "0.12.0",
+ *     version: "0.13.0",
  *     node_version: "v20.10.0",
  *     // ... other server info
  *   },

package/src/tools/transactionTools.ts

@@ -231,24 +231,9 @@ type BulkTransactionInput = Omit<
   'budget_id' | 'dry_run' | 'subtransactions'
 >;
 
-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): BulkTransactionInput => {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { subtransactions, ...rest } = data;
-    return rest;
-  });
+// Schema for bulk transaction creation - subtransactions are not supported
+// The .strict() modifier automatically rejects any fields not in the schema
+const BulkTransactionInputSchema = BulkTransactionInputSchemaBase.strict();
 
 export const CreateTransactionsSchema = z
   .object({
@@ -813,6 +798,10 @@ export async function handleListTransactions(
                 showing: `First ${preview.length} transactions:`,
                 total_count: transactions.length,
                 estimated_size_kb: Math.round(estimatedSize / 1024),
+                cached: cacheHit,
+                cache_info: cacheHit
+                  ? `Data retrieved from cache for improved performance${usedDelta ? ' (delta merge applied)' : ''}`
+                  : 'Fresh data retrieved from YNAB API',
                 preview_transactions: preview.map((transaction) => ({
                   id: transaction.id,
                   date: transaction.date,

package/src/utils/baseError.ts

@@ -0,0 +1,7 @@
+export class BaseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/utils/errors.ts

@@ -0,0 +1,21 @@
+export { BaseError } from './baseError.js';
+export { ValidationError } from './validationError.js';
+import { BaseError } from './baseError.js';
+
+export class ConfigurationError extends BaseError {}
+
+export class AuthenticationError extends BaseError {}
+
+export class YNABRequestError extends BaseError {
+  constructor(
+    public status: number,
+    public statusText: string,
+    public ynabErrorId?: string,
+  ) {
+    super(
+      `YNAB API request failed: ${status} ${statusText}${
+        ynabErrorId ? ` (Error ID: ${ynabErrorId})` : ''
+      }`,
+    );
+  }
+}