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

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

@@ -0,0 +1,98 @@
+# Snap handler sample
+
+This example demonstrates how to set up a transaction handler that uses event triggers to wait for and respond to external events, implementing a "snap" card game mechanic. It showcases the use of a **correlation stream** to match events from any event source with inflight transactions.
+
+## Overview
+
+The snap handler sample consists of four main components:
+
+1. **Transaction handler** (`snap-handler.ts`) - Implements a card game "snap" mechanic with three actions
+2. **Event source** (`event-source.ts`) - Acts as a card dealer, dealing cards from a shuffled deck
+3. **Correlation stream** (`stream.ts`) - Connects events from the event source to inflight transactions
+4. **Workflow** (`flow.ts`) - Defines the workflow stages and event bindings
+
+## How it works
+
+### The snap game flow
+
+The snap game works by setting a "trap" for a specific playing card (suit and rank) and waiting for that card to be dealt. Here's how the complete flow works:
+
+1. **Transaction Creation**: A transaction is created with a suit and rank (e.g., "hearts" and "king")
+2. **Trap Setup**: The transaction handler sets up a trigger for that specific card
+3. **Waiting State**: The transaction enters a waiting state, listening for matching events
+4. **Card Dealing**: The event source (dealer) deals cards from a shuffled deck
+5. **Event Correlation**: The correlation stream receives card events and determines if they match any inflight transactions
+6. **Match Detection**: When a matching card is dealt, the stream adds a transaction event to the database
+7. **Handler Invocation**: The transaction handler is invoked with the matching event, completing the "snap"
+
+### Transaction handler
+
+The snap handler (`snap-handler.ts`) implements a card game where you can "set a trap" for a specific playing card (suit and rank) and wait for that card to be played. The handler has three actions:
+
+1. **`set-trap`** - Sets up a trigger for a specific card by creating an event topic based on the suit and rank (e.g., `suit.hearts.rank.king`)
+2. **`trap-set`** - Marks that the trap is active and waits for the matching card to be played
+3. **`trap-fired`** - Handles when a matching card is played via an event, completing the "snap" and returning the card data
+
+### Event source
+
+The event source (`event-source.ts`) acts as a card dealer that generates card play events. It maintains a shuffled deck of 52 playing cards and deals random batches of cards (1-9 cards per poll) when polled by the workflow engine. Each card dealt generates an event with:
+
+- A topic matching the pattern `suit.<suit>.rank.<rank>` (e.g., `suit.hearts.rank.king`)
+- A data payload containing the card's description, suit, and rank
+- A unique idempotency key
+
+The event source tracks how many cards have been dealt and stops generating events when the deck is exhausted.
+
+### Correlation stream
+
+The correlation stream (`stream.ts`) is a key component that demonstrates how events from any event source can be correlated with inflight transactions. The stream:
+
+- **Type**: `correlation_stream` - This type of stream evaluates events against all inflight transactions
+- **Event source**: Connects to the `snap-dealer` event source to receive card events
+- **Matching Logic**: When a card event is received, the workflow engine checks if any inflight transactions have event listeners that match the event's topic pattern
+- **Transaction Event**: If a match is found, the engine adds a transaction event to the database and invokes the corresponding transaction handler
+
+This is different from an `event_stream`, which routes events to event processors. A correlation stream allows transactions to wait for and respond to events from any source, making it ideal for event-driven workflows where transactions need to react to external events.
+
+### Workflow
+
+The workflow (`flow.ts`) defines the stages and event bindings:
+
+- **`set-trap` stage**: Initializes the trap by calling the `set-trap` action
+- **`trap-set` stage**: Confirms the trap is set and enters a waiting state
+- **Event listener**: Listens for card play events matching the pattern `suit.<suit>.rank.<rank>`
+- **`snap` stage**: Final success stage reached when the matching card is played
+
+When the correlation stream receives a card event that matches an inflight transaction's event listener, the workflow engine automatically adds the event to that transaction and invokes the handler, causing the workflow to transition to the `snap` stage.
+
+## Usage
+
+1. Register the snap handler in your provider's main file:
+   ```typescript
+   const snapHandler = newDirectedTransactionHandler('snap-watcher', snapActionMap);
+   client.registerTransactionHandler('snap-watcher', snapHandler);
+   ```
+
+2. Register the dealer event source:
+   ```typescript
+   client.registerEventSource('snap-dealer', dealerEventSource);
+   ```
+
+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 scripts:
+   ```bash
+   npm run create-workflow src/samples/snap/flow.ts
+   ```
+
+5. Post the correlation stream to connect the dealer event source to the workflow engine:
+   ```bash
+   npm run create-stream src/samples/snap/stream.ts
+   ```
+
+6. Create a transaction with a suit and rank to set a trap:
+   ```bash
+   npm run create-transaction src/samples/snap/transaction.json
+   ```
+
+Once configured, the event source will deal cards from a shuffled deck. The correlation stream will evaluate each card event against all inflight transactions. When a card matching a transaction's trap is dealt, the stream will add the event to that transaction, causing the handler to be invoked and the workflow to transition to the `snap` stage, completing the transaction.

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

