@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/analytics/crawl-budget-priority-queue-forecaster.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - CrawlBudgetPriorityQueueForecaster
+ * Analyzes search engine crawl frequency against page update velocity and business value,
+ * diagnosing crawl budget waste (over-crawled static pages) and crawl starvation (under-crawled money pages).
+ */
+export interface PageCrawlProfileInput {
+    url: string;
+    monthlyBotHits: number;
+    lastUpdatedDaysAgo: number;
+    internalPageRankScore: number;
+    organicTrafficMonthly: number;
+    isIndexable: boolean;
+    httpStatusCode: number;
+}
+export type CrawlEfficiencyCategory = "optimal" | "crawl_waste_overcrawled_static" | "crawl_starvation_undercrawled_value" | "dead_weight_non_indexable";
+export interface PageCrawlEfficiencyEvaluation {
+    url: string;
+    category: CrawlEfficiencyCategory;
+    botHitsPerDay: number;
+    valueScore: number;
+    urgencyLevel: "critical" | "high" | "medium" | "low";
+    actionRecommendation: string;
+}
+export interface CrawlBudgetForecastReport {
+    totalPagesAudited: number;
+    totalMonthlyBotHits: number;
+    budgetAllocationEfficiencyScore: number;
+    starvedPagesCount: number;
+    wastedHitsCount: number;
+    evaluations: PageCrawlEfficiencyEvaluation[];
+    strategicRemediations: string[];
+}
+export declare class CrawlBudgetPriorityQueueForecaster {
+    /**
+     * Forecasts and prioritizes crawl budget allocation across site pages.
+     */
+    forecast(pages: PageCrawlProfileInput[]): CrawlBudgetForecastReport;
+}

package/dist/analytics/crawl-budget-waste-auditor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CrawlBudgetWasteAuditor — Audit de Gaspillage du Budget de Crawl & Détecteur de Pièges à Robots
+ *
+ * Parité : OnCrawl & Botify (Crawl Budget Optimization), Screaming Frog (Crawl Traps & Waste).
+ *
+ * Analyse les requêtes des robots d'indexation (Googlebot, Bingbot, etc.) pour mesurer l'efficacité
+ * avec laquelle le budget de crawl du moteur de recherche est alloué sur le site :
+ *
+ * 1. Calcul du Score d'Efficacité du Budget de Crawl (0 à 100).
+ * 2. Quantification des requêtes gaspillées par catégorie :
+ *    - Requêtes sur URLs avec code d'erreur (4xx / 5xx).
+ *    - Requêtes sur redirections (3xx, chaînes et boucles).
+ *    - Requêtes sur pages non indexables (balise 'noindex' ou en-tête X-Robots-Tag).
+ *    - Requêtes sur URLs canonisées vers une autre cible (canonicalisée non canonique).
+ *    - Requêtes sur URLs avec paramètres superflus / facettes infinies / sessions.
+ * 3. Détection de Pièges à Robots (Crawl Traps) :
+ *    - Répétition cyclique de segments d'URL (ex: /category/shoes/category/shoes/...).
+ *    - Explosion de facettes et paramètres combinatoires non canonicalisés.
+ *    - Boucles infinies de calendrier / pagination sans fin.
+ * 4. Plan de redressement chiffré du budget de crawl (Robots.txt, en-têtes HTTP, canonical).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface CrawledUrlHit {
+    url: string;
+    statusCode: number;
+    hitCount: number;
+    isNoindex?: boolean;
+    canonicalUrl?: string | null;
+    hasFacetedParams?: boolean;
+    responseTimeMs?: number;
+}
+export type WasteCategory = "client_server_errors" | "redirects" | "noindex_pages" | "non_canonical_pages" | "faceted_parameter_noise" | "crawl_trap";
+export interface WasteBreakdown {
+    category: WasteCategory;
+    wastedHits: number;
+    percentageOfTotalCrawl: number;
+    sampleUrls: string[];
+}
+export interface CrawlTrap {
+    patternType: "repeating_segment" | "faceted_explosion" | "calendar_loop" | "session_id_in_url";
+    sampleUrl: string;
+    wastedHits: number;
+    severity: "high" | "critical";
+    recommendation: string;
+}
+export interface CrawlBudgetWasteReport {
+    totalBotHits: number;
+    usefulHits: number;
+    wastedHits: number;
+    wastePercentage: number;
+    crawlBudgetEfficiencyScore: number;
+    breakdown: WasteBreakdown[];
+    crawlTraps: CrawlTrap[];
+    potentialIndexationGain: string;
+    actionChecklist: string[];
+    generatedAt: string;
+}
+export declare class CrawlBudgetWasteAuditor {
+    audit(hits: CrawledUrlHit[]): CrawlBudgetWasteReport;
+    private detectTrap;
+    private hasUnfilteredFacets;
+    private emptyReport;
+}

