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

package/dist/src/factories/event_source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event_source.js","sourceRoot":"","sources":["../../../src/factories/event_source.ts"],"names":[],"mappings":"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"}

package/dist/src/factories/transaction_handler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Transaction Handler Factory
+ *
+ * Provides factory functions for creating transaction handlers,
+ * especially directed transaction handlers using the StageDirector pattern.
+ */
+import { WithStageDirector } from '../types/core';
+import { TransactionHandler, DirectedActionConfig, EngineAPI } from '../interfaces/handlers';
+/**
+ * Transaction handler factory interface.
+ */
+export interface TransactionHandlerFactory extends TransactionHandler {
+    withInitFn(initFn: (engAPI: EngineAPI) => Promise<void>): TransactionHandlerFactory;
+    withCloseFn(closeFn: () => void): TransactionHandlerFactory;
+}
+/**
+ * Create a new simple directed handler, with no initialization.
+ *
+ * A directed handler uses the StageDirector pattern to route transactions
+ * to different actions based on the input's `action` field.
+ *
+ * @param name Handler name
+ * @param actionMap Map of action names to their configurations
+ * @returns A TransactionHandlerFactory for chaining
+ */
+export declare function newDirectedTransactionHandler<T extends WithStageDirector>(name: string, actionMap: Map<string, DirectedActionConfig<T>>): TransactionHandlerFactory;
+//# sourceMappingURL=transaction_handler.d.ts.map

package/dist/src/factories/transaction_handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction_handler.d.ts","sourceRoot":"","sources":["../../../src/factories/transaction_handler.ts"],"names":[],"mappings":"AAiBA;;;;;GAKG;AAEH,OAAO,EACL,iBAAiB,EAGlB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACV,MAAM,wBAAwB,CAAC;AAGhC;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,kBAAkB;IACnE,UAAU,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,yBAAyB,CAAC;IACpF,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,yBAAyB,CAAC;CAC7D;AAkDD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,iBAAiB,EACvE,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC,GAC9C,yBAAyB,CAE3B"}

package/dist/src/factories/transaction_handler.js

@@ -0,0 +1,66 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newDirectedTransactionHandler = newDirectedTransactionHandler;
+const stage_director_1 = require("../helpers/stage_director");
+/**
+ * Internal base implementation for directed transaction handlers.
+ */
+class TransactionHandlerBase {
+    constructor(name, actionMap) {
+        this._name = name;
+        this.actionMap = actionMap;
+    }
+    name() {
+        return this._name;
+    }
+    withInitFn(initFn) {
+        this.initFn = initFn;
+        return this;
+    }
+    withCloseFn(closeFn) {
+        this.closeFn = closeFn;
+        return this;
+    }
+    async init(engAPI) {
+        if (this.initFn) {
+            await this.initFn(engAPI);
+        }
+    }
+    close() {
+        if (this.closeFn) {
+            this.closeFn();
+        }
+    }
+    async transactionHandlerBatch(reply, batch) {
+        await (0, stage_director_1.evalDirected)(reply, batch, this.actionMap);
+    }
+}
+/**
+ * Create a new simple directed handler, with no initialization.
+ *
+ * A directed handler uses the StageDirector pattern to route transactions
+ * to different actions based on the input's `action` field.
+ *
+ * @param name Handler name
+ * @param actionMap Map of action names to their configurations
+ * @returns A TransactionHandlerFactory for chaining
+ */
+function newDirectedTransactionHandler(name, actionMap) {
+    return new TransactionHandlerBase(name, actionMap);
+}
+//# sourceMappingURL=transaction_handler.js.map

