@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/agentic-browsing-auditor.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 🤖 AgenticBrowsingAuditor — Lighthouse Agentic Browsing & AI Protocol Readiness
+ *
+ * Evaluates a site's readiness for autonomous AI agents that browse, fill forms, and transact:
+ *
+ * 1. Lighthouse Agentic Browsing Fraction (X/N, max 6 criteria):
+ *    - Accessibility Tree for Agents (valid button roles, labels)
+ *    - CLS <= 0.1 (Stable layouts, no shifting buttons)
+ *    - Server-Rendered Content (no empty JS-only shell)
+ *    - Deliberate robots.txt groups for AI purposes
+ *    - /llms.txt compliance
+ *    - WebMCP tools registered
+ * 2. Content-Signal directive in robots.txt:
+ *    - e.g. "Content-Signal: ai-train=no, ai-input=yes, search=yes"
+ * 3. Markdown Delivery & Content Negotiation:
+ *    - Support for "Accept: text/markdown", Vary: Accept, or .md siblings
+ * 4. Agentic Resource Discovery (ARD):
+ *    - /.well-known/ai-catalog.json
+ *    - /.well-known/agent-card.json (A2A protocol)
+ *    - /.well-known/ucp (Universal Commerce Protocol for AI shopping agents)
+ */
+export interface AgenticAuditorInput {
+    url: string;
+    html: string;
+    robotsTxt?: string;
+    responseHeaders?: Record<string, string>;
+    clsScore?: number;
+}
+export interface AgenticAuditFinding {
+    criterion: string;
+    status: "pass" | "warn" | "fail" | "info";
+    priority: "P0" | "P1" | "P2" | "P3";
+    title: string;
+    description: string;
+    recommendation: string;
+}
+export interface AgenticBrowsingReport {
+    url: string;
+    lighthouseFraction: string;
+    passedAuditsCount: number;
+    totalAuditsCount: number;
+    readinessPercentage: number;
+    contentSignal: {
+        present: boolean;
+        rawDirective?: string;
+        allowsAiSearch: boolean;
+        allowsAiInput: boolean;
+        allowsAiTraining: boolean;
+    };
+    markdownDelivery: {
+        hasMarkdownAlternate: boolean;
+        hasAcceptMarkdownSupport: boolean;
+        links: string[];
+    };
+    discoveryProtocols: {
+        aiCatalogFound: boolean;
+        agentCardFound: boolean;
+        ucpCommerceFound: boolean;
+    };
+    findings: AgenticAuditFinding[];
+    prioritizedPlan: string[];
+}
+export declare class AgenticBrowsingAuditor {
+    static audit(input: AgenticAuditorInput): AgenticBrowsingReport;
+}

package/dist/ai-bots-log-analyzer.d.ts

@@ -1,5 +1,5 @@
 /**
- * 📊 Server Crawl & AI Bots Log Analyzer (Inspiration: advertools/crawlytics.py & logs.py)
+ * 📊 Server Crawl & AI Bots Log Analyzer
  *
  * Analyzes access log lines from Nginx, Apache, or Cloudflare to track real crawl activity
  * from Googlebot, GPTBot, ClaudeBot, PerplexityBot, and identify status anomalies.
@@ -13,7 +13,7 @@ export interface LogLine {
     bytesSent: number;
     userAgent: string;
 }
-export type BotFamily = "googlebot-mobile" | "googlebot-desktop" | "gptbot" | "claudebot" | "perplexitybot" | "bingbot" | "generic-crawler" | "human-visitor";
+export type BotFamily = "googlebot-mobile" | "googlebot-desktop" | "gptbot" | "claudebot" | "perplexitybot" | "deepseekbot" | "bytespider" | "qwenbot" | "geminibot" | "baidubot" | "moonshotbot" | "mistralbot" | "bingbot" | "generic-crawler" | "human-visitor";
 export interface BotCrawlMetrics {
     botFamily: BotFamily;
     totalHits: number;
@@ -33,4 +33,8 @@ export declare class AiBotsLogAnalyzer {
      * Aggregates an array of parsed log lines into comprehensive crawl metrics per bot family.
      */
     static aggregateCrawlStats(logs: LogLine[]): Record<BotFamily, BotCrawlMetrics>;
+    /**
+     * Parses raw Nginx / Apache / Cloudflare log lines or JSON logs into LogLine objects.
+     */
+    static parseAccessLogs(rawText: string): LogLine[];
 }

