@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/persistent-page-store.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 🏛️ Persistent Page Store & Anti-Doorway Page Deduplication (2026 Standards)
+ *
+ * Implements persistent storage (Filesystem JSON / SQLite / DB-agnostic adapter)
+ * for AI-generated Programmatic SEO pages.
+ *
+ * Features:
+ * 1. Persistent Storage (File System JSON & Extensible Adapters)
+ * 2. Deterministic Hash-Modulo Allocation of Master AI Blueprints (Eliminates Duplicate Waste)
+ * 3. Jaccard & Normalized Similarity Guard (< 0.80) to prevent Google Scaled Content Abuse / Doorway Penalties
+ * 4. Microsecond read latency (< 2ms) for Googlebot and Edge SSR
+ */
+import { DragonflyClient } from "./dragonfly-client";
+export interface ProgrammaticPageDocument {
+    slug: string;
+    keyword: string;
+    variantIndex: number;
+    title: string;
+    metaDescription: string;
+    h1: string;
+    bodyMarkdown: string;
+    schemaJson?: Record<string, any>;
+    heroImageKey?: string;
+    status: "published" | "hidden";
+    dupReason?: string;
+    tokensConsumed: number;
+    aiProvider?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MasterVariantBlueprint {
+    variantIndex: number;
+    angle: string;
+    titleFormula: string;
+    hookTemplate: string;
+    coreMarkdownTemplate: string;
+    faqList: Array<{
+        question: string;
+        answer: string;
+    }>;
+    conversionCta: string;
+}
+export interface PageStoreAdapter {
+    getPage(slug: string): Promise<ProgrammaticPageDocument | null>;
+    savePage(page: ProgrammaticPageDocument): Promise<void>;
+    hasPage(slug: string): Promise<boolean>;
+    listPages(limit?: number): Promise<ProgrammaticPageDocument[]>;
+}
+/**
+ * Normalizes text for lexical comparison
+ */
+export declare function normalizeText(text: string): string;
+/**
+ * Calculates Jaccard Lexical Similarity between two text blocks (0.0 to 1.0)
+ * Google SpamBrain flags pages with similarity >= 0.80 as Doorway / Duplicate content.
+ */
+export declare function calculateJaccardSimilarity(textA: string, textB: string): number;
+/**
+ * Deterministically computes a hash integer for any string (e.g. city or service slug)
+ */
+export declare function hashSlug(slug: string): number;
+/**
+ * Default Filesystem JSON Adapter
+ * Stores generated pages under `.lynx-cache/pages/[slug].json`
+ */
+export declare class FileSystemPageStoreAdapter implements PageStoreAdapter {
+    private baseDir;
+    constructor(baseDir?: string);
+    private ensureDirectory;
+    private getFilePath;
+    getPage(slug: string): Promise<ProgrammaticPageDocument | null>;
+    savePage(page: ProgrammaticPageDocument): Promise<void>;
+    hasPage(slug: string): Promise<boolean>;
+    listPages(limit?: number): Promise<ProgrammaticPageDocument[]>;
+}
+/**
+ * In-Memory Adapter for Serverless Edge / Cloudflare Workers testing
+ */
+export declare class MemoryPageStoreAdapter implements PageStoreAdapter {
+    private store;
+    getPage(slug: string): Promise<ProgrammaticPageDocument | null>;
+    savePage(page: ProgrammaticPageDocument): Promise<void>;
+    hasPage(slug: string): Promise<boolean>;
+    listPages(limit?: number): Promise<ProgrammaticPageDocument[]>;
+}
+/**
+ * 🚀 PersistentPageStore Engine
+ *
+ * Orchestrates:
+ * 1. Fetching cached document
+ * 2. Deterministic AI Variant Allocation (hash % variantsCount)
+ * 3. Strict Anti-Duplicate Validation (Jaccard check vs existing corpus)
+ * 4. Permanent Persistence so paid AI generation is never lost
+ */
+export declare class PersistentPageStore {
+    private adapter;
+    constructor(adapter?: PageStoreAdapter);
+    /**
+     * Retrieves or builds and persists a programmatic page
+     */
+    getOrGenerate(params: {
+        slug: string;
+        keyword: string;
+        targetEntitySlug: string;
+        masterBlueprints: MasterVariantBlueprint[];
+        generator: (selectedBlueprint: MasterVariantBlueprint, variantIndex: number) => Promise<{
+            title: string;
+            metaDescription: string;
+            h1: string;
+            bodyMarkdown: string;
+            schemaJson?: Record<string, any>;
+            tokensConsumed?: number;
+            aiProvider?: string;
+        }>;
+    }): Promise<ProgrammaticPageDocument>;
+}
+/**
+ * 🐉 Dragonfly High-Performance Page Store Adapter
+ * Provides ultra-fast persistent storage with sub-millisecond retrieval for programmatic pages.
+ */
+export declare class DragonflyPageStoreAdapter implements PageStoreAdapter {
+    private client;
+    private prefix;
+    constructor(client?: DragonflyClient, prefix?: string);
+    getPage(slug: string): Promise<ProgrammaticPageDocument | null>;
+    savePage(page: ProgrammaticPageDocument): Promise<void>;
+    hasPage(slug: string): Promise<boolean>;
+    listPages(limit?: number): Promise<ProgrammaticPageDocument[]>;
+}

package/dist/pipeline/dlq-manager.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Dead-Letter Queue (DLQ) & Quarantine Management Engine
+ * Clean-room implementation inspirée de PostHog Ingestion DLQ & Kafka Dead-Letter Topics.
+ * Conforme AGPLv3.
+ *
+ * Isole les événements malformés, invalides ou rejetés lors de l'ingestion sans bloquer le pipeline,
+ * enregistre le diagnostic d'erreur, et permet le rejeu individuel ou par lot (1-click replay)
+ * après correction ou rétablissement des destinations.
+ */
+export type QuarantineErrorCategory = "malformed_json" | "schema_violation" | "target_offline" | "rate_limited" | "worker_timeout" | "auth_failure" | "unknown";
+export type QuarantinedStatus = "quarantined" | "reprocessing" | "resolved" | "discarded";
+export interface QuarantinedItem<T = any> {
+    id: string;
+    projectId: string;
+    payload: T;
+    errorCategory: QuarantineErrorCategory;
+    errorMessage: string;
+    errorStack?: string;
+    retryCount: number;
+    maxRetries: number;
+    firstFailedAt: string;
+    lastFailedAt: string;
+    nextRetryAt?: string;
+    status: QuarantinedStatus;
+    metadata?: Record<string, any>;
+    resolvedAt?: string;
+    discardReason?: string;
+}
+export interface QuarantineFilter {
+    projectId?: string;
+    category?: QuarantineErrorCategory;
+    status?: QuarantinedStatus;
+    limit?: number;
+    offset?: number;
+}
+export interface DlqMetrics {
+    totalItems: number;
+    quarantinedCount: number;
+    reprocessingCount: number;
+    resolvedCount: number;
+    discardedCount: number;
+    recoveryRatePct: number;
+    byCategory: Record<QuarantineErrorCategory, number>;
+}
+export interface ReprocessBatchResult {
+    totalProcessed: number;
+    recovered: number;
+    failed: number;
+}
+export declare class DeadLetterQueueManager {
+    private items;
+    /**
+     * Enregistre un événement en quarantaine avec son diagnostic d'échec.
+     */
+    quarantine<T = any>(params: {
+        projectId: string;
+        payload: T;
+        category: QuarantineErrorCategory;
+        error: Error | string;
+        id?: string;
+        maxRetries?: number;
+        metadata?: Record<string, any>;
+    }): QuarantinedItem<T>;
+    /**
+     * Récupère un élément en quarantaine par son ID.
+     */
+    get(id: string): QuarantinedItem | undefined;
+    /**
+     * Liste les éléments en quarantaine selon des filtres.
+     */
+    list(filter?: QuarantineFilter): QuarantinedItem[];
+    /**
+     * Rejoue un événement quarantainé avec un handler asynchrone.
+     * Si succès, passe en 'resolved'. Si échec, incrémente retryCount ou bascule en 'discarded' si maxRetries atteint.
+     */
+    reprocess(id: string, handler: (payload: any) => Promise<boolean>): Promise<{
+        success: boolean;
+        item?: QuarantinedItem;
+    }>;
+    /**
+     * Rejoue un lot d'éléments filtrés.
+     */
+    reprocessBatch(filter: QuarantineFilter, handler: (payload: any) => Promise<boolean>, maxBatchSize?: number): Promise<ReprocessBatchResult>;
+    /**
+     * Défausse manuellement un élément avec une justification.
+     */
+    discard(id: string, reason?: string): boolean;
+    /**
+     * Purge les éléments résolus, défaussés ou expirés.
+     */
+    purge(params?: {
+        olderThanMs?: number;
+        status?: QuarantinedStatus;
+    }): number;
+    /**
+     * Calcule les métriques globales et par catégorie.
+     */
+    getMetrics(projectId?: string): DlqMetrics;
+}

package/dist/pipeline/event-deduplication.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Event Deduplication & Idempotency Buffer — RudderStack Parity
+ *
+ * Élimine les événements en double (retries réseau du SDK, doubles balises GTM,
+ * requêtes concurrentes) à l'entrée du pipeline d'ingestion.
+ *
+ * Règles :
+ * - Déduplication basée sur la clé d'idempotence (`eventId`, `messageId`, `id`).
+ * - Si aucune clé n'est fournie, dérivation d'un hash de contenu déterministe
+ *   sur (eventName, userId/anonymousId, occurredAt, payload canonique).
+ * - Fenêtre glissante avec TTL et éviction LRU pour borner l'empreinte mémoire.
+ */
+export interface DeduplicationConfig {
+    /** Durée de rétention d'une clé en millisecondes (défaut : 1 heure) */
+    ttlMs?: number;
+    /** Nombre maximal de clés en mémoire par projet (défaut : 50 000) */
+    maxEntries?: number;
+    /** Activer le calcul de hash si l'identifiant est absent (défaut : true) */
+    useContentHashFallback?: boolean;
+}
+export interface DeduplicationResult {
+    isDuplicate: boolean;
+    eventId: string;
+    reason: "unique" | "duplicate_event_id" | "duplicate_content_hash";
+    firstSeenAt?: string;
+    ageMs?: number;
+}
+export declare class EventDeduplicator {
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly useFallback;
+    private readonly stores;
+    private readonly stats;
+    constructor(config?: DeduplicationConfig);
+    private getStore;
+    private getStats;
+    /**
+     * Calcule un hash SHA-256 déterministe à partir du contenu d'un événement
+     */
+    computeContentHash(event: Record<string, unknown>): string;
+    /**
+     * Vérifie si un événement a déjà été traité et l'enregistre dans la fenêtre glissante.
+     */
+    checkAndRecord(projectId: string, event: Record<string, unknown>, now?: number): DeduplicationResult;
+    /**
+     * Récupère les métriques de déduplication pour un projet donné.
+     */
+    getProjectMetrics(projectId: string): {
+        totalChecked: number;
+        duplicatesCount: number;
+        duplicateRatePct: number;
+        activeTrackedEvents: number;
+    };
+    /**
+     * Réinitialise le tampon pour un projet ou pour tous les projets.
+     */
+    clear(projectId?: string): void;
+}
+export declare const globalEventDeduplicator: EventDeduplicator;

package/dist/pipeline/event-replay.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Event Stream Replay & Backfill Engine — RudderStack Parity
+ * (Destination Backfilling & Historical Recovery)
+ *
+ * Permet de rejouer des flux d'événements historiques vers une destination :
+ * - Après l'ajout d'une nouvelle destination publicitaire ou data warehouse.
+ * - Après la correction d'une panne ou d'un incident de transport.
+ * - Avec contrôle de débit (rate limiting / batching), rapport d'avancement
+ *   et gestion des échecs individuels sans interruption du lot.
+ */
+import type { CapiConversion, CapiDestinationConfig, PreparedCapiRequest } from "../conversions-api";
+export type ReplayTransport = (request: PreparedCapiRequest) => Promise<{
+    status: number;
+    detail?: string;
+}>;
+export interface ReplayJobConfig {
+    jobId: string;
+    projectId: string;
+    destination: CapiDestinationConfig;
+    batchSize?: number;
+    stopOnConsecutiveErrors?: number;
+}
+export interface ReplayJobProgress {
+    jobId: string;
+    status: "idle" | "running" | "completed" | "aborted" | "failed";
+    totalEvents: number;
+    processedCount: number;
+    deliveredCount: number;
+    skippedCount: number;
+    failedCount: number;
+    startedAt?: string;
+    completedAt?: string;
+    lastError?: string;
+}
+export declare class EventReplayEngine {
+    /**
+     * Exécute un travail de rejeu historique vers une destination donnée.
+     */
+    static runReplayJob(config: ReplayJobConfig, conversions: CapiConversion[], transport: ReplayTransport, onProgress?: (progress: ReplayJobProgress) => void): Promise<ReplayJobProgress>;
+}

package/dist/pipeline/event-sampler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Dynamic Event Sampling & Ingestion Rate Control — RudderStack Parity
+ * (Cost Optimization & Traffic Spike Protection)
+ *
+ * Permet d'échantillonner les flux d'événements à haute fréquence (ex: scroll,
+ * mouse_move, heartbeat) pour maîtriser les coûts de stockage et de destination,
+ * tout en sanctuarisant les conversions critiques (achats, inscriptions, erreurs).
+ *
+ * Fonctionnalités :
+ * - Échantillonnage déterministe par utilisateur (hash de `userId` / `anonymousId`) :
+ *   garantit que les sessions sélectionnées restent complètes et analysables de bout en bout.
+ * - Exemptions d'échantillonnage prioritaires (ex: si conversion avec valeur financière ou erreur).
+ * - Configuration de taux par événement (0.01 = 1%, 0.10 = 10%, 1.0 = 100%).
+ */
+export type SamplingStrategy = "deterministic" | "random";
+export interface SamplingRule {
+    eventName: string | RegExp;
+    /** Taux de conservation entre 0 (0%) et 1 (100%) */
+    sampleRate: number;
+    strategy?: SamplingStrategy;
+    /** Si vrai, tout événement avec value > 0 est toujours conservé */
+    exemptIfHasValue?: boolean;
+    /** Si vrai, tout événement contenant une erreur est toujours conservé */
+    exemptIfError?: boolean;
+}
+export interface SamplerDecision {
+    keep: boolean;
+    sampleRate: number;
+    reason: "exempt_critical_event" | "exempt_value" | "exempt_error" | "sampled_in" | "sampled_out" | "default_pass";
+}
+export declare class EventSampler {
+    private readonly rules;
+    private readonly defaultRate;
+    constructor(rules?: SamplingRule[], defaultRate?: number);
+    private hashToRatio;
+    evaluate(event: Record<string, unknown>): SamplerDecision;
+}

package/dist/pipeline/event-transform-pipeline.d.ts

@@ -0,0 +1,89 @@
+/**
+ * EventTransformPipeline — Pipeline d'ingestion & de transformation temps réel
+ * inspiré de PostHog Hog Functions, Matomo Queued Tracking et RudderStack Transformations.
+ *
+ * Permet d'appliquer des filtres, du nettoyage PII, de la normalisation UTM,
+ * l'enrichissement de propriétés, le renommage de champs, le filtrage conditionnel
+ * et le déclenchement de webhooks sortants sur les flux d'événements analytiques.
+ */
+export interface DropCondition {
+    property: string;
+    operator: "equals" | "not_equals" | "contains" | "greater_than" | "less_than" | "in";
+    value: unknown;
+}
+export interface EventPipelineRule {
+    id: string;
+    name: string;
+    enabled: boolean;
+    triggerEvent: string;
+    action: "scrub_pii" | "normalize_utm" | "filter_bot" | "webhook_forward" | "add_timestamp" | "anonymize_ip" | "regex_redact" | "hash_sha256" | "enrich_properties" | "rename_property" | "drop_if" | "custom_transform";
+    config?: {
+        webhookUrl?: string;
+        scrubKeys?: string[];
+        allowedDomains?: string[];
+        ipField?: string;
+        regexPattern?: string;
+        regexTarget?: string;
+        redactWith?: string;
+        hashFields?: string[];
+        hashPlatform?: "meta" | "tiktok" | "pinterest" | "ga4";
+        enrichProperties?: Record<string, unknown>;
+        renameFrom?: string;
+        renameTo?: string;
+        dropCondition?: DropCondition;
+        transformFn?: (event: Record<string, unknown>) => Record<string, unknown> | null;
+    };
+}
+export interface PipelineExecutionResult {
+    event: Record<string, unknown>;
+    dropped: boolean;
+    actionsTaken: string[];
+    webhooksTriggered: string[];
+}
+export declare class EventTransformPipeline {
+    /**
+     * Clés sensibles masquées par défaut lors du nettoyage PII.
+     */
+    private static readonly DEFAULT_SENSITIVE_KEYS;
+    /**
+     * Évalue une condition de suppression d'événement.
+     */
+    static evaluateDropCondition(event: Record<string, unknown>, cond: DropCondition): boolean;
+    /**
+     * Exécute une suite de règles de pipeline sur un événement.
+     */
+    static process(rawEvent: Record<string, unknown>, rules: EventPipelineRule[]): PipelineExecutionResult;
+    /**
+     * Version asynchrone de l'exécution du pipeline, privilégiant Web Crypto API (`crypto.subtle`)
+     * pour les environnements Edge Runtime / Cloudflare Workers.
+     */
+    static processAsync(rawEvent: Record<string, unknown>, rules: EventPipelineRule[]): Promise<PipelineExecutionResult>;
+    /**
+     * Normalisation selon la spécification de chaque plateforme publicitaire.
+     */
+    static normalizeForPlatform(value: string, platform?: "meta" | "tiktok" | "pinterest" | "ga4"): string;
+    /**
+     * Anonymise une adresse IP (IPv4 -> /24 masqué, IPv6 -> /48 masqué).
+     */
+    static anonymizeIp(ip: string): string;
+    /**
+     * Redaction par expression régulière avec garde anti-ReDoS.
+     */
+    static regexRedact(text: string, pattern: string, redactWith?: string): string;
+    /**
+     * Hachage SHA-256 synchrone via node:crypto.
+     */
+    static hashSha256Sync(value: string): string;
+    /**
+     * Hachage SHA-256 asynchrone compatible Edge Runtime (crypto.subtle) et Node.js.
+     */
+    static hashSha256(value: string): Promise<string>;
+    /**
+     * Masque les champs sensibles dans un événement pour conformité RGPD.
+     */
+    static scrubPii(event: Record<string, unknown>, additionalKeys?: string[]): Record<string, unknown>;
+    /**
+     * Normalise les paramètres UTM en minuscules et sans espaces superflus.
+     */
+    static normalizeUtm(event: Record<string, unknown>): Record<string, unknown>;
+}

package/dist/pipeline/event-watermark-reorderer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Out-of-Order Event Watermarking & Sliding Window Reorderer — RudderStack Parity
+ * (Streaming Watermark & Sequence Alignment)
+ *
+ * Réaligne dans l'ordre chronologique strict les événements arrivant avec de légers
+ * retards réseau (SDK mobile, sendBeacon asynchrone, reprise sur panne) :
+ * - Maintient une marge de filigrane (Watermark Delay, défaut: 5000 ms).
+ * - Émet les événements ordonnés dès que le filigrane a dépassé leur horodatage.
+ * - Détecte et étiquette les événements trop tardifs (Late-arriving data).
+ */
+export interface WatermarkedEvent {
+    id?: string;
+    timestamp: number | string;
+    name: string;
+    payload: Record<string, unknown>;
+    isLate?: boolean;
+}
+export interface ReordererConfig {
+    /** Tolérance de retard en millisecondes pour le filigrane (défaut: 5000 ms) */
+    watermarkDelayMs?: number;
+    /** Capacité maximale de la mémoire tampon avant forçage d'émission */
+    maxBufferSize?: number;
+}
+export declare class EventWatermarkReorderer {
+    private readonly watermarkDelayMs;
+    private readonly maxBufferSize;
+    private buffer;
+    private maxObservedTimeMs;
+    private currentWatermarkMs;
+    constructor(config?: ReordererConfig);
+    /**
+     * Pousse un événement dans le tampon de réordonnancement.
+     * Renvoie l'événement annoté si trop tardif, ou null s'il est mis en tampon normal.
+     */
+    ingest(event: WatermarkedEvent): {
+        buffered: boolean;
+        isLate: boolean;
+    };
+    /**
+     * Extrait et émet tous les événements dont l'horodatage est inférieur ou égal au filigrane actuel,
+     * triés par ordre chronologique strict.
+     */
+    flushEmittableEvents(): WatermarkedEvent[];
+    /**
+     * Force la vidange complète du tampon (ex: fin de lot ou arrêt du worker).
+     */
+    flushAll(): WatermarkedEvent[];
+    getWatermarkMs(): number;
+    getBufferSize(): number;
+}

package/dist/pipeline/payload-compressor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Event Payload Wire Compressor — RudderStack & Segment Parity
+ * (Edge Runtime Compatible GZIP / Deflate Stream Compression)
+ *
+ * Compresse les lots d'événements volumineux à destination des Data Lakes (S3/R2)
+ * et des APIs de conversion par lots (Meta CAPI, Google Ads) :
+ * - Compatible Edge Runtime (Cloudflare Workers, D1) via CompressionStream / DecompressionStream.
+ * - Réduit l'empreinte réseau jusqu'à 85% pour les archives NDJSON et les lots JSON.
+ */
+export type CompressionFormat = "gzip" | "deflate";
+export declare class PayloadCompressor {
+    /**
+     * Compresse une chaîne de caractères (JSON ou NDJSON) en Uint8Array gzippé.
+     */
+    static compressText(text: string, format?: CompressionFormat): Promise<Uint8Array>;
+    /**
+     * Décompresse un flux Uint8Array gzippé en chaîne de caractères.
+     */
+    static decompressToText(compressedBytes: Uint8Array, format?: CompressionFormat): Promise<string>;
+}

package/dist/plugin/custom-dimensions-plugin.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Custom Dimensions Plugin — Matomo "CustomDimensions"
+ *
+ * Gère les dimensions personnalisées (scope visit/action/event) avec extraction par regex.
+ * Jusqu'à 5 dimensions par site.
+ */
+import { DragonflyClient } from "../dragonfly-client";
+import { type LynxSeoPlugin, type PluginManifest, type PluginEvent } from "./types";
+import { type CustomDimensionDef } from "../custom-dimensions";
+export interface CustomDimensionsPluginContext {
+    organizationId: string;
+    siteId?: string;
+    dragonfly: DragonflyClient;
+}
+export declare class CustomDimensionsPlugin implements LynxSeoPlugin {
+    readonly manifest: PluginManifest;
+    private ctx?;
+    enable(ctx: CustomDimensionsPluginContext): Promise<void>;
+    onEvent(event: PluginEvent): Promise<void>;
+    registerDimension(def: Omit<CustomDimensionDef, "id">): number;
+    getDimensions(): CustomDimensionDef[];
+    disable(): Promise<void>;
+}
+export default CustomDimensionsPlugin;

package/dist/plugin/device-detection-plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Device Detection Plugin — Matomo "DevicesDetection"
+ *
+ * Détecte le type d'appareil, OS, navigateur, marque depuis l'User-Agent.
+ * Écoute les événements tracker.visit et attache les infos device.
+ */
+import { DragonflyClient } from "../dragonfly-client";
+import { type LynxSeoPlugin, type PluginManifest, type PluginEvent } from "./types";
+import { type DeviceInfo } from "../device-detection";
+export interface DeviceDetectionPluginContext {
+    organizationId: string;
+    siteId?: string;
+    dragonfly: DragonflyClient;
+}
+export declare class DeviceDetectionPlugin implements LynxSeoPlugin {
+    readonly manifest: PluginManifest;
+    private ctx?;
+    enable(ctx: DeviceDetectionPluginContext): Promise<void>;
+    onEvent(event: PluginEvent): Promise<void>;
+    getDeviceInfo(userAgent: string, screenWidth?: number, screenHeight?: number): DeviceInfo;
+    disable(): Promise<void>;
+}
+export default DeviceDetectionPlugin;

package/dist/plugin/event-bus.d.ts

@@ -0,0 +1,47 @@
+import { DragonflyClient } from "../dragonfly-client";
+import { type PluginEvent, type EventHandler } from "./types";
+export interface EventSubscription {
+    handler: EventHandler;
+    /** Identifiant du plugin propriétaire, pour ne livrer qu'une fois par hit. */
+    pluginId?: string;
+}
+/** Une livraison planifiée : la souscription et la vue qui lui est servie. */
+export interface RoutedDelivery {
+    subscription: EventSubscription;
+    event: PluginEvent;
+}
+export declare class PluginEventBus {
+    private dragonfly;
+    private stream;
+    private group;
+    private consumer;
+    private handlers;
+    private running;
+    constructor(options?: {
+        streamName?: string;
+        groupName?: string;
+        consumerName?: string;
+        dragonfly?: DragonflyClient;
+    });
+    subscribe(eventType: string, handler: EventHandler, pluginId?: string): void;
+    publish(event: PluginEvent): Promise<string>;
+    start(): Promise<void>;
+    stop(): void;
+    recoverPending(minIdleTimeMs?: number): Promise<void>;
+    getHandlerCount(eventType: string): number;
+    /**
+     * Livre un événement à chaque plugin une seule fois : correspondance exacte
+     * (ou joker `tracker.*`) d'abord, puis vue dérivée pour les plugins qui
+     * n'ont pas de souscription exacte. Un handler sans `pluginId` n'est pas
+     * dédupliqué : il reçoit la vue exacte, puis les vues dérivées auxquelles il
+     * s'est abonné.
+     */
+    private dispatch;
+    private deserialize;
+}
+/**
+ * Calcule les livraisons d'un hit sans exécuter les handlers. Extrait de
+ * `dispatch` pour être testable sans Redis Streams : la règle « un plugin, un
+ * événement par hit » reste la même.
+ */
+export declare function routePluginEvent(handlers: ReadonlyMap<string, readonly EventSubscription[]>, event: PluginEvent): RoutedDelivery[];

package/dist/plugin/geoip-plugin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * GeoIP Plugin — Matomo "GeoIp2 / UserCountry"
+ *
+ * Géolocalisation des visiteurs par IP. Écoute les événements tracker.visit
+ * et attache les données de géolocalisation (pays, ville, région, FAI).
+ */
+import { DragonflyClient } from "../dragonfly-client";
+import { type LynxSeoPlugin, type PluginManifest, type PluginEvent } from "./types";
+import { type GeoIPDatabase, type GeoLookupResult } from "../geoip";
+export interface GeoIPPluginContext {
+    organizationId: string;
+    siteId?: string;
+    dragonfly: DragonflyClient;
+    geoIPDB?: GeoIPDatabase;
+}
+export declare class GeoIPPlugin implements LynxSeoPlugin {
+    readonly manifest: PluginManifest;
+    private ctx?;
+    private geoCache;
+    enable(ctx: GeoIPPluginContext): Promise<void>;
+    onEvent(event: PluginEvent): Promise<void>;
+    lookup(ip: string): Promise<GeoLookupResult>;
+    disable(): Promise<void>;
+}
+export default GeoIPPlugin;

package/dist/plugin/heatmap-plugin.d.ts

@@ -0,0 +1,23 @@
+import { DragonflyClient } from "../dragonfly-client";
+import { type LynxSeoPlugin, type PluginManifest, type PluginEvent } from "./types";
+export interface ClickEventPayload {
+    x: number;
+    y: number;
+    pageUrl: string;
+    elementSelector?: string;
+    sessionId?: string;
+}
+export interface HeatmapPluginContext {
+    organizationId: string;
+    siteId?: string;
+    dragonfly: DragonflyClient;
+}
+export declare class HeatmapPlugin implements LynxSeoPlugin {
+    readonly manifest: PluginManifest;
+    private clicks;
+    enable(ctx: HeatmapPluginContext): Promise<void>;
+    onEvent(event: PluginEvent): Promise<void>;
+    getClicks(siteId: string): ClickEventPayload[];
+    reset(siteId: string): Promise<void>;
+}
+export default HeatmapPlugin;