@x12i/ai-gateway 7.9.1

package/dist-cjs/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-cjs/gateway-rate-limiter-constants.cjs

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Rate Limiter Constants
+ *
+ * Default values for rate limiting configuration.
+ * These defaults ensure the system works safely even if config is missing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = void 0;
+/**
+ * Default minimum interval between API calls (in milliseconds)
+ * Used when rateLimit.defaultMinIntervalMs is not specified
+ */
+exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = 500;
+/**
+ * Default enabled state for rate limiting
+ * Used when rateLimit.enabled is not specified
+ */
+exports.DEFAULT_RATE_LIMIT_ENABLED = true;

package/dist-cjs/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-cjs/gateway-rate-limiter.cjs

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewayRateLimiter = void 0;
+const gateway_retry_js_1 = require("./gateway-retry.cjs");
+const gateway_rate_limiter_constants_js_1 = require("./gateway-rate-limiter-constants.cjs");
+/**
+ * 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.
+ */
+class GatewayRateLimiter {
+    lastCallTimes = new Map(); // provider -> last call timestamp
+    defaultMinIntervalMs;
+    providerIntervals = new Map(); // provider -> min interval
+    logger;
+    constructor(defaultMinIntervalMs = gateway_rate_limiter_constants_js_1.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 (0, gateway_retry_js_1.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();
+        }
+    }
+}
+exports.GatewayRateLimiter = GatewayRateLimiter;