package/dist/ai-citation-auditor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 🤖 AI Citation Auditor & AEO Ecosystem Mapper
+ * Audits brand visibility across AI Answer Engines (Perplexity, ChatGPT Search, Claude, Google AI Overviews).
+ * Identifies high-authority citation platforms (Reddit, Wikipedia, Wikidata, G2, Niche Directories)
+ * where competitors are cited and produces an actionable AEO citation roadmap.
+ */
+export interface CitationPlatformProfile {
+    platformName: string;
+    category: "community_discussion" | "knowledge_graph" | "b2b_reviews" | "authoritative_media" | "developer_ecosystem";
+    weight: number;
+    targetUrl?: string;
+    isBrandPresent: boolean;
+    competitorPresence: string[];
+    citationStrength: "strong" | "moderate" | "weak" | "absent";
+    recommendedAction: string;
+}
+export interface AiCitationAuditInput {
+    brandName: string;
+    domain: string;
+    competitors: string[];
+    targetKeywords: string[];
+    existingPlatformProfiles?: Partial<CitationPlatformProfile>[];
+}
+export interface AiCitationAuditReport {
+    brandName: string;
+    domain: string;
+    overallCitationScore: number;
+    ecosystemCoverageScore: number;
+    competitorGapCount: number;
+    platforms: CitationPlatformProfile[];
+    highPriorityGaps: CitationPlatformProfile[];
+    citationRoadmap: string[];
+}
+export declare class AiCitationAuditor {
+    static readonly DEFAULT_AEO_PLATFORMS: Omit<CitationPlatformProfile, "isBrandPresent" | "competitorPresence" | "citationStrength" | "recommendedAction">[];
+    /**
+     * Conducts a comprehensive AI Citation Audit.
+     */
+    static audit(input: AiCitationAuditInput): AiCitationAuditReport;
+}

package/dist/ai-citation-tracker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AI citation time series: per-platform citation rate, trend direction and
+ * spike/drop alerts against a rolling baseline. Observations are the output of
+ * `live-ai-citation-tester` / `geo-citation-scorer` runs.
+ */
+export type AiCitationPlatform = "chatgpt" | "perplexity" | "claude" | "gemini" | "copilot" | "google_ai_overview";
+export interface CitationObservation {
+    /** ISO date (`YYYY-MM-DD`). */
+    date: string;
+    platform: AiCitationPlatform;
+    query: string;
+    cited: boolean;
+    position?: number;
+    sentiment?: number;
+}
+export interface CitationPoint {
+    date: string;
+    observations: number;
+    cited: number;
+    citationRate: number;
+    averagePosition: number | null;
+}
+export interface CitationSeries {
+    platform: AiCitationPlatform;
+    points: CitationPoint[];
+    trend: "up" | "down" | "flat";
+    changePct: number;
+}
+export interface CitationAnomalyOptions {
+    baselineWindow?: number;
+    minObservations?: number;
+    dropThresholdPct?: number;
+    spikeThresholdPct?: number;
+}
+export interface CitationAnomaly {
+    date: string;
+    platform: AiCitationPlatform;
+    observedRate: number;
+    expectedRate: number;
+    deltaPct: number;
+    direction: "spike" | "drop";
+    severity: "low" | "medium" | "high";
+}
+export interface PlatformVisibility {
+    platform: AiCitationPlatform;
+    observations: number;
+    cited: number;
+    citationRate: number;
+    shareOfVoice: number;
+}
+export declare function buildCitationTimeSeries(observations: readonly CitationObservation[]): CitationSeries[];
+export declare function detectCitationAnomalies(series: readonly CitationSeries[], options?: CitationAnomalyOptions): CitationAnomaly[];
+export declare function summarizePlatformVisibility(observations: readonly CitationObservation[]): PlatformVisibility[];

package/dist/ai-copilot-client.d.ts

