@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/dashboard-rss-widget.d.ts

@@ -0,0 +1,110 @@
+/**
+ * RssDashboardWidget — Widget de tableau de bord RSS.
+ *
+ * Utilise RssWidgetParser pour récupérer et afficher des flux RSS externes
+ * dans un widget dashboard. Compatible avec le système DashboardWidgetsPlugin.
+ *
+ * Features :
+ * - URL allowlist stricte (anti-SSRF) via isAllowedFeedUrl
+ * - Parseur XML tolérant sans DTD ni entités externes (protection XXE)
+ * - Nettoyage HTML systématique (protection XSS)
+ * - Borne du volume (max items, max description chars)
+ * - Formats RSS 2.0 et Atom supportés
+ */
+import { type ParsedRssWidgetFeed } from "./rss-widget-feed";
+import { type DashboardWidget } from "../plugins/dashboard-widgets/index";
+import type { LynxSeoPlugin, PluginManifest, PluginContext, PluginEvent } from "../../plugin/types";
+export interface RssDashboardWidgetConfig {
+    /** URL du flux RSS/Atom (doit passer isAllowedFeedUrl) */
+    feedUrl: string;
+    /** Nombre maximum d'éléments à afficher (défaut: 10) */
+    maxItems?: number;
+    /** Longueur maximale de description en caractères (défaut: 500) */
+    maxDescriptionChars?: number;
+    /** Titre personnalisé du widget */
+    title?: string;
+}
+/** Identifiant unique pour un widget RSS */
+export type RssWidgetId = string;
+/** État interne du widget RSS */
+export interface RssWidgetState {
+    /** Dernier flux parsé */
+    lastFeed: ParsedRssWidgetFeed | null;
+    /** Temps du dernier rechargement */
+    lastUpdated: string | null;
+    /** En cours de chargement */
+    isLoading: boolean;
+    /** Message d'erreur le cas échéant */
+    error: string | null;
+}
+/** Default config for RSS dashboard widget */
+export declare const DEFAULT_RSS_WIDGET_CONFIG: RssDashboardWidgetConfig;
+/**
+ * Service widget RSS - gère la création, la mise à jour et le cycle de vie
+ * des widgets RSS dans les tableaux de bord.
+ */
+export declare class RssDashboardWidgetService {
+    private widgets;
+    /**
+     * Crée un nouveau widget RSS.
+     * Valide l'URL via isAllowedFeedUrl avant le stockage.
+     */
+    create(config: RssDashboardWidgetConfig): RssWidgetId;
+    /**
+     * Récupère l'état d'un widget RSS.
+     */
+    get(id: RssWidgetId): RssWidgetState | undefined;
+    /**
+     * Met à jour un widget RSS en récupérant le flux.
+     * Appelle le parseur et met à jour l'état atomiquement.
+     */
+    update(id: RssWidgetId, config: RssDashboardWidgetConfig): Promise<RssWidgetState>;
+    /**
+     * Supprime un widget RSS.
+     */
+    delete(id: RssWidgetId): boolean;
+    /**
+     * Liste tous les widgets RSS.
+     */
+    list(): RssWidgetState[];
+    /**
+     * Vide tous les widgets.
+     */
+    clear(): void;
+    /**
+     * Compte les widgets actifs.
+     */
+    count(): number;
+}
+/**
+ * Plugin Dashboard RSS - déclaration du plugin LynxSEO.
+ *
+ * S'abonne aux événements tracker.dashboard.widget pour enregistrer
+ * les widgets RSS créés via le système de widgets.
+ */
+export declare class DashboardRssPlugin implements LynxSeoPlugin {
+    readonly manifest: PluginManifest;
+    private service;
+    private ctx?;
+    enable(_ctx: PluginContext): Promise<void>;
+    disable(): Promise<void>;
+    onEvent(event: PluginEvent): Promise<void>;
+    create(config: RssDashboardWidgetConfig): RssWidgetId;
+    get(id: RssWidgetId): RssWidgetState | undefined;
+    list(): RssWidgetState[];
+    update(id: RssWidgetId, patch: Partial<DashboardWidget>): DashboardWidget | undefined;
+    delete(id: RssWidgetId): boolean;
+    count(): number;
+    reset(): void;
+}
+/** Export par défaut du plugin */
+declare const _default: DashboardRssPlugin;
+export default _default;
+/**
+ * Utilitaire : parse un flux RSS/Atom de manière asynchrone.
+ * Utilisé par les routeurs d'API et les composants React.
+ */
+export declare function parseRssFeed(feedUrl: string, options?: {
+    maxItems?: number;
+    maxDescriptionChars?: number;
+}): Promise<ParsedRssWidgetFeed>;

