wreq-js 0.2.0 → 1.1.0

package/README.md

@@ -1,260 +1,202 @@
 # wreq-js
 
-High-performance Node.js bindings for the Rust-based wreq HTTP client with native TLS and HTTP/2 browser impersonation.
+High-performance HTTP client for Node.JS with real-browser TLS and HTTP/2 fingerprints, powered by Rust.
 
-Note: This is a personal fork of [will-work-for-meal/node-wreq](https://github.com/will-work-for-meal/node-wreq) (originally named node-wreq) with ongoing maintenance and faster dependency updates.
+- ⚡️ A modern, actively maintained alternative to outdated browser-impersonating clients and legacy wrappers.  
+- When it comes to web scraping and automation, keeping up with the latest developments is NOT optional. Detection systems like Akamai and Cloudflare change every day using machine learning, old fingerprints are quickly detected.
+- `wreq-js` builds upon the Rust-based [`wreq`](https://github.com/0x676e67/wreq) engine to deliver drop-in Node.js bindings that feel like `fetch()` but behave like a real browser.
 
-## Features
-
-- Native performance (no process spawning)
-- TLS fingerprinting (JA3/JA4) aligned with real browsers
-- HTTP/2 fingerprinting: SETTINGS, PRIORITY, and header ordering
-- Multiple browser profiles (Chrome, Firefox, Safari, Edge, Opera, OkHttp)
-- WebSocket support
-- TypeScript definitions included
-
-## How It Works
-
-The library provides Node.js bindings over [wreq](https://github.com/0x676e67/wreq), a Rust HTTP client that uses BoringSSL to replicate browser network behavior at the TLS and HTTP/2 layers.
-
-### Why It Works
+> This is my maintained fork of [will-work-for-meal/node-wreq](https://github.com/will-work-for-meal/node-wreq), originally named `node-wreq`, with ongoing updates and dependency refreshes for compatibility and speed.
 
-Traditional HTTP clients (axios, fetch, curl) have differences in:
-- **TLS handshake signatures** — Different cipher suites and extensions
-- **HTTP/2 frame ordering** — Different SETTINGS and PRIORITY patterns
-- **Header ordering** — Different sequence and values
-
-This library reproduces browser network behavior with high fidelity.
-
-### Browser Profiles and wreq-util
+## Features
 
-- Browser profiles are generally tracked in the upstream `wreq-util` project; we depend on it for compatibility and support.
-- Profiles in this package are available in `src/generated-types.ts` and are automatically generated from the `wreq-util` codebase to improve update speed and reduce maintenance overhead.
-- Use `getProfiles()` to query the current set of supported profiles programmatically.
+- **Native performance** — no process spawning or browser overhead  
+- **Real browser TLS fingerprints** (JA3/JA4)  
+- **HTTP/2 impersonation** — replicates SETTINGS, PRIORITY, and header ordering  
+- **Multiple browser profiles** — Chrome, Firefox, Safari, Edge, Opera, OkHttp  
+- **WebSocket support** with browser fingerprint consistency  
+- **Prebuilt native binaries** for macOS, Linux, and Windows  
+- **TypeScript-ready** with generated definitions
 
 ## Installation
 
 ```bash
-# From GitHub (this fork)
-# Latest master branch
 npm install wreq-js
+# or
 yarn add wreq-js
 pnpm add wreq-js
 bun add wreq-js
-
-# From npm registry (original repo as node-wreq)
-npm install node-wreq
-yarn add node-wreq
-pnpm add node-wreq
-bun add node-wreq
 ```
 
-Pre-built native modules are included for major platforms:
-- macOS (Intel and Apple Silicon)
-- Linux (x64 and ARM64)
+Prebuilt binaries are provided for:
+- macOS (Intel & Apple Silicon)
+- Linux (x64 & ARM64)
 - Windows (x64)
 
-Note on GitHub installs: if a matching prebuilt binary is not available for the referenced tag/commit, installation may build from source. Ensure a Rust toolchain and platform build prerequisites are installed.
+> ⚠️ If a prebuilt binary for your platform or commit is unavailable, the package will build from source.  
+> Make sure a Rust toolchain and required build dependencies are installed.
 
-## Usage
+## Why It Exists
+
+HTTP clients like `axios`, `fetch`, `got`, `curl`  do not behave like browsers on the network layer.  
+They differ in:
+
+- **TLS handshake** - unique cipher suite order and extension sets  
+- **HTTP/2 frames** - different SETTINGS and PRIORITY sequences  
+- **Header ordering** - deterministic but non-browser-compliant  
+
+These subtle differences are enough for modern detection systems to identify automation.  
+`wreq-js` reproduces browser networking behavior using the `wreq` Rust engine underneath.  
+Your job is to write scripts, ours is to make them undetectable, yet effortless.
+
+## Architecture Overview
+
+`wreq-js` provides Node.js bindings over [`wreq`](https://github.com/0x676e67/wreq), a Rust HTTP client built on **BoringSSL** to emulate browser TLS and HTTP/2 stacks.  
+Browser profiles are defined in the upstream [`wreq-util`](https://github.com/0x676e67/wreq-util) project and automatically synchronized here for faster updates.
+
+To query supported profiles:
+
+```typescript
+import { getProfiles } from 'wreq-js';
+console.log(getProfiles());
+// ['chrome_142', 'firefox_139', 'edge_120', 'safari_18', ...]
+```
 
-### Basic Request
+## Quick Start
 
 ```typescript
-import { request } from 'wreq-js';
+import { fetch } from 'wreq-js';
 
-const response = await request({
-  url: 'https://example.com/api',
-  browser: 'chrome_137',
+const response = await fetch('https://example.com/api', {
+  browser: 'chrome_142',
 });
 
-console.log(response.status);  // 200
-console.log(response.body);    // Response body
-console.log(response.headers); // Response headers
-console.log(response.cookies); // Cookies
+console.log(await response.json());
 ```
 
-### With Custom Headers
+That’s it, you now have full browser impersonation, drop-in compatibility with the `fetch()` API.
+
+## Advanced Usage
+
+### Custom Headers
 
 ```typescript
-import { request } from 'wreq-js';
+import { fetch, Headers } from 'wreq-js';
 
-const response = await request({
-  url: 'https://api.example.com/data',
+const response = await fetch('https://api.example.com/data', {
   browser: 'firefox_139',
-  headers: {
-    'Authorization': 'Bearer token123',
+  headers: new Headers({
+    Authorization: 'Bearer token123',
     'Custom-Header': 'value',
+  }),
+});
+```
+
+By default, browser emulation headers (like `Accept`, `Accept-Language`, `User-Agent`, etc.) are automatically added and may be appended to your custom headers. To prevent this and use **only** your custom headers:
+
+```typescript
+const response = await fetch('https://api.example.com/data', {
+  browser: 'chrome_142',
+  headers: {
+    'Accept': '*/*',
+    'User-Agent': 'CustomBot/1.0',
   },
+  disableDefaultHeaders: true, // Disable emulation headers
 });
 ```
 
 ### POST Request
 
 ```typescript
-import { post } from 'wreq-js';
-
-const response = await post(
-  'https://api.example.com/submit',
-  JSON.stringify({ foo: 'bar' }),
-  {
-    browser: 'chrome_137',
-    headers: {
-      'Content-Type': 'application/json',
-    },
-  }
-);
+const res = await fetch('https://api.example.com/submit', {
+  method: 'POST',
+  browser: 'chrome_142',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ foo: 'bar' }),
+});
 ```
 
-### Convenience Methods
+## Session & Cookie Isolation
+
+Each `fetch()` call runs in **ephemeral mode** so that TLS caches, cookies, and session data never leak across requests.
+To persist state, use `createSession()` or `withSession()`:
 
 ```typescript
-import { get, post } from 'wreq-js';
+import { createSession, withSession } from 'wreq-js';
 
-// GET request
-const data = await get('https://api.example.com/users');
+const session = await createSession({ browser: 'chrome_142' });
+await session.fetch('https://example.com/login', { method: 'POST', body: '...' });
+await session.fetch('https://example.com/dashboard');
+await session.close();
 
-// POST request
-const result = await post(
-  'https://api.example.com/users',
-  JSON.stringify({ name: 'John' })
-);
-```
+// Auto-disposing helper
+await withSession(async (s) => {
+  await s.fetch('https://example.com/a');
+  await s.fetch('https://example.com/b');
+});
 
-### With Proxy
+For finer control:
 
 ```typescript
-import { request } from 'wreq-js';
-
-const response = await request({
-  url: 'https://example.com',
-  browser: 'chrome_137',
-  // proxy: 'http://proxy.example.com:8080',
-  // proxy: 'http://username:password@proxy.example.com:8080',
-  // proxy: 'socks5://proxy.example.com:1080',
+await fetch('https://example.com', {
+  sessionId: 'user-42',
+  cookieMode: 'session',
 });
 ```
 
-### WebSocket Connection
+## WebSocket Example
 
 ```typescript
 import { websocket } from 'wreq-js';
 
 const ws = await websocket({
   url: 'wss://echo.websocket.org',
-  browser: 'chrome_137',
-  onMessage: (data) => {
-    console.log('Received:', data);
-  },
-  onClose: () => {
-    console.log('Connection closed');
-  },
-  onError: (error) => {
-    console.error('Error:', error);
-  },
+  browser: 'chrome_142',
+  onMessage: (data) => console.log('Received:', data),
 });
 
-// Send text message
 await ws.send('Hello!');
-
-// Send binary message
-await ws.send(Buffer.from([1, 2, 3]));
-
-// Close connection
 await ws.close();
 ```
 
 ## API Reference
 
-### `request(options:` [`RequestOptions`](#requestoptions)`): Promise<`[`Response`](#response)`>`
-
-Main function for making HTTP requests with browser impersonation.
-
-**Options:**
-<a name="requestoptions"></a>
+The API is aiming to be `fetch`-compatible, with a few `wreq`-specific extensions.  
+See inline TypeScript definitions for complete typings.
 
 ```typescript
-interface RequestOptions {
-  url: string;                    // Required: URL to request
-  browser?: BrowserProfile;       // Default: 'chrome_137'
-  method?: HttpMethod;            // Default: 'GET'
-  headers?: Record<string, string>;
-  body?: string;
-  proxy?: string;                 // HTTP/HTTPS/SOCKS5 proxy URL
-  timeout?: number;               // Default: 30000ms
+interface RequestInit {
+  method?: string;
+  headers?: HeadersInit;
+  body?: BodyInit | null;
+  signal?: AbortSignal | null;
+  redirect?: 'follow';
+  browser?: BrowserProfile;
+  proxy?: string;
+  timeout?: number;
+  cookieMode?: 'session' | 'ephemeral';
+  session?: Session;
+  sessionId?: string;
+  disableDefaultHeaders?: boolean; // Prevent emulation headers from being appended
 }
 ```
 
-**Response:**
-<a name="response"></a>
-
-```typescript
-interface Response {
-  status: number;
-  headers: Record<string, string>;
-  body: string;
-  cookies: Record<string, string>;
-  url: string;  // Final URL after redirects
-}
-```
-
-### `get(url: string, options?): Promise<`[`Response`](#response)`>`
-
-### `post(url: string, body?: string, options?): Promise<`[`Response`](#response)`>`
-
-### `websocket(options:` [`WebSocketOptions`](#websocketoptions)`): Promise<WebSocket>`
-
-
-**Options:**
-<a name="websocketoptions"></a>
-
-```typescript
-interface WebSocketOptions {
-  url: string;                                  // Required: WebSocket URL (ws:// or wss://)
-  browser?: BrowserProfile;                     // Default: 'chrome_137'
-  headers?: Record<string, string>;
-  proxy?: string;                               // HTTP/HTTPS/SOCKS5 proxy URL
-  onMessage: (data: string | Buffer) => void;   // Required: Message callback
-  onClose?: () => void;                         // Optional: Close callback
-  onError?: (error: string) => void;            // Optional: Error callback
-}
-```
-
-**WebSocket Methods:**
-
-```typescript
-class WebSocket {
-  send(data: string | Buffer): Promise<void>;
-  close(): Promise<void>;
-}
-```
-
-### `getProfiles():` [`BrowserProfile[]`](#browser-profiles)
-
-Get list of available browser profiles.
-
-```typescript
-import { getProfiles } from 'wreq-js';
-
-const profiles = getProfiles();
-
-console.log(profiles);
-// ['chrome_100', 'chrome_101', ..., 'chrome_137', 'edge_101', ..., 'safari_18', ...]
-```
-
 ## Documentation
 
-- **[Architecture Guide](docs/ARCHITECTURE.md)** — Technical details about TLS/HTTP2 fingerprinting, how browser impersonation works
-- **[Build Instructions](docs/BUILD.md)** — Developer guide for building from source
-- **[Publishing Guide](docs/PUBLISHING.md)** — How to publish the package
+- **[Architecture Guide](docs/ARCHITECTURE.md)** - How fingerprinting and impersonation work  
+- **[Build Instructions](docs/BUILD.md)** - Build from source  
+- **[Publishing Guide](docs/PUBLISHING.md)** - Releasing new versions
 
 ## Contributing
 
 Please read the [Contributing Guide](CONTRIBUTING.md).
 
+## Origins
+This project began as a fork of [will-work-for-meal/node-wreq](https://github.com/will-work-for-meal/node-wreq) but has since evolved into an independent implementation with extensive rewrites, new APIs, and active maintenance. It is not affiliated with the original project.
+
 ## Acknowledgments
 
-- [wreq](https://github.com/0x676e67/wreq) — Rust HTTP client with browser impersonation
-- [wreq-util](https://github.com/0x676e67/wreq-util) — Upstream utility project that tracks and ships browser fingerprint updates rapidly
-- [Neon](https://neon-bindings.com/) — Rust ↔ Node.js bindings
-- Original Node.js wrapper: [will-work-for-meal/node-wreq](https://github.com/will-work-for-meal/node-wreq) (named node-wreq) — clean, well-written baseline this fork builds on
+- [wreq](https://github.com/0x676e67/wreq) - Rust HTTP client with browser impersonation  
+- [wreq-util](https://github.com/0x676e67/wreq-util) - Source of up-to-date browser profiles  
+- [Neon](https://neon-bindings.com/) - Rust ↔ Node.js bindings  
+- [will-work-for-meal/node-wreq](https://github.com/will-work-for-meal/node-wreq) - Original Node.js wrapper foundation

package/dist/test/helpers/local-test-server.d.ts

@@ -0,0 +1,7 @@
+export interface LocalTestServer {
+    httpBaseUrl: string;
+    wsUrl: string;
+    close(): Promise<void>;
+}
+export declare function startLocalTestServer(): Promise<LocalTestServer>;
+//# sourceMappingURL=local-test-server.d.ts.map

package/dist/test/helpers/local-test-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-test-server.d.ts","sourceRoot":"","sources":["../../../src/test/helpers/local-test-server.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,eAAe,CAAC,CA2MrE"}