Website · Documentation · GitHub · Changelog

Overview

@bpmnkit/api is a fully typed TypeScript SDK for the Camunda 8 Orchestration Cluster REST API v2. Every endpoint, request body, and response shape is typed end-to-end.

Features

• 180 typed operations across 30+ resource namespaces
• 502 TypeScript types generated from the official OpenAPI spec
• Authentication — Bearer token, OAuth2 (auto-refresh), HTTP Basic
• Retries — configurable exponential backoff with jitter
• Caching — in-memory LRU + TTL cache for read operations
• Events — subscribe to request, response, error, retry, and cache events
• Structured logging — pluggable logger with configurable levels
• Config resolution — constructor → YAML file → environment variables
• Token persistence — disk cache for OAuth2 access tokens
• Zero runtime dependencies

Installation

npm install @bpmnkit/api

Quick Start

import { CamundaClient } from "@bpmnkit/api"

const client = new CamundaClient({
  baseUrl: "https://cluster.camunda.io",
  auth: {
    type: "oauth2",
    clientId: process.env.CAMUNDA_CLIENT_ID!,
    clientSecret: process.env.CAMUNDA_CLIENT_SECRET!,
    tokenUrl: "https://login.cloud.camunda.io/oauth/token",
    audience: "zeebe.camunda.io",
  },
})

// Deploy a process
await client.deployment.create({
  resources: [{ name: "order.bpmn", content: bpmnXml }],
})

// Start a process instance
const instance = await client.processInstance.create({
  processDefinitionId: "order-process",
  variables: { orderId: "ORD-001", amount: 99.99 },
})

// Complete a user task
const tasks = await client.userTask.search({
  filter: { processInstanceKey: instance.processInstanceKey },
})
await client.userTask.complete(tasks.items[0].userTaskKey, {
  variables: { approved: true },
})

Authentication

// OAuth2 (recommended for Camunda Cloud)
const client = new CamundaClient({
  baseUrl: "...",
  auth: { type: "oauth2", clientId: "...", clientSecret: "...", tokenUrl: "...", audience: "..." },
})

// Bearer token (static)
const client = new CamundaClient({
  baseUrl: "...",
  auth: { type: "bearer", token: "..." },
})

// HTTP Basic
const client = new CamundaClient({
  baseUrl: "...",
  auth: { type: "basic", username: "...", password: "..." },
})

Resource Namespaces

| Namespace | Description | |-----------|-------------| | client.processInstance | CRUD + cancel + variables | | client.processDefinition | Definitions, XML, start forms | | client.deployment | Create, list, delete deployments | | client.job | Activate, complete, fail, update | | client.userTask | Search, complete, assign, update | | client.decisionDefinition | List, XML, evaluate | | client.decisionInstance | Search, get | | client.message | Publish, correlate | | client.signal | Broadcast | | client.incident | Search, resolve | | client.variable | Search, get | | client.flowNodeInstance | Search, get | | client.user | Search, create, update | | client.role | Search, create, assign | | client.group | Search, create, assign | | client.authorization | Manage permissions | | client.tenant | Multi-tenant management | | client.clock | Time manipulation (testing) |

Error Handling

import { CamundaNotFoundError, CamundaRateLimitError } from "@bpmnkit/api"

try {
  await client.processInstance.get(key)
} catch (err) {
  if (err instanceof CamundaNotFoundError) console.log("Not found")
  if (err instanceof CamundaRateLimitError) console.log("Rate limited")
}

Related Packages

| Package | Description | |---------|-------------| | @bpmnkit/core | BPMN/DMN/Form parser, builder, layout engine | | @bpmnkit/canvas | Zero-dependency SVG BPMN viewer | | @bpmnkit/editor | Full-featured interactive BPMN editor | | @bpmnkit/engine | Lightweight BPMN process execution engine | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 22 composable canvas plugins | | @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art | | @bpmnkit/ui | Shared design tokens and UI components | | @bpmnkit/profiles | Shared auth, profile storage, and client factories for CLI & proxy | | @bpmnkit/operate | Monitoring & operations frontend for Camunda clusters | | @bpmnkit/connector-gen | Generate connector templates from OpenAPI specs | | @bpmnkit/cli | Camunda 8 command-line interface (casen) | | @bpmnkit/proxy | Local AI bridge and Camunda API proxy server | | @bpmnkit/cli-sdk | Plugin authoring SDK for the casen CLI | | @bpmnkit/create-casen-plugin | Scaffold a new casen CLI plugin in seconds | | @bpmnkit/casen-report | HTML reports from Camunda 8 incident and SLA data |

License

MIT © BPMN Kit — made by u11g