@camunda8/sdk 8.4.0 → 8.4.1

package/.eslintrc.json

@@ -0,0 +1,34 @@
+{
+	"parser": "@typescript-eslint/parser",
+	"plugins": ["@typescript-eslint", "import", "prettier"],
+	"extends": [
+		"eslint:recommended",
+		"plugin:@typescript-eslint/recommended",
+		"prettier",
+		"plugin:prettier/recommended"
+	],
+	"ignorePatterns": ["dist/"],
+	"rules": {
+		// Define your rules, for example:
+		"semi": "off",
+		"import/order": [
+			"error",
+			{
+				"groups": [
+					"builtin",
+					"external",
+					"internal",
+					"parent",
+					"sibling",
+					"index"
+				],
+				"newlines-between": "always"
+			}
+		],
+		"import/newline-after-import": "error",
+		"prettier/prettier": "error"
+	},
+	"env": {
+		"node": true
+	}
+}

package/CHANGELOG.md

@@ -1,40 +1,80 @@
-# Change Log
+## [8.4.1](https://github.com/camunda/camunda-8-js-sdk/compare/v8.4.0...v8.4.1) (2024-04-08)
 
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-# 8.4.0 (2024-02-01)
+### Features
+
+* **oauth:** support optional scope in OAuth request ([#25](https://github.com/camunda/camunda-8-js-sdk/issues/25)) ([0451b80](https://github.com/camunda/camunda-8-js-sdk/commit/0451b802594f76518830b9bdff515d67fc0231b9))
+* **operate:** add multitenant support and lossless Json parsing ([#82](https://github.com/camunda/camunda-8-js-sdk/issues/82)) ([cf49a71](https://github.com/camunda/camunda-8-js-sdk/commit/cf49a717e2632af845529b3c1fde85ee1b0b347b)), closes [#78](https://github.com/camunda/camunda-8-js-sdk/issues/78) [#67](https://github.com/camunda/camunda-8-js-sdk/issues/67)
+* **repo:** add enhanced debug output for http errors ([#88](https://github.com/camunda/camunda-8-js-sdk/issues/88)) ([881b039](https://github.com/camunda/camunda-8-js-sdk/commit/881b03965cc37431885a76291f7c0aa762f26227)), closes [#87](https://github.com/camunda/camunda-8-js-sdk/issues/87)
+* **tasklist:** add multitenant support to tasklist ([#85](https://github.com/camunda/camunda-8-js-sdk/issues/85)) ([46bb564](https://github.com/camunda/camunda-8-js-sdk/commit/46bb564365afc3bc6758cd436490a459708128e6))
+* **zeebe:** add MigrateProcessInstance ([#97](https://github.com/camunda/camunda-8-js-sdk/issues/97)) ([2a9a123](https://github.com/camunda/camunda-8-js-sdk/commit/2a9a1232b160962f86b9450edd9047a8a933068a)), closes [#49](https://github.com/camunda/camunda-8-js-sdk/issues/49)
+* **zeebe:** implement deleteResource ([#73](https://github.com/camunda/camunda-8-js-sdk/issues/73)) ([0cd08b7](https://github.com/camunda/camunda-8-js-sdk/commit/0cd08b7b85d23ab44e42b36b2d9b48c1cfcb8c63))
+* **zeebe:** implement lossless parsing of job payload ([#95](https://github.com/camunda/camunda-8-js-sdk/issues/95)) ([57f3ea8](https://github.com/camunda/camunda-8-js-sdk/commit/57f3ea85d4cf86256301f5f2a9bcead09c01a199)), closes [#81](https://github.com/camunda/camunda-8-js-sdk/issues/81)
+* **zeebe:** normalise useragent, thread config ([#94](https://github.com/camunda/camunda-8-js-sdk/issues/94)) ([c1c4211](https://github.com/camunda/camunda-8-js-sdk/commit/c1c4211db11173c56d2410f489503ef9acf185f2))
+* **zeebe:** remove deployProcess method ([#71](https://github.com/camunda/camunda-8-js-sdk/issues/71)) ([6cb98f0](https://github.com/camunda/camunda-8-js-sdk/commit/6cb98f0ff3baf643015bacfa690f4f119caf6083))
+
+# [8.5.0-alpha.6](https://github.com/camunda/camunda-8-js-sdk/compare/v8.5.0-alpha.5...v8.5.0-alpha.6) (2024-04-08)
+
+
+### Bug Fixes
+
+* **issue118:** add smoke test and type surface tests ([fe0c709](https://github.com/camunda/camunda-8-js-sdk/commit/fe0c70925cf3df610b049e776eed5bffe56ef604)), closes [#118](https://github.com/camunda/camunda-8-js-sdk/issues/118)
+
+# [8.5.0-alpha.5](https://github.com/camunda/camunda-8-js-sdk/compare/v8.5.0-alpha.4...v8.5.0-alpha.5) (2024-04-07)
+
+
+### Bug Fixes
 
-**Note:** Version bump only for package @camunda8/sdk
+* **repo:** make fix type commits release a new package ([ded83cf](https://github.com/camunda/camunda-8-js-sdk/commit/ded83cfaf437a2f62a5ef134d7616538facda614))
 
-# CHANGELOG
+# [8.5.0-alpha.4](https://github.com/camunda/camunda-8-js-sdk/compare/v8.5.0-alpha.3...v8.5.0-alpha.4) (2024-04-05)
 
-## Version 0.15.1
 
-## Fixes
+### Bug Fixes
 
-_Things that were broken and are now fixed._
+* **repo:** use ts-patch to transform module mapping in output ([#112](https://github.com/camunda/camunda-8-js-sdk/issues/112)) ([7efdcf3](https://github.com/camunda/camunda-8-js-sdk/commit/7efdcf3478a0d68b4f1cbc62c1526ba7275008b0)), closes [#110](https://github.com/camunda/camunda-8-js-sdk/issues/110)
 
-- Update dependency `camunda-saas-oauth` to 1.2.4 to fix an issue with token expiration. Cached tokens were not correctly expired, leading to a 401 Unauthorized response to API calls after some time. The tokens are now correctly evicted from the cache. Thanks to [@hanh-le-clv](https://github.com/hanh-le-clv) for reporting this. See [this issue](https://github.com/camunda-community-hub/camunda-8-sdk-node-js/issues/7) for more details.
+# [8.5.0-alpha.3](https://github.com/camunda/camunda-8-js-sdk/compare/v8.5.0-alpha.2...v8.5.0-alpha.3) (2024-04-05)
 
-## Version 0.15.0
 
-- Update Operate client to 1.2.3, safely parsing variables when retrieving all variables for a process.
+### Bug Fixes
 
-## Version 0.14.0
+* **repo:** only git commit on npm publish success ([9012764](https://github.com/camunda/camunda-8-js-sdk/commit/901276451845c5dbd926af0a6563d5564d3e87b9))
 
-### Enhancements
+# [8.5.0-alpha.2](https://github.com/camunda/camunda-8-js-sdk/compare/v8.5.0-alpha.1...v8.5.0-alpha.2) (2024-04-05)
 
-- Update Tasklist client to 0.9.5, safely parsing variables when retrieving a Task.
 
-## Version 0.13.0
+### Bug Fixes
 
-### Enhancements
+* **repo:** add note on "supported" ([#107](https://github.com/camunda/camunda-8-js-sdk/issues/107)) ([fc45d61](https://github.com/camunda/camunda-8-js-sdk/commit/fc45d618bc459a06fbf76bd6907511d08e1f583b)), closes [#70](https://github.com/camunda/camunda-8-js-sdk/issues/70)
+
+# [8.5.0-alpha.1](https://github.com/camunda/camunda-8-js-sdk/compare/v8.4.0...v8.5.0-alpha.1) (2024-04-04)
+
+
+### Features
+
+* **oauth:** support optional scope in OAuth request ([#25](https://github.com/camunda/camunda-8-js-sdk/issues/25)) ([0451b80](https://github.com/camunda/camunda-8-js-sdk/commit/0451b802594f76518830b9bdff515d67fc0231b9))
+* **operate:** add multitenant support and lossless Json parsing ([#82](https://github.com/camunda/camunda-8-js-sdk/issues/82)) ([cf49a71](https://github.com/camunda/camunda-8-js-sdk/commit/cf49a717e2632af845529b3c1fde85ee1b0b347b)), closes [#78](https://github.com/camunda/camunda-8-js-sdk/issues/78) [#67](https://github.com/camunda/camunda-8-js-sdk/issues/67)
+* **repo:** add enhanced debug output for http errors ([#88](https://github.com/camunda/camunda-8-js-sdk/issues/88)) ([881b039](https://github.com/camunda/camunda-8-js-sdk/commit/881b03965cc37431885a76291f7c0aa762f26227)), closes [#87](https://github.com/camunda/camunda-8-js-sdk/issues/87)
+* **tasklist:** add multitenant support to tasklist ([#85](https://github.com/camunda/camunda-8-js-sdk/issues/85)) ([46bb564](https://github.com/camunda/camunda-8-js-sdk/commit/46bb564365afc3bc6758cd436490a459708128e6))
+* **zeebe:** add MigrateProcessInstance ([#97](https://github.com/camunda/camunda-8-js-sdk/issues/97)) ([2a9a123](https://github.com/camunda/camunda-8-js-sdk/commit/2a9a1232b160962f86b9450edd9047a8a933068a)), closes [#49](https://github.com/camunda/camunda-8-js-sdk/issues/49)
+* **zeebe:** implement deleteResource ([#73](https://github.com/camunda/camunda-8-js-sdk/issues/73)) ([0cd08b7](https://github.com/camunda/camunda-8-js-sdk/commit/0cd08b7b85d23ab44e42b36b2d9b48c1cfcb8c63))
+* **zeebe:** implement lossless parsing of job payload ([#95](https://github.com/camunda/camunda-8-js-sdk/issues/95)) ([57f3ea8](https://github.com/camunda/camunda-8-js-sdk/commit/57f3ea85d4cf86256301f5f2a9bcead09c01a199)), closes [#81](https://github.com/camunda/camunda-8-js-sdk/issues/81)
+* **zeebe:** normalise useragent, thread config ([#94](https://github.com/camunda/camunda-8-js-sdk/issues/94)) ([c1c4211](https://github.com/camunda/camunda-8-js-sdk/commit/c1c4211db11173c56d2410f489503ef9acf185f2))
+* **zeebe:** remove deployProcess method ([#71](https://github.com/camunda/camunda-8-js-sdk/issues/71)) ([6cb98f0](https://github.com/camunda/camunda-8-js-sdk/commit/6cb98f0ff3baf643015bacfa690f4f119caf6083))
+
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 8.4.0 (2024-02-01)
 
-- Update Operate API client to 1.2.2.
+### Bug Fixes
 
-## Version 0.11.0
+- REST getForm returns a flattened shape of the form compared to GraphQL ([58ec6d1](https://github.com/camunda/camunda-8-js-sdk/commit/58ec6d1de08e39cb4699326b67ebbf6a398fb30f))
 
-### Enhancements
+### Features
 
-- Update Operate API client to 1.2.0, enabling multiple clusters per application via custom OAuth injection.
+- configure specs to import configuration from .env file ([00804d1](https://github.com/camunda/camunda-8-js-sdk/commit/00804d132c0e1840846a5af9eee26351f9580c74))
+- **tasklist:** enable multiple clusters via constructor options ([#16](https://github.com/camunda/camunda-8-js-sdk/issues/16)) ([fb12e25](https://github.com/camunda/camunda-8-js-sdk/commit/fb12e258321e6bba03d11d38119c740f0e242773))

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at code-of-conduct@zeebe.io. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

package/CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Contributing to @camunda8/sdk
+
+Thank you for considering contributing to @camunda8/sdk! We welcome contributions from the community to make our package even better.
+
+## Getting Started
+
+To get started with contributing, please follow these steps:
+
+1. Fork the repository and clone it to your local machine.
+2. Check out the `alpha` branch. This is the development branch.
+3. Install the dependencies by running `npm install`.
+4. Make your changes or additions to the codebase.
+5. Write tests to cover your changes and ensure existing tests pass.
+6. Run the tests using `npm test` to make sure everything is working correctly. See below for details on running integration tests.
+7. Commit your changes and push them to your forked repository. Use [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) format for the commit message. See the note below.
+8. Submit a pull request to the main repository.
+9. When your PR is merged into the `alpha` branch, an alpha package is published to NPM.
+10. When the `alpha` branch is merged into `main`, a new package is published to NPM.
+
+## A note on commit messages
+
+The repository uses []`semantic-release`](https://github.com/semantic-release/semantic-release) to create releases. Because we track the Camunda 8 Platform minor version, we treat feature implementation during a minor release cycle as a patch release rather than a minor release.
+
+Creating a commit with a `feat` commit message will cause the package version patch release number to increment. To update the minor version, a commit with the type `minor` is needed.
+
+## Running tests
+
+Run all the unit tests with `npm run test`.
+
+### Integration tests
+
+Integration tests can be run against Self-Managed or against Camunda SaaS.
+
+To run integration tests against Camunda SaaS, but credentials for a Camunda SaaS API Client with scopes for all components in the environment, then run the integration tests against Camunda SaaS with `npm run test:integration`.
+
+To run the integration tests against Self-Managed, you can use either your own Self-Managed instance, or start one locally using Docker.
+
+To start one locally, run `docker compose -f docker-compose-modeler.yaml -f docker-compose-multitenancy.yml up -d`.
+
+Put the following credentials in the environment:
+
+```bash
+# Self-Managed
+export ZEEBE_SECURE_CONNECTION=false
+export ZEEBE_ADDRESS='localhost:26500'
+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'
+
+# Modeler API Client
+export CAMUNDA_CONSOLE_CLIENT_ID='zeebe'
+export CAMUNDA_CONSOLE_CLIENT_SECRET='zecret'
+# export CAMUNDA_CONSOLE_BASE_URL='https://api.cloud.camunda.io'
+# export CAMUNDA_CONSOLE_OAUTH_AUDIENCE='api.cloud.camunda.io'
+```
+
+Now run the integration tests against Self-Managed with `npm run test:local-integration`.
+
+### Multi-tenancy tests
+
+To run the multi-tenancy tests, use the following environment variables:
+
+```bash
+# Self-Managed
+export ZEEBE_SECURE_CONNECTION=false
+export ZEEBE_ADDRESS='localhost:26500'
+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>'
+```
+
+Now run the integration tests against Self-Managed with `npm run test:multitenancy`.
+
+## Code Style
+
+We follow a specific code style in our project to maintain consistency. Please make sure to adhere to the following guidelines:
+
+- Run `npm run lint` to lint your code with ESLint.
+- Run `npm run format` to format your code to the project standard.
+
+## Issue Reporting
+
+If you encounter any bugs or issues while using @camunda/sdk, please report them in the [issue tracker](https://github.com/camunda/camunda-8-js-sdk/issues). Provide as much detail as possible, including steps to reproduce the issue.
+
+## Feature Requests
+
+If you have any ideas or feature requests for @camunda/sdk, please submit them in the [issue tracker](https://github.com/camunda/camunda-8-js-sdk/issues). We appreciate your feedback and suggestions.
+
+## License
+
+By contributing to @camunda/sdk, you agree that your contributions will be licensed under the [Apache License](https://opensource.org/licenses/Apache).
+
+## Contact
+
+If you have any questions or need further assistance, open an issue in the repository.
+
+Happy contributing!

package/LICENSE

@@ -178,7 +178,7 @@
    APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
+      boilerplate notice, with the fields enclosed by brackets "{}"
       replaced with your own identifying information. (Don't include
       the brackets!)  The text should be enclosed in the appropriate
       comment syntax for the file format. We also recommend that a
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright {yyyy} {name of copyright owner}
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -1,55 +1,251 @@
-# Camunda 8 Unified SDK for Node.js
+# Camunda 8 JavaScript SDK
 
-[![NPM](https://nodei.co/npm/camunda-8-sdk.png)](https://npmjs.org/package/camunda-8-sdk) 
+[![NPM](https://nodei.co/npm/@camunda8/sdk.png)](https://www.npmjs.com/package/@camunda8/sdk)
 
-This SDK provides a high-level Node.js API for Camunda Platform 8. It is a wrapper around the following individual clients:
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-- [Web Console](https://github.com/camunda-community-hub/console-client-node-js)
-- [Optimize API Client](https://github.com/camunda-community-hub/optimize-client-node-js)
-- [Operate API Client](https://github.com/camunda-community-hub/operate-client-node-js)
-- [Tasklist API Client](https://github.com/camunda-community-hub/tasklist-client-node-js)
-- [Zeebe API Client](https://github.com/camunda-community-hub/zeebe-client-node-js)
-- [Web Modeler API Client](https://github.com/camunda-community-hub/modeler-client-node-js)
+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](https://github.com/camunda/camunda-8-js-sdk/issues/79).
 
-It uses the following libraries to hydrate credentials from the environment:
+## What does "supported" mean?
 
-- [Camunda 8 Credentials from Environment](https://github.com/camunda-community-hub/camunda-8-credentials-from-env)
-- [Camunda SaaS OAuth](https://github.com/camunda-community-hub/camunda-saas-oauth-nodejs)
+This is the official supported-by-Camunda Nodejs SDK for Camunda Platform 8.
 
-The full API documentation is hosted [here](https://camunda-community-hub.github.io/camunda-8-sdk-node-js/). 
+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.
 
-Watch a seven-minute speedrun demo video here:
+Prioritisation of implementing features is influenced by customer demand.
 
-[![](./img/video.png)](https://www.youtube.com/watch?v=A-P6upPCQWA)
+## Semantic versioning
 
-## API Coverage
+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.
 
-| Component   | Tested Environment  |
-|---|---|
-| Zeebe  | SaaS, Self-hosted  |
-| Operate  | SaaS  | 
-| Optimize  | SaaS  | 
-| Tasklist  |  SaaS  |
-| Console   |  SaaS  |
+## Using the SDK in your project
 
-## Installation
+Install the SDK as a dependency:
 
 ```bash
-npm i camunda-8-sdk
+npm i @camunda8/sdk
 ```
 
 ## Usage
 
-Set your Camunda SaaS credentials in the environment (at the moment, only Camunda SaaS is fully supported).
+In this release, the functionality of Camunda 8 is exposed via dedicated clients for the component APIs.
 
 ```typescript
-import { C8 } from 'camunda-8-sdk'
+import { Camunda8 } from '@camunda8/sdk'
+
+const c8 = new Camunda8()
+const zeebe = c8.getZeebeGrpcClient()
+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.
+
+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. See the file `src/lib/Configuration.ts` for a complete configuration outline.
+
+## A note on how int64 is handled in the JavaScript SDK
+
+Entity keys in Camunda 8 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](https://github.com/camunda/camunda-8-js-sdk/issues/78) for more details.
+
+Some number values - for example: "_total returned results_ " - may be specified as `int64` in the API specifications. Although these numbers will usually not contain unsafe values, they are always serialised to `string`.
+
+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. If no DTO is specified, the default behavior of the SDK is to serialise all numbers to JavaScript `number`, and if a number value is detected at a runtime that cannot be accurately stored as `number`, to throw an exception.
+
+## OAuth
 
-const zbc = new C8.ZBClient()
-const console = new C8.ConsoleApiClient()
-const operate = new C8.OperateApiClient()
-const optimize = new C8.OptimizeApiClient()
-const tasklist = new C8.TasklistApiClient()
+Calls to APIs are authorized using a token that is obtained via a client id/secret pair exchange, and then passes as an authorization header on API calls. The SDK handles this for you.
+
+If your Camunda 8 platform is secured using token exchange, provide the client id and secret to the SDK.
+
+### Disable OAuth
+
+To disable OAuth, set the environment variable `CAMUNDA_OAUTH_DISABLED`. You can use this when running against a minimal Zeebe broker in a development environment, for example.
+
+With this environment variable set, the SDK will inject a `NullAuthProvider` that does nothing.
+
+### Configuring OAuth
+
+To get a token for use with the application APIs, provide the following configuration fields at a minimum, either via the `Camunda8` constructor or in environment variables:
+
+```bash
+ZEEBE_ADDRESS
+ZEEBE_CLIENT_ID
+ZEEBE_CLIENT_SECRET
+CAMUNDA_OAUTH_URL
 ```
 
-Refer to the API docs [here](https://camunda-community-hub.github.io/camunda-8-sdk-node-js/) for full documentation of each component.
+To get a token for the Camunda SaaS Administration API or the Camunda SaaS Modeler API, set the following:
+
+```bash
+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:
+
+```typescript
+import { Camunda8 } from '@camunda8/sdk'
+
+const c8 = new Camunda8({
+	config: {
+		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.
+
+### Token refresh
+
+Token refresh timing relative to expiration is controlled by the `CAMUNDA_OAUTH_TOKEN_REFRESH_THRESHOLD_MS` value. By default, this is 1000ms. Tokens are renewed this amount of time before they expire.
+
+If you experience intermittent `401: Unauthorized` errors, this may not be sufficient time to refresh the token before it expires in your infrastructure. Increase this value to force a token to be refreshed before it expires.
+
+## Connection configuration examples
+
+### Self-Managed
+
+This is the complete environment configuration needed to run against the Dockerised Self-Managed stack in the `docker` subdirectory:
+
+```bash
+# Self-Managed
+export ZEEBE_ADDRESS='localhost:26500'
+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'
+
+# 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=''
+
+# TLS for gRPC is on by default. If the Zeebe broker is not secured by TLS, turn it off
+export CAMUNDA_SECURE_CONNECTION=false
+```
+
+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:
+
+```typescript
+import { Camunda8 } from '@camunda8/sdk'
+
+const c8 = new Camunda8({
+  config: {
+    ZEEBE_ADDRESS: 'localhost:26500'
+    ZEEBE_CLIENT_ID: 'zeebe'
+    ZEEBE_CLIENT_SECRET: 'zecret'
+    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:
+
+```bash
+export ZEEBE_ADDRESS='5c34c0a7-7f29-4424-8414-125615f7a9b9.syd-1.zeebe.camunda.io:443'
+export ZEEBE_CLIENT_ID='yvvURO9TmBnP3zx4Xd8Ho6apgeiZTjn6'
+export ZEEBE_CLIENT_SECRET='iJJu-SHgUtuJTTAMnMLdcb8WGF8s2mHfXhXutEwe8eSbLXn98vUpoxtuLk5uG0en'
+# export CAMUNDA_CREDENTIALS_SCOPES='Zeebe,Tasklist,Operate,Optimize' # What APIs these client creds are authorised for
+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'
+
+# This is on by default, but we include it in case it got turned off for local tests
+export CAMUNDA_SECURE_CONNECTION=true
+
+# 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'
+```
+
+## Debugging
+
+The SDK uses the [`debug`](https://github.com/debug-js/debug) library. 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:grpc`         | Zeebe gRPC channel   |
+| `camunda:worker`       | Zeebe Worker         |
+| `camunda:zeebeclient`  | Zeebe Client         |
+
+## 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`.
+
+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:
+
+```typescript
+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:
+
+```typescript
+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.

package/dist/admin/index.d.ts

@@ -0,0 +1,2 @@
+export { AdminApiClient } from './lib/AdminApiClient';
+export * as AdminDto from './lib/AdminDto';