@x12i/ai-providers-router 4.8.12 → 4.9.0

package/dist/factory.js

@@ -1,7 +1,7 @@
 import { applyPackageLogLevelsFromEnv } from '@x12i/logxer';
 import { LLMProviderRouter } from './router/RouterWrapper.js';
 import dns from 'node:dns';
-import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC, resolveUseOpenRouter } from './utils/openrouterEnv.js';
+import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC, resolvePreferOpenRouterPolicy } from './utils/openrouterEnv.js';
 import dotenv from 'dotenv';
 // Fix IPv6-first DNS resolution issue on Windows (forces IPv4-first to avoid connect timeouts)
 // This prevents undici from trying IPv6 first on networks that silently drop IPv6 traffic
@@ -121,7 +121,7 @@ export async function createRouter(config) {
                 apiKey: OPENROUTER_API_KEY_ERC,
                 httpReferer: 'ENV.OPENROUTER_HTTP_REFERER||ENV.OPEN_ROUTER_HTTP_REFERER',
                 xTitle: 'ENV.OPENROUTER_X_TITLE||ENV.OPEN_ROUTER_X_TITLE',
-                useOpenRouter: 'ENV.USE_OPENROUTER',
+                preferOpenRouter: 'ENV.PREFER_OPENROUTER||ENV.USE_OPENROUTER',
             },
         },
     };
@@ -134,19 +134,19 @@ export async function createRouter(config) {
         ercResult.config.providers.openrouter.apiKey = resolvedOpenRouterKey;
     }
     // Use explicit config if provided (Advanced Mode), otherwise use ERC auto-discovered config (Zero-Config Mode)
