@protobase/server 0.8.2 → 0.9.0

package/dist/batch/run-batch.js

@@ -2,7 +2,7 @@ import { HttpProblem, badRequest, notFound } from "../problem.js";
 import { problemOf } from "../error-handler.js";
 import { requestAccess } from "../request-access.js";
 import { writeTransaction } from "../transactions.js";
-import { actorSettings } from "../changes/actor.js";
+import { actorSettings, wakeDispatch } from "../changes/actor.js";
 import { keyOf } from "../write-shared.js";
 import { writeIn } from "../write-pipeline.js";
 import { resolveData, resolveKey } from "./refs.js";
@@ -38,7 +38,7 @@ const runBatch = async (deps, session, operations) => {
 		accesses.set(entry.name, access);
 		return access;
 	};
-	return writeTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+	const written = await writeTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
 		const created = /* @__PURE__ */ new Map();
 		const results = [];
 		for (const [index, operation] of operations.entries()) try {
@@ -101,6 +101,8 @@ const runBatch = async (deps, session, operations) => {
 		}
 		return results;
 	}, actorSettings(deps, session));
+	wakeDispatch(deps);
+	return written;
 };
 //#endregion
 export { runBatch };

package/dist/changes/actor.js

@@ -1,3 +1,5 @@
+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. */
 const actorSettings = (deps, session) => {
@@ -8,5 +10,9 @@ const actorSettings = (deps, session) => {
 	};
 	return { [deps.actorSetting]: JSON.stringify(actor) };
 };
+/** After a write committed: has this process's dispatcher deliver its events now, rather than at its next poll. */
+const wakeDispatch = (deps) => {
+	if (deps.actorSetting) runningJobs()?.wake(dispatchJobName);
+};
 //#endregion
-export { actorSettings };
+export { actorSettings, wakeDispatch };

package/dist/changes/capture-schema.js

@@ -1,5 +1,5 @@
-import { changesSchema } from "./events-options.js";
 import { quoteIdent, tableSql } from "./capture-sql.js";
+import { changesSchema } from "./events-options.js";
 import { capturePlan, planSql, uncaptured } from "./capture-plan.js";
 import { sql } from "kysely";
 //#region src/changes/capture-schema.ts

package/dist/changes/capture-sql.js

@@ -1,3 +1,4 @@
+import { jobsSchema } from "../jobs/schema.js";
 //#region src/changes/capture-sql.ts
 const quoteIdent = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
 const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
@@ -31,10 +32,16 @@ const outboxSql = (schema) => `create table if not exists ${quoteIdent(schema)}.
   "dispatch_after" timestamptz not null default now(),
   "created_at" timestamptz not null default now()
 )`;
+/** 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
-* `off`, and an update that changed none of those columns.
+* `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.
 */
 const captureBody = (schema) => `
 declare
@@ -71,6 +78,10 @@ begin
     changed,
     nullif(current_setting('${schema}.actor', true), '')::jsonb
   );
+  if current_setting('${schema}.dispatch', true) is distinct from 'queued' then
+    perform ${jobsSchema}.enqueue('${dispatchJobName}', null, null, null, '${dispatchGroup}');
+    perform set_config('${schema}.dispatch', 'queued', true);
+  end if;
   return null;
 end
 `;
@@ -105,4 +116,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, dropTriggerSql, outboxSql, quoteIdent, resourceTriggers, tableSql };
+export { captureBody, captureFunctionSql, createTriggerSql, dispatchGroup, dispatchJobName, dropTriggerSql, 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;
+  /** When the writing transaction started, ISO 8601. */
+  at: string;
 };
 /**
  * One record's changes in one transaction, as one: its columns at the start (`before`, none when it was inserted) and
@@ -28,6 +30,8 @@ export type CoalescedChange = {
   actor: EventActor | null;
   /** The id of its last outbox row. */
   sequence: string;
