@hot-updater/server 1.0.0-rc.1 → 1.0.0-rc.16

package/dist/assembly/assemblePlugins.cjs

@@ -0,0 +1,147 @@
+const require_resolveSchema = require("../database/resolveSchema.cjs");
+const require_database = require("../database/database.cjs");
+const require_reads = require("../core/reads.cjs");
+const require_schema = require("../core/schema.cjs");
+const require_api = require("../core/api.cjs");
+const require_fence = require("../database/fence.cjs");
+const require_builtIn = require("../plugins/builtIn.cjs");
+const require_builtInDatabase = require("../db/builtInDatabase.cjs");
+//#region src/assembly/assemblePlugins.ts
+/** A misconfigured `createHotUpdater` call, reported at startup. */
+var HotUpdaterConfigError = class extends Error {
+	name = "HotUpdaterConfigError";
+};
+const PLUGIN_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"provides",
+	"schemaVersion",
+	"schema",
+	"init"
+]);
+const INSTANCE_KEYS = /* @__PURE__ */ new Set([
+	"api",
+	"endpoints",
+	"clientAuth"
+]);
+const METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+const BUILT_IN_ID = /^[a-z][A-Za-z0-9]*$/u;
+const PLUGIN_ID = /^[a-z][a-z0-9_]*$/u;
+const PATH = /^(\/(:?[A-Za-z0-9_.~-]+))+$/u;
+const fail = (message) => {
+	throw new HotUpdaterConfigError(message);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const checkPlugin = (value, at) => {
+	if (!isRecord(value)) return fail(`${at} is not a plugin.`);
+	if ("kind" in value) fail(`${at} has a kind; core is built in and is never passed as a plugin.`);
+	const unknown = Object.keys(value).find((key) => !PLUGIN_KEYS.has(key));
+	if (unknown !== void 0) fail(`${at} has an unknown key "${unknown}".`);
+	const plugin = value;
+	const pattern = plugin[require_builtIn.builtInPlugin] ? BUILT_IN_ID : PLUGIN_ID;
+	if (typeof plugin.id !== "string" || !pattern.test(plugin.id)) fail(`${at} needs an id matching ${pattern.source}.`);
+	if (plugin.id === require_schema.coreModule.id) fail(`${at} uses the id "core", which is core's own.`);
+	if (typeof plugin.schemaVersion !== "string" || !isRecord(plugin.schema) || typeof plugin.init !== "function") fail(`Plugin "${plugin.id}" needs a schemaVersion, a schema, and init.`);
+	const provides = plugin.provides;
+	if (provides !== void 0 && (!isRecord(provides) || Object.entries(provides).some(([key, flag]) => key !== "clientAuth" || flag !== true))) fail(`Plugin "${plugin.id}" may only declare provides: { clientAuth: true }.`);
+	return plugin;
+};
+const checkEndpoint = (id, value) => {
+	const endpoint = isRecord(value) ? value : {};
+	if (!METHODS.has(endpoint.method) || typeof endpoint.path !== "string" || !PATH.test(endpoint.path) || endpoint.access !== "client" && endpoint.access !== "admin" || typeof endpoint.handler !== "function") fail(`Plugin "${id}" has an endpoint that needs a method, a path like /name/:param, access "client" or "admin", and a handler.`);
+	return {
+		...endpoint,
+		plugin: id
+	};
+};
+const checkInstance = (plugin, instance) => {
+	const { id } = plugin;
+	if (!isRecord(instance)) return fail(`Plugin "${id}" init returned no instance.`);
+	if (typeof instance.then === "function") fail(`Plugin "${id}" init returned a promise; init must be synchronous.`);
+	const unknown = Object.keys(instance).find((key) => !INSTANCE_KEYS.has(key));
+	if (unknown !== void 0 || !("api" in instance)) fail(`Plugin "${id}" init must return { api, endpoints?, clientAuth? }${unknown === void 0 ? "" : `, not "${unknown}"`}.`);
+	const declared = plugin.provides?.clientAuth === true;
+	const clientAuth = instance.clientAuth;
+	if (declared !== (clientAuth !== void 0)) fail(declared ? `Plugin "${id}" declares provides: { clientAuth: true } but its instance has no clientAuth.` : `Plugin "${id}" returns clientAuth without declaring provides: { clientAuth: true }.`);
+	if (clientAuth !== void 0 && (typeof clientAuth.authenticate !== "function" || !Array.isArray(clientAuth.varyHeaders) || !clientAuth.varyHeaders.every((header) => typeof header === "string"))) fail(`Plugin "${id}" clientAuth needs varyHeaders and authenticate.`);
+	const endpoints = instance.endpoints ?? [];
+	if (!Array.isArray(endpoints)) fail(`Plugin "${id}" endpoints must be an array.`);
+	return {
+		api: instance.api,
+		clientAuth,
+		endpoints: endpoints.map((endpoint) => checkEndpoint(id, endpoint))
+	};
+};
+/**
+* Checks every plugin, runs each `init` once against one engine over the
+* database's storage adapter, and collects APIs, endpoints, and clientAuth.
+* Core's reads run on the same engine, so plugins read core through `ctx.core`.
+*/
+const assemblePlugins = (value, adapter, { now = Date.now, storage = { resolveFileUrl: async () => null }, verify = false, onCachedRoutesChange } = {}) => {
+	if (!Array.isArray(value)) return fail("plugins must be an array of plugins.");
+	const plugins = value.map((plugin, position) => checkPlugin(plugin, `plugins[${position}]`));
+	const ids = /* @__PURE__ */ new Set();
+	for (const { id } of plugins) {
+		if (ids.has(id)) fail(`Plugin "${id}" is registered twice.`);
+		ids.add(id);
+	}
+	const modules = plugins.map((plugin) => ({
+		id: plugin.id,
+		schema: plugin.schema,
+		...plugin[require_builtIn.builtInPlugin] ? {} : { namespace: plugin.id }
+	}));
+	const added = modules.filter(({ namespace }) => namespace !== void 0);
+	if (added.length > 0) {
+		const taken = added.find(({ id }) => require_builtInDatabase.builtInModules.some((module) => module.id === id));
+		if (taken !== void 0) fail(`Plugin "${taken.id}" uses a built-in plugin's id.`);
+		require_resolveSchema.validateSchema([...require_builtInDatabase.builtInModules, ...added]);
+	}
+	const name = require_fence.fencedName(adapter);
+	const engine = require_database.createDatabaseEngine({
+		adapter: name === void 0 || added.length === 0 ? adapter : require_fence.withSchemaFence(adapter, name, require_builtInDatabase.addedSettings(plugins)),
+		schema: require_resolveSchema.resolveSchema([require_schema.coreModule, ...modules]),
+		verify
+	});
+	const coreDatabase = engine.database(require_schema.coreModule);
+	const core = require_api.createCoreApi(coreDatabase, storage, {
+		now,
+		...onCachedRoutesChange === void 0 ? {} : { onCachedRoutesChange }
+	});
+	const reads = require_reads.createCoreReads(coreDatabase, storage);
+	const api = {};
+	const endpoints = [];
+	let clientAuth;
+	plugins.forEach((plugin, position) => {
+		const instance = checkInstance(plugin, plugin.init({
+			db: engine.database(modules[position]),
+			core: reads,
+			now
+		}));
+		if (instance.clientAuth !== void 0) {
+			if (clientAuth !== void 0) fail(`Plugins "${clientAuth.plugin}" and "${plugin.id}" both provide clientAuth; keep one.`);
+			const provided = instance.clientAuth;
+			clientAuth = {
+				plugin: plugin.id,
+				varyHeaders: provided.varyHeaders,
+				authenticate: (headers) => provided.authenticate(headers)
+			};
+		}
+		endpoints.push(...instance.endpoints);
+		api[plugin.id] = instance.api;
+	});
+	return {
+		core,
+		api,
+		endpoints,
+		...clientAuth === void 0 ? {} : { clientAuth },
+		...verify ? { measureReads: engine.measureReads } : {}
+	};
+};
+//#endregion
+exports.HotUpdaterConfigError = HotUpdaterConfigError;
+exports.assemblePlugins = assemblePlugins;

package/dist/assembly/assemblePlugins.d.cts

@@ -0,0 +1,12 @@
+import "../database/engine.cjs";
+import "../core/reads.cjs";
+import "../core/api.cjs";
+import "../plugins/definePlugin.cjs";
+import { DatabaseAdapter } from "@hot-updater/plugin-core/internal";
+//#region src/assembly/assemblePlugins.d.ts
+/** A misconfigured `createHotUpdater` call, reported at startup. */
+declare class HotUpdaterConfigError extends Error {
+  readonly name = "HotUpdaterConfigError";
+}
+//#endregion
+export { HotUpdaterConfigError };

package/dist/assembly/assemblePlugins.d.mts

@@ -0,0 +1,12 @@
+import "../database/engine.mjs";
+import "../core/reads.mjs";
+import "../core/api.mjs";
+import "../plugins/definePlugin.mjs";
+import { DatabaseAdapter } from "@hot-updater/plugin-core/internal";
+//#region src/assembly/assemblePlugins.d.ts
+/** A misconfigured `createHotUpdater` call, reported at startup. */
+declare class HotUpdaterConfigError extends Error {
+  readonly name = "HotUpdaterConfigError";
+}
+//#endregion
+export { HotUpdaterConfigError };

package/dist/assembly/assemblePlugins.mjs

@@ -0,0 +1,146 @@
+import { resolveSchema, validateSchema } from "../database/resolveSchema.mjs";
+import { createDatabaseEngine } from "../database/database.mjs";
+import { createCoreReads } from "../core/reads.mjs";
+import { coreModule } from "../core/schema.mjs";
+import { createCoreApi } from "../core/api.mjs";
+import { fencedName, withSchemaFence } from "../database/fence.mjs";
+import { builtInPlugin } from "../plugins/builtIn.mjs";
+import { addedSettings, builtInModules } from "../db/builtInDatabase.mjs";
+//#region src/assembly/assemblePlugins.ts
+/** A misconfigured `createHotUpdater` call, reported at startup. */
+var HotUpdaterConfigError = class extends Error {
+	name = "HotUpdaterConfigError";
+};
+const PLUGIN_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"provides",
+	"schemaVersion",
+	"schema",
+	"init"
+]);
+const INSTANCE_KEYS = /* @__PURE__ */ new Set([
+	"api",
+	"endpoints",
+	"clientAuth"
+]);
+const METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+const BUILT_IN_ID = /^[a-z][A-Za-z0-9]*$/u;
+const PLUGIN_ID = /^[a-z][a-z0-9_]*$/u;
+const PATH = /^(\/(:?[A-Za-z0-9_.~-]+))+$/u;
+const fail = (message) => {
+	throw new HotUpdaterConfigError(message);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const checkPlugin = (value, at) => {
+	if (!isRecord(value)) return fail(`${at} is not a plugin.`);
+	if ("kind" in value) fail(`${at} has a kind; core is built in and is never passed as a plugin.`);
+	const unknown = Object.keys(value).find((key) => !PLUGIN_KEYS.has(key));
+	if (unknown !== void 0) fail(`${at} has an unknown key "${unknown}".`);
+	const plugin = value;
+	const pattern = plugin[builtInPlugin] ? BUILT_IN_ID : PLUGIN_ID;
+	if (typeof plugin.id !== "string" || !pattern.test(plugin.id)) fail(`${at} needs an id matching ${pattern.source}.`);
+	if (plugin.id === coreModule.id) fail(`${at} uses the id "core", which is core's own.`);
+	if (typeof plugin.schemaVersion !== "string" || !isRecord(plugin.schema) || typeof plugin.init !== "function") fail(`Plugin "${plugin.id}" needs a schemaVersion, a schema, and init.`);
+	const provides = plugin.provides;
+	if (provides !== void 0 && (!isRecord(provides) || Object.entries(provides).some(([key, flag]) => key !== "clientAuth" || flag !== true))) fail(`Plugin "${plugin.id}" may only declare provides: { clientAuth: true }.`);
+	return plugin;
+};
+const checkEndpoint = (id, value) => {
+	const endpoint = isRecord(value) ? value : {};
+	if (!METHODS.has(endpoint.method) || typeof endpoint.path !== "string" || !PATH.test(endpoint.path) || endpoint.access !== "client" && endpoint.access !== "admin" || typeof endpoint.handler !== "function") fail(`Plugin "${id}" has an endpoint that needs a method, a path like /name/:param, access "client" or "admin", and a handler.`);
+	return {
+		...endpoint,
+		plugin: id
+	};
+};
+const checkInstance = (plugin, instance) => {
+	const { id } = plugin;
+	if (!isRecord(instance)) return fail(`Plugin "${id}" init returned no instance.`);
+	if (typeof instance.then === "function") fail(`Plugin "${id}" init returned a promise; init must be synchronous.`);
+	const unknown = Object.keys(instance).find((key) => !INSTANCE_KEYS.has(key));
+	if (unknown !== void 0 || !("api" in instance)) fail(`Plugin "${id}" init must return { api, endpoints?, clientAuth? }${unknown === void 0 ? "" : `, not "${unknown}"`}.`);
+	const declared = plugin.provides?.clientAuth === true;
+	const clientAuth = instance.clientAuth;
+	if (declared !== (clientAuth !== void 0)) fail(declared ? `Plugin "${id}" declares provides: { clientAuth: true } but its instance has no clientAuth.` : `Plugin "${id}" returns clientAuth without declaring provides: { clientAuth: true }.`);
+	if (clientAuth !== void 0 && (typeof clientAuth.authenticate !== "function" || !Array.isArray(clientAuth.varyHeaders) || !clientAuth.varyHeaders.every((header) => typeof header === "string"))) fail(`Plugin "${id}" clientAuth needs varyHeaders and authenticate.`);
+	const endpoints = instance.endpoints ?? [];
+	if (!Array.isArray(endpoints)) fail(`Plugin "${id}" endpoints must be an array.`);
+	return {
+		api: instance.api,
+		clientAuth,
+		endpoints: endpoints.map((endpoint) => checkEndpoint(id, endpoint))
+	};
+};
+/**
+* Checks every plugin, runs each `init` once against one engine over the
+* database's storage adapter, and collects APIs, endpoints, and clientAuth.
+* Core's reads run on the same engine, so plugins read core through `ctx.core`.
+*/
+const assemblePlugins = (value, adapter, { now = Date.now, storage = { resolveFileUrl: async () => null }, verify = false, onCachedRoutesChange } = {}) => {
+	if (!Array.isArray(value)) return fail("plugins must be an array of plugins.");
+	const plugins = value.map((plugin, position) => checkPlugin(plugin, `plugins[${position}]`));
+	const ids = /* @__PURE__ */ new Set();
+	for (const { id } of plugins) {
+		if (ids.has(id)) fail(`Plugin "${id}" is registered twice.`);
+		ids.add(id);
+	}
+	const modules = plugins.map((plugin) => ({
+		id: plugin.id,
+		schema: plugin.schema,
+		...plugin[builtInPlugin] ? {} : { namespace: plugin.id }
+	}));
+	const added = modules.filter(({ namespace }) => namespace !== void 0);
+	if (added.length > 0) {
+		const taken = added.find(({ id }) => builtInModules.some((module) => module.id === id));
+		if (taken !== void 0) fail(`Plugin "${taken.id}" uses a built-in plugin's id.`);
+		validateSchema([...builtInModules, ...added]);
+	}
+	const name = fencedName(adapter);
+	const engine = createDatabaseEngine({
+		adapter: name === void 0 || added.length === 0 ? adapter : withSchemaFence(adapter, name, addedSettings(plugins)),
+		schema: resolveSchema([coreModule, ...modules]),
+		verify
+	});
+	const coreDatabase = engine.database(coreModule);
+	const core = createCoreApi(coreDatabase, storage, {
+		now,
+		...onCachedRoutesChange === void 0 ? {} : { onCachedRoutesChange }
+	});
+	const reads = createCoreReads(coreDatabase, storage);
+	const api = {};
+	const endpoints = [];
+	let clientAuth;
+	plugins.forEach((plugin, position) => {
+		const instance = checkInstance(plugin, plugin.init({
+			db: engine.database(modules[position]),
+			core: reads,
+			now
+		}));
+		if (instance.clientAuth !== void 0) {
+			if (clientAuth !== void 0) fail(`Plugins "${clientAuth.plugin}" and "${plugin.id}" both provide clientAuth; keep one.`);
+			const provided = instance.clientAuth;
+			clientAuth = {
+				plugin: plugin.id,
+				varyHeaders: provided.varyHeaders,
+				authenticate: (headers) => provided.authenticate(headers)
+			};
+		}
+		endpoints.push(...instance.endpoints);
+		api[plugin.id] = instance.api;
+	});
+	return {
+		core,
+		api,
+		endpoints,
+		...clientAuth === void 0 ? {} : { clientAuth },
+		...verify ? { measureReads: engine.measureReads } : {}
+	};
+};
+//#endregion
+export { HotUpdaterConfigError, assemblePlugins };

package/dist/assembly/databasePlugins.cjs

@@ -0,0 +1,23 @@
+const require_api = require("../core/api.cjs");
+const require_assemblePlugins = require("./assemblePlugins.cjs");
+//#region src/assembly/databasePlugins.ts
+function createDatabasePluginApis(database, plugins, options = {}) {
+	const adapter = require_api.engineAdapterOf(database);
+	if (adapter === void 0) throw new Error(require_api.OFF_ENGINE_DATABASE);
+	return require_assemblePlugins.assemblePlugins(plugins, adapter, options).api;
+}
+function createMeasuredDatabase(adapter, plugins, options = {}) {
+	const { core, api, clientAuth, measureReads } = require_assemblePlugins.assemblePlugins(plugins, adapter, {
+		...options,
+		verify: true
+	});
+	return {
+		core,
+		api,
+		...clientAuth === void 0 ? {} : { clientAuth },
+		measureReads
+	};
+}
+//#endregion
+exports.createDatabasePluginApis = createDatabasePluginApis;
+exports.createMeasuredDatabase = createMeasuredDatabase;

package/dist/assembly/databasePlugins.d.cts

@@ -0,0 +1,43 @@
+import { ReadMeasurement } from "../database/engine.cjs";
+import { CoreStorage } from "../core/reads.cjs";
+import { CoreApi } from "../core/api.cjs";
+import { AnyHotUpdaterPlugin, ClientAuth, PluginApis } from "../plugins/definePlugin.cjs";
+import { DatabaseAdapter } from "@hot-updater/plugin-core/internal";
+//#region src/assembly/databasePlugins.d.ts
+/**
+ * The plugins' APIs by plugin id over a configured database, assembled as
+ * `createHotUpdater` assembles them: how the console runs Insights and API
+ * keys in process, and how init provisions a key, on the tables the server
+ * uses. A database off the storage engine, `standaloneRepository` included,
+ * is refused: its server runs the plugins.
+ */
+declare function createDatabasePluginApis<const TPlugins extends readonly AnyHotUpdaterPlugin[]>(database: unknown, plugins: TPlugins, options?: {
+  readonly now?: () => number;
+}): PluginApis<TPlugins>;
+declare function createDatabasePluginApis(database: unknown, plugins: readonly unknown[], options?: {
+  readonly now?: () => number;
+}): Readonly<Record<string, unknown>>;
+interface MeasuredDatabaseOptions {
+  readonly now?: () => number;
+  /** How core reads bundle manifests and resolves file URLs, for artifact resolution. */
+  readonly storage?: CoreStorage;
+}
+/** Core and the plugins' APIs on one engine in verify mode, and its read meter. */
+interface MeasuredDatabase<TApi = Readonly<Record<string, unknown>>> {
+  readonly core: CoreApi;
+  readonly api: TApi;
+  /** The client-route policy, when a plugin provides one. */
+  readonly clientAuth?: ClientAuth;
+  /** Runs `read` and reports what it read at both boundaries. */
+  measureReads<T>(read: () => Promise<T>): Promise<ReadMeasurement<T>>;
+}
+/**
+ * Core and the plugins over a storage adapter, assembled as
+ * `createHotUpdater` assembles them but on an engine in verify mode, with
+ * that engine's `measureReads`: what read-budget suites measure. The adapter
+ * runs as given, without the schema fence.
+ */
+declare function createMeasuredDatabase<const TPlugins extends readonly AnyHotUpdaterPlugin[]>(adapter: DatabaseAdapter, plugins: TPlugins, options?: MeasuredDatabaseOptions): MeasuredDatabase<PluginApis<TPlugins>>;
+declare function createMeasuredDatabase(adapter: DatabaseAdapter, plugins: readonly unknown[], options?: MeasuredDatabaseOptions): MeasuredDatabase;
+//#endregion
+export { MeasuredDatabase, MeasuredDatabaseOptions, createDatabasePluginApis, createMeasuredDatabase };

package/dist/assembly/databasePlugins.d.mts

@@ -0,0 +1,43 @@
+import { ReadMeasurement } from "../database/engine.mjs";
+import { CoreStorage } from "../core/reads.mjs";
+import { CoreApi } from "../core/api.mjs";
+import { AnyHotUpdaterPlugin, ClientAuth, PluginApis } from "../plugins/definePlugin.mjs";
+import { DatabaseAdapter } from "@hot-updater/plugin-core/internal";
+//#region src/assembly/databasePlugins.d.ts
+/**
+ * The plugins' APIs by plugin id over a configured database, assembled as
+ * `createHotUpdater` assembles them: how the console runs Insights and API
+ * keys in process, and how init provisions a key, on the tables the server
+ * uses. A database off the storage engine, `standaloneRepository` included,
+ * is refused: its server runs the plugins.
+ */
+declare function createDatabasePluginApis<const TPlugins extends readonly AnyHotUpdaterPlugin[]>(database: unknown, plugins: TPlugins, options?: {
+  readonly now?: () => number;
+}): PluginApis<TPlugins>;
+declare function createDatabasePluginApis(database: unknown, plugins: readonly unknown[], options?: {
+  readonly now?: () => number;
+}): Readonly<Record<string, unknown>>;
+interface MeasuredDatabaseOptions {
+  readonly now?: () => number;
+  /** How core reads bundle manifests and resolves file URLs, for artifact resolution. */
+  readonly storage?: CoreStorage;
+}
+/** Core and the plugins' APIs on one engine in verify mode, and its read meter. */
+interface MeasuredDatabase<TApi = Readonly<Record<string, unknown>>> {
+  readonly core: CoreApi;
+  readonly api: TApi;
+  /** The client-route policy, when a plugin provides one. */
+  readonly clientAuth?: ClientAuth;
+  /** Runs `read` and reports what it read at both boundaries. */
+  measureReads<T>(read: () => Promise<T>): Promise<ReadMeasurement<T>>;
+}
+/**
+ * Core and the plugins over a storage adapter, assembled as
+ * `createHotUpdater` assembles them but on an engine in verify mode, with
+ * that engine's `measureReads`: what read-budget suites measure. The adapter
+ * runs as given, without the schema fence.
+ */
+declare function createMeasuredDatabase<const TPlugins extends readonly AnyHotUpdaterPlugin[]>(adapter: DatabaseAdapter, plugins: TPlugins, options?: MeasuredDatabaseOptions): MeasuredDatabase<PluginApis<TPlugins>>;
+declare function createMeasuredDatabase(adapter: DatabaseAdapter, plugins: readonly unknown[], options?: MeasuredDatabaseOptions): MeasuredDatabase;
+//#endregion
+export { MeasuredDatabase, MeasuredDatabaseOptions, createDatabasePluginApis, createMeasuredDatabase };

package/dist/assembly/databasePlugins.mjs

@@ -0,0 +1,22 @@
+import { OFF_ENGINE_DATABASE, engineAdapterOf } from "../core/api.mjs";
+import { assemblePlugins } from "./assemblePlugins.mjs";
+//#region src/assembly/databasePlugins.ts
+function createDatabasePluginApis(database, plugins, options = {}) {
+	const adapter = engineAdapterOf(database);
+	if (adapter === void 0) throw new Error(OFF_ENGINE_DATABASE);
+	return assemblePlugins(plugins, adapter, options).api;
+}
+function createMeasuredDatabase(adapter, plugins, options = {}) {
+	const { core, api, clientAuth, measureReads } = assemblePlugins(plugins, adapter, {
+		...options,
+		verify: true
+	});
+	return {
+		core,
+		api,
+		...clientAuth === void 0 ? {} : { clientAuth },
+		measureReads
+	};
+}
+//#endregion
+export { createDatabasePluginApis, createMeasuredDatabase };

package/dist/core/api.cjs

@@ -0,0 +1,91 @@
+const require_resolveSchema = require("../database/resolveSchema.cjs");
+const require_database = require("../database/database.cjs");
+const require_reads = require("./reads.cjs");
+const require_operations = require("./operations.cjs");
+const require_schema = require("./schema.cjs");
+//#region src/core/api.ts
+/**
+* The update check answers from one Release Catalog row, so a transaction
+* changes what the cacheable client routes answer only when it writes one.
+* The purge runs once, after the attempt that commits.
+*/
+const purgingCachedRoutes = (db, onCachedRoutesChange) => {
+	if (onCachedRoutesChange === void 0) return db;
+	return {
+		...db,
+		async transaction(fn) {
+			let changed = false;
+			const result = await db.transaction((tx) => {
+				changed = false;
+				return fn({
+					...tx,
+					create: (model, row) => {
+						changed ||= model === "release_catalogs";
+						tx.create(model, row);
+					},
+					update: (model, row, set) => {
+						changed ||= model === "release_catalogs";
+						tx.update(model, row, set);
+					},
+					delete: (model, row) => {
+						changed ||= model === "release_catalogs";
+						return tx.delete(model, row);
+					}
+				});
+			});
+			if (changed) await onCachedRoutesChange();
+			return result;
+		}
+	};
+};
+/** Core's reads and typed writes over one database handle. */
+const createCoreApi = (db, storage, options = {}) => {
+	const reads = require_reads.createCoreReads(db, storage);
+	return {
+		...reads,
+		...require_operations.createCoreOperations(purgingCachedRoutes(db, options.onCachedRoutesChange), options),
+		/** One read, which checks the schema settings first. */
+		ready: async () => {
+			await reads.listReleaseCatalogs({ limit: 1 });
+		}
+	};
+};
+/**
+* Core's API in process, on a database's storage adapter: how the CLI reads
+* and writes a database that runs on the storage engine.
+*/
+const createInProcessCoreApi = (adapter, options = {}) => createCoreApi(require_database.createDatabaseEngine({
+	adapter,
+	schema: require_resolveSchema.resolveSchema([require_schema.coreModule])
+}).database(require_schema.coreModule), { resolveFileUrl: async () => null }, options);
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isAdapter = (value) => isRecord(value) && [
+	"fits",
+	"get",
+	"query",
+	"write"
+].every((method) => typeof value[method] === "function");
+/** The storage adapter a configured database runs on, if it is on the engine. */
+const engineAdapterOf = (database) => isRecord(database) && isAdapter(database.adapter) ? database.adapter : isAdapter(database) ? database : void 0;
+const OFF_ENGINE_DATABASE = "This database does not run on Hot Updater's storage engine. Upgrade its provider package to 1.0.";
+/**
+* Core's API for a configured database, as the CLI uses it: a self-hosted
+* server's admin API when the database is `standaloneRepository`, or the
+* database's own storage adapter, in process.
+*/
+const createDatabaseCoreApi = (database, options = {}) => {
+	if (isRecord(database) && isRecord(database.core)) return database.core;
+	const adapter = engineAdapterOf(database);
+	if (adapter === void 0) throw new Error(OFF_ENGINE_DATABASE);
+	const engineDatabase = database;
+	return createInProcessCoreApi(adapter, {
+		...options,
+		...typeof engineDatabase.onCachedRoutesChange === "function" ? { onCachedRoutesChange: () => engineDatabase.onCachedRoutesChange() } : {}
+	});
+};
+//#endregion
+exports.OFF_ENGINE_DATABASE = OFF_ENGINE_DATABASE;
+exports.createCoreApi = createCoreApi;
+exports.createDatabaseCoreApi = createDatabaseCoreApi;
+exports.createInProcessCoreApi = createInProcessCoreApi;
+exports.engineAdapterOf = engineAdapterOf;

package/dist/core/api.d.cts

@@ -0,0 +1,65 @@
+import { ReleaseCatalogRequest } from "../db/releaseCatalog.cjs";
+import { CoreDatabase, CoreStorage } from "./reads.cjs";
+import { HotUpdaterCoreApi } from "@hot-updater/plugin-core";
+import { DatabaseAdapter } from "@hot-updater/plugin-core/internal";
+//#region src/core/api.d.ts
+interface CoreApiOptions {
+  readonly now?: () => number;
+  /** The database's CDN purge, called after a write that changes a Release Catalog. */
+  readonly onCachedRoutesChange?: () => Promise<void>;
+}
+/** Core's reads and typed writes over one database handle. */
+declare const createCoreApi: (db: CoreDatabase, storage: CoreStorage, options?: CoreApiOptions) => {
+  /** One read, which checks the schema settings first. */
+  ready: () => Promise<void>;
+  deploy: (deployments: readonly import("@hot-updater/plugin-core").Deployment[]) => Promise<import("@hot-updater/plugin-core").ReleaseCatalogMutationResult[]>;
+  updateReleasePolicy: (input: import("@hot-updater/plugin-core").ReleaseTarget & {
+    readonly patch: import("@hot-updater/plugin-core").ReleasePolicyPatch;
+  }) => Promise<import("@hot-updater/plugin-core").ReleaseCatalogMutationResult>;
+  preflightReleasePolicy: (input: import("@hot-updater/plugin-core").ReleaseTarget & {
+    readonly patch: import("@hot-updater/plugin-core").ReleasePolicyPatch;
+  }) => Promise<import("@hot-updater/plugin-core").ReleaseCatalogMutationPreflight>;
+  deleteRelease: (input: import("@hot-updater/plugin-core").ReleaseTarget) => Promise<import("@hot-updater/plugin-core").ReleaseCatalogMutationResult>;
+  promoteRelease: (input: import("@hot-updater/plugin-core").ReleaseTarget & {
+    readonly targetChannel: string;
+    readonly action?: "copy" | "move";
+  }) => Promise<import("@hot-updater/plugin-core").PromoteReleaseResult>;
+  rebuildReleaseCatalog: (scopeKey: string) => Promise<import("@hot-updater/plugin-core").ReleaseCatalogRebuildResult>;
+  preflightReleaseCatalogRebuild: (scopeKey: string) => Promise<import("@hot-updater/plugin-core").ReleaseCatalogRebuildPreflight>;
+  ensureChannel: (name: string) => Promise<import("@hot-updater/plugin-core").ChannelRow>;
+  deleteChannel: (id: string) => Promise<import("@hot-updater/plugin-core").ChannelDeleteResult>;
+  updateBundle: (id: string, update: Partial<Omit<import("@hot-updater/core").Bundle, "id" | "patches">> & {
+    readonly patches?: import("@hot-updater/core").Bundle["patches"];
+  }) => Promise<void>;
+  deleteBundles: (ids: readonly string[]) => Promise<void>;
+  getReleaseCatalog(input: ReleaseCatalogRequest): Promise<import("@hot-updater/core").ReleaseCatalog | null>;
+  getArtifactInfo(targetBundleId: string, currentBundleId: string, artifactProtocolVersion: 1): Promise<import("@hot-updater/core").ArtifactInfo | null>;
+  getBundle(id: string): Promise<import("@hot-updater/plugin-core").BundleDetail | null>;
+  countBundleChildren(baseBundleIds: readonly string[]): Promise<Record<string, number>>;
+  listPatchesFromBase(baseBundleId: string, input: import("@hot-updater/plugin-core").KeysetInput): Promise<import("@hot-updater/plugin-core").BundlePatchRow[]>;
+  listBundles(input: import("@hot-updater/plugin-core").KeysetInput & {
+    readonly platform?: "ios" | "android";
+  }): Promise<import("@hot-updater/plugin-core").BundleDetail[]>;
+  countBundles(platform?: "ios" | "android"): Promise<number>;
+  findBaseBundleIds(candidateKey: string, bundleId: string, limit: number): Promise<string[]>;
+  getRelease(id: string): Promise<import("@hot-updater/plugin-core").ReleaseRow | null>;
+  listReleases(input: import("@hot-updater/plugin-core").KeysetInput & {
+    readonly filter: import("@hot-updater/plugin-core").ReleaseFilter;
+  }): Promise<import("@hot-updater/plugin-core").ReleaseRow[]>;
+  latestReleaseId(scopeKey: string): Promise<string | null>;
+  getReleaseCatalogRow(scopeKey: string): Promise<import("@hot-updater/plugin-core").ReleaseCatalogRow | null>;
+  listReleaseCatalogs(input: import("@hot-updater/plugin-core").KeysetInput): Promise<import("@hot-updater/plugin-core").ReleaseCatalogRow[]>;
+  listChannels(): Promise<import("@hot-updater/plugin-core").ChannelRow[]>;
+  findChannelByName(name: string): Promise<import("@hot-updater/plugin-core").ChannelRow | null>;
+};
+type CoreApi = ReturnType<typeof createCoreApi>;
+/**
+ * Core's API for a configured database, as the CLI uses it: a self-hosted
+ * server's admin API when the database is `standaloneRepository`, or the
+ * database's own storage adapter, in process.
+ */
+declare const createDatabaseCoreApi: (database: unknown, options?: {
+  readonly now?: () => number;
+}) => HotUpdaterCoreApi;
+//#endregion
+export { CoreApi, CoreApiOptions, createCoreApi, createDatabaseCoreApi };