package/dist/analytics/data-retention-lifecycle-manager.d.ts

@@ -0,0 +1,81 @@
+/**
+ * LynxSEO Engine - Data Retention & Privacy Lifecycle Manager
+ * Parité Matomo PrivacyManager & PostHog Data Retention Policies.
+ *
+ * Gestion des politiques de rétention RGPD, purge progressive des logs bruts,
+ * anonymisation des adresses IP en cascade et plans d'effacement sécurisés.
+ */
+export interface DataRetentionPolicy {
+    siteId: string;
+    rawEventsRetentionDays: number;
+    sessionReplayRetentionDays: number;
+    anonymizeIpAfterDays: number;
+    ipAnonymizationMaskOctets: 1 | 2 | 3;
+    rollupAggregationBeforePurge: boolean;
+    autoPurgeEnabled: boolean;
+}
+export interface RetentionSimulatedItem {
+    id: string;
+    timestamp: string | number;
+    ipAddress?: string;
+    userId?: string;
+    isReplayChunk?: boolean;
+}
+export interface RetentionPurgeAction {
+    targetTable: "pulse_events" | "pulse_replays" | "pulse_sessions" | "pulse_visitor_profiles";
+    action: "delete" | "anonymize" | "rollup";
+    affectedCount: number;
+    cutoffIso: string;
+    description: string;
+}
+export interface RetentionPurgePlan {
+    siteId: string;
+    generatedAtIso: string;
+    policy: DataRetentionPolicy;
+    totalItemsScanned: number;
+    totalDeletionsPlanned: number;
+    totalAnonymizationsPlanned: number;
+    actions: RetentionPurgeAction[];
+    safeguardTriggered: boolean;
+    safeguardReason?: string;
+}
+export interface GdprErasureExecution {
+    siteId: string;
+    targetIdentifier: string;
+    identifierType: "userId" | "userPseudoId";
+    executedAtIso: string;
+    deletedEventsCount: number;
+    deletedReplaySessionsCount: number;
+    deletedProfileRecordsCount: number;
+    status: "completed" | "partial" | "failed";
+    auditSignature: string;
+}
+export declare class DataRetentionLifecycleManager {
+    /**
+     * Génère un plan de purge et d'anonymisation basé sur la politique configurée.
+     */
+    generatePurgePlan(policy: DataRetentionPolicy, items: RetentionSimulatedItem[], nowDate?: string | number): RetentionPurgePlan;
+    /**
+     * Masque les octets d'une adresse IP IPv4 ou IPv6 selon la norme RGPD / Matomo.
+     */
+    maskIpAddress(ip: string, maskOctets?: 1 | 2 | 3): string;
+    /**
+     * Exécute un effacement RGPD (Droit à l'oubli) complet pour un identifiant utilisateur.
+     */
+    executeGdprErasure(siteId: string, targetIdentifier: string, identifierType: "userId" | "userPseudoId", dataset: {
+        events: Array<{
+            userId?: string;
+            userPseudoId?: string;
+        }>;
+        replays: Array<{
+            userId?: string;
+            userPseudoId?: string;
+        }>;
+        profiles: Array<{
+            userId?: string;
+            userPseudoId?: string;
+        }>;
+    }): GdprErasureExecution;
+    private isIpAlreadyMasked;
+    private simpleHash;
+}

package/dist/analytics/data-staleness-sentinel.d.ts

@@ -0,0 +1,37 @@
+/**
+ * LynxSEO Engine - Data Freshness & Pipeline Staleness Sentinel
+ *
+ * Monitors data ingestion lag, pipeline delays, and rollups freshness
+ * to alert marketers and engineers when dashboards are viewing stale data.
+ *
+ * (Parity: Metabase Data Freshness & PostHog Pipeline Health).
+ */
+export interface PipelineComponentStatus {
+    componentId: string;
+    name: string;
+    lastIngestedTimestamp: string | number;
+    expectedMaxLagMinutes: number;
+    warningLagMinutes: number;
+}
+export interface ComponentStalenessEvaluation {
+    componentId: string;
+    name: string;
+    lastIngestedAt: string;
+    lagMinutes: number;
+    status: "realtime" | "healthy" | "delayed" | "critical_staleness";
+    recommendation?: string;
+}
+export interface PipelineStalenessReport {
+    overallHealthScore: number;
+    status: "healthy" | "degraded" | "critical";
+    evaluations: ComponentStalenessEvaluation[];
+    staleComponentsCount: number;
+    mostStaleComponent?: ComponentStalenessEvaluation;
+    generatedAt: string;
+}
+export declare class DataStalenessSentinel {
+    /**
+     * Evaluates freshness across multiple data pipeline components.
+     */
+    evaluateFreshness(components: PipelineComponentStatus[], now?: Date): PipelineStalenessReport;
+}

