@blokjs/shared 0.2.1 → 0.4.0

package/dist/BlokError.js

@@ -0,0 +1,328 @@
+import GlobalError from "./GlobalError";
+/**
+ * The categories every Blok node error falls into.
+ *
+ * Mirror of the proto `blok.runtime.v1.ErrorCategory` enum. Stored as string
+ * values so JSON payloads (e.g. `GlobalError.context.json`) are human-readable.
+ */
+export const ErrorCategory = {
+    VALIDATION: "VALIDATION",
+    CONFIGURATION: "CONFIGURATION",
+    DEPENDENCY: "DEPENDENCY",
+    TIMEOUT: "TIMEOUT",
+    PERMISSION: "PERMISSION",
+    RATE_LIMIT: "RATE_LIMIT",
+    NOT_FOUND: "NOT_FOUND",
+    CONFLICT: "CONFLICT",
+    CANCELLED: "CANCELLED",
+    INTERNAL: "INTERNAL",
+    PROTOCOL: "PROTOCOL",
+    DATA: "DATA",
+};
+/** How severe an error is. Default for thrown errors is `ERROR`. */
+export const ErrorSeverity = {
+    INFO: "INFO",
+    WARN: "WARN",
+    ERROR: "ERROR",
+    FATAL: "FATAL",
+};
+/**
+ * Default HTTP status per error category.
+ *
+ * Single source of truth — the runner uses these on `GlobalError.context.code`
+ * and HTTP triggers use them as the response status. Override per-error via
+ * `BlokErrorOpts.httpStatus`.
+ */
+export const DEFAULT_HTTP_STATUS = {
+    VALIDATION: 400,
+    CONFIGURATION: 500,
+    DEPENDENCY: 502,
+    TIMEOUT: 504,
+    PERMISSION: 403,
+    RATE_LIMIT: 429,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    CANCELLED: 499,
+    INTERNAL: 500,
+    PROTOCOL: 502,
+    DATA: 422,
+};
+/** Default retryable hint per error category. */
+export const DEFAULT_RETRYABLE = {
+    VALIDATION: false,
+    CONFIGURATION: false,
+    DEPENDENCY: true,
+    TIMEOUT: true,
+    PERMISSION: false,
+    RATE_LIMIT: true,
+    NOT_FOUND: false,
+    CONFLICT: false,
+    CANCELLED: false,
+    INTERNAL: false,
+    PROTOCOL: false,
+    DATA: false,
+};
+/**
+ * Structured error type for Blok nodes. Extends {@link GlobalError} so it
+ * remains fully compatible with existing `instanceof GlobalError` checks and
+ * `GlobalError.context` consumers (HTTP trigger, RunTracker, Studio).
+ *
+ * Use the static factory methods (`BlokError.validation`,
+ * `BlokError.dependency`, etc.) — direct construction is private.
+ *
+ * Auto-fills `name`, `stack`, and `at`. The runner enriches `node`, `sdk`,
+ * `sdkVersion`, and `runtimeKind` when the error is sourced from a runtime
+ * adapter; module nodes can override via {@link BlokErrorOpts}.
+ *
+ * @example
+ *   throw BlokError.dependency({
+ *     code: "POSTGRES_CONNECT_TIMEOUT",
+ *     message: "Could not connect to Postgres within 5s",
+ *     description: `Tried host=${host} port=${port}; timeout=${dur}ms`,
+ *     remediation: "Check DATABASE_URL env var and network reachability",
+ *     cause: err,
+ *   });
+ */
+export default class BlokError extends GlobalError {
+    category;
+    severity;
+    errorCode;
+    description;
+    remediation;
+    docUrl;
+    retryable;
+    retryAfterMs;
+    details;
+    contextSnapshot;
+    causes;
+    at;
+    sdk;
+    sdkVersion;
+    runtimeKind;
+    httpStatus;
+    nodeName;
+    constructor(category, opts) {
+        super(opts.message);
+        Object.setPrototypeOf(this, BlokError.prototype);
+        this.category = category;
+        this.severity = opts.severity ?? ErrorSeverity.ERROR;
+        this.errorCode = opts.code;
+        this.description = opts.description ?? "";
+        this.remediation = opts.remediation ?? "";
+        this.docUrl = opts.docUrl ?? "";
+        this.retryable = opts.retryable ?? DEFAULT_RETRYABLE[category];
+        this.retryAfterMs = opts.retryAfterMs ?? 0;
+        this.details = opts.details ?? null;
+        this.contextSnapshot = opts.contextSnapshot ?? null;
+        this.at = new Date();
+        this.sdk = opts.sdk ?? "";
+        this.sdkVersion = opts.sdkVersion ?? "";
+        this.runtimeKind = opts.runtimeKind ?? "";
+        this.nodeName = opts.node ?? "";
+        this.httpStatus = opts.httpStatus ?? DEFAULT_HTTP_STATUS[category];
+        this.causes = opts.cause ? Object.freeze(BlokError.flattenCauses(opts.cause)) : Object.freeze([]);
+        // Populate the GlobalError.context fields so legacy consumers keep working.
+        this.setCode(this.httpStatus);
+        this.setName(this.nodeName);
+        this.setStack(this.stack);
+        this.setJson(this.toJSON());
+    }
+    // =========================================================================
+    // Factory methods (one per category)
+    // =========================================================================
+    static validation(opts) {
+        return new BlokError(ErrorCategory.VALIDATION, opts);
+    }
+    static configuration(opts) {
+        return new BlokError(ErrorCategory.CONFIGURATION, opts);
+    }
+    static dependency(opts) {
+        return new BlokError(ErrorCategory.DEPENDENCY, opts);
+    }
+    static timeout(opts) {
+        return new BlokError(ErrorCategory.TIMEOUT, opts);
+    }
+    static permission(opts) {
+        return new BlokError(ErrorCategory.PERMISSION, opts);
+    }
+    static rateLimit(opts) {
+        return new BlokError(ErrorCategory.RATE_LIMIT, opts);
+    }
+    static notFound(opts) {
+        return new BlokError(ErrorCategory.NOT_FOUND, opts);
+    }
+    static conflict(opts) {
+        return new BlokError(ErrorCategory.CONFLICT, opts);
+    }
+    static cancelled(opts) {
+        return new BlokError(ErrorCategory.CANCELLED, opts);
+    }
+    static internal(opts) {
+        return new BlokError(ErrorCategory.INTERNAL, opts);
+    }
+    static protocol(opts) {
+        return new BlokError(ErrorCategory.PROTOCOL, opts);
+    }
+    static data(opts) {
+        return new BlokError(ErrorCategory.DATA, opts);
+    }
+    // =========================================================================
+    // Conversion
+    // =========================================================================
+    /**
+     * Convert any thrown value into a `BlokError`.
+     *
+     * Used by the runner's auto-wrap layer so legacy code (`throw new
+     * Error("oops")`) still produces a structured error. Categorization is
+     * heuristic — recognizes existing `BlokError` (passthrough), `GlobalError`
+     * (preserves code/json), `Error` (wraps as `INTERNAL`), and anything else
+     * (stringified as `INTERNAL`).
+     */
+    static fromUnknown(err, ctx) {
+        if (err instanceof BlokError) {
+            return err;
+        }
+        if (err instanceof GlobalError) {
+            const httpStatus = err.context.code ?? 500;
+            const wrapped = new BlokError(ErrorCategory.INTERNAL, {
+                code: "GLOBAL_ERROR",
+                message: err.message ?? "Unknown error",
+                details: err.context.json ?? null,
+                httpStatus,
+                node: ctx?.node ?? err.context.name ?? "",
+                sdk: ctx?.sdk,
+                sdkVersion: ctx?.sdkVersion,
+                runtimeKind: ctx?.runtimeKind,
+            });
+            if (err.stack)
+                wrapped.setStack(err.stack);
+            return wrapped;
+        }
+        if (err instanceof Error) {
+            return new BlokError(ErrorCategory.INTERNAL, {
+                code: `UNCAUGHT_${err.name || "ERROR"}`.toUpperCase(),
+                message: err.message || "Uncaught error",
+                cause: err,
+                node: ctx?.node,
+                sdk: ctx?.sdk,
+                sdkVersion: ctx?.sdkVersion,
+                runtimeKind: ctx?.runtimeKind,
+            });
+        }
+        return new BlokError(ErrorCategory.INTERNAL, {
+            code: "UNCAUGHT_ERROR",
+            message: typeof err === "string" ? err : JSON.stringify(err),
+            node: ctx?.node,
+            sdk: ctx?.sdk,
+            sdkVersion: ctx?.sdkVersion,
+            runtimeKind: ctx?.runtimeKind,
+        });
+    }
+    /**
+     * Reconstruct a `BlokError` from a serialized {@link NodeErrorPayload}.
+     *
+     * Used by the runner's gRPC codec to convert proto `NodeError` messages
+     * received from SDKs back into TS-side errors.
+     */
+    static fromJSON(payload) {
+        const err = new BlokError(payload.category, {
+            code: payload.code,
+            message: payload.message,
+            description: payload.description,
+            remediation: payload.remediation,
+            docUrl: payload.docUrl,
+            retryable: payload.retryable,
+            retryAfterMs: payload.retryAfterMs,
+            details: payload.details,
+            contextSnapshot: payload.contextSnapshot,
+            httpStatus: payload.httpStatus,
+            severity: payload.severity,
+            node: payload.node,
+            sdk: payload.sdk,
+            sdkVersion: payload.sdkVersion,
+            runtimeKind: payload.runtimeKind,
+        });
+        if (payload.stack)
+            err.setStack(payload.stack);
+        // Restore frozen causes from payload (causes are NodeErrorPayload[], not BlokError).
+        err.causes = Object.freeze([...payload.causes]);
+        return err;
+    }
+    /** Serialize to the canonical {@link NodeErrorPayload} shape (matches proto wire format). */
+    toJSON() {
+        return {
+            code: this.errorCode,
+            category: this.category,
+            severity: this.severity,
+            node: this.nodeName,
+            sdk: this.sdk,
+            sdkVersion: this.sdkVersion,
+            runtimeKind: this.runtimeKind,
+            at: this.at.toISOString(),
+            message: this.message,
+            description: this.description,
+            remediation: this.remediation,
+            docUrl: this.docUrl,
+            causes: [...this.causes],
+            stack: this.stack ?? "",
+            contextSnapshot: this.contextSnapshot,
+            httpStatus: this.httpStatus,
+            retryable: this.retryable,
+            retryAfterMs: this.retryAfterMs,
+            details: this.details,
+        };
+    }
+    // =========================================================================
+    // Internal helpers
+    // =========================================================================
+    static flattenCauses(cause) {
+        const causes = [];
+        let current = cause;
+        const visited = new Set();
+        while (current && !visited.has(current)) {
+            visited.add(current);
+            if (current instanceof BlokError) {
+                // Append the BlokError's own payload (with `causes` zeroed out so we
+                // don't double-count) followed by its already-flattened causes. This
+                // keeps the final chain flat regardless of how deeply nested the
+                // caller's BlokError-as-cause chain was.
+                causes.push(BlokError.causeToPayload(current));
+                causes.push(...current.causes);
+                break;
+            }
+            causes.push(BlokError.causeToPayload(current));
+            const nextCause = current.cause;
+            current = nextCause;
+        }
+        return causes;
+    }
+    static causeToPayload(cause) {
+        if (cause instanceof BlokError) {
+            // Strip the cause's own `causes` to avoid duplication — the caller
+            // (flattenCauses) appends them separately to keep the final list flat.
+            return { ...cause.toJSON(), causes: [] };
+        }
+        return {
+            code: `UNCAUGHT_${cause.name || "ERROR"}`.toUpperCase(),
+            category: ErrorCategory.INTERNAL,
+            severity: ErrorSeverity.ERROR,
+            node: "",
+            sdk: "",
+            sdkVersion: "",
+            runtimeKind: "",
+            at: new Date().toISOString(),
+            message: cause.message || "Uncaught error",
+            description: "",
+            remediation: "",
+            docUrl: "",
+            causes: [],
+            stack: cause.stack ?? "",
+            contextSnapshot: null,
+            httpStatus: 500,
+            retryable: false,
+            retryAfterMs: 0,
+            details: null,
+        };
+    }
+}
+//# sourceMappingURL=BlokError.js.map