package/dist/analytics/crawl-depth-click-distance-auditor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CrawlDepthClickDistanceAuditor — Audit de Profondeur de Clic (Crawl Depth BFS) & Diagnostic d'Enfouissement
+ *
+ * Parité : OnCrawl (Crawl Depth Distribution) & Screaming Frog (Click Distance).
+ *
+ * En SEO technique, la distance en clics (Click Depth) depuis la page d'accueil
+ * est un facteur déterminant pour l'indexation et le positionnement :
+ * - Profondeur 1 à 3 : Zone optimale explorée fréquemment par Googlebot.
+ * - Profondeur 4 et plus : "Pages enfouies" (Buried Pages) subissant une chute drastique
+ *   de budget de crawl et une perte majeure de PageRank interne.
+ *
+ * Fonctionnalités du moteur :
+ * 1. Algorithme BFS (Breadth-First Search) calculant la distance la plus courte depuis la racine (Seed URL).
+ * 2. Ventilation de la distribution de profondeur (Profondeur 0, 1, 2, 3, 4, 5+).
+ * 3. Indice de Risque de Pénalité d'Enfouissement (Deep Crawl Penalty Risk : safe, warning, severe).
+ * 4. Détection des pages critiques enfouies et génération de recommandations de raccourcis internes (Internal Shortcuts).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface InternalGraphEdge {
+    sourceUrl: string;
+    targetUrl: string;
+}
+export interface PageCrawlDepthInfo {
+    url: string;
+    depth: number;
+    isBuried: boolean;
+    shortestPath: string[];
+}
+export interface DepthDistributionTier {
+    depth: number;
+    count: number;
+    percentage: number;
+}
+export interface CrawlDepthAuditReport {
+    seedUrl: string;
+    totalPagesAudited: number;
+    buriedPagesCount: number;
+    buriedPercentage: number;
+    maxDepthReached: number;
+    averageDepth: number;
+    penaltyRisk: "safe" | "warning" | "severe";
+    distribution: DepthDistributionTier[];
+    buriedPagesSample: PageCrawlDepthInfo[];
+    shortcutRecommendations: string[];
+    generatedAt: string;
+}
+export declare class CrawlDepthClickDistanceAuditor {
+    audit(seedUrl: string, allUrls: string[], edges: InternalGraphEdge[]): CrawlDepthAuditReport;
+    private normalizeUrl;
+    private emptyReport;
+}

package/dist/analytics/crawl-log-cross-correlation-engine.d.ts

