@hebo-ai/gateway 0.2.1 → 0.3.0-rc.1

package/README.md

@@ -2,13 +2,15 @@
 
 Roll your own AI gateway for full control over models, providers, routing logic, guardrails, observability and more ...
 
-## Overview
+## 🐒 Overview
 
 Existing AI gateways like OpenRouter, Vercel AI Gateway, LiteLLM, and Portkey work out of the box, but they’re hard to extend once your needs go beyond configuration.
 
 Hebo Gateway is an open-source, embeddable AI gateway framework built to live inside your app. It gives you full control over providers, models, routing, and the request lifecycle.
 
-## Features
+Learn more in our blog post: [Yet Another AI Gateway?](https://hebo.ai/blog/260127-hebo-gateway/) (`https://hebo.ai/blog/260127-hebo-gateway/`)
+
+## 🍌 Features
 
 - 🌐 OpenAI-compatible /chat/completions, /embeddings & /models endpoints.
 - 🔌 Integrate into your existing Hono, Elysia, Next.js & TanStack apps.
@@ -18,13 +20,28 @@ Hebo Gateway is an open-source, embeddable AI gateway framework built to live in
 - 🪝 Hook system to customize routing, auth, rate limits, and shape responses.
 - 🧰 Low-level OpenAI-compatible schema, converters, and middleware helpers.
 
-## Installation
+## 📦 Installation
 
 ```bash
 bun install @hebo-ai/gateway
 ```
 
-## Quickstart
+## ☰ Table of Contents
+
+- Quickstart
+  - [Setup A Gateway Instance](#setup-a-gateway-instance) | [Mount Route Handlers](#mount-route-handlers) | [Call the Gateway](#call-the-gateway)
+- Configuration Reference
+  - [Providers](#providers) | [Models](#models) | [Hooks](#hooks) | [Logger](#logger-settings)
+- Framework Support
+  - [ElysiaJS](#elysiajs) | [Hono](#hono) | [Next.js](#nextjs) | [TanStack Start](#tanstack-start)
+- Runtime Support
+  - [Vercel Edge](#vercel-edge) | [Cloudflare Workers](#cloudflare-workers) | [Deno Deploy](#deno-deploy) | [AWS Lambda](#aws-lambda)
+- OpenAI Extensions
+  - [Reasoning](#reasoning)
+- Advanced Usage
+  - [Passing Framework State to Hooks](#passing-framework-state-to-hooks) | [Selective Route Mounting](#selective-route-mounting) | [Low-level Schemas & Converters](#low-level-schemas--converters)
+
+## 🚀 Quickstart
 
 ### Setup A Gateway Instance
 
@@ -113,7 +130,7 @@ const { text } = await generateText({
 console.log(text);
 ```
 
-## Configuration Reference
+## ⚙️ Configuration Reference
 
 ### Providers
 
@@ -316,25 +333,27 @@ const gw = gateway({
     },
     /**
      * Runs after the endpoint handler.
-     * @param ctx.response Response returned by the handler.
-     * @returns Response to replace, or undefined to keep original.
+     * @param ctx.result Result object returned by the handler.
+     * @returns Modified result, or undefined to keep original.
      */
-    after: async (ctx: { response: Response }): Promise<Response | void> => {
+    after: async (ctx: {
+      result: object | ReadableStream<Uint8Array>
+    }): Promise<object | ReadableStream<Uint8Array> | void> => {
       // Example Use Cases:
-      // - Transform response
-      // - Response logging
+      // - Transform result
+      // - Result logging
       return undefined;
     },
   },
 });
 ```
 
-The `ctx` object is **readonly for core fields**. Use return values to override request / response and provide modelId / provider instances.
+The `ctx` object is **readonly for core fields**. Use return values to override request / result and to provide modelId / provider instances.
 
 > [!TIP]
 > To pass data between hooks, use `ctx.state`. It’s a per-request mutable bag in which you can stash things like auth info, routing decisions, timers, or trace IDs and read them later again in any of the other hooks.
 
-## Framework Support
+## 🧩 Framework Support
 
 Hebo Gateway exposes **WinterCG-compatible** handlers that integrate with almost any existing framework.
 
@@ -362,7 +381,9 @@ export default new Hono().mount("/v1/gateway/", gw.handler);
 console.log(`🐒 Hebo Gateway is running with Hono framework`);
 ```
 
-### Next.js (App Router)
+### Next.js
+
+#### App Router
 
 `app/api/gateway/[...all]/route.ts`
 
@@ -376,7 +397,7 @@ const gw = gateway({
 export const POST = gw.handler, GET = gw.handler;
 ```
 
-### Next.js (Pages Router)
+#### Pages Router
 
 `pages/api/gateway/[...all].ts`
 
@@ -416,7 +437,69 @@ export const Route = createFileRoute("/api/$")({
 });
 ```
 
-## OpenAI Extensions
+## 🌍 Runtime Support
+
+Hebo Gateway also works directly with runtime-level `Request -> Response` handlers.
+
+### Vercel Edge
+
+`api/gateway.ts`
+
+```ts
+export const runtime = "edge";
+
+const gw = gateway({
+  // ...
+});
+
+export default gw.handler;
+```
+
+### Cloudflare Workers
+
+`src/index.ts`
+
+```ts
+const gw = gateway({
+  // ...
+});
+
+export default {
+  fetch: gw.handler,
+};
+```
+
+### Deno Deploy
+
+`main.ts`
+
+```ts
+import { serve } from "https://deno.land/std/http/server.ts";
+
+const gw = gateway({
+  // ...
+});
+
+serve((request: Request) => gw.handler(request));
+```
+
+### AWS Lambda
+
+`src/lambda.ts`
+
+```ts
+import { awsLambdaEventHandler } from "@hattip/adapter-aws-lambda";
+
+const gw = gateway({
+  // ...
+});
+
+export const handler = awsLambdaEventHandler({
+  handler: gw.handler,
+});
+```
+
+## 🧠 OpenAI Extensions
 
 ### Reasoning
 
@@ -449,7 +532,41 @@ Reasoning output is surfaced as extension to the `completion` object.
 
 Most SDKs handle these fields out-of-the-box.
 
-## Advanced Usage
+## 🧪 Advanced Usage
+
+### Logger Settings
+
+You can configure logging via the `logger` field in the gateway config. By default, the logger uses `console` and sets the level to `debug` in non-production and `info` in production (based on the `NODE_ENV` environment variable).
+
+```ts
+import { gateway } from "@hebo-ai/gateway";
+
+const gw = gateway({
+  // ...
+  logger: {
+    level: "debug", // "trace" | "debug" | "info" | "warn" | "error" | "silent"
+  },
+});
+```
+
+If you provide a custom logger, it must implement `trace`, `debug`, `info`, `warn`, and `error` methods.
+For production workloads, we recommend `pino` for better logging performance and lower overhead.
+
+Example with **pino**:
+
+```ts
+import pino from "pino";
+import { gateway } from "@hebo-ai/gateway";
+
+const gw = gateway({
+  // ...
+  logger: pino(
+    {
+      level: "info"
+    }
+  ),
+});
+```
 
 ### Passing Framework State to Hooks
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@hebo-ai/gateway",
-  "version": "0.2.1",
-  "description": "Hebo Gateway - Roll your own AI gateway for full control over models, providers, routing logic, guardrails, observability and more.",
+  "version": "0.3.0-rc.1",
+  "description": "AI gateway as a framework. For full control over models, routing & lifecycle. OpenAI-compatible /chat/completions, /embeddings & /models.",
   "keywords": [
     "ai",
+    "ai-gateway",
     "anthropic",
     "bedrock",
     "elysiajs",
@@ -11,10 +12,13 @@
     "groq",
     "hono",
     "llm",
+    "llm-gateway",
+    "llmops",
     "nextjs",
     "openai",
     "tanstack-start",
     "vercel-ai-sdk",
+    "vertex",
     "voyage"
   ],
   "homepage": "https://hebo.ai/gateway",
@@ -34,8 +38,10 @@
   ],
   "type": "module",
   "sideEffects": [
+    "./dist/logger/index.js",
     "./dist/providers/**/*.js",
     "./dist/models/**/*.js",
+    "./src/logger/index.ts",
     "./src/providers/**/*.ts",
     "./src/models/**/*.ts"
   ],
@@ -45,11 +51,6 @@
       "import": "./dist/index.js",
       "dev-source": "./src/index.ts"
     },
-    "./endpoints": {
-      "types": "./dist/endpoints/index.d.ts",
-      "import": "./dist/endpoints/index.js",
-      "dev-source": "./src/endpoints/index.ts"
-    },
     "./endpoints/chat-completions": {
       "types": "./dist/endpoints/chat-completions/index.d.ts",
       "import": "./dist/endpoints/chat-completions/index.js",
@@ -65,6 +66,11 @@
       "import": "./dist/endpoints/models/index.js",
       "dev-source": "./src/endpoints/models/index.ts"
     },
+    "./errors/openai": {
+      "types": "./dist/errors/openai.d.ts",
+      "import": "./dist/errors/openai.js",
+      "dev-source": "./src/errors/openai.ts"
+    },
     "./middleware/common": {
       "types": "./dist/middleware/common.d.ts",
       "import": "./dist/middleware/common.js",
@@ -149,7 +155,9 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "^3.0.7",
+    "@ai-sdk/provider-utils": "^4.0.13",
     "ai": "^6.0.67",
+    "serialize-error": "^13.0.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -172,6 +180,7 @@
     "next": "^16.1.6",
     "oxfmt": "^0.24.0",
     "oxlint": "^1.42.0",
+    "pino": "^10.3.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vite-tsconfig-paths": "^6.0.5",

package/src/config.ts

@@ -1,3 +1,5 @@
+import { isLogger, logger, setLoggerInstance } from "./logger";
+import { createDefaultLogger } from "./logger/default";
 import { kParsed, type GatewayConfig, type GatewayConfigParsed } from "./types";
 
 export const parseConfig = (config: GatewayConfig): GatewayConfigParsed => {
@@ -5,30 +7,64 @@ export const parseConfig = (config: GatewayConfig): GatewayConfigParsed => {
   if (kParsed in config) return config as GatewayConfigParsed;
 
   const providers = config.providers ?? {};
+  const parsedProviders = {} as typeof providers;
   const models = config.models ?? {};
 
-  if (Object.keys(providers).length === 0) {
-    throw new Error("Gateway config error: no providers configured (config.providers is empty).");
+  // Set the global logger instance
+  if (config.logger === undefined) {
+    setLoggerInstance(createDefaultLogger({}));
+  } else if (config.logger !== null) {
+    setLoggerInstance(isLogger(config.logger) ? config.logger : createDefaultLogger(config.logger));
+
+    logger.info(
+      isLogger(config.logger)
+        ? `[logger] custom logger configured`
+        : `[logger] logger configured: level=${config.logger.level}`,
+    );
+  }
+
+  // Strip providers that are not configured
+  for (const id in providers) {
+    const provider = providers[id];
+    if (provider === undefined) {
+      logger.warn(`[config] ${id} provider removed (undefined)`);
+      continue;
+    }
+    parsedProviders[id] = provider;
   }
 
-  // Strip out providers from models that are not configured
+  if (Object.keys(parsedProviders).length === 0) {
+    throw new Error("No providers configured (config.providers is empty)");
+  }
+
+  // Strip providers that are not configured from models
   const parsedModels = {} as typeof models;
+  const warnings = new Set<string>();
   for (const id in models) {
     const model = models[id!];
 
     const kept: string[] = [];
 
     for (const p of model!.providers) {
-      if (p in providers) kept.push(p);
-      else console.warn(`[models] ${id}: provider "${p}" removed (not configured)`);
+      if (p in parsedProviders) kept.push(p);
+      else warnings.add(p);
     }
 
     if (kept.length > 0) parsedModels[id] = { ...model!, providers: kept };
   }
+  for (const warning of warnings) {
+    logger.warn(`[config] ${warning} provider removed (not configured)`);
+  }
 
   if (Object.keys(parsedModels).length === 0) {
-    throw new Error("Gateway config error: no models configured (config.models is empty).");
+    throw new Error("No models configured (config.models is empty)");
   }
 
-  return { ...config, providers, models: parsedModels, [kParsed]: true };
+  return {
+    ...config,
+    logger: config.logger,
+    providers: parsedProviders,
+    models: parsedModels,
+    [kParsed]: true,
+  };
 };

package/src/endpoints/chat-completions/converters.test.ts

@@ -1,8 +1,59 @@
+import type { GenerateTextResult, ToolSet, Output } from "ai";
+
 import { describe, expect, test } from "bun:test";
 
-import { convertToTextCallOptions } from "./converters";
+import { convertToTextCallOptions, toChatCompletionsAssistantMessage } from "./converters";
 
 describe("Chat Completions Converters", () => {
+  describe("toChatCompletionsAssistantMessage", () => {
+    test("should pass through providerMetadata to extra_content", () => {
+      const mockResult: GenerateTextResult<ToolSet, Output.Output> = {
+        content: [
+          {
+            type: "text",
+            text: "hello",
+            providerMetadata: {
+              vertex: {
+                thought_signature: "signature-abc",
+              },
+            },
+          } as any,
+        ],
+        toolCalls: [],
+      };
+
+      const message = toChatCompletionsAssistantMessage(mockResult);
+
+      expect(message.extra_content).toEqual({
+        vertex: {
+          thought_signature: "signature-abc",
+        },
+      });
+    });
+
+    test("should pass through providerMetadata to tool calls", () => {
+      const mockResult: GenerateTextResult<ToolSet, Output.Output> = {
+        content: [],
+        toolCalls: [
+          {
+            toolCallId: "call_123",
+            toolName: "get_weather",
+            input: { location: "London" },
+            providerMetadata: {
+              vertex: { thought_signature: "tool-signature" },
+            },
+          },
+        ],
+      };
+
+      const message = toChatCompletionsAssistantMessage(mockResult);
+
+      expect(message.tool_calls![0].extra_content).toEqual({
+        vertex: { thought_signature: "tool-signature" },
+      });
+    });
+  });
+
   describe("convertToTextCallOptions", () => {
     test("should use max_completion_tokens when present", () => {
       const result = convertToTextCallOptions({