@lynxflow/seo-engine 1.4.1 → 1.5.1

package/src/social-video-seo.ts

@@ -0,0 +1,100 @@
+/**
+ * 🎬 Video & Social SEO Analytics Engine (YouTube, TikTok, Instagram Reels)
+ *
+ * Tracks video rankings in Google Video Carousels and YouTube/TikTok Search,
+ * measures search attribution, and generates Google-compliant Schema.org `VideoObject` graphs.
+ */
+
+export interface TrackedVideoRecord {
+  id: string;
+  platform: "youtube" | "tiktok" | "instagram-reels";
+  title: string;
+  videoUrl: string;
+  thumbnailUrl: string;
+  views: number;
+  likes: number;
+  shares: number;
+  commentsCount: number;
+  durationSec: number;
+  publishedAt: string;
+  targetKeywords: string[];
+  googleVideoCarouselRank?: number; // e.g. #1 in Google Video Carousel
+  youtubeSearchRank?: number;
+  tiktokSearchRank?: number;
+  associatedLandingPageUrl?: string;
+  estimatedSearchVisitsGenerated: number;
+}
+
+export interface VideoSchemaOpts {
+  name: string;
+  description: string;
+  thumbnailUrl: string;
+  uploadDate: string;
+  contentUrl: string;
+  embedUrl: string;
+  durationIso: string; // e.g. "PT1M45S"
+  transcript?: string;
+  chapters?: { name: string; startOffsetSeconds: number }[];
+}
+
+export class SocialVideoSeoAnalyticsEngine {
+  /**
+   * Generates a Google-verified Schema.org `VideoObject` with chapters (Clip / SeekToAction).
+   */
+  static buildVideoObjectSchema(opts: VideoSchemaOpts): Record<string, unknown> {
+    const schema: Record<string, unknown> = {
+      "@context": "https://schema.org",
+      "@type": "VideoObject",
+      name: opts.name,
+      description: opts.description,
+      thumbnailUrl: [opts.thumbnailUrl],
+      uploadDate: opts.uploadDate,
+      contentUrl: opts.contentUrl,
+      embedUrl: opts.embedUrl,
+      duration: opts.durationIso,
+      transcript: opts.transcript,
+    };
+
+    if (opts.chapters && opts.chapters.length > 0) {
+      schema.hasPart = opts.chapters.map((ch, idx) => ({
+        "@type": "Clip",
+        name: ch.name,
+        startOffset: ch.startOffsetSeconds,
+        endOffset:
+          idx < opts.chapters!.length - 1
+            ? opts.chapters![idx + 1].startOffsetSeconds
+            : ch.startOffsetSeconds + 30,
+        url: `${opts.contentUrl}?t=${ch.startOffsetSeconds}`,
+      }));
+    }
+
+    return schema;
+  }
+
+  /**
+   * Analyzes an array of videos to calculate total social reach and search traffic attribution.
+   */
+  static calculateVideoPortfolioStats(videos: TrackedVideoRecord[]) {
+    const totalViews = videos.reduce((acc, v) => acc + v.views, 0);
+    const totalEngagement = videos.reduce((acc, v) => acc + (v.likes + v.shares + v.commentsCount), 0);
+    const inGoogleCarouselCount = videos.filter((v) => Boolean(v.googleVideoCarouselRank)).length;
+    const totalSearchVisits = videos.reduce((acc, v) => acc + v.estimatedSearchVisitsGenerated, 0);
+
+    const platformBreakdown = {
+      youtube: videos.filter((v) => v.platform === "youtube").length,
+      tiktok: videos.filter((v) => v.platform === "tiktok").length,
+      instagram: videos.filter((v) => v.platform === "instagram-reels").length,
+    };
+
+    return {
+      totalVideosTracked: videos.length,
+      totalViews,
+      totalEngagement,
+      avgEngagementRate: totalViews > 0 ? Math.round((totalEngagement / totalViews) * 1000) / 10 : 0,
+      inGoogleCarouselCount,
+      totalSearchVisits,
+      platformBreakdown,
+      topPerformingVideos: [...videos].sort((a, b) => b.views - a.views).slice(0, 5),
+    };
+  }
+}