package/dist/src/factories/transaction_handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction_handler.js","sourceRoot":"","sources":["../../../src/factories/transaction_handler.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;;AAwFjC,sEAKC;AAzED,8DAAyD;AAUzD;;GAEG;AACH,MAAM,sBAAsB;IAM1B,YAAY,IAAY,EAAE,SAA+C;QACvE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,UAAU,CAAC,MAA4C;QACrD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,WAAW,CAAC,OAAmB;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAiB;QAC1B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,uBAAuB,CAC3B,KAAiC,EACjC,KAA2B;QAE3B,MAAM,IAAA,6BAAY,EAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,SAAgB,6BAA6B,CAC3C,IAAY,EACZ,SAA+C;IAE/C,OAAO,IAAI,sBAAsB,CAAI,IAAI,EAAE,SAAS,CAAC,CAAC;AACxD,CAAC"}

package/dist/src/helpers/stage_director.d.ts

@@ -0,0 +1,42 @@
+import { DirectedActionConfig } from '../interfaces/handlers';
+import { EvalResult, HandlerEvent, Patch, StageDirector, Trigger, WSHandleTransactions, WSHandleTransactionsResult, WSEvaluateReplyResult, WSEvaluateTransaction, WithStageDirector } from '../types/core';
+/**
+ * Basic StageDirector implementation
+ */
+export declare class BasicStageDirector implements StageDirector, WithStageDirector {
+    action: string;
+    outputPath: string;
+    nextStage: string;
+    failureStage: string;
+    constructor(action: string, outputPath: string, nextStage: string, failureStage: string);
+    getStageDirector(): StageDirector;
+}
+/**
+ * Helper class for mapping evaluation results to WebSocket responses
+ */
+export declare class StageDirectorHelper {
+    /**
+     * Maps an evaluation result to a WebSocket reply result
+     */
+    static mapOutput(stageDirector: StageDirector, transaction: WSEvaluateTransaction, result: EvalResult, output?: any, error?: Error, triggers?: Trigger[], extraStateUpdates?: Patch, customStage?: string, events?: HandlerEvent[]): WSEvaluateReplyResult;
+}
+/**
+ * Evaluate a batch of directed transactions
+ *
+ * This is the core function that processes a batch of transactions using the
+ * StageDirector pattern. It groups transactions by action, executes them according
+ * to their invocation mode (PARALLEL or BATCH), and maps the results back to
+ * the workflow engine's expected format.
+ *
+ * @param reply The reply object to populate with results
+ * @param batch The batch of transactions to process
+ * @param actionMap Map of action names to their configurations
+ * @param parseInput Function to parse transaction input
+ *
+ * @example
+ * ```typescript
+ * evalDirected(reply, batch, actionMap, (input) => input as MyInput);
+ * ```
+ */
+export declare function evalDirected<T extends WithStageDirector>(reply: WSHandleTransactionsResult, batch: WSHandleTransactions, actionMap: Map<string, DirectedActionConfig<T>>): Promise<void>;
+//# sourceMappingURL=stage_director.d.ts.map

package/dist/src/helpers/stage_director.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage_director.d.ts","sourceRoot":"","sources":["../../../src/helpers/stage_director.ts"],"names":[],"mappings":"AA0BA,OAAO,EACL,oBAAoB,EAErB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,UAAU,EAEV,YAAY,EAEZ,KAAK,EAEL,aAAa,EACb,OAAO,EACP,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAKvB;;GAEG;AACH,qBAAa,kBAAmB,YAAW,aAAa,EAAE,iBAAiB;IAEhE,MAAM,EAAE,MAAM;IACd,UAAU,EAAE,MAAM;IAClB,SAAS,EAAE,MAAM;IACjB,YAAY,EAAE,MAAM;gBAHpB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;IAG7B,gBAAgB,IAAI,aAAa;CAGlC;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B;;OAEG;IACH,MAAM,CAAC,SAAS,CACd,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,qBAAqB,EAClC,MAAM,EAAE,UAAU,EAClB,MAAM,CAAC,EAAE,GAAG,EACZ,KAAK,CAAC,EAAE,KAAK,EACb,QAAQ,CAAC,EAAE,OAAO,EAAE,EACpB,iBAAiB,CAAC,EAAE,KAAK,EACzB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,YAAY,EAAE,GACtB,qBAAqB;CA6FzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,iBAAiB,EAC5D,KAAK,EAAE,0BAA0B,EACjC,KAAK,EAAE,oBAAoB,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,IAAI,CAAC,CA6Hf"}

