@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/competitor-pages-generator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 🥊 Competitor Comparison & "X vs Y" Page Generator
+ *
+ * Automatically generates high-ranking, high-converting "X vs Y" and "Alternatives to X"
+ * comparison pages complete with comparison matrices, Product + AggregateRating Schema.org JSON-LD,
+ * conversion-focused CTAs, and FAQ schemas.
+ */
+export interface ComparisonFeature {
+    featureName: string;
+    category: string;
+    productAValue: string | boolean;
+    productBValue: string | boolean;
+    productAWins: boolean;
+    notes?: string;
+}
+export interface VsPageGenerationInput {
+    productA: {
+        name: string;
+        brand: string;
+        rating: number;
+        reviewCount: number;
+        priceStarting: string;
+        keyPros: string[];
+        keyCons: string[];
+    };
+    productB: {
+        name: string;
+        brand: string;
+        rating: number;
+        reviewCount: number;
+        priceStarting: string;
+        keyPros: string[];
+        keyCons: string[];
+    };
+    category: string;
+    features: ComparisonFeature[];
+}
+export interface GeneratedVsPage {
+    metaTitle: string;
+    metaDescription: string;
+    h1: string;
+    verdictSummary: string;
+    schemaJsonLd: Record<string, unknown>;
+    markdownContent: string;
+    htmlTablePreview: string;
+}
+export declare class CompetitorPagesGenerator {
+    /**
+     * Generates a complete "X vs Y" comparison page.
+     */
+    static generateVsPage(input: VsPageGenerationInput): GeneratedVsPage;
+    /**
+     * Generates "Top Alternatives to [Competitor]" page.
+     */
+    static generateAlternativesPage(competitorName: string, category: string, topAlternatives: string[]): {
+        metaTitle: string;
+        h1: string;
+        markdown: string;
+    };
+}

package/dist/content-ai-arsenal.d.ts

@@ -1,7 +1,7 @@
 /**
  * 🪄 LynxSEO Content AI Master Arsenal (40+ Tools & Copywriting Formulas)
  *
- * Provides complete parity and superiority over Rank Math Content AI, Yoast AI, and AIOSEO:
+ * Full-coverage AI content assistance for on-page SEO:
  * - 40+ Dedicated AI Generation Tools
  * - 6 Master Copywriting Formulas (AIDA, PAS, BAB, HERO, SPIN, IDCA)
  * - 1-Click Long-Form Blog Post Wizard

package/dist/content-freshness.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ⚡ Content & Git Freshness Signals Auditor
+ *
+ * Follows Google Search Central freshness guidelines.
+ * Audits and aligns freshness signals across:
+ * 1. JSON-LD schema `dateModified` & `datePublished`.
+ * 2. OpenGraph / Article meta tags (`article:modified_time`, `article:published_time`).
+ * 3. HTTP `Last-Modified` response header.
+ * 4. XML Sitemap `<lastmod>` tag.
+ * 5. On-page visible publication/update dates.
+ *
+ * Detects desynchronization, freshness penalties, future date hallucinations, and stale content.
+ */
+export interface FreshnessSignals {
+    datePublished?: string;
+    dateModified?: string;
+    articleModifiedTime?: string;
+    articlePublishedTime?: string;
+    httpLastModified?: string;
+    sitemapLastmod?: string;
+    visibleDatesFound: string[];
+}
+export interface FreshnessAuditIssue {
+    type: "future_date_detected" | "missing_date_modified" | "freshness_desynchronization" | "stale_content_warning" | "invalid_iso_format";
+    severity: "critical" | "warning" | "info";
+    message: string;
+    recommendation: string;
+}
+export interface FreshnessAuditResult {
+    signals: FreshnessSignals;
+    isConsistent: boolean;
+    effectiveModifiedDate?: string;
+    issues: FreshnessAuditIssue[];
+    freshnessScore: number;
+}
+export declare class ContentFreshnessAuditor {
+    /**
+     * Extracts all date and freshness signals from raw HTML and optional headers/sitemaps.
+     */
+    static extractFreshnessSignals(html: string, options?: {
+        headers?: Record<string, string>;
+        sitemapLastmod?: string;
+    }): FreshnessSignals;
+    /**
+     * Audits consistency and validity across all discovered freshness signals.
+     */
+    static auditFreshness(signals: FreshnessSignals, now?: Date): FreshnessAuditResult;
+}

