npm-ai-hooks 2.0.0 → 2.0.1

package/Readme.md

@@ -4,12 +4,15 @@
 
 Inject LLM-like behavior into any JavaScript or TypeScript function with a single line, without writing prompts, handling SDKs, or locking into any provider. Works seamlessly in both Node.js (Express) and React (Vite) environments.
 
+📚 **[View Homepage & Demos](./website/)** | 🎮 **[React Example](./examples/react/)** | 💻 **[Node.js Example](./examples/demo.ts)**
+
 ---
 
 ## Features
 
 * **Universal API:** Works with OpenAI, Claude, Gemini, DeepSeek, Groq, OpenRouter, XAI, Perplexity, and Mistral — out of the box.
 * **Cross-Platform:** Works in both Node.js (Express) and React (Vite) environments with dual build system.
+* **Multimodal Support:** 🆕 Images, files, and voice input support with vision-enabled models.
 * **Plug & Play:** Wrap any function and instantly give it AI-powered behavior.
 * **Zero Prompting:** Built-in task templates (summarize, explain, translate, sentiment, rewrite, code-review, etc.)
 * **Explicit Configuration:** No environment variables needed - initialize providers explicitly with API keys.
@@ -20,7 +23,7 @@ Inject LLM-like behavior into any JavaScript or TypeScript function with a singl
 * **Cost Awareness:** Estimate and log token usage and cost before and after calls.
 * **Caching:** Prevents duplicate calls and charges by caching results intelligently.
 * **Extensible:** Add your own providers and custom tasks easily.
-* **Debug Friendly:** Full debug logging with `AI_HOOK_DEBUG=true`.
+* **Debug Friendly:** Full debug logging with `DEBUG=true`.
 
 ---
 
