@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/analytics/site-health-analyzer.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Site Health Analyzer — LynxSEO Engine
+ *
+ * Fusionne la santé SEO technique, la disponibilité réseau (Uptime & TTFB),
+ * les Core Web Vitals réels (RUM) et la sécurité SSL en un score unifié de Santé du Site (0-100).
+ *
+ * Licence : AGPL-3.0-or-later
+ */
+export type HealthSeverity = "critical" | "warning" | "info" | "pass";
+export interface SiteHealthIssue {
+    id: string;
+    category: "seo" | "performance" | "uptime" | "security";
+    severity: HealthSeverity;
+    title: string;
+    description: string;
+    impactScore: number;
+    remediation: string;
+}
+export interface SiteHealthCategoryScore {
+    category: "seo" | "performance" | "uptime" | "security";
+    name: string;
+    score: number;
+    weight: number;
+    weightedScore: number;
+    status: "excellent" | "good" | "warning" | "critical";
+    checksPassed: number;
+    totalChecks: number;
+}
+export interface SiteHealthInput {
+    domain: string;
+    lcpP75Ms?: number;
+    inpP75Ms?: number;
+    clsP75?: number;
+    ttfbP75Ms?: number;
+    uptimePercent?: number;
+    http5xxErrorRatePercent?: number;
+    http4xxErrorRatePercent?: number;
+    avgLatencyMs?: number;
+    robotsTxtAccessible?: boolean;
+    sitemapAccessible?: boolean;
+    brokenLinksCount?: number;
+    unintendedNoindexCount?: number;
+    canonicalDiscrepanciesCount?: number;
+    httpsEnabled?: boolean;
+    sslDaysRemaining?: number;
+    hstsHeaderPresent?: boolean;
+    cspHeaderPresent?: boolean;
+    xContentTypeOptionsPresent?: boolean;
+}
+export interface SiteHealthReport {
+    domain: string;
+    overallScore: number;
+    status: "excellent" | "good" | "warning" | "critical";
+    timestamp: string;
+    categories: {
+        seo: SiteHealthCategoryScore;
+        performance: SiteHealthCategoryScore;
+        uptime: SiteHealthCategoryScore;
+        security: SiteHealthCategoryScore;
+    };
+    issues: SiteHealthIssue[];
+    passedChecksCount: number;
+    totalChecksCount: number;
+    summary: {
+        criticalCount: number;
+        warningCount: number;
+        passCount: number;
+    };
+    topRecommendations: string[];
+}
+export declare class SiteHealthAnalyzer {
+    /**
+     * Analyse et calcule le score global de santé d'un site web
+     */
+    static analyze(input: SiteHealthInput): SiteHealthReport;
+}

package/dist/analytics/site-registry-auditor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * LynxSEO Engine - Site Registry Auditor
+ *
+ * Clean-room centralised audit of a multi-site registry (SitesManager style):
+ * duplicate identifiers/domains, malformed domains (IP, localhost, underscore),
+ * missing collect hosts, missing read scopes and disabled sites, condensed into
+ * a deterministic health score and French remediation recommendations.
+ *
+ * AGPL-3.0-or-later
+ */
+export interface SiteRegistryEntry {
+    siteId: string;
+    name: string;
+    domain?: string | null;
+    enabled?: boolean;
+    collectHostnames?: string[];
+    apiScopes?: string[];
+}
+export interface SiteRegistryIssue {
+    code: "duplicate_domain" | "invalid_domain" | "missing_domain" | "missing_collect_domain" | "duplicate_collect_hostname" | "missing_api_scope" | "disabled_site" | "duplicate_site_id";
+    severity: "error" | "warning" | "info";
+    siteIds: string[];
+    message: string;
+}
+export interface SiteRegistryAudit {
+    totalSites: number;
+    enabledSites: number;
+    healthScore: number;
+    issues: SiteRegistryIssue[];
+    recommendations: string[];
+}
+export declare class SiteRegistryAuditor {
+    static readonly REQUIRED_READ_SCOPE = "pulse:read";
+    /**
+     * Canonicalises a domain or collect hostname:
+     * trims, lowercases, drops the protocol, credentials, port, path, query,
+     * fragment and trailing dot. `www.` is preserved on purpose.
+     * Returns null for empty input, IPs, localhost, underscores or invalid labels.
+     */
+    static normalizeDomain(input: string | null | undefined): string | null;
+    audit(entries: SiteRegistryEntry[]): SiteRegistryAudit;
+}