package/dist/content-humanizer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ✍️ Content Humanizer & AI Text Watermark Stripper
+ *
+ *
+ * 1. Rewrites 45+ AI-typical clichés & filler phrases into clean, authoritative editorial prose:
+ *    - "delve into" -> "explore"
+ *    - "in the ever-evolving landscape of" -> "in"
+ *    - "rich tapestry of" -> "range of"
+ *    - "a testament to" -> "evidence of"
+ *    - "a beacon of" -> "a leader in"
+ *    - "elevate your" -> "improve your"
+ *    - "revolutionize the way" -> "change how"
+ *    - "leverage the power of" -> "use"
+ *    - "game-changer" -> "important"
+ * 2. Strips invisible Unicode watermark artifacts left by AI tools and copy-paste pipelines:
+ *    - Zero-width spaces (\u200B), non-joiners (\u200C), word joiners (\u2060)
+ *    - Directional overrides (\u202A-\u202E, \u2066-\u2069)
+ *    - Unicode tag characters (\uE0000-\uE007F)
+ *    - Preserves legitimate emoji variation selectors and joiners.
+ */
+export interface HumanizeFinding {
+    original: string;
+    replacement: string;
+    label: string;
+    count: number;
+}
+export interface HumanizeResult {
+    cleanedText: string;
+    originalLength: number;
+    cleanedLength: number;
+    clichesReplacedCount: number;
+    watermarksStrippedCount: number;
+    findings: HumanizeFinding[];
+}
+export declare class ContentHumanizer {
+    private static readonly REPLACEMENTS;
+    private static readonly WATERMARK_REGEX;
+    /**
+     * Humanizes text by stripping AI cliches and invisible watermark codepoints.
+     */
+    static humanize(text: string): HumanizeResult;
+    /**
+     * Alias / wrapper for content cleaning and watermark scrubbing.
+     */
+    static analyzeAndClean(text: string, stripInvisibleWatermarks?: boolean): HumanizeResult;
+}

package/dist/content-prune-matrix.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ✂️ Content Quality & Pruning Matrix Engine
+ *
+ * Evidence-based content surgery to recover from Google Core Updates / HCU penalties,
+ * eliminate crawl budget bloat, and protect domain authority.
+ *
+ * Assigns one of 6 decisive actions:
+ * 1. KEEP: Traffic/Conversion leader.
+ * 2. REFRESH: Ranking decay, but active backlinks and search demand.
+ * 3. MERGE_301: Thin/cannibalized page with backlink equity -> 301 to parent pillar.
+ * 4. REWRITE_EEAT: High impressions, low CTR & low Information Gain -> upgrade with data anchors.
+ * 5. NOINDEX: Internal utility or thin programmatic row -> keep for users, hide from Googlebot.
+ * 6. DELETE_410: Zombie page (>12 months, 0 clicks, 0 impressions, 0 links) -> 410 Gone.
+ */
+export interface ContentPruneInputItem {
+    url: string;
+    ageInMonths: number;
+    clicksLast90Days: number;
+    impressionsLast90Days: number;
+    backlinksCount: number;
+    wordCount: number;
+    informationGainScore?: number;
+    hasConversionValue?: boolean;
+    isUtilityPage?: boolean;
+    targetCanonicalUrl?: string;
+}
+export type PruneAction = "KEEP" | "REFRESH" | "MERGE_301" | "REWRITE_EEAT" | "NOINDEX" | "DELETE_410";
+export interface PruneItemDisposition {
+    url: string;
+    action: PruneAction;
+    priority: "CRITICAL_IMMEDIATE" | "HIGH" | "MEDIUM" | "ROUTINE";
+    reason: string;
+    implementationDetail: string;
+    preservesBacklinkEquity: boolean;
+}
+export interface ContentPruneAuditSummary {
+    totalPagesAudited: number;
+    actionBreakdown: Record<PruneAction, number>;
+    crawlBudgetRecoveredPct: number;
+    immediateRiskUrlsCount: number;
+    dispositions: PruneItemDisposition[];
+    executiveActionPlan: string[];
+}
+export declare class ContentPruneMatrixEngine {
+    /**
+     * Evaluates content inventory items and assigns decisive disposition actions.
+     */
+    static evaluateInventory(items: ContentPruneInputItem[]): ContentPruneAuditSummary;
+}