@@ -230,7 +233,106 @@ const result = await translate(await summarize("Long technical article..."));
 console.log(result); // Résumé en français
 ```
 
-### 4. Error Handling
+### 4. Multimodal Support (Images, Files, Voice) 🎨🎤
+
+**NEW!** npm-ai-hooks now supports multimodal inputs including images, files, and voice.
+
+```typescript
+import { wrap, MultimodalInput } from "npm-ai-hooks";
+import * as fs from 'fs';
+
+// Image Analysis
+const analyzeImage = wrap((input: MultimodalInput) => input, {
+  provider: 'openai',
+  model: 'gpt-4o', // Vision-enabled model
+  customPrompt: 'Describe what you see in this image'
+});
+
+// Load and encode image
+const imageBuffer = fs.readFileSync('./photo.jpg');
+const base64Image = `data:image/jpeg;base64,${imageBuffer.toString('base64')}`;
+
+const result = await analyzeImage({
+  text: 'What is in this image?',
+  image: base64Image
+});
+console.log(result.output); // Detailed image description
+
+// OCR (Text Extraction)
+const extractText = wrap((input: MultimodalInput) => input, {
+  provider: 'openai',
+  model: 'gpt-4o',
+  customPrompt: 'Extract all text from this image'
+});
+
+const ocrResult = await extractText({
+  text: 'Extract text from this document',
+  image: base64Image
+});
+
+// File Processing
+const analyzeFile = wrap((input: MultimodalInput) => input, {
+  provider: 'claude',
+  model: 'claude-3-opus',
+  task: 'summarize'
+});
+
+const fileBuffer = fs.readFileSync('./document.pdf');
+const fileResult = await analyzeFile({
+  text: 'Summarize this document',
+  file: {
+    name: 'document.pdf',
+    data: `data:application/pdf;base64,${fileBuffer.toString('base64')}`,
+    type: 'application/pdf'
+  }
+});
+```
+
+**Browser Voice Input (Web Speech API):**
+```typescript
+// In browser environment
+const SpeechRecognition = window.webkitSpeechRecognition || window.SpeechRecognition;
+const recognition = new SpeechRecognition();
+
+recognition.onresult = async (event) => {
+  const transcript = event.results[0][0].transcript;
+  
+  // Process voice input with AI
+  const explain = wrap((text: string) => text, { task: 'explain' });
+  const result = await explain(transcript);
+  console.log(result.output);
+};
+
+recognition.start();
+```
+
+**Multimodal Interface:**
+```typescript
+interface MultimodalInput {
+  text?: string;           // Text content
+  image?: string;          // Base64 encoded image (with data URI)
+  file?: {                 // File attachment
+    name: string;          // File name
+    data: string;          // Base64 encoded (with data URI)
+    type: string;          // MIME type
+  };
+}
+```
+
+**Use Cases:**
+- 📸 Image analysis and description
+- 📄 OCR and document processing
+- 🔍 Code review from screenshots
+- 🎤 Voice commands and transcription
+- 📊 Chart and diagram analysis
+- 🏷️ Product image tagging
+
+**See full examples:**
+- [Vision Examples](./examples/multimodal/vision-example.ts)
+- [Voice Examples](./examples/multimodal/voice-example.ts)
+- [React Demo with UI](./examples/react/)
+
+### 5. Error Handling
 
 ```typescript
 try {
@@ -336,7 +438,7 @@ const summarize = wrap((t: string) => t, {
 ### Debug Mode
 
 ```bash
-AI_HOOK_DEBUG=true
+DEBUG=true
 ```
 
 Output:
@@ -354,7 +456,7 @@ Output:
 ### Old Way (v1.x)
 ```typescript
 // Set environment variables
-process.env.AI_HOOK_OPENAI_KEY = 'sk-...';
+process.env.OPENAI_KEY = 'sk-...';
 
 // Use providers
 import { getProvider } from 'npm-ai-hooks';

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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; } });
@@ -12,3 +12,15 @@ Object.defineProperty(exports, "getAvailableProviders", { enumerable: true, get:
 Object.defineProperty(exports, "getProvider", { enumerable: true, get: function () { return providers_1.getProvider; } });
 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
+var providerInfo_1 = require("./utils/providerInfo");
+Object.defineProperty(exports, "PROVIDER_NAMES", { enumerable: true, get: function () { return providerInfo_1.PROVIDER_NAMES; } });
+Object.defineProperty(exports, "getProviderModels", { enumerable: true, get: function () { return providerInfo_1.getProviderModels; } });
+Object.defineProperty(exports, "getAllProviders", { enumerable: true, get: function () { return providerInfo_1.getAllProviders; } });
+Object.defineProperty(exports, "getProviderInfo", { enumerable: true, get: function () { return providerInfo_1.getProviderInfo; } });
+Object.defineProperty(exports, "getAllProviderInfo", { enumerable: true, get: function () { return providerInfo_1.getAllProviderInfo; } });
+// Export key validation utilities
+var keyValidator_1 = require("./utils/keyValidator");
+Object.defineProperty(exports, "validateApiKey", { enumerable: true, get: function () { return keyValidator_1.validateApiKey; } });
+Object.defineProperty(exports, "validateApiKeys", { enumerable: true, get: function () { return keyValidator_1.validateApiKeys; } });
+Object.defineProperty(exports, "quickValidateKeyFormat", { enumerable: true, get: function () { return keyValidator_1.quickValidateKeyFormat; } });

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

@@ -29,7 +29,7 @@ exports.providerConfigs = {
     openai: {
         name: "openai",
         baseUrl: "https://api.openai.com/v1/chat/completions",
-        envKey: "AI_HOOK_OPENAI_KEY",
+        envKey: "OPENAI_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.openaiStyle,
         responseParser: exports.responseParsers.openaiStyle,
@@ -46,7 +46,7 @@ exports.providerConfigs = {
     groq: {
         name: "groq",
         baseUrl: "https://api.groq.com/openai/v1/chat/completions",
-        envKey: "AI_HOOK_GROQ_KEY",
+        envKey: "GROQ_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.openaiStyle,
         responseParser: exports.responseParsers.openaiStyle,
@@ -63,7 +63,7 @@ exports.providerConfigs = {
     claude: {
         name: "claude",
         baseUrl: "https://api.anthropic.com/v1/messages",
-        envKey: "AI_HOOK_CLAUDE_KEY",
+        envKey: "CLAUDE_KEY",
         headers: {
             "Content-Type": "application/json",
             "anthropic-version": "2023-06-01"
@@ -83,7 +83,7 @@ exports.providerConfigs = {
     gemini: {
         name: "gemini",
         baseUrl: "https://generativelanguage.googleapis.com/v1beta/models",
-        envKey: "AI_HOOK_GEMINI_KEY",
+        envKey: "GEMINI_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.geminiStyle,
         responseParser: exports.responseParsers.geminiStyle,
@@ -100,7 +100,7 @@ exports.providerConfigs = {
     deepseek: {
         name: "deepseek",
         baseUrl: "https://api.deepseek.com/v1/chat/completions",
-        envKey: "AI_HOOK_DEEPSEEK_KEY",
+        envKey: "DEEPSEEK_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.openaiStyle,
         responseParser: exports.responseParsers.openaiStyle,
@@ -117,7 +117,7 @@ exports.providerConfigs = {
     mistral: {
         name: "mistral",
         baseUrl: "https://api.mistral.ai/v1/chat/completions",
-        envKey: "AI_HOOK_MISTRAL_KEY",
+        envKey: "MISTRAL_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.openaiStyle,
         responseParser: exports.responseParsers.openaiStyle,
@@ -134,7 +134,7 @@ exports.providerConfigs = {
     xai: {
         name: "xai",
         baseUrl: "https://api.x.ai/v1/chat/completions",
-        envKey: "AI_HOOK_XAI_KEY",
+        envKey: "XAI_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.openaiStyle,
         responseParser: exports.responseParsers.openaiStyle,
@@ -151,7 +151,7 @@ exports.providerConfigs = {
     perplexity: {
         name: "perplexity",
         baseUrl: "https://api.perplexity.ai/chat/completions",
-        envKey: "AI_HOOK_PERPLEXITY_KEY",
+        envKey: "PERPLEXITY_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.openaiStyle,
         responseParser: exports.responseParsers.openaiStyle,
@@ -168,7 +168,7 @@ exports.providerConfigs = {
     openrouter: {
         name: "openrouter",
         baseUrl: "https://openrouter.ai/api/v1/chat/completions",
-        envKey: "AI_HOOK_OPENROUTER_KEY",
+        envKey: "OPENROUTER_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: exports.requestBodyBuilders.openaiStyle,
         responseParser: exports.responseParsers.openaiStyle,

package/dist/cjs/providers/index.js

@@ -78,5 +78,5 @@ function getProvider(name) {
         return { fn: providers[available[0]], provider: available[0] };
     }
     // 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  - AI_HOOK_OPENAI_KEY\n  - AI_HOOK_OPENROUTER_KEY\n  - AI_HOOK_GROQ_KEY\n", undefined, "Reference .env.example for setup instructions.");
+    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.");
 }

package/dist/cjs/utils/keyValidator.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateApiKey = validateApiKey;
+exports.validateApiKeys = validateApiKeys;
+exports.quickValidateKeyFormat = quickValidateKeyFormat;
+const BaseProvider_1 = require("../providers/base/BaseProvider");
+const SpecializedProviders_1 = require("../providers/base/SpecializedProviders");
+const ProviderConfigs_1 = require("../providers/base/ProviderConfigs");
+/**
+ * Validates an API key by making a minimal test request to the provider
+ */
+async function validateApiKey(provider, apiKey) {
+    if (!apiKey || apiKey.trim() === '') {
+        return {
+            valid: false,
+            provider,
+            error: 'EMPTY_KEY',
+            message: 'API key is empty'
+        };
+    }
+    try {
+        let providerInstance;
+        // Create provider instance based on type
+        switch (provider) {
+            case 'claude':
+                providerInstance = new SpecializedProviders_1.ClaudeProvider();
+                break;
+            case 'gemini':
+                providerInstance = new SpecializedProviders_1.GeminiProvider();
+                break;
+            case 'openrouter':
+                providerInstance = new SpecializedProviders_1.OpenRouterProvider();
+                break;
+            default:
+                const config = ProviderConfigs_1.providerConfigs[provider];
+                if (!config) {
+                    return {
+                        valid: false,
+                        provider,
+                        error: 'UNKNOWN_PROVIDER',
+                        message: `Unknown provider: ${provider}`
+                    };
+                }
+                providerInstance = new BaseProvider_1.BaseProvider(config);
+        }
+        // Set the API key temporarily
+        providerInstance.apiKey = apiKey;
+        // Make a minimal test request
+        const testPrompt = "Hi";
+        const testModel = getDefaultModel(provider);
+        await providerInstance.call(testPrompt, testModel);
+        return {
+            valid: true,
+            provider,
+            message: 'API key is valid'
+        };
+    }
+    catch (error) {
+        // Check for common error types
+        if (error.message?.includes('401') || error.message?.includes('Unauthorized') || error.message?.includes('Invalid API key')) {
+            return {
+                valid: false,
+                provider,
+                error: 'INVALID_KEY',
+                message: 'API key is invalid or unauthorized'
+            };
+        }
+        if (error.message?.includes('403') || error.message?.includes('Forbidden')) {
+            return {
+                valid: false,
+                provider,
+                error: 'FORBIDDEN',
+                message: 'API key does not have access to this resource'
+            };
+        }
+        if (error.message?.includes('429') || error.message?.includes('rate limit')) {
+            // Rate limit means the key is valid, just too many requests
+            return {
+                valid: true,
+                provider,
+                message: 'API key is valid (rate limited)'
+            };
+        }
+        // If we get other errors, the key might still be valid (could be model/format issues)
+        return {
+            valid: true, // Assume valid unless we get clear auth error
+            provider,
+            message: 'API key appears valid (test request had non-auth error)'
+        };
+    }
+}
+/**
+ * Validates multiple API keys
+ */
+async function validateApiKeys(keys) {
+    const results = {};
+    for (const [provider, key] of Object.entries(keys)) {
+        if (key && key.trim()) {
+            results[provider] = await validateApiKey(provider, key);
+        }
+    }
+    return results;
+}
+/**
+ * Get default model for a provider (for testing)
+ */
+function getDefaultModel(provider) {
+    const defaultModels = {
+        openai: 'gpt-3.5-turbo',
+        claude: 'claude-3-haiku-20240307',
+        gemini: 'gemini-1.5-flash',
+        groq: 'llama-3.1-8b-instant',
+        deepseek: 'deepseek-chat',
+        xai: 'grok-beta',
+        mistral: 'mistral-small-latest',
+        perplexity: 'llama-3.1-sonar-small-128k-chat',
+        openrouter: 'openai/gpt-3.5-turbo'
+    };
+    return defaultModels[provider] || 'default';
+}
+/**
+ * Quick check if API key format looks valid (doesn't make API call)
+ */
+function quickValidateKeyFormat(provider, apiKey) {
+    if (!apiKey || apiKey.trim() === '') {
+        return {
+            valid: false,
+            provider,
+            error: 'EMPTY_KEY',
+            message: 'API key is empty'
+        };
+    }
+    // Check key format patterns
+    const patterns = {
+        openai: /^sk-[a-zA-Z0-9-_]{20,}$/,
+        claude: /^sk-ant-[a-zA-Z0-9-_]{20,}$/,
+        gemini: /^AIza[a-zA-Z0-9-_]{35}$/,
+        groq: /^gsk_[a-zA-Z0-9]{52}$/,
+        deepseek: /^sk-[a-zA-Z0-9]{32}$/,
+        xai: /^xai-[a-zA-Z0-9-_]{40,}$/,
+        mistral: /^[a-zA-Z0-9]{32}$/,
+        perplexity: /^pplx-[a-zA-Z0-9]{40}$/,
+        openrouter: /^sk-or-v1-[a-zA-Z0-9]{64}$/
+    };
+    const pattern = patterns[provider];
+    if (pattern && !pattern.test(apiKey)) {
+        return {
+            valid: false,
+            provider,
+            error: 'INVALID_FORMAT',
+            message: `API key format doesn't match expected pattern for ${provider}`
+        };
+    }
+    return {
+        valid: true,
+        provider,
+        message: 'API key format looks valid'
+    };
+}

