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

package/dist-esm/src/types/core.js

@@ -0,0 +1,68 @@
+// 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.
+/**
+ * Core types and enums for the Workflow Engine TypeScript SDK.
+ */
+export var EvalResult;
+(function (EvalResult) {
+    EvalResult[EvalResult["FIXABLE_ERROR"] = 0] = "FIXABLE_ERROR";
+    EvalResult[EvalResult["TRANSIENT_ERROR"] = 1] = "TRANSIENT_ERROR";
+    EvalResult[EvalResult["HARD_FAILURE"] = 2] = "HARD_FAILURE";
+    EvalResult[EvalResult["COMPLETE"] = 3] = "COMPLETE";
+    EvalResult[EvalResult["WAITING"] = 4] = "WAITING";
+})(EvalResult || (EvalResult = {}));
+export var InvocationMode;
+(function (InvocationMode) {
+    InvocationMode[InvocationMode["PARALLEL"] = 0] = "PARALLEL";
+    InvocationMode[InvocationMode["BATCH"] = 1] = "BATCH";
+})(InvocationMode || (InvocationMode = {}));
+export var WSMessageType;
+(function (WSMessageType) {
+    WSMessageType["PROTOCOL_ERROR"] = "protocol_error";
+    WSMessageType["REGISTER_PROVIDER"] = "register_provider";
+    WSMessageType["REGISTER_HANDLER"] = "register_handler";
+    WSMessageType["EVALUATE"] = "evaluate";
+    WSMessageType["EVALUATE_RESULT"] = "evaluate_result";
+    WSMessageType["HANDLE_TRANSACTIONS"] = "handle_transactions";
+    WSMessageType["HANDLE_TRANSACTIONS_RESULT"] = "handle_transactions_result";
+    WSMessageType["EVENT_SOURCE_CONFIG"] = "event_source_config";
+    WSMessageType["EVENT_SOURCE_POLL"] = "event_source_poll";
+    WSMessageType["EVENT_SOURCE_POLL_RESULT"] = "event_source_poll_result";
+    WSMessageType["EVENT_SOURCE_VALIDATE_CONFIG"] = "event_source_validate_config";
+    WSMessageType["EVENT_SOURCE_VALIDATE_CONFIG_RESULT"] = "event_source_validate_config_result";
+    WSMessageType["EVENT_SOURCE_DELETE"] = "event_source_delete";
+    WSMessageType["EVENT_SOURCE_DELETE_RESULT"] = "event_source_delete_result";
+    WSMessageType["EVENT_PROCESSOR_BATCH"] = "event_processor_batch";
+    WSMessageType["EVENT_PROCESSOR_BATCH_RESULT"] = "event_processor_batch_result";
+    WSMessageType["ENGINE_API_SUBMIT_TRANSACTIONS"] = "engineapi_submit_transactions";
+    WSMessageType["ENGINE_API_SUBMIT_TRANSACTIONS_RESULT"] = "engineapi_submit_transactions_result";
+})(WSMessageType || (WSMessageType = {}));
+export var WSHandlerType;
+(function (WSHandlerType) {
+    WSHandlerType["TRANSACTION_HANDLER"] = "transaction_handler";
+    WSHandlerType["EVENT_PROCESSOR"] = "event_processor";
+    WSHandlerType["EVENT_SOURCE"] = "event_source";
+})(WSHandlerType || (WSHandlerType = {}));
+export var PatchOpType;
+(function (PatchOpType) {
+    PatchOpType["ADD"] = "add";
+    PatchOpType["REMOVE"] = "remove";
+    PatchOpType["REPLACE"] = "replace";
+    PatchOpType["MOVE"] = "move";
+    PatchOpType["COPY"] = "copy";
+    PatchOpType["TEST"] = "test";
+})(PatchOpType || (PatchOpType = {}));
+//# sourceMappingURL=core.js.map

