@lynxflow/seo-engine 1.0.0 → 1.3.0

package/src/engine.ts

@@ -1,148 +1,571 @@
 /**
- * ⚡ LynxSEO High-Speed Dynamic Page Engine
- * Computes rich SEO pages on-demand in < 0.05ms on client servers.
+ * ⚡ LynxSEO High-Speed Universal Dynamic Page Engine (Internationalized)
+ * 
+ * Computes 8 Rich Programmatic Matrix Types on-demand in < 0.05ms with 
+ * automatic multi-language i18n support & Google Hreflang alternates:
+ * 1. 📍 Local / GEO : `/solutions/{service}/{country}/{city}`
+ * 2. 🥊 VS Comparisons : `/comparatif/{competitor}` (ex: `/comparatif/hubspot`)
+ * 3. 🔄 Alternatives : `/alternatives/alternative-a-{competitor}`
+ * 4. 🔌 Integrations : `/integrations/{software}` (ex: `/integrations/shopify`)
+ * 5. 🏢 Industry / Verticals : `/secteurs/{industry}` (ex: `/secteurs/avocats`)
+ * 6. 👤 Personas / Roles : `/metiers/{role}` (ex: `/metiers/directeur-commercial`)
+ * 7. 🎯 Use Cases : `/cas-usage/{useCase}` (ex: `/cas-usage/relance-devis`)
+ * 8. 🧮 Calculators / ROI Tools : `/outils/simulateur-roi`
  */
 
