@lynxflow/seo-engine 2.0.0 → 2.0.1

package/README.md

@@ -1,18 +1,19 @@
 # @lynxflow/seo-engine
 
-High-Performance Programmatic SEO & Structured Data Engine for Modern Web Applications.
+High-Performance Universal Programmatic SEO & Structured Data Engine for Modern Web Applications.
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Proprietary-green.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/Version-2.0.0-orange.svg)](package.json)
+[![Version](https://img.shields.io/badge/Version-2.0.0-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
 
 ---
 
 ## Overview
 
-`@lynxflow/seo-engine` is an enterprise developer SDK providing in-memory programmatic SEO matrix generation, Google-compliant Schema.org structured data, infinite geographic location synthesis, and real-time GeoIP Edge detection worldwide.
+`@lynxflow/seo-engine` is an enterprise developer SDK providing in-memory programmatic SEO matrix generation, Google-compliant Schema.org structured data, infinite geographic location synthesis, strict market boundaries, and real-time GeoIP Edge detection worldwide.
 
 * **10 Canonical Root Pillars & 50+ Specialized Sub-Matrices:** Scales across industries, regulatory frameworks, role KPIs, multi-format templates, integration ecosystems, and ROI tools.
+* **Strict Geographic & Linguistic Scoping:** Easily lock your website to a single country (e.g. 100% US or 100% France) or expand globally across multiple languages and territories with `strictCountryBoundary`.
 * **In-Memory Dynamic Execution:** Resolves millions of programmatic routes in RAM with zero database query overhead and zero MySQL/Postgres saturation.
 * **Infinite Geographic Resolution (`createDynamicLocation`):** Dynamically synthesizes any municipality, county, state, or postal code worldwide (e.g. `austin`, `scottsdale`, `75015`, `90210`, `ec1a-1bb`, `shinjuku`) on the fly without 404 errors.
 * **Edge GeoIP Location Detection (`resolveLocationFromHeaders`):** Reads Cloudflare (`cf-ipcity`, `cf-postal-code`), Vercel, AWS CloudFront, and Nginx edge headers to adapt pages to the visitor's real-time location.
@@ -34,33 +35,36 @@ bun add @lynxflow/seo-engine
 
 ---
 
-## Core Matrix Architecture
+## Market Scoping: Single Country vs. Global Multi-Country
 
-The SDK structures programmatic content across **10 canonical root pillars** expanding into **50+ specialized sub-matrices**:
+### Option 1: 100% US-Only or Local Single-Country Website
+Prevent crawl waste on out-of-scope foreign locations by enabling `strictCountryBoundary`:
 
+```typescript
+export const SEO_CONFIG = {
+  brandName: "LoneStar HVAC Pro",
+  languages: ["en"],
+  countries: ["united-states"],
+  strictCountryBoundary: true, // 🛡️ Rejects non-US locations
+  defaultCurrency: "USD",
+  defaultCurrencySymbol: "$",
+};
 ```
-┌──────────────────────────────────────┬────────────────────────┬────────────────────────────────────────────────────────┐
-│ CANONICAL ROOT PILLAR                │ SPECIALIZED DIMENSIONS │ HIGH-INTENT EXAMPLES                                   │
-├──────────────────────────────────────┼────────────────────────┼────────────────────────────────────────────────────────┤
-│ 👥 /for/{target}                     │ 12 Sub-Matrices        │ Sector × Regulatory Compliance, Role × Daily KPIs      │
-│ 🔌 /integrations/{app}               │ 10 Sub-Matrices        │ App Connector × Real-Time Webhook, Bi-Directional Sync │
-│ 📑 /templates/{slug}                 │ 8 Sub-Matrices         │ Subject × Format (Excel, Notion, Google Sheets, PDF)   │
-│ 🎯 /use-cases/{useCase}              │ 8 Sub-Matrices         │ Operational Pain Point × Step-by-Step Playbook         │
-│ 🧮 /tools/{calculator}               │ 6 Sub-Matrices         │ Hours Saved Estimator, Revenue Uplift Simulator        │
-│ 📚 /glossary/{term}                  │ 6 Sub-Matrices         │ Financial Metrics (MRR/LTV), Technical Protocols (API) │
-│ 🥊 /vs/{competitor}                  │ Optional / Modular     │ Architectural Comparison & Differences                 │
-│ 🔄 /alternatives/{competitor}        │ Optional / Modular     │ Clean Canonical Migration Guides                       │
-│ 💰 /pricing/{competitor}             │ Optional / Modular     │ Transparent Plan Breakdown & Verified Disclaimers      │
-│ 📍 /solutions/{service}/{city}       │ Local Geo Matrix       │ Tiered Indexing (Crawl Budget) & Geodesic Mesh Links   │
-└──────────────────────────────────────┴────────────────────────┴────────────────────────────────────────────────────────┘
+
+### Option 2: Worldwide Multi-Country / Multi-Lingual SaaS
+```typescript
+export const SEO_CONFIG = {
+  brandName: "Apex Global Cloud",
+  languages: ["en", "de", "es", "fr", "ja", "pt-BR"],
+  countries: ["united-states", "united-kingdom", "germany", "france", "japan"],
+  strictCountryBoundary: false, // Allows worldwide expansion
+};
 ```
 
 ---
 
 ## Quickstart & Contrasting Examples
 
-> **Important Note:** All examples below are **non-limiting illustrations**. You can pass any arbitrary language code and any arbitrary city or postal code worldwide.
-
 ### 1. Initialize Engine & Dataset
 
 ```typescript
@@ -68,14 +72,6 @@ import { PseoMatrixEngine } from "@lynxflow/seo-engine";
 
 export const matrixEngine = new PseoMatrixEngine();
 
-// Non-limiting example configuration (Supports ANY country or locale)
-export const SEO_CONFIG = {
-  brandName: "Apex Global",
-  languages: ["en", "de", "es", "fr", "ja", "pt-BR"], // Any ISO-639-1 / BCP-47 locale
-  countries: ["united-states", "united-kingdom", "germany", "japan"], // Or "international" / any country
-  cleanDirectRoutes: true,
-};
-
 export const PSEO_DATASET = {
   services: [
     { 
@@ -93,10 +89,6 @@ export const PSEO_DATASET = {
       description: "Continuous enterprise backup and disaster recovery" 
     },
   ],
-  targets: [
-    { slug: "enterprises", name: "Enterprise Organizations", type: "b2b", painPoints: ["Downtime Risk"], benefits: ["99.99% SLA"] },
-    { slug: "healthcare", name: "Healthcare Providers", type: "industry", painPoints: ["HIPAA Compliance"], benefits: ["Audit-Ready Storage"] }
-  ],
 };
 ```
 
@@ -104,11 +96,10 @@ export const PSEO_DATASET = {
 
 ```typescript
 // Case 1: Standard Pre-Indexed City in English
-const pageStandard = matrixEngine.resolvePage(["commercial-hvac", "london"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
+const pageStandard = matrixEngine.resolvePage(["commercial-hvac", "new-york"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
 
-// Case 2: Contrasting Case — Arbitrary Postal Code / Custom District in Japanese
+// Case 2: Contrasting Case — Arbitrary Postal Code / Custom District
 const pageCustom = matrixEngine.resolvePage(["commercial-hvac", "90210"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
-const pageJapanese = matrixEngine.resolvePage(["ja", "commercial-hvac", "shinjuku"], "https://example.com", PSEO_DATASET, SEO_CONFIG);
 ```
 
 ### 3. Edge GeoIP Resolution Example
@@ -118,7 +109,6 @@ import { resolveLocationFromHeaders, PseoMatrixEngine } from "@lynxflow/seo-engi
 
 export function handleIncomingRequest(request: Request) {
   const geo = resolveLocationFromHeaders(request.headers);
-  // Extracted dynamically from Cloudflare / Vercel / CloudFront headers
   const userCity = geo.city || "new-york";
   
   return matrixEngine.resolvePage(["commercial-hvac", userCity], "https://example.com", PSEO_DATASET, SEO_CONFIG);
@@ -129,11 +119,10 @@ export function handleIncomingRequest(request: Request) {
 
 ## TypeScript API Reference
 
-* **`PseoMatrixEngine`**: Core programmatic matrix compiler across all 10 root pillars and 50+ sub-matrices.
-* **`createDynamicLocation(slugOrInput, fallbackCountry)`**: Dynamic synthesis of any city, postal code or district worldwide at runtime.
+* **`PseoMatrixEngine`**: Core programmatic matrix compiler with geographic boundaries and crawl budget protection.
+* **`createDynamicLocation(slugOrInput, fallbackCountry, options)`**: Dynamic synthesis of any city, postal code or district worldwide.
 * **`resolveLocationFromHeaders(headers)`**: Edge header GeoIP extractor for Cloudflare, Vercel, CloudFront, and Nginx.
 * **`cleanSeoSlug(text, options)`**: Multilingual slug normalizer with stop-word removal for 10+ languages.
-* **`validateSeoSlug(slug)`**: Strict slug validator.
 * **`ExtendedSchemaGraphBuilder`**: 50+ Google Rich Result Schema.org JSON-LD generator.
 * **`LegalDisclaimerEngine`**: Verified compliance notice manager with staleness guards (>90 days).
 * **`getSeoAgentPrompt(context)`**: Built-in LLM operational prompt for AI coding agents.

package/dist/built-in-locations.d.ts

@@ -15,7 +15,11 @@ export declare function resolveBuiltInLocations(territories?: string[] | string)
  * Allows resolving ANY unlisted city, commune, district, or postal code dynamically on demand
  * without returning 404 or requiring hardcoded databases.
  */
-export declare function createDynamicLocation(slugOrInput: string, fallbackCountry?: string): PseoLocation;
+export declare function createDynamicLocation(slugOrInput: string, fallbackCountry?: string, options?: {
+    currency?: string;
+    currencySymbol?: string;
+    region?: string;
+}): PseoLocation;
 /**
  * 📍 GeoIP Edge Headers Resolver (Dynamic User Geolocation)
  * Extracts the user's real-time city and country from Cloudflare / Vercel / Nginx Edge headers.

package/dist/index.js

@@ -3524,26 +3524,43 @@ function resolveBuiltInLocations(territories) {
       }
     }
   }
-  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.fr];
+  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.us];
 }
-function createDynamicLocation(slugOrInput, fallbackCountry = "France") {
+function createDynamicLocation(slugOrInput, fallbackCountry = "United States", options) {
   const cleanInput = slugOrInput.trim().toLowerCase();
   const slug = cleanInput.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const formattedName = slug.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-  const isPostalCode = /^\d{4,5}$/.test(cleanInput);
-  const displayName = isPostalCode ? `Secteur ${cleanInput}` : formattedName;
-  const isUS = fallbackCountry.toLowerCase().includes("us") || fallbackCountry.toLowerCase().includes("state");
-  const isUK = fallbackCountry.toLowerCase().includes("uk") || fallbackCountry.toLowerCase().includes("kingdom");
+  const isUsZip = /^\d{5}(-\d{4})?$/.test(cleanInput);
+  const isFrenchPostal = /^\d{5}$/.test(cleanInput) && (fallbackCountry.toLowerCase().includes("fr") || fallbackCountry.toLowerCase().includes("france"));
+  let displayName = formattedName;
+  let regionName = options?.region || "Metropolitan Area";
+  if (isUsZip) {
+    displayName = `Area ${cleanInput}`;
+    regionName = `ZIP Code ${cleanInput}`;
+  } else if (isFrenchPostal) {
+    displayName = `Secteur ${cleanInput}`;
+    regionName = `Département ${cleanInput.slice(0, 2)}`;
+  }
+  const countryLower = fallbackCountry.toLowerCase();
+  const isUS = countryLower.includes("us") || countryLower.includes("state") || countryLower.includes("america");
+  const isUK = countryLower.includes("uk") || countryLower.includes("kingdom") || countryLower.includes("britain");
+  const isJapan = countryLower.includes("japan") || countryLower.includes("jp") || countryLower.includes("tokyo");
+  const isCanada = countryLower.includes("canada") || countryLower.includes("ca");
+  const isAustralia = countryLower.includes("australia") || countryLower.includes("au");
+  const isBrazil = countryLower.includes("brazil") || countryLower.includes("br") || countryLower.includes("brasil");
+  const isSwitzerland = countryLower.includes("switzerland") || countryLower.includes("swiss") || countryLower.includes("ch");
+  const currency = options?.currency || (isUS ? "USD" : isUK ? "GBP" : isJapan ? "JPY" : isCanada ? "CAD" : isAustralia ? "AUD" : isBrazil ? "BRL" : isSwitzerland ? "CHF" : "EUR");
+  const currencySymbol = options?.currencySymbol || (isUS ? "$" : isUK ? "£" : isJapan ? "¥" : isCanada ? "CAD $" : isAustralia ? "AUD $" : isBrazil ? "R$" : isSwitzerland ? "CHF" : "€");
   return {
     slug,
     name: displayName,
-    region: isPostalCode ? `Département ${cleanInput.slice(0, 2)}` : "Région Métropolitaine",
+    region: regionName,
     country: fallbackCountry,
-    currency: isUS ? "USD" : isUK ? "GBP" : "EUR",
-    currencySymbol: isUS ? "$" : isUK ? "£" : "€",
-    population: 45000,
-    latitude: 48.8566,
-    longitude: 2.3522,
+    currency,
+    currencySymbol,
+    population: 50000,
+    latitude: 40.7128,
+    longitude: -74.006,
     neighborSlugs: []
   };
 }
@@ -4205,7 +4222,18 @@ class PseoMatrixEngine {
       const locationSlug = segments[segments.length - 1];
       const matchedService = data.services.find((s) => cleanSeoSlug(s.slug, { language: options.language }) === serviceSlug || s.slug === serviceSlug);
       if (matchedService) {
-        const dynamicLoc = createDynamicLocation(locationSlug, options.countries?.[0] || "France");
+        const countryList = options.allowedCountries || options.countries;
+        const fallbackCountry = Array.isArray(countryList) ? countryList[0] : typeof countryList === "string" && countryList !== "international" ? countryList : "United States";
+        const dynamicLoc = createDynamicLocation(locationSlug, fallbackCountry, {
+          currency: options.defaultCurrency,
+          currencySymbol: options.defaultCurrencySymbol
+        });
+        if (options.strictCountryBoundary && countryList) {
+          const allowed = (Array.isArray(countryList) ? countryList : [countryList]).map((c) => c.toLowerCase());
+          if (!allowed.includes("international") && !allowed.some((c) => dynamicLoc.country.toLowerCase().includes(c))) {
+            return;
+          }
+        }
         const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [dynamicLoc], options);
         return dynamicPages.find((p) => p.urlPath === path) || dynamicPages[0];
       }

package/dist/index.mjs

@@ -3524,26 +3524,43 @@ function resolveBuiltInLocations(territories) {
       }
     }
   }
-  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.fr];
+  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.us];
 }
-function createDynamicLocation(slugOrInput, fallbackCountry = "France") {
+function createDynamicLocation(slugOrInput, fallbackCountry = "United States", options) {
   const cleanInput = slugOrInput.trim().toLowerCase();
   const slug = cleanInput.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const formattedName = slug.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-  const isPostalCode = /^\d{4,5}$/.test(cleanInput);
-  const displayName = isPostalCode ? `Secteur ${cleanInput}` : formattedName;
-  const isUS = fallbackCountry.toLowerCase().includes("us") || fallbackCountry.toLowerCase().includes("state");
-  const isUK = fallbackCountry.toLowerCase().includes("uk") || fallbackCountry.toLowerCase().includes("kingdom");
+  const isUsZip = /^\d{5}(-\d{4})?$/.test(cleanInput);
+  const isFrenchPostal = /^\d{5}$/.test(cleanInput) && (fallbackCountry.toLowerCase().includes("fr") || fallbackCountry.toLowerCase().includes("france"));
+  let displayName = formattedName;
+  let regionName = options?.region || "Metropolitan Area";
+  if (isUsZip) {
+    displayName = `Area ${cleanInput}`;
+    regionName = `ZIP Code ${cleanInput}`;
+  } else if (isFrenchPostal) {
+    displayName = `Secteur ${cleanInput}`;
+    regionName = `Département ${cleanInput.slice(0, 2)}`;
+  }
+  const countryLower = fallbackCountry.toLowerCase();
+  const isUS = countryLower.includes("us") || countryLower.includes("state") || countryLower.includes("america");
+  const isUK = countryLower.includes("uk") || countryLower.includes("kingdom") || countryLower.includes("britain");
+  const isJapan = countryLower.includes("japan") || countryLower.includes("jp") || countryLower.includes("tokyo");
+  const isCanada = countryLower.includes("canada") || countryLower.includes("ca");
+  const isAustralia = countryLower.includes("australia") || countryLower.includes("au");
+  const isBrazil = countryLower.includes("brazil") || countryLower.includes("br") || countryLower.includes("brasil");
+  const isSwitzerland = countryLower.includes("switzerland") || countryLower.includes("swiss") || countryLower.includes("ch");
+  const currency = options?.currency || (isUS ? "USD" : isUK ? "GBP" : isJapan ? "JPY" : isCanada ? "CAD" : isAustralia ? "AUD" : isBrazil ? "BRL" : isSwitzerland ? "CHF" : "EUR");
+  const currencySymbol = options?.currencySymbol || (isUS ? "$" : isUK ? "£" : isJapan ? "¥" : isCanada ? "CAD $" : isAustralia ? "AUD $" : isBrazil ? "R$" : isSwitzerland ? "CHF" : "€");
   return {
     slug,
     name: displayName,
-    region: isPostalCode ? `Département ${cleanInput.slice(0, 2)}` : "Région Métropolitaine",
+    region: regionName,
     country: fallbackCountry,
-    currency: isUS ? "USD" : isUK ? "GBP" : "EUR",
-    currencySymbol: isUS ? "$" : isUK ? "£" : "€",
-    population: 45000,
-    latitude: 48.8566,
-    longitude: 2.3522,
+    currency,
+    currencySymbol,
+    population: 50000,
+    latitude: 40.7128,
+    longitude: -74.006,
     neighborSlugs: []
   };
 }
@@ -4205,7 +4222,18 @@ class PseoMatrixEngine {
       const locationSlug = segments[segments.length - 1];
       const matchedService = data.services.find((s) => cleanSeoSlug(s.slug, { language: options.language }) === serviceSlug || s.slug === serviceSlug);
       if (matchedService) {
-        const dynamicLoc = createDynamicLocation(locationSlug, options.countries?.[0] || "France");
+        const countryList = options.allowedCountries || options.countries;
+        const fallbackCountry = Array.isArray(countryList) ? countryList[0] : typeof countryList === "string" && countryList !== "international" ? countryList : "United States";
+        const dynamicLoc = createDynamicLocation(locationSlug, fallbackCountry, {
+          currency: options.defaultCurrency,
+          currencySymbol: options.defaultCurrencySymbol
+        });
+        if (options.strictCountryBoundary && countryList) {
+          const allowed = (Array.isArray(countryList) ? countryList : [countryList]).map((c) => c.toLowerCase());
+          if (!allowed.includes("international") && !allowed.some((c) => dynamicLoc.country.toLowerCase().includes(c))) {
+            return;
+          }
+        }
         const dynamicPages = this.generateLocalGeoMatrix(domain, [matchedService], [dynamicLoc], options);
         return dynamicPages.find((p) => p.urlPath === path) || dynamicPages[0];
       }

package/dist/matrix-engine.d.ts

@@ -131,7 +131,10 @@ export interface MatrixOptions {
     brandName: string;
     language?: string;
     languages?: string[];
+    allowedLanguages?: string[] | string;
     countries?: string[] | string;
+    allowedCountries?: string[] | string;
+    strictCountryBoundary?: boolean;
     territories?: string[] | string;
     cleanDirectRoutes?: boolean;
     enableFreeTools?: boolean;

package/package.json

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