@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/analytics/navigation-menu-depth-click-proximity-auditor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - NavigationMenuDepthClickProximityAuditor
+ * Audits internal link architecture and PageRank equity distribution by classifying link placements
+ * (header navigation, contextual in-body, sidebar, footer boilerplate) and measuring click depth
+ * proximity from the homepage according to the Google Reasonable Surfer model.
+ */
+export type LinkPlacementZone = "header_nav" | "contextual_body" | "sidebar_nav" | "footer_boilerplate";
+export interface PageLinkEquityNode {
+    url: string;
+    clickDepth: number;
+    incomingLinkZoneDistribution: Record<LinkPlacementZone, number>;
+    totalInboundInternalLinks: number;
+    estimatedReasonableSurferScore?: number;
+}
+export interface NavigationDepthDistribution {
+    depth0To1: number;
+    depth2: number;
+    depth3: number;
+    depth4Plus: number;
+}
+export interface DeepPageCrawlRisk {
+    url: string;
+    clickDepth: number;
+    inboundLinks: number;
+    primaryZone: LinkPlacementZone;
+    recommendation: string;
+}
+export interface NavigationClickProximityAuditReport {
+    totalPagesAudited: number;
+    averageClickDepth: number;
+    maxClickDepth: number;
+    depthDistribution: NavigationDepthDistribution;
+    deepCrawlRiskPages: DeepPageCrawlRisk[];
+    zoneBreakdown: Record<LinkPlacementZone, number>;
+    architectureHealthScore: number;
+    summary: string;
+}
+export declare class NavigationMenuDepthClickProximityAuditor {
+    audit(nodes: PageLinkEquityNode[]): NavigationClickProximityAuditReport;
+}

package/dist/analytics/navigation-timing-engine.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Navigation Timing Engine
+ * Clean-room implementation inspired by Matomo PagePerformance & W3C Navigation Timing API (Level 1 & 2).
+ * Computes exact phase latencies: DNS, TCP, SSL, TTFB, Download, DOM Processing, Load Event,
+ * and identifies the critical path bottleneck.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface NavigationTimingRaw {
+    navigationStart?: number;
+    domainLookupStart: number;
+    domainLookupEnd: number;
+    connectStart: number;
+    secureConnectionStart?: number;
+    connectEnd: number;
+    requestStart: number;
+    responseStart: number;
+    responseEnd: number;
+    domInteractive: number;
+    domContentLoadedEventStart?: number;
+    domContentLoadedEventEnd?: number;
+    domComplete: number;
+    loadEventStart: number;
+    loadEventEnd: number;
+}
+export type BottleneckType = 'dns' | 'tcp' | 'backend_ttfb' | 'content_download' | 'dom_processing' | 'optimal';
+export interface NavigationTimingBreakdown {
+    dnsMs: number;
+    tcpMs: number;
+    sslMs: number;
+    ttfbMs: number;
+    downloadMs: number;
+    domProcessingMs: number;
+    loadEventMs: number;
+    totalPageLoadMs: number;
+    criticalPathBottleneck: BottleneckType;
+}
+export interface AggregatedNavigationTimingStats {
+    samplesCount: number;
+    averages: {
+        dnsMs: number;
+        tcpMs: number;
+        sslMs: number;
+        ttfbMs: number;
+        downloadMs: number;
+        domProcessingMs: number;
+        totalPageLoadMs: number;
+    };
+    p50TotalLoadMs: number;
+    p75TotalLoadMs: number;
+    p90TotalLoadMs: number;
+    p99TotalLoadMs: number;
+    bottleneckPercentages: Record<BottleneckType, number>;
+}
+export declare class NavigationTimingEngine {
+    /**
+     * Computes individual timing breakdown and determines the principal bottleneck
+     */
+    static computeBreakdown(raw: NavigationTimingRaw): NavigationTimingBreakdown;
+    /**
+     * Aggregates a batch of breakdown samples into percentiles and bottleneck breakdown
+     */
+    static computeAggregatedStats(breakdowns: NavigationTimingBreakdown[]): AggregatedNavigationTimingStats;
+}

