@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/analytics/serp-rank-distribution-decay-matrix.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SERP Rank Distribution & Decay Matrix (Batch 16 - Gap 2)
+ *
+ * SERP rank tracking, positional distribution & keyword decay matrix inspired by
+ * Ahrefs Rank Tracker, Semrush Position Tracking & STAT Search Analytics.
+ *
+ * Tracks keyword velocity, models positional buckets (Top 1-3, Page 1, Page 2, Page 3-5),
+ * calculates estimated organic search traffic via CTR curve weighting,
+ * and surfaces striking distance opportunities and decaying search queries.
+ */
+export interface DecayMatrixRankSnapshot {
+    date: string;
+    rank: number | null;
+}
+export interface TrackedKeywordRecord {
+    keyword: string;
+    searchVolume: number;
+    url: string;
+    history: DecayMatrixRankSnapshot[];
+}
+export type KeywordVelocityStatus = "surging" | "striking_distance" | "stable" | "decaying" | "serp_displaced";
+export interface KeywordMomentumDetails {
+    keyword: string;
+    searchVolume: number;
+    url: string;
+    currentRank: number | null;
+    previousRank: number | null;
+    rankChange: number;
+    status: KeywordVelocityStatus;
+    estimatedCurrentMonthlyClicks: number;
+    monthlyTrafficDelta: number;
+}
+export interface PositionalBucketDistribution {
+    top1To3: number;
+    top4To10: number;
+    page2: number;
+    page3To5: number;
+    page6Plus: number;
+    unranked: number;
+}
+export interface SerpRankMatrixReport {
+    totalKeywordsTracked: number;
+    currentDistribution: PositionalBucketDistribution;
+    previousDistribution: PositionalBucketDistribution;
+    totalEstimatedMonthlyTraffic: number;
+    netMonthlyTrafficChange: number;
+    strikingDistanceOpportunities: KeywordMomentumDetails[];
+    decayingKeywords: KeywordMomentumDetails[];
+    surgingKeywords: KeywordMomentumDetails[];
+    serpDisplacedKeywords: KeywordMomentumDetails[];
+    strategicOptimizationAdvice: string[];
+}
+export declare class SerpRankDistributionDecayMatrix {
+    /**
+     * Industry benchmark organic click-through rate curve by SERP position.
+     */
+    static getEstimatedCtr(rank: number | null): number;
+    /**
+     * Analyzes historical keyword rank records and computes distribution shifts and momentum.
+     */
+    static analyzeRankMatrix(keywords: TrackedKeywordRecord[]): SerpRankMatrixReport;
+    private static incrementBucket;
+}

package/dist/analytics/serp-snippet-faq-accordion-eligibility-scorer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SerpSnippetFaqAccordionEligibilityScorer
+ * Evaluates FAQPage structured data and on-page content against Google's Search Central
+ * FAQ rich result policies and algorithmic SERP eligibility restrictions.
+ */
+export interface SerpFaqItem {
+    question: string;
+    answer: string;
+}
+export interface FaqEligibilityInput {
+    domain: string;
+    faqs: SerpFaqItem[];
+    pageHtml?: string;
+    isGovernmentOrHealthAuthority?: boolean;
+}
+export type FaqViolationType = "insufficient_questions" | "hidden_or_cloaked_faq" | "promotional_advertising_spam" | "repetitive_or_duplicate_question" | "answer_too_long" | "answer_too_short" | "commercial_site_serp_suppression";
+export interface FaqEligibilityFinding {
+    type: FaqViolationType;
+    severity: "critical" | "warning" | "info";
+    question?: string;
+    description: string;
+    recommendation: string;
+}
+export interface FaqEligibilityReport {
+    domain: string;
+    totalQuestions: number;
+    eligibilityStatus: "eligible" | "likely_suppressed" | "policy_violation";
+    score: number;
+    findings: FaqEligibilityFinding[];
+    sanitizedJsonLd: object;
+    recommendations: string[];
+}
+export declare class SerpSnippetFaqAccordionEligibilityScorer {
+    private static readonly PROMO_PATTERNS;
+    /**
+     * Evaluates FAQ items and on-page presence for Google SERP rich result eligibility.
+     */
+    evaluate(input: FaqEligibilityInput): FaqEligibilityReport;
+}

