@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/cro-industry-benchmarks.d.ts

@@ -0,0 +1,76 @@
+export type IndustryVertical = "fashion" | "beauty" | "food_beverage" | "electronics" | "home_living" | "health_supplements" | "luxury_jewelry" | "general_ecommerce";
+export interface MetricBenchmark {
+    median: number;
+    top10: number;
+    unit: "%" | "currency";
+}
+export interface IndustryBenchmarkMetrics {
+    vertical: IndustryVertical;
+    label: string;
+    optInRate: MetricBenchmark;
+    conversionRate: MetricBenchmark;
+    averageOrderValue: MetricBenchmark;
+    cartAbandonmentRate: MetricBenchmark;
+    revenuePerVisitor: MetricBenchmark;
+    mobileTrafficShare: MetricBenchmark;
+}
+export interface StoreMetricsInput {
+    vertical: IndustryVertical;
+    currency?: string;
+    visitors: number;
+    optIns: number;
+    orders: number;
+    revenue: number;
+    cartsStarted: number;
+    mobileVisitors?: number;
+}
+export type PerformanceTier = "elite" | "above_average" | "average" | "below_average";
+export interface BenchmarkEvaluationResult {
+    vertical: IndustryVertical;
+    verticalLabel: string;
+    currency: string;
+    store: {
+        optInRate: number;
+        conversionRate: number;
+        aov: number;
+        revenuePerVisitor: number;
+        cartAbandonmentRate: number;
+        mobileShare: number;
+    };
+    benchmarks: IndustryBenchmarkMetrics;
+    performanceTiers: {
+        optIn: PerformanceTier;
+        conversion: PerformanceTier;
+        aov: PerformanceTier;
+        cartAbandonment: PerformanceTier;
+    };
+    potentialRevenueGain: {
+        liftingConversionToMedian: number;
+        liftingConversionToTop10: number;
+        annualizedTop10Opportunity: number;
+    };
+    recommendations: Array<{
+        area: "opt_in" | "conversion" | "aov" | "cart_recovery";
+        title: string;
+        description: string;
+        priority: "high" | "medium" | "low";
+        recommendedFeature: "quiz" | "gamified_slot" | "free_shipping_ladder" | "exit_intent_cart_saver" | "urgency_timer";
+    }>;
+}
+export declare class CroIndustryBenchmarksEngine {
+    private static readonly BENCHMARK_CATALOG;
+    /**
+     * Retourne tous les secteurs et leurs métriques de référence.
+     */
+    static getAllVerticals(): IndustryBenchmarkMetrics[];
+    /**
+     * Retourne les benchmarks pour un secteur donné.
+     */
+    static getBenchmarks(vertical: IndustryVertical): IndustryBenchmarkMetrics;
+    /**
+     * Évalue la performance d'une boutique par rapport aux benchmarks sectoriels.
+     */
+    static evaluateStore(input: StoreMetricsInput): BenchmarkEvaluationResult;
+    private static classifyTier;
+    private static classifyInvertedTier;
+}

package/dist/cro-revenue-attribution-engine.d.ts

@@ -0,0 +1,53 @@
+export interface CohortMetrics {
+    visitors: number;
+    conversions: number;
+    totalRevenueCents: number;
+}
+export interface LiftAnalysisResult {
+    controlCr: number;
+    variantCr: number;
+    crRelativeLiftPercent: number;
+    controlRpvCents: number;
+    variantRpvCents: number;
+    rpvRelativeLiftPercent: number;
+    incrementalRevenueCents: number;
+    zScore: number;
+    pValue: number;
+    isStatisticallySignificant: number;
+}
+export interface PopupTouchpoint {
+    distinctId: string;
+    orderId: string;
+    orderRevenueCents: number;
+    couponCodeUsed?: string;
+    popupInteractedAt: string;
+    orderPlacedAt: string;
+    triggerType?: "exit_intent" | "time_delayed" | "scroll_depth" | "cart_abandonment";
+}
+export interface PopupAttributionSummary {
+    directOrdersCount: number;
+    directRevenueCents: number;
+    influencedOrdersCount: number;
+    influencedRevenueCents: number;
+    exitIntentRecoveredOrdersCount: number;
+    exitIntentRecoveredRevenueCents: number;
+    totalAttributedRevenueCents: number;
+}
+export declare class CroRevenueAttributionEngine {
+    /**
+     * Calcule le Lift Incrémental entre le groupe exposé (variante) et le groupe témoin (contrôle).
+     * Utilise le Z-test bilatéral à deux proportions pour déterminer la significativité statistique.
+     */
+    calculateIncrementalLift(variant: CohortMetrics, control: CohortMetrics): LiftAnalysisResult;
+    /**
+     * Segmente et attribue les commandes e-commerce selon leur proximité avec le popup :
+     * - Direct : code promo du popup appliqué lors de la commande
+     * - Influencé : commande passée dans la fenêtre d'attribution (ex: 24h) après interaction sans code
+     * - Panier sauvé : commande issue d'un déclenchement par 'exit_intent'
+     */
+    attributeOrders(touchpoints: PopupTouchpoint[], registeredPromoCodes: string[], attributionWindowHours?: number): PopupAttributionSummary;
+    /**
+     * Calcul d'approximation de p-value bilatérale à partir du score Z (formule erf).
+     */
+    private calculatePValueFromZ;
+}

