@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/server/budgetResolver.ts

@@ -1,194 +1,231 @@
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { ErrorHandler } from './errorHandler.js';
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ErrorHandler, createErrorHandler } from "./errorHandler.js";
+
+/**
+ * Module-level fallback ErrorHandler for convenience functions and backward compatibility.
+ * Uses a simple JSON formatter; callers that have access to the injected formatter
+ * should pass their own ErrorHandler instance via the optional parameter.
+ */
+const fallbackErrorHandler = createErrorHandler({
+	format: (value: unknown) => JSON.stringify(value, null, 2),
+});
 
 /**
  * Centralized budget resolution helper that standardizes budget ID validation
  * and resolution logic across the entire YNAB MCP server
  */
+// biome-ignore lint/complexity/noStaticOnlyClass: static utility class
 export class BudgetResolver {
-  /**
-   * UUID format validation regex (accepts UUID versions 1-5)
-   */
-  private static readonly UUID_REGEX =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-  /**
-   * Special keywords that are allowed as budget IDs
-   */
-  private static readonly ALLOWED_KEYWORDS = ['default'] as const;
-
-  /**
-   * Resolves a budget ID using provided ID or default, with standardized error handling.
-   * Maps keywords ('default') to concrete budget IDs to prevent 404s from YNAB API.
-   *
-   * Note: While YNAB API natively supports the "default" keyword, this MCP server
-   * intentionally intercepts it to use its own locally-stored default budget ID
-   * (set via set_default_budget tool). This provides caching, consistency, and
-   * allows the MCP server to maintain default budget state independently of YNAB's
-   * OAuth default budget setting.
-   *
-   * @param providedId - The budget ID provided by the user (optional)
-   * @param defaultId - The default budget ID to fall back to (optional)
-   * @returns The resolved budget ID string or CallToolResult with error
-   */
-  static resolveBudgetId(providedId?: string, defaultId?: string): string | CallToolResult {
-    // If a budget ID is provided (including empty strings), handle keywords first
-    if (providedId !== undefined && providedId !== null) {
-      const trimmed = providedId.trim();
-
-      // Handle special keywords
-      if (trimmed === 'default') {
-        // For "default" keyword, we use the MCP server's stored default budget ID
-        // rather than passing "default" to YNAB API (see function JSDoc for rationale)
-        if (defaultId) {
-          return this.validateBudgetId(defaultId);
-        }
-        // No default budget set in MCP server, return error
-        return this.createMissingBudgetError();
-      }
-
-      if (trimmed === 'last-used') {
-        // "last-used" keyword is not currently supported
-        return ErrorHandler.createValidationError(
-          'Unsupported keyword',
-          'The "last-used" keyword is not supported yet. Please use a specific budget ID or set a default budget.',
-          [
-            'Use a specific budget ID (UUID format)',
-            'Set a default budget using the set_default_budget tool',
-            'Use the "default" keyword after setting a default budget',
-            'Run the list_budgets tool to see available budget IDs',
-          ],
-        );
-      }
-
-      // For non-keyword IDs, validate normally (including empty strings)
-      return this.validateBudgetId(providedId);
-    }
-
-    // If no budget ID provided, try to use the default
-    if (defaultId) {
-      return this.validateBudgetId(defaultId);
-    }
-
-    // No budget ID provided and no default set
-    return this.createMissingBudgetError();
-  }
-
-  /**
-   * Validates that a budget ID has the correct format
-   *
-   * @param budgetId - The budget ID to validate
-   * @returns The validated budget ID or CallToolResult with error
-   */
-  static validateBudgetId(budgetId: string): string | CallToolResult {
-    if (!budgetId || typeof budgetId !== 'string') {
-      return this.createInvalidBudgetError('Budget ID must be provided as a non-empty string');
-    }
-
-    const trimmed = budgetId.trim();
-    if (!trimmed) {
-      return this.createInvalidBudgetError('Budget ID cannot be empty or whitespace only');
-    }
-
-    // Allow simplified identifiers in test environments
-    if (process.env['NODE_ENV'] === 'test') {
-      const testIdentifierPattern =
-        /^(test|budget|account|category|transaction|payee|mock)-[a-z0-9_-]+$/i;
-      if (testIdentifierPattern.test(trimmed)) {
-        return trimmed;
-      }
-    }
-
-    // Validate UUID format
-    if (!this.UUID_REGEX.test(trimmed)) {
-      return this.createInvalidBudgetError(
-        `Invalid budget ID format: '${trimmed}'. Must be a valid UUID format (versions 1-5)`,
-      );
-    }
-
-    return trimmed;
-  }
-
-  /**
-   * Creates a standardized error response for missing budget scenarios
-   *
-   * @returns CallToolResult with standardized error response
-   */
-  static createMissingBudgetError(): CallToolResult {
-    const detailMessage = `A budget ID is required for this operation. You can either:
+	/**
+	 * UUID format validation regex (accepts UUID versions 1-5)
+	 */
+	private static readonly UUID_REGEX =
+		/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+	/**
+	 * Special keywords that are allowed as budget IDs
+	 */
+	private static readonly ALLOWED_KEYWORDS = ["default"] as const;
+
+	/**
+	 * Resolves a budget ID using provided ID or default, with standardized error handling.
+	 * Maps keywords ('default') to concrete budget IDs to prevent 404s from YNAB API.
+	 *
+	 * Note: While YNAB API natively supports the "default" keyword, this MCP server
+	 * intentionally intercepts it to use its own locally-stored default budget ID
+	 * (set via set_default_budget tool). This provides caching, consistency, and
+	 * allows the MCP server to maintain default budget state independently of YNAB's
+	 * OAuth default budget setting.
+	 *
+	 * @param providedId - The budget ID provided by the user (optional)
+	 * @param defaultId - The default budget ID to fall back to (optional)
+	 * @returns The resolved budget ID string or CallToolResult with error
+	 */
+	static resolveBudgetId(
+		providedId?: string,
+		defaultId?: string,
+		errorHandler?: ErrorHandler,
+	): string | CallToolResult {
+		// If a budget ID is provided (including empty strings), handle keywords first
+		if (providedId !== undefined && providedId !== null) {
+			const trimmed = providedId.trim();
+
+			// Handle special keywords
+			if (trimmed === "default") {
+				// For "default" keyword, we use the MCP server's stored default budget ID
+				// rather than passing "default" to YNAB API (see function JSDoc for rationale)
+				if (defaultId) {
+					return BudgetResolver.validateBudgetId(defaultId, errorHandler);
+				}
+				// No default budget set in MCP server, return error
+				return BudgetResolver.createMissingBudgetError(errorHandler);
+			}
+
+			if (trimmed === "last-used") {
+				// "last-used" keyword is not currently supported
+				const eh = errorHandler ?? fallbackErrorHandler;
+				return eh.createValidationError(
+					"Unsupported keyword",
+					'The "last-used" keyword is not supported yet. Please use a specific budget ID or set a default budget.',
+					[
+						"Use a specific budget ID (UUID format)",
+						"Set a default budget using the set_default_budget tool",
+						'Use the "default" keyword after setting a default budget',
+						"Run the list_budgets tool to see available budget IDs",
+					],
+				);
+			}
+
+			// For non-keyword IDs, validate normally (including empty strings)
+			return BudgetResolver.validateBudgetId(providedId, errorHandler);
+		}
+
+		// If no budget ID provided, try to use the default
+		if (defaultId) {
+			return BudgetResolver.validateBudgetId(defaultId, errorHandler);
+		}
+
+		// No budget ID provided and no default set
+		return BudgetResolver.createMissingBudgetError(errorHandler);
+	}
+
+	/**
+	 * Validates that a budget ID has the correct format
+	 *
+	 * @param budgetId - The budget ID to validate
+	 * @returns The validated budget ID or CallToolResult with error
+	 */
+	static validateBudgetId(
+		budgetId: string,
+		errorHandler?: ErrorHandler,
+	): string | CallToolResult {
+		if (!budgetId || typeof budgetId !== "string") {
+			return BudgetResolver.createInvalidBudgetError(
+				"Budget ID must be provided as a non-empty string",
+				errorHandler,
+			);
+		}
+
+		const trimmed = budgetId.trim();
+		if (!trimmed) {
+			return BudgetResolver.createInvalidBudgetError(
+				"Budget ID cannot be empty or whitespace only",
+				errorHandler,
+			);
+		}
+
+		// Allow simplified identifiers in test environments
+		if (process.env["NODE_ENV"] === "test") {
+			const testIdentifierPattern =
+				/^(test|budget|account|category|transaction|payee|mock)-[a-z0-9_-]+$/i;
+			if (testIdentifierPattern.test(trimmed)) {
+				return trimmed;
+			}
+		}
+
+		// Validate UUID format
+		if (!BudgetResolver.UUID_REGEX.test(trimmed)) {
+			return BudgetResolver.createInvalidBudgetError(
+				`Invalid budget ID format: '${trimmed}'. Must be a valid UUID format (versions 1-5)`,
+				errorHandler,
+			);
+		}
+
+		return trimmed;
+	}
+
+	/**
+	 * Creates a standardized error response for missing budget scenarios
+	 *
+	 * @returns CallToolResult with standardized error response
+	 */
+	static createMissingBudgetError(errorHandler?: ErrorHandler): CallToolResult {
+		const detailMessage = `A budget ID is required for this operation. You can either:
 1. Provide a specific budget_id parameter
 2. Set a default budget using the set_default_budget tool first`;
 
-    return ErrorHandler.createValidationError(
-      'No budget ID provided and no default budget set',
-      detailMessage,
-      [
-        'Set a default budget first using the set_default_budget tool',
-        'Provide a budget_id parameter when invoking the tool',
-      ],
-    );
-  }
-
-  /**
-   * Creates a standardized error response for invalid budget ID format
-   *
-   * @param details - Specific details about the validation failure
-   * @returns CallToolResult with standardized error response
-   */
-  static createInvalidBudgetError(details: string): CallToolResult {
-    const detailMessage = `${details}
+		const eh = errorHandler ?? fallbackErrorHandler;
+		return eh.createValidationError(
+			"No budget ID provided and no default budget set",
+			detailMessage,
+			[
+				"Set a default budget first using the set_default_budget tool",
+				"Provide a budget_id parameter when invoking the tool",
+			],
+		);
+	}
+
+	/**
+	 * Creates a standardized error response for invalid budget ID format
+	 *
+	 * @param details - Specific details about the validation failure
+	 * @returns CallToolResult with standardized error response
+	 */
+	static createInvalidBudgetError(
+		details: string,
+		errorHandler?: ErrorHandler,
+	): CallToolResult {
+		const detailMessage = `${details}
 
 Valid formats:
 - UUID format (versions 1-5, e.g., "123e4567-e89b-12d3-a456-426614174000")
-- Special keywords: ${this.ALLOWED_KEYWORDS.map((k) => `"${k}"`).join(', ')}
+- Special keywords: ${BudgetResolver.ALLOWED_KEYWORDS.map((k) => `"${k}"`).join(", ")}
 
 You can use the list_budgets tool to see available budget IDs.`;
 
-    return ErrorHandler.createValidationError('Invalid budget ID format', detailMessage, [
-      'Use a valid UUID format (UUID v1-v5, e.g., 123e4567-e89b-12d3-a456-426614174000; standard UUID v4 format works as well)',
-      'Run the list_budgets tool to view available budget IDs',
-      'Use the special keyword "default" for convenience',
-    ]);
-  }
-
-  /**
-   * Convenience function that throws an error if budget resolution fails
-   *
-   * @param providedId - The budget ID provided by the user (optional)
-   * @param defaultId - The default budget ID to fall back to (optional)
-   * @returns The resolved budget ID string
-   * @throws Error if resolution fails
-   */
-  static resolveBudgetIdOrThrow(providedId?: string, defaultId?: string): string {
-    const result = this.resolveBudgetId(providedId, defaultId);
-    if (typeof result === 'string') {
-      return result;
-    }
-
-    // Extract error message from CallToolResult for throwing
-    const errorText =
-      result.content?.[0]?.type === 'text' ? result.content[0].text : 'Budget resolution failed';
-    throw new Error(errorText);
-  }
-
-  /**
-   * Convenience function that validates budget ID and throws an error if validation fails
-   *
-   * @param budgetId - The budget ID to validate
-   * @returns The validated budget ID string
-   * @throws Error if validation fails
-   */
-  static validateBudgetIdOrThrow(budgetId: string): string {
-    const result = this.validateBudgetId(budgetId);
-    if (typeof result === 'string') {
-      return result;
-    }
-
-    // Extract error message from CallToolResult for throwing
-    const errorText =
-      result.content?.[0]?.type === 'text' ? result.content[0].text : 'Budget validation failed';
-    throw new Error(errorText);
-  }
+		const eh = errorHandler ?? fallbackErrorHandler;
+		return eh.createValidationError("Invalid budget ID format", detailMessage, [
+			"Use a valid UUID format (UUID v1-v5, e.g., 123e4567-e89b-12d3-a456-426614174000; standard UUID v4 format works as well)",
+			"Run the list_budgets tool to view available budget IDs",
+			'Use the special keyword "default" for convenience',
+		]);
+	}
+
+	/**
+	 * Convenience function that throws an error if budget resolution fails
+	 *
+	 * @param providedId - The budget ID provided by the user (optional)
+	 * @param defaultId - The default budget ID to fall back to (optional)
+	 * @returns The resolved budget ID string
+	 * @throws Error if resolution fails
+	 */
+	static resolveBudgetIdOrThrow(
+		providedId?: string,
+		defaultId?: string,
+	): string {
+		const result = BudgetResolver.resolveBudgetId(providedId, defaultId);
+		if (typeof result === "string") {
+			return result;
+		}
+
+		// Extract error message from CallToolResult for throwing
+		const errorText =
+			result.content?.[0]?.type === "text"
+				? result.content[0].text
+				: "Budget resolution failed";
+		throw new Error(errorText);
+	}
+
+	/**
+	 * Convenience function that validates budget ID and throws an error if validation fails
+	 *
+	 * @param budgetId - The budget ID to validate
+	 * @returns The validated budget ID string
+	 * @throws Error if validation fails
+	 */
+	static validateBudgetIdOrThrow(budgetId: string): string {
+		const result = BudgetResolver.validateBudgetId(budgetId);
+		if (typeof result === "string") {
+			return result;
+		}
+
+		// Extract error message from CallToolResult for throwing
+		const errorText =
+			result.content?.[0]?.type === "text"
+				? result.content[0].text
+				: "Budget validation failed";
+		throw new Error(errorText);
+	}
 }
 
 /**
@@ -202,8 +239,11 @@ You can use the list_budgets tool to see available budget IDs.`;
  * @param defaultId - Default budget ID to use if `providedId` is not present (optional)
  * @returns The resolved budget ID string, or a `CallToolResult` describing a validation error
  */
