@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/screen-resolution-engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ScreenResolution & Viewport Analytics Engine
+ *
+ * Implements resolution bucketing, aspect ratio classification, viewport width categories,
+ * device pixel ratio (Retina) detection, and orientation breakdown.
+ * Parity with Matomo Resolution & OpenReplay Viewport Matrix.
+ *
+ * Clean-room implementation under AGPL-3.0-or-later.
+ */
+export interface ScreenRecordInput {
+    width: number;
+    height: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    devicePixelRatio?: number;
+    orientation?: 'portrait' | 'landscape';
+}
+export interface ResolutionAggregateRow {
+    resolution: string;
+    width: number;
+    height: number;
+    aspectRatio: string;
+    count: number;
+    percentage: number;
+}
+export interface ViewportCategoryRow {
+    category: 'mobile' | 'tablet' | 'desktop' | 'widescreen';
+    count: number;
+    percentage: number;
+}
+export interface AspectRatioRow {
+    ratio: string;
+    count: number;
+    percentage: number;
+}
+export interface ScreenResolutionReport {
+    totalScreens: number;
+    resolutions: ResolutionAggregateRow[];
+    viewportCategories: ViewportCategoryRow[];
+    aspectRatios: AspectRatioRow[];
+    retinaCount: number;
+    retinaPercentage: number;
+    orientationBreakdown: {
+        portrait: number;
+        landscape: number;
+        portraitPercentage: number;
+        landscapePercentage: number;
+    };
+}
+export declare class ScreenResolutionEngine {
+    private static calculateGcd;
+    static classifyAspectRatio(width: number, height: number): string;
+    static classifyViewport(viewportWidth: number): 'mobile' | 'tablet' | 'desktop' | 'widescreen';
+    static analyze(records: ScreenRecordInput[]): ScreenResolutionReport;
+}

package/dist/analytics/search-engine-bot-ip-range-geo-location-auditor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SearchEngineBotIpRangeGeoLocationAuditor
+ * Verifies search engine bot requests against authoritative crawler ASN and IP ranges,
+ * detecting fake Googlebot/Bingbot user-agent spoofing, scraper impersonation, and CDN bypasses.
+ */
+export interface BotRequestRecord {
+    requestId: string;
+    timestamp: string;
+    ipAddress: string;
+    userAgent: string;
+    asn?: number;
+    asnOrg?: string;
+    countryCode?: string;
+}
+export type BotVerificationStatus = "verified_authentic" | "spoofed_impersonation" | "unverified_commercial_crawler" | "unknown_user_agent";
+export interface BotRequestVerificationResult {
+    requestId: string;
+    ipAddress: string;
+    userAgent: string;
+    claimedBot: "googlebot" | "bingbot" | "yandexbot" | "baiduspider" | "none";
+    verificationStatus: BotVerificationStatus;
+    isLegitimateSearchEngine: boolean;
+    threatDetails?: string;
+}
+export interface BotAuditSummaryReport {
+    totalBotRequestsAudited: number;
+    verifiedSearchEngineRequestsCount: number;
+    spoofedImpersonationsCount: number;
+    legitimacyRatePercent: number;
+    flaggedIpAddresses: string[];
+    results: BotRequestVerificationResult[];
+}
+export declare class SearchEngineBotIpRangeGeoLocationAuditor {
+    private static readonly GOOGLE_ASNS;
+    private static readonly MICROSOFT_ASNS;
+    private static readonly YANDEX_ASNS;
+    private static readonly BAIDU_ASNS;
+    /**
+     * Verifies bot traffic logs against legitimate ASN ownership and user-agent claims.
+     */
+    verifyLogs(records: BotRequestRecord[]): BotAuditSummaryReport;
+    private verifyBotAsn;
+}

