@lynxflow/seo-engine 1.8.30 → 2.0.0

package/src/schema-builder.ts

@@ -1,134 +0,0 @@
-/**
- * 🌟 Standalone Schema.org Graph Builder
- *
- * Generates verified JSON-LD graphs (Product, FAQPage, Organization, Speakable)
- * for any manual or dynamic page without requiring the full engine resolver.
- */
-
-export class SchemaGraphBuilder {
-  /**
-   * Generates a complete Schema.org Graph for Product + FAQ + Speakable.
-   */
-  static buildGraph(opts: {
-    url: string;
-    name: string;
-    description: string;
-    brandName: string;
-    price?: number;
-    currency?: string;
-    image?: string;
-    faqs?: { question: string; answer: string }[];
-    ratingValue?: string;
-    reviewCount?: string;
-    locale?: string;
-    reviews?: Array<{
-      authorName: string;
-      ratingValue: number;
-      reviewText: string;
-      datePublished?: string;
-    }>;
-  }): Record<string, unknown> {
-    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,
-        },
-        datePublished: r.datePublished || new Date().toISOString().split("T")[0],
-        reviewBody: r.reviewText,
-        reviewRating: {
-          "@type": "Rating",
-          ratingValue: r.ratingValue.toString(),
-          bestRating: "5",
-          worstRating: "1",
-        },
-      }));
-    }
-
-    // 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({
-        "@type": "FAQPage",
-        "@id": `${opts.url}#faq`,
-        inLanguage: opts.locale || "fr",
-        mainEntity: opts.faqs.map((f) => ({
-          "@type": "Question",
-          name: f.question,
-          acceptedAnswer: {
-            "@type": "Answer",
-            text: f.answer,
-          },
-        })),
-      });
-    }
-
-    graph.push({
-      "@type": "WebPage",
-      "@id": `${opts.url}#webpage`,
-      url: opts.url,
-      name: opts.name,
-      description: opts.description,
-      speakable: {
-        "@type": "SpeakableSpecification",
-        cssSelector: [".geo-direct-answer", "h1"],
-      },
-    });
-
-    return {
-      "@context": "https://schema.org",
-      "@graph": graph,
-    };
-  }
-}

package/src/seo-opportunities-decay.ts

