@consilioweb/payload-seo-analyzer 1.8.1 → 1.10.0

package/README.md

@@ -631,13 +631,18 @@ All endpoints are prefixed with the configured `endpointBasePath` (default: `/se
 | `GET` | `/indexation-audit` | Cross-page indexation hygiene — surfaces every `noindex` / canonical problem in one place |
 | `GET` | `/core-web-vitals` | Real LCP/INP/CLS via PageSpeed Insights — informational, on-demand, SSRF-safe (own origin only) |
 | `GET` `POST` | `/gsc/*` | Google Search Console OAuth (opt-in `features.gscApi`): `status`, `auth`, `callback`, `data`, `disconnect` |
+| `POST` `GET` | `/rank-snapshot` `/rank-history` | Rank tracking (opt-in `features.gscApi`) — daily GSC position snapshots + movement over time |
+| `GET` `POST` | `/alerts-digest` `/alerts-run` | Monitoring digest (opt-in `features.alerts`) — score regressions, new 404s, ranking drops via webhook/email |
 | `GET` | `/history` | Score history data for trend charts |
 | `GET` | `/sitemap-audit` | Sitemap structure audit |
 | `GET` `PATCH` | `/settings` | Read or update SEO settings |
 | `POST` | `/suggest-links` | Internal link suggestions for a page |
 | `POST` | `/create-redirect` | Create a single redirect entry |
 | `GET` `POST` `PATCH` `DELETE` | `/redirects` | Full CRUD for redirect management |
-| `POST` | `/ai-generate` | AI-powered meta title/description generation |
+| `POST` | `/ai-generate` | Heuristic meta title/description generation (no API key needed) |
+| `POST` | `/ai-rewrite` | Rewrite a single meta field (Claude if `ANTHROPIC_API_KEY` set, else heuristic) |
+| `POST` | `/ai-optimize` | **AI SEO Optimize** — scan a page, propose optimized meta (Claude Opus 4.8 by default), server-validated; applied in one click from the sidebar |
+| `GET` `POST` | `/alt-text-audit` `/ai-alt-text` | **AI image alt-text** (Claude vision, `features.aiFeatures`) — list images missing alt, generate + apply |
 | `GET` | `/cannibalization` | Detect keyword cannibalization |
 | `POST` | `/external-links` | Check external link status (live HTTP checks with SSRF protection) |
 | `GET` | `/sitemap-config` | Sitemap configuration data |
@@ -647,6 +652,75 @@ All endpoints are prefixed with the configured `endpointBasePath` (default: `/se
 | `GET` | `/link-graph` | Internal link graph data |
 | `GET` `POST` `DELETE` | `/seo-logs` | 404 log management (POST supports secret-header auth) |
 
+### AI SEO Optimize (`/ai-optimize`)
+
+One-click **"scan → propose → apply"** assistant in the editor sidebar (button **“Optimiser avec l'IA”**):
+
+1. Runs the real SEO engine on the current page and collects the failing/warning meta checks.
+2. Sends the content + detected issues to Claude, which proposes an optimized **meta title**, **meta description** and (only when missing) a **focus keyword**, applying the same SEO 2026 rules the engine enforces.
+3. The editor reviews the *current → suggested* diff + rationale and **applies in one click** — the fields are filled, then saved as usual.
+
+Scope is **meta only** by design: the SEO 2026 analysis classifies mass AI-generated body content as a spam/penalty risk, so the feature never rewrites page content.
+
+**Setup (opt-in, billed to your own Anthropic key):**
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | — | Your Anthropic API key, read **only** server-side (never from the client). **Without it, the feature falls back to the built-in heuristic generators.** |
+| `SEO_AI_MODEL` | `claude-opus-4-8` | Override the Claude model (e.g. `claude-haiku-4-5` for a cheaper/faster option). |
+
+The endpoint is gated behind `features.aiFeatures` (default `true`). Suggestions are **validated/clamped server-side** (title ≤ 70, description ≤ 160, focus keyword only filled when empty) so what gets applied is always rule-compliant, regardless of the model's output.
+
+### AI image alt-text (`/ai-alt-text`)
+
+Generate the `alt` attribute for images that lack one (accessibility + SEO) using **Claude vision**. The Performance view lists media missing alt; for each image you **Generate**, review/edit, then **Apply** in one click. Gated by `features.aiFeatures`; uses `ANTHROPIC_API_KEY` and `SEO_AI_MODEL` (default `claude-opus-4-8`). Images are fetched server-side and must be on the site origin (or `SEO_MEDIA_ORIGIN`) — SSRF-safe.
+
+### Rank tracking & monitoring alerts
+
+- **Rank tracking** (opt-in `features.gscApi`): once Google Search Console is connected, the plugin snapshots **daily query positions** into `seo-rank-history` and shows **movement over time** in the Performance view. No extra setup beyond GSC.
+- **Monitoring alerts** (opt-in `features.alerts`): a periodic digest (default daily) reports **score regressions**, **new 404s** and **ranking drops** via **webhook and/or email**. Configure delivery with env vars:
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `SEO_ALERT_WEBHOOK_URL` | — | POST the digest JSON to this URL (Slack/Discord/automation). |
+| `SEO_ALERT_EMAIL` | — | Comma-separated recipients (uses Payload's email adapter). |
+| `SEO_ALERT_SCORE_DROP` | `10` | Minimum score drop to report. |
+| `SEO_ALERT_POSITION_DROP` | `5` | Minimum SERP positions lost to report. |
+| `SEO_ALERT_INTERVAL_HOURS` | `24` | Digest frequency. |
+
+### Frontend render helpers — produce the SEO, not just grade it
+
+Pure, dependency-free helpers to output the actual `<head>` metadata + JSON-LD from a Payload document, e.g. in a Next.js route:
+
+```ts
+import { buildSeoMetadata, buildJsonLd } from '@consilioweb/payload-seo-analyzer'
+
+export async function generateMetadata({ params }) {
+  const doc = await payload.findByID({ collection: 'pages', id, depth: 1 })
+  return buildSeoMetadata(doc, { collection: 'pages', siteName: 'My Site', siteUrl: 'https://example.com' })
+  // → { title, description, alternates: { canonical, languages }, robots, openGraph, twitter }
+}
+
+// In a Server Component, render the JSON-LD:
+function PageJsonLd({ doc }) {
+  const { jsonLd } = buildJsonLd(doc, { collection: 'pages' })
+  return <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+}
+```
+
+`buildSeoMetadata` returns a structural subset of Next's `Metadata` (assignable to it). `buildJsonLd` reuses the exact builders behind the admin schema generator (Article, Product, LocalBusiness, FAQPage, BreadcrumbList, Organization, Person, Event, Recipe, Video). Also exported: `renderJsonLdScript`, `detectSchemaType`, `getSchemaImageUrl`, `SCHEMA_TYPES`.
+
+### Low-memory hosting (e.g. Infomaniak)
+
+The site-wide audit (`/admin/seo` dashboard) is the heaviest operation. On constrained shared Node hosting it is built **single-flight, in the background**: the first uncached load returns `202` and the dashboard shows a “generating…” state while it computes, then polls until ready — it never blocks or OOM-kills the process. Tune it via env vars if needed:
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `SEO_AUDIT_BATCH_SIZE` | `15` | Documents processed per batch. Lower it on very small hosts. |
+| `SEO_AUDIT_MAX_DOCS` | `1500` | Hard cap on documents audited. |
+
+For the lowest-memory tiers you can also set `features: { warmCache: false }` to skip the startup/hourly pre-load entirely.
+
 <img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="line">
 
 ## SEO Rules Reference