@camunda8/sdk
Version:
[](https://www.npmjs.com/package/@camunda8/sdk)
472 lines (471 loc) • 22.3 kB
TypeScript
/// <reference types="node" />
/// <reference types="node" />
import { ReadStream } from 'node:fs';
import { Camunda8ClientConfiguration, CamundaPlatform8Configuration, LosslessDto } from '../../lib';
import { IOAuthProvider } from '../../oauth';
import { ActivateJobsRequest, BroadcastSignalReq, CompleteJobRequest, ErrorJobWithVariables, FailJobRequest, IProcessVariables, JobCompletionInterfaceRest, JSONDoc, PublishMessageRequest, TopologyResponse } from '../../zeebe/types';
import { AssignUserTaskRequest, BroadcastSignalResponse, CorrelateMessageResponse, CreateDocumentLinkRequest, CreateDocumentLinkResponse, CreateProcessInstanceReq, CreateProcessInstanceResponse, Ctor, DeployResourceResponse, DownloadDocumentRequest, EvaluateDecisionRequest, EvaluateDecisionResponse, JobUpdateChangeset, MigrationRequest, ModifyProcessInstanceRequest, NewUserInfo, PatchAuthorizationRequest, PublishMessageResponse, RestJob, SearchProcessInstanceRequest, SearchProcessInstanceResponse, SearchTasksRequest, SearchUserTasksResponse, SearchVariablesRequest, SearchVariablesResponse, TaskChangeSet, UpdateElementVariableRequest, UploadDocumentRequest, UploadDocumentResponse, UploadDocumentsResponse, UserTask, UserTaskVariablesRequest, UserTaskVariablesResponse } from './C8Dto';
import { Logger } from './C8Logger';
import { CamundaJobWorker, CamundaJobWorkerConfig } from './CamundaJobWorker';
/**
* The client for the unified Camunda 8 REST API.
*
* Logging: to enable debug tracing during development, you can set `DEBUG=camunda:zeebe-rest`.
*
* For production, you can pass in an instance of [winston.Logger](https://github.com/winstonjs/winston) to the constructor as `logger`.
*
* `CAMUNDA_LOG_LEVEL` in the environment or the constructor options can be used to set the log level to one of 'error', 'warn', 'info', 'http', 'verbose', 'debug', or 'silly'.
*
* @since 8.6.0
*/
export declare class CamundaRestClient {
private userAgentString;
private oAuthProvider;
private rest;
private tenantId?;
log: Logger;
private config;
private prefixUrl;
/**
* All constructor parameters for configuration are optional. If no configuration is provided, the SDK will use environment variables to configure itself.
*/
constructor(options?: {
config?: Camunda8ClientConfiguration;
oAuthProvider?: IOAuthProvider;
});
private getHeaders;
/**
* Manage the permissions assigned to authorization.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/patch-authorization/
*
* @since 8.6.0
*/
modifyAuthorization(req: PatchAuthorizationRequest): Promise<unknown>;
/**
* Broadcast a signal.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/broadcast-signal/
*
* @since 8.6.0
*/
broadcastSignal(req: BroadcastSignalReq): Promise<BroadcastSignalResponse>;
getTopology(): Promise<TopologyResponse>;
/**
* Complete a user task with the given key. The method either completes the task or throws 400, 404, or 409.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/zeebe-api-rest/specifications/complete-a-user-task/
*
* @since 8.6.0
*/
completeUserTask({ userTaskKey, variables, action, }: {
userTaskKey: string;
variables?: Record<string, unknown>;
action?: string;
}): Promise<void>;
/**
* Assign a user task with the given key to the given assignee.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/assign-user-task/
*
* @since 8.6.0
* @deprecated use `assignUserTask`
*/
assignTask({ userTaskKey, assignee, allowOverride, action, }: AssignUserTaskRequest): Promise<void>;
/**
* Assign a user task with the given key to the given assignee.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/assign-user-task/
*
* @since 8.6.0
*/
assignUserTask({ userTaskKey, assignee, allowOverride, action, }: AssignUserTaskRequest): Promise<void>;
/**
* Update a user task with the given key.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/update-user-task/
*
* @since 8.6.0
* @deprecated use `updateUserTask`
*/
updateTask({ userTaskKey, changeset, }: {
userTaskKey: string;
changeset: TaskChangeSet;
}): Promise<void>;
/**
* Update a user task with the given key.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/update-user-task/
*
* @since 8.6.0
*/
updateUserTask({ userTaskKey, changeset, }: {
userTaskKey: string;
changeset: TaskChangeSet;
}): Promise<void>;
/**
* Remove the assignee of a task with the given key.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/unassign-user-task/
*
* @since 8.6.0
* @deprecated use `unassignUserTask`
*/
unassignTask({ userTaskKey, }: {
userTaskKey: string;
}): Promise<void>;
/**
* Remove the assignee of a task with the given key.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/unassign-user-task/
*
* @since 8.6.0
*/
unassignUserTask({ userTaskKey, }: {
userTaskKey: string;
}): Promise<void>;
/**
* Search for user tasks based on given criteria.
*
* Documentation: https://docs.camunda.io/docs/8.7/apis-tools/camunda-api-rest/specifications/find-user-tasks/
*
* @since 8.8.0 - alpha status in 8.6 and 8.7
*/
searchUserTasks(request: SearchTasksRequest): Promise<SearchUserTasksResponse>;
/**
* Get the user task by the user task key.
*
* Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/get-user-task/
*
* @since 8.8.0
*/
getUserTask(userTaskKey: string): Promise<UserTask>;
/**
*
* Search for user task variables based on given criteria.
*
* Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/find-user-task-variables/
*
* @since 8.8.0
*/
searchUserTaskVariables(request: UserTaskVariablesRequest): Promise<UserTaskVariablesResponse>;
/**
* Create a user.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/create-user/
*
* @since 8.6.0
*/
createUser(newUserInfo: NewUserInfo): Promise<unknown>;
/**
* Search for user tasks based on given criteria.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/query-user-tasks-alpha/
* @since 8.8.0
*/
/**
* Publish a Message and correlates it to a subscription. If correlation is successful it will return the first process instance key the message correlated with.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/correlate-a-message/
*
* @since 8.6.0
*/
correlateMessage(message: Pick<PublishMessageRequest, 'name' | 'correlationKey' | 'variables' | 'tenantId'>): Promise<CorrelateMessageResponse>;
/**
* Publish a single message. Messages are published to specific partitions computed from their correlation keys. This method does not wait for a correlation result. Use `correlateMessage` for such use cases.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/publish-a-message/
*
* @since 8.6.0
*/
publishMessage(publishMessageRequest: PublishMessageRequest): Promise<PublishMessageResponse>;
/**
* Obtains the status of the current Camunda license.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/get-status-of-camunda-license/
*
* @since 8.6.0
*/
getLicenseStatus(): Promise<{
vaildLicense: boolean;
licenseType: string;
}>;
/**
* Create a new polling Job Worker.
* You can pass in an optional winston.Logger instance as `logger`. This enables you to have distinct logging levels for different workers.
*
* Polling: The worker polls periodically. If no jobs are available, the poll stays open for 10 seconds.
* If no jobs become available in that time, the poll is closed, and the worker polls again.
* When jobs are available, they are returned, and the worker polls again for more jobs as soon as it has capacity for more jobs.
*
* @since 8.6.0
*/
createJobWorker<Variables extends LosslessDto, CustomHeaders extends LosslessDto>(config: CamundaJobWorkerConfig<Variables, CustomHeaders>): CamundaJobWorker<Variables, CustomHeaders>;
/**
* Iterate through all known partitions and activate jobs up to the requested maximum.
*
* The parameter `inputVariablesDto` is a Dto to decode the job payload. The `customHeadersDto` parameter is a Dto to decode the custom headers.
* Pass in a Dto class that extends LosslessDto to provide both type information in your code,
* and safe interoperability with applications that use the `int64` type in variables.
*
* @since 8.6.0
*/
activateJobs<VariablesDto extends LosslessDto, CustomHeadersDto extends LosslessDto>(request: ActivateJobsRequest & {
inputVariableDto?: Ctor<VariablesDto>;
customHeadersDto?: Ctor<CustomHeadersDto>;
}): Promise<(RestJob<VariablesDto, CustomHeadersDto> & JobCompletionInterfaceRest<IProcessVariables>)[]>;
/**
* Fails a job using the provided job key. This method sends a POST request to the endpoint '/jobs/{jobKey}/fail' with the failure reason and other details specified in the failJobRequest object.
*
* Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/fail-job/
*
* @since 8.6.0
*/
failJob(failJobRequest: FailJobRequest): Promise<"JOB_ACTION_ACKNOWLEDGEMENT">;
/**
* Report a business error (i.e. non-technical) that occurs while processing a job.
*
* Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/report-error-for-job/
*
* @since 8.6.0
*/
errorJob(errorJobRequest: ErrorJobWithVariables & {
jobKey: string;
}): Promise<"JOB_ACTION_ACKNOWLEDGEMENT">;
/**
* Complete a job with the given payload, which allows completing the associated service task.
*
* Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/complete-job/
*
* @since 8.6.0
*/
completeJob(completeJobRequest: CompleteJobRequest): Promise<"JOB_ACTION_ACKNOWLEDGEMENT">;
/**
* Update a job with the given key.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/update-a-job/
*
* @since 8.6.0
*/
updateJob(jobChangeset: JobUpdateChangeset & {
jobKey: string;
}): Promise<import("got").Response<string>>;
/**
* Marks the incident as resolved; most likely a call to Update job will be necessary to reset the job's retries, followed by this call.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/resolve-incident/
*
* @since 8.6.0
*/
resolveIncident(incidentKey: string): Promise<import("got").Response<string>>;
/**
* Create and start a process instance. This method does not await the outcome of the process. For that, use `createProcessInstanceWithResult`.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/create-process-instance/
*
* @since 8.6.0
*/
createProcessInstance<T extends JSONDoc | LosslessDto>(request: CreateProcessInstanceReq<T>): Promise<CreateProcessInstanceResponse<never>>;
/**
* Create and start a process instance. This method awaits the outcome of the process.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/create-process-instance/
*
* @since 8.6.0
*/
createProcessInstanceWithResult<T extends JSONDoc | LosslessDto>(request: CreateProcessInstanceReq<T> & {
/** An array of variable names to fetch. If not supplied, all visible variables in the root scope will be returned */
fetchVariables?: string[];
}): Promise<CreateProcessInstanceResponse<unknown>>;
createProcessInstanceWithResult<T extends JSONDoc | LosslessDto, V extends LosslessDto>(request: CreateProcessInstanceReq<T> & {
/** An array of variable names to fetch. If not supplied, all visible variables in the root scope will be returned */
fetchVariables?: string[];
/** A Dto specifying the shape of the output variables. If not supplied, the output variables will be returned as a `LosslessDto` of type `unknown`. */
outputVariablesDto: Ctor<V>;
}): Promise<CreateProcessInstanceResponse<V>>;
/**
* Cancel an active process instance
*/
cancelProcessInstance({ processInstanceKey, operationReference, }: {
processInstanceKey: string;
operationReference?: number;
}): Promise<import("got").Response<string>>;
/**
* Migrates a process instance to a new process definition.
* This request can contain multiple mapping instructions to define mapping between the active process instance's elements and target process definition elements.
* Use this to upgrade a process instance to a new version of a process or to a different process definition, e.g. to keep your running instances up-to-date with the latest process improvements.
*
* Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/migrate-process-instance/
*
* @since 8.6.0
*/
migrateProcessInstance(req: MigrationRequest): Promise<import("got").Response<string>>;
/**
* Query process instances
*
* Documentation: https://docs.camunda.io/docs/8.7/apis-tools/camunda-api-rest/specifications/query-process-instances-alpha/
*
* @since 8.8.0
*/
searchProcessInstances(request: SearchProcessInstanceRequest): Promise<SearchProcessInstanceResponse>;
/**
* Deploy resources to the broker.
* @param resources - An array of binary data strings representing the resources to deploy.
* @param tenantId - Optional tenant ID to deploy the resources to. If not provided, the default tenant ID is used.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/deploy-resources/
*
* @since 8.6.0
*/
deployResources(resources: {
content: string;
name: string;
}[], tenantId?: string): Promise<DeployResourceResponse>;
/**
* Deploy resources to Camunda 8 from files
* @param files an array of file paths
*
* @since 8.6.0
*/
deployResourcesFromFiles(files: string[], { tenantId }?: {
tenantId?: string;
}): Promise<DeployResourceResponse>;
/**
* Deletes a deployed resource. This can be a process definition, decision requirements definition, or form definition deployed using the deploy resources endpoint. Specify the resource you want to delete in the resourceKey parameter.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/delete-resource/
*
* @since 8.6.0
*/
deleteResource(req: {
resourceKey: string;
operationReference?: number;
}): Promise<import("got").Response<string>>;
/**
* Set a precise, static time for the Zeebe engine's internal clock.
* When the clock is pinned, it remains at the specified time and does not advance.
* To change the time, the clock must be pinned again with a new timestamp, or reset.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/pin-internal-clock/
*
* @since 8.6.0
*/
pinInternalClock(epochMs: number): Promise<import("got").Response<string>>;
/**
* Resets the Zeebe engine's internal clock to the current system time, enabling it to tick in real-time.
* This operation is useful for returning the clock to normal behavior after it has been pinned to a specific time.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/reset-internal-clock/
*
* @since 8.6.0
*/
resetClock(): Promise<import("got").Response<string>>;
/**
* Updates all the variables of a particular scope (for example, process instance, flow element instance) with the given variable data.
* Specify the element instance in the elementInstanceKey parameter.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/update-element-instance-variables/
*
* @since 8.6.0
*/
updateElementInstanceVariables(req: UpdateElementVariableRequest): Promise<import("got").Response<string>>;
getConfig(): CamundaPlatform8Configuration;
/**
* Search for process and local variables based on given criteria.
*
* Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/find-variables/
* @since 8.8.0
*/
searchVariables(req: SearchVariablesRequest): Promise<SearchVariablesResponse>;
/**
* Download a document from the Camunda 8 cluster.
*
* Note that this is currently supported for document stores of type: AWS, GCP, in-memory, local
* Documentation: https://docs.camunda.io/docs/8.7/apis-tools/camunda-api-rest/specifications/get-document/
*
* @since 8.7.0
*/
downloadDocument(request: DownloadDocumentRequest): Promise<Buffer>;
/**
* Upload a document to the Camunda 8 cluster.
* Note that this is currently supported for document stores of type: AWS, GCP, in-memory, local
*
* Documentation: https://docs.camunda.io/docs/8.7/apis-tools/camunda-api-rest/specifications/create-document/
* @since 8.7.0
*/
uploadDocument(request: UploadDocumentRequest): Promise<UploadDocumentResponse>;
/**
* Delete a document from the Camunda 8 cluster.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/delete-document/
*
* @since 8.7.0
*/
deleteDocument({ documentId, storeId, }: {
documentId: string;
storeId?: string;
}): Promise<void>;
/**
*
* Upload multiple documents to the Camunda 8 cluster.
* The caller must provide a file name for each document, which will be used in case of a multi-status response to identify which documents failed to upload.
* The file name can be provided in the Content-Disposition header of the file part or in the fileName field of the metadata part.
* If both are provided, the fileName field takes precedence.
*
* In case of a multi-status response, the response body will contain a list of DocumentBatchProblemDetail objects,
* each of which contains the file name of the document that failed to upload and the reason for the failure.
* The client can choose to retry the whole batch or individual documents based on the response.
*
* Note that this is currently supported for document stores of type: AWS, GCP, in-memory (non-production), local (non-production)
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/create-documents/
* @since 8.7.0
*/
uploadDocuments(request: {
/** The ID of the document store to upload the documents to. Currently, only a single document store is supported per cluster.
* However, this attribute is included to allow for potential future support of multiple document stores.
**/
storeId?: string;
files: ReadStream[];
}): Promise<UploadDocumentsResponse>;
/**
* Create document link
*
* Create a link to a document in the Camunda 8 cluster.
* Note that this is currently supported for document stores of type: AWS, GCP
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/create-document-link/
* @since 8.7.0
*/
createDocumentLink(request: CreateDocumentLinkRequest): Promise<CreateDocumentLinkResponse>;
/**
* Modify process instance
*
* Modifies a running process instance. This request can contain multiple instructions to activate an element of the process or to terminate an active instance of an element.
* Use this to repair a process instance that is stuck on an element or took an unintended path. For example, because an external system is not available or doesn't respond as expected.
*
* Documentation https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/modify-process-instance/
* @since 8.6.0
*/
modifyProcessInstance(request: ModifyProcessInstanceRequest): Promise<void>;
/**
* Evaluate decision
*
* Evaluates a decision. You specify the decision to evaluate either by using its unique key (as returned by DeployResource), or using the decision ID.
* When using the decision ID, the latest deployed version of the decision is used.
*
* Documentation: https://docs.camunda.io/docs/apis-tools/camunda-api-rest/specifications/evaluate-decision/
* @since 8.6.0
*/
evaluateDecision(request: EvaluateDecisionRequest): Promise<EvaluateDecisionResponse>;
/**
* Helper method to add the default job methods to a job
* @param job The job to add the methods to
* @returns The job with the added methods
*/
private addJobMethods;
/**
* Helper method to add the default tenantIds if we are not passed explicit tenantIds
*/
private addDefaultTenantId;
}