@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/referrer-spam-detector.d.ts

@@ -0,0 +1,60 @@
+/**
+ * LynxSEO Engine - Referrer Spam & Ghost Traffic Firewall
+ *
+ * Provides automated detection and filtering of referral spam, ghost crawlers,
+ * and malicious traffic pollution (Parity: Matomo TrackingSpamPrevention & Plausible Ghost Shield).
+ *
+ * Features:
+ * - Built-in community blocklist of known spam referrers
+ * - Domain mismatch / ghost traffic heuristics (direct hits spoofing referrers without host match)
+ * - TLD spam patterns and regex filters
+ * - Sanitization scoring and report cleaning
+ * - Custom domain allowlist & blocklist overrides
+ */
+export interface ReferrerSpamConfig {
+    /** Allowed hostnames for the site (to detect ghost referrer spoofing) */
+    allowedHostnames?: string[];
+    /** Custom domains to block */
+    customBlocklist?: string[];
+    /** Custom domains to allow (overrides blocklist) */
+    customAllowlist?: string[];
+    /** Flag to block visits with suspicious TLDs */
+    blockSuspiciousTlds?: boolean;
+}
+export interface ReferrerEvaluationResult {
+    isSpam: boolean;
+    reason?: "known_spammer" | "ghost_traffic" | "suspicious_tld" | "custom_blocklist" | "invalid_url";
+    detectedDomain?: string;
+    confidenceScore: number;
+    sanitizedReferrer: string | null;
+}
+export interface SpamDetectionSummary {
+    totalAnalyzed: number;
+    spamCount: number;
+    cleanCount: number;
+    spamRate: number;
+    topSpamDomains: Array<{
+        domain: string;
+        count: number;
+    }>;
+    reasonsBreakdown: Record<string, number>;
+}
+export declare class ReferrerSpamDetector {
+    private customBlocklist;
+    private customAllowlist;
+    private allowedHostnames;
+    private blockSuspiciousTlds;
+    constructor(config?: ReferrerSpamConfig);
+    /**
+     * Evaluates a referrer URL against spam rules and ghost traffic heuristics.
+     */
+    evaluate(referrerUrl: string | null | undefined, requestHostname?: string): ReferrerEvaluationResult;
+    /**
+     * Analyzes a batch of referrer entries and generates a spam impact summary.
+     */
+    analyzeBatch(referrers: Array<{
+        referrer: string;
+        hostname?: string;
+    }>): SpamDetectionSummary;
+    private isKnownSpamDomain;
+}

package/dist/analytics/release-vitals-correlator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Release Vitals Correlator — PostHog Web Vitals per Release Parity
+ *
+ * Corrèle les performances Core Web Vitals (LCP, CLS, INP, FCP, TTFB)
+ * avec les déploiements, versions et commits Git (app_version, release_id, git_commit).
+ * Détecte automatiquement les régressions de performance introduites par une mise en production.
+ */
+export interface VitalsMeasurement {
+    metric: "LCP" | "CLS" | "INP" | "FCP" | "TTFB";
+    value: number;
+    release: string;
+    timestamp: string;
+}
+export interface MetricSummary {
+    metric: string;
+    count: number;
+    mean: number;
+    p75: number;
+    p90: number;
+    goodCount: number;
+    needsImprovementCount: number;
+    poorCount: number;
+    goodPercentage: number;
+}
+export interface ReleaseVitalsReport {
+    release: string;
+    sampleCount: number;
+    metrics: Record<string, MetricSummary>;
+}
+export interface ReleaseComparison {
+    baseRelease: string;
+    targetRelease: string;
+    regressions: {
+        metric: string;
+        baseP75: number;
+        targetP75: number;
+        deltaPercent: number;
+        severity: "warning" | "critical";
+        reason: string;
+    }[];
+    improvements: {
+        metric: string;
+        baseP75: number;
+        targetP75: number;
+        deltaPercent: number;
+    }[];
+    verdict: "improved" | "stable" | "regressed" | "critical_regression";
+}
+export declare class ReleaseVitalsCorrelator {
+    private static percentile;
+    /**
+     * Agrège les mesures brutes de Web Vitals par version de release.
+     */
+    static aggregateByRelease(measurements: VitalsMeasurement[]): Map<string, ReleaseVitalsReport>;
+    /**
+     * Compare deux versions consécutives et détecte les régressions de performance.
+     */
+    static compareReleases(baseReport: ReleaseVitalsReport, targetReport: ReleaseVitalsReport): ReleaseComparison;
+}

