@blazingagents/sdk 0.1.0

package/dist/generation.js

@@ -0,0 +1,422 @@
+import { createTextStreamResponse, parsePartialJson } from "ai";
+import { sessionIdSchema } from "./contracts/ids.js";
+import { BlazingAgentsError } from "./errors.js";
+import { requestStream } from "./http.js";
+// --- chat ---
+export async function chat(config, input) {
+    const body = buildChatBody(input);
+    /**
+     * URL presence is the mode: no `sessionId` → create
+     * (`POST /v1/agents/:agentId/sessions`, server mints the `ss_` id,
+     * returned via `Location`); `sessionId` present → resume
+     * (`POST /v1/agents/:agentId/sessions/:sessionId`).
+     */
+    const path = input.sessionId === undefined
+        ? `/v1/agents/${input.agentId}/sessions`
+        : `/v1/agents/${input.agentId}/sessions/${input.sessionId}`;
+    const response = await requestStream(config, path, {
+        json: body,
+        method: "POST",
+        clientRequestId: input.clientRequestId,
+        ...(input.signal ? { signal: input.signal } : {}),
+    });
+    return buildChatResult(response, input.sessionId);
+}
+function buildChatBody(input) {
+    const base = {};
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits an undefined trigger.
+    if (input.trigger !== undefined) {
+        base.trigger = input.trigger;
+    }
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits an undefined message id.
+    if (input.messageId !== undefined) {
+        base.messageId = input.messageId;
+    }
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits an undefined Version Pin.
+    if (input.version !== undefined) {
+        base.version = input.version;
+    }
+    if ("message" in input) {
+        base.message = input.message;
+    }
+    else {
+        base.promptId = input.promptId;
+        // Stryker disable next-line ConditionalExpression: JSON serialization omits undefined variables.
+        if (input.variables !== undefined) {
+            base.variables = input.variables;
+        }
+    }
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits an undefined user id.
+    if (input.userId !== undefined) {
+        base.userId = input.userId;
+    }
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits undefined metadata.
+    if (input.metadata !== undefined) {
+        base.metadata = input.metadata;
+    }
+    return base;
+}
+/**
+ * Extracts the server-minted `ss_` id from the `Location` header on the
+ * create path. The header is `/v1/agents/:agentId/sessions/:newId`; the
+ * id is the trailing path segment, validated against `sessionIdSchema`
+ * so a malformed or non-`ss_` value surfaces as a `stream_error` instead
+ * of flowing into resume calls as an untyped string.
+ */
+function sessionIdFromLocation(response, requestId) {
+    const location = response.headers.get("location");
+    if (!location) {
+        const message = "The server did not return a session id (no Location header).";
+        throw new BlazingAgentsError({
+            code: "stream_error",
+            message,
+            requestId,
+        }, { cause: new Error(message) });
+    }
+    const id = location.split("/").pop();
+    const parsed = sessionIdSchema.safeParse(id);
+    if (!parsed.success) {
+        throw new BlazingAgentsError({
+            code: "stream_error",
+            message: "The server returned a malformed session Location header.",
+            requestId,
+        }, { cause: parsed.error });
+    }
+    return parsed.data;
+}
+function buildChatResult(response, resumeSessionId) {
+    const terminalResult = buildTerminalStreamResult(response, "chat");
+    /**
+     * `sessionId` resolves from the `Location` header on create, or to the
+     * passed id on resume. Read eagerly (the header is available before the
+     * body streams) so awaiting `result.sessionId` does not depend on
+     * draining the stream.
+     */
+    let sessionIdPromise;
+    if (resumeSessionId === undefined) {
+        try {
+            sessionIdPromise = Promise.resolve(sessionIdFromLocation(response, terminalResult.requestId));
+        }
+        catch (error) {
+            sessionIdPromise = Promise.reject(error);
+        }
+    }
+    else {
+        sessionIdPromise = Promise.resolve(resumeSessionId);
+    }
+    sessionIdPromise.catch(() => {
+        /* no-op — prevents unhandled rejection if the caller never awaits */
+    });
+    return {
+        sessionId: sessionIdPromise,
+        ...terminalResult,
+    };
+}
+export function buildTerminalStreamResult(response, resourceName) {
+    const requestId = response.headers.get("x-request-id") ?? undefined;
+    const location = response.headers.get("location");
+    let bodyClaimed = false;
+    const claimBody = () => {
+        if (bodyClaimed) {
+            const message = `The ${resourceName} response body has already been claimed.`;
+            const cause = new Error(message);
+            throw new BlazingAgentsError({
+                code: "stream_error",
+                message,
+                requestId,
+            }, { cause });
+        }
+        bodyClaimed = true;
+        return normalizeStreamErrors(responseBodyStream(response, requestId, resourceName), requestId, `The ${resourceName} response stream failed.`);
+    };
+    return {
+        requestId,
+        toResponse: () => {
+            const headers = replacementResponseHeaders(requestId, location);
+            headers.set("content-type", "text/event-stream");
+            headers.set("cache-control", "no-cache");
+            headers.set("connection", "keep-alive");
+            headers.set("x-vercel-ai-ui-message-stream", "v1");
+            headers.set("x-accel-buffering", "no");
+            try {
+                return new Response(claimBody(), {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers,
+                });
+            }
+            catch (cause) {
+                throw toStreamError(cause, requestId, `The ${resourceName} response stream failed.`);
+            }
+        },
+    };
+}
+function toStreamError(cause, requestId, fallbackMessage) {
+    if (BlazingAgentsError.isInstance(cause) &&
+        cause.code === "stream_error" &&
+        cause.requestId === requestId) {
+        return cause;
+    }
+    let message;
+    if (cause instanceof Error) {
+        message = cause.message;
+    }
+    else if (typeof fallbackMessage === "function") {
+        message = fallbackMessage(cause);
+    }
+    else {
+        message = fallbackMessage;
+    }
+    return new BlazingAgentsError({
+        code: "stream_error",
+        message,
+        requestId,
+    }, { cause });
+}
+function normalizeStreamErrors(stream, requestId, fallbackMessage) {
+    let reader;
+    try {
+        reader = stream.getReader();
+    }
+    catch (cause) {
+        throw toStreamError(cause, requestId, fallbackMessage);
+    }
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(value);
+            }
+            catch (cause) {
+                controller.error(toStreamError(cause, requestId, fallbackMessage));
+            }
+        },
+        async cancel(reason) {
+            try {
+                await reader.cancel(reason);
+            }
+            catch (cause) {
+                throw toStreamError(cause, requestId, fallbackMessage);
+            }
+        },
+    });
+}
+function responseBodyStream(response, requestId, resourceName) {
+    if (response.body) {
+        return response.body;
+    }
+    const message = `The ${resourceName} response did not include a body.`;
+    const cause = new Error(message);
+    const error = new BlazingAgentsError({
+        code: "stream_error",
+        message,
+        requestId,
+    }, { cause });
+    return new ReadableStream({
+        start(controller) {
+            controller.error(error);
+        },
+    });
+}
+function replacementResponseHeaders(requestId, location) {
+    const headers = new Headers();
+    if (requestId !== undefined) {
+        headers.set("x-request-id", requestId);
+    }
+    if (location !== null) {
+        headers.set("location", location);
+    }
+    return headers;
+}
+function buildStatelessGenerationBody(input, output) {
+    const body = { output };
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits an undefined Version Pin.
+    if (input.version !== undefined) {
+        body.version = input.version;
+    }
+    if ("prompt" in input) {
+        body.prompt = input.prompt;
+    }
+    else {
+        body.promptId = input.promptId;
+        // Stryker disable next-line ConditionalExpression: JSON serialization omits undefined variables.
+        if (input.variables !== undefined) {
+            body.variables = input.variables;
+        }
+    }
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits an undefined user id.
+    if (input.userId !== undefined) {
+        body.userId = input.userId;
+    }
+    // Stryker disable next-line ConditionalExpression: JSON serialization omits undefined metadata.
+    if (input.metadata !== undefined) {
+        body.metadata = input.metadata;
+    }
+    return body;
+}
+// --- completion ---
+export async function completion(config, input) {
+    const body = buildStatelessGenerationBody(input, { type: "text" });
+    const path = `/v1/agents/${input.agentId}/generation`;
+    const response = await requestStream(config, path, {
+        json: body,
+        method: "POST",
+        clientRequestId: input.clientRequestId,
+        ...(input.signal ? { signal: input.signal } : {}),
+    });
+    return buildCompletionResult(response);
+}
+function buildCompletionResult(response) {
+    const { finalStream, outputStream, requestId, toResponse } = buildStatelessGenerationStreams(response, "completion");
+    const textPromise = (async () => {
+        let text = "";
+        for await (const delta of finalStream) {
+            text += delta;
+        }
+        return text;
+    })();
+    /**
+     * Attach a no-op rejection handler so the promise doesn't trigger an
+     * unhandled-rejection warning if the caller only uses `textStream` or
+     * `toResponse()` without awaiting `text`.
+     */
+    textPromise.catch(() => {
+        /* no-op — prevents unhandled rejection if the caller never awaits */
+    });
+    return {
+        requestId,
+        textStream: outputStream,
+        text: textPromise,
+        toResponse,
+    };
+}
+// --- object ---
+export async function objectGeneration(config, input) {
+    const body = buildStatelessGenerationBody(input, {
+        type: "object",
+        schema: input.schema,
+    });
+    const path = `/v1/agents/${input.agentId}/generation`;
+    const response = await requestStream(config, path, {
+        json: body,
+        method: "POST",
+        clientRequestId: input.clientRequestId,
+        ...(input.signal ? { signal: input.signal } : {}),
+    });
+    return buildObjectResult(response);
+}
+function buildObjectResult(response) {
+    const { finalStream, outputStream, requestId, toResponse } = buildStatelessGenerationStreams(response, "object");
+    let accumulatedText = "";
+    const partialObjectStream = outputStream.pipeThrough(new TransformStream({
+        async transform(chunk, controller) {
+            accumulatedText += chunk;
+            const { value } = await parsePartialJson(accumulatedText);
+            if (value !== undefined) {
+                controller.enqueue(value);
+            }
+        },
+        flush() {
+            try {
+                JSON.parse(accumulatedText);
+            }
+            catch (cause) {
+                throw new BlazingAgentsError({
+                    code: "stream_error",
+                    message: "The agent produced invalid JSON.",
+                    requestId,
+                }, { cause });
+            }
+        },
+    }));
+    const objectPromise = (async () => {
+        let text = "";
+        for await (const delta of finalStream) {
+            text += delta;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new BlazingAgentsError({
+                code: "stream_error",
+                message: "The agent produced invalid JSON.",
+                requestId,
+            }, { cause });
+        }
+    })();
+    objectPromise.catch(() => {
+        /* no-op — prevents unhandled rejection if the caller never awaits */
+    });
+    return {
+        partialObjectStream,
+        object: objectPromise,
+        requestId,
+        toResponse,
+    };
+}
+// --- helpers ---
+function buildStatelessGenerationStreams(response, resourceName) {
+    const requestId = response.headers.get("x-request-id") ?? undefined;
+    const location = response.headers.get("location");
+    const rawStream = responseBodyStream(response, requestId, resourceName);
+    const textStream = decodeTextStream(rawStream, requestId, resourceName);
+    /**
+     * The public output, awaited final value, and response relay each need a
+     * branch. `tee()` produces two branches, so tee twice.
+     */
+    const [outputStream, forRest] = textStream.tee();
+    const [finalStream, relayStream] = forRest.tee();
+    let responseBodyClaimed = false;
+    return {
+        finalStream,
+        outputStream,
+        requestId,
+        toResponse: () => {
+            if (responseBodyClaimed) {
+                const message = `The ${resourceName} response body has already been claimed.`;
+                throw new BlazingAgentsError({
+                    code: "stream_error",
+                    message,
+                    requestId,
+                }, { cause: new Error(message) });
+            }
+            responseBodyClaimed = true;
+            const headers = replacementResponseHeaders(requestId, location);
+            headers.set("content-type", "text/plain; charset=utf-8");
+            try {
+                return createTextStreamResponse({
+                    stream: relayStream,
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers,
+                });
+            }
+            catch (cause) {
+                throw toStreamError(cause, requestId, `The ${resourceName} response stream failed.`);
+            }
+        },
+    };
+}
+/**
+ * Wraps a `ReadableStream<Uint8Array>` as a `ReadableStream<string>` via
+ * `TextDecoderStream`. The cast works around a TS/Node-types mismatch
+ * where `TextDecoderStream`'s writable accepts `BufferSource` but the
+ * stream's chunks are typed as `Uint8Array<ArrayBufferLike>`.
+ */
+function decodeTextStream(raw, requestId, resourceName) {
+    let decodedStream;
+    try {
+        decodedStream = raw.pipeThrough(new TextDecoderStream());
+    }
+    catch (cause) {
+        throw toStreamError(cause, requestId, `The ${resourceName} response stream failed.`);
+    }
+    return normalizeStreamErrors(decodedStream, requestId, (cause) => typeof cause === "string"
+        ? cause
+        : `The ${resourceName} response stream failed.`);
+}

package/dist/http.d.ts

@@ -0,0 +1,21 @@
+import { BlazingAgentsError } from "./errors.ts";
+import type { HttpConfig, RequestOptions } from "./types.ts";
+/**
+ * Performs a request and returns the parsed JSON body for success (status
+ * 2xx). API errors preserve the tolerant wire envelope; malformed responses
+ * become `invalid_response`.
+ */
+export declare function requestJson<T>(config: HttpConfig, path: string, options?: RequestOptions, schema?: {
+    parse(value: unknown): T;
+}): Promise<T>;
+/**
+ * Performs a request and returns the raw `Response` for streaming paths.
+ * Non-2xx bodies are decoded before a caller can observe a streaming body.
+ */
+export declare function requestStream(config: HttpConfig, path: string, options?: RequestOptions): Promise<Response>;
+/**
+ * Decodes a response body with the tolerant consumer schema. Unknown future
+ * codes and fields remain valid; malformed responses never infer a domain
+ * code from HTTP status.
+ */
+export declare function parseErrorEnvelope(bodyText: string, status: number, headers?: Headers): BlazingAgentsError;