package/dist-esm/src/types/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../src/types/core.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,sCAAsC;AACtC,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AAGjC;;GAEG;AAEH,MAAM,CAAN,IAAY,UAMX;AAND,WAAY,UAAU;IACpB,6DAAiB,CAAA;IACjB,iEAAmB,CAAA;IACnB,2DAAgB,CAAA;IAChB,mDAAY,CAAA;IACZ,iDAAW,CAAA;AACb,CAAC,EANW,UAAU,KAAV,UAAU,QAMrB;AAED,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,2DAAY,CAAA;IACZ,qDAAS,CAAA;AACX,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,MAAM,CAAN,IAAY,aAmBX;AAnBD,WAAY,aAAa;IACvB,kDAAiC,CAAA;IACjC,wDAAuC,CAAA;IACvC,sDAAqC,CAAA;IACrC,sCAAqB,CAAA;IACrB,oDAAmC,CAAA;IACnC,4DAA2C,CAAA;IAC3C,0EAAyD,CAAA;IACzD,4DAA2C,CAAA;IAC3C,wDAAuC,CAAA;IACvC,sEAAqD,CAAA;IACrD,8EAA6D,CAAA;IAC7D,4FAA2E,CAAA;IAC3E,4DAA2C,CAAA;IAC3C,0EAAyD,CAAA;IACzD,gEAA+C,CAAA;IAC/C,8EAA6D,CAAA;IAC7D,iFAAgE,CAAA;IAChE,+FAA8E,CAAA;AAChF,CAAC,EAnBW,aAAa,KAAb,aAAa,QAmBxB;AAED,MAAM,CAAN,IAAY,aAIX;AAJD,WAAY,aAAa;IACvB,4DAA2C,CAAA;IAC3C,oDAAmC,CAAA;IACnC,8CAA6B,CAAA;AAC/B,CAAC,EAJW,aAAa,KAAb,aAAa,QAIxB;AAED,MAAM,CAAN,IAAY,WAOX;AAPD,WAAY,WAAW;IACrB,0BAAW,CAAA;IACX,gCAAiB,CAAA;IACjB,kCAAmB,CAAA;IACnB,4BAAa,CAAA;IACb,4BAAa,CAAA;IACb,4BAAa,CAAA;AACf,CAAC,EAPW,WAAW,KAAX,WAAW,QAOtB"}

package/dist-esm/src/types/flows.js

@@ -0,0 +1,27 @@
+// 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.
+/** Available flow stage types */
+export const FlowStageTypes = {
+    PENDING: 'pending',
+    SUCCESS: 'success',
+    FAILURE: 'failure',
+};
+/** Available flow operation types */
+export const FlowOperationTypes = {
+    ASYNC: 'asynchronous',
+    SYNC: 'synchronous',
+};
+//# sourceMappingURL=flows.js.map

package/dist-esm/src/types/flows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.js","sourceRoot":"","sources":["../../../src/types/flows.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,sCAAsC;AACtC,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AAYjC,iCAAiC;AACjC,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,SAA0B;IACnC,OAAO,EAAE,SAA0B;IACnC,OAAO,EAAE,SAA0B;CAC3B,CAAC;AAKX,qCAAqC;AACrC,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,cAAmC;IAC1C,IAAI,EAAE,aAAkC;CAChC,CAAC"}

package/dist-esm/src/utils/errors.js

@@ -0,0 +1,19 @@
+// 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 getErrorMessage = (error) => {
+    return error instanceof Error ? error.message : String(error);
+};
+//# sourceMappingURL=errors.js.map

package/dist-esm/src/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,sCAAsC;AACtC,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AAGjC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAc,EAAU,EAAE;IACxD,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC,CAAA"}

package/dist-esm/src/utils/patch.js

