@302ai/media-studio-core 0.1.0-beta.0

package/dist/stream/stream.d.ts

@@ -0,0 +1,58 @@
+import { type MediaResult } from "../media/media-result.js";
+import { type ChatStreamEvent } from "./events.js";
+export type ChatStreamSource = ReadableStream<Uint8Array> | (() => Promise<Response>);
+export interface ChatStreamOptions {
+    maxRetries?: number | undefined;
+    initialRetryDelayMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+    onFinalResponse?: ((res: ChatFinalResponse) => void) | undefined;
+    onError?: ((err: unknown) => void) | undefined;
+}
+export interface ChatFinalResponse {
+    text: string;
+    reasoning?: string;
+    toolCalls: Array<{
+        toolCallId: string;
+        toolName: string;
+        args?: unknown;
+    }>;
+    toolResults: Array<{
+        toolCallId: string;
+        result?: unknown;
+    }>;
+    mediaResults: MediaResult[];
+    finishReason?: string;
+}
+/**
+ * Isomorphic async stream wrapper that transforms raw SSE bytes into typed
+ * ChatStreamEvents. Supports async iteration (`for await (const ev of stream)`),
+ * connection-establishment exponential backoff retries, and automatic media result synthesis.
+ */
+export declare class ChatStream implements AsyncIterable<ChatStreamEvent> {
+    private readonly source;
+    private readonly options;
+    private readonly accumulator;
+    private hasStartedIterating;
+    private resolveCompletion;
+    private rejectCompletion;
+    private readonly completionPromise;
+    private isCompleted;
+    constructor(source: ChatStreamSource, options?: ChatStreamOptions);
+    private establishConnection;
+    private drainQueue;
+    [Symbol.asyncIterator](): AsyncIterator<ChatStreamEvent>;
+    /**
+     * Resolves with the aggregated final response.
+     * Awaits stream completion whether called before, during, or after iteration.
+     */
+    finalResponse(): Promise<ChatFinalResponse>;
+    /**
+     * Convenience helper that consumes the stream and resolves with just the full text.
+     */
+    finalText(): Promise<string>;
+    /**
+     * Settles when the stream completes, is cancelled, or encounters an error.
+     * Unlike finalResponse(), awaiting settled does not automatically start background iteration.
+     */
+    get settled(): Promise<void>;
+}

package/dist/stream/stream.js

