@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/live-ai-citation-tester.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 🎯 Live AI Citation Tester & Share of Voice Engine
+ *
+ * Method: Schulte et al. 2026, arXiv:2604.07585.
+ *
+ * Queries real AI answer engines (Perplexity Sonar, OpenAI, Anthropic, Gemini, SerpBase)
+ * or deterministic simulation to verify:
+ * 1. Brand Mention Rate (% of runs where the brand name is referenced in text)
+ * 2. Domain Citation Rate (% of runs where the domain is cited as an active source)
+ * 3. Wilson 95% Score Confidence Interval (statistical stability across multi-run sampling)
+ * 4. Competitor Share of Voice (which competitor domains are cited instead)
+ * 5. Qualitative Verdict: "strong" | "cited" | "mentioned_only" | "invisible"
+ */
+export interface CitationQueryConfig {
+    brand: string;
+    domain: string;
+    topic?: string;
+    queries?: string[];
+    provider?: "perplexity" | "openai" | "anthropic" | "gemini" | "serpbase" | "mock";
+    apiKey?: string;
+    runs?: number;
+    language?: "fr" | "en";
+}
+export interface CitationCheckEntry {
+    query: string;
+    provider: string;
+    model: string;
+    runs: number;
+    mentionRuns: number;
+    citationRuns: number;
+    brandMentioned: boolean;
+    domainCited: boolean;
+    citedSources: string[];
+    snippet: string;
+    competitorsFound: string[];
+    error?: string;
+}
+export type CitationVerdict = "strong" | "cited" | "mentioned_only" | "invisible";
+export interface LiveCitationReport {
+    checked: boolean;
+    brand: string;
+    domain: string;
+    provider: string;
+    totalQueries: number;
+    runsPerQuery: number;
+    totalAnswers: number;
+    brandMentionRate: number;
+    domainCitationRate: number;
+    brandMentionRateCi: [number, number];
+    domainCitationRateCi: [number, number];
+    stable: boolean;
+    verdict: CitationVerdict;
+    topCompetitorsCited: {
+        domain: string;
+        citationCount: number;
+        shareOfVoice: number;
+    }[];
+    entries: CitationCheckEntry[];
+    recommendations: string[];
+    skippedReason?: string;
+}
+export declare class LiveAiCitationTester {
+    private static readonly CI_Z;
+    private static readonly STRONG_THRESHOLD;
+    /**
+     * Normalizes a domain or URL to a clean lowercase hostname without www.
+     */
+    static normalizeDomain(value: string): string;
+    /**
+     * Extracts unique normalized domains from URLs in raw text.
+     */
+    static extractDomainsFromText(text: string): string[];
+    /**
+     * Computes the 95% Wilson score confidence interval for a binomial proportion.
+     * Preferred over normal approximation for small sample sizes in AI citation checks.
+     * (Schulte et al. 2026, arXiv:2604.07585)
+     */
+    static computeWilsonInterval(successes: number, n: number, z?: number): [number, number];
+    /**
+     * Determines the qualitative verdict based on citation and mention rates.
+     */
+    static determineVerdict(domainCitationRate: number, brandMentionRate: number): CitationVerdict;
+    /**
+     * Generates benchmark query prompts tailored for programmatic SEO & topic clusters.
+     */
+    static generateDefaultQueries(topicOrBrand: string, lang?: "fr" | "en"): string[];
+    /**
+     * Executes a citation check across queries with multi-run sampling.
+     */
+    static runCitationCheck(config: CitationQueryConfig): Promise<LiveCitationReport>;
+    /**
+     * Internal query router for LLM providers.
+     */
+    private static queryProvider;
+}

