@kaleido-io/workflow-engine-sdk 0.0.1 → 0.9.2

package/template/src/samples/event-source/event-source.ts

@@ -0,0 +1,70 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+import { EventSourceConf, EventSourceEvent, newEventSource, newLogger, WSEventStreamInfo } from "@kaleido-io/workflow-engine-sdk";
+
+const log = newLogger('event-source');
+
+// Example event source handler using the factory
+interface MyEventSourceConfig {
+  pollingInterval: number;
+}
+
+interface MyEventSourceCheckpoint {
+  lastPollTime: number;
+}
+
+interface MyEventData {
+  message: string;
+  timestamp: number;
+}
+
+export const eventSource = newEventSource<MyEventSourceCheckpoint, MyEventSourceConfig, MyEventData>(
+  'my-listener',
+  async (config: EventSourceConf<MyEventSourceConfig>, checkpoint: MyEventSourceCheckpoint | null) => {
+    log.info('Polling for events with config:', config.config);
+
+    const now = Date.now();
+    let lastPollTime = checkpoint?.lastPollTime || now;
+    const events: EventSourceEvent<MyEventData>[] = [];
+    if (now - lastPollTime > 10000) {
+      const timestamp = now;
+      events.push({
+        idempotencyKey: `event-${timestamp}`,
+        topic: 'my-topic',
+        data: { message: `Hello from event source at ${new Date(timestamp).toISOString()}`, timestamp }
+      });
+      lastPollTime = now;
+    }
+
+    return {
+      checkpointOut: { lastPollTime },
+      events
+    };
+  }
+)
+  .withInitialCheckpoint(async () => ({
+    lastPollTime: 0
+  }))
+  .withConfigParser(async (_, config: MyEventSourceConfig) => {
+    return {
+      pollingInterval: config.pollingInterval || 5000
+    };
+  })
+  .withDeleteFn(async (info: WSEventStreamInfo) => {
+    log.info(`Cleaning up event source ${info.streamName} (${info.streamId})`);
+  });

package/template/src/samples/event-source/stream.ts

@@ -0,0 +1,34 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+import provider from '../../provider.js';
+
+export const stream = {
+    "name": "event-echo-stream",
+    "description": "Listen for events from the custom event source and pass them to the echo event processor",
+    "type": "event_stream",
+    "config": {
+        "pollingInterval": "2s"
+    },
+    "listenerHandler": "my-listener",
+    "listenerHandlerProvider": provider.name,
+    "eventHandler": "echo",
+    "eventHandlerProvider": provider.name,
+    "postFilter": {
+        "jsonata": "true"
+    }
+}

package/template/src/samples/hello/README.md

@@ -0,0 +1,52 @@
+# Hello sample
+
+This example demonstrates a simple transaction handler that processes input data and returns a greeting message.
+
+## Overview
+
+The hello sample consists of two main components:
+
+1. **Handler** (`handlers.ts`) - Processes a name input and returns a personalized greeting
+2. **Workflow** (`flow.ts`) - Defines the workflow that invokes the hello handler
+
+## How it works
+
+### Handler
+
+The hello handler (`handlers.ts`) accepts a transaction with a `name` field in the input. It:
+
+- Validates that the `name` field is provided
+- Returns a personalized greeting message in the output
+- Emits an event with the greeting message to demonstrate event emission from handlers
+
+If the `name` field is missing, the handler returns a hard failure with an error message.
+
+### Workflow
+
+The `hello-flow` workflow (`flow.ts`) defines a simple asynchronous operation that:
+
+- Accepts an input with a required `name` string field
+- Invokes the hello handler to process the input
+- Returns the greeting message in the output
+
+## Usage
+
+1. Register the hello handler in your provider's main file:
+   ```typescript
+   const helloHandler = newDirectedTransactionHandler('hello', helloActionMap);
+   client.registerTransactionHandler('hello', helloHandler);
+   ```
+
+2. Start your application to register your provider and handlers with the workflow engine.
+
+3. Post the workflow to the workflow engine using the utility script:
+   ```bash
+   npm run create-workflow src/samples/hello/flow.ts
+   ```
+
+4. Create a transaction to test the handler:
+   ```bash
+   npm run create-transaction src/samples/hello/transaction.json
+   ```
+
+The handler will process the transaction and return a greeting message. A transaction event will also be created.