@@ -0,0 +1,325 @@
+import { attempt, delay } from "es-toolkit";
+import { isObject } from "es-toolkit/compat";
+import { isFunction, isNumber, isString } from "es-toolkit/predicate";
+import { createParser } from "eventsource-parser";
+import { match, P } from "ts-pattern";
+import { extractMediaResult } from "../media/media-result.js";
+import { ChatUpstreamError, extractUpstreamErrorMessage, } from "../transport/errors.js";
+import { ChatStreamEventSchema } from "./events.js";
+function abortException(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error)
+        return reason;
+    return new DOMException("This operation was aborted", "AbortError");
+}
+class ResponseAccumulator {
+    text = "";
+    reasoning = "";
+    toolCalls = [];
+    toolResults = [];
+    mediaResults = [];
+    finishReason;
+    record(event) {
+        match(event)
+            .with({ type: "text-delta" }, ({ delta }) => {
+            this.text += delta;
+        })
+            .with({ type: "reasoning-delta" }, ({ delta }) => {
+            this.reasoning += delta;
+        })
+            .with({ type: "tool-call" }, ({ toolCallId, toolName, args }) => {
+            this.toolCalls.push({ toolCallId, toolName, args });
+        })
+            .with({ type: "tool-result" }, ({ toolCallId, result }) => {
+            this.toolResults.push({ toolCallId, result });
+        })
+            .with({ type: "media-result" }, ({ result }) => {
+            this.mediaResults.push(result);
+        })
+            .with({ type: "finish" }, ({ finishReason }) => {
+            this.finishReason = finishReason;
+        })
+            .with({ type: "error" }, () => {
+            // Error events are upstream SSE domain data (e.g. rate limits).
+            // They are yielded to the consumer as-is; no accumulator-level side effect.
+        })
+            .exhaustive();
+    }
+    toResponse() {
+        return {
+            text: this.text,
+            ...(this.reasoning ? { reasoning: this.reasoning } : {}),
+            toolCalls: [...this.toolCalls],
+            toolResults: [...this.toolResults],
+            mediaResults: [...this.mediaResults],
+            ...(this.finishReason ? { finishReason: this.finishReason } : {}),
+        };
+    }
+}
+/**
+ * Isomorphic async stream wrapper that transforms raw SSE bytes into typed
+ * ChatStreamEvents. Supports async iteration (`for await (const ev of stream)`),
+ * connection-establishment exponential backoff retries, and automatic media result synthesis.
+ */
+export class ChatStream {
+    source;
+    options;
+    accumulator = new ResponseAccumulator();
+    hasStartedIterating = false;
+    resolveCompletion;
+    rejectCompletion;
+    completionPromise;
+    isCompleted = false;
+    constructor(source, options = {}) {
+        this.source = source;
+        this.options = options;
+        const { promise, resolve, reject } = Promise.withResolvers();
+        this.completionPromise = promise;
+        this.resolveCompletion = (res) => {
+            this.isCompleted = true;
+            resolve(res);
+        };
+        this.rejectCompletion = (err) => {
+            this.isCompleted = true;
+            reject(err);
+        };
+        // Prevent unhandled rejection when the iterator throws and nobody awaits completionPromise
+        this.completionPromise.catch(() => { });
+    }
+    async establishConnection() {
+        if (!isFunction(this.source)) {
+            const reader = this.source.getReader();
+            return { reader, firstChunk: null };
+        }
+        let attemptCount = 0;
+        const maxRetries = this.options.maxRetries ?? 0;
+        const initialDelay = this.options.initialRetryDelayMs ?? 1000;
+        while (true) {
+            if (this.options.signal?.aborted) {
+                throw abortException(this.options.signal);
+            }
+            let activeReader = null;
+            try {
+                const response = await this.source();
+                if (!response.ok) {
+                    const status = response.status;
+                    const rawBody = await response.text();
+                    const message = extractUpstreamErrorMessage(rawBody) ||
+                        `Connection establishment failed with status ${status}`;
+                    throw new ChatUpstreamError(message, status, rawBody);
+                }
+                if (!response.body) {
+                    throw new Error("Response body is empty");
+                }
+                activeReader = response.body.getReader();
+                // Connection establishment boundary: succeeds only when the first byte arrives!
+                const firstChunk = await activeReader.read();
+                if (firstChunk.done) {
+                    throw new Error("Connection closed before first chunk arrived");
+                }
+                return { reader: activeReader, firstChunk };
+            }
+            catch (err) {
+                if (activeReader) {
+                    activeReader.releaseLock();
+                }
+                // Never retry 4xx client errors or abort signals
+                const isClientError = (err instanceof ChatUpstreamError &&
+                    err.status >= 400 &&
+                    err.status < 500) ||
+                    (isObject(err) &&
+                        "status" in err &&
+                        isNumber(err.status) &&
+                        err.status >= 400 &&
+                        err.status < 500);
+                if (isClientError || attemptCount >= maxRetries) {
+                    throw err;
+                }
+                const retryDelay = initialDelay * 2 ** attemptCount;
+                attemptCount++;
+                await delay(retryDelay, { signal: this.options.signal });
+            }
+        }
+    }
+    *drainQueue(queue) {
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (item) {
+                this.accumulator.record(item);
+                yield item;
+            }
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        if (this.hasStartedIterating) {
+            throw new Error("ChatStream can only be iterated once directly; use finalResponse() to read accumulated output.");
+        }
+        this.hasStartedIterating = true;
+        let reader;
+        let abortCleanup;
+        try {
+            const conn = await this.establishConnection();
+            reader = conn.reader;
+            const firstChunk = conn.firstChunk;
+            if (this.options.signal?.aborted) {
+                throw abortException(this.options.signal);
+            }
+            const decoder = new TextDecoder();
+            const queue = [];
+            const parser = createParser({
+                onEvent: (event) => {
+                    if (!event.data || event.data === "[DONE]")
+                        return;
+                    const [jsonErr, raw] = attempt(() => JSON.parse(event.data));
+                    if (jsonErr || !isObject(raw))
+                        return;
+                    let normalized = raw;
+                    if ("type" in raw &&
+                        raw.type === "tool-input-available" &&
+                        "toolCallId" in raw &&
+                        isString(raw.toolCallId) &&
+                        "toolName" in raw &&
+                        isString(raw.toolName)) {
+                        normalized = {
+                            type: "tool-call",
+                            toolCallId: raw.toolCallId,
+                            toolName: raw.toolName,
+                            args: "input" in raw ? raw.input : undefined,
+                        };
+                    }
+                    else if ("type" in raw &&
+                        raw.type === "tool-output-available" &&
+                        "toolCallId" in raw &&
+                        isString(raw.toolCallId)) {
+                        normalized = {
+                            type: "tool-result",
+                            toolCallId: raw.toolCallId,
+                            result: "output" in raw ? raw.output : undefined,
+                        };
+                    }
+                    else if ("type" in raw &&
+                        raw.type === "text-delta" &&
+                        !("delta" in raw) &&
+                        "textDelta" in raw &&
+                        isString(raw.textDelta)) {
+                        normalized = {
+                            type: "text-delta",
+                            delta: raw.textDelta,
+                            id: "id" in raw && isString(raw.id) ? raw.id : undefined,
+                        };
+                    }
+                    else if ("type" in raw &&
+                        raw.type === "reasoning-delta" &&
+                        !("delta" in raw) &&
+                        "reasoningDelta" in raw &&
+                        isString(raw.reasoningDelta)) {
+                        normalized = {
+                            type: "reasoning-delta",
+                            delta: raw.reasoningDelta,
+                            id: "id" in raw && isString(raw.id) ? raw.id : undefined,
+                        };
+                    }
+                    const parsed = ChatStreamEventSchema.safeParse(normalized);
+                    if (!parsed.success)
+                        return;
+                    const ev = parsed.data;
+                    queue.push(ev);
+                    match(ev)
+                        .with({ type: "tool-result", result: P.nonNullable }, ({ result }) => {
+                        const media = extractMediaResult(result);
+                        if (media) {
+                            queue.push({
+                                type: "media-result",
+                                result: media,
+                            });
+                        }
+                    })
+                        .with(P._, () => { })
+                        .exhaustive();
+                },
+            });
+            const abortPromise = new Promise((_, reject) => {
+                if (this.options.signal) {
+                    const onAbort = () => {
+                        reader?.cancel().catch(() => { });
+                        reject(abortException(this.options.signal));
+                    };
+                    this.options.signal.addEventListener("abort", onAbort, {
+                        once: true,
+                    });
+                    abortCleanup = () => this.options.signal?.removeEventListener("abort", onAbort);
+                }
+            });
+            if (firstChunk) {
+                if (firstChunk.done) {
+                    throw new Error("Connection closed before first chunk arrived");
+                }
+                parser.feed(decoder.decode(firstChunk.value, { stream: true }));
+                yield* this.drainQueue(queue);
+            }
+            while (true) {
+                if (this.options.signal?.aborted) {
+                    throw abortException(this.options.signal);
+                }
+                const readPromise = reader.read();
+                const { done, value } = await Promise.race([readPromise, abortPromise]);
+                if (done)
+                    break;
+                parser.feed(decoder.decode(value, { stream: true }));
+                yield* this.drainQueue(queue);
+            }
+            parser.feed(decoder.decode());
+            yield* this.drainQueue(queue);
+            const finalRes = this.accumulator.toResponse();
+            this.resolveCompletion(finalRes);
+            this.options.onFinalResponse?.(finalRes);
+        }
+        catch (err) {
+            this.rejectCompletion(err);
+            this.options.onError?.(err);
+            throw err;
+        }
+        finally {
+            abortCleanup?.();
+            reader?.cancel().catch(() => { });
+            reader?.releaseLock();
+            if (!this.isCompleted) {
+                const finalRes = this.accumulator.toResponse();
+                this.resolveCompletion(finalRes);
+            }
+        }
+    }
+    /**
+     * Resolves with the aggregated final response.
+     * Awaits stream completion whether called before, during, or after iteration.
+     */
+    async finalResponse() {
+        if (!this.hasStartedIterating) {
+            (async () => {
+                try {
+                    for await (const _ of this) {
+                        // iterator consumption records into accumulator and resolves completionPromise
+                    }
+                }
+                catch {
+                    // errors are already caught and routed to rejectCompletion inside iterator
+                }
+            })();
+        }
+        return this.completionPromise;
+    }
+    /**
+     * Convenience helper that consumes the stream and resolves with just the full text.
+     */
+    async finalText() {
+        const response = await this.finalResponse();
+        return response.text;
+    }
+    /**
+     * Settles when the stream completes, is cancelled, or encounters an error.
+     * Unlike finalResponse(), awaiting settled does not automatically start background iteration.
+     */
+    get settled() {
+        return this.completionPromise.then(() => { }, () => { });
+    }
+}