package/dist/BlokError.js.map

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

package/dist/NodeBase.d.ts

@@ -13,14 +13,108 @@ export default abstract class NodeBase {
     active: boolean;
     stop: boolean;
     originalConfig: ParamsDictionary;
-    set_var: boolean;
+    /**
+     * @deprecated v2 default-stores every step's output. `set_var: true` is
+     * a no-op (default behaviour); `set_var: false` is normalized to
+     * `ephemeral: true` at workflow load time. Reading this field is still
+     * supported for legacy code paths but new code should rely on `ephemeral`.
+     *
+     * Default is `undefined` (NOT `false`) — `false` here would short-circuit
+     * `PersistenceHelper.applyStepOutput` and disable the v2 default-store
+     * rule for every step that didn't explicitly set the field.
+     */
+    set_var?: boolean;
+    /**
+     * Alternative state key for this step's output. When set, the runner
+     * stores result.data at `ctx.state[as]` instead of `ctx.state[name]`.
+     */
+    as?: string;
+    /**
+     * When true, the runner shallow-merges the keys of result.data into
+     * `ctx.state` instead of nesting under the step name. Mutually exclusive
+     * with `as`.
+     */
+    spread: boolean;
+    /**
+     * When true, the runner skips persisting this step's output to state.
+     * Only `ctx.prev` carries the result to the immediately next step.
+     */
+    ephemeral: boolean;
+    /**
+     * Optional cache key for this step's result. When set, the runner consults
+     * the idempotency cache before executing — a hit returns the cached result
+     * (and emits a NODE_CACHED event); a miss runs the step and caches its
+     * result on success. Cache namespace is (workflowName, name, idempotencyKey).
+     *
+     * Author-facing values may be a literal string ("user-123") or a $ proxy
+     * expression compiled to `js/ctx....`. The runner resolves the expression
+     * against the live ctx at run time before consulting the cache.
+     */
+    idempotencyKey?: string;
+    /**
+     * Optional cache lifetime in milliseconds. Defaults to 24 hours
+     * (86_400_000) when undefined. Pass 0 to mark a stored result as
+     * immediately expired (effectively disables caching for this step).
+     */
+    idempotencyKeyTTL?: number;
+    /**
+     * Optional retry configuration with capped exponential backoff. When
+     * undefined, the step runs at most once (matches pre-v0.3.x behaviour).
+     * Per-attempt failures emit `NODE_ATTEMPT_FAILED` trace events.
+     */
+    retry?: {
+        maxAttempts: number;
+        minTimeoutInMs?: number;
+        maxTimeoutInMs?: number;
+        factor?: number;
+    };
+    /**
+     * Tier 2 quick-wins — per-attempt execution timeout in milliseconds.
+     * When set, `RunnerSteps` wraps each `step.process()` in a setTimeout-
+     * based Promise.race. On timeout, throws `StepTimeoutError` (which the
+     * retry loop treats as any other error). On final-attempt timeout,
+     * the run auto-flips to `"timedOut"` status. When undefined, the
+     * step runs without a per-attempt cap (matches pre-quick-wins
+     * behaviour).
+     *
+     * Originally set as a duration string or number on the step schema;
+     * `Configuration.getSteps` converts to milliseconds via
+     * `parseDuration` before assigning here.
+     */
+    maxDurationMs?: number;
+    /**
+     * Name of the workflow to invoke when this step runs. When set, the
+     * step's `node` ref is `"@blokjs/subworkflow"` (a sentinel) and the
+     * runner resolves it to a `SubworkflowNode` that looks up the child
+     * by this name in the `WorkflowRegistry` singleton.
+     */
+    subworkflow?: string;
+    /**
+     * If true (default), the parent step blocks until the child workflow
+     * completes. The child's `ctx.response` becomes the parent step's
+     * output (lands on `state[<id>]` like any other step).
+     *
+     * `wait: false` (fire-and-forget) is rejected at workflow load time
+     * in v0.3.x — the schema includes a deferred-feature error message.
+     */
+    wait?: boolean;
     process(ctx: Context, step?: Step): Promise<ResponseContext>;
     processFlow(ctx: Context): Promise<ResponseContext>;
     abstract run(ctx: Context): Promise<ResponseContext>;
     runSteps(step: Step | Step[], ctx: Context): Promise<Context>;
     runJs(str: string, ctx: Context, data?: ParamsDictionary, func?: FunctionContext, vars?: VarsContext): ParamsDictionary;
+    /**
+     * @deprecated In v2, return your output and let the runner persist it
+     * to `ctx.state[id]` automatically. Use `ctx.publish(name, value)` for
+     * explicit side-channel publication when you really need it. This
+     * method continues to work for legacy code.
+     */
     setVar(ctx: Context, vars: VarsContext): void;
-    getVar(ctx: Context, name: string): ParamsDictionary | undefined;
+    /**
+     * @deprecated Read from `ctx.state[name]` directly, or reference it from
+     * a workflow step's `inputs` as `$.state[name]` / `js/ctx.state.name`.
+     */
+    getVar(ctx: Context, name: string): unknown;
     blueprintMapper: (obj: ParamsDictionary, ctx: Context, data?: ParamsDictionary) => string | ParamsDictionary;
     setError(config: ErrorContext): GlobalError;
 }