package/dist/cjs/utils/providerInfo.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_NAMES = void 0;
+exports.getProviderModels = getProviderModels;
+exports.getAllProviders = getAllProviders;
+exports.getProviderInfo = getProviderInfo;
+exports.getAllProviderInfo = getAllProviderInfo;
+// Provider display names
+exports.PROVIDER_NAMES = {
+    openai: "OpenAI",
+    claude: "Claude",
+    gemini: "Gemini",
+    groq: "Groq",
+    deepseek: "DeepSeek",
+    xai: "xAI",
+    mistral: "Mistral",
+    perplexity: "Perplexity",
+    openrouter: "OpenRouter"
+};
+// Get all available models for a provider
+function getProviderModels(provider) {
+    // These are the actual model types from the library
+    const modelMap = {
+        openai: [
+            "gpt-4.1",
+            "gpt-4.1-mini",
+            "gpt-4o",
+            "gpt-4o-mini",
+            "gpt-4-turbo",
+            "gpt-4",
+            "gpt-3.5-turbo"
+        ],
+        claude: [
+            "claude-3-5-sonnet-20241022",
+            "claude-3-5-haiku-20241022",
+            "claude-3-opus-20240229",
+            "claude-3-sonnet-20240229",
+            "claude-3-haiku-20240307"
+        ],
+        gemini: [
+            "gemini-2.0-flash-exp",
+            "gemini-2.0-flash-thinking-exp-01-21",
+            "gemini-exp-1206",
+            "gemini-1.5-pro",
+            "gemini-1.5-flash",
+            "gemini-1.5-flash-8b"
+        ],
+        groq: [
+            "llama-3.3-70b-versatile",
+            "llama-3.1-8b-instant",
+            "gemma2-9b-it"
+        ],
+        deepseek: [
+            "deepseek-chat",
+            "deepseek-reasoner"
+        ],
+        xai: [
+            "grok-4-0131",
+            "grok-beta",
+            "grok-2-1212"
+        ],
+        mistral: [
+            "mistral-large-latest",
+            "mistral-small-latest",
+            "pixtral-large-latest",
+            "ministral-8b-latest",
+            "mistral-nemo"
+        ],
+        perplexity: [
+            "llama-3.1-sonar-large-128k-online",
+            "llama-3.1-sonar-small-128k-online",
+            "llama-3.1-sonar-large-128k-chat",
+            "llama-3.1-sonar-small-128k-chat"
+        ],
+        openrouter: [
+            "openai/gpt-4o",
+            "anthropic/claude-3.5-sonnet",
+            "google/gemini-2.0-flash-exp",
+            "meta-llama/llama-3.3-70b-instruct",
+            "deepseek/deepseek-chat"
+        ]
+    };
+    return modelMap[provider] || [];
+}
+// Get all supported providers
+function getAllProviders() {
+    return Object.keys(exports.PROVIDER_NAMES);
+}
+function getProviderInfo(provider) {
+    return {
+        key: provider,
+        name: exports.PROVIDER_NAMES[provider],
+        models: getProviderModels(provider)
+    };
+}
+function getAllProviderInfo() {
+    return getAllProviders().map(getProviderInfo);
+}

