httpcloak 1.5.1 → 1.5.3

package/README.md

@@ -48,6 +48,19 @@ async function main() {
 main();
 ```
 
+### ES Modules
+
+```javascript
+import { Session } from "httpcloak";
+
+const session = new Session({ preset: "chrome-143" });
+
+const response = await session.get("https://example.com");
+console.log(response.text);
+
+session.close();
+```
+
 ### Synchronous Usage
 
 ```javascript
@@ -99,13 +112,209 @@ session.postCb(
 );
 ```
 
-### With Proxy
+### Streaming Downloads
+
+For large downloads, use streaming to avoid loading entire response into memory:
+
+```javascript
+const { Session } = require("httpcloak");
+const fs = require("fs");
+
+async function downloadFile() {
+  const session = new Session({ preset: "chrome-143" });
+
+  try {
+    // Start streaming request
+    const stream = session.getStream("https://example.com/large-file.zip");
+
+    console.log(`Status: ${stream.statusCode}`);
+    console.log(`Content-Length: ${stream.contentLength}`);
+    console.log(`Protocol: ${stream.protocol}`);
+
+    // Read in chunks
+    const file = fs.createWriteStream("downloaded-file.zip");
+    let totalBytes = 0;
+    let chunk;
+
+    while ((chunk = stream.readChunk(65536)) !== null) {
+      file.write(chunk);
+      totalBytes += chunk.length;
+      console.log(`Downloaded ${totalBytes} bytes...`);
+    }
+
+    file.end();
+    stream.close();
+    console.log(`Download complete: ${totalBytes} bytes`);
+  } finally {
+    session.close();
+  }
+}
+
+downloadFile();
+```
+
+### Streaming with All Methods
 
 ```javascript
+const { Session } = require("httpcloak");
+
+const session = new Session({ preset: "chrome-143" });
+
+// Stream GET
+const getStream = session.getStream("https://example.com/data");
+
+// Stream POST
+const postStream = session.postStream("https://example.com/upload", "data");
+
+// Stream with custom options
+const customStream = session.requestStream({
+  method: "PUT",
+  url: "https://example.com/resource",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ key: "value" }),
+});
+
+// Read response
+let chunk;
+while ((chunk = customStream.readChunk(65536)) !== null) {
+  console.log(`Received ${chunk.length} bytes`);
+}
+customStream.close();
+
+session.close();
+```
+
+## Proxy Support
+
+HTTPCloak supports HTTP, SOCKS5, and HTTP/3 (MASQUE) proxies with full fingerprint preservation.
+
+### HTTP Proxy
+
+```javascript
+const { Session } = require("httpcloak");
+
+// Basic HTTP proxy
 const session = new Session({
+  preset: "chrome-143",
+  proxy: "http://host:port",
+});
+
+// With authentication
+const sessionAuth = new Session({
   preset: "chrome-143",
   proxy: "http://user:pass@host:port",
 });
