@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/nl-to-sql-engine.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 🗣️ NL → SQL (Text-to-SQL déterministe)
+ *
+ * Pont entre le composant `SqlEditor` et le noyau sémantique : l'utilisateur
+ * écrit « Montre-moi les revenus par pays des 30 derniers jours », on obtient
+ * une `SemanticQuery`, puis du SQL **paramétré** via `compileQuery`.
+ *
+ * Ce module n'appelle aucun LLM. C'est un choix délibéré :
+ * - **pas d'hallucination de table ou de colonne** : les seuls identifiants
+ *   utilisables sont ceux du catalogue sémantique (`SemanticRegistry`) ;
+ * - **pas d'injection** : les valeurs passent par les filtres typés du
+ *   compilateur (placeholders `$1` / `{p1:String}`), jamais par concaténation ;
+ * - **explicable** : chaque requête renvoie `matched` et `explanation`, donc
+ *   l'utilisateur peut voir comment sa phrase a été interprétée et corriger.
+ *
+ * Le vocabulaire métier (alias de métriques, dimensions, termes de filtre)
+ * est injecté par l'appelant : le moteur ne devine pas que « panier
+ * abandonné » signifie `event_name = 'cart_abandoned'`.
+ */
+import type { QueryFilter, FilterOperator } from "./seo-query-builder";
+import type { SqlDialect } from "./semantic/dialects/types";
+import type { SemanticRegistry } from "./semantic/registry";
+import type { CompiledQuery, SemanticQuery } from "./semantic/types";
+export interface NlFilterTerm {
+    /** Expressions reconnues, en français et/ou anglais. */
+    terms: readonly string[];
+    field: string;
+    operator: FilterOperator;
+    value: string | number | boolean;
+}
+export interface NlVocabulary {
+    /** Alias de modèles, par nom de modèle. */
+    models?: Readonly<Record<string, readonly string[]>>;
+    /** Alias de métriques, par nom de métrique (métrique = clé du modèle). */
+    metrics?: Readonly<Record<string, readonly string[]>>;
+    /** Alias de dimensions, par nom de dimension. */
+    dimensions?: Readonly<Record<string, readonly string[]>>;
+    /** Termes métier → filtre. */
+    filters?: readonly NlFilterTerm[];
+}
+export interface NlToSqlOptions {
+    registry: SemanticRegistry;
+    dialect: SqlDialect;
+    /** Paramètres du `baseSql` (ex. `{ projectId }`) — obligatoire pour les modèles multi-tenant. */
+    context?: Record<string, unknown>;
+    vocabulary?: NlVocabulary;
+    /** Force le modèle (l'UI le connaît quand l'utilisateur est dans un onglet). */
+    model?: string;
+    /** Limite par défaut appliquée à toute requête compilée. */
+    limit?: number;
+    /** En dessous de ce seuil, aucune requête n'est produite. */
+    minimumConfidence?: number;
+    /** Horloge injectable pour les plages relatives (tests). */
+    now?: Date;
+}
+export interface NlMatched {
+    model: string;
+    metrics: string[];
+    dimensions: string[];
+    filters: QueryFilter[];
+    timeRange: {
+        from: string;
+        to: string;
+        label: string;
+    } | null;
+}
+export type NlFailureReason = "no_model" | "no_metric" | "ambiguous_metric" | "low_confidence" | "compilation_failed";
+export type NlToSqlResult = {
+    ok: true;
+    question: string;
+    matched: NlMatched;
+    query: SemanticQuery;
+    compiled: CompiledQuery;
+    confidence: number;
+    explanation: string[];
+} | {
+    ok: false;
+    question: string;
+    reason: NlFailureReason;
+    message: string;
+    suggestions: string[];
+};
+/** Retire les accents et la ponctuation, minuscule. */
+export declare function normalizeNlText(text: string): string;
+export declare function tokenizeNlText(text: string): string[];
+interface TimeRangeMatch {
+    from: string;
+    to: string;
+    label: string;
+}
+/** Détecte une plage relative (derniers N jours, aujourd'hui, ce mois…). */
+export declare function detectTimeRange(text: string, now: Date): TimeRangeMatch | null;
+/**
+ * Compile une question en langage naturel vers une requête sémantique, puis
+ * vers du SQL paramétré. Ne lève pas pour une question non comprise : renvoie
+ * un résultat `ok: false` avec des suggestions.
+ */
+export declare function compileNaturalLanguage(question: string, options: NlToSqlOptions): Promise<NlToSqlResult>;
+export {};