@@ -0,0 +1,56 @@
+// 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 * as fastJsonPatch from "fast-json-patch";
+import { PatchOpType } from "../types/core.js";
+const { applyPatch } = fastJsonPatch;
+export const apply = (state, patch) => {
+    if (!patch || patch.length === 0) {
+        return state;
+    }
+    const { newDocument: newState } = applyPatch(state, patch);
+    return newState;
+};
+// JSON Patch operation creators
+export const addOp = (path, value) => ({
+    op: PatchOpType.ADD,
+    path,
+    value,
+});
+export const removeOp = (path) => ({
+    op: PatchOpType.REMOVE,
+    path,
+});
+export const replaceOp = (path, value) => ({
+    op: PatchOpType.REPLACE,
+    path,
+    value,
+});
+export const moveOp = (from, path) => ({
+    op: PatchOpType.MOVE,
+    from,
+    path,
+});
+export const copyOp = (from, path) => ({
+    op: PatchOpType.COPY,
+    from,
+    path,
+});
+export const testOp = (path, value) => ({
+    op: PatchOpType.TEST,
+    path,
+    value,
+});
+//# sourceMappingURL=patch.js.map

package/dist-esm/src/utils/patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.js","sourceRoot":"","sources":["../../../src/utils/patch.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,sCAAsC;AACtC,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AAGjC,OAAO,KAAK,aAAa,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAW,WAAW,EAAS,MAAM,eAAe,CAAC;AAE5D,MAAM,EAAE,UAAU,EAAE,GAAG,aAAa,CAAC;AAErC,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAc,EAAE,KAAY,EAAE,EAAE;IACpD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC,KAAK,EAAE,KAAkC,CAAC,CAAC;IACxF,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF,gCAAgC;AAChC,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE,CAAC,CAAC;IAC/D,EAAE,EAAE,WAAW,CAAC,GAAG;IACnB,IAAI;IACJ,KAAK;CACN,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC;IAClD,EAAE,EAAE,WAAW,CAAC,MAAM;IACtB,IAAI;CACL,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE,CAAC,CAAC;IACnE,EAAE,EAAE,WAAW,CAAC,OAAO;IACvB,IAAI;IACJ,KAAK;CACN,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,IAAY,EAAW,EAAE,CAAC,CAAC;IAC9D,EAAE,EAAE,WAAW,CAAC,IAAI;IACpB,IAAI;IACJ,IAAI;CACL,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,IAAY,EAAW,EAAE,CAAC,CAAC;IAC9D,EAAE,EAAE,WAAW,CAAC,IAAI;IACpB,IAAI;IACJ,IAAI;CACL,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,KAAc,EAAW,EAAE,CAAC,CAAC;IAChE,EAAE,EAAE,WAAW,CAAC,IAAI;IACpB,IAAI;IACJ,KAAK;CACN,CAAC,CAAC"}

package/package.json

@@ -1,22 +1,90 @@
 {
   "name": "@kaleido-io/workflow-engine-sdk",
-  "version": "0.0.1",
-  "description": "Kaleido Typescript SDK",
-  "main": "index.js",
-  "scripts": {
-    "test": "npm t"
-  },
+  "version": "0.9.2",
+  "description": "TypeScript SDK for Kaleido Workflow Engine",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "module": "dist-esm/src/index.js",
+  "types": "dist/src/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kaleido-io/kaleido-sdk-typescript.git"
   },
+  "scripts": {
+    "prebuild": "npm run clean && npm run lint",
+    "build": "tsc && npm run build:cjs && npm run build:esm",
+    "build:cjs": "tsc && cp cjs-package-template.json dist/package.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "postbuild": "tsc-esm-fix --target='dist-esm'",
+    "clean": "rm -rf dist && rm -rf dist-esm",
+    "dev": "tsc --watch",
+    "test": "jest --testPathIgnorePatterns=tests/componenttest --coverage",
+    "test:unit": "jest tests/unit",
+    "test:component": "jest tests/componenttest",
+    "test:all": "jest --coverage",
+    "lint": "eslint . --config eslint.config.mjs",
+    "lint:fix": "eslint . --fix --config eslint.config.mjs"
+  },
   "keywords": [
-    "kaleido"
+    "kaleido",
+    "sdk",
+    "typescript",
+    "workflows",
+    "workflow-engine",
+    "handlers",
+    "providers"
   ],
