@protobase/server 0.8.1 → 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,11 +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 { Hono } from "hono";
 import { UserMenuSource } from "@protobase/schema";
 import { Db } from "@protobase/query";
 //#region src/create-admin.d.ts
@@ -26,8 +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, 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, views, pages, userMenu, db, authenticate, auth, functions, files: filesOptions, events, 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";
@@ -23,12 +26,16 @@ import { docsRoutes } from "./routes/docs.js";
 import { metaRoutes } from "./routes/meta.js";
 import { recordRoutes } from "./routes/record.js";
 import { createScanGuard } from "./scan-guard.js";
+import { failedJobs, failedJobsView } from "./jobs/failed-jobs.js";
 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, views = [], pages = [], userMenu, db, authenticate, auth, functions = {}, files: filesOptions, events, 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 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());
@@ -49,6 +56,7 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		models: registry.entries.map((entry) => entry.model),
 		systemPath
 	});
+	const table = webhooksOptions && webhookTable(webhooksOptions, auth);
 	const deps = {
 		db,
 		registry,
@@ -59,7 +67,7 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		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 },
@@ -133,7 +141,15 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 	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/functions/require-env.d.ts

@@ -3,5 +3,5 @@
  * An environment variable the function cannot work without, such as an API key: `protobase dev` reads it from `.env`,
  * `protobase serve` from its environment. A missing one is an error, so the call is a 500 the app reports.
  */
-export declare const requireEnv: (name: string) => any;
+export declare const requireEnv: (name: string) => string;
 //#endregion

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";
@@ -38,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";
@@ -47,11 +55,15 @@ import { WidgetOptions, maxWidgetPropsBytes, widget } from "./assistant/widget.j
 import { QueryOptions, QueryResult, runReadOnlyQuery, runReadWriteQuery } from "./assistant/run-query.js";
 import { readOnlyQueryTool, readWriteQueryTool } from "./assistant/query-tools.js";
 import { FunctionEnv, PublicFunctionEnv, functionApp } from "./functions/function-app.js";
-import { StandardSchema, readJson } from "./functions/read-json.js";
 import { SignatureOptions, StandardWebhookOptions, verifySignature, verifyStandardWebhook } from "./functions/verify-signature.js";
 import { requireEnv } from "./functions/require-env.js";
 import { LocalFilesOptions, localFileStore, localFiles } from "./files/local-files.js";
 import { FileCleanupInput, createFileCleanup } from "./files/file-cleanup.js";
 import { FileObject } from "./files/present.js";
 import { aspectRatio, fileSize, fileType, imageSize, processor } from "./files/processors.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 EventsOptions, 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 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 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, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, issueToken, 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, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, widget, withCacheBreakpoints };
+import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js";
+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 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,9 +19,17 @@ 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 { createAdmin } from "./create-admin.js";
 import { configExports } from "./resource-source.js";
@@ -30,9 +39,8 @@ 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";
@@ -40,4 +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";
-export { HttpProblem, ModelError, addAppRoleToOwners, addMember, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, badRequest, betterAuthAuthenticator, changesMigration, checkAuthSchema, checkChanges, coalesce, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createFileCleanup, createOrganization, createUser, defaultSignInPolicy, defineConfig, defineFunction, defineTool, deleteUser, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, functionApp, hasUsers, imageSize, issueToken, 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, storageCleanupSchedule, streamChatCompletion, unauthorized, verifySignature, verifyStandardWebhook, widget, withCacheBreakpoints };
+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, webhooks, webhooksMigration, widget, withCacheBreakpoints };

package/dist/jobs/current.d.ts

@@ -0,0 +1,10 @@
+import { EnqueueOptions, JobDefinition } from "./job-types.js";
+import { Db } from "@protobase/query";
+//#region src/jobs/current.d.ts
+/** 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

@@ -0,0 +1,20 @@
+//#region src/jobs/current.ts
+const key = Symbol.for("protobase.jobs");
+const holder = globalThis;
+/** The running jobs runtime; enqueueing needs one, started by `protobase dev`, `serve` and `worker`, or by `startJobs`. */
+const currentJobs = () => {
+	const runtime = holder[key];
+	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;
+};
+const clearCurrentJobs = (runtime) => {
+	if (holder[key] === runtime) delete holder[key];
+};
+//#endregion
+export { clearCurrentJobs, currentJobs, runningJobs, setCurrentJobs };

