@crombolo/server 0.16.0 → 0.18.0

package/src/content-notifications.ts

@@ -0,0 +1,310 @@
+/**
+ * Content notifications, delivered (story 045): an editor who asked to hear
+ * when a page is published — or moved, sorted, rolled back, and the rest of
+ * Umbraco's eleven — gets an e-mail when it is.
+ *
+ * A change is turned into outbox rows when it happens, one per person,
+ * resolved against the subscriptions on the page and the pages above it, and
+ * never for the person who made it. The rows wait a minute, so a save and a
+ * publish arrive as one e-mail, and a background job on the nodes that run
+ * jobs sends them; each person's rows are claimed by one node.
+ */
+import type { RaisedContentChange } from '@crombolo/api-management'
+import { hasPathAccess, isValidEmail, ObjectTypes, permissionsForPath } from '@crombolo/core'
+import {
+  type ContentNotification,
+  ContentNotificationRepository,
+  type Db,
+  DocumentRepository,
+  NOTIFIABLE_ACTIONS,
+  NodeRepository,
+  NotificationRepository,
+  UserRepository,
+} from '@crombolo/data'
+import { createNodeLookup, loadAccess } from './access.ts'
+import type { EmailPort } from './email.ts'
+import { retryAfter } from './form-workflows.ts'
+import { logger } from './logging.ts'
+
+const log = logger('notifications')
+
+/** How long a change waits for others to the same person, so they arrive as one e-mail. */
+export const DIGEST_DELAY_MS = 60_000
+/** A row a node took and never finished is retried after this long: that node died. */
+export const STALE_AFTER_MS = 15 * 60_000
+
+export interface Actor {
+  key: string | null
+  name: string
+}
+
+export interface ContentNotifierOptions {
+  /** False when the site cannot send e-mail: nothing is queued, and nothing piles up. */
+  canSend: boolean
+  delayMs?: number
+}
+
+export interface ContentNotifier {
+  raise(change: RaisedContentChange, actor: Actor | null, detail?: string): Promise<void>
+}
+
+/** The node ids of a path, root first, without the root's own -1 or the recycle bin's. */
+const pathIds = (path: string): number[] =>
+  path
+    .split(',')
+    .map(Number)
+    .filter((id) => Number.isFinite(id) && id > 0)
+
+export function createContentNotifier(db: Db, options: ContentNotifierOptions): ContentNotifier {
+  const nodes = new NodeRepository(db)
+  const documents = new DocumentRepository(db)
+  const subscriptions = new NotificationRepository(db)
+  const outbox = new ContentNotificationRepository(db)
+
+  const resolve = async (change: RaisedContentChange) => {
+    if (change.keyKind === 'version') {
+      const version = await documents.atVersion(change.key)
+      return version ? nodes.byKey(version.document.key) : undefined
+    }
+    return nodes.byKey(change.key)
+  }
+
+  return {
+    async raise(change, actor, detail) {
+      if (!options.canSend) return
+      try {
+        const node = await resolve(change)
+        if (!node || node.objectType !== ObjectTypes.Document) return
+        // A trashed page sits under the recycle bin now; its subscribers are
+        // the ones where it was.
+        let path = pathIds(node.path)
+        if (node.trashed) {
+          const parentKey = await documents.originalParent(node.key)
+          const parent = parentKey ? await nodes.byKey(parentKey) : undefined
+          path = [...(parent ? pathIds(parent.path) : []), node.id]
+        }
+        let summary = detail ?? null
+        if (change.withDescendants) {
+          const [row] = await db.query<{ n: number }>(
+            'SELECT COUNT(*) AS n FROM node WHERE path LIKE ? AND node_object_type = ? AND trashed = ?',
+            [`${node.path},%`, ObjectTypes.Document, db.dialect.boolValue(false)],
+          )
+          const under = Number(row?.n ?? 0)
+          if (under > 0) summary = `and ${under} page${under === 1 ? '' : 's'} under it`
+        }
+        const actorId = actor?.key ? (await new UserRepository(db).byKey(actor.key))?.id : undefined
+        const occurredAt = new Date()
+        const runAfter = new Date(occurredAt.getTime() + (options.delayMs ?? DIGEST_DELAY_MS))
+        const rows = []
+        for (const actionId of change.actions) {
+          const userIds = (await subscriptions.subscribersFor(actionId, path)).filter(
+            (id) => id !== actorId,
+          )
+          if (userIds.length === 0) continue
+          const keys = await db.query<{ key: string }>(
+            `SELECT key FROM user_account WHERE id IN (${userIds.map(() => '?').join(', ')})`,
+            userIds,
+          )
+          for (const { key } of keys)
+            rows.push({
+              recipientUserKey: String(key),
+              actionId,
+              nodeKey: node.key,
+              nodeName: node.text ?? node.key,
+              actorUserKey: actor?.key ?? null,
+              actorName: actor?.name ?? null,
+              detail: summary,
+              occurredAt,
+              runAfter,
+            })
+        }
+        await outbox.enqueue(rows)
+      } catch (error) {
+        // Like the audit log: a notification that cannot be queued never costs the change.
+        log.error('A content notification could not be queued: {error}', { error: String(error) })
+      }
+    },
+  }
+}
+
+const VERBS: Record<string, string> = {
+  'Umb.Document.Duplicate': 'copied',
+  'Umb.Document.Delete': 'moved to the recycle bin',
+  'Umb.Document.Move': 'moved',
+  'Umb.Document.Create': 'created',
+  'Umb.Document.PublicAccess': 'changed who can see',
+  'Umb.Document.Publish': 'published',
+  'Umb.DocumentRecycleBin.Restore': 'restored',
+  'Umb.Document.Permissions': 'changed the permissions on',
+  'Umb.Document.Rollback': 'rolled back',
+  'Umb.Document.Sort': 'sorted the pages under',
+  'Umb.Document.Update': 'saved',
+}
+
+/** What the subscriber asked to hear of, as a reader would say it: "published". */
+export const verbFor = (actionId: string): string => VERBS[actionId] ?? 'changed'
+
+export interface NotificationEmailContext {
+  siteName: string
+  /** The page's address in the back office; undefined when the site's address is not known. */
+  editUrl: (nodeKey: string) => string | undefined
+  /** The recipient's language. Only English so far; the others fall back to it. */
+  language?: string | null
+}
+
+const when = (date: Date) =>
+  date.toLocaleString('en-GB', {
+    hour: '2-digit',
+    minute: '2-digit',
+    day: 'numeric',
+    month: 'short',
+    year: 'numeric',
+    timeZone: 'UTC',
+  })
+
+/** One plain-text e-mail for everything due to one person, oldest first. */
+export function notificationEmail(
+  recipient: { name: string },
+  items: readonly ContentNotification[],
+  context: NotificationEmailContext,
+): { subject: string; text: string } {
+  const who = (item: ContentNotification) => item.actorName ?? 'Someone'
+  const first = items[0] as ContentNotification
+  const subject =
+    items.length === 1
+      ? `[${context.siteName}] ${who(first)} ${verbFor(first.actionId)} "${first.nodeName}"`
+      : `[${context.siteName}] ${items.length} changes to pages you follow`
+  const lines = items.map((item) => {
+    const link = context.editUrl(item.nodeKey)
+    return [
+      `${who(item)} ${verbFor(item.actionId)} "${item.nodeName}"${item.detail ? ` (${item.detail})` : ''}, ${when(item.occurredAt)} UTC.`,
+      ...(link ? [`  ${link}`] : []),
+    ].join('\n')
+  })
+  const verbs = [...new Set(items.map((item) => verbFor(item.actionId)))]
+  const text = [
+    `Hello ${recipient.name},`,
+    '',
+    ...lines,
+    '',
+    `You get this because you asked to hear when pages here are ${verbs.join(', ')}. To change that, open the page's Notifications in the back office.`,
+  ].join('\n')
+  return { subject, text }
+}
+
+export interface ContentNotificationRunReport {
+  claimed: number
+  sent: number
+  skipped: number
+  retrying: number
+  failed: number
+}
+
+export interface ContentNotificationRunner {
+  runDue(now?: Date, limit?: number): Promise<ContentNotificationRunReport>
+  prune(before: Date): Promise<number>
+}
+
+export function createContentNotificationRunner(deps: {
+  db: Db
+  email: EmailPort | undefined
+  siteName: string
+  editUrl: (nodeKey: string) => string | undefined
+}): ContentNotificationRunner {
+  const { db } = deps
+  const outbox = new ContentNotificationRepository(db)
+  const users = new UserRepository(db)
+  const lookup = createNodeLookup(db)
+
+  /** Whether the person may still read the page: a change made since may have taken it away. */
+  const mayRead = async (userId: number, item: ContentNotification) => {
+    const found = (await lookup.documents([item.nodeKey])).get(item.nodeKey)
+    if (!found) return false
+    const access = await loadAccess(db, userId)
+    // Moved to the recycle bin is about where the page was, so the bin does not count against it.
+    const trashed = found.trashed && item.actionId !== 'Umb.Document.Delete'
+    return (
+      hasPathAccess(access.startNodes.document, found.chain, trashed) &&
+      permissionsForPath(access.groups, found.chain).has('Umb.Document.Read')
+    )
+  }
+
+  return {
+    async runDue(now = new Date(), limit = 25) {
+      const report: ContentNotificationRunReport = {
+        claimed: 0,
+        sent: 0,
+        skipped: 0,
+        retrying: 0,
+        failed: 0,
+      }
+      await outbox.releaseStale(new Date(now.getTime() - STALE_AFTER_MS))
+      for (const recipientKey of await outbox.dueRecipients(now, limit)) {
+        const items = await outbox.claimFor(recipientKey, now)
+        if (items.length === 0) continue
+        report.claimed += items.length
+        const skip = async (rows: readonly ContentNotification[], reason: string) => {
+          await outbox.skip(
+            rows.map((row) => row.id),
+            reason,
+          )
+          report.skipped += rows.length
+        }
+        const user = await users.byKey(recipientKey)
+        if (!user) {
+          await skip(items, 'The user no longer exists.')
+          continue
+        }
+        if (!user.isApproved) {
+          await skip(items, 'The user is disabled.')
+          continue
+        }
+        if (!isValidEmail(user.email)) {
+          await skip(items, 'The user has no e-mail address.')
+          continue
+        }
+        const allowed: ContentNotification[] = []
+        for (const item of items) {
+          if (await mayRead(user.id, item)) allowed.push(item)
+          else await skip([item], 'The user can no longer see the page.')
+        }
+        if (allowed.length === 0) continue
+        const ids = allowed.map((item) => item.id)
+        if (!deps.email) {
+          await outbox.fail(ids, 'This site has no e-mail provider.')
+          report.failed += ids.length
+          continue
+        }
+        const message = notificationEmail(user, allowed, {
+          siteName: deps.siteName,
+          editUrl: deps.editUrl,
+          language: user.languageIsoCode,
+        })
+        const result = await deps.email.send({
+          to: [{ email: user.email, name: user.name }],
+          subject: message.subject,
+          text: message.text,
+        })
+        if (result.ok) {
+          await outbox.succeed(ids)
+          report.sent += ids.length
+          continue
+        }
+        const attempts = Math.max(...allowed.map((item) => item.attempts))
+        const retryAt = retryAfter(attempts, now)
+        await outbox.fail(ids, result.error, retryAt)
+        if (retryAt) report.retrying += ids.length
+        else report.failed += ids.length
+        log.warning('A content notification to {email} was not sent: {error}', {
+          email: user.email,
+          error: result.error,
+        })
+      }
+      return report
+    },
+    prune: (before) => outbox.prune(before),
+  }
+}
+
+/** Every action a person can subscribe to, so a caller can say which one a change was. */
+export const NOTIFICATION_ACTION_IDS: readonly string[] = NOTIFIABLE_ACTIONS.map((a) => a.actionId)

