@protobase/server 0.68.4 → 0.68.6

package/dist/workflows/hooks/hook-runs.js

@@ -0,0 +1,32 @@
+import { startWorkflow } from "../start-workflow.js";
+import { sql } from "kysely";
+//#region src/workflows/hooks/hook-runs.ts
+const stillLive = async (trx, schema, target) => {
+	const { rows } = await sql`select 1 from ${sql.id(schema, "triggers")} t
+    join ${sql.id(schema, "workflows")} w on w.id = t.workflow_id and w.enabled_version = t.version
+    where t.id = ${target.trigger_id} and t.version = ${target.version} and t.status in ('active', 'failing') for share`.execute(trx);
+	return rows.length > 0;
+};
+/**
+* Starts a run per item of a call, in one transaction: only while the trigger the call found still runs on the enabled
+* version, the version and tenant from the trigger row, never from the call, each item's key once per workflow. The
+* first run takes `firstId`, under which the call's large body was kept. The ids of the runs, a run already started
+* for a key included, or `undefined` when the workflow was turned off, changed or deleted since the call found it.
+*/
+const startHookRuns = (db, schema, target, items, firstId) => db.transaction().execute(async (trx) => {
+	if (!await stillLive(trx, schema, target)) return;
+	const ids = [];
+	for (const [index, item] of items.entries()) ids.push(await startWorkflow(trx, {
+		workflow: target.workflow_id,
+		version: target.version,
+		input: item.data,
+		...target.tenant_id !== null && { tenant: target.tenant_id },
+		startedBy: `trigger:${target.trigger_id}`,
+		...item.key !== void 0 && { key: item.key },
+		schema,
+		...index === 0 && { id: firstId }
+	}));
+	return ids;
+});
+//#endregion
+export { startHookRuns };

package/dist/workflows/hooks/hook-secrets.js

