@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/advanced-segmentation.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 🎯 Advanced Segmentation (G22)
+ *
+ * Advanced segmentation engine for LynxSEO:
+ * - Cohort segmentation (by signup/date, behavior)
+ * - RFM analysis (Recency, Frequency, Monetary)
+ * - Behavioral segments
+ * - Filter combinators AND/OR/NOT
+ * - Segment evaluation
+ *
+ * No external dependencies, pure TypeScript.
+ */
+export type AdvSegmentOperator = "equals" | "not_equals" | "contains" | "starts_with" | "ends_with" | "matches" | "greater_than" | "greater_than_or_equal" | "less_than" | "less_than_or_equal" | "in" | "not_in" | "is_null" | "is_not_null" | "between";
+export interface AdvSegmentCondition {
+    field: string;
+    operator: AdvSegmentOperator;
+    value?: string | number | boolean | Array<string | number> | null;
+    min?: number;
+    max?: number;
+}
+export type AdvSegmentCombinator = "AND" | "OR";
+export interface AdvFilterGroup {
+    combinator?: AdvSegmentCombinator;
+    conditions?: AdvSegmentCondition[];
+    groups?: AdvFilterGroup[];
+    negate?: boolean;
+    field?: string;
+    operator?: AdvSegmentOperator;
+    value?: any;
+    min?: number;
+    max?: number;
+}
+export interface AdvSegmentCriteria {
+    combinator?: AdvSegmentCombinator;
+    conditions?: AdvSegmentCondition[];
+    groups?: AdvFilterGroup[];
+    negate?: boolean;
+}
+export interface AdvSegmentRow {
+    id: string;
+    [key: string]: string | number | boolean | null | undefined | Date;
+}
+export interface SegmentEvaluationResult {
+    matchedIds: string[];
+    matchedRows: AdvSegmentRow[];
+    totalEvaluated: number;
+    matchCount: number;
+    matchRate: number;
+}
+export interface CohortDefinition {
+    name: string;
+    field: string;
+    startDate: string;
+    endDate: string;
+    includeUsers?: string[];
+}
+export interface CohortResult {
+    cohortName: string;
+    userIds: string[];
+    size: number;
+    startDate: string;
+    endDate: string;
+}
+export interface RFMScore {
+    userId: string;
+    recency: number;
+    frequency: number;
+    monetary: number;
+    rScore: number;
+    fScore: number;
+    mScore: number;
+    rfmScore: string;
+    segment: string;
+}
+export interface RFMConfig {
+    recencyWeight?: number;
+    frequencyWeight?: number;
+    monetaryWeight?: number;
+    quintiles?: boolean;
+}
+export interface BehavioralSegment {
+    name: string;
+    description: string;
+    criteria: AdvSegmentCriteria | AdvFilterGroup;
+}
+export interface BehavioralSegmentResult {
+    segmentName: string;
+    matchedIds: string[];
+    size: number;
+    matchRate: number;
+}
+export type SegmentOperator = AdvSegmentOperator;
+export type SegmentCondition = AdvSegmentCondition;
+export type SegmentCombinator = AdvSegmentCombinator;
+export type FilterGroup = AdvFilterGroup;
+export type SegmentCriteria = AdvSegmentCriteria;
+export type SegmentRow = AdvSegmentRow;
+export declare function evaluateSegment(rows: AdvSegmentRow[], criteria: AdvSegmentCriteria | AdvFilterGroup): SegmentEvaluationResult;
+export declare function buildDynamicSegment(rows: AdvSegmentRow[] | SegmentRow[], criteria: AdvSegmentCriteria | SegmentCriteria): SegmentEvaluationResult;
+export declare function createCohort(rows: AdvSegmentRow[], definition: CohortDefinition): CohortResult;
+export declare function createCohorts(rows: AdvSegmentRow[], definitions: CohortDefinition[]): CohortResult[];
+export declare function performRFMAnalysis(rows: AdvSegmentRow[], config?: RFMConfig): RFMScore[];
+export declare function createBehavioralSegment(name: string, description: string, criteria: AdvSegmentCriteria | AdvFilterGroup): BehavioralSegment;
+export declare function evaluateBehavioralSegments(rows: AdvSegmentRow[], segments: BehavioralSegment[]): BehavioralSegmentResult[];
+export declare class AdvancedSegmentationEngine {
+    private rows;
+    constructor(rows?: AdvSegmentRow[]);
+    setRows(rows: AdvSegmentRow[]): void;
+    addRows(rows: AdvSegmentRow[]): void;
+    getRows(): AdvSegmentRow[];
+    evaluate(criteria: AdvSegmentCriteria | AdvFilterGroup): SegmentEvaluationResult;
+    createCohort(definition: CohortDefinition): CohortResult;
+    createCohorts(definitions: CohortDefinition[]): CohortResult[];
+    performRFM(config?: RFMConfig): RFMScore[];
+    evaluateBehavioral(segments: BehavioralSegment[]): BehavioralSegmentResult[];
+}
+export declare const defaultAdvancedSegmentationEngine: AdvancedSegmentationEngine;

