@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/analytics/heatmap-density-rasterizer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * HeatmapDensityRasterizer — Normalisation responsive et calcul de densité 2D par noyau Gaussien (KDE).
+ * Parité PostHog Toolbar Heatmap & Matomo Heatmap Grid.
+ *
+ * Transforme des coordonnées de clics / scrolls collectées sur des résolutions variées
+ * (mobile 375px, tablette 768px, desktop 1440px) en une grille de densité normalisée
+ * exploitable directement par les canvas HTML5 ou calques SVG d'overlay.
+ */
+export interface HeatmapRawPoint {
+    x: number;
+    y: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    targetSelector?: string;
+    weight?: number;
+}
+export interface HeatmapRasterOptions {
+    gridCols?: number;
+    gridRows?: number;
+    kernelRadius?: number;
+    normalizeByViewport?: boolean;
+    minIntensityThreshold?: number;
+}
+export interface HeatmapDensityCell {
+    col: number;
+    row: number;
+    xPct: number;
+    yPct: number;
+    rawWeight: number;
+    intensity: number;
+}
+export interface HeatmapRasterResult {
+    metadata: {
+        totalPoints: number;
+        totalWeight: number;
+        gridCols: number;
+        gridRows: number;
+        maxDensity: number;
+        viewportDistribution: {
+            mobile: number;
+            tablet: number;
+            desktop: number;
+        };
+    };
+    cells: HeatmapDensityCell[];
+    topSelectors: Array<{
+        selector: string;
+        clicksCount: number;
+        sharePct: number;
+    }>;
+}
+export declare class HeatmapDensityRasterizer {
+    /**
+     * Calcule la matrice de densité 2D avec lissage Gaussien.
+     */
+    static rasterize(points: HeatmapRawPoint[], options?: HeatmapRasterOptions): HeatmapRasterResult;
+}

package/dist/analytics/holt-winters-forecast-engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 📈 Holt-Winters Time Series Forecast & Prediction Interval Engine
+ * Clean-room implementation inspired by GA4 Predictive Metrics & Amplitude Forecast Anomaly Detection.
+ *
+ * Implements double and additive triple exponential smoothing (level, trend, seasonal cycle),
+ * generates forward-looking forecast points with 95% and 99% confidence intervals, and flags breach anomalies.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface HoltWintersTimeSeriesPoint {
+    timestamp: number;
+    value: number;
+}
+export interface HoltWintersForecastPoint {
+    step: number;
+    projectedTimestamp: number;
+    forecastValue: number;
+    confidence95Lower: number;
+    confidence95Upper: number;
+    confidence99Lower: number;
+    confidence99Upper: number;
+}
+export interface ForecastDivergenceAnomaly {
+    timestamp: number;
+    actualValue: number;
+    expectedValue: number;
+    confidenceBand: "95%" | "99%";
+    direction: "above_upper" | "below_lower";
+    deviationDelta: number;
+    deviationPercentage: number;
+    severity: "warning" | "critical";
+    message: string;
+}
+export interface HoltWintersForecastReport {
+    historicalDataPointsCount: number;
+    levelAlpha: number;
+    trendBeta: number;
+    seasonalGamma?: number;
+    seasonLength?: number;
+    rmse: number;
+    mape: number;
+    forecastHorizon: number;
+    forecastPoints: HoltWintersForecastPoint[];
+    historicalDivergences: ForecastDivergenceAnomaly[];
+    trendDirection: "strongly_upward" | "upward" | "stable" | "downward" | "strongly_downward";
+}
+export interface HoltWintersOptions {
+    alpha?: number;
+    beta?: number;
+    gamma?: number;
+    seasonLength?: number;
+    forecastHorizon?: number;
+    stepDurationMs?: number;
+}
+export declare class HoltWintersForecastEngine {
+    /**
+     * Fits Holt-Winters model on historical series and projects forward forecast with prediction intervals.
+     */
+    static forecast(data: HoltWintersTimeSeriesPoint[], options?: HoltWintersOptions): HoltWintersForecastReport;
+    private static emptyReport;
+}

