@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/ai-generated-search-snippet-synthesizer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - AiGeneratedSearchSnippetSynthesizer
+ * Simulates generative AI search engine answer extraction (Google AI Overviews,
+ * SearchGPT, Perplexity) from page content, evaluating directness, factual entity density, and snippet length.
+ */
+export interface SnippetSynthesizerInput {
+    targetQuery: string;
+    pageTitle: string;
+    h1: string;
+    sections: Array<{
+        heading?: string;
+        paragraphs: string[];
+    }>;
+}
+export interface ExtractedAnswerCandidate {
+    sourceHeading?: string;
+    paragraphText: string;
+    relevanceScore: number;
+    wordCount: number;
+    entityCount: number;
+    isOptimalLength: boolean;
+    directAnswerScore: number;
+}
+export interface AiSearchSynthesisReport {
+    targetQuery: string;
+    queryIntentDirectness: "direct_definitional" | "procedural_list" | "comparison" | "vague";
+    topCandidate?: ExtractedAnswerCandidate;
+    allCandidates: ExtractedAnswerCandidate[];
+    synthesisReadinessScore: number;
+    hasHighConfidenceExtraction: boolean;
+    synthesizedAiOverviewSnippet: string;
+    optimizationTips: string[];
+}
+export declare class AiGeneratedSearchSnippetSynthesizer {
+    private static readonly OPTIMAL_MIN_WORDS;
+    private static readonly OPTIMAL_MAX_WORDS;
+    /**
+     * Synthesizes and scores extractive snippet candidates for generative search queries.
+     */
+    synthesize(input: SnippetSynthesizerInput): AiSearchSynthesisReport;
+    private tokenize;
+    private isStopword;
+    private classifyIntent;
+}