@@ -1,154 +0,0 @@
-/**
- * 🎯 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-client.ts

@@ -1,89 +0,0 @@
-/**
- * 🔎 LynxFlow SERP & Keyword Ranking Client
- *
- * Tracks keyword rankings on Google across multiple countries and languages,
- * discovers search volume, and analyzes AI Overview features.
- */
-
-export interface KeywordRankingItem {
-  keyword: string;
-  position: number;
-  previousPosition?: number;
-  searchVolume: number;
-  difficulty: number; // 0 to 100
-  url: string;
-  hasAiOverview: boolean;
-  country: string;
-}
-
-export interface SerpAnalysisResult {
-  keyword: string;
-  country: string;
-  totalResults: number;
-  rankings: { position: number; title: string; url: string; snippet: string }[];
-  aiOverviewSnippet?: string;
-  peopleAlsoAsk: string[];
-}
-
-export class SerpClient {
-  private apiKey: string;
-  private endpoint: string;
-
-  constructor(apiKey: string, endpoint = "https://lynxintel.io/api/v1/serp") {
-    this.apiKey = apiKey;
-    this.endpoint = endpoint;
-  }
-
-  /**
-   * Tracks a keyword ranking on Google for the client's domain.
-   */
-  async trackKeyword(keyword: string, country = "FR", domain = ""): Promise<KeywordRankingItem> {
-    try {
-      if (!this.apiKey || this.apiKey.startsWith("demo_")) {
-        // Mocked realistic ranking
-        return {
-          keyword,
-          position: 3,
-          previousPosition: 5,
-          searchVolume: 1800,
-          difficulty: 34,
-          url: `${domain}/solutions/${keyword.replace(/\s+/g, "-")}`,
-          hasAiOverview: true,
-          country,
-        };
-      }
-
-      const res = await fetch(`${this.endpoint}/track`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.apiKey}` },
-        body: JSON.stringify({ keyword, country, domain }),
-      });
-
-      if (!res.ok) throw new Error("SERP API error");
-      return (await res.json()) as KeywordRankingItem;
-    } catch {
-      return {
-        keyword,
-        position: 1,
-        searchVolume: 1200,
-        difficulty: 25,
-        url: domain,
-        hasAiOverview: true,
-        country,
-      };
-    }
-  }
-
-  /**
-   * Discovers related keywords, search volume, and People Also Ask questions.
-   */
-  async getKeywordSuggestions(seedKeyword: string, country = "FR"): Promise<string[]> {
-    return [
-      `${seedKeyword} avis`,
-      `${seedKeyword} tarif`,
-      `meilleur ${seedKeyword} 2026`,
-      `${seedKeyword} comparatif`,
-      `${seedKeyword} alternative`,
-    ];
-  }
-}

package/src/serp-history-alerts.ts

@@ -1,75 +0,0 @@
-/**
- * 📈 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/site-auditor.ts

@@ -1,83 +0,0 @@
-/**
- * 🔍 Standalone SEO Site Auditor & Meta Quality Inspector
- *
- * Evaluates SEO health, title length, description CTR quality,
- * heading hierarchy, and AI direct-answer readiness on any page or string.
- */
-
-export interface SeoAuditReport {
-  score: number; // 0 to 100
-  status: "excellent" | "good" | "needs_improvement" | "poor";
-  checks: {
-    name: string;
-    passed: boolean;
-    message: string;
-    weight: number;
-  }[];
-  suggestions: string[];
-}
-
-export class SiteAuditor {
-  /**
-   * Evaluates SEO quality for a given title, description, and h1.
-   */
-  static inspectMeta(params: {
-    title: string;
-    description: string;
-    h1?: string;
-    directAnswer?: string;
-    brandName?: string;
-  }): SeoAuditReport {
-    const checks: SeoAuditReport["checks"] = [];
-    const suggestions: string[] = [];
-    let score = 0;
-
-    // 1. Title Length Check (Optimal: 45 - 65 chars)
-    const titleLen = (params.title || "").length;
-    if (titleLen >= 40 && titleLen <= 70) {
-      checks.push({ name: "Title Tag Length", passed: true, message: `Title length (${titleLen} chars) is optimal for Google SERP.`, weight: 25 });
-      score += 25;
-    } else {
-      checks.push({ name: "Title Tag Length", passed: false, message: `Title length (${titleLen} chars) should be between 40 and 70 chars.`, weight: 25 });
-      suggestions.push("Adjust title to be between 40 and 70 characters to avoid truncation in search results.");
-    }
-
-    // 2. Meta Description Length Check (Optimal: 120 - 160 chars)
-    const descLen = (params.description || "").length;
-    if (descLen >= 110 && descLen <= 170) {
-      checks.push({ name: "Meta Description Length", passed: true, message: `Description length (${descLen} chars) is ideal.`, weight: 25 });
-      score += 25;
-    } else {
-      checks.push({ name: "Meta Description Length", passed: false, message: `Description length (${descLen} chars) should be between 110 and 170 chars.`, weight: 25 });
-      suggestions.push("Optimize meta description to 110-170 characters for higher click-through rates.");
-    }
-
-    // 3. H1 Heading Presence
-    if (params.h1 && params.h1.trim().length > 5) {
-      checks.push({ name: "H1 Tag Present", passed: true, message: "Primary H1 tag is clearly defined.", weight: 25 });
-      score += 25;
-    } else {
-      checks.push({ name: "H1 Tag Present", passed: false, message: "Missing or too short H1 heading.", weight: 25 });
-      suggestions.push("Ensure your page has a clear, keyword-rich H1 heading.");
-    }
-
-    // 4. AEO Direct Answer Check (For ChatGPT / Perplexity)
-    if (params.directAnswer && params.directAnswer.trim().length > 30) {
-      checks.push({ name: "AEO Direct Answer Ready", passed: true, message: "Direct-answer snippet is present for AI search engines.", weight: 25 });
-      score += 25;
-    } else {
-      checks.push({ name: "AEO Direct Answer Ready", passed: false, message: "No concise direct answer block found for AI citation.", weight: 25 });
-      suggestions.push("Add a 2-sentence summary block with structured facts for AI Overviews.");
-    }
-
-    const status: SeoAuditReport["status"] =
-      score >= 90 ? "excellent" : score >= 75 ? "good" : score >= 50 ? "needs_improvement" : "poor";
-
-    return {
-      score,
-      status,
-      checks,
-      suggestions,
-    };
-  }
-}