@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/geo-fixer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 🛠️ GEO Auto-Fix Generator
+ *
+ * Generates ready-to-deploy corrective artifacts based on a GEO audit:
+ * - robots.txt patch allowing citation search bots
+ * - Standardized /llms.txt and /llms-full.txt
+ * - JSON-LD Schema.org graphs (WebSite, Organization, FAQPage)
+ * - HTML meta tags
+ * - AI discovery endpoints (/.well-known/ai.txt, /ai/summary.json)
+ */
+import type { GeoScoreResult } from "./geo-score-calculator";
+export interface GeoFixOptions {
+    domain: string;
+    siteName: string;
+    description: string;
+    primaryIndustry?: string;
+    sitemapUrl?: string;
+    faqs?: Array<{
+        question: string;
+        answer: string;
+    }>;
+    socialUrls?: string[];
+}
+export interface GeoFixArtifacts {
+    robotsTxt: string;
+    llmsTxt: string;
+    llmsFullTxt: string;
+    schemaJsonLd: string;
+    metaTagsHtml: string;
+    aiTxt: string;
+    aiSummaryJson: string;
+    aiFaqJson: string;
+}
+export declare class GeoFixer {
+    static generateFixes(scoreResult: GeoScoreResult, options: GeoFixOptions): GeoFixArtifacts;
+}

package/dist/geo-grid-rank-tracker.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 📍 Geo-Grid Rank Tracking Engine
+ *
+ * Scans and models Google Maps Local 3-Pack rankings across a geographic matrix
+ * of coordinate points (3x3 up to 17x17 / 289 nodes) around any business location.
+ * Implements DataForSEO cost estimation guardrails ($0.0006/SERP) and visual rank status.
+ */
+export interface GeoGridPoint {
+    index: number;
+    row: number;
+    col: number;
+    lat: number;
+    lng: number;
+    distanceKm: number;
+    rankPosition: number;
+    inLocalPack: boolean;
+    color: "green" | "yellow" | "orange" | "red";
+    label: string;
+}
+export interface GeoGridScanOptions {
+    keyword: string;
+    businessName: string;
+    centerLat: number;
+    centerLng: number;
+    gridRadiusKm?: number;
+    gridSize?: number;
+}
+export interface GeoGridCalculationResult {
+    keyword: string;
+    businessName: string;
+    centerLat: number;
+    centerLng: number;
+    gridRadiusKm: number;
+    gridSize: number;
+    totalPoints: number;
+    averageGridRank: number;
+    shareOfLocalVoice: number;
+    top3Percentage: number;
+    top10Percentage: number;
+    gridNodes: GeoGridPoint[];
+    weakestDirection: string;
+    strongestDirection: string;
+    estimatedDataForSeoCostUsd: number;
+    saasSavingsEstimateUsd: number;
+    scanFingerprint: string;
+}
+export declare class GeoGridRankTracker {
+    static readonly DATAFORSEO_MAPS_COST_PER_NODE_USD = 0.0006;
+    static readonly TRADITIONAL_SAAS_SCAN_COST_USD = 49;
+    /**
+     * Calculates a multi-resolution GPS coordinate grid and models local pack positions.
+     */
+    static calculateGeoGrid(optionsOrKeyword: GeoGridScanOptions | string, businessName?: string, centerLat?: number, centerLng?: number, gridRadiusKm?: number, gridSize?: number): GeoGridCalculationResult;
+}

package/dist/geo-hallucination-bait.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Hallucination Bait & Ambiguity Detector for GEO
+ * Analyzes page content to detect linguistic and statistical patterns that trigger LLM hallucinations:
+ * - Unsourced statistics (% or multiplier lacking clear origin)
+ * - Absolute claims with certainty verbs ("studies show", "des études prouvent")
+ * - Speculative future projections without verifiable methodology
+ * - Vague comparative ranges ("between 10 and 100x", "jusqu'à...")
+ * - Circular self-citations ("selon nos données internes")
+ *
+ * Grounded in: UC Berkeley EMNLP 2024 & Anthropic AI Safety Research 2025.
+ */
+export interface HallucinationBaitItem {
+    type: "unsourced_stat" | "absolute_claim" | "speculative_future" | "vague_range" | "circular_citation";
+    snippet: string;
+    explanation: string;
+    suggestion: string;
+}
+export interface HallucinationBaitResult {
+    checked: boolean;
+    totalBaits: number;
+    severity: "clean" | "low" | "medium" | "high";
+    score: number;
+    items: HallucinationBaitItem[];
+    countsByType: Record<"unsourced_stat" | "absolute_claim" | "speculative_future" | "vague_range" | "circular_citation", number>;
+    summary: string;
+    recommendations: string[];
+}
+export declare class GeoHallucinationBaitDetector {
+    static analyze(textOrHtml: string): HallucinationBaitResult;
+}

