@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/ab-testing-sequential.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license AGPL-3.0-or-later
+ *
+ * Test séquentiel (SPRT — Sequential Probability Ratio Test, Wald) pour les
+ * experiments A/B.
+ *
+ * Contrairement au test Z fréquentiste classique qui fixe la taille d'échantillon
+ * à l'avance, le SPRT évalue les données au fur et à mesure de leur arrivée et
+ * décide d'arrêter le test dès que la preuve est suffisante :
+ * - accepter H1 (il y a un effet) si le rapport de vraisemblance dépasse une
+ *   borne supérieure ;
+ * - accepter H0 (pas d'effet) si le rapport tombe sous une borne inférieure ;
+ * - continuer sinon.
+ *
+ * Cela permet d'arrêter un test gagnant plus tôt et d'économiser du trafic,
+ * tout en maîtrisant les erreurs de type I (alpha) et de type II (beta).
+ *
+ * Tout le calcul est pur et déterministe.
+ */
+export interface SequentialOptions {
+    /** Taux de conversion de référence (contrôle), entre 0 et 1. */
+    baselineRate: number;
+    /** Effet minimal détectable (relatif), ex. 0.10 pour +10 %. */
+    minimumDetectableEffect: number;
+    /** Erreur alpha (risque de faux positif), défaut 0.05. */
+    alpha?: number;
+    /** Erreur beta (risque de faux négatif), défaut 0.20 (puissance 80 %). */
+    beta?: number;
+}
+export interface SequentialResult {
+    decision: "continue" | "stop_accept_h1" | "stop_accept_h0";
+    logLikelihoodRatio: number;
+    upperBound: number;
+    lowerBound: number;
+    observations: number;
+    estimatedWinProbability: number;
+}
+export declare function sequentialTest(observations: Array<{
+    converted: boolean;
+}>, options: SequentialOptions): SequentialResult;
+/**
+ * Compare un groupe contrôle et un groupe variant via le SPRT.
+ *
+ * Contrairement à `sequentialTest` qui traite un échantillon séquentiellement,
+ * cette fonction agrège les deux groupes puis évalue le rapport de
+ * vraisemblance global. L'ordre des observations n'influence pas le résultat,
+ * ce qui évite tout arrêt prématuré dû à l'ordre de traitement (contrôle d'abord,
+ * puis variant).
+ */
+export declare function shouldStopSequential(controlObservations: Array<{
+    converted: boolean;
+}>, variantObservations: Array<{
+    converted: boolean;
+}>, options: SequentialOptions): {
+    decision: "continue" | "stop_accept_h1" | "stop_accept_h0";
+    recommendedVariantId: string | null;
+    confidence: number;
+    detail: SequentialResult;
+};

package/dist/ab-testing-significance.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Frequentist analysis of a two-variant (or n-variant) conversion experiment.
+ *
+ * The z-test uses the pooled proportion, confidence intervals use the Wilson
+ * score, and sample-size planning uses the standard two-proportion power
+ * formula. Everything is deterministic and pure so the same experiment always
+ * yields the same verdict on every runtime.
+ */
+export interface ExperimentVariantObservation {
+    variantId: string;
+    name: string;
+    visitors: number;
+    conversions: number;
+}
+export interface ExperimentOptions {
+    controlVariantId?: string;
+    confidenceLevel?: 0.9 | 0.95 | 0.99;
+    /** Relative lift the test must be able to detect, e.g. 0.1 for +10%. */
+    minimumDetectableEffect?: number;
+    power?: 0.8 | 0.9;
+}
+export interface VariantSignificance {
+    variantId: string;
+    name: string;
+    visitors: number;
+    conversions: number;
+    conversionRate: number;
+    absoluteUplift: number | null;
+    relativeUplift: number | null;
+    zScore: number | null;
+    pValue: number | null;
+    confidenceInterval95: {
+        lower: number;
+        upper: number;
+    };
+    isSignificant: boolean;
+    isUnderpowered: boolean;
+}
+export type ExperimentStatus = "no_data" | "collecting" | "no_winner" | "winner";
+export interface ExperimentAnalysis {
+    controlVariantId: string | null;
+    confidenceLevel: 0.9 | 0.95 | 0.99;
+    power: 0.8 | 0.9;
+    minimumDetectableEffect: number;
+    totalVisitors: number;
+    requiredVisitorsPerVariant: number | null;
+    hasEnoughSamples: boolean;
+    status: ExperimentStatus;
+    winnerVariantId: string | null;
+    variants: VariantSignificance[];
+}
+export declare function normalCdf(value: number): number;
+export declare function wilsonInterval(conversions: number, visitors: number, confidenceLevel?: 0.9 | 0.95 | 0.99): {
+    lower: number;
+    upper: number;
+};
+/**
+ * Visitors per variant needed to detect the given relative lift with the
+ * requested power at the configured confidence level.
+ */
+export declare function requiredSampleSizePerVariant(params: {
+    baselineRate: number;
+    minimumDetectableEffect: number;
+    confidenceLevel?: 0.9 | 0.95 | 0.99;
+    power?: 0.8 | 0.9;
+}): number | null;
+export declare function analyzeExperiment(observations: ExperimentVariantObservation[], options?: ExperimentOptions): ExperimentAnalysis;

package/dist/account-centric-abm.d.ts

@@ -0,0 +1,73 @@
+/**
+ * G13 — Account-Centric ABM (reverse-IP, privacy-first).
+ *
+ * Identifies B2B accounts from pSEO cluster visits without ever exposing a raw
+ * visitor IP. Visitors are supplied already hashed (an irreversible
+ * fingerprint), and the engine only ever reports account-level aggregates.
+ *
+ * Privacy guarantees:
+ * - Raw IP addresses are never accepted, stored or emitted by this module.
+ * - A k-anonymity floor (`minVisitorsPerAccount`) hides accounts visited by
+ *   only a handful of visitors, so no single visitor can be isolated.
+ * - Visitor fingerprints are truncated before they leave the engine.
+ */
+/** A single pSEO cluster visit by an already-anonymised visitor. */
+export interface ClusterVisit {
+    /** Irreversible hash of the visitor IP or device id. Never a raw IP. */
+    visitorFingerprint: string;
+    /** The pSEO cluster (landing page group) the visitor landed on. */
+    cluster: string;
+    /** Organisation resolved from the anonymised fingerprint, when known. */
+    organization?: string;
+    /** Company size band, used to weight account value. */
+    employeeBand?: "1-10" | "11-50" | "51-200" | "201-1000" | "1000+";
+    /** Deal value in currency units, when the visit is attributed to revenue. */
+    dealValue?: number;
+}
+export interface AccountCentricAbmConfig {
+    /** Minimum distinct visitors before an account is reported (k-anonymity). */
+    minVisitorsPerAccount?: number;
+    /** Maximum number of accounts returned, ranked by score. */
+    maxAccounts?: number;
+    /** Truncation length of the emitted visitor fingerprint. */
+    fingerprintPrefixLength?: number;
+    /** Minimum cluster coverage ratio for an account to be reported. */
+    minClusterCoverage?: number;
+}
+export interface AccountProfile {
+    accountId: string;
+    organization: string;
+    /** Aggregated cluster footprint — never individual visitor rows. */
+    pseoClusters: string[];
+    /** Distinct visitors behind the account (clamped by the k-anonymity floor). */
+    visitorCount: number;
+    /** Number of distinct clusters the account engaged with. */
+    clusterCount: number;
+    /** 0..1 score combining coverage, depth and account value. */
+    matchScore: number;
+    /** Truncated, non-reversible fingerprint of the account. */
+    ipFingerprint: string;
+    employeeBand?: AccountEmployeeBand;
+    /** Revenue attributed to the account's cluster engagement. */
+    estimatedRevenue: number;
+}
+export type AccountEmployeeBand = "1-10" | "11-50" | "51-200" | "201-1000" | "1000+";
+/**
+ * Reverse-IP, privacy-first account identification from pSEO cluster traffic.
+ */
+export declare class AccountCentricAbmEngine {
+    private readonly config;
+    constructor(config?: AccountCentricAbmConfig);
+    /**
+     * Aggregates anonymised cluster visits into B2B account profiles.
+     *
+     * Accounts below the k-anonymity floor are dropped so that a single
+     * visitor can never be re-identified from the output.
+     */
+    identifyAccounts(visits: ClusterVisit[]): AccountProfile[];
+    /**
+     * True when the account clears the k-anonymity floor and can therefore be
+     * reported without risking re-identification of an individual visitor.
+     */
+    isReportable(visitorCount: number): boolean;
+}

package/dist/ad-cost-roas.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 💰 Ad Cost & ROAS — G16
+ *
+ * Import manuel (CSV / JSON) des coûts publicitaires pour comparer le retour
+ * sur investissement des campagnes Ads face au ROI des pages pSEO.
+ *
+ * Le module est purement déterministe : aucune I/O, aucun accès réseau. Il
+ * normalise les lignes importées, agrège par plateforme, calcule les ratios
+ * (ROAS, CPA, CPC, CTR) et confronte le ROI Ads au ROI organique pSEO.
+ *
+ * Adapté (réécrit, sans import) des heuristiques d'allocation média de
+ * `inspiration/.../skills/ads-budget` : on compare des fenêtres normalisées
+ * plutôt que des moyennes mélangées, et on n'érige aucun multiple en règle
+ * universelle (70/20/10, multiple de CPA, etc. restent des heuristiques).
+ */
+export declare const AD_PLATFORMS: readonly ["google_ads", "meta_ads", "linkedin_ads", "tiktok_ads", "microsoft_ads", "x_ads", "amazon_ads", "apple_ads", "other"];
+export type AdPlatform = (typeof AD_PLATFORMS)[number];
+export interface AdCostEntry {
+    /** Plateforme publicitaire normalisée. */
+    platform: AdPlatform;
+    /** Campagne facultative, utile pour un drill-down par campagne. */
+    campaign?: string;
+    /** Jour de la dépense, format `YYYY-MM-DD`. */
+    date: string;
+    /** Montant dépensé sur la fenêtre, dans `currency`. */
+    spend: number;
+    /** Devise ISO-4217, `EUR` par défaut. */
+    currency: string;
+    impressions: number;
+    clicks: number;
+    /** Conversions attribuées (leads, achats, inscriptions). */
+    conversions: number;
+    /** Revenu attribué sur la même fenêtre, pour le ROAS. */
+    revenue: number;
+}
+/** Une ligne brute avant normalisation (CSV, JSON collé, formulaire). */
+export interface RawAdCostInput {
+    platform?: string;
+    campaign?: string;
+    date?: string;
+    spend?: number | string;
+    currency?: string;
+    impressions?: number | string;
+    clicks?: number | string;
+    conversions?: number | string;
+    revenue?: number | string;
+}
+export interface RoasBreakdown {
+    platform: AdPlatform;
+    spend: number;
+    revenue: number;
+    conversions: number;
+    clicks: number;
+    impressions: number;
+    entries: number;
+    /** `revenue / spend`, `null` quand la dépense est nulle. */
+    roas: number | null;
+    /** `spend / conversions`, `null` quand aucune conversion. */
+    cpa: number | null;
+    cpc: number | null;
+    /** Taux de clic `clicks / impressions` en pourcentage. */
+    ctr: number | null;
+}
+export interface RoasSummary {
+    entries: number;
+    spend: number;
+    revenue: number;
+    conversions: number;
+    clicks: number;
+    impressions: number;
+    currency: string;
+    roas: number | null;
+    cpa: number | null;
+    cpc: number | null;
+    ctr: number | null;
+    platforms: RoasBreakdown[];
+}
+export interface AdVsPseoInput {
+    /** Dépense publicitaire totale sur la fenêtre comparée. */
+    adSpend: number;
+    /** Revenu attribué aux campagnes Ads sur la même fenêtre. */
+    adRevenue: number;
+    /**
+     * Revenu organique attribué aux pages pSEO sur la même fenêtre. Amener une
+     * fenêtre comparable et une définition d'attribution identique ; sinon la
+     * comparaison est trompeuse (cf. règle « normaliser avant de comparer »).
+     */
+    pseoRevenue: number;
+    /**
+     * Coût de production/exploitation du parc pSEO sur la fenêtre. Sert à
+     * mesurer un ROI et pas seulement un ratio de revenu.
+     */
+    pseoCost?: number;
+}
+export interface AdVsPseoResult {
+    adRoas: number | null;
+    pseoRoas: number | null;
+    /** Écart de ROAS en points, positif si le pSEO est plus rentable. */
+    pseoAdvantage: number | null;
+    winner: "ads" | "pseo" | "tie" | "unknown";
+}
+/** Normalise une ligne brute ; `spend <= 0` reste accepté (dépense nulle). */
+export declare function normalizeAdCostEntry(raw: RawAdCostInput): AdCostEntry;
+/**
+ * Agrège les dépenses par plateforme et calcule les ratios. Une plateforme
+ * sans conversion renvoie un `cpa` à `null` plutôt que `Infinity`, pour ne pas
+ * propager un faux indicateur dans l'UI.
+ */
+export declare function computeRoas(entries: AdCostEntry[]): RoasSummary;
+/**
+ * Confronte le ROI publicitaire au ROI organique pSEO. Les deux ROAS sont
+ * calculés sur la même base (revenu / coût) et restent `null` si le coût est
+ * nul, afin de ne jamais afficher un ratio infini.
+ */
+export declare function computeAdVsPseoRoas(input: AdVsPseoInput): AdVsPseoResult;
+/**
+ * Parse un export CSV de coûts. La première ligne non vide est l'en-tête ;
+ * les colonnes inconnues sont ignorées et les colonnes absentes valent 0.
+ */
+export declare function parseAdCostCsv(csv: string): AdCostEntry[];

package/dist/ad-intelligence-cro.d.ts

@@ -1,15 +1,14 @@
 /**
  * ⚡ Unified Ad Intelligence & Social CRO Optimizer
  *
- * Inspired by top GitHub Ad Scraping architectures:
- * - Meta Ad Library GraphQL Collector
- * - Google Ads Transparency Center MCP
- * - TikTok Creative Center Top Ads Scraper
+ * Covers Meta, Google and TikTok ad-intelligence sources.
  *
  * Capabilities:
  * 1. Audits winning competitor ads (running > 90 days = proven profitable).
  * 2. Injects high-converting ad angles into Programmatic SEO landing pages to boost CRO.
- * 3. Generates multi-platform ad campaigns (Meta, Google RSAs, LinkedIn) from any SEO page.
+ * 3. Generates multi-platform ad campaigns (Meta, Google RSAs, LinkedIn, TikTok) from any SEO page.
+ * 4. Live ingestion via Meta Ad Library Graph API, TikTok Creative Center & Google Transparency.
+ * 5. Direct campaign creation on Meta Marketing API & Google Ads API.
  */
 export interface ProvenAdWinner {
     competitorDomain: string;
@@ -22,7 +21,7 @@ export interface ProvenAdWinner {
     extractedCommercialKeywords: string[];
 }
 export interface AdCampaignBrief {
-    platform: "meta" | "google_search" | "linkedin";
+    platform: "meta" | "google_search" | "linkedin" | "tiktok";
     targetAudience: string;
     primaryTextOrDescriptions: string[];
     headlines: string[];
@@ -37,17 +36,50 @@ export interface CroPageOptimization {
     recommendedCtaButtonText: string;
     estimatedConversionUpliftPercent: number;
 }
+export interface LiveAdInspectionOptions {
+    competitorDomain: string;
+    metaAccessToken?: string;
+    metaAdAccountId?: string;
+    countryCode?: string;
+}
+export interface CampaignCreationResult {
+    success: boolean;
+    platform: string;
+    campaignId?: string;
+    adSetId?: string;
+    status: "active" | "draft" | "paused" | "error";
+    error?: string;
+}
 export declare class AdIntelligenceCroEngine {
     /**
-     * 1. Simulates/Queries competitor ad archives across Meta, Google & TikTok.
+     * 1. Inspects competitor ad archives across Meta, Google & TikTok (heuristic fallback).
      */
     static inspectCompetitorAds(competitorDomain: string, serviceName?: string): ProvenAdWinner[];
     /**
-     * 2. Uses proven ad angles to upgrade landing page conversion rates (CRO).
+     * 2. Live query into Meta Ad Library API using official Graph API credentials.
+     */
+    static fetchLiveMetaAds(options: LiveAdInspectionOptions): Promise<ProvenAdWinner[]>;
+    /**
+     * 3. Scrapes & parses TikTok Creative Center top-performing ads.
+     */
+    static scrapeTikTokCreativeCenter(keyword: string, options?: {
+        region?: string;
+    }): Promise<ProvenAdWinner[]>;
+    /**
+     * 4. Direct campaign launcher for Meta Marketing API.
+     */
+    static createLiveMetaCampaign(params: {
+        accountId: string;
+        accessToken: string;
+        brief: AdCampaignBrief;
+        dailyBudgetEur?: number;
+    }): Promise<CampaignCreationResult>;
+    /**
+     * 5. Uses proven ad angles to upgrade landing page conversion rates (CRO).
      */
     static optimizeLandingPageCroWithAdInsights(originalTitle: string, adWinners: ProvenAdWinner[]): CroPageOptimization;
     /**
-     * 3. Generates complete ad creatives (Google Search Ads & Meta Ads) from a Programmatic SEO page.
+     * 6. Generates complete ad creatives (Google Search Ads, Meta Ads & TikTok) from a Programmatic SEO page.
      */
     static generateAdCampaignFromSeoPage(opts: {
         seoPageUrl: string;

package/dist/ad-matrix-multiplier.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Ad Matrix Multiplier
+ * Générateur combinatoire d'annonces haute conversion pour Meta Ads, Google Ads et TikTok.
+ * Produit la matrice complète Angles x Hooks x Corps x CTAs avec export direct au format CSV.
+ */
+export interface AdMatrixInputs {
+    productName: string;
+    targetAudience: string;
+    angles: Array<{
+        type: "pain" | "gain" | "fomo" | "social_proof";
+        name: string;
+        hook: string;
+    }>;
+    bodies: string[];
+    callToActions: string[];
+}
+export interface AdVariant {
+    id: string;
+    angleType: string;
+    angleName: string;
+    headline: string;
+    primaryText: string;
+    callToAction: string;
+    persuasionScore: number;
+}
+export interface AdMatrixResult {
+    totalVariantsCount: number;
+    variants: AdVariant[];
+    csvExportContent: string;
+}
+export declare class AdMatrixMultiplier {
+    /**
+     * Génère toutes les combinaisons possibles et produit le CSV
+     */
+    static generateMatrix(input: AdMatrixInputs): AdMatrixResult;
+}

package/dist/ad-remix-engine.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 🎨 LynxSEO Ad Remix Engine - Structural Vision Deconstruction & Brand Reconstruction
+ *
+ * Repris et adapté sous licence MIT depuis inspiration/03-social-ad-intelligence/repos/nalarin-agentic-ads-studio.
+ *
+ * Fonctionnalités :
+ * 1. Déconstruction structurelle (Gemini / LLM Vision) : extrait un AdBlueprint neutre
+ *    (layout_framework, narrative_arc, text_hierarchy, psychological_triggers, visual_style_guide).
+ * 2. Reconstruction de marque : applique le Brand DNA et génère l'AdConcept complet
+ *    (headline_remix, visual_description, body_copy, cta_button, image_generation_prompt).
+ * 3. Génération de prompts prêts pour les modèles génératifs d'images (Imagen, Fal.ai, Midjourney, Flux).
+ */
+export interface AdBlueprint {
+    /** Cadre visuel ou grille de composition (ex: '4-panel comic grid', 'split screen vertical', 'UGC selfie') */
+    layoutFramework: string;
+    /** Séquence narrative (ex: 'Problem -> Discovery -> Solution -> CTA') */
+    narrativeArc: string;
+    /** Organisation et hiérarchie du texte (ex: 'Large question headline at top, 3 bullet points, badge, CTA') */
+    textHierarchy: string;
+    /** Déclencheurs psychologiques (ex: ['Social Proof', 'Urgency', 'Loss Aversion']) */
+    psychologicalTriggers: string[];
+    /** Direction artistique et ambiance visuelle (ex: 'Minimalist Apple-style', 'Bold Swiss Brutalism') */
+    visualStyleGuide: string;
+}
+export interface BrandData {
+    brandName: string;
+    brandVoice?: string;
+    productName: string;
+    productDescription: string;
+    audienceDemographics: string;
+    audiencePainPoints?: string;
+    audienceGoals?: string;
+    campaignOffer: string;
+    campaignUrgency?: string;
+    campaignMessaging: string;
+}
+export interface AdConcept {
+    /** Titre accrocheur adapté à la hiérarchie du blueprint */
+    headlineRemix: string;
+    /** Description visuelle de la nouvelle création (garde la grille du blueprint) */
+    visualDescription: string;
+    /** Corps de texte / puces adapté à l'offre de la marque */
+    bodyCopy: string;
+    /** Bouton d'action (CTA) aligné sur le style du blueprint */
+    ctaButton: string;
+    /** Prompt détaillé pour générateur d'image (Midjourney, Flux, Fal.ai, Imagen) */
+    imageGenerationPrompt: string;
+    /** Métadonnées de conformité au blueprint d'origine */
+    blueprintCompliance: {
+        appliedTriggers: string[];
+        layoutFramework: string;
+        narrativeArc: string;
+    };
+}
+export declare const AD_REMIX_DECONSTRUCTION_SYSTEM_PROMPT = "You are a master creative strategist analyzing advertising templates.\nYour goal: Extract the STRUCTURAL BLUEPRINT of this ad, ignoring the specific product being sold.\n\nAnalyze this ad and identify:\n1. The visual layout/composition (layout_framework)\n2. The narrative storytelling pattern (narrative_arc)\n3. How text is organized and prioritized (text_hierarchy)\n4. What psychological triggers make it effective (psychological_triggers)\n5. The overall aesthetic style (visual_style_guide)\n\nFocus on STRUCTURE, not content. If it is a fitness ad, describe the \"Before/After transformation\" pattern, not the workout itself.\n\nReturn ONLY valid JSON with this exact structure:\n{\n  \"layout_framework\": \"Describe the visual grid (e.g., 'split screen vertical', '4-panel comic grid', 'hero product with floating testimonials')\",\n  \"narrative_arc\": \"The storytelling sequence (e.g., 'Problem -> Discovery -> Solution -> CTA')\",\n  \"text_hierarchy\": \"How text is organized (e.g., 'Large problem question at top, 3 benefit bullets, CTA button at bottom')\",\n  \"psychological_triggers\": [\"Trigger 1\", \"Trigger 2\", \"Trigger 3\"],\n  \"visual_style_guide\": \"The aesthetic vibe (e.g., 'Minimalist high-contrast typography, warm natural lighting, candid UGC authenticity')\"\n}";
+export declare const AD_REMIX_RECONSTRUCTION_SYSTEM_PROMPT = "You are a Senior Creative Director creating a new ad concept.\nYou have been given:\n1. A PROVEN AD BLUEPRINT - a structural pattern that has been tested and works\n2. NEW BRAND DATA - your client's product information\n\nYour mission: Create a new ad concept that strictly follows the Blueprint's structure but is completely populated with the New Brand's content.\n\nCRITICAL RULES:\n1. Keep the blueprint's layout_framework exactly.\n2. Follow the blueprint's narrative_arc pattern.\n3. Match the blueprint's text_hierarchy.\n4. Incorporate the same psychological_triggers.\n5. Match the blueprint's visual_style_guide.\n\nReturn ONLY valid JSON with this exact structure:\n{\n  \"headline_remix\": \"New headline matching blueprint's text hierarchy and selling the new product\",\n  \"visual_description\": \"Detailed description of the new image preserving the blueprint layout framework\",\n  \"body_copy\": \"Supporting text and bullets adapted to the new brand\",\n  \"cta_button\": \"Call to action matching the blueprint style\",\n  \"image_generation_prompt\": \"Detailed visual prompt for Midjourney/Flux/Imagen. Mention layout, subjects, lighting, style, composition, aspect ratio --ar 4:5 --no watermark, text blur\"\n}";
+export declare class AdRemixEngine {
+    /**
+     * Construit le prompt de déconstruction pour une analyse visuelle.
+     */
+    static buildDeconstructionPrompt(imageContext?: string): string;
+    /**
+     * Construit le prompt de reconstruction injectant le Brand DNA dans le blueprint.
+     */
+    static buildReconstructionPrompt(blueprint: AdBlueprint, brand: BrandData): string;
+    /**
+     * Analyse et valide un JSON brut de déconstruction pour garantir un AdBlueprint conforme.
+     */
+    static parseBlueprintJson(rawJson: string): AdBlueprint;
+    /**
+     * Analyse et valide un JSON brut de reconstruction pour garantir un AdConcept conforme.
+     */
+    static parseConceptJson(rawJson: string, sourceBlueprint: AdBlueprint): AdConcept;
+    /**
+     * Générateur heuristique instantané (zéro latence / fallback hors-ligne)
+     * Permet de générer immédiatement un AdConcept depuis un blueprint sans appel API payant.
+     */
+    static generateConceptOffline(blueprint: AdBlueprint, brand: BrandData): AdConcept;
+}

package/dist/advanced-retention.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 📊 Advanced Retention Metrics (gap G5)
+ *
+ * Métriques de rétention avancée au-delà des cohorts basiques :
+ * - DAU / MAU et ratio de stickiness
+ * - Time-to-value (délai avant première action de valeur)
+ * - Power users (seuil d'activité élevé)
+ * - One-visit share (part des visiteurs ne revenant jamais)
+ * - Rétention par fenêtre glissante (rolling retention)
+ *
+ * Aucune dépendance externe, pur TypeScript. Fonctionne sur des événements
+ * utilisateurs déjà collectés (pulse-analytics).
+ */
+export interface RetentionEvent {
+    userId: string;
+    timestamp: string;
+    event: string;
+    properties?: Record<string, unknown>;
+}
+export interface DAUMAUResult {
+    date: string;
+    dau: number;
+    mau: number;
+    stickinessRatio: number;
+}
+export interface TimeToValueResult {
+    avgTimeToValueMs: number;
+    medianTimeToValueMs: number;
+    p90TimeToValueMs: number;
+    usersConverted: number;
+    totalUsers: number;
+    conversionRate: number;
+}
+export interface PowerUserResult {
+    powerUserCount: number;
+    totalUserCount: number;
+    powerUserRatio: number;
+    thresholdEvents: number;
+}
+export interface OneVisitShareResult {
+    oneVisitUsers: number;
+    totalUsers: number;
+    oneVisitShare: number;
+    returningUsers: number;
+}
+export interface RollingRetentionResult {
+    cohortDate: string;
+    cohortSize: number;
+    day1Retention: number;
+    day7Retention: number;
+    day30Retention: number;
+}
+export interface AdvancedRetentionMetrics {
+    dauMau: DAUMAUResult[];
+    timeToValue: TimeToValueResult;
+    powerUsers: PowerUserResult;
+    oneVisitShare: OneVisitShareResult;
+    rollingRetention: RollingRetentionResult[];
+}
+export declare class AdvancedRetentionEngine {
+    private events;
+    constructor(events?: RetentionEvent[]);
+    /** Ajoute des événements en lot. */
+    addEvents(events: RetentionEvent[]): void;
+    /** Remplace tous les événements. */
+    setEvents(events: RetentionEvent[]): void;
+    /** Retourne tous les événements. */
+    getEvents(): RetentionEvent[];
+    computeDAUMAU(startDate: string, endDate: string): DAUMAUResult[];
+    computeTimeToValue(valueEvent: string, windowMs?: number): TimeToValueResult;
+    computePowerUsers(thresholdEvents?: number, windowDays?: number): PowerUserResult;
+    computeOneVisitShare(): OneVisitShareResult;
+    computeRollingRetention(startDate: string, endDate: string): RollingRetentionResult[];
+    private _retainedUsers;
+    computeAll(startDate: string, endDate: string): AdvancedRetentionMetrics;
+}
+export declare const defaultRetentionEngine: AdvancedRetentionEngine;