package/dist/cjs/wrap.js

@@ -34,16 +34,43 @@ function wrap(fn, options) {
     }
     return async (...args) => {
         try {
-            const input = fn(...args);
+            // Await the function result to handle both sync and async functions
+            const rawInput = fn(...args);
+            const input = rawInput instanceof Promise ? await rawInput : rawInput;
+            // Check if input is multimodal
+            const isMultimodal = typeof input === 'object' && input !== null && ('image' in input || 'file' in input);
+            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  - AI_HOOK_OPENAI_KEY\n  - AI_HOOK_OPENROUTER_KEY\n  - AI_HOOK_GROQ_KEY\n", options.provider, "Reference .env.example for setup instructions.");
+                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 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}]`;
+                }
+            }
+            else {
+                // Use built-in task prompt
+                prompt = buildPrompt(options.task, textInput, options.targetLanguage);
+                if (imageData) {
+                    prompt = `${prompt}\n\n[Image attached]`;
+                }
+                if (fileData) {
+                    prompt = `${prompt}\n\n[File: ${fileData.name}]`;
+                }
             }
-            // Step 3: build prompt
-            const prompt = buildPrompt(options.task, input, options.targetLanguage);
             const startTime = Date.now();
             let output;
             try {

package/dist/esm/index.js

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

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

@@ -26,7 +26,7 @@ export const providerConfigs = {
     openai: {
         name: "openai",
         baseUrl: "https://api.openai.com/v1/chat/completions",
-        envKey: "AI_HOOK_OPENAI_KEY",
+        envKey: "OPENAI_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.openaiStyle,
         responseParser: responseParsers.openaiStyle,
@@ -43,7 +43,7 @@ export const providerConfigs = {
     groq: {
         name: "groq",
         baseUrl: "https://api.groq.com/openai/v1/chat/completions",
-        envKey: "AI_HOOK_GROQ_KEY",
+        envKey: "GROQ_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.openaiStyle,
         responseParser: responseParsers.openaiStyle,
@@ -60,7 +60,7 @@ export const providerConfigs = {
     claude: {
         name: "claude",
         baseUrl: "https://api.anthropic.com/v1/messages",
-        envKey: "AI_HOOK_CLAUDE_KEY",
+        envKey: "CLAUDE_KEY",
         headers: {
             "Content-Type": "application/json",
             "anthropic-version": "2023-06-01"
@@ -80,7 +80,7 @@ export const providerConfigs = {
     gemini: {
         name: "gemini",
         baseUrl: "https://generativelanguage.googleapis.com/v1beta/models",
-        envKey: "AI_HOOK_GEMINI_KEY",
+        envKey: "GEMINI_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.geminiStyle,
         responseParser: responseParsers.geminiStyle,
@@ -97,7 +97,7 @@ export const providerConfigs = {
     deepseek: {
         name: "deepseek",
         baseUrl: "https://api.deepseek.com/v1/chat/completions",
-        envKey: "AI_HOOK_DEEPSEEK_KEY",
+        envKey: "DEEPSEEK_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.openaiStyle,
         responseParser: responseParsers.openaiStyle,
@@ -114,7 +114,7 @@ export const providerConfigs = {
     mistral: {
         name: "mistral",
         baseUrl: "https://api.mistral.ai/v1/chat/completions",
-        envKey: "AI_HOOK_MISTRAL_KEY",
+        envKey: "MISTRAL_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.openaiStyle,
         responseParser: responseParsers.openaiStyle,
@@ -131,7 +131,7 @@ export const providerConfigs = {
     xai: {
         name: "xai",
         baseUrl: "https://api.x.ai/v1/chat/completions",
-        envKey: "AI_HOOK_XAI_KEY",
+        envKey: "XAI_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.openaiStyle,
         responseParser: responseParsers.openaiStyle,
@@ -148,7 +148,7 @@ export const providerConfigs = {
     perplexity: {
         name: "perplexity",
         baseUrl: "https://api.perplexity.ai/chat/completions",
-        envKey: "AI_HOOK_PERPLEXITY_KEY",
+        envKey: "PERPLEXITY_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.openaiStyle,
         responseParser: responseParsers.openaiStyle,
@@ -165,7 +165,7 @@ export const providerConfigs = {
     openrouter: {
         name: "openrouter",
         baseUrl: "https://openrouter.ai/api/v1/chat/completions",
-        envKey: "AI_HOOK_OPENROUTER_KEY",
+        envKey: "OPENROUTER_KEY",
         headers: { "Content-Type": "application/json" },
         requestBody: requestBodyBuilders.openaiStyle,
         responseParser: responseParsers.openaiStyle,

package/dist/esm/providers/index.js

@@ -67,7 +67,7 @@ export function getProvider(name) {
         return { fn: providers[available[0]], provider: available[0] };
     }
     // 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  - AI_HOOK_OPENAI_KEY\n  - AI_HOOK_OPENROUTER_KEY\n  - AI_HOOK_GROQ_KEY\n", undefined, "Reference .env.example for setup instructions.");
+    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.");
 }
 // Export the new initialization system
 export { initAIHooks, addProvider, removeProvider, isInitialized, reset };

package/dist/esm/utils/keyValidator.js

@@ -0,0 +1,154 @@
+import { BaseProvider } from "../providers/base/BaseProvider";
+import { ClaudeProvider, GeminiProvider, OpenRouterProvider } from "../providers/base/SpecializedProviders";
+import { providerConfigs } from "../providers/base/ProviderConfigs";
+/**
+ * Validates an API key by making a minimal test request to the provider
+ */
+export async function validateApiKey(provider, apiKey) {
+    if (!apiKey || apiKey.trim() === '') {
+        return {
+            valid: false,
+            provider,
+            error: 'EMPTY_KEY',
+            message: 'API key is empty'
+        };
+    }
+    try {
+        let providerInstance;
+        // Create provider instance based on type
+        switch (provider) {
+            case 'claude':
+                providerInstance = new ClaudeProvider();
+                break;
+            case 'gemini':
+                providerInstance = new GeminiProvider();
+                break;
+            case 'openrouter':
+                providerInstance = new OpenRouterProvider();
+                break;
+            default:
+                const config = providerConfigs[provider];
+                if (!config) {
+                    return {
+                        valid: false,
+                        provider,
+                        error: 'UNKNOWN_PROVIDER',
+                        message: `Unknown provider: ${provider}`
+                    };
+                }
+                providerInstance = new BaseProvider(config);
+        }
+        // Set the API key temporarily
+        providerInstance.apiKey = apiKey;
+        // Make a minimal test request
+        const testPrompt = "Hi";
+        const testModel = getDefaultModel(provider);
+        await providerInstance.call(testPrompt, testModel);
+        return {
+            valid: true,
+            provider,
+            message: 'API key is valid'
+        };
+    }
+    catch (error) {
+        // Check for common error types
+        if (error.message?.includes('401') || error.message?.includes('Unauthorized') || error.message?.includes('Invalid API key')) {
+            return {
+                valid: false,
+                provider,
+                error: 'INVALID_KEY',
+                message: 'API key is invalid or unauthorized'
+            };
+        }
+        if (error.message?.includes('403') || error.message?.includes('Forbidden')) {
+            return {
+                valid: false,
+                provider,
+                error: 'FORBIDDEN',
+                message: 'API key does not have access to this resource'
+            };
+        }
+        if (error.message?.includes('429') || error.message?.includes('rate limit')) {
+            // Rate limit means the key is valid, just too many requests
+            return {
+                valid: true,
+                provider,
+                message: 'API key is valid (rate limited)'
+            };
+        }
+        // If we get other errors, the key might still be valid (could be model/format issues)
+        return {
+            valid: true, // Assume valid unless we get clear auth error
+            provider,
+            message: 'API key appears valid (test request had non-auth error)'
+        };
+    }
+}
+/**
+ * Validates multiple API keys
+ */
+export async function validateApiKeys(keys) {
+    const results = {};
+    for (const [provider, key] of Object.entries(keys)) {
+        if (key && key.trim()) {
+            results[provider] = await validateApiKey(provider, key);
+        }
+    }
+    return results;
+}
+/**
+ * Get default model for a provider (for testing)
+ */
+function getDefaultModel(provider) {
+    const defaultModels = {
+        openai: 'gpt-3.5-turbo',
+        claude: 'claude-3-haiku-20240307',
+        gemini: 'gemini-1.5-flash',
+        groq: 'llama-3.1-8b-instant',
+        deepseek: 'deepseek-chat',
+        xai: 'grok-beta',
+        mistral: 'mistral-small-latest',
+        perplexity: 'llama-3.1-sonar-small-128k-chat',
+        openrouter: 'openai/gpt-3.5-turbo'
+    };
+    return defaultModels[provider] || 'default';
+}
+/**
+ * Quick check if API key format looks valid (doesn't make API call)
+ */
+export function quickValidateKeyFormat(provider, apiKey) {
+    if (!apiKey || apiKey.trim() === '') {
+        return {
+            valid: false,
+            provider,
+            error: 'EMPTY_KEY',
+            message: 'API key is empty'
+        };
+    }
+    // Check key format patterns
+    const patterns = {
+        openai: /^sk-[a-zA-Z0-9-_]{20,}$/,
+        claude: /^sk-ant-[a-zA-Z0-9-_]{20,}$/,
+        gemini: /^AIza[a-zA-Z0-9-_]{35}$/,
+        groq: /^gsk_[a-zA-Z0-9]{52}$/,
+        deepseek: /^sk-[a-zA-Z0-9]{32}$/,
+        xai: /^xai-[a-zA-Z0-9-_]{40,}$/,
+        mistral: /^[a-zA-Z0-9]{32}$/,
+        perplexity: /^pplx-[a-zA-Z0-9]{40}$/,
+        openrouter: /^sk-or-v1-[a-zA-Z0-9]{64}$/
+    };
+    const pattern = patterns[provider];
+    if (pattern && !pattern.test(apiKey)) {
+        return {
+            valid: false,
+            provider,
+            error: 'INVALID_FORMAT',
+            message: `API key format doesn't match expected pattern for ${provider}`
+        };
+    }
+    return {
+        valid: true,
+        provider,
+        message: 'API key format looks valid'
+    };
+}

