[PR #115] feat: fetch a job's execution log on demand with getLogs() #117

New issue

Open

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/comfy-typescript-sdk/pull/115
Author: @guill
Created: 9/1/2026
Status: 🔄 Open

Base: main ← Head: jacob/be-9479-add-devplat-execution-logs-support-to-sdk

📝 Commits (1)

20c57da feat: fetch a job's execution log on demand with getLogs()

📊 Changes

12 files changed (+702 additions, -8 deletions)

View changed files

📝 CHANGELOG.md (+17 -0)
📝 README.md (+52 -0)
📝 spec/openapi.yaml (+159 -1)
📝 src/low/generated/index.ts (+1 -1)
📝 src/low/generated/types.gen.ts (+77 -0)
📝 src/low/generated/zod.gen.ts (+21 -1)
📝 src/low/transport.test.ts (+52 -1)
📝 src/low/transport.ts (+30 -0)
📝 src/sdk/index.ts (+1 -1)
📝 src/sdk/jobs.ts (+76 -0)
➕ src/sdk/logs.test.ts (+141 -0)
📝 test/support/stub-server.ts (+75 -3)

📄 Description

Summary

Adds job.getLogs(), which fetches what a run printed and resolves to a JobLogs (text, truncated, capturedAt, complete) or null.

The log is a resource of its own rather than a field on the job, so submitting and polling never download one — run() to terminal issues zero log requests, and a caller pays only when it asks. Nothing is cached, so an early null on a job that has not finished cannot mask the log it goes on to produce; call again after a terminal status.

null is an ordinary answer, not an error. It covers every reason there is nothing to read — the deployment captures no logs at all, the job has not finished, it predates capture, the run was killed before the worker could report an outcome, capture failed, or the log is withheld from anonymous callers — and the API deliberately does not distinguish them.

A surface that captures no logs omits urls.logs entirely. The SDK answers from that absence without a request, rather than building the path itself, which would 404 as though the job were missing.

Consumer impact

Purely additive. No export is removed or narrowed, and existing code keeps compiling:

New: Job.getLogs(), ComfyLow.getJobLogs(), and the exported JobLogs type.
New JobUrls.logs, optional — a server that does not send it still validates.
capturedAt is resolved to a Date, matching getDownloadUrl's expiresAt and the Python twin's datetime.

The vendored spec is synced from the canonical contract and src/low/generated regenerated.

Testing

pnpm test — 419 passed across 24 files. New behavioural coverage: 200 yields a typed value, 204 yields null, three calls make three requests, run() to terminal issues none, a missing urls.logs short-circuits without a request, an empty urls.logs is treated the same way, and the SDK follows the link rather than rebuilding the path.
pnpm lint, pnpm format:check, pnpm typecheck — clean.
pnpm check:spec-drift — src/low/generated in sync with the vendored spec.
pnpm check:sdk-parity and the public-repo hygiene check — clean.

Also verified end to end by driving the real SDK against a live HTTP server, not only the test doubles.

Opened as a draft: the server side of this contract is not released yet.

_{🔄 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/115 **Author:** [@guill](https://github.com/guill) **Created:** 9/1/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `jacob/be-9479-add-devplat-execution-logs-support-to-sdk` --- ### 📝 Commits (1) - [`20c57da`](https://github.com/Comfy-Org/comfy-typescript-sdk/commit/20c57da77d307162601913e6b5f967e8f7fd924f) feat: fetch a job's execution log on demand with getLogs() ### 📊 Changes **12 files changed** (+702 additions, -8 deletions) <details> <summary>View changed files</summary> 📝 `CHANGELOG.md` (+17 -0) 📝 `README.md` (+52 -0) 📝 `spec/openapi.yaml` (+159 -1) 📝 `src/low/generated/index.ts` (+1 -1) 📝 `src/low/generated/types.gen.ts` (+77 -0) 📝 `src/low/generated/zod.gen.ts` (+21 -1) 📝 `src/low/transport.test.ts` (+52 -1) 📝 `src/low/transport.ts` (+30 -0) 📝 `src/sdk/index.ts` (+1 -1) 📝 `src/sdk/jobs.ts` (+76 -0) ➕ `src/sdk/logs.test.ts` (+141 -0) 📝 `test/support/stub-server.ts` (+75 -3) </details> ### 📄 Description ## Summary Adds `job.getLogs()`, which fetches what a run printed and resolves to a `JobLogs` (`text`, `truncated`, `capturedAt`, `complete`) or `null`. The log is a resource of its own rather than a field on the job, so submitting and polling never download one — `run()` to terminal issues zero log requests, and a caller pays only when it asks. Nothing is cached, so an early `null` on a job that has not finished cannot mask the log it goes on to produce; call again after a terminal status. `null` is an ordinary answer, not an error. It covers every reason there is nothing to read — the deployment captures no logs at all, the job has not finished, it predates capture, the run was killed before the worker could report an outcome, capture failed, or the log is withheld from anonymous callers — and the API deliberately does not distinguish them. A surface that captures no logs omits `urls.logs` entirely. The SDK answers from that absence without a request, rather than building the path itself, which would 404 as though the job were missing. ## Consumer impact Purely additive. No export is removed or narrowed, and existing code keeps compiling: - New: `Job.getLogs()`, `ComfyLow.getJobLogs()`, and the exported `JobLogs` type. - New `JobUrls.logs`, optional — a server that does not send it still validates. - `capturedAt` is resolved to a `Date`, matching `getDownloadUrl`'s `expiresAt` and the Python twin's `datetime`. The vendored spec is synced from the canonical contract and `src/low/generated` regenerated. ## Testing - `pnpm test` — 419 passed across 24 files. New behavioural coverage: 200 yields a typed value, 204 yields `null`, three calls make three requests, `run()` to terminal issues none, a missing `urls.logs` short-circuits without a request, an empty `urls.logs` is treated the same way, and the SDK follows the link rather than rebuilding the path. - `pnpm lint`, `pnpm format:check`, `pnpm typecheck` — clean. - `pnpm check:spec-drift` — `src/low/generated` in sync with the vendored spec. - `pnpm check:sdk-parity` and the public-repo hygiene check — clean. Also verified end to end by driving the real SDK against a live HTTP server, not only the test doubles. Opened as a draft: the server side of this contract is not released yet. --- <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:04:43 +00:00

bsakaguchi referenced this issue

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

[PR #117] [CLOSED] chore: sync vendored Comfy Router spec (cloud@18cb4d7) #119