@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/analytics/robots-txt-parity-compiler.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Robots.txt Parity Compiler (Batch 16 - Gap 1)
+ *
+ * RFC 9309 compliant robots.txt compiler and URL accessibility simulator
+ * inspired by Google Search Console Robots Testing Tool & Screaming Frog Robots.txt Validator.
+ *
+ * Strictly follows RFC 9309 precedence:
+ * 1. Most specific User-Agent group takes precedence over wildcard (*)
+ * 2. Longest matching path rule wins between Allow and Disallow
+ * 3. Equal length match: Allow wins over Disallow
+ *
+ * Detects critical SEO risks:
+ * - Blocking CSS / JS resources required for Googlebot mobile rendering
+ * - Accidental blanket disallows ("Disallow: /")
+ * - Trailing slash ambiguities and wildcards (*, $)
+ */
+export interface Rfc9309RobotsDirective {
+    type: "allow" | "disallow";
+    pathPattern: string;
+    lineNumber: number;
+}
+export interface UserAgentRuleGroup {
+    userAgentTokens: string[];
+    directives: Rfc9309RobotsDirective[];
+    crawlDelay?: number;
+    sitemaps?: string[];
+}
+export interface UrlCrawlAccessCheck {
+    url: string;
+    userAgent: string;
+    isAllowed: boolean;
+    matchingDirective?: Rfc9309RobotsDirective;
+    matchingUserAgentGroup: string;
+    isResourceBlockingGooglebotRendering: boolean;
+}
+export interface RobotsTxtAuditReport {
+    rawLinesCount: number;
+    ruleGroupsCount: number;
+    sitemapsDiscovered: string[];
+    hasBlanketDisallow: boolean;
+    blocksGooglebotRenderingResources: boolean;
+    accessSimulationResults: UrlCrawlAccessCheck[];
+    criticalDirectivesWarnings: string[];
+}
+export declare class RobotsTxtParityCompiler {
+    /**
+     * Compiles raw robots.txt string into RFC 9309 structured rule groups.
+     */
+    static parseRobotsTxt(rawContent: string): {
+        groups: UserAgentRuleGroup[];
+        globalSitemaps: string[];
+    };
+    /**
+     * Tests whether a given URL is allowed to be crawled by a specific User-Agent
+     * using RFC 9309 rules.
+     */
+    static testUrl(url: string, userAgent: string, parsed: {
+        groups: UserAgentRuleGroup[];
+    }): UrlCrawlAccessCheck;
+    /**
+     * Runs a complete audit on robots.txt and verifies test URLs.
+     */
+    static auditRobotsTxt(rawContent: string, testUrls?: {
+        url: string;
+        userAgent: string;
+    }[]): RobotsTxtAuditReport;
+    private static extractPath;
+    private static matchesPattern;
+}

package/dist/analytics/robots-txt-x-robots-tag-header-conflict-auditor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - RobotsTxtXRobotsTagHeaderConflictAuditor
+ * Detects contradictory indexing signals across robots.txt, X-Robots-Tag headers,
+ * HTML meta robots, and canonical link elements, preventing the classic "ghost indexing" trap.
+ */
+export interface PageDirectivesInput {
+    url: string;
+    isDisallowedInRobotsTxt: boolean;
+    xRobotsTagHeader?: string | string[];
+    htmlMetaRobots?: string;
+    canonicalUrl?: string;
+    httpStatusCode?: number;
+}
+export type DirectiveConflictType = "robots_disallowed_with_noindex_trap" | "robots_disallowed_with_canonical_trap" | "header_vs_meta_conflict" | "noindex_with_canonical_hint" | "none";
+export interface DirectiveIssue {
+    type: DirectiveConflictType;
+    severity: "critical" | "warning" | "info";
+    title: string;
+    explanation: string;
+    recommendedAction: string;
+}
+export type EffectiveIndexabilityStatus = "indexable" | "noindex_crawled" | "blocked_robots_txt" | "ghost_indexing_risk" | "conflicting_restriction";
+export interface DirectiveAuditReport {
+    url: string;
+    effectiveStatus: EffectiveIndexabilityStatus;
+    effectiveIndexable: boolean;
+    effectiveFollowable: boolean;
+    issues: DirectiveIssue[];
+    remediationSnippet?: string;
+}
+export declare class RobotsTxtXRobotsTagHeaderConflictAuditor {
+    /**
+     * Audits page indexing signals and identifies directive conflicts.
+     */
+    audit(input: PageDirectivesInput): DirectiveAuditReport;
+    private parseDirectives;
+}