package/dist/analytics/replay-annotation-engine.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Replay Annotation & Timestamped Collaboration Engine
+ * Clean-room implementation for pin-pointing observations, UX bugs, and tasks
+ * on specific frames/timestamps of session replays.
+ * Parity: PostHog Player Comment Overlay & OpenReplay Collaboration Notes.
+ */
+export interface ReplayTimestampComment {
+    id: string;
+    sessionId: string;
+    timestampMs: number;
+    formattedTime: string;
+    authorId: string;
+    authorName: string;
+    content: string;
+    taggedUserIds?: string[];
+    isTask?: boolean;
+    taskResolved?: boolean;
+    createdAt: string;
+    updatedAt?: string;
+}
+export interface ReplayAnnotationMarker {
+    timestampMs: number;
+    formattedTime: string;
+    count: number;
+    hasUnresolvedTask: boolean;
+    comments: ReplayTimestampComment[];
+}
+export interface ReplayCollaborationSummary {
+    sessionId: string;
+    totalComments: number;
+    openTasksCount: number;
+    resolvedTasksCount: number;
+    uniqueAuthorsCount: number;
+    markers: ReplayAnnotationMarker[];
+}
+export declare class ReplayAnnotationEngine {
+    /**
+     * Formats a millisecond duration to mm:ss or hh:mm:ss string.
+     */
+    static formatTime(ms: number): string;
+    /**
+     * Aggregates comments for a session into player scrub-bar markers.
+     * Clusters comments within a tolerance window (e.g., 2000ms).
+     */
+    static buildScrubMarkers(sessionId: string, comments: ReplayTimestampComment[], clusterToleranceMs?: number): ReplayCollaborationSummary;
+    /**
+     * Extracts @user mentions from comment content.
+     */
+    static extractMentions(content: string): string[];
+}

package/dist/analytics/replay-audio-track-sync.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ReplayAudioTrackSynchronizer — Audio / WebRTC track alignment for session replay.
+ *
+ * Clean-room implementation of the OpenReplay "Audio / WebRTC Stream Sync" gap.
+ * Media chunks are recorded relative to the moment a track started; this module
+ * shifts every track onto the session timeline so audio, WebRTC calls and the
+ * DOM replay share one clock. It reports gaps (silence) and overlaps (double
+ * audio) without mutating the caller's input.
+ *
+ * AGPL-3.0-or-later
+ */
+export interface MediaChunk {
+    startMs: number;
+    durationMs: number;
+    url?: string;
+    base64?: string;
+    bytes?: number;
+}
+export interface MediaTrackInput {
+    trackId: string;
+    kind: "audio" | "webrtc";
+    label?: string;
+    recordedAt: number;
+    chunks: MediaChunk[];
+}
+export interface TrackGap {
+    startMs: number;
+    endMs: number;
+}
+export interface SynchronizedTrack {
+    trackId: string;
+    kind: "audio" | "webrtc";
+    label: string | null;
+    offsetMs: number;
+    durationMs: number;
+    chunks: MediaChunk[];
+    gaps: TrackGap[];
+    overlaps: TrackGap[];
+    warnings: string[];
+}
+export interface AudioSyncInput {
+    sessionStartedAt: number;
+    tracks: MediaTrackInput[];
+    maxGapMs?: number;
+}
+export interface AudioSyncResult {
+    sessionDurationMs: number;
+    tracks: SynchronizedTrack[];
+    alignmentConfidence: number;
+    warnings: string[];
+}
+export declare class ReplayAudioTrackSynchronizer {
+    static readonly MAX_TRACKS: number;
+    static readonly MAX_CHUNKS: number;
+    /**
+     * Aligns every media track onto the session timeline and computes gaps,
+     * overlaps and a deterministic alignment confidence in the 0..1 range.
+     *
+     * Returned chunk `startMs` values are session-relative (`offsetMs + startMs`).
+     * Input objects are never modified.
+     */
+    synchronize(input: AudioSyncInput): AudioSyncResult;
+    private buildTrack;
+}

