@lynxflow/seo-engine 1.4.0 → 1.5.0

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 }));
+  }
+}

package/src/index.ts

@@ -11,6 +11,10 @@
  */
 
 export * from "./engine";
+export * from "./slug-engine";
+export * from "./legal-disclaimers";
+export * from "./matrix-engine";
+export * from "./llm-prompt";
 export * from "./auth-key";
 export * from "./token-quota-manager";
 export * from "./lago-token-meter";
@@ -18,11 +22,39 @@ export * from "./indexnow-client";
 export * from "./site-auditor";
 export * from "./site-crawler";
 export * from "./schema-builder";
+export * from "./extended-schemas";
 export * from "./analytics-client";
 export * from "./serp-client";
 export * from "./backlinks-client";
 export * from "./ai-copilot-client";
 export * from "./types";
+export * from "./geo-mesh-linking";
+export * from "./brand-dna-calendar";
+export * from "./technical-rules-auditor";
+export * from "./ai-bots-log-analyzer";
+export * from "./serp-history-alerts";
+export * from "./seo-opportunities-decay";
+export * from "./knowledge-graph-linker";
+export * from "./cro-copywriting-engine";
+export * from "./mcp-seo-server";
+export * from "./master-marketing-engine";
+export * from "./social-video-seo";
+export * from "./social-trend-seo";
+export * from "./crosslink-scorer";
+export * from "./instant-matrix-search";
+export * from "./rss-syndication-feed";
+export * from "./embeddable-seo-widget";
+export * from "./ngram-density-analyzer";
+export * from "./isr-cache-manager";
+export * from "./llm-content-cleaner";
+export * from "./copy-frameworks-master";
+export * from "./social-ads-seo";
+export * from "./ad-intelligence-cro";
+export * from "./rank-math-parity";
+export * from "./yoast-parity";
+export * from "./social-growth-suite";
+export * from "./team-rbac";
+export * from "./real-reviews-sync";
 
 import { LynxSeoEngine, type EngineConfig } from "./engine";
 import { ApiKeyGuardian } from "./auth-key";
@@ -32,6 +64,35 @@ import { IndexNowClient } from "./indexnow-client";
 import { SiteAuditor } from "./site-auditor";
 import { DeepCrawlerAuditor } from "./site-crawler";
 import { SchemaGraphBuilder } from "./schema-builder";