package/dist/analytics/hreflang-integrity-engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * HreflangIntegrityEngine — Audit de Réciprocité & Conformité Internationale Hreflang
+ *
+ * Parité : Ahrefs (International SEO Audit) & Screaming Frog Hreflang Tab.
+ *
+ * Valide la cohérence des balises hreflang multi-régionales et multi-lingues :
+ * 1. Balise d'auto-référence (Self-Referential Hreflang) : La page doit s'inclure elle-même.
+ * 2. Liens réciproques obligatoires (Return / Bi-directional links) :
+ *    Si la page A référence la page B en allemand, la page B DOIT référencer la page A en français.
+ * 3. Validation des codes de langue (ISO 639-1) et de région (ISO 3166-1 Alpha-2) :
+ *    Détecte les erreurs fréquentes (ex: 'en-UK' au lieu de 'en-GB', ou code pays inversé).
+ * 4. Gestion de la balise 'x-default' : Vérifie sa présence pour les pages de sélection globale.
+ * 5. Cibles invalides : Balises hreflang pointant vers des erreurs HTTP, redirections ou pages non-canoniques.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface HreflangTag {
+    lang: string;
+    href: string;
+}
+export interface PageHreflangDeclaration {
+    url: string;
+    hreflangs: HreflangTag[];
+    statusCode?: number;
+    isCanonical?: boolean;
+}
+export type HreflangIssueType = "missing_self_reference" | "missing_return_link" | "invalid_language_code" | "invalid_region_code" | "target_non_200" | "target_non_canonical" | "missing_x_default";
+export interface HreflangIssue {
+    sourceUrl: string;
+    targetUrl?: string;
+    langCode: string;
+    type: HreflangIssueType;
+    severity: "critical" | "warning";
+    detail: string;
+}
+export interface HreflangClusterGroup {
+    clusterId: string;
+    urls: {
+        lang: string;
+        url: string;
+        hasReciprocal: boolean;
+    }[];
+    isFullyReciprocal: boolean;
+}
+export interface HreflangAuditReport {
+    totalPagesAudited: number;
+    totalHreflangTagsFound: number;
+    validTagsCount: number;
+    issuesCount: number;
+    issues: HreflangIssue[];
+    clusters: HreflangClusterGroup[];
+    healthScore: number;
+    summary: string;
+    generatedAt: string;
+}
+export declare class HreflangIntegrityEngine {
+    audit(declarations: PageHreflangDeclaration[]): HreflangAuditReport;
+    private validateLangRegion;
+    private normalizeUrl;
+    private emptyReport;
+}

package/dist/analytics/hreflang-regional-x-default-cascade-resolver.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HreflangRegionalXDefaultCascadeResolver
+ * Simulates and resolves Googlebot and browser geo-targeting cascades across complex
+ * multi-language and multi-region hreflang page clusters with fallback resolution.
+ */
+export interface HreflangVariantEntry {
+    langCode: string;
+    targetUrl: string;
+}
+export interface ClientLocaleSignal {
+    acceptLanguage: string;
+    geoCountry?: string;
+}
+export type CascadeResolutionStrategy = "exact_lang_region_match" | "generic_language_fallback" | "x_default_global_fallback" | "cluster_primary_fallback";
+export interface ResolvedLocaleTarget {
+    selectedUrl: string;
+    matchedLangCode: string;
+    strategy: CascadeResolutionStrategy;
+    confidenceScore: number;
+    resolutionExplanation: string;
+}
+export declare class HreflangRegionalXDefaultCascadeResolver {
+    /**
+     * Resolves the optimal URL target for a user's locale and country from a hreflang cluster.
+     */
+    resolveTarget(cluster: HreflangVariantEntry[], client: ClientLocaleSignal): ResolvedLocaleTarget;
+    private parseAcceptLanguage;
+}

package/dist/analytics/hreflang-return-tag-reciprocity-auditor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HreflangReturnTagReciprocityAuditor
+ * Audits bidirectional return tag reciprocity, self-referencing hreflangs,
+ * ISO 639-1 / ISO 3166-1 format compliance, and x-default fallbacks.
+ */
+export interface HreflangTagEntry {
+    lang: string;
+    targetUrl: string;
+}
+export interface PageHreflangClusterInput {
+    url: string;
+    declaredHreflangs: HreflangTagEntry[];
+}
+export type HreflangReciprocityViolationType = "missing_self_reference" | "missing_return_tag_non_reciprocal" | "invalid_language_region_syntax" | "missing_x_default" | "target_page_not_found_in_cluster";
+export interface HreflangReciprocityViolation {
+    sourceUrl: string;
+    targetUrl?: string;
+    langCode: string;
+    violationType: HreflangReciprocityViolationType;
+    message: string;
+    remediationSnippet?: string;
+}
+export interface HreflangReciprocityAuditReport {
+    totalPagesAudited: number;
+    totalHreflangTagsEvaluated: number;
+    validReciprocalTagsCount: number;
+    violationsCount: number;
+    reciprocityScore: number;
+    violations: HreflangReciprocityViolation[];
+    hasXDefaultFallback: boolean;
+}
+export declare class HreflangReturnTagReciprocityAuditor {
+    private static readonly LANG_REGEX;
+    /**
+     * Audits a cluster of pages for hreflang reciprocity and syntax correctness.
+     */
+    audit(pages: PageHreflangClusterInput[]): HreflangReciprocityAuditReport;
+    private normalizeUrl;
+}

