voyage-and-consumption-mcp-server/dist/middleware/error-handler.d.ts

Voyage and consumption management server handling vessel voyages, fuel consumption, performance monitoring, and operational data with ERP access for data extraction

/**
 * Error Handling Middleware
 *
 * Centralizes error handling logic that was duplicated across
 * 29+ catch blocks in the codebase.
 *
 * This middleware standardizes:
 * - Error classification and type checking
 * - Error logging with consistent formatting
 * - Error response formatting for tools
 * - Service-specific error handling
 * - Parameter validation error handling
 */
import { ResponseArray } from '../utils/response-formatter.js';
export declare class MissingParameterError extends Error {
    param: string;
    tool_name: string;
    constructor(param: string, tool_name: string);
}
export declare class NavtorServiceError extends Error {
    original_error?: Error;
    constructor(message: string, original_error?: Error);
}
export declare class SiyaServiceError extends Error {
    original_error?: Error;
    constructor(message: string, original_error?: Error);
}
export declare class StormglassServiceError extends Error {
    original_error?: Error;
    constructor(message: string, original_error?: Error);
}
export declare class VesselPositionError extends Error {
    imo: string;
    constructor(imo: string);
}
export declare class VesselFuelConsumptionError extends Error {
    imo: string;
    constructor(imo: string);
}
export declare class VesselEtaError extends Error {
    imo: string;
    constructor(imo: string);
}
export declare class WeatherDataError extends Error {
    coordinates: string;
    constructor(coordinates: string, message?: string);
}
export declare class SearchError extends Error {
    query: string;
    original_error?: Error;
    constructor(query: string, message?: string, original_error?: Error);
}
export declare class MongoDBError extends Error {
    original_error?: Error;
    constructor(message: string, original_error?: Error);
}
export declare function isParameterError(error: any): error is MissingParameterError;
export declare function isServiceError(error: any): boolean;
export declare function isVesselDataError(error: any): boolean;
export declare function isDatabaseError(error: any): error is MongoDBError;
/**
 * Logs errors with consistent formatting
 * @param error - The error to log
 * @param context - Additional context for the error
 * @param imo - Optional IMO number for context
 */
export declare function logError(error: Error | string, context?: string, imo?: string | number): void;
/**
 * Creates a standardized error response for tools
 * @param error - The error to format
 * @param context - Optional context for the error
 * @param imo - Optional IMO number for context
 * @returns Formatted error response array
 */
export declare function createToolErrorResponse(error: Error | string, context?: string, imo?: string | number): ResponseArray;
/**
 * Handles API authentication errors with specific response formatting
 * @param response - The HTTP response object
 * @param responseText - The response body text
 * @param service - The service name (e.g., "NAVTOR", "SIYA")
 * @returns Error object with detailed message
 */
export declare function handleAuthenticationError(response: {
    status: number;
    ok: boolean;
}, responseText: string, service: string): Error;
/**
 * Handles JSON parsing errors with context
 * @param responseText - The response text that failed to parse
 * @param service - The service name
 * @returns Error object with detailed message
 */
export declare function handleJsonParsingError(responseText: string, service: string): Error;
/**
 * Validates API response and throws appropriate errors
 * @param response - The API response to validate
 * @param imo - The IMO number for context
 * @param errorClass - The error class to throw if validation fails
 * @param customMessage - Optional custom error message
 */
export declare function validateApiResponse(response: any, imo: string | number, errorClass: new (imo: string) => Error, customMessage?: string): void;
/**
 * Wraps a tool method with standardized error handling
 * @param toolMethod - The tool method to execute
 * @param toolName - The name of the tool for error context
 * @param imo - Optional IMO number for context
 * @returns Promise that resolves to tool response or error response
 */
export declare function withErrorHandling<T>(toolMethod: () => Promise<T>, toolName: string, imo?: string | number): Promise<T | ResponseArray>;
/**
 * Handles parameter validation errors consistently
 * @param parameterName - The name of the missing parameter
 * @param toolName - The name of the tool
 * @throws MissingParameterError
 */
export declare function validateRequiredParameter(value: any, parameterName: string, toolName: string): void;
/**
 * Handles multiple parameter validation
 * @param parameters - Object with parameter names and values
 * @param toolName - The name of the tool
 * @throws MissingParameterError for the first missing parameter
 */
export declare function validateRequiredParameters(parameters: Record<string, any>, toolName: string): void;
/**
 * Creates a graceful error handler that returns null instead of throwing
 * @param operation - The operation to execute
 * @param context - Context for logging
 * @returns Result of operation or null if error occurs
 */
export declare function withGracefulHandling<T>(operation: () => Promise<T>, context: string): Promise<T | null>;
/**
 * Standardizes error handling for database operations
 * @param operation - The database operation to execute
 * @param context - Context for the operation
 * @param imo - Optional IMO for context
 * @returns Result or throws MongoDBError
 */
export declare function withDatabaseErrorHandling<T>(operation: () => Promise<T>, context: string, imo?: string | number): Promise<T>;