@actuate-media/cms-core 0.25.1 → 0.27.0

package/dist/api/handlers.js

@@ -21,6 +21,7 @@ import { publishNotification } from '../realtime/notification-bus.js';
 import { createNotificationStreamResponse } from '../realtime/notification-stream.js';
 import { schedulingCronHandler } from '../scheduling/index.js';
 import { isAuthorizedCronRequest, processCleanup, processSeoScan } from '../cron/index.js';
+import { processContentHealthScan } from '../content-health/cron.js';
 import { verifyCaptcha, getCaptchaConfig } from '../security/captcha.js';
 import { checkForUpdates } from '../upgrade/version-check.js';
 import { createUpgradePR } from '../upgrade/upgrade-pr.js';
@@ -32,6 +33,7 @@ import { createSSEPresenceAdapter } from '../presence/index.js';
 import { BUILT_IN_TEMPLATES } from '../page-builder/templates.js';
 import { validateTree } from '../page-builder/validate.js';
 import { auditAccessibility, fixAccessibility } from '../page-builder/a11y-fix.js';
+import { SECTION_TYPE_LIST, getSectionType, getSectionTypesForScope, buildSection, coerceSections, coercePostHeader, defaultPostHeader, addSection as addSectionToList, removeSection as removeSectionFromList, reorderSections as reorderSectionList, setSectionVisibility, updateSectionContent as updateSectionContentInList, updateSectionSettings as updateSectionSettingsInList, updateSectionMeta as updateSectionMetaInList, validateSectionContent, } from '../sections/index.js';
 import { getClientIp, isResolvedIp } from '../security/client-ip.js';
 import { safeFetch, SsrfBlockedError } from '../security/safe-fetch.js';
 import { redactSecrets } from '../security/redact.js';
@@ -707,6 +709,41 @@ class ModelNotAvailableError extends Error {
         this.model = model;
     }
 }
+/**
+ * Resolve a collection definition from the runtime config, tolerating both
+ * the array and the record (keyed-by-slug) shapes consumers use.
+ */
+function findCollectionDef(slug) {
+    const collections = getActuateConfig()?.collections;
+    if (Array.isArray(collections)) {
+        return collections.find((c) => c?.slug === slug);
+    }
+    if (collections && typeof collections === 'object') {
+        const rec = collections;
+        return rec[slug] ?? Object.values(rec).find((c) => c?.slug === slug);
+    }
+    return undefined;
+}
+/**
+ * True when `collection` declares a `sections` JSON field — the storage
+ * contract the flat Page Editor + section endpoints rely on. Guards against
+ * silently dropping section writes on a collection that never declared the
+ * field (the field-access layer strips undeclared keys).
+ */
+function collectionSupportsSections(slug) {
+    const def = findCollectionDef(slug);
+    if (!def)
+        return false;
+    const fields = def.fields;
+    if (Array.isArray(fields)) {
+        return fields.some((f) => f?.name === 'sections' && f?.type === 'json');
+    }
+    if (fields && typeof fields === 'object') {
+        const f = fields.sections;
+        return f?.type === 'json';
+    }
+    return false;
+}
 export function registerCMSRoutes(router) {
     const rawDb = () => getDB();
     const db = () => {
@@ -810,6 +847,14 @@ export function registerCMSRoutes(router) {
                 type: def?.type ?? 'page',
                 urlPrefix: def?.urlPrefix ?? slug,
                 hidden: def?.admin?.hidden === true,
+                // Surface the admin metadata the Posts area needs to render
+                // type tabs / cards (description, icon, accent color, group).
+                // None are sensitive — they all already live on the public
+                // collection definition the admin client receives via props.
+                description: def?.admin?.description ?? null,
+                icon: def?.admin?.icon ?? null,
+                color: def?.admin?.color ?? null,
+                group: def?.admin?.group ?? null,
                 fieldCount: fieldSummary.length,
                 fields: fieldSummary,
             };
@@ -1704,6 +1749,337 @@ export function registerCMSRoutes(router) {
         }
     });
     // ---------------------------------------------------------------------------
