@zerodot/node-sdk 0.0.0-stage → 1.0.0

package/dist/index.mjs

@@ -0,0 +1,694 @@
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+// ../engine/src/expression.ts
+/**
+* Small safe expression evaluator. No eval, no new Function, no function calls.
+* Syntax: literals, paths (a.b, a["b"], a[0]), unary ! and -, arithmetic,
+* comparison, && || ??, the ternary operator, and `.includes(value)` on lists and text.
+*/
+var ExpressionError = class extends Error {
+	detail;
+	path;
+	constructor(detail, path) {
+		super(path ? `${detail} (at ${path})` : detail);
+		this.detail = detail;
+		this.path = path;
+		this.name = "ExpressionError";
+	}
+};
+const OPERATORS = [
+	"===",
+	"!==",
+	"==",
+	"!=",
+	"<=",
+	">=",
+	"&&",
+	"||",
+	"??",
+	"+",
+	"-",
+	"*",
+	"/",
+	"%",
+	"<",
+	">",
+	"!",
+	"?",
+	":",
+	".",
+	"[",
+	"]",
+	"(",
+	")"
+];
+function tokenize(source) {
+	const tokens = [];
+	let i = 0;
+	while (i < source.length) {
+		const ch = source[i];
+		if (/\s/.test(ch)) i++;
+		else if (/[0-9]/.test(ch)) {
+			const text = /^[0-9]+(\.[0-9]+)?/.exec(source.slice(i))?.[0] ?? ch;
+			tokens.push({
+				kind: "num",
+				value: Number(text)
+			});
+			i += text.length;
+		} else if (ch === "\"" || ch === "'") {
+			let out = "";
+			i++;
+			while (i < source.length && source[i] !== ch) {
+				if (source[i] === "\\" && i + 1 < source.length) i++;
+				out += source[i];
+				i++;
+			}
+			if (source[i] !== ch) throw new ExpressionError("Unterminated string");
+			i++;
+			tokens.push({
+				kind: "str",
+				value: out
+			});
+		} else if (/[A-Za-z_$]/.test(ch)) {
+			const text = /^[A-Za-z0-9_$]+/.exec(source.slice(i))?.[0] ?? ch;
+			tokens.push({
+				kind: "id",
+				value: text
+			});
+			i += text.length;
+		} else {
+			const op = OPERATORS.find((candidate) => source.startsWith(candidate, i));
+			if (!op) throw new ExpressionError(`Unexpected character "${ch}"`);
+			tokens.push({
+				kind: "op",
+				value: op
+			});
+			i += op.length;
+		}
+	}
+	tokens.push({ kind: "end" });
+	return tokens;
+}
+const BINARY_PRECEDENCE = {
+	"??": 1,
+	"||": 2,
+	"&&": 3,
+	"==": 4,
+	"!=": 4,
+	"===": 4,
+	"!==": 4,
+	"<": 5,
+	"<=": 5,
+	">": 5,
+	">=": 5,
+	"+": 6,
+	"-": 6,
+	"*": 7,
+	"/": 7,
+	"%": 7
+};
+const LITERALS = {
+	true: true,
+	false: false,
+	null: null,
+	undefined: void 0
+};
+var Parser = class {
+	tokens;
+	pos = 0;
+	constructor(tokens) {
+		this.tokens = tokens;
+	}
+	peek() {
+		return this.tokens[this.pos];
+	}
+	isOp(value) {
+		const token = this.peek();
+		return token.kind === "op" && token.value === value;
+	}
+	expectOp(value) {
+		if (!this.isOp(value)) throw new ExpressionError(`Expected "${value}"`);
+		this.pos++;
+	}
+	parse() {
+		const node = this.ternary();
+		if (this.peek().kind !== "end") throw new ExpressionError("Unexpected token after expression");
+		return node;
+	}
+	ternary() {
+		const test = this.binary(1);
+		if (!this.isOp("?")) return test;
+		this.pos++;
+		const yes = this.ternary();
+		this.expectOp(":");
+		return {
+			type: "cond",
+			test,
+			yes,
+			no: this.ternary()
+		};
+	}
+	binary(minPrecedence) {
+		let left = this.unary();
+		for (;;) {
+			const token = this.peek();
+			if (token.kind !== "op") break;
+			const precedence = BINARY_PRECEDENCE[token.value];
+			if (precedence === void 0 || precedence < minPrecedence) break;
+			this.pos++;
+			const right = this.binary(precedence + 1);
+			left = {
+				type: "binary",
+				op: token.value,
+				left,
+				right
+			};
+		}
+		return left;
+	}
+	unary() {
+		if (this.isOp("!") || this.isOp("-")) {
+			const op = this.peek().value;
+			this.pos++;
+			return {
+				type: "unary",
+				op,
+				arg: this.unary()
+			};
+		}
+		return this.postfix();
+	}
+	postfix() {
+		let node = this.primary();
+		for (;;) if (this.isOp(".")) {
+			this.pos++;
+			const token = this.peek();
+			if (token.kind !== "id") throw new ExpressionError("Expected a name after \".\"");
+			this.pos++;
+			node = {
+				type: "member",
+				object: node,
+				key: {
+					type: "lit",
+					value: token.value
+				},
+				label: token.value
+			};
+		} else if (this.isOp("[")) {
+			this.pos++;
+			const key = this.ternary();
+			this.expectOp("]");
+			node = {
+				type: "member",
+				object: node,
+				key,
+				label: key.type === "lit" ? String(key.value) : "[…]"
+			};
+		} else if (this.isOp("(")) {
+			if (node.type !== "member" || node.label !== "includes" || node.key.type !== "lit") throw new ExpressionError("Function calls are not allowed. Use a code node.");
+			this.pos++;
+			const arg = this.ternary();
+			this.expectOp(")");
+			node = {
+				type: "includes",
+				object: node.object,
+				arg
+			};
+		} else return node;
+	}
+	primary() {
+		const token = this.peek();
+		this.pos++;
+		if (token.kind === "num" || token.kind === "str") return {
+			type: "lit",
+			value: token.value
+		};
+		if (token.kind === "id") {
+			if (Object.hasOwn(LITERALS, token.value)) return {
+				type: "lit",
+				value: LITERALS[token.value]
+			};
+			return {
+				type: "id",
+				name: token.value
+			};
+		}
+		if (token.kind === "op" && token.value === "(") {
+			const inner = this.ternary();
+			this.expectOp(")");
+			return inner;
+		}
+		throw new ExpressionError("Unexpected end or token in expression");
+	}
+};
+/**
+* An object where a missing key is an error, not `undefined`. Used for `$vars`,
+* so a mistyped variable name fails the node and names the keys that are close.
+*/
+var StrictRecord = class {
+	label;
+	values;
+	constructor(label, values) {
+		this.label = label;
+		this.values = values;
+	}
+};
+function distance(a, b) {
+	const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		let previous = row[0] ?? 0;
+		row[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const current = row[j] ?? 0;
+			row[j] = Math.min((row[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+			previous = current;
+		}
+	}
+	return row[b.length] ?? 0;
+}
+function similarKeys(key, keys) {
+	const lower = key.toLowerCase();
+	return keys.map((k) => ({
+		k,
+		d: distance(lower, k.toLowerCase())
+	})).filter(({ k, d }) => d <= 2 || k.toLowerCase().includes(lower) || lower.includes(k.toLowerCase())).sort((x, y) => x.d - y.d).slice(0, 3).map(({ k }) => k);
+}
+const FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function readMember(object, key, path) {
+	if (object === null || object === void 0) throw new ExpressionError(`Cannot read "${String(key)}" of ${String(object)}`, path);
+	if (typeof key !== "string" && typeof key !== "number") throw new ExpressionError("A key must be a string or a number", path);
+	if (typeof key === "string" && FORBIDDEN_KEYS.has(key)) throw new ExpressionError(`Key "${key}" is not allowed`, path);
+	if (object instanceof StrictRecord) {
+		const name = String(key);
+		if (Object.hasOwn(object.values, name)) return object.values[name];
+		const similar = similarKeys(name, Object.keys(object.values));
+		const hint = similar.length > 0 ? ` Did you mean: ${similar.join(", ")}?` : "";
+		throw new ExpressionError(`${object.label} "${name}" does not exist.${hint}`, path);
+	}
+	if (Array.isArray(object)) {
+		if (key === "length") return object.length;
+		return typeof key === "number" ? object[key] : void 0;
+	}
+	if (typeof object === "string") {
+		if (key === "length") return object.length;
+		return;
+	}
+	if (typeof object === "object") return Object.hasOwn(object, key) ? object[key] : void 0;
+}
+function numeric(value, op) {
+	if (typeof value !== "number") throw new ExpressionError(`Operator "${op}" needs numbers`);
+	return value;
+}
+function evaluate(node, scope, path) {
+	switch (node.type) {
+		case "lit": return node.value;
+		case "id": return Object.hasOwn(scope, node.name) ? scope[node.name] : void 0;
+		case "member": return readMember(evaluate(node.object, scope, path), evaluate(node.key, scope, path), `${path}.${node.label}`.replace(/^\./, ""));
+		case "includes": {
+			const object = evaluate(node.object, scope, path);
+			const arg = evaluate(node.arg, scope, path);
+			if (Array.isArray(object)) return object.includes(arg);
+			if (typeof object === "string") return typeof arg === "string" && object.includes(arg);
+			throw new ExpressionError("\"includes\" needs a list or text", path);
+		}
+		case "unary": {
+			const value = evaluate(node.arg, scope, path);
+			return node.op === "!" ? !value : -numeric(value, "-");
+		}
+		case "cond": return evaluate(node.test, scope, path) ? evaluate(node.yes, scope, path) : evaluate(node.no, scope, path);
+		case "binary": {
+			if (node.op === "&&") {
+				const left = evaluate(node.left, scope, path);
+				return left ? evaluate(node.right, scope, path) : left;
+			}
+			if (node.op === "||") {
+				const left = evaluate(node.left, scope, path);
+				return left ? left : evaluate(node.right, scope, path);
+			}
+			if (node.op === "??") return evaluate(node.left, scope, path) ?? evaluate(node.right, scope, path);
+			const left = evaluate(node.left, scope, path);
+			const right = evaluate(node.right, scope, path);
+			switch (node.op) {
+				case "==":
+				case "===": return left === right;
+				case "!=":
+				case "!==": return left !== right;
+				case "<": return left < right;
+				case "<=": return left <= right;
+				case ">": return left > right;
+				case ">=": return left >= right;
+				case "+":
+					if (typeof left === "string" || typeof right === "string") return `${stringify(left)}${stringify(right)}`;
+					return numeric(left, "+") + numeric(right, "+");
+				case "-": return numeric(left, "-") - numeric(right, "-");
+				case "*": return numeric(left, "*") * numeric(right, "*");
+				case "/": return numeric(left, "/") / numeric(right, "/");
+				case "%": return numeric(left, "%") % numeric(right, "%");
+				default: throw new ExpressionError(`Unknown operator "${node.op}"`);
+			}
+		}
+	}
+}
+function stringify(value) {
+	if (typeof value === "string") return value;
+	if (value === void 0) return "";
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+}
+function evaluateExpression(source, scope) {
+	return evaluate(new Parser(tokenize(source)).parse(), scope, "");
+}
+function splitTemplate(input) {
+	const segments = [];
+	let rest = input;
+	while (rest.length > 0) {
+		const start = rest.indexOf("{{");
+		if (start === -1) {
+			segments.push({ text: rest });
+			break;
+		}
+		const end = rest.indexOf("}}", start + 2);
+		if (end === -1) throw new ExpressionError("Missing \"}}\"");
+		if (start > 0) segments.push({ text: rest.slice(0, start) });
+		segments.push({ expression: rest.slice(start + 2, end).trim() });
+		rest = rest.slice(end + 2);
+	}
+	return segments;
+}
+/** A string with one `` and nothing else keeps the value type. Otherwise the result is text. */
+function resolveTemplate(input, scope) {
+	if (!input.includes("{{")) return input;
+	const segments = splitTemplate(input);
+	const only = segments.length === 1 ? segments[0] : void 0;
+	if (only && "expression" in only) return evaluateExpression(only.expression, scope);
+	return segments.map((s) => "text" in s ? s.text : stringify(evaluateExpression(s.expression, scope))).join("");
+}
+// ../engine/src/graph.ts
+const retrySchema = z.object({
+	max: z.number().int().min(1).max(10),
+	backoffMs: z.number().int().min(0).max(6e4).default(1e3)
+});
+const graphNodeSchema = z.object({
+	id: z.string().min(1),
+	type: z.string().min(1),
+	name: z.string().min(1),
+	position: z.object({
+		x: z.number(),
+		y: z.number()
+	}),
+	config: z.record(z.string(), z.unknown()).default({}),
+	credentialId: z.string().nullable().default(null),
+	/**
+	* An expression that gives the id or the name of the credential at run time. When set, it is
+	* used instead of `credentialId`.
+	*/
+	credentialExpression: z.string().min(1).optional(),
+	/** Sample output. Test runs use it and skip the node. */
+	pinned: z.object({
+		port: z.string(),
+		data: z.unknown()
+	}).nullable().default(null),
+	/** A deactivated node passes its input through and does not run. */
+	disabled: z.boolean().optional(),
+	retry: retrySchema.optional(),
+	onError: z.enum(["fail", "continue"]).default("fail"),
+	/** If the node returns nothing or an empty list, it outputs an empty object instead. */
+	alwaysOutputData: z.boolean().optional(),
+	/** If the input is a list, the node runs once with the first item only. */
+	executeOnce: z.boolean().optional(),
+	/** A note for people. Not used at run time. */
+	notes: z.string().optional(),
+	/** Show the note under the node on the canvas. */
+	notesInFlow: z.boolean().optional()
+});
+const graphEdgeSchema = z.object({
+	id: z.string().min(1),
+	from: z.string().min(1),
+	fromPort: z.string().min(1),
+	to: z.string().min(1),
+	toPort: z.string().min(1)
+});
+const graphSchema = z.object({
+	schema: z.literal(1),
+	nodes: z.array(graphNodeSchema),
+	edges: z.array(graphEdgeSchema)
+});
+// ../engine/src/node.ts
+const FORM_FIELD_TYPES = [
+	"text",
+	"number",
+	"email",
+	"textarea",
+	"dropdown",
+	"checkbox",
+	"radio",
+	"password",
+	"date"
+];
+/** The most items one poll may return. A poll that returns more fails and the cursor stays. */
+const POLL_MAX_ITEMS = 1e3;
+function defineNode(definition) {
+	return definition;
+}
+graphSchema.extend({
+	name: z.string().trim().min(1).max(120).optional(),
+	variables: z.array(z.string()).optional()
+});
+z.object({
+	code: z.string().min(1).max(2e5),
+	/** Names the code can read, for example `$input` and `$vars`. Plain JSON values only. */
+	scope: z.record(z.string(), z.unknown()),
+	timeoutMs: z.number().int().min(1).max(6e4),
+	maxOutputBytes: z.number().int().min(1).optional()
+});
+// ../engine/src/tables.ts
+const COLUMN_TYPES = [
+	"string",
+	"number",
+	"boolean",
+	"date",
+	"json"
+];
+const MAX_QUERY_ROWS = 1e3;
+const COLUMN_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Every row has these. A column cannot use these keys. */
+const SYSTEM_FIELDS = [
+	"id",
+	"createdAt",
+	"updatedAt"
+];
+const columnKeySchema = z.string().max(64).regex(COLUMN_KEY_PATTERN, "Use letters, digits, and _. Do not start with a digit.").refine((key) => !SYSTEM_FIELDS.includes(key), { message: "id, createdAt, and updatedAt are reserved" });
+const columnSchema = z.object({
+	key: columnKeySchema,
+	type: z.enum(COLUMN_TYPES),
+	required: z.boolean().default(false),
+	unique: z.boolean().default(false),
+	default: z.unknown().optional()
+}).superRefine((column, ctx) => {
+	if (column.unique && column.type === "json") ctx.addIssue({
+		code: "custom",
+		message: "A json column cannot be unique",
+		path: ["unique"]
+	});
+	if (column.default !== void 0 && column.default !== null) {
+		const checked = checkValue(column.type, column.default);
+		if (!checked.ok) ctx.addIssue({
+			code: "custom",
+			message: checked.message,
+			path: ["default"]
+		});
+	}
+	if (column.unique && column.default !== void 0 && column.default !== null) ctx.addIssue({
+		code: "custom",
+		message: "A unique column cannot have a default",
+		path: ["default"]
+	});
+});
+z.array(columnSchema).max(20, `A table can have 20 columns`).superRefine((columns, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, column] of columns.entries()) {
+		if (seen.has(column.key)) ctx.addIssue({
+			code: "custom",
+			message: `Column "${column.key}" is listed twice`,
+			path: [index, "key"]
+		});
+		seen.add(column.key);
+	}
+});
+z.string().trim().min(1).max(80);
+function isJson(value, depth = 0) {
+	if (depth > 64) return false;
+	if (value === null) return true;
+	switch (typeof value) {
+		case "string":
+		case "boolean": return true;
+		case "number": return Number.isFinite(value);
+		case "object": return Array.isArray(value) ? value.every((item) => isJson(item, depth + 1)) : Object.values(value).every((item) => isJson(item, depth + 1));
+		default: return false;
+	}
+}
+/** Checks one non-null value against a column type. A date is stored as an ISO text in UTC. */
+function checkValue(type, value) {
+	switch (type) {
+		case "string": return typeof value === "string" ? {
+			ok: true,
+			value
+		} : {
+			ok: false,
+			message: "must be a string"
+		};
+		case "number": return typeof value === "number" && Number.isFinite(value) ? {
+			ok: true,
+			value
+		} : {
+			ok: false,
+			message: "must be a number"
+		};
+		case "boolean": return typeof value === "boolean" ? {
+			ok: true,
+			value
+		} : {
+			ok: false,
+			message: "must be true or false"
+		};
+		case "date": {
+			if (typeof value !== "string" && !(value instanceof Date) && typeof value !== "number") return {
+				ok: false,
+				message: "must be a date"
+			};
+			const time = new Date(value).getTime();
+			if (Number.isNaN(time)) return {
+				ok: false,
+				message: "must be a date"
+			};
+			return {
+				ok: true,
+				value: new Date(time).toISOString()
+			};
+		}
+		case "json": return isJson(value) ? {
+			ok: true,
+			value
+		} : {
+			ok: false,
+			message: "must be JSON"
+		};
+	}
+}
+const conditionSchema = z.object({
+	field: z.string().min(1).max(64),
+	op: z.enum([
+		"eq",
+		"neq",
+		"gt",
+		"gte",
+		"lt",
+		"lte",
+		"in",
+		"contains",
+		"isNull"
+	]),
+	value: z.unknown().optional()
+});
+/** A condition, or `{ and: [...] }`, or `{ or: [...] }`. No raw SQL. */
+const filterSchema = z.lazy(() => z.union([
+	z.object({ and: z.array(filterSchema).min(1).max(20) }),
+	z.object({ or: z.array(filterSchema).min(1).max(20) }),
+	conditionSchema
+]));
+const sortSchema = z.array(z.object({
+	field: z.string().min(1).max(64),
+	direction: z.enum(["asc", "desc"]).default("asc")
+})).max(3);
+z.object({
+	filter: filterSchema.optional(),
+	sort: sortSchema.optional(),
+	limit: z.number().int().min(1).max(MAX_QUERY_ROWS).default(100),
+	cursor: z.string().max(512).nullish()
+});
+// ../engine/src/variables.ts
+const VARIABLE_TYPES = [
+	"string",
+	"number",
+	"boolean",
+	"json"
+];
+const VARIABLE_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Returns an error message, or null when the value fits the type and the size limit. */
+function checkVariableValue(type, value) {
+	if (!(type === "string" && typeof value === "string" || type === "number" && typeof value === "number" && Number.isFinite(value) || type === "boolean" && typeof value === "boolean" || type === "json" && value !== void 0)) return `The value must be of type ${type}`;
+	return new TextEncoder().encode(JSON.stringify(value)).length > 65536 ? "The value is larger than 64 KB" : null;
+}
+z.object({
+	key: z.string().max(64).regex(VARIABLE_KEY_PATTERN, "Use letters, digits, and _. Do not start with a digit."),
+	type: z.enum(VARIABLE_TYPES),
+	value: z.unknown(),
+	description: z.string().max(500).default("")
+}).superRefine((input, ctx) => {
+	const problem = checkVariableValue(input.type, input.value);
+	if (problem) ctx.addIssue({
+		code: "custom",
+		message: problem,
+		path: ["value"]
+	});
+});
+// src/icon.ts
+const TYPES = {
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".webp": "image/webp"
+};
+/**
+* Reads an icon file of a package and returns it as a data URL, for `iconUrl` of a node or a
+* credential type. `from` is `import.meta.url` of the file that calls it, and `path` is relative
+* to that file, for example `fileIcon(import.meta.url, "./redis.svg")`. The icon file must be in
+* the `files` of the package.
+*/
+function fileIcon(from, path) {
+	const type = TYPES[extname(path).toLowerCase()];
+	if (!type) throw new Error(`Icon "${path}" must be .svg, .png, or .webp`);
+	const file = fileURLToPath(new URL(path, from));
+	return `data:${type};base64,${readFileSync(file).toString("base64")}`;
+}
+// src/version.ts
+/**
+* Version of the node contract (the shape of `NodeDefinition` and what a node can use).
+* A minor version only adds. A major version can break a node package.
+*/
+const SDK_VERSION = "1.0.0";
+function parse(text) {
+	const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(text.trim());
+	if (!match) return null;
+	return [
+		Number(match[1]),
+		Number(match[2] ?? 0),
+		Number(match[3] ?? 0)
+	];
+}
+const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+/**
+* True when `version` fits `range`. A range is a caret range (`^1.4`, `^1.4.2`) or one exact
+* version (`1.4.2`). A caret range allows the same major version, from the given version up.
+* For major 0 it allows the same minor version only, as npm does.
+*/
+function satisfiesSdk(range, version = SDK_VERSION) {
+	const actual = parse(version);
+	if (!actual) return false;
+	const text = range.trim();
+	if (text.startsWith("^")) {
+		const floor = parse(text.slice(1));
+		if (!floor) return false;
+		if (compare(actual, floor) < 0) return false;
+		if (actual[0] !== floor[0]) return false;
+		return floor[0] !== 0 || actual[1] === floor[1];
+	}
+	const exact = parse(text);
+	return exact !== null && compare(actual, exact) === 0;
+}
+export { FORM_FIELD_TYPES, POLL_MAX_ITEMS, SDK_VERSION, defineNode, fileIcon, resolveTemplate, satisfiesSdk };