@protobase/server 0.50.1 → 0.51.1

package/dist/assistant/delete-record-tool.js

@@ -1,7 +1,14 @@
 import { defineTool } from "./tools.js";
 import { keyOf, keyParameter, refused, resourceOf } from "./record-tool-args.js";
+import { deleteApproval } from "./write-prompts.js";
+import { approvalTexts, recordBefore } from "./record-before.js";
 import { onlyNote, outside, resourceParameterFor } from "./write-tool-limits.js";
 //#region src/assistant/delete-record-tool.ts
+/**
+* `delete_record`: deleting one record as the caller, through the REST API's delete path (its access rules, ETag check,
+* write hooks and soft delete), after the user approves it. Before asking it only reads: the resource's config and the
+* record the approval names, since MCP runs it again from the start with the user's answer.
+*/
 const parameterNames = [
 	"resource",
 	"key",
@@ -16,15 +23,6 @@ const deleteKeyOf = (value) => {
 };
 const etagOf = (value) => typeof value === "string" && /^"[\x21\x23-\x2b\x2d-\x7e]+"$/.test(value) ? value : void 0;
 const usage = "Pass only the resource, key and etag as { \"resource\": \"<name>\", \"key\": \"<key>\", \"etag\": \"<the etag get_record gave>\" }; nothing was deleted.";
-const approvalOf = (resource, shownKey, softDelete) => ({
-	title: softDelete ? `Delete this ${resource} record? It can be restored: the record is kept, marked deleted.` : `Delete this ${resource} record for good? This cannot be undone: the record is removed.`,
-	fields: [{
-		label: "Key",
-		value: shownKey
-	}],
-	tone: softDelete ? "warning" : "danger",
-	approveLabel: softDelete ? "Delete" : "Delete for good"
-});
 /** Deletes one record by its key and ETag once the user approves it, under the caller's access rules. */
 const deleteRecordTool = (input = {}) => defineTool({
 	name: "delete_record",
@@ -60,8 +58,10 @@ const deleteRecordTool = (input = {}) => defineTool({
 		if (refusal) return refusal;
 		const softDelete = await context.records.softDeleteField(resource).then((field) => ({ field }), refused);
 		if (typeof softDelete === "string") return softDelete;
-		const shownKey = Array.isArray(key) ? key.join(",") : String(key);
-		const answer = await context.approve(approvalOf(resource, shownKey, softDelete.field));
+		const before = await recordBefore(context, resource, key, etag);
+		if (typeof before === "string") return before;
+		const { text, described } = await approvalTexts(context, resource);
+		const answer = await context.approve(deleteApproval(text, described, key, before?.record ?? {}, softDelete.field !== void 0));
 		if (answer !== "approved") return `The user did not approve this delete (${answer}); nothing was deleted.`;
 		const deleted = () => JSON.stringify({
 			deleted: true,

package/dist/assistant/record-before.js

@@ -0,0 +1,20 @@
+import { HttpProblem, preconditionFailed } from "../problem.js";
+import { ifMatchSatisfied } from "../etag.js";
+import { refused } from "./record-tool-args.js";
+import { writeText } from "./write-messages.js";
+import { describedResource } from "./write-prompts.js";
+//#region src/assistant/record-before.ts
+const hidden = (error) => error instanceof HttpProblem && (error.status === 403 || error.status === 404);
+/**
+* The record as the caller reads it now, for what an approval names and shows before a write: undefined when they may
+* not read it. A record changed since `etag` is refused before asking, as the write would refuse it after the user
+* approved; so is any other refusal of the read, as the model's to read.
+*/
+const recordBefore = (context, resource, key, etag) => context.records.get(resource, key).then((current) => etag && !ifMatchSatisfied(etag, current.etag) ? refused(preconditionFailed("The record changed since it was read; fetch it again")) : current, (error) => hidden(error) ? void 0 : refused(error));
+/** What an approval is written with: the texts of the user's language, and the resource as the caller may read it. */
+const approvalTexts = async (context, resource) => ({
+	text: writeText(context.locale ?? "en"),
+	described: describedResource(await context.resources(), resource)
+});
+//#endregion
+export { approvalTexts, recordBefore };

package/dist/assistant/tools.d.ts

@@ -2,6 +2,7 @@ import { Session } from "../types.js";
 import { ToolRecords } from "./records.js";
 import { Conversation } from "./conversations.js";
 import { ApprovalAnswer, ApprovalRequest } from "./approval.js";
+import { Locale } from "@protobase/schema/internal";
 import { AssistantPart, ResourceModel, ViewModel } from "@protobase/schema";
 //#region src/assistant/tools.d.ts
 /** The resources a caller may read, each restricted to their fields, with their views. */
@@ -11,6 +12,8 @@ export type ReadableResources = {
 };
 export type ToolContext = {
   session: Session;
+  /** The language the user reads, for the texts a tool shows them such as its approvals; English when absent. */
+  locale?: Locale;
   /** The dock's conversation; absent over MCP. */
   conversation?: Conversation;
   /** Adds a part, such as a table of results, to the assistant message the turn is writing. */

package/dist/assistant/write-messages.js

@@ -0,0 +1,41 @@
+import { defineMessages } from "../locale/messages.js";
+//#region src/assistant/write-messages.ts
+/** The texts of the approvals the write tools ask for, which the user reads in their client. */
+const writeText = defineMessages({
+	en: {
+		createTitle: (resource, title) => `Create ${resource}${title === void 0 ? "" : ` "${title}"`}?`,
+		updateTitle: (record) => `Update ${record}?`,
+		deleteTitle: (record) => `Delete ${record}?`,
+		create: "Create",
+		update: "Update",
+		delete: "Delete",
+		deleteForGood: "Delete for good",
+		reject: "Cancel",
+		noChanges: "No field changes.",
+		restorable: "It can be restored: the record is kept, marked deleted.",
+		permanent: "This cannot be undone: the record is removed for good.",
+		empty: "empty",
+		hidden: "hidden",
+		yes: "Yes",
+		no: "No"
+	},
+	nl: {
+		createTitle: (resource, title) => `${resource}${title === void 0 ? "" : ` "${title}"`} aanmaken?`,
+		updateTitle: (record) => `${record} bijwerken?`,
+		deleteTitle: (record) => `${record} verwijderen?`,
+		create: "Aanmaken",
+		update: "Bijwerken",
+		delete: "Verwijderen",
+		deleteForGood: "Definitief verwijderen",
+		reject: "Annuleren",
+		noChanges: "Er verandert geen veld.",
+		restorable: "Het kan worden teruggezet: het record blijft bewaard, gemarkeerd als verwijderd.",
+		permanent: "Dit kan niet ongedaan worden gemaakt: het record wordt definitief verwijderd.",
+		empty: "leeg",
+		hidden: "verborgen",
+		yes: "Ja",
+		no: "Nee"
+	}
+});
+//#endregion
+export { writeText };

package/dist/assistant/write-prompts.js

@@ -0,0 +1,79 @@
+import { humanize, recordTitle } from "@protobase/schema/internal";
+import { enumLabel } from "@protobase/schema";
+//#region src/assistant/write-prompts.ts
+const describedResource = (readable, name) => ({
+	name,
+	model: readable.models.find((model) => model.name === name),
+	view: readable.views.find((view) => view.resource === name)
+});
+const hiddenCharacters = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+const longest = 200;
+/** `text` on one line with nothing hidden in it, cut at 200 characters. */
+const shown = (text) => {
+	const line = text.replace(hiddenCharacters, " ");
+	return line.length > longest ? `${line.slice(0, 199)}…` : line;
+};
+const resourceLabel = ({ name, view }) => shown(view?.names?.singular ?? humanize(name));
+const fieldLabel = ({ view }, name) => shown(view?.fields[name]?.label ?? humanize(name));
+const shownValue = (text, described, name, value) => {
+	const field = described.model?.fields[name];
+	if (field?.sensitive) return text.hidden;
+	if (value === null || value === void 0) return text.empty;
+	if (typeof value === "boolean") return value ? text.yes : text.no;
+	if (field?.type === "enum" && typeof value === "string") return shown(enumLabel(value, described.view?.fields[name]?.valueLabels));
+	if (typeof value === "string") return shown(value);
+	if (typeof value === "number" || typeof value === "bigint") return String(value);
+	return shown(JSON.stringify(value));
+};
+/** `Task #42 "Fix the sign-in lockout"`: the resource's label, the record's key, and its title when it has one apart from the key. */
+const recordName = (described, key, record) => {
+	const shownKey = shown(Array.isArray(key) ? key.join(",") : String(key));
+	const title = described.model ? shown(recordTitle(described.model, described.view, record, shownKey)) : shownKey;
+	return `${resourceLabel(described)} #${shownKey}${title === shownKey ? "" : ` "${title}"`}`;
+};
+const titleOfNew = (described, data) => {
+	if (!described.model) return void 0;
+	const title = shown(recordTitle(described.model, described.view, data, ""));
+	return title === "" ? void 0 : title;
+};
+const same = (before, after) => JSON.stringify(before ?? null) === JSON.stringify(after ?? null);
+/** `Create Task "Fix the sign-in lockout"?`, with each field the new record is given by its label. */
+const createApproval = (text, described, data) => ({
+	title: text.createTitle(resourceLabel(described), titleOfNew(described, data)),
+	fields: Object.entries(data).map(([name, value]) => ({
+		label: fieldLabel(described, name),
+		value: shownValue(text, described, name, value)
+	})),
+	approveLabel: text.create,
+	rejectLabel: text.reject
+});
+/**
+* `Update Task #42 "Fix the sign-in lockout"?`, with each field that changes as `In flight -> Done`. A field the
+* caller cannot read before, such as a sensitive one, shows its new value alone.
+*/
+const updateApproval = (text, described, key, current, data) => {
+	const fields = Object.entries(data).filter(([name, value]) => !Object.hasOwn(current, name) || !same(current[name], value)).map(([name, value]) => {
+		const after = shownValue(text, described, name, value);
+		const before = Object.hasOwn(current, name) ? `${shownValue(text, described, name, current[name])} -> ` : "";
+		return {
+			label: fieldLabel(described, name),
+			value: `${before}${after}`
+		};
+	});
+	return {
+		title: text.updateTitle(recordName(described, key, current)),
+		...fields.length > 0 ? { fields } : { body: text.noChanges },
+		approveLabel: text.update,
+		rejectLabel: text.reject
+	};
+};
+/** `Delete Task #42 "Fix the sign-in lockout"?`, saying whether it can be restored (a soft delete) or is gone for good. */
+const deleteApproval = (text, described, key, current, restorable) => ({
+	title: text.deleteTitle(recordName(described, key, current)),
+	body: restorable ? text.restorable : text.permanent,
+	tone: restorable ? "warning" : "danger",
+	approveLabel: restorable ? text.delete : text.deleteForGood,
+	rejectLabel: text.reject
+});
+//#endregion
+export { createApproval, deleteApproval, describedResource, updateApproval };

package/dist/assistant/write-record-tools.js

@@ -1,5 +1,7 @@
 import { defineTool } from "./tools.js";
 import { keyOf, keyParameter, refused, resourceOf } from "./record-tool-args.js";
+import { createApproval, updateApproval } from "./write-prompts.js";
+import { approvalTexts, recordBefore } from "./record-before.js";
 import { forbiddenText, notApproved, onlyNote, outside, resourceParameterFor } from "./write-tool-limits.js";
 import { deleteRecordTool } from "./delete-record-tool.js";
 //#region src/assistant/write-record-tools.ts
@@ -32,11 +34,8 @@ const createRecordTool = (input = {}) => defineTool({
 		if (!resource || !data) return "Pass the resource and data as { \"resource\": \"<name>\", \"data\": { \"<field>\": <value> } }.";
 		const refusal = outside(input, resource);
 		if (refusal) return refusal;
-		const answer = await context.approve({
-			title: `Create a record in ${resource}?`,
-			code: JSON.stringify(data, null, 2),
-			approveLabel: "Create"
-		});
+		const { text, described } = await approvalTexts(context, resource);
+		const answer = await context.approve(createApproval(text, described, data));
 		if (answer !== "approved") return notApproved(answer);
 		return context.records.create(resource, data).then((record) => JSON.stringify(record), refused);
 	}
@@ -76,14 +75,12 @@ const updateRecordTool = (input = {}) => defineTool({
 		const softDelete = await context.records.softDeleteField(resource).then((field) => ({ field }), refused);
 		if (typeof softDelete === "string") return softDelete;
 		if (softDelete.field && Object.hasOwn(data, softDelete.field)) return forbiddenText(`update_record does not set ${softDelete.field}, which deleting sets; delete with delete_record. Nothing was written.`);
-		const shownKey = Array.isArray(key) ? key.join(",") : String(key);
-		const answer = await context.approve({
-			title: `Update ${resource} ${shownKey}?`,
-			code: JSON.stringify(data, null, 2),
-			approveLabel: "Update"
-		});
-		if (answer !== "approved") return notApproved(answer);
 		const etag = typeof args.etag === "string" && args.etag ? args.etag : void 0;
+		const before = await recordBefore(context, resource, key, etag);
+		if (typeof before === "string") return before;
+		const { text, described } = await approvalTexts(context, resource);
+		const answer = await context.approve(updateApproval(text, described, key, before?.record ?? {}, data));
+		if (answer !== "approved") return notApproved(answer);
 		return context.records.update(resource, key, data, { etag }).then((record) => JSON.stringify(record), refused);
 	}
 });

package/dist/create-admin.js

@@ -80,6 +80,7 @@ import { functionRoutes } from "./functions/routes.js";
 import { supabaseFunctionRoutes } from "./functions/supabase-routes.js";
 import { upgradeAuthenticator } from "./functions/upgrade-caller.js";
 import { localeSetting } from "./locale/locale-option.js";
+import { requestLocale } from "./locale/request-locale.js";
 import { mapSettings } from "./maps/map-settings.js";
 import { pluginOptions, pluginsBeforeSignIn } from "./plugins/plugin-settings.js";
 import { runtimeUrl } from "./runtime/runtime-settings.js";
@@ -329,17 +330,20 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 			writes
 		});
 		const approvals = mcpApprovals();
-		const server = (session) => mcpServer({
-			info: {
-				name: appName,
-				version: "1.0.0"
-			},
-			tools: tools(session),
-			context: mcpToolContext(deps, meta, session),
-			report,
-			rolesWithoutApproval: rolesWithoutApproval(writes),
-			approvals
-		});
+		const server = (session, request) => {
+			const context = mcpToolContext(deps, meta, session, request ? requestLocale(locale, request) : locale);
+			return mcpServer({
+				info: {
+					name: appName,
+					version: "1.0.0"
+				},
+				tools: tools(session),
+				context,
+				report,
+				rolesWithoutApproval: rolesWithoutApproval(writes),
+				approvals
+			});
+		};
 		mcpRoutes(app, {
 			path: auth.mcp.path,
 			handler: mcpHandler({

package/dist/locale/messages.js

@@ -0,0 +1,8 @@
+//#region src/locale/messages.ts
+/**
+* An area's built-in texts in every language the screens come in: the lookup gives those of one locale, as the server
+* has no single active one. Dutch must translate every English text, which the types check.
+*/
+const defineMessages = (catalogue) => (locale) => catalogue[locale];
+//#endregion
+export { defineMessages };

package/dist/locale/request-locale.js

@@ -0,0 +1,14 @@
+import { pickLocale } from "@protobase/schema/internal";
+//#region src/locale/request-locale.ts
+const acceptedTags = (header) => header.split(",").map((entry) => {
+	const [tag = "", ...params] = entry.trim().split(";");
+	const weight = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+	return {
+		tag: tag.trim(),
+		q: weight ? Number(weight.slice(2)) : 1
+	};
+}).filter(({ tag, q }) => tag !== "" && tag !== "*" && q > 0).toSorted((a, b) => b.q - a.q).map(({ tag }) => tag);
+/** The language a request's user reads: the app's (`options.locale`) when it sets one, else their `Accept-Language`'s. */
+const requestLocale = (appLocale, request) => appLocale ?? pickLocale(acceptedTags(request.headers.get("accept-language") ?? ""));
+//#endregion
+export { requestLocale };

package/dist/mcp/mcp-approval.js

@@ -1,3 +1,4 @@
+import { defineMessages } from "../locale/messages.js";
 import { inputRequired, inputResponse } from "@modelcontextprotocol/server";
 //#region src/mcp/mcp-approval.ts
 /** Thrown by `approve` over MCP when the request carries no answer yet: the server then asks the client for one. */
@@ -41,20 +42,30 @@ const messageOf = (request) => [
 	request.fields?.map(({ label, value }) => `${label}: ${value}`).join("\n"),
 	request.code
 ].filter(Boolean).join("\n\n");
-const cannotAsk = {
+const text = defineMessages({
+	en: {
+		cannotAsk: "This client cannot ask you to approve a change, so nothing was written; use a client that supports MCP elicitation.",
+		approve: "Approve"
+	},
+	nl: {
+		cannotAsk: "Deze client kan je niet vragen een wijziging goed te keuren, dus er is niets opgeslagen; gebruik een client die MCP-elicitation ondersteunt.",
+		approve: "Goedkeuren"
+	}
+});
+const cannotAsk = (locale) => ({
 	content: [{
 		type: "text",
-		text: "This client cannot ask you to approve a change, so nothing was written; use a client that supports MCP elicitation."
+		text: text(locale).cannotAsk
 	}],
 	isError: true
-};
+});
 /**
 * The answer to a call whose tool asked for approval: a form asking the user to approve `request` when the client can
-* show one, filed under the nonce of the state `ask` mints for the call, else a refusal. A 2025-protocol request
-* declares no capabilities per request, so it is always refused.
+* show one, filed under the nonce of the state `ask` mints for the call, else a refusal in `locale`. A 2025-protocol
+* request declares no capabilities per request, so it is always refused.
 */
-const approvalAsked = async (request, capabilities, ask) => {
-	if (!asksForms(capabilities)) return cannotAsk;
+const approvalAsked = async (request, capabilities, ask, locale = "en") => {
+	if (!asksForms(capabilities)) return cannotAsk(locale);
 	const { state, nonce } = await ask();
 	return inputRequired({
 		inputRequests: { [approvalKey(nonce)]: inputRequired.elicit({
@@ -63,7 +74,7 @@ const approvalAsked = async (request, capabilities, ask) => {
 				type: "object",
 				properties: { approve: {
 					type: "boolean",
-					title: request.approveLabel ?? "Approve"
+					title: request.approveLabel ?? text(locale).approve
 				} },
 				required: ["approve"]
 			}

package/dist/mcp/mcp-context.d.ts

@@ -2,10 +2,12 @@ import { Session } from "../types.js";
 import { Deps } from "../deps.js";
 import { ToolContext } from "../assistant/tools.js";
 import { Meta } from "../meta.js";
+import { Locale } from "@protobase/schema/internal";
 //#region src/mcp/mcp-context.d.ts
 /**
- * What tools get over MCP for `session`: its records and the resources it may read, under its access rules. Nothing
- * shows beside a tool's result, and `mcpServer` gives each call its own `approve`.
+ * What tools get over MCP for `session`: its records and the resources it may read, under its access rules, and
+ * `locale`, the language its approvals are asked in. Nothing shows beside a tool's result, and `mcpServer` gives each
+ * call its own `approve`.
  */
-export declare const mcpToolContext: (deps: Deps, meta: Pick<Meta, "forCaller">, session: Session) => Omit<ToolContext, "approve">;
+export declare const mcpToolContext: (deps: Deps, meta: Pick<Meta, "forCaller">, session: Session, locale?: Locale) => Omit<ToolContext, "approve">;
 //#endregion

package/dist/mcp/mcp-context.js

@@ -2,11 +2,13 @@ import { assistantRecords } from "../assistant/records.js";
 import { readableResources } from "../assistant/readable-resources.js";
 //#region src/mcp/mcp-context.ts
 /**
-* What tools get over MCP for `session`: its records and the resources it may read, under its access rules. Nothing
-* shows beside a tool's result, and `mcpServer` gives each call its own `approve`.
+* What tools get over MCP for `session`: its records and the resources it may read, under its access rules, and
+* `locale`, the language its approvals are asked in. Nothing shows beside a tool's result, and `mcpServer` gives each
+* call its own `approve`.
 */
-const mcpToolContext = (deps, meta, session) => ({
+const mcpToolContext = (deps, meta, session, locale) => ({
 	session,
+	...locale && { locale },
 	records: assistantRecords(deps, session),
 	resources: () => readableResources(meta, session),
 	show: () => {}

package/dist/mcp/mcp-handler.d.ts

@@ -3,8 +3,11 @@ import { McpGateInput } from "./mcp-gate.js";
 import { McpServer } from "@modelcontextprotocol/server";
 //#region src/mcp/mcp-handler.d.ts
 export type McpHandlerInput = McpGateInput & {
-  /** Builds the server for the caller of one request, such as `mcpServer(...)` with tools of your own registered on it. */
-  server: (session: Session) => McpServer | Promise<McpServer>;
+  /**
+   * Builds the server for the caller of one request, such as `mcpServer(...)` with tools of your own registered on it;
+   * `request` is the HTTP request it serves, such as for the language its user reads.
+   */
+  server: (session: Session, request: Request | undefined) => McpServer | Promise<McpServer>;
 };
 /**
  * The MCP endpoint as a fetch handler: refuses a request addressed to another host than the resource's, then one

package/dist/mcp/mcp-handler.js

@@ -9,7 +9,7 @@ import { createMcpHandler, hostHeaderValidationResponse } from "@modelcontextpro
 const mcpHandler = ({ server, ...gate }) => {
 	const hostname = new URL(gate.resource).hostname;
 	const admit = mcpGate(gate);
-	const handler = createMcpHandler((context) => server(sessionOf(context.authInfo)), { legacy: "stateless" });
+	const handler = createMcpHandler((context) => server(sessionOf(context.authInfo), context.requestInfo), { legacy: "stateless" });
 	return async (request) => {
 		const wrongHost = hostHeaderValidationResponse(request, [hostname]);
 		if (wrongHost) return wrongHost;

package/dist/mcp/mcp-server.js

@@ -70,7 +70,7 @@ const mcpServer = ({ info, tools, context, report, rolesWithoutApproval = [], ap
 			} catch (error) {
 				if (!(error instanceof ApprovalNeeded)) throw error;
 				const { scope, call } = bound();
-				return approvalAsked(error.request, capabilitiesOf(ctx.mcpReq.envelope), () => approvals.ask(scope, call));
+				return approvalAsked(error.request, capabilitiesOf(ctx.mcpReq.envelope), () => approvals.ask(scope, call), context.locale);
 			}
 		};
 		server.registerTool(tool.name, config, async (args, ctx) => {

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.50.1";
+var version = "0.51.1";
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.50.1",
+  "version": "0.51.1",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,9 +40,9 @@
     "@better-auth/passkey": "^1.7.12",
     "@better-auth/sso": "^1.7.12",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@protobase/layout": "0.50.1",
-    "@protobase/query": "0.50.1",
-    "@protobase/schema": "0.50.1",
+    "@protobase/layout": "0.51.1",
+    "@protobase/query": "0.51.1",
+    "@protobase/schema": "0.51.1",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",