package/dist/esm/utils/providerInfo.js

@@ -0,0 +1,91 @@
+// Provider display names
+export const PROVIDER_NAMES = {
+    openai: "OpenAI",
+    claude: "Claude",
+    gemini: "Gemini",
+    groq: "Groq",
+    deepseek: "DeepSeek",
+    xai: "xAI",
+    mistral: "Mistral",
+    perplexity: "Perplexity",
+    openrouter: "OpenRouter"
+};
+// Get all available models for a provider
+export function getProviderModels(provider) {
+    // These are the actual model types from the library
+    const modelMap = {
+        openai: [
+            "gpt-4.1",
+            "gpt-4.1-mini",
+            "gpt-4o",
+            "gpt-4o-mini",
+            "gpt-4-turbo",
+            "gpt-4",
+            "gpt-3.5-turbo"
+        ],
+        claude: [
+            "claude-3-5-sonnet-20241022",
+            "claude-3-5-haiku-20241022",
+            "claude-3-opus-20240229",
+            "claude-3-sonnet-20240229",
+            "claude-3-haiku-20240307"
+        ],
+        gemini: [
+            "gemini-2.0-flash-exp",
+            "gemini-2.0-flash-thinking-exp-01-21",
+            "gemini-exp-1206",
+            "gemini-1.5-pro",
+            "gemini-1.5-flash",
+            "gemini-1.5-flash-8b"
+        ],
+        groq: [
+            "llama-3.3-70b-versatile",
+            "llama-3.1-8b-instant",
+            "gemma2-9b-it"
+        ],
+        deepseek: [
+            "deepseek-chat",
+            "deepseek-reasoner"
+        ],
+        xai: [
+            "grok-4-0131",
+            "grok-beta",
+            "grok-2-1212"
+        ],
+        mistral: [
+            "mistral-large-latest",
+            "mistral-small-latest",
+            "pixtral-large-latest",
+            "ministral-8b-latest",
+            "mistral-nemo"
+        ],
+        perplexity: [
+            "llama-3.1-sonar-large-128k-online",
+            "llama-3.1-sonar-small-128k-online",
+            "llama-3.1-sonar-large-128k-chat",
+            "llama-3.1-sonar-small-128k-chat"
+        ],
+        openrouter: [
+            "openai/gpt-4o",
+            "anthropic/claude-3.5-sonnet",
+            "google/gemini-2.0-flash-exp",
+            "meta-llama/llama-3.3-70b-instruct",
+            "deepseek/deepseek-chat"
+        ]
+    };
+    return modelMap[provider] || [];
+}
+// Get all supported providers
+export function getAllProviders() {
+    return Object.keys(PROVIDER_NAMES);
+}
+export function getProviderInfo(provider) {
+    return {
+        key: provider,
+        name: PROVIDER_NAMES[provider],
+        models: getProviderModels(provider)
+    };
+}
+export function getAllProviderInfo() {
+    return getAllProviders().map(getProviderInfo);
+}

