@bpmnkit/worker-client

@bpmnkit/worker-client is a thin TypeScript wrapper around the Zeebe REST API. It is the only runtime dependency for scaffolded BPMNKit workers. It works with both local reebe and Camunda 8 cloud.

Installation

npm install @bpmnkit/worker-client

Quick start

import { createWorkerClient } from "@bpmnkit/worker-client"

const client = createWorkerClient()

for await (const job of client.poll("com.example:send-email:1")) {
  try {
    await sendEmail(job.variables)
    await job.complete({ sent: true })
  } catch (err) {
    await job.fail(err instanceof Error ? err.message : String(err))
  }
}

createWorkerClient(options?)

Factory function. Reads connection details from environment variables by default.

const client = createWorkerClient({
  address:      "http://localhost:26500",  // or ZEEBE_ADDRESS
  clientId:     "...",                     // or ZEEBE_CLIENT_ID
  clientSecret: "...",                     // or ZEEBE_CLIENT_SECRET
  tokenUrl:     "...",                     // or ZEEBE_TOKEN_URL
  audience:     "zeebe.camunda.io",        // or ZEEBE_TOKEN_AUDIENCE
  workerName:   "my-worker",              // sent during job activation
})

Options

Returns

A WorkerClient object with a single poll() method.

client.poll(jobType, options?)

Async generator. Continuously polls Zeebe for jobs of the given type. Pauses 5 seconds between polls when no jobs are available.

for await (const job of client.poll("my-job-type", { maxJobs: 10, timeout: 60_000 })) {
  // handle job
}

Options

Yields ActivatedJob

Each iteration yields a job with these fields and methods:

interface ActivatedJob {
  key: string                            // unique job key
  jobType: string                        // job type from BPMN task definition
  processInstanceKey: string
  bpmnProcessId: string
  elementId: string
  retries: number                        // remaining retries — use to pass to fail()
  variables: Record<string, unknown>     // process variables from the instance

  complete(variables?: Record<string, unknown>): Promise<void>
  fail(message: string, retries?: number): Promise<void>
  throwError(errorCode: string, message: string, variables?: Record<string, unknown>): Promise<void>
}

job.complete(variables?)

Completes the job, optionally returning output variables to the process instance.

await job.complete({ approved: true, reviewedAt: new Date().toISOString() })

job.fail(message, retries?)

Marks the job as failed. Zeebe will retry (or raise an incident if retries reach zero). retries defaults to 0 if not provided — pass job.retries - 1 to decrement.

await job.fail("External API returned 503", job.retries - 1)

job.throwError(errorCode, message, variables?)

Throws a BPMN error that can be caught by an error boundary event on the task in the diagram.

await job.throwError("PAYMENT_DECLINED", "Card declined by issuer", { code: "05" })

OAuth2 (Camunda SaaS)

When clientId and clientSecret are present (either via options or env vars), the client fetches an OAuth2 token before the first request and refreshes it automatically 60 seconds before expiry. No manual token management required.

ZEEBE_ADDRESS=https://your-cluster.bru-2.zeebe.camunda.io:443
ZEEBE_CLIENT_ID=abc123
ZEEBE_CLIENT_SECRET=def456
node dist/index.js

Environment variables

See also

• Standalone Workers — scaffolding, running, and deploying workers
• AI-Driven Implementation — generate workers automatically with /implement