@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/analytics/timeseries-transform-engine.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Time-Series Transform Engine
+ * Clean-room implementation inspired by Metabase transforms & rollup aggregations.
+ * Provides statistical rolling transforms: SMA, EMA, cumulative sum, period-over-period delta, and scaling.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface TimeSeriesPoint {
+    timestamp: string | number;
+    value: number;
+}
+export interface TransformedTimeSeriesPoint extends TimeSeriesPoint {
+    transformedValue: number;
+    rawDelta?: number;
+    percentChange?: number;
+}
+export type TransformType = 'moving_average' | 'exponential_moving_average' | 'cumulative_sum' | 'period_over_period' | 'percent_of_total' | 'min_max_scale';
+export interface TransformOptions {
+    type: TransformType;
+    windowSize?: number;
+    smoothingAlpha?: number;
+    lagPeriod?: number;
+}
+export declare class TimeseriesTransformEngine {
+    static transform(series: TimeSeriesPoint[], options: TransformOptions): TransformedTimeSeriesPoint[];
+    private static computeMovingAverage;
+    private static computeEMA;
+    private static computeCumulativeSum;
+    private static computePeriodOverPeriod;
+    private static computePercentOfTotal;
+    private static computeMinMaxScale;
+}

package/dist/analytics/topical-authority-cluster-graph.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Topical Authority Cluster Graph (Batch 12 - Gap 2)
+ *
+ * Semantic content hub-and-spoke graph analyzer inspired by MarketMuse, Clearscope & InLinks.
+ * Analyzes topical coverage across domain entities, identifies pillar/spoke topology,
+ * flags entity blind spots vs competitor knowledge graphs, and scores cluster completeness.
+ */
+export interface SemanticEntity {
+    name: string;
+    category?: string;
+    salienceWeight: number;
+}
+export interface ClusterPageNode {
+    url: string;
+    title: string;
+    isPillarCandidate?: boolean;
+    coveredEntities: SemanticEntity[];
+    wordCount: number;
+    internalInboundLinksCount: number;
+    avgOrganicPosition?: number;
+}
+export interface CompetitorBenchmarkEntity {
+    name: string;
+    salienceWeight: number;
+    competitorCoverageRatio: number;
+}
+export interface ClusterSpokeLinkAdvice {
+    spokeUrl: string;
+    pillarUrl: string;
+    recommendedAnchorText: string;
+    entityFocus: string;
+}
+export interface TopicalEntityGap {
+    entityName: string;
+    salienceWeight: number;
+    competitorCoverageRatio: number;
+    urgency: "critical" | "high" | "medium";
+    recommendation: string;
+}
+export interface SemanticClusterNodeReport {
+    clusterTopic: string;
+    pillarPageUrl?: string;
+    spokePages: string[];
+    totalWordsInCluster: number;
+    clusterCompletenessScore: number;
+    topicalAuthorityScore: number;
+    cannibalizationAlerts: Array<{
+        entityName: string;
+        conflictingUrls: string[];
+    }>;
+    entityGaps: TopicalEntityGap[];
+    linkingBlueprint: ClusterSpokeLinkAdvice[];
+}
+export interface TopicalAuthorityClusterReport {
+    analyzedClustersCount: number;
+    overallAuthorityScore: number;
+    clusters: SemanticClusterNodeReport[];
+    globalMissingEntities: string[];
+    strategicRecommendations: string[];
+}
+export declare class TopicalAuthorityClusterGraph {
+    /**
+     * Analyzes an array of site pages categorized under a topic cluster against
+     * industry competitor entity benchmarks to produce authority scoring and graph advice.
+     */
+    static analyzeCluster(clusterTopic: string, pages: ClusterPageNode[], competitorBenchmark?: CompetitorBenchmarkEntity[]): SemanticClusterNodeReport;
+    /**
+     * Evaluates multiple clusters across a site to generate site-wide authority audit.
+     */
+    static auditDomainClusters(clusterConfigs: Array<{
+        clusterTopic: string;
+        pages: ClusterPageNode[];
+        competitorBenchmark?: CompetitorBenchmarkEntity[];
+    }>): TopicalAuthorityClusterReport;
+}

