@x12i/ai-providers-router 4.8.0 → 4.8.2

package/dist/errors.d.ts

@@ -5,18 +5,19 @@ import type { ProviderId } from './types.js';
 export declare class ProviderNotFoundError extends Error {
     constructor(providerName: ProviderId | string);
 }
+export type FallbackAttempt = {
+    provider: ProviderId | string;
+    model?: string;
+    httpStatus?: number;
+    error: Error;
+    responsePreview?: string;
+};
 /**
  * Error thrown when all providers in the fallback chain have failed
  */
 export declare class FallbackExhaustedError extends Error {
-    attempts: Array<{
-        provider: ProviderId;
-        error: Error;
-    }>;
-    constructor(attempts: Array<{
-        provider: ProviderId;
-        error: Error;
-    }>);
+    attempts: FallbackAttempt[];
+    constructor(attempts: FallbackAttempt[]);
 }
 /**
  * Error thrown when a provider package is not installed

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { LLMProviderRouter } from './router.js';
-export type { RouterConfig, HealthCheckResult, ProviderId, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, } from './router.js';
+export type { RouterConfig, HealthCheckResult, ProviderId, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, NormalizedRouterOutput, ProviderModelRef, } from './router.js';
 export { createRouter, createRouterFromConfig } from './factory.js';
 export type { CreateRouterConfig } from './factory.js';
 export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError, ProviderTimeoutError } from './errors.js';
+export type { FallbackAttempt } from './errors.js';
+export type { PartialRouterPayload } from './router/partialErrorPayload.js';
 export type { RequestInterceptor, ResponseInterceptor } from './interceptors.js';
 export type { UsageTracker, AdapterLoader, ProviderInit } from './types.js';
 export { Logger, getLogger, createLogger } from './logger.js';

package/dist/providers/OpenRouterProvider.js

@@ -4,6 +4,21 @@
  */
 import { OpenRouter } from '@openrouter/sdk';
 import { ProviderTimeoutError } from '../errors.js';
+function preservePartialResponseOnError(error) {
+    if (error == null || typeof error !== 'object')
+        return;
+    const e = error;
+    if (e.rawResponse !== undefined)
+        return;
+    const response = e.response;
+    if (response == null || typeof response !== 'object')
+        return;
+    const resp = response;
+    const body = resp.data ?? resp.body ?? resp;
+    if (body != null && typeof body === 'object') {
+        e.rawResponse = body;
+    }
+}
 /**
  * Create OpenRouter ProviderModule using @openrouter/sdk directly
  */
@@ -124,6 +139,7 @@ export function createOpenRouterProvider(config) {
                 if (timedOut && typeof timeoutMs === 'number') {
                     throw new ProviderTimeoutError('openrouter', timeoutMs, operation);
                 }
+                preservePartialResponseOnError(error);
                 throw error;
             }
             finally {
@@ -223,6 +239,7 @@ export function createOpenRouterProvider(config) {
                 if (timedOut && typeof timeoutMs === 'number') {
                     throw new ProviderTimeoutError('openrouter', timeoutMs, operation);
                 }
+                preservePartialResponseOnError(error);
                 throw error;
             }
             finally {

package/dist/router/Router.d.ts

@@ -1,6 +1,6 @@
 import type { ProviderRegistry } from '../registry/ProviderRegistry.js';
 import type { AdapterRegistry } from '../registry/AdapterRegistry.js';
-import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem } from './RouterTypes.js';
+import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, RouterConfig } from './RouterTypes.js';
 /**
  * Main router class
  * Orchestrates provider execution using ProviderModules and router-side adapters
@@ -8,7 +8,12 @@ import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBat
 export declare class AIRouter {
     private providers;
     private adapters;
-    constructor(providers: ProviderRegistry, adapters: AdapterRegistry);
+    private routerConfig;
+    constructor(providers: ProviderRegistry, adapters: AdapterRegistry, routerConfig?: RouterConfig);
+    /**
+     * Resolve provider module name for a specific fallback candidate.
+     */
+    private resolveProviderNameForCandidate;
     /**
      * Resolve provider name from request, checking OpenRouter mode first
      */

package/dist/router/Router.js

@@ -1,14 +1,34 @@
 import { newId } from '../utils/ids.js';
 import { applyResponseNormalization } from '../normalization/applyResponseNormalization.js';
 import { extractCostUsdFromRouterResponse } from '../normalization/cost.js';