package/dist/geo-instruction-auditor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Instruction Following & AI Agent Readiness Auditor
+ * Evaluates how easily autonomous AI agents (Computer Use Claude, WebMCP, ChatGPT Operator)
+ * can navigate, comprehend, and trigger actions on the webpage:
+ * - Action Clarity: buttons and interactive links with descriptive labels vs icon-only
+ * - Form Machine-Readability: inputs with associated labels, semantic types, and placeholders
+ * - Workflow Linearity: clear descriptive anchors and stateful paths
+ * - Agent Error Recovery: aria-live regions and role="alert" accessibility hooks
+ * - Agent Action Readiness Score (0 to 100)
+ */
+export interface InstructionReadinessResult {
+    checked: boolean;
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    actionClarity: {
+        totalInteractive: number;
+        descriptiveCount: number;
+        unlabeledCount: number;
+        ratio: number;
+    };
+    formReadability: {
+        totalInputs: number;
+        labeledInputs: number;
+        typedInputs: number;
+        score: number;
+    };
+    accessibilitySignals: {
+        hasAriaLive: boolean;
+        hasAlertRoles: boolean;
+        hasSkipLink: boolean;
+    };
+    summary: string;
+    recommendations: string[];
+}
+export declare class GeoInstructionAuditor {
+    static audit(html: string): InstructionReadinessResult;
+}

package/dist/geo-js-auditor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * JavaScript Rendering Dependency Auditor for AI Crawlers
+ * Evaluates whether raw server-rendered HTML contains sufficient content for AI bots
+ * without requiring client-side JavaScript execution.
+ *
+ * According to OtterlyAI Citation Report 2026:
+ * JavaScript rendering dependency is Barrier #3 preventing AI search engines
+ * (GPTBot, ClaudeBot, PerplexityBot) from indexing content.
+ */
+export interface JsRenderingResult {
+    checked: boolean;
+    rawWordCount: number;
+    rawHeadingCount: number;
+    hasEmptyRoot: boolean;
+    emptyRootContainer?: string;
+    hasNoscriptContent: boolean;
+    frameworkDetected?: "next.js" | "nuxt" | "react" | "angular" | "vue" | "gatsby" | "astro" | "svelte" | "unknown";
+    jsDependent: boolean;
+    severity: "none" | "low" | "medium" | "critical";
+    summary: string;
+    recommendations: string[];
+}
+export declare class GeoJsRenderingAuditor {
+    static audit(rawHtml: string): JsRenderingResult;
+}

