@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/audit-log.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Append-only audit log for product adoption and security events.
+ *
+ * Every entry is immutable, timestamped and categorized. The log is pure:
+ * it transforms state without touching the network, the clock or storage.
+ * Callers persist the returned state wherever they like (KV, D1, Postgres,
+ * SQLite) and replay it on restart.
+ */
+export type AuditEventCategory = "auth" | "billing" | "data_export" | "data_erasure" | "feature_flag" | "organization" | "project" | "report" | "security" | "share" | "user";
+export type AuditEventSeverity = "info" | "warning" | "error" | "critical";
+export interface AuditEvent {
+    id: string;
+    category: AuditEventCategory;
+    severity: AuditEventSeverity;
+    actorId: string | null;
+    actorEmail: string | null;
+    organizationId: string | null;
+    projectId: string | null;
+    resourceType: string | null;
+    resourceId: string | null;
+    action: string;
+    details: Record<string, unknown>;
+    createdAt: string;
+}
+export interface AuditLogState {
+    entries: AuditEvent[];
+    updatedAt: string;
+}
+export interface AuditLogEntryInput {
+    category: AuditEventCategory;
+    severity?: AuditEventSeverity;
+    actorId?: string | null;
+    actorEmail?: string | null;
+    organizationId?: string | null;
+    projectId?: string | null;
+    resourceType?: string | null;
+    resourceId?: string | null;
+    action: string;
+    details?: Record<string, unknown>;
+}
+/** Creates an empty audit log state. */
+export declare function createAuditLogState(now?: Date): AuditLogState;
+/**
+ * Appends an event to the audit log. When the cap is reached, the oldest
+ * entries are evicted first (FIFO). Returns a new state; the input is never
+ * mutated.
+ */
+export declare function appendAuditEvent(state: AuditLogState | null, input: AuditLogEntryInput, now?: Date, options?: {
+    maxEntries?: number;
+}): AuditLogState;
+/**
+ * Returns entries matching the optional filters, newest first. When neither
+ * filter is provided, all entries are returned.
+ */
+export declare function queryAuditLog(state: AuditLogState, filters: {
+    category?: AuditEventCategory;
+    severity?: AuditEventSeverity;
+    actorId?: string | null;
+    organizationId?: string | null;
+    projectId?: string | null;
+    resourceType?: string | null;
+    resourceId?: string | null;
+    action?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+}): AuditEvent[];
+/**
+ * Returns the count of entries per category, useful for dashboards and
+ * adoption reports.
+ */
+export declare function countByCategory(state: AuditLogState): Record<string, number>;
+/**
+ * Returns the count of entries per severity, useful for security dashboards.
+ */
+export declare function countBySeverity(state: AuditLogState): Record<string, number>;

package/dist/audit-scoring-engine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Deterministic Audit Scoring & Impact/Effort Matrix Engine
+ */
+import { type AuditCategory, type RuleSeverity, type EffortLevel, type SearchCentralFinding } from "./rules/search-central-catalog";
+export declare const CATEGORY_WEIGHTS: Record<AuditCategory, number>;
+export declare const DEDUCT_AMOUNTS: Record<RuleSeverity, number>;
+export declare const SITE_LEVEL_RULE_IDS: Set<string>;
+export interface PrioritizedAction {
+    actionId: string;
+    id: string;
+    origin: "rule" | "semantic" | "dataforseo";
+    category: AuditCategory;
+    priority: "P1" | "P2" | "P3";
+    impact: number;
+    effort: EffortLevel;
+    quickWin: boolean;
+    severity: RuleSeverity;
+    title: string;
+    fix: string;
+    source: string;
+    count: number;
+    evidence: string;
+    heuristic: boolean;
+    urls: string[];
+    importance: number | null;
+    status: "to_do" | "in_progress" | "done" | "deferred" | "not_applicable";
+    needsReview?: number;
+}
+export interface AuditScoreResult {
+    overall: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    categories: Record<AuditCategory, number | null>;
+    categoryNames: Record<AuditCategory, string>;
+    weights: Record<AuditCategory, number>;
+    caps: string[];
+    partial: string[];
+    actions: PrioritizedAction[];
+}
+export declare function calculateReach(finding: SearchCentralFinding, totalPages: number): number;
+export declare function calculateAreaScore(category: AuditCategory, findings: SearchCentralFinding[], totalPages: number): number;
+export declare function prioritizeActions(findings: SearchCentralFinding[], totalPages: number, pageImportanceMap?: Record<string, number>): PrioritizedAction[];
+export declare const generatePrioritizedActions: typeof prioritizeActions;
+export declare function calculateAuditScores(findings: SearchCentralFinding[], totalPages: number, options?: {
+    pageImportanceMap?: Record<string, number>;
+    lighthouseMobileScore?: number;
+    semanticQualityScore?: number;
+    semanticAiScore?: number;
+}): AuditScoreResult;