package/dist/analytics/device-detector-cache.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Device Detector LRU Cache Engine
+ *
+ * Clean-room implementation inspired by Matomo DeviceDetectorCache.
+ * Provides high-performance, bounded in-memory LRU caching of parsed User-Agent strings,
+ * device classifications, OS, and browser specs to minimize parsing overhead on high-throughput collectors.
+ */
+export interface DeviceDetectorParsedInfo {
+    userAgent: string;
+    deviceType: "desktop" | "mobile" | "tablet" | "tv" | "bot" | "unknown";
+    osFamily: string;
+    osVersion: string;
+    browserFamily: string;
+    browserVersion: string;
+    brand?: string;
+    model?: string;
+    isBot: boolean;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRatio: number;
+    size: number;
+    maxCapacity: number;
+    evictionCount: number;
+}
+export declare class DeviceDetectorCache {
+    private cache;
+    private maxCapacity;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(maxCapacity?: number);
+    get(userAgent: string): DeviceDetectorParsedInfo | undefined;
+    set(userAgent: string, info: DeviceDetectorParsedInfo): void;
+    getOrParse(userAgent: string, parseFn: (ua: string) => DeviceDetectorParsedInfo): DeviceDetectorParsedInfo;
+    getStats(): CacheStats;
+    clear(): void;
+}

package/dist/analytics/device-hardware-engine.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Device Hardware Engine
+ *
+ * Évalue les capacités matérielles du terminal utilisateur (RAM, cœurs CPU, écran, GPU)
+ * pour classifier la machine en catégories de puissance (low-end, mid-range, high-end)
+ * et adapter la collecte télémétrique (échantillonnage de replay, animations).
+ */
+export interface DeviceHardwareInput {
+    deviceMemoryGb?: number;
+    hardwareConcurrency?: number;
+    maxTouchPoints?: number;
+    screenWidth?: number;
+    screenHeight?: number;
+    pixelRatio?: number;
+    gpuRenderer?: string;
+}
+export type HardwareTier = "low-end" | "mid-range" | "high-end";
+export interface DeviceHardwareProfile {
+    deviceMemoryGb: number;
+    hardwareConcurrency: number;
+    maxTouchPoints: number;
+    gpuRenderer: string;
+    hardwareScore: number;
+    tier: HardwareTier;
+    recommendedSamplingRate: number;
+    adaptiveFlags: {
+        disableHeavyReplay: boolean;
+        reduceAnimationTelemetry: boolean;
+        enableAggressiveCompression: boolean;
+    };
+}
+export declare class DeviceHardwareEngine {
+    static evaluateProfile(input: DeviceHardwareInput): DeviceHardwareProfile;
+}

package/dist/analytics/disavow-file-format-syntax-validator.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - DisavowFileFormatSyntaxValidator
+ * Validates Google Search Console disavow link files according to official format specifications,
+ * catching malformed domain directives, protocol prefixes, duplicate entries, and size limit breaches.
+ */
+export interface DisavowLineError {
+    lineNumber: number;
+    rawLine: string;
+    errorCode: "invalid_domain_directive_with_protocol" | "invalid_domain_directive_with_path" | "invalid_url_format" | "wildcard_not_supported" | "empty_domain_value";
+    message: string;
+}
+export interface DisavowValidationReport {
+    isValid: boolean;
+    totalLines: number;
+    commentsCount: number;
+    validDomainsCount: number;
+    validUrlsCount: number;
+    duplicateEntriesCount: number;
+    disavowedDomains: string[];
+    disavowedUrls: string[];
+    errors: DisavowLineError[];
+    warnings: string[];
+}
+export declare class DisavowFileFormatSyntaxValidator {
+    private static readonly MAX_FILE_SIZE_BYTES;
+    private static readonly MAX_ENTRIES_LIMIT;
+    /**
+     * Validates raw text content of a disavow file.
+     */
+    validate(rawFileContent: string): DisavowValidationReport;
+}

