@voltro/protocol 0.85.0 → 0.86.0

package/dist/outbox.js

@@ -0,0 +1,10 @@
+//#region src/outbox.ts
+function e(e, t) {
+	if (typeof e != "object" || !e) throw Error(`Outbox handler ${t}: definition must be an object`);
+	let n = e;
+	if (typeof n.effect != "string" || n.effect.trim() === "") throw Error(`Outbox handler ${t}: effect must be a non-empty string`);
+	if (typeof n.handler != "function") throw Error(`Outbox handler ${t}: handler must be a function`);
+	if (n.maxAttempts !== void 0 && (typeof n.maxAttempts != "number" || !Number.isSafeInteger(n.maxAttempts) || n.maxAttempts < 1)) throw Error(`Outbox handler ${t}: maxAttempts must be a positive safe integer`);
+}
+//#endregion
+export { e as validateOutboxHandlerDefinition };

package/dist/pairing.js

@@ -0,0 +1,75 @@
+//#region src/pairing.ts
+var e = "voltro-dev", t = "pair", n = "voltro:pairing", r = (e) => {
+	try {
+		let t = new URL(e);
+		return t.protocol === "http:" || t.protocol === "https:";
+	} catch {
+		return !1;
+	}
+}, i = (e) => {
+	try {
+		let t = new URL(e).hostname;
+		return t === "localhost" || t === "127.0.0.1" || t === "::1" || t === "[::1]";
+	} catch {
+		return !1;
+	}
+}, a = (n) => {
+	if (!r(n.api)) throw Error(`pairingLink: api must be an http(s) url, got ${JSON.stringify(n.api)}`);
+	if (i(n.api)) throw Error("pairingLink: api must be the LAN address — a device cannot reach localhost on this machine");
+	if (!/^[A-Za-z0-9_-]+$/.test(n.name)) throw Error(`pairingLink: name must be a plain identifier, got ${JSON.stringify(n.name)}`);
+	let a = new URLSearchParams({
+		api: n.api,
+		name: n.name
+	});
+	return n.token !== void 0 && n.token.length > 0 && a.set("token", n.token), `${e}://${t}?${a.toString()}`;
+}, o = (e) => {
+	let t;
+	try {
+		t = new URL(e);
+	} catch {
+		return null;
+	}
+	if (t.protocol !== "voltro-dev:" || (t.host || t.pathname.replace(/^\/+/, "")) !== "pair") return null;
+	let n = t.searchParams.get("api") ?? "", a = t.searchParams.get("name") ?? "", o = t.searchParams.get("token");
+	return !r(n) || i(n) || !/^[A-Za-z0-9_-]+$/.test(a) ? null : {
+		api: n,
+		name: a,
+		...o !== null && o.length > 0 ? { token: o } : {}
+	};
+}, s = (e) => "getItem" in e ? {
+	get: async (t) => e.getItem(t),
+	set: async (t, n) => {
+		await e.setItem(t, n);
+	},
+	remove: e.removeItem ? async (t) => {
+		await e.removeItem(t);
+	} : null
+} : {
+	get: async (t) => e.get(t),
+	set: async (t, n) => {
+		await e.set(t, n);
+	},
+	remove: e.remove ? async (t) => {
+		await e.remove(t);
+	} : null
+}, c = async (e, t) => {
+	await s(e).set(n, JSON.stringify(t));
+}, l = async (e) => {
+	let t = await s(e).get(n);
+	if (t === null || t === "") return null;
+	try {
+		let e = JSON.parse(t);
+		return typeof e.api != "string" || typeof e.name != "string" || !r(e.api) ? null : {
+			api: e.api,
+			name: e.name,
+			...typeof e.token == "string" && e.token.length > 0 ? { token: e.token } : {}
+		};
+	} catch {
+		return null;
+	}
+}, u = async (e) => {
+	let t = s(e);
+	t.remove ? await t.remove(n) : await t.set(n, "");
+};
+//#endregion
+export { t as PAIRING_HOST, e as PAIRING_SCHEME, n as PAIRING_STORAGE_KEY, c as applyPairing, u as clearPairing, a as pairingLink, o as parsePairingLink, l as readPairing };

