@lynxflow/seo-engine 1.0.0 → 1.3.0

package/src/types.ts

@@ -1,48 +1,168 @@
 /**
- * 🌟 Types & Interfaces for @lynxflow/seo-engine SDK
+ * 🌟 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 {
-  licenseKey: string;
+  apiKey?: string;
+  licenseKey?: string; // Deprecated: use apiKey
   domain: string;
   brandName: string;
   category?: string;
+  defaultLocale?: string;
+  supportedLocales?: string[];
   currency?: string;
   currencySymbol?: string;
-  services: {
-    slug: string;
-    name: string;
-    description: string;
-    pricePerMonth: number;
-  }[];
-  niches?: {
-    slug: string;
-    name: string;
-  }[];
+  services: LynxServiceDefinition[];
+  industries?: PseoIndustry[];
+  competitors?: PseoCompetitor[];
+  integrations?: PseoIntegration[];
+  personas?: PseoPersona[];
+  useCases?: PseoUseCase[];
+  cities?: PseoCity[];
 }
 
 export interface LynxResolvedPage {
-  urlPath: string;
-  fullUrl: string;
-  meta: {
+  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;
+
+  // Localized ROI data (when applicable)
+  localizedRoi?: {
+    monthlySavingsFormatted: string;
+    hoursSavedWeekly: number;
+    annualSavingsFormatted: string;
+    currencySymbol: string;
+  };
+
+  // Structured component data
+  service?: LynxServiceDefinition;
+  industry?: PseoIndustry;
+  competitor?: PseoCompetitor;
+  integration?: PseoIntegration;
+
+  meta?: {
     title: string;
     description: string;
     h1: string;
     canonical: string;
-    openGraphImageUrl: string;
+    openGraphImageUrl?: string;
+  };
+
+  // Backward compatibility convenience fields
+  fullUrl?: string;
+  schemaJsonLd?: Record<string, unknown>;
+  content?: {
+    directAnswerGeoHtml?: string;
+    heroHeadline?: string;
+    heroSubheadline?: string;
+    markdownBody?: string;
+    faqList?: { question: string; answer: string }[];
   };
-  schemaJsonLd: any;
-  content: {
-    directAnswerGeoHtml: string;
-    heroHeadline: string;
-    heroSubheadline: string;
-    markdownBody: string;
-    faqList: { question: string; answer: string }[];
-    neighboringLinks: { name: string; url: string }[];
+  pricing?: {
+    priceNumber?: number;
+    priceFormatted?: string;
+    currency?: string;
   };
-  pricing: {
-    priceNumber: number;
-    priceFormatted: string;
+
+  debug?: {
+    licenseStatus?: "active" | "trial" | "expired" | "offline_mode";
+    generationMs?: number;
+    matrixType?: string;
   };
-  executionTimeMs: number;
 }

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}

package/src/licensing.ts

@@ -1,138 +0,0 @@
-/**
- * 🔒 LynxFlow License Key Guardian & Cryptographic Issuer
- * 
- * Manages enterprise cryptographic license keys, HMAC signatures,
- * tenant quota boundaries, and subscription status synchronization with Lago & Hyperswitch.
- */
-
-import { TokenQuotaManager } from "./token-quota-manager";
-
-export interface LicenseValidationResult {
-  isValid: boolean;
-  tier: "starter" | "growth" | "enterprise";
-  tenantId?: string;
-  maxPages: number;
-  monthlyCreditBudget: number;
-  tokenManager: TokenQuotaManager;
-  subscriptionStatus: "active" | "trialing" | "past_due" | "canceled";
-  expiresAt?: string;
-  errorMessage?: string;
-}
-
-export class LicenseGuardian {
-  /**
-   * Generates a cryptographically signed license key for a tenant.
-   * Format: lynx_<tier>_<tenantId>_<shortChecksum>
-   */
-  static generateKey(tenantId: string, tier: "starter" | "growth" | "enterprise" = "growth", secret = "lynxflow_secret_key"): string {
-    const raw = `${tenantId}:${tier}:${secret}`;
-    let hash = 0;
-    for (let i = 0; i < raw.length; i++) {
-      hash = ((hash << 5) - hash) + raw.charCodeAt(i);
-      hash |= 0;
-    }
-    const checksum = Math.abs(hash).toString(36).substring(0, 6);
-    return `lynx_${tier}_${tenantId}_${checksum}`;
-  }
-
-  /**
-   * Fast offline/online license validator with HMAC parsing.
-   */
-  static validateKey(licenseKey?: string, secret = "lynxflow_secret_key"): LicenseValidationResult {
-    if (!licenseKey || typeof licenseKey !== "string") {
-      return {
-        isValid: false,
-        tier: "starter",
-        maxPages: 100,
-        monthlyCreditBudget: 500,
-        subscriptionStatus: "canceled",
-        tokenManager: new TokenQuotaManager("starter"),
-        errorMessage: "Missing or invalid LynxFlow license key. Please set LYNXFLOW_LICENSE_KEY or pass licenseKey in config.",
-      };
-    }
-
-    const cleanKey = licenseKey.trim();
-    const parts = cleanKey.split("_");
-    // Extract tenantId preserving internal underscores: lynx_<tier>_<tenantId>_<checksum>
-    const tenantId = parts.length >= 4 ? parts.slice(2, -1).join("_") : (parts.length >= 3 ? parts[2] : "default_tenant");
-
-    // 1. Enterprise / Internal master keys
-    if (cleanKey.startsWith("lynx_enterprise_") || cleanKey.startsWith("lynx_live_") || cleanKey.startsWith("lynx_ent_")) {
-      return {
-        isValid: true,
-        tier: "enterprise",
-        tenantId,
-        maxPages: 5_000_000,
-        monthlyCreditBudget: 50_000,
-        subscriptionStatus: "active",
-        tokenManager: new TokenQuotaManager("enterprise"),
-      };
-    }
-
-    // 2. Growth Tier keys
-    if (cleanKey.startsWith("lynx_growth_")) {
-      return {
-        isValid: true,
-        tier: "growth",
-        tenantId,
-        maxPages: 500_000,
-        monthlyCreditBudget: 5_000,
-        subscriptionStatus: "active",
-        tokenManager: new TokenQuotaManager("growth"),
-      };
-    }
-
-    // 3. Starter / Trial keys
-    if (cleanKey.startsWith("lynx_starter_") || cleanKey.startsWith("lynx_test_")) {
-      return {
-        isValid: true,
-        tier: "starter",
-        tenantId,
-        maxPages: 10_000,
-        monthlyCreditBudget: 500,
-        subscriptionStatus: "trialing",
-        tokenManager: new TokenQuotaManager("starter"),
-      };
-    }
-
-    return {
-      isValid: false,
-      tier: "starter",
-      maxPages: 0,
-      monthlyCreditBudget: 0,
-      subscriptionStatus: "canceled",
-      tokenManager: new TokenQuotaManager("starter"),
-      errorMessage: "Unrecognized or corrupted LynxFlow license key signature.",
-    };
-  }
-
-  /**
-   * Online real-time verification against LynxFlow's central API (optional).
-   */
-  static async verifyOnline(licenseKey: string, apiEndpoint = "https://api.lynxintel.io/api/license/verify"): Promise<LicenseValidationResult> {
-    const offlineResult = this.validateKey(licenseKey);
-    if (!offlineResult.isValid) return offlineResult;
-
-    try {
-      const res = await fetch(apiEndpoint, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ licenseKey }),
-        signal: AbortSignal.timeout(3000),
-      });
-
-      if (res.ok) {
-        const data = await res.json();
-        return {
-          ...offlineResult,
-          isValid: data.isValid ?? true,
-          subscriptionStatus: data.status ?? "active",
-        };
-      }
-    } catch {
-      // Graceful offline fallback: keep valid offline result if network is temporarily unreachable
-    }
-
-    return offlineResult;
-  }
-}