@comfyorg/sdk 0.1.1 → 0.1.3

package/README.md

@@ -44,11 +44,11 @@ await job.getOutputs("13")[0].toFile("out.png");
 
 ## Auth, per surface
 
-| Surface                                                            | Auth                                       |
-| ------------------------------------------------------------------ | ------------------------------------------ |
-| Self-hosted proxy (`comfy-api-proxy` in front of your own ComfyUI) | none — do **not** pass `apiKey`            |
-| Comfy Cloud                                                        | `new Comfy(baseUrl, { apiKey: "ck_..." })` |
-| Serverless                                                         | `new Comfy(baseUrl, { apiKey: "ck_..." })` |
+| Surface                                                            | Auth                                            |
+| ------------------------------------------------------------------ | ----------------------------------------------- |
+| Self-hosted proxy (`comfy-api-proxy` in front of your own ComfyUI) | none — do **not** pass `apiKey`                 |
+| Comfy Cloud                                                        | `new Comfy(baseUrl, { apiKey: "comfyui-..." })` |
+| Serverless                                                         | `new Comfy(baseUrl, { apiKey: "comfyui-..." })` |
 
 The client only attaches the `Authorization` header to requests aimed at its
 own `baseUrl`'s origin. If the server hands back an absolute URL on a
@@ -56,6 +56,11 @@ different host (for example a job's `events`/`cancel` link, or a redirect on
 an asset download), the key is not sent there — see "Typed errors" below for
 the exception classes this surface can raise.
 
+The SDK identifies itself via `User-Agent` (for support + usage analytics);
+no other data is collected. Pass `clientInfo` to `new Comfy(baseUrl, { ... })`
+to append your own app's name to it, for example when attributing traffic
+from a Worker built on top of this SDK.
+
 ## Quickstart
 
 ```ts
@@ -173,6 +178,32 @@ managing an `AbortController` yourself:
 await client.run(wf, { timeoutMs: 60_000 });
 ```
 
+## Downloading outputs
+
+A finished job exposes its results as output handles — `job.outputs`, or
+`job.getOutputs(nodeId)` to filter to one node. Each is an asset you can pull
+down whichever way suits the caller:
+
+```ts
+const out = job.getOutputs("13")[0];
+await out.toFile("result.png"); // stream to disk
+const data = await out.toBytes(); // buffer into memory
+await out.toFile("head.png", { range: [0, 1023] }); // range-aware: first 1 KiB only
+```
+
+`getDownloadUrl()` hands back a fetchable URL instead of streaming the bytes
+through your process — give it to a browser, a CDN, or another service:
+
+```ts
+const { url, expiresAt } = await out.getDownloadUrl();
+```
+
+On Comfy Cloud / serverless it's a short-lived, **self-authorizing** signed
+storage URL: whoever holds it can read the asset until `expiresAt` with no API
+key of their own. On a self-hosted proxy it's the content endpoint (normal auth
+still applies) and `expiresAt` is `null`. It works on every backend and never
+downloads the bytes first.
+
 ## Typed errors
 
 Protocol-level failures are raised as one exception class per error code, so

package/dist/low/errors.js

@@ -66,6 +66,11 @@ const BY_CODE = {
     queue_full: QueueFull,
     insufficient_credits: InsufficientCredits,
     not_found: NotFound,
+    // public-api currently returns entity-specific 404 codes even though the spec
+    // documents the generic `not_found`; map them so callers still get a typed
+    // NotFound. (Server/spec reconciliation is a separate follow-up.)
+    job_not_found: NotFound,
+    asset_not_found: NotFound,
     unauthorized: Unauthorized,
     forbidden: Forbidden,
 };

package/dist/low/generated/types.gen.d.ts

