voyage-and-consumption-mcp-server/dist/utils/response-formatter.d.ts

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

/**
 * Response Formatter Utility
 *
 * Centralizes response formatting logic that was duplicated across
 * 76+ response patterns in the codebase.
 *
 * This utility extracts common patterns:
 * - IMO-based title generation (20+ instances)
 * - JSON response formatting with type/format structure
 * - Dual response patterns (main + artifact data)
 * - Error response formatting (40+ instances)
 * - Consistent response object structures
 */
export interface ResponseObject {
    [key: string]: unknown;
    type: "text";
    text: string;
    title?: string;
    format?: "json";
}
export type ResponseArray = ResponseObject[];
export declare class MissingParameterError extends Error {
    param: string;
    tool_name: string;
    constructor(param: string, tool_name: string);
}
/**
 * Creates a formatted JSON response with consistent structure
 * @param data - The data to serialize as JSON
 * @param title - Optional title for the response
 * @returns Formatted response object
 */
export declare function formatJsonResponse(data: any, title?: string): ResponseObject;
/**
 * Creates a simple text response
 * @param text - The text content
 * @param title - Optional title for the response
 * @returns Formatted response object
 */
export declare function formatTextResponse(text: string, title?: string): ResponseObject;
/**
 * Generates IMO-based titles with consistent formatting
 * @param action - The action description (e.g., "Fuel consumption data", "Live position and ETA")
 * @param imo - The IMO number (string or number)
 * @returns Formatted title string
 */
export declare function generateImoTitle(action: string, imo: string | number): string;
/**
 * Generates query-based titles for search operations
 * @param action - The action description (e.g., "Smart voyage search results")
 * @param query - The search query
 * @returns Formatted title string
 */
export declare function generateQueryTitle(action: string, query: string): string;
/**
 * Creates a standard vessel data response with IMO-based title
 * @param data - The vessel data to return
 * @param action - The action description for the title
 * @param imo - The IMO number
 * @returns Formatted response array
 */
export declare function createVesselDataResponse(data: any, action: string, imo: string | number): ResponseArray;
/**
 * Creates a dual response pattern (main data + artifact)
 * @param mainData - The primary response data
 * @param artifactData - The artifact data (usually with additional metadata)
 * @param action - The action description for titles
 * @param imo - The IMO number
 * @returns Array with both main and artifact responses
 */
export declare function createDualResponse(mainData: any, artifactData: any, action: string, imo: string | number): ResponseArray;
/**
 * Creates a search results response with conditional artifact
 * @param mainContent - The primary search results
 * @param artifactData - Optional artifact data
 * @param query - The search query
 * @param action - The action description
 * @returns Response array with optional artifact
 */
export declare function createSearchResponse(mainContent: ResponseObject, artifactData: any | null, query: string, action?: string): ResponseArray;
/**
 * Creates an error response with consistent formatting
 * @param error - The error object or message
 * @param context - Optional context information
 * @param imo - Optional IMO number for context
 * @returns Formatted error response array
 */
export declare function createErrorResponse(error: Error | string, context?: string, imo?: string | number): ResponseArray;
/**
 * Creates a service-specific error response
 * @param error - The error object
 * @param serviceName - The name of the service that failed
 * @param imo - Optional IMO number for context
 * @returns Formatted error response array
 */
export declare function createServiceErrorResponse(error: Error, serviceName: string, imo?: string | number): ResponseArray;
/**
 * Creates artifact data with standard structure
 * @param toolName - The name of the tool generating the artifact
 * @param url - Optional URL for the artifact
 * @returns Artifact object with standard metadata
 */
export declare function createArtifactData(toolName: string, url?: string): any;
/**
 * Creates a historical data response with consistent formatting
 * @param documents - Array of historical data documents
 * @param action - The action description
 * @param imo - The IMO number
 * @param totalRecords - Optional total record count
 * @returns Formatted response for historical data
 */
export declare function createHistoricalDataResponse(documents: any[], action: string, imo: string | number, totalRecords?: number): ResponseArray;
/**
 * Creates a casefile operation response
 * @param data - The casefile data
 * @param operation - The operation performed (e.g., "created", "updated")
 * @param casefileId - The casefile ID
 * @returns Formatted casefile response
 */
export declare function createCasefileResponse(data: any, operation: string, casefileId: string): ResponseArray;
/**
 * Wraps any response creation with error handling
 * @param responseCreator - Function that creates the response
 * @param errorContext - Context for error messages
 * @param imo - Optional IMO for error context
 * @returns Response array or error response
 */
export declare function withErrorHandling(responseCreator: () => ResponseArray, errorContext: string, imo?: string | number): ResponseArray;