firewalla-mcp-server/dist/validation/error-classification.d.ts

Model Context Protocol (MCP) server for Firewalla MSP API - Provides real-time network monitoring, security analysis, and firewall management through 28 specialized tools compatible with any MCP client

/**
 * Error Classification and Standardization Utilities for Firewalla MCP Server
 * Provides consistent error classification, response formatting, and troubleshooting guidance
 */
import { ErrorType } from './error-handler.js';
/**
 * Common error patterns and their classifications
 */
export declare const ERROR_PATTERNS: {
    readonly NETWORK_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
    readonly AUTH_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
    readonly NOT_FOUND_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp];
    readonly RATE_LIMIT_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp];
    readonly TIMEOUT_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp];
    readonly VALIDATION_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
    readonly CACHE_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp];
    readonly CORRELATION_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
    readonly SEARCH_ERRORS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
};
/**
 * Error context information for better troubleshooting
 */
export interface ErrorContext {
    /** Tool name where error occurred */
    toolName: string;
    /** Operation being performed */
    operation?: string;
    /** Parameters passed to the operation */
    parameters?: Record<string, unknown>;
    /** Original error object */
    originalError?: Error;
    /** Additional context information */
    context?: Record<string, unknown>;
}
/**
 * Standardized troubleshooting suggestions by error type
 */
export declare const TROUBLESHOOTING_GUIDES: {
    readonly validation_error: readonly ["Check that all required parameters are provided", "Verify parameter types and formats match expectations", "Review parameter value ranges and constraints", "Ensure special characters are properly escaped"];
    readonly authentication_error: readonly ["Verify your API token is valid and not expired", "Check that the token has necessary permissions", "Ensure the MSP domain is correct", "Try regenerating your access token"];
    readonly api_error: readonly ["Check if the Firewalla API is accessible", "Verify network connectivity to the MSP endpoint", "Ensure the resource exists and is accessible", "Check for API service outages or maintenance"];
    readonly network_error: readonly ["Verify internet connectivity", "Check firewall and proxy settings", "Ensure DNS resolution is working", "Try again after a brief delay"];
    readonly timeout_error: readonly ["Reduce the scope of your query (smaller limit, shorter time range)", "Try breaking large operations into smaller chunks", "Check for network latency issues", "Consider using pagination for large datasets"];
    readonly rate_limit_error: readonly ["Implement delays between API calls", "Reduce the frequency of requests", "Use caching to minimize duplicate requests", "Contact support if limits seem unreasonable"];
    readonly cache_error: readonly ["Clear local cache and retry", "Check cache service availability", "Try disabling cache temporarily", "Verify cache configuration settings"];
    readonly correlation_error: readonly ["Simplify correlation queries", "Check field names and availability", "Reduce the number of correlation fields", "Verify data types match for correlation"];
    readonly search_error: readonly ["Verify search query syntax", "Check field names and operators", "Simplify complex search expressions", "Try using exact matches instead of wildcards"];
    readonly service_unavailable: readonly ["Check if the MCP server is running in safe mode", "Verify the WAVE0_ENABLED environment variable is not set to false", "Wait for service maintenance to complete", "Try again after a short delay"];
    readonly tool_disabled: readonly ["Check if the tool is listed in MCP_DISABLED_TOOLS environment variable", "Verify the tool name is spelled correctly", "Contact administrator to enable the tool", "Use alternative tools if available"];
    readonly unknown_error: readonly ["Check the detailed error message for clues", "Try the operation again after a short delay", "Verify all parameters are correct", "Contact support if the issue persists"];
};
/**
 * Documentation links by error type
 */
export declare const DOCUMENTATION_LINKS: {
    readonly validation_error: "/docs/parameter-validation-guide.md";
    readonly authentication_error: "/docs/authentication-guide.md";
    readonly api_error: "/docs/firewalla-api-reference.md";
    readonly network_error: "/docs/troubleshooting-guide.md#network-issues";
    readonly timeout_error: "/docs/performance-optimization-guide.md";
    readonly rate_limit_error: "/docs/rate-limiting-guide.md";
    readonly cache_error: "/docs/caching-guide.md";
    readonly correlation_error: "/docs/correlation-guide.md";
    readonly search_error: "/docs/query-syntax-guide.md";
    readonly service_unavailable: "/docs/troubleshooting-guide.md";
    readonly tool_disabled: "/docs/feature-flags-guide.md";
    readonly unknown_error: "/docs/troubleshooting-guide.md";
};
/**
 * Error classification utility
 */
export declare class ErrorClassifier {
    /**
     * Classify an error based on its message and context with improved timeout detection
     */
    static classifyError(error: Error | string, context?: ErrorContext): ErrorType;
    /**
     * Create a standardized error response with proper classification
     */
    static createStandardizedErrorResponse(error: Error | string, context: ErrorContext): {
        content: Array<{
            type: string;
            text: string;
        }>;
        isError: true;
    };
    /**
     * Generate user-friendly error messages
     */
    private static generateUserFriendlyMessage;
    /**
     * Enhance existing error responses with standardized classification
     */
    static enhanceErrorResponse(existingResponse: any, error: Error | string, context: ErrorContext): any;
    /**
     * Check if an error is likely a timeout that should be reclassified
     */
    static isLikelyMisclassifiedTimeout(error: Error | string, duration?: number): boolean;
    /**
     * Get error statistics for monitoring
     */
    static getErrorStats(): {
        classifications: Record<string, number>;
        commonPatterns: Array<{
            pattern: string;
            count: number;
        }>;
    };
}
/**
 * Convenience function for creating standardized error responses
 */
export declare function createStandardizedError(error: Error | string, toolName: string, operation?: string, parameters?: Record<string, unknown>): {
    content: Array<{
        type: string;
        text: string;
    }>;
    isError: true;
};
/**
 * Convenience function for enhancing existing error responses
 */
export declare function enhanceExistingError(existingResponse: any, error: Error | string, toolName: string, operation?: string): any;
//# sourceMappingURL=error-classification.d.ts.map