@hebo-ai/gateway 0.6.2 → 0.8.0-rc0

package/dist/telemetry/memory.js

@@ -1,43 +0,0 @@
-import { metrics } from "@opentelemetry/api";
-const getMeter = () => metrics.getMeter("@hebo/gateway");
-const defaultHeapSpaceAttrs = { "v8js.heap.space.name": "total" };
-let registered = false;
-const isEnabled = (level) => level === "recommended" || level === "full";
-const observeMemory = (observe) => {
-    let usage;
-    try {
-        usage = globalThis.process?.memoryUsage?.();
-    }
-    catch {
-        return;
-    }
-    if (!usage)
-        return;
-    observe(usage.heapUsed, usage.rss);
-};
-export const observeV8jsMemoryMetrics = (level) => {
-    if (!isEnabled(level) || registered)
-        return;
-    registered = true;
-    const meter = getMeter();
-    meter
-        .createObservableGauge("v8js.memory.heap.used", {
-        description: "Used bytes in the V8 heap",
-        unit: "By",
-    })
-        .addCallback((result) => {
-        observeMemory((heapUsed) => {
-            result.observe(heapUsed, defaultHeapSpaceAttrs);
-        });
-    });
-    meter
-        .createObservableGauge("v8js.memory.heap.space.physical_size", {
-        description: "Physical bytes allocated for the V8 heap space",
-        unit: "By",
-    })
-        .addCallback((result) => {
-        observeMemory((_, rss) => {
-            result.observe(rss, defaultHeapSpaceAttrs);
-        });
-    });
-};

package/dist/telemetry/span.d.ts

@@ -1,13 +0,0 @@
-import type { Attributes, SpanOptions, Tracer } from "@opentelemetry/api";
-import type { TelemetrySignalLevel } from "../types";
-export declare const setSpanTracer: (tracer?: Tracer) => void;
-export declare const setSpanEventsEnabled: (level?: TelemetrySignalLevel) => void;
-export declare const startSpan: (name: string, options?: SpanOptions) => import("@opentelemetry/api").Span & {
-    runWithContext: <T>(fn: () => Promise<T> | T) => T | Promise<T>;
-    recordError: (_error: unknown) => void;
-    finish: () => void;
-    isExisting: boolean;
-};
-export declare const withSpan: <T>(name: string, run: () => Promise<T> | T, options?: SpanOptions) => Promise<T>;
-export declare const addSpanEvent: (name: string, attributes?: Attributes) => void;
-export declare const setSpanAttributes: (attributes?: Attributes) => void;

package/dist/telemetry/span.js

