Skip to main content
Cloacina Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  1. Cloacina
  2. /
  3. Reference
  4. /
  5. SDKs
  6. /
  7. TypeScript SDK

TypeScript SDK

TypeScript SDK (@cloacina/client)

Types generated by a pinned openapi-typescript over the tiny openapi-fetch runtime, wrapped in a hand-written shim. Node ≥ 20 and modern browsers; dual ESM/CJS.

Tutorial: execute a workflow and follow its events 

npm install @cloacina/client

import { CloacinaClient, followExecutionEvents } from "@cloacina/client";

const client = new CloacinaClient({
  baseUrl: "http://localhost:8080",
  apiKey: process.env.CLOACINA_API_KEY!,
  tenant: "public",
});

const { execution_id } = await client.executeWorkflow("my_workflow", {
  context: { input: 42 },
});

for await (const event of followExecutionEvents(client, execution_id)) {
  console.log(event);
}

How-to

Browser usage requires two deliberate steps:

  1. The server must opt in to CORS: --cors-allowed-origins https://your-ui.example.com (or CLOACINA_CORS_ALLOWED_ORIGINS). CORS is off by default.
  2. Understand the auth trade-off: API-key-in-browser is the v1 auth story for first-party admin UIs only. The key is visible in devtools — never ship one to untrusted users. WebSocket upgrades never carry the key; the SDK mints a single-use 60-second ticket per connection.

Paginate executions:

for await (const execution of client.iterateExecutions({ status: "Failed" })) {
  console.log(execution.id, execution.workflow_name);
}

Handle errors — CloacinaApiError carries the canonical envelope:

import { CloacinaApiError } from "@cloacina/client";

try {
  await client.getWorkflow("missing");
} catch (e) {
  if (e instanceof CloacinaApiError) console.log(e.status, e.code, e.message);
}

Node 20: the WS wrapper uses the platform WebSocket (native in Node ≥ 21 and browsers); on Node 20 pass an implementation:

import { WebSocket } from "ws";
followExecutionEvents(client, id, { webSocket: WebSocket as never });

Reach past the shim — the typed openapi-fetch client is exposed as client.api:

const { data } = await client.api.GET("/v1/health/graphs");

Reference

  • Wire contract: OpenAPI document, WebSocket protocol
  • Generated types ship in the package under generated/types.ts (paths, components exports)
  • Regeneration (pinned): see clients/typescript/README.md in the repository
gdoc_arrow_left_alt Python SDK WebSocket Protocol gdoc_arrow_right_alt