package/dist/src/helpers/stage_director.js

@@ -0,0 +1,304 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StageDirectorHelper = exports.BasicStageDirector = void 0;
+exports.evalDirected = evalDirected;
+/**
+ * Stage Director Helper
+ *
+ * Provides the StageDirector pattern for building composable transaction handlers.
+ * The StageDirector pattern allows handlers to define multiple "actions" that can
+ * be configured to transition to different stages based on success or failure.
+ */
+const errors_1 = require("../i18n/errors");
+const logger_1 = require("../log/logger");
+const core_1 = require("../types/core");
+const errors_2 = require("../utils/errors");
+const log = (0, logger_1.newLogger)('stage_director.ts');
+/**
+ * Basic StageDirector implementation
+ */
+class BasicStageDirector {
+    constructor(action, outputPath, nextStage, failureStage) {
+        this.action = action;
+        this.outputPath = outputPath;
+        this.nextStage = nextStage;
+        this.failureStage = failureStage;
+    }
+    getStageDirector() {
+        return this;
+    }
+}
+exports.BasicStageDirector = BasicStageDirector;
+/**
+ * Helper class for mapping evaluation results to WebSocket responses
+ */
+class StageDirectorHelper {
+    /**
+     * Maps an evaluation result to a WebSocket reply result
+     */
+    static mapOutput(stageDirector, transaction, result, output, error, triggers, extraStateUpdates, customStage, events) {
+        const replyResult = {};
+        // Add triggers if provided
+        if (triggers && triggers.length > 0) {
+            replyResult.triggers = triggers;
+        }
+        // Add events if provided
+        if (events && events.length > 0) {
+            replyResult.events = events;
+        }
+        // Serialize output to state updates
+        if (output !== undefined && output !== null) {
+            if (!stageDirector.outputPath) {
+                log.error(`Transaction ${transaction.transactionId} cannot store output as outputPath is missing`);
+                if (!error) {
+                    error = (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKDirectorOutputPathMissing);
+                    result = core_1.EvalResult.FIXABLE_ERROR;
+                }
+            }
+            else {
+                replyResult.stateUpdates = [{
+                        op: core_1.PatchOpType.ADD,
+                        path: stageDirector.outputPath,
+                        value: output
+                    }];
+            }
+        }
+        // Append any extra state updates provided by the handler
+        if (extraStateUpdates && extraStateUpdates.length) {
+            replyResult.stateUpdates = (replyResult.stateUpdates || []).concat(extraStateUpdates);
+        }
+        // Set result based on evaluation outcome
+        switch (result) {
+            case core_1.EvalResult.HARD_FAILURE: {
+                // Check if failureStage is missing (validation inside switch for failure-stage handling)
+                const failureStage = stageDirector.failureStage;
+                if (!failureStage && !customStage) {
+                    log.error(`Transaction ${transaction.transactionId} cannot be transitioned due to missing failureStage`);
+                    if (!error) {
+                        error = (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKDirectorFailureStageMissing);
+                    }
+                    // Fall through to error handling below by breaking and letting default case handle it
+                    replyResult.error = error.message;
+                    log.debug(`Transaction ${transaction.transactionId} encountered error: ${error.message}`);
+                }
+                else {
+                    // Successfully transitioning to failure stage
+                    const next = customStage || failureStage;
+                    replyResult.stage = next;
+                    // Store error in state at /error path
+                    if (error) {
+                        if (!replyResult.stateUpdates) {
+                            replyResult.stateUpdates = [];
+                        }
+                        replyResult.stateUpdates.push({
+                            op: core_1.PatchOpType.ADD,
+                            path: '/error',
+                            value: error.message
+                        });
+                    }
+                    log.debug(`Transaction ${transaction.transactionId} directed to failureStage '${next}'`);
+                }
+                break;
+            }
+            case core_1.EvalResult.COMPLETE: {
+                const next = customStage || stageDirector.nextStage;
+                if (!next) {
+                    error = (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKDirectorNextStageMissing);
+                    return { error: error.message };
+                }
+                replyResult.stage = next;
+                log.debug(`Transaction ${transaction.transactionId} evaluated successfully and will transition to nextStage '${next}'`);
+                break;
+            }
+            case core_1.EvalResult.WAITING:
+                log.debug(`Transaction ${transaction.transactionId} evaluated successfully and will remain in stage`);
+                break;
+            case core_1.EvalResult.FIXABLE_ERROR:
+            case core_1.EvalResult.TRANSIENT_ERROR:
+            default:
+                if (error) {
+                    replyResult.error = error.message;
+                    log.debug(`Transaction ${transaction.transactionId} encountered error: ${error.message}`);
+                }
+                break;
+        }
+        return replyResult;
+    }
+}
+exports.StageDirectorHelper = StageDirectorHelper;
+/**
+ * Evaluate a batch of directed transactions
+ *
+ * This is the core function that processes a batch of transactions using the
+ * StageDirector pattern. It groups transactions by action, executes them according
+ * to their invocation mode (PARALLEL or BATCH), and maps the results back to
+ * the workflow engine's expected format.
+ *
+ * @param reply The reply object to populate with results
+ * @param batch The batch of transactions to process
+ * @param actionMap Map of action names to their configurations
+ * @param parseInput Function to parse transaction input
+ *
+ * @example
+ * ```typescript
+ * evalDirected(reply, batch, actionMap, (input) => input as MyInput);
+ * ```
+ */
+async function evalDirected(reply, batch, actionMap) {
+    reply.results = new Array(batch.transactions.length);
+    const byAction = new Map();
+    // Phase 1: Parse inputs and group by action
+    for (let i = 0; i < batch.transactions.length; i++) {
+        const req = batch.transactions[i];
+        log.debug(`Transaction id=${req.transactionId},workflow=${req.workflowId},stage=${req.stage} evaluating`);
+        const execReq = { idx: i, transaction: req, input: {} };
+        try {
+            // Direct type assertion for transaction input (JSON-deserialized generic type)
+            execReq.input = req.input;
+            // Check if input is valid (not null or undefined)
+            if (!execReq.input) {
+                throw (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKInputNullOrUndefined, req.stage);
+            }
+            // If input doesn't have getStageDirector method (plain object from JSON),
+            // wrap it to provide the method
+            if (typeof execReq.input.getStageDirector !== 'function') {
+                const plainInput = execReq.input;
+                // Validate that the plain input has the required action field
+                if (!plainInput.action) {
+                    throw (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKMissingActionField, req.stage, Object.keys(plainInput).join(', '));
+                }
+                execReq.input = {
+                    ...plainInput,
+                    getStageDirector: () => ({
+                        action: plainInput.action,
+                        outputPath: plainInput.outputPath,
+                        nextStage: plainInput.nextStage,
+                        failureStage: plainInput.failureStage
+                    })
+                };
+            }
+        }
+        catch (error) {
+            log.error(`Transaction id=${req.transactionId} could not be parsed: ${error}`);
+            reply.results[i] = {
+                error: `Input parsing error: ${(0, errors_2.getErrorMessage)(error)}`
+            };
+            continue;
+        }
+        const sd = execReq.input.getStageDirector();
+        const actionConf = actionMap.get(sd.action);
+        if (!actionConf) {
+            reply.results[i] = {
+                error: `Invalid action '${sd.action}' for handler '${batch.handler}'`
+            };
+            continue;
+        }
+        if (!byAction.has(sd.action)) {
+            byAction.set(sd.action, []);
+        }
+        byAction.get(sd.action).push(execReq);
+    }
+    // Phase 2: Execute transactions by action
+    const completions = [];
+    for (const [actionName, transactions] of byAction) {
+        const actionConf = actionMap.get(actionName);
+        switch (actionConf.invocationMode) {
+            case core_1.InvocationMode.PARALLEL:
+                // Execute each transaction in parallel
+                for (const req of transactions) {
+                    completions.push((async () => {
+                        req.result = await execMapped(actionConf, req.transaction, req.input);
+                        return req;
+                    })());
+                }
+                break;
+            case core_1.InvocationMode.BATCH: {
+                // Execute all transactions for this action as a batch
+                // Note: We execute the batch as one async operation, but add each
+                // individual transaction to completions
+                const batchPromise = (async () => {
+                    const batchIn = transactions.map(r => ({
+                        transaction: r.transaction,
+                        value: r.input
+                    }));
+                    const batchOut = await execBatchMapped(actionConf, batchIn);
+                    for (let i = 0; i < transactions.length; i++) {
+                        transactions[i].result = batchOut[i];
+                    }
+                    return transactions;
+                })();
+                // Add each transaction as a separate completion to maintain flat array structure
+                for (const req of transactions) {
+                    completions.push(batchPromise.then(() => req));
+                }
+                break;
+            }
+        }
+    }
+    // Phase 3: Wait for all completions and collect results
+    const completed = await Promise.all(completions);
+    for (const execReq of completed) {
+        if (execReq.result) {
+            reply.results[execReq.idx] = execReq.result;
+        }
+    }
+}
+/**
+ * Execute a single mapped transaction
+ */
+async function execMapped(config, transaction, input) {
+    try {
+        if (!config.handler) {
+            throw (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKHandlerNotConfigured);
+        }
+        const handlerResult = await config.handler(transaction, input);
+        const { result, output, error, triggers, extraUpdates, customStage, events } = handlerResult;
+        return StageDirectorHelper.mapOutput(input.getStageDirector(), transaction, result, output, error, triggers, extraUpdates, customStage, events);
+    }
+    catch (error) {
+        log.error(`Handler execution failed:`, error);
+        return {
+            error: (0, errors_2.getErrorMessage)(error)
+        };
+    }
+}
+/**
+ * Execute a batch of mapped transactions
+ */
+async function execBatchMapped(config, transactions) {
+    if (!config.batchHandler) {
+        throw (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKBatchHandlerNotConfigured);
+    }
+    try {
+        const batchResults = await config.batchHandler(transactions);
+        if (batchResults.length !== transactions.length) {
+            throw (0, errors_1.newError)(errors_1.SDKErrors.MsgSDKBatchHandlerResultCountMismatch, batchResults.length, transactions.length);
+        }
+        return transactions.map((req, i) => {
+            const batchResult = batchResults[i];
+            return StageDirectorHelper.mapOutput(req.value.getStageDirector(), req.transaction, batchResult.result, batchResult.output, batchResult.error, batchResult.triggers, batchResult.extraUpdates, batchResult.customStage);
+        });
+    }
+    catch (error) {
+        log.error(`Batch handler execution failed:`, error);
+        return transactions.map(() => ({
+            error: (0, errors_2.getErrorMessage)(error)
+        }));
+    }
+}
+//# sourceMappingURL=stage_director.js.map