package/dist/live-co-browsing.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 🎥 Live Co-Browsing — plan de contrôle
+ *
+ * Le Session Replay montre le passé ; le co-browsing montre le présent et
+ * permet à un agent d'aider un visiteur bloqué. Ce module ne transporte pas la
+ * vidéo (WebRTC/WebSocket reste côté Worker) : il porte la **partie qui décide
+ * qui peut voir et agir**, et qui est la seule à devoir être fiable.
+ *
+ * Règles de sécurité :
+ * - un agent **ne peut pas** s'auto-approuver : seul un participant
+ *   `visitor` peut accorder le contrôle ;
+ * - un seul contrôle actif par session (pas de deux agents sur la même
+ *   session) ;
+ * - toute autorisation **expire** (`maxControlSeconds`), et `assertControl()`
+ *   vérifie l'expiration à chaque action ;
+ * - une session terminée n'accepte plus de messages ;
+ * - les champs sensibles (mot de passe, carte bancaire) ne sont jamais
+ *   transmis : `redactCoBrowsingPayload()` les remplace avant l'envoi.
+ *
+ * Horloge injectable, aucune I/O : le plan de contrôle est testable sans
+ * navigateur ni réseau.
+ */
+export type CoBrowsingRole = "agent" | "visitor" | "system";
+export interface CoBrowsingParticipant {
+    id: string;
+    role: CoBrowsingRole;
+    joinedAt: string;
+    lastSeenAt: string;
+    online: boolean;
+}
+export type SignalingMessageType = "presence" | "cursor" | "control_request" | "control_granted" | "control_denied" | "control_revoked" | "end";
+export interface SignalingMessage {
+    sequence: number;
+    id: string;
+    type: SignalingMessageType;
+    sessionId: string;
+    from: string;
+    at: string;
+    payload: Record<string, unknown>;
+}
+export interface ControlGrant {
+    requestId: string;
+    agentId: string;
+    visitorId: string;
+    scope: "view" | "control";
+    grantedAt: string;
+    expiresAt: string;
+}
+export type ControlRequestResult = {
+    ok: true;
+    requestId: string;
+    expiresAt: string;
+} | {
+    ok: false;
+    reason: "session_ended" | "not_a_participant" | "control_already_active" | "invalid_agent";
+};
+export type ControlDecisionResult = {
+    ok: true;
+    grant: ControlGrant;
+} | {
+    ok: false;
+    reason: "unknown_request" | "not_a_visitor" | "not_your_request" | "session_ended" | "denied";
+};
+export declare class CoBrowsingError extends Error {
+    constructor(message: string);
+}
+export interface CoBrowsingSessionOptions {
+    sessionId: string;
+    now?: () => Date;
+    /** Durée maximale d'un contrôle accordé (15 min par défaut). */
+    maxControlSeconds?: number;
+    /** Délai après lequel un participant silencieux est marqué hors ligne. */
+    presenceTtlSeconds?: number;
+}
+/**
+ * Remplace les valeurs sensibles par `[redacted]` avant transmission au
+ * navigateur de l'agent. Récursif, avec protection contre les cycles.
+ */
+export declare function redactCoBrowsingPayload(payload: Record<string, unknown>, seen?: WeakSet<object>): Record<string, unknown>;
+export declare class CoBrowsingSession {
+    private readonly sessionId;
+    private readonly now;
+    private readonly maxControlSeconds;
+    private readonly presenceTtlSeconds;
+    private readonly participants;
+    private readonly pending;
+    private readonly messages;
+    private sequence;
+    private activeGrant;
+    private requestCounter;
+    private ended;
+    constructor(options: CoBrowsingSessionOptions);
+    get id(): string;
+    join(input: {
+        participantId: string;
+        role: CoBrowsingRole;
+    }): CoBrowsingParticipant;
+    heartbeat(participantId: string): CoBrowsingParticipant;
+    /** Marque hors ligne les participants silencieux depuis plus de TTL. */
+    prunePresence(): string[];
+    cursor(participantId: string, position: {
+        x: number;
+        y: number;
+        selector?: string;
+    }): SignalingMessage;
+    /** Un agent demande le contrôle ; la demande expire avec le contrôle. */
+    requestControl(input: {
+        agentId: string;
+        scope?: "view" | "control";
+        visitorId: string;
+    }): ControlRequestResult;
+    /** Seul le visiteur ciblé peut approuver ou refuser. */
+    decideControl(input: {
+        requestId: string;
+        byVisitorId: string;
+        approved: boolean;
+    }): ControlDecisionResult;
+    /** Vérifie qu'un agent peut agir maintenant (contrôle actif et non expiré). */
+    assertControl(agentId: string, required?: "view" | "control"): ControlGrant;
+    revokeControl(reason?: "visitor" | "agent" | "timeout" | "session_end"): ControlGrant | null;
+    /** Message applicatif (déjà redacté par l'appelant). */
+    send(participantId: string, type: Extract<SignalingMessageType, "presence" | "cursor">, payload: Record<string, unknown>): SignalingMessage;
+    end(byParticipantId: string): SignalingMessage[];
+    isEnded(): boolean;
+    messagesSince(sequence: number): SignalingMessage[];
+    snapshot(): {
+        sessionId: string;
+        ended: boolean;
+        participants: CoBrowsingParticipant[];
+        activeGrant: ControlGrant | null;
+        messageCount: number;
+    };
+    private requireParticipant;
+    private push;
+}