package/dist/content-repurposer.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 📢 Multi-Channel Content Repurposing Engine
+ * Adapts high-ranking SEO articles and pages into native, high-engagement formats:
+ * - LinkedIn Thought Leadership Post
+ * - Twitter / X Thread (1/n)
+ * - Reddit Authentic Community Post (Zero-spam, high value)
+ * - Quora Direct Answer with organic citation
+ * - Medium Syndication Story (with rel="canonical" advice)
+ */
+export interface SourceArticleInput {
+    title: string;
+    topic: string;
+    canonicalUrl: string;
+    summary: string;
+    keyTakeaways: string[];
+    keyDataPoints?: string[];
+    targetAudience?: string;
+    authorName?: string;
+}
+export interface LinkedInRepurposedAsset {
+    hook: string;
+    body: string;
+    bulletPoints: string[];
+    closingQuestion: string;
+    callToAction: string;
+    hashtags: string[];
+    fullPostText: string;
+}
+export interface TwitterThreadAsset {
+    hookTweet: string;
+    threadTweets: string[];
+    closingTweet: string;
+    totalTweets: number;
+    fullThreadText: string;
+}
+export interface RedditCommunityAsset {
+    suggestedSubreddits: string[];
+    postTitle: string;
+    postBody: string;
+    authenticityNotice: string;
+}
+export interface QuoraAnswerAsset {
+    questionPrompt: string;
+    directAnswerSummary: string;
+    detailedPoints: string[];
+    canonicalCitationText: string;
+    fullAnswerText: string;
+}
+export interface MediumDraftAsset {
+    articleTitle: string;
+    subtitle: string;
+    narrativeIntroduction: string;
+    canonicalUrlNotice: string;
+    markdownBody: string;
+}
+export interface RepurposedSuite {
+    topic: string;
+    canonicalUrl: string;
+    linkedin: LinkedInRepurposedAsset;
+    twitter: TwitterThreadAsset;
+    reddit: RedditCommunityAsset;
+    quora: QuoraAnswerAsset;
+    medium: MediumDraftAsset;
+}
+export declare class ContentRepurposer {
+    /**
+     * Repurposes a source article into 5 platform-optimized assets.
+     */
+    static repurpose(article: SourceArticleInput): RepurposedSuite;
+    /**
+     * LinkedIn: High-engagement thought leadership post.
+     */
+    private static buildLinkedInPost;
+    /**
+     * Twitter/X: Compelling thread structure (1/n).
+     */
+    private static buildTwitterThread;
+    /**
+     * Reddit: Authentic community-focused post with zero sales pitch.
+     */
+    private static buildRedditPost;
+    /**
+     * Quora: Direct-answer authority format.
+     */
+    private static buildQuoraAnswer;
+    /**
+     * Medium: Syndicated long-form narrative.
+     */
+    private static buildMediumDraft;
+}

package/dist/content-writer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 📝 Content Writer — Génère du contenu long-form (articles, guides) à partir de plans SEO/AEO.
+ *
+ * Utilise les plans d'article de LongformArticlePlanner + le client LLM (ai-copilot-client)
+ * pour rédiger le corps de l'article.
+ *
+ * Conventions codebase : TypeScript strict, zéro dépendance, pas de `as any`,
+ * pas de `dangerouslySetInnerHTML`, pas de `Math.random()` dans le render.
+ *
+ * Fondements : structuration Answer-First (Princeton KDD 2024).
+ */
+import { LongformSectionPlan } from "./longform-article-planner";
+import { ArticleOutlinePlan } from "./longform-article-planner";
+import { GenerateArticleParams } from "./ai-copilot-client";
+/**
+ * Résultat de génération d'article.
+ */
+export interface GeneratedArticle {
+    title: string;
+    content: string;
+    wordCount: number;
+    sections: LongformSectionPlan[];
+    language: "fr" | "en";
+    keywords: string[];
+    qualityScore: number;
+    generatedAt: string;
+}
+/**
+ * ContentWriter génère un article complet (titre, corps, sections) à partir d'un
+ * plan structuré. Le rédacteur est déterministe : même plan + mêmes paramètres
+ * = même sortie (pas de simulation masquée).
+ */
+export declare class ContentWriter {
+    /**
+     * Génère un article complet à partir d'un plan SEO.
+     *
+     * @param plan Plan d'article structuré (sortie de LongformArticlePlanner)
+     * @param params Paramètres LLM (modèle, ton, langue, temperature)
+     * @returns Article validé, prêt à être publié ou stocké
+     */
+    generateArticle(plan: ArticleOutlinePlan, params: GenerateArticleParams): Promise<GeneratedArticle>;
+    private calculateQualityScore;
+}

