@prenta/admin 1.15.0 → 1.17.0

package/src/lib/seo-service.ts

@@ -501,15 +501,30 @@ export async function fetchSeoIssueFixSuggestion(issueId: string): Promise<{
   return { suggestion: res.data?.suggestion }
 }
 
+/**
+ * Per-approval refinements for an `add-section` (FAQ) fix. Both are ignored by
+ * the server for every other fix strategy.
+ */
+export interface SeoApplyFixOptions {
+  /** Indices into `section.content.items` to keep; the server requires at least two. */
+  includeItems?: number[]
+  /** Replacement section heading (server trims, then enforces `FAQ_HEADING_MAX`, mirrored from core). */
+  headingOverride?: string
+}
+
 export async function applySeoIssueFix(
   issueId: string,
   fingerprint: string,
+  opts?: SeoApplyFixOptions,
 ): Promise<{ issue?: SeoIssue; error?: string }> {
+  const body: Record<string, unknown> = { fingerprint }
+  if (opts?.includeItems) body.includeItems = opts.includeItems
+  if (opts?.headingOverride !== undefined) body.headingOverride = opts.headingOverride
   const res = await cmsApi<{ issue: SeoIssue }>(
     `/seo/issues/${encodeURIComponent(issueId)}/apply-fix`,
     {
       method: 'POST',
-      body: JSON.stringify({ fingerprint }),
+      body: JSON.stringify(body),
     },
   )
   if (res.error) return { error: res.error }
@@ -561,6 +576,7 @@ export const SEO_INLINE_FIX_ISSUE_TYPES = new Set([
   'duplicate-meta-title',
   'duplicate-meta-description',
   'missing-structured-data',
+  'faq-schema-missing',
   'broken-internal-link',
   'orphan-page',
 ])
@@ -843,6 +859,7 @@ export type SeoAutopilotIssueType =
   | 'missing-canonical'
   | 'accidental-noindex'
   | 'missing-structured-data'
+  | 'faq-schema-missing'
   | 'redirect'
 
 export const SEO_AUTOPILOT_ISSUE_TYPES: readonly SeoAutopilotIssueType[] = [
@@ -855,6 +872,7 @@ export const SEO_AUTOPILOT_ISSUE_TYPES: readonly SeoAutopilotIssueType[] = [
   'missing-canonical',
   'accidental-noindex',
   'missing-structured-data',
+  'faq-schema-missing',
   'redirect',
 ]
 
@@ -1140,6 +1158,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
@@ -1642,6 +1765,28 @@ export async function fetchLinkHealthIssues(): Promise<{
 }
 
 // ─── AI proposals inbox ─────────────────────────────────────────────────
+// Mirrors `packages/cms-core/src/seo/proposals.ts` (`SeoProposal`) and
+// `seo/faq-signals.ts` (`FaqSignals`). The server is the contract.
+
+/** Same union as core's `SeoProposalFixStrategy`; `null` for plain metadata writes. */
+export type SeoProposalFixStrategy = 'redirect' | 'fix-link' | 'insert-link' | 'add-section'
+
+/** Why a page got a `missing-faq` proposal (28-day window). */
+export interface SeoFaqSignals {
+  /**
+   * Answer-engine activity. `engines` carries the referrer registry's display
+   * names (`ChatGPT`, `Perplexity`, …), sorted; empty when only retrieval
+   * crawls were seen.
+   */
+  geo: { referralVisits: number; retrievalHits: number; engines: string[] } | null
+  /** Question-shaped Search Console queries, highest impressions first. */
+  queries: Array<{ query: string; impressions: number; clicks: number }>
+}
+
+export interface SeoFaqSectionDraft {
+  sectionType: 'faq'
+  content: { heading: string; items: Array<{ question: string; answer: string }> }
+}
 
 export interface SeoProposal {
   /** `issue:<issueId>` | `redirect:<suggestionId>` */
@@ -1665,6 +1810,22 @@ export interface SeoProposal {
   severity: SeoSeverity | null
   issueId: string | null
   suggestionId: string | null
+  /** Always `'redirect'` for redirect rows; `null` when the cached patch carries none. */
+  fixStrategy: SeoProposalFixStrategy | null
+  /**
+   * `add-section` only: the section approval will insert. `null` when the
+   * cached patch failed core's structural checks — the row must still render
+   * (badge + signals) but cannot be approved from the inbox.
+   */
+  section: SeoFaqSectionDraft | null
+  /**
+   * `add-section` only: verbatim page quotes parallel to `section.content.items`.
+   * A malformed row arrives as `sourceQuote: ''` — render as "no quote", never
+   * as an empty blockquote.
+   */
+  grounding: Array<{ sourceQuote: string }> | null
+  /** `missing-faq` only. */
+  signals: SeoFaqSignals | null
 }
 
 export interface SeoProposalsPayload {

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,7 +287,10 @@ 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 onNavigate={onNavigate} />}