-  "author": "support@kaleido.io",
+  "author": "Kaleido",
   "license": "Apache-2.0",
-  "bugs": {
-    "url": "https://github.com/kaleido-io/kaleido-sdk-typescript/issues"
+  "dependencies": {
+    "exponential-backoff": "^3.1.1",
+    "fast-json-patch": "^3.1.1",
+    "js-yaml": "^4.1.1",
+    "uuid": "^13.0.0",
+    "ws": "^8.14.0"
   },
-  "homepage": "https://github.com/kaleido-io/kaleido-sdk-typescript#readme"
+  "devDependencies": {
+    "@eslint/compat": "^2.0.0",
+    "@eslint/js": "^10.0.0",
+    "@jest/globals": "^30.2.0",
+    "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.2.1",
+    "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.5.0",
+    "eslint": "^10.0.0",
+    "eslint-plugin-notice": "^1.0.0",
+    "find-root": "^1.1.0",
+    "globals": "^17.3.0",
+    "jest": "^30.2.0",
+    "lodash": "^4.17.21",
+    "metric-lcs": "^1.0.3",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.2",
+    "tsc-esm-fix": "^3.1.2",
+    "typescript": "^5.2.0",
+    "typescript-eslint": "^8.56.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "wesdk": "./bin/wesdk.js"
+  },
+  "files": [
+    "dist/**/*",
+    "dist-esm/**/*",
+    "bin/**/*",
+    "template/**/*",
+    "!template/node_modules/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist-esm/src/index.js",
+      "require": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  }
 }

package/template/.env.sample

@@ -0,0 +1,14 @@
+# Account URL
+ACCOUNT=my-account.my-tenant.com
+
+# Environment
+ENVIRONMENT=my-environment-name
+
+# Workflow engine
+WORKFLOW_ENGINE=my-workflow-engine-name
+
+# API key name
+KEY_NAME="my-key-name"
+
+# API key
+KEY_VALUE="my-key-value"

package/template/.vscode/launch.json

@@ -0,0 +1,23 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug: npm run start:dev",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "start:dev"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    },
+    {
+      "name": "Debug: npm run test",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "test"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    }
+  ]
+}

package/template/README.md

@@ -0,0 +1,37 @@
+# Kaleido workflow engine custom providers
+
+This project contains worked examples of custom providers that register transaction handlers and event sources with the Kaleido workflow engine.
+
+## Getting started
+
+1. Copy `.env.sample` to `.env` and populate the values. You will need:
+   - a Kaleido account in a tenant something of the format <account_name>.<tenant_url>
+   - an environment in that account, either name or ID
+   - a workflow engine in that environment, either name or ID
+   - an API key name and value - the API key will need to be granted service access to the workflow engine
+2. Install dependencies: `npm install`
+3. Start the provider, either:
+   - use the vscode launch configurations to run inside the debugger
+   - use `npm run start:dev` to run TypeScript
+   - use `npm build` and `npm start` to run transpiled JavaScript
+
+Your provider will initialize and attempt to connect to the workflow engine and register the provider and handlers. You should see:
+```bash
+[handler_runtime] Registering provider and handlers
+```
+Followed by some handler registration messages. You can now take a look at your workflow engine provider page in the Kaleido UI and you should see your provider listed.
+
+This project will be bootstrapped with some example handlers, and the flows and streams needed to put them to use. To trigger a handler, you can use the `hello` sample by:
+- defining a workflow that uses the `hello` handler by running `npm run create-workflow ./src/samples/hello/flow.ts`
+- create a transaction against that workflow by running `npm run create-transaction ./src/samples/hello/transaction.json`
+
+You should see the transaction appear in your workflow engine, and it should transition to `succeeded` shortly afterwars with a greeting message produced by the `hello` handler in this project.
+
+## Included Samples
+
+This project includes several samples demonstrating different patterns and capabilities:
+
+- **[Hello](./src/samples/hello/README.md)** - A simple transaction handler that processes input and returns a greeting message
+- **[HTTP invoke](./src/samples/http-invoke/README.md)** - Demonstrates making HTTP requests to external APIs from within a transaction handler
+- **[Event source](./src/samples/event-source/README.md)** - Shows how to set up a custom event source that generates events and streams them to an event processor
+- **[Snap](./src/samples/snap/README.md)** - By playing the card game "snap", this sample demonstrates a correlation stream that matches events from any event source with inflight transactions.

