flux-2-pro #121

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/119
Author: @mattmillerai
Created: 9/3/2026
Status: ✅ Merged
Merged: 9/4/2026
Merged by: @mattmillerai

Base: main ← Head: matt/be-11088-bfl-flux-2-pro-example

📝 Commits (2)

0b53b76 docs: replace the non-existent fal-ai/flux-pro example with bfl/flux-2-pro
8b08bd4 docs: leave the vendored Router spec examples to the upstream sync

📊 Changes

4 files changed (+15 additions, -15 deletions)

View changed files

📝 README.md (+7 -7)
📝 src/sdk/models.test.ts (+5 -5)
📝 src/sdk/models.ts (+1 -1)
📝 src/sdk/router-spec-contract.test.ts (+2 -2)

📄 Description

ELI-5

Every "your first call" example in this SDK told you to run a model called fal-ai/flux-pro. There is no such model — so the very first thing a new reader copy-pastes could not work. This swaps it for bfl/flux-2-pro, which is real, enrolled, and the fastest path on the Router. Nothing about how the SDK behaves changes; only the example ID does.

What was wrong

The example was wrong twice over. flux-pro is not an enrolled Comfy Router model under any provider, and fal-ai is not a Comfy provider slug either — the fal provider's slug is fal, and fal-ai is an upstream path segment inside it. Flux is served direct from Black Forest Labs under bfl/*.

The string originates as an example: on the RouterModelId schema in the canonical Comfy API contract, so it propagated into the vendored Router spec here and, copied by hand, into the README prose and the comfy.models JSDoc.

What changed

README.md — all 7 occurrences (the quickstart call, the ID-format explanation, the typed-output example, the options example, the two retry examples, the abort-signal example).
src/sdk/models.ts — the JSDoc @example, which also renders in IDE hover and in generated typedoc, not only on GitHub.
Fixtures — src/sdk/models.test.ts (the shared MODEL constant, the asserted wire path, and the did-you-mean 404 pair, migrated as a matched set) and src/sdk/router-spec-contract.test.ts (the live-request fixture and its expected path, both sides moved together).

spec/router-openapi.yaml is deliberately NOT touched. An earlier revision of this branch patched its three example: values; that edit has been reverted. See Judgment calls.

Judgment calls

The vendored Router spec is left alone, and the fix belongs upstream. spec/router-openapi.yaml is a one-way vendored copy that AGENTS.md and spec/README.md both declare off-limits to hand edits — "in every case this file is the side that is right". An earlier revision of this branch patched the three example: values anyway, on the reasoning that nothing is generated from that file so the edit reddens nothing. That reasoning is what the rule exists to catch: because no check reads example:, the edit lands green and is silently undone by the next sync. Concretely, the pending sync branch chore/sync-router-spec-abdcb94 already carries fal-ai/flux-pro / flux-pro / fal-ai at those same three keys, so merging this branch and then that sync would put the vendored spec back out of step with the README and tests here — inside a routine sync diff, where the revert would not read as a regression to anyone reviewing it. The spec hunk is reverted; the upstream contract is the place to fix the string.

Nothing in this repo is generated from or compared against that file's example: values (scripts/check-spec-drift.mjs regenerates only against spec/openapi.yaml, and checks the Router route/host constants by comparison), so the two sides carrying different example strings reddens no check and misleads no reader — the reader-facing surfaces are the README and the JSDoc, and both are correct.

Two fixture corpora are deliberately left on fal-ai/..., because a real ID would defeat exactly what they test. The malformed-ID rejection list in models.test.ts ("flux-pro", "", "fal-ai/", "/flux-pro", "fal-ai/flux/pro", "./flux-pro", "fal-ai/..") exists to prove the parser refuses bad input without opening a socket. The percent-encoding fixture "fal ai/flux#pro" in router-spec-contract.test.ts exists to prove a space and a # are encoded rather than allowed to add a path segment. Both are hostile-input tests, not examples.

bfl/flux-2-pro/v1.1 in the "extra segment is a variant" test was migrated rather than left, since its point is the third segment, not the base ID — and a real base ID now makes the case read more clearly.

Verification of the replacement ID

bfl/flux-2-pro was not taken on trust from the report. Confirmed on the default branch of the server's own (private) source of truth, read read-only: it appears in the Router model enrolment table alongside the other bfl Flux routes, it has an authored per-model schema file, and the Router quickstart there already uses it as its canonical ID with provider: bfl / model: flux-2-pro. The same read confirms the negative: the fal section enrolls no Flux route at all.

bfl/flux-2-pro also passes this SDK's own parseModelId on the real code path — src/sdk/models.test.ts asserts the wire path is /v2/models/bfl/flux-2-pro from an actual call against the stub server, which is what proves the digit-bearing flux-2-pro segment is accepted rather than merely plausible.

Residual

