@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/i18n/translator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Report translation engine for LynxSEO Engine
+ * Translates HTML, PDF, Excel, and Markdown reports at render time so audit.json
+ * remains language-neutral and any saved audit can be re-rendered in any language.
+ */
+import type ExcelJS from "exceljs";
+export declare const SOURCE_LANG = "en";
+export declare const TRANSLATED_GROUP_PREFIX = "t_";
+export declare const PROTECTED_BLOCKS: RegExp;
+export declare const TEXT_NODE: RegExp;
+export declare const TEXT_ATTR: RegExp;
+export declare const CSS_CONTENT: RegExp;
+export declare const CSS_STRING: RegExp;
+export declare const FORMULA_LITERAL: RegExp;
+export interface TranslationCatalog {
+    text?: Record<string, string>;
+    patterns?: Array<[string, string]>;
+}
+export declare class Translator {
+    readonly lang: string;
+    readonly active: boolean;
+    readonly text: Map<string, string>;
+    readonly translated: Set<string>;
+    readonly patterns: Array<{
+        regex: RegExp;
+        template: string;
+    }>;
+    readonly misses: Set<string>;
+    constructor(lang?: string, catalogDir?: string);
+    /**
+     * Returns list of supported language codes available in catalogs directory.
+     */
+    static getAvailableLanguages(catalogDir?: string): string[];
+    /**
+     * Main string translator callable.
+     * Preserves leading and trailing whitespace.
+     */
+    translate(s: unknown): string;
+    /**
+     * Core translation lookup (exact dictionary first, then regex patterns).
+     */
+    core(s: string): string;
+    /**
+     * Escapes translated text for HTML injection while preserving quotes.
+     */
+    escaped(s: string): string;
+    /**
+     * Translates complete HTML document.
+     * Protects script and style blocks from being mangled,
+     * but translates CSS @page footer content: strings and title/alt attributes.
+     */
+    html(rawHtml: string): string;
+    /**
+     * Translates an in-memory ExcelJS workbook before saving.
+     * Updates:
+     * - Worksheet names
+     * - Sheet references in cell formulas (e.g. Actions!$E:$E -> 'Plan d'actions'!$E:$E)
+     * - Formula string literals (e.g. COUNTIF(..., "done") -> COUNTIF(..., "terminé"))
+     * - Data validation dropdown lists
+     * - Plain text cells
+     */
+    workbook(wb: ExcelJS.Workbook): void;
+    /**
+     * Translates Markdown document line by line.
+     * Preserves code fences, translates Mermaid diagrams, table rows,
+     * image alt text, and structured heading/list prefixes.
+     */
+    markdown(mdContent: string): string;
+    translateMdLine(line: string): string;
+    translateMermaid(line: string): string;
+}