@@ -0,0 +1,104 @@
+// 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, newEventSource, newLogger, WSEventStreamInfo } from "@kaleido-io/workflow-engine-sdk";
+
+const log = newLogger('dealer-event-source');
+
+export interface PlayingCard {
+    description: string;
+    suit: string;
+    rank: string;
+}
+
+interface DealerEventSourceConfig {
+    resetInterval: number;
+}
+
+export const suits = ['clubs', 'diamonds', 'hearts', 'spades'];
+export const ranks = ['ace', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'jack', 'queen', 'king'];
+
+const newDeck = (): PlayingCard[] => {
+    const deck: PlayingCard[] = [];
+    for (const suit of suits) {
+        for (const rank of ranks) {
+            deck.push({
+                description: `${rank} of ${suit}`,
+                suit,
+                rank
+            });
+        }
+    }
+    return deck;
+}
+
+const shuffleDeck = (deck: PlayingCard[]): void => {
+    for (let i = deck.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [deck[i], deck[j]] = [deck[j], deck[i]];
+    }
+}
+
+let deck: PlayingCard[] = newDeck();
+shuffleDeck(deck);
+
+let dealt = 0;
+
+interface DealerEventSourceCheckpoint {
+    dealt: number;
+}
+
+export const dealerEventSource = newEventSource<DealerEventSourceCheckpoint, DealerEventSourceConfig, PlayingCard>(
+    'snap-dealer',
+    async (_config: EventSourceConf<DealerEventSourceConfig>, _checkpoint: DealerEventSourceCheckpoint | null) => {
+        const toDeal = Math.min(Math.floor(Math.random() * 9) + 1, deck.length - dealt);
+        const dealSet = deck.slice(dealt, dealt + toDeal);
+
+        const events = dealSet.map(card => ({
+            idempotencyKey: `${card.suit}-${card.rank}-${Date.now()}-${Math.random()}`,
+            topic: `suit.${card.suit}.rank.${card.rank}`,
+            data: card
+        }));
+
+        dealt += toDeal;
+
+        log.info(`Dealt ${toDeal} cards, total: ${dealt}/${deck.length}`);
+
+        return {
+            checkpointOut: { dealt },
+            events
+        };
+    })
+    .withInitialCheckpoint(async () => ({
+        dealt: 0
+    }))
+    .withConfigParser(async (_, config: DealerEventSourceConfig) => {
+        log.info('Reset interval:', config.resetInterval || 10000);
+        setInterval(() => {
+            log.info('Resetting deck');
+            deck = newDeck();
+            shuffleDeck(deck);
+            dealt = 0;
+        }, config.resetInterval || 10000);
+        return {
+            resetInterval: config.resetInterval || 10000
+        };
+    })
+    .withDeleteFn(async (info: WSEventStreamInfo) => {
+        log.info(`Cleaning up event source ${info.streamName} (${info.streamId})`);
+    });
+
+export const eventSource = dealerEventSource;

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