package/dist/NodeBase.js

@@ -1,6 +1,7 @@
 import _ from "lodash";
 import GlobalError from "./GlobalError";
 import mapper from "./utils/Mapper";
+import { MapperResolutionError } from "./utils/MapperResolutionError";
 export default class NodeBase {
     flow = false;
     name = "";
@@ -8,7 +9,106 @@ export default class NodeBase {
     active = true;
     stop = false;
     originalConfig = {};
-    set_var = false;
+    /**
+     * @deprecated v2 default-stores every step's output. `set_var: true` is
+     * a no-op (default behaviour); `set_var: false` is normalized to
+     * `ephemeral: true` at workflow load time. Reading this field is still
+     * supported for legacy code paths but new code should rely on `ephemeral`.
+     *
+     * Default is `undefined` (NOT `false`) — `false` here would short-circuit
+     * `PersistenceHelper.applyStepOutput` and disable the v2 default-store
+     * rule for every step that didn't explicitly set the field.
+     */
+    set_var;
+    // =========================================================================
+    // V2 persistence knobs — populated by Configuration.getSteps from the
+    // step definition. Read by PersistenceHelper.applyStepOutput.
+    // =========================================================================
+    /**
+     * Alternative state key for this step's output. When set, the runner
+     * stores result.data at `ctx.state[as]` instead of `ctx.state[name]`.
+     */
+    as;
+    /**
+     * When true, the runner shallow-merges the keys of result.data into
+     * `ctx.state` instead of nesting under the step name. Mutually exclusive
+     * with `as`.
+     */
+    spread = false;
+    /**
+     * When true, the runner skips persisting this step's output to state.
+     * Only `ctx.prev` carries the result to the immediately next step.
+     */
+    ephemeral = false;
+    // =========================================================================
+    // V2 idempotency cache + retry knobs — populated by Configuration.getSteps
+    // from the step definition. Read by RunnerSteps before delegating to
+    // `step.process()`. Caching layers ABOVE PersistenceHelper.applyStepOutput;
+    // retry wraps the same call site.
+    //
+    // Mirrors the Zod schema in `@blokjs/helper/src/types/StepOpts.ts`. Kept
+    // as a structural interface here to avoid a runtime dep from shared on
+    // helper.
+    // =========================================================================
+    /**
+     * Optional cache key for this step's result. When set, the runner consults
+     * the idempotency cache before executing — a hit returns the cached result
+     * (and emits a NODE_CACHED event); a miss runs the step and caches its
+     * result on success. Cache namespace is (workflowName, name, idempotencyKey).
+     *
+     * Author-facing values may be a literal string ("user-123") or a $ proxy
+     * expression compiled to `js/ctx....`. The runner resolves the expression
+     * against the live ctx at run time before consulting the cache.
+     */
+    idempotencyKey;
+    /**
+     * Optional cache lifetime in milliseconds. Defaults to 24 hours
+     * (86_400_000) when undefined. Pass 0 to mark a stored result as
+     * immediately expired (effectively disables caching for this step).
+     */
+    idempotencyKeyTTL;
+    /**
+     * Optional retry configuration with capped exponential backoff. When
+     * undefined, the step runs at most once (matches pre-v0.3.x behaviour).
+     * Per-attempt failures emit `NODE_ATTEMPT_FAILED` trace events.
+     */
+    retry;
+    /**
+     * Tier 2 quick-wins — per-attempt execution timeout in milliseconds.
+     * When set, `RunnerSteps` wraps each `step.process()` in a setTimeout-
+     * based Promise.race. On timeout, throws `StepTimeoutError` (which the
+     * retry loop treats as any other error). On final-attempt timeout,
+     * the run auto-flips to `"timedOut"` status. When undefined, the
+     * step runs without a per-attempt cap (matches pre-quick-wins
+     * behaviour).
+     *
+     * Originally set as a duration string or number on the step schema;
+     * `Configuration.getSteps` converts to milliseconds via
+     * `parseDuration` before assigning here.
+     */
+    maxDurationMs;
+    // =========================================================================
+    // V2 sub-workflow knobs — populated by Configuration.getSteps for steps
+    // that invoke another workflow (`subworkflow: "<name>"` shape). Read by
+    // `SubworkflowNode.run()` to look up the child workflow in the
+    // WorkflowRegistry. Mirrors the Zod schema in `@blokjs/helper`.
+    // =========================================================================
+    /**
+     * Name of the workflow to invoke when this step runs. When set, the
+     * step's `node` ref is `"@blokjs/subworkflow"` (a sentinel) and the
+     * runner resolves it to a `SubworkflowNode` that looks up the child
+     * by this name in the `WorkflowRegistry` singleton.
+     */
+    subworkflow;
+    /**
+     * If true (default), the parent step blocks until the child workflow
+     * completes. The child's `ctx.response` becomes the parent step's
+     * output (lands on `state[<id>]` like any other step).
+     *
+     * `wait: false` (fire-and-forget) is rejected at workflow load time
+     * in v0.3.x — the schema includes a deferred-feature error message.
+     */
+    wait;
     async process(ctx, step) {
         let response = {
             success: true,
@@ -49,11 +149,21 @@ export default class NodeBase {
     runJs(str, ctx, data = {}, func = {}, vars = {}) {
         return Function("ctx", "data", "func", "vars", `"use strict";return (${str});`)(ctx, data, func, vars);
     }
+    /**
+     * @deprecated In v2, return your output and let the runner persist it
+     * to `ctx.state[id]` automatically. Use `ctx.publish(name, value)` for
+     * explicit side-channel publication when you really need it. This
+     * method continues to work for legacy code.
+     */
     setVar(ctx, vars) {
         if (ctx.vars === undefined)
             ctx.vars = {};
         ctx.vars = { ...ctx.vars, ...vars };
     }
+    /**
+     * @deprecated Read from `ctx.state[name]` directly, or reference it from
+     * a workflow step's `inputs` as `$.state[name]` / `js/ctx.state.name`.
+     */
     getVar(ctx, name) {
         return ctx.vars?.[name];
     }
@@ -66,7 +176,15 @@ export default class NodeBase {
                 mapper.replaceObjectStrings(newObj, ctx, data);
         }
         catch (e) {
-            console.log("MAPPER ERROR", e);
+            // `MapperResolutionError` (strict mode) carries full diagnostic
+            // context — let it escape so the step's error envelope surfaces
+            // the workflow / step / expression that failed.
+            if (e instanceof MapperResolutionError)
+                throw e;
+            // Anything else here is an UNEXPECTED bug in the mapper itself
+            // (recursion fault, OOM, logger crash). Surface loudly via
+            // stderr WITH the stack trace — never silently swallow.
+            console.error("[blok][mapper] unexpected error during input resolution:", e);
         }
         return newObj;
     };

package/dist/NodeBase.js.map

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

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import BlokError, { type BlokErrorOpts, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, ErrorCategory, ErrorSeverity, type NodeErrorPayload } from "./BlokError";
 import GlobalError from "./GlobalError";
 import GlobalLogger from "./GlobalLogger";
 import { Metrics, type MetricsType } from "./Metrics";
@@ -11,6 +12,8 @@ import LoggerContext from "./types/LoggerContext";
 import NodeConfigContext from "./types/NodeConfigContext";
 import RequestContext from "./types/RequestContext";
 import ResponseContext from "./types/ResponseContext";
+import StateContext from "./types/StateContext";
 import Step from "./types/Step";
+import VarsContext from "./types/VarsContext";
 import MemoryUsage from "./utils/MemoryUsage";
-export { NodeBase, Context, RequestContext, ResponseContext, ErrorContext, LoggerContext, ConfigContext, Trigger, NodeConfigContext, FunctionContext, Step, GlobalLogger, GlobalError, Metrics, MemoryUsage, type MetricsType, };
+export { NodeBase, Context, RequestContext, ResponseContext, ErrorContext, LoggerContext, ConfigContext, Trigger, NodeConfigContext, FunctionContext, StateContext, VarsContext, Step, GlobalLogger, GlobalError, BlokError, type BlokErrorOpts, type NodeErrorPayload, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, type MetricsType, };

package/dist/index.js

@@ -1,8 +1,9 @@
+import BlokError, { DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, ErrorCategory, ErrorSeverity, } from "./BlokError";
 import GlobalError from "./GlobalError";
 import GlobalLogger from "./GlobalLogger";
 import { Metrics } from "./Metrics";
 import NodeBase from "./NodeBase";
 import Trigger from "./Trigger";
 import MemoryUsage from "./utils/MemoryUsage";
-export { NodeBase, Trigger, GlobalLogger, GlobalError, Metrics, MemoryUsage, };
+export { NodeBase, Trigger, GlobalLogger, GlobalError, BlokError, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,eAAe,CAAC;AACxC,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,QAAQ,MAAM,YAAY,CAAC;AAClC,OAAO,OAAO,MAAM,WAAW,CAAC;AAUhC,OAAO,WAAW,MAAM,qBAAqB,CAAC;AAE9C,OAAO,EACN,QAAQ,EAOR,OAAO,EAIP,YAAY,EACZ,WAAW,EACX,OAAO,EACP,WAAW,GAEX,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,EAAE,EAEjB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,aAAa,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,WAAW,MAAM,eAAe,CAAC;AACxC,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,QAAQ,MAAM,YAAY,CAAC;AAClC,OAAO,OAAO,MAAM,WAAW,CAAC;AAYhC,OAAO,WAAW,MAAM,qBAAqB,CAAC;AAE9C,OAAO,EACN,QAAQ,EAOR,OAAO,EAMP,YAAY,EACZ,WAAW,EACX,SAAS,EAGT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,WAAW,GAEX,CAAC"}