@protobase/server 0.21.7 → 0.21.8

package/dist/check-views.js

@@ -6,9 +6,14 @@ import { chartErrors } from "./view-chart.js";
 import { mapDisplayErrors, mapErrors } from "./view-map.js";
 import { relatedColumnErrors } from "./view-related-column.js";
 import { editableErrors } from "./view-editable.js";
-import { actionInputErrors, addressErrors, addressPlaceholders, boardErrors, chartFields, displayFields, fieldRefsIn, hrefField, hrefPlaceholders, linkActionError } from "@protobase/schema/internal";
+import { actionInputErrors, addressErrors, addressPlaceholders, boardErrors, calendarErrors, chartFields, displayFields, fieldRefsIn, hrefField, hrefPlaceholders, linkActionError, promptError, promptFields } from "@protobase/schema/internal";
 //#region src/check-views.ts
 const linkFields = (run) => run?.kind !== "link" ? [] : "to" in run ? addressPlaceholders(run.to) : hrefPlaceholders(run.href);
+const actionFields = (run) => {
+	if (run?.kind === "update") return Object.keys(run.values);
+	if (run?.kind === "ai") return [run.writes, ...promptFields(run.prompt ?? "")];
+	return linkFields(run);
+};
 const sensitiveErrors = (view, model) => {
 	const sensitive = (name) => Boolean(model.fields[name]?.sensitive);
 	return [
@@ -26,7 +31,7 @@ const sensitiveErrors = (view, model) => {
 		["a map", view.layout.flatMap((item) => item.kind === "map" ? [item.latitude, item.longitude] : [])],
 		["a gallery", view.layout.flatMap((item) => item.kind === "gallery" && item.image !== void 0 ? [item.image] : [])],
 		["the recent records", view.nav?.recent ? [view.nav.recent.status] : []],
-		["an action", view.actions.flatMap((action) => action.run?.kind === "update" ? Object.keys(action.run.values) : linkFields(action.run))]
+		["an action", view.actions.flatMap((action) => actionFields(action.run))]
 	].flatMap(([place, names]) => [...new Set(names.filter(sensitive))].map((name) => `sensitive field "${name}" cannot be in ${place}`));
 };
 const valueLabelErrors = (view, model) => Object.entries(view.fields).flatMap(([name, hints]) => {
@@ -59,10 +64,22 @@ const linkErrors = (view, model, models, pages) => view.actions.flatMap(({ name,
 		source: model
 	}).map((error) => `action "${name}": ${error}`) : [];
 });
+const aiActionErrors = (view, model) => view.actions.flatMap(({ name, run }) => {
+	if (run?.kind !== "ai") return [];
+	const prompt = promptError(run.prompt ?? "");
+	const written = Object.hasOwn(model.fields, run.writes) ? model.fields[run.writes] : void 0;
+	return [
+		...prompt ? [prompt] : [],
+		...promptFields(run.prompt ?? "").filter((field) => !Object.hasOwn(model.fields, field)).map((field) => `its prompt names field "${field}", which ${model.name} does not have`),
+		...!written ? [`it writes field "${run.writes}", which ${model.name} does not have`] : [],
+		...written && written.type !== "text" && written.type !== "enum" ? [`it writes "${run.writes}", which is ${written.type}, not text or an enum`] : [],
+		...written?.readOnly ? [`it writes "${run.writes}", which is readOnly()`] : []
+	].map((error) => `action "${name}": ${error}`);
+});
 const inputErrors = (view, models) => view.actions.flatMap(({ name, run, inputs }) => {
 	if (!inputs) return [];
 	return [
-		...run ? [`inputs need a handler, and a${run.kind === "update" ? "n" : ""} ${run.kind} action has none`] : [],
+		...run ? [`inputs need a handler, and a${run.kind === "update" || run.kind === "ai" ? "n" : ""} ${run.kind} action has none`] : [],
 		...actionInputErrors(inputs),
 		...inputs.flatMap((input) => input.resource !== void 0 && !models[input.resource] ? [`input "${input.name}" picks from resource "${input.resource}", which the app does not have`] : [])
 	].map((error) => `action "${name}": ${error}`);
@@ -113,7 +130,7 @@ const listOfErrors = (model, name, models) => {
 * has a related section or related list column, a cards display's or gallery's photos or a cards display's favorite button, a `listOf`, a "Save search" button or a
 * `searchesOf` that do not fit the resources, cards
 * displays of one list that name different photos, a chart per value that cannot group or add up its fields, a map that cannot show the
-* record's position or a map display that cannot find the records in its view, a board whose columns are no filterable enum, a link to an address the app does not have, action inputs that do not fit, or a create page that is not one of `pages`.
+* record's position or a map display that cannot find the records in its view, a board whose columns are no filterable enum, a calendar whose dates are no filterable date or timestamp fields, a link to an address the app does not have, an AI action that cannot write its field, action inputs that do not fit, or a create page that is not one of `pages`.
 */
 const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 	const models = Object.fromEntries(registry.entries.map((entry) => [entry.name, entry.model]));
@@ -132,8 +149,10 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 		const searches = [...view.saveSearch ? saveSearchErrors(view.saveSearch, view.resource, models, views).map((error) => `saveSearch: ${error}`) : [], ...view.searchesOf ? searchesOfErrors(view.searchesOf, view.resource, models).map((error) => `searchesOf: ${error}`) : []];
 		const maps = [...view.layout.flatMap((item) => item.kind === "map" ? mapErrors(item, model).map((error) => `map "${item.title}": ${error}`) : []), ...(view.list?.displays ?? []).flatMap((display) => display.kind === "map" ? mapDisplayErrors(display, model).map((error) => `display "${display.name}": ${error}`) : [])];
 		const boards = (view.list?.displays ?? []).flatMap((display) => display.kind === "board" ? boardErrors(display, model).map((error) => `display "${display.name}": ${error}`) : []);
+		const calendars = (view.list?.displays ?? []).flatMap((display) => display.kind === "calendar" ? calendarErrors(display, model).map((error) => `display "${display.name}": ${error}`) : []);
 		const chart = view.chart ? chartErrors(view.chart, model).map((error) => `chart: ${error}`) : [];
 		const history = model.history ? [] : view.layout.flatMap((item) => item.kind === "history" ? [`history "${item.title}" needs .history() on resource "${view.resource}"`] : []);
+		const comments = model.comments ? [] : view.layout.flatMap((item) => item.kind === "comments" ? [`comments "${item.title}" needs .comments() on resource "${view.resource}"`] : []);
 		return [
 			...sensitiveErrors(view, model),
 			...unknownFieldErrors(view, model),
@@ -149,9 +168,12 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 			...searches,
 			...maps,
 			...history,
+			...comments,
 			...boards,
+			...calendars,
 			...chart,
 			...linkErrors(view, model, models, pageNames),
+			...aiActionErrors(view, model),
 			...inputErrors(view, models),
 			...createErrors(view, pageNames)
 		].map((problem) => `View "${view.resource}": ${problem}`);

package/dist/comments/app-origin.js

@@ -0,0 +1,11 @@
+//#region src/comments/app-origin.ts
+/**
+* The origin the app answers a request to `requestURL` on: the request's own when it is one of `origins`, else the
+* first of them, the app's base URL. Any origin when there are none to check against.
+*/
+const appOrigin = (origins) => (requestURL) => {
+	const origin = new URL(requestURL).origin;
+	return origins.length === 0 || origins.includes(origin) ? origin : origins[0];
+};
+//#endregion
+export { appOrigin };

package/dist/comments/comment-access.js

@@ -0,0 +1,54 @@
+import { forbidden, notFound } from "../problem.js";
+import { requestAccess, requireOperation } from "../request-access.js";
+import { fetchReadable } from "../read-service.js";
+//#region src/comments/comment-access.ts
+/** The caller's access to a resource with comments, who must be allowed to read it; a resource without is a 404. */
+const commentAccess = async (deps, entry, session) => {
+	if (!entry.model.comments) throw notFound(`${entry.name} takes no comments`);
+	const access = await requestAccess(deps, entry, session);
+	requireOperation(access, "read");
+	return access;
+};
+/** Writing a comment, or looking for someone to mention, takes a signed-in user: a visitor is no author. */
+const requireSignedIn = (session) => {
+	if (session.anonymous || session.user.id === "") throw forbidden("comment-needs-user", "Sign in to comment");
+};
+/** The record with this key when `access` may read it (tenant, row filter and record-level rule), with `fields` besides its key. */
+const readableRecord = (trx, access, key, deleted, fields = []) => {
+	const names = [.../* @__PURE__ */ new Set([...access.full.primaryKey, ...fields])];
+	return fetchReadable(trx, access, key, deleted, { fields: names.map((name) => access.full.fields[name]) });
+};
+/**
+* The sessions these users act with now, in the caller's tenant, built as a subscription's is (see `subscriberSession`);
+* none for one who holds no role there, or when the project has no auth to ask.
+*/
+const userSessions = (deps, caller, ids) => Promise.all(ids.map(async (id) => {
+	const users = deps.comments?.users;
+	const roles = users ? await users.roles({
+		id,
+		...caller.tenant !== void 0 && { tenant: caller.tenant }
+	}) : [];
+	if (roles.length === 0) return { id };
+	return {
+		id,
+		session: {
+			user: {
+				id,
+				roles
+			},
+			...caller.tenant !== void 0 && {
+				tenant: caller.tenant,
+				organization: { id: caller.tenant }
+			}
+		}
+	};
+}));
+/** Whether the user of `session` may read the record: the same operation, tenant, row filter and record-level rule as a get. */
+const mayRead = async (trx, deps, entry, session, key) => {
+	if (!session) return false;
+	const access = await requestAccess(deps, entry, session);
+	if (!access.resolved.operations.read) return false;
+	return await readableRecord(trx, access, key, "hide") !== void 0;
+};
+//#endregion
+export { commentAccess, mayRead, readableRecord, requireSignedIn, userSessions };

package/dist/comments/comment-input.js

@@ -0,0 +1,26 @@
+import { badRequest } from "../problem.js";
+import { z } from "zod";
+//#region src/comments/comment-input.ts
+/** The longest comment, in characters, after trimming. */
+const maxCommentLength = 1e4;
+const input = z.object({
+	body: z.string(),
+	mentions: z.array(z.string().min(1)).max(20).optional()
+});
+/**
+* A comment as `author` posts it: the body trimmed, not empty and at most `maxCommentLength` long, and the user ids it
+* mentions once each, without the author's own.
+*/
+const parseCommentInput = (body, author) => {
+	const parsed = input.safeParse(body);
+	if (!parsed.success) throw badRequest("invalid-comment", `The comment is invalid: ${parsed.error.issues[0].path.join(".") || "body"}: ${parsed.error.issues[0].message}`);
+	const text = parsed.data.body.trim();
+	if (text === "") throw badRequest("invalid-comment", "The comment is empty");
+	if (text.length > 1e4) throw badRequest("invalid-comment", `The comment is longer than ${maxCommentLength} characters`);
+	return {
+		body: text,
+		mentions: [...new Set(parsed.data.mentions ?? [])].filter((id) => id !== author)
+	};
+};
+//#endregion
+export { maxCommentLength, parseCommentInput };

package/dist/comments/comment-item.d.ts

@@ -0,0 +1,16 @@
+//#region src/comments/comment-item.d.ts
+/** One comment as the API gives it: its author and the people it mentions, with their names when the project's auth knows them. */
+export type CommentItem = {
+  id: string;
+  created_at: string;
+  body: string;
+  author: {
+    id: string;
+    name?: string;
+  };
+  mentions: {
+    id: string;
+    name?: string;
+  }[];
+};
+//#endregion

package/dist/comments/comment-item.js

@@ -0,0 +1,18 @@
+//#region src/comments/comment-item.ts
+const person = (id, names) => ({
+	id,
+	...names[id] !== void 0 && { name: names[id] }
+});
+/** The user ids a page of comments names, once each. */
+const namedUsers = (rows) => [...new Set(rows.flatMap((row) => [row.author_id, ...row.mentions]))];
+const commentItem = (row, names) => ({
+	id: row.id,
+	created_at: row.created_at,
+	body: row.body,
+	author: person(row.author_id, names),
+	mentions: row.mentions.map((id) => person(id, names))
+});
+/** The columns of a `CommentRow`, `created_at` as ISO text in UTC. */
+const commentColumns = `"id"::text as id, to_char("created_at" at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') as created_at, "body", "author_id", "mentions"`;
+//#endregion
+export { commentColumns, commentItem, namedUsers };

package/dist/comments/comment-users.d.ts

@@ -0,0 +1,21 @@
+import "../better-auth/create-auth.js";
+import { TenantValue } from "../types.js";
+//#region src/comments/comment-users.d.ts
+/** The users comments name, mention and mail: from the project's auth. */
+export type CommentUsers = {
+  /** The names of these user ids; one who is gone or has none is left out. */
+  names(ids: readonly string[]): Promise<Record<string, string>>;
+  /** Up to `limit` users whose name contains `query`, whatever its case, by name; no banned ones. */
+  search(query: string, limit: number): Promise<{
+    id: string;
+    name: string;
+  }[]>;
+  /** The role the user acts with now in `tenant` (see `betterAuthOwnerRoles`); none when banned or gone. */
+  roles(user: {
+    id: string;
+    tenant?: TenantValue;
+  }): Promise<string[]>;
+  /** The address mail to the user goes to; `undefined` when they are banned or gone. */
+  email(id: string): Promise<string | undefined>;
+};
+//#endregion

package/dist/comments/comment-users.js

@@ -0,0 +1,35 @@
+import { betterAuthActorNames } from "../history/actor-names.js";
+import { betterAuthOwnerRoles } from "../webhooks/table/owner-roles.js";
+//#region src/comments/comment-users.ts
+/** The users of a Better Auth instance, read through its adapters only (see `better-auth/users.ts`). */
+const betterAuthCommentUsers = (auth) => ({
+	names: betterAuthActorNames(auth),
+	roles: betterAuthOwnerRoles(auth),
+	search: async (query, limit) => {
+		const { adapter } = await auth.$context;
+		return (await adapter.findMany({
+			model: "user",
+			...query !== "" && { where: [{
+				field: "name",
+				operator: "contains",
+				value: query,
+				mode: "insensitive"
+			}] },
+			limit,
+			sortBy: {
+				field: "name",
+				direction: "asc"
+			}
+		})).flatMap((user) => user.banned || !user.name ? [] : [{
+			id: user.id,
+			name: user.name
+		}]);
+	},
+	email: async (id) => {
+		const { internalAdapter } = await auth.$context;
+		const user = await internalAdapter.findUserById(id);
+		return user && !user.banned && user.email ? user.email : void 0;
+	}
+});
+//#endregion
+export { betterAuthCommentUsers };

package/dist/comments/comments-sql.d.ts

@@ -0,0 +1,8 @@
+import { ResourceModel } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/comments/comments-sql.d.ts
+/** The SQL that adds the `comments` schema and its table, `undefined` when it is there. The table is never dropped. */
+export declare const commentsMigration: (db: Db) => Promise<string | undefined>;
+/** Refuses to go on while a resource has `.comments()` and the database lacks their table; the project's migrations add it. */
+export declare const checkComments: (db: Db, models: readonly ResourceModel[]) => Promise<void>;
+//#endregion

package/dist/comments/comments-sql.js

@@ -0,0 +1,37 @@
+import { migrationCommand } from "../changes/capture-schema.js";
+import { sql } from "kysely";
+//#region src/comments/comments-sql.ts
+/** The table the comments of every resource with `.comments()` are kept in, in a schema of its own. */
+const commentsTable = "\"comments\".\"comments\"";
+/**
+* A row per comment: the record it is on by resource and encoded key, its tenant, its author and the user ids it
+* mentions (`[]` for none). Every column the admin list filters on has an index.
+*/
+const commentsTableSql = () => `create table if not exists ${commentsTable} (
+  "id" bigint generated always as identity primary key,
+  "resource" text not null,
+  "record_key" text not null,
+  "tenant_id" text,
+  "author_id" text not null,
+  "body" text not null,
+  "mentions" jsonb not null,
+  "created_at" timestamptz not null default now()
+);
+create index if not exists "comments_record" on ${commentsTable} ("resource", "record_key", "id");
+create index if not exists "comments_tenant" on ${commentsTable} ("tenant_id", "id");
+create index if not exists "comments_author" on ${commentsTable} ("author_id", "id");
+create index if not exists "comments_created_at" on ${commentsTable} ("created_at")`;
+const hasCommentsTable = async (db) => (await sql`select to_regclass('comments.comments') is not null as found`.execute(db)).rows[0].found;
+/** The SQL that adds the `comments` schema and its table, `undefined` when it is there. The table is never dropped. */
+const commentsMigration = async (db) => {
+	if (await hasCommentsTable(db)) return void 0;
+	return `create schema if not exists "comments";\n\n${commentsTableSql()};`;
+};
+/** Refuses to go on while a resource has `.comments()` and the database lacks their table; the project's migrations add it. */
+const checkComments = async (db, models) => {
+	if (!models.some((model) => model.comments)) return;
+	if (await hasCommentsTable(db)) return;
+	throw new Error(`The comments schema is missing, and resources with .comments() keep their comments in comments.comments. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+};
+//#endregion
+export { checkComments, commentsMigration, commentsTable, commentsTableSql };

package/dist/comments/mention-email.js

@@ -0,0 +1,37 @@
+import { defineEmail } from "../mail/define-email.js";
+import { AuthEmailLayout, EmailButton, EmailNote } from "../better-auth/auth-mail/auth-email-layout.js";
+import { Text } from "react-email";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/comments/mention-email.tsx
+const MentionEmail = ({ app, author, record, body, url }) => /* @__PURE__ */ jsxs(AuthEmailLayout, {
+	app,
+	preview: `${author} mentioned you on ${record}`,
+	heading: `${author} mentioned you`,
+	children: [
+		/* @__PURE__ */ jsxs(Text, { children: [
+			author,
+			" mentioned you in a comment on ",
+			record,
+			" in ",
+			app.name,
+			":"
+		] }),
+		/* @__PURE__ */ jsx(Text, {
+			style: { whiteSpace: "pre-wrap" },
+			children: body.split("\n").flatMap((line, index) => index === 0 ? [line] : [/* @__PURE__ */ jsx("br", {}, index), line])
+		}),
+		/* @__PURE__ */ jsxs(EmailButton, {
+			href: url,
+			children: ["Open ", record]
+		}),
+		/* @__PURE__ */ jsx(EmailNote, { children: "You get this email because someone mentioned you. Reply in the app, not to this email." })
+	]
+});
+/** The email to someone a comment mentions: who wrote it on which record, the comment, and a link to the record. */
+const mentionEmail = defineEmail({
+	name: "mention",
+	subject: ({ author, record }) => `${author} mentioned you on ${record}`,
+	component: MentionEmail
+});
+//#endregion
+export { mentionEmail };

package/dist/comments/mention-job.d.ts

@@ -0,0 +1,3 @@
+import "./comment-users.js";
+import "../index.js";
+import { z } from "zod";

package/dist/comments/mention-job.js

@@ -0,0 +1,43 @@
+import { defineJob } from "../jobs/define-job.js";
+import { commentsTable } from "./comments-sql.js";
+import { z } from "zod";
+import { sql } from "kysely";
+//#region src/comments/mention-job.ts
+const payload = z.object({
+	comment: z.string().regex(/^\d+$/),
+	user: z.string().min(1),
+	url: z.string().url(),
+	record: z.string()
+});
+/**
+* The job that emails someone a comment mentions, enqueued with the comment: nothing when the app has no mail, when an
+* admin deleted the comment since, or when the user is banned or gone. A refused send is retried.
+*/
+const mentionJob = (users, appName) => defineJob({
+	name: "comments.mention",
+	payload,
+	retryDelay: "1 minute",
+	run: async ({ comment, user, url, record }, { db, mail }) => {
+		if (!mail) return;
+		if (!users) throw new Error("Not implemented: mentions need Better Auth");
+		const { rows } = await sql`select "author_id", "body" from ${sql.raw(commentsTable)} where "id" = ${comment}::bigint`.execute(db);
+		const found = rows[0];
+		if (!found) return;
+		const to = await users.email(user);
+		if (!to) return;
+		const author = (await users.names([found.author_id]))[found.author_id] ?? found.author_id;
+		const { mentionEmail } = await import("./mention-email.js");
+		await mentionEmail.send(to, {
+			app: {
+				name: appName,
+				url: new URL("/", url).href
+			},
+			author,
+			record,
+			body: found.body,
+			url
+		}, mail);
+	}
+});
+//#endregion
+export { mentionJob };

package/dist/comments/mentionable.js

@@ -0,0 +1,38 @@
+import { notFound } from "../problem.js";
+import { readTransaction } from "../transactions.js";
+import { parseParams } from "../params.js";
+import { commentAccess, mayRead, readableRecord, requireSignedIn, userSessions } from "./comment-access.js";
+import { z } from "zod";
+//#region src/comments/mentionable.ts
+const params = z.object({ q: z.string().max(100).optional() });
+/** The most people `:mentionable` offers, and the candidates it checks to find them. */
+const shown = 8;
+const candidates = 20;
+/**
+* The people the caller may mention on a record they may comment on: users whose name contains `q`, by name, who may
+* read the record themselves, without the caller. None without the project's auth.
+*/
+const mentionable = async (deps, entry, session, key, query) => {
+	const access = await commentAccess(deps, entry, session);
+	requireSignedIn(session);
+	const { q = "" } = parseParams(params, query);
+	const users = deps.comments?.users;
+	const found = users ? (await users.search(q.trim(), candidates)).filter((user) => user.id !== String(session.user.id)) : [];
+	const sessions = await userSessions(deps, session, found.map((user) => user.id));
+	const readers = await readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		if (!await readableRecord(trx, access, key, "hide")) return void 0;
+		const ids = /* @__PURE__ */ new Set();
+		for (const { id, session: theirs } of sessions) {
+			if (ids.size === shown) break;
+			if (await mayRead(trx, deps, entry, theirs, key)) ids.add(id);
+		}
+		return ids;
+	});
+	if (!readers) throw notFound(`No ${entry.name} with this key`);
+	return { items: found.filter((user) => readers.has(user.id)).map(({ id, name }) => ({
+		id,
+		name
+	})) };
+};
+//#endregion
+export { mentionable };

package/dist/comments/post-comment.js

@@ -0,0 +1,57 @@
+import { badRequest, notFound } from "../problem.js";
+import { tenantScope } from "../tenant.js";
+import { writeTransaction } from "../transactions.js";
+import { commentsTable } from "./comments-sql.js";
+import { commentAccess, mayRead, readableRecord, requireSignedIn, userSessions } from "./comment-access.js";
+import { parseCommentInput } from "./comment-input.js";
+import { commentColumns, commentItem, namedUsers } from "./comment-item.js";
+import { readableTitle, recordLabel } from "./record-label.js";
+import { encodeKey } from "@protobase/schema/internal";
+import { appPath } from "@protobase/schema";
+import { sql } from "kysely";
+//#region src/comments/post-comment.ts
+const invalidMention = () => badRequest("invalid-mention", "Someone you mentioned cannot read this record");
+/**
+* Adds the caller's comment to a record they may read, live rather than soft-deleted, and enqueues the email of each
+* person it mentions, who must be able to read the record too, in the same transaction. `requestURL` is the request's,
+* whose origin the emailed link takes when the app is served there (see `Deps.comments`).
+*/
+const postComment = async (deps, entry, session, key, body, requestURL) => {
+	const access = await commentAccess(deps, entry, session);
+	requireSignedIn(session);
+	const author = String(session.user.id);
+	const input = parseCommentInput(body, author);
+	const { users, mentionJob, appOrigin } = deps.comments ?? {};
+	if (input.mentions.length > 0 && !(users && mentionJob)) throw invalidMention();
+	const mentioned = await userSessions(deps, session, input.mentions);
+	const tenant = tenantScope(entry, session)?.tenantValue;
+	const title = readableTitle(access, deps.views);
+	const row = await writeTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		const current = await readableRecord(trx, access, key, "hide", title === void 0 ? [] : [title]);
+		if (!current) return void 0;
+		for (const { session: theirs } of mentioned) if (!await mayRead(trx, deps, entry, theirs, key)) throw invalidMention();
+		const { rows } = await sql`insert into ${sql.raw(commentsTable)} ("resource", "record_key", "tenant_id", "author_id", "body", "mentions")
+      values (${entry.name}, ${encodeKey(key)}, ${tenant === void 0 ? null : String(tenant)}, ${author}, ${input.body}, ${JSON.stringify(input.mentions)}::jsonb)
+      returning ${sql.raw(commentColumns)}`.execute(trx);
+		const inserted = rows[0];
+		if (input.mentions.length === 0) return inserted;
+		const url = `${appOrigin(requestURL)}${appPath({
+			kind: "record",
+			resource: entry.name,
+			key
+		})}`;
+		const record = recordLabel(access, deps.views, key, current.record);
+		for (const user of input.mentions) await mentionJob.enqueue(trx, {
+			comment: inserted.id,
+			user,
+			url,
+			record
+		}, { key: `${inserted.id}:${user}` });
+		return inserted;
+	});
+	if (!row) throw notFound(`No ${entry.name} with this key`);
+	const names = deps.comments?.users ? await deps.comments.users.names(namedUsers([row])) : {};
+	return commentItem(row, names);
+};
+//#endregion
+export { postComment };

package/dist/comments/read-comments.js

@@ -0,0 +1,45 @@
+import { notFound } from "../problem.js";
+import { tenantScope } from "../tenant.js";
+import { readTransaction } from "../transactions.js";
+import { commentsTable } from "./comments-sql.js";
+import { parseParams } from "../params.js";
+import { commentAccess, readableRecord } from "./comment-access.js";
+import { commentColumns, commentItem, namedUsers } from "./comment-item.js";
+import { encodeKey } from "@protobase/schema/internal";
+import { z } from "zod";
+import { sql } from "kysely";
+//#region src/comments/read-comments.ts
+const params = z.object({
+	page_size: z.coerce.number().int().min(0).max(100).optional(),
+	page_token: z.string().regex(/^\d+$/, "Use the next_page_token of the previous page").optional()
+});
+const defaultPageSize = 20;
+/**
+* A page of a record's comments, newest first, for a caller who may read the record: the same tenant, row filter and
+* record-level rule as a get, a soft-deleted record included.
+*/
+const readComments = async (deps, entry, session, key, query) => {
+	const access = await commentAccess(deps, entry, session);
+	const { page_size, page_token } = parseParams(params, query);
+	const size = page_size || defaultPageSize;
+	const tenant = tenantScope(entry, session)?.tenantValue;
+	const rows = await readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		if (!await readableRecord(trx, access, key, entry.model.softDelete ? "show" : "hide")) return void 0;
+		const { rows } = await sql`select ${sql.raw(commentColumns)}
+      from ${sql.raw(commentsTable)} where "resource" = ${entry.name} and "record_key" = ${encodeKey(key)}
+        ${tenant === void 0 ? sql`` : sql`and "tenant_id" = ${String(tenant)}`}
+        ${page_token === void 0 ? sql`` : sql`and "id" < ${page_token}::bigint`}
+      order by "id" desc limit ${size + 1}`.execute(trx);
+		return rows;
+	});
+	if (!rows) throw notFound(`No ${entry.name} with this key`);
+	const page = rows.slice(0, size);
+	const ids = namedUsers(page);
+	const names = ids.length > 0 && deps.comments?.users ? await deps.comments.users.names(ids) : {};
+	return {
+		items: page.map((row) => commentItem(row, names)),
+		next_page_token: rows.length > size ? page.at(-1).id : ""
+	};
+};
+//#endregion
+export { readComments };

package/dist/comments/record-comments.js

@@ -0,0 +1,53 @@
+import { f, l, resource, view } from "@protobase/schema";
+//#region src/comments/record-comments.ts
+const admins = ({ user }) => user?.roles?.includes("admin") ?? false;
+/**
+* Every comment on every resource with comments, over their table: the admin app lists them as Comments. Admins only,
+* whatever the project's roles say, since it spans every record; they may delete one, which is how a wrong or abusive
+* comment goes. With `tenant`, when a resource with comments has one, it is scoped to the caller's tenant.
+*/
+const commentsResource = ({ tenant }) => {
+	const comments = resource("record_comments").table("comments.comments").fields({
+		id: f.bigint().readOnly().sortable(),
+		resource: f.text().readOnly().filterable(),
+		record_key: f.text().readOnly().filterable(),
+		tenant_id: f.text().optional().readOnly(),
+		author_id: f.text().readOnly().filterable(),
+		body: f.text().readOnly(),
+		mentions: f.json().readOnly(),
+		created_at: f.timestamp().readOnly().filterable()
+	}).primaryKey((r) => r.id).access({
+		list: admins,
+		read: admins,
+		create: () => false,
+		update: () => false,
+		delete: admins
+	});
+	return tenant ? comments.tenant((r) => r.tenant_id) : comments;
+};
+const commentsView = view("record_comments").names({
+	singular: "Comment",
+	plural: "Comments"
+}).icon("message-square").title((r) => r.record_key).help("Every comment on the records whose resource takes comments, newest first. Delete one to take it down.").fields((r) => ({
+	record_key: r.record_key.label("Record"),
+	author_id: r.author_id.label("By"),
+	body: r.body.label("Comment"),
+	mentions: r.mentions.label("Mentions"),
+	created_at: r.created_at.label("When")
+})).list((r) => ({
+	columns: [
+		r.created_at,
+		r.resource,
+		r.record_key,
+		r.author_id,
+		r.body
+	],
+	sort: [[r.id, "desc"]]
+})).layout((r) => [l.section("Comment", [
+	r.resource,
+	r.record_key,
+	r.body,
+	r.mentions
+]), l.sidebar([r.created_at, r.author_id])]);
+//#endregion
+export { commentsResource, commentsView };

package/dist/comments/record-label.js

@@ -0,0 +1,19 @@
+import { encodeKey } from "@protobase/schema/internal";
+//#region src/comments/record-label.ts
+/** The title field of the resource's view, when the caller may read it. */
+const readableTitle = (access, views) => {
+	const title = views.find((view) => view.resource === access.entry.name)?.title;
+	return title !== void 0 && Object.hasOwn(access.model.fields, title) ? title : void 0;
+};
+/**
+* The record as a mention email names it: the view's singular name with the record's title when it has one the author
+* may read, else with its key, such as `Ticket: Printer on fire` or `Ticket 12`.
+*/
+const recordLabel = (access, views, key, record) => {
+	const name = views.find((view) => view.resource === access.entry.name)?.names?.singular ?? access.entry.name;
+	const title = readableTitle(access, views);
+	const value = title === void 0 ? void 0 : record[title];
+	return value === void 0 || value === null || value === "" ? `${name} ${encodeKey(key)}` : `${name}: ${String(value)}`;
+};
+//#endregion
+export { readableTitle, recordLabel };