The vendored spec still carries the bad example, and this PR no longer changes that. Correcting it is upstream work on the canonical contract, tracked separately and out of scope here. Until it lands, spec/router-openapi.yaml in this repo keeps fal-ai/flux-pro — a stale example in a file the repo's own rules point readers away from, rather than a hand-patch that a routine sync would quietly revert.
The live Router was not exercised for this ID. GET https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json returns 401 No Authorization header found unauthenticated, and the auth gate sits in front of model resolution — the identical 401 comes back for fal-ai/flux-pro — so the public endpoint cannot distinguish a real ID from a fictional one without a credential, and none was used here. The enrolment evidence above is source-of-truth rather than live-catalog.
One factual detail in the originating report is now slightly stale, in a direction that does not affect this change. It states the only enrolled fal ID is fal/patina; the enrolment table on the default branch today also carries minimax/h3-max routes under fal. Still no fal Flux route, so the replacement stands.
The originating user report itself was not readable from this environment — it was relayed second-hand, and its exact wording is unverified here. The defect was reproduced independently from the repository state rather than from that report.
Sibling repositories carrying the same example are untouched. The sweep that sized this fix found the string live in several repos; this PR fixes only this one. Within this repo the sweep is complete: 27 lines matched flux/fal, 15 were reader-facing or fixture uses and are fixed, 3 are the vendored spec's example: values now left to the upstream sync, 7 are the two hostile-input corpora named above and are intentionally left, and 2 are an unrelated FluxOutput type name in prose.

Provenance

Authored by: agent-work loop
Verified: pnpm test: 406 passed, 0 failed (23 files); node scripts/check-spec-drift.mjs: both checks OK (generated code in sync, Router route matches); pnpm typecheck, pnpm lint, pnpm format:check: clean; node scripts/check-public-repo-hygiene.mjs: OK, no internal-only references; node scripts/sync-python-surface.mjs: parity OK. Re-run in full after the spec-hunk revert.
Deviations: none outstanding. The one prior departure from repo convention — the hand-edit of the vendored spec/router-openapi.yaml — was raised in review and has been reverted, so this PR now touches only hand-written, reader-facing files.