package/dist/cro-variant-ai-engine.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CRO Variant AI Generator Engine
+ * Générateur de variantes de copies et d'expériences CRO pour les A/B tests bayésiens (Thompson Sampling).
+ */
+export interface CroBrandDnaProfile {
+    brandName: string;
+    niche: "beauty" | "fashion" | "electronics" | "wellness" | "home" | "food" | "general";
+    toneOfVoice: "playful" | "luxury" | "urgent" | "scientific" | "minimalist" | "friendly";
+    primaryBenefit: string;
+    defaultDiscount?: string;
+    freeGiftName?: string;
+}
+export interface GeneratedCroVariant {
+    variantId: string;
+    experienceType: "wheel" | "scratchcard" | "mystery_box" | "plinko" | "quiz" | "learn_and_earn";
+    headline: string;
+    subheadline: string;
+    teaserText: string;
+    ctaText: string;
+    badgeText: string;
+    urgencyCopy: string;
+    incentive: {
+        discountType: "percentage" | "fixed_amount" | "free_gift" | "free_shipping";
+        discountValue: number | string;
+        couponCode: string;
+    };
+    quizIntro?: {
+        question: string;
+        options: string[];
+    };
+}
+export declare class CroVariantAiEngine {
+    /**
+     * Génère un ensemble de variantes contrastées (A/B/C/D) prêtes pour l'évaluation Thompson Sampling
+     */
+    static generateVariantMatrix(profile: CroBrandDnaProfile): GeneratedCroVariant[];
+}

package/dist/cross-filter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * G4 — Cross-Filtering
+ *
+ * LynxSEO: PulseFilterBar.tsx + activeFilter + pulseEventFilterSchema
+ *          + PulseSegmentPresetsBar + cross-filter.ts (nouveau)
+ * Inspiration: SWETRIX_INSPIRATION_GAP_ANALYSIS.md + Metabase/Rybbit concepts
+ *
+ * NOTE: Le cross-filtering global est FERMÉ via PulseFilterBar mais ce module
+ * fournit la logique cross-filtering pure réutilisable across composants.
+ */
+import { z } from "zod";
+/** Filter operator types */
+export type FilterOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "contains" | "in";
+/** Filters applicable across any analytics entity */
+export type CrossFilter = {
+    /** Entity type (sessions, pages, events, goals) */
+    entity: "sessions" | "pages" | "events" | "goals";
+    /** Field to filter on */
+    field: string;
+    /** Operator (eq, ne, gt, gte, lt, lte, contains, in) */
+    operator: FilterOperator;
+    /** Value to match */
+    value: string | number | string[] | number[];
+};
+/** Pre-defined filter presets for common analytics use-cases */
+export declare const CROSS_FILTER_PRESETS: {
+    readonly today: {
+        readonly entity: "events";
+        readonly field: "timestamp";
+        readonly operator: "gte";
+        readonly value: number;
+    };
+    readonly yesterday: {
+        readonly entity: "events";
+        readonly field: "timestamp";
+        readonly operator: "gte";
+        readonly value: number;
+    };
+    readonly thisWeek: {
+        readonly entity: "events";
+        readonly field: "timestamp";
+        readonly operator: "gte";
+        readonly value: number;
+    };
+    readonly thisMonth: {
+        readonly entity: "events";
+        readonly field: "timestamp";
+        readonly operator: "gte";
+        readonly value: number;
+    };
+    readonly custom: {
+        readonly entity: "events";
+        readonly field: "timestamp";
+        readonly operator: "gte";
+        readonly value: "";
+    };
+};
+/** Apply a cross-filter to a dataset */
+export declare function applyCrossFilter<T extends Record<string, unknown>>(data: T[], filter: CrossFilter): T[];
+/** Build a cross-filter from form state */
+export declare function buildCrossFilterFromState(entity: CrossFilter["entity"], field: string, operator: FilterOperator, value: string | number | string[] | number[]): CrossFilter;
+/** Schema for cross-filter validation */
+export declare const crossFilterSchema: z.ZodObject<{
+    entity: z.ZodEnum<{
+        pages: "pages";
+        sessions: "sessions";
+        events: "events";
+        goals: "goals";
+    }>;
+    field: z.ZodString;
+    operator: z.ZodEnum<{
+        contains: "contains";
+        in: "in";
+        ne: "ne";
+        eq: "eq";
+        gt: "gt";
+        gte: "gte";
+        lt: "lt";
+        lte: "lte";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>]>;
+}, z.core.$strip>;