@@ -0,0 +1,42 @@
+import { badRequest } from "../../problem.js";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+//#region src/workflows/hooks/hook-secrets.ts
+const modes = [
+	"standard_webhooks",
+	"hmac",
+	"bearer"
+];
+/** The mode a webhook trigger's input names, `standard_webhooks` by default; `undefined` for one the route does not know. */
+const hookMode = (input) => {
+	const auth = input.auth;
+	if (auth === void 0) return "standard_webhooks";
+	return typeof auth?.mode === "string" && modes.includes(auth.mode) ? auth.mode : void 0;
+};
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/**
+* Whether `secret` is one this mode can check signatures with: a Standard Webhooks secret is `whsec_` and 24+ bytes in
+* padded base64, as strict as the signature check decodes it.
+*/
+const usable = (mode, secret) => {
+	if (mode !== "standard_webhooks") return secret.length >= 32 && secret.length <= 512;
+	const match = /^whsec_((?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?)$/.exec(secret);
+	return Boolean(match) && Buffer.from(match[1], "base64").length >= 24 && secret.length <= 512;
+};
+/** The secret of a new URL: the caller's, checked for its mode, or a new one of 32 random bytes. */
+const hookSecret = (mode, given) => {
+	if (given === void 0) return mode === "standard_webhooks" ? `whsec_${randomBytes(32).toString("base64")}` : randomBytes(32).toString("base64url");
+	if (!usable(mode, given)) throw badRequest("invalid-secret", mode === "standard_webhooks" ? "A standard_webhooks secret is whsec_ followed by at least 24 bytes in base64" : "A secret is 32 to 512 characters");
+	return given;
+};
+/** Whether a stored secret is still one its mode can check with, as after the mode changed since the URL was issued. */
+const usableSecret = (mode, secret) => secret !== null && usable(mode, secret);
+/** A new URL key: 32 random bytes, which only the URL holds; the app keeps its SHA-256. */
+const hookKey = () => randomBytes(32).toString("base64url");
+/** Whether a bearer token's SHA-256 is the kept one, compared in constant time on two digests of one length. */
+const bearerMatches = (token, secretHash) => {
+	const given = createHash("sha256").update(token).digest();
+	const kept = Buffer.from(secretHash, "hex");
+	return kept.length === given.length && timingSafeEqual(given, kept);
+};
+//#endregion
+export { bearerMatches, hookKey, hookMode, hookSecret, sha256, usableSecret };

package/dist/workflows/hooks/hook-store.js

@@ -0,0 +1,35 @@
+import { hookKey, hookSecret, sha256 } from "./hook-secrets.js";
+import { sql } from "kysely";
+//#region src/workflows/hooks/hook-store.ts
+/**
+* Gives the workflow a new URL key and secret, replacing any it had, so its old URL stops at once: the key's SHA-256 is
+* kept, the secret itself only where checking a signature needs it (`standard_webhooks`, `hmac`), and its SHA-256
+* always. The key and secret come back once.
+*/
+const saveHook = async (db, schema, hook) => {
+	const key = hookKey();
+	const secret = hookSecret(hook.mode, hook.secret);
+	const kept = hook.mode === "bearer" ? null : secret;
+	await sql`insert into ${sql.id(schema, "hooks")} (workflow_id, key_hash, secret, secret_hash, tenant_id)
+    values (${hook.workflow}, ${sha256(key)}, ${kept}, ${sha256(secret)}, ${hook.tenant})
+    on conflict (workflow_id) do update set key_hash = excluded.key_hash, secret = excluded.secret, secret_hash = excluded.secret_hash, tenant_id = excluded.tenant_id, created_at = now()`.execute(db);
+	return {
+		key,
+		secret
+	};
+};
+/**
+* The webhook trigger a URL key opens, in one statement: the key's workflow in the same tenant, its enabled version's
+* trigger of a webhook type, running or failing. `undefined` for an unknown key, a workflow turned off, deleted or
+* moved to another trigger, and a trigger stopping or waiting for a sign-in, alike.
+*/
+const findHook = async (db, schema, key, webhookTypes) => {
+	const { rows } = await sql`select h.workflow_id, h.tenant_id, h.secret, h.secret_hash, t.id as trigger_id, t.version, t.type, t.input
+    from ${sql.id(schema, "hooks")} h
+    join ${sql.id(schema, "workflows")} w on w.id = h.workflow_id and w.tenant_id is not distinct from h.tenant_id
+    join ${sql.id(schema, "triggers")} t on t.workflow_id = w.id and t.version = w.enabled_version and t.status in ('active', 'failing') and t.type = any(${webhookTypes})
+    where h.key_hash = ${sha256(key)}`.execute(db);
+	return rows[0];
+};
+//#endregion
+export { findHook, saveHook };

package/dist/workflows/hooks/hooks-sql.js

@@ -0,0 +1,20 @@
+import { quoteIdent } from "../../changes/capture-sql.js";
+//#region src/workflows/hooks/hooks-sql.ts
+/**
+* The webhook URL each workflow has, at most one: the SHA-256 of its key, which only the URL holds, and its secret.
+* A `bearer` secret is kept as its SHA-256 alone; `standard_webhooks` and `hmac` keep the secret itself, which checking
+* a signature needs. No API resource reads it. A workflow's delete removes its row, so its URL stops at once.
+*/
+const hooksSql = (schema) => {
+	const s = quoteIdent(schema);
+	return `create table if not exists ${s}."hooks" (
+  "workflow_id" uuid primary key references ${s}."workflows" ("id") on delete cascade,
+  "key_hash" text not null unique,
+  "secret" text,
+  "secret_hash" text not null,
+  "tenant_id" text,
+  "created_at" timestamptz not null default now()
+)`;
+};
+//#endregion
+export { hooksSql };

package/dist/workflows/hooks/issue-body.js

@@ -0,0 +1,21 @@
+import { badRequest } from "../../problem.js";
+//#region src/workflows/hooks/issue-body.ts
+const invalidBody = () => badRequest("invalid-body", "Send nothing, or { \"secret\": \"<secret>\" } to keep a secret the sender gives");
+/** The issue request's body: nothing, or `{ secret }`; anything else, malformed JSON included, is a 400 `invalid-body`. */
+const parseIssueBody = (text) => {
+	if (text === "") return {};
+	let body;
+	try {
+		body = JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) throw invalidBody();
+		throw error;
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) throw invalidBody();
+	const { secret } = body;
+	if (secret === void 0) return {};
+	if (typeof secret !== "string") throw invalidBody();
+	return { secret };
+};
+//#endregion
+export { parseIssueBody };

package/dist/workflows/hooks/issue-route.js

@@ -0,0 +1,23 @@
+import { webhookParams } from "./hook-paths.js";
+import { parseIssueBody } from "./issue-body.js";
+import { issueWebhook } from "./issue-webhook.js";
+import { Hono } from "hono";
+//#region src/workflows/hooks/issue-route.ts
+/**
+* `POST <systemPath>/workflows/<id>/webhook` with an optional `{ secret }`: a new URL and secret for the workflow's
+* webhook trigger, answered once and never stored by any cache.
+*/
+const issueRoute = (input) => {
+	const app = new Hono();
+	app.post(`/:${webhookParams.workflow}/webhook`, async (c) => {
+		const body = parseIssueBody(await c.req.text());
+		const issued = await issueWebhook(input, c.get("session"), c.req.param(webhookParams.workflow), {
+			...body,
+			origin: new URL(c.req.url).origin
+		});
+		return c.json(issued, 200, { "Cache-Control": "no-store" });
+	});
+	return app;
+};
+//#endregion
+export { issueRoute };

