@camunda8/orchestration-cluster-api 10.0.0-alpha.1 → 10.0.0-alpha.11

package/CHANGELOG.md

@@ -1,3 +1,87 @@
+# [10.0.0-alpha.11](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.10...v10.0.0-alpha.11) (2026-06-11)
+
+
+### Bug Fixes
+
+* adopt upstream wait-state details union in example ([8f8603c](https://github.com/camunda/orchestration-cluster-api-js/commit/8f8603cd1ed445ab8062c15d525598a5c36084d4))
+* adopt upstream wait-state details union in example ([07ed89c](https://github.com/camunda/orchestration-cluster-api-js/commit/07ed89c0eb2db17f7979ebd57c88983f8561a137))
+
+# [10.0.0-alpha.10](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.9...v10.0.0-alpha.10) (2026-06-09)
+
+
+### Bug Fixes
+
+* apply eventual consistency only to first searchVariablesAsDto search ([29387b0](https://github.com/camunda/orchestration-cluster-api-js/commit/29387b0b478e0c9a4d1dd0eaaf82c0481be5ddd8))
+* **deps:** bump camunda-schema-bundler to 2.4.3 for IterationId generation ([16a7c5d](https://github.com/camunda/orchestration-cluster-api-js/commit/16a7c5ddccc52b60b0dab3efc6048daaba687013))
+* **deps:** bump camunda-schema-bundler to 2.4.3 for IterationId generation ([8a8cdae](https://github.com/camunda/orchestration-cluster-api-js/commit/8a8cdae5fe9327a991e9670e4aeb50c6d8591356))
+* wait for all declared variables at the collection level for searchVariablesAsDto ([ba2f911](https://github.com/camunda/orchestration-cluster-api-js/commit/ba2f911e1d6254d25ac68c3ebfaa690ef0d9067a))
+
+
+### Features
+
+* add searchVariablesAsDto for DTO-driven typed variable maps ([52a544f](https://github.com/camunda/orchestration-cluster-api-js/commit/52a544fcc37f7ecc86fcfa153859baf6cf653b9b))
+* add searchVariablesAsDto for DTO-driven typed variable maps ([67418f2](https://github.com/camunda/orchestration-cluster-api-js/commit/67418f2f9ccbdc8b535b82cb8a66ec77b66143e0))
+
+# [10.0.0-alpha.9](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.8...v10.0.0-alpha.9) (2026-06-04)
+
+
+### Bug Fixes
+
+* pass author-association to community notification workflow ([82e7f6e](https://github.com/camunda/orchestration-cluster-api-js/commit/82e7f6e5b34c60d122b93a302c84dda1fc28f6f9))
+
+# [10.0.0-alpha.8](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.7...v10.0.0-alpha.8) (2026-06-04)
+
+
+### Features
+
+* add Slack notifications for release failures and community events ([051e782](https://github.com/camunda/orchestration-cluster-api-js/commit/051e78230ce2a2eeda53bdc604a99a783e4b5caa))
+* add Slack notifications for release failures and community events ([2981264](https://github.com/camunda/orchestration-cluster-api-js/commit/29812649034d2e961d65a7a80bd8bb2590e77dc1))
+
+# [10.0.0-alpha.7](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.6...v10.0.0-alpha.7) (2026-05-18)
+
+
+### Bug Fixes
+
+* update docker-compose env vars for 8.10 config schema ([d343d56](https://github.com/camunda/orchestration-cluster-api-js/commit/d343d56a54d6b83246e3a2b26b6ce2469c2de77c))
+
+# [10.0.0-alpha.6](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.5...v10.0.0-alpha.6) (2026-05-13)
+
+
+### Features
+
+* add example coverage for 4 new operations ([3a2c875](https://github.com/camunda/orchestration-cluster-api-js/commit/3a2c87577bcca87996cc77546216c68fb5124ec5))
+* add example coverage for 4 new operations ([6d757a4](https://github.com/camunda/orchestration-cluster-api-js/commit/6d757a4be85ba733f07bcd08c1b6ae33aacd6c15))
+
+# [10.0.0-alpha.5](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.4...v10.0.0-alpha.5) (2026-05-08)
+
+
+### Features
+
+* add agent instance example coverage ([8a0072d](https://github.com/camunda/orchestration-cluster-api-js/commit/8a0072d03cf426ea895863d7cbdd87178c2e7e2f))
+* v10 migration — bundler 2.4.1, branded type examples, README ([dd4a714](https://github.com/camunda/orchestration-cluster-api-js/commit/dd4a7149682b89d1f8f9c0f627dfef5645b10ea7)), closes [#203](https://github.com/camunda/orchestration-cluster-api-js/issues/203) [#204](https://github.com/camunda/orchestration-cluster-api-js/issues/204)
+
+# [10.0.0-alpha.4](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.3...v10.0.0-alpha.4) (2026-04-29)
+
+
+### Bug Fixes
+
+* **gen:** apply CAMUNDA_DEFAULT_TENANT_ID to activateJobs tenantIds ([fb7c661](https://github.com/camunda/orchestration-cluster-api-js/commit/fb7c661ba1f24dcfcfd738c6e344df09a2e2c52d))
+
+# [10.0.0-alpha.3](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.2...v10.0.0-alpha.3) (2026-04-29)
+
+
+### Bug Fixes
+
+* **docker:** resolve ambiguous numberOfReplicas config ([ab81098](https://github.com/camunda/orchestration-cluster-api-js/commit/ab810980e7dc3b820f6630ba36b1e191e1dd04ae))
+* getResource is now eventually consistent ([60d6c93](https://github.com/camunda/orchestration-cluster-api-js/commit/60d6c9398934cf5786d444d88472ec8198705ee5))
+
+# [10.0.0-alpha.2](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.1...v10.0.0-alpha.2) (2026-04-14)
+
+
+### Bug Fixes
+
+* update RELEASE.md with correct promotion procedure and troubleshooting ([10660be](https://github.com/camunda/orchestration-cluster-api-js/commit/10660be8743465c9cd5370af7eed3999972a0716))
+
 # [10.0.0-alpha.1](https://github.com/camunda/orchestration-cluster-api-js/compare/v9.1.0-alpha.1...v10.0.0-alpha.1) (2026-04-14)
 
 

package/README.md

@@ -149,10 +149,51 @@ await camunda.createDeployment({
 });
 ```
 
-`TenantId.assumeExists()` validates the string against the tenant ID pattern and brands it at zero runtime cost. See [Branded Keys](#branded-keys) for more on this pattern.
+`TenantId.assumeExists()` validates the string against the tenant ID pattern and returns a branded value. The branded value is just a string at runtime, but `assumeExists()` performs validation and can throw if the input is malformed. See [Branded Keys](#branded-keys) for more on this pattern.
 
 > **Tip**: If your tenant ID comes from a validated source (environment variable, config file), call `TenantId.assumeExists()` once at startup and pass the branded value throughout your application.
 
+## Migrating from 8.9
+
+SDK 10.x (for Camunda 8.10) promotes several identifier and name fields from plain `string` to **branded types** via `CamundaKey<T>`. The wire format and runtime API are unchanged — branded values are still plain strings at runtime and are assignable anywhere a `string` is expected (template literals, logging, JSON serialization). Callers need to brand values using `.assumeExists()` (which performs validation) to satisfy the new types.
+
+### New branded types
+
+| Brand | Used for |
+|-------|----------|
+| `RoleId` | Role identifiers |
+| `GroupId` | Group identifiers |
+| `ClientId` | OAuth client identifiers |
+| `MappingRuleId` | Mapping-rule identifiers |
+| `ClusterVariableName` | Cluster variable names |
+| `AgentInstanceKey` | Agent-instance system keys |
+
+### Migration
+
+<!-- snippet-source: examples/readme.ts | regions: V9ToV10Migration -->
+
+```ts
+// v9 — plain strings were accepted
+// await camunda.assignRoleToGroup({
+//   roleId: 'developer',
+//   groupId: 'engineering',
+// });
+
+// v10 — use the branded type helpers at the boundary
+await camunda.assignRoleToGroup({
+  roleId: RoleId.assumeExists('developer'),
+  groupId: GroupId.assumeExists('engineering'),
+});
+```
+
+Each branded type has an `.assumeExists()` method that validates the string and returns the branded value. Validation runs at call time and can throw if the input is malformed, so call it once at the boundary (startup, config parsing, API response) and pass the branded value through your application. See [Branded Keys](#branded-keys) for more on this pattern.
+
+### What does NOT change
+
+- The wire format is unchanged — all values are still strings on the wire.
+- No method signatures changed name or arity.
+- Branded values are assignable anywhere a `string` is expected (template literals, logging, JSON serialization), so existing string-handling code continues to work.
+
 ## Quick Start (Zero‑Config – Recommended)
 
 Keep configuration out of application code. Let the factory read `CAMUNDA_*` variables from the environment (12‑factor style). This makes rotation, secret management, and environment promotion safer & simpler.
@@ -576,6 +617,41 @@ Benchmark results against a single-node local cluster with multiple independent
 
 BALANCED wins 3 of 4 on pure throughput. The only scenario where LEGACY is faster is extreme overload (800 concurrent requests against a single broker) — and in that case LEGACY accumulates 44,505 errors vs BALANCED's 15,527. The default just works.
 
+## Typed Variable Map (DTO-driven search)
+
+`searchVariablesAsDto` fetches process variables and binds them to a [Zod](https://zod.dev) schema that acts as the DTO. The schema's keys are the exact variable names to fetch, and its shape drives validation. Only the declared variables are queried (via a `name $in [...]` filter), so memory stays bound by the DTO shape rather than the total number of variables on the instance. Results are paged internally until every declared variable is found or the result set is exhausted.
+
+The returned `VariableMap` offers two access modes:
+
+- **Lenient** — `has(name)` / `get(name)` for defensive reads that never throw on missing variables.
+- **Strict** — `validate()` returns a fully-typed object, or throws a `ZodError` when a required variable is missing or malformed.
+
+If a declared variable is found at more than one scope (for example a local variable shadowing a process-level one), the search throws a `VariableScopeCollisionError` rather than silently picking one. Pass an explicit `scopeKey` to disambiguate.
+
+<!-- snippet-source: examples/readme.ts | regions: ReadmeTypedVariables -->
+
+```ts
+// The Zod schema is the DTO: its keys are the variable names to fetch, and its
+// shape drives validation. Only these declared variables are queried, so memory
+// stays bound by the DTO — not by the total number of variables on the instance.
+const OrderVariables = z.object({
+  orderId: z.string(), // required
+  amount: z.number().optional(), // optional
+});
+
+const map = await camunda.searchVariablesAsDto(OrderVariables, { processInstanceKey });
+
+// Lenient access: defensive reads that never throw on missing variables.
+if (map.has('amount')) {
+  console.log('Amount:', map.get('amount'));
+}
+
+// Strict access: returns a fully-typed object, or throws a ZodError when a
+// required variable is missing or malformed.
+const order = map.validate(); // { orderId: string; amount?: number }
+console.log('Order:', order.orderId);
+```
+
 ## Job Workers (Polling API)
 
 The SDK provides a lightweight polling job worker for service task job types using `createJobWorker`. It activates jobs in batches (respecting a concurrency limit), validates variables (optional), and offers action helpers on each job.
@@ -681,6 +757,7 @@ Example patterns:
 return job.complete({ variables: { processed: true } });
 
 // GOOD: No-arg completion example, sentinel stored for ultimate return
+// biome-ignore lint/correctness/noUnreachable: intentional — showing multiple completion patterns
 const ack = await job.complete();
 // ...
 return ack;