package/dist/analytics/rollup-aggregator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * RollUp Aggregator — Matomo RollUp Reporting & Umami Multi-Domain Portfolio Parity
+ *
+ * Consolide les métriques analytiques à travers plusieurs sites et domaines d'une organisation :
+ * 1. Portée consolidée (Pages vues, Sessions, Commandes, Revenu global).
+ * 2. Déduplication des visiteurs uniques cross-domaines (modèle de recouvrement paramétrable).
+ * 3. Taux de rebond et durée moyenne de session pondérés par le volume de trafic.
+ * 4. Taux de conversion global e-commerce et panier moyen (AOV).
+ * 5. Répartition en pourcentage de part de trafic et de revenu par site.
+ */
+export interface SiteMetricInput {
+    siteId: string;
+    domain: string;
+    pageviews: number;
+    visits: number;
+    uniqueVisitors: number;
+    bounceRate: number;
+    avgDurationSec: number;
+    revenue?: number;
+    orders?: number;
+}
+export interface SiteContribution {
+    siteId: string;
+    domain: string;
+    pageviews: number;
+    visits: number;
+    uniqueVisitors: number;
+    trafficSharePercent: number;
+    revenueSharePercent: number;
+    bounceRate: number;
+    revenue: number;
+    orders: number;
+}
+export interface ConsolidatedRollupReport {
+    totalSites: number;
+    totalPageviews: number;
+    totalVisits: number;
+    estimatedConsolidatedUniqueVisitors: number;
+    weightedBounceRate: number;
+    weightedAvgDurationSec: number;
+    totalRevenue: number;
+    totalOrders: number;
+    overallConversionRate: number;
+    averageOrderValue: number;
+    topSiteByTraffic: {
+        siteId: string;
+        domain: string;
+        visits: number;
+    };
+    topSiteByRevenue: {
+        siteId: string;
+        domain: string;
+        revenue: number;
+    };
+    breakdown: SiteContribution[];
+    generatedAt: string;
+}
+export declare class RollupAggregator {
+    /**
+     * Agrège et consolide les métriques de plusieurs sites en un rapport exécutif.
+     * @param sites Liste des métriques par site
+     * @param crossDomainOverlapFactor Facteur de recouvrement des visiteurs cross-domaines (0.0 = aucun recouvrement, 0.2 = 20% de visiteurs communs entre domaines)
+     */
+    static aggregatePortfolio(sites: SiteMetricInput[], crossDomainOverlapFactor?: number): ConsolidatedRollupReport;
+}

package/dist/analytics/rss-atom-feed-syndication-discoverability-auditor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - RssAtomFeedSyndicationDiscoverabilityAuditor
+ * Audits RSS 2.0 and Atom XML syndication feeds and HTML head autodiscovery links (<link rel="alternate">),
+ * verifying RFC 822 / ISO 8601 date parsing, guid persistence, enclosure MIME types, and feed freshness.
+ */
+export interface FeedItemData {
+    title: string;
+    link: string;
+    guid?: string;
+    pubDateOrUpdated?: string;
+    descriptionOrSummary?: string;
+    hasEnclosure?: boolean;
+}
+export interface SyndicationFeedPayload {
+    feedType: "rss_2_0" | "atom_1_0";
+    feedUrl: string;
+    title: string;
+    siteUrl: string;
+    description?: string;
+    hasAutodiscoveryInHtmlHead: boolean;
+    items: FeedItemData[];
+}
+export interface FeedAuditIssue {
+    severity: "critical" | "warning" | "info";
+    message: string;
+}
+export interface FeedSyndicationAuditReport {
+    isDiscoverable: boolean;
+    isValidFeed: boolean;
+    feedType: "rss_2_0" | "atom_1_0";
+    itemCount: number;
+    freshnessHours?: number;
+    qualityScore: number;
+    issues: FeedAuditIssue[];
+    metrics: {
+        hasAutodiscoveryTag: boolean;
+        validDateCount: number;
+        guidPresenceRatio: number;
+    };
+    summary: string;
+}
+export declare class RssAtomFeedSyndicationDiscoverabilityAuditor {
+    audit(payload: SyndicationFeedPayload): FeedSyndicationAuditReport;
+}