package/dist/transport/errors.d.ts

@@ -0,0 +1,30 @@
+/** Marker used by the host app to distinguish local session expiry from upstream 401s. */
+export declare const ERR_SESSION_EXPIRED = "SESSION_EXPIRED";
+export declare class ChatUpstreamError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+export type ChatUpstreamErrorBody = {
+    error?: {
+        code?: string | number;
+        message?: string;
+        err_code?: string | number;
+        message_cn?: string;
+        message_en?: string;
+        message_ja?: string;
+    };
+    msg?: string;
+    message?: string;
+};
+/**
+ * Parses the raw upstream response body and extracts the human-readable error message.
+ *
+ * Implements the 5-level fallback priority:
+ * 1. Localized messages (`message_cn`, `message_en`, `message_ja`)
+ * 2. Standard nested message (`error.message`)
+ * 3. Top-level `msg`
+ * 4. Top-level `message`
+ * 5. String body fallback
+ */
+export declare function extractUpstreamErrorMessage(body: unknown): string | null;

package/dist/transport/errors.js

@@ -0,0 +1,47 @@
+import { attempt } from "es-toolkit";
+import { isString } from "es-toolkit/predicate";
+import { match, P } from "ts-pattern";
+/** Marker used by the host app to distinguish local session expiry from upstream 401s. */
+export const ERR_SESSION_EXPIRED = "SESSION_EXPIRED";
+export class ChatUpstreamError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ChatUpstreamError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Parses the raw upstream response body and extracts the human-readable error message.
+ *
+ * Implements the 5-level fallback priority:
+ * 1. Localized messages (`message_cn`, `message_en`, `message_ja`)
+ * 2. Standard nested message (`error.message`)
+ * 3. Top-level `msg`
+ * 4. Top-level `message`
+ * 5. String body fallback
+ */
+export function extractUpstreamErrorMessage(body) {
+    if (!body)
+        return null;
+    if (isString(body)) {
+        const trimmed = body.trim();
+        if (!trimmed)
+            return null;
+        const [err, parsed] = attempt(() => JSON.parse(trimmed));
+        if (!err) {
+            return extractUpstreamErrorMessage(parsed);
+        }
+        return trimmed;
+    }
+    return match(body)
+        .with({ error: { message_cn: P.select(P.string) } }, (msg) => msg.trim() || null)
+        .with({ error: { message: P.select(P.string) } }, (msg) => msg.trim() || null)
+        .with({ message_cn: P.select(P.string) }, (msg) => msg.trim() || null)
+        .with({ message: P.select(P.string) }, (msg) => msg !== ERR_SESSION_EXPIRED ? msg.trim() || null : null)
+        .with({ error: P.select(P.string) }, (msg) => msg !== ERR_SESSION_EXPIRED ? msg.trim() || null : null)
+        .with(P._, () => null)
+        .exhaustive();
+}

