@juspay/neurolink 11.0.0 → 11.1.0

package/dist/lib/providers/openaiCompatible/client.js

@@ -1,7 +1,7 @@
-import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
+import { AuthenticationError, InvalidModelError, NetworkError, } from "../../types/index.js";
 import { logger } from "../../utils/logger.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
-import { TimeoutError } from "../../utils/timeout.js";
+import { classifyProviderError, DEFAULT_ERROR_RULES, } from "../../utils/errorClassifier.js";
 import { OpenAIChatCompletionsProvider } from "../openaiChatCompletionsBase.js";
 import { FALLBACK_OPENAI_COMPATIBLE_MODEL } from "./constants.js";
 import { getDefaultOpenAICompatibleModel, getOpenAICompatibleConfig, } from "./utils.js";
@@ -52,36 +52,40 @@ export class OpenAICompatibleProvider extends OpenAIChatCompletionsProvider {
         ];
     }
     formatProviderError(error) {
-        if (error instanceof TimeoutError) {
-            return new NetworkError(`Request timed out: ${error.message}`, "openai-compatible");
-        }
-        const errorRecord = error;
-        if (errorRecord?.name === "TimeoutError" ||
-            (typeof errorRecord?.message === "string" &&
-                errorRecord.message.includes("Timeout"))) {
-            return new NetworkError(`Request timed out: ${errorRecord?.message || "Unknown timeout"}`, "openai-compatible");
-        }
-        if (typeof errorRecord?.message === "string") {
-            if (errorRecord.message.includes("ECONNREFUSED") ||
-                errorRecord.message.includes("Failed to fetch")) {
-                return new NetworkError(`OpenAI Compatible endpoint not available. Please check your OPENAI_COMPATIBLE_BASE_URL: ${redactUrlCredentials(this.config.baseURL)}`, "openai-compatible");
-            }
-            if (errorRecord.message.includes("API_KEY_INVALID") ||
-                errorRecord.message.includes("Invalid API key") ||
-                errorRecord.message.includes("Unauthorized")) {
-                return new AuthenticationError("Invalid OpenAI Compatible API key. Please check your OPENAI_COMPATIBLE_API_KEY environment variable.", "openai-compatible");
-            }
-            if (errorRecord.message.includes("rate limit")) {
-                return new RateLimitError("OpenAI Compatible rate limit exceeded. Please try again later.", "openai-compatible");
-            }
-            if (errorRecord.message.includes("model") &&
-                (errorRecord.message.includes("not found") ||
-                    errorRecord.message.includes("does not exist"))) {
-                return new InvalidModelError(`Model '${this.modelName}' not available on OpenAI Compatible endpoint. ` +
-                    "Please check available models or use getAvailableModels() to see supported models.", "openai-compatible");
-            }
-        }
-        return new ProviderError(`OpenAI Compatible error: ${errorRecord?.message || "Unknown error"}`, "openai-compatible");
+        const rules = [
+            // Duck-typed timeout check (name === "TimeoutError" or a "Timeout"
+            // substring) — broader than classifyProviderError's built-in
+            // `instanceof TimeoutError` handling, so it's preserved as an
+            // explicit rule rather than relying on the default.
+            {
+                match: (ctx) => ctx.errorName === "TimeoutError" || /Timeout/.test(ctx.message),
+                errorClass: NetworkError,
+                message: (ctx) => `Request timed out: ${ctx.message}`,
+            },
+            {
+                match: (ctx) => /ECONNREFUSED|Failed to fetch/i.test(ctx.message),
+                errorClass: NetworkError,
+                message: () => `OpenAI Compatible endpoint not available. Please check your OPENAI_COMPATIBLE_BASE_URL: ${redactUrlCredentials(this.config.baseURL)}`,
+            },
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /API_KEY_INVALID|Invalid API key|Unauthorized/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid OpenAI Compatible API key. Please check your OPENAI_COMPATIBLE_API_KEY environment variable.",
+            },
+            // "does not exist" isn't covered by DEFAULT_ERROR_RULES's
+            // model_not_found/"model not found" pattern — preserved verbatim.
+            {
+                match: (ctx) => /model/i.test(ctx.message) &&
+                    (/not found/i.test(ctx.message) ||
+                        /does not exist/i.test(ctx.message)),
+                errorClass: InvalidModelError,
+                message: (ctx) => `Model '${ctx.modelName}' not available on OpenAI Compatible endpoint. ` +
+                    "Please check available models or use getAvailableModels() to see supported models.",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ];
+        return classifyProviderError(error, rules, "openai-compatible", this.modelName);
     }
 }
 //# sourceMappingURL=client.js.map

