@lynxflow/seo-engine 2.8.0 → 3.2.1

package/README.md

@@ -1,16 +1,16 @@
-# @lynxflow/seo-engine
+# @lynxseo/engine
 
 High-Performance Universal Programmatic SEO & Structured Data Engine for Modern Web Applications.
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![License](https://img.shields.io/badge/License-Proprietary-green.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/Version-2.8.0-orange.svg)](https://www.npmjs.com/package/@lynxflow/seo-engine)
+[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/Version-3.0.0-orange.svg)](https://www.npmjs.com/package/@lynxseo/engine)
 
 ---
 
 ## Overview
 
-`@lynxflow/seo-engine` is an enterprise developer SDK providing in-memory programmatic SEO matrix generation, Google-compliant Schema.org structured data, infinite geographic location synthesis, strict market boundaries, and real-time GeoIP Edge detection worldwide.
+`@lynxseo/engine` is an enterprise developer SDK providing in-memory programmatic SEO matrix generation, Google-compliant Schema.org structured data, infinite geographic location synthesis, strict market boundaries, and real-time GeoIP Edge detection worldwide.
 
 * **10 Canonical Root Pillars & 50+ Specialized Sub-Matrices:** Scales across industries, regulatory frameworks, role KPIs, multi-format templates, integration ecosystems, and ROI tools.
 * **Strict Geographic & Linguistic Scoping:** Easily lock your website to a single country (e.g. 100% US or 100% France) or expand globally across multiple languages and territories with `strictCountryBoundary`.
@@ -26,11 +26,11 @@ High-Performance Universal Programmatic SEO & Structured Data Engine for Modern
 ## Installation
 
 ```bash
-npm install @lynxflow/seo-engine
+npm install @lynxseo/engine
 # or
-pnpm add @lynxflow/seo-engine
+pnpm add @lynxseo/engine
 # or
-bun add @lynxflow/seo-engine
+bun add @lynxseo/engine
 ```
 
 ---
@@ -68,7 +68,7 @@ export const SEO_CONFIG = {
 ### 1. Initialize Engine & Dataset
 
 ```typescript
-import { PseoMatrixEngine } from "@lynxflow/seo-engine";
+import { PseoMatrixEngine } from "@lynxseo/engine";
 
 export const matrixEngine = new PseoMatrixEngine();
 
@@ -105,7 +105,7 @@ const pageCustom = matrixEngine.resolvePage(["commercial-hvac", "90210"], "https
 ### 3. Edge GeoIP Resolution Example
 
 ```typescript
-import { resolveLocationFromHeaders, PseoMatrixEngine } from "@lynxflow/seo-engine";
+import { resolveLocationFromHeaders, PseoMatrixEngine } from "@lynxseo/engine";
 
 export function handleIncomingRequest(request: Request) {
   const geo = resolveLocationFromHeaders(request.headers);
@@ -117,11 +117,65 @@ export function handleIncomingRequest(request: Request) {
 
 ---
 
+---
+
+## Core SDK Facade: `LynxSeo`
+
+The `LynxSeo` class provides an enterprise, unified gateway to all algorithmic auditing, GEO/AEO optimization, and crawling capabilities:
+
+```typescript
+import { LynxSeo } from "@lynxseo/engine";
+
+const lynx = new LynxSeo();
+
+// 1. GEO / AEO Citability & Trust Optimization
+const trustScore = lynx.geoTrustStack.evaluate({
+  author: "Expert SEO",
+  citationsCount: 12,
+  primarySources: ["https://doi.org/..."],
+  verifiableFactsCount: 45,
+});
+
+// 2. Prompt Injection & AI Safety Defense
+const safetyCheck = lynx.geoPromptInjection.scan(rawUserInput);
+
+// 3. High-Performance Site Crawler with Robots.txt Compliance
+const crawler = lynx.crawler;
+const crawlReport = await crawler.crawl({
+  startUrl: "https://example.com",
+  maxPages: 50,
+  respectRobotsTxt: true,
+  userAgent: "LynxSeoBot/1.0",
+});
+
+// 4. Content Diffing & Near-Duplicate Detection
+const similarity = lynx.nearDuplicate.calculateSimilarity(docA, docB);
+```
+
+---
+
+## Complete Module Categories
+
+| Category | Key Modules & Classes | Capabilities |
+| :--- | :--- | :--- |
+| **Generative Engine Optimization (GEO / AEO)** | `GeoFixer`, `GeoTrustStack`, `GeoCitabilityAuditor`, `GeoPromptInjectionDetector`, `GeoKnowledgeGraph` | Optimizes content for Perplexity, SearchGPT, Gemini, and Claude citations; guards against AI prompt injections. |
+| **Site Crawling & Auditing** | `SiteCrawler`, `parseRobotsTxt`, `isRobotsAllowed`, `CrawlDiffTracker`, `NearDuplicateDetector` | High-speed async crawling, robots.txt parsing, canonical resolution, similarity hashing, and diff tracking. |
+| **Programmatic SEO (pSEO)** | `PseoMatrixEngine`, `createDynamicLocation`, `validatePseoService`, `validatePseoLocation` | Dynamic URL routing, infinite geographic resolution, input validation, and zero-DB RAM execution. |
+| **Structured Data & Schema.org** | `ExtendedSchemaGraphBuilder`, `SchemaValidator`, `JsonLdExtractor` | Generates 50+ Google Rich Result schemas (LocalBusiness, Product, FAQPage, Article, SoftwareApp). |
+| **Local SEO & Maps** | `LocalSeoBooster`, `GbpAuditor`, `ReviewSentimentAnalyzer`, `GeoGridScoreCalculator` | 3-Pack rank booster, citation consistency audit, NLP sentiment scoring on Google reviews. |
+| **Internal Linking & Graph** | `InternalLinkGraph`, `PageRankCalculator`, `AnchorTextOptimizer` | Simulates internal PageRank distribution, detects orphan pages and under-linked topical hubs. |
+| **Edge & Multi-Locale** | `resolveLocationFromHeaders`, `cleanSeoSlug`, `LegalDisclaimerEngine` | Real-time Edge GeoIP extraction (Cloudflare/Vercel/AWS), multilingual slug cleansing for 10+ languages. |
+
+---
+
 ## TypeScript API Reference
 
+* **`LynxSeo`**: Central facade unifying all SEO, GEO, and auditing modules.
 * **`PseoMatrixEngine`**: Core programmatic matrix compiler with geographic boundaries and crawl budget protection.
+* **`validatePseoService` / `validatePseoLocation`**: Zod-equivalent validation contracts for matrix datasets.
 * **`createDynamicLocation(slugOrInput, fallbackCountry, options)`**: Dynamic synthesis of any city, postal code or district worldwide.
 * **`resolveLocationFromHeaders(headers)`**: Edge header GeoIP extractor for Cloudflare, Vercel, CloudFront, and Nginx.
+* **`parseRobotsTxt(content)` / `isRobotsAllowed(path, userAgent, rules)`**: RFC-compliant robots.txt parser and evaluator.
 * **`cleanSeoSlug(text, options)`**: Multilingual slug normalizer with stop-word removal for 10+ languages.
 * **`ExtendedSchemaGraphBuilder`**: 50+ Google Rich Result Schema.org JSON-LD generator.
 * **`LegalDisclaimerEngine`**: Verified compliance notice manager with staleness guards (>90 days).
@@ -131,4 +185,18 @@ export function handleIncomingRequest(request: Request) {
 
 ## License
 
-Proprietary — LynxFlow Technologies. All rights reserved.
+GNU Affero General Public License v3.0 or later. See [LICENSE](LICENSE).
+
+---
+
+## 🏛️ Programmatic AI Page Persistence & Rotation Architecture
+
+Pour comprendre exactement comment sauvegarder les pages générées par l'IA sans perdre les jetons payés, comment les stocker (fichiers JSON, SQLite D1 ou WordPress) et comment distribuer 6 variantes uniques sur des milliers de villes sans duplication :
+
+👉 **Consultez la spécification complète : [PSEO_PERSISTENCE_ARCHITECTURE.md](./PSEO_PERSISTENCE_ARCHITECTURE.md)**
+
+### Résumé de l'architecture de persistance :
+1. **Génération par lots (AI Blueprint Pool) :** 6 variantes éditoriales complètes (Markdown, FAQ, Schema, Accroche) générées une seule fois par l'IA.
+2. **Rotation mathématique (`index % 6`) :** Attribution déterministe d'une variante par ville (ex: Paris = Var 0, Lyon = Var 1, Marseille = Var 2...), éliminant tout risque de *Doorway Pages*.
+3. **Persistance physique définitive :** Écriture sur disque local (`.lynx-cache/pages/{slug}.json`), en base SQL Cloudflare D1 (`prog_pages`) ou table WordPress (`wp_lynxseo_generation_logs`).
+4. **Temps de réponse Googlebot < 5ms :** Aucune requête IA sur les visites suivantes, coût d'exécution à 0 $ et vitesse de crawl maximale.

package/bin/lynx-audit

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+
+/**
+ * LynxSEO CLI Entrypoint (Executable)
+ * Run audits, generate PDF/Excel/Markdown reports, rescore saved crawls.
+ */
+
+const {
+  runAudit,
+  runRender,
+  runRescore,
+  runDoctor,
+  runGeoAudit,
+  runGeoCi,
+  runGeoDiff,
+  runGeoScaffold,
+  runGeoCoherence,
+  runGeoLogs,
+  runGeoTrack,
+  runGeoHistory,
+  runGeoMonitor,
+  runGeoSnapshots,
+  runLocalImport,
+  runLocalRiskAudit,
+  runDeepCrawlImport
+} = require("../dist/cli.js");
+
+function parseArgs(args) {
+  const result = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        result[key] = next;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    } else {
+      result._.push(arg);
+    }
+  }
+  return result;
+}
+
+async function main() {
+  const argv = parseArgs(process.argv.slice(2));
+  const cmd = argv._[0];
+
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(`
+LynxSEO Audit Engine CLI (v3.2.0)
+
+SEO & Traditional Crawl Commands:
+  lynx-audit audit        <url> [options]         Crawl site, evaluate 52 rules, output audit.json + digest.md
+  lynx-audit render       <dir> [options]         Generate HTML/PDF, Excel (.xlsx), and Markdown reports
+  lynx-audit run          <url> [options]         Audit and render in a single step
+  lynx-audit rescore      <dir>                   Recalculate scores and actions from saved audit.json
+  lynx-audit doctor                               Inspect dependencies and API credentials
+
+AI & GEO Citability Commands:
+  lynx-audit geo          <url|file> [options]    Full GEO Citability, Trust Stack, Context Window, Decay & Security Audit
+  lynx-audit geo:ci       <url|file> [options]    Run CI/CD policy gate with SARIF, JUnit, or Markdown PR annotations
+  lynx-audit geo:diff     <before> <after>        Compare 2 GEO audit snapshots and evaluate regression status
+  lynx-audit geo:scaffold <dir> [options]         Generate llms.txt, .well-known/ai.txt, /ai/summary.json
+  lynx-audit geo:coherence <dir|files>            Audit cross-page semantic coherence and definition conflicts
+  lynx-audit geo:logs     <logfile>               Analyze access logs for Googlebot, GPTBot, ClaudeBot, PerplexityBot
+  lynx-audit geo:track    <keyword> [options]     Geo-Grid local pack rank tracking with GPS coordinate matrix
+  lynx-audit geo:history  <url|file>              Evaluate content freshness half-life and evergreen decay score
+  lynx-audit geo:monitor  <url>                   Real-time monitoring of WAF barriers, prompt injections & decay
+  lynx-audit geo:snapshots <dir>                  List, inspect and verify chronological audit snapshots
+
+Local SEO & Pack 3-Pack Commands (Zero-API & Claim Ledger):
+  lynx-audit local:import   <file> [options]        Import Local Falcon CSV, GBP Insights, Reviews, Citations (Zero-API)
+  lynx-audit local:risk     [options]               Evaluate Google Business Profile suspension risk (Claim Ledger)
+
+Enterprise Deep Crawl & Health Diagnostic Commands (Zero-API):
+  lynx-audit crawl:import   <file> [options]        Import crawl CSV (internal URLs, redirect chains, canonicals)
+
+Options:
+  --out <path>          Output file or directory
+  --type <type>         Import type for local:import (geogrid, gbp, reviews, citations)
+  --registered-name <s> Registered legal business name for local:risk
+  --gbp-name <s>        Displayed name on Google Business Profile for local:risk
+  --coworking           Flag if address is in coworking or virtual office
+  --sab                 Flag if business is service-area only (itinérant)
+  --min-score <n>       Minimum score threshold for CI gate (default 70)
+  --format <fmt>        Output format for CI (json, sarif, junit, text)
+  --fail-on-warning     Fail CI step if warnings exist
+  --site-name <name>    Site brand name for scaffolding
+  --site-url <url>      Site root URL for scaffolding
+  --max-pages <n>       Maximum pages to crawl (default 60)
+  --max-depth <n>       Maximum BFS crawl depth (default 5)
+  --time-budget <sec>   Crawl time budget in seconds (default 600)
+  --no-psi              Skip PageSpeed Insights performance testing
+  --psi-pages <n>       Pages measured with PageSpeed Insights (default 3)
+  --full                Enable DataForSEO live keyword rankings and backlinks
+  --formats <list>      Comma-separated render formats (html,xlsx,md)
+  --language <lang>     Site language: crawler Accept-Language, browser locale, DataForSEO (default en)
+  --report-lang <lang>  Report language: translates deliverables at render time
+    `);
+    process.exit(0);
+  }
+
+  if (cmd === "doctor") {
+    runDoctor();
+    return;
+  }
+
+  // Normalize `lynx-audit geo <subcommand>` to `cmd = geo:<subcommand>`
+  let normalizedCmd = cmd;
+  let argsOffset = 1;
+  if (cmd === "geo" && argv._[1] && ["audit", "ci", "diff", "scaffold", "coherence", "logs", "track", "history", "monitor", "snapshots"].includes(argv._[1])) {
+    normalizedCmd = `geo:${argv._[1]}`;
+    argsOffset = 2;
+  }
+  if (cmd === "local" && argv._[1] && ["import", "risk"].includes(argv._[1])) {
+    normalizedCmd = `local:${argv._[1]}`;
+    argsOffset = 2;
+  }
+  if (cmd === "crawl" && argv._[1] && ["import"].includes(argv._[1])) {
+    normalizedCmd = `crawl:${argv._[1]}`;
+    argsOffset = 2;
+  }
+
+  if (normalizedCmd === "crawl:import") {
+    const file = argv._[argsOffset];
+    if (!file) {
+      console.error("Error: Missing file path for crawl:import. Usage: lynx-audit crawl:import <filepath> [--type internal|redirects|canonicals]");
+      process.exit(1);
+    }
+    runDeepCrawlImport(file, argv.type, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "local:import") {
+    const file = argv._[argsOffset];
+    if (!file) {
+      console.error("Error: Missing file path for local:import. Usage: lynx-audit local:import <filepath> [--type geogrid|gbp|reviews|citations]");
+      process.exit(1);
+    }
+    runLocalImport(file, argv.type, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "local:risk") {
+    const registeredName = argv["registered-name"] || argv.registeredName || argv._[argsOffset];
+    const gbpName = argv["gbp-name"] || argv.gbpName || registeredName;
+    if (!registeredName) {
+      console.error("Error: Missing business name. Usage: lynx-audit local:risk --registered-name \"Legal Name\" --gbp-name \"Displayed Name\"");
+      process.exit(1);
+    }
+    runLocalRiskAudit({
+      registeredBusinessName: registeredName,
+      gbpProfileName: gbpName,
+      isCoworkingOrVirtualOffice: Boolean(argv.coworking),
+      isServiceAreaOnly: Boolean(argv.sab),
+      addressHiddenIfServiceArea: !argv["show-address"],
+      categoriesCount: argv.categories ? parseInt(argv.categories, 10) : 3,
+      hasCustomReviewIncentive: Boolean(argv.gating || argv["review-gating"]),
+    }, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo" || normalizedCmd === "geo:audit") {
+    const target = argv._[argsOffset];
+    if (!target) {
+      console.error("Error: Missing target URL or HTML file for GEO audit.");
+      process.exit(1);
+    }
+    await runGeoAudit(target, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo:ci") {
+    const target = argv._[argsOffset];
+    if (!target) {
+      console.error("Error: Missing target URL or HTML file for GEO CI audit.");
+      process.exit(1);
+    }
+    const exitCode = await runGeoCi(target, {
+      minScore: argv["min-score"] ? parseInt(argv["min-score"], 10) : undefined,
+      format: argv.format,
+      out: argv.out,
+      failOnWarning: Boolean(argv["fail-on-warning"]),
+    });
+    process.exit(exitCode);
+  }
+
+  if (normalizedCmd === "geo:diff") {
+    const before = argv._[argsOffset];
+    const after = argv._[argsOffset + 1];
+    if (!before || !after) {
+      console.error("Error: Usage: lynx-audit geo:diff <before.json> <after.json> [--out <path>]");
+      process.exit(1);
+    }
+    runGeoDiff(before, after, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo:scaffold") {
+    const outDir = argv._[argsOffset] || argv.out || "./public";
+    runGeoScaffold(outDir, {
+      siteName: argv["site-name"] || argv.siteName || "My Site",
+      siteUrl: argv["site-url"] || argv.siteUrl || "https://example.com",
+      description: argv.description,
+    });
+    return;
+  }
+
+  if (normalizedCmd === "geo:coherence") {
+    const targets = argv._.slice(argsOffset);
+    if (targets.length === 0) {
+      console.error("Error: Missing directory or files for GEO coherence audit.");
+      process.exit(1);
+    }
+    runGeoCoherence(targets, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo:logs") {
+    const logFile = argv._[argsOffset];
+    if (!logFile) {
+      console.error("Error: Missing log file path. Usage: lynx-audit geo:logs <access.log> [--out <path>]");
+      process.exit(1);
+    }
+    runGeoLogs(logFile, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo:track") {
+    const keyword = argv._[argsOffset];
+    const businessName = argv._[argsOffset + 1] || argv["business-name"] || "Business";
+    const lat = argv.lat ? parseFloat(argv.lat) : 48.8566; // Default Paris
+    const lng = argv.lng ? parseFloat(argv.lng) : 2.3522;
+    if (!keyword) {
+      console.error("Error: Missing keyword. Usage: lynx-audit geo:track <keyword> [businessName] [--lat <f>] [--lng <f>]");
+      process.exit(1);
+    }
+    runGeoTrack({
+      keyword,
+      businessName,
+      centerLat: lat,
+      centerLng: lng,
+      gridRadiusKm: argv.radius ? parseFloat(argv.radius) : undefined,
+      gridSize: argv["grid-size"] ? parseInt(argv["grid-size"], 10) : undefined,
+    }, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo:history") {
+    const target = argv._[argsOffset];
+    if (!target) {
+      console.error("Error: Missing target URL or file. Usage: lynx-audit geo:history <file|url>");
+      process.exit(1);
+    }
+    runGeoHistory(target, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo:monitor") {
+    const target = argv._[argsOffset];
+    if (!target) {
+      console.error("Error: Missing target URL or file. Usage: lynx-audit geo:monitor <url>");
+      process.exit(1);
+    }
+    await runGeoMonitor(target, argv.out);
+    return;
+  }
+
+  if (normalizedCmd === "geo:snapshots") {
+    const snapshotsDir = argv._[argsOffset] || argv.dir || "./lynx-seo-reports";
+    runGeoSnapshots(snapshotsDir, argv.out);
+    return;
+  }
+
+  if (cmd === "rescore") {
+    const targetDir = argv._[1] || argv.dir;
+    if (!targetDir) {
+      console.error("Error: Missing target directory for rescore. Usage: lynx-audit rescore <dir>");
+      process.exit(1);
+    }
+    runRescore(targetDir);
+    return;
+  }
+
+  if (cmd === "render") {
+    const targetDir = argv._[1] || argv.dir;
+    if (!targetDir) {
+      console.error("Error: Missing target directory for render. Usage: lynx-audit render <dir>");
+      process.exit(1);
+    }
+    const formats = (argv.formats || "html,xlsx,md").split(",");
+    const reportLang = argv["report-lang"] || argv.reportLang || "en";
+    await runRender(targetDir, formats, reportLang);
+    return;
+  }
+
+  if (cmd === "audit" || cmd === "run") {
+    const url = argv._[1];
+    if (!url) {
+      console.error(`Error: Missing URL for ${cmd}. Usage: lynx-audit ${cmd} <url>`);
+      process.exit(1);
+    }
+
+    const reportLang = argv["report-lang"] || argv.reportLang || "en";
+    const outDir = await runAudit({
+      url,
+      out: argv.out,
+      maxPages: argv["max-pages"] ? parseInt(argv["max-pages"], 10) : undefined,
+      maxDepth: argv["max-depth"] ? parseInt(argv["max-depth"], 10) : undefined,
+      timeBudget: argv["time-budget"] ? parseInt(argv["time-budget"], 10) : undefined,
+      noPsi: Boolean(argv["no-psi"]),
+      psiPages: argv["psi-pages"] ? parseInt(argv["psi-pages"], 10) : undefined,
+      full: Boolean(argv.full),
+      locationCode: argv["location-code"] ? parseInt(argv["location-code"], 10) : undefined,
+      language: argv.language,
+      reportLang,
+      dfsBudget: argv["dfs-budget"] ? parseFloat(argv["dfs-budget"]) : undefined
+    });
+
+    if (cmd === "run") {
+      const formats = (argv.formats || "html,xlsx,md").split(",");
+      await runRender(outDir, formats, reportLang);
+    }
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}. Use lynx-audit --help for available commands.`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(`Fatal error: ${err.message}`);
+  process.exit(1);
+});

package/dist/ab-experiments-engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AB Experiments Engine — Gestionnaire complet du cycle de vie des expérimentations A/B
+ * Supporte le fractionnement de trafic, le calcul bayésien et fréquentiste, et le suivi des conversions.
+ */
+import { type VariantSignificance, type ExperimentStatus } from "./ab-testing-significance";
+export interface AbVariant {
+    id: string;
+    name: string;
+    isControl: boolean;
+    trafficWeight: number;
+    visitors: number;
+    conversions: number;
+    revenue?: number;
+}
+export type AbExperimentLifecycle = "draft" | "running" | "paused" | "concluded";
+export interface AbExperiment {
+    id: string;
+    projectId: string;
+    name: string;
+    description?: string;
+    targetUrlPattern: string;
+    goalEvent: string;
+    status: AbExperimentLifecycle;
+    startDate?: string;
+    endDate?: string;
+    variants: AbVariant[];
+    minimumDetectableEffect: number;
+    confidenceLevel: 0.9 | 0.95 | 0.99;
+}
+export interface AbExperimentEvaluation {
+    experimentId: string;
+    status: AbExperimentLifecycle;
+    statisticalStatus: ExperimentStatus;
+    winnerVariantId: string | null;
+    totalVisitors: number;
+    totalConversions: number;
+    variants: (VariantSignificance & {
+        trafficWeight: number;
+        winProbabilityPct: number;
+    })[];
+    recommendation: string;
+}
+export declare class AbExperimentsEngine {
+    private experiments;
+    createExperiment(experiment: Omit<AbExperiment, "id">): AbExperiment;
+    getExperiment(id: string): AbExperiment | undefined;
+    listExperiments(projectId?: string): AbExperiment[];
+    updateStatus(id: string, status: AbExperimentLifecycle): AbExperiment | undefined;
+    recordEvent(experimentId: string, variantId: string, type: "visit" | "conversion", revenue?: number): boolean;
+    /**
+     * Assigne un visiteur à une variante selon la répartition des poids de trafic.
+     */
+    assignVariant(experimentId: string, userIdOrSeed: string): AbVariant | null;
+    evaluateExperiment(experimentId: string): AbExperimentEvaluation | null;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * @license AGPL-3.0-or-later
+ *
+ * Multi-Armed Bandit (bandit multi-bras) pour les experiments A/B.
+ *
+ * Implémente un échantillonnage de Thompson beta-binomial : chaque bras
+ * (variante) est modélisé par une loi Beta(alpha, beta) où alpha = succès +
+ * 1 et beta = échecs + 1. À chaque décision, on tire un échantillon de chaque
+ * loi et on sert le bras dont l'échantillon est le plus élevé. Cela explore
+ * naturellement les variantes peu testées tout en exploitant les meilleures.
+ *
+ * Contrairement au test Z fréquentiste fixe, le bandit réalloue le trafic de
+ * manière continue : utile quand le coût d'attendre la significativité est
+ * élevé (ex. feature flag déployé sur un petit segment).
+ *
+ * Tout le calcul est pur et déterministe : une même suite d'observations
+ * produit toujours les mêmes sélections pour une même graine.
+ */
+export interface BanditArmObservation {
+    /** Identifiant stable de la variante. */
+    variantId: string;
+    /** Nombre de visiteurs exposés à cette variante. */
+    visitors: number;
+    /** Nombre de conversions observées pour cette variante. */
+    conversions: number;
+}
+export interface BanditSelection {
+    variantId: string;
+    /** Probabilité échantillonnée pour ce bras (entre 0 et 1). */
+    sampledProbability: number;
+    /** Taux de conversion observé (conversions / visiteurs, 0 si aucun visiteur). */
+    observedRate: number;
+    /** Nombre de visiteurs observés pour ce bras. */
+    visitors: number;
+}
+export interface BanditOptions {
+    /** Graine pour le générateur pseudo-aléatoire (défaut déterministe). */
+    seed?: string;
+    /**
+     * Facteur d'exploration : 1 = Thompson Sampling standard, >1 favorise
+     * l'exploration des bras peu testés, <1 favorise l'exploitation.
+     * Défaut : 1.
+     */
+    explorationFactor?: number;
+}
+export declare function selectBanditArm(observations: BanditArmObservation[], options?: BanditOptions): BanditSelection;
+export declare function updateBanditArm(observations: BanditArmObservation[], variantId: string, converted: boolean): BanditArmObservation[];
+export declare function winProbabilities(observations: BanditArmObservation[], options?: {
+    samples?: number;
+    seed?: string;
+}): Record<string, number>;

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

@@ -0,0 +1,70 @@
+/**
+ * 🧪 A/B Testing Engine with MDE Calculator & Statistical Guardrails
+ * Implements rigorous experimentation framework with sample size calculation,
+ * statistical significance testing, and protection against common pitfalls.
+ */
+export type TestMetricType = "conversion_rate" | "click_through_rate" | "revenue_per_user" | "engagement_score";
+export interface AbTestInput {
+    baselineRate: number;
+    mde: number;
+    alpha: number;
+    power: number;
+    ratio?: number;
+    testType?: TestMetricType;
+}
+export interface AbTestResult {
+    sampleSizePerVariant: number;
+    totalSampleSize: number;
+    durationDays: number;
+    isValid: boolean;
+    diagnostics: string[];
+    recommendedDuration: number;
+    confidenceInterval: [number, number];
+}
+export interface SrmCheck {
+    ratio: number;
+    expectedRatio: number;
+    chiSquare: number;
+    pValue: number;
+    isBalanced: boolean;
+}
+export interface PeekingGuard {
+    maxPeeks: number;
+    currentPeek: number;
+    adjustedAlpha: number;
+    shouldStop: boolean;
+}
+export declare class AbTestingEngine {
+    /**
+     * Calculate required sample size per variant for A/B test
+     * Uses standard formula for two-proportion z-test
+     */
+    static calculateSampleSize(input: AbTestInput): number;
+    /**
+     * Validate experiment design for common pitfalls
+     */
+    static validateExperimentDesign(input: AbTestInput, actualSampleSize?: number): AbTestResult;
+    /**
+     * Check for Sample Ratio Mismatch (SRM)
+     */
+    static checkSrm(observedCounts: number[], expectedRatios?: number[]): SrmCheck;
+    /**
+     * Calculate adjusted alpha for peeking protection (using Pocock boundary)
+     */
+    static calculatePeekingGuard(maxPeeks: number, currentPeek: number, alpha?: number): PeekingGuard;
+    /**
+     * Sequential testing with alpha-spending (Lan-DeMets approximation)
+     */
+    static sequentialTest(pValue: number, peekNumber: number, totalPlannedPeeks: number, alpha?: number): {
+        shouldReject: boolean;
+        adjustedAlpha: number;
+    };
+    private static normalQuantile;
+    private static chiSquareCdf;
+    private static gammaFn;
+    /**
+     * Calculate confidence interval for proportion difference
+     */
+    private static calculateConfidenceInterval;
+}
+export default AbTestingEngine;