imperium-crawl 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ceoimperiumprojects
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# imperium-crawl
+
+The most powerful open-source MCP server for web scraping, crawling, and data extraction. **16 tools. Zero API keys required for scraping. One `npx` command to install.**
+
+While others charge $19+/month for basic scraping, imperium-crawl gives you **more features for free** — including capabilities that no other MCP server offers at any price.
+
+## vs. The Competition
+
+| Feature | **imperium-crawl** | Firecrawl MCP | fetch MCP | Crawl4AI MCP | Browserbase MCP |
+|---------|:------------------:|:-------------:|:---------:|:------------:|:---------------:|
+| Price | **Free forever** | $19+/month | Free | Free | $0.01/min |
+| Scraping tools | **6** | 3 | 1 | 1 | 1 |
+| Search tools | **4** | 0 | 0 | 0 | 0 |
+| Stealth levels | **3 (auto-escalate)** | Cloud-based | None | 1 | Cloud-based |
+| Anti-bot detection | **7 systems** | Partial | None | Partial | Partial |
+| TLS fingerprinting | **Yes (JA3/JA4)** | No | No | No | No |
+| CAPTCHA auto-solving | **Yes (2Captcha)** | No | No | No | No |
+| API discovery from network traffic | **Yes** | No | No | No | No |
+| WebSocket monitoring | **Yes** | No | No | No | No |
+| Direct API calls | **Yes** | No | No | No | No |
+| Reusable skills system | **Yes** | No | No | No | No |
+| Structured data extraction (JSON-LD/OG) | **Yes** | Partial | No | No | No |
+| Priority-based crawling | **Yes** | No | No | No | No |
+| Circuit breaker + jitter backoff | **Yes** | No | No | No | No |
+| URL normalization (11 steps) | **Yes** | No | No | No | No |
+| Self-hosted | **Yes** | No | N/A | Yes | No |
+| Requires external service | **No** | Yes | No | No | Yes |
+| Total tools | **16** | 5 | 2 | 2 | 4 |
+
+> **TLDR:** More tools, more features, zero cost, no external dependencies. Self-hosted, open-source, and it runs on your machine.
+
+## Installation
+
+Add to your MCP client config (Claude Code, Cursor, VS Code, Windsurf, or any MCP client):
+
+```json
+{
+  "mcpServers": {
+    "imperium-crawl": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "imperium-crawl"],
+      "env": {
+        "BRAVE_API_KEY": "your-brave-api-key"
+      }
+    }
+  }
+}
+```
+
+> **API keys are optional.** Without `BRAVE_API_KEY`, only the 4 search tools are disabled. All 12 other tools work out of the box.
+
+### Enable full stealth (Level 3 — headless browser)
+
+```bash
+npm i rebrowser-playwright
+npx playwright install chromium
+```
+
+### Enable CAPTCHA auto-solving
+
+```bash
+# Add to your MCP config env:
+"TWOCAPTCHA_API_KEY": "your-2captcha-api-key"
+```
+
+Supports reCAPTCHA v2/v3, hCaptcha, and Cloudflare Turnstile. Auto-detects CAPTCHA type and solves transparently.
+
+---
+
+## 16 Tools
+
+### Scraping (no API key needed)
+
+| Tool | What It Does |
+|------|-------------|
+| **scrape** | URL to clean Markdown/HTML with 3-level auto-escalating stealth. Returns structured data (JSON-LD, OpenGraph, Microdata), metadata, and links on request. |
+| **crawl** | Priority-based crawling with depth control, concurrency limiting, and smart URL scoring. Content paths rank higher, tracking params are stripped. |
+| **map** | Discover all URLs on a domain via sitemap.xml parsing + page link extraction. |
+| **extract** | CSS selectors to structured JSON. Point at any repeating pattern and get clean data. |
+| **readability** | Mozilla Readability article extraction — title, author, content, publish date. 3x faster with linkedom. |
+| **screenshot** | Full-page or viewport PNG screenshots via headless Chromium. |
+
+### Search (requires free Brave API key)
+
+| Tool | What It Does |
+|------|-------------|
+| **search** | Web search via Brave Search API. |
+| **news_search** | News-specific search with freshness ranking. |
+| **image_search** | Image search with thumbnails and source URLs. |
+| **video_search** | Video search across platforms. |
+
+### Skills (no API key needed)
+
+| Tool | What It Does |
+|------|-------------|
+| **create_skill** | Analyze any page, auto-detect repeating patterns (articles, products, listings), generate CSS selectors, and save as a reusable skill. |
+| **run_skill** | Run a saved skill to get fresh structured data instantly. Supports pagination. |
+| **list_skills** | List all saved skills with their configurations. |
+
+### API Discovery & Real-Time (no API key needed, requires Playwright)
+
+| Tool | What It Does |
+|------|-------------|
+| **discover_apis** | Navigate to any page, intercept all XHR/fetch calls, and map every hidden REST/GraphQL API endpoint. Auto-detects GraphQL, filters noise, returns response previews. **No other MCP server does this.** |
+| **query_api** | Call any API endpoint directly with stealth headers. Bypass DOM rendering entirely for 10x faster data access. Use after `discover_apis` to hit endpoints directly. |
+| **monitor_websocket** | Capture real-time WebSocket messages from any page — financial tickers, chat feeds, live dashboards. Returns connection details and message payloads. **No other MCP server does this.** |
+
+---
+
+## Stealth Engine
+
+imperium-crawl uses a 3-level stealth system that **auto-escalates** based on the target site's defenses:
+
+| Level | Method | What It Defeats |
+|-------|--------|-----------------|
+| **1** | `header-generator` — Bayesian realistic headers + UA rotation | Basic bot detection, simple WAFs |
+| **2** | `impit` — browser-identical TLS fingerprints (JA3/JA4) | Cloudflare, Akamai, TLS fingerprinting WAFs |
+| **3** | `rebrowser-playwright` + `fingerprint-injector` + auto CAPTCHA solving | JavaScript challenges, SPAs, advanced anti-bot, CAPTCHAs |
+
+### Anti-Bot System Detection
+
+Automatically identifies which anti-bot system a site uses and chooses the optimal strategy:
+
+| System | Detection Method |
+|--------|-----------------|
+| **Cloudflare** | `cf_clearance` cookies, `cf-mitigated` header, challenge page title |
+| **Akamai** | `_abck`, `bm_sz` cookies |
+| **PerimeterX / HUMAN** | `_px` cookies, `_pxhd` headers |
+| **DataDome** | `datadome` cookies, `datadome` response header |
+| **Kasada** | `x-kpsdk-*` headers |
+| **AWS WAF** | `aws-waf-token` cookie |
+| **F5 / Shape Security** | `TS` prefix cookies |
+
+### Smart Rendering Cache
+
+Once imperium-crawl determines a domain needs Level 3 (browser), it **caches that decision** for 1 hour. Subsequent requests to the same domain skip straight to browser rendering — no wasted time on failed lower levels.
+
+---
+
+## Skills System
+
+Skills let you teach imperium-crawl how to extract data from any website, then re-run it for fresh content whenever you want.
+
+**Create a skill:**
+```
+create_skill({
+  url: "https://techcrunch.com/category/artificial-intelligence",
+  name: "tc-ai-news",
+  description: "Latest AI news from TechCrunch"
+})
+```
+
+The tool analyzes the page, auto-detects repeating elements (articles, products, listings), generates CSS selectors for each field, and saves the skill config.
+
+**Run a skill:**
+```
+run_skill({ name: "tc-ai-news" })
+```
+
+Returns fresh structured data with all detected fields. Skills are saved in `~/.imperium-crawl/skills/` as JSON files — human-readable, editable, and portable.
+
+---
+
+## API Discovery Workflow
+
+This is the workflow that no other MCP server supports:
+
+```
+1. discover_apis({ url: "https://github.com/anthropics" })
+   → Finds 5 hidden JSON API endpoints (refs, tree-commit-info, overview-files...)
+
+2. query_api({ url: "https://github.com/.../refs", method: "GET" })
+   → Direct API call, bypasses DOM entirely — 10x faster, structured JSON response
+
+3. monitor_websocket({ url: "https://binance.com/en/trade/BTC_USDT", duration_seconds: 10 })
+   → Captures 38 real-time WebSocket messages from 3 connections
+```
+
+Turn any website into an API. No documentation needed.
+
+---
+
+## Resilience
+
+- **Exponential backoff with full jitter** — AWS-recommended retry pattern, no thundering herd
+- **Per-domain circuit breaker** — 5 consecutive failures opens the circuit for 60s, then half-open probing
+- **URL normalization** — 11-step pipeline removes tracking params (utm_*, fbclid, gclid), sorts query params, normalizes encoding
+- **Concurrency limiting** — per-domain request throttling via p-queue
+- **robots.txt** — respected by default (configurable)
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BRAVE_API_KEY` | No | Brave Search API key (enables 4 search tools) |
+| `TWOCAPTCHA_API_KEY` | No | 2Captcha API key (enables auto CAPTCHA solving) |
+| `TRANSPORT` | No | `stdio` (default) or `http` |
+| `PORT` | No | HTTP port (default: 3000) |
+| `RESPECT_ROBOTS` | No | Respect robots.txt (default: `true`) |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/AiExperts/imperium-crawl
+cd imperium-crawl
+npm install
+npm run build
+npm test        # 120 tests
+npm start
+```
+
+---
+
+## License
+
+MIT — use it however you want. Free forever.

