@comfyorg/sdk 0.1.0

package/README.md

@@ -0,0 +1,236 @@
+# @comfyorg/sdk (TypeScript)
+
+TypeScript SDK for running ComfyUI workflows via the **Comfy API v2**. The
+same code runs against three surfaces — a self-hosted ComfyUI (through
+[`comfy-api-proxy`](https://github.com/Comfy-Org/comfy-api-proxy)), Comfy
+Cloud, or a serverless deployment — changing only the base URL and an
+optional API key. It mirrors the behavior of the
+[Python SDK](https://github.com/Comfy-Org/ComfyPythonSDK) (`comfy-sdk`):
+upload/dedup inputs, submit a workflow, wait for it, download the outputs —
+collapsed here to a single async client (no separate sync/async API;
+JavaScript is async-native).
+
+```ts
+import { Comfy } from "@comfyorg/sdk";
+
+const client = new Comfy("http://127.0.0.1:8189"); // local proxy, no key needed
+// const client = new Comfy("https://api.comfy.org", { apiKey: "..." }); // Comfy Cloud
+
+const wf = await client.workflows.fromFile("workflow_api.json");
+const asset = client.assets.fromFile("photo.png"); // lazy; hashed + uploaded on first use
+wf.setInput("10", "image", asset);
+
+const job = await client.run(wf); // submit, then poll to a terminal state
+await job.getOutputs("13")[0].toFile("out.png");
+```
+
+## Requirements
+
+- **Node >=22.** Node 20 reached end-of-life; browser support is out of
+  scope for v1.
+- **Install:**
+
+  ```bash
+  npm i @comfyorg/sdk
+  pnpm add @comfyorg/sdk
+  yarn add @comfyorg/sdk
+  ```
+
+  Releases are published to npm from a GitHub Release (tag `vX.Y.Z`) by
+  [`.github/workflows/publish.yml`](.github/workflows/publish.yml). To build
+  from source instead (for local development, or to track an unreleased
+  commit), clone this repo, `pnpm install`, `pnpm build`, and reference the
+  built `dist/`.
+
+## 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_..." })` |
+
+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
+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.
+
+## Quickstart
+
+```ts
+import { Comfy } from "@comfyorg/sdk";
+
+const client = new Comfy("http://127.0.0.1:8189");
+
+const wf = await client.workflows.fromFile("workflow_api.json");
+const job = await client.run(wf); // submit + poll to a terminal state; throws on failure
+const outputs = job.getOutputs("13"); // outputs produced by node "13"
+await outputs[0].toFile("out.png");
+```
+
+`run()` submits and polls to completion in one call. If you want to act on
+the job in between (read `job.status`, stream progress, cancel it), use
+`submit()` and drive the job yourself:
+
+```ts
+const job = await client.submit(wf);
+await job.wait(); // poll to terminal (adaptive backoff); or call job.refresh() yourself
+console.log(job.status, job.outputs);
+```
+
+## Assets and `core/ASSET`
+
+`client.assets.fromFile(path)` / `client.assets.fromBytes(data, options)`
+return a **lazy** asset handle: nothing is hashed or uploaded until the
+handle is actually used. Embed the handle directly in a workflow input with
+`wf.setInput(...)`:
+
+```ts
+const asset = client.assets.fromFile("photo.png");
+wf.setInput("10", "image", asset);
+```
+
+On submit, the SDK walks the workflow graph, finds every embedded handle,
+and for each one: hashes the bytes locally (blake3, via
+[`hash-wasm`](https://www.npmjs.com/package/hash-wasm) — pure WebAssembly,
+no native addon), probes the server's dedup fast path, and only streams a
+full upload if the server does not already have those bytes. Each handle is
+then substituted in place with a `core/ASSET` reference
+(`{ __type: "core/ASSET", info: { id, hash, file_path } }`) before the
+workflow is sent. Re-running a script against unchanged files re-uploads
+nothing.
+
+`client.assets` also has `fromStream`, `fromUrl`, and `get(assetId)` (to
+rehydrate a handle for an asset that is already committed) for less common
+cases — see the type definitions for details.
+
+## Live progress
+
+`job.events()` is a typed, auto-reconnecting async iterator over the job's
+live event stream:
+
+```ts
+const job = await client.submit(wf);
+for await (const event of job.events()) {
+  switch (event.kind) {
+    case "progress":
+      console.log(event.value);
+      break;
+    case "outputReady":
+      await event.output.toFile(`${event.output.name}`);
+      break;
+    case "statusChange":
+      if (event.status === "succeeded") break;
+  }
+}
+```
+
+The stream carries no replay cursor, so a dropped connection is reconnected
+from "now," not replayed from the start. Polling stays the source of truth
+for whether the job is actually done: if the stream is throttled, drops
+permanently, or never even connects, `events()` falls back to polling
+`GET /jobs/{id}` to detect the terminal state, so consumers never hang
+waiting on a stream that isn't coming back. If you only care about the
+final result, `run()`/`job.wait()` (poll-only, no SSE) is simpler.
+
+## Cancellation and timeouts
+
+`submit`, `run`, `wait`, `events`, and `cancel` all accept an `AbortSignal`,
+which stops both the in-flight request _and_ any internal wait (the queue-full
+retry pause, the poll backoff, the SSE reconnect pause) — an abort takes
+effect immediately rather than only after the current network call returns:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 30_000); // give up after 30s
+
+const job = await client.submit(wf, { signal: controller.signal });
+await job.wait(undefined, controller.signal);
+```
+
+`run()` also takes a plain `timeoutMs` if you just want a deadline without
+managing an `AbortController` yourself:
+
+```ts
+await client.run(wf, { timeoutMs: 60_000 });
+```
+
+## Typed errors
+
+Protocol-level failures are raised as one exception class per error code, so
+you can catch what you actually expect instead of string-matching messages:
+
+- `Unauthorized`, `Forbidden`, `NotFound`
+- `InvalidWorkflow` (and `WorkflowFormatUi`, for submitting a UI-export
+  instead of an API-format graph)
+- `MissingAsset` — a `core/ASSET` reference the server couldn't resolve
+- `HashMismatch` — uploaded bytes didn't match the declared hash
+- `BlobNotFound`
+- `IdempotencyKeyReuse` — the `Idempotency-Key` was reused. `submit()` (and
+  `run()`) attach a fresh key to every call, so an accidental exact resend never
+  runs the workflow twice. Keys are single-use (reject-on-duplicate, no replay),
+  so reusing your own explicit `idempotencyKey` throws this. After an ambiguous
+  failure, poll or list your jobs instead of resubmitting with the same key.
+- `InsufficientCredits`
+- `QueueFull` (carries `retryAfter`; `submit()` already retries this one
+  transparently)
+- `JobFailed` — a job reached a non-`succeeded` terminal state (carries the
+  node-level `error` detail when the platform provided one)
+
+All extend a shared `ComfyError` (`code`, `httpStatus`, `details`).
+
+```ts
+import { JobFailed, MissingAsset } from "@comfyorg/sdk";
+
+try {
+  await client.run(wf);
+} catch (err) {
+  if (err instanceof JobFailed) {
+    console.error(err.error); // { code, message, node_id, class_type, traceback } | null
+  } else if (err instanceof MissingAsset) {
+    console.error("asset reference was not usable:", err.details);
+  } else {
+    throw err;
+  }
+}
+```
+
+## Two layers
+
+- **`@comfyorg/sdk`** — the idiomatic client above: asset dedup/upload,
+  `core/ASSET` substitution, idempotent submit with queue-full backoff,
+  poll-authoritative job completion, typed SSE events, range-aware
+  downloads, and typed errors.
+- **`@comfyorg/sdk/low`** — generated types + [Zod](https://zod.dev) schemas
+  plus a hand-written `fetch` transport (`ComfyLow`) with one method per API
+  operation and the escape hatches the SDK layer is built on: raw `Response`
+  access, unbuffered streaming bodies (for SSE and range downloads), a
+  streaming multipart upload body, and per-request `AbortSignal`/timeout.
+  Use this directly if you need lower-level control.
+
+The generated part of `low` (`src/low/generated/*`) is produced by
+[`@hey-api/openapi-ts`](https://heyapi.dev) from `spec/openapi.yaml`, a
+vendored, filtered copy of the canonical Comfy API v2 contract (see
+`spec/README.md`). Regenerate it with `pnpm generate` after the spec
+changes; CI fails if the generated code has drifted from the spec.
+
+## Development
+
+```bash
+pnpm install --frozen-lockfile
+pnpm lint             # oxlint
+pnpm format:check     # oxfmt --check
+pnpm typecheck        # tsc --noEmit
+pnpm test             # vitest run
+pnpm build            # tsc -> dist/
+```
+
+Other useful scripts:
+
+```bash
+pnpm generate         # regenerate src/low/generated/* from spec/openapi.yaml
+pnpm format           # oxfmt --write
+pnpm test:coverage    # vitest run --coverage
+pnpm check:spec-drift # fails if src/low/generated/* is stale vs. the spec
+```

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Comfy SDK — the idiomatic TypeScript client for the Comfy API v2.
+ *
+ * Runs an API-format workflow against any Comfy API v2 surface (self-hosted
+ * ComfyUI through `comfy-api-proxy`, Comfy Cloud, or a serverless
+ * deployment) — the only per-surface difference is the base URL and an
+ * optional key. This is the `sdk` (idiomatic) layer; the generated
+ * types/validators + thin transport live under `@comfyorg/sdk/low` for
+ * advanced/escape-hatch use. Behaviorally mirrors the Python SDK
+ * (`Comfy-Org/ComfyPythonSDK`), collapsed to one async client (JS is
+ * async-native — no sync/async split).
+ *
+ * ```ts
+ * import { Comfy } from "@comfyorg/sdk";
+ *
+ * const client = new Comfy("http://127.0.0.1:8189"); // local proxy
+ * // const client = new Comfy("https://api.comfy.org", { apiKey: "..." }) // Comfy Cloud
+ *
+ * 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);
+ * await job.getOutputs("13")[0].toFile("out.png");
+ * ```
+ */
+export * from "./sdk/index.js";

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * Comfy SDK — the idiomatic TypeScript client for the Comfy API v2.
+ *
+ * Runs an API-format workflow against any Comfy API v2 surface (self-hosted
+ * ComfyUI through `comfy-api-proxy`, Comfy Cloud, or a serverless
+ * deployment) — the only per-surface difference is the base URL and an
+ * optional key. This is the `sdk` (idiomatic) layer; the generated
+ * types/validators + thin transport live under `@comfyorg/sdk/low` for
+ * advanced/escape-hatch use. Behaviorally mirrors the Python SDK
+ * (`Comfy-Org/ComfyPythonSDK`), collapsed to one async client (JS is
+ * async-native — no sync/async split).
+ *
+ * ```ts
+ * import { Comfy } from "@comfyorg/sdk";
+ *
+ * const client = new Comfy("http://127.0.0.1:8189"); // local proxy
+ * // const client = new Comfy("https://api.comfy.org", { apiKey: "..." }) // Comfy Cloud
+ *
+ * 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);
+ * await job.getOutputs("13")[0].toFile("out.png");
+ * ```
+ */
+export * from "./sdk/index.js";

package/dist/low/errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The shared error envelope mapped to a typed exception per `code`.
+ *
+ * This is the `low` (protocol) view of errors: one class per documented error
+ * `code`, plus a fallback. The `sdk` layer re-raises these as its own
+ * idiomatic exceptions where it adds value (e.g. `JobFailed` carrying node
+ * details), but the protocol codes are defined here so the generated layer
+ * has a stable, typed error surface. Mirrors `comfy_low.errors` in the
+ * Python SDK.
+ */
+export interface ApiErrorOptions {
+    code?: string;
+    httpStatus: number;
+    details?: Record<string, unknown> | null;
+    retryAfter?: number | null;
+}
+export declare class ApiError extends Error {
+    static readonly code: string;
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly details: Record<string, unknown> | null;
+    readonly retryAfter: number | null;
+    constructor(message: string, options: ApiErrorOptions);
+}
+export declare class InvalidWorkflow extends ApiError {
+    static readonly code = "invalid_workflow";
+}
+export declare class WorkflowFormatUi extends ApiError {
+    static readonly code = "workflow_format_ui";
+}
+export declare class MissingAsset extends ApiError {
+    static readonly code = "missing_asset";
+}
+export declare class HashMismatch extends ApiError {
+    static readonly code = "hash_mismatch";
+}
+export declare class BlobNotFound extends ApiError {
+    static readonly code = "blob_not_found";
+}
+export declare class IdempotencyKeyReuse extends ApiError {
+    static readonly code = "idempotency_key_reuse";
+}
+export declare class QueueFull extends ApiError {
+    static readonly code = "queue_full";
+}
+export declare class InsufficientCredits extends ApiError {
+    static readonly code = "insufficient_credits";
+}
+export declare class NotFound extends ApiError {
+    static readonly code = "not_found";
+}
+export declare class Unauthorized extends ApiError {
+    static readonly code = "unauthorized";
+}
+export declare class Forbidden extends ApiError {
+    static readonly code = "forbidden";
+}
+interface ErrorEnvelopeBody {
+    error?: {
+        code?: string;
+        message?: string;
+        details?: Record<string, unknown> | null;
+    };
+}
+/**
+ * Build the typed exception for an error response. Falls back to a
+ * status-derived code when the body is missing or not a well-formed
+ * envelope, so a bare 401 with no JSON still maps to `Unauthorized`.
+ */
+export declare function errorFromEnvelope(httpStatus: number, body: ErrorEnvelopeBody | null | undefined, options?: {
+    retryAfter?: number | null;
+}): ApiError;
+export {};

package/dist/low/errors.js

@@ -0,0 +1,104 @@
+/**
+ * The shared error envelope mapped to a typed exception per `code`.
+ *
+ * This is the `low` (protocol) view of errors: one class per documented error
+ * `code`, plus a fallback. The `sdk` layer re-raises these as its own
+ * idiomatic exceptions where it adds value (e.g. `JobFailed` carrying node
+ * details), but the protocol codes are defined here so the generated layer
+ * has a stable, typed error surface. Mirrors `comfy_low.errors` in the
+ * Python SDK.
+ */
+export class ApiError extends Error {
+    static code = "error";
+    code;
+    httpStatus;
+    details;
+    retryAfter;
+    constructor(message, options) {
+        super(message);
+        this.name = new.target.name;
+        this.code = options.code ?? new.target.code;
+        this.httpStatus = options.httpStatus;
+        this.details = options.details ?? null;
+        this.retryAfter = options.retryAfter ?? null;
+    }
+}
+export class InvalidWorkflow extends ApiError {
+    static code = "invalid_workflow";
+}
+export class WorkflowFormatUi extends ApiError {
+    static code = "workflow_format_ui";
+}
+export class MissingAsset extends ApiError {
+    static code = "missing_asset";
+}
+export class HashMismatch extends ApiError {
+    static code = "hash_mismatch";
+}
+export class BlobNotFound extends ApiError {
+    static code = "blob_not_found";
+}
+export class IdempotencyKeyReuse extends ApiError {
+    static code = "idempotency_key_reuse";
+}
+export class QueueFull extends ApiError {
+    static code = "queue_full";
+}
+export class InsufficientCredits extends ApiError {
+    static code = "insufficient_credits";
+}
+export class NotFound extends ApiError {
+    static code = "not_found";
+}
+export class Unauthorized extends ApiError {
+    static code = "unauthorized";
+}
+export class Forbidden extends ApiError {
+    static code = "forbidden";
+}
+const BY_CODE = {
+    invalid_workflow: InvalidWorkflow,
+    workflow_format_ui: WorkflowFormatUi,
+    missing_asset: MissingAsset,
+    hash_mismatch: HashMismatch,
+    blob_not_found: BlobNotFound,
+    idempotency_key_reuse: IdempotencyKeyReuse,
+    queue_full: QueueFull,
+    insufficient_credits: InsufficientCredits,
+    not_found: NotFound,
+    unauthorized: Unauthorized,
+    forbidden: Forbidden,
+};
+const CODE_BY_STATUS = {
+    401: "unauthorized",
+    402: "insufficient_credits",
+    403: "forbidden",
+    404: "not_found",
+    409: "hash_mismatch",
+    422: "invalid_workflow",
+    429: "queue_full",
+};
+/**
+ * Build the typed exception for an error response. Falls back to a
+ * status-derived code when the body is missing or not a well-formed
+ * envelope, so a bare 401 with no JSON still maps to `Unauthorized`.
+ */
+export function errorFromEnvelope(httpStatus, body, options = {}) {
+    const err = body && typeof body === "object" ? body.error : undefined;
+    let code = err && typeof err === "object" ? err.code : undefined;
+    let message = err && typeof err === "object" ? err.message : undefined;
+    const details = err && typeof err === "object" ? err.details : undefined;
+    if (!code) {
+        code = CODE_BY_STATUS[httpStatus] ?? "error";
+    }
+    if (!message) {
+        message = `HTTP ${httpStatus}`;
+    }
+    const cls = BY_CODE[code] ?? ApiError;
+    return new cls(message, {
+        code,
+        httpStatus,
+        details: details && typeof details === "object" ? details : null,
+        retryAfter: options.retryAfter ?? null,
+    });
+}

package/dist/low/generated/index.d.ts

@@ -0,0 +1 @@
+export type { Asset, AssetFromHashData, AssetFromHashError, AssetFromHashErrors, AssetFromHashResponse, AssetFromHashResponses, AssetId, BlakeHash, CancelJobData, CancelJobError, CancelJobErrors, CancelJobResponse, CancelJobResponses, ClientOptions, ErrorEnvelope, GetAssetContentData, GetAssetContentError, GetAssetContentErrors, GetAssetContentResponse, GetAssetContentResponses, GetAssetData, GetAssetError, GetAssetErrors, GetAssetResponse, GetAssetResponses, GetJobData, GetJobError, GetJobErrors, GetJobEventsData, GetJobEventsError, GetJobEventsErrors, GetJobEventsResponse, GetJobEventsResponses, GetJobResponse, GetJobResponses, HeadAssetByHashData, HeadAssetByHashError, HeadAssetByHashErrors, HeadAssetByHashResponses, IdempotencyKey, Job, JobError, JobId, JobStatus, JobUrls, Output, OutputType, PostAssetsData, PostAssetsError, PostAssetsErrors, PostAssetsResponse, PostAssetsResponses, PostJobsData, PostJobsError, PostJobsErrors, PostJobsResponse, PostJobsResponses, Progress } from './types.gen.js';

package/dist/low/generated/index.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};