package/src/email-ses.ts

@@ -30,6 +30,7 @@ import {
   postToProvider,
   validateMessage,
 } from './email.ts'
+import { setting } from './settings.ts'
 
 export interface SesOptions extends EmailAdapterOptions {
   region: string
@@ -228,13 +229,13 @@ export function rawMime(
 
 export function sesEmail(options: SesOptions): EmailPort {
   if (!options.region) throw new Error('An SES e-mail adapter needs a region.')
-  const accessKeyId = options.accessKeyId ?? Bun.env.AWS_ACCESS_KEY_ID ?? ''
-  const secretAccessKey = options.secretAccessKey ?? Bun.env.AWS_SECRET_ACCESS_KEY ?? ''
+  const accessKeyId = options.accessKeyId ?? setting('AWS_ACCESS_KEY_ID') ?? ''
+  const secretAccessKey = options.secretAccessKey ?? setting('AWS_SECRET_ACCESS_KEY') ?? ''
   if (!accessKeyId || !secretAccessKey)
     throw new Error(
       'An SES e-mail adapter needs credentials: pass accessKeyId and secretAccessKey, or set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Instance roles are not resolved.',
     )
-  const sessionToken = options.sessionToken ?? Bun.env.AWS_SESSION_TOKEN ?? undefined
+  const sessionToken = options.sessionToken ?? setting('AWS_SESSION_TOKEN') ?? undefined
   const call = options.fetch ?? fetch
   const base = options.endpoint ?? `https://email.${options.region}.amazonaws.com`
   assertSecureEndpoint(base, 'SES')

package/src/email-text.ts

@@ -0,0 +1,61 @@
+/**
+ * The plain-text part of an e-mail, derived from its HTML. `docs/forms.md`.
+ *
+ * A reader whose client shows text, and every spam filter that weighs an HTML
+ * part with no text beside it, read this. It is a reading of the markup, not a
+ * rendering: block elements become lines, list items "- ", links "text (url)".
+ */
+import { decodeEntities } from '@crombolo/data'
+
+const PARAGRAPH =
+  /<\/?(p|h[1-6]|table|ul|ol|blockquote|pre|hr|section|article|header|footer)\b[^>]*>/gi
+const LINE = /<\/?(div|tr|br|address|dl|dt|dd|figure|figcaption|thead|tbody|tfoot)\b[^>]*\/?>/gi
+
+// Stand-ins for the breaks the markup asks for, kept apart from the source's
+// own whitespace, which HTML collapses to a space.
+const BLANK = '\u0001'
+const BREAK = '\u0002'
+const CELL = '\u0003'
+/** A run of breaks with the spaces around them: a blank line if any asked for one. */
+const BREAKS = new RegExp(`[ \u00a0]*[${BLANK}${BREAK}][${BLANK}${BREAK} \u00a0]*`, 'g')
+
+const attribute = (tag: string, name: string): string | undefined => {
+  const found = new RegExp(`\\s${name}\\s*=\\s*("([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i').exec(tag)
+  return found ? (found[2] ?? found[3] ?? found[4]) : undefined
+}
+
+/** The text a reader of `html` would see, as lines. */
+export function htmlToText(html: string): string {
+  const marked = html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(head|style|script|title)\b[^>]*>[\s\S]*?<\/\1>/gi, '')
+    .replace(/<a\b([^>]*)>([\s\S]*?)<\/a>/gi, (_whole, attrs: string, inner: string) => {
+      const href = (attribute(attrs, 'href') ?? '').trim()
+      if (!href || href.startsWith('#')) return inner
+      const address = href.replace(/^mailto:/i, '')
+      const label = decodeEntities(inner.replace(/<[^>]*>/g, '')).trim()
+      return label && label !== decodeEntities(address) ? `${inner} (${address})` : address
+    })
+    .replace(/<li\b[^>]*>/gi, `${BREAK}- `)
+    .replace(/<\/li>/gi, BREAK)
+    .replace(PARAGRAPH, BLANK)
+    .replace(LINE, BREAK)
+    // A cell is a column: the row stays one line, its cells spaced apart.
+    .replace(/<\/t[dh]>/gi, CELL)
+    .replace(/<[^>]*>/g, '')
+    .replace(/\s+/g, ' ')
+
+  return decodeEntities(marked)
+    .replace(BREAKS, (run) => (run.includes(BLANK) ? '\n\n' : '\n'))
+    .split('\n')
+    .map((line) =>
+      line
+        .split(CELL)
+        .map((cell) => cell.replace(/[ \u00a0]+/g, ' ').trim())
+        .filter(Boolean)
+        .join('  '),
+    )
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}

package/src/email.ts

@@ -218,6 +218,7 @@ export const EMAIL_DEPENDENT_FEATURES = [
   'Inviting backoffice users',
   'Password reset by e-mail',
   "Forms' Send email workflow",
+  'Notifications about page changes',
 ]
 
 export const EMAIL_SETUP_HINT =

package/src/form-files.ts

@@ -30,6 +30,8 @@ export interface FormFileOptions {
   onChanged?: () => Promise<void>
   /** The field and workflow types the site's wired bundles add. */
   formTypes?: FormTypes
+  /** The components on disk, so a Send email `template` is held to one that exists. */
+  componentAliases?: () => ReadonlySet<string>
 }
 
 export type FormWriteResult =
@@ -243,6 +245,7 @@ export async function saveForm(
   const problems = validateForms([...others, form], {
     contentTypeAliases: new Set(loaded.set.contentTypes.map((type) => type.alias)),
     types: options.formTypes,
+    componentAliases: options.componentAliases?.(),
   })
   if (problems.length > 0) return { ok: false, status: 'invalid', problems }
 

package/src/form-workflows.ts

@@ -14,6 +14,7 @@
 import {
   allFormFields,
   type FormValueToStore,
+  formFieldType,
   type SchemaForm,
   type SchemaFormWorkflow,
 } from '@crombolo/core'
@@ -25,7 +26,9 @@ import {
   type FormWorkflowRun,
   type NodeSchemaState,
 } from '@crombolo/data'
+import type { EmailField, EmailProps, EmailRenderResult } from '@crombolo/render'
 import type { EmailAttachment, EmailPort } from './email.ts'
+import { htmlToText } from './email-text.ts'
 import type { FormWorkflowTypeDefinition } from './form-types.ts'
 import { logger } from './logging.ts'
 import type { MediaFileStore } from './media-files.ts'
@@ -43,8 +46,13 @@ export interface WorkflowContext {
   entryId: string | null
   /** Which attempt this is, from 1. */
   attempt?: number
+  /** When the run was queued; now when absent. */
+  submittedAt?: Date
 }
 
+/** What an e-mail template is rendered from: its props, less the signal the renderer adds. */
+export type EmailTemplateProps = Omit<EmailProps, 'signal'>
+
 /** How long a bundle's workflow may run before its signal aborts. */
 const BUNDLE_WORKFLOW_TIMEOUT_MS = 60_000
 
@@ -60,6 +68,10 @@ export interface WorkflowDeps {
   onContentChanged?: () => void
   /** The workflow types wired bundles add, by type. */
   bundleWorkflows?: ReadonlyMap<string, FormWorkflowTypeDefinition>
+  /** Renders a `template` component to HTML; absent, a workflow naming one cannot send. */
+  renderEmail?: (alias: string, props: EmailTemplateProps) => Promise<EmailRenderResult>
+  /** The site's name and address, for an e-mail template. */
+  site?: () => Promise<{ name: string; url: string }>
 }
 
 export type WorkflowResult =
@@ -105,20 +117,94 @@ const asList = (value: unknown): string[] =>
         .filter(Boolean)
     : []
 
-/** The submission as a reader sees it: caption, then what was entered. */
-export function plainSummary(context: WorkflowContext): string {
+/**
+ * The submission as a reader sees it: caption, then what was entered. A field
+ * in `leftOut` (lower-cased aliases) says it was left out rather than showing
+ * its answer.
+ */
+export function plainSummary(
+  context: WorkflowContext,
+  leftOut: ReadonlySet<string> = new Set(),
+): string {
   const captions = new Map(
     allFormFields(context.form).map((field) => [field.alias, field.caption || field.alias]),
   )
   const lines = context.values.map(
     (value) =>
       `${captions.get(value.fieldAlias) ?? value.fieldAlias}: ${
-        value.values.length > 0 ? shown(value).join(', ') : '(not answered)'
+        leftOut.has(value.fieldAlias.toLowerCase())
+          ? '(sensitive, not included)'
+          : value.values.length > 0
+            ? shown(value).join(', ')
+            : '(not answered)'
       }`,
   )
   return [`${context.form.name}`, '', ...lines].join('\n')
 }
 
+/**
+ * The sensitive fields a workflow leaves out, lower-cased: all of them unless it
+ * sets `include-sensitive = true`.
+ */
+export function leftOutFields(form: SchemaForm, workflow: SchemaFormWorkflow): Set<string> {
+  if (workflow.settings['include-sensitive'] === true) return new Set()
+  return new Set(
+    allFormFields(form)
+      .filter((field) => field.sensitive)
+      .map((field) => field.alias.toLowerCase()),
+  )
+}
+
+/** The values with every left-out field emptied, so substitution shows nothing for it. */
+const withoutLeftOut = (
+  values: readonly FormValueToStore[],
+  leftOut: ReadonlySet<string>,
+): FormValueToStore[] =>
+  values.map((value) =>
+    leftOut.has(value.fieldAlias.toLowerCase())
+      ? { fieldAlias: value.fieldAlias, values: [] }
+      : value,
+  )
+
+/** An e-mail template's props: the form, its fields in order, and where it came from. */
+export function emailTemplateProps(
+  context: WorkflowContext,
+  leftOut: ReadonlySet<string>,
+  subject: string,
+  site: { name: string; url: string },
+): EmailTemplateProps {
+  const sent = withoutLeftOut(context.values, leftOut)
+  const byAlias = new Map(sent.map((value) => [value.fieldAlias.toLowerCase(), value]))
+  const fields: EmailField[] = allFormFields(context.form)
+    // A heading or a paragraph collects nothing; a bundle's type is kept, since
+    // only its own declaration could say it is presentational.
+    .filter((field) => formFieldType(field.type)?.presentational !== true)
+    .map((field) => {
+      const found = byAlias.get(field.alias.toLowerCase())
+      const values = found ? shown(found) : []
+      return {
+        alias: field.alias,
+        caption: field.caption || field.alias,
+        type: field.type,
+        values,
+        answered: values.length > 0,
+        sensitive: field.sensitive,
+        leftOut: leftOut.has(field.alias.toLowerCase()),
+      }
+    })
+  return {
+    form: context.form,
+    fields,
+    value: (alias) => {
+      const found = byAlias.get(alias.toLowerCase())
+      return found ? shown(found).join(', ') : ''
+    },
+    entry: { id: context.entryId, submittedAt: context.submittedAt ?? new Date() },
+    site,
+    subject,
+  }
+}
+
 // ------------------------------------------------------------------ send email
 
 async function sendEmail(
@@ -136,8 +222,26 @@ async function sendEmail(
     }
 
   const settings = workflow.settings
-  const to = asList(substitute(asString(settings.to) ?? '', context.values))
+  // Sensitive answers stay out of every part of the e-mail unless the workflow
+  // asks for them: an inbox is not covered by the sensitive-data permission.
+  const leftOut = leftOutFields(context.form, workflow)
+  const values = withoutLeftOut(context.values, leftOut)
+  const to = asList(substitute(asString(settings.to) ?? '', values))
   if (to.length === 0) return { ok: false, retry: false, error: 'The workflow has no recipient.' }
+  const subject = substitute(asString(settings.subject) ?? context.form.name, values).trim()
+
+  let html: string | undefined
+  let text: string
+  const template = asString(settings.template)
+  if (template) {
+    const rendered = await renderTemplate(template, context, leftOut, subject, deps)
+    if (!rendered.ok) return rendered
+    html = rendered.html
+    text = htmlToText(html)
+  } else
+    text = settings.body
+      ? substitute(String(settings.body), values)
+      : plainSummary(context, leftOut)
 
   const attachments: EmailAttachment[] = []
   if (settings['attach-uploads'] === true && deps.mediaFiles) {
@@ -146,7 +250,7 @@ async function sendEmail(
         .filter((field) => field.type === 'fileUpload')
         .map((field) => field.alias),
     )
-    for (const value of context.values) {
+    for (const value of values) {
       if (!uploadAliases.has(value.fieldAlias)) continue
       for (const src of value.values) {
         const file = await deps.mediaFiles.open(src)
@@ -166,21 +270,67 @@ async function sendEmail(
     bcc: asList(asString(settings.bcc) ?? '').map((email) => ({ email })),
     replyTo: (() => {
       const replyTo = asString(settings['reply-to'])
-      const resolved = replyTo ? substitute(replyTo, context.values) : undefined
+      const resolved = replyTo ? substitute(replyTo, values) : undefined
       return resolved ? { email: resolved } : undefined
     })(),
     from: (() => {
       const from = asString(settings.from)
       return from ? { email: from } : undefined
     })(),
-    subject: substitute(asString(settings.subject) ?? context.form.name, context.values),
-    text: settings.body ? substitute(String(settings.body), context.values) : plainSummary(context),
+    subject,
+    text,
+    ...(html === undefined ? {} : { html }),
     attachments: attachments.length > 0 ? attachments : undefined,
   })
   // A provider that refused is worth another go: a 500 or a timeout is weather.
   return result.ok ? { ok: true } : { ok: false, retry: true, error: result.error }
 }
 
+/**
+ * The HTML of a workflow's e-mail template, or why there is none.
+ *
+ * Both failures are retried. A template missing now may be one a node has not
+ * caught up with after a deploy; one that throws may be reading something that
+ * is briefly unavailable. After the last attempt the run is left failed, with
+ * the reason a person can act on.
+ */
+async function renderTemplate(
+  template: string,
+  context: WorkflowContext,
+  leftOut: ReadonlySet<string>,
+  subject: string,
+  deps: WorkflowDeps,
+): Promise<{ ok: true; html: string } | (WorkflowResult & { ok: false })> {
+  if (!deps.renderEmail)
+    return {
+      ok: false,
+      retry: false,
+      error: `The e-mail template '${template}' cannot be rendered here: this server renders no templates.`,
+    }
+  try {
+    const site = (await deps.site?.()) ?? { name: '', url: '' }
+    const rendered = await deps.renderEmail(
+      template,
+      emailTemplateProps(context, leftOut, subject, site),
+    )
+    if (rendered.status === 'ok') return { ok: true, html: rendered.html }
+    return {
+      ok: false,
+      retry: true,
+      error:
+        rendered.status === 'missing'
+          ? `There is no e-mail template '${template}': no components/${template}.tsx in the views this node serves.`
+          : rendered.message,
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      retry: true,
+      error: `The e-mail template '${template}' failed: ${error instanceof Error ? error.message : String(error)}`,
+    }
+  }
+}
+
 // ------------------------------------------------------------------ save as content
 
 async function saveAsContent(
@@ -404,6 +554,7 @@ export function createWorkflowRunner(
       values: run.payload,
       entryId: run.entryId,
       attempt: run.attempts,
+      submittedAt: run.createDate,
     }
     let result: WorkflowResult
     try {