package/dist/geo-multi-turn-persistence.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 🔄 GeoMultiTurnPersistence & Brand Sentiment Engine
+ *
+ * Evaluates:
+ * 1. Multi-turn brand conversational persistence across progressive LLM turns:
+ *    - Does the brand survive follow-up questions or get replaced by competitors?
+ *    - Retention score (0-100) and turn-by-turn memory decay.
+ * 2. Brand sentiment and perception polarity in generative responses:
+ *    - Positive semantic polarity vs negative critiques (e.g. expensive, complex, limited).
+ */
+export interface MultiTurnTurnResult {
+    turnIndex: number;
+    question: string;
+    responseSnippet: string;
+    brandMentioned: boolean;
+    domainCited: boolean;
+    competitorsMentioned: string[];
+}
+export interface MultiTurnPersistenceReport {
+    brand: string;
+    domain: string;
+    totalTurns: number;
+    persistedTurnsCount: number;
+    persistenceScore: number;
+    droppedAtTurn: number | null;
+    turns: MultiTurnTurnResult[];
+    verdict: "permanent_retention" | "high_stickiness" | "early_drop" | "never_cited";
+    recommendations: string[];
+}
+export interface BrandSentimentReport {
+    brand: string;
+    sentimentPolarity: number;
+    sentimentGrade: "très_favorable" | "favorable" | "neutre" | "mitigé" | "défavorable";
+    positiveAttributes: string[];
+    criticismsFound: string[];
+    summary: string;
+}
+export declare class GeoMultiTurnPersistenceTester {
+    private static readonly POSITIVE_LEXICON;
+    private static readonly NEGATIVE_LEXICON;
+    private static readonly DEFAULT_TURNS_FR;
+    /**
+     * Simulates a multi-turn conversation and analyzes brand persistence.
+     */
+    static simulatePersistence(params: {
+        brand: string;
+        domain: string;
+        topic?: string;
+        competitors?: string[];
+    }): Promise<MultiTurnPersistenceReport>;
+    /**
+     * Analyzes text or LLM answers for brand sentiment polarity and attributes.
+     */
+    static analyzeSentiment(brand: string, sampleText: string): BrandSentimentReport;
+}

package/dist/geo-multimodal-auditor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Multimodal AI Readiness Auditor
+ * Evaluates visual and audio scaffolding required by multimodal AI engines (GPT-4o, Gemini, Claude 3.5 Sonnet)
+ *
+ * Checks:
+ * - Informative Alt Text on images (filters out filenames and placeholder noise)
+ * - Captions coverage (<figcaption>)
+ * - Video elements and video schema (VideoObject, Clip)
+ * - Closed captions & subtitle tracks (<track kind="captions">)
+ * - Audio elements and audio schema (AudioObject, PodcastEpisode)
+ * - Full text transcript availability
+ * - Multimodal Readiness Score (0-100)
+ */
+export interface MultimodalResult {
+    totalImages: number;
+    imagesWithInformativeAlt: number;
+    altCoverageRatio: number;
+    captionCount: number;
+    hasVideo: boolean;
+    videoCount: number;
+    hasVideoSchema: boolean;
+    hasVideoCaptions: boolean;
+    hasAudio: boolean;
+    hasAudioSchema: boolean;
+    hasTranscript: boolean;
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    summary: string;
+    recommendations: string[];
+}
+export declare class GeoMultimodalAuditor {
+    static audit(html: string, schemas?: any[]): MultimodalResult;
+}

package/dist/geo-negative-signals.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 🚫 GeoNegativeSignalsAuditor — Negative AI Citability Signals Audit
+ *
+ * Implements deterministic detection of anti-patterns identified in
+ * UC Berkeley EMNLP 2024, Princeton KDD, and Google Search Quality Evaluator Guidelines:
+ *
+ * 1. Excessive CTA Density (> 5 aggressive commercial triggers or > 1% word count ratio)
+ * 2. Aggressive Interstitial & Popup Signals in DOM (.modal, .overlay, data-popup)
+ * 3. Thin Content Promising Depth (words < 300 while H1 promises "complet", "guide", "ultime")
+ * 4. Broken or Dead Anchors (href empty, '#', or 'javascript:void(0)')
+ * 5. Keyword Stuffing (single non-stopword density > 2.5% with count >= 5)
+ * 6. Missing Author Byline / E-E-A-T Signal (no Person schema, no rel=author)
+ * 7. Boilerplate Ratio Skew (nav/footer/header occupying > 40% of total visible DOM text)
+ * 8. Mixed Promise Signals (title/H1 claiming in-depth analysis on stub page)
+ */
+export interface NegativeSignalItem {
+    id: string;
+    name: string;
+    detected: boolean;
+    severity: "high" | "medium" | "low";
+    penaltyPoints: number;
+    evidence: string;
+    recommendation: string;
+}
+export interface NegativeSignalsReport {
+    checked: boolean;
+    totalSignalsDetected: number;
+    totalPenaltiesDeducted: number;
+    severity: "clean" | "low" | "medium" | "high";
+    signals: NegativeSignalItem[];
+    hasCtaExcess: boolean;
+    hasPopups: boolean;
+    isThinContent: boolean;
+    hasBrokenAnchors: boolean;
+    hasKeywordStuffing: boolean;
+    hasMissingAuthor: boolean;
+    hasBoilerplateSkew: boolean;
+    hasMixedSignals: boolean;
+    summary: string;
+}
+export interface NegativeAuditInput {
+    html: string;
+    wordCount?: number;
+    h1Text?: string;
+    hasPersonSchema?: boolean;
+}
+export declare class GeoNegativeSignalsAuditor {
+    static audit(input: NegativeAuditInput): NegativeSignalsReport;
+}

