[PR #202] fix: land the cloud@b8907cf v2 spec sync (format, regenerate, listJobs) #205

New issue

Open

opened 2026-10-31 22:05:39 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 22:05:39 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/202
Author: @mattmillerai
Created: 10/9/2026
Status: 🔄 Open

Base: main ← Head: matt/land-v2-spec-sync-b8907cf

📝 Commits (5)

379af55 chore: sync vendored Comfy API v2 spec from cloud@b8907cf
ea7bad3 Merge remote-tracking branch 'origin/chore/sync-v2-spec' into matt/land-v2-spec-sync-b8907cf
ee0b5f3 fix: land the cloud@b8907cf v2 spec sync (format, regenerate, listJobs)
f69f83d fix(low): take JobMetadata, JobListItem and JobListPage from the generated spec types
c1c641d docs: mark the low jobs-list type change breaking, and match Asset.jobId to the dedup contract

📊 Changes

9 files changed (+695 additions, -100 deletions)

View changed files

📝 CHANGELOG.md (+11 -0)
📝 spec/openapi.yaml (+340 -29)
📝 src/low/generated/index.ts (+1 -1)
📝 src/low/generated/types.gen.ts (+243 -26)
📝 src/low/generated/zod.gen.ts (+86 -10)
📝 src/low/index.ts (+0 -2)
📝 src/low/transport.ts (+6 -30)
📝 src/sdk/assets.ts (+6 -1)
📝 src/sdk/jobs.ts (+2 -1)

📄 Description

Summary

Lands the vendored v2 spec sync from #158 (cloud@b8907cf) together with the follow-up it needs. #158's rolling sync branch must not take commits, so the follow-up goes on this branch instead. The branch merges #158's commit unchanged and adds commits that make these changes:

Formatting: spec/openapi.yaml run through oxfmt. The parsed content is unchanged; the sync wrote it unformatted, which failed pnpm format:check before any test could run.
Regeneration: src/low/generated regenerated with pnpm generate. The sync could not do this itself.
listJobs: added to OPERATION_IDS and OPERATION_METHODS. The spec now declares GET /api/v2/jobs (listJobs), which ComfyLow.listJobs (#200) already called ahead of the spec. The old "ahead of the vendored spec" note on that method is removed.
Jobs-list types: codegen now emits JobMetadata, JobListItem and JobList, which the hand-written copies in src/low/transport.ts were shadowing with a drifted shape. The hand-written copies are removed so the generated ones are exported; JobListPage is now an alias of JobList, and jobSummary reads the undeclared deployment_id extra narrowed to a string. Noted under CHANGELOG "Changed".
Doc reconciliation: the Asset.jobId TSDoc now matches the synced contract. An upload that matches an existing output by file path and bytes resolves to that output and carries its job. The CHANGELOG entry for the jobs-list types is marked Breaking for @comfyorg/sdk/low type consumers.

Once this lands, #158 has nothing left to add. The next sync run should refresh or close it.

ELI5

The server team published a new version of the API description, and the bot copied it in. The bot couldn't finish the job: the file wasn't formatted, the generated code wasn't rebuilt, and one new endpoint (listing jobs) wasn't registered, although the SDK already supported it. This PR finishes those three steps.

Provenance

Verified:

The branch merges #158's commit unchanged.
Local at c1c641d: pnpm lint, pnpm format:check, pnpm typecheck, pnpm check:spec-drift (both checks OK), pnpm test (785 passed, 5 skipped) and pnpm build.
Public-repo hygiene runs only in CI now (shared reusable workflow), not locally.

Deviations:

This PR is limited to the mechanical sync, the jobs-list type fix and the doc reconciliation above. SDK behaviour exposed by the new contract is deferred to follow-ups, not fixed here: the terminal SSE error event, bodiless HEAD 403/429, sso_required mapping, the bare-message 400, the list-item deployment_id, the rate_limited error mapping and header-less retry, 429 retry on the asset materialization path, and 429 handling in Job.events().

🤖 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/202 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 10/9/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `matt/land-v2-spec-sync-b8907cf` --- ### 📝 Commits (5) - [`379af55`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/379af551a8efcaeb8ca6d0c9a7edce2fcbb58ac4) chore: sync vendored Comfy API v2 spec from cloud@b8907cf - [`ea7bad3`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/ea7bad3a763fd19ed61c95986fd9ed276659e4e3) Merge remote-tracking branch 'origin/chore/sync-v2-spec' into matt/land-v2-spec-sync-b8907cf - [`ee0b5f3`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/ee0b5f3e09ee249ea07616da4fa33a94c860c468) fix: land the cloud@b8907cf v2 spec sync (format, regenerate, listJobs) - [`f69f83d`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/f69f83ddb1444be94730e8534570031b565053cf) fix(low): take JobMetadata, JobListItem and JobListPage from the generated spec types - [`c1c641d`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/c1c641d351b23b6624a169f2819aa2a2abce5484) docs: mark the low jobs-list type change breaking, and match Asset.jobId to the dedup contract ### 📊 Changes **9 files changed** (+695 additions, -100 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+11 -0) 📝 `spec/openapi.yaml` (+340 -29) 📝 `src/low/generated/index.ts` (+1 -1) 📝 `src/low/generated/types.gen.ts` (+243 -26) 📝 `src/low/generated/zod.gen.ts` (+86 -10) 📝 `src/low/index.ts` (+0 -2) 📝 `src/low/transport.ts` (+6 -30) 📝 `src/sdk/assets.ts` (+6 -1) 📝 `src/sdk/jobs.ts` (+2 -1) </details> ### 📄 Description ## Summary Lands the vendored v2 spec sync from #158 (`cloud@b8907cf`) together with the follow-up it needs. #158's rolling sync branch must not take commits, so the follow-up goes on this branch instead. The branch merges #158's commit unchanged and adds commits that make these changes: - **Formatting:** `spec/openapi.yaml` run through oxfmt. The parsed content is unchanged; the sync wrote it unformatted, which failed `pnpm format:check` before any test could run. - **Regeneration:** `src/low/generated` regenerated with `pnpm generate`. The sync could not do this itself. - **`listJobs`:** added to `OPERATION_IDS` and `OPERATION_METHODS`. The spec now declares `GET /api/v2/jobs` (`listJobs`), which `ComfyLow.listJobs` (#200) already called ahead of the spec. The old "ahead of the vendored spec" note on that method is removed. - **Jobs-list types:** codegen now emits `JobMetadata`, `JobListItem` and `JobList`, which the hand-written copies in `src/low/transport.ts` were shadowing with a drifted shape. The hand-written copies are removed so the generated ones are exported; `JobListPage` is now an alias of `JobList`, and `jobSummary` reads the undeclared `deployment_id` extra narrowed to a string. Noted under CHANGELOG "Changed". - **Doc reconciliation:** the `Asset.jobId` TSDoc now matches the synced contract. An upload that matches an existing output by file path and bytes resolves to that output and carries its job. The CHANGELOG entry for the jobs-list types is marked **Breaking** for `@comfyorg/sdk/low` type consumers. Once this lands, #158 has nothing left to add. The next sync run should refresh or close it. ## ELI5 The server team published a new version of the API description, and the bot copied it in. The bot couldn't finish the job: the file wasn't formatted, the generated code wasn't rebuilt, and one new endpoint (listing jobs) wasn't registered, although the SDK already supported it. This PR finishes those three steps. ## Provenance **Verified:** - The branch merges #158's commit unchanged. - Local at `c1c641d`: `pnpm lint`, `pnpm format:check`, `pnpm typecheck`, `pnpm check:spec-drift` (both checks OK), `pnpm test` (785 passed, 5 skipped) and `pnpm build`. - Public-repo hygiene runs only in CI now (shared reusable workflow), not locally. **Deviations:** - This PR is limited to the mechanical sync, the jobs-list type fix and the doc reconciliation above. SDK behaviour exposed by the new contract is deferred to follow-ups, not fixed here: the terminal SSE `error` event, bodiless HEAD 403/429, `sso_required` mapping, the bare-`message` 400, the list-item `deployment_id`, the `rate_limited` error mapping and header-less retry, 429 retry on the asset materialization path, and 429 handling in `Job.events()`. 🤖 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 added the

pull-request

label

2026-10-31 22:05:39 +00:00