### Start Example Worker with Node.js

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/zeebe-extra/example/README.md

Run this command to start an example worker that can process Zeebe tasks.

```bash
node worker.js
```

--------------------------------

### Deploy Example Process with Node.js

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/zeebe-extra/example/README.md

Execute this command to deploy the example process to Zeebe.

```bash
node process.js
```

--------------------------------

### Install Dependencies

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Run this command to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Create Example Process Instances with Node.js

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/zeebe-extra/example/README.md

Use this command to create new instances of an example process in Zeebe.

```bash
node start-process-instance.js
```

--------------------------------

### Example Test Structure in TypeScript

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Illustrates a typical test structure using `describe`, `beforeAll`, and `it` blocks for testing client methods. Ensure setup and assertions are implemented within the respective blocks.

```typescript
describe('SomeClient.someMethod', () => {
	let client: SomeClient

	beforeAll(async () => {
		// Setup resources and client
	})

	it('should correctly handle the happy path', async () => {
		// Test implementation
		// Assert expected behavior
	})

	it('should handle error conditions', async () => {
		// Test error paths
		// Assert error handling
	})
})
```

--------------------------------

### Start Local Camunda Instance with Docker

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Use this command to start a local Camunda instance for integration testing using Docker Compose.

```bash
docker compose -f docker-compose-modeler.yaml -f docker-compose-multitenancy.yml up -d
```

--------------------------------

### Initialize Node.js Project with TypeScript

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Sets up a new Node.js project with TypeScript support. Ensure Node.js is installed.

```bash
npm init -y
npm install -D typescript
npx tsc --init
```

--------------------------------

### Initialize TypeScript project

Source: https://github.com/camunda/camunda-8-js-sdk/wiki/Minimal-Reproducer

Install TypeScript globally and initialize a tsconfig.json file for a new TypeScript project.

```bash
npm i -g typescript && tsc --init
```

--------------------------------

### Install Camunda 8 JS SDK

Source: https://github.com/camunda/camunda-8-js-sdk/wiki/Minimal-Reproducer

Install the official Camunda 8 JavaScript SDK using npm.

```bash
npm i @camunda8/sdk
```

--------------------------------

### Install Camunda Console Client

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/src/admin/README.md

Install the Camunda 8 Console API client for Node.js using npm.

```bash
npm i @camunda8/console
```

--------------------------------

### Initialize Camunda8 SDK with Zero-Configuration

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Instantiate the Camunda8 client without any explicit configuration. This method relies entirely on environment variables for setup.

```typescript
const camunda = new Camunda8()
```

--------------------------------

### Implement GET Entity by ID

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Example of implementing a GET endpoint to retrieve a specific entity by its ID. It utilizes the `callApiEndpoint` method with specified response type.

```typescript
// In CamundaRestClient.ts
/**
 * Gets an entity by ID
 * @param entityId The ID of the entity to retrieve
 * @returns An EntityDetails object with entity information
 */
async getEntity(entityId: string): Promise<EntityDetails> {
  return this.callApiEndpoint<UnknownRequestBody, EntityDetails>({
    method: 'get',
    path: `entities/${entityId}`,
  })
}
```

--------------------------------

### Configure Self-Managed Camunda 8 Connection via Constructor

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Instantiate the Camunda8 client with configuration options, overriding environment variables if necessary. This example demonstrates setting connection details, authentication, and base URLs programmatically.

```typescript
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,
})
```

--------------------------------

### Get Zeebe GRPC API Client

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Obtains a client instance for interacting with the Zeebe GRPC API. This client is used for deploying process models and starting process instances.

```typescript
const zeebe = camunda.getZeebeGrpcApiClient()
```

--------------------------------

### Backport Action Example

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/MAINTAINER.md

This workflow uses the `korthout/backport-action` to create backport pull requests. It is triggered by a '/backport' comment on a PR.

```yaml
backport:
    runs-on: ubuntu-latest
    steps:
      - uses: korthout/backport-action@v2
        id: backport
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          use_git_tag: false
          update_commit_message: true
          fetch_depth: 0
```

--------------------------------

### Development Environment Management

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Scripts to manage Docker Compose for Self-Managed Camunda 8 instances, including starting and stopping specific versions.

```bash
npm run sm:start
```

```bash
npm run sm:stop
```

```bash
npm run sm:start:8.8
```