package/dist/contextual-auto-linker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Contextual Internal Auto-Linker
+ * Analyse le contenu HTML/Markdown et injecte dynamiquement des liens internes
+ * pertinents vers les pages stratégiques (Topic Clusters) en respectant les bonnes
+ * pratiques SEO (pas de liens dans les titres H1-H6, 1 lien max par paragraphe).
+ */
+export interface TargetLinkRule {
+    targetUrl: string;
+    keywords: string[];
+    maxOccurrencesPerPage?: number;
+}
+export interface AutoLinkOptions {
+    maxLinksTotal?: number;
+    caseSensitive?: boolean;
+}
+export interface AutoLinkResult {
+    modifiedContent: string;
+    linksAddedCount: number;
+    injectedLinks: Array<{
+        keyword: string;
+        targetUrl: string;
+    }>;
+}
+export declare class ContextualAutoLinker {
+    /**
+     * Injecte des liens internes dans du contenu HTML
+     */
+    static injectLinks(htmlContent: string, rules: TargetLinkRule[], options?: AutoLinkOptions): AutoLinkResult;
+    static link(html: string, rules: Array<{
+        keyword: string;
+        targetUrl: string;
+        exactMatchOnly?: boolean;
+        caseSensitive?: boolean;
+        maxInsertions?: number;
+    }>, options?: {
+        maxTotalLinks?: number;
+        openInNewTab?: boolean;
+    }): AutoLinkResult;
+}

package/dist/contextual-internal-linker.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 🔗 Contextual Internal Linker
+ *
+ * Moteur de suggestions de maillage interne contextuel basé sur la similarité
+ * N-gram (1-gram à 3-grams) avec scoring TF-IDF simplifié.
+ *
+ * - Détecte les URLs déjà liées dans le contenu courant
+ * - Calcule la similarité entre le contenu courant et chaque page publiée
+ * - Propose les meilleures ancres contextuelles et identifie les gaps thématiques
+ */
+export interface PublishedPage {
+    url: string;
+    title: string;
+    slug: string;
+    excerpt?: string;
+    focusKeyphrase?: string;
+    h2Headings?: string[];
+}
+export interface InternalLinkSuggestion {
+    targetUrl: string;
+    targetTitle: string;
+    suggestedAnchor: string;
+    contextSnippet: string;
+    relevanceScore: number;
+    reason: string;
+}
+export interface InternalLinkAnalysisInput {
+    currentContent: string;
+    currentTitle: string;
+    currentUrl: string;
+    publishedPages: PublishedPage[];
+}
+export interface InternalLinkAnalysisResult {
+    suggestions: InternalLinkSuggestion[];
+    analyzedPagesCount: number;
+    alreadyLinkedUrls: string[];
+    coverageGaps: string[];
+}
+export declare class ContextualInternalLinker {
+    /**
+     * Analyse le contenu courant et propose les meilleures suggestions de maillage
+     * interne en se basant sur la similarité N-gram avec les pages publiées.
+     *
+     * @param input  Données d'analyse (contenu, URL courante, pages publiées)
+     * @param topN   Nombre maximum de suggestions à retourner (défaut : 5)
+     */
+    static analyze(input: InternalLinkAnalysisInput, topN?: number): InternalLinkAnalysisResult;
+}

package/dist/conversion-funnel-calculator.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Conversion Funnel Calculator
+ * Calcule la progression des cohortes d'utilisateurs uniques à travers un entonnoir
+ * séquentiel multi-étapes, en mesurant les taux de conversion et d'abandon (drop-off).
+ */
+export interface FunnelStepDefinition {
+    stepIndex: number;
+    name: string;
+    urlPathPattern: string;
+}
+export interface RawVisitorEvent {
+    visitorId: string;
+    urlPath: string;
+    timestamp: string;
+}
+export interface FunnelStepResult {
+    stepIndex: number;
+    name: string;
+    urlPathPattern: string;
+    visitorsReached: number;
+    dropOffCount: number;
+    dropOffRatePercentage: number;
+    stepConversionRatePercentage: number;
+}
+export interface FunnelAnalysisResult {
+    funnelName: string;
+    totalUniqueVisitors: number;
+    completedFunnelVisitors: number;
+    overallConversionRatePercentage: number;
+    steps: FunnelStepResult[];
+}
+export declare class ConversionFunnelCalculator {
+    /**
+     * Analyse les événements visiteurs et calcule le tunnel séquentiel
+     */
+    static calculateFunnel(funnelName: string, steps: FunnelStepDefinition[], events: RawVisitorEvent[]): FunnelAnalysisResult;
+}

