@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/errors/error-handler.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Error Handler
+ *
+ * Provides reusable error handling utilities including:
+ * - Tool handler wrapper with automatic error normalization
+ * - Generic error normalization
+ * - Error type detection
+ */
+import { MCPError, ErrorContext, ToolContext } from "./types.js";
+/**
+ * Error Handler Class
+ *
+ * Central error handling and normalization logic.
+ */
+export declare class ErrorHandler {
+    /**
+     * Wrap tool handler with error normalization
+     *
+     * This wrapper:
+     * - Generates a request ID for tracking
+     * - Logs the tool invocation
+     * - Catches and normalizes all errors
+     * - Logs normalized errors
+     *
+     * @param toolName - Name of the tool being wrapped
+     * @param handler - The actual tool handler function
+     * @returns Wrapped handler with error normalization
+     *
+     * @example
+     * ```typescript
+     * const wrappedHandler = ErrorHandler.wrapHandler(
+     *   "timeentry_create",
+     *   async (input, context) => {
+     *     // Tool implementation
+     *     return result;
+     *   }
+     * );
+     * ```
+     */
+    static wrapHandler<TInput, TOutput>(toolName: string, handler: (input: TInput, context: ToolContext) => Promise<TOutput>): (input: TInput, context: ToolContext) => Promise<TOutput>;
+    /**
+     * Normalize any error to MCP format
+     *
+     * Detects the error type and maps it appropriately:
+     * - Already normalized MCPError: return as-is
+     * - FreshBooks API error: map using ErrorMapper
+     * - Zod validation error: map validation issues
+     * - OAuth error: map authentication error
+     * - Network error: map network/transport error
+     * - Unknown error: create generic internal error
+     *
+     * @param error - Error to normalize
+     * @param context - Additional context
+     * @returns Normalized MCP error
+     */
+    static normalizeError(error: unknown, context?: ErrorContext): MCPError;
+    /**
+     * Check if error is already an MCPError
+     */
+    private static isMCPError;
+    /**
+     * Check if error is a FreshBooks API error
+     */
+    private static isFreshBooksError;
+    /**
+     * Check if error is a network/transport error
+     */
+    private static isNetworkError;
+    /**
+     * Check if error has HTTP status code
+     */
+    private static isHttpError;
+    /**
+     * Create a validation error
+     *
+     * Helper method for creating validation errors directly.
+     *
+     * @param message - Error message
+     * @param context - Error context
+     * @returns MCPError with validation error code
+     */
+    static createValidationError(message: string, context?: ErrorContext): MCPError;
+    /**
+     * Create an authentication error
+     *
+     * Helper method for creating authentication errors directly.
+     *
+     * @param message - Error message
+     * @param context - Error context
+     * @returns MCPError with authentication error code
+     */
+    static createAuthError(message: string, context?: ErrorContext): MCPError;
+    /**
+     * Create a not found error
+     *
+     * Helper method for creating not found errors directly.
+     *
+     * @param resourceType - Type of resource (e.g., "TimeEntry")
+     * @param resourceId - ID of the resource
+     * @param context - Error context
+     * @returns MCPError with not found error code
+     */
+    static createNotFoundError(resourceType: string, resourceId: string | number, context?: ErrorContext): MCPError;
+}
+/**
+ * Generate a unique request ID
+ *
+ * Used for tracking requests through logs.
+ *
+ * @returns Request ID in format: req_<timestamp>_<random>
+ */
+declare function generateRequestId(): string;
+/**
+ * Export request ID generator for use in other modules
+ */
+export { generateRequestId };
+/**
+ * Convenience function for normalizing errors
+ * Re-exports ErrorHandler.normalizeError as handleError for backward compatibility
+ */
+export declare const handleError: typeof ErrorHandler.normalizeError;
+/**
+ * Convenience function for creating authentication errors
+ * Re-exports ErrorHandler.createAuthError for backward compatibility
+ */
+export declare const createAuthError: typeof ErrorHandler.createAuthError;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/errors/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/errors/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,QAAQ,EAIR,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB;;;;GAIG;AACH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,EAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,GACjE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC;IA2B5D;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,QAAQ;IAwEvE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAazB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAahC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAoB7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAW1B;;;;;;;;OAQG;IACH,MAAM,CAAC,qBAAqB,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,GACrB,QAAQ;IAiBX;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,QAAQ;IAiBzE;;;;;;;;;OASG;IACH,MAAM,CAAC,mBAAmB,CACxB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,MAAM,EAC3B,OAAO,CAAC,EAAE,YAAY,GACrB,QAAQ;CAkBZ;AAED;;;;;;GAMG;AACH,iBAAS,iBAAiB,IAAI,MAAM,CAInC;AAED;;GAEG;AACH,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;GAGG;AACH,eAAO,MAAM,WAAW,oCAAiD,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,eAAe,qCAAkD,CAAC"}

