🎩 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.