Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@camunda8/sdk

camunda94.6kApache-2.08.7.30TypeScript support: included

NPM

zeebe, zeebe-node, camunda, automation, bpmn, camunda 8, operate, optimize, tasklist, web modeler, modeler

readme

Camunda 8 JavaScript SDK

NPM

License

Full API Docs.

This is the official Camunda 8 JavaScript SDK. It is written in TypeScript and runs on Node.js. See why this does not run in a web browser.

See the Getting Started Example in the Camunda Docs for a quick start.

What does "supported" mean?

This is the official supported-by-Camunda Nodejs SDK for Camunda Platform 8.

The Node.js SDK will not always support all features of Camunda Platform 8 immediately upon their release. Complete API coverage for a platform release will lag behind the platform release.

Prioritisation of implementing features is influenced by customer demand.

Semantic versioning

The SDK package tracks Camunda Platform 8 minor versioning. Feature releases to support current Platform minor version features result in a patch release of the SDK.

Using the SDK in your project

Install the SDK as a dependency:

npm i @camunda8/sdk

Usage

The functionality of Camunda 8 is exposed via dedicated clients for the component APIs. The recommended API client for Camunda 8.8 is the Orchestration Cluster API, using the CamundaRestClient.

import { Camunda8 } from '@camunda8/sdk'

// Optional: Import types for CamundaRestClient requests and responses
import type { CamundaRestTypes} from '@camunda8/sdk'

const c8 = new Camunda8()

// Camunda 8 Orchestration API - recommended API from 8.8.0
const restClient = c8.getCamundaRestClient()

// Zeebe gRPC client - not recommended for new users
const zeebe = c8.getZeebeGrpcApiClient()

// Camunda v1 REST API clients
const operate = c8.getOperateApiClient()
const optimize = c8.getOptimizeApiClient()
const tasklist = c8.getTasklistApiClient()
const modeler = c8.getModelerApiClient()
const admin = c8.getAdminApiClient()

Configuration

The configuration for the SDK can be done by any combination of environment variables and explicit configuration passed to the Camunda8 constructor.

The recommended method of configuration is using the zero-conf constructor, which hydrates the configuration completely from the environment:

const camunda = new Camunda8()

This allows you to cleanly separate the concern of configuration from your code and locate it purely in environment variable management.

The complete documentation of all configuration parameters (environment variables) can be found here.

Any configuration passed in to the Camunda8 constructor is merged over any configuration in the environment. The configuration object fields and the environment variables have exactly the same names.

A note on how int64 is handled in the JavaScript SDK

Entity keys in Camunda 8.6 and earlier are stored and represented as int64 numbers. The range of int64 extends to numbers that cannot be represented by the JavaScript number type. To deal with this, int64 keys are serialised by the SDK to the JavaScript string type. See this issue for more details.

For int64 values whose type is not known ahead of time, such as job variables, you can pass an annotated data transfer object (DTO) to decode them reliably. See the section on Process Variable Typing. If no DTO is specified, the default behavior of the SDK is to serialise all numbers to JavaScript number, and to throw an exception if a number value is detected at a runtime that cannot be accurately represented as the JavaScript number type (that is, a value greater than 2^53-1).

Authorization

Calls to APIs can be authorized using a number of strategies. The most common is OAuth - a token that is obtained via a client id/secret pair exchange.

  • Camunda SaaS and Self-Managed by default are configured to use OAuth with token exchange. In most cases, you will use the OAUTH strategy and provide configuration only. The token exchange and its lifecycle are managed by the SDK in this strategy. This passes the token in the authorization header of requests.
  • If you secure the gateway behind an Nginx reverse-proxy secured with basic authentication, you will use the BASIC strategy. This adds the login credentials as the authorization header on requests.
  • For C8Run 8.7, you will need to use the COOKIE strategy. This manages a session cookie obtained from a login endpoint, and adds it as a cookie header to requests.
  • For more customisation, you can use the BEARER strategy. This is a strategy that allows you to dynamically provide the Bearer token directly. The currently set token is added as the authorization header on requests.
  • If you have a even more advanced use-case (for example, the need to add specific headers with specific values to authenticate with a proxy gateway), you can construct your own AuthProvider and pass it to the constructor.
  • You can also disable header auth completely and use mTLS (client certificate) — or no authentication at all — with the NONE strategy.

For more details on each of these scenarios, see the relevant section below.

Disable Auth

To disable Auth, set the environment variable CAMUNDA_AUTH_STRATEGY=NONE. You can use this when running against a minimal Zeebe broker in a development environment, for example. You can also use this when your authentication is being done using an x509 mTLS certificate (see the section on mTLS).

OAuth

If your platform is secured with OAuth token exchange (Camunda SaaS or Self-Managed with Identity), provide the following configuration fields at a minimum, either via the Camunda8 constructor or in environment variables:

CAMUNDA_AUTH_STRATEGY=OAUTH
ZEEBE_GRPC_ADDRESS=...
ZEEBE_REST_ADDRESS=...
ZEEBE_CLIENT_ID=...
ZEEBE_CLIENT_SECRET=...
CAMUNDA_OAUTH_URL=...

To get a token for the Camunda SaaS Administration API or the Camunda SaaS Modeler API, set the following:

CAMUNDA_AUTH_STRATEGY=OAUTH
CAMUNDA_CONSOLE_CLIENT_ID=...
CAMUNDA_CONSOLE_CLIENT_SECRET=...