package/dist/analytics/tracker-install-verifier.d.ts

@@ -0,0 +1,35 @@
+/**
+ * TrackerInstallVerifier Analytics Engine
+ *
+ * Implements automated validation of tracking script installation on target pages.
+ * Inspects HTML documents for `<script>` tags, checks nonce verification,
+ * parses Content-Security-Policy (CSP) headers, and evaluates script reachability.
+ * Parity with Matomo JsTrackerInstallCheck & Swetrix Snippet Verification.
+ *
+ * Clean-room implementation under AGPL-3.0-or-later.
+ */
+export interface TrackerInstallInspectionInput {
+    targetUrl: string;
+    htmlContent: string;
+    cspHeader?: string | null;
+    expectedTrackerDomain?: string;
+    verificationNonce?: string;
+}
+export interface TrackerInstallInspectionResult {
+    isInstalled: boolean;
+    scriptTagFound: boolean;
+    scriptSrc: string | null;
+    isAsyncOrDefer: boolean;
+    hasVerificationNonce: boolean;
+    cspStatus: {
+        isCspRestricted: boolean;
+        scriptSrcAllowsTracker: boolean;
+        connectSrcAllowsTracker: boolean;
+        missingDirectives: string[];
+    };
+    recommendations: string[];
+}
+export declare class TrackerInstallVerifier {
+    static generateVerificationNonce(): string;
+    static inspect(input: TrackerInstallInspectionInput): TrackerInstallInspectionResult;
+}

package/dist/analytics/tracking-plan-drift-detector.d.ts

@@ -0,0 +1,71 @@
+/**
+ * TrackingPlanDriftDetector — Détection de dérive de schéma de tracking plan & auto-patch (Parité RudderStack / Segment).
+ *
+ * Valide les événements entrants par rapport au plan de tracking contractuel :
+ * - Détecte les propriétés manquantes obligatoires (MISSING_REQUIRED)
+ * - Détecte les types incompatibles (TYPE_MISMATCH)
+ * - Détecte les propriétés non répertoriées (UNKNOWN_PROPERTY)
+ * - Détecte les violations d'enum et de pattern regex (ENUM_VIOLATION, PATTERN_VIOLATION)
+ * - Calcule le score de dérive (0 - 100%) et génère un plan de correction/auto-patch JSON
+ */
+export type PropertyType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+export interface TrackingPropertyRule {
+    property: string;
+    type: PropertyType;
+    required?: boolean;
+    pattern?: string;
+    enumValues?: Array<string | number>;
+    description?: string;
+}
+export interface TrackingEventSpec {
+    eventName: string;
+    description?: string;
+    allowAdditionalProperties?: boolean;
+    properties: TrackingPropertyRule[];
+}
+export interface TrackingPlan {
+    id: string;
+    name: string;
+    version: string;
+    strictMode?: boolean;
+    events: Record<string, TrackingEventSpec>;
+}
+export type DriftTrackingPlan = TrackingPlan;
+export type DriftViolationType = 'UNREGISTERED_EVENT' | 'MISSING_REQUIRED' | 'TYPE_MISMATCH' | 'UNKNOWN_PROPERTY' | 'ENUM_VIOLATION' | 'PATTERN_VIOLATION';
+export interface DriftViolation {
+    eventName: string;
+    property?: string;
+    violationType: DriftViolationType;
+    expected?: string;
+    actual?: string;
+    sampleValue?: unknown;
+}
+export interface ProposedPropertyPatch {
+    eventName: string;
+    property: string;
+    inferredType: PropertyType;
+    required: boolean;
+    sampleValue: unknown;
+}
+export interface DriftReport {
+    planId: string;
+    planVersion: string;
+    totalEventsAnalyzed: number;
+    validEventsCount: number;
+    driftedEventsCount: number;
+    driftScorePct: number;
+    status: 'clean' | 'minor_drift' | 'severe_drift';
+    violations: DriftViolation[];
+    violationsSummary: Record<DriftViolationType, number>;
+    autoPatchProposal: ProposedPropertyPatch[];
+}
+export declare class TrackingPlanDriftDetector {
+    /**
+     * Analyse un lot d'événements par rapport à un plan de tracking.
+     */
+    static analyzeBatch(plan: TrackingPlan, events: Array<{
+        event: string;
+        properties?: Record<string, unknown>;
+    }>): DriftReport;
+    private static inferType;
+}

