@x12i/ai-providers-router 4.6.0

package/dist/gateway.js

@@ -0,0 +1,154 @@
+import { LLMProviderRouter } from './router/RouterWrapper.js';
+export class AIGateway {
+    constructor(router) {
+        this.router = router || new LLMProviderRouter();
+    }
+    async invoke(request) {
+        // Accept router-wrapper requests too (provider/mode/request), and unwrap them
+        // so gateway doesn't treat them as an instruction object and run the instruction pipeline.
+        if (request && typeof request === 'object' && request.request && request.provider && request.mode) {
+            const inner = request.request;
+            request = {
+                ...inner,
+                // preserve provider/mode semantics in the gateway config
+                config: {
+                    ...(inner.config || {}),
+                    provider: (inner.config && inner.config.provider) || request.provider,
+                },
+                // optional: keep mode for downstream if you use it
+                mode: request.mode,
+            };
+        }
+        this.validateRequest(request);
+        const requestedProvider = request?.config?.provider;
+        const requestedModel = request?.config?.model;
+        const response = await this.invokeInternal(request);
+        // Optional: Diagnostic warning for JSON-looking prompts (doesn't block, just warns)
+        const outboundPrompt = this.extractOutboundPrompt(request);
+        if (outboundPrompt && this.looksLikeConfigJSON(outboundPrompt)) {
+            console.warn(`[WARNING] Outbound prompt appears to be JSON config data instead of user instructions. ` +
+                `This may indicate config data reached the AI model. Prompt preview: ${outboundPrompt.substring(0, 100)}...`);
+        }
+        // Enforce provider/model pinning when explicitly requested.
+        // Default behavior: warn only. Enable strict pinning via config flag.
+        const enforcePinning = request?.config?.enforceProviderModel === true;
+        const actualProvider = response?.content?.providerMetadata?.provider ||
+            response?.provider ||
+            response?.metadata?.provider;
+        const actualModel = response?.content?.providerMetadata?.model ||
+            response?.model ||
+            response?.metadata?.model;
+        if (enforcePinning && (requestedProvider || requestedModel)) {
+            if (requestedProvider && actualProvider && requestedProvider !== actualProvider) {
+                throw new Error(`Provider mismatch: requested '${requestedProvider}' but executed '${actualProvider}'. Refusing silent provider switching.`);
+            }
+            if (requestedModel && actualModel && requestedModel !== actualModel) {
+                throw new Error(`Model mismatch: requested '${requestedModel}' but executed '${actualModel}'. Refusing silent model fallback.`);
+            }
+        }
+        return response;
+    }
+    async invokeInternal(request) {
+        // Convert the request to router format and invoke
+        const routerRequest = {
+            provider: request.config?.provider || 'openai',
+            mode: request.mode || 'sync',
+            request: {
+                instructions: request.instructions || '',
+                inputData: request.inputData || '',
+                config: request.config || {},
+            },
+            exec: request.exec || {},
+        };
+        return await this.router.invoke(routerRequest);
+    }
+    validateRequest(request) {
+        if (!request) {
+            throw new Error('Request is required');
+        }
+        // 🚨 CRITICAL VALIDATION: Prevent config data from being sent as instructions
+        // This happens when adapters fall back to JSON.stringify(request) and send config to AI model
+        // Validate instruction content types
+        if (request.instructions !== undefined && typeof request.instructions !== 'string') {
+            throw new Error(`CRITICAL: instructions must be a string, got ${typeof request.instructions}. ` +
+                'Non-string instructions can cause adapters to stringify the entire request object.');
+        }
+        if (request.inputData !== undefined) {
+            if (typeof request.inputData !== 'string' && typeof request.inputData !== 'object') {
+                throw new Error(`CRITICAL: inputData must be a string or object, got ${typeof request.inputData}. ` +
+                    'Invalid inputData types can cause adapters to stringify the entire request object.');
+            }
+        }
+        // Validate messages structure
+        if (request.messages !== undefined) {
+            if (!Array.isArray(request.messages)) {
+                throw new Error(`CRITICAL: messages must be an array, got ${typeof request.messages}. ` +
+                    'Invalid messages structure can cause adapters to stringify the entire request object.');
+            }
+            for (let i = 0; i < request.messages.length; i++) {
+                const msg = request.messages[i];
+                if (!msg || typeof msg !== 'object') {
+                    throw new Error(`CRITICAL: messages[${i}] must be an object, got ${typeof msg}. ` +
+                        'Invalid message structure can cause adapters to stringify the entire request object.');
+                }
+                if (msg.content !== undefined && typeof msg.content !== 'string') {
+                    throw new Error(`CRITICAL: messages[${i}].content must be a string, got ${typeof msg.content}. ` +
+                        'Non-string message content can cause adapters to stringify the entire request object.');
+                }
+            }
+        }
+        // Require at least one valid instruction source
+        const hasValidInstructions = request.instructions && typeof request.instructions === 'string' && request.instructions.trim().length > 0;
+        const hasValidInputData = request.inputData && ((typeof request.inputData === 'string' && request.inputData.trim().length > 0) ||
+            (typeof request.inputData === 'object' && Object.keys(request.inputData).length > 0));
+        const hasValidUserMessage = request.messages && Array.isArray(request.messages) &&
+            request.messages.some((msg) => msg.role === 'user' && msg.content && typeof msg.content === 'string' && msg.content.trim().length > 0);
+        if (!hasValidInstructions && !hasValidInputData && !hasValidUserMessage) {
+            throw new Error('CRITICAL: Request must have at least one valid instruction source. ' +
+                'Provide either: non-empty string instructions, valid inputData, or at least one user message with string content. ' +
+                'Missing/empty instruction content causes adapters to fall back to JSON.stringify(request), ' +
+                'which sends configuration data to the AI model instead of proper instructions.');
+        }
+    }
+    extractOutboundPrompt(request) {
+        // Extract what will actually be sent to the AI model as the prompt/instructions
+        // Check inputData (most common)
+        if (request.inputData && typeof request.inputData === 'string' && request.inputData.trim()) {
+            return request.inputData.trim();
+        }
+        // Check instructions
+        if (request.instructions && typeof request.instructions === 'string' && request.instructions.trim()) {
+            return request.instructions.trim();
+        }
+        // Check messages
+        if (request.messages && Array.isArray(request.messages)) {
+            for (const msg of request.messages) {
+                if (msg.role === 'user' && msg.content && typeof msg.content === 'string' && msg.content.trim()) {
+                    return msg.content.trim();
+                }
+            }
+        }
+        return null;
+    }
+    looksLikeConfigJSON(text) {
+        if (!text || typeof text !== 'string')
+            return false;
+        const trimmed = text.trim();
+        if (!trimmed.startsWith('{'))
+            return false;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed !== 'object' || !parsed)
+                return false;
+            // Look for config-like patterns
+            const keys = Object.keys(parsed);
+            const configIndicators = ['config', 'provider', 'model', 'apiKey', 'maxTokens', 'temperature'];
+            // If it has multiple config keys, it's likely config JSON
+            const configKeyCount = keys.filter(key => configIndicators.includes(key)).length;
+            return configKeyCount >= 2;
+        }
+        catch {
+            return false; // Not valid JSON
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { LLMProviderRouter } from './router.js';
+export type { RouterConfig, HealthCheckResult, ProviderId, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, } from './router.js';
+export { createRouter, createRouterFromConfig } from './factory.js';
+export type { CreateRouterConfig } from './factory.js';
+export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError } from './errors.js';
+export type { RequestInterceptor, ResponseInterceptor } from './interceptors.js';
+export type { UsageTracker, AdapterLoader, ProviderInit } from './types.js';
+export { Logger, getLogger, createLogger } from './logger.js';
+export type { LogLevel, LoggerConfig } from './logger.js';