package/dist/analytics/serp-snippet-opportunity-hunter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SerpSnippetOpportunityHunter — Chasseur d'Opportunités Position 0 (Featured Snippets & Rich Results)
+ *
+ * Parité : Ahrefs & Semrush (Featured Snippet Opportunities & SERP Features Hunter).
+ *
+ * Analyse le contenu éditorial et le code HTML d'une page pour maximiser ses chances
+ * de capturer la Position 0 de Google (Featured Snippet) et les résultats enrichis :
+ *
+ * 1. Snippet Paragraphe (Définition) :
+ *    - Détecte les en-têtes d'intention définitionnelle ("Qu'est-ce que...", "What is...", "Définition...").
+ *    - Évalue la longueur du paragraphe de réponse immédiate (fourchette d'or : 40 à 60 mots / 250 à 350 caractères).
+ * 2. Snippet Liste Ordonnée / Étapes (How-To / Processus) :
+ *    - Détecte l'intention procédurale ("Comment...", "How to...", "Étapes pour...").
+ *    - Vérifie la présence d'une liste structurée (<ol> ou <ul> de 4 à 8 éléments concis).
+ * 3. Snippet Tableau Comparatif :
+ *    - Détecte l'intention comparative ("vs", "comparatif", "tarifs", "différences").
+ *    - Vérifie la présence d'une table HTML propre avec en-têtes <th>.
+ * 4. Résultats Enrichis FAQ (Schema FAQPage) :
+ *    - Détecte les questions/réponses récurrentes et vérifie l'intégration du balisage JSON-LD FAQPage.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface SnippetSectionInput {
+    headingText: string;
+    headingTag: "h1" | "h2" | "h3" | "h4";
+    immediateText: string;
+    hasOrderedList?: boolean;
+    listItemsCount?: number;
+    hasTable?: boolean;
+    hasFaqSchema?: boolean;
+}
+export type SnippetType = "paragraph_definition" | "numbered_list_steps" | "comparison_table" | "faq_rich_result";
+export interface SnippetOpportunity {
+    type: SnippetType;
+    headingText: string;
+    readinessScore: number;
+    status: "ready_to_win" | "needs_optimization" | "missing_structure";
+    currentWordCount: number;
+    recommendedAction: string;
+    suggestedMarkupSnippet?: string;
+}
+export interface SerpSnippetAuditReport {
+    targetKeyword: string;
+    totalSectionsAudited: number;
+    overallSnippetReadinessScore: number;
+    opportunities: SnippetOpportunity[];
+    topPriorityOpportunity?: SnippetOpportunity;
+    checklist: string[];
+    generatedAt: string;
+}
+export declare class SerpSnippetOpportunityHunter {
+    hunt(targetKeyword: string, sections: SnippetSectionInput[]): SerpSnippetAuditReport;
+    private countWords;
+    private isDefinitionHeading;
+    private isProceduralHeading;
+    private isComparativeHeading;
+    private emptyReport;
+}