@@ -0,0 +1,85 @@
+/**
+ * CrawlLogCrossCorrelationEngine — Croisement Logs Serveurs x Google Search Console x Structure de Site
+ *
+ * Parité : OnCrawl, Botify, Screaming Frog Log File Analyser.
+ *
+ * Détecte :
+ * 1. Pages Zombies : Fort crawl bot mais 0 performance dans Google Search Console (gaspillage de budget de crawl).
+ * 2. Pages Orphelines : Pages recevant des bots ou présentes dans le sitemap sans aucun lien interne.
+ * 3. Répartition & Gaspillage du Budget de Crawl (Crawl Budget Waste Ratio) : Requêtes sur codes d'erreur (4xx, 5xx), redirections (3xx) et paramètres sans valeur.
+ * 4. Décomposition par bot (Googlebot, Bingbot, ClaudeBot, GPTBot, PerplexityBot, ByteSpider).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface BotLogEntry {
+    url: string;
+    botName: string;
+    hitCount: number;
+    statusCode: number;
+    bytesTransferred?: number;
+}
+export interface SiteUrlStructure {
+    url: string;
+    inboundInternalLinksCount: number;
+    depth?: number;
+    isInSitemap?: boolean;
+}
+export interface SearchConsoleUrlMetric {
+    url: string;
+    clicks: number;
+    impressions: number;
+    ctr?: number;
+    position?: number;
+}
+export interface ZombiePageReport {
+    url: string;
+    botHits: number;
+    impressions: number;
+    clicks: number;
+    primaryBot: string;
+    wastedBytes: number;
+    severity: "high" | "medium" | "low";
+    recommendedAction: "noindex" | "canonicalize" | "301_redirect" | "block_robots_txt";
+    reason: string;
+}
+export interface OrphanPageReport {
+    url: string;
+    botHits: number;
+    isInSitemap: boolean;
+    clicks: number;
+    impressions: number;
+    recommendedAction: "link_from_parent_category" | "remove_from_sitemap" | "investigate";
+}
+export interface BotBreakdownMetric {
+    botName: string;
+    totalHits: number;
+    percentageOfAllCrawls: number;
+    wastedHits: number;
+    wastedPercentage: number;
+}
+export interface CrawlCrossCorrelationReport {
+    totalBotHits: number;
+    totalUrlsCrawled: number;
+    crawlBudgetWasteCount: number;
+    crawlBudgetWastePercentage: number;
+    zombiePages: ZombiePageReport[];
+    orphanPages: OrphanPageReport[];
+    botBreakdown: BotBreakdownMetric[];
+    statusCodesDistribution: Record<string, number>;
+    summary: {
+        totalZombieCount: number;
+        totalOrphanCount: number;
+        wastedBandwidthBytes: number;
+        healthScore: number;
+    };
+    generatedAt: string;
+}
+export declare class CrawlLogCrossCorrelationEngine {
+    /**
+     * Seuil minimum de hits bot pour qualifier une page de "Zombie" si 0 impression.
+     */
+    private readonly ZOMBIE_BOT_HITS_THRESHOLD;
+    analyze(botLogs: BotLogEntry[], siteStructure?: SiteUrlStructure[], gscMetrics?: SearchConsoleUrlMetric[]): CrawlCrossCorrelationReport;
+    private normalizeUrl;
+    private emptyReport;
+}

package/dist/analytics/cross-domain-linker.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CrossDomainLinker — Suivi multi-domaines sans cookies tiers (Matomo _pk_vid & GA4 _gl Parity)
+ *
+ * Permet de préserver l'identité de session et le visitorId lors du passage
+ * entre différents domaines d'une même marque (ex: boutique.fr → checkout.com)
+ * sans recourir aux cookies tiers bloqués par ITP / Safari / Chrome :
+ * - Signe cryptographiquement le visitorId avec un sel/secret partagé et un timestamp
+ * - Injecte le paramètre `_lynx_cid` sur les liens sortants autorisés
+ * - Valide et extrait le visitorId côté destination avec protection anti-rejeu et expiration.
+ */
+export interface CrossDomainTokenPayload {
+    visitorId: string;
+    timestamp: number;
+    hash: string;
+}
+export interface CrossDomainValidationResult {
+    valid: boolean;
+    visitorId: string | null;
+    timestamp?: number;
+    ageMs?: number;
+    reason?: "missing_param" | "malformed" | "expired" | "invalid_signature";
+}
+export declare class CrossDomainLinker {
+    static readonly DEFAULT_PARAM_NAME = "_lynx_cid";
+    static readonly DEFAULT_MAX_AGE_MS = 180000;
+    /**
+     * Calcule un hash déterministe pour signer le token
+     */
+    private static computeHash;
+    /**
+     * Crée un token signé pour un visiteur
+     */
+    static generateToken(visitorId: string, secret: string, timestamp?: number): string;
+    /**
+     * Décore une URL avec le paramètre de tracking cross-domain si le domaine est autorisé
+     */
+    static decorateUrl(targetUrl: string, visitorId: string, allowedDomains: string[], secret: string, paramName?: string, timestamp?: number): string;
+    /**
+     * Valide un token cross-domain extrait d'une URL
+     */
+    static validateToken(token: string, secret: string, maxAgeMs?: number, now?: number): CrossDomainValidationResult;
+    /**
+     * Extrait et valide directement depuis une URL complète
+     */
+    static extractFromUrl(urlString: string, secret: string, maxAgeMs?: number, paramName?: string, now?: number): CrossDomainValidationResult;
+    /**
+     * Génère le snippet JS client pour l'auto-décoration des balises <a> sortantes
+     */
+    static generateClientDecoratorScript(allowedDomains: string[], paramName?: string): string;
+}

package/dist/analytics/crux.d.ts

