human-browser 3.0.0

package/README.md

@@ -0,0 +1,218 @@
+# 🌍 Human Browser — Cloud Stealth Browser for AI Agents
+
+[![npm](https://img.shields.io/npm/v/%40al1enjesus%2Fhuman-browser?color=red&label=npm)](https://www.npmjs.com/package/@al1enjesus/human-browser)
+[![ClawHub](https://img.shields.io/badge/ClawHub-human--browser-orange)](https://clawhub.ai/al1enjesus/human-browser)
+[![skills.sh](https://img.shields.io/badge/skills.sh-listed-blue)](https://skills.sh/al1enjesus/human-browser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+> **No Mac Mini. No local machine. Your agent runs it anywhere.**  
+> Residential IPs from 10+ countries. Bypasses Cloudflare, DataDome, PerimeterX.
+
+🌐 **Product page + pricing:** [humanbrowser.dev](https://humanbrowser.dev)  
+💬 **Support:** [@virixlabs](https://t.me/virixlabs)
+
+---
+
+## Why your agent needs this
+
+Regular Playwright on a VPS gets blocked **immediately** by:
+
+- **Cloudflare** — bot score detection via data-center IP fingerprint
+- **DataDome** — fingerprint and behavioral analysis
+- **PerimeterX** — mouse movement and timing analysis
+- **Instagram, LinkedIn, TikTok** — residential IP requirement
+
+Human Browser solves this with:
+
+1. **Residential IP** — real ISP address from target country (not a data center)
+2. **Real device fingerprint** — iPhone 15 Pro or Windows Chrome, canvas + WebGL + fonts
+3. **Human-like behavior** — Bezier mouse curves, 60–220ms typing, natural scroll with jitter
+4. **Full anti-detection** — `webdriver=false`, no automation flags, correct timezone + geolocation
+
+---
+
+## Install
+
+```bash
+# OpenClaw agents (recommended)
+clawhub install al1enjesus/human-browser
+
+# skild.sh (multi-platform)
+skild install al1enjesus/human-browser
+
+# npm
+npm install @al1enjesus/human-browser
+```
+
+---
+
+## Quick Start
+
+```js
+const { launchHuman } = require('./scripts/browser-human');
+
+// Default: iPhone 15 Pro + Romania residential IP
+const { browser, page, humanType, humanClick, humanScroll, sleep } = await launchHuman();
+
+// Specific country
+const { page } = await launchHuman({ country: 'us' }); // US residential IP
+const { page } = await launchHuman({ country: 'gb' }); // UK residential IP
+const { page } = await launchHuman({ country: 'jp' }); // Japan
+
+// Desktop Chrome (Windows fingerprint)
+const { page } = await launchHuman({ mobile: false, country: 'us' });
+
+await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
+await humanScroll(page, 'down');
+await humanType(page, 'input[type="email"]', 'user@example.com');
+await humanClick(page, 760, 400);
+await browser.close();
+```
+
+---
+
+## Country → Service Compatibility
+
+| Country | ✅ Works great | ❌ Blocked |
+|---------|--------------|-----------|
+| 🇷🇴 Romania `ro` | Polymarket, Instagram, Binance, Cloudflare | US Banks, Netflix US |
+| 🇺🇸 United States `us` | Netflix, DoorDash, US Banks, Amazon US | Polymarket, Binance |
+| 🇬🇧 United Kingdom `gb` | Polymarket, Binance, BBC iPlayer | US-only apps |
+| 🇩🇪 Germany `de` | EU services, Binance, German e-commerce | US-only |
+| 🇳🇱 Netherlands `nl` | Crypto, privacy, Polymarket, Web3 | US Banks |
+| 🇯🇵 Japan `jp` | Japanese e-commerce, Line, localized prices | — |
+| 🇫🇷 France `fr` | EU services, luxury brands | US-only |
+| 🇨🇦 Canada `ca` | North American services | Some US-only |
+| 🇸🇬 Singapore `sg` | APAC/SEA e-commerce | US-only |
+| 🇦🇺 Australia `au` | Oceania content | — |
+
+**→ Interactive country selector + service matrix:** [humanbrowser.dev](https://humanbrowser.dev)
+
+---
+
+## Recipes
+
+### Scrape Instagram without getting blocked
+```js
+const { page } = await launchHuman({ country: 'ro' });
+await page.goto('https://www.instagram.com/username/');
+```
+
+### Polymarket / crypto platforms (EU IP required)
+```js
+const { page } = await launchHuman({ country: 'ro' }); // or 'gb', 'nl'
+await page.goto('https://polymarket.com');
+```
+
+### US-only services (Netflix, DoorDash)
+```js
+const { page } = await launchHuman({ country: 'us', mobile: false });
+await page.goto('https://doordash.com');
+```
+
+### React input fields
+```js
+// page.fill() fails silently on React inputs — use humanType instead
+await humanType(page, 'input[name="email"]', 'user@example.com');
+```
+
+### Bypass animated button detection
+```js
+await page.evaluate((text) => {
+  [...document.querySelectorAll('button')]
+    .find(b => b.offsetParent && b.textContent.includes(text))?.click();
+}, 'Continue');
+```
+
+### Verify your IP
+```js
+await page.goto('https://api.ipify.org?format=json');
+const { ip } = JSON.parse(await page.textContent('body'));
+console.log('IP:', ip); // Residential IP from your target country
+```
+
+---
+
+## Get Credentials
+
+Proxy credentials (residential IP) are required. The script itself is free and open source.
+
+**→ Purchase at: [humanbrowser.dev](https://humanbrowser.dev)**
+
+| Plan | Price | Countries | Bandwidth |
+|------|-------|-----------|-----------|
+| Starter 🇷🇴 | $13.99/mo | Romania | 2 GB |
+| Pro 🌍 | $49.99/mo | All 10+ countries | 20 GB |
+| Enterprise | $199/mo | All + dedicated zone | Unlimited |
+
+Payment: **Card** (Stripe + Apple Pay + Google Pay) or **Crypto** (USDT, BTC, ETH, SOL).  
+Credentials are delivered automatically after payment.
+
+---
+
+## Agent-Native Purchase API
+
+Your agent can buy credentials without human involvement:
+
+```js
+const res = await fetch('https://humanbrowser.dev/api/buy', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    plan: 'starter',    // 'starter' | 'pro' | 'enterprise'
+    currency: 'USDT',  // 'card' | 'USDT' | 'BTC' | 'ETH' | 'SOL'
+    email: 'agent@example.com'
+  })
+});
+const { payment_url, order_id } = await res.json();
+```
+
+After confirmation, credentials arrive automatically:
+```
+PROXY_USER=brd-customer-hl_XXXXXX-zone-mcp_unlocker-country-ro
+PROXY_PASS=XXXXXXXXXX
+PROXY_HOST=brd.superproxy.io
+PROXY_PORT=22225
+```
+
+---
+
+## Prerequisites
+
+```bash
+npm install playwright
+npx playwright install chromium --with-deps
+```
+
+Requires residential proxy credentials — see [humanbrowser.dev](https://humanbrowser.dev) for plans.  
+For manual Bright Data setup, see [references/brightdata-setup.md](references/brightdata-setup.md).
+
+---
+
+## How it compares
+
+| Feature | Regular Playwright | Human Browser |
+|---------|-------------------|---------------|
+| IP type | Data center → blocked | Residential → clean |
+| Bot detection | Fails | Passes all |
+| Mouse movement | Instant teleport | Bezier curves |
+| Typing speed | Instant | 60–220ms/char |
+| Fingerprint | Detectable bot | iPhone 15 Pro |
+| Countries | None | 10+ residential |
+| Cloudflare | ❌ | ✅ Bypassed |
+| DataDome | ❌ | ✅ Bypassed |
+| Agent payment | Manual | API-native |
+
+---
+
+## Links
+
+- 🌐 Product page: [humanbrowser.dev](https://humanbrowser.dev)
+- 🦀 ClawHub: [clawhub.ai/al1enjesus/human-browser](https://clawhub.ai/al1enjesus/human-browser)
+- 📦 npm: [@al1enjesus/human-browser](https://www.npmjs.com/package/@al1enjesus/human-browser)
+- 🛠 skills.sh: [skills.sh/al1enjesus/human-browser](https://skills.sh/al1enjesus/human-browser)
+- 💬 Support: [@virixlabs](https://t.me/virixlabs)
+
+---
+
+MIT License © [al1enjesus](https://github.com/al1enjesus)

package/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: human-browser
+description: "Stealth browser with residential proxy for AI agents — runs on any server, no Mac Mini or desktop required. Supports 10+ countries (US, UK, RO, DE, NL, JP, FR, CA, AU, SG). Use this skill for: web scraping, browser automation, bypassing Cloudflare, bypassing DataDome, bypassing PerimeterX, bypassing anti-bot, bypassing geo-blocks, residential proxy setup, scraping Instagram, scraping LinkedIn, scraping Amazon, scraping TikTok, scraping X/Twitter, US residential IP, UK residential IP, Japanese IP, European residential proxy, Playwright stealth, human-like browser, headless browser with proxy, login automation, form filling automation, account creation, price monitoring, data extraction from protected sites, Polymarket bot, DoorDash automation, US bank account verification, Netflix unblock, web automation without getting blocked, rotating residential proxies, multi-country proxy, country-specific IP agent. Triggers: open a browser, scrape this website, get data from a site, bypass bot detection, I keep getting blocked, need a residential IP, human browser, cloud browser, stealth mode, browser agent, playwright proxy, no mac mini, run browser on server, need US IP, need UK IP, need Japanese IP, residential proxy, unblock site."
+---
+
+# Human Browser — Cloud Stealth Browser for AI Agents
+
+> **No Mac Mini. No local machine. Your agent runs it anywhere.**
+> Residential IPs from 10+ countries. Bypasses Cloudflare, DataDome, PerimeterX.
+> 
+> 🌐 **Product page:** https://humanbrowser.dev  
+> 💬 **Support:** https://t.me/virixlabs
+
+---
+
+## Why your agent needs this
+
+Regular Playwright on a data-center server gets blocked **immediately** by:
+- Cloudflare (bot score detection)
+- DataDome (fingerprint analysis)
+- PerimeterX (behavioral analysis)
+- Instagram, LinkedIn, TikTok (residential IP requirement)
+
+Human Browser solves this by combining:
+1. **Residential IP** — real ISP address from the target country (not a data center)
+2. **Real device fingerprint** — iPhone 15 Pro or Windows Chrome, complete with canvas, WebGL, fonts
+3. **Human-like behavior** — Bezier mouse curves, 60–220ms typing, natural scroll with jitter
+4. **Full anti-detection** — `webdriver=false`, no automation flags, correct timezone & geolocation
+
+---
+
+## Country → Service Compatibility
+
+Pick the right country for the right service:
+
+| Country | ✅ Works great | ❌ Blocked |
+|---------|--------------|-----------|
+| 🇷🇴 Romania `ro` | Polymarket, Instagram, Binance, Cloudflare | US Banks, Netflix US |
+| 🇺🇸 United States `us` | Netflix, DoorDash, US Banks, Amazon US | Polymarket, Binance |
+| 🇬🇧 United Kingdom `gb` | Polymarket, Binance, BBC iPlayer | US-only apps |
+| 🇩🇪 Germany `de` | EU services, Binance, German e-commerce | US-only |
+| 🇳🇱 Netherlands `nl` | Crypto, privacy, Polymarket, Web3 | US Banks |
+| 🇯🇵 Japan `jp` | Japanese e-commerce, Line, localized prices | — |
+| 🇫🇷 France `fr` | EU services, luxury brands | US-only |
+| 🇨🇦 Canada `ca` | North American services | Some US-only |
+| 🇸🇬 Singapore `sg` | APAC/SEA e-commerce | US-only |
+| 🇦🇺 Australia `au` | Oceania content | — |
+
+**→ Interactive country selector + service matrix:** https://humanbrowser.dev
+
+---
+
+## Quick Start
+
+```js
+const { launchHuman } = require('./scripts/browser-human');
+
+// Default: iPhone 15 Pro + Romania residential IP
+const { browser, page, humanType, humanClick, humanScroll, sleep } = await launchHuman();
+
+// Specific country
+const { page } = await launchHuman({ country: 'us' }); // US residential IP
+const { page } = await launchHuman({ country: 'gb' }); // UK residential IP
+const { page } = await launchHuman({ country: 'jp' }); // Japan IP
+
+// Desktop Chrome (Windows fingerprint)
+const { page } = await launchHuman({ mobile: false, country: 'us' });
+
+await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
+await humanScroll(page, 'down');
+await humanType(page, 'input[type="email"]', 'user@example.com');
+await humanClick(page, 760, 400);
+await browser.close();
+```
+
+---
+
+## Get Credentials
+
+Credentials (proxy username/password/zone) are required to use the residential IP.
+
+**→ Purchase at: https://humanbrowser.dev**
+
+| Plan | Price | Countries | Bandwidth |
+|------|-------|-----------|-----------|
+| Starter 🇷🇴 | $13.99/mo | Romania only | 2GB |
+| Pro 🌍 | $49.99/mo | All 10+ countries | 20GB |
+| Enterprise | $199/mo | All + dedicated zone | Unlimited |
+
+Payment options: **Stripe** (card + Apple Pay + Google Pay) or **Crypto** (USDT TRC20, BTC, ETH, SOL).
+
+After payment → credentials are delivered automatically (email + Telegram).
+
+---
+
+## 🤖 Agent-Native Payment (Autonomous Purchase)
+
+Your agent can **purchase credentials without human involvement** using the API.
+
+### Step 1 — Create payment via API
+
+```js
+// Your agent calls this to start a purchase
+const res = await fetch('https://humanbrowser.dev/api/buy', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    plan: 'starter',      // 'starter' | 'pro' | 'enterprise'
+    currency: 'USDT',     // 'card' | 'USDT' | 'BTC' | 'ETH' | 'SOL'
+    email: 'your@email.com'
+  })
+});
+const data = await res.json();
+// { payment_url, order_id, currency, method }
+```
+
+### Step 2 — Route by payment method
+
+**If currency = 'card' (Stripe):**
+```js
+// Send human to the Stripe checkout link
+return `To activate Human Browser, please complete payment:\n${data.payment_url}`;
+```
+
+**If currency = 'USDT' / 'BTC' / 'ETH' / 'SOL' (crypto):**
+```js
+// payment_url contains the crypto invoice page
+// Tell your human the payment URL:
+return `To activate Human Browser:
+Order: ${data.order_id}
+Payment page: ${data.payment_url}
+
+Open the link to see the exact wallet address and amount.
+Credentials will be delivered automatically after confirmation.`;
+```
+
+**For fully autonomous crypto (agent-assisted wallet):**
+```js
+// Agent fetches the 0xProcessing invoice page and extracts the address
+// Then tells the human EXACTLY what to send and where:
+const page = await invoice_page_fetch(data.payment_url);
+// Extract: wallet address, amount in USDT, network (TRC20)
+return `Please send ${amount} USDT (TRC20) to:\n${walletAddress}\n\nOrder: ${data.order_id}`;
+```
+
+### Available plans & currencies
+
+```js
+// Plans
+'starter'    // $13.99/mo — Romania, 2GB
+'pro'        // $49.99/mo — All countries, 20GB  
+'enterprise' // $199/mo   — Unlimited + dedicated
+
+// Currencies
+'card'   // Stripe checkout (card + Apple Pay + Google Pay)
+'USDT'   // Tether (TRC20 / ERC20)
+'BTC'    // Bitcoin mainnet
+'ETH'    // Ethereum ERC20
+'SOL'    // Solana
+```
+
+### After payment
+
+Credentials are sent automatically. You'll receive:
+```
+PROXY_USER=brd-customer-hl_XXXXXX-zone-mcp_unlocker-country-ro
+PROXY_PASS=XXXXXXXXXX
+PROXY_HOST=brd.superproxy.io
+PROXY_PORT=22225
+CDP_ENDPOINT=wss://brd-customer-...@brd.superproxy.io:9222
+```
+
+Use these in `launchHuman()`:
+```js
+const { page } = await launchHuman({
+  country: 'ro',
+  proxyUser: process.env.PROXY_USER,
+  proxyPass: process.env.PROXY_PASS,
+});
+```
+
+### Show human the product page
+
+When you need to explain what this does, show pricing, or send someone to pay:
+
+```
+🌐 https://humanbrowser.dev
+```
+
+---
+
+## Real-world recipes
+
+### Scrape Instagram without getting blocked
+```js
+const { page } = await launchHuman({ country: 'ro' });
+await page.goto('https://www.instagram.com/username/');
+// Romanian residential IP — passes Instagram's residential check
+```
+
+### Polymarket / crypto platforms (EU IP required)
+```js
+const { page } = await launchHuman({ country: 'ro' }); // or 'gb', 'nl'
+await page.goto('https://polymarket.com');
+// Polymarket is blocked in US — Romanian IP works perfectly
+```
+
+### Netflix / DoorDash / US-only services
+```js
+const { page } = await launchHuman({ country: 'us', mobile: false });
+await page.goto('https://doordash.com');
+// US residential IP — passes geo-check
+```
+
+### React input fields (don't use page.fill!)
+```js
+// page.fill() fails silently on React inputs — use humanType instead
+await humanType(page, 'input[name="email"]', 'user@example.com');
+```
+
+### Bypass animated button detection
+```js
+await page.evaluate((text) => {
+  [...document.querySelectorAll('button')]
+    .find(b => b.offsetParent && b.textContent.includes(text))?.click();
+}, 'Continue');
+```
+
+### Verify your IP is residential
+```js
+await page.goto('https://api.ipify.org?format=json');
+const { ip } = JSON.parse(await page.textContent('body'));
+console.log('IP:', ip); // Should show a residential IP from your target country
+```
+
+---
+
+## Setup
+
+```bash
+# Install dependencies
+npm install playwright
+npx playwright install chromium --with-deps
+
+# (Optional) Install via skill manager
+clawhub install al1enjesus/human-browser
+# OR
+skild install al1enjesus/human-browser
+```
+
+---
+
+## How it compares
+
+| Feature | Regular Playwright | Human Browser |
+|---------|-------------------|---------------|
+| IP type | Data center → blocked | Residential → clean |
+| Bot detection | Fails | Passes all |
+| Mouse movement | Instant teleport | Bezier curves |
+| Typing speed | Instant | 60–220ms/char |
+| Fingerprint | Detectable bot | iPhone 15 Pro |
+| Countries | None | 10+ residential |
+| Cloudflare | Blocked | Bypassed |
+| DataDome | Blocked | Bypassed |
+| Agent payment | Manual | API-native |
+
+---
+
+→ **Product page + country selector + pricing:** https://humanbrowser.dev  
+→ **Support & questions:** https://t.me/virixlabs  
+→ **Bright Data manual setup:** see `references/brightdata-setup.md`

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "human-browser",
+  "version": "3.0.0",
+  "description": "Stealth browser with residential proxies from 10+ countries for AI agents. Bypasses Cloudflare, DataDome, PerimeterX. iPhone 15 Pro fingerprint.",
+  "keywords": [
+    "browser-automation",
+    "stealth-browser",
+    "residential-proxy",
+    "playwright",
+    "cloudflare-bypass",
+    "anti-bot",
+    "scraping",
+    "ai-agent",
+    "human-browser",
+    "multi-country",
+    "instagram-scraping",
+    "web-scraping",
+    "agent-skill"
+  ],
+  "author": "al1enjesus",
+  "license": "MIT",
+  "homepage": "https://humanbrowser.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/al1enjesus/human-browser"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "scripts/",
+    "references/"
+  ],
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/references/brightdata-setup.md

@@ -0,0 +1,57 @@
+# Bright Data — Setup & Reference
+
+## Sign Up
+- Registration: https://brightdata.com/
+- After signup, go to: https://brightdata.com/cp/zones
+
+## Create Zones
+
+### Web Unlocker Zone (for regular proxying)
+1. Dashboard → Proxies & Scraping → Add Zone
+2. Type: **Web Unlocker**
+3. Name: `mcp_unlocker` (or any name)
+4. Country: Romania (or leave "All" for auto-rotation)
+5. Copy credentials from zone settings
+
+### Scraping Browser Zone (for Playwright CDP)
+1. Dashboard → Proxies & Scraping → Add Zone
+2. Type: **Scraping Browser**
+3. Name: `mcp_browser`
+4. Used for: `wss://brd.superproxy.io:9222` CDP endpoint
+
+## Billing & Top-Up
+- Top up balance: https://brightdata.com/cp/billing
+- Minimum deposit: $10
+- Pay-as-you-go pricing:
+  - Web Unlocker: ~$3/GB
+  - Scraping Browser: ~$9/hour
+
+## Proxy Credentials Format
+
+```
+# HTTP Proxy (for Playwright context)
+server: http://brd.superproxy.io:22225
+username: brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-ro
+password: <ZONE_PASSWORD>
+
+# CDP WebSocket (Scraping Browser only)
+wss://brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-ro:<PASSWORD>@brd.superproxy.io:9222
+```
+
+## Where to Find Credentials
+- Dashboard: https://brightdata.com/cp/zones
+- Click on your zone → **Access Parameters** tab
+- Copy: Customer ID, Zone name, Password
+
+## Country Codes
+- `ro` — Romania (DIGI / WS Telecom residential IPs)
+- `us` — United States
+- `de` — Germany
+- Remove `-country-XX` for global rotation
+
+## Node.js Dependency
+
+```bash
+npm install playwright
+npx playwright install chromium --with-deps
+```

package/scripts/browser-human.js

@@ -0,0 +1,240 @@
+/**
+ * browser-human.js — Human Browser for AI Agents
+ *
+ * Stealth browser with residential proxies from 10+ countries.
+ * Appears as iPhone 15 Pro or Desktop Chrome to every website.
+ * Bypasses Cloudflare, DataDome, PerimeterX out of the box.
+ *
+ * Get credentials: https://humanbrowser.dev
+ * Support: https://t.me/virixlabs
+ *
+ * Usage:
+ *   const { launchHuman } = require('./browser-human');
+ *   const { browser, page } = await launchHuman({ country: 'us' });
+ */
+
+const { chromium } = require('playwright');
+require('dotenv').config();
+
+// ─── COUNTRY CONFIGS ──────────────────────────────────────────────────────────
+
+const COUNTRY_META = {
+  ro: { locale: 'ro-RO', tz: 'Europe/Bucharest', lat: 44.4268, lon: 26.1025, lang: 'ro-RO,ro;q=0.9,en-US;q=0.8' },
+  us: { locale: 'en-US', tz: 'America/New_York',  lat: 40.7128, lon: -74.006,  lang: 'en-US,en;q=0.9' },
+  uk: { locale: 'en-GB', tz: 'Europe/London',     lat: 51.5074, lon: -0.1278,  lang: 'en-GB,en;q=0.9' },
+  gb: { locale: 'en-GB', tz: 'Europe/London',     lat: 51.5074, lon: -0.1278,  lang: 'en-GB,en;q=0.9' },
+  de: { locale: 'de-DE', tz: 'Europe/Berlin',     lat: 52.5200, lon: 13.4050,  lang: 'de-DE,de;q=0.9,en;q=0.8' },
+  nl: { locale: 'nl-NL', tz: 'Europe/Amsterdam',  lat: 52.3676, lon: 4.9041,   lang: 'nl-NL,nl;q=0.9,en;q=0.8' },
+  jp: { locale: 'ja-JP', tz: 'Asia/Tokyo',        lat: 35.6762, lon: 139.6503, lang: 'ja-JP,ja;q=0.9,en;q=0.8' },
+  fr: { locale: 'fr-FR', tz: 'Europe/Paris',      lat: 48.8566, lon: 2.3522,   lang: 'fr-FR,fr;q=0.9,en;q=0.8' },
+  ca: { locale: 'en-CA', tz: 'America/Toronto',   lat: 43.6532, lon: -79.3832, lang: 'en-CA,en;q=0.9' },
+  au: { locale: 'en-AU', tz: 'Australia/Sydney',  lat: -33.8688, lon: 151.2093,lang: 'en-AU,en;q=0.9' },
+  sg: { locale: 'en-SG', tz: 'Asia/Singapore',    lat: 1.3521,  lon: 103.8198, lang: 'en-SG,en;q=0.9' },
+};
+
+// ─── PROXY CONFIG ─────────────────────────────────────────────────────────────
+
+function buildProxy(country = 'ro') {
+  const c = country.toLowerCase();
+  const server   = process.env.PROXY_SERVER   || 'http://brd.superproxy.io:22225';
+  const username = process.env.PROXY_USERNAME || '';
+  const password = process.env.PROXY_PASSWORD || '';
+
+  if (!username || !password) {
+    console.warn('⚠️  No proxy credentials set. Get them at: https://humanbrowser.dev');
+    console.warn('    Set PROXY_USERNAME and PROXY_PASSWORD in your .env file.');
+    return null;
+  }
+
+  // Inject country code into username if needed
+  // e.g. brd-customer-XXX-zone-YYY  →  brd-customer-XXX-zone-YYY-country-ro
+  const hasCountry = username.includes('-country-');
+  const finalUser = hasCountry
+    ? username.replace(/-country-\w+/, `-country-${c}`)
+    : `${username}-country-${c}`;
+
+  return { server, username: finalUser, password };
+}
+
+// ─── DEVICE PROFILES ─────────────────────────────────────────────────────────
+
+function buildDevice(mobile, country = 'ro') {
+  const meta = COUNTRY_META[country.toLowerCase()] || COUNTRY_META.ro;
+
+  if (mobile) {
+    return {
+      userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1',
+      viewport: { width: 393, height: 852 },
+      deviceScaleFactor: 3,
+      isMobile: true,
+      hasTouch: true,
+      locale: meta.locale,
+      timezoneId: meta.tz,
+      geolocation: { latitude: meta.lat, longitude: meta.lon, accuracy: 50 },
+      colorScheme: 'light',
+      extraHTTPHeaders: {
+        'Accept-Language': meta.lang,
+        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+        'Accept-Encoding': 'gzip, deflate, br',
+        'sec-fetch-dest': 'document',
+        'sec-fetch-mode': 'navigate',
+        'sec-fetch-site': 'none',
+      },
+    };
+  }
+
+  return {
+    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+    viewport: { width: 1440, height: 900 },
+    locale: meta.locale,
+    timezoneId: meta.tz,
+    geolocation: { latitude: meta.lat, longitude: meta.lon, accuracy: 50 },
+    colorScheme: 'light',
+    extraHTTPHeaders: {
+      'Accept-Language': meta.lang,
+      'sec-ch-ua': '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+      'sec-ch-ua-mobile': '?0',
+      'sec-ch-ua-platform': '"Windows"',
+    },
+  };
+}
+
+// ─── HUMAN BEHAVIOR ───────────────────────────────────────────────────────────
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+const rand  = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+
+async function humanMouseMove(page, toX, toY) {
+  const cp1x = toX + rand(-80, 80), cp1y = toY + rand(-60, 60);
+  const cp2x = toX + rand(-50, 50), cp2y = toY + rand(-40, 40);
+  const startX = rand(100, 300), startY = rand(200, 600);
+  const steps = rand(12, 25);
+  for (let i = 0; i <= steps; i++) {
+    const t = i / steps;
+    const x = Math.round(Math.pow(1-t,3)*startX + 3*Math.pow(1-t,2)*t*cp1x + 3*(1-t)*t*t*cp2x + t*t*t*toX);
+    const y = Math.round(Math.pow(1-t,3)*startY + 3*Math.pow(1-t,2)*t*cp1y + 3*(1-t)*t*t*cp2y + t*t*t*toY);
+    await page.mouse.move(x, y);
+    await sleep(t < 0.2 || t > 0.8 ? rand(8, 20) : rand(2, 8));
+  }
+}
+
+async function humanClick(page, x, y) {
+  await humanMouseMove(page, x, y);
+  await sleep(rand(50, 180));
+  await page.mouse.down();
+  await sleep(rand(40, 100));
+  await page.mouse.up();
+  await sleep(rand(100, 300));
+}
+
+async function humanType(page, selector, text) {
+  const el = await page.$(selector);
+  if (!el) throw new Error(`Element not found: ${selector}`);
+  const box = await el.boundingBox();
+  if (box) await humanClick(page, box.x + box.width / 2, box.y + box.height / 2);
+  await sleep(rand(200, 500));
+  for (const char of text) {
+    await page.keyboard.type(char);
+    await sleep(rand(60, 220));
+    if (Math.random() < 0.08) await sleep(rand(400, 900));
+  }
+  await sleep(rand(200, 400));
+}
+
+async function humanScroll(page, direction = 'down', amount = null) {
+  const scrollAmount = amount || rand(200, 600);
+  const delta = direction === 'down' ? scrollAmount : -scrollAmount;
+  const vp = page.viewportSize();
+  await humanMouseMove(page, rand(100, vp.width - 100), rand(200, vp.height - 200));
+  const steps = rand(4, 10);
+  for (let i = 0; i < steps; i++) {
+    await page.mouse.wheel(0, delta / steps + rand(-5, 5));
+    await sleep(rand(30, 80));
+  }
+  await sleep(rand(200, 800));
+}
+
+async function humanRead(page, minMs = 1500, maxMs = 4000) {
+  await sleep(rand(minMs, maxMs));
+  if (Math.random() < 0.3) await humanScroll(page, 'down', rand(50, 150));
+}
+
+// ─── LAUNCH ───────────────────────────────────────────────────────────────────
+
+/**
+ * Launch a human-like browser with residential proxy
+ *
+ * @param {Object}  opts
+ * @param {string}  opts.country  - 'ro'|'us'|'uk'|'de'|'nl'|'jp'|'fr'|'ca'|'au'|'sg' (default: 'ro')
+ * @param {boolean} opts.mobile   - iPhone 15 Pro (true) or Desktop Chrome (false). Default: true
+ * @param {boolean} opts.useProxy - Enable residential proxy. Default: true
+ * @param {boolean} opts.headless - Headless mode. Default: true
+ *
+ * @returns {{ browser, ctx, page, humanClick, humanType, humanScroll, humanRead, sleep, rand }}
+ */
+async function launchHuman(opts = {}) {
+  const {
+    country  = 'ro',
+    mobile   = true,
+    useProxy = true,
+    headless = true,
+  } = opts;
+
+  const meta   = COUNTRY_META[country.toLowerCase()] || COUNTRY_META.ro;
+  const device = buildDevice(mobile, country);
+  const proxy  = useProxy ? buildProxy(country) : null;
+
+  const browser = await chromium.launch({
+    headless,
+    args: [
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--ignore-certificate-errors',
+      '--disable-blink-features=AutomationControlled',
+      '--disable-features=IsolateOrigins,site-per-process',
+      '--disable-web-security',
+    ],
+  });
+
+  const ctxOpts = {
+    ...device,
+    ignoreHTTPSErrors: true,
+    permissions: ['geolocation', 'notifications'],
+  };
+  if (proxy) ctxOpts.proxy = proxy;
+
+  const ctx = await browser.newContext(ctxOpts);
+
+  // Anti-detection overrides
+  await ctx.addInitScript((m) => {
+    Object.defineProperty(navigator, 'webdriver',          { get: () => false });
+    Object.defineProperty(navigator, 'maxTouchPoints',     { get: () => 5 });
+    Object.defineProperty(navigator, 'platform',           { get: () => m.mobile ? 'iPhone' : 'Win32' });
+    Object.defineProperty(navigator, 'hardwareConcurrency',{ get: () => m.mobile ? 6 : 8 });
+    Object.defineProperty(navigator, 'language',           { get: () => m.locale });
+    Object.defineProperty(navigator, 'languages',          { get: () => [m.locale, 'en'] });
+  }, { mobile, locale: meta.locale });
+
+  const page = await ctx.newPage();
+
+  return { browser, ctx, page, humanClick, humanMouseMove, humanType, humanScroll, humanRead, sleep, rand };
+}
+
+module.exports = { launchHuman, humanClick, humanMouseMove, humanType, humanScroll, humanRead, sleep, rand, COUNTRY_META };
+
+// ─── QUICK TEST ───────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const country = process.argv[2] || 'ro';
+  console.log(`🧪 Testing Human Browser — country: ${country.toUpperCase()}\n`);
+  (async () => {
+    const { browser, page } = await launchHuman({ country, mobile: true });
+    await page.goto('https://ipinfo.io/json', { waitUntil: 'domcontentloaded', timeout: 30000 });
+    const info = JSON.parse(await page.textContent('body'));
+    console.log(`✅ IP:      ${info.ip}`);
+    console.log(`✅ Country: ${info.country} (${info.city})`);
+    console.log(`✅ Org:     ${info.org}`);
+    console.log(`✅ TZ:      ${info.timezone}`);
+    await browser.close();
+    console.log('\n🎉 Human Browser is ready.');
+  })().catch(console.error);
+}