@camunda8/sdk 8.9.0-alpha.1 → 8.9.0-alpha.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/AGENT.md +430 -101
  2. package/CHANGELOG.md +105 -0
  3. package/CONTRIBUTING.md +6 -5
  4. package/MAINTAINER.md +205 -0
  5. package/STYLE.md +136 -0
  6. package/dist/admin/lib/AdminApiClient.d.ts +146 -0
  7. package/dist/admin/lib/AdminApiClient.js +281 -0
  8. package/dist/admin/lib/AdminApiClient.js.map +1 -1
  9. package/dist/admin/lib/AdminDto.d.ts +133 -0
  10. package/dist/c8/lib/C8Dto.d.ts +10 -11
  11. package/dist/c8/lib/C8Dto.js +2 -1
  12. package/dist/c8/lib/C8Dto.js.map +1 -1
  13. package/dist/c8/lib/CamundaRestClient.d.ts +6 -1
  14. package/dist/c8/lib/CamundaRestClient.js +1 -1
  15. package/dist/c8/lib/CamundaRestClient.js.map +1 -1
  16. package/dist/index.d.ts +1 -0
  17. package/dist/index.js +4 -2
  18. package/dist/index.js.map +1 -1
  19. package/dist/lib/GotErrors.d.ts +7 -0
  20. package/dist/lib/GotErrors.js +31 -1
  21. package/dist/lib/GotErrors.js.map +1 -1
  22. package/dist/modeler/lib/ModelerAPIClient.d.ts +95 -2
  23. package/dist/modeler/lib/ModelerAPIClient.js +192 -11
  24. package/dist/modeler/lib/ModelerAPIClient.js.map +1 -1
  25. package/dist/modeler/lib/ModelerDto.d.ts +78 -0
  26. package/dist/oauth/lib/OAuthProvider.d.ts +1 -0
  27. package/dist/oauth/lib/OAuthProvider.js +126 -34
  28. package/dist/oauth/lib/OAuthProvider.js.map +1 -1
  29. package/dist/zeebe/lib/GrpcClient.d.ts +1 -2
  30. package/dist/zeebe/lib/GrpcClient.js +13 -5
  31. package/dist/zeebe/lib/GrpcClient.js.map +1 -1
  32. package/dist/zeebe/lib/ZBStreamWorker.js +12 -8
  33. package/dist/zeebe/lib/ZBStreamWorker.js.map +1 -1
  34. package/dist/zeebe/lib/ZBWorkerBase.js +18 -13
  35. package/dist/zeebe/lib/ZBWorkerBase.js.map +1 -1
  36. package/dist/zeebe/lib/cancelProcesses.js +8 -5
  37. package/dist/zeebe/lib/cancelProcesses.js.map +1 -1
  38. package/dist/zeebe/lib/stringifyVariables.d.ts +1 -1
  39. package/dist/zeebe/lib/stringifyVariables.js +11 -13
  40. package/dist/zeebe/lib/stringifyVariables.js.map +1 -1
  41. package/dist/zeebe/zb/ZeebeGrpcClient.js +13 -8
  42. package/dist/zeebe/zb/ZeebeGrpcClient.js.map +1 -1
  43. package/package.json +15 -8
