@5minds/processcube_engine_client 6.3.0-develop.1 → 6.3.0-develop.2

package/README.md

@@ -1,201 +1,712 @@
-# Engine Client.ts
-
-Ein NodeJS basierter Client zur Kommunikation mit der ProcessCube Engine.
+# ProcessCube Engine Client
+
+TypeScript-Client zur Kommunikation mit der ProcessCube Engine via REST und Socket.IO.
+
+- **Paketname:** `@5minds/processcube_engine_client`
+- **Lizenz:** MIT
+- **Plattformen:** Node.js, Browser
+
+## Inhaltsverzeichnis
+
+- [Installation](#installation)
+- [Schnelleinstieg](#schnelleinstieg)
+- [Architektur](#architektur)
+- [EngineClient](#engineclient)
+- [ClientFactory](#clientfactory)
+- [Authentifizierung](#authentifizierung)
+- [Prozesse starten](#prozesse-starten)
+- [UserTasks](#usertasks)
+- [External Tasks](#external-tasks)
+  - [Konzept](#konzept)
+  - [Lebenszyklus eines ExternalTasks](#lebenszyklus-eines-externaltasks)
+  - [ExternalTaskWorker](#externaltaskworker)
+  - [Worker-Konfiguration](#worker-konfiguration)
+  - [Processing Function](#processing-function)
+  - [Fehlerbehandlung](#fehlerbehandlung)
+  - [Lock-Verlängerung](#lock-verlängerung)
+  - [Health Monitoring](#health-monitoring)
+  - [Heartbeat Monitoring](#heartbeat-monitoring)
+  - [Graceful Shutdown](#graceful-shutdown)
+  - [Multi-Topic Worker](#multi-topic-worker)
+  - [Payload-Filter](#payload-filter)
+  - [ExternalTask REST API](#externaltask-rest-api)
+- [Echtzeit-Events via Socket.IO](#echtzeit-events-via-socketio)
+- [Alle verfügbaren Clients](#alle-verfügbaren-clients)
+
+## Installation
+
+```bash
+npm install @5minds/processcube_engine_client
+```
 
 ## Schnelleinstieg
 
 ```ts
 import { EngineClient } from '@5minds/processcube_engine_client';
 
-const engineUri = 'http://localhost:10560';
+const client = new EngineClient('http://localhost:10560');
+
+const processInstances = await client.processInstances.query({
+  correlationId: 'my-correlation-id',
+});
+```
+
+## Architektur
+
+Der Client ist modular aufgebaut. Der `EngineClient` bündelt spezialisierte Sub-Clients, die jeweils einen fachlichen Bereich der Engine abdecken. Die Kommunikation erfolgt über REST (HTTP) und Socket.IO (WebSocket).
+
+```mermaid
+graph TB
+    App[Anwendung]
+    EC[EngineClient]
+
+    subgraph "Sub-Clients"
+        PM[ProcessModels]
+        PI[ProcessInstances]
+        UT[UserTasks]
+        ET[ExternalTasks]
+        MT[ManualTasks]
+        CO[Correlations]
+        EV[Events]
+        NO[Notifications]
+        PD[ProcessDefinitions]
+        CR[Cronjobs]
+        FN[FlowNodeInstances]
+        DO[DataObjectInstances]
+        AI[ApplicationInfo]
+        UNT[UntypedTasks]
+    end
+
+    subgraph "Kommunikation"
+        HTTP[HttpClient<br/>REST / fetch]
+        SIO[SocketIoManager<br/>Socket.IO]
+    end
+
+    Engine[ProcessCube Engine]
+
+    App --> EC
+    EC --> PM & PI & UT & ET & MT & CO & EV & NO & PD & CR & FN & DO & AI & UNT
+    PM & PI & UT & ET & MT & CO & CR & FN & DO & AI & UNT & PD --> HTTP
+    EV & NO --> SIO
+    HTTP --> Engine
+    SIO --> Engine
+```
+
+## EngineClient
+
+Der `EngineClient` ist der zentrale Einstiegspunkt. Er erstellt alle Sub-Clients und verwaltet die Socket.IO-Verbindung.
+
+```ts
+import { EngineClient } from '@5minds/processcube_engine_client';
+
+const client = new EngineClient('http://localhost:10560');
+
+// Sub-Clients als Properties
+client.processModels;
+client.processInstances;
+client.userTasks;
+client.externalTasks;
+client.manualTasks;
+client.correlations;
+client.events;
+client.notification;
+client.processDefinitions;
+client.cronjobs;
+client.flowNodeInstances;
+client.dataObjectInstances;
+client.applicationInfo;
+client.untypedTasks;
+
+// Aufräumen
+client.dispose();
+```
+
+## ClientFactory
+
+Alternativ lassen sich einzelne Clients gezielt erstellen, wenn nur ein bestimmter fachlicher Bereich benötigt wird:
+
+```ts
+import { ClientFactory } from '@5minds/processcube_engine_client';
+
+const engineUrl = 'http://localhost:10560';
 
-const client = new EngineClient(engineUri);
+const processInstanceClient = ClientFactory.createProcessInstanceClient(engineUrl);
 
-const processInstancesInCorrelation = await client.processInstances.query({
-  correlationid: 'my-correlation-id',
+const processInstances = await processInstanceClient.query({
+  correlationId: 'my-correlation-id',
 });
 ```
 
-## Wie kann ich den Client verwenden?
+Verfügbare Factory-Methoden:
+
+| Methode                            | Beschreibung                               |
+| ---------------------------------- | ------------------------------------------ |
+| `createProcessModelClient()`       | Prozessmodelle deployen, starten, abfragen |
+| `createProcessInstanceClient()`    | Prozessinstanzen abfragen und verwalten    |
+| `createProcessDefinitionClient()`  | Prozessdefinitionen verwalten              |
+| `createUserTaskClient()`           | UserTasks abfragen und abschließen         |
+| `createExternalTaskClient()`       | ExternalTasks abonnieren und verarbeiten   |
+| `createManualTaskClient()`         | ManualTasks abfragen und abschließen       |
+| `createUntypedTaskClient()`        | Untypisierte Tasks verwalten               |
+| `createCorrelationClient()`        | Correlations abfragen                      |
+| `createEventClient()`              | BPMN-Events senden und empfangen           |
+| `createNotificationClient()`       | Echtzeit-Benachrichtigungen                |
+| `createCronJobClient()`            | Cronjobs verwalten                         |
+| `createFlowNodeInstanceClient()`   | FlowNode-Instanzen abfragen                |
+| `createDataObjectInstanceClient()` | DataObjects abfragen                       |
+| `createApplicationInfoClient()`    | Engine-Metadaten abfragen                  |
+
+## Authentifizierung
 
-Man benötigt lediglich die URL der anzusteuernden Engine.
-Mit dieser lässt sich eine Instanz des Clients anlegen, die direkt verwendbar ist.
+Der Client unterstützt verschiedene Authentifizierungsarten:
 
-Es gibt verschiedene Wege sich Clients anzulegen.
+### Statischer Token
+
+```ts
+import { EngineClient, Identity } from '@5minds/processcube_engine_client';
 
-### EngineClient
+const identity: Identity = { token: 'Bearer my-jwt-token', userId: 'user123' };
+const client = new EngineClient('http://localhost:10560', identity);
+```
 
-Man kann eine Instanz des `EngineClients` direkt anlegen, welche die API der ProcessCube Engine vollständig abdeckt.
+### Dynamischer Token (Callback)
 
 ```ts
 import { EngineClient } from '@5minds/processcube_engine_client';
 
-const engineUri = 'http://localhost:10560';
+const client = new EngineClient('http://localhost:10560', async () => {
+  const token = await fetchTokenFromAuthProvider();
+  return { token, userId: 'user123' };
+});
+```
 
-const client = new EngineClient(engineUri);
+### Client Credentials (OAuth2)
+
+```ts
+import { EngineClient, ClientCredentialsConfig } from '@5minds/processcube_engine_client';
 
-const processInstancesInCorrelation = await client.processInstances.query({
-  correlationid: 'my-correlation-id',
+const credentials: ClientCredentialsConfig = {
+  clientId: 'my-client-id',
+  clientSecret: 'my-client-secret',
+  authority: 'https://auth.example.com',
+  scope: 'engine',
+};
+
+const client = new EngineClient('http://localhost:10560', credentials);
+```
+
+Bei dynamischen Tokens und Client Credentials wird der Token automatisch vor Ablauf erneuert.
+
+## Prozesse starten
+
+### Einfacher Prozessstart
+
+```ts
+await client.processModels.startProcessInstance({
+  processModelId: 'myProcessModelId',
 });
 ```
 
-### Client Factory
+### Konfigurierter Prozessstart
 
-Oder man kann sich über die Client Factory einen feature-spezifischen Client anlegen, der nur einen besimmten fachlichen Aspekt der ProcessCube Engine abdeckt.
+```ts
+await client.processModels.startProcessInstance({
+  processModelId: 'myProcessModelId',
+  startEventId: 'StartEvent_1',
+  correlationId: 'my-correlation-id',
+  initialToken: { hello: 'world' },
+});
+```
 
-Beispiel:
+### Prozess starten und auf Ende warten
 
 ```ts
-import { ClientFactory } from '@5minds/processcube_engine_client';
+const result = await client.processModels.startProcessInstanceAndAwaitEndEvent({
+  processModelId: 'myProcessModelId',
+});
+```
 
-const engineUri = 'http://localhost:10560';
+## UserTasks
 
-const processInstanceClient = ClientFactory.createProcessInstanceClient(engineUri);
+```ts
+import { EngineClient, DataModels } from '@5minds/processcube_engine_client';
 
-const processInstances = await processInstanceClient.query({
-  correlationid: 'my-correlation-id',
+const client = new EngineClient('http://localhost:10560');
+
+const userTasks = await client.userTasks.query({
+  processModelId: 'myProcessModelId',
+  state: DataModels.FlowNodeInstances.FlowNodeInstanceState.suspended,
 });
 ```
 
-Hier wird eine Client Instanz angelegt, welche lediglich die Interaktion mit Prozessinstanzen abdeckt.
+---
 
-## Anwendungsbeispiele
+## External Tasks
 
-Nachfolgend werden ein paar der am häufigsten verwendeten Use Cases demonstriert.
+### Konzept
 
-### Prozesse starten
+External Tasks sind ein zentrales Muster in BPMN 2.0 zur Auslagerung von Arbeitsschritten an externe Worker. Wenn die ProcessCube Engine einen **External Service Task** in einem Prozess erreicht, erstellt sie einen ExternalTask-Eintrag und wartet, bis ein externer Worker diesen abholt, verarbeitet und das Ergebnis zurückmeldet.
 
-Das Starten von Prozessinstanzen kann über die `EngineClient.processModels` Fachlichkeit realisiert werden.
+```mermaid
+sequenceDiagram
+    participant P as BPMN-Prozess
+    participant E as ProcessCube Engine
+    participant W as ExternalTask Worker
 
-Prozesse lassen sich auf mehrere Arten starten.
+    P->>E: Erreicht External Service Task
+    E->>E: ExternalTask erstellen (state: pending)
+    Note over E: Task wartet auf Worker
 
-#### Einfacher Prozessstart
+    loop Polling-Schleife
+        W->>E: Fetch & Lock (Topic, maxTasks, lockDuration)
+        E-->>W: Gesperrte ExternalTasks
+    end
 
-```ts
-import { EngineClient } from '@5minds/processcube_engine_client';
+    W->>W: Payload verarbeiten
 
-const engineUri = 'http://localhost:10560';
+    alt Erfolg
+        W->>E: Finish (Result)
+        E->>P: Prozess fortsetzen mit Result
+    else Fehler
+        W->>E: HandleError (ErrorCode, Message)
+        E->>P: Fehler im Prozess auslösen
+    end
+```
 
-const client = new EngineClient(engineUri);
+Dieses Muster entkoppelt die Prozessausführung von der eigentlichen Geschäftslogik und ermöglicht:
 
-await client.processModels.startProcessInstance({ processModelId: 'myProcessModelId' });
+- **Skalierung:** Beliebig viele Worker können dieselben Topics verarbeiten
+- **Sprachunabhängigkeit:** Worker können in jeder Sprache implementiert werden
+- **Fehlertoleranz:** Locks verfallen automatisch, sodass fehlgeschlagene Tasks erneut verarbeitet werden
+- **Langläufige Aufgaben:** Locks werden automatisch verlängert
+
+### Lebenszyklus eines ExternalTasks
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending: Engine erstellt Task
+    pending --> pending: Lock abgelaufen<br/>(Multi-Try)
+    pending --> expired: Lock abgelaufen<br/>(Single-Try)
+    pending --> finished: Worker meldet Ergebnis<br/>oder Fehler
+    finished --> [*]
+    expired --> [*]
 ```
 
-Die `processModelId` ist der einzige erforderliche Parameter für diesen Request.
+| State      | Beschreibung                                                 |
+| ---------- | ------------------------------------------------------------ |
+| `pending`  | Task wartet auf Verarbeitung oder wird gerade verarbeitet    |
+| `finished` | Task wurde erfolgreich abgeschlossen oder mit Fehler beendet |
+| `expired`  | Lock ist abgelaufen (nur bei Single-Try Tasks)               |
+
+**Single-Try vs. Multi-Try:**
 
-Der Client wartet in diesem Szenario nur, bis die Engine den _Start_ des Prozesses bestätigt hat.
+- **Multi-Try** (Standard): Wenn der Lock abläuft, geht der Task zurück in `pending` und kann von einem anderen Worker abgeholt werden.
+- **Single-Try**: Wenn der Lock abläuft, geht der Task in `expired` und wird nicht erneut angeboten.
 
-#### Konfigurierter Prozessstart
+### ExternalTaskWorker
 
-Neben der `processModelId` können folgende Paramter mitgegeben werden:
+Der `ExternalTaskWorker` ist die zentrale Klasse zur Verarbeitung von External Tasks. Er implementiert eine Polling-Schleife mit Long-Polling, automatischer Lock-Verlängerung und robuster Fehlerbehandlung.
 
-- `startEventId`: Die ID des Start Events von welchem aus der Prozess losgehen soll
-  - **Hinweis:** Bei Prozessen mit mehreren Start Events ist dieser Parameter ebenfalls erforderlich!
-- `correlationId`: Gibt an, in welcher Correlation die Prozessinstanz laufen soll
-- `initialToken`: Der JSON-formatierte Prozess-Token, den die Prozessinstanz zu beginn besitzen soll
+#### Minimalbeispiel
 
 ```ts
-import { EngineClient } from '@5minds/processcube_engine_client';
+import { ExternalTaskWorker } from '@5minds/processcube_engine_client';
 
-const engineUri = 'http://localhost:10560';
+const worker = new ExternalTaskWorker<MyPayload, MyResult>('http://localhost:10560', 'my_topic', async (payload) => {
+  return { result: payload.value * 2 };
+});
 
-const client = new EngineClient(engineUri);
+worker.start();
+```
 
-await client.processModels.startProcessInstance({
-  processModelId: 'myProcessModelId',
-  startEventId: 'StartEvent_1',
-  correlationId: 'MyCorrelatioNid',
-  initialToken: {
-    hello: 'world',
+#### Vollständiges Beispiel mit Typen
+
+```ts
+import { ExternalTaskWorker, DataModels } from '@5minds/processcube_engine_client';
+
+interface OrderPayload {
+  orderId: string;
+  items: Array<{ productId: string; quantity: number }>;
+}
+
+interface OrderResult {
+  confirmationNumber: string;
+  totalPrice: number;
+}
+
+const worker = new ExternalTaskWorker<OrderPayload, OrderResult>(
+  'http://localhost:10560',
+  'process_order',
+  async (payload, externalTask, abortSignal) => {
+    const order = await processOrder(payload.orderId, payload.items);
+
+    if (abortSignal?.aborted) {
+      throw new Error('Task wurde abgebrochen');
+    }
+
+    return {
+      confirmationNumber: order.confirmation,
+      totalPrice: order.total,
+    };
   },
+  {
+    maxTasks: 5,
+    lockDuration: 60000,
+    longpollingTimeout: 15000,
+  },
+);
+
+worker.start();
+```
+
+#### Interner Ablauf des Workers
+
+```mermaid
+flowchart TD
+    Start([worker.start]) --> CheckAuth{Identity<br/>gültig?}
+    CheckAuth -->|Ja| FetchLock[Fetch & Lock<br/>Long-Polling]
+    CheckAuth -->|Nein| RefreshToken[Token erneuern]
+    RefreshToken -->|Erfolg| FetchLock
+    RefreshToken -->|Fehlgeschlagen| CritErr[Kritischer Fehler<br/>Zähler erhöhen]
+    CritErr --> MaxErr{> 5 kritische<br/>Fehler?}
+    MaxErr -->|Ja| StopWorker([Worker stoppt])
+    MaxErr -->|Nein| Backoff[Exponentielles<br/>Backoff]
+    Backoff --> CheckAuth
+
+    FetchLock -->|Tasks erhalten| Process[Tasks parallel<br/>verarbeiten]
+    FetchLock -->|Keine Tasks| Idle[Warten<br/>idleTimeout]
+    FetchLock -->|Fehler| ErrHandle[Fehlerbehandlung]
+    ErrHandle -->|401/403| PermErr[Permanenter<br/>Auth-Fehler]
+    PermErr --> StopWorker
+    ErrHandle -->|Transient| Backoff
+    Idle --> CheckAuth
+    Process --> CheckAuth
+
+    subgraph "Pro Task (parallel)"
+        Process --> Exec[ExternalTaskExecution]
+        Exec --> LockExt[Lock-Verlängerung<br/>planen]
+        Exec --> RunFn[Processing Function<br/>ausführen]
+        RunFn -->|Result| Finish[finishExternalTask]
+        RunFn -->|Error| HandleErr[handleError]
+        RunFn -->|Aborted| Cleanup[Aufräumen]
+    end
+```
+
+### Worker-Konfiguration
+
+```ts
+import { ExternalTaskWorker, IExternalTaskWorkerConfig } from '@5minds/processcube_engine_client';
+
+const config: IExternalTaskWorkerConfig = {
+  workerId: 'order-worker-1',
+  lockDuration: 30000,
+  maxTasks: 10,
+  idleTimeout: 500,
+  longpollingTimeout: 10000,
+  identity: { token: 'Bearer ...', userId: 'worker-user' },
+  payloadFilter: /urgent/,
+};
+```
+
+| Option               | Typ            | Standard | Beschreibung                                |
+| -------------------- | -------------- | -------- | ------------------------------------------- |
+| `workerId`           | `string`       | UUID     | Eindeutige Worker-ID                        |
+| `lockDuration`       | `number`       | `30000`  | Dauer des Locks in ms                       |
+| `maxTasks`           | `number`       | `10`     | Max. Tasks pro Fetch-and-Lock               |
+| `idleTimeout`        | `number`       | `500`    | Wartezeit in ms, wenn keine Tasks vorhanden |
+| `longpollingTimeout` | `number`       | `10000`  | Long-Polling-Timeout in ms                  |
+| `identity`           | `IdentityLike` | -        | Authentifizierung                           |
+| `payloadFilter`      | `RegExp`       | -        | Regex-Filter auf Task-Payload               |
+| `logger`             | `ILogger`      | -        | Eigener Logger                              |
+
+### Processing Function
+
+Die Processing Function erhält drei Parameter:
+
+```ts
+type HandleExternalTaskAction<TPayload, TResult> = (payload: TPayload, externalTask?: ExternalTask<TPayload>, signal?: AbortSignal) => TResult | Promise<TResult>;
+```
+
+| Parameter      | Beschreibung                                       |
+| -------------- | -------------------------------------------------- |
+| `payload`      | Die Nutzdaten des Tasks (generisch typisiert)      |
+| `externalTask` | Das vollständige ExternalTask-Objekt mit Metadaten |
+| `signal`       | AbortSignal zum Reagieren auf Abbruch              |
+
+**Rückgabewerte:**
+
+| Rückgabe            | Verhalten                                                   |
+| ------------------- | ----------------------------------------------------------- |
+| Objekt              | Task wird mit diesem Ergebnis als erfolgreich abgeschlossen |
+| `ExternalTaskError` | Task wird als fehlgeschlagen gemeldet                       |
+| `throw Error`       | Task wird als fehlgeschlagen gemeldet                       |
+
+#### Fehler gezielt melden
+
+```ts
+import { ExternalTaskWorker, DataModels } from '@5minds/processcube_engine_client';
+
+const worker = new ExternalTaskWorker<MyPayload, MyResult>('http://localhost:10560', 'validate_data', async (payload) => {
+  if (!payload.email) {
+    return new DataModels.ExternalTasks.ExternalTaskError('VALIDATION_ERROR', 'E-Mail-Adresse fehlt', { field: 'email' });
+  }
+
+  return { valid: true };
 });
 ```
 
-#### Prozess starten und auf dessen Ende warten
+### Fehlerbehandlung
+
+Der Worker unterscheidet zwischen verschiedenen Fehlertypen und reagiert entsprechend:
+
+```mermaid
+flowchart LR
+    Error[Fehler tritt auf]
+    Error --> Type{Fehlertyp}
+
+    Type -->|Netzwerk / Timeout| Retry[Retry mit<br/>exponentiellem Backoff]
+    Type -->|Token abgelaufen| Refresh[Token erneuern<br/>und Retry]
+    Type -->|401 / 403| Stop[Worker stoppt<br/>nach 5 Versuchen]
+    Type -->|409 Conflict| Abort[Task bereits<br/>abgeschlossen - Skip]
+    Type -->|Unbekannt| Report[Fehler melden<br/>und weiter]
+```
+
+#### Error-Handler registrieren
 
 ```ts
-import { EngineClient } from '@5minds/processcube_engine_client';
+worker.onWorkerError((errorType, error, externalTask) => {
+  console.error(`[${errorType}]`, error.message);
+});
+```
+
+| ErrorType                     | Beschreibung                                |
+| ----------------------------- | ------------------------------------------- |
+| `fetchAndLock`                | Fehler beim Abholen von Tasks               |
+| `extendLock`                  | Fehler bei der Lock-Verlängerung            |
+| `processExternalTask`         | Fehler in der Processing Function           |
+| `finishExternalTask`          | Fehler beim Abschließen des Tasks           |
+| `unprocessableExternalTask`   | Task konnte nicht verarbeitet werden        |
+| `identityRefresh`             | Fehler bei der Token-Erneuerung             |
+| `criticalIdentityFailure`     | Token-Erneuerung endgültig fehlgeschlagen   |
+| `permanentAuthorizationError` | Dauerhafter 401/403-Fehler                  |
+| `unexpectedLoopError`         | Unerwarteter Fehler in der Polling-Schleife |
+
+### Lock-Verlängerung
+
+Wenn eine Task-Verarbeitung länger dauert als die `lockDuration`, verlängert der Worker den Lock automatisch im Hintergrund.
+
+```mermaid
+sequenceDiagram
+    participant W as Worker
+    participant E as Engine
+
+    W->>E: Fetch & Lock (lockDuration: 30s)
+    E-->>W: Task (Lock bis T+30s)
+
+    Note over W: Verarbeitung startet...
+
+    W->>E: Extend Lock (bei T+25s)
+    E-->>W: OK (Lock bis T+55s)
+
+    Note over W: Verarbeitung läuft weiter...
 
-const engineUri = 'http://localhost:10560';
+    W->>E: Extend Lock (bei T+50s)
+    E-->>W: OK (Lock bis T+80s)
 
-const client = new EngineClient(engineUri);
+    Note over W: Verarbeitung abgeschlossen
 
-await client.processModels.startProcessInstanceAndAwaitEndEvent({ processModelId: 'myProcessModelId' });
+    W->>E: Finish Task (Result)
 ```
 
-Hier wartet der Client, bis die Engine den Prozess bis zum Ende ausgeführt hat.
+Die Lock-Verlängerung wird 5 Sekunden vor Ablauf des aktuellen Locks ausgelöst und verlängert jeweils um die konfigurierte `lockDuration`. Dies geschieht automatisch und transparent.
 
-Die Methode akzeptiert dieselben Parameter wie `processModels.startProcessInstance`.
+### Health Monitoring
 
-## Query UserTasks
+```ts
+const health = worker.getHealth();
+```
+
+Das Health-Objekt enthält:
 
-Abfragen aller User Tasks eines bestimmten Prozesses, die sich in einem "suspended" State befinden:
+| Eigenschaft                       | Typ       | Beschreibung                                  |
+| --------------------------------- | --------- | --------------------------------------------- |
+| `isPollingActive`                 | `boolean` | Ob die Polling-Schleife aktiv ist             |
+| `consecutiveCriticalErrors`       | `number`  | Anzahl aufeinanderfolgender kritischer Fehler |
+| `maxConsecutiveCriticalErrors`    | `number`  | Maximum (5), danach stoppt der Worker         |
+| `activeTaskCount`                 | `number`  | Anzahl aktuell verarbeiteter Tasks            |
+| `identityRefreshFailedCritically` | `boolean` | Ob die Token-Erneuerung fehlgeschlagen ist    |
 
 ```ts
-import { EngineClient, DataModels } from '@5minds/processcube_engine_client';
+if (!worker.isHealthy()) {
+  // Worker neu starten oder Alarm auslösen
+}
+```
 
-const engineUri = 'http://localhost:10560';
+### Heartbeat Monitoring
 
-const client = new EngineClient(engineUri);
+Für detailliertes Monitoring kann ein Heartbeat-Callback registriert werden:
 
-const userTasks = await client.userTasks.query({
-  processModelId: 'myProcessModelId',
-  state: DataModels.FlowNodeInstances.FlowNodeInstanceState.suspended,
+```ts
+worker.onHeartbeat((operation, externalTaskId) => {
+  metrics.recordHeartbeat(operation, externalTaskId);
 });
+```
+
+Gemeldete Operationen: `fetchAndLock`, `processExternalTask`, `extendLock`, `finishExternalTask`, `handleError`
+
+### Graceful Shutdown
 
-console.log(userTasks);
+```ts
+process.on('SIGTERM', () => {
+  worker.stop();
+});
 ```
 
-## External Task Worker
+`stop()` bewirkt:
 
-External Task Worker werden dazu benutzt, um die an einer Prozessinstanz anfallenden `External Service Tasks` zu verarbeiten.
+1. Polling-Schleife wird beendet
+2. Alle laufenden Tasks erhalten ein Abort-Signal
+3. Lock-Verlängerungen werden gestoppt
 
-Ein Worker benötigt minimal die folgenden 3 Einstellungen
+Für vollständiges Aufräumen:
 
-- Die URL der Ziel-Engine
-- Das Topic der abzuarbeitenden External Tasks
-- Eine Handler Funktion zum Verarbeiten der External Tasks
+```ts
+worker.dispose();
+```
 
-Beispiel:
+### Multi-Topic Worker
+
+Über die `ExternalTaskApiClient`-Klasse lassen sich Tasks aus mehreren Topics gleichzeitig abholen:
 
 ```ts
-import { ExternalTaskWorker } from '@5minds/processcube_engine_client';
+import { ClientFactory } from '@5minds/processcube_engine_client';
 
-interface AddPayload {
-  number1: number;
-  number2: number;
-}
+const externalTaskApiClient = ClientFactory.createExternalTaskClient('http://localhost:10560');
 
-interface AddResult {
-  sum: number;
-}
+const tasks = await externalTaskApiClient.fetchAndLockExternalTasks('my-worker-id', ['topic_a', 'topic_b', 'topic_c'], 10, 10000, 30000);
+```
+
+### Payload-Filter
 
-const engineUri = 'http://localhost:10560';
-const topic = 'sum_numbers';
+Mit einem Payload-Filter können nur Tasks abgeholt werden, deren Payload einem bestimmten Muster entspricht:
 
-const externalTaskWorker = new ExternalTaskWorker<AddPayload, AddResult>(url, topic, doAdd, config);
+```ts
+const worker = new ExternalTaskWorker<MyPayload, MyResult>('http://localhost:10560', 'notifications', handleNotification, {
+  payloadFilter: /priority.*high/,
+});
+```
 
-externalTaskWorker.start();
+### ExternalTask REST API
 
-async function doAdd(payload: AddPayload, externalTask: DataModels.ExternalTasks.ExternalTask<AddPayload>): Promise<AddResult> {
-  const result: AddResult = {
-    sum: payload.number1 + payload.number2,
-  };
+Der Client kommuniziert mit folgenden Engine-Endpunkten:
 
-  return result;
-}
+| Methode | Endpunkt                                               | Beschreibung                |
+| ------- | ------------------------------------------------------ | --------------------------- |
+| `GET`   | `/atlas_engine/api/v1/external_tasks/deployed_topics`  | Alle aktiven Topics abrufen |
+| `POST`  | `/atlas_engine/api/v1/external_tasks/fetch_and_lock`   | Tasks abholen und sperren   |
+| `PUT`   | `/atlas_engine/api/v1/external_tasks/{id}/extend_lock` | Lock verlängern             |
+| `PUT`   | `/atlas_engine/api/v1/external_tasks/{id}/finish`      | Task abschließen            |
+| `PUT`   | `/atlas_engine/api/v1/external_tasks/{id}/error`       | Fehler melden               |
+
+### ExternalTask-Datenmodell
+
+```ts
+type ExternalTask<TPayload> = {
+  id: string;
+  workerId: string;
+  topic: string;
+  isSingleTry: boolean;
+  flowNodeInstanceId: string;
+  correlationId: string;
+  processDefinitionId: string;
+  processModelId?: string;
+  embeddedProcessModelId?: string;
+  processInstanceId: string;
+  ownerId: string;
+  payload: TPayload;
+  lockExpirationTime: Date;
+  state: ExternalTaskState; // 'pending' | 'finished' | 'expired'
+  finishedAt?: Date;
+  result?: any;
+  error?: any;
+  createdAt?: Date;
+};
 ```
 
-Der Worker lässt sich mit folgendem Befehl starten:
+### ExternalTaskError
 
 ```ts
-externalTaskWorker.start();
+class ExternalTaskError {
+  errorCode: string;
+  errorMessage?: string;
+  errorDetails?: any;
+
+  constructor(errorCode: string, errorMessage?: string, errorDetails?: any);
+}
 ```
 
-und mit folgendem Befehl stoppen:
+---
+
+## Echtzeit-Events via Socket.IO
+
+Der Client kann sich über Socket.IO für Echtzeit-Benachrichtigungen der Engine registrieren.
+
+### Notification-Events
 
 ```ts
-externalTaskWorker.stop();
+const subscription = await client.notification.onProcessStarted((event) => {
+  // Prozess wurde gestartet
+});
+
+// Später abmelden
+client.notification.removeSubscription(subscription);
 ```
 
-Ein ausführbares Code-Beispiel [findet sich hier](./samples/external_task_worker/).
+### ExternalTask-Events
+
+| Event                    | Beschreibung                                     |
+| ------------------------ | ------------------------------------------------ |
+| `external_task_created`  | Ein neuer ExternalTask wurde erstellt            |
+| `external_task_locked`   | Ein ExternalTask wurde von einem Worker gesperrt |
+| `external_task_unlocked` | Ein Lock ist abgelaufen (Multi-Try)              |
+| `external_task_expired`  | Ein Lock ist abgelaufen (Single-Try)             |
+
+### Prozess-Events
+
+| Event                 | Beschreibung                       |
+| --------------------- | ---------------------------------- |
+| `OnProcessStarting`   | Prozessinstanz wird gestartet      |
+| `OnProcessStarted`    | Prozessinstanz wurde gestartet     |
+| `OnProcessFinished`   | Prozessinstanz wurde abgeschlossen |
+| `OnProcessError`      | Fehler in einer Prozessinstanz     |
+| `OnProcessTerminated` | Prozessinstanz wurde abgebrochen   |
+
+### Task-Events
+
+| Event                  | Beschreibung                      |
+| ---------------------- | --------------------------------- |
+| `user_task_waiting`    | UserTask wartet auf Bearbeitung   |
+| `user_task_finished`   | UserTask wurde abgeschlossen      |
+| `manual_task_waiting`  | ManualTask wartet auf Bearbeitung |
+| `manual_task_finished` | ManualTask wurde abgeschlossen    |
+
+---
+
+## Alle verfügbaren Clients
+
+| Client                     | Property                     | Beschreibung                                 |
+| -------------------------- | ---------------------------- | -------------------------------------------- |
+| `ProcessModelClient`       | `client.processModels`       | Prozessmodelle deployen, starten, abfragen   |
+| `ProcessInstanceClient`    | `client.processInstances`    | Laufende und abgeschlossene Prozessinstanzen |
+| `ProcessDefinitionClient`  | `client.processDefinitions`  | Prozessdefinitionen (BPMN-XML) verwalten     |
+| `UserTaskClient`           | `client.userTasks`           | UserTasks abfragen und abschließen           |
+| `ExternalTaskClient`       | `client.externalTasks`       | ExternalTasks abonnieren und verarbeiten     |
+| `ManualTaskClient`         | `client.manualTasks`         | ManualTasks abfragen und abschließen         |
+| `UntypedTaskClient`        | `client.untypedTasks`        | Untypisierte Tasks verwalten                 |
+| `CorrelationClient`        | `client.correlations`        | Correlations abfragen                        |
+| `EventClient`              | `client.events`              | BPMN-Message/Signal-Events senden            |
+| `NotificationClient`       | `client.notification`        | Echtzeit-Events über Socket.IO               |
+| `CronjobClient`            | `client.cronjobs`            | Zeitgesteuerte Prozesse verwalten            |
+| `FlowNodeInstanceClient`   | `client.flowNodeInstances`   | FlowNode-Instanzen abfragen                  |
+| `DataObjectInstanceClient` | `client.dataObjectInstances` | Prozess-Datenobjekte abfragen                |
+| `ApplicationInfoClient`    | `client.applicationInfo`     | Engine-Version und Metadaten                 |

package/package.json

@@ -4,7 +4,7 @@
     "utf-8-validate": "Not used by the client directly, but a requirement of the 'ws' sub-dependency. Since it is not available in the browser, the client would be unusable for the APP SDK, if we did not install it explicitly here"
   },
   "name": "@5minds/processcube_engine_client",
-  "version": "6.3.0-develop.1",
+  "version": "6.3.0-develop.2",
   "description": "Contains a typescript based client for accessing the Engine.",
   "main": "dist/commonjs/index.js",
   "types": "dist/index.d.ts",
@@ -32,14 +32,14 @@
   },
   "dependencies": {
     "async-lock": "^1.4.1",
-    "bufferutil": "4.0.9",
+    "bufferutil": "4.1.0",
     "cross-fetch": "4.1.0",
-    "dayjs": "^1.11.18",
-    "openid-client": "^6.8.1",
-    "socket.io-client": "4.8.1",
+    "dayjs": "^1.11.20",
+    "openid-client": "^6.8.2",
+    "socket.io-client": "4.8.3",
     "utf-8-validate": "5.0.10",
     "uuid": "^13.0.0",
-    "@5minds/processcube_engine_sdk": "7.3.0-develop.1"
+    "@5minds/processcube_engine_sdk": "7.3.0-develop.2"
   },
   "devDependencies": {
     "@types/node": "^24.7.2",