package/dist/analytics/search-engine-organic-cpc-cannibalization-arbitrage-auditor.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SearchEngineOrganicCpcCannibalizationArbitrageAuditor
+ * Detects paid vs organic search cannibalization, distinguishing wasted ad spend on unthreatened #1 ranks
+ * from defensive PPC bidding and calculating arbitrage savings opportunities.
+ */
+export interface QueryPaidOrganicInput {
+    keyword: string;
+    organicRank: number;
+    organicMonthlyClicks: number;
+    paidMonthlyClicks: number;
+    averageCpc: number;
+    monthlyPaidCost: number;
+    hasCompetitorAdsOnSerp: boolean;
+    isBrandKeyword: boolean;
+}
+export type CannibalizationStatus = "pure_cannibalization_waste" | "brand_defensive_necessary" | "incremental_gain" | "low_impact";
+export interface QueryArbitrageEvaluation {
+    keyword: string;
+    status: CannibalizationStatus;
+    monthlyWastedCost: number;
+    suggestedAction: string;
+    rationale: string;
+}
+export interface PaidOrganicArbitrageReport {
+    totalQueriesAudited: number;
+    totalMonthlyPaidCost: number;
+    potentialMonthlySavings: number;
+    cannibalizationWasteCount: number;
+    defensiveSpendCount: number;
+    arbitrageEfficiencyScore: number;
+    evaluations: QueryArbitrageEvaluation[];
+    strategicActionPlan: string[];
+}
+export declare class SearchEngineOrganicCpcCannibalizationArbitrageAuditor {
+    /**
+     * Audits keyword search queries for paid search cannibalization against organic rankings.
+     */
+    audit(queries: QueryPaidOrganicInput[]): PaidOrganicArbitrageReport;
+    /**
+     * Generates a CSV file payload compatible with Google Ads Editor
+     * to exclude pure cannibalization keywords as negative exact match.
+     */
+    exportGoogleAdsEditorCsv(report: PaidOrganicArbitrageReport, campaignName?: string): string;
+    /**
+     * Generates a Google Ads Script (JavaScript) that marketing teams can run
+     * nightly in Google Ads to auto-exclude pure cannibalization queries.
+     */
+    exportGoogleAdsAutomationScript(report: PaidOrganicArbitrageReport, options?: {
+        scriptName?: string;
+        dryRun?: boolean;
+    }): string;
+}

package/dist/analytics/search-engine-sitemap-image-extension-auditor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SearchEngineSitemapImageExtensionAuditor
+ * Audits XML sitemaps for Google Image extension compliance (xmlns:image, <image:loc>,
+ * <image:caption>, <image:license>), verifying image discovery and Licensable rich badges.
+ */
+export interface SitemapImageTagEntry {
+    pageUrl: string;
+    imageLoc: string;
+    caption?: string;
+    title?: string;
+    geoLocation?: string;
+    license?: string;
+}
+export interface ImageSitemapFinding {
+    pageUrl: string;
+    imageLoc: string;
+    isAbsoluteUrl: boolean;
+    hasSecureProtocol: boolean;
+    hasLicenseForRichBadge: boolean;
+    issues: string[];
+}
+export interface ImageSitemapAuditReport {
+    totalImagesAudited: number;
+    validImagesCount: number;
+    imagesWithLicenseBadgeCount: number;
+    complianceScore: number;
+    findings: ImageSitemapFinding[];
+    remediationAdvice: string[];
+    sampleValidXmlSnippet: string;
+}
+export declare class SearchEngineSitemapImageExtensionAuditor {
+    /**
+     * Audits image tags in an XML sitemap.
+     */
+    audit(images: SitemapImageTagEntry[]): ImageSitemapAuditReport;
+}