package/dist/analytics/replay-timeline-reconstructor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Session Replay Multi-Track Time-Synchronized Timeline Reconstructor
+ *
+ * Implémentation clean-room conforme aux moteurs de lecture OpenReplay & PostHog Session Recording.
+ * Fusionne les mutations DOM (rrweb), logs console, requêtes réseau et interactions frustrantes
+ * en une piste temporelle unifiée, corrèle les erreurs réseau/JS avec les clics rageurs et
+ * produit les marqueurs pour la barre de défilement (scrubber).
+ */
+export type ReplayTrackType = 'dom_mutation' | 'console' | 'network' | 'user_action' | 'navigation';
+export interface RawConsoleEvent {
+    level: 'log' | 'info' | 'warn' | 'error';
+    message: string;
+    stack?: string;
+    timestamp: number;
+}
+export interface RawNetworkEvent {
+    url: string;
+    method: string;
+    status: number;
+    durationMs: number;
+    timestamp: number;
+}
+export interface RawUserActionEvent {
+    type: 'click' | 'rage_click' | 'dead_click' | 'scroll' | 'input';
+    targetSelector?: string;
+    targetText?: string;
+    timestamp: number;
+}
+export interface RawNavigationEvent {
+    fromUrl?: string;
+    toUrl: string;
+    timestamp: number;
+}
+export interface RawDomEvent {
+    rrwebType: number;
+    timestamp: number;
+}
+export interface UnifiedTimelineMarker {
+    id: string;
+    offsetMs: number;
+    track: ReplayTrackType;
+    label: string;
+    severity: 'info' | 'warning' | 'error' | 'critical';
+    details?: Record<string, unknown>;
+    correlatedAnomaly?: string;
+}
+export interface ReplayTimelineSummary {
+    sessionDurationMs: number;
+    startTime: number;
+    endTime: number;
+    totalEvents: number;
+    errorCount: number;
+    failedNetworkCount: number;
+    rageClickCount: number;
+    frustrationScore: number;
+    markers: UnifiedTimelineMarker[];
+    timelineDensityBuckets: number[];
+}
+export interface ReplaySessionTracks {
+    domEvents?: RawDomEvent[];
+    consoleEvents?: RawConsoleEvent[];
+    networkEvents?: RawNetworkEvent[];
+    userActions?: RawUserActionEvent[];
+    navigationEvents?: RawNavigationEvent[];
+}
+export declare class ReplayTimelineReconstructor {
+    /**
+     * Reconstitue la chronologie unifiée d'une session de replay avec détection d'anomalies corrélées.
+     */
+    static reconstruct(tracks: ReplaySessionTracks): ReplayTimelineSummary;
+}

package/dist/analytics/resource-hint-speculation-rules-optimizer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - ResourceHintSpeculationRulesOptimizer
+ * Audits HTML resource hints (preload, prefetch, preconnect, dns-prefetch)
+ * and Speculation Rules API scripts for CWV performance and socket pool efficiency.
+ */
+export type ResourceHintType = "preload" | "prefetch" | "preconnect" | "dns-prefetch" | "speculationrules";
+export interface ResourceHintItem {
+    type: ResourceHintType;
+    href?: string;
+    as?: string;
+    crossorigin?: boolean;
+    fetchpriority?: "high" | "low" | "auto";
+    speculationRulesJson?: unknown;
+}
+export interface ResourceHintIssue {
+    type: "excessive_preconnects" | "missing_as_attribute" | "redundant_dns_prefetch" | "missing_font_crossorigin" | "invalid_speculation_rules" | "too_many_preloads";
+    severity: "critical" | "warning" | "info";
+    description: string;
+    affectedHint?: string;
+    recommendation: string;
+}
+export interface ResourceHintAuditReport {
+    totalHints: number;
+    preconnectCount: number;
+    preloadCount: number;
+    prefetchCount: number;
+    dnsPrefetchCount: number;
+    hasSpeculationRules: boolean;
+    score: number;
+    isOptimal: boolean;
+    issues: ResourceHintIssue[];
+    optimizedHeadSnippet: string;
+}
+export declare class ResourceHintSpeculationRulesOptimizer {
+    /**
+     * Audits an HTML document string or an array of parsed resource hints.
+     */
+    audit(htmlOrHints: string | ResourceHintItem[]): ResourceHintAuditReport;
+    private extractHintsFromHtml;
+    private getOrigin;
+    private generateOptimizedSnippet;
+}