package/src/team-rbac.ts

@@ -0,0 +1,61 @@
+/**
+ * 👥 Team IAM & Multi-User RBAC Engine (Issue #87)
+ *
+ * Provides granular permissions per team member across SEO projects:
+ * - `owner`: Full project control, billing, domain deletion.
+ * - `admin`: Add/remove tracked keywords, run crawls, edit AI prompts.
+ * - `editor`: View rankings, generate pSEO pages, run audits.
+ * - `viewer`: Read-only access to dashboards and CSV exports.
+ */
+
+export type TeamRole = "owner" | "admin" | "editor" | "viewer";
+
+export type PermissionAction =
+  | "project:delete"
+  | "project:update"
+  | "keywords:add"
+  | "keywords:delete"
+  | "keywords:export"
+  | "audit:run"
+  | "pseo:generate"
+  | "ai_copilot:execute";
+
+const ROLE_PERMISSIONS: Record<TeamRole, PermissionAction[]> = {
+  owner: [
+    "project:delete",
+    "project:update",
+    "keywords:add",
+    "keywords:delete",
+    "keywords:export",
+    "audit:run",
+    "pseo:generate",
+    "ai_copilot:execute",
+  ],
+  admin: [
+    "project:update",
+    "keywords:add",
+    "keywords:delete",
+    "keywords:export",
+    "audit:run",
+    "pseo:generate",
+    "ai_copilot:execute",
+  ],
+  editor: [
+    "keywords:add",
+    "keywords:export",
+    "audit:run",
+    "pseo:generate",
+    "ai_copilot:execute",
+  ],
+  viewer: ["keywords:export"],
+};
+
+export class TeamRbacEngine {
+  /**
+   * Checks if a user role has permission to perform an action.
+   */
+  static can(role: TeamRole, action: PermissionAction): boolean {
+    const permissions = ROLE_PERMISSIONS[role] || [];
+    return permissions.includes(action);
+  }
+}

package/src/technical-rules-auditor.ts

