@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/keyword-merger.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 🔀 KeywordMerger
+ *
+ * Fusionne jusqu'à 19 réponses d'endpoints en un seul tableau cohérent.
+ *
+ * Règles clés :
+ * 1. Never overwrite a value that is already there. Les endpoints tournent
+ *    du plus riche au plus simple — une source plus tardive comble les trous.
+ * 2. Never let one engine's figure masquerade as another's.
+ *    Bing et Amazon volumes → clés namespaced (bing_volume, amazon_volume)
+ *    et non pas sur search_volume pour ne pas mélanger les apples et les oranges.
+ * 3. Tout ce qui n'est pas un keyword row reste sous `panels` (tendances, demographics, SERP).
+ *
+ * Pure In-Memory, 0 dépendance.
+ */
+export type MergeRow = Record<string, unknown>;
+export interface BundleRunResult {
+    type: string;
+    response: unknown;
+    error: string | null;
+    costCents?: number;
+}
+export interface SourceReport {
+    type: string;
+    label: string;
+    group: "spine" | "demand" | "cross-engine" | "serp" | "other";
+    ok: boolean;
+    contributed: number;
+    returned?: number;
+    costCents: number | null;
+    error?: string;
+}
+export interface MergedKeywordResult {
+    success: true;
+    count: number;
+    results: MergeRow[];
+    meta: {
+        seed: string | null;
+        bundle: true;
+        /** Données non-row : panels trend, demographics, SERP, autocomplete, PAA */
+        panels: Record<string, unknown>;
+        sources: SourceReport[];
+        totalCostCents: number;
+    };
+}
+export declare class KeywordMerger {
+    /**
+     * Fusionne les résultats de N endpoints en un seul tableau cohérent.
+     */
+    static merge(runs: BundleRunResult[], seed?: string): MergedKeywordResult;
+    private static groupOf;
+    /**
+     * Extrait la liste PAA (People Also Ask) depuis le panel SERP organic.
+     */
+    static extractPeopleAlsoAsk(panels: Record<string, unknown>): string[];
+    /**
+     * Extrait les suggestions autocomplete depuis le panel SERP.
+     */
+    static extractAutocomplete(panels: Record<string, unknown>): string[];
+    /**
+     * Extrait les concurrents SERP (domaines qui se classent sur tout le set).
+     */
+    static extractSerpCompetitors(panels: Record<string, unknown>): Array<{
+        domain: string;
+        avgPosition: number;
+        intersections: number;
+    }>;
+    /**
+     * Extrait les données démographiques (age/gender split).
+     */
+    static extractDemographics(panels: Record<string, unknown>): {
+        ageGroups: Array<{
+            label: string;
+            share: number;
+        }>;
+        genderSplit: {
+            male: number;
+            female: number;
+        };
+    };
+}

package/dist/keyword-permutator.d.ts

@@ -1,6 +1,5 @@
 /**
  * ⚡ 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.

package/dist/keyword-session-manager.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 💾 KeywordSessionManager
+ *
+ * Cache In-Memory de sessions de keyword research.
+ * Rouvrir un rapport existant = 0 appel API payant supplémentaire.
+ * Persistance optionnelle via localStorage (côté client) ou Map en mémoire (côté serveur).
+ *
+ * Principe clé :
+ * "Saves completed reports locally so reopening a report makes no paid API call."
+ */
+export interface KeywordSession {
+    id: string;
+    keyword: string;
+    country: string;
+    language: string;
+    createdAt: string;
+    lastAccessedAt: string;
+    totalCostCents: number;
+    endpointsRun: string[];
+    /** Résultats fusionnés (shape MergedKeywordResult) */
+    results: Record<string, unknown>;
+    /** Métadonnées de la source */
+    sources: KeywordSessionSource[];
+    status: "complete" | "partial" | "error";
+}
+export interface KeywordSessionSource {
+    type: string;
+    label: string;
+    ok: boolean;
+    contributed: number;
+    returned?: number;
+    costCents: number | null;
+    error?: string;
+}
+export interface SessionListItem {
+    id: string;
+    keyword: string;
+    country: string;
+    language: string;
+    createdAt: string;
+    totalCostCents: number;
+    keywordCount: number;
+    status: KeywordSession["status"];
+}
+export declare class KeywordSessionManager {
+    private static dragonfly;
+    /**
+     * Crée et sauvegarde une nouvelle session (sync avec background Dragonfly sync).
+     */
+    static save(session: Omit<KeywordSession, "id" | "createdAt" | "lastAccessedAt">): KeywordSession;
+    /**
+     * Crée et sauvegarde une nouvelle session en attendant la confirmation Dragonfly.
+     */
+    static saveAsync(session: Omit<KeywordSession, "id" | "createdAt" | "lastAccessedAt">): Promise<KeywordSession>;
+    /**
+     * Récupère une session par son ID. Retourne null si inexistante.
+     * → 0 appel API payant si la session existe.
+     */
+    static get(id: string): KeywordSession | null;
+    /**
+     * Récupère une session par son ID de manière asynchrone (interroge Dragonfly si absent de la mémoire).
+     */
+    static getAsync(id: string): Promise<KeywordSession | null>;
+    /**
+     * Recherche une session existante pour un keyword + marché (évite le re-call).
+     * C'est la fonction clé : avant tout run, vérifier si on a déjà les données.
+     */
+    static findExisting(keyword: string, country: string, language: string): KeywordSession | null;
+    /**
+     * Liste toutes les sessions (pour la sidebar "Historique").
+     */
+    static list(): SessionListItem[];
+    /**
+     * Supprime une session.
+     */
+    static delete(id: string): void;
+    /**
+     * Vide toutes les sessions.
+     */
+    static clearAll(): void;
+    private static getIndex;
+    /** Formate le coût total pour affichage */
+    static formatCost(cents: number): string;
+}