package/dist/analytics/resource-timing-engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Resource Timing Engine
+ *
+ * Analyse et décompose les performances de chargement des ressources (W3C PerformanceResourceTiming) :
+ * scripts tiers, polices de caractères, feuilles de style, images et requêtes API.
+ * Identifie les ressources bloquantes pour le rendu et les gains de compression potentiels.
+ */
+export interface ResourceTimingEntry {
+    name: string;
+    initiatorType: "script" | "css" | "img" | "xmlhttprequest" | "fetch" | "font" | "beacon" | "other" | string;
+    startTime: number;
+    responseEnd: number;
+    duration: number;
+    transferSize?: number;
+    encodedBodySize?: number;
+    decodedBodySize?: number;
+}
+export interface ResourceTypeSummary {
+    count: number;
+    totalDurationMs: number;
+    totalTransferBytes: number;
+    averageDurationMs: number;
+}
+export interface ResourceTimingReport {
+    totalResources: number;
+    totalTransferBytes: number;
+    totalDecodedBytes: number;
+    compressionRatio: number;
+    byInitiatorType: Record<string, ResourceTypeSummary>;
+    firstPartyCount: number;
+    thirdPartyCount: number;
+    firstPartyBytes: number;
+    thirdPartyBytes: number;
+    slowestResources: Array<{
+        name: string;
+        initiatorType: string;
+        durationMs: number;
+        transferBytes: number;
+    }>;
+    renderBlockingCandidates: Array<{
+        name: string;
+        initiatorType: string;
+        durationMs: number;
+        reason: string;
+    }>;
+}
+export declare class ResourceTimingEngine {
+    private primaryOrigin;
+    constructor(primaryOrigin?: string);
+    private normalizeOrigin;
+    private isThirdParty;
+    analyze(entries: ResourceTimingEntry[]): ResourceTimingReport;
+}

package/dist/analytics/resource-timing-transfer-size-discrepancy-auditor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - ResourceTimingTransferSizeDiscrepancyAuditor
+ * Analyzes W3C PerformanceResourceTiming transferSize vs encodedBodySize vs decodedBodySize,
+ * auditing edge CDN cache hits, 304 revalidations, compression gaps, and Timing-Allow-Origin opacity.
+ */
+export interface ResourceTimingMetricInput {
+    name: string;
+    initiatorType: string;
+    transferSize: number;
+    encodedBodySize: number;
+    decodedBodySize: number;
+}
+export type ResourceCacheState = "local_cache_hit" | "conditional_304_revalidated" | "network_edge_cache_miss" | "cross_origin_timing_restricted";
+export interface ResourceTimingDiscrepancyFinding {
+    resourceUrl: string;
+    initiatorType: string;
+    cacheState: ResourceCacheState;
+    isCompressed: boolean;
+    compressionRatio: number;
+    isTaoRestricted: boolean;
+    issues: string[];
+}
+export interface ResourceTimingAuditReport {
+    totalResourcesAudited: number;
+    cacheHitCount: number;
+    cacheMissCount: number;
+    taoRestrictedCount: number;
+    uncompressedTextCount: number;
+    cachingEfficiencyScore: number;
+    findings: ResourceTimingDiscrepancyFinding[];
+    remediationAdvice: string[];
+}
+export declare class ResourceTimingTransferSizeDiscrepancyAuditor {
+    /**
+     * Audits PerformanceResourceTiming entries.
+     */
+    audit(resources: ResourceTimingMetricInput[]): ResourceTimingAuditReport;
+}

