wreq-js

https://github.com/sqdshguy/wreq-js
Admin
A high-performance HTTP client for Node.js with real-browser TLS and HTTP/2 fingerprints, powered by...
Tokens:72,915
Snippets:541
Trust Score:8.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quick Start Build Commands

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Install dependencies and build the project. This runs the Rust and TypeScript builds sequentially.

```bash
npm install
npm run build

```

--------------------------------

### Verify wreq-js installation

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/installation.mdx

TypeScript example that imports fetch and getProfiles from wreq-js, lists available browser profiles, and makes a test request to httpbin.org.

```typescript
import { fetch, getProfiles } from 'wreq-js';

// Check available browser profiles
console.log('Available profiles:', getProfiles());

// Make a test request
const response = await fetch('https://httpbin.org/get', {
  browser: 'chrome_142',
});
console.log('Status:', response.status);
```

--------------------------------

### createSession example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Creates a session with browser and OS options, performs a login POST request, then a subsequent GET request in the same session context. Always close the session when done.

```typescript
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();
```

--------------------------------

### getOperatingSystems() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Example of using getOperatingSystems() to retrieve and log available operating systems.

```typescript
import { getOperatingSystems } from 'wreq-js';

const systems = getOperatingSystems();
console.log(systems);
// Example output: ['windows', 'macos', 'linux', 'android', 'ios']
```

--------------------------------

### Install dependencies

Source: https://github.com/sqdshguy/wreq-js/blob/master/CONTRIBUTING.md

Run npm install to install project dependencies.

```bash
npm install
```

--------------------------------

### Install build tools on Linux (Ubuntu/Debian and Fedora/RHEL)

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Install standard build tools on Linux. The first command is for Ubuntu/Debian, the second for Fedora/RHEL.

```bash
# Ubuntu/Debian
sudo apt-get install build-essential
```

```bash
# Fedora/RHEL
sudo dnf install gcc
```

--------------------------------

### Quick Example: fetch with browser profile

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/introduction.mdx

Use the fetch-style API from 'wreq-js' to make a request with a browser profile and OS. The example selects 'chrome_142' and 'windows'. Note: for multiple requests, use a session to reuse the session context.

```typescript
import { fetch } from 'wreq-js';

const response = await fetch('https://example.com/api', {
  browser: 'chrome_142',
  os: 'windows',
});

console.log(await response.json());
```

--------------------------------

### get(url, init?)

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/fetch.mdx

Convenience helper that performs a GET request by calling fetch with method set to 'GET'.

```APIDOC
## get(url, init?)

### Description
Convenience helper that calls `fetch(url, { ...init, method: "GET" })`. Useful for making GET requests with the same options as fetch.

### Method
GET

### Endpoint
Any URL (passed as first argument)

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to request.

#### Request Body (optional)
- **init** (object) - Optional - Same options as fetch, except method is forced to 'GET'.

### Request Example
```typescript
import { get } from 'wreq-js';
const response = await get('https://api.example.com/data', { browser: 'chrome_142' });
```

### Response
#### Success Response (200)
- **response** (Response) - The standard Response object.

#### Response Example
```typescript
const data = await response.json();
```
```

--------------------------------

### Install wreq-js with bun

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/installation.mdx

Use this command to install wreq-js using the bun package manager. Requires Node.js v20.0.0 or higher.

```bash
bun add wreq-js
```

--------------------------------

### getEmulationHeaders() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Example usage of getEmulationHeaders, showing how to retrieve the user-agent header from a profile.

```typescript
import { getEmulationHeaders } from 'wreq-js';

const defaults = getEmulationHeaders('firefox_147');
console.log(defaults.get('user-agent'));
// Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:147.0) Gecko/20100101 Firefox/147.0
```

--------------------------------

### First-time Package Bootstrap Commands

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

One-time setup to claim platform package names and configure trusted publishing. Requires npm 12+ and a logged-in npm account with 2FA.

```bash
npm install -g npm@latest                          # needs npm 12+, see below
scripts/bootstrap-platform-packages.sh --dry-run   # inspect
scripts/bootstrap-platform-packages.sh             # claim names + configure trusted publishing

```

--------------------------------

### Install Rust toolchain via rustup

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/installation.mdx

Installs the Rust toolchain using rustup, a prerequisite for building wreq-js from source when a prebuilt binary is unavailable.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Helper style websocket() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/websocket.mdx

Helper style example using the websocket() function with browser profile and custom headers. Demonstrates sending a message after connection.

```typescript
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');
```

--------------------------------

### Install wreq-js with yarn

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/installation.mdx

Use this command to install wreq-js using the yarn package manager. Requires Node.js v20.0.0 or higher.

```bash
yarn add wreq-js
```

--------------------------------

### AWS setup IAM

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BENCHMARK.md

