wreq-js Documentation

Signature

function websocket(url: string | URL, options?: WebSocketOptions): Promise<WebSocket>

websocket(...) resolves after the connection opens.

Constructor shape

WebSocket also supports constructor usage for browser-style ergonomics.

declare class WebSocket {
  constructor(url: string | URL, protocols?: string | string[]);
  constructor(url: string | URL, options?: WebSocketOptions);
  constructor(url: string | URL, protocols?: string | string[], options?: WebSocketOptions);
}

WebSocketOptions

BrowserProfile

Browser fingerprint profile for the connection.

EmulationOS

Operating system fingerprint for the connection.

string

Proxy URL for the connection.

HeadersInit

Additional headers for the WebSocket handshake.

string | string[]

Optional subprotocol list for compatibility with standard WebSocket shape. Values are validated for non-empty unique entries and sent in the Sec-WebSocket-Protocol handshake header.

number

Maximum size in bytes for a single incoming WebSocket frame. Increase this when the peer sends large unfragmented frames.

number

Maximum size in bytes for a complete incoming WebSocket message. Increase this when the peer sends very large fragmented messages.

'nodebuffer' | 'arraybuffer' | 'blob'

default:"nodebuffer"

Binary payload format exposed at event.data.

Returned WebSocket instance

The instance mirrors familiar WebSocket APIs.

Properties
1. url
2. readyState
3. binaryType
4. bufferedAmount
5. protocol
6. extensions
7. onopen
8. onmessage
9. onclose
10. onerror

protocol and extensions reflect negotiated values from the upgrade response when the server provides them.

Methods
1. send(data) where data can be string, Buffer, ArrayBuffer, ArrayBufferView, or Blob
2. close(code?, reason?)
3. addEventListener(type, listener)
4. removeEventListener(type, listener)

close(code, reason) accepts code 1000 or codes in the 3000 to 4999 range. When providing a reason, the UTF-8 byte length must be 123 or fewer.

Constants
1. WebSocket.CONNECTING
2. WebSocket.OPEN
3. WebSocket.CLOSING
4. WebSocket.CLOSED

Session support

For authenticated socket flows, use createSession() and then session.websocket(url, options). Within a session, WebSocket uses the same session context and transport settings.

import { createSession } from 'wreq-js';

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

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

const ws = await session.websocket('wss://example.com/ws');

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

Examples

Helper style

import { websocket } from 'wreq-js';

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

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

void ws.send('hello');

Constructor style

import { WebSocket } from 'wreq-js';

const ws = new WebSocket('wss://example.com/socket', {
  browser: 'firefox_139',
  proxy: 'http://proxy.example.com:8080',
});

ws.addEventListener('open', () => {
  void ws.send(JSON.stringify({ type: 'ping' }));
});

ws.addEventListener('close', (event) => {
  console.log(event.code, event.reason);
});

Binary payload mode

const ws = await websocket('wss://example.com/socket', { browser: 'chrome_142' });

ws.binaryType = 'arraybuffer';

ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    console.log('received array buffer', event.data.byteLength);
  }
};

Large incoming messages

Some providers send very large WebSocket payloads in a single frame. If you see an error such as Space limit exceeded: Message too long, raise the frame or message limits explicitly.

const ws = await websocket('wss://example.com/socket', {
  browser: 'chrome_142',
  maxFrameSize: 32 * 1024 * 1024,
  maxMessageSize: 32 * 1024 * 1024,
});

API Reference

websocket()

Signature

Constructor shape

WebSocketOptions

Returned WebSocket instance

Session support

Examples

Helper style

Constructor style

Binary payload mode

Large incoming messages

​Signature

​Constructor shape

​WebSocketOptions

​Returned WebSocket instance

​Session support

​Examples

​Helper style

​Constructor style

​Binary payload mode

​Large incoming messages

Signature

Constructor shape

WebSocketOptions

Returned WebSocket instance

Session support

Examples

Helper style

Constructor style

Binary payload mode

Large incoming messages