```bash
npm run sm:stop:8.8
```

```bash
npm run sm:start:8.9
```

```bash
npm run sm:stop:8.9
```

--------------------------------

### Implement GET REST API Endpoint

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Use this pattern to implement GET requests for specific resources. Ensure DTOs are defined and decorators like `@Int64String` are used for int64 fields.

```typescript
/**
 * Gets a specific decision instance by ID
 * @param decisionInstanceId The ID of the decision instance to retrieve
 * @returns A GetDecisionInstanceResponse object with the decision instance details
 */
async getDecisionInstance(
  decisionInstanceId: string
): Promise<GetDecisionInstanceResponse> {
  return this.callApiEndpoint({
    method: 'get',
    path: `decision-instances/${decisionInstanceId}`,
    responseType: GetDecisionInstanceResponse,
  })
}
```

--------------------------------

### Get Entity

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Retrieves a specific entity by its ID. This method demonstrates a common GET endpoint pattern, including request DTOs and response handling.

```APIDOC
## GET /entities/{entityId}

### Description
Gets an entity by ID.

### Method
GET

### Endpoint
`/entities/{entityId}`

### Parameters
#### Path Parameters
- **entityId** (string) - Required - The ID of the entity to retrieve.

### Response
#### Success Response (200)
- Returns an `EntityDetails` object with entity information.
```

--------------------------------

### Get Tasklist API Client

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Obtains a client instance for interacting with the Tasklist API. This client allows programmatic interaction with user tasks.

```typescript
const tasklist = camunda.getTasklistApiClient()
```

--------------------------------

### Integration Test Matrix Trigger Configuration

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/MAINTAINER.md

This YAML configuration defines scheduled triggers for running the integration test matrix. It includes examples for different stable branches.

```yaml
on:
  schedule:
    - cron: '0 2 * * *'
  workflow_dispatch:
jobs:
  trigger-stable-8-8:
    uses: ./.github/workflows/integration-test-matrix.yml
    with:
      ref: 'stable/8.8'
  trigger-stable-8-9:
    uses: ./.github/workflows/integration-test-matrix.yml
    with:
      ref: 'stable/8.9'
```

--------------------------------

### Get Operate API Client

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Obtains a client instance for interacting with the Operate API. This client is used to query completed processes and deployed process models.

```typescript
const operate = camunda.getOperateApiClient()
```

--------------------------------

### Initialize npm project

Source: https://github.com/camunda/camunda-8-js-sdk/wiki/Minimal-Reproducer

Use npm init with the -y flag to quickly initialize a new Node.js project with default settings.

```bash
npm init -y
```

--------------------------------

### Configure Basic Authentication

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Set these environment variables for Basic Authentication. Provide both username and password.

```bash
CAMUNDA_AUTH_STRATEGY=BASIC
CAMUNDA_BASIC_AUTH_USERNAME=....
CAMUNDA_BASIC_AUTH_PASSWORD=...
```

--------------------------------

### Configure Camunda SaaS Connection via Environment Variables

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Set these environment variables to establish a connection to Camunda SaaS. Ensure all required addresses and credentials are correctly provided.

```bash
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'
```

--------------------------------

### Run Integration Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Execute integration tests by sourcing the appropriate environment file before running Vitest.

```bash
. env/8.8-alpha.env && npx vitest run --testTimeout=30000 ${testFile}
```

--------------------------------

### Get Decision Instance

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Retrieves a specific decision instance by its ID. This method is part of the client class and utilizes the `callApiEndpoint` pattern.

```APIDOC
## GET /decision-instances/{decisionInstanceId}

### Description
Gets a specific decision instance by ID.

### Method
GET

### Endpoint
`/decision-instances/{decisionInstanceId}`

### Parameters
#### Path Parameters
- **decisionInstanceId** (string) - Required - The ID of the decision instance to retrieve.

### Response
#### Success Response (200)
- Returns a `GetDecisionInstanceResponse` object with the decision instance details.
```

--------------------------------

### Run Integration Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Execute integration tests against Camunda SaaS. Ensure you have API client credentials configured.

```bash
npm run test:integration
```

--------------------------------

### Initialize and Use ConsoleApiClient

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/src/admin/README.md

Initialize the ConsoleApiClient and fetch clusters and parameters. Ensure Camunda SaaS Console credentials are set in the environment.