Creates the EC2 instance profile once, requires IAM permissions.

```bash
./scripts/aws-perf/setup-iam.sh

```

--------------------------------

### Install wreq-js with pnpm

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/installation.mdx

Use this command to install wreq-js using the pnpm package manager. Requires Node.js v20.0.0 or higher.

```bash
pnpm add wreq-js
```

--------------------------------

### Install wreq-js with npm

Source: https://github.com/sqdshguy/wreq-js/blob/master/README.md

Install the wreq-js package using npm. Alternative package managers (yarn, pnpm, bun) are shown in comments. Requires Node.js 20 or newer.

```bash
npm install wreq-js
# or: yarn add wreq-js / pnpm add wreq-js / bun add wreq-js
```

--------------------------------

### Install build essentials on Ubuntu/Debian

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/installation.mdx

Installs the build-essential package, which includes a C compiler and related tools, required for building from source on Ubuntu or Debian.

```bash
sudo apt-get install build-essential
```

--------------------------------

### Constructor style with new WebSocket()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/guides/websockets.mdx

Use the constructor style to get a browser-like WebSocket shape with CONNECTING state. Configure browser and OS options. The example shows open, message, and error handlers.

```typescript
import { WebSocket } from 'wreq-js';

const ws = new WebSocket('wss://example.com/socket', {
  browser: 'chrome_142',
  os: 'windows',
});

ws.onopen = () => {
  void ws.send('hello from constructor api');
};

ws.addEventListener('message', (event) => {
  console.log(event.data);
});

ws.onerror = () => {
  console.error('WebSocket error');
};
```

--------------------------------

### get() / post()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/overview.mdx

Convenience wrappers around fetch() for GET and POST requests.

```APIDOC
## get() / post()

### Description
Convenience wrappers around `fetch()` for GET and POST requests.

### Method
- `get()`: GET
- `post()`: POST

### Endpoint
Any URL (as specified in the `url` argument)

### Parameters
Same as `fetch()` but with `method` preset to GET or POST respectively.

### Request Example
```typescript
const response = await get('https://example.com');
const postResponse = await post('https://example.com', { body: 'data' });
```

### Response
Returns a `Response` object.
```

--------------------------------

### Constructor style WebSocket example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/websocket.mdx

Constructor style example using the WebSocket class with browser and proxy options. Uses addEventListener for open and close events.

```typescript
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);
});
```

--------------------------------

### Install Xcode Command Line Tools on macOS

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Run this command in Terminal to install the Xcode Command Line Tools, which are required for building on macOS.

```bash
xcode-select --install
```

--------------------------------

### Import convenience helpers: get, post, request

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/fetch.mdx

Imports the convenience helpers from wreq-js. The `get` and `post` helpers wrap fetch with preset methods, while `request` is deprecated and kept for compatibility.

```typescript
import { get, post, request } from 'wreq-js';
```

--------------------------------

### getProfiles() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Example of using getProfiles() to retrieve and log available browser profiles.

```typescript
import { getProfiles } from 'wreq-js';

const profiles = getProfiles();
console.log(profiles);
// Example output: ['chrome_142', 'firefox_139', 'safari_18', ...]
```

--------------------------------

### Commit message examples

Source: https://github.com/sqdshguy/wreq-js/blob/master/CONTRIBUTING.md

Examples of commit messages following Conventional Commits, including a breaking change example with a BREAKING CHANGE footer.

```bash
# Feature
feat(request): add support for HTTP/3

# Bug fix
fix(loader): resolve platform detection on Alpine Linux

# Documentation
docs(readme): add installation instructions for pnpm

# Breaking change
feat(api)!: change request signature to accept options object

BREAKING CHANGE: request() now requires an options object instead of positional arguments
```

--------------------------------

### Combining browser and OS

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Example of combining browser and OS options in fetch calls for different platforms.

```typescript
import { fetch, getProfiles, getOperatingSystems } from 'wreq-js';

// Chrome on Windows
const response = await fetch('https://example.com', {
  browser: 'chrome_142',
  os: 'windows',
});

// Safari on iOS
const mobileResponse = await fetch('https://example.com', {
  browser: 'safari_18',
  os: 'ios',
});
```

--------------------------------

### Run Tests

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Runs the test runner, starts a local test server, and executes the test suite.

```bash
npm test

```

--------------------------------

### resolveProfile() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Example usage of resolveProfile, showing that aliases resolve to concrete profiles and concrete profiles pass through unchanged.

```typescript
import { resolveProfile } from 'wreq-js';

resolveProfile('firefox');     // 'firefox_149'
resolveProfile('firefox_143'); // 'firefox_143'
```

--------------------------------

### Basic GET request with fetch

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/fetch.mdx

Performs a GET request using the fetch function from wreq-js. The `browser` option specifies the browser fingerprint to use.