@@ -1,60 +0,0 @@
-import { INVALID_SPAN_CONTEXT, SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
-const DEFAULT_TRACER_NAME = "@hebo/gateway";
-let spanTracer;
-let spanEventsEnabled = false;
-const NOOP_SPAN = {
-    runWithContext: (fn) => fn(),
-    recordError: (_error) => { },
-    finish: () => { },
-    isExisting: true,
-};
-export const setSpanTracer = (tracer) => {
-    spanTracer = tracer ?? trace.getTracer(DEFAULT_TRACER_NAME);
-};
-export const setSpanEventsEnabled = (level) => {
-    spanEventsEnabled = level === "recommended" || level === "full";
-};
-export const startSpan = (name, options) => {
-    if (!spanTracer) {
-        return Object.assign(trace.wrapSpanContext(INVALID_SPAN_CONTEXT), NOOP_SPAN);
-    }
-    const parentContext = context.active();
-    const activeSpan = trace.getActiveSpan();
-    const span = spanTracer.startSpan(name, { kind: activeSpan ? SpanKind.INTERNAL : SpanKind.SERVER, ...options }, parentContext);
-    const runWithContext = (fn) => context.with(trace.setSpan(parentContext, span), fn);
-    const recordError = (error) => {
-        const err = error instanceof Error ? error : new Error(String(error));
-        span.recordException(err);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-    };
-    const finish = () => {
-        span.end();
-    };
-    return Object.assign(span, { runWithContext, recordError, finish, isExisting: !!activeSpan });
-};
-export const withSpan = async (name, run, options) => {
-    if (!spanTracer) {
-        return run();
-    }
-    const started = startSpan(name, options);
-    try {
-        return await started.runWithContext(run);
-    }
-    catch (error) {
-        started.recordError(error);
-        throw error;
-    }
-    finally {
-        started.finish();
-    }
-};
-export const addSpanEvent = (name, attributes) => {
-    if (!spanEventsEnabled)
-        return;
-    trace.getActiveSpan()?.addEvent(name, attributes);
-};
-export const setSpanAttributes = (attributes) => {
-    if (!attributes)
-        return;
-    trace.getActiveSpan()?.setAttributes(attributes);
-};

package/dist/telemetry/stream.d.ts

@@ -1,3 +0,0 @@
-export declare const wrapStream: (src: ReadableStream, hooks: {
-    onDone?: (status: number, reason: unknown) => void;
-}) => ReadableStream;

package/dist/telemetry/stream.js

@@ -1,58 +0,0 @@
-import { toOpenAIError } from "../errors/openai";
-const isErrorChunk = (v) => v instanceof Error || (typeof v === "object" && v !== null && "error" in v);
-export const wrapStream = (src, hooks) => {
-    let finished = false;
-    let reader;
-    const done = (controller, status, reason) => {
-        if (finished)
-            return;
-        finished = true;
-        hooks.onDone?.(status, reason);
-        if (status !== 200) {
-            reader?.cancel(reason).catch(() => { });
-        }
-        try {
-            controller.close();
-        }
-        catch { }
-    };
-    return new ReadableStream({
-        async start(controller) {
-            reader = src.getReader();
-            try {
-                for (;;) {
-                    // oxlint-disable-next-line no-await-in-loop, no-unsafe-assignment
-                    const { value, done: eof } = await reader.read();
-                    if (eof)
-                        break;
-                    controller.enqueue(value);
-                    if (isErrorChunk(value)) {
-                        done(controller, toOpenAIError(value).error.type === "invalid_request_error" ? 422 : 502, value);
-                        return;
-                    }
-                }
-                done(controller, 200);
-            }
-            catch (err) {
-                try {
-                    controller.enqueue(toOpenAIError(err));
-                }
-                catch { }
-                done(controller, 502, err);
-            }
-            finally {
-                try {
-                    reader?.releaseLock();
-                }
-                catch { }
-            }
-        },
-        cancel(reason) {
-            if (finished)
-                return;
-            finished = true;
-            hooks.onDone?.(499, reason);
-            reader?.cancel(reason).catch(() => { });
-        },
-    });
-};

package/dist/types.d.ts

@@ -1,176 +0,0 @@
-import type { ProviderV3 } from "@ai-sdk/provider";
-import type { Tracer } from "@opentelemetry/api";
-import type { ChatCompletions, ChatCompletionsBody, ChatCompletionsChunk } from "./endpoints/chat-completions/schema";
-import type { Embeddings, EmbeddingsBody } from "./endpoints/embeddings/schema";
-import type { Model, ModelList } from "./endpoints/models";
-import type { Logger, LoggerConfig } from "./logger";
-import type { ModelCatalog, ModelId } from "./models/types";
-import type { ProviderId, ProviderRegistry } from "./providers/types";
-/**
- * Per-request context shared across handlers and hooks.
- */
-export type GatewayContext = {
-    /**
-     * Mutable bag for passing data between hooks.
-     */
-    state: Record<string, unknown>;
-    /**
-     * Provider registry from config.
-     */
-    providers: ProviderRegistry;
-    /**
-     * Model catalog from config.
-     */
-    models: ModelCatalog;
-    /**
-     * Incoming request for the handler.
-     */
-    request: Request;
-    /**
-     * Resolved request ID for logging and telemetry.
-     */
-    requestId: string;
-    /**
-     * Parsed body from the request.
-     */
-    body?: ChatCompletionsBody | EmbeddingsBody;
-    /**
-     * Incoming model ID.
-     */
-    modelId?: ModelId;
-    /**
-     * Resolved model ID.
-     */
-    resolvedModelId?: ModelId;
-    /**
-     * Operation type.
-     */
-    operation?: "chat" | "embeddings" | "models";
-    /**
-     * Resolved provider instance.
-     */
-    provider?: ProviderV3;
-    /**
-     * Resolved provider ID.
-     */
-    resolvedProviderId?: ProviderId;
-    /**
-     * Result returned by the handler (pre-response).
-     */
-    result?: ChatCompletions | ReadableStream<ChatCompletionsChunk | Error> | Embeddings | Model | ModelList;
-    /**
-     * Response object returned by the handler.
-     */
-    response?: Response;
-};
-/**
- * Hook context: all fields readonly except `state`.
- */
-export type HookContext = Omit<Readonly<GatewayContext>, "state"> & {
-    state: GatewayContext["state"];
-};
-type RequiredHookContext<K extends keyof GatewayContext> = Omit<HookContext, K> & Required<Pick<HookContext, K>>;
-export type OnRequestHookContext = RequiredHookContext<"request">;
-export type BeforeHookContext = RequiredHookContext<"request" | "operation" | "body">;
-export type ResolveModelHookContext = RequiredHookContext<"request" | "operation" | "body" | "modelId">;
-export type ResolveProviderHookContext = RequiredHookContext<"request" | "operation" | "body" | "modelId" | "resolvedModelId">;
-export type AfterHookContext = RequiredHookContext<"request" | "operation" | "body" | "modelId" | "resolvedModelId" | "provider" | "resolvedProviderId" | "result">;
-export type OnResponseHookContext = RequiredHookContext<"request" | "response">;
-/**
- * Hooks to plugin to the gateway lifecycle.
- */
-export type GatewayHooks = {
-    /**
-     * Runs before any endpoint handler logic.
-     * @returns Optional Response to short-circuit the request.
-     */
-    onRequest?: (ctx: OnRequestHookContext) => void | Response | Promise<void | Response>;
-    /**
-     * Runs after request JSON is parsed and validated for chat completions / embeddings.
-     * @returns Replacement parsed body, or undefined to keep original.
-     */
-    before?: (ctx: BeforeHookContext) => void | ChatCompletionsBody | EmbeddingsBody | Promise<void | ChatCompletionsBody | EmbeddingsBody>;
-    /**
-     * Maps a user-provided model ID or alias to a canonical ID.
-     * @returns Canonical model ID or undefined to keep original.
-     */
-    resolveModelId?: (ctx: ResolveModelHookContext) => ModelId | void | Promise<ModelId | void>;
-    /**
-     * Picks a provider instance for the request.
-     * @returns ProviderV3 to override, or undefined to use default.
-     */
-    resolveProvider?: (ctx: ResolveProviderHookContext) => ProviderV3 | void | Promise<ProviderV3 | void>;
-    /**
-     * Runs after the endpoint handler.
-     * @returns Result to replace, or undefined to keep original.
-     */
-    after?: (ctx: AfterHookContext) => void | ChatCompletions | ReadableStream<ChatCompletionsChunk | Error> | Embeddings | Promise<void | ChatCompletions | ReadableStream<ChatCompletionsChunk | Error> | Embeddings>;
-    /**
-     * Runs after the lifecycle has produced the final Response.
-     * @returns Replacement Response, or undefined to keep original.
-     */
-    onResponse?: (ctx: OnResponseHookContext) => void | Response | Promise<void | Response>;
-};
-export type TelemetrySignalLevel = "off" | "required" | "recommended" | "full";
-/**
- * Main configuration object for the gateway.
- */
-export type GatewayConfig = {
-    /**
-     * Optional base path the gateway is mounted under (e.g. "/v1/gateway").
-     */
-    basePath?: string;
-    /**
-     * Provider registry keyed by canonical provider IDs.
-     */
-    providers: ProviderRegistry;
-    /**
-     * Model catalog keyed by canonical model IDs.
-     */
-    models: ModelCatalog;
-    /**
-     * Optional lifecycle hooks for routing, auth, and response shaping.
-     */
-    hooks?: GatewayHooks;
-    /**
-     * Preferred logger configuration: custom logger or default logger settings.
-     */
-    logger?: Logger | LoggerConfig | null;
-    /**
-     * Optional AI SDK telemetry configuration.
-     */
-    telemetry?: {
-        /**
-         * Enable AI SDK OpenTelemetry instrumentation.
-         * Disabled by default.
-         */
-        enabled?: boolean;
-        /**
-         * Optional custom OpenTelemetry tracer passed to AI SDK telemetry.
-         */
-        tracer?: Tracer;
-        /**
-         * Telemetry signal levels by namespace.
-         * - off: disable the namespace
-         * - required: minimal baseline
-         * - recommended: practical defaults
-         * - full: include all available details
-         */
-        signals?: {
-            gen_ai?: TelemetrySignalLevel;
-            http?: TelemetrySignalLevel;
-            hebo?: TelemetrySignalLevel;
-        };
-    };
-};
-export declare const kParsed: unique symbol;
-export type GatewayConfigParsed = GatewayConfig & {
-    [kParsed]: true;
-};
-export interface Endpoint {
-    handler: (request: Request, state?: Record<string, unknown>) => Promise<Response>;
-}
-export interface HeboGateway<Routes extends Record<string, Endpoint>> extends Endpoint {
-    routes: Routes;
-}
-export {};

package/dist/types.js

@@ -1 +0,0 @@
-export const kParsed = Symbol("hebo.gateway.parsed");

package/dist/utils/env.d.ts

@@ -1,2 +0,0 @@
-export declare const isProduction: () => boolean;
-export declare const isTest: () => boolean;

package/dist/utils/env.js

@@ -1,7 +0,0 @@
-const NODE_ENV = typeof process === "undefined"
-    ? // oxlint-disable-next-line no-unsafe-member-access
-        (globalThis.NODE_ENV ?? globalThis.ENV?.NODE_ENV)
-    : // oxlint-disable-next-line no-unsafe-assignment
-        process.env?.NODE_ENV;
-export const isProduction = () => NODE_ENV === "production";
-export const isTest = () => NODE_ENV === "test";

package/dist/utils/headers.d.ts

@@ -1,4 +0,0 @@
-export declare const REQUEST_ID_HEADER = "x-request-id";
-type HeaderSource = Request | ResponseInit | undefined;
-export declare const resolveRequestId: (source: HeaderSource) => string | undefined;
-export {};

package/dist/utils/headers.js

@@ -1,22 +0,0 @@
-export const REQUEST_ID_HEADER = "x-request-id";
-export const resolveRequestId = (source) => {
-    if (!source)
-        return undefined;
-    if (source instanceof Request) {
-        return source.headers.get(REQUEST_ID_HEADER) ?? undefined;
-    }
-    const headers = source.headers;
-    if (!headers)
-        return undefined;
-    if (headers instanceof Headers) {
-        return headers.get(REQUEST_ID_HEADER) ?? undefined;
-    }
-    if (Array.isArray(headers)) {
-        for (const [key, value] of headers) {
-            if (key.toLowerCase() === REQUEST_ID_HEADER)
-                return value;
-        }
-        return undefined;
-    }
-    return headers[REQUEST_ID_HEADER];
-};

package/dist/utils/preset.d.ts

@@ -1,10 +0,0 @@
-export type DeepPartial<T> = T extends (...args: unknown[]) => unknown ? T : T extends readonly (infer U)[] ? readonly DeepPartial<U>[] : T extends object ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : T;
-/**
- * Deep merge where overrides win.
- * Arrays are replaced.
- */
-export declare function deepMerge<A extends object, B extends object>(base: A, override?: B): A & B;
-export type Preset<Id extends string, T extends Record<string, unknown>, Base extends DeepPartial<T>> = <O extends DeepPartial<T>>(override?: O) => Record<Id, Base & O>;
-export declare function presetFor<Ids extends string, T extends Record<string, unknown>>(): <const Id extends Ids, const Base extends DeepPartial<T>>(id: Id, base: Base) => Preset<Id, T, Base>;

package/dist/utils/preset.js

@@ -1,42 +0,0 @@
-function isPlainObject(v) {
-    if (!v || typeof v !== "object" || Array.isArray(v))
-        return false;
-    // oxlint-disable-next-line no-unsafe-assignment
-    const proto = Object.getPrototypeOf(v);
-    return proto === Object.prototype || proto === null;
-}
-/**
- * Deep merge where overrides win.
- * Arrays are replaced.
- */
-export function deepMerge(base, override) {
-    if (override === null || override === undefined)
-        return base;
-    if (!isPlainObject(base) || !isPlainObject(override)) {
-        return override;
-    }
-    const out = { ...base };
-    for (const [key, ov] of Object.entries(override)) {
-        if (ov === undefined)
-            continue;
-        const bv = out[key];
-        if (Array.isArray(ov)) {
-            out[key] = ov;
-            continue;
-        }
-        if (isPlainObject(bv) && isPlainObject(ov)) {
-            out[key] = deepMerge(bv, ov);
-            continue;
-        }
-        out[key] = ov;
-    }
-    return out;
-}
-export function presetFor() {
-    return function preset(id, base) {
-        return (override) => {
-            const merged = deepMerge(base, override ?? {});
-            return { [id]: merged };
-        };
-    };
-}

package/dist/utils/request.d.ts

@@ -1,2 +0,0 @@
-export declare const resolveOrCreateRequestId: (request: Request) => string;
-export declare const prepareForwardHeaders: (request: Request) => Record<string, string>;

package/dist/utils/request.js

@@ -1,43 +0,0 @@
-import pkg from "../../package.json" with { type: "json" };
-import { resolveRequestId } from "./headers";
-const GATEWAY_VERSION = pkg.version;
-const FORWARD_HEADER_ALLOWLIST = [
-    // OpenAI + OpenAI-compatible providers (Azure, Groq, Together, Fireworks, etc.)
-    "openai-beta",
-    "openai-organization",
-    "openai-project",
-    // OpenRouter
-    "x-openrouter-categories",
-    "x-openrouter-title",
-    "x-title",
-    // Anthropic
-    "anthropic-beta",
-    // AWS Bedrock
-    "x-amzn-bedrock-guardrailidentifier",
-    "x-amzn-bedrock-guardrailversion",
-    "x-amzn-bedrock-performanceconfig-latency",
-    "x-amzn-bedrock-trace",
-    // Cohere
-    "x-client-name",
-    // Vertex provisioned throughput / endpoint routing
-    "x-vertex-ai-endpoint-id",
-    "x-vertex-ai-llm-request-type",
-    "x-vertex-ai-llm-shared-request-type",
-];
-const createRequestId = () => "req_" + crypto.getRandomValues(new Uint32Array(2)).reduce((s, n) => s + n.toString(36), "");
-export const resolveOrCreateRequestId = (request) => resolveRequestId(request) ?? createRequestId();
-export const prepareForwardHeaders = (request) => {
-    const userAgent = request.headers.get("user-agent");
-    const appendedUserAgent = userAgent
-        ? `${userAgent} @hebo-ai/gateway/${GATEWAY_VERSION}`
-        : `@hebo-ai/gateway/${GATEWAY_VERSION}`;
-    const headers = {
-        "user-agent": appendedUserAgent,
-    };
-    for (const key of FORWARD_HEADER_ALLOWLIST) {
-        const value = request.headers.get(key);
-        if (value !== null)
-            headers[key] = value;
-    }
-    return headers;
-};

package/dist/utils/response.d.ts

@@ -1,3 +0,0 @@
-export declare const prepareResponseInit: (requestId: string) => ResponseInit;
-export declare const mergeResponseInit: (defaultHeaders: HeadersInit, responseInit?: ResponseInit) => ResponseInit;
-export declare const toResponse: (result: ReadableStream | Uint8Array<ArrayBuffer> | object | string, responseInit?: ResponseInit) => Response;

package/dist/utils/response.js

@@ -1,70 +0,0 @@
-import { REQUEST_ID_HEADER } from "./headers";
-const TEXT_ENCODER = new TextEncoder();
-class JsonToSseTransformStream extends TransformStream {
-    constructor() {
-        super({
-            transform(part, controller) {
-                controller.enqueue(`data: ${JSON.stringify(part)}\n\n`);
-            },
-            flush(controller) {
-                controller.enqueue("data: [DONE]\n\n");
-            },
-        });
-    }
-}
-export const prepareResponseInit = (requestId) => ({
-    headers: { [REQUEST_ID_HEADER]: requestId },
-});
-export const mergeResponseInit = (defaultHeaders, responseInit) => {
-    const headers = new Headers(defaultHeaders);
-    const override = responseInit?.headers;
-    if (override) {
-        new Headers(override).forEach((value, key) => {
-            headers.set(key, value);
-        });
-    }
-    if (!responseInit)
-        return { headers };
-    return {
-        status: responseInit.status,
-        statusText: responseInit.statusText,
-        headers,
-    };
-};
-export const toResponse = (result, responseInit) => {
-    let body;
-    const isStream = result instanceof ReadableStream;
-    if (isStream) {
-        body = result.pipeThrough(new JsonToSseTransformStream()).pipeThrough(new TextEncoderStream());
-    }
-    else if (result instanceof Uint8Array) {
-        body = result;
-    }
-    else if (typeof result === "string") {
-        body = TEXT_ENCODER.encode(result);
-    }
-    else if (result instanceof Error) {
-        body = TEXT_ENCODER.encode(JSON.stringify({ message: result.message }));
-    }
-    else {
-        body = TEXT_ENCODER.encode(JSON.stringify(result));
-    }
-    if (!responseInit?.statusText) {
-        const isError = result instanceof Error;
-        const status = responseInit?.status ?? (isError ? 500 : 200);
-        const statusText = isError ? "REQUEST_FAILED" : "OK";
-        const headers = responseInit?.headers;
-        responseInit = headers ? { status, statusText, headers } : { status, statusText };
-    }
-    const init = mergeResponseInit(isStream
-        ? {
-            "content-type": "text/event-stream",
-            "cache-control": "no-cache",
-            connection: "keep-alive",
-        }
-        : {
-            "content-type": "application/json",
-            "content-length": String(body.byteLength),
-        }, responseInit);
-    return new Response(body, init);
-};

package/dist/utils/url.d.ts

@@ -1,4 +0,0 @@
-export declare const parseDataUrl: (url: string) => {
-    mimeType: string;
-    dataStart: number;
-};

package/dist/utils/url.js

@@ -1,21 +0,0 @@
-export const parseDataUrl = (url) => {
-    if (url.slice(0, 5).toLowerCase() !== "data:") {
-        return { mimeType: "", dataStart: 0 };
-    }
-    const MAX_HEADER_LENGTH = 1024;
-    const headerEnd = Math.min(url.length, 5 + MAX_HEADER_LENGTH);
-    const comma = url.indexOf(",", 5);
-    if (comma <= 5 || comma > headerEnd) {
-        return { mimeType: "", dataStart: 0 };
-    }
-    const semi = url.indexOf(";", 5);
-    const mimeEnd = semi !== -1 && semi < comma ? semi : comma;
-    const mimeType = url.slice(5, mimeEnd).trim();
-    if (!mimeType) {
-        return { mimeType: "", dataStart: 0 };
-    }
-    return {
-        mimeType,
-        dataStart: comma + 1,
-    };
-};