package/dist/workflows/hooks/issue-webhook.js

@@ -0,0 +1,63 @@
+import { badRequest, notFound } from "../../problem.js";
+import { tenantScope } from "../../tenant.js";
+import { recordDecision, requestAccess, targetFilter } from "../../request-access.js";
+import { deletedRows } from "../../params.js";
+import { fetchRecord } from "../../records.js";
+import { fetchReadable } from "../../fetch-readable.js";
+import { hookMode } from "./hook-secrets.js";
+import { hookPath } from "./hook-paths.js";
+import { saveHook } from "./hook-store.js";
+//#region src/workflows/hooks/issue-webhook.ts
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const missing = () => notFound("No workflows with this key that you may change");
+const mayUpdate = async (trx, access, id, record) => {
+	const tenant = tenantScope(access.entry, access.session)?.tenantValue;
+	const key = [access.full.fields[access.full.primaryKey[0]]];
+	const filter = targetFilter(access, "update");
+	if (filter && !await fetchRecord(trx, access.entry, [id], tenant, {
+		filter,
+		fields: key
+	})) return false;
+	if (!access.resolved.recordChecks.includes("update")) return true;
+	const decision = await recordDecision(access, "update", record);
+	if (typeof decision === "boolean") return decision;
+	return Boolean(await fetchRecord(trx, access.entry, [id], tenant, {
+		filter: decision,
+		fields: key
+	}));
+};
+/**
+* Gives a workflow a new webhook URL and secret, as `POST .../workflows/<id>/webhook` and `new_webhook_url` do: only for
+* a caller who may change that workflow in their tenant, as its update access decides; 404 for anyone else, as for a
+* workflow that is not there. Its current definition must start from a webhook trigger that does not register its own
+* URL. The secret is the caller's, checked for the trigger's mode, or a new one. Both come back once; the old URL stops.
+*/
+const issueWebhook = async ({ deps, schema, webhooks, origin }, session, id, request) => {
+	if (!uuid.test(id)) throw missing();
+	const entry = deps().registry.find("workflows");
+	const access = await requestAccess(deps(), entry, session);
+	if (!access.resolved.operations.update) throw missing();
+	return deps().db.transaction().execute(async (trx) => {
+		const found = await fetchReadable(trx, access, [id], deletedRows(access.full, false), { lock: true });
+		if (!found || !await mayUpdate(trx, access, id, found.record)) throw missing();
+		const record = found.record;
+		const [type, input] = Object.entries(record.definition.trigger)[0];
+		const trigger = webhooks(type);
+		if (!trigger) throw badRequest("not-a-webhook", "This workflow does not start from a webhook trigger, such as app:webhook");
+		if (trigger.subscribe) throw badRequest("not-a-webhook", `${type} registers its own URL with its service as the workflow is turned on`);
+		const mode = hookMode(input);
+		if (!mode) throw badRequest("invalid-workflow", "The webhook trigger names an auth mode this app does not know");
+		const { key, secret } = await saveHook(trx, schema, {
+			workflow: id,
+			tenant: record.tenant_id ?? null,
+			mode,
+			...request.secret !== void 0 && { secret: request.secret }
+		});
+		return {
+			url: `${origin() ?? request.origin}${hookPath(deps().systemPath, key)}`,
+			secret
+		};
+	});
+};
+//#endregion
+export { issueWebhook };

package/dist/workflows/hooks/read-body.js

@@ -0,0 +1,32 @@
+//#region src/workflows/hooks/read-body.ts
+/**
+* The request's body, at most `limit` bytes, counted as they come off the stream whether or not the request declares
+* its length; `undefined` past the limit, having kept no more than `limit` bytes and cancelled the rest.
+*/
+const readBody = async (request, limit) => {
+	const declared = request.headers.get("content-length");
+	if (declared !== null && Number(declared) > limit) return void 0;
+	if (!request.body) return /* @__PURE__ */ new Uint8Array();
+	const reader = request.body.getReader();
+	const chunks = [];
+	let size = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value.length;
+		if (size > limit) {
+			await reader.cancel();
+			return;
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(size);
+	let at = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, at);
+		at += chunk.length;
+	}
+	return bytes;
+};
+//#endregion
+export { readBody };

package/dist/workflows/mcp/webhook-tools.d.ts