package/dist/keyword-trend-sparkline.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 📊 KeywordTrendSparkline
+ *
+ * Génère des données de sparkline SVG pour le volume mensuel d'un mot-clé.
+ * Retourne les points SVG normalisés (0–100) pour tracé dans une cellule de tableau.
+ * Pure In-Memory, sans dépendance DOM.
+ */
+export interface MonthlyVolume {
+    year: number;
+    month: number;
+    volume: number;
+}
+export interface SparklineData {
+    /** Points SVG normalisés sur viewBox 0 0 100 40 */
+    svgPath: string;
+    svgPolylinePoints: string;
+    /** Valeurs brutes */
+    values: number[];
+    min: number;
+    max: number;
+    average: number;
+    trend: "rising" | "falling" | "stable";
+    /** Variation % entre premier et dernier point */
+    changePercent: number;
+    /** Label de tendance court */
+    trendLabel: string;
+}
+export interface KeywordSparklineResult {
+    keyword: string;
+    sparkline: SparklineData;
+    monthLabels: string[];
+}
+export declare class KeywordTrendSparkline {
+    /**
+     * Génère les données de sparkline depuis 12 mois de volumes.
+     * @param keyword - Le mot-clé
+     * @param monthly - Tableau de volumes mensuels (peut être < 12 mois)
+     */
+    static generate(keyword: string, monthly: MonthlyVolume[]): KeywordSparklineResult;
+    /**
+     * Génère un chemin SVG lissé (cubic bezier) depuis les points normalisés.
+     */
+    private static buildSmoothPath;
+    /**
+     * Batch : génère les sparklines pour une liste de keywords.
+     */
+    static generateBatch(keywords: Array<{
+        keyword: string;
+        monthly: MonthlyVolume[];
+    }>): KeywordSparklineResult[];
+    /**
+     * Identifie les top N keywords en croissance (pour le dashboard "Opportunités en hausse").
+     */
+    static topRisingKeywords(results: KeywordSparklineResult[], topN?: number): KeywordSparklineResult[];
+}

package/dist/keywords/cannibalization.d.ts

@@ -0,0 +1,15 @@
+export interface CannibalRow {
+    keyword: string;
+    url: string;
+    position?: number;
+    impressions?: number;
+    clicks?: number;
+}
+export interface CannibalGroup {
+    keyword: string;
+    urls: string[];
+    count: number;
+    winner?: string;
+    reason?: string;
+}
+export declare function detectCannibalization(rows: CannibalRow[]): CannibalGroup[];

package/dist/klaviyo-sync-engine.d.ts

