@lynxflow/seo-engine 1.4.1 → 1.5.1

package/src/legal-disclaimers.ts

@@ -0,0 +1,407 @@
+/**
+ * Global Legal Compliance & Editorial Disclaimer Engine for B2B pSEO
+ * Multilingual compliance and anti-disparagement verification across 10+ languages.
+ */
+
+export type DisclaimerType =
+  | "comparison"
+  | "pricing"
+  | "feature"
+  | "exclusivity"
+  | "statistics"
+  | "alternative"
+  | "listicle";
+
+export interface DisclaimerTemplate {
+  type: DisclaimerType;
+  label: string;
+  templateText: string;
+}
+
+/**
+ * Multilingual Disclaimer Templates (English Default + Localized Fallbacks)
+ */
+export const MULTILINGUAL_DISCLAIMERS: Record<string, Record<DisclaimerType, DisclaimerTemplate>> = {
+  // 🇬🇧 English (Default)
+  en: {
+    comparison: {
+      type: "comparison",
+      label: "Standard Comparison Notice",
+      templateText:
+        "Editorial note: We research and verify all claims in our comparison articles using publicly available documentation. Pricing and features are subject to change by each provider. Report any inaccuracies to {correctionsEmail}.",
+    },
+    pricing: {
+      type: "pricing",
+      label: "Pricing Transparency Disclaimer",
+      templateText:
+        "Pricing disclaimer: All competitor pricing and plan details were verified on {lastVerifiedDate}. Providers may update their rates at any time without notice. Please verify current rates on the official provider website before making purchasing decisions.",
+    },
+    feature: {
+      type: "feature",
+      label: "Feature Capability Note",
+      templateText:
+        "Feature comparison note: Feature availability and tier limits were verified on {lastVerifiedDate}. Software updates occur continuously; consult each vendor's documentation for live specifications.",
+    },
+    exclusivity: {
+      type: "exclusivity",
+      label: "Exclusivity Distinction Claim",
+      templateText:
+        "Distinction note: To the best of our knowledge as of {lastVerifiedDate}, this architectural capability distinction is accurate based on public benchmarks.",
+    },
+    statistics: {
+      type: "statistics",
+      label: "Public Data & Statistics Note",
+      templateText:
+        "Data note: Statistics and benchmarks cited in this article are derived from public industry reports and official platform metrics as of {lastVerifiedDate}.",
+    },
+    alternative: {
+      type: "alternative",
+      label: "Alternative Directory Notice",
+      templateText:
+        "Editorial note: This page compares software alternatives objectively based on public specifications, user feedback, and architectural differences to help buyers make informed decisions.",
+    },
+    listicle: {
+      type: "listicle",
+      label: "Curated Directory & Review Notice",
+      templateText:
+        "Editorial note: Rankings and software evaluations reflect our objective editorial criteria and testing methodology. Inaccuracies can be flagged to {correctionsEmail}.",
+    },
+  },
+
+  // 🇫🇷 French
+  fr: {
+    comparison: {
+      type: "comparison",
+      label: "Note Éditoriale de Comparatif",
+      templateText:
+        "Note éditoriale : Nous vérifions scrupuleusement les informations sur la base des documentations publiques. Les fonctionnalités et tarifs évoluent régulièrement. Signalez toute inexactitude à {correctionsEmail}.",
+    },
+    pricing: {
+      type: "pricing",
+      label: "Avertissement sur les Tarifs",
+      templateText:
+        "Avertissement tarifaire : Les prix et offres ont été relevés le {lastVerifiedDate}. Les éditeurs peuvent modifier leurs conditions sans préavis. Vérifiez les tarifs officiels avant toute souscription.",
+    },
+    feature: {
+      type: "feature",
+      label: "Vérification des Fonctionnalités",
+      templateText:
+        "Note sur les fonctionnalités : La disponibilité des options a été vérifiée le {lastVerifiedDate}. Consultez les sites éditeurs pour les spécifications en direct.",
+    },
+    exclusivity: {
+      type: "exclusivity",
+      label: "Revendication d'Exclusivité",
+      templateText:
+        "Note d'exclusivité : Selon nos informations vérifiées au {lastVerifiedDate}, cette capacité technique est exclusive à notre plateforme.",
+    },
+    statistics: {
+      type: "statistics",
+      label: "Données et Statistiques Publiques",
+      templateText:
+        "Source des données : Les métriques citées proviennent de rapports sectoriels publics au {lastVerifiedDate}.",
+    },
+    alternative: {
+      type: "alternative",
+      label: "Annuaire des Alternatives",
+      templateText:
+        "Note éditoriale : Cette sélection compare objectivement les solutions du marché pour éclairer le choix des décideurs.",
+    },
+    listicle: {
+      type: "listicle",
+      label: "Méthodologie de Classement",
+      templateText:
+        "Note éditoriale : Ce classement reflète notre analyse technique indépendante. Contact : {correctionsEmail}.",
+    },
+  },
+
+  // 🇩🇪 German
+  de: {
+    comparison: {
+      type: "comparison",
+      label: "Redaktioneller Vergleichshinweis",
+      templateText:
+        "Redaktioneller Hinweis: Wir recherchieren und prüfen alle Angaben anhand öffentlich zugänglicher Dokumentationen. Preise und Funktionen können sich ändern. Bitte melden Sie Unstimmigkeiten an {correctionsEmail}.",
+    },
+    pricing: {
+      type: "pricing",
+      label: "Preistransparenz-Hinweis",
+      templateText:
+        "Preishinweis: Alle Preisangaben wurden am {lastVerifiedDate} überprüft. Anbieter können ihre Preise jederzeit anpassen. Bitte prüfen Sie die offiziellen Anbieterseiten.",
+    },
+    feature: {
+      type: "feature",
+      label: "Funktionshinweis",
+      templateText:
+        "Funktionshinweis: Die Verfügbarkeit von Funktionen wurde am {lastVerifiedDate} verifiziert.",
+    },
+    exclusivity: {
+      type: "exclusivity",
+      label: "Exklusivitätsangabe",
+      templateText:
+        "Hinweis: Nach unserem Kenntnisstand vom {lastVerifiedDate} ist dieses Merkmal eine spezifische Eigenschaft unserer Lösung.",
+    },
+    statistics: {
+      type: "statistics",
+      label: "Statistikhinweis",
+      templateText:
+        "Datenhinweis: Die genannten Statistiken basieren auf öffentlich zugänglichen Branchenberichten mit Stand vom {lastVerifiedDate}.",
+    },
+    alternative: {
+      type: "alternative",
+      label: "Alternativen-Verzeichnis",
+      templateText:
+        "Redaktioneller Hinweis: Dieser Vergleich bietet eine objektive Gegenüberstellung moderner Software-Alternativen.",
+    },
+    listicle: {
+      type: "listicle",
+      label: "Bewertungshinweis",
+      templateText:
+        "Redaktioneller Hinweis: Bewertungen basieren auf unserer unabhängigen Testmethodik. Feedback an {correctionsEmail}.",
+    },
+  },
+
+  // 🇪🇸 Spanish
+  es: {
+    comparison: {
+      type: "comparison",
+      label: "Nota Editorial Comparativa",
+      templateText:
+        "Nota editorial: Investigamos y verificamos la información con datos públicos. Los precios y funciones pueden variar. Notifique cualquier error a {correctionsEmail}.",
+    },
+    pricing: {
+      type: "pricing",
+      label: "Aviso sobre Precios",
+      templateText:
+        "Aviso de precios: Toda la información de precios fue verificada el {lastVerifiedDate}. Los proveedores pueden cambiar sus tarifas sin previo aviso.",
+    },
+    feature: {
+      type: "feature",
+      label: "Nota de Funcionalidades",
+      templateText:
+        "Nota de funciones: La disponibilidad de funciones fue verificada el {lastVerifiedDate}.",
+    },
+    exclusivity: {
+      type: "exclusivity",
+      label: "Distinción Exclusiva",
+      templateText:
+        "Nota de exclusividad: Según los datos verificados al {lastVerifiedDate}, esta capacidad es única de nuestra plataforma.",
+    },
+    statistics: {
+      type: "statistics",
+      label: "Datos Estadísticos",
+      templateText:
+        "Nota de datos: Las estadísticas provienen de informes sectoriales públicos al {lastVerifiedDate}.",
+    },
+    alternative: {
+      type: "alternative",
+      label: "Directorio de Alternativas",
+      templateText:
+        "Nota editorial: Esta página compara alternativas de software de forma objetiva para ayudar en la toma de decisiones.",
+    },
+    listicle: {
+      type: "listicle",
+      label: "Metodología del Ranking",
+      templateText:
+        "Nota editorial: Las recomendaciones se basan en nuestro análisis objetivo. Contacto: {correctionsEmail}.",
+    },
+  },
+};
+
+/**
+ * Multilingual Banned & Disparaging Words Dictionary across 10 Languages
+ */
+export const MULTILINGUAL_BANNED_DISPARAGING_WORDS: Record<string, string[]> = {
+  // 🇬🇧 English
+  en: [
+    "is a scam",
+    "fraudulent",
+    "worst software",
+    "useless product",
+    "terrible company",
+    "don't trust",
+    "rip-off",
+    "garbage software",
+    "incompetent",
+  ],
+
+  // 🇫🇷 French
+  fr: [
+    "est une arnaque",
+    "frauduleux",
+    "pire logiciel",
+    "produit inutile",
+    "entreprise malhonnête",
+    "ne faites pas confiance",
+    "escroquerie",
+    "logiciel poubelle",
+    "incompétent",
+  ],
+
+  // 🇩🇪 German
+  de: [
+    "ist ein betrug",
+    "betrügerisch",
+    "schlechteste software",
+    "nutzloses produkt",
+    "unseriöse firma",
+    "nicht vertrauen",
+    "abzocke",
+    "müll software",
+    "inkompetent",
+  ],
+
+  // 🇪🇸 Spanish
+  es: [
+    "es una estafa",
+    "fraudulento",
+    "peor software",
+    "producto inutil",
+    "empresa deshonesta",
+    "no confie",
+    "timo",
+    "software basura",
+    "incompetente",
+  ],
+
+  // 🇮🇹 Italian
+  it: [
+    "e una truffa",
+    "fraudolento",
+    "peggior software",
+    "prodotto inutile",
+    "azienda disonesta",
+    "non fidarti",
+    "fregatura",
+    "software spazzatura",
+  ],
+
+  // 🇵🇹 Portuguese
+  pt: [
+    "e um golpe",
+    "fraudulento",
+    "pior software",
+    "produto inutil",
+    "empresa desonesta",
+    "nao confie",
+    "engranacao",
+    "software lixo",
+  ],
+
+  // 🇳🇱 Dutch
+  nl: [
+    "is oplichterij",
+    "frauduleus",
+    "slechtste software",
+    "nutteloos product",
+    "onbetrouwbaar bedrijf",
+    "niet vertrouwen",
+  ],
+
+  // 🇷🇺 Russian (Latinized)
+  ru: [
+    "eto moshennichestvo",
+    "hudshiy soft",
+    "bespoleznyy produkt",
+    "obman",
+  ],
+
+  // 🇸🇪 Swedish
+  sv: [
+    "ar en bluff",
+    "bedraglig",
+    "samsta mjukvaran",
+    "vardelos produkt",
+    "lita inte pa",
+  ],
+
+  // 🇵🇱 Polish
+  pl: [
+    "to oszustwo",
+    "najgorsze oprogramowanie",
+    "bezuzyteczny produkt",
+    "nie ufaj",
+  ],
+};
+
+export interface LegalEngineOptions {
+  companyName?: string;
+  correctionsEmail?: string;
+  dataStalenessDays?: number;
+  language?: string;
+}
+
+export class LegalDisclaimerEngine {
+  private companyName: string;
+  private correctionsEmail: string;
+  private dataStalenessDays: number;
+  private defaultLanguage: string;
+
+  constructor(options: LegalEngineOptions = {}) {
+    this.companyName = options.companyName || "Our Platform";
+    this.correctionsEmail = options.correctionsEmail || "compliance@platform.com";
+    this.dataStalenessDays = options.dataStalenessDays ?? 90;
+    this.defaultLanguage = options.language || "en";
+  }
+
+  /**
+   * Generates a fully resolved disclaimer note in the target language (defaults to English).
+   */
+  getDisclaimer(type: DisclaimerType, lastVerifiedDate?: string, language?: string): string {
+    const lang = language || this.defaultLanguage;
+    const langTemplates = MULTILINGUAL_DISCLAIMERS[lang] || MULTILINGUAL_DISCLAIMERS.en;
+    const template = langTemplates[type]?.templateText || MULTILINGUAL_DISCLAIMERS.en.comparison.templateText;
+    const dateStr = lastVerifiedDate || new Date().toISOString().split("T")[0];
+
+    return template
+      .replace(/{companyName}/g, this.companyName)
+      .replace(/{correctionsEmail}/g, this.correctionsEmail)
+      .replace(/{lastVerifiedDate}/g, dateStr);
+  }
+
+  /**
+   * Evaluates if competitor pricing or feature claim data is older than the allowed staleness window (default: 90 days).
+   */
+  isDataStale(lastVerifiedDateStr?: string): boolean {
+    if (!lastVerifiedDateStr) return true;
+    const verified = new Date(lastVerifiedDateStr).getTime();
+    if (isNaN(verified)) return true;
+
+    const diffDays = (Date.now() - verified) / (1000 * 60 * 60 * 24);
+    return diffDays > this.dataStalenessDays;
+  }
+
+  /**
+   * Validates content against disparaging or legally hazardous statements across all supported languages.
+   */
+  validateCompliance(content: string, competitorName: string, language: string = "all"): { isCompliant: boolean; warnings: string[] } {
+    const warnings: string[] = [];
+    const lowerContent = content.toLowerCase();
+    const lowerComp = competitorName.toLowerCase();
+
+    // Check banned phrases in target language or across all languages
+    const activeLanguages = language === "all"
+      ? Object.keys(MULTILINGUAL_BANNED_DISPARAGING_WORDS)
+      : [language];
+
+    for (const lang of activeLanguages) {
+      const phrases = MULTILINGUAL_BANNED_DISPARAGING_WORDS[lang] || [];
+      for (const phrase of phrases) {
+        if (lowerContent.includes(phrase)) {
+          warnings.push(`[${lang.toUpperCase()}] Hazardous disparaging claim detected: "${phrase}". Maintain objective technical framing.`);
+        }
+      }
+    }
+
+    // Mention frequency check (prevent trademark keyword stuffing)
+    const regex = new RegExp(`\\b${lowerComp}\\b`, "gi");
+    const count = (lowerContent.match(regex) || []).length;
+    if (count > 25) {
+      warnings.push(`Excessive competitor trademark mentions (${count} times). Reduce to under 20 to avoid trademark dilution flags.`);
+    }
+
+    return {
+      isCompliant: warnings.length === 0,
+      warnings,
+    };
+  }
+}