Token caching

OAuth tokens are cached in-memory and on-disk. The disk cache is useful to prevent token endpoint saturation when restarting or rolling over workers, for example. They can all hit the cache instead of requesting new tokens.

You can turn off the disk caching by setting CAMUNDA_TOKEN_DISK_CACHE_DISABLE to true. This will cache tokens in-memory only.

By default, the token cache directory is $HOME/.camunda. You can specify a different directory by providing a full file path value for CAMUNDA_TOKEN_CACHE_DIR.

Here is an example of specifying a different cache directory via the constructor:

import { Camunda8 } from '@camunda8/sdk'

const c8 = new Camunda8({
  CAMUNDA_TOKEN_CACHE_DIR: '/tmp/cache',
})

If the cache directory does not exist, the SDK will attempt to create it (recursively). If the SDK is unable to create it, or the directory exists but is not writeable by your application, the SDK will throw an exception.

Basic Auth

To use basic auth, set the following values either via the environment or explicitly in code via the constructor:

CAMUNDA_AUTH_STRATEGY=BASIC
CAMUNDA_BASIC_AUTH_USERNAME=....
CAMUNDA_BASIC_AUTH_PASSWORD=...

For C8Run with 8.7, you need to use Cookie Authentication.

To use cookie auth, set the following value:

CAMUNDA_AUTH_STRATEGY=COOKIE

# Optional configurable values - these are the defaults
CAMUNDA_COOKIE_AUTH_URL=http://localhost:8080/api/login
CAMUNDA_COOKIE_AUTH_USERNAME=demo
CAMUNDA_COOKIE_AUTH_PASSWORD=demo

Bearer Token Auth

The BEARER auth strategy is provided as a low-level primitive for advanced use-cases that are not covered by the others. In this case, you need to pass an authorization header with a Bearer token on requests, but it is not issued by a supported OAuth token exchange endpoint. In this case, you can implement a token exchange mechanism and manage the lifecycle of the token, and dynamically inject it as a header through a BearerAuthProvider.

To use a Bearer token that you have already obtained, and that does not need to be dynamically updated during the lifetime of the application, simply set the following values:

CAMUNDA_AUTH_STRATEGY=BEARER
CAMUNDA_OAUTH_TOKEN=....

To refresh the bearer token dynamically at runtime (for example, when it has expired and your obtain a new one), you pass in a BearerAuthProvider that you control:

import { Camunda8, Auth } from '@camunda8/sdk'

const bearerAuth = new Auth.BearerAuthProvider()
const c8 = new Camunda8({ oauthProvider: bearerAuth }) // All clients and workers will use bearerAuth
// ... after obtaining a new token
bearerAuth.setToken('SOMETOKENVALUE....') // Dynamically update the bearer token value

Advanced Custom Headers

You can add arbitrary headers to all requests by implementing IOAuthProvider:

import { Camunda8, Auth } from '@camunda8/sdk'

class MyCustomAuthProvider implements Auth.IOAuthProvider {
  async getToken(audience: string) {
    // here we give a static example, but this class may read configuration,
    // exchange credentials with an endpoint, manage token lifecycles, and so forth...
    // Return an object which will be merged with the headers on the request
  return {
    'x-custom-auth-header': 'someCustomValue',
    }
  }
}

const customAuthProvider = new MyCustomAuthProvider()
const c8 = new Camunda8({ oauthProvider: customAuthProvider })

You can use this approach to wrap one of the existing strategy classes using a facade pattern to encapsulate and extend it.

TLS

If you are using self-signed certificates, you can provide the self-signed certificate path using the configuration parameter / environment variable: CAMUNDA_CUSTOM_ROOT_CERT_PATH.

mTLS

The Zeebe gRPC client supports mTLS. You can provide the mTLS certificate and key with:

CAMUNDA_CUSTOM_CERT_CHAIN_PATH # path to mTLS certificate
CAMUNDA_CUSTOM_PRIVATE_KEY_PATH # path to mTLS (client-side) key

Connection configuration examples

Camunda 8 Run 8.8

This is the configuration for Camunda 8 Run - a local Camunda 8 instance that is the best way to get started.

export ZEEBE_REST_ADDRESS='http://localhost:8080'
export ZEEBE_GRPC_ADDRESS='grpc://localhost:26500'
export CAMUNDA_AUTH_STRATEGY=NONE

Self-Managed

This is the complete environment configuration needed to run against the Dockerised Self-Managed stack in the docker subdirectory:

# Self-Managed
export ZEEBE_GRPC_ADDRESS='grpc://localhost:26500'
export ZEEBE_REST_ADDRESS='http://localhost:8080'
export ZEEBE_CLIENT_ID='zeebe'
export ZEEBE_CLIENT_SECRET='zecret'
export CAMUNDA_OAUTH_STRATEGY='OAUTH'
export CAMUNDA_OAUTH_URL='http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token'
export CAMUNDA_TASKLIST_BASE_URL='http://localhost:8082'
export CAMUNDA_OPERATE_BASE_URL='http://localhost:8081'
export CAMUNDA_OPTIMIZE_BASE_URL='http://localhost:8083'
export CAMUNDA_MODELER_BASE_URL='http://localhost:8070/api'

# Turn off the tenant ID, which may have been set by multi-tenant tests
# You can set this in a constructor config, or in the environment if running multi-tenant
export CAMUNDA_TENANT_ID=''