package/dist/analytics/network-information-tracker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Network Information Tracker
+ * Clean-room implementation inspired by OpenReplay connection tracking & RUM Network Information API.
+ * Tracks client connection parameters (effectiveType, downlink, rtt, saveData),
+ * computes connection quality scores, and flags performance bottlenecks.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export type EffectiveConnectionType = '4g' | '3g' | '2g' | 'slow-2g' | 'unknown';
+export interface NetworkInformationSample {
+    effectiveType: EffectiveConnectionType;
+    downlinkMbps: number;
+    rttMs: number;
+    saveData: boolean;
+    timestamp: number;
+}
+export interface NetworkQualityReport {
+    samplesCount: number;
+    predominantType: EffectiveConnectionType;
+    distribution: Record<EffectiveConnectionType, number>;
+    avgDownlinkMbps: number;
+    avgRttMs: number;
+    saveDataPercentage: number;
+    qualityScore: number;
+    bottleneckFlag: boolean;
+}
+export declare class NetworkInformationTracker {
+    /**
+     * Normalizes raw connection strings into strict EffectiveConnectionType
+     */
+    static normalizeEffectiveType(rawType?: string | null): EffectiveConnectionType;
+    /**
+     * Evaluates an individual sample's quality score (0 - 100)
+     */
+    static scoreSample(sample: NetworkInformationSample): number;
+    /**
+     * Aggregates multiple samples into a comprehensive NetworkQualityReport
+     */
+    static generateReport(samples: NetworkInformationSample[]): NetworkQualityReport;
+}

package/dist/analytics/network-sanitizer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * NetworkSanitizer & GraphQL Inspector Engine
+ *
+ * Implements HTTP request/response sanitization for session replay and APM monitoring.
+ * Masks sensitive authorization tokens, cookies, passwords, and PII in request/response bodies.
+ * Extracts GraphQL operation name, query type (query, mutation, subscription), and variables.
+ * Parity with OpenReplay Network Plugin & PostHog Network Inspector.
+ *
+ * Clean-room implementation under AGPL-3.0-or-later.
+ */
+export interface NetworkRequestInput {
+    requestId: string;
+    url: string;
+    method: string;
+    status?: number;
+    durationMs?: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    responseBody?: unknown;
+}
+export interface SanitizedNetworkEntry {
+    requestId: string;
+    url: string;
+    method: string;
+    status: number;
+    durationMs: number;
+    requestHeaders: Record<string, string>;
+    responseHeaders: Record<string, string>;
+    requestBody: unknown;
+    responseBody: unknown;
+    graphQl?: {
+        isGraphQl: boolean;
+        operationType?: 'query' | 'mutation' | 'subscription';
+        operationName?: string;
+    };
+}
+export declare class NetworkSanitizer {
+    private static readonly SENSITIVE_HEADERS;
+    private static readonly CREDIT_CARD_REGEX;
+    private static readonly EMAIL_REGEX;
+    private static readonly PHONE_REGEX;
+    static sanitizeHeaders(headers?: Record<string, string>): Record<string, string>;
+    static sanitizeStringPayload(raw: string): string;
+    static sanitizeBody(body?: unknown): unknown;
+    private static sanitizeObjectPayload;
+    static inspectGraphQl(url: string, body: unknown): {
+        isGraphQl: boolean;
+        operationType?: 'query' | 'mutation' | 'subscription';
+        operationName?: string;
+    };
+    static sanitizeRequest(input: NetworkRequestInput): SanitizedNetworkEntry;
+}