package/dist/crosslink-scorer.d.ts

@@ -1,5 +1,5 @@
 /**
- * 🕸️ Contextual Cross-Linking & Semantic Affinity Engine (Inspiration: seedrank/crosslinks.py)
+ * 🕸️ Contextual Cross-Linking & Semantic Affinity Engine
  *
  * Computes forward and backward internal link affinity scores based on:
  * Score = (TopicOverlap * 2 + KeywordOverlap) + VolumeBonus + ContentTypeBonus + RecencyBonus

package/dist/custom-dimensions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Custom Dimensions — Matomo Plugin "CustomDimensions"
+ *
+ * Dimensions personnalisées avec scope (visit, action, event), extraction par regex,
+ * et rapports par dimension. Jusqu'à 5 dimensions personnalisées par site.
+ */
+export type CustomDimensionScope = "visit" | "action" | "event";
+export interface CustomDimensionDef {
+    id: number;
+    name: string;
+    scope: CustomDimensionScope;
+    siteId: string;
+    regex?: string;
+    active: boolean;
+}
+export interface CustomDimensionValue {
+    dimensionId: number;
+    value: string;
+    scope: CustomDimensionScope;
+}
+export interface CustomDimensionsContext {
+    siteId: string;
+    dimensions: Map<number, CustomDimensionValue>;
+}
+export declare class CustomDimensionsManager {
+    private dimensions;
+    private nextSlot;
+    /**
+     * Enregistre une dimension personnalisée pour un site.
+     */
+    registerDimension(siteId: string, def: Omit<CustomDimensionDef, "id"> | Omit<CustomDimensionDef, "id" | "active">): number;
+    /**
+     * Récupère les définitions d'un site.
+     */
+    getDimensions(siteId: string): CustomDimensionDef[];
+    /**
+     * Récupère une définition par ID.
+     */
+    getDimension(siteId: string, dimensionId: number): CustomDimensionDef | undefined;
+    /**
+     * Extrait les valeurs de dimensions depuis un contexte de requête (query params, headers).
+     * Support de l'extraction par regex si définie.
+     */
+    extractValues(siteId: string, context: {
+        query?: Record<string, string>;
+        headers?: Record<string, string>;
+        payload?: Record<string, unknown>;
+    }): CustomDimensionValue[];
+    /**
+     * Définit une valeur de dimension pour un contexte donné.
+     */
+    setValue(ctx: CustomDimensionsContext, dimensionId: number, value: string): void;
+    /**
+     * Récupère toutes les valeurs d'un contexte.
+     */
+    getValues(ctx: CustomDimensionsContext): CustomDimensionValue[];
+}
+export declare const customDimensionsManager: CustomDimensionsManager;