package/template/src/samples/hello/flow.ts

@@ -0,0 +1,74 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+import provider from '../../provider.js';
+export const flow = {
+  "name": "hello-flow",
+  "description": "",
+  "labels": {},
+  "handlerBindings": {
+    "hello": {
+      "provider": provider.name,
+      "providerHandler": "hello"
+    }
+  },
+  "version": "1.0.0",
+  "operations": [
+    {
+      "name": "hello",
+      "description": "Hello",
+      "type": "asynchronous",
+      "stage": "my-beginning-state",
+      "stateUpdates": null,
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": [
+              "string"
+            ]
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      }
+    }
+  ],
+  "stages": [
+    {
+      "name": "my-beginning-state",
+      "type": "pending",
+      "handler": "hello",
+      "inputMap": {
+        "jsonata": "{\n    \"action\": \"hello\",\n    \"invoke\": {\n      \"input\": state.input\n    },\n    \"nextStage\": \"end\",\n    \"failureStage\": \"failure\",\n    \"outputPath\": \"/output\"\n}\n"
+      },
+      "fullState": true
+    },
+    {
+      "name": "end",
+      "type": "success",
+      "handler": ""
+    },
+    {
+      "name": "failure",
+      "type": "failure",
+      "handler": ""
+    }
+  ]
+}

package/template/src/samples/hello/handlers.test.ts

@@ -0,0 +1,147 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+import { describe, it, expect } from 'vitest';
+import { EvalResult, WSEvaluateTransaction } from '@kaleido-io/workflow-engine-sdk';
+import { actionMap } from './handlers';
+
+describe('Hello handlers', () => {
+    it('should return a greeting when name is provided', async () => {
+        const handler = actionMap.get('hello');
+        expect(handler).toBeDefined();
+
+        if (!handler || !handler.handler) {
+            throw new Error('Handler not found');
+        }
+
+        const mockRequest: Partial<WSEvaluateTransaction> = {
+            state: {
+                input: {
+                    name: 'World'
+                }
+            }
+        };
+
+        const mockInput = {
+            stageDirector: {
+                action: 'hello',
+                outputPath: '/output',
+                nextStage: 'end',
+                failureStage: 'failed'
+            },
+            getStageDirector: () => mockInput.stageDirector,
+            name: () => 'hello'
+        };
+
+        const result = await handler.handler(mockRequest as WSEvaluateTransaction, mockInput as any);
+
+        expect(result.result).toBe(EvalResult.COMPLETE);
+        expect(result.output).toEqual({
+            greeting: 'Hello World!'
+        });
+    });
+
+    it('should return HARD_FAILURE when name is missing', async () => {
+        const handler = actionMap.get('hello');
+        expect(handler).toBeDefined();
+
+        if (!handler || !handler.handler) {
+            throw new Error('Handler not found');
+        }
+
+        const mockRequest: Partial<WSEvaluateTransaction> = {
+            state: {
+                input: {}
+            }
+        };
+
+        const mockInput = {
+            stageDirector: {
+                action: 'hello',
+                outputPath: '/output',
+                nextStage: 'end',
+                failureStage: 'failed'
+            },
+            getStageDirector: () => mockInput.stageDirector,
+            name: () => 'hello'
+        };
+
+        const result = await handler.handler(mockRequest as WSEvaluateTransaction, mockInput as any);
+
+        expect(result.result).toBe(EvalResult.HARD_FAILURE);
+        expect(result.error).toBeInstanceOf(Error);
+        expect(result.error?.message).toBe('Name is required');
+    });
+
+    it('should return HARD_FAILURE when state.input is undefined', async () => {
+        const handler = actionMap.get('hello');
+        expect(handler).toBeDefined();
+
+        if (!handler || !handler.handler) {
+            throw new Error('Handler not found');
+        }
+
+        const mockRequest: Partial<WSEvaluateTransaction> = {
+            state: {}
+        };
+
+        const mockInput = {
+            stageDirector: {
+                action: 'hello',
+                outputPath: '/output',
+                nextStage: 'end',
+                failureStage: 'failed'
+            },
+            getStageDirector: () => mockInput.stageDirector,
+            name: () => 'hello'
+        };
+
+        const result = await handler.handler(mockRequest as WSEvaluateTransaction, mockInput as any);
+
+        expect(result.result).toBe(EvalResult.HARD_FAILURE);
+        expect(result.error).toBeInstanceOf(Error);
+        expect(result.error?.message).toBe('Name is required');
+    });
+
+    it('should return HARD_FAILURE when state is undefined', async () => {
+        const handler = actionMap.get('hello');
+        expect(handler).toBeDefined();
+
+        if (!handler || !handler.handler) {
+            throw new Error('Handler not found');
+        }
+
+        const mockRequest: Partial<WSEvaluateTransaction> = {};
+
+        const mockInput = {
+            stageDirector: {
+                action: 'hello',
+                outputPath: '/output',
+                nextStage: 'end',
+                failureStage: 'failed'
+            },
+            getStageDirector: () => mockInput.stageDirector,
+            name: () => 'hello'
+        };
+
+        const result = await handler.handler(mockRequest as WSEvaluateTransaction, mockInput as any);
+
+        expect(result.result).toBe(EvalResult.HARD_FAILURE);
+        expect(result.error).toBeInstanceOf(Error);
+        expect(result.error?.message).toBe('Name is required');
+    });
+});

