@voltro/protocol 0.85.0 → 0.86.0

package/dist/publicApi.js

@@ -0,0 +1,344 @@
+import { schemaShape as e, shapeDigest as t } from "./schemaShape.js";
+import { encodeRestError as n, encodeRestSuccess as r, resolveRestFormat as i, restViewSchema as a, toSnakeCase as o } from "./restFormat.js";
+import { RestRouteError as s, defineRestRoute as c, requireAuthenticated as l, requireScope as u, response as ee, sse as d, sseFrame as f } from "./rest.js";
+import { Effect as p, Schema as m, SchemaGetter as h, SchemaIssue as g } from "effect";
+import * as _ from "effect/SchemaAST";
+//#region src/publicApi.ts
+var v = (e, t, n) => t.method ?? (t.resource !== void 0 && n !== void 0 ? S("", t, n).method : void 0) ?? (e === "query" ? "GET" : "POST"), y = (e, t, n) => C(t.path ?? (t.resource !== void 0 && n !== void 0 ? S(e, t, n).path : `/${t.version ?? "v1"}/${e.replace(/\./g, "/")}`)), b = (e) => {
+	let t = e.split("/").pop() ?? e;
+	return t.endsWith("ies") ? `${t.slice(0, -3)}y` : t.endsWith("ses") || t.endsWith("xes") ? t.slice(0, -2) : t.endsWith("s") ? t.slice(0, -1) : t;
+}, x = (e, t) => {
+	let n = t != null && (typeof t == "object" || typeof t == "function") && "ast" in t ? L(t) : void 0;
+	if (n === void 0) return;
+	let r = `${b(e)}Id`;
+	return n.has(r) ? r : n.has("id") ? "id" : void 0;
+}, S = (e, t, n) => {
+	let r = (t.resource ?? "").replace(/^\/+|\/+$/g, ""), i = `/${t.version ?? "v1"}/${r}`, a = x(r, n.input), o = a === void 0 ? i : `${i}/:${a}`, s = e.split(".").pop() ?? e, c = n.target?.op;
+	return n.kind === "query" || n.kind === "stream" ? {
+		method: "GET",
+		path: o
+	} : n.kind === "mutation" && c === "insert" ? {
+		method: "POST",
+		path: i
+	} : n.kind === "mutation" && c === "update" ? {
+		method: a === void 0 ? "POST" : "PATCH",
+		path: o
+	} : n.kind === "mutation" && c === "delete" ? {
+		method: a === void 0 ? "POST" : "DELETE",
+		path: o
+	} : {
+		method: "POST",
+		path: `${o}/${s}`
+	};
+}, C = (e) => e.replace(/\{([A-Za-z0-9_]+)\}/g, ":$1"), w = (e) => [...e.matchAll(/:([A-Za-z0-9_]+)/g)].map((e) => e[1]), T = (e) => {
+	if (_.isUnion(e)) {
+		let t = e.types.filter((e) => !_.isUndefined(e));
+		if (t.length === 1) return t[0];
+		if (t.length !== e.types.length) return new _.Union(t);
+	}
+	return e;
+}, E = /^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i, D = (e, t) => {
+	let n = T(t);
+	if (n.encoding !== void 0) return D(e, _.toEncoded(n));
+	if (_.isUnion(n)) {
+		for (let t of n.types) {
+			let n = D(e, t);
+			if (n !== e) return n;
+		}
+		return e;
+	}
+	if (_.isArrays(n)) {
+		let t = Array.isArray(e) ? e : e === void 0 ? void 0 : [e];
+		if (t === void 0) return e;
+		let r = n.rest[0] ?? n.elements[0];
+		return r === void 0 ? t : t.map((e) => D(e, r));
+	}
+	if (typeof e != "string") return e;
+	if (_.isNumber(n)) return E.test(e.trim()) ? Number(e) : e;
+	if (_.isBoolean(n)) return e === "true" || e !== "false" && e;
+	if (_.isLiteral(n)) {
+		let t = n.literal;
+		return typeof t == "number" && E.test(e.trim()) && Number(e) === t || typeof t == "boolean" && String(t) === e ? t : e;
+	}
+	return e;
+}, O = (e, t) => {
+	if (typeof e != "object" || !e || Array.isArray(e)) return e;
+	let n = T(_.toEncoded(t.ast));
+	if (!_.isObjects(n)) return e;
+	let r = { ...e };
+	for (let e of n.propertySignatures) {
+		let t = String(e.name);
+		t in r && (r[t] = D(r[t], e.type));
+	}
+	return r;
+}, k = (e) => {
+	let t = T(_.toEncoded(e.ast));
+	if (!_.isObjects(t)) return (e) => e;
+	let n = t.propertySignatures, r = /* @__PURE__ */ new Map(), i = n.length >= 32 && n.every((e, t) => typeof e.name != "string" || e.name in Object.prototype || r.has(e.name) ? !1 : (r.set(e.name, {
+		type: e.type,
+		order: t
+	}), !0));
+	return (e) => {
+		if (typeof e != "object" || !e || Array.isArray(e)) return e;
+		let t = { ...e }, a = i ? Object.keys(t) : void 0;
+		if (a !== void 0 && a.length * 4 < n.length) {
+			let e = [];
+			for (let t of a) {
+				let n = r.get(t);
+				n !== void 0 && e.push({
+					key: t,
+					...n
+				});
+			}
+			e.sort((e, t) => e.order - t.order);
+			for (let { key: n, type: r } of e) t[n] = D(t[n], r);
+		} else for (let e of n) {
+			let n = String(e.name);
+			n in t && (t[n] = D(t[n], e.type));
+		}
+		return t;
+	};
+}, A = (e) => {
+	let t = /* @__PURE__ */ new Set();
+	if (e === void 0) return t;
+	let n = (e) => {
+		if (_.isUnion(e)) for (let t of e.types) n(t);
+		else if (e.encoding !== void 0 && n(_.toEncoded(e)), _.isObjects(e)) {
+			let n = e.propertySignatures.find((e) => e.name === "_tag");
+			n !== void 0 && _.isLiteral(n.type) && typeof n.type.literal == "string" && t.add(n.type.literal);
+		}
+	};
+	return n(e.ast), t;
+}, j = (e, t, n) => {
+	if (n !== void 0) try {
+		let r = m.encodeUnknownSync(n)(e);
+		if (typeof r == "object" && r) return {
+			error: t,
+			...r
+		};
+	} catch {}
+	let r = { error: t };
+	for (let [t, n] of Object.entries(e)) t !== "stack" && t !== "_tag" && (r[t] = n);
+	return r;
+}, M = (e, t, n, r = []) => N(e, t, n, r, A), N = (e, t, n, r, i) => {
+	if (typeof e != "object" || !e) return e;
+	let a = e._tag;
+	if (typeof a != "string" || a === "ScopeError" || a === "NoSuchResource") return e;
+	if (i(t.error).has(a)) {
+		let r = n.errorStatus?.[a] ?? 422;
+		return new s(r, j(e, a, t.error));
+	}
+	let o = r.find((e) => i(e.schema).has(a));
+	if (o === void 0) return e;
+	let c = n.errorStatus?.[a] ?? o.rest?.status ?? 422, l = o.rest?.headers?.(e);
+	return new s(c, j(e, a, o.schema), l);
+}, P = (e, t, r, i, a, o, c) => {
+	let l = N(e, t, r, i, c);
+	if (!(l instanceof s) || a.errors === "tagged" && a.encodeError === void 0) return l;
+	let { error: u, _tag: ee, ...d } = l.body, f = typeof d.message == "string" ? d.message : typeof d.reason == "string" ? d.reason : "", p = n(a, {
+		status: l.status,
+		tag: u,
+		message: f,
+		fields: d
+	}, {
+		...o,
+		status: l.status
+	});
+	return new s(l.status, p.body, {
+		...l.headers ?? {},
+		...p.headers ?? {}
+	}, p.contentType);
+}, F = (e, t) => {
+	if (e === void 0) return;
+	let n = _.isUnion(e.ast) ? e.ast.types : [e.ast];
+	for (let e of n) {
+		let n = m.make(e);
+		if (A(n).has(t)) return n;
+	}
+}, I = (e) => e.split(".").map((e, t) => t === 0 ? e : e.charAt(0).toUpperCase() + e.slice(1)).join("").replace(/[^A-Za-z0-9_]/g, "_"), L = (e) => {
+	let t = T(_.toEncoded(e.ast));
+	return _.isObjects(t) && t.indexSignatures.length === 0 ? new Set(t.propertySignatures.map((e) => String(e.name))) : void 0;
+}, R = (e, t) => e === t || JSON.stringify(e) === JSON.stringify(t), te = (e) => {
+	let t = T(_.toEncoded(e.ast)), n = _.isObjects(t) ? new Map(t.propertySignatures.map((e) => [String(e.name), e.type])) : /* @__PURE__ */ new Map();
+	return (e) => {
+		let t = {};
+		for (let [r, i] of Object.entries(e)) {
+			let e = n.get(r);
+			t[r] = e === void 0 ? i : D(i, e);
+		}
+		return t;
+	};
+}, z = (e, t) => {
+	if (e !== void 0) {
+		try {
+			return m.encodeUnknownSync(t)(e);
+		} catch {}
+		try {
+			return m.decodeUnknownSync(t)(e), e;
+		} catch {}
+		return e;
+	}
+}, B = (e, t, n) => ({
+	...e.request === void 0 ? {} : { request: z(e.request, t) },
+	...e.response === void 0 ? {} : { response: z(e.response, n) }
+}), ne = () => (e) => {
+	if (e.subject.type !== "anonymous") return;
+	let t = e.subject.credentialRejected;
+	return t === void 0 ? void 0 : {
+		status: 401,
+		message: t
+	};
+}, V = (e, t, n, s = {}) => {
+	let b = e.publicApi;
+	if (b === void 0) throw Error(`publicApiRoute: descriptor '${e.name}' has no publicApi annotation`);
+	let x = i(s.profile, b.format), S = s.pluginErrors ?? [], C = /* @__PURE__ */ new WeakMap(), T = (e) => {
+		if (e === void 0) return /* @__PURE__ */ new Set();
+		let t = C.get(e.ast);
+		if (t !== void 0) return t;
+		let n = A(e);
+		return C.set(e.ast, n), n;
+	}, E = /* @__PURE__ */ new WeakMap(), D = (e, t) => {
+		if (e === void 0) return;
+		let n = E.get(e.ast);
+		if (n === void 0) {
+			let t = /* @__PURE__ */ new Map();
+			for (let n of _.isUnion(e.ast) ? e.ast.types : [e.ast]) {
+				let e = m.make(n);
+				for (let n of T(e)) t.has(n) || t.set(n, e);
+			}
+			n = t, E.set(e.ast, n);
+		}
+		return n.get(t);
+	}, O = {
+		kind: e.kind,
+		input: e.input,
+		target: e.target
+	}, j = v(e.kind, b, O), M = (e) => x.naming === "snake_case" ? o(e) : e, N = y(e.name, b, O), F = N.replace(/:([A-Za-z0-9_]+)/g, (e, t) => `:${M(t)}`), z = w(F), V = a(e.input, x), H = k(V), U = te(V), W = L(V);
+	if (W !== void 0) {
+		for (let t of z) if (!W.has(t)) throw Error(`publicApi: descriptor '${e.name}' — path '${N}' binds ':${t}', and the input declares no field of that name` + (W.size > 0 ? ` (fields: ${[...W].join(", ")})` : " (the input declares no fields)"));
+	}
+	let G = a(e.output, x), re = m.Struct({ value: V }), K = j !== "GET" && W === void 0;
+	if (j !== "GET" && W !== void 0) {
+		let e = z.length >= 32 ? new Set(z) : void 0;
+		for (let t of W) if (!(e?.has(t) ?? z.includes(t))) {
+			K = !0;
+			break;
+		}
+	}
+	let q = {
+		query: m.Unknown,
+		params: m.Unknown,
+		form: m.Boolean
+	}, ie = (K ? m.Struct({
+		...q,
+		body: m.Unknown
+	}) : m.Struct(q)).pipe(m.decodeTo(re, {
+		decode: h.transformEffect((e) => {
+			let t = "body" in e ? e.body : void 0, n = j === "GET" ? H(e.query) : e.form ? H(t ?? {}) : t ?? {}, r = typeof e.params == "object" && e.params !== null ? U(e.params) : {};
+			if (typeof n != "object" || !n || Array.isArray(n)) return p.succeed({ value: n });
+			let i = n, a = Object.keys(r), o = 0;
+			for (let e of a) e in i && !R(i[e], r[e]) && (a[o++] = e);
+			if (a.length = o, a.length > 0) {
+				let t = j === "GET" ? "query string" : "body";
+				return p.fail(new g.InvalidValue({ message: `${a.map((e) => `'${e}'`).join(", ")} ${a.length === 1 ? "is" : "are"} bound by the path and sent with another value in the ${t}` }, e));
+			}
+			return p.succeed({ value: {
+				...i,
+				...r
+			} });
+		}),
+		encode: h.transform((e) => e)
+	})), ae = [
+		ne(),
+		...e.openAccess === void 0 ? [l()] : [],
+		...(b.scopes ?? []).map((e) => u(e))
+	], J = (() => {
+		let t = e.source;
+		return typeof t == "string" ? t : Array.isArray(t) ? t[0] : void 0;
+	})(), Y = (t, n = 200) => ({
+		tag: e.name,
+		method: t.method,
+		path: t.path,
+		query: t.query,
+		source: J,
+		status: n
+	}), X = b.stream === "sse" && e.kind === "query" && n !== void 0, oe = m.encodeUnknownEffect(G), se = X ? (e, t) => d((r) => n(e.value, t, (e) => {
+		r(f(String(e._tag ?? "message"), e));
+	})) : async (n, i) => {
+		let a;
+		try {
+			a = await t(n.value, i);
+		} catch (t) {
+			throw P(t, e, b, S, x, Y(i), T);
+		}
+		let o = await p.runPromise(oe(a)), s = r(x, o, Y(i));
+		return ee(s.body, {
+			...s.headers === void 0 ? {} : { headers: s.headers },
+			...s.contentType === void 0 ? {} : { contentType: s.contentType }
+		});
+	}, Z = e.error, Q = T(Z), ce = [...Q], $ = [];
+	for (let e of ce) {
+		let t = D(Z, e);
+		t !== void 0 && $.push({
+			status: b.errorStatus?.[e] ?? 422,
+			tag: e,
+			schema: t
+		});
+	}
+	for (let e of S) for (let t of T(e.schema)) {
+		if (Q.has(t)) continue;
+		let n = b.errorStatus?.[t] ?? e.rest?.status;
+		if (n === void 0) continue;
+		let r = D(e.schema, t) ?? e.schema;
+		$.push({
+			status: n,
+			tag: t,
+			schema: r
+		});
+	}
+	let le = b.security === !1 ? "none" : b.security ?? (e.openAccess === void 0 ? "required" : "optional"), ue = {
+		tag: e.name,
+		kind: e.kind,
+		version: b.version ?? "v1",
+		security: le,
+		idempotent: b.idempotent === !0,
+		input: V,
+		pathParams: z,
+		output: G,
+		source: J,
+		errorResponses: $,
+		format: x
+	};
+	return c({
+		method: j,
+		path: F,
+		input: ie,
+		output: m.Unknown,
+		handler: se,
+		...X ? { streaming: !0 } : {},
+		guards: ae,
+		operationId: b.operationId ?? I(e.name),
+		tags: b.tags ?? [e.name.split(".")[0] ?? e.name],
+		projection: ue,
+		...x.etag && j === "GET" && !X ? { etag: !0 } : {},
+		...b.cache !== void 0 && j === "GET" && !X ? { cache: b.cache } : {},
+		...b.example === void 0 ? {} : { example: B(b.example, V, G) },
+		...b.summary === void 0 ? {} : { summary: b.summary },
+		...b.description === void 0 ? {} : { description: b.description },
+		...b.deprecated === void 0 ? {} : { deprecated: b.deprecated },
+		...b.sunset === void 0 ? {} : { sunset: b.sunset }
+	});
+}, H = (e, t = {}) => e.filter((e) => e.descriptor.publicApi !== void 0).map((e) => V(e.descriptor, e.invoke, e.subscribe, t)).sort((e, t) => e.path.localeCompare(t.path)), U = (n) => t(n.filter((e) => e.projection !== void 0).map((t) => {
+	let n = t.projection, r = {
+		tag: n.tag,
+		method: t.method,
+		path: t.path,
+		pathParams: n.pathParams,
+		version: n.version,
+		security: n.security,
+		errors: [...n.errorResponses].map((e) => `${e.status}:${e.tag}`).sort()
+	};
+	return `${JSON.stringify(r)} ${e(n.input.ast)} ${e(n.output.ast)}`;
+}).sort().join("\n"));
+//#endregion
+export { O as coerceQueryObject, D as coerceQueryValue, H as collectPublicApiRoutes, A as declaredErrorTags, v as derivePublicMethod, y as derivePublicPath, S as deriveResource, F as errorMemberSchema, C as normalizePathParams, I as operationIdOf, w as pathParamNames, M as projectedFailure, V as publicApiRoute, U as publicSurfaceDigest, x as resourceIdField, B as wireExample };