package/dist/analytics/domain-connect-dns.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Domain Connect DNS Auto-Configuration & Verification Engine
+ *
+ * Clean-room implementation following the domainconnect.org v2 specification.
+ * Facilitates 1-click DNS record configuration (CNAME / TXT) for custom analytics
+ * proxy subdomains and validates DNS propagation status.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface DomainConnectServiceConfig {
+    providerId: string;
+    serviceId: string;
+    targetCname: string;
+    clientRedirectOrigin: string;
+}
+export interface DomainConnectApplyUrlOptions {
+    domain: string;
+    subdomain: string;
+    projectId: string;
+    dnsProviderBaseUrl?: string;
+}
+export interface DnsVerificationRecord {
+    type: "CNAME" | "TXT" | "A";
+    name: string;
+    expectedValue: string;
+    ttl: number;
+}
+export interface DnsPropagationStatus {
+    hostname: string;
+    isConfigured: boolean;
+    expectedRecord: DnsVerificationRecord;
+    resolvedValue?: string;
+    checkedAt: number;
+}
+export declare class DomainConnectDnsEngine {
+    private config;
+    constructor(config?: Partial<DomainConnectServiceConfig>);
+    /**
+     * Generates a Domain Connect v2 Apply URL for 1-click DNS setup
+     */
+    generateApplyUrl(options: DomainConnectApplyUrlOptions): string;
+    /**
+     * Generates the required DNS verification records for manual setup
+     */
+    getRequiredDnsRecords(hostname: string, verificationToken: string): DnsVerificationRecord[];
+    /**
+     * Evaluates simulated or observed DNS records against expectations
+     */
+    evaluateDnsStatus(hostname: string, observedCname?: string): DnsPropagationStatus;
+}

package/dist/analytics/domain-connect-provisioner.d.ts

@@ -0,0 +1,74 @@
+/**
+ * DomainConnectProvisioner — Auto-configuration DNS pour la collecte first-party
+ * (gap Swetrix Domain Connect)
+ *
+ * Produit un plan Domain Connect reproductible côté serveur :
+ * - validation stricte du domaine et des hostnames (anti-open-redirect / anti-SSRF)
+ * - enregistrements CNAME (routage collecte) et TXT (preuve de propriété)
+ * - URL d'application Domain Connect construite via URLSearchParams (encodage unique)
+ * - vérification tolérante des enregistrements observés (jamais d'exception)
+ */
+export interface DnsRecord {
+    type: "CNAME" | "TXT";
+    name: string;
+    value: string;
+    ttlSeconds: number;
+    purpose: string;
+}
+export interface DomainConnectPlan {
+    domain: string;
+    serviceId: string;
+    providerId: string | null;
+    discoveryRecordName: string;
+    records: DnsRecord[];
+    applyUrl: string;
+    manualInstructions: string[];
+    warnings: string[];
+}
+export interface ObservedDnsRecord {
+    type: string;
+    name: string;
+    value: string;
+}
+export interface DnsVerificationResult {
+    verified: boolean;
+    missing: DnsRecord[];
+    mismatched: DnsRecord[];
+    unexpected: ObservedDnsRecord[];
+}
+export declare class DomainConnectProvisionerError extends Error {
+    constructor(message: string);
+}
+export declare class DomainConnectProvisioner {
+    static readonly SERVICE_ID = "lynxseo-analytics";
+    /**
+     * Valide un hostname DNS nu (sans protocole, chemin, port ni credentials).
+     * Les majuscules sont acceptées ; le point final est refusé.
+     */
+    static validateDomain(domain: string): boolean;
+    /**
+     * Construit le plan DNS + Domain Connect pour un domaine client.
+     */
+    static buildPlan(input: {
+        domain: string;
+        collectHostname: string;
+        targetHostname: string;
+        verificationToken: string;
+        providerId?: string | null;
+        applyEndpoint?: string;
+        ttlSeconds?: number;
+    }): DomainConnectPlan;
+    /**
+     * Compare les enregistrements attendus aux enregistrements observés.
+     * Ne lève jamais : toute entrée malformée est classée en `unexpected`.
+     */
+    static verifyRecords(expected: DnsRecord[], observed: ObservedDnsRecord[]): DnsVerificationResult;
+    private static normalizeHostname;
+    private static isPublicHostname;
+    private static resolveApplyEndpoint;
+    private static buildApplyUrl;
+    private static normalizeRecordName;
+    private static normalizeCnameValue;
+    /** Valeur TXT exacte (casse conservée), en tolérant les guillemets d'affichage DNS. */
+    private static normalizeTxtValue;
+}