package/dist/analytics/tracking-proxy-config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tracking Proxy Configuration Builder
+ *
+ * Clean-room implementation of a first-party analytics reverse-proxy planner.
+ * Produces a ready-to-paste Caddy or nginx configuration that serves the
+ * collector and the tracking script from the customer's own domain so that
+ * ad/tracker blocklists cannot match the upstream analytics hostname.
+ *
+ * (Gap parity: Matomo "Proxy / Reverse Proxy" setup assistant.)
+ *
+ * The builder is deliberately pure: it performs no network I/O, never reads
+ * environment variables, and rejects any input that could break out of the
+ * generated configuration blocks (CR/LF injection, path traversal, query
+ * strings, credentials, non-standard ports).
+ */
+export interface TrackingProxyPlan {
+    publicOrigin: string;
+    pathPrefix: string;
+    collectUrl: string;
+    scriptUrl: string;
+    loaderSnippet: string;
+    caddyConfig: string;
+    nginxConfig: string;
+    warnings: string[];
+}
+export declare class TrackingProxyConfigError extends Error {
+    constructor(message: string);
+}
+export declare class TrackingProxyConfigBuilder {
+    static readonly DEFAULT_PATH_PREFIX: string;
+    /**
+     * Returns true when `hostname` is a syntactically valid, publicly routable
+     * DNS hostname (no scheme, path, port, IP literal, underscore or reserved
+     * local name). A single trailing dot is tolerated. Case is irrelevant.
+     */
+    static validateHostname(hostname: string): boolean;
+    static build(input: {
+        publicHostname: string;
+        upstreamOrigin: string;
+        pathPrefix?: string;
+    }): TrackingProxyPlan;
+    private static normalizeHostname;
+    private static normalizeUpstreamOrigin;
+    private static normalizePathPrefix;
+    private static assertNoInjection;
+    private static isIpv4Literal;
+    private static registrableDomain;
+}

package/dist/analytics/transitions-matrix-calculator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * TransitionsMatrixCalculator — Calculateur de matrice de transitions de page (Parité Matomo Transitions).
+ *
+ * Analyse pour une URL donnée tous les flux de navigation entrants et sortants :
+ * - Entrées :
+ *   - Pages internes précédentes (avec volumes et pourcentages)
+ *   - Moteurs de recherche (Google, Bing, DuckDuckGo, etc.)
+ *   - Campagnes marketing (UTM)
+ *   - Entrées directes
+ * - Sorties :
+ *   - Pages internes suivantes
+ *   - Liens sortants externes (outlinks)
+ *   - Téléchargements de fichiers (downloads .pdf, .zip, etc.)
+ *   - Sorties définitives du site (exits)
+ * - Boucles (rafraîchissements / re-navigation vers la même page)
+ * - Taux de rebond spécifique à la page
+ */
+export interface PageTransitionSessionEvent {
+    sessionId: string;
+    url: string;
+    referrer?: string;
+    timestamp: number;
+    type?: 'pageview' | 'outlink' | 'download';
+    outlinkUrl?: string;
+    downloadUrl?: string;
+    campaign?: {
+        source?: string;
+        campaign?: string;
+    };
+}
+export interface TransitionNodeCount {
+    label: string;
+    visits: number;
+    percentage: number;
+}
+export interface PageTransitionsMatrix {
+    targetUrl: string;
+    totalPageviews: number;
+    loopsCount: number;
+    bounceCount: number;
+    bounceRatePct: number;
+    incomings: {
+        total: number;
+        directEntries: TransitionNodeCount;
+        searchEngines: TransitionNodeCount[];
+        campaigns: TransitionNodeCount[];
+        previousPages: TransitionNodeCount[];
+    };
+    outgoings: {
+        total: number;
+        exits: TransitionNodeCount;
+        nextPages: TransitionNodeCount[];
+        outlinks: TransitionNodeCount[];
+        downloads: TransitionNodeCount[];
+    };
+}
+export declare class TransitionsMatrixCalculator {
+    /**
+     * Calcule la matrice complète des transitions pour une URL cible.
+     */
+    static calculate(targetUrl: string, events: PageTransitionSessionEvent[]): PageTransitionsMatrix;
+    private static normalizeUrl;
+    private static extractHostname;
+    private static extractFilename;
+    private static detectSearchEngine;
+}