package/dist/analytics/search-engine-sitemap-news-extension-auditor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SearchEngineSitemapNewsExtensionAuditor
+ * Audits Google News XML sitemaps (<news:news>, <news:publication>, <news:publication_date>, <news:title>),
+ * enforcing Google's strict 48-hour freshness rule, ISO-639 language codes, and headline accuracy.
+ */
+export interface SitemapNewsArticleEntry {
+    loc: string;
+    publicationName: string;
+    publicationLanguage: string;
+    publicationDateIso: string;
+    title: string;
+}
+export interface NewsArticleAuditFinding {
+    loc: string;
+    title: string;
+    ageHours: number;
+    isWithin48Hours: boolean;
+    hasValidLanguage: boolean;
+    issues: string[];
+}
+export interface NewsSitemapAuditReport {
+    totalArticlesAudited: number;
+    freshArticlesCount: number;
+    staleArticlesCount: number;
+    newsIndexingComplianceScore: number;
+    findings: NewsArticleAuditFinding[];
+    remediationAdvice: string[];
+    sampleValidNewsXml: string;
+}
+export declare class SearchEngineSitemapNewsExtensionAuditor {
+    private static readonly MAX_FRESHNESS_HOURS;
+    private static readonly ISO_639_LANG_REGEX;
+    /**
+     * Audits news sitemap entries against Google News guidelines.
+     */
+    audit(articles: SitemapNewsArticleEntry[], referenceTimestampMs?: number): NewsSitemapAuditReport;
+}

package/dist/analytics/segment-tree-compiler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Segment Tree Compiler
+ * Clean-room implementation inspired by Matomo SegmentEditor & PostHog Cohort/Filter Boolean Logic.
+ * Compiles nested condition trees (AND, OR, NOT) for audience segmentation,
+ * supports in-memory record filtering, and translates to secure parameterized SQL WHERE clauses.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export type SegmentTreeOperator = 'equals' | 'not_equals' | 'contains' | 'starts_with' | 'greater_than' | 'less_than' | 'in';
+export interface SegmentTreeCondition {
+    field: string;
+    operator: SegmentTreeOperator;
+    value: string | number | boolean | (string | number)[];
+}
+export interface SegmentNode {
+    type: 'and' | 'or' | 'not' | 'condition';
+    condition?: SegmentTreeCondition;
+    children?: SegmentNode[];
+}
+export declare class SegmentTreeCompiler {
+    /**
+     * Evaluates a segment boolean tree against a single data record in-memory
+     */
+    static evaluate(tree: SegmentNode, record: Record<string, unknown>): boolean;
+    /**
+     * Filters a list of records using the compiled tree
+     */
+    static filterRecords<T extends Record<string, unknown>>(tree: SegmentNode, records: T[]): T[];
+    /**
+     * Compiles the AST into an ANSI / SQLite / Postgres compatible WHERE clause string
+     */
+    static toSqlWhere(tree: SegmentNode): string;
+    private static escapeSql;
+}

