@neutrome/open-ai-router 0.1.0

package/src/index.ts

@@ -0,0 +1,50 @@
+export { createApp } from "./example.ts";
+export type { CreateAppOptions } from "./example.ts";
+
+export {
+  createFetchProviderInvoker,
+  createRouterExecutionRuntime,
+  createRouterRuntime,
+  handleChatCompletions,
+  handleResponses,
+  listConfiguredModels,
+  ProviderHttpError,
+  resolveInvocationTarget,
+  resolveInvocationTargets,
+  resolveRequestTarget,
+  RouterError,
+} from "./router/index.ts";
+export type {
+  AuthConfig,
+  CreateRouterOptions,
+  ExecutorNamespaceConfig,
+  ExecutorRouteConfig,
+  ExecutorRouteRuntime,
+  ExecutorRuntime,
+  HandleChatCompletionsOptions,
+  HandleResponsesOptions,
+  ProviderApiStyle,
+  ProviderApiStyle as ProviderStyle,
+  ProviderRuntime,
+  ProviderTargetConfig,
+  ResolvedTarget,
+  RouterConfig,
+  RouterExecutionOptions,
+  RouterRuntime,
+  UsageReport,
+} from "./router/index.ts";
+
+export type {
+  AuthDriver,
+  AuthResult,
+  RequestContext,
+  TargetAuthContext,
+} from "./auth/types.ts";
+export { buildAuthChain } from "./auth/registry.ts";
+export { envAuthDriver } from "./auth/env.ts";
+export { proxyAuthDriver } from "./auth/proxy.ts";
+
+export { cors } from "./app/cors.ts";
+export { healthHandler } from "./app/health.ts";
+export { chatCompletionsHandler, listModelsHandler, responsesHandler } from "./app/handlers.ts";
+export type { ChatCompletionsHandlerOptions, ResponsesHandlerOptions } from "./app/handlers.ts";

package/src/router/config.ts

@@ -0,0 +1,41 @@
+import type { ProviderStyle } from "@neutrome/lil-engine";
+import type { AuthConfigShape } from "../auth/config.ts";
+
+export type ProviderApiStyle = ProviderStyle;
+
+export type AuthConfig = AuthConfigShape;
+
+export type ProviderTargetConfig = {
+  api_base_url: string;
+  style: ProviderApiStyle;
+  exports?: string[] | null;
+  endpoint_path?: string;
+  allow_anonymous?: boolean;
+  no_prefix?: boolean;
+  headers?: Record<string, string>;
+  catalog?: string[];
+};
+
+export type ExecutorRouteConfig =
+  | {
+      executor: string;
+      alias?: string;
+      transforms?: string[];
+    }
+  | {
+      provider: string;
+      model: string;
+      transforms?: string[];
+    };
+
+export type ExecutorNamespaceConfig = {
+  exports?: string[] | null;
+  models: Record<string, ExecutorRouteConfig>;
+};
+
+export type RouterConfig = {
+  trace?: boolean;
+  auth?: AuthConfig;
+  providers: Record<string, ProviderTargetConfig>;
+  executors: Record<string, ExecutorNamespaceConfig>;
+};

package/src/router/execute.test.ts

