aeorank 2.3.2 → 3.0.0

package/dist/index.d.cts

@@ -1,122 +1,3 @@
-/**
- * AEORank type definitions.
- * Inlined from @aeo/shared to keep the package zero-dependency.
- */
-type Status = 'MISSING' | 'NEARLY EMPTY' | 'POOR' | 'WEAK' | 'PARTIAL' | 'MODERATE' | 'GOOD' | 'STRONG';
-type Severity = 'WORKING' | 'GOOD' | 'GOOD PATTERN' | 'PARTIAL' | 'MISSING' | 'ADD' | 'FIX' | 'FIX IMMEDIATELY' | 'REWRITE' | 'CONFUSING' | 'INCONSISTENT' | 'SPARSE' | 'PERFORMANCE' | 'CLUTTER' | 'PLATFORM LIMIT' | 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'BIG OPPORTUNITY' | 'AEO GOLDMINE' | 'AEO CORE' | 'CORE AEO' | 'AEO deliverable' | 'QUICK WIN' | 'MEASUREMENT';
-type FindingType = 'Test' | 'Good' | 'Bad' | 'Missing' | 'Critical' | 'Issue' | 'Fix' | 'Exists' | 'Calc' | 'Present' | 'Note' | 'Current' | 'Volume' | 'Bonus' | 'Impact';
-type ImpactLevel = 'QUICK WIN' | 'CRITICAL' | 'HIGH' | 'CORE AEO' | 'MEDIUM' | 'LOW' | 'MEASUREMENT' | 'BIG OPPORTUNITY';
-interface ScoreCardItem {
-    id: number;
-    criterion: string;
-    score: number;
-    status: Status;
-    keyFindings: string;
-}
-interface DetailedFinding {
-    type: FindingType;
-    description: string;
-    severity: Severity;
-}
-interface CriterionDetail {
-    id: number;
-    name: string;
-    findings: DetailedFinding[];
-}
-interface Deliverable {
-    id: number;
-    name: string;
-    description: string;
-    effort: string;
-    impact: ImpactLevel;
-}
-interface PitchMetric {
-    metric: string;
-    value: string;
-    significance: string;
-}
-type PageCategory$1 = 'homepage' | 'blog' | 'about' | 'pricing' | 'services' | 'contact' | 'team' | 'resources' | 'docs' | 'cases' | 'faq' | 'content';
-interface PageCriterionScore$1 {
-    criterion: string;
-    criterion_label: string;
-    score: number;
-    weight: number;
-}
-interface PageIssue {
-    check: string;
-    label: string;
-    severity: 'error' | 'warning' | 'info';
-}
-interface PageReview {
-    url: string;
-    title: string;
-    category: PageCategory$1;
-    wordCount: number;
-    issues: PageIssue[];
-    strengths: PageIssue[];
-    aeoScore?: number;
-    criterionScores?: PageCriterionScore$1[];
-}
-interface AuditData {
-    site: string;
-    auditDate: string;
-    auditor: string;
-    engine?: string;
-    overallScore: number;
-    verdict: string;
-    scorecard: ScoreCardItem[];
-    detailedFindings: CriterionDetail[];
-    opportunities: Deliverable[];
-    pitchNumbers: PitchMetric[];
-    bottomLine: string;
-    pagesReviewed?: PageReview[];
-}
-type AuditStatus = 'pass' | 'fail' | 'partial' | 'not_found';
-type Priority = 'P0' | 'P1' | 'P2' | 'P3';
-type FindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
-interface AuditFinding {
-    severity: FindingSeverity;
-    detail: string;
-    fix?: string;
-}
-
-/**
- * Programmatic audit API.
- * Runs the full 7-phase AEO audit pipeline and returns structured results.
- */
-
-interface AuditOptions {
-    /** Skip Puppeteer SPA rendering (default: false) */
-    noHeadless?: boolean;
-    /** Homepage + blog only, skip extra page discovery (default: false) */
-    noMultiPage?: boolean;
-    /** Fetch timeout in ms (default: 15000) */
-    timeout?: number;
-    /** Enable full-site BFS crawl (default: false) */
-    fullCrawl?: boolean;
-    /** Max pages for full crawl (default: 200) */
-    maxPages?: number;
-    /** Parallel fetch concurrency for full crawl (default: 5) */
-    concurrency?: number;
-}
-interface AuditResult extends AuditData {
-    /** True if headless browser was used for SPA rendering */
-    renderedWithHeadless?: boolean;
-    /** Wall-clock seconds */
-    elapsed: number;
-}
-/**
- * Run a complete AEO audit on a domain.
- *
- * @example
- * ```ts
- * import { audit } from 'aeorank';
- * const result = await audit('example.com');
- * console.log(result.overallScore); // 0-100
- * ```
- */
-declare function audit(domain: string, options?: AuditOptions): Promise<AuditResult>;
-
 /**
  * Link graph analysis for full-site AEO audits.
  * Builds an internal link graph, detects orphan pages, pillar pages,
@@ -132,7 +13,7 @@ interface PageNode {
     url: string;
     title: string;
     wordCount: number;
-    category: PageCategory;
+    category: PageCategory$1;
     inDegree: number;
     outDegree: number;
     depth: number;
@@ -212,12 +93,12 @@ interface CriterionResult {
     findings: AuditFinding[];
     fix_priority: Priority;
 }
-type PageCategory = 'homepage' | 'blog' | 'about' | 'pricing' | 'services' | 'contact' | 'team' | 'resources' | 'docs' | 'cases' | 'faq' | 'content';
+type PageCategory$1 = 'homepage' | 'blog' | 'about' | 'pricing' | 'services' | 'contact' | 'team' | 'resources' | 'docs' | 'cases' | 'faq' | 'content';
 interface FetchResult {
     text: string;
     status: number;
     finalUrl?: string;
-    category?: PageCategory;
+    category?: PageCategory$1;
 }
 interface SiteData {
     domain: string;
@@ -332,7 +213,7 @@ interface SitemapDateAnalysis {
 declare function countRecentSitemapDates(sitemapText: string): SitemapDateAnalysis;
 declare function extractRawDataSummary(data: SiteData): RawDataSummary;
 /**
- * Run all 26 criteria checks using pre-fetched site data.
+ * Run all 34 criteria checks using pre-fetched site data.
  * All functions are synchronous (no HTTP calls) - data was already fetched.
  */
 declare function auditSiteFromData(data: SiteData): CriterionResult[];