```typescript
import { fetch } from 'wreq-js';

const response = await fetch('https://api.example.com/data', {
  browser: 'chrome_142',
});

const data = await response.json();
```

--------------------------------

### Preset + overlay: fetch(), createSession(), createTransport()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/custom-emulation.md

Starts from a real browser profile and overlays custom emulation fields. Headers are merged, TLS/HTTP options are replaced at sub-object level. Shows usage with fetch(), createSession(), and createTransport().

```typescript
import { fetch, createSession, createTransport } from "wreq-js";

// With fetch()
const response = await fetch("https://example.com", {
  browser: "chrome_145",
  os: "macos",
  emulation: {
    tlsOptions: {
      permuteExtensions: false,  // disable random extension shuffling
    },
    headers: {
      "X-Custom": "overlay-value",
    },
  },
});

// With createSession()
const session = createSession({
  browser: "firefox_146",
  os: "linux",
  emulation: {
    http2Options: {
      initialWindowSize: 131072,
    },
  },
});

// With createTransport()
const transport = createTransport({
  browser: "chrome_145",
  emulation: {
    tlsOptions: {
      sessionTicket: false,
    },
  },
});

const response2 = await fetch("https://example.com", { transport });
```

--------------------------------

### Create WebSocket with constructor for CONNECTING behavior

Source: https://github.com/sqdshguy/wreq-js/blob/master/README.md

Use the WebSocket constructor if you want browser-like CONNECTING behaviour. The example shows setting onopen to send a message once connected.

```TypeScript
import { WebSocket } from 'wreq-js';

const ws = new WebSocket('wss://example.com/ws', { browser: 'chrome_149' });
ws.onopen = () => ws.send('connected');
```

--------------------------------

### Fetch with browser and OS options

Source: https://github.com/sqdshguy/wreq-js/blob/master/README.md

Use the fetch function from wreq-js to make a request with a specified browser and OS to mimic a real browser's TLS fingerprint. The example logs the JSON response.

```TypeScript
import { fetch } from 'wreq-js';

const res = await fetch('https://example.com/api', {
  browser: 'chrome_149',
  os: 'windows',
});

console.log(await res.json());
```

--------------------------------

### Event model example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/guides/websockets.mdx

Event handlers and listeners follow familiar WebSocket patterns. The example shows onmessage, onclose, and addEventListener for error events.

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

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

ws.onclose = (event) => {
  console.log(event.code, event.reason, event.wasClean);
};

ws.addEventListener('error', () => {
  console.error('error');
});
```

--------------------------------

### Binary payload mode example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/websocket.mdx

Shows how to set binaryType to 'arraybuffer' and handle binary messages as ArrayBuffer instances.

```typescript
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);
  }
};
```

--------------------------------

### withSession example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Uses withSession to perform a login and data fetch, with the session automatically closed after the callback returns.

```typescript
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);
```

--------------------------------

### Reusing a profile's User-Agent

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Example showing how to read a profile's user-agent and pass it as a custom header while keeping the rest of the fingerprint intact.

```typescript
import { fetch, getEmulationHeaders } from 'wreq-js';

const userAgent = getEmulationHeaders('firefox_147', 'windows').get('user-agent');

const response = await fetch('https://example.com', {
  browser: 'firefox_147',
  os: 'windows',
  headers: { 'X-Forwarded-User-Agent': userAgent ?? '' },
});
```

--------------------------------

### Using a random profile

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Example of selecting a random browser profile and using it with the fetch function.

```typescript
import { fetch, getProfiles } from 'wreq-js';

const profiles = getProfiles();
const randomProfile = profiles[Math.floor(Math.random() * profiles.length)];

const response = await fetch('https://example.com', {
  browser: randomProfile,
});
```

--------------------------------

### Connect to WebSocket with websocket() helper

Source: https://github.com/sqdshguy/wreq-js/blob/master/README.md

One await gets you a connected socket. The websocket function accepts a URL and options including browser and headers. The returned socket supports onmessage, send, and close.

```TypeScript
import { websocket } from 'wreq-js';

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

ws.onmessage = (event) => console.log(event.data);
ws.send('hello');
ws.close(1000, 'done');
```

--------------------------------

### Proxy rotation with random selection

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/guides/proxy-usage.mdx

Rotate through a list of proxies for each request. The example defines a list of proxies and a function to pick one randomly, then makes 10 requests each using a random proxy.

```typescript
import { fetch } from 'wreq-js';

const proxies = [
  'http://user:pass@proxy-1.example.com:8080',
  'http://user:pass@proxy-2.example.com:8080',
  'http://user:pass@proxy-3.example.com:8080',
];

function getRandomProxy() {
  return proxies[Math.floor(Math.random() * proxies.length)];
}

