@actuate-media/cms-core 0.78.0 → 0.79.1

package/dist/api/routes/seo.js

@@ -8,7 +8,7 @@ import { syncSchemaTypeFields } from '../../seo/schema-sync.js';
 import { guardedDb } from '../guarded-db.js';
 import { recordAiCrawlerFromRequest, recordAiCrawlerHit } from '../../seo/ai-crawler-log.js';
 import { detectAiBot } from '../../seo/ai-bots.js';
-import { json, errorResponse, internalError, asRecord, normalizeSeoPage, hasModel, formatCompactNumber, modelNotAvailable, requireAuth, buildActionContext, WRITE_ROLES, requireRole, linkHealthLimiter, seoAuditLimiter, checkRateLimitAsync, clientIp, enforceDocumentReadAccess, } from '../route-helpers.js';
+import { json, errorResponse, internalError, asRecord, normalizeSeoPage, hasModel, formatCompactNumber, modelNotAvailable, requireAuth, buildActionContext, WRITE_ROLES, ADMIN_ROLES, requireRole, linkHealthLimiter, seoAuditLimiter, aiGenerateLimiter, checkRateLimitAsync, clientIp, enforceDocumentReadAccess, } from '../route-helpers.js';
 // Explicit risk order. A plain `severity: 'asc'` DB sort orders the values
 // alphabetically (critical, info, warning) which wrongly ranks `info` above
 // `warning`. Unknown severities sort last.
@@ -391,6 +391,480 @@ export function registerSeoRoutes(router) {
             return internalError(err, 'seo/issues');
         }
     });