package/dist/analytics/rss-widget-feed.d.ts

@@ -0,0 +1,75 @@
+/**
+ * RssWidgetParser — Widget RSS de dashboard, sans dépendance (gap Matomo RssWidget)
+ *
+ * Récupère et normalise un flux RSS 2.0 ou Atom pour l'afficher dans un widget :
+ * - Allowlist d'URL strictement https, hôte public (anti-SSRF : loopback, privé, link-local)
+ * - Parseur XML tolérant, sans DTD ni entités externes (protection XXE / entity expansion)
+ * - Nettoyage HTML systématique : le widget ne rend que du texte sûr, jamais du HTML exécutable
+ * - Bornage du volume (octets, nombre d'items, taille des descriptions)
+ */
+export interface RssWidgetItem {
+    title: string;
+    link: string;
+    description: string;
+    publishedAt: string | null;
+    author: string | null;
+    guid: string | null;
+    categories: string[];
+}
+export interface ParsedRssWidgetFeed {
+    format: "rss" | "atom";
+    title: string;
+    link: string | null;
+    description: string | null;
+    generatedAt: string | null;
+    items: RssWidgetItem[];
+    truncated: boolean;
+}
+export declare class RssWidgetParseError extends Error {
+    constructor(message: string);
+}
+export declare class RssWidgetParser {
+    static readonly MAX_ITEMS = 25;
+    static readonly MAX_DESCRIPTION_CHARS = 500;
+    static readonly MAX_XML_BYTES = 2000000;
+    /**
+     * Vérifie qu'une URL de flux est sûre à récupérer côté serveur.
+     * Strictement https, hôte public, sans credentials, sans hash, port 443 implicite uniquement.
+     */
+    static isAllowedFeedUrl(raw: string): boolean;
+    /**
+     * Parse un flux RSS 2.0 ou Atom en structure normalisée.
+     */
+    static parse(xml: string, options?: {
+        maxItems?: number;
+    }): ParsedRssWidgetFeed;
+    /**
+     * Réduit un fragment (HTML, CDATA, entités) à du texte sûr et borné.
+     */
+    static stripHtml(input: string): string;
+    private static parseRss;
+    private static parseAtom;
+    /** Sélectionne le href du premier <link> alternatif (ou sans rel) dans un noeud Atom. */
+    private static atomLink;
+    private static parseXml;
+    private static findTagEnd;
+    private static parseAttrs;
+    private static syntheticRoot;
+    private static findElement;
+    private static findElements;
+    /** Premier enfant dont le nom local (sans préfixe de namespace) correspond. */
+    private static child;
+    private static childrenNamed;
+    private static localName;
+    private static rawText;
+    private static cleanText;
+    private static nullableText;
+    private static toIsoOrNull;
+    /** N'accepte que des liens http(s) absolus ou relatifs résolus contre le lien du flux. */
+    private static sanitizeLink;
+    private static byteLength;
+    private static decodeEntities;
+    private static removeScriptAndStyle;
+    private static isPrivateIpv4;
+    private static isPrivateIpv6;
+}

package/dist/analytics/rum.d.ts

@@ -0,0 +1,12 @@
+export type Vital = 'LCP' | 'INP' | 'CLS' | 'TTFB' | 'FCP';
+export declare function rateVital(v: Vital, val: number): 'good' | 'needs-improvement' | 'poor';
+export declare function p75(values: number[]): number;
+export declare function summarizeVitals(list: Array<{
+    metric: Vital;
+    value: number;
+}>): {
+    metric: Vital;
+    count: number;
+    p75: number;
+    rating: "good" | "poor" | "needs-improvement";
+}[];