package/dist/analytics/duplicate-title-meta-description-cluster-matrix.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - DuplicateTitleMetaDescriptionClusterMatrix
+ * Identifies exact and near-duplicate <title> tags and <meta name="description"> elements across site crawls,
+ * clustering affected URLs to resolve keyword cannibalization, SERP snippet dilution, and crawl budget waste.
+ */
+export interface PageMetadataEntry {
+    url: string;
+    title?: string;
+    metaDescription?: string;
+    isIndexable?: boolean;
+}
+export type DuplicateType = "exact" | "near_duplicate";
+export interface DuplicateCluster {
+    clusterId: string;
+    tagType: "title" | "meta_description";
+    duplicateType: DuplicateType;
+    representativeText: string;
+    urls: string[];
+    affectedPagesCount: number;
+    recommendation: string;
+}
+export interface DuplicateMetaMatrixReport {
+    totalPagesAudited: number;
+    missingTitlesCount: number;
+    missingMetaDescriptionsCount: number;
+    titleDuplicateClusters: DuplicateCluster[];
+    metaDescriptionDuplicateClusters: DuplicateCluster[];
+    totalDuplicateTitlePages: number;
+    totalDuplicateDescriptionPages: number;
+}
+export declare class DuplicateTitleMetaDescriptionClusterMatrix {
+    private static readonly NEAR_DUPLICATE_SIMILARITY_THRESHOLD;
+    /**
+     * Scans pages and builds duplicate clusters for titles and meta descriptions.
+     */
+    analyze(pages: PageMetadataEntry[]): DuplicateMetaMatrixReport;
+    private normalize;
+    private calculateJaccardSimilarity;
+}

package/dist/analytics/dynamic-render-cloaking-detector.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - DynamicRenderCloakingDetector
+ * Compares prerendered/SSR bot responses vs client-side browser responses to identify
+ * cloaking risks, text divergence, canonical mismatches, and rendering failures.
+ */
+export type CloakingRiskLevel = "safe" | "low" | "medium" | "high" | "critical";
+export interface VersionSnapshot {
+    html: string;
+    statusCode?: number;
+    headers?: Record<string, string>;
+}
+export interface CloakingDiscrepancy {
+    type: "status_code_mismatch" | "canonical_mismatch" | "robots_directive_mismatch" | "title_mismatch" | "critical_text_divergence" | "link_divergence" | "missing_bot_content" | "excessive_bot_content";
+    severity: "critical" | "warning" | "info";
+    description: string;
+    botValue?: string | number;
+    userValue?: string | number;
+}
+export interface CloakingAuditReport {
+    url: string;
+    riskLevel: CloakingRiskLevel;
+    similarityScore: number;
+    botWordCount: number;
+    userWordCount: number;
+    botLinkCount: number;
+    userLinkCount: number;
+    botCanonical?: string;
+    userCanonical?: string;
+    discrepancies: CloakingDiscrepancy[];
+    isLikelyCloaking: boolean;
+    recommendations: string[];
+}
+export declare class DynamicRenderCloakingDetector {
+    /**
+     * Compares the bot version (e.g., SSR or Prerender) against the standard user version.
+     */
+    audit(url: string, botVersion: VersionSnapshot, userVersion: VersionSnapshot): CloakingAuditReport;
+    private extractCanonical;
+    private extractTitle;
+    private extractMetaRobots;
+    private countOutlinks;
+    private tokenizeText;
+    private calculateJaccardSimilarity;
+}

