@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/tools/accountTools.ts

@@ -1,28 +1,36 @@
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import * as ynab from 'ynab';
-import { z } from 'zod/v4';
-import { withToolErrorHandling } from '../types/index.js';
-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 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';
-import type { ToolFactory } from '../types/toolRegistration.js';
-import { createAdapters, createBudgetResolver } from './adapters.js';
-import { ToolAnnotationPresets } from './toolCategories.js';
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type * as ynab from "ynab";
+import { z } from "zod/v4";
+import { CacheKeys } from "../server/cacheKeys.js";
+import {
+	CACHE_TTLS,
+	CacheManager,
+	cacheManager,
+} from "../server/cacheManager.js";
+import type { DeltaCache } from "../server/deltaCache.js";
+import type { ErrorHandler } from "../server/errorHandler.js";
+import { responseFormatter } from "../server/responseFormatter.js";
+import type { ServerKnowledgeStore } from "../server/serverKnowledgeStore.js";
+import { withToolErrorHandling } from "../types/index.js";
+import type { ToolFactory } from "../types/toolRegistration.js";
+import { milliunitsToAmount } from "../utils/amountUtils.js";
+import { createAdapters, createBudgetResolver } from "./adapters.js";
+import type { DeltaFetcher } from "./deltaFetcher.js";
+import {
+	resolveDeltaFetcherArgs,
+	resolveDeltaWriteArgs,
+} from "./deltaSupport.js";
+import { ToolAnnotationPresets } from "./toolCategories.js";
 
 /**
  * Schema for ynab:list_accounts tool parameters
  */
 export const ListAccountsSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    limit: z.number().int().positive().optional(),
-  })
-  .strict();
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		limit: z.number().int().positive().optional(),
+	})
+	.strict();
 
 export type ListAccountsParams = z.infer<typeof ListAccountsSchema>;
 
@@ -30,11 +38,11 @@ export type ListAccountsParams = z.infer<typeof ListAccountsSchema>;
  * Schema for ynab:get_account tool parameters
  */
 export const GetAccountSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    account_id: z.string().min(1, 'Account ID is required'),
-  })
-  .strict();
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		account_id: z.string().min(1, "Account ID is required"),
+	})
+	.strict();
 
 export type GetAccountParams = z.infer<typeof GetAccountSchema>;
 
@@ -42,22 +50,22 @@ export type GetAccountParams = z.infer<typeof GetAccountSchema>;
  * Schema for ynab:create_account tool parameters
  */
 export const CreateAccountSchema = z
-  .object({
-    budget_id: z.string().min(1, 'Budget ID is required'),
-    name: z.string().min(1, 'Account name is required'),
-    type: z.enum([
-      'checking',
-      'savings',
-      'creditCard',
-      'cash',
-      'lineOfCredit',
-      'otherAsset',
-      'otherLiability',
-    ]),
-    balance: z.number().optional(),
-    dry_run: z.boolean().optional(),
-  })
-  .strict();
+	.object({
+		budget_id: z.string().min(1, "Budget ID is required"),
+		name: z.string().min(1, "Account name is required"),
+		type: z.enum([
+			"checking",
+			"savings",
+			"creditCard",
+			"cash",
+			"lineOfCredit",
+			"otherAsset",
+			"otherLiability",
+		]),
+		balance: z.number().optional(),
+		dry_run: z.boolean().optional(),
+	})
+	.strict();
 
 export type CreateAccountParams = z.infer<typeof CreateAccountSchema>;
 