package/dist/aeo-geo-engine.d.ts

@@ -0,0 +1,366 @@
+/**
+ * 🤖 AeoGeoEngine : Generative Engine Optimization (GEO) & Answer Engine Optimization (AEO)
+ * Open-source LynxGEO Intelligence Engine for LynxSEO Studio
+ *
+ * Built according to the 2026 AI Search Specifications:
+ * 1. AI Search Visibility & Share of Voice Tracker (ChatGPT Search, Perplexity Pro, Google Gemini 2.0, Claude 3.7, DeepSeek)
+ * 2. Query Fan-Out Simulator (Models Google AI Overviews & Perplexity sub-queries)
+ * 3. AEO Direct Answer Writer (40-60 word concise passage, markdown comparison tables, entity linking)
+ * 4. Information Gain & Fact Density Scorer (Boosts AI citation probability by +40%)
+ * 5. Native /llms.txt & /llms-full.txt Generator for Agent Readiness
+ */
+export interface AiModelVisibility {
+    modelId: "chatgpt" | "perplexity" | "gemini" | "claude" | "deepseek";
+    modelName: string;
+    isBrandCited: boolean;
+    citationRank: number;
+    sentiment: "strongly_positive" | "positive" | "neutral" | "negative";
+    snippetQuote: string;
+    citedUrls: string[];
+}
+export interface QueryFanOutSubQuery {
+    subQuery: string;
+    intent: "definition" | "comparison" | "pricing" | "technical" | "troubleshooting";
+    searchIntentRelevance: number;
+    isCoveredInContent: boolean;
+}
+export interface PromptTrackingResult {
+    prompt: string;
+    brand: string;
+    competitors: string[];
+    shareOfVoice: number;
+    averageCitationRank: number;
+    overallSentiment: "positive" | "neutral" | "negative";
+    models: AiModelVisibility[];
+    fanOutQueries: QueryFanOutSubQuery[];
+    citedSources: {
+        domain: string;
+        url: string;
+        authorityScore: number;
+        isYourDomain: boolean;
+    }[];
+    recommendationTips: string[];
+}
+export interface AeoGeneratedArticle {
+    topic: string;
+    directAnswerSnippet: string;
+    structuredComparisonTableMarkdown: string;
+    keyFactualBulletPoints: string[];
+    fanOutSubSections: {
+        heading: string;
+        answerSnippet: string;
+    }[];
+    schemaJsonLd: string;
+    llmsTxtSnippet: string;
+    estimatedAiIngestionScore: number;
+    informationGainScore: number;
+}
+export interface AiPromptOpportunity {
+    prompt: string;
+    intent: "transactional" | "commercial" | "informational";
+    estimatedAiSearchVolume: number;
+    difficultyScore: number;
+    currentBrandPresence: boolean;
+}
+export interface AeoContentPatternAudit {
+    citationReadinessScore: number;
+    hasDirectDefinition: boolean;
+    hasComparisonTable: boolean;
+    quantifiedStatsCount: number;
+    hasConversationalFaq: boolean;
+    hasFirstPrinciplesSteps: boolean;
+    strengths: string[];
+    vulnerabilities: string[];
+    actionableOptimizations: string[];
+}
+export interface CitationVsRecommendationResult {
+    brand: string;
+    verdict: "RECOMMENDED_WINNER" | "NEUTRAL_REFERENCE" | "NEGATIVE_CRITIQUE" | "NOT_CITED";
+    recommendationConfidence: number;
+    snippet: string;
+    advice: string;
+}
+export interface AiCrawlerAuditItem {
+    name: string;
+    service: string;
+    category: "ai_search" | "ai_training";
+    isCritical: boolean;
+    status: "allowed" | "blocked" | "restricted";
+    recommendation: string;
+}
+export interface AiCrawlersAuditResult {
+    overallScore: number;
+    allowedCount: number;
+    blockedCount: number;
+    crawlers: AiCrawlerAuditItem[];
+    contentSignalsDeclared: boolean;
+    contentSignalDirectives: Record<string, string>;
+    hasSitemap: boolean;
+    recommendations: string[];
+}
+export interface PassageCitabilityDimension {
+    dimension: string;
+    weightPercent: number;
+    score: number;
+    feedback: string;
+}
+export interface PassageCitabilityResult {
+    overallCitabilityScore: number;
+    grade: "S" | "A" | "B" | "C" | "F";
+    verdict: "CITATION_READY" | "NEEDS_OPTIMIZATION" | "CITATION_UNLIKELY";
+    dimensions: {
+        answerBlockQuality: PassageCitabilityDimension;
+        selfContainment: PassageCitabilityDimension;
+        structuralReadability: PassageCitabilityDimension;
+        statisticalDensity: PassageCitabilityDimension;
+        uniqueness: PassageCitabilityDimension;
+    };
+    keyStrengths: string[];
+    actionableImprovements: string[];
+    optimizedRewriteSuggestion: string;
+}
+export interface PlatformReadinessItem {
+    platformId: "google_aio" | "chatgpt" | "perplexity" | "gemini" | "claude";
+    platformName: string;
+    score: number;
+    verdict: "OPTIMAL" | "BONNE" | "A RENFORCER" | "FAIBLE";
+    keySignals: string[];
+    criticalAction: string;
+}
+export interface PlatformReadinessMatrix {
+    overallPlatformReadinessScore: number;
+    platforms: PlatformReadinessItem[];
+    summary: string;
+}
+export declare class AeoGeoEngine {
+    /**
+     * 🎯 1. Track brand citations, Share of Voice, and Query Fan-Out across AI Search Engines
+     */
+    static trackPrompt(options: {
+        prompt: string;
+        brand: string;
+        competitors?: string[];
+        domain?: string;
+    }): PromptTrackingResult;
+    /**
+     * ✍️ 2. AEO AI Content Writer: Formats content specifically engineered for AI ingestion & Information Gain
+     */
+    static generateAeoArticle(options: {
+        topic: string;
+        brand?: string;
+        keyFeatures?: string[];
+    }): AeoGeneratedArticle;
+    /**
+     * 🔍 3. Discover high-converting conversational prompts asked to ChatGPT & Perplexity
+     */
+    static discoverAiPrompts(industry: string): AiPromptOpportunity[];
+    /**
+     * 🤖 4. Audit Content Patterns that trigger LLM citations
+     */
+    static auditContentPatterns(content: string): AeoContentPatternAudit;
+    /**
+     * 🏆 5. Score Citation vs Recommendation
+     * Distinguishes whether the brand is merely cited as a passive source or recommended as the winning solution.
+     */
+    static scoreCitationVsRecommendation(snippet: string, brand: string): CitationVsRecommendationResult;
+    /**
+     * 🤖 6. Audit 12 Critical AI Crawlers & IETF Content-Signal Directives
+     * Checks crawler permissions (GPTBot, ClaudeBot, PerplexityBot, etc.) according to RFC 9309 rules.
+     */
+    static audit12AiCrawlers(robotsTxtContent?: string, contentSignalsHeader?: string): AiCrawlersAuditResult;
+    /**
+     * 📝 7. Audit Passage Citability (5 Dimensions de Citabilité par IA)
+     * Evaluates content blocks for quoting and citation readiness by ChatGPT, Perplexity, and Claude.
+     */
+    static auditPassageCitability(passage: string, entityTerm?: string): PassageCitabilityResult;
+    /**
+     * 🌐 8. Audit Platform-Specific Optimization (5 Moteurs IA Majeurs)
+     * Scores optimization readiness for Google AI Overviews, ChatGPT Search, Perplexity AI, Google Gemini, and Claude.
+     */
+    static auditPlatformReadiness(options: {
+        domain?: string;
+        brand?: string;
+        hasWikipediaEntity?: boolean;
+        hasRedditMentions?: boolean;
+        hasComparisonTables?: boolean;
+        hasLlmsTxt?: boolean;
+        hasSchemaJsonLd?: boolean;
+    }): PlatformReadinessMatrix;
+    /**
+     * 📄 7. Générateur et Validateur de fichiers /llms.txt et /llms-full.txt
+     * Conforme à la spécification officielle standard llmstxt.org.
+     */
+    static generateAndValidateLlmsTxt(input: LlmsTxtBuilderInput): LlmsTxtResult;
+    /**
+     * 💼 8. Generateur de Proposition Commerciale GEO & AEO pour Agences (geo-proposal)
+     * Calcule dynamiquement le ROI de l'optimisation IA et le risque d'inaction.
+     */
+    static generateAgencyProposal(input: AgencyProposalInput): AgencyProposalResult;
+    /**
+     * 🌐 9. Audit de l'Empreinte de Citations sur les Sources Tierces de l'IA (geo-brands)
+     * Analyse la presence sur Reddit, Quora, Wikipedia, G2 et presse de reference.
+     */
+    static auditAiSourceFootprint(input: AiSourceFootprintInput): AiSourceFootprintResult;
+}
+export interface LlmsTxtSection {
+    title: string;
+    description?: string;
+    links: {
+        title: string;
+        url: string;
+        summary: string;
+    }[];
+}
+export interface LlmsTxtBuilderInput {
+    siteName: string;
+    siteUrl: string;
+    summary: string;
+    details?: string;
+    sections?: LlmsTxtSection[];
+    optionalLinks?: {
+        title: string;
+        url: string;
+        summary: string;
+    }[];
+}
+export interface LlmsTxtValidationCheck {
+    code: string;
+    level: "success" | "warning" | "error";
+    message: string;
+}
+export interface LlmsTxtResult {
+    llmsTxt: string;
+    llmsFullTxt: string;
+    isValid: boolean;
+    score: number;
+    validationChecks: LlmsTxtValidationCheck[];
+    stats: {
+        titleLength: number;
+        sectionsCount: number;
+        linksCount: number;
+        estimatedTokens: number;
+    };
+}
+export interface AgencyProposalInput {
+    clientName: string;
+    websiteUrl: string;
+    industry: string;
+    monthlyOrganicVisits: number;
+    averageConversionRatePercent: number;
+    averageCustomerValueEur: number;
+    estimatedAiTrafficShiftPercent?: number;
+    currency?: string;
+}
+export interface ProposalTier {
+    id: "starter" | "scale" | "enterprise";
+    name: string;
+    badge: string;
+    monthlyPriceEur: number;
+    durationMonths: number;
+    features: string[];
+    deliverables: string[];
+    expectedCitationLiftPercent: number;
+    expectedMonthlyRetainedRevenueEur: number;
+}
+export interface AgencyProposalResult {
+    clientName: string;
+    websiteUrl: string;
+    industry: string;
+    currency: string;
+    metrics: {
+        monthlyOrganicVisits: number;
+        atRiskMonthlyTraffic: number;
+        atRiskMonthlyRevenueEur: number;
+        annualAtRiskRevenueEur: number;
+        projectedNewAiReferralVisits: number;
+        projectedAnnualAiRevenueLiftEur: number;
+        paybackMonthsEstimated: number;
+    };
+    tiers: ProposalTier[];
+    executiveSummary: string;
+    commercialPitchMarkdown: string;
+}
+export interface AiSourceChannelStatus {
+    id: "reddit_forums" | "knowledge_bases" | "social_proof" | "technical_auth" | "authoritative_press";
+    name: string;
+    weightPercent: number;
+    currentPresenceScore: number;
+    citationLikelihood: "HIGH" | "MEDIUM" | "LOW" | "CRITICAL_MISSING";
+    detectedSignals: string[];
+    missingSignals: string[];
+    recommendedPlaybook: string;
+}
+export interface AiSourceFootprintInput {
+    brandName: string;
+    domain: string;
+    industry: string;
+    hasRedditDiscussions?: boolean;
+    hasWikipediaPage?: boolean;
+    hasG2TrustpilotReviews?: boolean;
+    hasGithubOrTechDocs?: boolean;
+    hasAuthoritativePressMentions?: boolean;
+    estimatedReviewCount?: number;
+}
+export interface AiSourceFootprintResult {
+    brandName: string;
+    domain: string;
+    industry: string;
+    overallFootprintScore: number;
+    maturityTier: "LEADER" | "STRONG" | "EMERGING" | "INVISIBLE_TO_AI";
+    channels: AiSourceChannelStatus[];
+    highestImpactQuickWin: string;
+    syndicationChecklist: {
+        step: string;
+        platform: string;
+        priority: "P1" | "P2" | "P3";
+    }[];
+}
+export type GeoProspectStage = "AUDIT_SENT" | "CALL_SCHEDULED" | "PROPOSAL_SENT" | "NEGOTIATION" | "WON" | "LOST";
+export interface GeoProspect {
+    id: string;
+    clientName: string;
+    domain: string;
+    contactEmail: string;
+    stage: GeoProspectStage;
+    tierSelected: "starter" | "scale" | "enterprise";
+    monthlyPriceEur: number;
+    auditScore: number;
+    notes?: string;
+    updatedAt: string;
+}
+export interface GeoProspectPipelineSummary {
+    totalProspectsCount: number;
+    activeProspectsCount: number;
+    totalUnweightedMrrEur: number;
+    weightedForecastMrrEur: number;
+    annualRunRateEur: number;
+    winRatePercent: number;
+    stageCounts: Record<GeoProspectStage, number>;
+    stageWeightedMrr: Record<GeoProspectStage, number>;
+}
+export declare class GeoProspectPipelineEngine {
+    static readonly STAGE_PROBABILITIES: Record<GeoProspectStage, number>;
+    static readonly TIER_PRICES: Record<"starter" | "scale" | "enterprise", number>;
+    static calculatePipeline(prospects: GeoProspect[]): GeoProspectPipelineSummary;
+    static getInitialDemoProspects(): GeoProspect[];
+}
+export declare class GeoSchemaAiEngine {
+    static generateOrganizationGraph(params: {
+        legalName: string;
+        url: string;
+        logoUrl?: string;
+        description: string;
+        wikidataId?: string;
+        wikipediaUrl?: string;
+        socialProfiles: string[];
+    }): string;
+    static generateFaqPageSchema(questions: {
+        question: string;
+        answerText: string;
+    }[]): string;
+    static generateSpeakableSchema(params: {
+        url: string;
+        headline: string;
+        cssSelectors: string[];
+    }): string;
+}