package/dist/analytics/serp-snippet-pixel-truncation-estimator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SerpSnippetPixelTruncationEstimator
+ * Proportional font pixel width calculator and SERP snippet preview simulator.
+ * Calibrated to Google SERP typography (Arial 20px titles, 14px snippets).
+ */
+export interface SnippetDimensionMetrics {
+    text: string;
+    pixelWidth: number;
+    maxLimitPx: number;
+    isTruncated: boolean;
+    truncatedText?: string;
+    charactersCount: number;
+}
+export interface SerpPreviewResult {
+    title: {
+        desktop: SnippetDimensionMetrics;
+        mobile: SnippetDimensionMetrics;
+    };
+    description: {
+        desktop: SnippetDimensionMetrics;
+        mobile: SnippetDimensionMetrics;
+    };
+    overallStatus: "optimal" | "title_truncated" | "description_truncated" | "severely_truncated" | "mobile_only_truncated";
+    recommendations: string[];
+}
+export declare class SerpSnippetPixelTruncationEstimator {
+    private static readonly TITLE_CHAR_WIDTHS;
+    private static readonly DESKTOP_TITLE_LIMIT_PX;
+    private static readonly MOBILE_TITLE_LIMIT_PX;
+    private static readonly DESKTOP_DESC_LIMIT_PX;
+    private static readonly MOBILE_DESC_LIMIT_PX;
+    /**
+     * Evaluates SERP Title and Meta Description pixel widths across Desktop and Mobile.
+     */
+    evaluate(title: string, description: string): SerpPreviewResult;
+    private measureTitle;
+    private measureDescription;
+}

package/dist/analytics/serp-volatility-sensor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SerpVolatilitySensor — Capteur Météo de Volatilité SERP & Détection de Mises à Jour Google
+ *
+ * Parité : Semrush Sensor, MozCast, Advanced Web Ranking Google Weather.
+ *
+ * Mesure les turbulences quotidiennes de positionnement sur un corpus de mots-clés suivis :
+ * 1. Calcul du Delta de Position Absolu Moyen (MAPC - Mean Absolute Position Change).
+ * 2. Taux de Renouvellement (Churn Rate) sur le Top 3 et le Top 10.
+ * 3. Indice de Température SERP normalisé de 0.0 (Calme plat) à 10.0 (Tempête / Core Update majeure).
+ * 4. Décomposition sectorielle (e-commerce, tech, finance, santé, global).
+ * 5. Détecteur d'Anomalie Algorithmique par Z-Score statistique :
+ *    Alerte lorsque la volatilité du jour s'écarte de plus de 2 écarts-types (> 2.0 sigma)
+ *    par rapport à l'historique glissant de 30 jours (signe d'un déploiement d'algorithme Google non annoncé).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface KeywordRankingObservation {
+    keywordId: string;
+    keyword: string;
+    category?: string;
+    previousPosition: number | null;
+    currentPosition: number | null;
+}
+export interface CategoryVolatility {
+    category: string;
+    keywordCount: number;
+    averageDelta: number;
+    volatilityScore: number;
+    level: "calm" | "normal" | "elevated" | "extreme";
+}
+export interface SerpHistoricalBaseline {
+    rolling30DaysMeanVolatility: number;
+    rolling30DaysStdDev: number;
+}
+export interface SerpVolatilityReport {
+    date: string;
+    totalKeywordsObserved: number;
+    globalScore: number;
+    temperatureFahrenheit: number;
+    volatilityLevel: "calm" | "normal" | "elevated" | "extreme";
+    top3ChurnRate: number;
+    top10ChurnRate: number;
+    averagePositionDelta: number;
+    categories: CategoryVolatility[];
+    isAlgorithmUpdateSuspected: boolean;
+    zScore: number | null;
+    insights: string[];
+    generatedAt: string;
+}
+export declare class SerpVolatilitySensor {
+    /**
+     * Analyse la volatilité du jour à partir des observations de mots-clés et d'une baseline optionnelle.
+     */
+    measure(observations: KeywordRankingObservation[], baseline?: SerpHistoricalBaseline, dateString?: string): SerpVolatilityReport;
+    private emptyReport;
+}

package/dist/analytics/server-timing-header-metrics-decomposer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - ServerTimingHeaderMetricsDecomposer
+ * Parses and decomposes W3C Server-Timing HTTP response headers, correlating server-side
+ * database, edge cache, and SSR render durations with client-side TTFB latency.
+ */
+export interface ServerTimingMetricEntry {
+    name: string;
+    durationMs: number | null;
+    description: string | null;
+}
+export interface ServerTimingDecompositionReport {
+    rawHeader: string;
+    totalServerDurationMs: number;
+    metrics: ServerTimingMetricEntry[];
+    dominantMetric: ServerTimingMetricEntry | null;
+    unaccountedLatencyMs: number | null;
+    bottleneckDiagnosis: string;
+}
+export declare class ServerTimingHeaderMetricsDecomposer {
+    /**
+     * Parses the Server-Timing header and diagnoses backend performance bottlenecks.
+     */
+    decompose(serverTimingHeader: string, clientTtfbMs?: number): ServerTimingDecompositionReport;
+    private splitMetrics;
+}