package/dist/analytics/scheduled-reports-engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-Format Scheduled Reports Generator Engine
+ *
+ * Clean-room implementation inspired by Matomo ScheduledReports.
+ * Generates automated scheduled analytics digests (Daily, Weekly, Monthly)
+ * formatted for Email HTML summaries, JSON exports, or CSV tabular representations.
+ */
+export interface ScheduledReportConfig {
+    id: string;
+    siteId: string;
+    name: string;
+    frequency: "daily" | "weekly" | "monthly";
+    format: "html" | "json" | "csv";
+    recipients: string[];
+    metricsIncluded: Array<"visits" | "pageviews" | "bounce_rate" | "top_pages" | "revenue" | "errors">;
+    enabled: boolean;
+    lastSentAt?: string;
+}
+export interface ReportMetricData {
+    siteName: string;
+    period: string;
+    visits: number;
+    pageviews: number;
+    bounceRatePct: number;
+    topPages: Array<{
+        url: string;
+        views: number;
+    }>;
+    revenue?: number;
+    errors?: number;
+}
+export declare class ScheduledReportsEngine {
+    private reports;
+    registerReport(report: ScheduledReportConfig): void;
+    getReport(id: string): ScheduledReportConfig | undefined;
+    generateReportContent(reportId: string, data: ReportMetricData): {
+        format: string;
+        content: string;
+    };
+    clear(): void;
+}

package/dist/analytics/schema-discrepancy-validator.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - Schema Discrepancy Validator (Batch 15 - Gap 2)
+ *
+ * Structured data (JSON-LD) vs Visible DOM discrepancy validator inspired by
+ * Google Rich Results Test & Screaming Frog Structured Data Validator.
+ *
+ * Prevents Google Rich Snippet manual actions and disqualifications by detecting:
+ * - Price discrepancies between JSON-LD and visible text
+ * - Availability mismatches (e.g. InStock vs "Sold Out")
+ * - Rating / Review count inflation
+ * - Missing required schema fields for Google Rich Results (Product, Article, FAQ, LocalBusiness)
+ */
+export interface SchemaJsonLdPayload {
+    context?: string;
+    type: string;
+    name?: string;
+    headline?: string;
+    image?: string | string[];
+    datePublished?: string;
+    author?: unknown;
+    offers?: {
+        price?: number | string;
+        priceCurrency?: string;
+        availability?: string;
+        url?: string;
+    };
+    aggregateRating?: {
+        ratingValue?: number | string;
+        reviewCount?: number | string;
+        bestRating?: number | string;
+    };
+    address?: unknown;
+    telephone?: string;
+    mainEntity?: Array<{
+        type?: string;
+        name?: string;
+        acceptedAnswer?: {
+            text?: string;
+        };
+    }>;
+    rawJsonLd?: Record<string, unknown>;
+}
+export interface VisibleDomSnapshot {
+    pageUrl: string;
+    visibleHeadline?: string;
+    visiblePrice?: number;
+    visibleCurrency?: string;
+    visibleAvailability?: "InStock" | "OutOfStock" | "PreOrder" | "Unknown";
+    visibleRatingValue?: number;
+    visibleReviewCount?: number;
+    visibleFaqQuestions?: string[];
+}
+export type DiscrepancySeverity = "critical_violation" | "warning" | "info";
+export interface SchemaDiscrepancyIssue {
+    issueCode: "price_mismatch" | "availability_mismatch" | "rating_inflation" | "missing_required_field" | "schema_dom_headline_mismatch";
+    severity: DiscrepancySeverity;
+    schemaType: string;
+    field: string;
+    schemaValue: unknown;
+    domValue: unknown;
+    impactDescription: string;
+    remediationAdvice: string;
+}
+export interface SchemaDiscrepancyAuditReport {
+    pageUrl: string;
+    schemaTypeDetected: string;
+    richResultsEligible: boolean;
+    complianceScore: number;
+    discrepanciesCount: number;
+    issues: SchemaDiscrepancyIssue[];
+    googleRichResultDirectives: string[];
+}
+export declare class SchemaDiscrepancyValidator {
+    /**
+     * Validates JSON-LD schema against visible DOM snapshot to detect discrepancies.
+     */
+    static validateSchemaVsDom(schema: SchemaJsonLdPayload, dom: VisibleDomSnapshot): SchemaDiscrepancyAuditReport;
+}

