TypeScript SDK - Surfsky

Requires Node.js 22 or newer, or Bun. The surfsky package uses ES modules and includes TypeScript definitions.

npm install surfsky

Set SURFSKY_API_TOKEN and SURFSKY_API_BASE_URL from the dashboard. See credential setup. You can also pass apiToken and baseUrl to the constructor.

Start a browser

Save as first-browser.mjs and run node first-browser.mjs. The same code can be used in a TypeScript project configured for ESM.

import { Surfsky } from "surfsky";

const client = new Surfsky();
const browser = await client.browser();
try {
  await browser.goto("https://example.com");
  console.log(await browser.title());
} finally {
  await browser.close();
}

Expected output is Example Domain. browser.close() stops the session. Put it in finally so it also runs when a page operation throws. Cleanup cannot complete if the process is forcibly terminated or loses access to the API. On runtimes that support explicit resource management, such as Node.js 24+ or Bun, await using can handle cleanup at scope exit:

await using browser = await client.browser();
await browser.goto("https://example.com");

For Node.js 22, use try/finally or a TypeScript build that transforms await using for your runtime.

Interact with the page

Methods include goto, click, type, hover, innerText, and waitForSelector. Run page operations while the browser is open, using selectors from your target page:

await browser.type('input[name="email"]', "[email protected]");
await browser.click('button[type="submit"]');
await browser.waitForSelector(".confirmation");
console.log(await browser.innerText(".confirmation"));

evaluate() runs JavaScript in an isolated execution context by default. Use isolated: false to access variables defined by the page. DOM changes remain visible to the page.

console.log(await browser.evaluate("document.title"));

Save traffic

Choose resource types when starting a browser:

const browser = await client.browser({
  blockResources: ["image", "font", "media"],
});

Close this browser after use. Keep resources required by your target page; see Speed optimization.

Capture a page’s API response

Start capture before navigation. Adapt the URL and response path to your application:

await browser.captureResponses("/api/search");
await browser.goto("https://your-site.example/search");
const response = await browser.waitForResponse("/api/search");
const data = response.json();

Multiple tabs

browser operates on the first tab. browser.pages contains other tabs and popups:

await browser.newPage();
await browser.pages[1].goto("https://example.com");
console.log(await browser.pages[1].title());

See the session page limit.

Running many browsers

import { Surfsky } from "surfsky";

const client = new Surfsky();
const outcomes = await client.map(
  async (browser, url) => {
    await browser.goto(url);
    return browser.title();
  },
  ["https://example.com", "https://example.org"],
  { concurrency: 2 },
);

for (const outcome of outcomes) {
  console.log(outcome.ok ? outcome.value : outcome.error);
}

The pool collects an outcome for each job and can reuse browsers between jobs. Leases retain browser state, including cookies. Do not assume each item receives an empty browser. For manual leasing on Node.js 24+ or Bun:

await using pool = await client.browsers({ concurrency: 2 });
await pool.lease(async (browser) => {
  await browser.goto("https://example.com");
  console.log(await browser.title());
});

See Concurrency for account limits and work distributed across processes.

Proxies

Pass proxy to browser() or session():

const browser = await client.browser({
  proxy: { tier: "premium", country: "us" },
});

You can also select tier: "shared" or supply a proxy URL. Close the browser after use. client.proxies provides location and quota lookups; see Proxies.

Sessions

By default, client.browser() starts a one-time session whose state is discarded when it stops. To reuse login state, cookies, and local storage across runs, create a persistent profile and pass its UUID to client.browser({ profileUuid }). Save this as reuse-session.mjs. On the first run it creates a profile and saves its UUID in profile-uuid.txt. Later runs read that UUID and restore the same profile:

import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { Surfsky } from "surfsky";

const client = new Surfsky();
const profileFile = "profile-uuid.txt";
if (!existsSync(profileFile)) {
  const profile = await client.profiles.create({
    title: "Reusable session",
    fingerprint: { os: "win" },
    storage_options: { cookies: true, localstorage: true },
  });
  writeFileSync(profileFile, profile.uuid);
}

const profileUuid = readFileSync(profileFile, "utf8").trim();
const browser = await client.browser({ profileUuid });
try {
  await browser.goto("https://example.com");
  console.log("Previous run:", await browser.evaluate('localStorage.getItem("previous-run")'));
  await browser.evaluate('localStorage.setItem("previous-run", "saved")');
} finally {
  await browser.close();
}

Run node reuse-session.mjs twice from the same directory, waiting for each run to finish. The first run prints Previous run: null; the second prints Previous run: saved. Surfsky stores the browser state; the local file stores only the profile UUID. await browser.close() stops the session and saves the selected browser state. To reuse a login, replace the example page operations with your site’s sign-in flow on the first run, then open an authenticated page on later runs.

Raw requests

const response = await client.request("GET", "/proxies/shared/quota");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

request() returns the raw response and does not throw on HTTP status. The SDK repository contains the complete method reference and examples.

​Start a browser

​Interact with the page

​Save traffic

​Capture a page’s API response

​Multiple tabs

​Running many browsers

​Proxies

​Sessions

​Raw requests