package/template/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "{{PROVIDER_NAME}}",
+    "version": "0.0.1",
+    "scripts": {
+        "prebuild": "npm run clean",
+        "build": "tsc",
+        "clean": "rm -rf dist",
+        "start": "node dist/src/connect.js",
+        "start:dev": "tsx ./src/connect.ts",
+        "create-workflow": "tsx ./src/utils/post-workflow.ts",
+        "create-transaction": "tsx ./src/utils/post-transaction.ts",
+        "create-stream": "tsx ./src/utils/post-stream.ts",
+        "test": "vitest run",
+        "test:watch": "vitest watch",
+        "test:coverage": "vitest run --coverage"
+    },
+    "private": true,
+    "devDependencies": {
+        "@vitest/coverage-v8": "^4.0.16",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.16"
+    },
+    "type": "module",
+    "main": "dist/src/connect.js",
+    "files": [
+        "dist/src",
+        "README.md"
+    ],
+    "dependencies": {
+        "@kaleido-io/workflow-engine-sdk": "^1.0.0",
+        "dotenv": "^17.2.3",
+        "web3": "^4.16.0",
+        "ws": "^8.18.0"
+    }
+}

package/template/src/connect.ts

@@ -0,0 +1,58 @@
+// 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 {
+  newDirectedTransactionHandler,
+  WorkflowEngineClient,
+} from '@kaleido-io/workflow-engine-sdk';
+import dotenv from 'dotenv';
+
+import provider from './provider.js';
+
+import { actionMap as helloActionMap } from './samples/hello/handlers.js';
+import { actionMap as httpInvokeActionMap } from './samples/http-invoke/handlers.js';
+import { eventSource } from './samples/event-source/event-source.js';
+import { actionMap as snapActionMap } from './samples/snap/snap-handler.js';
+import { echoEventProcessor } from './samples/event-source/event-processor.js';
+import { eventSource as dealerEventSource } from './samples/snap/event-source.js';
+
+dotenv.config();
+const wsUrl = `wss://${process.env.ACCOUNT}/endpoint/${process.env.ENVIRONMENT}/${process.env.WORKFLOW_ENGINE}/rest/ws`;
+const client = new WorkflowEngineClient({
+  url: wsUrl,
+  authHeaderName: 'Authorization',
+  authToken: `basic ${Buffer.from(`${process.env.KEY_NAME}:${process.env.KEY_VALUE}`).toString("base64")}`,
+  providerName: provider.name,
+  providerMetadata: provider.metadata ?? {},
+  reconnectDelay: 2000,
+});
+
+const helloHandler = newDirectedTransactionHandler('hello', helloActionMap);
+client.registerTransactionHandler('hello', helloHandler);
+
+const httpInvokeHandler = newDirectedTransactionHandler('http-invoke', httpInvokeActionMap);
+client.registerTransactionHandler('http-invoke', httpInvokeHandler);
+
+client.registerEventProcessor('echo', echoEventProcessor);
+client.registerEventSource('my-listener', eventSource);
+
+const snapHandler = newDirectedTransactionHandler('snap-watcher', snapActionMap);
+client.registerTransactionHandler('snap-watcher', snapHandler);
+
+client.registerEventSource('snap-dealer', dealerEventSource);
+
+await client.connect();

package/template/src/provider.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 default {
+    "name": "example-provider",
+    "metadata": {
+        "displayName": "Example provider",
+        "description": "An example provider for the Kaleido Workflow Engine"
+    }
+}

