@lynxflow/seo-engine 1.5.5 → 1.5.6

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
@@ -3754,6 +3812,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.

package/dist/index.mjs

@@ -3029,6 +3029,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
@@ -3653,6 +3709,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.
@@ -6064,6 +6258,7 @@ export {
   createLynxSeoEngine,
   cleanSeoSlug,
   YoastParityEngine,
+  UrlyticsEngine,
   TokenQuotaManager,
   TechnicalRulesAuditor,
   TeamRbacEngine,
@@ -6095,6 +6290,7 @@ export {
   LegalDisclaimerEngine,
   LagoTokenMeter,
   KnowledgeGraphLinker,
+  KeywordPermutatorEngine,
   IsrCacheManager,
   InstantMatrixSearchEngine,
   IndexNowClient,

package/dist/keyword-permutator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ⚡ High-Speed Keyword Permutator & SEM Matrix Engine
+ * Inspired by advertools.kw_generate
+ *
+ * Generates all permutations and combinations of Products × Modifiers × Intents × Locations
+ * with match types (Broad, Phrase, Exact) and estimated search intent tagging.
+ */
+export type SearchIntentType = "commercial" | "transactional" | "informational" | "navigational";
+export interface GeneratedKeyword {
+    keyword: string;
+    exactMatch: string;
+    phraseMatch: string;
+    intent: SearchIntentType;
+    product: string;
+    modifier?: string;
+    location?: string;
+}
+export interface PermutatorOptions {
+    products: string[];
+    words?: string[];
+    locations?: string[];
+    maxCombinations?: number;
+}
+export declare class KeywordPermutatorEngine {
+    /**
+     * Generates a combinatorial matrix of keywords.
+     */
+    static generateKeywordMatrix(options: PermutatorOptions): GeneratedKeyword[];
+}

package/dist/urlytics-engine.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 🔍 Universal URL Analytics & Structural Decomposition Engine
+ * Inspired by advertools.urlytics
+ *
+ * Breaks down any URL into structured path segments, query parameters, directory depths,
+ * and slug tokens for crawl validation, audit logs, and programmatic matrix matching.
+ */
+export interface ParsedUrlStructure {
+    url: string;
+    scheme: string;
+    domain: string;
+    path: string;
+    depth: number;
+    dir1?: string;
+    dir2?: string;
+    dir3?: string;
+    lastDir: string;
+    queryParams: Record<string, string>;
+    hashFragment?: string;
+    slugTokens: string[];
+    charCount: number;
+    hasTrailingSlash: boolean;
+}
+export declare class UrlyticsEngine {
+    /**
+     * Parses a single URL into its granular structural components.
+     */
+    static parseUrl(rawUrl: string): ParsedUrlStructure;
+    /**
+     * Batch processes an array of URLs for comparative directory analysis.
+     */
+    static analyzeUrls(urls: string[]): ParsedUrlStructure[];
+}

package/package.json

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

package/src/engine.test.ts

@@ -4,6 +4,9 @@ import { LegalDisclaimerEngine, MULTILINGUAL_BANNED_DISPARAGING_WORDS } from "./
 import { ExtendedSchemaGraphBuilder } from "./extended-schemas";
 import { PseoMatrixEngine } from "./matrix-engine";
 import { getSeoAgentPrompt } from "./llm-prompt";
+import { UrlyticsEngine } from "./urlytics-engine";
+import { KeywordPermutatorEngine } from "./keyword-permutator";
+import { renderBrandIconSvg } from "./brand-icons";
 
 describe("Multilingual SEO Slug Engine (10+ Languages)", () => {
   it("English: Strips stop words and years", () => {
@@ -134,3 +137,53 @@ describe("Master Programmatic Matrix Engine (English Default)", () => {
     expect(prompt).toContain("Schema.org");
   });
 });
+
+describe("Audited Reference Engines (Advertools, Santifer, Seonaut)", () => {
+  it("UrlyticsEngine: Parses and decomposes URL hierarchy", () => {
+    const parsed = UrlyticsEngine.parseUrl("https://acme.com/solutions/crm/fr/paris?src=seo&ref=top#pricing");
+    expect(parsed.domain).toBe("acme.com");
+    expect(parsed.depth).toBe(4);
+    expect(parsed.dir1).toBe("solutions");
+    expect(parsed.lastDir).toBe("paris");
+    expect(parsed.queryParams.src).toBe("seo");
+    expect(parsed.hashFragment).toBe("pricing");
+  });
+
+  it("KeywordPermutatorEngine: Generates combinatorial SEM matrix with intent", () => {
+    const matrix = KeywordPermutatorEngine.generateKeywordMatrix({
+      products: ["crm", "billing"],
+      words: ["best", "pricing"],
+      locations: ["paris"],
+    });
+    expect(matrix.length).toBeGreaterThan(5);
+    const hasBestCrm = matrix.some((k) => k.keyword === "best crm" && k.intent === "commercial");
+    expect(hasBestCrm).toBe(true);
+  });
+
+  it("BrandIcons: Resolves official SVG vector for Shopify, Facebook, Slack", () => {
+    const shopifySvg = renderBrandIconSvg("shopify");
+    expect(shopifySvg).toContain("<svg");
+    expect(shopifySvg).toContain("viewBox");
+
+    const fbSvg = renderBrandIconSvg("facebook");
+    expect(fbSvg).toContain("<svg");
+  });
+
+  it("ExtendedSchemas: Builds AggregateRating and AggregateOffer (Santifer model)", () => {
+    const rating = ExtendedSchemaGraphBuilder.buildAggregateRating({
+      itemReviewedName: "Acme CRM",
+      ratingValue: 4.9,
+      reviewCount: 1280,
+    });
+    expect(rating["@type"]).toBe("AggregateRating");
+    expect(rating.ratingValue).toBe(4.9);
+
+    const offer = ExtendedSchemaGraphBuilder.buildAggregateOffer({
+      lowPrice: 29,
+      highPrice: 99,
+      currency: "EUR",
+    });
+    expect(offer["@type"]).toBe("AggregateOffer");
+    expect(offer.lowPrice).toBe("29");
+  });
+});

package/src/extended-schemas.ts

@@ -276,4 +276,102 @@ export class ExtendedSchemaGraphBuilder {
       })),
     };
   }