package/dist/omnisend-sync-engine.d.ts

@@ -0,0 +1,31 @@
+export interface OmnisendContactInput {
+    email: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    tags?: string[];
+    zeroPartyAnswers?: Record<string, unknown>;
+    couponCode?: string;
+    sendWelcomeEmail?: boolean;
+}
+export interface OmnisendContactPayload {
+    email: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    status: "subscribed" | "nonSubscribed";
+    statusDate: string;
+    tags: string[];
+    customProperties: Record<string, unknown>;
+    sendWelcomeEmail?: boolean;
+}
+export declare class OmnisendSyncEngine {
+    /**
+     * Normalise le numéro de téléphone au format E.164.
+     */
+    static normalizePhoneNumber(phone?: string): string | undefined;
+    /**
+     * Construit le payload officiel de contact pour l'API Omnisend v3 (POST /v3/contacts).
+     */
+    static buildContactPayload(input: OmnisendContactInput): OmnisendContactPayload;
+}

package/dist/openreplay-adapted/clickmap-adapted.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/mouse.ts
+ * ClickMapRenderer + DOM inspector for LynxSEO session replay.
+ */
+export interface ClickMapCell {
+    x: number;
+    y: number;
+    count: number;
+    element: Element | null;
+    selector: string;
+}
+export declare function generateClickMap(points: {
+    x: number;
+    y: number;
+    target: Element | null;
+}[], gridWidth?: number, gridHeight?: number): ClickMapCell[];

package/dist/openreplay-adapted/console-adapted.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/console.ts (181 lines)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ * Not distributed with LynxSEO's AGPL build; kept in private local build per provenance-guard.
+ */
+export interface ConsoleTrackerOptions {
+    consoleMethods: string[] | null;
+    consoleThrottling: number;
+}
+export declare const consoleMethods: readonly ["log", "info", "warn", "error", "debug", "assert"];
+export declare function formatConsoleArgs(args: unknown[]): string;
+export declare function patchConsole(context: Window & typeof globalThis, sendLog: (level: string, msg: string) => void, opts?: Partial<ConsoleTrackerOptions>): () => void;

package/dist/openreplay-adapted/exception-adapted.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/exception.ts (106 lines)
+ */
+export interface StackFrame {
+    fileName?: string;
+    functionName?: string;
+    line?: number;
+    column?: number;
+    source?: string;
+}
+export interface ExceptionDetail {
+    message: string;
+    stack: StackFrame[];
+    timestamp: number;
+}
+export declare function parseStack(stackString: string): StackFrame[];
+export declare function formatException(err: Error): ExceptionDetail;

package/dist/openreplay-adapted/feature-flags-adapted.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/ee/feature_flags.ts
+ * Feature flags with user segmentation / percentage rollout.
+ */
+export interface FeatureFlagOptions {
+    targetingSegments?: string[];
+    defaultPercentRollout?: number;
+    percentageRolloutPerSegment?: Record<string, number>;
+    enableOn?: (environment?: string) => boolean;
+    disableOn?: (environment?: string) => boolean;
+}
+export interface FlagEvaluation {
+    enabled: boolean;
+    reasons: string[];
+}
+export declare function evaluateFeatureFlag(flagName: string, options: FeatureFlagOptions, userContext?: {
+    segment?: string;
+    environment?: string;
+}): FlagEvaluation;

package/dist/openreplay-adapted/input-adapted.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/input.ts (311 lines)
+ */
+export interface InputTrackerOptions {
+    maskInputs?: boolean;
+    maskInputsReg?: RegExp;
+    captureText?: boolean;
+}
+export declare enum MaskType {
+    Plain = "plain",
+    Obscured = "obscured",
+    Hidden = "hidden"
+}
+export declare function getMaskType(el: HTMLInputElement | HTMLTextAreaElement): MaskType;
+export declare function maskInputValue(value: string, maskType: MaskType): string | null;