package/dist/analytics/sitemap-health-auditor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SitemapHealthAuditor — Audit de Santé, Couverture & Conformité des Sitemaps XML
+ *
+ * Parité : OnCrawl, Botify & Screaming Frog XML Sitemap Validator.
+ *
+ * Vérifie la stricte conformité aux exigences de Google Search Central :
+ * 1. Limites protocolaires : Max 50 000 URLs et 50 Mo par sitemap.
+ * 2. Statut HTTP des URLs déclarées :
+ *    - URLs en erreur (404, 410, 500).
+ *    - URLs en redirection (301, 302) — un sitemap ne doit lister que des URLs 200 finales.
+ * 3. Cohérence d'indexabilité :
+ *    - URLs déclarées dans le sitemap mais bloquées par 'noindex' ou 'robots.txt'.
+ *    - URLs non-canoniques (balise canonical pointant vers une autre URL).
+ * 4. Couverture & Lacunes :
+ *    - URLs orphelines (présentes dans le sitemap mais sans lien interne sur le site).
+ *    - URLs indexables manquantes (URLs 200 trouvées lors du crawl mais absentes du sitemap).
+ * 5. Fraîcheur des 'lastmod' : Format W3C Datetime valide (ISO 8601).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface SitemapEntry {
+    loc: string;
+    lastmod?: string;
+    changefreq?: string;
+    priority?: number;
+}
+export interface CrawledPageContext {
+    url: string;
+    statusCode: number;
+    isIndexable: boolean;
+    canonicalUrl?: string;
+    inboundInternalLinksCount: number;
+}
+export interface SitemapIssue {
+    url: string;
+    type: "non_200_status" | "redirect_url" | "noindex_conflict" | "canonical_mismatch" | "orphan_url" | "invalid_lastmod";
+    severity: "critical" | "warning" | "info";
+    detail: string;
+}
+export interface SitemapAuditReport {
+    sitemapUrl: string;
+    totalUrlsInSitemap: number;
+    validIndexableUrlsCount: number;
+    issuesCount: number;
+    issues: SitemapIssue[];
+    missingIndexableUrlsCount: number;
+    missingIndexableUrls: string[];
+    healthScore: number;
+    compliance: {
+        withinUrlLimit: boolean;
+        hasValidLastmodFormat: boolean;
+    };
+    summary: string;
+    generatedAt: string;
+}
+export declare class SitemapHealthAuditor {
+    private static readonly MAX_URLS_PER_SITEMAP;
+    audit(sitemapUrl: string, sitemapEntries: SitemapEntry[], crawledPages?: CrawledPageContext[]): SitemapAuditReport;
+    private normalizeUrl;
+    private emptyReport;
+}

package/dist/analytics/sites-manager-engine.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Sites Manager & Multi-Tenant Token Security Engine
+ *
+ * Clean-room implementation inspired by Matomo SitesManager & Rybbit multi-tenant project isolation.
+ * Manages measurable website registrations, CORS allowed domains, tracking tokens,
+ * timezone/currency defaults, and role-based site security boundaries.
+ */
+export interface MeasurableSite {
+    id: string;
+    organizationId: string;
+    name: string;
+    mainUrl: string;
+    allowedDomains: string[];
+    trackingToken: string;
+    timezone: string;
+    currency: string;
+    ecommerceEnabled: boolean;
+    replayEnabled: boolean;
+    createdAt: string;
+    status: "active" | "archived" | "suspended";
+}
+export interface SiteSecurityValidation {
+    authorized: boolean;
+    site?: MeasurableSite;
+    reason?: string;
+}
+export declare class SitesManagerEngine {
+    private sites;
+    createSite(site: Omit<MeasurableSite, "id" | "trackingToken" | "createdAt" | "status"> & {
+        id?: string;
+        trackingToken?: string;
+    }): MeasurableSite;
+    getSite(id: string): MeasurableSite | undefined;
+    listSitesByOrg(organizationId: string): MeasurableSite[];
+    validateIngestionRequest(siteId: string, token: string, requestOrigin?: string): SiteSecurityValidation;
+    updateSite(id: string, updates: Partial<Omit<MeasurableSite, "id" | "organizationId" | "createdAt">>): MeasurableSite | undefined;
+    archiveSite(id: string): boolean;
+    clear(): void;
+}