package/dist/lib/providers/perplexity.js

@@ -1,9 +1,9 @@
 import { PerplexityModels } from "../constants/enums.js";
-import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
+import { AuthenticationError } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlCredentials } from "../utils/logSanitize.js";
+import { classifyProviderError, DEFAULT_ERROR_RULES, } from "../utils/errorClassifier.js";
 import { createPerplexityConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.js";
-import { TimeoutError } from "../utils/timeout.js";
 import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
 const PERPLEXITY_DEFAULT_BASE_URL = "https://api.perplexity.ai";
 const getPerplexityApiKey = () => validateApiKey(createPerplexityConfig());
@@ -54,25 +54,16 @@ export class PerplexityProvider extends OpenAIChatCompletionsProvider {
         ];
     }
     formatProviderError(error) {
-        if (error instanceof TimeoutError) {
-            return new NetworkError(`Request timed out: ${error.message}`, "perplexity");
-        }
-        const errorRecord = error;
-        const message = typeof errorRecord?.message === "string"
-            ? errorRecord.message
-            : "Unknown error";
-        if (message.includes("Invalid API key") ||
-            message.includes("Authentication") ||
-            message.includes("401")) {
-            return new AuthenticationError("Invalid Perplexity API key. Get one at https://www.perplexity.ai/settings/api", "perplexity");
-        }
-        if (message.includes("rate limit") || message.includes("429")) {
-            return new RateLimitError("Perplexity rate limit exceeded. Back off and retry.", "perplexity");
-        }
-        if (message.includes("model_not_found") || message.includes("404")) {
-            return new InvalidModelError(`Perplexity model '${this.modelName}' not found. Use sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, or sonar-deep-research.`, "perplexity");
-        }
-        return new ProviderError(`Perplexity error: ${message}`, "perplexity");
+        const rules = [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Perplexity API key. Get one at https://www.perplexity.ai/settings/api",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ];
+        return classifyProviderError(error, rules, "perplexity", this.modelName);
     }
 }
 //# sourceMappingURL=perplexity.js.map

package/dist/lib/providers/togetherAi.js

@@ -1,9 +1,9 @@
 import { TogetherAIModels } from "../constants/enums.js";
-import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
+import { AuthenticationError } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlCredentials } from "../utils/logSanitize.js";
+import { classifyProviderError, DEFAULT_ERROR_RULES, } from "../utils/errorClassifier.js";
 import { createTogetherAIConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.js";
-import { TimeoutError } from "../utils/timeout.js";
 import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
 const TOGETHER_DEFAULT_BASE_URL = "https://api.together.xyz/v1";
 const getTogetherApiKey = () => validateApiKey(createTogetherAIConfig());
@@ -58,25 +58,16 @@ export class TogetherAIProvider extends OpenAIChatCompletionsProvider {
         ];
     }
     formatProviderError(error) {
-        if (error instanceof TimeoutError) {
-            return new NetworkError(`Request timed out: ${error.message}`, "together-ai");
-        }
-        const errorRecord = error;
-        const message = typeof errorRecord?.message === "string"
-            ? errorRecord.message
-            : "Unknown error";
-        if (message.includes("Invalid API key") ||
-            message.includes("Authentication") ||
-            message.includes("401")) {
-            return new AuthenticationError("Invalid Together AI API key. Get one at https://api.together.xyz/settings/api-keys", "together-ai");
-        }
-        if (message.includes("rate limit") || message.includes("429")) {
-            return new RateLimitError("Together AI rate limit exceeded. Back off and retry.", "together-ai");
-        }
-        if (message.includes("model_not_found") || message.includes("404")) {
-            return new InvalidModelError(`Together AI model '${this.modelName}' not found. Browse the catalog at https://api.together.xyz/models`, "together-ai");
-        }
-        return new ProviderError(`Together AI error: ${message}`, "together-ai");
+        const rules = [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Together AI API key. Get one at https://api.together.xyz/settings/api-keys",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ];
+        return classifyProviderError(error, rules, "together-ai", this.modelName);
     }
 }
 //# sourceMappingURL=togetherAi.js.map

