shadey

Stealth browser sessions for AI agents. Pass Cloudflare, DataDome, PerimeterX, and Kasada from any IP.

Install

npm install shadey

Quick Start

import { Shadey } from "shadey";

const client = new Shadey("sk_your_api_key");
const session = await client.session();

// Navigate and scrape — no CDP needed
await session.goto("https://example.com");
const { data } = await session.extract("h1");
console.log(data); // "Example Domain"

// Screenshot the page
const { data: img } = await session.screenshot();

// Run JavaScript in the page
const { result } = await session.evaluate("document.title");

// Get full page HTML
const { html } = await session.content();

// Clean up
await session.close();

REST Scraping (no CDP)

const session = await client.session();

await session.goto("https://news.ycombinator.com");

// Extract all story titles
const { data: titles } = await session.extract("a.storylink", { all: true });
console.log(titles); // ["Story 1", "Story 2", ...]

// Extract href attributes
const { data: links } = await session.extract("a.storylink", {
  attribute: "href",
  all: true,
});

await session.close();

Behavioral Actions + CDP

const session = await client.session();

// Human-like click at coordinates
await session.click(500, 300);

// Type with realistic keystroke timing
await session.typeText("hello world", "search");

// Scroll down 400px with natural momentum
await session.scroll(400);

// Idle browse — mouse moves, scrolls, pauses like a real user
await session.idle(5000);

// Connect with Playwright for full browser control
import { chromium } from "playwright";
const browser = await chromium.connectOverCDP(session.playwrightUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://nowsecure.nl");
console.log(await page.title());

await session.close();

API

new Shadey(apiKey, baseUrl?)

Create a client. Default base URL: https://api.shadey.dev.

client.session(opts?)

Create a stealth browser session. Options:

• stealth: "basic" | "advanced" | "full" (default: "full")
• proxy: proxy URL
• profile: named browser profile for persistent cookies

REST Actions

session.goto(url, waitMs?)

Navigate to a URL. Default wait: 3000ms.

session.screenshot()

Take a JPEG screenshot. Returns { format, data } with base64 data URI.

session.extract(selector, opts?)

Extract data from the page. Options: { attribute?: string, all?: boolean }.

session.evaluate(expression)

Run JavaScript in the page. Returns { result, type, error? }.

session.content()

Get full page HTML. Returns { url, html, length }.

Behavioral Actions

session.click(x, y, width?)

Move mouse and click with Fitts' law timing and corrective submovements.

session.typeText(text, context?)

Type with QWERTY bigram-modeled keystroke timing. Context: "form" | "search" | "url".

session.scroll(distance)

Scroll with momentum. Positive = down, negative = up.

session.dwell(context?)

Wait a human-realistic duration. Context: "content" | "search" | "form".

session.idle(durationMs?)

Simulate idle browsing with HMM behavioral model.

Other

session.playwrightUrl / session.puppeteerUrl

CDP WebSocket URL for direct browser control.

session.close()

Destroy the session.

client.usage()

Get plan usage stats.

client.health()

Check API health.