package/dist/analytics/soft-404-thin-content-scorer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Soft404ThinContentScorer
+ * Heuristic detector for Google Search Console "Soft 404" errors and thin content pages
+ * returning HTTP 200 OK with missing or dead content.
+ */
+export interface Soft404ContentInput {
+    url: string;
+    statusCode?: number;
+    html?: string;
+    bodyText?: string;
+    hasSchemaEntity?: boolean;
+}
+export type Soft404Classification = "clean_content" | "suspected_soft_404" | "confirmed_soft_404" | "thin_content";
+export interface Soft404DetectionReport {
+    url: string;
+    statusCode: number;
+    classification: Soft404Classification;
+    soft404Probability: number;
+    wordCount: number;
+    detectedErrorPhrases: string[];
+    reasons: string[];
+    recommendedHttpStatus: 200 | 301 | 404 | 410;
+    remedyAction: string;
+}
+export declare class Soft404ThinContentScorer {
+    private static readonly SOFT_404_PHRASES;
+    /**
+     * Evaluates a page for Soft 404 signals and thin content penalties.
+     */
+    evaluate(input: Soft404ContentInput): Soft404DetectionReport;
+    private extractTextFromHtml;
+}

package/dist/analytics/sourcemap-symbolizer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SourceMap v3 Parser & StackTrace Symbolizer
+ * Clean-room implementation for demangling and un-minifying client-side JavaScript stack traces.
+ */
+export interface SourceMapV3 {
+    version: 3;
+    file?: string;
+    sourceRoot?: string;
+    sources: string[];
+    sourcesContent?: (string | null)[];
+    names?: string[];
+    mappings: string;
+}
+export interface SymbolizedFrame {
+    originalFunctionName?: string;
+    originalFile?: string;
+    originalLine?: number;
+    originalColumn?: number;
+    sourceContext?: string[];
+    rawLine: string;
+    isSymbolized: boolean;
+}
+export interface SymbolizedStackTraceResult {
+    symbolizedFrames: SymbolizedFrame[];
+    unmappedCount: number;
+    mappedCount: number;
+}
+export interface DecodedMapping {
+    generatedLine: number;
+    generatedColumn: number;
+    originalFileIndex?: number;
+    originalLine?: number;
+    originalColumn?: number;
+    nameIndex?: number;
+}
+/**
+ * Decodes the mappings string of a SourceMap v3.
+ */
+export declare function decodeSourceMapMappings(mappings: string): DecodedMapping[];
+/**
+ * Finds the closest mapped location for a generated line and column.
+ */
+export declare function findMapping(mappings: DecodedMapping[], line: number, column: number): DecodedMapping | null;
+/**
+ * Symbolizes a stack trace given a parsed SourceMap v3.
+ */
+export declare function symbolizeStackTrace(stackTrace: string, sourceMap: SourceMapV3): SymbolizedStackTraceResult;

package/dist/analytics/speculation-rules-prerender-candidate-auditor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SpeculationRulesPrerenderCandidateAuditor
+ * Analyzes navigation targets and generates safe, optimized Chrome Speculation Rules API manifests,
+ * distinguishing full prerendering (instant page loads) from prefetching and filtering dangerous endpoints.
+ */
+export type SpeculationAction = "prerender" | "prefetch" | "disallowed";
+export interface NavigationTargetInput {
+    url: string;
+    anchorText?: string;
+    isSameOrigin: boolean;
+    isIdempotentGet: boolean;
+    isUserActionSensitive: boolean;
+    expectedNavigationProbability: number;
+    requiresAuthentication?: boolean;
+}
+export interface CandidateEvaluation {
+    url: string;
+    recommendedAction: SpeculationAction;
+    eagerness: "immediate" | "eager" | "moderate" | "conservative";
+    rationale: string;
+}
+export interface SpeculationRulesAuditReport {
+    totalPagesAudited: number;
+    prerenderCandidatesCount: number;
+    prefetchCandidatesCount: number;
+    disallowedCount: number;
+    evaluations: CandidateEvaluation[];
+    generatedSpeculationRulesJson: string;
+    generatedHtmlScriptTag: string;
+}
+export declare class SpeculationRulesPrerenderCandidateAuditor {
+    private static readonly DISALLOWED_PATTERNS;
+    /**
+     * Evaluates navigation candidates and synthesizes Speculation Rules JSON script.
+     */
+    evaluate(candidates: NavigationTargetInput[]): SpeculationRulesAuditReport;
+}

