@protobase/server 0.11.0 → 0.11.1

package/dist/admin-options.d.ts

@@ -1,4 +1,5 @@
 import { AuditQueue, PipelineHook, ScanGuardMode } from "./types.js";
+import { PluginOption } from "./plugins/plugin-settings.js";
 import { CorsOrigins } from "./api-cors.js";
 import { AssistantOptions } from "./assistant/assistant-settings.js";
 import { RuntimeOptions } from "./runtime/runtime-settings.js";
@@ -39,5 +40,10 @@ export type AdminOptions = {
   cors?: CorsOrigins;
   /** The runtime updates endpoint behind the top bar's update button (see `RuntimeOptions`); `false` turns it off. */
   runtime?: RuntimeOptions | false;
+  /**
+   * The plugins the admin app loads (see `PluginOption`), before the ones the platform lists in `PROTOBASE_PLUGINS`;
+   * `false` turns both off.
+   */
+  plugins?: PluginOption[] | false;
 };
 //#endregion

package/dist/create-admin.js

@@ -19,6 +19,7 @@ import { checkViews } from "./check-views.js";
 import { createFilesRuntime } from "./files/runtime.js";
 import { fileRoutes } from "./files/routes.js";
 import { functionRoutes } from "./functions/routes.js";
+import { pluginOptions } from "./plugins/plugin-settings.js";
 import { runtimeUrl } from "./runtime/runtime-settings.js";
 import { createMeta } from "./meta.js";
 import { buildRegistry } from "./registry.js";
@@ -58,6 +59,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 	const systemPath = basePath.slice(0, basePath.lastIndexOf("/"));
 	const assistant = assistantSettings(options.assistant, globalThis.process?.env ?? {});
 	const runtime = runtimeUrl(options.runtime, globalThis.process?.env ?? {});
+	const plugins = pluginOptions(options.plugins, globalThis.process?.env ?? {});
 	const files = createFilesRuntime({
 		...filesOptions && { options: filesOptions },
 		env: globalThis.process?.env ?? {},
@@ -85,6 +87,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		rowPermissions: (resource) => typeof options.rowPermissions === "object" ? !options.rowPermissions.except.includes(resource) : options.rowPermissions !== false,
 		...assistant && { assistant: assistant.kind === "external" ? assistant.url : `${systemPath}/assistant` },
 		...runtime && { runtime },
+		plugins,
 		...files && { files },
 		...registry.entries.some((entry) => entry.model.events) && { actorSetting: `${changesSchema(events)}.actor` }
 	};

package/dist/deps.d.ts

@@ -1,5 +1,6 @@
 import "./types.js";
 import "./files/runtime.js";
+import "./plugins/plugin-settings.js";
 import "./registry.js";
 import "./scan-guard.js";
 import { PageModel } from "@protobase/layout";

package/dist/index.d.ts

@@ -16,6 +16,7 @@ import { FileProvider, FileStore, StoredObject } from "./files/store.js";
 import { FilesOptions } from "./files/options.js";
 import { CleanupEntry, CleanupSchedule, ScheduledDelete, storageCleanupSchedule } from "./files/cleanup-schedule.js";
 import { CleanupReport } from "./files/cleanup-runner.js";
+import { PluginOption, PluginRef, pluginOptions, pluginsFor, pluginsVariable } from "./plugins/plugin-settings.js";
 import { ResourceSource, configExports } from "./resource-source.js";
 import { RecordKeyInput, ToolRecord, ToolRecords } from "./assistant/records.js";
 import { FunctionRecords, ListParams, RecordPage } from "./functions/records.js";
@@ -68,4 +69,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 EnqueueOptions, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileObject, type FileProvider, type FileStore, 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 MemberInput, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, 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 ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type SignInPolicy, type SignInRule, type SignatureOptions, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, 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 TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints };
+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 EnqueueOptions, type EventData, type EventsOptions, FatalJobError, type FileCleanupInput, type FileObject, type FileProvider, type FileStore, 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 MemberInput, 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 ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type ScanGuardMode, type ScheduledDelete, type Session, type SessionOrganization, type SignInPolicy, type SignInRule, type SignatureOptions, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, 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 TurnOptions, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints };

package/dist/index.js

@@ -31,6 +31,7 @@ import { newWebhookSecret } from "./webhooks/standard-webhooks.js";
 import { subscription } from "./webhooks/subscription.js";
 import { storageCleanupSchedule } from "./files/cleanup-schedule.js";
 import { localFileStore, localFiles } from "./files/local-files.js";