+
+  /**
+   * 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> {
+    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,
+      },
+    };
+  }
+
+  /**
+   * 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> {
+    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",
+    };
+  }
+
+  /**
+   * 9. Service with ServiceArea & Providers
+   */
+  static buildService(opts: {
+    name: string;
+    description: string;
+    providerName: string;
+    areaServed?: string[];
+    serviceType?: string;
+  }): Record<string, unknown> {
+    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,
+    };
+  }
+
+  /**
+   * 10. WebSite with Google Sitelinks SearchBox
+   */
+  static buildWebSite(opts: {
+    name: string;
+    url: string;
+    searchUrlTemplate?: string;
+  }): Record<string, unknown> {
+    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,
+    };
+  }
 }

package/src/index.ts

@@ -15,6 +15,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/src/keyword-permutator.ts

@@ -0,0 +1,118 @@
+/**
+ * ⚡ High-Speed Keyword Permutator & SEM Matrix Engine
+ * Inspired by advertools.kw_generate
+ *
+ * Generates all permutations and combinations of Products × Modifiers × Intents × Locations
+ * with match types (Broad, Phrase, Exact) and estimated search intent tagging.
+ */
+
+export type SearchIntentType = "commercial" | "transactional" | "informational" | "navigational";
+
+export interface GeneratedKeyword {
+  keyword: string;
+  exactMatch: string;
+  phraseMatch: string;
+  intent: SearchIntentType;
+  product: string;
+  modifier?: string;
+  location?: string;
+}
+
+export interface PermutatorOptions {
+  products: string[];
+  words?: string[];
+  locations?: string[];
+  maxCombinations?: number;
+}
+
+export class KeywordPermutatorEngine {
+  /**
+   * Generates a combinatorial matrix of keywords.
+   */
+  static generateKeywordMatrix(options: PermutatorOptions): GeneratedKeyword[] {
+    const { products, words = [], locations = [], maxCombinations = 5000 } = options;
+    const results: GeneratedKeyword[] = [];
+
+    const intentKeywords: Record<SearchIntentType, string[]> = {
+      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: string): SearchIntentType => {
+      const lower = text.toLowerCase();
+      for (const [intent, triggers] of Object.entries(intentKeywords) as [SearchIntentType, string[]][]) {
+        if (triggers.some((t) => lower.includes(t))) {
+          return intent;
+        }
+      }
+      return "commercial";
+    };
+
+    for (const prod of products) {
+      // 1. Product alone
+      results.push({
+        keyword: prod,
+        exactMatch: `[${prod}]`,
+        phraseMatch: `"${prod}"`,
+        intent: detectIntent(prod),
+        product: prod,
+      });
+
+      // 2. Product × Words / Modifiers
+      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,
+        });
+
+        // 3. Product × Words × Locations
+        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;
+  }
+}

package/src/urlytics-engine.ts

@@ -0,0 +1,97 @@
+/**
+ * 🔍 Universal URL Analytics & Structural Decomposition Engine
+ * Inspired by advertools.urlytics
+ *
+ * Breaks down any URL into structured path segments, query parameters, directory depths,
+ * and slug tokens for crawl validation, audit logs, and programmatic matrix matching.
+ */
+
+export interface ParsedUrlStructure {
+  url: string;
+  scheme: string;
+  domain: string;
+  path: string;
+  depth: number;
+  dir1?: string;
+  dir2?: string;
+  dir3?: string;
+  lastDir: string;
+  queryParams: Record<string, string>;
+  hashFragment?: string;
+  slugTokens: string[];
+  charCount: number;
+  hasTrailingSlash: boolean;
+}
+
+export class UrlyticsEngine {
+  /**
+   * Parses a single URL into its granular structural components.
+   */
+  static parseUrl(rawUrl: string): ParsedUrlStructure {
+    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: Record<string, string> = {};
+
+      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,
+      };
+    }
+  }
+
+  /**
+   * Batch processes an array of URLs for comparative directory analysis.
+   */
+  static analyzeUrls(urls: string[]): ParsedUrlStructure[] {
+    return urls.map((u) => this.parseUrl(u));
+  }
+}