@juspay/neurolink 11.1.1 → 11.2.0

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[];

package/dist/providers/openaiCompatCatalog.js

@@ -0,0 +1,271 @@
+import { AIProviderName } from "../constants/enums.js";
+import { CloudflareModels, FireworksModels, GroqModels, MistralModels, PerplexityModels, TogetherAIModels, XaiModels, } from "../constants/enums.js";
+import { AuthenticationError, InvalidModelError, ProviderError, } from "../types/index.js";
+import { DEFAULT_ERROR_RULES } from "../utils/errorClassifier.js";
+import { createCloudflareConfig, createFireworksConfig, createGroqConfig, createMistralConfig, createPerplexityConfig, createTogetherAIConfig, createXaiConfig, } from "../utils/providerConfig.js";
+function buildCloudflareBaseURL(accountId) {
+    return `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`;
+}
+/**
+ * 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 const OPENAI_COMPAT_CATALOG = [
+    {
+        providerName: AIProviderName.GROQ,
+        aliases: ["groq"],
+        apiKeyEnvVar: "GROQ_API_KEY",
+        baseURLEnvVar: "GROQ_BASE_URL",
+        defaultBaseURL: "https://api.groq.com/openai/v1",
+        configOptions: createGroqConfig(),
+        modelEnvVar: "GROQ_MODEL",
+        defaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
+        registryDefaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: GroqModels.LLAMA_3_1_8B_INSTANT,
+        fallbackModels: [
+            GroqModels.LLAMA_3_3_70B_VERSATILE,
+            GroqModels.LLAMA_3_1_8B_INSTANT,
+            GroqModels.GEMMA_2_9B_IT,
+            GroqModels.MIXTRAL_8X7B_32768,
+            GroqModels.LLAMA_3_2_90B_VISION_PREVIEW,
+            GroqModels.LLAMA_3_2_11B_VISION_PREVIEW,
+        ],
+        // KNOWN GAP (not reproducible by this data-only array — flagged for PR C,
+        // see plan-05/task-A-report.md): live GroqProvider.formatProviderError()
+        // intercepts TimeoutError and returns a plain ProviderError BEFORE ever
+        // calling classifyProviderError, overriding that function's own
+        // (non-overridable) rule that TimeoutError always maps to NetworkError.
+        // ConfiguredOpenAICompatProvider.formatProviderError() has no such
+        // pre-check hook, so migrating Groq onto it as-is would silently
+        // reclassify Groq timeouts as NetworkError. This entry's errorRules
+        // still mirrors Groq's live rule array faithfully for every other error
+        // shape; the TimeoutError special case is a structural gap in
+        // ConfiguredOpenAICompatProvider, not a data error here.
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Groq API key. Check GROQ_API_KEY. Get one at https://console.groq.com/keys",
+            },
+            {
+                match: (ctx) => /model_decommissioned/i.test(ctx.message),
+                errorClass: InvalidModelError,
+                message: (ctx) => `Groq model '${ctx.modelName}' was decommissioned. Pick a current model from https://console.groq.com/docs/models.`,
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.XAI,
+        aliases: ["xai", "grok"],
+        apiKeyEnvVar: "XAI_API_KEY",
+        baseURLEnvVar: "XAI_BASE_URL",
+        defaultBaseURL: "https://api.x.ai/v1",
+        configOptions: createXaiConfig(),
+        modelEnvVar: "XAI_MODEL",
+        defaultModel: XaiModels.GROK_3,
+        registryDefaultModel: XaiModels.GROK_3,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: XaiModels.GROK_3_MINI,
+        fallbackModels: [
+            XaiModels.GROK_3,
+            XaiModels.GROK_3_MINI,
+            XaiModels.GROK_2_LATEST,
+            XaiModels.GROK_2_VISION_LATEST,
+            XaiModels.GROK_BETA,
+        ],
+        errorRules: [
+            {
+                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,
+        ],
+    },
+    {
+        providerName: AIProviderName.TOGETHER_AI,
+        aliases: ["together-ai", "together"],
+        apiKeyEnvVar: "TOGETHER_API_KEY",
+        baseURLEnvVar: "TOGETHER_BASE_URL",
+        defaultBaseURL: "https://api.together.xyz/v1",
+        configOptions: createTogetherAIConfig(),
+        modelEnvVar: "TOGETHER_MODEL",
+        defaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+        registryDefaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
+        fallbackModels: [
+            TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_405B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_70B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
+            TogetherAIModels.MIXTRAL_8X22B_INSTRUCT,
+            TogetherAIModels.QWEN_2_5_72B_INSTRUCT_TURBO,
+            TogetherAIModels.DEEPSEEK_R1,
+            TogetherAIModels.DEEPSEEK_V3,
+        ],
+        errorRules: [
+            {
+                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,
+        ],
+    },
+    {
+        providerName: AIProviderName.FIREWORKS,
+        aliases: ["fireworks"],
+        apiKeyEnvVar: "FIREWORKS_API_KEY",
+        baseURLEnvVar: "FIREWORKS_BASE_URL",
+        defaultBaseURL: "https://api.fireworks.ai/inference/v1",
+        configOptions: createFireworksConfig(),
+        modelEnvVar: "FIREWORKS_MODEL",
+        defaultModel: FireworksModels.DEEPSEEK_V4_PRO,
+        registryDefaultModel: FireworksModels.DEEPSEEK_V4_PRO,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: FireworksModels.DEEPSEEK_V4_PRO,
+        fallbackModels: [
+            FireworksModels.DEEPSEEK_V4_PRO,
+            FireworksModels.GLM_5P1,
+            FireworksModels.GLM_5,
+            FireworksModels.KIMI_K2P6,
+            FireworksModels.KIMI_K2P5,
+            FireworksModels.GPT_OSS_120B,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Fireworks API key. Get one at https://fireworks.ai/account/api-keys",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.PERPLEXITY,
+        aliases: ["perplexity", "pplx"],
+        apiKeyEnvVar: "PERPLEXITY_API_KEY",
+        baseURLEnvVar: "PERPLEXITY_BASE_URL",
+        defaultBaseURL: "https://api.perplexity.ai",
+        configOptions: createPerplexityConfig(),
+        modelEnvVar: "PERPLEXITY_MODEL",
+        defaultModel: PerplexityModels.SONAR,
+        registryDefaultModel: PerplexityModels.SONAR,
+        registryDefaultModelChecksEnvVar: true,
+        // Perplexity's live class does NOT override getFallbackModelName() — it
+        // inherits the base class default "gpt-3.5-turbo". Preserved here
+        // verbatim, not "fixed" to a Perplexity model — that's a real,
+        // pre-existing quirk this plan is not authorized to change.
+        fallbackModelName: "gpt-3.5-turbo",
+        fallbackModels: [
+            PerplexityModels.SONAR,
+            PerplexityModels.SONAR_PRO,
+            PerplexityModels.SONAR_REASONING,
+            PerplexityModels.SONAR_REASONING_PRO,
+            PerplexityModels.SONAR_DEEP_RESEARCH,
+        ],
+        errorRules: [
+            {
+                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,
+        ],
+    },
+    {
+        providerName: AIProviderName.MISTRAL,
+        aliases: ["mistral"],
+        apiKeyEnvVar: "MISTRAL_API_KEY",
+        baseURLEnvVar: "MISTRAL_BASE_URL",
+        defaultBaseURL: "https://api.mistral.ai/v1",
+        configOptions: createMistralConfig(),
+        modelEnvVar: "MISTRAL_MODEL",
+        defaultModel: MistralModels.MISTRAL_SMALL_2506,
+        // The one documented registry-vs-class default-model quirk (see this
+        // plan's "Design reference" section): the registry passes the bare
+        // literal MISTRAL_LARGE_LATEST with no env-var check, while
+        // MistralProvider.getDefaultModel() checks MISTRAL_MODEL and defaults to
+        // MISTRAL_SMALL_2506. Preserved exactly, not reconciled.
+        registryDefaultModel: MistralModels.MISTRAL_LARGE_LATEST,
+        registryDefaultModelChecksEnvVar: false,
+        fallbackModelName: MistralModels.MISTRAL_SMALL_2506,
+        fallbackModels: [
+            MistralModels.MISTRAL_SMALL_2506,
+            MistralModels.MISTRAL_LARGE_LATEST,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /API_KEY_INVALID|Invalid API key|Unauthorized/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Mistral API key. Please check your MISTRAL_API_KEY environment variable.",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.CLOUDFLARE,
+        aliases: ["cloudflare", "workers-ai", "cf-ai"],
+        apiKeyEnvVar: "CLOUDFLARE_API_KEY",
+        computedBaseURL: {
+            envVar: "CLOUDFLARE_ACCOUNT_ID",
+            missingValueMessage: "CLOUDFLARE_ACCOUNT_ID is required (or pass credentials.cloudflare.accountId). Get the account id from https://dash.cloudflare.com/",
+            build: buildCloudflareBaseURL,
+        },
+        configOptions: createCloudflareConfig(),
+        modelEnvVar: "CLOUDFLARE_MODEL",
+        defaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
+        registryDefaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: CloudflareModels.LLAMA_3_1_8B_FAST,
+        fallbackModels: [
+            CloudflareModels.LLAMA_3_3_70B_FAST,
+            CloudflareModels.LLAMA_3_1_70B_INSTRUCT,
+            CloudflareModels.LLAMA_3_1_8B_FAST,
+            CloudflareModels.LLAMA_3_2_11B_VISION,
+            CloudflareModels.MISTRAL_7B_INSTRUCT_V0_2,
+            CloudflareModels.QWEN_1P5_14B_CHAT_AWQ,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Cloudflare API key. Use a token with Workers AI Read+Write scope. Get one at https://dash.cloudflare.com/profile/api-tokens",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+];

package/dist/types/providers.d.ts

@@ -8,6 +8,7 @@ import type { ValidationSchema } from "./aliases.js";
 import type { EnhancedGenerateResult, GenerateResult, TextGenerationOptions } from "./generate.js";
 import type { MultimodalAudioEntry } from "./file.js";
 import type { StreamOptions, StreamResult } from "./stream.js";
+import type { ProviderErrorRule } from "./errors.js";
 import type { ExternalMCPToolInfo } from "./externalMcp.js";
 import type { ClaudeSubscriptionTier, AnthropicAuthMethod, AnthropicAuthConfig, SubscriptionInfo, OAuthToken } from "./subscription.js";
 import type { Tool } from "./tools.js";
@@ -577,6 +578,104 @@ export type ProviderConfigOptions = {
     fallbackEnvVars?: string[];
     optional?: boolean;
 };
+/**
+ * Minimal credential shape accepted by resolveOpenAICompatConfig() and
+ * ConfiguredOpenAICompatProvider. A structural superset of every real
+ * per-provider NeurolinkCredentials["<key>"] slice in this family (groq,
+ * xai, together, fireworks, perplexity, mistral, cloudflare) — all fields
+ * optional, so passing e.g. NeurolinkCredentials["groq"] (which has no
+ * accountId) here is always structurally valid.
+ */
+export type OpenAICompatCredentials = {
+    apiKey?: string;
+    baseURL?: string;
+    accountId?: string;
+};
+/**
+ * One row of the config-driven OpenAI-compatible provider catalog
+ * (OPENAI_COMPAT_CATALOG, src/lib/providers/openaiCompatCatalog.ts).
+ * Replaces a hand-written OpenAIChatCompletionsProvider subclass for
+ * providers whose only differences from every sibling are credentials,
+ * base URL, model defaults, and error-message classification.
+ */
+export type OpenAICompatCatalogEntry = {
+    /** Registry key / nl.generate({provider}) value, e.g. "groq". */
+    providerName: AIProviderName;
+    /** Registry aliases, e.g. ["together-ai", "together"]. */
+    aliases: string[];
+    /**
+     * Env var holding the API key, e.g. "GROQ_API_KEY".
+     *
+     * Declarative: the key is actually read through `configOptions.envVarName`,
+     * which `validateApiKey` consults. This field exists so an entry states its
+     * credential source without a caller having to reach into configOptions,
+     * and the catalog suite asserts the two always name the same variable — two
+     * fields describing one fact are worth nothing if they can disagree.
+     */
+    apiKeyEnvVar: string;
+    /**
+     * Env var that can override the base URL, e.g. "GROQ_BASE_URL". Omit
+     * for entries that use computedBaseURL instead (e.g. Cloudflare).
+     */
+    baseURLEnvVar?: string;
+    /** Static default base URL. Omit for computedBaseURL entries. */
+    defaultBaseURL?: string;
+    /**
+     * Present only for providers whose base URL is computed from an extra
+     * required credential value instead of a static default (Cloudflare's
+     * accountId). Deliberately narrow (accountId-shaped) rather than a
+     * generic extra-field mechanism — Cloudflare is the only current user.
+     */
+    computedBaseURL?: {
+        /** Env var fallback for the extra value, e.g. "CLOUDFLARE_ACCOUNT_ID". */
+        envVar: string;
+        /** Thrown when neither credentials.accountId nor envVar supply a value. */
+        missingValueMessage: string;
+        /** Builds the base URL from the resolved accountId. */
+        build: (accountId: string) => string;
+    };
+    /** Setup/help metadata, passed to validateApiKey(). Not consumed by
+     *  classifyProviderError() — that function's ProviderErrorContext has no
+     *  docsUrl field; any URL a rule's message needs is inlined in the rule
+     *  itself (see Task 4). */
+    configOptions: ProviderConfigOptions;
+    /** Env var for the default model, e.g. "GROQ_MODEL". */
+    modelEnvVar: string;
+    /** Default model when modelEnvVar is unset. */
+    defaultModel: string;
+    /**
+     * The literal passed as ProviderFactory.registerProvider()'s defaultModel
+     * argument (resolved before the provider is constructed). Preserves each
+     * provider's exact pre-migration registry behavior.
+     */
+    registryDefaultModel: string;
+    /**
+     * True for every provider except Mistral: whether the registry-level
+     * default also consults modelEnvVar before falling back to
+     * registryDefaultModel. False is a pre-existing, intentionally-preserved
+     * quirk unique to Mistral's registration (see plan's Design reference).
+     */
+    registryDefaultModelChecksEnvVar: boolean;
+    /** Fallback model name (getFallbackModelName()). */
+    fallbackModelName: string;
+    /** Fallback model list (getFallbackModels()). */
+    fallbackModels: string[];
+    /**
+     * Error-classification rules, consumed by classifyProviderError. Typed
+     * as a mutable array — not readonly — because plan 07's
+     * `classifyProviderError(error, rules: ProviderErrorRule[], provider, modelName?)`
+     * declares `rules` as `ProviderErrorRule[]`; a `readonly` array here
+     * would not be assignable to that parameter without a cast, which rule
+     * 14 (no double assertions) and general hygiene both rule out. Each
+     * entry's array is still constructed as a fresh literal per provider in
+     * Task 4, so nothing actually mutates it at runtime.
+     */
+    errorRules: ProviderErrorRule[];
+};
+/** The subset of OpenAICompatCatalogEntry that resolveOpenAICompatConfig()
+ *  needs — lets call sites pass a minimal object without the full catalog
+ *  entry (e.g. in tests, or a future non-catalog caller). */
+export type OpenAICompatConfigInput = Pick<OpenAICompatCatalogEntry, "providerName" | "apiKeyEnvVar" | "baseURLEnvVar" | "defaultBaseURL" | "computedBaseURL" | "configOptions">;
 /**
  * AI Provider type with flexible parameter support
  */