package/dist/analytics/session-issue-classifier.d.ts

@@ -0,0 +1,82 @@
+/**
+ * SessionIssueClassifier — Détecteur et classificateur d'incidents de session utilisateur (Parité OpenReplay / Sentry).
+ *
+ * Analyse la chronologie d'une session (clics, mouvements, requêtes réseau, erreurs JS) :
+ * - Catégorise les incidents selon la taxonomie OpenReplay :
+ *   - js_exception (erreur JS interceptée)
+ *   - bad_request (HTTP 4xx/5xx sur appel API)
+ *   - missing_resource (404 sur ressource statique css/js/img)
+ *   - click_rage (clics répétés frénétiques)
+ *   - tap_rage (taps mobiles répétés)
+ *   - mouse_thrashing (secousses de souris erratiques)
+ *   - dead_click (clic sans mutation ni navigation)
+ *   - crash (erreur fatale ou gel de session)
+ * - Calcule l'indice de santé de la session (0 - 100)
+ * - Agrège les sélecteurs et URLs d'API les plus problématiques
+ */
+export type SessionIssueType = 'js_exception' | 'bad_request' | 'missing_resource' | 'click_rage' | 'tap_rage' | 'mouse_thrashing' | 'dead_click' | 'crash';
+export type SessionIssueSeverity = 'low' | 'medium' | 'high' | 'critical';
+export interface RawSessionTimeline {
+    sessionId: string;
+    durationMs: number;
+    clicks?: Array<{
+        selector: string;
+        timestamp: number;
+        x?: number;
+        y?: number;
+        causedDomMutation?: boolean;
+        causedNetworkRequest?: boolean;
+    }>;
+    mouseMoves?: Array<{
+        timestamp: number;
+        x: number;
+        y: number;
+    }>;
+    networkRequests?: Array<{
+        url: string;
+        method: string;
+        status: number;
+        durationMs: number;
+        timestamp: number;
+        isResource?: boolean;
+    }>;
+    errors?: Array<{
+        message: string;
+        stack?: string;
+        timestamp: number;
+        isFatal?: boolean;
+    }>;
+}
+export interface ClassifiedSessionIssue {
+    id: string;
+    type: SessionIssueType;
+    severity: SessionIssueSeverity;
+    timestamp: number;
+    selector?: string;
+    url?: string;
+    message?: string;
+    details?: Record<string, unknown>;
+}
+export interface SessionHealthReport {
+    sessionId: string;
+    healthIndex: number;
+    status: 'healthy' | 'minor_issues' | 'degraded' | 'broken';
+    totalIssuesCount: number;
+    issues: ClassifiedSessionIssue[];
+    issuesByType: Record<SessionIssueType, number>;
+    topOffendingSelectors: Array<{
+        selector: string;
+        count: number;
+    }>;
+    topOffendingEndpoints: Array<{
+        url: string;
+        count: number;
+        status: number;
+    }>;
+}
+export declare class SessionIssueClassifier {
+    /**
+     * Analyse une session complète et extrait les incidents classifiés et le score de santé.
+     */
+    static classify(timeline: RawSessionTimeline): SessionHealthReport;
+}

