@lynxflow/seo-engine 1.5.5 → 1.5.7

package/dist/extended-schemas.d.ts

@@ -103,4 +103,42 @@ export declare class ExtendedSchemaGraphBuilder {
         name: string;
         url: string;
     }[]): Record<string, unknown>;
+    /**
+     * 7. AggregateRating (Google Gold Stars in SERPs) - Inspired by santifer-irepair
+     */
+    static buildAggregateRating(opts: {
+        ratingValue?: number;
+        reviewCount?: number;
+        bestRating?: number;
+        worstRating?: number;
+        itemReviewedName: string;
+    }): Record<string, unknown>;
+    /**
+     * 8. AggregateOffer (Price Ranges & Tiers) - Inspired by santifer-irepair
+     */
+    static buildAggregateOffer(opts: {
+        lowPrice: number;
+        highPrice: number;
+        currency: string;
+        offerCount?: number;
+        description?: string;
+    }): Record<string, unknown>;
+    /**
+     * 9. Service with ServiceArea & Providers
+     */
+    static buildService(opts: {
+        name: string;
+        description: string;
+        providerName: string;
+        areaServed?: string[];
+        serviceType?: string;
+    }): Record<string, unknown>;
+    /**
+     * 10. WebSite with Google Sitelinks SearchBox
+     */
+    static buildWebSite(opts: {
+        name: string;
+        url: string;
+        searchUrlTemplate?: string;
+    }): Record<string, unknown>;
 }

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export * from "./slug-engine";
 export * from "./legal-disclaimers";
 export * from "./matrix-engine";
 export * from "./brand-icons";
+export * from "./urlytics-engine";
+export * from "./keyword-permutator";
 export * from "./llm-prompt";
 export * from "./auth-key";
 export * from "./token-quota-manager";

package/dist/index.js

@@ -47,6 +47,7 @@ __export(exports_src, {
   createLynxSeoEngine: () => createLynxSeoEngine,
   cleanSeoSlug: () => cleanSeoSlug,
   YoastParityEngine: () => YoastParityEngine,
+  UrlyticsEngine: () => UrlyticsEngine,
   TokenQuotaManager: () => TokenQuotaManager,
   TechnicalRulesAuditor: () => TechnicalRulesAuditor,
   TeamRbacEngine: () => TeamRbacEngine,
@@ -78,6 +79,7 @@ __export(exports_src, {
   LegalDisclaimerEngine: () => LegalDisclaimerEngine,
   LagoTokenMeter: () => LagoTokenMeter,
   KnowledgeGraphLinker: () => KnowledgeGraphLinker,
+  KeywordPermutatorEngine: () => KeywordPermutatorEngine,
   IsrCacheManager: () => IsrCacheManager,
   InstantMatrixSearchEngine: () => InstantMatrixSearchEngine,
   IndexNowClient: () => IndexNowClient,
@@ -3130,6 +3132,62 @@ class ExtendedSchemaGraphBuilder {
       }))
     };
   }
+  static buildAggregateRating(opts) {
+    return {
+      "@type": "AggregateRating",
+      ratingValue: opts.ratingValue ?? 4.9,
+      reviewCount: opts.reviewCount ?? 1280,
+      bestRating: opts.bestRating ?? 5,
+      worstRating: opts.worstRating ?? 1,
+      itemReviewed: {
+        "@type": "Thing",
+        name: opts.itemReviewedName
+      }
+    };
+  }
+  static buildAggregateOffer(opts) {
+    return {
+      "@type": "AggregateOffer",
+      lowPrice: String(opts.lowPrice),
+      highPrice: String(opts.highPrice),
+      priceCurrency: opts.currency,
+      offerCount: String(opts.offerCount ?? 3),
+      description: opts.description || "Transparent pricing with zero lock-in"
+    };
+  }
+  static buildService(opts) {
+    return {
+      "@context": "https://schema.org",
+      "@type": "Service",
+      name: opts.name,
+      description: opts.description,
+      serviceType: opts.serviceType || "SoftwareService",
+      provider: {
+        "@type": "Organization",
+        name: opts.providerName
+      },
+      areaServed: opts.areaServed ? opts.areaServed.map((city) => ({
+        "@type": "City",
+        name: city
+      })) : undefined
+    };
+  }
+  static buildWebSite(opts) {
+    return {
+      "@context": "https://schema.org",
+      "@type": "WebSite",
+      name: opts.name,
+      url: opts.url,
+      potentialAction: opts.searchUrlTemplate ? {
+        "@type": "SearchAction",
+        target: {
+          "@type": "EntryPoint",
+          urlTemplate: opts.searchUrlTemplate
+        },
+        "query-input": "required name=search_term_string"
+      } : undefined
+    };
+  }
 }
 
 // src/matrix-engine.ts