package/dist/data-lifecycle-manager.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 🗄️ Data Lifecycle Manager (rétention, TTL, archivage)
+ *
+ * Les Session Replays et les logs RUM coûtent cher et grossissent vite ; les
+ * données financières, elles, doivent être conservées à vie. Sans politique
+ * explicite, la base sature en quelques semaines — ou pire, une purge manuelle
+ * emporte des écritures comptables.
+ *
+ * Ce module porte trois choses :
+ * 1. une politique **typée par classe de données** avec des invariants
+ *    (`financial` ne périme jamais, `audit_log` s'archive au lieu d'être
+ *    supprimé) ;
+ * 2. un `planLifecycle()` pur qui décide, enregistrement par enregistrement,
+ *    entre conserver / archiver / anonymiser / supprimer, avec dry-run ;
+ * 3. la traduction de la politique en clause `TTL` ClickHouse
+ *    (`buildClickHouseTtlClause`) pour que la base applique la rétention
+ *    elle-même, sans dépendre d'un cron.
+ */
+export declare const DATASET_CLASSES: readonly ["session_replay", "rum", "events", "audit_log", "financial", "export"];
+export type DatasetClass = (typeof DATASET_CLASSES)[number];
+export declare const RETENTION_ACTIONS: readonly ["delete", "anonymize", "archive", "keep"];
+export type RetentionAction = (typeof RETENTION_ACTIONS)[number];
+export interface RetentionPolicy {
+    dataset: DatasetClass;
+    action: RetentionAction;
+    /**
+     * Durée de conservation en jours. `null` = conservation illimitée, autorisée
+     * uniquement pour les classes que la loi ou la comptabilité impose.
+     */
+    retentionDays: number | null;
+    /** Bascule vers le stockage froid avant l'échéance (action `archive`). */
+    archiveAfterDays?: number;
+    /** Colonnes à vider lors d'une anonymisation. */
+    piiFields?: string[];
+    /** Suspension temporaire des purges (litige, enquête, réclamation). */
+    legalHold?: boolean;
+}
+export interface LifecycleRecord {
+    id: string;
+    dataset: DatasetClass;
+    /** Horodatage ISO (AGENTS.md §3 : tri lexicographique identique D1/Postgres). */
+    createdAt: string;
+    sizeBytes?: number;
+}
+export type LifecycleOutcome = "delete" | "anonymize" | "archive" | "keep";
+export type LifecycleReason = "financial_retention" | "legal_hold" | "within_retention" | "archive_window" | "expired";
+export interface LifecycleDecision {
+    id: string;
+    dataset: DatasetClass;
+    outcome: LifecycleOutcome;
+    reason: LifecycleReason;
+    ageDays: number;
+}
+export interface LifecycleSummary {
+    delete: number;
+    anonymize: number;
+    archive: number;
+    keep: number;
+    bytesFreed: number;
+}
+export interface LifecyclePlan {
+    evaluatedAt: string;
+    decisions: LifecycleDecision[];
+    summary: Record<DatasetClass, LifecycleSummary>;
+    bytesFreed: number;
+    blockedByLegalHold: number;
+}
+/**
+ * Politique par défaut.
+ *
+ * - `session_replay` : 30 jours puis suppression (le replay n'a pas de valeur
+ *   analytique au-delà d'un mois, et il contient des données de session).
+ * - `rum` : 90 jours — le temps de voir les régressions de Core Web Vitals.
+ * - `events` : 400 jours puis anonymisation (les agrégats restent exploitables
+ *   en comparaison annuelle).
+ * - `audit_log` : 2 ans puis archivage — jamais de suppression.
+ * - `financial` : conservation illimitée.
+ * - `export` : 7 jours (fichiers générés, reproductibles).
+ */
+export declare const DEFAULT_RETENTION_POLICIES: Record<DatasetClass, RetentionPolicy>;
+/**
+ * Valide une politique seule. Lève une exception plutôt que de corriger
+ * silencieusement : une politique fausse doit empêcher le déploiement du cron.
+ */
+export declare function validateRetentionPolicy(policy: RetentionPolicy): void;
+/** Valide le jeu complet : chaque classe doit avoir exactement une politique. */
+export declare function validateRetentionPolicies(policies: Partial<Record<DatasetClass, RetentionPolicy>>): Record<DatasetClass, RetentionPolicy>;
+/** Décide du sort d'un enregistrement. Fonction pure, testable sans horloge. */
+export declare function evaluateRecord(record: LifecycleRecord, policy: RetentionPolicy, nowMs: number): LifecycleDecision;
+/**
+ * Construit le plan de rétention (dry-run par construction : rien n'est
+ * supprimé ici, l'appelant exécute les décisions).
+ */
+export declare function planLifecycle(options: {
+    records: readonly LifecycleRecord[];
+    now: Date | string | number;
+    policies?: Partial<Record<DatasetClass, RetentionPolicy>>;
+}): LifecyclePlan;
+export interface ClickHouseTtlClause {
+    ttlClause: string | null;
+    /** Mutation à exécuter une fois pour vider les champs PII (ClickHouse ne le fait pas via TTL). */
+    anonymizeStatement: string | null;
+    notes: string[];
+}
+/**
+ * Traduit une politique en `TTL` ClickHouse.
+ *
+ * `created_at` est stocké en texte ISO (AGENTS.md §3) : `toDateTime64(..., 3)`
+ * est un no-op sur une colonne `DateTime64(3)` et analyse correctement une
+ * chaîne ISO, donc la même clause marche sur les deux schémas.
+ */
+export declare function buildClickHouseTtlClause(policy: RetentionPolicy, table?: "events" | "session_replay" | "rum" | "audit_log" | "financial" | "export"): ClickHouseTtlClause;
+/**
+ * Garde-fou multi-tenant : une purge ne doit jamais être globale. Rend la
+ * clause `WHERE` à ajouter à une suppression manuelle.
+ */
+export declare function buildScopedPurgeWhere(options: {
+    policy: RetentionPolicy;
+    now: Date;
+    projectColumn?: string;
+}): string;

