@crombolo/api-management 0.0.0-stage → 0.10.0

package/src/handlers/member.ts

@@ -0,0 +1,189 @@
+/**
+ * The Members section: the collection, the editor, and the lookups member
+ * pickers use.
+ *
+ * Members are not a tree — the contract gives them no `tree/member` operations —
+ * so the collection is `filter/member`, which is Umbraco's own member filter with
+ * the same columns and the same default order (username, ascending).
+ */
+import {
+  type DocumentValue,
+  invalidSkipTake,
+  notFound,
+  paged,
+  problemDetails,
+  problemResponse,
+} from '@crombolo/core'
+import type { PortFailure } from '../ports-content.ts'
+import type { MemberPort, SaveMember } from '../ports-members.ts'
+import type { ManagementApiRouter, Principal, RequestContext } from '../router.ts'
+import { created, paging } from './content-type.ts'
+import { readBody, validationProblem } from './document.ts'
+
+const V1 = '/umbraco/management/api/v1'
+
+const refId = (value: unknown): string | null => {
+  if (!value || typeof value !== 'object') return null
+  const id = (value as Record<string, unknown>).id
+  return typeof id === 'string' && id ? id : null
+}
+
+const strings = (value: unknown): string[] | undefined =>
+  Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : undefined
+
+function readValues(body: Record<string, unknown>): DocumentValue[] {
+  if (!Array.isArray(body.values)) return []
+  return (body.values as Array<Record<string, unknown>>).map((value) => ({
+    alias: String(value.alias ?? ''),
+    culture: (value.culture as string | null) ?? null,
+    segment: (value.segment as string | null) ?? null,
+    value: value.value,
+  }))
+}
+
+function readVariants(body: Record<string, unknown>) {
+  if (!Array.isArray(body.variants)) return []
+  return (body.variants as Array<Record<string, unknown>>).map((variant) => ({
+    culture: (variant.culture as string | null) ?? null,
+    segment: (variant.segment as string | null) ?? null,
+    name: String(variant.name ?? ''),
+  }))
+}
+
+/**
+ * A member save request. Create carries `password` and `memberType`; update
+ * carries `newPassword` with `oldPassword` and neither of the other two, since
+ * a member's type never changes.
+ */
+export function toSaveMember(key: string, body: Record<string, unknown>): SaveMember {
+  const newPassword = typeof body.newPassword === 'string' ? body.newPassword : null
+  return {
+    key,
+    memberTypeKey: refId(body.memberType) ?? '',
+    email: typeof body.email === 'string' ? body.email.trim() : '',
+    username: typeof body.username === 'string' ? body.username.trim() : '',
+    password: typeof body.password === 'string' ? body.password : newPassword,
+    oldPassword: typeof body.oldPassword === 'string' ? body.oldPassword : null,
+    isApproved: body.isApproved !== false,
+    isLockedOut: body.isLockedOut === true,
+    isTwoFactorEnabled: body.isTwoFactorEnabled === true,
+    groupKeys: strings(body.groups),
+    values: readValues(body),
+    variants: readVariants(body),
+  }
+}
+
+const failed = (title: string, result: PortFailure) =>
+  problemResponse(problemDetails({ title, status: result.status ?? 400, detail: result.reason }))
+
+const missing = () => problemResponse(notFound('The member could not be found'))
+
+/** Required fields the contract declares but does not constrain. */
+function missingFields(input: SaveMember, forCreate: boolean): string | undefined {
+  if (!input.email) return 'An e-mail address is required'
+  if (!input.username) return 'A username is required'
+  if (input.variants.length === 0 || !input.variants[0]?.name) return 'A name is required'
+  if (forCreate && !input.memberTypeKey) return 'A member type is required'
+  if (forCreate && !input.password) return 'A password is required'
+  return undefined
+}
+
+export function registerMemberHandlers(router: ManagementApiRouter, port: MemberPort): void {
+  const viewer = (ctx: RequestContext) => ctx.principal as Principal
+  const done = (ctx: RequestContext, message?: string) => {
+    if (message) ctx.notifications.push({ message, category: 'Member', type: 'Success' })
+    return new Response(null, { status: 200 })
+  }
+
+  const checked = async (input: SaveMember, forCreate: boolean) => {
+    const problem = missingFields(input, forCreate)
+    if (problem) return problemResponse(problemDetails({ title: problem, status: 400 }))
+    const errors = await port.validate(input)
+    if (errors.length > 0) return problemResponse(validationProblem(errors, input.values))
+    return undefined
+  }
+
+  router.handle('GetMemberById', async (ctx) => {
+    const member = await port.byKey(ctx.params.id as string, viewer(ctx))
+    return member ? Response.json(member) : missing()
+  })
+
+  router.handle('PostMemberValidate', async (ctx) => {
+    const input = toSaveMember(crypto.randomUUID(), await readBody(ctx))
+    return (await checked(input, true)) ?? done(ctx)
+  })
+
+  router.handle('PutMemberByIdValidate', async (ctx) => {
+    const key = ctx.params.id as string
+    if (!(await port.byKey(key, viewer(ctx)))) return missing()
+    return (await checked(toSaveMember(key, await readBody(ctx)), false)) ?? done(ctx)
+  })
+
+  router.handle('PostMember', async (ctx) => {
+    const body = await readBody(ctx)
+    const key = typeof body.id === 'string' && body.id ? body.id : crypto.randomUUID()
+    const input = toSaveMember(key, body)
+    const invalid = await checked(input, true)
+    if (invalid) return invalid
+    const result = await port.create(input, viewer(ctx))
+    if (!result.ok) return failed('Could not create the member', result)
+    return created(`${ctx.url.origin}${V1}/member/${result.key}`, result.key)
+  })
+
+  router.handle('PutMemberById', async (ctx) => {
+    const key = ctx.params.id as string
+    if (!(await port.byKey(key, viewer(ctx)))) return missing()
+    const input = toSaveMember(key, await readBody(ctx))
+    const invalid = await checked(input, false)
+    if (invalid) return invalid
+    const result = await port.update(key, input, viewer(ctx))
+    return result.ok ? done(ctx) : failed('Could not save the member', result)
+  })
+
+  router.handle('DeleteMemberById', async (ctx) =>
+    (await port.remove(ctx.params.id as string)) ? done(ctx) : missing(),
+  )
+
+  router.handle('GetFilterMember', async (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    const query = ctx.url.searchParams
+    const flag = (name: string) => {
+      const value = query.get(name)
+      return value === null ? undefined : value === 'true'
+    }
+    const result = await port.filter(
+      {
+        ...page,
+        memberTypeKey: query.get('memberTypeId'),
+        memberGroupName: query.get('memberGroupName'),
+        isApproved: flag('isApproved'),
+        isLockedOut: flag('isLockedOut'),
+        filter: query.get('filter') ?? undefined,
+        orderBy: query.get('orderBy') ?? undefined,
+        orderDirection: query.get('orderDirection') === 'Descending' ? 'Descending' : 'Ascending',
+      },
+      viewer(ctx),
+    )
+    return Response.json(paged(result.items, result.total))
+  })
+
+  router.handle('GetItemMember', async (ctx) =>
+    Response.json(await port.items(ctx.url.searchParams.getAll('id'))),
+  )
+
+  // A member has no ancestors: the list is always empty, but the picker asks.
+  router.handle('GetItemMemberAncestors', (ctx) =>
+    Response.json(ctx.url.searchParams.getAll('id').map((id) => ({ id, ancestors: [] }))),
+  )
+
+  router.handle('GetItemMemberSearch', async (ctx) => {
+    const page = paging(ctx)
+    if (!page) return problemResponse(invalidSkipTake())
+    const result = await port.search(ctx.url.searchParams.get('query') ?? '', {
+      ...page,
+      allowedMemberTypeKeys: ctx.url.searchParams.getAll('allowedMemberTypes'),
+    })
+    return Response.json(paged(result.items, result.total))
+  })
+}