package/src/llm-content-cleaner.ts

@@ -0,0 +1,64 @@
+/**
+ * 🧹 Boilerplate Stripper & Clean Markdown Extractor for LLMs (Inspiration: openserp/extract)
+ *
+ * Strips navigation, headers, footers, cookie banners, and advertisements from raw HTML
+ * to produce clean, high-density markdown text for AI search ingestion (/llms.txt & ChatGPT).
+ */
+
+export class LlmContentCleaner {
+  /**
+   * Alias: Cleans text or markdown for LLMs.
+   */
+  static cleanForLlm(content: string): string {
+    return this.htmlToCleanMarkdown(content);
+  }
+
+  /**
+   * Cleans raw HTML and returns pure readable markdown content.
+   */
+  static htmlToCleanMarkdown(rawHtml: string): string {
+    if (!rawHtml) return "";
+
+    let cleaned = rawHtml
+      // Remove scripts, styles, iframes, SVGs
+      .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, " ")
+      .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, " ")
+      .replace(/<svg\b[^<]*(?:(?!<\/svg>)<[^<]*)*<\/svg>/gi, " ")
+      .replace(/<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe>/gi, " ")
+      // Remove navigation, headers, footers, modals, cookie banners
+      .replace(/<nav\b[^<]*(?:(?!<\/nav>)<[^<]*)*<\/nav>/gi, " ")
+      .replace(/<footer\b[^<]*(?:(?!<\/footer>)<[^<]*)*<\/footer>/gi, " ")
+      .replace(/<header\b[^<]*(?:(?!<\/header>)<[^<]*)*<\/header>/gi, " ")
+      .replace(/<aside\b[^<]*(?:(?!<\/aside>)<[^<]*)*<\/aside>/gi, " ")
+      // Convert headings
+      .replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, "\n# $1\n")
+      .replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, "\n## $1\n")
+      .replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, "\n### $1\n")
+      .replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, "\n#### $1\n")
+      // Convert lists
+      .replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, "\n* $1")
+      // Convert paragraphs and line breaks
+      .replace(/<p[^>]*>([\s\S]*?)<\/p>/gi, "\n$1\n")
+      .replace(/<br\s*[\/]?>/gi, "\n")
+      // Convert links
+      .replace(/<a[^>]*href=["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)")
+      // Strip remaining HTML tags
+      .replace(/<[^>]+>/g, " ")
+      // Decode basic HTML entities
+      .replace(/&nbsp;/g, " ")
+      .replace(/&amp;/g, "&")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'");
+
+    // Clean whitespace and repeated linebreaks
+    cleaned = cleaned
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line, i, arr) => line !== "" || (i > 0 && arr[i - 1] !== ""))
+      .join("\n");
+
+    return cleaned.trim();
+  }
+}