package/dist/geo-page-intent-mapper.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 🎯 GeoPageIntentMapper — AI Search Intent Mapping & Readiness Engine
+ *
+ * Analyzes webpage content to determine which AI search intents it serves:
+ * - Informational (tutorials, explanations, definitions)
+ * - Commercial Investigation (comparisons, reviews, alternatives, vs)
+ * - Transactional (pricing, sign up, buy, plans)
+ * - Navigational (login, portal, official documentation)
+ *
+ * Evaluates readiness (0-100) for each intent and identifies missing signals
+ * (Schema.org types, tables, answer-first structures) required by AI answer engines.
+ */
+export type AiSearchIntent = "informational" | "commercial" | "transactional" | "navigational";
+export interface IntentReadiness {
+    intent: AiSearchIntent;
+    score: number;
+    confidence: number;
+    matchedSignals: string[];
+    missingSignals: string[];
+    requiredSchemaTypes: string[];
+    presentSchemaTypes: string[];
+    sampleAiQueries: string[];
+}
+export interface PageIntentAuditResult {
+    url: string;
+    primaryIntent: AiSearchIntent;
+    secondaryIntent: AiSearchIntent | null;
+    overallIntentReadinessScore: number;
+    intents: Record<AiSearchIntent, IntentReadiness>;
+    recommendations: string[];
+}
+export interface PageIntentInput {
+    url: string;
+    html: string;
+    title?: string;
+    metaDescription?: string;
+    schemaTypes?: string[];
+}
+export declare class GeoPageIntentMapper {
+    private static readonly INTENT_DEFINITIONS;
+    /**
+     * Analyzes page content and computes intent readiness scores.
+     */
+    static mapIntents(input: PageIntentInput): PageIntentAuditResult;
+    private static evaluateIntent;
+}

package/dist/geo-perception-extractor.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AI Perception Extractor (Deterministic Machine Synthesis)
+ *
+ * Simulates and extracts what autonomous AI answer engines (ChatGPT Search, Perplexity,
+ * Claude, Gemini) deterministically perceive about a brand and webpage.
+ *
+ * Evaluates:
+ * - Brand Name & Entity Classification (Organization, Person, Product, LocalBusiness)
+ * - Schema Knowledge Graph footprint
+ * - Perceived Authority Level & Trust Grade (from 5-layer Trust Stack)
+ * - Citability Worthy Facts & Supported Claims
+ * - Missing Authority Signals that trigger AI hallucinations or entity conflation
+ * - AI-Readable Summary: Synthetic paragraph of brand identity viewed by LLMs
+ */
+export interface PerceptionSnapshot {
+    url: string;
+    brandName: string | null;
+    brandEntityType: string | null;
+    detectedServices: string[];
+    schemaTypesPresent: string[];
+    citabilityGrade: string;
+    trustScore: number;
+    trustMax: number;
+    trustGrade: string;
+    citationWorthyFacts: string[];
+    supportedClaims: string[];
+    unsupportedClaims: string[];
+    missingAuthoritySignals: string[];
+    aiReadableSummary: string;
+    disclaimer: string;
+}
+export interface PerceptionExtractorInput {
+    url: string;
+    html?: string;
+    brandName?: string;
+    pageTitle?: string;
+    schemaTypes?: string[];
+    citabilityScore?: number;
+    citabilityGrade?: string;
+    trustScore?: number;
+    trustGrade?: string;
+    statisticsCount?: number;
+    authoritativeLinksCount?: number;
+    hasAboutLink?: boolean;
+    hasContactInfo?: boolean;
+    hasKgPillars?: boolean;
+}
+export declare class GeoPerceptionExtractor {
+    static extract(input: PerceptionExtractorInput): PerceptionSnapshot;
+}

