@protobase/server 0.3.5 → 0.5.0

package/dist/admin-options.d.ts

@@ -0,0 +1,35 @@
+import { AuditQueue, PipelineHook, ScanGuardMode } from "./types.js";
+import { AssistantOptions } from "./assistant/assistant-settings.js";
+import { RuntimeOptions } from "./runtime/runtime-settings.js";
+import { ResolveOptions } from "@protobase/schema";
+//#region src/admin-options.d.ts
+export type AdminOptions = {
+  /** Default `/api/v1`. */
+  basePath?: string;
+  /** Applied to every request's transaction with SET LOCAL. Default 15000. */
+  statementTimeoutMs?: number;
+  /** List shapes that would sequentially scan a table of more than `seqScanRows` rows (default 10000). Default mode `reject`. */
+  scanGuard?: {
+    mode?: ScanGuardMode;
+    seqScanRows?: number;
+  };
+  /** Runs inside the write transaction after each create, update and delete. */
+  writeHooks?: PipelineHook[];
+  /** The project's roles (from `defineRoles`): an operation without an access rule needs the matching capability. */
+  roles?: ResolveOptions['roles'];
+  /** What an operation without a rule does; overrides the capability check. Without `roles` the default is allow. */
+  defaultAccess?: ResolveOptions['defaultAccess'];
+  /** Whether list items carry their `permissions` (update, delete): true by default, or `{ except: [...] }` for resources that opt out. */
+  rowPermissions?: boolean | {
+    except: string[];
+  };
+  /** Receives an event for every reveal of a sensitive field. Default: printed to the console, nothing kept. */
+  audit?: AuditQueue;
+  /** Called with every error the API turns into a 500, so the host can report it. */
+  onUnhandledError?: (error: unknown) => void;
+  /** The assistant in the admin app's dock: a backend elsewhere or the built-in one (see `AssistantOptions`); `false` turns it off. */
+  assistant?: AssistantOptions | false;
+  /** The runtime updates endpoint behind the top bar's update button (see `RuntimeOptions`); `false` turns it off. */
+  runtime?: RuntimeOptions | false;
+};
+//#endregion

package/dist/aggregate-service.js

@@ -1,8 +1,8 @@
 import { badRequest } from "./problem.js";
