@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/copy-frameworks-master.d.ts

@@ -1,7 +1,7 @@
 /**
  * ✍️ Master Copywriting & AI-SEO Prompt Frameworks Engine
  *
- * Implements the complete set of formulas from marketingskills:
+ * Implements the copywriting formulas below:
  * 1. 5 Battle-Tested Headline Formulas (Outcome, Problem, Audience, Differentiation, Proof)
  * 2. The Human Action Model (Discomfort ➔ Vision ➔ Path)
  * 3. 40-60 Word Concise AEO / GEO Definition Answer Block for LLM Citation
@@ -22,7 +22,7 @@ export interface HumanActionModelCopy {
 }
 export declare class CopywritingFrameworksMaster {
     /**
-     * 1. Generates 5 high-converting headline variants based on marketingskills formulas.
+     * 1. Generates 5 high-converting headline variants based on proven copywriting formulas.
      */
     static generateHeadlines(opts: {
         serviceName: string;

package/dist/crawl-api-enricher.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 🦁 LynxSEO Crawl API Enrichment Engine
+ *
+ * Bridges the crawl tree with live external APIs:
+ * 1. Google Search Console: Injects clicks, impressions, CTR, position, and discovers orphan pages.
+ * 2. Google Analytics 4: Injects sessions, active users, bounce rate, and conversions.
+ * 3. PageSpeed Insights: Injects Core Web Vitals (LCP, CLS, INP, TTFB) and mobile/desktop score.
+ * 4. Backlinks Providers (Ahrefs, Moz, Majestic): Injects referring domains, backlink count, and trust authority.
+ * 5. AI Engine (Gemini / OpenAI / Ollama / Anthropic): Generates missing titles, descriptions, and intent classifications.
+ */
+import type { CrawledPageData } from "./site-crawler";
+import type { DeepCrawlUrlItem } from "./deep-crawl-importer";
+export interface GscPageMetric {
+    url: string;
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position: number;
+}
+export interface Ga4PageMetric {
+    url: string;
+    sessions: number;
+    users: number;
+    bounceRate: number;
+    conversions?: number;
+}
+export interface PsiPageMetric {
+    url: string;
+    score: number;
+    lcpMs: number;
+    cls: number;
+    inpMs: number;
+}
+export interface BacklinksPageMetric {
+    url: string;
+    backlinksCount: number;
+    referringDomainsCount: number;
+    authorityScore: number;
+}
+export interface AiPageEnrichment {
+    url: string;
+    suggestedTitle?: string;
+    suggestedMetaDescription?: string;
+    detectedIntent?: "informational" | "transactional" | "commercial" | "navigational";
+}
+export interface CrawlApiEnrichmentData {
+    gsc?: {
+        clicks: number;
+        impressions: number;
+        ctr: number;
+        position: number;
+    };
+    ga4?: {
+        sessions: number;
+        users: number;
+        bounceRate: number;
+        conversions?: number;
+    };
+    psi?: {
+        score: number;
+        lcpMs: number;
+        cls: number;
+        inpMs: number;
+    };
+    backlinks?: {
+        backlinksCount: number;
+        referringDomainsCount: number;
+        authorityScore: number;
+    };
+    ai?: {
+        suggestedTitle?: string;
+        suggestedMetaDescription?: string;
+        detectedIntent?: string;
+    };
+}
+export interface EnrichedCrawlItem extends DeepCrawlUrlItem {
+    apiEnrichment?: CrawlApiEnrichmentData;
+}
+export interface EnrichedCrawlReport {
+    totalUrls: number;
+    gscEnrichedUrlsCount: number;
+    ga4EnrichedUrlsCount: number;
+    psiEnrichedUrlsCount: number;
+    backlinksEnrichedUrlsCount: number;
+    aiEnrichedUrlsCount: number;
+    orphanPagesFound: Array<{
+        url: string;
+        clicks: number;
+        impressions: number;
+        message: string;
+    }>;
+    items: EnrichedCrawlItem[];
+}
+export declare class CrawlApiEnricher {
+    /**
+     * Normalize an URL for cross-reconciliation (stripping trailing slash, protocol normalization)
+     */
+    static normalizeUrl(rawUrl: string): string;
+    /**
+     * Merge external API datasets into crawl URL items
+     */
+    static enrich(options: {
+        items: DeepCrawlUrlItem[] | CrawledPageData[];
+        gscData?: GscPageMetric[];
+        ga4Data?: Ga4PageMetric[];
+        psiData?: PsiPageMetric[];
+        backlinksData?: BacklinksPageMetric[];
+        aiData?: AiPageEnrichment[];
+    }): EnrichedCrawlReport;
+}

package/dist/crawl-config-profile.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 🦁 LynxSEO Crawl Configuration Profile Engine
+ *
+ *
+ * Enables importing, exporting, and managing reusable enterprise crawl configuration
+ * profiles (.lynxseoconfig) across client accounts and CI/CD pipelines.
+ */
+export interface CrawlConfigProfile {
+    name: string;
+    version: "1.0.0";
+    createdAt: string;
+    description?: string;
+    spider: {
+        userAgent: "LynxSeoBot/3.0 (Desktop)" | "LynxSeoBot/3.0 (Mobile)" | string;
+        maxCrawlDepth: number;
+        maxPagesLimit: number;
+        concurrency: number;
+        obeyRobotsTxt: boolean;
+        stripQueryParams: boolean;
+        respectNoindex: boolean;
+        respectNofollow: boolean;
+        includePatterns: string[];
+        excludePatterns: string[];
+    };
+    auditors: {
+        enableNearDuplicateDetection: boolean;
+        nearDuplicateThresholdPercentage: number;
+        enableGoogleRichResultsValidation: boolean;
+        enableConsoleLogAuditing: boolean;
+        enableHreflangReciprocalValidation: boolean;
+        enableSitemapReconciliation: boolean;
+    };
+    customHeaders?: Record<string, string>;
+}
+export declare class CrawlConfigProfileEngine {
+    /**
+     * Generates a standard recommended enterprise crawl profile
+     */
+    static createDefaultProfile(name?: string): CrawlConfigProfile;
+    /**
+     * Serializes profile to formatted .lynxseoconfig JSON string
+     */
+    static serialize(profile: CrawlConfigProfile): string;
+    /**
+     * Parses and validates raw JSON into a validated CrawlConfigProfile
+     */
+    static deserialize(rawJson: string): CrawlConfigProfile;
+    /**
+     * Validate parameters integrity
+     */
+    static validate(profile: CrawlConfigProfile): {
+        isValid: boolean;
+        errors: string[];
+    };
+}

package/dist/crawl-diff-engine.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 🦁 LynxSEO Crawl Diff & Regression Engine
+ *
+ * Implements automated crawl comparison matching Screaming Frog's
+ * DiffOverviewReportJsonExporter. Compares a baseline crawl snapshot against
+ * a new crawl to detect regressions, inventory shifts, and indexability hazards.
+ */
+import type { DeepCrawlSummary } from "./deep-crawl-importer";
+export interface StatusCodeChange {
+    url: string;
+    oldStatus: number;
+    newStatus: number;
+    type: "regression" | "improvement" | "shift";
+    severity: "CRITICAL" | "HIGH" | "INFO";
+}
+export interface IndexabilityChange {
+    url: string;
+    oldIndexable: boolean;
+    newIndexable: boolean;
+    reason?: string;
+    severity: "CRITICAL" | "INFO";
+}
+export interface CanonicalChange {
+    url: string;
+    oldCanonical?: string;
+    newCanonical?: string;
+}
+export interface TitleChange {
+    url: string;
+    oldTitle?: string;
+    newTitle?: string;
+}
+export interface ContentWordRegression {
+    url: string;
+    oldWordCount: number;
+    newWordCount: number;
+    dropPercentage: number;
+}
+export interface CrawlDiffSummary {
+    urlsBaseline: number;
+    urlsCurrent: number;
+    deltaUrls: number;
+    addedUrlsCount: number;
+    removedUrlsCount: number;
+    statusCodeRegressionsCount: number;
+    statusCodeImprovementsCount: number;
+    indexabilityLossCount: number;
+    canonicalDriftsCount: number;
+    titleChangesCount: number;
+    contentRegressionsCount: number;
+}
+export interface CrawlDiffReport {
+    timestamp: string;
+    summary: CrawlDiffSummary;
+    addedUrls: string[];
+    removedUrls: string[];
+    statusCodeChanges: StatusCodeChange[];
+    indexabilityChanges: IndexabilityChange[];
+    canonicalChanges: CanonicalChange[];
+    titleChanges: TitleChange[];
+    contentRegressions: ContentWordRegression[];
+    prioritizedActionItems: string[];
+}
+export declare class CrawlDiffEngine {
+    /**
+     * Compares two crawl snapshots and produces a structured regression diff report
+     */
+    static compare(baseline: DeepCrawlSummary, current: DeepCrawlSummary): CrawlDiffReport;
+}

package/dist/crawler/native-crawler.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Native BFS Crawler & Site Probe Engine for LynxSEO Engine
+ */
+import { ParsedPageFacts } from "./native-parser";
+import { type CrawlerRetryPolicy } from "../crawler-retry-policy";
+export declare const USER_AGENT = "LynxSEO-Engine/3.0 (+https://lynxseo.io/bot)";
+export declare const TIMEOUT_MS = 20000;
+export declare const SKIP_EXT: RegExp;
+export declare const AI_BOTS: string[];
+export declare const SEARCH_BOTS: string[];
+export declare const SECURITY_HEADERS: string[];
+/**
+ * SSRF Guard: Verify that host resolves only to public routable IP addresses.
+ */
+export declare function isPublicHost(host: string): Promise<boolean>;
+/**
+ * Robots.txt Rule Parser
+ */
+export interface RobotsTxtResult {
+    url: string;
+    status: number | null;
+    present: boolean;
+    bytes: number;
+    sitemaps: string[];
+    crawl_delay: number | null;
+    disallow_all: boolean;
+    search_bots: Record<string, boolean>;
+    ai_bots: Record<string, boolean>;
+    ai_bots_named: string[];
+    /** True when the server asked us to come back later (429 / 5xx). */
+    retry_later?: boolean;
+    canFetch: (bot: string, path: string) => boolean;
+}
+export declare class RobotsParser {
+    private policy;
+    crawlDelay: number | null;
+    sitemaps: string[];
+    constructor(body: string);
+    canFetch(agent: string, targetPath: string): boolean;
+}
+export declare function parseRobotsTxt(fetcher: Fetcher, origin: string): Promise<RobotsTxtResult>;
+export interface SitemapFileResult {
+    url: string;
+    status: number | null;
+    urls: number;
+    error: string | null;
+    lastmod: number;
+    type?: string;
+    children?: number;
+}
+export interface SitemapsResult {
+    files: SitemapFileResult[];
+    urls: string[];
+    total_urls: number;
+}
+/**
+ * Fetch and parse XML sitemaps including gzip compressed files and sitemap indexes.
+ */
+export declare function readSitemaps(fetcher: Fetcher, urls: string[], limit?: number): Promise<SitemapsResult>;
+export interface HttpResponse {
+    status: number;
+    url: string;
+    finalUrl: string;
+    headers: Record<string, string>;
+    text: string;
+    buffer: Buffer;
+    history: Array<{
+        url: string;
+        status: number;
+    }>;
+    elapsedMs: number;
+}
+export declare const DEFAULT_LANG = "en";
+/**
+ * Polite HTTP Fetcher with SSRF guards, redirect tracking, and pacing.
+ * Sites that redirect by Accept-Language must be asked in their own language.
+ */
+export declare class Fetcher {
+    delayMs: number;
+    requests: number;
+    lang: string;
+    retryPolicy: CrawlerRetryPolicy;
+    private lastRequestTime;
+    private publicCache;
+    constructor(delaySeconds?: number, lang?: string, retryPolicy?: CrawlerRetryPolicy);
+    private pace;
+    private allowedHost;
+    get(url: string): Promise<HttpResponse | null>;
+    getRaw(url: string): Promise<HttpResponse | null>;
+    head(url: string): Promise<number | null>;
+    private send;
+    /**
+     * Sends one request, retrying transient statuses and network failures with
+     * bounded exponential backoff (honouring Retry-After). Returns the last
+     * response, which may still carry a retryable status once attempts run out,
+     * or `null` when every attempt failed at the network level.
+     */
+    private fetchWithRetry;
+}
+export interface CrawledPageRecord extends Partial<ParsedPageFacts> {
+    url: string;
+    fetched_at: string;
+    status: number | null;
+    final_url?: string;
+    redirect_chain?: Array<{
+        url: string;
+        status: number;
+    }>;
+    content_type?: string;
+    bytes?: number;
+    ttfb_ms?: number;
+    x_robots?: string | null;
+    headers?: Record<string, string>;
+    rendered?: boolean;
+    js_dependent?: boolean;
+    raw_word_count?: number;
+    depth?: number;
+    kind?: "page" | "redirect";
+    final_status?: number | null;
+    in_sitemap?: boolean;
+    reached_via?: string;
+    inlinks?: number;
+    inlink_anchors?: string[];
+    error?: string;
+}
+export interface CrawlResult {
+    input_url: string;
+    start_url: string;
+    final_url: string;
+    origin: string;
+    domain: string;
+    https: boolean;
+    robots: RobotsTxtResult;
+    sitemaps: SitemapsResult;
+    probes: {
+        http_to_https: boolean;
+        http_redirect_status: number | null;
+        host_variant: {
+            host: string;
+            status: number | null;
+            redirect_status: number | null;
+            redirects_to_canonical_host: boolean;
+        };
+        not_found_status: number | null;
+        llms_txt: boolean;
+    };
+    pages: CrawledPageRecord[];
+    link_status: Record<string, number | string | null>;
+    external_status: Record<string, number | null>;
+    external_total: number;
+    blocked_by_robots: string[];
+    render: {
+        mode: string;
+        browser_available: boolean | null;
+        homepage_rendered: boolean;
+    };
+    requests: number;
+    limits: {
+        max_pages: number;
+        max_depth: number;
+        time_budget_s: number;
+        hit_page_cap: boolean;
+        hit_time_budget: boolean;
+    };
+}
+export interface NativeCrawlOptions {
+    max_pages?: number;
+    max_depth?: number;
+    workers?: number;
+    render_mode?: "auto" | "always" | "never";
+    time_budget?: number;
+    lang?: string;
+    language?: string;
+    log?: (msg: string) => void;
+}
+/**
+ * Execute native crawl starting from seed URL.
+ */
+export declare function crawlSite(startUrl: string, options?: NativeCrawlOptions): Promise<CrawlResult>;

package/dist/crawler/native-parser.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Native HTML Document Parser for LynxSEO Engine
+ */
+export interface JsonLdNodeSummary {
+    types: string[];
+    keys: string[];
+    offers_price: boolean;
+    list_items: number;
+    list_items_ok: boolean;
+}
+export interface ParsedImageMeta {
+    total: number;
+    missing_alt: number;
+    empty_alt: number;
+    lazy: number;
+    no_dimensions: number;
+    missing_alt_samples: string[];
+}
+export interface ParsedLink {
+    url: string;
+    anchor: string;
+}
+export interface ParsedPageFacts {
+    url: string;
+    title: string | null;
+    title_count: number;
+    meta_description: string | null;
+    meta_robots: string | null;
+    canonical: string | null;
+    lang: string | null;
+    viewport: string | null;
+    charset: boolean;
+    og: {
+        title: string | null;
+        description: string | null;
+        image: string | null;
+        type: string | null;
+        url: string | null;
+    };
+    twitter_card: string | null;
+    favicon: boolean;
+    hreflang: Array<{
+        lang: string;
+        href: string;
+    }>;
+    h1: string[];
+    h2: string[];
+    h3: string[];
+    outline: string[];
+    heading_skips: number;
+    word_count: number;
+    text_excerpt: string;
+    calls_to_action: string[];
+    nav_labels: string[];
+    text_hash: string;
+    images: ParsedImageMeta;
+    links_internal: ParsedLink[];
+    links_external: ParsedLink[];
+    nofollow_links: number;
+    schema_types: string[];
+    schema_errors: string[];
+    schema_nodes: JsonLdNodeSummary[];
+    mixed_content: string[];
+    script_count: number;
+}
+export declare function normalizeUrl(url: string): string;
+export declare function hostKey(host: string): string;
+export declare function parsePage(url: string, html: string, siteHost: string): ParsedPageFacts;

package/dist/crawler-retry-policy.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Retry/backoff policy for the native crawler. Politeness pacing already
+ * lives in `Fetcher.pace()`; this module adds bounded retries with exponential
+ * backoff, jitter and Retry-After support.
+ */
+export interface CrawlerRetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    /** 0 = no jitter, 0.5 = ±50% around the computed delay. */
+    jitterRatio: number;
+    retryStatuses: readonly number[];
+    respectRetryAfter: boolean;
+}
+export declare const DEFAULT_CRAWLER_RETRY_POLICY: CrawlerRetryPolicy;
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | null;
+export declare function shouldRetryStatus(status: number, policy?: CrawlerRetryPolicy): boolean;
+export declare function computeRetryDelayMs(attempt: number, policy?: CrawlerRetryPolicy, retryAfterMs?: number, random?: () => number): number;

package/dist/cro-bayesian-calculator.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Calculateur bayésien de significativité pour l'optimisation des taux de conversion (CRO).
+ * Utilisé pour évaluer avec rigueur mathématique les variantes d'AB test et de multi-armed bandit.
+ */
+export interface ArmStats {
+    id: string;
+    name: string;
+    impressions: number;
+    conversions: number;
+    alpha?: number;
+    beta?: number;
+}
+export interface BayesianCredibleInterval {
+    lower: number;
+    upper: number;
+    mean: number;
+}
+export interface ArmComparisonResult {
+    controlId: string;
+    variantId: string;
+    variantName: string;
+    controlMean: number;
+    variantMean: number;
+    liftPercent: number;
+    chanceToBeatControl: number;
+    expectedLoss: number;
+    isWinner: boolean;
+    confidenceLevel: "low" | "medium" | "high" | "statistically_significant";
+    controlInterval: BayesianCredibleInterval;
+    variantInterval: BayesianCredibleInterval;
+}
+export declare class CroBayesianCalculator {
+    /**
+     * Calcule les paramètres postérieurs Beta(alpha, beta) avec a priori non informatif Beta(1, 1).
+     */
+    static getPosterior(impressions: number, conversions: number): {
+        alpha: number;
+        beta: number;
+    };
+    /**
+     * Approximation de l'intervalle de crédibilité bayésien à 95%
+     * en utilisant l'approximation normale de la loi Beta.
+     */
+    static calculateCredibleInterval(alpha: number, beta: number): BayesianCredibleInterval;
+    /**
+     * Calcule la probabilité exacte ou approchée par simulation de Monte Carlo
+     * que la variante B surpasse le contrôle A : P(B > A).
+     *
+     * Utilise une intégration numérique par échantillonnage de Monte Carlo
+     * vectorisé pour garantir une précision absolue à < 0.2%.
+     */
+    static calculateChanceToBeat(alphaA: number, betaA: number, alphaB: number, betaB: number, simulations?: number): {
+        chanceToBeat: number;
+        expectedLoss: number;
+    };
+    /**
+     * Compare un ensemble de variantes avec un bras de contrôle.
+     */
+    static compareArms(control: ArmStats, variants: ArmStats[]): ArmComparisonResult[];
+    /**
+     * Échantillonne une variable aléatoire suivant la loi Beta(alpha, beta).
+     * Utilise le rapport de deux distributions Gamma échantillonnées via Marsaglia-Tsang.
+     */
+    private static sampleBeta;
+    /**
+     * Générateur de nombres aléatoires suivant une loi Gamma(shape, scale).
+     * Méthode de Marsaglia et Tsang (2000).
+     */
+    private static sampleGamma;
+    /**
+     * Transformation de Box-Muller pour échantillonner une loi normale standard N(0, 1).
+     */
+    private static sampleStandardNormal;
+}

package/dist/cro-copywriting-engine.d.ts

@@ -1,5 +1,5 @@
 /**
- * ✍️ Automated Copywriting & CRO Injection Engine (Inspiration: marketingskills)
+ * ✍️ Automated Copywriting & CRO Injection Engine
  *
  * Automatically generates high-converting sales copy blocks using proven frameworks:
  * 1. PAS (Problem - Agitation - Solution)
@@ -40,7 +40,7 @@ export declare class CroCopywritingEngine {
         freeTrialDays?: number;
     }): string;
     /**
-     * Generates an Instant WhatsApp / Direct Call conversion trigger button (inspired by Jacobo).
+     * Generates an Instant WhatsApp / Direct Call conversion trigger button.
      */
     static generateInstantConverterWidget(phoneNumber: string, brandOrMessage: string, serviceName?: string): string;
 }