package/src/handlers/models-builder.ts

@@ -0,0 +1,29 @@
+/**
+ * Models Builder: the dashboard's state, whether the models are stale, and the
+ * Generate button. A build that fails still answers 200, as Umbraco's does —
+ * the client treats any other status as a failed request and never re-reads the
+ * dashboard, which is the only place the error is shown.
+ */
+import type { ModelsBuilderPort } from '../ports-models-builder.ts'
+import type { ManagementApiRouter } from '../router.ts'
+
+export function registerModelsBuilderHandlers(
+  router: ManagementApiRouter,
+  models: ModelsBuilderPort,
+): void {
+  router.handle('GetModelsBuilderDashboard', async () => Response.json(await models.info()))
+
+  router.handle('GetModelsBuilderStatus', async () =>
+    Response.json({ status: await models.status() }),
+  )
+
+  router.handle('PostModelsBuilderBuild', async (ctx) => {
+    const result = await models.build()
+    ctx.notifications.push(
+      result.ok
+        ? { message: 'Models generated', category: 'Models Builder', type: 'Success' }
+        : { message: 'Models could not be generated', category: 'Models Builder', type: 'Error' },
+    )
+    return new Response(null, { status: 200 })
+  })
+}

package/src/handlers/package.ts

@@ -0,0 +1,193 @@
+/**
+ * The Packages section: created-package definitions, their download, and the
+ * two migration operations that answer honestly rather than pretend.
+ *
+ * `packagePath` is required by the contract and is a real file path in Umbraco,
+ * which stores a built zip on disk. Nothing is stored here — the zip is built
+ * when it is downloaded — so it reports the name the download will carry,
+ * which is the only part of it the client ever shows.
+ */
+import {
+  invalidSkipTake,
+  notFound,
+  paged,
+  parseSkipTake,
+  problemDetails,
+  problemResponse,
+} from '@crombolo/core'
+import type {
+  PackageDefinition,
+  PackageDefinitionInput,
+  PackagePort,
+  PackageWriteResult,
+} from '../ports-packages.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+import { created } from './content-type.ts'
+
+const packageNotFound = () => problemResponse(notFound('The package could not be found'))
+
+/**
+ * A download filename, as `npm pack` names one: the package name with its scope
+ * folded in, then the version. No separators, no surprises.
+ */
+export function packageFileName(name: string, version = '1.0.0'): string {
+  const slug = name
+    .trim()
+    .toLowerCase()
+    .replace(/^@/, '')
+    .replace(/[^a-z0-9.]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return `${slug || 'package'}-${version}.tgz`
+}
+
+const toResponse = (definition: PackageDefinition) => ({
+  id: definition.id,
+  name: definition.name,
+  packagePath: packageFileName(definition.name),
+  contentNodeId: definition.contentNodeId,
+  contentLoadChildNodes: definition.contentLoadChildNodes,
+  mediaIds: definition.mediaIds,
+  mediaLoadChildNodes: definition.mediaLoadChildNodes,
+  elementIds: definition.elementIds,
+  documentTypes: definition.contentTypes,
+  mediaTypes: definition.mediaTypes,
+  dataTypes: definition.dataTypes,
+  templates: definition.templates,
+  partialViews: definition.partialViews,
+  stylesheets: definition.stylesheets,
+  scripts: definition.scripts,
+  languages: definition.languages,
+  dictionaryItems: definition.dictionaryItems,
+})
+
+const strings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
+
+/** The id of a reference, which the client sends as `{ id }` or as a bare string. */
+const refId = (value: unknown): string | null => {
+  if (typeof value === 'string') return value.length > 0 ? value : null
+  if (value && typeof value === 'object' && 'id' in value) {
+    const id = (value as { id: unknown }).id
+    return typeof id === 'string' && id.length > 0 ? id : null
+  }
+  return null
+}
+
+function readInput(body: Record<string, unknown>): PackageDefinitionInput {
+  return {
+    name: String(body.name ?? '').trim(),
+    contentNodeId: refId(body.contentNodeId),
+    contentLoadChildNodes: body.contentLoadChildNodes === true,
+    mediaIds: strings(body.mediaIds),
+    mediaLoadChildNodes: body.mediaLoadChildNodes === true,
+    elementIds:
+      body.elementIds === null || body.elementIds === undefined ? null : strings(body.elementIds),
+    contentTypes: strings(body.documentTypes),
+    mediaTypes: strings(body.mediaTypes),
+    dataTypes: strings(body.dataTypes),
+    templates: strings(body.templates),
+    partialViews: strings(body.partialViews),
+    stylesheets: strings(body.stylesheets),
+    scripts: strings(body.scripts),
+    languages: strings(body.languages),
+    dictionaryItems: strings(body.dictionaryItems),
+  }
+}
+
+function writeFailure(result: PackageWriteResult): Response | undefined {
+  if (result.ok) return undefined
+  switch (result.status) {
+    case 'NotFound':
+      return packageNotFound()
+    case 'InvalidName':
+      return problemResponse(
+        problemDetails({
+          title: 'A package name is required',
+          status: 400,
+          operationStatus: 'InvalidName',
+        }),
+      )
+    case 'DuplicateName':
+      return problemResponse(
+        problemDetails({
+          title: 'Duplicate package name detected',
+          detail: 'Another package exists with the same name. Package names must be unique.',
+          status: 400,
+          operationStatus: 'DuplicateName',
+        }),
+      )
+  }
+}
+
+const body = async (ctx: RequestContext): Promise<Record<string, unknown>> =>
+  ((await ctx.request.json().catch(() => ({}))) ?? {}) as Record<string, unknown>
+
+export function registerPackageHandlers(router: ManagementApiRouter, port: PackagePort): void {
+  router.handle('GetPackageConfiguration', () =>
+    Response.json({ marketplaceUrl: port.marketplaceUrl() }),
+  )
+
+  router.handle('GetPackageCreated', async (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const result = await port.list(page.value)
+    return Response.json(paged(result.items.map(toResponse), result.total))
+  })
+
+  router.handle('PostPackageCreated', async (ctx) => {
+    const input = await body(ctx)
+    const result = await port.create(readInput(input), refId(input.id) ?? undefined)
+    const failed = writeFailure(result)
+    if (failed) return failed
+    const id = result.ok ? result.id : ''
+    return created(`${ctx.url.origin}/umbraco/management/api/v1/package/created/${id}`, id)
+  })
+
+  router.handle('GetPackageCreatedById', async (ctx) => {
+    const definition = await port.byId(ctx.params.id as string)
+    if (!definition) return packageNotFound()
+    return Response.json(toResponse(definition))
+  })
+
+  router.handle('PutPackageCreatedById', async (ctx) => {
+    const result = await port.update(ctx.params.id as string, readInput(await body(ctx)))
+    return writeFailure(result) ?? new Response(null, { status: 200 })
+  })
+
+  router.handle('DeletePackageCreatedById', async (ctx) => {
+    const result = await port.remove(ctx.params.id as string)
+    if (result === 'notFound') return packageNotFound()
+    return new Response(null, { status: 200 })
+  })
+
+  router.handle('GetPackageCreatedByIdDownload', async (ctx) => {
+    const built = await port.build(ctx.params.id as string)
+    if (!built) return packageNotFound()
+    return new Response(built.bytes, {
+      headers: {
+        'content-type': built.contentType,
+        'content-disposition': `attachment; filename="${built.fileName}"`,
+      },
+    })
+  })
+
+  /**
+   * Umbraco's package migrations are C# migrations shipped inside a package.
+   * Nothing carries them here — extensions are client-side and schema changes
+   * travel as TOML through a deploy — so there is never a package with a
+   * pending migration, and saying so is the honest answer rather than a stub.
+   */
+  router.handle('GetPackageMigrationStatus', (ctx) => {
+    if (!parseSkipTake(ctx.url.searchParams).ok) return problemResponse(invalidSkipTake())
+    return Response.json(paged([], 0))
+  })
+
+  router.handle('PostPackageByNameRunMigration', (ctx) =>
+    problemResponse(
+      notFound(
+        'The package could not be found',
+        `No package named '${ctx.params.name}' has migrations to run. Package migrations do not exist in this CMS; schema changes travel as files through a deploy.`,
+      ),
+    ),
+  )
+}

package/src/handlers/public-access.ts

@@ -0,0 +1,107 @@
+/**
+ * Public access: which documents are protected, and by what.
+ *
+ * A rule names member groups **or** individual members, never both — Umbraco
+ * calls the mixture ambiguous and refuses it, and so do we, because the two are
+ * different intentions and the editor offers them as a choice.
+ */
+import { notFound, problemDetails, problemResponse } from '@crombolo/core'
+import type { PublicAccessPort, PublicAccessStatus } from '../ports-members.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+import { readBody } from './document.ts'
+
+const refId = (value: unknown): string | null => {
+  if (!value || typeof value !== 'object') return null
+  const id = (value as Record<string, unknown>).id
+  return typeof id === 'string' && id ? id : null
+}
+
+const names = (value: unknown): string[] =>
+  Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === 'string' && v.trim() !== '')
+    : []
+
+/** Umbraco's `PublicAccessOperationStatus`, as the problem details the client reads. */
+function statusResponse(status: PublicAccessStatus, ok: () => Response): Response {
+  switch (status) {
+    case 'ok':
+      return ok()
+    case 'content-not-found':
+      return problemResponse(notFound('The document could not be found'))
+    case 'login-node-not-found':
+      return problemResponse(notFound('The login page could not be found'))
+    case 'error-node-not-found':
+      return problemResponse(notFound('The error page could not be found'))
+    default:
+      return problemResponse(
+        problemDetails({
+          title: 'Entry not found',
+          detail: 'The specified entry was not found.',
+          status: 404,
+        }),
+      )
+  }
+}
+
+export function registerPublicAccessHandlers(
+  router: ManagementApiRouter,
+  port: PublicAccessPort,
+): void {
+  router.handle('GetDocumentByIdPublicAccess', async (ctx) => {
+    const result = await port.entry(
+      ctx.params.id as string,
+      ctx.url.searchParams.get('includeAncestors') === 'true',
+    )
+    if (result.status !== 'ok' || !result.entry)
+      return statusResponse(result.status, () => new Response(null, { status: 404 }))
+    return Response.json(result.entry)
+  })
+
+  const write = async (ctx: RequestContext, ok: () => Response) => {
+    const body = await readBody(ctx)
+    const login = refId(body.loginDocument)
+    const error = refId(body.errorDocument)
+    if (!login) return problemResponse(notFound('The login page could not be found'))
+    if (!error) return problemResponse(notFound('The error page could not be found'))
+    const memberGroupNames = names(body.memberGroupNames)
+    const memberUserNames = names(body.memberUserNames)
+    if (memberGroupNames.length === 0 && memberUserNames.length === 0)
+      return problemResponse(
+        problemDetails({
+          title: 'No allowed entities given',
+          detail: 'Both MemberGroups and Members were empty, thus no entities can be allowed.',
+          status: 400,
+        }),
+      )
+    if (memberGroupNames.length > 0 && memberUserNames.length > 0)
+      return problemResponse(
+        problemDetails({
+          title: 'Ambiguous Rule',
+          detail:
+            'The specified rule is ambiguous, because both member groups and member names were given.',
+          status: 400,
+        }),
+      )
+    const status = await port.save(ctx.params.id as string, {
+      loginDocumentKey: login,
+      errorDocumentKey: error,
+      memberGroupNames,
+      memberUserNames,
+    })
+    return statusResponse(status, ok)
+  }
+
+  router.handle('PostDocumentByIdPublicAccess', (ctx) =>
+    write(ctx, () => new Response(null, { status: 201 })),
+  )
+  router.handle('PutDocumentByIdPublicAccess', (ctx) =>
+    write(ctx, () => new Response(null, { status: 200 })),
+  )
+
+  router.handle('DeleteDocumentByIdPublicAccess', async (ctx) =>
+    statusResponse(
+      await port.remove(ctx.params.id as string),
+      () => new Response(null, { status: 200 }),
+    ),
+  )
+}

