@prenta/admin 1.13.0 → 1.15.0

package/src/components/seo/SeoIssueFixPanel.tsx

@@ -16,12 +16,12 @@ import {
   supportsSeoContentResearch,
   type SeoContentBrief,
   type SeoContentResearch,
-  type SeoFixFieldChange,
   type SeoIssue,
   type SeoIssueFixSuggestion,
 } from '../../lib/seo-service.js'
 import { hasPlanFeature, type PlanInfo } from '../../lib/plan.js'
 import { PlanUpgradeCallout } from '../PlanUpgradeCallout.js'
+import { ChangePreview } from './ChangePreview.js'
 import { SeoErrorState, btnPrimary, btnSecondary } from './primitives.js'
 
 function approveButtonLabel(strategy: SeoIssueFixSuggestion['fixStrategy']): string {
@@ -56,49 +56,6 @@ function approveSuccessToast(strategy: SeoIssueFixSuggestion['fixStrategy']): st
   }
 }
 
-function formatValue(value: string | boolean | null): string {
-  if (value === null || value === '') return '—'
-  if (typeof value === 'boolean') return value ? 'Yes' : 'No'
-  if (value.length > 280) return `${value.slice(0, 277)}…`
-  return value
-}
-
-function ChangePreview({ changes }: { changes: SeoFixFieldChange[] }) {
-  if (changes.length === 0) return null
-  return (
-    <div className="border-border overflow-x-auto rounded-md border">
-      <table className="w-full min-w-[480px] text-sm" aria-label="Proposed SEO changes">
-        <thead>
-          <tr className="border-border bg-muted/40 text-muted-foreground border-b text-left">
-            <th scope="col" className="py-2 pr-3 pl-3 font-medium">
-              Field
-            </th>
-            <th scope="col" className="py-2 pr-3 font-medium">
-              Current
-            </th>
-            <th scope="col" className="py-2 pr-3 font-medium">
-              Proposed
-            </th>
-          </tr>
-        </thead>
-        <tbody className="divide-border divide-y">
-          {changes.map((c) => (
-            <tr key={c.field}>
-              <td className="text-foreground py-2 pr-3 pl-3 font-medium">{c.label}</td>
-              <td className="text-muted-foreground max-w-48 py-2 pr-3 wrap-break-word">
-                {formatValue(c.before)}
-              </td>
-              <td className="text-foreground max-w-48 py-2 pr-3 wrap-break-word">
-                {formatValue(c.after)}
-              </td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </div>
-  )
-}
-
 function ContentResearchCard({ research }: { research: SeoContentResearch }) {
   return (
     <div className="border-border bg-card space-y-3 rounded-md border p-4">

package/src/lib/api.ts

@@ -62,10 +62,27 @@ function appendLocaleParam(endpoint: string): string {
   return `${endpoint}${separator}locale=${encodeURIComponent(locale)}`
 }
 
+export interface CmsApiResult<T> {
+  data?: T
+  error?: string
+  /**
+   * Machine-readable error discriminator (e.g. IP_LOCKOUT_RISK, conflict) set
+   * by guard responses so callers can branch without parsing the message.
+   */
+  code?: string
+  /**
+   * The parsed non-2xx body, for the few endpoints that return structured
+   * detail beyond `error` / `code` (e.g. the 409 `fields` list from
+   * `/seo/autopilot/applied/:id/revert`). Callers must narrow it themselves.
+   */
+  errorBody?: unknown
+  status: number
+}
+
 export async function cmsApi<T = unknown>(
   endpoint: string,
   options: RequestInit = {},
-): Promise<{ data?: T; error?: string; code?: string; status: number }> {
+): Promise<CmsApiResult<T>> {
   const url = `${basePath}${appendLocaleParam(endpoint)}`
   const isFormData = typeof FormData !== 'undefined' && options.body instanceof FormData
 
@@ -98,9 +115,8 @@ export async function cmsApi<T = unknown>(
     if (!res.ok) {
       return {
         error: json.error || `Request failed (${res.status})`,
-        // Machine-readable error discriminator (e.g. IP_LOCKOUT_RISK) set by
-        // guard responses so callers can branch without parsing the message.
         code: typeof json.code === 'string' ? json.code : undefined,
+        errorBody: json,
         status: res.status,
       }
     }

package/src/lib/seo-service.ts

@@ -113,6 +113,8 @@ export interface SeoOverview {
   lastAuditRunId: string | null
   /** True when the last audit hit AUDIT_MAX_ENTITIES. */
   auditTruncated?: boolean
+  /** Cached AI issue fixes + open redirect suggestions awaiting review. */
+  pendingProposals?: { issueFixes: number; redirects: number }
 }
 
 const EMPTY_OVERVIEW: SeoOverview = {
@@ -826,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 {
@@ -1055,7 +1346,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
 }
 
@@ -1077,10 +1378,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
 }> {
@@ -1333,3 +1640,149 @@ export async function fetchLinkHealthIssues(): Promise<{
     },
   }
 }
+
+// ─── AI proposals inbox ─────────────────────────────────────────────────
+
+export interface SeoProposal {
+  /** `issue:<issueId>` | `redirect:<suggestionId>` */
+  id: string
+  kind: 'issue-fix' | 'redirect'
+  title: string
+  entity: { type: string | null; id: string | null; title: string | null; url: string | null }
+  changes: SeoFixFieldChange[]
+  justification: string
+  source: 'ai' | 'deterministic' | 'ai-404-recovery'
+  /** 0–1, redirects only. */
+  confidence: number | null
+  /** 0–100, issue fixes only. */
+  brandAlignment: number | null
+  generatedAt: string | null
+  /** Issue fixes only; redirects are keyed by id. */
+  fingerprint: string | null
+  /** Issue fixes: cached fingerprint ≠ live fingerprint. Redirects: always false. */
+  stale: boolean
+  issueType: string | null
+  severity: SeoSeverity | null
+  issueId: string | null
+  suggestionId: string | null
+}
+
+export interface SeoProposalsPayload {
+  proposals: SeoProposal[]
+  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 {
+  generated: number
+  skipped: number
+  failed: number
+  remaining: number
+  haltedReason: string | null
+}
+
+export interface SeoProposalBulkApplyItem {
+  kind: 'issue-fix' | 'redirect'
+  id: string
+  fingerprint?: string
+}
+
+/** Mirrors core's `BulkApplyItemStatus` (`seo/proposals-bulk-apply.ts`). */
+export type SeoProposalBulkApplyItemStatus =
+  | 'applied'
+  | 'stale'
+  | 'verify-failed'
+  | 'plan-required'
+  | 'not-found'
+  | 'not-allowed'
+  | 'not-fixable'
+  | 'invalid'
+  | 'still-live'
+  | 'error'
+  | 'pending'
+
+export interface SeoProposalBulkApplyResult {
+  results: Array<{
+    kind: 'issue-fix' | 'redirect'
+    id: string
+    status: SeoProposalBulkApplyItemStatus
+    reason?: string
+  }>
+  applied: number
+  failed: number
+  /** Items the server did not reach within its time budget — resubmit exactly these. */
+  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> {
+  // `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)
+  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<{
+  result?: SeoProposalGenerateResult
+  error?: string
+}> {
+  const res = await cmsApi<SeoProposalGenerateResult>('/seo/proposals/generate', {
+    method: 'POST',
+    body: JSON.stringify({ confirm: true }),
+  })
+  if (res.error) return { error: res.error }
+  return { result: res.data }
+}
+
+export async function bulkApplySeoProposals(items: SeoProposalBulkApplyItem[]): Promise<{
+  result?: SeoProposalBulkApplyResult
+  error?: string
+  /** True when the server refused because `allowBulkApply` is off for a represented feature. */
+  governanceBlocked?: boolean
+}> {
+  const res = await cmsApi<SeoProposalBulkApplyResult>('/seo/proposals/bulk-apply', {
+    method: 'POST',
+    body: JSON.stringify({ items }),
+  })
+  if (res.error) {
+    return res.code === 'governance_blocked'
+      ? { error: res.error, governanceBlocked: true }
+      : { error: res.error }
+  }
+  return { result: res.data }
+}
+
+export async function dismissSeoIssueFix(issueId: string): Promise<{ error?: string }> {
+  const res = await cmsApi(`/seo/issues/${encodeURIComponent(issueId)}/dismiss-fix`, {
+    method: 'POST',
+  })
+  return res.error ? { error: res.error } : {}
+}