@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/indexnow-client.d.ts

@@ -16,10 +16,42 @@ export interface IndexNowResponse {
     message: string;
     submittedUrls: number;
 }
+export interface KeyFileOptions {
+    /** MIME type of the served response. Defaults to "text/plain". */
+    contentType?: string;
+    /** Extra headers to attach to the served response. */
+    headers?: Record<string, string>;
+}
+export interface PingOptions {
+    /** When true, embeds the keyLocation pointing at `{host}/{key}.txt`. */
+    publishKeyFile?: boolean;
+    /** Override the endpoint (useful for testing). */
+    endpoint?: string;
+}
 export declare class IndexNowClient {
     private static INDEXNOW_ENDPOINT;
+    /**
+     * Generates the raw body of an IndexNow key file.
+     * The file must be served at `https://<host>/<key>.txt` and contain
+     * only the key (no trailing newline, no extra whitespace).
+     */
+    static generateKeyFile(key: string): string;
+    /**
+     * Server function: builds an HTTP Response serving `{key}.txt`.
+     * Wire this route in your worker / edge runtime:
+     *
+     * ```ts
+     * app.get("/:key.txt", (c) => IndexNowClient.serveKeyFile(c.req.param("key")));
+     * ```
+     */
+    static serveKeyFile(key: string, options?: KeyFileOptions): Response;
     /**
      * Ping IndexNow with a list of updated or newly created URLs.
      */
-    static submitUrls(payload: IndexNowPayload): Promise<IndexNowResponse>;
+    static submitUrls(payload: IndexNowPayload, options?: PingOptions): Promise<IndexNowResponse>;
+    /**
+     * Convenience: generate a key, build the key file, and ping IndexNow
+     * in a single call. Useful when onboarding a new domain programmatically.
+     */
+    static ping(host: string, key: string, urlList: string[], options?: PingOptions): Promise<IndexNowResponse>;
 }

package/dist/information-gain-scorer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 🧠 Information Gain & Originality Scorer (Google August 2026 Core Update Standard)
+ *
+ * Measures the novelty, unique value, and factual entropy of a piece of content
+ * compared to generic AI-generated rehashes and boilerplate top 10 search results.
+ *
+ * Google 2026 Algorithm Criteria:
+ * 1. Proprietary Data & Statistics Anchor (benchmarks, $, %, numbers)
+ * 2. First-Hand Experience Markers ("In our test", "We measured", "Our team found")
+ * 3. Novel Counter-Intuitive Insights (unorthodox expert advice vs generic lists)
+ * 4. Original Media & Data Structure (tables, step-by-step frameworks, quotes)
+ * 5. Generic Cliché Penalty (deducts points for "In today's fast-paced world", "It is important to remember", etc.)
+ */
+export interface InformationGainResult {
+    informationGainScore: number;
+    originalityGrade: "Exceptional" | "High Gain" | "Moderate" | "Commodity AI Content" | "Penalty Risk";
+    passesInformationGainThreshold: boolean;
+    metrics: {
+        factualDataDensity: number;
+        firstHandExperienceScore: number;
+        noveltyEntropyScore: number;
+        structuredDataAnchorScore: number;
+        clichePenaltyPoints: number;
+    };
+    detectedDataAnchors: string[];
+    detectedExperienceClaims: string[];
+    detectedGenericCliches: string[];
+    actionableGainBoosters: string[];
+}
+export declare class InformationGainScorer {
+    /**
+     * Evaluates content for Information Gain and First-Hand Experience.
+     */
+    static scoreInformationGain(markdownContent: string): InformationGainResult;
+    private static getEmptyResult;
+}

package/dist/instant-matrix-search.d.ts

@@ -1,5 +1,5 @@
 /**
- * 🔎 Instant In-Memory Matrix Search & Autocomplete ("Buscador") (Inspiration: santifer-irepair)
+ * 🔎 Instant In-Memory Matrix Search & Autocomplete ("Buscador")
  *
  * Provides sub-millisecond client-side live filtering and autocomplete across all 8 programmatic matrices.
  */

package/dist/integrations/cloudflare-browser-renderer.d.ts