package/dist/reactivityChannel.js

@@ -0,0 +1,34 @@
+//#region src/reactivityChannel.ts
+var e = "channel:", t = Symbol.for("@voltro/protocol/reactivityChannels"), n = globalThis, r = n[t] ?? (n[t] = /* @__PURE__ */ new Map()), i = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$/, a = (t) => {
+	if (!i.test(t)) throw Error(`reactivityChannel('${t}'): invalid channel name.\n  Use lowercase kebab segments separated by dots — \`presence\`, \`job-queue\`,
+  \`billing.usage\`. A \`:\` is refused because it is the namespace separator in
+  the routing key (\`${e}<name>\`), and an uppercase letter is\n  refused because a key that differs only by case reads as one channel and
+  routes as two.`);
+	let n = r.get(t);
+	if (n !== void 0) return n;
+	let a = `${e}${t}`, o = Object.freeze({
+		kind: "reactivity-channel",
+		name: t,
+		key: a,
+		toString: () => a
+	});
+	return r.set(t, o), o;
+}, o = (e) => typeof e == "object" && !!e && e.kind === "reactivity-channel", s = (t) => t.startsWith(e), c = () => new Set([...r.values()].map((e) => e.key)), l = (e) => o(e) ? e.key : e, u = (e) => e === void 0 ? [] : Array.isArray(e) ? e.map(l) : [l(e)], d = (e) => e === void 0 ? void 0 : Array.isArray(e) ? e.map(l) : l(e), f = (e) => {
+	let t = c(), n = [];
+	for (let r of e) for (let e of u(r.source)) s(e) && !t.has(e) && n.push({
+		procedure: r.name,
+		key: e
+	});
+	return n;
+}, p = (e, t) => {
+	let n = e?.injectExternalChange;
+	return n !== void 0 && (n.call(e, {
+		table: t.key,
+		op: "update",
+		new: {},
+		old: {},
+		origin: "inline"
+	}), !0);
+};
+//#endregion
+export { e as REACTIVITY_CHANNEL_PREFIX, c as declaredReactivityChannelKeys, o as isReactivityChannel, s as isReactivityChannelKey, d as normalizeSource, p as publishReactivity, a as reactivityChannel, u as sourceKeys, f as undeclaredChannelKeys };