// Each request uses a random proxy
for (let i = 0; i < 10; i++) {
  const response = await fetch('https://example.com', {
    browser: 'chrome_142',
    proxy: getRandomProxy(),
  });
  console.log(`Request ${i + 1}: ${response.status}`);
}
```

--------------------------------

### getEmulationHeaders()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Gets the headers a browser profile injects into every request, without sending one. Both arguments default to the same profile and OS as fetch.

```APIDOC
## getEmulationHeaders()

### Description
Gets the headers a browser profile injects into every request, without sending one. Both arguments default to the same profile and OS as `fetch`.

### Signature
```typescript
function getEmulationHeaders(browser?: BrowserProfile, os?: EmulationOS): Headers
```

### Parameters
- **browser** (BrowserProfile) - Optional - The browser profile to use. Defaults to the same profile as `fetch`.
- **os** (EmulationOS) - Optional - The operating system to emulate. Defaults to the same OS as `fetch`.

### Returns
- **Headers** - A `Headers` instance holding the profile's headers, in the profile's own order and casing. Transport-level headers are not included: `Host`, `Connection`, `Content-Length`, and `Accept-Encoding` are added per request rather than by the emulation profile.

### Example
```typescript
import { getEmulationHeaders } from 'wreq-js';

const defaults = getEmulationHeaders('firefox_147');
console.log(defaults.get('user-agent'));
// Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:147.0) Gecko/20100101 Firefox/147.0
```

### Reusing a profile's User-Agent
Passing a header through `headers` replaces the profile's matching header and leaves the rest of the fingerprint intact, so read the value first when you want to build on it.

```typescript
import { fetch, getEmulationHeaders } from 'wreq-js';

const userAgent = getEmulationHeaders('firefox_147', 'windows').get('user-agent');

const response = await fetch('https://example.com', {
  browser: 'firefox_147',
  os: 'windows',
  headers: { 'X-Forwarded-User-Agent': userAgent ?? '' },
});
```
```

--------------------------------

### Import all wreq-js exports

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/overview.mdx

Imports the core functions, utilities, classes, and errors from the wreq-js package. Use this as a starting point for any project using wreq-js.

```typescript
import {
  // Core functions
  fetch,
  request,
  get,
  post,
  createTransport,
  createSession,
  withSession,
  websocket,
  
  // Utilities
  getProfiles,
  getOperatingSystems,
  getEmulationHeaders,
  resolveProfile,
  
  // Classes
  Headers,
  Response,
  Transport,
  Session,
  WebSocket,
  
  // Errors
  RequestError,
} from 'wreq-js';
```

--------------------------------

### session.fetch() request example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Makes a request using the session context. Per-request options override session defaults. Accepts request-scoped onRequestEvent and captureDiagnostics options from fetch(); when diagnostics are enabled, inspect response.diagnostics on the returned response.

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

--------------------------------

### Progress example using onRequestEvent switch

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/guides/request-events.mdx

Handle different request event types to render transport-phase progress. The switch covers request_start, request_sent, response_headers, body_progress, body_complete, and error. For body_progress, it calculates and logs the download percentage when contentLength is available.

```typescript
const response = await fetch('https://example.com/file.zip', {
  browser: 'chrome_142',
  onRequestEvent(event) {
    switch (event.type) {
      case 'request_start':
        console.log('connecting');
        break;
      case 'request_sent':
        console.log('waiting');
        break;
      case 'response_headers':
        console.log('status:', event.status);
        break;
      case 'body_progress':
        if (event.contentLength) {
          const downloaded = event.downloadedBytes ?? 0;
          const pct = (downloaded / event.contentLength) * 100;
          console.log(`loading ${pct.toFixed(1)}%`);
        }
        break;
      case 'body_complete':
        console.log('download complete');
        break;
      case 'error':
        console.error(event.message);
        break;
    }
  },
});

console.log(await response.arrayBuffer());
```

--------------------------------

### Key benchmark options

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BENCHMARK.md

Shows how to set duration, samples, warmup, and concurrency for the benchmark run.

```bash
npm run bench:run -- --duration-ms 2000 --samples 15 --warmup 3 --concurrency 32

```

--------------------------------

### Transport-level request progress with onRequestEvent

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/guides/streaming.mdx

Uses onRequestEvent to get progress before consuming response.body. Logs request start, headers, and body download progress.

```typescript
const response = await fetch('https://example.com/file.zip', {
  browser: 'chrome_142',
  onRequestEvent(event) {
    switch (event.type) {
      case 'request_start':
        console.log('connecting');
        break;
      case 'request_sent':
        console.log('waiting for response');
        break;
      case 'response_headers':
        console.log('status:', event.status);
        console.log('length:', event.contentLength);
        break;
      case 'body_progress':
        if (event.contentLength) {
          const pct = ((event.downloadedBytes ?? 0) / event.contentLength) * 100;
          console.log(`downloaded ${pct.toFixed(1)}%`);
        }
        break;
      case 'body_complete':
        console.log('download complete');
        break;
    }
  },
});