package/dist/analytics/semantic-metric-validator.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 🦁 LynxSEO Engine — Semantic Metric Validator & Context Studio
+ *
+ * Certified Metric Definitions & Context Validation System (inspired by Metabase Semantic Layer,
+ * Hex Context Studio, and Cube.js Semantic Catalog).
+ *
+ * Guarantees standard mathematical formulations, validates event and property tracking prerequisites,
+ * detects statistical incompatibilities with breakdown dimensions, and provides actionable setup guidance.
+ */
+export type CertifiedMetricId = "pageviews" | "unique_visitors" | "bounce_rate" | "avg_session_duration" | "conversion_rate" | "cart_abandonment_rate" | "ecommerce_revenue" | "mrr" | "churn_rate" | "arpu" | "capi_match_quality" | "core_web_vitals_lcp" | "core_web_vitals_inp" | "core_web_vitals_cls" | "rage_click_frequency";
+export type MetricUnitType = "count" | "percent" | "duration_s" | "duration_ms" | "currency" | "score";
+export type MetricStatus = "certified" | "ready" | "missing_prerequisites" | "degraded";
+export interface CertifiedMetric {
+    id: CertifiedMetricId;
+    label: string;
+    category: "traffic" | "engagement" | "conversion" | "ecommerce" | "performance" | "ux";
+    unit: MetricUnitType;
+    formula: string;
+    description: string;
+    requiredEvents: string[];
+    requiredProperties?: string[];
+    allowedBreakouts: string[];
+    forbiddenBreakouts?: string[];
+    setupGuide: {
+        snippetRequirement: string;
+        actionableFix: string;
+    };
+}
+export declare const CERTIFIED_METRICS_CATALOG: Record<CertifiedMetricId, CertifiedMetric>;
+export interface MetricValidationContext {
+    observedEvents: string[];
+    observedProperties?: Record<string, string[]>;
+}
+export interface MetricValidationResult {
+    metricId: CertifiedMetricId;
+    status: MetricStatus;
+    isReady: boolean;
+    missingEvents: string[];
+    missingProperties: string[];
+    guidance?: string;
+    actionableFix?: string;
+}
+export interface BreakoutValidationResult {
+    metricId: CertifiedMetricId;
+    dimension: string;
+    isValid: boolean;
+    reason?: string;
+}
+export interface ProjectMetricAuditReport {
+    timestamp: string;
+    totalCertified: number;
+    readyCount: number;
+    missingCount: number;
+    metrics: MetricValidationResult[];
+}
+/**
+ * Returns all certified metrics registered in the Semantic Catalog.
+ */
+export declare function getCertifiedMetricsCatalog(): CertifiedMetric[];
+/**
+ * Validates whether a specific certified metric can be reliably calculated given the observed
+ * event tracking in the project.
+ */
+export declare function validateMetricContext(metricId: CertifiedMetricId, context: MetricValidationContext): MetricValidationResult;
+/**
+ * Validates whether a proposed breakout dimension is statistically and mathematically compatible
+ * with the selected metric (preventing statistical fallacies like Simpson's paradox or invalid groupings).
+ */
+export declare function validateMetricBreakout(metricId: CertifiedMetricId, dimension: string): BreakoutValidationResult;
+/**
+ * Audits the readiness of all certified metrics against a project's active telemetry.
+ */
+export declare function auditProjectMetricReadiness(observedEvents: string[], observedProperties?: Record<string, string[]>): ProjectMetricAuditReport;
+export interface AiQueryValidationResult {
+    matchedMetrics: CertifiedMetric[];
+    certifiedSqlSuggestions: string[];
+    warnings: string[];
+    isFullyCertified: boolean;
+}
+/**
+ * Validates natural language questions or LLM-generated SQL against the Certified Semantic Catalog
+ * to prevent hallucinations on business-critical KPIs (e.g. churn, MRR, conversion rate, bounce rate).
+ */
+export declare function validateAiQueryAgainstSemanticMetrics(promptOrQuery: string): AiQueryValidationResult;

package/dist/analytics/seo-content-thinness-readability-score-synthesizer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SeoContentThinnessReadabilityScoreSynthesizer
+ * Evaluates editorial content depth, Flesch Reading Ease, sentence complexity, and transition words,
+ * detecting thin content risks and ensuring alignment with Google Helpful Content Guidelines.
+ */
+export interface ArticleContentInput {
+    url: string;
+    title: string;
+    plainTextBody: string;
+    pageType?: "blog_post" | "product_description" | "landing_page" | "documentation";
+}
+export interface ContentReadabilityMetrics {
+    wordCount: number;
+    sentenceCount: number;
+    syllableCount: number;
+    fleschReadingEase: number;
+    fleschKincaidGradeLevel: number;
+    averageSentenceLengthWords: number;
+    sentencesOver25WordsRatioPercent: number;
+    transitionWordsRatioPercent: number;
+    readabilityVerdict: "very_easy" | "easy" | "fairly_easy" | "standard" | "fairly_difficult" | "difficult" | "very_confusing";
+}
+export interface ContentDepthAssessment {
+    url: string;
+    isThinContent: boolean;
+    contentDepthCategory: "thin" | "shallow" | "adequate" | "comprehensive";
+    readability: ContentReadabilityMetrics;
+    contentQualityScore: number;
+    editorialCritique: string[];
+}
+export declare class SeoContentThinnessReadabilityScoreSynthesizer {
+    private static readonly COMMON_TRANSITION_WORDS;
+    /**
+     * Synthesizes readability, syllable complexity, and content depth into an SEO assessment.
+     */
+    evaluate(input: ArticleContentInput): ContentDepthAssessment;
+    private countSyllables;
+    private getReadabilityVerdict;
+}

