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.

Not on the npm registry

@cloacina/client is not published to npm — it ships in-repo at clients/typescript, kept in lockstep with the server by a CI drift gate. Install it from the repository:

git clone https://github.com/colliery-io/cloacina && cd cloacina/clients/typescript
npm ci && npm run build && npm pack   # yields cloacina-client-<version>.tgz
npm install /path/to/cloacina-client-<version>.tgz   # in your project

Tutorial: execute a workflow and follow its events

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 });

Stream operational metrics (TypeScript-only helper — no Python/Rust equivalent): followOpsMetrics(client, options) yields server/compiler/fleet/reconciler metric snapshots from the admin-scoped ops_metrics:global recipient; render the most recent value.

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

for await (const snapshot of followOpsMetrics(client)) {
  render(snapshot); // latest wins
}

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