genai-lite 0.4.3 → 0.5.1

package/dist/shared/adapters/errorUtils.js

@@ -0,0 +1,107 @@
+"use strict";
+// AI Summary: Centralized error mapping utility for LLM client adapters.
+// Maps common HTTP status codes and network errors to standardized AdapterErrorCode and errorType.
+// Reduces duplication across OpenAI, Anthropic and other provider adapters.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommonMappedErrorDetails = getCommonMappedErrorDetails;
+const types_1 = require("../../llm/clients/types");
+/**
+ * Maps common error patterns to standardized error codes and types
+ *
+ * This utility handles:
+ * - Common HTTP status codes (401, 402, 404, 429, 4xx, 5xx)
+ * - Network connection errors (ENOTFOUND, ECONNREFUSED, timeouts)
+ * - Generic JavaScript errors
+ *
+ * Individual adapters can further refine the mappings for provider-specific cases,
+ * particularly for 400 errors where message content determines the specific error type.
+ *
+ * @param error - The error object from the provider SDK or network layer
+ * @param providerMessageOverride - Optional override for the error message (e.g., from provider SDK)
+ * @returns Mapped error details with standardized codes and types
+ */
+function getCommonMappedErrorDetails(error, providerMessageOverride) {
+    let errorCode = types_1.ADAPTER_ERROR_CODES.UNKNOWN_ERROR;
+    let errorMessage = providerMessageOverride || error?.message || 'Unknown error occurred';
+    let errorType = 'server_error';
+    let status;
+    // Handle API errors with HTTP status codes
+    if (error && typeof error.status === 'number') {
+        const httpStatus = error.status;
+        status = httpStatus;
+        errorMessage = providerMessageOverride || error.message || `HTTP ${httpStatus} error`;
+        // Map common HTTP status codes
+        // TypeScript knows httpStatus is defined here due to the typeof check above
+        switch (httpStatus) {
+            case 400:
+                // Default mapping for 400 errors - adapters should refine based on message content
+                errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                errorType = 'invalid_request_error';
+                break;
+            case 401:
+                errorCode = types_1.ADAPTER_ERROR_CODES.INVALID_API_KEY;
+                errorType = 'authentication_error';
+                break;
+            case 402:
+                errorCode = types_1.ADAPTER_ERROR_CODES.INSUFFICIENT_CREDITS;
+                errorType = 'rate_limit_error';
+                break;
+            case 404:
+                errorCode = types_1.ADAPTER_ERROR_CODES.MODEL_NOT_FOUND;
+                errorType = 'invalid_request_error';
+                break;
+            case 429:
+                errorCode = types_1.ADAPTER_ERROR_CODES.RATE_LIMIT_EXCEEDED;
+                errorType = 'rate_limit_error';
+                break;
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                errorType = 'server_error';
+                break;
+            default:
+                if (httpStatus >= 400 && httpStatus < 500) {
+                    errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                    errorType = 'invalid_request_error';
+                }
+                else if (httpStatus >= 500) {
+                    errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                    errorType = 'server_error';
+                }
+                else {
+                    errorCode = types_1.ADAPTER_ERROR_CODES.PROVIDER_ERROR;
+                    errorType = 'server_error';
+                }
+        }
+    }
+    // Handle network connection errors
+    else if (error && (error.code === 'ENOTFOUND' ||
+        error.code === 'ECONNREFUSED' ||
+        error.code === 'ETIMEDOUT' ||
+        error.name === 'ConnectTimeoutError' ||
+        (error.type && error.type.includes('timeout')))) {
+        errorCode = types_1.ADAPTER_ERROR_CODES.NETWORK_ERROR;
+        errorType = 'connection_error';
+        errorMessage = providerMessageOverride || error.message || 'Network connection failed';
+    }
+    // Handle generic JavaScript errors
+    else if (error instanceof Error) {
+        errorMessage = providerMessageOverride || error.message || 'Client error occurred';
+        errorCode = types_1.ADAPTER_ERROR_CODES.UNKNOWN_ERROR;
+        errorType = 'client_error';
+    }
+    // Handle unknown error types
+    else {
+        errorMessage = providerMessageOverride || 'Unknown error occurred';
+        errorCode = types_1.ADAPTER_ERROR_CODES.UNKNOWN_ERROR;
+        errorType = 'server_error';
+    }
+    return {
+        errorCode,
+        errorMessage,
+        errorType,
+        status
+    };
+}

