@lynxflow/seo-engine 1.4.1 → 1.5.1

package/src/auth-key.ts

@@ -45,6 +45,21 @@ export class ApiKeyGuardian {
     return `ba_key_${tier}_${tenantId}_${checksum}`;
   }
 
+  /**
+   * 🛡️ Generates an Admin Bypass / Free Trial API key with a hard expiration date (YYYYMMDD).
+   * Bypasses Lago/Hyperswitch payment verification until the expiration date.
+   */
+  static generateAdminTrialBypassKey(opts: {
+    tenantId: string;
+    expiresAtIso: string; // e.g. "2026-12-31"
+    tier?: "starter" | "growth" | "enterprise";
+  }): string {
+    const tier = opts.tier || "growth";
+    const dateStr = opts.expiresAtIso.replace(/-/g, "").substring(0, 8); // "20261231"
+    const checksum = this.computeChecksum(`${opts.tenantId}:${tier}:${dateStr}`);
+    return `ba_trial_${tier}_${opts.tenantId}_${dateStr}_${checksum}`;
+  }
+
   /**
    * Fast cryptographic validation of Better Auth API keys.
    */
@@ -63,6 +78,50 @@ export class ApiKeyGuardian {
 
     const cleanKey = apiKey.trim();
 
+    // 0. Admin Trial / Payment Bypass Keys with Expiry (ba_trial_...)
+    if (cleanKey.startsWith("ba_trial_")) {
+      const parts = cleanKey.split("_");
+      // Format: ba_trial_{tier}_{tenantId}_{YYYYMMDD}_{checksum}
+      const tier = (parts[2] as "starter" | "growth" | "enterprise") || "growth";
+      const tenantId = parts[3] || "trial_tenant";
+      const dateStr = parts[4]; // "20261231"
+
+      if (dateStr && dateStr.length === 8) {
+        const year = parseInt(dateStr.substring(0, 4), 10);
+        const month = parseInt(dateStr.substring(4, 6), 10) - 1;
+        const day = parseInt(dateStr.substring(6, 8), 10);
+        const expiryDate = new Date(Date.UTC(year, month, day, 23, 59, 59));
+        const now = new Date();
+
+        if (now > expiryDate) {
+          return {
+            isValid: false,
+            tier,
+            tenantId,
+            maxPages: 0,
+            maxDomains: 0,
+            monthlyCreditBudget: 0,
+            tokenManager: new TokenQuotaManager("starter"),
+            errorMessage: `Admin Trial Expired: This license expired on ${year}-${String(month + 1).padStart(2, "0")}-${String(day).padStart(2, "0")}. Please renew or activate a paid subscription.`,
+          };
+        }
+      }
+
+      const maxPages = tier === "enterprise" ? 5_000_000 : tier === "starter" ? 50_000 : 500_000;
+      const maxDomains = tier === "enterprise" ? 9999 : tier === "starter" ? 1 : 3;
+      const budget = tier === "enterprise" ? 50_000 : tier === "starter" ? 1_000 : 5_000;
+
+      return {
+        isValid: true,
+        tier,
+        tenantId,
+        maxPages,
+        maxDomains,
+        monthlyCreditBudget: budget,
+        tokenManager: new TokenQuotaManager(tier),
+      };
+    }
+
     // 1. Enterprise / Master Admin Keys
     if (cleanKey.startsWith("ba_admin_") || cleanKey.startsWith("lynx_enterprise_") || cleanKey.startsWith("lynx_live_") || cleanKey.includes("_enterprise_")) {
       return {

package/src/brand-dna-calendar.ts

@@ -0,0 +1,120 @@
+/**
+ * 🧬 Brand DNA Extractor & Content Calendar Engine (Pole 4)
+ *
+ * Scrapes and analyzes client domain to extract Unique Value Proposition (UVP),
+ * target personas, editorial tone, and generates an automated 4-week content calendar.
+ */
+
+export interface BrandDnaProfile {
+  domain: string;
+  brandName: string;
+  tagline: string;
+  uniqueValueProposition: string;
+  targetPersonas: string[];
+  editorialTone: "authoritative" | "direct" | "technical" | "pedagogical" | "empathetic";
+  keyDifferentiators: string[];
+  primaryIndustry: string;
+}
+
+export interface ContentCalendarItem {
+  id: string;
+  weekNumber: number;
+  scheduledDay: string;
+  matrixFamily: string;
+  title: string;
+  targetUrl: string;
+  primaryKeyword: string;
+  status: "draft" | "ready" | "scheduled" | "published";
+}
+
+export class BrandDnaCalendarEngine {
+  /**
+   * Generates a complete 4-week editorial content calendar based on the Brand DNA and 8 matrices.
+   */
+  static generate4WeekCalendar(
+    dna: BrandDnaProfile,
+    services: { slug: string; name: string }[],
+    topCities: string[] = ["Paris", "Lyon", "Marseille", "Bordeaux"],
+  ): ContentCalendarItem[] {
+    const calendar: ContentCalendarItem[] = [];
+    const days = ["Lundi", "Mercredi", "Vendredi"];
+    let itemId = 1;
+
+    for (let week = 1; week <= 4; week++) {
+      for (const day of days) {
+        let matrixFamily = "local-geo";
+        let title = "";
+        let targetUrl = "";
+        let primaryKeyword = "";
+        const svc = services[(itemId - 1) % services.length];
+
+        switch (itemId % 8) {
+          case 1:
+            matrixFamily = "local-geo";
+            const city = topCities[(week - 1) % topCities.length];
+            title = `${svc.name} à ${city} — Solution Pro`;
+            targetUrl = `/solutions/${svc.slug}/fr/${city.toLowerCase()}`;
+            primaryKeyword = `${svc.name} ${city}`;
+            break;
+          case 2:
+            matrixFamily = "vs-comparison";
+            title = `${dna.brandName} vs HubSpot : Comparatif Détaillé`;
+            targetUrl = `/comparatif/${svc.slug}-vs-hubspot`;
+            primaryKeyword = `${svc.name} vs hubspot`;
+            break;
+          case 3:
+            matrixFamily = "alternative";
+            title = `Meilleure Alternative à Aircall en 2026`;
+            targetUrl = `/alternatives/alternative-a-aircall`;
+            primaryKeyword = `alternative aircall`;
+            break;
+          case 4:
+            matrixFamily = "industry";
+            title = `Solution ${svc.name} pour Cabinets d'Avocats`;
+            targetUrl = `/secteurs/${svc.slug}-pour-avocats`;
+            primaryKeyword = `${svc.name} avocats`;
+            break;
+          case 5:
+            matrixFamily = "integration";
+            title = `Intégration ${svc.name} & Shopify`;
+            targetUrl = `/integrations/${svc.slug}-avec-shopify`;
+            primaryKeyword = `${svc.name} shopify`;
+            break;
+          case 6:
+            matrixFamily = "persona";
+            title = `Espace de travail ${svc.name} pour Directeur Commercial`;
+            targetUrl = `/metiers/${svc.slug}-pour-directeur-commercial`;
+            primaryKeyword = `${svc.name} directeur commercial`;
+            break;
+          case 7:
+            matrixFamily = "use-case";
+            title = `Comment Automatiser la Relance de Devis avec ${dna.brandName}`;
+            targetUrl = `/cas-usage/${svc.slug}-relance-devis`;
+            primaryKeyword = `automatiser relance devis`;
+            break;
+          case 0:
+            matrixFamily = "calculator";
+            title = `Simulateur Gratuit de ROI & Gain de Temps`;
+            targetUrl = `/outils/simulateur-roi-${svc.slug}`;
+            primaryKeyword = `calculateur roi ${svc.name}`;
+            break;
+        }
+
+        calendar.push({
+          id: `cal-${itemId}`,
+          weekNumber: week,
+          scheduledDay: day,
+          matrixFamily,
+          title,
+          targetUrl,
+          primaryKeyword,
+          status: week === 1 ? "ready" : "scheduled",
+        });
+
+        itemId++;
+      }
+    }
+
+    return calendar;
+  }
+}

package/src/copy-frameworks-master.ts

@@ -0,0 +1,89 @@
+/**
+ * ✍️ Master Copywriting & AI-SEO Prompt Frameworks Engine
+ *
+ * Implements the complete set of formulas from marketingskills:
+ * 1. 5 Battle-Tested Headline Formulas (Outcome, Problem, Audience, Differentiation, Proof)
+ * 2. The Human Action Model (Discomfort ➔ Vision ➔ Path)
+ * 3. 40-60 Word Concise AEO / GEO Definition Answer Block for LLM Citation
+ * 4. Google AI Query Fan-Out Generator (5-10 concurrent semantic sub-queries)
+ * 5. Value Equation & Grand Slam Offer Stack (Alex Hormozi)
+ */
+
+export interface HeadlineVariants {
+  outcomeFocused: string; // "{Achieve outcome} without {pain point}"
+  problemFocused: string; // "Stop [pain]. Start [pleasure]."
+  audienceFocused: string; // "{Service} pensé pour {target audience}"
+  differentiationFocused: string; // "La méthode zéro-base de données pour {outcome}"
+  proofFocused: string; // "Rejoignez 1 200+ entreprises qui ont {outcome}"
+}
+
+export interface HumanActionModelCopy {
+  discomfortState: string; // Current painful friction
+  visionState: string; // Desirable effortless future
+  actionPath: string; // Immediate clear step
+}
+
+export class CopywritingFrameworksMaster {
+  /**
+   * 1. Generates 5 high-converting headline variants based on marketingskills formulas.
+   */
+  static generateHeadlines(opts: {
+    serviceName: string;
+    desiredOutcome: string;
+    painPoint: string;
+    targetAudience: string;
+    metricProof: string;
+  }): HeadlineVariants {
+    return {
+      outcomeFocused: `${opts.desiredOutcome} sans ${opts.painPoint}`,
+      problemFocused: `Arrêtez ${opts.painPoint}. Commencez à ${opts.desiredOutcome}.`,
+      audienceFocused: `${opts.serviceName} pour ${opts.targetAudience} : ${opts.desiredOutcome}`,
+      differentiationFocused: `Le moyen le plus rapide de ${opts.desiredOutcome} sans configuration complexe`,
+      proofFocused: `${opts.metricProof} font confiance à ${opts.serviceName} pour ${opts.desiredOutcome}`,
+    };
+  }
+
+  /**
+   * 2. Human Action Model (Discomfort ➔ Vision ➔ Path).
+   */
+  static generateHumanActionModel(opts: {
+    painPoint: string;
+    desiredOutcome: string;
+    solutionName: string;
+    timeframe: string;
+  }): HumanActionModelCopy {
+    return {
+      discomfortState: `Aujourd'hui, vous perdez un temps précieux avec ${opts.painPoint}, ce qui freine directement votre croissance.`,
+      visionState: `Imaginez pouvoir ${opts.desiredOutcome} automatiquement et recevoir des prospects qualifiés 24/7.`,
+      actionPath: `Activez ${opts.solutionName} en moins de ${opts.timeframe} et débloquez votre plein potentiel d'acquisition.`,
+    };
+  }
+
+  /**
+   * 3. 40-60 Word Direct-Answer GEO Block (Gold standard for ChatGPT, Perplexity & Google AI Overviews).
+   */
+  static generateAeoAnswerBlock(opts: {
+    term: string;
+    definition: string;
+    keyBenefit: string;
+    proofStat: string;
+  }): string {
+    return `${opts.term} est ${opts.definition}. Cette solution permet de ${opts.keyBenefit}, enregistrant ${opts.proofStat}. Elle est conçue pour optimiser l'indexation sur les moteurs traditionnels et les réponses de recherche IA (ChatGPT Search, Perplexity).`;
+  }
+
+  /**
+   * 4. Query Fan-Out Generator: 8 related queries that Google AI Overviews fan out to.
+   */
+  static generateQueryFanOut(topic: string, serviceSlug: string): string[] {
+    return [
+      `Comment fonctionne ${topic} ?`,
+      `Meilleur outil pour ${topic} en 2026`,
+      `Prix et tarif ${serviceSlug}`,
+      `Avis clients et comparatif ${serviceSlug}`,
+      `Alternatives à ${serviceSlug}`,
+      `Intégration ${topic} avec CRM et site web`,
+      `Comment automatiser ${topic} sans code ?`,
+      `Calculateur de ROI pour ${topic}`,
+    ];
+  }
+}

package/src/cro-copywriting-engine.ts

@@ -0,0 +1,105 @@
+/**
+ * ✍️ Automated Copywriting & CRO Injection Engine (Inspiration: marketingskills)
+ *
+ * Automatically generates high-converting sales copy blocks using proven frameworks:
+ * 1. PAS (Problem - Agitation - Solution)
+ * 2. AIDA (Attention - Interest - Desire - Action)
+ * 3. Trust & Social Proof Elements (Risk Reducers, Guarantees, Badges)
+ * 4. High-Conversion Sticky CTAs
+ */
+
+export interface CopywritingInput {
+  brandName: string;
+  solutionName: string;
+  targetNicheOrCity: string;
+  painPoint: string;
+  agitation: string;
+  outcome: string;
+  priceMonthly?: number;
+  currencySymbol?: string;
+}
+
+export class CroCopywritingEngine {
+  /**
+   * Returns structured PAS (Problem - Agitation - Solution) text data.
+   */
+  static generatePasCopy(solutionName: string, targetNiche: string): { problem: string; agitation: string; solution: string } {
+    return {
+      problem: `Les professionnels de ${targetNiche} perdent jusqu'à 15 heures par semaine sur des tâches manuelles répétitives.`,
+      agitation: `Sans automatisation, les relances sont oubliées, les opportunités clients s'évaporent et la rentabilité stagne.`,
+      solution: `${solutionName} automatise 100% de vos processus pour vous permettre de vous concentrer sur vos clients et votre croissance.`,
+    };
+  }
+
+  /**
+   * Generates a PAS (Problem - Agitation - Solution) sales block in HTML.
+   */
+  static generatePasBlock(input: CopywritingInput): string {
+    return `
+<section class="cro-pas-framework my-8 p-6 bg-slate-900 border border-slate-800 rounded-xl">
+  <div class="pas-problem mb-4">
+    <span class="inline-block text-xs font-semibold px-2 py-1 bg-red-950 text-red-400 rounded">Le Problème</span>
+    <h3 class="text-xl font-bold text-white mt-2">${input.painPoint}</h3>
+  </div>
+  <div class="pas-agitation mb-4 text-slate-300">
+    <p>${input.agitation}</p>
+  </div>
+  <div class="pas-solution mt-4 pt-4 border-t border-slate-800">
+    <span class="inline-block text-xs font-semibold px-2 py-1 bg-emerald-950 text-emerald-400 rounded">La Solution ${input.brandName}</span>
+    <h4 class="text-lg font-bold text-white mt-1">${input.solutionName} pour ${input.targetNicheOrCity}</h4>
+    <p class="text-emerald-300 font-medium mt-1">➔ ${input.outcome}</p>
+  </div>
+</section>
+    `.trim();
+  }
+
+  /**
+   * Generates a High-Converting Social Proof & Trust Badges block.
+   */
+  static generateTrustBadgesBlock(input: {
+    guaranteeDays?: number;
+    rating?: string;
+    reviewCount?: number;
+    freeTrialDays?: number;
+  }): string {
+    const guarantee = input.guaranteeDays ? `Garantie Satisfait ou Remboursé ${input.guaranteeDays} Jours` : "Sans engagement";
+    const trial = input.freeTrialDays ? `Essai gratuit ${input.freeTrialDays} jours sans carte bancaire` : "Déploiement immédiat";
+
+    return `
+<div class="cro-trust-badges flex flex-wrap gap-4 items-center justify-center my-6 text-sm text-slate-300">
+  <div class="flex items-center gap-2 bg-slate-800/80 px-3 py-1.5 rounded-lg border border-slate-700">
+    <span>🔒</span>
+    <span>Paiement 100% Sécurisé & RGPD</span>
+  </div>
+  <div class="flex items-center gap-2 bg-slate-800/80 px-3 py-1.5 rounded-lg border border-slate-700">
+    <span>⚡</span>
+    <span>${trial}</span>
+  </div>
+  <div class="flex items-center gap-2 bg-slate-800/80 px-3 py-1.5 rounded-lg border border-slate-700">
+    <span>🛡️</span>
+    <span>${guarantee}</span>
+  </div>
+</div>
+    `.trim();
+  }
+
+  /**
+   * Generates an Instant WhatsApp / Direct Call conversion trigger button (inspired by Jacobo).
+   */
+  static generateInstantConverterWidget(phoneNumber: string, brandOrMessage: string, serviceName?: string): string {
+    const cleanPhone = phoneNumber.replace(/[^0-9+]/g, "");
+    const msg = serviceName
+      ? `Bonjour ${brandOrMessage}, je souhaite en savoir plus sur votre solution ${serviceName}.`
+      : brandOrMessage;
+    const encodedMsg = encodeURIComponent(msg);
+
+    return `
+<div class="instant-converter-widget fixed bottom-6 right-6 z-50 flex flex-col gap-2">
+  <a href="https://wa.me/${cleanPhone}?text=${encodedMsg}" target="_blank" rel="noopener noreferrer" class="flex items-center gap-2 px-4 py-3 bg-emerald-600 hover:bg-emerald-500 text-white font-bold rounded-full shadow-2xl transition duration-200">
+    <svg class="w-6 h-6 fill-current" viewBox="0 0 24 24"><path d="M.057 24l1.687-6.163c-1.041-1.804-1.588-3.849-1.587-5.946.003-6.556 5.338-11.891 11.893-11.891 3.181.001 6.167 1.24 8.413 3.488 2.245 2.248 3.481 5.236 3.48 8.414-.003 6.557-5.338 11.892-11.893 11.892-1.99-.001-3.951-.5-5.688-1.448l-6.305 1.654zm6.597-3.807c1.676.995 3.276 1.591 5.392 1.592 5.448 0 9.886-4.434 9.889-9.885.002-5.462-4.415-9.89-9.881-9.892-5.452 0-9.887 4.434-9.889 9.884-.001 2.225.651 3.891 1.746 5.634l-.999 3.648 3.742-.981z"/></svg>
+    <span>Discuter en direct</span>
+  </a>
+</div>
+    `.trim();
+  }
+}

package/src/crosslink-scorer.ts

@@ -0,0 +1,101 @@
+/**
+ * 🕸️ Contextual Cross-Linking & Semantic Affinity Engine (Inspiration: seedrank/crosslinks.py)
+ *
+ * Computes forward and backward internal link affinity scores based on:
+ * Score = (TopicOverlap * 2 + KeywordOverlap) + VolumeBonus + ContentTypeBonus + RecencyBonus
+ */
+
+export interface ArticleOrPageNode {
+  slug: string;
+  title: string;
+  url: string;
+  targetKeywords: string[];
+  topics: string[];
+  contentType?: "landing-page" | "blog-post" | "comparison" | "use-case";
+  searchVolumeSum?: number;
+  publishedAt?: string; // ISO date
+}
+
+export interface CrosslinkSuggestion {
+  targetNode: ArticleOrPageNode;
+  score: number;
+  keywordOverlapCount: number;
+  topicOverlapCount: number;
+  anchorTextSuggestion: string;
+}
+
+export class CrosslinkScorerEngine {
+  /**
+   * Computes semantic crosslink affinity between a source page and candidate pages.
+   */
+  static computeCrosslinkScore(
+    source: ArticleOrPageNode,
+    candidate: ArticleOrPageNode,
+  ): CrosslinkSuggestion | null {
+    if (source.slug === candidate.slug) return null;
+
+    const sourceKws = new Set(source.targetKeywords.map((k) => k.toLowerCase()));
+    const candKws = new Set(candidate.targetKeywords.map((k) => k.toLowerCase()));
+    const sourceTopics = new Set(source.topics.map((t) => t.toLowerCase()));
+    const candTopics = new Set(candidate.topics.map((t) => t.toLowerCase()));
+
+    const kwOverlap = Array.from(sourceKws).filter((k) => candKws.has(k));
+    const topicOverlap = Array.from(sourceTopics).filter((t) => candTopics.has(t));
+
+    const baseScore = topicOverlap.length * 2 + kwOverlap.length;
+    if (baseScore === 0) return null;
+
+    // Search volume bonus (up to +1.0)
+    let volumeBonus = 0.0;
+    if (candidate.searchVolumeSum) {
+      volumeBonus = Math.min(candidate.searchVolumeSum / 2000, 1.0);
+    }
+
+    // Content type affinity (+0.5 if different types create funnel synergy)
+    let contentTypeBonus = 0.0;
+    if (source.contentType && candidate.contentType && source.contentType !== candidate.contentType) {
+      contentTypeBonus = 0.5; // Blog post linking to Landing page is high-value
+    }
+
+    // Recency bonus
+    let recencyBonus = 0.0;
+    if (candidate.publishedAt) {
+      const daysAgo = (Date.now() - new Date(candidate.publishedAt).getTime()) / (1000 * 3600 * 24);
+      if (daysAgo < 30) recencyBonus = 0.5;
+      else if (daysAgo < 90) recencyBonus = 0.25;
+    }
+
+    const totalScore = baseScore + volumeBonus + contentTypeBonus + recencyBonus;
+
+    const anchorText =
+      kwOverlap.length > 0 ? candidate.targetKeywords[0] : candidate.title;
+
+    return {
+      targetNode: candidate,
+      score: Math.round(totalScore * 100) / 100,
+      keywordOverlapCount: kwOverlap.length,
+      topicOverlapCount: topicOverlap.length,
+      anchorTextSuggestion: anchorText,
+    };
+  }
+
+  /**
+   * Finds the top N most relevant internal crosslinks for a given page.
+   */
+  static findBestCrosslinks(
+    source: ArticleOrPageNode,
+    allNodes: ArticleOrPageNode[],
+    maxLinks = 5,
+  ): CrosslinkSuggestion[] {
+    const suggestions: CrosslinkSuggestion[] = [];
+
+    for (const cand of allNodes) {
+      const scoreResult = this.computeCrosslinkScore(source, cand);
+      if (scoreResult) {
+        suggestions.push(scoreResult);
+      }
+    }
+
+    return suggestions.sort((a, b) => b.score - a.score).slice(0, maxLinks);
+  }
+}

package/src/embeddable-seo-widget.ts

@@ -0,0 +1,57 @@
+/**
+ * 🧩 Embeddable Client SEO & Discovery Widget (Inspiration: pages-seo/widget.js.js)
+ *
+ * Provides a lightweight (< 5KB) vanilla JavaScript snippet generator that allows external
+ * client sites to embed interactive directory navigation or related programmatic links.
+ */
+
+export class EmbeddableSeoWidgetGenerator {
+  /**
+   * Generates the client-side JavaScript snippet to inject dynamic links into any DOM container.
+   */
+  static generateWidgetJs(apiBaseUrl: string): string {
+    return `
+(function() {
+  const container = document.getElementById('lynxseo-widget');
+  if (!container) return;
+
+  const domain = container.getAttribute('data-domain') || window.location.hostname;
+  const currentPath = window.location.pathname;
+
+  fetch('${apiBaseUrl}/api/widget/related?domain=' + encodeURIComponent(domain) + '&path=' + encodeURIComponent(currentPath))
+    .then(res => res.json())
+    .then(data => {
+      if (!data || !data.links || data.links.length === 0) return;
+
+      const nav = document.createElement('nav');
+      nav.className = 'lynxseo-related-links';
+      nav.style.cssText = 'margin: 2rem 0; padding: 1.5rem; background: #0f172a; border-radius: 0.75rem; border: 1px solid #1e293b; color: #f8fafc; font-family: sans-serif;';
+
+      const title = document.createElement('h4');
+      title.textContent = data.title || 'Solutions & Pages Recommandées';
+      title.style.cssText = 'margin: 0 0 1rem; font-size: 1.1rem; color: #38bdf8; font-weight: 600;';
+      nav.appendChild(title);
+
+      const list = document.createElement('ul');
+      list.style.cssText = 'list-style: none; padding: 0; margin: 0; display: flex; flex-wrap: wrap; gap: 0.5rem;';
+
+      data.links.forEach(link => {
+        const li = document.createElement('li');
+        const a = document.createElement('a');
+        a.href = link.url;
+        a.textContent = link.name;
+        a.style.cssText = 'display: inline-block; padding: 0.4rem 0.8rem; background: #1e293b; color: #e2e8f0; text-decoration: none; border-radius: 0.375rem; font-size: 0.875rem; transition: background 0.2s;';
+        a.onmouseover = () => { a.style.background = '#2563eb'; };
+        a.onmouseout = () => { a.style.background = '#1e293b'; };
+        li.appendChild(a);
+        list.appendChild(li);
+      });
+
+      nav.appendChild(list);
+      container.appendChild(nav);
+    })
+    .catch(err => console.error('LynxSEO Widget Error:', err));
+})();
+    `.trim();
+  }
+}

package/src/engine.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import { cleanSeoSlug, validateSeoSlug, MULTILINGUAL_STOP_WORDS } from "./slug-engine";
+import { LegalDisclaimerEngine, MULTILINGUAL_BANNED_DISPARAGING_WORDS } from "./legal-disclaimers";
+import { ExtendedSchemaGraphBuilder } from "./extended-schemas";
+import { PseoMatrixEngine } from "./matrix-engine";
+import { getSeoAgentPrompt } from "./llm-prompt";
+
+describe("Multilingual SEO Slug Engine (10+ Languages)", () => {
+  it("English: Strips stop words and years", () => {
+    const slug = cleanSeoSlug("The best software for managing invoice payments in 2026", { language: "en" });
+    expect(slug).toBe("best-software-managing-invoice-payments");
+  });
+
+  it("German: Strips German stop words (der, die, für, mit)", () => {
+    const slug = cleanSeoSlug("Die beste Software für das Management mit Cloud", { language: "de" });
+    expect(slug).toBe("beste-software-management-cloud");
+  });
+
+  it("Spanish: Strips Spanish stop words (el, la, para, con)", () => {
+    const slug = cleanSeoSlug("El mejor software para la gestion con automatizacion", { language: "es" });
+    expect(slug).toBe("mejor-software-gestion-automatizacion");
+  });
+
+  it("French: Strips French stop words (le, pour, avec)", () => {
+    const slug = cleanSeoSlug("Le logiciel pour avocats avec automatisation", { language: "fr" });
+    expect(slug).toBe("logiciel-avocats-automatisation");
+  });
+
+  it("Validates all 10 language dictionaries exist", () => {
+    expect(Object.keys(MULTILINGUAL_STOP_WORDS).length).toBeGreaterThanOrEqual(10);
+    expect(MULTILINGUAL_STOP_WORDS.en).toBeDefined();
+    expect(MULTILINGUAL_STOP_WORDS.de).toBeDefined();
+    expect(MULTILINGUAL_STOP_WORDS.es).toBeDefined();
+    expect(MULTILINGUAL_STOP_WORDS.it).toBeDefined();
+    expect(MULTILINGUAL_STOP_WORDS.pt).toBeDefined();
+  });
+});
+
+describe("Multilingual Legal & Disclaimers Engine", () => {
+  const legal = new LegalDisclaimerEngine({
+    companyName: "Acme Cloud",
+    correctionsEmail: "legal@acme.com",
+    dataStalenessDays: 90,
+  });
+
+  it("Generates English disclaimer by default", () => {
+    const notice = legal.getDisclaimer("pricing", "2026-08-01");
+    expect(notice).toContain("Pricing disclaimer");
+    expect(notice).toContain("2026-08-01");
+  });
+
+  it("Generates German disclaimer when requested", () => {
+    const notice = legal.getDisclaimer("pricing", "2026-08-01", "de");
+    expect(notice).toContain("Preishinweis");
+  });
+
+  it("Flags hazardous claims in English, German, French, and Spanish", () => {
+    expect(legal.validateCompliance("This product is a scam", "Vendor").isCompliant).toBe(false);
+    expect(legal.validateCompliance("Diese Software ist ein Betrug", "Vendor").isCompliant).toBe(false);
+    expect(legal.validateCompliance("Ce logiciel est une arnaque", "Vendor").isCompliant).toBe(false);
+    expect(legal.validateCompliance("Este producto es una estafa", "Vendor").isCompliant).toBe(false);
+  });
+
+  it("Verifies 10 languages supported in banned disparaging words dictionary", () => {
+    expect(Object.keys(MULTILINGUAL_BANNED_DISPARAGING_WORDS).length).toBeGreaterThanOrEqual(10);
+  });
+});
+
+describe("Extended Schema.org Builder", () => {
+  it("Resolves 35+ specialized LocalBusiness types", () => {
+    expect(ExtendedSchemaGraphBuilder.resolveBusinessType("plumber")).toBe("Plumber");
+    expect(ExtendedSchemaGraphBuilder.resolveBusinessType("dentist")).toBe("Dentist");
+    expect(ExtendedSchemaGraphBuilder.resolveBusinessType("lawyer")).toBe("LegalService");
+    expect(ExtendedSchemaGraphBuilder.resolveBusinessType("hvac")).toBe("HVACBusiness");
+    expect(ExtendedSchemaGraphBuilder.resolveBusinessType("accounting")).toBe("AccountingService");
+  });
+
+  it("Builds valid Organization with sameAs Entity SEO links", () => {
+    const schema = ExtendedSchemaGraphBuilder.buildOrganization({
+      name: "Acme",
+      url: "https://acme.com",
+      sameAs: ["https://wikidata.org/wiki/Q123"],
+    });
+    expect(schema["@type"]).toBe("Organization");
+    expect(schema.sameAs).toContain("https://wikidata.org/wiki/Q123");
+  });
+});
+
+describe("Master Programmatic Matrix Engine (English Default)", () => {
+  const engine = new PseoMatrixEngine();
+  const options = { brandName: "Acme", minPopulationToIndex: 15_000 };
+
+  it("Generates English default URLs (/vs/, /alternatives/, /pricing/, /templates/, /glossary/)", () => {
+    const pages = engine.generateAllMatrices(
+      "https://acme.com",
+      {
+        competitors: [{ slug: "hubspot", name: "HubSpot", category: "CRM", drawbacks: [], advantagesOver: [] }],
+        templates: [{ slug: "crm-pipeline-excel", title: "CRM Pipeline", topic: "Sales", format: "excel", benefits: ["Save time"] }],
+        glossaryTerms: [{ slug: "mrr", term: "MRR", shortDefinition: "Monthly Recurring Revenue" }],
+      },
+      options,
+    );
+
+    const paths = pages.map((p) => p.urlPath);
+    expect(paths).toContain("/vs/hubspot");
+    expect(paths).toContain("/alternatives/hubspot");
+    expect(paths).toContain("/pricing/hubspot");
+    expect(paths).toContain("/templates/crm-pipeline-excel");
+    expect(paths).toContain("/glossary/mrr");
+  });
+
+  it("Switches cleanly to French route prefixes when language is 'fr'", () => {
+    const frOptions = { brandName: "Acme", language: "fr" };
+    const pages = engine.generateAllMatrices(
+      "https://acme.com",
+      {
+        competitors: [{ slug: "hubspot", name: "HubSpot", category: "CRM", drawbacks: [], advantagesOver: [] }],
+        templates: [{ slug: "crm-pipeline-excel", title: "CRM Pipeline", topic: "Sales", format: "excel", benefits: ["Gain de temps"] }],
+      },
+      frOptions,
+    );
+
+    const paths = pages.map((p) => p.urlPath);
+    expect(paths).toContain("/comparatif/hubspot");
+    expect(paths).toContain("/tarifs/hubspot");
+    expect(paths).toContain("/modeles/crm-pipeline-excel");
+  });
+
+  it("Generates comprehensive system prompt for LLMs and AI Agents", () => {
+    const prompt = getSeoAgentPrompt({ brandName: "Acme", domain: "https://acme.com" });
+    expect(prompt).toContain("Acme");
+    expect(prompt).toContain("https://acme.com");
+    expect(prompt).toContain("cleanSeoSlug");
+    expect(prompt).toContain("Schema.org");
+  });
+});