@x12i/ai-gateway 9.6.9 → 9.7.0

package/dist/gateway-config.js

@@ -204,7 +204,7 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     // OpenRouter: always pass apiKey when set (fallback for providers without direct keys).
-    // USE_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
+    // PREFER_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
     const openRouterKey = resolveOpenRouterApiKey(config);
     const preferOpenRouter = resolvePreferOpenRouter(config);
     if (openRouterKey) {

package/dist/gateway-provider-auto-register.js

@@ -146,7 +146,7 @@ export async function autoRegisterProviders(router, logger) {
             optionalEnvVars: PROVIDER_CONFIGS
                 .filter(p => p.optional)
                 .map(p => p.envVar),
-            openRouter: 'Set OPENROUTER_API_KEY for OpenRouter (default route when set). USE_OPENROUTER=false prefers direct provider keys when present; OpenRouter is still used when a requested provider has no key.',
+            openRouter: 'Set OPENROUTER_API_KEY for OpenRouter (default route when set). PREFER_OPENROUTER=false prefers direct provider keys when present; OpenRouter is still used when a requested provider has no key.',
             note: 'You can still manually register providers using gateway.register(provider)'
         });
     }

package/dist/openrouter-routing.d.ts

@@ -5,8 +5,13 @@
 import type { GatewayConfig } from './types.js';
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export declare function readPreferOpenRouterFromEnv(): boolean | undefined;
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;

package/dist/openrouter-routing.js

@@ -11,17 +11,38 @@ export function resolveOpenRouterApiKey(config = {}) {
     return env || undefined;
 }
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export function readPreferOpenRouterFromEnv() {
+    const prefer = process.env.PREFER_OPENROUTER?.trim();
+    if (prefer === 'false' || prefer === '0')
+        return false;
+    if (prefer === 'true' || prefer === '1')
+        return true;
+    const legacy = process.env.USE_OPENROUTER?.trim();
+    if (legacy === 'false' || legacy === '0')
+        return false;
+    if (legacy === 'true' || legacy === '1')
+        return true;
+    return undefined;
+}
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export function resolvePreferOpenRouter(config = {}) {
+    if (config.openRouter?.prefer === true)
+        return true;
+    if (config.openRouter?.prefer === false)
+        return false;
     if (config.openRouter?.enabled === true)
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    const env = process.env.USE_OPENROUTER;
-    if (env === 'false' || env === '0')
-        return false;
-    return !!resolveOpenRouterApiKey(config);
+    const fromEnv = readPreferOpenRouterFromEnv();
+    if (fromEnv !== undefined)
+        return fromEnv;
+    return true;
 }

package/dist/types.d.ts

@@ -383,8 +383,8 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     };
     /**
      * OpenRouter preference (not a hard off-switch when {@link openrouter}.apiKey or OPENROUTER_API_KEY is set).
-     * - `enabled: true` or omitted with OPENROUTER_API_KEY: prefer OpenRouter even when direct provider keys exist.
-     * - `enabled: false` or USE_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
+     * - `prefer: true` / `enabled: true` or omitted env (default true): prefer OpenRouter when OPENROUTER_API_KEY is present.
+     * - `prefer: false` / `enabled: false` or PREFER_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
      */
     openRouter?: {
         enabled?: boolean;

package/dist-cjs/gateway-config.cjs

@@ -204,7 +204,7 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     // OpenRouter: always pass apiKey when set (fallback for providers without direct keys).
-    // USE_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
+    // PREFER_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
     const openRouterKey = resolveOpenRouterApiKey(config);
     const preferOpenRouter = resolvePreferOpenRouter(config);
     if (openRouterKey) {

package/dist-cjs/gateway-provider-auto-register.cjs

@@ -146,7 +146,7 @@ export async function autoRegisterProviders(router, logger) {
             optionalEnvVars: PROVIDER_CONFIGS
                 .filter(p => p.optional)
                 .map(p => p.envVar),
-            openRouter: 'Set OPENROUTER_API_KEY for OpenRouter (default route when set). USE_OPENROUTER=false prefers direct provider keys when present; OpenRouter is still used when a requested provider has no key.',
+            openRouter: 'Set OPENROUTER_API_KEY for OpenRouter (default route when set). PREFER_OPENROUTER=false prefers direct provider keys when present; OpenRouter is still used when a requested provider has no key.',
             note: 'You can still manually register providers using gateway.register(provider)'
         });
     }

package/dist-cjs/openrouter-routing.cjs

@@ -11,17 +11,38 @@ export function resolveOpenRouterApiKey(config = {}) {
     return env || undefined;
 }
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export function readPreferOpenRouterFromEnv() {
+    const prefer = process.env.PREFER_OPENROUTER?.trim();
+    if (prefer === 'false' || prefer === '0')
+        return false;
+    if (prefer === 'true' || prefer === '1')
+        return true;
+    const legacy = process.env.USE_OPENROUTER?.trim();
+    if (legacy === 'false' || legacy === '0')
+        return false;
+    if (legacy === 'true' || legacy === '1')
+        return true;
+    return undefined;
+}
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export function resolvePreferOpenRouter(config = {}) {
+    if (config.openRouter?.prefer === true)
+        return true;
+    if (config.openRouter?.prefer === false)
+        return false;
     if (config.openRouter?.enabled === true)
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    const env = process.env.USE_OPENROUTER;
-    if (env === 'false' || env === '0')
-        return false;
-    return !!resolveOpenRouterApiKey(config);
+    const fromEnv = readPreferOpenRouterFromEnv();
+    if (fromEnv !== undefined)
+        return fromEnv;
+    return true;
 }

package/dist-cjs/openrouter-routing.d.ts

@@ -5,8 +5,13 @@
 import type { GatewayConfig } from './types.js';
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export declare function readPreferOpenRouterFromEnv(): boolean | undefined;
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;

package/dist-cjs/types.d.ts

@@ -383,8 +383,8 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     };
     /**
      * OpenRouter preference (not a hard off-switch when {@link openrouter}.apiKey or OPENROUTER_API_KEY is set).
-     * - `enabled: true` or omitted with OPENROUTER_API_KEY: prefer OpenRouter even when direct provider keys exist.
-     * - `enabled: false` or USE_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
+     * - `prefer: true` / `enabled: true` or omitted env (default true): prefer OpenRouter when OPENROUTER_API_KEY is present.
+     * - `prefer: false` / `enabled: false` or PREFER_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
      */
     openRouter?: {
         enabled?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.6.9",
+  "version": "9.7.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -42,10 +42,10 @@
   "license": "mit",
   "dependencies": {
     "@x12i/activix": "^8.3.1",
-    "@x12i/ai-providers-router": "^4.8.12",
-    "@x12i/ai-tools": "^2.1.2",
+    "@x12i/ai-providers-router": "^4.9.0",
+    "@x12i/ai-tools": "^2.1.3",
     "@x12i/flex-md": "^4.8.0",
-    "@x12i/logxer": "^4.5.1",
+    "@x12i/logxer": "^4.6.0",
     "@x12i/optimixer": "^2.4.4",
     "@x12i/rendrix": "^4.3.0"
   },