package/dist/shared/services/AdapterRegistry.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Information about a registered adapter
+ */
+export interface AdapterInfo<TProviderId extends string> {
+    providerId: TProviderId;
+    hasAdapter: boolean;
+    adapterInfo?: {
+        name: string;
+    };
+}
+/**
+ * Summary of provider availability
+ */
+export interface ProviderSummary {
+    totalProviders: number;
+    providersWithAdapters: number;
+    availableProviders: string[];
+    unavailableProviders: string[];
+}
+/**
+ * Minimal provider information interface
+ */
+export interface MinimalProviderInfo<TProviderId extends string> {
+    id: TProviderId;
+    [key: string]: any;
+}
+/**
+ * Configuration for adapter initialization
+ */
+export interface AdapterRegistryConfig<TAdapter, TProviderId extends string> {
+    /** List of supported providers */
+    supportedProviders: readonly MinimalProviderInfo<TProviderId>[];
+    /** Map of provider IDs to adapter constructors */
+    adapterConstructors?: Partial<Record<string, new (config?: any) => TAdapter>>;
+    /** Map of provider IDs to adapter configurations */
+    adapterConfigs?: Record<string, any>;
+    /** Fallback adapter to use when no specific adapter is registered */
+    fallbackAdapter: TAdapter;
+    /** Optional custom adapters to register at initialization */
+    customAdapters?: Record<string, TAdapter>;
+}
+/**
+ * Generic registry for managing service adapters across different providers.
+ * Handles adapter initialization, registration, and retrieval.
+ *
+ * @template TAdapter - The adapter interface type
+ * @template TProviderId - The provider ID type (string union)
+ */
+export declare class AdapterRegistry<TAdapter, TProviderId extends string> {
+    private adapters;
+    private fallbackAdapter;
+    private supportedProviders;
+    /**
+     * Creates a new AdapterRegistry
+     *
+     * @param config - Configuration for the registry
+     */
+    constructor(config: AdapterRegistryConfig<TAdapter, TProviderId>);
+    /**
+     * Initializes adapters for all supported providers using constructors
+     */
+    private initializeAdapters;
+    /**
+     * Registers an adapter for a specific provider
+     *
+     * @param providerId - The provider ID
+     * @param adapter - The adapter implementation
+     */
+    registerAdapter(providerId: TProviderId, adapter: TAdapter): void;
+    /**
+     * Gets the appropriate adapter for a provider
+     *
+     * @param providerId - The provider ID
+     * @returns The adapter to use
+     */
+    getAdapter(providerId: TProviderId): TAdapter;
+    /**
+     * Gets information about registered adapters
+     *
+     * @returns Map of provider IDs to adapter info
+     */
+    getRegisteredAdapters(): Map<TProviderId, AdapterInfo<TProviderId>>;
+    /**
+     * Gets a summary of available providers and their adapter status
+     *
+     * @returns Summary of provider availability
+     */
+    getProviderSummary(): ProviderSummary;
+}

package/dist/shared/services/AdapterRegistry.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterRegistry = void 0;
+/**
+ * Generic registry for managing service adapters across different providers.
+ * Handles adapter initialization, registration, and retrieval.
+ *
+ * @template TAdapter - The adapter interface type
+ * @template TProviderId - The provider ID type (string union)
+ */
+class AdapterRegistry {
+    /**
+     * Creates a new AdapterRegistry
+     *
+     * @param config - Configuration for the registry
+     */
+    constructor(config) {
+        this.adapters = new Map();
+        this.fallbackAdapter = config.fallbackAdapter;
+        this.supportedProviders = config.supportedProviders;
+        // Register custom adapters first if provided
+        if (config.customAdapters) {
+            for (const [providerId, adapter] of Object.entries(config.customAdapters)) {
+                this.registerAdapter(providerId, adapter);
+            }
+        }
+        // Initialize adapters from constructors
+        if (config.adapterConstructors) {
+            this.initializeAdapters(config.adapterConstructors, config.adapterConfigs || {});
+        }
+    }
+    /**
+     * Initializes adapters for all supported providers using constructors
+     */
+    initializeAdapters(adapterConstructors, adapterConfigs) {
+        let registeredCount = 0;
+        const successfullyRegisteredProviders = [];
+        for (const provider of this.supportedProviders) {
+            const providerId = provider.id;
+            // Skip if adapter is already registered (from custom adapters)
+            if (this.adapters.has(providerId)) {
+                console.log(`AdapterRegistry: Skipping constructor initialization for '${provider.id}' ` +
+                    `(custom adapter already registered)`);
+                continue;
+            }
+            const AdapterClass = adapterConstructors[provider.id];
+            if (AdapterClass) {
+                try {
+                    const adapterConfig = adapterConfigs[provider.id];
+                    const adapterInstance = new AdapterClass(adapterConfig);
+                    this.registerAdapter(providerId, adapterInstance);
+                    registeredCount++;
+                    successfullyRegisteredProviders.push(provider.id);
+                }
+                catch (error) {
+                    console.error(`AdapterRegistry: Failed to instantiate adapter for provider '${provider.id}'. ` +
+                        `This provider will use the fallback adapter. Error:`, error);
+                }
+            }
+            else {
+                console.warn(`AdapterRegistry: No adapter constructor found for supported provider '${provider.id}'. ` +
+                    `This provider will use the fallback adapter.`);
+            }
+        }
+        if (registeredCount > 0) {
+            console.log(`AdapterRegistry: Initialized with ${registeredCount} dynamically registered adapter(s) ` +
+                `for: ${successfullyRegisteredProviders.join(', ')}.`);
+        }
+        else {
+            console.log(`AdapterRegistry: No real adapters were dynamically registered. ` +
+                `All providers will use the fallback adapter.`);
+        }
+    }
+    /**
+     * Registers an adapter for a specific provider
+     *
+     * @param providerId - The provider ID
+     * @param adapter - The adapter implementation
+     */
+    registerAdapter(providerId, adapter) {
+        this.adapters.set(providerId, adapter);
+        console.log(`AdapterRegistry: Registered adapter for provider: ${providerId}`);
+    }
+    /**
+     * Gets the appropriate adapter for a provider
+     *
+     * @param providerId - The provider ID
+     * @returns The adapter to use
+     */
+    getAdapter(providerId) {
+        // Check for registered real adapters first
+        const registeredAdapter = this.adapters.get(providerId);
+        if (registeredAdapter) {
+            console.log(`AdapterRegistry: Using registered adapter for provider: ${providerId}`);
+            return registeredAdapter;
+        }
+        // Fall back to fallback adapter for unsupported providers
+        console.log(`AdapterRegistry: No real adapter found for ${providerId}, using fallback adapter`);
+        return this.fallbackAdapter;
+    }
+    /**
+     * Gets information about registered adapters
+     *
+     * @returns Map of provider IDs to adapter info
+     */
+    getRegisteredAdapters() {
+        const adapterInfo = new Map();
+        for (const [providerId, adapter] of this.adapters.entries()) {
+            // Try to get adapter info if the adapter has a getAdapterInfo method
+            const adapterInfoData = adapter.getAdapterInfo?.() ||
+                { name: adapter.id || 'Unknown Adapter' };
+            adapterInfo.set(providerId, {
+                providerId,
+                hasAdapter: true,
+                adapterInfo: adapterInfoData,
+            });
+        }
+        return adapterInfo;
+    }
+    /**
+     * Gets a summary of available providers and their adapter status
+     *
+     * @returns Summary of provider availability
+     */
+    getProviderSummary() {
+        const availableProviders = [];
+        const unavailableProviders = [];
+        for (const provider of this.supportedProviders) {
+            if (this.adapters.has(provider.id)) {
+                availableProviders.push(provider.id);
+            }
+            else {
+                unavailableProviders.push(provider.id);
+            }
+        }
+        return {
+            totalProviders: this.supportedProviders.length,
+            providersWithAdapters: availableProviders.length,
+            availableProviders,
+            unavailableProviders,
+        };
+    }
+}
+exports.AdapterRegistry = AdapterRegistry;