package/dist/analytics/schema-graph-auditor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 🕸️ Schema.org Interconnected @graph & Rich Results Auditor
+ * Clean-room implementation inspired by Google Rich Results Test & Schema App.
+ *
+ * Validates complex interconnected JSON-LD @graph architectures, resolves @id URI references,
+ * checks Google Search Rich Results mandatory properties, and detects isolated schema islands.
+ *
+ * @license AGPL-3.0-or-later
+ */
+export interface SchemaNode {
+    "@type": string | string[];
+    "@id"?: string;
+    [key: string]: unknown;
+}
+export interface SchemaGraphPayload {
+    "@context"?: string | Record<string, unknown>;
+    "@graph"?: SchemaNode[];
+    [key: string]: unknown;
+}
+export type SchemaIssueSeverity = "critical" | "warning" | "info";
+export interface SchemaGraphIssue {
+    nodeType: string;
+    nodeId?: string;
+    severity: SchemaIssueSeverity;
+    rule: string;
+    message: string;
+    missingProperty?: string;
+    suggestedFix?: string;
+}
+export interface SchemaEntitySummary {
+    nodeType: string;
+    nodeId?: string;
+    hasId: boolean;
+    inboundReferencesCount: number;
+    outboundReferencesCount: number;
+    isOrphanIsland: boolean;
+    eligibleForRichResults: boolean;
+}
+export interface SchemaGraphAuditReport {
+    isValidJsonLd: boolean;
+    totalEntitiesCount: number;
+    richResultEligibilityScore: number;
+    entities: SchemaEntitySummary[];
+    issues: SchemaGraphIssue[];
+    danglingReferenceIds: string[];
+    orphanIslandsCount: number;
+    summary: {
+        status: "eligible" | "warnings" | "invalid";
+        identifiedTypes: string[];
+    };
+}
+export declare class SchemaGraphAuditor {
+    /**
+     * Audits a JSON-LD object or parsed @graph array.
+     */
+    static audit(rawPayload: unknown): SchemaGraphAuditReport;
+    private static validateEntityType;
+    private static extractReferencedIds;
+}

package/dist/analytics/schema-org-course-educational-credential-auditor.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SchemaOrgCourseEducationalCredentialAuditor
+ * Audits Google Course Rich Results structured data (Schema.org Course & EducationalOccupationalCredential),
+ * verifying mandatory course title, description, provider authority, course instance offerings,
+ * pricing transparency, and recognized educational credential metadata.
+ */
+export interface CourseProviderInfo {
+    type?: "Organization" | "Person";
+    name?: string;
+    url?: string;
+    sameAs?: string | string[];
+}
+export interface CourseInstanceInfo {
+    courseMode?: "online" | "onsite" | "blended" | string;
+    startDate?: string;
+    endDate?: string;
+    location?: string | {
+        name?: string;
+        address?: string;
+    };
+    instructor?: {
+        name?: string;
+    };
+}
+export interface CourseOfferInfo {
+    price?: number | string;
+    priceCurrency?: string;
+    category?: "Free" | "Paid" | "Subscription" | string;
+    availability?: string;
+    url?: string;
+}
+export interface EducationalCredentialInfo {
+    credentialCategory?: "degree" | "certificate" | "badge" | "diploma" | string;
+    name?: string;
+    recognizedBy?: {
+        name?: string;
+    };
+    validIn?: {
+        name?: string;
+    };
+}
+export interface SchemaOrgCoursePayload {
+    name?: string;
+    description?: string;
+    provider?: CourseProviderInfo;
+    courseCode?: string;
+    hasCourseInstance?: CourseInstanceInfo | CourseInstanceInfo[];
+    offers?: CourseOfferInfo | CourseOfferInfo[];
+    educationalCredentialAwarded?: string | EducationalCredentialInfo | EducationalCredentialInfo[];
+    totalHistoricalEnrollment?: number;
+    inLanguage?: string;
+    aggregateRating?: {
+        ratingValue?: number | string;
+        reviewCount?: number | string;
+    };
+}
+export interface CourseAuditIssue {
+    severity: "critical" | "warning" | "info";
+    field: string;
+    message: string;
+}
+export interface CourseAuditReport {
+    isEligibleForCourseSnippet: boolean;
+    hasAccreditedCredential: boolean;
+    hasTransparentPricing: boolean;
+    hasActiveInstance: boolean;
+    qualityScore: number;
+    missingRequiredFields: string[];
+    missingRecommendedFields: string[];
+    issues: CourseAuditIssue[];
+    metrics: {
+        courseName?: string;
+        providerName?: string;
+        modeOfStudy?: string;
+        credentialType?: string;
+    };
+}
+export declare class SchemaOrgCourseEducationalCredentialAuditor {
+    audit(course: SchemaOrgCoursePayload): CourseAuditReport;
+}

