@protobase/server 0.19.16 → 0.21.0

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

@@ -130,6 +130,7 @@ const needs = {
 	list: "list",
 	search: "list",
 	facets: "list",
+	aggregate: "list",
 	series: "list",
 	histogram: "list",
 	map: "list",
@@ -324,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,
@@ -363,6 +435,71 @@ const resourcePaths = (access) => {
 				...auth
 			}
 		} },
+		[`/${entry.name}:aggregate`]: { get: {
+			operationId: `aggregate_${entry.name}`,
+			tags: tag,
+			summary: `Totals per group of ${entry.name} records`,
+			description: "Groups the records the filter finds, its own terms on `group_by` included, by the value of a field, or by the hour, day, week, month or year of a date or timestamp field with the empty ones included. Each group has its count and, with `sum` or `average`, that of a numeric field, `null` when no record of the group has a value. Value groups come largest first. An index must serve the grouped field.",
+			parameters: [
+				query("group_by", "A filterable field", { type: "string" }, true),
+				param("filter"),
+				query("sum", "A numeric field to add up per group"),
+				query("average", "A numeric field to average per group, instead of `sum`"),
+				query("limit", "Most value groups to return, default 100, at most 1000", { type: "integer" }),
+				query("label", "For a relation to a single-key resource: the field of that resource whose value each group carries as `label`"),
+				query("granularity", "For a date group_by: the bucket, default day", {
+					type: "string",
+					enum: [
+						"hour",
+						"day",
+						"week",
+						"month",
+						"year"
+					]
+				}),
+				query("range", "For a date group_by: the relative range ending now (default 30d); `all` starts at the earliest row", {
+					type: "string",
+					enum: [
+						"7d",
+						"30d",
+						"90d",
+						"1y",
+						"all"
+					]
+				}),
+				query("from", "For a date group_by: the explicit start (ISO 8601); with `to`, replaces range"),
+				query("to", "For a date group_by: the exclusive end (ISO 8601), default now"),
+				query("time_zone", "For a date group_by: the IANA time zone of the buckets, default UTC")
+			],
+			responses: {
+				200: {
+					description: "The groups; a date group's `value` is its bucket in local ISO time",
+					content: json({
+						type: "object",
+						properties: {
+							group_by: { type: "string" },
+							granularity: { type: "string" },
+							time_zone: { type: "string" },
+							groups: {
+								type: "array",
+								items: {
+									type: "object",
+									properties: {
+										value: {},
+										label: { type: "string" },
+										count: { type: "integer" },
+										sum: { type: ["number", "null"] },
+										average: { type: ["number", "null"] }
+									}
+								}
+							}
+						}
+					})
+				},
+				400: error("BadRequest"),
+				...auth
+			}
+		} },
 		[`/${entry.name}:series`]: { get: {
 			operationId: `series_${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/collection.js

@@ -1,6 +1,7 @@
 import { runWrite } from "../write-pipeline.js";
 import { listRecords } from "../list-service.js";
 import { facets, numericHistogram, timeSeries } from "../aggregate-service.js";
+import { aggregate } from "../aggregate-groups.js";
 import { mapRecords } from "../map-service.js";
 import { uploadFile } from "../files/upload.js";
 import { returnPreference } from "./preferences.js";
@@ -25,6 +26,10 @@ const collectionRoutes = (deps) => {
 			const { body, warning } = await facets(deps, entry, session, query);
 			return c.json(body, 200, warningHeader(warning));
 		}
+		if (action === "aggregate") {
+			const { body, warning } = await aggregate(deps, entry, session, query);
+			return c.json(body, 200, warningHeader(warning));
+		}
 		if (action === "series") return c.json(await timeSeries(deps, entry, session, query));
 		if (action === "histogram") return c.json(await numericHistogram(deps, entry, session, query));
 		if (action === "map") {