package/dist-cjs/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-cjs/gateway-retry.cjs

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNetworkError = isNetworkError;
+exports.extractHttpStatusCode = extractHttpStatusCode;
+exports.isRetryableHttpError = isRetryableHttpError;
+exports.isRetryableError = isRetryableError;
+exports.sleep = sleep;
+exports.invokeWithRetry = invokeWithRetry;
+/**
+ * Determines if an error is a network error (fetch failed, DNS, connectivity)
+ */
+function isNetworkError(error) {
+    const message = error.message.toLowerCase();
+    const networkPatterns = [
+        'fetch failed',
+        'network error',
+        'dns',
+        'connectivity',
+        'connection',
+        'econnrefused',
+        'enotfound',
+        'etimedout',
+        'econnreset',
+        'api endpoint unavailability'
+    ];
+    return networkPatterns.some(pattern => message.includes(pattern));
+}
+/**
+ * Extracts HTTP status code from error message or error object properties
+ */
+function extractHttpStatusCode(error) {
+    // Try to extract from error message
+    const statusMatch = error.message.match(/\b(4\d{2}|5\d{2})\b/);
+    if (statusMatch) {
+        return parseInt(statusMatch[1], 10);
+    }
+    // Try to extract from error object properties
+    const errorAny = error;
+    if (errorAny.statusCode) {
+        return errorAny.statusCode;
+    }
+    if (errorAny.status) {
+        return errorAny.status;
+    }
+    if (errorAny.response?.status) {
+        return errorAny.response.status;
+    }
+    return undefined;
+}
+/**
+ * Determines if an HTTP error should be retried
+ * Retryable: 429 (throttling), 5xx (server errors)
+ * Non-retryable: 4xx except 429 (client errors)
+ */
+function isRetryableHttpError(error, statusCode) {
+    // 429 (throttling) is retryable
+    if (statusCode === 429) {
+        return true;
+    }
+    // 5xx (server errors) are retryable
+    if (statusCode >= 500 && statusCode < 600) {
+        return true;
+    }
+    // 4xx (client errors) are NOT retryable except 429
+    return false;
+}
+/**
+ * Determines if an error should be retried
+ */
+function isRetryableError(error) {
+    // Network errors are always retryable
+    if (isNetworkError(error)) {
+        return true;
+    }
+    // Check HTTP status code
+    const statusCode = extractHttpStatusCode(error);
+    if (statusCode !== undefined) {
+        return isRetryableHttpError(error, statusCode);
+    }
+    // Timeout errors are retryable
+    if (error.name === 'TimeoutError' || error.message.toLowerCase().includes('timeout')) {
+        return true;
+    }
+    // Default: don't retry unknown errors
+    return false;
+}
+/**
+ * Sleep helper for retry delays
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Invokes router with retry logic for network and server errors
+ * Returns response and retry metadata
+ */
+async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger) {
+    const maxRetries = retryConfig.maxRetries ?? 3;
+    const initialDelay = retryConfig.initialDelay ?? 1000;
+    const maxDelay = retryConfig.maxDelay ?? 30000;
+    const backoffMultiplier = retryConfig.backoffMultiplier ?? 2;
+    const enableJitter = retryConfig.enableJitter ?? true;
+    const throttlingDelay = retryConfig.throttlingDelay ?? 5000;
+    let lastError;
+    const retryAttempts = [];
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const response = await router.invoke(routerRequest);
+            // Log success after retry if this wasn't the first attempt
+            if (attempt > 0) {
+                logger.info('Request succeeded after retry', {
+                    jobId,
+                    attempt: attempt + 1,
+                    totalAttempts: attempt + 1,
+                    retryCount: retryAttempts.length
+                });
+            }
+            // Return response with retry metadata if there were retries
+            if (retryAttempts.length > 0) {
+                return {
+                    response,
+                    retryMetadata: {
+                        retryCount: retryAttempts.length,
+                        retryAttempts
+                    }
+                };
+            }
+            return { response };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if error is retryable
+            if (!isRetryableError(lastError)) {
+                logger.debug('Non-retryable error, not retrying', {
+                    jobId,
+                    error: lastError.message,
+                    errorName: lastError.name,
+                    attempt: attempt + 1
+                });
+                throw lastError;
+            }
+            // If this was the last attempt, throw the error
+            if (attempt >= maxRetries) {
+                logger.warn('Max retries exceeded', {
+                    jobId,
+                    error: lastError.message,
+                    errorName: lastError.name,
+                    totalAttempts: attempt + 1,
+                    maxRetries
+                });
+                throw lastError;
+            }
+            // Calculate delay with exponential backoff
+            const baseDelay = initialDelay * Math.pow(backoffMultiplier, attempt);
+            let delay = Math.min(baseDelay, maxDelay);
+            // Add extra delay for throttling
+            const statusCode = extractHttpStatusCode(lastError);
+            if (statusCode === 429) {
+                delay += throttlingDelay;
+                logger.debug('Throttling detected, adding extra delay', {
+                    jobId,
+                    throttlingDelay,
+                    baseDelay: Math.round(delay - throttlingDelay)
+                });
+            }
+            // Add jitter if enabled
+            if (enableJitter) {
+                const jitter = Math.random() * delay * 0.3; // Up to 30% jitter
+                delay += jitter;
+            }
+            // Classify error type for logging
+            const errorType = isNetworkError(lastError)
+                ? 'network'
+                : statusCode !== undefined
+                    ? `http-${statusCode}`
+                    : 'timeout';
+            // Record retry attempt for activity tracking
+            retryAttempts.push({
+                attempt: attempt + 1,
+                timestamp: Date.now(),
+                error: lastError.message,
+                errorType,
+                delayMs: Math.round(delay)
+            });
+            logger.warn('Retrying request after error', {
+                jobId,
+                error: lastError.message,
+                errorName: lastError.name,
+                errorType,
+                attempt: attempt + 1,
+                maxRetries: maxRetries + 1,
+                delayMs: Math.round(delay),
+                statusCode
+            });
+            await sleep(delay);
+        }
+    }
+    // If we get here, all retries exhausted - throw error with retry metadata
+    const errorWithRetries = lastError;
+    errorWithRetries.retryMetadata = {
+        retryCount: retryAttempts.length,
+        retryAttempts
+    };
+    throw errorWithRetries;
+}

package/dist-cjs/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;
+        }>;
+    };
+}>;