@lynxflow/seo-engine 1.2.0 → 1.4.0

package/dist/engine.d.ts

@@ -21,6 +21,7 @@ import { AiCopilotClient } from "./ai-copilot-client";
 import { LagoTokenMeter } from "./lago-token-meter";
 import { SiteAuditor } from "./site-auditor";
 import { SchemaGraphBuilder } from "./schema-builder";
+import { DeepCrawlerAuditor, type SiteAuditSummary, type CrawlOptions } from "./site-crawler";
 export type EngineConfig = LynxSeoConfig;
 export declare class LynxSeoEngine {
     private config;
@@ -32,6 +33,7 @@ export declare class LynxSeoEngine {
     readonly ai: AiCopilotClient;
     readonly tokenMeter: LagoTokenMeter;
     readonly auditor: typeof SiteAuditor;
+    readonly crawler: typeof DeepCrawlerAuditor;
     readonly schema: typeof SchemaGraphBuilder;
     readonly indexNow: typeof IndexNowClient;
     constructor(config: LynxSeoConfig);
@@ -61,6 +63,8 @@ export declare class LynxSeoEngine {
     private buildIndustryPage;
     private buildRolePage;
     private buildIntegrationPage;
+    private buildUseCasePage;
+    private buildToolPage;
     private assemblePage;
     /**
      * Returns the exact count of distinct unique programmatic pages currently active.
@@ -70,4 +74,8 @@ export declare class LynxSeoEngine {
      * Returns the list of all distinct unique URL paths generated so far.
      */
     getUniquePageList(): string[];
+    /**
+     * Performs an automated deep crawl and technical SEO audit of the configured domain.
+     */
+    crawlSite(options?: CrawlOptions): Promise<SiteAuditSummary>;
 }

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from "./token-quota-manager";
 export * from "./lago-token-meter";
 export * from "./indexnow-client";
 export * from "./site-auditor";
+export * from "./site-crawler";
 export * from "./schema-builder";
 export * from "./analytics-client";
 export * from "./serp-client";
@@ -27,6 +28,7 @@ import { TokenQuotaManager } from "./token-quota-manager";
 import { LagoTokenMeter, HyperswitchGateway } from "./lago-token-meter";
 import { IndexNowClient } from "./indexnow-client";
 import { SiteAuditor } from "./site-auditor";
+import { DeepCrawlerAuditor } from "./site-crawler";
 import { SchemaGraphBuilder } from "./schema-builder";
 export declare function createLynxSeoEngine(config: EngineConfig): LynxSeoEngine;
 export declare const LynxSeo: {
@@ -37,6 +39,8 @@ export declare const LynxSeo: {
     createHyperswitchGateway: (apiKey: string, baseUrl?: string) => HyperswitchGateway;
     submitToIndexNow: typeof IndexNowClient.submitUrls;
     inspectMeta: typeof SiteAuditor.inspectMeta;
+    crawlDomain: typeof DeepCrawlerAuditor.crawlAndAuditDomain;
+    inspectHtmlSnapshot: typeof DeepCrawlerAuditor.inspectHtmlSnapshot;
     buildSchemaGraph: typeof SchemaGraphBuilder.buildGraph;
 };
 export default LynxSeo;

package/dist/index.js

@@ -995,6 +995,295 @@ class SchemaGraphBuilder {
   }
 }
 
+// src/site-crawler.ts
+class DeepCrawlerAuditor {
+  static DEFAULT_USER_AGENT = "LynxFlowSeoBot/1.2 (+https://lynxintel.io/bot; technical audit)";
+  static inspectHtmlSnapshot(url, html, statusCode = 200, responseTimeMs = 45) {
+    const issues = [];
+    if (statusCode >= 400 && statusCode < 500) {
+      issues.push({
+        url,
+        type: "broken_page_404",
+        severity: "critical",
+        message: `HTTP Client Error: Page returned ${statusCode}`,
+        recommendation: "Fix broken link or configure a 301 permanent redirect to a relevant page."
+      });
+    } else if (statusCode >= 500) {
+      issues.push({
+        url,
+        type: "server_error_500",
+        severity: "critical",
+        message: `HTTP Server Error: Page returned ${statusCode}`,
+        recommendation: "Inspect server logs and resolve backend application crash."
+      });
+    }
+    const titleMatch = html.match(/<title[^>]*>([^<]*)<\/title>/i);
+    const title = titleMatch ? titleMatch[1].trim() : null;
+    if (!title) {
+      issues.push({
+        url,
+        type: "missing_title",
+        severity: "critical",
+        message: "Missing <title> tag.",
+        recommendation: "Add an explicit, compelling <title> between 30 and 60 characters."
+      });
+    } else if (title.length < 20) {
+      issues.push({
+        url,
+        type: "short_title",
+        severity: "warning",
+        message: `Title is too short (${title.length} chars): "${title}"`,
+        recommendation: "Expand title to at least 30 characters including primary keyword and brand name."
+      });
+    } else if (title.length > 70) {
+      issues.push({
+        url,
+        type: "long_title",
+        severity: "warning",
+        message: `Title is too long (${title.length} chars), risk of SERP truncation.`,
+        recommendation: "Keep title under 60-65 characters for optimal desktop & mobile display."
+      });
+    }
+    const descMatch = html.match(/<meta[^>]*name=["']description["'][^>]*content=["']([^"']*)["'][^>]*>/i) || html.match(/<meta[^>]*content=["']([^"']*)["'][^>]*name=["']description["'][^>]*>/i);
+    const description = descMatch ? descMatch[1].trim() : null;
+    if (!description) {
+      issues.push({
+        url,
+        type: "missing_meta_description",
+        severity: "critical",
+        message: "Missing meta description.",
+        recommendation: "Add a compelling meta description between 120 and 160 characters with clear call-to-action."
+      });
+    } else if (description.length < 70) {
+      issues.push({
+        url,
+        type: "short_meta_description",
+        severity: "warning",
+        message: `Meta description is too short (${description.length} chars).`,
+        recommendation: "Expand meta description to at least 120 characters."
+      });
+    } else if (description.length > 180) {
+      issues.push({
+        url,
+        type: "long_meta_description",
+        severity: "info",
+        message: `Meta description exceeds 180 chars (${description.length} chars).`,
+        recommendation: "Shorten meta description to 155-160 characters."
+      });
+    }
+    const h1Matches = Array.from(html.matchAll(/<h1[^>]*>([^<]*)<\/h1>/gi)).map((m) => m[1].trim());
+    const h1Count = h1Matches.length;
+    const h1 = h1Count > 0 ? h1Matches[0] : null;
+    if (h1Count === 0) {
+      issues.push({
+        url,
+        type: "missing_h1",
+        severity: "critical",
+        message: "Missing <h1> headline.",
+        recommendation: "Add exactly one descriptive <h1> headline containing your target keyword."
+      });
+    } else if (h1Count > 1) {
+      issues.push({
+        url,
+        type: "multiple_h1",
+        severity: "warning",
+        message: `Found ${h1Count} <h1> tags on the page.`,
+        recommendation: "Use only one single <h1> per page and structure other sections with <h2>/<h3>."
+      });
+    }
+    const canonicalMatch = html.match(/<link[^>]*rel=["']canonical["'][^>]*href=["']([^"']*)["'][^>]*>/i);
+    const canonical = canonicalMatch ? canonicalMatch[1].trim() : null;
+    const isCanonicalMatch = canonical ? canonical.replace(/\/$/, "") === url.replace(/\/$/, "") : false;
+    if (!canonical) {
+      issues.push({
+        url,
+        type: "missing_canonical",
+        severity: "warning",
+        message: "Missing self-referencing canonical tag.",
+        recommendation: "Add a <link rel='canonical' href='...' /> tag to prevent duplicate content indexation."
+      });
+    }
+    const imgMatches = Array.from(html.matchAll(/<img([^>]*)>/gi));
+    let imagesWithoutAlt = 0;
+    for (const match of imgMatches) {
+      const imgTag = match[1];
+      if (!/alt=["'][^"']+["']/i.test(imgTag)) {
+        imagesWithoutAlt++;
+      }
+    }
+    if (imagesWithoutAlt > 0) {
+      issues.push({
+        url,
+        type: "images_missing_alt",
+        severity: "warning",
+        message: `${imagesWithoutAlt} image(s) missing descriptive 'alt' attribute.`,
+        recommendation: "Add descriptive ALT text for SEO image search and accessibility compliance."
+      });
+    }
+    const cleanText = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    const wordCount = cleanText.split(" ").filter((w) => w.length > 1).length;
+    if (wordCount < 150 && statusCode === 200) {
+      issues.push({
+        url,
+        type: "thin_content",
+        severity: "warning",
+        message: `Thin content detected (${wordCount} words).`,
+        recommendation: "Expand content to at least 300-500 words to provide authoritative value."
+      });
+    }
+    const linkMatches = Array.from(html.matchAll(/<a[^>]*href=["']([^"']*)["'][^>]*>/gi));
+    let internalLinksCount = 0;
+    let externalLinksCount = 0;
+    for (const match of linkMatches) {
+      const href = match[1];
+      if (href.startsWith("http://") || href.startsWith("https://")) {
+        try {
+          const targetHost = new URL(href).hostname;
+          const currentHost = new URL(url).hostname;
+          if (targetHost === currentHost)
+            internalLinksCount++;
+          else
+            externalLinksCount++;
+        } catch {
+          externalLinksCount++;
+        }
+      } else if (href.startsWith("/") || href.startsWith("#") || href.startsWith(".")) {
+        internalLinksCount++;
+      }
+    }
+    return {
+      url,
+      statusCode,
+      responseTimeMs,
+      title,
+      description,
+      h1,
+      h1Count,
+      canonical,
+      isCanonicalMatch,
+      wordCount,
+      imagesWithoutAlt,
+      internalLinksCount,
+      externalLinksCount,
+      issues
+    };
+  }
+  static async crawlAndAuditDomain(targetUrl, options = {}) {
+    const t0 = performance.now();
+    const maxPages = options.maxPages || 30;
+    const timeoutMs = options.timeoutMs || 8000;
+    const userAgent = options.userAgent || this.DEFAULT_USER_AGENT;
+    const baseDomain = targetUrl.replace(/\/$/, "");
+    const baseHost = new URL(baseDomain).hostname;
+    const visited = new Set;
+    const queue = [baseDomain];
+    const crawledPages = [];
+    const brokenLinks404 = [];
+    const redirectChains = [];
+    while (queue.length > 0 && crawledPages.length < maxPages) {
+      const currentUrl = queue.shift();
+      const normalized = currentUrl.replace(/\/$/, "");
+      if (visited.has(normalized))
+        continue;
+      visited.add(normalized);
+      try {
+        const fetchStart = performance.now();
+        const controller = new AbortController;
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const res = await fetch(currentUrl, {
+          signal: controller.signal,
+          headers: { "User-Agent": userAgent }
+        });
+        clearTimeout(timeoutId);
+        const fetchTimeMs = Math.round(performance.now() - fetchStart);
+        const statusCode = res.status;
+        if (statusCode === 404) {
+          brokenLinks404.push(currentUrl);
+        }
+        if (res.redirected && res.url !== currentUrl) {
+          redirectChains.push({ source: currentUrl, target: res.url, statusCode });
+        }
+        const html = await res.text();
+        const pageAudit = this.inspectHtmlSnapshot(currentUrl, html, statusCode, fetchTimeMs);
+        crawledPages.push(pageAudit);
+        const hrefMatches = Array.from(html.matchAll(/<a[^>]*href=["']([^"'#]+)["']/gi));
+        for (const match of hrefMatches) {
+          const rawHref = match[1].trim();
+          try {
+            const resolved = new URL(rawHref, currentUrl).href.replace(/\/$/, "");
+            const parsed = new URL(resolved);
+            if (parsed.hostname === baseHost && !visited.has(resolved) && !queue.includes(resolved)) {
+              if (!/\.(png|jpg|jpeg|gif|svg|webp|css|js|pdf|zip)$/i.test(parsed.pathname)) {
+                queue.push(resolved);
+              }
+            }
+          } catch {}
+        }
+      } catch (err) {
+        crawledPages.push({
+          url: currentUrl,
+          statusCode: 0,
+          responseTimeMs: 0,
+          title: null,
+          description: null,
+          h1: null,
+          h1Count: 0,
+          canonical: null,
+          isCanonicalMatch: false,
+          wordCount: 0,
+          imagesWithoutAlt: 0,
+          internalLinksCount: 0,
+          externalLinksCount: 0,
+          issues: [{
+            url: currentUrl,
+            type: "fetch_timeout_error",
+            severity: "critical",
+            message: `Connection Error: ${err?.message || "Failed to reach server"}`,
+            recommendation: "Ensure server is reachable and responds in under 5 seconds."
+          }]
+        });
+      }
+    }
+    let criticalCount = 0;
+    let warningCount = 0;
+    let infoCount = 0;
+    for (const p of crawledPages) {
+      for (const iss of p.issues) {
+        if (iss.severity === "critical")
+          criticalCount++;
+        else if (iss.severity === "warning")
+          warningCount++;
+        else
+          infoCount++;
+      }
+    }
+    const totalPages = Math.max(1, crawledPages.length);
+    const penalty = (criticalCount * 12 + warningCount * 4 + infoCount * 1) / totalPages;
+    const healthScore = Math.max(10, Math.min(100, Math.round(100 - penalty)));
+    const categories = {
+      metaAndTags: Math.max(20, Math.min(100, Math.round(100 - (criticalCount * 8 + warningCount * 3) / totalPages))),
+      contentQuality: Math.max(30, Math.min(100, Math.round(100 - warningCount * 5 / totalPages))),
+      indexingAndLinks: Math.max(25, Math.min(100, Math.round(100 - brokenLinks404.length * 15 / totalPages))),
+      performanceAndStatus: Math.max(40, Math.min(100, Math.round(100 - criticalCount * 10 / totalPages)))
+    };
+    return {
+      domain: baseDomain,
+      crawledPagesCount: crawledPages.length,
+      healthScore,
+      categories,
+      totalIssues: {
+        critical: criticalCount,
+        warning: warningCount,
+        info: infoCount
+      },
+      brokenLinks404,
+      redirectChains,
+      pages: crawledPages,
+      executionTimeMs: Math.round(performance.now() - t0)
+    };
+  }
+}
+
 // src/engine.ts
 class LynxSeoEngine {
   config;
@@ -1006,6 +1295,7 @@ class LynxSeoEngine {
   ai;
   tokenMeter;
   auditor = SiteAuditor;
+  crawler = DeepCrawlerAuditor;
   schema = SchemaGraphBuilder;
   indexNow = IndexNowClient;
   constructor(config) {
@@ -1163,12 +1453,14 @@ class LynxSeoEngine {
       return this.buildRolePage(service, remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
     }
     if ((pathParts[0] === "cas-usage" || pathParts[0] === "use-cases") && pathParts.length >= 2) {
-      const { service, remainder } = detectServiceFromSlug(pathParts[1]);
-      return this.buildGeoPage(service, "FR", remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
+      const raw = pathParts[1].replace(/-(pour|for)-/i, "-");
+      const { service, remainder } = detectServiceFromSlug(raw);
+      return this.buildUseCasePage(service, remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
     }
     if ((pathParts[0] === "outils" || pathParts[0] === "tools") && pathParts.length >= 2) {
-      const { service } = detectServiceFromSlug(pathParts[1]);
-      return this.buildGeoPage(service, "FR", "Calculateur ROI", domain, t0, locale, cleanPath);
+      const raw = pathParts[1].replace(/^simulateur-roi-/i, "");
+      const { service, remainder } = detectServiceFromSlug(raw);
+      return this.buildToolPage(service, remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
     }
     return this.buildGeoPage(defaultService, "FR", "Paris", domain, t0, locale, cleanPath);
   }
@@ -1310,6 +1602,41 @@ class LynxSeoEngine {
       t0
     });
   }
+  buildUseCasePage(service, topic, domain, t0, locale = "fr", path = `cas-usage/${topic.toLowerCase().replace(/\s+/g, "-")}`) {
+    const topicName = topic.charAt(0).toUpperCase() + topic.slice(1);
+    const title = `${service.name} pour ${topicName} — ${this.config.brandName}`;
+    const description = `Découvrez comment optimiser vos opérations de ${topicName} avec notre solution ${service.name}. Déploiement en 10 minutes.`;
+    const h1 = `${service.name} : ${topicName}`;
+    const directAnswer = `${this.config.brandName} (${service.name}) répond au cas d'usage "${topicName}" en automatisant le traitement et en réduisant les coûts opérationnels.`;
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0
+    });
+  }
+  buildToolPage(service, tool, domain, t0, locale = "fr", path = `outils/${tool.toLowerCase().replace(/\s+/g, "-")}`) {
+    const title = `Simulateur & Calculateur ROI : ${service.name} — ${this.config.brandName}`;
+    const description = `Estimez vos gains de productivité et vos économies annuelles grâce à notre calculateur ROI pour ${service.name}.`;
+    const h1 = `Simulateur de Rentabilité & ROI : ${service.name}`;
+    const directAnswer = `Utilisez le simulateur ROI de ${this.config.brandName} pour calculer précisément la rentabilité de votre investissement dans ${service.name} (amortissement en moins de 30 jours).`;
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0
+    });
+  }
   assemblePage(opts) {
     const dict = getDictionary(opts.locale);
     const domain = this.config.domain.replace(/\/$/, "");
@@ -1428,6 +1755,9 @@ ${opts.description}
     const rawKey = this.config.apiKey || this.config.licenseKey || "";
     return ApiKeyGuardian.getUniquePageList(rawKey);
   }
+  async crawlSite(options) {
+    return DeepCrawlerAuditor.crawlAndAuditDomain(this.config.domain, options);
+  }
 }
 // src/index.ts
 function createLynxSeoEngine(config) {
@@ -1441,6 +1771,8 @@ var LynxSeo = {
   createHyperswitchGateway: (apiKey, baseUrl) => new HyperswitchGateway({ apiKey, baseUrl }),
   submitToIndexNow: IndexNowClient.submitUrls,
   inspectMeta: SiteAuditor.inspectMeta,
+  crawlDomain: DeepCrawlerAuditor.crawlAndAuditDomain,
+  inspectHtmlSnapshot: DeepCrawlerAuditor.inspectHtmlSnapshot,
   buildSchemaGraph: SchemaGraphBuilder.buildGraph
 };
 var src_default = LynxSeo;
@@ -1457,6 +1789,7 @@ export {
   LagoTokenMeter,
   IndexNowClient,
   HyperswitchGateway,
+  DeepCrawlerAuditor,
   BacklinksClient,
   ApiKeyGuardian,
   AiCopilotClient