@@ -13,6 +13,7 @@ export interface GenerateArticleParams {
     locale?: string;
     enableRag?: boolean;
     siteId?: string;
+    contentPlan?: GenerateArticleParams;
 }
 export interface GeneratedArticleResult {
     title: string;

package/dist/ai-safety-auditor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 🛡️ AI Safety & RAG Readiness Auditor
+ *
+ * Implements:
+ * 1. Prompt Injection & AI manipulation pattern detection (UC Berkeley EMNLP 2024)
+ * 2. RAG Chunk Readiness scoring
+ * 3. Hallucination Bait Detection (Anthropic AI Safety & Berkeley)
+ * 4. WebMCP Browser Agent Readiness
+ */
+export interface PromptInjectionFinding {
+    type: "hidden_css" | "invisible_unicode" | "llm_instruction" | "html_comment" | "micro_font" | "data_attribute" | "aria_hidden_abuse";
+    snippet: string;
+    severity: "critical" | "high" | "medium";
+    description: string;
+}
+export interface PromptInjectionReport {
+    isSafe: boolean;
+    threatLevel: "NONE" | "LOW" | "HIGH" | "CRITICAL";
+    findings: PromptInjectionFinding[];
+    score: number;
+}
+export interface RagChunkReport {
+    score: number;
+    totalSections: number;
+    sectionsInOptimalRange: number;
+    averageSectionWords: number;
+    hasDefinitionOpening: boolean;
+    headingBoundariesRatio: number;
+    isRagOptimized: boolean;
+    recommendations: string[];
+}
+export interface HallucinationBaitReport {
+    score: number;
+    unsourcedStatsCount: number;
+    absoluteClaimsCount: number;
+    vagueRangesCount: number;
+    unsupportedProjectionsCount: number;
+    riskLevel: "LOW" | "MODERATE" | "HIGH";
+    findings: string[];
+}
+export interface WebMcpReport {
+    isReady: boolean;
+    score: number;
+    hasSearchAction: boolean;
+    hasPotentialAction: boolean;
+    hasToolAttributes: boolean;
+    hasLabeledForms: boolean;
+    featuresDetected: string[];
+}
+export declare class AiSafetyAuditor {
+    /**
+     * 1. Detect prompt injections and adversarial manipulations in HTML.
+     */
+    static auditPromptInjections(html: string): PromptInjectionReport;
+    /**
+     * 2. Audit content segmentation for RAG chunk retrieval (SE Ranking 2026: 100-150 words = 4.7x citation).
+     */
+    static auditRagChunkReadiness(html: string): RagChunkReport;
+    /**
+     * 3. Detect patterns triggering LLM hallucinations (Anthropic AI Safety).
+     */
+    static auditHallucinationBait(text: string): HallucinationBaitReport;
+    /**
+     * 4. Audit WebMCP readiness for browser AI agents (W3C / Chrome WebMCP).
+     */
+    static auditWebMcpReadiness(html: string): WebMcpReport;
+}

package/dist/ai-targeting-translator.d.ts

@@ -0,0 +1,24 @@
+import { TargetingRules, TargetingContext } from "./lynx-pulse-prism-engine";
+export interface NaturalLanguageTargetingPrompt {
+    prompt: string;
+}
+export interface GeneratedTargetingRulesResult {
+    rules: TargetingRules;
+    matchedConcepts: string[];
+    explanation: string;
+    confidenceScore: number;
+}
+/**
+ * AI Targeting Rule Translator (Alia Parity)
+ * Transforme des prompts en langage naturel (FR / EN) en règles déterministes de ciblage CRO.
+ */
+export declare class AiTargetingTranslator {
+    /**
+     * Traduit un prompt en langage naturel en règles de ciblage exécutables.
+     */
+    static translatePrompt(input: string): GeneratedTargetingRulesResult;
+    /**
+     * Valide si le résultat traduit fonctionne correctement sur un contexte donné.
+     */
+    static testContext(rules: TargetingRules, context: TargetingContext): boolean;
+}

package/dist/ai-visibility-tracker.d.ts

@@ -0,0 +1,70 @@
+export type AiMatchType = "own" | "mentioned" | "cited";
+export interface AiPrompt {
+    readonly id: string;
+    readonly text: string;
+    readonly version: number;
+    archived: boolean;
+    readonly createdAt: string;
+    readonly parentId: string | null;
+}
+export interface AiObservation {
+    id: string;
+    runId: string;
+    platform: string;
+    brandMentioned: boolean;
+    cited: boolean;
+    mentioned: boolean;
+    firstMentionOffset: number | null;
+    shareOfVoice: number;
+    recordedAt: string;
+}
+export interface AiSource {
+    id: string;
+    runId: string;
+    url: string;
+    domain: string;
+    title: string;
+    recordedAt: string;
+}
+export interface AiMatch {
+    id: string;
+    sourceId: string;
+    type: AiMatchType;
+    brand: string;
+    recordedAt: string;
+}
+export interface AiRun {
+    id: string;
+    trackerId: string;
+    promptId: string;
+    promptVersion: number;
+    scheduledAt: string;
+    status: "scheduled" | "running" | "completed" | "failed";
+    observations: AiObservation[];
+    sources: AiSource[];
+    matches: AiMatch[];
+    completedAt: string | null;
+}
+export interface AiTracker {
+    id: string;
+    name: string;
+    brand: string;
+    prompts: AiPrompt[];
+    runs: AiRun[];
+    createdAt: string;
+}
+export declare function createTracker(name: string, brand: string): AiTracker;
+export declare function addPrompt(tracker: AiTracker, text: string): AiPrompt;
+export declare function scheduleRun(tracker: AiTracker, promptId: string, scheduledAt?: string): AiRun;
+export declare function recordObservation(run: AiRun, data: Omit<AiObservation, "id" | "runId" | "recordedAt">): AiObservation;
+export declare function recordSource(run: AiRun, data: Omit<AiSource, "id" | "runId" | "recordedAt">): AiSource;
+export declare function recordMatch(run: AiRun, sourceId: string, type: AiMatchType, brand: string): AiMatch;
+export declare function computeTrend(run: AiRun): {
+    direction: "up" | "down" | "flat";
+    delta: number;
+};
+export declare function computeRetention(tracker: AiTracker): {
+    promptId: string;
+    retentionRate: number;
+}[];
+export declare function completeRun(run: AiRun): void;

package/dist/alerting-thresholds.d.ts

@@ -0,0 +1,63 @@
+/**
+ * G3 — Alerting / Thresholds.
+ *
+ * Evaluates metric snapshots against configurable thresholds and produces
+ * Slack / Email ready alert payloads. Channels are configured by the
+ * consumer — no webhooks, tokens or credentials are embedded here.
+ *
+ * Built-in rules:
+ * - traffic drop greater than the configured percentage
+ * - JavaScript error count above the allowed maximum
+ * - massive deindexing (pages dropped from the index)
+ */
+export type AlertMetric = "traffic" | "jsErrors" | "deindexedPages" | "indexability";
+export type AlertSeverity = "warning" | "error" | "critical";
+export type AlertChannel = "slack" | "email";
+export interface AlertCondition {
+    name: string;
+    metric: AlertMetric;
+    /** Percentage for rate metrics, absolute count for count metrics. */
+    threshold: number;
+    operator: ">" | "<";
+    severity: AlertSeverity;
+}
+export interface AlertResult {
+    triggered: boolean;
+    alerts: string[];
+    /** Slack message payload (blocks-style text) when slack channel is enabled. */
+    slackPayload: {
+        text: string;
+        severity: AlertSeverity;
+    } | null;
+    /** Email payload when email channel is enabled. */
+    emailPayload: {
+        subject: string;
+        body: string;
+        severity: AlertSeverity;
+    } | null;
+    timestamp: string;
+    metricSnapshot: Record<string, number>;
+}
+export interface AlertConfig {
+    /** Percentage drop of traffic that triggers an alert (default 20). */
+    trafficDropPercent?: number;
+    /** Absolute number of JS errors above which an alert fires (default 5). */
+    maxJsErrors?: number;
+    /** Number of deindexed pages above which an alert fires (default 100). */
+    maxDeindexedPages?: number;
+    /** Channels to deliver to (default slack + email). */
+    channels?: AlertChannel[];
+    /** Optional webhook target supplied by the consumer. */
+    webhookUrl?: string;
+}
+export declare class AlertingThresholdEngine {
+    private readonly config;
+    constructor(config?: AlertConfig);
+    /**
+     * Evaluates a metric snapshot (optionally against a previous snapshot) and
+     * returns the triggered alerts plus the channel payloads.
+     */
+    evaluate(snapshot: Record<string, number>, previous?: Record<string, number>): AlertResult;
+    /** Describes the active thresholds, useful for a status endpoint. */
+    describeThresholds(): AlertCondition[];
+}

package/dist/analytics/active-dwell-time-calculator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ActiveDwellTimeCalculator — Calcul du temps d'attention réelle vs onglets en arrière-plan (Parité Matomo Ping / PostHog Heartbeat).
+ *
+ * Mesure avec précision :
+ * - Le temps d'engagement actif (onglets visibles avec interactions souris/clavier/scroll)
+ * - Le temps passif / inactif (temps mort au-delà du seuil d'inactivité)
+ * - Le temps masqué (onglets en tâche de fond via visibilitychange ou window blur)
+ * - La segmentation de l'attention (Zombie session, Lecteur passif, Utilisateur hautement engagé)
+ */
+export type DwellEventType = "focus" | "blur" | "visibility_visible" | "visibility_hidden" | "scroll" | "click" | "mousemove" | "keydown" | "heartbeat";
+export interface DwellRawEvent {
+    sessionId: string;
+    pageUrl: string;
+    eventType: DwellEventType;
+    timestamp: number | string;
+}
+export interface DwellTimeOptions {
+    idleTimeoutSeconds?: number;
+    maxIntervalGapSeconds?: number;
+}
+export type DwellEngagementCategory = "zombie_session" | "bounced" | "passive_reader" | "active_engager";
+export interface SessionDwellMetrics {
+    sessionId: string;
+    pageUrl: string;
+    totalDurationSeconds: number;
+    activeSeconds: number;
+    idleSeconds: number;
+    hiddenSeconds: number;
+    activeRatioPct: number;
+    interactionsCount: number;
+    interactionsPerActiveMinute: number;
+    category: DwellEngagementCategory;
+}
+export interface DwellTimeReport {
+    summary: {
+        totalSessionsAnalyzed: number;
+        totalWallClockHours: number;
+        totalActiveAttentionHours: number;
+        overallActiveRatioPct: number;
+        avgActiveSecondsPerSession: number;
+    };
+    categoryDistribution: Record<DwellEngagementCategory, {
+        count: number;
+        sharePct: number;
+    }>;
+    pageBreakdown: Array<{
+        pageUrl: string;
+        sessionsCount: number;
+        avgActiveSeconds: number;
+        avgActiveRatioPct: number;
+    }>;
+    sessions: SessionDwellMetrics[];
+}
+export declare class ActiveDwellTimeCalculator {
+    /**
+     * Analyse les événements de suivi du temps et extrait les métriques d'engagement actif.
+     */
+    static calculate(events: DwellRawEvent[], options?: DwellTimeOptions): DwellTimeReport;
+}

package/dist/analytics/ad-audience-sync-engine.d.ts

@@ -0,0 +1,69 @@
+/**
+ * AdAudienceSyncEngine — Normalisation, hachage SHA-256 et export d'audiences publicitaires (Parité RudderStack / PostHog).
+ *
+ * Permet de synchroniser les cohortes comportementales vers les régies publicitaires :
+ * - Meta Custom Audiences (Facebook & Instagram)
+ * - Google Customer Match (Google Ads)
+ * - TikTok Custom Audiences
+ *
+ * Respecte les standards stricts de normalisation (E.164 pour les téléphones, lowercase sans espace pour les emails)
+ * et le hachage cryptographique SHA-256 garantissant la conformité RGPD.
+ */
+export type AdAudiencePlatform = "meta" | "google" | "tiktok";
+export interface UserAudienceRecord {
+    userId?: string;
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    countryCode?: string;
+    postalCode?: string;
+    customAttributes?: Record<string, unknown>;
+}
+export interface AdAudienceHashedRecord {
+    hashedEmail?: string;
+    hashedPhone?: string;
+    hashedFirstName?: string;
+    hashedLastName?: string;
+    countryCode?: string;
+    postalCode?: string;
+}
+export interface AdAudienceSyncBatch {
+    platform: AdAudiencePlatform;
+    batchIndex: number;
+    recordsCount: number;
+    payload: Record<string, unknown>;
+}
+export interface AdAudienceSyncResult {
+    summary: {
+        platform: AdAudiencePlatform;
+        totalInputRecords: number;
+        validHashedRecordsCount: number;
+        skippedInvalidCount: number;
+        batchesCount: number;
+    };
+    batches: AdAudienceSyncBatch[];
+    sampleHashedRecords: AdAudienceHashedRecord[];
+}
+export declare class AdAudienceSyncEngine {
+    /**
+     * Calcule le condensat SHA-256 hexadécimal d'une chaîne.
+     */
+    static sha256(value: string): Promise<string>;
+    /**
+     * Normalise une adresse email selon les règles des régies (trim, lowercase, suppression des points pour gmail).
+     */
+    static normalizeEmail(email: string): string;
+    /**
+     * Normalise un numéro de téléphone au standard E.164 sans espaces ni caractères spéciaux.
+     */
+    static normalizePhone(phone: string, defaultCountryPrefix?: string): string;
+    /**
+     * Normalise et hache un enregistrement utilisateur pour l'audience.
+     */
+    static hashRecord(record: UserAudienceRecord): Promise<AdAudienceHashedRecord | null>;
+    /**
+     * Prépare les lots d'audience pour la régie cible.
+     */
+    static prepareAudience(records: UserAudienceRecord[], platform: AdAudiencePlatform, batchSize?: number): Promise<AdAudienceSyncResult>;
+}

package/dist/analytics/adaptive-event-sampler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Adaptive Event Sampler & Traffic Multiplier Compensator
+ * Dynamic volume-based event throttling with deterministic user hash sampling,
+ * critical event immunity, and unbiased query expansion multipliers ($1/p$).
+ * Inspired by PostHog and modern telemetry cost-control pipelines.
+ */
+export interface AdaptiveSamplingConfig {
+    /** Target maximum events per second before throttling kicks in */
+    targetEventsPerSec: number;
+    /** Current incoming velocity of events per second */
+    currentEventsPerSec: number;
+    /** Base minimum sampling rate (e.g. 0.05 = never sample below 5%) */
+    minSampleRate?: number;
+    /** Force sample rate if overriding automatic calculation */
+    overrideSampleRate?: number;
+    /** Events exempt from ever being sampled (e.g. conversions, revenue) */
+    exemptEvents?: string[];
+}
+export interface SampleEvaluationResult {
+    isKept: boolean;
+    sampleRate: number;
+    /** Expansion multiplier for analytics rollups: count * expansionMultiplier */
+    expansionMultiplier: number;
+    isExempt: boolean;
+    reason: "exempt" | "sampled_in" | "sampled_out" | "no_sampling_needed";
+}
+export declare class AdaptiveEventSampler {
+    /**
+     * Calculates the optimal sampling rate given current velocity vs target capacity.
+     */
+    static calculateDynamicRate(config: AdaptiveSamplingConfig): number;
+    /**
+     * Deterministic 32-bit FNV-1a hash to convert distinct_id into [0, 1) float.
+     */
+    static hashToFloat(str: string): number;
+    /**
+     * Evaluates an individual event to decide whether to retain it and computes the expansion multiplier.
+     */
+    static evaluateEvent(eventName: string, distinctId: string, config: AdaptiveSamplingConfig): SampleEvaluationResult;
+    /**
+     * Unbiases an aggregated sampled count or metric.
+     */
+    static unbiasCount(sampledCount: number, sampleRate: number): number;
+}

package/dist/analytics/ai-agents-tracker.d.ts

@@ -0,0 +1,63 @@
+/**
+ * AIAgentsTracker — clean-room implementation inspired by Matomo's AIAgents plugin.
+ * Detects and classifies AI agent / AI provider traffic (GPTBot, ClaudeBot, Perplexity, etc.)
+ * and aggregates usage metrics for SEO visibility in AI search channels.
+ * AGPL-3.0-or-later
+ */
+export interface AIAgentSignature {
+    agentId: string;
+    name: string;
+    provider: string;
+    uaPatterns: RegExp[];
+    /** Category: crawler | assistant | scraper */
+    category: "crawler" | "assistant" | "scraper";
+}
+export interface AIAgentVisit {
+    agentId: string;
+    agentName: string;
+    provider: string;
+    category: "crawler" | "assistant" | "scraper";
+    url: string;
+    timestamp: string;
+    userAgent: string;
+    referrer: string | null;
+}
+export interface AIAgentStat {
+    agentId: string;
+    agentName: string;
+    provider: string;
+    category: "crawler" | "assistant" | "scraper";
+    totalVisits: number;
+    uniqueUrls: number;
+    lastSeen: string;
+    topUrls: Array<{
+        url: string;
+        visits: number;
+    }>;
+}
+export interface AIAgentsReport {
+    projectId: string;
+    generatedAt: string;
+    totalAIVisits: number;
+    uniqueAgents: number;
+    byProvider: Array<{
+        provider: string;
+        visits: number;
+        sharePercent: number;
+    }>;
+    agents: AIAgentStat[];
+    recommendation: string;
+}
+export declare class AIAgentsTracker {
+    private visits;
+    /** Identify agent from UA string. Returns null if not an AI agent. */
+    identifyAgent(userAgent: string): AIAgentSignature | null;
+    recordVisit(projectId: string, params: {
+        url: string;
+        userAgent: string;
+        referrer?: string | null;
+        timestamp?: string;
+    }): boolean;
+    getReport(projectId: string): AIAgentsReport;
+    seedDemoData(projectId: string, count?: number): void;
+}