@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/AGENT.md CHANGED
@@ -1,54 +1,143 @@
1
1
  # Agent Information for Camunda 8 JavaScript SDK
2
2
 
3
- This file contains information for AI agents working on the Camunda 8 JavaScript SDK repository.
3
+ This file is the **canonical** instruction document for AI agents (Copilot, Claude, etc.) working on the Camunda 8 JavaScript SDK repository. It supersedes the previous `.github/copilot-instructions.md`.
4
+
5
+ See also:
6
+
7
+ - [CONTRIBUTING.md](CONTRIBUTING.md) — contributor onboarding, branch model, release summary
8
+ - [MAINTAINER.md](MAINTAINER.md) — operational guide (CI workflows, semantic-release, npm publishing)
9
+
10
+ ---
4
11
 
5
12
  ## Project Overview
6
13
 
7
- The Camunda 8 JavaScript SDK is the official TypeScript/Node.js SDK for Camunda Platform 8. It provides unified access to all Camunda 8 APIs including Zeebe, Operate, Optimize, Tasklist, Modeler, and Admin.
14
+ The Camunda 8 JavaScript SDK is the official TypeScript/Node.js client library for Camunda Platform 8. It provides unified access to all Camunda 8 APIs including Zeebe, Operate, Optimize, Tasklist, Modeler, and Admin. It targets Node.js (not browser) and ships TypeScript typings.
15
+
16
+ ### Key Features
17
+
18
+ - Full-featured clients for all Camunda 8 services
19
+ - Support for both SaaS and Self-Managed deployments
20
+ - OAuth authentication with token management
21
+ - Specialized handling for int64 values through the `LosslessDto` system
22
+ - Comprehensive testing suite for unit and integration tests
23
+
24
+ ---
25
+
26
+ ## Commit Conventions (read this before committing)
27
+
28
+ The repo enforces [Conventional Commits](https://www.conventionalcommits.org/) via `commitlint` (see [commitlint.config.js](commitlint.config.js)). The CI job `lint-commits` will block PRs that violate these rules.
29
+
30
+ ### Allowed commit types
31
+
32
+ Only these `type:` values are accepted (any other type — including `deps:` — will fail `lint-commits`):
33
+
34
+ | Type | When to use | Release impact |
35
+ | -------------- | ----------------------------------------------------------- | -------------- |
36
+ | `feat` | New SDK feature | patch |
37
+ | `fix` | Bug fix | patch |
38
+ | `perf` | Performance improvement | patch |
39
+ | `revert` | Revert a previous commit | patch |
40
+ | `release` | Force a patch release with no other eligible commits | patch |
41
+ | `server` | Bump to a new Camunda **minor** line (e.g. 8.8 → 8.9) | minor |
42
+ | `server-major` | Bump to a new Camunda **major** line (e.g. 8.x → 9.0) | major |
43
+ | `chore` | Maintenance, dependency bumps (`chore(deps): ...`), tooling | none |
44
+ | `build` | Build system / packaging changes | none |
45
+ | `ci` | CI workflow / GitHub Actions changes | none |
46
+ | `docs` | Documentation only | none |
47
+ | `refactor` | Code refactor with no behavior change | none |
48
+ | `style` | Whitespace / formatting only | none |
49
+ | `test` | Test-only changes | none |
50
+
51
+ Note the **mutated semver**: `feat`/`fix` produce **patch** bumps, not minor/major. The SDK's version tracks the Camunda 8 server line, not its own API surface. See [MAINTAINER.md](MAINTAINER.md) for the full release pipeline.
52
+
53
+ ### Scopes
54
+
55
+ `commitlint` does not enforce a scope-enum, so any scope is accepted. Use scopes when they clarify the change (e.g. `chore(deps): ...`, `fix(zeebe): ...`, `ci(release): ...`).
56
+
57
+ ### Format constraints
58
+
59
+ - Body lines: max **500** characters per line (`body-max-line-length`).
60
+ - Footer lines: max **1000** characters per line (`footer-max-line-length`).
61
+ - Header (first line): conventional-commits default — keep concise.
62
+
63
+ ### Common pitfalls
64
+
65
+ - **`deps:` is not valid.** Use `chore(deps): ...` for dependency pinning / bumps. (Renovate is configured to use `chore(deps):` as well.)
66
+ - The pre-commit Husky hook runs `npm run test`, which can fail on local-only files (e.g. nested worktrees). The release workflow bypasses this with `HUSKY=0`. For agent commits that are otherwise validated, prefix with `HUSKY=0` rather than `--no-verify`.
67
+
68
+ ---
8
69
 
9
70
  ## Essential Commands
10
71
 
11
72
  ### Build & Compilation
73
+
12
74
  ```bash
13
- npm run build # Clean, compile TypeScript, and copy proto files
75
+ npm run build # Clean, compile TypeScript, copy proto files
14
76
  npm run clean # Remove dist folder and build artifacts
15
77
  npm run compile # Compile TypeScript to JavaScript
16
78
  ```
17
79
 
18
80
  ### Testing
81
+
82
+ The repo uses **vitest** (not jest, despite older docs).
83
+
84
+ ```bash
85
+ npm test # Run unit tests only (CAMUNDA_UNIT_TEST=true)
86
+ npm run test:smoketest # Build + smoke test + tsd typings check
87
+ npm run test:8.8:sm # 8.8 self-managed integration
88
+ npm run test:8.8:saas # 8.8 SaaS integration
89
+ npm run test:8.7:sm # 8.7 self-managed integration
90
+ npm run test:8.7:mt # 8.7 multi-tenancy integration
91
+ npm run test:8.7:saas # 8.7 SaaS integration
92
+ npm run test:c8run # C8Run integration
93
+ ```
94
+
95
+ Run a single test file:
96
+
19
97
  ```bash
20
- npm test # Run unit tests only
21
- npm run test:integration # Run integration tests (requires Docker)
22
- npm run test:local # Run local integration tests
23
- npm run test:smoketest # Build and run smoke tests
24
- npm run test:c8run # Run Camunda 8 specific tests
98
+ # Unit test — source unit env first
99
+ . env/unit-test.env && CAMUNDA_UNIT_TEST=true npx vitest run --testTimeout=30000 ${testFile}
100
+
101
+ # Integration test — source the appropriate env file
102
+ . env/8.8-alpha.env && npx vitest run --testTimeout=30000 ${testFile}
25
103
  ```
26
104
 
27
105
  ### Code Quality
106
+
28
107
  ```bash
29
- npm run lint # Run ESLint on TypeScript files
30
- npm run format # Format code with Prettier
108
+ npm run lint # ESLint on src/**/*.ts
109
+ npm run format # Prettier --write on src/**/*.ts
110
+
111
+ # Single file:
112
+ npx prettier --write 'src/${filename}'
113
+ npx eslint 'src/${filename}'
31
114
  ```
32
115
 
33
116
  ### Development Environment
117
+
34
118
  ```bash
35
- npm run sm:start # Start Docker Compose for Self-Managed Camunda 8
36
- npm run sm:stop # Stop Docker Compose services
37
- npm run sm:start8.8 # Start Camunda 8.8 specific environment
38
- npm run sm:stop8.8 # Stop Camunda 8.8 environment
119
+ npm run sm:start # Start Docker Compose (Self-Managed Camunda 8)
120
+ npm run sm:stop # Stop Docker Compose
121
+ npm run sm:start:8.8 # Start 8.8 stack
122
+ npm run sm:stop:8.8 # Stop 8.8 stack
123
+ npm run sm:start:8.9 # Start 8.9 stack
124
+ npm run sm:stop:8.9 # Stop 8.9 stack
39
125
  ```
40
126
 
41
127
  ### Documentation
128
+
42
129
  ```bash
43
- npm run docs # Generate TypeDoc documentation
44
- npm run docs:watch # Generate and watch docs for changes
130
+ npm run docs # Generate TypeDoc docs
131
+ npm run docs:watch # Generate + watch
45
132
  ```
46
133
 
134
+ ---
135
+
47
136
  ## Project Structure
48
137
 
49
138
  ```
50
139
  src/
51
- ├── index.ts # Main entry point
140
+ ├── index.ts # Main entry point and exports
52
141
  ├── lib/ # Common utilities and base classes
53
142
  ├── c8/ # Camunda 8 unified client and REST API
54
143
  │ ├── index.ts # Camunda8 main class
@@ -57,125 +146,365 @@ src/
57
146
  │ └── CamundaRestClient.ts # REST API client implementation
58
147
  ├── zeebe/ # Zeebe gRPC and REST clients
59
148
  ├── operate/ # Operate API client
60
- ├── optimize/ # Optimize API client
149
+ ├── optimize/ # Optimize API client
61
150
  ├── tasklist/ # Tasklist API client
62
151
  ├── modeler/ # Web Modeler API client
63
152
  ├── admin/ # Admin API client
64
153
  ├── oauth/ # OAuth authentication providers
65
- └── __tests__/ # Test files organized by component
154
+ └── __tests__/ # Test files organized by component and version
66
155
  ```
67
156
 
157
+ ### Important Files
158
+
159
+ - `src/c8/lib/C8Dto.ts` — Main DTO definitions for REST API
160
+ - `src/c8/lib/CamundaRestClient.ts` — Unified REST API client
161
+ - `src/lib/Configuration.ts` — Configuration management
162
+ - `src/lib/LosslessDto.ts` — Base class for DTOs with int64 support
163
+ - `package.json` — Scripts and dependencies
164
+ - `tsconfig.json` — TypeScript configuration
165
+ - `commitlint.config.js` — Allowed commit types
166
+ - `release.config.js` — semantic-release branch + dist-tag rules
167
+
168
+ ---
169
+
68
170
  ## Key Architecture Patterns
69
171
 
70
- ### Client Pattern
71
- - Each API has its own client class (e.g., `OperateApiClient`, `TasklistApiClient`)
72
- - All clients are instantiated through the main `Camunda8` factory class
73
- - Clients support both SaaS and Self-Managed configurations
172
+ ### 1. Client Factory Pattern
173
+
174
+ - The main `Camunda8` class is the factory for all service clients.
175
+ - Configuration is centralized in the factory and passed to individual clients.
176
+ - Clients are created via methods like `getCamundaRestClient()`, `getZeebeGrpcApiClient()`, `getOperateClient()`, `getTasklistClient()`, etc.
177
+ - Clients support both SaaS and Self-Managed configurations.
178
+
179
+ ### 2. DTO Pattern
180
+
181
+ - DTOs live in `*Dto.ts` files.
182
+ - Most DTOs extend `LosslessDto` for int64 handling.
183
+ - Use decorators like `@Int64String` for int64 fields.
184
+ - Always follow existing patterns when adding new DTOs.
185
+
186
+ ```typescript
187
+ export class SomeEntityDto extends LosslessDto {
188
+ @Int64String
189
+ entityKey!: string
190
+ name!: string
191
+ // Other fields...
192
+ }
193
+ ```
194
+
195
+ ### 3. Pagination
196
+
197
+ - **`CamundaRestClient`**: cursor-based — `startCursor` / `endCursor` (string values).
198
+ - **Other APIs (Operate, Tasklist, …)**: `firstSortValues` / `lastSortValues` or `sortValues` (arrays).
199
+
200
+ ### 4. Authentication
201
+
202
+ The SDK supports five authentication strategies (set via `CAMUNDA_AUTH_STRATEGY` or programmatically):
203
+
204
+ | Strategy | Use case |
205
+ | -------- | ----------------------------------------- |
206
+ | `OAUTH` | Default for Camunda SaaS and Self-Managed |
207
+ | `BASIC` | Nginx reverse-proxy with basic auth |
208
+ | `COOKIE` | C8Run 8.7 |
209
+ | `BEARER` | Custom token management |
210
+ | `NONE` | Development or mTLS |
211
+
212
+ - Clients accept `IHeadersProvider` for custom auth.
213
+ - Use `constructOAuthProvider()` for standard OAuth flows.
214
+ - Token caching and automatic refresh are built in.
215
+
216
+ ### 5. Code formatting and linting
217
+
218
+ - Prettier formats code; ESLint lints it.
219
+ - Configs: `prettier.config.js`, `.eslintrc.json`.
220
+ - The Husky pre-commit hook runs `lint-staged` (Prettier on staged TS files) plus `npm run test`.
221
+
222
+ ---
223
+
224
+ ## REST API Endpoint Pattern
225
+
226
+ When implementing a new REST API endpoint:
227
+
228
+ 1. Review the REST API documentation to understand the endpoint.
229
+ 2. Create request/response DTOs in the appropriate `*Dto.ts` file.
230
+ 3. Add appropriate decorators like `@Int64String` for int64 fields.
231
+ 4. Add the method to the relevant client class.
232
+ 5. Use the `callApiEndpoint` pattern.
233
+ 6. Document parameters with JSDoc.
234
+ 7. Include proper error handling.
235
+ 8. Write comprehensive unit and integration tests.
236
+
237
+ ```typescript
238
+ /**
239
+ * Gets a specific decision instance by ID
240
+ * @param decisionInstanceId The ID of the decision instance to retrieve
241
+ * @returns A GetDecisionInstanceResponse object with the decision instance details
242
+ */
243
+ async getDecisionInstance(
244
+ decisionInstanceId: string
245
+ ): Promise<GetDecisionInstanceResponse> {
246
+ return this.callApiEndpoint({
247
+ method: 'get',
248
+ path: `decision-instances/${decisionInstanceId}`,
249
+ responseType: GetDecisionInstanceResponse,
250
+ })
251
+ }
252
+ ```
253
+
254
+ ### Full example: GET endpoint
255
+
256
+ ```typescript
257
+ // In C8Dto.ts
258
+ export class GetEntityRequest extends LosslessDto {
259
+ @Int64String
260
+ entityId!: string
261
+ }
262
+
263
+ export class EntityDetails extends LosslessDto {
264
+ @Int64String
265
+ entityKey!: string
266
+ name!: string
267
+ creationTime!: string
268
+ state!: string
269
+ }
270
+
271
+ // In CamundaRestClient.ts
272
+ /**
273
+ * Gets an entity by ID
274
+ * @param entityId The ID of the entity to retrieve
275
+ * @returns An EntityDetails object with entity information
276
+ */
277
+ async getEntity(entityId: string): Promise<EntityDetails> {
278
+ return this.callApiEndpoint<UnknownRequestBody, EntityDetails>({
279
+ method: 'get',
280
+ path: `entities/${entityId}`,
281
+ })
282
+ }
283
+ ```
74
284
 
75
- ### DTO Pattern
76
- - Data Transfer Objects (DTOs) extend `LosslessDto` for int64 handling
77
- - Use decorators like `@Int64String` for precise number handling
78
- - Search request DTOs extend `BaseSearchRequest<TSortFields, TFilter>` or `BaseSearchRequestWithOptionalFilter<TSortFields, TFilter>`
79
- - Response DTOs use `PaginatedCamundaRestSearchResponse<T>` pattern for consistent pagination
285
+ ### Search endpoints
286
+
287
+ For implementing search endpoints:
288
+
289
+ 1. Define the filter interface (e.g. `SomeEntitySearchFilter`).
290
+ 2. Extend `BaseSearchRequest<TSortFields, TFilter>` or `BaseSearchRequestWithOptionalFilter<TSortFields, TFilter>`.
291
+ 3. Define a response interface extending `PaginatedCamundaRestSearchResponse<EntityDetails>`.
292
+ 4. Use cursor-based pagination with `startCursor` / `endCursor` for REST API endpoints.
293
+
294
+ ```typescript
295
+ // In C8Dto.ts
296
+ export interface EntitySearchFilter {
297
+ state?: string
298
+ name?: string
299
+ }
300
+
301
+ export type EntitySortFields = 'creationTime' | 'name'
302
+
303
+ export class SearchEntitiesRequest extends BaseSearchRequest<
304
+ EntitySortFields,
305
+ EntitySearchFilter
306
+ > {}
307
+
308
+ export class CamundaRestSearchEntitiesResponse extends PaginatedCamundaRestSearchResponse<EntityDetails> {}
309
+
310
+ // In CamundaRestClient.ts
311
+ /**
312
+ * Search for entities
313
+ * @param request The search request with filters and sorting options
314
+ * @returns A paginated response with entity details
315
+ */
316
+ async searchEntities(
317
+ request: SearchEntitiesRequest
318
+ ): Promise<CamundaRestSearchEntitiesResponse> {
319
+ return this.callApiEndpoint<SearchEntitiesRequest, CamundaRestSearchEntitiesResponse>({
320
+ method: 'post',
321
+ path: 'entities/search',
322
+ body: request,
323
+ })
324
+ }
325
+ ```
326
+
327
+ ### Handling int64 Values
80
328
 
81
- ### Authentication
82
- - OAuth2/OIDC support for SaaS
83
- - Basic auth and custom auth providers for Self-Managed
84
- - Token caching and automatic refresh
329
+ - Always use the `@Int64String` decorator for int64 fields in DTOs.
330
+ - Extend `LosslessDto` for request and response DTOs.
331
+ - Follow existing patterns for handling large numbers.
85
332
 
86
- ### Pagination
87
- - **CamundaRestClient**: Uses `startCursor`/`endCursor` (string values)
88
- - **Other APIs**: Use `firstSortValues`/`lastSortValues` or `sortValues` (arrays)
333
+ ---
89
334
 
90
335
  ## Testing Patterns
91
336
 
92
337
  ### Test Organization
93
- - Unit tests: `*.unit.spec.ts` - Mock external dependencies
94
- - Integration tests: `*.integration.spec.ts` - Test against real services
95
- - Local integration: `*local-integration.spec.ts` - Test local Docker setup
338
+
339
+ - Unit tests: `*.unit.spec.ts` — mock external dependencies.
340
+ - Integration tests: `*.integration.spec.ts` (and `*.rest.spec.ts`) — test against real services.
341
+ - Local integration: `*local-integration.spec.ts` — local Docker setup.
342
+ - Tests are organized by component and version under `src/__tests__/`.
96
343
 
97
344
  ### Test Environment Variables
98
- - `CAMUNDA_UNIT_TEST=true` - Forces unit test mode
99
- - Various `ZEEBE_*`, `OPERATE_*` environment variables for service configuration
100
- - Integration tests use environment files from `env/` directory (e.g., `env/8.8-alpha.env`)
101
345
 
102
- ### Test Utilities
103
- - Use `jest` as the test framework
104
- - Tests are organized by component in `src/__tests__/`
105
- - Integration tests require either Docker services or sourced environment variables
106
- - **Running Integration Tests**: `source env/8.8-alpha.env && npx jest path/to/test.rest.spec.ts`
107
- - **Running Unit Tests**: `npm test -- --testPathPattern="testname.unit"`
346
+ - `CAMUNDA_UNIT_TEST=true` — forces unit-test mode.
347
+ - `TEST_DEPLOYMENT`, `TEST_VERSION`, `TEST_TENANCY`, `TEST_SECURITY` — gate which integration suites run.
348
+ - Various `ZEEBE_*`, `CAMUNDA_*` environment variables for service configuration.
349
+ - Integration tests source environment files from `env/` (e.g. `env/8.8-alpha.env`, `env/unit-test.env`).
350
+
351
+ ### Test Implementation Guidelines
352
+
353
+ **Unit tests:**
354
+
355
+ - Mock external dependencies and API calls.
356
+ - Test error handling paths.
357
+ - Validate proper parameter passing.
358
+ - Run a single unit test file:
359
+ ```bash
360
+ . env/unit-test.env && CAMUNDA_UNIT_TEST=true npx vitest run --testTimeout=30000 ${testFile}
361
+ ```
362
+
363
+ **Integration tests:**
364
+
365
+ - Deploy required resources (BPMN, DMN) before testing.
366
+ - Clean up resources after tests.
367
+ - Source environment variables from `env/`.
368
+ - Handle async operations with proper timeouts.
369
+ - Validate response DTOs with assertions.
370
+ - Run a single integration test file:
371
+ ```bash
372
+ . env/8.8-alpha.env && npx vitest run --testTimeout=30000 ${testFile}
373
+ ```
374
+
375
+ **BPMN / DMN test resources:**
376
+
377
+ - Place test models in `src/__tests__/<version>/resources/` (e.g. `src/__tests__/8.8/resources/`).
378
+ - For DMN decision tables, use the **`FIRST`** hit policy (not `UNIQUE`).
379
+ - Validate that resources are deployed before exercising them.
380
+
381
+ ### Example test structure
382
+
383
+ ```typescript
384
+ describe('SomeClient.someMethod', () => {
385
+ let client: SomeClient
386
+
387
+ beforeAll(async () => {
388
+ // Setup resources and client
389
+ })
390
+
391
+ it('should correctly handle the happy path', async () => {
392
+ // Test implementation
393
+ // Assert expected behavior
394
+ })
395
+
396
+ it('should handle error conditions', async () => {
397
+ // Test error paths
398
+ // Assert error handling
399
+ })
400
+ })
401
+ ```
402
+
403
+ ---
108
404
 
109
405
  ## Common Development Tasks
110
406
 
111
- ### Adding New Search Endpoints
112
- 1. Define filter interface (e.g., `ProcessInstanceSearchFilter`)
113
- 2. Extend `BaseSearchRequest<TSortFields, TFilter>` or `BaseSearchRequestWithOptionalFilter<TSortFields, TFilter>`
114
- 3. Define details interface for response items (e.g., `DecisionInstanceDetails`)
115
- 4. Create `CamundaRest*Response` interface extending `PaginatedCamundaRestSearchResponse<DetailsType>`
116
- 5. Add method to `CamundaRestClient` using `callApiEndpoint` pattern
117
- 6. Write comprehensive unit tests with mocked `callApiEndpoint`
118
- 7. Write integration tests that source environment variables from `env/` directory
119
-
120
- ### Adding New API Clients
121
- 1. Create client class in appropriate directory (e.g., `src/newservice/`)
122
- 2. Define DTOs in `*Dto.ts` file
123
- 3. Add client factory method to main `Camunda8` class
124
- 4. Export client from main `index.ts`
125
-
126
- ### Handling Authentication
127
- - Clients accept `IHeadersProvider` for custom auth
128
- - Use `constructOAuthProvider()` for standard OAuth flows
129
- - Set appropriate environment variables for configuration
130
-
131
- ## Important Files
132
-
133
- - `src/c8/lib/C8Dto.ts` - Main DTO definitions for REST API
134
- - `src/c8/lib/CamundaRestClient.ts` - Unified REST API client
135
- - `src/lib/Configuration.ts` - Configuration management
136
- - `src/lib/LosslessDto.ts` - Base class for DTOs with int64 support
137
- - `package.json` - Scripts and dependencies
138
- - `tsconfig.json` - TypeScript configuration
407
+ ### Adding a New REST API Endpoint
408
+
409
+ See [REST API Endpoint Pattern](#rest-api-endpoint-pattern) above. Summary:
410
+
411
+ 1. Review the REST API spec.
412
+ 2. Create request/response DTOs in `*Dto.ts` (with `@Int64String` decorators where needed).
413
+ 3. Add the client method using `callApiEndpoint`.
414
+ 4. Write unit + integration tests.
415
+
416
+ ### Adding a New Search Endpoint
417
+
418
+ See [Search endpoints](#search-endpoints) above. Summary:
419
+
420
+ 1. Define filter interface.
421
+ 2. Extend `BaseSearchRequest<TSortFields, TFilter>` or `BaseSearchRequestWithOptionalFilter<TSortFields, TFilter>`.
422
+ 3. Define details interface for response items.
423
+ 4. Define response interface extending `PaginatedCamundaRestSearchResponse<DetailsType>`.
424
+ 5. Add method to `CamundaRestClient` using `callApiEndpoint`.
425
+ 6. Write unit tests with mocked `callApiEndpoint`.
426
+ 7. Write integration tests sourcing env files.
427
+
428
+ ### Adding a New API Client
429
+
430
+ 1. Create the client class in an appropriate directory (e.g. `src/newservice/`).
431
+ 2. Define DTOs in a `*Dto.ts` file.
432
+ 3. Add a client factory method to the `Camunda8` class.
433
+ 4. Export the client from `src/index.ts`.
434
+
435
+ ---
436
+
437
+ ## Coding Guidelines
438
+
439
+ See [STYLE.md](STYLE.md) for the codebase's control-flow, iteration, and state
440
+ philosophy (immutable by default, guard-clause conditionals, declarative
441
+ iteration). New code should match it.
442
+
443
+ 1. Use TypeScript strict mode.
444
+ 2. Add detailed JSDoc comments to public methods.
445
+ 3. Follow existing naming conventions.
446
+ 4. Write comprehensive tests for all new functionality.
447
+ 5. Include both unit and integration tests.
448
+ 6. Maintain backward compatibility.
449
+ 7. Use meaningful variable and function names.
450
+ 8. Follow the existing error handling patterns.
451
+ 9. Use `LosslessDto` base class for API responses.
452
+ 10. Prefer composition over inheritance for client features.
453
+
454
+ ## Documentation Guidelines
455
+
456
+ - Include JSDoc comments for all public methods and classes.
457
+ - Document parameters, return types, and thrown exceptions.
458
+ - Include examples for complex functionality.
459
+ - Keep documentation up-to-date with code changes.
460
+
461
+ ---
139
462
 
140
463
  ## Common Issues & Solutions
141
464
 
142
465
  ### Build Issues
143
- - Run `npm run clean` before building if encountering cache issues
144
- - Ensure all imports use correct relative paths
145
- - Check for TypeScript errors with `npm run compile`
146
466
 
147
- ### Test Issues
148
- - Integration tests require Docker services: `npm run sm:start`
149
- - Use `npm run test` for unit tests only
150
- - Check test environment variables are set correctly
467
+ - Run `npm run clean` before building if encountering cache issues.
468
+ - Ensure all imports use correct relative paths.
469
+ - Check for TypeScript errors with `npm run compile`.
470
+
471
+ ### Test Issues
472
+
473
+ - Integration tests require Docker services: `npm run sm:start` (or one of the version-specific variants).
474
+ - Use `npm run test` for unit tests only.
475
+ - Verify test environment variables are set (source the right file from `env/`).
151
476
 
152
477
  ### Authentication Issues
153
- - Verify OAuth configuration for SaaS
154
- - Check basic auth credentials for Self-Managed
155
- - Ensure certificates are properly configured for custom CA
156
478
 
157
- ## Code Style Guidelines
479
+ - Verify OAuth configuration for SaaS.
480
+ - Check basic-auth credentials for Self-Managed.
481
+ - Ensure certificates are properly configured for custom CA.
482
+
483
+ ### Commit Rejected by `lint-commits`
484
+
485
+ - Confirm the type is in the [allowed commit types](#allowed-commit-types) table. `deps:` is the most common mistake — use `chore(deps):` instead.
158
486
 
159
- - Use TypeScript strict mode
160
- - Follow existing patterns for DTO definitions
161
- - Use `LosslessDto` base class for API responses
162
- - Prefer composition over inheritance for client features
163
- - Write comprehensive JSDoc comments for public APIs
487
+ ---
488
+
489
+ ## Dependencies
490
+
491
+ Key dependencies to be aware of:
492
+
493
+ - `@camunda8/orchestration-cluster-api` — generated REST client (pinned to 8.x; see [MAINTAINER.md](MAINTAINER.md))
494
+ - `@grpc/grpc-js` — gRPC client
495
+ - `lossless-json` — JSON parsing with int64 support
496
+ - `form-data` — Multipart form handling
497
+ - `vitest` — test framework
498
+ - `got` — HTTP client (legacy paths)
499
+
500
+ ---
164
501
 
165
502
  ## Recent Additions
166
503
 
167
504
  ### Search Decision Instances API
168
- - `searchDecisionInstances()` method in `CamundaRestClient`
505
+
506
+ - `searchDecisionInstances()` method on `CamundaRestClient`
169
507
  - `DecisionInstanceSearchFilter` and `SearchDecisionInstancesRequest` DTOs
170
508
  - `CamundaRestSearchDecisionInstancesResponse` with cursor-based pagination
171
509
  - Comprehensive unit and integration tests
172
510
  - Follows established patterns for search endpoints
173
-
174
- ## Dependencies
175
-
176
- Key dependencies to be aware of:
177
- - `got` - HTTP client library
178
- - `@grpc/grpc-js` - gRPC client
179
- - `lossless-json` - JSON parsing with int64 support
180
- - `form-data` - Multipart form handling
181
- - `jest` - Testing framework