package/dist/jobs/database.js

@@ -0,0 +1,36 @@
+import { CompiledQuery } from "kysely";
+//#region src/jobs/database.ts
+const block = /^\s*BEGIN;\s*(SET LOCAL lock_timeout = \d+);\s*(SET LOCAL idle_in_transaction_session_timeout = \d+);\s*(SELECT pg_advisory_xact_lock\([^;]*\);\s*)?([\s\S]+?);\s*COMMIT;\s*$/;
+/**
+* The statements of one of pg-boss's transaction texts, in order, or `undefined` for any other text. A text that
+* starts a transaction and is not in that shape is an error, so a pg-boss upgrade that changes it fails loudly.
+*/
+const transactionStatements = (text) => {
+	if (!/^\s*BEGIN;/.test(text)) return void 0;
+	const match = block.exec(text);
+	if (!match) throw new Error(`Unexpected pg-boss transaction:\n${text}`);
+	const [, lockTimeout, idleTimeout, lock, statement] = match;
+	return [
+		lockTimeout,
+		idleTimeout,
+		...lock ? [lock.trim().replace(/;$/, "")] : [],
+		statement
+	];
+};
+/**
+* pg-boss's database over the app's own Kysely pool or transaction: one connection pool for the app and its jobs, the
+* same driver on Node, Bun and PGlite. Every statement runs on its own, or inside one transaction for pg-boss's
+* transaction texts, which works through a pooler in transaction mode: pg-boss takes only transaction-scoped locks.
+*/
+const jobsDatabase = (db) => ({ executeSql: async (text, values) => {
+	if (values && values.length > 0) return { rows: [...(await db.executeQuery(CompiledQuery.raw(text, values))).rows] };
+	const statements = transactionStatements(text);
+	if (!statements) return { rows: [...(await db.executeQuery(CompiledQuery.raw(text))).rows] };
+	return db.transaction().execute(async (trx) => {
+		let rows = [];
+		for (const statement of statements) rows = [...(await trx.executeQuery(CompiledQuery.raw(statement))).rows];
+		return { rows };
+	});
+} });
+//#endregion
+export { jobsDatabase, transactionStatements };

package/dist/jobs/define-job.d.ts

@@ -0,0 +1,8 @@
+import { JobDefinition, JobOptions } from "./job-types.js";
+//#region src/jobs/define-job.d.ts
+/** A job the app's workers run: export it from the module that `protobase.config.ts` passes as `jobs`. */
+export declare const defineJob: <Payload = undefined>(options: JobOptions<Payload>) => JobDefinition<Payload>;
+export declare const isJobDefinition: (value: unknown) => value is JobDefinition;
+/** The job definitions among a module's exports, such as `import * as jobs from './config/jobs'`, each name once. */
+export declare const jobDefinitions: (module: Record<string, unknown>) => JobDefinition[];
+//#endregion

package/dist/jobs/define-job.js