@@ -372,7 +372,7 @@ export type PostJobsData = {
             [key: string]: unknown;
         };
         /**
-         * Optional typed extras submitted alongside the workflow. Closed: only the enumerated properties are accepted.
+         * Per-prompt ComfyUI `extra_data`, same shape as Comfy Cloud and local ComfyUI. Closed object: only the enumerated keys are accepted, keeping the contract fully typed. Forwarded to the worker per-prompt, never persisted, and excluded from idempotency comparison.
          */
         extra_data?: {
             /**
@@ -446,6 +446,10 @@ export type GetJobErrors = {
      * `not_found`.
      */
     404: ErrorEnvelope;
+    /**
+     * `rate_limited` — the caller has exceeded the request rate limit for this account. Account/rate-scoped, not job-specific — this can be returned even for a job id the caller doesn't own or that doesn't exist, without revealing which.
+     */
+    429: ErrorEnvelope;
     /**
      * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
      */
@@ -522,6 +526,10 @@ export type CancelJobErrors = {
      * `not_found`.
      */
     404: ErrorEnvelope;
+    /**
+     * `rate_limited` — the caller has exceeded the request rate limit for this account. Account/rate-scoped, not job-specific — this can be returned even for a job id the caller doesn't own or that doesn't exist, without revealing which.
+     */
+    429: ErrorEnvelope;
     /**
      * `upstream_error` — an unexpected failure reaching or processing the request in this implementation's backing services. The message is always a generic, safe-to-display string; implementation detail (the specific upstream, its error text, transport failures) is never included here — see each implementation's own error-mapping notes. Every operation in this contract can fail this way.
      */

package/dist/low/index.d.ts

@@ -18,4 +18,4 @@ export * as schemas from "./generated/zod.gen.js";
 export * from "./models.js";
 export * from "./errors.js";
 export { type RawEvent, iterateSse } from "./sse.js";
-export { ComfyLow, OPERATION_IDS, OPERATION_METHODS, type ComfyLowOptions, type RequestOptions, } from "./transport.js";
+export { ComfyLow, OPERATION_IDS, OPERATION_METHODS, type ComfyLowOptions, type RequestOptions, type AssetContentUrl, } from "./transport.js";

package/dist/low/sse.d.ts

@@ -14,11 +14,24 @@ export interface RawEvent {
     event: string;
     data: Record<string, unknown>;
 }
+/**
+ * Default read-idle timeout for the SSE byte stream. The server sends keepalive
+ * comments well within this window, so no *bytes at all* for this long means a
+ * silently-stalled ("zombie") connection — open but delivering nothing, not
+ * legitimately idle. We error the stream in that case so the caller's
+ * reconnect/poll fallback runs (see `Job.events`) instead of hanging forever.
+ * The timeout is at the byte level, not the parsed-message level, so keepalive
+ * comments (which `eventsource-parser` drops) still count as liveness.
+ */
+export declare const SSE_IDLE_TIMEOUT_MS = 45000;
 /**
  * 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.
+ * the Python decoder. A read-idle timeout (default {@link SSE_IDLE_TIMEOUT_MS})
+ * errors a silently-stalled connection instead of blocking forever.
  */
-export declare function iterateSse(body: ReadableStream<Uint8Array>): AsyncGenerator<RawEvent, void, void>;
+export declare function iterateSse(body: ReadableStream<Uint8Array>, options?: {
+    idleTimeoutMs?: number;
+}): AsyncGenerator<RawEvent, void, void>;

package/dist/low/sse.js

@@ -24,15 +24,48 @@ function parseData(raw) {
     }
     return { value: parsed };
 }
+/**
+ * Default read-idle timeout for the SSE byte stream. The server sends keepalive
+ * comments well within this window, so no *bytes at all* for this long means a
+ * silently-stalled ("zombie") connection — open but delivering nothing, not
+ * legitimately idle. We error the stream in that case so the caller's
+ * reconnect/poll fallback runs (see `Job.events`) instead of hanging forever.
+ * The timeout is at the byte level, not the parsed-message level, so keepalive
+ * comments (which `eventsource-parser` drops) still count as liveness.
+ */
+export const SSE_IDLE_TIMEOUT_MS = 45_000;
+/** A pass-through stream that errors if no chunk arrives within `ms`. */
+function idleTimeout(ms) {
+    let timer;
+    const clear = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    };
+    const arm = (controller) => {
+        clear();
+        timer = setTimeout(() => controller.error(new Error(`SSE idle timeout: no data for ${ms}ms`)), ms);
+    };
+    return new TransformStream({
+        start: arm,
+        transform(chunk, controller) {
+            arm(controller);
+            controller.enqueue(chunk);
+        },
+        flush: clear,
+        cancel: clear,
+    });
+}
 /**
  * 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.
+ * the Python decoder. A read-idle timeout (default {@link SSE_IDLE_TIMEOUT_MS})
+ * errors a silently-stalled connection instead of blocking forever.
  */