package/dist/conversion-tracking-generator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Conversion tracking snippets for the platforms the marketing playbooks
+ * target. Every identifier is validated before interpolation, so a campaign
+ * name coming from a spreadsheet cannot inject script into the generated tag.
+ */
+export type ConversionPlatform = "ga4" | "gtm" | "google_ads" | "meta" | "linkedin" | "tiktok";
+export interface ConversionDefinition {
+    /** Internal taxonomy event, e.g. `lead_submit`. */
+    eventName: string;
+    platform: ConversionPlatform;
+    value?: number;
+    currency?: string;
+    /** GA4 measurement id (`G-…`). */
+    measurementId?: string;
+    /** Google Ads conversion id (`AW-…`). */
+    conversionId?: string;
+    /** Google Ads conversion label. */
+    conversionLabel?: string;
+    /** Meta pixel id. */
+    pixelId?: string;
+    /** LinkedIn conversion id. */
+    linkedinConversionId?: number;
+}
+export interface ConversionValidation {
+    valid: boolean;
+    errors: string[];
+}
+export interface ConversionSnippet {
+    platform: ConversionPlatform;
+    eventName: string;
+    code: string;
+    notes: string[];
+}
+export declare function toGa4EventName(eventName: string): string;
+export declare function toMetaEventName(eventName: string): string;
+export declare function toTikTokEventName(eventName: string): string;
+export declare function validateConversionDefinition(definition: ConversionDefinition): ConversionValidation;
+export declare function generateConversionSnippet(definition: ConversionDefinition): ConversionSnippet;
+export interface GtmTagConfig {
+    tag: {
+        name: string;
+        type: "html";
+        parameter: Array<{
+            key: "html";
+            value: string;
+        }>;
+    };
+    trigger: {
+        name: string;
+        type: "customEvent";
+        customEventFilter: Array<{
+            type: "equals";
+            parameter: Array<{
+                key: string;
+                value: string;
+            }>;
+        }>;
+    };
+}
+export declare function generateGtmTagConfig(definition: ConversionDefinition): GtmTagConfig;
+export declare function generateMeasurementPlan(definitions: readonly ConversionDefinition[]): string;