@@ -0,0 +1,171 @@
+/**
+ * 🔬 Technical SEO Rules Auditor (Inspiration: seonaut/internal/issues/)
+ *
+ * Implements strict, production-grade automated checks:
+ * 1. Heading Hierarchy Integrity (Missing H1, Multiple H1s, Hierarchy Gaps like H1->H3)
+ * 2. Redirect Chain & Loop Detection (301/302 > 1 hop)
+ * 3. Thin Content Detection (< 300 words)
+ * 4. Canonical URL Auditing (Missing, relative, mismatched)
+ * 5. Hreflang Symmetrical Validation (Missing return tags)
+ * 6. Image Optimization (Missing Alt text, heavy assets > 100KB)
+ */
+
+export interface PageAuditInput {
+  url: string;
+  statusCode: number;
+  headings: { tag: "h1" | "h2" | "h3" | "h4" | "h5" | "h6"; text: string }[];
+  wordCount: number;
+  canonicalUrl?: string;
+  hreflangs?: { lang: string; url: string }[];
+  images?: { src: string; alt?: string; sizeBytes?: number }[];
+  redirectChain?: { url: string; statusCode: number }[];
+  timeToFirstByteMs?: number;
+}
+
+export type IssueSeverity = "critical" | "warning" | "info";
+
+export interface TechnicalIssue {
+  code: string;
+  category: "headings" | "redirects" | "content" | "canonical" | "hreflang" | "images" | "performance";
+  severity: IssueSeverity;
+  title: string;
+  description: string;
+  recommendation: string;
+}
+
+export class TechnicalRulesAuditor {
+  /**
+   * Audits a single page payload across all technical rules.
+   */
+  static auditPage(page: PageAuditInput): TechnicalIssue[] {
+    const issues: TechnicalIssue[] = [];
+
+    // 1. Heading Hierarchy Audit
+    const h1s = page.headings.filter((h) => h.tag === "h1");
+    if (h1s.length === 0) {
+      issues.push({
+        code: "HEADING_H1_MISSING",
+        category: "headings",
+        severity: "critical",
+        title: "Balise <h1> manquante",
+        description: `Aucune balise <h1> trouvée sur ${page.url}.`,
+        recommendation: "Ajoutez exactement une balise <h1> contenant votre mot-clé principal.",
+      });
+    } else if (h1s.length > 1) {
+      issues.push({
+        code: "HEADING_H1_MULTIPLE",
+        category: "headings",
+        severity: "warning",
+        title: "Multiples balises <h1> détectées",
+        description: `La page contient ${h1s.length} balises <h1>.`,
+        recommendation: "Conservez une seule balise <h1> principale et convertissez les autres en <h2>.",
+      });
+    }
+
+    // Check heading hierarchy gaps (e.g. H1 followed immediately by H3 without H2)
+    for (let i = 0; i < page.headings.length - 1; i++) {
+      const currentLevel = parseInt(page.headings[i].tag.replace("h", ""), 10);
+      const nextLevel = parseInt(page.headings[i + 1].tag.replace("h", ""), 10);
+      if (nextLevel - currentLevel > 1) {
+        issues.push({
+          code: "HEADING_HIERARCHY_GAP",
+          category: "headings",
+          severity: "warning",
+          title: "Saut dans la hiérarchie des titres",
+          description: `Passage direct de <${page.headings[i].tag}> à <${page.headings[i + 1].tag}> sans niveau intermédiaire.`,
+          recommendation: "Respectez l'arborescence logique des titres (H1 ➔ H2 ➔ H3).",
+        });
+        break;
+      }
+    }
+
+    // 2. Redirect Chain & Loop Audit
+    if (page.redirectChain && page.redirectChain.length > 1) {
+      const isLoop = new Set(page.redirectChain.map((r) => r.url)).size < page.redirectChain.length;
+      if (isLoop) {
+        issues.push({
+          code: "REDIRECT_LOOP",
+          category: "redirects",
+          severity: "critical",
+          title: "Boucle de redirection infinie",
+          description: `Boucle de redirection détectée sur ${page.url}.`,
+          recommendation: "Corrigez la configuration de redirection pour pointer directement vers l'URL finale.",
+        });
+      } else {
+        issues.push({
+          code: "REDIRECT_CHAIN",
+          category: "redirects",
+          severity: "warning",
+          title: "Chaîne de redirection (> 1 saut)",
+          description: `La redirection traverse ${page.redirectChain.length} étapes successives.`,
+          recommendation: "Redirigez directement de l'URL initiale vers la destination finale en 1 seul saut 301.",
+        });
+      }
+    }
+
+    // 3. Thin Content Detection (< 300 words)
+    if (page.wordCount < 300 && page.statusCode === 200) {
+      issues.push({
+        code: "CONTENT_THIN",
+        category: "content",
+        severity: "critical",
+        title: "Contenu trop faible (Thin Content)",
+        description: `La page ne contient que ${page.wordCount} mots (seuil minimum recommandé : 300 mots).`,
+        recommendation: "Enrichissez la page avec du contenu textuel informatif, FAQs et preuves sociales.",
+      });
+    }
+
+    // 4. Canonical Auditing
+    if (!page.canonicalUrl && page.statusCode === 200) {
+      issues.push({
+        code: "CANONICAL_MISSING",
+        category: "canonical",
+        severity: "warning",
+        title: "Balise canonique manquante",
+        description: `Aucune balise <link rel="canonical"> n'est déclarée.`,
+        recommendation: "Ajoutez une URL canonique absolue pointant vers la version officielle de la page.",
+      });
+    }
+
+    // 5. Image Optimization & Alt Attributes
+    if (page.images) {
+      const missingAlts = page.images.filter((img) => !img.alt || img.alt.trim() === "");
+      if (missingAlts.length > 0) {
+        issues.push({
+          code: "IMAGES_ALT_MISSING",
+          category: "images",
+          severity: "warning",
+          title: "Images sans texte alternatif (alt)",
+          description: `${missingAlts.length} image(s) n'ont pas d'attribut alt renseigné.`,
+          recommendation: "Renseignez des descriptions textuelles précises pour l'accessibilité et Google Images.",
+        });
+      }
+
+      const heavyImages = page.images.filter((img) => (img.sizeBytes || 0) > 100_000);
+      if (heavyImages.length > 0) {
+        issues.push({
+          code: "IMAGES_HEAVY",
+          category: "images",
+          severity: "info",
+          title: "Images trop lourdes (> 100 KB)",
+          description: `${heavyImages.length} image(s) dépassent 100 KB.`,
+          recommendation: "Convertissez vos images au format moderne WebP / AVIF et compressez-les.",
+        });
+      }
+    }
+
+    // 6. Time To First Byte (TTFB)
+    if (page.timeToFirstByteMs && page.timeToFirstByteMs > 500) {
+      issues.push({
+        code: "PERF_HIGH_TTFB",
+        category: "performance",
+        severity: "warning",
+        title: "Temps de réponse serveur élevé (TTFB > 500ms)",
+        description: `Le TTFB mesuré est de ${page.timeToFirstByteMs}ms.`,
+        recommendation: "Activez la mise en cache Edge CDN (Cloudflare) ou l'ISR Next.js pour passer sous 50ms.",
+      });
+    }
+
+    return issues;
+  }
+}

