httpcloak 1.6.1-beta.3 → 1.6.5

package/README.md

@@ -16,7 +16,7 @@ npm install httpcloak
 const { Session } = require("httpcloak");
 
 async function main() {
-  const session = new Session({ preset: "chrome-145" });
+  const session = new Session({ preset: "chrome-latest" });
 
   try {
     // GET request
@@ -53,7 +53,7 @@ main();
 ```javascript
 import { Session } from "httpcloak";
 
-const session = new Session({ preset: "chrome-145" });
+const session = new Session({ preset: "chrome-latest" });
 
 const response = await session.get("https://example.com");
 console.log(response.text);
@@ -66,7 +66,7 @@ session.close();
 ```javascript
 const { Session } = require("httpcloak");
 
-const session = new Session({ preset: "chrome-145" });
+const session = new Session({ preset: "chrome-latest" });
 
 // Sync GET
 const response = session.getSync("https://example.com");
@@ -86,7 +86,7 @@ session.close();
 ```javascript
 const { Session } = require("httpcloak");
 
-const session = new Session({ preset: "chrome-145" });
+const session = new Session({ preset: "chrome-latest" });
 
 // GET with callback
 session.getCb("https://example.com", (err, response) => {
@@ -121,7 +121,7 @@ const { Session } = require("httpcloak");
 const fs = require("fs");
 
 async function downloadFile() {
-  const session = new Session({ preset: "chrome-145" });
+  const session = new Session({ preset: "chrome-latest" });
 
   try {
     // Start streaming request
@@ -158,7 +158,7 @@ downloadFile();
 ```javascript
 const { Session } = require("httpcloak");
 
-const session = new Session({ preset: "chrome-145" });
+const session = new Session({ preset: "chrome-latest" });
 
 // Stream GET
 const getStream = session.getStream("https://example.com/data");
@@ -195,19 +195,19 @@ const { Session } = require("httpcloak");
 
 // Basic HTTP proxy
 const session = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   proxy: "http://host:port",
 });
 
 // With authentication
 const sessionAuth = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   proxy: "http://user:pass@host:port",
 });
 
 // HTTPS proxy
 const sessionHttps = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   proxy: "https://user:pass@host:port",
 });
 ```
@@ -219,13 +219,13 @@ const { Session } = require("httpcloak");
 
 // SOCKS5 proxy (with DNS resolution on proxy)
 const session = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   proxy: "socks5h://host:port",
 });
 
 // With authentication
 const sessionAuth = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   proxy: "socks5h://user:pass@host:port",
 });
 
@@ -242,7 +242,7 @@ const { Session } = require("httpcloak");
 
 // MASQUE proxy (auto-detected for known providers like Bright Data)
 const session = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   proxy: "https://user:pass@brd.superproxy.io:10001",
 });
 
@@ -258,7 +258,7 @@ Use different proxies for TCP (HTTP/1.1, HTTP/2) and UDP (HTTP/3) traffic:
 const { Session } = require("httpcloak");
 
 const session = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   tcpProxy: "http://tcp-proxy:port",      // For HTTP/1.1, HTTP/2
   udpProxy: "https://masque-proxy:port",  // For HTTP/3
 });
@@ -275,7 +275,7 @@ const { Session } = require("httpcloak");
 
 // Enable ECH for Cloudflare domains
 const session = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   echConfigDomain: "cloudflare-ech.com",
 });
 
@@ -293,7 +293,7 @@ const { Session } = require("httpcloak");
 
 // Connect to example.com's IP but request www.cloudflare.com
 const session = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   connectTo: { "www.cloudflare.com": "example.com" },
 });
 
@@ -308,7 +308,7 @@ Get HTTP/3 with encrypted SNI through a SOCKS5 proxy:
 const { Session } = require("httpcloak");
 
 const session = new Session({
-  preset: "chrome-145",
+  preset: "chrome-latest",
   proxy: "socks5h://user:pass@host:port",
   echConfigDomain: "cloudflare-ech.com",
 });
@@ -324,18 +324,31 @@ const { Session } = require("httpcloak");
 
 const session = new Session();
 
-// Set a cookie
+// Set a simple cookie (global, sent to all domains)
 session.setCookie("session_id", "abc123");
 
-// Get all cookies
+// Set a domain-scoped cookie with full metadata
+session.setCookie("auth", "token", {
+  domain: ".example.com",
+  path: "/",
+  secure: true,
+  httpOnly: true,
+  sameSite: "Lax",
+});
+
+// Get all cookies (returns Cookie[] with full metadata)
 const cookies = session.getCookies();
-console.log(cookies);
+for (const cookie of cookies) {
+  console.log(`${cookie.name}=${cookie.value} (domain: ${cookie.domain})`);
+}
 
-// Access cookies as property
-console.log(session.cookies);
+// Get a specific cookie by name (returns Cookie or null)
+const cookie = session.getCookie("session_id");
+if (cookie) console.log(cookie.value);
 
-// Delete a cookie
+// Delete a cookie (omit domain to delete from all domains)
 session.deleteCookie("session_id");
+session.deleteCookie("auth", ".example.com"); // delete from specific domain
 
 // Clear all cookies
 session.clearCookies();
@@ -349,7 +362,7 @@ session.close();
 const { Session } = require("httpcloak");
 
 const session = new Session({
-  preset: "chrome-145",           // Browser fingerprint preset
+  preset: "chrome-latest",           // Browser fingerprint preset
   proxy: null,                    // Proxy URL
   tcpProxy: null,                 // Separate TCP proxy
   udpProxy: null,                 // Separate UDP proxy (MASQUE)
@@ -371,8 +384,8 @@ const session = new Session({
 const { availablePresets } = require("httpcloak");
 
 console.log(availablePresets());
-// ['chrome-145', 'chrome-144', 'chrome-143', 'chrome-141', 'chrome-133',
-//  'firefox-133', 'safari-18', 'chrome-145-ios', ...]
+// ['chrome-146', 'chrome-145', 'chrome-144', 'chrome-143', 'chrome-141', 'chrome-133',
+//  'firefox-133', 'safari-18', 'chrome-146-ios', ...]
 ```
 
 ## Response Object
