@j0hanz/superfetch 1.0.0

package/README.md

@@ -0,0 +1,327 @@
+# 🚀 superFetch
+
+[![npm version](https://img.shields.io/npm/v/@j0hanz/superfetch.svg)](https://www.npmjs.com/package/@j0hanz/superfetch)[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)[![Node.js](https://img.shields.io/badge/Node.js-≥18.0.0-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)[![MCP](https://img.shields.io/badge/MCP-1.0.4-8B5CF6?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQyIDAtOC0zLjU4LTgtOHMzLjU4LTggOC04IDggMy41OCA4IDgtMy41OCA4LTggOHoiLz48L3N2Zz4=)](https://modelcontextprotocol.io/)
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that fetches, extracts, and transforms web content into AI-optimized formats using Mozilla Readability.
+
+[Quick Start](#quick-start) · [Tools](#available-tools) · [Configuration](#configuration) · [Contributing](#contributing)
+
+---
+
+> [!CAUTION]
+> This server can access URLs on behalf of AI assistants. Built-in SSRF protection blocks private IP ranges and cloud metadata endpoints, but exercise caution when deploying in sensitive environments.
+
+## ✨ Features
+
+| Feature                   | Description                                                   |
+| ------------------------- | ------------------------------------------------------------- |
+| 🧠 **Smart Extraction**   | Mozilla Readability removes ads, navigation, and boilerplate  |
+| 📄 **Multiple Formats**   | JSONL semantic blocks or clean Markdown with YAML frontmatter |
+| 🔗 **Link Discovery**     | Extract and classify internal/external links                  |
+| ⚡ **Built-in Caching**   | Configurable TTL and max entries                              |
+| 🛡️ **Security First**     | SSRF protection, URL validation, header sanitization          |
+| 🔄 **Resilient Fetching** | Exponential backoff with jitter                               |
+| 📊 **Monitoring**         | Stats resource for cache performance and health               |
+
+---
+
+## Quick Start
+
+Add superFetch to your MCP client configuration — no installation required!
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "superFetch": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "superFetch": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"]
+    }
+  }
+}
+```
+
+### With Environment Variables
+
+```json
+{
+  "servers": {
+    "superFetch": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/superfetch@latest", "--stdio"],
+      "env": {
+        "CACHE_TTL": "7200",
+        "LOG_LEVEL": "debug"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Installation (Alternative)
+
+### Global Installation
+
+```bash
+npm install -g @j0hanz/superfetch
+
+# Run in stdio mode
+superfetch --stdio
+
+# Run HTTP server
+superfetch
+```
+
+### From Source
+
+```bash
+git clone https://github.com/j0hanz/super-fetch-mcp-server.git
+cd super-fetch-mcp-server
+npm install
+npm run build
+```
+
+### Running the Server
+
+<details>
+<summary><strong>HTTP Mode</strong> (default)</summary>
+
+```bash
+# Development with hot reload
+npm run dev
+
+# Production
+npm start
+```
+
+Server runs at `http://127.0.0.1:3000`:
+
+- Health check: `GET /health`
+- MCP endpoint: `POST /mcp`
+
+</details>
+
+<details>
+<summary><strong>stdio Mode</strong> (direct MCP integration)</summary>
+
+```bash
+node dist/index.js --stdio
+```
+
+</details>
+
+---
+
+## Available Tools
+
+### `fetch-url`
+
+Fetches a webpage and converts it to AI-readable format.
+
+| Parameter            | Type                      | Default    | Description                |
+| -------------------- | ------------------------- | ---------- | -------------------------- |
+| `url`                | string                    | _required_ | URL to fetch               |
+| `format`             | `'jsonl'` \| `'markdown'` | `'jsonl'`  | Output format              |
+| `extractMainContent` | boolean                   | `true`     | Use Readability extraction |
+| `includeMetadata`    | boolean                   | `true`     | Include page metadata      |
+| `maxContentLength`   | number                    | –          | Max content length (chars) |
+| `customHeaders`      | object                    | –          | Custom HTTP headers        |
+
+### `fetch-links`
+
+Extracts hyperlinks from a webpage with classification.
+
+| Parameter         | Type    | Default    | Description               |
+| ----------------- | ------- | ---------- | ------------------------- |
+| `url`             | string  | _required_ | URL to extract links from |
+| `includeExternal` | boolean | `true`     | Include external links    |
+| `includeInternal` | boolean | `true`     | Include internal links    |
+
+### `fetch-markdown`
+
+Fetches a webpage and converts it to clean Markdown.
+
+| Parameter            | Type    | Default    | Description               |
+| -------------------- | ------- | ---------- | ------------------------- |
+| `url`                | string  | _required_ | URL to fetch              |
+| `extractMainContent` | boolean | `true`     | Extract main content only |
+| `includeMetadata`    | boolean | `true`     | Include YAML frontmatter  |
+
+### Resources
+
+| URI                  | Description                         |
+| -------------------- | ----------------------------------- |
+| `superfetch://stats` | Server statistics and cache metrics |
+
+### Prompts
+
+- **`analyze-web-content`** — Analyze fetched content with optional focus area
+- **`summarize-page`** — Fetch and summarize a webpage concisely
+- **`extract-data`** — Extract structured data from a webpage
+
+---
+
+## Configuration
+
+### Alternative MCP Client Setups
+
+<details>
+<summary><strong>VS Code (HTTP mode)</strong> — requires running server separately</summary>
+
+First, start the HTTP server:
+
+```bash
+npx -y @j0hanz/superfetch@latest
+```
+
+Then add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "superFetch": {
+      "type": "http",
+      "url": "http://127.0.0.1:3000/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop (local path)</strong> — for development</summary>
+
+```json
+{
+  "mcpServers": {
+    "superFetch": {
+      "command": "node",
+      "args": ["/path/to/super-fetch-mcp-server/dist/index.js", "--stdio"]
+    }
+  }
+}
+```
+
+</details>
+
+### Environment Variables
+
+| Variable             | Default              | Description               |
+| -------------------- | -------------------- | ------------------------- |
+| `PORT`               | `3000`               | HTTP server port          |
+| `HOST`               | `127.0.0.1`          | HTTP server host          |
+| `FETCH_TIMEOUT`      | `30000`              | Request timeout (ms)      |
+| `MAX_REDIRECTS`      | `5`                  | Maximum HTTP redirects    |
+| `USER_AGENT`         | `superFetch-MCP/1.0` | HTTP User-Agent           |
+| `MAX_CONTENT_LENGTH` | `10485760`           | Max response size (bytes) |
+| `CACHE_ENABLED`      | `true`               | Enable response caching   |
+| `CACHE_TTL`          | `3600`               | Cache TTL (seconds)       |
+| `CACHE_MAX_KEYS`     | `100`                | Maximum cache entries     |
+| `LOG_LEVEL`          | `info`               | Logging level             |
+
+---
+
+## Content Block Types
+
+JSONL output includes semantic content blocks:
+
+| Type        | Description                                     |
+| ----------- | ----------------------------------------------- |
+| `metadata`  | Page title, description, author, URL, timestamp |
+| `heading`   | Headings (h1-h6) with level indicator           |
+| `paragraph` | Text paragraphs                                 |
+| `list`      | Ordered/unordered lists                         |
+| `code`      | Code blocks with language                       |
+| `table`     | Tables with headers and rows                    |
+| `image`     | Images with src and alt text                    |
+
+---
+
+## Security
+
+### SSRF Protection
+
+Blocked destinations:
+
+- Localhost and loopback addresses
+- Private IP ranges (`10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`)
+- Cloud metadata endpoints (AWS, GCP, Azure)
+- IPv6 link-local and unique local addresses
+
+### Header Sanitization
+
+Blocked headers: `host`, `authorization`, `cookie`, `x-forwarded-for`, `x-real-ip`, `proxy-authorization`
+
+### Rate Limiting
+
+Default: **100 requests/minute** per IP (configurable)
+
+---
+
+## Development
+
+### Scripts
+
+| Command              | Description                        |
+| -------------------- | ---------------------------------- |
+| `npm run dev`        | Development server with hot reload |
+| `npm run build`      | Compile TypeScript                 |
+| `npm start`          | Production server                  |
+| `npm run lint`       | Run ESLint                         |
+| `npm run type-check` | TypeScript type checking           |
+| `npm run format`     | Format with Prettier               |
+| `npm test`           | Run tests                          |
+
+### Tech Stack
+
+| Category           | Technology                      |
+| ------------------ | ------------------------------- |
+| Runtime            | Node.js ≥18                     |
+| Language           | TypeScript 5.9                  |
+| MCP SDK            | @modelcontextprotocol/sdk 1.0.4 |
+| Content Extraction | @mozilla/readability            |
+| HTML Parsing       | Cheerio, JSDOM                  |
+| Markdown           | Turndown                        |
+| HTTP               | Express, Axios                  |
+| Caching            | node-cache                      |
+| Validation         | Zod                             |
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Ensure linting passes: `npm run lint`
+4. Commit changes: `git commit -m 'Add amazing feature'`
+5. Push: `git push origin feature/amazing-feature`
+6. Open a Pull Request
+
+For examples of other MCP servers, see: [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/dist/config/index.d.ts

@@ -0,0 +1,30 @@
+export declare const config: {
+    readonly server: {
+        readonly name: "superFetch";
+        readonly version: "1.0.0";
+        readonly port: number;
+        readonly host: string;
+    };
+    readonly fetcher: {
+        readonly timeout: number;
+        readonly maxRedirects: number;
+        readonly userAgent: string;
+        readonly maxContentLength: number;
+    };
+    readonly cache: {
+        readonly enabled: boolean;
+        readonly ttl: number;
+        readonly maxKeys: number;
+    };
+    readonly extraction: {
+        readonly extractMainContent: boolean;
+        readonly includeMetadata: boolean;
+        readonly maxBlockLength: number;
+        readonly minParagraphLength: number;
+    };
+    readonly logging: {
+        readonly level: string;
+        readonly enabled: boolean;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCT,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,42 @@
+/**
+ * Safely parses an integer from environment variable with validation
+ * Environment variables can still be used for deployment overrides (e.g., PORT=8080 npm start)
+ */
+function parseIntEnv(value, defaultValue, min = 0, max = Number.MAX_SAFE_INTEGER) {
+    if (!value)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed))
+        return defaultValue;
+    return Math.max(min, Math.min(max, parsed));
+}
+export const config = {
+    server: {
+        name: 'superFetch',
+        version: '1.0.0',
+        port: parseIntEnv(process.env.PORT, 3000, 1, 65535),
+        host: process.env.HOST || '127.0.0.1',
+    },
+    fetcher: {
+        timeout: parseIntEnv(process.env.FETCH_TIMEOUT, 30000, 1000, 120000), // 1s-120s
+        maxRedirects: parseIntEnv(process.env.MAX_REDIRECTS, 5, 0, 20),
+        userAgent: process.env.USER_AGENT || 'superFetch-MCP/1.0',
+        maxContentLength: parseIntEnv(process.env.MAX_CONTENT_LENGTH, 10485760, 1024, 52428800), // 1KB-50MB
+    },
+    cache: {
+        enabled: process.env.CACHE_ENABLED !== 'false',
+        ttl: parseIntEnv(process.env.CACHE_TTL, 3600, 60, 86400), // 1min-24hr
+        maxKeys: parseIntEnv(process.env.CACHE_MAX_KEYS, 100, 10, 10000),
+    },
+    extraction: {
+        extractMainContent: process.env.EXTRACT_MAIN_CONTENT !== 'false',
+        includeMetadata: process.env.INCLUDE_METADATA !== 'false',
+        maxBlockLength: parseIntEnv(process.env.MAX_BLOCK_LENGTH, 5000, 100, 50000),
+        minParagraphLength: parseIntEnv(process.env.MIN_PARAGRAPH_LENGTH, 10, 0, 1000),
+    },
+    logging: {
+        level: process.env.LOG_LEVEL || 'info',
+        enabled: process.env.ENABLE_LOGGING !== 'false',
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,SAAS,WAAW,CAClB,KAAyB,EACzB,YAAoB,EACpB,GAAG,GAAG,CAAC,EACP,GAAG,GAAG,MAAM,CAAC,gBAAgB;IAE7B,IAAI,CAAC,KAAK;QAAE,OAAO,YAAY,CAAC;IAChC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,YAAY,CAAC;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,MAAM,EAAE;QACN,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC;QACnD,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,WAAW;KACtC;IACD,OAAO,EAAE;QACP,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,UAAU;QAChF,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9D,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,oBAAoB;QACzD,gBAAgB,EAAE,WAAW,CAC3B,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAC9B,QAAQ,EACR,IAAI,EACJ,QAAQ,CACT,EAAE,WAAW;KACf;IACD,KAAK,EAAE;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,OAAO;QAC9C,GAAG,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,YAAY;QACtE,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,CAAC;KACjE;IACD,UAAU,EAAE;QACV,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,OAAO;QAChE,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,OAAO;QACzD,cAAc,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;QAC3E,kBAAkB,EAAE,WAAW,CAC7B,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAChC,EAAE,EACF,CAAC,EACD,IAAI,CACL;KACF;IACD,OAAO,EAAE;QACP,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;QACtC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,OAAO;KAChD;CACO,CAAC"}

package/dist/errors/app-error.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Base application error class with status code support
+ */
+export declare class AppError extends Error {
+    readonly statusCode: number;
+    readonly isOperational: boolean;
+    readonly code: string;
+    constructor(message: string, statusCode?: number, code?: string, isOperational?: boolean);
+}
+/**
+ * Not found error (404)
+ */
+export declare class NotFoundError extends AppError {
+    constructor(resource: string);
+}
+/**
+ * Validation error (400)
+ */
+export declare class ValidationError extends AppError {
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * URL validation error (400)
+ */
+export declare class UrlValidationError extends AppError {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+/**
+ * Fetch error - network/HTTP errors during URL fetching
+ */
+export declare class FetchError extends AppError {
+    readonly url: string;
+    readonly httpStatus?: number;
+    constructor(message: string, url: string, httpStatus?: number);
+}
+/**
+ * Content extraction error
+ */
+export declare class ExtractionError extends AppError {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+/**
+ * Unauthorized error (401)
+ */
+export declare class UnauthorizedError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * Forbidden error (403)
+ */
+export declare class ForbiddenError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * Rate limit error (429)
+ */
+export declare class RateLimitError extends AppError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number);
+}
+/**
+ * Timeout error (408/504)
+ */
+export declare class TimeoutError extends AppError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, isGateway?: boolean);
+}
+//# sourceMappingURL=app-error.d.ts.map

package/dist/errors/app-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.d.ts","sourceRoot":"","sources":["../../src/errors/app-error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,aAAa,EAAE,OAAO,CAAC;IACvC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,UAAU,SAAM,EAChB,IAAI,SAAmB,EACvB,aAAa,UAAO;CASvB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,QAAQ,EAAE,MAAM;CAG7B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAI/D;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,SAAgB,GAAG,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAIzC;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACtC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAK9D;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,SAAgB,GAAG,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAIzC;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAAiB;CAGrC;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAAc;CAGlC;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,UAAU,EAAE,MAAM;CAI/B;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IACxC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,SAAS,EAAE,MAAM,EAAE,SAAS,UAAQ;CAQjD"}

package/dist/errors/app-error.js

@@ -0,0 +1,103 @@
+/**
+ * Base application error class with status code support
+ */
+export class AppError extends Error {
+    statusCode;
+    isOperational;
+    code;
+    constructor(message, statusCode = 500, code = 'INTERNAL_ERROR', isOperational = true) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.isOperational = isOperational;
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * Not found error (404)
+ */
+export class NotFoundError extends AppError {
+    constructor(resource) {
+        super(`${resource} not found`, 404, 'NOT_FOUND');
+    }
+}
+/**
+ * Validation error (400)
+ */
+export class ValidationError extends AppError {
+    details;
+    constructor(message, details) {
+        super(message, 400, 'VALIDATION_ERROR');
+        this.details = details;
+    }
+}
+/**
+ * URL validation error (400)
+ */
+export class UrlValidationError extends AppError {
+    url;
+    constructor(message, url) {
+        super(message, 400, 'INVALID_URL');
+        this.url = url;
+    }
+}
+/**
+ * Fetch error - network/HTTP errors during URL fetching
+ */
+export class FetchError extends AppError {
+    url;
+    httpStatus;
+    constructor(message, url, httpStatus) {
+        super(message, httpStatus ?? 502, 'FETCH_ERROR');
+        this.url = url;
+        this.httpStatus = httpStatus;
+    }
+}
+/**
+ * Content extraction error
+ */
+export class ExtractionError extends AppError {
+    url;
+    constructor(message, url) {
+        super(message, 422, 'EXTRACTION_ERROR');
+        this.url = url;
+    }
+}
+/**
+ * Unauthorized error (401)
+ */
+export class UnauthorizedError extends AppError {
+    constructor(message = 'Unauthorized') {
+        super(message, 401, 'UNAUTHORIZED');
+    }
+}
+/**
+ * Forbidden error (403)
+ */
+export class ForbiddenError extends AppError {
+    constructor(message = 'Forbidden') {
+        super(message, 403, 'FORBIDDEN');
+    }
+}
+/**
+ * Rate limit error (429)
+ */
+export class RateLimitError extends AppError {
+    retryAfter;
+    constructor(retryAfter) {
+        super('Too many requests', 429, 'RATE_LIMITED');
+        this.retryAfter = retryAfter;
+    }
+}
+/**
+ * Timeout error (408/504)
+ */
+export class TimeoutError extends AppError {
+    timeoutMs;
+    constructor(timeoutMs, isGateway = false) {
+        super(`Request timeout after ${timeoutMs}ms`, isGateway ? 504 : 408, 'TIMEOUT');
+        this.timeoutMs = timeoutMs;
+    }
+}
+//# sourceMappingURL=app-error.js.map

package/dist/errors/app-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.js","sourceRoot":"","sources":["../../src/errors/app-error.ts"],"names":[],"mappings":"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"}

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from './app-error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,2 @@
+export * from './app-error.js';
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}