@crombolo/api-management 0.0.0-stage → 0.10.0

package/src/handlers/file-systems.ts

@@ -0,0 +1,207 @@
+/**
+ * Partial views, stylesheets and scripts: one file-system area each, served by
+ * the same handlers — the tree, items, the file and its folders — keyed by path.
+ */
+import {
+  invalidSkipTake,
+  notFound,
+  paged,
+  parseSkipTake,
+  problemDetails,
+  problemResponse,
+} from '@crombolo/core'
+import type { FileEntry, FileResult, FileStatus, FileSystemPort, Snippet } from '../ports-files.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+
+export type FileArea = 'PartialView' | 'Stylesheet' | 'Script'
+
+const LABEL: Record<FileArea, string> = {
+  PartialView: 'Partial view',
+  Stylesheet: 'Stylesheet',
+  Script: 'Script',
+}
+const ROUTE: Record<FileArea, string> = {
+  PartialView: 'partial-view',
+  Stylesheet: 'stylesheet',
+  Script: 'script',
+}
+
+const parentRef = (parentPath: string | null) => (parentPath ? { path: parentPath } : null)
+
+const treeItem = (entry: FileEntry) => ({
+  name: entry.name,
+  path: entry.path,
+  parent: parentRef(entry.parentPath),
+  isFolder: entry.isFolder,
+  hasChildren: entry.hasChildren,
+})
+
+function failure(area: FileArea, status: FileStatus, folder = false): Response {
+  const thing = folder ? 'Folder' : LABEL[area]
+  const [code, title] = (
+    {
+      AlreadyExists: [400, `${thing} already exists`],
+      NotFound: [404, `${thing} not found`],
+      ParentNotFound: [404, 'Parent not found'],
+      InvalidName: [400, 'Invalid name'],
+      InvalidFileExtension: [400, 'Invalid file extension'],
+      NotEmpty: [400, 'Folder is not empty'],
+    } as const
+  )[status]
+  return problemResponse(problemDetails({ title, status: code, operationStatus: status }))
+}
+
+async function body(ctx: RequestContext): Promise<Record<string, unknown>> {
+  return ((await ctx.request.json().catch(() => ({}))) ?? {}) as Record<string, unknown>
+}
+
+const parentPathOf = (value: unknown): string | null => {
+  const path = (value as { path?: unknown } | null | undefined)?.path
+  return typeof path === 'string' && path !== '' && path !== '/' ? path : null
+}
+
+export function registerFileSystemHandlers(
+  router: ManagementApiRouter,
+  area: FileArea,
+  port: FileSystemPort,
+  snippets: readonly Snippet[] = [],
+): void {
+  const base = `/umbraco/management/api/v1/${ROUTE[area]}`
+  const created = (ctx: RequestContext, path: string, folder = false) =>
+    new Response(null, {
+      status: 201,
+      headers: {
+        location: `${ctx.url.origin}${base}${folder ? '/folder' : ''}/${encodeURIComponent(path)}`,
+        'umb-generated-resource': encodeURIComponent(path),
+      },
+    })
+  const result = (ctx: RequestContext, outcome: FileResult, create: boolean, folder = false) => {
+    if (!outcome.ok) return failure(area, outcome.status, folder)
+    return create ? created(ctx, outcome.path, folder) : new Response(null, { status: 200 })
+  }
+  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(`GetTree${area}Root`, async (ctx) => page(ctx, await port.children(null)))
+  router.handle(`GetTree${area}Children`, async (ctx) =>
+    page(ctx, await port.children(ctx.url.searchParams.get('parentPath') || null)),
+  )
+  router.handle(`GetTree${area}Ancestors`, async (ctx) => {
+    const path = ctx.url.searchParams.get('descendantPath')
+    const chain: FileEntry[] = []
+    let current = path ? await port.entry(path) : undefined
+    while (current) {
+      chain.unshift(current)
+      current = current.parentPath ? await port.entry(current.parentPath) : undefined
+    }
+    return Response.json(chain.map(treeItem))
+  })
+  router.handle(`GetTree${area}Siblings`, async (ctx) => {
+    const path = ctx.url.searchParams.get('path') ?? ''
+    const target = await port.entry(path)
+    // As the tree answers for a path it cannot find: no siblings
+    if (!target) return Response.json({ totalBefore: 0, totalAfter: 0, items: [] })
+    const siblings = (await port.children(target.parentPath)) ?? []
+    const index = siblings.findIndex((s) => s.path === target.path)
+    const before = Math.max(0, Number(ctx.url.searchParams.get('before') ?? 0))
+    const after = Math.max(0, Number(ctx.url.searchParams.get('after') ?? 0))
+    const from = Math.max(0, index - before)
+    return Response.json({
+      totalBefore: from,
+      totalAfter: Math.max(0, siblings.length - (index + after + 1)),
+      items: siblings.slice(from, index + after + 1).map(treeItem),
+    })
+  })
+
+  router.handle(`GetItem${area}`, async (ctx) => {
+    const items = []
+    for (const path of ctx.url.searchParams.getAll('path')) {
+      const entry = await port.entry(path)
+      if (entry)
+        items.push({
+          isFolder: entry.isFolder,
+          name: entry.name,
+          parent: parentRef(entry.parentPath),
+          path: entry.path,
+        })
+    }
+    return Response.json(items)
+  })
+
+  router.handle(`Get${area}ByPath`, async (ctx) => {
+    const file = await port.read(ctx.params.path as string)
+    if (!file) return failure(area, 'NotFound')
+    return Response.json({
+      name: file.name,
+      path: file.path,
+      parent: parentRef(file.parentPath),
+      content: file.content,
+    })
+  })
+  router.handle(`Post${area}`, async (ctx) => {
+    const b = await body(ctx)
+    const outcome = await port.create(
+      parentPathOf(b.parent),
+      String(b.name ?? ''),
+      typeof b.content === 'string' ? b.content : '',
+    )
+    return result(ctx, outcome, true)
+  })
+  router.handle(`Put${area}ByPath`, async (ctx) => {
+    const b = await body(ctx)
+    const content = typeof b.content === 'string' ? b.content : ''
+    return result(ctx, await port.update(ctx.params.path as string, content), false)
+  })
+  router.handle(`Put${area}ByPathRename`, async (ctx) => {
+    const b = await body(ctx)
+    return result(ctx, await port.rename(ctx.params.path as string, String(b.name ?? '')), true)
+  })
+  router.handle(`Delete${area}ByPath`, async (ctx) =>
+    result(ctx, await port.delete(ctx.params.path as string), false),
+  )
+
+  router.handle(`Post${area}Folder`, async (ctx) => {
+    const b = await body(ctx)
+    return result(
+      ctx,
+      await port.createFolder(parentPathOf(b.parent), String(b.name ?? '')),
+      true,
+      true,
+    )
+  })
+  router.handle(`Get${area}FolderByPath`, async (ctx) => {
+    const entry = await port.entry(ctx.params.path as string)
+    if (!entry?.isFolder) return failure(area, 'NotFound', true)
+    return Response.json({
+      name: entry.name,
+      path: entry.path,
+      parent: parentRef(entry.parentPath),
+    })
+  })
+  router.handle(`Delete${area}FolderByPath`, async (ctx) =>
+    result(ctx, await port.deleteFolder(ctx.params.path as string), false, true),
+  )
+
+  if (area !== 'PartialView') return
+  router.handle('GetPartialViewSnippet', (ctx) => {
+    const parsed = parseSkipTake(ctx.url.searchParams)
+    if (!parsed.ok) return problemResponse(invalidSkipTake())
+    const { skip, take } = parsed.value
+    return Response.json(
+      paged(
+        snippets.slice(skip, skip + take).map((s) => ({ id: s.id, name: s.name })),
+        snippets.length,
+      ),
+    )
+  })
+  router.handle('GetPartialViewSnippetById', (ctx) => {
+    const snippet = snippets.find((s) => s.id === ctx.params.id)
+    if (!snippet) return problemResponse(notFound('Snippet not found'))
+    return Response.json(snippet)
+  })
+}