package/dist/cro-heuristic-auditor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 🎯 CroHeuristicAuditor — Conversion Rate & Above-The-Fold Heuristic Auditor
+ *
+ *
+ * Checks:
+ * 1. Above-The-Fold Hero Hierarchy (H1, Value Proposition, Primary CTA visible without scroll)
+ * 2. CTA Clarity & Power Verb usage ("Commencer","Essai gratuit","Calculer")
+ * 3. Friction Reducers ("Sans carte bancaire", "Annulation à tout moment", "Conforme RGPD")
+ * 4. Social Proof & Trust Signals (avis clients, logos, certifications, étoiles)
+ * 5. Visual Distraction & Form Field Friction (> 4 champs pénalisé)
+ */
+export interface CroFinding {
+    id: string;
+    category: "hero_above_fold" | "cta_action" | "trust_proof" | "friction";
+    status: "pass" | "warn" | "fail";
+    pointsAwarded: number;
+    maxPoints: number;
+    title: string;
+    description: string;
+    remedy: string;
+}
+export interface CroAuditReport {
+    checked: boolean;
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    findings: CroFinding[];
+    metrics: {
+        ctaCount: number;
+        hasAboveTheFoldCta: boolean;
+        hasClearValueProposition: boolean;
+        trustSignalsCount: number;
+        frictionReducersCount: number;
+        formFieldCount: number;
+    };
+    summary: string;
+    actionableRecommendations: string[];
+}
+export interface CroAuditInput {
+    html: string;
+    url?: string;
+}
+export declare class CroHeuristicAuditor {
+    static audit(input: CroAuditInput): CroAuditReport;
+}