@@ -0,0 +1,38 @@
+import { currentJobs } from "./current.js";
+import { nextRun } from "./schedule.js";
+//#region src/jobs/define-job.ts
+const namePattern = /^[\w.\-/]+$/;
+const checkSchedule = (name, schedule, timezone) => {
+	try {
+		nextRun(schedule, timezone, /* @__PURE__ */ new Date());
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+		throw new Error(`Job "${name}" has the schedule "${schedule}" in ${timezone}, which is not a cron schedule there: ${error.message}`, { cause: error });
+	}
+};
+/** A job the app's workers run: export it from the module that `protobase.config.ts` passes as `jobs`. */
+const defineJob = (options) => {
+	if (!namePattern.test(options.name)) throw new Error(`Job name "${options.name}" may only hold letters, digits, "_", "-", "." and "/"`);
+	if (options.schedule !== void 0) checkSchedule(options.name, options.schedule, options.timezone ?? "UTC");
+	const definition = {
+		kind: "job",
+		name: options.name,
+		options,
+		enqueue: async (db, payload, enqueueOptions) => currentJobs().enqueue(definition, db, payload, enqueueOptions)
+	};
+	return definition;
+};
+const isJobDefinition = (value) => typeof value === "object" && value !== null && value.kind === "job" && typeof value.enqueue === "function";
+/** The job definitions among a module's exports, such as `import * as jobs from './config/jobs'`, each name once. */
+const jobDefinitions = (module) => {
+	const byName = /* @__PURE__ */ new Map();
+	for (const value of Object.values(module)) {
+		if (!isJobDefinition(value)) continue;
+		const known = byName.get(value.name);
+		if (known && known !== value) throw new Error(`Two jobs are named "${value.name}"; rename one of them`);
+		byName.set(value.name, value);
+	}
+	return [...byName.values()];
+};
+//#endregion
+export { defineJob, isJobDefinition, jobDefinitions };

package/dist/jobs/drain-route.d.ts

@@ -0,0 +1,21 @@
+import { JobsRuntime } from "./runtime.js";
+//#region src/jobs/drain-route.d.ts
+/**
+ * `POST /api/jobs/drain?seconds=25`: runs the app's due jobs until none is left or `seconds` have passed, and answers
+ * `{ drained, remaining, nextDue }`. For the operator of a host that lets the app sleep and wakes it for its jobs: it
+ * takes the operator's `token` as a bearer token, never a user's.
+ */
+export declare const jobsDrainApp: ({ runtime, token }: {
+  runtime: JobsRuntime;
+  token: string;
+}) => import("hono/hono-base").HonoBase<import("hono/types").BlankEnv, {
+  "/api/jobs/drain": {
+    $post: {
+      input: {};
+      output: {};
+      outputFormat: string;
+      status: import("hono/utils/http-status").StatusCode;
+    };
+  };
+}, "/", "/api/jobs/drain">;
+//#endregion

package/dist/jobs/drain-route.js

@@ -0,0 +1,28 @@
+import { HttpProblem, badRequest, problemResponse, unauthorized } from "../problem.js";
+import { Hono } from "hono";
+import { createHash, timingSafeEqual } from "node:crypto";
+//#region src/jobs/drain-route.ts
+const drainPath = "/api/jobs/drain";
+const digest = (text) => createHash("sha256").update(text).digest();
+const sameToken = (given, token) => given !== void 0 && timingSafeEqual(digest(given), digest(token));
+const maxSeconds = 300;
+/**
+* `POST /api/jobs/drain?seconds=25`: runs the app's due jobs until none is left or `seconds` have passed, and answers
+* `{ drained, remaining, nextDue }`. For the operator of a host that lets the app sleep and wakes it for its jobs: it
+* takes the operator's `token` as a bearer token, never a user's.
+*/
+const jobsDrainApp = ({ runtime, token }) => new Hono().post(drainPath, async (c) => {
+	const problem = (error) => problemResponse(error, c.req.path);
+	if (!sameToken(c.req.header("authorization")?.replace(/^Bearer /, ""), token)) return problem(unauthorized("Send the operator token as a bearer token"));
+	const seconds = Number(c.req.query("seconds") ?? 25);
+	if (!Number.isFinite(seconds) || seconds <= 0 || seconds > maxSeconds) return problem(badRequest("invalid-seconds", `seconds must be more than 0 and at most ${maxSeconds}`));
+	if (!runtime.works) return problem(new HttpProblem(409, "jobs-elsewhere", "Conflict", "This process runs no jobs (PROTOBASE_JOBS=off); drain the one that does"));
+	const { drained, remaining, nextDue } = await runtime.drain(seconds);
+	return c.json({
+		drained,
+		remaining,
+		nextDue: nextDue?.toISOString() ?? null
+	});
+});
+//#endregion
+export { drainPath, jobsDrainApp };