[PR #52] [MERGED] docs: document fromJson/fromString and kind-typed (audio) outputs #61

New issue

Closed

opened 2026-10-31 22:04:14 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 22:04:14 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/52
Author: @mattmillerai
Created: 8/13/2026
Status: ✅ Merged
Merged: 8/22/2026
Merged by: @mattmillerai

Base: main ← Head: matt/be-7454-readme-programmatic-graph-outputs

📝 Commits (1)

26ac63d docs: document fromJson/fromString and kind-typed (audio) outputs

📊 Changes

1 file changed (+69 additions, -0 deletions)

View changed files

📝 README.md (+69 -0)

📄 Description

ELI-5

The README only ever showed one way to build a workflow (read a workflow_api.json off disk) and only ever showed image outputs. The SDK has done more than that for a while: client.workflows also takes a graph you built in code or a JSON string you already hold, and every job output carries a kind — image, video, audio, text, file or latent. This adds both to the README so you do not have to read the SDK source to find them.

What changed

Docs only — one file, README.md, no source or behavior touched.

New "Building a workflow" section (right after Quickstart): a table of the three constructors — await client.workflows.fromFile(path), client.workflows.fromJson(graph), client.workflows.fromString(text) — plus a worked example that builds an API-format graph in code, calls setInput on it, and runs it. It also states the two things that bite first: fromJson uses the object as-is rather than copying it, and none of the three validates the graph (a UI-format export is caught at submit time with WorkflowFormatUi, before any request goes out).
"Downloading outputs" now documents the kind discriminator: out.type is "image" | "video" | "audio" | "text" | "file" | "latent", alongside out.contentType, with a non-image example — reading a SaveAudioMP3 node's output to disk, and handing getDownloadUrl() straight to a browser <audio> element so the bytes never pass through the caller's process.

The union documented is the full six-member OutputType from the spec, not a four-member subset.

Verification

pnpm format:check, pnpm lint, pnpm typecheck, pnpm test — all green (169 tests, 16 files).
Every TS example added here was compiled, not eyeballed. Both new snippets were extracted verbatim into a scratch .mts file and typechecked under --strict twice: once against this branch's src/, and once against the published @comfyorg/sdk@0.1.7 installed from npm in a clean scratch project. Both exit 0. The track.type === "audio" narrowing and every property accessed (type, contentType, toFile, getDownloadUrl, workflows.fromJson/fromString/fromFile, wf.json) resolve against the published types. OutputType in the published dist/low/generated/types.gen.d.ts is byte-identical to the one in this tree, so the union printed in the README is accurate for anyone on the current release.
API names and signatures were taken from src/sdk/workflows.ts and src/sdk/outputs.ts rather than invented. One correction worth flagging: the discriminator is the type accessor on Output — kind is the SSE event discriminator (event.kind), a different thing — so the README says out.type.
The self-authorizing claim is scoped: the new prose says the URL can go straight into an <audio>/<video> element on Cloud/serverless, and that on a self-hosted proxy it is the content URL with normal auth still applying. An unqualified version of that sentence would have contradicted the paragraph directly below it.

Notes / judgment calls

Overlapping in-flight work: draft PR #37 ("Update README", opened 2026-07-31) rewrites large parts of this same file. Its diff contains no fromJson/fromString and no audio/video coverage, so it does not cover this gap — but whichever of the two lands second will need a rebase. Flagging rather than resolving, since #37 is someone else's draft.
The Quickstart and the hero snippet still use fromFile, deliberately: file-on-disk is the right first example, and the new section sits immediately below it.
One linked item in our internal tracker (the consumer-migration spec that surfaced these gaps) is not reachable from the environment this was written in, so it is unexercised here; it names no API, and everything documented was instead verified against this repo's source and the published package as above.

Docs-only, so there is nothing to feature-flag and no test to add beyond the compile checks above.

_{🔄 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/52 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 8/13/2026 **Status:** ✅ Merged **Merged:** 8/22/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/be-7454-readme-programmatic-graph-outputs` --- ### 📝 Commits (1) - [`26ac63d`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/26ac63d3e6102bbe54902e8e85ffa6a46efed833) docs: document fromJson/fromString and kind-typed (audio) outputs ### 📊 Changes **1 file changed** (+69 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+69 -0) </details> ### 📄 Description ## ELI-5 The README only ever showed one way to build a workflow (read a `workflow_api.json` off disk) and only ever showed image outputs. The SDK has done more than that for a while: `client.workflows` also takes a graph you built in code or a JSON string you already hold, and every job output carries a kind — image, video, audio, text, file or latent. This adds both to the README so you do not have to read the SDK source to find them. ## What changed Docs only — one file, `README.md`, no source or behavior touched. - **New "Building a workflow" section** (right after Quickstart): a table of the three constructors — `await client.workflows.fromFile(path)`, `client.workflows.fromJson(graph)`, `client.workflows.fromString(text)` — plus a worked example that builds an API-format graph in code, calls `setInput` on it, and `run`s it. It also states the two things that bite first: `fromJson` uses the object as-is rather than copying it, and none of the three validates the graph (a UI-format export is caught at submit time with `WorkflowFormatUi`, before any request goes out). - **"Downloading outputs" now documents the kind discriminator**: `out.type` is `"image" | "video" | "audio" | "text" | "file" | "latent"`, alongside `out.contentType`, with a non-image example — reading a `SaveAudioMP3` node's output to disk, and handing `getDownloadUrl()` straight to a browser `<audio>` element so the bytes never pass through the caller's process. The union documented is the full six-member `OutputType` from the spec, not a four-member subset. ## Verification - `pnpm format:check`, `pnpm lint`, `pnpm typecheck`, `pnpm test` — all green (169 tests, 16 files). - **Every TS example added here was compiled, not eyeballed.** Both new snippets were extracted verbatim into a scratch `.mts` file and typechecked under `--strict` twice: once against this branch's `src/`, and once against the **published `@comfyorg/sdk@0.1.7`** installed from npm in a clean scratch project. Both exit 0. The `track.type === "audio"` narrowing and every property accessed (`type`, `contentType`, `toFile`, `getDownloadUrl`, `workflows.fromJson`/`fromString`/`fromFile`, `wf.json`) resolve against the published types. `OutputType` in the published `dist/low/generated/types.gen.d.ts` is byte-identical to the one in this tree, so the union printed in the README is accurate for anyone on the current release. - API names and signatures were taken from `src/sdk/workflows.ts` and `src/sdk/outputs.ts` rather than invented. One correction worth flagging: the discriminator is the **`type`** accessor on `Output` — `kind` is the SSE *event* discriminator (`event.kind`), a different thing — so the README says `out.type`. - The self-authorizing claim is scoped: the new prose says the URL can go straight into an `<audio>`/`<video>` element **on Cloud/serverless**, and that on a self-hosted proxy it is the content URL with normal auth still applying. An unqualified version of that sentence would have contradicted the paragraph directly below it. ## Notes / judgment calls - **Overlapping in-flight work:** draft PR #37 ("Update README", opened 2026-07-31) rewrites large parts of this same file. Its diff contains no `fromJson`/`fromString` and no audio/video coverage, so it does not cover this gap — but whichever of the two lands second will need a rebase. Flagging rather than resolving, since #37 is someone else's draft. - The Quickstart and the hero snippet still use `fromFile`, deliberately: file-on-disk is the right first example, and the new section sits immediately below it. - One linked item in our internal tracker (the consumer-migration spec that surfaced these gaps) is not reachable from the environment this was written in, so it is unexercised here; it names no API, and everything documented was instead verified against this repo's source and the published package as above. Docs-only, so there is nothing to feature-flag and no test to add beyond the compile checks above. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 22:04:14 +00:00