Website · Documentation · GitHub · Changelog

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 one ActivatedJob at a time; idles cleanly between polls
• Job lifecycle — complete(variables), fail(message, retries), throwError(code, message, variables)
• 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_SECRET automatically
• Zero dependencies — pure Node.js fetch, no external packages

Installation

npm install @bpmnkit/worker-client

Quick 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. Pauses 5 seconds between polls when idle.

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

Job methods

// Return output variables to the process
await job.complete({ approved: true })

// Fail the job (Zeebe retries or raises incident at retries=0)
await job.fail("upstream timeout", job.retries - 1)

// 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 execution engine | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 22 composable canvas plugins | | @bpmnkit/api | Camunda 8 REST API TypeScript client | | @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/patterns | Domain process patterns for BPMNKit AIKit | | @bpmnkit/reebe-wasm | WebAssembly BPMN engine for browser simulation | | @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 |

License

MIT © BPMN Kit — made by u11g