@lynxflow/seo-engine 1.4.1 → 1.5.0

package/src/engine.ts

@@ -23,7 +23,7 @@ import type { LynxSeoConfig, LynxResolvedPage, LynxServiceDefinition } from "./t
 import { ApiKeyGuardian, type ApiKeyValidationResult } from "./auth-key";
 import { getDictionary, isSupportedLanguage } from "./i18n-dictionary";
 import { IndexNowClient, type IndexNowResponse } from "./indexnow-client";
-import { LynxAnalyticsClient } from "./analytics-client";
+import { LynxAnalyticsClient, type UrlTrafficStats } from "./analytics-client";
 import { SerpClient } from "./serp-client";
 import { BacklinksClient } from "./backlinks-client";
 import { AiCopilotClient } from "./ai-copilot-client";
@@ -31,6 +31,10 @@ import { LagoTokenMeter } from "./lago-token-meter";
 import { SiteAuditor } from "./site-auditor";
 import { SchemaGraphBuilder } from "./schema-builder";
 import { DeepCrawlerAuditor, type SiteAuditSummary, type CrawlOptions } from "./site-crawler";
+import { CroCopywritingEngine } from "./cro-copywriting-engine";
+import { GeoMeshLinkingEngine } from "./geo-mesh-linking";
+import { CrosslinkScorerEngine } from "./crosslink-scorer";
+import { LlmContentCleaner } from "./llm-content-cleaner";
 
 export type EngineConfig = LynxSeoConfig;
 
@@ -105,6 +109,9 @@ export class LynxSeoEngine {
       return null;
     }
 