```typescript
import { ConsoleApiClient } from '@camunda8/console'

const console = new ConsoleApiClient()

async function main() {
	const res = await console.getClusters()
	console.log(res)
	const params = await console.getParameters()
	console.log(params)
}

main()
```

--------------------------------

### Run JavaScript reproducer

Source: https://github.com/camunda/camunda-8-js-sdk/wiki/Minimal-Reproducer

Execute a JavaScript minimal reproducer using Node.js.

```bash
node index.js
```

--------------------------------

### Run Unit Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Execute unit tests using Vitest. Ensure the correct environment variables are sourced.

```bash
. env/unit-test.env && CAMUNDA_UNIT_TEST=true npx vitest run --testTimeout=30000 ${testFile}
```

--------------------------------

### DTO Class Definition

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Example of a Data Transfer Object (DTO) class extending LosslessDto, utilizing the @Int64String decorator for int64 fields.

```typescript
export class SomeEntityDto extends LosslessDto {
	@Int64String
	entityKey!: string
	name!: string
	// Other fields...
}
```

--------------------------------

### Create Process Instance with Strict and Loose Orchestration Clients

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Demonstrates creating a process instance using both the strict (strongly typed) and loose (string-based) Orchestration Cluster API clients. The strict client uses branded types like ProcessDefinitionId, while the loose client uses plain strings.

```typescript
import { Camunda8 } from '@camunda8/sdk'
const c8 = new Camunda8()

// Strict client (preferred once migrated)
const oca = c8.getOrchestrationClusterApiClient()
const proc = await oca.createProcessInstance({
  processDefinitionId: ProcessDefinitionId.assumeExists('order-process'),
  variables: { orderId: 'A123' },
})
// proc.processInstanceKey is a branded type (not a plain string)

// Loose client (progressive adoption)
const ocaLoose = c8.getOrchestrationClusterApiClientLoose()
const procLoose = await ocaLoose.createProcessInstance({
  processDefinitionId: 'order-process',
  variables: { orderId: 'B456' },
})
// procLoose.processInstanceKey is a plain string
```

--------------------------------

### Run Local Integration Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Execute the local integration tests using npm after configuring the environment variables. This command verifies the SDK's functionality against a self-managed Camunda instance.

```bash
npm run test:local-integration
```

--------------------------------

### Run Multi-tenancy Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Execute the multi-tenancy integration tests using npm after setting the appropriate environment variables. This command ensures multi-tenancy configurations are working correctly.

```bash
npm run test:multitenancy
```

--------------------------------

### Disable Secure Connection for Self-Managed

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Disables TLS/SSL for the connection to Zeebe when running a self-managed instance without TLS enabled. Use this only if your setup does not use secure connections.

```bash
export CAMUNDA_SECURE_CONNECTION=false
```

--------------------------------

### Camunda Process Model XML

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

