@camunda8/orchestration-cluster-api 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# [1.1.0](https://github.com/camunda/orchestration-cluster-api-js/compare/v1.0.0...v1.1.0) (2025-11-05)
+
+### Features
+
+- add CamundaSupportLogger ([2562abc](https://github.com/camunda/orchestration-cluster-api-js/commit/2562abc2849161d5a306fda19776eb30c2ab56b4))
+- enrich activated jobs with resolution methods ([2bbd361](https://github.com/camunda/orchestration-cluster-api-js/commit/2bbd36142abc21b34f9b9aaa16639efa6859835c))
+- log telemetry at trace level ([822bf29](https://github.com/camunda/orchestration-cluster-api-js/commit/822bf29f9ef6add9f6d5668e024f8376bf2483e8))
+- propagate cancel throw to caller ([c69fc0c](https://github.com/camunda/orchestration-cluster-api-js/commit/c69fc0c52881498c32b80da310a922892d92b06f))
+- use injected support logger ([b46606b](https://github.com/camunda/orchestration-cluster-api-js/commit/b46606bfd49e2dcf57e5e852a15142115188a4de))
+
 # 1.0.0 (2025-10-23)
 
 ### Bug Fixes

package/README.md

@@ -1,5 +1,3 @@
-<!-- Greenfield public README for the Camunda 8 Orchestration Cluster TypeScript SDK -->
-
 # Camunda 8 Orchestration Cluster TypeScript SDK (Pre‑release)
 
 Type‑safe, promise‑based client for the Camunda 8 Orchestration Cluster REST API.
@@ -15,7 +13,7 @@ Type‑safe, promise‑based client for the Camunda 8 Orchestration Cluster REST
 - Eventual consistency helper for polling endpoints
 - Immutable, deep‑frozen configuration accessible through a factory‑created client instance
 - Automatic body-level tenantId defaulting: if a request body supports an optional tenantId and you omit it, the SDK fills it from CAMUNDA_DEFAULT_TENANT_ID (path params are never auto-filled)
-- Automatic transient HTTP retry (429, 503, network) with exponential backoff + full jitter (configurable via CAMUNDA*SDK_HTTP_RETRY*\*). Non-retryable 500s fail fast. Pluggable strategy surface (default uses p-retry when available, internal fallback otherwise).
+- Automatic transient HTTP retry (429, 503, network) with exponential backoff + full jitter (configurable via CAMUNDA_SDK_HTTP_RETRY\*). Non-retryable 500s fail fast. Pluggable strategy surface (default uses p-retry when available, internal fallback otherwise).
 
 ## Install
 
@@ -193,7 +191,6 @@ const skip = new Set([
   'withCorrelation',
   'deployResourcesFromFiles',
 ]);
-
 for (const key of Object.keys(client)) {
   const val: any = (client as any)[key];
   if (typeof val === 'function' && !key.startsWith('_') && !skip.has(key)) {
@@ -205,6 +202,53 @@ for (const key of Object.keys(client)) {
 // Now every public operation is wrapped.
 ```
 
+## Support Logger (Node Only)
+
+For diagnostics during support interactions you can enable an auxiliary file logger that captures a sanitized snapshot of environment & configuration plus selected runtime events.
+
+Enable by setting one of:
+
+```bash
+CAMUNDA_SUPPORT_LOG_ENABLED=true        # canonical
+```
+
+Optional override for output path (default is `./camunda-support.log` in the current working directory):
+
+```bash
+CAMUNDA_SUPPORT_LOG_FILE_PATH=/var/log/camunda-support.log
+```
+
+Behavior:
+
+- File is created eagerly on first client construction (one per process; if the path exists a numeric suffix is appended to avoid clobbering).
+- Initial preamble includes SDK package version, timestamp, and redacted environment snapshot.
+- Secrets (client secret, passwords, mTLS private key, etc.) are automatically masked or truncated.
+- Designed to be low‑impact: append‑only, newline‑delimited JSON records may be added in future releases for deeper inspection (current version writes the preamble only unless additional events are wired).
+
+Recommended usage:
+
+```bash
+CAMUNDA_SUPPORT_LOG_ENABLED=1 CAMUNDA_SDK_LOG_LEVEL=debug node app.js
+```
+
+Keep the file only as long as needed for troubleshooting; it may contain sensitive non‑secret operational metadata. Do not commit it to version control.
+
+To disable, unset the env variable or set `CAMUNDA_SUPPORT_LOG_ENABLED=false`.
+
+Refer to `./docs/CONFIG_REFERENCE.md` for the full list of related environment variables.
+
+## Contributing
+
+We welcome issues and pull requests. Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) guide before opening a PR to understand:
+
+- Deterministic builds policy (no committed timestamps) – see CONTRIBUTING
+- Commit message conventions (Conventional Commits with enforced subject length)
+- Release workflow & how to dry‑run semantic‑release locally
+- Testing strategy (unit vs integration)
+- Performance and security considerations
+
+If you plan to help migrate to npm Trusted Publishing (OIDC), open an issue so we can coordinate workflow permission changes (`id-token: write`) and removal of the legacy `NPM_TOKEN` secret.
+
 ### Custom Classification Example
 
 Retry only network errors + 429/503, plus optionally 500 on safe GET endpoints you mark:
@@ -357,12 +401,11 @@ const worker = client.createJobWorker({
   outputSchema: Output, // validates variables passed to complete(...)
   validateSchemas: true, // set false for max throughput (skip Zod)
   autoStart: true, // default true; start polling immediately
-  jobHandler: async (job) => {
+  jobHandler: (job) => {
     // Access typed variables
     const vars = job.variables; // inferred from Input schema
     // Do work...
-    await job.complete({ variables: { processed: true } });
-    // Returning the receipt is optional; completion already acknowledges the job.
+    return job.complete({ variables: { processed: true } });
   },
 });
 
@@ -376,12 +419,46 @@ process.on('SIGINT', () => {
 
 Your `jobHandler` must ultimately invoke exactly one of:
 
-- `job.complete({ variables? })`
+- `job.complete({ variables? })` OR `job.complete()`
 - `job.fail({ errorMessage, retries?, retryBackoff? })`
-- `job.cancelWorkflow({})` / `job.cancel({})` (alias – cancels the process instance)
-- `job.ignore()` (marks as done locally without reporting to broker – only use for experimental flows)
+- `job.cancelWorkflow({})` (cancels the process instance)
+- `job.ignore()` (marks as done locally without reporting to broker – can be used for decoupled flows)
+
+Each action returns an opaque unique symbol receipt (`JobActionReceipt`). The handler's declared return type (`Promise<JobActionReceipt>`) is intentional:
 
-Each action returns an opaque unique symbol receipt (`JobActionReceipt`) primarily for internal/test assertions; you do not need to use it. If the handler returns without invoking an action the worker logs a warning and internally marks the job done (no completion sent) to prevent a leak.
+Why this design:
+
+- Enforces a single terminal code path: every successful handler path should end by returning the sentinal obtained by invoking an action.
+- Enables static reasoning: TypeScript can identify if your handler has a code path that does not acknowledge the job (catch unintended behavior early).
+- Makes test assertions simple: e.g. `expect(await job.complete()).toBe(JobActionReceipt)`.
+
+Acknowledgement lifecycle:
+
+- Calling any action (`complete`, `fail`, `cancelWorkflow`, `ignore`) sets `job.acknowledged = true` internally. This surfaces multiple job resolution code paths at runtime.
+- If the handler resolves (returns the symbol manually or via an action) without any acknowledgement having occurred, the worker logs `job.handler.noAction` and locally marks the job finished WITHOUT informing the broker (avoids a leak of the in-memory slot, but the broker will eventually time out and re-dispatch the job).
+
+Recommended usage:
+
+- Always invoke an action; if you truly mean to skip broker acknowledgement (for example: forwarding a job to another system which will complete it) use `job.ignore()`.
+
+Example patterns:
+
+```ts
+// GOOD: explicit completion
+return job.complete({ variables: { processed: true } });
+
+// GOOD: No-arg completion example, sentinel stored for ultimate return
+const ack = await job.complete();
+// ...
+return ack;
+
+// GOOD: explicit ignore
+const ack = await job.ignore();
+```
+
+```ts
+// No-arg completion example
+```
 
 ### Concurrency & Backpressure
 
@@ -397,7 +474,26 @@ If `validateSchemas` is true:
 
 ### Graceful Shutdown
 
-Call `worker.stop()` (or `client.stopAllWorkers()`) to cancel ongoing polling and prevent new activations. Jobs already handed to handlers can finish their HTTP completion/failure calls.
+Use `await worker.stopGracefully({ waitUpToMs?, checkIntervalMs? })` to drain without force‑cancelling the current activation request.
+
+```ts
+// Attempt graceful drain for up to 8 seconds
+const { remainingJobs, timedOut } = await worker.stopGracefully({ waitUpToMs: 8000 });
+if (timedOut) {
+  console.warn('Graceful stop timed out; remaining jobs:', remainingJobs);
+}
+```
+
+Behavior:
+
+- Stops scheduling new polls immediately.
+- Lets any in‑flight activation finish (not cancelled proactively).
+- Waits for active jobs to acknowledge (complete/fail/cancelWorkflow/ignore).
+- On timeout: falls back to hard stop semantics (cancels activation) and logs `worker.gracefulStop.timeout` at debug.
+
+For immediate termination call `worker.stop()` (or `client.stopAllWorkers()`) which cancels the in‑flight activation if present.
+
+Activation cancellations during stop are logged at debug (`activation.cancelled`) instead of error noise.
 
 ### Multiple Workers
 
@@ -427,7 +523,6 @@ For custom strategies you can still call `client.activateJobs(...)`, manage conc
 - Never increases latency for healthy clusters (no cap until first signal).
 - Cannot create fairness across multiple _processes_; it is per client instance in a single process. Scale your worker pool with that in mind.
 - Not a replacement for server‑side quotas or external rate limiters—it's a cooperative adaptive limiter.
-- Exempt list is minimal by design; adding more exemptions without care can reduce effectiveness.
 
 ### Opt‑Out
 
@@ -556,9 +651,21 @@ All methods return a `CancelablePromise<T>`:
 ```ts
 const p = camunda.searchProcessInstances({ filter: { processDefinitionKey: defKey } });
 setTimeout(() => p.cancel(), 100); // best‑effort cancel
-await p; // rejects with CancelError if aborted
+try {
+  await p; // resolves if not cancelled
+} catch (e) {
+  if (isSdkError(e) && e.name === 'CancelSdkError') {
+    console.log('Operation cancelled');
+  } else throw e;
+}
 ```
 
+Notes:
+
+- Rejects with `CancelSdkError`.
+- Cancellation classification runs first so aborted fetches are never downgraded to generic network errors.
+- Abort is immediate and idempotent; underlying fetch is signalled.
+
 ## Functional (fp-ts style) Surface (Opt-In Subpath)
 
 The main entry stays minimal. To opt in to a TaskEither-style facade & helper combinators import from the dedicated subpath:
@@ -783,7 +890,7 @@ May throw:
 - Non‑2xx HTTP responses
 - Validation errors (strict mode)
 - `EventualConsistencyTimeoutError`
-- `CancelError` on cancellation
+- `CancelSdkError` on cancellation
 
 ### Typed Error Handling
 
@@ -809,6 +916,9 @@ try {
       case 'AuthSdkError':
         console.error('Auth problem', e.message, e.status);
         break;
+      case 'CancelSdkError':
+        console.error('Operation cancelled', e.operationId);
+        break;
       case 'NetworkSdkError':
         console.error('Network layer error', e.message);
         break;
@@ -1006,29 +1116,3 @@ const client = createCamundaClient({
 ## License
 
 Apache 2.0
-
-## Deterministic Build Mode
-
-To eliminate spurious publish drift caused by timestamps and formatting churn in generated artifacts, the SDK supports a deterministic build mode gated by the environment variable `CAMUNDA_SDK_DETERMINISTIC_BUILD=1`.
-
-When set:
-
-- All generation scripts use a fixed timestamp (`1970-01-01T00:00:00.000Z`) instead of `new Date().toISOString()`.
-- Build info writer and doc generators produce stable content.
-- Upstream spec cloning still occurs, but we exclude auto-formatting of generated files via `.prettierignore` to avoid style oscillation.
-
-Release workflow strategy:
-
-1. Generate job runs with `CAMUNDA_SDK_DETERMINISTIC_BUILD=1`, producing canonical artifacts. If drift is detected they are committed on a temp branch and fast‑forwarded to `main`.
-2. Publish job re-runs the deterministic build and performs `git diff --exit-code` to assert zero drift before `semantic-release`.
-
-Local verification:
-
-```bash
-CAMUNDA_SDK_DETERMINISTIC_BUILD=1 npm run build
-git diff --exit-code  # should be clean after baseline committed
-```
-
-If you see persistent diff after following the above, ensure you have not manually edited generated files and that your local commit hooks (lint-staged) respect `.prettierignore`.
-
-Do not hand-edit files under `src/gen/`, `branding/branding-metadata.json`, `tests-integration/methods/manifest.json`, or `docs/CONFIG_REFERENCE.md`; regenerate instead.