@x12i/ai-gateway 11.0.7 → 11.1.0

package/dist-cjs/router-errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Router error types and enrichment helpers for gateway consumers.
+ */
+export declare const PROVIDER_FAILURE_CODES: readonly ["OPENROUTER_API_KEY_MISSING", "PROVIDER_AUTH_FAILED", "PROVIDER_RATE_LIMITED", "PROVIDER_QUOTA_EXCEEDED", "PROVIDER_MODEL_NOT_FOUND", "PROVIDER_GATEWAY_UNREACHABLE", "PROVIDER_NOT_REGISTERED", "PROVIDER_REQUEST_FAILED", "PROVIDER_INVOKE_FAILED"];
+export type ProviderFailureCode = (typeof PROVIDER_FAILURE_CODES)[number];
+export type ProviderAttemptDetail = {
+    provider: string;
+    modelId?: string;
+    httpStatus?: number;
+    message: string;
+    code: ProviderFailureCode;
+    retryable?: boolean;
+};
+export declare function operatorHintForProviderFailureCode(code: ProviderFailureCode): string;
+export type FallbackAttempt = {
+    provider: string;
+    model?: string;
+    httpStatus?: number;
+    code?: ProviderFailureCode;
+    message?: string;
+    error: Error;
+    responsePreview?: string;
+};
+export declare class ProviderNotFoundError extends Error {
+    constructor(providerName: string);
+}
+export declare class OpenRouterApiKeyMissingError extends Error {
+    readonly code: "OPENROUTER_API_KEY_MISSING";
+    constructor();
+}
+export declare class FallbackExhaustedError extends Error {
+    attempts: FallbackAttempt[];
+    code?: ProviderFailureCode;
+    operatorHint?: string;
+    details?: {
+        providerAttempts: ProviderAttemptDetail[];
+    };
+    constructor(attempts: FallbackAttempt[]);
+}
+export declare function buildProviderAttemptDetail(input: {
+    provider: string;
+    modelId?: string;
+    httpStatus?: number;
+    message: string;
+    code?: ProviderFailureCode;
+    err?: unknown;
+}): ProviderAttemptDetail;
+export declare function providerAttemptsFromFallbackAttempts(attempts: FallbackAttempt[]): ProviderAttemptDetail[];
+export declare function enrichRunTaskError(err: Error, input?: {
+    providerAttempts?: ProviderAttemptDetail[];
+    code?: ProviderFailureCode;
+}): Error;

package/dist-cjs/router-types.cjs

@@ -0,0 +1,4 @@
+/**
+ * Router-level types for @x12i/ai-gateway (backed by @x12i/ai-router-runtime).
+ */
+export {};