package/dist/autonomous-audit-engine.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 🦁 Autonomous SEO Audit Engine
+ *
+ * Zero-configuration, end-to-end automated audit pipeline:
+ * 1. Native High-Performance Crawl (robots.txt, sitemaps, internal links, headers, meta tags)
+ * 2. Deterministic Google Search Central Checks (52+ official rules & heuristics)
+ * 3. PageSpeed Insights / CWV Lab & Field Metrics
+ * 4. Deterministic 6-Category Scoring & Grade Attribution (A to F)
+ * 5. Impact vs Effort Matrix & Prioritized Actions (P1 to P4, Quick Wins)
+ * 6. Automated Code & Configuration Fix Snippets (robots, canonical, schema, headers, llms.txt)
+ * 7. Executive Narrative Generator (Summary, 3 Strategic Horizons, Risks, Quick Wins)
+ * 8. All Executive Deliverables Compiled:
+ *    - Self-contained Vector HTML & PDF Report
+ *    - Full Excel Action Tracker (.xlsx) with Formulas
+ *    - Comprehensive Markdown Report
+ *    - Executive Markdown Digest
+ *    - Complete Audit JSON Dataset
+ */
+import { type CrawlResult } from "./crawler/native-crawler";
+import { type AuditScoreResult, type PrioritizedAction } from "./audit-scoring-engine";
+import { type PsiReport } from "./integrations/pagespeed-client";
+import { type DfsCollectResult } from "./integrations/dataforseo-audit-client";
+import { type AuditNarrative } from "./narrative-validator";
+import { type WhiteLabelConfig } from "./exporters/html-pdf-report";
+import type { SearchCentralFinding } from "./rules/search-central-catalog";
+import { type GeneratedSiteAssets } from "./autonomous-site-assets-generator";
+export interface AutonomousAuditInput {
+    /** Target website URL (e.g. "https://example.com" or "example.com") */
+    url: string;
+    /** Maximum pages to crawl (default 60) */
+    maxPages?: number;
+    /** Maximum crawl depth (default 5) */
+    maxDepth?: number;
+    /** Crawl time budget in seconds (default 600) */
+    timeBudget?: number;
+    /** Skip PageSpeed Insights performance testing */
+    noPsi?: boolean;
+    /** Maximum pages to test with PageSpeed Insights (default 3) */
+    psiPages?: number;
+    /** Enable DataForSEO live keyword rankings and backlinks */
+    full?: boolean;
+    /** DataForSEO location code (default 2840 US, 2250 FR, etc.) */
+    locationCode?: number;
+    /** Site language for crawler Accept-Language header, browser locale and DataForSEO (default "en") */
+    language?: string;
+    /** Report language: translates HTML, PDF, Excel, and Markdown at render time (en, fr, es, de, it, pt, nl, pl, ar, zh, ja, etc.) */
+    reportLang?: string;
+    /** Optional agency white-label branding */
+    whiteLabel?: WhiteLabelConfig;
+    /** Optional directory to automatically save all deliverable files */
+    outDir?: string;
+    /** Optional custom logger callback */
+    logger?: (msg: string) => void;
+}
+export interface AutonomousAuditDeliverables {
+    domain: string;
+    startUrl: string;
+    auditDate: string;
+    crawl: CrawlResult;
+    findings: SearchCentralFinding[];
+    passedRules: string[];
+    scores: AuditScoreResult;
+    actions: PrioritizedAction[];
+    actionSnippets: Record<string, string>;
+    narrative: AuditNarrative;
+    performance: PsiReport | null;
+    dataforseo: DfsCollectResult | null;
+    siteAssets: GeneratedSiteAssets;
+    deliverables: {
+        html: string;
+        xlsxBuffer: Uint8Array;
+        markdown: string;
+        digest: string;
+        auditJson: string;
+        sitemapXml: string;
+        llmsTxt: string;
+        llmsFullTxt: string;
+        robotsTxt: string;
+        schemaJsonLd: string;
+    };
+    savedPaths?: {
+        dir: string;
+        html: string;
+        xlsx: string;
+        markdown: string;
+        digest: string;
+        json: string;
+        sitemap: string;
+        llms: string;
+        llmsFull: string;
+        robots: string;
+        schema: string;
+    };
+}
+export declare class AutonomousAuditEngine {
+    /**
+     * Run a full, completely automated autonomous SEO audit from start to finish.
+     */
+    static run(input: AutonomousAuditInput): Promise<AutonomousAuditDeliverables>;
+}
+/**
+ * Convenience helper to run an autonomous audit with 1 line of code.
+ */
+export declare function executeAutonomousAudit(input: AutonomousAuditInput): Promise<AutonomousAuditDeliverables>;

