@x12i/ai-gateway 7.9.1

package/dist/gateway-provider.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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>>;

package/dist/gateway-provider.js

@@ -0,0 +1,202 @@
+/**
+ * Gateway Provider Module
+ * Handles provider management
+ */
+/**
+ * Register a provider with the router
+ */
+export function registerProvider(provider, router, logger) {
+    // Get provider name - try multiple methods
+    let providerName = 'unknown';
+    if (typeof provider.getProviderName === 'function') {
+        providerName = provider.getProviderName();
+    }
+    else if (provider.name) {
+        providerName = provider.name;
+    }
+    else if (provider.constructor?.name) {
+        providerName = provider.constructor.name.replace('Provider', '').toLowerCase();
+    }
+    logger.debug('Registering provider', { provider: providerName });
+    // Check if provider has required methods
+    if (!provider || (typeof provider.invoke !== 'function' && typeof provider.aiCall !== 'function')) {
+        logger.error('Provider registration failed: must implement invoke() or aiCall()', {
+            provider: providerName,
+            hasInvoke: typeof provider.invoke === 'function',
+            hasAiCall: typeof provider.aiCall === 'function'
+        });
+        throw new Error('Provider must implement LLMProviderInterface (invoke) or AIProviderInterface (aiCall)');
+    }
+    // Create a ProviderModule wrapper for the provider instance
+    logger.debug('Creating ProviderModule wrapper for provider instance', { provider: providerName });
+    // Ensure provider has invoke method
+    let providerWithInvoke = provider;
+    if (typeof provider.aiCall === 'function' && typeof provider.invoke !== 'function') {
+        logger.debug('Provider uses aiCall, creating invoke wrapper', { provider: providerName });
+        providerWithInvoke = {
+            ...provider,
+            invoke: async (request) => {
+                // Convert LLMRequest to format expected by aiCall
+                return await provider.aiCall(request);
+            }
+        };
+    }
+    // Create ProviderModule wrapper
+    const providerModule = {
+        name: providerName,
+        capabilities: {
+            modes: {
+                sync: true,
+                stream: false,
+                batch: false
+            },
+            operations: ['invoke'],
+            maxConcurrency: 10
+        },
+        execute: async (request) => {
+            return await providerWithInvoke.invoke(request);
+        }
+    };
+    // Register with router using registerProvider
+    try {
+        router.registerProvider(providerModule);
+        logger.info('Provider registered as ProviderModule', {
+            provider: providerName,
+            totalProviders: router.listProviders().length
+        });
+    }
+    catch (error) {
+        logger.error('Failed to register provider with router.registerProvider, trying registry directly', {
+            provider: providerName,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        // Fallback: try to access registry directly
+        try {
+            const registry = router.getProviderRegistry();
+            registry.register(providerModule);
+            logger.info('Provider registered via registry fallback', {
+                provider: providerName,
+                totalProviders: router.listProviders().length
+            });
+        }
+        catch (registryError) {
+            logger.error('Failed to register provider via registry', {
+                provider: providerName,
+                error: registryError instanceof Error ? registryError.message : String(registryError)
+            });
+            throw registryError;
+        }
+    }
+}
+/**
+ * Unregister a provider
+ */
+export function unregisterProvider(providerName, router, logger) {
+    try {
+        // Try to access registry directly to remove the provider
+        const registry = router.getProviderRegistry();
+        // Since registry doesn't have an unregister method, we'll need to manipulate the map directly
+        // This is a bit hacky but necessary since the API doesn't provide unregister
+        const map = registry.map;
+        if (map && map instanceof Map) {
+            map.delete(providerName);
+            logger.info('Provider unregistered from registry', { provider: providerName });
+        }
+        else {
+            logger.warn('Could not access provider registry map for unregistration', { provider: providerName });
+        }
+    }
+    catch (error) {
+        logger.error('Failed to unregister provider', {
+            provider: providerName,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Get a provider module
+ */
+export function getProvider(providerName, router) {
+    try {
+        const registry = router.getProviderRegistry();
+        return registry.get(providerName);
+    }
+    catch (error) {
+        // Fallback to any access if registry access fails
+        return router.getProvider?.(providerName);
+    }
+}
+/**
+ * List all registered providers
+ */
+export function listProviders(router) {
+    return router.listProviders();
+}
+/**
+ * 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 function setDefaultProvider(provider, router, logger) {
+    // Router doesn't support changing default provider after initialization
+    // Default provider must be set in router config during initialization
+    logger.warn('setDefaultProvider called but router does not support changing default provider after initialization', {
+        provider,
+        note: 'Default provider must be set in router config during initialization'
+    });
+}
+/**
+ * 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 function setFallbackChain(chain, router, logger) {
+    // Router doesn't support changing fallback chain after initialization
+    // Fallback chain must be set in router config during initialization
+    logger.warn('setFallbackChain called but router does not support changing fallback chain after initialization', {
+        chain,
+        note: 'Fallback chain must be set in router config during initialization'
+    });
+}
+/**
+ * Add request interceptor
+ */
+export function addRequestInterceptor(interceptor, router) {
+    router.addRequestInterceptor(interceptor);
+}
+/**
+ * Add response interceptor
+ */
+export function addResponseInterceptor(interceptor, router) {
+    router.addResponseInterceptor(interceptor);
+}
+/**
+ * Check health of a provider
+ */
+export async function checkHealth(provider, router) {
+    return router.checkHealth(provider);
+}
+/**
+ * Check health of all providers
+ */
+export async function checkAllHealth(router) {
+    const providers = listProviders(router);
+    const results = {};
+    for (const provider of providers) {
+        try {
+            results[provider] = await router.checkHealth(provider);
+        }
+        catch (error) {
+            results[provider] = {
+                provider,
+                healthy: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    return results;
+}

package/dist/gateway-rate-limiter-constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Rate Limiter Constants
+ *
+ * Default values for rate limiting configuration.
+ * These defaults ensure the system works safely even if config is missing.
+ */
+/**
+ * Default minimum interval between API calls (in milliseconds)
+ * Used when rateLimit.defaultMinIntervalMs is not specified
+ */
+export declare const DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = 500;
+/**
+ * Default enabled state for rate limiting
+ * Used when rateLimit.enabled is not specified
+ */
+export declare const DEFAULT_RATE_LIMIT_ENABLED = true;

package/dist/gateway-rate-limiter-constants.js

@@ -0,0 +1,16 @@
+/**
+ * Rate Limiter Constants
+ *
+ * Default values for rate limiting configuration.
+ * These defaults ensure the system works safely even if config is missing.
+ */
+/**
+ * Default minimum interval between API calls (in milliseconds)
+ * Used when rateLimit.defaultMinIntervalMs is not specified
+ */
+export const DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = 500;
+/**
+ * Default enabled state for rate limiting
+ * Used when rateLimit.enabled is not specified
+ */
+export const DEFAULT_RATE_LIMIT_ENABLED = true;

package/dist/gateway-rate-limiter.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Gateway Rate Limiter
+ *
+ * Smart rate limiting for BETWEEN-CALLS (not retries).
+ *
+ * Two types of rate limiting in the system:
+ * 1. RETRY delays (in gateway-retry.ts) - Simple sleep, not smart. Used when retrying after errors.
+ * 2. BETWEEN-CALLS rate limiting (this class) - Smart, tracks last call time and only waits if needed.
+ *
+ * This class handles #2: it tracks when the last API call was made per provider
+ * and only waits if necessary to maintain minimum intervals between separate API calls.
+ * This prevents unnecessary delays when enough time has already passed.
+ */
+import type { Logxer } from '@x12i/logxer';
+/**
+ * Smart Rate Limiter (Between-Calls Only)
+ *
+ * Tracks the last API call time per provider and only waits if necessary.
+ * Supports per-provider rate limits with safe defaults.
+ *
+ * NOTE: This is for BETWEEN-CALLS rate limiting (smart).
+ * Retry delays are handled separately in gateway-retry.ts (simple sleep).
+ *
+ * This ensures minimum intervals between separate API calls regardless of what happens between them.
+ */
+export declare class GatewayRateLimiter {
+    private lastCallTimes;
+    private defaultMinIntervalMs;
+    private providerIntervals;
+    private logger?;
+    constructor(defaultMinIntervalMs?: number, providerIntervals?: Record<string, number>, logger?: Logxer);
+    /**
+     * Gets the minimum interval for a specific provider
+     * Falls back to default if provider-specific interval not set
+     */
+    private getMinIntervalForProvider;
+    /**
+     * Waits only if necessary to maintain the minimum interval between calls for a provider
+     * @param provider - Provider name (e.g., 'openai', 'grok')
+     * @returns Promise that resolves when it's safe to make the next call
+     */
+    waitIfNeeded(provider?: string): Promise<void>;
+    /**
+     * Records that an API call was made (call this after the API call completes)
+     * This ensures we track the actual call time, accounting for call duration
+     */
+    recordCall(provider?: string): void;
+    /**
+     * Gets the time since the last call for a provider
+     */
+    getTimeSinceLastCall(provider?: string): number;
+    /**
+     * Resets the rate limiter for a provider (useful for testing or reset scenarios)
+     */
+    reset(provider?: string): void;
+}

package/dist/gateway-rate-limiter.js

@@ -0,0 +1,107 @@
+/**
+ * Gateway Rate Limiter
+ *
+ * Smart rate limiting for BETWEEN-CALLS (not retries).
+ *
+ * Two types of rate limiting in the system:
+ * 1. RETRY delays (in gateway-retry.ts) - Simple sleep, not smart. Used when retrying after errors.
+ * 2. BETWEEN-CALLS rate limiting (this class) - Smart, tracks last call time and only waits if needed.
+ *
+ * This class handles #2: it tracks when the last API call was made per provider
+ * and only waits if necessary to maintain minimum intervals between separate API calls.
+ * This prevents unnecessary delays when enough time has already passed.
+ */
+import { sleep } from './gateway-retry.js';
+import { DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS } from './gateway-rate-limiter-constants.js';
+/**
+ * Smart Rate Limiter (Between-Calls Only)
+ *
+ * Tracks the last API call time per provider and only waits if necessary.
+ * Supports per-provider rate limits with safe defaults.
+ *
+ * NOTE: This is for BETWEEN-CALLS rate limiting (smart).
+ * Retry delays are handled separately in gateway-retry.ts (simple sleep).
+ *
+ * This ensures minimum intervals between separate API calls regardless of what happens between them.
+ */
+export class GatewayRateLimiter {
+    lastCallTimes = new Map(); // provider -> last call timestamp
+    defaultMinIntervalMs;
+    providerIntervals = new Map(); // provider -> min interval
+    logger;
+    constructor(defaultMinIntervalMs = DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, providerIntervals, logger) {
+        this.defaultMinIntervalMs = defaultMinIntervalMs;
+        this.logger = logger;
+        // Store per-provider intervals
+        if (providerIntervals) {
+            for (const [provider, interval] of Object.entries(providerIntervals)) {
+                this.providerIntervals.set(provider.toLowerCase(), interval);
+            }
+        }
+    }
+    /**
+     * Gets the minimum interval for a specific provider
+     * Falls back to default if provider-specific interval not set
+     */
+    getMinIntervalForProvider(provider) {
+        const providerKey = provider.toLowerCase();
+        return this.providerIntervals.get(providerKey) ?? this.defaultMinIntervalMs;
+    }
+    /**
+     * Waits only if necessary to maintain the minimum interval between calls for a provider
+     * @param provider - Provider name (e.g., 'openai', 'grok')
+     * @returns Promise that resolves when it's safe to make the next call
+     */
+    async waitIfNeeded(provider = 'global') {
+        const minIntervalMs = this.getMinIntervalForProvider(provider);
+        const now = Date.now();
+        const lastCallTime = this.lastCallTimes.get(provider) || 0;
+        const timeSinceLastCall = now - lastCallTime;
+        if (timeSinceLastCall < minIntervalMs) {
+            const waitTime = minIntervalMs - timeSinceLastCall;
+            this.logger?.debug('Rate limiting: waiting before API call', {
+                provider,
+                waitTimeMs: waitTime,
+                timeSinceLastCallMs: timeSinceLastCall,
+                minIntervalMs,
+                usingProviderSpecific: this.providerIntervals.has(provider.toLowerCase())
+            });
+            await sleep(waitTime);
+        }
+        else {
+            this.logger?.verbose('Rate limit OK: enough time has passed', {
+                provider,
+                timeSinceLastCallMs: timeSinceLastCall,
+                minIntervalMs,
+                usingProviderSpecific: this.providerIntervals.has(provider.toLowerCase())
+            });
+        }
+        // Record the call time (after waiting if needed)
+        this.lastCallTimes.set(provider, Date.now());
+    }
+    /**
+     * Records that an API call was made (call this after the API call completes)
+     * This ensures we track the actual call time, accounting for call duration
+     */
+    recordCall(provider = 'global') {
+        this.lastCallTimes.set(provider, Date.now());
+    }
+    /**
+     * Gets the time since the last call for a provider
+     */
+    getTimeSinceLastCall(provider = 'global') {
+        const lastCallTime = this.lastCallTimes.get(provider) || 0;
+        return Date.now() - lastCallTime;
+    }
+    /**
+     * Resets the rate limiter for a provider (useful for testing or reset scenarios)
+     */
+    reset(provider) {
+        if (provider) {
+            this.lastCallTimes.delete(provider);
+        }
+        else {
+            this.lastCallTimes.clear();
+        }
+    }
+}

package/dist/gateway-retry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Gateway Retry Module
+ * Handles retry logic for network and server errors
+ *
+ * NOTE: Retry delays use SIMPLE SLEEP (not smart rate limiting).
+ * Between-calls rate limiting is handled separately in gateway-rate-limiter.ts (smart).
+ */
+import type { RetryConfig } from './types.js';
+import type { LLMProviderRouter } from '@x12i/ai-providers-router';
+import type { Logxer } from '@x12i/logxer';
+/**
+ * Determines if an error is a network error (fetch failed, DNS, connectivity)
+ */
+export declare function isNetworkError(error: Error): boolean;
+/**
+ * Extracts HTTP status code from error message or error object properties
+ */
+export declare function extractHttpStatusCode(error: Error): number | undefined;
+/**
+ * Determines if an HTTP error should be retried
+ * Retryable: 429 (throttling), 5xx (server errors)
+ * Non-retryable: 4xx except 429 (client errors)
+ */
+export declare function isRetryableHttpError(error: Error, statusCode: number): boolean;
+/**
+ * Determines if an error should be retried
+ */
+export declare function isRetryableError(error: Error): boolean;
+/**
+ * Sleep helper for retry delays
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Invokes router with retry logic for network and server errors
+ * Returns response and retry metadata
+ */
+export declare function invokeWithRetry(routerRequest: any, retryConfig: RetryConfig, jobId: string, router: LLMProviderRouter, logger: Logxer): Promise<{
+    response: any;
+    retryMetadata?: {
+        retryCount: number;
+        retryAttempts: Array<{
+            attempt: number;
+            timestamp: number;
+            error: string;
+            errorType: string;
+            delayMs: number;
+        }>;
+    };
+}>;