package/dist/analytics/types.d.ts

@@ -0,0 +1,77 @@
+export type AnalyticsEnv = 'd1' | 'pg' | 'memory';
+export interface TimeRange {
+    from: string;
+    to: string;
+    tz?: string;
+}
+export interface EventInput {
+    siteId: string;
+    sessionId?: string;
+    visitorId?: string;
+    type: 'pageview' | 'click' | 'form_submit' | 'custom';
+    name?: string;
+    url: string;
+    referrer?: string;
+    userAgent?: string;
+    ip?: string;
+    country?: string;
+    device?: 'desktop' | 'mobile' | 'tablet' | 'other';
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmTerm?: string;
+    utmContent?: string;
+    props?: Record<string, unknown>;
+    consent?: boolean;
+}
+export interface RumMetricInput {
+    siteId: string;
+    url: string;
+    sessionId?: string;
+    metric: 'LCP' | 'INP' | 'CLS' | 'TTFB' | 'FCP';
+    value: number;
+    rating?: 'good' | 'needs-improvement' | 'poor';
+    delta?: number;
+    id?: string;
+    navigationType?: string;
+    connection?: string;
+}
+export interface LogEntryInput {
+    siteId: string;
+    ts: string;
+    ip?: string;
+    method?: string;
+    path: string;
+    status: number;
+    bytes?: number;
+    referer?: string;
+    userAgent?: string;
+    bot?: boolean;
+    botName?: string;
+}
+export interface AiCitationInput {
+    siteId: string;
+    engine: 'chatgpt' | 'perplexity' | 'google_ai' | 'claude' | 'gemini' | 'grok' | 'other';
+    query?: string;
+    topic?: string;
+    url: string;
+    citedUrl?: string;
+    passage?: string;
+    position?: number;
+    visible?: boolean;
+    checkedAt?: string;
+}
+export interface CrawlSnapshotItem {
+    url: string;
+    status: number;
+    title?: string;
+    metaDescription?: string;
+    h1?: string;
+    canonical?: string;
+    robots?: string;
+    schemaCount?: number;
+    linksInternal?: number;
+    linksExternal?: number;
+    redirectChain?: string[];
+    hash: string;
+}

package/dist/analytics/unified.d.ts