package/dist/autonomous-site-assets-generator.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 🦁 Autonomous Site & AI Assets Generator
+ *
+ * Automatically generates production-ready, standards-compliant web & AI assets:
+ * 1. sitemap.xml & sitemapindex.xml (Google & Bing Sitemaps protocol with priority, changefreq, image extensions)
+ * 2. llms.txt (The official AI crawl manifest for ChatGPT, Claude, Perplexity, Gemini)
+ * 3. llms-full.txt (Comprehensive passage-level AI knowledge base for RAG and AI search)
+ * 4. robots.txt (RFC 9309 compliant, security-hardened, AI bots enabled, sitemap declared)
+ * 5. schema.jsonld (Structured data graph: WebSite, Organization, SearchAction)
+ */
+import type { CrawledPageRecord, CrawlResult } from "./crawler/native-crawler";
+export interface GeneratedSiteAssets {
+    domain: string;
+    sitemapXml: string;
+    sitemapIndexXml?: string;
+    sitemapCount: number;
+    llmsTxt: string;
+    llmsFullTxt: string;
+    robotsTxt: string;
+    schemaJsonLd: string;
+}
+export interface SiteAssetsGeneratorInput {
+    domain: string;
+    startUrl?: string;
+    siteTitle?: string;
+    siteDescription?: string;
+    pages?: Array<Partial<CrawledPageRecord> & {
+        url: string;
+    }>;
+    crawl?: CrawlResult;
+}
+export declare class AutonomousSiteAssetsGenerator {
+    /**
+     * Automatically generate all web & AI assets from crawl data or domain info.
+     */
+    static generate(input: SiteAssetsGeneratorInput): GeneratedSiteAssets;
+}

package/dist/backlinks-client.d.ts