@@ -0,0 +1,85 @@
+// 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 = {
+  "operations": [
+    {
+      "name": "play",
+      "type": "asynchronous",
+      "stage": "set-trap",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "suit": {
+            "type": "string"
+          },
+          "rank": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "suit",
+          "rank"
+        ],
+        "additionalProperties": false
+      }
+    }
+  ],
+  "stages": [
+    {
+      "name": "set-trap",
+      "type": "pending",
+      "handler": "watcher",
+      "inputMap": {
+        "jsonata": "{\n  \"action\": \"set-trap\",\n  \"nextStage\": \"trap-set\",\n  \"failureStage\": \"fail\",\n  \"suit\": state.input.suit,\n  \"rank\": state.input.rank\n}\n"
+      }
+    },
+    {
+      "name": "trap-set",
+      "type": "pending",
+      "handler": "watcher",
+      "inputMap": {
+        "jsonata": "{\n  \"action\": \"trap-set\",\n  \"nextStage\": \"success\",\n  \"failureStage\": \"fail\",\n  \"suit\": state.input.suit,\n  \"rank\": state.input.rank\n}\n"
+      }
+    },
+    {
+      "name": "snap",
+      "type": "success"
+    },
+    {
+      "name": "fail",
+      "type": "failure"
+    }
+  ],
+  "events": [
+    {
+      "name": "played",
+      "topicMatch": "suit\\.(.*)\\.rank\\.(.*)",
+      "handler": "watcher",
+      "inputMap": {
+        "jsonata": "{\n  \"action\": \"trap-fired\",\n  \"nextStage\": \"snap\",\n  \"failureStage\": \"fail\",\n  \"outputPath\": \"/data\",\n  \"suit\": state.input.suit,\n  \"rank\": state.input.rank\n}\n"
+      }
+    }
+  ],
+  "handlerBindings": {
+    "watcher": {
+      "provider": provider.name,
+      "providerHandler": "snap-watcher"
+    }
+  }
+}

package/template/src/samples/snap/snap-handler.ts

@@ -0,0 +1,84 @@
+// 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, EvalResult, InvocationMode, WithStageDirector, WSEvaluateTransaction } from "@kaleido-io/workflow-engine-sdk";
+
+import { newLogger } from "@kaleido-io/workflow-engine-sdk";
+
+const log = newLogger('snap-handler');
+
+class SnapHandlerInput implements WithStageDirector {
+    public stageDirector: BasicStageDirector;
+    public suit: string;
+    public rank: string;
+
+    constructor(input: any) {
+        this.stageDirector = new BasicStageDirector(
+            input.action || 'set-trap',
+            input.outputPath || '/output',
+            input.nextStage || 'success',
+            input.failureStage || 'fail'
+        );
+        this.suit = input.suit;
+        this.rank = input.rank;
+    }
+
+    getStageDirector() {
+        return this.stageDirector;
+    }
+}
+const trapsSet = new Map<string, boolean>();
+
+const map = new Map();
+
+// Set trap action
+map.set('set-trap', {
+    invocationMode: InvocationMode.PARALLEL,
+    handler: async (transaction: WSEvaluateTransaction, input: SnapHandlerInput) => {
+        const cardTopic = `suit.${input.suit}.rank.${input.rank}`;
+        return {
+            result: EvalResult.COMPLETE,
+            triggers: [{ topic: cardTopic }]
+        };
+    }
+});
+
+// Trap set action
+map.set('trap-set', {
+    invocationMode: InvocationMode.PARALLEL,
+    handler: async (transaction: WSEvaluateTransaction, input: SnapHandlerInput) => {
+        const cardTopic = `suit.${input.suit}.rank.${input.rank}`;
+        log.info(`Trap set: ${cardTopic}`);
+        trapsSet.set(cardTopic, true);
+        return {
+            result: EvalResult.WAITING
+        };
+    }
+});
+
+// Trap fired action
+map.set('trap-fired', {
+    invocationMode: InvocationMode.PARALLEL,
+    handler: async (transaction: WSEvaluateTransaction, _input: SnapHandlerInput) => {
+        const snap = transaction.events![0];
+        return {
+            result: EvalResult.COMPLETE,
+            output: snap.data
+        };
+    }
+});
+
+export const actionMap = map;

package/template/src/samples/snap/stream.ts

@@ -0,0 +1,26 @@
+// 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: 'snap-dealer-stream',
+    started: true,
+    type: 'correlation_stream',
+    listenerHandler: 'snap-dealer',
+    listenerHandlerProvider: provider.name,
+    config: { resetInterval: 10000 }
+}

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

@@ -0,0 +1,26 @@
+// 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 { suits, ranks } from "./event-source.js";
+
+export const transaction = {
+    "input": {
+        "suit": suits[Math.floor(Math.random() * suits.length)],
+        "rank": ranks[Math.floor(Math.random() * ranks.length)]
+    },
+    "operation": "play",
+    "workflow": "snap-flow"
+}

package/template/src/utils/post-stream.ts

