@protobase/server 0.0.0-stage → 0.1.1

package/dist/filter-input.js

@@ -0,0 +1,28 @@
+import { badRequest } from "./problem.js";
+import { checkFilter, checkOrderBy, parseFilter, parseOrderBy } from "@protobase/schema";
+//#region src/filter-input.ts
+const filterProblem = (parameter, errors) => badRequest(parameter === "filter" ? "invalid-filter" : "invalid-order-by", `The ${parameter} parameter is invalid: ${errors[0].message}`, {
+	parameter,
+	errors
+});
+/** AIP-160 text to a checked filter; throws a 400 problem carrying the checker's errors with spans and hints. */
+const checkedFilter = (model, source, maxLength) => {
+	if (!source?.trim()) return void 0;
+	const parsed = parseFilter(source, maxLength ? { maxLength } : {});
+	if (!parsed.ok) throw filterProblem("filter", parsed.errors);
+	if (!parsed.ast) return void 0;
+	const checked = checkFilter(model, parsed.ast);
+	if (!checked.ok) throw filterProblem("filter", checked.errors);
+	return checked.filter;
+};
+/** AIP-132 `order_by` text to a sort spec; throws a 400 problem on any error. */
+const checkedSort = (model, source) => {
+	if (!source?.trim()) return void 0;
+	const parsed = parseOrderBy(source);
+	if (!parsed.ok) throw filterProblem("order_by", parsed.errors);
+	const checked = checkOrderBy(model, parsed.items);
+	if (!checked.ok) throw filterProblem("order_by", checked.errors);
+	return checked.sort;
+};
+//#endregion
+export { checkedFilter, checkedSort };

package/dist/filter-shape.js

@@ -0,0 +1,25 @@
+//#region src/filter-shape.ts
+/** The filter with its values blanked out: queries that differ only in values share a shape. */
+const filterShape = (filter) => {
+	if (!filter) return "";
+	switch (filter.kind) {
+		case "and":
+		case "or": return `${filter.kind}(${filter.args.map(filterShape).join(",")})`;
+		case "not": return `not(${filterShape(filter.arg)})`;
+		case "compare": return `${filter.field.name}${filter.op}?`;
+		case "search": return "search";
+		default: return `${filter.kind}:${filter.field.name}`;
+	}
+};
+const filterFields = (filter) => {
+	if (!filter) return [];
+	switch (filter.kind) {
+		case "and":
+		case "or": return filter.args.flatMap(filterFields);
+		case "not": return filterFields(filter.arg);
+		case "search": return [];
+		default: return [filter.field];
+	}
+};
+//#endregion
+export { filterFields, filterShape };

package/dist/hash.js