@@ -342,6 +223,168 @@ declare function auditSiteFromData(data: SiteData): CriterionResult[];
  */
 declare function auditSite(targetUrl: string): Promise<CriterionResult[]>;
 
+/**
+ * V2 Pillar Framework — 5-pillar scoring model.
+ * Maps all 34 criteria into pillars, computes sub-scores,
+ * provides client-friendly names, and calculates top-3 fixes.
+ */
+
+interface PillarScores {
+    answerReadiness: number;
+    contentStructure: number;
+    trustAuthority: number;
+    technicalFoundation: number;
+    aiDiscovery: number;
+}
+interface TopFix {
+    criterion: string;
+    clientName: string;
+    description: string;
+    impactPoints: number;
+    effort: 'Low' | 'Medium' | 'High';
+}
+type PillarName = 'Answer Readiness' | 'Content Structure' | 'Trust & Authority' | 'Technical Foundation' | 'AI Discovery';
+declare const PILLARS: Record<PillarName, string[]>;
+declare const CLIENT_NAMES: Record<string, string>;
+declare function getCriterionPillar(criterionId: string): string;
+declare function computePillarScores(criteria: CriterionResult[]): PillarScores;
+declare function computeTopFixes(criteria: CriterionResult[], count?: number): TopFix[];
+
+/**
+ * AEORank type definitions.
+ * Inlined from @aeo/shared to keep the package zero-dependency.
+ */
+type Status = 'MISSING' | 'NEARLY EMPTY' | 'POOR' | 'WEAK' | 'PARTIAL' | 'MODERATE' | 'GOOD' | 'STRONG';
+type Severity = 'WORKING' | 'GOOD' | 'GOOD PATTERN' | 'PARTIAL' | 'MISSING' | 'ADD' | 'FIX' | 'FIX IMMEDIATELY' | 'REWRITE' | 'CONFUSING' | 'INCONSISTENT' | 'SPARSE' | 'PERFORMANCE' | 'CLUTTER' | 'PLATFORM LIMIT' | 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'BIG OPPORTUNITY' | 'AEO GOLDMINE' | 'AEO CORE' | 'CORE AEO' | 'AEO deliverable' | 'QUICK WIN' | 'MEASUREMENT';
+type FindingType = 'Test' | 'Good' | 'Bad' | 'Missing' | 'Critical' | 'Issue' | 'Fix' | 'Exists' | 'Calc' | 'Present' | 'Note' | 'Current' | 'Volume' | 'Bonus' | 'Impact';
+type ImpactLevel = 'QUICK WIN' | 'CRITICAL' | 'HIGH' | 'CORE AEO' | 'MEDIUM' | 'LOW' | 'MEASUREMENT' | 'BIG OPPORTUNITY';
+interface ScoreCardItem {
+    id: number;
+    criterion: string;
+    score: number;
+    status: Status;
+    keyFindings: string;
+    pillar?: string;
+    clientName?: string;
+    weight?: number;
+}
+interface DetailedFinding {
+    type: FindingType;
+    description: string;
+    severity: Severity;
+}
+interface CriterionDetail {
+    id: number;
+    name: string;
+    findings: DetailedFinding[];
+}
+interface Deliverable {
+    id: number;
+    name: string;
+    description: string;
+    effort: string;
+    impact: ImpactLevel;
+}
+interface PitchMetric {
+    metric: string;
+    value: string;
+    significance: string;
+}
+type PageCategory = 'homepage' | 'blog' | 'about' | 'pricing' | 'services' | 'contact' | 'team' | 'resources' | 'docs' | 'cases' | 'faq' | 'content';
+interface PageCriterionScore$1 {
+    criterion: string;
+    criterion_label: string;
+    score: number;
+    weight: number;
+}
+interface PageIssue {
+    check: string;
+    label: string;
+    severity: 'error' | 'warning' | 'info';
+}
+interface PageReview {
+    url: string;
+    title: string;
+    category: PageCategory;
+    wordCount: number;
+    issues: PageIssue[];
+    strengths: PageIssue[];
+    aeoScore?: number;
+    criterionScores?: PageCriterionScore$1[];
+    pillarScores?: PillarScores;
+    estimatedSiteScore?: number;
+    scoreCapped?: boolean;
+    topFixes?: string[];
+}
+interface AuditData {
+    site: string;
+    auditDate: string;
+    auditor: string;
+    engine?: string;
+    overallScore: number;
+    verdict: string;
+    scorecard: ScoreCardItem[];
+    detailedFindings: CriterionDetail[];
+    opportunities: Deliverable[];
+    pitchNumbers: PitchMetric[];
+    bottomLine: string;
+    pagesReviewed?: PageReview[];
+    pillarScores?: PillarScores;
+    coherenceGated?: boolean;
+    criteriaScored?: number;
+    topFixes?: Array<{
+        fix: string;
+        impact: string;
+        effort: string;
+    }>;
+}
+type AuditStatus = 'pass' | 'fail' | 'partial' | 'not_found';
+type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+type FindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+interface AuditFinding {
+    severity: FindingSeverity;
+    detail: string;
+    fix?: string;
+}
+
+/**
+ * Programmatic audit API.
+ * Runs the full 7-phase AEO audit pipeline and returns structured results.
+ */
+
+interface AuditOptions {
+    /** Skip Puppeteer SPA rendering (default: false) */
+    noHeadless?: boolean;
+    /** Homepage + blog only, skip extra page discovery (default: false) */
+    noMultiPage?: boolean;
+    /** Fetch timeout in ms (default: 15000) */
+    timeout?: number;
+    /** Enable full-site BFS crawl (default: false) */
+    fullCrawl?: boolean;
+    /** Max pages for full crawl (default: 200) */
+    maxPages?: number;
+    /** Parallel fetch concurrency for full crawl (default: 5) */
+    concurrency?: number;
+}
+interface AuditResult extends AuditData {
+    /** True if headless browser was used for SPA rendering */
+    renderedWithHeadless?: boolean;
+    /** Wall-clock seconds */
+    elapsed: number;
+}
+/**
+ * Run a complete AEO audit on a domain.
+ *
+ * @example
+ * ```ts
+ * import { audit } from 'aeorank';
+ * const result = await audit('example.com');
+ * console.log(result.overallScore); // 0-100
+ * ```
+ */
+declare function audit(domain: string, options?: AuditOptions): Promise<AuditResult>;
+
+declare const WEIGHTS: Record<string, number>;
 declare function calculateOverallScore(criteria: CriterionResult[]): number;
 
 /**
@@ -367,16 +410,16 @@ declare function generateBottomLine(score: number, opportunities: Deliverable[],
 
 /**
  * Per-page analysis for instant audit.
- * Runs 12 deterministic checks on each crawled page (no LLM).
+ * Runs 15 deterministic checks on each crawled page (no LLM).
  */
 