+  /** When its last change's transaction started. */
+  at: string;
 };
 /**
  * The outbox rows of one or more transactions, in id order, as one change per (transaction, record). An insert then a

package/dist/changes/coalesce.js

@@ -17,7 +17,8 @@ const merged = ({ first, last, actor, listed }) => {
 		transaction: first.transaction,
 		resource: first.resource,
 		actor,
-		sequence: last.id
+		sequence: last.id,
+		at: last.at
 	};
 	const before = first.op === "INSERT" ? null : first.old;
 	const after = last.op === "DELETE" ? null : last.new;

package/dist/changes/outbox.d.ts

@@ -0,0 +1,14 @@
+import { Row } from "../types.js";
+import { CapturedRow } from "./coalesce.js";
+import { ResourceModel } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/changes/outbox.d.ts
+/**
+ * A captured row's columns from the JSON text the database stores: the columns of 64-bit integer and decimal fields as
+ * their exact digits, other numbers as numbers. Needs a runtime that passes JSON.parse revivers the source text
+ * (Node 21 and later, Bun).
+ */
+export declare const parseColumns: (text: string | null, model?: ResourceModel) => Row | null;
+/** The oldest `limit` rows of the outbox that committed, in id order. */
+export declare const readOutbox: (db: Db, schema: string, models: readonly ResourceModel[], limit: number) => Promise<CapturedRow[]>;
+//#endregion

package/dist/changes/outbox.js

@@ -0,0 +1,51 @@
+import { quoteIdent } from "./capture-sql.js";
+import { sql } from "kysely";
+//#region src/changes/outbox.ts
+var ExactNumber = class {
+	source;
+	constructor(source) {
+		this.source = source;
+	}
+};
+const exact = (_key, value, context) => typeof value === "number" && context?.source !== void 0 ? new ExactNumber(context.source) : value;
+const plain = (value) => {
+	if (value instanceof ExactNumber) return Number(value.source);
+	if (Array.isArray(value)) return value.map(plain);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, plain(item)]));
+	return value;
+};
+const textTypes = /* @__PURE__ */ new Set(["bigint", "decimal"]);
+/**
+* A captured row's columns from the JSON text the database stores: the columns of 64-bit integer and decimal fields as
+* their exact digits, other numbers as numbers. Needs a runtime that passes JSON.parse revivers the source text
+* (Node 21 and later, Bun).
+*/
+const parseColumns = (text, model) => {
+	if (text === null) return null;
+	const parsed = JSON.parse(text, exact);
+	const types = new Map(Object.values(model?.fields ?? {}).map((field) => [field.column, field.type]));
+	return Object.fromEntries(Object.entries(parsed).map(([column, value]) => [column, value instanceof ExactNumber && textTypes.has(types.get(column) ?? "") ? value.source : plain(value)]));
+};
+/** The oldest `limit` rows of the outbox that committed, in id order. */
+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
+    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);
+		return {
+			...row,
+			old: parseColumns(row.old, model),
+			new: parseColumns(row.new, model),
+			actor: row.actor === null ? null : JSON.parse(row.actor)
+		};
+	});
+};
+/** Removes dispatched rows from the outbox. */
+const deleteOutbox = async (db, schema, ids) => {
+	if (ids.length === 0) return;
+	await sql`delete from ${sql.raw(`${quoteIdent(schema)}."outbox"`)} where "id" = any(${ids}::bigint[])`.execute(db);
+};
+//#endregion
+export { deleteOutbox, parseColumns, readOutbox };

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

@@ -19,6 +19,8 @@ export type ResourceChange = {
   transaction: string;
   /** Grows with every change of a record, so receivers can drop stale events. */
   sequence: string;
+  /** When the change's transaction started, ISO 8601. */
+  at: string;
 };
 /** A captured row by field name, fields without a captured column left out. */
 export declare const recordOf: (model: ResourceModel, columns: Row) => Row;

package/dist/changes/resource-change.js