package/dist/dataforseo-ai-tracking-client.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 🤖 DataForSEO AI tracking client
+ *
+ * Typed access to the AI Optimization LLM Responses and LLM Scraper APIs:
+ * runs a prompt on ChatGPT, Claude, Gemini or Perplexity, collects the answer
+ * and its citations, and reports whether a brand was mentioned and cited.
+ *
+ * DataForSEO bills a task that fails with `Invalid Field: 'model_name'`, so
+ * the client can validate the model name against a known catalog before
+ * dispatching (`strictModelNames`) and always exposes the live catalog
+ * through {@link DataForSeoAiTrackingClient.listModels}.
+ *
+ * ```ts
+ * const tracking = new DataForSeoAiTrackingClient({ apiKey });
+ * const report = await tracking.trackBrandVisibility({
+ *   engine: "chatgpt",
+ *   brand: "LynxSEO",
+ *   modelName: "gpt-5",
+ *   queries: ["best seo audit tool"],
+ * });
+ * ```
+ */
+import { z } from "zod";
+import { DataForSeoTransport, type DataForSeoTransportOptions } from "./dataforseo-transport";
+export interface DataForSeoAiTrackingClientOptions extends DataForSeoTransportOptions {
+    /** Reuse an existing transport (and its credentials) across clients. */
+    transport?: DataForSeoTransport;
+    /**
+     * Reject a `modelName` that is not in {@link AI_TRACKING_KNOWN_MODELS}
+     * before dispatching. DataForSEO charges rejected tasks, so the guard is
+     * worth enabling for unattended runs.
+     */
+    strictModelNames?: boolean;
+}
+/** AI engines supported by the LLM Responses API. */
+export type AiTrackingEngine = "chatgpt" | "claude" | "gemini" | "perplexity";
+/** DataForSEO path slug of each engine. */
+export declare const AI_TRACKING_ENGINE_SLUGS: Record<AiTrackingEngine, string>;
+/**
+ * Model names accepted by DataForSEO per engine (verified against the
+ * `/ai_optimization/{model}/llm_responses/models` catalog, 2026-06-30).
+ * DataForSEO resolves a basic alias to its latest dated version.
+ */
+export declare const AI_TRACKING_KNOWN_MODELS: Record<AiTrackingEngine, readonly string[]>;
+/** The answer returned by an LLM Responses task. */
+export declare const aiLlmResponseSchema: z.ZodObject<{
+    model_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    output_tokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    web_search: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    items: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        sections: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            annotations: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$loose>>>>;
+        }, z.core.$loose>>>>;
+    }, z.core.$loose>>>>;
+    fan_out_queries: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.core.$loose>;
+export type AiLlmResponse = z.infer<typeof aiLlmResponseSchema>;
+/** A row of the AI keyword data endpoint. */
+export declare const aiKeywordVolumeItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    search_volume: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cpc: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    location_code: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    language_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type AiKeywordVolumeItem = z.infer<typeof aiKeywordVolumeItemSchema>;
+/** A scraped LLM answer row. */
+export declare const aiScraperItemSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    question: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    answer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type AiScraperItem = z.infer<typeof aiScraperItemSchema>;
+export interface AiLlmResponseInput {
+    /** Engine the prompt runs on. */
+    engine: AiTrackingEngine;
+    /** The prompt sent to the model. */
+    userPrompt: string;
+    /** DataForSEO model name, e.g. "gpt-5". */
+    modelName: string;
+    /** Enable web search inside the answer. Defaults to true. */
+    webSearch?: boolean;
+    /** Max output tokens (256..4096). */
+    maxOutputTokens?: number;
+    /** Two-letter ISO country code used to geolocate the web-search component. */
+    webSearchCountryCode?: string;
+}
+export interface AiKeywordSearchVolumeInput {
+    keywords: string[];
+    locationCode?: number;
+    languageCode?: string;
+}
+export interface AiScraperInput {
+    /** Only ChatGPT and Gemini expose the LLM Scraper API. */
+    engine: "chatgpt" | "gemini";
+    keyword: string;
+    locationCode?: number;
+    languageCode?: string;
+    limit?: number;
+}
+/** One tracked query and what the model answered. */
+export interface AiBrandVisibilityEntry {
+    query: string;
+    /** The answer text extracted from the response sections. */
+    answer: string;
+    /** True when the brand name appears in the answer. */
+    mentioned: boolean;
+    /** True when at least one citation points at the brand domain. */
+    cited: boolean;
+    /** Domains cited by the answer. */
+    citedDomains: string[];
+    /** True when the model reported a web search. */
+    webSearch: boolean;
+}
+export interface AiBrandVisibilityReport {
+    engine: AiTrackingEngine;
+    brand: string;
+    /** Brand domain used to detect citations. */
+    brandDomain: string | null;
+    queries: string[];
+    entries: AiBrandVisibilityEntry[];
+    /** Number of answers collected. */
+    responseCount: number;
+    /** Answers mentioning the brand. */
+    mentionCount: number;
+    /** Answers citing the brand. */
+    citationCount: number;
+    /** mentionCount / responseCount, 0..1. */
+    mentionRate: number;
+    /** citationCount / responseCount, 0..1. */
+    citationRate: number;
+    /** Cost reported by DataForSEO for the tracked calls, in USD. */
+    costUsd: number;
+}
+export interface AiBrandVisibilityInput {
+    engine: AiTrackingEngine;
+    /** Brand name looked for in the answers. */
+    brand: string;
+    /** Brand domain used to detect citations (e.g. "example.com"). */
+    brandDomain?: string;
+    /** Prompts sent to the model. */
+    queries: string[];
+    modelName: string;
+    webSearch?: boolean;
+    maxOutputTokens?: number;
+    webSearchCountryCode?: string;
+}
+/**
+ * Client for the DataForSEO AI Optimization tracking endpoints.
+ */
+export declare class DataForSeoAiTrackingClient {
+    readonly transport: DataForSeoTransport;
+    private readonly strictModelNames;
+    constructor(options?: DataForSeoAiTrackingClientOptions);
+    /** Runs a prompt on an LLM and returns the answer with its citations. */
+    llmResponse(input: AiLlmResponseInput): Promise<AiLlmResponse>;
+    /** Free catalog of the models available for an engine. */
+    listModels(engine: AiTrackingEngine): Promise<unknown>;
+    /** Search volume of keywords inside AI tools. */
+    aiKeywordSearchVolume(input: AiKeywordSearchVolumeInput): Promise<AiKeywordVolumeItem[]>;
+    /** Scrapes the answers an AI platform returns for a keyword. */
+    llmScraper(input: AiScraperInput): Promise<AiScraperItem[]>;
+    /**
+     * Runs every query on the engine and reports how often the brand was
+     * mentioned and cited. The report also carries the DataForSEO cost so the
+     * caller can meter the run.
+     */
+    trackBrandVisibility(input: AiBrandVisibilityInput): Promise<AiBrandVisibilityReport>;
+}
+/** Throws when the model name is unknown for the engine. */
+export declare function assertKnownModel(engine: AiTrackingEngine, modelName: string): void;
+/** Convenience factory for {@link DataForSeoAiTrackingClient}. */
+export declare function createDataForSeoAiTrackingClient(options?: DataForSeoAiTrackingClientOptions): DataForSeoAiTrackingClient;