@@ -3214,7 +3272,7 @@ class PseoMatrixEngine {
         const countryCode = cleanSeoSlug(loc.country, { language: lang });
         const citySlug = cleanSeoSlug(loc.slug, { language: lang });
         const serviceSlug = cleanSeoSlug(s.slug, { language: lang });
-        const urlPath = `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
+        const urlPath = options.cleanDirectRoutes !== false ? `/${serviceSlug}/${citySlug}` : `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
         const fullUrl = `${cleanDomain}${urlPath}`;
         const isIndexed = (loc.population ?? 20000) >= minPop;
         const robots = isIndexed ? "index, follow" : "noindex, follow";
@@ -3637,6 +3695,40 @@ class PseoMatrixEngine {
     }
     return allPages;
   }
+  resolvePage(slugOrPath, domain, data, options) {
+    const path = typeof slugOrPath === "string" ? slugOrPath.startsWith("/") ? slugOrPath : `/${slugOrPath}` : `/${slugOrPath.join("/")}`;
+    const pages = this.generateAllMatrices(domain, data, options);
+    return pages.find((p) => p.urlPath === path);
+  }
+  generateSitemapXml(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options).filter((p) => p.robots.includes("index"));
+    const now = new Date().toISOString();
+    const urls = pages.map((p) => `  <url>
+    <loc>${p.canonicalUrl}</loc>
+    <lastmod>${now}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>`).join(`
+`);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`;
+  }
+  generateLlmsTxt(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const lines = [
+      `# ${options.brandName} — AI Knowledge Graph & Page Hub`,
+      `> Complete index of services, tools, integrations, and local solution hubs.`,
+      "",
+      `## Indexed Programmatic Hubs (${pages.length} Pages)`
+    ];
+    for (const p of pages) {
+      lines.push(`- [${p.h1}](${p.canonicalUrl}): ${p.description}`);
+    }
+    return lines.join(`
+`);
+  }
 }
 // src/brand-icons.ts
 var BRAND_ICONS = {
@@ -3754,6 +3846,144 @@ function renderBrandIconSvg(input, className = "w-5 h-5 inline-block") {
     return "";
   return `<svg class="${className}" viewBox="${icon.viewBox}" fill="currentColor" aria-hidden="true"><path d="${icon.svgPath}"/></svg>`;
 }
+// src/urlytics-engine.ts
+class UrlyticsEngine {
+  static parseUrl(rawUrl) {
+    if (!rawUrl || typeof rawUrl !== "string") {
+      return {
+        url: "",
+        scheme: "",
+        domain: "",
+        path: "/",
+        depth: 0,
+        lastDir: "",
+        queryParams: {},
+        slugTokens: [],
+        charCount: 0,
+        hasTrailingSlash: false
+      };
+    }
+    try {
+      const parsed = new URL(rawUrl.startsWith("http") ? rawUrl : `https://${rawUrl}`);
+      const pathClean = parsed.pathname.replace(/\/+$/, "");
+      const segments = pathClean.split("/").filter(Boolean);
+      const queryParams = {};
+      parsed.searchParams.forEach((val, key) => {
+        queryParams[key] = val;
+      });
+      const lastDir = segments.length > 0 ? segments[segments.length - 1] : "";
+      const slugTokens = lastDir.split("-").filter(Boolean);
+      return {
+        url: rawUrl,
+        scheme: parsed.protocol.replace(":", ""),
+        domain: parsed.hostname,
+        path: parsed.pathname,
+        depth: segments.length,
+        dir1: segments[0],
+        dir2: segments[1],
+        dir3: segments[2],
+        lastDir,
+        queryParams,
+        hashFragment: parsed.hash ? parsed.hash.replace("#", "") : undefined,
+        slugTokens,
+        charCount: rawUrl.length,
+        hasTrailingSlash: parsed.pathname.length > 1 && parsed.pathname.endsWith("/")
+      };
+    } catch {
+      return {
+        url: rawUrl,
+        scheme: "unknown",
+        domain: "",
+        path: rawUrl,
+        depth: 0,
+        lastDir: rawUrl,
+        queryParams: {},
+        slugTokens: [rawUrl],
+        charCount: rawUrl.length,
+        hasTrailingSlash: false
+      };
+    }
+  }
+  static analyzeUrls(urls) {
+    return urls.map((u) => this.parseUrl(u));
+  }
+}
+// src/keyword-permutator.ts
+class KeywordPermutatorEngine {
+  static generateKeywordMatrix(options) {
+    const { products, words = [], locations = [], maxCombinations = 5000 } = options;
+    const results = [];
+    const intentKeywords = {
+      transactional: ["buy", "pricing", "cost", "hire", "quote", "tarif", "prix", "devis", "acheter"],
+      commercial: ["best", "top", "review", "vs", "comparison", "alternative", "comparatif", "meilleur"],
+      informational: ["how to", "what is", "guide", "tutorial", "definition", "comment", "quest ce que"],
+      navigational: ["login", "app", "portal", "website", "connexion"]
+    };
+    const detectIntent = (text) => {
+      const lower = text.toLowerCase();
+      for (const [intent, triggers] of Object.entries(intentKeywords)) {
+        if (triggers.some((t) => lower.includes(t))) {
+          return intent;
+        }
+      }
+      return "commercial";
+    };
+    for (const prod of products) {
+      results.push({
+        keyword: prod,
+        exactMatch: `[${prod}]`,
+        phraseMatch: `"${prod}"`,
+        intent: detectIntent(prod),
+        product: prod
+      });
+      for (const word of words) {
+        const kw1 = `${word} ${prod}`;
+        const kw2 = `${prod} ${word}`;
+        results.push({
+          keyword: kw1,
+          exactMatch: `[${kw1}]`,
+          phraseMatch: `"${kw1}"`,
+          intent: detectIntent(word),
+          product: prod,
+          modifier: word
+        });
+        results.push({
+          keyword: kw2,
+          exactMatch: `[${kw2}]`,
+          phraseMatch: `"${kw2}"`,
+          intent: detectIntent(word),
+          product: prod,
+          modifier: word
+        });
+        for (const loc of locations) {
+          const kwLoc1 = `${word} ${prod} ${loc}`;
+          const kwLoc2 = `${prod} ${loc} ${word}`;
+          results.push({
+            keyword: kwLoc1,
+            exactMatch: `[${kwLoc1}]`,
+            phraseMatch: `"${kwLoc1}"`,
+            intent: detectIntent(word),
+            product: prod,
+            modifier: word,
+            location: loc
+          });
+          results.push({
+            keyword: kwLoc2,
+            exactMatch: `[${kwLoc2}]`,
+            phraseMatch: `"${kwLoc2}"`,
+            intent: detectIntent(word),
+            product: prod,
+            modifier: word,
+            location: loc
+          });
+          if (results.length >= maxCombinations)
+            return results;
+        }
+      }
+    }
+    return results;
+  }
+}
 // src/llm-prompt.ts
 var PSEO_AGENT_SYSTEM_PROMPT = `
 You are the Programmatic SEO Implementation Specialist powered by @lynxflow/seo-engine.
@@ -3788,7 +4018,21 @@ When discovering product modules, features, or services to build the SEO matrice
 
 ---
 
-### \uD83C\uDFC6 3. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
+### \uD83D\uDCCF 3. THE GOLDEN RULES OF URL ARCHITECTURE (MAX 3-4 SEGMENTS, ZERO PARASITE WORDS)
+
+- **Rule A (2 to 3 URL Segments Ideal, 4 Maximum):**
+  - ✅ **2 Segments (Top SEO Performance):** \`site.com/{service}/{city}\` (e.g. \`/autopost-facebook/lyon\`, \`/crm/paris\`).
+  - ✅ **3 Segments (B2B Persona/Hub):** \`site.com/for/{target}/{city}\` or \`site.com/{locale}/{service}/{city}\`.
+  - ❌ **Never 5 to 6 Segments:** Avoid \`/solutions/ai/autopost/facebook/fr/lyon\`.
+- **Rule B (Eliminate All Parasite Noise Words):**
+  - Banish generic wrapper words like \`/solutions/\`, \`/pages/\`, \`/items/\`. Go direct to user search intent: What you do + Platform + Location.
+- **Rule C (The SDK Does 100% of the Heavy Lifting):**
+  - The developer/AI only registers 3-4 product features and target cities in \`lib/seo.ts\`.
+  - The SDK automatically resolves routes in memory via \`matrixEngine.resolvePage(params.slug)\`, generates complete Schema.org graphs (LocalBusiness, AggregateRating, AggregateOffer), creates AEO summaries, builds FAQ accordions, and manages mesh linking in < 0.05ms.
+
+---
+
+### \uD83C\uDFC6 4. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
 
 How category leaders generate millions of high-converting pages without server saturation:
 
@@ -3800,18 +4044,18 @@ How category leaders generate millions of high-converting pages without server s
 
 2. **The 4 Pillars of Zero-Latency (< 0.05ms) Resolution:**
    - **0 Bytes in Database:** Never generate physical static files or query heavy databases per request. Pages are resolved mathematically in RAM upon arrival.
-   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` (or \`app/[locale]/[...slug]/page.tsx\`) handles all matrices through one lightweight layout.
-   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge (Cloudflare / Vercel Edge) on first request.
+   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` handles all matrices through one lightweight layout.
+   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge on first request.
    - **Automatic Siloing & Mesh Linking:**
      - Links to 3 neighboring geographic cities for the same service.
      - Links to 4 related professions/industries in the same target category.
      - Complete Schema.org BreadcrumbList navigation.
-   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index to respect Google's crawl budget.
+   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index.
    - **Dynamic \`/llms.txt\` Feed:** High-density Markdown stream enabling direct indexing by ChatGPT Search & Perplexity.
 
 ---
 
-### \uD83D\uDEE0️ 4. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
+### \uD83D\uDEE0️ 5. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
 
 When setting up programmatic SEO in any codebase, the AI Agent MUST generate these exact 4 files:
 
@@ -3824,6 +4068,7 @@ export const matrixEngine = new PseoMatrixEngine();
 export const SEO_CONFIG = {
   brandName: "Acme",
   language: "en",
+  cleanDirectRoutes: true, // Eliminates parasite words (/solutions/, etc.)
   minPopulationToIndex: 15_000,
 };
 
@@ -3831,19 +4076,23 @@ export const SEO_CONFIG = {
 export const PSEO_DATASET = {
   services: [
     // 1 per major frontend feature branch
-    { slug: "crm-pipeline", name: "Visual CRM Pipeline", category: "Sales", keyFeatures: ["Kanban", "Lead scoring"], description: "Visual deal tracking" },
+    { slug: "autopost-facebook", name: "Autopost Facebook & Instagram", category: "Social Media", keyFeatures: ["AI Scheduling", "Visual Calendar", "Auto-Hashtags"], description: "Automated social media posting engine" },
+  ],
+  locations: [
+    { slug: "paris", name: "Paris", region: "Île-de-France", country: "France", population: 2_161_000, currency: "EUR", currencySymbol: "€" },
+    { slug: "lyon", name: "Lyon", region: "Rhône-Alpes", country: "France", population: 522_000, currency: "EUR", currencySymbol: "€" },
   ],
   targets: [
-    { slug: "law-firms", name: "Law Firms", type: "industry", painPoints: ["Billing"], benefits: ["Compliance"] },
+    { slug: "agences", name: "Marketing Agencies", type: "industry", painPoints: ["Manual Posting"], benefits: ["10x Output"] },
   ],
   integrations: [
-    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Order sync"] },
+    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Catalog sync"] },
   ],
   templates: [
-    { slug: "sales-tracker-excel", title: "Sales Tracker", topic: "Sales", format: "excel", benefits: ["Instant setup"] },
+    { slug: "social-calendar-excel", title: "Social Media Calendar", topic: "Social Media", format: "excel", benefits: ["Instant setup"] },
   ],
   glossaryTerms: [
-    { slug: "mrr", term: "MRR", shortDefinition: "Monthly Recurring Revenue" },
+    { slug: "engagement-rate", term: "Engagement Rate", shortDefinition: "Percentage of audience interacting with content" },
   ],
 };
 \`\`\`
@@ -3856,19 +4105,15 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 import { renderBrandIconSvg } from "@lynxflow/seo-engine";
 
 export async function generateMetadata({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) return {};
   return { title: page.title, description: page.description, alternates: { canonical: page.canonicalUrl }, robots: page.robots };
 }
 
 export default async function ProgrammaticPage({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) notFound();
 
   // Automatic Brand Icon Detection