package/dist/agent-skills-registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent Skills Registry for LynxSEO Engine
+ *
+ * Defines built-in agent skills with metadata, MCP tools, and prompt templates
+ */
+export interface SkillDefinition {
+    name: string;
+    description: string;
+    mcpTools: string[];
+    promptTemplate: string;
+}
+declare const BUILTIN_SKILLS: SkillDefinition[];
+/**
+ * Register a new skill in the registry
+ */
+export declare function registerSkill(skill: SkillDefinition): void;
+/**
+ * Get a skill by name
+ */
+export declare function getSkill(name: string): SkillDefinition | undefined;
+/**
+ * List all registered skills
+ */
+export declare function listSkills(): SkillDefinition[];
+/**
+ * Find skills by MCP tool name
+ */
+export declare function findSkillsByTool(toolName: string): SkillDefinition[];
+export { BUILTIN_SKILLS };

package/dist/agent-ux-scorer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 🤖 Agent-UX Score & Agentic Browsing Readiness
+ *
+ * Scores how easily AI agents (ChatGPT/OpenAI, Claude, Perplexity, Gemini and
+ * agentic crawlers / Agentic Browsing Lighthouse) can scrape and understand a
+ * page. Based on the accessibility-tree / semantic-signal approach: agents
+ * navigate a DOM the way assistive tech does, so semantic HTML and exposed
+ * accessibility states directly raise the score.
+ */
+export interface AgentUxSignal {
+    /** Number of semantic landmarks (<header>, <nav>, <main>, <footer>…). */
+    landmarkCount: number;
+    /** Number of `<h1>`..`<h6>` elements. */
+    headingCount: number;
+    /** Whether a heading containing the target query text exists. */
+    hasTargetHeading: boolean;
+    /** Total words of main readable text (after stripping nav/scripts). */
+    readableTextLength: number;
+    /** Number of elements carrying aria-label / aria-labelledby / role. */
+    ariaAnnotatedCount: number;
+    /** Links that have an accessible name (text or aria-label). */
+    namedLinksCount: number;
+    totalLinksCount: number;
+    /** Whether the main content is reachable via skip-link. */
+    hasSkipLink: boolean;
+    /** Whether images expose meaningful alt text (non-empty, non-decorative). */
+    meaningfulAltCount: number;
+    imageCount: number;
+    /** Presence of a Direct-Answer-ready ~40-60 word summary block for GEO. */
+    hasDirectAnswerBlock: boolean;
+    /** Whether key facts are machine-readable (JSON-LD / meta). */
+    hasStructuredData: boolean;
+}
+export interface AgentUxScoreResult {
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    dimensionScores: {
+        semantics: number;
+        headings: number;
+        navigation: number;
+        accessibility: number;
+        geoDirectAnswers: number;
+    };
+    recommendations: string[];
+}
+/**
+ * Computes a 0-100 Agent-UX score from lightweight, DOM-derived signals.
+ * Heuristic model — mirrors the spirit of the Lighthouse "Agentic Browsing"
+ * category without a full Chromium run.
+ */
+export declare class AgentUxScorer {
+    static score(signals: AgentUxSignal): AgentUxScoreResult;
+}