package/dist/utils/providerConfig.d.ts

@@ -5,7 +5,7 @@
  * Enhanced with format validation and advanced error classification
  * Extended with Claude subscription OAuth support
  */
-import type { APIValidationResult, ProviderConfigOptions, AnthropicAuthMethod, ClaudeSubscriptionTier, AnthropicAuthConfig, AnthropicAuthConfigResult } from "../types/index.js";
+import type { APIValidationResult, ProviderConfigOptions, AnthropicAuthMethod, ClaudeSubscriptionTier, AnthropicAuthConfig, AnthropicAuthConfigResult, OpenAICompatConfigInput, OpenAICompatCredentials } from "../types/index.js";
 /**
  * API key format validation patterns (extracted from advanced validation system)
  * Exported for use across the codebase to replace scattered regex patterns
@@ -369,3 +369,25 @@ export declare function hasSubscriptionFeature(feature: "extended_thinking" | "p
  * @returns Human-readable configuration description
  */
 export declare function describeAnthropicConfig(): string;
+/**
+ * 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 declare function resolveOpenAICompatConfig(entry: OpenAICompatConfigInput, credentials?: OpenAICompatCredentials): {
+    apiKey: string;
+    baseURL: string;
+};

package/dist/utils/providerConfig.js

@@ -1300,3 +1300,63 @@ 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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.1.1",
+  "version": "11.2.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -94,6 +94,7 @@
     "test:mcp:spans": "npx tsx test/continuous-test-suite-mcp-spans.ts",
     "test:mcp:infra": "npx tsx test/continuous-test-suite-mcp-infra.ts",
     "test:providers-mocked": "npx tsx test/continuous-test-suite-providers-mocked.ts",
+    "test:openai-compat-catalog": "npx tsx test/continuous-test-suite-openai-compat-catalog.ts",
     "test:provider-descriptors": "npx tsx test/continuous-test-suite-provider-descriptors.ts",
     "test:provider-structure": "npx tsx test/continuous-test-suite-provider-structure.ts",
     "test:provider-fallback": "npx tsx test/continuous-test-suite-provider-fallback.ts",