@blokjs/shared 0.2.1 → 0.2.2

package/__tests__/unit/BlokError.test.ts

@@ -0,0 +1,294 @@
+import { describe, expect, it } from "vitest";
+import BlokError, {
+	DEFAULT_HTTP_STATUS,
+	DEFAULT_RETRYABLE,
+	ErrorCategory,
+	ErrorSeverity,
+	type NodeErrorPayload,
+} from "../../src/BlokError";
+import GlobalError from "../../src/GlobalError";
+
+describe("BlokError", () => {
+	describe("factory methods", () => {
+		const factories = [
+			{ name: "validation", method: BlokError.validation, expected: ErrorCategory.VALIDATION },
+			{ name: "configuration", method: BlokError.configuration, expected: ErrorCategory.CONFIGURATION },
+			{ name: "dependency", method: BlokError.dependency, expected: ErrorCategory.DEPENDENCY },
+			{ name: "timeout", method: BlokError.timeout, expected: ErrorCategory.TIMEOUT },
+			{ name: "permission", method: BlokError.permission, expected: ErrorCategory.PERMISSION },
+			{ name: "rateLimit", method: BlokError.rateLimit, expected: ErrorCategory.RATE_LIMIT },
+			{ name: "notFound", method: BlokError.notFound, expected: ErrorCategory.NOT_FOUND },
+			{ name: "conflict", method: BlokError.conflict, expected: ErrorCategory.CONFLICT },
+			{ name: "cancelled", method: BlokError.cancelled, expected: ErrorCategory.CANCELLED },
+			{ name: "internal", method: BlokError.internal, expected: ErrorCategory.INTERNAL },
+			{ name: "protocol", method: BlokError.protocol, expected: ErrorCategory.PROTOCOL },
+			{ name: "data", method: BlokError.data, expected: ErrorCategory.DATA },
+		];
+
+		for (const { name, method, expected } of factories) {
+			it(`${name}() creates an error with the right category`, () => {
+				const err = method({ code: "TEST", message: "test" });
+				expect(err.category).toBe(expected);
+				expect(err).toBeInstanceOf(BlokError);
+				expect(err).toBeInstanceOf(GlobalError);
+				expect(err).toBeInstanceOf(Error);
+			});
+		}
+
+		it("each factory applies the default http_status for its category", () => {
+			for (const { method, expected } of factories) {
+				const err = method({ code: "TEST", message: "test" });
+				expect(err.httpStatus).toBe(DEFAULT_HTTP_STATUS[expected]);
+				expect(err.context.code).toBe(DEFAULT_HTTP_STATUS[expected]);
+			}
+		});
+
+		it("each factory applies the default retryable hint for its category", () => {
+			for (const { method, expected } of factories) {
+				const err = method({ code: "TEST", message: "test" });
+				expect(err.retryable).toBe(DEFAULT_RETRYABLE[expected]);
+			}
+		});
+
+		it("defaults severity to ERROR", () => {
+			const err = BlokError.dependency({ code: "X", message: "x" });
+			expect(err.severity).toBe(ErrorSeverity.ERROR);
+		});
+	});
+
+	describe("constructor options", () => {
+		it("preserves all human-readable fields", () => {
+			const err = BlokError.dependency({
+				code: "POSTGRES_CONNECT_TIMEOUT",
+				message: "Could not connect to Postgres within 5s",
+				description: "Tried host=localhost port=5432; timeout=5000ms",
+				remediation: "Check DATABASE_URL env var and network reachability",
+				docUrl: "https://blok.dev/errors/POSTGRES_CONNECT_TIMEOUT",
+			});
+
+			expect(err.errorCode).toBe("POSTGRES_CONNECT_TIMEOUT");
+			expect(err.message).toBe("Could not connect to Postgres within 5s");
+			expect(err.description).toContain("port=5432");
+			expect(err.remediation).toContain("DATABASE_URL");
+			expect(err.docUrl).toContain("POSTGRES_CONNECT_TIMEOUT");
+		});
+
+		it("allows overriding httpStatus", () => {
+			const err = BlokError.dependency({ code: "X", message: "x", httpStatus: 503 });
+			expect(err.httpStatus).toBe(503);
+			expect(err.context.code).toBe(503);
+		});
+
+		it("allows overriding retryable + retryAfterMs", () => {
+			const err = BlokError.dependency({
+				code: "X",
+				message: "x",
+				retryable: false,
+				retryAfterMs: 0,
+			});
+			expect(err.retryable).toBe(false);
+			expect(err.retryAfterMs).toBe(0);
+		});
+
+		it("allows overriding severity", () => {
+			const err = BlokError.timeout({
+				code: "X",
+				message: "x",
+				severity: ErrorSeverity.FATAL,
+			});
+			expect(err.severity).toBe(ErrorSeverity.FATAL);
+		});
+
+		it("captures structured details", () => {
+			const err = BlokError.validation({
+				code: "VALIDATION_FAILED",
+				message: "schema mismatch",
+				details: { issues: [{ path: "email", message: "invalid" }] },
+			});
+			expect(err.details).toEqual({ issues: [{ path: "email", message: "invalid" }] });
+		});
+
+		it("captures contextSnapshot", () => {
+			const snapshot = { inputs: { foo: "bar" }, varsKeys: ["a", "b"] };
+			const err = BlokError.internal({
+				code: "OOPS",
+				message: "oops",
+				contextSnapshot: snapshot,
+			});
+			expect(err.contextSnapshot).toEqual(snapshot);
+		});
+	});
+
+	describe("cause chain", () => {
+		it("flattens a single Error cause", () => {
+			const inner = new Error("connect ECONNREFUSED");
+			const outer = BlokError.dependency({
+				code: "DB_DOWN",
+				message: "Database unreachable",
+				cause: inner,
+			});
+
+			expect(outer.causes).toHaveLength(1);
+			expect(outer.causes[0].message).toBe("connect ECONNREFUSED");
+			expect(outer.causes[0].category).toBe(ErrorCategory.INTERNAL);
+		});
+
+		it("flattens a BlokError cause without re-wrapping its own causes", () => {
+			const root = BlokError.timeout({ code: "DNS_TIMEOUT", message: "dns timed out" });
+			const middle = BlokError.dependency({ code: "DB_DOWN", message: "db unreachable", cause: root });
+			const top = BlokError.internal({ code: "REQUEST_FAILED", message: "request failed", cause: middle });
+
+			expect(top.causes).toHaveLength(2);
+			expect(top.causes[0].code).toBe("DB_DOWN");
+			expect(top.causes[1].code).toBe("DNS_TIMEOUT");
+		});
+
+		it("returns an empty causes array when no cause is provided", () => {
+			const err = BlokError.internal({ code: "X", message: "x" });
+			expect(err.causes).toHaveLength(0);
+		});
+
+		it("does not infinite-loop on circular causes", () => {
+			const a = new Error("a");
+			const b = new Error("b");
+			(a as Error & { cause?: Error }).cause = b;
+			(b as Error & { cause?: Error }).cause = a;
+
+			expect(() => BlokError.internal({ code: "CYCLE", message: "circular", cause: a })).not.toThrow();
+		});
+	});
+
+	describe("GlobalError compatibility", () => {
+		it("populates context.code with httpStatus", () => {
+			const err = BlokError.notFound({ code: "USER_NOT_FOUND", message: "no user" });
+			expect(err.context.code).toBe(404);
+		});
+
+		it("populates context.name with node when provided", () => {
+			const err = BlokError.dependency({ code: "X", message: "x", node: "fetch-user" });
+			expect(err.context.name).toBe("fetch-user");
+		});
+
+		it("populates context.json with the full payload", () => {
+			const err = BlokError.dependency({
+				code: "DB_DOWN",
+				message: "db down",
+				description: "host unreachable",
+				remediation: "check network",
+			});
+			const payload = err.context.json as unknown as NodeErrorPayload;
+			expect(payload.code).toBe("DB_DOWN");
+			expect(payload.category).toBe(ErrorCategory.DEPENDENCY);
+			expect(payload.description).toBe("host unreachable");
+			expect(payload.remediation).toBe("check network");
+		});
+	});
+
+	describe("toJSON / fromJSON round-trip", () => {
+		it("preserves every field", () => {
+			const inner = BlokError.timeout({
+				code: "INNER_TIMEOUT",
+				message: "inner timed out",
+			});
+			const original = BlokError.dependency({
+				code: "DB_DOWN",
+				message: "Database unreachable",
+				description: "Tried host=db port=5432",
+				remediation: "Check DATABASE_URL",
+				docUrl: "https://blok.dev/errors/DB_DOWN",
+				cause: inner,
+				retryable: true,
+				retryAfterMs: 5000,
+				details: { sqlState: "08001" },
+				contextSnapshot: { inputs: { query: "SELECT 1" } },
+				httpStatus: 503,
+				severity: ErrorSeverity.WARN,
+				node: "store-tutorial",
+				sdk: "blok-python3",
+				sdkVersion: "1.0.0",
+				runtimeKind: "runtime.python3",
+			});
+
+			const json = original.toJSON();
+			const restored = BlokError.fromJSON(json);
+
+			expect(restored.errorCode).toBe(original.errorCode);
+			expect(restored.category).toBe(original.category);
+			expect(restored.severity).toBe(original.severity);
+			expect(restored.message).toBe(original.message);
+			expect(restored.description).toBe(original.description);
+			expect(restored.remediation).toBe(original.remediation);
+			expect(restored.docUrl).toBe(original.docUrl);
+			expect(restored.retryable).toBe(original.retryable);
+			expect(restored.retryAfterMs).toBe(original.retryAfterMs);
+			expect(restored.details).toEqual(original.details);
+			expect(restored.contextSnapshot).toEqual(original.contextSnapshot);
+			expect(restored.httpStatus).toBe(original.httpStatus);
+			expect(restored.nodeName).toBe(original.nodeName);
+			expect(restored.sdk).toBe(original.sdk);
+			expect(restored.sdkVersion).toBe(original.sdkVersion);
+			expect(restored.runtimeKind).toBe(original.runtimeKind);
+			expect(restored.causes).toEqual(original.causes);
+		});
+
+		it("toJSON produces an ISO timestamp for `at`", () => {
+			const err = BlokError.internal({ code: "X", message: "x" });
+			const json = err.toJSON();
+			expect(json.at).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+			expect(new Date(json.at).getTime()).not.toBeNaN();
+		});
+	});
+
+	describe("fromUnknown", () => {
+		it("passes BlokError through unchanged", () => {
+			const original = BlokError.dependency({ code: "X", message: "x" });
+			const wrapped = BlokError.fromUnknown(original);
+			expect(wrapped).toBe(original);
+		});
+
+		it("wraps a plain Error as INTERNAL with UNCAUGHT_<NAME> code", () => {
+			const err = new TypeError("bad type");
+			const wrapped = BlokError.fromUnknown(err);
+			expect(wrapped.category).toBe(ErrorCategory.INTERNAL);
+			expect(wrapped.errorCode).toBe("UNCAUGHT_TYPEERROR");
+			expect(wrapped.message).toBe("bad type");
+			expect(wrapped.causes).toHaveLength(1);
+		});
+
+		it("wraps a string as INTERNAL/UNCAUGHT_ERROR", () => {
+			const wrapped = BlokError.fromUnknown("oops");
+			expect(wrapped.category).toBe(ErrorCategory.INTERNAL);
+			expect(wrapped.errorCode).toBe("UNCAUGHT_ERROR");
+			expect(wrapped.message).toBe("oops");
+		});
+
+		it("wraps a non-Error value as INTERNAL/UNCAUGHT_ERROR with stringified message", () => {
+			const wrapped = BlokError.fromUnknown({ weird: true });
+			expect(wrapped.category).toBe(ErrorCategory.INTERNAL);
+			expect(wrapped.errorCode).toBe("UNCAUGHT_ERROR");
+			expect(wrapped.message).toContain("weird");
+		});
+
+		it("preserves a pre-existing GlobalError code and json", () => {
+			const ge = new GlobalError("legacy");
+			ge.setCode(403);
+			ge.setJson({ origin: "auth" });
+			const wrapped = BlokError.fromUnknown(ge);
+			expect(wrapped.httpStatus).toBe(403);
+			expect(wrapped.details).toEqual({ origin: "auth" });
+		});
+
+		it("uses ctx overrides for node/sdk/sdkVersion/runtimeKind", () => {
+			const wrapped = BlokError.fromUnknown(new Error("x"), {
+				node: "step-1",
+				sdk: "blok-go",
+				sdkVersion: "1.0.0",
+				runtimeKind: "runtime.go",
+			});
+			expect(wrapped.nodeName).toBe("step-1");
+			expect(wrapped.sdk).toBe("blok-go");
+			expect(wrapped.sdkVersion).toBe("1.0.0");
+			expect(wrapped.runtimeKind).toBe("runtime.go");
+		});
+	});
+});