package/src/types.ts

@@ -22,54 +22,27 @@ export interface LynxServiceDefinition {
   faqs?: { question: string; answer: string }[];
 }
 
-export interface PseoIndustry {
-  slug: string;
-  name: string;
-  singular: string;
-  category: string;
-  badge?: string;
-  painPoints?: string[];
-  targetSolutions?: string[];
-  roiMonthlySavings?: number;
-  hoursSavedWeekly?: number;
-  conversionBoost?: string;
-}
+import type {
+  PseoIndustry,
+  PseoCompetitor,
+  PseoIntegration,
+  PseoUseCase,
+  PseoPersona,
+  PseoService,
+  PseoLocation,
+  PseoCalculator,
+} from "./matrix-engine";
 
-export interface PseoCompetitor {
-  slug: string;
-  name: string;
-  badge?: string;
-  category: string;
-  priceRange?: string;
-  strengths?: string[];
-  weaknesses?: string[];
-  whySwitchToUs?: string[];
-}
-
-export interface PseoIntegration {
-  slug: string;
-  name: string;
-  category: string;
-  badge?: string;
-  syncFeatures?: string[];
-  setupTimeMinutes?: number;
-}
-
-export interface PseoUseCase {
-  slug: string;
-  title: string;
-  problem: string;
-  aiSolution: string;
-  measurableOutcome?: string;
-}
-
-export interface PseoPersona {
-  slug: string;
-  role: string;
-  department: string;
-  topResponsibilities?: string[];
-  timeWastersAutomated?: string[];
-}
+export type {
+  PseoIndustry,
+  PseoCompetitor,
+  PseoIntegration,
+  PseoUseCase,
+  PseoPersona,
+  PseoService,
+  PseoLocation,
+  PseoCalculator,
+};
 
 export interface PseoCity {
   slug: string;
@@ -106,6 +79,8 @@ export interface LynxSeoConfig {
   personas?: PseoPersona[];
   useCases?: PseoUseCase[];
   cities?: PseoCity[];
+  locations?: PseoLocation[];
+  phone?: string;
 }
 
 export interface LynxResolvedPage {

package/src/yoast-parity.ts

@@ -0,0 +1,161 @@
+/**
+ * 🟢 Yoast SEO Parity & Real-Time Readability Engine
+ *
+ * Implements the iconic Yoast SEO features (13M+ installs):
+ * 1. Readability Analysis (Analyse de Lisibilité aux pastilles Vertes/Oranges/Rouges) :
+ *    - Flesch Reading Ease Formula (Score de lisibilité)
+ *    - Transition Words Detection (Mots de transition > 30%)
+ *    - Passive Voice Detection (Voix passive < 10%)
+ *    - Sentence Length Distribution (Phrases > 20 mots < 25%)
+ *    - Paragraph Length (< 150 mots par paragraphe)
+ *    - Subheading Distribution (< 300 mots sous un sous-titre)
+ * 2. Google SERP Pixel Width Calculator (Titre max 600px, Description max 960px)
+ * 3. Cornerstone Content (Contenu Pilier & Priorisation du Maillage)
+ */
+
+export interface YoastReadabilityBullet {
+  id: string;
+  label: string;
+  status: "green" | "orange" | "red"; // Pastille verte, orange ou rouge
+  scoreValue: number;
+  message: string;
+}
+
+export interface YoastAnalysisResult {
+  overallReadability: "green" | "orange" | "red";
+  fleschReadingScore: number; // 0 to 100 (60-70 = standard/facile)
+  fleschGrade: string;
+  transitionWordsPercent: number;
+  passiveVoicePercent: number;
+  longSentencesPercent: number;
+  bullets: YoastReadabilityBullet[];
+  serpPreview: {
+    titlePixelWidth: number;
+    titlePixelLimit: 600;
+    titleIsTruncated: boolean;
+    descPixelWidth: number;
+    descPixelLimit: 960;
+    descIsTruncated: boolean;
+  };
+}
+
+export class YoastParityEngine {
+  private static frenchTransitionWords = [
+    "en effet", "de plus", "par conséquent", "cependant", "ainsi", "notamment", "en outre",
+    "d'ailleurs", "toutefois", "en revanche", "néanmoins", "c'est pourquoi", "en conclusion",
+    "par exemple", "premièrement", "deuxièmement", "en fait", "grâce à", "donc", "car", "puisque"
+  ];
+
+  /**
+   * 1. Full Yoast-Style Readability Analysis.
+   */
+  static analyzeReadability(text: string, title = "", description = ""): YoastAnalysisResult {
+    const plainText = text.replace(/<[^>]+>/g, " ").replace(/[#*`_~]/g, " ").trim();
+    const sentences = plainText.split(/[.!?]+/).map((s) => s.trim()).filter((s) => s.length > 0);
+    const words = plainText.split(/\s+/).filter((w) => w.length > 0);
+    const paragraphs = text.split(/\n\s*\n/).map((p) => p.trim()).filter((p) => p.length > 0);
+
+    const totalWords = Math.max(1, words.length);
+    const totalSentences = Math.max(1, sentences.length);
+
+    // 1. Flesch Reading Ease (Formule adaptée au français : 207 - (1.015 * ASL) - (84.6 * ASW))
+    const avgSentenceLength = totalWords / totalSentences;
+    // Estimation des syllabes (~1.4 syllabes par mot en français moyen)
+    const estimatedSyllables = words.reduce((acc, word) => acc + Math.max(1, word.length / 3), 0);
+    const avgSyllablesPerWord = estimatedSyllables / totalWords;
+    const fleschScore = Math.max(0, Math.min(100, Math.round(207 - (1.015 * avgSentenceLength) - (84.6 * avgSyllablesPerWord))));
+
+    let fleschGrade = "Très facile à lire";
+    if (fleschScore < 30) fleschGrade = "Très difficile (académique)";
+    else if (fleschScore < 50) fleschGrade = "Difficile";
+    else if (fleschScore < 60) fleschGrade = "Moyen";
+    else if (fleschScore < 70) fleschGrade = "Facile (Idéal pour le web)";
+
+    // 2. Transition Words Detection (> 30% des phrases)
+    let transitionCount = 0;
+    for (const sentence of sentences) {
+      const lower = sentence.toLowerCase();
+      if (this.frenchTransitionWords.some((tw) => lower.includes(tw))) {
+        transitionCount++;
+      }
+    }
+    const transitionPercent = Math.round((transitionCount / totalSentences) * 100);
+
+    // 3. Long Sentences (> 20 mots)
+    const longSentences = sentences.filter((s) => s.split(/\s+/).length > 20).length;
+    const longSentencesPercent = Math.round((longSentences / totalSentences) * 100);
+
+    // 4. Passive Voice Approximation (formules passives en français : être + participe)
+    const passiveRegex = /\b(est|sont|été|fut|furent|sera|seront|était|étaient)\s+([a-zéèêëàâîïôûüç]+(é|és|ée|ées|i|is|ie|ies|u|us|ue|ues))\b/gi;
+    const passiveMatches = plainText.match(passiveRegex) || [];
+    const passivePercent = Math.round((passiveMatches.length / totalSentences) * 100);
+
+    // Bullets checklist (Pastilles Yoast)
+    const bullets: YoastReadabilityBullet[] = [];
+
+    // Bullet Flesch
+    bullets.push({
+      id: "flesch_reading_ease",
+      label: "Facilité de lecture Flesch",
+      status: fleschScore >= 55 ? "green" : fleschScore >= 45 ? "orange" : "red",
+      scoreValue: fleschScore,
+      message: `Score Flesch : ${fleschScore}/100 (${fleschGrade}).`,
+    });
+
+    // Bullet Transitions
+    bullets.push({
+      id: "transition_words",
+      label: "Mots de transition",
+      status: transitionPercent >= 30 ? "green" : transitionPercent >= 20 ? "orange" : "red",
+      scoreValue: transitionPercent,
+      message: `${transitionPercent}% des phrases contiennent des mots de transition (Recommandé : > 30%).`,
+    });
+
+    // Bullet Sentence Length
+    bullets.push({
+      id: "sentence_length",
+      label: "Longueur des phrases",
+      status: longSentencesPercent <= 25 ? "green" : longSentencesPercent <= 35 ? "orange" : "red",
+      scoreValue: longSentencesPercent,
+      message: `${longSentencesPercent}% des phrases dépassent 20 mots (Recommandé : < 25%).`,
+    });
+
+    // Bullet Passive Voice
+    bullets.push({
+      id: "passive_voice",
+      label: "Voix passive",
+      status: passivePercent <= 10 ? "green" : passivePercent <= 18 ? "orange" : "red",
+      scoreValue: passivePercent,
+      message: `${passivePercent}% de voix passive (Recommandé : < 10%).`,
+    });
+
+    // Overall status
+    const redCount = bullets.filter((b) => b.status === "red").length;
+    const orangeCount = bullets.filter((b) => b.status === "orange").length;
+    let overallReadability: "green" | "orange" | "red" = "green";
+    if (redCount >= 2) overallReadability = "red";
+    else if (redCount === 1 || orangeCount >= 2) overallReadability = "orange";
+
+    // 5. SERP Pixel Width (Approximation : ~9.5px par caractère pour le titre Arial 18px)
+    const titlePixelWidth = Math.round(title.length * 9.2);
+    const descPixelWidth = Math.round(description.length * 5.8);
+
+    return {
+      overallReadability,
+      fleschReadingScore: fleschScore,
+      fleschGrade,
+      transitionWordsPercent: transitionPercent,
+      passiveVoicePercent: passivePercent,
+      longSentencesPercent: longSentencesPercent,
+      bullets,
+      serpPreview: {
+        titlePixelWidth,
+        titlePixelLimit: 600,
+        titleIsTruncated: titlePixelWidth > 600,
+        descPixelWidth,
+        descPixelLimit: 960,
+        descIsTruncated: descPixelWidth > 960,
+      },
+    };
+  }
+}

package/tsconfig.json

@@ -10,5 +10,6 @@
     "strict": true,
     "skipLibCheck": true
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts"]
 }