package/dist/plugin.js

@@ -0,0 +1,61 @@
+import { Context as e, Layer as t } from "effect";
+//#region src/plugin.ts
+var n = (e) => e, r = (e) => e, i = (e) => {
+	let t = e.alias?.trim(), n = e.instance?.trim(), r = t !== void 0 && t !== "" ? t : e.base;
+	return n !== void 0 && n !== "" ? `${r}#${n}` : r;
+}, a = (e) => {
+	if (e.length !== 0) return (t, n) => e.reduceRight((e, t) => t(e, n), t);
+}, o = (n, r) => {
+	let i = e.Service(n);
+	return {
+		Tag: i,
+		Live: t.succeed(i, r)
+	};
+}, s = (e, t, n) => {
+	if (!t) return { ok: !0 };
+	let r = n === void 0 ? null : c(n);
+	if (!r) return {
+		ok: !0,
+		unverified: `plugin "${e}" requires framework ${t}, but the running framework version is ${n === void 0 ? "unknown" : `unreadable ("${n}")`} — not checked.`
+	};
+	let i = t.trim();
+	if (i === "*" || i === "") return { ok: !0 };
+	let a = i.split(/\s+/);
+	for (let i of a) if (!u(i, r)) return {
+		ok: !1,
+		reason: `plugin "${e}" requires framework ${t}, running ${n}`
+	};
+	return { ok: !0 };
+}, c = (e) => {
+	let t = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9a-zA-Z.-]+))?$/.exec(e.trim());
+	return t ? {
+		major: Number(t[1]),
+		minor: Number(t[2]),
+		patch: Number(t[3]),
+		pre: t[4] ?? ""
+	} : null;
+}, l = (e, t) => e.major === t.major ? e.minor === t.minor ? e.patch === t.patch ? e.pre && !t.pre ? -1 : !e.pre && t.pre ? 1 : e.pre && t.pre ? e.pre < t.pre ? -1 : +(e.pre > t.pre) : 0 : e.patch - t.patch : e.minor - t.minor : e.major - t.major, u = (e, t) => {
+	if (e === "*") return !0;
+	if (e.startsWith("^")) {
+		let n = c(e.slice(1));
+		return !n || t.major !== n.major ? !1 : l(t, n) >= 0;
+	}
+	if (e.startsWith("~")) {
+		let n = c(e.slice(1));
+		return !n || t.major !== n.major || t.minor !== n.minor ? !1 : l(t, n) >= 0;
+	}
+	let n = /^(>=|<=|>|<)(.+)$/.exec(e);
+	if (n) {
+		let e = n[1], r = c(n[2]);
+		if (!r) return !1;
+		let i = l(t, r);
+		if (e === ">=") return i >= 0;
+		if (e === "<=") return i <= 0;
+		if (e === ">") return i > 0;
+		if (e === "<") return i < 0;
+	}
+	let r = c(e);
+	return r ? l(t, r) === 0 : !1;
+};
+//#endregion
+export { s as checkFrameworkCompat, a as composeRpcInterceptors, n as definePlugin, r as definePluginRoute, o as definePluginService, i as pluginInstanceName };

package/dist/pluginNaming.js