package/dist/shared/services/PresetManager.d.ts

@@ -0,0 +1,33 @@
+import type { PresetMode } from "../../types";
+/**
+ * Generic preset manager for managing presets across different services.
+ * Handles loading, merging, and resolution of presets.
+ *
+ * @template TPreset - The preset type, must have an 'id' property
+ */
+export declare class PresetManager<TPreset extends {
+    id: string;
+}> {
+    private presets;
+    /**
+     * Creates a new PresetManager
+     *
+     * @param defaultPresets - The default presets to load
+     * @param customPresets - Optional custom presets to add or override
+     * @param mode - How to handle custom presets ('extend' or 'replace')
+     */
+    constructor(defaultPresets: TPreset[], customPresets?: TPreset[], mode?: PresetMode);
+    /**
+     * Gets all configured presets
+     *
+     * @returns Array of presets
+     */
+    getPresets(): TPreset[];
+    /**
+     * Resolves a preset by ID
+     *
+     * @param presetId - The preset ID to resolve
+     * @returns The preset if found, null otherwise
+     */
+    resolvePreset(presetId: string): TPreset | null;
+}

package/dist/shared/services/PresetManager.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PresetManager = void 0;
+/**
+ * Generic preset manager for managing presets across different services.
+ * Handles loading, merging, and resolution of presets.
+ *
+ * @template TPreset - The preset type, must have an 'id' property
+ */
+class PresetManager {
+    /**
+     * Creates a new PresetManager
+     *
+     * @param defaultPresets - The default presets to load
+     * @param customPresets - Optional custom presets to add or override
+     * @param mode - How to handle custom presets ('extend' or 'replace')
+     */
+    constructor(defaultPresets, customPresets = [], mode = 'extend') {
+        // Initialize presets based on mode
+        const finalPresets = new Map();
+        if (mode === 'replace') {
+            // Replace Mode: Only use custom presets.
+            for (const preset of customPresets) {
+                finalPresets.set(preset.id, preset);
+            }
+        }
+        else {
+            // Extend Mode: Load defaults first, then add/override.
+            for (const preset of defaultPresets) {
+                finalPresets.set(preset.id, preset);
+            }
+            for (const preset of customPresets) {
+                finalPresets.set(preset.id, preset);
+            }
+        }
+        this.presets = Array.from(finalPresets.values());
+    }
+    /**
+     * Gets all configured presets
+     *
+     * @returns Array of presets
+     */
+    getPresets() {
+        return [...this.presets]; // Return a copy to prevent external modification
+    }
+    /**
+     * Resolves a preset by ID
+     *
+     * @param presetId - The preset ID to resolve
+     * @returns The preset if found, null otherwise
+     */
+    resolvePreset(presetId) {
+        return this.presets.find(p => p.id === presetId) || null;
+    }
+}
+exports.PresetManager = PresetManager;