package/dist/analytics/session-playlist-orchestrator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Session Replay Playlist & Queue Orchestrator
+ * Clean-room implementation for dynamic session filtering, triage queues,
+ * and smart continuous review playlists.
+ * Parity: PostHog Session Recording Playlists & OpenReplay Triage Queues.
+ */
+export interface SessionPlaylistItem {
+    sessionId: string;
+    userId?: string;
+    durationSeconds: number;
+    activeSeconds: number;
+    activityRatio: number;
+    eventsCount: number;
+    errorsCount: number;
+    hasRageClick: boolean;
+    hasDeadClick: boolean;
+    timestamp: string;
+    isWatched?: boolean;
+    tags?: string[];
+}
+export interface PlaylistFilterCriteria {
+    minDurationSeconds?: number;
+    maxDurationSeconds?: number;
+    minActivityRatio?: number;
+    hasErrors?: boolean;
+    hasRageClick?: boolean;
+    unwatchedOnly?: boolean;
+    tags?: string[];
+    sortBy?: "errors_desc" | "duration_desc" | "recency_desc" | "activity_asc";
+    limit?: number;
+}
+export interface PlaylistSummary {
+    totalInQueue: number;
+    watchedCount: number;
+    unwatchedCount: number;
+    avgDurationSeconds: number;
+    frictionCount: number;
+    queue: SessionPlaylistItem[];
+    nextSessionToWatch: SessionPlaylistItem | null;
+}
+export declare class SessionPlaylistOrchestrator {
+    /**
+     * Filters and orders sessions into a smart playlist triage queue.
+     */
+    static buildPlaylist(sessions: SessionPlaylistItem[], criteria?: PlaylistFilterCriteria): PlaylistSummary;
+}

package/dist/analytics/session-replay-live-assist.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SessionReplayLiveAssist — Signalisation et Co-Browsing en temps réel (OpenReplay Live Assist Parity)
+ *
+ * Gère la coordination et l'échange de messages en temps réel entre un visiteur actif
+ * et un agent de support / analyste lors d'une session de Live Assist :
+ * - Gestion des salles de session (`LiveRoom`)
+ * - Diffusion des coordonnées de curseur relatives (x %, y %) et du scroll
+ * - Émission de points d'attention visuels (« click ping » / halo d'assistance)
+ * - Négociation des droits de co-browsing (demande, approbation, révocation de contrôle)
+ * - Journalisation des notes d'assistance horodatées pour audit.
+ */
+export type ParticipantRole = "visitor" | "agent" | "observer";
+export type AssistMessageType = "join" | "leave" | "cursor_move" | "click_ping" | "scroll_sync" | "request_control" | "grant_control" | "revoke_control" | "session_note";
+export interface AssistMessage {
+    id: string;
+    sessionId: string;
+    senderId: string;
+    senderRole: ParticipantRole;
+    type: AssistMessageType;
+    timestamp: number;
+    payload?: {
+        x?: number;
+        y?: number;
+        scrollTop?: number;
+        scrollLeft?: number;
+        text?: string;
+        targetSelector?: string;
+        accepted?: boolean;
+    };
+}
+export interface LiveParticipant {
+    id: string;
+    role: ParticipantRole;
+    name?: string;
+    joinedAt: number;
+    lastActiveAt: number;
+}
+export interface LiveRoomState {
+    sessionId: string;
+    projectId: string;
+    createdAt: number;
+    hasActiveVisitor: boolean;
+    controlHolderId: string | null;
+    participants: Record<string, LiveParticipant>;
+    recentNotes: Array<{
+        id: string;
+        agentId: string;
+        text: string;
+        timestamp: number;
+    }>;
+}
+export declare class SessionReplayLiveAssist {
+    private rooms;
+    /**
+     * Obtient ou initialise une salle d'assistance en direct
+     */
+    getOrCreateRoom(projectId: string, sessionId: string, now?: number): LiveRoomState;
+    /**
+     * Traite l'arrivée d'un message de signalisation et met à jour l'état de la salle
+     */
+    processMessage(projectId: string, message: AssistMessage, now?: number): {
+        broadcast: boolean;
+        state: LiveRoomState;
+        error?: string;
+    };
+    /**
+     * Supprime les salles inactives
+     */
+    cleanupIdleRooms(maxIdleMs?: number, now?: number): number;
+}

