@quanticjs/workflow-quanticflow 3.3.0

package/README.md

@@ -0,0 +1,193 @@
+# @quanticjs/workflow-quanticflow
+
+QuanticFlow workflow engine adapter for `@quanticjs/workflow`. Connects any QuanticJS application to a standalone [QuanticFlow](https://github.com/quanticjs/quanticflow) instance via REST API.
+
+Supports two modes for service task execution:
+
+| Mode | Transport | How it works |
+|---|---|---|
+| **Callback** | HTTP webhook | QuanticFlow POSTs to your app's `/workflow-callback/service-task` endpoint |
+| **Event** | Redis Streams | Your app consumes `ServiceTaskStartedEvent` from Redis and signals back via REST |
+
+Both modes can run simultaneously (`mode: 'both'`).
+
+## Install
+
+```bash
+npm install @quanticjs/workflow-quanticflow
+```
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { QuanticFlowWorkflowModule } from '@quanticjs/workflow-quanticflow';
+import { QuanticWorkflowModule } from '@quanticjs/workflow';
+
+@Module({
+  imports: [
+    // 1. Register the QuanticFlow engine adapter
+    QuanticFlowWorkflowModule.forRoot({
+      url: 'http://quanticflow:3000',
+      serviceTaskHandling: {
+        mode: 'both',                          // 'callback' | 'event' | 'both'
+        callbackSecret: process.env.CALLBACK_SECRET,
+      },
+    }),
+
+    // 2. Wire the @Workflow decorator into the CQRS pipeline
+    QuanticWorkflowModule.forRoot(),
+  ],
+})
+export class AppModule {}
+```
+
+Now any command decorated with `@Workflow` will be routed to QuanticFlow:
+
+```typescript
+import { Workflow } from '@quanticjs/core';
+
+@Workflow('expense-approval')
+@Validate(CreateExpenseValidator)
+export class CreateExpenseCommand {
+  constructor(
+    readonly amount: number,
+    readonly category: string,
+  ) {}
+}
+```
+
+## Service Task Handlers
+
+Register handlers that execute when QuanticFlow reaches a service task node:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { ServiceTaskHandler, ServiceTaskContext, ServiceTaskResult } from '@quanticjs/workflow-quanticflow';
+
+@Injectable()
+export class SendEmailHandler implements ServiceTaskHandler {
+  constructor(private readonly mailer: MailerService) {}
+
+  async execute(context: ServiceTaskContext): Promise<ServiceTaskResult> {
+    await this.mailer.send({
+      to: context.variables.recipientEmail,
+      subject: `Process ${context.correlationId} update`,
+    });
+    return { signal: 'email-sent', data: { sentAt: new Date() } };
+  }
+}
+```
+
+Register handlers in your module — the registry resolves them by name from the DI container:
+
+```typescript
+@Module({
+  providers: [SendEmailHandler],
+})
+export class NotificationsModule {}
+```
+
+The handler name in the BPMN definition must match the class name (e.g., `SendEmailHandler`).
+
+## Configuration
+
+```typescript
+QuanticFlowWorkflowModule.forRoot({
+  // Required
+  url: 'http://quanticflow:3000',
+
+  // Optional
+  requestTimeout: 10000,                     // HTTP timeout in ms (default: 10000)
+
+  serviceTaskHandling: {
+    mode: 'callback',                        // 'callback' | 'event' | 'both'
+
+    // Callback mode options
+    callbackSecret: 'hmac-secret',           // HMAC-SHA256 signature verification
+
+    // Event mode options (requires ioredis + @quanticjs/redis)
+    streamKey: 'arex:events:services',       // Redis stream (default)
+    consumerGroup: 'my-app-tasks',           // Consumer group name
+    consumerName: 'worker-1',                // Consumer name (default: consumer-{pid})
+  },
+})
+```
+
+## Using the Client Directly
+
+The `QuanticFlowClient` is exported for direct REST API access beyond the `WorkflowEngine` interface:
+
+```typescript
+import { QuanticFlowClient } from '@quanticjs/workflow-quanticflow';
+
+@Injectable()
+export class WorkflowDashboardService {
+  constructor(private readonly qf: QuanticFlowClient) {}
+
+  async getMyTasks(userId: string) {
+    return this.qf.listTasks({ userId, status: 'pending' });
+  }
+
+  async approveTask(taskId: string) {
+    return this.qf.executeTaskAction(taskId, 'approve', { comment: 'Looks good' });
+  }
+}
+```
+
+### Client Methods
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `startInstance(definitionId, variables?, correlationId?)` | `POST /workflow/instances` | Start a workflow |
+| `signalInstance(instanceId, signal, data?)` | `POST /workflow/instances/:id/signal` | Send signal |
+| `abortInstance(instanceId)` | `POST /workflow/instances/:id/abort` | Abort workflow |
+| `getInstance(instanceId)` | `GET /workflow/instances/:id` | Get instance detail |
+| `updateVariables(instanceId, variables)` | `PUT /workflow/instances/:id/variables` | Update variables |
+| `listTasks(filters?)` | `GET /workflow/tasks` | List tasks |
+| `getTask(taskId)` | `GET /workflow/tasks/:id` | Get task detail |
+| `claimTask(taskId)` | `POST /workflow/tasks/:id/claim` | Claim task |
+| `executeTaskAction(taskId, action, data?)` | `POST /workflow/tasks/:id/action` | Execute action |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│  Your NestJS App                             │
+│                                              │
+│  @Workflow('expense')                        │
+│  CreateExpenseCommand ──▶ WorkflowBehavior   │
+│                              │               │
+│                    ┌─────────▼──────────┐    │
+│                    │ QuanticFlowWorkflow │    │
+│                    │ Engine (HTTP)       │    │
+│                    └─────────┬──────────┘    │
+│                              │               │
+│  ┌───────────────────────────┼────────────┐  │
+│  │ Service Task Handling     │            │  │
+│  │                           │            │  │
+│  │  ┌─────────────┐  ┌──────▼─────────┐  │  │
+│  │  │  Callback   │  │  Event         │  │  │
+│  │  │  Controller │  │  Consumer      │  │  │
+│  │  │  (webhook)  │  │  (Redis Stream)│  │  │
+│  │  └──────┬──────┘  └──────┬─────────┘  │  │
+│  │         │                │             │  │
+│  │         ▼                ▼             │  │
+│  │  ServiceTaskHandlerRegistry            │  │
+│  │         │                              │  │
+│  │         ▼                              │  │
+│  │  SendEmailHandler (your code)          │  │
+│  └────────────────────────────────────────┘  │
+└──────────────────────────────────────────────┘
+                    │
+                    │ HTTP / Redis
+                    ▼
+         ┌──────────────────┐
+         │   QuanticFlow    │
+         │   (standalone)   │
+         └──────────────────┘
+```
+
+## License
+
+MIT

package/dist/QuanticFlowCallbackController.d.ts

@@ -0,0 +1,24 @@
+import { QuanticFlowClient } from './QuanticFlowClient';
+import { ServiceTaskHandlerRegistry } from './ServiceTaskHandlerRegistry';
+import { QuanticFlowWorkflowModuleOptions } from './QuanticFlowWorkflowModule';
+export interface ServiceTaskCallbackPayload {
+    instanceId: string;
+    definitionId: string;
+    stateName: string;
+    handlerName: string;
+    correlationId?: string;
+    variables: Record<string, unknown>;
+}
+export interface ServiceTaskCallbackResponse {
+    signal: string;
+    data?: unknown;
+}
+export declare class QuanticFlowCallbackController {
+    private readonly registry;
+    private readonly client;
+    private readonly logger;
+    private readonly callbackSecret?;
+    constructor(registry: ServiceTaskHandlerRegistry, client: QuanticFlowClient, options: QuanticFlowWorkflowModuleOptions);
+    handleServiceTask(payload: ServiceTaskCallbackPayload, signature?: string): Promise<ServiceTaskCallbackResponse>;
+    private verifySignature;
+}

package/dist/QuanticFlowCallbackController.js

@@ -0,0 +1,91 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var QuanticFlowCallbackController_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticFlowCallbackController = void 0;
+const common_1 = require("@nestjs/common");
+const QuanticFlowClient_1 = require("./QuanticFlowClient");
+const ServiceTaskHandlerRegistry_1 = require("./ServiceTaskHandlerRegistry");
+const QuanticFlowWorkflowModule_1 = require("./QuanticFlowWorkflowModule");
+const crypto_1 = require("crypto");
+let QuanticFlowCallbackController = QuanticFlowCallbackController_1 = class QuanticFlowCallbackController {
+    registry;
+    client;
+    logger = new common_1.Logger(QuanticFlowCallbackController_1.name);
+    callbackSecret;
+    constructor(registry, client, options) {
+        this.registry = registry;
+        this.client = client;
+        this.callbackSecret = options.serviceTaskHandling?.callbackSecret;
+    }
+    async handleServiceTask(payload, signature) {
+        this.verifySignature(payload, signature);
+        this.logger.log(`Service task callback: handler=${payload.handlerName}, instance=${payload.instanceId}`);
+        const handler = await this.registry.resolve(payload.handlerName);
+        if (!handler) {
+            this.logger.error(`No handler registered for "${payload.handlerName}"`);
+            await this.client.signalInstance(payload.instanceId, 'handler-not-found', {
+                error: `Handler "${payload.handlerName}" not registered`,
+            });
+            return { signal: 'handler-not-found' };
+        }
+        const context = {
+            instanceId: payload.instanceId,
+            definitionId: payload.definitionId,
+            stateName: payload.stateName,
+            handlerName: payload.handlerName,
+            correlationId: payload.correlationId,
+            variables: payload.variables,
+        };
+        try {
+            const result = await handler.execute(context);
+            this.logger.log(`Handler "${payload.handlerName}" completed with signal="${result.signal}"`);
+            return { signal: result.signal, data: result.data };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger.error(`Handler "${payload.handlerName}" failed: ${message}`);
+            return { signal: 'handler-error', data: { error: message } };
+        }
+    }
+    verifySignature(payload, signature) {
+        if (!this.callbackSecret)
+            return;
+        if (!signature) {
+            throw new common_1.ForbiddenException('Missing callback signature');
+        }
+        const expected = (0, crypto_1.createHmac)('sha256', this.callbackSecret)
+            .update(JSON.stringify(payload))
+            .digest('hex');
+        if (signature !== expected) {
+            throw new common_1.ForbiddenException('Invalid callback signature');
+        }
+    }
+};
+exports.QuanticFlowCallbackController = QuanticFlowCallbackController;
+__decorate([
+    (0, common_1.Post)('service-task'),
+    (0, common_1.HttpCode)(200),
+    __param(0, (0, common_1.Body)()),
+    __param(1, (0, common_1.Headers)('x-callback-signature')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], QuanticFlowCallbackController.prototype, "handleServiceTask", null);
+exports.QuanticFlowCallbackController = QuanticFlowCallbackController = QuanticFlowCallbackController_1 = __decorate([
+    (0, common_1.Controller)('workflow-callback'),
+    __param(2, (0, common_1.Inject)(QuanticFlowWorkflowModule_1.QUANTICFLOW_OPTIONS)),
+    __metadata("design:paramtypes", [ServiceTaskHandlerRegistry_1.ServiceTaskHandlerRegistry,
+        QuanticFlowClient_1.QuanticFlowClient, Object])
+], QuanticFlowCallbackController);

package/dist/QuanticFlowClient.d.ts

@@ -0,0 +1,59 @@
+import { HttpService } from '@nestjs/axios';
+export interface QuanticFlowInstance {
+    id: string;
+    definitionId: string;
+    definitionVersion: string;
+    status: string;
+    currentState: string;
+    variables: Record<string, unknown>;
+    correlationId: string | null;
+    startedBy: string;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface QuanticFlowTask {
+    id: string;
+    processInstanceId: string;
+    stateName: string;
+    taskType: string;
+    taskName: string;
+    assignedRole: string;
+    assignedUserId: string | null;
+    status: string;
+    actions: Array<{
+        name: string;
+        label: string;
+        roles: string[];
+    }>;
+    outcome: string | null;
+    outputData: Record<string, unknown> | null;
+    formSchema: Record<string, unknown> | null;
+    formData: Record<string, unknown> | null;
+    dueAt: string | null;
+    completedBy: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export declare class QuanticFlowClient {
+    private readonly httpService;
+    private readonly logger;
+    constructor(httpService: HttpService);
+    startInstance(definitionId: string, variables?: Record<string, unknown>, correlationId?: string): Promise<QuanticFlowInstance>;
+    signalInstance(instanceId: string, signalName: string, signalData?: unknown): Promise<QuanticFlowInstance>;
+    abortInstance(instanceId: string): Promise<QuanticFlowInstance>;
+    getInstance(instanceId: string): Promise<QuanticFlowInstance>;
+    updateVariables(instanceId: string, variables: Record<string, unknown>): Promise<QuanticFlowInstance>;
+    listTasks(filters?: Record<string, string | number>): Promise<PaginatedResult<QuanticFlowTask>>;
+    getTask(taskId: string): Promise<QuanticFlowTask>;
+    claimTask(taskId: string): Promise<QuanticFlowTask>;
+    executeTaskAction(taskId: string, actionName: string, actionData?: Record<string, unknown>): Promise<QuanticFlowTask>;
+}

package/dist/QuanticFlowClient.js

@@ -0,0 +1,79 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var QuanticFlowClient_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticFlowClient = void 0;
+const common_1 = require("@nestjs/common");
+const axios_1 = require("@nestjs/axios");
+const rxjs_1 = require("rxjs");
+let QuanticFlowClient = QuanticFlowClient_1 = class QuanticFlowClient {
+    httpService;
+    logger = new common_1.Logger(QuanticFlowClient_1.name);
+    constructor(httpService) {
+        this.httpService = httpService;
+    }
+    async startInstance(definitionId, variables, correlationId) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.post('/workflow/instances', {
+            definitionId,
+            variables,
+            correlationId,
+        }));
+        this.logger.log(`Started instance ${data.id} for definition ${definitionId}`);
+        return data;
+    }
+    async signalInstance(instanceId, signalName, signalData) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.post(`/workflow/instances/${instanceId}/signal`, { signalName, data: signalData }));
+        this.logger.log(`Signaled instance ${instanceId} with "${signalName}"`);
+        return data;
+    }
+    async abortInstance(instanceId) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.post(`/workflow/instances/${instanceId}/abort`));
+        this.logger.log(`Aborted instance ${instanceId}`);
+        return data;
+    }
+    async getInstance(instanceId) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.get(`/workflow/instances/${instanceId}`));
+        return data;
+    }
+    async updateVariables(instanceId, variables) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.put(`/workflow/instances/${instanceId}/variables`, { variables }));
+        this.logger.log(`Updated variables for instance ${instanceId}`);
+        return data;
+    }
+    async listTasks(filters) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.get('/workflow/tasks', {
+            params: filters,
+        }));
+        return data;
+    }
+    async getTask(taskId) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.get(`/workflow/tasks/${taskId}`));
+        return data;
+    }
+    async claimTask(taskId) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.post(`/workflow/tasks/${taskId}/claim`));
+        this.logger.log(`Claimed task ${taskId}`);
+        return data;
+    }
+    async executeTaskAction(taskId, actionName, actionData) {
+        const { data } = await (0, rxjs_1.firstValueFrom)(this.httpService.post(`/workflow/tasks/${taskId}/action`, {
+            actionName,
+            data: actionData,
+        }));
+        this.logger.log(`Executed action "${actionName}" on task ${taskId}`);
+        return data;
+    }
+};
+exports.QuanticFlowClient = QuanticFlowClient;
+exports.QuanticFlowClient = QuanticFlowClient = QuanticFlowClient_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [axios_1.HttpService])
+], QuanticFlowClient);

package/dist/QuanticFlowWorkflowEngine.d.ts

@@ -0,0 +1,13 @@
+import type { WorkflowEngine, WorkflowStartResult } from '@quanticjs/core';
+import { QuanticFlowClient } from './QuanticFlowClient';
+export declare class QuanticFlowWorkflowEngine implements WorkflowEngine {
+    private readonly client;
+    private readonly logger;
+    constructor(client: QuanticFlowClient);
+    startProcess(processDefinitionId: string, command: object, metadata: {
+        commandType: string;
+        correlationId?: string;
+    }): Promise<WorkflowStartResult>;
+    signalProcess(processInstanceId: string, signal: string, data?: unknown): Promise<void>;
+    abortProcess(processInstanceId: string): Promise<void>;
+}

package/dist/QuanticFlowWorkflowEngine.js

@@ -0,0 +1,48 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var QuanticFlowWorkflowEngine_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticFlowWorkflowEngine = void 0;
+const common_1 = require("@nestjs/common");
+const QuanticFlowClient_1 = require("./QuanticFlowClient");
+let QuanticFlowWorkflowEngine = QuanticFlowWorkflowEngine_1 = class QuanticFlowWorkflowEngine {
+    client;
+    logger = new common_1.Logger(QuanticFlowWorkflowEngine_1.name);
+    constructor(client) {
+        this.client = client;
+    }
+    async startProcess(processDefinitionId, command, metadata) {
+        const variables = {
+            ...JSON.parse(JSON.stringify(command)),
+            __commandType: metadata.commandType,
+        };
+        const instance = await this.client.startInstance(processDefinitionId, variables, metadata.correlationId);
+        this.logger.log(`Workflow started: instance=${instance.id}, definition=${processDefinitionId}`);
+        return {
+            workflowInstanceId: instance.id,
+            processInstanceId: instance.id,
+            status: 'STARTED',
+        };
+    }
+    async signalProcess(processInstanceId, signal, data) {
+        await this.client.signalInstance(processInstanceId, signal, data);
+        this.logger.log(`Workflow signaled: instance=${processInstanceId}, signal=${signal}`);
+    }
+    async abortProcess(processInstanceId) {
+        await this.client.abortInstance(processInstanceId);
+        this.logger.log(`Workflow aborted: instance=${processInstanceId}`);
+    }
+};
+exports.QuanticFlowWorkflowEngine = QuanticFlowWorkflowEngine;
+exports.QuanticFlowWorkflowEngine = QuanticFlowWorkflowEngine = QuanticFlowWorkflowEngine_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [QuanticFlowClient_1.QuanticFlowClient])
+], QuanticFlowWorkflowEngine);

package/dist/QuanticFlowWorkflowModule.d.ts

@@ -0,0 +1,22 @@
+import { DynamicModule } from '@nestjs/common';
+import { ServiceTaskHandler } from './ServiceTaskHandlerRegistry';
+export declare const QUANTICFLOW_OPTIONS: unique symbol;
+export interface ServiceTaskHandlingOptions {
+    mode: 'callback' | 'event' | 'both';
+    callbackSecret?: string;
+    streamKey?: string;
+    consumerGroup?: string;
+    consumerName?: string;
+}
+export interface QuanticFlowWorkflowModuleOptions {
+    url: string;
+    requestTimeout?: number;
+    serviceTaskHandling?: ServiceTaskHandlingOptions;
+    handlers?: Array<{
+        name: string;
+        useClass: new (...args: unknown[]) => ServiceTaskHandler;
+    }>;
+}
+export declare class QuanticFlowWorkflowModule {
+    static forRoot(options: QuanticFlowWorkflowModuleOptions): DynamicModule;
+}

package/dist/QuanticFlowWorkflowModule.js

@@ -0,0 +1,82 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var QuanticFlowWorkflowModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticFlowWorkflowModule = exports.QUANTICFLOW_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+const axios_1 = require("@nestjs/axios");
+const core_1 = require("@quanticjs/core");
+const QuanticFlowClient_1 = require("./QuanticFlowClient");
+const QuanticFlowWorkflowEngine_1 = require("./QuanticFlowWorkflowEngine");
+const QuanticFlowCallbackController_1 = require("./QuanticFlowCallbackController");
+const ServiceTaskEventConsumer_1 = require("./ServiceTaskEventConsumer");
+const ServiceTaskHandlerRegistry_1 = require("./ServiceTaskHandlerRegistry");
+exports.QUANTICFLOW_OPTIONS = Symbol('QUANTICFLOW_OPTIONS');
+let QuanticFlowWorkflowModule = QuanticFlowWorkflowModule_1 = class QuanticFlowWorkflowModule {
+    static forRoot(options) {
+        const mode = options.serviceTaskHandling?.mode ?? 'callback';
+        const enableCallback = mode === 'callback' || mode === 'both';
+        const enableEvents = mode === 'event' || mode === 'both';
+        const providers = [
+            {
+                provide: exports.QUANTICFLOW_OPTIONS,
+                useValue: options,
+            },
+            QuanticFlowClient_1.QuanticFlowClient,
+            {
+                provide: core_1.WORKFLOW_ENGINE,
+                useClass: QuanticFlowWorkflowEngine_1.QuanticFlowWorkflowEngine,
+            },
+            ServiceTaskHandlerRegistry_1.ServiceTaskHandlerRegistry,
+        ];
+        const controllers = [];
+        if (enableCallback) {
+            controllers.push(QuanticFlowCallbackController_1.QuanticFlowCallbackController);
+        }
+        if (enableEvents) {
+            providers.push({
+                provide: 'QUANTICFLOW_EVENT_OPTIONS',
+                useValue: {
+                    streamKey: options.serviceTaskHandling?.streamKey,
+                    consumerGroup: options.serviceTaskHandling?.consumerGroup,
+                    consumerName: options.serviceTaskHandling?.consumerName,
+                },
+            });
+            providers.push(ServiceTaskEventConsumer_1.ServiceTaskEventConsumer);
+        }
+        if (options.handlers) {
+            for (const { name, useClass } of options.handlers) {
+                providers.push({
+                    provide: name,
+                    useClass,
+                });
+            }
+        }
+        return {
+            module: QuanticFlowWorkflowModule_1,
+            imports: [
+                axios_1.HttpModule.register({
+                    baseURL: options.url,
+                    timeout: options.requestTimeout ?? 10000,
+                }),
+            ],
+            controllers,
+            providers,
+            exports: [
+                core_1.WORKFLOW_ENGINE,
+                QuanticFlowClient_1.QuanticFlowClient,
+                ServiceTaskHandlerRegistry_1.ServiceTaskHandlerRegistry,
+            ],
+        };
+    }
+};
+exports.QuanticFlowWorkflowModule = QuanticFlowWorkflowModule;
+exports.QuanticFlowWorkflowModule = QuanticFlowWorkflowModule = QuanticFlowWorkflowModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], QuanticFlowWorkflowModule);

package/dist/ServiceTaskEventConsumer.d.ts

@@ -0,0 +1,20 @@
+import { Logger } from '@nestjs/common';
+import { RedisStreamConsumer } from '@quanticjs/events';
+import { QuanticFlowClient } from './QuanticFlowClient';
+import { ServiceTaskHandlerRegistry } from './ServiceTaskHandlerRegistry';
+import type { Redis } from 'ioredis';
+export declare class ServiceTaskEventConsumer extends RedisStreamConsumer {
+    private readonly registry;
+    private readonly client;
+    protected readonly logger: Logger;
+    readonly streamKey: string;
+    readonly consumerGroup: string;
+    readonly consumerName: string;
+    constructor(redis: Redis | undefined, registry: ServiceTaskHandlerRegistry, client: QuanticFlowClient, options: {
+        streamKey?: string;
+        consumerGroup?: string;
+        consumerName?: string;
+    });
+    protected shouldHandle(fields: Record<string, string>): boolean;
+    handleMessage(fields: Record<string, string>): Promise<void>;
+}

package/dist/ServiceTaskEventConsumer.js

@@ -0,0 +1,86 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var ServiceTaskEventConsumer_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceTaskEventConsumer = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@quanticjs/core");
+const events_1 = require("@quanticjs/events");
+const QuanticFlowClient_1 = require("./QuanticFlowClient");
+const ServiceTaskHandlerRegistry_1 = require("./ServiceTaskHandlerRegistry");
+const DEFAULT_STREAM_KEY = 'arex:events:services';
+const DEFAULT_CONSUMER_GROUP = 'quanticflow-service-tasks';
+let ServiceTaskEventConsumer = ServiceTaskEventConsumer_1 = class ServiceTaskEventConsumer extends events_1.RedisStreamConsumer {
+    registry;
+    client;
+    logger = new common_1.Logger(ServiceTaskEventConsumer_1.name);
+    streamKey;
+    consumerGroup;
+    consumerName;
+    constructor(redis, registry, client, options) {
+        super(redis);
+        this.registry = registry;
+        this.client = client;
+        this.streamKey = options.streamKey ?? DEFAULT_STREAM_KEY;
+        this.consumerGroup = options.consumerGroup ?? DEFAULT_CONSUMER_GROUP;
+        this.consumerName = options.consumerName ?? `consumer-${process.pid}`;
+    }
+    shouldHandle(fields) {
+        return fields['eventType'] === 'ServiceTaskStartedEvent';
+    }
+    async handleMessage(fields) {
+        const payload = JSON.parse(fields['payload'] ?? '{}');
+        const { instanceId, definitionId, stateName, handlerName, correlationId, variables, } = payload;
+        this.logger.log(`Service task event: handler=${handlerName}, instance=${instanceId}`);
+        const handler = await this.registry.resolve(handlerName);
+        if (!handler) {
+            this.logger.error(`No handler registered for "${handlerName}"`);
+            await this.client.signalInstance(instanceId, 'handler-not-found', {
+                error: `Handler "${handlerName}" not registered`,
+            });
+            return;
+        }
+        const context = {
+            instanceId,
+            definitionId,
+            stateName,
+            handlerName,
+            correlationId,
+            variables: variables ?? {},
+        };
+        try {
+            const result = await handler.execute(context);
+            await this.client.signalInstance(instanceId, result.signal, result.data);
+            this.logger.log(`Handler "${handlerName}" completed, signaled instance ${instanceId} with "${result.signal}"`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger.error(`Handler "${handlerName}" failed: ${message}`);
+            await this.client.signalInstance(instanceId, 'handler-error', {
+                error: message,
+                handlerName,
+                stateName,
+            });
+        }
+    }
+};
+exports.ServiceTaskEventConsumer = ServiceTaskEventConsumer;
+exports.ServiceTaskEventConsumer = ServiceTaskEventConsumer = ServiceTaskEventConsumer_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(core_1.REDIS_CLIENT)),
+    __param(3, (0, common_1.Inject)('QUANTICFLOW_EVENT_OPTIONS')),
+    __metadata("design:paramtypes", [Object, ServiceTaskHandlerRegistry_1.ServiceTaskHandlerRegistry,
+        QuanticFlowClient_1.QuanticFlowClient, Object])
+], ServiceTaskEventConsumer);

package/dist/ServiceTaskHandlerRegistry.d.ts

@@ -0,0 +1,25 @@
+import { ModuleRef } from '@nestjs/core';
+export interface ServiceTaskHandler {
+    execute(context: ServiceTaskContext): Promise<ServiceTaskResult>;
+}
+export interface ServiceTaskContext {
+    instanceId: string;
+    definitionId: string;
+    stateName: string;
+    handlerName: string;
+    correlationId?: string;
+    variables: Record<string, unknown>;
+}
+export interface ServiceTaskResult {
+    signal: string;
+    data?: unknown;
+}
+export declare const SERVICE_TASK_HANDLERS: unique symbol;
+export declare class ServiceTaskHandlerRegistry {
+    private readonly moduleRef;
+    private readonly logger;
+    private readonly handlers;
+    constructor(moduleRef: ModuleRef);
+    register(name: string, handler: ServiceTaskHandler): void;
+    resolve(name: string): Promise<ServiceTaskHandler | undefined>;
+}

package/dist/ServiceTaskHandlerRegistry.js

@@ -0,0 +1,49 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var ServiceTaskHandlerRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceTaskHandlerRegistry = exports.SERVICE_TASK_HANDLERS = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+exports.SERVICE_TASK_HANDLERS = Symbol('SERVICE_TASK_HANDLERS');
+let ServiceTaskHandlerRegistry = ServiceTaskHandlerRegistry_1 = class ServiceTaskHandlerRegistry {
+    moduleRef;
+    logger = new common_1.Logger(ServiceTaskHandlerRegistry_1.name);
+    handlers = new Map();
+    constructor(moduleRef) {
+        this.moduleRef = moduleRef;
+    }
+    register(name, handler) {
+        this.handlers.set(name, handler);
+        this.logger.log(`Registered service task handler: ${name}`);
+    }
+    async resolve(name) {
+        const registered = this.handlers.get(name);
+        if (registered)
+            return registered;
+        try {
+            const handler = this.moduleRef.get(name, { strict: false });
+            if (handler && typeof handler.execute === 'function') {
+                this.handlers.set(name, handler);
+                return handler;
+            }
+        }
+        catch {
+            // Not found in DI container
+        }
+        return undefined;
+    }
+};
+exports.ServiceTaskHandlerRegistry = ServiceTaskHandlerRegistry;
+exports.ServiceTaskHandlerRegistry = ServiceTaskHandlerRegistry = ServiceTaskHandlerRegistry_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.ModuleRef])
+], ServiceTaskHandlerRegistry);

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { QuanticFlowWorkflowModule, QUANTICFLOW_OPTIONS } from './QuanticFlowWorkflowModule';
+export type { QuanticFlowWorkflowModuleOptions, ServiceTaskHandlingOptions, } from './QuanticFlowWorkflowModule';
+export { QuanticFlowClient } from './QuanticFlowClient';
+export type { QuanticFlowInstance, QuanticFlowTask, PaginatedResult, } from './QuanticFlowClient';
+export { QuanticFlowWorkflowEngine } from './QuanticFlowWorkflowEngine';
+export { QuanticFlowCallbackController } from './QuanticFlowCallbackController';
+export type { ServiceTaskCallbackPayload, ServiceTaskCallbackResponse, } from './QuanticFlowCallbackController';
+export { ServiceTaskEventConsumer } from './ServiceTaskEventConsumer';
+export { ServiceTaskHandlerRegistry, SERVICE_TASK_HANDLERS, } from './ServiceTaskHandlerRegistry';
+export type { ServiceTaskHandler, ServiceTaskContext, ServiceTaskResult, } from './ServiceTaskHandlerRegistry';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_TASK_HANDLERS = exports.ServiceTaskHandlerRegistry = exports.ServiceTaskEventConsumer = exports.QuanticFlowCallbackController = exports.QuanticFlowWorkflowEngine = exports.QuanticFlowClient = exports.QUANTICFLOW_OPTIONS = exports.QuanticFlowWorkflowModule = void 0;
+var QuanticFlowWorkflowModule_1 = require("./QuanticFlowWorkflowModule");
+Object.defineProperty(exports, "QuanticFlowWorkflowModule", { enumerable: true, get: function () { return QuanticFlowWorkflowModule_1.QuanticFlowWorkflowModule; } });
+Object.defineProperty(exports, "QUANTICFLOW_OPTIONS", { enumerable: true, get: function () { return QuanticFlowWorkflowModule_1.QUANTICFLOW_OPTIONS; } });
+var QuanticFlowClient_1 = require("./QuanticFlowClient");
+Object.defineProperty(exports, "QuanticFlowClient", { enumerable: true, get: function () { return QuanticFlowClient_1.QuanticFlowClient; } });
+var QuanticFlowWorkflowEngine_1 = require("./QuanticFlowWorkflowEngine");
+Object.defineProperty(exports, "QuanticFlowWorkflowEngine", { enumerable: true, get: function () { return QuanticFlowWorkflowEngine_1.QuanticFlowWorkflowEngine; } });
+var QuanticFlowCallbackController_1 = require("./QuanticFlowCallbackController");
+Object.defineProperty(exports, "QuanticFlowCallbackController", { enumerable: true, get: function () { return QuanticFlowCallbackController_1.QuanticFlowCallbackController; } });
+var ServiceTaskEventConsumer_1 = require("./ServiceTaskEventConsumer");
+Object.defineProperty(exports, "ServiceTaskEventConsumer", { enumerable: true, get: function () { return ServiceTaskEventConsumer_1.ServiceTaskEventConsumer; } });
+var ServiceTaskHandlerRegistry_1 = require("./ServiceTaskHandlerRegistry");
+Object.defineProperty(exports, "ServiceTaskHandlerRegistry", { enumerable: true, get: function () { return ServiceTaskHandlerRegistry_1.ServiceTaskHandlerRegistry; } });
+Object.defineProperty(exports, "SERVICE_TASK_HANDLERS", { enumerable: true, get: function () { return ServiceTaskHandlerRegistry_1.SERVICE_TASK_HANDLERS; } });

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@quanticjs/workflow-quanticflow",
+  "version": "3.3.0",
+  "description": "QuanticFlow workflow engine adapter for @quanticjs/workflow — supports callback and event-driven service task execution",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "jest --passWithNoTests",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "nestjs",
+    "cqrs",
+    "quanticflow",
+    "workflow",
+    "bpmn"
+  ],
+  "author": "turkelk",
+  "license": "MIT",
+  "dependencies": {
+    "@nestjs/axios": "^4.0.0",
+    "@quanticjs/core": "^3.3.0",
+    "@quanticjs/events": "^3.3.0",
+    "axios": "^1.6.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/cqrs": "^10.0.0 || ^11.0.0",
+    "ioredis": "^5.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quanticjs/quanticjs-backend.git",
+    "directory": "packages/workflow-quanticflow"
+  }
+}