package/dist/analytics/network-waterfall-analyzer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * LynxSEO Engine - Client Network Waterfall & API Latency Analyzer
+ *
+ * Inspects client-side Fetch/XHR network calls, error distributions,
+ * latency percentiles (p50, p95, p99), and correlation with drop-offs.
+ * (Parity: OpenReplay NetworkProxy & PostHog Network Performance).
+ */
+export interface NetworkCallEntry {
+    id: string;
+    sessionId: string;
+    url: string;
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+    status: number;
+    durationMs: number;
+    transferSize?: number;
+    initiatorType: "fetch" | "xmlhttprequest" | "beacon";
+    timestamp: string;
+}
+export interface EndpointMetricSummary {
+    endpoint: string;
+    method: string;
+    totalCalls: number;
+    errorCount: number;
+    errorRate: number;
+    avgDurationMs: number;
+    p50DurationMs: number;
+    p95DurationMs: number;
+    p99DurationMs: number;
+    avgTransferSizeBytes: number;
+}
+export interface NetworkPerformanceReport {
+    totalCalls: number;
+    totalErrors: number;
+    overallErrorRate: number;
+    avgDurationMs: number;
+    slowestEndpoints: EndpointMetricSummary[];
+    highestErrorEndpoints: EndpointMetricSummary[];
+    statusCodesDistribution: Record<string, number>;
+}
+export declare class NetworkWaterfallAnalyzer {
+    private calls;
+    constructor(initialCalls?: NetworkCallEntry[]);
+    recordCall(call: NetworkCallEntry): void;
+    recordBatch(calls: NetworkCallEntry[]): void;
+    /**
+     * Normalizes URLs into endpoints (strips query parameters and IDs).
+     */
+    normalizeEndpoint(rawUrl: string): string;
+    /**
+     * Generates a comprehensive network performance and error report.
+     */
+    generateReport(): NetworkPerformanceReport;
+    private getPercentile;
+}

package/dist/analytics/offline-event-reconciler.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OfflineEventReconciler — Réconciliation d'événements hors-ligne (Matomo & RudderStack Offline Sync Parity)
+ *
+ * Gère l'ingestion asynchrone des événements différés collectés lors de pertes de connectivité (PWA, Mobile, Voyage) :
+ * - Calcul du décalage d'horloge client/serveur (clock skew reconciliation)
+ * - Correction précise de l'horodatage des événements historiques
+ * - Déduplication idempotente via clé d'idempotence ou empreinte synthétique
+ * - Élimination des événements obsolètes dépassant la fenêtre maximale de rétention
+ * - Réordonnancement chronologique strict.
+ */
+export interface QueuedOfflineEvent {
+    id?: string;
+    idempotencyKey?: string;
+    name: string;
+    visitorId: string;
+    clientTimestamp: number;
+    properties?: Record<string, unknown>;
+}
+export interface OfflineBatchInput {
+    clientBatchSentAt: number;
+    events: QueuedOfflineEvent[];
+}
+export interface ReconciledEvent {
+    id: string;
+    name: string;
+    visitorId: string;
+    originalClientTimestamp: number;
+    correctedTimestamp: number;
+    skewAppliedMs: number;
+    properties?: Record<string, unknown>;
+}
+export interface ReconciliationReport {
+    serverReceivedAt: number;
+    clockSkewMs: number;
+    totalReceived: number;
+    reconciledCount: number;
+    discardedStaleCount: number;
+    duplicateCount: number;
+    events: ReconciledEvent[];
+}
+export interface ReconcilerOptions {
+    maxRetentionMs?: number;
+    knownEventIds?: Set<string>;
+}
+export declare class OfflineEventReconciler {
+    static readonly DEFAULT_MAX_RETENTION_MS: number;
+    /**
+     * Génère une clé d'idempotence synthétique pour un événement
+     */
+    private static generateSyntheticKey;
+    /**
+     * Réconcilie un lot d'événements offline
+     */
+    static reconcile(batch: OfflineBatchInput, options?: ReconcilerOptions, serverReceivedAt?: number): ReconciliationReport;
+}