package/dist/identity-resolver.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 🔗 Identity Resolution (anonymous → user)
+ *
+ * Sans ce module, un funnel est faux par construction : la visite anonyme qui
+ * mène à l'inscription est comptée sur un `anonymous_id`, puis la conversion
+ * sur un `user_id`. Les deux ne sont jamais rapprochés.
+ *
+ * Le résolveur tient un graphe d'identités :
+ * - `anonymous_id` → utilisateur canonique ;
+ * - `user_id` → utilisateur canonique (alias après fusion de comptes) ;
+ * - email normalisé → utilisateur canonique.
+ *
+ * Invariants :
+ * - **Déterministe** : aucune horloge implicite (`now` injectable), aucun
+ *   `Math.random()`. Une même séquence d'appels produit le même graphe.
+ * - **Fusion stable** : quand deux identités désignent deux comptes, le compte
+ *   canonique est celui qui a été vu en premier (`firstSeenAt`, puis `userId`
+ *   lexicographique en cas d'égalité). Une fusion ne s'inverse jamais toute
+ *   seule, et `mergeUsers` conserve les alias pour que les événements déjà
+ *   ingérés restent attribuables.
+ * - **Fail-closed** : un `anonymous_id` non relié ne renvoie jamais un
+ *   utilisateur « au hasard » ; il renvoie `null`.
+ * - **Effacement** : `anonymize()` coupe les emails et marque le profil, sans
+ *   supprimer les alias — sinon les funnels historiques deviendraient
+ *   incohérents après une demande RGPD.
+ */
+export interface IdentityLink {
+    anonymousId: string;
+    userId: string;
+    at: string;
+    source: IdentityLinkSource;
+}
+export type IdentityLinkSource = "signup" | "login" | "identify" | "email" | "merge";
+export interface IdentityProfile {
+    /** Identifiant canonique : jamais réécrit, même après une fusion. */
+    userId: string;
+    anonymousIds: string[];
+    /** Emails normalisés (minuscules, espaces retirés). */
+    emails: string[];
+    firstSeenAt: string;
+    lastSeenAt: string;
+    anonymized: boolean;
+}
+export interface IdentifyInput {
+    anonymousId?: string;
+    userId?: string;
+    email?: string;
+    at?: string;
+    source?: IdentityLinkSource;
+}
+export interface IdentifyResult {
+    /** `null` tant qu'aucun compte n'est connu (visiteur purement anonyme). */
+    userId: string | null;
+    profile: IdentityProfile | null;
+    /** Comptes absorbés par cette résolution (du plus ancien au plus récent). */
+    mergedUserIds: string[];
+    /** Vrai si un nouveau profil vient d'être créé. */
+    created: boolean;
+}
+export interface ResolvedEvent<T> {
+    event: T;
+    userId: string | null;
+    anonymousId: string | null;
+    /** Faux si l'événement n'a pas pu être rattaché à un compte. */
+    attributed: boolean;
+}
+export interface EventWithIdentity {
+    anonymousId?: string | null;
+    userId?: string | null;
+}
+export interface IdentityResolverOptions {
+    /** Horloge injectable — les tests passent une horloge fixe. */
+    now?: () => Date;
+}
+/**
+ * Résolveur d'identités en mémoire.
+ *
+ * La persistance (D1/Postgres) est laissée à l'appelant : `snapshot()` et
+ * `restore()` permettent de sérialiser le graphe dans la table d'identités,
+ * sans dépendre d'un stockage particulier.
+ */
+export declare class IdentityResolver {
+    private readonly now;
+    /** userId (ou alias) → userId canonique. */
+    private readonly userAliases;
+    /** anonymous_id → userId canonique. */
+    private readonly anonymousOwners;
+    /** email normalisé → userId canonique. */
+    private readonly emailOwners;
+    /** anonymous_id connus mais pas encore reliés à un compte. */
+    private readonly pendingAnonymous;
+    private readonly profiles;
+    private readonly links;
+    constructor(options?: IdentityResolverOptions);
+    /**
+     * Enregistre une identification (inscription, connexion, `identify()`).
+     *
+     * - Avec `anonymousId` seul : mémorise le visiteur, renvoie `userId: null`.
+     * - Avec `userId` : crée ou rejoint le profil, et rattache l'`anonymousId`
+     *   et/ou l'email fournis.
+     * - Si l'`anonymousId` ou l'email appartient déjà à un AUTRE compte, les
+     *   comptes sont fusionnés (le plus ancien l'emporte).
+     */
+    identify(input: IdentifyInput): IdentifyResult;
+    /** Rattache un `anonymous_id` à un compte connu. */
+    linkAnonymous(anonymousId: string, userId: string, at?: string, source?: IdentityLinkSource): string;
+    /** Résout un identifiant quelconque (anonyme ou utilisateur) vers le canonique. */
+    resolve(identifier: string): string | null;
+    /** Profil canonique, ou `null` si inconnu. */
+    getProfile(userId: string): IdentityProfile | null;
+    /** Tous les alias connus d'un utilisateur (anonymes, emails, comptes fusionnés). */
+    getAliases(userId: string): {
+        userIds: string[];
+        anonymousIds: string[];
+        emails: string[];
+    };
+    /**
+     * Fusionne deux comptes. Le compte canonique est le plus ancien ; l'autre
+     * devient un alias. Aucune donnée n'est perdue : les anonymes et emails du
+     * compte absorbé sont déplacés vers le canonique.
+     */
+    mergeUsers(fromUserId: string, toUserId: string, at?: string): string;
+    /**
+     * Réécrit les événements d'un lot avec l'utilisateur canonique résolu.
+     * Utilisé à l'ingestion Pulse pour corriger les funnels rétroactivement.
+     */
+    resolveEvents<T extends EventWithIdentity>(events: readonly T[]): {
+        events: Array<ResolvedEvent<T>>;
+        attributed: number;
+        unattributed: number;
+    };
+    /**
+     * Effacement RGPD : supprime les emails et marque le profil comme anonymisé.
+     * Les alias d'anonymes sont conservés (identifiants techniques, non
+     * personnels) pour ne pas casser les agrégats historiques.
+     */
+    anonymize(userId: string, at?: string): boolean;
+    /** Sérialise le graphe pour persistance. */
+    snapshot(): {
+        profiles: IdentityProfile[];
+        aliases: Array<[string, string]>;
+        anonymous: Array<[string, string]>;
+        emails: Array<[string, string]>;
+        pendingAnonymous: string[];
+    };
+    /** Restaure un graphe sérialisé (idempotent). */
+    restore(snapshot: ReturnType<IdentityResolver["snapshot"]>): void;
+    /** Journal des rattachements, dans l'ordre d'ingestion. */
+    getLinks(): IdentityLink[];
+    private requireCanonicalUser;
+    private ensureProfile;
+    private canonicalizeUser;
+    private aliasUser;
+    private linkAnonymousRaw;
+    private linkEmail;
+    /** Absorbe `loser` dans `winner` : alias, anonymes et emails sont déplacés. */
+    private absorb;
+    /** Ordre canonique : plus ancien d'abord, puis `userId` lexicographique. */
+    private compareProfiles;
+    private touch;
+    private cloneProfile;
+}

package/dist/image-cwv-auditor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ⚡ Image SEO & Core Web Vitals 2026 Auditor & Modernizer
+ *
+ * Audits image markup against 2026 Core Web Vitals (LCP, CLS, INP)
+ * and Googlebot/AI Crawler indexation standards.
+ *
+ * Modernizes legacy JavaScript lazy loaders
+ * into zero-JS native HTML standards:
+ *  - Native loading="lazy" for below-the-fold images
+ *  - Native fetchpriority="high" for the LCP candidate (and NEVER loading="lazy" on LCP)
+ *  - Native sizes="auto" (Baseline 2024-2026)
+ *  - Explicit width/height or CSS aspect-ratio to prevent CLS
+ *  - decoding="async" to preserve INP / Main Thread responsiveness
+ *  - Modern image format detection (AVIF, WebP)
+ */
+export interface ImageCwvIssue {
+    type: "lcp-lazy-loaded" | "missing-fetchpriority-lcp" | "legacy-js-lazyload" | "missing-dimensions" | "outdated-format" | "missing-async-decoding";
+    severity: "critical" | "warning" | "info";
+    message: string;
+    recommendation: string;
+    elementSnippet: string;
+}
+export interface ImageCwvAuditReport {
+    score: number;
+    totalImages: number;
+    legacyScriptsDetected: string[];
+    issues: ImageCwvIssue[];
+    lcpCandidate: {
+        src?: string;
+        hasFetchPriorityHigh: boolean;
+        isLazyLoaded: boolean;
+        violatesLcpRule: boolean;
+    } | null;
+    metrics: {
+        clsRiskCount: number;
+        modernFormatCount: number;
+        legacyLazyloadCount: number;
+        nativeLazyloadCount: number;
+    };
+    verdict: "excellent" | "needs-improvement" | "critical-cwv-failure";
+    summary: string;
+}
+export interface ModernizationResult {
+    originalHtml: string;
+    modernizedHtml: string;
+    changesApplied: string[];
+    scoreGainEst: number;
+}
+export declare class ImageCwvAuditor {
+    private static readonly LEGACY_JS_PATTERNS;
+    /**
+     * Audits HTML string for images and Core Web Vitals 2026 compliance.
+     */
+    static auditHtml(html: string): ImageCwvAuditReport;
+    /**
+     * Modernizes legacy HTML to 2026 standards.
+     */
+    static modernizeTo2026(html: string): ModernizationResult;
+}

package/dist/image-geo-exif-enricher.d.ts

@@ -0,0 +1,68 @@
+export interface GeoCoordinates {
+    latitude: number;
+    longitude: number;
+    altitude?: number;
+}
+export interface ImageMetadata {
+    filename: string;
+    title?: string;
+    description?: string;
+    keywords?: string[];
+    copyright?: string;
+    credit?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    countryCode?: string;
+}
+export interface DmsCoordinate {
+    degrees: number;
+    minutes: number;
+    seconds: number;
+    ref: string;
+}
+export interface ExifGeoPayload {
+    GPSLatitude: DmsCoordinate;
+    GPSLongitude: DmsCoordinate;
+    GPSAltitude?: number;
+    GPSAltitudeRef?: number;
+    Headline?: string;
+    Caption?: string;
+    Keywords?: string[];
+    City?: string;
+    ProvinceState?: string;
+    CountryName?: string;
+    CountryCode?: string;
+    Credit?: string;
+    CopyrightNotice?: string;
+    xmpTitle?: string;
+    xmpDescription?: string;
+    exiftoolCommand: string;
+    htmlMetaSnippet: string;
+}
+export interface GeoExifEnrichmentResult {
+    filename: string;
+    coordinates: GeoCoordinates;
+    dmsLatitude: DmsCoordinate;
+    dmsLongitude: DmsCoordinate;
+    exifPayload: ExifGeoPayload;
+    localSeoKeywords: string[];
+    seoRecommendations: string[];
+}
+export declare class ImageGeoExifEnricher {
+    /**
+     * Convertit des degres decimaux en degres-minutes-secondes (DMS).
+     * @param decimal  Valeur en degres decimaux (positive ou negative)
+     * @param isLongitude  true pour la longitude (E/W), false pour la latitude (N/S)
+     */
+    static decimalToDms(decimal: number, isLongitude: boolean): DmsCoordinate;
+    /**
+     * Enrichit une image avec des donnees EXIF geographiques completes.
+     */
+    static enrich(coordinates: GeoCoordinates, metadata: ImageMetadata): GeoExifEnrichmentResult;
+    private static _formatDmsForExiftool;
+    private static _buildExiftoolCommand;
+    private static _buildHtmlMetaSnippet;
+    private static _buildLocalSeoKeywords;
+    private static _buildSeoRecommendations;
+}

package/dist/impact-analysis.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 📈 Impact Analysis (corrélation feature → rétention)
+ *
+ * Répond à la question que les cohortes ne savent pas trancher : « les
+ * utilisateurs qui utilisent la feature X se retiennent-ils *plus* que les
+ * autres, ou est-ce du bruit ? »
+ *
+ * Le module compare deux cohortes (exposée / contrôle) sur un taux de
+ * rétention et rend :
+ * - l'écart absolu en points de pourcentage (`absoluteLiftPp`) ;
+ * - l'écart relatif (`relativeLiftPct`) ;
+ * - un test de deux proportions (z, p-value bilatérale) ;
+ * - un intervalle de confiance à 95 % sur l'écart ;
+ * - un verdict `positive | negative | neutral | insufficient_data`.
+ *
+ * **Aucune corrélation n'est présentée comme une causalité** : le verdict est
+ * un signal, pas une preuve. Le champ `caveat` le rappelle explicitement à
+ * l'UI pour éviter les conclusions hâtives.
+ *
+ * Les mathématiques sont pures et déterministes (pas de `Math.random`), donc
+ * testables au chiffre près.
+ */
+export interface CohortStats {
+    /** Taille de la cohorte. */
+    total: number;
+    /** Nombre d'individus retenus (conversion, rétention J30, etc.). */
+    retained: number;
+}
+export interface ImpactAnalysisInput {
+    feature: string;
+    exposed: CohortStats;
+    control: CohortStats;
+    /** Seuil de significativité (0.05 par défaut). */
+    alpha?: number;
+    /** Taille minimale par cohorte avant de conclure quoi que ce soit. */
+    minimumSamplePerArm?: number;
+}
+export type ImpactVerdict = "positive" | "negative" | "neutral" | "insufficient_data";
+export interface ImpactResult {
+    feature: string;
+    exposedRate: number;
+    controlRate: number;
+    absoluteLiftPp: number;
+    relativeLiftPct: number | null;
+    zScore: number;
+    pValue: number;
+    alpha: number;
+    significant: boolean;
+    confidenceIntervalPp: {
+        low: number;
+        high: number;
+    };
+    verdict: ImpactVerdict;
+    caveat: string;
+    sample: {
+        exposed: number;
+        control: number;
+    };
+}
+/** Fonction d'erreur (Abramowitz & Stegun 7.1.26, erreur < 1.5e-7). */
+export declare function erf(x: number): number;
+/** Φ(z) — fonction de répartition de la loi normale centrée réduite. */
+export declare function normalCdf(z: number): number;
+/** p-value bilatérale d'un z-score. */
+export declare function twoSidedPValue(z: number): number;
+/**
+ * Test de deux proportions (pooled) : `H0 : p_exposed = p_control`.
+ */
+export declare function twoProportionZTest(exposed: CohortStats, control: CohortStats): {
+    zScore: number;
+    pValue: number;
+    pooledRate: number;
+};
+export declare function analyzeFeatureImpact(input: ImpactAnalysisInput): ImpactResult;
+/**
+ * Classe les impacts du plus convaincant au moins convaincant.
+ *
+ * Le score pénalise les résultats non significatifs (facteur 0.25) et les
+ * échantillons insuffisants (facteur 0), pour que l'UI ne place pas un
+ * « +400 % » calculé sur 2 utilisateurs en tête de liste.
+ */
+export declare function rankFeatureImpacts(results: readonly ImpactResult[]): ImpactResult[];
+export declare function impactScore(result: ImpactResult): number;
+/** Corrélation de Pearson entre deux séries de même longueur. */
+export declare function pearsonCorrelation(xs: readonly number[], ys: readonly number[]): number;