@@ -36,7 +36,8 @@ const resourceChange = (model, change) => {
 		source: change.actor ? "api" : "database",
 		...tenant != null && { tenant },
 		transaction: change.transaction,
-		sequence: change.sequence
+		sequence: change.sequence,
+		at: change.at
 	};
 };
 //#endregion

package/dist/create-admin.d.ts

@@ -1,12 +1,13 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
 import { EventsOptions } from "./changes/events-options.js";
+import { JobDefinition } from "./jobs/job-types.js";
+import { Admin, Authenticator, PageSource, ViewSource } from "./types.js";
+import { WebhooksOptions } from "./webhooks/table/options.js";
+import { SubscriptionDefinition } from "./webhooks/subscription.js";
 import { FilesOptions } from "./files/options.js";
-import { AdminEnv, Authenticator, PageSource, ViewSource } from "./types.js";
 import { ResourceSource } from "./resource-source.js";
 import { FunctionSource } from "./functions/define-function.js";
 import { AdminOptions } from "./admin-options.js";
-import { JobDefinition } from "./jobs/job-types.js";
-import { Hono } from "hono";
 import { UserMenuSource } from "@protobase/schema";
 import { Db } from "@protobase/query";
 //#region src/create-admin.d.ts
@@ -27,10 +28,14 @@ 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, admins get the failed jobs page (`failedJobs`). */
+  /** The app's jobs (see `defineJob`): with any, or a resource with events, admins get the failed jobs page (`failedJobs`). */
   jobs?: JobDefinition[];
+  /** Where the resources' events are delivered (`subscription(...)` exports of the config module). */
+  subscriptions?: SubscriptionDefinition[];
+  /** Webhook subscriptions made in the admin app, from `extends: [webhooks()]` (see `WebhooksOptions`). */
+  webhooks?: WebhooksOptions;
   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, db, authenticate, auth, functions, files: filesOptions, events, jobs, options }: CreateAdminInput) => Hono<AdminEnv, import("hono/types").BlankSchema, "/">;
+export declare const createAdmin: ({ resources: appResources, views: appViews, pages, userMenu, db, authenticate, auth, functions, files: filesOptions, events, jobs, subscriptions, webhooks: webhooksOptions, options }: CreateAdminInput) => Admin;
 //#endregion

package/dist/create-admin.js

@@ -7,12 +7,15 @@ 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 { callerRecords } from "./functions/records.js";
+import { toApiFunction } from "./functions/define-function.js";
+import { createWebhooks } from "./webhooks/webhooks.js";
+import { webhookTable } from "./webhooks/table/webhook-table.js";
+import { subscriptionWriteCheck } from "./webhooks/table/validate-hook.js";
 import { checkShell } from "./check-shell.js";
 import { checkViews } from "./check-views.js";
 import { createFilesRuntime } from "./files/runtime.js";
 import { fileRoutes } from "./files/routes.js";
-import { toApiFunction } from "./functions/define-function.js";
-import { callerRecords } from "./functions/records.js";
 import { functionRoutes } from "./functions/routes.js";
 import { runtimeUrl } from "./runtime/runtime-settings.js";
 import { createMeta } from "./meta.js";