package/dist/analytics/open-graph-social-card-auditor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - OpenGraphSocialCardAuditor
+ * Audits OpenGraph and Twitter Card social metadata for Facebook, Twitter/X,
+ * and LinkedIn sharing compliance, image aspect ratio fidelity, and URL parity.
+ */
+export interface SocialCardInput {
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogUrl?: string;
+    ogType?: string;
+    ogSiteName?: string;
+    twitterCard?: "summary" | "summary_large_image" | "app" | "player" | string;
+    twitterTitle?: string;
+    twitterDescription?: string;
+    twitterImage?: string;
+    twitterSite?: string;
+    twitterCreator?: string;
+    canonicalUrl?: string;
+    imageDimensions?: {
+        width: number;
+        height: number;
+    };
+}
+export type SocialIssueType = "missing_og_title" | "missing_og_description" | "missing_og_image" | "relative_image_url" | "image_below_min_dimensions" | "non_optimal_aspect_ratio" | "missing_twitter_card" | "og_url_canonical_mismatch" | "excessive_title_length";
+export interface SocialAuditFinding {
+    issue: SocialIssueType;
+    severity: "critical" | "warning" | "info";
+    platform: "all" | "facebook" | "twitter" | "linkedin";
+    description: string;
+    recommendation: string;
+}
+export interface SocialAuditReport {
+    score: number;
+    isValidForSharing: boolean;
+    findings: SocialAuditFinding[];
+    previews: {
+        facebook: {
+            title: string;
+            description: string;
+            imageUrl?: string;
+            cardType: "large_preview" | "small_preview" | "fallback";
+        };
+        twitter: {
+            title: string;
+            description: string;
+            imageUrl?: string;
+            cardType: string;
+        };
+    };
+    recommendedMetaSnippet: string;
+}
+export declare class OpenGraphSocialCardAuditor {
+    /**
+     * Audits parsed social tags or an HTML document string.
+     */
+    audit(input: string | SocialCardInput): SocialAuditReport;
+    private extractTagsFromHtml;
+    private normalize;
+}

package/dist/analytics/opengraph-twitter-card-image-dimension-auditor.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - OpenGraphTwitterCardImageDimensionAuditor
+ * Audits Open Graph and Twitter Card social sharing images for dimension compliance,
+ * 1.91:1 aspect ratio, accessibility alt text, and minimum resolution requirements.
+ */
+export interface SocialCardMetadataInput {
+    pageUrl: string;
+    ogImage?: string;
+    ogImageWidth?: number;
+    ogImageHeight?: number;
+    ogImageAlt?: string;
+    twitterCard?: "summary" | "summary_large_image" | "app" | "player";
+    twitterImage?: string;
+    fileSizeBytes?: number;
+}
+export type SocialCardIssueSeverity = "critical" | "warning" | "notice";
+export interface SocialCardIssue {
+    platform: "facebook_og" | "twitter_x" | "both";
+    severity: SocialCardIssueSeverity;
+    issueCode: string;
+    message: string;
+    recommendation: string;
+}
+export interface SocialCardAuditReport {
+    pageUrl: string;
+    hasOgImage: boolean;
+    hasTwitterImage: boolean;
+    dimensionsFound: {
+        width: number | null;
+        height: number | null;
+    };
+    aspectRatio: number | null;
+    cardQualityScore: number;
+    issues: SocialCardIssue[];
+    recommendedMarkupSnippet: string;
+}
+export declare class OpenGraphTwitterCardImageDimensionAuditor {
+    /**
+     * Audits social card image dimensions and metadata tags.
+     */
+    audit(input: SocialCardMetadataInput): SocialCardAuditReport;
+}

package/dist/analytics/orphan-page-rescue-linker.d.ts