package/__tests__/unit/NodeBase.test.ts

@@ -46,7 +46,10 @@ describe("NodeBase", () => {
 			expect(n.name).toBe("");
 			expect(n.active).toBe(true);
 			expect(n.stop).toBe(false);
-			expect(n.set_var).toBe(false);
+			// set_var defaults to undefined (NOT false). false short-circuits
+			// PersistenceHelper.applyStepOutput and silently disables v2's
+			// default-store rule for every step that didn't explicitly set it.
+			expect(n.set_var).toBeUndefined();
 			expect(n.contentType).toBe("");
 		});
 	});

package/dist/BlokError.d.ts

@@ -0,0 +1,196 @@
+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 declare const ErrorCategory: {
+    readonly VALIDATION: "VALIDATION";
+    readonly CONFIGURATION: "CONFIGURATION";
+    readonly DEPENDENCY: "DEPENDENCY";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly PERMISSION: "PERMISSION";
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly CANCELLED: "CANCELLED";
+    readonly INTERNAL: "INTERNAL";
+    readonly PROTOCOL: "PROTOCOL";
+    readonly DATA: "DATA";
+};
+export type ErrorCategory = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+/** How severe an error is. Default for thrown errors is `ERROR`. */
+export declare const ErrorSeverity: {
+    readonly INFO: "INFO";
+    readonly WARN: "WARN";
+    readonly ERROR: "ERROR";
+    readonly FATAL: "FATAL";
+};
+export type ErrorSeverity = (typeof ErrorSeverity)[keyof typeof ErrorSeverity];
+/**
+ * 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 declare const DEFAULT_HTTP_STATUS: Readonly<Record<ErrorCategory, number>>;
+/** Default retryable hint per error category. */
+export declare const DEFAULT_RETRYABLE: Readonly<Record<ErrorCategory, boolean>>;
+/**
+ * The plain-data shape of a Blok node error.
+ *
+ * 1:1 mirror of the proto `blok.runtime.v1.NodeError` message in JSON form.
+ * The runner-side gRPC codec converts between this shape and the proto type;
+ * this module has no gRPC dependency.
+ */
+export interface NodeErrorPayload {
+    /** Stable machine identifier — see `docs/error-codes.md`. */
+    code: string;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    /** Node name that produced this error (auto-filled by SDKs). */
+    node: string;
+    /** SDK identifier, e.g. "blok-python3" (auto-filled). */
+    sdk: string;
+    sdkVersion: string;
+    /** Runtime kind, e.g. "runtime.python3" (auto-filled). */
+    runtimeKind: string;
+    /** ISO 8601 timestamp of the error. */
+    at: string;
+    message: string;
+    description: string;
+    remediation: string;
+    docUrl: string;
+    /** Flattened cause chain — outermost cause first. */
+    causes: NodeErrorPayload[];
+    stack: string;
+    /** Bounded slice of resolved inputs/state at error time. */
+    contextSnapshot: unknown;
+    httpStatus: number;
+    retryable: boolean;
+    retryAfterMs: number;
+    /** Category-specific structured details (Zod issues, SQL state, etc.). */
+    details: unknown;
+}
+/**
+ * Constructor options for {@link BlokError}.
+ *
+ * `code`, `message`, and the implicit `category` (via the factory method) are
+ * the seven required fields that, combined with auto-filled origin, make every
+ * error self-describing.
+ */
+export interface BlokErrorOpts {
+    /** Stable machine identifier (e.g. "POSTGRES_CONNECT_TIMEOUT"). */
+    code: string;
+    /** One-sentence human summary. */
+    message: string;
+    /** Multi-paragraph context: what was tried, why it failed. */
+    description?: string;
+    /** Suggested next step for the developer. */
+    remediation?: string;
+    /** Optional link to documentation explaining this code. */
+    docUrl?: string;
+    /** Underlying cause — any Error or BlokError. */
+    cause?: Error | BlokError;
+    /** Override default retryable hint. */
+    retryable?: boolean;
+    /** Suggested wait time before retrying. */
+    retryAfterMs?: number;
+    /** Category-specific structured details. */
+    details?: unknown;
+    /** Bounded slice of inputs/state at error time. */
+    contextSnapshot?: unknown;
+    /** Override the default HTTP status for this category. */
+    httpStatus?: number;
+    /** Override the default severity (`ERROR`). */
+    severity?: ErrorSeverity;
+    /** Override the auto-filled node name. */
+    node?: string;
+    /** Override the auto-filled SDK name. */
+    sdk?: string;
+    /** Override the auto-filled SDK version. */
+    sdkVersion?: string;
+    /** Override the auto-filled runtime kind. */
+    runtimeKind?: string;
+}
+/**
+ * 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 {
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly errorCode: string;
+    readonly description: string;
+    readonly remediation: string;
+    readonly docUrl: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs: number;
+    readonly details: unknown;
+    readonly contextSnapshot: unknown;
+    readonly causes: ReadonlyArray<NodeErrorPayload>;
+    readonly at: Date;
+    readonly sdk: string;
+    readonly sdkVersion: string;
+    readonly runtimeKind: string;
+    readonly httpStatus: number;
+    readonly nodeName: string;
+    private constructor();
+    static validation(opts: BlokErrorOpts): BlokError;
+    static configuration(opts: BlokErrorOpts): BlokError;
+    static dependency(opts: BlokErrorOpts): BlokError;
+    static timeout(opts: BlokErrorOpts): BlokError;
+    static permission(opts: BlokErrorOpts): BlokError;
+    static rateLimit(opts: BlokErrorOpts): BlokError;
+    static notFound(opts: BlokErrorOpts): BlokError;
+    static conflict(opts: BlokErrorOpts): BlokError;
+    static cancelled(opts: BlokErrorOpts): BlokError;
+    static internal(opts: BlokErrorOpts): BlokError;
+    static protocol(opts: BlokErrorOpts): BlokError;
+    static data(opts: BlokErrorOpts): BlokError;
+    /**
+     * 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: unknown, ctx?: {
+        node?: string;
+        sdk?: string;
+        sdkVersion?: string;
+        runtimeKind?: string;
+    }): BlokError;
+    /**
+     * 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: NodeErrorPayload): BlokError;
+    /** Serialize to the canonical {@link NodeErrorPayload} shape (matches proto wire format). */
+    toJSON(): NodeErrorPayload;
+    private static flattenCauses;
+    private static causeToPayload;
+}

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,50 @@ 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;
     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