package/dist/analytics/responsive-search-ad-creative-builder.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - ResponsiveSearchAdCreativeBuilder
+ *
+ * Repris et adapté sous licence AGPL-3.0-or-later depuis:
+ * - inspiration/01-logiciels-seo-ai/repos/advertools (advertools/ad_create.py & ad_from_string.py)
+ *
+ * Fonctionnalités :
+ * 1. Découpage intelligent de textes longs ou métadonnées SEO en titres (max 30 caractères)
+ *    et descriptions (max 90 caractères) sans troncature brutale de mots.
+ * 2. Génération automatique de variantes Responsive Search Ads (RSA) Google Ads & Microsoft Ads.
+ * 3. Validation des contraintes de caractères, tokens d'insertion dynamique {KeyWord:Default}.
+ * 4. Stratégie de pinning (Position 1: Mot-clé, Position 2: Bénéfice/Différenciateur, Position 3: CTA).
+ * 5. Export au format CSV Google Ads Editor.
+ */
+export interface RsaGenerationInput {
+    targetKeyword: string;
+    brandName: string;
+    uniqueSellingPoints: string[];
+    callToAction: string;
+    sourceText?: string;
+    finalUrl: string;
+    path1?: string;
+    path2?: string;
+}
+export interface GeneratedHeadline {
+    text: string;
+    characterCount: number;
+    pinPosition?: 1 | 2 | 3;
+    type: "keyword" | "brand" | "usp" | "cta" | "custom";
+}
+export interface GeneratedDescription {
+    text: string;
+    characterCount: number;
+    pinPosition?: 1 | 2;
+    type: "primary_benefit" | "social_proof_guarantee" | "summary_cta";
+}
+export interface ResponsiveSearchAd {
+    campaignName: string;
+    adGroupName: string;
+    finalUrl: string;
+    path1: string;
+    path2: string;
+    headlines: GeneratedHeadline[];
+    descriptions: GeneratedDescription[];
+    adStrengthScore: "Poor" | "Average" | "Good" | "Excellent";
+    recommendations: string[];
+}
+export declare class ResponsiveSearchAdCreativeBuilder {
+    static readonly MAX_HEADLINE_CHARS = 30;
+    static readonly MAX_DESCRIPTION_CHARS = 90;
+    static readonly MAX_PATH_CHARS = 15;
+    static readonly MAX_HEADLINES_PER_RSA = 15;
+    static readonly MAX_DESCRIPTIONS_PER_RSA = 4;
+    /**
+     * Découpe une chaîne longue en tranches n'excédant pas maxChars, sans couper au milieu d'un mot.
+     */
+    static splitStringWithoutBreakingWords(text: string, maxChars: number): string[];
+    /**
+     * Valide la syntaxe d'un token d'insertion de mot-clé dynamique {KeyWord:Defaut}.
+     */
+    static isValidDkiToken(token: string): boolean;
+    /**
+     * Génère un ensemble complet de RSA avec titres et descriptions conformes Google Ads.
+     */
+    static generateAd(input: RsaGenerationInput): ResponsiveSearchAd;
+    /**
+     * Exporte l'annonce au format CSV Google Ads Editor officiel.
+     */
+    static exportGoogleAdsEditorCsv(ad: ResponsiveSearchAd): string;
+}