@@ -0,0 +1,66 @@
+/**
+ * OrphanPageRescueLinker — Reconnexion Automatisée & Transfert d'Autorité pour Pages Orphelines
+ *
+ * Parité : OnCrawl (Orphan Page Recovery & Inrank Flow), Sitebulb (Internal Link Opportunities).
+ *
+ * Résout le problème critique des pages orphelines (pages présentes dans les sitemaps ou les logs
+ * mais ne recevant AUCUN lien interne du site, causant leur désindexation par Google) :
+ *
+ * 1. Appariement Sémantique & Topologique :
+ *    - Compare les pages orphelines avec les pages donatrices à fort PageRank interne (Hubs / Authorities).
+ *    - Calcule un score de pertinence thématique combiné (Similarité Jaccard des mots-clés,
+ *      proximité d'arborescence d'URL, concordance de catégorie).
+ * 2. Génération de Recommandations de Liens Précises :
+ *    - URL Donatrice optimale (Source) et URL Orpheline (Cible).
+ *    - Ancre de texte suggérée (naturelle, exacte, sémantique).
+ *    - Emplacement DOM recommandé (corps d'article éditorial `<article>` vs bloc "Articles liés").
+ * 3. Projection d'Impact SEO :
+ *    - Gain estimé de PageRank interne.
+ *    - Probabilité de réindexation et récupération du crawl.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface OrphanPageInput {
+    url: string;
+    title: string;
+    category?: string;
+    keywords?: string[];
+}
+export interface DonorPageCandidate {
+    url: string;
+    title: string;
+    category?: string;
+    keywords?: string[];
+    internalPageRank: number;
+    outDegree: number;
+}
+export interface RescueLinkRecommendation {
+    orphanUrl: string;
+    donorUrl: string;
+    donorTitle: string;
+    donorPageRank: number;
+    relevanceScore: number;
+    suggestedAnchorText: string;
+    recommendedPlacement: "editorial_content" | "related_topics_widget" | "category_hub";
+    estimatedPageRankGain: number;
+    priority: "high" | "medium" | "low";
+}
+export interface OrphanRescuePlan {
+    totalOrphansAnalyzed: number;
+    rescuedOrphansCount: number;
+    unmatchedOrphansCount: number;
+    recommendations: RescueLinkRecommendation[];
+    summary: {
+        averageRelevanceScore: number;
+        highPriorityCount: number;
+        projectedTotalPageRankDistributed: number;
+    };
+    generatedAt: string;
+}
+export declare class OrphanPageRescueLinker {
+    generatePlan(orphans: OrphanPageInput[], donors: DonorPageCandidate[]): OrphanRescuePlan;
+    private computeRelevance;
+    private tokenize;
+    private generateAnchorText;
+    private emptyPlan;
+}

package/dist/analytics/page-lifecycle-tracker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Page Lifecycle Tracker
+ *
+ * Implémente l'analyse du cycle de vie de page (W3C Page Lifecycle API).
+ * Distingue le temps de présence active (foreground engagement) du temps passé en arrière-plan
+ * (onglets cachés ou gelés) et détecte les bascules d'onglets et déchargements de mémoire.
+ */
+export type PageLifecycleState = "active" | "passive" | "hidden" | "frozen" | "terminated" | "discarded";
+export interface LifecycleTransitionEvent {
+    fromState?: PageLifecycleState;
+    toState: PageLifecycleState;
+    timestamp: number;
+    type: "visibilitychange" | "focus" | "blur" | "freeze" | "resume" | "pagehide" | "pageshow";
+}
+export interface PageLifecycleSummary {
+    totalSessionDurationMs: number;
+    activeDwellTimeMs: number;
+    passiveDwellTimeMs: number;
+    hiddenDwellTimeMs: number;
+    frozenDwellTimeMs: number;
+    activeRatio: number;
+    tabSwitchCount: number;
+    wasDiscarded: boolean;
+    engagementQuality: "low" | "medium" | "high";
+    stateDurations: Record<PageLifecycleState, number>;
+}
+export declare class PageLifecycleTracker {
+    static summarizeLifecycle(transitions: LifecycleTransitionEvent[], sessionEndTimestamp?: number): PageLifecycleSummary;
+}