@@ -0,0 +1,32 @@
+//#region src/pluginNaming.ts
+var e = (e) => {
+	let t = e.startsWith("@") ? e.replace(/^@[^/]+\//, "") : e;
+	return (t.startsWith("plugin-") ? t.slice(7) : t).replace(/-([a-zA-Z0-9])/g, (e, t) => t.toUpperCase());
+}, t = (e) => {
+	let t = e.startsWith("@") ? e.replace(/^@[^/]+\//, "") : e;
+	return (t.startsWith("plugin-") ? t.slice(7) : t).replace(/#/g, "--").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}, n = Symbol.for("@voltro/protocol/pluginAliases"), r = () => {
+	let e = globalThis, t = e[n];
+	if (t instanceof Map) return t;
+	let r = /* @__PURE__ */ new Map();
+	return e[n] = r, r;
+}, i = (e) => {
+	let t = r();
+	for (let [n, r] of Object.entries(e)) {
+		if (r === "") continue;
+		let e = t.get(n);
+		e === void 0 ? t.set(n, /* @__PURE__ */ new Set([r])) : e.add(r);
+	}
+}, a = () => {
+	r().clear();
+}, o = (t, n) => {
+	let i = r().get(t);
+	if (i === void 0 || i.size === 0) return `${e(t)}.${n}`;
+	if (i.size === 1) for (let e of i) return `${e}.${n}`;
+	let a, o = 0;
+	for (let e of i) e.includes("#") || (a = e, o++);
+	if (o === 1) return `${a}.${n}`;
+	throw Error(`[voltro] ${t} is installed more than once (${[...i].sort().join(", ")}) and no single install is the primary one, so a plugin hook cannot tell which of them it addresses. Call the route by its full tag instead — e.g. useSubscription(api, '${[...i].sort()[0]}.${n}').`);
+};
+//#endregion
+export { e as pluginAlias, t as pluginSlug, o as pluginTag, i as registerPluginAliases, a as resetPluginAliases };

package/dist/procedure.js

@@ -0,0 +1,262 @@
+import { subscriptionEvent as e } from "./subscriptionEvent.js";
+import { RequestedTenantRefused as t } from "./tenantSelection.js";
+import { Unauthenticated as n } from "./auth.js";
+import { NoSuchResource as r, ScopeError as i, declaresResourceGuard as a, isOpenAccess as o, openAccessSpec as s, serviceAccessSpec as c } from "./scopes.js";
+import { strictInput as l } from "./strictInput.js";
+import { BusinessRuleViolation as u } from "./businessRule.js";
+import { MutationConnectionRequired as d, MutationInFlight as f } from "./idempotency.js";
+import { ValidationError as p, ValidationErrors as m } from "./validation.js";
+import { ApprovalErrors as h } from "./approval.js";
+import { normalizeSource as g } from "./reactivityChannel.js";
+import { Schema as _ } from "effect";
+import { Rpc as v } from "effect/rpc";
+import { VersionConflict as y } from "@voltro/database/wire";
+//#region src/procedure.ts
+var b = (e) => e.internal !== !0, x = (e) => e.service === void 0 ? "client" : "service", S = (e) => b(e) && e.service === void 0, C = (e) => b(e) && e.service !== void 0, w = /^[a-z][a-z0-9-]{0,55}$/i, T = (e) => {
+	if (D(e), E(e), e.idempotencyScope !== void 0 && e.idempotencyScope !== "subject" && e.idempotencyScope !== "connection") throw Error(`${e.name}: idempotencyScope must be 'subject' or 'connection'`);
+	let t = e.serialize;
+	if (t !== void 0) {
+		if (typeof t.key != "function") throw Error(`${e.name}: serialize.key must be a function of the input`);
+		if (t.maxPending !== void 0 && (!Number.isSafeInteger(t.maxPending) || t.maxPending < 1)) throw Error(`${e.name}: serialize.maxPending must be a positive integer`);
+	}
+	if (e.idempotencyScope === "connection" && (e.internal === !0 || e.publicApi !== void 0 || e.exposeAsTool !== void 0)) throw Error(`${e.name}: connection-scoped mutations require the native WebSocket RPC surface; internal, publicApi and exposeAsTool cannot establish its connection state`);
+	if (Array.isArray(e.guards) && e.guards.length === 0) throw Error(`${e.name}: \`guards: []\` is empty, so it enforces nothing — but it reads\n  at the call site as if this procedure were protected. Omit the field for an
+  unguarded procedure, or list the scopes required to call it.`);
+	let n = typeof e.source == "string" ? [e.source] : Array.isArray(e.source) ? e.source : void 0;
+	if (n !== void 0 && (n.length === 0 || n.some((e) => String(e).trim() === ""))) throw Error(`${e.name}: \`source\` is empty, so this query declares reactivity and\n  subscribes to nothing — it serves one snapshot and never updates again,
+  which is indistinguishable from "nothing changed". Name the table(s) it
+  reads, or omit \`source\` for a non-reactive query.`);
+	if (e.internal !== !0) return e;
+	if (e.openAccess !== void 0) throw Error(`${e.name}: \`internal: true\` cannot be combined with \`openAccess\`.\n  \`internal\` takes the procedure OFF the wire, and \`openAccess\` declares who may
+  call it there — together they describe a decision about a surface that does not
+  exist. Drop \`openAccess\` (an internal procedure needs no wire decision), or drop
+  \`internal: true\` if the procedure really is meant to be callable.`);
+	if (e.overridesPlugin === !0) throw Error(`${e.name}: \`internal: true\` cannot be combined with \`overridesPlugin\`.\n  The override REMOVES the plugin route, and an internal procedure is not
+  wire-reachable — so the plugin's route would vanish with nothing callable
+  in its place, and callers would get a 404 for something that used to work.`);
+	let r = [e.publicApi === void 0 ? void 0 : "publicApi", e.exposeAsTool === void 0 ? void 0 : "exposeAsTool"].filter((e) => e !== void 0);
+	if (r.length === 0) return e;
+	throw Error(`${e.name}: \`internal: true\` cannot be combined with ${r.map((e) => `\`${e}\``).join(" or ")}. \`internal\` takes the procedure OFF the wire; those put it back ON a different one (${r.includes("publicApi") ? "a REST route" : "an agent tool"}), and that surface is projected without consulting the flag — so the procedure would be unreachable from your client and reachable from the internet. Drop \`internal: true\` if the wider surface is intended, or remove the ${r.join(" / ")} annotation if it is not.`);
+}, E = (e) => {
+	let t = e.service;
+	if (t === void 0) return;
+	let n = t.callers;
+	if (!Array.isArray(n) || n.length === 0) throw Error(`${e.name}: \`service.callers\` is empty, so NO app may call this procedure —\n  and no browser either. Name the calling app(s), e.g. \`service: { callers: ['worker'] }\`,
+  or drop \`service:\` if the procedure is meant for this app's own clients.`);
+	let r = n.filter((e) => typeof e != "string" || !w.test(e));
+	if (r.length > 0) throw Error(`${e.name}: \`service.callers\` holds ${r.map((e) => JSON.stringify(e)).join(", ")} — a caller is an\n  app name (letters, digits, dashes; starting with a letter; at most 56 characters), the same name this app
+  lists in \`serviceCallers\` and the caller's credential resolves to.`);
+	if (new Set(n).size !== n.length) throw Error(`${e.name}: \`service.callers\` lists the same app twice`);
+	let i = [
+		e.internal === !0 ? "`internal: true` (it removes the wire surface a service calls over)" : void 0,
+		e.publicApi === void 0 ? void 0 : "`publicApi` (a REST route is for callers that are not the listed apps)",
+		e.exposeAsTool === void 0 ? void 0 : "`exposeAsTool` (an agent tool is not one of the listed apps)",
+		e.requiresApproval === void 0 ? void 0 : "`requiresApproval` (a second HUMAN cannot approve a machine call)",
+		e.overridesPlugin === !0 ? "`overridesPlugin` (a plugin route is a client surface; replacing it with a service-only one breaks its clients)" : void 0,
+		e.idempotencyScope === "connection" ? "`idempotencyScope: 'connection'` (a service call dedups per service, across reconnects)" : void 0
+	].filter((e) => e !== void 0);
+	if (i.length !== 0) throw Error(`${e.name}: \`service:\` cannot be combined with ${i.join("; ")}.\n  A service procedure is callable only by the listed apps of this project, over the
+  socket, with their service credential. Drop the other field, or drop \`service:\`.`);
+}, D = (e) => {
+	let t = e.requiresApproval;
+	if (t !== void 0) {
+		if (!Array.isArray(t.approvers) || t.approvers.length === 0) throw Error(`${e.name}: \`requiresApproval.approvers\` is empty, so NOBODY can approve this\n  procedure and every call would park forever. Name the scope(s) an approver must hold
+  — e.g. \`approvers: [{ scope: 'invoices:approve' }]\`.`);
+		if (e.openAccess !== void 0) throw Error(`${e.name}: \`requiresApproval\` cannot be combined with \`openAccess\`.\n  The self-approval refusal compares subject ids, and an unauthenticated caller has
+  none — so on an open procedure every anonymous caller would count as a DIFFERENT
+  human from every other, and the second-pair-of-eyes control would enforce nothing.
+  Give the procedure a \`guards:\` decision, or drop \`requiresApproval\`.`);
+	}
+}, O = (e) => e.action !== void 0 && e.resourceType !== void 0, k = (e) => e.authenticated === !0, A = (e) => e.openAccess !== void 0 || e.guards !== void 0 && e.guards.length > 0, j = (e, t, n, r) => {
+	if (r !== void 0) {
+		if (n !== void 0 || t !== void 0 && t.length > 0) throw Error(`${e}: \`service:\` is an access decision of its own — only the listed apps may\n  call this procedure — so it cannot sit beside \`guards:\` or \`openAccess:\`. A service
+  holds no scopes, and no user may call a service procedure. Keep exactly one.`);
+		return Array.isArray(r.callers) ? [c(r.callers)] : void 0;
+	}
+	if (n === void 0) return t;
+	if (n.trim() === "") throw Error(`${e}: \`openAccess\` needs a REASON, not an empty string. It is the sentence a\n  reviewer reads to decide whether this procedure should really be callable
+  without an authorization check — e.g. \`openAccess: 'public pricing, no caller data'\`.`);
+	if (t !== void 0 && t.length > 0) throw Error(`${e}: \`openAccess\` and \`guards\` are two different access decisions, so\n  declaring both says the procedure is protected AND open. Keep the guards if a
+  caller must hold a scope; drop them if anyone may call it.`);
+	return [s(n.trim())];
+}, M = (e) => T({
+	kind: "query",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? _.Never,
+	source: g(e.source),
+	cache: e.cache,
+	guards: j(e.name, e.guards, e.openAccess, e.service),
+	openAccess: e.openAccess,
+	service: e.service === void 0 ? void 0 : { callers: Array.isArray(e.service.callers) ? [...e.service.callers] : e.service.callers },
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool,
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
+}), N = (e) => T({
+	kind: "mutation",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? _.Never,
+	...e.idempotencyScope === void 0 ? {} : { idempotencyScope: e.idempotencyScope },
+	...e.serialize === void 0 ? {} : { serialize: e.serialize },
+	target: e.target,
+	guards: j(e.name, e.guards, e.openAccess, e.service),
+	openAccess: e.openAccess,
+	service: e.service === void 0 ? void 0 : { callers: Array.isArray(e.service.callers) ? [...e.service.callers] : e.service.callers },
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool,
+	requiresApproval: e.requiresApproval,
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
+}), P = (e) => T({
+	kind: "action",
+	name: e.name,
+	input: e.input,
+	output: e.output,
+	error: e.error ?? _.Never,
+	guards: j(e.name, e.guards, e.openAccess, e.service),
+	openAccess: e.openAccess,
+	service: e.service === void 0 ? void 0 : { callers: Array.isArray(e.service.callers) ? [...e.service.callers] : e.service.callers },
+	source: e.source,
+	target: e.target,
+	publicApi: e.publicApi,
+	exposeAsTool: e.exposeAsTool,
+	requiresApproval: e.requiresApproval,
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin
+}), F = (e) => T({
+	kind: "stream",
+	name: e.name,
+	input: e.input,
+	element: e.element,
+	error: e.error ?? _.Never,
+	internal: e.internal,
+	overridesPlugin: e.overridesPlugin,
+	guards: j(e.name, e.guards, e.openAccess),
+	openAccess: e.openAccess
+}), I = (e, t) => t && t.length > 0 ? _.Union([e, ...t]) : e, L = (e) => e !== void 0 && e.some((e) => !o(e)), R = (e) => _.Union([
+	e,
+	i,
+	n,
+	t
+]), z = (e) => _.Union([e, u]), B = (e) => _.Union([
+	e,
+	p,
+	m
+]), V = (e, t) => t === void 0 ? e : _.Union([e, h]), H = (e, t) => a(t) ? _.Union([e, r]) : e, U = (e, t, n) => I(W(e, t), n), W = (e, t) => {
+	let n = H(R(e.error), e.guards);
+	if (t === "stream" || t === "query") return n;
+	let r = t === "mutation" ? _.Union([
+		z(n),
+		f,
+		y
+	]) : n;
+	return V(B(t === "mutation" && e.idempotencyScope === "connection" ? _.Union([r, d]) : r), e.requiresApproval);
+}, G = {
+	query: [
+		i,
+		n,
+		t
+	],
+	stream: [
+		i,
+		n,
+		t
+	],
+	action: [
+		i,
+		n,
+		t,
+		p,
+		m
+	],
+	mutation: [
+		i,
+		n,
+		t,
+		u,
+		f,
+		y,
+		p,
+		m
+	]
+}, K = (e, t) => I(H(R(e.errorSchema), e.guards), t), q = (e, t) => ({
+	...e,
+	name: t
+}), J = (t, n) => v.make(t.name, {
+	payload: l(t.input, t.name, L(t.guards)),
+	success: e(t.output),
+	error: U(t, "query", n),
+	stream: !0
+}), Y = (e, t) => v.make(e.name, {
+	payload: l(e.input, e.name, L(e.guards)),
+	success: e.output,
+	error: U(e, "mutation", t)
+}), X = (e, t) => v.make(e.name, {
+	payload: l(e.input, e.name, L(e.guards)),
+	success: e.output,
+	error: U(e, "action", t)
+}), Z = (e, t) => v.make(e.name, {
+	payload: l(e.input, e.name, L(e.guards)),
+	success: e.element,
+	error: U(e, "stream", t),
+	stream: !0
+}), Q = (e) => {
+	switch (e.kind) {
+		case "query": return J(e);
+		case "mutation": return Y(e);
+		case "action": return X(e);
+		case "stream": return Z(e);
+	}
+}, $ = (e) => {
+	let t = e.input, n = t === void 0 ? {} : { input: t }, r = e.output, i = r === void 0 ? {} : { output: r };
+	if (e.kind === "query") return {
+		kind: "query",
+		source: e.source,
+		...n,
+		...i
+	};
+	if (e.kind === "action") return {
+		kind: "action",
+		...n,
+		...i
+	};
+	if (e.kind === "stream") return {
+		kind: "stream",
+		...n,
+		...i
+	};
+	let a = e.target, o = e.idempotencyScope === void 0 ? {} : { idempotencyScope: e.idempotencyScope }, s = e.serialize === void 0 ? {} : { serialize: e.serialize };
+	if (a === void 0) return {
+		kind: "mutation",
+		...n,
+		...i,
+		...o,
+		...s
+	};
+	let c = Array.isArray(a) ? a : [a];
+	return {
+		kind: "mutation",
+		...n,
+		...i,
+		...o,
+		...s,
+		targets: c.map((e) => ({
+			table: e.table,
+			op: e.op,
+			..."order" in e && e.order !== void 0 ? { order: e.order } : {},
+			..."shape" in e && e.shape !== void 0 ? { shape: e.shape } : {},
+			..."identify" in e && e.identify !== void 0 ? { identify: e.identify } : {},
+			..."path" in e && e.path !== void 0 ? { path: e.path } : {},
+			..."by" in e && e.by !== void 0 ? { by: e.by } : {},
+			..."match" in e && e.match !== void 0 ? { match: e.match } : {},
+			..."shapeItem" in e && e.shapeItem !== void 0 ? { shapeItem: e.shapeItem } : {},
+			..."relations" in e && e.relations !== void 0 ? { relations: e.relations } : {}
+		}))
+	};
+};
+//#endregion
+export { G as FRAMEWORK_WIRE_ERRORS, w as SERVICE_NAME_PATTERN, X as actionToRpc, P as defineAction, N as defineMutation, M as defineQuery, F as defineStream, A as hasAccessDecision, L as hasEnforcedGuard, k as isAuthenticatedGuard, S as isClientReachable, O as isPolicyGuard, C as isServiceReachable, b as isWireReachable, Y as mutationToRpc, $ as normalizeDescriptor, J as queryToRpc, Z as streamToRpc, Q as toRpc, x as wireAudienceOf, U as wireErrorUnion, q as withRpcTag, K as workflowWireErrorUnion };