@@ -0,0 +1,9 @@
+export interface CruxMetric {
+    metric: 'LCP' | 'INP' | 'CLS' | 'FID';
+    p75: number;
+    category: 'FAST' | 'AVERAGE' | 'SLOW';
+}
+export declare function categorizeCrux(m: 'LCP' | 'INP' | 'CLS' | 'FID', p75v: number): 'FAST' | 'AVERAGE' | 'SLOW';
+export declare function mergeRUMCrux(rumP75: Record<string, number>, crux: CruxMetric[]): {
+    [x: string]: number;
+};

package/dist/analytics/css-rules-mutation-tracker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CSS Rules Mutation Tracker & CSSOM Thrash Analyzer
+ * Clean-room implementation inspired by OpenReplay cssrules & CSSOM performance diagnostics.
+ * Monitors dynamic stylesheet rule insertions, deletions, and updates, detecting style recalculation thrashing.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface CssRuleMutationEvent {
+    action: 'insert' | 'delete' | 'modify';
+    styleSheetId?: string;
+    ruleText: string;
+    index: number;
+    timestamp: number;
+}
+export interface CssMutationAnalysis {
+    totalMutations: number;
+    insertions: number;
+    deletions: number;
+    modifications: number;
+    themeSwitchDetected: boolean;
+    excessiveMutationWarning: boolean;
+    expensiveSelectors: string[];
+    maxMutationFrequencyPerSec: number;
+}
+export declare class CssRulesMutationTracker {
+    private static readonly THEME_KEYWORDS;
+    static analyzeMutations(events: CssRuleMutationEvent[]): CssMutationAnalysis;
+}

package/dist/analytics/cumulative-layout-shift-target-element-clusterer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - CumulativeLayoutShiftTargetElementClusterer
+ * Implements W3C / Chrome Web Vitals v4 Session Window clustering for CLS,
+ * identifies the maximum shift window, attributes culprits to DOM nodes, and generates CSS fixes.
+ */
+export interface DomRectSnapshot {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    width: number;
+    height: number;
+}
+export interface LayoutShiftSourceNode {
+    nodeSelector: string;
+    previousRect?: DomRectSnapshot;
+    currentRect?: DomRectSnapshot;
+}
+export interface ClsRawLayoutShiftEntry {
+    timestampMs: number;
+    value: number;
+    hadRecentInput?: boolean;
+    sources?: LayoutShiftSourceNode[];
+}
+export interface LayoutShiftSessionWindow {
+    windowIndex: number;
+    startTimeMs: number;
+    endTimeMs: number;
+    durationMs: number;
+    windowScore: number;
+    shifts: ClsRawLayoutShiftEntry[];
+}
+export interface CulpritElementAttribution {
+    nodeSelector: string;
+    totalShiftContribution: number;
+    percentageOfWindow: number;
+    inferredCause: "un_dimensioned_ad_banner" | "late_injected_modal_or_bar" | "font_foit_fout_swap" | "general_layout_jump";
+    recommendedCssFix: string;
+}
+export interface ClsClusterReport {
+    overallClsScore: number;
+    rating: "good" | "needs_improvement" | "poor";
+    sessionWindowCount: number;
+    maxSessionWindow: LayoutShiftSessionWindow;
+    culpritElements: CulpritElementAttribution[];
+}
+export declare class CumulativeLayoutShiftTargetElementClusterer {
+    private static readonly MAX_GAP_MS;
+    private static readonly MAX_DURATION_MS;
+    /**
+     * Clusters raw layout shifts into session windows and attributes the worst cluster.
+     */
+    clusterAndAttribute(entries: ClsRawLayoutShiftEntry[]): ClsClusterReport;
+    private buildWindow;
+    private inferCause;
+}

package/dist/analytics/currency-converter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Multi-Currency Engine for LynxSEO E-commerce & Pulse Analytics
+ * Clean-room implementation inspired by enterprise multi-currency handling (Matomo multi-currency).
+ */
+export type SupportedCurrency = "EUR" | "USD" | "GBP" | "CAD" | "AUD" | "CHF" | "JPY" | "CNY";
+/**
+ * Mid-market reference rates relative to EUR (base = 1.0)
+ */
+export declare const DEFAULT_EXCHANGE_RATES: Record<SupportedCurrency, number>;
+export interface MultiCurrencyBreakdownItem {
+    originalCurrency: string;
+    originalAmount: number;
+    convertedAmount: number;
+    percentageOfTotal: number;
+    orderCount: number;
+}
+export interface MultiCurrencyAggregationResult {
+    targetCurrency: SupportedCurrency;
+    totalConvertedRevenue: number;
+    totalOrders: number;
+    breakdown: Record<string, MultiCurrencyBreakdownItem>;
+}
+/**
+ * Converts a monetary value between any two supported currencies using EUR as intermediary pivot.
+ */
+export declare function convertCurrency(amount: number, from: string, to: SupportedCurrency, customRates?: Record<string, number>): number;
+/**
+ * Formats an amount with standard localized currency symbols.
+ */
+export declare function formatCurrencyAmount(amount: number, currency?: SupportedCurrency | string, locale?: string): string;
+/**
+ * Aggregates a list of multi-currency orders/transactions into a unified base currency.
+ */
+export declare function aggregateMultiCurrencyOrders(orders: Array<{
+    amount: number;
+    currency: string;
+}>, targetCurrency?: SupportedCurrency, customRates?: Record<string, number>): MultiCurrencyAggregationResult;

