@hebo-ai/gateway 0.9.2 → 0.9.3

package/dist/endpoints/chat-completions/schema.js

@@ -0,0 +1,252 @@
+import * as z from "zod";
+import { CacheControlSchema as ChatCompletionsCacheControlSchema, ReasoningEffortSchema as ChatCompletionsReasoningEffortSchema, ReasoningConfigSchema as ChatCompletionsReasoningConfigSchema, ServiceTierSchema as ChatCompletionsServiceTierSchema, ProviderMetadataSchema as ChatCompletionsProviderMetadataSchema, ContentPartAudioSchema as ChatCompletionsContentPartAudioSchema, } from "../shared/schema";
+export { ChatCompletionsCacheControlSchema, ChatCompletionsReasoningEffortSchema, ChatCompletionsReasoningConfigSchema, ChatCompletionsServiceTierSchema, ChatCompletionsProviderMetadataSchema, ChatCompletionsContentPartAudioSchema, };
+export const ChatCompletionsContentPartTextSchema = z.object({
+    type: z.literal("text"),
+    text: z.string(),
+    // Extension origin: Anthropic/OpenRouter/Vercel
+    cache_control: ChatCompletionsCacheControlSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsContentPartImageSchema = z.object({
+    type: z.literal("image_url"),
+    image_url: z.object({
+        url: z.string(),
+        detail: z.enum(["low", "high", "auto"]).optional(),
+    }),
+    // Extension origin: OpenRouter/Vercel/Anthropic
+    cache_control: ChatCompletionsCacheControlSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsContentPartFileSchema = z.object({
+    type: z.literal("file"),
+    file: z.object({
+        data: z.string(),
+        media_type: z.string(),
+        filename: z.string().optional(),
+    }),
+    // Extension origin: OpenRouter/Vercel/Anthropic
+    cache_control: ChatCompletionsCacheControlSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsContentPartSchema = z.discriminatedUnion("type", [
+    ChatCompletionsContentPartTextSchema,
+    ChatCompletionsContentPartImageSchema,
+    ChatCompletionsContentPartFileSchema,
+    ChatCompletionsContentPartAudioSchema,
+]);
+export const ChatCompletionsToolCallSchema = z.object({
+    type: z.literal("function"),
+    id: z.string(),
+    function: z.object({
+        arguments: z.string(),
+        name: z.string(),
+    }),
+    // Extension origin: Gemini
+    extra_content: ChatCompletionsProviderMetadataSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsSystemMessageSchema = z.object({
+    role: z.literal("system"),
+    content: z.string(),
+    name: z.string().optional(),
+    // Extension origin: OpenRouter/Vercel/Anthropic
+    cache_control: ChatCompletionsCacheControlSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsUserMessageSchema = z.object({
+    role: z.literal("user"),
+    content: z.union([z.string(), z.array(ChatCompletionsContentPartSchema)]),
+    name: z.string().optional(),
+    // Extension origin: OpenRouter/Vercel/Anthropic
+    cache_control: ChatCompletionsCacheControlSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsReasoningDetailSchema = z.object({
+    id: z.string().optional(),
+    index: z.int().nonnegative(),
+    type: z.string(),
+    text: z.string().optional(),
+    signature: z.string().optional(),
+    data: z.string().optional(),
+    summary: z.string().optional(),
+    format: z.string().optional(),
+});
+export const ChatCompletionsAssistantMessageSchema = z.object({
+    role: z.literal("assistant"),
+    content: z
+        .union([z.string(), z.null(), z.array(ChatCompletionsContentPartTextSchema)])
+        .optional(),
+    name: z.string().optional(),
+    // FUTURE: This should also support Custom Tool Calls
+    tool_calls: z.array(ChatCompletionsToolCallSchema).optional(),
+    // Extension origin: OpenRouter/Vercel
+    reasoning: z.string().optional().meta({ extension: true }),
+    // Extension origin: OpenRouter/Vercel
+    reasoning_details: z
+        .array(ChatCompletionsReasoningDetailSchema)
+        .optional()
+        .meta({ extension: true }),
+    // Extension origin: Gemini
+    extra_content: ChatCompletionsProviderMetadataSchema.optional().meta({ extension: true }),
+    // Extension origin: OpenRouter/Vercel/Anthropic
+    cache_control: ChatCompletionsCacheControlSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsToolMessageSchema = z.object({
+    role: z.literal("tool"),
+    content: z.union([z.string(), z.array(ChatCompletionsContentPartTextSchema)]),
+    tool_call_id: z.string(),
+});
+export const ChatCompletionsMessageSchema = z.discriminatedUnion("role", [
+    ChatCompletionsSystemMessageSchema,
+    ChatCompletionsUserMessageSchema,
+    ChatCompletionsAssistantMessageSchema,
+    ChatCompletionsToolMessageSchema,
+]);
+export const ChatCompletionsToolSchema = z.object({
+    type: z.literal("function"),
+    function: z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        parameters: z.record(z.string(), z.unknown()),
+        strict: z.boolean().optional(),
+    }),
+    // FUTURE: cache_control support on tools
+});
+const ChatCompletionsNamedFunctionToolChoiceSchema = z.object({
+    type: z.literal("function"),
+    function: z.object({
+        name: z.string(),
+    }),
+});
+const ChatCompletionsAllowedFunctionToolChoiceSchema = z.object({
+    type: z.literal("allowed_tools"),
+    allowed_tools: z.object({
+        mode: z.enum(["auto", "required"]),
+        tools: z.array(ChatCompletionsNamedFunctionToolChoiceSchema).nonempty(),
+    }),
+});
+export const ChatCompletionsToolChoiceSchema = z.union([
+    z.enum(["none", "auto", "required", "validated"]),
+    z.discriminatedUnion("type", [
+        ChatCompletionsNamedFunctionToolChoiceSchema,
+        ChatCompletionsAllowedFunctionToolChoiceSchema,
+    ]),
+    // FUTURE: Missing CustomTool
+]);
+export const ChatCompletionsResponseFormatJsonSchema = z.object({
+    // FUTURE: consider support for legacy json_object (if demand)
+    type: z.literal("json_schema"),
+    json_schema: z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        schema: z.record(z.string(), z.unknown()),
+        // FUTURE: consider support for non-strict mode (for providers that support it)
+        strict: z.boolean().optional(),
+    }),
+});
+export const ChatCompletionsResponseFormatTextSchema = z.object({
+    type: z.literal("text"),
+});
+export const ChatCompletionsResponseFormatSchema = z.discriminatedUnion("type", [
+    ChatCompletionsResponseFormatJsonSchema,
+    ChatCompletionsResponseFormatTextSchema,
+]);
+export const ChatCompletionsMetadataSchema = z.record(z.string().min(1).max(64), z.string().max(512));
+const ChatCompletionsInputsSchema = z.object({
+    messages: z.array(ChatCompletionsMessageSchema),
+    tools: z.array(ChatCompletionsToolSchema).optional(),
+    tool_choice: ChatCompletionsToolChoiceSchema.optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    max_tokens: z.int().nonnegative().optional(),
+    max_completion_tokens: z.int().nonnegative().optional(),
+    frequency_penalty: z.number().min(-2.0).max(2.0).optional(),
+    presence_penalty: z.number().min(-2.0).max(2.0).optional(),
+    seed: z.int().optional(),
+    stop: z.union([z.string(), z.array(z.string())]).optional(),
+    top_p: z.number().min(0).max(1.0).optional(),
+    metadata: ChatCompletionsMetadataSchema.optional(),
+    response_format: ChatCompletionsResponseFormatSchema.optional(),
+    reasoning_effort: ChatCompletionsReasoningEffortSchema.optional(),
+    service_tier: ChatCompletionsServiceTierSchema.optional(),
+    prompt_cache_key: z.string().optional(),
+    prompt_cache_retention: z.enum(["in-memory", "24h"]).optional(),
+    parallel_tool_calls: z.boolean().optional(),
+    // FUTURE: OpenAI configurations
+    // logprobs: z.boolean().optional(),
+    // top_logprobs: z.number().int().optional(),
+    // user: z.string().optional(),
+    // Extension origin: OpenRouter/Vercel/Anthropic
+    cache_control: ChatCompletionsCacheControlSchema.optional().meta({ extension: true }),
+    // Extension origin: OpenRouter
+    reasoning: ChatCompletionsReasoningConfigSchema.optional().meta({ extension: true }),
+    // Extension origin: Gemini extra_body
+    // https://docs.cloud.google.com/vertex-ai/generative-ai/docs/migrate/openai/overview#extra_body
+    extra_body: ChatCompletionsProviderMetadataSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsBodySchema = z.looseObject({
+    model: z.string(),
+    stream: z.boolean().optional(),
+    ...ChatCompletionsInputsSchema.shape,
+});
+export const ChatCompletionsFinishReasonSchema = z.enum([
+    "stop",
+    "length",
+    "content_filter",
+    "tool_calls",
+]);
+export const ChatCompletionsChoiceSchema = z.object({
+    index: z.int().nonnegative(),
+    message: ChatCompletionsAssistantMessageSchema,
+    finish_reason: ChatCompletionsFinishReasonSchema,
+    // FUTURE: model this out
+    logprobs: z.unknown().optional(),
+});
+export const ChatCompletionsUsageSchema = z.object({
+    prompt_tokens: z.int().nonnegative().optional(),
+    completion_tokens: z.int().nonnegative().optional(),
+    total_tokens: z.int().nonnegative().optional(),
+    completion_tokens_details: z
+        .object({
+        // FUTURE: add missing properties
+        reasoning_tokens: z.int().nonnegative().optional(),
+    })
+        .optional(),
+    prompt_tokens_details: z
+        .object({
+        // FUTURE: add missing properties
+        cached_tokens: z.int().nonnegative().optional(),
+        // Extension origin: OpenRouter
+        cache_write_tokens: z.int().nonnegative().optional().meta({ extension: true }),
+    })
+        .optional(),
+});
+export const ChatCompletionsSchema = z.object({
+    id: z.string(),
+    object: z.literal("chat.completion"),
+    created: z.int().nonnegative(),
+    model: z.string(),
+    choices: z.array(ChatCompletionsChoiceSchema),
+    usage: ChatCompletionsUsageSchema.nullable(),
+    service_tier: ChatCompletionsServiceTierSchema.optional(),
+    // Extension origin: Vercel AI Gateway
+    provider_metadata: ChatCompletionsProviderMetadataSchema.optional().meta({ extension: true }),
+});
+export const ChatCompletionsToolCallDeltaSchema = ChatCompletionsToolCallSchema.partial().extend({
+    index: z.int().nonnegative(),
+});
+export const ChatCompletionsAssistantMessageDeltaSchema = ChatCompletionsAssistantMessageSchema.partial().extend({
+    tool_calls: z.array(ChatCompletionsToolCallDeltaSchema).optional(),
+});
+export const ChatCompletionsChoiceDeltaSchema = z.object({
+    index: z.int().nonnegative(),
+    delta: ChatCompletionsAssistantMessageDeltaSchema,
+    finish_reason: ChatCompletionsFinishReasonSchema.nullable(),
+    // FUTURE: model this out
+    logprobs: z.unknown().optional(),
+});
+export const ChatCompletionsChunkSchema = z.object({
+    id: z.string(),
+    object: z.literal("chat.completion.chunk"),
+    created: z.int().nonnegative(),
+    model: z.string(),
+    choices: z.array(ChatCompletionsChoiceDeltaSchema),
+    usage: ChatCompletionsUsageSchema.nullable(),
+    service_tier: ChatCompletionsServiceTierSchema.optional(),
+    // Extension origin: Vercel AI Gateway
+    provider_metadata: ChatCompletionsProviderMetadataSchema.optional().meta({ extension: true }),
+});

package/dist/endpoints/conversations/converters.d.ts

@@ -0,0 +1,8 @@
+import type { Conversation, ConversationItem, ConversationDeleted } from "./schema";
+import type { ConversationEntity, ConversationItemEntity } from "./storage/types";
+export declare function toConversation(entity: ConversationEntity): Conversation;
+export declare function toConversationItem(entity: ConversationItemEntity): ConversationItem;
+export declare function toConversationDeleted(result: {
+    id: string;
+    deleted: boolean;
+}): ConversationDeleted;

package/dist/endpoints/conversations/converters.js

@@ -0,0 +1,29 @@
+export function toConversation(entity) {
+    return {
+        id: entity.id,
+        object: "conversation",
+        created_at: Math.floor(entity.created_at / 1000),
+        metadata: entity.metadata,
+    };
+}
+export function toConversationItem(entity) {
+    const item = {};
+    for (const key in entity) {
+        if (key === "conversation_id")
+            continue;
+        if (key === "created_at") {
+            item["created_at"] = Math.floor(entity["created_at"] / 1000);
+            continue;
+        }
+        item[key] = entity[key];
+    }
+    item["object"] = "conversation.item";
+    return item;
+}
+export function toConversationDeleted(result) {
+    return {
+        id: result.id,
+        deleted: result.deleted,
+        object: "conversation.deleted",
+    };
+}

package/dist/endpoints/conversations/handler.d.ts

@@ -0,0 +1,2 @@
+import type { Endpoint, GatewayConfig } from "../../types";
+export declare const conversations: (config: GatewayConfig) => Endpoint;

package/dist/endpoints/conversations/handler.js

@@ -0,0 +1,259 @@
+import * as z from "zod";
+import { parseConfig } from "../../config";
+import { GatewayError } from "../../errors/gateway";
+import { winterCgHandler } from "../../lifecycle";
+import { logger } from "../../logger";
+import { addSpanEvent } from "../../telemetry/span";
+import { parseRequestBody } from "../../utils/body";
+import { toConversation, toConversationItem, toConversationDeleted } from "./converters";
+import { ConversationCreateParamsSchema, ConversationItemsAddBodySchema, ConversationUpdateBodySchema, ConversationItemListParamsSchema, ConversationListParamsSchema, } from "./schema";
+export const conversations = (config) => {
+    const parsedConfig = parseConfig(config);
+    const storage = parsedConfig.storage;
+    async function list(ctx, searchParams) {
+        const params = Object.fromEntries(searchParams.entries());
+        const parsed = ConversationListParamsSchema.safeParse(params);
+        if (!parsed.success) {
+            throw new GatewayError(z.prettifyError(parsed.error), 400, undefined, parsed.error);
+        }
+        const { limit, after, order, metadata } = parsed.data;
+        // Treat limit 0 as unlimited (up to 100,000 items)
+        const entities = await storage.listConversations({
+            limit: limit ? limit + 1 : 100000,
+            after,
+            order,
+            metadata: metadata,
+        });
+        logger.trace({ requestId: ctx.requestId, count: entities.length }, "[storage] listConversations result");
+        const has_more = limit !== 0 && entities.length > limit;
+        const targetLength = limit > 0 && entities.length > limit ? limit : entities.length;
+        const data = [];
+        for (let i = 0; i < targetLength; i++) {
+            const entity = entities[i];
+            if (entity) {
+                data.push(toConversation(entity));
+            }
+        }
+        return {
+            object: "list",
+            data,
+            has_more,
+            first_id: data[0]?.id,
+            last_id: data.at(-1)?.id,
+        };
+    }
+    async function create(ctx) {
+        const body = await parseRequestBody(ctx.request, parsedConfig.maxBodySize);
+        addSpanEvent("hebo.request.deserialized");
+        const parsed = ConversationCreateParamsSchema.safeParse(body);
+        if (!parsed.success) {
+            throw new GatewayError(z.prettifyError(parsed.error), 400, undefined, parsed.error);
+        }
+        addSpanEvent("hebo.request.parsed");
+        const entity = await storage.createConversation({
+            metadata: parsed.data.metadata,
+            items: parsed.data.items,
+        });
+        logger.debug(`[conversations] created conversation: ${entity.id}`);
+        logger.trace({ requestId: ctx.requestId, entity }, "[storage] createConversation result");
+        return toConversation(entity);
+    }
+    async function retrieve(ctx, conversationId) {
+        const entity = await storage.getConversation(conversationId);
+        logger.trace({ requestId: ctx.requestId, entity }, "[storage] getConversation result");
+        if (!entity) {
+            throw new GatewayError("Conversation not found", 404);
+        }
+        return toConversation(entity);
+    }
+    async function update(ctx, conversationId) {
+        const body = await parseRequestBody(ctx.request, parsedConfig.maxBodySize);
+        addSpanEvent("hebo.request.deserialized");
+        const parsed = ConversationUpdateBodySchema.safeParse(body);
+        if (!parsed.success) {
+            throw new GatewayError(z.prettifyError(parsed.error), 400, undefined, parsed.error);
+        }
+        addSpanEvent("hebo.request.parsed");
+        const entity = await storage.updateConversation(conversationId, parsed.data.metadata);
+        if (!entity) {
+            throw new GatewayError("Conversation not found", 404);
+        }
+        logger.debug(`[conversations] updated conversation: ${conversationId}`);
+        logger.trace({ requestId: ctx.requestId, entity }, "[storage] updateConversation result");
+        return toConversation(entity);
+    }
+    async function remove(ctx, conversationId) {
+        const result = await storage.deleteConversation(conversationId);
+        logger.debug(`[conversations] deleted conversation: ${conversationId}`);
+        logger.trace({ requestId: ctx.requestId, result }, "[storage] deleteConversation result");
+        return toConversationDeleted(result);
+    }
+    async function retrieveItem(ctx, conversationId, itemId) {
+        const entity = await storage.getItem(conversationId, itemId);
+        logger.trace({ requestId: ctx.requestId, entity }, "[storage] getItem result");
+        if (!entity) {
+            throw new GatewayError("Item not found", 404);
+        }
+        return toConversationItem(entity);
+    }
+    async function deleteItem(ctx, conversationId, itemId) {
+        const entity = await storage.deleteItem(conversationId, itemId);
+        logger.debug(`[conversations] deleted item ${itemId} from conversation: ${conversationId}`);
+        logger.trace({ requestId: ctx.requestId, entity }, "[storage] deleteItem result");
+        if (!entity) {
+            throw new GatewayError("Conversation not found", 404);
+        }
+        return toConversation(entity);
+    }
+    async function listItems(ctx, conversationId, searchParams) {
+        const params = Object.fromEntries(searchParams.entries());
+        const parsed = ConversationItemListParamsSchema.safeParse(params);
+        if (!parsed.success) {
+            throw new GatewayError(z.prettifyError(parsed.error), 400, undefined, parsed.error);
+        }
+        const { limit, after, order } = parsed.data;
+        // Treat limit 0 as unlimited (up to 100,000 items)
+        const entities = await storage.listItems(conversationId, {
+            limit: limit ? limit + 1 : 100000,
+            after,
+            order,
+        });
+        logger.trace({ requestId: ctx.requestId, conversationId, itemCount: entities?.length }, "[storage] listItems result");
+        if (!entities)
+            throw new GatewayError("Conversation not found", 404);
+        const has_more = limit !== 0 && entities.length > limit;
+        const targetLength = limit > 0 && entities.length > limit ? limit : entities.length;
+        const data = [];
+        for (let i = 0; i < targetLength; i++) {
+            const entity = entities[i];
+            if (entity) {
+                data.push(toConversationItem(entity));
+            }
+        }
+        return {
+            object: "list",
+            data,
+            has_more,
+            first_id: data[0]?.id,
+            last_id: data.at(-1)?.id,
+        };
+    }
+    async function addItems(ctx, conversationId) {
+        const body = await parseRequestBody(ctx.request, parsedConfig.maxBodySize);
+        addSpanEvent("hebo.request.deserialized");
+        const parsed = ConversationItemsAddBodySchema.safeParse(body);
+        if (!parsed.success) {
+            throw new GatewayError(z.prettifyError(parsed.error), 400, undefined, parsed.error);
+        }
+        addSpanEvent("hebo.request.parsed");
+        const entities = await storage.addItems(conversationId, parsed.data.items);
+        if (!entities) {
+            throw new GatewayError("Conversation not found", 404);
+        }
+        logger.debug(`[conversations] added ${entities.length} items to conversation: ${conversationId}`);
+        logger.trace({ requestId: ctx.requestId, conversationId, itemCount: entities.length }, "[storage] addItems result");
+        const dataLength = entities.length;
+        const data = [];
+        for (let i = 0; i < dataLength; i++) {
+            const entity = entities[i];
+            if (entity) {
+                data.push(toConversationItem(entity));
+            }
+        }
+        return {
+            object: "list",
+            data,
+            has_more: false,
+            first_id: data[0]?.id,
+            last_id: data.at(-1)?.id,
+        };
+    }
+    const handler = async (ctx) => {
+        ctx.operation = "conversations";
+        addSpanEvent("hebo.handler.started");
+        const url = new URL(ctx.request.url);
+        const rawSegments = url.pathname.split("/");
+        const segments = [];
+        for (let i = 0; i < rawSegments.length; i++) {
+            const segment = rawSegments[i];
+            if (segment) {
+                segments.push(segment);
+            }
+        }
+        let rootIndex = -1;
+        for (let i = 0; i < segments.length; i++) {
+            if (segments[i] === "conversations") {
+                rootIndex = i;
+                break;
+            }
+        }
+        if (rootIndex === -1) {
+            throw new GatewayError("Not Found", 404);
+        }
+        const len = segments.length - rootIndex;
+        let result;
+        // GET/POST /conversations (List/Create)
+        if (len === 1) {
+            if (ctx.request.method === "GET") {
+                result = await list(ctx, url.searchParams);
+            }
+            else if (ctx.request.method === "POST") {
+                result = await create(ctx);
+            }
+            else {
+                throw new GatewayError("Method Not Allowed", 405);
+            }
+        }
+        // GET/POST/DELETE /conversations/{id} (Conversation Instance)
+        else if (len === 2) {
+            const conversationId = segments[rootIndex + 1];
+            logger.debug(`[conversations] resolved conversation ID: ${conversationId}`);
+            if (ctx.request.method === "GET") {
+                result = await retrieve(ctx, conversationId);
+            }
+            else if (ctx.request.method === "POST") {
+                result = await update(ctx, conversationId);
+            }
+            else if (ctx.request.method === "DELETE") {
+                result = await remove(ctx, conversationId);
+            }
+            else {
+                throw new GatewayError("Method Not Allowed", 405);
+            }
+        }
+        // GET/POST /conversations/{id}/items
+        else if (len === 3 && segments[rootIndex + 2] === "items") {
+            const conversationId = segments[rootIndex + 1];
+            logger.debug(`[conversations] list/add items for conversation ID: ${conversationId}`);
+            if (ctx.request.method === "GET") {
+                result = await listItems(ctx, conversationId, url.searchParams);
+            }
+            else if (ctx.request.method === "POST") {
+                result = await addItems(ctx, conversationId);
+            }
+            else {
+                throw new GatewayError("Method Not Allowed", 405);
+            }
+        }
+        // GET/DELETE /conversations/{id}/items/{item_id}
+        else if (len === 4 && segments[rootIndex + 2] === "items") {
+            const conversationId = segments[rootIndex + 1];
+            const itemId = segments[rootIndex + 3];
+            logger.debug(`[conversations] item access: conversation ID=${conversationId}, item ID=${itemId}`);
+            if (ctx.request.method === "GET") {
+                result = await retrieveItem(ctx, conversationId, itemId);
+            }
+            else if (ctx.request.method === "DELETE") {
+                result = await deleteItem(ctx, conversationId, itemId);
+            }
+            else {
+                throw new GatewayError("Method Not Allowed", 405);
+            }
+        }
+        else {
+            throw new GatewayError("Not Found", 404);
+        }
+        return result;
+    };
+    return { handler: winterCgHandler(handler, parsedConfig) };
+};

package/dist/endpoints/conversations/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./handler";
+export * from "./schema";
+export * from "./storage/types";

package/dist/endpoints/conversations/index.js

@@ -0,0 +1,3 @@
+export * from "./handler";
+export * from "./schema";
+export * from "./storage/types";