@lynxflow/seo-engine 1.0.0 → 1.2.0

package/dist/src/token-quota-manager.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 🪙 Token Quota & Credit Billing Bridge
+ *
+ * Synchronizes with LynxFlow's official TokenBillingService & CreditService (1$ = 100 credits).
+ * Manages tenant monthly quotas, OpenRouter raw provider costs, and credit balances.
+ */
+export interface TokenUsageRecord {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    creditsCharged: number;
+    model: string;
+    timestamp: string;
+}
+export interface CreditQuotaStatus {
+    tier: "starter" | "growth" | "enterprise";
+    monthlyCreditBudget: number;
+    usedCredits: number;
+    remainingCredits: number;
+    isQuotaExceeded: boolean;
+}
+export declare class TokenQuotaManager {
+    private tier;
+    private monthlyCreditBudget;
+    private usedCredits;
+    constructor(tier?: "starter" | "growth" | "enterprise");
+    private resolveBudget;
+    /**
+     * Records token usage and calculates LynxFlow Credit cost (1$ = 100 credits).
+     * Only charges credits when AI call succeeds (Issue #222 fix).
+     */
+    consumeTokens(promptTokens: number, completionTokens: number, model: string, rawProviderCostUsd?: number): TokenUsageRecord;
+    /**
+     * Gets current credit quota status.
+     */
+    getStatus(): CreditQuotaStatus;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 🌟 Types & Interfaces for @lynxflow/seo-engine Universal SDK
+ *
+ * Full Institutional pSEO Type System matching LynxFlow's 8 Programmatic Matrices:
+ * 1. 📍 Local & GEO : [Pillar/Service] × [City/Country]
+ * 2. 🥊 VS & Comparatifs : [Brand/Service] vs [Competitor]
+ * 3. 🔄 Alternatives : [Competitor] ➔ [Brand/Service]
+ * 4. 🏢 Secteurs & Métiers : [Service] × [Industry Vertical] (with localized ROI)
+ * 5. 🔌 Intégrations : [Service] × [Third-party Software]
+ * 6. 👤 Personas & Décideurs : [Service] × [Decision Maker Role]
+ * 7. 🎯 Cas d'Usage : [Problem Statement] ➔ [AI Workflow Solution]
+ * 8. 🧮 Simulateurs & Outils : Interactive ROI & Time-Savings Calculators
+ */
+export interface LynxServiceDefinition {
+    slug: string;
+    name: string;
+    description?: string;
+    pricePerMonth: number;
+    category?: string;
+    features?: string[];
+    faqs?: {
+        question: string;
+        answer: string;
+    }[];
+}
+export interface PseoIndustry {
+    slug: string;
+    name: string;
+    singular: string;
+    category: string;
+    badge?: string;
+    painPoints?: string[];
+    targetSolutions?: string[];
+    roiMonthlySavings?: number;
+    hoursSavedWeekly?: number;
+    conversionBoost?: string;
+}
+export interface PseoCompetitor {
+    slug: string;
+    name: string;
+    badge?: string;
+    category: string;
+    priceRange?: string;
+    strengths?: string[];
+    weaknesses?: string[];
+    whySwitchToUs?: string[];
+}
+export interface PseoIntegration {
+    slug: string;
+    name: string;
+    category: string;
+    badge?: string;
+    syncFeatures?: string[];
+    setupTimeMinutes?: number;
+}
+export interface PseoUseCase {
+    slug: string;
+    title: string;
+    problem: string;
+    aiSolution: string;
+    measurableOutcome?: string;
+}
+export interface PseoPersona {
+    slug: string;
+    role: string;
+    department: string;
+    topResponsibilities?: string[];
+    timeWastersAutomated?: string[];
+}
+export interface PseoCity {
+    slug: string;
+    name: string;
+    region: string;
+    country: string;
+    department?: string;
+    densityTier?: "major" | "secondary" | "regional";
+}
+export interface PseoCountry {
+    code: string;
+    name: string;
+    currency: string;
+    currencySymbol: string;
+    locale: string;
+    economicMultiplier: number;
+}
+export interface LynxSeoConfig {
+    apiKey?: string;
+    licenseKey?: string;
+    domain: string;
+    brandName: string;
+    category?: string;
+    defaultLocale?: string;
+    supportedLocales?: string[];
+    currency?: string;
+    currencySymbol?: string;
+    services: LynxServiceDefinition[];
+    industries?: PseoIndustry[];
+    competitors?: PseoCompetitor[];
+    integrations?: PseoIntegration[];
+    personas?: PseoPersona[];
+    useCases?: PseoUseCase[];
+    cities?: PseoCity[];
+}
+export interface LynxResolvedPage {
+    url: string;
+    title: string;
+    description: string;
+    h1: string;
+    directAnswer: string;
+    locale?: string;
+    hreflangs?: {
+        lang: string;
+        url: string;
+    }[];
+    faqs: {
+        question: string;
+        answer: string;
+    }[];
+    jsonLd: Record<string, unknown>;
+    htmlBody: string;
+    markdownBody: string;
+    executionTimeMs: number;
+    localizedRoi?: {
+        monthlySavingsFormatted: string;
+        hoursSavedWeekly: number;
+        annualSavingsFormatted: string;
+        currencySymbol: string;
+    };
+    service?: LynxServiceDefinition;
+    industry?: PseoIndustry;
+    competitor?: PseoCompetitor;
+    integration?: PseoIntegration;
+    meta?: {
+        title: string;
+        description: string;
+        h1: string;
+        canonical: string;
+        openGraphImageUrl?: string;
+    };
+    debug?: {
+        licenseStatus: "active" | "trial" | "expired" | "offline_mode";
+        generationMs: number;
+        matrixType: string;
+    };
+}

package/dist/token-quota-manager.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 🪙 Token Quota & Credit Billing Bridge
+ *
+ * Synchronizes with LynxFlow's official TokenBillingService & CreditService (1$ = 100 credits).
+ * Manages tenant monthly quotas, OpenRouter raw provider costs, and credit balances.
+ */
+export interface TokenUsageRecord {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    creditsCharged: number;
+    model: string;
+    timestamp: string;
+}
+export interface CreditQuotaStatus {
+    tier: "starter" | "growth" | "enterprise";
+    monthlyCreditBudget: number;
+    usedCredits: number;
+    remainingCredits: number;
+    isQuotaExceeded: boolean;
+}
+export declare class TokenQuotaManager {
+    private tier;
+    private monthlyCreditBudget;
+    private usedCredits;
+    constructor(tier?: "starter" | "growth" | "enterprise");
+    private resolveBudget;
+    /**
+     * Records token usage and calculates LynxFlow Credit cost (1$ = 100 credits).
+     * Only charges credits when AI call succeeds (Issue #222 fix).
+     */
+    consumeTokens(promptTokens: number, completionTokens: number, model: string, rawProviderCostUsd?: number): TokenUsageRecord;
+    /**
+     * Gets current credit quota status.
+     */
+    getStatus(): CreditQuotaStatus;
+}

package/dist/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 🌟 Types & Interfaces for @lynxflow/seo-engine Universal SDK
+ *
+ * Full Institutional pSEO Type System matching LynxFlow's 8 Programmatic Matrices:
+ * 1. 📍 Local & GEO : [Pillar/Service] × [City/Country]
+ * 2. 🥊 VS & Comparatifs : [Brand/Service] vs [Competitor]
+ * 3. 🔄 Alternatives : [Competitor] ➔ [Brand/Service]
+ * 4. 🏢 Secteurs & Métiers : [Service] × [Industry Vertical] (with localized ROI)
+ * 5. 🔌 Intégrations : [Service] × [Third-party Software]
+ * 6. 👤 Personas & Décideurs : [Service] × [Decision Maker Role]
+ * 7. 🎯 Cas d'Usage : [Problem Statement] ➔ [AI Workflow Solution]
+ * 8. 🧮 Simulateurs & Outils : Interactive ROI & Time-Savings Calculators
+ */
+export interface LynxServiceDefinition {
+    slug: string;
+    name: string;
+    description?: string;
+    pricePerMonth: number;
+    category?: string;
+    features?: string[];
+    faqs?: {
+        question: string;
+        answer: string;
+    }[];
+}
+export interface PseoIndustry {
+    slug: string;
+    name: string;
+    singular: string;
+    category: string;
+    badge?: string;
+    painPoints?: string[];
+    targetSolutions?: string[];
+    roiMonthlySavings?: number;
+    hoursSavedWeekly?: number;
+    conversionBoost?: string;
+}
+export interface PseoCompetitor {
+    slug: string;
+    name: string;
+    badge?: string;
+    category: string;
+    priceRange?: string;
+    strengths?: string[];
+    weaknesses?: string[];
+    whySwitchToUs?: string[];
+}
+export interface PseoIntegration {
+    slug: string;
+    name: string;
+    category: string;
+    badge?: string;
+    syncFeatures?: string[];
+    setupTimeMinutes?: number;
+}
+export interface PseoUseCase {
+    slug: string;
+    title: string;
+    problem: string;
+    aiSolution: string;
+    measurableOutcome?: string;
+}
+export interface PseoPersona {
+    slug: string;
+    role: string;
+    department: string;
+    topResponsibilities?: string[];
+    timeWastersAutomated?: string[];
+}
+export interface PseoCity {
+    slug: string;
+    name: string;
+    region: string;
+    country: string;
+    department?: string;
+    densityTier?: "major" | "secondary" | "regional";
+}
+export interface PseoCountry {
+    code: string;
+    name: string;
+    currency: string;
+    currencySymbol: string;
+    locale: string;
+    economicMultiplier: number;
+}
+export interface LynxSeoConfig {
+    apiKey?: string;
+    licenseKey?: string;
+    domain: string;
+    brandName: string;
+    category?: string;
+    defaultLocale?: string;
+    supportedLocales?: string[];
+    currency?: string;
+    currencySymbol?: string;
+    services: LynxServiceDefinition[];
+    industries?: PseoIndustry[];
+    competitors?: PseoCompetitor[];
+    integrations?: PseoIntegration[];
+    personas?: PseoPersona[];
+    useCases?: PseoUseCase[];
+    cities?: PseoCity[];
+}
+export interface LynxResolvedPage {
+    url: string;
+    title: string;
+    description: string;
+    h1: string;
+    directAnswer: string;
+    locale?: string;
+    hreflangs?: {
+        lang: string;
+        url: string;
+    }[];
+    faqs: {
+        question: string;
+        answer: string;
+    }[];
+    jsonLd: Record<string, unknown>;
+    htmlBody: string;
+    markdownBody: string;
+    executionTimeMs: number;
+    localizedRoi?: {
+        monthlySavingsFormatted: string;
+        hoursSavedWeekly: number;
+        annualSavingsFormatted: string;
+        currencySymbol: string;
+    };
+    service?: LynxServiceDefinition;
+    industry?: PseoIndustry;
+    competitor?: PseoCompetitor;
+    integration?: PseoIntegration;
+    meta?: {
+        title: string;
+        description: string;
+        h1: string;
+        canonical: string;
+        openGraphImageUrl?: string;
+    };
+    fullUrl?: string;
+    schemaJsonLd?: Record<string, unknown>;
+    content?: {
+        directAnswerGeoHtml?: string;
+        heroHeadline?: string;
+        heroSubheadline?: string;
+        markdownBody?: string;
+        faqList?: {
+            question: string;
+            answer: string;
+        }[];
+    };
+    pricing?: {
+        priceNumber?: number;
+        priceFormatted?: string;
+        currency?: string;
+    };
+    debug?: {
+        licenseStatus?: "active" | "trial" | "expired" | "offline_mode";
+        generationMs?: number;
+        matrixType?: string;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynxflow/seo-engine",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Proprietary High-Performance pSEO & AI Search Engine SDK by LynxFlow",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/ai-copilot-client.ts

@@ -0,0 +1,84 @@
+/**
+ * 🤖 LynxFlow AI Content Copilot Client
+ *
+ * Generates automated long-form blog articles, landing page copywriting,
+ * FAQ expansions, and PAS framework marketing copy.
+ */
+
+export interface GenerateArticleParams {
+  topic: string;
+  targetKeywords: string[];
+  targetAudience?: string;
+  tone?: "professional" | "persuasive" | "educational";
+  wordCount?: number;
+  locale?: string;
+}
+
+export interface GeneratedArticleResult {
+  title: string;
+  metaDescription: string;
+  h1: string;
+  markdownContent: string;
+  htmlContent: string;
+  directAnswerSnippet: string;
+  faqs: { question: string; answer: string }[];
+  tokensConsumed: number;
+}
+
+export class AiCopilotClient {
+  private apiKey: string;
+  private endpoint: string;
+
+  constructor(apiKey: string, endpoint = "https://lynxintel.io/api/v1/ai") {
+    this.apiKey = apiKey;
+    this.endpoint = endpoint;
+  }
+
+  /**
+   * Generates a complete SEO article with headings, FAQs, and Schema-ready JSON.
+   */
+  async generateArticle(params: GenerateArticleParams): Promise<GeneratedArticleResult> {
+    try {
+      if (!this.apiKey || this.apiKey.startsWith("demo_")) {
+        const title = `Guide Complet : ${params.topic} en 2026`;
+        const metaDescription = `Découvrez comment maîtriser ${params.topic} avec les meilleures pratiques, outils et stratégies pour accélérer vos résultats.`;
+        const h1 = `Tout Savoir sur ${params.topic}`;
+        const directAnswer = `${params.topic} permet aux entreprises d'optimiser leurs performances grâce à des processus automatisés et une intégration fluide.`;
+
+        return {
+          title,
+          metaDescription,
+          h1,
+          directAnswerSnippet: directAnswer,
+          markdownContent: `# ${h1}\n\n${metaDescription}\n\n## 1. Pourquoi ${params.topic} est incontournable\n\nOptimiser votre stratégie avec ${params.targetKeywords.join(", ")}.\n\n## 2. Étapes de Mise en Place\n\n- Configuration initiale rapide\n- Déploiement automatisé\n- Mesure du ROI`,
+          htmlContent: `<h1>${h1}</h1><p>${metaDescription}</p><h2>1. Pourquoi ${params.topic} est incontournable</h2><p>Optimiser votre stratégie avec ${params.targetKeywords.join(", ")}.</p>`,
+          faqs: [
+            { question: `Combien de temps pour mettre en place ${params.topic} ?`, answer: "La mise en place prend généralement moins de 15 minutes." },
+            { question: "Quels sont les bénéfices immédiats ?", answer: "Gain de temps, réduction des coûts et automatisation des tâches chronophages." },
+          ],
+          tokensConsumed: 450,
+        };
+      }
+
+      const res = await fetch(`${this.endpoint}/generate-article`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.apiKey}` },
+        body: JSON.stringify(params),
+      });
+
+      if (!res.ok) throw new Error("AI Copilot API error");
+      return (await res.json()) as GeneratedArticleResult;
+    } catch {
+      return {
+        title: params.topic,
+        metaDescription: `Guide sur ${params.topic}`,
+        h1: params.topic,
+        directAnswerSnippet: `${params.topic} est essentiel en 2026.`,
+        markdownContent: `# ${params.topic}`,
+        htmlContent: `<h1>${params.topic}</h1>`,
+        faqs: [],
+        tokensConsumed: 0,
+      };
+    }
+  }
+}

package/src/analytics-client.ts

@@ -0,0 +1,141 @@
+/**
+ * 📊 LynxFlow Embedded Analytics & Web Traffic Client
+ *
+ * Tracks pageviews, visitors, sessions, Core Web Vitals, and AI Crawler Bots
+ * (ChatGPT-User, PerplexityBot, ClaudeBot, Googlebot) directly from client sites.
+ */
+
+export interface AnalyticsEventPayload {
+  path: string;
+  referrer?: string;
+  userAgent?: string;
+  country?: string;
+  durationMs?: number;
+  isAiBot?: boolean;
+  botName?: string;
+}
+
+export interface AnalyticsSummaryReport {
+  totalPageViews: number;
+  uniqueVisitors: number;
+  bounceRate: number; // 0.0 to 1.0
+  avgTimeOnPageSec: number;
+  topPages: { path: string; views: number }[];
+  aiBotVisits: { bot: string; hits: number }[];
+  trafficByCountry: { country: string; visitors: number }[];
+}
+
+export class LynxAnalyticsClient {
+  private apiKey: string;
+  private endpoint: string;
+
+  constructor(apiKey: string, endpoint = "https://lynxintel.io/api/v1/analytics") {
+    this.apiKey = apiKey;
+    this.endpoint = endpoint;
+  }
+
+  /**
+   * Identifies if a User-Agent belongs to an AI search crawler.
+   */
+  static detectAiBot(userAgent: string): { isAiBot: boolean; botName?: string } {
+    const ua = (userAgent || "").toLowerCase();
+    if (ua.includes("chatgpt-user") || ua.includes("oai-searchbot") || ua.includes("gptbot")) {
+      return { isAiBot: true, botName: "ChatGPT Search (OpenAI)" };
+    }
+    if (ua.includes("perplexitybot")) {
+      return { isAiBot: true, botName: "Perplexity AI" };
+    }
+    if (ua.includes("claudebot") || ua.includes("anthropic-ai")) {
+      return { isAiBot: true, botName: "Claude (Anthropic)" };
+    }
+    if (ua.includes("google-extended") || ua.includes("googlebot")) {
+      return { isAiBot: true, botName: "Googlebot / AI Overviews" };
+    }
+    if (ua.includes("bingbot")) {
+      return { isAiBot: true, botName: "Bingbot (Microsoft)" };
+    }
+    return { isAiBot: false };
+  }
+
+  /**
+   * Tracks a live pageview or visitor interaction.
+   */
+  async trackPageView(event: AnalyticsEventPayload): Promise<boolean> {
+    try {
+      const aiInfo = event.userAgent ? LynxAnalyticsClient.detectAiBot(event.userAgent) : { isAiBot: false };
+
+      const payload = {
+        apiKey: this.apiKey,
+        timestamp: Date.now(),
+        ...event,
+        isAiBot: event.isAiBot ?? aiInfo.isAiBot,
+        botName: event.botName ?? aiInfo.botName,
+      };
+
+      if (!this.apiKey || this.apiKey.startsWith("demo_") || this.apiKey.startsWith("lynx_starter_")) {
+        // Offline / local in-memory fallback
+        return true;
+      }
+
+      const res = await fetch(`${this.endpoint}/track`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.apiKey}` },
+        body: JSON.stringify(payload),
+      });
+
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Retrieves analytics summary and AI search traffic report for the site.
+   */
+  async getSummary(period: "24h" | "7d" | "30d" | "all" = "30d"): Promise<AnalyticsSummaryReport> {
+    try {
+      if (!this.apiKey || this.apiKey.startsWith("demo_")) {
+        // Mocked realistic default report for offline/demo usage
+        return {
+          totalPageViews: 14820,
+          uniqueVisitors: 6340,
+          bounceRate: 0.38,
+          avgTimeOnPageSec: 84,
+          topPages: [
+            { path: "/solutions/crm-pipeline/paris", views: 2450 },
+            { path: "/comparatif/crm-pipeline-vs-hubspot", views: 1890 },
+            { path: "/secteurs/crm-pipeline-pour-avocats", views: 1420 },
+          ],
+          aiBotVisits: [
+            { bot: "ChatGPT Search (OpenAI)", hits: 412 },
+            { bot: "Perplexity AI", hits: 308 },
+            { bot: "Googlebot / AI Overviews", hits: 1250 },
+          ],
+          trafficByCountry: [
+            { country: "FR", visitors: 4200 },
+            { country: "BE", visitors: 850 },
+            { country: "CH", visitors: 690 },
+            { country: "CA", visitors: 600 },
+          ],
+        };
+      }
+
+      const res = await fetch(`${this.endpoint}/summary?period=${period}`, {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      });
+
+      if (!res.ok) throw new Error("Failed to fetch analytics summary");
+      return (await res.json()) as AnalyticsSummaryReport;
+    } catch {
+      return {
+        totalPageViews: 0,
+        uniqueVisitors: 0,
+        bounceRate: 0,
+        avgTimeOnPageSec: 0,
+        topPages: [],
+        aiBotVisits: [],
+        trafficByCountry: [],
+      };
+    }
+  }
+}