@juspay/neurolink
Version:
Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applicatio
304 lines (303 loc) • 11.7 kB
TypeScript
/**
* Robust Error Handling Utilities for NeuroLink
* Provides structured error management for tool execution and system operations
*/
import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
import type { StructuredError } from "../types/index.js";
export declare const ERROR_CODES: {
readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
readonly TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED";
readonly TOOL_TIMEOUT: "TOOL_TIMEOUT";
readonly TOOL_VALIDATION_FAILED: "TOOL_VALIDATION_FAILED";
readonly INVALID_PARAMETERS: "INVALID_PARAMETERS";
readonly MISSING_REQUIRED_PARAM: "MISSING_REQUIRED_PARAM";
readonly MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED";
readonly NETWORK_ERROR: "NETWORK_ERROR";
readonly PERMISSION_DENIED: "PERMISSION_DENIED";
readonly PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE";
readonly PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED";
readonly PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED";
readonly OPERATION_ABORTED: "OPERATION_ABORTED";
readonly INVALID_CONFIGURATION: "INVALID_CONFIGURATION";
readonly MISSING_CONFIGURATION: "MISSING_CONFIGURATION";
readonly INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION";
readonly INVALID_VIDEO_LENGTH: "INVALID_VIDEO_LENGTH";
readonly INVALID_VIDEO_ASPECT_RATIO: "INVALID_VIDEO_ASPECT_RATIO";
readonly INVALID_VIDEO_AUDIO: "INVALID_VIDEO_AUDIO";
readonly INVALID_VIDEO_MODE: "INVALID_VIDEO_MODE";
readonly MISSING_VIDEO_IMAGE: "MISSING_VIDEO_IMAGE";
readonly EMPTY_VIDEO_PROMPT: "EMPTY_VIDEO_PROMPT";
readonly VIDEO_PROMPT_TOO_LONG: "VIDEO_PROMPT_TOO_LONG";
readonly EMPTY_IMAGE_PATH: "EMPTY_IMAGE_PATH";
readonly INVALID_IMAGE_TYPE: "INVALID_IMAGE_TYPE";
readonly IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE";
readonly IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL";
readonly INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT";
readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
readonly RATE_LIMITER_RESET: "RATE_LIMITER_RESET";
readonly SCORER_NOT_FOUND: "SCORER_NOT_FOUND";
readonly EVALUATION_VALIDATION_FAILED: "EVALUATION_VALIDATION_FAILED";
readonly EVALUATION_TIMEOUT: "EVALUATION_TIMEOUT";
readonly EVALUATION_EXECUTION_FAILED: "EVALUATION_EXECUTION_FAILED";
readonly MISSING_PPT_PROPERTIES: "MISSING_PPT_PROPERTIES";
readonly INVALID_PPT_PAGES: "INVALID_PPT_PAGES";
readonly INVALID_PPT_FORMAT: "INVALID_PPT_FORMAT";
readonly INVALID_PPT_PROVIDER: "INVALID_PPT_PROVIDER";
readonly INVALID_PPT_OUTPUT_OPTIONS: "INVALID_PPT_OUTPUT_OPTIONS";
readonly INVALID_PPT_OUTPUT_PATH: "INVALID_PPT_OUTPUT_PATH";
readonly INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH";
readonly INVALID_PPT_MODE: "INVALID_PPT_MODE";
readonly INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT";
};
/**
* Enhanced error class with structured information
*/
export declare class NeuroLinkError extends Error {
readonly code: string;
readonly category: ErrorCategory;
readonly severity: ErrorSeverity;
readonly retriable: boolean;
readonly context: Record<string, unknown>;
readonly timestamp: Date;
readonly toolName?: string;
readonly serverId?: string;
constructor(options: {
code: string;
message: string;
category: ErrorCategory;
severity: ErrorSeverity;
retriable: boolean;
context?: Record<string, unknown>;
originalError?: Error;
toolName?: string;
serverId?: string;
});
/**
* Convert to JSON for logging and serialization
*/
toJSON(): StructuredError;
}
/**
* Error factory for common error scenarios
*/
export declare class ErrorFactory {
/**
* Create a tool not found error
*/
static toolNotFound(toolName: string, availableTools?: string[]): NeuroLinkError;
/**
* Create a tool execution failed error
*/
static toolExecutionFailed(toolName: string, originalError: Error, serverId?: string): NeuroLinkError;
/**
* Create a tool timeout error
*/
static toolTimeout(toolName: string, timeoutMs: number, serverId?: string): NeuroLinkError;
/**
* Create a parameter validation error
*/
static invalidParameters(toolName: string, validationError: Error, providedParams?: unknown): NeuroLinkError;
/**
* Create a network error
*/
static networkError(toolName: string, originalError: Error, serverId?: string): NeuroLinkError;
/**
* Create a memory exhaustion error
*/
static memoryExhausted(toolName: string, memoryUsageMB: number): NeuroLinkError;
/**
* Create a typed abort error preserving the originating exception. Callers
* can switch on `error.category === ErrorCategory.ABORT` and
* `error.code === ERROR_CODES.OPERATION_ABORTED` instead of message-string
* matching DOMException / AI SDK error wrappers.
*
* `error.name` is intentionally set to "AbortError" (overriding the default
* "NeuroLinkError") so existing callers that branch on
* `err.name === "AbortError"` keep working without code changes — the new
* structured fields (category, code, retriable) are additive.
*/
static aborted(originalError?: Error): NeuroLinkError;
/**
* Create a missing configuration error (e.g., missing API key)
*/
static missingConfiguration(configName: string, context?: Record<string, unknown>): NeuroLinkError;
/**
* Create an invalid configuration error (e.g., NaN for numeric values)
*/
static invalidConfiguration(configName: string, reason: string, context?: Record<string, unknown>): NeuroLinkError;
/**
* Create an invalid video resolution error
*/
static invalidVideoResolution(resolution: string): NeuroLinkError;
/**
* Create an invalid video length error
*/
static invalidVideoLength(length: number): NeuroLinkError;
/**
* Create an invalid video aspect ratio error
*/
static invalidVideoAspectRatio(aspectRatio: string): NeuroLinkError;
/**
* Create an invalid video audio option error
*/
static invalidVideoAudio(audio: unknown): NeuroLinkError;
/**
* Create an invalid video mode error
*/
static invalidVideoMode(): NeuroLinkError;
/**
* Create a missing video image error
*/
static missingVideoImage(): NeuroLinkError;
/**
* Create an empty video prompt error
*/
static emptyVideoPrompt(): NeuroLinkError;
/**
* Create a video prompt too long error
*/
static videoPromptTooLong(length: number, maxLength: number): NeuroLinkError;
/**
* Create an empty image path error
*/
static emptyImagePath(): NeuroLinkError;
/**
* Create an invalid image type error
*/
static invalidImageType(): NeuroLinkError;
/**
* Create a PDF page limit exceeded error
*/
static pdfPageLimitExceeded(estimatedPages: number, maxPages: number, provider: string): NeuroLinkError;
/**
* Create an image too large error
*/
static imageTooLarge(sizeMB: string, maxMB: string): NeuroLinkError;
/**
* Create an image too small error
*/
static imageTooSmall(): NeuroLinkError;
/**
* Create an invalid image format error
*/
static invalidImageFormat(): NeuroLinkError;
/**
* Create a rate limiter queue full error
*/
static rateLimiterQueueFull(maxQueueSize: number): NeuroLinkError;
/**
* Create a rate limiter queue timeout error
*/
static rateLimiterQueueTimeout(timeoutMs: number): NeuroLinkError;
/**
* Create a rate limiter reset error
*/
static rateLimiterReset(): NeuroLinkError;
/**
* Create a generic missing PPT property error
*/
static missingPPTProperty(field: string, suggestions?: string[]): NeuroLinkError;
/**
* Create an invalid PPT pages error
*/
static invalidPPTPages(pages: unknown, reason: string): NeuroLinkError;
/**
* Create an invalid PPT format error
*/
static invalidPPTFormat(format: string): NeuroLinkError;
/**
* Create a generic invalid PPT output options error
*/
static invalidPPTOutputOptions(field: string, value: unknown, validOptions?: string[]): NeuroLinkError;
/**
* Create an invalid PPT output path error
*/
static invalidPPTOutputPath(path: unknown, reason: string): NeuroLinkError;
/**
* Create an invalid PPT mode error
*/
static invalidPPTMode(): NeuroLinkError;
/**
* Create an invalid PPT prompt error
*/
static invalidPPTPrompt(reason: string): NeuroLinkError;
/**
* Create an invalid PPT logo path error
*/
static invalidPPTLogoPath(path: unknown, reason: string): NeuroLinkError;
/**
* Create an invalid PPT provider error
*/
static invalidPPTProvider(provider: unknown): NeuroLinkError;
/**
* Create a scorer not found error
*/
static scorerNotFound(scorerId: string, availableScorers?: string[]): NeuroLinkError;
/**
* Create an evaluation validation error
*/
static evaluationValidationFailed(scorerId: string, errors: string[]): NeuroLinkError;
/**
* Create an evaluation timeout error
*/
static evaluationTimeout(operation: string, timeoutMs: number): NeuroLinkError;
/**
* Create an evaluation execution failed error
*/
static evaluationExecutionFailed(operation: string, originalError: Error): NeuroLinkError;
}
/**
* Timeout wrapper for async operations
*/
export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutError?: Error): Promise<T>;
/**
* Retry mechanism for retriable operations
*/
export declare function withRetry<T>(operation: () => Promise<T>, options: {
maxAttempts: number;
delayMs: number;
isRetriable?: (error: Error) => boolean;
onRetry?: (attempt: number, error: Error) => void;
}): Promise<T>;
/**
* Circuit breaker for preventing cascading failures
*/
export declare class CircuitBreaker {
private readonly failureThreshold;
private readonly resetTimeoutMs;
private failures;
private lastFailureTime;
private state;
private name;
constructor(failureThreshold?: number, resetTimeoutMs?: number, name?: string);
execute<T>(operation: () => Promise<T>): Promise<T>;
private onSuccess;
private onFailure;
getState(): "closed" | "open" | "half-open";
getFailureCount(): number;
}
/**
* Detect AbortError from any source (DOMException, plain Error, or message-based).
* Used to short-circuit retry/fallback loops when an abort signal fires.
*
* Uses `includes()` for message checks because provider error handlers
* (e.g., googleVertex.formatProviderError) wrap the original AbortError
* in a formatted error like "❌ Provider Error\n\nThis operation was aborted\n\n..."
* which destroys the exact message match.
*/
export declare function isAbortError(error: unknown): boolean;
/**
* Error handler that decides whether to retry based on error type
*/
export declare function isRetriableError(error: Error): boolean;
/**
* Determines if an error is likely recoverable (rate limit, timeout, network issues).
* Useful for deciding whether to retry or fail fast.
*/
export declare function isRecoverableError(error: Error): boolean;
/**
* Enhanced error logger that provides structured logging
*/
export declare function logStructuredError(error: NeuroLinkError, context?: Record<string, unknown>): void;