@@ -0,0 +1,75 @@
+export interface KlaviyoProfileInput {
+    email: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    zeroPartyAnswers?: Record<string, unknown>;
+    campaignId?: string;
+    couponCode?: string;
+    consentSource?: string;
+}
+export interface KlaviyoProfilePayload {
+    data: {
+        type: "profile";
+        attributes: {
+            email: string;
+            phone_number?: string;
+            first_name?: string;
+            last_name?: string;
+            properties: Record<string, unknown>;
+        };
+    };
+}
+export interface KlaviyoSubscriptionPayload {
+    data: {
+        type: "profile-subscription-bulk-create-job";
+        attributes: {
+            custom_source?: string;
+            profiles: {
+                data: Array<{
+                    type: "profile";
+                    attributes: {
+                        email: string;
+                        phone_number?: string;
+                        subscriptions?: {
+                            email?: {
+                                marketing: {
+                                    consent: "SUBSCRIBED" | "NEVER_SUBSCRIBED";
+                                    consent_timestamp?: string;
+                                };
+                            };
+                            sms?: {
+                                marketing: {
+                                    consent: "SUBSCRIBED" | "NEVER_SUBSCRIBED";
+                                    consent_timestamp?: string;
+                                };
+                            };
+                        };
+                    };
+                }>;
+            };
+        };
+        relationships: {
+            list: {
+                data: {
+                    type: "list";
+                    id: string;
+                };
+            };
+        };
+    };
+}
+export declare class KlaviyoSyncEngine {
+    /**
+     * Normalise un numéro de téléphone au format international E.164 (ex: +33612345678).
+     */
+    static normalizePhoneNumber(phone?: string): string | undefined;
+    /**
+     * Construit le payload officiel de création/mise à jour de profil pour l'API Klaviyo v3.
+     */
+    static buildProfilePayload(input: KlaviyoProfileInput): KlaviyoProfilePayload;
+    /**
+     * Construit le payload officiel d'abonnement à une liste Klaviyo (Double/Single opt-in avec consentement TCPA/GDPR).
+     */
+    static buildSubscriptionPayload(listId: string, email: string, phone?: string, source?: string): KlaviyoSubscriptionPayload;
+}

package/dist/knowledge-graph-linker.d.ts