+    router.get('/seo/issues/export-brief', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            if (!hasModel(db(), 'seoIssue')) {
+                const { buildSeoFixBriefMarkdown, fixBriefFilename } = await import('../../seo/fix-brief-export.js');
+                return json({
+                    data: {
+                        markdown: buildSeoFixBriefMarkdown({ issues: [], manualOnly: true }),
+                        filename: fixBriefFilename(),
+                        issueCount: 0,
+                    },
+                });
+            }
+            const url = new URL(request.url);
+            const severity = url.searchParams.get('severity');
+            const status = url.searchParams.get('status');
+            const auditRunId = url.searchParams.get('auditRunId');
+            const manualOnly = url.searchParams.get('manualOnly') !== 'false';
+            const includeContentBriefs = url.searchParams.get('includeContentBriefs') !== 'false';
+            const includeContentResearch = url.searchParams.get('includeContentResearch') !== 'false';
+            const where = {};
+            if (severity)
+                where.severity = severity;
+            if (status)
+                where.status = status;
+            else
+                where.status = { in: ['open', 'recurring'] };
+            if (auditRunId)
+                where.auditRunId = auditRunId;
+            const issues = sortIssuesBySeverity(await db().seoIssue.findMany({
+                where,
+                orderBy: { lastDetectedAt: 'desc' },
+                take: 500,
+            }));
+            let runAuditDate = null;
+            let runId = auditRunId;
+            if (auditRunId && hasModel(db(), 'seoAuditRun')) {
+                const run = await db().seoAuditRun.findUnique({ where: { id: auditRunId } });
+                runAuditDate = run?.finishedAt ?? run?.startedAt ?? null;
+            }
+            else if (hasModel(db(), 'seoAuditRun')) {
+                const lastRun = await db().seoAuditRun.findFirst({
+                    where: { status: 'COMPLETED' },
+                    orderBy: { startedAt: 'desc' },
+                });
+                runId = lastRun?.id ?? null;
+                runAuditDate = lastRun?.finishedAt ?? lastRun?.startedAt ?? null;
+            }
+            const { applySeoOverrides, getSeoOverrides } = await import('../../seo/config-store.js');
+            const overrides = await getSeoOverrides(db()).catch(() => null);
+            const mergedConfig = applySeoOverrides(getActuateConfig(), overrides);
+            const siteSeo = mergedConfig?.seo;
+            const { buildSeoFixBriefMarkdown, filterFixBriefIssues, fixBriefFilename } = await import('../../seo/fix-brief-export.js');
+            const entityIds = [
+                ...new Set(issues
+                    .map((i) => i.entityId)
+                    .filter((id) => typeof id === 'string' && id.length > 0)),
+            ];
+            const updatedAtByEntity = new Map();
+            if ((includeContentBriefs || includeContentResearch) && entityIds.length > 0) {
+                const docs = await db().document.findMany({
+                    where: { id: { in: entityIds }, deletedAt: null },
+                    select: { id: true, updatedAt: true },
+                });
+                for (const doc of docs) {
+                    updatedAtByEntity.set(doc.id, doc.updatedAt instanceof Date ? doc.updatedAt : new Date(doc.updatedAt));
+                }
+            }
+            const { contentBriefFromMetadata } = await import('../../seo/issue-content-brief.js');
+            const { contentResearchFromMetadata } = await import('../../seo/issue-content-research.js');
+            const briefIssues = issues.map((i) => {
+                let contentBrief = null;
+                let contentResearch = null;
+                if (i.entityId) {
+                    const updatedAt = updatedAtByEntity.get(i.entityId);
+                    if (updatedAt) {
+                        if (includeContentBriefs) {
+                            contentBrief = contentBriefFromMetadata(i.metadata, i.type, i.entityId, updatedAt);
+                        }
+                        if (includeContentResearch) {
+                            contentResearch = contentResearchFromMetadata(i.metadata, i.type, i.entityId, updatedAt);
+                        }
+                    }
+                }
+                return {
+                    id: i.id,
+                    type: i.type,
+                    title: i.title,
+                    description: i.description ?? null,
+                    impact: i.impact ?? null,
+                    recommendation: i.recommendation ?? null,
+                    severity: i.severity,
+                    category: i.category,
+                    status: i.status,
+                    entityType: i.entityType ?? null,
+                    entityId: i.entityId ?? null,
+                    entityTitle: i.entityTitle ?? null,
+                    url: i.url ?? null,
+                    fixActionType: i.fixActionType ?? null,
+                    fixable: i.fixable ?? false,
+                    contentBrief,
+                    contentResearch,
+                };
+            });
+            const markdown = buildSeoFixBriefMarkdown({
+                siteName: siteSeo?.siteName ?? null,
+                siteUrl: siteSeo?.siteUrl ?? null,
+                auditRunId: runId,
+                auditDate: runAuditDate,
+                issues: briefIssues,
+                manualOnly,
+            });
+            const issueCount = filterFixBriefIssues(briefIssues, manualOnly).length;
+            return json({
+                data: {
+                    markdown,
+                    filename: fixBriefFilename(siteSeo?.siteName, runAuditDate ?? undefined),
+                    issueCount,
+                },
+            });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/export-brief');
+        }
+    });
+    router.post('/seo/issues/batch-content-briefs', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
+            if (roleErr)
+                return roleErr;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            if (!(await checkRateLimitAsync(aiGenerateLimiter, `ai-seo-batch-briefs:${auth.session.userId}`))) {
+                return errorResponse('AI rate limit reached. Try again in an hour.', 429);
+            }
+            const body = (await request.json().catch(() => ({})));
+            const severity = typeof body?.severity === 'string' ? body.severity : null;
+            const status = typeof body?.status === 'string' ? body.status : null;
+            const skipExisting = body?.skipExisting !== false;
+            const includeResearch = body?.includeResearch === true;
+            const competitorUrls = Array.isArray(body?.competitorUrls)
+                ? body.competitorUrls.filter((u) => typeof u === 'string')
+                : undefined;
+            const issueIds = Array.isArray(body?.issueIds)
+                ? body.issueIds.filter((id) => typeof id === 'string' && id.length > 0)
+                : null;
+            const where = {};
+            if (severity)
+                where.severity = severity;
+            if (status)
+                where.status = status;
+            else
+                where.status = { in: ['open', 'recurring'] };
+            let issues = await db().seoIssue.findMany({
+                where,
+                orderBy: { lastDetectedAt: 'desc' },
+                take: 500,
+            });
+            if (issueIds?.length) {
+                const idSet = new Set(issueIds);
+                issues = issues.filter((i) => idSet.has(i.id));
+            }
+            const { supportsContentBrief } = await import('../../seo/issue-content-brief.js');
+            const eligible = issues.filter((i) => supportsContentBrief(i.type));
+            const entityIds = [
+                ...new Set(eligible
+                    .map((i) => i.entityId)
+                    .filter((id) => typeof id === 'string' && id.length > 0)),
+            ];
+            const { documentToAuditEntity, frontEndContentCollectionTypes } = await import('../../seo/audit-runner.js');
+            const { applySeoOverrides, getSeoOverrides } = await import('../../seo/config-store.js');
+            const collectionTypes = frontEndContentCollectionTypes(getActuateConfig());
+            const overrides = await getSeoOverrides(db()).catch(() => null);
+            const mergedConfig = applySeoOverrides(getActuateConfig(), overrides);
+            const contexts = new Map();
+            if (entityIds.length > 0) {
+                const docs = await db().document.findMany({
+                    where: { id: { in: entityIds }, deletedAt: null },
+                    select: {
+                        id: true,
+                        collection: true,
+                        title: true,
+                        slug: true,
+                        data: true,
+                        structuredData: true,
+                        plainText: true,
+                        publishedAt: true,
+                        updatedAt: true,
+                    },
+                });
+                for (const doc of docs) {
+                    contexts.set(doc.id, {
+                        collection: doc.collection,
+                        entity: documentToAuditEntity(doc, collectionTypes, mergedConfig?.seo),
+                        updatedAt: doc.updatedAt instanceof Date ? doc.updatedAt : new Date(doc.updatedAt),
+                    });
+                }
+            }
+            const { batchGenerateContentBriefs } = await import('../../seo/issue-batch-briefs.js');
+            const result = await batchGenerateContentBriefs(eligible.map((i) => ({
+                id: i.id,
+                type: i.type,
+                title: i.title,
+                description: i.description,
+                recommendation: i.recommendation,
+                entityId: i.entityId,
+                entityType: i.entityType,
+                metadata: i.metadata,
+            })), contexts, { db: db(), userId: auth.session.userId, collection: 'pages' }, { skipExisting, includeResearch, competitorUrls });
+            return json({ data: result });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/batch-content-briefs');
+        }
+    });
+    router.get('/seo/issues/:id/content-brief', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            const issue = await db().seoIssue.findUnique({ where: { id: params.id } });
+            if (!issue)
+                return errorResponse('Issue not found', 404);
+            const { supportsContentBrief, contentBriefFromMetadata } = await import('../../seo/issue-content-brief.js');
+            if (!supportsContentBrief(issue.type)) {
+                return json({ data: { supported: false, brief: null, stale: false } });
+            }
+            if (!issue.entityId) {
+                return json({ data: { supported: true, brief: null, stale: false } });
+            }
+            const loaded = await loadIssueFixContext(issue);
+            if ('error' in loaded)
+                return loaded.error;
+            const brief = contentBriefFromMetadata(issue.metadata, issue.type, issue.entityId, loaded.updatedAt);
+            const raw = asRecord(issue.metadata)?.contentBrief;
+            const stale = !!raw &&
+                typeof raw === 'object' &&
+                !Array.isArray(raw) &&
+                typeof raw.fingerprint === 'string' &&
+                !brief;
+            return json({ data: { supported: true, brief, stale } });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/:id/content-brief');
+        }
+    });
+    router.post('/seo/issues/:id/content-brief', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
+            if (roleErr)
+                return roleErr;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            if (!(await checkRateLimitAsync(aiGenerateLimiter, `ai-seo-content-brief:${auth.session.userId}`))) {
+                return errorResponse('AI rate limit reached. Try again in an hour.', 429);
+            }
+            const issue = await db().seoIssue.findUnique({ where: { id: params.id } });
+            if (!issue)
+                return errorResponse('Issue not found', 404);
+            const loaded = await loadIssueFixContext(issue);
+            if ('error' in loaded)
+                return loaded.error;
+            const { generateContentBrief, contentBriefToMetadata, supportsContentBrief } = await import('../../seo/issue-content-brief.js');
+            if (!supportsContentBrief(issue.type)) {
+                return errorResponse('This issue type does not support content briefs.', 422);
+            }
+            const result = await generateContentBrief({
+                id: issue.id,
+                type: issue.type,
+                title: issue.title,
+                description: issue.description,
+                recommendation: issue.recommendation,
+                entityId: issue.entityId,
+            }, { entity: loaded.entity, updatedAt: loaded.updatedAt }, { db: db(), userId: auth.session.userId, collection: loaded.collection });
+            if (!result.ok) {
+                if (result.code === 'unavailable' || result.code === 'feature_disabled') {
+                    return errorResponse(result.message, 503);
+                }
+                if (result.code === 'rate_limited') {
+                    return errorResponse(result.message, 429);
+                }
+                return errorResponse(result.message, 422);
+            }
+            const existingMeta = asRecord(issue.metadata);
+            await db().seoIssue.update({
+                where: { id: issue.id },
+                data: { metadata: { ...existingMeta, ...contentBriefToMetadata(result.brief) } },
+            });
+            return json({ data: { brief: result.brief } });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/:id/content-brief');
+        }
+    });
+    router.get('/seo/issues/:id/content-research', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            const issue = await db().seoIssue.findUnique({ where: { id: params.id } });
+            if (!issue)
+                return errorResponse('Issue not found', 404);
+            const { supportsContentResearch, contentResearchFromMetadata } = await import('../../seo/issue-content-research.js');
+            if (!supportsContentResearch(issue.type)) {
+                return json({ data: { supported: false, research: null, stale: false } });
+            }
+            if (!issue.entityId) {
+                return json({ data: { supported: true, research: null, stale: false } });
+            }
+            const loaded = await loadIssueFixContext(issue);
+            if ('error' in loaded)
+                return loaded.error;
+            const research = contentResearchFromMetadata(issue.metadata, issue.type, issue.entityId, loaded.updatedAt);
+            const raw = asRecord(issue.metadata)?.contentResearch;
+            const stale = !!raw &&
+                typeof raw === 'object' &&
+                !Array.isArray(raw) &&
+                typeof raw.fingerprint === 'string' &&
+                !research;
+            return json({ data: { supported: true, research, stale } });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/:id/content-research');
+        }
+    });
+    router.post('/seo/issues/:id/content-research', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
+            if (roleErr)
+                return roleErr;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            if (!(await checkRateLimitAsync(aiGenerateLimiter, `ai-seo-content-research:${auth.session.userId}`))) {
+                return errorResponse('AI rate limit reached. Try again in an hour.', 429);
+            }
+            const body = (await request.json().catch(() => ({})));
+            const competitorUrls = Array.isArray(body?.competitorUrls)
+                ? body.competitorUrls.filter((u) => typeof u === 'string')
+                : undefined;
+            const issue = await db().seoIssue.findUnique({ where: { id: params.id } });
+            if (!issue)
+                return errorResponse('Issue not found', 404);
+            const loaded = await loadIssueFixContext(issue);
+            if ('error' in loaded)
+                return loaded.error;
+            const { generateContentResearch, contentResearchToMetadata, supportsContentResearch } = await import('../../seo/issue-content-research.js');
+            if (!supportsContentResearch(issue.type)) {
+                return errorResponse('This issue type does not support topic research.', 422);
+            }
+            const result = await generateContentResearch({
+                id: issue.id,
+                type: issue.type,
+                title: issue.title,
+                description: issue.description,
+                recommendation: issue.recommendation,
+                entityId: issue.entityId,
+            }, { entity: loaded.entity, updatedAt: loaded.updatedAt }, { db: db(), userId: auth.session.userId, collection: loaded.collection }, { competitorUrls });
+            if (!result.ok) {
+                if (result.code === 'unavailable' || result.code === 'feature_disabled') {
+                    return errorResponse(result.message, 503);
+                }
+                if (result.code === 'rate_limited') {
+                    return errorResponse(result.message, 429);
+                }
+                return errorResponse(result.message, 422);
+            }
+            const existingMeta = asRecord(issue.metadata);
+            await db().seoIssue.update({
+                where: { id: issue.id },
+                data: { metadata: { ...existingMeta, ...contentResearchToMetadata(result.research) } },
+            });
+            return json({ data: { research: result.research } });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/:id/content-research');
+        }
+    });
+    router.post('/seo/issues/:id/research-and-brief', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
+            if (roleErr)
+                return roleErr;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            if (!(await checkRateLimitAsync(aiGenerateLimiter, `ai-seo-research-brief:${auth.session.userId}`))) {
+                return errorResponse('AI rate limit reached. Try again in an hour.', 429);
+            }
+            const body = (await request.json().catch(() => ({})));
+            const competitorUrls = Array.isArray(body?.competitorUrls)
+                ? body.competitorUrls.filter((u) => typeof u === 'string')
+                : undefined;
+            const issue = await db().seoIssue.findUnique({ where: { id: params.id } });
+            if (!issue)
+                return errorResponse('Issue not found', 404);
+            const loaded = await loadIssueFixContext(issue);
+            if ('error' in loaded)
+                return loaded.error;
+            const { generateContentResearch, contentResearchToMetadata, supportsContentResearch, contentResearchFromMetadata, } = await import('../../seo/issue-content-research.js');
+            const { generateContentBrief, contentBriefToMetadata, supportsContentBrief } = await import('../../seo/issue-content-brief.js');
+            if (!supportsContentBrief(issue.type)) {
+                return errorResponse('This issue type does not support content briefs.', 422);
+            }
+            const issueInput = {
+                id: issue.id,
+                type: issue.type,
+                title: issue.title,
+                description: issue.description,
+                recommendation: issue.recommendation,
+                entityId: issue.entityId,
+            };
+            const briefCtx = { entity: loaded.entity, updatedAt: loaded.updatedAt };
+            const deps = { db: db(), userId: auth.session.userId, collection: loaded.collection };
+            let research = supportsContentResearch(issue.type)
+                ? contentResearchFromMetadata(issue.metadata, issue.type, issue.entityId, loaded.updatedAt)
+                : null;
+            if (supportsContentResearch(issue.type) && !research) {
+                const researchResult = await generateContentResearch(issueInput, briefCtx, deps, {
+                    competitorUrls,
+                });
+                if (!researchResult.ok) {
+                    if (researchResult.code === 'unavailable' || researchResult.code === 'feature_disabled') {
+                        return errorResponse(researchResult.message, 503);
+                    }
+                    if (researchResult.code === 'rate_limited') {
+                        return errorResponse(researchResult.message, 429);
+                    }
+                    return errorResponse(researchResult.message, 422);
+                }
+                research = researchResult.research;
+            }
+            const briefResult = await generateContentBrief(issueInput, briefCtx, deps, { research });
+            if (!briefResult.ok) {
+                if (briefResult.code === 'unavailable' || briefResult.code === 'feature_disabled') {
+                    return errorResponse(briefResult.message, 503);
+                }
+                if (briefResult.code === 'rate_limited') {
+                    return errorResponse(briefResult.message, 429);
+                }
+                return errorResponse(briefResult.message, 422);
+            }
+            const existingMeta = asRecord(issue.metadata);
+            const metadata = {
+                ...existingMeta,
+                ...contentBriefToMetadata(briefResult.brief),
+                ...(research ? contentResearchToMetadata(research) : {}),
+            };
+            await db().seoIssue.update({
+                where: { id: issue.id },
+                data: { metadata },
+            });
+            return json({ data: { research, brief: briefResult.brief } });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/:id/research-and-brief');
+        }
+    });
     router.get('/seo/issues/:id', async (request, params) => {
         try {
             const auth = await requireAuth(request);
@@ -442,6 +916,208 @@ export function registerSeoRoutes(router) {
     router.post('/seo/issues/:id/resolve', (request, params) => setIssueStatus(request, params.id, 'resolved').catch((e) => internalError(e)));
     router.post('/seo/issues/:id/ignore', (request, params) => setIssueStatus(request, params.id, 'ignored').catch((e) => internalError(e)));
     router.post('/seo/issues/:id/reopen', (request, params) => setIssueStatus(request, params.id, 'open').catch((e) => internalError(e)));
+    /** Load the audit entity + collection for an issue's linked document. */
+    async function loadIssueFixContext(issue) {
+        if (!issue.entityId) {
+            return { error: errorResponse('This issue is not linked to a content item.', 422) };
+        }
+        const doc = await db().document.findFirst({
+            where: { id: issue.entityId, deletedAt: null },
+            select: {
+                id: true,
+                collection: true,
+                title: true,
+                slug: true,
+                data: true,
+                structuredData: true,
+                plainText: true,
+                publishedAt: true,
+                updatedAt: true,
+            },
+        });
+        if (!doc)
+            return { error: errorResponse('Content not found', 404) };
+        const { documentToAuditEntity, frontEndContentCollectionTypes } = await import('../../seo/audit-runner.js');
+        const { applySeoOverrides, getSeoOverrides } = await import('../../seo/config-store.js');
+        const collectionTypes = frontEndContentCollectionTypes(getActuateConfig());
+        const overrides = await getSeoOverrides(db()).catch(() => null);
+        const mergedConfig = applySeoOverrides(getActuateConfig(), overrides);
+        const entity = documentToAuditEntity(doc, collectionTypes, mergedConfig?.seo);
+        if (issue.entityType && entity.entityType !== issue.entityType) {
+            return { error: errorResponse('Issue entity type does not match the linked document.', 409) };
+        }
+        return {
+            collection: doc.collection,
+            entity,
+            updatedAt: doc.updatedAt instanceof Date ? doc.updatedAt : new Date(doc.updatedAt),
+            siteSeo: mergedConfig?.seo,
+        };
+    }
+    router.post('/seo/issues/:id/suggest-fix', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            const issue = await db().seoIssue.findUnique({ where: { id: params.id } });
+            if (!issue)
+                return errorResponse('Issue not found', 404);
+            const loaded = await loadIssueFixContext(issue);
+            if ('error' in loaded)
+                return loaded.error;
+            const issueInput = {
+                type: issue.type,
+                title: issue.title,
+                recommendation: issue.recommendation,
+                entityType: issue.entityType,
+                entityId: issue.entityId,
+            };
+            const fixCtx = {
+                entity: loaded.entity,
+                siteSeo: loaded.siteSeo,
+                updatedAt: loaded.updatedAt,
+            };
+            let aiDeps;
+            const adminErr = requireRole(auth.session.role, ADMIN_ROLES);
+            if (!adminErr &&
+                (await checkRateLimitAsync(aiGenerateLimiter, `ai-seo-fix-suggest:${auth.session.userId}`))) {
+                aiDeps = {
+                    db: db(),
+                    userId: auth.session.userId,
+                    collection: loaded.collection,
+                };
+            }
+            const { suggestIssueFix } = await import('../../seo/issue-fix.js');
+            const { pendingFixToMetadata } = await import('../../seo/issue-fix-ai.js');
+            const result = await suggestIssueFix(issueInput, fixCtx, aiDeps);
+            const existingMeta = asRecord(issue.metadata);
+            const nextMetadata = result.cacheForApply
+                ? { ...existingMeta, ...pendingFixToMetadata(result.suggestion) }
+                : { ...existingMeta, pendingFix: null };
+            await db().seoIssue.update({
+                where: { id: issue.id },
+                data: { metadata: nextMetadata },
+            });
+            return json({ data: { suggestion: result.suggestion } });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/:id/suggest-fix');
+        }
+    });
+    router.post('/seo/issues/:id/apply-fix', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const roleErr = requireRole(auth.session.role, WRITE_ROLES);
+            if (roleErr)
+                return roleErr;
+            if (!hasModel(db(), 'seoIssue'))
+                return modelNotAvailable('SeoIssue');
+            const body = (await request.json().catch(() => ({})));
+            const issue = await db().seoIssue.findUnique({ where: { id: params.id } });
+            if (!issue)
+                return errorResponse('Issue not found', 404);
+            if (issue.status === 'ignored') {
+                return errorResponse('Cannot apply a fix to an ignored issue. Reopen it first.', 409);
+            }
+            const loaded = await loadIssueFixContext(issue);
+            if ('error' in loaded)
+                return loaded.error;
+            const issueInput = {
+                type: issue.type,
+                title: issue.title,
+                recommendation: issue.recommendation,
+                entityType: issue.entityType,
+                entityId: issue.entityId,
+            };
+            const fixCtx = {
+                entity: loaded.entity,
+                siteSeo: loaded.siteSeo,
+                updatedAt: loaded.updatedAt,
+            };
+            const { suggestDeterministicFix, buildFixFingerprint } = await import('../../seo/issue-fix.js');
+            const { pendingFixFromMetadata } = await import('../../seo/issue-fix-ai.js');
+            const deterministic = suggestDeterministicFix(issueInput, fixCtx);
+            let suggestion = deterministic;
+            if (!deterministic.autoFixable || Object.keys(deterministic.patch).length === 0) {
+                const cached = pendingFixFromMetadata(issue.metadata);
+                const liveFingerprint = buildFixFingerprint(loaded.entity.entityId, issue.type, loaded.updatedAt);
+                if (!cached || !cached.autoFixable) {
+                    return errorResponse('This issue does not support an automatic fix.', 422);
+                }
+                if (body?.fingerprint && body.fingerprint !== cached.fingerprint) {
+                    return errorResponse('This fix is stale — the page changed since the suggestion was loaded. Expand the row again.', 409);
+                }
+                if (cached.fingerprint !== liveFingerprint) {
+                    return errorResponse('This fix is stale — the page changed since the suggestion was loaded. Expand the row again.', 409);
+                }
+                suggestion = {
+                    autoFixable: true,
+                    source: 'ai',
+                    fingerprint: cached.fingerprint,
+                    patch: cached.patch,
+                    changes: cached.changes,
+                    justification: cached.justification,
+                };
+            }
+            else if (body?.fingerprint && body.fingerprint !== suggestion.fingerprint) {
+                return errorResponse('This fix is stale — the page changed since the suggestion was loaded. Expand the row again.', 409);
+            }
+            if (!suggestion.autoFixable || Object.keys(suggestion.patch).length === 0) {
+                return errorResponse('This issue does not support an automatic fix.', 422);
+            }
+            const ctx = buildActionContext(auth.session, db());
+            try {
+                await updateDocumentSeoFields(loaded.collection, loaded.entity.entityId, suggestion.patch, ctx);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : '';
+                if (msg.includes('Access denied'))
+                    return errorResponse('Insufficient permissions', 403);
+                if (msg.includes('not found'))
+                    return errorResponse('Document not found', 404);
+                throw err;
+            }
+            const existingMeta = asRecord(issue.metadata);
+            const resolved = await db().seoIssue.update({
+                where: { id: issue.id },
+                data: {
+                    status: 'resolved',
+                    resolvedAt: new Date(),
+                    resolvedById: auth.session.userId,
+                    metadata: { ...existingMeta, pendingFix: null },
+                },
+            });
+            try {
+                await logEvent({
+                    event: 'document_updated',
+                    userId: auth.session.userId,
+                    details: {
+                        action: 'seo_issue_fix_applied',
+                        issueId: issue.id,
+                        issueType: issue.type,
+                        entityId: loaded.entity.entityId,
+                        fields: Object.keys(suggestion.patch),
+                        source: suggestion.source ?? 'deterministic',
+                    },
+                });
+            }
+            catch {
+                /* noop */
+            }
+            return json({
+                data: {
+                    issue: seoIssueToApi(resolved),
+                    applied: suggestion.changes,
+                },
+            });
+        }
+        catch (err) {
+            return internalError(err, 'seo/issues/:id/apply-fix');
+        }
+    });
     router.get('/seo/overview', async (request) => {
         try {
             const auth = await requireAuth(request);