package/dist/openreplay-adapted/integrations-adapted.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copied and adapted from OpenReplay (AGPLv3)
+ * Source: inspiration/openreplay/ee/api/routers/core.py (Sentry / Datadog / Slack integrations)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ */
+export interface IntegrationConfig {
+    service: 'sentry' | 'datadog' | 'slack';
+    apiKey: string;
+    endpoint?: string;
+    projectId?: string;
+}
+export interface IntegrationEvent {
+    eventType: 'error' | 'performance' | 'session' | 'metric';
+    payload: Record<string, unknown>;
+    timestamp: number;
+}
+export declare function sendToSentry(config: IntegrationConfig, event: IntegrationEvent): Promise<{
+    ok: boolean;
+    id?: string;
+    error?: string;
+}>;
+export declare function sendToDatadog(config: IntegrationConfig, event: IntegrationEvent): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+export declare function sendToSlack(config: IntegrationConfig, event: IntegrationEvent): Promise<{
+    ok: boolean;
+    error?: string;
+}>;

package/dist/openreplay-adapted/mouse-adapted.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/mouse.ts (465 lines)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ */
+export interface MouseTrackerOptions {
+    captureMouse: boolean;
+}
+export interface MouseEventPoint {
+    x: number;
+    y: number;
+    target: Element | null;
+    targetTag: string;
+    targetId: string;
+    targetClasses: string[];
+    targetText: string;
+}
+export declare function getCSSPath(el: Element | null): string;
+export declare function captureMousePoint(e: MouseEvent): MouseEventPoint;

package/dist/openreplay-adapted/network-adapted.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/network.ts (368 lines)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ * Not distributed with LynxSEO's AGPL build; kept in private local build per provenance-guard.
+ */
+export interface NetworkTrackerOptions {
+    failuresOnly: boolean;
+    ignoreHeaders: string[];
+    capturePayload: boolean;
+    sessionTokenHeader: string | false;
+    useProxy: boolean;
+}
+export interface RequestResponseData {
+    readonly status: number;
+    readonly method: string;
+    url: string;
+    request: {
+        headers: Record<string, string>;
+        body: string | null;
+    };
+    response: {
+        headers: Record<string, string>;
+        body: any;
+    };
+}
+export declare function isIgnoredHeader(header: string, ignoreList: string[]): boolean;
+export declare function cloneRequestData(req: Request): RequestResponseData;

package/dist/openreplay-adapted/performance-adapted.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/performance.ts (144 lines)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ */
+export interface PerformanceTrackerOptions {
+    capturePerformance: boolean;
+}
+export declare const deviceMemory: number;
+export declare const jsHeapSizeLimit: number;
+export declare function computeSpeedIndex(firstContentfulPaint: number, paintBlocks: PaintBlock[]): number;
+interface PaintBlock {
+    time: number;
+    area: number;
+}
+export {};

package/dist/openreplay-adapted/sourcemap-uploader-adapted.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copied and adapted from OpenReplay (AGPLv3)
+ * Source: inspiration/openreplay/sourcemap-uploader/ (sourcemap-uploader module)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ */
+export interface SourcemapUploaderOptions {
+    /** API endpoint for upload */
+    endpoint?: string;
+    /** Project ID for the sourcemap */
+    projectId: string;
+    /** Authentication token */
+    token?: string;
+    /** Release/version identifier */
+    release: string;
+}
+export interface UploadResult {
+    success: boolean;
+    id?: string;
+    error?: string;
+}
+export declare function uploadSourcemap(file: File, options: SourcemapUploaderOptions): Promise<UploadResult>;
+export declare function uploadSourcemapBatch(files: File[], options: SourcemapUploaderOptions): Promise<UploadResult[]>;

package/dist/openreplay-adapted/sourcemapreader-adapted.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copied and adapted from OpenReplay (AGPLv3)
+ * Source: inspiration/openreplay/sourcemapreader/ (sourcemapreader module)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ */
+export interface SourcemapReaderOptions {
+    /** Maximum file size to read (bytes) */
+    maxFileSize?: number;
+    /** Maximum depth for nested sources */
+    maxDepth?: number;
+}
+export interface SourcemapFile {
+    version: string;
+    file: string;
+    sources: {
+        url: string;
+        hash: string;
+        text: string;
+    }[];
+}
+export declare function parseSourcemap(content: string): SourcemapFile | null;
+export declare function getSourceFromSourcemap(sourcemap: SourcemapFile, sourceUrl: string): string | null;

