openapi-typescript on the Sume OpenAPI JSON: types only, one command

The answer

openapi-typescript's introduction says it turns OpenAPI 3.0 and 3.1 schemas into TypeScript using Node.js, and shows two input forms: a local file and a URL. Sume's spec is OpenAPI 3.0.3, so it is in the supported range. Run npx openapi-typescript https://api.sume.com/reference/json -o ./sume.d.ts and you have types for every request and response.

A .d.ts file is types only. It adds nothing to the runtime bundle, which makes it the lightest way to type your own fetch calls against Sume.

The commands

The tool's page describes the invocation as the input schema followed by --output or -o. The two forms below differ only in where the schema comes from.

# from the live spec
npx openapi-typescript https://api.sume.com/reference/json -o ./sume.d.ts

# from a committed copy (recommended for reproducible builds)
curl -s https://api.sume.com/reference/json -o sume-openapi.json
npx openapi-typescript ./sume-openapi.json -o ./sume.d.ts

Using the output with fetch

The generated file exports paths and components. Index into them to type a request body or a response without writing the shape by hand. For example, take the job status response type from the /v1/jobs/{id}/status path and use it to type the parsed JSON. Because Sume wraps every success body in a data object, your code reads body.data.terminal and body.data.result_ready.

Types do not validate. If you need a runtime check, pair them with a schema library at the boundary; the Valibot post shows one way.

Pin the schema and review the diff

A URL input is convenient for a first try. For a team, commit the downloaded JSON and the generated .d.ts, and regenerate when you choose to. A change in the spec then shows up as a plain diff on a types file, which is easy to review and easy to roll back.

Watch the nullable fields. In 3.0.x a field marked nullable: true generates a type that allows null; handle it explicitly when you compute a poll delay.

A small typed helper

With the types in place, write one function that takes a job id and returns the status body. Type the return value from the generated paths entry for the status endpoint, and let the compiler tell you when the spec changes a field you read. That is the whole benefit of generating types: the build fails at the line that depends on a field that moved.

Keep authentication out of the types. They describe request and response shapes only; you still add the Bearer or x-api-key header yourself, and you should send only one of them, since Sume answers 401 when both are present.

If you also need a fetch wrapper, the project documents a companion client, but you do not need it to use the types. Plain fetch with a typed return is enough for a polling loop, and it keeps your dependency list short.