wreq-js 1.7.0 → 2.0.0

package/README.md

@@ -4,27 +4,29 @@
 [![CI](https://github.com/sqdshguy/wreq-js/actions/workflows/test.yml/badge.svg)](https://github.com/sqdshguy/wreq-js/actions/workflows/test.yml)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/sqdshguy/wreq-js)
 
-Node.js/TypeScript HTTP client with browser TLS fingerprint impersonation (JA3/JA4). Bypass Cloudflare, DataDome, and other anti-bot TLS fingerprinting. Rust-powered via [wreq](https://github.com/0x676e67/wreq).
-
-- **Bypass anti-bot TLS detection** (Cloudflare, DataDome, Akamai, etc.)
-- Native Rust performance (no browser/process spawning)
-- Real browser TLS fingerprints (JA3/JA4)
-- HTTP/2 impersonation (SETTINGS/PRIORITY/header ordering)
-- Multiple browser profiles (Chrome/Firefox/Safari/Edge/Opera/OkHttp)
-- `fetch()`-compatible API with sessions, cookies, and proxies
-- WebSocket support with fingerprint consistency
-- Prebuilt native binaries for macOS/Linux/Windows
-- TypeScript-first with generated definitions
+`wreq-js` is a Node.js and TypeScript HTTP client that helps you bypass TLS fingerprinting checks used by services like Cloudflare and DataDome, powered by native Rust bindings from [wreq](https://github.com/0x676e67/wreq).
+
+If your requests work in a browser but get blocked from Node.js because your network fingerprint looks wrong, this is for you.
+You keep a fetch style API and get browser profile level network behavior without running a full browser.
+
+1. Built in browser TLS and HTTP fingerprint profiles across Chrome, Firefox, Safari, Edge, Opera, and OkHttp families
+2. Native Rust engine for high throughput traffic with no browser process overhead
+3. Fetch style API with sessions, cookies, proxies, and transport controls
+4. WebSocket helper and constructor APIs with session cookie and transport reuse
+5. TypeScript first developer experience with generated definitions
+6. Native targets for macOS, Linux, and Windows
+
+Common search terms: cloudflare bypass, datadome bypass, tls fingerprinting, ja3, ja4, browser impersonation, nodejs fetch, typescript http client.
 
 ## Alternatives comparison
 
-| Library | Approach | Maintained | API | Performance | Fingerprint profiles |
-|---------|----------|:----------:|-----|:-----------:|:--------------------:|
-| **wreq-js** | Rust native bindings ([wreq](https://github.com/0x676e67/wreq)) | Yes | `fetch()`-compatible, TypeScript-first | Native Rust, no subprocess overhead | Built-in, kept current via [wreq-util](https://github.com/0x676e67/wreq-util) |
-| [CycleTLS](https://github.com/Danny-Dasilva/CycleTLS) | Go subprocess | Sporadic | Promise-based | IPC overhead (Go subprocess) | BYO (manual JA3 strings) |
-| [got-scraping](https://github.com/apify/got-scraping) | Pure JS header tweaking | Yes | `got`-based | JS-only, no real TLS spoofing | N/A (header-level only) |
-| [node-tls-client](https://github.com/Sahil1337/node-tls-client) | Go shared lib (bogdanfinn) | Sporadic | Custom | FFI overhead | Depends on upstream |
-| [curl-impersonate](https://github.com/lwthiker/curl-impersonate) | Modified curl binary | Inactive (last release Mar 2024) | CLI/bindings | Subprocess | Stale |
+| Library | Approach | API | Notes |
+|---------|----------|-----|-------|
+| **wreq-js** | Rust native bindings ([wreq](https://github.com/0x676e67/wreq)) | Fetch style, TypeScript first | Profile labels and network behavior come from the native layer |
+| [CycleTLS](https://github.com/Danny-Dasilva/CycleTLS) | Go subprocess bridge | Promise based | Subprocess model |
+| [got-scraping](https://github.com/apify/got-scraping) | JavaScript HTTP client customization | `got` based | Header and request customization |
+| [node-tls-client](https://github.com/Sahil1337/node-tls-client) | Native shared library bindings | Custom | Behavior depends on upstream native layer |
+| [curl-impersonate](https://github.com/lwthiker/curl-impersonate) | curl based tooling | CLI and bindings | Binary/tooling workflow |
 
 ## Documentation
 
@@ -34,6 +36,13 @@ All guides, concepts, and API reference live at:
 
 (If you're looking for examples, sessions/cookies, proxy usage, streaming, WebSockets, or the full API surface - it's all there.)
 
+Quick links:
+1. Quickstart: https://wreq.sqdsh.win/quickstart
+2. API overview: https://wreq.sqdsh.win/api-reference/overview
+3. Sessions: https://wreq.sqdsh.win/concepts/sessions
+4. WebSockets: https://wreq.sqdsh.win/guides/websockets
+5. Compatibility matrix: https://wreq.sqdsh.win/concepts/compatibility-matrix
+
 ## Installation
 
 ```bash
@@ -44,12 +53,12 @@ pnpm add wreq-js
 bun add wreq-js
 ```
 
-Prebuilt binaries are provided for:
-- macOS (Intel & Apple Silicon)
-- Linux (x64 & ARM64, glibc & musl)
-- Windows (x64)
+Current configured native target matrix in `package.json` includes:
+1. macOS (Intel and Apple Silicon)
+2. Linux (x64 glibc and musl, arm64 glibc)
+3. Windows (x64)
 
-If a prebuilt binary for your platform/commit is unavailable, the package will build from source (requires a Rust toolchain).
+If a matching prebuilt artifact is unavailable for your environment, installation may build from source (requires a Rust toolchain).
 
 ## Quick start
 
@@ -64,10 +73,13 @@ const res = await fetch('https://example.com/api', {
 console.log(await res.json());
 ```
 
+By default, standalone `fetch()` calls use isolated ephemeral cookie storage.
+Use `createSession()` when you want cookie persistence across requests.
+
 ## Use sessions (recommended)
 
 For **most real-world workloads**, start with a session and reuse it across requests.
-This keeps TLS/cookies warm and avoids paying setup costs on every call.
+This keeps one cookie and request context for multi step flows.
 
 ```ts
 import { createSession } from 'wreq-js';
@@ -85,12 +97,84 @@ try {
 
 More session patterns: https://wreq.sqdsh.win
 
+## WebSockets
+
+Use the helper for a connected socket from one `await`.
+
+```ts
+import { websocket } from 'wreq-js';
+
+const ws = await websocket('wss://example.com/ws', {
+  browser: 'chrome_142',
+  headers: {
+    Authorization: 'Bearer token',
+  },
+});
+
+ws.onmessage = (event) => {
+  console.log(event.data);
+};
+
+ws.send('hello');
+ws.close(1000, 'done');
+```
+
+Use the constructor when you want browser like `CONNECTING` behavior.
+
+```ts
+import { WebSocket } from 'wreq-js';
+
+const ws = new WebSocket('wss://example.com/ws', {
+  browser: 'chrome_142',
+  os: 'windows',
+});
+
+ws.onopen = () => {
+  void ws.send('connected');
+};
+```
+
+Use `session.websocket(...)` to reuse cookies and transport settings from session HTTP calls.
+
+```ts
+import { createSession } from 'wreq-js';
+
+const session = await createSession({ browser: 'chrome_142' });
+
+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');
+  ws.onmessage = (event) => {
+    console.log(event.data);
+  };
+} finally {
+  await session.close();
+}
+```
+
 ## When to use
 
-Use `wreq-js` when you need to make HTTP requests that pass Cloudflare, DataDome, or other anti-bot TLS fingerprinting checks without spinning up a real browser. It's a drop-in `fetch()` replacement that impersonates real browser TLS/HTTP2 fingerprints at the network level.
+Use `wreq-js` when your Node.js HTTP or WebSocket traffic gets blocked because of TLS fingerprinting or browser profile mismatches.
+It is a good fit when you want Cloudflare bypass and DataDome bypass style network behavior with a familiar fetch style API.
+It handles transport and fingerprint level behavior, not CAPTCHA solving and not in page JavaScript execution.
 
 If you need DOM/JS execution, CAPTCHA solving, or full browser automation, use Playwright/Puppeteer instead.
 
+## FAQ
+
+1. Why use sessions?
+Use sessions for multi-step flows where cookie and request context should be shared.
+
+2. Why does install compile from source on some machines?
+If a matching prebuilt native artifact is unavailable, npm may build from source.
+
+3. Can I use per-request proxy overrides inside a session?
+Yes, by passing a `transport` on that specific `session.fetch(...)` call. The `proxy` field itself remains session-scoped.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -102,5 +186,5 @@ This is a maintained fork of [will-work-for-meal/node-wreq](https://github.com/w
 ## Acknowledgments
 
 - [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
+- [wreq-util](https://github.com/0x676e67/wreq-util) - related browser profile tooling in the upstream ecosystem
 - [NAPI-RS](https://napi.rs/) - Rust ↔ Node.js bindings