@crombolo/api-management 0.11.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/api-management",
-  "version": "0.11.0",
+  "version": "0.13.1",
   "description": "Umbraco-compatible Management API handlers for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.11.0",
-    "@crombolo/contracts": "0.11.0"
+    "@crombolo/core": "0.13.1",
+    "@crombolo/contracts": "0.13.1"
   }
 }

package/src/divergences.ts

@@ -0,0 +1,22 @@
+/**
+ * Operations that answer 501 on purpose, with the reason; `coverage:api` lists
+ * them apart from what is still to build. docs/roadmap.md, "Deliberate divergence".
+ */
+const INSTALL =
+  'There is no browser install wizard: `crombolo init` and schema-as-code stand a site up.'
+const UPGRADE =
+  'Upgrades run from the command line with `crombolo upgrade`, not from the backoffice.'
+
+export const DELIBERATE_DIVERGENCES: Readonly<Record<string, string>> = {
+  GetInstallSettings: INSTALL,
+  PostInstallSetup: INSTALL,
+  PostInstallValidateDatabase: INSTALL,
+  GetUpgradeSettings: UPGRADE,
+  PostUpgradeAuthorize: UPGRADE,
+}
+
+/** Areas still to build, by the story that builds them. */
+export const PLANNED_AREAS: Readonly<Record<string, string>> = {}
+
+/** Operations outside those areas that a story builds. */
+export const PLANNED_OPERATIONS: Readonly<Record<string, string>> = {}

package/src/handlers/data-type.ts

@@ -205,6 +205,31 @@ export function registerDataTypeHandlers(router: ManagementApiRouter, port: Data
     return Response.json({ total: result.total, items: result.items.map(toItem) })
   })
 
