npm-ai-hooks 1.0.0 → 1.0.1

package/.env.example

@@ -0,0 +1,14 @@
+# OpenAI API key (for OpenRouter OpenAI models or standalone OpenAI)
+AI_HOOK_OPENAI_KEY=your_openai_api_key_here
+
+# OpenRouter API key
+AI_HOOK_OPENROUTER_KEY=your_openrouter_api_key_here
+
+# Groq API key
+AI_HOOK_GROQ_KEY=your_groq_api_key_here
+
+# Default provider (optional)
+# AI_HOOK_DEFAULT_PROVIDER=openrouter
+
+# Default model is handled by code, so no need to set it here
+# AI_HOOK_DEFAULT_MODEL=

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+```md
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Using welcoming and inclusive language  
+- Being respectful of differing viewpoints and experiences  
+- Gracefully accepting constructive criticism  
+- Focusing on what is best for the community  
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior include:
+
+- Harassment of public or private forms  
+- Trolling, insulting/derogatory comments  
+- Publishing others’ private information without permission  
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive behavior may be reported to the maintainers via [issues](https://github.com/RealTeebot/npm-ai-hooks/issues).  
+All complaints will be reviewed and addressed appropriately.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/).

package/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to npm-ai-hooks
+
+👋 Thanks for your interest in contributing to **npm-ai-hooks**!  
+This project is maintained by the [RealTeebot](https://github.com/RealTeebot) organization and welcomes community involvement at all levels — from bug fixes and documentation to major feature development.
+
+---
+
+## 🛠️ Development Setup
+
+1. **Fork** the repository and clone your fork:
+
+```bash
+git clone https://github.com/your-username/npm-ai-hooks.git
+cd npm-ai-hooks
+
+npm install
+
+npm run dev
+
+npm run test
+
+npm-ai-hooks/
+├─ src/
+│  ├─ index.ts          # Main entry
+│  ├─ wrap.ts           # Core hook wrapper logic
+│  ├─ cache.ts          # Caching engine
+│  ├─ cost.ts           # Cost estimation utilities
+│  ├─ errors.ts         # Unified error handling
+│  ├─ providers/        # Provider adapters
+│  │   ├─ openai.ts
+│  │   ├─ claude.ts
+│  │   └─ ...
+├─ examples/
+│  ├─ node-basic/
+│  └─ react-basic/
+├─ tests/
+└─ ...
+
+✨ Contributing Guidelines
+
+TypeScript Only: All code must be written in TypeScript with strict typing enabled.
+
+Linting: Run npm run lint before committing.
+
+Formatting: Code must pass Prettier formatting checks.
+
+Commit Style: Use Conventional Commits
+ (e.g., feat: add caching to DeepSeek provider).
+
+Tests: Add unit/integration tests for any new features or bug fixes.
+
+📦 Adding a New Provider
+
+Create a new file in src/providers/ (e.g., mistral.ts)
+
+Implement the required interface:
+
+export const mistralProvider: Provider = {
+  name: "mistral",
+  isAvailable: () => !!process.env.AI_HOOK_MISTRAL_KEY,
+  generate: async (prompt, options) => { /* API call logic */ },
+  models: ["mistral-medium", "mistral-large"]
+};
+
+
+Register the provider in providers/index.ts
+
+Add documentation and tests.
+
+🧪 Testing
+
+We use Jest for unit testing and Playwright for integration tests where relevant.
+
+npm run test
+npm run test:watch
+
+📣 Communication
+
+Issues: GitHub Issues
+
+Discussions: GitHub Discussions
+
+Pull Requests: Always create a PR to the main branch
+
+🙏 Credits
+
+Maintained with ❤️ by RealTeebot
+ and contributors.

package/EXAMPLES.md