If you are using an OIDC that requires a scope parameter to be passed with the token request, set the following variable:

CAMUNDA_TOKEN_SCOPE

Here is an example of doing this via the constructor, rather than via the environment:

import { Camunda8 } from '@camunda8/sdk'

const c8 = new Camunda8({
  ZEEBE_GRPC_ADDRESS: 'grpc://localhost:26500',
  ZEEBE_REST_ADDRESS: 'http://localhost:8080',
  ZEEBE_CLIENT_ID: 'zeebe',
  ZEEBE_CLIENT_SECRET: 'zecret',
  CAMUNDA_OAUTH_STRATEGY: 'OAUTH',
  CAMUNDA_OAUTH_URL:
    'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token',
  CAMUNDA_TASKLIST_BASE_URL: 'http://localhost:8082',
  CAMUNDA_OPERATE_BASE_URL: 'http://localhost:8081',
  CAMUNDA_OPTIMIZE_BASE_URL: 'http://localhost:8083',
  CAMUNDA_MODELER_BASE_URL: 'http://localhost:8070/api',
  CAMUNDA_TENANT_ID: '', // We can override values in the env by passing an empty string value
  CAMUNDA_SECURE_CONNECTION: false,
})

Camunda SaaS

Here is a complete configuration example for connection to Camunda SaaS:

export ZEEBE_GRPC_ADDRESS='grpcs://5c34c0a7-7f29-4424-8414-125615f7a9b9.syd-1.zeebe.camunda.io:443'
export ZEEBE_REST_ADDRESS='https://syd-1.zeebe.camunda.io/5c34c0a7-7f29-4424-8414-125615f7a9b9'
export ZEEBE_CLIENT_ID='yvvURO9TmBnP3zx4Xd8Ho6apgeiZTjn6'
export ZEEBE_CLIENT_SECRET='iJJu-SHgUtuJTTAMnMLdcb8WGF8s2mHfXhXutEwe8eSbLXn98vUpoxtuLk5uG0en'

export CAMUNDA_TASKLIST_BASE_URL='https://syd-1.tasklist.camunda.io/5c34c0a7-7f29-4424-8414-125615f7a9b9'
export CAMUNDA_OPTIMIZE_BASE_URL='https://syd-1.optimize.camunda.io/5c34c0a7-7f29-4424-8414-125615f7a9b9'
export CAMUNDA_OPERATE_BASE_URL='https://syd-1.operate.camunda.io/5c34c0a7-7f29-4424-8414-125615f7a9b9'
export CAMUNDA_OAUTH_URL='https://login.cloud.camunda.io/oauth/token'
export CAMUNDA_AUTH_STRATEGY='OAUTH'

# Admin Console and Modeler API Client
export CAMUNDA_CONSOLE_CLIENT_ID='e-JdgKfJy9hHSXzi'
export CAMUNDA_CONSOLE_CLIENT_SECRET='DT8Pe-ANC6e3Je_ptLyzZvBNS0aFwaIV'
export CAMUNDA_CONSOLE_BASE_URL='https://api.cloud.camunda.io'
export CAMUNDA_CONSOLE_OAUTH_AUDIENCE='api.cloud.camunda.io'

Logging

The SDK uses a Winston / Pino compatible logging setup. By default it uses Winston.

When using the default logging library, you can set the logging level of the SDK via the environment variable (or constructor configuration property) CAMUNDA_LOG_LEVEL. This defaults to 'info'. Values (in order of priority): error, warn, info, http, verbose, debug, silly.

Custom logger

You can supply a custom logger via the constructor. For example, to use the Pino logging library:

import pino from 'pino'

import { Camunda8 } from '@camunda8/sdk'

const level = process.env.CAMUNDA_LOG_LEVEL ?? 'trace'
const logger = pino({ level }) // Logging level controlled via the logging library

logger.info('Pino logger created')
const c8 = new Camunda8({
  logger,
})
c8.log.info('Using pino logger')

Awaiting Asynchronous Query Data

Camunda 8 uses an eventually-consistent data architecture. When you start a process instance, data related to this process instance is not immediately available in the datastore. This leads to data synchronisation issues you need to manage in your application. To aid you with this, the SDK provides a utility: PollingOperation. You can pass a query API operation to this utility with a polling interval and a timeout.

The PollingOperation will execute the query repeatedly until the expected data is available in the data store, or the timeout is reached.

The following example will return the query response for a newly-created process instance as soon as the element instance data is available:

import { Camunda8, PollingOperation } from '@camunda8/sdk'

const c8 = new Camunda8()

const elementInstances = await PollingOperation({
  operation: () =>
  c8.searchElementInstances({
    sort: [{ field: 'processInstanceKey' }],
    filter: {
      processInstanceKey: processInstance.processInstanceKey,
      type: 'SERVICE_TASK',
    },
  }),
  interval: 500,
  timeout: 10000,
})

By default, the PollingOperation waits for a query response from the Orchestration Cluster API that has one or more results in the items array. If you have a more specific predicate, or are using one of the v1 component APIs, you can pass in a custom predicate function.

The following example waits for a process instance to be available to a query over the Operate API:

import { Camunda8, PollingOperation } from '@camunda8/sdk'

const c8 = new Camunda8()
const c = c8.getOperateApiClient()