package/dist/src/helpers/stage_director.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage_director.js","sourceRoot":"","sources":["../../../src/helpers/stage_director.ts"],"names":[],"mappings":"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"}

package/dist/src/i18n/errors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Internationalization for SDK error messages.
+ *
+ * Error codes follow the pattern: KA1406XX
+ * - KA: Kaleido prefix ,
+ * - 140: SDK error category
+ * - 6: SDK subcategory
+ * - XX: Specific error number
+ */
+export interface ErrorMessage {
+    code: string;
+    message: string;
+}
+/**
+ * SDK error messages
+ */
+export declare const SDKErrors: {
+    readonly MsgSDKObservedPanic: ErrorMessage;
+    readonly MsgSDKUnknownHandler: ErrorMessage;
+    readonly MsgSDKUnknownNoListenerConfig: ErrorMessage;
+    readonly MsgSDKOutputSerializationError: ErrorMessage;
+    readonly MsgSDKDirectorNextStageMissing: ErrorMessage;
+    readonly MsgSDKDirectorOutputPathMissing: ErrorMessage;
+    readonly MsgSDKDirectorFailureStageMissing: ErrorMessage;
+    readonly MsgSDKInputParsingError: ErrorMessage;
+    readonly MsgSDKInvalidAction: ErrorMessage;
+    readonly MsgSDKInvalidResult: ErrorMessage;
+    readonly MsgSDKCheckpointInvalidForHandler: ErrorMessage;
+    readonly MsgSDKStreamConfigInvalidForHandler: ErrorMessage;
+    readonly MsgSDKCheckpointInvalid: ErrorMessage;
+    readonly MsgSDKEventSourceDataInvalid: ErrorMessage;
+    readonly MsgSDKEngineReplyInvalidData: ErrorMessage;
+    readonly MsgSDKEngineReplyInvalidType: ErrorMessage;
+    readonly MsgSDKEngineReqNoActiveRequest: ErrorMessage;
+    readonly MsgSDKEngineFailMarshalEngineRequest: ErrorMessage;
+    readonly MsgSDKEngineFailSendEngineRequest: ErrorMessage;
+    readonly MsgSDKEngineNoTokenAuthRef: ErrorMessage;
+    readonly MsgSDKProviderNameNotSet: ErrorMessage;
+    readonly MsgSDKURLRequiredOutbound: ErrorMessage;
+    readonly MsgSDKWebSocketPortRequiredInbound: ErrorMessage;
+    readonly MsgSDKAccountNotSet: ErrorMessage;
+    readonly MsgSDKEnvironmentNotSet: ErrorMessage;
+    readonly MsgSDKWorkflowEngineNotSet: ErrorMessage;
+    readonly MsgSDKHandlerNotConfigured: ErrorMessage;
+    readonly MsgSDKBatchHandlerNotConfigured: ErrorMessage;
+    readonly MsgSDKBatchHandlerResultCountMismatch: ErrorMessage;
+    readonly MsgSDKInputNullOrUndefined: ErrorMessage;
+    readonly MsgSDKMissingActionField: ErrorMessage;
+    readonly MsgSDKConfigUnknownAuthType: ErrorMessage;
+    readonly MsgSDKEngineNotConnected: ErrorMessage;
+};
+/**
+ * Format an error message with arguments
+ * Supports simple %s, %d placeholders
+ */
+export declare function formatError(errorMsg: ErrorMessage, ...args: any[]): string;
+/**
+ * Create a new Error with an i18n message
+ */
+export declare function newError(errorMsg: ErrorMessage, ...args: any[]): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/i18n/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/i18n/errors.ts"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AASD;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CZ,CAAC;AAEX;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAS1E;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,KAAK,CAEtE"}

