httpcloak 1.6.5 → 1.6.7

package/lib/index.d.ts

@@ -213,9 +213,9 @@ export interface SessionOptions {
   allowRedirects?: boolean;
   /** Maximum number of redirects to follow (default: 10) */
   maxRedirects?: number;
-  /** Number of retries on failure (default: 3, set to 0 to disable) */
+  /** Number of retries on failure (default: 0, opt in by setting a positive integer) */
   retry?: number;
-  /** Status codes to retry on (default: [429, 500, 502, 503, 504]) */
+  /** Status codes to retry on (default: empty; set explicitly to opt in, e.g. [429, 500, 502, 503, 504]) */
   retryOnStatus?: number[];
   /** Minimum wait time between retries in milliseconds (default: 500) */
   retryWaitMin?: number;
@@ -241,12 +241,30 @@ export interface SessionOptions {
   enableSpeculativeTls?: boolean;
   /** Protocol to switch to after Refresh() (e.g., "h1", "h2", "h3") */
   switchProtocol?: string;
+  /** Disable internal cookie jar entirely — caller manages cookies via per-request headers (default: false) */
+  withoutCookieJar?: boolean;
+  /** Disable ETag / If-Modified-Since handling for the lifetime of the session (default: false) */
+  withoutConditionalCache?: boolean;
+  /** Skip the ECH (Encrypted Client Hello) HTTPS RR lookup. Saves ~15-20ms on first connect (default: false) */
+  disableEch?: boolean;
+  /** Disable HTTP/3 racing while keeping H1/H2 auto-negotiation. Reachable indirectly via httpVersion: "h2" but the explicit flag is cleaner (default: false) */
+  disableHttp3?: boolean;
   /** Custom JA3 fingerprint string (e.g., "771,4865-4866-4867-...,0-23-65281-...,29-23-24,0") */
   ja3?: string;
   /** Custom Akamai HTTP/2 fingerprint string (e.g., "1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p") */
   akamai?: string;
   /** Extra fingerprint options: { tls_alpn, tls_signature_algorithms, tls_cert_compression, tls_permute_extensions } */
   extraFp?: Record<string, any>;
+  /** TCP IP Time-To-Live in the SYN packet. 128 = Windows, 64 = Linux/macOS/iOS/Android. */
+  tcpTtl?: number;
+  /** TCP Maximum Segment Size option. 1460 for standard Ethernet. */
+  tcpMss?: number;
+  /** TCP Window Size in the SYN packet. 64240 = Windows 10/11, 65535 = Linux/macOS. */
+  tcpWindowSize?: number;
+  /** TCP Window Scale option exponent. 8 = Windows, 7 = Linux/Android, 6 = macOS/iOS. */
+  tcpWindowScale?: number;
+  /** IP Don't-Fragment flag. true on every modern client. */
+  tcpDf?: boolean;
 }
 
 export interface RequestOptions {
@@ -281,6 +299,64 @@ export interface RequestOptions {
    * 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";
+
+  /**
+   * Per-request override for redirect following. true forces redirects on this
+   * call, false surfaces the 3xx back to the caller; null / undefined defers
+   * to the session-level setting (which itself defaults to follow).
+   */
+  allowRedirects?: boolean | null;
+
+  /**
+   * Per-request opt-out of the session's ETag / If-Modified-Since handling.
+   * When true, no cache validators are injected on the way out and the
+   * response's ETag / Last-Modified are not stored. Useful for a one-off
+   * fresh fetch without touching the session-wide setting.
+   */
+  disableConditionalCache?: boolean;
+
+  /**
+   * AbortSignal for cancelling an in-flight request. Honored by the async
+   * methods (get, post, put, patch, delete, head, options, request). When
+   * the signal aborts, the underlying Go-side request is cancelled (DNS /
+   * TCP / TLS / HTTP work is torn down) and the returned promise rejects
+   * with the signal's reason (or a generic AbortError if none was set).
+   *
+   * @example
+   * const controller = new AbortController();
+   * setTimeout(() => controller.abort(new Error("too slow")), 5000);
+   * await session.get("https://slow.example.com", { signal: controller.signal });
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Snapshot returned by `Session.stats()`. Mirrors the wire shape emitted by
+ * the Go-side `session.Stats()` after snake_case marshalling.
+ */
+export interface SessionStats {
+  /** Stable session ID assigned at construction. */
+  id: string;
+  /** Preset name the session was created with. */
+  preset: string;
+  /** Construction time, Unix nanoseconds. */
+  created_at: number;
+  /** Last-request time, Unix nanoseconds. */
+  last_used: number;
+  /** Total requests serviced by this session. */
+  request_count: number;
+  /** Whether the session is still usable (false after close). */
+  active: boolean;
+  /** Live cookie count in the jar. */
+  cookie_count: number;
+  /** Conditional-cache entry count (one per cached URL). */
+  cache_entry_count: number;
+  /** Age in nanoseconds (now - created_at). */
+  age_ns: number;
+  /** Idle time in nanoseconds (now - last_used). */
+  idle_time_ns: number;
+  /** Transport-level stats (per-protocol). Shape varies; treat as opaque. */
+  transport_stats?: Record<string, any>;
 }
 
 export class Session {
@@ -311,8 +387,11 @@ export class Session {
   /** Refresh the session by closing all connections while keeping TLS session tickets.
    * This simulates a browser page refresh - connections are severed but 0-RTT
    * early data can be used on reconnection due to preserved session tickets.
+   *
+   * @param switchProtocol - Optional protocol to switch to ("h1", "h2", "h3").
+   *   Overrides any switchProtocol set at construction time. Persists for future refresh() calls.
    */
-  refresh(): void;
+  refresh(switchProtocol?: "h1" | "h2" | "h3"): void;
 
   // Synchronous methods
   /** Perform a synchronous GET request */
@@ -357,17 +436,11 @@ export class Session {
   /** 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 all cookies with full metadata. Alias of getCookiesDetailed(); the older flat dict shape was removed in v1.6.5. */
+  getCookies(): Cookie[];
 
-  /**
-   * 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;
+  /** Get a specific cookie by name. Alias of getCookieDetailed(); the older value-only shape was removed in v1.6.5. */
+  getCookie(name: string): Cookie | null;
 
   /** Set a cookie in the session */
   setCookie(
@@ -390,11 +463,72 @@ export class Session {
   /** Clear all cookies from the session */
   clearCookies(): void;
 
+  /** Cookies in the session jar with full metadata. Same shape as getCookies(). */
+  readonly cookies: Cookie[];
+
+  // Conditional cache and redirect runtime control
+
+  /**
+   * Drop the session's per-URL conditional-cache map (ETag / Last-Modified).
+   * The next request to each URL goes out without If-None-Match /
+   * If-Modified-Since headers. Cookies and TLS tickets are not touched.
+   */
+  clearCache(): void;
+
+  /**
+   * Snapshot of session counters, timestamps and transport-level metrics.
+   * Mirrors the keys Go's session.Stats() returns, snake_case on the wire.
+   */
+  stats(): SessionStats;
+
+  /**
+   * Return the time since the session last serviced a request, in seconds.
+   * Returns -1 if the session handle is invalid.
+   */
+  idleTime(): number;
+
+  /**
+   * Return true if the session is still usable (close() has not been called
+   * and the handle is valid).
+   */
+  isActive(): boolean;
+
+  /**
+   * Reset the idle timer to now without issuing a request. Useful in
+   * long-running pools where an external heartbeat shouldn't let a session
+   * look idle to a reaper.
+   */
+  touch(): void;
+
+  /**
+   * Toggle the session's ETag / If-Modified-Since handling at runtime.
+   * When disabled, the session stops injecting cache validators on outgoing
+   * requests and stops storing them from responses; the existing cache map
+   * is preserved (re-enabling resumes using it). Pair with clearCache() to
+   * also wipe previously-stored validators.
+   */
+  setConditionalCache(enabled: boolean): void;
+
+  /** Read the session's current conditional-cache state. */
+  getConditionalCache(): boolean;
+
+  /**
+   * Toggle the session's redirect-following policy at runtime. The change
+   * takes effect on the next request and persists until set again.
+   */
+  setFollowRedirects(enabled: boolean): void;
+
+  /** Read the session's current redirect-following policy. */
+  getFollowRedirects(): boolean;
+
   /**
-   * Get cookies as a property.
-   * @deprecated Will return Cookie[] with full metadata in a future release.
+   * Update the session's redirect cap at runtime. Values of zero or below
+   * are ignored, leaving the prior cap (or the default of 10) in place.
    */
-  readonly cookies: Record<string, string>;
+  setMaxRedirects(max: number): void;
+
+  /** Read the session's current redirect cap. */
+  getMaxRedirects(): number;
 
   // Proxy management
 
@@ -655,6 +789,37 @@ export class Session {
    * @returns FastResponse with Buffer body
    */
   patchFast(url: string, options?: RequestOptions): FastResponse;
+
+  /**
+   * Stream an arbitrary-sized body to the wire without buffering it in memory.
+   * `chunks` is any iterable / async-iterable yielding Buffer / Uint8Array /
+   * string chunks; the Go side opens an io.Pipe for the body and each chunk
+   * flows straight through with no base64 wrap and no JSON envelope.
+   *
+   * @param method  Typically "POST", "PUT" or "PATCH".
+   * @param url
+   * @param chunks  Iterable or async-iterable of body chunks.
+   * @param options.headers Headers (Content-Type defaults to application/octet-stream).
+   * @param options.contentType Optional explicit Content-Type override.
+   * @param options.timeout Per-request timeout in milliseconds.
+   * @returns Resolves to a regular `Response` once the upload completes.
+   */
+  uploadStream(
+    method: string,
+    url: string,
+    chunks: AsyncIterable<Buffer | Uint8Array | string> | Iterable<Buffer | Uint8Array | string>,
+    options?: { headers?: Record<string, string>; contentType?: string; timeout?: number }
+  ): Promise<Response>;
+
+  /**
+   * Convenience wrapper: streaming POST. Same semantics as
+   * `uploadStream("POST", url, chunks, options)`.
+   */
+  postUpload(
+    url: string,
+    chunks: AsyncIterable<Buffer | Uint8Array | string> | Iterable<Buffer | Uint8Array | string>,
+    options?: { headers?: Record<string, string>; contentType?: string; timeout?: number }
+  ): Promise<Response>;
 }
 
 export interface LocalProxyOptions {
@@ -675,16 +840,20 @@ export interface LocalProxyOptions {
 }
 
 export interface LocalProxyStats {
-  /** Total number of requests processed */
-  totalRequests: number;
-  /** Number of active connections */
-  activeConnections: number;
-  /** Number of failed requests */
-  failedRequests: number;
-  /** Bytes sent */
-  bytesSent: number;
-  /** Bytes received */
-  bytesReceived: number;
+  /** Whether the proxy is currently accepting connections */
+  running: boolean;
+  /** TCP port the proxy is bound to */
+  port: number;
+  /** Live count of in-flight connections */
+  active_conns: number;
+  /** Lifetime request counter since the proxy started */
+  total_requests: number;
+  /** Preset name the proxy was started with */
+  preset: string;
+  /** Max concurrent connections configured at start time */
+  max_connections: number;
+  /** Number of sessions currently registered via registerSession() */
+  registered_sessions: number;
 }
 
 /**
@@ -788,6 +957,22 @@ export class LocalProxy {
    */
   unregisterSession(sessionId: string): boolean;
 
+  /**
+   * Return the IDs of every session currently registered on this proxy.
+   * These are the same IDs the X-HTTPCloak-Session header accepts for
+   * per-request session routing.
+   *
+   * @returns List of registered session IDs (empty array if none).
+   */
+  listSessions(): string[];
+
+  /**
+   * Return true if a session with the given ID is currently registered.
+   * Cheaper than `listSessions().includes(id)` when callers only need an
+   * existence check (no JSON marshal across the FFI boundary).
+   */
+  hasSession(sessionId: string): boolean;
+
   /**
    * Stop and close the proxy.
    * After closing, the LocalProxy instance cannot be reused.
@@ -798,8 +983,30 @@ export class LocalProxy {
 /** Get the httpcloak library version */
 export function version(): string;
 
-/** Get list of available browser presets */
-export function availablePresets(): string[];
+/**
+ * Get available browser presets keyed by preset name.
+ *
+ * Each entry carries the protocols the preset supports (some H1/H2 only, some H1/H2/H3).
+ * The shape is `{ [presetName: string]: { protocols: string[] } }`.
+ *
+ * @example
+ * const presets = availablePresets();
+ * Object.entries(presets).filter(([, info]) => info.protocols.includes("h3"));
+ */
+export function availablePresets(): Record<string, { protocols: string[] }>;
+
+/**
+ * Return a fully-resolved JSON dump of a preset's TLS / H2 / H3 / header configuration.
+ *
+ * Useful for inspecting what a preset name actually does at the wire level, or for
+ * dumping a built-in preset, mutating it, and loading it back with `loadPresetFromJSON`
+ * under a new name.
+ *
+ * @param name - Preset name (e.g. "chrome-148-windows", "firefox-148", "chrome-latest")
+ * @returns JSON string. Parse with `JSON.parse` to get the structured form.
+ * @throws {HTTPCloakError} If the preset name is not registered.
+ */
+export function describePreset(name: string): string;
 
 /**
  * Configure the DNS servers used for ECH (Encrypted Client Hello) config queries.
@@ -857,6 +1064,28 @@ export function request(method: string, url: string, options?: RequestOptions):
 
 /** Available browser presets */
 export const Preset: {
+  CHROME_LATEST: string;
+  CHROME_LATEST_WINDOWS: string;
+  CHROME_LATEST_LINUX: string;
+  CHROME_LATEST_MACOS: string;
+  CHROME_LATEST_IOS: string;
+  CHROME_LATEST_ANDROID: string;
+  CHROME_149: string;
+  CHROME_149_WINDOWS: string;
+  CHROME_149_LINUX: string;
+  CHROME_149_MACOS: string;
+  CHROME_148: string;
+  CHROME_148_WINDOWS: string;
+  CHROME_148_LINUX: string;
+  CHROME_148_MACOS: string;
+  CHROME_148_IOS: string;
+  CHROME_148_ANDROID: string;
+  CHROME_147: string;
+  CHROME_147_WINDOWS: string;
+  CHROME_147_LINUX: string;
+  CHROME_147_MACOS: string;
+  CHROME_147_IOS: string;
+  CHROME_147_ANDROID: string;
   CHROME_146: string;
   CHROME_146_WINDOWS: string;
   CHROME_146_LINUX: string;

package/lib/index.js

@@ -21,91 +21,143 @@ class HTTPCloakError extends Error {
 }
 
 /**
- * Available browser presets for TLS fingerprinting.
+ * Available browser presets for TLS fingerprinting. Mirrors the runtime
+ * registry shipped by the linked libhttpcloak. Use Preset.CHROME_LATEST to
+ * auto-track newest stable Chrome, or pin to a specific major version for
+ * reproducibility.
  *
- * Use these constants instead of typing preset strings manually:
  *   const httpcloak = require("httpcloak");
- *   httpcloak.configure({ preset: httpcloak.Preset.CHROME_143 });
+ *   httpcloak.configure({ preset: httpcloak.Preset.CHROME_LATEST });
  *
- *   // Or with Session
- *   const session = new httpcloak.Session({ preset: httpcloak.Preset.FIREFOX_133 });
+ *   const session = new httpcloak.Session({ preset: httpcloak.Preset.FIREFOX_LATEST });
  */
 const Preset = {
-  // Chrome 146 (latest)
+  // Chrome latest (auto-resolves to newest shipped Chrome)
+  CHROME_LATEST: "chrome-latest",
+  CHROME_LATEST_WINDOWS: "chrome-latest-windows",
+  CHROME_LATEST_LINUX: "chrome-latest-linux",
+  CHROME_LATEST_MACOS: "chrome-latest-macos",
+  CHROME_LATEST_IOS: "chrome-latest-ios",
+  CHROME_LATEST_ANDROID: "chrome-latest-android",
+
+  // Chrome 149 (desktop; wire fingerprint identical to 148)
+  CHROME_149: "chrome-149",
+  CHROME_149_WINDOWS: "chrome-149-windows",
+  CHROME_149_LINUX: "chrome-149-linux",
+  CHROME_149_MACOS: "chrome-149-macos",
+
+  // Chrome 148
+  CHROME_148: "chrome-148",
+  CHROME_148_WINDOWS: "chrome-148-windows",
+  CHROME_148_LINUX: "chrome-148-linux",
+  CHROME_148_MACOS: "chrome-148-macos",
+  CHROME_148_IOS: "chrome-148-ios",
+  CHROME_148_ANDROID: "chrome-148-android",
+
+  // Chrome 147
+  CHROME_147: "chrome-147",
+  CHROME_147_WINDOWS: "chrome-147-windows",
+  CHROME_147_LINUX: "chrome-147-linux",
+  CHROME_147_MACOS: "chrome-147-macos",
+  CHROME_147_IOS: "chrome-147-ios",
+  CHROME_147_ANDROID: "chrome-147-android",
+
+  // Chrome 146
   CHROME_146: "chrome-146",
   CHROME_146_WINDOWS: "chrome-146-windows",
   CHROME_146_LINUX: "chrome-146-linux",
   CHROME_146_MACOS: "chrome-146-macos",
+  CHROME_146_IOS: "chrome-146-ios",
+  CHROME_146_ANDROID: "chrome-146-android",
 
   // Chrome 145
   CHROME_145: "chrome-145",
   CHROME_145_WINDOWS: "chrome-145-windows",
   CHROME_145_LINUX: "chrome-145-linux",
   CHROME_145_MACOS: "chrome-145-macos",
+  CHROME_145_IOS: "chrome-145-ios",
+  CHROME_145_ANDROID: "chrome-145-android",
 
   // Chrome 144
   CHROME_144: "chrome-144",
   CHROME_144_WINDOWS: "chrome-144-windows",
   CHROME_144_LINUX: "chrome-144-linux",
   CHROME_144_MACOS: "chrome-144-macos",
+  CHROME_144_IOS: "chrome-144-ios",
+  CHROME_144_ANDROID: "chrome-144-android",
 
   // Chrome 143
   CHROME_143: "chrome-143",
   CHROME_143_WINDOWS: "chrome-143-windows",
   CHROME_143_LINUX: "chrome-143-linux",
   CHROME_143_MACOS: "chrome-143-macos",
+  CHROME_143_IOS: "chrome-143-ios",
+  CHROME_143_ANDROID: "chrome-143-android",
 
-  // Chrome 141
+  // Older Chrome (H1/H2 only, no H3)
   CHROME_141: "chrome-141",
-
-  // Chrome 133
   CHROME_133: "chrome-133",
 
-  // Mobile Chrome
-  CHROME_143_IOS: "chrome-143-ios",
-  CHROME_144_IOS: "chrome-144-ios",
-  CHROME_145_IOS: "chrome-145-ios",
-  CHROME_146_IOS: "chrome-146-ios",
-  CHROME_143_ANDROID: "chrome-143-android",
-  CHROME_144_ANDROID: "chrome-144-android",
-  CHROME_145_ANDROID: "chrome-145-android",
-  CHROME_146_ANDROID: "chrome-146-android",
-
   // Firefox
+  FIREFOX_LATEST: "firefox-latest",
+  FIREFOX_148: "firefox-148",
   FIREFOX_133: "firefox-133",
 
   // Safari (desktop and mobile)
+  SAFARI_LATEST: "safari-latest",
   SAFARI_18: "safari-18",
   SAFARI_17_IOS: "safari-17-ios",
   SAFARI_18_IOS: "safari-18-ios",
+  SAFARI_LATEST_IOS: "safari-latest-ios",
 
-  // Backwards compatibility aliases (old naming convention)
+  // Backwards compatibility aliases (old "ios-chrome" / "android-chrome" naming)
   IOS_CHROME_143: "chrome-143-ios",
   IOS_CHROME_144: "chrome-144-ios",
   IOS_CHROME_145: "chrome-145-ios",
   IOS_CHROME_146: "chrome-146-ios",
+  IOS_CHROME_147: "chrome-147-ios",
+  IOS_CHROME_148: "chrome-148-ios",
+  IOS_CHROME_LATEST: "chrome-latest-ios",
   ANDROID_CHROME_143: "chrome-143-android",
   ANDROID_CHROME_144: "chrome-144-android",
   ANDROID_CHROME_145: "chrome-145-android",
   ANDROID_CHROME_146: "chrome-146-android",
+  ANDROID_CHROME_147: "chrome-147-android",
+  ANDROID_CHROME_148: "chrome-148-android",
+  ANDROID_CHROME_LATEST: "chrome-latest-android",
   IOS_SAFARI_17: "safari-17-ios",
   IOS_SAFARI_18: "safari-18-ios",
+  IOS_SAFARI_LATEST: "safari-latest-ios",
 
   /**
-   * Get all available preset names
-   * @returns {string[]} List of all preset names
+   * Get all built-in preset names known to this binding version.
+   *
+   * For the authoritative live list (which may include custom presets
+   * loaded at runtime), call `availablePresets()` instead.
+   *
+   * @returns {string[]} List of preset names
    */
   all() {
     return [
+      this.CHROME_LATEST, this.CHROME_LATEST_WINDOWS, this.CHROME_LATEST_LINUX,
+      this.CHROME_LATEST_MACOS, this.CHROME_LATEST_IOS, this.CHROME_LATEST_ANDROID,
+      this.CHROME_149, this.CHROME_149_WINDOWS, this.CHROME_149_LINUX, this.CHROME_149_MACOS,
+      this.CHROME_148, this.CHROME_148_WINDOWS, this.CHROME_148_LINUX, this.CHROME_148_MACOS,
+      this.CHROME_148_IOS, this.CHROME_148_ANDROID,
+      this.CHROME_147, this.CHROME_147_WINDOWS, this.CHROME_147_LINUX, this.CHROME_147_MACOS,
+      this.CHROME_147_IOS, this.CHROME_147_ANDROID,
       this.CHROME_146, this.CHROME_146_WINDOWS, this.CHROME_146_LINUX, this.CHROME_146_MACOS,
+      this.CHROME_146_IOS, this.CHROME_146_ANDROID,
       this.CHROME_145, this.CHROME_145_WINDOWS, this.CHROME_145_LINUX, this.CHROME_145_MACOS,
+      this.CHROME_145_IOS, this.CHROME_145_ANDROID,
       this.CHROME_144, this.CHROME_144_WINDOWS, this.CHROME_144_LINUX, this.CHROME_144_MACOS,
+      this.CHROME_144_IOS, this.CHROME_144_ANDROID,
       this.CHROME_143, this.CHROME_143_WINDOWS, this.CHROME_143_LINUX, this.CHROME_143_MACOS,
+      this.CHROME_143_IOS, this.CHROME_143_ANDROID,
       this.CHROME_141, this.CHROME_133,
-      this.CHROME_146_IOS, this.CHROME_145_IOS, this.CHROME_144_IOS, this.CHROME_143_IOS,
-      this.CHROME_146_ANDROID, this.CHROME_145_ANDROID, this.CHROME_144_ANDROID, this.CHROME_143_ANDROID,
-      this.FIREFOX_133,
-      this.SAFARI_18, this.SAFARI_17_IOS, this.SAFARI_18_IOS,
+      this.FIREFOX_LATEST, this.FIREFOX_148, this.FIREFOX_133,
+      this.SAFARI_LATEST, this.SAFARI_18, this.SAFARI_17_IOS, this.SAFARI_18_IOS,
+      this.SAFARI_LATEST_IOS,
     ];
   },
 };
@@ -830,6 +882,18 @@ function getLib() {
       httpcloak_set_cookie: nativeLibHandle.func("httpcloak_set_cookie", "void", ["int64", "str"]),
       httpcloak_delete_cookie: nativeLibHandle.func("httpcloak_delete_cookie", "void", ["int64", "str", "str"]),
       httpcloak_clear_cookies: nativeLibHandle.func("httpcloak_clear_cookies", "void", ["int64"]),
+      httpcloak_session_clear_cache: nativeLibHandle.func("httpcloak_session_clear_cache", "void", ["int64"]),
+      httpcloak_session_stats: nativeLibHandle.func("httpcloak_session_stats", HeapStr, ["int64"]),
+      httpcloak_session_idle_time: nativeLibHandle.func("httpcloak_session_idle_time", "int64", ["int64"]),
+      httpcloak_session_is_active: nativeLibHandle.func("httpcloak_session_is_active", "int", ["int64"]),
+      httpcloak_session_touch: nativeLibHandle.func("httpcloak_session_touch", "void", ["int64"]),
+      httpcloak_session_set_conditional_cache: nativeLibHandle.func("httpcloak_session_set_conditional_cache", "void", ["int64", "int"]),
+      httpcloak_session_get_conditional_cache: nativeLibHandle.func("httpcloak_session_get_conditional_cache", "int", ["int64"]),
+      httpcloak_session_set_follow_redirects: nativeLibHandle.func("httpcloak_session_set_follow_redirects", "void", ["int64", "int"]),
+      httpcloak_session_get_follow_redirects: nativeLibHandle.func("httpcloak_session_get_follow_redirects", "int", ["int64"]),
+      httpcloak_session_set_max_redirects: nativeLibHandle.func("httpcloak_session_set_max_redirects", "void", ["int64", "int"]),
+      httpcloak_session_get_max_redirects: nativeLibHandle.func("httpcloak_session_get_max_redirects", "int", ["int64"]),
+      httpcloak_session_set_identifier: nativeLibHandle.func("httpcloak_session_set_identifier", "void", ["int64", "str"]),
       httpcloak_free_string: httpcloakFreeString,
       httpcloak_version: nativeLibHandle.func("httpcloak_version", HeapStr, []),
       httpcloak_available_presets: nativeLibHandle.func("httpcloak_available_presets", HeapStr, []),
@@ -841,6 +905,7 @@ function getLib() {
       httpcloak_get_async: nativeLibHandle.func("httpcloak_get_async", "void", ["int64", "str", "str", "int64"]),
       httpcloak_post_async: nativeLibHandle.func("httpcloak_post_async", "void", ["int64", "str", "str", "str", "int64"]),
       httpcloak_request_async: nativeLibHandle.func("httpcloak_request_async", "void", ["int64", "str", "int64"]),
+      httpcloak_cancel_request: nativeLibHandle.func("httpcloak_cancel_request", "void", ["int64"]),
       // Streaming functions
       httpcloak_stream_get: nativeLibHandle.func("httpcloak_stream_get", "int64", ["int64", "str", "str"]),
       httpcloak_stream_post: nativeLibHandle.func("httpcloak_stream_post", "int64", ["int64", "str", "str", "str"]),
@@ -848,6 +913,15 @@ function getLib() {
       httpcloak_stream_get_metadata: nativeLibHandle.func("httpcloak_stream_get_metadata", HeapStr, ["int64"]),
       httpcloak_stream_read: nativeLibHandle.func("httpcloak_stream_read", HeapStr, ["int64", "int64"]),
       httpcloak_stream_close: nativeLibHandle.func("httpcloak_stream_close", "void", ["int64"]),
+      // Chunked upload state machine (mirrors Python's stream_upload). Lets
+      // bindings ship arbitrarily-large bodies without buffering in memory:
+      // upload_start opens a pipe to the Go side, upload_write_raw streams
+      // chunks straight to the wire, upload_finish reads the response,
+      // upload_cancel tears down a partial upload on error.
+      httpcloak_upload_start: nativeLibHandle.func("httpcloak_upload_start", "int64", ["int64", "str", "str"]),
+      httpcloak_upload_write_raw: nativeLibHandle.func("httpcloak_upload_write_raw", "int", ["int64", "void*", "int"]),
+      httpcloak_upload_finish: nativeLibHandle.func("httpcloak_upload_finish", HeapStr, ["int64"]),
+      httpcloak_upload_cancel: nativeLibHandle.func("httpcloak_upload_cancel", "void", ["int64"]),
       // Raw response functions for fast-path (zero-copy)
       httpcloak_get_raw: nativeLibHandle.func("httpcloak_get_raw", "int64", ["int64", "str", "str"]),
       httpcloak_post_raw: nativeLibHandle.func("httpcloak_post_raw", "int64", ["int64", "str", "void*", "int", "str"]),
@@ -881,6 +955,8 @@ function getLib() {
       httpcloak_local_proxy_get_stats: nativeLibHandle.func("httpcloak_local_proxy_get_stats", HeapStr, ["int64"]),
       httpcloak_local_proxy_register_session: nativeLibHandle.func("httpcloak_local_proxy_register_session", HeapStr, ["int64", "str", "int64"]),
       httpcloak_local_proxy_unregister_session: nativeLibHandle.func("httpcloak_local_proxy_unregister_session", "int", ["int64", "str"]),
+      httpcloak_local_proxy_list_sessions: nativeLibHandle.func("httpcloak_local_proxy_list_sessions", HeapStr, ["int64"]),
+      httpcloak_local_proxy_has_session: nativeLibHandle.func("httpcloak_local_proxy_has_session", "int", ["int64", "str"]),
       // Session cache callbacks
       httpcloak_set_session_cache_callbacks: nativeLibHandle.func("httpcloak_set_session_cache_callbacks", "void", [
         koffi.pointer(SessionCacheGetProto),
@@ -1010,7 +1086,7 @@ class AsyncCallbackManager {
    * Register a new async request
    * @returns {{ callbackId: number, promise: Promise<Response> }}
    */
-  registerRequest(nativeLib) {
+  registerRequest(nativeLib, signal) {
     this._ensureCallback();
 
     // Register callback with Go (each request gets unique ID)
@@ -1027,6 +1103,43 @@ class AsyncCallbackManager {
     this._pendingRequests.set(Number(callbackId), { resolve, reject, startTime });
     this._ref(); // Keep event loop alive
 
+    // AbortSignal integration. If the caller supplies a signal that is
+    // already aborted, cancel synchronously; otherwise install a listener
+    // that fires once. Pre-aborted signals never deliver the "abort" event,
+    // so the explicit early-path matters.
+    //
+    // Order matters in onAbort:
+    //   1) cancel_request → unblocks the Go goroutine (ctx.Done fires)
+    //   2) unregister_callback → removes the entry from Go's asyncCallbacks
+    //      map so the goroutine's final invokeCallback() finds !exists and
+    //      returns silently. Without this, Go would still relay an error
+    //      callback through koffi after the JS side has already settled
+    //      and torn down its callback context, which crashes node with
+    //      "Error::ThrowAsJavaScriptException napi_throw" during exit.
+    if (signal && typeof signal === "object" && "aborted" in signal) {
+      const onAbort = () => {
+        const cid = Number(callbackId);
+        try {
+          nativeLib.httpcloak_cancel_request(cid);
+          nativeLib.httpcloak_unregister_callback(cid);
+        } catch {
+          // Best-effort: the request may have already settled.
+        }
+        const pending = this._pendingRequests.get(cid);
+        if (pending) {
+          this._pendingRequests.delete(cid);
+          this._unref();
+          const reason = signal.reason ?? new Error("AbortError");
+          pending.reject(reason);
+        }
+      };
+      if (signal.aborted) {
+        onAbort();
+      } else if (typeof signal.addEventListener === "function") {
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+
     return { callbackId, promise };
   }
 }
@@ -1361,6 +1474,10 @@ class Session {
       keyLogFile = null,
       enableSpeculativeTls = false,
       switchProtocol = null,
+      withoutCookieJar = false,
+      withoutConditionalCache = false,
+      disableEch = false,
+      disableHttp3 = false,
       ja3 = null,
       akamai = null,
       extraFp = null,
@@ -1435,6 +1552,18 @@ class Session {
     if (switchProtocol) {
       config.switch_protocol = switchProtocol;
     }
+    if (withoutCookieJar) {
+      config.without_cookie_jar = true;
+    }
+    if (withoutConditionalCache) {
+      config.without_conditional_cache = true;
+    }
+    if (disableEch) {
+      config.disable_ech = true;
+    }
+    if (disableHttp3) {
+      config.disable_http3 = true;
+    }
     if (ja3) {
       config.ja3 = ja3;
     }
@@ -1598,7 +1727,7 @@ class Session {
    * @returns {Response} Response object
    */
   getSync(url, options = {}) {
-    const { headers = null, params = null, cookies = null, auth = null, fetchMode = null } = options;
+    const { headers = null, params = null, cookies = null, auth = null, fetchMode = null, allowRedirects = null, disableConditionalCache = false } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
@@ -1615,6 +1744,12 @@ class Session {
     if (fetchMode) {
       reqOptions.fetch_mode = fetchMode;
     }
+    if (allowRedirects !== null && allowRedirects !== undefined) {
+      reqOptions.follow_redirects = !!allowRedirects;
+    }
+    if (disableConditionalCache) {
+      reqOptions.disable_conditional_cache = true;
+    }
     const optionsJson = Object.keys(reqOptions).length > 0 ? JSON.stringify(reqOptions) : null;
 
     const startTime = Date.now();
@@ -1644,7 +1779,7 @@ class Session {
    * @returns {Response} Response object
    */
   postSync(url, options = {}) {
-    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, fetchMode = null } = options;
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, fetchMode = null, allowRedirects = null, disableConditionalCache = false } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
@@ -1689,6 +1824,12 @@ class Session {
     if (fetchMode) {
       reqOptions.fetch_mode = fetchMode;
     }
+    if (allowRedirects !== null && allowRedirects !== undefined) {
+      reqOptions.follow_redirects = !!allowRedirects;
+    }
+    if (disableConditionalCache) {
+      reqOptions.disable_conditional_cache = true;
+    }
     const optionsJson = Object.keys(reqOptions).length > 0 ? JSON.stringify(reqOptions) : null;
 
     const bodyPtr = bodyBuffer || Buffer.alloc(0);
@@ -1713,7 +1854,7 @@ class Session {
    * @returns {Response} Response object
    */
   requestSync(method, url, options = {}) {
-    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, timeout = null, fetchMode = null } = options;
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, timeout = null, fetchMode = null, allowRedirects = null, disableConditionalCache = false } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
@@ -1756,6 +1897,8 @@ class Session {
     if (mergedHeaders) requestConfig.headers = mergedHeaders;
     if (timeout) requestConfig.timeout = timeout;
     if (fetchMode) requestConfig.fetch_mode = fetchMode;
+    if (allowRedirects !== null && allowRedirects !== undefined) requestConfig.follow_redirects = !!allowRedirects;
+    if (disableConditionalCache) requestConfig.disable_conditional_cache = true;
 
     const bodyPtr = bodyBuffer || Buffer.alloc(0);
     const bodyLen = bodyBuffer ? bodyBuffer.length : 0;
@@ -1786,7 +1929,7 @@ class Session {
    * @returns {Promise<Response>} Response object
    */
   get(url, options = {}) {
-    const { headers = null, params = null, cookies = null, auth = null, fetchMode = null, timeout = null } = options;
+    const { headers = null, params = null, cookies = null, auth = null, fetchMode = null, timeout = null, allowRedirects = null, disableConditionalCache = false, signal = null } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
@@ -1809,11 +1952,17 @@ class Session {
       // httpcloak_request_async — that path also uses time.Second).
       reqOptions.timeout = timeout;
     }
+    if (allowRedirects !== null && allowRedirects !== undefined) {
+      reqOptions.follow_redirects = !!allowRedirects;
+    }
+    if (disableConditionalCache) {
+      reqOptions.disable_conditional_cache = true;
+    }
     const optionsJson = Object.keys(reqOptions).length > 0 ? JSON.stringify(reqOptions) : null;
 
     // Register async request with callback manager
     const manager = getAsyncManager();
-    const { callbackId, promise } = manager.registerRequest(this._lib);
+    const { callbackId, promise } = manager.registerRequest(this._lib, signal);
 
     // Start async request
     this._lib.httpcloak_get_async(this._handle, url, optionsJson, callbackId);
@@ -1829,16 +1978,23 @@ class Session {
    * @returns {Promise<Response>} Response object
    */
   post(url, options = {}) {
-    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, fetchMode = null, timeout = null } = options;
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, fetchMode = null, timeout = null, allowRedirects = null, disableConditionalCache = false, signal = null } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
 
+    // bodyEncoding tells clib whether `body` is plain text or base64-encoded
+    // binary. Default "" = text. Anything that carries arbitrary bytes
+    // (Buffer, multipart) flows through as base64 so NUL bytes don't truncate
+    // the C string at the cgo boundary.
+    let bodyEncoding = "";
+
     // Handle multipart file upload
     if (files !== null) {
       const formData = (data !== null && typeof data === "object") ? data : null;
       const multipart = encodeMultipart(formData, files);
-      body = multipart.body.toString("latin1");
+      body = multipart.body.toString("base64");
+      bodyEncoding = "base64";
       mergedHeaders = mergedHeaders || {};
       mergedHeaders["Content-Type"] = multipart.contentType;
     }
@@ -1858,9 +2014,11 @@ class Session {
         mergedHeaders["Content-Type"] = "application/x-www-form-urlencoded";
       }
     }
-    // Handle Buffer body
+    // Handle Buffer body (binary payload). base64-encode so NUL bytes and
+    // non-UTF-8 sequences survive the cgo C-string round-trip intact.
     else if (Buffer.isBuffer(body)) {
-      body = body.toString("utf8");
+      body = body.toString("base64");
+      bodyEncoding = "base64";
     }
 
     // Use request auth if provided, otherwise fall back to session auth
@@ -1880,11 +2038,20 @@ class Session {
       // Public API: seconds. clib post_async path enforces in seconds.
       reqOptions.timeout = timeout;
     }
+    if (allowRedirects !== null && allowRedirects !== undefined) {
+      reqOptions.follow_redirects = !!allowRedirects;
+    }
+    if (disableConditionalCache) {
+      reqOptions.disable_conditional_cache = true;
+    }
+    if (bodyEncoding) {
+      reqOptions.body_encoding = bodyEncoding;
+    }
     const optionsJson = Object.keys(reqOptions).length > 0 ? JSON.stringify(reqOptions) : null;
 
     // Register async request with callback manager
     const manager = getAsyncManager();
-    const { callbackId, promise } = manager.registerRequest(this._lib);
+    const { callbackId, promise } = manager.registerRequest(this._lib, signal);
 
     // Start async request
     this._lib.httpcloak_post_async(this._handle, url, body, optionsJson, callbackId);
@@ -1901,16 +2068,22 @@ class Session {
    * @returns {Promise<Response>} Response object
    */
   request(method, url, options = {}) {
-    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, timeout = null, fetchMode = null } = options;
+    let { body = null, json = null, data = null, files = null, headers = null, params = null, cookies = null, auth = null, timeout = null, fetchMode = null, allowRedirects = null, disableConditionalCache = false, signal = null } = options;
 
     url = addParamsToUrl(url, params);
     let mergedHeaders = this._mergeHeaders(headers);
 
+    // bodyEncoding tells clib whether `body` is text or base64 binary.
+    // Binary payloads (Buffer / multipart) flow through as base64 so they
+    // survive JSON serialization + the cgo C-string boundary intact.
+    let bodyEncoding = "";
+
     // Handle multipart file upload
     if (files !== null) {
       const formData = (data !== null && typeof data === "object") ? data : null;
       const multipart = encodeMultipart(formData, files);
-      body = multipart.body.toString("latin1");
+      body = multipart.body.toString("base64");
+      bodyEncoding = "base64";
       mergedHeaders = mergedHeaders || {};
       mergedHeaders["Content-Type"] = multipart.contentType;
     }
@@ -1930,9 +2103,11 @@ class Session {
         mergedHeaders["Content-Type"] = "application/x-www-form-urlencoded";
       }
     }
-    // Handle Buffer body
+    // Handle Buffer body (binary payload). base64-encode so non-UTF-8 bytes
+    // and NUL bytes survive JSON.stringify + the C boundary.
     else if (Buffer.isBuffer(body)) {
-      body = body.toString("utf8");
+      body = body.toString("base64");
+      bodyEncoding = "base64";
     }
 
     // Use request auth if provided, otherwise fall back to session auth
@@ -1946,12 +2121,15 @@ class Session {
     };
     if (mergedHeaders) requestConfig.headers = mergedHeaders;
     if (body) requestConfig.body = body;
+    if (bodyEncoding) requestConfig.body_encoding = bodyEncoding;
     if (timeout) requestConfig.timeout = timeout;
     if (fetchMode) requestConfig.fetch_mode = fetchMode;
+    if (allowRedirects !== null && allowRedirects !== undefined) requestConfig.follow_redirects = !!allowRedirects;
+    if (disableConditionalCache) requestConfig.disable_conditional_cache = true;
 
     // Register async request with callback manager
     const manager = getAsyncManager();
-    const { callbackId, promise } = manager.registerRequest(this._lib);
+    const { callbackId, promise } = manager.registerRequest(this._lib, signal);
 
     // Start async request
     this._lib.httpcloak_request_async(this._handle, JSON.stringify(requestConfig), callbackId);
@@ -2099,6 +2277,122 @@ class Session {
     return this.getCookies();
   }
 
+  // ===========================================================================
+  // Conditional Cache and Redirect Runtime Control
+  // ===========================================================================
+
+  /**
+   * Drop the session's per-URL conditional-cache map (ETag / Last-Modified).
+   * The next request to each URL goes out without If-None-Match /
+   * If-Modified-Since headers. Cookies and TLS tickets are not touched.
+   */
+  clearCache() {
+    this._lib.httpcloak_session_clear_cache(this._handle);
+  }
+
+  /**
+   * Return a snapshot of session counters, timestamps and transport-level
+   * metrics. Useful for long-running scrapers that want per-session metrics
+   * scraped into Prometheus / Datadog / etc.
+   *
+   * Keys: id, preset, created_at (Unix ns), last_used (Unix ns),
+   * request_count, active, cookie_count, cache_entry_count, age_ns,
+   * idle_time_ns, transport_stats (per-protocol object).
+   *
+   * @returns {Object} Stats snapshot, or empty object if the session is closed.
+   */
+  stats() {
+    const ptr = this._lib.httpcloak_session_stats(this._handle);
+    const raw = resultToString(ptr);
+    if (!raw) return {};
+    try { return JSON.parse(raw); } catch { return {}; }
+  }
+
+  /**
+   * Return the time since the session last serviced a request, in seconds.
+   * Returns -1 if the session handle is invalid.
+   *
+   * @returns {number} Idle time in seconds (may be fractional).
+   */
+  idleTime() {
+    const ns = Number(this._lib.httpcloak_session_idle_time(this._handle));
+    if (ns < 0) return -1;
+    return ns / 1_000_000_000;
+  }
+
+  /**
+   * Return true if the session is still usable (close() has not been called
+   * and the handle is valid).
+   *
+   * @returns {boolean}
+   */
+  isActive() {
+    return this._lib.httpcloak_session_is_active(this._handle) === 1;
+  }
+
+  /**
+   * Reset the idle timer to now without issuing a request. Useful in
+   * long-running pools where an external heartbeat shouldn't let a session
+   * look idle to a reaper.
+   */
+  touch() {
+    this._lib.httpcloak_session_touch(this._handle);
+  }
+
+  /**
+   * Toggle the session's ETag / If-Modified-Since handling at runtime.
+   * When disabled, the session stops injecting cache validators on outgoing
+   * requests and stops storing them from responses; the existing cache map
+   * is preserved (re-enabling resumes using it). Pair with clearCache() to
+   * also wipe previously-stored validators.
+   * @param {boolean} enabled
+   */
+  setConditionalCache(enabled) {
+    this._lib.httpcloak_session_set_conditional_cache(this._handle, enabled ? 1 : 0);
+  }
+
+  /**
+   * Return the session's current conditional-cache state.
+   * @returns {boolean}
+   */
+  getConditionalCache() {
+    return this._lib.httpcloak_session_get_conditional_cache(this._handle) !== 0;
+  }
+
+  /**
+   * Toggle the session's redirect-following policy at runtime. The change
+   * takes effect on the next request and persists until set again.
+   * @param {boolean} enabled
+   */
+  setFollowRedirects(enabled) {
+    this._lib.httpcloak_session_set_follow_redirects(this._handle, enabled ? 1 : 0);
+  }
+
+  /**
+   * Return the session's current redirect-following policy.
+   * @returns {boolean}
+   */
+  getFollowRedirects() {
+    return this._lib.httpcloak_session_get_follow_redirects(this._handle) !== 0;
+  }
+
+  /**
+   * Update the session's redirect cap at runtime. Values of zero or below
+   * are ignored, leaving the prior cap (or the default of 10) in place.
+   * @param {number} max
+   */
+  setMaxRedirects(max) {
+    this._lib.httpcloak_session_set_max_redirects(this._handle, max);
+  }
+
+  /**
+   * Return the session's current redirect cap.
+   * @returns {number}
+   */
+  getMaxRedirects() {
+    return this._lib.httpcloak_session_get_max_redirects(this._handle);
+  }
+
   // ===========================================================================
   // Proxy Management
   // ===========================================================================
@@ -2395,7 +2689,7 @@ class Session {
    *   stream.close();
    */
   getStream(url, options = {}) {
-    const { params, headers, cookies, timeout } = options;
+    const { params, headers, cookies, timeout, allowRedirects = null, disableConditionalCache = false } = options;
 
     // Add params to URL
     if (params) {
@@ -2422,6 +2716,12 @@ class Session {
     if (timeout) {
       reqOptions.timeout = timeout;
     }
+    if (allowRedirects !== null && allowRedirects !== undefined) {
+      reqOptions.follow_redirects = !!allowRedirects;
+    }
+    if (disableConditionalCache) {
+      reqOptions.disable_conditional_cache = true;
+    }
     const optionsJson = Object.keys(reqOptions).length > 0 ? JSON.stringify(reqOptions) : null;
 
     // Start stream
@@ -2461,7 +2761,7 @@ class Session {
    * @returns {StreamResponse} - Streaming response for chunked reading
    */
   postStream(url, options = {}) {
-    const { body: bodyOpt, json: jsonBody, form, params, headers, cookies, timeout } = options;
+    const { body: bodyOpt, json: jsonBody, form, params, headers, cookies, timeout, allowRedirects = null, disableConditionalCache = false } = options;
 
     // Add params to URL
     if (params) {
@@ -2501,6 +2801,12 @@ class Session {
     if (timeout) {
       reqOptions.timeout = timeout;
     }
+    if (allowRedirects !== null && allowRedirects !== undefined) {
+      reqOptions.follow_redirects = !!allowRedirects;
+    }
+    if (disableConditionalCache) {
+      reqOptions.disable_conditional_cache = true;
+    }
     const optionsJson = Object.keys(reqOptions).length > 0 ? JSON.stringify(reqOptions) : null;
 
     // Start stream
@@ -2539,7 +2845,7 @@ class Session {
    * @returns {StreamResponse} - Streaming response for chunked reading
    */
   requestStream(method, url, options = {}) {
-    const { body, params, headers, cookies, timeout } = options;
+    const { body, params, headers, cookies, timeout, allowRedirects = null, disableConditionalCache = false } = options;
 
     // Add params to URL
     if (params) {
@@ -2572,6 +2878,12 @@ class Session {
     if (timeout) {
       requestConfig.timeout = timeout;
     }
+    if (allowRedirects !== null && allowRedirects !== undefined) {
+      requestConfig.follow_redirects = !!allowRedirects;
+    }
+    if (disableConditionalCache) {
+      requestConfig.disable_conditional_cache = true;
+    }
 
     // Start stream
     const streamHandle = this._lib.httpcloak_stream_request(this._handle, JSON.stringify(requestConfig));
@@ -2890,6 +3202,84 @@ class Session {
   patchFast(url, options = {}) {
     return this.requestFast("PATCH", url, options);
   }
+
+  /**
+   * Stream an arbitrary-sized body to the wire without buffering in memory.
+   *
+   * `chunks` is anything iterable that yields Buffer-shaped objects: an
+   * AsyncIterable&lt;Buffer&gt; (e.g. an `fs.createReadStream(path)`), an
+   * Iterable&lt;Buffer&gt; (e.g. an array), or a sync generator that yields
+   * Buffers. String chunks are auto-encoded as UTF-8.
+   *
+   * The Go side opens an `io.Pipe()` for the body when uploadStart returns;
+   * each chunk is written straight through with no base64 / no JSON wrapping.
+   * On error the partial upload is cancelled and the underlying connection
+   * closed; on success uploadFinish reads the full response and parses it
+   * into a regular `Response` (same shape as a normal post()).
+   *
+   * @param {string} method  HTTP method (POST / PUT / PATCH typically)
+   * @param {string} url
+   * @param {AsyncIterable&lt;Buffer&gt;|Iterable&lt;Buffer&gt;} chunks  Body chunks
+   * @param {Object} [options]
+   * @param {Object} [options.headers]
+   * @param {string} [options.contentType="application/octet-stream"]
+   * @param {number} [options.timeout]  Per-request timeout in ms
+   * @returns {Promise<Response>}
+   */
+  async uploadStream(method, url, chunks, options = {}) {
+    const { headers = null, contentType = "application/octet-stream", timeout = null } = options;
+    const mergedHeaders = this._mergeHeaders(headers) || {};
+    const optsJson = JSON.stringify({
+      method: method.toUpperCase(),
+      headers: mergedHeaders,
+      content_type: contentType,
+      ...(timeout ? { timeout } : {}),
+    });
+
+    const uploadHandle = this._lib.httpcloak_upload_start(this._handle, url, optsJson);
+    if (uploadHandle <= 0) {
+      throw new HTTPCloakError("Failed to start streaming upload");
+    }
+
+    const startTime = Date.now();
+    try {
+      for await (const chunk of chunks) {
+        const buf = Buffer.isBuffer(chunk)
+          ? chunk
+          : typeof chunk === "string"
+            ? Buffer.from(chunk, "utf8")
+            : Buffer.from(chunk);
+        if (buf.length === 0) continue;
+        const written = this._lib.httpcloak_upload_write_raw(uploadHandle, buf, buf.length);
+        if (written < 0) {
+          throw new HTTPCloakError("Failed to write upload chunk");
+        }
+      }
+
+      const resultPtr = this._lib.httpcloak_upload_finish(uploadHandle);
+      const elapsed = Date.now() - startTime;
+      const raw = resultToString(resultPtr);
+      if (!raw) {
+        throw new HTTPCloakError("Empty response from streaming upload");
+      }
+      const data = JSON.parse(raw);
+      if (data.error) {
+        throw new HTTPCloakError(data.error);
+      }
+      return new Response(data, elapsed);
+    } catch (err) {
+      try { this._lib.httpcloak_upload_cancel(uploadHandle); } catch { /* best-effort */ }
+      throw err;
+    }
+  }
+
+  /**
+   * Convenience wrapper: streaming POST. Same semantics as
+   * {@link uploadStream}('POST', ...).
+   */
+  postUpload(url, chunks, options = {}) {
+    return this.uploadStream("POST", url, chunks, options);
+  }
 }
 
 // =============================================================================
@@ -3223,6 +3613,41 @@ class LocalProxy {
     return result === 1;
   }
 
+  /**
+   * Return the IDs of every session currently registered on this proxy.
+   *
+   * These are the same IDs the X-HTTPCloak-Session header accepts for
+   * per-request session routing. Useful for sanity checks, GC of stale
+   * registrations in long-running processes, and operational dashboards.
+   *
+   * @returns {string[]} List of registered session IDs (empty if none).
+   */
+  listSessions() {
+    const resultPtr = this._lib.httpcloak_local_proxy_list_sessions(this._handle);
+    const raw = resultToString(resultPtr);
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed.map(String) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Return true if a session with the given ID is currently registered.
+   *
+   * Cheaper than listSessions() + .includes() when callers only need an
+   * existence check.
+   *
+   * @param {string} sessionId
+   * @returns {boolean}
+   */
+  hasSession(sessionId) {
+    if (!sessionId) return false;
+    return this._lib.httpcloak_local_proxy_has_session(this._handle, sessionId) === 1;
+  }
+
   /**
    * Stop the local proxy server.
    */

package/lib/index.mjs

@@ -22,10 +22,17 @@ export const Cookie = cjs.Cookie;
 export const RedirectInfo = cjs.RedirectInfo;
 export const HTTPCloakError = cjs.HTTPCloakError;
 export const SessionCacheBackend = cjs.SessionCacheBackend;
+export const PresetPool = cjs.PresetPool;
 
 // Presets
 export const Preset = cjs.Preset;
 
+// Custom preset loading
+export const loadPreset = cjs.loadPreset;
+export const loadPresetFromJSON = cjs.loadPresetFromJSON;
+export const unregisterPreset = cjs.unregisterPreset;
+export const describePreset = cjs.describePreset;
+
 // Configuration
 export const configure = cjs.configure;
 export const configureSessionCache = cjs.configureSessionCache;

package/npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/darwin-arm64",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "HTTPCloak native binary for darwin arm64",
   "os": [
     "darwin"

package/npm/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/darwin-x64",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "HTTPCloak native binary for darwin x64",
   "os": [
     "darwin"

package/npm/linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/linux-arm64",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "HTTPCloak native binary for linux arm64",
   "os": [
     "linux"

package/npm/linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/linux-x64",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "HTTPCloak native binary for linux x64",
   "os": [
     "linux"

package/npm/win32-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@httpcloak/win32-x64",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "HTTPCloak native binary for win32 x64",
   "os": [
     "win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "httpcloak",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "Browser fingerprint emulation HTTP client with HTTP/1.1, HTTP/2, and HTTP/3 support",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
@@ -49,12 +49,11 @@
     "koffi": "^2.9.0"
   },
   "optionalDependencies": {
-    "@httpcloak/darwin-arm64": "1.6.5",
-    "@httpcloak/darwin-x64": "1.6.5",
-    "@httpcloak/linux-arm64": "1.6.5",
-    "@httpcloak/linux-x64": "1.6.5",
-    "@httpcloak/win32-arm64": "1.6.5",
-    "@httpcloak/win32-x64": "1.6.5"
+    "@httpcloak/darwin-arm64": "1.6.7",
+    "@httpcloak/darwin-x64": "1.6.7",
+    "@httpcloak/linux-arm64": "1.6.7",
+    "@httpcloak/linux-x64": "1.6.7",
+    "@httpcloak/win32-x64": "1.6.7"
   },
   "devDependencies": {
     "@types/node": "^25.1.0",

package/scripts/setup-npm-packages.js

@@ -8,13 +8,17 @@ const path = require("path");
 
 const VERSION = "1.4.0";
 
+// Platforms we actually build and publish via CI's npm-platform matrix.
+// Keep in sync with .github/workflows/bindings.yml's `npm_platform` matrix —
+// adding a row here without adding it to the matrix means npm install will
+// fail with an unresolvable optional dependency on yarn classic / pnpm
+// strict modes.
 const PLATFORMS = [
   { name: "linux-x64", os: "linux", cpu: "x64", libName: "libhttpcloak-linux-amd64.so" },
   { name: "linux-arm64", os: "linux", cpu: "arm64", libName: "libhttpcloak-linux-arm64.so" },
   { name: "darwin-x64", os: "darwin", cpu: "x64", libName: "libhttpcloak-darwin-amd64.dylib" },
   { name: "darwin-arm64", os: "darwin", cpu: "arm64", libName: "libhttpcloak-darwin-arm64.dylib" },
   { name: "win32-x64", os: "win32", cpu: "x64", libName: "libhttpcloak-windows-amd64.dll" },
-  { name: "win32-arm64", os: "win32", cpu: "arm64", libName: "libhttpcloak-windows-arm64.dll" },
 ];
 
 const npmDir = path.join(__dirname, "..", "npm");

package/npm/win32-arm64/lib.js

@@ -1,3 +0,0 @@
-// Auto-generated - exports path to native library
-const path = require("path");
-module.exports = path.join(__dirname, "libhttpcloak-windows-arm64.dll");

package/npm/win32-arm64/lib.mjs

@@ -1,6 +0,0 @@
-// Auto-generated - exports path to native library (ESM)
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-export default join(__dirname, "libhttpcloak-windows-arm64.dll");

package/npm/win32-arm64/package.json

@@ -1,27 +0,0 @@
-{
-  "name": "@httpcloak/win32-arm64",
-  "version": "1.6.5",
-  "description": "HTTPCloak native binary for win32 arm64",
-  "os": [
-    "win32"
-  ],
-  "cpu": [
-    "arm64"
-  ],
-  "main": "lib.js",
-  "module": "lib.mjs",
-  "exports": {
-    ".": {
-      "import": "./lib.mjs",
-      "require": "./lib.js"
-    }
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/sardanioss/httpcloak"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}