package/dist/geo-platform-auditor.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 🎯 GeoPlatformAuditor — Multi-Platform AI Citation Profile
+ *
+ * Implements per-platform citation readiness scores based on Superlines 2026,
+ * OtterlyAI, and Princeton KDD 2024 empirical research:
+ *
+ * 1. ChatGPT (GPT-4o / GPT-5):
+ *    - Favors: GPTBot access, /llms.txt, FAQ structured data, clear entity (Organization)
+ *
+ * 2. Perplexity (Sonar / Pro):
+ *    - Favors: PerplexityBot access, /llms.txt with deep links, inline citation density (>= 70),
+ *      content freshness (dateModified), external authoritative citations (>= 3)
+ *
+ * 3. Google AI Overviews & AI Search:
+ *    - Favors: Googlebot access, rich Schema.org (Product, Article, WebSite),
+ *      complete meta tags, SSR HTML (no heavy client JS), image alt quality, sameAs authority
+ */
+export interface PlatformScore {
+    platform: "chatgpt" | "perplexity" | "google_ai";
+    name: string;
+    score: number;
+    strengths: string[];
+    recommendations: string[];
+}
+export interface PlatformCitationReport {
+    checked: boolean;
+    overallAverageScore: number;
+    platforms: {
+        chatgpt: PlatformScore;
+        perplexity: PlatformScore;
+        google_ai: PlatformScore;
+    };
+    primaryBottleneckPlatform: "chatgpt" | "perplexity" | "google_ai" | "none";
+    prioritizedActions: string[];
+}
+export interface PlatformAuditorInput {
+    robots: {
+        allowedBots: string[];
+        blockedBots: string[];
+    };
+    llms: {
+        found: boolean;
+        hasSections?: boolean;
+        hasLinks?: boolean;
+    };
+    schema: {
+        found: boolean;
+        types: string[];
+        hasOrganizationOrWebsite?: boolean;
+        hasFaq?: boolean;
+        hasHowTo?: boolean;
+        hasArticle?: boolean;
+        hasProduct?: boolean;
+        hasSameAs?: boolean;
+    };
+    meta: {
+        hasTitle: boolean;
+        hasDescription: boolean;
+        hasCanonical: boolean;
+        hasOgTags: boolean;
+    };
+    content: {
+        hasH1: boolean;
+        wordCount: number;
+        externalLinksCount?: number;
+        hasDescriptiveImageAlts?: boolean;
+    };
+    citability: {
+        overallScore: number;
+    };
+    signals?: {
+        hasFreshness?: boolean;
+        hasRss?: boolean;
+    };
+    isClientJsDependent?: boolean;
+}
+export declare class GeoPlatformAuditor {
+    static audit(input: PlatformAuditorInput): PlatformCitationReport;
+    private static scoreChatGPT;
+    private static scorePerplexity;
+    private static scoreGoogleAi;
+}

package/dist/geo-prompt-injection-detector.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Prompt Injection & Adversarial RAG Poisoning Detector
+ * Identifies hidden text, invisible Unicode, prompt injections, and adversarial manipulations
+ * designed to hijack AI agents, manipulate RAG retrieval, or poison LLM citations.
+ * Based on research by UC Berkeley EMNLP 2024 on search manipulation via injected context.
+ */
+export interface GeoPromptInjectionFinding {
+    category: "css_hidden_text" | "invisible_unicode" | "llm_instruction_override" | "html_comment_injection" | "monochrome_camouflage" | "micro_font_injection" | "data_attribute_injection" | "aria_hidden_injection";
+    severity: "critical" | "high" | "medium";
+    description: string;
+    excerpt: string;
+    remediation: string;
+}
+export interface PromptInjectionResult {
+    checked: boolean;
+    isSafe: boolean;
+    safetyScore: number;
+    totalFindings: number;
+    findings: GeoPromptInjectionFinding[];
+    findingsByCategory: Record<string, number>;
+    summary: string;
+}
+export declare class GeoPromptInjectionDetector {
+    static analyze(html: string): PromptInjectionResult;
+}