package/dist/lib/providers/xai.js

@@ -1,9 +1,9 @@
 import { XaiModels } from "../constants/enums.js";
-import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
+import { AuthenticationError, ProviderError } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlCredentials } from "../utils/logSanitize.js";
+import { classifyProviderError, DEFAULT_ERROR_RULES, } from "../utils/errorClassifier.js";
 import { createXaiConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.js";
-import { TimeoutError } from "../utils/timeout.js";
 import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
 const XAI_DEFAULT_BASE_URL = "https://api.x.ai/v1";
 const getXaiApiKey = () => validateApiKey(createXaiConfig());
@@ -57,30 +57,21 @@ export class XaiProvider extends OpenAIChatCompletionsProvider {
         ];
     }
     formatProviderError(error) {
-        if (error instanceof TimeoutError) {
-            return new NetworkError(`Request timed out: ${error.message}`, "xai");
-        }
-        const errorRecord = error;
-        const message = typeof errorRecord?.message === "string"
-            ? errorRecord.message
-            : "Unknown error";
-        if (message.includes("Invalid API key") ||
-            message.includes("Authentication") ||
-            message.includes("401") ||
-            message.includes("invalid_api_key")) {
-            return new AuthenticationError("Invalid xAI API key. Please check your XAI_API_KEY environment variable. Get one at https://console.x.ai/", "xai");
-        }
-        if (message.includes("rate limit") || message.includes("429")) {
-            return new RateLimitError("xAI rate limit exceeded. Back off and retry.", "xai");
-        }
-        if (message.includes("model_not_found") || message.includes("404")) {
-            return new InvalidModelError(`xAI model '${this.modelName}' not found. Use grok-2-latest, grok-3, grok-3-mini, grok-2-vision-latest, or grok-beta.`, "xai");
-        }
-        if (message.includes("insufficient_quota") ||
-            message.includes("quota exceeded")) {
-            return new ProviderError("xAI account has insufficient quota. Top up at https://console.x.ai/", "xai");
-        }
-        return new ProviderError(`xAI error: ${message}`, "xai");
+        const rules = [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid xAI API key. Please check your XAI_API_KEY environment variable. Get one at https://console.x.ai/",
+            },
+            {
+                match: (ctx) => /insufficient_quota|quota exceeded/i.test(ctx.message),
+                errorClass: ProviderError,
+                message: "xAI account has insufficient quota. Top up at https://console.x.ai/",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ];
+        return classifyProviderError(error, rules, "xai", this.modelName);
     }
 }
 //# sourceMappingURL=xai.js.map

package/dist/lib/server/errors.d.ts