package/dist/analytics/ecommerce-merchandise-funnel-auditor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Ecommerce Merchandise Funnel Auditor (Batch 14 - Gap 2)
+ *
+ * Enhanced Ecommerce conversion and merchandise performance auditor
+ * inspired by GA4 Ecommerce, Shopify Analytics & Mixpanel Commerce.
+ *
+ * Tracks funnel progression (view_item -> add_to_cart -> begin_checkout -> purchase),
+ * calculates Cart-to-Detail & Buy-to-Detail ratios, detects product abandonment friction,
+ * and quantifies cart recovery revenue upside.
+ */
+export interface EcommerceItemSnapshot {
+    itemId: string;
+    itemName: string;
+    itemCategory?: string;
+    price: number;
+    itemViews: number;
+    addedToCartCount: number;
+    purchasedCount: number;
+    totalRevenue: number;
+}
+export interface EcommerceFunnelStepMetrics {
+    step: "view_item_list" | "view_item" | "add_to_cart" | "view_cart" | "begin_checkout" | "add_shipping_info" | "add_payment_info" | "purchase";
+    userCount: number;
+    dropoffCount: number;
+    dropoffRatePct: number;
+    stepConversionRatePct: number;
+}
+export interface ProductMerchandiseFriction {
+    itemId: string;
+    itemName: string;
+    cartToDetailRatePct: number;
+    buyToDetailRatePct: number;
+    abandonedCartUnits: number;
+    potentialLostRevenue: number;
+    frictionType: "high_views_no_cart" | "high_cart_no_buy" | "healthy";
+    diagnosis: string;
+}
+export interface EcommerceFunnelAuditReport {
+    totalItemViews: number;
+    totalCartAdds: number;
+    totalPurchases: number;
+    totalGrossRevenue: number;
+    averageOrderValue: number;
+    cartToDetailRatePct: number;
+    buyToDetailRatePct: number;
+    cartAbandonmentRatePct: number;
+    checkoutCompletionRatePct: number;
+    abandonedCartRevenuePool: number;
+    recoverableRevenueOpportunity10Pct: number;
+    funnelSteps: EcommerceFunnelStepMetrics[];
+    frictionProducts: ProductMerchandiseFriction[];
+    strategicMerchandiseAdvice: string[];
+}
+export declare class EcommerceMerchandiseFunnelAuditor {
+    /**
+     * Audits e-commerce funnel events and product merchandise metrics.
+     */
+    static auditEcommerceFunnel(stepUserCounts: Partial<Record<EcommerceFunnelStepMetrics["step"], number>>, items?: EcommerceItemSnapshot[]): EcommerceFunnelAuditReport;
+}

package/dist/analytics/engagement-matrix-analyzer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * EngagementMatrixAnalyzer — Matomo VisitTime & Plausible Peak Engagement Parity
+ *
+ * Agrège les sessions, pages vues, conversions et rebonds selon une grille 7x24
+ * (Jour de semaine 0=Dimanche à 6=Samedi x Heure du jour 0 à 23).
+ *
+ * Permet de détecter les créneaux de forte audience, les heures à plus forte conversion
+ * et les fenêtres creuses idéales pour les opérations de maintenance.
+ */
+export interface RawEngagementEvent {
+    timestamp: number;
+    localHour?: number;
+    localDayOfWeek?: number;
+    isSessionStart?: boolean;
+    isConversion?: boolean;
+    revenue?: number;
+    isBounce?: boolean;
+}
+export interface EngagementMatrixCell {
+    dayOfWeek: number;
+    hour: number;
+    pageviews: number;
+    sessions: number;
+    conversions: number;
+    conversionRate: number;
+    revenue: number;
+    bounceRate: number;
+    intensityScore: number;
+}
+export interface WindowSlot {
+    dayOfWeek: number;
+    dayLabel: string;
+    hour: number;
+    timeLabel: string;
+    value: number;
+    formattedMetric: string;
+}
+export interface EngagementMatrixResult {
+    totalPageviews: number;
+    totalSessions: number;
+    totalConversions: number;
+    totalRevenue: number;
+    overallBounceRate: number;
+    grid: EngagementMatrixCell[][];
+    peakTrafficWindows: WindowSlot[];
+    peakConversionWindows: WindowSlot[];
+    coldMaintenanceWindows: WindowSlot[];
+}
+export declare class EngagementMatrixAnalyzer {
+    /**
+     * Analyse les événements d'engagement et génère la matrice 7x24.
+     *
+     * @param events Liste d'événements bruts
+     * @param useLocalTime Si vrai, utilise localHour/localDayOfWeek fournis dans l'événement, sinon l'heure UTC du timestamp.
+     */
+    static analyze(events: RawEngagementEvent[], useLocalTime?: boolean): EngagementMatrixResult;
+    /**
+     * Analyse directement une matrice 7x24 de visites (Matomo heatmapMatrix).
+     */
+    static analyzeFromMatrix(matrix: number[][]): {
+        peakTrafficWindows: Array<{
+            dayOfWeek: number;
+            hour: number;
+            visits: number;
+        }>;
+        coldMaintenanceWindows: Array<{
+            dayOfWeek: number;
+            hour: number;
+            visits: number;
+        }>;
+    };
+}