@@ -0,0 +1,9 @@
+import { Session } from "../../types.js";
+import "../../index.js";
+//#region src/workflows/mcp/webhook-tools.d.ts
+/** Issues a workflow's webhook URL as the caller; the server answers 404 for a workflow they may not change. */
+export type IssueWebhook = (session: Session, id: string, secret: string | undefined) => Promise<{
+  url: string;
+  secret: string;
+}>;
+//#endregion

package/dist/workflows/mcp/webhook-tools.js

@@ -0,0 +1,96 @@
+import { notFound, preconditionFailed } from "../../problem.js";
+import { defineTool } from "../../assistant/tools.js";
+import { refused } from "../../assistant/record-tool-args.js";
+import { recordName, updateApproval } from "../../assistant/write-prompts.js";
+import { approvalTexts, recordBefore } from "../../assistant/record-before.js";
+import { notApproved, onlyNote, outside } from "../../assistant/write-tool-limits.js";
+import { idOf, idParameter, textOf } from "./workflow-tool-args.js";
+//#region src/workflows/mcp/webhook-tools.ts
+/**
+* `enable_workflow` and `new_webhook_url`: turning a workflow's trigger on or off, and issuing its webhook URL, each as
+* the caller and after the user approves it in their client.
+*/
+const writes = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	openWorldHint: false
+};
+/** Turns a workflow's trigger on, on its current version, or off, once the user approves it. */
+const enableWorkflowTool = (input = {}) => defineTool({
+	name: "enable_workflow",
+	description: `Turns a workflow's trigger on (enabled: true) on version, which must be its current version as create_workflow, update_workflow or get_workflow gave it, or off (enabled: false), and returns JSON { id, enabled_version }. A workflow saved since that version is refused; read it again. While on, its trigger starts runs: a webhook trigger whose sender you give a URL once it is issued with new_webhook_url, one that registers its own URL with its service as soon as it did, a polling trigger at its next poll. A later save keeps it on, on the new version. The user approves it in their client first.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			id: idParameter,
+			enabled: {
+				type: "boolean",
+				description: "true to turn it on, false to turn it off."
+			},
+			version: {
+				type: "integer",
+				description: "With enabled: true, the version to turn on: the workflow's current version."
+			}
+		},
+		required: ["id", "enabled"]
+	},
+	annotations: writes,
+	run: async (args, context) => {
+		const id = idOf(args);
+		const version = args.version;
+		if (!id || typeof args.enabled !== "boolean" || args.enabled && !Number.isInteger(version)) return "Pass { \"id\": \"<id>\", \"enabled\": true, \"version\": <its current version> } or { \"id\": \"<id>\", \"enabled\": false }.";
+		const refusal = outside(input, "workflows");
+		if (refusal) return refusal;
+		const before = await recordBefore(context, "workflows", id, void 0);
+		if (typeof before === "string") return before;
+		if (!before) return refused(notFound("No workflows with this key that you may read"));
+		if (args.enabled && before.record.version !== version) return refused(preconditionFailed(`The workflow was saved since version ${version}; its current version is ${before.record.version}`));
+		const data = { enabled_version: args.enabled ? version : null };
+		const { text, described } = await approvalTexts(context, "workflows");
+		const answer = await context.approve(updateApproval(text, described, id, before.record, data));
+		if (answer !== "approved") return notApproved(answer);
+		return context.records.update("workflows", id, data, args.enabled ? { etag: before.etag } : {}).then(({ record }) => JSON.stringify({
+			id: record.id,
+			enabled_version: record.enabled_version
+		}), refused);
+	}
+});
+/** Issues a new webhook URL and secret for a workflow, once the user approves it. */
+const newWebhookUrlTool = (issue, input = {}) => defineTool({
+	name: "new_webhook_url",
+	description: `Issues a new URL and secret for a workflow that starts from a webhook trigger whose sender you give a URL (such as app:webhook), and returns JSON { url, secret }, shown this once: the app keeps no way to show them again, and the workflow's old URL stops. Pass secret to keep one the sender makes itself (a Standard Webhooks sender's whsec_ secret); without it the app makes one. The sender then POSTs to the url, signed as the trigger's auth mode says. A trigger that registers its own URL with its service is refused: turning the workflow on is all it needs. The user approves it in their client first.${onlyNote(input)}`,
+	parameters: {
+		type: "object",
+		properties: {
+			id: idParameter,
+			secret: {
+				type: "string",
+				description: "The sender's own secret, when it makes one; omit it to have the app make one."
+			}
+		},
+		required: ["id"]
+	},
+	annotations: writes,
+	run: async (args, context) => {
+		const id = idOf(args);
+		if (!id) return "Pass { \"id\": \"<id>\" }, and a secret when the sender makes its own.";
+		const refusal = outside(input, "workflows");
+		if (refusal) return refusal;
+		const before = await recordBefore(context, "workflows", id, void 0);
+		if (typeof before === "string") return before;
+		if (!before) return refused(notFound("No workflows with this key that you may read"));
+		const { text, described } = await approvalTexts(context, "workflows");
+		const answer = await context.approve({
+			title: text("webhookTitle", { record: recordName(described, id, before.record) }),
+			body: text("webhookBody"),
+			approveLabel: text("issue"),
+			rejectLabel: text("reject")
+		});
+		if (answer !== "approved") return notApproved(answer);
+		return issue(context.session, id, textOf(args.secret) || void 0).then((issued) => JSON.stringify(issued), refused);
+	}
+});
+/** The tools that turn workflows on and issue their webhook URLs; `new_webhook_url` only where the app can issue them. */
+const webhookTools = (input = {}, issue) => [enableWorkflowTool(input), ...issue ? [newWebhookUrlTool(issue, input)] : []];
+//#endregion
+export { enableWorkflowTool, newWebhookUrlTool, webhookTools };

