@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/gamified-cro-engine.d.ts

@@ -0,0 +1,62 @@
+export interface GamifiedReward {
+    id: string;
+    label: string;
+    discountCode: string;
+    discountPercent?: number;
+    fixedDiscountCents?: number;
+    freeShipping?: boolean;
+    freeGift?: string;
+    freeGiftVariantId?: string;
+    weight: number;
+    color?: string;
+}
+export interface WheelConfig {
+    rewards: GamifiedReward[];
+    spinDurationMs?: number;
+}
+export interface ScratchcardConfig {
+    rewards: GamifiedReward[];
+    scratchAreaPercentageToReveal?: number;
+}
+export interface SlotSymbol {
+    id: string;
+    symbol: string;
+    label: string;
+}
+export interface SlotMachineConfig {
+    reelsCount?: number;
+    symbols?: SlotSymbol[];
+    rewards: GamifiedReward[];
+    spinDurationMs?: number;
+}
+export interface SlotSpinResult {
+    reels: string[];
+    isJackpot: boolean;
+    outcome: GamifiedOutcome;
+}
+export interface GamifiedOutcome {
+    rewardId: string;
+    label: string;
+    discountCode: string;
+    segmentIndex: number;
+    signedToken: string;
+    issuedAt: string;
+}
+export declare class GamifiedCroEngine {
+    private readonly secretKey;
+    constructor(secretKey?: string);
+    /**
+     * Sélectionne un gain selon la distribution de probabilité pondérée (Discrete Cumulative Distribution).
+     */
+    drawReward(rewards: GamifiedReward[], distinctId: string): GamifiedOutcome;
+    /**
+     * Simule un tirage de Machine à Sous (Slot Machine 3 rouleaux).
+     * Aligne 3 symboles identiques pour le jackpot ou le reward sélectionné.
+     */
+    spinSlotMachine(config: SlotMachineConfig, distinctId: string): SlotSpinResult;
+    /**
+     * Vérifie qu'un jeton de gain présenté par le client est authentique et n'a pas été falsifié.
+     */
+    verifyToken(distinctId: string, rewardId: string, discountCode: string, issuedAt: string, token: string, maxAgeMinutes?: number): boolean;
+    private generateToken;
+}

package/dist/gbp-client.d.ts