-declare function analyzePage(html: string, url: string, category: PageCategory): PageReview;
+declare function analyzePage(html: string, url: string, category: PageCategory$1): PageReview;
 declare function analyzeAllPages(siteData: SiteData): PageReview[];
 
 /**
  * Per-page AEO scoring.
- * Evaluates 14 of 28 criteria that apply at individual page level.
- * Produces a 0-100 AEO score per page.
+ * Evaluates 20 of 34 criteria that apply at individual page level.
+ * Produces a 0-75 AEO score per page (single-page cap at 75).
  */
 
 interface PageCriterionScore {
@@ -388,10 +431,23 @@ interface PageCriterionScore {
 interface PageScoreResult {
     aeoScore: number;
     criterionScores: PageCriterionScore[];
-}
-/**
- * Score a single page against 14 AEO criteria.
- * Returns a 0-100 AEO score and individual criterion scores.
+    scoreCapped?: boolean;
+}
+/** 15. Citation-Ready Writing Quality */
+declare function scoreCitationReadyWriting(html: string): number;
+/** 16. Answer-First Placement */
+declare function scoreAnswerFirstPlacement(html: string): number;
+/** 17. Evidence Packaging */
+declare function scoreEvidencePackaging(html: string): number;
+/** 18. Entity Disambiguation */
+declare function scoreEntityDisambiguation(html: string): number;
+/** 19. Extraction Friction Score */
+declare function scoreExtractionFriction(html: string): number;
+/** 20. Image Context for AI */
+declare function scoreImageContextAI(html: string): number;
+/**
+ * Score a single page against 20 AEO criteria.
+ * Returns a 0-100 AEO score (capped at 75 for single pages) and individual criterion scores.
  */
 declare function scorePage(html: string, url?: string): PageScoreResult;
 /**
@@ -444,6 +500,24 @@ interface CrawlOptions {
     respectRobots?: boolean;
     /** Include asset files — skipped by default */
     includeAssets?: boolean;
+    /** Called after each batch with per-URL results */
+    onProgress?: (event: CrawlProgressEvent) => void;
+}
+interface CrawlProgressEvent {
+    /** URLs attempted in this batch */
+    urls: string[];
+    /** Whether each URL succeeded */
+    results: Array<{
+        url: string;
+        ok: boolean;
+        status?: number;
+    }>;
+    /** Total fetched so far */
+    fetched: number;
+    /** Total discovered so far */
+    discovered: number;
+    /** Max pages limit */
+    maxPages: number;
 }
 interface CrawlResult {
     pages: FetchResult[];
@@ -465,7 +539,7 @@ declare function extractInternalLinks(html: string, domain: string): string[];
 /**
  * Infer PageCategory from URL path patterns.
  */
-declare function inferCategory(url: string): PageCategory;
+declare function inferCategory(url: string): PageCategory$1;
 /**
  * BFS crawl of a site, discovering all internal pages up to maxPages.
  * Seeds from sitemap URLs + homepage internal links.
@@ -631,4 +705,4 @@ interface ComparisonResult {
  */
 declare function compare(domainA: string, domainB: string, options?: AuditOptions): Promise<ComparisonResult>;
 
-export { type AuditData, type AuditFinding, type AuditOptions, type AuditResult, type AuditStatus, CRITERION_LABELS, type ComparisonResult, type CrawlOptions, type CrawlResult, type CriterionComparison, type CriterionDetail, type CriterionResult, type Deliverable, type DetailedFinding, type FetchResult, type FindingSeverity, type FindingType, type FixAction, type FixPhase, type FixPlan, type FixPlanSummary, type HeadlessOptions, type ImpactLevel, type LinkEdge, type LinkGraph, type LinkGraphStats, type PageCategory$1 as PageCategory, type PageCriterionScore$1 as PageCriterionScore, type PageIssue, type PageNode, type PageReview, type PageScoreResult, type ParkedDomainResult, type PitchMetric, type Priority, type RawDataSummary, type RenderingMethod, type ScoreCardItem, type SerializedLinkGraph, type Severity, type SiteData, type SitemapDateAnalysis, type Status, type TopicCluster, analyzeAllPages, analyzePage, audit, auditSite, auditSiteFromData, buildDetailedFindings, buildLinkGraph, buildScorecard, calculateDepths, calculateOverallScore, classifyRendering, compare, countRecentSitemapDates, crawlFullSite, detectClusters, detectHubs, detectParkedDomain, detectPillars, extractAllUrlsFromSitemap, extractContentPagesFromSitemap, extractInternalLinks, extractLinksWithAnchors, extractNavLinks, extractRawDataSummary, fetchMultiPageData, fetchWithHeadless, generateBottomLine, generateComparisonHtmlReport, generateFixPlan, generateHtmlReport, generateOpportunities, generatePitchNumbers, generateVerdict, inferCategory, isSpaShell, prefetchSiteData, scoreAllPages, scorePage, scoreToStatus, serializeLinkGraph };
+export { type AuditData, type AuditFinding, type AuditOptions, type AuditResult, type AuditStatus, CLIENT_NAMES, CRITERION_LABELS, type ComparisonResult, type CrawlOptions, type CrawlResult, type CriterionComparison, type CriterionDetail, type CriterionResult, type Deliverable, type DetailedFinding, type FetchResult, type FindingSeverity, type FindingType, type FixAction, type FixPhase, type FixPlan, type FixPlanSummary, type HeadlessOptions, type ImpactLevel, type LinkEdge, type LinkGraph, type LinkGraphStats, PILLARS, type PageCategory, type PageCriterionScore$1 as PageCriterionScore, type PageIssue, type PageNode, type PageReview, type PageScoreResult, type ParkedDomainResult, type PillarName, type PillarScores, type PitchMetric, type Priority, type RawDataSummary, type RenderingMethod, type ScoreCardItem, type SerializedLinkGraph, type Severity, type SiteData, type SitemapDateAnalysis, type Status, type TopFix, type TopicCluster, WEIGHTS, analyzeAllPages, analyzePage, audit, auditSite, auditSiteFromData, buildDetailedFindings, buildLinkGraph, buildScorecard, calculateDepths, calculateOverallScore, classifyRendering, compare, computePillarScores, computeTopFixes, countRecentSitemapDates, crawlFullSite, detectClusters, detectHubs, detectParkedDomain, detectPillars, extractAllUrlsFromSitemap, extractContentPagesFromSitemap, extractInternalLinks, extractLinksWithAnchors, extractNavLinks, extractRawDataSummary, fetchMultiPageData, fetchWithHeadless, generateBottomLine, generateComparisonHtmlReport, generateFixPlan, generateHtmlReport, generateOpportunities, generatePitchNumbers, generateVerdict, getCriterionPillar, inferCategory, isSpaShell, prefetchSiteData, scoreAllPages, scoreAnswerFirstPlacement, scoreCitationReadyWriting, scoreEntityDisambiguation, scoreEvidencePackaging, scoreExtractionFriction, scoreImageContextAI, scorePage, scoreToStatus, serializeLinkGraph };