Skip to main content

​
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

​
browser
BrowserProfile
Default browser fingerprint profile for all session requests.
​
os
EmulationOS
Default operating system to emulate.
​
proxy
string
Default proxy URL for all session requests.
​
timeout
number
default:"30000"
Default request timeout in milliseconds.
​
defaultHeaders
HeadersInit
Default headers to include in every session request. Can be a Headers object, plain object, or array of key-value pairs.
​
sessionId
string
Explicit session identifier. When omitted, a random ID is generated.
​
insecure
boolean
default:"false"
Accept invalid certificates for all session requests. Use only in development.

​
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.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" }
​
url
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.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');
​
name
string
required
Cookie name.
​
value
string
required
Cookie value.
​
url
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

FeatureEphemeral (default fetch)Session
CookiesSeparate request contextShared session context
Transport settingsRequest scopedSession scoped unless overridden by transport
Use caseIsolated requestsMulti-step flows