package/template/src/samples/hello/handlers.ts

@@ -0,0 +1,72 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+import { BasicStageDirector, DirectedActionConfig, EvalResult, InvocationMode, WithStageDirector, WSEvaluateTransaction } from "@kaleido-io/workflow-engine-sdk";
+
+class MyHandlerInput implements WithStageDirector {
+    public stageDirector: BasicStageDirector;
+    public action1?: { inputA: string };
+    public action2?: { inputB: string };
+    public customData?: any;
+
+    constructor(data: any) {
+        this.stageDirector = new BasicStageDirector(
+            data.action || 'hello',
+            data.outputPath || '/output',
+            data.nextStage || 'end',
+            data.failureStage || 'failed'
+        );
+        this.customData = data.customData;
+    }
+
+    getStageDirector(): BasicStageDirector {
+        return this.stageDirector;
+    }
+
+    name(): string {
+        return 'hello';
+    }
+}
+
+const map: Map<string, DirectedActionConfig<MyHandlerInput>> = new Map([
+    ["hello", {
+        invocationMode: InvocationMode.PARALLEL, handler: async (transaction: WSEvaluateTransaction) => {
+            if (transaction.state?.input?.name === undefined) {
+                return {
+                    result: EvalResult.HARD_FAILURE,
+                    error: new Error('Name is required')
+                }
+            } else {
+                return {
+                    result: EvalResult.COMPLETE,
+                    output: {
+                        greeting: `Hello ${transaction.state.input.name}!`,
+                    },
+                    events: [
+                        {
+                            idempotencyKey: transaction.idempotencyKey,
+                            topic: 'greeting',
+                            data: `Hello ${transaction.state.input.name}!`
+                        }
+                    ]
+                }
+            }
+        }
+    }],
+]);
+
+export const actionMap = map;

package/template/src/samples/hello/transaction.ts

@@ -0,0 +1,24 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+export const transaction = {
+    "input": {
+      "name": "workflow engine developer"
+    },
+    "operation": "hello",
+    "workflow": "hello-flow"
+  }

package/template/src/samples/http-invoke/README.md