package/src/handlers/published-cache.ts

@@ -0,0 +1,27 @@
+/**
+ * The Published Status dashboard's three buttons. Reload and rebuild answer 200
+ * with no body, and the client polls the rebuild status until it reports it has
+ * finished — which, since a rebuild here completes before the response, it
+ * already has by the first poll.
+ */
+import type { PublishedCachePort } from '../ports.ts'
+import type { ManagementApiRouter } from '../router.ts'
+
+export function registerPublishedCacheHandlers(
+  router: ManagementApiRouter,
+  cache: PublishedCachePort,
+): void {
+  router.handle('PostPublishedCacheReload', () => {
+    cache.reload()
+    return new Response(null, { status: 200 })
+  })
+
+  router.handle('PostPublishedCacheRebuild', async () => {
+    await cache.rebuild()
+    return new Response(null, { status: 200 })
+  })
+
+  router.handle('GetPublishedCacheRebuildStatus', () =>
+    Response.json({ isRebuilding: cache.isRebuilding() }),
+  )
+}

package/src/handlers/redirects.ts

@@ -0,0 +1,78 @@
+/**
+ * The Redirect URL Management dashboard, in the Content section, and the
+ * redirects listed on a page's Info tab.
+ *
+ * Two quirks of the contract are worth naming. `{id}` means the *document* on the
+ * GET and the *redirect* on the DELETE. And `document` is a required field on
+ * every item although the client's own mapper throws it away — a redirect the
+ * site configured towards an external URL names no document, so those report the
+ * empty key rather than inventing one.
+ *
+ * `POST status` is a no-op, as it is in Umbraco since v17: tracking is a
+ * configuration setting, not something an editor toggles.
+ */
+import {
+  invalidSkipTake,
+  paged,
+  parseSkipTake,
+  problemDetails,
+  problemResponse,
+} from '@crombolo/core'
+import type { RedirectListing, RedirectPort } from '../ports-content.ts'
+import type { ManagementApiRouter } from '../router.ts'
+
+const NO_DOCUMENT = '00000000-0000-0000-0000-000000000000'
+
+const toResponse = (item: RedirectListing) => ({
+  id: item.key,
+  originalUrl: item.originalUrl,
+  destinationUrl: item.destinationUrl,
+  created: item.created.toISOString(),
+  document: { id: item.documentKey ?? NO_DOCUMENT },
+  culture: item.culture,
+})
+
+export function registerRedirectHandlers(router: ManagementApiRouter, port: RedirectPort): void {
+  router.handle('GetRedirectManagement', async (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const filter = ctx.url.searchParams.get('filter') ?? undefined
+    const result = await port.list(filter, page.value)
+    return Response.json(paged(result.items.map(toResponse), result.total))
+  })
+
+  router.handle('GetRedirectManagementById', async (ctx) => {
+    const page = parseSkipTake(ctx.url.searchParams)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const result = await port.byDocument(ctx.params.id as string, page.value)
+    return Response.json(paged(result.items.map(toResponse), result.total))
+  })
+
+  router.handle('DeleteRedirectManagementById', async (ctx) => {
+    const result = await port.remove(ctx.params.id as string)
+    if (result === 'notFound')
+      return problemResponse(
+        problemDetails({ title: 'The redirect could not be found', status: 404 }),
+      )
+    if (result === 'configured')
+      return problemResponse(
+        problemDetails({
+          title: 'The redirect is defined in configuration',
+          detail: "Remove it from the site's `redirects` configuration instead.",
+          status: 409,
+        }),
+      )
+    return new Response(null, { status: 200 })
+  })
+
+  router.handle('GetRedirectManagementStatus', (ctx) =>
+    Response.json({
+      status: port.isTracking() ? 'Enabled' : 'Disabled',
+      userIsAdmin: ctx.principal?.isAdmin ?? false,
+    }),
+  )
+
+  // Umbraco deprecated this in v17 and made it a no-op; reporting success without
+  // changing anything is what its own client now expects.
+  router.handle('PostRedirectManagementStatus', () => new Response(null, { status: 200 }))
+}

