ai-gateway-proxy 0.0.2 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,329 @@
+import { LanguageModelV4CallOptions, LanguageModelV4Content, LanguageModelV4FinishReason, LanguageModelV4Usage, SharedV4Warning, SharedV4ProviderMetadata, LanguageModelV4StreamPart } from '@ai-sdk/provider';
+
+type GatewayAuthToken = {
+    token: string;
+    authMethod: "api-key" | "oidc";
+};
+/**
+ * Get authentication token for the AI Gateway.
+ * Tries API key first (AI_GATEWAY_API_KEY env var), then falls back to Vercel OIDC.
+ * Returns `null` when neither is available, after logging why OIDC failed, and the proxy then answers 500.
+ */
+declare function getGatewayAuthToken(): Promise<GatewayAuthToken | null>;
+
+/**
+ * The response body from the AI Gateway for non-streaming requests.
+ * For streaming requests, this is aggregated from the stream events.
+ */
+type GatewayResponse = {
+    content: LanguageModelV4Content[];
+    finishReason: LanguageModelV4FinishReason;
+    /** `undefined` when a stream ended without a `finish` event, so the usage is unknown. */
+    usage: LanguageModelV4Usage | undefined;
+    warnings: SharedV4Warning[];
+    providerMetadata?: SharedV4ProviderMetadata;
+    /**
+     * The provider's response id, model and start time, from a stream's `response-metadata` parts.
+     * `timestamp` is the string sent over the wire, not a `Date`. Neither the proxy nor the client reads it from a result.
+     */
+    response?: GatewayResponseMetadata;
+};
+/**
+ * What a stream's `response-metadata` parts say about the response, the latest value of each field winning.
+ */
+type GatewayResponseMetadata = {
+    id?: string;
+    modelId?: string;
+    timestamp?: string;
+};
+/**
+ * Why a stream had no `finish` event; the cancel reason is in `cancelReason`.
+ */
+type IncompleteStream = {
+    reason: "ended";
+} | {
+    reason: "error";
+    error: unknown;
+} | {
+    reason: "cancelled";
+    cancelReason?: unknown;
+};
+/**
+ * Error response from the AI Gateway.
+ */
+type GatewayError = {
+    error: {
+        message: string;
+        type: string;
+        param?: unknown;
+        code?: string | number | null;
+    };
+    /** The gateway's id for the failed generation, which `@ai-sdk/gateway` appends to the error message. */
+    generationId?: string | null;
+};
+/**
+ * The kind of a call that is not a language model call, named after the `@ai-sdk/gateway` model it comes from.
+ */
+type ModelCallKind = "embedding" | "image" | "video" | "speech" | "transcription" | "reranking" | "decision" | "batch";
+/**
+ * What `beforeRawRequest` receives.
+ */
+type RawRequestContext = {
+    kind: ModelCallKind;
+    /** The upstream path relative to `baseUrl`, such as `embedding-model` or `batch/start`. */
+    path: string;
+    /** The `ai-model-id` header the client sent, which names the model; a batch names it per request too. */
+    modelId: string | undefined;
+    /** The parsed JSON body, unchecked. */
+    request: unknown;
+};
+/**
+ * What `afterRawResponse` receives.
+ */
+type RawResponseContext = RawRequestContext & {
+    /**
+     * The response the proxy would send: the upstream status, `content-type` and allowlisted
+     * headers, with the upstream body on success and a `GatewayError` JSON body on failure.
+     * Its body can be read once, so read `response.clone()` to leave it for the client.
+     */
+    response: Response;
+};
+/**
+ * Options for creating a gateway proxy.
+ */
+type CreateGatewayProxyOptions = {
+    /**
+     * Base URL for the AI Gateway. A trailing slash is accepted.
+     * Request paths are resolved under it and cannot leave it; one that would returns 400 Invalid path.
+     * @default "https://ai-gateway.vercel.sh/v4/ai"
+     */
+    baseUrl?: string;
+    /**
+     * Additional headers to send with requests.
+     * The proxy sets `authorization`, `ai-gateway-auth-method` and `ai-gateway-protocol-version` after these, so they win.
+     * On requests with a body it also sets `content-type`, drops entries naming the model call
+     * (`ai-language-model-*`, `ai-model-id`, `ai-*-model-specification-version`) in favour of the
+     * incoming request's, and lets the incoming `ai-o11y-*`, `idempotency-key` and `accept` override these.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The name of the catch-all parameter in the route.
+     * @default "segments"
+     * @example
+     * // For Next.js route `app/api/ai/[...path]/route.ts`
+     * createGatewayProxy({ segmentsParam: "path" })
+     */
+    segmentsParam?: string;
+    /**
+     * Custom function to extract the path from the request.
+     * Use this for frameworks without catch-all route support (e.g., Hono, Express).
+     *
+     * When provided, `segmentsParam` is ignored.
+     *
+     * Return a path relative to `baseUrl`, without a leading `/`.
+     * A path that starts with `/`, contains `://`, or has a segment that fails to decode or decodes
+     * to `.` or `..` or contains `/`, `\` or a NUL byte returns 400 Invalid path.
+     *
+     * @example
+     * // Hono with a base path
+     * createGatewayProxy({
+     *   extractPath: (request) => {
+     *     const url = new URL(request.url);
+     *     return url.pathname.replace(/^\/api\/ai\//, "");
+     *   }
+     * })
+     */
+    extractPath?: (request: Request) => string | Promise<string>;
+    /**
+     * Called before the request is sent to the gateway.
+     * Allows modification of the request body. Returning `undefined` or `null` sends the
+     * parsed body unchanged and logs an error. Any other result that is not an object, such as
+     * a string or an array, is not sent: the client gets a 500 and the gateway is not called.
+     *
+     * Not called for GET, HEAD or other requests without a body, which are forwarded as is.
+     * A body that is JSON but not an object gets a 400 before this or any other language model
+     * hook runs.
+     *
+     * Not called when the path relative to `baseUrl` is exactly one of the paths `@ai-sdk/gateway`
+     * uses for other calls: `embedding-model`, `image-model`, `video-model`, `video-model/start`,
+     * `video-model/status`, `speech-model`, `transcription-model`, `reranking-model`,
+     * `decision-model`, `batch/start`, `batch/status`, `batch/results` and `batch/cancel`.
+     * Every other path runs it, whatever headers the request sends.
+     */
+    beforeRequest?: (context: {
+        request: LanguageModelV4CallOptions;
+        /** The `ai-language-model-id` header the client sent, which names the model; the body does not. */
+        modelId?: string;
+    }) => LanguageModelV4CallOptions | Promise<LanguageModelV4CallOptions>;
+    /**
+     * Called after a successful response is received from the gateway.
+     * Allows modification of the response body.
+     *
+     * For non-streaming responses, the returned object replaces the JSON body sent to the client.
+     * A result with a missing or wrong-typed field is not sent: the client gets a 500 naming the
+     * field, and on a stream the original finish event is forwarded. `null` stands for an absent
+     * field, and `warnings` may be left out. An absent `usage` keeps the gateway's, on both paths.
+     *
+     * For streaming responses, this is called when the stream completes with
+     * the aggregated response. The content has already been streamed, but you
+     * can modify the finish event metadata (usage, finishReason, providerMetadata).
+     * If the hook throws while handling a stream, the error is logged and the
+     * original finish event is forwarded unchanged. It runs once per stream: a
+     * later finish event gets the same rewrite, or none if the hook failed.
+     *
+     * A stream that ends, fails or is cancelled before its finish event calls the hook once
+     * with the content received so far, `incomplete` set, `response.usage` undefined and
+     * `response.finishReason` `error` when the read failed or the stream sent an `error` part,
+     * `other` otherwise. Nothing can be rewritten then, so the
+     * returned value is ignored and a throw is logged.
+     *
+     * Not called for an event stream or JSON Lines body answering a request not marked
+     * `ai-language-model-streaming: true`, such as a video model call or batch results, which is
+     * forwarded as is.
+     *
+     * Not called for a 204 or 205 response, which is forwarded without a body.
+     *
+     * Not called for GET, HEAD or other requests without a body, which are forwarded as is.
+     *
+     * Not called when the path relative to `baseUrl` is exactly one of the paths `@ai-sdk/gateway`
+     * uses for other calls: `embedding-model`, `image-model`, `video-model`, `video-model/start`,
+     * `video-model/status`, `speech-model`, `transcription-model`, `reranking-model`,
+     * `decision-model`, `batch/start`, `batch/status`, `batch/results` and `batch/cancel`.
+     * Every other path runs it, whatever headers the request sends.
+     */
+    afterResponse?: (context: {
+        request: LanguageModelV4CallOptions;
+        /** The `ai-language-model-id` header the client sent, which names the model; the body does not. */
+        modelId?: string;
+        response: GatewayResponse;
+        /** Set only for a stream that did not deliver its `finish` event. */
+        incomplete?: IncompleteStream;
+    }) => GatewayResponse | Promise<GatewayResponse>;
+    /**
+     * Called when the gateway returns an error response.
+     * Allows custom error handling or modification.
+     *
+     * A returned error body is sent as JSON with the upstream status.
+     * A returned `Response` is sent as is.
+     * Returning `undefined`, `null` or a body without a string `error.message` (or with a
+     * non-string `error.type`, an `error.code` that is neither a string nor a number, or a
+     * non-string `generationId`) logs an error and sends the upstream error body instead, and so
+     * does a hook that throws.
+     *
+     * Not called for GET, HEAD or other requests without a body, which are forwarded as is.
+     *
+     * Not called when the path relative to `baseUrl` is exactly one of the paths `@ai-sdk/gateway`
+     * uses for other calls: `embedding-model`, `image-model`, `video-model`, `video-model/start`,
+     * `video-model/status`, `speech-model`, `transcription-model`, `reranking-model`,
+     * `decision-model`, `batch/start`, `batch/status`, `batch/results` and `batch/cancel`.
+     * Every other path runs it, whatever headers the request sends.
+     */
+    onError?: (context: {
+        request: LanguageModelV4CallOptions;
+        /** The `ai-language-model-id` header the client sent, which names the model; the body does not. */
+        modelId?: string;
+        error: GatewayError;
+        status: number;
+    }) => GatewayError | Response | Promise<GatewayError | Response>;
+    /**
+     * Called before a call that is not a language model call is sent to the gateway: a request
+     * with a body whose path relative to `baseUrl` is exactly `embedding-model`, `image-model`,
+     * `video-model`, `video-model/start`, `speech-model`, `transcription-model`,
+     * `reranking-model`, `decision-model` or `batch/start`. Job reads (`video-model/status` and
+     * `batch/status`, `batch/results`, `batch/cancel`) run no hook.
+     *
+     * A returned value replaces the body sent upstream; `undefined` or `null` sends the body as is.
+     */
+    beforeRawRequest?: (context: RawRequestContext) => unknown;
+    /**
+     * Called with the response to a call `beforeRawRequest` would run for, on success and on an
+     * upstream error status, but not on a redirect, which is answered with a 502, nor when the
+     * upstream request fails.
+     *
+     * A returned `Response` is sent instead. Returning nothing sends `response`, which must then
+     * be unread; a hook that read it without returning a `Response`, or returned anything else,
+     * is a 500. When the hook returns another `Response`, throws or returns anything else, an
+     * unread `response.body` is cancelled unless the returned `Response` is built on it.
+     */
+    afterRawResponse?: (context: RawResponseContext) => Response | undefined | Promise<Response | undefined>;
+};
+/**
+ * Route handler function signature for the gateway proxy.
+ * Compatible with Next.js App Router and other frameworks.
+ * Takes a Fetch API `Request`, not a Node or Express request object.
+ */
+type CreateGatewayProxyFn = (request: Request, context?: {
+    params: Promise<Record<string, string | string[] | undefined>>;
+}) => Promise<Response>;
+/**
+ * Result of createGatewayProxy - a handler function with HTTP method exports.
+ */
+type CreateGatewayProxyResult = CreateGatewayProxyFn & {
+    GET: CreateGatewayProxyFn;
+    POST: CreateGatewayProxyFn;
+    PUT: CreateGatewayProxyFn;
+    DELETE: CreateGatewayProxyFn;
+    PATCH: CreateGatewayProxyFn;
+};
+
+/**
+ * Creates a proxy handler for the Vercel AI Gateway.
+ *
+ * Uses AI SDK V4 Language Model.
+ * @see https://github.com/vercel/ai/blob/main/packages/gateway/src/gateway-language-model.ts
+ */
+declare const createGatewayProxy: ({ baseUrl, headers, segmentsParam, extractPath, beforeRequest, afterResponse, onError, beforeRawRequest, afterRawResponse, }?: CreateGatewayProxyOptions) => CreateGatewayProxyResult;
+
+/**
+ * Aggregator for collecting stream content.
+ * Tracks text deltas, reasoning, tool calls, and other content to build the final GatewayResponse.
+ *
+ * Uses AI SDK V4 protocol types.
+ * @see https://github.com/vercel/ai/blob/main/packages/provider/src/language-model/v4/language-model-v4-stream-part.ts
+ */
+declare class StreamContentAggregator {
+    private content;
+    private warnings;
+    private textContent;
+    private reasoningContent;
+    private finishReason;
+    private usage;
+    private providerMetadata;
+    private response;
+    /**
+     * Process a stream part and update aggregated state.
+     * Uses LanguageModelV4StreamPart type from @ai-sdk/provider.
+     *
+     * @see https://github.com/vercel/ai/blob/main/packages/provider/src/language-model/v4/language-model-v4-stream-part.ts
+     */
+    process(part: LanguageModelV4StreamPart): void;
+    private recordResponseMetadata;
+    private openText;
+    private openReasoning;
+    /**
+     * Get the aggregated response. Before a `finish` part, `usage` is undefined and
+     * `finishReason` is `error` after an `error` part and `other` otherwise.
+     */
+    getResponse(): GatewayResponse;
+}
+/**
+ * Creates a transform stream that:
+ * 1. Passes through all SSE events immediately
+ * 2. Aggregates content using StreamContentAggregator
+ * 3. Calls afterResponse once: on the first finish event, or with partial content if the
+ *    stream ends, fails or is cancelled first
+ * 4. Modifies every finish event based on that afterResponse result
+ *
+ * Pass the client request's `signal` when it is also the upstream fetch's signal: a read that
+ * fails because it aborted is then reported as a cancel rather than an upstream failure.
+ *
+ * Uses EventSourceParserStream from @ai-sdk/provider-utils for SSE parsing.
+ * EventSourceParserStream is re-exported from the eventsource-parser package.
+ * @see https://github.com/vercel/ai/blob/main/packages/provider-utils/src/parse-json-event-stream.ts
+ * @see https://github.com/rexxars/eventsource-parser
+ */
+declare function createStreamTransformer(body: ReadableStream<Uint8Array>, requestBody: LanguageModelV4CallOptions, afterResponse: NonNullable<CreateGatewayProxyOptions["afterResponse"]>, signal?: AbortSignal): ReadableStream<Uint8Array>;
+
+export { StreamContentAggregator, createGatewayProxy, createStreamTransformer, getGatewayAuthToken };
+export type { CreateGatewayProxyFn, CreateGatewayProxyOptions, CreateGatewayProxyResult, GatewayAuthToken, GatewayError, GatewayResponse, GatewayResponseMetadata, IncompleteStream, ModelCallKind, RawRequestContext, RawResponseContext };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sources":["../src/auth.ts","../src/types.ts","../src/proxy.ts","../src/stream.ts"],"mappings":";;AAAA,KAAK,gBAAgB;AACrB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iBAAiB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB;;ACRhE;AACA;AACA;AACA;AACA,KAAK,eAAe;AACpB,aAAa,sBAAsB;AACnC,kBAAkB,2BAA2B;AAC7C;AACA,WAAW,oBAAoB;AAC/B,cAAc,eAAe;AAC7B,uBAAuB,wBAAwB;AAC/C;AACA;AACA;AACA;AACA,eAAe,uBAAuB;AACtC;AACA;AACA;AACA;AACA,KAAK,uBAAuB;AAC5B;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,gBAAgB;AACrB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,aAAa;AAClB;AACA;AACA;AACA,KAAK,iBAAiB;AACtB,UAAU,aAAa;AACvB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,kBAAkB,GAAG,iBAAiB;AAC3C;AACA;AACA;AACA;AACA;AACA,cAAc,QAAQ;AACtB;AACA;AACA;AACA;AACA,KAAK,yBAAyB;AAC9B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,cAAc,MAAM;AACpB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,4BAA4B,OAAO,cAAc,OAAO;AACxD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iBAAiB,0BAA0B;AAC3C;AACA;AACA,UAAU,0BAA0B,GAAG,OAAO,CAAC,0BAA0B;AACzE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iBAAiB,0BAA0B;AAC3C;AACA;AACA,kBAAkB,eAAe;AACjC;AACA,qBAAqB,gBAAgB;AACrC,UAAU,eAAe,GAAG,OAAO,CAAC,eAAe;AACnD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iBAAiB,0BAA0B;AAC3C;AACA;AACA,eAAe,YAAY;AAC3B;AACA,UAAU,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC,YAAY,GAAG,QAAQ;AACnE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iCAAiC,iBAAiB;AAClD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iCAAiC,kBAAkB,KAAK,QAAQ,eAAe,OAAO,CAAC,QAAQ;AAC/F;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,oBAAoB,aAAa,OAAO;AAC7C,YAAY,OAAO,CAAC,MAAM;AAC1B,MAAM,OAAO,CAAC,QAAQ;AACtB;AACA;AACA;AACA,KAAK,wBAAwB,GAAG,oBAAoB;AACpD,SAAS,oBAAoB;AAC7B,UAAU,oBAAoB;AAC9B,SAAS,oBAAoB;AAC7B,YAAY,oBAAoB;AAChC,WAAW,oBAAoB;AAC/B;;AC7PA;AACA;AACA;AACA;AACA;AACA;AACA,cAAc,kBAAkB,kIAAkI,yBAAyB,KAAK,wBAAwB;;ACLxN;AACA;AACA;AACA;AACA;AACA;AACA;AACA,cAAc,uBAAuB;AACrC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,kBAAkB,yBAAyB;AAC3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA,mBAAmB,eAAe;AAClC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iBAAiB,uBAAuB,OAAO,cAAc,CAAC,UAAU,gBAAgB,0BAA0B,iBAAiB,WAAW,CAAC,yBAAyB,6BAA6B,WAAW,GAAG,cAAc,CAAC,UAAU;;","names":[]}