@netbirdio/explain 0.1.0

package/src/server/handler.ts

@@ -0,0 +1,158 @@
+import type { Message } from "../types";
+import { AnthropicProvider } from "./providers/anthropic";
+import { OpenAIProvider } from "./providers/openai";
+import type { LLMProvider } from "./providers/types";
+
+export type AssistantConfig = {
+  provider: "anthropic" | "openai";
+  apiKey: string;
+  model?: string;
+  systemPrompt?: string;
+};
+
+type HandlerOptions = {
+  apiKey?: string;
+};
+
+type ChatRequest = {
+  messages: Message[];
+};
+
+type ChatResponse = {
+  reply: string;
+};
+
+interface IncomingRequest {
+  headers: Record<string, string | string[] | undefined> | { get(name: string): string | null };
+  body?: unknown;
+  method?: string;
+  on?(event: string, callback: (...args: unknown[]) => void): unknown;
+}
+
+interface OutgoingResponse {
+  status?(code: number): Pick<OutgoingResponse, "json" | "end">;
+  statusCode?: number;
+  json?(data: unknown): void;
+  end?(data?: string): void;
+  setHeader?(name: string, value: string): void;
+  writeHead?(statusCode: number, headers?: Record<string, string>): void;
+}
+
+function getHeader(req: IncomingRequest, name: string): string | null {
+  if (typeof req.headers === "object" && req.headers !== null) {
+    if ("get" in req.headers && typeof req.headers.get === "function") {
+      return req.headers.get(name);
+    }
+    const headers = req.headers as Record<string, string | string[] | undefined>;
+    const value = headers[name] ?? headers[name.toLowerCase()];
+    if (Array.isArray(value)) return value[0] ?? null;
+    return value ?? null;
+  }
+  return null;
+}
+
+function sendJson(res: OutgoingResponse, statusCode: number, data: unknown): void {
+  if (typeof res.status === "function" && typeof res.json === "function") {
+    const chained = res.status(statusCode);
+    if (chained && typeof chained.json === "function") {
+      chained.json(data);
+      return;
+    }
+  }
+  if (typeof res.writeHead === "function" && typeof res.end === "function") {
+    res.writeHead(statusCode, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(data));
+    return;
+  }
+  if (typeof res.end === "function") {
+    if (res.statusCode !== undefined) res.statusCode = statusCode;
+    res.end(JSON.stringify(data));
+  }
+}
+
+async function parseBody(req: IncomingRequest): Promise<unknown> {
+  if (req.body !== undefined && req.body !== null) {
+    return req.body;
+  }
+  if (typeof req.on === "function") {
+    const onFn = req.on.bind(req);
+    return new Promise((resolve, reject) => {
+      const chunks: string[] = [];
+      onFn("data", (chunk: unknown) => chunks.push(String(chunk)));
+      onFn("end", () => {
+        try {
+          resolve(JSON.parse(chunks.join("")));
+        } catch {
+          reject(new Error("Invalid JSON body"));
+        }
+      });
+      onFn("error", reject);
+    });
+  }
+  throw new Error("Unable to parse request body");
+}
+
+function createProvider(config: AssistantConfig): LLMProvider {
+  switch (config.provider) {
+    case "anthropic":
+      return new AnthropicProvider({ apiKey: config.apiKey, model: config.model });
+    case "openai":
+      return new OpenAIProvider({ apiKey: config.apiKey, model: config.model });
+    default:
+      throw new Error(`Unknown provider: ${config.provider}`);
+  }
+}
+
+export function createAssistant(config: AssistantConfig) {
+  const provider = createProvider(config);
+
+  async function chat(req: ChatRequest): Promise<ChatResponse> {
+    if (!req.messages || !Array.isArray(req.messages) || req.messages.length === 0) {
+      throw new Error("messages array is required and must not be empty");
+    }
+    const reply = await provider.chat(req.messages, config.systemPrompt);
+    return { reply };
+  }
+
+  function handler(opts?: HandlerOptions) {
+    return async (req: IncomingRequest, res: OutgoingResponse): Promise<void> => {
+      try {
+        if (opts?.apiKey) {
+          const authHeader = getHeader(req, "Authorization") || getHeader(req, "authorization");
+          const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+          if (token !== opts.apiKey) {
+            sendJson(res, 401, { error: "Unauthorized" });
+            return;
+          }
+        }
+
+        let body: unknown;
+        try {
+          body = await parseBody(req);
+        } catch {
+          sendJson(res, 400, { error: "Invalid request body" });
+          return;
+        }
+
+        const { messages } = body as { messages?: Message[] };
+        if (!messages || !Array.isArray(messages) || messages.length === 0) {
+          sendJson(res, 400, { error: "messages array is required and must not be empty" });
+          return;
+        }
+
+        try {
+          const result = await chat({ messages });
+          sendJson(res, 200, result);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : "LLM request failed";
+          sendJson(res, 502, { error: message });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Internal server error";
+        sendJson(res, 500, { error: message });
+      }
+    };
+  }
+
+  return { chat, handler };
+}

package/src/server/index.ts

@@ -0,0 +1,5 @@
+export { createAssistant } from "./handler";
+export type { AssistantConfig } from "./handler";
+export { AnthropicProvider } from "./providers/anthropic";
+export { OpenAIProvider } from "./providers/openai";
+export type { LLMProvider, ProviderConfig } from "./providers/types";

package/src/server/providers/anthropic.ts

@@ -0,0 +1,53 @@
+import type { Message } from "../../types";
+import type { LLMProvider, ProviderConfig } from "./types";
+
+export class AnthropicProvider implements LLMProvider {
+  private apiKey: string;
+  private model: string;
+
+  constructor(config: ProviderConfig) {
+    this.apiKey = config.apiKey;
+    this.model = config.model || "claude-sonnet-4-20250514";
+  }
+
+  async chat(messages: Message[], systemPrompt?: string): Promise<string> {
+    const anthropicMessages = messages.map((m) => ({
+      role: m.role === "context" || m.role === "system" ? ("user" as const) : m.role,
+      content: m.role === "context" ? `[Context]: ${m.content}` : m.content,
+    }));
+
+    const body: Record<string, unknown> = {
+      model: this.model,
+      max_tokens: 4096,
+      messages: anthropicMessages,
+    };
+
+    if (systemPrompt) {
+      body.system = systemPrompt;
+    }
+
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Anthropic API error ${response.status}: ${text}`);
+    }
+
+    const data = await response.json();
+    const textBlock = data.content?.find(
+      (block: { type: string }) => block.type === "text",
+    );
+    if (!textBlock) {
+      throw new Error("No text content in Anthropic response");
+    }
+    return textBlock.text;
+  }
+}

package/src/server/providers/openai.ts

@@ -0,0 +1,55 @@
+import type { Message } from "../../types";
+import type { LLMProvider, ProviderConfig } from "./types";
+
+export class OpenAIProvider implements LLMProvider {
+  private apiKey: string;
+  private model: string;
+
+  constructor(config: ProviderConfig) {
+    this.apiKey = config.apiKey;
+    this.model = config.model || "gpt-4o";
+  }
+
+  async chat(messages: Message[], systemPrompt?: string): Promise<string> {
+    const openaiMessages: Array<{ role: string; content: string }> = [];
+
+    if (systemPrompt) {
+      openaiMessages.push({ role: "system", content: systemPrompt });
+    }
+
+    for (const m of messages) {
+      if (m.role === "context") {
+        openaiMessages.push({ role: "user", content: `[Context]: ${m.content}` });
+      } else if (m.role === "system") {
+        openaiMessages.push({ role: "user", content: m.content });
+      } else {
+        openaiMessages.push({ role: m.role, content: m.content });
+      }
+    }
+
+    const response = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages: openaiMessages,
+        max_tokens: 4096,
+      }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`OpenAI API error ${response.status}: ${text}`);
+    }
+
+    const data = await response.json();
+    const choice = data.choices?.[0];
+    if (!choice?.message?.content) {
+      throw new Error("No content in OpenAI response");
+    }
+    return choice.message.content;
+  }
+}

package/src/server/providers/types.ts

@@ -0,0 +1,10 @@
+import type { Message } from "../../types";
+
+export interface LLMProvider {
+  chat(messages: Message[], systemPrompt?: string): Promise<string>;
+}
+
+export type ProviderConfig = {
+  apiKey: string;
+  model?: string;
+};

package/src/types.ts

@@ -0,0 +1,11 @@
+export type Message = {
+  id?: string;
+  role: "user" | "assistant" | "context" | "system";
+  content: string;
+};
+
+export type ExplainContext = {
+  modalName?: string;
+  pageName?: string;
+  docsUrls?: string[];
+};