package/dist/analytics/html-doctype-declaration-legacy-syntax-auditor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HtmlDoctypeDeclarationLegacySyntaxAuditor
+ * Audits HTML document doctype declarations, detecting missing doctypes, quirks mode triggers,
+ * XML prologs, and legacy HTML4/XHTML doctypes that harm CSS rendering and CLS stability.
+ */
+export type DoctypeStatus = "standard_html5" | "legacy_xhtml_or_html4" | "quirks_mode_missing_doctype" | "xml_prolog_preceding_doctype";
+export interface DoctypeAuditReport {
+    status: DoctypeStatus;
+    detectedDoctypeString: string | null;
+    triggersQuirksMode: boolean;
+    doctypeComplianceScore: number;
+    explanation: string;
+    recommendedDoctype: string;
+}
+export declare class HtmlDoctypeDeclarationLegacySyntaxAuditor {
+    private static readonly HTML5_DOCTYPE_REGEX;
+    private static readonly ANY_DOCTYPE_REGEX;
+    private static readonly XML_PROLOG_REGEX;
+    /**
+     * Audits the HTML doctype declaration.
+     */
+    audit(htmlPrefix: string): DoctypeAuditReport;
+}

package/dist/analytics/html-entity-encoding-double-escaping-auditor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HtmlEntityEncodingDoubleEscapingAuditor
+ * Detects double-encoded HTML entities in SEO title tags, meta descriptions, and JSON-LD schemas
+ * (e.g. &, ', ") that degrade SERP CTR and cause snippet corruption.
+ */
+export interface SnippetEntityAuditInput {
+    url: string;
+    field: "title" | "meta_description" | "og_title" | "og_description" | "json_ld_name";
+    rawText: string;
+}
+export interface DoubleEscapedEntityFinding {
+    field: string;
+    rawText: string;
+    doubleEncodedEntity: string;
+    suggestedSingleEncoded: string;
+    decodedCharacter: string;
+    correctedText: string;
+    serpImpactExplanation: string;
+}
+export interface HtmlEntityEncodingAuditReport {
+    url: string;
+    hasDoubleEncoding: boolean;
+    totalDoubleEncodedEntities: number;
+    snippetQualityScore: number;
+    findings: DoubleEscapedEntityFinding[];
+    remediatedFields: Record<string, string>;
+}
+export declare class HtmlEntityEncodingDoubleEscapingAuditor {
+    private static readonly DOUBLE_ENCODED_REGEX;
+    private static readonly REPLACEMENTS;
+    /**
+     * Audits SEO titles and descriptions for double-escaped entities.
+     */
+    audit(url: string, inputs: SnippetEntityAuditInput[]): HtmlEntityEncodingAuditReport;
+}

package/dist/analytics/html-lang-directionality-bidi-auditor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HtmlLangDirectionalityBidiAuditor
+ * Audits BCP 47 language tags, RTL/LTR directionality consistency,
+ * and WCAG 3.1.1 compliance on root <html> tags and inline content blocks.
+ */
+export interface BidiAuditorInput {
+    url: string;
+    htmlString?: string;
+    declaredLang?: string;
+    declaredDir?: "ltr" | "rtl" | "auto" | string;
+}
+export type BidiIssueType = "missing_html_lang" | "invalid_bcp47_delimiter" | "unrecognized_language_code" | "rtl_language_missing_rtl_dir" | "ltr_language_with_rtl_dir" | "missing_dir_attribute";
+export interface BidiAuditFinding {
+    issue: BidiIssueType;
+    severity: "critical" | "warning" | "info";
+    description: string;
+    recommendation: string;
+}
+export interface BidiAuditReport {
+    url: string;
+    isValid: boolean;
+    score: number;
+    effectiveLang?: string;
+    effectiveDir: "ltr" | "rtl" | "auto";
+    isRtlExpected: boolean;
+    findings: BidiAuditFinding[];
+    correctedHtmlTag: string;
+    recommendations: string[];
+}
+export declare class HtmlLangDirectionalityBidiAuditor {
+    private static readonly RTL_LANG_PREFIXES;
+    private static readonly KNOWN_COMMON_LANGS;
+    /**
+     * Audits document language and directionality attributes.
+     */
+    audit(input: BidiAuditorInput): BidiAuditReport;
+    private extractFromHtml;
+}

package/dist/analytics/html-microformat-hcard-hcalendar-auditor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HtmlMicroformatHcardHcalendarAuditor
+ * Detects legacy microformats (hCard, hCalendar, hReview, hEntry) and prescribes migration
+ * to modern schema.org JSON-LD structured data for Google Knowledge Graph and Rich Results.
+ */
+export interface MicroformatElementInput {
+    className: string;
+    tagName: string;
+    extractedValues?: Record<string, string>;
+}
+export type LegacyMicroformatType = "h-card" | "h-calendar" | "h-review" | "h-entry" | "h-geo";
+export interface MicroformatFinding {
+    detectedType: LegacyMicroformatType;
+    rawClassString: string;
+    isIgnoredByGoogleRichResults: boolean;
+    recommendedSchemaType: string;
+    generatedJsonLdSnippet: string;
+}
+export interface MicroformatAuditReport {
+    hasLegacyMicroformats: boolean;
+    totalMicroformatsDetected: number;
+    modernizationScore: number;
+    findings: MicroformatFinding[];
+    migrationGuidance: string[];
+}
+export declare class HtmlMicroformatHcardHcalendarAuditor {
+    private static readonly MICROFORMAT_PATTERNS;
+    /**
+     * Audits HTML DOM class structures for legacy microformats.
+     */
+    audit(elements: MicroformatElementInput[]): MicroformatAuditReport;
+    private generateJsonLd;
+}

package/dist/analytics/html-text-contrast-accessibility-a11y-auditor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HtmlTextContrastAccessibilityA11yAuditor
+ * Computes W3C relative luminance and contrast ratios between text and background colors,
+ * verifying WCAG 2.2 AA/AAA accessibility compliance to avoid Lighthouse organic SEO penalties.
+ */
+export interface TextContrastAuditInput {
+    elementSelector: string;
+    textColorHex: string;
+    backgroundColorHex: string;
+    fontSizePx: number;
+    isBold?: boolean;
+}
+export interface ContrastFinding {
+    elementSelector: string;
+    contrastRatio: number;
+    isLargeText: boolean;
+    passesWcagAA: boolean;
+    passesWcagAAA: boolean;
+    requiredRatioAA: number;
+    requiredRatioAAA: number;
+    textColorHex: string;
+    backgroundColorHex: string;
+    remediationAdvice?: string;
+}
+export interface TextContrastAuditReport {
+    totalElementsAudited: number;
+    passingElementsCount: number;
+    failingElementsCount: number;
+    accessibilityContrastScore: number;
+    findings: ContrastFinding[];
+}
+export declare class HtmlTextContrastAccessibilityA11yAuditor {
+    /**
+     * Audits DOM text elements for WCAG 2.2 contrast compliance.
+     */
+    audit(elements: TextContrastAuditInput[]): TextContrastAuditReport;
+    /**
+     * Computes the W3C contrast ratio between two colors: (L1 + 0.05) / (L2 + 0.05)
+     */
+    calculateContrastRatio(foregroundHex: string, backgroundHex: string): number;
+    /**
+     * Calculates W3C relative luminance from sRGB hex color.
+     */
+    private calculateRelativeLuminance;
+    private channelLuminance;
+}

package/dist/analytics/http-header-security-seo-audit-engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HttpHeaderSecuritySeoAuditEngine
+ * Source-grounded HTTP security and SEO header auditor.
+ * Provides Mozilla Observatory, SecurityHeaders.com, and Screaming Frog audit parity.
+ */
+export type HeaderSecurityGrade = "A+" | "A" | "B" | "C" | "D" | "F";
+export type HeaderFindingSeverity = "critical" | "warning" | "info" | "pass";
+export interface HeaderAuditFinding {
+    header: string;
+    severity: HeaderFindingSeverity;
+    status: "present" | "missing" | "misconfigured" | "deprecated" | "leaked";
+    currentValue?: string;
+    recommendedValue?: string;
+    title: string;
+    description: string;
+    scorePenalty: number;
+}
+export interface HeaderAuditReport {
+    targetUrl?: string;
+    overallScore: number;
+    grade: HeaderSecurityGrade;
+    passedCount: number;
+    warningCount: number;
+    criticalCount: number;
+    findings: HeaderAuditFinding[];
+    xRobotsDirectives: {
+        noindex: boolean;
+        nofollow: boolean;
+        noarchive: boolean;
+        nosnippet: boolean;
+        rawValues: string[];
+    };
+    serverLeakage: {
+        serverHeader?: string;
+        poweredByHeader?: string;
+        isVulnerableToFingerprinting: boolean;
+    };
+    remediationSnippets: {
+        nginx: string;
+        cloudflareTransformRules: string;
+        caddy: string;
+    };
+}
+export declare class HttpHeaderSecuritySeoAuditEngine {
+    /**
+     * Normalizes header keys to lowercase for case-insensitive lookup.
+     */
+    private normalizeHeaders;
+    /**
+     * Audits HTTP response headers for security compliance and SEO directives.
+     */
+    audit(headers: Record<string, string | string[] | undefined>, options?: {
+        targetUrl?: string;
+        isHttps?: boolean;
+    }): HeaderAuditReport;
+    /**
+     * Generates production snippets for hardening server configurations.
+     */
+    private generateSnippets;
+}

package/dist/analytics/http-strict-transport-security-preload-auditor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - HttpStrictTransportSecurityPreloadAuditor
+ * Audits HTTP Strict Transport Security (HSTS) headers against Chromium/hstspreload.org
+ * submission criteria, preventing SSL stripping (MIM), downgrade attacks, and search indexing degradation.
+ */
+export interface HstsEndpointResponse {
+    url: string;
+    protocol: "http" | "https";
+    statusCode: number;
+    headers: Record<string, string | undefined>;
+    redirectTarget?: string;
+}
+export interface HstsAuditDomainInput {
+    domain: string;
+    httpRoot: HstsEndpointResponse;
+    httpsRoot: HstsEndpointResponse;
+    subdomainChecks?: HstsEndpointResponse[];
+}
+export type HstsPreloadIneligibilityReason = "http_does_not_redirect_to_https" | "missing_hsts_header_on_https" | "max_age_below_one_year" | "missing_include_subdomains" | "missing_preload_directive" | "hsts_header_leaked_over_insecure_http" | "subdomains_lack_valid_https";
+export interface HstsPreloadAuditResult {
+    domain: string;
+    isEligibleForPreloadList: boolean;
+    securityScore: number;
+    parsedMaxAgeSeconds: number;
+    hasIncludeSubDomains: boolean;
+    hasPreloadDirective: boolean;
+    ineligibilityReasons: HstsPreloadIneligibilityReason[];
+    recommendations: string[];
+    canonicalHeaderSuggestion: string;
+}
+export declare class HttpStrictTransportSecurityPreloadAuditor {
+    private static readonly MIN_MAX_AGE_SECONDS;
+    /**
+     * Audits domain HSTS configuration for chromium preload eligibility and security compliance.
+     */
+    audit(input: HstsAuditDomainInput): HstsPreloadAuditResult;
+    private parseHstsHeader;
+    private getHeaderCaseInsensitive;
+}

package/dist/analytics/http2-server-push-deprecation-early-hints-auditor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Http2ServerPushDeprecationEarlyHintsAuditor
+ * Audits HTTP/2 Server Push deprecation and prescribes migration to HTTP 103 Early Hints
+ * for ultra-low latency resource preloading without server push bandwidth waste.
+ */
+export interface ServerPushHeaderInput {
+    url: string;
+    responseHeaders: Record<string, string>;
+    isHttp2Or3: boolean;
+    resourceSizeEstBytes?: number;
+}
+export type PushDeliveryMechanism = "deprecated_h2_push" | "modern_103_early_hints" | "standard_html_preload";
+export interface EarlyHintsPreloadCandidate {
+    resourceUri: string;
+    asType: "script" | "style" | "font" | "image";
+    isEarlyHintsEligible: boolean;
+    recommendedHeaderDirective: string;
+}
+export interface EarlyHintsAuditReport {
+    pageUrl: string;
+    currentMechanism: PushDeliveryMechanism;
+    hasDeprecatedServerPush: boolean;
+    hasEarlyHintsConfigured: boolean;
+    preloadingEfficiencyScore: number;
+    candidates: EarlyHintsPreloadCandidate[];
+    remediationAdvice: string[];
+    recommended103Headers: string[];
+}
+export declare class Http2ServerPushDeprecationEarlyHintsAuditor {
+    private static readonly PUSH_LINK_REGEX;
+    /**
+     * Audits HTTP response headers for deprecated HTTP/2 Server Push and modern 103 Early Hints.
+     */
+    audit(input: ServerPushHeaderInput): EarlyHintsAuditReport;
+}

package/dist/analytics/identity-graph-stitching-engine.d.ts

@@ -0,0 +1,66 @@
+/**
+ * IdentityGraphStitchingEngine — Réconciliation d'Identité Cross-Device & Stitching Rétroactif
+ *
+ * Parité : Google Analytics 4 (User-ID & Cross-Device Stitching) & Mixpanel Identity Resolution.
+ *
+ * Résout le problème fondamental de la fragmentation de l'identité des visiteurs :
+ * Un utilisateur navigue d'abord de manière anonyme sur mobile (cookie A), puis sur desktop (cookie B),
+ * avant de se connecter avec son compte authentifié (User ID 'usr_123').
+ *
+ * Fonctionnalités du moteur :
+ * 1. Graphe d'Identité Disjoint (Union-Find / Disjoint-Set Forest) :
+ *    - Relie les identifiants anonymes (cookies, anonymous_id, device_id) à l'identifiant personne canonique.
+ * 2. Stitching Rétroactif des Événements :
+ *    - Réattribue les événements passés enregistrés sous l'ID anonyme à la personne authentifiée unifiée.
+ * 3. Gestion des Conflits Multi-Utilisateurs :
+ *    - Gère les ordinateurs partagés où plusieurs utilisateurs distincts se connectent sur le même appareil
+ *      en isolant les sessions sans corrompre le graphe global.
+ * 4. Vue Unifiée du Parcours Client (Unified Customer Journey) :
+ *    - Reconstitue la chronologie exacte des interactions multi-appareils pour l'attribution.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface IdentityLinkEvent {
+    anonymousId: string;
+    userId?: string | null;
+    timestamp: string;
+    deviceType?: "mobile" | "desktop" | "tablet";
+}
+export interface RawTrackEvent {
+    eventId: string;
+    anonymousId: string;
+    userId?: string | null;
+    eventName: string;
+    timestamp: string;
+    properties?: Record<string, string | number | boolean>;
+}
+export interface StitchedEvent extends RawTrackEvent {
+    canonicalPersonId: string;
+    isRetroactivelyStitched: boolean;
+}
+export interface PersonIdentityNode {
+    canonicalPersonId: string;
+    associatedUserIds: string[];
+    associatedAnonymousIds: string[];
+    devicesCount: number;
+    firstSeenAt: string;
+    lastSeenAt: string;
+}
+export interface IdentityStitchingReport {
+    totalLinksProcessed: number;
+    uniqueCanonicalPersons: number;
+    totalAnonymousIdsMerged: number;
+    stitchedEventsCount: number;
+    retroactiveStitchPercentage: number;
+    persons: PersonIdentityNode[];
+    generatedAt: string;
+}
+export declare class IdentityGraphStitchingEngine {
+    private idToCanonical;
+    private personNodes;
+    processLinks(links: IdentityLinkEvent[]): void;
+    stitchEvents(events: RawTrackEvent[]): StitchedEvent[];
+    generateReport(links: IdentityLinkEvent[], events: RawTrackEvent[]): IdentityStitchingReport;
+    getCanonicalId(identifier: string): string;
+    private updatePersonNode;
+}

package/dist/analytics/identity-ip-bucket.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Identity IP Bucket & Subnet Anonymizer
+ * Clean-room implementation inspired by Rybbit identityIpBucket & privacy-first analytics.
+ * Truncates IPv4 addresses to /24 subnets and IPv6 addresses to /48 subnets,
+ * producing deterministic, GDPR-compliant pseudonymized identity buckets using HMAC.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface IpBucketResult {
+    originalIpMasked: string;
+    subnetCidr: string;
+    bucketHash: string;
+    isIpv6: boolean;
+    isPrivateOrLoopback: boolean;
+}
+export declare class IdentityIpBucket {
+    private static readonly IPV4_REGEX;
+    /**
+     * Evaluates and buckets an IP address into a privacy-safe /24 or /48 CIDR subnet
+     */
+    static bucketIp(ip: string, salt?: string): IpBucketResult;
+    private static processIpv4;
+    private static processIpv6;
+    private static hashString;
+}