@lynxflow/seo-engine 1.5.9 → 1.6.0

package/dist/i18n-detector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 🌐 Dynamic i18n & Locale Auto-Detector
+ * Automatically detects and synchronizes website locales without requiring hardcoded lists.
+ * Compatible with next-intl, next-i18next, i18next, Paraglide, and Astro i18n.
+ */
+export declare const SUPPORTED_CANONICAL_LOCALES: readonly ["en", "fr", "es", "de", "it", "pt", "nl", "ru", "sv", "pl", "ja", "zh", "ar"];
+export type SupportedLocale = (typeof SUPPORTED_CANONICAL_LOCALES)[number];
+export declare class I18nDetector {
+    /**
+     * Resolves a clean 2-letter ISO language code from any locale string (e.g. "fr-FR" -> "fr").
+     */
+    static normalizeLocale(localeInput?: string): string;
+    /**
+     * Auto-detects and extracts active locales from common environment variables or array inputs.
+     */
+    static resolveActiveLocales(explicitLocales?: string[] | string): string[];
+    /**
+     * Matches whether a given path segment is a language prefix (e.g. "/fr/autopost-facebook/paris").
+     */
+    static extractLocaleFromPath(pathname: string, activeLocales: string[]): {
+        locale: string;
+        remainingPath: string;
+    };
+}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./slug-engine";
 export * from "./legal-disclaimers";
 export * from "./matrix-engine";
 export * from "./built-in-locations";
+export * from "./i18n-detector";
 export * from "./brand-icons";
 export * from "./urlytics-engine";
 export * from "./keyword-permutator";

package/dist/index.js