package/dist/brave-api/index.d.ts

@@ -0,0 +1,6 @@
+export declare class BraveApiError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export declare function issueRequest(apiKey: string, endpoint: string, params: Record<string, string | number | undefined>): Promise<unknown>;
+//# sourceMappingURL=index.d.ts.map

package/dist/brave-api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/brave-api/index.ts"],"names":[],"mappings":"AAEA,qBAAa,aAAc,SAAQ,KAAK;IAE7B,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAClD,OAAO,CAAC,OAAO,CAAC,CAuBlB"}

package/dist/brave-api/index.js

@@ -0,0 +1,31 @@
+import { BRAVE_API_BASE } from "../constants.js";
+export class BraveApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "BraveApiError";
+    }
+}
+export async function issueRequest(apiKey, endpoint, params) {
+    const url = new URL(`${BRAVE_API_BASE}${endpoint}`);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    const res = await fetch(url.toString(), {
+        headers: {
+            Accept: "application/json",
+            "Accept-Encoding": "gzip",
+            "X-Subscription-Token": apiKey,
+        },
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "Unknown error");
+        throw new BraveApiError(res.status, `Brave API ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+//# sourceMappingURL=index.js.map

package/dist/brave-api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/brave-api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,OAAO,aAAc,SAAQ,KAAK;IAE7B;IADT,YACS,MAAc,EACrB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,WAAM,GAAN,MAAM,CAAQ;QAIrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,QAAgB,EAChB,MAAmD;IAEnD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,cAAc,GAAG,QAAQ,EAAE,CAAC,CAAC;IACpD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE;QACtC,OAAO,EAAE;YACP,MAAM,EAAE,kBAAkB;YAC1B,iBAAiB,EAAE,MAAM;YACzB,sBAAsB,EAAE,MAAM;SAC/B;QACD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;KACpC,CAAC,CAAC;IAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;QAC3D,MAAM,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC"}

package/dist/captcha/detector.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CAPTCHA type detection from HTML.
+ * Identifies reCAPTCHA v2/v3, hCaptcha, and Cloudflare Turnstile,
+ * and extracts the sitekey needed for solving.
+ */
+export type CaptchaType = "recaptcha_v2" | "recaptcha_v3" | "hcaptcha" | "turnstile";
+export interface CaptchaInfo {
+    type: CaptchaType;
+    sitekey: string;
+    action?: string;
+    enterprise?: boolean;
+    s?: string;
+}
+/**
+ * Detect CAPTCHA type and extract sitekey from HTML.
+ * Checks in order: Turnstile (most specific) → hCaptcha → reCAPTCHA.
+ * Returns null if no CAPTCHA detected.
+ */
+export declare function detectCaptcha(html: string): CaptchaInfo | null;
+/**
+ * Quick check if HTML contains any CAPTCHA indicators.
+ * Faster than full detection — use as pre-filter.
+ */
+export declare function hasCaptcha(html: string): boolean;
+//# sourceMappingURL=detector.d.ts.map

package/dist/captcha/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../src/captcha/detector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAErF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAyHD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAc9D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAShD"}

package/dist/captcha/detector.js

@@ -0,0 +1,137 @@
+/**
+ * CAPTCHA type detection from HTML.
+ * Identifies reCAPTCHA v2/v3, hCaptcha, and Cloudflare Turnstile,
+ * and extracts the sitekey needed for solving.
+ */
+// ── reCAPTCHA Detection ──
+const RECAPTCHA_SITEKEY_PATTERNS = [
+    /data-sitekey=["']([A-Za-z0-9_-]{40})["']/,
+    /grecaptcha\.render\s*\([^,]*,\s*\{\s*['"]?sitekey['"]?\s*:\s*['"]([A-Za-z0-9_-]{40})["']/,
+    /['"]sitekey['"]\s*:\s*['"]([A-Za-z0-9_-]{40})["']/,
+    /recaptcha\/api2?\/anchor\?.*?k=([A-Za-z0-9_-]{40})/,
+    /recaptcha\/enterprise\/anchor\?.*?k=([A-Za-z0-9_-]{40})/,
+];
+const RECAPTCHA_V3_INDICATORS = [
+    "grecaptcha.execute",
+    "recaptcha/api.js?render=",
+    "recaptcha/enterprise.js?render=",
+    "recaptcha-v3",
+    '"size":"invisible"',
+];
+const RECAPTCHA_ENTERPRISE_INDICATORS = [
+    "recaptcha/enterprise",
+    "grecaptcha.enterprise",
+];
+function detectRecaptcha(html) {
+    // Try to find sitekey
+    let sitekey = null;
+    for (const pattern of RECAPTCHA_SITEKEY_PATTERNS) {
+        const match = html.match(pattern);
+        if (match) {
+            sitekey = match[1];
+            break;
+        }
+    }
+    if (!sitekey) {
+        // Check for general reCAPTCHA presence without sitekey
+        if (!html.includes("g-recaptcha") && !html.includes("grecaptcha") && !html.includes("recaptcha/api")) {
+            return null;
+        }
+        // Try render param as sitekey
+        const renderMatch = html.match(/recaptcha\/(?:enterprise\/)?api\.js\?.*?render=([A-Za-z0-9_-]{40})/);
+        if (renderMatch) {
+            sitekey = renderMatch[1];
+        }
+        else {
+            return null;
+        }
+    }
+    const isEnterprise = RECAPTCHA_ENTERPRISE_INDICATORS.some((i) => html.includes(i));
+    const isV3 = RECAPTCHA_V3_INDICATORS.some((i) => html.includes(i));
+    // Try to extract action for v3
+    let action;
+    if (isV3) {
+        const actionMatch = html.match(/grecaptcha\.(?:enterprise\.)?execute\s*\(\s*['"][^'"]*['"]\s*,\s*\{\s*action\s*:\s*['"]([^'"]+)['"]/);
+        action = actionMatch?.[1] || "verify";
+    }
+    // Extract data-s if present (invisible reCAPTCHA)
+    const sMatch = html.match(/data-s=["']([^"']+)["']/);
+    return {
+        type: isV3 ? "recaptcha_v3" : "recaptcha_v2",
+        sitekey,
+        action,
+        enterprise: isEnterprise || undefined,
+        s: sMatch?.[1],
+    };
+}
+// ── hCaptcha Detection ──
+const HCAPTCHA_SITEKEY_PATTERNS = [
+    /data-sitekey=["']([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})["']/,
+    /hcaptcha\.render\s*\([^,]*,\s*\{[^}]*sitekey['"]\s*:\s*['"]([0-9a-f-]{36})["']/,
+    /['"]sitekey['"]\s*:\s*['"]([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})["']/,
+];
+function detectHcaptcha(html) {
+    // Must have hCaptcha indicators
+    if (!html.includes("h-captcha") && !html.includes("hcaptcha") && !html.includes("hcaptcha.com")) {
+        return null;
+    }
+    for (const pattern of HCAPTCHA_SITEKEY_PATTERNS) {
+        const match = html.match(pattern);
+        if (match) {
+            return { type: "hcaptcha", sitekey: match[1] };
+        }
+    }
+    return null;
+}
+// ── Cloudflare Turnstile Detection ──
+const TURNSTILE_SITEKEY_PATTERNS = [
+    /class=["'][^"']*cf-turnstile[^"']*["'][^>]*data-sitekey=["']([A-Za-z0-9_-]+)["']/,
+    /data-sitekey=["']([A-Za-z0-9_-]+)["'][^>]*class=["'][^"']*cf-turnstile/,
+    /turnstile\.render\s*\([^,]*,\s*\{[^}]*sitekey['"]\s*:\s*['"]([A-Za-z0-9_-]+)["']/,
+];
+function detectTurnstile(html) {
+    if (!html.includes("cf-turnstile") && !html.includes("challenges.cloudflare.com/turnstile")) {
+        return null;
+    }
+    for (const pattern of TURNSTILE_SITEKEY_PATTERNS) {
+        const match = html.match(pattern);
+        if (match) {
+            return { type: "turnstile", sitekey: match[1] };
+        }
+    }
+    return null;
+}
+// ── Main Detector ──
+/**
+ * Detect CAPTCHA type and extract sitekey from HTML.
+ * Checks in order: Turnstile (most specific) → hCaptcha → reCAPTCHA.
+ * Returns null if no CAPTCHA detected.
+ */
+export function detectCaptcha(html) {
+    // Turnstile first (Cloudflare-specific, most precise match)
+    const turnstile = detectTurnstile(html);
+    if (turnstile)
+        return turnstile;
+    // hCaptcha (UUID sitekey is very specific)
+    const hcaptcha = detectHcaptcha(html);
+    if (hcaptcha)
+        return hcaptcha;
+    // reCAPTCHA (most common, check last)
+    const recaptcha = detectRecaptcha(html);
+    if (recaptcha)
+        return recaptcha;
+    return null;
+}
+/**
+ * Quick check if HTML contains any CAPTCHA indicators.
+ * Faster than full detection — use as pre-filter.
+ */
+export function hasCaptcha(html) {
+    return (html.includes("g-recaptcha") ||
+        html.includes("grecaptcha") ||
+        html.includes("h-captcha") ||
+        html.includes("hcaptcha") ||
+        html.includes("cf-turnstile") ||
+        html.includes("challenges.cloudflare.com/turnstile"));
+}
+//# sourceMappingURL=detector.js.map

package/dist/captcha/detector.js.map

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

package/dist/captcha/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CAPTCHA orchestrator: detect → solve via 2Captcha → inject into Playwright page.
+ *
+ * This is the high-level module that ties detection, solving, and injection together.
+ * Used by the stealth engine's browser-level fetch to auto-solve CAPTCHAs.
+ */
+export { detectCaptcha, hasCaptcha, type CaptchaInfo } from "./detector.js";
+export { TwoCaptchaSolver, CaptchaSolverError, type SolveResult } from "./solver.js";
+type PlaywrightPage = any;
+export interface CaptchaSolveAttempt {
+    detected: boolean;
+    solved: boolean;
+    captchaType?: string;
+    solveTimeMs?: number;
+    error?: string;
+}
+/**
+ * Attempt to detect and solve a CAPTCHA on a Playwright page.
+ *
+ * Flow:
+ * 1. Get page HTML
+ * 2. Detect CAPTCHA type + sitekey
+ * 3. Submit to 2Captcha
+ * 4. Poll for solution
+ * 5. Inject token into page
+ * 6. Wait for page to process the token
+ *
+ * Returns details about the attempt. Non-throwing — errors are captured in result.
+ */
+export declare function trySolveCaptcha(page: PlaywrightPage, apiKey: string): Promise<CaptchaSolveAttempt>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/captcha/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAIrF,KAAK,cAAc,GAAG,GAAG,CAAC;AAE1B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC,CA0E9B"}