package/dist/errors/error-handler.js

@@ -0,0 +1,283 @@
+/**
+ * Error Handler
+ *
+ * Provides reusable error handling utilities including:
+ * - Tool handler wrapper with automatic error normalization
+ * - Generic error normalization
+ * - Error type detection
+ */
+import { z } from "zod";
+import { MCPErrorCode, OAuthError, } from "./types.js";
+import { ErrorMapper } from "./error-mapper.js";
+/**
+ * Error Handler Class
+ *
+ * Central error handling and normalization logic.
+ */
+export class ErrorHandler {
+    /**
+     * Wrap tool handler with error normalization
+     *
+     * This wrapper:
+     * - Generates a request ID for tracking
+     * - Logs the tool invocation
+     * - Catches and normalizes all errors
+     * - Logs normalized errors
+     *
+     * @param toolName - Name of the tool being wrapped
+     * @param handler - The actual tool handler function
+     * @returns Wrapped handler with error normalization
+     *
+     * @example
+     * ```typescript
+     * const wrappedHandler = ErrorHandler.wrapHandler(
+     *   "timeentry_create",
+     *   async (input, context) => {
+     *     // Tool implementation
+     *     return result;
+     *   }
+     * );
+     * ```
+     */
+    static wrapHandler(toolName, handler) {
+        return async (input, context) => {
+            const requestId = generateRequestId();
+            try {
+                // Note: In production, this would use a proper logger
+                // For now, we avoid logging to keep stdio clean for MCP
+                const result = await handler(input, context);
+                return result;
+            }
+            catch (error) {
+                const errorContext = {
+                    tool: toolName,
+                    requestId,
+                };
+                if (context.accountId !== undefined) {
+                    errorContext.accountId = context.accountId;
+                }
+                const mcpError = this.normalizeError(error, errorContext);
+                // Re-throw the normalized error
+                throw mcpError;
+            }
+        };
+    }
+    /**
+     * Normalize any error to MCP format
+     *
+     * Detects the error type and maps it appropriately:
+     * - Already normalized MCPError: return as-is
+     * - FreshBooks API error: map using ErrorMapper
+     * - Zod validation error: map validation issues
+     * - OAuth error: map authentication error
+     * - Network error: map network/transport error
+     * - Unknown error: create generic internal error
+     *
+     * @param error - Error to normalize
+     * @param context - Additional context
+     * @returns Normalized MCP error
+     */
+    static normalizeError(error, context) {
+        // Already normalized
+        if (this.isMCPError(error)) {
+            // Add context if provided and not already present
+            if (context && !error.data.context) {
+                error.data.context = context;
+            }
+            return error;
+        }
+        // FreshBooks API error
+        if (this.isFreshBooksError(error)) {
+            return ErrorMapper.mapFreshBooksError(error, context);
+        }
+        // Zod validation error
+        if (error instanceof z.ZodError) {
+            return ErrorMapper.mapValidationError(error, context);
+        }
+        // OAuth error
+        if (error instanceof OAuthError) {
+            return ErrorMapper.mapOAuthError(error, context);
+        }
+        // Network error
+        if (error instanceof Error && this.isNetworkError(error)) {
+            return ErrorMapper.mapNetworkError(error, context);
+        }
+        // HTTP-like error with status code
+        if (this.isHttpError(error)) {
+            return ErrorMapper.mapHttpError(error.statusCode, error.statusText || "Unknown", context);
+        }
+        // Unknown error - create generic internal error
+        const message = error instanceof Error ? error.message : String(error);
+        const stack = error instanceof Error ? error.stack : undefined;
+        const errorData = {
+            recoverable: true,
+            suggestion: "An unexpected error occurred. Please try again.",
+        };
+        if (context) {
+            errorData.context = context;
+        }
+        if (stack) {
+            errorData.freshbooksError = {
+                code: "UNKNOWN_ERROR",
+                message,
+                details: { stack },
+            };
+        }
+        const mcpError = Object.assign(new Error(`Unexpected error: ${message}`), {
+            code: MCPErrorCode.INTERNAL_ERROR,
+            message: `Unexpected error: ${message}`,
+            data: errorData,
+        });
+        return mcpError;
+    }
+    /**
+     * Check if error is already an MCPError
+     */
+    static isMCPError(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            "message" in error &&
+            "data" in error &&
+            typeof error.code === "number" &&
+            error.code < -32000 &&
+            "recoverable" in error.data);
+    }
+    /**
+     * Check if error is a FreshBooks API error
+     */
+    static isFreshBooksError(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "ok" in error &&
+            error.ok === false &&
+            "error" in error &&
+            typeof error.error === "object");
+    }
+    /**
+     * Check if error is a network/transport error
+     */
+    static isNetworkError(error) {
+        const networkIndicators = [
+            "ETIMEDOUT",
+            "ECONNREFUSED",
+            "ENOTFOUND",
+            "ECONNRESET",
+            "EAI_AGAIN",
+            "ENOTFOUND",
+            "socket hang up",
+            "network",
+            "fetch failed",
+            "getaddrinfo",
+        ];
+        const message = error.message.toLowerCase();
+        return networkIndicators.some((indicator) => message.includes(indicator.toLowerCase()));
+    }
+    /**
+     * Check if error has HTTP status code
+     */
+    static isHttpError(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "statusCode" in error &&
+            typeof error.statusCode === "number");
+    }
+    /**
+     * Create a validation error
+     *
+     * Helper method for creating validation errors directly.
+     *
+     * @param message - Error message
+     * @param context - Error context
+     * @returns MCPError with validation error code
+     */
+    static createValidationError(message, context) {
+        const errorData = {
+            recoverable: true,
+            suggestion: "Check the input parameters and try again",
+        };
+        if (context) {
+            errorData.context = context;
+        }
+        return Object.assign(new Error(message), {
+            code: MCPErrorCode.INVALID_PARAMS,
+            message,
+            data: errorData,
+        });
+    }
+    /**
+     * Create an authentication error
+     *
+     * Helper method for creating authentication errors directly.
+     *
+     * @param message - Error message
+     * @param context - Error context
+     * @returns MCPError with authentication error code
+     */
+    static createAuthError(message, context) {
+        const errorData = {
+            recoverable: true,
+            suggestion: "Please re-authenticate using auth_get_url",
+        };
+        if (context) {
+            errorData.context = context;
+        }
+        return Object.assign(new Error(message), {
+            code: MCPErrorCode.NOT_AUTHENTICATED,
+            message,
+            data: errorData,
+        });
+    }
+    /**
+     * Create a not found error
+     *
+     * Helper method for creating not found errors directly.
+     *
+     * @param resourceType - Type of resource (e.g., "TimeEntry")
+     * @param resourceId - ID of the resource
+     * @param context - Error context
+     * @returns MCPError with not found error code
+     */
+    static createNotFoundError(resourceType, resourceId, context) {
+        const message = `${resourceType} with id ${resourceId} was not found`;
+        const errorData = {
+            recoverable: false,
+            suggestion: `Verify the ${resourceType} ID is correct. The resource may have been deleted.`,
+        };
+        if (context) {
+            errorData.context = context;
+        }
+        return Object.assign(new Error(message), {
+            code: MCPErrorCode.RESOURCE_NOT_FOUND,
+            message,
+            data: errorData,
+        });
+    }
+}
+/**
+ * Generate a unique request ID
+ *
+ * Used for tracking requests through logs.
+ *
+ * @returns Request ID in format: req_<timestamp>_<random>
+ */
+function generateRequestId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `req_${timestamp}_${random}`;
+}
+/**
+ * Export request ID generator for use in other modules
+ */
+export { generateRequestId };
+/**
+ * Convenience function for normalizing errors
+ * Re-exports ErrorHandler.normalizeError as handleError for backward compatibility
+ */
+export const handleError = ErrorHandler.normalizeError.bind(ErrorHandler);
+/**
+ * Convenience function for creating authentication errors
+ * Re-exports ErrorHandler.createAuthError for backward compatibility
+ */
+export const createAuthError = ErrorHandler.createAuthError.bind(ErrorHandler);
+//# sourceMappingURL=error-handler.js.map