package/dist/esm/wrap.js

@@ -31,16 +31,43 @@ export function wrap(fn, options) {
     }
     return async (...args) => {
         try {
-            const input = fn(...args);
+            // Await the function result to handle both sync and async functions
+            const rawInput = fn(...args);
+            const input = rawInput instanceof Promise ? await rawInput : rawInput;
+            // Check if input is multimodal
+            const isMultimodal = typeof input === 'object' && input !== null && ('image' in input || 'file' in input);
+            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  - AI_HOOK_OPENAI_KEY\n  - AI_HOOK_OPENROUTER_KEY\n  - AI_HOOK_GROQ_KEY\n", options.provider, "Reference .env.example for setup instructions.");
+                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 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}]`;
+                }
+            }
+            else {
+                // Use built-in task prompt
+                prompt = buildPrompt(options.task, textInput, options.targetLanguage);
+                if (imageData) {
+                    prompt = `${prompt}\n\n[Image attached]`;
+                }
+                if (fileData) {
+                    prompt = `${prompt}\n\n[File: ${fileData.name}]`;
+                }
             }
-            // Step 3: build prompt
-            const prompt = buildPrompt(options.task, input, options.targetLanguage);
             const startTime = Date.now();
             let output;
             try {

package/dist/index.d.ts

@@ -1,2 +1,7 @@
 export { wrap } from "./wrap";
+export type { MultimodalInput } from "./wrap";
 export { initAIHooks, addProvider, removeProvider, getAvailableProviders, getProvider, 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";
+export { validateApiKey, validateApiKeys, quickValidateKeyFormat, type KeyValidationResult } from "./utils/keyValidator";

package/dist/types/index.d.ts

@@ -7,6 +7,15 @@ import { DeepSeekModel } from "./deepseek";
 import { XAIModel } from "./xai";
 import { PerplexityModel } from "./perplexity";
 import { MistralModel } from "./mistral";
+export type { OpenAIModel } from "./openai";
+export type { OpenRouterModel } from "./openrouter";
+export type { GroqModel } from "./groq";
+export type { GeminiModel } from "./gemini";
+export type { ClaudeModel } from "./claude";
+export type { DeepSeekModel } from "./deepseek";
+export type { XAIModel } from "./xai";
+export type { PerplexityModel } from "./perplexity";
+export type { MistralModel } from "./mistral";
 export type Provider = "openrouter" | "groq" | "openai" | "gemini" | "claude" | "deepseek" | "xai" | "perplexity" | "mistral";
 export type ProviderModels = {
     openrouter: OpenRouterModel;
@@ -26,11 +35,13 @@ export type TaskType = "summarize" | "translate" | "explain" | "rewrite" | "sent
 export type WrapOptions<P extends Provider | undefined = undefined> = {
     provider: P extends Provider ? P : never;
     model?: P extends Provider ? ProviderModels[P] : never;
-    task: TaskType;
+    task?: TaskType;
     targetLanguage?: string;
+    customPrompt?: string;
 } | {
     provider?: never;
     model?: never;
-    task: TaskType;
+    task?: TaskType;
     targetLanguage?: string;
+    customPrompt?: string;
 };

package/dist/utils/keyValidator.d.ts

@@ -0,0 +1,19 @@
+import type { Provider } from "../types";
+export interface KeyValidationResult {
+    valid: boolean;
+    provider: Provider;
+    error?: string;
+    message: string;
+}
+/**
+ * Validates an API key by making a minimal test request to the provider
+ */
+export declare function validateApiKey(provider: Provider, apiKey: string): Promise<KeyValidationResult>;
+/**
+ * Validates multiple API keys
+ */
+export declare function validateApiKeys(keys: Record<Provider, string>): Promise<Record<Provider, KeyValidationResult>>;
+/**
+ * Quick check if API key format looks valid (doesn't make API call)
+ */
+export declare function quickValidateKeyFormat(provider: Provider, apiKey: string): KeyValidationResult;

package/dist/utils/providerInfo.d.ts

@@ -0,0 +1,11 @@
+import type { Provider } from "../types";
+export declare const PROVIDER_NAMES: Record<Provider, string>;
+export declare function getProviderModels(provider: Provider): string[];
+export declare function getAllProviders(): Provider[];
+export interface ProviderInfo {
+    key: Provider;
+    name: string;
+    models: string[];
+}
+export declare function getProviderInfo(provider: Provider): ProviderInfo;
+export declare function getAllProviderInfo(): ProviderInfo[];

package/dist/wrap.d.ts

@@ -1,4 +1,13 @@
 import { WrapOptions, Provider } from "./types";
+export interface MultimodalInput {
+    text?: string;
+    image?: string;
+    file?: {
+        name: string;
+        data: string;
+        type: string;
+    };
+}
 export declare function wrap<T extends (...args: any[]) => any, P extends Provider | undefined = undefined>(fn: T, options: WrapOptions<P>): (...args: Parameters<T>) => Promise<{
     output: string;
     meta: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npm-ai-hooks",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "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",
@@ -42,19 +42,6 @@
     "setup:dev:win": "scripts\\setup-dev.bat",
     "setup:dev:ps": "powershell -ExecutionPolicy Bypass -File scripts\\setup-dev.ps1"
   },
-  "keywords": [
-    "ai",
-    "hooks",
-    "llm",
-    "nodejs",
-    "typescript",
-    "openai",
-    "gemini",
-    "claude",
-    "deepseek",
-    "groq",
-    "mistral"
-  ],
   "author": "AteebNoOne <ateebnoone@gmail.com>",
   "repository": {
     "type": "git",