package/dist/index.js

@@ -0,0 +1,42 @@
+// 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
+// Must be set before any network calls are made
+import dns from 'node:dns';
+dns.setDefaultResultOrder('ipv4first');
+// Main exports
+export { LLMProviderRouter } from './router.js';
+// Provider/model enums and helpers
+/*
+export {
+  AIProvider,
+  NxAiProvider,
+  OpenAIModel,
+  GroqModel,
+  AnthropicModel,
+  GoogleModel,
+  GoogleEmbeddingModel,
+  MistralModel,
+  CohereModel,
+  CohereEmbeddingModel,
+  MetaModel,
+  DeepSeekModel,
+  XAIModel,
+  AmazonModel,
+  QwenModel,
+  PerplexityModel,
+  VoyageModel,
+  TogetherModel,
+  FireworksModel,
+  OllamaModel,
+  listModelsByProvider,
+  isValidModelForProvider,
+  mapProviderNameToEnum,
+} from './models.js';
+*/
+//export type { ProviderModelRef } from './models.js';
+// Factory functions
+export { createRouter, createRouterFromConfig } from './factory.js';
+// Error classes
+export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError } from './errors.js';
+// Logger
+export { Logger, getLogger, createLogger } from './logger.js';

package/dist/interceptors.d.ts