const process = await PollingOperation({
  operation: () => c.getProcessInstance(p.processInstanceKey),
  predicate: (res) => res.key === p.processInstanceKey,
  interval: 500,
  timeout: 15000,
})

Subscribing to queries

You can subscribe to queries using a QuerySubscription. This is an event emitter that emits a data event when new data is available. You pass a predicate function that takes a previous and current query result set. In this predicate function you can examine the two states to see whether or not to emit a data event, and also perform data-processing — for example, removing items that were emitted in the last update.

Note that this is an experimental feature and may change in future releases. We are looking for feedback on this feature, please report issues in the GitHub repo or via a JIRA ticket if you have an account with Camunda.

Here is an example of using QuerySubscription:

import { Camunda8, QuerySubscription } from '@camunda8/sdk'

const c8 = new Camunda8()

const query = () =>
 c8.searchProcessInstances({
  filter: {
    processDefinitionKey: key,
    state: 'ACTIVE',
  },
  sort: [{ field: 'startDate', order: 'ASC' }],
})

const subscription = QuerySubscription({
  query,
  predicate: (previous, current) => {
    // This is the default predicate, provided here as an example
    const previousItems = (previous?.items ?? []) as Array<unknown>
    const currentItems = current.items.filter(
        (item) =>
            !previousItems.some((prevItem) => isDeepStrictEqual(prevItem, item))
    )
    if (currentItems.length > 0) {
        return {
            ...current,
            items: currentItems,
            page: { ...current.page, totalItems: currentItems.length },
        }
    }
    return false // No new items, do not emit
  },
  interval: 5000,
  trackingWindow: 5, // Remember emitted items from last 5 poll cycles (default)
})

subscription.on('data', data => {
    // new process instances
})
//...
subscription.cancel() // close subscription and free resources
// You can also use subscription.pause() and subscription.resume() to pause and resume the subscription

Note:

  • QuerySubscription uses a rolling window approach to prevent memory leaks when tracking emitted items. By default, it remembers items from the last 5 poll cycles to prevent duplicates. You can adjust this with the trackingWindow parameter:
const subscription = QuerySubscription({
  query,
  predicate: myCustomPredicate,
  interval: 5000,
  trackingWindow: 10, // Remember items from the last 10 polling cycles
})

If you implement a custom predicate, your predicate determines what data should be emitted, and then the rolling window mechanism prevents duplicate emissions across multiple poll cycles.

Important: The rolling window mechanism operates by serializing each emitted item to a string and tracking it for the specified number of poll cycles. This means that if an entity changes state and then returns to a previous state within the tracking window timeframe, the second appearance in the original state might not trigger an emission. For example, if a process instance transitions from "READY" to "NOT_READY" and back to "READY" within the tracking window, the second "READY" state might not be emitted. If you need to track all state transitions regardless of previous states, consider:

  1. Setting a smaller trackingWindow value to reduce the tracking period
  2. Implementing a custom state tracking mechanism in your application
  3. Including a timestamp or version field in your item identification logic

Debugging

The SDK uses the debug library to help you debug specific issues. This produces verbose, low-level output from specific components to the console.

To enable debugging output, set a value for the DEBUG environment variable. The value is a comma-separated list of debugging namespaces. The SDK has the following namespaces:

Value Component
camunda:adminconsole Administration API
camunda:modeler Modeler API
camunda:operate Operate API
camunda:optimize Optimize API
camunda:tasklist Tasklist API
camunda:oauth OAuth Token Exchange
camunda:querySubscription QuerySubscription debugging
camunda:grpc Zeebe gRPC channel
camunda:worker Zeebe Worker
camunda:worker:verbose Zeebe Worker (additional detail)
camunda:zeebeclient Zeebe Client
camunda:orchestration-rest Camunda Orchestration Cluster API Client

Here is an example of turning on debugging for the OAuth and Operate components:

DEBUG=camunda:oauth,camunda:operate node app.js

This is intended for development debugging and it should not be enabled in production. The debug trace can include sensitive information such as secrets.

Diagnostic Trace file

You can output a diagnostic trace file to use with Camunda technical support by setting the environment variable CAMUNDA_SUPPORT_LOG_ENABLED to true. This will output a file camunda-support.log containing diagnostic information and tracing calls. This information is useful for debugging. Be aware that this log file will contain secrets such as bearer tokens, as well as exposing urls.

Process Variable Typing

Process variables - the variables of Zeebe messages, jobs, and process instance creation requests and responses - are stored in the broker as key:value pairs. They are transported as a JSON string. The SDK parses the JSON string into a JavaScript object.

Various Zeebe methods accept DTO classes for variable input and output. These DTO classes are used to provide design-time type information on the variables object. They are also used to safely decode 64-bit integer values that cannot be accurately represented by the JavaScript number type.

To create a DTO to represent the expected shape and type of the variables object, extend the LosslessDto class:

class myVariableDTO extends LosslessDto {
    firstName!: string
    lastName!: string
    age!: number
    optionalValue?: number
    @Int64String
    veryBigInteger?: string
    constructor(data: Partial<myVariableDTO>) {
        super(data)
    }
}

Typing of Zeebe worker variables

The variable payload in a Zeebe worker task handler is available as an object job.variables. By default, this is of type any for the gRPC API, and unknown for the REST API.