@@ -66,69 +74,73 @@ export type CreateAccountParams = z.infer<typeof CreateAccountSchema>;
  * Lists all accounts for a specific budget
  */
 export async function handleListAccounts(
-  ynabAPI: ynab.API,
-  deltaFetcher: DeltaFetcher,
-  params: ListAccountsParams,
+	ynabAPI: ynab.API,
+	deltaFetcher: DeltaFetcher,
+	params: ListAccountsParams,
 ): Promise<CallToolResult>;
 export async function handleListAccounts(
-  ynabAPI: ynab.API,
-  params: ListAccountsParams,
+	ynabAPI: ynab.API,
+	params: ListAccountsParams,
 ): Promise<CallToolResult>;
 export async function handleListAccounts(
-  ynabAPI: ynab.API,
-  deltaFetcherOrParams: DeltaFetcher | ListAccountsParams,
-  maybeParams?: ListAccountsParams,
+	ynabAPI: ynab.API,
+	deltaFetcherOrParams: DeltaFetcher | ListAccountsParams,
+	maybeParams?: ListAccountsParams,
+	errorHandler?: ErrorHandler,
 ): Promise<CallToolResult> {
-  const { deltaFetcher, params } = resolveDeltaFetcherArgs(
-    ynabAPI,
-    deltaFetcherOrParams,
-    maybeParams,
-  );
-  return await withToolErrorHandling(
-    async () => {
-      const result = await deltaFetcher.fetchAccounts(params.budget_id);
-      let accounts = result.data;
-      const wasCached = result.wasCached;
+	const { deltaFetcher, params } = resolveDeltaFetcherArgs(
+		ynabAPI,
+		deltaFetcherOrParams,
+		maybeParams,
+	);
+	return await withToolErrorHandling(
+		async () => {
+			const result = await deltaFetcher.fetchAccounts(params.budget_id);
+			let accounts = result.data;
+			const wasCached = result.wasCached;
 
-      // Apply limit if specified
-      const totalCount = accounts.length;
-      if (params.limit !== undefined) {
-        accounts = accounts.slice(0, params.limit);
-      }
+			// Apply limit if specified
+			const totalCount = accounts.length;
+			if (params.limit !== undefined) {
+				accounts = accounts.slice(0, params.limit);
+			}
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              accounts: accounts.map((account) => ({
-                id: account.id,
-                name: account.name,
-                type: account.type,
-                on_budget: account.on_budget,
-                closed: account.closed,
-                note: account.note,
-                balance: milliunitsToAmount(account.balance),
-                cleared_balance: milliunitsToAmount(account.cleared_balance),
-                uncleared_balance: milliunitsToAmount(account.uncleared_balance),
-                transfer_payee_id: account.transfer_payee_id,
-                direct_import_linked: account.direct_import_linked,
-                direct_import_in_error: account.direct_import_in_error,
-              })),
-              total_count: totalCount,
-              returned_count: accounts.length,
-              cached: wasCached,
-              cache_info: wasCached
-                ? `Data retrieved from cache for improved performance${result.usedDelta ? ' (delta merge applied)' : ''}`
-                : 'Fresh data retrieved from YNAB API',
-            }),
-          },
-        ],
-      };
-    },
-    'ynab:list_accounts',
-    'listing accounts',
-  );
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							accounts: accounts.map((account) => ({
+								id: account.id,
+								name: account.name,
+								type: account.type,
+								on_budget: account.on_budget,
+								closed: account.closed,
+								note: account.note,
+								balance: milliunitsToAmount(account.balance),
+								cleared_balance: milliunitsToAmount(account.cleared_balance),
+								uncleared_balance: milliunitsToAmount(
+									account.uncleared_balance,
+								),
+								transfer_payee_id: account.transfer_payee_id,
+								direct_import_linked: account.direct_import_linked,
+								direct_import_in_error: account.direct_import_in_error,
+							})),
+							total_count: totalCount,
+							returned_count: accounts.length,
+							cached: wasCached,
+							cache_info: wasCached
+								? `Data retrieved from cache for improved performance${result.usedDelta ? " (delta merge applied)" : ""}`
+								: "Fresh data retrieved from YNAB API",
+						}),
+					},
+				],
+			};
+		},
+		"ynab:list_accounts",
+		"listing accounts",
+		errorHandler,
+	);
 }
 
 /**
@@ -136,61 +148,65 @@ export async function handleListAccounts(
  * Gets detailed information for a specific account
  */
 export async function handleGetAccount(
-  ynabAPI: ynab.API,
-  params: GetAccountParams,
+	ynabAPI: ynab.API,
+	params: GetAccountParams,
+	errorHandler?: ErrorHandler,
 ): Promise<CallToolResult> {
-  return await withToolErrorHandling(
-    async () => {
-      // Use enhanced CacheManager wrap method
-      const cacheKey = CacheManager.generateKey(
-        CacheKeys.ACCOUNTS,
-        'get',
-        params.budget_id,
-        params.account_id,
-      );
-      const wasCached = cacheManager.has(cacheKey);
-      const account = await cacheManager.wrap<ynab.Account>(cacheKey, {
-        ttl: CACHE_TTLS.ACCOUNTS,
-        loader: async () => {
-          const response = await ynabAPI.accounts.getAccountById(
-            params.budget_id,
-            params.account_id,
-          );
-          return response.data.account;
-        },
-      });
+	return await withToolErrorHandling(
+		async () => {
+			// Use enhanced CacheManager wrap method
+			const cacheKey = CacheManager.generateKey(
+				CacheKeys.ACCOUNTS,
+				"get",
+				params.budget_id,
+				params.account_id,
+			);
+			const wasCached = cacheManager.has(cacheKey);
+			const account = await cacheManager.wrap<ynab.Account>(cacheKey, {
+				ttl: CACHE_TTLS.ACCOUNTS,
+				loader: async () => {
+					const response = await ynabAPI.accounts.getAccountById(
+						params.budget_id,
+						params.account_id,
+					);
+					return response.data.account;
+				},
+			});
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              account: {
-                id: account.id,
-                name: account.name,
-                type: account.type,
-                on_budget: account.on_budget,
-                closed: account.closed,
-                note: account.note,
-                balance: milliunitsToAmount(account.balance),
-                cleared_balance: milliunitsToAmount(account.cleared_balance),
-                uncleared_balance: milliunitsToAmount(account.uncleared_balance),
-                transfer_payee_id: account.transfer_payee_id,
-                direct_import_linked: account.direct_import_linked,
-                direct_import_in_error: account.direct_import_in_error,
-              },
-              cached: wasCached,
-              cache_info: wasCached
-                ? 'Data retrieved from cache for improved performance'
-                : 'Fresh data retrieved from YNAB API',
-            }),
-          },
-        ],
-      };
-    },
-    'ynab:get_account',
-    'getting account details',
-  );
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							account: {
+								id: account.id,
+								name: account.name,
+								type: account.type,
+								on_budget: account.on_budget,
+								closed: account.closed,
+								note: account.note,
+								balance: milliunitsToAmount(account.balance),
+								cleared_balance: milliunitsToAmount(account.cleared_balance),
+								uncleared_balance: milliunitsToAmount(
+									account.uncleared_balance,
+								),
+								transfer_payee_id: account.transfer_payee_id,
+								direct_import_linked: account.direct_import_linked,
+								direct_import_in_error: account.direct_import_in_error,
+							},
+							cached: wasCached,
+							cache_info: wasCached
+								? "Data retrieved from cache for improved performance"
+								: "Fresh data retrieved from YNAB API",
+						}),
+					},
+				],
+			};
+		},
+		"ynab:get_account",
+		"getting account details",
+		errorHandler,
+	);
 }
 
 /**
@@ -198,144 +214,150 @@ export async function handleGetAccount(
  * Creates a new account in the specified budget
  */
 export async function handleCreateAccount(
-  ynabAPI: ynab.API,
-  deltaCache: DeltaCache,
-  knowledgeStore: ServerKnowledgeStore,
-  params: CreateAccountParams,
+	ynabAPI: ynab.API,
+	deltaCache: DeltaCache,
+	knowledgeStore: ServerKnowledgeStore,
+	params: CreateAccountParams,
 ): Promise<CallToolResult>;
 export async function handleCreateAccount(
-  ynabAPI: ynab.API,
-  params: CreateAccountParams,
+	ynabAPI: ynab.API,
+	params: CreateAccountParams,
 ): Promise<CallToolResult>;
 export async function handleCreateAccount(
-  ynabAPI: ynab.API,
-  deltaCacheOrParams: DeltaCache | CreateAccountParams,
-  knowledgeStoreOrParams?: ServerKnowledgeStore | CreateAccountParams,
-  maybeParams?: CreateAccountParams,
+	ynabAPI: ynab.API,
+	deltaCacheOrParams: DeltaCache | CreateAccountParams,
+	knowledgeStoreOrParams?: ServerKnowledgeStore | CreateAccountParams,
+	maybeParams?: CreateAccountParams,
+	errorHandler?: ErrorHandler,
 ): Promise<CallToolResult> {
-  const { deltaCache, params } = resolveDeltaWriteArgs(
-    deltaCacheOrParams,
-    knowledgeStoreOrParams,
-    maybeParams,
-  );
-  return await withToolErrorHandling(
-    async () => {
-      if (params.dry_run) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({
-                dry_run: true,
-                action: 'create_account',
-                request: {
-                  budget_id: params.budget_id,
-                  name: params.name,
-                  type: params.type,
-                  balance: params.balance ?? 0,
-                },
-              }),
-            },
-          ],
-        };
-      }
-      const accountData: ynab.SaveAccount = {
-        name: params.name,
-        type: params.type as ynab.Account['type'],
-        balance: params.balance ? params.balance * 1000 : 0, // Convert to milliunits
-      };
+	const { deltaCache, params } = resolveDeltaWriteArgs(
+		deltaCacheOrParams,
+		knowledgeStoreOrParams,
+		maybeParams,
+	);
+	return await withToolErrorHandling(
+		async () => {
+			if (params.dry_run) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: responseFormatter.format({
+								dry_run: true,
+								action: "create_account",
+								request: {
+									budget_id: params.budget_id,
+									name: params.name,
+									type: params.type,
+									balance: params.balance ?? 0,
+								},
+							}),
+						},
+					],
+				};
+			}
+			const accountData: ynab.SaveAccount = {
+				name: params.name,
+				type: params.type as ynab.Account["type"],
+				balance: params.balance ? params.balance * 1000 : 0, // Convert to milliunits
+			};
 