The XML definition for a simple Camunda process model including a start event, service task, user task, and end event.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:modeler="http://camunda.org/schema/modeler/1.0" id="Definitions_14f3xb6" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.8.0" modeler:executionPlatform="Camunda Cloud" modeler:executionPlatformVersion="8.1.0">
  <bpmn:process id="c8-sdk-demo" name="C8 SDK Demo" isExecutable="true">
    <bpmn:startEvent id="StartEvent_1">
      <bpmn:outgoing>Flow_0yqo0wz</bpmn:outgoing>
    </bpmn:startEvent>
    <bpmn:sequenceFlow id="Flow_0yqo0wz" sourceRef="StartEvent_1" targetRef="Activity_1gwbbuy" />
    <bpmn:sequenceFlow id="Flow_0qugen1" sourceRef="Activity_1gwbbuy" targetRef="Activity_0tp91ve" />
    <bpmn:endEvent id="Event_0j28rou">
      <bpmn:incoming>Flow_03qgl0x</bpmn:incoming>
    </bpmn:endEvent>
    <bpmn:sequenceFlow id="Flow_03qgl0x" sourceRef="Activity_0tp91ve" targetRef="Event_0j28rou" />
    <bpmn:serviceTask id="Activity_1gwbbuy" name="Do the service thing">
      <bpmn:extensionElements>
        <zeebe:taskDefinition type="service-task" />
      </bpmn:extensionElements>
      <bpmn:incoming>Flow_0yqo0wz</bpmn:incoming>
      <bpmn:outgoing>Flow_0qugen1</bpmn:outgoing>
    </bpmn:serviceTask>
    <bpmn:userTask id="Activity_0tp91ve" name="Human, do something!">
      <bpmn:incoming>Flow_0qugen1</bpmn:incoming>
      <bpmn:outgoing>Flow_03qgl0x</bpmn:outgoing>
    </bpmn:userTask>
  </bpmn:process>
  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="c8-sdk-demo">
      <bpmndi:BPMNShape id="_BPMNShape_StartEvent_2" bpmnElement="StartEvent_1">
        <dc:Bounds x="179" y="99" width="36" height="36" />
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="Event_0j28rou_di" bpmnElement="Event_0j28rou">
        <dc:Bounds x="592" y="99" width="36" height="36" />
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="Activity_1rvlo9s_di" bpmnElement="Activity_1gwbbuy">
        <dc:Bounds x="270" y="77" width="100" height="80" />
        <bpmndi:BPMNLabel />
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="Activity_1wxn0pq_di" bpmnElement="Activity_0tp91ve">
        <dc:Bounds x="430" y="77" width="100" height="80" />
        <bpmndi:BPMNLabel />
      </bpmndi:BPMNShape>
      <bpmndi:BPMNEdge id="Flow_0yqo0wz_di" bpmnElement="Flow_0yqo0wz">
        <di:waypoint x="215" y="117" />
        <di:waypoint x="270" y="117" />
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="Flow_0qugen1_di" bpmnElement="Flow_0qugen1">
        <di:waypoint x="370" y="117" />
        <di:waypoint x="430" y="117" />
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="Flow_03qgl0x_di" bpmnElement="Flow_03qgl0x">
        <di:waypoint x="530" y="117" />
        <di:waypoint x="592" y="117" />
      </bpmndi:BPMNEdge>
    </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>
</bpmn:definitions>
```

--------------------------------

### Configure OAuth with Environment Variables

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Set these environment variables for OAuth authentication with Camunda SaaS or Self-Managed Identity. Ensure all required fields are provided.

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

--------------------------------

### Configure Local Integration Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Set environment variables to configure the SDK for local integration tests against a self-managed Camunda instance. Ensure all necessary addresses and credentials are correctly set.

```bash
export ZEEBE_SECURE_CONNECTION=false
export ZEEBE_GRPC_ADDRESS='localhost:26500'
export ZEEBE_REST_ADDRESS='localhost:8080/v1/'
export ZEEBE_CLIENT_ID='zeebe'
export ZEEBE_CLIENT_SECRET='zecret'
export ZEEBE_AUTHORIZATION_SERVER_URL='http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token'
export ZEEBE_TOKEN_AUDIENCE='zeebe.camunda.io'
export CAMUNDA_CREDENTIALS_SCOPES='Zeebe,Tasklist,Operate,Optimize'
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:8086'
export CAMUNDA_MODELER_OAUTH_AUDIENCE='_omit_'
export CAMUNDA_TENANT_ID=''

export CAMUNDA_TEST_TYPE='local'
```

--------------------------------

### Configure Camunda SaaS Environment Variables

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Sets environment variables for connecting to Camunda SaaS. These include GRPC and REST addresses, client credentials, and base URLs for SaaS services. Ensure you replace the placeholder values with your actual secrets and URLs.

```bash
export ZEEBE_GRPC_ADDRESS='5c34c0a7-...-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='yvvURO...'
export ZEEBE_CLIENT_SECRET='iJJu-SHg...'
export CAMUNDA_TASKLIST_BASE_URL='https://syd-1.tasklist.camunda.io/5c34c0a7-...-125615f7a9b9'
export CAMUNDA_OPTIMIZE_BASE_URL='https://syd-1.optimize.camunda.io/5c34c0a7-...-125615f7a9b9'
export CAMUNDA_OPERATE_BASE_URL='https://syd-1.operate.camunda.io/5c34c0a7-...-125615f7a9b9'
export CAMUNDA_OAUTH_URL='https://login.cloud.camunda.io/oauth/token'
export CAMUNDA_SECURE_CONNECTION=true
```

--------------------------------

### Import and Initialize Camunda8 SDK

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Imports the Camunda8 class from the SDK and initializes a new instance. This instance will use environment variables for configuration by default.

```typescript
import { Camunda8 } from '@camunda8/sdk'
import path from 'path' // we'll use this later

