@hatua/sdk 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,31 @@
 # @hatua/sdk
 
-This version reserves the package name and contains no code.
+The Hatua SDK for Node backends and workflow runners: the contract plus the
+shared expression evaluator.
 
-Install `0.1.0` or later.
+A Host that runs Workflow Definitions written in `@hatua/react` needs to
+parse and validate the same YAML, resolve the same `{{ … }}` Expressions
+against a Run Context, and load Manifests the same way the designer does. This
+package is that half of the contract, published so a runner never has to
+reimplement the expression language against its own reading of the format —
+a runner that evaluates an Expression differently from the builder produces a
+workflow that looks correct in the editor and does the wrong thing in
+production.
+
+`@hatua/sdk` has no UI and no dependency on React. `@hatua/react` is the
+designer a Host embeds in a browser; this package is what runs on the backend
+that stores and executes what the designer produces.
+
+## Install
+
+```sh
+npm install @hatua/sdk
+```
+
+## The other `@hatua/*` packages
+
+`@hatua/document`, `@hatua/expressions`, `@hatua/layout`, `@hatua/log`,
+`@hatua/model`, `@hatua/schema` and `@hatua/services` are also on npm, but
+only because `@hatua/react`'s build treats them as externals rather than
+bundling them. They are implementation details, not a supported API —
+nobody installs `@hatua/model` directly and expects a contract.

package/dist/expression.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The Hatua SDK for Node backends and workflow runners.
+ *
+ * This exists mainly so no Host has to reimplement the expression language. A
+ * runner that evaluates `{{ … }}` differently from the builder produces the
+ * worst possible failure: a workflow that looks correct in the editor and does
+ * the wrong thing in production. One evaluator, shared, removes that.
+ *
+ * It re-exports the contract rather than duplicating it, so a runner validates
+ * with exactly the code the builder validated with — and the same is now true
+ * of evaluation: `@hatua/expressions` is the one implementation, and
+ * `hatua.dev/go/expressions` is its Go counterpart, kept honest by
+ * conformance/expression/.
+ */
+export { type CheckContext, coreFunctions, type Diagnostic, type DiagnosticCode, type EvaluationContext, ExpressionError, type FunctionImpl, type FunctionRegistry, hostFunctions, isReference, mergeRegistries, type OnMissing, parseTemplate, resolve, resolveAll, type ScopeEntry, type Severity, type Slot, sourceReference, type TypeNode, type Value, type ValueType, validate, } from '@hatua/expressions';
+export { type Board, type BoardId, boardScope, boards, callSlots, cyclicBlocks, findStep, REPEAT_VERB, repeatSlot, returnSlots, SET_VAR_VERB, type StepRef, scopeFor, setVarSlot, slotsFor, stepKey, upstreamOf, variableOn, variableSlot, variableType, varsOn, walkDocument, walkSteps, whenSlot, } from '@hatua/model';
+export * from '@hatua/schema';
+export { loadDefinition, loadExecution, loadManifests, loadRunContext } from './load';

package/dist/index.js

@@ -0,0 +1,22 @@
+import { ExpressionError as e, coreFunctions as t, hostFunctions as n, isReference as r, mergeRegistries as i, parseTemplate as a, resolve as o, resolveAll as s, sourceReference as c, validate as l } from "@hatua/expressions";
+import { REPEAT_VERB as u, SET_VAR_VERB as d, boardScope as f, boards as p, callSlots as m, cyclicBlocks as h, findStep as g, repeatSlot as _, returnSlots as v, scopeFor as y, setVarSlot as b, slotsFor as x, stepKey as S, upstreamOf as C, variableOn as w, variableSlot as T, variableType as E, varsOn as D, walkDocument as O, walkSteps as k, whenSlot as A } from "@hatua/model";
+import { componentManifest as j, runContextManifest as M, workflowDefinition as N, workflowExecution as P } from "@hatua/schema";
+import { parse as F } from "yaml";
+export * from "@hatua/schema";
+//#region src/load.ts
+function I(e, t, n) {
+	let r = t.safeParse(F(e));
+	if (!r.success || r.data === void 0) {
+		let e = r.error?.issues[0], t = e?.path.length ? ` at ${e.path.join(".")}` : "";
+		throw Error(`Not a valid ${n}${t}: ${e?.message ?? "unknown error"}`);
+	}
+	return r.data;
+}
+var L = (e) => I(e, N, "Workflow Definition"), R = (e) => I(e, P, "Workflow Execution");
+function z(e) {
+	let t = I(e, j, "Component Manifest");
+	return "components" in t ? t.components : [t];
+}
+var B = (e) => I(e, M, "Run Context Manifest");
+//#endregion
+export { e as ExpressionError, u as REPEAT_VERB, d as SET_VAR_VERB, f as boardScope, p as boards, m as callSlots, t as coreFunctions, h as cyclicBlocks, g as findStep, n as hostFunctions, r as isReference, L as loadDefinition, R as loadExecution, z as loadManifests, B as loadRunContext, i as mergeRegistries, a as parseTemplate, _ as repeatSlot, o as resolve, s as resolveAll, v as returnSlots, y as scopeFor, b as setVarSlot, x as slotsFor, c as sourceReference, S as stepKey, C as upstreamOf, l as validate, w as variableOn, T as variableSlot, E as variableType, D as varsOn, O as walkDocument, k as walkSteps, A as whenSlot };

package/dist/load.d.ts

@@ -0,0 +1,22 @@
+import { Manifest, RunContextManifest, WorkflowDefinition, WorkflowExecution } from '@hatua/schema';
+export declare const loadDefinition: (yaml: string) => WorkflowDefinition;
+export declare const loadExecution: (yaml: string) => WorkflowExecution;
+/**
+ * Accepts a single manifest or a `components:` catalogue, always returning a
+ * FLAT list. The return type is deliberately `Manifest[]` rather than the
+ * parse-time union: leaving the catalogue variant in the type forces every
+ * consumer to narrow, and a consumer that narrows by dropping — rather than
+ * flattening — silently loses every component in the catalogue.
+ */
+export declare function loadManifests(yaml: string): Manifest[];
+/**
+ * Parse a Run Context Manifest: the ambient values the Host supplies to every
+ * execution, addressed as `run.<k>`.
+ *
+ * No catalogue variant to unwrap, unlike `loadManifests`. There is exactly one
+ * Run Context per execution, so the file declares keys directly and a second
+ * declaration is a mistake rather than a longer list — which is also what keeps
+ * this return type a single object instead of an array nobody would know how to
+ * merge.
+ */
+export declare const loadRunContext: (yaml: string) => RunContextManifest;

package/package.json

@@ -1,17 +1,37 @@
 {
   "name": "@hatua/sdk",
-  "version": "0.0.0",
-  "description": "Placeholder reserving the name. Nothing is published here; see 0.1.0 and later.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Hatua SDK for Node backends and workflow runners — the contract plus the shared expression evaluator",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pedromvgomes/hatua.git",
     "directory": "source/sdk/js"
   },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "yaml": "^2.8.1",
+    "@hatua/model": "0.1.0",
+    "@hatua/expressions": "0.1.0",
+    "@hatua/schema": "0.1.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reporter=lcovonly"
+  }
 }