@@ -0,0 +1,56 @@
+export interface UnifiedOverviewInput {
+    siteId: string;
+    range: {
+        from: string;
+        to: string;
+    };
+    vitals?: Array<{
+        metric: any;
+        value: number;
+    }>;
+    logs?: any[];
+    aiRows?: any[];
+    serpRows?: any[];
+}
+export declare function buildUnifiedOverview(i: UnifiedOverviewInput): {
+    siteId: string;
+    range: {
+        from: string;
+        to: string;
+    };
+    health: {
+        vitals: {
+            metric: import("./rum").Vital;
+            count: number;
+            p75: number;
+            rating: "good" | "poor" | "needs-improvement";
+        }[];
+        lfa: {
+            total: number;
+            bots: number;
+            humans: number;
+            ok: number;
+            err: number;
+            bytes: number;
+            topPaths: {
+                path: string;
+                hits: number;
+            }[];
+            crawlBudgetWaste: number;
+        } | null;
+        aiSov: {
+            engine: import("./ai-sov").AiEngine;
+            total: number;
+            cited: number;
+            sov: number;
+            passageCoverage: number;
+        }[];
+        serpVisibility: {
+            top1: number;
+            top3: number;
+            top10: number;
+            visibility: number;
+        } | null;
+    };
+    generatedAt: string;
+};

package/dist/analytics/user-feedback-engine.d.ts

@@ -0,0 +1,79 @@
+/**
+ * LynxSEO Engine - In-App User Feedback & NPS Sentiment Engine
+ *
+ * Provides interactive micro-surveys, Net Promoter Score (NPS), CSAT ratings,
+ * and exit-intent feedback tracking correlated with analytics sessions.
+ * (Parity: PostHog Surveys & Matomo Feedback).
+ */
+export type SurveyType = "nps" | "csat" | "rating" | "free_text" | "multi_choice";
+export interface SurveyTriggerRules {
+    urlPattern?: string;
+    minSecondsOnPage?: number;
+    minScrollDepthPercent?: number;
+    exitIntent?: boolean;
+    sampleRate?: number;
+}
+export interface SurveyDefinition {
+    id: string;
+    title: string;
+    question: string;
+    type: SurveyType;
+    options?: string[];
+    triggerRules?: SurveyTriggerRules;
+    enabled: boolean;
+    createdAt: string;
+}
+export interface SurveyResponseSubmission {
+    surveyId: string;
+    visitorId: string;
+    sessionId?: string;
+    url: string;
+    score?: number;
+    selectedOption?: string;
+    comment?: string;
+    timestamp: string;
+}
+export interface SurveyAnalyticsSummary {
+    surveyId: string;
+    totalResponses: number;
+    npsScore: number | null;
+    csatAverage: number | null;
+    promotersCount: number;
+    passivesCount: number;
+    detractorsCount: number;
+    topComments: Array<{
+        comment: string;
+        timestamp: string;
+        score?: number;
+    }>;
+    optionCounts: Record<string, number>;
+}
+export declare class UserFeedbackEngine {
+    private surveys;
+    private responses;
+    constructor(initialSurveys?: SurveyDefinition[]);
+    registerSurvey(survey: SurveyDefinition): void;
+    getSurvey(surveyId: string): SurveyDefinition | undefined;
+    listSurveys(): SurveyDefinition[];
+    /**
+     * Determines if a survey should be displayed based on visitor context.
+     */
+    shouldDisplaySurvey(surveyId: string, context: {
+        currentUrl: string;
+        secondsOnPage: number;
+        scrollDepthPercent: number;
+        isExitIntent?: boolean;
+        randomSeed?: number;
+    }): boolean;
+    /**
+     * Records a user response and validates boundary constraints.
+     */
+    recordResponse(submission: SurveyResponseSubmission): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * Aggregates survey metrics and NPS/CSAT benchmarks.
+     */
+    getSurveySummary(surveyId: string): SurveyAnalyticsSummary;
+}