const camunda = new Camunda8()
```

--------------------------------

### Configure OAuth for Camunda SaaS Admin/Modeler APIs

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Use these environment variables to obtain tokens for the Camunda SaaS Administration API or Modeler API.

```bash
CAMUNDA_AUTH_STRATEGY=OAUTH
CAMUNDA_CONSOLE_CLIENT_ID=...
CAMUNDA_CONSOLE_CLIENT_SECRET=...
```

--------------------------------

### Run Unit Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Execute all unit tests to ensure code quality and functionality.

```bash
npm test
```

--------------------------------

### Format Code

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Run the format command to automatically format the code according to the project's standards. This ensures a consistent code style.

```bash
npm run format
```

--------------------------------

### Documentation Generation

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Commands to generate TypeDoc documentation, with an option to watch for changes.

```bash
npm run docs
```

```bash
npm run docs:watch
```

--------------------------------

### Set Environment Credentials for Self-Managed Instance

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Configure environment variables with credentials for connecting to a Self-Managed Camunda instance.

```bash
export CAMUNDA_OPERATE_BASE_URL=http://localhost:8300
export CAMUNDA_OPERATE_CLIENT_ID=operate
export CAMUNDA_OPERATE_CLIENT_SECRET=operate
export CAMUNDA_TASKLIST_BASE_URL=http://localhost:8081
export CAMUNDA_TASKLIST_CLIENT_ID=tasklist
export CAMUNDA_TASKLIST_CLIENT_SECRET=tasklist
export CAMUNDA_ZEEBE_ADDRESS=localhost:26500
```

--------------------------------

### Build and Compile TypeScript

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Use these commands to clean, compile TypeScript, and copy proto files for the SDK. The `compile` command specifically transpiles TypeScript to JavaScript.

```bash
npm run build          # Clean, compile TypeScript, copy proto files
```

```bash
npm run clean          # Remove dist folder and build artifacts
```

```bash
npm run compile        # Compile TypeScript to JavaScript
```

--------------------------------

### Initialize Camunda 8 SDK Clients

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Instantiate the Camunda8 client and obtain clients for the Orchestration Cluster API. Use the strict client for new projects on 8.8.0+ or the loose client for progressive adoption in existing codebases.

```typescript
import { Camunda8 } from '@camunda8/sdk'

const c8 = new Camunda8()

// Camunda 8 Orchestration Cluster API (STRICT client) - recommended from 8.8.0
// Provides strongly typed request & response IDs (e.g. ProcessInstanceKey, ProcessDefinitionId)
const orchestration = c8.getOrchestrationClusterApiClient()

// Camunda 8 Orchestration Cluster API (LOOSE client) - progressive adoption variant
// Same methods, but all IDs are plain string. Start here in existing codebases, then
// migrate to the strict client when convenient.
const orchestrationLoose = c8.getOrchestrationClusterApiClientLoose()
```

--------------------------------

### Enable Debugging for Camunda SDK Components

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Set the DEBUG environment variable to a comma-separated list of namespaces to enable verbose logging from specific SDK components. This is useful for development but should not be used in production due to potential exposure of sensitive information.

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

--------------------------------

### Configure Camunda 8 Run Connection

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Set environment variables to configure the connection to a local Camunda 8 Run instance. This includes addresses for REST and gRPC, and disabling authentication.

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

--------------------------------

### Deploy Process Model with Camunda 8 JS SDK

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Deploys a BPMN process model to Camunda. Ensure the process model file exists at the specified path. Network operations are asynchronous and return Promises.

```typescript
async function main() {
	const deploy = await zeebe.deployResource({
		processFilename: path.join(process.cwd(), 'process.bpmn'),
	})
	console.log(
		`[Zeebe] Deployed process ${deploy.deployments[0].process.bpmnProcessId}`
	)
}