The ZBClient.createWorker() method accepts an inputVariableDto to control the parsing of number values and provide design-time type information. Passing an inputVariableDto class to a Zeebe worker is optional. If a DTO class is passed to the Zeebe worker, it is used for two purposes:

  • To provide design-time type information on the job.variables object.
  • To specify the parsing of JSON number fields. These can potentially represent int64 values that cannot be represented accurately by the JavaScript number type. With a DTO, you can specify that a specific JSON number fields be parsed losslessly to a string or BigInt.

With no DTO specified, there is no design-time type safety. At run-time, all JSON numbers are converted to the JavaScript number type. If a variable field has a number value that cannot be safely represented using the JavaScript number type (a value greater than 2^53 -1), an exception is thrown.

To provide a DTO, extend the LosslessDto class like so:

class MyVariableDto extends LosslessDto {
    name!: string
    maybeAge?: number
    @Int64String
    veryBigNumber!: string
    @BigIntValue
    veryBigInteger!: bigint
}

In this case, veryBigNumber is an int64 value. It is transferred as a JSON number on the wire, but the parser will parse it into a string so that no loss of precision occurs. Similarly, veryBigInteger is a very large integer value. In this case, we direct the parser to parse this variable field as a bigint.

You can nest DTOs like this:

class MyLargerDto extends LosslessDto {
    id!: string
    @ChildDto(MyVariableDto)
    entry!: MyVariableDto
}

Typing of custom headers

The Zeebe worker receives custom headers as job.customHeaders. The ZBClient.createWorker() method accepts a customHeadersDto to control the behavior of custom header parsing of number values and provide design-time type information.

This follows the same strategy as the job variables, as previously described.

Zeebe User Tasks

From 8.5, you can use Zeebe user tasks. See the documentation on how to migrate to Zeebe user tasks.

The SDK supports the Zeebe REST API. Be sure to set the ZEEBE_REST_ADDRESS either via environment variable or configuration field.

Job Streaming

The Zeebe gRPC API supports streaming available jobs, rather than polling for them.

The ZeebeGrpcClient method StreamJobs allows you to use this API.

Please note that only jobs that become available after the stream is opened are pushed to the client. For jobs that were already activatable before the method is called, you need to use a polling worker.

In this release, this is not handled for you. You must both poll and stream jobs to make sure that you get jobs that were available before your application started as well as jobs that become available after your application starts.

In a subsequent release, the ZeebeWorker will transparently handle this for you.

Multi-tenant workers

Workers, both polling and streaming, can be multi-tenanted, requesting jobs from more than one tenant.

Example:

client.createWorker({
    taskHandler: (job) => {
        console.log(job.tenantId) // '<default>' | 'green'
        return job.complete()
    },
    taskType: 'multi-tenant-work',
    tenantIds: ['<default>', 'green'],
})

client.streamJobs({
    taskHandler: async (job) => {
        console.log(job.tenantId) // '<default>' | 'green'
        return job.complete()
    },
    type: 'multi-tenant-stream-work',
    tenantIds: ['<default>', 'green'],
    worker: 'stream-worker',
    timeout: 2000,
})

Polling worker backoff in error conditions

When a polling worker encounters an error, including not being authenticated, the worker will back off subsequent polls by +2 seconds with each subsequent failure, up to a maximum of CAMUNDA_JOB_WORKER_MAX_BACKOFF_MS, which is 15000 by default (15 seconds). If the failure is due to invalid credentials and occurs during the token request, then the worker backoff will be compounded with a token endpoint backoff, which is +1000ms for each subsequent failure up to a maximum of 15s.

This means that if you start a worker with invalid credentials, then the polling backoff will look like this, by default (times in seconds): 3, 6, 9, 12, 15, 18, 21, 23, 24, 25, 26, 27, 28, 29, 30, 30, 30...

If the worker is backing off for a reason other than invalid credentials - for example a backpressure signal from the gateway - it will be: 2, 4, 6, 8, 10, 12, 14, 15, 15, 15.....

changelog

8.7.30 (2025-09-30)

Bug Fixes

  • add typed-emitter to deps (1b42edc)
  • allow explicit override of auth strategy (67031ab)
  • searchUserTasks signature expansion (7422e18)
  • set AUTH strategy to OAUTH if OAUTH url set (53185ed)
  • update DecisionEvaluation signatures (ca9c050)

Features

  • add default Operate and Tasklist urls (2d4acc0)

8.7.29 (2025-09-12)

Bug Fixes

  • update DecisionDeploymentDto (dafa72a)

8.7.28 (2025-08-06)

Features

  • support new runtimeInstructions field. fixes #472 (53bc43d)

8.7.27 (2025-07-31)

Bug Fixes

8.7.26 (2025-07-30)

Bug Fixes

  • docs: adjust variable names for cookie auth (a162005)

Features

  • add ability to override caching of clients. fixes #575 (d9c24c5)
  • add close() method to Rest Job Worker. Fixes #571 (da239fb)
  • allow configuration of default Camunda8 client caching behaviour (97d2a45)

8.7.25 (2025-07-29)

Bug Fixes

  • export SearchUsersRequest type (5c44ffe)

Features

8.7.24 (2025-07-25)

Features

8.7.23 (2025-07-22)

Bug Fixes

  • add missing fields to getDecisionInstance Response Dto. fixes #545 (2378d6b)

8.7.22 (2025-07-22)