@@ -0,0 +1,100 @@
+/**
+ * CloudflareBrowserRenderer - Edge headless browser rendering engine for LynxSEO.
+ * Leverages Cloudflare Workers Browser Rendering API (env.MYBROWSER),
+ * Cloudflare REST API (/browser-rendering/screenshot & /pdf),
+ * or remote headless CDP gateways (Browserless / Chrome container).
+ */
+export interface CloudflareBrowserBinding {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export interface CloudflareBrowserConfig {
+    /**
+     * Workers Browser Rendering fetcher binding (e.g. env.MYBROWSER)
+     */
+    binding?: CloudflareBrowserBinding;
+    /**
+     * Cloudflare Account ID for direct REST API invocation
+     */
+    accountId?: string;
+    /**
+     * Cloudflare API Token with Browser Rendering permissions
+     */
+    apiToken?: string;
+    /**
+     * Remote Browserless or Headless Chrome REST endpoint URL
+     */
+    remoteEndpoint?: string;
+    /**
+     * Custom request timeout in milliseconds (default: 30000)
+     */
+    timeoutMs?: number;
+}
+export interface BrowserScreenshotInput {
+    url: string;
+    width?: number;
+    height?: number;
+    fullPage?: boolean;
+    format?: "png" | "jpeg" | "webp";
+    quality?: number;
+    selector?: string;
+    delayMs?: number;
+}
+export interface BrowserScreenshotResult {
+    success: boolean;
+    url: string;
+    dataUri?: string;
+    buffer?: Uint8Array;
+    contentType: string;
+    width: number;
+    height: number;
+    capturedAt: string;
+    renderMode: "cloudflare-binding" | "cloudflare-rest" | "remote-gateway" | "simulated-fallback";
+    error?: string;
+}
+export interface BrowserPdfInput {
+    url: string;
+    format?: "A4" | "Letter" | "Legal";
+    printBackground?: boolean;
+    landscape?: boolean;
+    margin?: {
+        top?: string;
+        bottom?: string;
+        left?: string;
+        right?: string;
+    };
+    delayMs?: number;
+}
+export interface BrowserPdfResult {
+    success: boolean;
+    url: string;
+    dataUri?: string;
+    buffer?: Uint8Array;
+    contentType: string;
+    capturedAt: string;
+    renderMode: "cloudflare-binding" | "cloudflare-rest" | "remote-gateway" | "simulated-fallback";
+    error?: string;
+}
+export declare class CloudflareBrowserRenderer {
+    private readonly binding?;
+    private readonly accountId?;
+    private readonly apiToken?;
+    private readonly remoteEndpoint?;
+    private readonly timeoutMs;
+    constructor(config?: CloudflareBrowserConfig);
+    /**
+     * Returns true if any real headless browser backend is configured.
+     */
+    isConfigured(): boolean;
+    /**
+     * Captures a high-resolution screenshot using Cloudflare Browser Rendering or remote gateway.
+     */
+    takeScreenshot(input: BrowserScreenshotInput): Promise<BrowserScreenshotResult>;
+    /**
+     * Generates a PDF of the target web page using Cloudflare Browser Rendering or remote gateway.
+     */
+    printToPdf(input: BrowserPdfInput): Promise<BrowserPdfResult>;
+    /**
+     * Generates a high-quality PDF using Cloudflare Browser Rendering or remote gateway.
+     */
+    generatePdf(input: BrowserPdfInput): Promise<BrowserPdfResult>;
+}

package/dist/integrations/dataforseo-audit-client.d.ts

@@ -0,0 +1,152 @@
+/**
+ * DataForSEO Full Integration Client with Hard Budget Cap Ledger
+ */
+import { SearchCentralFinding } from "../rules/search-central-catalog";
+export declare const DFS_BASE_URL = "https://api.dataforseo.com/v3/";
+export declare const ESTIMATE_USD: Record<string, number>;
+export declare const PLATFORM_DOMAINS: Set<string>;
+export declare const SERP_FEATURES: string[];
+export declare function bareDomain(domain?: string | null): string;
+export declare function normalizeKeyword(k?: string | null): string;
+export interface DfsCallLog {
+    endpoint: string;
+    cost_usd: number;
+    reported: boolean;
+}
+export interface DfsLedger {
+    requests: number;
+    cost_usd: number;
+    reserved_usd: number;
+    skipped_budget: number;
+    failed: number;
+    errors: string[];
+    calls: DfsCallLog[];
+}
+export interface DfsKeywordRow {
+    keyword: string;
+    volume?: number;
+    cpc?: number;
+    difficulty?: number;
+    intent?: string;
+    position?: number;
+    url?: string;
+    etv?: number;
+    source?: string;
+    rival_position?: number;
+    relevance?: number | null;
+    target?: string;
+    page?: string;
+}
+export interface DfsOverview {
+    count?: number;
+    etv?: number;
+    estimated_paid_traffic_cost?: number;
+    pos_1?: number;
+    pos_2_3?: number;
+    pos_4_10?: number;
+    pos_11_20?: number;
+    pos_21_30?: number;
+    pos_31_40?: number;
+    pos_41_50?: number;
+    pos_51_60?: number;
+    pos_61_70?: number;
+    pos_71_80?: number;
+    pos_81_90?: number;
+    pos_91_100?: number;
+    is_new?: number;
+    is_up?: number;
+    is_down?: number;
+    is_lost?: number;
+}
+export interface DfsCompetitor {
+    domain: string;
+    shared_keywords?: number;
+    avg_position?: number;
+    etv?: number;
+    keywords?: number;
+}
+export interface DfsBacklinks {
+    rank?: number;
+    backlinks?: number;
+    referring_domains?: number;
+    referring_main_domains?: number;
+    referring_ips?: number;
+    broken_backlinks?: number;
+    broken_pages?: number;
+    backlinks_spam_score?: number;
+    crawled_pages?: number;
+    referring_links_types?: Record<string, number>;
+    referring_links_attributes?: Record<string, number>;
+}
+export interface DfsSerpItem {
+    keyword: string;
+    features: string[];
+    top: Array<{
+        position?: number;
+        domain: string;
+        url?: string;
+        title?: string;
+    }>;
+    own_position?: number | null;
+    ai_overview: boolean;
+    ai_overview_cites_site: boolean;
+    ai_overview_domains: string[];
+}
+export interface DfsCollectResult {
+    available: boolean;
+    location_code: number;
+    language_code: string;
+    ledger: DfsLedger;
+    overview?: DfsOverview | null;
+    ranked?: DfsKeywordRow[];
+    ranked_total?: number;
+    competitors?: DfsCompetitor[];
+    competitors_all?: DfsCompetitor[];
+    backlinks?: DfsBacklinks | null;
+    referring_domains?: Array<{
+        domain: string;
+        referring_domains?: number;
+        referring_main_domains?: number;
+    }>;
+    opportunities?: DfsKeywordRow[];
+    seeds?: string[];
+    serps?: DfsSerpItem[];
+    mentions?: {
+        total?: number;
+        items?: Array<{
+            platform?: string;
+            model?: string;
+            question?: string;
+            ai_search_volume?: number;
+            sources: string[];
+        }>;
+    } | null;
+    reused_from?: string;
+}
+export declare class DataForSeoClient {
+    private username?;
+    private password?;
+    budgetUsd: number;
+    log: (msg: string) => void;
+    ledger: DfsLedger;
+    constructor(options?: {
+        username?: string;
+        password?: string;
+        budgetUsd?: number;
+        log?: (msg: string) => void;
+    });
+    get isAvailable(): boolean;
+    post(endpoint: string, task: Record<string, unknown>): Promise<any>;
+}
+export declare function collectDataForSeo(domain: string, homepageTitle?: string, options?: {
+    locationCode?: number;
+    languageCode?: string;
+    budgetUsd?: number;
+    username?: string;
+    password?: string;
+    log?: (msg: string) => void;
+}): Promise<DfsCollectResult>;
+/**
+ * Extracts audit findings from DataForSEO collected data
+ */
+export declare function extractDfsFindings(domain: string, dfs: DfsCollectResult | null | undefined): SearchCentralFinding[];

package/dist/integrations/linkwarden-connector.d.ts

@@ -0,0 +1,72 @@
+/**
+ * LinkwardenConnector - Connecteur d'intégration API vers Linkwarden.
+ * Permet de synchroniser des backlinks, des URLs concurrentes et des ressources SEO
+ * vers des collections Linkwarden auto-hébergées ou Cloud.
+ */
+export interface LinkwardenConfig {
+    baseUrl: string;
+    accessToken: string;
+    defaultCollectionId?: number;
+}
+export interface LinkwardenTagInput {
+    name: string;
+}
+export interface LinkwardenCreateLinkInput {
+    url: string;
+    name?: string;
+    description?: string;
+    collectionId?: number;
+    tags?: LinkwardenTagInput[];
+}
+export interface LinkwardenLinkResult {
+    success: boolean;
+    linkId?: number;
+    url: string;
+    status?: number;
+    error?: string;
+}
+export interface LinkwardenCollection {
+    id: number;
+    name: string;
+    description?: string;
+    color?: string;
+    isPublic?: boolean;
+}
+export interface LinkwardenCreateCollectionInput {
+    name: string;
+    description?: string;
+    color?: string;
+    parentId?: number;
+    isPublic?: boolean;
+}
+export declare class LinkwardenConnector {
+    private readonly baseUrl;
+    private readonly accessToken;
+    private readonly defaultCollectionId?;
+    constructor(config: LinkwardenConfig);
+    private getHeaders;
+    /**
+     * Crée ou archive un lien dans Linkwarden.
+     */
+    createLink(input: LinkwardenCreateLinkInput): Promise<LinkwardenLinkResult>;
+    /**
+     * Récupère la liste des collections de l'utilisateur.
+     */
+    getCollections(): Promise<LinkwardenCollection[]>;
+    /**
+     * Crée une nouvelle collection dans Linkwarden.
+     */
+    createCollection(input: LinkwardenCreateCollectionInput): Promise<LinkwardenCollection>;
+    /**
+     * Synchronise une liste de backlinks surveillés vers Linkwarden.
+     */
+    syncMonitoredBacklinks(links: Array<{
+        url: string;
+        title: string;
+        notes?: string;
+        targetCollectionId?: number;
+    }>): Promise<{
+        synced: number;
+        failed: number;
+    }>;
+}

package/dist/integrations/pagespeed-client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Google PageSpeed Insights v5 Client
+ * Chrome UX Report (CrUX) Field Data + Lighthouse Lab Scores
+ */
+import { SearchCentralFinding } from "../rules/search-central-catalog";
+export declare const PAGESPEED_API_URL = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed";
+export declare const PSI_CATEGORIES: readonly ["performance", "accessibility", "best-practices", "seo"];
+export interface MetricThreshold {
+    name: string;
+    unit: string;
+    goodMax: number;
+    poorMin: number;
+}
+export declare const METRIC_THRESHOLDS: Record<string, MetricThreshold>;
+export declare const LAB_METRICS: Record<string, string>;
+export interface FieldMetric {
+    p75: number;
+    unit: string;
+    rating: "good" | "needs improvement" | "poor";
+    good_max: number;
+    poor_min: number;
+}
+export interface FieldExperience {
+    overall?: string;
+    metrics: Record<string, FieldMetric>;
+}
+export interface PsiOpportunity {
+    id: string;
+    title: string;
+    savings_ms: number;
+}
+export interface PsiRunResult {
+    url: string;
+    strategy: "mobile" | "desktop";
+    fetched_at?: string;
+    lighthouse_version?: string;
+    scores?: Record<string, number>;
+    lab?: Record<string, {
+        value?: number;
+        display?: string;
+    }>;
+    field_url?: FieldExperience | null;
+    field_origin?: FieldExperience | null;
+    opportunities?: PsiOpportunity[];
+    error?: string;
+}
+export interface PsiReport {
+    source: string;
+    keyed: boolean;
+    runs: PsiRunResult[];
+}
+export declare function parseFieldExperience(block: any): FieldExperience | null;
+export declare function runPageSpeedOne(url: string, strategy: "mobile" | "desktop", apiKey?: string): Promise<PsiRunResult>;
+export declare function runPageSpeedInsights(urls: string[], options?: {
+    apiKey?: string;
+    log?: (msg: string) => void;
+}): Promise<PsiReport>;
+/**
+ * Derives audit findings from PageSpeed results: real-user Core Web Vitals and Lighthouse score.
+ */
+export declare function extractPerformanceFindings(perf: PsiReport | null): SearchCentralFinding[];

package/dist/internal-link-graph-engine.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 🕸️ InternalLinkGraphEngine
+ *
+ * Analyse la topologie du maillage interne d'un site web :
+ * - Calcul du PageRank interne distribué (algorithme power iteration O(N))
+ * - Détection des pages orphelines (0 inlinks)
+ * - Détection des gouffres (dead-ends / pages sans liens sortants)
+ * - Classification des nœuds : Hubs (distributeurs de PageRank) vs Authorities (récepteurs)
+ * - Calcul de coordonnées 2D (force-directed layout) pour rendu SVG/Canvas interactif
+ *
+ * Pure In-Memory, 0 dépendance, < 0.1ms.
+ */
+export interface LinkEdge {
+    from: string;
+    to: string;
+    anchorText?: string;
+    isDofollow?: boolean;
+    /**
+     * Emplacement sémantique du lien dans le DOM. Les menus globaux (`<nav>`,
+     * `<footer>`) ne portent pas le même poids qu'un lien contextuel éditorial
+     * du corps de la page (`<main>`, `<article>`).
+     */
+    location?: "nav" | "footer" | "content" | "header" | "unknown";
+}
+export interface GraphNode {
+    id: string;
+    url: string;
+    title?: string;
+    inDegree: number;
+    outDegree: number;
+    contentInDegree: number;
+    navInDegree: number;
+    /**
+     * Page accessible uniquement via menu global / footer / sitemap,
+     * sans aucun lien contextuel éditorial dans le contenu.
+     */
+    isWeakLinkage: boolean;
+    internalPageRank: number;
+    type: "hub" | "authority" | "orphan" | "dead-end" | "weak" | "standard";
+    depth: number;
+    /** Coordonnées 2D normalisées (0-100) pour rendu SVG */
+    x: number;
+    y: number;
+    radius: number;
+}
+export interface LinkGraphAnalysisResult {
+    nodes: GraphNode[];
+    edges: LinkEdge[];
+    summary: {
+        totalPages: number;
+        totalInternalLinks: number;
+        contentLinksCount: number;
+        navLinksCount: number;
+        orphanPagesCount: number;
+        weakPagesCount: number;
+        deadEndsCount: number;
+        averageInDegree: number;
+        density: number;
+        topAuthorityUrl: string;
+        deepestPageDepth: number;
+    };
+    orphanUrls: string[];
+    weakUrls: string[];
+    deadEndUrls: string[];
+}
+export interface ClickDepthAuditResult {
+    rootUrl: string;
+    maxDepth: number;
+    clickDepthDistribution: {
+        l0: number;
+        l1: number;
+        l2: number;
+        l3: number;
+        l4PlusBuried: number;
+    };
+    threeClickRuleComplianceScore: number;
+    buriedUrls: {
+        url: string;
+        depth: number;
+    }[];
+    recommendations: string[];
+}
+export interface SiloDefinition {
+    siloName: string;
+    hubUrl: string;
+    spokeUrls: string[];
+}
+export interface SiloIntegrityAuditResult {
+    overallIntegrityScore: number;
+    siloReports: {
+        siloName: string;
+        hubUrl: string;
+        internalConnectivityScore: number;
+        spokeCount: number;
+        unlinkedSpokesFromHub: string[];
+        spokesMissingLinkToHub: string[];
+        crossSiloLeakCount: number;
+    }[];
+    criticalFixes: string[];
+}
+export declare class InternalLinkGraphEngine {
+    /**
+     * Analyse un graphe de liens internes et calcule la distribution du PageRank.
+     */
+    static analyze(urls: string[], edges: LinkEdge[], rootUrl?: string): LinkGraphAnalysisResult;
+    /**
+     * Génère un export Gephi GEXF formaté pour visualiseur de réseau.
+     */
+    static toGexf(result: LinkGraphAnalysisResult): string;
+    /**
+     * 🎯 3. Audit Click Depth & The 3-Click Rule
+     * Users and search crawlers should be able to reach any important page in 3 clicks or fewer from root.
+     */
+    static auditClickDepth(rootUrl: string, edges: LinkEdge[]): ClickDepthAuditResult;
+    /**
+     * 🏛️ 4. Audit Silo & Hub-Spoke Topical Integrity
+     * Ensures topical cluster isolation: Hub connects to all Spokes, and Spokes link back to Hub.
+     */
+    static auditSiloIntegrity(edges: LinkEdge[], silos: SiloDefinition[]): SiloIntegrityAuditResult;
+}

package/dist/international-seo-auditor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 🌍 International SEO Advanced — Cultural Adaptation, Content Parity & Locale Formats
+ *
+ * Goes beyond technical hreflang tags to validate that a site actually *qualifies*
+ * for each language it claims to support:
+ *   - Cultural Adaptation Score   → is the content genuinely localized, not machine-sloshed?
+ *   - Content Parity Audit        → per-language page existence + length ratios vs reference
+ *   - Locale Format Validation    → numbers/dates/currency/address/phone idioms per locale
+ *
+ * Reference model (industry heuristics, not hard Google rules):
+ *   German often runs 25-35% longer than English; Japanese 10-25% shorter.
+ */
+export interface CulturalProfile {
+    refLanguage: string;
+    lengthRatioToRef: number;
+    tone: "direct" | "formal" | "polite" | "expressive";
+    currencyFormats: string[];
+    dateFormats: string[];
+    numberDecimal: string;
+    phonePattern: string;
+    notes: string;
+}
+export interface LocaleContentDatum {
+    locale: string;
+    exists: boolean;
+    wordCount: number;
+    freshnessDays: number;
+}
+export interface ContentParityResult {
+    locale: string;
+    exists: boolean;
+    expectedLengthMin: number;
+    expectedLengthMax: number;
+    actualLength: number;
+    lengthStatus: "in_range" | "too_short" | "too_long" | "missing";
+    freshnessStatus: "fresh" | "stale" | "missing";
+    score: number;
+}
+export interface InternationalSeoAudit {
+    domain: string;
+    referenceLocale: string;
+    cultural: CulturalProfile;
+    parity: ContentParityResult[];
+    formatValidation: Array<{
+        locale: string;
+        field: "number" | "date" | "currency" | "address" | "phone";
+        sample: string;
+        valid: boolean;
+        expected: string;
+    }>;
+    overallScore: number;
+    recommendations: string[];
+}
+export declare class InternationalSeoAuditor {
+    /**
+     * Builds the cultural profile for a target locale vs a reference (default en).
+     */
+    static buildCulturalProfile(locale: string, ref?: string): CulturalProfile;
+    /**
+     * Validates a locale's content length against the expected parity range for a
+     * reference-language word count. Returns a 0-100 score.
+     */
+    static evaluateContentParity(locale: string, refWordCount: number, datum: {
+        exists?: boolean;
+        wordCount?: number;
+        freshnessDays?: number;
+    }): ContentParityResult;
+    /**
+     * Validates named format idioms (number/date/currency/phone) for a locale.
+     */
+    static validateLocaleFormat(locale: string, sample: string): {
+        valid: boolean;
+        expected: string;
+    };
+    /**
+     * Runs the full international audit across a set of locales. `datumByLocale`
+     * supplies content word counts/freshness per locale; `refWordCount` is the
+     * reference (usually English) page length.
+     */
+    static audit(input: {
+        domain: string;
+        locales: string[];
+        refWordCount: number;
+        referenceLocale?: string;
+        datumByLocale?: Record<string, {
+            wordCount?: number;
+            freshnessDays?: number;
+        }>;
+        formatSamples?: Record<string, Record<string, string>>;
+    }): InternationalSeoAudit;
+}