@juspay/neurolink 11.1.0 → 11.2.0

package/dist/lib/utils/providerConfig.js

@@ -185,6 +185,29 @@ export function getProviderModel(envVar, defaultModel) {
 export function hasProviderCredentials(envVars) {
     return envVars.some((envVar) => !!process.env[envVar]);
 }
+/**
+ * Evaluates a `ProviderDescriptor.envVars.extraRequiredFallbacks`-shaped
+ * list against an env-var source. Each entry is either a single env var
+ * name (satisfied on its own) or a nested array of names that must ALL be
+ * present together (e.g. Vertex's GOOGLE_AUTH_CLIENT_EMAIL +
+ * GOOGLE_AUTH_PRIVATE_KEY pair, which is only valid auth as a pair).
+ * Returns true when at least one entry is satisfied. The single evaluation
+ * site for this shape — every consumer (providerUtils.ts, providerHealth.ts,
+ * setup.ts, environmentManager.ts) must call this instead of re-deriving the
+ * same `.some()`/`.every()` logic, so they can't drift out of sync with each
+ * other or with the real auth gate (hasGoogleCredentials()).
+ * @param env Explicit env-var source (`process.env`, or a parsed .env file) —
+ *   never hardcoded, so callers checking a file's contents (not the live
+ *   process env) can reuse this too.
+ */
+export function satisfiesFallbacks(fallbacks, env) {
+    if (!fallbacks) {
+        return false;
+    }
+    return fallbacks.some((entry) => typeof entry === "string"
+        ? !!env[entry]
+        : entry.every((name) => !!env[name]));
+}
 // =============================================================================
 // PROVIDER-SPECIFIC CONFIGURATION CREATORS
 // =============================================================================
@@ -1277,4 +1300,64 @@ export function describeAnthropicConfig() {
     lines.push(`Priority Access: ${config.limits.priorityAccess ? "Yes" : "No"}`);
     return lines.join("\n");
 }
+/**
+ * Resolves the {apiKey, baseURL} pair for a config-driven OpenAI-compatible
+ * catalog entry (see OpenAICompatCatalogEntry in types/providers.ts).
+ *
+ * Extracted from the identical 6-line precedence block that was copy-pasted
+ * across groq.ts, xai.ts, togetherAi.ts, fireworks.ts, perplexity.ts, and
+ * mistral.ts, plus Cloudflare's accountId-computed-baseURL variant.
+ *
+ * Precedence (matches every ported subclass's original behavior exactly):
+ *   apiKey:  credentials.apiKey (trimmed, non-blank) > env var > throw
+ *   baseURL: credentials.baseURL (trimmed, non-blank)
+ *            > env var (if entry.baseURLEnvVar is set, trimmed, non-blank)
+ *            > entry.defaultBaseURL
+ *   baseURL (computedBaseURL entries, e.g. Cloudflare):
+ *            credentials.baseURL > computedBaseURL.build(accountId), where
+ *            accountId = credentials.accountId (trimmed) > env var (trimmed)
+ *            > throw computedBaseURL.missingValueMessage
+ */
+export function resolveOpenAICompatConfig(entry, credentials) {
+    const overrideApiKey = credentials?.apiKey?.trim();
+    const apiKey = overrideApiKey && overrideApiKey.length > 0
+        ? overrideApiKey
+        : validateApiKey(entry.configOptions);
+    if (entry.computedBaseURL) {
+        const { envVar, missingValueMessage, build } = entry.computedBaseURL;
+        // An explicit base URL is checked first and trimmed the same way the
+        // static branch trims it. It makes the account id irrelevant — there is
+        // nothing left to build — so demanding one anyway would reject a fully
+        // specified override.
+        const overrideComputedBaseURL = credentials?.baseURL?.trim();
+        if (overrideComputedBaseURL && overrideComputedBaseURL.length > 0) {
+            return { apiKey, baseURL: overrideComputedBaseURL };
+        }
+        const extraValue = (credentials?.accountId ??
+            process.env[envVar] ??
+            "").trim();
+        if (!extraValue) {
+            throw new Error(missingValueMessage);
+        }
+        return { apiKey, baseURL: build(extraValue) };
+    }
+    const overrideBaseURL = credentials?.baseURL?.trim();
+    const envBaseURL = entry.baseURLEnvVar
+        ? process.env[entry.baseURLEnvVar]?.trim()
+        : undefined;
+    const baseURL = (overrideBaseURL && overrideBaseURL.length > 0
+        ? overrideBaseURL
+        : undefined) ??
+        (envBaseURL && envBaseURL.length > 0 ? envBaseURL : undefined) ??
+        entry.defaultBaseURL;
+    if (!baseURL) {
+        // Reachable only for an entry that sets neither defaultBaseURL nor
+        // computedBaseURL. Returning "" instead would hand the SDK an empty base
+        // URL and surface as a confusing request failure far from the cause.
+        throw new Error(`${entry.providerName}: no base URL. Set one in credentials` +
+            (entry.baseURLEnvVar ? `, set ${entry.baseURLEnvVar}` : "") +
+            `, or give the catalog entry a defaultBaseURL.`);
+    }
+    return { apiKey, baseURL };
+}
 //# sourceMappingURL=providerConfig.js.map

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

@@ -36,27 +36,25 @@ export declare class ProviderHealthChecker {
      */
     private static checkModelAvailability;
     /**
-     * Providers whose credential model can't be reduced to "every one of
-     * these exact env vars must be literally set" — the check in
-     * checkEnvironmentConfiguration() below ANDs every entry in the
-     * returned list together, which can't express Vertex's file-OR-
-     * individual-creds-OR-service-account auth, Bedrock's AWS SDK default
-     * provider chain (profile / IAM role, no env vars at all), or
-     * LiteLLM's documented zero-config local proxy. Their real requirement
-     * is validated by checkProviderSpecificConfig()'s dedicated per-provider
-     * checks instead — matches the original hand-written switch's
-     * deliberate `return []` for exactly these three. Naively deriving
-     * [apiKey, ...extraRequired] from the descriptor here (as for the other
-     * 27 providers) would make checkEnvironmentConfiguration() push a false
-     * "missing environment variables" issue — and therefore isHealthy=false
-     * — for legitimate fallback-based Vertex auth, AWS_PROFILE/IAM-role
-     * Bedrock auth, and unauthenticated local LiteLLM proxies. See
-     * hasProviderEnvVars() in providerUtils.ts for the equivalent OR-aware
-     * check used for auto-select gating.
-     */
-    private static readonly ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG;
-    /**
-     * Get required environment variables for a provider
+     * Get required environment variables for a provider.
+     *
+     * Returns `[]` for providers with `descriptor.credentialsResolvedExternally
+     * === true` (Vertex, Bedrock, LiteLLM) — the check in
+     * checkEnvironmentConfiguration() below ANDs every entry in the returned
+     * list together, which can't express Vertex's file-OR-individual-creds-
+     * OR-service-account auth, Bedrock's AWS SDK default provider chain
+     * (profile / IAM role, no env vars at all), or LiteLLM's documented
+     * zero-config local proxy. Their real requirement is validated by
+     * checkProviderSpecificConfig()'s dedicated per-provider checks instead.
+     * Naively deriving [apiKey, ...extraRequired] from the descriptor for
+     * these three (as for the other 27 providers) would make
+     * checkEnvironmentConfiguration() push a false "missing environment
+     * variables" issue — and therefore isHealthy=false — for legitimate
+     * fallback-based Vertex auth, AWS_PROFILE/IAM-role Bedrock auth, and
+     * unauthenticated local LiteLLM proxies. See hasProviderEnvVars() in
+     * providerUtils.ts for the equivalent OR-aware check used for
+     * auto-select gating. See `ProviderDescriptor.credentialsResolvedExternally`
+     * (types/providers.ts) for the field's full documentation.
      */
     static getRequiredEnvironmentVariables(providerName: string): string[];
     /**
@@ -107,9 +105,17 @@ export declare class ProviderHealthChecker {
      */
     private static checkGoogleApplicationCredentials;
     /**
-     * Check individual Google credentials
-     */
-    private static checkIndividualGoogleCredentials;
+     * Check Vertex's non-file auth fallbacks (GOOGLE_APPLICATION_CREDENTIALS_
+     * NEUROLINK, GOOGLE_SERVICE_ACCOUNT_KEY, or the GOOGLE_AUTH_CLIENT_EMAIL +
+     * GOOGLE_AUTH_PRIVATE_KEY pair) via the descriptor's extraRequiredFallbacks
+     * instead of a hand-maintained env-var list, so this stays in sync with
+     * the real gating logic (hasGoogleCredentials()) the same way
+     * checkApiKeyValidity()'s vertex branch does. The previous hand-rolled
+     * version only recognized GOOGLE_SERVICE_ACCOUNT_KEY or the email+key
+     * pair — missing GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK, the
+     * descriptor's documented first-priority fallback.
+     */
+    private static checkExtraRequiredFallbackCredentials;
     /**
      * Check AWS Bedrock configuration
      */

package/dist/lib/utils/providerHealth.js

@@ -4,7 +4,7 @@
  */
 import { logger } from "./logger.js";
 import { AIProviderName, OpenAIModels, GoogleAIModels, AnthropicModels, BedrockModels, } from "../constants/enums.js";
-import { PROJECT_ID_FORMAT } from "./providerConfig.js";
+import { PROJECT_ID_FORMAT, satisfiesFallbacks } from "./providerConfig.js";
 import { basename } from "path";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
@@ -194,7 +194,7 @@ export class ProviderHealthChecker {
             const descriptor = ProviderFactory.getDescriptor(AIProviderName.VERTEX);
             const { extraRequired, extraRequiredFallbacks } = descriptor?.envVars ?? {};
             const hasValidAuth = (extraRequired ?? []).every((v) => !!process.env[v]) ||
-                (extraRequiredFallbacks ?? []).some((v) => !!process.env[v]);
+                satisfiesFallbacks(extraRequiredFallbacks, process.env);
             logger.debug("Vertex auth final result", { hasValidAuth });
             if (hasValidAuth) {
                 healthStatus.hasApiKey = true;
@@ -342,46 +342,40 @@ export class ProviderHealthChecker {
         }
     }
     /**
-     * Providers whose credential model can't be reduced to "every one of
-     * these exact env vars must be literally set" — the check in
-     * checkEnvironmentConfiguration() below ANDs every entry in the
-     * returned list together, which can't express Vertex's file-OR-
-     * individual-creds-OR-service-account auth, Bedrock's AWS SDK default
-     * provider chain (profile / IAM role, no env vars at all), or
-     * LiteLLM's documented zero-config local proxy. Their real requirement
-     * is validated by checkProviderSpecificConfig()'s dedicated per-provider
-     * checks instead — matches the original hand-written switch's
-     * deliberate `return []` for exactly these three. Naively deriving
-     * [apiKey, ...extraRequired] from the descriptor here (as for the other
-     * 27 providers) would make checkEnvironmentConfiguration() push a false
-     * "missing environment variables" issue — and therefore isHealthy=false
-     * — for legitimate fallback-based Vertex auth, AWS_PROFILE/IAM-role
-     * Bedrock auth, and unauthenticated local LiteLLM proxies. See
-     * hasProviderEnvVars() in providerUtils.ts for the equivalent OR-aware
-     * check used for auto-select gating.
-     */
-    static ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG = new Set([
-        AIProviderName.VERTEX,
-        AIProviderName.BEDROCK,
-        AIProviderName.LITELLM,
-    ]);
-    /**
-     * Get required environment variables for a provider
+     * Get required environment variables for a provider.
+     *
+     * Returns `[]` for providers with `descriptor.credentialsResolvedExternally
+     * === true` (Vertex, Bedrock, LiteLLM) — the check in
+     * checkEnvironmentConfiguration() below ANDs every entry in the returned
+     * list together, which can't express Vertex's file-OR-individual-creds-
+     * OR-service-account auth, Bedrock's AWS SDK default provider chain
+     * (profile / IAM role, no env vars at all), or LiteLLM's documented
+     * zero-config local proxy. Their real requirement is validated by
+     * checkProviderSpecificConfig()'s dedicated per-provider checks instead.
+     * Naively deriving [apiKey, ...extraRequired] from the descriptor for
+     * these three (as for the other 27 providers) would make
+     * checkEnvironmentConfiguration() push a false "missing environment
+     * variables" issue — and therefore isHealthy=false — for legitimate
+     * fallback-based Vertex auth, AWS_PROFILE/IAM-role Bedrock auth, and
+     * unauthenticated local LiteLLM proxies. See hasProviderEnvVars() in
+     * providerUtils.ts for the equivalent OR-aware check used for
+     * auto-select gating. See `ProviderDescriptor.credentialsResolvedExternally`
+     * (types/providers.ts) for the field's full documentation.
      */
     static getRequiredEnvironmentVariables(providerName) {
-        // Resolve the descriptor FIRST so the delegation-Set check below is
-        // keyed on the canonical, alias-resolved `descriptor.name` — not the
-        // raw, possibly-aliased `providerName` argument. Checking the raw
-        // input here would let documented aliases (e.g. "googleVertex" for
+        // Resolve the descriptor FIRST so the field check below is keyed on
+        // the canonical, alias-resolved `descriptor.credentialsResolvedExternally`
+        // — not the raw, possibly-aliased `providerName` argument. Checking the
+        // raw input here would let documented aliases (e.g. "googleVertex" for
         // vertex, "aws" for bedrock) skip the delegation and fall through to
         // the naive [apiKey, ...extraRequired] derivation below, reproducing
         // the exact false "missing environment variables" regression this
-        // Set exists to prevent.
+        // field exists to prevent.
         const descriptor = ProviderFactory.getDescriptor(providerName);
         if (!descriptor) {
             return [];
         }
-        if (this.ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG.has(descriptor.name)) {
+        if (descriptor.credentialsResolvedExternally) {
             return [];
         }
         const { apiKey, extraRequired } = descriptor.envVars;
@@ -518,11 +512,11 @@ export class ProviderHealthChecker {
             hasValidAuth = await this.checkGoogleApplicationCredentials(healthStatus);
         }
         if (!hasValidAuth) {
-            hasValidAuth = this.checkIndividualGoogleCredentials(healthStatus);
+            hasValidAuth = this.checkExtraRequiredFallbackCredentials(healthStatus);
         }
         if (!hasValidAuth) {
             healthStatus.configurationIssues.push("Google Cloud authentication not configured or credentials file missing");
-            healthStatus.recommendations.push("Set either GOOGLE_APPLICATION_CREDENTIALS (valid file path), GOOGLE_SERVICE_ACCOUNT_KEY (base64), or both GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY");
+            healthStatus.recommendations.push("Set either GOOGLE_APPLICATION_CREDENTIALS (valid file path), GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK, GOOGLE_SERVICE_ACCOUNT_KEY (base64), or both GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY");
         }
         return hasValidAuth;
     }
@@ -554,13 +548,20 @@ export class ProviderHealthChecker {
         }
     }
     /**
-     * Check individual Google credentials
+     * Check Vertex's non-file auth fallbacks (GOOGLE_APPLICATION_CREDENTIALS_
+     * NEUROLINK, GOOGLE_SERVICE_ACCOUNT_KEY, or the GOOGLE_AUTH_CLIENT_EMAIL +
+     * GOOGLE_AUTH_PRIVATE_KEY pair) via the descriptor's extraRequiredFallbacks
+     * instead of a hand-maintained env-var list, so this stays in sync with
+     * the real gating logic (hasGoogleCredentials()) the same way
+     * checkApiKeyValidity()'s vertex branch does. The previous hand-rolled
+     * version only recognized GOOGLE_SERVICE_ACCOUNT_KEY or the email+key
+     * pair — missing GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK, the
+     * descriptor's documented first-priority fallback.
      */
-    static checkIndividualGoogleCredentials(healthStatus) {
-        const hasServiceAccountKey = !!process.env.GOOGLE_SERVICE_ACCOUNT_KEY;
-        const hasIndividualCredentials = !!(process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
-            process.env.GOOGLE_AUTH_PRIVATE_KEY);
-        if (hasServiceAccountKey || hasIndividualCredentials) {
+    static checkExtraRequiredFallbackCredentials(healthStatus) {
+        const descriptor = ProviderFactory.getDescriptor(AIProviderName.VERTEX);
+        const hasValidAuth = satisfiesFallbacks(descriptor?.envVars.extraRequiredFallbacks, process.env);
+        if (hasValidAuth) {
             healthStatus.hasApiKey = true;
             return true;
         }

package/dist/lib/utils/providerUtils.js

@@ -6,7 +6,7 @@ import { AIProviderFactory } from "../core/factory.js";
 import { logger } from "./logger.js";
 import { AIProviderName } from "../constants/enums.js";
 import { ProviderHealthChecker } from "./providerHealth.js";
-import { API_KEY_FORMATS, API_KEY_LENGTHS, PROJECT_ID_FORMAT, } from "./providerConfig.js";
+import { API_KEY_FORMATS, API_KEY_LENGTHS, PROJECT_ID_FORMAT, satisfiesFallbacks, } from "./providerConfig.js";
 import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
 import { ProviderFactory } from "../factories/providerFactory.js";
 import { PROVIDER_DESCRIPTORS } from "../factories/providerDescriptors.js";
@@ -340,7 +340,7 @@ export function hasProviderEnvVars(provider) {
         return false;
     }
     return ((extraRequired ?? []).every((v) => !!process.env[v]) ||
-        (extraRequiredFallbacks ?? []).some((v) => !!process.env[v]));
+        satisfiesFallbacks(extraRequiredFallbacks, process.env));
 }
 /**
  * Get available provider names

package/dist/processors/base/BaseFileProcessor.d.ts

@@ -45,6 +45,23 @@
  */
 import { FileErrorCode } from "../errors/index.js";
 import type { BatchProcessingSummary, FileInfo, FileProcessingError, ProcessorFileProcessingResult, FileProcessorConfig, ProcessorOperationResult, ProcessedFileBase, ProcessOptions } from "../../types/index.js";
+/**
+ * Marker on the error raised when a processor refuses content for exceeding
+ * the size limit *after* the download — a ZIP entry that expands past the
+ * bound, say.
+ *
+ * Separate from DOWNLOAD_TOO_LARGE because the two fire at different stages,
+ * but it exists for the same reason. Without it a bound that fires reaches
+ * `buildProcessedResultWithResult` as a plain Error and becomes
+ * PROCESSING_FAILED, which is `retryable: true` — so a caller retries a
+ * deterministic refusal three times and gets the identical answer each time.
+ * FILE_TOO_LARGE is `retryable: false`, which is the truth about this failure.
+ */
+export declare const CONTENT_TOO_LARGE_CODE = "CONTENT_TOO_LARGE";
+/** An error that a processor's own size bound was exceeded. */
+export declare function contentTooLargeError(message: string): Error;
+/** Whether `error` is a processor size bound firing rather than a fault. */
+export declare function isContentTooLarge(error: unknown): boolean;
 /**
  * Abstract base class for file processors.
  * Provides common download, validation, and error handling functionality.

package/dist/processors/base/BaseFileProcessor.js

@@ -72,6 +72,29 @@ function downloadTooLargeError(maxSizeMB, typeName) {
 function isDownloadTooLarge(error) {
     return (error?.code === DOWNLOAD_TOO_LARGE_CODE);
 }
+/**
+ * Marker on the error raised when a processor refuses content for exceeding
+ * the size limit *after* the download — a ZIP entry that expands past the
+ * bound, say.
+ *
+ * Separate from DOWNLOAD_TOO_LARGE because the two fire at different stages,
+ * but it exists for the same reason. Without it a bound that fires reaches
+ * `buildProcessedResultWithResult` as a plain Error and becomes
+ * PROCESSING_FAILED, which is `retryable: true` — so a caller retries a
+ * deterministic refusal three times and gets the identical answer each time.
+ * FILE_TOO_LARGE is `retryable: false`, which is the truth about this failure.
+ */
+export const CONTENT_TOO_LARGE_CODE = "CONTENT_TOO_LARGE";
+/** An error that a processor's own size bound was exceeded. */
+export function contentTooLargeError(message) {
+    const error = new Error(message);
+    error.code = CONTENT_TOO_LARGE_CODE;
+    return error;
+}
+/** Whether `error` is a processor size bound firing rather than a fault. */
+export function isContentTooLarge(error) {
+    return (error?.code === CONTENT_TOO_LARGE_CODE);
+}
 /** Node's signal that a zlib output bound was reached. */
 function isBufferTooLargeError(error) {
     return (error?.code === "ERR_BUFFER_TOO_LARGE");
@@ -360,6 +383,23 @@ export class BaseFileProcessor {
             return { success: true, data: result };
         }
         catch (error) {
+            // A size bound firing is a verdict, not a fault: PROCESSING_FAILED is
+            // retryable, and re-running a decompression that will hit the same
+            // ceiling is the one thing worth not doing three times.
+            if (isContentTooLarge(error)) {
+                return {
+                    success: false,
+                    // Same detail keys as the other FILE_TOO_LARGE sites, so anything
+                    // reading them does not have to special-case where the verdict came
+                    // from. `sizeMB` is absent on purpose: the decompressed size is the
+                    // number this bound exists to never find out.
+                    error: this.createError(FileErrorCode.FILE_TOO_LARGE, {
+                        maxMB: this.config.maxSizeMB,
+                        type: this.config.fileTypeName,
+                        reason: error instanceof Error ? error.message : undefined,
+                    }),
+                };
+            }
             return {
                 success: false,
                 error: this.createError(FileErrorCode.PROCESSING_FAILED, { fileType: this.config.fileTypeName }, error instanceof Error ? error : undefined),

package/dist/processors/document/OpenDocumentProcessor.js

@@ -8,7 +8,7 @@
  */
 import { createRequire } from "node:module";
 import * as zlib from "node:zlib";
-import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import { BaseFileProcessor, contentTooLargeError, isContentTooLarge, } from "../base/BaseFileProcessor.js";
 import { readZipEntryWithinLimit } from "../archive/zipEntryReader.js";
 import { SIZE_LIMITS } from "../config/index.js";
 const require = createRequire(import.meta.url);
@@ -71,7 +71,10 @@ export class OpenDocumentProcessor extends BaseFileProcessor {
                 // `maxSizeMB` only ever saw the compressed archive on the way in.
                 const read = readZipEntryWithinLimit(contentEntry, SIZE_LIMITS.DOCUMENT_MAX_MB * 1024 * 1024, zlib);
                 if (read.status === "too-large") {
-                    throw new Error(`content.xml exceeds the ${SIZE_LIMITS.DOCUMENT_MAX_MB}MB limit for OpenDocument content`);
+                    // Coded, so the bound surfaces as FILE_TOO_LARGE (not retryable)
+                    // rather than PROCESSING_FAILED (retryable). The file will be
+                    // exactly as oversized on the next attempt.
+                    throw contentTooLargeError(`content.xml in "${this.getFilename(fileInfo)}" exceeds the ${SIZE_LIMITS.DOCUMENT_MAX_MB}MB limit for OpenDocument content`);
                 }
                 if (read.status !== "ok") {
                     throw new Error("content.xml could not be read from the archive");
@@ -93,6 +96,13 @@ export class OpenDocumentProcessor extends BaseFileProcessor {
             }
         }
         catch (error) {
+            // A size verdict passes through intact. Re-wrapping it as a plain Error
+            // drops the code, and the base class then reports PROCESSING_FAILED —
+            // which is retryable, so the caller would refetch and decompress a file
+            // guaranteed to be exactly as oversized.
+            if (isContentTooLarge(error)) {
+                throw error;
+            }
             const message = error instanceof Error ? error.message : "Unknown error";
             throw new Error(`Failed to extract OpenDocument content: ${message}`, {
                 cause: error,

package/dist/providers/configuredOpenAICompat.d.ts

@@ -0,0 +1,24 @@
+import type { AIProviderName } from "../constants/enums.js";
+import type { OpenAICompatCatalogEntry, OpenAICompatCredentials } from "../types/index.js";
+import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
+/**
+ * Generic OpenAI-compatible provider driven entirely by an
+ * OpenAICompatCatalogEntry. Replaces a hand-written subclass for any
+ * provider whose only differences from its siblings are credentials, base
+ * URL, model defaults, and error-classification rules — see
+ * OPENAI_COMPAT_CATALOG in openaiCompatCatalog.ts for the entries.
+ *
+ * If a provider needs a real hook override (adjustRequestBody,
+ * adjustBodyAfter400, getChatCompletionsURL, getAuthHeaders,
+ * suppressResponseFormatWithTools, ...) it does NOT belong in the catalog —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts).
+ */
+export declare class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvider {
+    private readonly entry;
+    constructor(entry: OpenAICompatCatalogEntry, modelName?: string, sdk?: unknown, credentials?: OpenAICompatCredentials);
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    protected getFallbackModelName(): string;
+    protected getFallbackModels(): string[];
+    protected formatProviderError(error: unknown): Error;
+}

package/dist/providers/configuredOpenAICompat.js

@@ -0,0 +1,59 @@
+import { logger } from "../utils/logger.js";
+import { redactUrlCredentials } from "../utils/logSanitize.js";
+import { getProviderModel, resolveOpenAICompatConfig, } from "../utils/providerConfig.js";
+import { classifyProviderError } from "../utils/errorClassifier.js";
+import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
+/**
+ * Generic OpenAI-compatible provider driven entirely by an
+ * OpenAICompatCatalogEntry. Replaces a hand-written subclass for any
+ * provider whose only differences from its siblings are credentials, base
+ * URL, model defaults, and error-classification rules — see
+ * OPENAI_COMPAT_CATALOG in openaiCompatCatalog.ts for the entries.
+ *
+ * If a provider needs a real hook override (adjustRequestBody,
+ * adjustBodyAfter400, getChatCompletionsURL, getAuthHeaders,
+ * suppressResponseFormatWithTools, ...) it does NOT belong in the catalog —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts).
+ */
+export class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvider {
+    entry;
+    constructor(entry, modelName, sdk, credentials) {
+        const { apiKey, baseURL } = resolveOpenAICompatConfig(entry, credentials);
+        // BaseProvider's constructor calls `this.getDefaultModel()` /
+        // `this.getProviderName()` synchronously inside `super()`, before this
+        // class's own constructor body (or field initializers) ever run — so
+        // `this.entry` is not yet assigned at that point and those overrides
+        // would read `undefined.modelEnvVar`. `entry.providerName` is always
+        // defined, so passing it straight through makes the base constructor's
+        // `providerName || this.getProviderName()` short-circuit; resolving the
+        // model up front and always passing a truthy `modelName` does the same
+        // for `getDefaultModel()`. Both overrides remain correct for any call
+        // made after construction, once `this.entry` is set below.
+        const resolvedModelName = modelName || getProviderModel(entry.modelEnvVar, entry.defaultModel);
+        super(entry.providerName, resolvedModelName, sdk, { baseURL, apiKey });
+        this.entry = entry;
+        logger.debug(`${entry.configOptions.providerName} Provider initialized`, {
+            modelName: this.modelName,
+            providerName: this.providerName,
+            baseURL: redactUrlCredentials(this.config.baseURL),
+        });
+    }
+    getProviderName() {
+        return this.entry.providerName;
+    }
+    getDefaultModel() {
+        return getProviderModel(this.entry.modelEnvVar, this.entry.defaultModel);
+    }
+    getFallbackModelName() {
+        return this.entry.fallbackModelName;
+    }
+    getFallbackModels() {
+        return this.entry.fallbackModels;
+    }
+    formatProviderError(error) {
+        // classifyProviderError handles TimeoutError internally (always maps
+        // to NetworkError, ahead of any rule table) — no local pre-check
+        // needed or wanted here; see this task's design note.
+        return classifyProviderError(error, this.entry.errorRules, this.entry.providerName, this.modelName);
+    }
+}

package/dist/providers/openaiCompatCatalog.d.ts

@@ -0,0 +1,24 @@
+import type { OpenAICompatCatalogEntry } from "../types/index.js";
+/**
+ * Config-driven catalog of the 7 zero-quirk OpenAI-compatible providers.
+ * Each entry fully replaces what used to be a hand-written
+ * OpenAIChatCompletionsProvider subclass — see ConfiguredOpenAICompatProvider
+ * for the class that reads these entries, and providerRegistry.ts for the
+ * registration loop that consumes this array.
+ *
+ * `errorRules` mirrors each provider's LIVE `formatProviderError` rule array
+ * (post plan-07/wave-2 migration), not the original hand-rolled ladder these
+ * providers had when plan 05 was first drafted: every provider below now
+ * keeps only its bespoke rule(s) — auth, plus Groq's model_decommissioned and
+ * xAI's insufficient_quota — before spreading the SAME exported
+ * `DEFAULT_ERROR_RULES` constant that the live subclasses spread (never an
+ * inlined copy, so this catalog cannot drift from that table independently).
+ * See plan-05/progress.md Ruling R4 for the full rationale.
+ *
+ * To add a new zero-quirk OpenAI-compatible provider: add one entry here.
+ * Do NOT add a provider here if it needs any hook override beyond the 3
+ * mandatory ones (getProviderName/getDefaultModel/formatProviderError) —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts, and
+ * Task 14's docs task for the deciding criteria).
+ */
+export declare const OPENAI_COMPAT_CATALOG: readonly OpenAICompatCatalogEntry[];