pyseoa-ts/README.md

SEO analysis tools for the web, ported from pyseoa (Python) to TypeScript

# pyseoa-ts

> TypeScript SEO audit library for frontend and microservice use – crawl, analyze, and track progress in real time.

## ✨ Features

- Full or single-page SEO audits
- Real-time progress via callback
- Crawl with depth & page limits
- Rate limiting (delay between requests)
- Custom User-Agent support
- Clean typed output for easy integration

---


## 📦 Installation

```bash
npm install pyseoa-ts
```

---


## 🚀 Quick Usage

```ts
import { runSeoAudit } from "pyseoa-ts";

const summary = await runSeoAudit("https://example.com", {
  crawl: true,
  delayMs: 500,
  userAgent: "MySEOAuditBot/1.0",
}, (progress) => {
  console.log(`[${progress.pageIndex}] ${progress.type.toUpperCase()} ${progress.stage}: ${progress.url}`);
});
```

---


## 🛠 API

### `runSeoAudit(url: string, options?: RunSeoAuditOptions, onProgress?: (progress: AuditProgress) => void): Promise<AuditSummary>`

Audit a single page or entire site (if `crawl: true`).

#### Options:
```ts
type RunSeoAuditOptions = {
  crawl?: boolean;
  maxPages?: number;
  maxDepth?: number;
  delayMs?: number;          // Delay (ms) between pages when crawling
  userAgent?: string;        // Custom User-Agent string
}
```

### Progress Events:
```ts
type AuditProgress = {
  type: "crawl" | "analyze";   // Type of progress
  url: string;                 // Current URL
  pageIndex: number;          // Index of page in crawl
  stage: "fetch" | "skip" | "analyze";  // Progress stage
}
```

---


## 📤 Exports

```ts
// Functions
export { runAnalysis, runSeoAudit };

// Types
export type {
  AuditSummary,
  PageAnalysisResult,
  AnalysisResult,
  TitleResult,
  MetaDescriptionResult,
  H1Result,
  CanonicalResult,
  RobotsResult,
  KeywordsResult,
  OpenGraphResult,
  TwitterCardResult,
  KeywordDensityResult,
  AuditProgress
} from "pyseoa-ts";
```

---


## 📚 License

MIT  
Made by [masem - Mario Semper](https://www.masem.at)