@@ -28,10 +31,11 @@ import { Hono } from "hono";
 import { checkPages } from "@protobase/layout";
 //#region src/create-admin.ts
 /** 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, db, authenticate, auth, functions = {}, files: filesOptions, events, jobs = [], options = {} }) => {
+const createAdmin = ({ resources: appResources, views: appViews = [], pages = [], userMenu, db, authenticate, auth, functions = {}, files: filesOptions, events, jobs = [], subscriptions = [], webhooks: webhooksOptions, options = {} }) => {
 	const basePath = options.basePath ?? "/api/v1";
-	const resources = jobs.length > 0 ? [...appResources, failedJobs] : appResources;
-	const views = jobs.length > 0 ? [...appViews, failedJobsView] : appViews;
+	const withJobs = jobs.length > 0 || appResources.some((resource) => resource.toModel().events);
+	const resources = withJobs ? [...appResources, failedJobs] : appResources;
+	const views = withJobs ? [...appViews, failedJobsView] : appViews;
 	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());
@@ -52,6 +56,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		models: registry.entries.map((entry) => entry.model),
 		systemPath
 	});
+	const table = webhooksOptions && webhookTable(webhooksOptions, auth);
 	const deps = {
 		db,
 		registry,
@@ -62,7 +67,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		systemPath,
 		statementTimeoutMs: options.statementTimeoutMs ?? 15e3,
 		guard: createScanGuard(db, options.scanGuard),
-		hooks: options.writeHooks ?? [],
+		hooks: [...options.writeHooks ?? [], ...table ? [subscriptionWriteCheck(registry.entries.map((entry) => entry.model), table.checkUrl)] : []],
 		audit: options.audit ?? consoleAuditQueue(),
 		accessOptions: {
 			...options.roles && { roles: options.roles },
@@ -136,7 +141,15 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 	app.route("/", fileRoutes(deps, authenticate));
 	app.route(basePath, api);
 	app.route(deps.systemPath || "/", system);
-	return app;
+	const webhooks = createWebhooks({
+		deps,
+		subscriptions,
+		functions: apiFunctions,
+		schema: changesSchema(events),
+		log: (line) => console.log(line),
+		...table && { table }
+	});
+	return Object.assign(app, { jobs: webhooks.jobs });
 };
 //#endregion
 export { createAdmin };

package/dist/index.d.ts

@@ -7,9 +7,13 @@ import { OrganizationsOptions } from "./better-auth/organizations/options.js";
 import { PlatformSignIn, readPlatformSignIn } from "./better-auth/platform-sign-in.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, createAuth, normalizeRoles } from "./better-auth/create-auth.js";
 import { EventsOptions } from "./changes/events-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";
+import { WebhooksOptions } from "./webhooks/table/options.js";
+import { EventData, RunContext, SubscriptionDefinition, SubscriptionEvent, SubscriptionOptions, subscription } from "./webhooks/subscription.js";
 import { FileProvider, FileStore, StoredObject } from "./files/store.js";
 import { FilesOptions } from "./files/options.js";
-import { Admin, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, SessionOrganization, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
 import { CleanupEntry, CleanupSchedule, ScheduledDelete, storageCleanupSchedule } from "./files/cleanup-schedule.js";
 import { CleanupReport } from "./files/cleanup-runner.js";
 import { ResourceSource, configExports } from "./resource-source.js";
@@ -24,8 +28,6 @@ import { AssistantTool, ToolContext, defineTool } from "./assistant/tools.js";
 import { AssistantOptions, AssistantSettings, assistantRoles, assistantSettings, assistantVariables, seesAssistant } from "./assistant/assistant-settings.js";
 import { RuntimeOptions, runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
 import { AdminOptions } from "./admin-options.js";
-import { StandardSchema, readJson } from "./functions/read-json.js";
-import { EnqueueOptions, JobContext, JobDefinition, JobOptions } from "./jobs/job-types.js";
 import { CreateAdminInput, createAdmin } from "./create-admin.js";
 import { ProjectConfig, defineConfig, mergeConfig } from "./project-config.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
@@ -40,6 +42,10 @@ import { changesMigration, checkChanges, migrationCommand } from "./changes/capt
 import { CapturedRow, CoalescedChange, coalesce } from "./changes/coalesce.js";
 import { ResourceChange, recordOf, resourceChange } from "./changes/resource-change.js";
 import { eventMatcher } from "./changes/match-events.js";
+import { parseColumns, readOutbox } from "./changes/outbox.js";
+import { newWebhookSecret } from "./webhooks/standard-webhooks.js";
+import { webhooks } from "./webhooks/table/plugin.js";
+import { checkWebhooksSchema, webhooksMigration } from "./webhooks/table/schema.js";
 import { MemberInput, NewOrganization, addAppRoleToOwners, addMember, createOrganization, listOrganizations, removeMember, setMemberRoles } from "./better-auth/organizations/host.js";
 import { AssistantBackend, assistantProtocolRoutes } from "./assistant/protocol-routes.js";
 import { fileConversationStore } from "./assistant/file-conversation-store.js";
@@ -60,4 +66,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 CreateAdminInput, type CreateAuthOptions, type DrainResult, type EnqueueOptions, 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 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 TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WidgetOptions, type WriteEvent, type WriteOperation, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, checkJobsSchema, 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, normalizeRoles, notFound, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, startJobs, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, 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 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, webhooks, webhooksMigration, widget, withCacheBreakpoints };

package/dist/index.js

@@ -9,6 +9,7 @@ import { readOnlyQueryTool, readWriteQueryTool } from "./assistant/query-tools.j
 import { requestApproval } from "./assistant/approval.js";
 import { withCacheBreakpoints } from "./assistant/cache-breakpoints.js";
 import { ModelError, streamChatCompletion } from "./assistant/chat-completions.js";
+import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
 import { runTurn } from "./assistant/turn.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { readOperatorSettings } from "./better-auth/operator-provider.js";
@@ -18,23 +19,28 @@ 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 { 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";
+import { subscription } from "./webhooks/subscription.js";
 import { storageCleanupSchedule } from "./files/cleanup-schedule.js";
 import { localFileStore, localFiles } from "./files/local-files.js";
-import { defineFunction } from "./functions/define-function.js";
 import { runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
-import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
 import { createAdmin } from "./create-admin.js";
 import { configExports } from "./resource-source.js";
-import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js";
 import { defineConfig, mergeConfig } from "./project-config.js";
 import { jwtAuthenticator } from "./auth/jwt.js";
 import { betterAuthAuthenticator } from "./better-auth/authenticator.js";
 import { issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
 import { authSchemaMigration, checkAuthSchema } from "./better-auth/auth-schema.js";
 import { changesMigration, checkChanges, migrationCommand } from "./changes/capture-schema.js";
-import { coalesce } from "./changes/coalesce.js";
-import { recordOf, resourceChange } from "./changes/resource-change.js";
-import { eventMatcher } from "./changes/match-events.js";
+import { webhooks } from "./webhooks/table/plugin.js";
+import { checkWebhooksSchema, webhooksMigration } from "./webhooks/table/schema.js";
 import { maxWidgetPropsBytes, widget } from "./assistant/widget.js";
 import { functionApp } from "./functions/function-app.js";
 import { readJson } from "./functions/read-json.js";
@@ -42,7 +48,6 @@ import { verifySignature, verifyStandardWebhook } from "./functions/verify-signa
 import { requireEnv } from "./functions/require-env.js";
 import { createFileCleanup } from "./files/file-cleanup.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.js";
-import { FatalJobError } from "./jobs/run-job.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, 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, normalizeRoles, notFound, parseRoles, processor, readJson, readOnlyQueryTool, readOperatorSettings, readPlatformSignIn, readWriteQueryTool, recordOf, removeMember, requestApproval, requireEnv, resourceChange, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, startJobs, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, 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, 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, webhooks, webhooksMigration, widget, withCacheBreakpoints };

package/dist/jobs/current.d.ts

@@ -4,5 +4,7 @@ import { Db } from "@protobase/query";
 /** What `defineJob(...).enqueue` reaches: the jobs runtime this process started. */
 export type JobsEnqueuer = {
   enqueue(definition: JobDefinition, db: Db, payload: unknown, options?: EnqueueOptions): Promise<string>;
+  /** Has this process's worker of the job look for due jobs now rather than at its next poll; nothing without one. */
+  wake(name: string): void;
 };
 //#endregion