@@ -8,7 +8,37 @@ 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;
     async process(ctx, step) {
         let response = {
             success: true,
@@ -49,11 +79,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];
     }

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"}

package/dist/types/Context.d.ts

@@ -6,20 +6,94 @@ import type FunctionContext from "./FunctionContext";
 import type LoggerContext from "./LoggerContext";
 import type RequestContext from "./RequestContext";
 import type ResponseContext from "./ResponseContext";
+import type StateContext from "./StateContext";
 import type VarsContext from "./VarsContext";
+/**
+ * The runtime context for a single workflow execution. One Context object
+ * is created per run and threaded through every step.
+ *
+ * **The two-tier read model:**
+ *
+ * - `ctx.prev` — the previous step's full result envelope ({ data, success,
+ *   error }). Overwritten on every step. Use for adjacent-step access.
+ *   Aliased by `ctx.response` for back-compat with v1.
+ *
+ * - `ctx.state[stepId]` — each step's `result.data` is automatically
+ *   persisted here under the step's `id` (or its `as` override). Use
+ *   for any-distance access. Aliased by `ctx.vars` for back-compat.
+ *
+ * **Side-channel publication:**
+ *
+ * - `ctx.publish(name, value)` — explicitly publish a value into state
+ *   from inside a node. Logged in Studio's trace tab. Use sparingly —
+ *   most nodes should just `return` their output and let the runner
+ *   persist it.
+ *
+ * **Request envelope aliases:**
+ *
+ * - `ctx.req` — alias for `ctx.request`. Read query, body, params,
+ *   headers, etc. via either form.
+ */
 type Context = {
     id: string;
     workflow_name?: string;
     workflow_path?: string;
+    /**
+     * Request envelope. Body, query, params, headers, etc.
+     *
+     * Also accessible as `ctx.req` (alias).
+     */
     request: RequestContext;
+    /**
+     * Alias for `ctx.request` — same object, read-only getter. v2
+     * authoring uses `req`; v1 authoring used `request`. Both work.
+     */
+    readonly req?: RequestContext;
+    /**
+     * Previous step's full result envelope. **Overwritten every step.**
+     * Use for adjacent-step access only; for cross-step access use
+     * `ctx.state[stepId]`.
+     *
+     * Aliased by `ctx.response` for v1 back-compat.
+     */
     response: ResponseContext;
+    /**
+     * Alias for `ctx.response` — same object. v2 authoring uses `prev`;
+     * v1 authoring used `response.data`. Both work.
+     */
+    readonly prev?: ResponseContext;
     error: ErrorContext;
     logger: LoggerContext;
     config: ConfigContext;
     func?: FunctionContext;
+    /**
+     * Accumulated step outputs by step `id`. Filled automatically when
+     * a step completes (unless `ephemeral: true`).
+     *
+     * Aliased by `ctx.vars` for v1 back-compat — both fields point at
+     * the same underlying object.
+     *
+     * Always initialized to `{}` by `TriggerBase.createContext`. Marked
+     * optional only so legacy code paths that hand-construct a Context
+     * (some tests, internal utilities) keep type-checking; production
+     * runs always have `state` defined.
+     */
+    state?: StateContext;
+    /**
+     * Alias for `ctx.state` — same underlying object. v2 authoring
+     * uses `state`; v1 authoring used `vars`. Both work.
+     *
+     * @deprecated Prefer `ctx.state` (or `$.state.<id>` from inputs).
+     */
     vars?: VarsContext;
     env?: EnvContext;
     eventLogger: GlobalLogger | unknown;
+    /**
+     * Explicit side-channel publication. Writes to state under `name`
+     * and emits a Studio trace event. Use only when a node needs to
+     * publish something other than its return value (most nodes don't).
+     */
+    publish?: (name: string, value: unknown) => void;
     _PRIVATE_: unknown;
 };
 export default Context;