@@ -0,0 +1,478 @@
+import { appendAssistantMessage } from "@neutrome/lil-engine";
+import { describe, expect, it, vi } from "vitest";
+import type { RequestContext } from "../auth/types.ts";
+import { handleChatCompletions } from "./execute.ts";
+import { createRouterRuntime } from "./runtime.ts";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+describe("router execution", () => {
+  it("routes chat completions requests through provider transport", async () => {
+    let capturedUrl = "";
+    let capturedBody: Record<string, unknown> | null = null;
+    let capturedAuth = "";
+
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            allow_anonymous: true,
+            exports: ["gpt-4o"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async (input, init) => {
+        capturedUrl = String(input);
+        capturedAuth = new Headers(init?.headers).get("authorization") ?? "";
+        capturedBody = JSON.parse(decoder.decode(new Uint8Array(init?.body as ArrayBuffer)));
+        return new Response(
+          JSON.stringify({
+            id: "resp_1",
+            model: "gpt-4o",
+            choices: [
+              {
+                index: 0,
+                message: { role: "assistant", content: "hello" },
+                finish_reason: "stop",
+              },
+            ],
+          }),
+          { headers: { "content-type": "application/json; charset=utf-8" } },
+        );
+      }),
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: {
+          authorization: "Bearer incoming",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          model: "gpt-4o",
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({ runtime, ctx });
+
+    expect(response.status).toBe(200);
+    expect(capturedUrl).toBe("https://openrouter.ai/api/v1/chat/completions");
+    expect(capturedAuth).toBe("Bearer incoming");
+    expect(capturedBody).toEqual({
+      model: "gpt-4o",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    expect(response.headers.get("x-openairouter-provider-id")).toBe("openrouter");
+    expect(response.headers.get("x-openairouter-model-id")).toBe("gpt-4o");
+    expect(await response.json()).toEqual({
+      object: "chat.completion",
+      id: "resp_1",
+      model: "gpt-4o",
+      choices: [
+        {
+          index: 0,
+          message: { role: "assistant", content: "hello" },
+          finish_reason: "stop",
+        },
+      ],
+    });
+  });
+
+  it("routes responses-style providers through provider transport", async () => {
+    let capturedUrl = "";
+    let capturedBody: Record<string, unknown> | null = null;
+
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openai: {
+            api_base_url: "https://api.openai.com/v1",
+            style: "responses",
+            allow_anonymous: true,
+            exports: ["gpt-5"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async (input, init) => {
+        capturedUrl = String(input);
+        capturedBody = JSON.parse(decoder.decode(new Uint8Array(init?.body as ArrayBuffer)));
+        return new Response(
+          JSON.stringify({
+            id: "resp_1",
+            model: "gpt-5",
+            output: [{
+              type: "message",
+              role: "assistant",
+              status: "completed",
+              content: [{ type: "output_text", text: "hello" }],
+            }],
+          }),
+          { headers: { "content-type": "application/json; charset=utf-8" } },
+        );
+      }),
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "gpt-5",
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({ runtime, ctx });
+    expect(response.status).toBe(200);
+    expect(capturedUrl).toBe("https://api.openai.com/v1/responses");
+    expect(capturedBody).toEqual({
+      model: "gpt-5",
+      input: [{ role: "user", content: "hi" }],
+    });
+    expect(await response.json()).toEqual({
+      object: "chat.completion",
+      id: "resp_1",
+      model: "gpt-5",
+      choices: [{
+        index: 0,
+        message: { role: "assistant", content: "hello" },
+        finish_reason: "stop",
+      }],
+    });
+  });
+
+  it("routes anthropic-style providers through provider transport", async () => {
+    let capturedUrl = "";
+    let capturedBody: Record<string, unknown> | null = null;
+
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          anthropic: {
+            api_base_url: "https://api.anthropic.com",
+            style: "anthropic-messages",
+            allow_anonymous: true,
+            exports: ["claude-*"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async (input, init) => {
+        capturedUrl = String(input);
+        capturedBody = JSON.parse(decoder.decode(new Uint8Array(init?.body as ArrayBuffer)));
+        return new Response(
+          JSON.stringify({
+            id: "msg_1",
+            model: "claude-sonnet-4",
+            content: [{ type: "text", text: "hello" }],
+            stop_reason: "end_turn",
+            usage: { input_tokens: 10, output_tokens: 5 },
+          }),
+          { headers: { "content-type": "application/json; charset=utf-8" } },
+        );
+      }),
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "claude-sonnet-4",
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({ runtime, ctx });
+    expect(response.status).toBe(200);
+    expect(capturedUrl).toBe("https://api.anthropic.com/v1/messages");
+    expect(capturedBody).toEqual({
+      model: "claude-sonnet-4",
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+    });
+    expect(await response.json()).toEqual({
+      object: "chat.completion",
+      id: "msg_1",
+      model: "claude-sonnet-4",
+      usage: {
+        prompt_tokens: 10,
+        completion_tokens: 5,
+        total_tokens: 15,
+      },
+      choices: [{
+        index: 0,
+        message: { role: "assistant", content: "hello" },
+        finish_reason: "stop",
+      }],
+    });
+  });
+
+  it("routes google-genai providers through provider transport", async () => {
+    let capturedUrl = "";
+    let capturedBody: Record<string, unknown> | null = null;
+
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          google: {
+            api_base_url: "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent",
+            style: "google-genai",
+            allow_anonymous: true,
+            exports: ["gemini-*"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async (input, init) => {
+        capturedUrl = String(input);
+        capturedBody = JSON.parse(decoder.decode(new Uint8Array(init?.body as ArrayBuffer)));
+        return new Response(
+          JSON.stringify({
+            modelVersion: "gemini-2.5-flash",
+            candidates: [{
+              content: { parts: [{ text: "hello" }] },
+              finishReason: "STOP",
+            }],
+          }),
+          { headers: { "content-type": "application/json; charset=utf-8" } },
+        );
+      }),
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "gemini-2.5-flash",
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({ runtime, ctx });
+    expect(response.status).toBe(200);
+    expect(capturedUrl).toBe("https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent");
+    expect(capturedBody).toEqual({
+      model: "gemini-2.5-flash",
+      contents: [{ role: "user", parts: [{ text: "hi" }] }],
+    });
+    expect(await response.json()).toEqual({
+      object: "chat.completion",
+      model: "gemini-2.5-flash",
+      choices: [{
+        index: 0,
+        message: { role: "assistant", content: "hello" },
+        finish_reason: "stop",
+      }],
+    });
+  });
+
+  it("routes executor-backed aliases without re-entering provider transport", async () => {
+    const fetchImpl = vi.fn(async () => {
+      throw new Error("fetch should not be called");
+    });
+
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {},
+        executors: {
+          enei: {
+            exports: ["enei-*"],
+            models: {
+              "enei-1": { executor: "enei-1" },
+            },
+          },
+        },
+      },
+      fetchImpl,
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "enei-1",
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({
+      runtime,
+      ctx,
+      executors: {
+        "enei-1": {
+          async execute(request) {
+            return appendAssistantMessage(request, "done");
+          },
+          async *stream(request) {
+            yield appendAssistantMessage(request, "done");
+          },
+        },
+      },
+    });
+
+    expect(fetchImpl).not.toHaveBeenCalled();
+    expect(response.headers.get("x-openairouter-executor-id")).toBe("enei-1");
+    expect(await response.json()).toEqual({
+      object: "chat.completion",
+      choices: [
+        {
+          index: 0,
+          message: { role: "assistant", content: "done" },
+          finish_reason: "stop",
+        },
+      ],
+    });
+  });
+
+  it("streams provider chunks as openai sse output", async () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            allow_anonymous: true,
+            exports: ["gpt-4o"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async () => {
+        const stream = new ReadableStream<Uint8Array>({
+          start(controller) {
+            controller.enqueue(
+              encoder.encode(
+                `data: ${JSON.stringify({
+                  id: "chunk_1",
+                  model: "gpt-4o",
+                  choices: [{ index: 0, delta: { role: "assistant", content: "Hi" } }],
+                })}\n\n`,
+              ),
+            );
+            controller.enqueue(
+              encoder.encode(
+                `data: ${JSON.stringify({
+                  id: "chunk_1",
+                  model: "gpt-4o",
+                  choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+                })}\n\n`,
+              ),
+            );
+            controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+            controller.close();
+          },
+        });
+
+        return new Response(stream, {
+          headers: { "content-type": "text/event-stream; charset=utf-8" },
+        });
+      }),
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "gpt-4o",
+          stream: true,
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({ runtime, ctx });
+    const text = await response.text();
+
+    expect(response.headers.get("content-type")).toBe("text/event-stream; charset=utf-8");
+    expect(text).toContain("\"content\":\"Hi\"");
+    expect(text).toContain("\"finish_reason\":\"stop\"");
+    expect(text).toContain("data: [DONE]");
+  });
+
+  it("returns a gateway timeout when the upstream provider hangs", async () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            api_base_url: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            allow_anonymous: true,
+            exports: ["gpt-4o"],
+            no_prefix: true,
+          },
+        },
+        executors: {},
+      },
+      fetchImpl: vi.fn(async (_input, init) => {
+        return await new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener(
+            "abort",
+            () => reject(init.signal?.reason ?? new Error("aborted")),
+            { once: true },
+          );
+        });
+      }),
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "gpt-4o",
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({
+      runtime,
+      ctx,
+      upstreamTimeoutMs: 5,
+    });
+
+    expect(response.status).toBe(504);
+    expect(await response.json()).toEqual({
+      error: {
+        message: "Upstream provider timed out after 5ms",
+        type: "invalid_request_error",
+        param: null,
+        code: "upstream_timeout",
+      },
+    });
+  });
+});