@comfyorg/sdk 0.1.0

package/dist/low/models.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Hand-maintained supplement to the generated models.
+ *
+ * `@hey-api/openapi-ts` only emits types reachable from an operation's
+ * request/response schema. Four schemas in `spec/openapi.yaml` are
+ * documented but never referenced that way — the SSE event payloads
+ * (`StatusEvent`, `PreviewEvent`, `LogEvent`; `progress` and `output`
+ * events reuse the generated `Progress`/`Output` types directly) are only
+ * reachable via the non-standard `x-sse-events` vendor extension, and
+ * `AssetReference` (the `core/ASSET` object) documents a shape substituted
+ * into workflow JSON, not a request/response body. Kept here by hand
+ * instead of forcing codegen to walk vendor extensions it doesn't
+ * understand. `tests/spec-coverage.test.ts` asserts these stay in sync with
+ * the spec's property lists.
+ */
+import type { JobStatus } from "./generated/types.gen.js";
+/** SSE `status` event payload. */
+export interface StatusEvent {
+    status: JobStatus;
+    queue_position?: number | null;
+}
+/** SSE `preview` event payload (JPEG, base64, throttled). */
+export interface PreviewEvent {
+    node_id: string;
+    content_type: string;
+    data_base64: string;
+}
+/** SSE `log` event payload. Best-effort diagnostics. */
+export interface LogEvent {
+    level: string;
+    message: string;
+}
+/**
+ * The typed asset-reference object placed inside workflow JSON where a
+ * filename would normally go: `{"__type": "core/ASSET", "info": {"id":
+ * "asset_...", "hash": "blake3:...", "file_path": "photo.png"}}`. `info.id`
+ * is required and authoritative; `hash`/`file_path` are optional
+ * staging/lookup hints.
+ */
+export interface AssetReference {
+    __type: "core/ASSET";
+    info: {
+        id: string;
+        hash?: string;
+        file_path?: string;
+    };
+}

package/dist/low/models.js

@@ -0,0 +1,16 @@
+/**
+ * Hand-maintained supplement to the generated models.
+ *
+ * `@hey-api/openapi-ts` only emits types reachable from an operation's
+ * request/response schema. Four schemas in `spec/openapi.yaml` are
+ * documented but never referenced that way — the SSE event payloads
+ * (`StatusEvent`, `PreviewEvent`, `LogEvent`; `progress` and `output`
+ * events reuse the generated `Progress`/`Output` types directly) are only
+ * reachable via the non-standard `x-sse-events` vendor extension, and
+ * `AssetReference` (the `core/ASSET` object) documents a shape substituted
+ * into workflow JSON, not a request/response body. Kept here by hand
+ * instead of forcing codegen to walk vendor extensions it doesn't
+ * understand. `tests/spec-coverage.test.ts` asserts these stay in sync with
+ * the spec's property lists.
+ */
+export {};

package/dist/low/sse.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Server-Sent-Events decoding over a `fetch` response body.
+ *
+ * Deliberately built on `eventsource-parser` over the raw fetch stream, not
+ * the `EventSource` global: the global can't send headers (no
+ * `Authorization`/`Accept`) and can't be aborted per-request, both of which
+ * this transport needs. Mirrors the wire-format contract of `comfy_low.sse`
+ * in the Python SDK (a `RawEvent` per frame, `event` defaults to `message`),
+ * but the parsing itself is delegated to `eventsource-parser` rather than
+ * hand-rolled, since JS has no sans-IO decoder to share between a sync and
+ * an async transport the way Python's dual sync/async layers did.
+ */
+export interface RawEvent {
+    event: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Decode a fetch response body into a stream of {@link RawEvent}s.
+ *
+ * No cursor/replay support by design — the contract carries no `id`/
+ * `Last-Event-ID`; a blank `data:` frame (no payload) is dropped, matching
+ * the Python decoder.
+ */
+export declare function iterateSse(body: ReadableStream<Uint8Array>): AsyncGenerator<RawEvent, void, void>;

package/dist/low/sse.js

@@ -0,0 +1,44 @@
+/**
+ * Server-Sent-Events decoding over a `fetch` response body.
+ *
+ * Deliberately built on `eventsource-parser` over the raw fetch stream, not
+ * the `EventSource` global: the global can't send headers (no
+ * `Authorization`/`Accept`) and can't be aborted per-request, both of which
+ * this transport needs. Mirrors the wire-format contract of `comfy_low.sse`
+ * in the Python SDK (a `RawEvent` per frame, `event` defaults to `message`),
+ * but the parsing itself is delegated to `eventsource-parser` rather than
+ * hand-rolled, since JS has no sans-IO decoder to share between a sync and
+ * an async transport the way Python's dual sync/async layers did.
+ */
+import { EventSourceParserStream } from "eventsource-parser/stream";
+function parseData(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { raw };
+    }
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return { value: parsed };
+}
+/**
+ * Decode a fetch response body into a stream of {@link RawEvent}s.
+ *
+ * No cursor/replay support by design — the contract carries no `id`/
+ * `Last-Event-ID`; a blank `data:` frame (no payload) is dropped, matching
+ * the Python decoder.
+ */
+export async function* iterateSse(body) {
+    const stream = body
+        .pipeThrough(new TextDecoderStream())
+        .pipeThrough(new EventSourceParserStream());
+    for await (const message of stream) {
+        if (message.data === "") {
+            continue;
+        }
+        yield { event: message.event || "message", data: parseData(message.data) };
+    }
+}

