Usage

Minimal Example: Playwright CDP Connection

The core pattern is replacing chromium.launch() with chromium.connectOverCDP() pointing at the Surfsky WebSocket endpoint. All standard Playwright page automation runs unchanged after connection.

import { chromium } from 'playwright';

const SURFSKY_KEY = process.env.SURFSKY_API_KEY;

// Connect to a Surfsky cloud browser session
const browser = await chromium.connectOverCDP(
  `wss://surfsky.io/?key=${SURFSKY_KEY}&profile=acc_42`
);

const page = await browser.newPage();
await page.goto('https://example.com');

const title = await page.title();
console.log('Page title:', title);

await browser.close();

One-Time Profile via REST API

For scraping tasks where you do not need a persistent profile, create a one-time session via HTTP POST before connecting:

curl -X POST https://surfsky.io/profiles/one_time \
  -H "Authorization: Bearer $SURFSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": { "os": "win" },
    "proxy": { "country": "us" },
    "captcha": { "auto_solve": true }
  }'

The response returns a profile ID and a WebSocket URL. Pass that URL to connectOverCDP().

Human Emulation Layer

Surfsky exposes a CDP domain called Human that emulates realistic mouse movements and typing patterns:

const cdp = await page.context().newCDPSession(page);

// Human-like click on a CSS selector
await cdp.send('Human.click', '#login-button');

// Human-like keystroke-by-keystroke typing
await cdp.send('Human.type', 'user@example.com');

Use Human.click and Human.type in place of page.click() and page.fill() when targeting sites that monitor interaction timing.

Parallel Sessions

Surfsky is designed for concurrent workloads. Use Promise.all to run multiple sessions simultaneously up to your plan's concurrency limit:

const jobs = ['https://site-a.com', 'https://site-b.com', 'https://site-c.com'];

await Promise.all(
  jobs.map(async (url) => {
    const browser = await chromium.connectOverCDP(
      `wss://surfsky.io/?key=${SURFSKY_KEY}&profile=acc_${Math.random()}`
    );
    const page = await browser.newPage();
    await page.goto(url);
    const data = await page.textContent('body');
    console.log(url, data.slice(0, 100));
    await browser.close();
  })
);