main() // remember to invoke the function
```

--------------------------------

### Configure Cookie Authentication

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Set the authentication strategy to COOKIE for C8Run. Optional values for URL, username, and password are provided with defaults.

```bash
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
```

--------------------------------

### Lint Code with ESLint

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Run the linting command to check code for style and potential errors using ESLint. This helps maintain code quality and consistency across the project.

```bash
npm run lint
```

--------------------------------

### Configure Multi-tenancy Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/CONTRIBUTING.md

Set environment variables for multi-tenancy integration tests against a self-managed Camunda instance. This includes specifying a tenant ID for testing multi-tenancy features.

```bash
# Self-Managed
export ZEEBE_SECURE_CONNECTION=false
export ZEEBE_GRPC_ADDRESS='localhost:26500'
export ZEEBE_REST_ADDRESS='localhost:8080/v1/'
export ZEEBE_CLIENT_ID='zeebe'
export ZEEBE_CLIENT_SECRET='zecret'
export ZEEBE_AUTHORIZATION_SERVER_URL='http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token'
export ZEEBE_TOKEN_AUDIENCE='zeebe.camunda.io'
export CAMUNDA_CREDENTIALS_SCOPES='Zeebe,Tasklist,Operate,Optimize'
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_TEST_TYPE='local'
export CAMUNDA_TENANT_ID='<default>'
```

--------------------------------

### Run Unit and Integration Tests

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Execute various test suites including unit tests, smoke tests, and integration tests for different Camunda 8 versions and configurations (SaaS, self-managed, multi-tenancy).

```bash
npm test               # Run unit tests only (CAMUNDA_UNIT_TEST=true)
```

```bash
npm run test:smoketest # Build + smoke test + tsd typings check
```

```bash
npm run test:8.8:sm    # 8.8 self-managed integration
```

```bash
npm run test:8.8:saas  # 8.8 SaaS integration
```

```bash
npm run test:8.7:sm    # 8.7 self-managed integration
```

```bash
npm run test:8.7:mt    # 8.7 multi-tenancy integration
```

```bash
npm run test:8.7:saas  # 8.7 SaaS integration
```

```bash
npm run test:c8run     # C8Run integration
```

--------------------------------

### Subscribe to Process Instances with QuerySubscription

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Use QuerySubscription to subscribe to real-time updates of process instances. It emits 'data' events when new or changed data is available based on the provided predicate. Ensure necessary imports and initialize the Camunda8 client.

```typescript
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
```

--------------------------------

### Run TypeScript reproducer

Source: https://github.com/camunda/camunda-8-js-sdk/wiki/Minimal-Reproducer

Execute a TypeScript minimal reproducer using ts-node.

```bash
npx ts-node index.ts
```

--------------------------------

### Configure Self-Managed Camunda 8 Connection

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Set environment variables for a complete self-managed Camunda 8 Dockerized stack configuration. This includes gRPC and REST addresses, client credentials, OAuth settings, and base URLs for various Camunda components.

```bash
# 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=''
```

--------------------------------

### Configure Multi-Tenancy for Self-Managed

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Sets the tenant ID for multi-tenancy environments in self-managed Camunda 8. Replace '<default>' with your specific tenant identifier.

```bash
export CAMUNDA_TENANT_ID='<default>'
```

--------------------------------

### Cut a New Stable Branch

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/MAINTAINER.md

Use these bash commands to create a new stable branch from main and push it to origin. This is the first step in promoting a new minor version.

```bash
git checkout main
git checkout -b stable/8.9
git push -u origin stable/8.9
```

--------------------------------

### Configure Self-Managed Environment Variables

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Sets environment variables for connecting to a self-managed Camunda 8 instance. These variables define addresses, authentication credentials, and base URLs for various Camunda services.

```bash
# Self-Managed
export ZEEBE_GRPC_ADDRESS='localhost:26500'
export ZEEBE_REST_ADDRESS='localhost:8080/v1/'
export ZEEBE_CLIENT_ID='zeebe'
export ZEEBE_CLIENT_SECRET='zecret'
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'
```

--------------------------------

### Create a Process Instance with Result

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

This code creates a new process instance and waits for its completion, returning the final process variables. Use this for shorter-running processes where you need the outcome.

```typescript
const p = await zbc.createProcessInstanceWithResult({
	bpmnProcessId: `c8-sdk-demo`,
	variables: {
		humanTaskStatus: 'Needs doing',
	},
})
console.log(`[Zeebe] Finished Process Instance ${p.processInstanceKey}`)
console.log(`[Zeebe] humanTaskStatus is "${p.variables.humanTaskStatus}"`) 
console.log(`[Zeebe] serviceTaskOutcome is "${p.variables.serviceTaskOutcome}"`) 
```

--------------------------------

### Mock Zeebee Client Options with Log Level

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/src/__tests__/zeebe/__mocks__/zbClientOptions.ts.txt

Defines mock client options with a private log level property and public getter/setter. Use this for testing interactions with the Zeebee client's log level.

```typescript
import { Loglevel } from '../../../zeebe/lib/interfaces-published-contract'

