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.setCookies(cookies, url?)

Restore a batch of cookies into the session jar, keeping every attribute. Accepts the output of getAllCookies() directly, so a jar can round-trip through JSON.

// Export
fs.writeFileSync('cookies.json', JSON.stringify(session.getAllCookies()));

// Import, in another process
const restored = await createSession({ browser: 'chrome' });
restored.setCookies(JSON.parse(fs.readFileSync('cookies.json', 'utf8')), 'https://example.com');

SessionCookieInit[]

required

Cookies to store. Only name and value are required; domain, path, secure, httpOnly, sameSite, and expiresAtMs are applied when present.

string | URL

Origin used to scope host-only cookies — those without a domain. Required whenever the batch contains one, unless the cookie carries its own url.

A cookie with a domain describes its own scope. A cookie without one is host-only, and the jar keeps that host as an internal key it never returns, so it is missing from the export. url supplies it — which means a jar holding host-only cookies from several hosts cannot be restored from a single url: they would all land on that one host. Set url on the individual cookie to place each one precisely.

The batch is validated before anything is stored, so a rejected cookie leaves the jar untouched instead of applying half the restore. Cookies whose expiresAtMs is already in the past are dropped rather than stored, matching how the jar treats an expired Set-Cookie.

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.setCookies(cookies, 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.setCookies(cookies, 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.setCookies(cookies, url?)

session.clearCookies()

session.close()

Example

withSession()

Signature

Example

With options

Session vs. Ephemeral