+import { FallbackExhaustedError } from '../errors.js';
+import { buildCandidateRequest, buildFallbackCandidates, isRetryableError, summarizeError, toError, } from './fallbackUtils.js';
+import { attachPartialRouterPayload, buildPartialRouterPayload } from './partialErrorPayload.js';
 /**
  * Main router class
  * Orchestrates provider execution using ProviderModules and router-side adapters
  */
 export class AIRouter {
-    constructor(providers, adapters) {
+    constructor(providers, adapters, routerConfig = {}) {
         this.providers = providers;
         this.adapters = adapters;
+        this.routerConfig = routerConfig;
+    }
+    /**
+     * Resolve provider module name for a specific fallback candidate.
+     */
+    resolveProviderNameForCandidate(input, candidateProvider) {
+        const candidateInput = {
+            ...input,
+            request: {
+                ...input.request,
+                config: {
+                    ...(input.request?.config ?? {}),
+                    provider: candidateProvider,
+                },
+            },
+        };
+        return this.resolveProviderName(candidateInput);
     }
     /**
      * Resolve provider name from request, checking OpenRouter mode first
@@ -93,12 +113,15 @@ export class AIRouter {
     async runSync(input) {
         const requestId = input.requestId ?? newId();
         const primaryProviderName = this.resolveProviderName(input);
-        const fallbackProvidersRaw = input.request?.config?.fallbackProviders;
-        const fallbackProviders = Array.isArray(fallbackProvidersRaw)
-            ? fallbackProvidersRaw.filter((p) => typeof p === 'string' && p.trim().length > 0).map((p) => p.trim())
-            : [];
-        // Candidates are ordered: primary, then fallbacks.
-        const providerCandidates = [primaryProviderName, ...fallbackProviders.filter((p) => p !== primaryProviderName)];
+        const requestConfig = input.request?.config;
+        const primaryModel = (typeof requestConfig?.model === 'string' ? requestConfig.model : undefined) ??
+            (typeof input.request?.model === 'string' ? input.request.model : undefined);
+        const fallbackCandidates = buildFallbackCandidates({
+            primaryProvider: primaryProviderName,
+            primaryModel,
+            requestConfig: requestConfig && typeof requestConfig === 'object' ? requestConfig : undefined,
+            routerFallbackChain: this.routerConfig.fallbackChain,
+        });
         const maxRetries = Math.max(0, Math.min(10, Number(input.exec?.retries ?? 0) || 0));
         const attempts = [];
         const normalizeUsage = (usage) => {
@@ -129,61 +152,73 @@ export class AIRouter {
                 (typeof args.maxTokens === 'number' ? args.maxTokens : undefined);
             return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
         };
-        const summarizeError = (err) => {
-            const e = err instanceof Error ? err : new Error(String(err));
-            const name = typeof e.name === 'string' ? e.name : 'Error';
-            const message = typeof e.message === 'string' ? e.message : String(err);
-            // Size cap to avoid shipping huge provider payloads.
-            const capped = message.length > 500 ? message.slice(0, 500) : message;
-            return { name, message: capped };
-        };
         const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-        const isRetryableError = (err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            const name = err instanceof Error ? err.name : '';
-            const combined = `${name} ${msg}`.toLowerCase();
-            return (combined.includes('timeout') ||
-                combined.includes('timed out') ||
-                combined.includes('rate limit') ||
-                combined.includes('429') ||
-                combined.includes('econnreset') ||
-                combined.includes('etimedout') ||
-                combined.includes('503') ||
-                combined.includes('502') ||
-                combined.includes('504') ||
-                combined.includes('temporarily unavailable'));
-        };
         const backoffMs = (retryIndex) => {
             const base = 250 * Math.pow(2, Math.max(0, retryIndex));
             const jitter = Math.floor(Math.random() * 100);
             return Math.min(5000, base + jitter);
         };
         let lastError = undefined;
-        for (let fallbackIndex = 0; fallbackIndex < providerCandidates.length; fallbackIndex++) {
-            const providerName = providerCandidates[fallbackIndex];
+        const failedAttemptErrors = [];
+        let lastPartialPayload;
+        for (let fallbackIndex = 0; fallbackIndex < fallbackCandidates.length; fallbackIndex++) {
+            const candidate = fallbackCandidates[fallbackIndex];
+            const candidateInput = buildCandidateRequest(input, candidate);
+            const providerName = this.resolveProviderNameForCandidate(candidateInput, candidate.provider);
+            if (!this.providers.has(providerName)) {
+                const err = new Error(`Provider not registered: ${providerName}. Available: ${this.providers.list().join(', ')}`);
+                lastError = err;
+                failedAttemptErrors.push(err);
+                const partialPayload = buildPartialRouterPayload({
+                    requestId,
+                    engineProvider: candidate.provider,
+                    providerModule: providerName,
+                    modelUsed: candidate.model,
+                    attempts,
+                    providerError: err,
+                });
+                lastPartialPayload = partialPayload;
+                attachPartialRouterPayload(err, partialPayload);
+                attempts.push({
+                    ok: false,
+                    routing: {
+                        provider: candidate.provider,
+                        retryIndex: 0,
+                        fallbackIndex,
+                        requestIds: { routerRequestId: requestId },
+                    },
+                    modelUsed: candidate.model,
+                    error: summarizeError(err),
+                });
+                continue;
+            }
             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 (once per provider candidate; retries reuse the same spec)
+            // Build call spec (once per fallback candidate; retries reuse the same spec)
             const spec = await adapter.buildCallSpec({
                 requestId,
                 mode: 'sync',
-                request: input.request,
+                request: candidateInput.request,
                 exec: input.exec,
             });
             const maxTokensRequested = extractMaxTokensRequested(spec);
-            const requestedModel = spec?.args?.model ?? input.request?.config?.model ?? input.request?.model;
+            const requestedModel = spec?.args?.model ??
+                candidate.model ??
+                candidateInput.request?.config?.model ??
+                candidateInput.request?.model;
             for (let retryIndex = 0; retryIndex <= maxRetries; retryIndex++) {
                 const startedAt = Date.now();
+                let execResult;
                 try {
-                    const execResult = await provider.execute(spec);
+                    execResult = await provider.execute(spec);
                     const endedAt = Date.now();
                     const parsed = adapter.parseResponse({
                         requestId,
-                        request: { ...input.request, _callSpec: spec }, // Include call spec for adapter access
+                        request: { ...candidateInput.request, _callSpec: spec },
                         execResult,
                     });
                     const usage = normalizeUsage(parsed.usage);
@@ -203,7 +238,7 @@ export class AIRouter {
                     const attempt = {
                         ok: true,
                         routing: {
-                            provider: providerName,
+                            provider: candidate.provider,
                             retryIndex,
                             fallbackIndex,
                             requestIds: {
@@ -242,24 +277,42 @@ export class AIRouter {
                         usage,
                         metadata: mergedMetadata,
                     };
-                    return applyResponseNormalization(baseResponse, input.request);
+                    return applyResponseNormalization(baseResponse, candidateInput.request);
                 }
                 catch (err) {
                     const endedAt = Date.now();
                     lastError = err;
+                    failedAttemptErrors.push(err);
+                    const modelUsed = typeof requestedModel === 'string'
+                        ? requestedModel
+                        : candidate.model;
+                    const timing = { startedAt, endedAt, durationMs: endedAt - startedAt };
                     attempts.push({
                         ok: false,
                         routing: {
-                            provider: providerName,
+                            provider: candidate.provider,
                             retryIndex,
                             fallbackIndex,
                             requestIds: { routerRequestId: requestId },
                         },
-                        timing: { startedAt, endedAt, durationMs: endedAt - startedAt },
+                        timing,
                         maxTokensRequested,
-                        modelUsed: typeof requestedModel === 'string' ? requestedModel : undefined,
+                        modelUsed,
                         error: summarizeError(err),
                     });
+                    const partialPayload = buildPartialRouterPayload({
+                        requestId,
+                        engineProvider: candidate.provider,
+                        providerModule: providerName,
+                        modelUsed,
+                        maxTokensRequested,
+                        timing,
+                        attempts,
+                        execResult,
+                        providerError: err,
+                    });
+                    lastPartialPayload = partialPayload;
+                    attachPartialRouterPayload(err, partialPayload);
                     const shouldRetry = retryIndex < maxRetries && isRetryableError(err);
                     if (shouldRetry) {
                         await sleep(backoffMs(retryIndex));
@@ -269,10 +322,19 @@ export class AIRouter {
                 }
             }
         }
-        // Fallback chain exhausted
-        const error = lastError instanceof Error ? lastError : new Error(String(lastError ?? 'Unknown error'));
-        error.attempts = attempts;
-        throw error;
+        const failedTraces = attempts.filter((a) => !a.ok);
+        const exhaustedAttempts = failedTraces.map((trace, i) => ({
+            provider: trace.routing.provider,
+            model: trace.modelUsed,
+            httpStatus: trace.error?.httpStatus,
+            error: toError(failedAttemptErrors[i] ?? lastError),
+            ...(trace.error?.responsePreview !== undefined ? { responsePreview: trace.error.responsePreview } : {}),
+        }));
+        const exhaustedError = new FallbackExhaustedError(exhaustedAttempts);
+        if (lastPartialPayload) {
+            attachPartialRouterPayload(exhaustedError, lastPartialPayload);
+        }
+        throw exhaustedError;
     }
     /**
      * Execute a streaming request

package/dist/router/RouterTypes.d.ts

@@ -18,6 +18,14 @@ export type AttemptTiming = {
 export type AttemptErrorSummary = {
     name: string;
     message: string;
+    httpStatus?: number;
+    responsePreview?: string;
+};
+/** Provider + model reference used in fallback chains (`engine` is a gateway alias for `provider`). */
+export type ProviderModelRef = {
+    engine?: string;
+    provider?: string;
+    model?: string;
 };
 export type AttemptRouting = {
     provider: string;
@@ -93,6 +101,8 @@ export interface RouterConfig {
         httpReferer?: string;
         xTitle?: string;
     };
+    /** Default provider/model fallback chain when request config does not specify one. */
+    fallbackChain?: ProviderModelRef[];
 }
 /**
  * Router request - the input to the router

package/dist/router/RouterWrapper.js

@@ -60,7 +60,7 @@ export class LLMProviderRouter {
         this.adapterRegistry.register(new GrokAdapter());
         this.adapterRegistry.register(new OpenRouterAdapter());
         // Create router
-        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry);
+        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry, this.config);
         this.logger.info('Router initialized with ProviderModule architecture', {
             verbose: this.logger.verbose,
             logLevel: this.logger.level,

package/dist/router/fallbackUtils.d.ts

@@ -0,0 +1,38 @@
+import type { AttemptErrorSummary } from './RouterTypes.js';
+export type FallbackCandidate = {
+    provider: string;
+    model?: string;
+};
+export type ProviderModelRef = {
+    engine?: string;
+    provider?: string;
+    model?: string;
+};
+export declare function extractHttpStatus(err: unknown): number | undefined;
+export declare function extractResponsePreview(err: unknown): string | undefined;
+export declare function toError(err: unknown): Error;
+export declare function summarizeError(err: unknown): AttemptErrorSummary;
+export declare function isModelNotFoundError(err: unknown): boolean;
+/** Transient failures — retry the same provider/model candidate. */
+export declare function isRetryableError(err: unknown): boolean;
+/** Failures that should advance to the next fallback candidate (not retry same candidate). */
+export declare function isFallbackEligibleError(err: unknown): boolean;
+export declare function buildFallbackCandidates(input: {
+    primaryProvider: string;
+    primaryModel?: string;
+    requestConfig?: Record<string, unknown>;
+    routerFallbackChain?: ProviderModelRef[];
+}): FallbackCandidate[];
+export declare function buildCandidateRequest(input: AIRouterRequestLike, candidate: FallbackCandidate): AIRouterRequestLike;
+type AIRouterRequestLike = {
+    request?: {
+        config?: Record<string, unknown>;
+        model?: string;
+        [key: string]: unknown;
+    };
+    provider?: string;
+    mode?: string;
+    exec?: unknown;
+    requestId?: string;
+};
+export {};

package/dist/router/fallbackUtils.js

@@ -0,0 +1,176 @@
+const PREVIEW_CAP = 500;
+export function extractHttpStatus(err) {
+    const e = err;
+    if (!e)
+        return undefined;
+    for (const key of ['status', 'statusCode', 'httpStatus']) {
+        const v = e[key];
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    const response = e.response;
+    if (response && typeof response.status === 'number')
+        return response.status;
+    const msg = err instanceof Error ? err.message : String(err);
+    const httpMatch = msg.match(/\bHTTP\s+(\d{3})\b/i);
+    if (httpMatch)
+        return Number(httpMatch[1]);
+    return undefined;
+}
+export function extractResponsePreview(err) {
+    const e = err;
+    if (!e)
+        return undefined;
+    const raw = e.body ??
+        e.responseBody ??
+        e.response?.data ??
+        e.data ??
+        e.error;
+    if (raw === undefined || raw === null)
+        return undefined;
+    let text;
+    if (typeof raw === 'string') {
+        text = raw;
+    }
+    else {
+        try {
+            text = JSON.stringify(raw);
+        }
+        catch {
+            text = String(raw);
+        }
+    }
+    return text.length > PREVIEW_CAP ? text.slice(0, PREVIEW_CAP) : text;
+}
+export function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+export function summarizeError(err) {
+    const e = toError(err);
+    const name = typeof e.name === 'string' ? e.name : 'Error';
+    const message = typeof e.message === 'string' ? e.message : String(err);
+    const capped = message.length > PREVIEW_CAP ? message.slice(0, PREVIEW_CAP) : message;
+    const httpStatus = extractHttpStatus(err);
+    const responsePreview = extractResponsePreview(err);
+    return {
+        name,
+        message: capped,
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+        ...(responsePreview !== undefined ? { responsePreview } : {}),
+    };
+}
+export function isModelNotFoundError(err) {
+    const status = extractHttpStatus(err);
+    if (status === 404)
+        return true;
+    const msg = err instanceof Error ? err.message : String(err);
+    const name = err instanceof Error ? err.name : '';
+    const combined = `${name} ${msg}`.toLowerCase();
+    return (combined.includes('model not found') ||
+        combined.includes('model_not_found') ||
+        combined.includes('model does not exist') ||
+        combined.includes('unknown model') ||
+        combined.includes('invalid model'));
+}
+/** Transient failures — retry the same provider/model candidate. */
+export function isRetryableError(err) {
+    if (isModelNotFoundError(err))
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    const name = err instanceof Error ? err.name : '';
+    const combined = `${name} ${msg}`.toLowerCase();
+    return (combined.includes('timeout') ||
+        combined.includes('timed out') ||
+        combined.includes('rate limit') ||
+        combined.includes('429') ||
+        combined.includes('econnreset') ||
+        combined.includes('etimedout') ||
+        combined.includes('503') ||
+        combined.includes('502') ||
+        combined.includes('504') ||
+        combined.includes('temporarily unavailable'));
+}
+/** Failures that should advance to the next fallback candidate (not retry same candidate). */
+export function isFallbackEligibleError(err) {
+    if (isModelNotFoundError(err))
+        return true;
+    const status = extractHttpStatus(err);
+    if (status !== undefined) {
+        if (status === 404)
+            return true;
+        if (status >= 500)
+            return false;
+        if (status === 429)
+            return false;
+    }
+    return !isRetryableError(err);
+}
+function parseProviderModelRef(entry) {
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    const ref = entry;
+    const providerRaw = ref.engine ?? ref.provider;
+    if (typeof providerRaw !== 'string' || !providerRaw.trim())
+        return undefined;
+    const provider = providerRaw.trim();
+    const model = typeof ref.model === 'string' && ref.model.trim() ? ref.model.trim() : undefined;
+    return { provider, model };
+}
+function dedupeCandidates(candidates) {
+    const seen = new Set();
+    const out = [];
+    for (const c of candidates) {
+        const key = `${c.provider}\0${c.model ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+export function buildFallbackCandidates(input) {
+    const { primaryProvider, primaryModel, requestConfig, routerFallbackChain } = input;
+    const candidates = [{ provider: primaryProvider, model: primaryModel }];
+    const chainRaw = (Array.isArray(requestConfig?.fallbackChain) ? requestConfig.fallbackChain : undefined) ??
+        (Array.isArray(requestConfig?.fallbackEngines) ? requestConfig.fallbackEngines : undefined) ??
+        (Array.isArray(routerFallbackChain) ? routerFallbackChain : undefined);
+    if (Array.isArray(chainRaw) && chainRaw.length > 0) {
+        for (const entry of chainRaw) {
+            const parsed = parseProviderModelRef(entry);
+            if (parsed)
+                candidates.push(parsed);
+        }
+    }
+    else {
+        const fallbackProvidersRaw = requestConfig?.fallbackProviders;
+        const fallbackProviders = Array.isArray(fallbackProvidersRaw)
+            ? fallbackProvidersRaw
+                .filter((p) => typeof p === 'string' && p.trim().length > 0)
+                .map((p) => p.trim())
+            : [];
+        for (const provider of fallbackProviders) {
+            if (provider !== primaryProvider) {
+                candidates.push({ provider, model: primaryModel });
+            }
+        }
+    }
+    return dedupeCandidates(candidates);
+}
+export function buildCandidateRequest(input, candidate) {
+    const baseConfig = (input.request?.config && typeof input.request.config === 'object')
+        ? input.request.config
+        : {};
+    const model = candidate.model ?? (typeof baseConfig.model === 'string' ? baseConfig.model : undefined);
+    return {
+        ...input,
+        request: {
+            ...input.request,
+            ...(model !== undefined ? { model } : {}),
+            config: {
+                ...baseConfig,
+                provider: candidate.provider,
+                ...(model !== undefined ? { model } : {}),
+            },
+        },
+    };
+}

package/dist/router/partialErrorPayload.d.ts

@@ -0,0 +1,26 @@
+import type { ProviderSDKExecResult } from '@x12i/ai-provider-interface';
+import type { AttemptTrace, DiagnosticsMetadata, NormalizedUsage } from './RouterTypes.js';
+export type PartialRouterPayload = {
+    requestId: string;
+    provider: string;
+    usage?: NormalizedUsage;
+    metadata: DiagnosticsMetadata;
+    rawResponse?: unknown;
+};
+export declare function attachPartialRouterPayload(err: unknown, payload: PartialRouterPayload): void;
+export declare function normalizeUsageFromUnknown(usage: unknown): NormalizedUsage | undefined;
+export declare function buildPartialRouterPayload(args: {
+    requestId: string;
+    engineProvider: string;
+    providerModule?: string;
+    modelUsed?: string;
+    maxTokensRequested?: number;
+    timing?: {
+        startedAt: number;
+        endedAt: number;
+        durationMs: number;
+    };
+    attempts?: AttemptTrace[];
+    execResult?: ProviderSDKExecResult;
+    providerError?: unknown;
+}): PartialRouterPayload;

package/dist/router/partialErrorPayload.js

@@ -0,0 +1,133 @@
+export function attachPartialRouterPayload(err, payload) {
+    if (err == null || typeof err !== 'object')
+        return;
+    err.response = payload;
+}
+function firstString(...values) {
+    for (const v of values) {
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+export function normalizeUsageFromUnknown(usage) {
+    if (!usage || typeof usage !== 'object')
+        return undefined;
+    const u = usage;
+    const promptTokens = (typeof u.promptTokens === 'number' ? u.promptTokens : undefined) ??
+        (typeof u.inputTokens === 'number' ? u.inputTokens : undefined) ??
+        (typeof u.prompt_tokens === 'number' ? u.prompt_tokens : undefined) ??
+        (typeof u.input_tokens === 'number' ? u.input_tokens : undefined) ??
+        (typeof u.prompt === 'number' ? u.prompt : undefined);
+    const completionTokens = (typeof u.completionTokens === 'number' ? u.completionTokens : undefined) ??
+        (typeof u.outputTokens === 'number' ? u.outputTokens : undefined) ??
+        (typeof u.completion_tokens === 'number' ? u.completion_tokens : undefined) ??
+        (typeof u.output_tokens === 'number' ? u.output_tokens : undefined) ??
+        (typeof u.completion === 'number' ? u.completion : undefined);
+    const totalTokens = (typeof u.totalTokens === 'number' ? u.totalTokens : undefined) ??
+        (typeof u.total_tokens === 'number' ? u.total_tokens : undefined) ??
+        (typeof u.total === 'number' ? u.total : undefined);
+    if (promptTokens === undefined && completionTokens === undefined && totalTokens === undefined) {
+        return undefined;
+    }
+    const p = promptTokens ?? 0;
+    const c = completionTokens ?? 0;
+    return { promptTokens: p, completionTokens: c, totalTokens: totalTokens ?? p + c };
+}
+function extractIdsFromRaw(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const r = raw;
+    const id = firstString(r.id, r.request_id, r.requestId);
+    if (!id)
+        return {};
+    return { providerRequestId: id, openrouterRequestId: id };
+}
+function extractRawBody(err) {
+    if (err == null || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    const response = e.response;
+    if (response != null && typeof response === 'object') {
+        const resp = response;
+        if (resp.data !== undefined)
+            return resp.data;
+        if (resp.body !== undefined)
+            return resp.body;
+    }
+    for (const key of ['rawResponse', 'body', 'data', 'lastResponse', 'routerResponse']) {
+        if (e[key] !== undefined)
+            return e[key];
+    }
+    const nestedError = e.error;
+    if (nestedError != null && typeof nestedError === 'object') {
+        return extractRawBody(nestedError);
+    }
+    return undefined;
+}
+function extractHeaderRequestId(err) {
+    if (err == null || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    const response = e.response;
+    if (response == null || typeof response !== 'object')
+        return undefined;
+    const headers = response.headers;
+    if (headers == null || typeof headers !== 'object')
+        return undefined;
+    const h = headers;
+    return firstString(h['x-request-id'], h['x-openrouter-request-id'], h['request-id'], h['openrouter-request-id']);
+}
+function usageToGatewayTokens(usage) {
+    return {
+        prompt: usage.promptTokens,
+        completion: usage.completionTokens,
+        total: usage.totalTokens,
+    };
+}
+export function buildPartialRouterPayload(args) {
+    let usage = args.execResult?.rawResponse
+        ? normalizeUsageFromUnknown(args.execResult.rawResponse?.usage)
+        : undefined;
+    let rawResponse = args.execResult?.rawResponse;
+    let ids = rawResponse ? extractIdsFromRaw(rawResponse) : {};
+    const errorBody = extractRawBody(args.providerError);
+    if (errorBody !== undefined) {
+        rawResponse = rawResponse ?? errorBody;
+        usage = usage ?? normalizeUsageFromUnknown(errorBody?.usage);
+        const bodyIds = extractIdsFromRaw(errorBody);
+        ids = { ...bodyIds, ...ids };
+    }
+    const headerRequestId = extractHeaderRequestId(args.providerError);
+    if (headerRequestId) {
+        ids = {
+            providerRequestId: ids.providerRequestId ?? headerRequestId,
+            openrouterRequestId: ids.openrouterRequestId ?? headerRequestId,
+        };
+    }
+    const providerRequestId = ids.providerRequestId;
+    const openrouterRequestId = args.providerModule === 'openrouter' ? providerRequestId : ids.openrouterRequestId;
+    const metadata = {
+        provider: args.providerModule ?? args.engineProvider,
+        ...(args.modelUsed !== undefined ? { modelUsed: args.modelUsed } : {}),
+        ...(args.maxTokensRequested !== undefined ? { maxTokensRequested: args.maxTokensRequested } : {}),
+        requestIds: {
+            routerRequestId: args.requestId,
+            ...(providerRequestId ? { providerRequestId } : {}),
+            ...(openrouterRequestId ? { openrouterRequestId } : {}),
+        },
+        ...(args.timing ? { timing: args.timing, latencyMs: args.timing.durationMs } : {}),
+        ...(args.attempts ? { attempts: args.attempts } : {}),
+    };
+    if (usage) {
+        metadata.usage = usage;
+        metadata.tokens = usageToGatewayTokens(usage);
+    }
+    return {
+        requestId: args.requestId,
+        provider: args.engineProvider,
+        ...(usage ? { usage } : {}),
+        ...(rawResponse !== undefined ? { rawResponse } : {}),
+        metadata,
+    };
+}

package/dist/router.d.ts

@@ -1,5 +1,5 @@
 export { LLMProviderRouter } from './router/RouterWrapper.js';
-export type { RouterConfig, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, ActivityCostStatus, NormalizedRouterOutput } from './router/RouterTypes.js';
+export type { RouterConfig, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, ActivityCostStatus, NormalizedRouterOutput, ProviderModelRef, } from './router/RouterTypes.js';
 export { ProviderRegistry } from './registry/ProviderRegistry.js';
 export { AdapterRegistry } from './registry/AdapterRegistry.js';
 export { OpenAIAdapter } from './adapters/openai/OpenAIAdapter.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.8.0",
+  "version": "4.8.2",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",