@plitzi/sdk-server 0.33.2 → 0.34.0

package/dist/modules/actions/tasks/db.js

@@ -0,0 +1,59 @@
+import { renderTaskParams } from "./helpers.js";
+//#region src/modules/actions/tasks/db.ts
+var TEMPLATE = /\{\{/;
+var parseParams = (value) => {
+	if (Array.isArray(value)) return value;
+	if (typeof value !== "string" || value.trim() === "") return [];
+	try {
+		const parsed = JSON.parse(value);
+		return Array.isArray(parsed) ? parsed : [parsed];
+	} catch {
+		throw new Error("Query parameters are not a valid JSON array");
+	}
+};
+var dbTasks = [{
+	namespace: "db",
+	action: "query",
+	title: "Database Query",
+	description: "Runs a parameterized statement against a database this space declared as a credential",
+	rawParams: true,
+	params: {
+		credential: {
+			type: "text",
+			canBind: true,
+			defaultValue: "",
+			label: "Connection (credential)"
+		},
+		sql: {
+			type: "codemirror-text",
+			canBind: false,
+			defaultValue: "",
+			label: "SQL (no templates)"
+		},
+		params: {
+			type: "codemirror-json",
+			canBind: true,
+			defaultValue: "[]",
+			label: "Bound parameters"
+		}
+	},
+	run: async (raw, ctx) => {
+		if (!raw.credential) throw new Error("The query names no connection credential");
+		if (raw.sql.trim() === "") throw new Error("The query is empty");
+		if (TEMPLATE.test(raw.sql)) throw new Error("The statement must be a literal: put the value in `params` and use a placeholder");
+		const credential = await ctx.credential(raw.credential);
+		if (!credential) throw new Error(`Credential "${raw.credential}" is not available for this space`);
+		const { engine, dsn } = credential;
+		if (!engine || !dsn) throw new Error(`Credential "${raw.credential}" carries no engine and dsn`);
+		const driver = ctx.dbDrivers.find((item) => item.engine === engine);
+		if (!driver) throw new Error(`This server has no driver for "${engine}"`);
+		const rendered = await renderTaskParams({ params: raw.params }, ctx, raw.credential);
+		const rows = await driver.query(dsn, raw.sql, parseParams(rendered.params), ctx.signal);
+		return {
+			rows,
+			count: rows.length
+		};
+	}
+}];
+//#endregion
+export { dbTasks };

package/dist/modules/actions/tasks/db.test.d.ts

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

package/dist/modules/actions/tasks/flow.d.ts

@@ -0,0 +1,3 @@
+import { ActionTask } from '../types';
+export declare const flowTasks: ActionTask<Record<string, unknown>>[];
+export declare const streamTasks: ActionTask<Record<string, unknown>>[];

package/dist/modules/actions/tasks/flow.js

@@ -0,0 +1,109 @@
+import onAbort from "../../../helpers/onAbort.js";
+//#region src/modules/actions/tasks/flow.ts
+var MAX_DELAY_MS = 5e3;
+/**
+* Pauses the flow.
+*
+* Capped hard: a run holds a connection and a concurrency slot for its whole life, so an authored `delay` is a way
+* to spend both on nothing. Anything longer than this is a schedule, not a step.
+*/
+var delay = {
+	namespace: "flow",
+	action: "delay",
+	title: "Delay",
+	params: { milliseconds: {
+		type: "text",
+		canBind: true,
+		defaultValue: "1000",
+		label: "Milliseconds"
+	} },
+	run: async ({ milliseconds }, ctx) => {
+		const parsed = typeof milliseconds === "number" ? milliseconds : Number.parseInt(milliseconds, 10);
+		const waitMs = Math.min(Number.isNaN(parsed) || parsed < 0 ? 0 : parsed, MAX_DELAY_MS);
+		await new Promise((resolve) => {
+			const timer = setTimeout(resolve, waitMs);
+			onAbort(ctx.signal, () => {
+				clearTimeout(timer);
+				resolve();
+			});
+		});
+		return { waited: waitMs };
+	}
+};
+/** Ends the run as failed, on purpose. The message reaches the trace, never the caller. */
+var fail = {
+	namespace: "flow",
+	action: "fail",
+	title: "Fail",
+	params: { message: {
+		type: "text",
+		canBind: true,
+		defaultValue: "",
+		label: "Message"
+	} },
+	run: ({ message }) => {
+		throw new Error(message || "Action failed");
+	}
+};
+/**
+* Declares what the caller gets back — and IS the declaration.
+*
+* The flow scope is not the answer: it holds every node's raw result, including whatever a fetch happened to
+* return. This step is the one place that decides what leaves the server, and what it names is exactly what the
+* caller receives.
+*
+* There is no separate output contract on the document, deliberately. Declaring the shape before the steps exist
+* asks an author to know what a flow returns before writing it, and leaves two places to keep in step; the values
+* here are the contract, and the builder derives the field list from them for bindings.
+*
+* It must be the LAST step: the runner reads the last one that ran, so a step after it is work whose result
+* nobody asked for — the validator says so.
+*/
+var output = {
+	namespace: "flow",
+	action: "output",
+	title: "Output",
+	params: { values: {
+		type: "codemirror-json",
+		canBind: true,
+		defaultValue: "{}",
+		label: "Values"
+	} },
+	run: ({ values }) => {
+		if (typeof values !== "string") return values;
+		try {
+			return JSON.parse(values);
+		} catch {
+			throw new Error("Output values are not valid JSON");
+		}
+	}
+};
+/**
+* Pushes progress to a caller watching the run.
+*
+* A no-op when nobody negotiated a stream, and deliberately so: a flow is authored once and runs both ways, so a
+* step that reported progress must not fail on the request/response path just because nobody is listening.
+*/
+var emit = {
+	namespace: "stream",
+	action: "emit",
+	title: "Report Progress",
+	params: { chunk: {
+		type: "codemirror-text",
+		canBind: true,
+		defaultValue: "",
+		label: "Chunk"
+	} },
+	run: ({ chunk }, ctx) => {
+		ctx.emit(chunk);
+		return { emitted: true };
+	}
+};
+var flowTasks = [
+	delay,
+	fail,
+	output
+];
+var streamTasks = [emit];
+//#endregion
+export { flowTasks, streamTasks };

package/dist/modules/actions/tasks/helpers.d.ts

@@ -0,0 +1,16 @@
+import { ActionTaskContext } from '../types';
+/**
+ * Renders a task's own params, with its own credential in scope.
+ *
+ * This is the shape every task that talks to a third party takes — `http.request` today, `apiCall` and whatever
+ * else tomorrow — and it exists so each of them does not invent its own answer to the same question.
+ *
+ * The credential is resolved HERE, inside the task, and never enters the flow scope. That is the whole point:
+ * a secret in the run's scope is interpolable by every other node, including the one that returns values to the
+ * browser, and no amount of care in this task would stop that. What a flow can reach is what its tasks chose to
+ * hand back — a credential is not that.
+ *
+ * Tasks using this declare `rawParams: true`, because the runner must not have resolved the params first: a
+ * `{{credential.*}}` token would then have been spent against a scope that has no credential in it.
+ */
+export declare const renderTaskParams: <T extends Record<string, unknown>>(params: T, ctx: ActionTaskContext, credentialId?: string) => Promise<T>;

package/dist/modules/actions/tasks/helpers.js

@@ -0,0 +1,30 @@
+import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
+//#region src/modules/actions/tasks/helpers.ts
+/**
+* Renders a task's own params, with its own credential in scope.
+*
+* This is the shape every task that talks to a third party takes — `http.request` today, `apiCall` and whatever
+* else tomorrow — and it exists so each of them does not invent its own answer to the same question.
+*
+* The credential is resolved HERE, inside the task, and never enters the flow scope. That is the whole point:
+* a secret in the run's scope is interpolable by every other node, including the one that returns values to the
+* browser, and no amount of care in this task would stop that. What a flow can reach is what its tasks chose to
+* hand back — a credential is not that.
+*
+* Tasks using this declare `rawParams: true`, because the runner must not have resolved the params first: a
+* `{{credential.*}}` token would then have been spent against a scope that has no credential in it.
+*/
+var renderTaskParams = async (params, ctx, credentialId) => {
+	const credential = credentialId ? await ctx.credential(credentialId) : void 0;
+	if (credentialId && !credential) throw new Error(`Credential "${credentialId}" is not available for this space`);
+	const scope = {
+		...ctx.scope,
+		...credential ? { credential } : {}
+	};
+	return Object.entries(params).reduce((acum, [key, value]) => {
+		acum[key] = typeof value === "string" ? processTwig(value, scope, false, true) : value;
+		return acum;
+	}, {});
+};
+//#endregion
+export { renderTaskParams };

package/dist/modules/actions/tasks/http.d.ts

@@ -0,0 +1,2 @@
+import { ActionTask } from '../types';
+export declare const httpTasks: ActionTask<Record<string, unknown>>[];

package/dist/modules/actions/tasks/http.js

@@ -0,0 +1,111 @@
+import { assertOutboundAllowed } from "../../../helpers/outboundGuard.js";
+import { renderTaskParams } from "./helpers.js";
+//#region src/modules/actions/tasks/http.ts
+var BODYLESS = ["GET", "HEAD"];
+var parseJsonParam = (value, label) => {
+	if (value === void 0 || value === "") return {};
+	if (typeof value === "object" && value !== null) return value;
+	if (typeof value !== "string") throw new Error(`${label} is not valid JSON`);
+	try {
+		const parsed = JSON.parse(value);
+		return parsed !== null && typeof parsed === "object" ? parsed : {};
+	} catch {
+		throw new Error(`${label} is not valid JSON`);
+	}
+};
+var httpTasks = [{
+	namespace: "http",
+	action: "request",
+	title: "HTTP Request",
+	rawParams: true,
+	params: {
+		credential: {
+			type: "text",
+			canBind: true,
+			defaultValue: "",
+			label: "Credential"
+		},
+		url: {
+			type: "text",
+			canBind: true,
+			defaultValue: "",
+			label: "URL"
+		},
+		method: {
+			type: "select",
+			defaultValue: "GET",
+			label: "Method",
+			options: [
+				{
+					label: "GET",
+					value: "GET"
+				},
+				{
+					label: "POST",
+					value: "POST"
+				},
+				{
+					label: "PUT",
+					value: "PUT"
+				},
+				{
+					label: "PATCH",
+					value: "PATCH"
+				},
+				{
+					label: "DELETE",
+					value: "DELETE"
+				}
+			]
+		},
+		headers: {
+			type: "codemirror-json",
+			canBind: true,
+			defaultValue: "{}",
+			label: "Headers"
+		},
+		body: {
+			type: "codemirror-json",
+			canBind: true,
+			defaultValue: "",
+			label: "Body",
+			when: (params) => params.method !== "GET"
+		}
+	},
+	run: async (raw, ctx) => {
+		const params = await renderTaskParams(raw, ctx, raw.credential || void 0);
+		const method = (params.method || "GET").toUpperCase();
+		let url;
+		try {
+			url = new URL(params.url);
+		} catch {
+			throw new Error("Request URL is not a valid absolute URL");
+		}
+		await assertOutboundAllowed(url);
+		const headers = Object.entries(parseJsonParam(params.headers, "Headers")).reduce((acum, [key, value]) => {
+			acum[key] = typeof value === "string" ? value : JSON.stringify(value);
+			return acum;
+		}, {});
+		const hasBody = !BODYLESS.includes(method) && params.body !== "";
+		const declaresContentType = Object.keys(headers).some((name) => name.toLowerCase() === "content-type");
+		if (hasBody && !declaresContentType) headers["Content-Type"] = "application/json";
+		const response = await ctx.fetch(url.toString(), {
+			method,
+			headers,
+			body: hasBody ? JSON.stringify(parseJsonParam(params.body, "Body")) : void 0,
+			signal: ctx.signal
+		});
+		const text = await response.text();
+		let data = text;
+		try {
+			data = JSON.parse(text);
+		} catch {}
+		return {
+			status: response.status,
+			ok: response.ok,
+			data
+		};
+	}
+}];
+//#endregion
+export { httpTasks };

package/dist/modules/actions/tasks/http.test.d.ts

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

package/dist/modules/actions/tasks/kv.d.ts

@@ -0,0 +1,2 @@
+import { ActionTask } from '../types';
+export declare const kvTasks: ActionTask<Record<string, unknown>>[];

package/dist/modules/actions/tasks/kv.js

@@ -0,0 +1,102 @@
+//#region src/modules/actions/tasks/kv.ts
+var toNumber = (value, fallback) => {
+	if (value === void 0 || value === "") return fallback;
+	const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : fallback;
+};
+var kvTasks = [
+	{
+		namespace: "kv",
+		action: "get",
+		title: "Read Value",
+		params: { key: {
+			type: "text",
+			canBind: true,
+			defaultValue: "",
+			label: "Key"
+		} },
+		run: async ({ key }, ctx) => ({ value: await ctx.kv.get(key) ?? null })
+	},
+	{
+		namespace: "kv",
+		action: "set",
+		title: "Write Value",
+		params: {
+			key: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Key"
+			},
+			value: {
+				type: "codemirror-text",
+				canBind: true,
+				defaultValue: "",
+				label: "Value"
+			},
+			ttlSeconds: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "TTL (seconds)"
+			}
+		},
+		run: async ({ key, value, ttlSeconds }, ctx) => {
+			const ttl = ttlSeconds === "" ? void 0 : toNumber(ttlSeconds, 0) || void 0;
+			await ctx.kv.set(key, value, ttl);
+			return {
+				key,
+				stored: true
+			};
+		}
+	},
+	{
+		namespace: "kv",
+		action: "increment",
+		title: "Increment Counter",
+		params: {
+			key: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "Key"
+			},
+			amount: {
+				type: "text",
+				canBind: true,
+				defaultValue: "1",
+				label: "Amount"
+			},
+			ttlSeconds: {
+				type: "text",
+				canBind: true,
+				defaultValue: "",
+				label: "TTL (seconds)"
+			}
+		},
+		run: async ({ key, amount, ttlSeconds }, ctx) => {
+			const ttl = ttlSeconds === "" ? void 0 : toNumber(ttlSeconds, 0) || void 0;
+			return { value: await ctx.kv.increment(key, toNumber(amount, 1), ttl) };
+		}
+	},
+	{
+		namespace: "kv",
+		action: "delete",
+		title: "Delete Value",
+		params: { key: {
+			type: "text",
+			canBind: true,
+			defaultValue: "",
+			label: "Key"
+		} },
+		run: async ({ key }, ctx) => {
+			await ctx.kv.delete(key);
+			return {
+				key,
+				deleted: true
+			};
+		}
+	}
+];
+//#endregion
+export { kvTasks };