+    // Page section routes (flat Page Editor model)
+    //
+    // These operate on a page document's `data.sections` JSON array — the same
+    // model the visual Page Editor reads/writes — so an AI agent driving the
+    // CMS from Cursor/VS Code via MCP produces real, editable, publishable
+    // sections rather than disposable markup. All mutations go through the
+    // audited `updateDocument` path (versions, hooks, cache invalidation,
+    // live-preview push) and reuse collection scope checks.
+    //
+    // Discovery + validation are deterministic (no LLM) and only need auth.
+    // ---------------------------------------------------------------------------
+    // GET /page-sections/types — discover registered section types + schemas.
+    // Optional `?scope=page|post` filters to types usable on that surface so an
+    // agent only builds sections that have a working renderer in that context.
+    router.get('/page-sections/types', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scope = new URL(request.url).searchParams.get('scope');
+            const data = scope === 'page' || scope === 'post'
+                ? getSectionTypesForScope(scope)
+                : SECTION_TYPE_LIST;
+            return json({ data });
+        }
+        catch (err) {
+            return internalError(err, 'list section types');
+        }
+    });
+    // POST /page-sections/validate — validate section content against its
+    // type schema. Body: { sectionType, content, settings? }.
+    router.post('/page-sections/validate', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const body = (await request.json().catch(() => null));
+            const sectionType = typeof body?.sectionType === 'string' ? body.sectionType : '';
+            if (!sectionType)
+                return errorResponse('sectionType is required', 400);
+            const content = body?.content && typeof body.content === 'object'
+                ? body.content
+                : {};
+            const settings = body?.settings && typeof body.settings === 'object'
+                ? body.settings
+                : undefined;
+            const result = validateSectionContent(sectionType, content, settings);
+            return json({ data: result });
+        }
+        catch (err) {
+            return internalError(err, 'validate section');
+        }
+    });
+    // Shared: load a page document's sections, or a Response on error.
+    const loadPageSections = async (collection, id, ctx) => {
+        if (!collectionSupportsSections(collection)) {
+            return errorResponse(`Collection "${collection}" does not declare a "sections" JSON field, so it cannot store page sections.`, 400);
+        }
+        const doc = await getDocument(collection, id, ctx);
+        if (!doc)
+            return errorResponse('Page not found', 404);
+        const data = doc.data ?? {};
+        return { sections: coerceSections(data.sections) };
+    };
+    // Shared: persist a mutated section array via the audited update path.
+    const persistPageSections = async (collection, id, sections, ctx, userId) => {
+        const doc = await updateDocument(collection, id, { sections }, ctx);
+        await logEvent({
+            event: 'document_updated',
+            userId,
+            details: { collection, documentId: id, action: 'page_sections_updated' },
+        });
+        notifyPreviewUpdate(collection, id, {
+            values: doc.data,
+            status: doc.status,
+            updatedAt: doc.updatedAt?.toISOString?.(),
+        });
+        const data = doc.data ?? {};
+        return coerceSections(data.sections);
+    };
+    // GET /page-sections/:collection/:id — list a page's sections.
+    router.get('/page-sections/:collection/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'read');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            return json({ data: loaded.sections });
+        }
+        catch (err) {
+            return internalError(err, 'list page sections');
+        }
+    });
+    // POST /page-sections/:collection/:id — add a section.
+    // Body: { sectionType, name?, internalLabel?, visible?, content?, settings?, position? }.
+    router.post('/page-sections/:collection/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const sectionType = typeof body?.sectionType === 'string' ? body.sectionType : '';
+            if (!getSectionType(sectionType)) {
+                return errorResponse(`Unknown section type "${sectionType}". Call GET /page-sections/types for valid ids.`, 400);
+            }
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const section = buildSection(sectionType, {
+                name: typeof body?.name === 'string' ? body.name : undefined,
+                internalLabel: typeof body?.internalLabel === 'string' ? body.internalLabel : undefined,
+                visible: body?.visible !== false,
+                content: body?.content && typeof body.content === 'object'
+                    ? body.content
+                    : undefined,
+                settings: body?.settings && typeof body.settings === 'object'
+                    ? body.settings
+                    : undefined,
+            });
+            const position = typeof body?.position === 'number' ? body.position : undefined;
+            const next = addSectionToList(loaded.sections, section, position);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            const validation = validateSectionContent(section.sectionType, section.content, section.settings);
+            return json({ data: { section, sections: saved, validation } }, 201);
+        }
+        catch (err) {
+            return internalError(err, 'add page section');
+        }
+    });
+    // POST /page-sections/:collection/:id/reorder — reorder by id list.
+    // Registered BEFORE the :sectionId routes so "reorder" isn't captured as a
+    // section id (the router matches in registration order).
+    router.post('/page-sections/:collection/:id/reorder', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const orderedIds = Array.isArray(body?.orderedIds)
+                ? body.orderedIds.filter((x) => typeof x === 'string')
+                : null;
+            if (!orderedIds)
+                return errorResponse('orderedIds (string[]) is required', 400);
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const next = reorderSectionList(loaded.sections, orderedIds);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            return json({ data: saved });
+        }
+        catch (err) {
+            return internalError(err, 'reorder page sections');
+        }
+    });
+    // PATCH /page-sections/:collection/:id/:sectionId — update a section.
+    // Body: { content?, settings?, name?, internalLabel?, visible? }.
+    router.patch('/page-sections/:collection/:id/:sectionId', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const sectionId = params.sectionId;
+            if (!loaded.sections.some((s) => s.id === sectionId)) {
+                return errorResponse(`Section "${sectionId}" not found on this page.`, 404);
+            }
+            let next = loaded.sections;
+            if (body?.content && typeof body.content === 'object') {
+                next = updateSectionContentInList(next, sectionId, body.content);
+            }
+            if (body?.settings && typeof body.settings === 'object') {
+                next = updateSectionSettingsInList(next, sectionId, body.settings);
+            }
+            const meta = {};
+            if (typeof body?.name === 'string')
+                meta.name = body.name;
+            if (typeof body?.internalLabel === 'string')
+                meta.internalLabel = body.internalLabel;
+            if (Object.keys(meta).length > 0)
+                next = updateSectionMetaInList(next, sectionId, meta);
+            if (typeof body?.visible === 'boolean') {
+                next = setSectionVisibility(next, sectionId, body.visible);
+            }
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            const updated = saved.find((s) => s.id === sectionId);
+            const validation = updated
+                ? validateSectionContent(updated.sectionType, updated.content, updated.settings)
+                : undefined;
+            return json({ data: { section: updated, sections: saved, validation } });
+        }
+        catch (err) {
+            return internalError(err, 'update page section');
+        }
+    });
+    // DELETE /page-sections/:collection/:id/:sectionId — remove a section.
+    router.delete('/page-sections/:collection/:id/:sectionId', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.collection, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const loaded = await loadPageSections(params.collection, params.id, ctx);
+            if (loaded instanceof Response)
+                return loaded;
+            const sectionId = params.sectionId;
+            if (!loaded.sections.some((s) => s.id === sectionId)) {
+                return errorResponse(`Section "${sectionId}" not found on this page.`, 404);
+            }
+            const next = removeSectionFromList(loaded.sections, sectionId);
+            const saved = await persistPageSections(params.collection, params.id, next, ctx, auth.session.userId);
+            return json({ data: { sections: saved } });
+        }
+        catch (err) {
+            return internalError(err, 'remove page section');
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // Post template routes
+    //
+    // A post type's template is a single document in the hidden
+    // `post-templates` collection, matched by `slug` == the post-type slug. It
+    // stores the design-driven header layout (`data.header`) and the default
+    // section list (`data.sections`) new posts inherit. Lets an external AI
+    // agent (Cursor/VS Code) read a type's template and build it from
+    // scope=post section types discovered via `/page-sections/types?scope=post`.
+    // ---------------------------------------------------------------------------
+    const POST_TEMPLATES_COLLECTION = 'post-templates';
+    const findPostTemplateDoc = async (postType, ctx) => {
+        const res = await listDocuments({ collection: POST_TEMPLATES_COLLECTION, pageSize: 200 }, ctx);
+        const docs = res.docs ?? [];
+        return (docs.find((d) => (d.slug ?? d.data?.slug) === postType) ?? null);
+    };
+    const templateResponse = (postType, doc) => {
+        if (!doc) {
+            return { postType, docId: null, header: defaultPostHeader(), sections: [] };
+        }
+        const data = doc.data ?? {};
+        return {
+            postType,
+            docId: doc.id,
+            header: coercePostHeader(data.header),
+            sections: coerceSections(data.sections),
+        };
+    };
+    // GET /post-templates/:type — read a post type's template (header +
+    // default sections). Returns an unsaved default when none exists yet.
+    router.get('/post-templates/:type', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, POST_TEMPLATES_COLLECTION, 'read');
+            if (scopeErr)
+                return scopeErr;
+            const ctx = buildActionContext(auth.session, db());
+            const doc = await findPostTemplateDoc(params.type, ctx);
+            return json({ data: templateResponse(params.type, doc) });
+        }
+        catch (err) {
+            return internalError(err, 'get post template');
+        }
+    });
+    // PUT /post-templates/:type — create or replace a post type's template.
+    // Body: { header?, sections? }. Header is coerced to a full PostHeaderConfig
+    // and sections are coerced (unknown section types dropped) so the stored
+    // template always renders.
+    router.put('/post-templates/:type', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, POST_TEMPLATES_COLLECTION, 'update');
+            if (scopeErr)
+                return scopeErr;
+            const body = (await request.json().catch(() => null));
+            const header = coercePostHeader(body?.header);
+            const sections = coerceSections(body?.sections);
+            const ctx = buildActionContext(auth.session, db());
+            const existing = await findPostTemplateDoc(params.type, ctx);
+            const data = {
+                title: `${params.type} template`,
+                slug: params.type,
+                postType: params.type,
+                header,
+                sections,
+                status: 'PUBLISHED',
+            };
+            const doc = existing
+                ? await updateDocument(POST_TEMPLATES_COLLECTION, existing.id, data, ctx)
+                : await createDocument(POST_TEMPLATES_COLLECTION, data, ctx);
+            await logEvent({
+                event: existing ? 'document_updated' : 'document_created',
+                userId: auth.session.userId,
+                details: {
+                    collection: POST_TEMPLATES_COLLECTION,
+                    documentId: doc.id,
+                    action: 'post_template_saved',
+                    postType: params.type,
+                },
+            });
+            return json({ data: templateResponse(params.type, doc) });
+        }
+        catch (err) {
+            return internalError(err, 'save post template');
+        }
+    });
+    // ---------------------------------------------------------------------------
     // Media routes
     // ---------------------------------------------------------------------------
     router.get('/media', async (request) => {
@@ -2520,6 +2896,31 @@ export function registerCMSRoutes(router) {
         statusCounts: {},
         recentDocuments: [],
     };
+    const EMPTY_DELIVERY_STATS = {
+        hasData: false,
+        requests24h: 0,
+        requestsPrev24h: 0,
+        deltaPercent: null,
+        errorRate: 0,
+        errorCount: 0,
+        avgLatencyMs: 0,
+        p95LatencyMs: 0,
+        maxLatencyMs: 0,
+        webhookCount: 0,
+        webhookActiveCount: 0,
+    };
+    const EMPTY_CONTENT_HEALTH = {
+        score: 100,
+        label: 'Good',
+        counts: {
+            MISSING_META_DESCRIPTION: 0,
+            MISSING_ALT_TEXT: 0,
+            BROKEN_INTERNAL_LINK: 0,
+            OUTDATED_CONTENT: 0,
+        },
+        totalIssues: 0,
+        lastScanAt: null,
+    };
     async function safeGroupBy(model, by, where) {
         if (!model || typeof model !== 'object')
             return [];
@@ -2552,6 +2953,36 @@ export function registerCMSRoutes(router) {
             score += 25;
         return score;
     }
+    /**
+     * Collection slugs that are written by the benchmark suite and a few
+     * other internal/test fixtures. Documents in these collections are
+     * never editor-facing content and should never appear in the
+     * dashboard's stats, counts, or recent-activity feed.
+     *
+     * This list is the fallback when the consumer ships collection
+     * definitions only to the admin client (e.g. `apps/dev`) and
+     * `getActuateConfig()?.collections` is therefore empty on the
+     * server. Production consumers normally pass `collections` to
+     * `handleActuateAPI({ config })`, in which case the registered
+     * slugs become the allowlist and this denylist is unused.
+     */
+    const INTERNAL_COLLECTION_SLUGS = ['benchmarks', 'bench'];
+    /**
+     * Build the Prisma `where` clause for "user-facing content".
+     *
+     *   - If the CMS config registered collections, restrict to those
+     *     slugs — anything else is orphan/test data.
+     *   - Otherwise fall back to excluding the internal denylist.
+     *
+     * Always excludes soft-deleted rows. Callers can spread additional
+     * filters on top (`status: 'PUBLISHED'`, etc.).
+     */
+    function userContentWhere(extra = {}) {
+        const cfg = getActuateConfig();
+        const registered = Object.keys(cfg?.collections ?? {});
+        const collectionFilter = registered.length > 0 ? { in: registered } : { notIn: [...INTERNAL_COLLECTION_SLUGS] };
+        return { deletedAt: null, collection: collectionFilter, ...extra };
+    }
     router.get('/stats', async (request) => {
         try {
             if (!isSecretMissing()) {
@@ -2566,8 +2997,13 @@ export function registerCMSRoutes(router) {
             catch {
                 return json({ data: EMPTY_STATS });
             }
+            // `userContentWhere()` filters out benchmark / orphan / internal
+            // collections so the dashboard surfaces editor content only. See
+            // the helper above for the allowlist-vs-denylist behaviour.
+            const contentWhere = userContentWhere();
+            const publishedContentWhere = userContentWhere({ status: 'PUBLISHED' });
             const [docResult, mediaResult, userResult, recentResult, collGroupResult, statusGroupResult, formResult, seoDocsResult, webhookTotalResult, webhookActiveResult,] = await Promise.allSettled([
-                safeCount(d.document, { deletedAt: null }),
+                safeCount(d.document, contentWhere),
                 safeCount(d.media),
                 safeCount(d.user),
                 safeFindMany(d.document, {
@@ -2577,7 +3013,7 @@ export function registerCMSRoutes(router) {
                     // -> Prisma Postgres path that saves ~80 ms (one full network
                     // RTT) on every dashboard load.
                     relationLoadStrategy: 'join',
-                    where: { deletedAt: null },
+                    where: contentWhere,
                     orderBy: { updatedAt: 'desc' },
                     take: 20,
                     select: {
@@ -2590,11 +3026,11 @@ export function registerCMSRoutes(router) {
                         createdBy: { select: { name: true, email: true } },
                     },
                 }),
-                safeGroupBy(d.document, ['collection'], { deletedAt: null }),
-                safeGroupBy(d.document, ['status'], { deletedAt: null }),
+                safeGroupBy(d.document, ['collection'], contentWhere),
+                safeGroupBy(d.document, ['status'], contentWhere),
                 safeCount(d.formSubmission),
                 safeFindMany(d.document, {
-                    where: { deletedAt: null, status: 'PUBLISHED' },
+                    where: publishedContentWhere,
                     select: { data: true },
                     take: 200,
                 }),
@@ -2650,6 +3086,227 @@ export function registerCMSRoutes(router) {
         }
     });
     // ---------------------------------------------------------------------------
+    // Content Health — backs the dashboard "Content Health" issue rows
+    // ---------------------------------------------------------------------------
+    //
+    // Aggregates rows from `actuate_content_issues` (populated nightly by
+    // /cron/content-health) by `type`, returning the totals the dashboard
+    // surfaces. We also compute an overall content-health score so the
+    // big number + progress bar stay consistent with the per-row counts.
+    //
+    // Score model:
+    //   - Start at 100.
+    //   - Subtract 5 per missing-meta-description issue.
+    //   - Subtract 2 per missing-alt image.
+    //   - Subtract 10 per broken internal link.
+    //   - Subtract 3 per outdated document.
+    // Floor at 0. The weights reflect SEO impact (broken links and
+    // missing meta hit hardest) and are kept here, not in the DB, so we
+    // can tune them without a migration.
+    router.get('/stats/content-health', async (request) => {
+        try {
+            if (!isSecretMissing()) {
+                const auth = await requireAuth(request);
+                if (auth.error)
+                    return auth.error;
+            }
+            let d;
+            try {
+                d = db();
+            }
+            catch {
+                return json({ data: EMPTY_CONTENT_HEALTH });
+            }
+            if (!d?.contentIssue) {
+                return json({ data: EMPTY_CONTENT_HEALTH });
+            }
+            let rows = [];
+            try {
+                rows = await d.contentIssue.groupBy({
+                    by: ['type'],
+                    _sum: { count: true },
+                });
+            }
+            catch {
+                return json({ data: EMPTY_CONTENT_HEALTH });
+            }
+            const counts = {
+                MISSING_META_DESCRIPTION: 0,
+                MISSING_ALT_TEXT: 0,
+                BROKEN_INTERNAL_LINK: 0,
+                OUTDATED_CONTENT: 0,
+            };
+            for (const r of rows) {
+                counts[r.type] = r._sum.count ?? 0;
+            }
+            // Read-out via locals so TS narrows away the Record<string,..>
+            // indexed-access undefined union — we know the keys are present
+            // because we initialised them above.
+            const cMeta = counts['MISSING_META_DESCRIPTION'] ?? 0;
+            const cAlt = counts['MISSING_ALT_TEXT'] ?? 0;
+            const cLinks = counts['BROKEN_INTERNAL_LINK'] ?? 0;
+            const cOutdated = counts['OUTDATED_CONTENT'] ?? 0;
+            // Penalty model — see comment above.
+            let score = 100;
+            score -= cMeta * 5;
+            score -= cAlt * 2;
+            score -= cLinks * 10;
+            score -= cOutdated * 3;
+            score = Math.max(0, Math.min(100, score));
+            // Last scan timestamp — useful for the dashboard to display
+            // "Last scanned X minutes ago" so editors don't think the
+            // numbers are live.
+            let lastScanAt = null;
+            try {
+                const latest = await d.contentIssue.findFirst({
+                    orderBy: { lastSeenAt: 'desc' },
+                    select: { lastSeenAt: true },
+                });
+                lastScanAt = latest?.lastSeenAt ?? null;
+            }
+            catch {
+                /* ignore — empty table or stale schema */
+            }
+            return json({
+                data: {
+                    score,
+                    label: score >= 70 ? 'Good' : score >= 40 ? 'Fair' : 'Poor',
+                    counts,
+                    totalIssues: cMeta + cAlt + cLinks + cOutdated,
+                    lastScanAt: lastScanAt?.toISOString() ?? null,
+                },
+            });
+        }
+        catch {
+            return json({ data: EMPTY_CONTENT_HEALTH });
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // Delivery API metrics — backs the dashboard "Delivery API" tiles
+    // ---------------------------------------------------------------------------
+    //
+    // Reads from `actuate_api_request_metrics` (per-minute pre-aggregated
+    // counters populated by `recordApiRequest` in handler-factory.ts) and
+    // folds the last 24h into the four scalars the dashboard surfaces:
+    //
+    //   - requests24h, requestsPrev24h (delta = "+12% vs yesterday")
+    //   - errorRate (4xx + 5xx as fraction of total)
+    //   - avgLatencyMs, p95LatencyMs (latter via histogram merge)
+    //   - webhooks (total + active count)
+    //
+    // The endpoint returns a complete, never-undefined object even when
+    // the metrics table is empty — the dashboard distinguishes
+    // "no traffic yet" from "table missing" via the boolean `hasData`
+    // field so it can render an empty state without an extra round-trip.
+    router.get('/stats/api-delivery', async (request) => {
+        try {
+            if (!isSecretMissing()) {
+                const auth = await requireAuth(request);
+                if (auth.error)
+                    return auth.error;
+            }
+            let d;
+            try {
+                d = db();
+            }
+            catch {
+                return json({ data: EMPTY_DELIVERY_STATS });
+            }
+            if (!d?.apiRequestMetric) {
+                return json({ data: EMPTY_DELIVERY_STATS });
+            }
+            const now = new Date();
+            const since24h = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+            const sincePrev24h = new Date(now.getTime() - 48 * 60 * 60 * 1000);
+            const [currentResult, prevResult, webhookTotalResult, webhookActiveResult] = await Promise.allSettled([
+                safeFindMany(d.apiRequestMetric, {
+                    where: { bucketStart: { gte: since24h } },
+                    select: {
+                        statusBucket: true,
+                        count: true,
+                        sumLatencyMs: true,
+                        maxLatencyMs: true,
+                        latencyHistogram: true,
+                    },
+                }),
+                safeFindMany(d.apiRequestMetric, {
+                    where: { bucketStart: { gte: sincePrev24h, lt: since24h } },
+                    select: { count: true },
+                }),
+                safeCount(d.webhookEndpoint),
+                safeCount(d.webhookEndpoint, { active: true }),
+            ]);
+            const currentRows = currentResult.status === 'fulfilled' ? currentResult.value : [];
+            const prevRows = prevResult.status === 'fulfilled' ? prevResult.value : [];
+            let total = 0;
+            let errorTotal = 0; // 4xx + 5xx
+            let sumLatency = 0;
+            let maxLatency = 0;
+            // Histogram merge for p95 — fixed 12-bucket array (see
+            // diagnostics/api-metrics.ts `HISTOGRAM_LENGTH`).
+            const mergedHistogram = new Array(12).fill(0);
+            for (const row of currentRows) {
+                total += row.count;
+                if (row.statusBucket === '4xx' || row.statusBucket === '5xx')
+                    errorTotal += row.count;
+                sumLatency += row.sumLatencyMs;
+                if (row.maxLatencyMs > maxLatency)
+                    maxLatency = row.maxLatencyMs;
+                const h = row.latencyHistogram;
+                if (Array.isArray(h)) {
+                    for (let i = 0; i < mergedHistogram.length; i++) {
+                        const v = h[i];
+                        const current = mergedHistogram[i] ?? 0;
+                        if (typeof v === 'number')
+                            mergedHistogram[i] = current + v;
+                    }
+                }
+            }
+            const prevTotal = prevRows.reduce((s, r) => s + r.count, 0);
+            const delta = prevTotal === 0 ? null : Math.round(((total - prevTotal) / prevTotal) * 1000) / 10; // 1-decimal %
+            const errorRate = total === 0 ? 0 : errorTotal / total;
+            const avgLatency = total === 0 ? 0 : sumLatency / total;
+            // p95: walk the merged histogram cumulatively, return the upper
+            // bound of the bucket that crosses the 0.95 watermark.
+            const LATENCY_BUCKET_UPPER = [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024];
+            let p95Latency = 0;
+            if (total > 0) {
+                const target = total * 0.95;
+                let acc = 0;
+                for (let i = 0; i < mergedHistogram.length; i++) {
+                    acc += mergedHistogram[i] ?? 0;
+                    if (acc >= target) {
+                        p95Latency =
+                            i < LATENCY_BUCKET_UPPER.length
+                                ? LATENCY_BUCKET_UPPER[i]
+                                : LATENCY_BUCKET_UPPER[LATENCY_BUCKET_UPPER.length - 1] * 2;
+                        break;
+                    }
+                }
+            }
+            const webhookTotal = webhookTotalResult.status === 'fulfilled' ? webhookTotalResult.value : 0;
+            const webhookActive = webhookActiveResult.status === 'fulfilled' ? webhookActiveResult.value : 0;
+            return json({
+                data: {
+                    hasData: total > 0,
+                    requests24h: total,
+                    requestsPrev24h: prevTotal,
+                    deltaPercent: delta,
+                    errorRate: Math.round(errorRate * 10000) / 10000, // 4-dec precision
+                    errorCount: errorTotal,
+                    avgLatencyMs: Math.round(avgLatency * 10) / 10,
+                    p95LatencyMs: p95Latency,
+                    maxLatencyMs: Math.round(maxLatency * 10) / 10,
+                    webhookCount: webhookTotal,
+                    webhookActiveCount: webhookActive,
+                },
+            });
+        }
+        catch {
+            return json({ data: EMPTY_DELIVERY_STATS });
+        }
+    });
+    // ---------------------------------------------------------------------------
     // Global search
     // ---------------------------------------------------------------------------
     router.get('/search/global', async (request) => {
@@ -5420,6 +6077,22 @@ export function registerCMSRoutes(router) {
     };
     router.get('/cron/seo-scan', cronSeoScan);
     router.post('/cron/seo-scan', cronSeoScan);
+    const cronContentHealth = async (request) => {
+        try {
+            if (!isAuthorizedCronRequest(request.headers.get('authorization'))) {
+                return errorResponse('Unauthorized', 401);
+            }
+            const config = getActuateConfig();
+            const siteOrigin = config?.site?.url ?? config?.seo?.siteUrl ?? process.env.NEXT_PUBLIC_SITE_URL ?? null;
+            const result = await processContentHealthScan(db(), { siteOrigin });
+            return json({ data: result });
+        }
+        catch (err) {
+            return internalError(err, 'cron content-health');
+        }
+    };
+    router.get('/cron/content-health', cronContentHealth);
+    router.post('/cron/content-health', cronContentHealth);
     router.get('/scheduling/calendar', async (request) => {
         try {
             const auth = await requireAuth(request);