+  const isUsed = port.isUsed
+  if (isUsed)
+    router.handle('GetDataTypeByIdIsUsed', async (ctx) => {
+      const used = await isUsed(ctx.params.id as string)
+      if (used === undefined)
+        return problemResponse(notFound('Data type not found', 'The data type could not be found.'))
+      return Response.json(used)
+    })
+  const propertyIsUsed = port.propertyIsUsed
+  if (propertyIsUsed)
+    router.handle('GetPropertyTypeIsUsed', async (ctx) => {
+      const contentTypeId = ctx.url.searchParams.get('contentTypeId')
+      const alias = ctx.url.searchParams.get('propertyAlias')
+      const used = contentTypeId && alias ? await propertyIsUsed(contentTypeId, alias) : undefined
+      if (used === undefined)
+        return problemResponse(
+          problemDetails({
+            title: 'Property type not found',
+            detail: 'There is no property with that alias on that content type.',
+            status: 400,
+          }),
+        )
+      return Response.json(used)
+    })
+
   router.handle('GetDataTypeByIdReferencedBy', async (ctx) => {
     const page = paging(ctx)
     if (!page) return problemResponse(invalidSkipTake())

package/src/handlers/diagnostics.ts

@@ -0,0 +1,89 @@
+/**
+ * Health checks, telemetry, profiling and the server's troubleshooting and
+ * upgrade-check answers. Telemetry and profiling are fixed: nothing is
+ * collected or sent, and there is no profiler. docs/diagnostics.md.
+ */
+import { invalidSkipTake, notFound, problemDetails, problemResponse } from '@crombolo/core'
+import type { DiagnosticsPort } from '../ports-diagnostics.ts'
+import type { ManagementApiRouter } from '../router.ts'
+import { paging } from './content-type.ts'
+import { readBody } from './document.ts'
+
+const TELEMETRY_LEVEL = 'Minimal'
+
+const badRequest = (title: string, detail: string) => problemDetails({ title, detail, status: 400 })
+
+export function registerTelemetryAndProfilingHandlers(router: ManagementApiRouter): void {
+  router.handle('GetTelemetry', (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    const items = [{ telemetryLevel: TELEMETRY_LEVEL }]
+    return Response.json({
+      total: items.length,
+      items: items.slice(page.skip, page.skip + page.take),
+    })
+  })
+  router.handle('GetTelemetryLevel', () => Response.json({ telemetryLevel: TELEMETRY_LEVEL }))
+  router.handle('PostTelemetryLevel', async (ctx) => {
+    const { telemetryLevel } = await readBody(ctx)
+    if (telemetryLevel === TELEMETRY_LEVEL) return new Response(null, { status: 200 })
+    return problemResponse(
+      badRequest(
+        'Telemetry cannot be raised',
+        'This site collects no telemetry and sends nothing anywhere, so the level stays at Minimal.',
+      ),
+    )
+  })
+  router.handle('GetProfilingStatus', () => Response.json({ enabled: false }))
+  router.handle('PutProfilingStatus', async (ctx) => {
+    const { enabled } = await readBody(ctx)
+    if (enabled === false) return new Response(null, { status: 200 })
+    return problemResponse(
+      badRequest('Profiling is not available', 'This site has no profiler to switch on.'),
+    )
+  })
+}
+
+export function registerDiagnosticsHandlers(
+  router: ManagementApiRouter,
+  diagnostics: DiagnosticsPort,
+): void {
+  const groupNamed = (name: string) =>
+    diagnostics.groups().find((group) => group.name.toLowerCase() === name.toLowerCase())
+  const noGroup = () => problemResponse(notFound('The health check group could not be found'))
+
+  router.handle('GetHealthCheckGroup', (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    const groups = diagnostics.groups()
+    return Response.json({
+      total: groups.length,
+      items: groups.slice(page.skip, page.skip + page.take).map(({ name }) => ({ name })),
+    })
+  })
+  router.handle('GetHealthCheckGroupByName', (ctx) => {
+    const group = groupNamed(String(ctx.params.name))
+    return group ? Response.json(group) : noGroup()
+  })
+  router.handle('PostHealthCheckGroupByNameCheck', async (ctx) => {
+    const group = groupNamed(String(ctx.params.name))
+    const checks = group && (await diagnostics.run(group.name))
+    return checks ? Response.json({ checks }) : noGroup()
+  })
+  // No check here offers an action: each one reports, and the fix is a change
+  // to the site's configuration rather than something a button can do.
+  router.handle('PostHealthCheckExecuteAction', () =>
+    problemResponse(
+      badRequest(
+        'There is nothing to run',
+        'These health checks report only; none offers an action.',
+      ),
+    ),
+  )
+  router.handle('GetServerTroubleshooting', async () =>
+    Response.json(await diagnostics.troubleshooting()),
+  )
+  router.handle('GetServerUpgradeCheck', async () =>
+    Response.json(await diagnostics.upgradeCheck()),
+  )
+}

package/src/handlers/document.ts

@@ -7,8 +7,10 @@ import type {
   DocumentTreeItem,
   DocumentValidationError,
   DocumentValue,
+  PatchOperation,
 } from '@crombolo/core'
 import {
+  applyJsonPatch,
   DocumentPermissions,
   invalidSkipTake,
   notFound,
@@ -18,7 +20,7 @@ import {
   ROOT_ACCESS,
 } from '@crombolo/core'
 import type { PreviewPort } from '../ports.ts'
-import type { DocumentPort, PortFailure, SaveDocument } from '../ports-content.ts'
+import type { ApprovalGatePort, DocumentPort, PortFailure, SaveDocument } from '../ports-content.ts'
 import type { ManagementApiRouter, RequestContext } from '../router.ts'
 import { created, paging } from './content-type.ts'
 import {
@@ -275,7 +277,14 @@ export function registerDocumentHandlers(
   router: ManagementApiRouter,
   port: DocumentPort,
   preview?: PreviewPort,
+  approvals?: ApprovalGatePort,
 ): void {
+  /** A page a workflow covers goes through it: the gate's refusal, as a problem. */
+  const needsApproval = (title: string, detail: string) =>
+    problemResponse(
+      problemDetails({ title, status: 400, detail, operationStatus: 'NeedsApproval' }),
+    )
+  const principalOf = (ctx: RequestContext) => ctx.principal as NonNullable<typeof ctx.principal>
   const trees: TreeSource = {
     treeRoot: (paging) => port.treeRoot(paging),
     treeChildren: (key, paging) => port.treeChildren(key, paging),
@@ -328,6 +337,12 @@ export function registerDocumentHandlers(
     const body = await readBody(ctx)
     const key = typeof body.id === 'string' && body.id ? body.id : crypto.randomUUID()
     const input = toSaveDocument(key, body)
+    const refusal = await approvals?.newPageRefusal(
+      principalOf(ctx),
+      input.parentKey,
+      input.contentTypeKey,
+    )
+    if (refusal) return needsApproval('The document needs approval before it is published', refusal)
     const result = await port.createAndPublish(
       input,
       readCultures(body),
@@ -344,6 +359,10 @@ export function registerDocumentHandlers(
     const body = await readBody(ctx)
     const key = ctx.params.id as string
     const input = toSaveDocument(key, body)
+    const refusal =
+      (await approvals?.beforeSave(principalOf(ctx), key)) ??
+      (await approvals?.publishRefusal(principalOf(ctx), key, 'publish'))
+    if (refusal) return needsApproval('The document needs approval before it is published', refusal)
     const result = await port.updateAndPublish(
       key,
       input,
@@ -471,11 +490,14 @@ export function registerDocumentHandlers(
     return created(`${ctx.url.origin}/umbraco/management/api/v1/document/${result.key}`, result.key)
   })
 
-  router.handle('PutDocumentById', async (ctx) => {
-    const key = ctx.params.id as string
-    const existing = await port.byKey(key)
-    if (!existing) return problemResponse(notFound('The document could not be found'))
-    const body = await readBody(ctx)
+  const saveUpdate = async (
+    ctx: RequestContext,
+    key: string,
+    existing: DocumentAggregate,
+    body: Record<string, unknown>,
+  ) => {
+    const refusal = await approvals?.beforeSave(principalOf(ctx), key)
+    if (refusal) return needsApproval('The document is waiting for approval', refusal)
     const result = await port.update(
       key,
       {
@@ -494,8 +516,51 @@ export function registerDocumentHandlers(
         }),
       )
     }
+    await approvals?.afterSave(principalOf(ctx), key)
     ctx.notifications.push({ message: 'Document saved', category: 'Content', type: 'Success' })
     return new Response(null, { status: 200 })
+  }
+
+  router.handle('PutDocumentById', async (ctx) => {
+    const key = ctx.params.id as string
+    const existing = await port.byKey(key)
+    if (!existing) return problemResponse(notFound('The document could not be found'))
+    return saveUpdate(ctx, key, existing, await readBody(ctx))
+  })
+
+  // JSON Patch over the update model, Umbraco's filter segments included; the
+  // patched model then saves exactly as a PUT would.
+  router.handle('PatchDocumentByIdPatch', async (ctx) => {
+    const key = ctx.params.id as string
+    const existing = await port.byKey(key)
+    if (!existing) return problemResponse(notFound('The document could not be found'))
+    const invalid = (detail: string, status = 400) =>
+      problemResponse(problemDetails({ title: 'Could not patch the document', status, detail }))
+    const { operations } = await readBody(ctx)
+    if (!Array.isArray(operations) || operations.length === 0)
+      return invalid('A patch needs at least one operation.')
+    const current = {
+      template: existing.componentKey ? { id: existing.componentKey } : null,
+      values: existing.values.map(({ alias, culture, segment, value }) => ({
+        alias,
+        culture,
+        segment,
+        value,
+      })),
+      variants: existing.variants.map(({ culture, segment, name }) => ({ culture, segment, name })),
+    }
+    const patched = applyJsonPatch(current, operations as PatchOperation[])
+    if (!patched.ok) return invalid(patched.reason)
+    const body = patched.value as Record<string, unknown>
+    if (!Array.isArray(body.values) || !Array.isArray(body.variants))
+      return invalid('A patch may change values and variants, but not remove them.')
+    const aliases = new Set((await port.propertyAliases?.(key)) ?? [])
+    const unknown = (body.values as Array<{ alias?: unknown }>).find(
+      (value) => !aliases.has(String(value?.alias)),
+    )
+    if (unknown)
+      return invalid(`This document's type has no property "${String(unknown.alias)}".`, 422)
+    return saveUpdate(ctx, key, existing, body)
   })
 
   router.handle('PutDocumentByIdPublish', async (ctx) => {
@@ -503,6 +568,8 @@ export function registerDocumentHandlers(
     if (!(await port.byKey(key)))
       return problemResponse(notFound('The document could not be found'))
     const body = await readBody(ctx)
+    const refusal = await approvals?.publishRefusal(principalOf(ctx), key, 'publish')
+    if (refusal) return needsApproval('The document needs approval before it is published', refusal)
     const schedules = readSchedules(body)
     if (schedules === 'invalid')
       return problemResponse(
@@ -547,6 +614,8 @@ export function registerDocumentHandlers(
     const key = ctx.params.id as string
     if (!(await port.byKey(key)))
       return problemResponse(notFound('The document could not be found'))
+    const refusal = await approvals?.publishRefusal(principalOf(ctx), key, 'unpublish')
+    if (refusal) return needsApproval('Taking the document down needs approval', refusal)
     const result = await port.unpublish(key, readCultures(await readBody(ctx)))
     if (!result.ok) {
       return problemResponse(
@@ -665,6 +734,9 @@ export function registerDocumentHandlers(
   const branchTasks = new Map<string, { documentKey: string }>()
   router.handle('PutDocumentByIdPublishWithDescendants', async (ctx) => {
     const key = ctx.params.id as string
+    const refusal = await approvals?.branchRefusal(principalOf(ctx), key)
+    if (refusal)
+      return needsApproval('Part of this branch needs approval before it is published', refusal)
     const body = await readBody(ctx)
     const cultures = Array.isArray(body.cultures) ? (body.cultures as unknown[]).map(String) : []
     const result = await port.publishBranch(

package/src/handlers/dynamic-root.ts

@@ -0,0 +1,63 @@
+/**
+ * Dynamic roots: a content picker's start node, resolved from the document being
+ * edited by an origin and a list of steps.
+ */
+import { problemDetails, problemResponse } from '@crombolo/core'
+import type { DynamicRootPort } from '../ports.ts'
+import type { ManagementApiRouter } from '../router.ts'
+import { readBody } from './document.ts'
+
+export const DYNAMIC_ROOT_STEP_ALIASES = [
+  'NearestAncestorOrSelf',
+  'FurthestAncestorOrSelf',
+  'NearestDescendantOrSelf',
+  'FurthestDescendantOrSelf',
+]
+
+const EMPTY_GUID = '00000000-0000-0000-0000-000000000000'
+
+const keyOf = (value: unknown): string | null => {
+  const id = (value as { id?: unknown } | null | undefined)?.id ?? value
+  return typeof id === 'string' && id !== '' && id !== EMPTY_GUID ? id : null
+}
+
+export function registerDynamicRootHandlers(
+  router: ManagementApiRouter,
+  port: DynamicRootPort,
+): void {
+  router.handle('GetDynamicRootSteps', () => Response.json(DYNAMIC_ROOT_STEP_ALIASES))
+  router.handle('PostDynamicRootQuery', async (ctx) => {
+    const body = await readBody(ctx)
+    const context = body.context as { id?: unknown; parent?: unknown } | undefined
+    const query = body.query as
+      | { origin?: { alias?: unknown; id?: unknown }; steps?: unknown }
+      | undefined
+    if (!context || typeof query?.origin?.alias !== 'string')
+      return problemResponse(
+        problemDetails({
+          title: 'Invalid dynamic root query',
+          detail: 'A query needs a context and an origin.',
+          status: 400,
+        }),
+      )
+    const steps = Array.isArray(query.steps) ? query.steps : []
+    const roots = await port.resolve({
+      currentKey: keyOf(context.id),
+      parentKey: keyOf(context.parent),
+      origin: { alias: query.origin.alias, key: keyOf(query.origin.id) },
+      steps: steps.map((step) => {
+        const { alias, documentTypeIds } = (step ?? {}) as {
+          alias?: unknown
+          documentTypeIds?: unknown
+        }
+        return {
+          alias: String(alias ?? ''),
+          documentTypeKeys: Array.isArray(documentTypeIds)
+            ? documentTypeIds.filter((id): id is string => typeof id === 'string')
+            : [],
+        }
+      }),
+    })
+    return Response.json({ roots })
+  })
+}

package/src/handlers/reference-data.ts

@@ -0,0 +1,35 @@
+/**
+ * Fixed reference answers: the node object types a relation type can join, and
+ * the help pages. Umbraco relays its help pages from our.umbraco.com; there is
+ * nothing to relay here, so the list is honestly empty.
+ */
+import { invalidSkipTake, ObjectTypes, problemResponse } from '@crombolo/core'
+import type { ManagementApiRouter } from '../router.ts'
+import { paging } from './content-type.ts'
+
+/** Internal markers rather than things a relation can point at. */
+const HIDDEN = new Set<string>(['SystemRoot', 'LockObject'])
+
+/** `DocumentTypeContainer` → `Document Type Container`. */
+const spaced = (name: string) => name.replace(/([a-z])([A-Z])/g, '$1 $2')
+
+export const OBJECT_TYPES = Object.entries(ObjectTypes)
+  .filter(([name]) => !HIDDEN.has(name))
+  .map(([name, id]) => ({ id, name: spaced(name) }))
+  .sort((a, b) => a.name.localeCompare(b.name))
+
+export function registerReferenceDataHandlers(router: ManagementApiRouter): void {
+  router.handle('GetObjectTypes', (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    return Response.json({
+      total: OBJECT_TYPES.length,
+      items: OBJECT_TYPES.slice(page.skip, page.skip + page.take),
+    })
+  })
+  router.handle('GetHelp', (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    return Response.json({ total: 0, items: [] })
+  })
+}

package/src/handlers/relations.ts

@@ -0,0 +1,60 @@
+/**
+ * Relation types and their relations, read-only and derived (story 046), and
+ * the recycle bins' "what refers to what is in here" lists.
+ */
+import { invalidSkipTake, notFound, paged, parseSkipTake, problemResponse } from '@crombolo/core'
+import type { ReferencePort, RelationPort } from '../ports-content.ts'
+import type { ManagementApiRouter } from '../router.ts'
+
+const missing = () => problemResponse(notFound('The relation type could not be found'))
+
+export function registerRelationHandlers(router: ManagementApiRouter, port: RelationPort): void {
+  router.handle('GetRelationType', (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const types = port.types()
+    return Response.json(
+      paged(types.slice(page.value.skip, page.value.skip + page.value.take), types.length),
+    )
+  })
+
+  router.handle('GetRelationTypeById', (ctx) => {
+    const id = String(ctx.params.id).toLowerCase()
+    const type = port.types().find((t) => t.id === id)
+    return type ? Response.json(type) : missing()
+  })
+
+  router.handle('GetItemRelationType', (ctx) => {
+    const ids = new Set(ctx.url.searchParams.getAll('id').map((id) => id.toLowerCase()))
+    // Built in, so none of them can be deleted.
+    return Response.json(
+      port
+        .types()
+        .filter((t) => ids.has(t.id))
+        .map((t) => ({ id: t.id, name: t.name, isDeletable: false, flags: [] })),
+    )
+  })
+
+  router.handle('GetRelationByRelationTypeId', async (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const result = await port.relations(String(ctx.params.id), page.value)
+    return result ? Response.json(paged(result.items, result.total)) : missing()
+  })
+}
+
+export function registerRecycleBinReferenceHandlers(
+  router: ManagementApiRouter,
+  port: ReferencePort,
+): void {
+  const ask = port.recycleBinReferencedBy?.bind(port)
+  if (!ask) return
+  for (const area of ['Document', 'Media', 'Element'] as const)
+    router.handle(`GetRecycleBin${area}ReferencedBy`, async (ctx) => {
+      // Umbraco pages these 20 at a time, as it does every references list.
+      const page = parseSkipTake(ctx.url.searchParams, 20)
+      if (!page.ok) return problemResponse(invalidSkipTake())
+      const result = await ask(area, page.value)
+      return Response.json(paged(result.items, result.total))
+    })
+}

package/src/handlers/settings-stubs.ts

@@ -23,18 +23,9 @@ const PAGED = [
     `GetRecycleBin${b}Children`,
     `GetRecycleBin${b}ReferencedBy`,
   ]),
-  'GetRecycleBinDocumentReferencedBy', // needs relations, story 046
-  'GetRecycleBinMediaReferencedBy',
-  'GetRecycleBinElementReferencedBy',
-  // The recycle bin and the trash and delete dialogs; needs relations, story 046. Until
-  // then they cannot warn that other content links to what is being removed.
-  'GetTreeStaticFileRoot',
-  'GetTreeStaticFileChildren',
-  'GetRelationType',
-  'GetWebhook',
 ]
 /** Ancestor lookups: a bare array. */
-const ANCESTORS = [...STUB_TREES.map((t) => `GetTree${t}Ancestors`), 'GetTreeStaticFileAncestors']
+const ANCESTORS = STUB_TREES.map((t) => `GetTree${t}Ancestors`)
 /** Sibling windows: `{ totalBefore, totalAfter, items }`. */
 const SIBLINGS = [
   ...STUB_TREES.map((t) => `GetTree${t}Siblings`),

package/src/handlers/static-files.ts

@@ -0,0 +1,98 @@
+/**
+ * The static-file picker's tree: the stylesheets and scripts folders the site
+ * serves at `/css/` and `/scripts/`, so every path it offers is one a browser
+ * can load as it stands. Read-only; the files are edited in their own areas.
+ */
+import { invalidSkipTake, paged, parseSkipTake, problemResponse } from '@crombolo/core'
+import type { FileEntry, FileSystemPort } from '../ports-files.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+
+type Area = Pick<FileSystemPort, 'children' | 'entry'>
+
+/** The two served folders, by the URL segment each is served under. */
+export function createStaticFiles(mounts: Record<string, Area>): Area {
+  const split = (path: string): [Area, string, string] | undefined => {
+    const [, mount = '', ...rest] = path.replace(/\/+$/, '').split('/')
+    const area = mounts[mount]
+    return area ? [area, mount, `/${rest.join('/')}`] : undefined
+  }
+  const mounted = (mount: string, entry: FileEntry): FileEntry => ({
+    ...entry,
+    path: `/${mount}${entry.path}`,
+    parentPath: entry.parentPath ? `/${mount}${entry.parentPath}` : `/${mount}`,
+  })
+  const folder = async (mount: string, area: Area): Promise<FileEntry | undefined> => {
+    const children = await area.children(null)
+    if (!children || children.length === 0) return undefined
+    return { name: mount, path: `/${mount}`, parentPath: null, isFolder: true, hasChildren: true }
+  }
+  return {
+    async children(parentPath) {
+      if (!parentPath || parentPath === '/') {
+        const roots = await Promise.all(
+          Object.entries(mounts).map(([mount, area]) => folder(mount, area)),
+        )
+        return roots.filter((entry): entry is FileEntry => entry !== undefined)
+      }
+      const found = split(parentPath)
+      if (!found) return undefined
+      const [area, mount, inner] = found
+      const children = await area.children(inner === '/' ? null : inner)
+      return children?.map((entry) => mounted(mount, entry))
+    },
+    async entry(path) {
+      const found = split(path)
+      if (!found) return undefined
+      const [area, mount, inner] = found
+      if (inner === '/') return folder(mount, area)
+      const entry = await area.entry(inner)
+      return entry ? mounted(mount, entry) : undefined
+    },
+  }
+}
+
+const treeItem = (entry: FileEntry) => ({
+  name: entry.name,
+  path: entry.path,
+  parent: entry.parentPath ? { path: entry.parentPath } : null,
+  isFolder: entry.isFolder,
+  hasChildren: entry.hasChildren,
+})
+
+export function registerStaticFileHandlers(router: ManagementApiRouter, files: Area): void {
+  const page = (ctx: RequestContext, entries: readonly FileEntry[] | undefined) => {
+    const parsed = parseSkipTake(ctx.url.searchParams)
+    if (!parsed.ok) return problemResponse(invalidSkipTake())
+    const all = (entries ?? []).map(treeItem)
+    const { skip, take } = parsed.value
+    return Response.json(paged(all.slice(skip, skip + take), all.length))
+  }
+  router.handle('GetTreeStaticFileRoot', async (ctx) => page(ctx, await files.children(null)))
+  router.handle('GetTreeStaticFileChildren', async (ctx) =>
+    page(ctx, await files.children(ctx.url.searchParams.get('parentPath') || null)),
+  )
+  router.handle('GetTreeStaticFileAncestors', async (ctx) => {
+    const path = ctx.url.searchParams.get('descendantPath')
+    const chain: FileEntry[] = []
+    let current = path ? await files.entry(path) : undefined
+    while (current) {
+      chain.unshift(current)
+      current = current.parentPath ? await files.entry(current.parentPath) : undefined
+    }
+    return Response.json(chain.map(treeItem))
+  })
+  router.handle('GetItemStaticFile', async (ctx) => {
+    const items = []
+    for (const path of ctx.url.searchParams.getAll('path')) {
+      const entry = await files.entry(path)
+      if (entry)
+        items.push({
+          isFolder: entry.isFolder,
+          name: entry.name,
+          parent: entry.parentPath ? { path: entry.parentPath } : null,
+          path: entry.path,
+        })
+    }
+    return Response.json(items)
+  })
+}

package/src/handlers/template.ts

@@ -22,6 +22,8 @@ function toResponse(model: ComponentModel): ResponseOf<'GetTemplateById'> {
 }
 
 export function registerTemplateHandlers(router: ManagementApiRouter, port: TemplatePort): void {
+  // Templates are the site's components and are always on.
+  router.handle('GetTemplateConfiguration', () => Response.json({ disabled: false }))
   router.handle('GetTemplateById', async ({ params }) => {
     const model = await port.byKey(params.id as string)
     if (!model) return problemResponse(notFound('The template could not be found'))

package/src/handlers/webhook.ts

@@ -0,0 +1,146 @@
+/**
+ * The webhook operations: definitions, the events they may name, and the
+ * delivery log. docs/webhooks.md.
+ */
+import {
+  invalidSkipTake,
+  notFound,
+  paged,
+  parseSkipTake,
+  problemDetails,
+  problemResponse,
+} from '@crombolo/core'
+import type {
+  WebhookInput,
+  WebhookPort,
+  WebhookPortResult,
+  WebhookPortView,
+} from '../ports-webhooks.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+import { WEBHOOK_EVENTS } from '../webhook-events.ts'
+import { created } from './content-type.ts'
+
+const V1 = '/umbraco/management/api/v1'
+
+const EVENTS = new Map(WEBHOOK_EVENTS.map((event) => [event.alias, event]))
+
+/** Umbraco names each event in the response, not just by alias. */
+function toResponse(webhook: WebhookPortView) {
+  return {
+    ...webhook,
+    events: webhook.events.map(
+      (alias) => EVENTS.get(alias) ?? { alias, eventName: alias, eventType: 'Other' },
+    ),
+  }
+}
+
+const strings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
+
+/** The request body as a webhook; what is not there reads as empty, for the validator to refuse. */
+async function inputOf(ctx: RequestContext): Promise<WebhookInput> {
+  const body = ((await ctx.request.json().catch(() => ({}))) ?? {}) as Record<string, unknown>
+  const text = (key: string) => (typeof body[key] === 'string' ? (body[key] as string) : null)
+  const headers: Record<string, string> = {}
+  if (body.headers && typeof body.headers === 'object' && !Array.isArray(body.headers))
+    for (const [name, value] of Object.entries(body.headers as Record<string, unknown>))
+      if (typeof value === 'string') headers[name] = value
+  return {
+    id: text('id') ?? undefined,
+    name: text('name'),
+    description: text('description'),
+    url: text('url') ?? '',
+    enabled: body.enabled !== false,
+    events: strings(body.events),
+    contentTypeKeys: strings(body.contentTypeKeys).map((key) => key.toLowerCase()),
+    headers,
+  }
+}
+
+function refused(result: Exclude<WebhookPortResult, { ok: true }>): Response {
+  if (result.status === 404) return problemResponse(notFound('The webhook could not be found'))
+  return problemResponse(
+    problemDetails({
+      title: result.reason,
+      status: result.status,
+      detail: result.problems?.join(' '),
+      ...(result.problems ? { errors: { webhook: result.problems } } : {}),
+    }),
+  )
+}
+
+export function registerWebhookHandlers(router: ManagementApiRouter, port: WebhookPort): void {
+  router.handle('GetWebhook', async (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const all = await port.list()
+    const { skip, take } = page.value
+    return Response.json(paged(all.slice(skip, skip + take).map(toResponse), all.length))
+  })
+
+  router.handle('GetWebhookById', async (ctx) => {
+    const webhook = await port.get(ctx.params.id as string)
+    return webhook
+      ? Response.json(toResponse(webhook))
+      : problemResponse(notFound('The webhook could not be found'))
+  })
+
+  router.handle('GetItemWebhook', async (ctx) => {
+    const ids = new Set(ctx.url.searchParams.getAll('id').map((id) => id.toLowerCase()))
+    const all = await port.list()
+    return Response.json(
+      all
+        .filter((webhook) => ids.has(webhook.id))
+        .map((webhook) => ({
+          id: webhook.id,
+          name: webhook.name ?? webhook.url,
+          enabled: webhook.enabled,
+          url: webhook.url,
+          events: webhook.events.map((alias) => EVENTS.get(alias)?.eventName ?? alias).join(', '),
+          types: webhook.contentTypeKeys.join(', '),
+          flags: [],
+        })),
+    )
+  })
+
+  router.handle('PostWebhook', async (ctx) => {
+    const input = await inputOf(ctx)
+    const result = await port.create({ ...input, id: input.id ?? crypto.randomUUID() })
+    if (!result.ok) return refused(result)
+    return created(`${ctx.url.origin}${V1}/webhook/${result.id}`, result.id)
+  })
+
+  router.handle('PutWebhookById', async (ctx) => {
+    const result = await port.update(ctx.params.id as string, await inputOf(ctx))
+    return result.ok ? new Response(null, { status: 200 }) : refused(result)
+  })
+
+  router.handle('DeleteWebhookById', async (ctx) =>
+    (await port.remove(ctx.params.id as string))
+      ? new Response(null, { status: 200 })
+      : problemResponse(notFound('The webhook could not be found')),
+  )
+
+  router.handle('GetWebhookEvents', (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const { skip, take } = page.value
+    return Response.json(paged(WEBHOOK_EVENTS.slice(skip, skip + take), WEBHOOK_EVENTS.length))
+  })
+
+  router.handle('GetWebhookLogs', async (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const result = await port.logs(undefined, page.value)
+    return Response.json(paged(result.items, result.total))
+  })
+
+  router.handle('GetWebhookByIdLogs', async (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    if (!(await port.get(ctx.params.id as string)))
+      return problemResponse(notFound('The webhook could not be found'))
+    const result = await port.logs(ctx.params.id as string, page.value)
+    return Response.json(paged(result.items, result.total))
+  })
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './audit.ts'
 export * from './authorization.ts'
+export * from './divergences.ts'
 export * from './handlers/content-type.ts'
 export * from './handlers/package.ts'
 export * from './handlers/settings-stubs.ts'
@@ -7,12 +8,15 @@ export * from './handlers/template-query.ts'
 export * from './handlers/user.ts'
 export * from './ports.ts'
 export * from './ports-content.ts'
+export * from './ports-diagnostics.ts'
 export * from './ports-files.ts'
 export * from './ports-logs.ts'
 export * from './ports-members.ts'
 export * from './ports-models-builder.ts'
 export * from './ports-packages.ts'
 export * from './ports-users.ts'
+export * from './ports-webhooks.ts'
 export * from './router.ts'
 export * from './routes.ts'
 export * from './server-events.ts'
+export * from './webhook-events.ts'

package/src/ports-content.ts

@@ -231,6 +231,10 @@ export interface DataTypePort extends TreePort {
     paging: SkipTake,
   ): Promise<Page<DataTypeModel>>
   search(query: string, paging: SkipTake): Promise<Page<DataTypeModel>>
+  /** Whether any current value is saved through it; undefined when it does not exist. */
+  isUsed?(key: string): Promise<boolean | undefined>
+  /** Whether any current value is saved for a property; undefined when there is no such property. */
+  propertyIsUsed?(contentTypeKey: string, alias: string): Promise<boolean | undefined>
   referencedBy(key: string): Promise<
     Array<{
       propertyKey: string
@@ -262,6 +266,8 @@ export interface TemplatePort extends TreePort {
 
 export interface DocumentPort extends TreePort {
   byKey(key: string): Promise<DocumentAggregate | undefined>
+  /** Every property alias its type has, compositions included. */
+  propertyAliases?(key: string): Promise<string[] | undefined>
   /** The published version's values; undefined when nothing is published. */
   byKeyPublished(key: string): Promise<DocumentAggregate | undefined>
   /** What the editor asks before a save: the rules the server would enforce. */
@@ -498,11 +504,34 @@ export interface MediaPort {
 
 /** What refers to a document, media item or member — the Info tab's list. */
 export interface ReferencePort {
+  /** What refers to anything of this kind in the recycle bin, as the empty-bin dialog asks. */
+  recycleBinReferencedBy?(
+    area: 'Document' | 'Media' | 'Element',
+    paging: SkipTake,
+  ): Promise<Page<unknown>>
   referencedBy(key: string, paging: SkipTake): Promise<Page<unknown>>
   referencedDescendants(key: string, paging: SkipTake): Promise<Page<{ id: string }>>
   areReferenced(keys: readonly string[], paging: SkipTake): Promise<Page<{ id: string }>>
 }
 
+/** A relation type as the wire carries it: `RelationTypeResponseModel`. */
+export interface RelationTypeView {
+  id: string
+  alias: string
+  name: string
+  parentObject: { id: string; name: string } | null
+  childObject: { id: string; name: string } | null
+  isBidirectional: boolean
+  isDependency: boolean
+}
+
+/** Umbraco's relation types, read-only, with relations derived for each (story 046). */
+export interface RelationPort {
+  types(): readonly RelationTypeView[]
+  /** Undefined when there is no such type. */
+  relations(typeKey: string, paging: SkipTake): Promise<Page<unknown> | undefined>
+}
+
 /** One redirect as the dashboard and the Info tab read it. */
 export interface RedirectListing {
   key: string
@@ -562,3 +591,26 @@ export interface TemplateQueryPort {
   documentTypeAliases(): Promise<string[]>
   execute(request: TemplateQueryRequest): Promise<{ items: TemplateQueryItem[]; total: number }>
 }
+
+/**
+ * Approval before publishing (story 028): asked before a publish, an unpublish
+ * or a save, so a page a workflow covers goes through it. Each answer is
+ * undefined to go ahead, or what to tell the person.
+ */
+export interface ApprovalGatePort {
+  publishRefusal(
+    principal: Principal,
+    key: string,
+    action: 'publish' | 'unpublish',
+  ): Promise<string | undefined>
+  /** A branch publish: the root and every page below it. */
+  branchRefusal(principal: Principal, key: string): Promise<string | undefined>
+  /** A page created and published in one go, by where it will sit and its type. */
+  newPageRefusal(
+    principal: Principal,
+    parentKey: string | null,
+    contentTypeKey: string,
+  ): Promise<string | undefined>
+  beforeSave(principal: Principal, key: string): Promise<string | undefined>
+  afterSave(principal: Principal, key: string): Promise<void>
+}

package/src/ports-diagnostics.ts

@@ -0,0 +1,17 @@
+import type { ResponseOf, Schemas } from '@crombolo/contracts'
+
+export type HealthCheckResult = Schemas['HealthCheckResultResponseModel']
+
+export interface HealthCheckGroup {
+  name: string
+  checks: Schemas['HealthCheckModel'][]
+}
+
+/** The health checks, troubleshooting report and upgrade check. docs/diagnostics.md. */
+export interface DiagnosticsPort {
+  groups(): HealthCheckGroup[]
+  /** Runs every check in the group; undefined when there is no such group. */
+  run(group: string): Promise<Schemas['HealthCheckWithResultPresentationModel'][] | undefined>
+  troubleshooting(): Promise<ResponseOf<'GetServerTroubleshooting'>>
+  upgradeCheck(): Promise<ResponseOf<'GetServerUpgradeCheck'>>
+}

package/src/ports-webhooks.ts

@@ -0,0 +1,32 @@
+/** Webhooks, as the Management API's eight operations and the item lookup need them. */
+import type { Page, SkipTake } from '@crombolo/core'
+
+/** One webhook as the backoffice edits it; a typed-in secret comes back masked. */
+export interface WebhookInput {
+  id?: string
+  name: string | null
+  description: string | null
+  url: string
+  enabled: boolean
+  events: string[]
+  contentTypeKeys: string[]
+  headers: Record<string, string>
+}
+
+export interface WebhookPortView extends WebhookInput {
+  id: string
+}
+
+export type WebhookPortResult =
+  | { ok: true; id: string }
+  | { ok: false; status: 400 | 404 | 409; reason: string; problems?: string[] }
+
+export interface WebhookPort {
+  list(): Promise<WebhookPortView[]>
+  get(id: string): Promise<WebhookPortView | undefined>
+  create(input: WebhookInput): Promise<WebhookPortResult>
+  update(id: string, input: WebhookInput): Promise<WebhookPortResult>
+  remove(id: string): Promise<boolean>
+  /** Already in the wire's `WebhookLogResponseModel` shape; one webhook's when `id` is given. */
+  logs(id: string | undefined, paging: SkipTake): Promise<Page<unknown>>
+}

package/src/ports.ts

@@ -10,6 +10,7 @@
 import type { ResponseOf } from '@crombolo/contracts'
 import type { UploadSettings } from '@crombolo/core'
 import type {
+  ApprovalGatePort,
   BlueprintPort,
   ContentTypePort,
   DataTypePort,
@@ -18,15 +19,18 @@ import type {
   MediaPort,
   RedirectPort,
   ReferencePort,
+  RelationPort,
   TemplatePort,
   TemplateQueryPort,
 } from './ports-content.ts'
+import type { DiagnosticsPort } from './ports-diagnostics.ts'
 import type { FileSystemPort, Snippet } from './ports-files.ts'
 import type { LogViewerPort } from './ports-logs.ts'
 import type { MemberGroupPort, MemberPort, PublicAccessPort } from './ports-members.ts'
 import type { ModelsBuilderPort } from './ports-models-builder.ts'
 import type { PackagePort } from './ports-packages.ts'
 import type { UserDataPort, UserGroupPort, UserPort } from './ports-users.ts'
+import type { WebhookPort } from './ports-webhooks.ts'
 import type { Principal } from './router.ts'
 
 export interface ServerPort {
@@ -170,6 +174,16 @@ export interface OEmbedPort {
   >
 }
 
+/** A content picker's start node, found from the document being edited. */
+export interface DynamicRootPort {
+  resolve(query: {
+    currentKey: string | null
+    parentKey: string | null
+    origin: { alias: string; key: string | null }
+    steps: Array<{ alias: string; documentTypeKeys: string[] }>
+  }): Promise<string[]>
+}
+
 /** Preview mode is a cookie; the server owns its name and attributes. */
 export interface PreviewPort {
   /** `Set-Cookie` values that enter preview for the signed-in editor. */
@@ -233,11 +247,14 @@ export interface AuthPort {
 
 export interface ManagementApiDeps {
   server: ServerPort
+  /** Health checks, troubleshooting and the upgrade check; needs the database. */
+  diagnostics?: DiagnosticsPort
   manifests: ManifestPort
   localization: LocalizationPort
   currentUser: CurrentUserPort
   users?: UserItemPort
   preview?: PreviewPort
+  dynamicRoots?: DynamicRootPort
   temporaryFiles?: TemporaryFilePort
   media?: MediaPort
   tags?: TagPort
@@ -249,6 +266,8 @@ export interface ManagementApiDeps {
   dataTypes?: DataTypePort
   templates?: TemplatePort
   documents?: DocumentPort
+  /** Approval workflows: the gate on publishing and saving a page a workflow covers. */
+  approvals?: ApprovalGatePort
   dictionary?: DictionaryPort
   userManagement?: UserPort
   userGroups?: UserGroupPort
@@ -270,6 +289,8 @@ export interface ManagementApiDeps {
   publicAccess?: PublicAccessPort
   elements?: ElementPort
   references?: ReferencePort
+  relations?: RelationPort
+  webhooks?: WebhookPort
   redirects?: RedirectPort
   packages?: PackagePort
 }

package/src/router.ts

@@ -3,6 +3,7 @@
  * so a path that is not in the contract cannot be served, and an operation in
  * the contract without a handler answers 501 rather than 404.
  */
+
 import { type HttpMethod, listOperations, loadSpec, type OperationInfo } from '@crombolo/contracts'
 import {
   applyNotifications,
@@ -25,6 +26,7 @@ import {
 } from './audit.ts'
 import { authorize, LOCAL_LOGIN_OPERATIONS, type NodeLookup } from './authorization.ts'
 import { type ServerEvent, serverEventFor } from './server-events.ts'
+import { type RaisedWebhookEvent, webhookEventFor } from './webhook-events.ts'
 
 /**
  * Resolved back-office identity, assembled from a reference token plus the
@@ -88,6 +90,10 @@ export interface RouterOptions {
   audit?: AuditSink
   /** Where a request came from, for its audit entry. */
   clientAddress?: (request: Request) => ClientAddress
+  /** Answers an error a handler threw; undefined lets it propagate. */
+  onError?: (error: unknown) => Response | undefined
+  /** Told about every webhook event a successful operation raises. */
+  onWebhookEvent?: (event: RaisedWebhookEvent) => void
 }
 
 export interface ClientAddress {
@@ -122,6 +128,8 @@ export class ManagementApiRouter {
   readonly #allowLocalLogin: boolean
   readonly #audit: AuditSink | undefined
   readonly #clientAddress: (request: Request) => ClientAddress
+  readonly #onError: RouterOptions['onError']
+  readonly #onWebhookEvent: RouterOptions['onWebhookEvent']
 
   constructor(options: RouterOptions = {}) {
     const operations = options.operations ?? listOperations(loadSpec())
@@ -133,6 +141,8 @@ export class ManagementApiRouter {
     this.#allowLocalLogin = options.allowLocalLogin ?? true
     this.#audit = options.audit
     this.#clientAddress = options.clientAddress ?? forwardedOnly
+    this.#onError = options.onError
+    this.#onWebhookEvent = options.onWebhookEvent
     for (const operation of operations) {
       const segments = operation.path.split('/').filter((s) => s.length > 0)
       const paramNames = segments.map((s) =>
@@ -233,7 +243,7 @@ export class ManagementApiRouter {
     const plan = handler && this.#audit ? auditPlanFor(operation.operationId) : undefined
     const audit = plan ? await this.#beforeAudit(plan, params, request) : undefined
     const response = handler
-      ? await handler({ request, url, params, operation, notifications, principal })
+      ? await this.#run(handler, { request, url, params, operation, notifications, principal })
       : problemResponse(notImplemented(operation.operationId))
     if (plan && audit && response.status >= 200 && response.status < 300)
       await this.#recordAudit(plan, audit, params, request, response, principal)
@@ -241,12 +251,26 @@ export class ManagementApiRouter {
       const event = serverEventFor(operation, params, response)
       if (event) this.#onServerEvent(event)
     }
+    if (handler && this.#onWebhookEvent) {
+      const event = webhookEventFor(operation.operationId, params, response)
+      if (event) this.#onWebhookEvent(event)
+    }
     const headers = new Headers(response.headers)
     applyNotifications(headers, request.method, notifications)
     headers.set('cache-control', 'no-store')
     return new Response(response.body, { status: response.status, headers })
   }
 
+  async #run(handler: OperationHandler, ctx: RequestContext): Promise<Response> {
+    try {
+      return await handler(ctx)
+    } catch (error) {
+      const answered = this.#onError?.(error)
+      if (answered) return answered
+      throw error
+    }
+  }
+
   /** Reads what the entry needs before the handler consumes the body or removes the item. */
   async #beforeAudit(
     plan: AuditPlan,

package/src/routes.ts

@@ -5,9 +5,14 @@
 import { registerAuditLogHandlers } from './handlers/audit-log.ts'
 import { registerContentTypeHandlers } from './handlers/content-type.ts'
 import { registerDataTypeHandlers } from './handlers/data-type.ts'
+import {
+  registerDiagnosticsHandlers,
+  registerTelemetryAndProfilingHandlers,
+} from './handlers/diagnostics.ts'
 import { registerDictionaryHandlers } from './handlers/dictionary.ts'
 import { registerDocumentHandlers } from './handlers/document.ts'
 import { registerDocumentBlueprintHandlers } from './handlers/document-blueprint.ts'
+import { registerDynamicRootHandlers } from './handlers/dynamic-root.ts'
 import { registerEditorServiceHandlers } from './handlers/editor-services.ts'
 import { registerElementHandlers } from './handlers/element.ts'
 import { registerFileSystemHandlers } from './handlers/file-systems.ts'
@@ -23,14 +28,21 @@ import { registerPackageHandlers } from './handlers/package.ts'
 import { registerPublicAccessHandlers } from './handlers/public-access.ts'
 import { registerPublishedCacheHandlers } from './handlers/published-cache.ts'
 import { registerRedirectHandlers } from './handlers/redirects.ts'
+import { registerReferenceDataHandlers } from './handlers/reference-data.ts'
 import { registerReferenceHandlers } from './handlers/references.ts'
+import {
+  registerRecycleBinReferenceHandlers,
+  registerRelationHandlers,
+} from './handlers/relations.ts'
 import { registerSearchIndexHandlers } from './handlers/search-index.ts'
 import { registerServerHandlers } from './handlers/server.ts'
 import { registerSettingsStubHandlers } from './handlers/settings-stubs.ts'
+import { createStaticFiles, registerStaticFileHandlers } from './handlers/static-files.ts'
 import { registerTemplateHandlers } from './handlers/template.ts'
 import { registerTemplateQueryHandlers } from './handlers/template-query.ts'
 import { registerTemporaryFileHandlers } from './handlers/temporary-file.ts'
 import { registerUserHandlers } from './handlers/user.ts'
+import { registerWebhookHandlers } from './handlers/webhook.ts'
 import type { ManagementApiDeps } from './ports.ts'
 import { type Authenticator, ManagementApiRouter, type RouterOptions } from './router.ts'
 
@@ -43,6 +55,8 @@ export interface ManagementApiOptions {
   allowLocalLogin?: boolean
   audit?: RouterOptions['audit']
   clientAddress?: RouterOptions['clientAddress']
+  onError?: RouterOptions['onError']
+  onWebhookEvent?: RouterOptions['onWebhookEvent']
 }
 
 export function createManagementApiRouter(options: ManagementApiOptions = {}): ManagementApiRouter {
@@ -54,6 +68,8 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     allowLocalLogin: options.allowLocalLogin,
     audit: options.audit,
     clientAddress: options.clientAddress,
+    onError: options.onError,
+    onWebhookEvent: options.onWebhookEvent,
   })
   const { deps } = options
   if (!deps) return router
@@ -67,6 +83,10 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     userData: deps.userData,
   })
   registerSettingsStubHandlers(router)
+  registerTelemetryAndProfilingHandlers(router)
+  registerReferenceDataHandlers(router)
+  if (deps.dynamicRoots) registerDynamicRootHandlers(router, deps.dynamicRoots)
+  if (deps.diagnostics) registerDiagnosticsHandlers(router, deps.diagnostics)
   if (deps.contentTypes)
     registerContentTypeHandlers(router, deps.contentTypes, 'document', deps.temporaryFiles)
   if (deps.mediaTypes)
@@ -76,7 +96,7 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
   if (deps.dataTypes) registerDataTypeHandlers(router, deps.dataTypes)
   if (deps.templates) registerTemplateHandlers(router, deps.templates)
   if (deps.templateQuery) registerTemplateQueryHandlers(router, deps.templateQuery)
-  if (deps.documents) registerDocumentHandlers(router, deps.documents, deps.preview)
+  if (deps.documents) registerDocumentHandlers(router, deps.documents, deps.preview, deps.approvals)
   if (deps.blueprints) registerDocumentBlueprintHandlers(router, deps.blueprints)
   if (deps.temporaryFiles) registerTemporaryFileHandlers(router, deps.temporaryFiles)
   if (deps.media) registerMediaHandlers(router, deps.media)
@@ -87,6 +107,11 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     registerFileSystemHandlers(router, 'PartialView', deps.components, deps.componentSnippets)
   if (deps.stylesheets) registerFileSystemHandlers(router, 'Stylesheet', deps.stylesheets)
   if (deps.scripts) registerFileSystemHandlers(router, 'Script', deps.scripts)
+  if (deps.stylesheets && deps.scripts)
+    registerStaticFileHandlers(
+      router,
+      createStaticFiles({ css: deps.stylesheets, scripts: deps.scripts }),
+    )
   if (deps.logViewer) registerLogViewerHandlers(router, deps.logViewer)
   if (deps.modelsBuilder) registerModelsBuilderHandlers(router, deps.modelsBuilder)
   if (deps.publishedCache) registerPublishedCacheHandlers(router, deps.publishedCache)
@@ -108,9 +133,13 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
   )
   if (deps.redirects) registerRedirectHandlers(router, deps.redirects)
   if (deps.packages) registerPackageHandlers(router, deps.packages)
-  if (deps.references)
+  if (deps.references) {
     for (const area of ['Document', 'Media', 'Member', 'Element'] as const)
       registerReferenceHandlers(router, area, deps.references)
+    registerRecycleBinReferenceHandlers(router, deps.references)
+  }
+  if (deps.relations) registerRelationHandlers(router, deps.relations)
+  if (deps.webhooks) registerWebhookHandlers(router, deps.webhooks)
   registerEditorServiceHandlers(router, { tags: deps.tags, oembed: deps.oembed })
   return router
 }

package/src/webhook-events.ts

@@ -0,0 +1,74 @@
+/**
+ * The webhook events this site raises, and which Management API operation
+ * raises each. Aliases are Umbraco's, so the backoffice's event picker and an
+ * imported site's choices mean the same thing. docs/webhooks.md.
+ */
+
+export type WebhookEventType = 'Content' | 'Media'
+
+export interface WebhookEventInfo {
+  alias: string
+  eventName: string
+  eventType: WebhookEventType
+}
+
+export const WEBHOOK_EVENTS: readonly WebhookEventInfo[] = [
+  { alias: 'Umbraco.ContentSaved', eventName: 'Content Saved', eventType: 'Content' },
+  { alias: 'Umbraco.ContentPublish', eventName: 'Content Published', eventType: 'Content' },
+  { alias: 'Umbraco.ContentUnpublish', eventName: 'Content Unpublished', eventType: 'Content' },
+  { alias: 'Umbraco.ContentDelete', eventName: 'Content Deleted', eventType: 'Content' },
+  {
+    alias: 'Umbraco.ContentMovedToRecycleBin',
+    eventName: 'Content Moved to Recycle Bin',
+    eventType: 'Content',
+  },
+  { alias: 'Umbraco.ContentMoved', eventName: 'Content Moved', eventType: 'Content' },
+  { alias: 'Umbraco.ContentCopied', eventName: 'Content Copied', eventType: 'Content' },
+  { alias: 'Umbraco.MediaSave', eventName: 'Media Saved', eventType: 'Media' },
+  { alias: 'Umbraco.MediaDelete', eventName: 'Media Deleted', eventType: 'Media' },
+]
+
+export const WEBHOOK_EVENT_ALIASES: ReadonlySet<string> = new Set(
+  WEBHOOK_EVENTS.map((event) => event.alias),
+)
+
+/** Something happened to one item: what, and to which. */
+export interface RaisedWebhookEvent {
+  alias: string
+  key: string
+}
+
+const BY_OPERATION: Record<string, string> = {
+  PostDocument: 'Umbraco.ContentSaved',
+  PutDocumentById: 'Umbraco.ContentSaved',
+  PutDocumentByIdPublish: 'Umbraco.ContentPublish',
+  PutDocumentByIdPublishWithDescendants: 'Umbraco.ContentPublish',
+  PostDocumentCreateAndPublish: 'Umbraco.ContentPublish',
+  PutDocumentByIdUpdateAndPublish: 'Umbraco.ContentPublish',
+  PutDocumentByIdUnpublish: 'Umbraco.ContentUnpublish',
+  DeleteDocumentById: 'Umbraco.ContentDelete',
+  DeleteRecycleBinDocumentById: 'Umbraco.ContentDelete',
+  PutDocumentByIdMoveToRecycleBin: 'Umbraco.ContentMovedToRecycleBin',
+  PutDocumentByIdMove: 'Umbraco.ContentMoved',
+  PostDocumentByIdCopy: 'Umbraco.ContentCopied',
+  PostMedia: 'Umbraco.MediaSave',
+  PutMediaById: 'Umbraco.MediaSave',
+  DeleteMediaById: 'Umbraco.MediaDelete',
+  DeleteRecycleBinMediaById: 'Umbraco.MediaDelete',
+}
+
+/**
+ * The event a successful operation raises, if any. Pure. The item is the one
+ * the operation created (its generated-resource header) or the one it names.
+ */
+export function webhookEventFor(
+  operationId: string,
+  params: Readonly<Record<string, string>>,
+  response: Pick<Response, 'status' | 'headers'>,
+): RaisedWebhookEvent | undefined {
+  if (response.status < 200 || response.status >= 300) return undefined
+  const alias = BY_OPERATION[operationId]
+  if (!alias) return undefined
+  const key = response.headers.get('umb-generated-resource') ?? params.id
+  return key ? { alias, key: key.toLowerCase() } : undefined
+}