package/dist/rest.d.ts

@@ -1,5 +1,6 @@
 import * as AST from 'effect/SchemaAST';
 import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
 import { Schema } from 'effect';
 
 declare interface ActionProcedureDescriptor<Name extends string, Input extends Schema.Top, Output extends Schema.Top, Error extends Schema.Top> {
@@ -589,6 +590,9 @@ declare interface PluginHttpRoute {
      * handler branches on: exempting `/saml` exempts `POST /saml/anything`.
      */
     readonly originGuard?: 'exempt';
+    readonly cors?: RestCors;
+    /** Bearer-only routes must discard cookie authority before authentication. */
+    readonly credentials?: 'bearer';
 }
 
 /**
@@ -1225,6 +1229,22 @@ export declare interface RestCache {
     readonly audience?: (output: unknown, input: unknown, subject: Subject) => 'public' | 'private';
 }
 
+/** Cross-origin browser access for one route. Origins are exact, including opaque `null`. */
+export declare interface RestCors {
+    readonly origins: ReadonlyArray<string>;
+    readonly headers?: ReadonlyArray<string>;
+    readonly methods?: ReadonlyArray<RestMethod>;
+    /** Preflight cache lifetime in seconds. */
+    readonly maxAge?: number;
+    readonly exposeHeaders?: ReadonlyArray<string>;
+}
+
+/** Shared by the descriptor adapter and listener, including early transport refusals. */
+export declare const restCorsHeaders: (cors: RestCors | undefined, origin: string | undefined) => Record<string, string>;
+
+/** Preflight never authenticates, consumes quota, reads a body or executes a handler. */
+export declare const restCorsPreflight: (cors: RestCors, method: string, headers: Readonly<Record<string, string>>) => PluginHttpRouteResult;
+
 export declare type RestDates = 'iso' | 'epoch-ms';
 
 export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
@@ -1327,6 +1347,13 @@ export declare type RestNaming = 'camelCase' | 'snake_case';
 
 export declare type RestPagination = 'link-header' | 'body-cursor';
 
+/** Uses the mounted rate-limit plugin's store, algorithms and dynamic policy. */
+export declare interface RestRateLimit {
+    readonly limit: number;
+    readonly window: string;
+    readonly by?: 'subject' | 'tenant' | 'apiKey' | 'ip' | 'global';
+}
+
 /** A schema-encoded REST body with an application-selected HTTP status and
  *  response headers. The marker keeps ordinary domain objects unambiguous.
  *  `output` still validates/encodes `body`; use `Schema.Void` with a 204 when
@@ -1425,6 +1452,10 @@ export declare interface RestRouteDescriptor<I, O> {
      */
     readonly version?: `v${number}`;
     readonly guards?: ReadonlyArray<RestGuard>;
+    readonly cors?: RestCors;
+    /** Only an explicit bearer header may authenticate; cookies are removed before auth and context construction. */
+    readonly credentials?: 'bearer';
+    readonly rateLimit?: RestRateLimit;
     /**
      * This route STREAMS (Server-Sent Events) rather than resolving one value — its
      * handler returns `sse(...)`. Declared on the descriptor, not left implicit in
@@ -1510,6 +1541,8 @@ export declare const restRoutesToHttpRoutes: (routes: ReadonlyArray<RestRouteDes
  * auth subject + the bound DataStore.
  */
 export declare interface RestServeBindings {
+    /** Bound once from the app's mounted rate-limit plugin. */
+    readonly rateLimit?: (policy: RestRateLimit, ctx: RestRouteContext, route: RestRouteDescriptor<any, any>) => Effect.Effect<void, unknown>;
     /** Resolve the calling subject from the request headers. */
     readonly resolveSubject?: (headers: Readonly<Record<string, string>>) => Subject | Promise<Subject>;
     /** The bound framework DataStore. */