@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/errors/error-mapper.js

@@ -0,0 +1,449 @@
+/**
+ * Error Mapper
+ *
+ * Maps various error types to normalized MCP format while
+ * preserving original error details for debugging.
+ */
+import { MCPErrorCode, FreshBooksErrorCode, } from "./types.js";
+/**
+ * Error Mapper Class
+ *
+ * Provides static methods for mapping different error types
+ * to the normalized MCP error format.
+ */
+export 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, context) {
+        const errorCode = fbError.error?.code || "UNKNOWN";
+        const mapping = ERROR_MAPPINGS[errorCode] || DEFAULT_MAPPING;
+        const mcpError = Object.assign(new Error(mapping.getMessage(fbError.error)), {
+            code: mapping.mcpCode,
+            message: mapping.getMessage(fbError.error),
+            data: {
+                freshbooksError: {
+                    code: fbError.error?.code || "UNKNOWN",
+                    message: fbError.error?.message || "Unknown error",
+                    field: fbError.error?.field,
+                    errno: fbError.error?.errno,
+                    details: fbError.error?.details,
+                },
+                context,
+                recoverable: mapping.recoverable,
+                suggestion: mapping.getSuggestion(fbError.error),
+                retryAfter: fbError.retryAfter,
+            },
+        });
+        return 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, context) {
+        const issues = zodError.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+            code: issue.code,
+            expected: "expected" in issue ? String(issue.expected) : undefined,
+            received: "received" in issue ? issue.received : undefined,
+        }));
+        const firstIssue = issues[0];
+        const message = firstIssue
+            ? `Validation failed for "${firstIssue.path}": ${firstIssue.message}`
+            : "Validation failed";
+        const mcpError = Object.assign(new Error(message), {
+            code: MCPErrorCode.INVALID_PARAMS,
+            message,
+            data: {
+                validationErrors: issues,
+                context,
+                recoverable: true,
+                suggestion: this.getValidationSuggestion(issues),
+                statusCode: 400,
+            },
+        });
+        return mcpError;
+    }
+    /**
+     * Map OAuth error to MCP error
+     *
+     * @param error - OAuth error
+     * @param context - Additional error context
+     * @returns Normalized MCP error
+     */
+    static mapOAuthError(error, context) {
+        const isTokenExpired = error.code === "invalid_grant" ||
+            error.code === "token_expired" ||
+            error.message.toLowerCase().includes("expired");
+        const isInvalidAuth = error.code === "invalid_client" ||
+            error.code === "unauthorized_client" ||
+            error.code === "access_denied";
+        if (isTokenExpired) {
+            const message = "Authentication token has expired.";
+            return Object.assign(new Error(message), {
+                code: MCPErrorCode.TOKEN_EXPIRED,
+                message,
+                data: {
+                    freshbooksError: {
+                        code: error.code,
+                        message: error.message,
+                    },
+                    context,
+                    recoverable: true,
+                    suggestion: "Call auth_refresh to get a new token, or re-authenticate using auth_get_url",
+                },
+            });
+        }
+        if (isInvalidAuth) {
+            const message = "Authentication failed or access was denied.";
+            return Object.assign(new Error(message), {
+                code: MCPErrorCode.NOT_AUTHENTICATED,
+                message,
+                data: {
+                    freshbooksError: {
+                        code: error.code,
+                        message: error.message,
+                    },
+                    context,
+                    recoverable: true,
+                    suggestion: "Re-authenticate using auth_get_url to obtain valid credentials",
+                },
+            });
+        }
+        const message = `OAuth error: ${error.message}`;
+        return Object.assign(new Error(message), {
+            code: MCPErrorCode.NOT_AUTHENTICATED,
+            message,
+            data: {
+                freshbooksError: {
+                    code: error.code,
+                    message: error.message,
+                    details: error.details,
+                },
+                context,
+                recoverable: true,
+                suggestion: "Check your OAuth credentials and try again",
+            },
+        });
+    }
+    /**
+     * Get validation suggestion based on issues
+     *
+     * @param issues - Validation issues
+     * @returns Human-readable suggestion
+     */
+    static getValidationSuggestion(issues) {
+        if (issues.length === 0) {
+            return "Check the input parameters and try again";
+        }
+        if (issues.length === 1) {
+            const issue = issues[0];
+            if (!issue) {
+                return "Check the input parameters and try again";
+            }
+            return `Fix the "${issue.path}" field: ${issue.message.toLowerCase()}`;
+        }
+        const fields = issues.map((i) => `"${i.path}"`).join(", ");
+        return `Fix the following fields: ${fields}`;
+    }
+    /**
+     * 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, context) {
+        const errorMessage = error.message.toLowerCase();
+        // Timeout errors
+        const isTimeout = errorMessage.includes("etimedout") || errorMessage.includes("timeout");
+        // Connection errors
+        const isConnection = errorMessage.includes("econnrefused") ||
+            errorMessage.includes("enotfound") ||
+            errorMessage.includes("econnreset");
+        // DNS errors
+        const isDNS = errorMessage.includes("eai_again") ||
+            errorMessage.includes("getaddrinfo");
+        // Socket errors
+        const isSocket = errorMessage.includes("socket hang up");
+        if (isTimeout) {
+            const message = "Request timed out. FreshBooks may be slow to respond.";
+            return Object.assign(new Error(message), {
+                code: MCPErrorCode.SERVICE_UNAVAILABLE,
+                message,
+                data: {
+                    context,
+                    recoverable: true,
+                    suggestion: "Wait a moment and try again. If the issue persists, check FreshBooks status.",
+                },
+            });
+        }
+        if (isConnection || isDNS) {
+            const message = "Could not connect to FreshBooks API.";
+            return Object.assign(new Error(message), {
+                code: MCPErrorCode.SERVICE_UNAVAILABLE,
+                message,
+                data: {
+                    context,
+                    recoverable: true,
+                    suggestion: "Check your internet connection and try again.",
+                },
+            });
+        }
+        if (isSocket) {
+            const message = "Connection was closed unexpectedly.";
+            return Object.assign(new Error(message), {
+                code: MCPErrorCode.SERVICE_UNAVAILABLE,
+                message,
+                data: {
+                    context,
+                    recoverable: true,
+                    suggestion: "The connection was interrupted. Please try again.",
+                },
+            });
+        }
+        // Generic network error
+        const message = `Network error: ${error.message}`;
+        return Object.assign(new Error(message), {
+            code: MCPErrorCode.INTERNAL_ERROR,
+            message,
+            data: {
+                context,
+                recoverable: true,
+                suggestion: "An unexpected network error occurred. Please try again.",
+            },
+        });
+    }
+    /**
+     * 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, statusText, context) {
+        let code;
+        let message;
+        let recoverable;
+        let suggestion;
+        switch (statusCode) {
+            case 401:
+                code = MCPErrorCode.NOT_AUTHENTICATED;
+                message = "Authentication required or session expired";
+                recoverable = true;
+                suggestion = "Please re-authenticate using auth_get_url";
+                break;
+            case 403:
+                code = MCPErrorCode.PERMISSION_DENIED;
+                message = "Permission denied";
+                recoverable = false;
+                suggestion =
+                    "You don't have access to this resource. Contact your administrator.";
+                break;
+            case 404:
+                code = MCPErrorCode.RESOURCE_NOT_FOUND;
+                message = "Resource not found";
+                recoverable = false;
+                suggestion =
+                    "Verify the resource ID is correct. The resource may have been deleted.";
+                break;
+            case 409:
+                code = MCPErrorCode.CONFLICT;
+                message = "Conflict with existing resource";
+                recoverable = false;
+                suggestion = "A resource with these details already exists";
+                break;
+            case 422:
+                code = MCPErrorCode.VALIDATION_ERROR;
+                message = "Validation failed";
+                recoverable = true;
+                suggestion = "Check the input values and try again";
+                break;
+            case 429:
+                code = MCPErrorCode.RATE_LIMITED;
+                message = "Rate limit exceeded";
+                recoverable = true;
+                suggestion = "Wait a moment before making more requests";
+                break;
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                code = MCPErrorCode.SERVICE_UNAVAILABLE;
+                message = "FreshBooks service is unavailable";
+                recoverable = true;
+                suggestion =
+                    "An error occurred on FreshBooks' side. Please try again.";
+                break;
+            default:
+                code = MCPErrorCode.INTERNAL_ERROR;
+                message = `HTTP error ${statusCode}: ${statusText}`;
+                recoverable = true;
+                suggestion = "An unexpected error occurred. Please try again.";
+        }
+        return Object.assign(new Error(message), {
+            code,
+            message,
+            data: {
+                freshbooksError: {
+                    code: `HTTP_${statusCode}`,
+                    message: statusText,
+                },
+                context,
+                recoverable,
+                suggestion,
+            },
+        });
+    }
+}
+/**
+ * Error Mapping Configuration
+ *
+ * Maps FreshBooks error codes to MCP error codes with
+ * recovery guidance.
+ */
+const ERROR_MAPPINGS = {
+    // Authentication Errors
+    [FreshBooksErrorCode.UNAUTHORIZED]: {
+        mcpCode: MCPErrorCode.NOT_AUTHENTICATED,
+        recoverable: true,
+        statusCode: 401,
+        getMessage: () => "Authentication required or session expired",
+        getSuggestion: () => "Please authenticate using auth_get_url to obtain access credentials",
+    },
+    [FreshBooksErrorCode.UNAUTHENTICATED]: {
+        mcpCode: MCPErrorCode.NOT_AUTHENTICATED,
+        recoverable: true,
+        statusCode: 401,
+        getMessage: () => "No valid authentication found",
+        getSuggestion: () => "Call auth_get_url to start the authentication process",
+    },
+    [FreshBooksErrorCode.TOKEN_EXPIRED]: {
+        mcpCode: MCPErrorCode.TOKEN_EXPIRED,
+        recoverable: true,
+        statusCode: 401,
+        getMessage: () => "Access token has expired",
+        getSuggestion: () => "Call auth_refresh to refresh your token, or re-authenticate if refresh fails",
+    },
+    [FreshBooksErrorCode.INVALID_GRANT]: {
+        mcpCode: MCPErrorCode.TOKEN_EXPIRED,
+        recoverable: true,
+        statusCode: 401,
+        getMessage: () => "Refresh token is invalid or expired",
+        getSuggestion: () => "Re-authenticate using auth_get_url to obtain new credentials",
+    },
+    // Permission Errors
+    [FreshBooksErrorCode.FORBIDDEN]: {
+        mcpCode: MCPErrorCode.PERMISSION_DENIED,
+        recoverable: false,
+        statusCode: 403,
+        getMessage: (e) => `Permission denied: ${e.message}`,
+        getSuggestion: () => "You don't have permission to access this resource. Contact your FreshBooks administrator to request access.",
+    },
+    [FreshBooksErrorCode.INSUFFICIENT_PERMISSIONS]: {
+        mcpCode: MCPErrorCode.PERMISSION_DENIED,
+        recoverable: false,
+        statusCode: 403,
+        getMessage: (e) => `Insufficient permissions: ${e.message}`,
+        getSuggestion: () => "Your FreshBooks account lacks the required permissions for this operation",
+    },
+    // Resource Errors
+    [FreshBooksErrorCode.NOT_FOUND]: {
+        mcpCode: MCPErrorCode.RESOURCE_NOT_FOUND,
+        recoverable: false,
+        statusCode: 404,
+        getMessage: (e) => {
+            if (e.field) {
+                return `Resource not found: The ${e.field} you specified doesn't exist`;
+            }
+            return `Resource not found: ${e.message}`;
+        },
+        getSuggestion: (e) => {
+            if (e.field) {
+                return `Verify the ${e.field} is correct. The resource may have been deleted or moved to a different account.`;
+            }
+            return "Double-check the ID or identifier. The resource may have been deleted.";
+        },
+    },
+    // Validation Errors
+    [FreshBooksErrorCode.VALIDATION_ERROR]: {
+        mcpCode: MCPErrorCode.VALIDATION_ERROR,
+        recoverable: true,
+        statusCode: 422,
+        getMessage: (e) => {
+            if (e.field) {
+                return `Invalid value for "${e.field}": ${e.message}`;
+            }
+            return `Validation error: ${e.message}`;
+        },
+        getSuggestion: (e) => {
+            if (e.field) {
+                return `Check the value provided for "${e.field}" and ensure it meets the requirements`;
+            }
+            return "Review the input values and ensure they match the expected format";
+        },
+    },
+    [FreshBooksErrorCode.BAD_REQUEST]: {
+        mcpCode: MCPErrorCode.VALIDATION_ERROR,
+        recoverable: true,
+        statusCode: 400,
+        getMessage: (e) => `Invalid request: ${e.message}`,
+        getSuggestion: () => "Check the request parameters and ensure all required fields are provided correctly",
+    },
+    // Rate Limiting
+    [FreshBooksErrorCode.RATE_LIMIT_EXCEEDED]: {
+        mcpCode: MCPErrorCode.RATE_LIMITED,
+        recoverable: true,
+        statusCode: 429,
+        getMessage: () => "Rate limit exceeded",
+        getSuggestion: () => "You've made too many requests in a short period. Wait before making more requests.",
+    },
+    // Conflict Errors
+    [FreshBooksErrorCode.CONFLICT]: {
+        mcpCode: MCPErrorCode.CONFLICT,
+        recoverable: false,
+        statusCode: 409,
+        getMessage: (e) => `Conflict: ${e.message}`,
+        getSuggestion: () => "A resource with these details already exists. Try updating the existing resource instead of creating a new one.",
+    },
+    // Server Errors
+    [FreshBooksErrorCode.INTERNAL_ERROR]: {
+        mcpCode: MCPErrorCode.INTERNAL_ERROR,
+        recoverable: true,
+        statusCode: 500,
+        getMessage: () => "FreshBooks server error",
+        getSuggestion: () => "An error occurred on FreshBooks' side. Please try again in a few moments. If the issue persists, contact FreshBooks support.",
+    },
+    [FreshBooksErrorCode.SERVICE_UNAVAILABLE]: {
+        mcpCode: MCPErrorCode.SERVICE_UNAVAILABLE,
+        recoverable: true,
+        statusCode: 503,
+        getMessage: () => "FreshBooks service is temporarily unavailable",
+        getSuggestion: () => "FreshBooks may be undergoing maintenance. Please try again later or check status.freshbooks.com",
+    },
+};
+/**
+ * Default Error Mapping
+ *
+ * Used when no specific mapping is found for an error code.
+ */
+const DEFAULT_MAPPING = {
+    mcpCode: MCPErrorCode.INTERNAL_ERROR,
+    recoverable: true,
+    getMessage: (e) => e.message || "An unexpected error occurred",
+    getSuggestion: () => "Please try again. If the issue persists, check the error details.",
+};
+//# sourceMappingURL=error-mapper.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-mapper.js","sourceRoot":"","sources":["../../src/errors/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAEL,YAAY,EAEZ,mBAAmB,GAKpB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CACvB,OAA2B,EAC3B,OAAsB;QAEtB,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,IAAI,SAAS,CAAC;QACnD,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,eAAe,CAAC;QAE7D,MAAM,QAAQ,GAAa,MAAM,CAAC,MAAM,CACtC,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAC5C;YACE,IAAI,EAAE,OAAO,CAAC,OAAO;YACrB,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC;YAC1C,IAAI,EAAE;gBACJ,eAAe,EAAE;oBACf,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,IAAI,SAAS;oBACtC,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,IAAI,eAAe;oBAClD,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK;oBAC3B,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK;oBAC3B,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO;iBAChC;gBACD,OAAO;gBACP,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,UAAU,EAAE,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC;gBAChD,UAAU,EAAE,OAAO,CAAC,UAAU;aACf;SAClB,CACF,CAAC;QAEF,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CACvB,QAAoB,EACpB,OAAsB;QAEtB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC7C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;YAClE,QAAQ,EAAE,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SAC3D,CAAC,CAAC,CAAC;QAEJ,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,OAAO,GAAG,UAAU;YACxB,CAAC,CAAC,0BAA0B,UAAU,CAAC,IAAI,MAAM,UAAU,CAAC,OAAO,EAAE;YACrE,CAAC,CAAC,mBAAmB,CAAC;QAExB,MAAM,QAAQ,GAAa,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;YAC3D,IAAI,EAAE,YAAY,CAAC,cAAc;YACjC,OAAO;YACP,IAAI,EAAE;gBACJ,gBAAgB,EAAE,MAAM;gBACxB,OAAO;gBACP,WAAW,EAAE,IAAI;gBACjB,UAAU,EAAE,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC;gBAChD,UAAU,EAAE,GAAG;aACA;SAClB,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,KAAiB,EAAE,OAAsB;QAC5D,MAAM,cAAc,GAClB,KAAK,CAAC,IAAI,KAAK,eAAe;YAC9B,KAAK,CAAC,IAAI,KAAK,eAAe;YAC9B,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAElD,MAAM,aAAa,GACjB,KAAK,CAAC,IAAI,KAAK,gBAAgB;YAC/B,KAAK,CAAC,IAAI,KAAK,qBAAqB;YACpC,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;QAEjC,IAAI,cAAc,EAAE,CAAC;YACnB,MAAM,OAAO,GAAG,mCAAmC,CAAC;YACpD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;gBACvC,IAAI,EAAE,YAAY,CAAC,aAAa;gBAChC,OAAO;gBACP,IAAI,EAAE;oBACJ,eAAe,EAAE;wBACf,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;qBACvB;oBACD,OAAO;oBACP,WAAW,EAAE,IAAI;oBACjB,UAAU,EACR,6EAA6E;iBAChE;aAClB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,OAAO,GAAG,6CAA6C,CAAC;YAC9D,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;gBACvC,IAAI,EAAE,YAAY,CAAC,iBAAiB;gBACpC,OAAO;gBACP,IAAI,EAAE;oBACJ,eAAe,EAAE;wBACf,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;qBACvB;oBACD,OAAO;oBACP,WAAW,EAAE,IAAI;oBACjB,UAAU,EACR,gEAAgE;iBACnD;aAClB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,OAAO,GAAG,gBAAgB,KAAK,CAAC,OAAO,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;YACvC,IAAI,EAAE,YAAY,CAAC,iBAAiB;YACpC,OAAO;YACP,IAAI,EAAE;gBACJ,eAAe,EAAE;oBACf,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,OAAO,EAAE,KAAK,CAAC,OAAO;iBACvB;gBACD,OAAO;gBACP,WAAW,EAAE,IAAI;gBACjB,UAAU,EAAE,4CAA4C;aACzC;SAClB,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACK,MAAM,CAAC,uBAAuB,CACpC,MAAgD;QAEhD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,0CAA0C,CAAC;QACpD,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACxB,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,0CAA0C,CAAC;YACpD,CAAC;YACD,OAAO,YAAY,KAAK,CAAC,IAAI,YAAY,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;QACzE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,OAAO,6BAA6B,MAAM,EAAE,CAAC;IAC/C,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,CAAC,KAAY,EAAE,OAAsB;QACzD,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAEjD,iBAAiB;QACjB,MAAM,SAAS,GACb,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEzE,oBAAoB;QACpB,MAAM,YAAY,GAChB,YAAY,CAAC,QAAQ,CAAC,cAAc,CAAC;YACrC,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC;YAClC,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAEtC,aAAa;QACb,MAAM,KAAK,GACT,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC;YAClC,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;QAEvC,gBAAgB;QAChB,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;QAEzD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,OAAO,GAAG,uDAAuD,CAAC;YACxE,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;gBACvC,IAAI,EAAE,YAAY,CAAC,mBAAmB;gBACtC,OAAO;gBACP,IAAI,EAAE;oBACJ,OAAO;oBACP,WAAW,EAAE,IAAI;oBACjB,UAAU,EACR,8EAA8E;iBACjE;aAClB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,YAAY,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,sCAAsC,CAAC;YACvD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;gBACvC,IAAI,EAAE,YAAY,CAAC,mBAAmB;gBACtC,OAAO;gBACP,IAAI,EAAE;oBACJ,OAAO;oBACP,WAAW,EAAE,IAAI;oBACjB,UAAU,EAAE,+CAA+C;iBAC5C;aAClB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,qCAAqC,CAAC;YACtD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;gBACvC,IAAI,EAAE,YAAY,CAAC,mBAAmB;gBACtC,OAAO;gBACP,IAAI,EAAE;oBACJ,OAAO;oBACP,WAAW,EAAE,IAAI;oBACjB,UAAU,EACR,mDAAmD;iBACtC;aAClB,CAAC,CAAC;QACL,CAAC;QAED,wBAAwB;QACxB,MAAM,OAAO,GAAG,kBAAkB,KAAK,CAAC,OAAO,EAAE,CAAC;QAClD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;YACvC,IAAI,EAAE,YAAY,CAAC,cAAc;YACjC,OAAO;YACP,IAAI,EAAE;gBACJ,OAAO;gBACP,WAAW,EAAE,IAAI;gBACjB,UAAU,EAAE,yDAAyD;aACtD;SAClB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,CACjB,UAAkB,EAClB,UAAkB,EAClB,OAAsB;QAEtB,IAAI,IAAkB,CAAC;QACvB,IAAI,OAAe,CAAC;QACpB,IAAI,WAAoB,CAAC;QACzB,IAAI,UAAkB,CAAC;QAEvB,QAAQ,UAAU,EAAE,CAAC;YACnB,KAAK,GAAG;gBACN,IAAI,GAAG,YAAY,CAAC,iBAAiB,CAAC;gBACtC,OAAO,GAAG,4CAA4C,CAAC;gBACvD,WAAW,GAAG,IAAI,CAAC;gBACnB,UAAU,GAAG,2CAA2C,CAAC;gBACzD,MAAM;YAER,KAAK,GAAG;gBACN,IAAI,GAAG,YAAY,CAAC,iBAAiB,CAAC;gBACtC,OAAO,GAAG,mBAAmB,CAAC;gBAC9B,WAAW,GAAG,KAAK,CAAC;gBACpB,UAAU;oBACR,qEAAqE,CAAC;gBACxE,MAAM;YAER,KAAK,GAAG;gBACN,IAAI,GAAG,YAAY,CAAC,kBAAkB,CAAC;gBACvC,OAAO,GAAG,oBAAoB,CAAC;gBAC/B,WAAW,GAAG,KAAK,CAAC;gBACpB,UAAU;oBACR,wEAAwE,CAAC;gBAC3E,MAAM;YAER,KAAK,GAAG;gBACN,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC;gBAC7B,OAAO,GAAG,iCAAiC,CAAC;gBAC5C,WAAW,GAAG,KAAK,CAAC;gBACpB,UAAU,GAAG,8CAA8C,CAAC;gBAC5D,MAAM;YAER,KAAK,GAAG;gBACN,IAAI,GAAG,YAAY,CAAC,gBAAgB,CAAC;gBACrC,OAAO,GAAG,mBAAmB,CAAC;gBAC9B,WAAW,GAAG,IAAI,CAAC;gBACnB,UAAU,GAAG,sCAAsC,CAAC;gBACpD,MAAM;YAER,KAAK,GAAG;gBACN,IAAI,GAAG,YAAY,CAAC,YAAY,CAAC;gBACjC,OAAO,GAAG,qBAAqB,CAAC;gBAChC,WAAW,GAAG,IAAI,CAAC;gBACnB,UAAU,GAAG,2CAA2C,CAAC;gBACzD,MAAM;YAER,KAAK,GAAG,CAAC;YACT,KAAK,GAAG,CAAC;YACT,KAAK,GAAG,CAAC;YACT,KAAK,GAAG;gBACN,IAAI,GAAG,YAAY,CAAC,mBAAmB,CAAC;gBACxC,OAAO,GAAG,mCAAmC,CAAC;gBAC9C,WAAW,GAAG,IAAI,CAAC;gBACnB,UAAU;oBACR,0DAA0D,CAAC;gBAC7D,MAAM;YAER;gBACE,IAAI,GAAG,YAAY,CAAC,cAAc,CAAC;gBACnC,OAAO,GAAG,cAAc,UAAU,KAAK,UAAU,EAAE,CAAC;gBACpD,WAAW,GAAG,IAAI,CAAC;gBACnB,UAAU,GAAG,iDAAiD,CAAC;QACnE,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE;YACvC,IAAI;YACJ,OAAO;YACP,IAAI,EAAE;gBACJ,eAAe,EAAE;oBACf,IAAI,EAAE,QAAQ,UAAU,EAAE;oBAC1B,OAAO,EAAE,UAAU;iBACpB;gBACD,OAAO;gBACP,WAAW;gBACX,UAAU;aACK;SAClB,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,cAAc,GAAiC;IACnD,wBAAwB;IACxB,CAAC,mBAAmB,CAAC,YAAY,CAAC,EAAE;QAClC,OAAO,EAAE,YAAY,CAAC,iBAAiB;QACvC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG,EAAE,CAAC,4CAA4C;QAC9D,aAAa,EAAE,GAAG,EAAE,CAClB,qEAAqE;KACxE;IAED,CAAC,mBAAmB,CAAC,eAAe,CAAC,EAAE;QACrC,OAAO,EAAE,YAAY,CAAC,iBAAiB;QACvC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG,EAAE,CAAC,+BAA+B;QACjD,aAAa,EAAE,GAAG,EAAE,CAClB,uDAAuD;KAC1D;IAED,CAAC,mBAAmB,CAAC,aAAa,CAAC,EAAE;QACnC,OAAO,EAAE,YAAY,CAAC,aAAa;QACnC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG,EAAE,CAAC,0BAA0B;QAC5C,aAAa,EAAE,GAAG,EAAE,CAClB,8EAA8E;KACjF;IAED,CAAC,mBAAmB,CAAC,aAAa,CAAC,EAAE;QACnC,OAAO,EAAE,YAAY,CAAC,aAAa;QACnC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG,EAAE,CAAC,qCAAqC;QACvD,aAAa,EAAE,GAAG,EAAE,CAClB,8DAA8D;KACjE;IAED,oBAAoB;IACpB,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE;QAC/B,OAAO,EAAE,YAAY,CAAC,iBAAiB;QACvC,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,CAAC,OAAO,EAAE;QACpD,aAAa,EAAE,GAAG,EAAE,CAClB,6GAA6G;KAChH;IAED,CAAC,mBAAmB,CAAC,wBAAwB,CAAC,EAAE;QAC9C,OAAO,EAAE,YAAY,CAAC,iBAAiB;QACvC,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,6BAA6B,CAAC,CAAC,OAAO,EAAE;QAC3D,aAAa,EAAE,GAAG,EAAE,CAClB,2EAA2E;KAC9E;IAED,kBAAkB;IAClB,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE;QAC/B,OAAO,EAAE,YAAY,CAAC,kBAAkB;QACxC,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE;YAChB,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;gBACZ,OAAO,2BAA2B,CAAC,CAAC,KAAK,8BAA8B,CAAC;YAC1E,CAAC;YACD,OAAO,uBAAuB,CAAC,CAAC,OAAO,EAAE,CAAC;QAC5C,CAAC;QACD,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE;YACnB,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;gBACZ,OAAO,cAAc,CAAC,CAAC,KAAK,kFAAkF,CAAC;YACjH,CAAC;YACD,OAAO,wEAAwE,CAAC;QAClF,CAAC;KACF;IAED,oBAAoB;IACpB,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE;QACtC,OAAO,EAAE,YAAY,CAAC,gBAAgB;QACtC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE;YAChB,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;gBACZ,OAAO,sBAAsB,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;YACxD,CAAC;YACD,OAAO,qBAAqB,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1C,CAAC;QACD,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE;YACnB,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;gBACZ,OAAO,iCAAiC,CAAC,CAAC,KAAK,wCAAwC,CAAC;YAC1F,CAAC;YACD,OAAO,mEAAmE,CAAC;QAC7E,CAAC;KACF;IAED,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE;QACjC,OAAO,EAAE,YAAY,CAAC,gBAAgB;QACtC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,oBAAoB,CAAC,CAAC,OAAO,EAAE;QAClD,aAAa,EAAE,GAAG,EAAE,CAClB,oFAAoF;KACvF;IAED,gBAAgB;IAChB,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,EAAE;QACzC,OAAO,EAAE,YAAY,CAAC,YAAY;QAClC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG,EAAE,CAAC,qBAAqB;QACvC,aAAa,EAAE,GAAG,EAAE,CAClB,oFAAoF;KACvF;IAED,kBAAkB;IAClB,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE;QAC9B,OAAO,EAAE,YAAY,CAAC,QAAQ;QAC9B,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;QAC3C,aAAa,EAAE,GAAG,EAAE,CAClB,iHAAiH;KACpH;IAED,gBAAgB;IAChB,CAAC,mBAAmB,CAAC,cAAc,CAAC,EAAE;QACpC,OAAO,EAAE,YAAY,CAAC,cAAc;QACpC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG,EAAE,CAAC,yBAAyB;QAC3C,aAAa,EAAE,GAAG,EAAE,CAClB,8HAA8H;KACjI;IAED,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,EAAE;QACzC,OAAO,EAAE,YAAY,CAAC,mBAAmB;QACzC,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG,EAAE,CAAC,+CAA+C;QACjE,aAAa,EAAE,GAAG,EAAE,CAClB,iGAAiG;KACpG;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,eAAe,GAAiB;IACpC,OAAO,EAAE,YAAY,CAAC,cAAc;IACpC,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,8BAA8B;IAC9D,aAAa,EAAE,GAAG,EAAE,CAClB,mEAAmE;CACtE,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error System
+ *
+ * Comprehensive error handling for the FreshBooks MCP server.
+ *
+ * This module provides a dual-format error system:
+ * - All errors normalized to MCP JSON-RPC format for clients
+ * - Original FreshBooks errors preserved in data field for debugging
+ *
+ * @module errors
+ */
+export type { MCPError, MCPErrorData, ErrorContext, FreshBooksApiError, ErrorMapping, ToolContext, } from "./types.js";
+export { MCPErrorCode, FreshBooksErrorCode, OAuthError, } from "./types.js";
+export { ErrorMapper } from "./error-mapper.js";
+export { ErrorHandler, generateRequestId, handleError, createAuthError } from "./error-handler.js";
+import { MCPErrorCode as _MCPErrorCode } from "./types.js";
+/**
+ * Re-export commonly used error codes for convenience
+ */
+export declare const ErrorCodes: {
+    readonly PARSE_ERROR: _MCPErrorCode.PARSE_ERROR;
+    readonly INVALID_REQUEST: _MCPErrorCode.INVALID_REQUEST;
+    readonly METHOD_NOT_FOUND: _MCPErrorCode.METHOD_NOT_FOUND;
+    readonly INVALID_PARAMS: _MCPErrorCode.INVALID_PARAMS;
+    readonly INTERNAL_ERROR: _MCPErrorCode.INTERNAL_ERROR;
+    readonly NOT_AUTHENTICATED: _MCPErrorCode.NOT_AUTHENTICATED;
+    readonly TOKEN_EXPIRED: _MCPErrorCode.TOKEN_EXPIRED;
+    readonly PERMISSION_DENIED: _MCPErrorCode.PERMISSION_DENIED;
+    readonly RATE_LIMITED: _MCPErrorCode.RATE_LIMITED;
+    readonly RESOURCE_NOT_FOUND: _MCPErrorCode.RESOURCE_NOT_FOUND;
+    readonly VALIDATION_ERROR: _MCPErrorCode.VALIDATION_ERROR;
+    readonly CONFLICT: _MCPErrorCode.CONFLICT;
+    readonly SERVICE_UNAVAILABLE: _MCPErrorCode.SERVICE_UNAVAILABLE;
+    readonly NETWORK_ERROR: _MCPErrorCode.NETWORK_ERROR;
+    readonly TIMEOUT: _MCPErrorCode.TIMEOUT;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGnG,OAAO,EAAE,YAAY,IAAI,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;CAmBb,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,41 @@
+/**
+ * Error System
+ *
+ * Comprehensive error handling for the FreshBooks MCP server.
+ *
+ * This module provides a dual-format error system:
+ * - All errors normalized to MCP JSON-RPC format for clients
+ * - Original FreshBooks errors preserved in data field for debugging
+ *
+ * @module errors
+ */
+export { MCPErrorCode, FreshBooksErrorCode, OAuthError, } from "./types.js";
+// Error Mapping
+export { ErrorMapper } from "./error-mapper.js";
+// Error Handling
+export { ErrorHandler, generateRequestId, handleError, createAuthError } from "./error-handler.js";
+// Re-export MCPErrorCode enum for convenience
+import { MCPErrorCode as _MCPErrorCode } from "./types.js";
+/**
+ * Re-export commonly used error codes for convenience
+ */
+export const ErrorCodes = {
+    // JSON-RPC standard errors
+    PARSE_ERROR: _MCPErrorCode.PARSE_ERROR,
+    INVALID_REQUEST: _MCPErrorCode.INVALID_REQUEST,
+    METHOD_NOT_FOUND: _MCPErrorCode.METHOD_NOT_FOUND,
+    INVALID_PARAMS: _MCPErrorCode.INVALID_PARAMS,
+    INTERNAL_ERROR: _MCPErrorCode.INTERNAL_ERROR,
+    // Application errors
+    NOT_AUTHENTICATED: _MCPErrorCode.NOT_AUTHENTICATED,
+    TOKEN_EXPIRED: _MCPErrorCode.TOKEN_EXPIRED,
+    PERMISSION_DENIED: _MCPErrorCode.PERMISSION_DENIED,
+    RATE_LIMITED: _MCPErrorCode.RATE_LIMITED,
+    RESOURCE_NOT_FOUND: _MCPErrorCode.RESOURCE_NOT_FOUND,
+    VALIDATION_ERROR: _MCPErrorCode.VALIDATION_ERROR,
+    CONFLICT: _MCPErrorCode.CONFLICT,
+    SERVICE_UNAVAILABLE: _MCPErrorCode.SERVICE_UNAVAILABLE,
+    NETWORK_ERROR: _MCPErrorCode.NETWORK_ERROR,
+    TIMEOUT: _MCPErrorCode.TIMEOUT,
+};
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,gBAAgB;AAChB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEnG,8CAA8C;AAC9C,OAAO,EAAE,YAAY,IAAI,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,2BAA2B;IAC3B,WAAW,EAAE,aAAa,CAAC,WAAW;IACtC,eAAe,EAAE,aAAa,CAAC,eAAe;IAC9C,gBAAgB,EAAE,aAAa,CAAC,gBAAgB;IAChD,cAAc,EAAE,aAAa,CAAC,cAAc;IAC5C,cAAc,EAAE,aAAa,CAAC,cAAc;IAE5C,qBAAqB;IACrB,iBAAiB,EAAE,aAAa,CAAC,iBAAiB;IAClD,aAAa,EAAE,aAAa,CAAC,aAAa;IAC1C,iBAAiB,EAAE,aAAa,CAAC,iBAAiB;IAClD,YAAY,EAAE,aAAa,CAAC,YAAY;IACxC,kBAAkB,EAAE,aAAa,CAAC,kBAAkB;IACpD,gBAAgB,EAAE,aAAa,CAAC,gBAAgB;IAChD,QAAQ,EAAE,aAAa,CAAC,QAAQ;IAChC,mBAAmB,EAAE,aAAa,CAAC,mBAAmB;IACtD,aAAa,EAAE,aAAa,CAAC,aAAa;IAC1C,OAAO,EAAE,aAAa,CAAC,OAAO;CACtB,CAAC"}

package/dist/errors/response-formatter.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Response Formatter
+ *
+ * Formats errors for different output contexts:
+ * - JSON-RPC response format (for MCP protocol)
+ * - Claude-friendly text format (for display)
+ */
+import { MCPError } from "./types.js";
+/**
+ * Format MCPError for JSON-RPC 2.0 error response
+ *
+ * Creates a properly formatted JSON-RPC error response object
+ * that can be sent over the MCP protocol.
+ *
+ * @param error - The normalized MCP error
+ * @param requestId - Optional request ID (null for notifications)
+ * @returns JSON-RPC error response object
+ *
+ * @example
+ * ```typescript
+ * const response = formatErrorResponse(mcpError, "req-123");
+ * // Returns:
+ * // {
+ * //   jsonrpc: "2.0",
+ * //   id: "req-123",
+ * //   error: {
+ * //     code: -32005,
+ * //     message: "Resource not found",
+ * //     data: { ... }
+ * //   }
+ * // }
+ * ```
+ */
+export declare function formatErrorResponse(error: MCPError, requestId?: string | number | null): object;
+/**
+ * Format error for Claude-friendly display
+ *
+ * Creates a markdown-formatted, human-readable error message
+ * that Claude can present to the user with actionable guidance.
+ *
+ * @param error - The normalized MCP error
+ * @returns Formatted error message with suggestions
+ *
+ * @example
+ * ```typescript
+ * const display = formatErrorForClaude(mcpError);
+ * // Returns:
+ * // **Error:** Resource not found
+ * //
+ * // **Suggestion:** Verify the ID is correct...
+ * //
+ * // *This error cannot be recovered by retrying.*
+ * ```
+ */
+export declare function formatErrorForClaude(error: MCPError): string;
+/**
+ * Format error for logging
+ *
+ * Creates a structured log entry suitable for stderr logging.
+ * Omits sensitive information like tokens or PII.
+ *
+ * @param error - The normalized MCP error
+ * @returns Structured log object
+ *
+ * @example
+ * ```typescript
+ * const logEntry = formatErrorForLogging(mcpError);
+ * console.error(JSON.stringify(logEntry));
+ * ```
+ */
+export declare function formatErrorForLogging(error: MCPError): object;
+/**
+ * Format error details for debugging
+ *
+ * Creates a comprehensive error dump including all details
+ * for debugging purposes. Should only be used in development.
+ *
+ * @param error - The normalized MCP error
+ * @returns Detailed error information
+ */
+export declare function formatErrorForDebug(error: MCPError): object;
+/**
+ * Get error summary
+ *
+ * Returns a brief one-line summary of the error.
+ *
+ * @param error - The normalized MCP error
+ * @returns Brief error summary
+ */
+export declare function getErrorSummary(error: MCPError): string;
+/**
+ * Check if error is retryable
+ *
+ * Determines if the error can be resolved by retrying.
+ *
+ * @param error - The normalized MCP error
+ * @returns True if error is retryable
+ */
+export declare function isRetryable(error: MCPError): boolean;
+/**
+ * Get suggested retry delay
+ *
+ * Returns the suggested delay before retrying (in milliseconds).
+ *
+ * @param error - The normalized MCP error
+ * @returns Delay in milliseconds, or undefined if not retryable
+ */
+export declare function getRetryDelay(error: MCPError): number | undefined;
+//# sourceMappingURL=response-formatter.d.ts.map

package/dist/errors/response-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-formatter.d.ts","sourceRoot":"","sources":["../../src/errors/response-formatter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,QAAQ,EACf,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GACjC,MAAM,CAUR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAgD5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAgB7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAW3D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAYvD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAqBjE"}