at-mintel/packages/page-audit/README.md

@mintel/page-audit

AI-powered website IST-analysis — combines DataForSEO On-Page crawl data with Gemini Pro to generate a comprehensive German-language audit report.

Setup

Add the following to your .env:

# DataForSEO — get credentials at https://dataforseo.com
# Format: your login email + API password from the dashboard
DATA_FOR_SEO_LOGIN=yourlogin@example.com
DATA_FOR_SEO_PASSWORD=your_api_password

# Or as a single key (login:password)
DATA_FOR_SEO_API_KEY=yourlogin@example.com:your_api_password

# OpenRouter (for AI report)
OPENROUTER_API_KEY=sk-or-...

Usage

CLI

# Full audit with AI report
npx tsx src/cli.ts run https://www.e-tib.com

# Faster: skip AI report (data only)
npx tsx src/cli.ts run https://www.e-tib.com --light

# Custom max pages and output dir
npx tsx src/cli.ts run https://www.e-tib.com --max-pages 100 --output ./out/audits

Programmatic

import { PageAuditor } from '@mintel/page-audit';

const auditor = new PageAuditor({
  dataForSeoLogin: process.env.DATA_FOR_SEO_LOGIN!,
  dataForSeoPassword: process.env.DATA_FOR_SEO_PASSWORD!,
  openrouterKey: process.env.OPENROUTER_API_KEY,
  outputDir: './out/page-audits',
});

const result = await auditor.audit('https://www.e-tib.com', {
  maxPages: 50,
  onProgress: (msg) => console.log(msg),
});

console.log(result.report?.executiveSummary);
console.log(result.report?.seoScore);  // 0-100

What it checks

DataForSEO On-Page (deterministic)

• HTTP status codes, broken pages (4xx/5xx)
• Title tags, meta descriptions, H1 presence
• Image alt attributes
• Internal/external link counts
• Core Web Vitals: LCP, CLS, TTFB
• Viewport meta, canonical tags
• Indexability

AI Report (Gemini Pro)

• Executive summary of current state
• Strengths (what's working)
• Critical issues (urgent fixes)
• Quick wins (high impact, low effort)
• Strategic recommendations
• Scores: SEO (0-100), UX (0-100), Performance (0-100)
• Overall health: critical | needs-work | good | excellent

Output

Results are saved as JSON to out/page-audits/{domain}_{timestamp}.json.

Integration in Estimation Engine

@mintel/page-audit can be used as an optional pre-step in the @mintel/estimation-engine pipeline to enrich the site analysis with real SEO metrics from DataForSEO before the AI estimation runs.