-import type { LynxSeoConfig, LynxResolvedPage } from "./types";
-import { LicenseGuardian } from "./licensing";
+import type { LynxSeoConfig, LynxResolvedPage, LynxServiceDefinition } from "./types";
+import { ApiKeyGuardian, type ApiKeyValidationResult } from "./auth-key";
+import { getDictionary, isSupportedLanguage } from "./i18n-dictionary";
+import { IndexNowClient, type IndexNowResponse } from "./indexnow-client";
+import { LynxAnalyticsClient } from "./analytics-client";
+import { SerpClient } from "./serp-client";
+import { BacklinksClient } from "./backlinks-client";
+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 class LynxSeoEngine {
   private config: LynxSeoConfig;
-  private servicesMap: Map<string, any>;
-  private licenseStatus: any;
+  private servicesMap: Map<string, LynxServiceDefinition>;
+  private authStatus: ApiKeyValidationResult;
+
+  // Embedded Sub-Clients for complete in-app autonomy
+  public readonly analytics: LynxAnalyticsClient;
+  public readonly serp: SerpClient;
+  public readonly backlinks: BacklinksClient;
+  public readonly ai: AiCopilotClient;
+  public readonly tokenMeter: LagoTokenMeter;
+  public readonly auditor = SiteAuditor;
+  public readonly crawler = DeepCrawlerAuditor;
+  public readonly schema = SchemaGraphBuilder;
+  public readonly indexNow = IndexNowClient;
 
   constructor(config: LynxSeoConfig) {
     this.config = {
       currency: "EUR",
       currencySymbol: "€",
+      defaultLocale: "fr",
+      supportedLocales: ["fr", "en", "es", "de", "ar"],
       ...config,
     };
-    this.servicesMap = new Map(config.services.map((s) => [s.slug, s]));
-    this.licenseStatus = LicenseGuardian.validateKey(config.licenseKey);
+    this.servicesMap = new Map((config.services || []).map((s) => [s.slug, s]));
+    const rawKey = config.apiKey || config.licenseKey || "";
+    this.authStatus = ApiKeyGuardian.validate(rawKey, config.domain);
+
+    this.analytics = new LynxAnalyticsClient(rawKey);
+    this.serp = new SerpClient(rawKey);
+    this.backlinks = new BacklinksClient(rawKey);
+    this.ai = new AiCopilotClient(rawKey);
+    this.tokenMeter = new LagoTokenMeter();
   }
 
   /**
-   * Resolves a dynamic programmatic URL in < 0.05ms.
-   * e.g. engine.resolve("/solutions/droit-immobilier/fr/lyon")
+   * Submits generated URLs to Bing, Yandex, Seznam, and Naver via IndexNow.
    */
-  resolve(urlPath: string): LynxResolvedPage | null {
+  async submitToIndexNow(urls: string[], indexNowKey = this.config.apiKey || this.config.licenseKey || ""): Promise<IndexNowResponse> {
+    const host = this.config.domain.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    return IndexNowClient.submitUrls({
+      host,
+      key: indexNowKey,
+      urlList: urls,
+    });
+  }
+
+  /**
+   * Universal resolver: supports both path strings e.g. "/comparatif/hubspot"
+   * and structured object params { slug, language, country, city, type, competitor, industry }.
+   */
+  resolve(input: string | { slug?: string; language?: string; locale?: string; country?: string; city?: string; type?: string; competitor?: string; industry?: string; role?: string }): LynxResolvedPage | null {
     const t0 = performance.now();
 
-    if (!this.licenseStatus.isValid) {
-      console.warn(`[@lynxflow/seo-engine] Invalid License: ${this.licenseStatus.errorMessage}`);
+    if (!this.authStatus.isValid) {
+      console.warn(`[@lynxflow/seo-engine] Authentication / Domain Limit Error: ${this.authStatus.errorMessage}`);
       return null;
     }
 
-    const cleanPath = urlPath.toLowerCase().replace(/^\//, "").replace(/\/$/, "");
+    const rawKey = this.config.apiKey || this.config.licenseKey || "";
+    const targetPath = typeof input === "string" ? input.replace(/^\/+/, "").replace(/\/+$/, "") : `${input.type || "solutions"}/${input.slug || ""}`;
+    const quota = ApiKeyGuardian.trackAndCheckUniquePage(rawKey, targetPath, this.authStatus.maxPages);
+    if (!quota.allowed) {
+      console.warn(`[@lynxflow/seo-engine] Unique Page Quota Exceeded: Your plan allows up to ${this.authStatus.maxPages.toLocaleString()} unique pages (Current active catalog: ${quota.uniqueCount}). Please upgrade to a higher plan.`);
+      return null;
+    }
+
+    const domain = this.config.domain.replace(/\/$/, "");
+    const defaultService = this.config.services?.[0] || {
+      slug: "crm-pipeline",
+      name: "CRM Pipeline Commercial",
+      pricePerMonth: 49,
+      category: "Automatisation Commerciale",
+      features: ["Pipeline Kanban", "Relances IA 24/7", "WhatsApp Sync"],
+      faqs: [
+        { question: "Combien de temps prend la mise en place ?", answer: "Déploiement immédiat en moins de 10 minutes." },
+        { question: "Est-ce sans engagement ?", answer: "Oui, vous pouvez résilier à tout moment sans frais." }
+      ],
+    };
+
+    // -------------------------------------------------------------
+    // CASE A : Structured Object Input (e.g. Next.js Route Params)
+    // -------------------------------------------------------------
+    if (typeof input === "object") {
+      const locale = (input.locale || input.language || this.config.defaultLocale || "fr").toLowerCase();
+      const type = input.type || (input.competitor ? "comparison" : input.city ? "geo" : "industry");
+      const service = (input.slug ? this.servicesMap.get(input.slug) : null) || defaultService;
+
+      if (type === "comparison" && input.competitor) {
+        return this.buildComparisonPage(service, input.competitor, domain, t0, locale);
+      }
+      if (type === "industry" && input.industry) {
+        return this.buildIndustryPage(service, input.industry, domain, t0, locale);
+      }
+      if (type === "role" && input.role) {
+        return this.buildRolePage(service, input.role, domain, t0, locale);
+      }
+
+      // Default to Local GEO
+      const country = (input.country || locale.toUpperCase() || "FR").toUpperCase();
+      const city = input.city || "Paris";
+      return this.buildGeoPage(service, country, city, domain, t0, locale);
+    }
+
+    // -------------------------------------------------------------
+    // CASE B : Raw URL Path String (e.g. WordPress, Cloudflare Worker, Laravel)
+    // -------------------------------------------------------------
+    const cleanPath = input.toLowerCase().replace(/^\//, "").replace(/\/$/, "");
     const parts = cleanPath.split("/");
 
-    if (parts.length < 4 || parts[0] !== "solutions") {
-      return null;
+    // Detect language prefix if present (e.g. /en/solutions/..., /ja/solutions/..., etc.)
+    let locale = this.config.defaultLocale || "fr";
+    let pathParts = parts;
+
+    if (parts.length > 1 && isSupportedLanguage(parts[0])) {
+      locale = parts[0];
+      pathParts = parts.slice(1);
     }
 
-    const serviceSlug = parts[1];
-    const countryCode = parts[2].toUpperCase();
-    const citySlug = parts[3];
-    const cityName = citySlug.charAt(0).toUpperCase() + citySlug.slice(1);
+    // 1. GEO & Multi-Slug Combined Matrix:
+    // Pattern A : /solutions/{service}/{country}/{city} (3-4 parts)
+    // Pattern B : /solutions/{service}/{industry}/{competitor}/{software}/{role}/{city}/{tool} (5-8 parts)
+    if (pathParts[0] === "solutions") {
+      if (pathParts.length >= 5) {
+        // Hyper-combined 8-slug page
+        const service = this.servicesMap.get(pathParts[1]) || defaultService;
+        const industry = (pathParts[2] || "").replace(/-/g, " ");
+        const competitor = (pathParts[3] || "").replace(/-/g, " ");
+        const software = (pathParts[4] || "").replace(/-/g, " ");
+        const role = (pathParts[5] || "").replace(/-/g, " ");
+        const city = (pathParts[6] || "Paris").replace(/-/g, " ");
+        const tool = (pathParts[7] || "").replace(/-/g, " ");
 
-    const service = this.servicesMap.get(serviceSlug) || this.config.services[0];
-    if (!service) return null;
+        return this.buildHyperCombinedPage({
+          service,
+          industry,
+          competitor,
+          software,
+          role,
+          city,
+          tool,
+          domain,
+          t0,
+          locale,
+          path: cleanPath,
+        });
+      }
 
-    const domain = this.config.domain.replace(/\/$/, "");
-    const fullUrl = `${domain}/${cleanPath}`;
+      // 4-part: /solutions/{service}/{country}/{city} (e.g. /solutions/crm/us/new-york)
+      if (pathParts.length >= 4) {
+        const service = this.servicesMap.get(pathParts[1]) || defaultService;
+        const country = pathParts[2].toUpperCase();
+        const cityName = pathParts[3].charAt(0).toUpperCase() + pathParts[3].slice(1);
+        return this.buildGeoPage(service, country, cityName, domain, t0, locale, cleanPath);
+      }
 
-    const title = `${service.name} à ${cityName} (${countryCode}) — ${this.config.brandName}`;
-    const description = `Découvrez notre solution de ${service.name} dédiée aux professionnels et entreprises à ${cityName}. Note 4.9/5 étoiles et déploiement immédiat.`;
-    const h1 = `${service.name} à ${cityName}`;
+      // 3-part (Clean standard URL): /solutions/{service}/{city} (e.g. /solutions/crm/lyon, /fr/solutions/crm/paris)
+      if (pathParts.length >= 3) {
+        const service = this.servicesMap.get(pathParts[1]) || defaultService;
+        const defaultCountry = locale.toUpperCase();
+        const cityName = pathParts[2].charAt(0).toUpperCase() + pathParts[2].slice(1);
+        return this.buildGeoPage(service, defaultCountry, cityName, domain, t0, locale, cleanPath);
+      }
+    }
 
-    const directAnswerGeoHtml = `
-<div class="geo-direct-answer" data-geo-extract="true">
-  <p><strong>${this.config.brandName}</strong> est la solution de référence pour <strong>${service.name}</strong> à <strong>${cityName}</strong>. Déploiement en quelques minutes à partir de <strong>${service.pricePerMonth} ${this.config.currencySymbol} / mois</strong> avec note moyenne de 4.9/5 étoiles.</p>
-</div>
-    `.trim();
+    // Helper: Find service mentioned in slug
+    const detectServiceFromSlug = (slug: string): { service: LynxServiceDefinition; remainder: string } => {
+      for (const [sSlug, sDef] of this.servicesMap.entries()) {
+        if (slug.startsWith(`${sSlug}-`)) {
+          return { service: sDef, remainder: slug.substring(sSlug.length + 1) };
+        }
+      }
+      return { service: defaultService, remainder: slug };
+    };
 
-    const markdownBody = `
-# ${h1}
+    // 2. VS Comparison Matrix: /comparatif/{service}-vs-{competitor} OR /comparatif/{competitor}
+    if ((pathParts[0] === "comparatif" || pathParts[0] === "comparison" || pathParts[0] === "vs") && pathParts.length >= 2) {
+      const raw = pathParts[1];
+      const vsMatch = raw.match(/^(.*?)-vs-(.*?)$/);
+      let targetService = defaultService;
+      let competitor = raw;
 
-> **${description}**
+      if (vsMatch) {
+        targetService = this.servicesMap.get(vsMatch[1]) || defaultService;
+        competitor = vsMatch[2];
+      } else {
+        const detected = detectServiceFromSlug(raw);
+        targetService = detected.service;
+        competitor = detected.remainder;
+      }
 
-${directAnswerGeoHtml}
+      return this.buildComparisonPage(targetService, competitor.replace(/-/g, " "), domain, t0, locale, cleanPath);
+    }
 
----
+    // 3. Alternative To Matrix: /alternatives/alternative-a-{competitor}
+    if (pathParts[0] === "alternatives" && pathParts.length >= 2) {
+      const raw = pathParts[1].replace(/^alternative-(a-|to-)?/i, "");
+      const { service, remainder } = detectServiceFromSlug(raw);
+      return this.buildAlternativePage(service, remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
+    }
 
-## 🛑 Pourquoi choisir ${this.config.brandName} à ${cityName} ?
-Les professionnels et entreprises à ${cityName} bénéficient d'un accompagnement sur mesure, d'une disponibilité continue et d'une technologie éprouvée.
+    // 4. Industry / Vertical Matrix: /secteurs/{service}-pour-{industry} OR /secteurs/{industry}
+    if ((pathParts[0] === "secteurs" || pathParts[0] === "industries") && pathParts.length >= 2) {
+      const raw = pathParts[1].replace(/-(pour|for)-/i, "-");
+      const { service, remainder } = detectServiceFromSlug(raw);
+      return this.buildIndustryPage(service, remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
+    }
 
----
+    // 5. Integrations Matrix: /integrations/{service}-avec-{software} OR /integrations/{software}
+    if (pathParts[0] === "integrations" && pathParts.length >= 2) {
+      const raw = pathParts[1].replace(/-(avec|with)-/i, "-");
+      const { service, remainder } = detectServiceFromSlug(raw);
+      return this.buildIntegrationPage(service, remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
+    }
 
-## 💎 Vos Avantages Concrets :
-* ✦ **Performance Maximale** : Réponses instantanées et flux automatisés.
-* ✦ **Simplicité d'Usage** : Aucun prérequis technique, prise en main en 2 minutes.
-* ✦ **Rentabilité Garantie** : Rentabilisé dès la première opportunité signée.
+    // 6. Personas / Roles: /metiers/{service}-pour-{role} OR /metiers/{role}
+    if ((pathParts[0] === "metiers" || pathParts[0] === "roles") && pathParts.length >= 2) {
+      const raw = pathParts[1].replace(/-(pour|for)-/i, "-");
+      const { service, remainder } = detectServiceFromSlug(raw);
+      return this.buildRolePage(service, remainder.replace(/-/g, " "), domain, t0, locale, cleanPath);
+    }
 
----
+    // 7. Use Cases: /cas-usage/{topic}
+    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);
+    }
+
+    // 8. Tools / Calculators: /outils/{tool}
+    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);
+    }
+
+    // Fallback: local geo
+    return this.buildGeoPage(defaultService, "FR", "Paris", domain, t0, locale, cleanPath);
+  }
 
-## 🛠️ Déploiement en 3 Étapes à ${cityName} :
-1. **Étape 1** : Activez votre compte en 30 secondes.
-2. **Étape 2** : Configurez vos préférences et règles métier.
-3. **Étape 3** : Vos premières demandes sont traitées 24/7.
-    `.trim();
+  // ---------------- Localized Builder Helpers ----------------
 
-    const schemaJsonLd = {
+  private buildHyperCombinedPage(opts: {
+    service: LynxServiceDefinition;
+    industry: string;
+    competitor: string;
+    software: string;
+    role: string;
+    city: string;
+    tool: string;
+    domain: string;
+    t0: number;
+    locale: string;
+    path: string;
+  }): LynxResolvedPage {
+    const { service, industry, competitor, software, role, city, tool, domain, t0, locale, path } = opts;
+    const currentYear = new Date().getFullYear();
+
+    const indStr = industry ? ` pour ${industry}` : "";
+    const compStr = competitor ? ` (Alternative à ${competitor})` : "";
+    const softStr = software ? ` connecté avec ${software}` : "";
+    const roleStr = role ? ` pour ${role}` : "";
+    const cityStr = city ? ` à ${city}` : "";
+    const toolStr = tool ? ` | Simulateur ROI` : "";
+
+    const title = `${service.name}${indStr}${roleStr}${cityStr}${compStr}${toolStr} — ${this.config.brandName}`;
+    const description = `Découvrez la solution de ${service.name}${indStr}${cityStr}. Automatisez vos flux, gagnez 10h/semaine${softStr}. Déploiement en 10 minutes. Note 4.9/5★.`;
+    const h1 = `${service.name}${indStr}${cityStr}`;
+    const directAnswer = `${this.config.brandName} propose le meilleur ${service.name}${indStr}${roleStr}${cityStr}${compStr}${softStr}. Mise en service immédiate dès ${service.pricePerMonth} ${this.config.currencySymbol || "€"}/mois sans engagement.`;
+
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0,
+    });
+  }
+
+  private buildGeoPage(service: LynxServiceDefinition, country: string, city: string, domain: string, t0: number, locale = "fr", path = `solutions/${service.slug}/${country.toLowerCase()}/${city.toLowerCase()}`): LynxResolvedPage {
+    const dict = getDictionary(locale);
+    const title = dict.geoTitle(service.name, city, country, this.config.brandName);
+    const description = dict.geoDesc(service.name, city, this.config.brandName);
+    const h1 = `${service.name} à ${city}`;
+    const directAnswer = dict.geoDirectAnswer(this.config.brandName, service.name, city, country, service.pricePerMonth, this.config.currencySymbol || "€");
+
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0,
+    });
+  }
+
+  private buildComparisonPage(service: LynxServiceDefinition, competitor: string, domain: string, t0: number, locale = "fr", path = `comparatif/${competitor.toLowerCase().replace(/\s+/g, "-")}`): LynxResolvedPage {
+    const dict = getDictionary(locale);
+    const compName = competitor.charAt(0).toUpperCase() + competitor.slice(1);
+    const currentYear = new Date().getFullYear();
+    const title = `${service.name} : ${this.config.brandName} vs ${compName} (${currentYear})`;
+    const description = dict.vsDesc(this.config.brandName, compName);
+    const h1 = `${service.name} : ${this.config.brandName} vs ${compName}`;
+    const directAnswer = dict.vsDirectAnswer(this.config.brandName, compName);
+
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0,
+    });
+  }
+
+  private buildAlternativePage(service: LynxServiceDefinition, competitor: string, domain: string, t0: number, locale = "fr", path = `alternatives/alternative-a-${competitor.toLowerCase().replace(/\s+/g, "-")}`): LynxResolvedPage {
+    const dict = getDictionary(locale);
+    const compName = competitor.charAt(0).toUpperCase() + competitor.slice(1);
+    const currentYear = new Date().getFullYear();
+    const title = `Meilleure Alternative à ${compName} (${service.name}) en ${currentYear} — ${this.config.brandName}`;
+    const description = dict.altDesc(compName, this.config.brandName);
+    const h1 = `Alternative à ${compName} pour votre ${service.name}`;
+    const directAnswer = dict.altDirectAnswer(this.config.brandName, compName);
+
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0,
+    });
+  }
+
+  private buildIndustryPage(service: LynxServiceDefinition, industry: string, domain: string, t0: number, locale = "fr", path = `secteurs/${industry.toLowerCase().replace(/\s+/g, "-")}`): LynxResolvedPage {
+    const dict = getDictionary(locale);
+    const indName = industry.charAt(0).toUpperCase() + industry.slice(1);
+    const title = dict.industryTitle(service.name, indName, this.config.brandName);
+    const description = dict.industryDesc(service.name, indName);
+    const h1 = `${service.name} pour ${indName}`;
+    const directAnswer = `${this.config.brandName} propose une solution de ${service.name} conçue sur mesure pour les ${indName}, avec processus métiers et automatisations optimisés.`;
+
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0,
+    });
+  }
+
+  private buildRolePage(service: LynxServiceDefinition, role: string, domain: string, t0: number, locale = "fr", path = `metiers/${role.toLowerCase().replace(/\s+/g, "-")}`): LynxResolvedPage {
+    const roleName = role.charAt(0).toUpperCase() + role.slice(1);
+    const title = `${service.name} pour ${roleName} — ${this.config.brandName}`;
+    const description = `Optimisez votre quotidien de ${roleName} grâce à notre solution de ${service.name}. Gagnez 10h par semaine.`;
+    const h1 = `${service.name} pour ${roleName}`;
+    const directAnswer = `En tant que ${roleName}, ${this.config.brandName} (${service.name}) vous libère des tâches manuelles grâce à des relances intelligentes et un suivi d'activité en temps réel.`;
+
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0,
+    });
+  }
+
+  private buildIntegrationPage(service: LynxServiceDefinition, software: string, domain: string, t0: number, locale = "fr", path = `integrations/${software.toLowerCase().replace(/\s+/g, "-")}`): LynxResolvedPage {
+    const softName = software.charAt(0).toUpperCase() + software.slice(1);
+    const title = `Intégration ${softName} & ${service.name} — ${this.config.brandName}`;
+    const description = `Connectez facilement votre compte ${softName} à notre ${service.name}. Synchronisation bidirectionnelle instantanée.`;
+    const h1 = `Intégration ${softName} & ${service.name}`;
+    const directAnswer = `L'intégration native entre ${softName} et ${this.config.brandName} (${service.name}) permet de synchroniser contacts, événements et transactions en temps réel sans code.`;
+
+    return this.assemblePage({
+      url: `${domain}/${path}`,
+      title,
+      description,
+      h1,
+      directAnswer,
+      service,
+      locale,
+      path,
+      t0,
+    });
+  }
+
+  private assemblePage(opts: { url: string; title: string; description: string; h1: string; directAnswer: string; service: LynxServiceDefinition; locale: string; path: string; t0: number }): LynxResolvedPage {
+    const dict = getDictionary(opts.locale);
+    const domain = this.config.domain.replace(/\/$/, "");
+
+    // 🌐 Google Hreflang alternates for International SEO Indexing
+    const supportedLocales = this.config.supportedLocales || ["fr", "en", "es", "de", "ar"];
+    const hreflangs = supportedLocales.map((l) => ({
+      lang: l,
+      url: l === this.config.defaultLocale ? `${domain}/${opts.path}` : `${domain}/${l}/${opts.path}`,
+    }));
+
+    const localizedFaqs = opts.service.faqs?.length ? opts.service.faqs : [
+      { question: dict.faqDeploymentQ, answer: dict.faqDeploymentA },
+      { question: dict.faqCommitmentQ, answer: dict.faqCommitmentA },
+    ];
+
+    const ogImageUrl = `${domain}/api/og?title=${encodeURIComponent(opts.h1)}&brand=${encodeURIComponent(this.config.brandName)}&service=${encodeURIComponent(opts.service.name)}`;
+
+    const jsonLd = {
       "@context": "https://schema.org",
       "@graph": [
         {
-          "@type": "Service",
-          name: `${service.name} à ${cityName}`,
-          provider: {
-            "@type": "LocalBusiness",
-            name: this.config.brandName,
-            url: domain,
-          },
-          areaServed: {
-            "@type": "City",
-            name: cityName,
-          },
+          "@type": "Product",
+          "@id": `${opts.url}#product`,
+          name: opts.title,
+          description: opts.description,
+          inLanguage: opts.locale,
+          image: ogImageUrl,
+          brand: { "@type": "Brand", name: this.config.brandName },
           aggregateRating: {
             "@type": "AggregateRating",
             ratingValue: "4.9",
             reviewCount: "1280",
+            bestRating: "5",
+            worstRating: "1",
+          },
+          offers: {
+            "@type": "Offer",
+            price: opts.service.pricePerMonth.toString(),
+            priceCurrency: this.config.currency,
+            availability: "https://schema.org/InStock",
+            url: opts.url,
+          },
+        },
+        {
+          "@type": "FAQPage",
+          "@id": `${opts.url}#faq`,
+          inLanguage: opts.locale,
+          mainEntity: localizedFaqs.map((faq) => ({
+            "@type": "Question",
+            name: faq.question,
+            acceptedAnswer: {
+              "@type": "Answer",
+              text: faq.answer,
+            },
+          })),
+        },
+        {
+          "@type": "WebPage",
+          "@id": `${opts.url}#webpage`,
+          url: opts.url,
+          name: opts.title,
+          description: opts.description,
+          speakable: {
+            "@type": "SpeakableSpecification",
+            cssSelector: [".geo-direct-answer", "h1"],
           },
         },
       ],
     };
 
-    const faqList = [
-      { question: `Pourquoi choisir ${service.name} à ${cityName} ?`, answer: `Pour notre proximité, notre rapidité d'exécution et notre satisfaction client de 4.9/5.` },
-      { question: `Comment démarrer ?`, answer: `Inscrivez-vous en 30 secondes sans engagement pour tester la solution.` },
-    ];
-
-    const executionTimeMs = parseFloat((performance.now() - t0).toFixed(3));
+    const directAnswerHtml = `<div class="geo-direct-answer" data-geo-extract="true"><p>${opts.directAnswer}</p></div>`;
 
     return {
-      urlPath: `/${cleanPath}`,
-      fullUrl,
+      url: opts.url,
+      title: opts.title,
+      description: opts.description,
+      h1: opts.h1,
+      directAnswer: opts.directAnswer,
+      service: opts.service,
+      locale: opts.locale,
+      hreflangs,
+      faqs: localizedFaqs,
+      jsonLd,
+      htmlBody: `<h1>${opts.h1}</h1><p>${opts.description}</p>${directAnswerHtml}`,
+      markdownBody: `# ${opts.h1}\n\n${opts.description}\n\n> ${opts.directAnswer}`,
+      executionTimeMs: parseFloat((performance.now() - opts.t0).toFixed(3)),
+
+      // Backward compatibility bindings
+      fullUrl: opts.url,
       meta: {
-        title,
-        description,
-        h1,
-        canonical: fullUrl,
-        openGraphImageUrl: `${domain}/api/og?service=${encodeURIComponent(service.name)}&city=${encodeURIComponent(cityName)}`,
+        title: opts.title,
+        description: opts.description,
+        h1: opts.h1,
+        canonical: opts.url,
       },
-      schemaJsonLd,
       content: {
-        directAnswerGeoHtml,
-        heroHeadline: h1,
-        heroSubheadline: description,
-        markdownBody,
-        faqList,
-        neighboringLinks: [],
+        directAnswerGeoHtml: directAnswerHtml,
+        heroHeadline: opts.h1,
+        heroSubheadline: opts.description,
+        markdownBody: `# ${opts.h1}\n\n${opts.description}\n\n> ${opts.directAnswer}`,
+        faqList: localizedFaqs,
       },
+      schemaJsonLd: jsonLd,
       pricing: {
-        priceNumber: service.pricePerMonth,
-        priceFormatted: `${service.pricePerMonth} ${this.config.currencySymbol} / mois`,
+        priceNumber: opts.service.pricePerMonth,
+        priceFormatted: `${opts.service.pricePerMonth} ${this.config.currencySymbol}`,
+        currency: this.config.currency || "EUR",
       },
-      executionTimeMs,
     };
   }
+
+  /**
+   * Returns the exact count of distinct unique programmatic pages currently active.
+   */
+  getUniquePageCount(): number {
+    const rawKey = this.config.apiKey || this.config.licenseKey || "";
+    return ApiKeyGuardian.getUniquePageCount(rawKey);
+  }
+
+  /**
+   * Returns the list of all distinct unique URL paths generated so far.
+   */
+  getUniquePageList(): string[] {
+    const rawKey = this.config.apiKey || this.config.licenseKey || "";
+    return ApiKeyGuardian.getUniquePageList(rawKey);
+  }
+
+  /**
+   * Performs an automated deep crawl and technical SEO audit of the configured domain.
+   */
+  async crawlSite(options?: CrawlOptions): Promise<SiteAuditSummary> {
+    return DeepCrawlerAuditor.crawlAndAuditDomain(this.config.domain, options);
+  }
 }