Bug Fixes

  • fix QuerySubscription duplicate item emission. fixes #540 (8d61bcb)

Features

  • correctly handle backpressure 503 response. fixes #509 (7994b5f)
  • enable debugging for Camunda Rest Client (cba989f)
  • implement getDecisionInstance. fixes #293 (eea159d)
  • implement searchDecisionInstances. fixes #292 (83a7d7b)

Reverts

8.7.21 (2025-07-17)

Features

  • backoff retry on 429 "Too many client requests". FIxes #528 (63ea9ec)

8.7.20 (2025-07-16)

8.7.19 (2025-07-15)

Bug Fixes

Reverts

  • fix resetClock http method (5c2baad)

8.7.18 (2025-07-07)

Features

  • add stopWorkers and startWorkers methods. fixes #511 (69612a3)
  • implement searchIncidents. fixes #310 (e840d79)

8.7.17 (2025-06-18)

Bug Fixes

Features

8.7.16 (2025-06-11)

Bug Fixes

  • fix implementation of updateElementInstanceVariables. fixes #495 (6d36a8a)

Features

8.7.15 (2025-06-06)

Bug Fixes

  • destroy streams rather than removing all listeners. Fixes #466 (2d12170)

8.7.14 (2025-06-05)

Bug Fixes

  • prevent ZBLogger crash when stacktrace is undefined (d9b757f)

8.7.13 (2025-06-05)

Features

  • add getVariable to Rest API client. Fixes #344 (ecacfda)
  • add static method to OAuthProvider to clear file cache (754bc20)

8.7.12 (2025-06-04)

Bug Fixes

  • suppress cancelation error when worker is stopping. FIxes #432 (d4f313c)

8.7.11 (2025-05-30)

Bug Fixes

  • check the existing correlationKey first instead of using uuid() every time (1cebb44)

8.7.10 (2025-05-30)

Bug Fixes

  • do not remove stream listeners on stream end. fixes #466 (c0003bf)

8.7.9 (2025-05-27)

Features

  • add searchUsersForTenant (4438ad0)
  • add searchUsersForTenant (7d16d12)
  • camunda: implement searchUsers. fixes #338 (4a981f1)
  • camunda: implement searchUsers. fixes #338 (2f3ea0d)
  • enhance context output for ZeebeGrpcClient log messages. fixes #467 (2ababad)

8.7.8 (2025-05-16)

Features

  • add hinting for Rest errors. fixes #456 (cf34f57)
  • debug and trace support log infrastructure. fixes #457 (a8e3234)

8.7.7 (2025-05-12)

Bug Fixes

  • expose configuration in documentation. fixes #451 (55dc5d5)
  • refactor tests for configuration change (4b33ad4)

8.7.6 (2025-05-08)

Features

  • enable arbitrary headers on requests. fixes #448 (e07ab76)

8.7.5 (2025-05-07)

Features

  • allow dynamic update of Bearer token. fixes #445 (fda54f5)

8.7.4 (2025-05-05)

Bug Fixes

  • rename messageKey in PublishMessageResponse Dto (9ce67f6)
  • update documentation around TLS and mTLS configuration, fixes #395 (bcd4590)

8.7.3 (2025-05-05)

Bug Fixes

  • change CorrelateMessageResponse Dto. fixes #433 (c1f1fdc)
  • created self-signed cert valid for 100 years (4bdbab9)

Features

  • add Cookie auth to support c8run (1ee9ad1)

8.7.2 (2025-04-28)

Features

  • make activeJobs REST calls cancelable. fixes #424 (7cf5e6d)

8.7.1 (2025-04-23)

Features

  • add generic callApiEndpoint method (384161e)

8.7.0 (2025-04-16)

8.6.38 (2025-04-14)

Bug Fixes

  • camunda8: standardise on search for methods. closes #363 (3e4deaa)

Features

  • camunda8: implement evaluateDecision. closes #291 (ff7ac09)

8.6.37 (2025-04-10)

Features

  • camunda8: implement createDocumentLink. closes Implement Create Document link #300 (e46114c)
  • camunda8: implement modifyProcessInstance. closes Implement Modify process instance #321 (20ca335)
  • camunda8: implement uploadDocuments. closes Implement Upload multiple documents #404 (3f2ef14)

8.6.36 (2025-04-09)

Features

  • camunda8: implement deleteDocument. closes Implement Delete document #299 (18115c3)

8.6.35 (2025-04-09)

Bug Fixes

  • camunda8: change userTask method names and set explict return types (6fc8bee)

8.6.34 (2025-04-09)

Bug Fixes

  • camunda8: remove debugging console.error statement (b4fa2b0)

Features

  • camunda8: implement uploadDocument and downloadDocument. fixes #297, fixes #298 (b6b8b18)

8.6.33 (2025-03-17)

Bug Fixes

  • polling when maxJobsToActivate is reached (0dc7fe4)

8.6.32 (2025-03-06)

Bug Fixes

  • add tests and documentation for logging (3522faf), closes #397
  • operate: allow paging for getVariablesforProcess (b94532d), closes #387

8.6.31 (2025-03-05)

Bug Fixes

  • use ZEEBE_TOKEN_AUDIENCE if set (ac46921), closes #392

8.6.30 (2025-03-05)

Features

  • camunda8: support getUserTask (8.8) (26e0507)
  • camunda: implement getUserTaskVariables (6dd59f6), closes #342
  • camunda: implement searchProcessInstances. fixes #320 (bce0eb1)

