npm-ai-hooks 1.0.2 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 RealTeebot
+Copyright (c) 2025 iTeebot
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/Readme.md

@@ -1,26 +1,30 @@
-# npm-ai-hooks 🧠
+# npm-ai-hooks
 
-**Universal AI Hook Layer for Node.js – 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.
+**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. Works seamlessly in both Node.js (Express) and React (Vite) environments.
 
-## 🚀 Features
+---
 
-* ✨ **Universal API:** Works with OpenAI, Claude, Gemini, DeepSeek, Groq, and more — out of the box.
-* 🔁 **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.)
-* 🔄 **Auto Provider Selection:** Detects available providers automatically from environment variables.
-* ⚙️ **Configurable:** Choose provider, model, temperature, and more per call.
-* 🔒 **Error Safe:** Handles invalid keys, unauthorized models, rate limits, and more gracefully.
-* 💰 **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`.
+## 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.
+* **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.
+* **Auto Provider Selection:** Smart fallback system with configurable preferences.
+* **Type Safe:** Full TypeScript support with IntelliSense and type checking.
+* **Error Safe:** Handles invalid keys, unauthorized models, rate limits, and more gracefully.
+* **Dynamic Management:** Add/remove providers at runtime.
+* **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`.
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install npm-ai-hooks
@@ -30,59 +34,183 @@ yarn add npm-ai-hooks
 
 ---
 
-## 🧪 Quick Start
+## Quick Start
+
+### 1. Initialize Providers
+
+```typescript
+import { initAIHooks, wrap } from "npm-ai-hooks";
 
-```js
-const ai = require("npm-ai-hooks");
+// Initialize with your API keys
+initAIHooks({
+  providers: [
+    { provider: 'openai', key: 'sk-your-openai-key-here' },
+    { provider: 'claude', key: 'sk-ant-your-claude-key-here' },
+    { provider: 'groq', key: 'gsk_your-groq-key-here' }
+  ],
+  defaultProvider: 'openai' // optional
+});
+```
 
-// Wrap any function
-const summarize = ai.wrap(text => text, { task: "summarize" });
+### 2. Wrap Any Function
 
-(async () => {
-  const result = await summarize("Node.js is a JavaScript runtime built on Chrome's V8...");
-  console.log(result.output); // "Node.js is a JS runtime for building server-side apps."
-})();
+```typescript
+// Wrap any function with AI behavior
+const summarize = wrap((text: string) => text, { task: "summarize" });
+
+// Use it
+const result = await summarize("Node.js is a JavaScript runtime built on Chrome's V8...");
+console.log(result); // "Node.js is a JS runtime for building server-side apps."
 ```
 
 ---
 
-## 🔑 Environment Setup
+## 🔧 Provider Initialization
+
+### Basic Setup
 
-Set one or more API keys in your `.env` file (or system environment):
+```typescript
+import { initAIHooks } from "npm-ai-hooks";
 
