@lynxflow/seo-engine 1.4.1 → 1.5.0

package/src/rss-syndication-feed.ts

@@ -0,0 +1,56 @@
+/**
+ * 📰 RSS 2.0 & Atom Syndication Feed Generator (Inspiration: pages-seo/feed.xml.js)
+ *
+ * Automatically generates standards-compliant RSS 2.0 and Atom feeds for published
+ * programmatic landing pages and articles to accelerate syndication and indexing.
+ */
+
+export interface FeedItem {
+  title: string;
+  url: string;
+  description: string;
+  publishedAt: string; // ISO date
+  author?: string;
+  category?: string;
+}
+
+export class RssSyndicationFeedGenerator {
+  /**
+   * Generates a valid RSS 2.0 XML string.
+   */
+  static generateRss2(opts: {
+    siteTitle: string;
+    siteUrl: string;
+    description: string;
+    items: FeedItem[];
+  }): string {
+    const itemsXml = opts.items
+      .map(
+        (item) => `
+    <item>
+      <title><![CDATA[${item.title}]]></title>
+      <link>${item.url}</link>
+      <guid isPermaLink="true">${item.url}</guid>
+      <description><![CDATA[${item.description}]]></description>
+      <pubDate>${new Date(item.publishedAt).toUTCString()}</pubDate>
+      ${item.category ? `<category>${item.category}</category>` : ""}
+      ${item.author ? `<author>${item.author}</author>` : ""}
+    </item>
+    `.trim(),
+      )
+      .join("\n");
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title><![CDATA[${opts.siteTitle}]]></title>
+    <link>${opts.siteUrl}</link>
+    <description><![CDATA[${opts.description}]]></description>
+    <atom:link href="${opts.siteUrl}/feed.xml" rel="self" type="application/rss+xml" />
+    <language>fr</language>
+    <lastBuildDate>${new Date().toUTCString()}</lastBuildDate>
+${itemsXml}
+  </channel>
+</rss>`.trim();
+  }
+}

package/src/schema-builder.ts

@@ -21,35 +21,82 @@ export class SchemaGraphBuilder {
     ratingValue?: string;
     reviewCount?: string;
     locale?: string;
+    reviews?: Array<{
+      authorName: string;
+      ratingValue: number;
+      reviewText: string;
+      datePublished?: string;
+    }>;
   }): Record<string, unknown> {
-    const graph: Record<string, unknown>[] = [
-      {
-        "@type": "Product",
-        "@id": `${opts.url}#product`,
-        name: opts.name,
-        description: opts.description,
-        inLanguage: opts.locale || "fr",
-        image: opts.image || `${opts.url}/api/og`,
-        brand: {
-          "@type": "Brand",
-          name: opts.brandName,
+    const productNode: Record<string, unknown> = {
+      "@type": "Product",
+      "@id": `${opts.url}#product`,
+      name: opts.name,
+      description: opts.description,
+      image: opts.image || `${opts.url}/api/og`,
+      brand: {
+        "@type": "Brand",
+        name: opts.brandName,
+      },
+    };
+
+    if (opts.locale) {
+      productNode.inLanguage = opts.locale;
+    }
+
+    // Automatically compute or attach real AggregateRating
+    if (opts.ratingValue && opts.reviewCount) {
+      productNode.aggregateRating = {
+        "@type": "AggregateRating",
+        ratingValue: opts.ratingValue,
+        reviewCount: opts.reviewCount,
+        bestRating: "5",
+        worstRating: "1",
+      };
+    } else if (opts.reviews && opts.reviews.length > 0) {
+      const avg = (
+        opts.reviews.reduce((acc, r) => acc + r.ratingValue, 0) / opts.reviews.length
+      ).toFixed(1);
+      productNode.aggregateRating = {
+        "@type": "AggregateRating",
+        ratingValue: avg,
+        reviewCount: opts.reviews.length.toString(),
+        bestRating: "5",
+        worstRating: "1",
+      };
+    }
+
+    // Attach individual authentic reviews if provided
+    if (opts.reviews && opts.reviews.length > 0) {
+      productNode.review = opts.reviews.map((r) => ({
+        "@type": "Review",
+        author: {
+          "@type": "Person",
+          name: r.authorName,
         },
-        aggregateRating: {
-          "@type": "AggregateRating",
-          ratingValue: opts.ratingValue || "4.9",
-          reviewCount: opts.reviewCount || "1280",
+        datePublished: r.datePublished || new Date().toISOString().split("T")[0],
+        reviewBody: r.reviewText,
+        reviewRating: {
+          "@type": "Rating",
+          ratingValue: r.ratingValue.toString(),
           bestRating: "5",
           worstRating: "1",
         },
-        offers: {
-          "@type": "Offer",
-          price: (opts.price || 49).toString(),
-          priceCurrency: opts.currency || "EUR",
-          availability: "https://schema.org/InStock",
-          url: opts.url,
-        },
-      },
-    ];
+      }));
+    }
+
+    // Only emit Offer if real price is provided
+    if (opts.price !== undefined) {
+      productNode.offers = {
+        "@type": "Offer",
+        price: opts.price.toString(),
+        priceCurrency: opts.currency || "EUR",
+        availability: "https://schema.org/InStock",
+        url: opts.url,
+      };
+    }
+
+    const graph: Record<string, unknown>[] = [productNode];
 
     if (opts.faqs && opts.faqs.length > 0) {
       graph.push({

package/src/seo-opportunities-decay.ts

@@ -0,0 +1,154 @@
+/**
+ * 🎯 Advanced SEO Opportunities & Content Decay Detector (Inspiration: crawlseo/seo-opportunities.ts)
+ *
+ * Implements mathematical models to detect:
+ * 1. Striking Distance Keywords (Positions 4 to 20 with high impressions)
+ * 2. Low CTR Gaps (Real CTR < Expected Industry Curve)
+ * 3. Content Decay (Pages losing > 30% traffic over 28-day windows)
+ * 4. Keyword Cannibalization (Multiple internal URLs splitting Google rankings)
+ */
+
+export interface KeywordMetric {
+  query: string;
+  url: string;
+  position: number;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+}
+
+export interface ContentDecayInput {
+  url: string;
+  previous28DaysClicks: number;
+  last28DaysClicks: number;
+}
+
+export interface OpportunityFinding {
+  type: "striking_distance" | "low_ctr" | "content_decay" | "cannibalization";
+  severity: "critical" | "high" | "medium" | "low";
+  title: string;
+  detail: string;
+  query?: string;
+  url?: string;
+  potentialTrafficGain?: number;
+  suggestedAction: string;
+}
+
+export class SeoOpportunitiesDecayDetector {
+  /**
+   * Expected organic CTR curve by Google SERP rank position.
+   */
+  static getExpectedCtr(position: number): number {
+    if (position <= 1) return 0.28;
+    if (position <= 2) return 0.15;
+    if (position <= 3) return 0.11;
+    if (position <= 5) return 0.07;
+    if (position <= 10) return 0.03;
+    if (position <= 20) return 0.01;
+    return 0.005;
+  }
+
+  /**
+   * Detects Striking Distance opportunities (Keywords ranked between #4 and #20).
+   */
+  static detectStrikingDistance(keywords: KeywordMetric[], minImpressions = 30): OpportunityFinding[] {
+    return keywords
+      .filter((k) => k.position >= 4 && k.position <= 20 && k.impressions >= minImpressions)
+      .sort((a, b) => b.impressions - a.impressions)
+      .map((k) => {
+        const targetPos = Math.max(1, k.position - 3);
+        const potentialClicks = Math.round(k.impressions * this.getExpectedCtr(targetPos)) - k.clicks;
+
+        return {
+          type: "striking_distance",
+          severity: k.position <= 10 ? "high" : "medium",
+          title: `🎯 Mot-clé à portée de main : "${k.query}" (#${k.position.toFixed(1)})`,
+          detail: `${k.impressions} impressions mensuelles actuelles. Atteindre le top 3 générerait environ +${Math.max(1, potentialClicks)} clics/mois.`,
+          query: k.query,
+          url: k.url,
+          potentialTrafficGain: Math.max(1, potentialClicks),
+          suggestedAction: "Ajoutez 1 lien interne contextualisé vers cette page et enrichissez la section FAQ avec ce terme.",
+        };
+      });
+  }
+
+  /**
+   * Detects Low CTR Gaps (Ranked in top 15 but underperforming in clicks).
+   */
+  static detectLowCtrGaps(keywords: KeywordMetric[], minImpressions = 50): OpportunityFinding[] {
+    return keywords
+      .filter((k) => k.impressions >= minImpressions && k.position <= 15)
+      .map((k) => {
+        const expected = this.getExpectedCtr(k.position);
+        const gap = expected - k.ctr;
+        return { ...k, expected, gap };
+      })
+      .filter((k) => k.gap > 0.02)
+      .sort((a, b) => b.impressions * b.gap - a.impressions * a.gap)
+      .map((k) => ({
+        type: "low_ctr" as const,
+        severity: "high" as const,
+        title: `⚡ CTR anormalement bas sur "${k.query}" (${(k.ctr * 100).toFixed(1)}% vs ${(k.expected * 100).toFixed(1)}% attendu)`,
+        detail: `Classé #${k.position.toFixed(1)} avec ${k.impressions} impressions, mais un taux de clic inférieur aux moyennes du secteur.`,
+        query: k.query,
+        url: k.url,
+        potentialTrafficGain: Math.round(k.impressions * k.gap),
+        suggestedAction: "Réécrivez la balise <title> et la méta-description avec des mots d'action, des chiffres ou un crochet d'actualité.",
+      }));
+  }
+
+  /**
+   * Detects Content Decay (Pages losing more than 30% of traffic).
+   */
+  static detectContentDecay(pages: ContentDecayInput[]): OpportunityFinding[] {
+    return pages
+      .filter((p) => p.previous28DaysClicks >= 20)
+      .map((p) => {
+        const dropRatio = (p.previous28DaysClicks - p.last28DaysClicks) / p.previous28DaysClicks;
+        return { ...p, dropRatio };
+      })
+      .filter((p) => p.dropRatio >= 0.3)
+      .sort((a, b) => b.dropRatio - a.dropRatio)
+      .map((p) => ({
+        type: "content_decay" as const,
+        severity: "critical" as const,
+        title: `📉 Déclin de contenu détecté (-${Math.round(p.dropRatio * 100)}% de trafic)`,
+        detail: `Le trafic est passé de ${p.previous28DaysClicks} à ${p.last28DaysClicks} clics sur les 28 derniers jours.`,
+        url: p.url,
+        potentialTrafficGain: p.previous28DaysClicks - p.last28DaysClicks,
+        suggestedAction: "Mettez à jour les données datées, ajoutez une section 2026 et vérifiez si des concurrents ont publié un meilleur guide.",
+      }));
+  }
+
+  /**
+   * Detects Keyword Cannibalization across internal URLs.
+   */
+  static detectCannibalization(keywords: KeywordMetric[]): OpportunityFinding[] {
+    const queryMap: Record<string, KeywordMetric[]> = {};
+
+    for (const k of keywords) {
+      if (!queryMap[k.query]) queryMap[k.query] = [];
+      queryMap[k.query].push(k);
+    }
+
+    const cannibalized: OpportunityFinding[] = [];
+
+    for (const [query, urls] of Object.entries(queryMap)) {
+      if (urls.length > 1) {
+        const totalImpressions = urls.reduce((acc, curr) => acc + curr.impressions, 0);
+        if (totalImpressions >= 20) {
+          cannibalized.push({
+            type: "cannibalization",
+            severity: "high",
+            title: `⚔️ Cannibalisation détectée sur "${query}" (${urls.length} URLs en compétition)`,
+            detail: `Les URLs suivantes se partagent les clics : ${urls.map((u) => u.url).join(", ")}.`,
+            query,
+            suggestedAction: "Fusionnez les deux contenus en une seule page maîtresse ou placez une balise canonique vers la plus performante.",
+          });
+        }
+      }
+    }
+
+    return cannibalized;
+  }
+}

package/src/serp-history-alerts.ts

@@ -0,0 +1,75 @@
+/**
+ * 📈 SERP Chronological History & Webhook Alert Engine (Pole 5)
+ *
+ * Tracks keyword rank history over time, detects ranking shifts,
+ * and triggers automated alerts (Top 3, Top 10, rank drop).
+ */
+
+export interface KeywordRankSnapshot {
+  keyword: string;
+  date: string; // ISO format: YYYY-MM-DD
+  position: number;
+  url: string;
+  searchEngine: "google-mobile" | "google-desktop" | "bing";
+}
+
+export interface RankShiftAlert {
+  keyword: string;
+  previousPosition: number;
+  newPosition: number;
+  shiftType: "entered-top-3" | "entered-top-10" | "critical-drop" | "improved";
+  message: string;
+  timestamp: string;
+}
+
+export class SerpRankHistoryEngine {
+  /**
+   * Evaluates position shifts between two snapshots and returns alerts if thresholds are breached.
+   */
+  static analyzeRankShift(
+    previousSnapshot: KeywordRankSnapshot,
+    currentSnapshot: KeywordRankSnapshot,
+  ): RankShiftAlert | null {
+    const prev = previousSnapshot.position;
+    const curr = currentSnapshot.position;
+
+    if (prev === curr) return null;
+
+    const diff = prev - curr; // Positive means gained positions, negative means dropped
+
+    if (curr <= 3 && prev > 3) {
+      return {
+        keyword: currentSnapshot.keyword,
+        previousPosition: prev,
+        newPosition: curr,
+        shiftType: "entered-top-3",
+        message: `🚀 Le mot-clé "${currentSnapshot.keyword}" a pénétré le TOP 3 (#${curr}) !`,
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    if (curr <= 10 && prev > 10) {
+      return {
+        keyword: currentSnapshot.keyword,
+        previousPosition: prev,
+        newPosition: curr,
+        shiftType: "entered-top-10",
+        message: `🎯 Le mot-clé "${currentSnapshot.keyword}" est désormais en Première Page (#${curr}) !`,
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    if (diff <= -5) {
+      return {
+        keyword: currentSnapshot.keyword,
+        previousPosition: prev,
+        newPosition: curr,
+        shiftType: "critical-drop",
+        message: `⚠️ Chute de position détectée sur "${currentSnapshot.keyword}" (${prev} ➔ ${curr}).`,
+        timestamp: new Date().toISOString(),
+      };
+    }
+
+    return null;
+  }
+}

package/src/slug-engine.ts

@@ -0,0 +1,183 @@
+/**
+ * Global Multilingual Programmatic SEO Slug Engine
+ * Enforces the 6 golden rules of SEO-optimized URL paths across 10+ languages:
+ * English, French, German, Spanish, Italian, Portuguese, Dutch, Russian, Swedish, Polish.
+ *
+ * 1. Short & focused (3-5 target keywords)
+ * 2. Hyphen (-) as the sole delimiter
+ * 3. 100% lowercase, diacritics/accents stripped
+ * 4. Stop words removed for 10+ international languages
+ * 5. Zero dates/numbers for evergreen content
+ * 6. Primary keyword positioned first
+ */
+
+export const MULTILINGUAL_STOP_WORDS: Record<string, Set<string>> = {
+  // 🇬🇧 English
+  en: new Set([
+    "the", "a", "an", "and", "or", "for", "with", "without", "in", "on", "at",
+    "by", "to", "of", "from", "as", "is", "are", "be", "this", "that", "these",
+    "those", "how", "what", "which", "who", "whom", "when", "where", "why",
+    "your", "my", "our", "their", "its", "into", "over", "after", "before",
+  ]),
+
+  // 🇫🇷 French
+  fr: new Set([
+    "le", "la", "les", "un", "une", "des", "du", "de", "d", "l", "pour", "avec",
+    "sans", "sur", "sous", "dans", "par", "et", "ou", "a", "au", "aux", "en",
+    "ce", "cet", "cette", "ces", "son", "sa", "ses", "leur", "leurs", "notre",
+    "votre", "nos", "vos", "qui", "que", "quoi", "dont", "comment", "pourquoi",
+  ]),
+
+  // 🇩🇪 German
+  de: new Set([
+    "der", "die", "das", "ein", "eine", "eines", "einer", "einem", "einen",
+    "und", "oder", "fur", "für", "mit", "ohne", "auf", "unter", "in", "im", "von",
+    "vom", "zu", "zum", "zur", "bei", "beim", "nach", "aus", "uber", "über", "vor",
+    "wie", "was", "wer", "warum", "ihr", "ihre", "sein", "seine", "mein",
+  ]),
+
+  // 🇪🇸 Spanish
+  es: new Set([
+    "el", "la", "los", "las", "un", "una", "unos", "unas", "de", "del", "para",
+    "con", "sin", "en", "por", "y", "o", "a", "al", "este", "esta", "estos",
+    "estas", "su", "sus", "mi", "mis", "tu", "tus", "como", "que", "cual",
+  ]),
+
+  // 🇮🇹 Italian
+  it: new Set([
+    "il", "lo", "la", "i", "gli", "le", "un", "uno", "una", "un'", "di", "del",
+    "dello", "della", "dei", "degli", "delle", "a", "al", "allo", "alla", "ai",
+    "agli", "alle", "da", "dal", "in", "con", "su", "per", "tra", "fra", "e", "o",
+    "come", "cosa", "perche", "questo", "questa",
+  ]),
+
+  // 🇵🇹 Portuguese
+  pt: new Set([
+    "o", "a", "os", "as", "um", "uma", "uns", "umas", "de", "do", "da", "dos",
+    "das", "em", "no", "na", "nos", "nas", "para", "por", "com", "sem", "e",
+    "ou", "como", "que", "qual", "seu", "sua", "seus", "suas", "este", "esta",
+  ]),
+
+  // 🇳🇱 Dutch
+  nl: new Set([
+    "de", "het", "een", "en", "of", "voor", "met", "zonder", "in", "op", "bij",
+    "van", "naar", "door", "over", "onder", "als", "hoe", "wat", "wie", "waarom",
+    "zijn", "haar", "hun", "onze", "uw",
+  ]),
+
+  // 🇷🇺 Russian (Transliterated / Latinized)
+  ru: new Set([
+    "i", "v", "na", "s", "po", "dlya", "ot", "iz", "k", "o", "za", "kak",
+    "chto", "gde", "kogda", "pochemu", "eto", "etot", "eta", "eti", "ili",
+  ]),
+
+  // 🇸🇪 Swedish
+  sv: new Set([
+    "en", "ett", "den", "det", "de", "och", "eller", "for", "med", "utan",
+    "pa", "under", "i", "av", "till", "fran", "om", "hur", "vad", "varfor",
+  ]),
+
+  // 🇵🇱 Polish
+  pl: new Set([
+    "i", "w", "we", "z", "ze", "na", "do", "dla", "od", "o", "po", "za", "jak",
+    "co", "gdzie", "dlaczego", "to", "ten", "ta", "te", "lub", "albo",
+  ]),
+};
+
+// Global merged stop words set
+const ALL_STOP_WORDS = new Set<string>();
+for (const langSet of Object.values(MULTILINGUAL_STOP_WORDS)) {
+  for (const word of langSet) {
+    ALL_STOP_WORDS.add(word);
+  }
+}
+
+export interface SlugOptions {
+  language?: string; // e.g. "en", "fr", "de", "es", "all"
+  removeStopWords?: boolean;
+  stripDates?: boolean;
+  maxWords?: number;
+  maxLength?: number;
+}
+
+/**
+ * Normalizes any text into a clean, canonical SEO slug with multilingual stop word filtering.
+ */
+export function cleanSeoSlug(input: string, options: SlugOptions = {}): string {
+  const {
+    language = "en",
+    removeStopWords = true,
+    stripDates = true,
+    maxWords = 5,
+    maxLength = 75,
+  } = options;
+
+  if (!input || typeof input !== "string") {
+    return "page";
+  }
+
+  let text = input
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .trim();
+
+  if (stripDates) {
+    // Strip 4-digit years (2010-2039) and transient top lists (e.g. "top 10")
+    text = text.replace(/\b(20[1-3][0-9])\b/g, "");
+    text = text.replace(/\btop\s*\d+\s*/g, "");
+  }
+
+  let tokens = text
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+
+  if (removeStopWords) {
+    const activeSet = language === "all" || !MULTILINGUAL_STOP_WORDS[language]
+      ? ALL_STOP_WORDS
+      : MULTILINGUAL_STOP_WORDS[language];
+
+    tokens = tokens.filter((token) => !activeSet.has(token) && token.length > 1);
+  }
+
+  tokens = tokens.slice(0, maxWords);
+  let result = tokens.join("-");
+
+  if (result.length > maxLength) {
+    result = result.substring(0, maxLength).replace(/-[^-]*$/, "");
+  }
+
+  return result || "page";
+}
+
+export interface SlugValidationResult {
+  isValid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validates a slug against universal SEO golden rules.
+ */
+export function validateSeoSlug(slug: string): SlugValidationResult {
+  const errors: string[] = [];
+
+  if (!slug || slug.length < 2) {
+    errors.push("Slug must contain at least 2 characters");
+  }
+  if (slug.length > 75) {
+    errors.push("Slug should not exceed 75 characters for optimal CTR");
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) {
+    errors.push("Slug must be 100% lowercase alphanumeric with single hyphen (-) separators");
+  }
+  if (/(?:20[1-3][0-9])/.test(slug)) {
+    errors.push("Evergreen slug should not contain yearly date stamps");
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+}