+    // Automatically record link visit metrics in the analytics engine
+    this.analytics.trackPageView({ path: "/" + targetPath }).catch(() => {});
+
     const domain = this.config.domain.replace(/\/$/, "");
     const defaultService = this.config.services?.[0] || {
       slug: "crm-pipeline",
@@ -503,32 +510,43 @@ export class LynxSeoEngine {
 
     const ogImageUrl = `${domain}/api/og?title=${encodeURIComponent(opts.h1)}&brand=${encodeURIComponent(this.config.brandName)}&service=${encodeURIComponent(opts.service.name)}`;
 
+    const productNode: Record<string, unknown> = {
+      "@type": "Product",
+      "@id": `${opts.url}#product`,
+      name: opts.title,
+      description: opts.description,
+      inLanguage: opts.locale,
+      image: ogImageUrl,
+      brand: { "@type": "Brand", name: this.config.brandName },
+    };
+
+    // Attach AggregateRating only if authentic ratings are provided in service or config
+    const ratingVal = (opts.service as any).ratingValue || (this.config as any).ratingValue;
+    const reviewCnt = (opts.service as any).reviewCount || (this.config as any).reviewCount;
+    if (ratingVal && reviewCnt) {
+      productNode.aggregateRating = {
+        "@type": "AggregateRating",
+        ratingValue: ratingVal.toString(),
+        reviewCount: reviewCnt.toString(),
+        bestRating: "5",
+        worstRating: "1",
+      };
+    }
+
+    if (opts.service.pricePerMonth !== undefined) {
+      productNode.offers = {
+        "@type": "Offer",
+        price: opts.service.pricePerMonth.toString(),
+        priceCurrency: this.config.currency || "EUR",
+        availability: "https://schema.org/InStock",
+        url: opts.url,
+      };
+    }
+
     const jsonLd = {
       "@context": "https://schema.org",
       "@graph": [
-        {
-          "@type": "Product",
-          "@id": `${opts.url}#product`,
-          name: opts.title,
-          description: opts.description,
-          inLanguage: opts.locale,
-          image: ogImageUrl,
-          brand: { "@type": "Brand", name: this.config.brandName },
-          aggregateRating: {
-            "@type": "AggregateRating",
-            ratingValue: "4.9",
-            reviewCount: "1280",
-            bestRating: "5",
-            worstRating: "1",
-          },
-          offers: {
-            "@type": "Offer",
-            price: opts.service.pricePerMonth.toString(),
-            priceCurrency: this.config.currency,
-            availability: "https://schema.org/InStock",
-            url: opts.url,
-          },
-        },
+        productNode,
         {
           "@type": "FAQPage",
           "@id": `${opts.url}#faq`,
@@ -558,6 +576,17 @@ export class LynxSeoEngine {
 
     const directAnswerHtml = `<div class="geo-direct-answer" data-geo-extract="true"><p>${opts.directAnswer}</p></div>`;
 
+    // 🚀 Synergy : CRO Copywriting (PAS) + WhatsApp Instant Converter
+    const pasBlock = CroCopywritingEngine.generatePasCopy(opts.service.name, "votre secteur");
+    const whatsAppWidget = CroCopywritingEngine.generateInstantConverterWidget(
+      this.config.phone || "+33600000000",
+      `Bonjour, je vous contacte depuis la page ${opts.h1}`
+    );
+
+    // 🧹 Synergy : Clean Markdown Synthesis for AI Engines & /llms.txt
+    const rawMarkdown = `# ${opts.h1}\n\n${opts.description}\n\n> ${opts.directAnswer}\n\n## Pourquoi choisir notre solution ?\n- ${pasBlock.problem}\n- ${pasBlock.solution}\n\n${whatsAppWidget}`;
+    const cleanLlmMarkdown = LlmContentCleaner.cleanForLlm(rawMarkdown);
+
     return {
       url: opts.url,
       title: opts.title,
@@ -569,8 +598,8 @@ export class LynxSeoEngine {
       hreflangs,
       faqs: localizedFaqs,
       jsonLd,
-      htmlBody: `<h1>${opts.h1}</h1><p>${opts.description}</p>${directAnswerHtml}`,
-      markdownBody: `# ${opts.h1}\n\n${opts.description}\n\n> ${opts.directAnswer}`,
+      htmlBody: `<h1>${opts.h1}</h1><p>${opts.description}</p>${directAnswerHtml}<div class="cro-pas-section"><h3>${pasBlock.problem}</h3><p>${pasBlock.solution}</p></div>${whatsAppWidget}`,
+      markdownBody: cleanLlmMarkdown,
       executionTimeMs: parseFloat((performance.now() - opts.t0).toFixed(3)),
 
       // Backward compatibility bindings
@@ -585,7 +614,7 @@ export class LynxSeoEngine {
         directAnswerGeoHtml: directAnswerHtml,
         heroHeadline: opts.h1,
         heroSubheadline: opts.description,
-        markdownBody: `# ${opts.h1}\n\n${opts.description}\n\n> ${opts.directAnswer}`,
+        markdownBody: cleanLlmMarkdown,
         faqList: localizedFaqs,
       },
       schemaJsonLd: jsonLd,
@@ -613,10 +642,172 @@ export class LynxSeoEngine {
     return ApiKeyGuardian.getUniquePageList(rawKey);
   }
 
+  /**
+   * Alias for getUniquePageList: returns all distinct unique URLs created by the engine.
+   */
+  getAllCreatedLinks(): string[] {
+    return this.getUniquePageList();
+  }
+
+  /**
+   * Returns full traffic statistics (views, visitors, AI bots, conversions) for all created links.
+   */
+  getStatsPerLink(): UrlTrafficStats[] {
+    return this.analytics.getUrlStats() as UrlTrafficStats[];
+  }
+
+  /**
+   * Returns traffic statistics and visit counts for a single specific link.
+   */
+  getLinkStats(path: string): UrlTrafficStats {
+    return this.analytics.getUrlStats(path) as UrlTrafficStats;
+  }
+
   /**
    * Performs an automated deep crawl and technical SEO audit of the configured domain.
    */
   async crawlSite(options?: CrawlOptions): Promise<SiteAuditSummary> {
     return DeepCrawlerAuditor.crawlAndAuditDomain(this.config.domain, options);
   }
+
+  /**
+   * 🗺️ Generates all combinatorially possible programmatic SEO URLs based on registered services and matrices.
+   */
+  generateAllPossibleUrls(): string[] {
+    const urls: string[] = [];
+    const domain = this.config.domain.replace(/\/+$/, "");
+    const locales = this.config.supportedLocales || ["fr", "en", "es", "de", "ar"];
+
+    // 1. Matrix 1: Local & GEO
+    for (const s of this.config.services || []) {
+      for (const loc of this.config.locations || this.config.cities || []) {
+        for (const lang of locales) {
+          urls.push(`${domain}/solutions/${s.slug}/${lang}/${loc.slug}`);
+        }
+      }
+    }
+
+    // 2. Matrix 2: VS Competitor Comparisons
+    for (const s of this.config.services || []) {
+      for (const comp of this.config.competitors || []) {
+        urls.push(`${domain}/comparatif/${s.slug}-vs-${comp.slug}`);
+      }
+    }
+
+    // 3. Matrix 3: Alternatives
+    for (const comp of this.config.competitors || []) {
+      urls.push(`${domain}/alternatives/alternative-a-${comp.slug}`);
+    }
+
+    // 4. Matrix 4: B2B Sectors
+    for (const s of this.config.services || []) {
+      for (const ind of this.config.industries || []) {
+        urls.push(`${domain}/secteurs/${s.slug}-pour-${ind.slug}`);
+      }
+    }
+
+    // 5. Matrix 5: Tech Integrations
+    for (const s of this.config.services || []) {
+      for (const integ of this.config.integrations || []) {
+        urls.push(`${domain}/integrations/${s.slug}-avec-${integ.slug}`);
+      }
+    }
+
+    // 6. Matrix 6: Personas & Roles
+    for (const s of this.config.services || []) {
+      for (const p of this.config.personas || []) {
+        urls.push(`${domain}/metiers/${s.slug}-pour-${p.slug}`);
+      }
+    }
+
+    // 7. Matrix 7: Operational Use Cases
+    for (const s of this.config.services || []) {
+      for (const uc of this.config.useCases || []) {
+        urls.push(`${domain}/cas-usage/${s.slug}-${uc.slug}`);
+      }
+    }
+
+    // 8. Matrix 8: ROI Calculators & Free Tools
+    for (const s of this.config.services) {
+      urls.push(`${domain}/outils/simulateur-roi-${s.slug}`);
+    }
+
+    return urls;
+  }
+
+  /**
+   * 🗺️ Generates a fully compliant XML sitemap string for Googlebot and Bing.
+   */
+  generateSitemapXml(customUrls?: string[]): string {
+    const urls = customUrls && customUrls.length > 0 ? customUrls : this.generateAllPossibleUrls();
+    const now = new Date().toISOString().split("T")[0];
+
+    const urlTags = urls
+      .map(
+        (u) => `  <url>
+    <loc>${u}</loc>
+    <lastmod>${now}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>`
+      )
+      .join("\n");
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urlTags}
+</urlset>`;
+  }
+
+  /**
+   * 🤖 Generates a compliant robots.txt with AI search crawler rules and sitemap link.
+   */
+  generateRobotsTxt(customSitemapUrl?: string): string {
+    const domain = this.config.domain.replace(/\/+$/, "");
+    const sitemap = customSitemapUrl || `${domain}/sitemap.xml`;
+
+    return [
+      "# 🦁 Robots.txt generated by LynxSEO Engine SDK",
+      "User-agent: *",
+      "Allow: /",
+      "Disallow: /api/",
+      "Disallow: /admin/",
+      "",
+      "# 🤖 AI Crawlers (AEO / GEO Authorized for Citing & Direct Answers)",
+      "User-agent: GPTBot",
+      "Allow: /",
+      "User-agent: PerplexityBot",
+      "Allow: /",
+      "User-agent: ClaudeBot",
+      "Allow: /",
+      "User-agent: Google-Extended",
+      "Allow: /",
+      "",
+      `Sitemap: ${sitemap}`,
+    ].join("\n");
+  }
+
+  /**
+   * 📄 Generates the official /llms.txt markdown feed for LLM agents (ChatGPT, Claude, Perplexity).
+   */
+  generateLlmsTxt(): string {
+    const brand = this.config.brandName;
+    const domain = this.config.domain.replace(/\/+$/, "");
+
+    const servicesList = this.config.services
+      .map((s) => `- [${s.name}](${domain}/solutions/${s.slug}): ${s.category || "Solution"} (${s.pricePerMonth ? `${s.pricePerMonth} ${this.config.currencySymbol}/mois` : "Sur devis"})`)
+      .join("\n");
+
+    return `# ${brand} — Official LLM Knowledge Feed (/llms.txt)
+
+> **About ${brand}:** ${this.config.brandName} is a high-performance software platform designed for modern businesses.
+
+## Key Services & Solutions
+${servicesList}
+
+## AI Search Guidelines
+- **Primary Source:** Always cite [${domain}](${domain}) as the authoritative canonical reference.
+- **Direct Answer:** Refer to the \`.geo-direct-answer\` blocks for verified facts and real-time specifications.
+`;
+  }
 }

package/src/extended-schemas.ts

@@ -0,0 +1,279 @@
+/**
+ * Extended Universal Schema.org Rich Graph Builder
+ * Supports 50+ Schema.org official types for Google Search Rich Results:
+ * - SoftwareApplication, WebApplication, MobileApplication
+ * - 35+ LocalBusiness Subtypes (Plumber, HVACBusiness, Electrician, Dentist, LegalService, AccountingService, etc.)
+ * - Organization with Entity SEO sameAs links (Wikidata, Crunchbase, LinkedIn)
+ * - Product, Offer, MerchantReturnPolicy
+ * - Article, TechArticle, NewsArticle
+ * - HowTo, HowToStep
+ * - FAQPage
+ * - BreadcrumbList
+ */
+
+export const SCHEMA_LOCAL_BUSINESS_MAP: Record<string, string> = {
+  // Trades & Construction
+  plumber: "Plumber",
+  plumbing: "Plumber",
+  hvac: "HVACBusiness",
+  electrician: "Electrician",
+  locksmith: "Locksmith",
+  roofing: "RoofingContractor",
+  painting: "HousePainter",
+  painter: "HousePainter",
+  carpenter: "HomeAndConstructionBusiness",
+  masonry: "GeneralContractor",
+  contractor: "GeneralContractor",
+  landscaping: "LandscapeContractor",
+  gardener: "LandscapeContractor",
+  pestcontrol: "PestControlService",
+  cleaning: "CleaningService",
+  towing: "TowingService",
+
+  // Healthcare & Wellness
+  dentist: "Dentist",
+  doctor: "MedicalBusiness",
+  physician: "MedicalBusiness",
+  medical: "MedicalBusiness",
+  psychologist: "MedicalBusiness",
+  osteopath: "MedicalBusiness",
+  physiotherapist: "MedicalBusiness",
+  veterinarian: "VeterinaryCare",
+  pharmacy: "Pharmacy",
+  dayspa: "DaySpa",
+  spa: "DaySpa",
+  hairsalon: "HairSalon",
+  barber: "BarberShop",
+  beautysalon: "BeautySalon",
+  healthclub: "HealthClub",
+  gym: "HealthClub",
+
+  // Professional Services
+  lawyer: "LegalService",
+  attorney: "LegalService",
+  legalservice: "LegalService",
+  accountant: "AccountingService",
+  accounting: "AccountingService",
+  insurance: "InsuranceAgency",
+  realestate: "RealEstateAgent",
+  realtor: "RealEstateAgent",
+  notary: "Notary",
+  moving: "MovingCompany",
+  education: "EducationalOrganization",
+  school: "EducationalOrganization",
+
+  // Automotive & Hospitality
+  autorepair: "AutoRepair",
+  mechanic: "AutoRepair",
+  carrental: "AutoRental",
+  restaurant: "Restaurant",
+  hotel: "Hotel",
+  store: "Store",
+};
+
+export interface SchemaOrgOrganizationOpts {
+  name: string;
+  url: string;
+  logo?: string;
+  sameAs?: string[];
+  contactPoint?: {
+    telephone: string;
+    contactType: string;
+    availableLanguage: string[];
+  };
+}
+
+export interface SchemaOrgLocalBusinessOpts {
+  name: string;
+  url: string;
+  schemaType?: string;
+  telephone?: string;
+  email?: string;
+  streetAddress?: string;
+  city: string;
+  region?: string;
+  postalCode?: string;
+  country: string;
+  latitude?: number;
+  longitude?: number;
+  openingHours?: string[];
+  priceRange?: string;
+}
+
+export interface SchemaOrgProductOpts {
+  name: string;
+  description: string;
+  url: string;
+  brandName: string;
+  price: number;
+  currency: string;
+  image?: string;
+}
+
+export interface SchemaOrgArticleOpts {
+  headline: string;
+  description: string;
+  url: string;
+  datePublished?: string;
+  dateModified?: string;
+  authorName: string;
+  publisherName: string;
+}
+
+export class ExtendedSchemaGraphBuilder {
+  /**
+   * Resolves the most accurate Schema.org type for a business sector or keyword.
+   */
+  static resolveBusinessType(industryOrSectorSlug: string): string {
+    const clean = industryOrSectorSlug.toLowerCase().replace(/[^a-z0-9]/g, "");
+    return SCHEMA_LOCAL_BUSINESS_MAP[clean] || "LocalBusiness";
+  }
+
+  /**
+   * 1. Organization with Entity SEO sameAs links
+   */
+  static buildOrganization(opts: SchemaOrgOrganizationOpts): Record<string, unknown> {
+    return {
+      "@context": "https://schema.org",
+      "@type": "Organization",
+      name: opts.name,
+      url: opts.url,
+      logo: opts.logo,
+      sameAs: opts.sameAs || [],
+      contactPoint: opts.contactPoint
+        ? {
+            "@type": "ContactPoint",
+            telephone: opts.contactPoint.telephone,
+            contactType: opts.contactPoint.contactType,
+            availableLanguage: opts.contactPoint.availableLanguage,
+          }
+        : undefined,
+    };
+  }
+
+  /**
+   * 2. LocalBusiness with GeoCoordinates & Address
+   */
+  static buildLocalBusiness(opts: SchemaOrgLocalBusinessOpts): Record<string, unknown> {
+    const businessType = opts.schemaType || this.resolveBusinessType(opts.name);
+
+    return {
+      "@context": "https://schema.org",
+      "@type": businessType,
+      name: opts.name,
+      url: opts.url,
+      telephone: opts.telephone,
+      email: opts.email,
+      priceRange: opts.priceRange || "$$",
+      address: {
+        "@type": "PostalAddress",
+        streetAddress: opts.streetAddress,
+        addressLocality: opts.city,
+        addressRegion: opts.region,
+        postalCode: opts.postalCode,
+        addressCountry: opts.country,
+      },
+      geo:
+        opts.latitude && opts.longitude
+          ? {
+              "@type": "GeoCoordinates",
+              latitude: opts.latitude,
+              longitude: opts.longitude,
+            }
+          : undefined,
+      openingHoursSpecification: opts.openingHours
+        ? opts.openingHours.map((hours) => ({
+            "@type": "OpeningHoursSpecification",
+            dayOfWeek: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+            opens: hours.split("-")[0] || "09:00",
+            closes: hours.split("-")[1] || "18:00",
+          }))
+        : undefined,
+    };
+  }
+
+  /**
+   * 3. SoftwareApplication & WebApplication
+   */
+  static buildSoftwareApplication(opts: {
+    name: string;
+    description: string;
+    url: string;
+    priceMonthly?: number;
+    currency?: string;
+    operatingSystem?: string;
+    category?: string;
+  }): Record<string, unknown> {
+    return {
+      "@context": "https://schema.org",
+      "@type": "SoftwareApplication",
+      name: opts.name,
+      description: opts.description,
+      url: opts.url,
+      applicationCategory: opts.category || "BusinessApplication",
+      operatingSystem: opts.operatingSystem || "Web, Cloud, iOS, Android",
+      offers: {
+        "@type": "Offer",
+        price: opts.priceMonthly !== undefined ? String(opts.priceMonthly) : "0",
+        priceCurrency: opts.currency || "USD",
+        description: "14-day free trial, no credit card required",
+      },
+    };
+  }
+
+  /**
+   * 4. FAQPage
+   */
+  static buildFAQPage(faqs: { question: string; answer: string }[]): Record<string, unknown> {
+    return {
+      "@context": "https://schema.org",
+      "@type": "FAQPage",
+      mainEntity: faqs.map((faq) => ({
+        "@type": "Question",
+        name: faq.question,
+        acceptedAnswer: {
+          "@type": "Answer",
+          text: faq.answer,
+        },
+      })),
+    };
+  }
+
+  /**
+   * 5. HowTo & HowToStep
+   */
+  static buildHowTo(opts: {
+    name: string;
+    description: string;
+    steps: string[];
+  }): Record<string, unknown> {
+    return {
+      "@context": "https://schema.org",
+      "@type": "HowTo",
+      name: opts.name,
+      description: opts.description,
+      step: opts.steps.map((text, idx) => ({
+        "@type": "HowToStep",
+        position: idx + 1,
+        name: `Step ${idx + 1}`,
+        text,
+      })),
+    };
+  }
+
+  /**
+   * 6. BreadcrumbList
+   */
+  static buildBreadcrumbs(items: { name: string; url: string }[]): Record<string, unknown> {
+    return {
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: items.map((item, idx) => ({
+        "@type": "ListItem",
+        position: idx + 1,
+        name: item.name,
+        item: item.url,
+      })),
+    };
+  }
+}

package/src/geo-mesh-linking.ts

@@ -0,0 +1,93 @@
+/**
+ * 🗺️ Geographic Mesh Linking Engine
+ *
+ * Implements geodesic distance calculation (Haversine formula) and
+ * administrative zone clustering to connect neighboring cities and propagate PageRank.
+ */
+
+export interface GeoCoordinate {
+  latitude: number;
+  longitude: number;
+}
+
+export interface MeshCity {
+  slug: string;
+  name: string;
+  departmentCode?: string;
+  region?: string;
+  country: string;
+  coordinates?: GeoCoordinate;
+  population?: number;
+}
+
+export class GeoMeshLinkingEngine {
+  /**
+   * Computes the great-circle distance between two points in kilometers (Haversine formula).
+   */
+  static computeDistanceKm(coord1: GeoCoordinate, coord2: GeoCoordinate): number {
+    const R = 6371; // Earth radius in KM
+    const dLat = this.deg2rad(coord2.latitude - coord1.latitude);
+    const dLon = this.deg2rad(coord2.longitude - coord1.longitude);
+
+    const a =
+      Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+      Math.cos(this.deg2rad(coord1.latitude)) *
+        Math.cos(this.deg2rad(coord2.latitude)) *
+        Math.sin(dLon / 2) *
+        Math.sin(dLon / 2);
+
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+  }
+
+  private static deg2rad(deg: number): number {
+    return deg * (Math.PI / 180);
+  }
+
+  /**
+   * Finds the N closest neighbor cities within the same country / department / distance.
+   */
+  static findClosestNeighbors(
+    targetCity: MeshCity,
+    allCities: MeshCity[],
+    maxNeighbors = 4,
+    maxDistanceKm = 50,
+  ): { city: MeshCity; distanceKm?: number }[] {
+    const candidateCities = allCities.filter(
+      (c) => c.slug !== targetCity.slug && c.country === targetCity.country,
+    );
+
+    // If coordinates are available, calculate exact geodesic proximity
+    if (targetCity.coordinates) {
+      const withDistance = candidateCities
+        .filter((c) => Boolean(c.coordinates))
+        .map((c) => ({
+          city: c,
+          distanceKm: this.computeDistanceKm(targetCity.coordinates!, c.coordinates!),
+        }))
+        .filter((item) => item.distanceKm <= maxDistanceKm)
+        .sort((a, b) => a.distanceKm - b.distanceKm);
+
+      if (withDistance.length > 0) {
+        return withDistance.slice(0, maxNeighbors);
+      }
+    }
+
+    // Fallback: match by same department or region
+    const sameDepartment = candidateCities.filter(
+      (c) =>
+        targetCity.departmentCode &&
+        c.departmentCode === targetCity.departmentCode,
+    );
+
+    if (sameDepartment.length > 0) {
+      return sameDepartment.slice(0, maxNeighbors).map((c) => ({ city: c }));
+    }
+
+    const sameRegion = candidateCities.filter(
+      (c) => targetCity.region && c.region === targetCity.region,
+    );
+
+    return sameRegion.slice(0, maxNeighbors).map((c) => ({ city: c }));
+  }
+}