+import { pluginOptions, pluginsFor, pluginsVariable } from "./plugins/plugin-settings.js";
 import { runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
 import { createAdmin } from "./create-admin.js";
 import { configExports } from "./resource-source.js";
@@ -51,4 +52,4 @@ import { createFileCleanup } from "./files/file-cleanup.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
 import { startJobs } from "./jobs/runtime.js";
 import { jobsDrainApp } from "./jobs/drain-route.js";
-export { FatalJobError, HttpProblem, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints };
+export { FatalJobError, HttpProblem, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, checkWebhooksSchema, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineJob, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, isJobDefinition, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, listOrganizations, listUsers, localFileStore, localFiles, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, migrationCommand, newWebhookSecret, normalizeRoles, notFound, parseColumns, parseRoles, pluginOptions, pluginsFor, pluginsVariable, processor, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, startJobs, storageCleanupSchedule, streamChatCompletion, subscription, unauthorized, verifySignature, verifyStandardWebhook, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints };

package/dist/meta.js

@@ -2,6 +2,7 @@ import { seesAssistant } from "./assistant/assistant-settings.js";
 import { sha256Hex, stableJson } from "./hash.js";
 import { requestAccess } from "./request-access.js";
 import { activeRole } from "./active-role.js";
+import { pluginsFor } from "./plugins/plugin-settings.js";
 import { seesRuntime } from "./runtime/runtime-settings.js";
 import { pruneView } from "./view-access.js";
 import { prunePage } from "@protobase/layout";
@@ -35,6 +36,7 @@ const createMeta = (deps) => {
 		const shown = (item) => item.kind === "link" || (item.kind === "resource" ? visible.some((access) => access.entry.name === item.resource) : pages.some((page) => page.name === item.page));
 		const bar = bottomBarFor(deps.bottomBars, activeRole(session));
 		const barItems = bar?.items.filter(shown) ?? [];
+		const plugins = pluginsFor(deps.plugins, session.user.roles);
 		const body = {
 			resources: visible.map((access) => access.readable),
 			views,
@@ -56,7 +58,8 @@ const createMeta = (deps) => {
 				items: barItems
 			} },
 			...deps.assistant && seesAssistant(session.user.roles) && { assistant: { url: deps.assistant } },
-			...deps.runtime && seesRuntime(session.user.roles) && { runtime: { url: deps.runtime } }
+			...deps.runtime && seesRuntime(session.user.roles) && { runtime: { url: deps.runtime } },
+			...plugins.length > 0 && { plugins }
 		};
 		return {
 			body,

package/dist/plugins/plugin-settings.d.ts

@@ -0,0 +1,27 @@
+import { JsonValue } from "@protobase/schema";
+//#region src/plugins/plugin-settings.d.ts
+/**
+ * A plugin the admin app loads at runtime: `url` names its plugin.json (`protobase build-plugin` writes it), on another
+ * origin or this one (`/plugins/...`). The plugin reads `settings` with `usePlugin()`. With `roles`, `/meta` names it
+ * only to callers holding one of them; without, to everyone.
+ */
+export type PluginOption = {
+  url: string;
+  settings?: Record<string, JsonValue>;
+  roles?: string[];
+};
+/** A plugin as `/meta` names it to a caller. */
+export type PluginRef = {
+  url: string;
+  settings?: Record<string, JsonValue>;
+};
+/** The platform's plugins, as plugin.json URLs separated by commas, loaded after the ones `options.plugins` lists. */
+export declare const pluginsVariable = "PROTOBASE_PLUGINS";
+/**
+ * The plugins the app loads: those `options.plugins` lists, then those `PROTOBASE_PLUGINS` adds, each URL once. `false`
+ * turns both off. A value that is no URL stops the server at startup.
+ */
+export declare const pluginOptions: (option: PluginOption[] | false | undefined, env: Record<string, string | undefined>) => PluginOption[];
+/** The plugins `/meta` names to a caller with `roles`: those for everyone, and those for one of their roles. */
+export declare const pluginsFor: (plugins: readonly PluginOption[], roles: readonly string[]) => PluginRef[];
+//#endregion

package/dist/plugins/plugin-settings.js

@@ -0,0 +1,31 @@
+//#region src/plugins/plugin-settings.ts
+/** The platform's plugins, as plugin.json URLs separated by commas, loaded after the ones `options.plugins` lists. */
+const pluginsVariable = "PROTOBASE_PLUGINS";
+const checkedPluginUrl = (url, source) => {
+	if (url.startsWith("/") && !url.startsWith("//")) return url;
+	if (!URL.canParse(url)) throw new Error(`${source} names "${url}", which is no URL; use https://... or a path such as /plugins/name/plugin.json`);
+	const { protocol } = new URL(url);
+	if (protocol !== "https:" && protocol !== "http:") throw new Error(`${source} names "${url}", which must start with https:// or http://, not ${protocol}//`);
+	return url;
+};
+/**
+* The plugins the app loads: those `options.plugins` lists, then those `PROTOBASE_PLUGINS` adds, each URL once. `false`
+* turns both off. A value that is no URL stops the server at startup.
+*/
+const pluginOptions = (option, env) => {
+	if (option === false) return [];
+	const given = (option ?? []).map((plugin) => ({
+		...plugin,
+		url: checkedPluginUrl(plugin.url.trim(), "options.plugins")
+	}));
+	const listed = (env["PROTOBASE_PLUGINS"] ?? "").split(",").map((url) => url.trim()).filter((url) => url !== "").map((url) => ({ url: checkedPluginUrl(url, pluginsVariable) }));
+	const all = [...given, ...listed];
+	return all.filter((plugin, index) => all.findIndex((other) => other.url === plugin.url) === index);
+};
+/** The plugins `/meta` names to a caller with `roles`: those for everyone, and those for one of their roles. */
+const pluginsFor = (plugins, roles) => plugins.filter((plugin) => !plugin.roles || plugin.roles.some((role) => roles.includes(role))).map(({ url, settings }) => ({
+	url,
+	...settings && { settings }
+}));
+//#endregion
+export { pluginOptions, pluginsFor, pluginsVariable };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.11.0",
+  "version": "0.11.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.11.0",
-    "@protobase/query": "0.11.0",
-    "@protobase/schema": "0.11.0",
+    "@protobase/layout": "0.11.1",
+    "@protobase/query": "0.11.1",
+    "@protobase/schema": "0.11.1",
     "@scalar/hono-api-reference": "^0.12.10",
     "@simplewebauthn/server": "^13.3.1",
     "better-auth": "^1.7.7",