package/dist/analytics/retention-curve-fitting-engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * RetentionCurveFittingEngine — Modélisation Prédictive de Courbe de Rétention & Détection de PMF
+ *
+ * Parité : Amplitude (Retention Curve Power Law & Flattening), PostHog (Cohort Asymptote), Sequoia Capital.
+ *
+ * Analyse les cohortes de rétention empiriques (ex: J0, J1, J7, J14, J30) et ajuste
+ * un modèle mathématique de décroissance en loi de puissance avec asymptote :
+ *
+ * R(t) = a * (t + 1)^(-b) + c
+ *
+ * Où :
+ * - c = Taux de rétention asymptotique (Terminal / Steady-State Retention).
+ * - b = Vitesse de décroissance initiale (Churn Velocity).
+ * - R'(t) = Pente de la courbe.
+ *
+ * Indicateurs stratégiques générés :
+ * 1. Test d'Aplatissement de la Courbe (Curve Flattening) : Détermine si la rétention se stabilise
+ *    (preuve de Product-Market Fit - PMF) ou si elle tend asymptotiquement vers 0 (Seau Percé / Leaky Bucket).
+ * 2. Score de Santé PMF (0 à 100) : Mesure la solidité de la rétention terminale.
+ * 3. Projections à long terme : Prédiction des taux de rétention à J60, J90, J180 et J365.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface RetentionDataPoint {
+    day: number;
+    retentionRate: number;
+}
+export type RetentionPmfGrade = "exceptional_pmf" | "good_pmf" | "moderate" | "leaky_bucket";
+export interface RetentionCurveFittingResult {
+    observedPointsCount: number;
+    modelParameters: {
+        a: number;
+        b: number;
+        c: number;
+    };
+    asymptoticRetentionRate: number;
+    hasFlattened: boolean;
+    flatteningDay: number | null;
+    pmfScore: number;
+    pmfGrade: RetentionPmfGrade;
+    projections: {
+        day60: number;
+        day90: number;
+        day180: number;
+        day365: number;
+    };
+    insights: string[];
+    generatedAt: string;
+}
+export declare class RetentionCurveFittingEngine {
+    fit(points: RetentionDataPoint[]): RetentionCurveFittingResult;
+    private emptyResult;
+}

package/dist/analytics/retention.d.ts

@@ -0,0 +1,6 @@
+export interface CohortRow {
+    cohort: string;
+    size: number;
+    periods: number[];
+}
+export declare function buildCohorts(dates: string[], periodDays?: number): CohortRow[];

package/dist/analytics/rfm-segmentation-engine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RfmSegmentationEngine — Segmentation E-commerce & SaaS RFM (Récence, Fréquence, Montant)
+ *
+ * Catégorise automatiquement les clients en segments comportementaux :
+ * 1. Champions (VIP)
+ * 2. Clients fidèles (Loyal)
+ * 3. Fidèles potentiels (Potential Loyalists)
+ * 4. Nouveaux clients (New Customers)
+ * 5. À risque (At Risk)
+ * 6. En hibernation (Hibernating)
+ * 7. Perdus / Churnés (Lost)
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface RfmTransaction {
+    customerId: string;
+    timestamp: string | Date;
+    amount: number;
+    orderId?: string;
+}
+export type RfmSegmentName = "champions" | "loyal_customers" | "potential_loyalists" | "new_customers" | "at_risk" | "hibernating" | "lost";
+export interface CustomerRfmScore {
+    customerId: string;
+    recencyDays: number;
+    frequency: number;
+    monetaryTotal: number;
+    rScore: number;
+    fScore: number;
+    mScore: number;
+    segment: RfmSegmentName;
+    segmentLabel: string;
+    recommendedAction: string;
+}
+export interface RfmSegmentSummary {
+    segment: RfmSegmentName;
+    label: string;
+    customerCount: number;
+    customerPercentage: number;
+    totalRevenue: number;
+    revenuePercentage: number;
+    averageOrderValue: number;
+    averageRecencyDays: number;
+    recommendedAction: string;
+}
+export interface RfmAnalysisReport {
+    totalCustomers: number;
+    totalRevenue: number;
+    averageRevenuePerCustomer: number;
+    segments: Record<RfmSegmentName, RfmSegmentSummary>;
+    customerScores: CustomerRfmScore[];
+    generatedAt: string;
+}
+export interface RfmOptions {
+    referenceDate?: string | Date;
+}
+export declare class RfmSegmentationEngine {
+    calculate(transactions: RfmTransaction[], options?: RfmOptions): RfmAnalysisReport;
+    private classifySegment;
+    private emptyReport;
+}