package/dist/transport/types.d.ts

@@ -0,0 +1,44 @@
+/** Text part of an OpenAI-format message content array. */
+export type ChatContentPartText = {
+    type: "text";
+    text: string;
+};
+/** Image part of an OpenAI-format message content array. */
+export type ChatContentPartImage = {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+/** Tool call emitted by an assistant message. */
+export type ChatToolCall = {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+/** A single OpenAI-format chat message. Core never accepts AI SDK message types. */
+export type ChatUpstreamMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | Array<ChatContentPartText | ChatContentPartImage> | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ChatToolCall[];
+};
+/** Request payload sent to the 302.AI async completions endpoint. */
+export type ChatUpstreamRequest = {
+    apiBaseUrl: string;
+    apiKey: string;
+    sessionId: string;
+    messages: ChatUpstreamMessage[];
+    locale?: string;
+    modelParams?: unknown;
+    skillUrls?: string[];
+    chatTaskId?: string;
+    sinceSeq?: number | string;
+    structuredOutput?: boolean;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+};

package/dist/transport/types.js

@@ -0,0 +1 @@
+export {};

package/dist/transport/upstream.d.ts

@@ -0,0 +1,8 @@
+import type { ChatUpstreamRequest } from "./types.js";
+/**
+ * Sends one chat turn to the 302.AI async completions endpoint and returns the
+ * raw streaming response. Callers own their own SSE pipeline; core applies none.
+ *
+ * @throws {ChatUpstreamError} when the upstream status is not ok.
+ */
+export declare function sendChatUpstream(req: ChatUpstreamRequest): Promise<Response>;

package/dist/transport/upstream.js

@@ -0,0 +1,63 @@
+import { isString } from "es-toolkit/predicate";
+import { ChatUpstreamError, extractUpstreamErrorMessage } from "./errors.js";
+/** Fixed by the upstream contract; not caller-controllable. */
+const ASYNC_COMPLETIONS_PATH = "/302/media-studio/chat/completions/async";
+const SESSION_ID_HEADER = "X-User-Session-Id";
+const UI_LOCALE_HEADER = "X-UI-Locale";
+function buildHeaders(req) {
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${req.apiKey}`,
+        [SESSION_ID_HEADER]: req.sessionId,
+    };
+    if (req.locale) {
+        headers[UI_LOCALE_HEADER] = req.locale;
+    }
+    return headers;
+}
+function buildBody(req) {
+    const body = {
+        stream: true,
+        messages: req.messages,
+        session_id: req.sessionId,
+        structured_output: req.structuredOutput ?? false,
+    };
+    if (req.modelParams !== undefined) {
+        body.model_params = isString(req.modelParams)
+            ? req.modelParams
+            : JSON.stringify(req.modelParams);
+    }
+    if (req.skillUrls?.length) {
+        body.skill_urls = req.skillUrls;
+    }
+    if (req.chatTaskId) {
+        body.chat_task_id = req.chatTaskId;
+        if (req.sinceSeq !== undefined) {
+            body.since_seq = req.sinceSeq;
+        }
+    }
+    return body;
+}
+/**
+ * Sends one chat turn to the 302.AI async completions endpoint and returns the
+ * raw streaming response. Callers own their own SSE pipeline; core applies none.
+ *
+ * @throws {ChatUpstreamError} when the upstream status is not ok.
+ */
+export async function sendChatUpstream(req) {
+    const url = `${req.apiBaseUrl.replace(/\/+$/, "")}${ASYNC_COMPLETIONS_PATH}`;
+    const fetchFn = req.fetch ?? fetch;
+    const response = await fetchFn(url, {
+        method: "POST",
+        headers: buildHeaders(req),
+        body: JSON.stringify(buildBody(req)),
+        signal: req.signal,
+    });
+    if (!response.ok) {
+        const rawBody = await response.text();
+        const message = extractUpstreamErrorMessage(rawBody) ||
+            `Upstream request failed with ${response.status}`;
+        throw new ChatUpstreamError(message, response.status, rawBody);
+    }
+    return response;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@302ai/media-studio-core",
+  "version": "0.1.0-beta.0",
+  "description": "Outbound client for the 302.AI media-studio async chat completions SSE endpoint",
+  "author": "302.AI",
+  "license": "Apache-2.0",
+  "homepage": "https://302.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/302ai/AI-Media-Studio.git",
+    "directory": "packages/media-studio-core"
+  },
+  "keywords": [
+    "302.ai",
+    "chat",
+    "sse",
+    "streaming",
+    "media-studio"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun scripts/fix-dist.ts",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "es-toolkit": "^1.46.1",
+    "eventsource-parser": "^4.1.0",
+    "nanoid": "^5.1.11",
+    "ts-pattern": "^5.9.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "typescript": "^7"
+  }
+}