package/dist/agentic-ads-guardrails.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 🛡️ LynxSEO Agentic Ads Guardrails & Cryptographic Proposal Token Service
+ *
+ * Repris et adapté sous licence MIT depuis inspiration/03-social-ad-intelligence/repos/nalarin-agentic-ads-studio (backend/app/core/executor.py).
+ *
+ * Fonctionnalités critiques :
+ * 1. Jeton de proposition cryptographique (HMAC-SHA256) avec TTL 10 minutes.
+ * 2. Hachage canonique du payload (SHA-256) pour garantir l'intégrité absolue de la mutation.
+ * 3. Hachage d'état (state hash) pour empêcher les attaques par rejeu ou modifications concurrentes.
+ * 4. Garde-fous budgétaires stricts (Plafond par action, plafond cumulé 24h, compteur d'actions).
+ * 5. Kill-Switch global d'urgence (arrêt immédiat de toute mutation payante).
+ * 6. Principe Fail-Closed : toute nouvelle campagne est créée impérativement au statut "PAUSED".
+ */
+export declare const ALLOWED_MUTATION_ACTIONS: readonly ["campaign.create", "campaign.pause", "campaign.enable", "budget.update", "adset.update", "ad.pause"];
+export type MutationAction = (typeof ALLOWED_MUTATION_ACTIONS)[number];
+export declare const DEFAULT_PROPOSAL_TOKEN_TTL_SEC = 600;
+export interface MutationBudgetPolicy {
+    /** Budget maximal par action individuelle en micros (ex: 50_000_000 = 50.00$) */
+    maxBudgetMicrosPerAction: number;
+    /** Dépense maximale cumulée par 24h en micros (ex: 200_000_000 = 200.00$) */
+    maxDailySpendMicros: number;
+    /** Nombre maximal d'actions automatisées par fenêtre de 24h */
+    maxActionsPerDay: number;
+    /** Statut forcé pour toute création de campagne (Fail-Closed) */
+    enforcePausedOnCreation: boolean;
+}
+export declare const DEFAULT_BUDGET_POLICY: MutationBudgetPolicy;
+export interface ProposalPayload {
+    action: MutationAction;
+    provider: "meta" | "google" | "tiktok" | "linkedin";
+    accountId: string;
+    campaignId?: string;
+    campaignName?: string;
+    budgetMicros?: number;
+    status?: "PAUSED" | "ACTIVE";
+    parameters?: Record<string, unknown>;
+}
+export interface ProposalTokenEnvelope {
+    actor: string;
+    provider: string;
+    accountId: string;
+    action: MutationAction;
+    payloadHash: string;
+    stateHash: string;
+    issuedAt: number;
+    signature: string;
+}
+export declare class AgenticAdsGuardrails {
+    /**
+     * Calcule le hash canonique et déterministe d'un payload JSON (SHA-256).
+     * Les clés sont triées alphabétiquement pour garantir un hash identique quel que soit l'ordre d'insertion.
+     */
+    static canonicalPayloadHash(payload: Record<string, unknown>): string;
+    /**
+     * Signe une proposition d'action avec HMAC-SHA256.
+     */
+    static signProposal(params: {
+        secret: string;
+        actor: string;
+        provider: string;
+        accountId: string;
+        action: MutationAction;
+        payloadHash: string;
+        stateHash: string;
+        issuedAt?: number;
+    }): ProposalTokenEnvelope;
+    /**
+     * Vérifie la validité d'un jeton de proposition cryptographique.
+     */
+    static verifyProposal(params: {
+        secret: string;
+        envelope: ProposalTokenEnvelope;
+        expectedPayload: Record<string, unknown>;
+        expectedStateHash: string;
+        ttlSeconds?: number;
+        currentTimeSec?: number;
+        killSwitchActive?: boolean;
+    }): {
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * Évalue si la mutation demandée respecte les plafonds budgétaires et la politique Fail-Closed.
+     */
+    static evaluateBudgetPolicy(proposal: ProposalPayload, context: {
+        spentTodayMicros: number;
+        actionsTodayCount: number;
+        policy?: Partial<MutationBudgetPolicy>;
+    }): {
+        allowed: boolean;
+        violationReason?: string;
+        safePayload: ProposalPayload;
+    };
+}