+import { ExtendedSchemaGraphBuilder } from "./extended-schemas";
+
+import { GeoMeshLinkingEngine } from "./geo-mesh-linking";
+import { BrandDnaCalendarEngine } from "./brand-dna-calendar";
+import { TechnicalRulesAuditor } from "./technical-rules-auditor";
+import { AiBotsLogAnalyzer } from "./ai-bots-log-analyzer";
+import { SerpRankHistoryEngine } from "./serp-history-alerts";
+import { SeoOpportunitiesDecayDetector } from "./seo-opportunities-decay";
+import { KnowledgeGraphLinker } from "./knowledge-graph-linker";
+import { CroCopywritingEngine } from "./cro-copywriting-engine";
+import { McpSeoServerHub } from "./mcp-seo-server";
+import { MasterMarketingEngine } from "./master-marketing-engine";
+import { SocialVideoSeoAnalyticsEngine } from "./social-video-seo";
+import { SocialTrendSeoGenerator } from "./social-trend-seo";
+import { CrosslinkScorerEngine } from "./crosslink-scorer";
+import { InstantMatrixSearchEngine } from "./instant-matrix-search";
+import { RssSyndicationFeedGenerator } from "./rss-syndication-feed";
+import { EmbeddableSeoWidgetGenerator } from "./embeddable-seo-widget";
+import { NGramDensityAnalyzer } from "./ngram-density-analyzer";
+import { IsrCacheManager } from "./isr-cache-manager";
+import { LlmContentCleaner } from "./llm-content-cleaner";
+import { CopywritingFrameworksMaster } from "./copy-frameworks-master";
+import { SocialAdsSocialSeoEngine } from "./social-ads-seo";
+import { AdIntelligenceCroEngine } from "./ad-intelligence-cro";
+import { RankMathParityEngine } from "./rank-math-parity";
+import { YoastParityEngine } from "./yoast-parity";
+import { SocialGrowthSuite } from "./social-growth-suite";
+import { TeamRbacEngine } from "./team-rbac";
+import { RealReviewsSyncEngine } from "./real-reviews-sync";
 
 export function createLynxSeoEngine(config: EngineConfig) {
   return new LynxSeoEngine(config);
@@ -48,6 +109,34 @@ export const LynxSeo = {
   crawlDomain: DeepCrawlerAuditor.crawlAndAuditDomain,
   inspectHtmlSnapshot: DeepCrawlerAuditor.inspectHtmlSnapshot,
   buildSchemaGraph: SchemaGraphBuilder.buildGraph,
+  extendedSchemas: ExtendedSchemaGraphBuilder,
+  geoMesh: GeoMeshLinkingEngine,
+  brandDna: BrandDnaCalendarEngine,
+  technicalAuditor: TechnicalRulesAuditor,
+  aiBotsLogger: AiBotsLogAnalyzer,
+  serpRankHistory: SerpRankHistoryEngine,
+  opportunitiesDecay: SeoOpportunitiesDecayDetector,
+  knowledgeGraph: KnowledgeGraphLinker,
+  croCopywriting: CroCopywritingEngine,
+  mcpServer: McpSeoServerHub,
+  marketing: MasterMarketingEngine,
+  socialVideo: SocialVideoSeoAnalyticsEngine,
+  socialTrends: SocialTrendSeoGenerator,
+  crosslinks: CrosslinkScorerEngine,
+  instantSearch: InstantMatrixSearchEngine,
+  rssFeed: RssSyndicationFeedGenerator,
+  embeddableWidget: EmbeddableSeoWidgetGenerator,
+  ngramDensity: NGramDensityAnalyzer,
+  isrCache: IsrCacheManager,
+  llmCleaner: LlmContentCleaner,
+  copyFrameworks: CopywritingFrameworksMaster,
+  socialAds: SocialAdsSocialSeoEngine,
+  adIntelligence: AdIntelligenceCroEngine,
+  rankMathScore: RankMathParityEngine,
+  yoastReadability: YoastParityEngine,
+  socialGrowth: SocialGrowthSuite,
+  rbac: TeamRbacEngine,
+  realReviews: RealReviewsSyncEngine,
 };
 
 export default LynxSeo;

package/src/instant-matrix-search.ts

@@ -0,0 +1,48 @@
+/**
+ * 🔎 Instant In-Memory Matrix Search & Autocomplete ("Buscador") (Inspiration: santifer-irepair)
+ *
+ * Provides sub-millisecond client-side live filtering and autocomplete across all 8 programmatic matrices.
+ */
+
+export interface SearchableMatrixPage {
+  url: string;
+  title: string;
+  serviceName: string;
+  matrixType: string;
+  modifierName: string; // City, Competitor, Industry, Software, Persona...
+  keywords: string[];
+}
+
+export class InstantMatrixSearchEngine {
+  /**
+   * Fast in-memory search over programmatic pages.
+   */
+  static search(query: string, pages: SearchableMatrixPage[], limit = 10): SearchableMatrixPage[] {
+    const cleanQuery = query.trim().toLowerCase();
+    if (!cleanQuery) return [];
+
+    const tokens = cleanQuery.split(/\s+/).filter(Boolean);
+
+    return pages
+      .map((p) => {
+        const textTarget = `${p.title} ${p.serviceName} ${p.modifierName} ${p.keywords.join(" ")}`.toLowerCase();
+        let matchScore = 0;
+
+        for (const token of tokens) {
+          if (textTarget.includes(token)) {
+            matchScore += 1;
+            // Exact prefix match bonus
+            if (p.modifierName.toLowerCase().startsWith(token) || p.serviceName.toLowerCase().startsWith(token)) {
+              matchScore += 2;
+            }
+          }
+        }
+
+        return { page: p, score: matchScore };
+      })
+      .filter((item) => item.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit)
+      .map((item) => item.page);
+  }
+}

package/src/isr-cache-manager.ts

@@ -0,0 +1,78 @@
+/**
+ * ⚡ Incremental Static Regeneration (ISR) & Edge Invalidation Cache Manager
+ *
+ * Implements high-throughput in-memory LRU caching with stale-while-revalidate semantics
+ * and selective tag-based invalidation for programmatic pages.
+ */
+
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  tags: string[];
+}
+
+export class IsrCacheManager {
+  private static cache = new Map<string, CacheEntry<any>>();
+  private static defaultTtlMs = 24 * 3600 * 1000; // 24 hours
+
+  /**
+   * Retrieves an item from cache, or executes the resolver and caches the result.
+   */
+  static async getOrSet<T>(
+    key: string,
+    resolver: () => Promise<T> | T,
+    tags: string[] = [],
+    ttlMs = this.defaultTtlMs,
+  ): Promise<T> {
+    const cached = this.cache.get(key);
+    const now = Date.now();
+
+    if (cached && now - cached.timestamp < ttlMs) {
+      return cached.data;
+    }
+
+    const data = await resolver();
+    this.cache.set(key, {
+      data,
+      timestamp: now,
+      tags,
+    });
+
+    return data;
+  }
+
+  /**
+   * Invalidates a specific cache key.
+   */
+  static invalidateKey(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Invalidates all cache entries matching a tag (e.g. "service:crm-pipeline" or "city:lyon").
+   */
+  static invalidateTag(tag: string): number {
+    let count = 0;
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.tags.includes(tag)) {
+        this.cache.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Clears the entire cache.
+   */
+  static clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Returns cache size.
+   */
+  static size(): number {
+    return this.cache.size;
+  }
+}

package/src/knowledge-graph-linker.ts

@@ -0,0 +1,81 @@
+/**
+ * 🧠 Google Knowledge Graph Entity Linker (Inspiration: advertools/knowledge_graph.py)
+ *
+ * Resolves official Google Entity IDs (`kgmid`), entity types, and Wikidata URIs
+ * to maximize semantic authority and Knowledge Panel recognition (Entity SEO).
+ */
+
+export interface KnowledgeGraphEntity {
+  name: string;
+  kgmid: string; // e.g. "/m/02zsn" or "kg:/g/11b6t4q7k"
+  types: string[]; // e.g. ["Organization", "Corporation", "SoftwareApplication"]
+  description?: string;
+  detailedDescriptionUrl?: string;
+  wikidataUri?: string;
+  resultScore: number;
+}
+
+export class KnowledgeGraphLinker {
+  /**
+   * Constructs search query parameters for the Google Knowledge Graph Search API.
+   */
+  static buildSearchUrl(query: string, apiKey: string, limit = 5, languages = ["fr", "en"]): string {
+    const params = new URLSearchParams({
+      query,
+      key: apiKey,
+      limit: String(limit),
+      indent: "true",
+      languages: languages.join(","),
+    });
+    return `https://kgsearch.googleapis.com/v1/entities:search?${params.toString()}`;
+  }
+
+  /**
+   * Parses Google Knowledge Graph JSON-LD response items into normalized entities.
+   */
+  static parseApiResponse(jsonResponse: any): KnowledgeGraphEntity[] {
+    if (!jsonResponse || !Array.isArray(jsonResponse.itemListElement)) {
+      return [];
+    }
+
+    return jsonResponse.itemListElement.map((item: any) => {
+      const result = item.result || {};
+      const kgmid = result["@id"] || "";
+      const types = Array.isArray(result["@type"]) ? result["@type"] : [result["@type"] || "Thing"];
+      const detailed = result.detailedDescription || {};
+
+      let wikidataUri: string | undefined;
+      if (detailed.url && detailed.url.includes("wikipedia.org")) {
+        wikidataUri = detailed.url;
+      }
+
+      return {
+        name: result.name || "",
+        kgmid,
+        types,
+        description: detailed.articleBody || result.description,
+        detailedDescriptionUrl: detailed.url,
+        wikidataUri,
+        resultScore: item.resultScore || 0,
+      };
+    });
+  }
+
+  /**
+   * Generates Schema.org `sameAs` entity triples combining Google kgmid and Wikipedia/Wikidata.
+   */
+  static generateEntitySameAsLinks(entity: KnowledgeGraphEntity, customUrls: string[] = []): string[] {
+    const links: string[] = [...customUrls];
+
+    if (entity.kgmid) {
+      const cleanMid = entity.kgmid.replace(/^kg:/, "");
+      links.push(`https://www.google.com/search?kgmid=${encodeURIComponent(cleanMid)}`);
+    }
+
+    if (entity.wikidataUri) {
+      links.push(entity.wikidataUri);
+    }
+
+    return Array.from(new Set(links));
+  }
+}