package/src/handlers/references.ts

@@ -0,0 +1,44 @@
+/**
+ * "What refers to this?" — the Info tab's list, and the checks the client makes
+ * before a delete. These answered an empty page until now, which told an editor
+ * that nothing referenced a document they were about to delete.
+ */
+import { invalidSkipTake, paged, parseSkipTake, problemResponse } from '@crombolo/core'
+import type { ReferencePort } from '../ports-content.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+
+type Area = 'Document' | 'Media' | 'Member' | 'Element'
+
+export function registerReferenceHandlers(
+  router: ManagementApiRouter,
+  area: Area,
+  port: ReferencePort,
+): void {
+  // Umbraco pages these 20 at a time, not the usual 100.
+  const paging = (ctx: RequestContext) => parseSkipTake(ctx.url.searchParams, 20)
+  const has = (id: string) => router.operations.some((o) => o.operationId === id)
+  const handle = (id: string, handler: Parameters<ManagementApiRouter['handle']>[1]) => {
+    if (has(id)) router.handle(id, handler)
+  }
+
+  handle(`Get${area}ByIdReferencedBy`, async (ctx) => {
+    const page = paging(ctx)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const result = await port.referencedBy(ctx.params.id as string, page.value)
+    return Response.json(paged(result.items, result.total))
+  })
+
+  handle(`Get${area}ByIdReferencedDescendants`, async (ctx) => {
+    const page = paging(ctx)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const result = await port.referencedDescendants(ctx.params.id as string, page.value)
+    return Response.json(paged(result.items, result.total))
+  })
+
+  handle(`Get${area}AreReferenced`, async (ctx) => {
+    const page = paging(ctx)
+    if (!page.ok) return problemResponse(invalidSkipTake())
+    const result = await port.areReferenced(ctx.url.searchParams.getAll('id'), page.value)
+    return Response.json(paged(result.items, result.total))
+  })
+}