[PR #3] [MERGED] @comfyorg/sdk (TypeScript): the Comfy API v2 client — two-layer SDK #12

New issue

Closed

opened 2026-10-31 22:03:50 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 22:03:50 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/3
Author: @wei-hai
Created: 7/16/2026
Status: ✅ Merged
Merged: 7/17/2026
Merged by: @wei-hai

Base: main ← Head: feat/full-v2

📝 Commits (8)

01ac0c7 Build the full two-layer Comfy API v2 SDK
6eaa69c Scrub internal references from the vendored spec
dca70f8 Fix must-fix review findings: bearer-token leak, missing abort support, untested auth
06fabd7 Expand README and close test gaps for the v2 SDK
88b6bd9 docs: correct submit() idempotency JSDoc
daada4d Sync to the current v2 contract: drop replay/409 idempotency, reject-on-duplicate
7208839 README: drop removed IdempotencyConflict; document single-use idempotency
1726984 ci: add public-repo hygiene guard + publish-readiness check

📊 Changes

45 files changed (+6122 additions, -81 deletions)

View changed files

📝 .github/workflows/ci.yml (+61 -0)
📝 .oxlintrc.json (+1 -1)
➕ .prettierignore (+6 -0)
📝 README.md (+220 -18)
➕ openapi-ts.config.ts (+42 -0)
📝 package.json (+18 -3)
📝 pnpm-lock.yaml (+596 -14)
➕ scripts/check-public-repo-hygiene.mjs (+164 -0)
➕ scripts/check-spec-drift.mjs (+63 -0)
➕ spec/README.md (+1 -0)
➕ spec/VERSION (+1 -0)
➕ spec/openapi.yaml (+944 -0)
📝 src/index.test.ts (+11 -6)
📝 src/index.ts (+23 -39)
➕ src/low/errors.test.ts (+60 -0)
➕ src/low/errors.ts (+144 -0)
➕ src/low/generated/index.ts (+3 -0)
➕ src/low/generated/types.gen.ts (+591 -0)
➕ src/low/generated/zod.gen.ts (+238 -0)
➕ src/low/index.ts (+28 -0)

...and 25 more files

📄 Description

What this is

The TypeScript SDK for running ComfyUI workflows via the Comfy API v2 — the same code against a self-hosted ComfyUI, Comfy Cloud, or a serverless deployment. Only the base URL and (where needed) an API key change. It mirrors the Python SDK's surface so the two behave identically.

import { Comfy } from "@comfyorg/sdk";

const client = new Comfy("http://127.0.0.1:8189");                  // local (self-hosted proxy)
// const client = new Comfy("https://api.comfy.org", { apiKey });  // Comfy Cloud

const asset = client.assets.fromFile("photo.png");                 // hashed + uploaded once, on use
wf.setInput("10", "image", asset);                                 // becomes a core/ASSET reference
const job = await client.run(wf);
await job.getOutputs("13")[0].toFile("out.png");

Two layers

flowchart TB
    subgraph sdk["sdk — hand-written, idiomatic (the value)"]
        assets["assets: fromFile/fromUrl/…<br/>blake3 dedup, lazy upload"]
        wf["workflows + core/ASSET substitution"]
        jobs["run() · wait() · events() (SSE)"]
        out["typed outputs, events, errors"]
    end
    subgraph low["low — generated + thin transport"]
        models["types + Zod (generated from the v2 spec)"]
        transport["fetch transport: 1 fn/endpoint,<br/>streaming, AbortSignal, raw Response"]
    end
    sdk --> low
    low -->|"/api/v2/*"| surface["any Comfy API v2 surface"]

low: types + Zod generated from the Comfy API v2 OpenAPI contract (spec/openapi.yaml, a synced copy), plus a hand-written fetch transport. The codegen tool's generated client was evaluated against the hard requirements (raw Response, unbuffered streaming, streaming upload body, per-request abort); since three of the nine operations (multipart upload, SSE, ranged download) must bypass a generated call-site to use those anyway, the transport is hand-written for all nine — matching the Python SDK's architecture. A drift check + spec-coverage test keep low in sync with the contract.
sdk: the idiomatic layer — content-addressed upload with blake3 (hash-wasm) dedup, core/ASSET substitution, poll-authoritative run()/wait(), a reconnecting typed SSE stream (eventsource-parser over the raw fetch body, since the EventSource global can't send headers or abort), range-aware downloads, and typed errors for every code.

Notes for reviewers

Async-only (JS is async-native — no sync/async split).
Multipart upload streams via fs.openAsBlob() (disk-backed, never buffered whole).
Poll is the source of truth; SSE is a reconnecting enhancement that never gates completion.
Node 20 / 22 / 24; browser support is out of scope for v1 (deferred).

Tests

76 tests across 11 files against a stub server, covering the same scenarios as the Python SDK: dedup fast-path, streaming upload, hash-mismatch without blind retry, poll-only completion, SSE reconnect without replay, idempotent submit, error→exception mapping, ranged download. CI green on Node 22 and 24.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/comfy-typescript-sdk/pull/3 **Author:** [@wei-hai](https://github.com/wei-hai) **Created:** 7/16/2026 **Status:** ✅ Merged **Merged:** 7/17/2026 **Merged by:** [@wei-hai](https://github.com/wei-hai) **Base:** `main` ← **Head:** `feat/full-v2` --- ### 📝 Commits (8) - [`01ac0c7`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/01ac0c79a92add8060d04ea0e591d672f7281968) Build the full two-layer Comfy API v2 SDK - [`6eaa69c`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/6eaa69c30fa90d7704dc1487f195e521d0924f2b) Scrub internal references from the vendored spec - [`dca70f8`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/dca70f88fa8fdf0cdd7eb58bef2e4f04de894349) Fix must-fix review findings: bearer-token leak, missing abort support, untested auth - [`06fabd7`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/06fabd700968e56721e2b0f6a20e16b03a8d3dc9) Expand README and close test gaps for the v2 SDK - [`88b6bd9`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/88b6bd92958e23568122c5533695baa8a671c56b) docs: correct submit() idempotency JSDoc - [`daada4d`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/daada4dba4aff496aed65916aaf1cbd3959c1007) Sync to the current v2 contract: drop replay/409 idempotency, reject-on-duplicate - [`7208839`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/7208839046463de06abe2b576703319bfcf9ec80) README: drop removed IdempotencyConflict; document single-use idempotency - [`1726984`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/1726984eda3f0804807476f1fe7f3bc780880269) ci: add public-repo hygiene guard + publish-readiness check ### 📊 Changes **45 files changed** (+6122 additions, -81 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/ci.yml` (+61 -0) 📝 `.oxlintrc.json` (+1 -1) ➕ `.prettierignore` (+6 -0) 📝 `README.md` (+220 -18) ➕ `openapi-ts.config.ts` (+42 -0) 📝 `package.json` (+18 -3) 📝 `pnpm-lock.yaml` (+596 -14) ➕ `scripts/check-public-repo-hygiene.mjs` (+164 -0) ➕ `scripts/check-spec-drift.mjs` (+63 -0) ➕ `spec/README.md` (+1 -0) ➕ `spec/VERSION` (+1 -0) ➕ `spec/openapi.yaml` (+944 -0) 📝 `src/index.test.ts` (+11 -6) 📝 `src/index.ts` (+23 -39) ➕ `src/low/errors.test.ts` (+60 -0) ➕ `src/low/errors.ts` (+144 -0) ➕ `src/low/generated/index.ts` (+3 -0) ➕ `src/low/generated/types.gen.ts` (+591 -0) ➕ `src/low/generated/zod.gen.ts` (+238 -0) ➕ `src/low/index.ts` (+28 -0) _...and 25 more files_ </details> ### 📄 Description ## What this is The TypeScript SDK for running ComfyUI workflows via the **Comfy API v2** — the same code against a self-hosted ComfyUI, Comfy Cloud, or a serverless deployment. Only the base URL and (where needed) an API key change. It mirrors the Python SDK's surface so the two behave identically. ```ts import { Comfy } from "@comfyorg/sdk"; const client = new Comfy("http://127.0.0.1:8189"); // local (self-hosted proxy) // const client = new Comfy("https://api.comfy.org", { apiKey }); // Comfy Cloud const asset = client.assets.fromFile("photo.png"); // hashed + uploaded once, on use wf.setInput("10", "image", asset); // becomes a core/ASSET reference const job = await client.run(wf); await job.getOutputs("13")[0].toFile("out.png"); ``` ## Two layers ```mermaid flowchart TB subgraph sdk["sdk — hand-written, idiomatic (the value)"] assets["assets: fromFile/fromUrl/…<br/>blake3 dedup, lazy upload"] wf["workflows + core/ASSET substitution"] jobs["run() · wait() · events() (SSE)"] out["typed outputs, events, errors"] end subgraph low["low — generated + thin transport"] models["types + Zod (generated from the v2 spec)"] transport["fetch transport: 1 fn/endpoint,<br/>streaming, AbortSignal, raw Response"] end sdk --> low low -->|"/api/v2/*"| surface["any Comfy API v2 surface"] ``` - **`low`**: types + Zod generated from the Comfy API v2 OpenAPI contract (`spec/openapi.yaml`, a synced copy), plus a hand-written `fetch` transport. The codegen tool's generated *client* was evaluated against the hard requirements (raw `Response`, unbuffered streaming, streaming upload body, per-request abort); since three of the nine operations (multipart upload, SSE, ranged download) must bypass a generated call-site to use those anyway, the transport is hand-written for all nine — matching the Python SDK's architecture. A drift check + spec-coverage test keep `low` in sync with the contract. - **`sdk`**: the idiomatic layer — content-addressed upload with **blake3** (`hash-wasm`) dedup, `core/ASSET` substitution, poll-authoritative `run()`/`wait()`, a reconnecting typed SSE stream (`eventsource-parser` over the raw fetch body, since the `EventSource` global can't send headers or abort), range-aware downloads, and typed errors for every code. ## Notes for reviewers - **Async-only** (JS is async-native — no sync/async split). - Multipart upload streams via `fs.openAsBlob()` (disk-backed, never buffered whole). - **Poll is the source of truth**; SSE is a reconnecting enhancement that never gates completion. - Node 20 / 22 / 24; **browser support is out of scope for v1** (deferred). ## Tests 76 tests across 11 files against a stub server, covering the same scenarios as the Python SDK: dedup fast-path, streaming upload, hash-mismatch without blind retry, poll-only completion, SSE reconnect without replay, idempotent submit, error→exception mapping, ranged download. CI green on Node 22 and 24. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 22:03:50 +00:00