package/dist/modules/actions/tasks/kv.test.d.ts

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

package/dist/modules/actions/tasks/registry.d.ts

@@ -0,0 +1,10 @@
+import { ActionTask, ActionTaskRegistry } from '../types';
+export declare const taskName: (task: Pick<ActionTask, "namespace" | "action">) => string;
+/**
+ * Builds the set of tasks this server can run.
+ *
+ * Validation is at BOOT and it throws, because every alternative is worse: a task registered under a malformed
+ * name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
+ * in that deployment does. Both are invisible until a run misbehaves in production.
+ */
+export declare const createTaskRegistry: (custom?: ActionTask<never>[], hasDbDrivers?: boolean) => ActionTaskRegistry;

package/dist/modules/actions/tasks/registry.js

@@ -0,0 +1,36 @@
+import { builtinTasks } from "./builtins.js";
+import { dbTasks } from "./db.js";
+//#region src/modules/actions/tasks/registry.ts
+var NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+var taskName = (task) => `${task.namespace}.${task.action}`;
+var reservedNamespaces = new Set([...builtinTasks, ...dbTasks].map((task) => task.namespace));
+/**
+* Builds the set of tasks this server can run.
+*
+* Validation is at BOOT and it throws, because every alternative is worse: a task registered under a malformed
+* name is unreachable from any document, and one shadowing a built-in silently changes what every existing action
+* in that deployment does. Both are invisible until a run misbehaves in production.
+*/
+var createTaskRegistry = (custom = [], hasDbDrivers = false) => {
+	const tasks = /* @__PURE__ */ new Map();
+	(hasDbDrivers ? [...builtinTasks, ...dbTasks] : builtinTasks).forEach((task) => tasks.set(taskName(task), {
+		...task,
+		name: taskName(task)
+	}));
+	custom.forEach((task) => {
+		if (!NAME_PATTERN.test(task.namespace) || !NAME_PATTERN.test(task.action)) throw new Error(`[Actions] Invalid task name "${taskName(task)}": expected camelCase namespace and action`);
+		if (reservedNamespaces.has(task.namespace)) throw new Error(`[Actions] Namespace "${task.namespace}" is reserved by a built-in task set`);
+		const name = taskName(task);
+		if (tasks.has(name)) throw new Error(`[Actions] Task "${name}" is registered twice`);
+		tasks.set(name, {
+			...task,
+			name
+		});
+	});
+	return {
+		get: (name) => tasks.get(name),
+		list: () => [...tasks.values()]
+	};
+};
+//#endregion
+export { createTaskRegistry, taskName };