package/template/src/samples/event-source/README.md

@@ -0,0 +1,50 @@
+# Event source sample
+
+This example demonstrates how to set up a custom event source that generates events and streams them to an event processor.
+
+## Overview
+
+The event source sample consists of three main components:
+
+1. **Event source** (`event-source.ts`) - Generates timestamped events at regular intervals
+2. **Event Processor** (`event-processor.ts`) - Logs out any events it receives
+3. **Event stream** (`stream.ts`) - Connects the event source to the event processor
+
+## How it works
+
+### Event source
+
+The event source (`event-source.ts`) generates a new timestamped event every ten seconds. When the workflow engine polls for events, the event source checks if more than ten seconds have passed since the last poll time stored in the checkpoint. If so, it generates a new event with:
+
+- A unique idempotency key
+- A topic (`my-topic`)
+- A data payload containing a message and timestamp
+
+### Stream
+
+When an event is received from the event source, the stream (`stream.ts`) ensures that the event is passed on to the event processor handler. In this scenario, for simplicity, the event processor is part of the same provider, but this is not a requirement.
+
+### Event processor
+
+The event processor (`event-processor.ts`) listens for batches of events and logs them out as they are received. It then updates the checkpoint to acknowledge the event shave been processed.
+
+## Usage
+
+1. Register the event source in your provider's main file:
+   ```typescript
+   client.registerEventSource('my-listener', eventSource);
+   ```
+
+2. Register the event processor:
+   ```typescript
+   client.registerEventProcessor('echo', echoEventProcessor);
+   ```
+
+3. Start your application to register your provider and handlers with the workflow engine.
+
+4. Post the stream to the workflow engine using the utility scripts:
+   ```bash
+   npm run create-stream src/samples/event-source/stream.ts
+   ```
+
+Once configured, the event source will generate events every ten seconds, which will result in the event processor being called.

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

@@ -0,0 +1,65 @@
+// 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 || 'echo',
+            data.outputPath || '/output',
+            data.nextStage || 'end',
+            data.failureStage || 'failed'
+        );
+        this.customData = data.customData;
+    }
+
+    getStageDirector(): BasicStageDirector {
+        return this.stageDirector;
+    }
+
+    name(): string {
+        return 'echo';
+    }
+}
+
+const map: Map<string, DirectedActionConfig<MyHandlerInput>> = new Map([
+    ["echo", {
+        invocationMode: InvocationMode.PARALLEL, handler: async (transaction: WSEvaluateTransaction) => {
+            if (transaction.state?.input?.data === undefined || transaction.state?.input?.data?.message === undefined) {
+                return {
+                    result: EvalResult.HARD_FAILURE,
+                    error: new Error('Message is required')
+                }
+            } else {
+                return {
+                    result: EvalResult.COMPLETE,
+                    output: {
+                        message: `Event received with message: ${transaction.state.input.data.message}`,
+                    }
+                }
+            }
+        }
+    }],
+]);
+
+export const actionMap = map;

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

@@ -0,0 +1,46 @@
+// 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 { EngineAPI, WSEventProcessorBatchRequest, WSEventProcessorBatchResult } from "@kaleido-io/workflow-engine-sdk";
+
+export class MyEventProcessor {
+
+    constructor() { }
+
+    name(): string {
+        return 'echo';
+    }
+
+    init(_engAPI: EngineAPI): Promise<void> {
+        return Promise.resolve();
+    }
+
+    close(): void {
+        return;
+    }
+
+    eventProcessorBatch(result: WSEventProcessorBatchResult, batch: WSEventProcessorBatchRequest): Promise<void> {
+        for (const event of batch.events) {
+            console.log(`Event received: ${event.topic} - ${JSON.stringify(event.data, null, '\t')}`);
+        }
+        result.checkpoint = {
+            lastPollTime: Date.now()
+        };
+        return Promise.resolve();
+    }
+}
+
+export const echoEventProcessor = new MyEventProcessor();