@bpmnkit/worker-client
v0.2.1
Published
Thin Zeebe REST client for standalone workers — no BPMNKit SDK required at runtime
Maintainers
Readme
Website · Documentation · GitHub · Changelog
Tools tier. Maintained, on 0.x: a minor release can break, so pin a version. See product tiers.
Overview
@bpmnkit/worker-client is a minimal TypeScript wrapper around the Zeebe REST API. It is the only runtime dependency for workers scaffolded by the BPMNKit AIKit /implement skill. It works with both local reebe and Camunda 8 cloud.
The key principle: workers built with this package have zero BPMNKit runtime dependency. They are standalone Node.js programs that can run anywhere.
Features
- Async generator polling —
client.poll(jobType)yields oneActivatedJobat a time; idles cleanly between polls - Job lifecycle —
complete(variables),fail(message, retries),throwError(code, message, variables) - Typed jobs —
createWorkerClient<JobTypes>()with the mapcasen gen typesgenerates types each job's variables, output, headers and error codes by job type - OAuth2 for Camunda SaaS — token fetching and caching built in; no manual auth management
- Env-var driven — reads
ZEEBE_ADDRESS,ZEEBE_CLIENT_ID,ZEEBE_CLIENT_SECRETautomatically - Zero dependencies — pure Node.js
fetch, no external packages
Installation
npm install @bpmnkit/worker-clientQuick Start
import { createWorkerClient } from "@bpmnkit/worker-client"
const client = createWorkerClient() // reads ZEEBE_ADDRESS from env
for await (const job of client.poll("com.example:send-email:1")) {
try {
await sendEmail(job.variables)
await job.complete({ sent: true })
console.log("completed", job.key)
} catch (err) {
await job.fail(err instanceof Error ? err.message : String(err), job.retries - 1)
}
}API Reference
createWorkerClient(options?)
const client = createWorkerClient({
address: "http://localhost:26500", // or ZEEBE_ADDRESS
clientId: "...", // or ZEEBE_CLIENT_ID (Camunda SaaS)
clientSecret: "...", // or ZEEBE_CLIENT_SECRET
tokenUrl: "...", // or ZEEBE_TOKEN_URL
audience: "zeebe.camunda.io", // or ZEEBE_TOKEN_AUDIENCE
workerName: "my-worker",
})client.poll(jobType, options?)
Async generator. Continuously polls Zeebe with long polling (requestTimeout, default 20 s).
Transient errors go to onError and are retried; rejected credentials or a 4xx answer end the loop by throwing.
Pass signal (an AbortSignal) to stop the loop, even while it waits.
for await (const job of client.poll("my-job-type", { maxJobs: 10, timeout: 60_000 })) {
// job.key, job.variables, job.retries, job.bpmnProcessId, ...
await job.complete({ result: "ok" })
}Typed jobs from BPMN
Generate a JobTypes map from your BPMN with casen gen types processes/ --out src/generated/bpmn-types.ts,
then pass it as the type argument. Job types, variable names, output keys and error codes are checked at compile time:
import type { JobTypes } from "./generated/bpmn-types.js"
const client = createWorkerClient<JobTypes>()
for await (const job of client.poll("charge-card")) {
job.variables.amount // typed; a misspelt key is a compile error
job.customHeaders.provider // literal header value from the BPMN
await job.complete({ transactionId: "t-1" })
}Without a type argument the client is untyped. See the Typed Workers guide.
Job methods
// Return output variables to the process
await job.complete({ approved: true })
// Fail the job; retries default to job.retries - 1 (incident when none are left)
await job.fail("upstream timeout")
// Throw a BPMN error (caught by an error boundary event in the diagram)
await job.throwError("PAYMENT_DECLINED", "Card issuer declined", { code: "05" })Environment Variables
| Variable | Description |
|----------|-------------|
| ZEEBE_ADDRESS | Zeebe REST base URL (default: http://localhost:26500) |
| ZEEBE_CLIENT_ID | OAuth2 client ID (Camunda SaaS) |
| ZEEBE_CLIENT_SECRET | OAuth2 client secret (Camunda SaaS) |
| ZEEBE_TOKEN_URL | OAuth2 token URL |
| ZEEBE_TOKEN_AUDIENCE | OAuth2 audience |
Used by AIKit
Workers generated by /implement (via the worker_scaffold MCP tool) depend only on this package.
They are TypeScript programs with their own package.json — fully standalone, no other BPMNKit packages needed.
See the Standalone Workers guide for deployment options (local dev, Docker, Camunda SaaS).
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 simulator for tests and demos |
| @bpmnkit/feel | FEEL expression language parser & evaluator |
| @bpmnkit/plugins | 34 composable canvas plugins |
| @bpmnkit/api | Camunda 8 REST API TypeScript client |
| @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art |
| @bpmnkit/markdown | BPMN diagrams in Markdown — remark, markdown-it and README pre-rendering |
| @bpmnkit/docspack | BPMN Kit docs as an offline docspack package for AI agents |
| @bpmnkit/camunda-docspack | Camunda 8 docs as an offline docspack package for AI agents |
| @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/connectors | Camunda 8 OOTB connector catalog and deterministic template application |
| @bpmnkit/cli | Camunda 8 command-line interface (casen) |
| @bpmnkit/proxy | Local AI bridge and Camunda API proxy server |
| @bpmnkit/patterns | Domain process patterns for BPMNKit AIKit |
| @bpmnkit/reebe-wasm | WebAssembly BPMN engine for browser simulation |
| @bpmnkit/flow | Code-first durable flows that derive BPMN, job types and workers |
| @bpmnkit/user-tasks | Embeddable user task widget for Camunda 8 |
| @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 |
| @bpmnkit/casen-worker-http | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data |
| @bpmnkit/casen-worker-ai | AI task worker — classify, summarize, extract, and decide using Claude |
