@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/server/errorHandler.js

@@ -0,0 +1,524 @@
+export class YNABAPIError extends Error {
+    constructor(code, message, originalError) {
+        super(message);
+        this.name = 'YNABAPIError';
+        this.code = code;
+        this.originalError = originalError;
+    }
+}
+export class ValidationError extends Error {
+    constructor(message, details, suggestions) {
+        super(message);
+        this.name = 'ValidationError';
+        this.details = details;
+        this.suggestions = suggestions;
+    }
+}
+export class ErrorHandler {
+    constructor(formatter) {
+        this.formatter = formatter;
+    }
+    static createFallbackFormatter() {
+        return {
+            format: (value) => JSON.stringify(value, null, 2),
+        };
+    }
+    static setFormatter(formatter) {
+        ErrorHandler.defaultInstance = new ErrorHandler(formatter);
+    }
+    handleError(error, context) {
+        const errorResponse = this.createErrorResponse(error, context);
+        let formattedText;
+        try {
+            formattedText = this.formatter.format(errorResponse);
+        }
+        catch {
+            formattedText = JSON.stringify(errorResponse, null, 2);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: formattedText,
+                },
+            ],
+        };
+    }
+    static handleError(error, context) {
+        if (!ErrorHandler.defaultInstance) {
+            ErrorHandler.defaultInstance = new ErrorHandler(ErrorHandler.createFallbackFormatter());
+        }
+        return ErrorHandler.defaultInstance.handleError(error, context);
+    }
+    createErrorResponse(error, context) {
+        if (error instanceof YNABAPIError) {
+            const sanitizedDetails = this.sanitizeErrorDetails(error.originalError);
+            return {
+                error: {
+                    code: error.code,
+                    message: this.getErrorMessage(error.code, context),
+                    userMessage: this.getUserFriendlyMessage(error.code, context),
+                    suggestions: this.getErrorSuggestions(error.code, context),
+                    ...(sanitizedDetails && { details: sanitizedDetails }),
+                },
+            };
+        }
+        if (error instanceof ValidationError) {
+            const sanitizedDetails = error.details ? this.sanitizeErrorDetails(error.details) : undefined;
+            const suggestions = error.suggestions && error.suggestions.length > 0
+                ? error.suggestions
+                : this.getErrorSuggestions("VALIDATION_ERROR", context);
+            return {
+                error: {
+                    code: "VALIDATION_ERROR",
+                    message: error.message,
+                    userMessage: this.getUserFriendlyMessage("VALIDATION_ERROR", context),
+                    suggestions,
+                    ...(sanitizedDetails && { details: sanitizedDetails }),
+                },
+            };
+        }
+        const ynabApiError = this.extractYNABApiError(error);
+        if (ynabApiError) {
+            const sanitizedDetails = ynabApiError.details
+                ? this.sanitizeErrorDetails(ynabApiError.details)
+                : undefined;
+            return {
+                error: {
+                    code: ynabApiError.code,
+                    message: this.getErrorMessage(ynabApiError.code, context),
+                    userMessage: this.getUserFriendlyMessage(ynabApiError.code, context),
+                    suggestions: this.getErrorSuggestions(ynabApiError.code, context),
+                    ...(sanitizedDetails && { details: sanitizedDetails }),
+                },
+            };
+        }
+        const httpStatus = this.extractHttpStatus(error);
+        if (httpStatus !== null) {
+            const code = this.mapHttpStatusToErrorCode(httpStatus);
+            if (code) {
+                const details = this.extractHttpStatusDetails(error);
+                return {
+                    error: {
+                        code,
+                        message: this.getErrorMessage(code, context),
+                        userMessage: this.getUserFriendlyMessage(code, context),
+                        suggestions: this.getErrorSuggestions(code, context),
+                        ...(details && { details }),
+                    },
+                };
+            }
+        }
+        if (error instanceof Error) {
+            const detectedCode = this.detectErrorCode(error);
+            if (detectedCode) {
+                return {
+                    error: {
+                        code: detectedCode,
+                        message: this.getErrorMessage(detectedCode, context),
+                        userMessage: this.getUserFriendlyMessage(detectedCode, context),
+                        suggestions: this.getErrorSuggestions(detectedCode, context),
+                    },
+                };
+            }
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const sanitizedDetails = this.sanitizeErrorDetails(errorMessage);
+        return {
+            error: {
+                code: "UNKNOWN_ERROR",
+                message: this.getGenericErrorMessage(context),
+                userMessage: this.getUserFriendlyGenericMessage(context),
+                suggestions: [
+                    'Try the operation again',
+                    'Check your internet connection',
+                    'Contact support if the issue persists',
+                ],
+                ...(sanitizedDetails && { details: sanitizedDetails }),
+            },
+        };
+    }
+    detectErrorCode(error) {
+        const message = error.message.toLowerCase();
+        if (message.includes('401') || message.includes('unauthorized')) {
+            return 401;
+        }
+        if (message.includes('403') || message.includes('forbidden')) {
+            return 403;
+        }
+        if (message.includes('404') || message.includes('not found')) {
+            return 404;
+        }
+        if (message.includes('429') || message.includes('too many requests')) {
+            return 429;
+        }
+        if (message.includes('500') || message.includes('internal server error')) {
+            return 500;
+        }
+        return null;
+    }
+    getUserFriendlyMessage(code, context) {
+        switch (code) {
+            case 401:
+                return 'Your YNAB access token is invalid or has expired. Please check your token and try again.';
+            case 403:
+                return "You don't have permission to access this YNAB data. Please check your account permissions.";
+            case 404:
+                return this.getUserFriendlyNotFoundMessage(context);
+            case 429:
+                return "We're making too many requests to YNAB. Please wait a moment and try again.";
+            case 500:
+                return "YNAB's servers are having issues. Please try again in a few minutes.";
+            case "VALIDATION_ERROR":
+                return 'Some of the information provided is invalid. Please check your inputs and try again.';
+            case "RATE_LIMIT_EXCEEDED":
+                return 'Too many requests have been made. Please wait before trying again.';
+            default:
+                return this.getUserFriendlyGenericMessage(context);
+        }
+    }
+    getErrorSuggestions(code, context) {
+        switch (code) {
+            case 401:
+                return [
+                    'Go to https://app.youneedabudget.com/settings/developer to generate a new access token',
+                    'Make sure you copied the entire token without any extra spaces',
+                    "Check that your token hasn't expired",
+                ];
+            case 403:
+                return [
+                    'Verify that your YNAB account has access to the requested budget',
+                    'Check if your YNAB subscription is active',
+                    'Try logging into YNAB directly to confirm access',
+                ];
+            case 404:
+                return this.getNotFoundSuggestions(context);
+            case 429:
+                return [
+                    'Wait 1-2 minutes before trying again',
+                    'Try making fewer requests at once',
+                    'The system will automatically retry after a short delay',
+                ];
+            case 500:
+                return [
+                    "Check YNAB's status page at https://status.youneedabudget.com",
+                    'Try again in a few minutes',
+                    'Contact YNAB support if the issue persists',
+                ];
+            case "VALIDATION_ERROR":
+                return [
+                    'Double-check all required fields are filled out',
+                    'Verify that amounts are in the correct format',
+                    'Make sure dates are valid and in the right format',
+                ];
+            default:
+                return [
+                    'Try the operation again',
+                    'Check your internet connection',
+                    'Contact support if the issue persists',
+                ];
+        }
+    }
+    getUserFriendlyNotFoundMessage(context) {
+        if (context.includes('account')) {
+            return "We couldn't find the budget or account you're looking for.";
+        }
+        if (context.includes('budget')) {
+            return "We couldn't find that budget. It may have been deleted or you may not have access.";
+        }
+        if (context.includes('category')) {
+            return "We couldn't find that category. It may have been deleted or moved.";
+        }
+        if (context.includes('transaction')) {
+            return "We couldn't find that transaction. It may have been deleted or moved.";
+        }
+        if (context.includes('payee')) {
+            return "We couldn't find that payee in your budget.";
+        }
+        return "We couldn't find what you're looking for. Please check that all information is correct.";
+    }
+    getNotFoundSuggestions(context) {
+        const baseSuggestions = [
+            'Double-check that the name or ID is spelled correctly',
+            'Try refreshing your budget data',
+            "Make sure you're using the right budget",
+        ];
+        if (context.includes('account')) {
+            return [...baseSuggestions, 'Check if the account was recently closed or renamed'];
+        }
+        if (context.includes('category')) {
+            return [
+                ...baseSuggestions,
+                'Check if the category was deleted or moved to a different group',
+            ];
+        }
+        if (context.includes('transaction')) {
+            return [
+                ...baseSuggestions,
+                'Check if the transaction was deleted or is in a different account',
+            ];
+        }
+        return baseSuggestions;
+    }
+    getUserFriendlyGenericMessage(context) {
+        if (context.includes('transaction')) {
+            return 'There was a problem with your transaction. Please check your information and try again.';
+        }
+        if (context.includes('budget')) {
+            return 'There was a problem accessing your budget data. Please try again.';
+        }
+        if (context.includes('account')) {
+            return 'There was a problem accessing your account information. Please try again.';
+        }
+        return 'Something went wrong. Please try again in a moment.';
+    }
+    getErrorMessage(code, context) {
+        switch (code) {
+            case 401:
+                return 'Invalid or expired YNAB access token';
+            case 403:
+                return 'Insufficient permissions to access YNAB data';
+            case 404:
+                return this.getNotFoundMessage(context);
+            case 429:
+                return 'Rate limit exceeded. Please try again later';
+            case 500:
+                return 'YNAB service is currently unavailable';
+            default:
+                return this.getGenericErrorMessage(context);
+        }
+    }
+    getNotFoundMessage(context) {
+        if (context.includes('listing accounts')) {
+            return 'Failed to list accounts - budget or account not found';
+        }
+        if (context.includes('getting account')) {
+            return 'Failed to get account - budget or account not found';
+        }
+        if (context.includes('listing budgets') || context.includes('getting budget')) {
+            return 'Budget not found';
+        }
+        if (context.includes('listing categories') || context.includes('getting category')) {
+            return 'Budget or category not found';
+        }
+        if (context.includes('listing months') || context.includes('getting month')) {
+            return 'Budget or month not found';
+        }
+        if (context.includes('listing payees') || context.includes('getting payee')) {
+            return 'Budget or payee not found';
+        }
+        if (context.includes('listing transactions') || context.includes('getting transaction')) {
+            return 'Budget, account, category, or transaction not found';
+        }
+        return 'The requested resource was not found. Please verify the provided IDs are correct.';
+    }
+    getGenericErrorMessage(context) {
+        if (context.includes('listing accounts')) {
+            return 'Failed to list accounts';
+        }
+        if (context.includes('getting account')) {
+            return 'Failed to get account';
+        }
+        if (context.includes('creating account')) {
+            return 'Failed to create account';
+        }
+        if (context.includes('listing budgets')) {
+            return 'Failed to list budgets';
+        }
+        if (context.includes('getting budget')) {
+            return 'Failed to get budget';
+        }
+        if (context.includes('listing categories')) {
+            return 'Failed to list categories';
+        }
+        if (context.includes('getting category')) {
+            return 'Failed to get category';
+        }
+        if (context.includes('updating category')) {
+            return 'Failed to update category';
+        }
+        if (context.includes('listing months')) {
+            return 'Failed to list months';
+        }
+        if (context.includes('getting month')) {
+            return 'Failed to get month data';
+        }
+        if (context.includes('listing payees')) {
+            return 'Failed to list payees';
+        }
+        if (context.includes('getting payee')) {
+            return 'Failed to get payee';
+        }
+        if (context.includes('listing transactions')) {
+            return 'Failed to list transactions';
+        }
+        if (context.includes('getting transaction')) {
+            return 'Failed to get transaction';
+        }
+        if (context.includes('creating transaction')) {
+            return 'Failed to create transaction';
+        }
+        if (context.includes('updating transaction')) {
+            return 'Failed to update transaction';
+        }
+        if (context.includes('getting user')) {
+            return 'Failed to get user information';
+        }
+        return `An error occurred while ${context}`;
+    }
+    extractHttpStatus(error) {
+        if (!error || typeof error !== 'object') {
+            return null;
+        }
+        const directStatus = error.status;
+        if (typeof directStatus === 'number' && Number.isInteger(directStatus) && directStatus > 0) {
+            return directStatus;
+        }
+        const response = error.response;
+        if (response && typeof response === 'object') {
+            const responseStatus = response.status;
+            if (typeof responseStatus === 'number' &&
+                Number.isInteger(responseStatus) &&
+                responseStatus > 0) {
+                return responseStatus;
+            }
+        }
+        return null;
+    }
+    mapHttpStatusToErrorCode(status) {
+        switch (status) {
+            case 401:
+            case 403:
+            case 404:
+            case 429:
+            case 500:
+                return status;
+            default:
+                return null;
+        }
+    }
+    extractHttpStatusDetails(error) {
+        if (error && typeof error === 'object') {
+            const response = error.response;
+            if (response && typeof response === 'object') {
+                const statusText = response.statusText;
+                if (typeof statusText === 'string' && statusText.trim().length > 0) {
+                    return this.sanitizeErrorDetails(statusText);
+                }
+            }
+        }
+        if (error instanceof Error && error.message) {
+            return this.sanitizeErrorDetails(error.message);
+        }
+        return undefined;
+    }
+    extractYNABApiError(error) {
+        if (!error || typeof error !== 'object' || !('error' in error)) {
+            return null;
+        }
+        const payload = error.error;
+        if (!payload || typeof payload !== 'object') {
+            return null;
+        }
+        const id = payload.id;
+        const name = payload.name;
+        const detail = payload.detail;
+        let code = null;
+        if (typeof id === 'string') {
+            const numeric = parseInt(id, 10);
+            if (!Number.isNaN(numeric)) {
+                code = this.mapHttpStatusToErrorCode(numeric);
+            }
+        }
+        if (!code && typeof name === 'string') {
+            const normalized = name.toLowerCase();
+            if (normalized.includes('unauthorized')) {
+                code = 401;
+            }
+            else if (normalized.includes('forbidden')) {
+                code = 403;
+            }
+            else if (normalized.includes('not_found')) {
+                code = 404;
+            }
+            else if (normalized.includes('too_many_requests') || normalized.includes('rate_limit')) {
+                code = 429;
+            }
+            else if (normalized.includes('internal_server_error')) {
+                code = 500;
+            }
+        }
+        if (!code) {
+            return null;
+        }
+        const details = typeof detail === 'string' ? detail : undefined;
+        const result = { code };
+        if (details !== undefined) {
+            result.details = details;
+        }
+        return result;
+    }
+    sanitizeErrorDetails(error) {
+        if (!error)
+            return undefined;
+        let details = '';
+        if (error instanceof Error) {
+            details = error.message;
+        }
+        else if (typeof error === 'string') {
+            details = error;
+        }
+        else {
+            details = 'Unknown error details';
+        }
+        details = details
+            .replace(/token[s]?[:\s=]+([^\s,"']+)/gi, 'token=***')
+            .replace(/key[s]?[:\s=]+([^\s,"']+)/gi, 'key=***')
+            .replace(/password[s]?[:\s=]+([^\s,"']+)/gi, 'password=***')
+            .replace(/authorization[:\s=]+[^\r\n]+/gi, 'authorization=***')
+            .replace(/\bBearer\s+[A-Za-z0-9._-]+/gi, 'Bearer ***');
+        return details;
+    }
+    async withErrorHandling(operation, context) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            return this.handleError(error, context);
+        }
+    }
+    static async withErrorHandling(operation, context) {
+        if (!ErrorHandler.defaultInstance) {
+            ErrorHandler.defaultInstance = new ErrorHandler(ErrorHandler.createFallbackFormatter());
+        }
+        return ErrorHandler.defaultInstance.withErrorHandling(operation, context);
+    }
+    createValidationError(message, details, suggestions) {
+        return this.handleError(new ValidationError(message, details, suggestions), 'validating parameters');
+    }
+    static createValidationError(message, details, suggestions) {
+        if (!ErrorHandler.defaultInstance) {
+            ErrorHandler.defaultInstance = new ErrorHandler(ErrorHandler.createFallbackFormatter());
+        }
+        return ErrorHandler.defaultInstance.createValidationError(message, details, suggestions);
+    }
+    createYNABError(code, context, originalError) {
+        const message = this.getErrorMessage(code, context);
+        return new YNABAPIError(code, message, originalError);
+    }
+    static createYNABError(code, context, originalError) {
+        if (!ErrorHandler.defaultInstance) {
+            ErrorHandler.defaultInstance = new ErrorHandler(ErrorHandler.createFallbackFormatter());
+        }
+        return ErrorHandler.defaultInstance.createYNABError(code, context, originalError);
+    }
+}
+export function createErrorHandler(formatter) {
+    return new ErrorHandler(formatter);
+}
+export function handleToolError(error, toolName, operation) {
+    return ErrorHandler.handleError(error, `executing ${toolName} - ${operation}`);
+}
+export async function withToolErrorHandling(operation, toolName, operationName) {
+    return ErrorHandler.withErrorHandling(operation, `executing ${toolName} - ${operationName}`);
+}

package/dist/server/prompts.d.ts

@@ -0,0 +1,31 @@
+export interface PromptArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface PromptDefinition {
+    name: string;
+    description: string;
+    arguments: PromptArgument[];
+}
+export interface PromptResponse {
+    description: string;
+    messages: {
+        role: 'user' | 'assistant';
+        content: {
+            type: 'text';
+            text: string;
+        };
+    }[];
+}
+export type PromptHandler = (name: string, args: Record<string, unknown> | undefined) => Promise<PromptResponse>;
+export declare class PromptManager {
+    private promptDefinitions;
+    private promptHandlers;
+    constructor();
+    registerPrompt(definition: PromptDefinition, handler: PromptHandler): void;
+    listPrompts(): {
+        prompts: PromptDefinition[];
+    };
+    getPrompt(name: string, args: Record<string, unknown> | undefined): Promise<PromptResponse>;
+}