@@ -88,7 +88,7 @@ export declare class RateLimitError extends ServerAdapterError {
 /**
  * Timeout error
  */
-export declare class TimeoutError extends ServerAdapterError {
+export declare class ServerTimeoutError extends ServerAdapterError {
     constructor(timeoutMs: number, operation?: string, requestId?: string);
 }
 /**

package/dist/lib/server/errors.js

@@ -206,7 +206,7 @@ export class RateLimitError extends ServerAdapterError {
 /**
  * Timeout error
  */
-export class TimeoutError extends ServerAdapterError {
+export class ServerTimeoutError extends ServerAdapterError {
     constructor(timeoutMs, operation, requestId) {
         super(`Operation timed out after ${timeoutMs}ms${operation ? `: ${operation}` : ""}`, ServerAdapterErrorCode.TIMEOUT, {
             category: ErrorCategory.EXECUTION,
@@ -215,7 +215,7 @@ export class TimeoutError extends ServerAdapterError {
             requestId,
             details: { timeoutMs, operation },
         });
-        this.name = "TimeoutError";
+        this.name = "ServerTimeoutError";
     }
 }
 /**

package/dist/lib/server/index.d.ts

@@ -27,7 +27,7 @@ export { ExpressServerAdapter } from "./adapters/expressAdapter.js";
 export { FastifyServerAdapter } from "./adapters/fastifyAdapter.js";
 export { HonoServerAdapter } from "./adapters/honoAdapter.js";
 export { KoaServerAdapter } from "./adapters/koaAdapter.js";
-export { AlreadyRunningError, AuthenticationError, AuthorizationError, ConfigurationError, ErrorRecoveryStrategies, HandlerError, InvalidAuthenticationError, MissingDependencyError, NotRunningError, RateLimitError as ServerRateLimitError, RouteConflictError, RouteNotFoundError, ServerAdapterError, ServerStartError, ServerStopError, StreamAbortedError, StreamingError, TimeoutError, ValidationError as ServerValidationError, WebSocketConnectionError, WebSocketError, wrapError, } from "./errors.js";
+export { AlreadyRunningError, AuthenticationError as ServerAuthenticationError, AuthorizationError as ServerAuthorizationError, ConfigurationError, ErrorRecoveryStrategies, HandlerError, InvalidAuthenticationError, MissingDependencyError, NotRunningError, RateLimitError as ServerRateLimitError, RouteConflictError, RouteNotFoundError, ServerAdapterError, ServerStartError, ServerStopError, StreamAbortedError, StreamingError, ServerTimeoutError, ValidationError as ServerValidationError, WebSocketConnectionError, WebSocketError, wrapError, } from "./errors.js";
 export { createServer, ServerAdapterFactory, } from "./factory/serverAdapterFactory.js";
 export { createAbortSignalMiddleware, createExpressAbortMiddleware, } from "./middleware/abortSignal.js";
 export { createAuthMiddleware, createRoleMiddleware, } from "./middleware/auth.js";
@@ -35,7 +35,7 @@ export { createCacheInvalidator, createCacheMiddleware, InMemoryCacheStore, } fr
 export { createCompressionMiddleware, createErrorHandlingMiddleware, createLoggingMiddleware, createRequestIdMiddleware, createSecurityHeadersMiddleware, createTimingMiddleware, } from "./middleware/common.js";
 export { createDeprecationMiddleware } from "./middleware/deprecation.js";
 export { createMCPBodyAttachmentMiddleware, fastifyMCPBodyHook, } from "./middleware/mcpBodyAttachment.js";
-export { createRateLimitMiddleware, createSlidingWindowRateLimitMiddleware, InMemoryRateLimitStore, RateLimitError, } from "./middleware/rateLimit.js";
+export { createRateLimitMiddleware, createSlidingWindowRateLimitMiddleware, InMemoryRateLimitStore, } from "./middleware/rateLimit.js";
 export { CommonSchemas, createFieldValidator, createRequestValidationMiddleware, ValidationError, } from "./middleware/validation.js";
 export { AgentExecuteRequestSchema as OpenAPIAgentExecuteRequestSchema, AgentExecuteResponseSchema, AgentInputSchema, ApiKeySecurityScheme, BasicSecurityScheme, BearerSecurityScheme, CommonParameters, ConversationMessageSchema, createApiInfo, createDeleteOperation, createErrorResponse as createOpenAPIErrorResponse, createGetOperation, createHeaderParameter, createOpenAPIGenerator, createPathParameter, createPostOperation, createQueryParameter, createServer as createOpenAPIServer, createStreamingPostOperation, createStreamingResponse, createSuccessResponse, DefaultServers, ErrorResponseSchema, generateOpenAPIFromConfig, generateOpenAPISpec, HealthResponseSchema, MCPServerStatusSchema, MCPServersListResponseSchema, MCPServerToolSchema, MetricsResponseSchema, NeuroLinkApiInfo, OpenAPIGenerator, OpenAPISchemas, ProviderInfoSchema, ReadyResponseSchema, SessionSchema, SessionsListResponseSchema, StandardErrorResponses, StandardTags, TokenUsageSchema, ToolCallSchema, ToolDefinitionSchema, ToolExecuteRequestSchema as OpenAPIToolExecuteRequestSchema, ToolExecuteResponseSchema, ToolListResponseSchema, ToolParameterSchema, } from "./openapi/index.js";
 export { createAgentRoutes, createAllRoutes, createHealthRoutes, createMCPRoutes, createMemoryRoutes, createOpenApiRoutes, createToolRoutes, registerAllRoutes, } from "./routes/index.js";

package/dist/lib/server/index.js

@@ -38,7 +38,9 @@ export { KoaServerAdapter } from "./adapters/koaAdapter.js";
 // ============================================
 export { AlreadyRunningError, 
 // Authentication/Authorization errors
-AuthenticationError, AuthorizationError, 
+// (aliased: the bare names resolve to the provider-error classes of the
+// same name from types/ on the public @juspay/neurolink surface)
+AuthenticationError as ServerAuthenticationError, AuthorizationError as ServerAuthorizationError, 
 // Configuration errors
 ConfigurationError, 
 // Error recovery
@@ -56,7 +58,7 @@ ServerStartError, ServerStopError, StreamAbortedError,
 // Streaming errors
 StreamingError, 
 // Timeout errors
-TimeoutError, 
+ServerTimeoutError, 
 // Validation errors
 ValidationError as ServerValidationError, WebSocketConnectionError, 
 // WebSocket errors
@@ -76,7 +78,7 @@ export { createCacheInvalidator, createCacheMiddleware, InMemoryCacheStore, } fr
 export { createCompressionMiddleware, createErrorHandlingMiddleware, createLoggingMiddleware, createRequestIdMiddleware, createSecurityHeadersMiddleware, createTimingMiddleware, } from "./middleware/common.js";
 export { createDeprecationMiddleware } from "./middleware/deprecation.js";
 export { createMCPBodyAttachmentMiddleware, fastifyMCPBodyHook, } from "./middleware/mcpBodyAttachment.js";
-export { createRateLimitMiddleware, createSlidingWindowRateLimitMiddleware, InMemoryRateLimitStore, RateLimitError, } from "./middleware/rateLimit.js";
+export { createRateLimitMiddleware, createSlidingWindowRateLimitMiddleware, InMemoryRateLimitStore, } from "./middleware/rateLimit.js";
 export { CommonSchemas, createFieldValidator, createRequestValidationMiddleware, ValidationError, } from "./middleware/validation.js";
 // ============================================
 // OpenAPI

package/dist/lib/server/middleware/rateLimit.d.ts

@@ -40,10 +40,6 @@ export declare class InMemoryRateLimitStore implements RateLimitStore {
  * ```
  */
 export declare function createRateLimitMiddleware(config: RateLimitMiddlewareConfig): MiddlewareDefinition;
-/**
- * Re-export RateLimitError from errors for convenience
- */
-export { RateLimitError } from "../errors.js";
 /**
  * Create a sliding window rate limiter
  * More accurate than fixed window but slightly more complex

package/dist/lib/server/middleware/rateLimit.js

@@ -114,10 +114,6 @@ function defaultKeyGenerator(ctx) {
         ctx.headers["x-real-ip"] ||
         "unknown");
 }
-/**
- * Re-export RateLimitError from errors for convenience
- */
-export { RateLimitError } from "../errors.js";
 /**
  * Create a sliding window rate limiter
  * More accurate than fixed window but slightly more complex

package/dist/lib/types/errors.d.ts

@@ -47,6 +47,41 @@ export declare class RateLimitError extends ProviderError {
 export declare class InvalidModelError extends ProviderError {
     constructor(message: string, provider?: string);
 }
+/**
+ * Everything a ProviderErrorRule's `match`/`message` functions can inspect
+ * about a raw thrown error, pre-extracted once so every rule doesn't
+ * re-derive the same duck-typed fields.
+ */
+export type ProviderErrorContext = {
+    /** The raw thrown value, for rules that need custom inspection beyond the extracted fields. */
+    error: unknown;
+    /** `.message` off the raw error, or "Unknown error" if absent/non-string. */
+    message: string;
+    /** HTTP status code, duck-typed from `.statusCode` / `.status`. */
+    statusCode: number | undefined;
+    /** `.name` off the raw error (e.g. AWS SDK exception names like "ThrottlingException"). */
+    errorName: string | undefined;
+    /** `.code` off the raw error (e.g. AWS SDK / Node network error codes). */
+    errorCode: string | undefined;
+    /** Provider key passed to classifyProviderError (e.g. "mistral", "vertex"). */
+    provider: string;
+    /** Model name in effect for this call, when the caller has one available. */
+    modelName: string | undefined;
+};
+/**
+ * One row of a provider's error-classification table. Rules are tried in
+ * array order; the first `match` to return true wins. `errorClass` must be
+ * `ProviderError` or one of its subclasses (AuthenticationError,
+ * RateLimitError, InvalidModelError, NetworkError, ...) sharing its
+ * `(message, provider?)` constructor shape. `message` can be a static
+ * string or a function of the context, for providers that need to
+ * interpolate a model name, a scraped retry-delay, or an AWS error code.
+ */
+export type ProviderErrorRule = {
+    match: (ctx: ProviderErrorContext) => boolean;
+    errorClass: new (message: string, provider?: string) => ProviderError;
+    message: string | ((ctx: ProviderErrorContext) => string);
+};
 /**
  * Base class for OAuth-specific errors
  */

package/dist/lib/types/providers.d.ts

@@ -96,6 +96,7 @@ export type NeurolinkCredentials = {
     };
     googleAiStudio?: {
         apiKey?: string;
+        baseURL?: string;
     };
     vertex?: {
         projectId?: string;
@@ -888,6 +889,8 @@ export type GenAIClient = {
 export type GoogleGenAIHttpOptions = {
     /** Custom fetch implementation for proxy support */
     fetch?: typeof fetch;
+    /** Override the API base URL (e.g. a corporate proxy or mock endpoint) */
+    baseUrl?: string;
 };
 /**
  * Google GenAI constructor type
@@ -1677,6 +1680,67 @@ export type ProviderRegistration = {
     constructor: ProviderConstructor;
     defaultModel?: string;
     aliases?: string[];
+    descriptor?: ProviderDescriptor;
+};
+/**
+ * Single source of truth for one AI provider's static identity: how it's
+ * addressed (name/aliases), how it's authenticated (credentialsKey/envVars),
+ * what it defaults to (defaultModel), and how the rest of the codebase
+ * should treat it (toolSupport/localRuntime/healthCheck). Every consumer
+ * that used to hand-maintain its own provider table (CLI choices,
+ * CREDENTIAL_KEY_MAP, env-var checks, health-check dispatch, auto-select
+ * priority, PROMPT_ONLY_TOOL_PROVIDERS) derives from PROVIDER_DESCRIPTORS
+ * instead. See src/lib/factories/providerDescriptors.ts for the data.
+ */
+export type ProviderDescriptor = {
+    /** Canonical identity — matches an AIProviderName enum member (never AUTO). */
+    name: AIProviderName;
+    /** Alternate spellings accepted by the CLI and the alias index (kebab-case, shorthand, legacy names). Does not include `name` itself. */
+    aliases: readonly string[];
+    /** Key into NeurolinkCredentials for per-call/per-instance credential overrides. */
+    credentialsKey: keyof NeurolinkCredentials;
+    /** Environment variables this provider reads at runtime. */
+    envVars: {
+        /** Primary identity/secret env var. Absent for providers with no required credential (Ollama, LM Studio, llama.cpp) or that use extraRequired instead of a single key (Vertex). */
+        apiKey?: string;
+        /** Alternate env vars accepted in place of apiKey, checked in order after apiKey. */
+        fallbacks?: readonly string[];
+        baseURL?: string;
+        /** Alternate env vars accepted in place of baseURL. */
+        baseURLFallbacks?: readonly string[];
+        /** Env var that overrides the static defaultModel at runtime. */
+        model?: string;
+        /** Alternate env vars accepted in place of model, checked in order after model. */
+        modelFallbacks?: readonly string[];
+        /** Additional env vars required alongside apiKey (e.g. AWS secret key, Azure endpoint). */
+        extraRequired?: readonly string[];
+        /** Alternate ways to satisfy extraRequired when it isn't a plain env-var list (e.g. Vertex's file-path-OR-individual-fields auth). */
+        extraRequiredFallbacks?: readonly string[];
+        /** True when the provider is usable with zero configuration (local runtime with a documented default URL, or a documented non-secret default like LiteLLM's "sk-anything"). */
+        optional?: boolean;
+    };
+    /**
+     * Static fallback model. The empty string "" is a documented sentinel
+     * meaning "no static default — resolved at runtime via envVars.model or
+     * provider-side auto-discovery" (used by Bedrock, OpenAI-Compatible,
+     * LM Studio, llama.cpp, matching how providerRegistry.ts already passes
+     * `undefined` as their defaultModel argument today).
+     */
+    defaultModel: string;
+    toolSupport: "native" | "prompt-only" | "none" | "model-dependent";
+    /** True only for providers that run entirely on the caller's machine with no cloud account (Ollama, LM Studio, llama.cpp). LiteLLM is a local proxy but commonly points at cloud models, so it is deliberately false. */
+    localRuntime: boolean;
+    /** How ProviderHealthChecker should verify this provider is reachable. */
+    healthCheck: "env-only" | "models-probe" | "live-generate";
+    setupUrl?: string;
+    timeouts?: {
+        generateMs?: number;
+        streamMs?: number;
+    };
+    /** Ascending priority (1 = tried first) in the auto-select fallback chain used by getBestProvider(). Undefined = not part of the auto-select chain. */
+    autoSelectPriority?: number;
+    /** Format-validation regex sourced from providerConfig.ts's API_KEY_FORMATS, when one exists for this provider. */
+    apiKeyFormatPattern?: RegExp;
 };
 /** Minimal NeuroLink-like instance accepted by the image generation service. */
 export type NeuroLinkInstance = {

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

@@ -0,0 +1,30 @@
+/**
+ * Shared provider-error classification. Every provider's
+ * `formatProviderError(error)` delegates here instead of hand-rolling its
+ * own TimeoutError-check → .includes()-chain → `new XError(...)` ladder.
+ *
+ * `classifyProviderError` picks the Error subclass + message; it does NOT
+ * stamp statusCode/isRetryable/retryAfterMs onto the result — that
+ * passthrough already happens generically in
+ * `BaseProvider.handleProviderError()` (src/lib/core/baseProvider.ts) for
+ * every provider's returned error, migrated or not, so duplicating it here
+ * would risk the two copies disagreeing.
+ */
+import { type ProviderErrorRule } from "../types/index.js";
+/**
+ * Classify a raw provider error into a NeuroLink `ProviderError` subclass.
+ * `rules` are tried in order; the first match wins. `TimeoutError` is
+ * always handled first, ahead of any rule table — every provider treated
+ * it identically before this change, so it is not made overridable.
+ */
+export declare function classifyProviderError(error: unknown, rules: ProviderErrorRule[], provider: string, modelName?: string): Error;
+/**
+ * Generic fallback rule table covering the five categories every
+ * OpenAI-compatible provider already hand-rolled near-identically:
+ * auth (401), rate limit (429), model-not-found (404), network/connection
+ * errors, and 5xx server errors. Providers with a provider-specific auth
+ * message (naming the exact env var) prepend one override rule and spread
+ * this table after it — see errorClassifier usage in any migrated
+ * provider's formatProviderError for the pattern.
+ */
+export declare const DEFAULT_ERROR_RULES: ProviderErrorRule[];

package/dist/lib/utils/errorClassifier.js

@@ -0,0 +1,94 @@
+/**
+ * Shared provider-error classification. Every provider's
+ * `formatProviderError(error)` delegates here instead of hand-rolling its
+ * own TimeoutError-check → .includes()-chain → `new XError(...)` ladder.
+ *
+ * `classifyProviderError` picks the Error subclass + message; it does NOT
+ * stamp statusCode/isRetryable/retryAfterMs onto the result — that
+ * passthrough already happens generically in
+ * `BaseProvider.handleProviderError()` (src/lib/core/baseProvider.ts) for
+ * every provider's returned error, migrated or not, so duplicating it here
+ * would risk the two copies disagreeing.
+ */
+import { ProviderError, AuthenticationError, RateLimitError, InvalidModelError, NetworkError, } from "../types/index.js";
+import { TimeoutError } from "./timeout.js";
+import { duckTypedStatusCode } from "./providerRetry.js";
+function buildErrorContext(error, provider, modelName) {
+    const record = error && typeof error === "object"
+        ? error
+        : undefined;
+    const message = typeof record?.message === "string"
+        ? record.message
+        : error instanceof Error
+            ? error.message
+            : "Unknown error";
+    return {
+        error,
+        message,
+        statusCode: duckTypedStatusCode(error),
+        errorName: typeof record?.name === "string" ? record.name : undefined,
+        errorCode: typeof record?.code === "string" ? record.code : undefined,
+        provider,
+        modelName,
+    };
+}
+/**
+ * Classify a raw provider error into a NeuroLink `ProviderError` subclass.
+ * `rules` are tried in order; the first match wins. `TimeoutError` is
+ * always handled first, ahead of any rule table — every provider treated
+ * it identically before this change, so it is not made overridable.
+ */
+export function classifyProviderError(error, rules, provider, modelName) {
+    if (error instanceof TimeoutError) {
+        return new NetworkError(`Request timed out: ${error.message}`, provider);
+    }
+    const ctx = buildErrorContext(error, provider, modelName);
+    const rule = rules.find((r) => r.match(ctx));
+    if (!rule) {
+        return new ProviderError(`${provider} error: ${ctx.message}`, provider);
+    }
+    const message = typeof rule.message === "function" ? rule.message(ctx) : rule.message;
+    return new rule.errorClass(message, provider);
+}
+/**
+ * Generic fallback rule table covering the five categories every
+ * OpenAI-compatible provider already hand-rolled near-identically:
+ * auth (401), rate limit (429), model-not-found (404), network/connection
+ * errors, and 5xx server errors. Providers with a provider-specific auth
+ * message (naming the exact env var) prepend one override rule and spread
+ * this table after it — see errorClassifier usage in any migrated
+ * provider's formatProviderError for the pattern.
+ */
+export const DEFAULT_ERROR_RULES = [
+    {
+        match: (ctx) => ctx.statusCode === 401 ||
+            /API_KEY_INVALID|Invalid API key|Unauthorized|invalid_api_key/i.test(ctx.message),
+        errorClass: AuthenticationError,
+        message: (ctx) => `Invalid ${ctx.provider} API key. Please check your credentials.`,
+    },
+    {
+        match: (ctx) => ctx.statusCode === 429 || /rate limit/i.test(ctx.message),
+        errorClass: RateLimitError,
+        message: (ctx) => `${ctx.provider} rate limit exceeded. Please try again later.`,
+    },
+    {
+        match: (ctx) => ctx.statusCode === 404 ||
+            /model_not_found|model not found/i.test(ctx.message),
+        errorClass: InvalidModelError,
+        message: (ctx) => ctx.modelName
+            ? `${ctx.provider} model '${ctx.modelName}' not found.`
+            : `${ctx.provider} model not found.`,
+    },
+    {
+        match: (ctx) => /ECONNRESET|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|connection/i.test(ctx.message),
+        errorClass: NetworkError,
+        message: (ctx) => `Connection error: ${ctx.message}`,
+    },
+    {
+        match: (ctx) => (ctx.statusCode !== undefined && ctx.statusCode >= 500) ||
+            /\b5\d\d\b|server error/i.test(ctx.message),
+        errorClass: ProviderError,
+        message: (ctx) => `${ctx.provider} server error: ${ctx.message}`,
+    },
+];
+//# sourceMappingURL=errorClassifier.js.map