package/dist/src/i18n/errors.js

@@ -0,0 +1,90 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDKErrors = void 0;
+exports.formatError = formatError;
+exports.newError = newError;
+/**
+ * Create a formatted error with code and message
+ */
+function fe(code, template) {
+    return { code, message: template };
+}
+/**
+ * SDK error messages
+ */
+exports.SDKErrors = {
+    // Handler errors (KA1406XX)
+    MsgSDKObservedPanic: fe('KA140600', 'Observed panic: %s'),
+    MsgSDKUnknownHandler: fe('KA140601', "Unknown handler '%s'"),
+    MsgSDKUnknownNoListenerConfig: fe('KA140602', "Listener config for stream '%s' not supplied by workflow engine"),
+    MsgSDKOutputSerializationError: fe('KA140603', "Unable to serialize output to %s"),
+    MsgSDKDirectorNextStageMissing: fe('KA140604', "Handler called with 'nextStage' missing from input"),
+    MsgSDKDirectorOutputPathMissing: fe('KA140605', "Handler called with 'outputPath' missing from input"),
+    MsgSDKDirectorFailureStageMissing: fe('KA140606', "Handler resulted in a failure, but 'failureStage' missing from input"),
+    MsgSDKInputParsingError: fe('KA140607', 'Unable to parse input'),
+    MsgSDKInvalidAction: fe('KA140608', "Action '%s' is invalid for handler '%s'"),
+    MsgSDKInvalidResult: fe('KA140609', "Action '%s' gave unexpected result '%s' without error"),
+    // Event source errors
+    MsgSDKCheckpointInvalidForHandler: fe('KA140610', "Checkpoint could not be parsed by handler '%s'"),
+    MsgSDKStreamConfigInvalidForHandler: fe('KA140611', "Event stream config could not be parsed by handler '%s'"),
+    MsgSDKCheckpointInvalid: fe('KA140612', "Checkpoint generated by handler '%s' cannot be serialized"),
+    MsgSDKEventSourceDataInvalid: fe('KA140613', "Event source data could not be serialized for handler '%s'"),
+    // Engine API errors
+    MsgSDKEngineReplyInvalidData: fe('KA140614', "Engine API reply for transaction %s invalid: %s"),
+    MsgSDKEngineReplyInvalidType: fe('KA140615', "Engine API reply type for transaction %s invalid: %s"),
+    MsgSDKEngineReqNoActiveRequest: fe('KA140616', 'No engine handler is active on the supplied context'),
+    MsgSDKEngineFailMarshalEngineRequest: fe('KA140617', 'Failed to marshal engine transaction data'),
+    MsgSDKEngineFailSendEngineRequest: fe('KA140618', 'Failed to send engine transaction'),
+    MsgSDKEngineNoTokenAuthRef: fe('KA140619', "No auth token available in engine supplied context for authRef '%s'"),
+    // Configuration errors
+    MsgSDKProviderNameNotSet: fe('KA140620', 'Provider name not set'),
+    MsgSDKURLRequiredOutbound: fe('KA140630', 'URL is required in outbound mode'),
+    MsgSDKWebSocketPortRequiredInbound: fe('KA140631', 'WEBSOCKET_PORT is required in inbound mode'),
+    MsgSDKAccountNotSet: fe('KA140632', 'ACCOUNT is not set and no baseUrl provided'),
+    MsgSDKEnvironmentNotSet: fe('KA140633', 'ENVIRONMENT is not set and no baseUrl provided'),
+    MsgSDKWorkflowEngineNotSet: fe('KA140634', 'WORKFLOW_ENGINE is not set and no baseUrl provided'),
+    // Stage Director errors
+    MsgSDKHandlerNotConfigured: fe('KA140621', 'Handler not configured for this action'),
+    MsgSDKBatchHandlerNotConfigured: fe('KA140622', 'Handler not configured for BATCH invocation mode'),
+    MsgSDKBatchHandlerResultCountMismatch: fe('KA140623', 'Batch handler returned %d results but expected %d'),
+    MsgSDKInputNullOrUndefined: fe('KA140628', 'Input is null or undefined in stage %s'),
+    MsgSDKMissingActionField: fe('KA140629', 'Input is missing required "action" field in stage %s. Available fields: %s'),
+    // Configuration validation errors
+    MsgSDKConfigUnknownAuthType: fe('KA140626', 'Unknown auth type: %s'),
+    // Engine connection errors
+    MsgSDKEngineNotConnected: fe('KA140627', 'WebSocket is not connected. Cannot submit async transactions'),
+};
+/**
+ * Format an error message with arguments
+ * Supports simple %s, %d placeholders
+ */
+function formatError(errorMsg, ...args) {
+    let formatted = errorMsg.message;
+    for (const arg of args) {
+        // Replace first occurrence of %s or %d
+        formatted = formatted.replace(/%[sd]/, String(arg));
+    }
+    return `${errorMsg.code}: ${formatted}`;
+}
+/**
+ * Create a new Error with an i18n message
+ */
+function newError(errorMsg, ...args) {
+    return new Error(formatError(errorMsg, ...args));
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/i18n/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/i18n/errors.ts"],"names":[],"mappings":"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"}