package/dist/analytics/pagination-infinite-scroll-auditor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PaginationInfiniteScrollAuditor — Audit SEO Technique de Pagination & Défilement Infini (Infinite Scroll)
+ *
+ * Parité : Screaming Frog & Sitebulb (Pagination Architecture & Infinite Scroll Crawlability).
+ *
+ * Analyse la structure technique des séries paginées (e-commerce, blogs, catalogues) :
+ * 1. Piège Canonique Critique (Page 2+ canonicalisée vers Page 1) :
+ *    - Détecte l'erreur fréquente consistant à pointer le canonical de la page 2 vers la page 1,
+ *      ce qui pousse Google à désindexer tous les produits profonds des pages suivantes.
+ *    - Valide que chaque page paginée possède son propre canonical auto-référent.
+ * 2. Défilement Infini Invisible (Infinite Scroll JS Blindness) :
+ *    - Détecte les flux infinis en JavaScript dépourvus de liens statiques HTML <a href="...">
+ *      ou d'un fallback <nav>, rendant le contenu profond 100% invisible à Googlebot.
+ * 3. Cohérence des Chaînes Rel Next / Prev :
+ *    - Valide la réciprocité logique entre la page N, la page précédente (N-1) et suivante (N+1).
+ * 4. Présence Inappropriée de 'noindex' :
+ *    - Alerte si des pages paginées portent la balise 'noindex', coupant la transmission du PageRank.
+ * 5. Impasses & Liens Brisés de Pagination :
+ *    - Identifie les pages paginées renvoyant des codes 404 / 5xx.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface PaginatedPageNode {
+    url: string;
+    seriesKey: string;
+    pageNumber: number;
+    canonicalUrl?: string | null;
+    relNext?: string | null;
+    relPrev?: string | null;
+    statusCode: number;
+    isInfiniteScroll?: boolean;
+    hasStaticHtmlLinksFallback?: boolean;
+    metaRobots?: string | null;
+}
+export type PaginationIssueSeverity = "critical" | "high" | "medium";
+export interface PaginationIssue {
+    url: string;
+    seriesKey: string;
+    pageNumber: number;
+    type: "canonical_to_root" | "infinite_scroll_unindexable" | "noindex_on_paginated_page" | "broken_pagination_link" | "broken_rel_sequence";
+    severity: PaginationIssueSeverity;
+    description: string;
+    recommendation: string;
+}
+export interface PaginationSeriesSummary {
+    seriesKey: string;
+    totalPagesCount: number;
+    healthScore: number;
+    hasCanonicalToRootIssue: boolean;
+    hasInfiniteScrollIssue: boolean;
+    issuesCount: number;
+}
+export interface PaginationAuditReport {
+    totalPagesAudited: number;
+    totalSeriesAudited: number;
+    overallPaginationScore: number;
+    criticalIssuesCount: number;
+    issues: PaginationIssue[];
+    seriesSummaries: PaginationSeriesSummary[];
+    actionPlan: string[];
+    generatedAt: string;
+}
+export declare class PaginationInfiniteScrollAuditor {
+    audit(pages: PaginatedPageNode[]): PaginationAuditReport;
+    private normalizeUrl;
+    private emptyReport;
+}

package/dist/analytics/parameterized-query-engine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ParameterizedQueryEngine — Moteur de requêtes SQL paramétrées sécurisées (Parité Metabase / Redash SQL Variables).
+ *
+ * Permet aux dashboards personnalisés et aux rapports d'exécuter des requêtes dynamiques sécurisées :
+ * - Remplacement de balises Mustache `{{variable}}` et blocs conditionnels `[[ WHERE condition = {{var}} ]]`
+ * - Typage strict (number, text, date, date_range, enum) avec rejet immédiat des injections
+ * - Génération dialecte D1 (SQLite avec `?`) et Hyperdrive (PostgreSQL avec `$1, $2, ...`)
+ * - Garde-fous en lecture seule : interdiction des mutations (DROP, ALTER, TRUNCATE, UPDATE, DELETE, etc.)
+ * - Injection automatique de LIMIT de sécurité pour éviter les dépassements de mémoire à l'Edge
+ */
+export type QueryParamType = "text" | "number" | "date" | "date_range" | "enum";
+export interface QueryParamDefinition {
+    name: string;
+    type: QueryParamType;
+    required?: boolean;
+    defaultValue?: unknown;
+    allowedValues?: string[];
+    column?: string;
+}
+export type SqlDialect = "sqlite" | "postgres";
+export interface CompileQueryOptions {
+    dialect?: SqlDialect;
+    maxLimit?: number;
+}
+export interface CompiledQuery {
+    rawTemplate: string;
+    sql: string;
+    params: unknown[];
+    dialect: SqlDialect;
+    detectedVariables: string[];
+    hasLimit: boolean;
+    injectedLimit?: number;
+}
+export declare class ParameterizedQueryEngine {
+    /**
+     * Analyse et extrait les variables Mustache `{{variable}}` d'un template SQL.
+     */
+    static extractVariables(template: string): string[];
+    /**
+     * Compile un template SQL avec ses valeurs de paramètres en une requête paramétrée sécurisée.
+     */
+    static compile(template: string, definitions: QueryParamDefinition[], values: Record<string, unknown>, options?: CompileQueryOptions): CompiledQuery;
+}