package/dist/analytics/schema-org-recipe-nutritional-information-validator.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @license AGPL-3.0-or-later
+ * LynxSEO - SchemaOrgRecipeNutritionalInformationValidator
+ * Validates Google Recipe Rich Results structured data (Schema.org Recipe),
+ * ensuring full compliance with required fields (name, image, recipeIngredient, recipeInstructions),
+ * recommended fields (prepTime, cookTime, nutrition.calories, aggregateRating),
+ * and ISO 8601 duration formatting.
+ */
+export interface RecipeNutritionData {
+    calories?: string | number;
+    fatContent?: string;
+    saturatedFatContent?: string;
+    carbohydrateContent?: string;
+    sugarContent?: string;
+    fiberContent?: string;
+    proteinContent?: string;
+    sodiumContent?: string;
+    cholesterolContent?: string;
+    servingSize?: string;
+}
+export interface RecipeInstructionStep {
+    text?: string;
+    name?: string;
+    url?: string;
+    image?: string;
+}
+export interface SchemaOrgRecipePayload {
+    name?: string;
+    image?: string | string[] | Array<{
+        url?: string;
+        width?: number;
+        height?: number;
+    }>;
+    description?: string;
+    author?: {
+        name?: string;
+    } | Array<{
+        name?: string;
+    }> | string;
+    datePublished?: string;
+    prepTime?: string;
+    cookTime?: string;
+    totalTime?: string;
+    recipeYield?: string | number | string[];
+    recipeCategory?: string | string[];
+    recipeCuisine?: string | string[];
+    recipeIngredient?: string[];
+    recipeInstructions?: string | string[] | RecipeInstructionStep[] | Array<{
+        itemListElement?: RecipeInstructionStep[];
+    }>;
+    nutrition?: RecipeNutritionData;
+    aggregateRating?: {
+        ratingValue?: number | string;
+        reviewCount?: number | string;
+        ratingCount?: number | string;
+        bestRating?: number | string;
+        worstRating?: number | string;
+    };
+    video?: {
+        name?: string;
+        description?: string;
+        thumbnailUrl?: string | string[];
+        contentUrl?: string;
+        embedUrl?: string;
+        uploadDate?: string;
+    };
+}
+export interface RecipeValidationIssue {
+    severity: "critical" | "warning" | "info";
+    field: string;
+    message: string;
+}
+export interface RecipeValidationReport {
+    isEligibleForRichSnippet: boolean;
+    hasNutritionalInfo: boolean;
+    hasRating: boolean;
+    hasVideo: boolean;
+    qualityScore: number;
+    missingRequiredFields: string[];
+    missingRecommendedFields: string[];
+    issues: RecipeValidationIssue[];
+    metrics: {
+        ingredientCount: number;
+        instructionCount: number;
+        caloriesDeclared?: string;
+        prepTimeIso?: string;
+        cookTimeIso?: string;
+        totalTimeIso?: string;
+    };
+}
+export declare class SchemaOrgRecipeNutritionalInformationValidator {
+    validate(recipe: SchemaOrgRecipePayload): RecipeValidationReport;
+    private validateImage;
+    private countInstructions;
+}