@@ -0,0 +1,42 @@
+# HTTP invoke sample
+
+This example demonstrates how to make HTTP requests to external APIs from within a transaction handler.
+
+## Overview
+
+The http-invoke sample consists of two main components:
+
+1. **Handler** (`handlers.ts`) - Makes an HTTP request to an external API and returns the response
+2. **Workflow** (`flow.ts`) - Defines the workflow that invokes the http-invoke handler
+
+## How it works
+
+### Handler
+
+The http-invoke handler (`handlers.ts`) demonstrates a handler making an async request and providing a response to the transaction when the request has completed.
+
+### Workflow
+
+The `http-invoke-flow` workflow (`flow.ts`) is a simple flow that completes once the HTTP response has been returned by the handler.
+
+## Usage
+
+1. Register the http-invoke handler in your provider's main file:
+   ```typescript
+   const httpInvokeHandler = newDirectedTransactionHandler('http-invoke', httpInvokeActionMap);
+   client.registerTransactionHandler('http-invoke', httpInvokeHandler);
+   ```
+
+3. Start your application to register your provider and handlers with the workflow engine.
+
+4. Post the workflow to the workflow engine using the utility script:
+   ```bash
+   npm run create-workflow src/samples/http-invoke/flow.ts
+   ```
+
+5. Create a transaction to test the handler:
+   ```bash
+   npm run create-transaction src/samples/http-invoke/transaction.json
+   ```
+
+The handler will make the HTTP request and return the response.

package/template/src/samples/http-invoke/flow.ts

@@ -0,0 +1,63 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+import provider from '../../provider.js';
+export const flow = {
+  "name": "http-invoke-flow",
+  "description": "",
+  "labels": {},
+  "handlerBindings": {
+    "http-invoke": {
+      "provider": provider.name,
+      "providerHandler": "http-invoke"
+    }
+  },
+  "version": "1.0.0",
+  "operations": [
+    {
+      "name": "http-invoke",
+      "description": "HTTP Invoke",
+      "type": "asynchronous",
+      "stage": "start",
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  ],
+  "stages": [
+    {
+      "name": "start",
+      "type": "pending",
+      "handler": "http-invoke",
+      "inputMap": {
+        "jsonata": "{\n    \"action\": \"http-invoke\",\n    \"invoke\": {\n      \"input\": state.input\n    },\n    \"nextStage\": \"end\",\n    \"failureStage\": \"failure\",\n    \"outputPath\": \"/output\"\n}\n"
+      },
+      "fullState": true
+    },
+    {
+      "name": "end",
+      "type": "success",
+      "handler": ""
+    },
+    {
+      "name": "failure",
+      "type": "failure",
+      "handler": ""
+    }
+  ]
+}

package/template/src/samples/http-invoke/handlers.ts

@@ -0,0 +1,66 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+import { BasicStageDirector, DirectedActionConfig, EvalResult, InvocationMode, WithStageDirector } from "@kaleido-io/workflow-engine-sdk";
+
+class HTTPInvokeHandlerInput implements WithStageDirector {
+    public stageDirector: BasicStageDirector;
+    public action1?: { inputA: string };
+    public action2?: { inputB: string };
+    public customData?: any;
+
+    constructor(data: any) {
+        this.stageDirector = new BasicStageDirector(
+            data.action || 'http-invoke',
+            data.outputPath || '/output',
+            data.nextStage || 'end',
+            data.failureStage || 'failed'
+        );
+        this.customData = data.customData;
+    }
+
+    getStageDirector(): BasicStageDirector {
+        return this.stageDirector;
+    }
+
+    name(): string {
+        return 'hello';
+    }
+}
+
+const url = 'https://httpbin.org/get';
+const map: Map<string, DirectedActionConfig<HTTPInvokeHandlerInput>> = new Map([
+    ["http-invoke", {
+        invocationMode: InvocationMode.PARALLEL, handler: async () => {
+            const response = await fetch(url, {
+                headers: {
+                    'X-API-KEY': process.env.API_KEY ?? '',
+                },
+            });
+            const body = await response.json();
+            return {
+                result: EvalResult.COMPLETE,
+                output: {
+                    body,
+                    status: response.status,
+                },
+            }
+        }
+    }],
+]);
+
+export const actionMap = map;

package/template/src/samples/http-invoke/transaction.ts

@@ -0,0 +1,22 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+export const transaction = {
+    "input": {},
+    "operation": "http-invoke",
+    "workflow": "http-invoke-flow"
+}