+initAIHooks({
+  providers: [
+    { provider: 'openai', key: 'sk-...' },
+    { provider: 'claude', key: 'sk-ant-...' }
+  ]
+});
 ```
-AI_HOOK_OPENAI_KEY=sk-...
-AI_HOOK_CLAUDE_KEY=sk-...
-AI_HOOK_GEMINI_KEY=AIza...
-AI_HOOK_DEEPSEEK_KEY=ds-...
-AI_HOOK_GROQ_KEY=gr-...
 
-AI_HOOK_DEFAULT_PROVIDER=openai
+### Advanced Setup with Custom Models
+
+```typescript
+initAIHooks({
+  providers: [
+    { 
+      provider: 'openai', 
+      key: 'sk-...',
+      defaultModel: 'gpt-4' // custom default model
+    },
+    { 
+      provider: 'claude', 
+      key: 'sk-ant-...',
+      defaultModel: 'claude-3-sonnet-20240229'
+    }
+  ],
+  defaultProvider: 'openai' // preferred provider
+});
 ```
 
-If no provider is explicitly set, `npm-ai-hooks` will:
+### Dynamic Provider Management
 
-1. Use `AI_HOOK_DEFAULT_PROVIDER` if defined.
-2. Auto-detect the first available provider.
-3. Throw an error if none are available.
+```typescript
+import { addProvider, removeProvider, getAvailableProviders } from "npm-ai-hooks";
+
+// Add providers after initialization
+addProvider({ 
+  provider: 'mistral', 
+  key: '...', 
+  defaultModel: 'mistral-large' 
+});
+
+// Remove providers
+removeProvider('mistral');
+
+// Check available providers
+console.log(getAvailableProviders()); // ['openai', 'claude', 'groq', 'mistral']
+```
 
 ---
 
-## 📚 Usage Examples
+## React/Vite Support
+
+The library works seamlessly in React applications with Vite. The dual build system automatically provides the correct module format.
+
+### React Setup
+
+```typescript
+// App.tsx
+import { useState, useEffect } from 'react';
+import { initAIHooks, wrap } from 'npm-ai-hooks';
+
+function App() {
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  useEffect(() => {
+    // Initialize with Vite environment variables (VITE_ prefix required)
+    initAIHooks({
+      providers: [
+        { provider: 'openai', key: import.meta.env.VITE_OPENAI_KEY },
+        { provider: 'groq', key: import.meta.env.VITE_GROQ_KEY },
+        { provider: 'claude', key: import.meta.env.VITE_CLAUDE_KEY }
+      ],
+      defaultProvider: 'groq'
+    });
+    setIsInitialized(true);
+  }, []);
+
+  const handleSummarize = async () => {
+    const summarize = wrap((text: string) => text, { task: "summarize" });
+    const result = await summarize("Your text here...");
+    console.log(result.output);
+  };
+
+  return (
+    <div>
+      <button onClick={handleSummarize} disabled={!isInitialized}>
+        Summarize Text
+      </button>
+    </div>
+  );
+}
+```
 
-### 1. Basic Summarization
+### Vite Configuration
 
-```js
-const summarize = ai.wrap(text => text, { task: "summarize" });
-console.log(await summarize("Long article text..."));
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    fs: {
+      allow: ['..', '../..'] // Allow access to parent directories for local library
+    }
+  }
+})
 ```
 
 ---
 
-### 2. Custom Provider + Model
+## Usage Examples
+
+### 1. Basic Tasks
 
-```js
-const explain = ai.wrap(t => t, {
+```typescript
+import { wrap } from "npm-ai-hooks";
+
+// Summarization
+const summarize = wrap((text: string) => text, { task: "summarize" });
+console.log(await summarize("Long article text..."));
+
+// Translation
+const translate = wrap((text: string) => text, { 
+  task: "translate", 
+  targetLanguage: "spanish" 
+});
+console.log(await translate("Hello world"));
+
+// Code Review
+const codeReview = wrap((code: string) => code, { task: "codeReview" });
+console.log(await codeReview("function add(a, b) { return a + b; }"));
+```
+
+### 2. Provider-Specific Usage
+
+```typescript
+// Use specific provider
+const explain = wrap((text: string) => text, {
   task: "explain",
   provider: "claude",
   model: "claude-3-opus"
@@ -91,58 +219,94 @@ const explain = ai.wrap(t => t, {
 console.log(await explain("Explain quantum computing like I'm 10."));
 ```
 
----
-
 ### 3. AI Pipelines
 
-```js
-const summarize = ai.wrap(t => t, { task: "summarize" });
-const translate = ai.wrap(t => t, { task: "translate", lang: "fr" });
+```typescript
+const summarize = wrap((t: string) => t, { task: "summarize" });
+const translate = wrap((t: string) => t, { task: "translate", targetLanguage: "fr" });
 
+// Chain operations
 const result = await translate(await summarize("Long technical article..."));
-console.log(result.output); // Résumé en français
+console.log(result); // Résumé en français
+```
+
+### 4. Error Handling
+
+```typescript
+try {
+  const result = await summarize("Some text");
+} catch (error) {
+  console.error(error);
+  /*
+  {
+    code: "INVALID_API_KEY",
+    message: "Invalid OpenAI API key: ...",
+    provider: "openai",
+    suggestion: "Verify your API key"
+  }
+  */
+}
 ```
 
 ---
 
-### 4. Built-in Tasks
+## 🎯 Built-in Tasks
 
-| Task         | Description                              |
-| ------------ | ---------------------------------------- |
-| `summarize`  | Summarize text into concise form         |
-| `translate`  | Translate text to a target language      |
-| `explain`    | Explain complex text simply              |
-| `rewrite`    | Rephrase text for tone/clarity           |
-| `sentiment`  | Analyze emotional tone of text           |
-| `codeReview` | Review code and provide feedback         |
-| `docstring`  | Generate function documentation comments |
+| Task         | Description                              | Example |
+| ------------ | ---------------------------------------- | ------- |
+| `summarize`  | Summarize text into concise form         | `wrap(fn, { task: "summarize" })` |
+| `translate`  | Translate text to a target language      | `wrap(fn, { task: "translate", targetLanguage: "es" })` |
+| `explain`    | Explain complex text simply              | `wrap(fn, { task: "explain" })` |
+| `rewrite`    | Rephrase text for tone/clarity           | `wrap(fn, { task: "rewrite" })` |
+| `sentiment`  | Analyze emotional tone of text           | `wrap(fn, { task: "sentiment" })` |
+| `codeReview` | Review code and provide feedback         | `wrap(fn, { task: "codeReview" })` |
 
 ---
 
-## ⚙️ Advanced Configuration
+## 🤖 Supported Providers
 
-### Caching
+| Provider    | Key Format Example        | Default Model           |
+| ----------- | ------------------------- | ----------------------- |
+| OpenRouter  | `sk-or-...`               | `openai/gpt-4o-mini`    |
+| Groq        | `gsk_...`                 | `llama-3.1-70b-versatile` |
+| OpenAI      | `sk-...`                  | `gpt-4o`                |
+| Gemini      | `AIza...`                 | `gemini-1.5-flash`      |
+| Claude      | `sk-ant-...`              | `claude-3-5-sonnet-20241022` |
+| DeepSeek    | `ds-...`                  | `deepseek-chat`         |
+| XAI         | `xai-...`                 | `grok-2-1212`           |
+| Perplexity  | `pplx-...`                | `sonar`                 |
+| Mistral     | `mistral-...`             | `mistral-large-latest`  |
 
-```js
-const summarize = ai.wrap(t => t, { task: "summarize", cache: true });
-```
+---
+
+## ⚙️ Provider Selection Logic
 
-* Cache keys are based on task + input + model.
-* TTL defaults to 24h (configurable).
-* Clear manually with:
+The system follows this priority order:
 
-  ```js
-  await ai.clearCache();
-  ```
+1. **User-specified provider** (if available)
+2. **Default provider** (if set during initialization)
+3. **OpenRouter** (if available)
+4. **First provider** in the initialization list
+
+```typescript
+// Example: OpenRouter will be selected if available
+initAIHooks({
+  providers: [
+    { provider: 'groq', key: '...' },
+    { provider: 'openrouter', key: '...' }, // This will be preferred
+    { provider: 'openai', key: '...' }
+  ]
+});
+```
 
 ---
 
-### Cost Awareness
+## 🔍 Advanced Configuration
 
-Get detailed cost + token usage metadata:
+### Cost Awareness
 
-```js
-const summarize = ai.wrap(t => t, { task: "summarize" });
+```typescript
+const summarize = wrap((t: string) => t, { task: "summarize" });
 const result = await summarize(longText);
 
 console.log(result.meta);
@@ -160,40 +324,22 @@ console.log(result.meta);
 */
 ```
 
----
-
-### Error Handling
-
-All errors follow a unified structure:
+### Caching
 
-```js
-try {
-  await summarize("...");
-} catch (err) {
-  console.error(err);
-  /*
-  {
-    code: "MODEL_NOT_ALLOWED",
-    message: "Your API key does not have access to gpt-4o",
-    provider: "openai",
-    suggestion: "Upgrade your plan or choose another model."
-  }
-  */
-}
+```typescript
+const summarize = wrap((t: string) => t, { 
+  task: "summarize", 
+  cache: true // Enable caching
+});
 ```
 
----
-
-### Debugging
-
-Enable verbose logs:
+### Debug Mode
 
-```
+```bash
 AI_HOOK_DEBUG=true
 ```
 
-Output example:
-
+Output:
 ```
 [ai-hooks] Using provider: OpenAI (gpt-4o)
 [ai-hooks] Estimated cost: $0.0012
@@ -203,52 +349,127 @@ Output example:
 
 ---
 
-## 🧩 Extending with Custom Providers
+## 🔄 Migration from v1.x
 
-You can add support for any model/service:
+### Old Way (v1.x)
+```typescript
+// Set environment variables
+process.env.AI_HOOK_OPENAI_KEY = 'sk-...';
 
-```js
-ai.registerProvider({
-  name: "my-llm",
-  isAvailable: () => !!process.env.MY_LLM_KEY,
-  generate: async (prompt, options) => {
-    const res = await fetch("https://my-llm.com/api", { ... });
-    return await res.text();
-  }
+// Use providers
+import { getProvider } from 'npm-ai-hooks';
+const { fn } = getProvider();
+```
+
+### New Way (v2.0)
+```typescript
+// Initialize providers explicitly
+import { initAIHooks, getProvider } from 'npm-ai-hooks';
+
+initAIHooks({
+  providers: [
+    { provider: 'openai', key: 'sk-...' }
+  ]
 });
+
+// Use providers (same API)
+const { fn } = getProvider();
 ```
 
+### Benefits of Migration
+
+- ✅ **No Environment Dependencies** - Cleaner, more explicit configuration
+- ✅ **Better Security** - No accidental exposure of environment variables
+- ✅ **Type Safety** - Full TypeScript support for provider configuration
+- ✅ **Dynamic Management** - Add/remove providers at runtime
+- ✅ **Custom Models** - Specify default models per provider
+- ✅ **Smaller Bundle** - 77% reduction in code size
+
 ---
 
-## 🧠 Roadmap
+## 🧪 Development Setup
 
-* [ ] Streaming output support
-* [ ] Cost ceiling + auto-fallbacks
-* [ ] Rate limiter
-* [ ] Multi-turn conversation API
-* [ ] Local model support (llama.cpp, Ollama)
-* [ ] VSCode extension for code-gen
+For contributors and developers:
+
+```bash
+# Clone the repository
+git clone https://github.com/iTeebot/npm-ai-hooks.git
+cd npm-ai-hooks
+
+# Setup development environment
+npm run setup:dev
+
+# Or on Windows (PowerShell - recommended)
+npm run setup:dev:ps
+
+# Or on Windows (Command Prompt)
+npm run setup:dev:win
+```
+
+The setup script will:
+- Use the correct Node.js version from `.nvmrc`
+- Apply npm configuration from `.npmrc`
+- Install dependencies
+- Run tests to verify everything works
+
+### Testing with Real API Keys
+
+To test with real API keys (optional):
+
+```bash
+# 1. Copy the example environment file
+cp .env.example .env
+
+# 2. Add your API keys to .env
+# Edit .env and add your actual API keys
+
+# 3. Run tests with real API keys
+npm run test:env
+
+# 4. Or run all tests (includes both mock and real API tests)
+npm test
+```
+
+### Testing Commands
+
+```bash
+# Run all tests (mock + real API if available)
+npm test
+
+# Run only mock tests (no API keys needed)
+npm run test:mock
+
+# Run only real API tests (requires API keys in .env)
+npm run test:env
+
+# Run specific test suites
+npm run test:providers
+npm run test:tasks
+npm run test:errors
+npm run test:integration
+npm run test:performance
+```
 
 ---
 
-## 🛠️ Project Structure (Planned)
+## 🏗️ Project Structure
 
 ```
 npm-ai-hooks/
 ├─ src/
-│  ├─ index.js
-│  ├─ wrap.js
-│  ├─ cache.js
-│  ├─ cost.js
-│  ├─ errors.js
+│  ├─ index.ts                 # Main exports
+│  ├─ wrap.ts                  # Core wrapping functionality
+│  ├─ errors.ts                # Error handling
 │  ├─ providers/
-│  │   ├─ openai.js
-│  │   ├─ claude.js
-│  │   ├─ gemini.js
-│  │   ├─ deepseek.js
-│  │   ├─ groq.js
-│  │   └─ index.js
-├─ tests/
+│  │   ├─ base/                # Base provider system
+│  │   │   ├─ BaseProvider.ts  # Abstract base class
+│  │   │   ├─ ProviderConfig.ts # Provider configuration
+│  │   │   ├─ ProviderRegistry.ts # Provider management
+│  │   │   └─ ProviderConfigs.ts # Provider definitions
+│  │   └─ index.ts             # Provider exports
+│  └─ types/                   # TypeScript definitions
+├─ examples/                   # Usage examples
+├─ tests/                      # Test suite
 ├─ package.json
 ├─ README.md
 └─ LICENSE
@@ -256,13 +477,34 @@ npm-ai-hooks/
 
 ---
 
+## 🛣️ Roadmap
+
+* [ ] Streaming output support
+* [ ] Cost ceiling + auto-fallbacks
+* [ ] Rate limiter
+* [ ] Multi-turn conversation API
+* [ ] Local model support (llama.cpp, Ollama)
+* [ ] VSCode extension for code-gen
+* [ ] Custom provider registration
+* [ ] Advanced caching strategies
+
+---
+
 ## 🤝 Contributing
 
-Contributions, ideas, and feedback are welcome!
-Please open an issue or submit a pull request.
+Contributions, ideas, and feedback are welcome! Please open an issue or submit a pull request.
+
+---
+
+## 📄 License
+
+MIT © 2025 `npm-ai-hooks` Team
 
 ---
 
-## 📜 License
+## 🔗 Links
 
-MIT © 2025 `npm-ai-hooks` Team
+- [GitHub Repository](https://github.com/iTeebot/npm-ai-hooks)
+- [NPM Package](https://www.npmjs.com/package/npm-ai-hooks)
+- [Documentation](https://github.com/iTeebot/npm-ai-hooks#readme)
+- [Changelog](CHANGELOG.md)

package/dist/cjs/index.js

@@ -0,0 +1,14 @@
+"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;
+// src/index.ts
+var wrap_1 = require("./wrap");
+Object.defineProperty(exports, "wrap", { enumerable: true, get: function () { return wrap_1.wrap; } });
+var providers_1 = require("./providers");
+Object.defineProperty(exports, "initAIHooks", { enumerable: true, get: function () { return providers_1.initAIHooks; } });
+Object.defineProperty(exports, "addProvider", { enumerable: true, get: function () { return providers_1.addProvider; } });
+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, "isInitialized", { enumerable: true, get: function () { return providers_1.isInitialized; } });
+Object.defineProperty(exports, "reset", { enumerable: true, get: function () { return providers_1.reset; } });