package/CHANGELOG.md CHANGED
@@ -1,3 +1,108 @@
1
+ # [8.9.0-alpha.11](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.10...v8.9.0-alpha.11) (2026-08-31)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * **modeler:** preserve query string on CAMUNDA_MODELER_BASE_URL ([#825](https://github.com/camunda/camunda-8-js-sdk/issues/825)) ([b6ecd45](https://github.com/camunda/camunda-8-js-sdk/commit/b6ecd451c79ca0cdadc826dd28d94184c60fbb24)), closes [#824](https://github.com/camunda/camunda-8-js-sdk/issues/824)
7
+
8
+ # [8.9.0-alpha.10](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.9...v8.9.0-alpha.10) (2026-07-16)
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * **modeler:** resolve delete methods with real null instead of casting ([931b601](https://github.com/camunda/camunda-8-js-sdk/commit/931b6018d62d2a857d05fd8a241e437deafd1dac))
14
+
15
+
16
+ ### Features
17
+
18
+ * **modeler:** add versions endpoints and deprecate milestones ([6d8ad5f](https://github.com/camunda/camunda-8-js-sdk/commit/6d8ad5f1323a06544a520bb3a4995dd2886bd6ee)), closes [#812](https://github.com/camunda/camunda-8-js-sdk/issues/812)
19
+
20
+ # [8.9.0-alpha.9](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.8...v8.9.0-alpha.9) (2026-07-02)
21
+
22
+
23
+ ### Features
24
+
25
+ * **rest-client:** allow customizing retry config via constructor option ([cea5ab8](https://github.com/camunda/camunda-8-js-sdk/commit/cea5ab87bc370413fecf202c397bd003d78f8c19)), closes [#808](https://github.com/camunda/camunda-8-js-sdk/issues/808)
26
+
27
+ # [8.9.0-alpha.8](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.7...v8.9.0-alpha.8) (2026-06-04)
28
+
29
+
30
+ ### Bug Fixes
31
+
32
+ * pass author-association to community notification workflow ([09fb9b8](https://github.com/camunda/camunda-8-js-sdk/commit/09fb9b8849b3d9c7f5ab3d19457c9bb1e7b492a6))
33
+
34
+ # [8.9.0-alpha.7](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.6...v8.9.0-alpha.7) (2026-05-31)
35
+
36
+
37
+ ### Bug Fixes
38
+
39
+ * issue 784 ([4caab63](https://github.com/camunda/camunda-8-js-sdk/commit/4caab63c5964093e0d4987cf1789d1faa3522e4c))
40
+
41
+ # [8.9.0-alpha.6](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.5...v8.9.0-alpha.6) (2026-04-22)
42
+
43
+
44
+ ### Bug Fixes
45
+
46
+ * keep error.message static for error-monitoring grouping ([0c2df38](https://github.com/camunda/camunda-8-js-sdk/commit/0c2df387d7a228fa5b322179fb70991e9d69180f)), closes [#658](https://github.com/camunda/camunda-8-js-sdk/issues/658)
47
+ * **oauth:** improve OAuthProvider reliability ([b699342](https://github.com/camunda/camunda-8-js-sdk/commit/b699342eda39551b1cadccd6065460ac669ae22a))
48
+ * **oauth:** write disk-cached tokens with mode 0600 (current-user only) ([1444787](https://github.com/camunda/camunda-8-js-sdk/commit/1444787086f30f2eb7363220c52a440526cb29f6)), closes [#737](https://github.com/camunda/camunda-8-js-sdk/issues/737)
49
+ * remove logs ([4ab2178](https://github.com/camunda/camunda-8-js-sdk/commit/4ab21783387b08ee27580129231bcd0de6d82408))
50
+ * resolve conflict ([356eaf5](https://github.com/camunda/camunda-8-js-sdk/commit/356eaf58b07b3b4009763266f36caa4ecb2363a4))
51
+ * skip unstable tests ([cf38fdf](https://github.com/camunda/camunda-8-js-sdk/commit/cf38fdf67be3e4d8b4290c20faed0c194e1fbc08))
52
+ * **test:** use response.statusCode for 403 detection ([c976899](https://github.com/camunda/camunda-8-js-sdk/commit/c9768995b6cbdd049549d58d95e3f538b3c4ef32))
53
+
54
+
55
+ ### Features
56
+
57
+ * **admin:** implement all missing Admin API operations ([e5527ba](https://github.com/camunda/camunda-8-js-sdk/commit/e5527bac2b139790638c76b26b0f737986413850)), closes [#713](https://github.com/camunda/camunda-8-js-sdk/issues/713)
58
+
59
+ # [8.9.0-alpha.5](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.4...v8.9.0-alpha.5) (2026-03-18)
60
+
61
+
62
+ ### Bug Fixes
63
+
64
+ * do not arm client-side timeout on long-lived gRPC streams ([a5ed433](https://github.com/camunda/camunda-8-js-sdk/commit/a5ed433a01043f1d36cca1de4afb17e993e618ea))
65
+ * remove Promise churn from job pathway ([d763c89](https://github.com/camunda/camunda-8-js-sdk/commit/d763c896780a7aa17f9ec6d500745a806b8d3867))
66
+ * update grpc dependencies ([ce7a450](https://github.com/camunda/camunda-8-js-sdk/commit/ce7a45008da4c505a8fa9bb2e807d864effcd267))
67
+
68
+ # [8.9.0-alpha.4](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.3...v8.9.0-alpha.4) (2026-03-15)
69
+
70
+
71
+ ### Bug Fixes
72
+
73
+ * address npm audit issues ([fea2510](https://github.com/camunda/camunda-8-js-sdk/commit/fea251013097768d0514a355ba95e768d5737de3))
74
+ * use latest stable tag for version detection in compatibility workflow ([7591903](https://github.com/camunda/camunda-8-js-sdk/commit/75919032eee6bb794d9f5541bb97ecd3cde93229))
75
+
76
+
77
+ ### Features
78
+
79
+ * add author as reviewer ([3c02ce6](https://github.com/camunda/camunda-8-js-sdk/commit/3c02ce6a46577a67c35cfdc9129dab8143f8f205))
80
+
81
+ # [8.9.0-alpha.3](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.2...v8.9.0-alpha.3) (2026-03-10)
82
+
83
+
84
+ ### Bug Fixes
85
+
86
+ * use semver comparison for gateway version check in cancelProcesses ([042e3a9](https://github.com/camunda/camunda-8-js-sdk/commit/042e3a9a9c147f4675b8af138164ee4458b9f8c5))
87
+
88
+
89
+ ### Features
90
+
91
+ * add trigger for stable branches ([6344480](https://github.com/camunda/camunda-8-js-sdk/commit/6344480c373ec9beeb985242ed2ccaeefcb67705))
92
+
93
+ # [8.9.0-alpha.2](https://github.com/camunda/camunda-8-js-sdk/compare/v8.9.0-alpha.1...v8.9.0-alpha.2) (2026-03-07)
94
+
95
+
96
+ ### Bug Fixes
97
+
98
+ * export types. fixes Missing types in export ([bda4b97](https://github.com/camunda/camunda-8-js-sdk/commit/bda4b9705da03f63c9d9eed04a5dc99e5bda1ec1)), closes [#570](https://github.com/camunda/camunda-8-js-sdk/issues/570)
99
+ * implement copilot suggestions ([fb25ca5](https://github.com/camunda/camunda-8-js-sdk/commit/fb25ca54025fdbdfe33fbd9b62b131ecf5714257))
100
+
101
+
102
+ ### Features
103
+
104
+ * add new compatibility test workflow ([e8074c4](https://github.com/camunda/camunda-8-js-sdk/commit/e8074c42b47d05234a9cc37e7ac5d96b8b3efdd3))
105
+
1
106
  # [8.9.0-alpha.1](https://github.com/camunda/camunda-8-js-sdk/compare/v8.8.5...v8.9.0-alpha.1) (2026-03-05)
2
107
 
3
108
 
package/CONTRIBUTING.md CHANGED
@@ -38,11 +38,11 @@ Releases are performed by GitHub Actions using semantic-release:
38
38
 
39
39
  ### Branch model
40
40
 
41
- | Branch | Type | npm dist-tag |
42
- |--------|------|--------------|
43
- | `main` | prerelease | `alpha` |
44
- | `stable/<major>.<minor>` (current) | stable | `latest` |
45
- | `stable/<major>.<minor>` (older) | maintenance | `<major>.<minor>-stable` |
41
+ | Branch | Type | npm dist-tag |
42
+ | ---------------------------------- | ----------- | ------------------------ |
43
+ | `main` | prerelease | `alpha` |
44
+ | `stable/<major>.<minor>` (current) | stable | `latest` |
45
+ | `stable/<major>.<minor>` (older) | maintenance | `<major>.<minor>-stable` |
46
46
 
47
47
  ### Promotion procedure (switch current stable line)
48
48
 
@@ -136,6 +136,7 @@ We follow a specific code style in our project to maintain consistency. Please m
136
136
 
137
137
  - Run `npm run lint` to lint your code with ESLint.
138
138
  - Run `npm run format` to format your code to the project standard.
139
+ - Read [STYLE.md](STYLE.md) for the codebase's control-flow, iteration, and state philosophy — much of it is authorial discipline that the linter does not enforce.
139
140
 
140
141
  ## Issue Reporting
141
142
 
package/MAINTAINER.md ADDED
@@ -0,0 +1,205 @@
1
+ <h1 align="center">Maintainer Guide – Camunda 8 JavaScript SDK</h1>
2
+
3
+ Operational documentation for maintainers of `@camunda8/sdk`. End-user documentation lives in [README.md](README.md); contributor onboarding (forking, commit conventions, running tests locally) lives in [CONTRIBUTING.md](CONTRIBUTING.md).
4
+
5
+ This document focuses on **how CI works**, **how releases happen**, and **how to operate the branch model**.
6
+
7
+ ---
8
+
9
+ ## 1. Branch Model
10
+
11
+ | Branch | Type | npm dist-tag | Trigger |
12
+ | ----------------------------------- | ------------------- | ------------------------ | -------------------- |
13
+ | `main` | alpha pre-releases | `alpha` | merge to `main` |
14
+ | `stable/<major>.<minor>` (current) | stable releases | `latest` | merge to that branch |
15
+ | `stable/<major>.<minor>` (older) | maintenance | `<major>.<minor>-stable` | merge to that branch |
16
+
17
+ The "current" stable line is selected at release time by the GitHub repo variable `CAMUNDA_SDK_CURRENT_STABLE_MINOR` (e.g. `8.8`). The branch matching that value publishes to `latest`; every other `stable/*` branch publishes to its own maintenance dist-tag.
18
+
19
+ At time of writing, `stable/8.8` is the current stable line (publishes to `latest`) and `main` carries `8.9.0-alpha.*` (publishes to `alpha`).
20
+
21
+ The branch resolution logic lives in [release.config.js](release.config.js) (`stableMinorFromBranch`, `envCurrentStableMinor`, `dedupeBranches`). The logic mirrors `orchestration-cluster-api-js` so the two SDKs stay aligned.
22
+
23
+ ### Promoting a new stable line
24
+
25
+ When a new Camunda minor (e.g. `8.9`) is ready to be promoted to `latest`:
26
+
27
+ 1. Cut the branch from `main`:
28
+ ```bash
29
+ git checkout main
30
+ git checkout -b stable/8.9
31
+ git push -u origin stable/8.9
32
+ ```
33
+ 2. Update the GitHub **repository variable** (Settings → Secrets and variables → Actions → Variables) `CAMUNDA_SDK_CURRENT_STABLE_MINOR` from `8.8` to `8.9`.
34
+ 3. The next merge to `stable/8.9` will publish to npm dist-tag `latest`. The previous current line (`stable/8.8`) automatically falls back to maintenance dist-tag `8.8-stable` on its next release.
35
+ 4. Update [.github/workflows/integration-test-matrix-trigger.yaml](.github/workflows/integration-test-matrix-trigger.yaml) to add a daily compatibility-test trigger for the new branch (uncomment / duplicate the `trigger-stable-8-9` block).
36
+ 5. Update [.github/renovate.json](.github/renovate.json) `baseBranchPatterns` if the previous stable line should be replaced as a Renovate target.
37
+
38
+ No git tag manipulation is required — semantic-release reads existing tags and computes the next version per branch independently.
39
+
40
+ ---
41
+
42
+ ## 2. CI Workflows
43
+
44
+ All workflows live under [.github/workflows/](.github/workflows/).
45
+
46
+ | Workflow | Trigger | Purpose |
47
+ | ----------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
48
+ | `ci.yml` | push to feature branches, all PRs | Fast feedback for contributors. Unit tests + 8.8 SM integration. Heavier 8.7 jobs are PR-only and gated by environment. |
49
+ | `release.yml` | push to `main` or `stable/**`, manual dispatch | Full integration suite **plus** semantic-release publish step. |
50
+ | `commitlint.yml` | PR | Enforces conventional commits. |
51
+ | `code-scanning.yml` | scheduled / push | CodeQL. |
52
+ | `backport.yml` | PR closed, `/backport` comment | Creates backport PRs (e.g. `main` → `stable/8.8`) via `korthout/backport-action`. |
53
+ | `integration-test-matrix.yml` | scheduled (02:00 UTC), manual dispatch | Cross-version client × server compatibility matrix. Runs **on a stable branch** and tests every released SDK version against every server version ≥ current minor. |
54
+ | `integration-test-matrix-trigger.yaml` | scheduled (02:00 UTC) | Fans out the matrix run to each active stable branch (uses `gh workflow run --ref stable/<x.y>`). |
55
+
56
+ ### CI vs. Release: why feature branches and `main`/`stable/**` are separated
57
+
58
+ `ci.yml` listens on `push` for everything **except** `main` and `stable/**`, plus all `pull_request` events. `release.yml` listens on `push` to `main` and `stable/**`. This avoids running the same jobs twice on the same SHA when a PR is merged.
59
+
60
+ The release workflow re-runs the same gating jobs as `ci.yml`, then layers on:
61
+
62
+ - `local_integration` (8.7 SM, requires `selfhosted` env + `DOCKER_PASSWORD`)
63
+ - `local_multitenancy_integration` (8.7 SM-MT, same)
64
+ - `saas_integration` (8.7 SaaS, requires `integration` env)
65
+ - `saas_integration_8_8` (8.8 SaaS, requires `integration-8.8` env)
66
+
67
+ All of those are **required** before the `tag-and-publish` job runs. There is no path that publishes to npm without the full integration suite passing.
68
+
69
+ ### SaaS concurrency
70
+
71
+ SaaS test clusters are shared across branches. To prevent a `main` release and a `stable/8.8` release from interleaving requests against the same cluster, each SaaS job declares a `concurrency` group keyed to its cluster (`saas-integration-8.7`, `saas-integration-8.8`) with `cancel-in-progress: false`. Concurrent triggers queue rather than abort.
72
+
73
+ ---
74
+
75
+ ## 3. Release Pipeline
76
+
77
+ Releases are produced by [semantic-release](https://github.com/semantic-release/semantic-release) inside the `tag-and-publish` job at the end of [release.yml](.github/workflows/release.yml). The job runs in the GitHub `publish` environment (any environment-level approval gates apply here).
78
+
79
+ ### What semantic-release does
80
+
81
+ 1. Reads commits since the last release tag on the current branch.
82
+ 2. Computes the next version from commit types (see [release.config.js](release.config.js) `releaseRules`).
83
+ 3. Updates `package.json`, generates `CHANGELOG.md`, commits with `chore(release): <version> [skip ci]`, tags `v<version>`.
84
+ 4. Publishes to npm with the dist-tag derived from the branch.
85
+ 5. Creates a GitHub Release with auto-generated notes.
86
+ 6. Posts a "Released in `<tag>`" comment on PRs included in the release.
87
+
88
+ ### Commit type → version bump
89
+
90
+ | Commit type | Bump | Notes |
91
+ | --------------- | ----- | ------------------------------------------------------ |
92
+ | `feat` | patch | Mutated semver: features within a minor cycle = patch |
93
+ | `fix` | patch | |
94
+ | `perf` | patch | |
95
+ | `revert` | patch | |
96
+ | `release` | patch | |
97
+ | `BREAKING CHANGE` footer | patch | Also a patch — bumps are tied to the Camunda server line, not breaking changes in the SDK itself |
98
+ | `server` | minor | Use when bumping to a new Camunda 8 minor (e.g. 8.8 → 8.9) |
99
+ | `server-major` | major | Use when bumping to a new Camunda 8 major |
100
+ | anything else (`chore`, `docs`, `test`, `ci`, `build`, `refactor`, `style`) | none | No release |
101
+
102
+ This mutated semver is intentional: the SDK's version tracks the Camunda 8 server minor line, not its own API surface. To force a release of accumulated `chore`-only work, push a commit (or empty commit) with type `release`.
103
+
104
+ ### npm authentication: Trusted Publishing (OIDC)
105
+
106
+ Publishing uses npm **Trusted Publishing** via GitHub Actions OIDC. Consequences:
107
+
108
+ - The workflow requests `id-token: write` and **does not** read `NPM_TOKEN`. The `NODE_AUTH_TOKEN=""` in front of the `npx semantic-release` invocation is deliberate — it ensures any stale token in the environment is ignored.
109
+ - `NPM_CONFIG_PROVENANCE: true` is set, so published tarballs include npm provenance attestations.
110
+ - For publishing to succeed, `@camunda8/sdk` must be configured on npmjs.com to **trust this repository and the `release.yml` workflow**.
111
+ - If publishing fails with auth errors (`ENEEDAUTH`, `E401`), check the npm Trusted Publishing configuration **before** introducing an `NPM_TOKEN` secret. Adding a token undermines the OIDC posture and should be a last resort.
112
+
113
+ ### Stable line dist-tag derivation at publish time
114
+
115
+ The `Export stable line config` step in `tag-and-publish` writes `CAMUNDA_SDK_CURRENT_STABLE_MINOR` from the repo variable into the job env. `release.config.js` then dynamically constructs the `branches` array based on the current branch (`GITHUB_REF_NAME`) and that env var. Effects:
116
+
117
+ - On `main`: only the `main` (alpha) branch entry is active.
118
+ - On `stable/<current>`: both `main` and `stable/<current>` (channel: `latest`) are present.
119
+ - On `stable/<other>`: a maintenance entry is appended for that branch (channel: `<x.y>-stable`).
120
+
121
+ A consequence: if you push to a `stable/*` branch **without** `CAMUNDA_SDK_CURRENT_STABLE_MINOR` being set correctly, semantic-release may either refuse to publish or publish to the wrong dist-tag. Always verify the repo variable before promoting a new stable line.
122
+
123
+ ### Documentation deployment
124
+
125
+ After a successful release on `main`, the same job builds TypeDoc output (`npm run docs`) and deploys it to the `gh-pages` branch via `JamesIves/github-pages-deploy-action`. Releases on `stable/**` do not redeploy docs.
126
+
127
+ ---
128
+
129
+ ## 4. Compatibility Matrix
130
+
131
+ [integration-test-matrix.yml](.github/workflows/integration-test-matrix.yml) runs nightly on each active stable branch (driven by `integration-test-matrix-trigger.yaml`). It:
132
+
133
+ 1. Derives the current minor from the **latest stable git tag** on the branch (intentionally not from `package.json`, which may already be at a pre-release version).
134
+ 2. Enumerates SDK client versions ≥ that minor from local git tags.
135
+ 3. Enumerates Camunda server versions ≥ that minor from `camunda/camunda` git tags via `git ls-remote` (no clone).
136
+ 4. Runs the full client × server matrix, with caching to avoid retesting known-good combinations.
137
+
138
+ Manual dispatch supports pinning a `client_version`, a `server_version`, and `skip_cache` to force a full re-run.
139
+
140
+ When promoting a new stable line, **add a trigger entry** in `integration-test-matrix-trigger.yaml` so the new branch is exercised nightly. Failure to do so means the new line silently loses compatibility coverage.
141
+
142
+ ---
143
+
144
+ ## 5. Hotfix / Maintenance Workflow
145
+
146
+ To ship a fix to a stable line:
147
+
148
+ 1. Land the fix on `main` via a normal PR (so `alpha` users get it immediately).
149
+ 2. Add the appropriate `backport-stable/<x.y>` label on the merged PR (or comment `/backport stable/<x.y>`). [backport.yml](.github/workflows/backport.yml) creates the backport PR automatically; conflicts are committed as draft commits per the `experimental.conflict_resolution` setting.
150
+ 3. Merge the backport PR to `stable/<x.y>`. The Release workflow then runs the full integration suite and publishes to npm.
151
+
152
+ Always land on `main` first unless the fix is genuinely stable-only (e.g. it touches code that no longer exists on `main`). Stable-only fixes should be opened directly against the `stable/<x.y>` branch.
153
+
154
+ ---
155
+
156
+ ## 6. Required Secrets and Environments
157
+
158
+ | Name | Scope | Used by |
159
+ | -------------------------------------------- | ------------------------------ | ---------------------------------------------- |
160
+ | `DOCKER_PASSWORD` | env: `selfhosted` | 8.7 self-managed integration jobs (login to `registry.camunda.cloud`) |
161
+ | `ZEEBE_*`, `CAMUNDA_*`, `CAMUNDA_CONSOLE_*` | env: `integration` | 8.7 SaaS integration |
162
+ | `ZEEBE_*`, `CAMUNDA_*`, `CAMUNDA_CONSOLE_*` | env: `integration-8.8` | 8.8 SaaS integration |
163
+ | (none — OIDC) | env: `publish` | npm publish via Trusted Publishing |
164
+ | `BACKPORT_ACTION_PAT` | repo | `backport.yml` (PAT with write access for cross-branch pushes) |
165
+ | `CAMUNDA_SDK_CURRENT_STABLE_MINOR` (variable, not secret) | repo | `release.yml` → `release.config.js` |
166
+
167
+ Fork PRs cannot read environment secrets, so the heavier jobs (`local_integration`, `local_multitenancy_integration`, both SaaS jobs) skip on fork PRs by virtue of the environment lookup failing or, in `ci.yml`, by an explicit `if: github.event_name == 'pull_request' && github.actor != 'dependabot[bot]'` guard plus the environment scoping. Fork contributors get unit tests + the public 8.8 docker stack.
168
+
169
+ ---
170
+
171
+ ## 7. Common Operational Tasks
172
+
173
+ ### Force a release with no eligible commits
174
+
175
+ Push an empty commit with type `release`:
176
+
177
+ ```bash
178
+ git commit --allow-empty -m "release: ship pending chore work"
179
+ git push
180
+ ```
181
+
182
+ ### Re-run a failed release
183
+
184
+ Re-run the `tag-and-publish` job from the Actions UI. semantic-release is idempotent: it will skip publishing if the version was already published, or resume from the next pending version.
185
+
186
+ ### Diagnose "wrong dist-tag" issues
187
+
188
+ 1. Check `CAMUNDA_SDK_CURRENT_STABLE_MINOR` in repo variables.
189
+ 2. Inspect the workflow log for the line `Export stable line config` to confirm the value reached the job.
190
+ 3. Confirm the branch you pushed to matches the configured current stable minor (or is `main`, or is an older stable line).
191
+
192
+ ### Diagnose "publish failed: no auth"
193
+
194
+ Do **not** add an `NPM_TOKEN` secret. Verify on npmjs.com that `@camunda8/sdk` lists this repo + `release.yml` as a Trusted Publisher.
195
+
196
+ ---
197
+
198
+ ## 8. Cross-references
199
+
200
+ - [CONTRIBUTING.md](CONTRIBUTING.md) — contributor-facing version of the branching/release summary
201
+ - [release.config.js](release.config.js) — semantic-release configuration (branches, dist-tags, releaseRules)
202
+ - [.github/workflows/release.yml](.github/workflows/release.yml) — full release pipeline
203
+ - [.github/workflows/ci.yml](.github/workflows/ci.yml) — PR / feature-branch CI
204
+ - [.github/workflows/integration-test-matrix.yml](.github/workflows/integration-test-matrix.yml) — nightly compatibility matrix
205
+ - [.github/workflows/backport.yml](.github/workflows/backport.yml) — automated backports
package/STYLE.md ADDED
@@ -0,0 +1,136 @@
1
+ # Code Style & Philosophy
2
+
3
+ This document describes the _implicit_ coding philosophy of this codebase — the
4
+ conventions that shape how control flow, iteration, and state are expressed in
5
+ `src/`. Most of these are **not enforced by a linter**; they are deliberate
6
+ authorial discipline. New code should read like the code already here.
7
+
8
+ > **In one line:** _Prefer expressions over statements; keep the happy path
9
+ > straight; make every exception deliberate._
10
+
11
+ The style is functional-leaning and immutability-first. Imperative constructs
12
+ (`let`, raw `for`/`while`, `if/else` branching) are treated as escape hatches
13
+ that must earn their place — and when used, they are kept narrow, localized, and
14
+ often annotated with a comment explaining why.
15
+
16
+ ---
17
+
18
+ ## 1. Immutable by default
19
+
20
+ - **`const` over `let`, always; never `var`.** In `src/` the ratio is roughly
21
+ 26:1 `const`:`let`, with zero `var`.
22
+ - **Push immutability into the type system** with `readonly`, `private readonly`,
23
+ and `as const` rather than runtime freezing. (`Object.freeze` is intentionally
24
+ absent.)
25
+ - **Mutation is rare and localized.** Compound-assignment and increment operators
26
+ barely appear; `.push` is used for accumulation but in-place rewriting of shared
27
+ state is avoided.
28
+
29
+ ### When `let` is acceptable
30
+
31
+ `let` is an exception, not a default, and falls into three shapes:
32
+
33
+ 1. **Definite-assignment across branches** — when the initializing logic is
34
+ _multi-statement_ (a `try/catch`, a multi-arm `if`) and cannot be a single
35
+ `const x = expr`, declare a typed `let` and assign it **exactly once per branch**.
36
+ These are morally `const`; TypeScript's definite-assignment analysis guarantees
37
+ they are set before use.
38
+
39
+ ```ts
40
+ let effectiveAddress: string // ZeebeGrpcClient.ts
41
+ let protocolBasedTLS: boolean | undefined
42
+ if (hasProtocol) {
43
+ try {
44
+ const info = parseZeebeGrpcAddress(addr)
45
+ effectiveAddress = info.hostPort
46
+ protocolBasedTLS = info.isSecure
47
+ } catch {
48
+ effectiveAddress = fallback
49
+ }
50
+ } else {
51
+ // ...assigned here instead
52
+ }
53
+ ```
54
+
55
+ 2. **Genuine accumulators, counters, and flags** — e.g. `connectionErrorCount`,
56
+ `doBackoff`, or a recursion accumulator `let taskTypes: string[] = []`. Prefer a
57
+ short comment when the mutation is non-obvious (see `BpmnParser.ts`:
58
+ `// mutated in the recursive function`).
59
+
60
+ 3. **Lazy caches / memoization singletons** — module-level bindings assigned once
61
+ on first use (e.g. `C8Logger.ts`).
62
+
63
+ ---
64
+
65
+ ## 2. Conditionals: guard first, branch in expressions
66
+
67
+ - **`if` is a one-armed guard that exits early** (`return` / `throw`), not a
68
+ two-armed branch. Validate preconditions and bail so the happy path stays at the
69
+ lowest indentation. In `src/`, ~85% of `if`s have no `else`.
70
+
71
+ ```ts
72
+ const methodName = methodMatch?.[1]
73
+ if (!methodName) return line // guard, then continue on the straight path
74
+ const targetLine = findMethodLine(targetFile, methodName)
75
+ if (!targetLine) return line
76
+ return line.replace(/.../, replacement)
77
+ ```
78
+
79
+ - **Choose _values_ with expressions, not `if/else` assignment** — reach for the
80
+ ternary (`?:`), nullish coalescing (`??`), short-circuit (`||`, `&&`), and
81
+ optional chaining (`?.`):
82
+
83
+ ```ts
84
+ const targetFile = preferDist ? distPath : srcPath
85
+ const cacheDir = dir ?? OAuthProvider.defaultTokenCache
86
+ ```
87
+
88
+ - **No `switch`.** Multi-way logic is expressed with sequential guards or lookup
89
+ objects/maps, never a `switch` statement. There are zero `switch` statements in
90
+ `src/`.
91
+
92
+ ---
93
+
94
+ ## 3. Iteration: declarative first, imperative as an escape hatch
95
+
96
+ - **Prefer array methods** — `.map` / `.filter` / `.reduce` / `.forEach` /
97
+ `.some` / `.every` — for transforming and collecting known collections. They
98
+ outnumber imperative loops by roughly 3.5:1.
99
+
100
+ - **Reach for an imperative `for` only where array methods genuinely cannot**:
101
+
102
+ - **Unknown-shape object-graph traversal**, usually recursive —
103
+ `for (const k in obj)` walking an arbitrary tree (`BpmnParser.ts`,
104
+ `LosslessJsonParser.ts`),
105
+ switching _back_ to `.forEach` for the known-array parts.
106
+ - **Index-sensitive scanning** of strings/buffers — `for (let i = 0; ...)` where
107
+ the index itself matters (`OriginTracing.ts`, `QuerySubscription.ts`).
108
+ - **Async-sequential or side-effecting** iteration — awaiting per item, or
109
+ dispatching jobs; use `Promise.all` where the work is safely parallel.
110
+
111
+ - **`while` / `for await` are reserved for genuinely unbounded streams** — e.g. a
112
+ `while (true)` poll-retry loop _inside an async generator_ that `yield`s then
113
+ `break`s, consumed declaratively via `for await (const data of generator)`
114
+ (`Subscription.ts`).
115
+
116
+ - **No `do...while`.** Same "no exotic constructs" discipline as no `switch`.
117
+
118
+ ---
119
+
120
+ ## 4. The unifying tell
121
+
122
+ The same instinct yields **zero `switch`, zero `do...while`, zero `var`, and zero
123
+ `Object.freeze`**. When the imperative escape hatch _is_ used — a mutable `let`, a
124
+ raw `for`, a `while (true)` — it is narrow, localized, and frequently annotated
125
+ with a comment explaining why. The result is a **straight, un-nested happy path
126
+ built from immutable values and pure transformations, with side effects and
127
+ mutation quarantined at the edges** (streams, caches, I/O).
128
+
129
+ ---
130
+
131
+ ## Not linter-enforced
132
+
133
+ These conventions are largely a matter of discipline: the ESLint config does not
134
+ set `prefer-const`, `no-var`, `no-else-return`, `no-param-reassign`, `max-depth`,
135
+ or `complexity` rules. Prettier handles layout only. Follow the philosophy because
136
+ it keeps the codebase coherent — not because a tool will catch you.
@@ -137,4 +137,150 @@ export declare class AdminApiClient {
137
137
  *
138
138
  */
139
139
  deleteMember(email: string): Promise<null>;
140
+ /**
141
+ *
142
+ * Get the egress IP ranges for Camunda SaaS. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetMeta) for more details.
143
+ * @throws {RESTError}
144
+ */
145
+ getIpRanges(): Promise<Dto.MetaDto>;
146
+ /**
147
+ *
148
+ * Update a cluster's name, description, or stage label. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/UpdateCluster) for more details.
149
+ * @param clusterUuid - The cluster UUID
150
+ * @param updateRequest - The fields to update
151
+ * @throws {RESTError}
152
+ */
153
+ updateCluster(clusterUuid: string, updateRequest: Dto.UpdateClusterBody): Promise<void>;
154
+ /**
155
+ *
156
+ * Upgrade a cluster to the latest available generation. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/UpgradeCluster) for more details.
157
+ * @param clusterUuid - The cluster UUID
158
+ * @throws {RESTError}
159
+ */
160
+ upgradeCluster(clusterUuid: string): Promise<Dto.GenerationUpgradeForClusterDto>;
161
+ /**
162
+ *
163
+ * Resume a suspended cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/Wake) for more details.
164
+ * @param clusterUuid - The cluster UUID
165
+ * @throws {RESTError}
166
+ */
167
+ wakeCluster(clusterUuid: string): Promise<void>;
168
+ /**
169
+ *
170
+ * Update the IP allowlist for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/UpdateIpAllowlist) for more details.
171
+ * @param clusterUuid - The cluster UUID
172
+ * @param ipallowlist - Array of IP allowlist entries
173
+ * @throws {RESTError}
174
+ */
175
+ updateIpAllowlist(clusterUuid: string, ipallowlist: Dto.IpAllowListEntry[]): Promise<void>;
176
+ /**
177
+ *
178
+ * Update a connector secret value. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/UpdateSecret) for more details.
179
+ * @param clusterUuid - The cluster UUID
180
+ * @param secretName - The name of the secret to update
181
+ * @param secretValue - The new secret value
182
+ * @throws {RESTError}
183
+ */
184
+ updateSecret(clusterUuid: string, secretName: string, secretValue: string): Promise<void>;
185
+ /**
186
+ *
187
+ * Activate Secure Connectivity for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/ActivateSecureConnectivity) for more details.
188
+ * @param clusterUuid - The cluster UUID
189
+ * @param request - The allowed principals and regions
190
+ * @throws {RESTError}
191
+ */
192
+ activateSecureConnectivity(clusterUuid: string, request: Dto.ActivateSecureConnectivityBody): Promise<void>;
193
+ /**
194
+ *
195
+ * Deactivate Secure Connectivity for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/DeactivateSecureConnectivity) for more details.
196
+ * @param clusterUuid - The cluster UUID
197
+ * @throws {RESTError}
198
+ */
199
+ deactivateSecureConnectivity(clusterUuid: string): Promise<void>;
200
+ /**
201
+ *
202
+ * Get the Secure Connectivity status for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetSecureConnectivityStatus) for more details.
203
+ * @param clusterUuid - The cluster UUID
204
+ * @throws {RESTError}
205
+ */
206
+ getSecureConnectivityStatus(clusterUuid: string): Promise<Dto.SecureConnectivityStatusResponse>;
207
+ /**
208
+ *
209
+ * Activate External Monitoring (BYOM) for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/ActivateMonitoring) for more details.
210
+ * @param clusterUuid - The cluster UUID
211
+ * @throws {RESTError}
212
+ */
213
+ activateMonitoring(clusterUuid: string): Promise<void>;
214
+ /**
215
+ *
216
+ * Deactivate External Monitoring (BYOM) for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/DeactivateMonitoring) for more details.
217
+ * @param clusterUuid - The cluster UUID
218
+ * @throws {RESTError}
219
+ */
220
+ deactivateMonitoring(clusterUuid: string): Promise<void>;
221
+ /**
222
+ *
223
+ * Get all External Monitoring clients for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetMonitoringClients) for more details.
224
+ * @param clusterUuid - The cluster UUID
225
+ * @throws {RESTError}
226
+ */
227
+ getMonitoringClients(clusterUuid: string): Promise<Dto.MonitoringClientsResponse>;
228
+ /**
229
+ *
230
+ * Create a new External Monitoring client for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/CreateMonitoringClient) for more details.
231
+ * @param clusterUuid - The cluster UUID
232
+ * @param username - The username for the monitoring client
233
+ * @throws {RESTError}
234
+ */
235
+ createMonitoringClient(clusterUuid: string, username: string): Promise<Dto.CreatedMonitoringClient>;
236
+ /**
237
+ *
238
+ * Rotate the password for an External Monitoring client. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/RotateMonitoringClientPassword) for more details.
239
+ * @param clusterUuid - The cluster UUID
240
+ * @param clientUuid - The monitoring client UUID
241
+ * @throws {RESTError}
242
+ */
243
+ rotateMonitoringClientPassword(clusterUuid: string, clientUuid: string): Promise<Dto.CreatedMonitoringClient>;
244
+ /**
245
+ *
246
+ * Delete an External Monitoring client. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/DeleteMonitoringClient) for more details.
247
+ * @param clusterUuid - The cluster UUID
248
+ * @param clientUuid - The monitoring client UUID
249
+ * @throws {RESTError}
250
+ */
251
+ deleteMonitoringClient(clusterUuid: string, clientUuid: string): Promise<void>;
252
+ /**
253
+ *
254
+ * Get all backups for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetBackups) for more details.
255
+ * @param clusterUuid - The cluster UUID
256
+ * @throws {RESTError}
257
+ */
258
+ getBackups(clusterUuid: string): Promise<Dto.Backup[]>;
259
+ /**
260
+ *
261
+ * Create a new backup for a cluster. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/CreateBackup) for more details.
262
+ * @param clusterUuid - The cluster UUID
263
+ * @throws {RESTError}
264
+ */
265
+ createBackup(clusterUuid: string): Promise<Dto.Backup>;
266
+ /**
267
+ *
268
+ * Delete a backup. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/DeleteBackup) for more details.
269
+ * @param clusterUuid - The cluster UUID
270
+ * @param backupId - The backup ID
271
+ * @throws {RESTError}
272
+ */
273
+ deleteBackup(clusterUuid: string, backupId: string): Promise<Dto.Backup>;
274
+ /**
275
+ *
276
+ * Fetch all activity/audit events as JSON. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetJson) for more details.
277
+ * @throws {RESTError}
278
+ */
279
+ getActivityEvents(): Promise<Dto.AuditEvent[]>;
280
+ /**
281
+ *
282
+ * Fetch all activity/audit events as CSV. See [the API Documentation](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetCsv) for more details.
283
+ * @throws {RESTError}
284
+ */
285
+ getActivityEventsCsv(): Promise<string>;
140
286
  }