@@ -0,0 +1,10 @@
+import type { AIRouterRequest, AIResponse } from './router/RouterTypes.js';
+import type { ProviderId } from './types.js';
+/**
+ * Interceptor function that can modify requests before they are sent
+ */
+export type RequestInterceptor = (request: AIRouterRequest, provider?: ProviderId) => AIRouterRequest | Promise<AIRouterRequest>;
+/**
+ * Interceptor function that can modify responses after they are received
+ */
+export type ResponseInterceptor = (response: AIResponse, provider: ProviderId) => AIResponse | Promise<AIResponse>;

package/dist/interceptors.js

@@ -0,0 +1 @@
+export {};

package/dist/logger.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Logging utility for AI Provider Router
+ * Provides structured logging with proper log levels and verbose mode support
+ */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+export interface LoggerConfig {
+    verbose?: boolean;
+    level?: LogLevel;
+}
+/**
+ * Logger class that wraps logxer with proper log levels
+ */
+export declare class Logger {
+    verbose: boolean;
+    level: LogLevel;
+    private gateway;
+    constructor(config?: LoggerConfig);
+    /**
+     * Update logger configuration
+     */
+    setConfig(config: LoggerConfig): void;
+    /**
+     * Check if a log level should be logged
+     */
+    private shouldLog;
+    /**
+     * Log error messages
+     */
+    error(message: string, data?: any): void;
+    /**
+     * Log warning messages
+     */
+    warn(message: string, data?: any): void;
+    /**
+     * Log informational messages
+     */
+    info(message: string, data?: any): void;
+    /**
+     * Log debug messages
+     */
+    debug(message: string, data?: any): void;
+    /**
+     * Log verbose messages (only when verbose mode is enabled)
+     */
+    logVerbose(message: string, data?: any): void;
+    /**
+     * Log AI request (unfiltered, only in verbose mode)
+     */
+    logAIRequest(provider: string, request: any, metadata?: any): void;
+    /**
+     * Log AI response (unfiltered, only in verbose mode)
+     */
+    logAIResponse(provider: string, response: any, metadata?: any): void;
+    /**
+     * Log AI request/response pair (unfiltered, only in verbose mode)
+     */
+    logAIIteraction(provider: string, request: any, response: any, duration?: number, metadata?: any): void;
+    /**
+     * Sanitize data for logging (remove sensitive info, handle circular refs)
+     */
+    sanitizeForLogging(data: any): any;
+}
+/**
+ * Get or create the default logger instance
+ */
+export declare function getLogger(config?: LoggerConfig): Logger;
+/**
+ * Create a new logger instance
+ */
+export declare function createLogger(config?: LoggerConfig): Logger;

package/dist/logger.js