package/dist/low/transport.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Thin `low` transport over `fetch` — one async function per `operationId`
+ * in `spec/openapi.yaml`, plus the mandatory escape hatches the hand-written
+ * `sdk` layer builds on:
+ *
+ * - **raw response access** — every method's Promise resolves from (or, via
+ *   {@link ComfyLow.request}, directly returns) a `Response` whose body is
+ *   never pre-read.
+ * - **unbuffered / streaming bodies** — a `fetch` `Response.body` is always a
+ *   lazy `ReadableStream`; nothing here buffers it before the caller asks
+ *   for `.json()`/`.body`. This is why, unlike the Python transport (which
+ *   distinguishes a buffering `raw_request` from a streaming `open`), there
+ *   is exactly one request primitive here — fetch's laziness already gives
+ *   both hatches from a single call.
+ * - **streaming request bodies** — `postAssets` takes a `Blob` (a Node
+ *   `fs.openAsBlob()` handle is a lazy, disk-backed `Blob`, so a multi-GB
+ *   upload is never buffered whole in memory) inside a native `FormData`;
+ *   `fetch`/undici streams the encoded body to the wire.
+ * - **per-request timeout/abort** — every method accepts `signal` and
+ *   `timeoutMs`; `AbortSignal.any` composes a caller's signal with this
+ *   client's default timeout (or overrides/disables it per call).
+ *
+ * This layer contains no orchestration, retries, hashing, or SSE
+ * reconnection — those live in `../sdk`. Mirrors `comfy_low.transport` in
+ * the Python SDK (its `AsyncComfyLow`; there is no sync variant here — see
+ * the package README for why).
+ */
+import type { Asset, Job } from "./generated/types.gen.js";
+import { type RawEvent } from "./sse.js";
+export interface RequestOptions {
+    headers?: Record<string, string>;
+    json?: unknown;
+    body?: string | FormData;
+    signal?: AbortSignal;
+    /**
+     * Per-request timeout. `undefined` uses the client's default; `null`
+     * disables the default timeout entirely (used for the SSE stream, which
+     * must not time out while idle mid-job).
+     */
+    timeoutMs?: number | null;
+}
+export interface ComfyLowOptions {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/** Synchronous protocol bindings — async throughout (JS is async-native). */
+export declare class ComfyLow {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    private readonly defaultTimeoutMs;
+    constructor(baseUrl: string, apiKey?: string, options?: ComfyLowOptions);
+    private urlFor;
+    /**
+     * Is `url` on the same origin (scheme + host + port) as this client's
+     * `baseUrl`? A relative `path` always resolves to a `baseUrl`-derived URL
+     * (see {@link urlFor}), so this only ever says "no" for a server-returned
+     * absolute URL (`model.urls.self`/`cancel`/`events`) that points somewhere
+     * else — which is exactly the case where the bearer token must not be
+     * attached.
+     */
+    private isSameOrigin;
+    private buildHeaders;
+    private resolveSignal;
+    /**
+     * The single escape hatch: an unread `Response` (raw headers/status,
+     * lazy body) for a request built from `{json | body}`. Every typed
+     * method below is a thin wrapper over this.
+     */
+    request(method: string, path: string, options?: RequestOptions): Promise<Response>;
+    private parseOrRaise;
+    /** `POST /api/v2/assets` — streaming multipart upload. */
+    postAssets(file: Blob, contentType: string, filePath: string, options?: {
+        expectedHash?: string;
+        tags?: readonly string[];
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+        timeoutMs?: number | null;
+    }): Promise<Asset>;
+    /** `POST /api/v2/assets/from-hash` — dedup mint over existing bytes. */
+    assetFromHash(hash: string, options?: {
+        filePath?: string;
+        tags?: readonly string[];
+        signal?: AbortSignal;
+    }): Promise<Asset>;
+    /** `HEAD /api/v2/assets/by-hash/{hash}` — existence probe. */
+    headAssetByHash(hash: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /** `GET /api/v2/assets/{id}` — metadata with a fresh content URL. */
+    getAsset(assetId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Asset>;
+    /**
+     * `GET /api/v2/assets/{id}/content` — raw, streamed, range-aware body.
+     * Returns the response itself (escape hatch); the caller reads
+     * `response.body`.
+     */
+    getAssetContent(assetId: string, options?: {
+        range?: readonly [number, number];
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /** `POST /api/v2/jobs`. */
+    postJobs(workflow: Record<string, unknown>, options?: {
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<Job>;
+    /** `GET /api/v2/jobs/{id}` (or an absolute self link). */
+    getJob(jobIdOrUrl: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Job>;
+    /**
+     * `GET /api/v2/jobs/{id}/events` — raw live SSE iterator (escape hatch).
+     * No reconnection here; a single connection's frames. `../sdk` adds the
+     * reconnect loop. No default timeout: an idle stream must not time out
+     * mid-job (pass `timeoutMs` to override).
+     */
+    getJobEvents(jobIdOrUrl: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number | null;
+    }): AsyncGenerator<RawEvent, void, void>;
+    /** `POST /api/v2/jobs/{id}/cancel` — idempotent. */
+    cancelJob(jobIdOrUrl: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Job>;
+}
+export declare const OPERATION_IDS: readonly ["postAssets", "assetFromHash", "headAssetByHash", "getAsset", "getAssetContent", "postJobs", "getJob", "getJobEvents", "cancelJob"];
+export declare const OPERATION_METHODS: Record<(typeof OPERATION_IDS)[number], keyof ComfyLow>;

package/dist/low/transport.js

@@ -0,0 +1,285 @@
+/**
+ * Thin `low` transport over `fetch` — one async function per `operationId`
+ * in `spec/openapi.yaml`, plus the mandatory escape hatches the hand-written
+ * `sdk` layer builds on:
+ *
+ * - **raw response access** — every method's Promise resolves from (or, via
+ *   {@link ComfyLow.request}, directly returns) a `Response` whose body is
+ *   never pre-read.
+ * - **unbuffered / streaming bodies** — a `fetch` `Response.body` is always a
+ *   lazy `ReadableStream`; nothing here buffers it before the caller asks
+ *   for `.json()`/`.body`. This is why, unlike the Python transport (which
+ *   distinguishes a buffering `raw_request` from a streaming `open`), there
+ *   is exactly one request primitive here — fetch's laziness already gives
+ *   both hatches from a single call.
+ * - **streaming request bodies** — `postAssets` takes a `Blob` (a Node
+ *   `fs.openAsBlob()` handle is a lazy, disk-backed `Blob`, so a multi-GB
+ *   upload is never buffered whole in memory) inside a native `FormData`;
+ *   `fetch`/undici streams the encoded body to the wire.
+ * - **per-request timeout/abort** — every method accepts `signal` and
+ *   `timeoutMs`; `AbortSignal.any` composes a caller's signal with this
+ *   client's default timeout (or overrides/disables it per call).
+ *
+ * This layer contains no orchestration, retries, hashing, or SSE
+ * reconnection — those live in `../sdk`. Mirrors `comfy_low.transport` in
+ * the Python SDK (its `AsyncComfyLow`; there is no sync variant here — see
+ * the package README for why).
+ */
+import { errorFromEnvelope } from "./errors.js";
+import { iterateSse } from "./sse.js";
+const API_PREFIX = "/api/v2";
+const DEFAULT_TIMEOUT_MS = 30_000;
+function looksLikePath(value) {
+    return value.startsWith("http") || value.startsWith("/");
+}
+function parseRetryAfter(response) {
+    const raw = response.headers.get("Retry-After");
+    if (raw === null)
+        return null;
+    const seconds = Number.parseInt(raw, 10);
+    return Number.isNaN(seconds) ? null : seconds;
+}
+/** Synchronous protocol bindings — async throughout (JS is async-native). */
+export class ComfyLow {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    defaultTimeoutMs;
+    constructor(baseUrl, apiKey, options = {}) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.apiKey = apiKey;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.defaultTimeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    urlFor(path) {
+        if (path.startsWith("http"))
+            return path;
+        if (path.startsWith("/api/"))
+            return this.baseUrl + path;
+        return this.baseUrl + API_PREFIX + path;
+    }
+    /**
+     * Is `url` on the same origin (scheme + host + port) as this client's
+     * `baseUrl`? A relative `path` always resolves to a `baseUrl`-derived URL
+     * (see {@link urlFor}), so this only ever says "no" for a server-returned
+     * absolute URL (`model.urls.self`/`cancel`/`events`) that points somewhere
+     * else — which is exactly the case where the bearer token must not be
+     * attached.
+     */
+    isSameOrigin(url) {
+        try {
+            return new URL(url).origin === new URL(this.baseUrl).origin;
+        }
+        catch {
+            return false;
+        }
+    }
+    buildHeaders(url, extra) {
+        const headers = new Headers();
+        // Only authenticate when a key is set (a local proxy fronts a ComfyUI
+        // with no auth, so we never leak credentials it does not want) AND the
+        // request target is this client's own origin. `getJob`/`cancelJob`/
+        // `getJobEvents` can be fed a server-returned absolute URL
+        // (`model.urls.self/cancel/events`); if that ever points at a different
+        // host, the bearer token must not follow it there.
+        if (this.apiKey && this.isSameOrigin(url)) {
+            headers.set("Authorization", `Bearer ${this.apiKey}`);
+        }
+        if (extra) {
+            for (const [key, value] of Object.entries(extra)) {
+                headers.set(key, value);
+            }
+        }
+        return headers;
+    }
+    resolveSignal(callerSignal, timeoutMs) {
+        const effective = timeoutMs === undefined ? this.defaultTimeoutMs : timeoutMs;
+        if (effective === null)
+            return callerSignal;
+        const timeoutSignal = AbortSignal.timeout(effective);
+        return callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal;
+    }
+    /**
+     * The single escape hatch: an unread `Response` (raw headers/status,
+     * lazy body) for a request built from `{json | body}`. Every typed
+     * method below is a thin wrapper over this.
+     */
+    async request(method, path, options = {}) {
+        const url = this.urlFor(path);
+        const headers = this.buildHeaders(url, options.headers);
+        let body = options.body;
+        if (options.json !== undefined) {
+            headers.set("Content-Type", "application/json");
+            body = JSON.stringify(options.json);
+        }
+        const signal = this.resolveSignal(options.signal, options.timeoutMs);
+        return this.fetchImpl(url, { method, headers, body, signal, redirect: "follow" });
+    }
+    async parseOrRaise(response, ok) {
+        if (ok.includes(response.status)) {
+            if (response.status === 204 || response.headers.get("Content-Length") === "0") {
+                return {};
+            }
+            const text = await response.text();
+            return text ? JSON.parse(text) : {};
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = undefined;
+        }
+        throw errorFromEnvelope(response.status, body, {
+            retryAfter: parseRetryAfter(response),
+        });
+    }
+    // -- assets -------------------------------------------------------------
+    /** `POST /api/v2/assets` — streaming multipart upload. */
+    async postAssets(file, contentType, filePath, options = {}) {
+        const form = new FormData();
+        form.append("file", file, filePath);
+        form.append("content_type", contentType);
+        form.append("file_path", filePath);
+        if (options.expectedHash !== undefined) {
+            form.append("expected_hash", options.expectedHash);
+        }
+        for (const tag of options.tags ?? []) {
+            form.append("tags", tag);
+        }
+        const headers = {};
+        if (options.idempotencyKey) {
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        }
+        const response = await this.request("POST", "/assets", {
+            headers,
+            body: form,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        return this.parseOrRaise(response, [200, 201, 202]);
+    }
+    /** `POST /api/v2/assets/from-hash` — dedup mint over existing bytes. */
+    async assetFromHash(hash, options = {}) {
+        const json = { hash };
+        if (options.filePath !== undefined)
+            json.file_path = options.filePath;
+        if (options.tags !== undefined)
+            json.tags = [...options.tags];
+        const response = await this.request("POST", "/assets/from-hash", {
+            json,
+            signal: options.signal,
+        });
+        return this.parseOrRaise(response, [200, 201]);
+    }
+    /** `HEAD /api/v2/assets/by-hash/{hash}` — existence probe. */
+    async headAssetByHash(hash, options = {}) {
+        const response = await this.request("HEAD", `/assets/by-hash/${encodeURIComponent(hash)}`, {
+            signal: options.signal,
+        });
+        if (response.status === 200)
+            return true;
+        if (response.status === 404)
+            return false;
+        return this.parseOrRaise(response, [200]);
+    }
+    /** `GET /api/v2/assets/{id}` — metadata with a fresh content URL. */
+    async getAsset(assetId, options = {}) {
+        const response = await this.request("GET", `/assets/${encodeURIComponent(assetId)}`, {
+            signal: options.signal,
+        });
+        return this.parseOrRaise(response, [200]);
+    }
+    /**
+     * `GET /api/v2/assets/{id}/content` — raw, streamed, range-aware body.
+     * Returns the response itself (escape hatch); the caller reads
+     * `response.body`.
+     */
+    async getAssetContent(assetId, options = {}) {
+        const headers = {};
+        if (options.range) {
+            headers.Range = `bytes=${options.range[0]}-${options.range[1]}`;
+        }
+        const response = await this.request("GET", `/assets/${encodeURIComponent(assetId)}/content`, {
+            headers,
+            signal: options.signal,
+        });
+        if (response.status !== 200 && response.status !== 206) {
+            await this.parseOrRaise(response, [200, 206]);
+        }
+        return response;
+    }
+    // -- jobs -----------------------------------------------------------------
+    /** `POST /api/v2/jobs`. */
+    async postJobs(workflow, options = {}) {
+        const headers = {};
+        if (options.idempotencyKey) {
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        }
+        const json = { workflow };
+        const response = await this.request("POST", "/jobs", { headers, json, signal: options.signal });
+        return this.parseOrRaise(response, [201]);
+    }
+    /** `GET /api/v2/jobs/{id}` (or an absolute self link). */
+    async getJob(jobIdOrUrl, options = {}) {
+        const path = looksLikePath(jobIdOrUrl) ? jobIdOrUrl : `/jobs/${encodeURIComponent(jobIdOrUrl)}`;
+        const response = await this.request("GET", path, { signal: options.signal });
+        return this.parseOrRaise(response, [200]);
+    }
+    /**
+     * `GET /api/v2/jobs/{id}/events` — raw live SSE iterator (escape hatch).
+     * No reconnection here; a single connection's frames. `../sdk` adds the
+     * reconnect loop. No default timeout: an idle stream must not time out
+     * mid-job (pass `timeoutMs` to override).
+     */
+    async *getJobEvents(jobIdOrUrl, options = {}) {
+        const path = looksLikePath(jobIdOrUrl)
+            ? jobIdOrUrl
+            : `/jobs/${encodeURIComponent(jobIdOrUrl)}/events`;
+        const response = await this.request("GET", path, {
+            headers: { Accept: "text/event-stream" },
+            signal: options.signal,
+            timeoutMs: options.timeoutMs ?? null,
+        });
+        if (response.status !== 200) {
+            await this.parseOrRaise(response, [200]);
+            return;
+        }
+        if (!response.body)
+            return;
+        yield* iterateSse(response.body);
+    }
+    /** `POST /api/v2/jobs/{id}/cancel` — idempotent. */
+    async cancelJob(jobIdOrUrl, options = {}) {
+        const path = looksLikePath(jobIdOrUrl)
+            ? jobIdOrUrl
+            : `/jobs/${encodeURIComponent(jobIdOrUrl)}/cancel`;
+        const response = await this.request("POST", path, { signal: options.signal });
+        return this.parseOrRaise(response, [200]);
+    }
+}
+// The exact set of operationIds the transport must cover; the spec-coverage
+// test asserts this equals the set of operationIds in spec/openapi.yaml.
+export const OPERATION_IDS = [
+    "postAssets",
+    "assetFromHash",
+    "headAssetByHash",
+    "getAsset",
+    "getAssetContent",
+    "postJobs",
+    "getJob",
+    "getJobEvents",
+    "cancelJob",
+];
+// operationId -> transport method name.
+export const OPERATION_METHODS = {
+    postAssets: "postAssets",
+    assetFromHash: "assetFromHash",
+    headAssetByHash: "headAssetByHash",
+    getAsset: "getAsset",
+    getAssetContent: "getAssetContent",
+    postJobs: "postJobs",
+    getJob: "getJob",
+    getJobEvents: "getJobEvents",
+    cancelJob: "cancelJob",
+};

package/dist/sdk/abortable-sleep.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `setTimeout`-based sleep that rejects immediately when `signal` aborts,
+ * instead of only resolving after the full delay.
+ *
+ * Every internal wait the `sdk` layer schedules on the caller's behalf — the
+ * adaptive poll backoff in `Job.wait`, the reconnect pause in `Job.events`,
+ * the queue-full retry pause in `Comfy.submit` — uses this instead of a
+ * plain sleep. Without it, an aborted `AbortSignal` would only cancel the
+ * *current* fetch; the loop would still wake up on its own timer and start
+ * another iteration. Composing the signal into the wait itself is what
+ * makes an abort actually stop the loop promptly.
+ */
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/sdk/abortable-sleep.js

@@ -0,0 +1,31 @@
+/**
+ * `setTimeout`-based sleep that rejects immediately when `signal` aborts,
+ * instead of only resolving after the full delay.
+ *
+ * Every internal wait the `sdk` layer schedules on the caller's behalf — the
+ * adaptive poll backoff in `Job.wait`, the reconnect pause in `Job.events`,
+ * the queue-full retry pause in `Comfy.submit` — uses this instead of a
+ * plain sleep. Without it, an aborted `AbortSignal` would only cancel the
+ * *current* fetch; the loop would still wake up on its own timer and start
+ * another iteration. Composing the signal into the wait itself is what
+ * makes an abort actually stop the loop promptly.
+ */
+export function abortableSleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(abortReason(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortReason(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("This operation was aborted", "AbortError");
+}

package/dist/sdk/assets.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 type { Asset as LowAsset, ComfyLow } from "../low/index.js";
+import { ASSET_HANDLE } from "./core.js";
+type Hasher = () => Promise<string>;
+type Opener = () => Promise<Blob>;
+interface Source {
+    contentType: string;
+    filePath: string;
+    hasher: Hasher;
+    opener: Opener;
+}
+export declare class Asset {
+    readonly [ASSET_HANDLE]: true;
+    private readonly low;
+    private readonly source;
+    private readonly idempotencyKey;
+    private hashValue?;
+    private idValue?;
+    private createdNewValue;
+    constructor(low: ComfyLow, source: Source);
+    get id(): string | undefined;
+    get filePath(): string;
+    get createdNew(): boolean | null;
+    /** The local blake3 (computed once, lazily). */
+    hash(): Promise<string>;
+    /**
+     * 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: LowAsset): void;
+    /** Force the hash/dedup/upload now; return the asset UUID. */
+    commit(signal?: AbortSignal): Promise<string>;
+    /** The `core/ASSET` object (commits first if needed). */
+    asReference(signal?: AbortSignal): Promise<import("../low/models.js").AssetReference>;
+}
+/** `client.assets` — alternative constructors for {@link Asset}. */
+export declare class AssetFactory {
+    private readonly low;
+    constructor(low: ComfyLow);
+    fromFile(path: string): Asset;
+    fromBytes(data: Uint8Array, options?: {
+        filename?: string;
+        contentType?: string;
+    }): Asset;
+    /**
+     * 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.
+     */
+    fromStream(stream: ReadableStream<Uint8Array> | NodeJS.ReadableStream, options?: {
+        filename?: string;
+        contentType?: string;
+    }): Promise<Asset>;
+    /** Client-side download (not a server-side fetch): the bytes must
+     * transit the same blake3 -> dedup -> upload pipeline as every other
+     * source. */
+    fromUrl(url: string): Promise<Asset>;
+    /** Rehydrate an already-committed asset by UUID. */
+    get(assetId: string): Promise<Asset>;
+}
+export {};