package/dist/analytics/squarified-treemap-engine.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Squarified Treemap Engine
+ * Clean-room implementation inspired by Matomo TreemapVisualization & PostHog hierarchical category visualizer.
+ * Implements the Squarified Treemap algorithm (Bruls, Huizing, van Wijk) to generate nested
+ * rectangular layouts with optimal aspect ratios for traffic and page hierarchies.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface TreemapNodeInput {
+    id: string;
+    label: string;
+    value: number;
+    children?: TreemapNodeInput[];
+    category?: string;
+}
+export interface TreemapRect {
+    id: string;
+    label: string;
+    value: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    depth: number;
+    category?: string;
+}
+export declare class SquarifiedTreemapEngine {
+    /**
+     * Computes layout bounds for the entire tree
+     */
+    static computeLayout(root: TreemapNodeInput, bounds: {
+        width: number;
+        height: number;
+    }, startX?: number, startY?: number, depth?: number): TreemapRect[];
+    private static squarify;
+    private static worstAspectRatio;
+}

package/dist/analytics/ssr-streaming-ttfb-flush-auditor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SsrStreamingTtfbFlushAuditor
+ * Analyzes SSR edge streaming chunks, Time to First Byte (TTFB) early flushing,
+ * critical head asset preloading in chunk 0, and HTTP 103 Early Hints efficiency.
+ */
+export interface StreamChunkInput {
+    chunkIndex: number;
+    timestampMs: number;
+    byteLength: number;
+    contentSnippet: string;
+}
+export interface SsrStreamingAuditInput {
+    url: string;
+    chunks: StreamChunkInput[];
+    hasEarlyHints103?: boolean;
+    totalDurationMs?: number;
+}
+export type StreamingPerformanceClassification = "optimal_edge_stream" | "buffered_blocking_ssr" | "delayed_first_chunk" | "empty_first_chunk";
+export interface StreamingFinding {
+    issue: "blocking_buffered_first_byte" | "delayed_chunk_zero" | "missing_critical_head_in_chunk_zero" | "missing_early_hints" | "chunk_interval_pause_stall";
+    severity: "critical" | "warning" | "info";
+    description: string;
+    recommendation: string;
+}
+export interface SsrStreamingAuditReport {
+    url: string;
+    classification: StreamingPerformanceClassification;
+    ttfbMs: number;
+    totalDurationMs: number;
+    score: number;
+    isOptimal: boolean;
+    chunkCount: number;
+    hasCriticalHeadInChunkZero: boolean;
+    findings: StreamingFinding[];
+    recommendedEdgeStreamSnippet: string;
+}
+export declare class SsrStreamingTtfbFlushAuditor {
+    private static readonly OPTIMAL_TTFB_THRESHOLD_MS;
+    private static readonly CRITICAL_TTFB_THRESHOLD_MS;
+    /**
+     * Audits SSR streaming chunk timings and content distribution.
+     */
+    audit(input: SsrStreamingAuditInput): SsrStreamingAuditReport;
+}

package/dist/analytics/standalone-replay-exporter.d.ts