@@ -0,0 +1,203 @@
+/**
+ * 📍 Google Business Profile (GBP) client.
+ *
+ * Reads public profile data through Google's Business Profile endpoints using an
+ * API key: business profile, reviews, local posts (updates), Q&A, categories and
+ * a local rank grid. The client validates that a key is configured before issuing
+ * a request and never echoes the key into error messages.
+ */
+export interface GbpClientOptions {
+    apiKey?: string;
+    fetchImpl?: typeof globalThis.fetch;
+    baseUrl?: string;
+}
+export interface GbpAddress {
+    addressLines: string[];
+    locality: string;
+    postalCode: string;
+    regionCode: string;
+}
+export interface GbpTime {
+    hours: number;
+    minutes: number;
+}
+export interface GbpHoursPeriod {
+    openDay: "MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" | "FRIDAY" | "SATURDAY" | "SUNDAY";
+    openTime: GbpTime;
+    closeDay?: "MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" | "FRIDAY" | "SATURDAY" | "SUNDAY";
+    closeTime?: GbpTime;
+}
+export interface GbpRegularHours {
+    periods: GbpHoursPeriod[];
+    timeZone?: string;
+}
+export interface BusinessProfile {
+    name: string;
+    title: string;
+    addresses?: GbpAddress;
+    phoneNumbers: string[];
+    primaryCategory: {
+        displayName: string;
+        categoryId: string;
+    };
+    categories: Array<{
+        displayName: string;
+        categoryId: string;
+    }>;
+    websiteUri: string;
+    regularHours?: GbpRegularHours;
+    rating: number;
+    reviewCount: number;
+    latlng?: {
+        latitude: number;
+        longitude: number;
+    };
+}
+export interface GbpReview {
+    name: string;
+    reviewer: {
+        displayName: string;
+        profilePhotoUrl?: string;
+    };
+    rating: number;
+    comment: string;
+    createTime: string;
+    updateTime: string;
+    reviewReply?: {
+        comment: string;
+        updateTime: string;
+    };
+}
+export interface ReviewsResponse {
+    reviews: GbpReview[];
+    nextPageToken?: string;
+}
+export interface GbpUpdate {
+    name: string;
+    languageCode: string;
+    summary: string;
+    callToAction?: {
+        actionType: string;
+        url: string;
+    };
+    media: string[];
+    createTime: string;
+    updateTime: string;
+    searchableState: "PENDING" | "LIVE" | "REJECTED" | "PAUSED";
+}
+export interface UpdatesResponse {
+    localPosts: GbpUpdate[];
+    nextPageToken?: string;
+}
+export interface GbpQuestionAnswer {
+    text: string;
+    author: {
+        displayName: string;
+        profilePhotoUrl?: string;
+    };
+    createTime: string;
+    updateTime: string;
+    isBusinessOwner: boolean;
+}
+export interface GbpQuestion {
+    name: string;
+    displayName: string;
+    text: string;
+    createTime: string;
+    updateTime: string;
+    answerCount: number;
+    answers: GbpQuestionAnswer[];
+}
+export interface QAResponse {
+    questions: GbpQuestion[];
+    nextPageToken?: string;
+}
+export interface GbpCategory {
+    categoryId: string;
+    displayName: string;
+}
+export interface CategoriesResponse {
+    primaryCategory: GbpCategory | null;
+    additionalCategories: GbpCategory[];
+}
+export interface RankGridCell {
+    col: number;
+    row: number;
+    lat: number;
+    lng: number;
+    keyword: string;
+    rank: number | null;
+}
+export interface RankGridResponse {
+    keyword: string;
+    center: {
+        lat: number;
+        lng: number;
+    };
+    gridSize: number;
+    radiusMeters: number;
+    cells: RankGridCell[];
+    fetchedAt: string;
+}
+export declare class GbpClient {
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(options?: GbpClientOptions);
+    get configured(): boolean;
+    private request;
+    private locationPath;
+    /**
+     * Fetches a single business profile (location) by account and location id.
+     */
+    fetchBusinessProfile(params: {
+        accountId: string;
+        locationId: string;
+    }): Promise<BusinessProfile>;
+    /**
+     * Fetches the reviews of a location.
+     */
+    fetchReviews(params: {
+        accountId: string;
+        locationId: string;
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<ReviewsResponse>;
+    /**
+     * Fetches the local posts (updates) of a location.
+     */
+    fetchUpdates(params: {
+        accountId: string;
+        locationId: string;
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<UpdatesResponse>;
+    /**
+     * Fetches the questions & answers (Q&A) of a location.
+     */
+    fetchQA(params: {
+        accountId: string;
+        locationId: string;
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<QAResponse>;
+    /**
+     * Fetches the primary and additional categories of a location.
+     */
+    fetchCategories(params: {
+        accountId: string;
+        locationId: string;
+    }): Promise<CategoriesResponse>;
+    /**
+     * Fetches a simulated local rank grid for a keyword around a location.
+     * There is no official Google endpoint for rank grids; this hits the
+     * `/local-rank-grid` surface of the configured base URL so the call is still
+     * authenticated with the API key.
+     */
+    fetchLocalRankGrid(params: {
+        locationId: string;
+        keyword: string;
+        gridSize?: number;
+        radiusMeters?: number;
+    }): Promise<RankGridResponse>;
+}

package/dist/geo-badge-generator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 🛡️ Dynamic SVG Badge Generator for GEO & AI Discoverability Scores
+ *
+ * Shields.io-standard badge generator for GEO readiness scores.
+ * Renders lightweight, scalable SVG badges embeddable in GitHub READMEs, footers, and dashboards.
+ *
+ * Example:
+ * [![GEO Score](https://lynxseo.app/api/badge?score=94&grade=A)](https://lynxseo.app)
+ */
+export interface BadgeOptions {
+    score: number;
+    label?: string;
+    grade?: string;
+    style?: "flat" | "rounded";
+    isError?: boolean;
+}
+export declare class GeoBadgeGenerator {
+    private static readonly BAND_COLORS;
+    /**
+     * Escape XML / SVG entities to ensure strict SVG validity and prevent injection.
+     */
+    private static escapeXml;
+    /**
+     * Generates a high-quality SVG badge.
+     */
+    static generateBadgeSvg(options: BadgeOptions): string;
+}

package/dist/geo-cdn-waf-auditor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CDN / WAF AI Bot Barrier Auditor
+ * Detects whether Cloudflare, AWS WAF, Akamai, or Fastly block or challenge AI crawlers.
+ *
+ * According to OtterlyAI Citation Report 2026: 73% of web domains exhibit technical barriers
+ * to AI crawlers, and WAF/CDN challenge pages (HTTP 403, Cloudflare Turnstile/Managed Challenge)
+ * are the #2 cause of complete AI search invisibility.
+ */
+export interface BotCdnStatus {
+    botName: string;
+    userAgent: string;
+    isBlockedOrChallenged: boolean;
+    status: "allowed" | "challenged" | "blocked" | "rate_limited";
+    barrierReason?: string;
+}
+export interface CdnWafAuditResult {
+    cdnDetected: "cloudflare" | "aws_cloudfront" | "akamai" | "fastly" | "vercel" | "generic" | "none";
+    hasChallengePage: boolean;
+    challengeType?: "cf_managed_challenge" | "captcha" | "bot_management" | "access_denied";
+    safeForAiSearchBots: boolean;
+    botsStatus: BotCdnStatus[];
+    wafRuleSnippet: {
+        cloudflareExpression: string;
+        description: string;
+    };
+    recommendations: string[];
+}
+export declare const TOP_AI_SEARCH_USER_AGENTS: {
+    name: string;
+    ua: string;
+}[];
+export declare class GeoCdnWafAuditor {
+    /**
+     * Audit response headers and HTML content for CDN / WAF barriers
+     */
+    static audit(headers?: Record<string, string>, html?: string): CdnWafAuditResult;
+}

package/dist/geo-ci-formatter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * LynxSEO GEO CI/CD Formatter & Policy Gate
+ * Formats audit findings into SARIF v2.1.0 (GitHub Code Scanning),
+ * JUnit XML (CI test reporting), and GitHub Step Summary with workflow annotations.
+ */
+export interface GeoCiAuditSummary {
+    url: string;
+    citabilityScore: number;
+    grade: string;
+    categories: {
+        name: string;
+        score: number;
+        maxScore: number;
+        passed: boolean;
+        issues: string[];
+    }[];
+    criticalIssues: string[];
+    warnings: string[];
+    promptInjectionSafe?: boolean;
+}
+export interface GeoGateOptions {
+    minScore?: number;
+    failOnWarning?: boolean;
+}
+export interface GeoGateResult {
+    passed: boolean;
+    exitCode: 0 | 1;
+    reasons: string[];
+}
+export declare class GeoCiFormatter {
+    /**
+     * Formats audit findings as SARIF v2.1.0 for GitHub Code Scanning / SonarQube.
+     */
+    static formatSarif(summary: GeoCiAuditSummary): string;
+    /**
+     * Formats audit findings into JUnit XML format for CI test reporting.
+     */
+    static formatJunit(summary: GeoCiAuditSummary): string;
+    /**
+     * Formats GitHub Step Summary Markdown and workflow command annotations.
+     */
+    static formatGithubSummary(summary: GeoCiAuditSummary): {
+        markdown: string;
+        annotations: string[];
+    };
+    /**
+     * Evaluates CI policy gate and determines exit code.
+     */
+    static evaluateGate(summary: GeoCiAuditSummary, options?: GeoGateOptions): GeoGateResult;
+}

package/dist/geo-citability-scorer.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 🎯 GEO Citability Scorer - 47-Method Princeton & AutoGEO Content Analyzer
+ *
+ * Implements deterministic content analysis based on:
+ * 1. Princeton KDD 2024 ("GEO: Generative Engine Optimization", Aggarwal et al.)
+ * 2. AutoGEO ICLR 2026 (Answer-first heading passage optimization)
+ * 3. Stanford 2025 (Passage density & RAG retrieval optimization)
+ * 4. SE Ranking & Growth Marshal 2026 empirical AI search benchmarks
+ *
+ * Pure In-Memory TypeScript, 0 ML / LLM dependencies, < 1ms execution time.
+ */
+export interface DetectedCitation {
+    url: string;
+    domain: string;
+    text: string;
+    isAuthoritative: boolean;
+}
+export interface DetectedStatistic {
+    raw: string;
+    context: string;
+    type: "percentage" | "currency" | "multiplier" | "scale" | "date";
+}
+export interface DetectedQuote {
+    quote: string;
+    attribution?: string;
+    hasRoleOrOrg: boolean;
+}
+export interface MethodEvaluation {
+    id: string;
+    name: string;
+    category: "princeton" | "autogeo" | "stanford" | "structure";
+    score: number;
+    weight: number;
+    weightedScore: number;
+    measuredImpact: string;
+    detectedCount: number;
+    status: "pass" | "warn" | "fail";
+    details: string;
+}
+export interface CitabilityScoreResult {
+    overallScore: number;
+    grade: "S" | "A" | "B" | "C" | "D" | "F";
+    aiCitationProbability: "TRÈS ÉLEVÉE" | "ÉLEVÉE" | "MOYENNE" | "FAIBLE" | "CRITIQUE";
+    wordCount: number;
+    methods: Record<string, MethodEvaluation>;
+    detected: {
+        citations: DetectedCitation[];
+        statistics: DetectedStatistic[];
+        quotes: DetectedQuote[];
+        answerFirstH2Count: number;
+        totalH2Count: number;
+        optimalPassagesCount: number;
+        totalPassagesCount: number;
+        hedgingPhrases: string[];
+        topRepeatedTerms: Array<{
+            term: string;
+            count: number;
+            density: number;
+        }>;
+    };
+    recommendations: string[];
+}
+export declare const AUTHORITATIVE_TLDS: Set<string>;
+export declare const AUTHORITATIVE_DOMAINS: Set<string>;
+export declare class GeoCitabilityScorer {
+    /**
+     * Evaluates text or HTML content against the 47 GEO Citability standards.
+     */
+    static analyze(rawInput: string): CitabilityScoreResult;
+    private static stripHtml;
+    private static extractCitations;
+    private static extractStatistics;
+    private static extractQuotations;
+    private static evaluateAnswerFirst;
+    private static evaluatePassageDensity;
+    private static evaluateKeywordDensity;
+}

package/dist/geo-competitive-narrative.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ⚔️ GeoCompetitiveNarrative & Gap Analysis Engine
+ *
+ * Extracts how AI answer engines perceive brand positioning versus competitors:
+ * - Dominant adjectives & positioning frames
+ * - Credibility signals (case studies, certifications, metrics)
+ * - Narrative gaps that allow competitors to capture the AI citation
+ * - Side-by-side gap analysis between 2 sites with quantified impact points
+ */
+export interface CompetitorNarrative {
+    url: string;
+    domain: string;
+    brandName: string;
+    dominantAdjectives: string[];
+    keyFrames: string[];
+    positioningStatement: string;
+    credibilitySignals: string[];
+    contentGaps: string[];
+    confidence: number;
+    geoScore: number;
+}
+export interface CompetitiveGapItem {
+    category: "positioning" | "credibility" | "technical" | "schema" | "citability";
+    gapType: "missing" | "weaker" | "opposing";
+    competitorDomain: string;
+    competitorStrength: string;
+    targetMissing: string;
+    actionRecommendation: string;
+    potentialImpactPoints: number;
+}
+export interface CompetitiveNarrativeReport {
+    targetUrl: string;
+    targetDomain: string;
+    targetNarrative: CompetitorNarrative;
+    competitors: CompetitorNarrative[];
+    competitiveGaps: CompetitiveGapItem[];
+    executiveSummary: string;
+    prioritizedActionPlan: {
+        priority: "P0" | "P1" | "P2";
+        action: string;
+        impactPoints: number;
+        targetCategory: string;
+    }[];
+}
+export declare class GeoCompetitiveNarrativeEngine {
+    private static readonly INJECTION_STRIP_REGEX;
+    /**
+     * Sanitizes external scraped text before analysis or LLM prompt formatting.
+     */
+    static sanitizeText(text: string, maxLen?: number): string;
+    /**
+     * Extracts the AI narrative profile for a single domain/page.
+     */
+    static extractNarrative(params: {
+        url: string;
+        html: string;
+        brandName?: string;
+        title?: string;
+        geoScore?: number;
+    }): CompetitorNarrative;
+    /**
+     * Compares the target page against competitor narratives and computes actionable gaps.
+     */
+    static compare(params: {
+        targetUrl: string;
+        targetHtml: string;
+        targetBrand?: string;
+        targetGeoScore?: number;
+        competitors: {
+            url: string;
+            html: string;
+            brandName?: string;
+            geoScore?: number;
+        }[];
+    }): CompetitiveNarrativeReport;
+}

package/dist/geo-content-decay.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Content Decay & Staleness Predictor for GEO / AEO
+ * Detects temporal and factual patterns that cause AI engines to deprioritize stale citations:
+ * - Temporal decay: explicit years/dates (e.g. "En 2023, ...")
+ * - Statistical decay: numeric claims and percentages lacking date anchors
+ * - Version decay: software versions (e.g. "Next.js 13", "Python 3.10")
+ * - Event/recency decay: subjective recency ("récemment", "vient de sortir", "latest release")
+ * - Price decay: monetary amounts without "au [date]" context
+ * - Evergreen Score (0-100) & estimated freshness half-life in days
+ */
+export interface DecaySignal {
+    type: "temporal" | "statistical" | "version" | "event" | "price";
+    context: string;
+    decayDays: number;
+    suggestion: string;
+}
+export interface ContentDecayResult {
+    evergreenScore: number;
+    freshnessHalfLifeDays: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    signals: DecaySignal[];
+    signalsCountByType: Record<"temporal" | "statistical" | "version" | "event" | "price", number>;
+    recommendations: string[];
+}
+export declare class GeoContentDecayPredictor {
+    static predict(textOrHtml: string, currentYear?: number): ContentDecayResult;
+}

package/dist/geo-context-window.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Context Window & RAG Efficiency Analyzer
+ * Evaluates how effectively page content utilizes LLM context windows:
+ * - Token estimation (word count * 1.3 heuristic)
+ * - Front-loading ratio: essential facts, answers & data in the first 30%
+ * - Boilerplate & filler ratio detection
+ * - Truncation risk analysis per platform (RAG chunk, Perplexity, GPT-4o, Claude 3.5)
+ * - Context Efficiency Score (0-100)
+ */
+export interface PlatformContextLimit {
+    name: string;
+    limitTokens: number;
+    fitsComfortably: boolean;
+    truncationRisk: "low" | "medium" | "high";
+}
+export interface ContextWindowResult {
+    totalWords: number;
+    totalTokens: number;
+    frontLoadedRatio: number;
+    fillerRatio: number;
+    efficiencyScore: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    platforms: Record<"ragChunk" | "perplexity" | "chatgpt" | "claude", PlatformContextLimit>;
+    keyFactsCount: number;
+    fillerMatchesCount: number;
+    recommendations: string[];
+}
+export declare class GeoContextWindowAuditor {
+    static audit(textOrHtml: string): ContextWindowResult;
+}

package/dist/geo-diff-engine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A/B Audit Diff & Regression Engine for GEO / AEO
+ * Compares two audit snapshots (Before vs After) to measure progress,
+ * detect regressions, and validate release deployments.
+ */
+import type { GeoScoreResult, ScoreCategory } from "./geo-score-calculator";
+export interface CategoryDelta {
+    category: ScoreCategory;
+    label: string;
+    beforeScore: number;
+    afterScore: number;
+    delta: number;
+    maxScore: number;
+    status: "improved" | "regressed" | "unchanged";
+}
+export interface GapAction {
+    category: ScoreCategory;
+    title: string;
+    rationale: string;
+    impactPoints: number;
+    priority: "high" | "medium" | "low";
+    actionableCommand?: string;
+}
+export interface GeoGapAnalysisResult {
+    weakerUrl: string;
+    strongerUrl: string;
+    weakerScore: number;
+    strongerScore: number;
+    scoreGap: number;
+    weakerBand: string;
+    strongerBand: string;
+    diff: AuditDiffResult;
+    actionPlan: GapAction[];
+    keyStrengthsOfStronger: string[];
+}
+export interface AuditDiffResult {
+    beforeUrl: string;
+    afterUrl: string;
+    beforeScore: number;
+    afterScore: number;
+    scoreDelta: number;
+    beforeBand: string;
+    afterBand: string;
+    hasRegressed: boolean;
+    improvedCategoriesCount: number;
+    regressedCategoriesCount: number;
+    categoryDeltas: CategoryDelta[];
+    regressedCategories: CategoryDelta[];
+    improvedCategories: CategoryDelta[];
+    summary: string;
+    deploymentVerdict: "APPROVED" | "CAUTION_REGRESSION" | "BLOCKED_CRITICAL_DROP";
+}
+export declare class GeoDiffEngine {
+    static compare(before: GeoScoreResult, after: GeoScoreResult): AuditDiffResult;
+    /**
+     * Performs an interpretative Gap Analysis between two sites/snapshots
+     * identifying concrete signals the weaker site lacks compared to the stronger site.
+     */
+    static gapAnalysis(result1: GeoScoreResult, result2: GeoScoreResult): GeoGapAnalysisResult;
+}

package/dist/geo-factual-accuracy-auditor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ⚖️ GeoFactualAccuracyAuditor — Factual Claims, Attribution & Verification Auditor
+ *
+ * Deterministic factual auditing against FactCheck / ClaimReview (Schema.org) standards.
+ *
+ * Checks:
+ * 1. Extraction of empirical/numerical claims (percentages, currencies, multipliers, scales)
+ * 2. Source Attribution Check: Are statistical claims grounded with outbound source citations?
+ * 3. Conflicting Numeric Claims: Identifies conflicting stats on the same entity/topic
+ * 4. Temporal / Copyright Inconsistency: Mismatch between publication/update dates and copyright year
+ * 5. Unverifiable Superlatives: "guaranteed", "revolutionary", "best in the world", "100% infallible"
+ */
+export interface NumericClaim {
+    rawSnippet: string;
+    contextKey: string;
+    values: string[];
+    hasSourceOrAttribution: boolean;
+    citationUrl?: string;
+}
+export interface FactualAccuracyReport {
+    checked: boolean;
+    totalClaimsFound: number;
+    claimsSourcedCount: number;
+    claimsUnsourcedCount: number;
+    sourcingRatePercentage: number;
+    unverifiableSuperlativesCount: number;
+    numericInconsistenciesCount: number;
+    severity: "clean" | "low" | "medium" | "high";
+    claims: NumericClaim[];
+    inconsistencies: string[];
+    unverifiableClaims: string[];
+    recommendations: string[];
+}
+export interface FactualAuditInput {
+    html: string;
+    baseUrl?: string;
+}
+export declare class GeoFactualAccuracyAuditor {
+    static audit(input: FactualAuditInput): FactualAccuracyReport;
+}