@lynxflow/seo-engine 2.0.1 → 2.1.0

package/README.md

@@ -4,7 +4,7 @@ High-Performance Universal Programmatic SEO & Structured Data Engine for Modern
 
 [![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)](https://www.npmjs.com/package/@lynxflow/seo-engine)
+[![Version](https://img.shields.io/badge/Version-2.1.0-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
 
 ---
 

package/dist/generation-tracker.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 📊 Page Generation & Multi-Cycle Regeneration Tracker
+ *
+ * Tracks:
+ * 1. Unique Live Programmatic Pages in Index
+ * 2. Total Generation Cycles (Initial Creation + 2x, 3x+ Re-Optimizations)
+ * 3. Execution Mode: 'standard' (Deterministic 0€, 0 Token) vs 'ai-enhanced' (LLM Custom Copy with Token Billing)
+ * 4. Market Demand Signals & Emerging Country Opportunities (e.g. Brazil, US, Spain)
+ */
+export interface PageGenerationRecord {
+    urlPath: string;
+    service: string;
+    location: string;
+    country: string;
+    language: string;
+    generationCount: number;
+    mode: "standard" | "ai-enhanced";
+    tokensConsumed: number;
+    firstGeneratedAt: string;
+    lastGeneratedAt: string;
+}
+export interface MarketOpportunitySignal {
+    country: string;
+    countryCode: string;
+    detectedRequests: number;
+    activeIndexedPages: number;
+    coverageStatus: "optimal" | "underserved" | "opportunity_detected";
+    estimatedMonthlyTrafficUpside: number;
+    recommendation: string;
+}
+export interface GenerationMetricsReport {
+    uniquePagesCount: number;
+    totalGenerationCycles: number;
+    regenerationFrequency: {
+        singleGeneration: number;
+        doubleGeneration: number;
+        multiGeneration: number;
+    };
+    modeDistribution: {
+        standardDeterministicCount: number;
+        aiEnhancedCount: number;
+    };
+    totalAiTokensConsumed: number;
+    activeCountriesCount: number;
+    marketOpportunities: MarketOpportunitySignal[];
+}
+export declare class PageRegenerationTracker {
+    private records;
+    private demandSignals;
+    /**
+     * Records a page generation or regeneration event.
+     */
+    recordGeneration(params: {
+        urlPath: string;
+        service?: string;
+        location?: string;
+        country?: string;
+        language?: string;
+        mode?: "standard" | "ai-enhanced";
+        tokensConsumed?: number;
+    }): PageGenerationRecord;
+    /**
+     * Ingests external traffic or search demand signals (e.g. from Cloudflare / Nginx Edge / Google Search Console).
+     */
+    recordMarketDemand(country: string, requestVolume?: number): void;
+    /**
+     * Computes comprehensive analytics report for admin dashboards.
+     */
+    getMetricsReport(): GenerationMetricsReport;
+}

package/dist/index.d.ts

@@ -110,6 +110,7 @@ import { LynxRateLimitedTranslator } from "./rate-limited-translator";
 import { InternalPageRankEngine } from "./internal-pagerank-graph";
 import { GeoCitationScorer } from "./geo-citation-scorer";
 import { MarketingSkillsEngine } from "./marketing-skills-engine";
+import { PageRegenerationTracker } from "./generation-tracker";
 export declare function createLynxSeoEngine(config: EngineConfig): LynxSeoEngine;
 export declare const LynxSeo: {
     createEngine: typeof createLynxSeoEngine;
@@ -157,7 +158,9 @@ export declare const LynxSeo: {
     pageRankGraph: typeof InternalPageRankEngine;
     geoCitation: typeof GeoCitationScorer;
     marketingSkills: typeof MarketingSkillsEngine;
+    regenerationTracker: typeof PageRegenerationTracker;
 };
+export * from "./generation-tracker";
 export * from "./internal-pagerank-graph";
 export * from "./geo-citation-scorer";
 export * from "./marketing-skills-engine";

package/dist/index.js

@@ -9457,6 +9457,114 @@ class MarketingSkillsEngine {
   }
 }
 
+// src/generation-tracker.ts
+class PageRegenerationTracker {
+  records = new Map;
+  demandSignals = new Map;
+  recordGeneration(params) {
+    const key = params.urlPath.trim().toLowerCase();
+    const existing = this.records.get(key);
+    const now = new Date().toISOString();
+    const country = params.country || existing?.country || "United States";
+    const language = params.language || existing?.language || "en";
+    const service = params.service || existing?.service || "General Service";
+    const location = params.location || existing?.location || "National";
+    const mode = params.mode || "standard";
+    const tokens = params.tokensConsumed || 0;
+    if (existing) {
+      existing.generationCount += 1;
+      existing.mode = mode;
+      existing.tokensConsumed += tokens;
+      existing.lastGeneratedAt = now;
+      this.records.set(key, existing);
+      return existing;
+    }
+    const newRecord = {
+      urlPath: key,
+      service,
+      location,
+      country,
+      language,
+      generationCount: 1,
+      mode,
+      tokensConsumed: tokens,
+      firstGeneratedAt: now,
+      lastGeneratedAt: now
+    };
+    this.records.set(key, newRecord);
+    const countryKey = country.toLowerCase();
+    const currentSignal = this.demandSignals.get(countryKey) || { requests: 0, country };
+    currentSignal.requests += 1;
+    this.demandSignals.set(countryKey, currentSignal);
+    return newRecord;
+  }
+  recordMarketDemand(country, requestVolume = 1) {
+    const countryKey = country.trim().toLowerCase();
+    const current = this.demandSignals.get(countryKey) || { requests: 0, country };
+    current.requests += requestVolume;
+    this.demandSignals.set(countryKey, current);
+  }
+  getMetricsReport() {
+    let singleGen = 0;
+    let doubleGen = 0;
+    let multiGen = 0;
+    let standardCount = 0;
+    let aiCount = 0;
+    let totalTokens = 0;
+    const countriesSet = new Set;
+    const countryPageCounts = new Map;
+    for (const record of this.records.values()) {
+      if (record.generationCount === 1)
+        singleGen++;
+      else if (record.generationCount === 2)
+        doubleGen++;
+      else
+        multiGen++;
+      if (record.mode === "ai-enhanced") {
+        aiCount++;
+        totalTokens += record.tokensConsumed;
+      } else {
+        standardCount++;
+      }
+      countriesSet.add(record.country);
+      const cKey = record.country.toLowerCase();
+      countryPageCounts.set(cKey, (countryPageCounts.get(cKey) || 0) + 1);
+    }
+    const marketOpportunities = [];
+    for (const [countryKey, signal] of this.demandSignals.entries()) {
+      const indexedPages = countryPageCounts.get(countryKey) || 0;
+      const countryFormatted = signal.country.charAt(0).toUpperCase() + signal.country.slice(1);
+      if (signal.requests > 100 && indexedPages < 20) {
+        marketOpportunities.push({
+          country: countryFormatted,
+          countryCode: countryKey.slice(0, 2).toUpperCase(),
+          detectedRequests: signal.requests,
+          activeIndexedPages: indexedPages,
+          coverageStatus: "opportunity_detected",
+          estimatedMonthlyTrafficUpside: Math.round(signal.requests * 3.4),
+          recommendation: `High demand detected in ${countryFormatted} (${signal.requests} hits). Upgrade to Pro Growth or activate ${countryFormatted} in SEO_CONFIG to capture +${Math.round(signal.requests * 3.4)} visits/month.`
+        });
+      }
+    }
+    return {
+      uniquePagesCount: this.records.size,
+      totalGenerationCycles: singleGen + doubleGen * 2 + multiGen * 3,
+      regenerationFrequency: {
+        singleGeneration: singleGen,
+        doubleGeneration: doubleGen,
+        multiGeneration: multiGen
+      },
+      modeDistribution: {
+        standardDeterministicCount: standardCount,
+        aiEnhancedCount: aiCount
+      },
+      totalAiTokensConsumed: totalTokens,
+      activeCountriesCount: countriesSet.size,
+      marketOpportunities
+    };
+  }
+}
+
 // src/index.ts
 function createLynxSeoEngine(config) {
   return new LynxSeoEngine(config);
@@ -9506,7 +9614,8 @@ var LynxSeo = {
   translator: LynxRateLimitedTranslator,
   pageRankGraph: InternalPageRankEngine,
   geoCitation: GeoCitationScorer,
-  marketingSkills: MarketingSkillsEngine
+  marketingSkills: MarketingSkillsEngine,
+  regenerationTracker: PageRegenerationTracker
 };
 var src_default = LynxSeo;
 export {
@@ -9546,6 +9655,7 @@ export {
   PublicRoutesManifestEngine,
   PseoMatrixEngine,
   PowerWordsPsychologyEngine,
+  PageRegenerationTracker,
   PSEO_AGENT_SYSTEM_PROMPT,
   OgImageGenerator,
   NGramDensityAnalyzer,

package/dist/index.mjs

@@ -9457,6 +9457,114 @@ class MarketingSkillsEngine {
   }
 }
 
+// src/generation-tracker.ts
+class PageRegenerationTracker {
+  records = new Map;
+  demandSignals = new Map;
+  recordGeneration(params) {
+    const key = params.urlPath.trim().toLowerCase();
+    const existing = this.records.get(key);
+    const now = new Date().toISOString();
+    const country = params.country || existing?.country || "United States";
+    const language = params.language || existing?.language || "en";
+    const service = params.service || existing?.service || "General Service";
+    const location = params.location || existing?.location || "National";
+    const mode = params.mode || "standard";
+    const tokens = params.tokensConsumed || 0;
+    if (existing) {
+      existing.generationCount += 1;
+      existing.mode = mode;
+      existing.tokensConsumed += tokens;
+      existing.lastGeneratedAt = now;
+      this.records.set(key, existing);
+      return existing;
+    }
+    const newRecord = {
+      urlPath: key,
+      service,
+      location,
+      country,
+      language,
+      generationCount: 1,
+      mode,
+      tokensConsumed: tokens,
+      firstGeneratedAt: now,
+      lastGeneratedAt: now
+    };
+    this.records.set(key, newRecord);
+    const countryKey = country.toLowerCase();
+    const currentSignal = this.demandSignals.get(countryKey) || { requests: 0, country };
+    currentSignal.requests += 1;
+    this.demandSignals.set(countryKey, currentSignal);
+    return newRecord;
+  }
+  recordMarketDemand(country, requestVolume = 1) {
+    const countryKey = country.trim().toLowerCase();
+    const current = this.demandSignals.get(countryKey) || { requests: 0, country };
+    current.requests += requestVolume;
+    this.demandSignals.set(countryKey, current);
+  }
+  getMetricsReport() {
+    let singleGen = 0;
+    let doubleGen = 0;
+    let multiGen = 0;
+    let standardCount = 0;
+    let aiCount = 0;
+    let totalTokens = 0;
+    const countriesSet = new Set;
+    const countryPageCounts = new Map;
+    for (const record of this.records.values()) {
+      if (record.generationCount === 1)
+        singleGen++;
+      else if (record.generationCount === 2)
+        doubleGen++;
+      else
+        multiGen++;
+      if (record.mode === "ai-enhanced") {
+        aiCount++;
+        totalTokens += record.tokensConsumed;
+      } else {
+        standardCount++;
+      }
+      countriesSet.add(record.country);
+      const cKey = record.country.toLowerCase();
+      countryPageCounts.set(cKey, (countryPageCounts.get(cKey) || 0) + 1);
+    }
+    const marketOpportunities = [];
+    for (const [countryKey, signal] of this.demandSignals.entries()) {
+      const indexedPages = countryPageCounts.get(countryKey) || 0;
+      const countryFormatted = signal.country.charAt(0).toUpperCase() + signal.country.slice(1);
+      if (signal.requests > 100 && indexedPages < 20) {
+        marketOpportunities.push({
+          country: countryFormatted,
+          countryCode: countryKey.slice(0, 2).toUpperCase(),
+          detectedRequests: signal.requests,
+          activeIndexedPages: indexedPages,
+          coverageStatus: "opportunity_detected",
+          estimatedMonthlyTrafficUpside: Math.round(signal.requests * 3.4),
+          recommendation: `High demand detected in ${countryFormatted} (${signal.requests} hits). Upgrade to Pro Growth or activate ${countryFormatted} in SEO_CONFIG to capture +${Math.round(signal.requests * 3.4)} visits/month.`
+        });
+      }
+    }
+    return {
+      uniquePagesCount: this.records.size,
+      totalGenerationCycles: singleGen + doubleGen * 2 + multiGen * 3,
+      regenerationFrequency: {
+        singleGeneration: singleGen,
+        doubleGeneration: doubleGen,
+        multiGeneration: multiGen
+      },
+      modeDistribution: {
+        standardDeterministicCount: standardCount,
+        aiEnhancedCount: aiCount
+      },
+      totalAiTokensConsumed: totalTokens,
+      activeCountriesCount: countriesSet.size,
+      marketOpportunities
+    };
+  }
+}
+
 // src/index.ts
 function createLynxSeoEngine(config) {
   return new LynxSeoEngine(config);
@@ -9506,7 +9614,8 @@ var LynxSeo = {
   translator: LynxRateLimitedTranslator,
   pageRankGraph: InternalPageRankEngine,
   geoCitation: GeoCitationScorer,
-  marketingSkills: MarketingSkillsEngine
+  marketingSkills: MarketingSkillsEngine,
+  regenerationTracker: PageRegenerationTracker
 };
 var src_default = LynxSeo;
 export {
@@ -9546,6 +9655,7 @@ export {
   PublicRoutesManifestEngine,
   PseoMatrixEngine,
   PowerWordsPsychologyEngine,
+  PageRegenerationTracker,
   PSEO_AGENT_SYSTEM_PROMPT,
   OgImageGenerator,
   NGramDensityAnalyzer,

package/package.json

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