package/dist/types/StateContext.d.ts

@@ -0,0 +1,21 @@
+/**
+ * StateContext — accumulated step outputs for a single workflow run.
+ *
+ * Every step's `result.data` lands here under the step's `id` (or its
+ * `as` override) automatically. Steps marked `ephemeral: true` skip
+ * persistence; steps marked `spread: true` shallow-merge their result
+ * keys into state.
+ *
+ * Read via `ctx.state[stepId]` or `$.state[stepId]` from a workflow's
+ * `inputs`. Always initialized to `{}` at run start — never undefined.
+ *
+ * Aliased by `ctx.vars` for backward compatibility with v1 workflows.
+ *
+ * @example
+ *   ctx.state["fetch-users"]   // the data returned by the fetch-users step
+ *   ctx.state.user             // when a step has `as: "user"`
+ */
+type StateContext = {
+    [key: string]: unknown;
+};
+export default StateContext;

package/dist/types/StateContext.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StateContext.js.map

package/dist/types/StateContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateContext.js","sourceRoot":"","sources":["../../src/types/StateContext.ts"],"names":[],"mappings":""}

package/dist/types/VarsContext.d.ts

@@ -1,5 +1,18 @@
-import type ParamsDictionary from "./ParamsDictionary";
+/**
+ * VarsContext — accumulated step outputs for a single workflow run.
+ *
+ * **Legacy alias for {@link StateContext}.** The two types describe the
+ * same underlying object (`ctx.state` and `ctx.vars` are aliases). v2
+ * code should prefer `ctx.state` / `StateContext`.
+ *
+ * Values can be any JSON-serializable shape — a step's output is whatever
+ * its node returned. The strict `ParamsDictionary` shape from earlier
+ * versions of Blok was inaccurate; real workflows have always stored
+ * arbitrary objects, arrays, primitives, etc. here.
+ *
+ * @deprecated Prefer {@link StateContext}.
+ */
 type VarsContext = {
-    [key: string]: ParamsDictionary;
+    [key: string]: unknown;
 };
 export default VarsContext;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blokjs/shared",
-	"version": "0.2.1",
+	"version": "0.2.2",
 	"description": "Shared class, interfaces and types",
 	"type": "module",
 	"main": "dist/index.js",
@@ -11,10 +11,7 @@
 		"test": "vitest run",
 		"test:dev": "vitest"
 	},
-	"keywords": [
-		"api",
-		"blueprint"
-	],
+	"keywords": ["api", "blueprint"],
 	"author": "Deskree Inc",
 	"license": "MIT",
 	"devDependencies": {