npm-ai-hooks 2.0.2 → 2.0.3

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.quickValidateKeyFormat = exports.validateApiKeys = exports.validateApiKey = exports.getAllProviderInfo = exports.getProviderInfo = exports.getAllProviders = exports.getProviderModels = exports.PROVIDER_NAMES = exports.reset = exports.isInitialized = exports.getProvider = exports.getAvailableProviders = exports.removeProvider = exports.addProvider = exports.initAIHooks = exports.wrap = void 0;
+exports.quickValidateKeyFormat = exports.validateApiKeys = exports.validateApiKey = exports.getAllProviderInfo = exports.getProviderInfo = exports.getAllProviders = exports.getProviderModels = exports.PROVIDER_NAMES = exports.reset = exports.isInitialized = exports.getProviderChain = exports.getProvider = exports.getAvailableProviders = exports.removeProvider = exports.addProvider = exports.initAIHooks = exports.wrap = void 0;
 // src/index.ts
 var wrap_1 = require("./wrap");
 Object.defineProperty(exports, "wrap", { enumerable: true, get: function () { return wrap_1.wrap; } });
@@ -10,6 +10,7 @@ Object.defineProperty(exports, "addProvider", { enumerable: true, get: function
 Object.defineProperty(exports, "removeProvider", { enumerable: true, get: function () { return providers_1.removeProvider; } });
 Object.defineProperty(exports, "getAvailableProviders", { enumerable: true, get: function () { return providers_1.getAvailableProviders; } });
 Object.defineProperty(exports, "getProvider", { enumerable: true, get: function () { return providers_1.getProvider; } });
+Object.defineProperty(exports, "getProviderChain", { enumerable: true, get: function () { return providers_1.getProviderChain; } });
 Object.defineProperty(exports, "isInitialized", { enumerable: true, get: function () { return providers_1.isInitialized; } });
 Object.defineProperty(exports, "reset", { enumerable: true, get: function () { return providers_1.reset; } });
 // Export provider utilities

package/dist/cjs/providers/base/ProviderConfig.js

@@ -78,26 +78,51 @@ class ProviderManager {
     getAvailableProviders() {
         return Array.from(this.providers.keys());
     }
-    getProvider(name) {
+    /**
+     * Returns the full ordered list of providers to try for a given request.
+     * Order: explicit name → defaultProvider → openrouter → rest in registration order.
+     * Used by the fallback mechanism in wrap().
+     */
+    getProviderChain(name) {
         const available = this.getAvailableProviders();
         if (available.length === 0) {
             throw new Error('No providers initialized. Please initialize providers first.');
         }
-        // 1. If user specified provider and it's available
-        if (name && this.providerFunctions.has(name)) {
-            return { fn: this.providerFunctions.get(name), provider: name };
-        }
-        // 2. If default provider is specified and available
-        if (this.defaultProvider && this.providerFunctions.has(this.defaultProvider)) {
-            return { fn: this.providerFunctions.get(this.defaultProvider), provider: this.defaultProvider };
+        const seen = new Set();
+        const chain = [];
+        const push = (p) => {
+            if (!seen.has(p) && this.providerFunctions.has(p)) {
+                seen.add(p);
+                chain.push({ fn: this.providerFunctions.get(p), provider: p });
+            }
+        };
+        // 1. Explicitly requested provider goes first
+        if (name)
+            push(name);
+        // 2. Default provider next
+        if (this.defaultProvider)
+            push(this.defaultProvider);
+        // 3. OpenRouter preferred over generic providers
+        push('openrouter');
+        // 4. Rest in registration order
+        for (const p of available)
+            push(p);
+        return chain;
+    }
+    getProvider(name) {
+        const available = this.getAvailableProviders();
+        if (available.length === 0) {
+            throw new Error('No providers initialized. Please initialize providers first.');
         }
-        // 3. Prefer OpenRouter if available
-        if (this.providerFunctions.has('openrouter')) {
-            return { fn: this.providerFunctions.get('openrouter'), provider: 'openrouter' };
+        // If user explicitly requested a specific provider, it MUST be available
+        if (name) {
+            if (this.providerFunctions.has(name)) {
+                return { fn: this.providerFunctions.get(name), provider: name };
+            }
+            throw new Error(`Provider "${name}" is not initialized. Available providers: ${available.join(', ')}`);
         }
-        // 4. Use first available provider
-        const firstProvider = available[0];
-        return { fn: this.providerFunctions.get(firstProvider), provider: firstProvider };
+        const chain = this.getProviderChain();
+        return chain[0];
     }
     addProvider(config) {
         this.providers.set(config.provider, {

package/dist/cjs/providers/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.providerRegistry = exports.reset = exports.isInitialized = exports.removeProvider = exports.addProvider = exports.initAIHooks = void 0;
 exports.getAvailableProviders = getAvailableProviders;
 exports.getProvider = getProvider;
+exports.getProviderChain = getProviderChain;
 const errors_1 = require("../errors");
 const ProviderRegistry_1 = require("./base/ProviderRegistry");
 Object.defineProperty(exports, "providerRegistry", { enumerable: true, get: function () { return ProviderRegistry_1.providerRegistry; } });
@@ -80,3 +81,28 @@ function getProvider(name) {
     // 3. No valid keys found → throw error (single instruction, no fallback)
     throw new errors_1.AIHookError("NO_PROVIDER_FOUND", "No valid AI provider API key was found.\n\nAt least one provider API key is required in your .env file.\n\nPlease add one of the following to your .env (see .env.example for details):\n  - OPENAI_KEY\n  - OPENROUTER_KEY\n  - GROQ_KEY\n", undefined, "Reference .env.example for setup instructions.");
 }
+// Returns the full ordered provider chain for fallback (new system only)
+function getProviderChain(name) {
+    if ((0, init_1.isInitialized)()) {
+        return (0, init_1.getProviderChain)(name);
+    }
+    // Legacy fallback: wrap available providers into a chain
+    const available = getAvailableProviders();
+    const seen = new Set();
+    const chain = [];
+    const tryPush = (p) => {
+        if (!seen.has(p) && providers[p]) {
+            seen.add(p);
+            chain.push({ fn: providers[p], provider: p });
+        }
+    };
+    // Explicit name first
+    if (name)
+        tryPush(name);
+    // OpenRouter preferred
+    tryPush('openrouter');
+    // Rest in availability order
+    for (const p of available)
+        tryPush(p);
+    return chain;
+}

package/dist/cjs/providers/init.js

@@ -5,6 +5,7 @@ exports.addProvider = addProvider;
 exports.removeProvider = removeProvider;
 exports.getAvailableProviders = getAvailableProviders;
 exports.getProvider = getProvider;
+exports.getProviderChain = getProviderChain;
 exports.isInitialized = isInitialized;
 exports.reset = reset;
 const ProviderConfig_1 = require("./base/ProviderConfig");
@@ -75,6 +76,17 @@ function getProvider(name) {
     }
     return providerManager.getProvider(name);
 }
+/**
+ * Get the full ordered provider chain for fallback
+ * @param name - Optional preferred provider name (placed first)
+ * @returns Ordered array of {fn, provider} to try in sequence
+ */
+function getProviderChain(name) {
+    if (!providerManager) {
+        throw new Error('AI hooks not initialized. Call initAIHooks() first.');
+    }
+    return providerManager.getProviderChain(name);
+}
 /**
  * Check if AI hooks is initialized
  * @returns True if initialized

package/dist/cjs/wrap.js

@@ -42,78 +42,78 @@ function wrap(fn, options) {
             const textInput = isMultimodal ? input.text || '' : String(input);
             const imageData = isMultimodal ? input.image : undefined;
             const fileData = isMultimodal ? input.file : undefined;
-            // Step 1: get provider function and the actual provider name
-            const { fn: providerFn, provider: providerKey } = (0, providers_1.getProvider)(options.provider);
-            // Step 2: pick model: passed model or provider-specific default
-            const model = options.model || (providerKey in types_1.DEFAULT_MODEL ? types_1.DEFAULT_MODEL[providerKey] : undefined);
-            if (!model) {
-                throw new errors_1.AIHookError("NO_MODEL_FOUND", "No model found: You must specify a provider or pass a valid model.\n\nAt least one provider API key is required in your .env file.\n\nPlease add one of the following to your .env (see .env.example for details):\n  - OPENAI_KEY\n  - OPENROUTER_KEY\n  - GROQ_KEY\n", options.provider, "Reference .env.example for setup instructions.");
+            // Step 1: get the ordered provider chain for automatic fallback
+            const chain = (0, providers_1.getProviderChain)(options.provider);
+            if (chain.length === 0) {
+                throw new errors_1.AIHookError("NO_PROVIDER_FOUND", "No valid AI provider API key was found.\n\nAt least one provider API key is required.\n\nPlease call initAIHooks() with at least one provider configuration.", options.provider, "Call initAIHooks({ providers: [...] }) before using wrap().");
             }
-            // Step 3: build prompt with multimodal support
-            let prompt;
-            if (options.customPrompt) {
-                // Use custom prompt if provided
-                prompt = `${options.customPrompt}\n\n${textInput}`;
-                if (imageData) {
-                    prompt = `${prompt}\n\n[Image attached]`;
-                }
-                if (fileData) {
-                    prompt = `${prompt}\n\n[File: ${fileData.name}]`;
+            let lastError;
+            const startTime = Date.now();
+            for (const { fn: providerFn, provider: providerKey } of chain) {
+                // Step 2: pick model: passed model or provider-specific default
+                const model = options.model || (providerKey in types_1.DEFAULT_MODEL ? types_1.DEFAULT_MODEL[providerKey] : undefined);
+                if (!model) {
+                    // Skip providers with no resolvable model (shouldn't normally happen)
+                    continue;
                 }
-            }
-            else {
-                // Use built-in task prompt
-                prompt = buildPrompt(options.task, textInput, options.targetLanguage);
-                if (imageData) {
-                    prompt = `${prompt}\n\n[Image attached]`;
+                // Step 3: build prompt with multimodal support
+                let prompt;
+                if (options.customPrompt) {
+                    prompt = `${options.customPrompt}\n\n${textInput}`;
+                    if (imageData)
+                        prompt = `${prompt}\n\n[Image attached]`;
+                    if (fileData)
+                        prompt = `${prompt}\n\n[File: ${fileData.name}]`;
                 }
-                if (fileData) {
-                    prompt = `${prompt}\n\n[File: ${fileData.name}]`;
+                else {
+                    prompt = buildPrompt(options.task, textInput, options.targetLanguage);
+                    if (imageData)
+                        prompt = `${prompt}\n\n[Image attached]`;
+                    if (fileData)
+                        prompt = `${prompt}\n\n[File: ${fileData.name}]`;
                 }
-            }
-            const startTime = Date.now();
-            let output;
-            try {
-                output = await providerFn(prompt, model);
-            }
-            catch (err) {
-                if (err instanceof errors_1.AIHookError) {
-                    // For AIHookError, just re-throw it - it will be handled by the outer catch
-                    throw err;
+                try {
+                    const output = await providerFn(prompt, model);
+                    const endTime = Date.now();
+                    // Success — if we used a fallback provider, log it
+                    if (options.provider && providerKey !== options.provider) {
+                        console.warn(`[ai-hooks] ⚠️  Fell back to provider: ${providerKey} (original: ${options.provider} failed)`);
+                    }
+                    else if (!options.provider && chain[0].provider !== providerKey) {
+                        console.warn(`[ai-hooks] ⚠️  Fell back to provider: ${providerKey}`);
+                    }
+                    return {
+                        output,
+                        meta: {
+                            provider: providerKey,
+                            model,
+                            task: options.task,
+                            targetLanguage: options.targetLanguage,
+                            cached: false,
+                            estimatedCostUSD: 0.0,
+                            latencyMs: endTime - startTime,
+                            fallback: chain[0].provider !== providerKey
+                        }
+                    };
                 }
-                if (err instanceof Error) {
-                    throw new Error(`[ai-hooks] Unknown error calling provider: ${err.message}`);
+                catch (err) {
+                    lastError = err;
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    // Only log warning if there are more providers to try
+                    const idx = chain.findIndex(c => c.provider === providerKey);
+                    if (idx < chain.length - 1) {
+                        console.warn(`[ai-hooks] ⚠️  Provider "${providerKey}" failed (${errMsg}). Trying next provider...`);
+                    }
                 }
-                throw new Error(`[ai-hooks] Unknown non-error thrown by provider: ${String(err)}`);
             }
-            const endTime = Date.now();
-            return {
-                output,
-                meta: {
-                    provider: providerKey,
-                    model,
-                    cached: false,
-                    estimatedCostUSD: 0.0,
-                    latencyMs: endTime - startTime
-                }
-            };
+            // All providers exhausted — surface the last error
+            throw lastError;
         }
         catch (err) {
             if (err instanceof errors_1.AIHookError) {
-                // For AIHookError, just log the pretty message without the full error handling
+                // Log the pretty message for developer visibility, then re-throw
                 console.error(err.pretty());
-                // Return a mock response to prevent the demo from crashing
-                return {
-                    output: "Error occurred",
-                    meta: {
-                        provider: "unknown",
-                        model: "unknown",
-                        cached: false,
-                        estimatedCostUSD: 0.0,
-                        latencyMs: 0,
-                        error: true
-                    }
-                };
+                throw err;
             }
             handleError(err);
         }

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 export { wrap } from "./wrap";
-export { initAIHooks, addProvider, removeProvider, getAvailableProviders, getProvider, isInitialized, reset } from "./providers";
+export { initAIHooks, addProvider, removeProvider, getAvailableProviders, getProvider, getProviderChain, isInitialized, reset } from "./providers";
 // Export provider utilities
 export { PROVIDER_NAMES, getProviderModels, getAllProviders, getProviderInfo, getAllProviderInfo } from "./utils/providerInfo";
 // Export key validation utilities

package/dist/esm/providers/base/ProviderConfig.js

@@ -75,26 +75,51 @@ export class ProviderManager {
     getAvailableProviders() {
         return Array.from(this.providers.keys());
     }
-    getProvider(name) {
+    /**
+     * Returns the full ordered list of providers to try for a given request.
+     * Order: explicit name → defaultProvider → openrouter → rest in registration order.
+     * Used by the fallback mechanism in wrap().
+     */
+    getProviderChain(name) {
         const available = this.getAvailableProviders();
         if (available.length === 0) {
             throw new Error('No providers initialized. Please initialize providers first.');
         }
-        // 1. If user specified provider and it's available
-        if (name && this.providerFunctions.has(name)) {
-            return { fn: this.providerFunctions.get(name), provider: name };
-        }
-        // 2. If default provider is specified and available
-        if (this.defaultProvider && this.providerFunctions.has(this.defaultProvider)) {
-            return { fn: this.providerFunctions.get(this.defaultProvider), provider: this.defaultProvider };
+        const seen = new Set();
+        const chain = [];
+        const push = (p) => {
+            if (!seen.has(p) && this.providerFunctions.has(p)) {
+                seen.add(p);
+                chain.push({ fn: this.providerFunctions.get(p), provider: p });
+            }
+        };
+        // 1. Explicitly requested provider goes first
+        if (name)
+            push(name);
+        // 2. Default provider next
+        if (this.defaultProvider)
+            push(this.defaultProvider);
+        // 3. OpenRouter preferred over generic providers
+        push('openrouter');
+        // 4. Rest in registration order
+        for (const p of available)
+            push(p);
+        return chain;
+    }
+    getProvider(name) {
+        const available = this.getAvailableProviders();
+        if (available.length === 0) {
+            throw new Error('No providers initialized. Please initialize providers first.');
         }
-        // 3. Prefer OpenRouter if available
-        if (this.providerFunctions.has('openrouter')) {
-            return { fn: this.providerFunctions.get('openrouter'), provider: 'openrouter' };
+        // If user explicitly requested a specific provider, it MUST be available
+        if (name) {
+            if (this.providerFunctions.has(name)) {
+                return { fn: this.providerFunctions.get(name), provider: name };
+            }
+            throw new Error(`Provider "${name}" is not initialized. Available providers: ${available.join(', ')}`);
         }
-        // 4. Use first available provider
-        const firstProvider = available[0];
-        return { fn: this.providerFunctions.get(firstProvider), provider: firstProvider };
+        const chain = this.getProviderChain();
+        return chain[0];
     }
     addProvider(config) {
         this.providers.set(config.provider, {

package/dist/esm/providers/index.js

@@ -4,7 +4,7 @@ import { providerConfigs } from "./base/ProviderConfigs";
 import { BaseProvider } from "./base/BaseProvider";
 import { ClaudeProvider, GeminiProvider, OpenRouterProvider } from "./base/SpecializedProviders";
 // Import the new initialization system
-import { initAIHooks, addProvider, removeProvider, getAvailableProviders as getNewAvailableProviders, getProvider as getNewProvider, isInitialized, reset } from "./init";
+import { initAIHooks, addProvider, removeProvider, getAvailableProviders as getNewAvailableProviders, getProvider as getNewProvider, getProviderChain as getNewProviderChain, isInitialized, reset } from "./init";
 // Initialize all providers (legacy environment-based system)
 function initializeProviders() {
     // Standard providers using BaseProvider
@@ -69,6 +69,31 @@ export function getProvider(name) {
     // 3. No valid keys found → throw error (single instruction, no fallback)
     throw new AIHookError("NO_PROVIDER_FOUND", "No valid AI provider API key was found.\n\nAt least one provider API key is required in your .env file.\n\nPlease add one of the following to your .env (see .env.example for details):\n  - OPENAI_KEY\n  - OPENROUTER_KEY\n  - GROQ_KEY\n", undefined, "Reference .env.example for setup instructions.");
 }
+// Returns the full ordered provider chain for fallback (new system only)
+export function getProviderChain(name) {
+    if (isInitialized()) {
+        return getNewProviderChain(name);
+    }
+    // Legacy fallback: wrap available providers into a chain
+    const available = getAvailableProviders();
+    const seen = new Set();
+    const chain = [];
+    const tryPush = (p) => {
+        if (!seen.has(p) && providers[p]) {
+            seen.add(p);
+            chain.push({ fn: providers[p], provider: p });
+        }
+    };
+    // Explicit name first
+    if (name)
+        tryPush(name);
+    // OpenRouter preferred
+    tryPush('openrouter');
+    // Rest in availability order
+    for (const p of available)
+        tryPush(p);
+    return chain;
+}
 // Export the new initialization system
 export { initAIHooks, addProvider, removeProvider, isInitialized, reset };
 // Export the registry for advanced usage (legacy)

package/dist/esm/providers/init.js

@@ -66,6 +66,17 @@ export function getProvider(name) {
     }
     return providerManager.getProvider(name);
 }
+/**
+ * Get the full ordered provider chain for fallback
+ * @param name - Optional preferred provider name (placed first)
+ * @returns Ordered array of {fn, provider} to try in sequence
+ */
+export function getProviderChain(name) {
+    if (!providerManager) {
+        throw new Error('AI hooks not initialized. Call initAIHooks() first.');
+    }
+    return providerManager.getProviderChain(name);
+}
 /**
  * Check if AI hooks is initialized
  * @returns True if initialized

package/dist/esm/wrap.js

@@ -1,5 +1,5 @@
 // dotenv removed - using explicit provider initialization instead
-import { getProvider } from "./providers";
+import { getProviderChain } from "./providers";
 import { DEFAULT_MODEL } from "./types";
 import { AIHookError } from "./errors";
 function handleError(err) {
@@ -39,78 +39,78 @@ export function wrap(fn, options) {
             const textInput = isMultimodal ? input.text || '' : String(input);
             const imageData = isMultimodal ? input.image : undefined;
             const fileData = isMultimodal ? input.file : undefined;
-            // Step 1: get provider function and the actual provider name
-            const { fn: providerFn, provider: providerKey } = getProvider(options.provider);
-            // Step 2: pick model: passed model or provider-specific default
-            const model = options.model || (providerKey in DEFAULT_MODEL ? DEFAULT_MODEL[providerKey] : undefined);
-            if (!model) {
-                throw new AIHookError("NO_MODEL_FOUND", "No model found: You must specify a provider or pass a valid model.\n\nAt least one provider API key is required in your .env file.\n\nPlease add one of the following to your .env (see .env.example for details):\n  - OPENAI_KEY\n  - OPENROUTER_KEY\n  - GROQ_KEY\n", options.provider, "Reference .env.example for setup instructions.");
+            // Step 1: get the ordered provider chain for automatic fallback
+            const chain = getProviderChain(options.provider);
+            if (chain.length === 0) {
+                throw new AIHookError("NO_PROVIDER_FOUND", "No valid AI provider API key was found.\n\nAt least one provider API key is required.\n\nPlease call initAIHooks() with at least one provider configuration.", options.provider, "Call initAIHooks({ providers: [...] }) before using wrap().");
             }
-            // Step 3: build prompt with multimodal support
-            let prompt;
-            if (options.customPrompt) {
-                // Use custom prompt if provided
-                prompt = `${options.customPrompt}\n\n${textInput}`;
-                if (imageData) {
-                    prompt = `${prompt}\n\n[Image attached]`;
-                }
-                if (fileData) {
-                    prompt = `${prompt}\n\n[File: ${fileData.name}]`;
+            let lastError;
+            const startTime = Date.now();
+            for (const { fn: providerFn, provider: providerKey } of chain) {
+                // Step 2: pick model: passed model or provider-specific default
+                const model = options.model || (providerKey in DEFAULT_MODEL ? DEFAULT_MODEL[providerKey] : undefined);
+                if (!model) {
+                    // Skip providers with no resolvable model (shouldn't normally happen)
+                    continue;
                 }
-            }
-            else {
-                // Use built-in task prompt
-                prompt = buildPrompt(options.task, textInput, options.targetLanguage);
-                if (imageData) {
-                    prompt = `${prompt}\n\n[Image attached]`;
+                // Step 3: build prompt with multimodal support
+                let prompt;
+                if (options.customPrompt) {
+                    prompt = `${options.customPrompt}\n\n${textInput}`;
+                    if (imageData)
+                        prompt = `${prompt}\n\n[Image attached]`;
+                    if (fileData)
+                        prompt = `${prompt}\n\n[File: ${fileData.name}]`;
                 }
-                if (fileData) {
-                    prompt = `${prompt}\n\n[File: ${fileData.name}]`;
+                else {
+                    prompt = buildPrompt(options.task, textInput, options.targetLanguage);
+                    if (imageData)
+                        prompt = `${prompt}\n\n[Image attached]`;
+                    if (fileData)
+                        prompt = `${prompt}\n\n[File: ${fileData.name}]`;
                 }
-            }
-            const startTime = Date.now();
-            let output;
-            try {
-                output = await providerFn(prompt, model);
-            }
-            catch (err) {
-                if (err instanceof AIHookError) {
-                    // For AIHookError, just re-throw it - it will be handled by the outer catch
-                    throw err;
+                try {
+                    const output = await providerFn(prompt, model);
+                    const endTime = Date.now();
+                    // Success — if we used a fallback provider, log it
+                    if (options.provider && providerKey !== options.provider) {
+                        console.warn(`[ai-hooks] ⚠️  Fell back to provider: ${providerKey} (original: ${options.provider} failed)`);
+                    }
+                    else if (!options.provider && chain[0].provider !== providerKey) {
+                        console.warn(`[ai-hooks] ⚠️  Fell back to provider: ${providerKey}`);
+                    }
+                    return {
+                        output,
+                        meta: {
+                            provider: providerKey,
+                            model,
+                            task: options.task,
+                            targetLanguage: options.targetLanguage,
+                            cached: false,
+                            estimatedCostUSD: 0.0,
+                            latencyMs: endTime - startTime,
+                            fallback: chain[0].provider !== providerKey
+                        }
+                    };
                 }
-                if (err instanceof Error) {
-                    throw new Error(`[ai-hooks] Unknown error calling provider: ${err.message}`);
+                catch (err) {
+                    lastError = err;
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    // Only log warning if there are more providers to try
+                    const idx = chain.findIndex(c => c.provider === providerKey);
+                    if (idx < chain.length - 1) {
+                        console.warn(`[ai-hooks] ⚠️  Provider "${providerKey}" failed (${errMsg}). Trying next provider...`);
+                    }
                 }
-                throw new Error(`[ai-hooks] Unknown non-error thrown by provider: ${String(err)}`);
             }
-            const endTime = Date.now();
-            return {
-                output,
-                meta: {
-                    provider: providerKey,
-                    model,
-                    cached: false,
-                    estimatedCostUSD: 0.0,
-                    latencyMs: endTime - startTime
-                }
-            };
+            // All providers exhausted — surface the last error
+            throw lastError;
         }
         catch (err) {
             if (err instanceof AIHookError) {
-                // For AIHookError, just log the pretty message without the full error handling
+                // Log the pretty message for developer visibility, then re-throw
                 console.error(err.pretty());
-                // Return a mock response to prevent the demo from crashing
-                return {
-                    output: "Error occurred",
-                    meta: {
-                        provider: "unknown",
-                        model: "unknown",
-                        cached: false,
-                        estimatedCostUSD: 0.0,
-                        latencyMs: 0,
-                        error: true
-                    }
-                };
+                throw err;
             }
             handleError(err);
         }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { wrap } from "./wrap";
 export type { MultimodalInput } from "./wrap";
-export { initAIHooks, addProvider, removeProvider, getAvailableProviders, getProvider, isInitialized, reset } from "./providers";
+export { initAIHooks, addProvider, removeProvider, getAvailableProviders, getProvider, getProviderChain, isInitialized, reset } from "./providers";
 export type { Provider, ProviderModels, TaskType } from "./types";
 export type { OpenAIModel, ClaudeModel, GeminiModel, GroqModel, DeepSeekModel, XAIModel, MistralModel, PerplexityModel, OpenRouterModel } from "./types";
 export { PROVIDER_NAMES, getProviderModels, getAllProviders, getProviderInfo, getAllProviderInfo, type ProviderInfo } from "./utils/providerInfo";

package/dist/providers/base/ProviderConfig.d.ts

@@ -19,6 +19,15 @@ export declare class ProviderManager {
     private createProviderInstance;
     private getDefaultModelForProvider;
     getAvailableProviders(): Provider[];
+    /**
+     * Returns the full ordered list of providers to try for a given request.
+     * Order: explicit name → defaultProvider → openrouter → rest in registration order.
+     * Used by the fallback mechanism in wrap().
+     */
+    getProviderChain(name?: Provider): Array<{
+        fn: any;
+        provider: Provider;
+    }>;
     getProvider(name?: Provider): {
         fn: any;
         provider: Provider;

package/dist/providers/base/SpecializedProviders.d.ts

@@ -72,6 +72,7 @@ export declare class GeminiProvider extends BaseProvider {
         };
         formDataHeaderPolicy?: "legacy" | "content-only";
         redact?: string[];
+        sensitiveHeaders?: string[];
     };
     protected buildAuthHeaders(): Record<string, string>;
 }

package/dist/providers/index.d.ts

@@ -7,5 +7,9 @@ export declare function getProvider(name?: Provider): {
     fn: ProviderFunction<any>;
     provider: Provider | "mock";
 };
+export declare function getProviderChain(name?: Provider): Array<{
+    fn: ProviderFunction<any>;
+    provider: Provider;
+}>;
 export { initAIHooks, addProvider, removeProvider, isInitialized, reset, UserProviderConfig, ProviderInitializationOptions };
 export { providerRegistry };

package/dist/providers/init.d.ts

@@ -46,6 +46,15 @@ export declare function getProvider(name?: Provider): {
     fn: any;
     provider: Provider;
 };
+/**
+ * Get the full ordered provider chain for fallback
+ * @param name - Optional preferred provider name (placed first)
+ * @returns Ordered array of {fn, provider} to try in sequence
+ */
+export declare function getProviderChain(name?: Provider): Array<{
+    fn: any;
+    provider: Provider;
+}>;
 /**
  * Check if AI hooks is initialized
  * @returns True if initialized

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npm-ai-hooks",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Universal AI Hook Layer for Node.js and React – one wrapper for all AI providers. Inject LLM-like behavior into any JavaScript or TypeScript function with a single line, without writing prompts, handling SDKs, or locking into any provider.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -45,7 +45,7 @@
   "author": "AteebNoOne <ateebnoone@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "https://github.com/iTeebot/npm-ai-hooks.git"
+    "url": "git+https://github.com/iTeebot/npm-ai-hooks.git"
   },
   "license": "MIT",
   "dependencies": {
@@ -91,4 +91,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}