package/dist/conversions-api.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Conversions API (server-side tagging)
+ *
+ * Le pendant serveur des balises de conversion : la plateforme publicitaire
+ * reçoit l'événement converti directement depuis notre backend, donc un
+ * bloqueur de pub ou un Safari tronqué ne fait plus disparaître la conversion.
+ *
+ * Deux règles structurelles :
+ * - Ce module ne fabrique JAMAIS l'authentification. Il décrit le régime
+ *   d'auth attendu (`auth`) et c'est le transport (Lynx Connect, qui détient
+ *   le token OAuth) qui l'applique. Un token n'entre pas dans ce dépôt.
+ * - Les identifiants personnels partent hachés en SHA-256, normalisés selon
+ *   l'usage de chaque plateforme ; le body préparé ne contient donc rien de
+ *   réidentifiant et peut être journalisé tel quel.
+ *
+ * Les noms d'événements Meta et TikTok réutilisent `conversion-tracking-generator`
+ * : la balise navigateur et le hit serveur doivent déclarer le même événement,
+ * sinon les deux canaux se déduisent mutuellement.
+ */
+export type CapiProvider = "meta" | "tiktok" | "pinterest" | "ga4" | "google_ads" | "snapchat" | "linkedin" | "posthog" | "webhook";
+export declare const CAPI_PROVIDERS: readonly CapiProvider[];
+export type CapiActionSource = "email" | "web" | "app" | "phone_call";
+export interface CapiUserData {
+    email?: string | null;
+    phone?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    externalId?: string | null;
+}
+export interface CapiContent {
+    id: string;
+    quantity?: number | null;
+    price?: number | null;
+}
+export interface CapiConversion {
+    /** Nom interne (`lead_submit`, `purchase`…), mappé par plateforme. */
+    eventName: string;
+    /** Clé d'idempotence : la plateforme déduplique dessus. */
+    eventId: string;
+    occurredAt: string;
+    actionSource?: CapiActionSource;
+    pageUrl?: string | null;
+    value?: number | null;
+    currency?: string | null;
+    userData?: CapiUserData | null;
+    contents?: CapiContent[] | null;
+}
+export interface CapiDestinationConfig {
+    provider: CapiProvider;
+    /** Pixel Meta, event source TikTok ou ad account Pinterest — jamais un secret. */
+    accountId: string;
+    /** Version d'API Graph (Meta seulement). */
+    apiVersion?: string;
+    /** Code d'événement de test (Meta seulement) : rien ne touche les enchères. */
+    testEventCode?: string;
+    /** Événements internes autorisés ; absent = tous ceux qu'on sait mapper. */
+    eventAllowlist?: string[];
+    /** Mapping personnalisé eventName interne -> eventName plateforme */
+    eventMapping?: Record<string, string>;
+    /** URL personnalisée (utilisée pour les webhooks ou relais custom) */
+    endpointUrl?: string;
+}
+export type CapiAuth = {
+    kind: "query";
+    param: string;
+} | {
+    kind: "header";
+    header: string;
+} | {
+    kind: "bearer";
+};
+export interface PreparedCapiRequest {
+    method: "POST";
+    url: string;
+    /**
+     * Même endpoint, relatif à la base de la plateforme : c'est la forme attendue
+     * par un proxy d'auth (Lynx Connect), qui ne accepte qu'un chemin.
+     */
+    proxyPath: string;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+    /** Régime d'auth à appliquer par le transport détenant le token. */
+    auth: CapiAuth;
+    eventId: string;
+    provider: CapiProvider;
+}
+export declare function toPinterestEventName(eventName: string): string;
+export declare function platformEventName(provider: CapiProvider, eventName: string, eventMapping?: Record<string, string>): string;
+export declare function isCapiProvider(value: string): value is CapiProvider;
+/**
+ * Construit la requête d'une conversion vers une destination.
+ * Renvoie `null` — jamais une requête approximative — quand l'identifiant de
+ * destination manque ou que l'événement n'a pas d'équivalent côté plateforme :
+ * envoyer `CustomEvent` à Pinterest fabriquerait un signal faux.
+ */
+export declare function prepareCapiRequest(destination: CapiDestinationConfig, conversion: CapiConversion): Promise<PreparedCapiRequest | null>;
+/**
+ * Hachage seul, exposé pour la vérification d'un import CRM : un projet peut
+ * vouloir contrôler ce que la plateforme verrait sans envoyer l'événement.
+ */
+export declare function hashConversionUserData(userData: CapiUserData): Promise<Record<string, string[]>>;
+export interface Ga4MeasurementProtocolDestination {
+    /** `tid` — id de flux GA4 (`G-…`). Public, stockable dans une destination. */
+    measurementId: string;
+    /** Fourni par l'appelant (coffre/variables d'env) ; jamais persisté ici. */
+    apiSecret: string;
+}
+export interface Ga4MeasurementProtocolHit {
+    kind: "event" | "pageview" | "screen_view";
+    /** Nom interne, mappé vers GA4 (`lead_submit` → `generate_lead`). */
+    eventName?: string | null;
+    clientId: string;
+    /** Identifiant applicatif ; la couche appelante ne le fournit qu'avec consentement. */
+    userId?: string | null;
+    eventId?: string | null;
+    occurredAt: string;
+    pageLocation?: string | null;
+    pageTitle?: string | null;
+    eventParameters?: Record<string, string | number | boolean> | null;
+    userProperties?: Record<string, string | number> | null;
+}
+export interface PreparedGa4Request {
+    method: "POST";
+    url: string;
+    headers: Record<string, string>;
+    /** Corps `x-www-form-urlencoded` prêt à émettre — contient l'api_secret. */
+    body: string;
+    provider: "ga4";
+    eventId: string;
+}
+export type Ga4HitRejectionReason = "measurement_id_invalid" | "api_secret_missing" | "client_id_missing" | "event_name_invalid";
+export declare class Ga4MeasurementProtocolError extends Error {
+    readonly reason: Ga4HitRejectionReason;
+    constructor(reason: Ga4HitRejectionReason, message: string);
+}
+export declare function prepareGa4MeasurementProtocolHit(destination: Ga4MeasurementProtocolDestination, hit: Ga4MeasurementProtocolHit): PreparedGa4Request;