@crombolo/api-management 0.10.0 → 0.12.1

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,4 +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'
@@ -6,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

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

@@ -18,15 +18,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 {
@@ -111,6 +114,54 @@ export interface PublishedCachePort {
   isRebuilding(): boolean
 }
 
+/** An index as the Examine dashboard lists it. */
+export interface SearchIndexInfo {
+  name: string
+  searcherName: string
+  documentCount: number
+  fieldCount: number
+  /** Items waiting to be indexed; while any are, the index reports itself rebuilding. */
+  pending: number
+}
+
+/** An item's entries in the audit log, for its Info tab. docs/audit-log.md. */
+export interface AuditHistoryPort {
+  forItem(
+    key: string,
+  ): Promise<
+    Array<{ userKey: string | null; occurredAt: Date; action: string; detail: string | null }>
+  >
+  /** When the log began; an item's versions from before then stand in for its entries. */
+  startedAt(): Promise<Date | undefined>
+  /** Entries older than this have been aged out, and versions standing in for them are too. */
+  retainedSince(): Date | undefined
+}
+
+/** The backoffice search index behind the Examine dashboard. docs/search.md. */
+export interface SearchIndexPort {
+  indexes(): Promise<SearchIndexInfo[]>
+  index(name: string): Promise<SearchIndexInfo | undefined>
+  /** False when there is no index by that name. */
+  rebuild(name: string): Promise<boolean>
+  searchers(): string[]
+  /** Undefined when there is no searcher by that name. */
+  query(
+    searcherName: string,
+    term: string,
+    paging: { skip: number; take: number },
+  ): Promise<
+    | {
+        total: number
+        items: Array<{
+          key: string
+          score: number
+          fields: Array<{ name: string; values: string[] }>
+        }>
+      }
+    | undefined
+  >
+}
+
 /** Embed markup for a URL, from its oEmbed provider. */
 export interface OEmbedPort {
   markup(
@@ -122,6 +173,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. */
@@ -185,11 +246,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
@@ -213,6 +277,8 @@ export interface ManagementApiDeps {
   logViewer?: LogViewerPort
   modelsBuilder?: ModelsBuilderPort
   publishedCache?: PublishedCachePort
+  searchIndex?: SearchIndexPort
+  auditHistory?: AuditHistoryPort
   /** The template editor's query builder. */
   templateQuery?: TemplateQueryPort
   memberGroups?: MemberGroupPort
@@ -220,6 +286,8 @@ export interface ManagementApiDeps {
   publicAccess?: PublicAccessPort
   elements?: ElementPort
   references?: ReferencePort
+  relations?: RelationPort
+  webhooks?: WebhookPort
   redirects?: RedirectPort
   packages?: PackagePort
 }