@@ -0,0 +1,45 @@
+/**
+ * StandaloneReplayExporter — Générateur de Session Replay HTML Autonome et Autoporteur
+ *
+ * Parité : PostHog (Session Replay > Export as HTML / Standalone archive).
+ *
+ * Exporte une session d'enregistrement sous forme d'un unique fichier .html 100% autonome
+ * (zéro dépendance externe, CSS/JS embarqués) pour le partage sécurisé de replays dans :
+ * - Tickets Jira, GitHub Issues, Linear.
+ * - Rapports d'incidents techniques & tickets de support client.
+ * - Archivage légal ou conformité RGPD sans compte utilisateur LynxSEO.
+ *
+ * Intègre un lecteur multimédia léger :
+ * - Scrubber temporel, bouton Play/Pause, accélérateurs (1x, 2x, 4x, 8x).
+ * - Saut automatique des périodes d'inactivité.
+ * - Vue fenêtrée avec curseur de souris synchronisé et visualisateur de clics.
+ * - Onglet "Console Logs" (info, warn, error) et "Réseau" (status, url, latence).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface ReplayEventSnapshot {
+    timestamp: number;
+    type: "dom_snapshot" | "mouse_move" | "click" | "scroll" | "input" | "network" | "console";
+    data: Record<string, unknown>;
+}
+export interface ReplaySessionExportData {
+    sessionId: string;
+    userId?: string;
+    startedAt: string;
+    durationMs: number;
+    initialUrl: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    userAgent?: string;
+    events: ReplayEventSnapshot[];
+}
+export declare class StandaloneReplayExporter {
+    /**
+     * Génère le document HTML autonome complet contenant le lecteur et les données de session.
+     */
+    exportToHtml(session: ReplaySessionExportData): string;
+    private safeJsonSerialize;
+    private escapeHtml;
+}

package/dist/analytics/state-mutation-recorder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * StateMutationRecorder Engine
+ *
+ * Implements client-side application state change recording (Redux, Zustand, Pinia, Vuex),
+ * sensitive PII scrubbing (passwords, auth tokens, credit cards, SSN),
+ * deep structural delta calculation, and time-travel state reconstruction.
+ * Parity with OpenReplay Redux/Zustand Tracker & PostHog Session State Timeline.
+ *
+ * Clean-room implementation under AGPL-3.0-or-later.
+ */
+export interface StateActionRecord {
+    actionId: string;
+    type: string;
+    payload?: unknown;
+    timestamp: number;
+}
+export interface StateSnapshotRecord {
+    timestamp: number;
+    state: Record<string, unknown>;
+    action?: StateActionRecord;
+}
+export interface StateMutationDelta {
+    path: string;
+    oldValue: unknown;
+    newValue: unknown;
+    type: 'added' | 'modified' | 'deleted';
+}
+export declare class StateMutationRecorder {
+    private static readonly SENSITIVE_KEY_PATTERNS;
+    /**
+     * Recursively scrubs sensitive keys and values from state objects or action payloads.
+     */
+    static scrubSensitiveData<T>(obj: T): T;
+    /**
+     * Computes structural differences between two state snapshots.
+     */
+    static computeDiff(prevState: Record<string, unknown>, nextState: Record<string, unknown>, prefix?: string): StateMutationDelta[];
+    /**
+     * Reconstructs the application state at any millisecond timestamp using base snapshot and mutations.
+     */
+    static reconstructStateAt(timeline: StateSnapshotRecord[], targetTimestamp: number): Record<string, unknown>;
+}