@@ -0,0 +1,10 @@
+//#region src/hash.ts
+/** Hex SHA-256 of a string, through Web Crypto so it runs on Node and Workers. */
+const sha256Hex = async (text) => {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+/** JSON with object keys sorted, so equal content always serializes equally. */
+const stableJson = (value) => JSON.stringify(value, (_, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : v);
+//#endregion
+export { sha256Hex, stableJson };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { AdminAuth, CreateAuthOptions, createAuth, normalizeRoles } from "./better-auth/create-auth.js";
+import { ResourceSource, configExports } from "./resource-source.js";
+import { Admin, AdminOptions, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
+import { CreateAdminInput, createAdmin } from "./create-admin.js";
+import { consoleAuditQueue } from "./audit/console-queue.js";
+import { JwtOptions, jwtAuthenticator } from "./auth/jwt.js";
+import { HttpProblem, badRequest, forbidden, notFound, unauthorized } from "./problem.js";
+import { BetterAuthAuthenticatorOptions, betterAuthAuthenticator } from "./better-auth/authenticator.js";
+import { NewUser, StoredUser, createUser, deleteUser, hasUsers, listUsers, parseRoles, roleChoices, setUserBanned, setUserRole } from "./better-auth/users.js";
+import { IssueTokenOptions, issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
+export { type Admin, type AdminAuth, type AdminOptions, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type CreateAdminInput, type CreateAuthOptions, HttpProblem, type IssueTokenOptions, type JwtOptions, type NewUser, type PipelineHook, type ResourceSource, type ScanGuardMode, type Session, type StoredUser, type TenantValue, type User, type ViewSource, type WriteEvent, type WriteOperation, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, createAdmin, createAuth, createUser, deleteUser, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, roleChoices, setUserBanned, setUserRole, unauthorized };

package/dist/index.js

@@ -0,0 +1,10 @@
+import { consoleAuditQueue } from "./audit/console-queue.js";
+import { createAuth, normalizeRoles } from "./better-auth/create-auth.js";
+import { createUser, deleteUser, hasUsers, listUsers, parseRoles, roleChoices, setUserBanned, setUserRole } from "./better-auth/users.js";
+import { HttpProblem, badRequest, forbidden, notFound, unauthorized } from "./problem.js";
+import { createAdmin } from "./create-admin.js";
+import { configExports } from "./resource-source.js";
+import { jwtAuthenticator } from "./auth/jwt.js";
+import { betterAuthAuthenticator } from "./better-auth/authenticator.js";
+import { issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
+export { HttpProblem, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, createAdmin, createAuth, createUser, deleteUser, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, roleChoices, setUserBanned, setUserRole, unauthorized };

package/dist/key.js

@@ -0,0 +1,22 @@
+import { badRequest } from "./problem.js";
+import { decodeKey } from "@protobase/schema";
+//#region src/key.ts
+/** Decodes key text (`a,b` for composite keys, parts percent-encoded). decodeKey is a pure parser: every error it throws is a malformed key. */
+const decodeKeyText = (entry, raw) => {
+	try {
+		const key = decodeKey(raw, entry.keyTypes);
+		return Array.isArray(key) ? key : [key];
+	} catch {
+		throw badRequest("invalid-key", `"${raw}" is not a valid ${entry.name} key`);
+	}
+};
+/**
+* The key from the `:key` path segment, minus a custom method `suffix` such as `:undelete`. A single key is Hono's decoded
+* param; composite parts stay percent-encoded so an encoded comma inside a part survives.
+*/
+const keyFromPath = (c, entry, suffix = "") => {
+	const segment = entry.keyTypes.length === 1 ? c.req.param("key") : new URL(c.req.url).pathname.split("/").pop();
+	return decodeKeyText(entry, suffix && segment.endsWith(suffix) ? segment.slice(0, -suffix.length) : segment);
+};
+//#endregion
+export { decodeKeyText, keyFromPath };

package/dist/list-service.js

@@ -0,0 +1,96 @@
+import { checkedFilter, checkedSort } from "./filter-input.js";
+import { readScope, requestAccess, requireOperation } from "./request-access.js";
+import { readTransaction } from "./transactions.js";
+import { etagAlias } from "./sql-parts.js";
+import { etagOf } from "./etag.js";
+import { exposeRow, pickFields } from "./rows.js";
+import { deletedRows, listParams, pageSizeOf, parseParams, seekParams, selectedFields } from "./params.js";
+import { rowPermissions } from "./row-permissions.js";
+import { estimateCount, exactCount, listQuery, seekToPosition } from "@protobase/query";
+//#region src/list-service.ts
+/**
+* AIP-132 list, the `:search` variant and (with `jump`) `:seek`: both take the same parameters, from the query string or a JSON body.
+* Everything the caller names (filter, order_by, fields, search) is checked against the model as this caller sees it,
+* so a hidden field is refused exactly like an unknown one; the access row filter is applied by the query layer.
+*/
+const listRecords = async (deps, entry, session, input, maxFilterLength, jump = false) => {
+	const params = jump ? parseParams(seekParams, input) : parseParams(listParams, input);
+	const access = await requestAccess(deps, entry, session);
+	requireOperation(access, "list");
+	const showDeleted = deletedRows(access.full, params.show_deleted) === "show";
+	const full = showDeleted ? {
+		...access.full,
+		softDelete: void 0
+	} : access.full;
+	const model = showDeleted ? {
+		...access.model,
+		softDelete: void 0
+	} : access.model;
+	const filter = checkedFilter(model, params.filter, maxFilterLength);
+	const sort = checkedSort(model, params.order_by);
+	const columns = selectedFields(model, params.fields);
+	const limit = pageSizeOf(params.page_size);
+	const scope = readScope(access, full);
+	const etagField = entry.etag && !model.fields[entry.etag.field.name] ? full.fields[entry.etag.field.name] : void 0;
+	const queryModel = etagField ? {
+		...model,
+		fields: {
+			...model.fields,
+			[etagField.name]: etagField
+		}
+	} : model;
+	const read = entry.etag && columns ? columns : Object.keys(model.fields);
+	const shape = {
+		...filter && { filter },
+		...sort && { sort },
+		limit
+	};
+	const warning = await deps.guard(entry, shape, {
+		model: queryModel,
+		scope
+	});
+	const position = jump ? params.position : void 0;
+	const result = await readTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
+		const extraColumns = entry.etag ? [{
+			field: entry.etag.field.name,
+			as: "text",
+			alias: etagAlias
+		}] : [];
+		const page = position === void 0 ? await listQuery(trx, queryModel, {
+			...shape,
+			columns: read,
+			...params.page_token && { cursor: params.page_token }
+		}, scope, { extraColumns }) : await seekToPosition(trx, queryModel, {
+			position,
+			orderBy: sort ?? [[entry.model.primaryKey[0], "asc"]],
+			...filter && { filter },
+			columns: read,
+			limit
+		}, scope, { extraColumns });
+		const rows = page.rows.map((row) => exposeRow(model, row));
+		return {
+			page,
+			rows,
+			etags: await Promise.all(rows.map((row, i) => etagOf(entry, page.rows[i], row))),
+			permissions: deps.rowPermissions(entry.name) ? await rowPermissions(trx, access, rows) : void 0,
+			estimate: await estimateCount(trx, queryModel, filter, scope),
+			...params.count === "exact" && { total: await exactCount(trx, queryModel, filter, scope) }
+		};
+	});
+	return {
+		warning,
+		body: {
+			items: result.rows.map((row, i) => ({
+				...pickFields(row, columns),
+				etag: result.etags[i],
+				...result.permissions && { permissions: result.permissions[i] }
+			})),
+			next_page_token: result.page.nextCursor ?? "",
+			...position !== void 0 && { prev_page_token: result.page.prevCursor ?? "" },
+			total_size_estimate: result.estimate,
+			...result.total !== void 0 && { total_size: result.total }
+		}
+	};
+};
+//#endregion
+export { listRecords };

package/dist/mail/mail-settings.js

@@ -0,0 +1,26 @@
+//#region src/mail/mail-settings.ts
+const smtpUrlVariable = "PROTOBASE_SMTP_URL";
+const mailFromVariable = "PROTOBASE_MAIL_FROM";
+const address = /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/;
+/**
+* The SMTP server and sender the platform passes in `PROTOBASE_SMTP_URL` and `PROTOBASE_MAIL_FROM`; `undefined` when
+* neither is set, which turns mail (and so password reset) off. One without the other, or a value that cannot be used,
+* is a configuration error, so the server stops at startup instead of failing on the first reset request.
+*/
+const readMailSettings = (env) => {
+	const smtpUrl = env["PROTOBASE_SMTP_URL"] || void 0;
+	const from = env["PROTOBASE_MAIL_FROM"]?.trim() || void 0;
+	if (!smtpUrl && !from) return void 0;
+	if (!smtpUrl || !from) throw new Error(`${smtpUrlVariable} and ${mailFromVariable} go together: set both to send mail, or neither`);
+	if (!URL.canParse(smtpUrl)) throw new Error(`${smtpUrlVariable} is not a URL; use smtp://user:password@host:587 or smtps://...:465`);
+	const url = new URL(smtpUrl);
+	if (url.protocol !== "smtp:" && url.protocol !== "smtps:") throw new Error(`${smtpUrlVariable} must start with smtp:// or smtps://, not ${url.protocol}//`);
+	if (!url.hostname) throw new Error(`${smtpUrlVariable} has no host`);
+	if (!address.test(from)) throw new Error(`${mailFromVariable} must be a plain email address, like noreply@example.com`);
+	return {
+		smtpUrl,
+		from
+	};
+};
+//#endregion
+export { mailFromVariable, readMailSettings, smtpUrlVariable };

package/dist/mail/smtp-mailer.d.ts

@@ -0,0 +1,11 @@
+//#region src/mail/smtp-mailer.d.ts
+export type MailMessage = {
+  to: string;
+  subject: string;
+  text: string;
+};
+/** Sends one message; rejects when the server refuses it. */
+export type Mailer = {
+  send: (message: MailMessage) => Promise<void>;
+};
+//#endregion

package/dist/mail/smtp-mailer.js

@@ -0,0 +1,17 @@
+//#region src/mail/smtp-mailer.ts
+/**
+* Plain-text mail over SMTP with Nodemailer: the most used Node SMTP client, maintained, with no dependencies of its
+* own. It is loaded on the first message, so `@protobase/server` itself stays free of Node's network modules.
+*/
+const smtpMailer = (settings) => {
+	let transport;
+	return { send: async (message) => {
+		transport ??= import("nodemailer").then(({ createTransport }) => createTransport(settings.smtpUrl));
+		await (await transport).sendMail({
+			from: settings.from,
+			...message
+		});
+	} };
+};
+//#endregion
+export { smtpMailer };

package/dist/meta.js

@@ -0,0 +1,63 @@
+import { sha256Hex, stableJson } from "./hash.js";
+import { requestAccess } from "./request-access.js";
+import { pruneView } from "./view-access.js";
+import { prunePage } from "@protobase/layout";
+import { pickView } from "@protobase/schema";
+//#region src/meta.ts
+const modelsHash = (deps) => sha256Hex(stableJson(deps.registry.entries.map((entry) => entry.model))).then((hash) => hash.slice(0, 32));
+/**
+* `/meta` as one caller sees it: the resources they can do anything with, each as the restricted model (hidden fields
+* absent, `readOnly` unless writable), the view for their roles with hidden fields pruned, what they may do, and the
+* user menu without the resources they cannot see.
+* The ETag hashes all of it, so it differs per user and per roles.
+*/
+const createMeta = (deps) => {
+	const base = modelsHash(deps);
+	const forCaller = async (session) => {
+		const visible = (await Promise.all(deps.registry.entries.map((entry) => requestAccess(deps, entry, session)))).filter((access) => Object.values(access.resolved.operations).some(Boolean));
+		const listed = Object.fromEntries(visible.map((access) => [access.entry.name, access.model]));
+		const views = visible.flatMap((access) => {
+			const view = pickView(deps.views, session.user.roles, access.entry.name);
+			return view ? [pruneView(view, access.readable, listed)] : [];
+		});
+		const callerAccess = {
+			models: listed,
+			permissions: Object.fromEntries(visible.map(({ entry, resolved }) => [entry.name, {
+				create: resolved.operations.create,
+				update: resolved.operations.update
+			}])),
+			actions: (resource) => new Set(views.find((view) => view.resource === resource)?.actions.map((action) => action.name) ?? [])
+		};
+		const pages = deps.pages.flatMap((page) => prunePage(page, session.user.roles, callerAccess) ?? []);
+		const shown = (item) => item.kind === "link" || (item.kind === "resource" ? visible.some((access) => access.entry.name === item.resource) : pages.some((page) => page.name === item.page));
+		const body = {
+			resources: visible.map((access) => access.readable),
+			views,
+			pages,
+			permissions: Object.fromEntries(visible.map(({ entry, resolved }) => [entry.name, {
+				read: resolved.operations.read || resolved.operations.list,
+				create: resolved.operations.create,
+				update: resolved.operations.update,
+				delete: resolved.operations.delete,
+				conditional: [
+					"create",
+					"update",
+					"delete"
+				].filter((op) => resolved.operations[op] && (resolved.recordChecks.includes(op) || resolved.rowFilter[op] !== void 0))
+			}])),
+			...deps.userMenu && { userMenu: { items: deps.userMenu.items.filter(shown) } }
+		};
+		return {
+			body,
+			etag: `"${(await sha256Hex(stableJson(body))).slice(0, 32)}"`
+		};
+	};
+	/** The X-Meta-Version header: the models, and the roles the access depends on, so a role change moves it. */
+	const version = async (roles) => (await sha256Hex(`${await base}|${[...roles].sort().join(",")}`)).slice(0, 32);
+	return {
+		forCaller,
+		version
+	};
+};
+//#endregion
+export { createMeta };

package/dist/openapi/components.js

@@ -0,0 +1,331 @@
+//#region src/openapi/components.ts
+const problemContent = { "application/problem+json": { schema: { $ref: "#/components/schemas/Problem" } } };
+const problem = (description) => ({
+	description,
+	content: problemContent
+});
+const problemSchema = {
+	type: "object",
+	description: "RFC 9457 problem details",
+	required: [
+		"type",
+		"title",
+		"status",
+		"detail"
+	],
+	properties: {
+		type: {
+			type: "string",
+			description: "A URN naming the kind of problem"
+		},
+		title: { type: "string" },
+		status: { type: "integer" },
+		detail: { type: "string" },
+		instance: {
+			type: "string",
+			description: "The request path"
+		},
+		parameter: {
+			type: "string",
+			description: "For filter and order_by errors, the offending parameter"
+		},
+		errors: {
+			type: "array",
+			description: "Filter and order_by errors (code, message, hint, span) or field errors (field, code, message)",
+			items: {
+				type: "object",
+				additionalProperties: true
+			}
+		}
+	},
+	additionalProperties: true
+};
+const errorResponses = {
+	BadRequest: problem("Invalid filter, order_by, parameter, key or body"),
+	Unauthorized: problem("Missing or invalid credentials"),
+	Forbidden: problem("The caller may not do this, or has no tenant"),
+	NotFound: problem("No such resource or record, or the record belongs to another tenant"),
+	PreconditionFailed: problem("If-Match no longer matches the record"),
+	PreconditionRequired: problem("If-Match is required"),
+	Conflict: problem("A unique or foreign key constraint rejected the write")
+};
+const parameters = {
+	filter: {
+		name: "filter",
+		in: "query",
+		description: [
+			"An [AIP-160](https://google.aip.dev/160) filter, for example `status = \"confirmed\" AND total > 100`.",
+			"Only filterable fields can be used.",
+			"Functions: `in(field, v1, v2, ...)`, `search(\"text\")` (also bare words), `similar(field, \"text\")`, `regex(field, \"pattern\")`, `isNull(field)`, `now()` with a duration offset such as `now() - 7d`.",
+			"Syntax errors come back as a problem with `errors` carrying spans and hints."
+		].join(" "),
+		schema: { type: "string" }
+	},
+	orderBy: {
+		name: "order_by",
+		in: "query",
+		description: "Comma separated sortable fields, each with an optional `desc`, as in [AIP-132](https://google.aip.dev/132#ordering): `createdAt desc, number`. The primary key breaks ties.",
+		schema: { type: "string" }
+	},
+	pageSize: {
+		name: "page_size",
+		in: "query",
+		description: "As in [AIP-158](https://google.aip.dev/158): default 50, maximum 500 (larger values are coerced).",
+		schema: {
+			type: "integer",
+			minimum: 0,
+			maximum: 500
+		}
+	},
+	pageToken: {
+		name: "page_token",
+		in: "query",
+		description: "The `next_page_token` of the previous page",
+		schema: { type: "string" }
+	},
+	fields: {
+		name: "fields",
+		in: "query",
+		description: "Comma separated field names to return",
+		schema: { type: "string" }
+	},
+	count: {
+		name: "count",
+		in: "query",
+		description: "`exact` adds `total_size`, a real count(*)",
+		schema: {
+			type: "string",
+			enum: ["exact"]
+		}
+	},
+	key: {
+		name: "key",
+		in: "path",
+		required: true,
+		description: "The primary key. Composite keys are comma separated parts, each percent-encoded.",
+		schema: { type: "string" }
+	},
+	ifMatch: {
+		name: "If-Match",
+		in: "header",
+		required: true,
+		description: "The `etag` of the record, from a GET or a list item; `*` matches any version",
+		schema: { type: "string" }
+	},
+	ifMatchOptional: {
+		name: "If-Match",
+		in: "header",
+		description: "When sent, the operation only happens if it matches the current `etag` ([AIP-135](https://google.aip.dev/135)); `*` matches any version",
+		schema: { type: "string" }
+	},
+	showDeleted: {
+		name: "show_deleted",
+		in: "query",
+		description: "Also return soft-deleted records ([AIP-164](https://google.aip.dev/164)); only on resources that soft delete",
+		schema: { type: "boolean" }
+	},
+	prefer: {
+		name: "Prefer",
+		in: "header",
+		description: "`return=minimal` or `return=representation` (default)",
+		schema: { type: "string" }
+	}
+};
+const searchBody = {
+	type: "object",
+	description: "The list parameters as JSON, for filters too long for a URL",
+	properties: {
+		filter: {
+			type: "string",
+			description: parameters.filter.description
+		},
+		order_by: { type: "string" },
+		page_size: { type: "integer" },
+		page_token: { type: "string" },
+		fields: {
+			type: "array",
+			items: { type: "string" }
+		},
+		count: {
+			type: "string",
+			enum: ["exact"]
+		},
+		show_deleted: {
+			type: "boolean",
+			description: "Soft-delete resources only"
+		}
+	}
+};
+const batchSchemas = {
+	BatchRef: {
+		type: "object",
+		description: "Points at a record created earlier in the batch by its `ref` name: in a key it stands for that record's key, in `data` for its key (or, with `field`, that field's value)",
+		required: ["$ref"],
+		additionalProperties: { type: "string" }
+	},
+	BatchKey: {
+		description: "A record key: its text as in a URL (`a,b` when composite), a number, a list of parts, or a `$ref`",
+		anyOf: [
+			{ type: "string" },
+			{ type: "number" },
+			{
+				type: "array",
+				items: { anyOf: [
+					{ type: "string" },
+					{ type: "number" },
+					{ $ref: "#/components/schemas/BatchRef" }
+				] }
+			},
+			{ $ref: "#/components/schemas/BatchRef" }
+		]
+	},
+	BatchRequest: {
+		type: "object",
+		required: ["ops"],
+		properties: { ops: {
+			type: "array",
+			minItems: 1,
+			maxItems: 500,
+			description: "Run in order inside one transaction through the normal write pipeline; all or nothing",
+			items: { oneOf: [
+				{
+					type: "object",
+					required: [
+						"op",
+						"resource",
+						"data"
+					],
+					properties: {
+						op: { const: "create" },
+						resource: { type: "string" },
+						data: {
+							type: "object",
+							additionalProperties: true
+						},
+						ref: {
+							type: "string",
+							description: "Names the created record for later `$ref`s"
+						}
+					},
+					additionalProperties: false
+				},
+				{
+					type: "object",
+					required: [
+						"op",
+						"resource",
+						"key",
+						"data"
+					],
+					properties: {
+						op: { const: "update" },
+						resource: { type: "string" },
+						key: { $ref: "#/components/schemas/BatchKey" },
+						etag: {
+							type: "string",
+							description: "Required, as `If-Match` on a single update; `*` matches any version"
+						},
+						data: {
+							type: "object",
+							additionalProperties: true
+						}
+					},
+					additionalProperties: false
+				},
+				{
+					type: "object",
+					required: [
+						"op",
+						"resource",
+						"key"
+					],
+					properties: {
+						op: { const: "delete" },
+						resource: { type: "string" },
+						key: { $ref: "#/components/schemas/BatchKey" },
+						etag: {
+							type: "string",
+							description: "Optional, as `If-Match` on a single delete"
+						}
+					},
+					additionalProperties: false
+				},
+				{
+					type: "object",
+					required: [
+						"op",
+						"resource",
+						"field",
+						"keys"
+					],
+					properties: {
+						op: { const: "reorder" },
+						resource: { type: "string" },
+						field: {
+							type: "string",
+							description: "An integer field the caller may write, for example `position`"
+						},
+						keys: {
+							type: "array",
+							minItems: 1,
+							items: { $ref: "#/components/schemas/BatchKey" },
+							description: "The records in their final order: `field` becomes 1, 2, 3, ..."
+						},
+						etags: {
+							type: "object",
+							additionalProperties: { type: "string" },
+							description: "ETag per key (the key as text) for every record whose value changes"
+						}
+					},
+					additionalProperties: false
+				}
+			] }
+		} }
+	},
+	BatchResponse: {
+		type: "object",
+		required: ["results"],
+		properties: { results: {
+			type: "array",
+			description: "One result per operation, in order: records come with their new `etag`",
+			items: {
+				type: "object",
+				required: ["op", "resource"],
+				properties: {
+					op: {
+						type: "string",
+						enum: [
+							"create",
+							"update",
+							"delete",
+							"reorder"
+						]
+					},
+					resource: { type: "string" },
+					ref: { type: "string" },
+					record: {
+						type: "object",
+						additionalProperties: true
+					},
+					etag: { type: "string" },
+					deleted: { type: "boolean" },
+					records: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								record: {
+									type: "object",
+									additionalProperties: true
+								},
+								etag: { type: "string" }
+							}
+						}
+					}
+				}
+			}
+		} }
+	}
+};
+//#endregion
+export { batchSchemas, errorResponses, parameters, problemSchema, searchBody };