package/dist/analytics/seo-split-test-engine.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SEO Split-Testing & Causal Impact Engine — LynxSEO
+ *
+ * Parité fonctionnelle :
+ * - SearchPilot & SplitSignal (Semrush) : URL Group SEO Experimentation
+ * - Évaluation causale par Contrôle Synthétique (Synthetic Control / Difference-in-Differences)
+ *
+ * Problématique résolue :
+ * En SEO, Googlebot ne supporte pas le split-testing 50/50 par cookie utilisateur.
+ * La méthode scientifique consiste à partitionner un ensemble d'URLs homogènes en :
+ * - Groupe Contrôle (témoin non modifié)
+ * - Groupe Variante (URLs recevant l'optimisation SEO : title, schema JSON-LD, H1, maillage)
+ *
+ * Le modèle estime la trajectoire contrefactuelle (ce qu'aurait produit la variante sans le changement)
+ * et calcule le lift organique net cumulé, la valeur p statistique et l'impact annuel projeté.
+ *
+ * Licence : AGPL-3.0-or-later
+ */
+export interface DailyUrlGroupMetric {
+    date: string;
+    controlValue: number;
+    variantValue: number;
+}
+export interface SeoSplitTestInput {
+    testId: string;
+    testName: string;
+    hypothesis: string;
+    metricType: "organic_clicks" | "organic_impressions" | "search_rank";
+    controlUrlCount: number;
+    variantUrlCount: number;
+    experimentStartDate: string;
+    dailyMetrics: DailyUrlGroupMetric[];
+    averageValuePerClick?: number;
+    alpha?: number;
+}
+export interface DailyExperimentImpact {
+    date: string;
+    actualVariant: number;
+    counterfactualVariant: number;
+    dailyLift: number;
+    cumulativeLift: number;
+    lowerConfidence95: number;
+    upperConfidence95: number;
+}
+export interface SeoSplitTestResult {
+    testId: string;
+    testName: string;
+    metricType: string;
+    preTestDays: number;
+    testDays: number;
+    preTestCorrelation: {
+        r2: number;
+        beta: number;
+        alpha: number;
+        isValidBaseline: boolean;
+    };
+    impact: {
+        totalActualClicks: number;
+        totalCounterfactualClicks: number;
+        cumulativeLift: number;
+        relativeLiftPercent: number;
+        tStatistic: number;
+        pValue: number;
+        isStatisticallySignificant: boolean;
+    };
+    verdict: "statistically_significant_winner" | "statistically_significant_loser" | "inconclusive";
+    annualizedRoi: {
+        projectedAnnualClicksLift: number;
+        projectedAnnualRevenueLift: number;
+    };
+    dailyImpacts: DailyExperimentImpact[];
+    recommendations: string[];
+}
+export declare class SeoSplitTestEngine {
+    /**
+     * Analyse l'expérience SEO par contrôle synthétique contrefactuel.
+     */
+    static evaluateTest(input: SeoSplitTestInput): SeoSplitTestResult;
+    private static fitLinearRegression;
+    private static standardDeviation;
+    private static approxTwoTailedPValue;
+    private static generateRecommendations;
+}

package/dist/analytics/serp-ai-overview-citation-auditor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SERP AI Overview Citation Auditor (Batch 14 - Gap 4)
+ *
+ * Generative Engine Optimization (GEO) & AI Overview citation auditor inspired by
+ * Semrush AI Overview Tracker, BrightEdge Generative Parser & Authoritas GEO.
+ *
+ * Audits Google AI Overviews, Perplexity & ChatGPT Search citations across high-value queries,
+ * measures target domain citation share, maps competitor citation dominance, and
+ * surfaces unclaimed AI Overview opportunities.
+ */
+export type GenerativeEngine = "google_ai_overview" | "perplexity" | "chatgpt_search" | "copilot";
+export interface AiCitationSource {
+    domain: string;
+    url: string;
+    title?: string;
+    snippetQuoteText?: string;
+    citationOrder: number;
+}
+export interface AiOverviewQueryResult {
+    query: string;
+    searchVolume?: number;
+    engine: GenerativeEngine;
+    aiOverviewTriggered: boolean;
+    aiOverviewText?: string;
+    citedSources: AiCitationSource[];
+}
+export interface CompetitorCitationShare {
+    domain: string;
+    citationCount: number;
+    queriesCitedCount: number;
+    citationSharePct: number;
+    topCitedUrls: string[];
+}
+export interface UnclaimedAiOverviewOpportunity {
+    query: string;
+    searchVolume: number;
+    engine: GenerativeEngine;
+    topCompetitorCitedDomain: string;
+    competitorSnippetQuote?: string;
+    geoActionPlan: string;
+}
+export interface SerpAiOverviewAuditReport {
+    totalQueriesAudited: number;
+    queriesWithAiOverview: number;
+    aiOverviewTriggerRatePct: number;
+    targetDomain: string;
+    targetDomainCitationCount: number;
+    targetDomainQueryCoveragePct: number;
+    targetDomainAverageCitationRank: number;
+    topCompetitorCitationLeaders: CompetitorCitationShare[];
+    unclaimedOpportunities: UnclaimedAiOverviewOpportunity[];
+    geoActionRecommendations: string[];
+}
+export declare class SerpAiOverviewCitationAuditor {
+    /**
+     * Normalizes hostname to standard domain format (e.g. 'https://www.example.com/page' -> 'example.com')
+     */
+    private static extractRootDomain;
+    /**
+     * Audits AI Overview and Generative Search results for a target domain.
+     */
+    static auditAiCitations(queryResults: AiOverviewQueryResult[], targetDomain: string): SerpAiOverviewAuditReport;
+}

package/dist/analytics/serp-intent-congruence-auditor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SerpIntentCongruenceAuditor — Audit d'Adéquation de l'Intention de Recherche (SERP Intent Congruence)
+ *
+ * Parité : Semrush & Ahrefs (Search Intent Alignment & Content Mismatch Diagnostics).
+ *
+ * Résout la cause n°1 de déclassement algorithmique et de taux de rebond élevé :
+ * Le décalage entre ce que l'utilisateur attend sur Google (Intention de la Requête)
+ * et ce que la page web lui délivre réellement (Contenu & Structure de la Page) :
+ *
+ * 1. Inférence de l'Intention de la Requête Cible :
+ *    - Informational : "comment...", "qu'est-ce que...", "guide...", "pourquoi..."
+ *    - Commercial Investigation : "meilleur...", "top...", "avis...", "vs...", "comparatif..."
+ *    - Transactional : "acheter...", "prix...", "tarif...", "devis...", "télécharger..."
+ *    - Navigational : "connexion...", "login...", "support...", marque seule
+ * 2. Évaluation de l'Intention Réelle Servie par la Page :
+ *    - Analyse la présence de tables de prix, formulaires de devis, listes d'étapes tutoriels,
+ *      tableaux comparatifs et boutons d'appel à l'action (CTA).
+ * 3. Détection des Décalages Critiques (Intent Mismatches) :
+ *    - Requête Informationnelle tombant sur une page de vente pure sans contenu explicatif (Rebond 90%+).
+ *    - Requête Transactionnelle tombant sur un essai académique sans bouton d'achat ni prix visible.
+ * 4. Score de Congruence (0 à 100) et Recommandations d'Alignement Éditorial.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export type QuerySearchIntent = "informational" | "commercial_investigation" | "transactional" | "navigational";
+export interface PageContentProfile {
+    url: string;
+    title: string;
+    targetKeyword: string;
+    wordCount: number;
+    hasPricingTable?: boolean;
+    hasCheckoutOrOrderButton?: boolean;
+    hasHowToSteps?: boolean;
+    hasComparisonTable?: boolean;
+    hasFaqAccordion?: boolean;
+    callToActionCount: number;
+}
+export interface IntentCongruenceReport {
+    targetKeyword: string;
+    queryIntent: QuerySearchIntent;
+    pageDeliveredIntent: QuerySearchIntent;
+    congruenceScore: number;
+    isCongruent: boolean;
+    bounceRateRisk: "low" | "moderate" | "critical";
+    intentDiscrepancies: string[];
+    remediationRoadmap: string[];
+    generatedAt: string;
+}
+export declare class SerpIntentCongruenceAuditor {
+    audit(page: PageContentProfile): IntentCongruenceReport;
+    private inferQueryIntent;
+    private inferPageDeliveredIntent;
+    private emptyReport;
+}

package/dist/analytics/serp-rank-cpc-opportunity-matrix.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SERP Rank & CPC Opportunity Matrix (Batch 18 - Gap 4)
+ *
+ * PPC vs Organic cross-channel arbitrage & cost savings matrix inspired by
+ * SpyFu PPC vs SEO Cross-Matrix, Ahrefs Paid Search Arbitrage & WordStream ROI Matrix.
+ *
+ * Pinpoints expensive PPC keywords already won organically to pause ad spend,
+ * and identifies high-CPC Page 2 keywords representing the highest ROI SEO targets.
+ */
+export interface KeywordCpcRecord {
+    keyword: string;
+    monthlySearchVolume: number;
+    costPerClickUsd: number;
+    organicRank: number | null;
+    isActivelyBiddingPpc?: boolean;
+    currentMonthlyPpcSpendUsd?: number;
+}
+export type CpcArbitrageQuadrant = "ppc_budget_saver" | "organic_arbitrage_target" | "paid_gap_coverage" | "low_value_maintain";
+export interface KeywordCpcArbitrageAnalysis {
+    keyword: string;
+    monthlySearchVolume: number;
+    costPerClickUsd: number;
+    organicRank: number | null;
+    quadrant: CpcArbitrageQuadrant;
+    estimatedMonthlyOrganicValueUsd: number;
+    potentialMonthlyPpcSavingsUsd: number;
+    actionableStrategicAdvice: string;
+}
+export interface SerpRankCpcMatrixReport {
+    totalKeywordsAnalyzed: number;
+    totalMonthlyOrganicValueGeneratedUsd: number;
+    totalPotentialPpcSavingsUsd: number;
+    quadrantDistribution: {
+        ppcBudgetSaversCount: number;
+        organicArbitrageTargetsCount: number;
+        paidGapCoverageCount: number;
+        lowValueMaintainCount: number;
+    };
+    topBudgetSaverOpportunities: KeywordCpcArbitrageAnalysis[];
+    topOrganicArbitrageTargets: KeywordCpcArbitrageAnalysis[];
+    executiveSummary: string[];
+}
+export declare class SerpRankCpcOpportunityMatrix {
+    /**
+     * Evaluates keyword list and correlates SERP ranks with PPC CPC to expose financial arbitrage.
+     */
+    static evaluateMatrix(records: KeywordCpcRecord[]): SerpRankCpcMatrixReport;
+    private static getEstimatedCtr;
+}