package/dist/live-metrics-advanced.d.ts

@@ -0,0 +1,60 @@
+export interface LatencySample {
+    timestamp: number;
+    ms: number;
+}
+export declare function percentile(samples: LatencySample[] | number[], p: number): number | null;
+export interface LatencyStats {
+    count: number;
+    min: number | null;
+    max: number | null;
+    avg: number | null;
+    p50: number | null;
+    p95: number | null;
+    p99: number | null;
+}
+export declare function latencyStats(samples: LatencySample[] | number[]): LatencyStats;
+export interface LiveEvent {
+    id: string;
+    type: string;
+    value?: number;
+    timestamp: number;
+    meta?: Record<string, unknown>;
+}
+export interface LiveEventBufferOptions {
+    capacity?: number;
+}
+export declare class LiveEventBuffer {
+    private events;
+    private capacity;
+    constructor(options?: LiveEventBufferOptions);
+    push(event: LiveEvent): void;
+    snapshot(): LiveEvent[];
+    size(): number;
+    clear(): void;
+    latest(n?: number): LiveEvent[];
+    byType(type: string): LiveEvent[];
+}
+export interface VisitorSession {
+    visitorId: string;
+    lastSeen: number;
+}
+export declare function countConcurrentVisitors(sessions: VisitorSession[], now: number, windowMs: number): number;
+export declare function throughput(events: LiveEvent[] | {
+    timestamp: number;
+}[], windowMs: number): number;
+export interface TimeWindowBucket {
+    windowStart: number;
+    windowEnd: number;
+    count: number;
+    sum: number;
+    avg: number | null;
+    min: number | null;
+    max: number | null;
+}
+export interface TimeWindowAggregationOptions {
+    windowMs: number;
+    now?: number;
+    valueFn?: (event: LiveEvent) => number;
+}
+export declare function aggregateByTimeWindow(events: LiveEvent[], options: TimeWindowAggregationOptions): TimeWindowBucket[];
+export declare function liveMetricsAdvancedVersion(): string;

package/dist/llm-content-cleaner.d.ts

@@ -1,8 +1,12 @@
 /**
- * 🧹 Boilerplate Stripper & Clean Markdown Extractor for LLMs (Inspiration: openserp/extract)
+ * 🧹 Boilerplate Stripper & Clean Markdown Extractor for LLMs
  *
  * 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).
+ *
+ * Also exposes `verifyClaimsAndCitations` — a deterministic "content verify" that audits
+ * how many factual/statistical claims in an article are backed by an inline citation,
+ * so content stays credible for AI search engines that weight cited sources.
  */
 export declare class LlmContentCleaner {
     /**
@@ -13,4 +17,27 @@ export declare class LlmContentCleaner {
      * Cleans raw HTML and returns pure readable markdown content.
      */
     static htmlToCleanMarkdown(rawHtml: string): string;
+    /**
+     * Content verify: audits statistical/factual claims and whether each is
+     * backed by an inline citation in the same sentence.
+     *
+     * A "claim" is any sentence containing a numeric statement (percentage,
+     * quantity, currency, or year-range). A sentence "has a citation" when it
+     * contains either a markdown link `[...](url)` or a bracket reference
+     * `[n]`. Heuristic and deterministic — it does not judge truthfulness.
+     */
+    static verifyClaimsAndCitations(markdown: string): ClaimsCitationReport;
+}
+export interface ClaimOccurrence {
+    sentence: string;
+    claim: string;
+    cited: boolean;
+}
+export interface ClaimsCitationReport {
+    claimCount: number;
+    citedClaimCount: number;
+    uncitedClaimCount: number;
+    /** 0-100: share of claims backed by a citation (100 when no claims). */
+    citationScore: number;
+    claims: ClaimOccurrence[];
 }