package/dist/errors/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/errors/error-handler.ts"],"names":[],"mappings":"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"}

package/dist/errors/error-mapper.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Error Mapper
+ *
+ * Maps various error types to normalized MCP format while
+ * preserving original error details for debugging.
+ */
+import { z } from "zod";
+import { MCPError, FreshBooksApiError, ErrorContext, OAuthError } from "./types.js";
+/**
+ * Error Mapper Class
+ *
+ * Provides static methods for mapping different error types
+ * to the normalized MCP error format.
+ */
+export declare class ErrorMapper {
+    /**
+     * Map FreshBooks API error to MCP error
+     *
+     * @param fbError - FreshBooks API error object
+     * @param context - Additional error context
+     * @returns Normalized MCP error
+     */
+    static mapFreshBooksError(fbError: FreshBooksApiError, context?: ErrorContext): MCPError;
+    /**
+     * Map Zod validation error to MCP error
+     *
+     * @param zodError - Zod validation error
+     * @param context - Additional error context
+     * @returns Normalized MCP error
+     */
+    static mapValidationError(zodError: z.ZodError, context?: ErrorContext): MCPError;
+    /**
+     * Map OAuth error to MCP error
+     *
+     * @param error - OAuth error
+     * @param context - Additional error context
+     * @returns Normalized MCP error
+     */
+    static mapOAuthError(error: OAuthError, context?: ErrorContext): MCPError;
+    /**
+     * Get validation suggestion based on issues
+     *
+     * @param issues - Validation issues
+     * @returns Human-readable suggestion
+     */
+    private static getValidationSuggestion;
+    /**
+     * Map network/transport error to MCP error
+     *
+     * Handles various network error conditions like timeouts,
+     * connection failures, DNS errors, etc.
+     *
+     * @param error - Network error
+     * @param context - Additional error context
+     * @returns Normalized MCP error
+     */
+    static mapNetworkError(error: Error, context?: ErrorContext): MCPError;
+    /**
+     * Map HTTP status code to MCP error
+     *
+     * @param statusCode - HTTP status code
+     * @param statusText - HTTP status text
+     * @param context - Additional error context
+     * @returns Normalized MCP error
+     */
+    static mapHttpError(statusCode: number, statusText: string, context?: ErrorContext): MCPError;
+}
+//# sourceMappingURL=error-mapper.d.ts.map

package/dist/errors/error-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-mapper.d.ts","sourceRoot":"","sources":["../../src/errors/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,QAAQ,EAIR,kBAAkB,EAElB,YAAY,EACZ,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,qBAAa,WAAW;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CACvB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,YAAY,GACrB,QAAQ;IA4BX;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CACvB,QAAQ,EAAE,CAAC,CAAC,QAAQ,EACpB,OAAO,CAAC,EAAE,YAAY,GACrB,QAAQ;IA6BX;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,QAAQ;IAgEzE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAmBtC;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,QAAQ;IA2EtE;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,CACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,YAAY,GACrB,QAAQ;CAmFZ"}