package/dist/openreplay-adapted/state-adapted.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copied and adapted from OpenReplay tracker (AGPLv3)
+ * Source: inspiration/openreplay/tracker/tracker/src/main/modules/ (state store capture - Redux/Vuex/MobX/Zustand equivalent)
+ * Original licenses preserved — see AGENTS.md §8 and THIRD_PARTY_LICENSES.md
+ */
+export interface StateTrackerOptions {
+    captureRedux?: boolean;
+    captureVuex?: boolean;
+    captureMobX?: boolean;
+    captureZustand?: boolean;
+    maxPayloadSize?: number;
+}
+export interface StateSnapshot {
+    timestamp: number;
+    store: string;
+    keys: string[];
+    payload: Record<string, unknown>;
+}
+export declare function initStateTracker(opts?: Partial<StateTrackerOptions>): () => void;
+export declare function takeStateSnapshot(store: string, state: Record<string, unknown>): StateSnapshot;

package/dist/openserp-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 🌐 OpenSERP Client — Free, Zero-Cost Multi-Engine SERP Scraper
+ *
+ * Provides a resilient search client querying Google, Bing, Baidu, DuckDuckGo
+ * without requiring paid API keys or per-search quotas.
+ */
+export interface OpenSerpResultItem {
+    rank: number;
+    title: string;
+    url: string;
+    description: string;
+}
+export declare const OPENSERP_ENGINES: readonly ["google", "bing", "duckduckgo", "baidu", "ecosia", "yandex"];
+export type OpenSerpEngine = (typeof OPENSERP_ENGINES)[number];
+export interface OpenSerpOptions {
+    engine?: OpenSerpEngine;
+    limit?: number;
+    language?: string;
+    timeoutMs?: number;
+    /**
+     * Unwrap redirect links (`/url?q=`, `adurl`) into final destination URLs.
+     * `true` resolves every result, a number resolves the top N. Google only.
+     */
+    resolveUrls?: boolean | number;
+}
+export declare class OpenSerpClient {
+    private baseUrl;
+    constructor(baseUrl?: string);
+    /**
+     * A self-hosted instance can switch an engine off with `OPENSERP_<ENGINE>_DISABLED`
+     * or `<engine>.disabled` in its config; the client mirrors that so a disabled
+     * engine never burns a request and a retry slot.
+     */
+    isEngineDisabled(engine: OpenSerpEngine): boolean;
+    availableEngines(): OpenSerpEngine[];
+    /**
+     * Checks if the OpenSERP server instance is reachable.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Executes a search query on the selected search engine via OpenSERP.
+     */
+    search(query: string, options?: OpenSerpOptions): Promise<OpenSerpResultItem[]>;
+    /**
+     * Executes a Megasearch across multiple search engines concurrently.
+     */
+    megasearch(query: string, engines?: OpenSerpEngine[], limit?: number, options?: Pick<OpenSerpOptions, "resolveUrls" | "language" | "timeoutMs">): Promise<OpenSerpResultItem[]>;
+}

package/dist/page-delivery-auditor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Page delivery audit for the parts that are invisible in Lighthouse:
+ * resource hints (preload/preconnect), Speculation Rules validity and the
+ * signals that make a document ineligible for the back/forward cache.
+ */
+export type DeliveryCheckStatus = "pass" | "warn" | "fail" | "info";
+export interface DeliveryAuditInput {
+    url: string;
+    html: string;
+    headers?: Record<string, string>;
+}
+export interface DeliveryCheck {
+    id: string;
+    label: string;
+    status: DeliveryCheckStatus;
+    message: string;
+    recommendation?: string;
+}
+export interface DeliveryAuditResult {
+    url: string;
+    score: number;
+    grade: "good" | "needs_work" | "poor";
+    checks: DeliveryCheck[];
+    stats: {
+        preloads: number;
+        preconnects: number;
+        renderBlockingScripts: number;
+        speculationRules: boolean;
+    };
+}
+export declare function auditPageDelivery(input: DeliveryAuditInput): DeliveryAuditResult;

package/dist/page-snapshotter.d.ts

@@ -0,0 +1,41 @@
+export interface SnapshotOptions {
+    fullPage?: boolean;
+    width?: number;
+    height?: number;
+    format?: "png" | "jpeg" | "webp";
+    quality?: number;
+    timeoutMs?: number;
+    browserEndpoint?: string;
+    authToken?: string;
+}
+export interface ScreenshotResult {
+    success: boolean;
+    url: string;
+    dataUri?: string;
+    buffer?: Uint8Array;
+    contentType: string;
+    width: number;
+    height: number;
+    capturedAt: string;
+    error?: string;
+}
+export interface PdfResult {
+    success: boolean;
+    url: string;
+    dataUri?: string;
+    buffer?: Uint8Array;
+    pageCount?: number;
+    capturedAt: string;
+    error?: string;
+}
+export declare class PageSnapshotter {
+    /**
+     * Captures a screenshot of the specified web page.
+     * Leverages remote CDP / Browserless / Cloudflare Browser Rendering API or custom gateway.
+     */
+    static captureScreenshot(url: string, options?: SnapshotOptions): Promise<ScreenshotResult>;
+    /**
+     * Generates a printable PDF of the target web page.
+     */
+    static capturePdf(url: string, options?: SnapshotOptions): Promise<PdfResult>;
+}