@@ -1,8 +1,13 @@
 /**
- * 🧠 Google Knowledge Graph Entity Linker (Inspiration: advertools/knowledge_graph.py)
+ * 🧠 Knowledge Graph Entity Linker & Client
  *
  * Resolves official Google Entity IDs (`kgmid`), entity types, and Wikidata URIs
  * to maximize semantic authority and Knowledge Panel recognition (Entity SEO).
+ *
+ * The `KnowledgeGraphClient` is free-first: it resolves entities live through
+ * public, keyless APIs and only upgrades to the Google Knowledge Graph Search
+ * API when `GOOGLE_KG_API_KEY` is configured. Nothing is fabricated when every
+ * provider is unavailable — the result is an explicit empty, non-live lookup.
  */
 export interface KnowledgeGraphEntity {
     name: string;
@@ -27,3 +32,28 @@ export declare class KnowledgeGraphLinker {
      */
     static generateEntitySameAsLinks(entity: KnowledgeGraphEntity, customUrls?: string[]): string[];
 }
+export type KnowledgeGraphProvider = "google-kg" | "wikidata" | "wikipedia" | "none";
+export interface KnowledgeGraphLookupResult {
+    query: string;
+    entities: KnowledgeGraphEntity[];
+    provider: KnowledgeGraphProvider;
+    /** True only when entities were returned by a live network API. */
+    isLive: boolean;
+}
+/**
+ * Free-first client that actually resolves entities.
+ *
+ * Provider priority (first configured wins, then free fallback):
+ *   1. Google Knowledge Graph Search API — when GOOGLE_KG_API_KEY is set
+ *   2. Wikidata `wbsearchentities` — free, no key
+ *   3. Wikipedia `opensearch` — free, no key (final fallback)
+ */
+export declare class KnowledgeGraphClient {
+    private apiKey?;
+    constructor(apiKey?: string);
+    getProviderName(): Exclude<KnowledgeGraphProvider, "none">;
+    lookup(query: string, limit?: number, languages?: string[]): Promise<KnowledgeGraphLookupResult>;
+    private fetchGoogle;
+    private fetchWikidata;
+    private fetchWikipedia;
+}

package/dist/kvi-opportunity-calculator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 💎 KVI Opportunity Calculator
+ *
+ * Implements the signature Keyword Value Index (KVI) methodology:
+ * - KVI = (Volume * CPC) / (Allintitle + 1) * IntentMultiplier
+ * - Identifies "Gold Mine" keywords with high commercial value and low competition
+ * - Supports batch evaluation of up to thousands of keywords
+ * - Classifies opportunities into actionable ROI tiers
+ */
+export type KviSearchIntent = "transactional" | "commercial" | "informational" | "navigational";
+export type KviTier = "GOLD_MINE" | "HIGH_OPPORTUNITY" | "MODERATE" | "LOW_ROI";
+export interface KviKeywordInput {
+    keyword: string;
+    monthlySearchVolume: number;
+    cpcEur: number;
+    allintitleCount: number;
+    intent?: KviSearchIntent;
+    keywordDifficulty?: number;
+}
+export interface KviEvaluationResult {
+    keyword: string;
+    monthlySearchVolume: number;
+    cpcEur: number;
+    allintitleCount: number;
+    intent: KviSearchIntent;
+    kviScore: number;
+    tier: KviTier;
+    tierLabel: string;
+    opportunitySummary: string;
+    estimatedMonthlyValueEur: number;
+}
+export interface KviBatchOptions {
+    minVolume?: number;
+    minCpcEur?: number;
+    maxAllintitle?: number;
+    topN?: number;
+}
+export interface KviBatchResult {
+    results: KviEvaluationResult[];
+    totalKeywords: number;
+    goldMineCount: number;
+    highOpportunityCount: number;
+    moderateCount: number;
+    lowRoiCount: number;
+    averageKvi: number;
+    totalMonthlyVolume: number;
+    topOpportunities: KviEvaluationResult[];
+}
+export declare class KviOpportunityCalculator {
+    private static readonly INTENT_WEIGHTS;
+    /**
+     * Computes the KVI score for a single keyword.
+     */
+    static computeKvi(keyword: string, volume: number, cpcEur: number, allintitleCount: number, intent?: KviSearchIntent): KviEvaluationResult;
+    /**
+     * Evaluates a batch of keywords, sorts by KVI descending, and computes aggregated metrics.
+     */
+    static batchEvaluate(keywords: KviKeywordInput[], options?: KviBatchOptions): KviBatchResult;
+    private static classifyTier;
+    private static getTierLabel;
+}

package/dist/lago-token-meter.d.ts

@@ -25,6 +25,10 @@ export declare class LagoTokenMeter {
      * Sends a real-time token metering event to Lago.
      */
     trackTokenUsage(externalCustomerId: string, tokenCount: number, model: string): Promise<boolean>;
+    /**
+     * Sends a real-time SERP scrape metering event to Lago.
+     */
+    trackSerpScrapes(externalCustomerId: string, units?: number, provider?: string): Promise<boolean>;
 }
 export declare class HyperswitchGateway {
     private config;

package/dist/lcp-subparts-analyzer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ⚡ LcpSubpartsAnalyzer — Core Web Vitals LCP Phase Decomposition
+ *
+ * Follows the Google CrUX 2025/2026 LCP sub-part specification.
+ *
+ * Decomposes Largest Contentful Paint (LCP) into its 4 distinct subparts:
+ * 1. Time to First Byte (TTFB): Server response & network transit (target < 800ms, ideal < 200ms).
+ * 2. Resource Load Delay: Time from TTFB until browser discovers and starts fetching LCP asset (target < 200ms).
+ * 3. Resource Load Duration: Time taken to download the LCP asset bytes (target < 500ms).
+ * 4. Element Render Delay: Time from download finish until pixels are painted on screen (target < 200ms).
+ *
+ * Identifies the exact bottleneck phase to eliminate generic "slow LCP" guesses.
+ */
+export interface LcpSubpartsInput {
+    url?: string;
+    totalLcpMs?: number;
+    ttfbMs?: number;
+    resourceLoadDelayMs?: number;
+    loadDelayMs?: number;
+    resourceLoadDurationMs?: number;
+    loadDurationMs?: number;
+    elementRenderDelayMs?: number;
+    renderDelayMs?: number;
+    isLcpImage?: boolean;
+}
+export interface LcpPhaseBreakdown {
+    phase: "ttfb" | "load_delay" | "load_duration" | "render_delay";
+    name: string;
+    durationMs: number;
+    percentageOfLcp: number;
+    status: "good" | "needs_improvement" | "poor";
+    diagnostic: string;
+    remedyAction: string;
+}
+export interface LcpSubpartsReport {
+    url: string;
+    totalLcpMs: number;
+    overallRating: "good" | "needs_improvement" | "poor";
+    rating: "good" | "needs_improvement" | "poor";
+    primaryBottleneck: "ttfb" | "load_delay" | "load_duration" | "render_delay";
+    dominantPhase: "ttfb" | "load_delay" | "load_duration" | "render_delay";
+    bottleneckPhase: "ttfb" | "load_delay" | "load_duration" | "render_delay";
+    verdict: {
+        status: "good" | "needs-improvement" | "poor";
+    };
+    phases: Record<"ttfb" | "load_delay" | "load_duration" | "render_delay", LcpPhaseBreakdown>;
+    actionableRemedies: string[];
+    recommendations: string[];
+}
+export declare class LcpSubpartsAnalyzer {
+    private static readonly TARGETS;
+    /**
+     * Analyzes and decomposes LCP into actionable phases.
+     */
+    static analyze(input: LcpSubpartsInput): LcpSubpartsReport;
+}

package/dist/links/backlinks-gap.d.ts

@@ -0,0 +1,31 @@
+export interface OwnBacklinkSource {
+    sourceDomain: string;
+}
+export interface CompetitorGapBacklinkRow {
+    competitorDomain: string;
+    sourceDomain?: string;
+    sourceUrl?: string;
+    anchor?: string | null;
+    domainAuthority?: number | null;
+}
+export interface BacklinkGapOpportunity {
+    sourceDomain: string;
+    competitorDomains: string[];
+    referringUrls: string[];
+    anchors: string[];
+    backlinkCount: number;
+    domainAuthority: number | null;
+    priority: number;
+    reason: string;
+}
+/**
+ * Referring domains a competitor earns links from while we hold none there.
+ * Priority blends how many tracked competitors share the domain, how many
+ * links they take from it, and its authority when the import carried one.
+ */
+export declare function computeBacklinkGaps(ownSources: OwnBacklinkSource[], competitorRows: CompetitorGapBacklinkRow[]): BacklinkGapOpportunity[];
+/** Same gaps grouped per competitor, so each rival gets its own outreach list. */
+export declare function groupGapsByCompetitor(gaps: BacklinkGapOpportunity[]): {
+    competitorDomain: string;
+    gaps: BacklinkGapOpportunity[];
+}[];

package/dist/links/competitors-import.d.ts

@@ -0,0 +1,17 @@
+export interface CompetitorImportRow {
+    competitorDomain?: string;
+    sourceUrl: string;
+    targetUrl?: string;
+    anchorText?: string;
+    domainAuthority?: number;
+    pageAuthority?: number;
+}
+export declare function parseCompetitorCsv(csv: string): CompetitorImportRow[];
+export declare function normalizeCompetitorImport(rows: CompetitorImportRow[]): {
+    competitorDomain: string | undefined;
+    sourceUrl: string;
+    targetUrl?: string;
+    anchorText?: string;
+    domainAuthority?: number;
+    pageAuthority?: number;
+}[];

package/dist/links/opportunities.d.ts

@@ -0,0 +1,20 @@
+export interface InternalLinkCandidate {
+    from: string;
+    to: string;
+    anchor: string;
+    reason: string;
+    score: number;
+}
+export declare function suggestInternalLinks(params: {
+    pages: Array<{
+        url: string;
+        title?: string;
+        h1?: string;
+        topicality?: number;
+    }>;
+    targets: Array<{
+        url: string;
+        priority?: number;
+    }>;
+}): InternalLinkCandidate[];
+export declare function detectOrphans(pages: string[], linked: string[]): string[];

package/dist/links-matrix-exporter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 🦁 LynxSEO Engine - In-Page Links Matrix & CSV Exporter (v3.2.0)
+ *
+ * Analyzes in-page link profiles, classifies internal vs external,
+ * inspects rel attributes (nofollow, sponsored, ugc), and exports RFC-4180 compliant CSV files.
+ */
+export interface InPageLinkItem {
+    href: string;
+    text: string;
+    isInternal: boolean;
+    rel: string;
+}
+export interface LinksSummary {
+    total: number;
+    internal: number;
+    external: number;
+    nofollow: number;
+    sponsored: number;
+    ugc: number;
+    uniqueDestinations: number;
+}
+export declare class LinksMatrixEngine {
+    /**
+     * Summarizes links collection.
+     */
+    static summarize(links: InPageLinkItem[]): LinksSummary;
+    /**
+     * Generates UTF-8 encoded, quoted CSV string.
+     */
+    static exportToCsv(links: InPageLinkItem[]): string;
+}