package/dist/llms-txt-generator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 🤖 Standardized LLMS.TXT & LLMS-FULL.TXT Generator
+ * Follows the /llms.txt standard for AI-readable project files.
+ *
+ * Exposes a clean, structured, and parseable markdown manifest of the site
+ * at https://domain.com/llms.txt and https://domain.com/llms-full.txt
+ * for consumption by AI Crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended).
+ */
+export interface LlmsTxtConfig {
+    domain: string;
+    brandName: string;
+    description: string;
+    uniqueValueProposition: string;
+    primaryIndustry: string;
+    truthAnchors: {
+        whatWeAre: string[];
+        whatWeAreNot: string[];
+        keyBenchmarks: string[];
+    };
+    canonicalSections: Array<{
+        title: string;
+        description: string;
+        url: string;
+    }>;
+    programmaticMatrices?: Array<{
+        matrixName: string;
+        routePattern: string;
+        description: string;
+        totalActivePages: number;
+        sampleUrls: string[];
+    }>;
+}
+export interface GeneratedLlmsManifest {
+    llmsTxt: string;
+    llmsFullTxt: string;
+}
+export declare class LlmsTxtGenerator {
+    /**
+     * Generates lightweight /llms.txt and comprehensive /llms-full.txt
+     */
+    static generate(config: LlmsTxtConfig): GeneratedLlmsManifest;
+}

package/dist/local-geogrid-simulator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Local GeoGrid Simulator
+ * Génère une grille matricielle de coordonnées GPS (3x3 ou 5x5) autour d'un établissement local,
+ * et calcule la distribution des positions Google Maps (Pack Local 3-Pack), le score AGR
+ * (Average Grid Rank) et le score ATR (Average Total Rank).
+ */
+export interface LocalGeoGridPoint {
+    row: number;
+    col: number;
+    lat: number;
+    lng: number;
+    distanceKm: number;
+    rank: number;
+    isInThreePack: boolean;
+}
+type GeoGridPoint = LocalGeoGridPoint;
+export interface GeoGridSimulationInput {
+    centerLat: number;
+    centerLng: number;
+    gridSize: 3 | 5;
+    radiusKm: number;
+    keyword: string;
+    businessName: string;
+    simulatedBaselineRank?: number;
+}
+export interface GeoGridSimulationResult {
+    businessName: string;
+    keyword: string;
+    centerLat: number;
+    centerLng: number;
+    gridSize: number;
+    radiusKm: number;
+    totalPoints: number;
+    points: GeoGridPoint[];
+    metrics: {
+        averageGridRank: number;
+        threePackSharePercentage: number;
+        topRankCount: number;
+        unrankedCount: number;
+    };
+}
+export declare class LocalGeoGridSimulator {
+    /**
+     * Calcule la grille de points et simule ou projette les positions locales
+     */
+    static simulateGrid(input: GeoGridSimulationInput): GeoGridSimulationResult;
+}
+export {};

