@crombolo/api-management 0.16.0 → 0.17.0

package/package.json

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

package/src/handlers/document.ts

@@ -847,7 +847,16 @@ export function registerDocumentHandlers(
       ctx.principal as NonNullable<typeof ctx.principal>,
       ids,
     )
-    if (!saved) return problemResponse(notFound('The document could not be found'))
+    if (saved === 'notFound') return problemResponse(notFound('The document could not be found'))
+    if (saved === 'unavailable')
+      return problemResponse(
+        problemDetails({
+          title: 'Notifications are unavailable',
+          status: 400,
+          detail:
+            "This site can't send e-mail yet, so it can't tell you when pages change. Ask an administrator to set up e-mail.",
+        }),
+      )
     return done(ctx, 'Notification settings saved')
   })
 

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './handlers/package.ts'
 export * from './handlers/settings-stubs.ts'
 export * from './handlers/template-query.ts'
 export * from './handlers/user.ts'
+export * from './notification-events.ts'
 export * from './ports.ts'
 export * from './ports-content.ts'
 export * from './ports-diagnostics.ts'

package/src/notification-events.ts

@@ -0,0 +1,103 @@
+/**
+ * Which of Umbraco's eleven notification actions a Management API operation
+ * performs, and on which item (story 045). Pure: the router hands the server
+ * what it says, and the server finds who asked to hear of it.
+ */
+
+/** What a successful operation did, for the people subscribed to its page. */
+export interface RaisedContentChange {
+  /** `Umb.Document.Publish` and the rest; create-and-publish is two. */
+  actions: string[]
+  /** The item it names: a document's key, or for a rollback the version's. */
+  key: string
+  keyKind: 'document' | 'version'
+  /** A branch publish: one change for the page, "and the pages under it". */
+  withDescendants?: boolean
+}
+
+interface Mapping {
+  actions: string[]
+  from: 'created' | 'id' | 'body-parent'
+  /** A publish that only sets a schedule publishes nothing yet: the job notifies when it does. */
+  scheduleOnly?: boolean
+  keyKind?: 'document' | 'version'
+  withDescendants?: boolean
+}
+
+const CREATE = 'Umb.Document.Create'
+const UPDATE = 'Umb.Document.Update'
+const PUBLISH = 'Umb.Document.Publish'
+
+const BY_OPERATION: Record<string, Mapping> = {
+  PostDocument: { actions: [CREATE], from: 'created' },
+  PostDocumentCreateAndPublish: { actions: [CREATE, PUBLISH], from: 'created' },
+  PutDocumentById: { actions: [UPDATE], from: 'id' },
+  PutDocumentByIdUpdateAndPublish: { actions: [UPDATE, PUBLISH], from: 'id' },
+  PutDocumentByIdPublish: { actions: [PUBLISH], from: 'id', scheduleOnly: true },
+  PutDocumentByIdPublishWithDescendants: {
+    actions: [PUBLISH],
+    from: 'id',
+    withDescendants: true,
+  },
+  PutDocumentByIdMoveToRecycleBin: { actions: ['Umb.Document.Delete'], from: 'id' },
+  PutDocumentByIdMove: { actions: ['Umb.Document.Move'], from: 'id' },
+  // Notified on the original, as Umbraco does.
+  PostDocumentByIdCopy: { actions: ['Umb.Document.Duplicate'], from: 'id' },
+  // Notified on the parent whose children were sorted; sorting at the root notifies nobody.
+  PutDocumentByIdSortChildren: { actions: ['Umb.Document.Sort'], from: 'id' },
+  PutDocumentSort: { actions: ['Umb.Document.Sort'], from: 'body-parent' },
+  PostDocumentVersionByIdRollback: {
+    actions: ['Umb.Document.Rollback'],
+    from: 'id',
+    keyKind: 'version',
+  },
+  PutRecycleBinDocumentByIdRestore: { actions: ['Umb.DocumentRecycleBin.Restore'], from: 'id' },
+  PostDocumentByIdPublicAccess: { actions: ['Umb.Document.PublicAccess'], from: 'id' },
+  PutDocumentByIdPublicAccess: { actions: ['Umb.Document.PublicAccess'], from: 'id' },
+  DeleteDocumentByIdPublicAccess: { actions: ['Umb.Document.PublicAccess'], from: 'id' },
+}
+
+/** Whether the router has to keep the request body for this operation. */
+export const changeReadsBody = (operationId: string): boolean =>
+  BY_OPERATION[operationId]?.from === 'body-parent' ||
+  BY_OPERATION[operationId]?.scheduleOnly === true
+
+/** Whether every culture in a publish request is scheduled for later rather than published now. */
+const onlySchedules = (body: unknown): boolean => {
+  const schedules = (
+    body as { publishSchedules?: Array<{ schedule?: { publishTime?: unknown } | null }> }
+  )?.publishSchedules
+  return (
+    Array.isArray(schedules) &&
+    schedules.length > 0 &&
+    schedules.every((entry) => Boolean(entry?.schedule?.publishTime))
+  )
+}
+
+/** The change a successful operation made, if it is one anybody can subscribe to. */
+export function contentChangeFor(
+  operationId: string,
+  params: Readonly<Record<string, string>>,
+  response: Pick<Response, 'status' | 'headers'>,
+  body: unknown,
+): RaisedContentChange | undefined {
+  if (response.status < 200 || response.status >= 300) return undefined
+  const mapping = BY_OPERATION[operationId]
+  if (!mapping) return undefined
+  if (mapping.scheduleOnly && onlySchedules(body)) return undefined
+  const key =
+    mapping.from === 'created'
+      ? response.headers.get('umb-generated-resource')
+      : mapping.from === 'body-parent'
+        ? ((body as { parent?: { id?: unknown } | null } | undefined)?.parent?.id as
+            | string
+            | undefined)
+        : params.id
+  if (!key) return undefined
+  return {
+    actions: mapping.actions,
+    key: key.toLowerCase(),
+    keyKind: mapping.keyKind ?? 'document',
+    ...(mapping.withDescendants ? { withDescendants: true } : {}),
+  }
+}