-    const useOpenRouter = resolveUseOpenRouter({
-        userValue: config?.useOpenRouter,
+    const preferOpenRouter = resolvePreferOpenRouterPolicy({
+        userValue: config?.preferOpenRouter ?? config?.useOpenRouter,
     });
     const finalConfig = Object.keys(config || {}).length > 0 ? {
         ...config,
-        useOpenRouter: config?.useOpenRouter ?? useOpenRouter,
+        preferOpenRouter: config?.preferOpenRouter ?? config?.useOpenRouter ?? preferOpenRouter,
     } : {
         logLevel: (ercResult.config.router.logsLevel ||
             ercResult.config.router.logLevel),
         verbose: ercResult.config.router.verbose === 'true' || ercResult.config.router.verbose === true,
         timeoutMs: ercResult.config.router.timeoutMs ? parseInt(String(ercResult.config.router.timeoutMs), 10) : undefined,
         defaultTimeoutMs: ercResult.config.router.timeoutMs ? parseInt(String(ercResult.config.router.timeoutMs), 10) : undefined,
-        useOpenRouter,
+        preferOpenRouter,
     };
     const router = new LLMProviderRouter(finalConfig);
     // Configure providers from ERC auto-detected config OR explicit config

package/dist/router/Router.d.ts

@@ -16,7 +16,7 @@ export declare class AIRouter {
     private resolveProviderNameForCandidate;
     /**
      * Resolve provider name from request.
-     * Prefers OpenRouter when USE_OPENROUTER is true (default); falls back to OpenRouter when
+     * Prefers OpenRouter when PREFER_OPENROUTER is true (default) and a key is present; falls back to OpenRouter when
      * the requested vendor has no direct provider registered but an OpenRouter key exists.
      */
     private resolveProviderName;

package/dist/router/Router.js

@@ -33,7 +33,7 @@ export class AIRouter {
     }
     /**
      * Resolve provider name from request.
-     * Prefers OpenRouter when USE_OPENROUTER is true (default); falls back to OpenRouter when
+     * Prefers OpenRouter when PREFER_OPENROUTER is true (default) and a key is present; falls back to OpenRouter when
      * the requested vendor has no direct provider registered but an OpenRouter key exists.
      */
     resolveProviderName(input) {

package/dist/router/RouterTypes.d.ts

@@ -104,9 +104,11 @@ export interface RouterConfig {
     defaultTimeoutMs?: number;
     /**
      * Prefer OpenRouter for vendor calls when OPENROUTER_API_KEY is set (default: true).
-     * Maps to USE_OPENROUTER env. When false, direct providers are used when keys exist;
+     * Maps to PREFER_OPENROUTER env. When false, direct providers are used when keys exist;
      * OpenRouter is still used as fallback for providers without a direct key.
      */
+    preferOpenRouter?: boolean;
+    /** @deprecated Use preferOpenRouter (maps to USE_OPENROUTER env as legacy fallback). */
     useOpenRouter?: boolean;
     /** OpenRouter provider config (e.g. from gateway); used when env OPEN_ROUTER_KEY is not visible */
     openrouter?: {

package/dist/utils/openrouterEnv.d.ts

@@ -6,21 +6,32 @@ export declare function resolveOpenRouterApiKey(): string | undefined;
 export declare function hasOpenRouterApiKey(): boolean;
 /** ERC placeholder resolution: prefer canonical name, fall back to legacy. */
 export declare const OPENROUTER_API_KEY_ERC = "ENV.OPENROUTER_API_KEY||ENV.OPEN_ROUTER_KEY";
-export interface ResolveUseOpenRouterOptions {
-    /** Programmatic override from RouterConfig.useOpenRouter — wins over environment. */
+export interface ResolvePreferOpenRouterOptions {
+    /** Programmatic override from RouterConfig.preferOpenRouter — wins over environment. */
     userValue?: boolean;
     /** For tests; defaults to `process.env`. */
     env?: NodeJS.ProcessEnv;
 }
+/** @deprecated Use ResolvePreferOpenRouterOptions */
+export type ResolveUseOpenRouterOptions = ResolvePreferOpenRouterOptions;
+export interface PreferOpenRouterConfig {
+    preferOpenRouter?: boolean;
+    /** @deprecated Use preferOpenRouter */
+    useOpenRouter?: boolean;
+}
 /**
- * Whether to prefer OpenRouter for vendor calls when an OpenRouter key is available.
+ * Read operator preference from env. Prefers PREFER_OPENROUTER; USE_OPENROUTER is legacy fallback.
+ * Default when both are unset: `true`.
+ */
+export declare function readPreferOpenRouterFromEnv(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the operator prefers OpenRouter for vendor calls (before key availability is applied).
  *
- * Default: `true` (route through OpenRouter even when direct provider keys exist).
- * Set `USE_OPENROUTER=false` to use direct providers when keys exist; OpenRouter remains
- * available as fallback for providers without a direct key.
+ * Default: `true`. Set `PREFER_OPENROUTER=false` to force vendor-direct when keys exist;
+ * OpenRouter remains available as fallback for providers without a direct key.
  */
-export declare function resolveUseOpenRouter(options?: ResolveUseOpenRouterOptions): boolean;
+export declare function resolvePreferOpenRouterPolicy(options?: ResolvePreferOpenRouterOptions): boolean;
+/** @deprecated Use resolvePreferOpenRouterPolicy */
+export declare function resolveUseOpenRouter(options?: ResolvePreferOpenRouterOptions): boolean;
 /** True when OpenRouter should be the primary transport (not merely fallback). */
-export declare function shouldPreferOpenRouter(config: {
-    useOpenRouter?: boolean;
-} | undefined, env?: NodeJS.ProcessEnv): boolean;
+export declare function shouldPreferOpenRouter(config: PreferOpenRouterConfig | undefined, env?: NodeJS.ProcessEnv): boolean;

package/dist/utils/openrouterEnv.js

@@ -16,31 +16,56 @@ export function hasOpenRouterApiKey() {
 }
 /** ERC placeholder resolution: prefer canonical name, fall back to legacy. */
 export const OPENROUTER_API_KEY_ERC = 'ENV.OPENROUTER_API_KEY||ENV.OPEN_ROUTER_KEY';
+function parsePreferOpenRouterEnvValue(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    if (raw === 'false')
+        return false;
+    if (raw === 'true')
+        return true;
+    return true;
+}
 /**
- * Whether to prefer OpenRouter for vendor calls when an OpenRouter key is available.
+ * Read operator preference from env. Prefers PREFER_OPENROUTER; USE_OPENROUTER is legacy fallback.
+ * Default when both are unset: `true`.
+ */
+export function readPreferOpenRouterFromEnv(env = process.env) {
+    const prefer = parsePreferOpenRouterEnvValue(env.PREFER_OPENROUTER);
+    if (prefer !== undefined)
+        return prefer;
+    const legacy = parsePreferOpenRouterEnvValue(env.USE_OPENROUTER);
+    if (legacy !== undefined)
+        return legacy;
+    return true;
+}
+function resolveConfigPreferOpenRouter(config) {
+    if (config?.preferOpenRouter !== undefined)
+        return config.preferOpenRouter;
+    if (config?.useOpenRouter !== undefined)
+        return config.useOpenRouter;
+    return undefined;
+}
+/**
+ * Whether the operator prefers OpenRouter for vendor calls (before key availability is applied).
  *
- * Default: `true` (route through OpenRouter even when direct provider keys exist).
- * Set `USE_OPENROUTER=false` to use direct providers when keys exist; OpenRouter remains
- * available as fallback for providers without a direct key.
+ * Default: `true`. Set `PREFER_OPENROUTER=false` to force vendor-direct when keys exist;
+ * OpenRouter remains available as fallback for providers without a direct key.
  */
-export function resolveUseOpenRouter(options = {}) {
+export function resolvePreferOpenRouterPolicy(options = {}) {
     const { userValue, env = process.env } = options;
     if (userValue === false)
         return false;
     if (userValue === true)
         return true;
-    const raw = env.USE_OPENROUTER;
-    if (raw === undefined || raw === '')
-        return true;
-    if (raw === 'false')
-        return false;
-    if (raw === 'true')
-        return true;
-    return true;
+    return readPreferOpenRouterFromEnv(env);
+}
+/** @deprecated Use resolvePreferOpenRouterPolicy */
+export function resolveUseOpenRouter(options = {}) {
+    return resolvePreferOpenRouterPolicy(options);
 }
 /** True when OpenRouter should be the primary transport (not merely fallback). */
 export function shouldPreferOpenRouter(config, env) {
     if (!hasOpenRouterApiKey())
         return false;
-    return resolveUseOpenRouter({ userValue: config?.useOpenRouter, env });
+    return resolvePreferOpenRouterPolicy({ userValue: resolveConfigPreferOpenRouter(config), env });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.8.12",
+  "version": "4.9.0",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
     "@x12i/ai-provider-grok": "^3.2.0",
     "@x12i/ai-provider-interface": "^3.2.1",
     "@x12i/ai-provider-openai": "^3.2.1",
-    "@x12i/logxer": "^4.5.1",
+    "@x12i/logxer": "^4.6.0",
     "ai-io-normalizer": "^6.0.3"
   },
   "devDependencies": {