+import { columnId, filterCondition, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { checkedFilter } from "./filter-input.js";
 import { readScope, requestAccess, requireOperation } from "./request-access.js";
 import { readTransaction } from "./transactions.js";
-import { columnId, filterCondition, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { parseParams } from "./params.js";
 import { facetCounts, histogram, series } from "@protobase/query";
 import { sql } from "kysely";

package/dist/assistant/assistant-settings.d.ts

@@ -1,16 +1,12 @@
+import { ModelSettings } from "./chat-completions.js";
+import { AssistantTool } from "./tools.js";
 //#region src/assistant/assistant-settings.d.ts
-/** An OpenAI-compatible chat completions endpoint for the built-in assistant. */
-export type ModelSettings = {
-  baseUrl: string;
-  apiKey: string;
-  model: string;
-  fetch?: typeof fetch;
-};
 /**
  * `url`: an assistant backend elsewhere, which the dock talks to instead of the built-in one.
  * `apiKey`, `model`, `baseUrl`: the built-in assistant, which answers questions about the app with a chat model.
  * `chats`: the directory the built-in assistant keeps conversations in, one file each.
  * Each falls back to its environment variable; `fetch` replaces the model endpoint, for tests.
+ * `tools`: the app's own tools, which the built-in assistant offers after its own; a backend elsewhere has its own.
  */
 export type AssistantOptions = {
   url?: string;
@@ -19,6 +15,7 @@ export type AssistantOptions = {
   baseUrl?: string;
   chats?: string;
   fetch?: typeof fetch;
+  tools?: AssistantTool[];
 };
 export type AssistantSettings = {
   kind: 'external';

package/dist/assistant/built-in-assistant.js

@@ -6,16 +6,31 @@ import { assistantProtocolRoutes } from "./protocol-routes.js";
 import { readOnlyQueryTool, readWriteQueryTool } from "./query-tools.js";
 import { runTurn } from "./turn.js";
 //#region src/assistant/built-in-assistant.ts
+const toolName = /^[A-Za-z0-9_-]{1,64}$/;
+/** The tools in order; a name a model endpoint refuses, or one taken twice, stops the server at startup. */
+const checkedTools = (tools) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const tool of tools) {
+		if (!toolName.test(tool.name)) throw new Error(`Assistant tool name "${tool.name}" must be 1 to 64 letters, digits, _ or -`);
+		if (seen.has(tool.name)) throw new Error(`Two assistant tools are named "${tool.name}"; give one of them another name`);
+		seen.add(tool.name);
+	}
+	return tools;
+};
 const pageContext = (page) => page && `The user is on the page ${page} of the app (/<resource> lists records, /<resource>/<key> shows one).`;
 /**
 * Protobase's own assistant: answers questions about the app, reads its data with read-only queries and proposes
-* changes the user approves, for callers with the `admin` or `ai` role. Made only of the exported building blocks and
-* its prompt, which describes what the caller may see of the app. Conversations are files in the `chats` directory.
-* On OpenRouter it caches the prompt and asks for little reasoning.
+* changes the user approves, with the app's own tools besides, for callers with the `admin` or `ai` role. Made only of
+* the exported building blocks and its prompt, which describes what the caller may see of the app. Conversations are
+* files in the `chats` directory. On OpenRouter it caches the prompt and asks for little reasoning.
 */
-const builtInAssistant = ({ model, chats, db, meta, authenticate, report }) => {
+const builtInAssistant = ({ model, chats, db, meta, authenticate, tools: appTools = [], records, report }) => {
 	const conversations = createConversations({ store: fileConversationStore(chats) });
-	const tools = [readOnlyQueryTool(db), readWriteQueryTool(db)];
+	const tools = checkedTools([
+		readOnlyQueryTool(db),
+		readWriteQueryTool(db),
+		...appTools
+	]);
 	const onOpenRouter = model.baseUrl === openRouterUrl;
 	return assistantProtocolRoutes({
 		authenticate,
@@ -30,6 +45,7 @@ const builtInAssistant = ({ model, chats, db, meta, authenticate, report }) => {
 				session,
 				system: appContext(body.resources, body.views),
 				tools,
+				...records && { records: records(session) },
 				report,
 				...page && { context: pageContext(page) },
 				...onOpenRouter && {

package/dist/assistant/chat-completions.d.ts

@@ -1,5 +1,11 @@
-import { ModelSettings } from "./assistant-settings.js";
 //#region src/assistant/chat-completions.d.ts
+/** An OpenAI-compatible chat completions endpoint for the built-in assistant. */
+export type ModelSettings = {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  fetch?: typeof fetch;
+};
 export type ToolCall = {
   id: string;
   type: 'function';

package/dist/assistant/conversations.d.ts

@@ -1,5 +1,5 @@
-import { Session } from "../types.js";
 import { ChatMessage } from "./chat-completions.js";
+import { Session } from "../types.js";
 import { ConversationStore } from "./conversation-store.js";
 import { AssistantEvent, AssistantState } from "@protobase/schema";
 //#region src/assistant/conversations.d.ts

package/dist/assistant/records.d.ts

@@ -0,0 +1,23 @@
+import { Row } from "../types.js";
+import "../deps.js";
+//#region src/assistant/records.d.ts
+/** A record's key: its URL text (`a,b` when composite), a scalar, or its parts. */
+export type RecordKeyInput = string | number | Array<string | number>;
+/** A record as the user may see it, with the ETag a later update can pass to fail when someone changed it since. */
+export type ToolRecord = {
+  record: Row;
+  etag: string;
+};
+/**
+ * The app's resources as the session's user: their access rules, tenant scope, validation and write hooks apply as
+ * in the REST API. A refusal or a missing record rejects with an `HttpProblem`, which a tool can turn into text.
+ */
+export type ToolRecords = {
+  get: (resource: string, key: RecordKeyInput) => Promise<ToolRecord>;
+  create: (resource: string, data: Row) => Promise<ToolRecord>;
+  /** With `etag`, fails with 412 when the record changed since it was read; without, it updates any version. */
+  update: (resource: string, key: RecordKeyInput, data: Row, options?: {
+    etag?: string;
+  }) => Promise<ToolRecord>;
+};
+//#endregion

package/dist/assistant/records.js

@@ -0,0 +1,53 @@
+import { notFound } from "../problem.js";
+import { decodeKeyText } from "../key.js";
+import { readRecord } from "../read-service.js";
+import { runWrite } from "../write-pipeline.js";
+import { encodeKey } from "@protobase/schema";
+//#region src/assistant/records.ts
+/** `ToolRecords` over the admin's resources for `session`. */
+const assistantRecords = (deps, session) => {
+	const entryOf = (resource) => {
+		const entry = deps.registry.find(resource);
+		if (!entry) throw notFound(`There is no resource "${resource}"`);
+		return entry;
+	};
+	const keyOf = (resource, key) => {
+		const entry = entryOf(resource);
+		return {
+			entry,
+			key: decodeKeyText(entry, Array.isArray(key) ? encodeKey(key) : String(key))
+		};
+	};
+	return {
+		get: async (resource, input) => {
+			const { entry, key } = keyOf(resource, input);
+			const { record, etag } = await readRecord(deps, entry, session, key);
+			return {
+				record,
+				etag
+			};
+		},
+		create: async (resource, data) => runWrite(deps, entryOf(resource), session, {
+			operation: "create",
+			body: data
+		}),
+		update: async (resource, input, data, { etag } = {}) => {
+			const { entry, key } = keyOf(resource, input);
+			return runWrite(deps, entry, session, {
+				operation: "update",
+				key,
+				body: data,
+				ifMatch: etag ?? "*"
+			});
+		}
+	};
+};
+const withoutAdmin = () => Promise.reject(/* @__PURE__ */ new Error("This assistant has no records: ToolContext.records works in the built-in assistant"));
+/** Records for a turn without an admin around it, such as in a backend of its own: every call fails. */
+const noRecords = {
+	get: withoutAdmin,
+	create: withoutAdmin,
+	update: withoutAdmin
+};
+//#endregion
+export { assistantRecords, noRecords };

package/dist/assistant/tools.d.ts

@@ -1,6 +1,7 @@
 import { Session } from "../types.js";
 import { Conversation } from "./conversations.js";
 import { ApprovalAnswer, ApprovalRequest } from "./approval.js";
+import { ToolRecords } from "./records.js";
 import { AssistantPart } from "@protobase/schema";
 //#region src/assistant/tools.d.ts
 export type ToolContext = {
@@ -10,6 +11,8 @@ export type ToolContext = {
   show: (part: AssistantPart) => void;
   /** Asks the user to approve with a card in that message (see `requestApproval`). */
   approve: (request: ApprovalRequest) => Promise<ApprovalAnswer>;
+  /** The app's resources as the session's user, through their access rules and write hooks (built-in assistant only). */
+  records: ToolRecords;
 };
 /**
  * A function the model may call during a turn. `parameters` is the JSON Schema of its arguments; `run` gets them

package/dist/assistant/turn.d.ts

@@ -1,7 +1,7 @@
-import { ModelSettings } from "./assistant-settings.js";
+import { ModelSettings, ReasoningEffort } from "./chat-completions.js";
 import { Session } from "../types.js";
-import { ReasoningEffort } from "./chat-completions.js";
 import { Conversation } from "./conversations.js";
+import { ToolRecords } from "./records.js";
 import { AssistantTool } from "./tools.js";
 //#region src/assistant/turn.d.ts
 export type TurnOptions = {
@@ -11,6 +11,8 @@ export type TurnOptions = {
   /** The system prompt. */
   system: string;
   tools?: AssistantTool[];
+  /** What tools get as `records`; without it, their calls fail. */
+  records?: ToolRecords;
   /** Model calls in one turn before it stops. Default 8. */
   maxSteps?: number;
   /** Gets errors other than the model endpoint's refusals, which the user only sees as a failure. */

package/dist/assistant/turn.js

@@ -1,6 +1,7 @@
 import { requestApproval } from "./approval.js";
 import { withCacheBreakpoints } from "./cache-breakpoints.js";
 import { ModelError, streamChatCompletion } from "./chat-completions.js";
+import { noRecords } from "./records.js";
 //#region src/assistant/turn.ts
 const toolResult = async (call, tools, context) => {
 	const tool = tools.find((entry) => entry.name === call.function.name);
@@ -39,7 +40,8 @@ const runTurn = async (options, text) => {
 		session,
 		conversation,
 		show,
-		approve: (request) => requestApproval(conversation, messageId, request)
+		approve: (request) => requestApproval(conversation, messageId, request),
+		records: options.records ?? noRecords
 	};
 	const specs = tools.map((tool) => ({
 		type: "function",

package/dist/assistant/widget.d.ts

@@ -0,0 +1,15 @@
+import { AssistantWidgetPart } from "@protobase/schema";
+//#region src/assistant/widget.d.ts
+/** The most a widget's props may take, as JSON in UTF-8: room for ids and settings, not for the state it shows. */
+export declare const maxWidgetPropsBytes = 2048;
+export type WidgetOptions = {
+  id?: string;
+  fallback?: AssistantWidgetPart['fallback'];
+};
+/**
+ * A widget part for `show`: the app's component `name` draws it with `props`, fetching what it shows itself. A name
+ * that is not PascalCase, or props that are not a JSON object of at most 2 KB, throw, so a tool cannot keep state in
+ * the chat by accident. Without an `id`, the part gets a new one; show a part with the same id again to replace it.
+ */
+export declare const widget: (name: string, props: Record<string, unknown>, options?: WidgetOptions) => AssistantWidgetPart;
+//#endregion

package/dist/assistant/widget.js

@@ -0,0 +1,32 @@
+//#region src/assistant/widget.ts
+const componentName = /^[A-Z][A-Za-z0-9]*$/;
+/** The most a widget's props may take, as JSON in UTF-8: room for ids and settings, not for the state it shows. */
+const maxWidgetPropsBytes = 2048;
+const isPlainObject = (value) => typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+const isJson = (value) => {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJson);
+	return isPlainObject(value) && Object.values(value).every(isJson);
+};
+/**
+* A widget part for `show`: the app's component `name` draws it with `props`, fetching what it shows itself. A name
+* that is not PascalCase, or props that are not a JSON object of at most 2 KB, throw, so a tool cannot keep state in
+* the chat by accident. Without an `id`, the part gets a new one; show a part with the same id again to replace it.
+*/
+const widget = (name, props, options = {}) => {
+	if (!componentName.test(name)) throw new Error(`Widget name "${name}" must be PascalCase, such as TaskProposal`);
+	if (!isPlainObject(props) || !isJson(props)) throw new Error(`The props of widget ${name} must be a JSON object`);
+	const bytes = new TextEncoder().encode(JSON.stringify(props)).length;
+	if (bytes > 2048) throw new Error(`The props of widget ${name} take ${bytes} bytes, more than ${maxWidgetPropsBytes}; pass ids and let the widget fetch the rest`);
+	const { id = crypto.randomUUID(), fallback } = options;
+	return {
+		type: "widget",
+		id,
+		name,
+		props,
+		...fallback && { fallback }
+	};
+};
+//#endregion
+export { maxWidgetPropsBytes, widget };

package/dist/batch/reorder.js

@@ -1,10 +1,10 @@
 import { badRequest } from "../problem.js";
-import { tenantScope } from "../tenant.js";
-import { requireOperation, targetFilter, writableFields } from "../request-access.js";
 import { columnId, keyConditions, scopeConditions, tableId, whereClause } from "../sql-parts.js";
 import { fetchRecord } from "../records.js";
-import { missing, shown } from "../write-shared.js";
+import { tenantScope } from "../tenant.js";
+import { requireOperation, targetFilter, writableFields } from "../request-access.js";
 import { validateBody } from "../validate-body.js";
+import { missing, shown } from "../write-shared.js";
 import { applyUpdate, planUpdate } from "../write-update.js";
 import { encodeKey } from "@protobase/schema";
 import { sql } from "kysely";

package/dist/better-auth/admin-only.js

@@ -0,0 +1,13 @@
+import { parseRoles } from "./parse-roles.js";
+import { APIError, createAuthMiddleware, sessionMiddleware } from "better-auth/api";
+//#region src/better-auth/admin-only.ts
+/** Lets a request through only with the session of an admin; others get `403 ADMIN_ONLY` with `message`. */
+const adminOnly = (message) => createAuthMiddleware({ use: [sessionMiddleware] }, async (ctx) => {
+	if (!parseRoles(ctx.context.session.user.role).includes("admin")) throw new APIError("FORBIDDEN", {
+		code: "ADMIN_ONLY",
+		message
+	});
+	return { session: ctx.context.session };
+});
+//#endregion
+export { adminOnly };