-      const response = await ynabAPI.accounts.createAccount(params.budget_id, {
-        account: accountData,
-      });
+			const response = await ynabAPI.accounts.createAccount(params.budget_id, {
+				account: accountData,
+			});
 
-      const account = response.data.account;
+			const account = response.data.account;
 
-      // Invalidate accounts list cache after successful account creation
-      const accountsListCacheKey = CacheManager.generateKey(
-        CacheKeys.ACCOUNTS,
-        'list',
-        params.budget_id,
-      );
-      cacheManager.delete(accountsListCacheKey);
+			// Invalidate accounts list cache after successful account creation
+			const accountsListCacheKey = CacheManager.generateKey(
+				CacheKeys.ACCOUNTS,
+				"list",
+				params.budget_id,
+			);
+			cacheManager.delete(accountsListCacheKey);
 
-      deltaCache.invalidate(params.budget_id, CacheKeys.ACCOUNTS);
+			deltaCache.invalidate(params.budget_id, CacheKeys.ACCOUNTS);
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: responseFormatter.format({
-              account: {
-                id: account.id,
-                name: account.name,
-                type: account.type,
-                on_budget: account.on_budget,
-                closed: account.closed,
-                note: account.note,
-                balance: milliunitsToAmount(account.balance),
-                cleared_balance: milliunitsToAmount(account.cleared_balance),
-                uncleared_balance: milliunitsToAmount(account.uncleared_balance),
-                transfer_payee_id: account.transfer_payee_id,
-                direct_import_linked: account.direct_import_linked,
-                direct_import_in_error: account.direct_import_in_error,
-              },
-            }),
-          },
-        ],
-      };
-    },
-    'ynab:create_account',
-    'creating account',
-  );
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							account: {
+								id: account.id,
+								name: account.name,
+								type: account.type,
+								on_budget: account.on_budget,
+								closed: account.closed,
+								note: account.note,
+								balance: milliunitsToAmount(account.balance),
+								cleared_balance: milliunitsToAmount(account.cleared_balance),
+								uncleared_balance: milliunitsToAmount(
+									account.uncleared_balance,
+								),
+								transfer_payee_id: account.transfer_payee_id,
+								direct_import_linked: account.direct_import_linked,
+								direct_import_in_error: account.direct_import_in_error,
+							},
+						}),
+					},
+				],
+			};
+		},
+		"ynab:create_account",
+		"creating account",
+		errorHandler,
+	);
 }
 
 /**
  * Registers all account-related tools with the registry.
  */
 export const registerAccountTools: ToolFactory = (registry, context) => {
-  const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
-  const budgetResolver = createBudgetResolver(context);
+	const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
+	const budgetResolver = createBudgetResolver(context);
 
-  registry.register({
-    name: 'list_accounts',
-    description: 'List all accounts for a specific budget',
-    inputSchema: ListAccountsSchema,
-    handler: adaptWithDelta(handleListAccounts),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof ListAccountsSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: List Accounts',
-      },
-    },
-  });
+	registry.register({
+		name: "list_accounts",
+		description: "List all accounts for a specific budget",
+		inputSchema: ListAccountsSchema,
+		handler: adaptWithDelta(handleListAccounts),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof ListAccountsSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+				title: "YNAB: List Accounts",
+			},
+		},
+	});
 
