@protobase/server 0.20.0 → 0.21.1

package/dist/changes/actor.js

@@ -1,7 +1,7 @@
 import { runningJobs } from "../jobs/current.js";
 import { dispatchJobName } from "./capture-sql.js";
 //#region src/changes/actor.ts
-/** The setting a write transaction sets so the change capture records who wrote, when a resource has events. */
+/** The setting a write transaction sets so the change capture records who wrote, when a resource has events or history. */
 const actorSettings = (deps, session) => {
 	if (!deps.actorSetting) return {};
 	const actor = {

package/dist/changes/capture-plan.js

@@ -1,4 +1,5 @@
-import { captureBody, captureFunctionSql, createTriggerSql, dropTriggerSql, outboxSql, quoteIdent, resourceTriggers, tableSql } from "./capture-sql.js";
+import { captureBody, captureFunctionSql, createTriggerSql, dropTriggerSql, isCaptured, outboxSql, quoteIdent, resourceTriggers, tableSql } from "./capture-sql.js";
+import { historyTableSql } from "../history/history-sql.js";
 //#region src/changes/capture-plan.ts
 const sameTrigger = (found, wanted) => found.type === wanted.type && found.args.length === wanted.args.length && found.args.every((arg, index) => arg === wanted.args[index]);
 const tableOf = (state, model) => {
@@ -7,14 +8,14 @@ const tableOf = (state, model) => {
 	return table;
 };
 /**
-* Compares the database with the resources that declare events. Fails on what it cannot change safely: a missing
-* table, two resources with events on one table, or a trigger of the same name that calls another function.
+* Compares the database with the resources that declare events or history. Fails on what it cannot change safely: a
+* missing table, two captured resources on one table, or a trigger of the same name that calls another function.
 */
 const capturePlan = (schema, models, state) => {
-	const withEvents = models.filter((model) => (model.events ?? []).length > 0);
+	const captured = models.filter(isCaptured);
 	const capture = state.capture;
 	const current = capture !== void 0 && capture.definer && capture.source === captureBody(schema);
-	const wanted = withEvents.flatMap((model) => resourceTriggers(model).map((trigger) => ({
+	const wanted = captured.flatMap((model) => resourceTriggers(model).map((trigger) => ({
 		model,
 		trigger,
 		table: tableOf(state, model)
@@ -22,17 +23,18 @@ const capturePlan = (schema, models, state) => {
 	const tables = /* @__PURE__ */ new Map();
 	for (const { model, table } of wanted) {
 		const other = tables.get(table);
-		if (other && other !== model.name) throw new Error(`Not implemented: resources "${other}" and "${model.name}" both have events on table ${tableSql(model)}; declare them on one`);
+		if (other && other !== model.name) throw new Error(`Not implemented: resources "${other}" and "${model.name}" both have events or history on table ${tableSql(model)}; declare them on one`);
 		tables.set(table, model.name);
 	}
 	const create = wanted.filter(({ model, trigger, table }) => {
 		const found = state.triggers.find((candidate) => candidate.table === table && candidate.name === trigger.name);
-		if (found && found.function !== capture?.oid) throw new Error(`Table ${tableSql(model)} has a trigger "${trigger.name}" of its own; rename it, since events need that name`);
+		if (found && found.function !== capture?.oid) throw new Error(`Table ${tableSql(model)} has a trigger "${trigger.name}" of its own; rename it, since events and history need that name`);
 		return !found || !sameTrigger(found, trigger);
 	});
 	const drop = state.triggers.filter((found) => found.function === capture?.oid).filter((found) => !wanted.some(({ trigger, table }) => table === found.table && trigger.name === found.name));
 	return {
-		setup: withEvents.length > 0 && (!state.outbox || !current),
+		setup: captured.length > 0 && (!state.outbox || !current),
+		history: models.some((model) => model.history) && !state.history,
 		create: create.map(({ model, trigger }) => ({
 			model,
 			trigger
@@ -51,12 +53,13 @@ const planSql = (schema, plan) => {
 			outboxSql(schema),
 			captureFunctionSql(schema)
 		] : [],
+		...plan.history ? [`create schema if not exists ${quoteIdent(schema)}`, historyTableSql(schema)] : [],
 		...plan.drop.map(({ name, tableSql }) => dropTriggerSql(name, tableSql)),
 		...plan.create.flatMap(({ model, trigger }) => [dropTriggerSql(trigger.name, tableSql(model)), createTriggerSql(schema, trigger, tableSql(model))])
 	];
 	return statements.length === 0 ? void 0 : `${statements.join(";\n\n")};`;
 };
-/** The resources whose changes would not be captured as the config declares: what a server refuses to start with. */
-const uncaptured = (plan, models) => plan.setup ? models.filter((model) => (model.events ?? []).length > 0).map((model) => model.name) : [...new Set(plan.create.map(({ model }) => model.name))];
+/** The resources whose changes would not be captured or kept as the config declares: what a server refuses to start with. */
+const uncaptured = (plan, models) => [...new Set([...plan.setup ? models.filter(isCaptured) : plan.create.map(({ model }) => model), ...plan.history ? models.filter((model) => model.history) : []].map((model) => model.name))];
 //#endregion
 export { capturePlan, planSql, uncaptured };

package/dist/changes/capture-schema.d.ts

@@ -5,14 +5,16 @@ import { Db } from "@protobase/query";
 /** The command that writes what the config needs as a migration file of the project. */
 export declare const migrationCommand = "protobase migration";
 /**
- * The SQL that brings the database to the capture the resources' events need: the schema with the outbox and
- * `capture()`, and a trigger pair per resource with events, recreated when its fields changed; triggers of resources
- * without events any more are dropped. `undefined` when the database is current. Tables are never dropped.
+ * The SQL that brings the database to the capture the resources' events and history need: the schema with the outbox
+ * and `capture()`, the history table, and a trigger pair per resource with either, recreated when its fields changed;
+ * triggers of resources without either any more are dropped. `undefined` when the database is current. Tables are
+ * never dropped.
  */
 export declare const changesMigration: (db: Db, models: readonly ResourceModel[], options?: EventsOptions) => Promise<string | undefined>;
 /**
- * Refuses to go on while a resource's events would not be captured as declared: a missing or out-of-date schema, or
- * trigger. The server never changes the schema itself: the project's migrations do, before the new version serves.
+ * Refuses to go on while a resource's events or history would not be captured as declared: a missing or out-of-date
+ * schema, history table or trigger. The server never changes the schema itself: the project's migrations do, before the
+ * new version serves.
  */
 export declare const checkChanges: (db: Db, models: readonly ResourceModel[], options?: EventsOptions) => Promise<void>;
 //#endregion

package/dist/changes/capture-schema.js

@@ -1,4 +1,4 @@
-import { quoteIdent, tableSql } from "./capture-sql.js";
+import { isCaptured, quoteIdent, tableSql } from "./capture-sql.js";
 import { changesSchema } from "./events-options.js";
 import { capturePlan, planSql, uncaptured } from "./capture-plan.js";
 import { sql } from "kysely";
@@ -11,7 +11,7 @@ const triggerArgs = (hex) => {
 };
 const rowsOf = async (db, query) => (await query.execute(db)).rows;
 const readCaptureState = async (db, schema, models) => {
-	const [outbox] = await rowsOf(db, sql`select to_regclass(${`${quoteIdent(schema)}."outbox"`}) is not null as found`);
+	const exists = async (table) => (await rowsOf(db, sql`select to_regclass(${`${quoteIdent(schema)}.${quoteIdent(table)}`}) is not null as found`))[0]?.found ?? false;
 	const [capture] = await rowsOf(db, sql`select p.oid::text as oid, p.prosrc as source, p.prosecdef as definer from pg_proc p join pg_namespace n on n.oid = p.pronamespace where n.nspname = ${schema} and p.proname = 'capture' and p.pronargs = 0`);
 	const tables = {};
 	for (const model of models) {
@@ -24,7 +24,8 @@ const readCaptureState = async (db, schema, models) => {
       from pg_trigger t join pg_class c on c.oid = t.tgrelid join pg_namespace ns on ns.oid = c.relnamespace
       where not t.tgisinternal and (t.tgfoid::text = ${capture?.oid ?? ""} or t.tgrelid::text = any(${oids}::text[]))`);
 	return {
-		outbox: outbox?.found ?? false,
+		outbox: await exists("outbox"),
+		history: await exists("history"),
 		...capture && { capture },
 		triggers: triggers.map((trigger) => ({
 			...trigger,
@@ -35,31 +36,32 @@ const readCaptureState = async (db, schema, models) => {
 };
 const plan = async (db, models, options) => {
 	const schema = changesSchema(options);
-	const withEvents = models.filter((model) => (model.events ?? []).length > 0);
 	return {
 		schema,
-		plan: capturePlan(schema, models, await readCaptureState(db, schema, withEvents))
+		plan: capturePlan(schema, models, await readCaptureState(db, schema, models.filter(isCaptured)))
 	};
 };
 /**
-* The SQL that brings the database to the capture the resources' events need: the schema with the outbox and
-* `capture()`, and a trigger pair per resource with events, recreated when its fields changed; triggers of resources
-* without events any more are dropped. `undefined` when the database is current. Tables are never dropped.
+* The SQL that brings the database to the capture the resources' events and history need: the schema with the outbox
+* and `capture()`, the history table, and a trigger pair per resource with either, recreated when its fields changed;
+* triggers of resources without either any more are dropped. `undefined` when the database is current. Tables are
+* never dropped.
 */
 const changesMigration = async (db, models, options) => {
 	const { schema, plan: found } = await plan(db, models, options);
 	return planSql(schema, found);
 };
 /**
-* Refuses to go on while a resource's events would not be captured as declared: a missing or out-of-date schema, or
-* trigger. The server never changes the schema itself: the project's migrations do, before the new version serves.
+* Refuses to go on while a resource's events or history would not be captured as declared: a missing or out-of-date
+* schema, history table or trigger. The server never changes the schema itself: the project's migrations do, before the
+* new version serves.
 */
 const checkChanges = async (db, models, options) => {
-	if (!models.some((model) => model.events)) return;
+	if (!models.some(isCaptured)) return;
 	const { plan: found } = await plan(db, models, options);
 	const missing = uncaptured(found, models);
 	if (missing.length === 0) return;
-	throw new Error(`The changes of ${missing.join(", ")} are not captured as their events need: their triggers or the changes schema are missing or out of date. Write the change as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+	throw new Error(`The changes of ${missing.join(", ")} are not captured as their events or history need: their triggers, the history table or the changes schema are missing or out of date. Write the change as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
 };
 //#endregion
 export { changesMigration, checkChanges, migrationCommand };

package/dist/changes/capture-sql.d.ts

@@ -0,0 +1,5 @@
+import { ResourceModel } from "@protobase/schema";
+//#region src/changes/capture-sql.d.ts
+/** Whether the triggers capture a resource's changes: for its events, its history, or both. */
+export declare const isCaptured: (model: ResourceModel) => boolean;
+//#endregion

package/dist/changes/capture-sql.js

@@ -16,9 +16,12 @@ const identifier = (name) => {
 };
 /** The table as SQL names it, qualified when the resource names a schema. */
 const tableSql = (model) => qualified(model.table);
+/** Whether the triggers capture a resource's changes: for its events, its history, or both. */
+const isCaptured = (model) => (model.events ?? []).length > 0 || model.history === true;
 /**
 * The outbox: one row per changed row, written in the writer's transaction. `transaction` is the writer's transaction
-* id; `dispatch_after` holds back a change that the process which wrote it is delivering itself.
+* id; `database_role` the role that wrote; `dispatch_after` holds back a change that the process which wrote it is
+* delivering itself. The `alter` adds the role to an outbox of an earlier version.
 */
 const outboxSql = (schema) => `create table if not exists ${quoteIdent(schema)}."outbox" (
   "id" bigint generated always as identity primary key,
@@ -29,16 +32,19 @@ const outboxSql = (schema) => `create table if not exists ${quoteIdent(schema)}.
   "new" jsonb,
   "changed" text[],
   "actor" jsonb,
+  "database_role" text,
   "dispatch_after" timestamptz not null default now(),
   "created_at" timestamptz not null default now()
-)`;
+);
+alter table ${quoteIdent(schema)}."outbox" add column if not exists "database_role" text`;
 /** The job that turns captured changes into events and deliveries: one per writing transaction, run one at a time. */
 const dispatchJobName = "changes.dispatch";
 /** Every dispatch job's group in its ordered queue, so only one runs at a time, across processes too. */
 const dispatchGroup = "changes";
 /**
 * The body of `capture()`: its arguments are the resource, the columns to keep and the sensitive columns, whose names
-* it lists when they change but whose values it never keeps. It skips a transaction that set `<schema>.capture` to
+* it lists when they change but whose values it never keeps. It keeps the writing role: the one `set role` chose, else
+* the session's, since the function itself runs as its owner. It skips a transaction that set `<schema>.capture` to
 * `off`, and an update that changed none of those columns. The first row a transaction captures enqueues a dispatch
 * job in the same transaction; `<schema>.dispatch` remembers that for the rest of it, and a rolled-back savepoint
 * forgets it with the job.
@@ -68,7 +74,7 @@ begin
       return null;
     end if;
   end if;
-  insert into ${quoteIdent(schema)}."outbox" ("transaction", "resource", "op", "old", "new", "changed", "actor")
+  insert into ${quoteIdent(schema)}."outbox" ("transaction", "resource", "op", "old", "new", "changed", "actor", "database_role")
   values (
     pg_current_xact_id()::text::bigint,
     TG_ARGV[0],
@@ -76,7 +82,8 @@ begin
     (select jsonb_object_agg(o.key, o.value) from jsonb_each(old_row) as o where o.key = any(kept)),
     (select jsonb_object_agg(n.key, n.value) from jsonb_each(new_row) as n where n.key = any(kept)),
     changed,
-    nullif(current_setting('${schema}.actor', true), '')::jsonb
+    nullif(current_setting('${schema}.actor', true), '')::jsonb,
+    coalesce(nullif(current_setting('role'), 'none'), session_user)
   );
   if current_setting('${schema}.dispatch', true) is distinct from 'queued' then
     perform ${jobsSchema}.enqueue('${dispatchJobName}', null, null, null, '${dispatchGroup}');
@@ -90,7 +97,7 @@ end
 * service writing as its own role keeps working once a resource has events.
 */
 const captureFunctionSql = (schema) => `create or replace function ${quoteIdent(schema)}."capture"() returns trigger language plpgsql security definer set search_path = pg_catalog, pg_temp as $capture$${captureBody(schema)}$capture$`;
-/** The two triggers of a resource with events: inserts and deletes, and updates that change the row. */
+/** The two triggers of a resource whose changes are captured: inserts and deletes, and updates that change the row. */
 const resourceTriggers = (model) => {
 	const fields = Object.values(model.fields);
 	const args = [
@@ -116,4 +123,4 @@ const createTriggerSql = (schema, trigger, table) => {
 	return `create trigger ${quoteIdent(trigger.name)} ${timing} on ${table} for each row${when} execute function ${quoteIdent(schema)}."capture"(${args})`;
 };
 //#endregion
-export { captureBody, captureFunctionSql, createTriggerSql, dispatchGroup, dispatchJobName, dropTriggerSql, outboxSql, quoteIdent, resourceTriggers, tableSql };
+export { captureBody, captureFunctionSql, createTriggerSql, dispatchGroup, dispatchJobName, dropTriggerSql, isCaptured, outboxSql, quoteIdent, resourceTriggers, tableSql };

package/dist/changes/coalesce.d.ts

@@ -14,6 +14,8 @@ export type CapturedRow = {
   /** The columns an update changed, sensitive ones included; `null` for inserts and deletes. */
   changed: string[] | null;
   actor: EventActor | null;
+  /** The database role that wrote; `null` for a row captured before Protobase kept it. */
+  databaseRole: string | null;
   /** When the writing transaction started, ISO 8601. */
   at: string;
 };
@@ -28,6 +30,8 @@ export type CoalescedChange = {
   after: Row | null;
   changed: string[];
   actor: EventActor | null;
+  /** The database role of its last change. */
+  databaseRole: string | null;
   /** The id of its last outbox row. */
   sequence: string;
   /** When its last change's transaction started. */

package/dist/changes/coalesce.js

@@ -17,6 +17,7 @@ const merged = ({ first, last, actor, listed }) => {
 		transaction: first.transaction,
 		resource: first.resource,
 		actor,
+		databaseRole: last.databaseRole,
 		sequence: last.id,
 		at: last.at
 	};

package/dist/changes/outbox.js

@@ -30,7 +30,7 @@ const parseColumns = (text, model) => {
 const readOutbox = async (db, schema, models, limit) => {
 	const byName = new Map(models.map((model) => [model.name, model]));
 	const { rows } = await sql`select "id"::text as id, "transaction"::text as transaction, "resource", "op", "old"::text as old, "new"::text as new, "changed",
-      "actor"::text as actor, to_char("created_at" at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') as at
+      "actor"::text as actor, "database_role" as "databaseRole", to_char("created_at" at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') as at
     from ${sql.raw(`${quoteIdent(schema)}."outbox"`)} where "dispatch_after" <= now() order by "id" limit ${limit}`.execute(db);
 	return rows.map((row) => {
 		const model = byName.get(row.resource);

package/dist/changes/resource-change.d.ts

@@ -15,6 +15,8 @@ export type ResourceChange = {
   changed: string[];
   actor: EventActor | null;
   source: 'api' | 'database';
+  /** The database role that wrote; `null` when unknown. */
+  databaseRole: string | null;
   tenant?: TenantValue;
   transaction: string;
   /** Grows with every change of a record, so receivers can drop stale events. */

package/dist/changes/resource-change.js

@@ -34,6 +34,7 @@ const resourceChange = (model, change) => {
 		changed: fieldsOf(model, change.changed),
 		actor: change.actor,
 		source: change.actor ? "api" : "database",
+		databaseRole: change.databaseRole,
 		...tenant != null && { tenant },
 		transaction: change.transaction,
 		sequence: change.sequence,

package/dist/check-views.js

@@ -133,6 +133,7 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 		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 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}"`] : []);
 		return [
 			...sensitiveErrors(view, model),
 			...unknownFieldErrors(view, model),
@@ -147,6 +148,7 @@ const checkViews = (registry, views, pages = [], fieldTypes = {}) => {
 			...listOf,
 			...searches,
 			...maps,
+			...history,
 			...boards,
 			...chart,
 			...linkErrors(view, model, models, pageNames),

package/dist/create-admin.d.ts

@@ -1,5 +1,6 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
 import { EventsOptions } from "./changes/events-options.js";
+import { HistoryOptions } from "./history/options.js";
 import { JobDefinition } from "./jobs/job-types.js";
 import { Admin, Authenticator, PageSource, ViewSource } from "./types.js";
 import { WebhooksOptions } from "./webhooks/table/options.js";
@@ -30,7 +31,9 @@ export type CreateAdminInput = {
   files?: FilesOptions;
   /** Where the changes that resources' events are raised from are captured (see `EventsOptions`). */
   events?: EventsOptions;
-  /** The app's jobs (see `defineJob`): with any, or a resource with events, admins get the failed jobs page (`failed_jobs`). */
+  /** How long the history of resources with `.history()` is kept (see `HistoryOptions`). */
+  history?: HistoryOptions;
+  /** The app's jobs (see `defineJob`): with any, or a resource with events or history, admins get the failed jobs page (`failed_jobs`). */
   jobs?: JobDefinition[];
   /** Where the resources' events are delivered (`subscription(...)` exports of the config module). */
   subscriptions?: SubscriptionDefinition[];
@@ -51,5 +54,5 @@ export type CreateAdminInput = {
   options?: AdminOptions;
 };
 /** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
-export declare const createAdmin: ({ resources: appResources, views: appViews, pages, userMenu, bottomBars, db, authenticate, auth, functions, files: filesOptions, events, jobs, subscriptions, webhooks: webhooksOptions, bundlePlugins, fieldTypes, options }: CreateAdminInput) => Admin;
+export declare const createAdmin: ({ resources: appResources, views: appViews, pages, userMenu, bottomBars, db, authenticate, auth, functions, files: filesOptions, events, history: historyOptions, jobs, subscriptions, webhooks: webhooksOptions, bundlePlugins, fieldTypes, options }: CreateAdminInput) => Admin;
 //#endregion

package/dist/create-admin.js

@@ -1,5 +1,6 @@
 import { assistantSettings } from "./assistant/assistant-settings.js";
 import { createErrorHandler } from "./error-handler.js";
+import { isCaptured } from "./changes/capture-sql.js";
 import { assistantRecords } from "./assistant/records.js";
 import { builtInAssistant } from "./assistant/built-in-assistant.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
@@ -9,6 +10,10 @@ import { authBasePath } from "./better-auth/create-auth.js";
 import { organizationRoutes } from "./better-auth/organizations/admin-routes.js";
 import { statusRoute } from "./better-auth/status-route.js";
 import { changesSchema } from "./changes/events-options.js";
+import { activityResource, activityView } from "./history/activity.js";
+import { betterAuthActorNames } from "./history/actor-names.js";
+import { historyDays } from "./history/options.js";
+import { pruneHistoryJob } from "./history/prune-history.js";
 import { callerRecords } from "./functions/records.js";
 import { toApiFunction } from "./functions/define-function.js";
 import { createWebhooks } from "./webhooks/webhooks.js";
@@ -45,11 +50,23 @@ const declaredRoles = (auth, roles) => {
 	return names.length > 0 ? [...new Set(names)] : void 0;
 };
 /** The admin REST API as a Hono app. It uses only Web APIs, so it runs on Node, Workers and anywhere else Hono does. */
-const createAdmin = ({ resources: appResources, views: appViews = [], pages = [], userMenu, bottomBars = [], db, authenticate, auth, functions = {}, files: filesOptions, events, jobs = [], subscriptions = [], webhooks: webhooksOptions, bundlePlugins = [], fieldTypes = {}, options = {} }) => {
+const createAdmin = ({ resources: appResources, views: appViews = [], pages = [], userMenu, bottomBars = [], db, authenticate, auth, functions = {}, files: filesOptions, events, history: historyOptions, jobs = [], subscriptions = [], webhooks: webhooksOptions, bundlePlugins = [], fieldTypes = {}, options = {} }) => {
 	const basePath = options.basePath ?? "/api/v1";
-	const withJobs = jobs.length > 0 || appResources.some((resource) => resource.toModel().events);
-	const resources = withJobs ? [...appResources, failedJobs] : appResources;
-	const views = withJobs ? [...appViews, failedJobsView] : appViews;
+	const appModels = appResources.map((resource) => resource.toModel());
+	const withJobs = jobs.length > 0 || appModels.some(isCaptured);
+	const withHistory = appModels.some((model) => model.history);
+	const changes = changesSchema(events);
+	const days = historyDays(historyOptions);
+	const resources = [
+		...appResources,
+		...withJobs ? [failedJobs] : [],
+		...withHistory ? [activityResource(changes, { tenant: appModels.some((model) => model.history && model.tenant) })] : []
+	];
+	const views = [
+		...appViews,
+		...withJobs ? [failedJobsView] : [],
+		...withHistory ? [activityView] : []
+	];
 	const registry = buildRegistry(resources);
 	const apiFunctions = Object.fromEntries(Object.entries(functions).map(([name, source]) => [name, toApiFunction(name, source)]));
 	const viewModels = views.map((view) => view.toModel());
@@ -108,7 +125,11 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		plugins,
 		sources,
 		...files && { files },
-		...registry.entries.some((entry) => entry.model.events) && { actorSetting: `${changesSchema(events)}.actor` }
+		...appModels.some(isCaptured) && { actorSetting: `${changes}.actor` },
+		...withHistory && { history: {
+			schema: changes,
+			...auth && { actorNames: betterAuthActorNames(auth) }
+		} }
 	};
 	const meta = createMeta(deps);
 	const onError = createErrorHandler(options.onUnhandledError);
@@ -194,11 +215,11 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		deps,
 		subscriptions,
 		functions: apiFunctions,
-		schema: changesSchema(events),
+		schema: changes,
 		log: (line) => console.log(line),
 		...table && { table }
 	});
-	return Object.assign(app, { jobs: webhooks.jobs });
+	return Object.assign(app, { jobs: [...webhooks.jobs, ...withHistory && days !== void 0 ? [pruneHistoryJob(changes, days)] : []] });
 };
 //#endregion
 export { createAdmin };

package/dist/history/activity.js

@@ -0,0 +1,75 @@
+import { f, l, resource, view } from "@protobase/schema";
+//#region src/history/activity.ts
+const admins = ({ user }) => user?.roles?.includes("admin") ?? false;
+/**
+* Every kept change of every resource with history, over the history table of `schema`: the admin app lists them as
+* Activity. Admins only, whatever the project's roles say, since a change holds the record's fields before and after;
+* read-only. With `tenant`, when a resource with history has one, it is scoped to the caller's tenant.
+*/
+const activityResource = (schema, { tenant }) => {
+	const changes = resource("record_history").table(`${schema}.history`).fields({
+		id: f.bigint().readOnly().sortable(),
+		resource: f.text().readOnly().filterable(),
+		record_key: f.text().readOnly().filterable(),
+		tenant_id: f.text().optional().readOnly(),
+		operation: f.enum([
+			"create",
+			"update",
+			"delete",
+			"undelete"
+		]).readOnly().filterable(),
+		before: f.json().optional().readOnly(),
+		after: f.json().optional().readOnly(),
+		changed: f.json().readOnly(),
+		actor_id: f.text().optional().readOnly().filterable(),
+		actor_roles: f.json().optional().readOnly(),
+		database_role: f.text().optional().readOnly().filterable(),
+		transaction: f.bigint().readOnly().filterable(),
+		at: f.timestamp().readOnly().filterable()
+	}).primaryKey((r) => r.id).access({
+		list: admins,
+		read: admins,
+		create: () => false,
+		update: () => false,
+		delete: () => false
+	});
+	return tenant ? changes.tenant((r) => r.tenant_id) : changes;
+};
+const activityView = view("record_history").names({
+	singular: "Change",
+	plural: "Activity"
+}).icon("history").title((r) => r.record_key).help("Every change of the records whose resource keeps history, from the app or straight in the database, newest first.").fields((r) => ({
+	record_key: r.record_key.label("Record"),
+	actor_id: r.actor_id.label("By"),
+	actor_roles: r.actor_roles.label("Acting as"),
+	database_role: r.database_role.label("Database role"),
+	changed: r.changed.label("Changed fields"),
+	at: r.at.label("When")
+})).list((r) => ({
+	columns: [
+		r.at,
+		r.resource,
+		r.record_key,
+		r.operation,
+		r.actor_id,
+		r.changed
+	],
+	sort: [[r.id, "desc"]]
+})).layout((r) => [
+	l.section("Change", [
+		r.resource,
+		r.record_key,
+		r.operation,
+		r.changed
+	]),
+	l.section("Before and after", [r.before, r.after]),
+	l.sidebar([
+		r.at,
+		r.actor_id,
+		r.actor_roles,
+		r.database_role,
+		r.transaction
+	])
+]);
+//#endregion
+export { activityResource, activityView };

package/dist/history/actor-names.js

@@ -0,0 +1,9 @@
+//#region src/history/actor-names.ts
+/** The names Better Auth knows of these user ids; a user who is gone, or signed in elsewhere, has none. */
+const betterAuthActorNames = (auth) => async (ids) => {
+	const { internalAdapter } = await auth.$context;
+	const users = await Promise.all(ids.map((id) => internalAdapter.findUserById(id)));
+	return Object.fromEntries(users.flatMap((user) => user?.name ? [[user.id, user.name]] : []));
+};
+//#endregion
+export { betterAuthActorNames };

package/dist/history/history-sql.js

@@ -0,0 +1,31 @@
+import { quoteIdent } from "../changes/capture-sql.js";
+//#region src/history/history-sql.ts
+/**
+* The history of the resources with `.history()`: a row per record and transaction, as events see the change. `before`
+* and `after` are the fields by name, without sensitive ones; `changed` names the fields an update changed, sensitive
+* ones included. `actor_id` and `actor_roles` are the API's caller, `null` for a write from elsewhere; `database_role`
+* is the role that wrote, `null` for a change captured before Protobase kept it.
+*/
+const historyTableSql = (schema) => {
+	const table = `${quoteIdent(schema)}."history"`;
+	return `create table if not exists ${table} (
+  "id" bigint generated always as identity primary key,
+  "resource" text not null,
+  "record_key" text not null,
+  "tenant_id" text,
+  "operation" text not null check ("operation" in ('create', 'update', 'delete', 'undelete')),
+  "before" jsonb,
+  "after" jsonb,
+  "changed" jsonb not null,
+  "actor_id" text,
+  "actor_roles" jsonb,
+  "database_role" text,
+  "transaction" bigint not null,
+  "at" timestamptz not null
+);
+create index if not exists "history_record" on ${table} ("resource", "record_key", "id");
+create index if not exists "history_tenant" on ${table} ("tenant_id", "id");
+create index if not exists "history_at" on ${table} ("at")`;
+};
+//#endregion
+export { historyTableSql };

package/dist/history/options.d.ts

@@ -0,0 +1,7 @@
+//#region src/history/options.d.ts
+/** How long record history is kept (`history` in `protobase.config.ts`). */
+export type HistoryOptions = {
+  /** Days a change is kept; a daily job deletes older ones. Kept forever when omitted. */
+  days?: number;
+};
+//#endregion

package/dist/history/options.js

@@ -0,0 +1,9 @@
+//#region src/history/options.ts
+/** The days of the options, checked: a positive whole number, or none. */
+const historyDays = (options = {}) => {
+	const { days } = options;
+	if (days !== void 0 && (!Number.isInteger(days) || days < 1)) throw new Error(`history.days must be a positive whole number of days, not ${days}`);
+	return days;
+};
+//#endregion
+export { historyDays };

package/dist/history/prune-history.js

@@ -0,0 +1,26 @@
+import { quoteIdent } from "../changes/capture-sql.js";
+import { defineJob } from "../jobs/define-job.js";
+import { sql } from "kysely";
+//#region src/history/prune-history.ts
+/** Rows one delete removes, so a first prune of a long history does not hold one long transaction. */
+const batchSize = 1e4;
+/** Deletes the changes older than `days`, in batches; returns how many went. */
+const pruneHistory = async (db, schema, days) => {
+	const table = sql.raw(`${quoteIdent(schema)}."history"`);
+	let total = 0;
+	for (;;) {
+		const result = await sql`delete from ${table} where "id" in (select "id" from ${table} where "at" < now() - make_interval(days => ${days}) order by "id" limit ${batchSize})`.execute(db);
+		const deleted = Number(result.numAffectedRows ?? 0);
+		total += deleted;
+		if (deleted < batchSize) return total;
+	}
+};
+/** The daily job that keeps record history to `days`. */
+const pruneHistoryJob = (schema, days) => defineJob({
+	name: "history.prune",
+	schedule: "41 3 * * *",
+	timeout: "30 minutes",
+	run: async (_payload, { db }) => void await pruneHistory(db, schema, days)
+});
+//#endregion
+export { pruneHistory, pruneHistoryJob };

package/dist/history/read-history.js

@@ -0,0 +1,72 @@
+import { notFound } from "../problem.js";
+import { tenantScope } from "../tenant.js";
+import { requestAccess, requireOperation } from "../request-access.js";
+import { readTransaction } from "../transactions.js";
+import { fetchReadable } from "../read-service.js";
+import { quoteIdent } from "../changes/capture-sql.js";
+import { parseParams } from "../params.js";
+import { encodeKey } from "@protobase/schema/internal";
+import { sql } from "kysely";
+import { z } from "zod";
+//#region src/history/read-history.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;
+const picked = (row, names) => row ? Object.fromEntries(Object.entries(row).filter(([name]) => names.has(name))) : void 0;
+const shown = (row, readable, names) => {
+	const values = new Set(Object.values(readable.fields).filter((field) => !field.sensitive && !field.file).map((field) => field.name));
+	const changed = row.changed.filter((name) => Object.hasOwn(readable.fields, name));
+	if (row.operation === "update" && changed.length === 0) return [];
+	const before = picked(row.before, values);
+	const after = picked(row.after, values);
+	const name = row.actor_id === null ? void 0 : names[row.actor_id];
+	return [{
+		id: row.id,
+		at: row.at,
+		operation: row.operation,
+		changed,
+		...before && { before },
+		...after && { after },
+		actor: row.actor_id === null ? null : {
+			id: row.actor_id,
+			...name !== void 0 && { name }
+		},
+		database_role: row.database_role
+	}];
+};
+/**
+* A page of a record's history, 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. Each change carries only the fields the caller may read.
+*/
+const readHistory = async (deps, entry, session, key, query) => {
+	const { schema, actorNames } = deps.history ?? {};
+	if (!schema || !entry.model.history) throw notFound(`${entry.name} keeps no history`);
+	const { page_size, page_token } = parseParams(params, query);
+	const size = page_size || defaultPageSize;
+	const access = await requestAccess(deps, entry, session);
+	requireOperation(access, "read");
+	const keyFields = access.full.primaryKey.map((part) => access.full.fields[part]);
+	const tenant = tenantScope(entry, session)?.tenantValue;
+	const table = sql.raw(`${quoteIdent(schema)}."history"`);
+	const rows = await readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		if (!await fetchReadable(trx, access, key, entry.model.softDelete ? "show" : "hide", { fields: keyFields })) return void 0;
+		const { rows } = await sql`select "id"::text as id, to_char("at" at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') as at, "operation", "changed", "before", "after", "actor_id", "database_role"
+      from ${table} 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 = [...new Set(page.flatMap((row) => row.actor_id === null ? [] : [row.actor_id]))];
+	const names = ids.length > 0 && actorNames ? await actorNames(ids) : {};
+	return {
+		items: page.flatMap((row) => shown(row, access.readable, names)),
+		next_page_token: rows.length > size ? page.at(-1).id : ""
+	};
+};
+//#endregion
+export { readHistory };

package/dist/history/write-history.js

@@ -0,0 +1,43 @@
+import { quoteIdent } from "../changes/capture-sql.js";
+import { sql } from "kysely";
+//#region src/history/write-history.ts
+const historyRow = (change) => ({
+	resource: change.resource,
+	record_key: change.key,
+	tenant_id: change.tenant === void 0 ? null : String(change.tenant),
+	operation: change.operation,
+	before: change.before ?? null,
+	after: change.after ?? null,
+	changed: change.changed,
+	actor_id: change.actor?.id ?? null,
+	actor_roles: change.actor?.roles ?? null,
+	database_role: change.databaseRole,
+	transaction: change.transaction,
+	at: change.at
+});
+const typed = [
+	["resource", "text"],
+	["record_key", "text"],
+	["tenant_id", "text"],
+	["operation", "text"],
+	["before", "jsonb"],
+	["after", "jsonb"],
+	["changed", "jsonb"],
+	["actor_id", "text"],
+	["actor_roles", "jsonb"],
+	["database_role", "text"],
+	["transaction", "bigint"],
+	["at", "timestamptz"]
+];
+const columns = typed.map(([name]) => `"${name}"`).join(", ");
+const types = typed.map(([name, type]) => `"${name}" ${type}`).join(", ");
+/** Adds the changes to the history table, in their order: one statement, in the caller's transaction. */
+const writeHistory = async (db, schema, changes) => {
+	if (changes.length === 0) return;
+	const rows = JSON.stringify(changes.map(historyRow));
+	await sql`insert into ${sql.raw(`${quoteIdent(schema)}."history"`)} (${sql.raw(columns)})
+    select ${sql.raw(columns)} from rows from (jsonb_to_recordset(${rows}::jsonb) as (${sql.raw(types)})) with ordinality as r(${sql.raw(columns)}, "position")
+    order by "position"`.execute(db);
+};
+//#endregion
+export { writeHistory };

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { PlatformSignIn, readPlatformSignIn } from "./better-auth/platform-sign-
 import { EmailComponent, EmailOptions, EmailTemplate, RenderedEmail, defineEmail } from "./mail/define-email.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, createAuth, normalizeRoles } from "./better-auth/create-auth.js";
 import { EventsOptions } from "./changes/events-options.js";
+import { HistoryOptions } from "./history/options.js";
 import { StandardSchema, readJson } from "./functions/read-json.js";
 import { EnqueueOptions, JobContext, JobDefinition, JobOptions } from "./jobs/job-types.js";
 import { Admin, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, SessionOrganization, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
@@ -51,6 +52,7 @@ import { IssueTokenOptions, issueToken, maxTokenTtlSeconds } from "./better-auth
 import { webauthnPath } from "./better-auth/origins.js";
 import { authSchemaMigration, checkAuthSchema } from "./better-auth/auth-schema.js";
 import { changesMigration, checkChanges, migrationCommand } from "./changes/capture-schema.js";
+import { isCaptured } from "./changes/capture-sql.js";
 import { CapturedRow, CoalescedChange, coalesce } from "./changes/coalesce.js";
 import { ResourceChange, recordOf, resourceChange } from "./changes/resource-change.js";
 import { eventMatcher } from "./changes/match-events.js";
@@ -84,4 +86,4 @@ import { FatalJobError } from "./jobs/run-job.js";
 import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, beforeSignInPluginsVariable, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CapturedRow, type ChatMessage, type ChatTextPart, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSource, type HistoryOptions, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type MemberInput, MissingCredentials, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, beforeSignInPluginsVariable, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isCaptured, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/dist/index.js

@@ -11,6 +11,7 @@ import { withCacheBreakpoints } from "./assistant/cache-breakpoints.js";
 import { ModelError, streamChatCompletion } from "./assistant/chat-completions.js";
 import { formatUri, variantPath } from "./files/uri.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
+import { isCaptured } from "./changes/capture-sql.js";
 import { runTurn } from "./assistant/turn.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { webauthnPath } from "./better-auth/origins.js";
@@ -21,11 +22,11 @@ import { readPlatformSignIn } from "./better-auth/platform-sign-in.js";
 import { createAuth, normalizeRoles } from "./better-auth/create-auth.js";
 import { addAppRoleToOwners, addMember, createOrganization, listOrganizations, removeMember, setMemberRoles } from "./better-auth/organizations/host.js";
 import { createUser, deleteUser, hasUsers, listUsers, roleChoices, setUserBanned, setUserRole } from "./better-auth/users.js";
+import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js";
 import { coalesce } from "./changes/coalesce.js";
 import { eventMatcher } from "./changes/match-events.js";
 import { parseColumns, readOutbox } from "./changes/outbox.js";
 import { recordOf, resourceChange } from "./changes/resource-change.js";
-import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js";
 import { FatalJobError } from "./jobs/run-job.js";
 import { defineFunction } from "./functions/define-function.js";
 import { newWebhookSecret } from "./webhooks/standard-webhooks.js";
@@ -64,4 +65,4 @@ import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/p
 import { defineEmail } from "./mail/define-email.js";
 import { startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
-export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, beforeSignInPluginsVariable, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };
+export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, beforeSignInPluginsVariable, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, hasUsers, imageSize, isCaptured, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, limitedFileStore, listOrganizations, listUsers, localFileStore, localFiles, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storeFile, streamChatCompletion, subscription, thumbHash, unauthorized, variantPath, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps };

package/dist/openapi/resource-paths.js

@@ -325,6 +325,77 @@ const resourcePaths = (access) => {
 				...keyErrors
 			}
 		} } },
+		...entry.model.history && { [`/${entry.name}/{key}:history`]: { get: {
+			operationId: `history_${entry.name}`,
+			tags: tag,
+			summary: `The changes of a ${entry.name} record`,
+			description: "Newest first, with the same access as a get, a deleted record included. Each change carries only the fields the caller may read, never a sensitive value; an update of only other fields is left out.",
+			parameters: [
+				param("key"),
+				query("page_size", "Changes per page, at most 100 (default 20)", { type: "integer" }),
+				query("page_token", "The next_page_token of the previous page")
+			],
+			responses: {
+				200: {
+					description: "A page of changes",
+					content: json({
+						type: "object",
+						required: ["items", "next_page_token"],
+						properties: {
+							items: {
+								type: "array",
+								items: {
+									type: "object",
+									required: [
+										"id",
+										"at",
+										"operation",
+										"changed",
+										"actor",
+										"database_role"
+									],
+									properties: {
+										id: { type: "string" },
+										at: {
+											type: "string",
+											format: "date-time"
+										},
+										operation: {
+											type: "string",
+											enum: [
+												"create",
+												"update",
+												"delete",
+												"undelete"
+											]
+										},
+										changed: {
+											type: "array",
+											items: { type: "string" }
+										},
+										before: { type: "object" },
+										after: { type: "object" },
+										actor: {
+											type: ["object", "null"],
+											properties: {
+												id: { type: "string" },
+												name: { type: "string" }
+											}
+										},
+										database_role: { type: ["string", "null"] }
+									}
+								}
+							},
+							next_page_token: {
+								type: "string",
+								description: "Empty on the last page"
+							}
+						}
+					})
+				},
+				...keyErrors
+			}
+		} } },
 		[`/${entry.name}:facets`]: { get: {
 			operationId: `facets_${entry.name}`,
 			tags: tag,

package/dist/project-config.d.ts

@@ -1,5 +1,6 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
 import { EventsOptions } from "./changes/events-options.js";
+import { HistoryOptions } from "./history/options.js";
 import { Authenticator } from "./types.js";
 import { WebhooksOptions } from "./webhooks/table/options.js";
 import { FilesOptions } from "./files/options.js";
@@ -25,6 +26,8 @@ export type ProjectConfig = {
   files?: FilesOptions;
   /** Where the changes that resources' events are raised from are captured (see `EventsOptions`). */
   events?: EventsOptions;
+  /** How long the history of resources with `.history()` is kept (see `HistoryOptions`). */
+  history?: HistoryOptions;
   /** Webhook subscriptions made in the admin app; set by `extends: [webhooks()]` (see `WebhooksOptions`). */
   webhooks?: WebhooksOptions;
   /** The module of the app's jobs, e.g. `import * as jobs from './config/jobs'`: every `defineJob` it exports. */

package/dist/project-config.js

@@ -143,11 +143,12 @@ const mergedOptions = (named) => {
 */
 const mergeConfig = (...configs) => {
 	const named = configs.flatMap((config, index) => flatten(config, config.name ?? `config ${index + 1}`));
-	const { db, authenticate, auth, events, webhooks } = lastSet(named.map(({ config }) => ({
+	const { db, authenticate, auth, events, history, webhooks } = lastSet(named.map(({ config }) => ({
 		db: config.db,
 		authenticate: config.authenticate,
 		auth: config.auth,
 		events: config.events,
+		history: config.history,
 		webhooks: config.webhooks
 	})));
 	const module = mergedModule(named);
@@ -165,6 +166,7 @@ const mergeConfig = (...configs) => {
 		...functions && { functions },
 		...files && { files },
 		...events && { events },
+		...history && { history },
 		...webhooks && { webhooks },
 		...jobs && { jobs },
 		...options && { options }

package/dist/routes/record.js

@@ -8,12 +8,14 @@ import { deletedRows, selectedFields } from "../params.js";
 import { returnPreference } from "./preferences.js";
 import { resolveTarget } from "./target.js";
 import { revealField } from "../reveal-service.js";
+import { readHistory } from "../history/read-history.js";
 import { Hono } from "hono";
 //#region src/routes/record.ts
 const recordRoutes = (deps) => {
 	const app = new Hono();
 	app.get("/:resource/:key", async (c) => {
 		const { entry } = resolveTarget(deps, c.req.param("resource"));
+		if (c.req.param("key").endsWith(":history")) return c.json(await readHistory(deps, entry, c.get("session"), keyFromPath(c, entry, ":history"), c.req.query()));
 		const deleted = deletedRows(entry.model, c.req.query("show_deleted") === "true");
 		const found = await readRecord(deps, entry, c.get("session"), keyFromPath(c, entry), deleted);
 		const columns = selectedFields({

package/dist/validate-body.js

@@ -2,6 +2,20 @@ import { badRequest } from "./problem.js";
 import { writableFields } from "./request-access.js";
 //#region src/validate-body.ts
 const fail = (errors) => badRequest("invalid-record", `The request body is invalid: ${errors[0].field}: ${errors[0].message}`, { errors });
+const paramsOf = (issue) => {
+	if (issue.code === "too_small") return { min: Number(issue.minimum) };
+	if (issue.code === "too_big") return { max: Number(issue.maximum) };
+	if (issue.code === "custom") return issue.params;
+};
+const invalidValue = (field, issue) => {
+	const params = paramsOf(issue);
+	return {
+		field,
+		code: "invalid-value",
+		message: issue.message,
+		...params && { params }
+	};
+};
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const reserved = ["etag", "permissions"];
 const isEmptyText = (field, value) => field.type === "text" && !field.nullable && value === "";
@@ -62,11 +76,7 @@ const validateBody = (access, mode, body, current = {}) => {
 			code: "required",
 			message: `"${name}" is required`
 		});
-		else errors.push(...parsed.error.issues.map((issue) => ({
-			field: name,
-			code: "invalid-value",
-			message: issue.message
-		})));
+		else errors.push(...parsed.error.issues.map((issue) => invalidValue(name, issue)));
 	}
 	if (errors.length > 0) throw fail(errors);
 	const merged = {

package/dist/view-access.js

@@ -172,7 +172,13 @@ const layoutShape = (resource, model, models) => shapes.oneOf({
 		sidebar: shapes.data,
 		when: shapes.data
 	}, { requires: ["latitude", "longitude"] }),
-	gallery: shapes.map((item) => pruneGallery(item, resource, model, models))
+	gallery: shapes.map((item) => pruneGallery(item, resource, model, models)),
+	history: shapes.object({
+		kind: shapes.data,
+		title: shapes.data,
+		limit: shapes.data,
+		when: shapes.data
+	})
 });
 const linkShape = (model, models) => shapes.map((run) => {
 	return ("to" in run ? addressErrors(run.to, {

package/dist/webhooks/webhooks.js

@@ -1,11 +1,12 @@
-import { dispatchJobName } from "../changes/capture-sql.js";
+import { dispatchJobName, isCaptured } from "../changes/capture-sql.js";
+import { defineJob } from "../jobs/define-job.js";
 import { coalesce } from "../changes/coalesce.js";
 import { EventCodeError } from "../changes/event-code-error.js";
 import { eventMatcher } from "../changes/match-events.js";
 import { deleteOutbox, readOutbox } from "../changes/outbox.js";
 import { resourceChange } from "../changes/resource-change.js";
 import { callerRecords } from "../functions/records.js";
-import { defineJob } from "../jobs/define-job.js";
+import { writeHistory } from "../history/write-history.js";
 import { FatalJobError } from "../jobs/run-job.js";
 import { maxTries, nextRetryDelay } from "./retry-schedule.js";
 import { subscriberEvents } from "./subscriber-view.js";
@@ -40,7 +41,8 @@ const deliveryGroup = ({ subscription, change }) => `${subscription.name}:${chan
 *
 * - `changes.dispatch`, which `capture()` enqueues once per writing transaction, in one ordered group so one runs at a
 *   time: it turns the committed outbox rows into events, makes the first try of every unordered delivery itself,
-*   queues the failures and the ordered deliveries, and deletes the rows in that same transaction. A process that dies
+*   queues the failures and the ordered deliveries, keeps the changes of resources with history, and deletes the rows
+*   in that same transaction. A process that dies
 *   before that commits leaves the rows, and the job's retry delivers them again, under the same `webhook-id`.
 * - `webhooks.dispatch-change`, one change whose app code threw in dispatch: an event's `match` or filter, a
 *   subscription's `when`, or an access rule of its roles. Kept as failed, so dispatch moves on to later changes; a
@@ -52,14 +54,14 @@ const deliveryGroup = ({ subscription, change }) => `${subscription.name}:${chan
 *
 * With `table`, also `webhooks.send-test`, which Send test event queues, and with its log `webhooks.prune-log`, daily.
 *
-* No jobs without a resource with events; the subscriptions must name declared events.
+* No jobs without a resource with events or history; the subscriptions must name declared events.
 */
 const createWebhooks = ({ deps, subscriptions, functions, schema, log, table }) => {
 	const entries = deps.registry.entries;
 	const models = entries.map((entry) => entry.model);
 	const problems = subscriptionProblems(subscriptions, models, Object.keys(functions));
 	if (problems.length > 0) throw new Error(problems.join("; "));
-	if (!models.some((model) => model.events)) return { jobs: [] };
+	if (!models.some(isCaptured)) return { jobs: [] };
 	const matchers = new Map(entries.map((entry) => [entry.name, eventMatcher(entry.model, entry.source.eventMatches?.() ?? {})]));
 	const keyColumns = (resource) => {
 		const model = deps.registry.find(resource)?.model;
@@ -230,6 +232,7 @@ const createWebhooks = ({ deps, subscriptions, functions, schema, log, table })
 			}
 			await queueOrdered(trx, deliveries);
 			for (const { change } of failures) await dispatchChange.enqueue(trx, { change });
+			await writeHistory(trx, schema, changes.filter((change) => deps.registry.find(change.resource)?.model.history));
 			await deleteOutbox(trx, schema, rows.map((row) => row.id));
 		});
 		for (const [index, { subscription, event }] of now.entries()) report(subscription.name, event, 1, results[index]);

package/package.json

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