package/dist/local-seo-importer.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 🦁 @lynxseo/engine - Local SEO Importer & Intelligence Engine
+ *
+ * High-performance, zero-API cost offline parser and intelligence suite
+ * for local SEO exports.
+ *
+ * Features:
+ * - Google Business Profile Insights CSV parser
+ * - Geo-Grid Scan CSV parser (Local Falcon, Local Viking, GeoRanker)
+ * - Reviews CSV/JSON parser with PII redaction (GDPR), velocity calculation, and keyword tokenization
+ * - Citations & NAP directory audit parser
+ * - Google Business Profile Anti-Suspension Risk Evaluator (Claim Ledger doctrine)
+ */
+export interface GbpInsightsMetric {
+    periodStart: string;
+    periodEnd: string;
+    totalImpressions: number;
+    mapsImpressions: number;
+    searchImpressions: number;
+    websiteClicks: number;
+    phoneCalls: number;
+    directionRequests: number;
+    bookings: number;
+    dailyBreakdown?: Array<{
+        date: string;
+        impressions: number;
+        actions: number;
+    }>;
+}
+export interface GeoGridImportPoint {
+    lat: number;
+    lng: number;
+    rank: number | null;
+    keyword: string;
+}
+export interface GeoGridImportSummary {
+    keyword: string;
+    totalPoints: number;
+    rankedPoints: number;
+    averageRank: number;
+    top3Count: number;
+    top3SharePercentage: number;
+    top10Count: number;
+    top10SharePercentage: number;
+    points: GeoGridImportPoint[];
+}
+export interface LocalReviewItem {
+    id?: string;
+    authorMasked: string;
+    rating: number;
+    date: string;
+    text: string;
+    hasOwnerResponse: boolean;
+}
+export interface ReviewsIntelligenceSummary {
+    totalReviews: number;
+    averageRating: number;
+    ratingDistribution: {
+        5: number;
+        4: number;
+        3: number;
+        2: number;
+        1: number;
+    };
+    monthlyVelocity: number;
+    recent30DaysCount: number;
+    responseRatePercentage: number;
+    topPositiveKeywords: Array<{
+        word: string;
+        count: number;
+    }>;
+    topCriticalKeywords: Array<{
+        word: string;
+        count: number;
+    }>;
+    piiRedactedCount: number;
+    healthGrade: "A+" | "A" | "B" | "C" | "D";
+}
+export interface CitationDirectoryItem {
+    directory: string;
+    category: "tier1" | "tier2" | "niche";
+    url?: string;
+    status: "verified" | "mismatch" | "missing" | "unverified";
+    issues: string[];
+}
+export interface GbpRiskIssue {
+    id: string;
+    title: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+    policySource: string;
+    description: string;
+    riskOutcome: string;
+    recommendedAction: string;
+    rollbackPlan: string;
+}
+export interface GbpRiskAssessment {
+    overallRiskLevel: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "CLEAN";
+    riskScore: number;
+    issues: GbpRiskIssue[];
+    passedChecks: string[];
+}
+export declare class LocalSeoImporter {
+    /**
+     * Parse Google Business Profile Insights Performance CSV
+     */
+    static parseGbpInsightsCsv(csvContent: string): GbpInsightsMetric;
+    /**
+     * Parse GeoGrid CSV exports (Local Falcon, Local Viking, GeoRanker, etc.)
+     */
+    static parseGeoGridCsv(csvContent: string): GeoGridImportSummary;
+    /**
+     * Parse Reviews from CSV or JSON with PII sanitization and NLP keyword extraction
+     */
+    static parseReviews(content: string): ReviewsIntelligenceSummary;
+    /**
+     * Same computation as `parseReviews` but from a typed array, so the caller
+     * keeps the parsed records (ids, authors, dates) alongside the summary.
+     */
+    static analyzeReviewsArray(rawItems: Array<{
+        author?: string;
+        rating: number;
+        date?: string;
+        text?: string;
+        response?: boolean;
+    }>): ReviewsIntelligenceSummary;
+    /**
+     * Evaluate Google Business Profile Anti-Suspension Risk based on Claim Ledger doctrine
+     */
+    static evaluateGbpRisk(params: {
+        registeredBusinessName: string;
+        gbpProfileName: string;
+        hasPhysicalSignage: boolean;
+        isCoworkingOrVirtualOffice: boolean;
+        isServiceAreaOnly: boolean;
+        addressHiddenIfServiceArea: boolean;
+        categoriesCount: number;
+        hasCustomReviewIncentive: boolean;
+    }): GbpRiskAssessment;
+    /**
+     * Parse Citations directory CSV
+     */
+    static parseCitationsCsv(csvContent: string): CitationDirectoryItem[];
+}