@@ -0,0 +1,222 @@
+/**
+ * Logging utility for AI Provider Router
+ * Provides structured logging with proper log levels and verbose mode support
+ */
+import logxer from '@x12i/logxer';
+const logs = logxer || console;
+/**
+ * Logger class that wraps logxer with proper log levels
+ */
+export class Logger {
+    constructor(config = {}) {
+        this.verbose = config.verbose || false;
+        this.level = config.level || 'info';
+        this.gateway = logs || console;
+    }
+    /**
+     * Update logger configuration
+     */
+    setConfig(config) {
+        if (config.verbose !== undefined) {
+            this.verbose = config.verbose;
+        }
+        if (config.level !== undefined) {
+            this.level = config.level;
+        }
+    }
+    /**
+     * Check if a log level should be logged
+     */
+    shouldLog(level) {
+        const levels = ['error', 'warn', 'info', 'debug', 'verbose'];
+        const currentIndex = levels.indexOf(this.level);
+        const messageIndex = levels.indexOf(level);
+        return messageIndex <= currentIndex;
+    }
+    /**
+     * Log error messages
+     */
+    error(message, data) {
+        if (!this.shouldLog('error'))
+            return;
+        if (this.gateway?.error) {
+            this.gateway.error(message, data || {});
+        }
+        else {
+            console.error(`[ERROR] ${message}`, data || '');
+        }
+    }
+    /**
+     * Log warning messages
+     */
+    warn(message, data) {
+        if (!this.shouldLog('warn'))
+            return;
+        if (this.gateway?.warn) {
+            this.gateway.warn(message, data || {});
+        }
+        else {
+            console.warn(`[WARN] ${message}`, data || '');
+        }
+    }
+    /**
+     * Log informational messages
+     */
+    info(message, data) {
+        if (!this.shouldLog('info'))
+            return;
+        if (this.gateway?.info) {
+            this.gateway.info(message, data || {});
+        }
+        else {
+            console.log(`[INFO] ${message}`, data || '');
+        }
+    }
+    /**
+     * Log debug messages
+     */
+    debug(message, data) {
+        if (!this.shouldLog('debug'))
+            return;
+        if (this.gateway?.debug) {
+            this.gateway.debug(message, data || {});
+        }
+        else {
+            console.debug(`[DEBUG] ${message}`, data || '');
+        }
+    }
+    /**
+     * Log verbose messages (only when verbose mode is enabled)
+     */
+    logVerbose(message, data) {
+        if (!this.verbose || !this.shouldLog('verbose'))
+            return;
+        if (this.gateway?.verbose) {
+            this.gateway.verbose(message, data || {});
+        }
+        else if (this.gateway?.trace) {
+            this.gateway.trace(message, data || {});
+        }
+        else {
+            console.log(`[VERBOSE] ${message}`, data || '');
+        }
+    }
+    /**
+     * Log AI request (unfiltered, only in verbose mode)
+     */
+    logAIRequest(provider, request, metadata) {
+        if (!this.verbose)
+            return;
+        this.logVerbose('AI Request Sent', {
+            provider,
+            request: this.sanitizeForLogging(request),
+            metadata: metadata || {},
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Log AI response (unfiltered, only in verbose mode)
+     */
+    logAIResponse(provider, response, metadata) {
+        if (!this.verbose)
+            return;
+        this.logVerbose('AI Response Received', {
+            provider,
+            response: this.sanitizeForLogging(response),
+            metadata: metadata || {},
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Log AI request/response pair (unfiltered, only in verbose mode)
+     */
+    logAIIteraction(provider, request, response, duration, metadata) {
+        if (!this.verbose)
+            return;
+        this.logVerbose('AI Interaction Complete', {
+            provider,
+            request: this.sanitizeForLogging(request),
+            response: this.sanitizeForLogging(response),
+            duration: duration ? `${duration}ms` : undefined,
+            metadata: metadata || {},
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Sanitize data for logging (remove sensitive info, handle circular refs)
+     */
+    sanitizeForLogging(data) {
+        if (data === null || data === undefined) {
+            return data;
+        }
+        // Handle circular references and large objects
+        const seen = new WeakSet();
+        const sanitize = (obj, depth = 0) => {
+            // Prevent infinite recursion
+            if (depth > 10) {
+                return '[Max Depth Reached]';
+            }
+            // Handle primitives
+            if (obj === null || obj === undefined) {
+                return obj;
+            }
+            if (typeof obj === 'string' || typeof obj === 'number' || typeof obj === 'boolean') {
+                return obj;
+            }
+            // Handle circular references
+            if (typeof obj === 'object') {
+                if (seen.has(obj)) {
+                    return '[Circular Reference]';
+                }
+                seen.add(obj);
+                // Handle arrays
+                if (Array.isArray(obj)) {
+                    return obj.map((item) => sanitize(item, depth + 1));
+                }
+                // Handle Buffer (common in file uploads)
+                if (Buffer.isBuffer(obj)) {
+                    return `[Buffer: ${obj.length} bytes]`;
+                }
+                // Handle objects
+                const result = {};
+                for (const key in obj) {
+                    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                        // Skip sensitive keys (can be extended)
+                        if (key.toLowerCase().includes('password') ||
+                            key.toLowerCase().includes('secret') ||
+                            key.toLowerCase().includes('apikey') ||
+                            key.toLowerCase().includes('token') && key !== 'token') {
+                            result[key] = '[REDACTED]';
+                        }
+                        else {
+                            result[key] = sanitize(obj[key], depth + 1);
+                        }
+                    }
+                }
+                return result;
+            }
+            return String(obj);
+        };
+        return sanitize(data);
+    }
+}
+// Default logger instance
+let defaultLogger = null;
+/**
+ * Get or create the default logger instance
+ */
+export function getLogger(config) {
+    if (!defaultLogger) {
+        defaultLogger = new Logger(config);
+    }
+    else if (config) {
+        defaultLogger.setConfig(config);
+    }
+    return defaultLogger;
+}
+/**
+ * Create a new logger instance
+ */
+export function createLogger(config = {}) {
+    return new Logger(config);
+}

package/dist/openrouter-catalog.d.ts

@@ -0,0 +1,119 @@
+export interface OpenRouterProvider {
+    slug: string;
+    name: string;
+}
+export interface OpenRouterModelVendor {
+    author: string;
+    direct: {
+        vendorId: string;
+        apiStyle: string;
+        baseUrlHint?: string | null;
+        modelId: string;
+        confidence: string;
+        notes: string;
+    };
+}
+export interface OpenRouterModel {
+    openrouterId: string;
+    canonicalSlug: string;
+    displayName: string;
+    vendor: OpenRouterModelVendor;
+    aliases: string[];
+    fallbackOf: string[];
+    capabilities: {
+        contextLength: number;
+        supportedParameters: string[];
+    };
+}
+export interface OpenRouterCatalog {
+    schemaVersion: string;
+    source: {
+        providersEndpoint: string;
+        modelsEndpoint: string;
+        retrievedAt: string;
+        counts: {
+            providers: number;
+            models: number;
+        };
+    };
+    providers: OpenRouterProvider[];
+    models: OpenRouterModel[];
+}
+/**
+ * OpenRouter Catalog Loader
+ * Loads and caches the OpenRouter catalog data from JSON file
+ */
+export declare class OpenRouterCatalogLoader {
+    private static instance;
+    private catalog;
+    private catalogPath;
+    private constructor();
+    static getInstance(): OpenRouterCatalogLoader;
+    /**
+     * Load the catalog from the JSON file
+     */
+    load(): Promise<OpenRouterCatalog>;
+    /**
+     * Get the loaded catalog (throws if not loaded)
+     */
+    getCatalog(): OpenRouterCatalog;
+    /**
+     * Get all providers
+     */
+    getProviders(): Promise<OpenRouterProvider[]>;
+    /**
+     * Get all models
+     */
+    getModels(): Promise<OpenRouterModel[]>;
+    /**
+     * Find a model by OpenRouter ID
+     */
+    findModelById(openrouterId: string): Promise<OpenRouterModel | null>;
+    /**
+     * Find models by canonical slug
+     */
+    findModelByCanonicalSlug(canonicalSlug: string): Promise<OpenRouterModel | null>;
+    /**
+     * Find models by aliases (returns all matches)
+     */
+    findModelsByAlias(alias: string): Promise<OpenRouterModel[]>;
+    /**
+     * Find provider by slug
+     */
+    findProviderBySlug(slug: string): Promise<OpenRouterProvider | null>;
+    /**
+     * Get all provider slugs
+     */
+    getProviderSlugs(): Promise<string[]>;
+    /**
+     * Find provider by vendor ID (from model.vendor.direct.vendorId)
+     * This maps vendor IDs to provider slugs for alias support
+     */
+    findProviderByVendorId(vendorId: string): Promise<OpenRouterProvider | null>;
+    /**
+     * Get all vendor IDs that map to providers
+     */
+    getAllVendorIds(): Promise<string[]>;
+    /**
+     * Check if a model is available
+     */
+    isModelAvailable(modelId: string): Promise<boolean>;
+    /**
+     * Get model capabilities
+     */
+    getModelCapabilities(modelId: string): Promise<OpenRouterModel['capabilities'] | null>;
+    /**
+     * Validate model supports a specific parameter
+     */
+    modelSupportsParameter(modelId: string, parameter: string): Promise<boolean>;
+    /**
+     * Infer provider from model name using catalog data
+     */
+    inferProviderFromModel(modelName: string): Promise<string | null>;
+    /**
+     * Normalize model name to OpenRouter format
+     * Returns the canonical OpenRouter ID for the model
+     */
+    normalizeModelName(modelName: string, providerHint?: string): Promise<string>;
+}
+export declare const openRouterCatalog: OpenRouterCatalogLoader;