package/dist/analytics/statistical-anomaly-detector.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Statistical Anomaly Detection & Adaptive Alerting Engine
+ *
+ * Moteur d'analyse statistique et de détection d'anomalies en temps réel
+ * inspiré de Matomo CustomAlerts / Insights et Swetrix Anomaly Detection.
+ *
+ * Remplace les seuils statiques par une détection adaptative basée sur :
+ * 1. Moyenne mobile glissante (Moving Average) et écart-type (Standard Deviation).
+ * 2. Z-Score (nombre d'écarts-types par rapport à la moyenne historique).
+ * 3. Déviation en pourcentage par rapport au référentiel.
+ * 4. Classification de sévérité (info, warning, critical) et direction (spike vs dip).
+ * 5. Diagnostic automatique et recommandations opérationnelles.
+ */
+export interface MetricDataPoint {
+    timestamp: number;
+    value: number;
+}
+export type AnomalyMetricType = "pageviews" | "visitors" | "bounce_rate" | "conversion_rate" | "error_rate" | "avg_duration_sec" | "turnstile_blocks" | "custom";
+export type AnomalySeverity = "info" | "warning" | "critical";
+export type AnomalyDirection = "spike" | "dip";
+export interface AnomalyDetectionRule {
+    id: string;
+    siteId: string;
+    metric: AnomalyMetricType;
+    customMetricName?: string;
+    baselineWindowSize?: number;
+    zScoreThreshold?: number;
+    minAbsoluteChange?: number;
+    minPercentChange?: number;
+    direction?: "both" | "spike_only" | "dip_only";
+    enabled: boolean;
+}
+export interface DetectedMetricAnomaly {
+    ruleId: string;
+    siteId: string;
+    metric: AnomalyMetricType;
+    timestamp: number;
+    currentValue: number;
+    baselineMean: number;
+    baselineStdDev: number;
+    zScore: number;
+    percentChange: number;
+    direction: AnomalyDirection;
+    severity: AnomalySeverity;
+    message: string;
+    diagnosticRecommendation: string;
+}
+export declare class StatisticalAnomalyDetector {
+    /**
+     * Calcule la moyenne arithmétique d'une série numérique.
+     */
+    static mean(values: number[]): number;
+    /**
+     * Calcule l'écart-type d'une série numérique.
+     */
+    static stdDev(values: number[], avg?: number): number;
+    /**
+     * Évalue une série chronologique pour détecter si le dernier point constitue une anomalie.
+     */
+    static evaluateMetric(history: MetricDataPoint[], rule: AnomalyDetectionRule): DetectedMetricAnomaly | null;
+    /**
+     * Analyse l'ensemble des règles sur plusieurs séries de métriques.
+     */
+    static evaluateAll(metricsData: Map<AnomalyMetricType, MetricDataPoint[]>, rules: AnomalyDetectionRule[]): DetectedMetricAnomaly[];
+    private static formatDiagnostic;
+}

package/dist/analytics/stickiness-engine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * StickinessEngine — Analyse de l'adhérence produit (Product Stickiness)
+ *
+ * Calcule :
+ * 1. La distribution de fréquence d'activité des utilisateurs sur une période donnée (ex: 7 ou 30 jours).
+ * 2. Le nombre d'utilisateurs actifs 1 jour, 2 jours, ..., N jours.
+ * 3. Les ratios DAU/MAU, WAU/MAU et DAU/WAU évaluant l'habitude et la rétention produit.
+ *
+ * Implémentation Clean-Room indépendante sous licence AGPL-3.0.
+ */
+export interface StickinessActivityRecord {
+    distinctId: string;
+    timestamp: string | Date;
+    event?: string;
+    properties?: Record<string, unknown>;
+}
+export interface StickinessCalculationOptions {
+    windowDays?: 7 | 14 | 30;
+    targetEvent?: string;
+    warningDauMauThresholdPct?: number;
+}
+export interface StickinessBucket {
+    daysActive: number;
+    userCount: number;
+    percentage: number;
+    cumulativeCount: number;
+    cumulativePercentage: number;
+}
+export interface StickinessReport {
+    windowDays: number;
+    totalUniqueUsers: number;
+    buckets: StickinessBucket[];
+    dauAverage: number;
+    wauAverage: number;
+    mau: number;
+    dauMauRatioPct: number;
+    wauMauRatioPct: number;
+    healthGrade: "excellent" | "healthy" | "warning" | "critical";
+    healthMessage: string;
+    generatedAt: string;
+}
+export declare class StickinessEngine {
+    /**
+     * Calcule le rapport d'adhérence produit à partir d'une liste d'activités.
+     */
+    calculate(records: StickinessActivityRecord[], options?: StickinessCalculationOptions): StickinessReport;
+}

package/dist/analytics/sticky-user-id.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sticky User ID Resolver & Identity Alias Manager
+ * Clean-room implementation inspired by Rybbit stickyUserId & Matomo UserID.
+ * Provides ephemeral or windowed sticky visitor identity resolution using rotating HMAC salts
+ * and user alias linking without persistent cross-site tracking cookies.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export type RotationWindow = 'daily' | 'weekly' | 'monthly' | 'never';
+export interface StickyUserIdOptions {
+    siteId: string;
+    ipSubnet: string;
+    userAgentNormalized: string;
+    rotationWindow?: RotationWindow;
+    customUserId?: string;
+    baseSecret?: string;
+}
+export interface StickyIdentity {
+    visitorId: string;
+    isCustomUser: boolean;
+    windowEpoch: string;
+    aliasKey?: string;
+}
+export declare class StickyUserIdResolver {
+    /**
+     * Resolves a privacy-safe sticky visitor ID
+     */
+    static resolve(options: StickyUserIdOptions): StickyIdentity;
+    private static getEpoch;
+    private static hash;
+}