package/dist/analytics/session-replay-privacy-masker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Session Replay Privacy Masker (Batch 18 - Gap 3)
+ *
+ * Client & Edge Session Recording DOM sanitizer and PII anonymizer inspired by
+ * PostHog Session Recording Masking, Hotjar Privacy Controls & FullStory Data Masking.
+ *
+ * Masks credit cards, emails, phone numbers, password fields, and elements annotated
+ * with data-privacy="mask", .ph-no-capture, or .fs-exclude before telemetry egress.
+ */
+export interface MaskingOptions {
+    maskAllInputs?: boolean;
+    maskCreditCards?: boolean;
+    maskEmails?: boolean;
+    maskPhoneNumbers?: boolean;
+    maskPassphraseInputs?: boolean;
+    customMaskRegexList?: RegExp[];
+}
+export interface SanitizationResult {
+    sanitizedHtml: string;
+    totalPiiItemsRedacted: number;
+    creditCardsRedactedCount: number;
+    emailsRedactedCount: number;
+    phoneNumbersRedactedCount: number;
+    inputValuesMaskedCount: number;
+    markedElementsMaskedCount: number;
+}
+export declare class SessionReplayPrivacyMasker {
+    private static readonly EMAIL_REGEX;
+    private static readonly PHONE_REGEX;
+    private static readonly CARD_REGEX;
+    /**
+     * Sanitizes an HTML snapshot string by masking PII and protected DOM nodes.
+     */
+    static sanitizeHtmlSnapshot(rawHtml: string, options?: MaskingOptions): SanitizationResult;
+}

package/dist/analytics/session-similarity-matcher.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Session Similarity & Anomaly Matcher
+ * Clean-room algorithm for finding nearest-neighbor replay sessions based on
+ * behavioral vector similarity (Jaccard on events, cosine on error vectors, duration/dwell ratio).
+ * Parity: OpenReplay Similar Sessions & PostHog Session Similarity.
+ */
+export interface SessionBehaviorProfile {
+    sessionId: string;
+    userId?: string;
+    durationSeconds: number;
+    pageViewsCount: number;
+    eventsList: string[];
+    errorCodes: string[];
+    hasRageClick?: boolean;
+    hasDeadClick?: boolean;
+    hasConversion?: boolean;
+    country?: string;
+    browser?: string;
+}
+export interface SessionSimilarityMatch {
+    candidateSessionId: string;
+    similarityScore: number;
+    sharedEvents: string[];
+    sharedErrors: string[];
+    reasons: string[];
+}
+export declare class SessionSimilarityMatcher {
+    /**
+     * Jaccard similarity between two sets of string tokens: |A ∩ B| / |A ∪ B|
+     */
+    static jaccardSimilarity(setA: Set<string>, setB: Set<string>): number;
+    /**
+     * Compares a target session against candidate sessions to find nearest neighbors.
+     */
+    static findSimilarSessions(target: SessionBehaviorProfile, candidates: SessionBehaviorProfile[], options?: {
+        limit?: number;
+        minSimilarity?: number;
+    }): SessionSimilarityMatch[];
+}

