@juspay/neurolink 11.13.0 → 11.13.2

package/dist/lib/utils/errorHandling.d.ts

@@ -1,398 +0,0 @@
-/**
- * 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 PROXY_WORKER_LIFECYCLE_FAILED: "PROXY_WORKER_LIFECYCLE_FAILED";
-    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 INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE";
-    readonly IMAGE_BUFFER_INVALID: "IMAGE_BUFFER_INVALID";
-    readonly FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED";
-    readonly CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED";
-    readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
-    readonly PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED: "PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED";
-    readonly PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED: "PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED";
-    readonly PDF_PAGE_COUNT_UNVERIFIABLE: "PDF_PAGE_COUNT_UNVERIFIABLE";
-    readonly PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED";
-    readonly PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD";
-    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";
-    readonly CSV_INVALID_INPUT: "CSV_INVALID_INPUT";
-    readonly CSV_ROW_INVALID: "CSV_ROW_INVALID";
-    readonly CSV_FILE_ACCESS_FAILED: "CSV_FILE_ACCESS_FAILED";
-    readonly CSV_PARSE_FAILED: "CSV_PARSE_FAILED";
-};
-/**
- * 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 retryAfterMs?: number;
-    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;
-        retryAfterMs?: number;
-        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 CSV input error (e.g. an empty filePath/csvString argument).
-     */
-    static csvInvalidInput(message: string): NeuroLinkError;
-    /**
-     * Create a CSV row-shape violation error (#384) — a parsed row that isn't a
-     * string-keyed object with string values.
-     */
-    static csvRowInvalid(message: string, rowNumber: number): NeuroLinkError;
-    /**
-     * Create a CSV file access error (bad path, permissions, ENOENT/EACCES) (#375).
-     */
-    static csvFileAccessFailed(message: string, filePath: string, originalError?: Error): NeuroLinkError;
-    /**
-     * Create a CSV read/parse failure error (#375) — source stream errors and
-     * csv-parser errors both route through this, carrying the enriched
-     * `buildCsvParseErrorMessage` context in `message`.
-     */
-    static csvParseFailed(message: string, context: Record<string, unknown>, originalError?: Error): 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;
-    /**
-     * The combined page count across every PDF in one request exceeds what the
-     * provider accepts (#309). Distinct from `pdfPageLimitExceeded`, which is
-     * per-file — here each document can be individually legal.
-     */
-    static pdfAggregatePageLimitExceeded(fileCount: number, totalPages: number, maxPages: number, provider: string): NeuroLinkError;
-    /**
-     * The combined byte size across every PDF in one request exceeds what the
-     * provider accepts (#309).
-     */
-    static pdfAggregateSizeLimitExceeded(fileCount: number, totalMB: number, maxSizeMB: number, provider: string): NeuroLinkError;
-    /**
-     * A PDF supplied through the untrusted `input.content` surface could not be
-     * parsed for a page count (#309). Caller-supplied `metadata.pages` is not
-     * authoritative there, so an unreadable document is rejected rather than
-     * admitted with an assumed count of zero.
-     */
-    static pdfPageCountUnverifiable(filenames: string[], provider: string): NeuroLinkError;
-    /**
-     * The PDF is encrypted and no password was supplied (#258).
-     */
-    static pdfPasswordRequired(): NeuroLinkError;
-    /**
-     * A password was supplied for an encrypted PDF but it was incorrect (#258).
-     */
-    static pdfIncorrectPassword(): NeuroLinkError;
-    /**
-     * Create an image too large error
-     */
-    static imageTooLarge(sizeMB: string, maxMB: string): NeuroLinkError;
-    /**
-     * Create an invalid image size error (NaN/Infinity/negative byte length).
-     * Distinct from `imageTooLarge` — this rejects a malformed size value
-     * before it reaches the max-size comparison, since `NaN > maxSize` and
-     * `-1 > maxSize` both evaluate to `false` and would otherwise let a
-     * corrupted stat/header value silently skip the guard.
-     */
-    static invalidImageSize(size: number): NeuroLinkError;
-    /**
-     * Create an image too small error
-     */
-    static imageTooSmall(): NeuroLinkError;
-    /**
-     * Create an invalid image format error
-     */
-    static invalidImageFormat(): NeuroLinkError;
-    /**
-     * Create an image buffer validation error: empty, undersized, or a
-     * truncated buffer detected by `ImageProcessor.validateBufferNotEmpty()`.
-     * Takes the fully-formed message so call sites keep their specific
-     * byte-count detail instead of a fixed generic message.
-     */
-    static imageBufferInvalid(message: string): 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;
-    /**
-     * Create a proxy rolling-worker lifecycle error. Preserves the caller's exact
-     * message so existing substring-based assertions keep working, while giving
-     * callers a typed `code`/`category` to branch on instead of string-matching
-     * generic `Error` instances.
-     */
-    static proxyWorkerLifecycle(message: string, context?: Record<string, unknown>): NeuroLinkError;
-    /**
-     * Create a generic file-processing-failed error (e.g. an unrecognized or
-     * corrupt file in `processUnifiedFilesArray`). Preserves the original error
-     * as `originalError` (stack + message copied onto the new error's context).
-     */
-    static fileProcessingFailed(filename: string, originalError: Error): NeuroLinkError;
-    /**
-     * Create a generic CSV-processing-failed error (explicit `csvFiles` path,
-     * distinct from `fileProcessingFailed` so callers can classify CSV-specific
-     * failures separately). Preserves the original error as `originalError`.
-     */
-    static csvProcessingFailed(filename: 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;