package/src/ports-content.ts

@@ -370,7 +370,15 @@ export interface DocumentPort extends TreePort {
     key: string,
     principal: Principal,
   ): Promise<Array<{ actionId: string; alias: string; subscribed: boolean }> | undefined>
-  setNotifications(key: string, principal: Principal, actionIds: string[]): Promise<boolean>
+  /**
+   * Replaces the user's subscriptions. `unavailable` refuses a new one on a
+   * site that cannot send e-mail; clearing them is always allowed.
+   */
+  setNotifications(
+    key: string,
+    principal: Principal,
+    actionIds: string[],
+  ): Promise<'saved' | 'notFound' | 'unavailable'>
   /** The document as it stood at a version. */
   atVersion(
     versionId: string,

package/src/router.ts

@@ -25,6 +25,11 @@ import {
   auditReadsBody,
 } from './audit.ts'
 import { authorize, LOCAL_LOGIN_OPERATIONS, type NodeLookup } from './authorization.ts'
+import {
+  changeReadsBody,
+  contentChangeFor,
+  type RaisedContentChange,
+} from './notification-events.ts'
 import { type ServerEvent, serverEventFor } from './server-events.ts'
 import { type RaisedWebhookEvent, webhookEventFor } from './webhook-events.ts'
 
@@ -94,6 +99,8 @@ export interface RouterOptions {
   onError?: (error: unknown) => Response | undefined
   /** Told about every webhook event a successful operation raises. */
   onWebhookEvent?: (event: RaisedWebhookEvent) => void
+  /** A change to a page that people can subscribe to, and who made it (story 045). */
+  onContentChange?: (change: RaisedContentChange, principal: Principal | undefined) => void
 }
 
 export interface ClientAddress {
@@ -130,6 +137,7 @@ export class ManagementApiRouter {
   readonly #clientAddress: (request: Request) => ClientAddress
   readonly #onError: RouterOptions['onError']
   readonly #onWebhookEvent: RouterOptions['onWebhookEvent']
+  readonly #onContentChange: RouterOptions['onContentChange']
 
   constructor(options: RouterOptions = {}) {
     const operations = options.operations ?? listOperations(loadSpec())
@@ -143,6 +151,7 @@ export class ManagementApiRouter {
     this.#clientAddress = options.clientAddress ?? forwardedOnly
     this.#onError = options.onError
     this.#onWebhookEvent = options.onWebhookEvent
+    this.#onContentChange = options.onContentChange
     for (const operation of operations) {
       const segments = operation.path.split('/').filter((s) => s.length > 0)
       const paramNames = segments.map((s) =>
@@ -242,6 +251,13 @@ export class ManagementApiRouter {
     if (!handler) this.#onNotImplemented?.(operation, request)
     const plan = handler && this.#audit ? auditPlanFor(operation.operationId) : undefined
     const audit = plan ? await this.#beforeAudit(plan, params, request) : undefined
+    const changeBody =
+      handler && this.#onContentChange && changeReadsBody(operation.operationId)
+        ? await request
+            .clone()
+            .json()
+            .catch(() => undefined)
+        : undefined
     const response = handler
       ? await this.#run(handler, { request, url, params, operation, notifications, principal })
       : problemResponse(notImplemented(operation.operationId))
@@ -255,6 +271,10 @@ export class ManagementApiRouter {
       const event = webhookEventFor(operation.operationId, params, response)
       if (event) this.#onWebhookEvent(event)
     }
+    if (handler && this.#onContentChange) {
+      const change = contentChangeFor(operation.operationId, params, response, changeBody)
+      if (change) this.#onContentChange(change, principal)
+    }
     const headers = new Headers(response.headers)
     applyNotifications(headers, request.method, notifications)
     headers.set('cache-control', 'no-store')

package/src/routes.ts

@@ -57,6 +57,7 @@ export interface ManagementApiOptions {
   clientAddress?: RouterOptions['clientAddress']
   onError?: RouterOptions['onError']
   onWebhookEvent?: RouterOptions['onWebhookEvent']
+  onContentChange?: RouterOptions['onContentChange']
 }
 
 export function createManagementApiRouter(options: ManagementApiOptions = {}): ManagementApiRouter {
@@ -70,6 +71,7 @@ export function createManagementApiRouter(options: ManagementApiOptions = {}): M
     clientAddress: options.clientAddress,
     onError: options.onError,
     onWebhookEvent: options.onWebhookEvent,
+    onContentChange: options.onContentChange,
   })
   const { deps } = options
   if (!deps) return router