@@ -428,7 +441,7 @@ stream.close();
 ```javascript
 const { Session } = require("httpcloak");
 
-const session = new Session({ preset: "chrome-145" });
+const session = new Session({ preset: "chrome-latest" });
 
 // GET
 const response = await session.get("https://example.com");
@@ -452,9 +465,7 @@ const headResponse = await session.head("https://example.com");
 const optionsResponse = await session.options("https://example.com");
 
 // Custom request
-const customResponse = await session.request({
-  method: "PUT",
-  url: "https://api.example.com/resource",
+const customResponse = await session.request("PUT", "https://api.example.com/resource", {
   headers: { "X-Custom": "value" },
   body: { data: "value" },
   timeout: 60,
@@ -490,7 +501,7 @@ HTTPCloak includes TypeScript definitions out of the box:
 ```typescript
 import { Session, Response, StreamResponse, HTTPCloakError } from "httpcloak";
 
-const session = new Session({ preset: "chrome-145" });
+const session = new Session({ preset: "chrome-latest" });
 
 async function fetchData(): Promise<Response> {
   return session.get("https://example.com");
@@ -519,7 +530,7 @@ const { LocalProxy } = require("httpcloak");
 const axios = require("axios");
 
 // Start local proxy with Chrome fingerprint
-const proxy = new LocalProxy({ preset: "chrome-145" });
+const proxy = new LocalProxy({ preset: "chrome-latest" });
 console.log(`Proxy running on ${proxy.proxyUrl}`);
 
 // Use X-HTTPCloak-Scheme header for HTTPS with fingerprinting + streaming
@@ -558,7 +569,7 @@ const { LocalProxy } = require("httpcloak");
 const axios = require("axios");
 
 // Start local proxy with Chrome fingerprint
-const proxy = new LocalProxy({ preset: "chrome-145" });
+const proxy = new LocalProxy({ preset: "chrome-latest" });
 
 // Standard HTTPS (uses CONNECT tunnel - fingerprinting via upstream proxy only)
 const response = await axios.get("https://example.com", {
@@ -590,7 +601,7 @@ When your client already provides authentic browser headers, use TLS-only mode:
 const { LocalProxy } = require("httpcloak");
 
 // Only apply TLS fingerprint, pass headers through
-const proxy = new LocalProxy({ preset: "chrome-145", tlsOnly: true });
+const proxy = new LocalProxy({ preset: "chrome-latest", tlsOnly: true });
 
 // Your client's headers are preserved
 const response = await fetch("https://example.com", {
@@ -608,10 +619,10 @@ Route different requests through different browser fingerprints:
 ```javascript
 const { LocalProxy, Session } = require("httpcloak");
 
-const proxy = new LocalProxy({ preset: "chrome-145" });
+const proxy = new LocalProxy({ preset: "chrome-latest" });
 
 // Create sessions with different fingerprints
-const chromeSession = new Session({ preset: "chrome-145" });
+const chromeSession = new Session({ preset: "chrome-latest" });
 const firefoxSession = new Session({ preset: "firefox-133" });
 
 // Register sessions with the proxy
@@ -638,7 +649,7 @@ proxy.close();
 ```javascript
 const proxy = new LocalProxy({
   port: 0,              // Port (0 = auto-select)
-  preset: "chrome-145", // Browser fingerprint
+  preset: "chrome-latest", // Browser fingerprint
   timeout: 30,          // Request timeout in seconds
   maxConnections: 1000, // Max concurrent connections
   tcpProxy: null,       // Default upstream TCP proxy

package/lib/index.d.ts

@@ -195,7 +195,7 @@ export class StreamResponse {
 }
 
 export interface SessionOptions {
-  /** Browser preset to use (default: "chrome-145") */
+  /** Browser preset to use (default: "chrome-146") */
   preset?: string;
   /** Proxy URL (e.g., "http://user:pass@host:port" or "socks5://host:port") */
   proxy?: string;
@@ -268,6 +268,19 @@ export interface RequestOptions {
   auth?: [string, string];
   /** Optional request timeout in seconds */
   timeout?: number;
+  /**
+   * Explicit Sec-Fetch-Mode/Dest override for requests where auto-sniffing isn't enough.
+   *
+   * Valid values:
+   * - `"cors"` - XHR/fetch() request (Sec-Fetch-Mode: cors, Sec-Fetch-Dest: empty, Sec-Fetch-Site: same-origin)
+   * - `"no-cors"` - Subresource load (image/script/stylesheet tag)
+   * - `"navigate"` - Top-level navigation (document load, classic form POST)
+   * - `"websocket"` - WebSocket upgrade
+   *
+   * When unset (default), httpcloak auto-detects based on method, Accept, Content-Type, and Sec-Fetch-Dest headers.
+   * Set this explicitly when the auto-sniff gets it wrong (e.g., POST to a CORS endpoint without a JSON Accept header).
+   */
+  fetchMode?: "cors" | "no-cors" | "navigate" | "websocket";
 }
 
 export class Session {
@@ -337,22 +350,50 @@ export class Session {
   options(url: string, options?: RequestOptions): Promise<Response>;
 
   // Cookie management
-  /** Get all cookies from the session */
+
+  /** Get all cookies with full metadata (domain, path, expiry, flags) */
+  getCookiesDetailed(): Cookie[];
+
+  /** Get a specific cookie by name with full metadata */
+  getCookieDetailed(name: string): Cookie | null;
+
+  /**
+   * Get all cookies as a flat name-value object.
+   * @deprecated Will return Cookie[] with full metadata in a future release. Use getCookiesDetailed() for the new format now.
+   */
   getCookies(): Record<string, string>;
 
-  /** Get a specific cookie by name */
+  /**
+   * Get a specific cookie value by name.
+   * @deprecated Will return Cookie|null in a future release. Use getCookieDetailed() for the new format now.
+   */
   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;
+  setCookie(
+    name: string,
+    value: string,
+    options?: {
+      domain?: string;
+      path?: string;
+      secure?: boolean;
+      httpOnly?: boolean;
+      sameSite?: string;
+      maxAge?: number;
+      expires?: string;
+    }
+  ): void;
+
+  /** Delete a specific cookie by name. If domain is omitted, deletes from all domains. */
+  deleteCookie(name: string, domain?: string): void;
 
   /** Clear all cookies from the session */
   clearCookies(): void;
 
-  /** Get cookies as a property */
+  /**
+   * Get cookies as a property.
+   * @deprecated Will return Cookie[] with full metadata in a future release.
+   */
   readonly cookies: Record<string, string>;
 
   // Proxy management
@@ -619,7 +660,7 @@ export class Session {
 export interface LocalProxyOptions {
   /** Port to listen on (default: 0 for auto-assign) */
   port?: number;
-  /** Browser preset to use (default: "chrome-145") */
+  /** Browser preset to use (default: "chrome-146") */
   preset?: string;
   /** Request timeout in seconds (default: 30) */
   timeout?: number;
@@ -659,7 +700,7 @@ export interface LocalProxyStats {
  *
  * @example
  * // Basic usage
- * const proxy = new LocalProxy({ preset: "chrome-145", tlsOnly: true });
+ * const proxy = new LocalProxy({ preset: "chrome-146", tlsOnly: true });
  * console.log(`Proxy running on ${proxy.proxyUrl}`);
  * // Use with any HTTP client pointing to the proxy
  * proxy.close();
@@ -816,6 +857,10 @@ export function request(method: string, url: string, options?: RequestOptions):
 
 /** Available browser presets */
 export const Preset: {
+  CHROME_146: string;
+  CHROME_146_WINDOWS: string;
+  CHROME_146_LINUX: string;
+  CHROME_146_MACOS: string;
   CHROME_145: string;
   CHROME_145_WINDOWS: string;
   CHROME_145_LINUX: string;
@@ -833,9 +878,11 @@ export const Preset: {
   CHROME_143_IOS: string;
   CHROME_144_IOS: string;
   CHROME_145_IOS: string;
+  CHROME_146_IOS: string;
   CHROME_143_ANDROID: string;
   CHROME_144_ANDROID: string;
   CHROME_145_ANDROID: string;
+  CHROME_146_ANDROID: string;
   FIREFOX_133: string;
   SAFARI_18: string;
   SAFARI_17_IOS: string;
@@ -844,9 +891,11 @@ export const Preset: {
   IOS_CHROME_143: string;
   IOS_CHROME_144: string;
   IOS_CHROME_145: string;
+  IOS_CHROME_146: string;
   ANDROID_CHROME_143: string;
   ANDROID_CHROME_144: string;
   ANDROID_CHROME_145: string;
+  ANDROID_CHROME_146: string;
   IOS_SAFARI_17: string;
   IOS_SAFARI_18: string;
   all(): string[];
@@ -984,3 +1033,66 @@ export function configureSessionCache(options: SessionCacheOptions): SessionCach
  * After calling this, new sessions will not use distributed caching.
  */
 export function clearSessionCache(): void;
+
+/**
+ * Load a custom preset from a JSON file and register it.
+ * @param filePath - Path to the preset JSON file
+ * @returns The registered preset name
+ */
+export function loadPreset(filePath: string): string;
+
+/**
+ * Load a custom preset from a JSON string and register it.
+ * @param jsonData - JSON string defining the preset
+ * @returns The registered preset name
+ */
+export function loadPresetFromJSON(jsonData: string): string;
+
+/**
+ * Unregister a custom preset by name.
+ * @param name - The preset name to unregister
+ */
+export function unregisterPreset(name: string): void;
+
+/**
+ * A pool of custom fingerprint presets for rotation.
+ *
+ * Pools load multiple presets from a single JSON file and provide
+ * round-robin or random selection. All presets are auto-registered
+ * on construction, so you can pass the returned name directly to
+ * `new Session({ preset: name })`.
+ */
+export class PresetPool {
+  /**
+   * Load a preset pool from a JSON file.
+   * @param filePath - Path to the pool JSON file
+   */
+  constructor(filePath: string);
+
+  /**
+   * Load a preset pool from a JSON string.
+   * @param jsonData - JSON string defining the pool
+   */
+  static fromJSON(jsonData: string): PresetPool;
+
+  /** Pick a preset using the pool's configured strategy. */
+  pick(): string;
+
+  /** Pick a random preset from the pool. */
+  random(): string;
+
+  /** Pick the next preset in round-robin order. */
+  next(): string;
+
+  /** Get a preset by index. */
+  get(index: number): string;
+
+  /** Number of presets in the pool. */
+  readonly size: number;
+
+  /** Name of the preset pool. */
+  readonly name: string;
+
+  /** Free the pool handle and unregister all its presets. */
+  close(): void;
+}