-  registry.register({
-    name: 'get_account',
-    description: 'Get detailed information for a specific account',
-    inputSchema: GetAccountSchema,
-    handler: adapt(handleGetAccount),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof GetAccountSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
-        title: 'YNAB: Get Account Details',
-      },
-    },
-  });
+	registry.register({
+		name: "get_account",
+		description: "Get detailed information for a specific account",
+		inputSchema: GetAccountSchema,
+		handler: adapt(handleGetAccount),
+		defaultArgumentResolver: budgetResolver<z.infer<typeof GetAccountSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+				title: "YNAB: Get Account Details",
+			},
+		},
+	});
 
-  registry.register({
-    name: 'create_account',
-    description: 'Create a new account in the specified budget',
-    inputSchema: CreateAccountSchema,
-    handler: adaptWrite(handleCreateAccount),
-    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateAccountSchema>>(),
-    metadata: {
-      annotations: {
-        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
-        title: 'YNAB: Create Account',
-      },
-    },
-  });
+	registry.register({
+		name: "create_account",
+		description: "Create a new account in the specified budget",
+		inputSchema: CreateAccountSchema,
+		handler: adaptWrite(handleCreateAccount),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof CreateAccountSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+				title: "YNAB: Create Account",
+			},
+		},
+	});
 };