@@ -0,0 +1,67 @@
+// 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 {
+    CreateStreamRequest,
+    WorkflowEngineRestClient
+} from '@kaleido-io/workflow-engine-sdk';
+
+import dotenv from 'dotenv';
+
+dotenv.config();
+async function main() {
+    try {
+        // Get the flow name from command line arguments
+        const streamPath = process.argv[2];
+
+        if (!streamPath) {
+            console.error('Error: Please provide a stream TypeScript file as an argument.');
+            console.error('Usage: tsx post-stream.ts <stream>');
+            process.exit(1);
+        }
+
+        // Import the workflow from the TypeScript file
+        let stream: CreateStreamRequest;
+        try {
+            const streamModule = await import(`../../${streamPath}`);
+            if (!streamModule.stream) {
+                console.error(`Error: The file ${streamPath} does not export a 'stream' constant.`);
+                process.exit(1);
+            }
+            stream = streamModule.stream;
+        } catch (error) {
+            console.error(`Error importing stream file at ${streamPath}:`, error);
+            process.exit(1);
+        }
+
+        console.log('Posting stream:', JSON.stringify(stream, null, 2));
+
+        // Create the workflow engine REST client
+        const client = new WorkflowEngineRestClient();
+
+        // Post the workflow
+        const response = await client.createStream(stream);
+
+        console.log('Stream posted successfully!');
+        console.log('Response:', JSON.stringify(response, null, 2));
+    } catch (error) {
+        console.error('Error posting stream:', error);
+        process.exit(1);
+    }
+}
+
+main();

package/template/src/utils/post-transaction.ts

@@ -0,0 +1,64 @@
+// 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 { WorkflowEngineRestClient, CreateTransactionRequest } from '@kaleido-io/workflow-engine-sdk';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function main() {
+  try {
+    // Get the flow name from command line arguments
+    const transactionPath = process.argv[2];
+
+    if (!transactionPath) {
+      console.error('Error: Please provide a transaction JSON file as an argument.');
+      console.error('Usage: tsx post-transaction.ts <transaction>');
+      process.exit(1);
+    }
+
+    // Import the transaction from the TypeScript file
+    let transaction: CreateTransactionRequest;
+    try {
+        const transactionModule = await import(`../../${transactionPath}`);
+        if (!transactionModule.transaction) {
+            console.error(`Error: The file ${transactionPath} does not export a 'transaction' constant.`);
+            process.exit(1);
+        }
+        transaction = transactionModule.transaction;
+    } catch (error) {
+        console.error(`Error importing transaction file at ${transactionPath}:`, error);
+        process.exit(1);
+    }
+
+    console.log('Posting transaction:', JSON.stringify(transaction, null, 2));
+
+    // Create the transaction engine REST client
+    const client = new WorkflowEngineRestClient();
+
+    // Post the transaction
+    const response = await client.createTransaction(transaction);
+
+    console.log('Transaction posted successfully!');
+    console.log('Response:', JSON.stringify(response, null, 2));
+  } catch (error) {
+    console.error('Error posting transaction:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/template/src/utils/post-workflow.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 { WorkflowEngineRestClient, CreateWorkflowRequest } from '@kaleido-io/workflow-engine-sdk';
+import dotenv from 'dotenv';
+
+dotenv.config();
+async function main() {
+    try {
+        // Get the flow name from command line arguments
+        const workflowPath = process.argv[2];
+
+        if (!workflowPath) {
+            console.error('Error: Please provide a workflow TypeScript file as an argument.');
+            console.error('Usage: tsx post-workflow.ts <workflow>');
+            process.exit(1);
+        }
+
+        // Import the workflow from the TypeScript file
+        let workflow: CreateWorkflowRequest;
+        try {
+            const workflowModule = await import(`../../${workflowPath}`);
+            if (!workflowModule.flow) {
+                console.error(`Error: The file ${workflowPath} does not export a 'flow' constant.`);
+                process.exit(1);
+            }
+            workflow = workflowModule.flow;
+        } catch (error) {
+            console.error(`Error importing workflow file at ${workflowPath}:`, error);
+            process.exit(1);
+        }
+
+        console.log('Posting workflow:', JSON.stringify(workflow, null, 2));
+
+        // Create the workflow engine REST client
+        const client = new WorkflowEngineRestClient();
+
+        // Post the workflow
+        const response = await client.createWorkflow(workflow);
+
+        console.log('Workflow posted successfully!');
+        console.log('Response:', JSON.stringify(response, null, 2));
+    } catch (error) {
+        console.error('Error posting workflow:', error);
+        process.exit(1);
+    }
+}
+
+main();

package/template/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "baseUrl": "./"
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "**/*.test.ts",
+    "node_modules",
+    "dist"
+  ]
+}