package/src/llm-prompt.ts

@@ -0,0 +1,81 @@
+/**
+ * Built-in AI Agent & LLM System Prompt Guide
+ * Provides complete operational context for autonomous coding agents (Claude, Cursor, Copilot, ChatGPT, Antigravity)
+ * to configure Programmatic SEO correctly without leaking backend providers or hardcoding translations.
+ */
+
+export const PSEO_AGENT_SYSTEM_PROMPT = `
+You are the Programmatic SEO Implementation Specialist powered by @lynxflow/seo-engine.
+Your role is to configure, resolve, and maintain programmatic SEO pages, XML sitemaps, Schema.org JSON-LD graphs, and compliance rules.
+
+---
+
+### 🚨 1. CRITICAL RULE: FEATURE DISCOVERY FROM FRONTEND ONLY (NEVER USE BACKEND / PROVIDERS)
+
+When discovering or listing product modules, features, or services to build the SEO matrices:
+- **❌ NEVER inspect backend API routes, internal database folders, or third-party providers:**
+  - DO NOT create programmatic pages for internal plumbing like: \`/api/stripe\`, \`/api/resend\`, \`/api/auth\`, \`/api/d1\`, \`/api/webhooks\`, \`/api/openai\`.
+  - DO NOT expose internal infrastructure, vendors, or suppliers (e.g. Stripe, Resend, Cloudflare D1, Better-Auth, Supabase, PostgreSQL drivers) as public product features. End users never search for or buy your internal backend plumbing.
+- **✅ ALWAYS inspect the FRONTEND user-facing interface & commercial value propositions:**
+  - Read marketing navigation menus & dropdowns (\`components/Navbar.tsx\`, \`components/Header.tsx\`, \`components/Navigation.tsx\`).
+  - Read marketing feature pages & pricing tiers (\`app/(marketing)/*\`, \`pages/features/*\`, \`app/pricing/*\`).
+  - Read dashboard UI workflows & user modules (\`components/dashboard/*\`, \`components/sidebar/*\`).
+  - Identify the actual **benefits and tools the end-user buys** (e.g. "Visual Pipeline Kanban", "Automated Invoice Tracking", "Electronic Signature", "Real-Time Client Portal", "Custom Reporting").
+
+---
+
+### 🌐 2. ARCHITECTURAL RULE: THE WEBSITE OWNS ITS LANGUAGES (i18n)
+
+- **The Website (Application) is the sole owner of its languages, routes, and translations:**
+  - The website provides its own localized routes (e.g. \`app/[locale]/[...slug]/page.tsx\`) and dictionary files (\`next-intl\`, \`i18next\`, Astro i18n).
+- **The SDK is a 100% language-agnostic structural engine:**
+  - The SDK receives the \`locale\` and data passed by the application at runtime.
+  - The SDK generates Google-compliant Schema.org JSON-LD, resolves routes in-memory (< 0.05ms), normalizes slugs, builds cross-language \`hreflang\` alternate tags, and partitions sitemaps.
+
+---
+
+### 🏛️ 3. MATRIX ARCHITECTURE: 10 ROOT PILLARS & 50+ SPECIALIZED SUB-MATRICES
+
+1. **10 Canonical Root Pillars:**
+   - Comparisons: \`/vs/{competitor}\`
+   - Alternatives: \`/alternatives/{competitor}\` (Zero keyword stuttering)
+   - Pricing: \`/pricing/{competitor}\`
+   - Audiences: \`/for/{target}\` (Unified industry/role mapping, anti-cannibalization)
+   - Integrations: \`/integrations/{app}\` (Clean slug without stop words)
+   - Use Cases: \`/use-cases/{useCase}\` (Actionable workflows with HowTo JSON-LD)
+   - Templates: \`/templates/{slug}\` (High-converting spreadsheet/notion lead magnets)
+   - Glossary: \`/glossary/{term}\` (Topic authority cluster hub)
+   - Tools: \`/tools/{calculator}\` (Interactive ROI & value estimators)
+   - Local Geo: \`/solutions/{service}/{country}/{city}\` (Tiered Indexing & Mesh Links)
+
+2. **50+ Specialized Sub-Matrix Dimensions:**
+   - **Industry & Regulatory (12):** Sector × Compliance (e.g., GDPR Law Firm), Sector × Team Size.
+   - **Role & Workflow (10):** Role × Core KPI (e.g., Sales Director Revenue), Role × Daily Toolchain.
+   - **Multi-Format Templates (8):** Subject × Format (Excel .xlsx, Notion, Google Sheets, Word, PDF).
+   - **Ecosystem & Integrations (10):** Module × App (e.g., CRM × Shopify), Connector × Webhook Trigger.
+   - **Problem Playbooks (8):** Pain Point × Step-by-Step Playbook, Bottleneck × ROI.
+   - **Interactive Calculators (6):** Time-Saved Estimator, Revenue Uplift Simulator.
+   - **Topic Authority Clusters (6):** Financial Metrics (MRR, LTV), Technical Protocols (OAuth, Webhook).
+
+---
+
+### 🧹 4. URL SLUG INTEGRITY & SCHEMA.ORG
+
+- Use \`cleanSeoSlug(text, { language })\` to strip accents, dates, and stop words.
+- Use \`ExtendedSchemaGraphBuilder\` to output valid JSON-LD graphs (\`SoftwareApplication\`, \`LocalBusiness\`, \`HowTo\`, \`FAQPage\`, \`BreadcrumbList\`, \`Organization\`).
+`.trim();
+
+/**
+ * Returns the complete LLM guidance prompt for AI agents and developer copilots.
+ */
+export function getSeoAgentPrompt(customContext?: { brandName?: string; domain?: string }): string {
+  if (!customContext) return PSEO_AGENT_SYSTEM_PROMPT;
+
+  return `
+${PSEO_AGENT_SYSTEM_PROMPT}
+
+### 🏢 Current Project Context:
+- Brand Name: ${customContext.brandName || "Our Platform"}
+- Domain: ${customContext.domain || "https://example.com"}
+`.trim();
+}