@prenta/admin 1.14.0 → 1.16.0

package/src/lib/seo-service.ts

@@ -828,6 +828,295 @@ export async function sendTestDigest(): Promise<{ ok: boolean; to?: string; erro
   return { ok: true, to: res.data?.to }
 }
 
+// ─── SEO Autopilot ───────────────────────────────────────────────────
+// Mirrors `packages/cms-core/src/seo/autopilot-policy.ts` (`SeoAutopilotPolicy`,
+// `AutopilotRunSummary`) and the `/seo/autopilot/*` routes. The server is the
+// contract; keep these shapes in lock-step with it.
+
+export type SeoAutopilotIssueType =
+  | 'missing-meta-title'
+  | 'meta-title-length'
+  | 'duplicate-meta-title'
+  | 'missing-meta-description'
+  | 'meta-description-length'
+  | 'duplicate-meta-description'
+  | 'missing-canonical'
+  | 'accidental-noindex'
+  | 'missing-structured-data'
+  | 'redirect'
+
+export const SEO_AUTOPILOT_ISSUE_TYPES: readonly SeoAutopilotIssueType[] = [
+  'missing-meta-title',
+  'meta-title-length',
+  'duplicate-meta-title',
+  'missing-meta-description',
+  'meta-description-length',
+  'duplicate-meta-description',
+  'missing-canonical',
+  'accidental-noindex',
+  'missing-structured-data',
+  'redirect',
+]
+
+export type SeoAutopilotPauseReason = 'outcome_regression' | 'owner_unavailable' | 'manual'
+
+/**
+ * Run-level stop reasons the engine reports. `already_running` is
+ * informational (another tick held the run lease; nothing was written); the
+ * rest are warnings. The engine never stores raw error messages; a throwing
+ * phase is reported as the coded `apply_failed` / `run_failed`.
+ */
+export type SeoAutopilotHaltReason =
+  | 'disabled'
+  | 'paused'
+  | 'owner_unavailable'
+  | 'already_running'
+  | 'verify_failures'
+  | 'budget_exhausted'
+  | 'ledger_write_failed'
+  | 'apply_failed'
+  | 'run_failed'
+
+export interface SeoAutopilotRunSummary {
+  startedAt: string
+  durationMs: number
+  applied: number
+  verifyFailed: number
+  /** Outcome-watch reverts this tick. */
+  reverted: number
+  /** Gate reason → count (`policy_disabled`, `cap_per_run`, `brand_below_threshold`, …). */
+  gated: Record<string, number>
+  /**
+   * Non-applied apply statuses plus run-level counters: `error`,
+   * `gate_mismatch`, `after_unreadable`, `outcome_watch_error`,
+   * `outcome_revert_error`, `budget_exhausted`.
+   */
+  applyOutcomes: Record<string, number>
+  generated: { generated: number; skipped: number; failed: number; haltedReason: string | null }
+  halted: boolean
+  /** A {@link SeoAutopilotHaltReason}; unknown strings come from a newer core and are shown verbatim. */
+  haltedReason: string | null
+}
+
+export interface SeoAutopilotOutcomeWatch {
+  enabled: boolean
+  days: number
+  dropRatio: number
+  minPriorClicks: number
+}
+
+export interface SeoAutopilotGovernance {
+  /** Settings → AI "Requires approval" on the issue-fix feature vetoes every metadata type. */
+  issueFixApprovalRequired: boolean
+  /** Same veto for 404-recovery redirects. */
+  redirectApprovalRequired: boolean
+}
+
+export interface SeoAutopilotSettings {
+  enabled: boolean
+  enabledById: string | null
+  pausedAt: string | null
+  pausedReason: SeoAutopilotPauseReason | null
+  types: Partial<Record<SeoAutopilotIssueType, boolean>>
+  pausedTypes: Partial<Record<SeoAutopilotIssueType, string>>
+  minBrandAlignment: number
+  redirectMinConfidence: number
+  maxPerRun: number
+  maxPerDay: number
+  verifyFailuresPerRun: number
+  outcomeWatch: SeoAutopilotOutcomeWatch
+  lastRunAt: string | null
+  lastRun: SeoAutopilotRunSummary | null
+  governance: SeoAutopilotGovernance
+}
+
+/** Server-side ranges (`AUTOPILOT_LIMITS`) — mirrored so the card clamps before it PUTs. */
+export const SEO_AUTOPILOT_LIMITS = {
+  maxPerRun: { min: 1, max: 25 },
+  maxPerDay: { min: 1, max: 100 },
+  verifyFailuresPerRun: { min: 1, max: 10 },
+  minBrandAlignment: { min: 0, max: 100 },
+  redirectMinConfidence: { min: 50, max: 100 },
+  outcomeDays: { min: 7, max: 28 },
+  /** Whole percentages; the API takes a 0.2–0.8 ratio. */
+  dropPercent: { min: 20, max: 80 },
+  minPriorClicks: { min: 0, max: 100_000 },
+} as const
+
+/**
+ * A sparse PUT body: only the keys sent are written. `outcomeWatch` is itself
+ * partial. `resume` clears the engine-level pause; `resumeTypes` clears
+ * per-type pauses. Owner and pause state are never accepted from the client.
+ */
+export type SeoAutopilotSettingsPatch = Partial<
+  Pick<
+    SeoAutopilotSettings,
+    | 'enabled'
+    | 'types'
+    | 'minBrandAlignment'
+    | 'redirectMinConfidence'
+    | 'maxPerRun'
+    | 'maxPerDay'
+    | 'verifyFailuresPerRun'
+  >
+> & {
+  outcomeWatch?: Partial<SeoAutopilotOutcomeWatch>
+  resume?: boolean
+  resumeTypes?: SeoAutopilotIssueType[]
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+/**
+ * Validate the settings payload before handing it to the card: an unexpected
+ * body must render the error state, not crash on `settings.types[...]`.
+ * `governance` is normalised defensively (missing → no veto).
+ */
+function normalizeAutopilotSettings(raw: unknown): SeoAutopilotSettings | null {
+  if (!isRecord(raw)) return null
+  if (typeof raw.enabled !== 'boolean' || !isRecord(raw.types) || !isRecord(raw.outcomeWatch)) {
+    return null
+  }
+  const d = raw as unknown as SeoAutopilotSettings
+  const gov = isRecord(raw.governance) ? raw.governance : {}
+  return {
+    ...d,
+    pausedTypes: isRecord(raw.pausedTypes) ? d.pausedTypes : {},
+    lastRunAt: typeof raw.lastRunAt === 'string' ? raw.lastRunAt : null,
+    lastRun: isRecord(raw.lastRun) ? d.lastRun : null,
+    governance: {
+      issueFixApprovalRequired: gov.issueFixApprovalRequired === true,
+      redirectApprovalRequired: gov.redirectApprovalRequired === true,
+    },
+  }
+}
+
+export async function fetchAutopilotSettings(): Promise<
+  { settings: SeoAutopilotSettings } | { settings: null; error: string }
+> {
+  const res = await cmsApi<unknown>('/seo/autopilot/settings')
+  if (res.error) return { settings: null, error: res.error }
+  const settings = normalizeAutopilotSettings(res.data)
+  if (!settings) return { settings: null, error: 'Unexpected autopilot settings response' }
+  return { settings }
+}
+
+export async function updateAutopilotSettings(
+  patch: SeoAutopilotSettingsPatch,
+): Promise<{ ok: boolean; error?: string; settings?: SeoAutopilotSettings }> {
+  const res = await cmsApi<unknown>('/seo/autopilot/settings', {
+    method: 'PUT',
+    body: JSON.stringify(patch),
+  })
+  if (res.error) return { ok: false, error: res.error }
+  return { ok: true, settings: normalizeAutopilotSettings(res.data) ?? undefined }
+}
+
+export async function runAutopilotNow(): Promise<{
+  ok: boolean
+  error?: string
+  summary?: SeoAutopilotRunSummary
+}> {
+  const res = await cmsApi<SeoAutopilotRunSummary>('/seo/autopilot/run', {
+    method: 'POST',
+    body: '{}',
+  })
+  if (res.error) return { ok: false, error: res.error }
+  return { ok: true, summary: res.data }
+}
+
+export type SeoAutoApplyStatus = 'applied' | 'verify_failed' | 'reverted' | 'outcome_reverted'
+export type SeoAutoApplyOutcome = 'pending' | 'held' | 'regressed' | 'insufficient_data' | 'skipped'
+
+export interface SeoAutoApplyRow {
+  id: string
+  kind: 'issue-fix' | 'redirect'
+  issueType: string
+  entityId: string | null
+  /** Collection slug of the touched document; `null` for redirects. */
+  collection: string | null
+  entityTitle: string | null
+  entityUrl: string | null
+  path: string | null
+  before: Record<string, unknown> | null
+  after: Record<string, unknown>
+  gate: {
+    source: string
+    brandAlignment: number | null
+    confidence: number | null
+    checks: Record<string, boolean>
+  }
+  status: SeoAutoApplyStatus
+  outcome: SeoAutoApplyOutcome
+  outcomeMetrics: Record<string, unknown> | null
+  appliedAt: string
+  revertedAt: string | null
+  revertReason: string | null
+}
+
+export interface SeoAutoApplyList {
+  docs: SeoAutoApplyRow[]
+  total: number
+  page: number
+  pageSize: number
+  /** True for ADMIN callers — the only role the revert route accepts. */
+  canRevert: boolean
+}
+
+export async function fetchAutopilotApplied(params: {
+  page: number
+  pageSize: number
+  status?: SeoAutoApplyStatus
+  outcome?: SeoAutoApplyOutcome
+}): Promise<SeoAutoApplyList> {
+  const search = new URLSearchParams({
+    page: String(params.page),
+    pageSize: String(params.pageSize),
+  })
+  if (params.status) search.set('status', params.status)
+  if (params.outcome) search.set('outcome', params.outcome)
+  const res = await cmsApi<SeoAutoApplyList>(`/seo/autopilot/applied?${search.toString()}`)
+  throwIfError(res)
+  return (
+    res.data ?? {
+      docs: [],
+      total: 0,
+      page: params.page,
+      pageSize: params.pageSize,
+      canRevert: false,
+    }
+  )
+}
+
+/**
+ * Revert one ledgered change. A 409 (`code: 'conflict'`) means a human edited
+ * the same fields since autopilot wrote them; the server lists them in
+ * `fields` and `force: true` overrides.
+ */
+export async function revertAutopilotChange(
+  id: string,
+  force = false,
+): Promise<{ ok: true } | { ok: false; error: string; conflictFields?: string[] }> {
+  const res = await cmsApi<unknown>(`/seo/autopilot/applied/${encodeURIComponent(id)}/revert`, {
+    method: 'POST',
+    body: JSON.stringify({ force }),
+  })
+  if (res.error) {
+    if (res.code !== 'conflict') return { ok: false, error: res.error }
+    const fields = isRecord(res.errorBody) ? res.errorBody.fields : undefined
+    return {
+      ok: false,
+      error: res.error,
+      conflictFields: Array.isArray(fields)
+        ? fields.filter((f): f is string => typeof f === 'string')
+        : [],
+    }
+  }
+  return { ok: true }
+}
+
 // ─── AI crawler activity ─────────────────────────────────────────────
 
 export interface AiCrawlerRow {
@@ -851,6 +1140,111 @@ export async function fetchAiCrawlerActivity(): Promise<AiCrawlerActivity> {
   return res.data ?? { enabled: false, rows: [], totals: { hits: 0, bots: 0, honeypot: 0 } }
 }
 
+// ─── AI visibility (GEO measurement) ────────────────────────────────────────
+// Mirrors `packages/cms-core/src/seo/geo-report.ts` (`SeoGeoReport`) and the
+// `GET /seo/geo?days=N` route. The server is the contract; keep in lock-step.
+
+export type SeoGeoDays = 7 | 28 | 90
+export type SeoGeoBotCategory = 'training' | 'retrieval' | 'search'
+/**
+ * `blocked_still_crawling` = robots.txt disallows this bot's category, yet it
+ * was observed in the window — the signal the tab surfaces most prominently.
+ */
+export type SeoGeoBotPolicy = 'allowed' | 'blocked' | 'blocked_still_crawling'
+
+/** A top-path row's optional join to the document behind it. */
+export interface SeoGeoEntityRef {
+  entityId?: string
+  entityTitle?: string
+  /** Collection slug of the matched document; routes the editor link. */
+  collection?: string
+}
+
+/**
+ * Why `enabled` is `false`: the kill switch in Settings → SEO (`settings`) or
+ * the GEO tables are not migrated on the CMS database (`unavailable`).
+ */
+export type SeoGeoDisabledReason = 'settings' | 'unavailable'
+
+export interface SeoGeoReport {
+  enabled: boolean
+  /** Present only when `enabled` is `false`. */
+  disabledReason?: SeoGeoDisabledReason
+  window: { from: string; to: string; days: number }
+  /** ISO date of the earliest recorded row, or null when nothing has arrived. */
+  firstSeenAt: string | null
+  crawl: {
+    /** Whole-window crawl volume (incl. the capped "other" bucket). */
+    total: { hits: number; prevHits: number | null }
+    series: Array<{ date: string; hits: Record<string, number> }>
+    bots: Array<{
+      bot: string
+      category: SeoGeoBotCategory
+      hits: number
+      /** `null` when the prior window is not fully covered by data. */
+      prevHits: number | null
+      lastSeenAt: string | null
+      policy: SeoGeoBotPolicy
+    }>
+    topPaths: Array<SeoGeoEntityRef & { path: string; hits: number; bots: string[] }>
+    /** Hits that rolled into the capped "other" bucket. */
+    otherHits: number
+  }
+  referrals: {
+    total: { visits: number; prevVisits: number | null }
+    engines: Array<{ engine: string; visits: number; prevVisits: number | null }>
+    topPaths: Array<SeoGeoEntityRef & { path: string; visits: number; engines: string[] }>
+    /** Visits that rolled into the capped "other" bucket. */
+    otherVisits: number
+  }
+}
+
+export async function fetchSeoGeo(days: SeoGeoDays): Promise<SeoGeoReport> {
+  const res = await cmsApi<SeoGeoReport>(`/seo/geo?days=${days}`)
+  throwIfError(res)
+  // Validate the shape before handing it to the tab — an unexpected body must
+  // render the error state, not crash in render. `crawl.total` is the newest
+  // field on the wire; a `@prenta/core` deployed before it lands here.
+  const d = res.data
+  if (!d || typeof d.enabled !== 'boolean' || typeof d.crawl?.total?.hits !== 'number') {
+    throw new Error('Unexpected AI visibility response')
+  }
+  return d
+}
+
+// Mirrors `GET|PUT /seo/geo-settings` (`routes/seo-geo.ts`). The server clamps
+// `retentionDays` to `SEO_GEO_RETENTION` itself; the card clamps first so the
+// value it shows is the value that lands.
+export const SEO_GEO_RETENTION = { min: 7, max: 365 } as const
+
+export interface SeoGeoSettings {
+  /** Kill switch: when off the server drops incoming beacons. */
+  enabled: boolean
+  /** Daily-bucket retention, 7–365 days. */
+  retentionDays: number
+}
+
+export type SeoGeoSettingsPatch = Partial<SeoGeoSettings>
+
+/** Resolves `null` on an error envelope or a malformed body so the card renders its error state. */
+export async function fetchGeoSettings(): Promise<SeoGeoSettings | null> {
+  const res = await cmsApi<SeoGeoSettings>('/seo/geo-settings')
+  const d = res.data
+  if (!d || typeof d.enabled !== 'boolean' || typeof d.retentionDays !== 'number') return null
+  return { enabled: d.enabled, retentionDays: d.retentionDays }
+}
+
+export async function updateGeoSettings(
+  patch: SeoGeoSettingsPatch,
+): Promise<{ ok: boolean; error?: string }> {
+  const res = await cmsApi<{ ok: boolean }>('/seo/geo-settings', {
+    method: 'PUT',
+    body: JSON.stringify(patch),
+  })
+  if (res.error) return { ok: false, error: res.error }
+  return { ok: true }
+}
+
 export interface RobotsConfig {
   body: string
   generated: boolean
@@ -1057,7 +1451,17 @@ export async function fetchRedirectSuggestions(): Promise<RedirectSuggestion[]>
 
 export interface RedirectRecoverySettings {
   aiRerank: boolean
+  /**
+   * @deprecated Auto-apply moved to the SEO Autopilot engine (`types.redirect`
+   * on `SeoAutopilotSettings`, managed from the Settings → SEO "SEO Autopilot"
+   * card). The server still emits this for one release; nothing in the admin
+   * reads it. Remove together with the server field.
+   */
   autoApply: boolean
+  /**
+   * @deprecated Superseded by `SeoAutopilotSettings.redirectMinConfidence`,
+   * managed from the "SEO Autopilot" card. Server-emitted for one release only.
+   */
   autoApplyMinConfidence: number
 }
 
@@ -1079,10 +1483,16 @@ export async function saveRedirectRecoverySettings(
 
 export async function generate404RecoverySuggestions(): Promise<{
   error?: string
+  /**
+   * @deprecated Always `0`: generation no longer applies redirects. Auto-apply
+   * is the SEO Autopilot engine's job (Settings → SEO "SEO Autopilot" card);
+   * the server keeps the field for one release. Drop with the server field.
+   */
   autoApplied?: number
   /**
-   * Set when AI governance vetoed a requested auto-apply (eligible plans were
-   * stored as pending suggestions instead). Human-readable reason to surface.
+   * @deprecated Always `undefined` (server sends `null`): the governance veto
+   * now happens inside the autopilot gate, not at generation time. Kept for
+   * one release alongside `autoApplied`.
    */
   governanceBlocked?: string
 }> {
@@ -1367,6 +1777,15 @@ export interface SeoProposalsPayload {
   counts: { issueFixes: number; redirects: number; stale: number; eligibleForGeneration: number }
   /** `allowBulkApply` per feature, so the UI can disable batch approve up front. */
   governance: { issueFixBulk: boolean; redirectBulk: boolean }
+  /** Autopilot status strip for the proposals inbox (mirror of core's payload). */
+  autopilot: {
+    enabled: boolean
+    /** Set only while the engine is actually paused. */
+    pausedReason: string | null
+    lastRunAt: string | null
+    /** Live autopilot changes (`status = applied`) from the last 7 days. */
+    appliedLast7d: number
+  }
 }
 
 export interface SeoProposalGenerateResult {
@@ -1410,16 +1829,30 @@ export interface SeoProposalBulkApplyResult {
   pending: number
 }
 
+/** What the chip shows when the server says nothing about autopilot. */
+const AUTOPILOT_OFF: SeoProposalsPayload['autopilot'] = {
+  enabled: false,
+  pausedReason: null,
+  lastRunAt: null,
+  appliedLast7d: 0,
+}
+
 export async function fetchSeoProposals(): Promise<SeoProposalsPayload> {
-  const res = await cmsApi<SeoProposalsPayload>('/seo/proposals')
+  // `autopilot` is optional on the wire: a `@prenta/core` deployed before
+  // autopilot shipped omits it, and the tab must still render.
+  const res = await cmsApi<Omit<SeoProposalsPayload, 'autopilot'> & Partial<SeoProposalsPayload>>(
+    '/seo/proposals',
+  )
   throwIfError(res)
-  return (
-    res.data ?? {
+  if (!res.data) {
+    return {
       proposals: [],
       counts: { issueFixes: 0, redirects: 0, stale: 0, eligibleForGeneration: 0 },
       governance: { issueFixBulk: false, redirectBulk: false },
+      autopilot: AUTOPILOT_OFF,
     }
-  )
+  }
+  return { ...res.data, autopilot: res.data.autopilot ?? AUTOPILOT_OFF }
 }
 
 export async function generateSeoProposals(): Promise<{

package/src/views/SEO.tsx

@@ -1,11 +1,11 @@
 'use client'
 
 /**
- * SEO Operations Center — seven-tab workflow surface (Overview / Content /
- * Links / Technical / Redirects / Audit / Proposals). Tab + deep-link state is
- * driven by the `?tab=` query string so audits, issues, redirects, proposals,
- * and content editors are all linkable. All data flows through
- * `lib/seo-service.ts`.
+ * SEO Operations Center — eight-tab workflow surface (Overview / Content /
+ * Links / Technical / AI visibility / Redirects / Audit / Proposals). Tab +
+ * deep-link state is driven by the `?tab=` query string so audits, issues,
+ * redirects, proposals, and content editors are all linkable. All data flows
+ * through `lib/seo-service.ts`.
  */
 import * as Tabs from '@radix-ui/react-tabs'
 import {
@@ -18,6 +18,7 @@ import {
   Bot,
   Link2,
   Inbox,
+  Radar,
 } from 'lucide-react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { toast } from 'sonner'
@@ -35,6 +36,7 @@ import { RedirectsTab } from './seo/RedirectsTab.js'
 import { AuditTab } from './seo/AuditTab.js'
 import { LinksTab } from './seo/LinksTab.js'
 import { ProposalsTab } from './seo/ProposalsTab.js'
+import { AiVisibilityTab } from './seo/AiVisibilityTab.js'
 
 export interface SEOProps {
   onNavigate?: (path: string) => void
@@ -46,6 +48,7 @@ const TABS = [
   { id: 'content', label: 'Content SEO', icon: FileText },
   { id: 'links', label: 'Links', icon: Link2 },
   { id: 'technical', label: 'Technical', icon: Settings2 },
+  { id: 'ai-visibility', label: 'AI visibility', icon: Radar },
   { id: 'redirects', label: 'Redirects', icon: ArrowRightLeft },
   { id: 'audit', label: 'Audit', icon: ClipboardCheck },
   { id: 'proposals', label: 'Proposals', icon: Inbox },
@@ -74,6 +77,7 @@ export const SEO_DEEP_PATHS = [
   '/seo/links',
   '/seo/audit',
   '/seo/proposals',
+  '/seo/ai-visibility',
   '/seo',
 ] as const
 
@@ -96,6 +100,8 @@ export function seoTabForPath(pathname: string): TabId | null {
       return 'audit'
     case '/seo/proposals':
       return 'proposals'
+    case '/seo/ai-visibility':
+      return 'ai-visibility'
     case '/seo':
       return 'overview'
     default:
@@ -281,10 +287,13 @@ export function SEO({ onNavigate, initialTab = 'overview' }: SEOProps) {
               {activeTab === 'links' && <LinksTab onNavigate={onNavigate} planInfo={planInfo} />}
             </Tabs.Content>
             <Tabs.Content value="technical" tabIndex={-1}>
-              {activeTab === 'technical' && <TechnicalTab />}
+              {activeTab === 'technical' && <TechnicalTab onNavigate={onNavigate} />}
+            </Tabs.Content>
+            <Tabs.Content value="ai-visibility" tabIndex={-1}>
+              {activeTab === 'ai-visibility' && <AiVisibilityTab onNavigate={onNavigate} />}
             </Tabs.Content>
             <Tabs.Content value="redirects" tabIndex={-1}>
-              {activeTab === 'redirects' && <RedirectsTab />}
+              {activeTab === 'redirects' && <RedirectsTab onNavigate={onNavigate} />}
             </Tabs.Content>
             <Tabs.Content value="audit" tabIndex={-1}>
               {activeTab === 'audit' && (