package/src/handlers/import.ts

@@ -0,0 +1,46 @@
+/**
+ * What an uploaded file turns out to be, which the client asks before it offers
+ * to import: the entity type, and the alias and key inside the file so it can
+ * tell a new type from an update to an existing one.
+ */
+import { notFound, problemDetails, problemResponse } from '@crombolo/core'
+import type { TemporaryFilePort } from '../ports.ts'
+import type { ManagementApiRouter } from '../router.ts'
+
+/** The root element names Umbraco's `.udt` exports use, to their entity types. */
+const ENTITY_OF: Record<string, string> = {
+  documenttype: 'document-type',
+  mediatype: 'media-type',
+  membertype: 'member-type',
+  datatype: 'data-type',
+  dictionaryitem: 'dictionary-item',
+}
+
+export function registerImportHandlers(
+  router: ManagementApiRouter,
+  temporaryFiles: TemporaryFilePort,
+): void {
+  router.handle('GetImportAnalyze', async (ctx) => {
+    const id = ctx.url.searchParams.get('temporaryFileId')
+    if (!id)
+      return problemResponse(
+        problemDetails({ title: 'A temporary file id is required', status: 400 }),
+      )
+    const file = await temporaryFiles.read(id)
+    if (!file) return problemResponse(notFound('The file could not be found'))
+    const text = new TextDecoder().decode(file.bytes)
+    const root = /<\s*([A-Za-z][\w.-]*)/.exec(text.replace(/<\?[^?]*\?>/g, ''))?.[1]
+    const entityType = root ? ENTITY_OF[root.toLowerCase()] : undefined
+    if (!entityType)
+      return problemResponse(
+        problemDetails({
+          title: 'The file could not be read',
+          detail: 'It is not an Umbraco export.',
+          status: 400,
+        }),
+      )
+    const inside = (name: string) =>
+      new RegExp(`<${name}>([^<]*)</${name}>`, 'i').exec(text)?.[1]?.trim() || null
+    return Response.json({ entityType, alias: inside('Alias'), key: inside('Key') })
+  })
+}