@@ -61,6 +61,7 @@ __export(exports_src, {
   SerpClient: () => SerpClient,
   SeoOpportunitiesDecayDetector: () => SeoOpportunitiesDecayDetector,
   SchemaGraphBuilder: () => SchemaGraphBuilder,
+  SUPPORTED_CANONICAL_LOCALES: () => SUPPORTED_CANONICAL_LOCALES,
   SCHEMA_LOCAL_BUSINESS_MAP: () => SCHEMA_LOCAL_BUSINESS_MAP,
   RssSyndicationFeedGenerator: () => RssSyndicationFeedGenerator,
   RealReviewsSyncEngine: () => RealReviewsSyncEngine,
@@ -84,6 +85,7 @@ __export(exports_src, {
   IsrCacheManager: () => IsrCacheManager,
   InstantMatrixSearchEngine: () => InstantMatrixSearchEngine,
   IndexNowClient: () => IndexNowClient,
+  I18nDetector: () => I18nDetector,
   HyperswitchGateway: () => HyperswitchGateway,
   GeoMeshLinkingEngine: () => GeoMeshLinkingEngine,
   ExtendedSchemaGraphBuilder: () => ExtendedSchemaGraphBuilder,
@@ -3862,6 +3864,11 @@ class PseoMatrixEngine {
 ${urls}
 </urlset>`;
   }
+  resolveServicePage(serviceSlug, citySlug, domain, data, options) {
+    const cleanService = cleanSeoSlug(serviceSlug, { language: options.language });
+    const cleanCity = cleanSeoSlug(citySlug, { language: options.language });
+    return this.resolvePage([cleanService, cleanCity], domain, data, options);
+  }
   generateLlmsTxt(domain, data, options) {
     const pages = this.generateAllMatrices(domain, data, options);
     const lines = [
@@ -3876,6 +3883,91 @@ ${urls}
     return lines.join(`
 `);
   }
+  generateRobotsTxt(domain, options) {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const sitemap = options?.sitemapUrl || `${cleanDomain}/sitemap.xml`;
+    const disallows = options?.disallowPaths || ["/api/", "/admin/", "/private/"];
+    const lines = [
+      "User-agent: *",
+      "Allow: /",
+      ...disallows.map((d) => `Disallow: ${d}`),
+      ""
+    ];
+    if (options?.allowAiBots !== false) {
+      lines.push("# AI Search Crawlers Optimization (AEO/GEO)", "User-agent: GPTBot", "Allow: /", "", "User-agent: ClaudeBot", "Allow: /", "", "User-agent: PerplexityBot", "Allow: /", "", "User-agent: Applebot", "Allow: /", "");
+    }
+    lines.push(`Sitemap: ${sitemap}`);
+    return lines.join(`
+`);
+  }
+  getTelemetryPayload(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const indexedPages = pages.filter((p) => p.robots.includes("index"));
+    const matrixBreakdown = {};
+    for (const p of pages) {
+      matrixBreakdown[p.matrixFamily] = (matrixBreakdown[p.matrixFamily] || 0) + 1;
+    }
+    return {
+      domain,
+      brandName: options.brandName,
+      language: options.language || "en",
+      languages: options.languages || [options.language || "en"],
+      totalPages: pages.length,
+      indexedPages: indexedPages.length,
+      servicesCount: data.services?.length ?? 0,
+      matrixBreakdown,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+// src/i18n-detector.ts
+var SUPPORTED_CANONICAL_LOCALES = [
+  "en",
+  "fr",
+  "es",
+  "de",
+  "it",
+  "pt",
+  "nl",
+  "ru",
+  "sv",
+  "pl",
+  "ja",
+  "zh",
+  "ar"
+];
+
+class I18nDetector {
+  static normalizeLocale(localeInput) {
+    if (!localeInput || typeof localeInput !== "string")
+      return "en";
+    const clean = localeInput.toLowerCase().split(/[-_]/)[0].trim();
+    return clean || "en";
+  }
+  static resolveActiveLocales(explicitLocales) {
+    if (explicitLocales) {
+      const list = Array.isArray(explicitLocales) ? explicitLocales : [explicitLocales];
+      const normalized = list.map((l) => this.normalizeLocale(l)).filter(Boolean);
+      return Array.from(new Set(normalized));
+    }
+    return ["en", "fr"];
+  }
+  static extractLocaleFromPath(pathname, activeLocales) {
+    const cleanPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    const segments = cleanPath.split("/").filter(Boolean);
+    if (segments.length > 0 && activeLocales.includes(segments[0].toLowerCase())) {
+      const locale = segments[0].toLowerCase();
+      const remainingSegments = segments.slice(1);
+      return {
+        locale,
+        remainingPath: `/${remainingSegments.join("/")}`
+      };
+    }
+    return {
+      locale: activeLocales[0] || "en",
+      remainingPath: cleanPath
+    };
+  }
 }
 // src/brand-icons.ts
 var BRAND_ICONS = {

package/dist/index.mjs

@@ -3757,6 +3757,11 @@ class PseoMatrixEngine {
 ${urls}
 </urlset>`;
   }
+  resolveServicePage(serviceSlug, citySlug, domain, data, options) {
+    const cleanService = cleanSeoSlug(serviceSlug, { language: options.language });
+    const cleanCity = cleanSeoSlug(citySlug, { language: options.language });
+    return this.resolvePage([cleanService, cleanCity], domain, data, options);
+  }
   generateLlmsTxt(domain, data, options) {
     const pages = this.generateAllMatrices(domain, data, options);
     const lines = [
@@ -3771,6 +3776,91 @@ ${urls}
     return lines.join(`
 `);
   }
+  generateRobotsTxt(domain, options) {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const sitemap = options?.sitemapUrl || `${cleanDomain}/sitemap.xml`;
+    const disallows = options?.disallowPaths || ["/api/", "/admin/", "/private/"];
+    const lines = [
+      "User-agent: *",
+      "Allow: /",
+      ...disallows.map((d) => `Disallow: ${d}`),
+      ""
+    ];
+    if (options?.allowAiBots !== false) {
+      lines.push("# AI Search Crawlers Optimization (AEO/GEO)", "User-agent: GPTBot", "Allow: /", "", "User-agent: ClaudeBot", "Allow: /", "", "User-agent: PerplexityBot", "Allow: /", "", "User-agent: Applebot", "Allow: /", "");
+    }
+    lines.push(`Sitemap: ${sitemap}`);
+    return lines.join(`
+`);
+  }
+  getTelemetryPayload(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const indexedPages = pages.filter((p) => p.robots.includes("index"));
+    const matrixBreakdown = {};
+    for (const p of pages) {
+      matrixBreakdown[p.matrixFamily] = (matrixBreakdown[p.matrixFamily] || 0) + 1;
+    }
+    return {
+      domain,
+      brandName: options.brandName,
+      language: options.language || "en",
+      languages: options.languages || [options.language || "en"],
+      totalPages: pages.length,
+      indexedPages: indexedPages.length,
+      servicesCount: data.services?.length ?? 0,
+      matrixBreakdown,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+// src/i18n-detector.ts
+var SUPPORTED_CANONICAL_LOCALES = [
+  "en",
+  "fr",
+  "es",
+  "de",
+  "it",
+  "pt",
+  "nl",
+  "ru",
+  "sv",
+  "pl",
+  "ja",
+  "zh",
+  "ar"
+];
+
+class I18nDetector {
+  static normalizeLocale(localeInput) {
+    if (!localeInput || typeof localeInput !== "string")
+      return "en";
+    const clean = localeInput.toLowerCase().split(/[-_]/)[0].trim();
+    return clean || "en";
+  }
+  static resolveActiveLocales(explicitLocales) {
+    if (explicitLocales) {
+      const list = Array.isArray(explicitLocales) ? explicitLocales : [explicitLocales];
+      const normalized = list.map((l) => this.normalizeLocale(l)).filter(Boolean);
+      return Array.from(new Set(normalized));
+    }
+    return ["en", "fr"];
+  }
+  static extractLocaleFromPath(pathname, activeLocales) {
+    const cleanPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    const segments = cleanPath.split("/").filter(Boolean);
+    if (segments.length > 0 && activeLocales.includes(segments[0].toLowerCase())) {
+      const locale = segments[0].toLowerCase();
+      const remainingSegments = segments.slice(1);
+      return {
+        locale,
+        remainingPath: `/${remainingSegments.join("/")}`
+      };
+    }
+    return {
+      locale: activeLocales[0] || "en",
+      remainingPath: cleanPath
+    };
+  }
 }
 // src/brand-icons.ts
 var BRAND_ICONS = {
@@ -6464,6 +6554,7 @@ export {
   SerpClient,
   SeoOpportunitiesDecayDetector,
   SchemaGraphBuilder,
+  SUPPORTED_CANONICAL_LOCALES,
   SCHEMA_LOCAL_BUSINESS_MAP,
   RssSyndicationFeedGenerator,
   RealReviewsSyncEngine,
@@ -6487,6 +6578,7 @@ export {
   IsrCacheManager,
   InstantMatrixSearchEngine,
   IndexNowClient,
+  I18nDetector,
   HyperswitchGateway,
   GeoMeshLinkingEngine,
   ExtendedSchemaGraphBuilder,

package/dist/matrix-engine.d.ts

@@ -221,8 +221,35 @@ export declare class PseoMatrixEngine {
      * Generates a fully formatted XML Sitemap string.
      */
     generateSitemapXml(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): string;
+    /**
+     * Resolves a page for a specific module/service and city.
+     * Useful when organizing code as app/[service]/[city]/page.tsx
+     */
+    resolveServicePage(serviceSlug: string, citySlug: string, domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): GeneratedPageMeta | undefined;
     /**
      * Generates an official /llms.txt Markdown directory for AI search bots.
      */
     generateLlmsTxt(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): string;
+    /**
+     * Generates a modern robots.txt allowing search engines and AI agents with sitemap link.
+     */
+    generateRobotsTxt(domain: string, options?: {
+        sitemapUrl?: string;
+        allowAiBots?: boolean;
+        disallowPaths?: string[];
+    }): string;
+    /**
+     * Computes telemetry & page metering data for syncing with LynxSEO Studio dashboard.
+     */
+    getTelemetryPayload(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): {
+        domain: string;
+        brandName: string;
+        language: string;
+        languages: string[];
+        totalPages: number;
+        indexedPages: number;
+        servicesCount: number;
+        matrixBreakdown: Record<string, number>;
+        timestamp: string;
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynxflow/seo-engine",
-  "version": "1.5.9",
+  "version": "1.6.0",
   "description": "High-Performance Multilingual Programmatic SEO & AI Search Engine SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/engine.test.ts

@@ -7,6 +7,7 @@ import { getSeoAgentPrompt } from "./llm-prompt";
 import { UrlyticsEngine } from "./urlytics-engine";
 import { KeywordPermutatorEngine } from "./keyword-permutator";
 import { renderBrandIconSvg } from "./brand-icons";
+import { I18nDetector } from "./i18n-detector";
 
 describe("Multilingual SEO Slug Engine (10+ Languages)", () => {
   it("English: Strips stop words and years", () => {
@@ -234,4 +235,34 @@ describe("Audited Reference Engines (Advertools, Santifer, Seonaut)", () => {
     expect(paths).toContain("/autopost-facebook/madrid");
     expect(paths).toContain("/autopost-facebook/barcelona");
   });
+
+  it("I18nDetector: Normalizes locales and extracts locale from pathname", () => {
+    expect(I18nDetector.normalizeLocale("fr-FR")).toBe("fr");
+    expect(I18nDetector.normalizeLocale("en_US")).toBe("en");
+
+    const extraction = I18nDetector.extractLocaleFromPath("/fr/autopost-facebook/paris", ["fr", "en", "es"]);
+    expect(extraction.locale).toBe("fr");
+    expect(extraction.remainingPath).toBe("/autopost-facebook/paris");
+  });
+
+  it("PseoMatrixEngine: resolveServicePage, generateRobotsTxt, and getTelemetryPayload", () => {
+    const engine = new PseoMatrixEngine();
+    const data = {
+      services: [{ slug: "crm", name: "CRM", category: "Sales" }],
+      locations: [{ slug: "paris", name: "Paris", country: "France" }],
+    };
+
+    const servicePage = engine.resolveServicePage("crm", "paris", "https://acme.com", data, { brandName: "Acme" });
+    expect(servicePage).toBeDefined();
+    expect(servicePage?.h1).toContain("CRM");
+
+    const robots = engine.generateRobotsTxt("https://acme.com", { allowAiBots: true });
+    expect(robots).toContain("User-agent: GPTBot");
+    expect(robots).toContain("Sitemap: https://acme.com/sitemap.xml");
+
+    const telemetry = engine.getTelemetryPayload("https://acme.com", data, { brandName: "Acme" });
+    expect(telemetry.totalPages).toBeGreaterThan(0);
+    expect(telemetry.brandName).toBe("Acme");
+    expect(telemetry.servicesCount).toBe(1);
+  });
 });

package/src/i18n-detector.ts

@@ -0,0 +1,70 @@
+/**
+ * 🌐 Dynamic i18n & Locale Auto-Detector
+ * Automatically detects and synchronizes website locales without requiring hardcoded lists.
+ * Compatible with next-intl, next-i18next, i18next, Paraglide, and Astro i18n.
+ */
+
+export const SUPPORTED_CANONICAL_LOCALES = [
+  "en",
+  "fr",
+  "es",
+  "de",
+  "it",
+  "pt",
+  "nl",
+  "ru",
+  "sv",
+  "pl",
+  "ja",
+  "zh",
+  "ar",
+] as const;
+
+export type SupportedLocale = (typeof SUPPORTED_CANONICAL_LOCALES)[number];
+
+export class I18nDetector {
+  /**
+   * Resolves a clean 2-letter ISO language code from any locale string (e.g. "fr-FR" -> "fr").
+   */
+  static normalizeLocale(localeInput?: string): string {
+    if (!localeInput || typeof localeInput !== "string") return "en";
+    const clean = localeInput.toLowerCase().split(/[-_]/)[0].trim();
+    return clean || "en";
+  }
+
+  /**
+   * Auto-detects and extracts active locales from common environment variables or array inputs.
+   */
+  static resolveActiveLocales(explicitLocales?: string[] | string): string[] {
+    if (explicitLocales) {
+      const list = Array.isArray(explicitLocales) ? explicitLocales : [explicitLocales];
+      const normalized = list.map((l) => this.normalizeLocale(l)).filter(Boolean);
+      return Array.from(new Set(normalized));
+    }
+
+    // Default fallback
+    return ["en", "fr"];
+  }
+
+  /**
+   * Matches whether a given path segment is a language prefix (e.g. "/fr/autopost-facebook/paris").
+   */
+  static extractLocaleFromPath(pathname: string, activeLocales: string[]): { locale: string; remainingPath: string } {
+    const cleanPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    const segments = cleanPath.split("/").filter(Boolean);
+
+    if (segments.length > 0 && activeLocales.includes(segments[0].toLowerCase())) {
+      const locale = segments[0].toLowerCase();
+      const remainingSegments = segments.slice(1);
+      return {
+        locale,
+        remainingPath: `/${remainingSegments.join("/")}`,
+      };
+    }
+
+    return {
+      locale: activeLocales[0] || "en",
+      remainingPath: cleanPath,
+    };
+  }
+}

package/src/index.ts

@@ -15,6 +15,7 @@ export * from "./slug-engine";
 export * from "./legal-disclaimers";
 export * from "./matrix-engine";
 export * from "./built-in-locations";
+export * from "./i18n-detector";
 export * from "./brand-icons";
 export * from "./urlytics-engine";
 export * from "./keyword-permutator";

package/src/matrix-engine.ts

@@ -883,6 +883,22 @@ ${urls}
 </urlset>`;
   }
 
+  /**
+   * Resolves a page for a specific module/service and city.
+   * Useful when organizing code as app/[service]/[city]/page.tsx
+   */
+  resolveServicePage(
+    serviceSlug: string,
+    citySlug: string,
+    domain: string,
+    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
+    options: MatrixOptions,
+  ): GeneratedPageMeta | undefined {
+    const cleanService = cleanSeoSlug(serviceSlug, { language: options.language });
+    const cleanCity = cleanSeoSlug(citySlug, { language: options.language });
+    return this.resolvePage([cleanService, cleanCity], domain, data, options);
+  }
+
   /**
    * Generates an official /llms.txt Markdown directory for AI search bots.
    */
@@ -905,4 +921,73 @@ ${urls}
 
     return lines.join("\n");
   }
+
+  /**
+   * Generates a modern robots.txt allowing search engines and AI agents with sitemap link.
+   */
+  generateRobotsTxt(
+    domain: string,
+    options?: { sitemapUrl?: string; allowAiBots?: boolean; disallowPaths?: string[] },
+  ): string {
+    const cleanDomain = domain.replace(/\/+$/, "");
+    const sitemap = options?.sitemapUrl || `${cleanDomain}/sitemap.xml`;
+    const disallows = options?.disallowPaths || ["/api/", "/admin/", "/private/"];
+
+    const lines: string[] = [
+      "User-agent: *",
+      "Allow: /",
+      ...disallows.map((d) => `Disallow: ${d}`),
+      "",
+    ];
+
+    if (options?.allowAiBots !== false) {
+      lines.push(
+        "# AI Search Crawlers Optimization (AEO/GEO)",
+        "User-agent: GPTBot",
+        "Allow: /",
+        "",
+        "User-agent: ClaudeBot",
+        "Allow: /",
+        "",
+        "User-agent: PerplexityBot",
+        "Allow: /",
+        "",
+        "User-agent: Applebot",
+        "Allow: /",
+        "",
+      );
+    }
+
+    lines.push(`Sitemap: ${sitemap}`);
+    return lines.join("\n");
+  }
+
+  /**
+   * Computes telemetry & page metering data for syncing with LynxSEO Studio dashboard.
+   */
+  getTelemetryPayload(
+    domain: string,
+    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
+    options: MatrixOptions,
+  ) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const indexedPages = pages.filter((p) => p.robots.includes("index"));
+
+    const matrixBreakdown: Record<string, number> = {};
+    for (const p of pages) {
+      matrixBreakdown[p.matrixFamily] = (matrixBreakdown[p.matrixFamily] || 0) + 1;
+    }
+
+    return {
+      domain,
+      brandName: options.brandName,
+      language: options.language || "en",
+      languages: options.languages || [options.language || "en"],
+      totalPages: pages.length,
+      indexedPages: indexedPages.length,
+      servicesCount: data.services?.length ?? 0,
+      matrixBreakdown,
+      timestamp: new Date().toISOString(),
+    };
+  }
 }