+
+// HTTPS proxy
+const sessionHttps = new Session({
+  preset: "chrome-143",
+  proxy: "https://user:pass@host:port",
+});
+```
+
+### SOCKS5 Proxy
+
+```javascript
+const { Session } = require("httpcloak");
+
+// SOCKS5 proxy (with DNS resolution on proxy)
+const session = new Session({
+  preset: "chrome-143",
+  proxy: "socks5h://host:port",
+});
+
+// With authentication
+const sessionAuth = new Session({
+  preset: "chrome-143",
+  proxy: "socks5h://user:pass@host:port",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+console.log(response.protocol); // h3 (HTTP/3 through SOCKS5!)
+```
+
+### HTTP/3 MASQUE Proxy
+
+MASQUE (RFC 9484) enables HTTP/3 connections through compatible proxies:
+
+```javascript
+const { Session } = require("httpcloak");
+
+// MASQUE proxy (auto-detected for known providers like Bright Data)
+const session = new Session({
+  preset: "chrome-143",
+  proxy: "https://user:pass@brd.superproxy.io:10001",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+console.log(response.protocol); // h3
+```
+
+### Split Proxy Configuration
+
+Use different proxies for TCP (HTTP/1.1, HTTP/2) and UDP (HTTP/3) traffic:
+
+```javascript
+const { Session } = require("httpcloak");
+
+const session = new Session({
+  preset: "chrome-143",
+  tcpProxy: "http://tcp-proxy:port",      // For HTTP/1.1, HTTP/2
+  udpProxy: "https://masque-proxy:port",  // For HTTP/3
+});
+```
+
+## Advanced Features
+
+### Encrypted Client Hello (ECH)
+
+ECH encrypts the SNI (Server Name Indication) to prevent traffic analysis. Works with all Cloudflare domains:
+
+```javascript
+const { Session } = require("httpcloak");
+
+// Enable ECH for Cloudflare domains
+const session = new Session({
+  preset: "chrome-143",
+  echConfigDomain: "cloudflare-ech.com",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+console.log(response.text);
+// Output includes: sni=encrypted, http=http/3
+```
+
+### Domain Fronting (Connect-To)
+
+Connect to one server while requesting a different domain:
+
+```javascript
+const { Session } = require("httpcloak");
+
+// Connect to claude.ai's IP but request www.cloudflare.com
+const session = new Session({
+  preset: "chrome-143",
+  connectTo: { "www.cloudflare.com": "claude.ai" },
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+```
+
+### Combined: SOCKS5 + ECH
+
+Get HTTP/3 with encrypted SNI through a SOCKS5 proxy:
+
+```javascript
+const { Session } = require("httpcloak");
+
+const session = new Session({
+  preset: "chrome-143",
+  proxy: "socks5h://user:pass@host:port",
+  echConfigDomain: "cloudflare-ech.com",
+});
+
+const response = await session.get("https://www.cloudflare.com/cdn-cgi/trace");
+// Response shows: http=http/3, sni=encrypted
 ```
 
 ## Cookie Management
@@ -115,19 +324,47 @@ const { Session } = require("httpcloak");
 
 const session = new Session();
 
+// Set a cookie
+session.setCookie("session_id", "abc123");
+
 // Get all cookies
 const cookies = session.getCookies();
 console.log(cookies);
 
-// Set a cookie
-session.setCookie("session_id", "abc123");
-
 // Access cookies as property
 console.log(session.cookies);
 
+// Clear a cookie
+session.clearCookie("session_id");
+
+// Clear all cookies
+session.clearCookies();
+
 session.close();
 ```
 
+## Session Configuration
+
+```javascript
+const { Session } = require("httpcloak");
+
+const session = new Session({
+  preset: "chrome-143",           // Browser fingerprint preset
+  proxy: null,                    // Proxy URL
+  tcpProxy: null,                 // Separate TCP proxy
+  udpProxy: null,                 // Separate UDP proxy (MASQUE)
+  timeout: 30,                    // Request timeout in seconds
+  httpVersion: "auto",            // "auto", "h1", "h2", "h3"
+  verify: true,                   // SSL certificate verification
+  allowRedirects: true,           // Follow redirects
+  maxRedirects: 10,               // Maximum redirect count
+  retry: 3,                       // Retry count on failure
+  preferIpv4: false,              // Prefer IPv4 over IPv6
+  connectTo: null,                // Domain fronting map
+  echConfigDomain: null,          // ECH config domain
+});
+```
+
 ## Available Presets
 
 ```javascript
@@ -140,28 +377,90 @@ console.log(availablePresets());
 
 ## Response Object
 
+### Standard Response
+
 ```javascript
 const response = await session.get("https://example.com");
 
-response.statusCode; // number: HTTP status code
-response.headers; // object: Response headers
-response.body; // Buffer: Raw response body
-response.text; // string: Response body as text
-response.finalUrl; // string: Final URL after redirects
-response.protocol; // string: Protocol used (http/1.1, h2, h3)
-response.json(); // Parse response body as JSON
+response.statusCode;   // number: HTTP status code
+response.headers;      // object: Response headers (values are arrays)
+response.body;         // Buffer: Raw response body
+response.text;         // string: Response body as text
+response.finalUrl;     // string: Final URL after redirects
+response.protocol;     // string: Protocol used (http/1.1, h2, h3)
+response.ok;           // boolean: True if status < 400
+response.cookies;      // array: Cookies from response
+response.history;      // array: Redirect history
+
+// Get specific header
+const contentType = response.getHeader("Content-Type");
+const allCookies = response.getHeaders("Set-Cookie");
+
+// Parse JSON
+const data = response.json();
 ```
 
-## Custom Requests
+### Streaming Response
 
 ```javascript
-const response = await session.request({
+const stream = session.getStream("https://example.com");
+
+stream.statusCode;      // number: HTTP status code
+stream.headers;         // object: Response headers (values are arrays)
+stream.contentLength;   // number: Content length (-1 if unknown)
+stream.finalUrl;        // string: Final URL after redirects
+stream.protocol;        // string: Protocol used
+
+// Read all bytes
+const data = stream.readAll();
+
+// Read in chunks (memory efficient)
+let chunk;
+while ((chunk = stream.readChunk(65536)) !== null) {
+  process(chunk);
+}
+
+stream.close();
+```
+
+## HTTP Methods
+
+```javascript
+const { Session } = require("httpcloak");
+
+const session = new Session({ preset: "chrome-143" });
+
+// GET
+const response = await session.get("https://example.com");
+
+// POST
+const postResponse = await session.post("https://example.com", { key: "value" });
+
+// PUT
+const putResponse = await session.put("https://example.com", { key: "value" });
+
+// PATCH
+const patchResponse = await session.patch("https://example.com", { key: "value" });
+
+// DELETE
+const deleteResponse = await session.delete("https://example.com");
+
+// HEAD
+const headResponse = await session.head("https://example.com");
+
+// OPTIONS
+const optionsResponse = await session.options("https://example.com");
+
+// Custom request
+const customResponse = await session.request({
   method: "PUT",
   url: "https://api.example.com/resource",
   headers: { "X-Custom": "value" },
   body: { data: "value" },
   timeout: 60,
 });
+
+session.close();
 ```
 
 ## Error Handling
@@ -189,13 +488,22 @@ session.close();
 HTTPCloak includes TypeScript definitions out of the box:
 
 ```typescript
-import { Session, Response, HTTPCloakError } from "httpcloak";
+import { Session, Response, StreamResponse, HTTPCloakError } from "httpcloak";
 
 const session = new Session({ preset: "chrome-143" });
 
 async function fetchData(): Promise<Response> {
   return session.get("https://example.com");
 }
+
+async function downloadLargeFile(): Promise<void> {
+  const stream: StreamResponse = session.getStream("https://example.com/file");
+  let chunk: Buffer | null;
+  while ((chunk = stream.readChunk(65536)) !== null) {
+    // Process chunk
+  }
+  stream.close();
+}
 ```
 
 ## Platform Support
@@ -203,6 +511,7 @@ async function fetchData(): Promise<Response> {
 - Linux (x64, arm64)
 - macOS (x64, arm64)
 - Windows (x64, arm64)
+- Node.js 16+
 
 ## License
 

package/lib/index.d.ts

@@ -6,6 +6,22 @@ export class HTTPCloakError extends Error {
   name: "HTTPCloakError";
 }
 
+export class Cookie {
+  /** Cookie name */
+  name: string;
+  /** Cookie value */
+  value: string;
+}
+
+export class RedirectInfo {
+  /** HTTP status code */
+  statusCode: number;
+  /** Request URL */
+  url: string;
+  /** Response headers */
+  headers: Record<string, string>;
+}
+
 export class Response {
   /** HTTP status code */
   statusCode: number;
@@ -13,22 +29,45 @@ export class Response {
   headers: Record<string, string>;
   /** Raw response body as Buffer */
   body: Buffer;
+  /** Response body as Buffer (alias for body) */
+  content: Buffer;
   /** Response body as string */
   text: string;
   /** Final URL after redirects */
   finalUrl: string;
+  /** Final URL after redirects (alias for finalUrl) */
+  url: string;
   /** Protocol used (http/1.1, h2, h3) */
   protocol: string;
+  /** Elapsed time in milliseconds */
+  elapsed: number;
+  /** Cookies set by this response */
+  cookies: Cookie[];
+  /** Redirect history */
+  history: RedirectInfo[];
+  /** True if status code < 400 */
+  ok: boolean;
+  /** HTTP status reason phrase (e.g., 'OK', 'Not Found') */
+  reason: string;
+  /** Response encoding from Content-Type header */
+  encoding: string | null;
 
   /** Parse response body as JSON */
   json<T = any>(): T;
+
+  /** Raise error if status >= 400 */
+  raiseForStatus(): void;
 }
 
 export interface SessionOptions {
   /** Browser preset to use (default: "chrome-143") */
   preset?: string;
-  /** Proxy URL (e.g., "http://user:pass@host:port") */
+  /** Proxy URL (e.g., "http://user:pass@host:port" or "socks5://host:port") */
   proxy?: string;
+  /** Proxy URL for TCP protocols (HTTP/1.1, HTTP/2) - use with udpProxy for split config */
+  tcpProxy?: string;
+  /** Proxy URL for UDP protocols (HTTP/3 via MASQUE) - use with tcpProxy for split config */
+  udpProxy?: string;
   /** Request timeout in seconds (default: 30) */
   timeout?: number;
   /** HTTP version: "auto", "h1", "h2", "h3" (default: "auto") */
@@ -43,17 +82,33 @@ export interface SessionOptions {
   retry?: number;
   /** Status codes to retry on (default: [429, 500, 502, 503, 504]) */
   retryOnStatus?: number[];
+  /** Prefer IPv4 addresses over IPv6 (default: false) */
+  preferIpv4?: boolean;
+  /** Default basic auth [username, password] */
+  auth?: [string, string];
+  /** Domain fronting map {requestHost: connectHost} - DNS resolves connectHost but SNI/Host uses requestHost */
+  connectTo?: Record<string, string>;
+  /** Domain to fetch ECH config from (e.g., "cloudflare-ech.com" for any Cloudflare domain) */
+  echConfigDomain?: string;
 }
 
 export interface RequestOptions {
-  /** HTTP method */
-  method: string;
-  /** Request URL */
-  url: string;
   /** Optional custom headers */
   headers?: Record<string, string>;
-  /** Optional request body */
+  /** Optional request body (for POST, PUT, PATCH) */
   body?: string | Buffer | Record<string, any>;
+  /** JSON body (will be serialized) */
+  json?: Record<string, any>;
+  /** Form data (will be URL encoded) */
+  data?: Record<string, any>;
+  /** Files to upload as multipart/form-data */
+  files?: Record<string, Buffer | { filename: string; content: Buffer; contentType?: string }>;
+  /** Query parameters */
+  params?: Record<string, string | number | boolean>;
+  /** Cookies to send with this request */
+  cookies?: Record<string, string>;
+  /** Basic auth [username, password] */
+  auth?: [string, string];
   /** Optional request timeout in seconds */
   timeout?: number;
 }
@@ -61,67 +116,66 @@ export interface RequestOptions {
 export class Session {
   constructor(options?: SessionOptions);
 
+  /** Default headers for all requests */
+  headers: Record<string, string>;
+
+  /** Default auth for all requests [username, password] */
+  auth: [string, string] | null;
+
   /** Close the session and release resources */
   close(): void;
 
   // Synchronous methods
   /** Perform a synchronous GET request */
-  getSync(url: string, headers?: Record<string, string>): Response;
+  getSync(url: string, options?: RequestOptions): Response;
 
   /** Perform a synchronous POST request */
-  postSync(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Response;
+  postSync(url: string, options?: RequestOptions): Response;
 
   /** Perform a synchronous custom HTTP request */
-  requestSync(options: RequestOptions): Response;
+  requestSync(method: string, url: string, options?: RequestOptions): Response;
 
   // Promise-based methods
   /** Perform an async GET request */
-  get(url: string, headers?: Record<string, string>): Promise<Response>;
+  get(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async POST request */
-  post(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Promise<Response>;
+  post(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async custom HTTP request */
-  request(options: RequestOptions): Promise<Response>;
+  request(method: string, url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async PUT request */
-  put(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Promise<Response>;
+  put(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async DELETE request */
-  delete(url: string, headers?: Record<string, string>): Promise<Response>;
+  delete(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async PATCH request */
-  patch(
-    url: string,
-    body?: string | Buffer | Record<string, any>,
-    headers?: Record<string, string>
-  ): Promise<Response>;
+  patch(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async HEAD request */
-  head(url: string, headers?: Record<string, string>): Promise<Response>;
+  head(url: string, options?: RequestOptions): Promise<Response>;
 
   /** Perform an async OPTIONS request */
-  options(url: string, headers?: Record<string, string>): Promise<Response>;
+  options(url: string, options?: RequestOptions): Promise<Response>;
 
   // Cookie management
   /** Get all cookies from the session */
   getCookies(): Record<string, string>;
 
+  /** Get a specific cookie by name */
+  getCookie(name: string): string | null;
+
   /** Set a cookie in the session */
   setCookie(name: string, value: string): void;
 
+  /** Delete a specific cookie by name */
+  deleteCookie(name: string): void;
+
+  /** Clear all cookies from the session */
+  clearCookies(): void;
+
   /** Get cookies as a property */
   readonly cookies: Record<string, string>;
 }
@@ -162,7 +216,8 @@ export function patch(url: string, options?: RequestOptions): Promise<Response>;
 export function head(url: string, options?: RequestOptions): Promise<Response>;
 
 /** Perform an OPTIONS request */
-export function options(url: string, options?: RequestOptions): Promise<Response>;
+declare function opts(url: string, options?: RequestOptions): Promise<Response>;
+export { opts as options };
 
 /** Perform a custom HTTP request */
 export function request(method: string, url: string, options?: RequestOptions): Promise<Response>;