package/dist/local-seo-review-intelligence.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 📍 Local SEO Review Intelligence & Response Generator
+ * Targets direct Google Business Profile policy compliance.
+ *
+ * Provides:
+ * 1. NLP Sentiment analysis & keyword extraction from GBP / Trustpilot customer reviews.
+ * 2. Velocity analysis (review velocity, response rate, negative surge detection).
+ * 3. Safe, Google-compliant AI review response generator (avoids keyword stuffing, protects against policy strikes).
+ */
+export interface CustomerReview {
+    id: string;
+    author: string;
+    rating: number;
+    text: string;
+    date: string;
+    response?: string;
+    likes?: number;
+}
+export interface ReviewSentimentResult {
+    overallSentiment: "positive" | "neutral" | "negative";
+    score: number;
+    sentimentBreakdown: {
+        positive: number;
+        neutral: number;
+        negative: number;
+    };
+    dominantKeywords: Array<{
+        keyword: string;
+        occurrences: number;
+        sentiment: "positive" | "negative" | "neutral";
+    }>;
+    authoritySignals: string[];
+    velocity: {
+        totalReviews: number;
+        averageRating: number;
+        responseRatePercent: number;
+        monthlyVelocity: number;
+        isVelocityHealthy: boolean;
+        surgeDetected: boolean;
+    };
+}
+export interface GeneratedReviewResponse {
+    reviewId: string;
+    recommendedResponse: string;
+    tone: "empathic_resolution" | "grateful_advocacy" | "neutral_clarification";
+    policyCheckPassed: boolean;
+    complianceNotes: string[];
+}
+export declare class LocalSeoReviewIntelligence {
+    /**
+     * Analyzes an array of reviews to compute NLP sentiment, keywords, and velocity metrics.
+     */
+    static analyzeReviews(reviews: CustomerReview[]): ReviewSentimentResult;
+    /**
+     * Generates a safe, professional, Google Business Profile compliant response to a review.
+     */
+    static generateResponse(review: CustomerReview, businessContext: {
+        businessName: string;
+        city?: string;
+        service?: string;
+    }): GeneratedReviewResponse;
+}

package/dist/longform-article-planner.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 📝 LongformArticlePlanner — SEO & AEO Long-Form Content Outline Architect
+ *
+ * Method:
+ * - Princeton KDD 2024 Answer-First structuring for LLMs
+ */
+export interface LongformSectionPlan {
+    heading: string;
+    level: "h2" | "h3";
+    intent: "answer_first" | "deep_dive" | "comparison" | "faq" | "actionable_takeaways";
+    recommendedWordCount: number;
+    keyPointsToCover: string[];
+    answerFirstPrompt: string;
+}
+export interface ArticleOutlinePlan {
+    topic: string;
+    targetKeyword: string;
+    searchIntent: "informational" | "commercial_bofu" | "transactional" | "navigational";
+    targetAudience: string;
+    recommendedTotalWords: number;
+    estimatedReadingTimeMinutes: number;
+    titleSuggestions: string[];
+    metaDescription: string;
+    sections: LongformSectionPlan[];
+    schemaRecommendations: string[];
+    llmsSnippet: string;
+}
+export interface PlanArticleInput {
+    topic: string;
+    targetKeyword?: string;
+    intent?: "informational" | "commercial_bofu" | "transactional";
+    audience?: string;
+    language?: "fr" | "en";
+}
+export declare class LongformArticlePlanner {
+    static plan(input: PlanArticleInput): ArticleOutlinePlan;
+}

package/dist/lql/compiler.d.ts

@@ -0,0 +1,2 @@
+import type { CompiledSql, LqlDialect, LqlQuery } from "./types";
+export declare function compileLqlToSql(query: LqlQuery, dialect?: LqlDialect): CompiledSql;

package/dist/lql/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./compiler";
+export * from "./validator";
+export * from "./streaming";

package/dist/lql/streaming.d.ts

@@ -0,0 +1,8 @@
+import type { LqlQuery } from "./types";
+export declare function streamLqlResults(_query: LqlQuery, options: {
+    batchSize: number;
+    cursor: number;
+}): AsyncIterable<{
+    rows: unknown[];
+    nextCursor: number | null;
+}>;