package/src/handlers/localization.ts

@@ -0,0 +1,116 @@
+/**
+ * Cultures and languages. UI translation strings are client-side manifests, not
+ * server endpoints — these describe which cultures exist, not what words mean.
+ */
+import {
+  invalidSkipTake,
+  notFound,
+  paged,
+  parseSkipTake,
+  problemDetails,
+  problemResponse,
+} from '@crombolo/core'
+import type { LanguageInput, LocalizationPort } from '../ports.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+
+/** Applies Umbraco's paging contract, including the skip-multiple-of-take rule. */
+function pageOf<T>(ctx: RequestContext, items: readonly T[]): Response {
+  const skipTake = parseSkipTake(ctx.url.searchParams)
+  if (!skipTake.ok) return problemResponse(invalidSkipTake())
+  const { skip, take } = skipTake.value
+  const window = take === 0 ? [] : items.slice(skip, skip + take)
+  return Response.json(paged([...window], items.length))
+}
+
+export function registerLocalizationHandlers(
+  router: ManagementApiRouter,
+  localization: LocalizationPort,
+): void {
+  router.handle('GetCulture', (ctx) => pageOf(ctx, localization.cultures()))
+  // Segments come from a segment provider; like Umbraco without one, there are none
+  router.handle('GetSegment', (ctx) => pageOf(ctx, []))
+  router.handle('GetDocumentByIdAvailableSegmentOptions', (ctx) => pageOf(ctx, []))
+  router.handle('GetLanguage', async (ctx) => pageOf(ctx, await localization.allLanguages()))
+  router.handle('GetItemLanguageDefault', async () => {
+    const languages = await localization.allLanguages()
+    const fallback = languages.find((l) => l.isDefault) ?? languages[0]
+    return Response.json(
+      fallback ?? {
+        isoCode: 'en-US',
+        name: 'English (United States)',
+        isDefault: true,
+        isMandatory: true,
+        fallbackIsoCode: null,
+      },
+    )
+  })
+  router.handle('GetItemLanguage', async (ctx) => {
+    const wanted = new Set(ctx.url.searchParams.getAll('isoCode').map((c) => c.toLowerCase()))
+    const languages = await localization.allLanguages()
+    return Response.json(
+      languages
+        .filter((l) => wanted.size === 0 || wanted.has(l.isoCode.toLowerCase()))
+        .map((l) => ({ name: l.name, isoCode: l.isoCode })),
+    )
+  })
+  router.handle('GetLanguageByIsoCode', async ({ params }) => {
+    const language = await localization.language(params.isoCode as string)
+    if (!language) return problemResponse(notFound('The language could not be found'))
+    return Response.json(language)
+  })
+  router.handle('PostLanguage', async (ctx) => {
+    const body = (await ctx.request.json()) as Record<string, unknown>
+    const isoCode = String(body.isoCode ?? '')
+    if (!isoCode)
+      return problemResponse(problemDetails({ title: 'isoCode is required', status: 400 }))
+    if (await localization.language(isoCode))
+      return problemResponse(
+        problemDetails({
+          title: 'The language already exists',
+          status: 400,
+          operationStatus: 'DuplicateIsoCode',
+        }),
+      )
+    await localization.saveLanguage(readLanguage(isoCode, body))
+    ctx.notifications.push({ message: 'Language created', category: 'Language', type: 'Success' })
+    return new Response(null, {
+      status: 201,
+      headers: { location: `${ctx.url.origin}/umbraco/management/api/v1/language/${isoCode}` },
+    })
+  })
+  router.handle('PutLanguageByIsoCode', async (ctx) => {
+    const isoCode = ctx.params.isoCode as string
+    const existing = await localization.language(isoCode)
+    if (!existing) return problemResponse(notFound('The language could not be found'))
+    const body = (await ctx.request.json()) as Record<string, unknown>
+    await localization.saveLanguage(readLanguage(existing.isoCode, body))
+    ctx.notifications.push({ message: 'Language saved', category: 'Language', type: 'Success' })
+    return new Response(null, { status: 200 })
+  })
+  router.handle('DeleteLanguageByIsoCode', async (ctx) => {
+    const result = await localization.deleteLanguage(ctx.params.isoCode as string)
+    if (result === 'not-found') return problemResponse(notFound('The language could not be found'))
+    if (result !== 'deleted')
+      return problemResponse(
+        problemDetails({
+          title:
+            result === 'default'
+              ? 'The default language cannot be deleted'
+              : 'Another language falls back to this one',
+          status: 400,
+        }),
+      )
+    ctx.notifications.push({ message: 'Language deleted', category: 'Language', type: 'Success' })
+    return new Response(null, { status: 200 })
+  })
+}
+
+function readLanguage(isoCode: string, body: Record<string, unknown>): LanguageInput {
+  return {
+    isoCode,
+    name: String(body.name ?? isoCode),
+    isDefault: body.isDefault === true,
+    isMandatory: body.isMandatory === true,
+    fallbackIsoCode: typeof body.fallbackIsoCode === 'string' ? body.fallbackIsoCode : null,
+  }
+}