package/dist/parasite-seo-detector.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 🦠 ParasiteSeoDetector — Site Reputation Abuse & Parasite SEO Risk Scanner
+ *
+ * Follows Google Search Central 2024-2026 policy on reputation abuse.
+ *
+ * Google's Site Reputation Abuse policy states:
+ * "No amount of first-party involvement alters the third-party nature of a section."
+ *
+ * Scans pages and subfolders for 3 critical parasite signals:
+ * 1. Third-party authorship density (Sponsored bylines, "Brand Studio", "Partenaire")
+ * 2. Commercial / Affiliate intent skew on editorial domains (affiliate parameters, coupon tables)
+ * 3. Topical drift: sections deviating sharply from the site's primary authority corpus
+ *    (e.g. casino, payday loans, crypto signals on a news or university domain)
+ */
+export interface ParasiteSignalMatch {
+    signalType: "third_party_authorship" | "affiliate_skew" | "topical_drift";
+    description: string;
+    matchesCount: number;
+    sampleEvidence: string[];
+}
+export interface ParasiteRiskReport {
+    url: string;
+    subfolder: string;
+    riskLevel: "low" | "medium" | "high";
+    isReputationAbuseLikely: boolean;
+    isParasiteRisk: boolean;
+    score: number;
+    riskScore: number;
+    signals: ParasiteSignalMatch[];
+    detectedAffiliateDomains: string[];
+    recommendations: string[];
+}
+export declare class ParasiteSeoDetector {
+    private static readonly SPONSORED_BYLINES_REGEX;
+    private static readonly AFFILIATE_PARAM_REGEX;
+    private static readonly HIGH_RISK_TOPICS_REGEX;
+    /**
+     * Scans a webpage or subfolder for Parasite SEO & Site Reputation Abuse indicators.
+     */
+    static scan(params: {
+        url: string;
+        html: string;
+        primarySiteCorpus?: string;
+    }): ParasiteRiskReport;
+    /**
+     * Alias / flexible parameter evaluator for Parasite SEO detection.
+     */
+    static evaluate(params: {
+        hostDomain?: string;
+        pageUrl?: string;
+        url?: string;
+        pageTitle?: string;
+        pageContent?: string;
+        html?: string;
+        outboundLinks?: string[];
+        hostCoreTopics?: string[];
+        primarySiteCorpus?: string;
+    }): ParasiteRiskReport;
+}

package/dist/period-compare.d.ts

@@ -0,0 +1,34 @@
+/**
+ * G1 — Period Compare / Previous Period
+ *
+ * LynxSEO: PulsePeriodCompare.tsx + ComparativeDatepicker.tsx + DeltaPill
+ * Inspiration: SWETRIX_INSPIRATION_GAP_ANALYSIS.md §4 ligne 136
+ *
+ * NOTE: L'UI du datepicker avec comparePeriod/previousPeriod est documenté
+ * comme "partiel" — les écarts calculés sont affichés via DeltaPill mais
+ * le composant datepicker native manquant l'état previousPeriod.
+ */
+import { z } from "zod";
+/** Schema for period comparison configuration */
+export declare const periodCompareSchema: z.ZodObject<{
+    comparePeriod: z.ZodOptional<z.ZodString>;
+    previousPeriod: z.ZodOptional<z.ZodString>;
+    operation: z.ZodDefault<z.ZodEnum<{
+        percent: "percent";
+        delta: "delta";
+        absolute: "absolute";
+    }>>;
+}, z.core.$strip>;
+/** Type for period comparison result */
+export type PeriodCompareResult = {
+    comparePeriod?: string;
+    previousPeriod?: string;
+    delta: number;
+    percentChange: number;
+    operation: "delta" | "percent" | "absolute";
+};
+/** Compute delta between two periods */
+export declare function computePeriodDelta(current: number, previous: number, operation?: "delta" | "percent" | "absolute"): {
+    delta: number;
+    percentChange: number;
+};