package/dist/analytics/custom-alerts-engine.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Custom Alerts & Anomaly Trigger Engine
+ *
+ * Clean-room implementation inspired by Matomo CustomAlerts & PostHog alert destinations.
+ * Evaluates incoming metric aggregates against threshold or percentage change conditions,
+ * generates alert notifications with debounce/cooldown rules, and formats webhook payloads.
+ */
+export interface MetricAlertRule {
+    id: string;
+    name: string;
+    siteId: string;
+    metric: "visits" | "bounce_rate" | "revenue" | "errors" | "conversion_rate" | "p95_latency";
+    condition: "greater_than" | "less_than" | "increases_by_pct" | "decreases_by_pct";
+    threshold: number;
+    period: "hourly" | "daily" | "weekly";
+    webhookUrl?: string;
+    emailRecipients?: string[];
+    cooldownMinutes: number;
+    lastTriggeredAt?: number;
+    enabled: boolean;
+}
+export interface MetricAlertEvaluation {
+    ruleId: string;
+    triggered: boolean;
+    currentValue: number;
+    previousValue?: number;
+    differencePct?: number;
+    message: string;
+    evaluatedAt: number;
+}
+export declare class CustomAlertsEngine {
+    private rules;
+    registerRule(rule: MetricAlertRule): void;
+    getRule(id: string): MetricAlertRule | undefined;
+    evaluateMetric(ruleId: string, currentValue: number, previousValue?: number, currentTimeMs?: number): MetricAlertEvaluation;
+    clear(): void;
+}

package/dist/analytics/custom-variables-engine.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Custom Variables & Scoped Slots Engine
+ *
+ * Clean-room implementation inspired by Matomo CustomVariables.
+ * Manages visit-scoped and page-scoped key/value custom dimensions across numbered slots (1 to 5),
+ * enforcing slot isolation, length limits, and scoped variable inheritance.
+ */
+export interface CustomVariableSlot {
+    index: number;
+    name: string;
+    value: string;
+    scope: "visit" | "page";
+}
+export interface CustomVariablesSnapshot {
+    visitVariables: Record<string, string>;
+    pageVariables: Record<string, string>;
+}
+export declare class CustomVariablesEngine {
+    private visitSlots;
+    private pageSlots;
+    setVariable(index: number, name: string, value: string, scope?: "visit" | "page"): boolean;
+    getVariable(index: number, scope?: "visit" | "page"): {
+        name: string;
+        value: string;
+    } | undefined;
+    deleteVariable(index: number, scope?: "visit" | "page"): void;
+    clearPageVariables(): void;
+    getSnapshot(): CustomVariablesSnapshot;
+    clear(): void;
+}

