@comfyorg/sdk 0.1.0

package/dist/sdk/assets.js

@@ -0,0 +1,200 @@
+/**
+ * Content-addressed asset handles and their constructors.
+ *
+ * `client.assets.from*` returns a **lazy** {@link Asset} handle: no network
+ * at construction. On first use (`commit`/`asReference`/submit) the handle
+ * hashes its bytes locally with blake3, probes the server's dedup
+ * fast-path (`HEAD by-hash` then `from-hash` mint over existing bytes), and
+ * only streams a full multipart upload when the server does not already
+ * have the bytes. Because the handle carries an idempotency key,
+ * re-running a script re-uploads nothing whose bytes already made it to
+ * the server. Mirrors `comfy_sdk.assets` in the Python SDK — folded to one
+ * async class since JS is async-native (no separate sync variant).
+ */
+import { basename, extname } from "node:path";
+import { ASSET_HANDLE, assetReference, newIdempotencyKey } from "./core.js";
+import { translate } from "./exceptions.js";
+import { hashBytes, hashFile } from "./hashing.js";
+const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+// A small, deliberately non-exhaustive extension -> MIME map: Node has no
+// bundled equivalent of Python's `mimetypes.guess_type`, and pulling in a
+// full MIME database for a handful of common asset kinds isn't worth the
+// dependency. Anything unrecognized falls back to `application/octet-stream`
+// (the server never trusts this — it is a convenience default only).
+const EXTENSION_CONTENT_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".flac": "audio/flac",
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".safetensors": "application/octet-stream",
+};
+function guessContentType(name) {
+    if (!name)
+        return DEFAULT_CONTENT_TYPE;
+    return EXTENSION_CONTENT_TYPES[extname(name).toLowerCase()] ?? DEFAULT_CONTENT_TYPE;
+}
+function noOpener() {
+    throw new Error("this asset is already committed; nothing to upload");
+}
+function fileSource(path) {
+    const name = basename(path);
+    return {
+        contentType: guessContentType(name),
+        filePath: name,
+        hasher: () => hashFile(path),
+        // `fs.openAsBlob` is a lazy, disk-backed Blob: reading it (by
+        // `fetch`/undici, while encoding the multipart body) streams from disk
+        // on demand instead of loading the whole file into memory up front —
+        // this is what makes `postAssets` a genuine streaming upload.
+        opener: async () => {
+            const { openAsBlob } = await import("node:fs");
+            return openAsBlob(path, { type: guessContentType(name) });
+        },
+    };
+}
+function bytesSource(data, filename, contentType) {
+    const name = filename ?? "upload.bin";
+    return {
+        contentType: contentType ?? guessContentType(filename),
+        filePath: name,
+        hasher: () => hashBytes(data),
+        opener: async () => new Blob([data]),
+    };
+}
+export class Asset {
+    [ASSET_HANDLE] = true;
+    low;
+    source;
+    idempotencyKey = newIdempotencyKey();
+    hashValue;
+    idValue;
+    createdNewValue = null;
+    constructor(low, source) {
+        this.low = low;
+        this.source = source;
+    }
+    get id() {
+        return this.idValue;
+    }
+    get filePath() {
+        return this.source.filePath;
+    }
+    get createdNew() {
+        return this.createdNewValue;
+    }
+    /** The local blake3 (computed once, lazily). */
+    async hash() {
+        this.hashValue ??= await this.source.hasher();
+        return this.hashValue;
+    }
+    /**
+     * Adopt a resolved `Asset` model's identity. Not part of the public
+     * surface — used internally after a commit and by
+     * {@link AssetFactory.get} to rehydrate an already-committed handle.
+     */
+    adopt(asset) {
+        this.idValue = asset.id;
+        if (asset.hash)
+            this.hashValue = asset.hash;
+        this.createdNewValue = asset.created_new ?? null;
+    }
+    /** Force the hash/dedup/upload now; return the asset UUID. */
+    async commit(signal) {
+        if (this.idValue !== undefined)
+            return this.idValue;
+        const digest = await this.hash();
+        const asset = await translate(async () => {
+            if (await this.low.headAssetByHash(digest, { signal })) {
+                return this.low.assetFromHash(digest, { filePath: this.source.filePath, signal });
+            }
+            const blob = await this.source.opener();
+            return this.low.postAssets(blob, this.source.contentType, this.source.filePath, {
+                expectedHash: digest,
+                idempotencyKey: this.idempotencyKey,
+                signal,
+            });
+        });
+        this.adopt(asset);
+        return this.idValue;
+    }
+    /** The `core/ASSET` object (commits first if needed). */
+    async asReference(signal) {
+        await this.commit(signal);
+        return assetReference(this.idValue, { hash: this.hashValue, filePath: this.source.filePath });
+    }
+}
+/** `client.assets` — alternative constructors for {@link Asset}. */
+export class AssetFactory {
+    low;
+    constructor(low) {
+        this.low = low;
+    }
+    fromFile(path) {
+        return new Asset(this.low, fileSource(path));
+    }
+    fromBytes(data, options = {}) {
+        return new Asset(this.low, bytesSource(data, options.filename, options.contentType));
+    }
+    /**
+     * Buffers the stream fully so the dedup probe can hash before upload
+     * (the bytes must be re-readable for the upload itself). If the source
+     * is a file, prefer {@link fromFile} — it stays lazy end to end.
+     */
+    async fromStream(stream, options = {}) {
+        const data = await bufferStream(stream);
+        return new Asset(this.low, bytesSource(data, options.filename, options.contentType));
+    }
+    /** Client-side download (not a server-side fetch): the bytes must
+     * transit the same blake3 -> dedup -> upload pipeline as every other
+     * source. */
+    async fromUrl(url) {
+        const response = await fetch(url, { redirect: "follow" });
+        if (!response.ok) {
+            throw new Error(`failed to download ${url}: HTTP ${response.status}`);
+        }
+        const data = new Uint8Array(await response.arrayBuffer());
+        const filename = basename(new URL(url).pathname) || "download.bin";
+        const contentType = response.headers.get("Content-Type")?.split(";")[0] || undefined;
+        return new Asset(this.low, bytesSource(data, filename, contentType));
+    }
+    /** Rehydrate an already-committed asset by UUID. */
+    async get(assetId) {
+        const model = await translate(() => this.low.getAsset(assetId));
+        const asset = new Asset(this.low, {
+            contentType: model.content_type,
+            filePath: model.file_path ?? assetId,
+            hasher: async () => model.hash ?? "",
+            opener: noOpener,
+        });
+        asset.adopt(model);
+        return asset;
+    }
+}
+async function bufferStream(stream) {
+    if (Symbol.asyncIterator in stream) {
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of stream) {
+            chunks.push(chunk);
+            total += chunk.length;
+        }
+        const merged = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            merged.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return merged;
+    }
+    throw new TypeError("stream must be async-iterable (a Node Readable or a web ReadableStream)");
+}

