Migrate from the TypeScript REST client

SDK 0.3.4 keeps the typed API client and adds tools for defining agents, publishing changes and implementing customer endpoints. You can upgrade an application that only calls the API without rewriting it as an agent-as-code project.

The new authoring helpers belong to TypeScript. The separately maintained Python client continues to provide typed API access.

Update the package and Node version

Use Node 22 or newer. Obtain the authorized SDK archive and install it in your application:

npm install /absolute/path/to/cumulus-sdk-0.3.4.tgz

Keep the updated lockfile and run your application's tests. Package installation uses package access; Cumulus API calls use your workspace's API key.

Both ESM and CommonJS are supported, with matching declarations:

// ESM
import { Cumulus } from '@cumulus/sdk';

// CommonJS
const { Cumulus } = require('@cumulus/sdk');

Compile TypeScript to JavaScript before loading definitions through the CLI. Examples that use Node's built-in SQLite require Node 22.13 or newer.

Keep existing API calls

The root client still accepts path, query, body and idempotencyKey. Pass your workspace's API origin explicitly:

import { Cumulus } from '@cumulus/sdk';
const baseUrl = process.env.CUMULUS_API_URL;
if (!baseUrl) throw new Error('Set CUMULUS_API_URL');
const client = new Cumulus({ baseUrl }); // reads CUMULUS_API_KEY
const page = await client.agents.list({ query: { limit: 20 } });
for (const agent of page.agents) console.log(agent.ref.id, agent.name);

client.call(operationId, input, signal?) also remains available. Applications with separate service origins or custom route templates can continue using operationPaths and their existing transport configuration.

Successful JSON responses are validated by default. If validation fails after upgrading, compare the response with the expected contract and API deployment before changing validation settings.

Add features as you need them

For example, keep your existing client.runs.get({ path: { run_id } }) code while introducing a TypeScript definition for one agent. Follow the tutorial to add that definition and its backend tool without replacing unrelated API code.

Review environment and server integration

The root client's optional environment default is CUMULUS_BASE_URL; the CLI reads CUMULUS_API_URL and CUMULUS_API_KEY. Setting baseUrl explicitly, as above, avoids ambiguity when your application and CLI use the same workspace.

Keep API keys and Node-only authoring/server helpers in your backend. Browser applications call your authenticated same-origin proxy. The client uses a 30-second default JSON timeout and refuses redirects; set the correct API origin rather than relying on redirects.

When bringing an existing Studio agent into source control, export and review its public draft, then adopt the reviewed revision. Studio collaboration explains this process. Tool implementation code stays in your application; publishing a definition supplies its contract and connection settings.