package/dist/analytics/user-flow-aggregator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * UserFlowAggregator — Agrégateur de parcours de navigation multi-étapes (Parité PostHog Paths / Matomo Users Flow).
+ *
+ * Transforme les sessions utilisateur séquentielles en un graphe d'étapes (Sankey / User Flow) :
+ * - Calcul des flux par étape (Stage 1..N)
+ * - Taux de continuation vs taux d'abandon (drop-off) par nœud
+ * - Arêtes de transition pondérées (from -> to)
+ * - Filtrage par page d'entrée, page de sortie ou seuil de volume
+ * - Regroupement automatique des chemins marginaux dans un nœud "(autres pages)"
+ */
+export interface RawFlowEvent {
+    sessionId: string;
+    path: string;
+    timestamp: number | string;
+    title?: string;
+}
+export interface UserFlowStepNode {
+    path: string;
+    title?: string;
+    visitors: number;
+    pctOfStep: number;
+    dropOffRatePct: number;
+    continuingVisitors: number;
+    dropOffVisitors: number;
+}
+export interface UserFlowEdge {
+    sourceStage: number;
+    sourcePath: string;
+    targetStage: number;
+    targetPath: string;
+    visitors: number;
+    pctOfSourceNode: number;
+}
+export interface UserFlowStage {
+    stageNumber: number;
+    title: string;
+    totalVisitors: number;
+    nodes: UserFlowStepNode[];
+}
+export interface UserFlowAnalysisOptions {
+    maxStages?: number;
+    maxNodesPerStage?: number;
+    startPathFilter?: string;
+    endPathFilter?: string;
+    minVisitorsThreshold?: number;
+    collapseConsecutiveDuplicates?: boolean;
+}
+export interface UserFlowResult {
+    stages: UserFlowStage[];
+    edges: UserFlowEdge[];
+    summary: {
+        totalSessionsAnalyzed: number;
+        matchingSessions: number;
+        completedToMaxStageSessions: number;
+        overallDropOffRatePct: number;
+        topPaths: Array<{
+            pathSequence: string[];
+            sessionsCount: number;
+        }>;
+    };
+}
+export declare class UserFlowAggregator {
+    /**
+     * Agrège les événements de session en un graphe de flux par étapes.
+     */
+    static aggregateFlow(events: RawFlowEvent[], options?: UserFlowAnalysisOptions): UserFlowResult;
+}

package/dist/analytics/user-flow-dropoff-sunburst-engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - User Flow Dropoff Sunburst Engine (Batch 13 - Gap 2)
+ *
+ * Hierarchical multi-level user journey and path dropoff engine
+ * inspired by Amplitude Pathfinder, Mixpanel Flows, and GA4 Path Exploration.
+ *
+ * Builds N-level prefix tree (Trie) for interactive sunburst / multi-ring visualization,
+ * quantifies transition probabilities, detects cyclic loopbacks,
+ * and pinpoints major friction dropoff bottlenecks.
+ */
+export interface JourneyPathStep {
+    name: string;
+    timestampMs?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface UserSessionJourney {
+    userId?: string;
+    sessionId: string;
+    steps: JourneyPathStep[];
+}
+export interface SunburstNode {
+    name: string;
+    depth: number;
+    sessionCount: number;
+    dropoffCount: number;
+    dropoffRatePct: number;
+    continuationRatePct: number;
+    children: SunburstNode[];
+}
+export interface LoopbackFinding {
+    cycleSignature: string;
+    affectedSessionsCount: number;
+    frictionSeverity: "high" | "medium";
+}
+export interface PathDropoffHotspot {
+    fromStep: string;
+    toStep?: string;
+    dropoffCount: number;
+    dropoffRatePct: number;
+    depth: number;
+}
+export interface UserFlowSunburstReport {
+    totalSessionsAnalyzed: number;
+    maxExplorationDepth: number;
+    rootSunburstTree: SunburstNode;
+    topDropoffHotspots: PathDropoffHotspot[];
+    detectedLoopbacks: LoopbackFinding[];
+    flowHealthScore: number;
+    strategicInsights: string[];
+}
+export declare class UserFlowDropoffSunburstEngine {
+    /**
+     * Builds an N-level sunburst tree and calculates path dropoffs from user journey sessions.
+     */
+    static buildSunburstFlow(sessions: UserSessionJourney[], options?: {
+        maxDepth?: number;
+        minSessionThreshold?: number;
+        reverseFlowFromGoal?: string;
+    }): UserFlowSunburstReport;
+}