@crombolo/server 0.16.0 → 0.18.0

package/src/index.ts

@@ -25,6 +25,7 @@ export * from './bundles.ts'
 export * from './busy.ts'
 export * from './components.ts'
 export * from './config.ts'
+export * from './content-notifications.ts'
 export * from './content-type-udt.ts'
 export * from './database.ts'
 export * from './diagnostics.ts'
@@ -37,6 +38,7 @@ export * from './email-notice.ts'
 export * from './email-postmark.ts'
 export * from './email-resend.ts'
 export * from './email-ses.ts'
+export * from './email-text.ts'
 export * from './extensions-notice.ts'
 export * from './external-sign-in.ts'
 export * from './file-intake.ts'
@@ -76,6 +78,7 @@ export * from './secrets.ts'
 export * from './seo.ts'
 export * from './server.ts'
 export * from './server-events.ts'
+export * from './settings.ts'
 export * from './setup.ts'
 export * from './site-file.ts'
 export * from './site-replace.ts'

package/src/jobs.ts

@@ -1,9 +1,11 @@
 /**
  * Background jobs, as Umbraco runs them: scheduled publishing every minute and
  * version cleanup every hour when it is enabled, plus the search indexer
- * draining its queue and the audit log ageing out old entries hourly. Each run can also be called directly, which is
- * how tests drive them. On a multi-node Postgres site every node runs them;
- * each schedule and queued item is claimed atomically, so it runs once.
+ * draining its queue, the audit log ageing out old entries hourly, and the
+ * form, webhook and content notification queues. Each run can also be called
+ * directly, which is how tests drive them. Every node that owns writes (`all`
+ * and `api`) runs them; each schedule and queued item is claimed atomically, so
+ * it runs once.
  */
 
 import type { NodeSchemaState } from '@crombolo/data'
@@ -16,6 +18,11 @@ import {
 } from '@crombolo/data'
 import type { PublishedCache } from '@crombolo/render'
 import { auditRetainedSince, recordAudit } from './adapters/audit.ts'
+import type {
+  ContentNotificationRunner,
+  ContentNotificationRunReport,
+  ContentNotifier,
+} from './content-notifications.ts'
 import type { WorkflowRunner, WorkflowRunReport } from './form-workflows.ts'
 import { logger } from './logging.ts'
 import type { MediaFileStore } from './media-files.ts'
@@ -49,6 +56,11 @@ export interface JobsOptions {
   searchIndexingMs?: number
   /** Days the audit log keeps an entry; 0 or absent keeps them forever. */
   auditRetentionDays?: number
+  /** Content notifications (story 045): queued by changes, sent here. Absent without e-mail. */
+  contentNotifications?: ContentNotificationRunner
+  contentNotificationsMs?: number
+  /** Queues the notifications scheduled publishing makes, as an editor's publish does. */
+  notifier?: ContentNotifier
 }
 
 export interface ScheduledRun {
@@ -63,6 +75,8 @@ export interface BackgroundJobs {
   runFormWorkflows(now?: Date): Promise<WorkflowRunReport>
   /** Delivers the webhook and bundle events that are due. */
   runWebhooks(now?: Date): Promise<WorkflowRunReport>
+  /** Sends the content notifications that are due (story 045). */
+  runContentNotifications(now?: Date): Promise<ContentNotificationRunReport>
   /** Indexes every queued item, and returns how many. docs/search.md. */
   runSearchIndexing(): Promise<number>
   /** Something was queued here: index it shortly, rather than at the next tick. */
@@ -115,13 +129,24 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
       }
     }
     if (run.published.length + run.unpublished.length > 0) options.cache.invalidate()
-    for (const key of run.published)
+    for (const key of run.published) {
       await options.webhooks?.raise({ alias: 'Umbraco.ContentPublish', key })
+      await options.notifier?.raise(
+        { actions: ['Umb.Document.Publish'], key, keyKind: 'document' },
+        { key: null, name: 'The schedule' },
+        'scheduled',
+      )
+    }
     for (const key of run.unpublished)
       await options.webhooks?.raise({ alias: 'Umbraco.ContentUnpublish', key })
     return run
   }
 