console.log(await response.arrayBuffer());
```

--------------------------------

### Session-based WebSocket with authentication

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/guides/websockets.mdx

Create a session, log in with HTTP, then open a WebSocket using the same session. session.websocket() reuses the session transport and context. The example shows sending a JSON message and closing with a code and reason.

```typescript
import { createSession } from 'wreq-js';

const session = await createSession({
  browser: 'chrome_142',
  os: 'windows',
  proxy: 'http://proxy.example.com:8080',
});

try {
  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', {
    headers: {
      'X-Client': 'dashboard',
    },
  });

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

  void ws.send(JSON.stringify({ type: 'subscribe', channel: 'updates' }));
  ws.close(1000, 'done');
} finally {
  await session.close();
}
```

--------------------------------

### session.websocket() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Opens a WebSocket that reuses the session transport and context. Use after login or any other HTTP flow that sets cookies. Accepts headers, protocols, and binaryType; 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.

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

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

ws.close();
```

--------------------------------

### session.getAllCookies() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Returns every cookie currently stored in the session jar, regardless of URL matching. Returns SessionCookie[] with scope metadata such as domain, path, sameSite, and expiresAtMs when available.

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

--------------------------------

### Layer custom emulation overrides on a preset

Source: https://github.com/sqdshguy/wreq-js/blob/master/README.md

When a preset gets you close but a specific target is picky, layer overrides on top of it. Anything you do not specify keeps the profile's value. This example overrides http2Options with headerTableSize, initialWindowSize, and headersPseudoOrder.

```TypeScript
const res = await fetch('https://example.com', {
  browser: 'chrome_149',
  emulation: {
    http2Options: {
      headerTableSize: 65536,
      initialWindowSize: 6291456,
      headersPseudoOrder: ['Method', 'Authority', 'Scheme', 'Path'],
    },
  },
});
```

--------------------------------

### Use a family alias and resolveProfile()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/concepts/browser-profiles.mdx

Passes a family alias like 'firefox' to fetch, and uses resolveProfile() to get the concrete profile it resolves to (e.g., 'firefox_149'). Aliases resolve to the newest profile in the family.

```typescript
import { fetch, resolveProfile } from 'wreq-js';

const response = await fetch('https://example.com', {
  browser: 'firefox',
});

resolveProfile('firefox'); // 'firefox_149'
```

--------------------------------

### Build the project

Source: https://github.com/sqdshguy/wreq-js/blob/master/CONTRIBUTING.md

Run npm run build to compile the project.

```bash
npm run build
```

--------------------------------

### Build and run benchmark

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BENCHMARK.md

Builds the project and runs the benchmark suite.

```bash
npm run bench

```

--------------------------------

### session.getCookies() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Returns cookies that would be sent to the given URL using RFC 6265 domain/path matching. Only cookies whose domain and path match the URL are returned. Returns Record<string, string> of cookie name/value pairs.

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

--------------------------------

### Test naming examples

Source: https://github.com/sqdshguy/wreq-js/blob/master/CONTRIBUTING.md

Examples of good and bad test names in TypeScript.

```typescript
// Good
test('should load correct binary for macOS ARM64', () => {
  // ...
});

// Bad
test('test1', () => {
  // ...
});
```

--------------------------------

### Using Headers with fetch

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Shows how to create a Headers instance, set headers, and pass it to fetch with a browser option.

```typescript
import { fetch, Headers } from 'wreq-js';

const headers = new Headers();
headers.set('Authorization', 'Bearer token');
headers.set('Content-Type', 'application/json');

const response = await fetch('https://api.example.com', {
  browser: 'chrome_142',
  headers,
});
```

--------------------------------

### getOperatingSystems()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/utilities.mdx

Returns a list of all available operating systems for emulation that can be used with the 'os' option.

```APIDOC
## getOperatingSystems()

### Description
Get a list of all available operating systems for emulation.

### Signature
```typescript
function getOperatingSystems(): EmulationOS[]
```

### Returns
Array of OS names that can be used with the `os` option.

### Example
```typescript
import { getOperatingSystems } from 'wreq-js';

const systems = getOperatingSystems();
console.log(systems);
// Example output: ['windows', 'macos', 'linux', 'android', 'ios']
```

### Combining browser and OS
```typescript
import { fetch, getProfiles, getOperatingSystems } from 'wreq-js';

// Chrome on Windows
const response = await fetch('https://example.com', {
  browser: 'chrome_142',
  os: 'windows',
});

// Safari on iOS
const mobileResponse = await fetch('https://example.com', {
  browser: 'safari_18',
  os: 'ios',
});
```
```

