@juspay/neurolink 11.12.0 → 11.13.1

package/dist/lib/utils/errorHandling.js

@@ -1,1282 +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 { logger } from "./logger.js";
-import { CircuitBreakerOpenError } from "../types/index.js";
-import { HITLTimeoutError } from "../hitl/hitlErrors.js";
-// Error codes for different scenarios
-export const ERROR_CODES = {
-    // Tool errors
-    TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
-    TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
-    TOOL_TIMEOUT: "TOOL_TIMEOUT",
-    TOOL_VALIDATION_FAILED: "TOOL_VALIDATION_FAILED",
-    // Parameter errors
-    INVALID_PARAMETERS: "INVALID_PARAMETERS",
-    MISSING_REQUIRED_PARAM: "MISSING_REQUIRED_PARAM",
-    // System errors
-    MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED",
-    NETWORK_ERROR: "NETWORK_ERROR",
-    PERMISSION_DENIED: "PERMISSION_DENIED",
-    PROXY_WORKER_LIFECYCLE_FAILED: "PROXY_WORKER_LIFECYCLE_FAILED",
-    // Provider errors
-    PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE",
-    PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
-    PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED",
-    // Cancellation
-    OPERATION_ABORTED: "OPERATION_ABORTED",
-    // Configuration errors
-    INVALID_CONFIGURATION: "INVALID_CONFIGURATION",
-    MISSING_CONFIGURATION: "MISSING_CONFIGURATION",
-    // Video validation errors
-    INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION",
-    INVALID_VIDEO_LENGTH: "INVALID_VIDEO_LENGTH",
-    INVALID_VIDEO_ASPECT_RATIO: "INVALID_VIDEO_ASPECT_RATIO",
-    INVALID_VIDEO_AUDIO: "INVALID_VIDEO_AUDIO",
-    INVALID_VIDEO_MODE: "INVALID_VIDEO_MODE",
-    MISSING_VIDEO_IMAGE: "MISSING_VIDEO_IMAGE",
-    EMPTY_VIDEO_PROMPT: "EMPTY_VIDEO_PROMPT",
-    VIDEO_PROMPT_TOO_LONG: "VIDEO_PROMPT_TOO_LONG",
-    // Image validation errors
-    EMPTY_IMAGE_PATH: "EMPTY_IMAGE_PATH",
-    INVALID_IMAGE_TYPE: "INVALID_IMAGE_TYPE",
-    IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE",
-    IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL",
-    INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT",
-    INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE",
-    IMAGE_BUFFER_INVALID: "IMAGE_BUFFER_INVALID",
-    // Generic file/CSV processing errors
-    FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED",
-    CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
-    // PDF validation errors
-    PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
-    PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED: "PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED",
-    PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED: "PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED",
-    PDF_PAGE_COUNT_UNVERIFIABLE: "PDF_PAGE_COUNT_UNVERIFIABLE",
-    PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED",
-    PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD",
-    // Rate limiter errors
-    RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL",
-    RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT",
-    RATE_LIMITER_RESET: "RATE_LIMITER_RESET",
-    // Evaluation errors
-    SCORER_NOT_FOUND: "SCORER_NOT_FOUND",
-    EVALUATION_VALIDATION_FAILED: "EVALUATION_VALIDATION_FAILED",
-    EVALUATION_TIMEOUT: "EVALUATION_TIMEOUT",
-    EVALUATION_EXECUTION_FAILED: "EVALUATION_EXECUTION_FAILED",
-    // PPT validation errors
-    MISSING_PPT_PROPERTIES: "MISSING_PPT_PROPERTIES",
-    INVALID_PPT_PAGES: "INVALID_PPT_PAGES",
-    INVALID_PPT_FORMAT: "INVALID_PPT_FORMAT",
-    INVALID_PPT_PROVIDER: "INVALID_PPT_PROVIDER",
-    INVALID_PPT_OUTPUT_OPTIONS: "INVALID_PPT_OUTPUT_OPTIONS",
-    INVALID_PPT_OUTPUT_PATH: "INVALID_PPT_OUTPUT_PATH",
-    INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH",
-    INVALID_PPT_MODE: "INVALID_PPT_MODE",
-    INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT",
-    // CSV validation/parsing errors (#1199)
-    CSV_INVALID_INPUT: "CSV_INVALID_INPUT",
-    CSV_ROW_INVALID: "CSV_ROW_INVALID",
-    CSV_FILE_ACCESS_FAILED: "CSV_FILE_ACCESS_FAILED",
-    CSV_PARSE_FAILED: "CSV_PARSE_FAILED",
-};
-/**
- * Enhanced error class with structured information
- */
-export class NeuroLinkError extends Error {
-    code;
-    category;
-    severity;
-    retriable;
-    retryAfterMs;
-    context;
-    timestamp;
-    toolName;
-    serverId;
-    constructor(options) {
-        super(options.message);
-        this.name = "NeuroLinkError";
-        this.code = options.code;
-        this.category = options.category;
-        this.severity = options.severity;
-        this.retriable = options.retriable;
-        this.retryAfterMs = options.retryAfterMs;
-        this.context = options.context || {};
-        this.timestamp = new Date();
-        this.toolName = options.toolName;
-        this.serverId = options.serverId;
-        // Preserve original error stack if provided
-        if (options.originalError) {
-            this.stack = options.originalError.stack;
-            this.context.originalMessage = options.originalError.message;
-        }
-    }
-    /**
-     * Convert to JSON for logging and serialization
-     */
-    toJSON() {
-        return {
-            code: this.code,
-            message: this.message,
-            category: this.category,
-            severity: this.severity,
-            retriable: this.retriable,
-            context: this.context,
-            timestamp: this.timestamp,
-            toolName: this.toolName,
-            serverId: this.serverId,
-        };
-    }
-}
-/**
- * Error factory for common error scenarios
- */
-export class ErrorFactory {
-    /**
-     * Create a tool not found error
-     */
-    static toolNotFound(toolName, availableTools) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.TOOL_NOT_FOUND,
-            message: `Tool '${toolName}' not found`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { toolName, availableTools },
-            toolName,
-        });
-    }
-    /**
-     * Create a tool execution failed error
-     */
-    static toolExecutionFailed(toolName, originalError, serverId) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.TOOL_EXECUTION_FAILED,
-            message: `Tool '${toolName}' execution failed: ${originalError.message}`,
-            category: ErrorCategory.EXECUTION,
-            severity: ErrorSeverity.HIGH,
-            retriable: true,
-            originalError,
-            toolName,
-            serverId,
-        });
-    }
-    /**
-     * Create a tool timeout error
-     */
-    static toolTimeout(toolName, timeoutMs, serverId) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.TOOL_TIMEOUT,
-            message: `Tool '${toolName}' timed out after ${timeoutMs}ms`,
-            category: ErrorCategory.TIMEOUT,
-            severity: ErrorSeverity.HIGH,
-            retriable: true,
-            context: { timeoutMs },
-            toolName,
-            serverId,
-        });
-    }
-    /**
-     * Create a parameter validation error
-     */
-    static invalidParameters(toolName, validationError, providedParams) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PARAMETERS,
-            message: `Invalid parameters for tool '${toolName}': ${validationError.message}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { providedParams },
-            originalError: validationError,
-            toolName,
-        });
-    }
-    /**
-     * Create a network error
-     */
-    static networkError(toolName, originalError, serverId) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.NETWORK_ERROR,
-            message: `Network error in tool '${toolName}': ${originalError.message}`,
-            category: ErrorCategory.NETWORK,
-            severity: ErrorSeverity.HIGH,
-            retriable: true,
-            originalError,
-            toolName,
-            serverId,
-        });
-    }
-    /**
-     * Create a memory exhaustion error
-     */
-    static memoryExhausted(toolName, memoryUsageMB) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.MEMORY_EXHAUSTED,
-            message: `Memory exhausted during tool '${toolName}' execution (${memoryUsageMB}MB used)`,
-            category: ErrorCategory.RESOURCE,
-            severity: ErrorSeverity.CRITICAL,
-            retriable: false,
-            context: { memoryUsageMB },
-            toolName,
-        });
-    }
-    /**
-     * 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) {
-        const err = new NeuroLinkError({
-            code: ERROR_CODES.OPERATION_ABORTED,
-            message: originalError?.message || "The operation was aborted",
-            category: ErrorCategory.ABORT,
-            severity: ErrorSeverity.LOW,
-            retriable: false,
-            context: {},
-            originalError,
-        });
-        err.name = "AbortError";
-        return err;
-    }
-    // ============================================================================
-    // CONFIGURATION ERRORS
-    // ============================================================================
-    /**
-     * Create a missing configuration error (e.g., missing API key)
-     */
-    static missingConfiguration(configName, context) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.MISSING_CONFIGURATION,
-            message: `Missing required configuration: ${configName}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-            context: context || {},
-        });
-    }
-    /**
-     * Create an invalid configuration error (e.g., NaN for numeric values)
-     */
-    static invalidConfiguration(configName, reason, context) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_CONFIGURATION,
-            message: `Invalid configuration for '${configName}': ${reason}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-            context: context || {},
-        });
-    }
-    // ============================================================================
-    // CSV VALIDATION/PARSING ERRORS (#1199)
-    // ============================================================================
-    /**
-     * Create an invalid CSV input error (e.g. an empty filePath/csvString argument).
-     */
-    static csvInvalidInput(message) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.CSV_INVALID_INPUT,
-            message,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {},
-        });
-    }
-    /**
-     * Create a CSV row-shape violation error (#384) — a parsed row that isn't a
-     * string-keyed object with string values.
-     */
-    static csvRowInvalid(message, rowNumber) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.CSV_ROW_INVALID,
-            message,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { rowNumber },
-        });
-    }
-    /**
-     * Create a CSV file access error (bad path, permissions, ENOENT/EACCES) (#375).
-     */
-    static csvFileAccessFailed(message, filePath, originalError) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.CSV_FILE_ACCESS_FAILED,
-            message,
-            category: ErrorCategory.RESOURCE,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-            context: { filePath },
-            originalError,
-        });
-    }
-    /**
-     * 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, context, originalError) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.CSV_PARSE_FAILED,
-            message,
-            category: ErrorCategory.EXECUTION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context,
-            originalError,
-        });
-    }
-    // ============================================================================
-    // VIDEO VALIDATION ERRORS
-    // ============================================================================
-    /**
-     * Create an invalid video resolution error
-     */
-    static invalidVideoResolution(resolution) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_VIDEO_RESOLUTION,
-            message: `Invalid resolution '${resolution}'. Use '720p' or '1080p'`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.video.resolution",
-                providedValue: resolution,
-                suggestions: ["Use '720p' for standard HD", "Use '1080p' for full HD"],
-            },
-        });
-    }
-    /**
-     * Create an invalid video length error
-     */
-    static invalidVideoLength(length) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_VIDEO_LENGTH,
-            message: `Invalid length '${length}'. Use 4, 6, or 8 seconds`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.video.length",
-                providedValue: length,
-                suggestions: [
-                    "Use 4 for short clips",
-                    "Use 6 for balanced duration (recommended)",
-                    "Use 8 for longer videos",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid video aspect ratio error
-     */
-    static invalidVideoAspectRatio(aspectRatio) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_VIDEO_ASPECT_RATIO,
-            message: `Invalid aspect ratio '${aspectRatio}'. Use '9:16' or '16:9'`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.video.aspectRatio",
-                providedValue: aspectRatio,
-                suggestions: [
-                    "Use '9:16' for portrait/vertical video",
-                    "Use '16:9' for landscape",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid video audio option error
-     */
-    static invalidVideoAudio(audio) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_VIDEO_AUDIO,
-            message: `Invalid audio option '${audio}'. Must be true or false`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.video.audio",
-                providedValue: audio,
-                suggestions: [
-                    "Set audio: true to enable audio generation",
-                    "Set audio: false to disable",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid video mode error
-     */
-    static invalidVideoMode() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_VIDEO_MODE,
-            message: "Video generation requires output.mode to be 'video'",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.mode",
-                suggestions: ["Set output: { mode: 'video' } for video generation"],
-            },
-        });
-    }
-    /**
-     * Create a missing video image error
-     */
-    static missingVideoImage() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.MISSING_VIDEO_IMAGE,
-            message: "Video generation requires an input image",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.images",
-                suggestions: [
-                    "Provide an image via input.images array",
-                    "Example: input: { text: 'prompt', images: [imageBuffer] }",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an empty video prompt error
-     */
-    static emptyVideoPrompt() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.EMPTY_VIDEO_PROMPT,
-            message: "Video prompt cannot be empty",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.text",
-                suggestions: [
-                    "Provide a text prompt describing the desired video motion/content",
-                    "Example: 'Smooth camera pan with dramatic lighting'",
-                ],
-            },
-        });
-    }
-    /**
-     * Create a video prompt too long error
-     */
-    static videoPromptTooLong(length, maxLength) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.VIDEO_PROMPT_TOO_LONG,
-            message: `Video prompt must be ${maxLength} characters or less (got ${length})`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.text",
-                providedLength: length,
-                maxLength,
-                suggestions: [
-                    `Shorten your prompt to ${maxLength} characters or less`,
-                    "Focus on key visual elements and camera motion",
-                ],
-            },
-        });
-    }
-    // ============================================================================
-    // IMAGE VALIDATION ERRORS
-    // ============================================================================
-    /**
-     * Create an empty image path error
-     */
-    static emptyImagePath() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.EMPTY_IMAGE_PATH,
-            message: "Image path or URL cannot be empty",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.images",
-                suggestions: ["Provide a valid file path or URL"],
-            },
-        });
-    }
-    /**
-     * Create an invalid image type error
-     */
-    static invalidImageType() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_IMAGE_TYPE,
-            message: "Image must be a Buffer, file path string, or URL",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.images",
-                suggestions: [
-                    "Provide image as Buffer: fs.readFileSync('image.jpg')",
-                    "Or as file path string: './image.jpg'",
-                    "Or as URL: 'https://example.com/image.jpg'",
-                ],
-            },
-        });
-    }
-    // ============================================================================
-    // PDF VALIDATION ERRORS
-    // ============================================================================
-    /**
-     * Create a PDF page limit exceeded error
-     */
-    static pdfPageLimitExceeded(estimatedPages, maxPages, provider) {
-        const alternatives = [
-            `Split the PDF into smaller files (max ${maxPages} pages each)`,
-            "Extract only the pages you need using a PDF editor",
-            "For large files, consider Google AI Studio which supports up to 2000MB file size (though page limits still apply)",
-            "Convert specific pages to images manually before processing",
-            "Bypass this limit with { enforceLimits: false } (not recommended - may cause API errors or unexpected costs)",
-        ];
-        return new NeuroLinkError({
-            code: ERROR_CODES.PDF_PAGE_LIMIT_EXCEEDED,
-            message: `PDF page limit exceeded: ${estimatedPages} pages detected, but ${provider} supports maximum ${maxPages} pages.\n\n` +
-                `Alternatives:\n` +
-                alternatives.map((alt, i) => `${i + 1}. ${alt}`).join("\n"),
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                estimatedPages,
-                maxPages,
-                provider,
-                alternatives,
-            },
-        });
-    }
-    /**
-     * 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, totalPages, maxPages, provider) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED,
-            message: `[PDF] Combined page count across ${fileCount} PDF(s) (${totalPages}) exceeds the ` +
-                `${maxPages}-page limit for ${provider}. ` +
-                `Split the request or reduce the number of PDFs.`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { fileCount, totalPages, maxPages, provider },
-        });
-    }
-    /**
-     * The combined byte size across every PDF in one request exceeds what the
-     * provider accepts (#309).
-     */
-    static pdfAggregateSizeLimitExceeded(fileCount, totalMB, maxSizeMB, provider) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED,
-            message: `[PDF] Combined size across ${fileCount} PDF(s) (${totalMB.toFixed(2)}MB) exceeds the ` +
-                `${maxSizeMB}MB limit for ${provider}.`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { fileCount, totalMB, maxSizeMB, provider },
-        });
-    }
-    /**
-     * 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, provider) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.PDF_PAGE_COUNT_UNVERIFIABLE,
-            message: `[PDF] Cannot verify the page count for ${filenames.length} PDF(s) supplied via ` +
-                `input.content (${filenames.join(", ")}). Provide readable PDFs, or submit them ` +
-                `via input.pdfFiles where page counts are derived during detection.`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { filenames, provider },
-        });
-    }
-    /**
-     * The PDF is encrypted and no password was supplied (#258).
-     */
-    static pdfPasswordRequired() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.PDF_PASSWORD_REQUIRED,
-            message: "This PDF is password-protected. Supply the password via " +
-                "`pdfOptions: { password: '…' }` (SDK) or `--pdf-password` (CLI).",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-        });
-    }
-    /**
-     * A password was supplied for an encrypted PDF but it was incorrect (#258).
-     */
-    static pdfIncorrectPassword() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.PDF_INCORRECT_PASSWORD,
-            message: "The password supplied for this PDF is incorrect. Check the " +
-                "`pdfOptions.password` / `--pdf-password` value and try again.",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-        });
-    }
-    /**
-     * Create an image too large error
-     */
-    static imageTooLarge(sizeMB, maxMB) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.IMAGE_TOO_LARGE,
-            message: `Image size (${sizeMB}MB) exceeds maximum (${maxMB}MB)`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.images",
-                sizeMB,
-                maxMB,
-                suggestions: [
-                    `Compress or resize the image to under ${maxMB}MB`,
-                    "Use a lower quality JPEG compression",
-                    "Reduce image dimensions",
-                ],
-            },
-        });
-    }
-    /**
-     * 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) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_IMAGE_SIZE,
-            message: `Invalid image size: ${size} (must be a finite, non-negative number)`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.images",
-                size,
-            },
-        });
-    }
-    /**
-     * Create an image too small error
-     */
-    static imageTooSmall() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.IMAGE_TOO_SMALL,
-            message: "Image data is too small to be a valid image file",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.images",
-                suggestions: ["Provide a valid JPEG, PNG, or WebP image file"],
-            },
-        });
-    }
-    /**
-     * Create an invalid image format error
-     */
-    static invalidImageFormat() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_IMAGE_FORMAT,
-            message: "Unsupported image format. Use JPEG, PNG, or WebP",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.images",
-                suggestions: [
-                    "Convert your image to JPEG, PNG, or WebP format",
-                    "Ensure the file is not corrupted",
-                    "Check that the file extension matches the actual format",
-                ],
-            },
-        });
-    }
-    /**
-     * 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) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.IMAGE_BUFFER_INVALID,
-            message,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { field: "input.images" },
-        });
-    }
-    // ============================================================================
-    // RATE LIMITER ERRORS
-    // ============================================================================
-    /**
-     * Create a rate limiter queue full error
-     */
-    static rateLimiterQueueFull(maxQueueSize) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.RATE_LIMITER_QUEUE_FULL,
-            message: `Rate limiter queue full: too many pending requests (${maxQueueSize} max)`,
-            category: ErrorCategory.RESOURCE,
-            severity: ErrorSeverity.HIGH,
-            retriable: true,
-            context: { maxQueueSize },
-        });
-    }
-    /**
-     * Create a rate limiter queue timeout error
-     */
-    static rateLimiterQueueTimeout(timeoutMs) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.RATE_LIMITER_QUEUE_TIMEOUT,
-            message: `Rate limiter queue timeout: request exceeded ${timeoutMs}ms wait time`,
-            category: ErrorCategory.TIMEOUT,
-            severity: ErrorSeverity.HIGH,
-            retriable: true,
-            context: { timeoutMs },
-        });
-    }
-    /**
-     * Create a rate limiter reset error
-     */
-    static rateLimiterReset() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.RATE_LIMITER_RESET,
-            message: "Rate limiter was reset while request was pending",
-            category: ErrorCategory.EXECUTION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: true,
-            context: {},
-        });
-    }
-    // ============================================================================
-    // PPT VALIDATION ERRORS
-    // ============================================================================
-    /**
-     * Create a generic missing PPT property error
-     */
-    static missingPPTProperty(field, suggestions) {
-        const defaultSuggestions = [`Provide the required '${field}' field`];
-        return new NeuroLinkError({
-            code: ERROR_CODES.MISSING_PPT_PROPERTIES,
-            message: `PPT generation requires '${field}' field`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field,
-                suggestions: suggestions || defaultSuggestions,
-            },
-        });
-    }
-    /**
-     * Create an invalid PPT pages error
-     */
-    static invalidPPTPages(pages, reason) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_PAGES,
-            message: `Invalid pages value '${pages}': ${reason}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.ppt.pages",
-                providedValue: pages,
-                suggestions: [
-                    "Use a number between 5 and 50",
-                    "For longer presentations, consider breaking into multiple decks",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid PPT format error
-     */
-    static invalidPPTFormat(format) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_FORMAT,
-            message: `Invalid format '${format}'. Only 'pptx' is supported`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.ppt.format",
-                providedValue: format,
-                suggestions: ["Use format: 'pptx' or omit (defaults to 'pptx')"],
-            },
-        });
-    }
-    /**
-     * Create a generic invalid PPT output options error
-     */
-    static invalidPPTOutputOptions(field, value, validOptions) {
-        const suggestions = validOptions
-            ? validOptions.map((opt) => `Use '${opt}'`)
-            : ["Check the documentation for valid options"];
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_OUTPUT_OPTIONS,
-            message: `Invalid ${field} value '${value}'`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: `output.ppt.${field}`,
-                providedValue: value,
-                suggestions,
-            },
-        });
-    }
-    /**
-     * Create an invalid PPT output path error
-     */
-    static invalidPPTOutputPath(path, reason) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_OUTPUT_PATH,
-            message: `Invalid outputPath '${path}': ${reason}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.ppt.outputPath",
-                providedValue: path,
-                suggestions: [
-                    "Provide a valid file path string",
-                    "Example: './presentations/my-deck.pptx'",
-                    "Omit to use auto-generated path",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid PPT mode error
-     */
-    static invalidPPTMode() {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_MODE,
-            message: "Presentation generation requires output.mode to be 'ppt'",
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.mode",
-                suggestions: [
-                    "Set output: { mode: 'ppt' } for presentation generation",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid PPT prompt error
-     */
-    static invalidPPTPrompt(reason) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_PROMPT,
-            message: `Invalid PPT prompt: ${reason}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "input.text",
-                suggestions: [
-                    "Provide a non-empty text prompt",
-                    "Keep the prompt under 1000 characters",
-                    "Focus on key topics and structure for the presentation",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid PPT logo path error
-     */
-    static invalidPPTLogoPath(path, reason) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_LOGO_PATH,
-            message: `Invalid logoPath '${path}': ${reason}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "output.ppt.logoPath",
-                providedValue: path,
-                suggestions: [
-                    "Provide a valid file path string",
-                    "Example: './assets/logo.png'",
-                    "Omit to skip logo inclusion",
-                ],
-            },
-        });
-    }
-    /**
-     * Create an invalid PPT provider error
-     */
-    static invalidPPTProvider(provider) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.INVALID_PPT_PROVIDER,
-            message: `Invalid provider '${provider}' for PPT generation. Supported providers: vertex, openai, azure, anthropic, google-ai, bedrock`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: {
-                field: "provider",
-                providedValue: provider,
-                suggestions: [
-                    "Use 'vertex' for Google Vertex AI (Gemini)",
-                    "Use 'openai' for OpenAI GPT models",
-                    "Use 'azure' for Azure OpenAI",
-                    "Use 'anthropic' for Anthropic Claude models",
-                    "Use 'google-ai' for Google AI Studio (Gemini)",
-                    "Use 'bedrock' for AWS Bedrock (Claude, Llama, Nova, etc.)",
-                ],
-            },
-        });
-    }
-    // ============================================================================
-    // EVALUATION ERRORS
-    // ============================================================================
-    /**
-     * Create a scorer not found error
-     */
-    static scorerNotFound(scorerId, availableScorers) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.SCORER_NOT_FOUND,
-            message: `Scorer '${scorerId}' not found. Use neurolink.getAvailableScorers() to see available scorers.`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { scorerId, availableScorers },
-        });
-    }
-    /**
-     * Create an evaluation validation error
-     */
-    static evaluationValidationFailed(scorerId, errors) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.EVALUATION_VALIDATION_FAILED,
-            message: `Invalid input for scorer '${scorerId}': ${errors.join(", ")}`,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.MEDIUM,
-            retriable: false,
-            context: { scorerId, validationErrors: errors },
-        });
-    }
-    /**
-     * Create an evaluation timeout error
-     */
-    static evaluationTimeout(operation, timeoutMs) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.EVALUATION_TIMEOUT,
-            message: `Evaluation ${operation} timed out after ${timeoutMs}ms`,
-            category: ErrorCategory.TIMEOUT,
-            severity: ErrorSeverity.HIGH,
-            retriable: true,
-            context: { operation, timeoutMs },
-        });
-    }
-    /**
-     * Create an evaluation execution failed error
-     */
-    static evaluationExecutionFailed(operation, originalError) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.EVALUATION_EXECUTION_FAILED,
-            message: `Evaluation ${operation} failed: ${originalError.message}`,
-            category: ErrorCategory.EXECUTION,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-            originalError,
-        });
-    }
-    // ============================================================================
-    // PROXY ROLLING-WORKER ERRORS
-    // ============================================================================
-    /**
-     * 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, context) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.PROXY_WORKER_LIFECYCLE_FAILED,
-            message,
-            category: ErrorCategory.SYSTEM,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-            context: context || {},
-        });
-    }
-    // ============================================================================
-    // GENERIC FILE / CSV PROCESSING ERRORS
-    // ============================================================================
-    /**
-     * 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, originalError) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.FILE_PROCESSING_FAILED,
-            message: `Failed to process file "${filename}": ${originalError.message}`,
-            category: ErrorCategory.EXECUTION,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-            context: { filename },
-            originalError,
-        });
-    }
-    /**
-     * 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, originalError) {
-        return new NeuroLinkError({
-            code: ERROR_CODES.CSV_PROCESSING_FAILED,
-            message: `Failed to process CSV file "${filename}": ${originalError.message}`,
-            category: ErrorCategory.EXECUTION,
-            severity: ErrorSeverity.HIGH,
-            retriable: false,
-            context: { filename },
-            originalError,
-        });
-    }
-}
-/**
- * Timeout wrapper for async operations
- */
-export async function withTimeout(promise, timeoutMs, timeoutError) {
-    let timer;
-    const timeoutPromise = new Promise((_, reject) => {
-        timer = setTimeout(() => {
-            reject(timeoutError || new Error(`Operation timed out after ${timeoutMs}ms`));
-        }, timeoutMs);
-    });
-    try {
-        return await Promise.race([promise, timeoutPromise]);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/**
- * Retry mechanism for retriable operations
- */
-export async function withRetry(operation, options) {
-    const { maxAttempts, delayMs, isRetriable = () => true, onRetry } = options;
-    let lastError;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        try {
-            return await operation();
-        }
-        catch (error) {
-            lastError = error instanceof Error ? error : new Error(String(error));
-            // Don't retry on the last attempt or if error is not retriable
-            if (attempt === maxAttempts || !isRetriable(lastError)) {
-                throw lastError;
-            }
-            if (onRetry) {
-                onRetry(attempt, lastError);
-            }
-            // Wait before retry
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
-        }
-    }
-    if (lastError) {
-        throw lastError;
-    }
-    throw new Error("Retry operation failed with no error information");
-}
-/**
- * Circuit breaker for preventing cascading failures
- */
-export class CircuitBreaker {
-    failureThreshold;
-    resetTimeoutMs;
-    failures = 0;
-    lastFailureTime = 0;
-    state = "closed";
-    name;
-    constructor(failureThreshold = 5, resetTimeoutMs = 60000, name = "tool-execution") {
-        this.failureThreshold = failureThreshold;
-        this.resetTimeoutMs = resetTimeoutMs;
-        this.name = name;
-    }
-    async execute(operation) {
-        if (this.state === "open") {
-            const retryAfterMs = this.resetTimeoutMs - (Date.now() - this.lastFailureTime);
-            if (retryAfterMs > 0) {
-                throw new CircuitBreakerOpenError({
-                    breakerName: this.name,
-                    retryAfter: new Date(this.lastFailureTime + this.resetTimeoutMs),
-                    retryAfterMs,
-                    breakerState: "open",
-                    failureCount: this.failures,
-                });
-            }
-            this.state = "half-open";
-        }
-        try {
-            const result = await operation();
-            this.onSuccess();
-            return result;
-        }
-        catch (error) {
-            this.onFailure();
-            throw error;
-        }
-    }
-    onSuccess() {
-        this.failures = 0;
-        this.state = "closed";
-    }
-    onFailure() {
-        this.failures++;
-        this.lastFailureTime = Date.now();
-        if (this.failures >= this.failureThreshold) {
-            this.state = "open";
-        }
-    }
-    getState() {
-        return this.state;
-    }
-    getFailureCount() {
-        return this.failures;
-    }
-}
-/**
- * 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 function isAbortError(error) {
-    if (error instanceof DOMException && error.name === "AbortError") {
-        return true;
-    }
-    if (error instanceof Error && error.name === "AbortError") {
-        return true;
-    }
-    // Typed NeuroLinkError abort - canonical from-now-on shape.
-    if (error instanceof NeuroLinkError &&
-        error.category === ErrorCategory.ABORT) {
-        return true;
-    }
-    if (error instanceof Error &&
-        (error.message?.includes("This operation was aborted") ||
-            error.message?.includes("The operation was aborted") ||
-            error.message?.includes("The user aborted a request"))) {
-        return true;
-    }
-    return false;
-}
-/**
- * Error handler that decides whether to retry based on error type
- */
-export function isRetriableError(error) {
-    if (error instanceof NeuroLinkError) {
-        return error.retriable;
-    }
-    if (error instanceof HITLTimeoutError) {
-        return false;
-    }
-    // Check for common retriable error patterns
-    const retriablePatterns = [
-        /timeout/i,
-        /network/i,
-        /connection/i,
-        /temporary/i,
-        /rate limit/i,
-        /quota/i,
-        /503/i, // Service unavailable
-        /502/i, // Bad gateway
-        /504/i, // Gateway timeout
-    ];
-    return retriablePatterns.some((pattern) => pattern.test(error.message));
-}
-/**
- * Determines if an error is likely recoverable (rate limit, timeout, network issues).
- * Useful for deciding whether to retry or fail fast.
- */
-export function isRecoverableError(error) {
-    // Check NeuroLinkError.retriable first
-    const errorWithRetriable = error;
-    if ("retriable" in error &&
-        typeof errorWithRetriable.retriable === "boolean") {
-        return errorWithRetriable.retriable;
-    }
-    const message = error.message?.toLowerCase() || "";
-    // Rate limit errors
-    if (message.includes("rate limit") || message.includes("too many requests")) {
-        return true;
-    }
-    if (/\b429\b/.test(message)) {
-        return true;
-    }
-    // Timeout errors
-    if (message.includes("timeout") ||
-        message.includes("etimedout") ||
-        message.includes("timed out")) {
-        return true;
-    }
-    // Network errors
-    if (message.includes("econnreset") ||
-        message.includes("econnrefused") ||
-        message.includes("network") ||
-        message.includes("socket")) {
-        return true;
-    }
-    // Server errors (use word boundaries to avoid false matches)
-    if (/\b50[0234]\b/.test(message)) {
-        return true;
-    }
-    return false;
-}
-/**
- * Enhanced error logger that provides structured logging
- */
-export function logStructuredError(error, context) {
-    const logData = {
-        ...error.toJSON(),
-        ...context,
-    };
-    switch (error.severity) {
-        case ErrorSeverity.CRITICAL:
-            logger.error(`[CRITICAL] ${error.message}`, logData);
-            break;
-        case ErrorSeverity.HIGH:
-            logger.error(`[HIGH] ${error.message}`, logData);
-            break;
-        case ErrorSeverity.MEDIUM:
-            logger.warn(`[MEDIUM] ${error.message}`, logData);
-            break;
-        case ErrorSeverity.LOW:
-            logger.info(`[LOW] ${error.message}`, logData);
-            break;
-    }
-}
-//# sourceMappingURL=errorHandling.js.map