@@ -1,8 +1,9 @@
 /**
- * 🔗 LynxFlow Backlinks & Domain Authority Client
+ * 🔗 LynxFlow Backlinks, Domain Authority & Gap Analysis Client
  *
  * Tracks incoming backlinks, referring domains, lost/new links,
- * and Domain Rating (DR) directly through the SDK.
+ * competitor backlink gap analysis, and toxic link detection.
+ * Supports DataForSEO, Ahrefs, and pluggable custom BacklinkProviders.
  */
 export interface BacklinkItem {
     sourceUrl: string;
@@ -19,13 +20,106 @@ export interface BacklinkProfileSummary {
     referringDomains: number;
     doFollowRatio: number;
     topBacklinks: BacklinkItem[];
+    isDemo?: boolean;
+    provider?: string;
 }
-export declare class BacklinksClient {
+export interface BacklinkGapItem {
+    referringDomain: string;
+    domainRating: number;
+    linksToTarget: boolean;
+    linksToCompetitor: boolean;
+    targetBacklinkCount: number;
+    competitorBacklinkCount: number;
+    opportunityType: "shared" | "missed_opportunity" | "target_advantage";
+    suggestedAction: string;
+}
+export interface BacklinkGapResult {
+    targetDomain: string;
+    competitorDomain: string;
+    targetDR: number;
+    competitorDR: number;
+    sharedDomainsCount: number;
+    missedOpportunitiesCount: number;
+    targetAdvantageCount: number;
+    gapOpportunities: BacklinkGapItem[];
+    isDemo?: boolean;
+    provider?: string;
+}
+export interface ToxicBacklinkItem {
+    sourceUrl: string;
+    sourceDomain: string;
+    spamScore: number;
+    domainRating: number;
+    toxicReason: string;
+    anchorText: string;
+    isSitewide: boolean;
+}
+export interface ToxicBacklinkSummary {
+    domain: string;
+    totalAnalyzed: number;
+    toxicCount: number;
+    toxicPercentage: number;
+    averageSpamScore: number;
+    toxicLinks: ToxicBacklinkItem[];
+    disavowSnippet: string;
+    isDemo?: boolean;
+    provider?: string;
+}
+export interface BacklinkProvider {
+    readonly name: string;
+    getProfile(domain: string): Promise<BacklinkProfileSummary>;
+    getGapAnalysis(targetDomain: string, competitorDomain: string): Promise<BacklinkGapResult>;
+    getToxicLinks(domain: string): Promise<ToxicBacklinkSummary>;
+}
+/**
+ * 📊 Real DataForSEO Backlinks Provider
+ * Interacts with DataForSEO v3 Backlinks API.
+ */
+export declare class DataforseoBacklinksProvider implements BacklinkProvider {
+    readonly name = "DataForSEO";
+    private authHeader;
+    private baseUrl;
+    constructor(apiKeyOrLogin: string, apiPassword?: string, baseUrl?: string);
+    getProfile(domain: string): Promise<BacklinkProfileSummary>;
+    getGapAnalysis(targetDomain: string, competitorDomain: string): Promise<BacklinkGapResult>;
+    getToxicLinks(domain: string): Promise<ToxicBacklinkSummary>;
+}
+/**
+ * ⚡ Ahrefs Backlinks Provider (G5 Partner Extension)
+ */
+export declare class AhrefsBacklinksProvider implements BacklinkProvider {
+    readonly name = "Ahrefs";
     private apiKey;
-    private endpoint;
-    constructor(apiKey: string, endpoint?: string);
-    /**
-     * Retrieves backlink profile and domain authority summary.
-     */
+    private baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    getProfile(domain: string): Promise<BacklinkProfileSummary>;
+    getGapAnalysis(targetDomain: string, competitorDomain: string): Promise<BacklinkGapResult>;
+    getToxicLinks(domain: string): Promise<ToxicBacklinkSummary>;
+}
+/**
+ * 🛡️ Fallback Demo Provider
+ * Explicitly marks data as demonstration when no real live credentials exist.
+ */
+export declare class FallbackDemoBacklinkProvider implements BacklinkProvider {
+    readonly name = "DemoFallback";
+    private getDomainHash;
+    getProfile(domain: string): Promise<BacklinkProfileSummary>;
+    getGapAnalysis(targetDomain: string, competitorDomain: string): Promise<BacklinkGapResult>;
+    getToxicLinks(domain: string): Promise<ToxicBacklinkSummary>;
+}
+/**
+ * 🚀 High-Level Backlinks Client with Provider Injection
+ */
+export declare class BacklinksClient {
+    private provider;
+    constructor(options?: {
+        provider?: BacklinkProvider;
+        apiKey?: string;
+        endpoint?: string;
+        dataforseoPassword?: string;
+    });
+    getProviderName(): string;
     getProfile(domain: string): Promise<BacklinkProfileSummary>;
+    getGapAnalysis(targetDomain: string, competitorDomain: string): Promise<BacklinkGapResult>;
+    getToxicLinks(domain: string): Promise<ToxicBacklinkSummary>;
 }

package/dist/backlinks-store.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 🔗 Persistent Backlinks Store
+ *
+ * In-memory store with history timeseries, subfolder authority,
+ * referring domains, profile, gap, and toxic detection.
+ */
+import type { BacklinkItem, BacklinkProfileSummary, BacklinkGapResult, ToxicBacklinkItem, ToxicBacklinkSummary } from "./backlinks-client";
+export interface BacklinkHistoryEntry {
+    timestamp: number;
+    totalBacklinks: number;
+    referringDomains: number;
+    domainAuthority: number;
+    doFollowRatio: number;
+}
+export interface SubfolderAuthority {
+    path: string;
+    backlinks: number;
+    referringDomains: number;
+    authority: number;
+}
+export interface ReferringDomain {
+    domain: string;
+    backlinks: number;
+    domainRating: number;
+    firstSeen: string;
+    isDoFollow: boolean;
+}
+export interface BacklinksStoreSnapshot {
+    profile: BacklinkProfileSummary;
+    history: BacklinkHistoryEntry[];
+    subfolderAuthority: SubfolderAuthority[];
+    referringDomains: ReferringDomain[];
+    gapAnalysis?: BacklinkGapResult;
+    toxicSummary?: ToxicBacklinkSummary;
+    lastUpdated: number;
+}
+export declare class BacklinksStore {
+    private profiles;
+    private history;
+    private subfolderAuthority;
+    private referringDomains;
+    private gapAnalyses;
+    private toxicSummaries;
+    private getKey;
+    /**
+     * Save or update profile for a domain
+     */
+    setProfile(domain: string, profile: BacklinkProfileSummary): void;
+    /**
+     * Get profile for a domain
+     */
+    getProfile(domain: string): BacklinkProfileSummary | null;
+    /**
+     * Record history entry for timeseries
+     */
+    private recordHistory;
+    /**
+     * Get history timeseries for a domain
+     */
+    getHistory(domain: string, limit?: number): BacklinkHistoryEntry[];
+    /**
+     * Set subfolder authority distribution
+     */
+    setSubfolderAuthority(domain: string, subfolders: SubfolderAuthority[]): void;
+    /**
+     * Get subfolder authority for a domain
+     */
+    getSubfolderAuthority(domain: string): SubfolderAuthority[];
+    /**
+     * Set referring domains list
+     */
+    setReferringDomains(domain: string, domains: ReferringDomain[]): void;
+    /**
+     * Get referring domains for a domain
+     */
+    getReferringDomains(domain: string): ReferringDomain[];
+    /**
+     * Add or update referring domains
+     */
+    addReferringDomain(domain: string, refDomain: ReferringDomain): void;
+    /**
+     * Set gap analysis result
+     */
+    setGapAnalysis(targetDomain: string, competitorDomain: string, gap: BacklinkGapResult): void;
+    /**
+     * Get gap analysis result
+     */
+    getGapAnalysis(targetDomain: string, competitorDomain: string): BacklinkGapResult | null;
+    /**
+     * Set toxic links summary
+     */
+    setToxicSummary(domain: string, toxic: ToxicBacklinkSummary): void;
+    /**
+     * Get toxic links summary
+     */
+    getToxicSummary(domain: string): ToxicBacklinkSummary | null;
+    /**
+     * Toxic link detection helper - analyze and flag toxic links
+     */
+    detectToxic(links: BacklinkItem[]): ToxicBacklinkItem[];
+    private extractDomain;
+    /**
+     * Get full snapshot for a domain
+     */
+    getSnapshot(domain: string): BacklinksStoreSnapshot | null;
+    /**
+     * Clear all data for a domain
+     */
+    clearDomain(domain: string): void;
+    /**
+     * Clear all data
+     */
+    clearAll(): void;
+}
+export declare const backlinksStore: BacklinksStore;

package/dist/bandit-optimizer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 🎰 LynxSEO Contextual Multi-Armed Bandit & Thompson Sampling Optimizer
+ *
+ * Implémente l'algorithme "Prism AI" de bandits manchots contextuels pour l'optimisation
+ * en temps réel des popups, sondages et offres promotionnelles e-commerce (Shopify/WooCommerce).
+ *
+ * Principes :
+ * 1. Thompson Sampling : Échantillonnage bayésien selon la loi Beta(alpha, beta).
+ * 2. Ciblage contextuel : Segmentation selon le panier, la source de trafic et le type d'appareil.
+ * 3. Minimisation du regret : Réallocation continue du trafic vers les variantes gagnantes
+ *    sans interrompre l'exploration des nouvelles variantes.
+ * 4. Déterminisme visiteur optionnel (pour consistance de session).
+ */
+export interface BanditArm {
+    id: string;
+    name: string;
+    /** Nombre de conversions réussies (succès) */
+    conversions: number;
+    /** Nombre d'expositions (impressions) */
+    impressions: number;
+    /** Valeur cumulée des conversions (ex: chiffre d'affaires généré) */
+    revenueGenerated?: number;
+    /** Conditions contextuelles optionnelles d'éligibilité */
+    contextConditions?: {
+        minCartTotal?: number;
+        maxCartTotal?: number;
+        deviceType?: "mobile" | "desktop" | "all";
+        trafficSource?: "paid" | "organic" | "direct" | "all";
+    };
+    /** Données de payload de la variante (titre, code promo, quiz questions, etc.) */
+    payload: Record<string, unknown>;
+}
+export interface VisitorContext {
+    distinctId?: string;
+    cartTotal?: number;
+    deviceType?: "mobile" | "desktop";
+    trafficSource?: "paid" | "organic" | "direct";
+    urlPath?: string;
+}
+export declare class BanditOptimizer {
+    /**
+     * Échantillonnage pseudo-aléatoire d'une distribution Gamma via Marsaglia-Tsang.
+     * Sert à échantillonner la distribution Beta(a, b) = Gamma(a) / (Gamma(a) + Gamma(b)).
+     */
+    static sampleGamma(alpha: number): number;
+    /**
+     * Échantillonnage d'une distribution normale standard N(0,1) via Box-Muller.
+     */
+    static sampleNormal(): number;
+    /**
+     * Échantillonnage de la loi Beta(alpha, beta).
+     */
+    static sampleBeta(alpha: number, beta: number): number;
+    /**
+     * Sélectionne la meilleure variante éligible via Thompson Sampling.
+     */
+    static selectArm(arms: BanditArm[], context?: VisitorContext, options?: {
+        priorAlpha?: number;
+        priorBeta?: number;
+    }): {
+        selectedArm: BanditArm;
+        sampleScore: number;
+        eligibleArmsCount: number;
+    };
+    /**
+     * Met à jour les métriques d'un bras après une impression ou une conversion.
+     */
+    static recordFeedback(arm: BanditArm, event: "impression" | "conversion", value?: number): BanditArm;
+    /**
+     * Identifie s'il existe une variante gagnante avec un seuil de confiance statistique donné (Early Stopping).
+     */
+    static findStatisticalWinner(arms: BanditArm[], minConversions?: number, confidenceThreshold?: number): {
+        hasWinner: boolean;
+        winningArm?: BanditArm;
+        confidence: number;
+        liftPercent: number;
+    };
+    /**
+     * Calcule le taux de conversion empirique (CR) et l'intervalle de confiance estimé.
+     */
+    static getArmStats(arm: BanditArm): {
+        conversionRate: number;
+        totalImpressions: number;
+        totalConversions: number;
+        avgOrderValue: number;
+    };
+}