npm-ai-hooks 1.0.0-beta.0

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

@@ -0,0 +1,32 @@
+{
+  "name": "npm-ai-hooks",
+  "version": "1.0.0-beta.0",
+  "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",
+    "build": "tsc",
+    "test": "jest --verbose",
+    "prepare": "npm run build",
+    "demo": "npx ts-node examples/demo.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "axios": "^1.12.2",
+    "dotenv": "^17.2.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.7.0",
+    "eslint": "^9.37.0",
+    "jest": "^30.2.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.4.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/src/index.ts

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

package/src/providers/groq.ts

@@ -0,0 +1,98 @@
+import axios from "axios";
+import { AIHookError } from "../errors";
+import { GroqModel } from "../types/groq";
+
+const BASE_URL = "https://api.groq.com/openai/v1";
+
+export async function callGroq(prompt: string, model: GroqModel): Promise<string> {
+  const apiKey = process.env.AI_HOOK_GROQ_KEY;
+  if (!apiKey) {
+    throw new AIHookError(
+      "INVALID_API_KEY",
+      "Missing Groq API key.",
+      "groq",
+      "Set AI_HOOK_GROQ_KEY in your environment variables."
+    );
+  }
+
+  try {
+    const response = await axios.post(
+      `${BASE_URL}/chat/completions`,
+      {
+        model,
+        messages: [
+          {
+            role: "user",
+            content: prompt
+          }
+        ]
+      },
+      {
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        }
+      }
+    );
+
+    const output = response.data?.choices?.[0]?.message?.content;
+    if (!output) {
+      throw new AIHookError(
+        "PROVIDER_ERROR",
+        "Groq returned empty response",
+        "groq",
+        "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",
+          `Groq rejected the request: ${text}`,
+          "groq",
+          "Check your prompt and model"
+        );
+      if (status === 401)
+        throw new AIHookError(
+          "INVALID_API_KEY",
+          `Invalid Groq API key: ${text}`,
+          "groq",
+          "Verify your AI_HOOK_GROQ_KEY environment variable"
+        );
+      if (status === 429)
+        throw new AIHookError(
+          "RATE_LIMIT",
+          `Too many requests to Groq: ${text}`,
+          "groq",
+          "Throttle requests or upgrade your plan"
+        );
+
+      throw new AIHookError(
+        "PROVIDER_ERROR",
+        `Groq API error: ${text}`,
+        "groq"
+      );
+    } else if (err.request) {
+      throw new AIHookError(
+        "NETWORK_ERROR",
+        "Network error while contacting Groq",
+        "groq",
+        "Check your internet connection"
+      );
+    } else {
+      throw new AIHookError(
+        "UNKNOWN_ERROR",
+        err.message,
+        "groq"
+      );
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,54 @@
+import { AIHookError } from "../errors";
+import { callOpenAI } from "./openai";
+import { callOpenRouter } from "./openrouter";
+import { callGroq } from "./groq";
+import { Provider } from "../types";
+import { ProviderFunction, ProviderMap } from "../types/core/providers";
+
+const providers: ProviderMap = {
+    openai: callOpenAI,
+    openrouter: callOpenRouter,
+    groq: callGroq,
+    mock: async (prompt: string, model?: string) => `[MOCK OUTPUT] ${prompt}`
+};
+
+// Returns an array of providers whose API keys exist in environment
+export function getAvailableProviders(): Provider[] {
+    const available: Provider[] = [];
+    // Always prefer openrouter if present
+    if (process.env.AI_HOOK_OPENROUTER_KEY) {
+        available.push("openrouter");
+    }
+    // Add others in order of their presence
+    if (process.env.AI_HOOK_GROQ_KEY && !available.includes("groq")) {
+        available.push("groq");
+    }
+    if (process.env.AI_HOOK_OPENAI_KEY && !available.includes("openai")) {
+        available.push("openai");
+    }
+    return available;
+}
+
+// ✅ Returns both the provider function and the actual provider name
+export function getProvider(name?: Provider): { fn: ProviderFunction<any>; provider: Provider | "mock" } {
+    const available = getAvailableProviders();
+
+    // 1. If user specified provider and it's available
+    if (name && providers[name]) {
+        return { fn: providers[name], provider: name };
+    }
+
+    // 2. If at least one provider is available, pick the first one (openrouter always preferred if present)
+    if (available.length > 0) {
+        console.log(`[ai-hooks] ✅ Auto-selected provider: ${available[0]}`);
+        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."
+    );
+}

package/src/providers/openai.ts

@@ -0,0 +1,19 @@
+import axios from "axios";
+
+export async function callOpenAI(prompt: string, model: string) {
+  const key = process.env.AI_HOOK_OPENAI_KEY;
+  if (!key) throw new Error("Missing AI_HOOK_OPENAI_KEY");
+
+  const response = await axios.post(
+    "https://api.openai.com/v1/chat/completions",
+    {
+      model,
+      messages: [{ role: "user", content: prompt }]
+    },
+    {
+      headers: { Authorization: `Bearer ${key}` }
+    }
+  );
+
+  return response.data.choices[0].message.content;
+}

package/src/providers/openrouter.ts

@@ -0,0 +1,100 @@
+import axios from "axios";
+import { AIHookError } from "../errors";
+
+const BASE_URL = "https://openrouter.ai/api/v1";
+
+export async function callOpenRouter(prompt: string, model: string): Promise<string> {
+  const apiKey = process.env.AI_HOOK_OPENROUTER_KEY;
+  if (!apiKey) {
+    throw new AIHookError(
+      "INVALID_API_KEY",
+      "Missing OpenRouter API key.",
+      "openrouter",
+      "Set AI_HOOK_OPENROUTER_KEY in your environment variables."
+    );
+  }
+
+  try {
+    const response = await axios.post(
+      `${BASE_URL}/chat/completions`,
+      {
+        model,
+        messages: [{ role: "user", content: prompt }],
+      },
+      {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+      }
+    );
+
+    const output = response.data?.choices?.[0]?.message?.content;
+    if (!output) {
+      throw new AIHookError(
+        "PROVIDER_ERROR",
+        "OpenRouter returned empty response.",
+        "openrouter",
+        "Check that the model name is correct and your API key has access to it."
+      );
+    }
+
+    return output;
+  } catch (err: any) {
+    if (err.response) {
+      const status = err.response.status;
+      // Make sure we get a string message
+      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",
+        `OpenRouter rejected the request: ${text}`,
+        "openrouter",
+        "Check your prompt, model name, and payload format."
+      );
+      if (status === 401) throw new AIHookError(
+        "INVALID_API_KEY",
+        `Invalid OpenRouter API key: ${text}`,
+        "openrouter",
+        "Verify your AI_HOOK_OPENROUTER_KEY environment variable."
+      );
+      if (status === 403) throw new AIHookError(
+        "MODEL_NOT_ALLOWED",
+        `Your API key cannot access this model: ${text}`,
+        "openrouter",
+        "Try a different model or check API key permissions."
+      );
+      if (status === 429) throw new AIHookError(
+        "RATE_LIMIT",
+        `Too many requests to OpenRouter: ${text}`,
+        "openrouter",
+        "Consider throttling requests or upgrading your plan."
+      );
+
+      throw new AIHookError(
+        "PROVIDER_ERROR",
+        `OpenRouter API error: ${text}`,
+        "openrouter",
+        "Check your model, prompt, and API key."
+      );
+    }
+
+    else if (err.request) {
+      throw new AIHookError(
+        "NETWORK_ERROR",
+        "Network error while contacting OpenRouter.",
+        "openrouter",
+        "Check your internet connection."
+      );
+    }
+    else {
+      throw new AIHookError(
+        "UNKNOWN_ERROR",
+        err.message,
+        "openrouter"
+      );
+    }
+  }
+}

package/src/types/core/providers.ts

@@ -0,0 +1,13 @@
+import { Provider, ProviderModels } from "../index"; 
+
+export interface ProviderFunction<P extends Provider = Provider> {
+  (prompt: string, model: ProviderModels[P]): Promise<string>;
+}
+
+export interface ProviderMap {
+    openai: ProviderFunction<"openai">;
+    openrouter: ProviderFunction<"openrouter">;
+    groq: ProviderFunction<"groq">;
+    mock: ProviderFunction<any>; // generic fallback for mock
+  }
+  

package/src/types/groq.ts

@@ -0,0 +1,20 @@
+export type GroqModel =
+  | "allam-2-7b"
+  | "deepseek-r1-distill-llama-70b"
+  | "gemma2-9b-it"
+  | "groq/compound"
+  | "groq/compound-mini"
+  | "llama-3.1-8b-instant"
+  | "llama-3.3-70b-versatile"
+  | "meta-llama/llama-4-maverick-17b-128e-instruct"
+  | "meta-llama/llama-4-scout-17b-16e-instruct"
+  | "meta-llama/llama-guard-4-12b"
+  | "meta-llama/llama-prompt-guard-2-22m"
+  | "meta-llama/llama-prompt-guard-2-86m"
+  | "moonshotai/kimi-k2-instruct"
+  | "moonshotai/kimi-k2-instruct-0905"
+  | "openai/gpt-oss-120b"
+  | "openai/gpt-oss-20b"
+  | "qwen/qwen3-32b";
+
+export const GroqDefaultModel: GroqModel = "groq/compound";

package/src/types/index.ts

@@ -0,0 +1,37 @@
+import { OpenAIModel, OpenAIDefaultModel } from "./openai";
+import { OpenRouterModel, OpenRouterDefaultModel } from "./openrouter";
+import { GroqModel, GroqDefaultModel } from "./groq";
+
+export type Provider = "openai" | "openrouter" | "groq";
+
+export type ProviderModels = {
+  openai: OpenAIModel;
+  openrouter: OpenRouterModel;
+  groq: GroqModel;
+};
+
+export const DEFAULT_MODEL: { [P in Provider]: ProviderModels[P] } = {
+  openai: OpenAIDefaultModel,
+  openrouter: OpenRouterDefaultModel,
+  groq: GroqDefaultModel,
+};
+
+// Task types
+export type TaskType =
+  | "summarize"
+  | "translate"
+  | "explain"
+  | "rewrite"
+  | "sentiment"
+  | "codeReview";
+
+// Wrap options
+export type WrapOptions<P extends Provider | undefined = undefined> =
+  | {
+      provider: P extends Provider ? P : never;
+      model?: P extends Provider ? ProviderModels[P] : never;
+      task: TaskType;
+      targetLanguage?: string; // new optional
+    }
+  | { provider?: never; model?: never; task: TaskType; targetLanguage?: string };
+

package/src/types/openai.ts

@@ -0,0 +1,3 @@
+export type OpenAIModel = "gpt-4" | "gpt-4o" | "gpt-3.5-turbo";
+
+export const OpenAIDefaultModel: OpenAIModel = "gpt-4";

package/src/types/openrouter.ts

@@ -0,0 +1,52 @@
+export type OpenRouterModel = "openai/gpt-oss-20b:free" 
+| "openai/gpt-4.1" 
+| "openai/gpt-5-pro" 
+| "openai/gpt-5-codex"
+| "openai/gpt-5-chat" 
+| "openai/gpt-5" 
+| "openai/gpt-5-mini" 
+| "openai/gpt-5-nano" 
+| "openai/gpt-oss-120b" 
+| "openai/gpt-oss-20b" 
+| "openai/o3-pro" 
+| "openai/codex-mini" 
+| "openai/o3" 
+| "openai/o4-mini" 
+| "openai/gpt-4.1-mini" 
+| "openai/gpt-4.1-nano" 
+| "openai/o1-pro" 
+| "openai/gpt-4o-mini-search-preview" 
+| "openai/gpt-4o-search-preview" 
+| "openai/o3-mini-high" 
+| "openai/o3-mini" 
+| "openai/o1" 
+| "openai/gpt-4o-2024-11-20" 
+| "openai/o1-mini" 
+| "openai/o1-mini-2024-09-12" 
+| "openai/chatgpt-4o-latest" 
+| "openai/gpt-4o-2024-08-06" 
+| "openai/gpt-4o-mini" 
+| "openai/gpt-4o-mini-2024-07-18" 
+| "openai/gpt-4o" 
+| "openai/gpt-4o:extended" 
+| "openai/gpt-4o-2024-05-13" 
+| "openai/gpt-4-turbo" 
+| "openai/gpt-3.5-turbo-0613" 
+| "openai/gpt-4-turbo-preview" 
+| "openai/gpt-4-1106-preview" 
+| "openai/gpt-3.5-turbo-instruct" 
+| "openai/gpt-3.5-turbo-16k" 
+| "openai/gpt-3.5-turbo" 
+| "openai/gpt-4" 
+| "openai/gpt-4-0314" 
+| "openai/gpt-4.5-preview" 
+| "openai/o1-preview" 
+| "openai/o1-preview-2024-09-12" 
+| "openai/gpt-4-vision-preview" 
+| "openai/gpt-3.5-turbo-1106" 
+| "openai/gpt-4-32k" 
+| "openai/gpt-4-32k-0314" 
+| "openai/gpt-3.5-turbo-0301" 
+| "openai/gpt-3.5-turbo-0125" ;
+
+export const OpenRouterDefaultModel: OpenRouterModel = "openai/gpt-oss-20b:free" ;

package/src/wrap.ts

@@ -0,0 +1,93 @@
+import dotenv from "dotenv";
+dotenv.config();
+import { getProvider } from "./providers";
+import { WrapOptions, TaskType, Provider, DEFAULT_MODEL } from "./types";
+
+function handleError(err: unknown): never {
+  if (err && typeof err === "object" && "pretty" in err && typeof (err as any).pretty === "function") {
+    // Print pretty message and exit
+    console.error((err as any).pretty());
+    process.exit(1);
+  } else {
+    console.error(err);
+    process.exit(1);
+  }
+  throw new Error("Process exited due to AIHookError"); // for TS never
+}
+
+export 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 }> {
+  return async (...args: Parameters<T>) => {
+    try {
+      const input = fn(...args);
+
+      // Step 1: get provider function and the actual provider name
+      const { fn: providerFn, provider: providerKey } = getProvider(options.provider as Provider | undefined);
+
+      // Step 2: pick model: passed model or provider-specific default
+      const model = options.model || (providerKey in DEFAULT_MODEL ? DEFAULT_MODEL[providerKey as Provider] : undefined);
+
+      if (!model) {
+        throw new (require('./errors').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 as Provider | undefined,
+          "Reference .env.example for setup instructions."
+        );
+      }
+
+      // Step 3: build prompt
+      const prompt = buildPrompt(options.task, input, (options as any).targetLanguage);
+
+      const startTime = Date.now();
+      let output: string;
+      try {
+        output = await providerFn(prompt, model);
+      } catch (err: unknown) {
+        if (err instanceof require('./errors').AIHookError) {
+          handleError(err);
+        }
+        if (err instanceof Error) {
+          throw new Error(`[ai-hooks] Unknown error calling provider: ${err.message}`);
+        }
+        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
+        }
+      };
+    } catch (err) {
+      handleError(err);
+    }
+  };
+}
+
+function buildPrompt(task: TaskType, text: string, targetLanguage?: string) {
+  switch (task) {
+    case "summarize":
+      return `Summarize the following text:\n${text}`;
+    case "translate":
+      const language = targetLanguage || "English"; // default to English
+      return `Translate this text into ${language}:\n${text}`;
+    case "explain":
+      return `Explain this clearly:\n${text}`;
+    case "rewrite":
+      return `Rewrite this text with better clarity:\n${text}`;
+    case "sentiment":
+      return `Analyze the sentiment of this text:\n${text}`;
+    case "codeReview":
+      return `Review this code and suggest improvements:\n${text}`;
+    default:
+      return text;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}