package/dist/modules/actions/tasks/transform.d.ts

@@ -0,0 +1,2 @@
+import { ActionTask } from '../types';
+export declare const transformTasks: ActionTask<Record<string, unknown>>[];

package/dist/modules/actions/tasks/transform.js

@@ -0,0 +1,34 @@
+import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
+var transformTasks = [{
+	namespace: "transform",
+	action: "template",
+	title: "Template",
+	rawParams: true,
+	params: { template: {
+		type: "codemirror-text",
+		canBind: true,
+		defaultValue: "",
+		label: "Template"
+	} },
+	run: ({ template: source }, ctx) => ({ value: typeof source === "string" ? processTwig(source, { ...ctx.scope }) : "" })
+}, {
+	namespace: "transform",
+	action: "json",
+	title: "Parse JSON",
+	params: { value: {
+		type: "codemirror-text",
+		canBind: true,
+		defaultValue: "",
+		label: "Value"
+	} },
+	run: ({ value }) => {
+		if (typeof value !== "string") return { value };
+		try {
+			return { value: JSON.parse(value) };
+		} catch {
+			throw new Error("Value is not valid JSON");
+		}
+	}
+}];
+//#endregion
+export { transformTasks };

package/dist/modules/actions/transport/callHandler.d.ts

@@ -0,0 +1,24 @@
+import { RawResponse } from '../../../helpers/buildResponseHelpers';
+import { ActionsModule } from '../index';
+import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+export type ActionCallDeps = {
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    /** The raw response, for the streaming path alone: SSE cannot go through the one-shot helpers. */
+    raw: RawResponse;
+    config: SSRPageServerConfig;
+    module: ActionsModule;
+    /** The request's own signal: a caller that hangs up stops the run rather than paying for it to finish. */
+    signal: AbortSignal;
+    /** Who is asking, for the single-flight key and for cancellation ownership. */
+    callerId: string;
+    lineage: string[];
+};
+/**
+ * Handles an action-addressed call.
+ *
+ * The browser names an action and hands it inputs. Everything that decides whether the run may happen — the
+ * document, the access rule, the input contract, the lineage — is the runner's, so a deployment mounting its own
+ * trigger cannot end up with a weaker set of checks than this endpoint applies.
+ */
+export declare const handleActionCall: (deps: ActionCallDeps) => Promise<void>;