export const clientOptions = {
	_loglevel: 'NONE' as Loglevel,
	// it's a setter!
	set loglevel(value: Loglevel) {
		this._loglevel = value
	},
	get loglevel(): Loglevel {
		return this._loglevel
	},
}
```

--------------------------------

### Export ZEEBE_REST_ADDRESS with version suffix

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

If the ZEEBE_REST_ADDRESS environment variable already includes the '/v2' suffix, it will be preserved. Trailing slashes are automatically stripped before normalization.

```bash
export ZEEBE_REST_ADDRESS='http://localhost:8888/v2'
```

--------------------------------

### Specify Custom Token Cache Directory

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Provide a full file path for this environment variable to specify a custom directory for the token cache. The SDK will attempt to create the directory if it doesn't exist.

```typescript
import { Camunda8 } from '@camunda8/sdk'

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

--------------------------------

### Stream Jobs with Custom Options

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Use `streamJobs` to activate jobs via gRPC streaming. Configure optional parameters like `jitter` for staggered startup, `pollMaxJobsToActivate` for batch size, and `pollInterval` for sidecar polling frequency. Defaults are provided for most options.

```typescript
client.streamJobs({
	type: 'payment-service',
	worker: 'my-worker',
	timeout: 30000,
	tenantIds: ['<default>'],
	taskHandler: async (job) => {
		// business logic
		return job.complete()
	},
	// Optional: stagger startup across workers
	jitter: 2000,
	// Optional: control poll batch size (default: 32)
	pollMaxJobsToActivate: 64,
	// Optional: sidecar poll every 60 s instead of the default 30 s
	pollInterval: 60_000,
})
```

--------------------------------

### Implement Search REST API Endpoint

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Implement search endpoints using POST requests with cursor-based pagination. The request body should be an instance of the search request DTO.

```typescript
// In CamundaRestClient.ts
/**
 * Search for entities
 * @param request The search request with filters and sorting options
 * @returns A paginated response with entity details
 */
async searchEntities(
  request: SearchEntitiesRequest
): Promise<CamundaRestSearchEntitiesResponse> {
  return this.callApiEndpoint<SearchEntitiesRequest, CamundaRestSearchEntitiesResponse>({
    method: 'post',
    path: 'entities/search',
    body: request,
  })
}
```

--------------------------------

### Retrieve a Process Instance

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/QUICKSTART.md

Fetches historical details of a completed process instance using its key from the Operate API. This demonstrates how to query process instance status after completion.

```typescript
const historicalProcessInstance = await operate.getProcessInstance(
	p.processInstanceKey
)
console.log('[Operate]', historicalProcessInstance)
```

--------------------------------

### Integrate Custom Pino Logger with Camunda 8 SDK

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Supply a custom logger instance to the Camunda8 constructor for enhanced logging control. The logging level can be managed via environment variables or the logger's configuration.

```typescript
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')
```

--------------------------------

### Implement Advanced Custom Headers with IOAuthProvider

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Implement the IOAuthProvider interface to add arbitrary headers to all requests. The getToken method can manage token lifecycles and return custom headers.

```typescript
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 })
```

--------------------------------

### Force a Release with Empty Commit

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/MAINTAINER.md

Use this command to push an empty commit with a release type to trigger a release, useful for shipping pending chore work without code changes.

```bash
git commit --allow-empty -m "release: ship pending chore work"
git push
```

--------------------------------

### Create Multi-Tenant Streaming Worker

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/README.md

Configure a streaming worker to receive jobs from multiple tenants by providing an array of `tenantIds` to `streamJobs`. The `taskHandler` can access the `tenantId` from the job object.

```typescript
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,
})
```

--------------------------------

### Code Quality Checks

Source: https://github.com/camunda/camunda-8-js-sdk/blob/main/AGENT.md

Commands for linting and formatting TypeScript code using ESLint and Prettier.

```bash
npm run lint
```

```bash
npm run format
```

```bash
npx prettier --write 'src/${filename}'
```

```bash
npx eslint 'src/${filename}'
```