@camunda8/sdk

# Agent Information for Camunda 8 JavaScript SDK This file contains information for AI agents working on the Camunda 8 JavaScript SDK repository. ## Project Overview 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. ## Essential Commands ### Build & Compilation ```bash npm run build # Clean, compile TypeScript, and copy proto files npm run clean # Remove dist folder and build artifacts npm run compile # Compile TypeScript to JavaScript ``` ### Testing ```bash npm test # Run unit tests only npm run test:integration # Run integration tests (requires Docker) npm run test:local # Run local integration tests npm run test:smoketest # Build and run smoke tests npm run test:c8run # Run Camunda 8 specific tests ``` ### Code Quality ```bash npm run lint # Run ESLint on TypeScript files npm run format # Format code with Prettier ``` ### Development Environment ```bash npm run sm:start # Start Docker Compose for Self-Managed Camunda 8 npm run sm:stop # Stop Docker Compose services npm run sm:start8.8 # Start Camunda 8.8 specific environment npm run sm:stop8.8 # Stop Camunda 8.8 environment ``` ### Documentation ```bash npm run docs # Generate TypeDoc documentation npm run docs:watch # Generate and watch docs for changes ``` ## Project Structure ``` src/ ├── index.ts # Main entry point ├── lib/ # Common utilities and base classes ├── c8/ # Camunda 8 unified client and REST API │ ├── index.ts # Camunda8 main class │ └── lib/ │ ├── C8Dto.ts # Data Transfer Objects for REST API │ └── CamundaRestClient.ts # REST API client implementation ├── zeebe/ # Zeebe gRPC and REST clients ├── operate/ # Operate API client ├── optimize/ # Optimize API client ├── tasklist/ # Tasklist API client ├── modeler/ # Web Modeler API client ├── admin/ # Admin API client ├── oauth/ # OAuth authentication providers └── __tests__/ # Test files organized by component ``` ## Key Architecture Patterns ### Client Pattern - Each API has its own client class (e.g., `OperateApiClient`, `TasklistApiClient`) - All clients are instantiated through the main `Camunda8` factory class - Clients support both SaaS and Self-Managed configurations ### DTO Pattern - Data Transfer Objects (DTOs) extend `LosslessDto` for int64 handling - Use decorators like `@Int64String` for precise number handling - Search request DTOs extend `BaseSearchRequest<TSortFields, TFilter>` or `BaseSearchRequestWithOptionalFilter<TSortFields, TFilter>` - Response DTOs use `PaginatedCamundaRestSearchResponse<T>` pattern for consistent pagination ### Authentication - OAuth2/OIDC support for SaaS - Basic auth and custom auth providers for Self-Managed - Token caching and automatic refresh ### Pagination - **CamundaRestClient**: Uses `startCursor`/`endCursor` (string values) - **Other APIs**: Use `firstSortValues`/`lastSortValues` or `sortValues` (arrays) ## Testing Patterns ### Test Organization - Unit tests: `*.unit.spec.ts` - Mock external dependencies - Integration tests: `*.integration.spec.ts` - Test against real services - Local integration: `*local-integration.spec.ts` - Test local Docker setup ### Test Environment Variables - `CAMUNDA_UNIT_TEST=true` - Forces unit test mode - Various `ZEEBE_*`, `OPERATE_*` environment variables for service configuration - Integration tests use environment files from `env/` directory (e.g., `env/8.8-alpha.env`) ### Test Utilities - Use `jest` as the test framework - Tests are organized by component in `src/__tests__/` - Integration tests require either Docker services or sourced environment variables - **Running Integration Tests**: `source env/8.8-alpha.env && npx jest path/to/test.rest.spec.ts` - **Running Unit Tests**: `npm test -- --testPathPattern="testname.unit"` ## Common Development Tasks ### Adding New Search Endpoints 1. Define filter interface (e.g., `ProcessInstanceSearchFilter`) 2. Extend `BaseSearchRequest<TSortFields, TFilter>` or `BaseSearchRequestWithOptionalFilter<TSortFields, TFilter>` 3. Define details interface for response items (e.g., `DecisionInstanceDetails`) 4. Create `CamundaRest*Response` interface extending `PaginatedCamundaRestSearchResponse<DetailsType>` 5. Add method to `CamundaRestClient` using `callApiEndpoint` pattern 6. Write comprehensive unit tests with mocked `callApiEndpoint` 7. Write integration tests that source environment variables from `env/` directory ### Adding New API Clients 1. Create client class in appropriate directory (e.g., `src/newservice/`) 2. Define DTOs in `*Dto.ts` file 3. Add client factory method to main `Camunda8` class 4. Export client from main `index.ts` ### Handling Authentication - Clients accept `IHeadersProvider` for custom auth - Use `constructOAuthProvider()` for standard OAuth flows - Set appropriate environment variables for configuration ## Important Files - `src/c8/lib/C8Dto.ts` - Main DTO definitions for REST API - `src/c8/lib/CamundaRestClient.ts` - Unified REST API client - `src/lib/Configuration.ts` - Configuration management - `src/lib/LosslessDto.ts` - Base class for DTOs with int64 support - `package.json` - Scripts and dependencies - `tsconfig.json` - TypeScript configuration ## Common Issues & Solutions ### Build Issues - Run `npm run clean` before building if encountering cache issues - Ensure all imports use correct relative paths - Check for TypeScript errors with `npm run compile` ### Test Issues - Integration tests require Docker services: `npm run sm:start` - Use `npm run test` for unit tests only - Check test environment variables are set correctly ### Authentication Issues - Verify OAuth configuration for SaaS - Check basic auth credentials for Self-Managed - Ensure certificates are properly configured for custom CA ## Code Style Guidelines - Use TypeScript strict mode - Follow existing patterns for DTO definitions - Use `LosslessDto` base class for API responses - Prefer composition over inheritance for client features - Write comprehensive JSDoc comments for public APIs ## Recent Additions ### Search Decision Instances API - `searchDecisionInstances()` method in `CamundaRestClient` - `DecisionInstanceSearchFilter` and `SearchDecisionInstancesRequest` DTOs - `CamundaRestSearchDecisionInstancesResponse` with cursor-based pagination - Comprehensive unit and integration tests - Follows established patterns for search endpoints ## Dependencies Key dependencies to be aware of: - `got` - HTTP client library - `@grpc/grpc-js` - gRPC client - `lossless-json` - JSON parsing with int64 support - `form-data` - Multipart form handling - `jest` - Testing framework