package/dist/analytics/customer-lifetime-value-survival-engine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Customer Lifetime Value Survival Engine (Batch 16 - Gap 4)
+ *
+ * Kaplan-Meier cohort survival & Customer Lifetime Value (CLV/LTV) forecasting engine
+ * inspired by Amplitude Cohort LTV, GA4 Predictive Metrics & RetentionX.
+ *
+ * Models monthly survival curves S(t), projects 12-month & 24-month cumulative LTV,
+ * calculates CAC Payback Periods, and isolates segment profitability (Organic Search vs Paid).
+ */
+export interface CustomerCohortRecord {
+    customerId: string;
+    segment: string;
+    tenureMonths: number;
+    totalHistoricalSpend: number;
+    isChurned: boolean;
+    acquisitionCostCac?: number;
+}
+export interface MonthSurvivalDataPoint {
+    month: number;
+    atRiskCount: number;
+    churnedCount: number;
+    survivalProbabilityPct: number;
+    projectedCumulativeLtv: number;
+}
+export interface SegmentLtvSurvivalAnalysis {
+    segment: string;
+    customerCount: number;
+    averageTenureMonths: number;
+    averageHistoricalSpend: number;
+    projected12MonthLtv: number;
+    projected24MonthLtv: number;
+    averageCac: number;
+    ltvToCacRatio: number;
+    cacPaybackMonths: number;
+    survivalCurve: MonthSurvivalDataPoint[];
+}
+export interface ClvSurvivalAuditReport {
+    totalCustomersAudited: number;
+    overallBlended12MonthLtv: number;
+    overallBlended24MonthLtv: number;
+    blendedLtvToCacRatio: number;
+    segmentsAnalysis: SegmentLtvSurvivalAnalysis[];
+    highestRoiAcquisitionChannel: string;
+    financialInsights: string[];
+}
+export declare class CustomerLifetimeValueSurvivalEngine {
+    /**
+     * Computes Kaplan-Meier survival probabilities and LTV projections by segment.
+     */
+    static modelCohortLtv(customers: CustomerCohortRecord[], defaultCac?: number): ClvSurvivalAuditReport;
+    private static calculateKaplanMeier;
+}

package/dist/analytics/customer-ltv-modeler.d.ts

@@ -0,0 +1,80 @@
+/**
+ * CustomerLtvModeler — Modélisation prédictive de la Lifetime Value (LTV) et du risque de Churn (Parité PostHog / Mixpanel / Amplitude).
+ *
+ * Fournit :
+ * 1. Segmentation RFM (Recency, Frequency, Monetary) avec scores 1-5 et persona client.
+ * 2. Modèle de probabilité de Churn basé sur la cadence d'achat historique et le temps écoulé.
+ * 3. Courbes de LTV cumulée par cohorte de vintage (Day 30, 60, 90, 180, 365).
+ * 4. Prévision de LTV à 12 mois et alertes sur les comptes à forte valeur en décroissance.
+ */
+export interface CustomerTransaction {
+    customerId: string;
+    timestamp: string | number;
+    amount: number;
+    currency?: string;
+    orderId?: string;
+}
+export type RfmSegment = "champion" | "loyal" | "potential_loyalist" | "recent_customer" | "promising" | "needs_attention" | "about_to_sleep" | "at_risk" | "cant_lose" | "hibernating" | "lost";
+export type ChurnRiskLevel = "low" | "medium" | "high" | "critical";
+export interface CustomerProfileAnalysis {
+    customerId: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    daysSinceLastPurchase: number;
+    customerLifespanDays: number;
+    totalOrders: number;
+    totalSpend: number;
+    averageOrderValue: number;
+    averageDaysBetweenOrders: number;
+    rfm: {
+        recencyScore: number;
+        frequencyScore: number;
+        monetaryScore: number;
+        compositeScore: number;
+        segment: RfmSegment;
+        segmentLabel: string;
+    };
+    churnPrediction: {
+        churnProbability: number;
+        riskLevel: ChurnRiskLevel;
+        projectedDaysToChurn: number;
+    };
+    projected12MonthLtv: number;
+}
+export interface CohortLtvPoint {
+    cohortVintage: string;
+    initialCustomersCount: number;
+    initialRevenue: number;
+    cumulativeLtvDay30: number;
+    cumulativeLtvDay60: number;
+    cumulativeLtvDay90: number;
+    cumulativeLtvDay180: number;
+    cumulativeLtvDay365: number;
+    projectedAnnualLtv: number;
+}
+export interface CustomerLtvReport {
+    analyzedCustomersCount: number;
+    totalRevenue: number;
+    averageLtv: number;
+    medianLtv: number;
+    averageAov: number;
+    highRiskHighValueCustomersCount: number;
+    segmentsDistribution: Record<RfmSegment, {
+        count: number;
+        percentage: number;
+        totalRevenue: number;
+    }>;
+    cohortLtvCurves: CohortLtvPoint[];
+    topAtRiskCustomers: Array<{
+        customerId: string;
+        totalSpend: number;
+        daysSinceLastPurchase: number;
+        churnProbability: number;
+    }>;
+}
+export declare class CustomerLtvModeler {
+    /**
+     * Analyse un ensemble de transactions pour calculer les scores RFM, la LTV prédictive et les cohortes.
+     */
+    static analyze(transactions: CustomerTransaction[], referenceTimestamp?: number | string): CustomerLtvReport;
+}