_{🔄 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/119 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 9/3/2026 **Status:** ✅ Merged **Merged:** 9/4/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `matt/be-11088-bfl-flux-2-pro-example` --- ### 📝 Commits (2) - [`0b53b76`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/0b53b76e0c32040169a34a32c695aa6c8c897929) docs: replace the non-existent fal-ai/flux-pro example with bfl/flux-2-pro - [`8b08bd4`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/8b08bd489b5eedc5fd8f34df36639ba10a3cdebd) docs: leave the vendored Router spec examples to the upstream sync ### 📊 Changes **4 files changed** (+15 additions, -15 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+7 -7) 📝 `src/sdk/models.test.ts` (+5 -5) 📝 `src/sdk/models.ts` (+1 -1) 📝 `src/sdk/router-spec-contract.test.ts` (+2 -2) </details> ### 📄 Description ## ELI-5 Every "your first call" example in this SDK told you to run a model called `fal-ai/flux-pro`. There is no such model — so the very first thing a new reader copy-pastes could not work. This swaps it for `bfl/flux-2-pro`, which is real, enrolled, and the fastest path on the Router. Nothing about how the SDK behaves changes; only the example ID does. ## What was wrong The example was wrong twice over. `flux-pro` is not an enrolled Comfy Router model under any provider, and `fal-ai` is not a Comfy provider slug either — the fal provider's slug is `fal`, and `fal-ai` is an *upstream* path segment inside it. Flux is served direct from Black Forest Labs under `bfl/*`. The string originates as an `example:` on the `RouterModelId` schema in the canonical Comfy API contract, so it propagated into the vendored Router spec here and, copied by hand, into the README prose and the `comfy.models` JSDoc. ## What changed - **`README.md`** — all 7 occurrences (the quickstart call, the ID-format explanation, the typed-output example, the options example, the two retry examples, the abort-signal example). - **`src/sdk/models.ts`** — the JSDoc `@example`, which also renders in IDE hover and in generated typedoc, not only on GitHub. - **Fixtures** — `src/sdk/models.test.ts` (the shared `MODEL` constant, the asserted wire path, and the did-you-mean 404 pair, migrated as a matched set) and `src/sdk/router-spec-contract.test.ts` (the live-request fixture and its expected path, both sides moved together). **`spec/router-openapi.yaml` is deliberately NOT touched.** An earlier revision of this branch patched its three `example:` values; that edit has been reverted. See Judgment calls. ## Judgment calls **The vendored Router spec is left alone, and the fix belongs upstream.** `spec/router-openapi.yaml` is a one-way vendored copy that AGENTS.md and `spec/README.md` both declare off-limits to hand edits — "in every case this file is the side that is right". An earlier revision of this branch patched the three `example:` values anyway, on the reasoning that nothing is generated from that file so the edit reddens nothing. That reasoning is what the rule exists to catch: *because* no check reads `example:`, the edit lands green and is silently undone by the next sync. Concretely, the pending sync branch `chore/sync-router-spec-abdcb94` already carries `fal-ai/flux-pro` / `flux-pro` / `fal-ai` at those same three keys, so merging this branch and then that sync would put the vendored spec back out of step with the README and tests here — inside a routine sync diff, where the revert would not read as a regression to anyone reviewing it. The spec hunk is reverted; the upstream contract is the place to fix the string. Nothing in this repo is generated from or compared against that file's `example:` values (`scripts/check-spec-drift.mjs` regenerates only against `spec/openapi.yaml`, and checks the Router route/host constants by comparison), so the two sides carrying different example strings reddens no check and misleads no reader — the reader-facing surfaces are the README and the JSDoc, and both are correct. **Two fixture corpora are deliberately left on `fal-ai/...`, because a real ID would defeat exactly what they test.** The malformed-ID rejection list in `models.test.ts` (`"flux-pro"`, `""`, `"fal-ai/"`, `"/flux-pro"`, `"fal-ai/flux/pro"`, `"./flux-pro"`, `"fal-ai/.."`) exists to prove the parser refuses bad input without opening a socket. The percent-encoding fixture `"fal ai/flux#pro"` in `router-spec-contract.test.ts` exists to prove a space and a `#` are encoded rather than allowed to add a path segment. Both are hostile-input tests, not examples. `bfl/flux-2-pro/v1.1` in the "extra segment is a variant" test was migrated rather than left, since its point is the third segment, not the base ID — and a real base ID now makes the case read more clearly. ## Verification of the replacement ID `bfl/flux-2-pro` was not taken on trust from the report. Confirmed on the default branch of the server's own (private) source of truth, read read-only: it appears in the Router model enrolment table alongside the other `bfl` Flux routes, it has an authored per-model schema file, and the Router quickstart there already uses it as its canonical ID with `provider: bfl` / `model: flux-2-pro`. The same read confirms the negative: the fal section enrolls no Flux route at all. `bfl/flux-2-pro` also passes this SDK's own `parseModelId` on the real code path — `src/sdk/models.test.ts` asserts the wire path is `/v2/models/bfl/flux-2-pro` from an actual call against the stub server, which is what proves the digit-bearing `flux-2-pro` segment is accepted rather than merely plausible. ## Residual - **The vendored spec still carries the bad example, and this PR no longer changes that.** Correcting it is upstream work on the canonical contract, tracked separately and out of scope here. Until it lands, `spec/router-openapi.yaml` in this repo keeps `fal-ai/flux-pro` — a stale example in a file the repo's own rules point readers away from, rather than a hand-patch that a routine sync would quietly revert. - **The live Router was not exercised for this ID.** `GET https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json` returns `401 No Authorization header found` unauthenticated, and the auth gate sits in front of model resolution — the identical 401 comes back for `fal-ai/flux-pro` — so the public endpoint cannot distinguish a real ID from a fictional one without a credential, and none was used here. The enrolment evidence above is source-of-truth rather than live-catalog. - **One factual detail in the originating report is now slightly stale, in a direction that does not affect this change.** It states the only enrolled fal ID is `fal/patina`; the enrolment table on the default branch today also carries `minimax/h3-max` routes under fal. Still no fal Flux route, so the replacement stands. - **The originating user report itself was not readable from this environment** — it was relayed second-hand, and its exact wording is unverified here. The defect was reproduced independently from the repository state rather than from that report. - **Sibling repositories carrying the same example are untouched.** The sweep that sized this fix found the string live in several repos; this PR fixes only this one. Within this repo the sweep is complete: 27 lines matched `flux`/`fal`, 15 were reader-facing or fixture uses and are fixed, 3 are the vendored spec's `example:` values now left to the upstream sync, 7 are the two hostile-input corpora named above and are intentionally left, and 2 are an unrelated `FluxOutput` type name in prose. ## Provenance - **Authored by:** agent-work loop - **Verified:** `pnpm test`: 406 passed, 0 failed (23 files); `node scripts/check-spec-drift.mjs`: both checks OK (generated code in sync, Router route matches); `pnpm typecheck`, `pnpm lint`, `pnpm format:check`: clean; `node scripts/check-public-repo-hygiene.mjs`: OK, no internal-only references; `node scripts/sync-python-surface.mjs`: parity OK. Re-run in full after the spec-hunk revert. - **Deviations:** none outstanding. The one prior departure from repo convention — the hand-edit of the vendored `spec/router-openapi.yaml` — was raised in review and has been reverted, so this PR now touches only hand-written, reader-facing files. --- <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:47 +00:00