8.6.29 (2025-03-04)

Bug Fixes

8.6.28 (2025-02-28)

Bug Fixes

  • camunda8: remove experimental decorator (809fe9b)

8.6.27 (2025-02-27)

Bug Fixes

  • camunda8: add optional tenantId to deployResourcesFromFiles (dff868e), closes #375

Features

  • camunda8: add queryVariables method. fixes #343 (b361d71)
  • camunda8: implement findUserTasks (d2baa70), closes #341
  • camunda: implement getUserTask. fixes #339 (8bcb59a)

8.6.26 (2025-02-26)

Bug Fixes

  • repo: close backoff timers on worker close (405595a)

Features

  • camunda: implement backoff on errors for REST job worker (4895942), closes #370

8.6.25 (2025-02-17)

Bug Fixes

  • zeebe: throw UNAUTHENTICATED error on ActivateJobs from stream.error event (d44029e), closes #378

8.6.24 (2025-02-12)

Features

  • zeebe: support 8.7 string entity keys (backwards-compatible with int64) (1ea31f0), closes #279

8.6.23 (2025-02-05)

Bug Fixes

  • oauth: pass out full auth header from getToken method (55a19b6), closes #367

8.6.22 (2025-02-04)

Features

  • zeebe: implement backoff on UNAUTHENTICATED error for workers (56c3c78), closes #366

8.6.21 (2025-01-24)

Bug Fixes

  • zeebe: move polling blocked log message to new verbose level. fixes #356 (62c1459)

8.6.20 (2025-01-23)

Bug Fixes

  • zeebe: catch exception in fail job on unhandled exception in job handler. fixes #351 (91e7213)
  • zeebe: do not fail jobs that are already not found (448575c)

8.6.19 (2025-01-23)

Bug Fixes

  • zeebe: propagate 'NOT_FOUND' error on job.complete(). fixes #351 (59ebf5d)

8.6.18 (2024-12-20)

Bug Fixes

  • modeler: update SaaS URL for Modeler (563e866)

8.6.17 (2024-12-19)

Bug Fixes

  • zeebe: update JS GPRC lib dependency, release stream resources on end (89fd95c)

8.6.16 (2024-11-15)

Features

  • authorization: add bearer token authorization (f7d1ff3)

8.6.15 (2024-10-24)

Bug Fixes

  • modeler: correct HTTP methods for file methods. fixes #269 (7819baa)

8.6.14 (2024-10-24)

Bug Fixes

  • camunda8: correctly parse autostart parameter of JobWorker (cb95946)
  • camunda8: type variables in async process instance start as never (3055734)
  • lossless-parser: correctly parse number array (d69729a), closes #258
  • lossless-parser: throw on encountering Date, Map, or Set (bb5d8ea), closes #254
  • zeebe: do not override explicit ZEEBE_GRPC_ADDRESS with default ZEEBE_ADDRESS (cd6080f), closes #245
  • zeebe: throw on client if array passed as variables to CompleteJob (40a6316), closes #247

Features

  • camunda8: add C8RestClient (8e93c92), closes #235
  • camunda8: add modifyAuthorization method (0d97f68)
  • camunda8: complete deployResources feature (8043ac9)
  • camunda8: implement createProcessInstanceWithResult (4ec4fa1)
  • camunda8: implement deleteResource over REST (1dcb101), closes #251
  • camunda8: implement deployResources REST API (debd212)
  • camunda8: implement publishMessage over REST (057a9fe), closes #250
  • camunda8: support broadcastSignal over REST (43f82a4), closes #248
  • camunda8: support pluggable winston logging for C8RestClient (d41d3f8)
  • camunda8: support updateElementInstanceVariables (7de82b7), closes #249
  • repo: support passing middleware (1b7715e), closes #261
  • zeebe: add operationReference field to gRPC methods (2e5af66), closes #237
  • zeebe: create and cancel process instances over REST (a49d217)
  • zeebe: lossless parse REST variables and customheaders (f19a252), closes #244

8.6.13 (2024-09-26)

Bug Fixes

  • operate: use post request for decision definitions and decision instances endpoints (419ae56)

8.6.12 (2024-08-30)

Bug Fixes

  • zeebe: fail job if variables cannot be parsed (495c05e), closes #236

8.6.11 (2024-08-21)

Bug Fixes

  • oauth: uri encode clientId and clientSecret (dd8583a), closes #230

8.6.10 (2024-07-29)

Bug Fixes

  • lossless-parser: correctly handle null in objects (b712651), closes #212

8.6.9 (2024-07-29)

Features

  • zeebe: add support for ZEEBE_INSECURE_CONNECTION env var (ed14df8)
  • zeebe: fix activate jobs stream (68bb5da)

8.6.8 (2024-07-12)

Bug Fixes

8.6.7 (2024-06-21)

Bug Fixes

  • docs: update config for disabling authentication (df5879f)

8.6.6 (2024-06-18)

Bug Fixes

  • optimize: fix exportReportDefinitions REST call path (e5f5da7), closes #192

8.6.5 (2024-06-18)

Bug Fixes

  • zeebe: add headers to all REST method calls (9b99177)

8.6.4 (2024-06-13)

Bug Fixes

  • optimize: fix labelVariables method (b8a4c68)

8.6.3 (2024-06-13)

