@prenta/admin 0.92.0

package/src/lib/seo-service.ts

@@ -0,0 +1,1150 @@
+/**
+ * SEO service — typed client over the cms-core SEO REST endpoints.
+ *
+ * Every SEO admin component reads/writes through this module (never raw
+ * `cmsApi` / `fetch`), so the network contract lives in one place. Fetchers
+ * return typed data with safe fallbacks; mutations return `{ error?: string }`.
+ *
+ * Endpoint paths here are the contract implemented by cms-core
+ * `packages/cms-core/src/api/handlers.ts` across phases 2-3 and 6.
+ */
+import type { BrandAlignmentScoreResult } from '@prenta/core/brand-voice'
+import type { SEOAnalysisResult } from '@prenta/core/seo/analysis'
+import { cmsApi } from './api.js'
+
+/**
+ * `cmsApi` never throws — it returns `{ error, status }` on a network/HTTP
+ * failure. Read (GET) fetchers below must re-surface that as a thrown error so
+ * `useSeoResource` can distinguish "request failed" from "empty result".
+ * Without this, a failed `/seo/overview` would fall through to the empty
+ * fallback (a fake score of 0 / grade "Critical") and the error/retry UI would
+ * be permanently unreachable. Mutations intentionally return `{ error }` and do
+ * not use this.
+ */
+function throwIfError(res: { error?: string }): void {
+  if (res.error) throw new Error(res.error)
+}
+
+// ─── Shared enums ────────────────────────────────────────────────────
+
+export type SeoGrade = 'good' | 'fair' | 'poor' | 'critical'
+export type SeoSeverity = 'critical' | 'warning' | 'info'
+export type SeoIssueStatus = 'open' | 'ignored' | 'resolved' | 'recurring'
+export type SeoIssueCategory =
+  | 'content'
+  | 'technical'
+  | 'redirects'
+  | 'media'
+  | 'performance'
+  | 'schema'
+  | 'social'
+  | 'indexing'
+export type RedirectStatusCode = 301 | 302 | 307 | 308 | 410
+
+// ─── Overview ────────────────────────────────────────────────────────
+
+export interface SeoSiteScore {
+  score: number
+  grade: SeoGrade
+  /** Change vs the previous audit run, e.g. +6. */
+  delta: number | null
+  breakdown: { category: string; score: number; weight: number; contribution: number }[]
+}
+
+export interface SeoMetric {
+  label: string
+  value: string
+  helper: string
+  /** Optional trend direction for the helper colour. */
+  trend?: 'up' | 'down' | 'flat'
+}
+
+export interface SeoIssue {
+  id: string
+  auditRunId: string | null
+  entityType: string | null
+  entityId: string | null
+  entityTitle: string | null
+  url: string | null
+  severity: SeoSeverity
+  category: SeoIssueCategory
+  type: string
+  title: string
+  description: string | null
+  impact: string | null
+  recommendation: string | null
+  status: SeoIssueStatus
+  fixable: boolean
+  fixActionType: string | null
+  relatedEntityIds: string[]
+  source: string
+  firstDetectedAt: string | null
+  lastDetectedAt: string | null
+  resolvedAt: string | null
+}
+
+export interface QuickWin {
+  id: string
+  title: string
+  explanation: string
+  impact: 'High' | 'Medium' | 'Low'
+  issueId: string | null
+  fixActionType: string | null
+}
+
+export interface SearchPerformanceRow {
+  url: string
+  title: string
+  impressions: number
+  clicks: number
+  ctr: number
+  averagePosition: number
+}
+
+export interface SeoOverview {
+  siteScore: SeoSiteScore
+  metrics: SeoMetric[]
+  issues: SeoIssue[]
+  issuesSummary: { total: number; critical: number; warning: number; info: number }
+  quickWins: QuickWin[]
+  searchPerformance: SearchPerformanceRow[]
+  searchConsoleConnected: boolean
+  lastAuditRunId: string | null
+}
+
+const EMPTY_OVERVIEW: SeoOverview = {
+  siteScore: { score: 0, grade: 'critical', delta: null, breakdown: [] },
+  metrics: [],
+  issues: [],
+  issuesSummary: { total: 0, critical: 0, warning: 0, info: 0 },
+  quickWins: [],
+  searchPerformance: [],
+  searchConsoleConnected: false,
+  lastAuditRunId: null,
+}
+
+export async function fetchSeoOverview(): Promise<SeoOverview> {
+  const res = await cmsApi<SeoOverview>('/seo/overview')
+  throwIfError(res)
+  return res.data ?? EMPTY_OVERVIEW
+}
+
+export async function fetchSearchPerformance(
+  params: {
+    limit?: number
+  } = {},
+): Promise<SearchPerformanceRow[]> {
+  const qs = params.limit ? `?limit=${params.limit}` : ''
+  const res = await cmsApi<{ rows: SearchPerformanceRow[] }>(`/seo/search-performance${qs}`)
+  throwIfError(res)
+  return res.data?.rows ?? []
+}
+
+// ─── Content SEO ─────────────────────────────────────────────────────
+
+/** Schema.org types available in document SEO editors. */
+export const SEO_SCHEMA_TYPES = [
+  'Article',
+  'BlogPosting',
+  'WebPage',
+  'FAQPage',
+  'Product',
+  'Event',
+  'LocalBusiness',
+  'HowTo',
+  'Recipe',
+] as const
+
+export type SeoSchemaType = (typeof SEO_SCHEMA_TYPES)[number]
+
+export interface SeoContentRecord {
+  id: string
+  entityType: 'page' | 'post'
+  entityId: string
+  title: string
+  url: string
+  canonicalUrl: string | null
+  /** Rendered public title (after site title template). */
+  metaTitle: string | null
+  /** Stored page-specific portion for the `%page%` token. */
+  metaTitlePage?: string | null
+  siteName?: string | null
+  titleTemplate?: string | null
+  metaDescription: string | null
+  focusKeyword: string | null
+  keyTakeaway: string | null
+  ogTitle: string | null
+  ogDescription: string | null
+  ogImageId: string | null
+  ogImage: string | null
+  twitterTitle: string | null
+  twitterDescription: string | null
+  twitterImageId: string | null
+  noindex: boolean
+  nofollow: boolean
+  structuredDataType: string | null
+  structuredData: Record<string, unknown> | null
+  /** llms.txt curation: AUTO (heuristic), ALWAYS (pin), NEVER (exclude). */
+  llmsInclude: LlmsInclude
+  /** Curated agent-facing description for llms.txt (overrides the fallback). */
+  llmsDescription: string | null
+  /** Section/grouping override in llms.txt (defaults to the collection). */
+  llmsSection: string | null
+  /** Route this entry into the reserved `## Optional` section. */
+  llmsOptional: boolean
+  seoScore: number
+  seoGrade: SeoGrade
+  updatedAt: string | null
+}
+
+export type LlmsInclude = 'AUTO' | 'ALWAYS' | 'NEVER'
+
+export type ContentSeoFilter = 'all' | 'pages' | 'posts'
+
+export async function fetchSeoContentRecords(): Promise<SeoContentRecord[]> {
+  const res = await cmsApi<{ records: SeoContentRecord[] }>('/seo/content')
+  throwIfError(res)
+  return res.data?.records ?? []
+}
+
+export async function fetchSeoContentRecord(
+  entityType: string,
+  entityId: string,
+): Promise<SeoContentRecord | null> {
+  const res = await cmsApi<SeoContentRecord>(
+    `/seo/content/${entityType}/${encodeURIComponent(entityId)}`,
+  )
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export interface SeoFieldPayload {
+  metaTitle?: string
+  metaDescription?: string
+  canonicalUrl?: string
+  focusKeyword?: string
+  keyTakeaway?: string
+  ogTitle?: string
+  ogDescription?: string
+  ogImage?: string
+  twitterTitle?: string
+  twitterDescription?: string
+  twitterImage?: string
+  noindex?: boolean
+  nofollow?: boolean
+  structuredDataType?: string
+  structuredData?: Record<string, unknown>
+  llmsInclude?: LlmsInclude
+  llmsDescription?: string
+  llmsSection?: string
+  llmsOptional?: boolean
+}
+
+export async function fetchDocumentSeoAnalysis(documentId: string): Promise<SEOAnalysisResult> {
+  const res = await cmsApi<SEOAnalysisResult>(`/seo/analysis/${encodeURIComponent(documentId)}`)
+  throwIfError(res)
+  return res.data ?? { score: 0, checks: [] }
+}
+
+export async function updateSeoFields(
+  entityType: string,
+  entityId: string,
+  payload: SeoFieldPayload,
+): Promise<{ error?: string }> {
+  const res = await cmsApi(`/seo/content/${entityType}/${encodeURIComponent(entityId)}`, {
+    method: 'PUT',
+    body: JSON.stringify(payload),
+  })
+  return res.error ? { error: res.error } : {}
+}
+
+/** Pure search/filter over the content records (decoupled from network for tests). */
+export function applyContentSeoQuery(
+  records: SeoContentRecord[],
+  query: { search?: string; filter?: ContentSeoFilter },
+): SeoContentRecord[] {
+  const search = (query.search ?? '').trim().toLowerCase()
+  const filter = query.filter ?? 'all'
+  return records.filter((r) => {
+    if (filter === 'pages' && r.entityType !== 'page') return false
+    if (filter === 'posts' && r.entityType !== 'post') return false
+    if (search) {
+      const haystack = [
+        r.title,
+        r.url,
+        r.metaTitle ?? '',
+        r.metaDescription ?? '',
+        String(r.seoScore),
+        r.entityType,
+      ]
+        .join(' ')
+        .toLowerCase()
+      if (!haystack.includes(search)) return false
+    }
+    return true
+  })
+}
+
+// ─── Audit ───────────────────────────────────────────────────────────
+
+export type SeoAuditScope = 'full' | 'content' | 'technical' | 'redirect'
+
+export interface SeoAuditRun {
+  id: string
+  status: 'RUNNING' | 'COMPLETED' | 'FAILED'
+  scope: string
+  startedAt: string
+  finishedAt: string | null
+  siteScoreBefore: number | null
+  siteScoreAfter: number | null
+  pagesScanned: number
+  issuesFound: number
+  criticalCount: number
+  warningCount: number
+  infoCount: number
+  errorMessage: string | null
+}
+
+export async function runSeoAudit(
+  scope: SeoAuditScope = 'full',
+): Promise<{ run?: SeoAuditRun; error?: string }> {
+  const res = await cmsApi<SeoAuditRun>('/seo/audit', {
+    method: 'POST',
+    body: JSON.stringify({ scope }),
+  })
+  if (res.error) return { error: res.error }
+  return { run: res.data }
+}
+
+export async function fetchSeoAuditRuns(): Promise<SeoAuditRun[]> {
+  const res = await cmsApi<{ runs: SeoAuditRun[] }>('/seo/audits')
+  throwIfError(res)
+  return res.data?.runs ?? []
+}
+
+export async function fetchSeoAuditRun(auditRunId: string): Promise<SeoAuditRun | null> {
+  const res = await cmsApi<SeoAuditRun>(`/seo/audits/${encodeURIComponent(auditRunId)}`)
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export interface SeoIssueQuery {
+  severity?: SeoSeverity | 'all'
+  category?: SeoIssueCategory | 'all'
+  status?: SeoIssueStatus | 'all'
+  auditRunId?: string
+}
+
+export async function fetchSeoIssues(query: SeoIssueQuery = {}): Promise<SeoIssue[]> {
+  const params = new URLSearchParams()
+  if (query.severity && query.severity !== 'all') params.set('severity', query.severity)
+  if (query.category && query.category !== 'all') params.set('category', query.category)
+  if (query.status && query.status !== 'all') params.set('status', query.status)
+  if (query.auditRunId) params.set('auditRunId', query.auditRunId)
+  const qs = params.toString()
+  const res = await cmsApi<{ issues: SeoIssue[] }>(`/seo/issues${qs ? `?${qs}` : ''}`)
+  throwIfError(res)
+  return res.data?.issues ?? []
+}
+
+export async function fetchSeoIssue(issueId: string): Promise<SeoIssue | null> {
+  const res = await cmsApi<SeoIssue>(`/seo/issues/${encodeURIComponent(issueId)}`)
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export async function resolveSeoIssue(issueId: string): Promise<{ error?: string }> {
+  const res = await cmsApi(`/seo/issues/${encodeURIComponent(issueId)}/resolve`, { method: 'POST' })
+  return res.error ? { error: res.error } : {}
+}
+
+export async function ignoreSeoIssue(issueId: string): Promise<{ error?: string }> {
+  const res = await cmsApi(`/seo/issues/${encodeURIComponent(issueId)}/ignore`, { method: 'POST' })
+  return res.error ? { error: res.error } : {}
+}
+
+export async function reopenSeoIssue(issueId: string): Promise<{ error?: string }> {
+  const res = await cmsApi(`/seo/issues/${encodeURIComponent(issueId)}/reopen`, { method: 'POST' })
+  return res.error ? { error: res.error } : {}
+}
+
+// ─── Inline audit fixes (Phase 1 — deterministic, approval-gated) ───
+
+export interface SeoFixFieldChange {
+  field: string
+  label: string
+  before: string | boolean | null
+  after: string | boolean | null
+}
+
+export interface SeoIssueFixSuggestion {
+  autoFixable: boolean
+  source?: 'deterministic' | 'ai'
+  fixStrategy?: 'redirect' | 'fix-link'
+  aiUnavailable?: boolean
+  fingerprint: string
+  patch: Record<string, unknown>
+  changes: SeoFixFieldChange[]
+  justification: string
+}
+
+export async function fetchSeoIssueFixSuggestion(issueId: string): Promise<{
+  suggestion?: SeoIssueFixSuggestion
+  error?: string
+}> {
+  const res = await cmsApi<{ suggestion: SeoIssueFixSuggestion }>(
+    `/seo/issues/${encodeURIComponent(issueId)}/suggest-fix`,
+    { method: 'POST' },
+  )
+  if (res.error) return { error: res.error }
+  return { suggestion: res.data?.suggestion }
+}
+
+export async function applySeoIssueFix(
+  issueId: string,
+  fingerprint: string,
+): Promise<{ issue?: SeoIssue; error?: string }> {
+  const res = await cmsApi<{ issue: SeoIssue }>(
+    `/seo/issues/${encodeURIComponent(issueId)}/apply-fix`,
+    {
+      method: 'POST',
+      body: JSON.stringify({ fingerprint }),
+    },
+  )
+  if (res.error) return { error: res.error }
+  return { issue: res.data?.issue }
+}
+
+export interface SeoFixBriefExport {
+  markdown: string
+  filename: string
+  issueCount: number
+}
+
+export interface SeoFixBriefExportQuery {
+  severity?: SeoSeverity | 'all'
+  status?: SeoIssueStatus | 'all'
+  auditRunId?: string
+  /** Default true — only issues needing dev/content handoff. */
+  manualOnly?: boolean
+  /** Default true — embed cached AI content briefs when available. */
+  includeContentBriefs?: boolean
+  /** Default true — embed cached topic research when available. */
+  includeContentResearch?: boolean
+}
+
+export async function exportSeoFixBrief(
+  query: SeoFixBriefExportQuery = {},
+): Promise<{ data?: SeoFixBriefExport; error?: string }> {
+  const params = new URLSearchParams()
+  if (query.severity && query.severity !== 'all') params.set('severity', query.severity)
+  if (query.status && query.status !== 'all') params.set('status', query.status)
+  if (query.auditRunId) params.set('auditRunId', query.auditRunId)
+  if (query.manualOnly === false) params.set('manualOnly', 'false')
+  if (query.includeContentBriefs === false) params.set('includeContentBriefs', 'false')
+  if (query.includeContentResearch === false) params.set('includeContentResearch', 'false')
+  const qs = params.toString()
+  const res = await cmsApi<SeoFixBriefExport>(`/seo/issues/export-brief${qs ? `?${qs}` : ''}`)
+  if (res.error) return { error: res.error }
+  return { data: res.data }
+}
+
+/** Issue types with inline Approve fix in the Audit tab (keep in sync with cms-core). */
+export const SEO_INLINE_FIX_ISSUE_TYPES = new Set([
+  'meta-title-length',
+  'meta-description-length',
+  'accidental-noindex',
+  'missing-meta-title',
+  'missing-meta-description',
+  'missing-canonical',
+  'duplicate-meta-title',
+  'duplicate-meta-description',
+  'missing-structured-data',
+  'broken-internal-link',
+])
+
+export function isInlineSeoFixIssue(type: string): boolean {
+  return SEO_INLINE_FIX_ISSUE_TYPES.has(type)
+}
+
+export const SEO_CONTENT_BRIEF_ISSUE_TYPES = [
+  'thin-content',
+  'missing-h1',
+  'multiple-h1',
+  'missing-alt-text',
+] as const
+
+export function supportsSeoContentBrief(type: string): boolean {
+  return (SEO_CONTENT_BRIEF_ISSUE_TYPES as readonly string[]).includes(type)
+}
+
+export interface SeoContentBriefSection {
+  heading: string
+  bullets: string[]
+}
+
+export interface SeoContentBrief {
+  issueType: string
+  entityId: string
+  fingerprint: string
+  generatedAt: string
+  summary: string
+  suggestedH1: string | null
+  targetWordCount: number | null
+  topics: string[]
+  sections: SeoContentBriefSection[]
+  keyTakeawayDraft: string | null
+  geoNote: string | null
+}
+
+export async function fetchSeoContentBrief(issueId: string): Promise<{
+  supported?: boolean
+  brief?: SeoContentBrief | null
+  stale?: boolean
+  error?: string
+}> {
+  const res = await cmsApi<{ supported: boolean; brief: SeoContentBrief | null; stale: boolean }>(
+    `/seo/issues/${encodeURIComponent(issueId)}/content-brief`,
+  )
+  if (res.error) return { error: res.error }
+  return {
+    supported: res.data?.supported,
+    brief: res.data?.brief,
+    stale: res.data?.stale,
+  }
+}
+
+export async function generateSeoContentBrief(
+  issueId: string,
+): Promise<{ brief?: SeoContentBrief; error?: string }> {
+  const res = await cmsApi<{ brief: SeoContentBrief }>(
+    `/seo/issues/${encodeURIComponent(issueId)}/content-brief`,
+    { method: 'POST' },
+  )
+  if (res.error) return { error: res.error }
+  return { brief: res.data?.brief }
+}
+
+export const SEO_RESEARCH_ISSUE_TYPES = ['thin-content'] as const
+
+export function supportsSeoContentResearch(type: string): boolean {
+  return (SEO_RESEARCH_ISSUE_TYPES as readonly string[]).includes(type)
+}
+
+export interface SeoContentResearchCompetitor {
+  url: string
+  title: string
+  note: string
+}
+
+export interface SeoContentResearch {
+  issueType: string
+  entityId: string
+  fingerprint: string
+  generatedAt: string
+  focusKeyword: string | null
+  suggestedWordCount: number | null
+  outline: string[]
+  faqCandidates: string[]
+  entitiesToMention: string[]
+  competitorInsights: SeoContentResearchCompetitor[]
+  summary: string
+}
+
+export async function fetchSeoContentResearch(issueId: string): Promise<{
+  supported?: boolean
+  research?: SeoContentResearch | null
+  stale?: boolean
+  error?: string
+}> {
+  const res = await cmsApi<{
+    supported: boolean
+    research: SeoContentResearch | null
+    stale: boolean
+  }>(`/seo/issues/${encodeURIComponent(issueId)}/content-research`)
+  if (res.error) return { error: res.error }
+  return {
+    supported: res.data?.supported,
+    research: res.data?.research,
+    stale: res.data?.stale,
+  }
+}
+
+export async function generateSeoContentResearch(
+  issueId: string,
+  competitorUrls?: string[],
+): Promise<{ research?: SeoContentResearch; error?: string }> {
+  const res = await cmsApi<{ research: SeoContentResearch }>(
+    `/seo/issues/${encodeURIComponent(issueId)}/content-research`,
+    {
+      method: 'POST',
+      body: JSON.stringify({ competitorUrls: competitorUrls?.filter(Boolean) }),
+    },
+  )
+  if (res.error) return { error: res.error }
+  return { research: res.data?.research }
+}
+
+export async function researchAndBriefSeoIssue(
+  issueId: string,
+  competitorUrls?: string[],
+): Promise<{ research?: SeoContentResearch | null; brief?: SeoContentBrief; error?: string }> {
+  const res = await cmsApi<{ research: SeoContentResearch | null; brief: SeoContentBrief }>(
+    `/seo/issues/${encodeURIComponent(issueId)}/research-and-brief`,
+    {
+      method: 'POST',
+      body: JSON.stringify({ competitorUrls: competitorUrls?.filter(Boolean) }),
+    },
+  )
+  if (res.error) return { error: res.error }
+  return { research: res.data?.research, brief: res.data?.brief }
+}
+
+export interface BatchContentBriefResult {
+  generated: number
+  skipped: number
+  failed: number
+  results: Array<{ issueId: string; status: 'generated' | 'skipped' | 'failed'; error?: string }>
+}
+
+export interface BatchContentBriefQuery {
+  severity?: SeoSeverity | 'all'
+  status?: SeoIssueStatus | 'all'
+  issueIds?: string[]
+  skipExisting?: boolean
+  includeResearch?: boolean
+}
+
+export async function batchGenerateSeoContentBriefs(
+  query: BatchContentBriefQuery = {},
+): Promise<{ data?: BatchContentBriefResult; error?: string }> {
+  const body: Record<string, unknown> = {}
+  if (query.severity && query.severity !== 'all') body.severity = query.severity
+  if (query.status && query.status !== 'all') body.status = query.status
+  if (query.issueIds?.length) body.issueIds = query.issueIds
+  if (query.skipExisting === false) body.skipExisting = false
+  if (query.includeResearch) body.includeResearch = true
+
+  const res = await cmsApi<BatchContentBriefResult>('/seo/issues/batch-content-briefs', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+  if (res.error) return { error: res.error }
+  return { data: res.data }
+}
+
+// ─── Technical (sitemap / robots / crawl) ────────────────────────────
+
+export interface SitemapStatus {
+  sitemapUrl: string
+  lastGeneratedAt: string | null
+  pagesIncluded: number
+  pagesExcluded: number
+  autoRegenerateOnPublish: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+export interface CrawlSettings {
+  indexEntireSite: boolean
+  includeImagesInSitemap: boolean
+  includePostsInSitemap: boolean
+  sitemapEnabled: boolean
+  autoRegenerateSitemapOnPublish: boolean
+  pingSearchEnginesOnPublish: boolean
+}
+
+export async function fetchSitemapStatus(): Promise<SitemapStatus | null> {
+  const res = await cmsApi<SitemapStatus>('/seo/sitemap/status')
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export async function regenerateSitemap(): Promise<{ status?: SitemapStatus; error?: string }> {
+  const res = await cmsApi<SitemapStatus>('/seo/sitemap/regenerate', { method: 'POST' })
+  if (res.error) return { error: res.error }
+  return { status: res.data }
+}
+
+export async function fetchCrawlSettings(): Promise<CrawlSettings | null> {
+  const res = await cmsApi<CrawlSettings>('/seo/crawl-settings')
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export async function updateCrawlSettings(
+  payload: Partial<CrawlSettings>,
+): Promise<{ error?: string }> {
+  const res = await cmsApi('/seo/crawl-settings', {
+    method: 'PUT',
+    body: JSON.stringify(payload),
+  })
+  return res.error ? { error: res.error } : {}
+}
+
+// ─── AI crawler activity ─────────────────────────────────────────────
+
+export interface AiCrawlerRow {
+  bot: string
+  surface: string
+  category: string
+  hits: number
+  firstSeenAt: string
+  lastSeenAt: string
+}
+
+export interface AiCrawlerActivity {
+  enabled: boolean
+  rows: AiCrawlerRow[]
+  totals: { hits: number; bots: number; honeypot: number }
+}
+
+export async function fetchAiCrawlerActivity(): Promise<AiCrawlerActivity> {
+  const res = await cmsApi<AiCrawlerActivity>('/ai-crawlers')
+  throwIfError(res)
+  return res.data ?? { enabled: false, rows: [], totals: { hits: 0, bots: 0, honeypot: 0 } }
+}
+
+export interface RobotsConfig {
+  body: string
+  generated: boolean
+}
+
+export interface RobotsValidation {
+  valid: boolean
+  blocksEntireSite: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+export async function fetchRobotsTxt(): Promise<RobotsConfig | null> {
+  const res = await cmsApi<RobotsConfig>('/seo/robots')
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export async function updateRobotsTxt(body: string): Promise<{ error?: string }> {
+  const res = await cmsApi('/seo/robots', { method: 'PUT', body: JSON.stringify({ body }) })
+  return res.error ? { error: res.error } : {}
+}
+
+/** Client-side robots.txt validation (mirrors server-side checks). */
+export function validateRobotsTxt(body: string): RobotsValidation {
+  const errors: string[] = []
+  const warnings: string[] = []
+  const lines = body.split(/\r?\n/)
+  let blocksEntireSite = false
+  let sawUserAgent = false
+  let starAgent = false
+
+  for (const raw of lines) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const colon = line.indexOf(':')
+    if (colon === -1) {
+      errors.push(`Invalid directive (missing ":"): "${line}"`)
+      continue
+    }
+    const directive = line.slice(0, colon).trim().toLowerCase()
+    const value = line.slice(colon + 1).trim()
+    if (directive === 'user-agent') {
+      sawUserAgent = true
+      starAgent = value === '*'
+    } else if (directive === 'disallow') {
+      if (value === '/' && starAgent) blocksEntireSite = true
+    } else if (!['allow', 'sitemap', 'crawl-delay', 'host'].includes(directive)) {
+      warnings.push(`Unknown directive: "${directive}"`)
+    }
+  }
+
+  if (!sawUserAgent) errors.push('No User-agent directive found.')
+  if (blocksEntireSite) {
+    warnings.push('This configuration blocks the entire site from all crawlers.')
+  }
+  return { valid: errors.length === 0, blocksEntireSite, errors, warnings }
+}
+
+// ─── Redirects ───────────────────────────────────────────────────────
+
+export interface RedirectRule {
+  id: string
+  type: RedirectStatusCode
+  fromPath: string
+  toPath: string
+  enabled: boolean
+  priority: number
+  preserveQuery: boolean
+  hits: number
+  lastHitAt: string | null
+  /** True when lastHitAt is null — never recorded a public hit. */
+  neverHit: boolean
+  /** True when last hit was more than 60 days ago (never-hit is not stale). */
+  stale: boolean
+  source: string
+  notes: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface RedirectOverview {
+  activeRedirects: number
+  staleRedirects: number
+  neverHitRedirects: number
+  notFoundCount: number
+  notFoundHits: number
+  chainsAndLoops: number
+  trafficRecovered: number
+}
+
+export interface Redirect404 {
+  id: string
+  path: string
+  hits: number
+  lastSeenAt: string
+}
+
+export interface RedirectSuggestion {
+  id: string
+  fromPath: string
+  toPath: string
+  confidence: number
+  reason: string | null
+  status: 'open' | 'accepted' | 'dismissed'
+  hits: number
+  trend: string | null
+}
+
+export interface RedirectChain {
+  id: string
+  kind: 'chain' | 'loop'
+  hops: string[]
+  suggestedFrom: string
+  suggestedTo: string
+}
+
+export async function fetchRedirectOverview(): Promise<RedirectOverview> {
+  const res = await cmsApi<RedirectOverview>('/seo/redirects/overview')
+  throwIfError(res)
+  return (
+    res.data ?? {
+      activeRedirects: 0,
+      staleRedirects: 0,
+      neverHitRedirects: 0,
+      notFoundCount: 0,
+      notFoundHits: 0,
+      chainsAndLoops: 0,
+      trafficRecovered: 0,
+    }
+  )
+}
+
+export async function fetchRedirectRules(): Promise<RedirectRule[]> {
+  const rules: RedirectRule[] = []
+  let page = 1
+  let totalPages = 1
+  do {
+    const res = await cmsApi<{
+      rules: RedirectRule[]
+      totalPages?: number
+    }>(`/seo/redirects?page=${page}&pageSize=500`)
+    throwIfError(res)
+    rules.push(...(res.data?.rules ?? []))
+    totalPages = res.data?.totalPages ?? 1
+    page += 1
+  } while (page <= totalPages)
+  return rules
+}
+
+export interface RedirectRulePayload {
+  type: RedirectStatusCode
+  fromPath: string
+  toPath: string
+  enabled?: boolean
+  preserveQuery?: boolean
+  notes?: string
+}
+
+export async function createRedirectRule(
+  payload: RedirectRulePayload,
+): Promise<{ error?: string }> {
+  const res = await cmsApi('/seo/redirects', { method: 'POST', body: JSON.stringify(payload) })
+  return res.error ? { error: res.error } : {}
+}
+
+export async function updateRedirectRule(
+  redirectId: string,
+  payload: Partial<RedirectRulePayload>,
+): Promise<{ error?: string }> {
+  const res = await cmsApi(`/seo/redirects/${encodeURIComponent(redirectId)}`, {
+    method: 'PUT',
+    body: JSON.stringify(payload),
+  })
+  return res.error ? { error: res.error } : {}
+}
+
+export async function deleteRedirectRule(redirectId: string): Promise<{ error?: string }> {
+  const res = await cmsApi(`/seo/redirects/${encodeURIComponent(redirectId)}`, {
+    method: 'DELETE',
+  })
+  return res.error ? { error: res.error } : {}
+}
+
+export async function fetchRedirectChains(): Promise<RedirectChain[]> {
+  const res = await cmsApi<{ chains: RedirectChain[] }>('/seo/redirects/chains')
+  throwIfError(res)
+  return res.data?.chains ?? []
+}
+
+export async function flattenRedirectChain(chainId: string): Promise<{ error?: string }> {
+  const res = await cmsApi('/seo/redirects/flatten', {
+    method: 'POST',
+    body: JSON.stringify({ chainId }),
+  })
+  return res.error ? { error: res.error } : {}
+}
+
+export async function fetchRedirectSuggestions(): Promise<RedirectSuggestion[]> {
+  const res = await cmsApi<{ suggestions: RedirectSuggestion[] }>('/seo/redirects/suggestions')
+  throwIfError(res)
+  return res.data?.suggestions ?? []
+}
+
+export interface RedirectRecoverySettings {
+  aiRerank: boolean
+  autoApply: boolean
+  autoApplyMinConfidence: number
+}
+
+export async function fetchRedirectRecoverySettings(): Promise<RedirectRecoverySettings | null> {
+  const res = await cmsApi<RedirectRecoverySettings>('/seo/redirects/recovery-settings')
+  throwIfError(res)
+  return res.data ?? null
+}
+
+export async function saveRedirectRecoverySettings(
+  settings: Partial<RedirectRecoverySettings>,
+): Promise<{ error?: string }> {
+  const res = await cmsApi<RedirectRecoverySettings>('/seo/redirects/recovery-settings', {
+    method: 'PUT',
+    body: JSON.stringify(settings),
+  })
+  return res.error ? { error: res.error } : {}
+}
+
+export async function generate404RecoverySuggestions(): Promise<{
+  error?: string
+  autoApplied?: number
+}> {
+  const res = await cmsApi<{ created?: number; autoApplied?: number }>('/seo/redirects/suggest', {
+    method: 'POST',
+  })
+  if (res.error) return { error: res.error }
+  return { autoApplied: res.data?.autoApplied ?? 0 }
+}
+
+export async function acceptRedirectSuggestion(suggestionId: string): Promise<{ error?: string }> {
+  const res = await cmsApi(
+    `/seo/redirects/suggestions/${encodeURIComponent(suggestionId)}/accept`,
+    {
+      method: 'POST',
+    },
+  )
+  return res.error ? { error: res.error } : {}
+}
+
+export async function dismissRedirectSuggestion(suggestionId: string): Promise<{ error?: string }> {
+  const res = await cmsApi(
+    `/seo/redirects/suggestions/${encodeURIComponent(suggestionId)}/dismiss`,
+    { method: 'POST' },
+  )
+  return res.error ? { error: res.error } : {}
+}
+
+export async function exportRedirectsCsv(): Promise<{ csv?: string; error?: string }> {
+  const res = await cmsApi<{ csv: string }>('/seo/redirects/export')
+  if (res.error) return { error: res.error }
+  return { csv: res.data?.csv ?? '' }
+}
+
+export async function importRedirectsCsv(
+  csv: string,
+): Promise<{ imported?: number; errors?: string[]; error?: string }> {
+  const res = await cmsApi<{ imported: number; errors: string[] }>('/seo/redirects/import', {
+    method: 'POST',
+    body: JSON.stringify({ csv }),
+  })
+  if (res.error) return { error: res.error }
+  return { imported: res.data?.imported ?? 0, errors: res.data?.errors ?? [] }
+}
+
+// ─── AI Copilot ──────────────────────────────────────────────────────
+
+export interface SeoAiResult {
+  text?: string
+  alternatives?: string[]
+  structuredData?: Record<string, unknown>
+  brandAlignment?: BrandAlignmentScoreResult
+  /** True when the AI provider is not configured (graceful fallback). */
+  unavailable?: boolean
+}
+
+/**
+ * AI SEO endpoints report unavailability with two statuses: 501 (plugin-ai not
+ * installed) and 503 (installed but the provider isn't configured). Both map to
+ * the same graceful "AI unavailable" UX.
+ */
+function isAiUnavailable(status?: number): boolean {
+  return status === 501 || status === 503
+}
+
+export async function generateSeoField(
+  field:
+    | 'metaTitle'
+    | 'metaDescription'
+    | 'ogTitle'
+    | 'ogDescription'
+    | 'focusKeyword'
+    | 'keyTakeaway',
+  context: { entityType: string; entityId: string },
+): Promise<SeoAiResult> {
+  const res = await cmsApi<SeoAiResult>('/ai/seo/generate-field', {
+    method: 'POST',
+    body: JSON.stringify({ field, ...context }),
+  })
+  if (isAiUnavailable(res.status)) return { unavailable: true }
+  return res.data ?? {}
+}
+
+export async function explainSeoIssue(issueId: string): Promise<SeoAiResult> {
+  const res = await cmsApi<SeoAiResult>('/ai/seo/explain-issue', {
+    method: 'POST',
+    body: JSON.stringify({ issueId }),
+  })
+  if (isAiUnavailable(res.status)) return { unavailable: true }
+  return res.data ?? {}
+}
+
+export async function generateStructuredData(context: {
+  entityType: string
+  entityId: string
+  schemaType: string
+}): Promise<SeoAiResult> {
+  const res = await cmsApi<SeoAiResult>('/ai/seo/generate-schema', {
+    method: 'POST',
+    body: JSON.stringify(context),
+  })
+  if (isAiUnavailable(res.status)) return { unavailable: true }
+  return res.data ?? {}
+}
+
+export async function summarizeSeoAudit(): Promise<SeoAiResult> {
+  const res = await cmsApi<SeoAiResult>('/ai/seo/summarize', { method: 'POST' })
+  if (isAiUnavailable(res.status)) return { unavailable: true }
+  return res.data ?? {}
+}
+
+// ─── Link graph & AI suggestions ───────────────────────────────────────────
+
+export interface LinkGraphEntityRef {
+  id: string
+  title: string
+  url: string
+  path: string
+  collection: string
+  entityType: 'page' | 'post'
+  isHome: boolean
+}
+
+export interface LinkGraphSnapshot {
+  scannedAt: string
+  postsCrawled: number
+  internalLinks: number
+  externalLinks: number
+  internalRatio: number
+  orphanCount: number
+  orphaned: LinkGraphEntityRef[]
+  linkCoveragePercent: number
+  underLinked: Array<LinkGraphEntityRef & { outboundInternal: number }>
+  brokenLinkCount: number
+  aiIndexLastRunAt: string | null
+  aiIndexReady: boolean
+}
+
+export interface LinkHealthIssue {
+  id: string
+  page: string
+  url: string
+  status: number
+  type: string
+}
+
+export interface LinkSuggestion {
+  sourceEntityId: string
+  sourceTitle: string
+  sourceUrl: string
+  anchorText: string
+  confidence: number
+  excerpt: string
+}
+
+export async function fetchLinkGraphSnapshot(): Promise<LinkGraphSnapshot> {
+  const res = await cmsApi<LinkGraphSnapshot>('/seo/links/snapshot')
+  throwIfError(res)
+  if (!res.data) throw new Error('No link snapshot data')
+  return res.data
+}
+
+export async function runLinkAiIndex(): Promise<{
+  data?: {
+    indexedAt: string
+    entitiesIndexed: number
+    aiAvailable: boolean
+    message: string
+  }
+  error?: string
+}> {
+  const res = await cmsApi<{
+    indexedAt: string
+    entitiesIndexed: number
+    aiAvailable: boolean
+    message: string
+  }>('/seo/links/ai-index', { method: 'POST' })
+  if (res.error) return { error: res.error }
+  return { data: res.data }
+}
+
+export async function fetchLinkSuggestions(input: {
+  targetEntityId: string
+  targetEntityType: 'page' | 'post'
+  limit?: number
+}): Promise<{
+  data?: {
+    target: { id: string; title: string; url: string }
+    suggestions: LinkSuggestion[]
+  }
+  error?: string
+}> {
+  const res = await cmsApi<{
+    target: { id: string; title: string; url: string }
+    suggestions: LinkSuggestion[]
+  }>('/seo/links/suggest', { method: 'POST', body: JSON.stringify(input) })
+  if (res.error) return { error: res.error }
+  return { data: res.data }
+}
+
+export async function fetchLinkHealthIssues(): Promise<{
+  data?: { issues: LinkHealthIssue[]; checked: number; truncated: boolean }
+  error?: string
+}> {
+  const res = await cmsApi<{ truncated: boolean; checked: number; issues: LinkHealthIssue[] }>(
+    '/seo/link-health',
+  )
+  if (res.error) return { error: res.error }
+  return {
+    data: {
+      issues: res.data?.issues ?? [],
+      checked: res.data?.checked ?? 0,
+      truncated: res.data?.truncated ?? false,
+    },
+  }
+}