stealthBrowser

Librería Node.js que combina:

• Cliente HTTP/HTTPS con manejo de cookies, redirects, headers “tipo Chrome”, y descompresión gzip/deflate/br.
• “Navegación” de páginas HTML usando jsdom, ejecutando scripts y exponiendo varias APIs típicas del navegador (navigator, screen, storage, permissions, etc.) con valores configurables.

Nota: esto no es un navegador real (no hay motor de render real). Está pensado para scraping/automatización ligera cuando necesitas HTML + scripts en un sandbox.

Instalación

npm i stealthBrowser

Import / Require (ESM y CommonJS)

ESM

import StealthBrowser from "stealthBrowser";

const browser = StealthBrowser.create({ debug: false });

CommonJS

const StealthBrowser = require("stealthBrowser");

const browser = StealthBrowser.create({ debug: false });

Quick start

import StealthBrowser from "stealthBrowser";

const browser = StealthBrowser.create({
  language: "es-ES,es;q=0.9,en;q=0.8",
  timezone: "America/Managua"
});

const page = await browser.navigate("https://example.com");

console.log(page.title);
console.log(page.status);
console.log(page.fingerprint.canvas);
browser.close();

API

StealthBrowser.create(options?)

Crea una instancia.

Opciones comunes (todas opcionales):

• userAgent (string)
• language (string)
• timezone (string)
• locale (string)
• platform (string)
• screen (obj) { width, height, depth, availWidth, availHeight }
• hardwareConcurrency (number)
• deviceMemory (number)
• headers (obj) headers extra/override
• cookies (obj) cookies iniciales { name: value }
• proxy (obj) configuración para http(s).request (avanzado)
• maxRedirects (number)
• timeout (ms)
• debug (boolean)
• Toggles: webRTC, canvasNoise, audioContextNoise, mediaDevices, batteryAPI

browser.get(url, headers?) / browser.post(url, data, headers?)

Devuelve:

{
  status: number,
  statusText: string,
  headers: Record<string, string | string[]>,
  body: Buffer,
  rawBody: Buffer,
  url: string,
  redirected: boolean,
  type: string
}

Ejemplo:

const res = await browser.get("https://httpbin.org/headers");
// Tip: body es Buffer
console.log(res.status, res.body.toString("utf8"));

browser.navigate(url, headers?, options?)

Si la respuesta es HTML, retorna un “page context” con jsdom:

{
  pageId: string,
  url: string,
  status: number,
  headers: any,
  html: string,
  window: Window,
  document: Document,
  title: string,
  cookies: Array<Cookie>,
  fingerprint: Fingerprint,
  localStorage: Map,
  sessionStorage: Map
}

Ejemplo:

const page = await browser.navigate("https://example.com");
console.log(page.document.querySelector("h1")?.textContent);

Interacción ligera: click, type, evaluate

browser.click(selector, page)

Simula eventos de mouse y, si el elemento es <a> navega automáticamente.

const page = await browser.navigate("https://example.com");

// click en un link
const next = await browser.click("a", page);
console.log(next.url);

browser.type(selector, text, page)

Asigna el valor y dispara eventos básicos.

await browser.type('input[name="q"]', "hola", page);
// (comentario) no es un teclado real; solo dispara eventos comunes

browser.evaluate(page, script)

Ejecuta JS en un contexto con window y document.

const result = await browser.evaluate(page, "return document.title;");
console.log(result);

Cookies

• Se guardan cookies de Set-Cookie automáticamente.
• browser.clearCookies(domain?) borra por dominio o todas.
• browser.getHistory() devuelve historial de requests.
• browser.clearStorage(pageId?) limpia storage y timers.

Recomendaciones

• Si un sitio depende mucho de APIs no soportadas por jsdom o de renderizado real, esto no va a ser suficiente.
• Ajusta timeout y maxRedirects según el target.
• Usa debug: true para ver errores de ejecución de scripts.

License

MIT