package/dist/analytics/ai-overviews-citation-passage-relevance-auditor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - AiOverviewsCitationPassageRelevanceAuditor
+ * Analyzes HTML text passages for citeability and excerpt candidate quality in Google AI Overviews,
+ * Perplexity, and LLM search answer engines, scoring information density, entity citation readiness,
+ * definition sentence patterns, and structural bullet formatting.
+ */
+export interface CandidatePassage {
+    id: string;
+    headingContext?: string;
+    text: string;
+    isListOrTable: boolean;
+}
+export interface PassageCitationScore {
+    passageId: string;
+    headingContext?: string;
+    wordCount: number;
+    hasDefinitionPattern: boolean;
+    hasStatisticalEvidence: boolean;
+    hasDirectAnswerFormat: boolean;
+    citationReadinessScore: number;
+    strengths: string[];
+    recommendations: string[];
+}
+export interface AiOverviewsAuditReport {
+    totalPassagesEvaluated: number;
+    topCandidateCount: number;
+    averageCitationScore: number;
+    passages: PassageCitationScore[];
+    bestCitationCandidate?: PassageCitationScore;
+    summary: string;
+}
+export declare class AiOverviewsCitationPassageRelevanceAuditor {
+    audit(passages: CandidatePassage[]): AiOverviewsAuditReport;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * AI Providers & Models Registry Engine
+ *
+ * Clean-room implementation inspired by modern AI tracker plugins (Matomo AIProviders, OpenReplay LLM).
+ * Tracks token usage, latency, error rate, cost estimations, and model performance
+ * across external LLM and AI inference providers (OpenAI, Anthropic, Google Gemini, Mistral, Local Ollama, etc.).
+ */
+export interface AIProviderModelConfig {
+    provider: "openai" | "anthropic" | "gemini" | "mistral" | "ollama" | "groq" | "custom";
+    model: string;
+    costPer1kPromptTokensUsd: number;
+    costPer1kCompletionTokensUsd: number;
+}
+export interface AIInferenceEvent {
+    id: string;
+    provider: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    latencyMs: number;
+    status: "success" | "error" | "rate_limited" | "timeout";
+    errorMessage?: string;
+    timestamp: string;
+    sessionId?: string;
+    userId?: string;
+    promptTemplateId?: string;
+}
+export interface AIProviderSummary {
+    provider: string;
+    model: string;
+    totalCalls: number;
+    successfulCalls: number;
+    failedCalls: number;
+    errorRate: number;
+    avgLatencyMs: number;
+    p95LatencyMs: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalTokens: number;
+    estimatedCostUsd: number;
+}
+export interface AIModelBenchmark {
+    fastestModel: string;
+    cheapestModel: string;
+    mostReliableModel: string;
+    summaries: AIProviderSummary[];
+}
+export declare class AIProvidersTracker {
+    private events;
+    private modelPricing;
+    constructor(defaultPricing?: AIProviderModelConfig[]);
+    registerPricing(pricing: AIProviderModelConfig): void;
+    recordInference(event: Omit<AIInferenceEvent, "id" | "totalTokens" | "timestamp"> & {
+        timestamp?: string;
+    }): AIInferenceEvent;
+    getSummaries(filter?: {
+        provider?: string;
+        since?: string;
+    }): AIProviderSummary[];
+    getBenchmark(): AIModelBenchmark;
+    clear(): void;
+}

package/dist/analytics/ai-sov.d.ts

@@ -0,0 +1,21 @@
+export type AiEngine = 'chatgpt' | 'perplexity' | 'google_ai' | 'claude' | 'gemini' | 'grok' | 'other';
+export interface AiRow {
+    engine: AiEngine;
+    url: string;
+    citedUrl?: string;
+    visible: boolean;
+    checkedAt: string;
+    passage?: string;
+    query?: string;
+}
+export declare function computeSov(rows: AiRow[]): {
+    engine: AiEngine;
+    total: number;
+    cited: number;
+    sov: number;
+    passageCoverage: number;
+}[];
+export declare function topCited(rows: AiRow[]): {
+    url: string;
+    count: number;
+}[];

package/dist/analytics/alerts-engine.d.ts

@@ -0,0 +1,24 @@
+export interface AlertRule {
+    id: string;
+    siteId: string;
+    enabled: boolean;
+    type: 'position_drop' | 'status_change' | 'title_change' | 'canonical_change' | 'robots_change' | 'ai_visibility_drop' | 'cwvc_drop';
+    threshold?: number;
+    channels?: ('inapp' | 'email')[];
+}
+export interface AlertEvent {
+    ruleId: string;
+    siteId: string;
+    severity: 'low' | 'medium' | 'high';
+    message: string;
+    meta: Record<string, unknown>;
+    createdAt: string;
+}
+/**
+ * Contexte d'évaluation. Volontairement ouvert (clé/valeur) : il provient
+ * soit d'une query string (tout est `string`), soit d'un corps JSON arbitraire,
+ * soit de `diffSnapshots` (tableau `changes`). Les valeurs sont donc lues via
+ * des helpers de narrowing au runtime plutôt que par un typage présumé.
+ */
+export type AlertContext = Record<string, unknown>;
+export declare function evaluateRules(rules: AlertRule[], ctx: AlertContext): AlertEvent[];

package/dist/analytics/anchor-text-diversity-auditor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AnchorTextDiversityAuditor — Audit de Diversité des Ancres de Liens Internes & Détecteur de Cannibalisation
+ *
+ * Parité : Screaming Frog & Sitebulb (Anchor Text Analysis), OnCrawl (Anchor Variety & Inrank Cannibalization).
+ *
+ * Analyse la distribution et la qualité sémantique des ancres de liens internes :
+ * 1. Détection de la Cannibalisation d'Ancres (Anchor Cannibalization) :
+ *    - Une même ancre descriptive (ex: "logiciel crm saas") pointant vers 2 URLs cibles différentes,
+ *      créant une confusion sémantique pour Google sur la page légitime à positionner.
+ * 2. Détection des Ancres Génériques & Vides (Low-Value Anchors) :
+ *    - "cliquez ici", "click here", "en savoir plus", "read more", "lien", ou liens images sans texte alt.
+ * 3. Risque de Sur-Optimisation d'Ancre Exacte (Over-Optimization Penalty Risk) :
+ *    - Détecte si une page reçoit plus de 60% de ses liens avec la même ancre mot-à-mot (manque de naturel).
+ * 4. Calcul de l'Indice de Diversité Sémantique (Entropie de Shannon normalisée, 0 à 1).
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface InternalLinkOccurrence {
+    sourceUrl: string;
+    targetUrl: string;
+    anchorText: string;
+    isImageLink?: boolean;
+    altText?: string;
+}
+export interface TargetPageAnchorProfile {
+    targetUrl: string;
+    totalInlinks: number;
+    uniqueAnchorsCount: number;
+    diversityScore: number;
+    genericAnchorsCount: number;
+    genericAnchorsPercentage: number;
+    topAnchors: {
+        anchor: string;
+        count: number;
+        percentage: number;
+    }[];
+    isOverOptimized: boolean;
+    issues: string[];
+}
+export interface AnchorCannibalizationIssue {
+    anchorText: string;
+    competingTargetUrls: string[];
+    totalOccurrences: number;
+    severity: "high" | "medium";
+    recommendation: string;
+}
+export interface AnchorAuditReport {
+    totalLinksAudited: number;
+    uniqueTargetsCount: number;
+    cannibalizationIssues: AnchorCannibalizationIssue[];
+    overOptimizedPagesCount: number;
+    averageDiversityScore: number;
+    genericAnchorsTotal: number;
+    targetProfiles: TargetPageAnchorProfile[];
+    remediationChecklist: string[];
+    generatedAt: string;
+}
+export declare class AnchorTextDiversityAuditor {
+    private static readonly GENERIC_ANCHORS;
+    audit(links: InternalLinkOccurrence[]): AnchorAuditReport;
+    private cleanAnchor;
+    private normalizeUrl;
+    private emptyReport;
+}

package/dist/analytics/anchor-text-optimization-distribution-analyzer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - AnchorTextOptimizationDistributionAnalyzer
+ * Analyzes internal and inbound anchor text diversity, classifying link text into branded,
+ * exact-match, partial-match, generic, and naked-URL distributions to prevent Google Penguin/spam penalties.
+ */
+export interface LinkAnchorInput {
+    sourceUrl: string;
+    targetUrl: string;
+    anchorText: string;
+    isImageLink?: boolean;
+    imageAltText?: string;
+    relAttributes?: string[];
+}
+export type AnchorClassification = "branded" | "exact_match" | "partial_match" | "generic" | "naked_url" | "empty_or_missing_alt";
+export interface ClassifiedAnchor {
+    link: LinkAnchorInput;
+    classification: AnchorClassification;
+    resolvedText: string;
+}
+export interface TargetUrlAnchorProfile {
+    targetUrl: string;
+    totalInboundLinks: number;
+    distribution: Record<AnchorClassification, number>;
+    exactMatchRatio: number;
+    isOverOptimized: boolean;
+    genericRatio: number;
+    warnings: string[];
+}
+export interface AnchorAnalysisReport {
+    totalLinksAudited: number;
+    totalTargetUrls: number;
+    overallDistribution: Record<AnchorClassification, number>;
+    targetProfiles: TargetUrlAnchorProfile[];
+    flaggedOverOptimizedUrlsCount: number;
+    cannibalizingAnchorPairs: {
+        anchorText: string;
+        conflictingTargetUrls: string[];
+    }[];
+}
+export declare class AnchorTextOptimizationDistributionAnalyzer {
+    private static readonly GENERIC_ANCHOR_PATTERNS;
+    private static readonly EXACT_MATCH_THRESHOLD;
+    /**
+     * Analyzes anchor texts across links against brand terms and targeted keywords.
+     */
+    analyze(links: LinkAnchorInput[], brandNames: string[], targetKeywordsMap?: Record<string, string[]>): AnchorAnalysisReport;
+    private classifyAnchor;
+}

package/dist/analytics/api-playground-generator.d.ts

@@ -0,0 +1,56 @@
+/**
+ * API Playground & Developer SDK Snippet Generator
+ *
+ * Moteur d'exploration interactif d'API inspiré du Rybbit API Playground
+ * et du Matomo API Explorer.
+ *
+ * Fournit :
+ * 1. Le catalogue complet des spécifications d'endpoints analytiques Pulse & CAPI.
+ * 2. Générateur de snippets de code exécutables (cURL, TypeScript fetch, Python requests, Node.js).
+ * 3. Validation de payload de requête client avant envoi.
+ * 4. Documentation des en-têtes d'authentification et des scopes de clés API.
+ */
+export interface ApiParamSpec {
+    name: string;
+    in: "path" | "query" | "header" | "body";
+    type: "string" | "number" | "boolean" | "object" | "array";
+    required: boolean;
+    description: string;
+    defaultValue?: unknown;
+    example?: unknown;
+}
+export interface ApiEndpointSpec {
+    id: string;
+    category: "ingest" | "analytics" | "capi" | "governance" | "query";
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    summary: string;
+    description: string;
+    requiredScope: string;
+    parameters: ApiParamSpec[];
+    sampleRequestBody?: Record<string, unknown>;
+    sampleResponse?: Record<string, unknown>;
+}
+export interface GeneratedSnippetBundle {
+    curl: string;
+    typescript: string;
+    python: string;
+}
+export declare class ApiPlaygroundGenerator {
+    /**
+     * Spécifications complètes des endpoints LynxSEO Analytics.
+     */
+    private static readonly ENDPOINTS;
+    /**
+     * Retourne la liste complète des endpoints documentés.
+     */
+    static listEndpoints(): ApiEndpointSpec[];
+    /**
+     * Trouve la spécification d'un endpoint par son ID.
+     */
+    static getEndpoint(id: string): ApiEndpointSpec | undefined;
+    /**
+     * Génère les snippets cURL, TypeScript et Python pour un endpoint donné.
+     */
+    static generateSnippets(endpoint: ApiEndpointSpec, baseUrl?: string, apiKey?: string, customBody?: Record<string, unknown>): GeneratedSnippetBundle;
+}

package/dist/analytics/api-rate-limit-quota-shield.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - API Rate Limit Quota Shield (Batch 12 - Gap 3)
+ *
+ * Distributed Sliding-Window Token Bucket rate limiter & quota shield.
+ * Protects analytics ingestion endpoints, public SEO crawling proxies, and export APIs.
+ * Generates RFC 6585 (429 Too Many Requests) and IETF Draft RateLimit headers.
+ */
+export interface RateLimitTierConfig {
+    tierName: string;
+    maxRequestsPerWindow: number;
+    windowSeconds: number;
+    burstAllowance?: number;
+}
+export interface RateLimitConsumptionRequest {
+    key: string;
+    cost?: number;
+    tier?: string;
+    timestampMs?: number;
+}
+export interface RateLimitShieldDecision {
+    allowed: boolean;
+    key: string;
+    tier: string;
+    limit: number;
+    remaining: number;
+    resetSeconds: number;
+    retryAfterSeconds?: number;
+    standardHeaders: {
+        "RateLimit-Limit": string;
+        "RateLimit-Remaining": string;
+        "RateLimit-Reset": string;
+        "Retry-After"?: string;
+    };
+    reason?: "QUOTA_EXCEEDED" | "BURST_EXCEEDED" | "SHIELD_CIRCUIT_OPEN";
+}
+export interface BucketState {
+    tokens: number;
+    lastRefillMs: number;
+    windowStartMs: number;
+    requestCountInWindow: number;
+}
+export declare const DEFAULT_RATE_LIMIT_TIERS: Record<string, RateLimitTierConfig>;
+export declare class ApiRateLimitQuotaShield {
+    private buckets;
+    private tiers;
+    constructor(customTiers?: Record<string, RateLimitTierConfig>);
+    /**
+     * Consumes request tokens from the bucket using sliding token replenishment.
+     */
+    evaluateRequest(req: RateLimitConsumptionRequest): RateLimitShieldDecision;
+    /**
+     * Resets quota state for an API key or IP (e.g. after manual unblock or upgrade).
+     */
+    resetKey(key: string): void;
+    /**
+     * Cleans up expired buckets that have been inactive for more than 2 full windows.
+     */
+    purgeStaleBuckets(now?: number): number;
+}

package/dist/analytics/attribution-markov-chain-engine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Attribution Markov Chain Engine (Batch 17 - Gap 3)
+ *
+ * Algorithmic Multi-Touch Attribution (MTA) engine using First-Order Markov Chains
+ * and Removal Effect calculations, inspired by Google Attribution 360 & ChannelMix.
+ *
+ * Replaces naive First-Touch / Last-Touch bias with probabilistic transition matrices.
+ * Quantifies the true marginal conversion value contributed by organic search,
+ * content nurturing, social, and paid ads.
+ */
+export interface CustomerTouchpointJourney {
+    journeyId: string;
+    touchpoints: string[];
+    converted: boolean;
+    conversionValue?: number;
+}
+export interface ChannelAttributionMetric {
+    channel: string;
+    removalEffect: number;
+    markovAttributedConversions: number;
+    markovAttributedValue: number;
+    markovWeightPercent: number;
+    firstTouchAttributedConversions: number;
+    lastTouchAttributedConversions: number;
+    lastClickUndervaluationRatio: number;
+}
+export interface MultiTouchMarkovAttributionReport {
+    totalJourneys: number;
+    convertedJourneys: number;
+    totalConversionValue: number;
+    baselineConversionRatePercent: number;
+    channels: ChannelAttributionMetric[];
+    topAssistingChannel: string;
+    topClosingChannel: string;
+    attributionInsights: string[];
+}
+export declare class AttributionMarkovChainEngine {
+    /**
+     * Evaluates customer touchpoint journeys and computes Markov chain removal effects.
+     */
+    static calculateMarkovAttribution(journeys: CustomerTouchpointJourney[]): MultiTouchMarkovAttributionReport;
+    /**
+     * Solves conversion probability from (start) to (conversion) using
+     * random walk / transition probabilities, optionally removing a specific channel.
+     */
+    private static computeConversionProbability;
+}

package/dist/analytics/attribution.d.ts

@@ -0,0 +1,8 @@
+export type Touch = {
+    channel: string;
+    ts: number;
+};
+export declare function attrFirst(t: Touch[]): string;
+export declare function attrLast(t: Touch[]): string;
+export declare function attrLinear(t: Touch[]): Record<string, number>;
+export declare function attrTimeDecay(t: Touch[], halfLifeH?: number): Record<string, number>;

package/dist/analytics/automated-analytics-report-renderer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AutomatedAnalyticsReportRenderer — Générateur de rapports analytiques planifiés (Rybbit & Matomo Scheduled Digest Parity)
+ *
+ * Produit un document HTML auto-contenu et imprimable en PDF haute-fidélité pour
+ * l'envoi automatisé de bilans de performance analytique et SEO (hebdomadaire, mensuel) :
+ * - Tableau de bord exécutif (visiteurs uniques, sessions, pages vues, taux de rebond, durée moyenne)
+ * - Comparatifs d'évolution (deltas vs période précédente) avec pastilles colorées
+ * - Mini-graphiques sparklines vectoriels inline SVG sans dépendance externe
+ * - Top pages de destination, sources de trafic et canaux d'acquisition
+ * - Indicateurs Core Web Vitals réels (LCP, CLS, INP)
+ * - Recommandations d'optimisation prioritaires.
+ */
+export interface MetricDelta {
+    current: number;
+    previous: number;
+    changePct: number;
+    isPositiveGood?: boolean;
+}
+export interface ReportTopPage {
+    path: string;
+    views: number;
+    bounceRatePct: number;
+}
+export interface ReportTopSource {
+    source: string;
+    medium: string;
+    visitors: number;
+    sharePct: number;
+}
+export interface ReportWebVitals {
+    lcpMs: number;
+    cls: number;
+    inpMs: number;
+    rating: "good" | "needs_improvement" | "poor";
+}
+export interface ScheduledAnalyticsReportData {
+    projectName: string;
+    domain: string;
+    periodLabel: string;
+    generatedAt: string;
+    metrics: {
+        uniqueVisitors: MetricDelta;
+        totalVisits: MetricDelta;
+        pageviews: MetricDelta;
+        bounceRate: MetricDelta;
+        avgSessionDurationSec: MetricDelta;
+    };
+    sparklineData?: number[];
+    topPages: ReportTopPage[];
+    topSources: ReportTopSource[];
+    webVitals?: ReportWebVitals;
+    recommendations?: string[];
+}
+export declare class AutomatedAnalyticsReportRenderer {
+    /**
+     * Échappe les caractères HTML sensibles
+     */
+    private static escape;
+    /**
+     * Génère un sparkline SVG inline léger et auto-contenu
+     */
+    static renderSparklineSvg(data: number[], width?: number, height?: number, color?: string): string;
+    /**
+     * Formate un delta sous forme de badge HTML stylisé
+     */
+    private static renderDeltaBadge;
+    /**
+     * Génère le document HTML complet et imprimable
+     */
+    static render(data: ScheduledAnalyticsReportData): string;
+}

package/dist/analytics/b2b-group-analytics-engine.d.ts

@@ -0,0 +1,64 @@
+/**
+ * B2BGroupAnalyticsEngine — Agrégateur d'Analytics B2B Multi-Tenant par Entreprise / Organisation
+ *
+ * Parité : PostHog Group Analytics, Amplitude Account-Based Reporting, Mixpanel Company Analytics.
+ *
+ * Dans les produits B2B SaaS, l'analyse au niveau de l'utilisateur individuel est insuffisante :
+ * les décisions de vente, d'expansion et de renouvellement se prennent au niveau du compte
+ * (Entreprise, Espace de Travail, Organisation).
+ *
+ * Fonctionnalités du moteur :
+ * 1. Association Multi-Tenant Utilisateur -> Groupe (Organization / Company / Workspace).
+ * 2. Métriques Agrégées au Niveau du Compte :
+ *    - DAU, WAU, MAU du Compte (nombre d'utilisateurs uniques actifs dans l'entreprise).
+ *    - Taux d'Utilisation des Sièges (Seat Utilization Rate = Sièges actifs / Sièges achetés).
+ *    - Score de Santé du Compte (Account Health Score, 0 à 100).
+ *    - Risque de Non-Renouvellement / Churn B2B (Critical, Moderate, Healthy).
+ * 3. Funnels et Adoption de Fonctionnalités au Niveau Entreprise :
+ *    - Évalue si au moins un membre de l'organisation a activé la fonctionnalité clé.
+ *
+ * Implémentation Clean-Room sous licence AGPL-3.0.
+ */
+export interface GroupMemberEvent {
+    userId: string;
+    groupId: string;
+    groupType: "organization" | "company" | "workspace";
+    eventName: string;
+    timestamp: string;
+}
+export interface B2BGroupProfile {
+    groupId: string;
+    groupType: "organization" | "company" | "workspace";
+    groupName: string;
+    planTier: "starter" | "pro" | "enterprise";
+    purchasedSeats: number;
+    monthlyContractValue: number;
+    renewalDate: string;
+}
+export interface AccountHealthReport {
+    groupId: string;
+    groupName: string;
+    planTier: string;
+    purchasedSeats: number;
+    activeSeatsLast30Days: number;
+    seatUtilizationPercentage: number;
+    totalEventsLast30Days: number;
+    dauToMauRatio: number;
+    healthScore: number;
+    renewalRisk: "healthy" | "moderate_risk" | "high_churn_risk";
+    adoptedKeyFeatures: string[];
+    recommendations: string[];
+}
+export interface B2BGroupAnalyticsSummary {
+    totalAccountsAudited: number;
+    healthyAccountsCount: number;
+    atRiskAccountsCount: number;
+    averageSeatUtilization: number;
+    totalMrrAtRisk: number;
+    accountReports: AccountHealthReport[];
+    generatedAt: string;
+}
+export declare class B2BGroupAnalyticsEngine {
+    analyzeAccounts(profiles: B2BGroupProfile[], events: GroupMemberEvent[], keyFeatureEvents?: string[]): B2BGroupAnalyticsSummary;
+    private emptySummary;
+}

package/dist/analytics/bandwidth-calculator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * BandwidthCalculator Analytics Engine
+ *
+ * Implements network transfer size tracking, asset categorization (HTML, JS, CSS, Media, API),
+ * bandwidth throughput calculation (Kbps/Mbps), and CDN egress cost estimation.
+ * Parity with Matomo Bandwidth plugin.
+ *
+ * Clean-room implementation under AGPL-3.0-or-later.
+ */
+export interface NetworkTransferEntry {
+    url: string;
+    bytesTransferred: number;
+    durationMs?: number;
+    resourceType?: 'html' | 'javascript' | 'stylesheet' | 'image' | 'font' | 'media' | 'api' | 'other';
+}
+export interface BandwidthUsageSummary {
+    totalBytes: number;
+    totalKilobytes: number;
+    totalMegabytes: number;
+    totalGigabytes: number;
+    averageBytesPerRequest: number;
+    estimatedCostUsd: number;
+    breakdownByType: Record<string, {
+        bytes: number;
+        percentage: number;
+        count: number;
+    }>;
+    averageThroughputKbps: number;
+}
+export declare class BandwidthCalculator {
+    static readonly DEFAULT_COST_PER_GB_USD = 0.08;
+    static inferResourceType(url: string, declaredType?: string): 'html' | 'javascript' | 'stylesheet' | 'image' | 'font' | 'media' | 'api' | 'other';
+    static calculateSummary(entries: NetworkTransferEntry[], costPerGbUsd?: number): BandwidthUsageSummary;
+}