SDKs

The TypeScript and Python SDKs are generated from the same operation registry as the API: one method per operation, typed requests, validated responses, and the idempotency and retry rules built in.

Getting the packages

The SDKs are not yet published to the public npm and PyPI registries. Your Cumulus contact provides the packages; until you have them, every operation works over plain HTTPS (see the curl samples).

One method per operation

An operation domain.method is client.domain.method(…) in both SDKs: runs.create is client.runs.create. Each call takes the request's parts by name: path, query, bodyand, for commands that take one, the idempotency key. The SDK sends Authorization, generates an Idempotency-Key when you pass none, and raises one error type carrying the API's code, retryable, outcome and the key it sent.

In Python, a method named by a keyword takes a trailing underscore (client.agents.import_), and responses are Pydantic models. Both SDKs can also call an operation by id: client.call("runs.get", …).

TypeScript

run.mjs

import { Cumulus } from "@cumulus/sdk";

const client = new Cumulus({ apiKey: process.env.CUMULUS_API_KEY });
const run = await client.runs.create({
  body: { channel: "cloud", agent_id: "…", mode: "task", input: { ticket: "I was charged twice this month." } },
});
for await (const event of client.events({ path: { run_id: run.run_id } })) {
  console.log(event.sequence, event.type);
  if (event.type === "run.ended") break;
}

Python

run.py

from cumulus import Cumulus

with Cumulus() as client:  # reads CUMULUS_API_KEY
    run = client.runs.create(
        body={"channel": "cloud", "agent_id": "…", "mode": "task", "input": {"ticket": "I was charged twice this month."}}
    )
    for event in client.events(str(run.run_id)):
        payload = event.model_dump(mode="json")
        print(payload["sequence"], payload["type"])
        if payload["type"] == "run.ended":
            break

Errors

When to retry

• error.outcome === "unknown": the command may have happened (a timeout, a dropped connection). Retry with the same key: error.idempotencyKey / error.idempotency_key.
• error.retryable with outcome none: nothing happened; retry after a pause.
• Anything else: fix the request. error.code and error.details say what is wrong.

Every step of the main flows, in both SDKs, is in Using the API.