Bug Fixes

  • specify the correct audience when getting an Optimize auth token (#185) (a852281)

8.6.2 (2024-06-12)

Bug Fixes

  • zeebe: security fix for grpc-js dependency update (#180) (f43d956)

Features

8.6.1-alpha.2 (2024-06-12)

Bug Fixes

  • zeebe: security fix for grpc-js dependency update (#180) (f43d956)

8.6.1 (2024-06-10)

8.6.1-alpha.1 (2024-06-07)

Features

8.6.0 (2024-06-05)

8.5.5-alpha.1 (2024-06-05)

Features

8.5.4 (2024-05-24)

Bug Fixes

  • issue137: support ZEEBE_REST_ADDRESS and ZEEBE_GRPC_ADDRESS environment variables (#159) (41fdca0)
  • oauth: correctly expire cached token (#164) (c86e550), closes #163

Features

  • camunda8: support Basic Auth (d6acdfd), closes #165
  • oauth: add conditional loading of client key and cert for getting a token (#161) (f05aa8a)
  • zeebe: support Zeebe User Task REST API (022607b), closes #34

8.5.4-alpha.2 (2024-05-22)

Bug Fixes

  • issue137: support ZEEBE_REST_ADDRESS and ZEEBE_GRPC_ADDRESS environment variables (#159) (41fdca0)
  • oauth: correctly expire cached token (#164) (c86e550), closes #163

Features

  • zeebe: support Zeebe User Task REST API (022607b), closes #34

8.5.4-alpha.1 (2024-05-15)

Features

  • oauth: add conditional loading of client key and cert for getting a token (#161) (f05aa8a)

8.5.3 (2024-05-08)

Bug Fixes

8.5.2 (2024-05-07)

Bug Fixes

  • zeebe: waitForReady deadline not miliseconds, but date (#148) (12db206)

Features

Reverts

  • Revert "fix(zeebe): waitForReady deadline not miliseconds, but date (#148)" (#149) (f8c0c7d), closes #148 #149

8.5.2-alpha.1 (2024-05-07)

Bug Fixes

Features

8.5.1 (2024-05-05)

Features

8.5.1-alpha.4 (2024-05-03)

Features

8.5.1-alpha.3 (2024-04-29)

Bug Fixes

  • tasklist: correct default value of includeVariables parameter in tasklist variables search (#136) (23af921)

8.5.1-alpha.2 (2024-04-20)

Features

8.5.1-alpha.1 (2024-04-09)

Features

  • repo: add stack traces to async REST errors (#131) (ef8d9c6)

8.5.0 (2024-04-08)

Bug Fixes

  • issue118: add smoke test and type surface tests (fe0c709), closes #118
  • repo: add note on "supported" (#107) (fc45d61), closes #70
  • repo: make fix type commits release a new package (ded83cf)
  • repo: only git commit on npm publish success (9012764)
  • repo: use ts-patch to transform module mapping in output (#112) (7efdcf3), closes #110

8.4.1 (2024-04-08)

Features

  • oauth: support optional scope in OAuth request (#25) (0451b80)
  • operate: add multitenant support and lossless Json parsing (#82) (cf49a71), closes #78 #67
  • repo: add enhanced debug output for http errors (#88) (881b039), closes #87
  • tasklist: add multitenant support to tasklist (#85) (46bb564)
  • zeebe: add MigrateProcessInstance (#97) (2a9a123), closes #49
  • zeebe: implement deleteResource (#73) (0cd08b7)
  • zeebe: implement lossless parsing of job payload (#95) (57f3ea8), closes #81
  • zeebe: normalise useragent, thread config (#94) (c1c4211)
  • zeebe: remove deployProcess method (#71) (6cb98f0)

8.5.0-alpha.6 (2024-04-08)

Bug Fixes

  • issue118: add smoke test and type surface tests (fe0c709), closes #118

8.5.0-alpha.5 (2024-04-07)

Bug Fixes

  • repo: make fix type commits release a new package (ded83cf)

8.5.0-alpha.4 (2024-04-05)

Bug Fixes

  • repo: use ts-patch to transform module mapping in output (#112) (7efdcf3), closes #110

8.5.0-alpha.3 (2024-04-05)

Bug Fixes

  • repo: only git commit on npm publish success (9012764)

8.5.0-alpha.2 (2024-04-05)

Bug Fixes

8.5.0-alpha.1 (2024-04-04)

Features

  • oauth: support optional scope in OAuth request (#25) (0451b80)
  • operate: add multitenant support and lossless Json parsing (#82) (cf49a71), closes #78 #67
  • repo: add enhanced debug output for http errors (#88) (881b039), closes #87
  • tasklist: add multitenant support to tasklist (#85) (46bb564)
  • zeebe: add MigrateProcessInstance (#97) (2a9a123), closes #49
  • zeebe: implement deleteResource (#73) (0cd08b7)
  • zeebe: implement lossless parsing of job payload (#95) (57f3ea8), closes #81
  • zeebe: normalise useragent, thread config (#94) (c1c4211)
  • zeebe: remove deployProcess method (#71) (6cb98f0)

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

8.4.0 (2024-02-01)

Bug Fixes

  • REST getForm returns a flattened shape of the form compared to GraphQL (58ec6d1)

Features

  • configure specs to import configuration from .env file (00804d1)
  • tasklist: enable multiple clusters via constructor options (#16) (fb12e25)