package/dist/jobs/current.js

@@ -7,6 +7,8 @@ const currentJobs = () => {
 	if (!runtime) throw new Error("Jobs are not running in this process: start them with startJobs(), as protobase dev, serve and worker do");
 	return runtime;
 };
+/** The running jobs runtime, if this process started one. */
+const runningJobs = () => holder[key];
 const setCurrentJobs = (runtime) => {
 	if (holder[key]) throw new Error("Jobs are already running in this process; stop them before starting them again");
 	holder[key] = runtime;
@@ -15,4 +17,4 @@ const clearCurrentJobs = (runtime) => {
 	if (holder[key] === runtime) delete holder[key];
 };
 //#endregion
-export { clearCurrentJobs, currentJobs, setCurrentJobs };
+export { clearCurrentJobs, currentJobs, runningJobs, setCurrentJobs };

package/dist/jobs/runtime.js

@@ -1,5 +1,5 @@
-import { jobsSchema } from "./schema.js";
 import { clearCurrentJobs, setCurrentJobs } from "./current.js";
+import { jobsSchema } from "./schema.js";
 import "./schedule.js";
 import { runJob, validatePayload } from "./run-job.js";
 import { jobsDatabase } from "./database.js";
@@ -98,10 +98,7 @@ const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSecon
 		};
 		const id = options.key === void 0 ? await boss.send(name, data, send) : await keyed(options.key);
 		if (!id) throw new Error(`Job "${name}" was not enqueued`);