package/dist/workflows/mcp/workflow-instructions.js

@@ -4,7 +4,7 @@ import { limits } from "@protobase/workflows";
 * profile of the States Language with JSONata, and how the workflow tools find, make, change and test-run them.
 */
 const workflowInstructions = [
-	"Workflows: list_workflow_types names the step types and triggers with their arguments and inputs; list_workflows and get_workflow read workflows; validate_workflow checks a definition without saving it; create_workflow and update_workflow save one; run_workflow starts a run with an input, and get_workflow_run reads it with each step's input, output, logs and error. A run goes on in the background: read it again until its status is succeeded or failed, then fix the step that failed with update_workflow and run it again.",
+	"Workflows: list_workflow_types names the step types and triggers with their arguments and inputs; list_workflows and get_workflow read workflows; validate_workflow checks a definition without saving it; create_workflow and update_workflow save one; run_workflow starts a run with an input, and get_workflow_run reads it with each step's input, output, logs and error. A run goes on in the background: read it again until its status is succeeded or failed, then fix the step that failed with update_workflow and run it again. A trigger starts runs only once enable_workflow turned the workflow on. A webhook trigger whose sender you give a URL, such as app:webhook, gets its URL and secret from new_webhook_url, shown once; one that registers its own URL with its service as the workflow is turned on needs none, and new_webhook_url refuses it.",
 	"A definition is one JSON document: { \"trigger\": <trigger>, \"stateMachine\": { \"QueryLanguage\": \"JSONata\", \"StartAt\": \"<state>\", \"States\": { \"<state>\": <state>, ... } } }, the States Language with JSONata expressions, in a profile where every value is read by name. It holds no layout. <trigger> is an object with one key: { \"<trigger id>\": <its input> } for a trigger list_workflow_types names, or { \"manual\": {} } for a workflow that runs only when someone starts it.",
 	"States: Task { Resource: <step type>, Arguments, TimeoutSeconds, Retry, Catch }; Pass { Output, Assign }; Choice { Choices: [{ Condition, Next, Output?, Assign? }], Default }; Map { Items, ItemProcessor: { StartAt, States }, MaxConcurrency }; Wait { Seconds | Timestamp }; Succeed { Output }; Fail { Error, Cause }. Every state may have Comment, Output and Assign. Task, Pass, Map and Wait have exactly one of Next (a state name) and End: true. State names are unique across the document, Maps included, and every state must be reachable from StartAt. InputPath, Parameters, ResultPath and the other JSONPath fields, and Parallel, are not part of the profile.",
 	"Expressions: a string that is whole \"{% ... %}\" is a JSONata expression whose value, of any type, the field takes; any other string is literal text. Build text inside one expression with &: \"{% 'Order ' & $order.id %}\". Expressions sit at any depth in Arguments, Output and Assign, and in Items, Condition, Seconds, Timestamp, Error and Cause.",

package/dist/workflows/mcp/workflow-read-tools.d.ts

@@ -1,4 +1,5 @@
 import { AssistantTool, ToolContext } from "../../assistant/tools.js";
+import { IssueWebhook } from "./webhook-tools.js";
 import "../../index.js";
 import { ResourceModel } from "@protobase/schema";
 import { CheckOptions, TypeEntry } from "@protobase/workflows";
@@ -10,6 +11,8 @@ import { CheckOptions, TypeEntry } from "@protobase/workflows";
 export type WorkflowCatalog = {
   types: readonly TypeEntry[];
   checkWith: (models: (name: string) => ResourceModel | undefined) => CheckOptions;
+  /** Issues a workflow's webhook URL as the caller, for `new_webhook_url`. */
+  issueWebhook?: IssueWebhook;
 };
 /** The tools that read workflows, their types and runs, and check definitions. */
 export declare const workflowReadTools: (catalog: WorkflowCatalog) => AssistantTool<ToolContext>[];

package/dist/workflows/plugin-records.js

@@ -3,8 +3,8 @@ import { tenantScope } from "../tenant.js";
 import { issueTicket } from "../files/ticket.js";
 import { runBatch } from "../batch/run-batch.js";
 import { assistantRecords, toolEntry } from "../assistant/records.js";
-import { effectsStore } from "./effects-store.js";
 import { runFileRef } from "./run-files.js";
+import { effectsStore } from "./effects-store.js";
 import { sql } from "kysely";
 import { StepError } from "@protobase/workflows";
 //#region src/workflows/plugin-records.ts

package/dist/workflows/plugin-services.js

@@ -1,6 +1,6 @@
+import { pluginFetch } from "./plugin-fetch.js";
 import { readRunFile, storeRunFile } from "./run-files.js";
 import { pluginRecords } from "./plugin-records.js";
-import { pluginFetch } from "./plugin-fetch.js";
 //#region src/workflows/plugin-services.ts
 /** The plugin context's `files`: those of the run alone, in the app's `private` file provider. */
 const runFiles = (files, runId) => ({

package/dist/workflows/ready/ready-start.js

@@ -1,7 +1,7 @@
 import { HttpProblem } from "../../problem.js";
 import { assistantRecords } from "../../assistant/records.js";
-import { saverSession } from "../plugin-records.js";
 import { startWorkflow } from "../start-workflow.js";
+import { saverSession } from "../plugin-records.js";
 import { triggerFailed, triggerRecovered } from "../triggers/trigger-row.js";
 import { encodeKey } from "@protobase/schema/internal";
 import { checkFilter, evaluateFilter, parseFilter } from "@protobase/schema";

package/dist/workflows/run-files.js

@@ -62,5 +62,11 @@ const readRunFile = async (files, runId, value, field) => {
 		bytes
 	};
 };
+/** Removes a file a run stored, as when the run it was kept for turned out to be started already. */
+const removeRunFile = async (files, value) => {
+	const ref = parseUri(value.uri);
+	if (!ref) throw new Error(`${value.uri} is not a file URI`);
+	await runStore(files).delete(ref.path);
+};
 //#endregion
-export { isFileValue, readRunFile, runFileLimit, runFileRef, storeRunFile };
+export { isFileValue, readRunFile, removeRunFile, runFileLimit, runFileRef, storeRunFile };

package/dist/workflows/schema-sql.js

@@ -1,6 +1,6 @@
 import { quoteIdent } from "../changes/capture-sql.js";
 /** The comment the schema's function carries, which the startup check reads. */
-const workflowsComment = `Protobase workflows 6`;
+const workflowsComment = `Protobase workflows 7`;
 const commentVersion = (comment) => {
 	const match = comment?.match(/^Protobase workflows (\d+)$/);
 	return match ? Number(match[1]) : void 0;
@@ -83,7 +83,9 @@ const triggerStateBytes = 65536;
 /**
 * Which version of a workflow is on (`enabled_version`, null when off), and one row per trigger of an enabled version:
 * its type and input, and the state its kind keeps. A change raises `generation`, so a job queued for an older one
-* ends without acting. A trigger being stopped stays `stopping` until its stop job removes it. Written whole each time:
+* ends without acting. A poll or renewal acts only as the job `poll_job_id` names, on the try `poll_attempt` claimed,
+* so a try that ran past its timeout writes nothing once its retry claimed the trigger. A deleted workflow leaves its
+* trigger without a workflow, which its delete hook stops. A trigger being stopped stays `stopping` until its stop job removes it. Written whole each time:
 * every statement is idempotent.
 */
 const triggersSql = (schema) => {
@@ -96,7 +98,7 @@ do $$ begin
 end $$;
 create table if not exists ${s}."triggers" (
   "id" uuid primary key default gen_random_uuid(),
-  "workflow_id" uuid not null references ${s}."workflows" ("id") on delete cascade,
+  "workflow_id" uuid references ${s}."workflows" ("id") on delete set null,
   "version" integer not null,
   "tenant_id" text,
   "type" text not null,
@@ -107,12 +109,22 @@ create table if not exists ${s}."triggers" (
   "cursor" jsonb check (octet_length("cursor"::text) <= ${triggerStateBytes}),
   "store" jsonb check (octet_length("store"::text) <= ${triggerStateBytes}),
   "poll_job_id" text,
+  "poll_attempt" integer,
   "consecutive_failures" integer not null,
   "last_error" jsonb,
   "next_poll_at" timestamptz,
   "created_at" timestamptz not null default now(),
   "updated_at" timestamptz not null default now()
 );
+alter table ${s}."triggers" add column if not exists "poll_attempt" integer;
+-- A deleted workflow's trigger stays, without its workflow, until its stop job unsubscribed it at its provider.
+alter table ${s}."triggers" alter column "workflow_id" drop not null;
+do $$ begin
+  if exists (select 1 from pg_constraint where conname = 'triggers_workflow_id_fkey' and confdeltype = 'c' and connamespace = ${`'${schema.replaceAll("'", "''")}'`}::regnamespace) then
+    alter table ${s}."triggers" drop constraint "triggers_workflow_id_fkey";
+    alter table ${s}."triggers" add constraint "triggers_workflow_id_fkey" foreign key ("workflow_id") references ${s}."workflows" ("id") on delete set null;
+  end if;
+end $$;
 create unique index if not exists "triggers_workflow" on ${s}."triggers" ("workflow_id") where "status" <> 'stopping';
 create index if not exists "triggers_workflow_id" on ${s}."triggers" ("workflow_id");
 create index if not exists "triggers_updated_at" on ${s}."triggers" ("updated_at");

package/dist/workflows/schema.js

@@ -2,6 +2,7 @@ import { quoteIdent } from "../changes/capture-sql.js";
 import { migrationCommand } from "../changes/capture-schema.js";
 import { workflowsSchema } from "./options.js";
 import { commentVersion, effectsSql, functionsSql, indexesSql, tablesSql, triggersSql, workflowsTriggers } from "./schema-sql.js";
+import { hooksSql } from "./hooks/hooks-sql.js";
 import { sql } from "kysely";
 //#region src/workflows/schema.ts
 const readWorkflowsSchema = async (db, schema) => {
@@ -15,7 +16,7 @@ const readWorkflowsSchema = async (db, schema) => {
 	const row = rows[0];
 	return {
 		tables: row.found,
-		current: row.found && row.trigger_rows && commentVersion(row.comment) === 6 && row.triggers === workflowsTriggers.length
+		current: row.found && row.trigger_rows && commentVersion(row.comment) === 7 && row.triggers === workflowsTriggers.length
 	};
 };
 /**
@@ -31,6 +32,7 @@ const workflowsMigration = async (db, options = {}) => {
 		...found.tables ? [] : [tablesSql(schema)],
 		triggersSql(schema),
 		effectsSql(schema),
+		hooksSql(schema),
 		indexesSql(schema),
 		functionsSql(schema)
 	].join(";\n\n")};`;

package/dist/workflows/start-workflow.d.ts

@@ -19,10 +19,12 @@ export type StartWorkflowOptions = {
   schema?: string;
   /** The version to run, as a trigger runs the enabled one; default the workflow's current version. */
   version?: number;
+  /** The run's id, when the caller kept something under it first, such as a webhook's large body; default a new one. */
+  id?: string;
 };
 /**
  * Starts a run of a workflow from the app's own code, such as a job or a write hook, and returns the run's id. In
  * `db`'s own transaction when it is one, so the run starts when the caller's writes commit, or not at all.
  */
-export declare const startWorkflow: (db: Db, { workflow, input, tenant, startedBy, key, schema, version }: StartWorkflowOptions) => Promise<string>;
+export declare const startWorkflow: (db: Db, { workflow, input, tenant, startedBy, key, schema, version, id: runId }: StartWorkflowOptions) => Promise<string>;
 //#endregion

package/dist/workflows/start-workflow.js

@@ -7,13 +7,13 @@ import { sql } from "kysely";
 * Starts a run of a workflow from the app's own code, such as a job or a write hook, and returns the run's id. In
 * `db`'s own transaction when it is one, so the run starts when the caller's writes commit, or not at all.
 */
-const startWorkflow = async (db, { workflow, input, tenant, startedBy, key, schema = "workflows", version }) => {
+const startWorkflow = async (db, { workflow, input, tenant, startedBy, key, schema = "workflows", version, id: runId }) => {
 	checkRunInput(input);
 	const job = currentJobs().definition(segmentJobName);
 	if (!job) throw new Error("Workflows are not running in this app: add `workflows: {}` to protobase.config.ts");
 	const runs = sql.id(schema, "runs");
-	const { rows } = await sql`insert into ${runs} (workflow_id, version, input, tenant_id, started_by, key)
-    values (${workflow}, ${version ?? null}, ${input === void 0 ? null : JSON.stringify(input)}::jsonb, ${tenant === void 0 ? null : String(tenant)}, ${startedBy ?? null}, ${key ?? null})
+	const { rows } = await sql`insert into ${runs} (id, workflow_id, version, input, tenant_id, started_by, key)
+    values (${runId === void 0 ? sql`gen_random_uuid()` : sql`${runId}::uuid`}, ${workflow}, ${version ?? null}, ${input === void 0 ? null : JSON.stringify(input)}::jsonb, ${tenant === void 0 ? null : String(tenant)}, ${startedBy ?? null}, ${key ?? null})
     on conflict (workflow_id, key) do nothing returning id`.execute(db);
 	if (rows.length === 0) {
 		const existing = (await sql`select id, status from ${runs} where workflow_id = ${workflow} and key = ${key}`.execute(db)).rows[0];
@@ -24,5 +24,11 @@ const startWorkflow = async (db, { workflow, input, tenant, startedBy, key, sche
 	await job.enqueue(db, { run: id }, { key: id });
 	return id;
 };
+/** Queues the first segment of runs a trigger inserted itself, in `db`'s transaction. */
+const queueRuns = async (db, ids) => {
+	const job = currentJobs().definition(segmentJobName);
+	if (!job) throw new Error("Workflows are not running in this app: add `workflows: {}` to protobase.config.ts");
+	for (const id of ids) await job.enqueue(db, { run: id }, { key: id });
+};
 //#endregion
-export { startWorkflow };
+export { queueRuns, startWorkflow };

package/dist/workflows/triggers/delete-hook.js

@@ -0,0 +1,15 @@
+import { sql } from "kysely";
+//#region src/workflows/triggers/delete-hook.ts
+/**
+* As a workflow is deleted, in the delete's transaction: its trigger, which the delete left without a workflow, stops at
+* once, so no poll or call starts a run of it, and its stop job, queued in the same write, ends any subscription at its
+* provider and then removes it. The delete removed its webhook URL already.
+*/
+const workflowDeleteHook = (schema, jobs) => async (event, trx) => {
+	if (event.resource.name !== "workflows" || event.operation !== "delete") return;
+	const { rows } = await sql`update ${sql.id(schema, "triggers")} set status = 'stopping', generation = generation + 1, updated_at = now()
+    where workflow_id is null and status <> 'stopping' returning id`.execute(trx);
+	for (const { id } of rows) await jobs.stop.enqueue(trx, { trigger: id });
+};
+//#endregion
+export { workflowDeleteHook };

package/dist/workflows/triggers/plugin-call.js

@@ -0,0 +1,35 @@
+import { pluginFetch } from "../plugin-fetch.js";
+import { ConnectionError } from "@protobase/workflows/plugin";
+//#region src/workflows/triggers/plugin-call.ts
+/** The longest a plugin's error message is kept on its trigger, which the workflow's readers see. */
+const messageLength = 1e3;
+/**
+* Runs a plugin's trigger code: any error it throws is the plugin's, which the trigger records rather than the job
+* retrying it; a `ConnectionError('link_expired')` is a sign-in to renew. The message goes through `redact` and is cut
+* to 1 000 characters, since the trigger's readers see it.
+*/
+const callPlugin = (work, redact) => Promise.resolve().then(work).then((value) => ({ value }), (error) => {
+	const message = redact(error instanceof Error ? error.message : String(error)).slice(0, messageLength);
+	if (error instanceof ConnectionError && error.code === "link_expired") return { expired: message };
+	return { failed: message };
+});
+/**
+* `redact` after blanking out `values` that only this call knew, such as a webhook's URL key and secret, as written and
+* URL-encoded, so a message that quotes them keeps neither.
+*/
+const redactAlso = (values, redact) => {
+	const blanked = [...new Set(values.flatMap((value) => [value, encodeURIComponent(value)]))].filter((value) => value.length > 0);
+	return (text) => redact(blanked.reduce((kept, value) => kept.replaceAll(value, "[redacted]"), text));
+};
+/**
+* What a trigger's hooks get: its input, the guarded `fetch`, and the job's signal, which aborts at its timeout. No
+* type that needs a connection runs yet, so it has none.
+*/
+const triggerContext = ({ allowPrivateAddresses }, input, signal) => ({
+	input,
+	connection: void 0,
+	fetch: pluginFetch({ allowPrivateAddresses }),
+	signal
+});
+//#endregion
+export { callPlugin, redactAlso, triggerContext };