package/dist-cjs/router-types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Router-level types for @x12i/ai-gateway (backed by @x12i/ai-router-runtime).
+ */
+import type { LogLevel, Logxer, StackLoggingOptions } from '@x12i/logxer';
+import type { ProviderFailureCode } from './router-errors.js';
+export type RouterMode = 'sync' | 'stream' | 'batch';
+export type NormalizedUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+export type ActivityCostStatus = 'priced' | 'unpriced';
+export type ProviderModelRef = {
+    engine?: string;
+    provider?: string;
+    model?: string;
+};
+export type AttemptErrorSummary = {
+    name: string;
+    message: string;
+    code: ProviderFailureCode;
+    httpStatus?: number;
+    responsePreview?: string;
+};
+export type DiagnosticsMetadata = {
+    provider?: string;
+    region?: string;
+    modelUsed?: string;
+    costUsd?: number;
+    cost?: number;
+    costStatus?: ActivityCostStatus;
+    maxTokensRequested?: number;
+    requestIds?: Record<string, string | undefined>;
+    timing?: {
+        startedAt: number;
+        endedAt: number;
+        durationMs: number;
+    };
+    latencyMs?: number;
+    attempts?: unknown[];
+    failureCode?: ProviderFailureCode;
+    providerAttempts?: unknown[];
+    operatorHint?: string;
+    normalization?: {
+        normalizedConfig?: Record<string, unknown>;
+        warnings?: string[];
+    };
+    [key: string]: unknown;
+};
+/**
+ * Router configuration shared between gateway init and standalone router factory.
+ */
+export interface GatewayRouterConfig {
+    usageTracker?: {
+        recordRequest(event: {
+            provider: string;
+            timestamp: number;
+            duration: number;
+            tokens: {
+                input: number;
+                output: number;
+                total: number;
+            };
+            cost?: number;
+            success: boolean;
+        }): void;
+    };
+    verbose?: boolean;
+    logLevel?: LogLevel;
+    logging?: StackLoggingOptions;
+    logger?: Logxer;
+    timeoutMs?: number;
+    defaultTimeoutMs?: number;
+    preferOpenRouter?: boolean;
+    /** @deprecated Use preferOpenRouter. */
+    useOpenRouter?: boolean;
+    openrouter?: {
+        apiKey?: string;
+        httpReferer?: string;
+        xTitle?: string;
+    };
+    fallbackChain?: ProviderModelRef[];
+    defaultProvider?: string;
+    autoDiscover?: boolean;
+}
+export interface AIRouterRequest {
+    requestId?: string;
+    request: Record<string, unknown>;
+    provider?: string;
+    mode: RouterMode;
+    exec?: {
+        timeoutMs?: number;
+        retries?: number;
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    };
+}
+export type NormalizedRouterOutput = {
+    parsed?: Record<string, unknown>;
+};
+export interface AIResponse {
+    requestId: string;
+    provider: string;
+    rawResponse: unknown;
+    outputText?: string;
+    output?: NormalizedRouterOutput;
+    usage?: NormalizedUsage;
+    reasoning: {
+        requested: {
+            effort: string;
+            visibility: string;
+        };
+        applied: {
+            effort: string;
+            visibility: string;
+        };
+        artifacts: {
+            encrypted?: unknown[];
+            summary?: {
+                text: string;
+                format: string;
+            };
+            trace?: {
+                text: string;
+                format: string;
+            };
+        };
+        availability: {
+            supportsEffort: boolean;
+            supportsSummary: boolean;
+            supportsTrace: boolean;
+            supportsEncrypted: boolean;
+        };
+        warnings?: unknown[];
+    };
+    metadata?: DiagnosticsMetadata;
+}
+export interface HealthCheckResult {
+    provider: string;
+    healthy: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/** @deprecated Use {@link GatewayRouterConfig}. */
+export type RouterConfig = GatewayRouterConfig;
+/** Backward-compatible alias for {@link GatewayRouter}. */
+export type LLMProviderRouter = import('./gateway-router.js').GatewayRouter;

package/dist-cjs/types.d.ts

@@ -3,7 +3,8 @@
  *
  * Extends router types with gateway-specific enhancements
  */
-import { AIResponse, LLMProviderRouter, type RouterConfig } from '@x12i/ai-providers-router';
+import type { AIResponse, GatewayRouterConfig } from './router-types.js';
+import type { GatewayRouter } from './gateway-router.js';
 type AIProvider = string;
 type AIModel = string;
 export type UsageTier = string;
@@ -366,7 +367,7 @@ export type GatewayInvokeRejectionMetadata = {
      */
     fallbackAttempts?: GatewayFallbackAttempt[];
     /**
-     * Structured per-attempt diagnostics (`@x12i/ai-providers-router` ≥ 4.10).
+     * Structured per-attempt diagnostics from the gateway fallback chain.
      * Same attempts as {@link fallbackAttempts} when enriched; prefer this for UIs.
      */
     providerAttempts?: Array<{
@@ -399,7 +400,7 @@ export type GatewayFallbackAttempt = {
     model?: string;
     httpStatus?: number;
     error: string;
-    /** Stable sub-code from `@x12i/ai-providers-router` ≥ 4.10 (`PROVIDER_AUTH_FAILED`, …). */
+    /** Stable sub-code (`PROVIDER_AUTH_FAILED`, …). */
     code?: string;
     responsePreview?: string;
 };
@@ -456,18 +457,12 @@ export type ActivityIdentity = {
 };
 /** Re-export parser template options for gateway consumers (MUST/optional protocol, subPathSearch, smartInput, etc.). */
 export type { SmartInputConfig, SmartInputRenderOptions, TemplateRenderOptions } from '@x12i/rendrix';
-type LLMRequest = Parameters<LLMProviderRouter['invoke']>[0];
-type LLMResponse = Awaited<ReturnType<LLMProviderRouter['invoke']>>;
+type LLMRequest = Parameters<GatewayRouter['invoke']>[0];
+type LLMResponse = Awaited<ReturnType<GatewayRouter['invoke']>>;
 /**
  * Gateway configuration extending router configuration
  *
- * RouterConfig already includes:
- * - defaultProvider?: LLMProvider (from llm-provider-interface)
- * - fallbackChain?: LLMProvider[]
- * - autoDiscover?: boolean
- * - usageTracker?: UsageTracker
- *
- * We don't need to redeclare these - they're inherited from RouterConfig
+ * GatewayRouterConfig fields (defaultProvider, fallbackChain, usageTracker, …) are inherited below.
  */
 /**
  * Provider + model reference used for defaults and fallbacks
@@ -578,7 +573,7 @@ export interface ModelConfig {
 }
 /** Alias for {@link ModelConfig} in gateway documentation. */
 export type GatewayModelConfig = ModelConfig;
-export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'logger'> {
+export interface GatewayConfig extends Omit<GatewayRouterConfig, 'logger'> {
     /**
      * Default target (engine + model) for routing
      */
@@ -610,8 +605,8 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     /**
      * Process-wide package log level registry (logxer ≥ 4.5).
      * Merged after `applyPackageLogLevelsFromEnv()` on first gateway init.
-     * `logging` (from {@link RouterConfig}) is forwarded to the gateway logger and router.
-     * @example `{ default: 'warn', levels: { AI_GATEWAY: 'info', AI_PROVIDER_ROUTER: 'debug' } }`
+     * `logging` is forwarded to the gateway logger and router runtime.
+     * @example `{ default: 'warn', levels: { AI_GATEWAY: 'info', AI_ROUTER_RUNTIME: 'debug' } }`
      */
     packageLogLevels?: PackageLogLevelsConfig;
     /**
@@ -627,7 +622,7 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     packageName?: string;
     /**
      * Full payload logging for gateway-owned verbose lines (`AI_GATEWAY_VERBOSE=true`).
-     * Separate from log threshold (`AI_GATEWAY_LOGS_LEVEL=verbose`). Router I/O payloads use the same flag via `RouterConfig.verbose`.
+     * Separate from log threshold (`AI_GATEWAY_LOGS_LEVEL=verbose`). Router I/O payloads use the same flag via `GatewayRouterConfig.verbose`.
      */
     verbose?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "11.0.7",
+  "version": "11.1.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -42,13 +42,12 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/activix": "^9.0.3",
-    "@x12i/ai-profiles": "^4.0.0",
-    "@x12i/ai-providers-router": "^4.11.1",
-    "@x12i/ai-tools": "^3.3.5",
+    "@x12i/activix": "^9.0.4",
+    "@x12i/ai-profiles": "^4.2.1",
+    "@x12i/ai-router-runtime": "^1.1.0",
+    "@x12i/ai-tools": "^5.0.0",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^5.1.0",
-    "@x12i/openrouter-runtime": "^1.0.5",
     "@x12i/rendrix": "^4.3.0"
   },
   "devDependencies": {

package/dist/gateway-provider-auto-register.d.ts

@@ -1,17 +0,0 @@
-/**
- * Gateway Provider Auto-Registration Module
- * Automatically registers providers based on environment variables
- */
-import type { LLMProviderRouter } from '@x12i/ai-providers-router';
-import type { Logxer } from '@x12i/logxer';
-/**
- * Auto-registers providers based on environment variables
- * Only registers providers that:
- * 1. Have their API key set in environment variables
- * 2. Have their provider package installed
- *
- * @param router - LLM provider router instance
- * @param logger - Logger instance
- * @returns Array of provider names that were successfully registered
- */
-export declare function autoRegisterProviders(router: LLMProviderRouter, logger: Logxer): Promise<string[]>;

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

@@ -1,159 +0,0 @@
-/**
- * Gateway Provider Auto-Registration Module
- * Automatically registers providers based on environment variables
- */
-const PROVIDER_CONFIGS = [
-    {
-        name: 'openai',
-        packageName: '@x12i/ai-provider-openai',
-        className: 'OpenAIProvider',
-        envVar: 'OPENAI_API_KEY'
-    },
-    {
-        name: 'grok',
-        packageName: '@x12i/ai-provider-grok',
-        className: 'GrokProvider',
-        envVar: 'GROK_API_KEY'
-    },
-    {
-        name: 'anthropic',
-        packageName: '@x12i/ai-provider-anthropic',
-        className: 'AnthropicProvider',
-        envVar: 'ANTHROPIC_API_KEY',
-        optional: true // Optional - may not be installed
-    },
-    {
-        name: 'google',
-        packageName: '@x12i/ai-provider-google',
-        className: 'GoogleProvider',
-        envVar: 'GOOGLE_API_KEY',
-        optional: true // Optional - may not be installed
-    },
-    {
-        name: 'cohere',
-        packageName: '@x12i/ai-provider-cohere',
-        className: 'CohereProvider',
-        envVar: 'COHERE_API_KEY',
-        optional: true // Optional - may not be installed
-    },
-    {
-        name: 'mistral',
-        packageName: '@x12i/ai-provider-mistral',
-        className: 'MistralProvider',
-        envVar: 'MISTRAL_API_KEY',
-        optional: true // Optional - may not be installed
-    }
-];
-/**
- * Auto-registers providers based on environment variables
- * Only registers providers that:
- * 1. Have their API key set in environment variables
- * 2. Have their provider package installed
- *
- * @param router - LLM provider router instance
- * @param logger - Logger instance
- * @returns Array of provider names that were successfully registered
- */
-export async function autoRegisterProviders(router, logger) {
-    const registeredProviders = [];
-    logger.debug('Auto-registering providers from environment variables');
-    for (const providerConfig of PROVIDER_CONFIGS) {
-        const apiKey = process.env[providerConfig.envVar];
-        // Skip if API key is not set
-        if (!apiKey) {
-            if (!providerConfig.optional) {
-                logger.debug(`Skipping ${providerConfig.name} provider: ${providerConfig.envVar} not set`);
-            }
-            continue;
-        }
-        try {
-            // Dynamically import the provider package
-            // Use dynamic import() for ES module compatibility
-            let ProviderClass;
-            try {
-                const providerModule = await import(providerConfig.packageName);
-                ProviderClass = providerModule[providerConfig.className] || providerModule.default;
-                if (!ProviderClass) {
-                    logger.debug(`Provider class ${providerConfig.className} not found in ${providerConfig.packageName}`);
-                    continue;
-                }
-            }
-            catch (importError) {
-                if (!providerConfig.optional) {
-                    logger.warn(`Failed to import ${providerConfig.packageName}`, {
-                        error: importError instanceof Error ? importError.message : String(importError),
-                        note: `Install it with: npm install ${providerConfig.packageName}`
-                    });
-                }
-                continue;
-            }
-            // Instantiate the provider
-            const provider = new ProviderClass({
-                apiKey: apiKey
-            });
-            // Get provider name for both module creation and logging
-            const providerName = typeof provider.getProviderName === 'function'
-                ? provider.getProviderName()
-                : providerConfig.name;
-            // Register with router as ProviderModule
-            const providerModule = {
-                name: providerName,
-                capabilities: {
-                    modes: {
-                        sync: true,
-                        stream: false,
-                        batch: false
-                    },
-                    operations: ['invoke'],
-                    maxConcurrency: 10
-                },
-                execute: async (request) => {
-                    // Use aiCall if available, otherwise assume invoke
-                    if (typeof provider.aiCall === 'function') {
-                        return await provider.aiCall(request);
-                    }
-                    else if (typeof provider.invoke === 'function') {
-                        return await provider.invoke(request);
-                    }
-                    else {
-                        throw new Error(`Provider ${providerName} has neither aiCall nor invoke method`);
-                    }
-                }
-            };
-            router.registerProvider(providerModule);
-            registeredProviders.push(providerName);
-            logger.info(`Auto-registered provider: ${providerName}`, {
-                provider: providerName,
-                envVar: providerConfig.envVar,
-                hasApiKey: !!apiKey
-            });
-        }
-        catch (error) {
-            logger.error(`Failed to auto-register ${providerConfig.name} provider`, {
-                provider: providerConfig.name,
-                package: providerConfig.packageName,
-                error: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined
-            });
-            // Continue with other providers even if one fails
-        }
-    }
-    if (registeredProviders.length === 0) {
-        logger.warn('No providers were auto-registered. Make sure API keys are set in environment variables:', {
-            requiredEnvVars: PROVIDER_CONFIGS
-                .filter(p => !p.optional)
-                .map(p => p.envVar),
-            optionalEnvVars: PROVIDER_CONFIGS
-                .filter(p => p.optional)
-                .map(p => p.envVar),
-            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)'
-        });
-    }
-    else {
-        logger.info(`Auto-registered ${registeredProviders.length} provider(s)`, {
-            providers: registeredProviders
-        });
-    }
-    return registeredProviders;
-}

package/dist/gateway-provider.d.ts

@@ -1,54 +0,0 @@
-/**
- * Gateway Provider Module
- * Handles provider management
- */
-import type { LLMProviderRouter } from '@x12i/ai-providers-router';
-import type { Logxer } from '@x12i/logxer';
-/**
- * Register a provider with the router
- */
-export declare function registerProvider(provider: any, router: LLMProviderRouter, logger: Logxer): void;
-/**
- * Unregister a provider
- */
-export declare function unregisterProvider(providerName: string, router: LLMProviderRouter, logger: Logxer): void;
-/**
- * Get a provider module
- */
-export declare function getProvider(providerName: string, router: LLMProviderRouter): any;
-/**
- * List all registered providers
- */
-export declare function listProviders(router: LLMProviderRouter): string[];
-/**
- * Set default provider
- *
- * NOTE: Router doesn't support changing default provider after initialization.
- * This method is kept for API compatibility but does nothing.
- * Default provider must be set in router config during initialization.
- */
-export declare function setDefaultProvider(provider: string, router: LLMProviderRouter, logger: Logxer): void;
-/**
- * Set fallback chain
- *
- * NOTE: Router doesn't support changing fallback chain after initialization.
- * This method is kept for API compatibility but does nothing.
- * Fallback chain must be set in router config during initialization.
- */
-export declare function setFallbackChain(chain: string[], router: LLMProviderRouter, logger: Logxer): void;
-/**
- * Add request interceptor
- */
-export declare function addRequestInterceptor(interceptor: any, router: LLMProviderRouter): void;
-/**
- * Add response interceptor
- */
-export declare function addResponseInterceptor(interceptor: any, router: LLMProviderRouter): void;
-/**
- * Check health of a provider
- */
-export declare function checkHealth(provider: string, router: LLMProviderRouter): Promise<import("@x12i/ai-providers-router").HealthCheckResult>;
-/**
- * Check health of all providers
- */
-export declare function checkAllHealth(router: LLMProviderRouter): Promise<Record<string, any>>;