wreq-js Documentation

createSession()

Create a persistent session context for related requests. Within a session, browser, os, and proxy are fixed at creation time (unless you pass an explicit transport per request).

Signature

function createSession(options?: CreateSessionOptions): Promise<Session>

Options

BrowserProfile

Default browser fingerprint profile for all session requests.

EmulationOS

Default operating system to emulate.

string

Default proxy URL for all session requests.

number

default:"30000"

Default request timeout in milliseconds.

HeadersInit

Default headers to include in every session request. Can be a Headers object, plain object, or array of key-value pairs.

string

Explicit session identifier. When omitted, a random ID is generated.

boolean

default:"false"

Accept invalid certificates for all session requests. Use only in development.

boolean

default:"false"

Enable extra connection and TLS diagnostics for requests made through this session by default.

Session object

The returned Session object has:

session.fetch(url, init?)

Make a request using the session context.

const response = await session.fetch('https://example.com/api', {
  method: 'POST',
  body: JSON.stringify({ data: 'value' }),
});

Per-request options override session defaults. session.fetch() also accepts request-scoped onRequestEvent and captureDiagnostics options from fetch(). When diagnostics are enabled, inspect response.diagnostics on the returned response.

session.websocket(url, options?)

Open a WebSocket that reuses the session transport and context. Use this after login or any other HTTP flow that sets cookies.

const ws = await session.websocket('wss://example.com/ws', {
  headers: {
    Authorization: 'Bearer token',
  },
});

ws.onmessage = (event) => {
  console.log(event.data);
};

ws.close();

session.websocket(...) accepts headers, protocols, and binaryType. It does not accept browser, os, or proxy because those are owned by the session transport. protocols values are validated for non-empty unique entries and sent in the Sec-WebSocket-Protocol handshake header.

session.getCookies(url)

Return cookies that would be sent to the given URL (RFC 6265 domain/path matching).

const cookies: Record<string, string> = session.getCookies('https://example.com');
// { "session_id": "abc123", "theme": "dark" }

string | URL

required

Target URL. Only cookies whose domain and path match this URL are returned.

Returns Record<string, string> — cookie name/value pairs.

session.getAllCookies()

Return every cookie currently stored in the session jar, regardless of URL matching.

const cookies = session.getAllCookies();
// [
//   {
//     name: 'session_id',
//     value: 'abc123',
//     secure: true,
//     httpOnly: true,
//     domain: 'example.com',
//     path: '/',
//   },
// ]

Returns SessionCookie[] — all cookies in the jar, with scope metadata such as domain, path, sameSite, and expiresAtMs when available.

session.setCookie(name, value, url)

Add a cookie to the session jar, scoped to the domain/path of the given URL.

session.setCookie('token', 'abc123', 'https://example.com');

string

required

Cookie name.

string

required

Cookie value.

string | URL

required

URL that determines the cookie’s domain and path scope.

session.clearCookies()

Clear all cookies from the session cookie jar.

await session.clearCookies();

session.close()

Close the session and release resources. Always call this when done.

await session.close();

Example

import { createSession } from 'wreq-js';

const session = await createSession({
  browser: 'chrome_142',
  os: 'windows',
});

// Login in the same session context
await session.fetch('https://example.com/login', {
  method: 'POST',
  body: new URLSearchParams({ user: 'name', pass: 'secret' }),
});

// Subsequent requests use the same session context
const profile = await session.fetch('https://example.com/profile');
console.log(await profile.json());

// Always close when done
await session.close();

withSession()

Auto-disposing session helper that closes the session when the callback completes.

Signature

function withSession<T>(
  fn: (session: Session) => Promise<T> | T,
  options?: CreateSessionOptions
): Promise<T>

Example

import { withSession } from 'wreq-js';

const result = await withSession(async (session) => {
  await session.fetch('https://example.com/login', {
    method: 'POST',
    body: 'credentials',
  });
  
  const response = await session.fetch('https://example.com/data');
  return response.json();
}, {
  browser: 'chrome_142',
});

// Session is automatically closed
console.log(result);

With options

const data = await withSession(
  async (session) => {
    const response = await session.fetch('https://example.com/api');
    return response.json();
  },
  {
    browser: 'firefox_139',
    proxy: 'http://proxy.example.com:8080',
  }
);

Session vs. Ephemeral

Feature	Ephemeral (default `fetch`)	Session
Cookies	Separate request context	Shared session context
Transport settings	Request scoped	Session scoped unless overridden by transport
Use case	Isolated requests	Multi-step flows

API Reference

Sessions

createSession()

Signature

Options

Session object

session.fetch(url, init?)

session.websocket(url, options?)

session.getCookies(url)

session.getAllCookies()

session.setCookie(name, value, url)

session.clearCookies()

session.close()

Example

withSession()

Signature

Example

With options

Session vs. Ephemeral

​createSession()

​Signature

​Options

​Session object

​session.fetch(url, init?)

​session.websocket(url, options?)

​session.getCookies(url)

​session.getAllCookies()

​session.setCookie(name, value, url)

​session.clearCookies()

​session.close()

​Example

​withSession()

​Signature

​Example

​With options

​Session vs. Ephemeral

createSession()

Signature

Options

Session object

session.fetch(url, init?)

session.websocket(url, options?)

session.getCookies(url)

session.getAllCookies()

session.setCookie(name, value, url)

session.clearCookies()

session.close()

Example

withSession()

Signature

Example

With options

Session vs. Ephemeral