package/src/handlers/log-viewer.ts

@@ -0,0 +1,125 @@
+/**
+ * The log viewer: levels, level counts, message templates, the log itself and
+ * saved searches, with Umbraco's defaults — the last day when either date is
+ * missing, 100 per page, newest first — and its size check before any read.
+ */
+import {
+  invalidSkipTake,
+  notFound,
+  paged,
+  parseSkipTake,
+  problemDetails,
+  problemResponse,
+} from '@crombolo/core'
+import type { LogLevelName, LogRange, LogViewerPort } from '../ports-logs.ts'
+import type { ManagementApiRouter, RequestContext } from '../router.ts'
+
+const LEVELS: readonly LogLevelName[] = [
+  'Verbose',
+  'Debug',
+  'Information',
+  'Warning',
+  'Error',
+  'Fatal',
+]
+
+const tooLarge = () =>
+  problemResponse(
+    problemDetails({
+      title: 'Cancelled due to log file size',
+      detail: 'The log file size for the requested date range prevented the operation.',
+      status: 400,
+      operationStatus: 'CancelledByLogsSizeValidation',
+    }),
+  )
+
+function dateParam(ctx: RequestContext, name: string): Date | null {
+  const value = ctx.url.searchParams.get(name)
+  if (!value) return null
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+const rangeOf = (ctx: RequestContext): LogRange => ({
+  start: dateParam(ctx, 'startDate'),
+  end: dateParam(ctx, 'endDate'),
+})
+
+function page<T>(ctx: RequestContext, items: readonly T[]): Response {
+  const parsed = parseSkipTake(ctx.url.searchParams)
+  if (!parsed.ok) return problemResponse(invalidSkipTake())
+  const { skip, take } = parsed.value
+  return Response.json(paged(items.slice(skip, skip + take), items.length))
+}
+
+export function registerLogViewerHandlers(router: ManagementApiRouter, logs: LogViewerPort): void {
+  router.handle('GetLogViewerLevel', (ctx) => page(ctx, logs.loggers()))
+
+  router.handle('GetLogViewerValidateLogsSize', async (ctx) =>
+    (await logs.canView(rangeOf(ctx))) ? new Response(null, { status: 200 }) : tooLarge(),
+  )
+
+  router.handle('GetLogViewerLevelCount', async (ctx) => {
+    const range = rangeOf(ctx)
+    if (!(await logs.canView(range))) return tooLarge()
+    return Response.json(await logs.levelCounts(range))
+  })
+
+  router.handle('GetLogViewerMessageTemplate', async (ctx) => {
+    const range = rangeOf(ctx)
+    if (!(await logs.canView(range))) return tooLarge()
+    return page(ctx, await logs.templates(range))
+  })
+
+  router.handle('GetLogViewerLog', async (ctx) => {
+    const range = rangeOf(ctx)
+    if (!(await logs.canView(range))) return tooLarge()
+    const q = ctx.url.searchParams
+    const levels = q
+      .getAll('logLevel')
+      .filter((l): l is LogLevelName => LEVELS.includes(l as LogLevelName))
+    const entries = await logs.logs(range, {
+      filter: q.get('filterExpression'),
+      levels,
+      direction: q.get('orderDirection') === 'Ascending' ? 'Ascending' : 'Descending',
+    })
+    return page(ctx, entries)
+  })
+
+  router.handle('GetLogViewerSavedSearch', async (ctx) => page(ctx, await logs.savedSearches()))
+
+  router.handle('GetLogViewerSavedSearchByName', async (ctx) => {
+    const found = await logs.savedSearch(ctx.params.name as string)
+    if (!found) return problemResponse(notFound('The saved search could not be found'))
+    return Response.json(found)
+  })
+
+  router.handle('PostLogViewerSavedSearch', async (ctx) => {
+    const body = ((await ctx.request.json().catch(() => ({}))) ?? {}) as Record<string, unknown>
+    const name = typeof body.name === 'string' ? body.name.trim() : ''
+    const query = typeof body.query === 'string' ? body.query : ''
+    if (!name) return problemResponse(problemDetails({ title: 'A name is required', status: 400 }))
+    if ((await logs.saveSearch(name, query)) === 'duplicate')
+      return problemResponse(
+        problemDetails({
+          title: 'Duplicate log search name',
+          detail: 'Another log search already exists with the same name.',
+          status: 400,
+          operationStatus: 'DuplicateLogSearch',
+        }),
+      )
+    return new Response(null, {
+      status: 201,
+      headers: {
+        location: `${ctx.url.origin}/umbraco/management/api/v1/log-viewer/saved-search/${encodeURIComponent(name)}`,
+        'umb-generated-resource': name,
+      },
+    })
+  })
+
+  router.handle('DeleteLogViewerSavedSearchByName', async (ctx) =>
+    (await logs.deleteSearch(ctx.params.name as string))
+      ? new Response(null, { status: 200 })
+      : problemResponse(notFound('The saved search could not be found')),
+  )
+}

package/src/handlers/manifest.ts

@@ -0,0 +1,15 @@
+/**
+ * Extension discovery. `/public` is anonymous and feeds the login screen;
+ * `/private` requires a signed-in user and carries the rest.
+ */
+import type { ManifestPort } from '../ports.ts'
+import type { ManagementApiRouter } from '../router.ts'
+
+export function registerManifestHandlers(
+  router: ManagementApiRouter,
+  manifests: ManifestPort,
+): void {
+  router.handle('GetManifestManifest', () => Response.json(manifests.list('all')))
+  router.handle('GetManifestManifestPublic', () => Response.json(manifests.list('public')))
+  router.handle('GetManifestManifestPrivate', () => Response.json(manifests.list('private')))
+}