-export async function* iterateSse(body) {
+export async function* iterateSse(body, options = {}) {
     const stream = body
+        .pipeThrough(idleTimeout(options.idleTimeoutMs ?? SSE_IDLE_TIMEOUT_MS))
         .pipeThrough(new TextDecoderStream())
         .pipeThrough(new EventSourceParserStream());
     for await (const message of stream) {

package/dist/low/transport.d.ts

@@ -38,10 +38,24 @@ export interface RequestOptions {
      * must not time out while idle mid-job).
      */
     timeoutMs?: number | null;
+    /** Defaults to `"follow"`; `getAssetContentUrl` passes `"manual"` so it can
+     * read a redirect's `Location` instead of following it. */
+    redirect?: "follow" | "manual" | "error";
 }
 export interface ComfyLowOptions {
     fetch?: typeof fetch;
     timeoutMs?: number;
+    /**
+     * Appended to the default `User-Agent` as `app/{clientInfo}` — lets an
+     * app built on this SDK attribute its own traffic in request logs.
+     * Opt-in; omitted by default.
+     */
+    clientInfo?: string;
+}
+/** Return shape of {@link ComfyLow.getAssetContentUrl}. */
+export interface AssetContentUrl {
+    url: string;
+    expiresAt: Date | null;
 }
 /** Synchronous protocol bindings — async throughout (JS is async-native). */
 export declare class ComfyLow {
@@ -49,6 +63,7 @@ export declare class ComfyLow {
     private readonly apiKey?;
     private readonly fetchImpl;
     private readonly defaultTimeoutMs;
+    private readonly userAgent;
     constructor(baseUrl: string, apiKey?: string, options?: ComfyLowOptions);
     private urlFor;
     /**
@@ -100,6 +115,23 @@ export declare class ComfyLow {
         range?: readonly [number, number];
         signal?: AbortSignal;
     }): Promise<Response>;
+    /**
+     * `GET /api/v2/assets/{id}/content` with the redirect **not** followed —
+     * hands back a directly-fetchable URL instead of the bytes, so a caller
+     * (e.g. a serverless/Cloudflare Worker) can pass the URL to a downstream
+     * consumer without streaming the body through itself. On an object-storage
+     * backend (Cloud/serverless) the server redirects to a short-lived signed
+     * URL; that redirect is deliberately not followed (unlike
+     * {@link getAssetContent}), both so its `Location` can be read and so this
+     * client's bearer token is never attached to the object-storage host. On a
+     * self-hosted proxy (which serves the bytes inline, no redirect) this
+     * returns the endpoint's own absolute URL instead. Works on every backend
+     * and never throws for either shape — only a genuine failure maps to the
+     * usual typed error.
+     */
+    getAssetContentUrl(assetId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AssetContentUrl>;
     /**
      * `POST /api/v2/jobs`. `extraData` (e.g. the partner-node API key) is a
      * sibling of `workflow` on the wire, per the spec's closed `extra_data`

package/dist/low/transport.js

@@ -27,11 +27,53 @@
  */
 import { errorFromEnvelope } from "./errors.js";
 import { iterateSse } from "./sse.js";
+import { SDK_VERSION } from "./version.js";
 const API_PREFIX = "/api/v2";
 const DEFAULT_TIMEOUT_MS = 30_000;
 function looksLikePath(value) {
     return value.startsWith("http") || value.startsWith("/");
 }
+function buildUserAgent(clientInfo) {
+    const base = `comfy-sdk-typescript/${SDK_VERSION} (node ${process.version})`;
+    if (!clientInfo)
+        return base;
+    // A caller-set token goes verbatim into a header value; reject CR/LF so it
+    // can never split/inject headers (undici would reject it anyway, but fail
+    // fast with a clear message at construction).
+    if (/[\r\n]/.test(clientInfo)) {
+        throw new Error("clientInfo must not contain CR or LF characters");
+    }
+    return `${base} app/${clientInfo}`;
+}
+const GOOG_DATE_RE = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
+/**
+ * Expiry off a GCS V4 signed URL's `X-Goog-Date` (`YYYYMMDDTHHMMSSZ`, UTC) +
+ * `X-Goog-Expires` (seconds) query params. `null` if either is missing or
+ * doesn't match — an unrecognized signed-URL flavor degrades to "unknown
+ * expiry" rather than throwing.
+ */
+function parseExpiry(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const dateParam = parsed.searchParams.get("X-Goog-Date");
+    const expiresParam = parsed.searchParams.get("X-Goog-Expires");
+    if (!dateParam || !expiresParam)
+        return null;
+    const match = GOOG_DATE_RE.exec(dateParam);
+    if (!match)
+        return null;
+    const expiresSeconds = Number.parseInt(expiresParam, 10);
+    if (Number.isNaN(expiresSeconds))
+        return null;
+    const [, year, month, day, hour, minute, second] = match;
+    const epochMs = Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second));
+    return new Date(epochMs + expiresSeconds * 1000);
+}
 function parseRetryAfter(response) {
     const raw = response.headers.get("Retry-After");
     if (raw === null)
@@ -45,17 +87,28 @@ export class ComfyLow {
     apiKey;
     fetchImpl;
     defaultTimeoutMs;
+    userAgent;
     constructor(baseUrl, apiKey, options = {}) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
         this.apiKey = apiKey;
         this.fetchImpl = options.fetch ?? fetch;
         this.defaultTimeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.userAgent = buildUserAgent(options.clientInfo);
     }
     urlFor(path) {
         if (path.startsWith("http"))
             return path;
-        if (path.startsWith("/api/"))
-            return this.baseUrl + path;
+        // A server link (job.urls.*, marked by containing /api/) already carries
+        // the server's mount prefix, so it resolves against the origin — joining
+        // it to baseUrl would double the prefix on a prefix-mounted surface.
+        if (path.startsWith("/") && path.includes("/api/")) {
+            try {
+                return new URL(this.baseUrl).origin + path;
+            }
+            catch {
+                return this.baseUrl + path;
+            }
+        }
         return this.baseUrl + API_PREFIX + path;
     }
     /**
@@ -90,6 +143,12 @@ export class ComfyLow {
                 headers.set(key, value);
             }
         }
+        // Identifies this SDK's traffic in request logs (support + adoption
+        // metrics, no other data collected) — never overrides a caller-supplied
+        // header.
+        if (!headers.has("User-Agent")) {
+            headers.set("User-Agent", this.userAgent);
+        }
         return headers;
     }
     resolveSignal(callerSignal, timeoutMs) {
@@ -113,7 +172,13 @@ export class ComfyLow {
             body = JSON.stringify(options.json);
         }
         const signal = this.resolveSignal(options.signal, options.timeoutMs);
-        return this.fetchImpl(url, { method, headers, body, signal, redirect: "follow" });
+        return this.fetchImpl(url, {
+            method,
+            headers,
+            body,
+            signal,
+            redirect: options.redirect ?? "follow",
+        });
     }
     async parseOrRaise(response, ok) {
         if (ok.includes(response.status)) {
@@ -137,8 +202,11 @@ export class ComfyLow {
     // -- assets -------------------------------------------------------------
     /** `POST /api/v2/assets` — streaming multipart upload. */
     async postAssets(file, contentType, filePath, options = {}) {
+        // public-api streams the multipart upload and requires the metadata fields
+        // BEFORE the file part (so it can route the file stream without buffering).
+        // The `file` part MUST be appended last, or the server rejects with 422
+        // "content_type is required and must be sent before the file field".
         const form = new FormData();
-        form.append("file", file, filePath);
         form.append("content_type", contentType);
         form.append("file_path", filePath);
         if (options.expectedHash !== undefined) {
@@ -147,6 +215,7 @@ export class ComfyLow {
         for (const tag of options.tags ?? []) {
             form.append("tags", tag);
         }
+        form.append("file", file, filePath);
         const headers = {};
         if (options.idempotencyKey) {
             headers["Idempotency-Key"] = options.idempotencyKey;
@@ -209,6 +278,41 @@ export class ComfyLow {
         }
         return response;
     }
+    /**
+     * `GET /api/v2/assets/{id}/content` with the redirect **not** followed —
+     * hands back a directly-fetchable URL instead of the bytes, so a caller
+     * (e.g. a serverless/Cloudflare Worker) can pass the URL to a downstream
+     * consumer without streaming the body through itself. On an object-storage
+     * backend (Cloud/serverless) the server redirects to a short-lived signed
+     * URL; that redirect is deliberately not followed (unlike
+     * {@link getAssetContent}), both so its `Location` can be read and so this
+     * client's bearer token is never attached to the object-storage host. On a
+     * self-hosted proxy (which serves the bytes inline, no redirect) this
+     * returns the endpoint's own absolute URL instead. Works on every backend
+     * and never throws for either shape — only a genuine failure maps to the
+     * usual typed error.
+     */
+    async getAssetContentUrl(assetId, options = {}) {
+        const path = `/assets/${encodeURIComponent(assetId)}/content`;
+        const response = await this.request("GET", path, {
+            signal: options.signal,
+            redirect: "manual",
+        });
+        const location = response.headers.get("Location");
+        // Node/undici hands back the real 3xx status with a readable `Location`
+        // for a manual redirect; status 0 covers a browser's opaque redirect.
+        // We only want the URL, not the bytes — release the response body so
+        // undici can reuse the connection instead of pinning it until GC.
+        if (location && (response.status === 0 || (response.status >= 300 && response.status < 400))) {
+            await response.body?.cancel();
+            return { url: location, expiresAt: parseExpiry(location) };
+        }
+        if (response.status === 200 || response.status === 206) {
+            await response.body?.cancel();
+            return { url: this.urlFor(path), expiresAt: null };
+        }
+        return this.parseOrRaise(response, [200, 206]); // always throws here
+    }
     // -- jobs -----------------------------------------------------------------
     /**
      * `POST /api/v2/jobs`. `extraData` (e.g. the partner-node API key) is a

package/dist/low/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.1.3";

package/dist/low/version.js

@@ -0,0 +1,2 @@
+// GENERATED by scripts/gen-version.mjs from package.json — do not edit.
+export const SDK_VERSION = "0.1.3";

package/dist/sdk/client.d.ts

@@ -37,6 +37,9 @@ export interface ComfyOptions {
     apiKey?: string;
     timeoutMs?: number;
     fetch?: ComfyLowOptions["fetch"];
+    /** Appended to the SDK's default `User-Agent` as `app/{clientInfo}` — lets
+     * an app built on this SDK attribute its own traffic in request logs. */
+    clientInfo?: string;
 }
 export declare class Comfy {
     private readonly low;

package/dist/sdk/client.js

@@ -52,6 +52,7 @@ export class Comfy {
         this.low = new ComfyLow(baseUrl, options.apiKey, {
             timeoutMs: options.timeoutMs,
             fetch: options.fetch,
+            clientInfo: options.clientInfo,
         });
         this.assets = new AssetFactory(this.low);
         this.workflows = new WorkflowFactory();

package/dist/sdk/exceptions.js

@@ -79,6 +79,11 @@ const BY_CODE = {
     idempotency_key_reuse: IdempotencyKeyReuse,
     insufficient_credits: InsufficientCredits,
     not_found: NotFound,
+    // public-api returns entity-specific 404 codes even though the spec documents
+    // the generic not_found; map them so a missing job/asset raises the typed
+    // NotFound. (Server/spec reconciliation of the code set is a separate follow-up.)
+    job_not_found: NotFound,
+    asset_not_found: NotFound,
     unauthorized: Unauthorized,
     forbidden: Forbidden,
 };

package/dist/sdk/outputs.d.ts

@@ -23,4 +23,18 @@ export declare class Output {
     toBytes(options?: {
         range?: readonly [number, number];
     }): Promise<Uint8Array>;
+    /**
+     * A directly-fetchable URL for this output's bytes — a short-lived,
+     * self-authorizing bearer credential (readable until `expiresAt`) — so a
+     * caller (e.g. a serverless/Cloudflare Worker) can hand the URL to a
+     * downstream consumer instead of streaming the bytes through itself. On an
+     * object-storage backend (Cloud/serverless) this is a signed URL and
+     * `expiresAt` is set; on a self-hosted proxy (which serves the bytes
+     * inline) it's this asset's own content URL and `expiresAt` is `null`.
+     * Works on every backend and never throws.
+     */
+    getDownloadUrl(): Promise<{
+        url: string;
+        expiresAt: Date | null;
+    }>;
 }

package/dist/sdk/outputs.js

@@ -45,4 +45,17 @@ export class Output {
         const response = await this.low.getAssetContent(this.model.id, { range: options.range });
         return new Uint8Array(await response.arrayBuffer());
     }
+    /**
+     * A directly-fetchable URL for this output's bytes — a short-lived,
+     * self-authorizing bearer credential (readable until `expiresAt`) — so a
+     * caller (e.g. a serverless/Cloudflare Worker) can hand the URL to a
+     * downstream consumer instead of streaming the bytes through itself. On an
+     * object-storage backend (Cloud/serverless) this is a signed URL and
+     * `expiresAt` is set; on a self-hosted proxy (which serves the bytes
+     * inline) it's this asset's own content URL and `expiresAt` is `null`.
+     * Works on every backend and never throws.
+     */
+    async getDownloadUrl() {
+        return this.low.getAssetContentUrl(this.model.id);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfyorg/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "description": "TypeScript SDK for running ComfyUI workflows via the Comfy API v2 (self-hosted, Comfy Cloud, serverless).",
   "homepage": "https://github.com/Comfy-Org/ComfyTypeScriptSDK#readme",
@@ -46,7 +46,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/gen-version.mjs && tsc",
     "generate": "openapi-ts",
     "lint": "oxlint .",
     "format": "oxfmt --write .",