🎩 hatbreak

Anti-detect web fetch engine. Any URL → clean Markdown, escalating from a fast HTTP request to a real stealth browser through residential proxies — with an optional CAPTCHA solver.

hatbreak is the engine that powers HatFetch. Give it a URL; it returns the page as clean, LLM-ready Markdown — and it only spends effort when a page needs it:

1. HTTP — fast fetch → main-content extraction → Markdown. Handles the server-rendered web with no browser.
2. Stealth browser — if the page is an empty JavaScript app, or gets blocked, it escalates to a real Patchright Chromium (patched to beat headless fingerprinting) running through residential proxies, with human-like behavior.
3. CAPTCHA solver (optional) — if an interactive Turnstile / reCAPTCHA / hCaptcha still appears, and you've configured a solver key, it solves and injects the token.

[!TIP] Recommended proxies — ProxyHat residential IPs. Every feature in this package is tested end-to-end against ProxyHat and works great. First-class integration; also works with any proxy, or none.

Install

npm install hatbreak

Quick start

import { Unblock } from "hatbreak";

const ub = new Unblock(); // reads PROXYHAT_API_KEY / CAPTCHA_API_KEY from env

const page = await ub.fetch("https://example.com");
console.log(page.markdown); // clean Markdown
console.log(page.via);      // "direct connection" | "ProxyHat residential + browser (auto: SPA)" | ...

const png = await ub.screenshot("https://example.com");
await ub.close();

Function API (no class):

import { retrieve } from "hatbreak";
const page = await retrieve("https://example.com", { render: "auto" });

What it does (honestly)

| Target | Result | |---|---| | Server-rendered sites (news, docs, forums, catalogs) | ✅ Fast HTTP path | | JavaScript / SPA sites | ✅ Auto-escalates to the browser and renders | | Geo-restricted content | ✅ Exit from 148+ countries (residential) | | Datacenter-IP blocks / IP rate limits | ✅ Rotating residential IPs | | Common Cloudflare / anti-bot | ✅ Browser + residential fingerprint + behavior | | Interactive CAPTCHAs (Turnstile / reCAPTCHA / hCaptcha) | ✅ With a solver key (CAPTCHA_API_KEY) | | The very hardest anti-bot (aggressive DataDome / PerimeterX) | ⚠️ Sometimes blocked — returns an honest error, never a CAPTCHA page as "content" |

No engine passes 100% of anti-bot in 2026. hatbreak gets you the calm-to-hard web reliably and is honest about the rest.

Configuration (environment variables)

| Variable | Description | |---|---| | PROXYHAT_API_KEY | ProxyHat API key — auto-selects a residential sub-user. Get one at proxyhat.com. | | PROXYHAT_USERNAME / PROXYHAT_PASSWORD | Explicit sub-user proxy credentials (alternative to the API key). | | PROXYHAT_COUNTRY / PROXYHAT_REGION / PROXYHAT_CITY | Geo targeting (default country any). | | PROXYHAT_STICKY | Keep one IP for a session, e.g. 30m. Omit for rotating. | | PROXYHAT_FILTER | AI IP-quality tier: medium (default), high, high-speed-fast. | | PROXY_URL | Any generic http://user:pass@host:port proxy instead of ProxyHat. | | CAPTCHA_API_KEY | Enables the CAPTCHA solver. | | CAPTCHA_PROVIDER | capsolver (default) or 2captcha. |

Proxy connection is built on the official proxyhat SDK.

fetch result

interface RetrieveResult {
  url: string;          // final URL after redirects
  title: string | null;
  markdown: string;     // clean, main-content Markdown
  links: string[];      // absolute links found
  via: string;          // how it was retrieved
  status: number;
  screenshot?: Buffer;  // when requested
}

Safety

• SSRF guard — refuses internal / loopback / cloud-metadata addresses (it's a tool you may hand to an autonomous agent).
• No silent block-pages — if a challenge/block page slips through, hatbreak throws UnblockError instead of returning it as content.

Roadmap

• Camoufox engine option for the hardest fingerprint checks
• Proxy-bound CAPTCHA solving
• search (query → results → fetch)

License

MIT © ProxyHat — residential & mobile proxies for the hard web.