-export function resolveBudgetId(providedId?: string, defaultId?: string): string | CallToolResult {
-  return BudgetResolver.resolveBudgetId(providedId, defaultId);
+export function resolveBudgetId(
+	providedId?: string,
+	defaultId?: string,
+): string | CallToolResult {
+	return BudgetResolver.resolveBudgetId(providedId, defaultId);
 }
 
 /**
@@ -212,7 +252,7 @@ export function resolveBudgetId(providedId?: string, defaultId?: string): string
  * @returns The validated budget ID string, or a CallToolResult describing the validation error.
  */
 export function validateBudgetId(budgetId: string): string | CallToolResult {
-  return BudgetResolver.validateBudgetId(budgetId);
+	return BudgetResolver.validateBudgetId(budgetId);
 }
 
 /**
@@ -221,7 +261,7 @@ export function validateBudgetId(budgetId: string): string | CallToolResult {
  * @returns A CallToolResult representing a validation error that explains a budget_id is missing and provides guidance to supply a `budget_id` or configure a default budget.
  */
 export function createMissingBudgetError(): CallToolResult {
-  return BudgetResolver.createMissingBudgetError();
+	return BudgetResolver.createMissingBudgetError();
 }
 
 /**
@@ -231,5 +271,5 @@ export function createMissingBudgetError(): CallToolResult {
  * @returns CallToolResult with standardized error response
  */
 export function createInvalidBudgetError(details: string): CallToolResult {
-  return BudgetResolver.createInvalidBudgetError(details);
+	return BudgetResolver.createInvalidBudgetError(details);
 }

package/src/server/cacheKeys.ts

@@ -1,8 +1,8 @@
 export const CacheKeys = {
-  ACCOUNTS: 'accounts',
-  BUDGETS: 'budgets',
-  CATEGORIES: 'categories',
-  PAYEES: 'payees',
-  TRANSACTIONS: 'transactions',
-  MONTHS: 'months',
+	ACCOUNTS: "accounts",
+	BUDGETS: "budgets",
+	CATEGORIES: "categories",
+	PAYEES: "payees",
+	TRANSACTIONS: "transactions",
+	MONTHS: "months",
 } as const;