-		if (!target.isTransaction) {
-			const worker = workers.get(name);
-			if (worker) boss.notifyWorker(worker.id);
-		}
+		if (!target.isTransaction) wake(name);
 		return id;
 	};
 	const nextDue = async () => (await sql`select ${sql.id(jobsSchema, "next_due")}() as due`.execute(db)).rows[0].due;
@@ -129,9 +126,14 @@ const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSecon
 			await new Promise((resolve) => setTimeout(resolve, 100));
 		}
 	};
+	const wake = (name) => {
+		const worker = workers.get(name);
+		if (worker) boss.notifyWorker(worker.id);
+	};
 	const runtime = {
 		works: work,
 		enqueue,
+		wake,
 		update,
 		drain,
 		nextDue,

package/dist/project-config.d.ts

@@ -1,7 +1,8 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
 import { EventsOptions } from "./changes/events-options.js";
-import { FilesOptions } from "./files/options.js";
 import { Authenticator } from "./types.js";
+import { WebhooksOptions } from "./webhooks/table/options.js";
+import { FilesOptions } from "./files/options.js";
 import { FunctionSource } from "./functions/define-function.js";
 import { AdminOptions } from "./admin-options.js";
 import { Db } from "@protobase/query";
@@ -24,6 +25,8 @@ export type ProjectConfig = {
   files?: FilesOptions;
   /** Where the changes that resources' events are raised from are captured (see `EventsOptions`). */
   events?: EventsOptions;
+  /** 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. */
   jobs?: Record<string, unknown>;
   options?: AdminOptions;

package/dist/project-config.js

@@ -1,4 +1,5 @@
 import { jobDefinitions } from "./jobs/define-job.js";
+import { isSubscription } from "./webhooks/subscription.js";
 import { isPageDefinition } from "@protobase/layout";
 //#region src/project-config.ts
 /** Typed identity, for `export default defineConfig({ extends: [...], config, auth, ... })` in `protobase.config.ts`. */
@@ -41,6 +42,11 @@ const mergedModule = (named) => {
 		value,
 		label
 	})));
+	checkUnique("The subscription", exports.filter(({ value }) => isSubscription(value)).map(({ value, label }) => ({
+		name: value.name,
+		value,
+		label
+	})));
 	const menus = values.filter(({ value }) => typeof value?.toUserMenuModel === "function");
 	if (new Set(menus.map(({ value }) => value)).size > 1) throw new Error(`Only one config may export a user menu; ${menus.map(({ label }) => label).join(" and ")} each do`);
 	const module = {};
