@manablox/api-rpc 0.2.0 → 0.3.0

package/dist/index.js

@@ -0,0 +1,994 @@
+import { z } from "zod";
+import { MIN_PASSWORD_LENGTH, actorRoles, allowedTypeIds, assertCan, effectiveGrants, normaliseGrants } from "@manablox/auth";
+import { ManabloxError, TRANSPORT_CODE, WORKFLOW_CONDITION_OPERATORS, WORKFLOW_EVENTS } from "@manablox/core";
+import { ORPCError, os } from "@orpc/server";
+import { renderContentTypeConfig } from "@manablox/services";
+//#region src/base.ts
+/**
+* Base procedure builder. Every management procedure runs through it, so the
+* `ManabloxError` → transport mapping lives in exactly one place.
+*/
+const base = os.$context().use(async ({ next }) => {
+	try {
+		return await next();
+	} catch (error) {
+		throw toOrpcError(error);
+	}
+});
+function toOrpcError(error) {
+	if (!ManabloxError.is(error)) return error;
+	return new ORPCError(TRANSPORT_CODE[error.kind], {
+		message: error.key,
+		data: {
+			key: error.key,
+			details: error.details
+		}
+	});
+}
+/** Requires an authenticated principal. */
+const authed = base.use(async ({ context, next }) => {
+	if (!context.principal) throw toOrpcError(ManabloxError.unauthorized());
+	return next({ context: {
+		...context,
+		principal: context.principal
+	} });
+});
+/**
+* Requires a permission in the space named by the input's `spaceId`.
+*
+* Authorisation is a middleware rather than a call at the top of each handler, so a new
+* procedure cannot forget it — the input type makes `spaceId` mandatory.
+*/
+function scoped(permission) {
+	return authed.use(async ({ context, next }, input) => {
+		const raw = input;
+		const spaceId = raw?.spaceId ?? raw?.filter?.spaceId ?? null;
+		assertCan(context.principal, spaceId, permission);
+		return next();
+	});
+}
+/** Requires an instance-wide superadmin, for operations that are not space-scoped. */
+const superadmin = authed.use(async ({ context, next }) => {
+	if (context.principal?.role !== "superadmin" || context.principal.allowedSpaceIds) throw toOrpcError(ManabloxError.forbidden("auth.superadminRequired"));
+	return next();
+});
+//#endregion
+//#region src/schemas.ts
+/** Input primitives shared by every management router. */
+const uuid = z.string().uuid();
+/** BCP-47-ish, the way the rest of the system stores it: `en`, `de-AT`. */
+const locale = z.string().min(2).max(10);
+const localeList = z.array(locale).min(1);
+/**
+* A technical name: lower-case, starts with a letter, may carry digits, `_` and `-`. It
+* keys the GraphQL schema and the public API's space pinning, so it is stricter than a
+* label.
+*/
+const machineName = z.string().regex(/^[a-z][a-z0-9_-]*$/).max(64);
+/** A role's machine name: one of the built-in five, or a role created for the space. */
+const spaceRole = machineName;
+const searchTerm = z.string().max(200);
+/** `image/png`, or a family with a trailing slash: `image/`. */
+const mimeTypePattern = z.string().regex(/^[a-z0-9-]+\/([a-z0-9.+-]+)?$/).max(100);
+/** `limit`/`offset` with the caller's defaults and ceiling. */
+function pagination(options) {
+	return z.object({
+		limit: z.number().int().min(1).max(options.max).default(options.limit),
+		offset: z.number().int().min(0).default(0)
+	});
+}
+z.object({ spaceId: uuid });
+//#endregion
+//#region src/routers/asset.ts
+const crop = z.object({
+	left: z.number().int().min(0),
+	top: z.number().int().min(0),
+	width: z.number().int().min(1),
+	height: z.number().int().min(1)
+});
+const focalPoint = z.object({
+	x: z.number().min(0).max(1),
+	y: z.number().min(0).max(1)
+});
+const assetRouter = {
+	/** What an upload into this space is held to, and the instance's ceiling above it. */
+	limits: scoped("asset:read").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.media.limits(input.spaceId)),
+	list: scoped("asset:read").input(pagination({
+		limit: 40,
+		max: 100
+	}).extend({
+		spaceId: uuid,
+		mimeType: z.string().optional(),
+		search: searchTerm.optional()
+	})).handler(async ({ input, context }) => {
+		const page = await context.repos.assets.list({
+			spaceId: input.spaceId,
+			...input.mimeType ? { mimeType: input.mimeType } : {},
+			...input.search ? { search: input.search } : {}
+		}, {
+			limit: input.limit,
+			offset: input.offset
+		});
+		return {
+			...page,
+			items: page.items.map((asset) => context.media.present(asset))
+		};
+	}),
+	/** Several assets in one round trip, for a field that references them; missing ids are absent. */
+	getMany: scoped("asset:read").input(z.object({
+		spaceId: uuid,
+		ids: z.array(uuid).max(200)
+	})).handler(async ({ input, context }) => {
+		return (await context.repos.assets.findManyByIds(input.ids, input.spaceId)).map((asset) => context.media.present(asset));
+	}),
+	get: scoped("asset:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		const asset = await context.repos.assets.findById(input.id);
+		return asset ? context.media.present(asset) : null;
+	}),
+	update: scoped("asset:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		name: z.string().max(200).optional(),
+		alt: z.string().max(500).nullable().optional(),
+		title: z.string().max(500).nullable().optional()
+	})).handler(async ({ input, context }) => {
+		const { spaceId: _spaceId, id, ...data } = input;
+		return context.repos.assets.update(id, data);
+	}),
+	/**
+	* An image's crop and focal point. `null` clears one; omitting it also clears it, so
+	* the call always states the whole edit. Every variant re-renders through the result.
+	*/
+	setImageEdits: scoped("asset:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		crop: crop.nullable().optional(),
+		focalPoint: focalPoint.nullable().optional()
+	})).handler(async ({ input, context }) => {
+		const asset = await context.media.setImageEdits(input.id, {
+			crop: input.crop ?? null,
+			focalPoint: input.focalPoint ?? null
+		});
+		return context.media.present(asset);
+	}),
+	delete: scoped("asset:delete").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await context.media.delete(input.id);
+		return { ok: true };
+	})
+};
+//#endregion
+//#region src/routers/content.ts
+const filterSchema = z.object({
+	spaceId: uuid,
+	/** Specific documents, for a relation field's chips: one request instead of one per id. */
+	ids: z.array(uuid).max(200).optional(),
+	typeIds: z.array(uuid).optional(),
+	locale: locale.optional(),
+	status: z.enum([
+		"draft",
+		"published",
+		"archived"
+	]).optional(),
+	parentId: uuid.nullable().optional(),
+	under: uuid.optional(),
+	search: searchTerm.optional(),
+	fields: z.array(z.object({
+		name: z.string(),
+		op: z.enum([
+			"eq",
+			"neq",
+			"lt",
+			"lte",
+			"gt",
+			"gte",
+			"in",
+			"notIn",
+			"contains",
+			"startsWith",
+			"endsWith",
+			"isNull",
+			"isNotNull"
+		]),
+		value: z.unknown().optional()
+	})).max(10).optional()
+});
+const paginationSchema = pagination({
+	limit: 25,
+	max: 200
+});
+const sortSchema = z.array(z.object({
+	by: z.enum([
+		"position",
+		"title",
+		"createdAt",
+		"updatedAt",
+		"publishedAt",
+		"slug"
+	]),
+	direction: z.enum(["asc", "desc"]).default("asc")
+})).max(3);
+const saveSchema = z.object({
+	spaceId: uuid,
+	typeId: uuid,
+	locale: locale.default("en"),
+	localizationId: uuid.optional(),
+	parentId: uuid.nullable().optional(),
+	title: z.string().min(1).max(500),
+	slug: z.string().max(200).optional(),
+	fields: z.record(z.string(), z.unknown()).default({}),
+	position: z.number().int().optional(),
+	expectedVersion: z.number().int().positive().optional()
+});
+const contentRouter = {
+	list: scoped("content:read").input(z.object({
+		filter: filterSchema,
+		pagination: paginationSchema.optional(),
+		sort: sortSchema.optional()
+	}).transform((v) => ({
+		...v,
+		spaceId: v.filter.spaceId
+	}))).handler(async ({ input, context }) => {
+		const filter = narrowToAllowed(context, input.filter);
+		if (!filter) return {
+			items: [],
+			total: 0,
+			...input.pagination ?? {
+				limit: 25,
+				offset: 0
+			}
+		};
+		return context.content.list(filter, input.pagination ?? {
+			limit: 25,
+			offset: 0
+		}, input.sort ?? [], { actor: toActor(context, input.filter.spaceId) });
+	}),
+	tree: scoped("content:read").input(z.object({
+		spaceId: uuid,
+		locale: locale.default("en"),
+		rootId: uuid.nullable().default(null)
+	})).handler(async ({ input, context }) => context.content.tree(input.spaceId, input.locale, input.rootId)),
+	get: scoped("content:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await assertOnDocument(context, input.spaceId, "content:read", input.id);
+		return context.content.get(input.id, { actor: toActor(context, input.spaceId) });
+	}),
+	/** Field values with defaults filled in — what the editor opens a new document with. */
+	blank: scoped("content:read").input(z.object({
+		spaceId: uuid,
+		typeId: uuid
+	})).handler(async ({ input, context }) => {
+		assertOnType(context, input.spaceId, "content:read", input.typeId);
+		return { fields: await context.content.initFields(context.manablox.contentTypes.get(input.typeId)) };
+	}),
+	create: scoped("content:write").input(saveSchema).handler(async ({ input, context }) => {
+		assertOnType(context, input.spaceId, "content:write", input.typeId);
+		return context.content.create(input, toActor(context, input.spaceId));
+	}),
+	update: scoped("content:write").input(saveSchema.extend({ id: uuid })).handler(async ({ input, context }) => {
+		assertOnType(context, input.spaceId, "content:write", input.typeId);
+		return context.content.update(input.id, input, toActor(context, input.spaceId));
+	}),
+	delete: scoped("content:delete").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await assertOnDocument(context, input.spaceId, "content:delete", input.id);
+		return { deleted: await context.content.delete(input.id, toActor(context, input.spaceId)) };
+	}),
+	publish: scoped("content:publish").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await assertOnDocument(context, input.spaceId, "content:publish", input.id);
+		return context.content.publish(input.id, toActor(context, input.spaceId));
+	}),
+	unpublish: scoped("content:publish").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await assertOnDocument(context, input.spaceId, "content:publish", input.id);
+		await context.content.unpublish(input.id, toActor(context, input.spaceId));
+		return { ok: true };
+	}),
+	/** Reparent or reorder a document in the tree — a drag in the admin's tree panel. */
+	move: scoped("content:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		parentId: uuid.nullable(),
+		position: z.number().int().min(0)
+	})).handler(async ({ input, context }) => {
+		await assertOnDocument(context, input.spaceId, "content:write", input.id);
+		return context.content.move(input.spaceId, input.id, input.parentId, input.position);
+	}),
+	/** Every locale a document exists in, for the editor's language switcher. */
+	translations: scoped("content:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => context.content.translations(input.spaceId, input.id)),
+	/** Starts a translation of an existing document, in the localization group it shares. */
+	createTranslation: scoped("content:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		locale
+	})).handler(async ({ input, context }) => {
+		await assertOnDocument(context, input.spaceId, "content:write", input.id);
+		return context.content.createTranslation(input.spaceId, input.id, input.locale, toActor(context, input.spaceId));
+	}),
+	versions: scoped("content:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => context.repos.content.versions(input.id)),
+	versionSnapshot: scoped("content:read").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		version: z.number().int().positive()
+	})).handler(async ({ input, context }) => context.repos.content.versionSnapshot(input.id, input.version)),
+	restore: scoped("content:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		version: z.number().int().positive()
+	})).handler(async ({ input, context }) => {
+		await assertOnDocument(context, input.spaceId, "content:write", input.id);
+		return context.content.restore(input.id, input.version, toActor(context, input.spaceId));
+	})
+};
+function assertOnType(context, spaceId, permission, typeId) {
+	try {
+		assertCan(context.principal, spaceId, permission, typeId);
+	} catch (error) {
+		throw toOrpcError(error);
+	}
+}
+async function assertOnDocument(context, spaceId, permission, id) {
+	if (allowedTypeIds(context.principal, spaceId, permission) === null) return;
+	const row = await context.repos.content.findById(id);
+	if (!row || row.spaceId !== spaceId) throw toOrpcError(ManabloxError.notFound("content.notFound", { id }));
+	assertOnType(context, spaceId, permission, row.typeId);
+}
+/** The filter narrowed to the types the caller may read; `null` when that leaves none. */
+function narrowToAllowed(context, filter) {
+	const allowed = allowedTypeIds(context.principal, filter.spaceId, "content:read");
+	if (allowed === null) return filter;
+	const typeIds = filter.typeIds?.length ? filter.typeIds.filter((typeId) => allowed.includes(typeId)) : allowed;
+	return typeIds.length ? {
+		...filter,
+		typeIds
+	} : null;
+}
+function toActor(context, spaceId) {
+	const principal = context.principal;
+	if (!principal) return null;
+	return {
+		userId: principal.userId,
+		roles: actorRoles(principal, spaceId)
+	};
+}
+//#endregion
+//#region src/routers/content-type.ts
+const fieldSchema = z.object({
+	id: z.string().optional(),
+	name: z.string().min(1).max(64),
+	label: z.string().optional(),
+	type: z.string(),
+	settings: z.record(z.string(), z.unknown()).default({}),
+	required: z.boolean().default(false),
+	localized: z.boolean().default(false),
+	unique: z.boolean().default(false),
+	readRoles: z.array(z.string()).optional(),
+	writeRoles: z.array(z.string()).optional(),
+	admin: z.object({
+		zone: z.enum(["main", "sidebar"]).default("main"),
+		width: z.number().int().min(25).max(100).default(100),
+		position: z.number().int().default(0),
+		help: z.string().optional(),
+		placeholder: z.string().optional()
+	}).optional()
+});
+const contentTypeSchema = z.object({
+	name: z.string().min(1).max(64),
+	label: z.string().optional(),
+	description: z.string().optional(),
+	icon: z.string().optional(),
+	kind: z.enum(["content", "block"]).default("content"),
+	spaceId: uuid.nullable().default(null),
+	hasSlug: z.boolean().optional(),
+	isPublishable: z.boolean().optional(),
+	isVisibleInTree: z.boolean().optional(),
+	canBeVisibleInMenu: z.boolean().optional(),
+	fields: z.array(fieldSchema).default([])
+});
+const contentTypeRouter = {
+	list: scoped("contentType:read").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.contentTypes.list(input.spaceId)),
+	get: scoped("contentType:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => context.contentTypes.get(input.id)),
+	create: scoped("contentType:write").input(contentTypeSchema.extend({ spaceId: uuid })).handler(async ({ input, context }) => context.contentTypes.create(input, context.principal.userId)),
+	update: scoped("contentType:write").input(contentTypeSchema.extend({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => context.contentTypes.update(input.id, input)),
+	delete: scoped("contentType:delete").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await context.contentTypes.delete(input.id);
+		return { ok: true };
+	}),
+	/**
+	* The field-type catalogue the admin's "add field" menu is built from. Derived from
+	* the registry, so a plugin's field type appears in the menu with no admin change.
+	*/
+	fieldTypes: base.handler(async ({ context }) => context.manablox.fieldTypes.all.map((type) => ({
+		name: type.name,
+		label: type.label,
+		icon: type.icon ?? null,
+		description: type.description ?? null,
+		nested: type.nested ?? false,
+		filters: type.filters,
+		admin: type.admin
+	}))),
+	/** JSON Schema for one field type's settings, so the admin renders its form generically. */
+	fieldTypeSettingsSchema: base.input(z.object({ name: z.string() })).handler(async ({ input, context }) => {
+		const type = context.manablox.fieldTypes.get(input.name);
+		const schema = type.settingsSchema;
+		return {
+			name: type.name,
+			jsonSchema: typeof schema.toJSONSchema === "function" ? schema.toJSONSchema() : null
+		};
+	}),
+	/**
+	* The space's runtime types rendered as `manablox.config.ts` source, for moving a type
+	* built in the admin into code where it can be reviewed and versioned.
+	*/
+	config: scoped("contentType:read").input(z.object({
+		spaceId: uuid,
+		ids: z.array(uuid).optional()
+	})).handler(async ({ input, context }) => {
+		const wanted = input.ids?.length ? new Set(input.ids) : null;
+		const types = context.manablox.contentTypes.forSpace(input.spaceId).filter((type) => type.source !== "code" && (!wanted || wanted.has(type.id)));
+		return {
+			code: renderContentTypeConfig(types),
+			count: types.length
+		};
+	}),
+	reload: superadmin.handler(async ({ context }) => {
+		await context.manablox.reload(await context.repos.contentTypes.all());
+		return { schemaVersion: context.manablox.contentTypes.schemaVersion };
+	})
+};
+//#endregion
+//#region src/routers/menu.ts
+const menuSchema = z.object({
+	name: z.string().min(1).max(200),
+	machineName,
+	description: z.string().max(2e3).nullable().optional()
+});
+const menuItemSchema = z.lazy(() => z.object({
+	id: uuid.optional(),
+	localizationId: uuid.nullable().optional(),
+	label: z.string().max(200).nullable().optional(),
+	url: z.string().max(2e3).nullable().optional(),
+	children: z.array(menuItemSchema).max(500).optional()
+}));
+/**
+* Menus. Each rule — the unique machine name, what an entry may point at — lives in
+* `MenuService`; a procedure here is an input schema, a permission and one call.
+*/
+const menuRouter = {
+	list: scoped("menu:read").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.menus.list(input.spaceId)),
+	/** The menu with its entries, each content entry resolved to the document in `locale`. */
+	get: scoped("menu:read").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		locale
+	})).handler(async ({ input, context }) => context.menus.get(input.spaceId, input.id, input.locale)),
+	create: scoped("menu:write").input(menuSchema.extend({ spaceId: uuid })).handler(async ({ input, context }) => context.menus.create(input)),
+	update: scoped("menu:write").input(menuSchema.partial().extend({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		const { spaceId, id, ...data } = input;
+		return context.menus.update(spaceId, id, data);
+	}),
+	delete: scoped("menu:write").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await context.menus.delete(input.spaceId, input.id);
+		return { ok: true };
+	}),
+	/** Replaces the whole entry tree; the editor saves a menu as one document. */
+	setItems: scoped("menu:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		items: z.array(menuItemSchema).max(500)
+	})).handler(async ({ input, context }) => context.menus.setItems(input.spaceId, input.id, input.items)),
+	/** Menus a document is linked from, for the editor's hint. */
+	usedIn: scoped("menu:read").input(z.object({
+		spaceId: uuid,
+		localizationId: uuid
+	})).handler(async ({ input, context }) => context.menus.usedIn(input.spaceId, input.localizationId))
+};
+//#endregion
+//#region src/routers/role.ts
+const roleSchema = z.object({
+	spaceId: uuid,
+	name: z.string().trim().min(1).max(100),
+	machineName,
+	description: z.string().max(500).nullable().optional(),
+	/** `space:write`, `content:read` for every type, `content:read:<typeId>` for one. */
+	permissions: z.array(z.string().max(120)).max(500)
+});
+/**
+* The roles of a space. The rules — reserved names, grants that exist, a role nobody
+* holds before it goes — live in `RoleService`; a procedure here is an input schema, a
+* permission and one call.
+*/
+const roleRouter = {
+	/** The permission catalogue, grouped the way the role editor lays it out. */
+	catalog: authed.handler(async ({ context }) => context.roles.catalog()),
+	list: scoped("role:read").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.roles.list(input.spaceId)),
+	get: scoped("role:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => context.roles.get(input.spaceId, input.id)),
+	create: scoped("role:write").input(roleSchema).handler(async ({ input, context }) => {
+		const { spaceId, ...data } = input;
+		return context.roles.create(spaceId, data);
+	}),
+	update: scoped("role:write").input(roleSchema.extend({ id: uuid })).handler(async ({ input, context }) => {
+		const { spaceId, id, ...data } = input;
+		return context.roles.update(spaceId, id, data);
+	}),
+	delete: scoped("role:write").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await context.roles.delete(input.spaceId, input.id);
+		return { ok: true };
+	})
+};
+//#endregion
+//#region src/routers/space.ts
+const spaceSchema = z.object({
+	name: z.string().min(1).max(200),
+	machineName,
+	description: z.string().nullable().optional(),
+	url: z.string().url(),
+	defaultLocale: locale.default("en"),
+	locales: localeList.default(["en"]),
+	settings: z.record(z.string(), z.unknown()).optional()
+});
+/**
+* Spaces and membership. Every rule — the locale invariant, the last-owner guard, the
+* creator-owns-it grant — lives in `SpaceService`; a procedure here is an input schema,
+* a permission and one call.
+*/
+const spaceRouter = {
+	/**
+	* Only the spaces the caller is a member of — a superadmin sees all. A member's query
+	* is bounded by their memberships rather than by the instance, so a large multi-tenant
+	* install does not load every space to show someone their two.
+	*/
+	list: authed.handler(async ({ context }) => {
+		const { principal } = context;
+		const all = principal.role === "superadmin" ? await context.repos.spaces.all() : await context.repos.spaces.findManyByIds(Object.keys(principal.spaces));
+		const allowed = principal.allowedSpaceIds;
+		return allowed ? all.filter((space) => allowed.includes(space.id)) : all;
+	}),
+	get: scoped("space:read").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.repos.spaces.findById(input.spaceId)),
+	create: superadmin.input(spaceSchema).handler(async ({ input, context }) => context.spaces.create(input, context.principal?.userId ?? null)),
+	update: scoped("space:write").input(spaceSchema.partial().extend({ spaceId: uuid })).handler(async ({ input, context }) => {
+		const { spaceId, ...data } = input;
+		return context.spaces.update(spaceId, data);
+	}),
+	delete: scoped("space:delete").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => {
+		await context.spaces.delete(input.spaceId);
+		return { ok: true };
+	}),
+	/** Nominates one document as the space's root; `null` clears it. */
+	setHome: scoped("space:write").input(z.object({
+		spaceId: uuid,
+		contentId: uuid.nullable()
+	})).handler(async ({ input, context }) => context.spaces.setHome(input.spaceId, input.contentId)),
+	/**
+	* The space's upload limits, each narrowing the instance's. `allowedMimeTypes` absent
+	* means the instance's list; empty means the same thing rather than "nothing".
+	*/
+	setAssetSettings: scoped("space:write").input(z.object({
+		spaceId: uuid,
+		allowedMimeTypes: z.array(mimeTypePattern).max(50).optional(),
+		maxFileSize: z.number().int().positive().nullable().optional()
+	})).handler(async ({ input, context }) => context.spaces.setAssetSettings(input.spaceId, {
+		...input.allowedMimeTypes?.length ? { allowedMimeTypes: input.allowedMimeTypes } : {},
+		...input.maxFileSize ? { maxFileSize: input.maxFileSize } : {}
+	})),
+	/**
+	* The whole space as one JSON document. `space:write` rather than `space:read` because
+	* an export is every field of every document in one file, regardless of who may read
+	* what.
+	*/
+	export: scoped("space:write").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.spaces.export(input.spaceId)),
+	/** Restores such a document into an instance that does not hold the space yet. Superadmin, because it creates a space. */
+	import: superadmin.input(z.object({ payload: z.unknown() })).handler(async ({ input, context }) => context.spaces.import(input.payload, context.principal.userId)),
+	members: scoped("user:read").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.spaces.members(input.spaceId)),
+	grant: scoped("user:write").input(z.object({
+		spaceId: uuid,
+		userId: uuid,
+		role: spaceRole
+	})).handler(async ({ input, context }) => {
+		await context.spaces.grant(input.spaceId, input.userId, input.role);
+		return { ok: true };
+	}),
+	/** Users who are not yet members, for the add-member picker. */
+	candidates: scoped("user:write").input(z.object({
+		spaceId: uuid,
+		search: searchTerm.optional()
+	})).handler(async ({ input, context }) => context.spaces.candidates(input.spaceId, input.search)),
+	/** Grants the same role to several users at once, as the picker hands them over. */
+	addMembers: scoped("user:write").input(z.object({
+		spaceId: uuid,
+		userIds: z.array(uuid).min(1).max(100),
+		role: spaceRole.default("editor")
+	})).handler(async ({ input, context }) => ({
+		ok: true,
+		added: await context.spaces.addMembers(input.spaceId, input.userIds, input.role)
+	})),
+	revoke: scoped("user:write").input(z.object({
+		spaceId: uuid,
+		userId: uuid
+	})).handler(async ({ input, context }) => {
+		await context.spaces.revoke(input.spaceId, input.userId);
+		return { ok: true };
+	}),
+	/** Locales available for a space, for the editor's language switcher. */
+	locales: base.input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.spaces.locales(input.spaceId))
+};
+//#endregion
+//#region src/routers/user.ts
+const instanceRole = z.enum(["superadmin", "editor"]);
+const password = z.string().min(MIN_PASSWORD_LENGTH).max(200);
+const email = z.string().email().max(320);
+const displayName = z.string().trim().min(1).max(200);
+/**
+* The caller's own account and keys, and — for a superadmin — every account on the
+* instance. The rules (no locking yourself out, one superadmin always remains) live in
+* `UserService`; a procedure here is an input schema, a permission and one call.
+*/
+const userRouter = {
+	me: authed.handler(async ({ context }) => {
+		const user = await context.repos.users.findById(context.principal.userId);
+		return user ? {
+			id: user.id,
+			email: user.email,
+			name: user.name,
+			image: user.image,
+			role: user.role,
+			spaces: context.principal.spaces,
+			permissions: Object.fromEntries(Object.keys(context.principal.spaces).map((spaceId) => [spaceId, effectiveGrants(context.principal, spaceId)]))
+		} : null;
+	}),
+	/**
+	* Whether the instance still has no account at all. Public, because the login page
+	* needs it before anyone is signed in: it decides whether to offer "create the first
+	* account". Once one exists, sign-up is closed and every account is created here.
+	*/
+	setupNeeded: base.handler(async ({ context }) => ({ setupNeeded: await context.repos.users.count() === 0 })),
+	list: superadmin.input(pagination({
+		limit: 25,
+		max: 100
+	}).extend({ search: searchTerm.optional() })).handler(async ({ input, context }) => context.users.list({
+		limit: input.limit,
+		offset: input.offset
+	}, input.search)),
+	get: superadmin.input(z.object({ userId: uuid })).handler(async ({ input, context }) => context.users.get(input.userId)),
+	create: superadmin.input(z.object({
+		name: displayName,
+		email,
+		password,
+		role: instanceRole.default("editor")
+	})).handler(async ({ input, context }) => context.users.create(input)),
+	update: superadmin.input(z.object({
+		userId: uuid,
+		name: displayName.optional(),
+		email: email.optional()
+	})).handler(async ({ input, context }) => {
+		const { userId, ...data } = input;
+		return context.users.update(userId, data);
+	}),
+	setRole: superadmin.input(z.object({
+		userId: uuid,
+		role: instanceRole
+	})).handler(async ({ input, context }) => context.users.setRole(input.userId, input.role)),
+	/** Resets a password and signs the account out everywhere. */
+	setPassword: superadmin.input(z.object({
+		userId: uuid,
+		password
+	})).handler(async ({ input, context }) => {
+		await context.users.setPassword(input.userId, input.password);
+		return { ok: true };
+	}),
+	ban: superadmin.input(z.object({
+		userId: uuid,
+		reason: z.string().trim().max(500).optional()
+	})).handler(async ({ input, context }) => context.users.ban(context.principal.userId, input.userId, input.reason || null)),
+	unban: superadmin.input(z.object({ userId: uuid })).handler(async ({ input, context }) => context.users.unban(input.userId)),
+	revokeSessions: superadmin.input(z.object({ userId: uuid })).handler(async ({ input, context }) => {
+		await context.users.revokeSessions(input.userId);
+		return { ok: true };
+	}),
+	delete: superadmin.input(z.object({ userId: uuid })).handler(async ({ input, context }) => {
+		await context.users.delete(context.principal.userId, input.userId);
+		return { ok: true };
+	}),
+	apiKeys: authed.handler(async ({ context }) => context.apiKeys.list(context.principal.userId)),
+	issueApiKey: authed.input(z.object({
+		name: z.string().min(1).max(100),
+		expiresAt: z.coerce.date().optional(),
+		/** Empty or omitted issues an unrestricted key. */
+		spaceIds: z.array(uuid).optional(),
+		/**
+		* Grants the key is confined to, in the roles' vocabulary; omitted leaves the
+		* owner's role as the limit. At use the two are intersected, so a grant here
+		* never widens the key beyond its owner.
+		*/
+		permissions: z.array(z.string().max(120)).max(500).optional()
+	})).handler(async ({ input, context }) => {
+		for (const spaceId of input.spaceIds ?? []) assertCan(context.principal, spaceId, "space:read");
+		const reachable = input.spaceIds?.length ? input.spaceIds : context.principal.role === "superadmin" ? null : Object.keys(context.principal.spaces);
+		const typeIds = new Set((reachable ? reachable.flatMap((spaceId) => context.manablox.contentTypes.forSpace(spaceId)) : context.manablox.contentTypes.all).map((type) => type.id));
+		let permissions = null;
+		if (input.permissions) {
+			const checked = normaliseGrants(input.permissions, typeIds);
+			if (checked.unknown.length) throw ManabloxError.validation(checked.unknown.map(({ index, grant }) => ({
+				key: "role.permission.unknown",
+				path: ["permissions", index],
+				params: { permission: grant }
+			})), "apiKey.validation.failed");
+			permissions = checked.permissions;
+		}
+		return context.apiKeys.issue(context.principal.userId, input.name, {
+			expiresAt: input.expiresAt,
+			spaceIds: input.spaceIds,
+			permissions
+		});
+	}),
+	revokeApiKey: authed.input(z.object({ id: uuid })).handler(async ({ input, context }) => {
+		if (!(await context.apiKeys.list(context.principal.userId)).some((key) => key.id === input.id)) return { ok: false };
+		await context.apiKeys.revoke(input.id);
+		return { ok: true };
+	})
+};
+//#endregion
+//#region src/routers/workflow.ts
+const template = z.string().max(2e4);
+const eventTrigger = z.object({
+	kind: z.literal("event"),
+	events: z.array(z.enum(WORKFLOW_EVENTS)).max(10),
+	typeIds: z.array(z.string().max(120)).max(200).default([]),
+	locales: z.array(z.string().max(10)).max(50).default([])
+});
+const selection = z.object({
+	typeIds: z.array(z.string().max(120)).max(200).default([]),
+	status: z.enum([
+		"any",
+		"draft",
+		"published"
+	]).default("any"),
+	changedWithinHours: z.number().int().min(1).max(8760).nullable().default(null),
+	locale: z.string().max(10).nullable().default(null)
+});
+const scheduleTrigger = z.object({
+	kind: z.literal("schedule"),
+	cron: z.string().max(100),
+	timezone: z.string().max(60).default("UTC"),
+	selection: selection.nullable().default(null),
+	perDocument: z.boolean().default(false)
+});
+const stepBase = {
+	id: z.string().max(64).default(""),
+	name: z.string().max(200).default(""),
+	enabled: z.boolean().default(true),
+	continueOnError: z.boolean().default(false)
+};
+const emailStep = z.object({
+	...stepBase,
+	type: z.literal("email"),
+	to: z.array(z.string().max(500)).max(50).default([]),
+	toRoles: z.array(z.string().max(64)).max(50).default([]),
+	subject: template,
+	body: template,
+	html: z.boolean().default(false)
+});
+const httpStep = z.object({
+	...stepBase,
+	type: z.literal("http"),
+	method: z.enum([
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE"
+	]).default("POST"),
+	url: z.string().max(2e3),
+	headers: z.array(z.object({
+		name: z.string().max(200),
+		value: z.string().max(4e3)
+	})).max(50).default([]),
+	body: z.object({
+		mode: z.enum([
+			"event",
+			"custom",
+			"none"
+		]).default("event"),
+		template: template.default("")
+	}).default({
+		mode: "event",
+		template: ""
+	}),
+	secret: z.string().max(500).nullable().default(null),
+	timeoutMs: z.number().int().min(1e3).max(12e4).default(1e4)
+});
+const pushStep = z.object({
+	...stepBase,
+	type: z.literal("push"),
+	roles: z.array(z.string().max(64)).max(50).default([]),
+	userIds: z.array(uuid).max(200).default([]),
+	title: template,
+	body: template.default(""),
+	url: z.string().max(2e3).default("")
+});
+const rules = z.array(z.object({
+	field: z.string().max(300),
+	operator: z.enum(WORKFLOW_CONDITION_OPERATORS),
+	value: z.string().max(4e3).default("")
+})).max(50);
+const conditionStep = z.object({
+	...stepBase,
+	type: z.literal("condition"),
+	match: z.enum(["all", "any"]).default("all"),
+	rules
+});
+const delayStep = z.object({
+	...stepBase,
+	type: z.literal("delay"),
+	minutes: z.number().min(1).max(43200)
+});
+/** A fork carries two chains of its own, so the step schema refers to itself (Zod 4 getters). */
+const branchStep = z.object({
+	...stepBase,
+	type: z.literal("branch"),
+	match: z.enum(["all", "any"]).default("all"),
+	rules,
+	get then() {
+		return z.array(step).max(50).default([]);
+	},
+	get else() {
+		return z.array(step).max(50).default([]);
+	}
+});
+const step = z.discriminatedUnion("type", [
+	emailStep,
+	httpStep,
+	pushStep,
+	conditionStep,
+	branchStep,
+	delayStep
+]);
+const workflowSchema = z.object({
+	spaceId: uuid,
+	name: z.string().max(200),
+	description: z.string().max(2e3).nullable().optional(),
+	enabled: z.boolean().optional(),
+	trigger: z.discriminatedUnion("kind", [eventTrigger, scheduleTrigger]),
+	steps: z.array(step).max(50)
+});
+const pushSubscription = z.object({
+	endpoint: z.string().max(4e3),
+	keys: z.object({
+		p256dh: z.string().max(500),
+		auth: z.string().max(500)
+	})
+});
+/**
+* Workflows. The rules — a cron that parses, a step with somewhere to go — live in
+* `WorkflowService`; a procedure here is an input schema, a permission and one call.
+*/
+const workflowRouter = {
+	/** The events, step types and operators the editor offers, and what the instance can send. */
+	catalog: authed.handler(async ({ context }) => context.workflows.catalog()),
+	list: scoped("workflow:read").input(z.object({ spaceId: uuid })).handler(async ({ input, context }) => context.workflows.list(input.spaceId)),
+	get: scoped("workflow:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => context.workflows.get(input.spaceId, input.id)),
+	create: scoped("workflow:write").input(workflowSchema).handler(async ({ input, context }) => {
+		const { spaceId, ...data } = input;
+		return context.workflows.create(spaceId, data);
+	}),
+	update: scoped("workflow:write").input(workflowSchema.extend({ id: uuid })).handler(async ({ input, context }) => {
+		const { spaceId, id, ...data } = input;
+		return context.workflows.update(spaceId, id, data);
+	}),
+	setEnabled: scoped("workflow:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		enabled: z.boolean()
+	})).handler(async ({ input, context }) => context.workflows.setEnabled(input.spaceId, input.id, input.enabled)),
+	delete: scoped("workflow:write").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => {
+		await context.workflows.delete(input.spaceId, input.id);
+		return { ok: true };
+	}),
+	/** The latest runs of a workflow, newest first, each with its step log. */
+	runs: scoped("workflow:read").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		limit: z.number().int().min(1).max(200).default(50)
+	})).handler(async ({ input, context }) => context.workflows.runs(input.spaceId, input.id, input.limit)),
+	run: scoped("workflow:read").input(z.object({
+		spaceId: uuid,
+		id: uuid
+	})).handler(async ({ input, context }) => context.workflows.run(input.spaceId, input.id)),
+	/** Runs the workflow now, against a document when one is named, and returns the run. */
+	runNow: scoped("workflow:write").input(z.object({
+		spaceId: uuid,
+		id: uuid,
+		contentId: uuid.nullable().optional()
+	})).handler(async ({ input, context }) => context.workflows.runNow(input.spaceId, input.id, input.contentId ?? null)),
+	pushSubscriptions: authed.handler(async ({ context }) => context.workflows.subscriptions(context.principal.userId)),
+	pushSubscribe: authed.input(pushSubscription).handler(async ({ input, context }) => context.workflows.subscribe(context.principal.userId, input, context.headers.get("user-agent"))),
+	pushUnsubscribe: authed.input(z.object({ endpoint: z.string().max(4e3) })).handler(async ({ input, context }) => {
+		await context.workflows.unsubscribe(context.principal.userId, input.endpoint);
+		return { ok: true };
+	})
+};
+//#endregion
+//#region src/context.ts
+/** The runtime's RPC-facing slice, without whatever else the host keeps on it. */
+function pickRpcRuntime(runtime) {
+	const { manablox, repos, auth, apiKeys, media, content, contentTypes, spaces, users, menus, roles, workflows } = runtime;
+	return {
+		manablox,
+		repos,
+		auth,
+		apiKeys,
+		media,
+		content,
+		contentTypes,
+		spaces,
+		users,
+		menus,
+		roles,
+		workflows
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* The management API. The admin imports the *type* of this object and gets end-to-end
+* safety with no codegen step.
+*/
+const router = {
+	content: contentRouter,
+	contentTypes: contentTypeRouter,
+	spaces: spaceRouter,
+	assets: assetRouter,
+	users: userRouter,
+	menus: menuRouter,
+	roles: roleRouter,
+	workflows: workflowRouter
+};
+//#endregion
+export { authed, base, pickRpcRuntime, router, scoped, superadmin, toOrpcError };