package/dist/sdk/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `Comfy` — the client integrators import.
+ *
+ * Runs an API-format workflow against any Comfy API v2 surface (self-hosted
+ * proxy, Comfy Cloud, serverless) — the only per-surface difference is the
+ * base URL and an optional key — and owns everything a generator cannot
+ * produce: local blake3 dedup-upload, `core/ASSET` substitution, idempotent
+ * submit, live SSE with a poll-authoritative backstop, range-aware
+ * downloads, and typed errors. It is layered over `../low` (the generated
+ * types/validators + thin transport).
+ *
+ * Mirrors `comfy_sdk.client.AsyncComfy` in the Python SDK — there is no
+ * separate sync client here (JS is async-native, so the Python SDK's
+ * sync/async split collapses to one class).
+ *
+ * @example
+ * ```ts
+ * import { Comfy } from "@comfyorg/sdk";
+ *
+ * const client = new Comfy("http://127.0.0.1:8189"); // self-hosted, no key
+ * // const client = new Comfy("https://api.comfy.org", { apiKey: "ck_..." });
+ *
+ * const wf = await client.workflows.fromFile("workflow_api.json");
+ * const asset = client.assets.fromFile("photo.png"); // lazy; uploaded on use
+ * wf.setInput("10", "image", asset);
+ *
+ * const job = await client.run(wf); // submit + poll-to-done
+ * (await job.getOutputs("13")[0].toFile("out.png"));
+ * ```
+ */
+import { type ComfyLowOptions } from "../low/index.js";
+import { AssetFactory } from "./assets.js";
+import { Job, JobFactory } from "./jobs.js";
+import type { Workflow } from "./workflows.js";
+import { WorkflowFactory } from "./workflows.js";
+export interface ComfyOptions {
+    apiKey?: string;
+    timeoutMs?: number;
+    fetch?: ComfyLowOptions["fetch"];
+}
+export declare class Comfy {
+    private readonly low;
+    readonly assets: AssetFactory;
+    readonly workflows: WorkflowFactory;
+    readonly jobs: JobFactory;
+    constructor(baseUrl: string, options?: ComfyOptions);
+    private materialize;
+    /**
+     * Submit a workflow. Retries `queue_full` with `Retry-After`. An aborted
+     * `signal` stops asset materialization, the submit request, and the
+     * `queue_full` retry pause.
+     *
+     * Sends an auto-generated `Idempotency-Key` so the server rejects an
+     * accidental exact resend of *this* request (`422 idempotency_key_reuse`)
+     * instead of creating a duplicate job. Each call mints a fresh key, so
+     * calling `submit()` again is a distinct submission — to make a retry
+     * idempotent, pass an explicit `idempotencyKey` and reuse it. Note a reused
+     * key is *rejected*, not replayed: on reuse, catch the error and poll/list
+     * for the job the first attempt already created.
+     */
+    submit(workflow: Workflow, options?: {
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<Job>;
+    /** Submit, then poll to terminal (authoritative). Throws on failure. */
+    run(workflow: Workflow, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<Job>;
+}

package/dist/sdk/client.js

@@ -0,0 +1,120 @@
+/**
+ * `Comfy` — the client integrators import.
+ *
+ * Runs an API-format workflow against any Comfy API v2 surface (self-hosted
+ * proxy, Comfy Cloud, serverless) — the only per-surface difference is the
+ * base URL and an optional key — and owns everything a generator cannot
+ * produce: local blake3 dedup-upload, `core/ASSET` substitution, idempotent
+ * submit, live SSE with a poll-authoritative backstop, range-aware
+ * downloads, and typed errors. It is layered over `../low` (the generated
+ * types/validators + thin transport).
+ *
+ * Mirrors `comfy_sdk.client.AsyncComfy` in the Python SDK — there is no
+ * separate sync client here (JS is async-native, so the Python SDK's
+ * sync/async split collapses to one class).
+ *
+ * @example
+ * ```ts
+ * import { Comfy } from "@comfyorg/sdk";
+ *
+ * const client = new Comfy("http://127.0.0.1:8189"); // self-hosted, no key
+ * // const client = new Comfy("https://api.comfy.org", { apiKey: "ck_..." });
+ *
+ * const wf = await client.workflows.fromFile("workflow_api.json");
+ * const asset = client.assets.fromFile("photo.png"); // lazy; uploaded on use
+ * wf.setInput("10", "image", asset);
+ *
+ * const job = await client.run(wf); // submit + poll-to-done
+ * (await job.getOutputs("13")[0].toFile("out.png"));
+ * ```
+ */
+import { ApiError, ComfyLow } from "../low/index.js";
+import { abortableSleep } from "./abortable-sleep.js";
+import { AssetFactory } from "./assets.js";
+import { findAssetHandles, looksLikeUiFormat, newIdempotencyKey, substituteAssetHandles, SUCCESS, } from "./core.js";
+import { JobFailed, QueueFull, WorkflowFormatUi, toSdkError } from "./exceptions.js";
+import { Job, JobFactory } from "./jobs.js";
+import { WorkflowFactory } from "./workflows.js";
+// How long to keep retrying a full queue before giving up (ms).
+const QUEUE_RETRY_BUDGET_MS = 60_000;
+const DEFAULT_RETRY_AFTER_S = 2;
+function guardUiFormat(workflow) {
+    if (looksLikeUiFormat(workflow.json)) {
+        throw new WorkflowFormatUi("workflow is in UI-export format (nodes/links/last_node_id); submit the API-format graph instead", { code: "workflow_format_ui", httpStatus: 422 });
+    }
+}
+export class Comfy {
+    low;
+    assets;
+    workflows;
+    jobs;
+    constructor(baseUrl, options = {}) {
+        this.low = new ComfyLow(baseUrl, options.apiKey, {
+            timeoutMs: options.timeoutMs,
+            fetch: options.fetch,
+        });
+        this.assets = new AssetFactory(this.low);
+        this.workflows = new WorkflowFactory();
+        this.jobs = new JobFactory(this.low);
+    }
+    async materialize(workflow, signal) {
+        const handles = findAssetHandles(workflow.json);
+        const refs = new Map();
+        for (const handle of handles) {
+            refs.set(handle, await handle.asReference(signal));
+        }
+        return substituteAssetHandles(workflow.json, refs);
+    }
+    /**
+     * Submit a workflow. Retries `queue_full` with `Retry-After`. An aborted
+     * `signal` stops asset materialization, the submit request, and the
+     * `queue_full` retry pause.
+     *
+     * Sends an auto-generated `Idempotency-Key` so the server rejects an
+     * accidental exact resend of *this* request (`422 idempotency_key_reuse`)
+     * instead of creating a duplicate job. Each call mints a fresh key, so
+     * calling `submit()` again is a distinct submission — to make a retry
+     * idempotent, pass an explicit `idempotencyKey` and reuse it. Note a reused
+     * key is *rejected*, not replayed: on reuse, catch the error and poll/list
+     * for the job the first attempt already created.
+     */
+    async submit(workflow, options = {}) {
+        guardUiFormat(workflow);
+        const graph = await this.materialize(workflow, options.signal);
+        const key = options.idempotencyKey ?? newIdempotencyKey();
+        const deadline = Date.now() + QUEUE_RETRY_BUDGET_MS;
+        for (;;) {
+            try {
+                const job = await this.low.postJobs(graph, {
+                    idempotencyKey: key,
+                    signal: options.signal,
+                });
+                return new Job(this.low, job);
+            }
+            catch (exc) {
+                if (!(exc instanceof ApiError))
+                    throw exc;
+                const err = toSdkError(exc);
+                if (err instanceof QueueFull && Date.now() < deadline) {
+                    await abortableSleep((err.retryAfter || DEFAULT_RETRY_AFTER_S) * 1000, options.signal);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    /** Submit, then poll to terminal (authoritative). Throws on failure. */
+    async run(workflow, options = {}) {
+        const job = await this.submit(workflow, { signal: options.signal });
+        return options.timeoutMs === undefined
+            ? job.result(options.signal)
+            : runWithTimeout(job, options.timeoutMs, options.signal);
+    }
+}
+async function runWithTimeout(job, timeoutMs, signal) {
+    await job.wait(timeoutMs, signal);
+    if (job.status !== SUCCESS) {
+        throw new JobFailed(`job ${job.id} ended ${job.status}`, { error: job.error });
+    }
+    return job;
+}

package/dist/sdk/core.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Sans-IO core shared across the `sdk` layer.
+ *
+ * Pure decision logic — no network, no awaiting — for terminal-state
+ * detection, adaptive poll backoff, idempotency-key minting, the
+ * `core/ASSET` reference shape, and the workflow-graph walk that finds and
+ * substitutes asset handles. Mirrors `comfy_sdk._core` in the Python SDK.
+ */
+import type { AssetReference } from "../low/index.js";
+export declare const TERMINAL: Set<string>;
+export declare const SUCCESS = "succeeded";
+export declare function newIdempotencyKey(): string;
+export declare function isTerminal(status: string): boolean;
+/** Adaptive poll intervals (ms): start small, grow, then hold at the cap. */
+export declare function backoffSchedule(start?: number, factor?: number, cap?: number): Generator<number, never, void>;
+/** Build the `core/ASSET` object substituted into workflow JSON. */
+export declare function assetReference(assetId: string, options?: {
+    hash?: string | null;
+    filePath?: string | null;
+}): AssetReference;
+export declare const ASSET_HANDLE: unique symbol;
+export interface AssetHandleLike {
+    readonly [ASSET_HANDLE]: true;
+    asReference(signal?: AbortSignal): Promise<AssetReference>;
+}
+/** Collect every asset handle embedded anywhere in the workflow graph. */
+export declare function findAssetHandles(graph: unknown): AssetHandleLike[];
+/**
+ * Return a copy of `graph` with each asset handle replaced by its
+ * `core/ASSET` reference, keyed by identity in `refs`.
+ */
+export declare function substituteAssetHandles(graph: unknown, refs: Map<AssetHandleLike, AssetReference>): unknown;
+export declare function looksLikeUiFormat(graph: unknown): boolean;

package/dist/sdk/core.js

@@ -0,0 +1,89 @@
+/**
+ * Sans-IO core shared across the `sdk` layer.
+ *
+ * Pure decision logic — no network, no awaiting — for terminal-state
+ * detection, adaptive poll backoff, idempotency-key minting, the
+ * `core/ASSET` reference shape, and the workflow-graph walk that finds and
+ * substitutes asset handles. Mirrors `comfy_sdk._core` in the Python SDK.
+ */
+import { randomUUID } from "node:crypto";
+// Terminal job states. `canceling` is deliberately NOT terminal —
+// cancellation takes effect at node/step boundaries and can take seconds.
+export const TERMINAL = new Set(["succeeded", "canceled", "failed", "expired"]);
+export const SUCCESS = "succeeded";
+export function newIdempotencyKey() {
+    return randomUUID();
+}
+export function isTerminal(status) {
+    return TERMINAL.has(status);
+}
+/** Adaptive poll intervals (ms): start small, grow, then hold at the cap. */
+export function* backoffSchedule(start = 500, factor = 1.5, cap = 5_000) {
+    let delay = start;
+    for (;;) {
+        yield delay;
+        delay = Math.min(delay * factor, cap);
+    }
+}
+/** Build the `core/ASSET` object substituted into workflow JSON. */
+export function assetReference(assetId, options = {}) {
+    const info = { id: assetId };
+    if (options.hash)
+        info.hash = options.hash;
+    if (options.filePath)
+        info.file_path = options.filePath;
+    return { __type: "core/ASSET", info };
+}
+// A unique marker so `findAssetHandles`/`substituteAssetHandles` can spot an
+// asset handle embedded anywhere in a workflow graph without importing
+// `Asset` here (avoids a core <-> assets circular import).
+export const ASSET_HANDLE = Symbol("comfy.assetHandle");
+function isAssetHandle(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[ASSET_HANDLE] === true);
+}
+/** Collect every asset handle embedded anywhere in the workflow graph. */
+export function findAssetHandles(graph) {
+    if (isAssetHandle(graph))
+        return [graph];
+    if (Array.isArray(graph))
+        return graph.flatMap(findAssetHandles);
+    if (graph !== null && typeof graph === "object") {
+        return Object.values(graph).flatMap(findAssetHandles);
+    }
+    return [];
+}
+/**
+ * Return a copy of `graph` with each asset handle replaced by its
+ * `core/ASSET` reference, keyed by identity in `refs`.
+ */
+export function substituteAssetHandles(graph, refs) {
+    if (isAssetHandle(graph)) {
+        const ref = refs.get(graph);
+        if (!ref)
+            throw new Error("asset handle was not materialized before substitution");
+        return ref;
+    }
+    if (Array.isArray(graph)) {
+        return graph.map((v) => substituteAssetHandles(v, refs));
+    }
+    if (graph !== null && typeof graph === "object") {
+        return Object.fromEntries(Object.entries(graph).map(([k, v]) => [
+            k,
+            substituteAssetHandles(v, refs),
+        ]));
+    }
+    return graph;
+}
+// UI-export detection: the ComfyUI editor export carries these top-level
+// keys, whereas the API format is a flat node-id -> node map. Catching it
+// locally lets the SDK fail fast with a clear message instead of relying
+// only on the server.
+const UI_KEYS = ["nodes", "links", "last_node_id"];
+export function looksLikeUiFormat(graph) {
+    if (graph === null || typeof graph !== "object" || Array.isArray(graph))
+        return false;
+    const record = graph;
+    return UI_KEYS.every((key) => key in record);
+}

package/dist/sdk/events.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed, discriminated (`switch (event.kind)`-able) streamed events.
+ *
+ * The raw SSE frames from `../low` (an event name + a data record) are
+ * lifted into a small closed set of interfaces so callers can pattern-match:
+ *
+ * ```ts
+ * for await (const event of job.events()) {
+ *   switch (event.kind) {
+ *     case "progress": ...
+ *     case "outputReady": await event.output.toFile(...); break;
+ *     case "statusChange": if (event.status === "succeeded") return;
+ *   }
+ * }
+ * ```
+ *
+ * Named to match the Python SDK's `comfy_sdk.events` (`Progress`,
+ * `Preview`, `OutputReady`, `StatusChange`, `Log`) with one deviation: the
+ * union is `ComfyEvent`, not `Event` — `Event` is a global DOM/Node type.
+ */
+import type { RawEvent } from "../low/index.js";
+import type { Output } from "./outputs.js";
+export interface Progress {
+    kind: "progress";
+    value: number;
+    message: string | null;
+    nodesDone: number | null;
+    nodesTotal: number | null;
+    currentNode: string | null;
+    step: number | null;
+    steps: number | null;
+}
+export interface Preview {
+    kind: "preview";
+    nodeId: string;
+    contentType: string;
+    data: Uint8Array;
+}
+export interface OutputReady {
+    kind: "outputReady";
+    output: Output;
+}
+export interface StatusChange {
+    kind: "statusChange";
+    status: string;
+    queuePosition: number | null;
+}
+export interface Log {
+    kind: "log";
+    level: string;
+    message: string;
+}
+export type ComfyEvent = Progress | Preview | OutputReady | StatusChange | Log;
+/**
+ * Lift a raw SSE frame into a typed event. `bindOutput` wraps the
+ * low-level output model into an SDK `Output` (the only event type that
+ * needs the transport, for download). Unknown event names return `null` so
+ * the iterator can skip them.
+ */
+export declare function eventFromRaw(raw: RawEvent, bindOutput: (model: Record<string, unknown>) => Output): ComfyEvent | null;

package/dist/sdk/events.js

@@ -0,0 +1,84 @@
+/**
+ * Typed, discriminated (`switch (event.kind)`-able) streamed events.
+ *
+ * The raw SSE frames from `../low` (an event name + a data record) are
+ * lifted into a small closed set of interfaces so callers can pattern-match:
+ *
+ * ```ts
+ * for await (const event of job.events()) {
+ *   switch (event.kind) {
+ *     case "progress": ...
+ *     case "outputReady": await event.output.toFile(...); break;
+ *     case "statusChange": if (event.status === "succeeded") return;
+ *   }
+ * }
+ * ```
+ *
+ * Named to match the Python SDK's `comfy_sdk.events` (`Progress`,
+ * `Preview`, `OutputReady`, `StatusChange`, `Log`) with one deviation: the
+ * union is `ComfyEvent`, not `Event` — `Event` is a global DOM/Node type.
+ */
+function progressFrom(data) {
+    return {
+        kind: "progress",
+        value: typeof data.value === "number" ? data.value : 0,
+        message: data.message ?? null,
+        nodesDone: data.nodes_done ?? null,
+        nodesTotal: data.nodes_total ?? null,
+        currentNode: data.current_node ?? null,
+        step: data.step ?? null,
+        steps: data.steps ?? null,
+    };
+}
+function previewFrom(data) {
+    const raw = typeof data.data_base64 === "string" ? data.data_base64 : "";
+    let decoded;
+    try {
+        decoded = Uint8Array.from(Buffer.from(raw, "base64"));
+    }
+    catch {
+        decoded = new Uint8Array(0);
+    }
+    return {
+        kind: "preview",
+        nodeId: typeof data.node_id === "string" ? data.node_id : "",
+        contentType: typeof data.content_type === "string" ? data.content_type : "application/octet-stream",
+        data: decoded,
+    };
+}
+function statusFrom(data) {
+    return {
+        kind: "statusChange",
+        status: typeof data.status === "string" ? data.status : "",
+        queuePosition: data.queue_position ?? null,
+    };
+}
+function logFrom(data) {
+    return {
+        kind: "log",
+        level: typeof data.level === "string" ? data.level : "info",
+        message: typeof data.message === "string" ? data.message : "",
+    };
+}
+/**
+ * Lift a raw SSE frame into a typed event. `bindOutput` wraps the
+ * low-level output model into an SDK `Output` (the only event type that
+ * needs the transport, for download). Unknown event names return `null` so
+ * the iterator can skip them.
+ */
+export function eventFromRaw(raw, bindOutput) {
+    switch (raw.event) {
+        case "progress":
+            return progressFrom(raw.data);
+        case "preview":
+            return previewFrom(raw.data);
+        case "status":
+            return statusFrom(raw.data);
+        case "log":
+            return logFrom(raw.data);
+        case "output":
+            return { kind: "outputReady", output: bindOutput(raw.data) };
+        default:
+            return null;
+    }
+}