package/dist/analytics/sessionizer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sessionizer & Session Attribution Engine — RudderStack & Snowplow Parity
+ *
+ * Reconstitue et agrège les sessions de navigation à partir d'un flux chronologique
+ * d'événements atomiques (pageviews, clics, conversions).
+ *
+ * Fonctionnalités :
+ * - Découpage automatique des sessions par seuil d'inactivité (défaut: 30 minutes).
+ * - Détection du rebond (Bounce Rate) : session à pageview unique et durée inférieure au seuil.
+ * - Capture de la page d'entrée (Landing Page) et de la page de sortie (Exit Page).
+ * - Attribution du canal initial (UTM, referrer) et cumul du chiffre d'affaires / conversions.
+ */
+export interface SessionizerConfig {
+    /** Seuil d'inactivité en minutes pour clore une session (défaut: 30 min) */
+    inactivityTimeoutMinutes?: number;
+    /** Seuil de durée en secondes pour qualifier un rebond si 1 seul pageview (défaut: 10s) */
+    bounceThresholdSeconds?: number;
+}
+export interface SessionSummary {
+    sessionId: string;
+    userId?: string;
+    anonymousId: string;
+    startedAt: string;
+    endedAt: string;
+    durationSeconds: number;
+    eventCount: number;
+    pageViewCount: number;
+    entryPage: string;
+    exitPage: string;
+    referrer: string;
+    channel: string;
+    device?: string;
+    isBounce: boolean;
+    hasConversion: boolean;
+    revenue: number;
+    eventsCount: number;
+}
+export declare class Sessionizer {
+    private readonly timeoutMs;
+    private readonly bounceThresholdSeconds;
+    constructor(config?: SessionizerConfig);
+    /**
+     * Reconstitue les sessions à partir d'une liste d'événements.
+     */
+    sessionizeEvents(rawEvents: Array<Record<string, unknown>>): SessionSummary[];
+    private buildSessionSummary;
+}

package/dist/analytics/sessions.d.ts

@@ -0,0 +1,2 @@
+export declare function newSessionId(): string;
+export declare function newVisitorId(): string;

package/dist/analytics/shapley-attribution-engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shapley Value & Cooperative Game Theory Attribution Engine
+ * Clean-room implementation inspirée de Matomo Multi-Channel Attribution & PostHog Game-Theoretic Attribution.
+ * Conforme AGPLv3.
+ *
+ * Implémente le calcul rigoureux de la valeur de Shapley (Prix Nobel Lloyd Shapley) pour l'attribution marketing multi-touch :
+ * Chaque canal marketing est modélisé comme un joueur dans une coalition coopérative.
+ * Sa contribution marginale v(S ∪ {i}) - v(S) est moyennée sur l'ensemble des sous-ensembles de canaux possibles.
+ *
+ * Propriétés fondamentales garanties :
+ * - Efficacité : La somme des attributions est exactement égale au total des conversions / CA (100%).
+ * - Symétrie : Deux canaux produisant le même impact marginal reçoivent la même valeur.
+ * - Joueur nul : Un canal sans impact incrémental reçoit une attribution de 0.
+ * - Additivité : La combinaison de conversions est additive.
+ */
+import type { JourneyPath } from "./markov-attribution-engine";
+export interface ChannelShapleyAttribution {
+    channel: string;
+    shapleyValue: number;
+    attributionSharePct: number;
+    attributedConversions: number;
+    attributedRevenue: number;
+    firstTouchSharePct: number;
+    lastTouchSharePct: number;
+    linearSharePct: number;
+    deltaVsLastTouchPct: number;
+}
+export interface ShapleyAttributionReport {
+    totalJourneys: number;
+    convertedJourneys: number;
+    totalConversions: number;
+    totalRevenue: number;
+    uniqueChannelsCount: number;
+    method: "exact_enumeration" | "monte_carlo_sampling";
+    permutationsEvaluated: number;
+    channels: ChannelShapleyAttribution[];
+}
+export interface ShapleyEngineOptions {
+    /** Nombre maximal de canaux pour l'énumération exacte 2^N (par défaut : 10) */
+    exactThreshold?: number;
+    /** Nombre d'échantillons Monte Carlo si N > exactThreshold (par défaut : 2000) */
+    monteCarloSamples?: number;
+    /**
+     * Graine du générateur pseudo-aléatoire utilisé par Monte Carlo. Fixée par
+     * défaut pour que deux appels sur les mêmes parcours produisent le même
+     * rapport (les rapports sont comparés et mis en cache).
+     */
+    seed?: number;
+}
+export declare class ShapleyAttributionEngine {
+    /**
+     * Calcule l'attribution par Valeur de Shapley sur un ensemble de parcours clients.
+     */
+    static compute(journeys: JourneyPath[], options?: ShapleyEngineOptions): ShapleyAttributionReport;
+}