--------------------------------

### Run benchmark (assumes built)

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BENCHMARK.md

Runs the benchmark suite assuming dist/ and native addon are already built.

```bash
npm run bench:run

```

--------------------------------

### List operating systems with getOperatingSystems()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/concepts/browser-profiles.mdx

Imports getOperatingSystems from 'wreq-js' and logs the array of OS labels: ['windows', 'macos', 'linux', 'android', 'ios'].

```typescript
import { getOperatingSystems } from 'wreq-js';

console.log(getOperatingSystems());
// ['windows', 'macos', 'linux', 'android', 'ios']
```

--------------------------------

### fetch(input, init?)

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/fetch.mdx

Makes an HTTP request with the given input and optional configuration. Supports browser emulation, proxy, timeout, and request lifecycle events.

```APIDOC
## fetch(input, init?)

### Description
Makes an HTTP request with the given input and optional configuration. Supports browser emulation, proxy, timeout, and request lifecycle events.

### Signature
```typescript
function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>
```

### Parameters
- **input** (string | URL | Request) - Required - The resource to fetch. Can be a URL string, URL object, or a Request object.
- **init** (RequestInit) - Optional - Optional request configuration.

### RequestInit options
- **method** (string) - Optional, default: `GET` - HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`.
- **headers** (HeadersInit) - Optional - Request headers. Can be a `Headers` object, plain object, or array of key-value pairs.
- **body** (BodyInit | null) - Optional - Request body. Supported types: `string`, `Buffer`, `URLSearchParams`, `ArrayBuffer`, `ArrayBufferView` (for example `Uint8Array`), `Blob`, `FormData`, `ReadableStream<Uint8Array>`, and any sync or async iterable of `Uint8Array`. Stream and iterable bodies are read fully into memory before the request is sent, so an unbounded stream means an unbounded allocation.
- **transport** (Transport) - Optional - Reusable transport context for this request (proxy + emulation settings, with connection behavior handled by the native layer). When provided, you must not also set `browser`, `os`, `proxy`, or `insecure`.
- **browser** (BrowserProfile | BrowserAlias) - Optional, default: `chrome` - Browser fingerprint profile to use (e.g., `'chrome_142'`, `'firefox_139'`), or a family alias such as `'firefox'` that resolves to the newest profile in that family. See [browser profiles](/concepts/browser-profiles#family-aliases).
- **os** (EmulationOS) - Optional - Operating system to emulate: `'windows'`, `'macos'`, `'linux'`, `'android'`, `'ios'`.
- **proxy** (string) - Optional - Proxy URL. Support depends on the native layer and proxy scheme.
- **timeout** (number) - Optional, default: `30000` - Request timeout in milliseconds. Set to `0` to disable the timeout.
- **signal** (AbortSignal) - Optional - AbortSignal for cancelling the request.
- **redirect** ('follow' | 'manual' | 'error') - Optional, default: `follow` - Redirect handling mode.
- **disableDefaultHeaders** (boolean) - Optional, default: `false` - When `true`, prevents browser emulation headers from being automatically added.
- **insecure** (boolean) - Optional, default: `false` - When `true`, accepts invalid/self-signed certificates. **Use only in development.**
- **onRequestEvent** ((event: RequestEvent) => void) - Optional - Optional callback for structured request lifecycle events emitted by the native layer. Use this to observe phases such as request start, response headers, and body download progress.
- **captureDiagnostics** (boolean) - Optional, default: `false` - When `true`, captures a final diagnostics payload on the response where supported by the native layer. This can include timing, address, and TLS peer details.

### Returns
- **Promise<Response>** - A promise that resolves to a Response object.
```

--------------------------------

### Using a transport with fetch()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/transport.mdx

Shows how to pass a transport to fetch() via RequestInit.transport, and notes that certain request options become invalid when a transport is provided.

```APIDOC
## Using a transport with fetch()

### Description
Pass the transport via `RequestInit.transport` to use the transport's settings for the request. When a transport is provided, you must not also set `browser`, `os`, `proxy`, or `insecure` on that request.

### Example
```typescript
import { createTransport, fetch } from "wreq-js";

const transport = await createTransport({
  proxy: "http://user:pass@proxy.example.com:8080",
  browser: "chrome_142",
  poolMaxSize: 64,
});

try {
  const res = await fetch("https://httpbin.org/get", {
    transport,
    timeout: 10_000,
  });

  console.log(res.status);
} finally {
  await transport.close();
}
```

### Notes
- You can still pass per-request `onRequestEvent` callbacks when using a transport.
- If `captureDiagnostics` is enabled on the transport, returned responses expose `response.diagnostics` without having to repeat the flag on every request.
- When you provide `transport`, you must not also set `browser`, `os`, `proxy`, or `insecure` on that request.
```

--------------------------------

### Build native addon and run tests

Source: https://github.com/sqdshguy/wreq-js/blob/master/CONTRIBUTING.md

Run npm run test:build to build the native addon and then run tests. Use this if you changed Rust code or need a fresh addon.

```bash
npm run test:build
```

--------------------------------

### session.clearCookies() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Clears all cookies from the session cookie jar.

```typescript
await session.clearCookies();
```

--------------------------------

### session.close() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Closes the session and releases resources. Always call this when done.

```typescript
await session.close();
```

--------------------------------

### Check formatting and linting

Source: https://github.com/sqdshguy/wreq-js/blob/master/CONTRIBUTING.md

Run npm run check to check formatting and linting with Biome.

```bash
npm run check
```

--------------------------------

### Build Rust addon (npm run build:rust)

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Run this command to build the Rust addon when you encounter 'Cannot find module 'wreq-js.*.node''. This error indicates the addon wasn't built.

```bash
npm run build:rust
```

--------------------------------

### transport.close() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/transport.mdx

Closes a transport. After closing, transport.closed becomes true and the transport can no longer be used.

```typescript
await transport.close();
```

--------------------------------

### Clean slate rebuild

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Run these commands to clean and rebuild the project from scratch, removing node_modules and package-lock.json before reinstalling and building.

```bash
npm run clean
rm -rf node_modules package-lock.json
npm install
npm run build
```

--------------------------------

### Clean Build Commands

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Remove build artifacts and rebuild from scratch.

```bash
npm run clean    # removes dist/, rust/target/, rust/*.node
npm run build

```

--------------------------------

### Binary messages with binaryType

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/guides/websockets.mdx

binaryType defaults to 'nodebuffer'. Set it to 'arraybuffer' or 'blob'. The example shows handling ArrayBuffer and Buffer data.

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

ws.binaryType = 'arraybuffer';

ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    console.log('ArrayBuffer bytes:', event.data.byteLength);
    return;
  }

  if (Buffer.isBuffer(event.data)) {
    console.log('Buffer bytes:', event.data.byteLength);
    return;
  }

  console.log('Text:', event.data);
};
```

```typescript
ws.binaryType = 'blob';
```

--------------------------------

### post(url, body?, init?)

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/fetch.mdx

Convenience helper that performs a POST request by calling fetch with method set to 'POST' and the provided body.

```APIDOC
## post(url, body?, init?)

### Description
Convenience helper that calls `fetch(url, { ...init, method: "POST", body })`. Useful for making POST requests with a body.

### Method
POST

### Endpoint
Any URL (passed as first argument)

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to request.

#### Request Body (optional)
- **body** (any) - Optional - The request body (string, URLSearchParams, etc.).
- **init** (object) - Optional - Same options as fetch, except method is forced to 'POST' and body is set.

### Request Example
```typescript
import { post } from 'wreq-js';
const response = await post('https://api.example.com/submit', JSON.stringify({ name: 'John' }), {
  headers: { 'Content-Type': 'application/json' },
});
```

### Response
#### Success Response (200)
- **response** (Response) - The standard Response object.

#### Response Example
```typescript
const data = await response.json();
```
```

--------------------------------

### session.setCookie() example

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/sessions.mdx

Adds a cookie to the session jar, scoped to the domain/path of the given URL. The URL determines the cookie's domain and path scope.

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

--------------------------------

### RequestInit interface with wreq-js extensions

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/overview.mdx

Defines the RequestInit interface, showing standard Fetch options and wreq-js extensions like transport, browser, os, proxy, timeout, session, and cookieMode.

```typescript
interface RequestInit {
  // Standard options
  method?: string;
  headers?: HeadersInit;
  body?: BodyInit | null;
  signal?: AbortSignal | null;
  redirect?: 'follow' | 'manual' | 'error';

  // wreq-js extensions
  transport?: Transport;         // Reusable transport (pool/proxy/browser/os)
  browser?: BrowserProfile;      // Browser fingerprint profile
  os?: EmulationOS;              // Operating system emulation
  proxy?: string;                // Proxy URL
  timeout?: number;              // Request timeout in ms
  session?: Session;             // Bind to an existing session
  sessionId?: string;            // Bind to a session by ID
  cookieMode?: 'session' | 'ephemeral'; // Cookie scoping strategy
  disableDefaultHeaders?: boolean; // Disable auto-added headers
  insecure?: boolean;            // Accept invalid certificates
}
```

--------------------------------

### Standalone custom: fetch(), createSession(), createTransport()

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/custom-emulation.md

No browser or OS is set; you supply the entire fingerprint. At least one of tlsOptions, http1Options, http2Options, headers, or origHeaders must be present. Shows usage with fetch(), createSession(), and createTransport().

```typescript
import { fetch, createSession, createTransport } from "wreq-js";

// With fetch()
const response = await fetch("https://example.com", {
  emulation: {
    tlsOptions: {
      alpnProtocols: ["HTTP2"],
      minTlsVersion: "1.2",
      sessionTicket: true,
    },
    http2Options: {
      initialWindowSize: 65535,
      headersPseudoOrder: ["Method", "Authority", "Scheme", "Path"],
    },
    headers: {
      "User-Agent": "MyCustomAgent/1.0",
      "Accept": "text/html",
    },
    origHeaders: ["User-Agent", "Accept"],
  },
});

// With createSession()
const session = createSession({
  emulation: {
    headers: {
      "User-Agent": "Standalone Agent/1.0",
    },
  },
});

// With createTransport()
const transport = createTransport({
  emulation: {
    tlsOptions: {
      alpnProtocols: ["HTTP2"],
      cipherList: "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384",
    },
    http2Options: {
      settingsOrder: ["HeaderTableSize", "EnablePush", "InitialWindowSize", "MaxFrameSize"],
    },
  },
});
```

--------------------------------

### Thousands of proxies: recommended pattern

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/transport.mdx

Recommended pattern for managing many proxies: create one transport per proxy, reuse it, and close it when no longer needed.

```APIDOC
## Thousands of proxies: recommended pattern

### Description
Create **one transport per proxy**, reuse it for all requests that should go through that proxy, and close transports when you no longer need them.

### Example
```typescript
import { createTransport, fetch, type Transport } from "wreq-js";

const transports = new Map<string, Transport>();

async function getTransportForProxy(proxy: string): Promise<Transport> {
  const cached = transports.get(proxy);
  if (cached && !cached.closed) return cached;

  const transport = await createTransport({ proxy, poolMaxSize: 32 });
  transports.set(proxy, transport);
  return transport;
}

export async function fetchViaProxy(url: string, proxy: string) {
  const transport = await getTransportForProxy(proxy);
  return fetch(url, { transport, timeout: 30_000 });
}

export async function shutdown() {
  await Promise.all([...transports.values()].map((t) => t.close()));
  transports.clear();
}
```
```

--------------------------------

### Set multiple cookies with different URLs

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/concepts/sessions.mdx

Shows how to set cookies with different URLs when host-only cookies come from multiple hosts. Each cookie gets its own url.

```typescript
restored.setCookies([
  { name: 'session_id', value: 'abc123', url: 'https://example.com' },
  { name: 'consent', value: 'yes', url: 'https://cdn.other.test' },
]);
```

--------------------------------

### Read cookies for a URL

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/concepts/sessions.mdx

Uses getCookies(url) to inspect which cookies would be sent to a URL. The example shows a POST request followed by reading cookies and logging them.

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

const cookies = session.getCookies('https://example.com');
console.log(cookies);
// { "session_id": "abc123", "csrf": "xyz" }
```

--------------------------------

### Run tests

Source: https://github.com/sqdshguy/wreq-js/blob/master/CONTRIBUTING.md

Run npm test to execute tests. Assumes the native addon is already built.

```bash
npm test
```

--------------------------------

### new WebSocket(url, protocols?, options?)

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/api-reference/websocket.mdx

Constructor-style WebSocket for browser-like ergonomics. Supports multiple overloads for protocols and options.

```APIDOC
## new WebSocket(url, protocols?, options?)

### Description
Constructor-style WebSocket for browser-like ergonomics. Supports multiple overloads for protocols and options.

### Constructor Overloads
```typescript
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);
}
```

### Parameters
- **url** (string | URL) - Required - The WebSocket server URL.
- **protocols** (string | string[]) - Optional - Subprotocol list.
- **options** (WebSocketOptions) - Optional - Configuration options (same as `websocket()`).

### Example
```typescript
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);
});
```

```

--------------------------------

### Individual Build Commands

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/BUILD.md

Build only the Rust or TypeScript parts separately.

```bash
# Rust only
npm run build:rust

# TypeScript only
npm run build:ts

```

--------------------------------

### Create session with options

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/concepts/sessions.mdx

Creates a session with browser, os, proxy, and insecure options. The browser and os are fixed at creation time unless overridden per request.

```typescript
const session = await createSession({
  browser: 'chrome_142',
  os: 'windows',
  proxy: 'http://proxy.example.com:8080',
  insecure: false,
});
```

--------------------------------

### Emulate Windows Chrome with os option

Source: https://github.com/sqdshguy/wreq-js/blob/master/docs/concepts/browser-profiles.mdx

Sets both 'browser' and 'os' options in a fetch call to emulate Windows Chrome.

```typescript
const response = await fetch('https://example.com', {
  browser: 'chrome_142',
  os: 'windows',
});
```
Tokens:
Raw