@@ -0,0 +1,53 @@
+7. EXAMPLES.md
+# Usage Examples – npm-ai-hooks
+
+## 🧠 In a React Frontend
+
+Install:
+
+```bash
+npm install npm-ai-hooks
+
+
+Example:
+
+import { wrap } from "npm-ai-hooks";
+
+const summarize = wrap((text: string) => text, { task: "summarize" });
+
+export function App() {
+  const [result, setResult] = useState("");
+
+  const handleClick = async () => {
+    const res = await summarize("Explain server components in React.");
+    setResult(res.output);
+  };
+
+  return (
+    <div>
+      <button onClick={handleClick}>Summarize</button>
+      <p>{result}</p>
+    </div>
+  );
+}
+
+⚙️ In a Node.js Backend
+import { wrap } from "npm-ai-hooks";
+
+const explain = wrap((input: string) => input, { task: "explain" });
+
+app.post("/explain", async (req, res) => {
+  const result = await explain(req.body.text);
+  res.json(result);
+});
+
+
+This works with Express, NestJS, Fastify, Next.js API routes — anything Node-compatible.
+
+
+---
+
+
+---
+
+✅ **With these files in place**, your repository will be structured like a professional, enterprise-ready open-source project:

package/ROADMAP.md

@@ -0,0 +1,22 @@
+# Roadmap – npm-ai-hooks
+
+✅ v0.1.0 (MVP)
+- [x] Basic `wrap()` functionality
+- [x] OpenAI + Claude support
+- [x] Error handling and cost estimation
+- [x] Caching layer
+
+🚀 v0.2.0
+- [ ] Provider auto-discovery CLI
+- [ ] More built-in tasks (e.g., classify, code explain)
+- [ ] React hook wrapper (`useAI`)
+
+💡 v0.3.0
+- [ ] Streaming support
+- [ ] Local model support (Ollama / Llama.cpp)
+- [ ] SDK for Python (bridge)
+
+🧠 Long-Term Vision
+- Unified dashboard for usage + cost
+- Plugin ecosystem (community providers, custom tasks)
+- Serverless deployment starter template

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported Versions
+
+We actively support the latest major release and security patches for the previous one.
+
+| Version | Supported |
+|--------|-----------|
+| 1.x.x  | ✅        |
+| 0.x.x  | ❌        |
+
+---
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, **DO NOT** open a public GitHub issue.
+
+Instead, please report it privately by emailing:  
+**security@realteebot.dev**
+
+We take all security issues seriously and will respond within 48 hours.
+
+---
+
+## Disclosure Process
+
+1. We confirm and investigate the vulnerability.
+2. We create a patch and test the fix.
+3. We coordinate a release and notify users.
+4. We credit the reporter (if they wish).

package/examples/basic/explain.ts

@@ -0,0 +1,18 @@
+import { wrap } from "../../src/wrap";
+
+const explain = wrap((text: string) => text, { task: "explain" });
+
+async function run() {
+  try {
+    const result = await explain("Quantum computing is complex.");
+    console.log(result.output);
+  } catch (err: any) {
+    if (err && typeof err.pretty === "function") {
+      err.pretty();
+    } else {
+      console.error(err.message || err);
+    }
+  }
+}
+
+run();

package/examples/basic/rewrite.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const rewrite = wrap((text: string) => text, { task: "rewrite" });
+
+async function run() {
+  const result = await rewrite("AI code can sometimes be confusing.");
+  console.log(result.output);
+}
+
+run();

package/examples/basic/sentiment.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const sentiment = wrap((text: string) => text, { task: "sentiment" });
+
+async function run() {
+  const result = await sentiment("I love using AI-Hooks for my projects!");
+  console.log(result.output);
+}
+
+run();

package/examples/basic/summarize.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const summarize = wrap((text: string) => text, { task: "summarize" });
+
+async function run() {
+  const result = await summarize("OpenRouter is a powerful AI integration tool.");
+  console.log(result.output);
+}
+
+run();

package/examples/basic/translate.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const translate = wrap((text: string) => text, { task: "translate", targetLanguage: "Urdu" });
+
+async function run() {
+  const result = await translate("Hello everyone! Welcome to AI demos.");
+  console.log(result.output);
+}
+
+run();

package/examples/demo.ts

@@ -0,0 +1,16 @@
+import { wrap } from "../src";
+
+const summarize = wrap((text: string) => text, { task: "summarize" });
+
+(async () => {
+  try {
+    const result = await summarize("Gemini is made by..");
+    console.log(result.output);
+  } catch (err: any) {
+    if (err.pretty) {
+      err.pretty(); // prints nice error with suggestions
+    } else {
+      console.error(err);
+    }
+  }
+})();

package/examples/model-switch/groq-default.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const explain = wrap((text: string) => text, { task: "explain", provider: "groq" });
+
+async function run() {
+  const result = await explain("Groq provides fast text AI models.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/groq-text2.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const explain = wrap((text: string) => text, { task: "explain", provider: "groq", model: "allam-2-7b" });
+
+async function run() {
+  const result = await explain("Groq's text-2 model is versatile for many tasks.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/openrouter-default.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const summarize = wrap((text: string) => text, { task: "summarize", provider: "openrouter" });
+
+async function run() {
+  const result = await summarize("OpenRouter makes AI integration seamless.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/openrouter-gpt5.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const summarize = wrap((text: string) => text, { task: "summarize", provider: "openrouter", model: "openai/gpt-5-pro" });
+
+async function run() {
+  const result = await summarize("OpenRouter supports multiple models including GPT-5.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/wrong-models.ts

@@ -0,0 +1,21 @@
+import { wrap } from "../../src/wrap";
+
+async function run() {
+  // Wrong OpenRouter model
+  try {
+    const wrongOpenRouter = wrap((text: string) => text, { task: "summarize", provider: "openrouter", model: "invalid-model" as any });
+    await wrongOpenRouter("Test text");
+  } catch (err: unknown) {
+    console.error("❌ OpenRouter error:", err);
+  }
+
+  // Wrong Groq model
+  try {
+    const wrongGroq = wrap((text: string) => text, { task: "explain", provider: "groq", model: "invalid-groq-model" as any });
+    await wrongGroq("Test text");
+  } catch (err: unknown) {
+    console.error("❌ Groq error:", err);
+  }
+}
+
+run();

package/examples/openrouter/summarize-switch-model-demo.ts

@@ -0,0 +1,25 @@
+import dotenv from "dotenv";
+dotenv.config();
+import { wrap } from "../../src/wrap";
+import { OpenRouterModel } from "../../src/types/openrouter";
+
+const summarize = (model: OpenRouterModel) =>
+  wrap((text: string) => text, { task: "summarize", provider: "openrouter", model });
+
+async function run() {
+  const text = "OpenRouter allows developers to switch AI models easily.";
+
+  const models: OpenRouterModel[] = [
+    "openai/gpt-oss-20b:free",
+    "openai/gpt-5-pro",
+    "openai/gpt-5-mini"
+  ];
+
+  for (const model of models) {
+    console.log(`\n--- Using model: ${model} ---`);
+    const result = await summarize(model)(text);
+    console.log(result.output);
+  }
+}
+
+run();

package/examples/openrouter/translate-switch-model-demo.ts

@@ -0,0 +1,24 @@
+import dotenv from "dotenv";
+dotenv.config();
+import { wrap } from "../../src/wrap";
+import { OpenRouterModel } from "../../src/types/openrouter";
+
+const translate = (model: OpenRouterModel) =>
+  wrap((text: string) => text, { task: "translate", provider: "openrouter", model });
+
+async function run() {
+  const text = "Bonjour tout le monde!";
+
+  const models: OpenRouterModel[] = [
+    "openai/gpt-4.1",
+    "openai/gpt-5-chat"
+  ];
+
+  for (const model of models) {
+    console.log(`\n--- Using model: ${model} ---`);
+    const result = await translate(model)(text);
+    console.log(result.output);
+  }
+}
+
+run();

package/examples/openrouter/translate-to-urdu-demo.ts

@@ -0,0 +1,19 @@
+import dotenv from "dotenv";
+dotenv.config();
+import { wrap } from "../../src/wrap";
+
+// Wrap the text function for translation to Urdu
+const translate = wrap((text: string) => text, {
+  task: "translate",
+  provider: "openrouter",
+  targetLanguage: "Roman Urdu" // specify target language
+});
+
+async function run() {
+  const text = "Hello everyone! Welcome to OpenRouter demos.";
+
+  const result = await translate(text);
+  console.log(result.output);
+}
+
+run();

package/examples/openrouter-openai/gpt5-demo.ts

@@ -0,0 +1,25 @@
+import dotenv from "dotenv";
+dotenv.config();
+import { wrap } from "../../src/wrap";
+import { OpenRouterModel } from "../../src/types/openrouter";
+
+const summarize = (model: OpenRouterModel) =>
+  wrap((text: string) => text, { task: "summarize", provider: "openrouter", model });
+
+async function run() {
+  const text = "This is a demonstration of switching OpenRouter models to GPT-5 variants.";
+
+  const models: OpenRouterModel[] = [
+    "openai/gpt-5",
+    "openai/gpt-5-pro",
+    "openai/gpt-5-mini"
+  ];
+
+  for (const model of models) {
+    console.log(`\n--- Using model: ${model} ---`);
+    const result = await summarize(model)(text);
+    console.log(result.output);
+  }
+}
+
+run();

package/jest.config.js

@@ -0,0 +1,11 @@
+const { createDefaultPreset } = require("ts-jest");
+
+const tsJestTransformCfg = createDefaultPreset().transform;
+
+/** @type {import("jest").Config} **/
+module.exports = {
+  testEnvironment: "node",
+  transform: {
+    ...tsJestTransformCfg,
+  },
+};

package/package.json

@@ -1,19 +1,8 @@
 {
   "name": "npm-ai-hooks",
-  "version": "1.0.0",
-  "description": "Universal AI Hook Layer for Node.js – one wrapper for all AI providers.",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist/**/*"
-  ],
+  "version": "1.0.1",
+  "description": "**Universal AI Hook Layer for Node.js – one wrapper for all AI providers.**\r 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": "index.js",
   "scripts": {
     "dev": "ts-node src/index.ts",
     "build:clean": "rimraf dist && tsc",
@@ -23,7 +12,7 @@
     "demo": "npx ts-node examples/demo.ts"
   },
   "keywords": [],
-  "author": "AteebNoOne",
+  "author": "",
   "license": "ISC",
   "dependencies": {
     "axios": "^1.12.2",
@@ -40,4 +29,4 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }
-}
+}

package/src/errors.ts

@@ -0,0 +1,23 @@
+export class AIHookError extends Error {
+    code: string;
+    provider?: string;
+    suggestion?: string;
+  
+    constructor(code: string, message: string, provider?: string, suggestion?: string) {
+      super(message);
+      this.code = code;
+      this.provider = provider;
+      this.suggestion = suggestion;
+      // Do NOT print pretty message in constructor
+    }
+  
+    pretty() {
+      return `\n❌ AI-HOOK ERROR: ${this.message}` +
+        (this.provider ? `\n   Provider: ${this.provider}` : "") +
+        (this.suggestion ? `\n   Suggestion: ${this.suggestion}\n` : "");
+    }
+
+    toString() {
+      return this.pretty();
+    }
+  }

package/{dist/index.d.ts → src/index.ts}

@@ -1 +1,2 @@
-export { wrap } from "./wrap";
+// src/index.ts
+export { wrap } from "./wrap";

package/src/providers/claude.ts

@@ -0,0 +1,101 @@
+import axios from "axios";
+import { AIHookError } from "../errors";
+import { ClaudeModel } from "../types/claude";
+
+const BASE_URL = "https://api.anthropic.com/v1";
+const ANTHROPIC_VERSION = "2023-06-01";
+
+export async function callClaude(prompt: string, model: ClaudeModel): Promise<string> {
+  const apiKey = process.env.AI_HOOK_CLAUDE_KEY;
+  if (!apiKey) {
+    throw new AIHookError(
+      "INVALID_API_KEY",
+      "Missing Claude API key.",
+      "claude",
+      "Set AI_HOOK_CLAUDE_KEY in your environment variables."
+    );
+  }
+
+  try {
+    const response = await axios.post(
+      `${BASE_URL}/messages`,
+      {
+        model,
+        max_tokens: 4096,
+        messages: [
+          {
+            role: "user",
+            content: prompt
+          }
+        ]
+      },
+      {
+        headers: {
+          "x-api-key": apiKey,
+          "anthropic-version": ANTHROPIC_VERSION,
+          "Content-Type": "application/json"
+        }
+      }
+    );
+
+    const output = response.data?.content?.[0]?.text;
+    if (!output) {
+      throw new AIHookError(
+        "PROVIDER_ERROR",
+        "Claude returned empty response",
+        "claude",
+        "Check your model and API key"
+      );
+    }
+
+    return output;
+  } catch (err: any) {
+    if (err.response) {
+      const status = err.response.status;
+      const text = err.response.data?.error
+        ? JSON.stringify(err.response.data.error)
+        : err.response.statusText || "Unknown error";
+
+      if (status === 400)
+        throw new AIHookError(
+          "BAD_REQUEST",
+          `Claude rejected the request: ${text}`,
+          "claude",
+          "Check your prompt and model"
+        );
+      if (status === 401)
+        throw new AIHookError(
+          "INVALID_API_KEY",
+          `Invalid Claude API key: ${text}`,
+          "claude",
+          "Verify your AI_HOOK_CLAUDE_KEY environment variable"
+        );
+      if (status === 429)
+        throw new AIHookError(
+          "RATE_LIMIT",
+          `Too many requests to Claude: ${text}`,
+          "claude",
+          "Throttle requests or upgrade your plan"
+        );
+
+      throw new AIHookError(
+        "PROVIDER_ERROR",
+        `Claude API error: ${text}`,
+        "claude"
+      );
+    } else if (err.request) {
+      throw new AIHookError(
+        "NETWORK_ERROR",
+        "Network error while contacting Claude",
+        "claude",
+        "Check your internet connection"
+      );
+    } else {
+      throw new AIHookError(
+        "UNKNOWN_ERROR",
+        err.message,
+        "claude"
+      );
+    }
+  }
+}