@@ -133,11 +139,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 } = lastSet(named.map(({ config }) => ({
+	const { db, authenticate, auth, events, webhooks } = lastSet(named.map(({ config }) => ({
 		db: config.db,
 		authenticate: config.authenticate,
 		auth: config.auth,
-		events: config.events
+		events: config.events,
+		webhooks: config.webhooks
 	})));
 	const module = mergedModule(named);
 	const functions = mergedFunctions(named);
@@ -154,6 +161,7 @@ const mergeConfig = (...configs) => {
 		...functions && { functions },
 		...files && { files },
 		...events && { events },
+		...webhooks && { webhooks },
 		...jobs && { jobs },
 		...options && { options }
 	};

package/dist/resource-source.d.ts

@@ -1,5 +1,7 @@
+import { SubscriptionDefinition } from "./webhooks/subscription.js";
+import "./index.js";
 import { PageDefinition } from "@protobase/layout";
-import { AccessSource, FileProcessor, UserMenuSource, ViewModel } from "@protobase/schema";
+import { AccessSource, EventMatch, FileProcessor, UserMenuSource, ViewModel } from "@protobase/schema";
 import { z } from "zod";
 //#region src/resource-source.d.ts
 type FieldSource = {
@@ -22,10 +24,12 @@ export type ResourceSource = AccessSource & {
     message: string;
   }> | undefined)[];
   recordSchema(): z.ZodType;
+  /** The code predicates of its events, by event name. */
+  eventMatches?(): Record<string, EventMatch<any>>;
 };
 /**
- * Splits a config module (`import * as config from './config'`) into its resources, views, pages and, when it exports
- * one `userMenu(...)`, the user menu.
+ * Splits a config module (`import * as config from './config'`) into its resources, views, pages, subscriptions and,
+ * when it exports one `userMenu(...)`, the user menu.
  */
 export declare const configExports: (module: Record<string, unknown>) => {
   userMenu?: UserMenuSource | undefined;
@@ -34,5 +38,6 @@ export declare const configExports: (module: Record<string, unknown>) => {
     toModel(): ViewModel;
   }>;
   pages: PageDefinition[];
+  subscriptions: SubscriptionDefinition[];
 };
 //#endregion

package/dist/resource-source.js

@@ -1,13 +1,15 @@
+import { isSubscription } from "./webhooks/subscription.js";
 import { isPageDefinition } from "@protobase/layout";
 //#region src/resource-source.ts
 /**
-* Splits a config module (`import * as config from './config'`) into its resources, views, pages and, when it exports
-* one `userMenu(...)`, the user menu.
+* Splits a config module (`import * as config from './config'`) into its resources, views, pages, subscriptions and,
+* when it exports one `userMenu(...)`, the user menu.
 */
 const configExports = (module) => {
 	const values = Object.values(module);
 	const pages = values.filter(isPageDefinition);
-	const others = values.filter((value) => !isPageDefinition(value));
+	const subscriptions = [...new Set(values.filter(isSubscription))];
+	const others = values.filter((value) => !isPageDefinition(value) && !isSubscription(value));
 	const buildable = others.filter((value) => typeof value?.toModel === "function");
 	const menus = others.filter((value) => typeof value?.toUserMenuModel === "function");
 	if (menus.length > 1) throw new Error(`The config module exports ${menus.length} user menus; export one userMenu(...)`);
@@ -15,6 +17,7 @@ const configExports = (module) => {
 		resources: buildable.filter((value) => typeof value.recordSchema === "function"),
 		views: buildable.filter((value) => typeof value.recordSchema !== "function"),
 		pages,
+		subscriptions,
 		...menus[0] && { userMenu: menus[0] }
 	};
 };

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { JobDefinition } from "./jobs/job-types.js";
 import { Hono } from "hono";
 import { PageModel } from "@protobase/layout";
 import { ResourceModel, ViewModel } from "@protobase/schema";
@@ -88,5 +89,8 @@ export type ViewSource = {
 export type PageSource = {
   toModel(): PageModel;
 };
-export type Admin = Hono<AdminEnv>;
+/** The admin API, and the jobs it needs a worker to run: the delivery of resource events. */
+export type Admin = Hono<AdminEnv> & {
+  jobs: JobDefinition[];
+};
 //#endregion