@x12i/ai-providers-router 4.6.0

package/dist/router/Router.js

@@ -0,0 +1,258 @@
+import { newId } from '../utils/ids.js';
+/**
+ * Main router class
+ * Orchestrates provider execution using ProviderModules and router-side adapters
+ */
+export class AIRouter {
+    constructor(providers, adapters) {
+        this.providers = providers;
+        this.adapters = adapters;
+    }
+    /**
+     * Resolve provider name from request, checking OpenRouter mode first
+     */
+    resolveProviderName(input) {
+        const hasOpenRouterAdapter = this.adapters.has('openrouter');
+        const hasOpenRouterProvider = this.providers.has('openrouter');
+        // Check if OPEN_ROUTER_KEY is set in environment (completely automatic detection)
+        const hasOpenRouterKey = !!(process.env.OPEN_ROUTER_KEY &&
+            process.env.OPEN_ROUTER_KEY.trim() !== '' &&
+            !process.env.OPEN_ROUTER_KEY.startsWith('ENV.'));
+        // Normalize config.provider (handle string, trim whitespace)
+        const cfgProviderRaw = input.request?.config?.provider;
+        const cfgProvider = typeof cfgProviderRaw === 'string' ? cfgProviderRaw.trim() : undefined;
+        const hasProviderInConfig = !!cfgProvider && cfgProvider !== '';
+        const hasProviderAtTopLevel = input.provider === 'openrouter';
+        const hasRegisteredProviders = this.providers.list().length > 0;
+        // OpenRouter mode detection (COMPLETELY AUTOMATIC):
+        // 1. Explicit: top-level provider is 'openrouter'
+        // 2. OpenRouter provider is registered (when OPEN_ROUTER_KEY is set via factory)
+        // 3. AUTOMATIC: OpenRouter adapter exists + OPEN_ROUTER_KEY env var is set + config.provider is specified
+        //    This works even when router is created manually without calling createRouter()
+        // 4. Fallback: adapter exists + config.provider + no providers registered (auto-detect)
+        // 
+        // IMPORTANT: When OpenRouter provider is registered OR OPEN_ROUTER_KEY is set, OpenRouter mode is active.
+        // All provider names (openai, grok, anthropic, etc.) route through OpenRouter.
+        // The interceptor sets input.provider = 'openrouter' when OpenRouter mode is enabled.
+        const isOpenRouterMode = hasProviderAtTopLevel ||
+            hasOpenRouterProvider || // OpenRouter provider registered = OpenRouter mode is DEFAULT
+            (hasOpenRouterAdapter && hasOpenRouterKey && hasProviderInConfig) || // AUTOMATIC: env var + adapter + config.provider
+            (hasOpenRouterAdapter && hasProviderInConfig && !hasRegisteredProviders); // Fallback: adapter + config.provider + no providers
+        if (isOpenRouterMode) {
+            return 'openrouter';
+        }
+        // Honor request.config.provider in normal flow
+        if (hasProviderInConfig) {
+            // Validate provider is registered
+            if (!this.providers.has(cfgProvider)) {
+                const available = this.providers.list().join(', ');
+                // Check if OpenRouter mode could work automatically
+                if (hasOpenRouterAdapter && !hasOpenRouterKey) {
+                    throw new Error(`Provider '${cfgProvider}' specified in request.config.provider but not registered. ` +
+                        `OpenRouter adapter is available - set OPEN_ROUTER_KEY environment variable to enable automatic OpenRouter mode. ` +
+                        `Available providers: ${available || '(none)'}`);
+                }
+                throw new Error(`Provider '${cfgProvider}' specified in request.config.provider but not registered. Available providers: ${available || '(none)'}`);
+            }
+            // Validate adapter is registered
+            if (!this.adapters.has(cfgProvider)) {
+                const available = this.adapters.list().join(', ');
+                throw new Error(`Adapter '${cfgProvider}' specified in request.config.provider but not registered. Available adapters: ${available || '(none)'}`);
+            }
+            return cfgProvider;
+        }
+        // Existing fallback: top-level provider or first registered provider
+        const providerName = input.provider ?? this.providers.list()[0];
+        if (!providerName) {
+            // Improved error messages with OpenRouter mode guidance
+            if (hasProviderInConfig && hasOpenRouterAdapter && !hasRegisteredProviders) {
+                if (!hasOpenRouterKey) {
+                    throw new Error('OpenRouter adapter available and config.provider specified, but OpenRouter provider module not registered. ' +
+                        'Set OPEN_ROUTER_KEY environment variable to enable automatic OpenRouter mode (works with both createRouter() and manual initialization).');
+                }
+                throw new Error('OpenRouter adapter available and config.provider specified, but OpenRouter provider module not registered. ' +
+                    'OPEN_ROUTER_KEY is set but provider module initialization failed. Check that @x12i/ai-provider-openai is installed.');
+            }
+            if (hasProviderInConfig && !hasOpenRouterAdapter) {
+                throw new Error(`Provider '${input.request?.config?.provider}' specified in config but no providers registered and OpenRouter adapter not available.`);
+            }
+            // Final fallback error with OpenRouter suggestion
+            if (hasOpenRouterAdapter && !hasOpenRouterKey) {
+                throw new Error('No provider specified and no providers registered. ' +
+                    'OpenRouter adapter is available - set OPEN_ROUTER_KEY environment variable to enable automatic OpenRouter mode.');
+            }
+            throw new Error('No provider specified and no providers registered');
+        }
+        return providerName;
+    }
+    /**
+     * Execute a sync request
+     */
+    async runSync(input) {
+        const requestId = input.requestId ?? newId();
+        const providerName = this.resolveProviderName(input);
+        const provider = this.providers.get(providerName);
+        const adapter = this.adapters.get(providerName);
+        // Check capabilities
+        if (!provider.capabilities.modes.sync) {
+            throw new Error(`Provider '${providerName}' does not support sync mode`);
+        }
+        // Build call spec
+        const spec = await adapter.buildCallSpec({
+            requestId,
+            mode: 'sync',
+            request: input.request,
+            exec: input.exec,
+        });
+        // Execute
+        const execResult = await provider.execute(spec);
+        // Parse response
+        return adapter.parseResponse({
+            requestId,
+            request: { ...input.request, _callSpec: spec }, // Include call spec for adapter access
+            execResult,
+        });
+    }
+    /**
+     * Execute a streaming request
+     */
+    async *runStream(input) {
+        const requestId = input.requestId ?? newId();
+        const providerName = this.resolveProviderName(input);
+        const provider = this.providers.get(providerName);
+        const adapter = this.adapters.get(providerName);
+        // Check capabilities
+        if (!provider.capabilities.modes.stream) {
+            throw new Error(`Provider '${providerName}' does not support stream mode`);
+        }
+        if (!provider.stream) {
+            throw new Error(`Provider '${providerName}' does not implement stream()`);
+        }
+        if (!adapter.parseStreamChunk || !adapter.finalizeStream) {
+            throw new Error(`Adapter for '${providerName}' does not support streaming`);
+        }
+        // Build call spec
+        const spec = await adapter.buildCallSpec({
+            requestId,
+            mode: 'stream',
+            request: input.request,
+            exec: input.exec,
+        });
+        // Collect stream data
+        const collected = {
+            rawEvents: [],
+            outputText: '',
+        };
+        try {
+            // Stream chunks
+            for await (const chunk of provider.stream(spec)) {
+                collected.rawEvents.push(chunk.raw);
+                // Emit provider_raw event
+                yield {
+                    type: 'provider_raw',
+                    requestId,
+                    provider: providerName,
+                    raw: chunk.raw,
+                };
+                // Parse chunk to router events
+                const events = adapter.parseStreamChunk({
+                    requestId,
+                    request: input.request,
+                    chunk,
+                });
+                for (const ev of events) {
+                    // Accumulate output text
+                    if (ev.type === 'output_text_delta') {
+                        collected.outputText += ev.delta;
+                    }
+                    yield ev;
+                }
+            }
+            // Finalize stream
+            const response = adapter.finalizeStream({
+                requestId,
+                request: input.request,
+                collected,
+            });
+            yield {
+                type: 'completed',
+                requestId,
+                response,
+            };
+        }
+        catch (error) {
+            yield {
+                type: 'error',
+                requestId,
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+            throw error;
+        }
+    }
+    /**
+     * Execute a batch request
+     */
+    async runBatch(providerName, items, exec) {
+        const provider = this.providers.get(providerName);
+        const adapter = this.adapters.get(providerName);
+        // Check capabilities
+        if (!provider.capabilities.modes.batch) {
+            throw new Error(`Provider '${providerName}' does not support batch mode`);
+        }
+        if (!provider.submitBatch || !provider.getBatchStatus || !provider.fetchBatchResults) {
+            throw new Error(`Provider '${providerName}' does not implement batch methods`);
+        }
+        if (!adapter.parseBatchItem) {
+            throw new Error(`Adapter for '${providerName}' does not support batch parsing`);
+        }
+        // Ensure exec.timeoutMs is always set (router owns execution semantics)
+        const execWithTimeout = {
+            timeoutMs: exec?.timeoutMs ?? 60000,
+            retries: exec?.retries,
+        };
+        // Fix: Persist requestIds for items that don't have them, so we can map results back correctly
+        const itemsWithIds = items.map((it) => ({
+            ...it,
+            requestId: it.requestId ?? newId(),
+        }));
+        // Build call specs for each item using persisted requestIds
+        const specs = await Promise.all(itemsWithIds.map((it) => adapter.buildCallSpec({
+            requestId: it.requestId,
+            mode: 'sync', // Batch items are sync specs
+            request: it.request,
+            exec: execWithTimeout,
+        })));
+        // Submit batch
+        const handle = await provider.submitBatch(specs);
+        // Poll until complete
+        while (true) {
+            const status = await provider.getBatchStatus(handle);
+            if (status.state === 'completed') {
+                break;
+            }
+            if (status.state === 'failed' || status.state === 'canceled') {
+                throw new Error(`Batch ended with state: ${status.state}`);
+            }
+            // Wait before polling again
+            await new Promise((r) => setTimeout(r, 2000));
+        }
+        // Fetch results
+        const batchResults = await provider.fetchBatchResults(handle);
+        // Fix: Use Map for efficient lookup by requestId
+        const originalById = new Map(itemsWithIds.map((it) => [it.requestId, it]));
+        // Parse each item using the Map for correct correlation
+        const parsedItems = batchResults.items.map((item) => {
+            const originalItem = originalById.get(item.requestId);
+            return adapter.parseBatchItem({
+                requestId: item.requestId,
+                request: originalItem?.request || {},
+                item,
+            });
+        });
+        return {
+            provider: providerName,
+            rawBatch: batchResults.rawResponse,
+            items: parsedItems,
+        };
+    }
+}

package/dist/router/RouterTypes.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Router-level request and response types
+ * These are the public API of the router
+ */
+export type RouterMode = 'sync' | 'stream' | 'batch';
+/**
+ * Router configuration
+ */
+export interface RouterConfig {
+    usageTracker?: {
+        recordRequest(event: {
+            provider: string;
+            timestamp: number;
+            duration: number;
+            tokens: {
+                input: number;
+                output: number;
+                total: number;
+            };
+            cost?: number;
+            success: boolean;
+        }): void;
+    };
+    verbose?: boolean;
+    logLevel?: 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+    logger?: any;
+    timeoutMs?: number;
+    defaultTimeoutMs?: number;
+    /** OpenRouter provider config (e.g. from gateway); used when env OPEN_ROUTER_KEY is not visible */
+    openrouter?: {
+        apiKey?: string;
+        httpReferer?: string;
+        xTitle?: string;
+    };
+}
+/**
+ * Router request - the input to the router
+ */
+export interface AIRouterRequest {
+    requestId?: string;
+    request: any;
+    provider?: string;
+    mode: RouterMode;
+    exec?: {
+        timeoutMs?: number;
+        retries?: number;
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    };
+}
+/**
+ * Router response for sync mode
+ */
+export interface AIResponse {
+    requestId: string;
+    provider: string;
+    rawResponse: unknown;
+    outputText?: string;
+    usage?: any;
+    reasoning: {
+        requested: {
+            effort: string;
+            visibility: string;
+        };
+        applied: {
+            effort: string;
+            visibility: string;
+        };
+        artifacts: {
+            encrypted?: any[];
+            summary?: {
+                text: string;
+                format: string;
+            };
+            trace?: {
+                text: string;
+                format: string;
+            };
+        };
+        availability: {
+            supportsEffort: boolean;
+            supportsSummary: boolean;
+            supportsTrace: boolean;
+            supportsEncrypted: boolean;
+        };
+        warnings?: any[];
+    };
+    metadata?: any;
+}
+/**
+ * Router stream events
+ */
+export type AIStreamEvent = {
+    type: 'provider_raw';
+    requestId: string;
+    provider: string;
+    raw: unknown;
+} | {
+    type: 'output_text_delta';
+    requestId: string;
+    delta: string;
+} | {
+    type: 'reasoning_summary_delta';
+    requestId: string;
+    delta: string;
+} | {
+    type: 'reasoning_trace_delta';
+    requestId: string;
+    delta: string;
+} | {
+    type: 'completed';
+    requestId: string;
+    response: AIResponse;
+} | {
+    type: 'error';
+    requestId: string;
+    error: any;
+};
+/**
+ * Batch request item
+ */
+export interface AIBatchRequestItem {
+    requestId?: string;
+    request: any;
+}
+/**
+ * Batch response
+ */
+export interface AIBatchResponse {
+    provider: string;
+    items: Array<{
+        requestId: string;
+        rawResponse?: unknown;
+        outputText?: string;
+        error?: any;
+    }>;
+    rawBatch?: unknown;
+}

package/dist/router/RouterTypes.js

@@ -0,0 +1,5 @@
+/**
+ * Router-level request and response types
+ * These are the public API of the router
+ */
+export {};

package/dist/router/RouterWrapper.d.ts

@@ -0,0 +1,83 @@
+import { ProviderRegistry } from '../registry/ProviderRegistry.js';
+import { AdapterRegistry } from '../registry/AdapterRegistry.js';
+import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem } from './RouterTypes.js';
+import type { RouterConfig } from './RouterTypes.js';
+import type { RequestInterceptor, ResponseInterceptor } from '../interceptors.js';
+/**
+ * Wrapper around AIRouter that adds logging, interceptors, and usage tracking
+ * Maintains backward compatibility with existing router API
+ */
+export declare class LLMProviderRouter {
+    private router;
+    private providerRegistry;
+    private adapterRegistry;
+    private config;
+    private requestInterceptors;
+    private responseInterceptors;
+    private logger;
+    private providerConfigs;
+    private lastConfiguredProvider;
+    private autoRegistrationAttempted;
+    constructor(config?: RouterConfig);
+    /**
+     * Register a provider module
+     */
+    registerProvider(providerModuleOrFactory: any, factoryName?: string): void;
+    /**
+     * Configure provider SDK client config
+     */
+    configureProvider(providerName: string, config: any): void;
+    /**
+     * Add request interceptor
+     */
+    addRequestInterceptor(interceptor: RequestInterceptor): void;
+    /**
+     * Add response interceptor
+     */
+    addResponseInterceptor(interceptor: ResponseInterceptor): void;
+    /**
+     * Invoke router (sync mode)
+     */
+    invoke(request: AIRouterRequest): Promise<AIResponse>;
+    /**
+     * Stream request
+     */
+    stream(request: AIRouterRequest): AsyncIterable<AIStreamEvent>;
+    /**
+     * Batch request
+     */
+    createBatch(providerName: string, items: AIBatchRequestItem[], exec?: {
+        timeoutMs?: number;
+        retries?: number;
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<AIBatchResponse>;
+    /**
+     * List registered providers
+     */
+    listProviders(): string[];
+    /**
+     * Check health of a specific provider
+     */
+    checkHealth(provider: string): Promise<import('../router.js').HealthCheckResult>;
+    /**
+     * Get provider registry (for advanced usage)
+     */
+    getProviderRegistry(): ProviderRegistry;
+    /**
+     * Get adapter registry (for advanced usage)
+     */
+    getAdapterRegistry(): AdapterRegistry;
+    /**
+     * Try to register OpenRouter if a key is available (constructor config or resolved env).
+     * Used by ensureProvidersRegistered() and by the OpenRouter retry path when the first run skipped registration.
+     */
+    private tryRegisterOpenRouter;
+    /**
+     * Automatically detect and register providers based on environment variables
+     * This ensures "Zero-Config" initialization works even if createRouter() isn't used.
+     * When the first run did not register OpenRouter (e.g. key was missing), a later invoke
+     * can still register it by retrying OpenRouter-only registration when the key is now available.
+     */
+    private ensureProvidersRegistered;
+}