+  async function runContentNotifications(now = new Date()): Promise<ContentNotificationRunReport> {
+    const runner = options.contentNotifications
+    return runner ? runner.runDue(now) : { claimed: 0, sent: 0, skipped: 0, retrying: 0, failed: 0 }
+  }
+
   async function runAuditRetention(now = new Date()): Promise<number> {
     const before = auditRetainedSince(options.auditRetentionDays ?? 0, now)
     return before ? new AuditLog(options.db).prune(before) : 0
@@ -184,6 +209,7 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
     runAuditRetention,
     runFormWorkflows,
     runWebhooks,
+    runContentNotifications,
     runSearchIndexing,
     kickSearchIndexing() {
       if (timers.length === 0 || kicked) return
@@ -204,6 +230,12 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
       if (options.formWorkflows) every(options.formWorkflowsMs ?? 15_000, runFormWorkflows)
       // As often, for the same reason: a receiver that is waiting notices a minute.
       if (options.webhooks) every(options.webhooksMs ?? 15_000, runWebhooks)
+      // A digest waits a minute anyway; this is how soon after that it goes.
+      const notifications = options.contentNotifications
+      if (notifications) {
+        every(options.contentNotificationsMs ?? 15_000, runContentNotifications)
+        every(60 * 60_000, () => notifications.prune(new Date(Date.now() - 30 * 86_400_000)))
+      }
       if (options.versionCleanup.enabled) every(60 * 60_000, runVersionCleanup)
       if (options.auditRetentionDays) every(60 * 60_000, runAuditRetention)
       const files = options.mediaFiles

package/src/ports.ts

@@ -74,6 +74,7 @@ import { createWebhookPort } from './adapters/webhooks.ts'
 import { createApprovals } from './approvals.ts'
 import { COMPONENT_SNIPPETS } from './component-snippets.ts'
 import { type CromboloConfig, type UserLinkSender, VERSION } from './config.ts'
+import type { ContentNotifier } from './content-notifications.ts'
 import { type EmailPort, resolveEmailPort } from './email.ts'
 import { createFileIntake } from './file-intake.ts'
 import { formTypesFor } from './form-types.ts'
@@ -405,6 +406,26 @@ export interface DepsOptions {
   onViewsChange?: (alias: string) => void | Promise<void>
   /** Items were queued for the search index; the indexer can start on them now. */
   onSearchQueued?: () => void
+  /** Queues content notifications for changes made outside the router (story 045). */
+  notifier?: ContentNotifier
+}
+
+/** The back office's address, e.g. `https://site.example/crombolo`; undefined when the site's own is not set. */
+export function backOfficeUrl(
+  config: Pick<CromboloConfig, 'applicationUrl' | 'backOfficePath'>,
+): string | undefined {
+  return config.applicationUrl
+    ? `${config.applicationUrl.replace(/\/$/, '')}${config.backOfficePath}`
+    : undefined
+}
+
+/** A page's address in the back office, for a link in an e-mail. */
+export function documentEditUrl(
+  config: Pick<CromboloConfig, 'applicationUrl' | 'backOfficePath'>,
+  key: string,
+): string | undefined {
+  const base = backOfficeUrl(config)
+  return base ? `${base}/section/content/workspace/document/edit/${key}` : undefined
 }
 
 function createTemporaryFilePort(files: MediaFileStore): TemporaryFilePort {
@@ -493,6 +514,15 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
       endSessions: async (userId) => {
         await store.endAllSessionsForUser(userId)
       },
+      onPagePermissionsChanged: (principal, nodeKeys) =>
+        Promise.all(
+          nodeKeys.map((key) =>
+            options.notifier?.raise(
+              { actions: ['Umb.Document.Permissions'], key, keyKind: 'document' },
+              { key: principal.id, name: principal.name },
+            ),
+          ),
+        ).then(() => undefined),
     })
     // Story 032: the authenticator provider, offered only where secrets can be sealed.
     const twoFactor = new TwoFactorService(options.db, {
@@ -620,6 +650,7 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
           enabled: options.config.trackRedirects,
         }),
         options.config.siteDir,
+        Boolean(email),
       )
     if (deps.documents) {
       const documents = deps.documents
@@ -627,6 +658,8 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
         db: options.db,
         nodeState: options.schema?.nodeState,
         email,
+        backOfficeUrl: backOfficeUrl(options.config),
+        notifier: options.notifier,
         // Through the same port an editor's publish takes, so what approval
         // publishes is cached, tracked and announced as any publish is.
         publisher: {

package/src/server.ts

@@ -98,6 +98,7 @@ import { CommandError, installBundleContent } from './bundle-install.ts'
 import { bundleChains, bundleTablesReport } from './bundle-tables.ts'
 import { createBundleRedirects, createServerBundles, validateServerBundles } from './bundles.ts'
 import { busyResponse } from './busy.ts'
+import { listEmailTemplates } from './components.ts'
 import {
   type CromboloConfig,
   listeningBodyLimit,
@@ -105,6 +106,7 @@ import {
   type ServerRole,
   VERSION,
 } from './config.ts'
+import { createContentNotificationRunner, createContentNotifier } from './content-notifications.ts'
 import { attachDatabase, bootstrapDatabase } from './database.ts'
 import { createDeliveryMemberSecurity } from './delivery-members.ts'
 import { createDiagnostics } from './diagnostics.ts'
@@ -143,7 +145,7 @@ import { mediaStoreFromEnvironment } from './media-store.ts'
 import { createMemberAuth, MEMBER_ROUTE_PREFIX } from './member-auth.ts'
 import { noNodesPage } from './no-nodes.ts'
 import { NotImplementedLog } from './not-implemented.ts'
-import { createDeps, PREVIEW_COOKIE, resolveUserLinkSender } from './ports.ts'
+import { createDeps, documentEditUrl, PREVIEW_COOKIE, resolveUserLinkSender } from './ports.ts'
 import { createRedirectTracker } from './redirects.ts'
 import { createRemote } from './remote.ts'
 import { withRemoteMedia } from './remote-media.ts'
@@ -167,6 +169,7 @@ import { syncConfiguredRedirects } from './redirects.ts'
 import {
   bootSchema,
   CacheInstructionPoller,
+  componentAliasesIn,
   importSchema,
   type SchemaBoot,
   watchSchema,
@@ -751,6 +754,9 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
   // gates the options rather than `emailStatus.available`: development delivers
   // to the console, and that is a working flow for the person using it.
   const canSendUserLinks = Boolean(resolveUserLinkSender(config, email))
+  // Story 045: a change queues the e-mails its subscribers asked for. Nothing is
+  // queued on a site that cannot send; development sends to the console.
+  const notifier = createContentNotifier(db, { canSend: Boolean(email) })
   const mediaFiles = new MediaFileStore(mediaStore)
   const images = new ImageProcessor(mediaStore)
   const webhooks = createWebhookService({
@@ -775,6 +781,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     schema,
     mediaFiles,
     email,
+    notifier,
     onSearchQueued: () => jobs.kickSearchIndexing(),
     // This node looks again at once; the others are told to. The write has
     // already landed wherever `componentsDir` points, so there is nothing to
@@ -812,6 +819,10 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     onWebhookEvent: (event) => {
       void webhooks.raise(event)
     },
+    // After the response too: the subscribers are worked out and queued, and sent a minute later.
+    onContentChange: (change, principal) => {
+      void notifier.raise(change, principal ? { key: principal.id, name: principal.name } : null)
+    },
     onServerEvent: (event) => {
       events.broadcast('notify', [event])
       // Saves, deletes and moves all announce themselves; whatever they queued gets indexed now.
@@ -874,7 +885,21 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
       nodeId: schema.nodeId,
       onContentChanged: () => cache.invalidate(),
       bundleWorkflows: formTypes.workflows,
+      renderEmail: (alias, props) => renderer.renderEmail(alias, props),
+      site: async () => ({
+        name: (await seo.siteDefaults()).siteName || config.siteName,
+        url: config.applicationUrl,
+      }),
     }),
+    notifier,
+    contentNotifications: email
+      ? createContentNotificationRunner({
+          db,
+          email,
+          siteName: config.siteName,
+          editUrl: (key) => documentEditUrl(config, key),
+        })
+      : undefined,
     onDocumentChanged: (key) =>
       events.broadcast('notify', [
         { eventSource: 'Umbraco:CMS:Document', eventType: 'Updated', key },
@@ -1273,6 +1298,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
         reason: emailStatus.reason,
         affects: emailStatus.affects,
         canSendUserLinks,
+        canSendNotifications: Boolean(email),
       })
     }
 
@@ -1329,6 +1355,18 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
       // Hyphenated, so no form alias (letters and digits) can be mistaken for it.
       if (action === 'available-types' && request.method === 'GET')
         return Response.json(describeFormTypes(formTypes.types))
+      // The designer's "E-mail design" picker.
+      if (action === 'email-templates' && request.method === 'GET')
+        return Response.json({
+          items: listEmailTemplates(
+            config.componentsDir,
+            definitions.flatMap((form) =>
+              form.workflows.flatMap((workflow) =>
+                typeof workflow.settings.template === 'string' ? [workflow.settings.template] : [],
+              ),
+            ),
+          ),
+        })
 
       const entries = new FormEntryRepository(db)
       const byKey = formsByKey(definitions)
@@ -1340,6 +1378,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
         schemaDir: config.schemaDir,
         writable: config.schemaWritable,
         formTypes: formTypes.types,
+        componentAliases: () => componentAliasesIn(config.componentsDir),
         onChanged: config.schemaStore
           ? async () => {
               await publishSchema(config.schemaStore as SchemaStore, config.schemaDir)