wreq-js 1.7.0 → 2.0.0

package/dist/wreq-js.d.cts

@@ -76,7 +76,35 @@ type BodyInit = string | ArrayBuffer | ArrayBufferView | URLSearchParams | Buffe
 /**
  * Details about why a WebSocket connection closed.
  */
+type WebSocketBinaryType = "nodebuffer" | "arraybuffer" | "blob";
+type WebSocketEventType = "open" | "message" | "close" | "error";
+interface WebSocketOpenEvent {
+    type: "open";
+    isTrusted: false;
+    timeStamp: number;
+    target: WebSocket;
+    currentTarget: WebSocket;
+}
+interface WebSocketMessageEvent {
+    type: "message";
+    isTrusted: false;
+    timeStamp: number;
+    data: string | Buffer | ArrayBuffer | Blob;
+    target: WebSocket;
+    currentTarget: WebSocket;
+}
+interface WebSocketErrorEvent {
+    type: "error";
+    isTrusted: false;
+    timeStamp: number;
+    message?: string;
+    target: WebSocket;
+    currentTarget: WebSocket;
+}
 interface WebSocketCloseEvent {
+    type: "close";
+    isTrusted: false;
+    timeStamp: number;
     /**
      * WebSocket close status code (RFC 6455).
      */
@@ -85,10 +113,13 @@ interface WebSocketCloseEvent {
      * UTF-8 close reason sent by the peer.
      */
     reason: string;
+    wasClean: boolean;
+    target: WebSocket;
+    currentTarget: WebSocket;
 }
 /**
- * Options for configuring a fetch request. Compatible with the standard Fetch API
- * with additional wreq-specific extensions for browser impersonation, proxies, and timeouts.
+ * Options for configuring a fetch style request with wreq-specific extensions
+ * for browser impersonation, proxies, sessions, and timeouts.
  *
  * @example
  * ```typescript
@@ -133,27 +164,28 @@ interface RequestInit {
     transport?: Transport;
     /**
      * Browser profile to impersonate for this request.
-     * Automatically applies browser-specific headers, TLS fingerprints, and HTTP/2 settings.
+     * Applies browser profile behavior handled by the native layer.
      * Ignored when `transport` is provided.
      * @default 'chrome_142'
      */
     browser?: BrowserProfile;
     /**
      * Operating system to emulate for this request.
-     * Influences platform-specific headers and TLS fingerprints.
+     * Influences platform-specific behavior handled by the native layer.
      * Ignored when `transport` is provided.
      * @default 'macos'
      */
     os?: EmulationOS;
     /**
      * Proxy URL to route the request through (e.g., 'http://proxy.example.com:8080').
-     * Supports HTTP and SOCKS5 proxies.
+     * Proxy support depends on the native layer and proxy scheme.
      * Ignored when `transport` is provided.
      */
     proxy?: string;
     /**
      * Request timeout in milliseconds. If the request takes longer than this value,
-     * it will be aborted. No timeout is applied by default.
+     * it will be aborted.
+     * @default 30000
      */
     timeout?: number;
     /**
@@ -208,20 +240,14 @@ interface CreateSessionOptions {
     defaultHeaders?: HeadersInit;
     /**
      * Browser profile to bind to this session. Defaults to 'chrome_142'.
-     *
-     * @deprecated Use {@link createTransport} and pass the transport to requests instead.
      */
     browser?: BrowserProfile;
     /**
      * Operating system to bind to this session. Defaults to 'macos'.
-     *
-     * @deprecated Use {@link createTransport} and pass the transport to requests instead.
      */
     os?: EmulationOS;
     /**
      * Optional proxy for every request made through the session.
-     *
-     * @deprecated Use {@link createTransport} and pass the transport to requests instead.
      */
     proxy?: string;
     /**
@@ -233,8 +259,6 @@ interface CreateSessionOptions {
      * Disable HTTPS certificate verification. When enabled, self-signed and invalid
      * certificates will be accepted for all requests made through this session.
      *
-     * @deprecated Use {@link createTransport} and pass the transport to requests instead.
-     *
      * # Warning
      *
      * You should think very carefully before using this method. If invalid
@@ -315,7 +339,7 @@ interface RequestOptions {
     url: string;
     /**
      * Browser profile to impersonate.
-     * Automatically applies browser-specific headers, TLS fingerprints, and HTTP/2 settings.
+     * Applies browser profile behavior handled by the native layer.
      * @default 'chrome_142'
      */
     browser?: BrowserProfile;
@@ -337,7 +361,7 @@ interface RequestOptions {
     /**
      * Request body data (for POST, PUT, PATCH requests).
      */
-    body?: Buffer;
+    body?: BodyInit | null;
     /**
      * Transport instance to use for this request. When provided, transport-level
      * options such as `browser`, `os`, `proxy`, and `insecure` must not be set.
@@ -345,7 +369,7 @@ interface RequestOptions {
     transport?: Transport;
     /**
      * Proxy URL to route the request through (e.g., 'http://proxy.example.com:8080').
-     * Supports HTTP and SOCKS5 proxies.
+     * Proxy support depends on the native layer and proxy scheme.
      */
     proxy?: string;
     /**
@@ -355,9 +379,22 @@ interface RequestOptions {
     redirect?: "follow" | "manual" | "error";
     /**
      * Request timeout in milliseconds. If the request takes longer than this value,
-     * it will be aborted. No timeout is applied by default.
+     * it will be aborted.
+     * @default 30000
      */
     timeout?: number;
+    /**
+     * Signal used to abort the request.
+     */
+    signal?: AbortSignal | null;
+    /**
+     * Session instance to bind this request to.
+     */
+    session?: Session;
+    /**
+     * Controls cookie scoping behavior for this request.
+     */
+    cookieMode?: CookieMode;
     /**
      * Identifier for the session that should handle this request.
      * @internal
@@ -438,27 +475,17 @@ interface NativeResponse {
  *
  * @example
  * ```typescript
- * const ws = await createWebSocket({
- *   url: 'wss://echo.websocket.org',
+ * const ws = await websocket('wss://example.com/socket', {
  *   browser: 'chrome_142',
  *   headers: { 'Authorization': 'Bearer token' },
- *   onMessage: (data) => {
- *     console.log('Received:', data);
- *   },
- *   onClose: (event) => {
- *     console.log('Connection closed:', event.code, event.reason);
- *   },
- *   onError: (error) => {
- *     console.error('WebSocket error:', error);
- *   }
  * });
+ *
+ * ws.onmessage = (event) => {
+ *   console.log('Received:', event.data);
+ * };
  * ```
  */
 interface WebSocketOptions {
-    /**
-     * The WebSocket URL to connect to. Must use wss:// (secure) or ws:// (insecure) protocol.
-     */
-    url: string;
     /**
      * Browser profile to impersonate for the WebSocket upgrade request.
      * Automatically applies browser-specific headers and TLS fingerprints.
@@ -474,28 +501,60 @@ interface WebSocketOptions {
      * Additional headers to send with the WebSocket upgrade request.
      * Common headers include Authorization, Origin, or custom application headers.
      */
-    headers?: Record<string, string> | HeaderTuple[];
+    headers?: HeadersInit;
     /**
      * Proxy URL to route the connection through (e.g., 'http://proxy.example.com:8080').
-     * Supports HTTP and SOCKS5 proxies.
+     * Proxy support depends on the native layer and proxy scheme.
      */
     proxy?: string;
     /**
-     * Callback function invoked when a message is received from the server.
-     * The data parameter will be a string for text frames or a Buffer for binary frames.
-     *
-     * @param data - The received message as a string or Buffer
+     * Optional subprotocols for compatibility with the WHATWG WebSocket constructor.
+     * Values are validated for non-empty, unique entries and sent in
+     * the `Sec-WebSocket-Protocol` handshake header.
      */
-    onMessage: (data: string | Buffer) => void;
+    protocols?: string | string[];
+    /**
+     * Controls the binary payload type exposed via `MessageEvent.data`.
+     * - "nodebuffer": delivers Node.js Buffer instances (default)
+     * - "arraybuffer": delivers ArrayBuffer instances
+     * - "blob": delivers Blob instances
+     */
+    binaryType?: WebSocketBinaryType;
+}
+interface LegacyWebSocketOptions extends WebSocketOptions {
+    /**
+     * @deprecated Use `websocket(url, options)` or `new WebSocket(...)`.
+     */
+    url: string;
     /**
-     * Callback function invoked when the WebSocket connection is closed.
-     * This is called for both clean closes and connection errors.
+     * @deprecated Use `onmessage` or `addEventListener("message", ...)`.
+     */
+    onMessage?: (data: string | Buffer) => void;
+    /**
+     * @deprecated Use `onclose` or `addEventListener("close", ...)`.
      */
     onClose?: (event: WebSocketCloseEvent) => void;
     /**
-     * Callback function invoked when a connection or protocol error occurs.
-     *
-     * @param error - A string describing the error that occurred
+     * @deprecated Use `onerror` or `addEventListener("error", ...)`.
+     */
+    onError?: (error: string) => void;
+}
+type SessionWebSocketOptions = Omit<WebSocketOptions, "browser" | "os" | "proxy">;
+interface LegacySessionWebSocketOptions extends SessionWebSocketOptions {
+    /**
+     * @deprecated Use `session.websocket(url, options)`.
+     */
+    url: string;
+    /**
+     * @deprecated Use `onmessage` or `addEventListener("message", ...)`.
+     */
+    onMessage?: (data: string | Buffer) => void;
+    /**
+     * @deprecated Use `onclose` or `addEventListener("close", ...)`.
+     */
+    onClose?: (event: WebSocketCloseEvent) => void;
+    /**
+     * @deprecated Use `onerror` or `addEventListener("error", ...)`.
      */
     onError?: (error: string) => void;
 }
@@ -513,6 +572,16 @@ interface NativeWebSocketConnection {
      * @internal
      */
     _id: number;
+    /**
+     * Selected subprotocol returned by the server, when present.
+     * @internal
+     */
+    protocol?: string;
+    /**
+     * Negotiated extension string returned by the server, when present.
+     * @internal
+     */
+    extensions?: string;
 }
 /**
  * Error thrown when a request fails. This can occur due to network errors,
@@ -529,10 +598,14 @@ interface NativeWebSocketConnection {
  * }
  * ```
  */
-declare class RequestError extends Error {
+declare class RequestError extends TypeError {
     constructor(message: string);
 }
 
+interface NativeWebSocketCloseEvent {
+    code: number;
+    reason: string;
+}
 type SessionDefaults = {
     browser: BrowserProfile;
     os: EmulationOS;
@@ -543,6 +616,24 @@ type SessionDefaults = {
     transportId?: string;
     ownsTransport?: boolean;
 };
+type LegacyWebSocketCallbacks = {
+    onMessage?: (data: string | Buffer) => void;
+    onClose?: (event: WebSocketCloseEvent) => void;
+    onError?: (error: string) => void;
+};
+type WebSocketOpenDispatchMode = "automatic" | "deferred";
+type InternalWebSocketInit = {
+    readonly _internal: true;
+    url: string;
+    options: WebSocketOptions;
+    openDispatchMode: WebSocketOpenDispatchMode;
+    connect: (callbacks: {
+        onMessage: (data: string | Buffer) => void;
+        onClose: (event: NativeWebSocketCloseEvent) => void;
+        onError: (message: string) => void;
+    }) => Promise<NativeWebSocketConnection>;
+    legacyCallbacks: LegacyWebSocketCallbacks | undefined;
+};
 declare class Headers implements Iterable<[string, string]> {
     private readonly store;
     constructor(init?: HeadersInit);
@@ -591,6 +682,8 @@ declare class Response {
     json<T = unknown>(): Promise<T>;
     arrayBuffer(): Promise<ArrayBuffer>;
     text(): Promise<string>;
+    blob(): Promise<Blob>;
+    formData(): Promise<FormData>;
     clone(): Response;
     private assertBodyAvailable;
     private consumeBody;
@@ -613,27 +706,36 @@ declare class Session implements SessionHandle {
     getDefaults(): SessionDefaults;
     /** @internal */
     _defaultsRef(): SessionDefaults;
-    fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
     clearCookies(): Promise<void>;
+    /**
+     * Create a WebSocket connection that shares this session's cookies and TLS configuration.
+     *
+     * @param urlOrOptions - WebSocket URL or legacy options object
+     * @param options - Session WebSocket options
+     * @returns Promise that resolves to the WebSocket instance
+     */
+    websocket(url: string | URL, options?: SessionWebSocketOptions): Promise<WebSocket>;
+    websocket(options: LegacySessionWebSocketOptions): Promise<WebSocket>;
     close(): Promise<void>;
 }
 /**
  * Fetch-compatible entry point that adds browser impersonation controls.
  *
- * **Important:** The default fetch is isolated and non-persistent by design. Each request
- * uses a fresh connection with no shared state (cookies, TLS sessions). This prevents
- * TLS fingerprint leakage between requests.
+ * **Important:** The default fetch path is isolated and non-persistent by design.
+ * Each call uses an isolated request context, so cookies are not shared across calls.
+ * Connection and TLS reuse behavior is handled by the native layer.
  *
  * **Use {@link createSession} or {@link withSession} if you need:**
  * - Cookie persistence across requests
- * - TLS connection reuse for performance
- * - Shared connection state
+ * - Shared session defaults across requests
+ * - A single session context for multi-step flows
  *
  * **Concurrency:** The core is unthrottled by design. Callers are expected to implement
  * their own concurrency control (e.g., p-limit) if needed. Built-in throttling would
  * reduce performance for high-throughput workloads.
  *
- * @param input - Request URL (string or URL instance)
+ * @param input - Request URL (string or URL) or a Request object
  * @param init - Fetch-compatible init options
  *
  * @example
@@ -648,7 +750,7 @@ declare class Session implements SessionHandle {
  * });
  * ```
  */
-declare function fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+declare function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
 declare function createTransport(options?: CreateTransportOptions): Promise<Transport>;
 declare function createSession(options?: CreateSessionOptions): Promise<Session>;
 declare function withSession<T>(fn: (session: Session) => Promise<T> | T, options?: CreateSessionOptions): Promise<T>;
@@ -679,64 +781,107 @@ declare function getOperatingSystems(): EmulationOS[];
 /**
  * Convenience helper for GET requests using {@link fetch}.
  */
-declare function get(url: string, init?: Omit<RequestInit, "method">): Promise<Response>;
+declare function get(url: string | URL | Request, init?: Omit<RequestInit, "method">): Promise<Response>;
 /**
  * Convenience helper for POST requests using {@link fetch}.
  */
-declare function post(url: string, body?: BodyInit | null, init?: Omit<RequestInit, "method" | "body">): Promise<Response>;
+declare function post(url: string | URL | Request, body?: BodyInit | null, init?: Omit<RequestInit, "method" | "body">): Promise<Response>;
+type WebSocketAddEventListenerOptions = boolean | {
+    once?: boolean;
+    signal?: AbortSignal | null;
+};
 /**
- * WebSocket connection class
- *
- * @example
- * ```typescript
- * import { websocket } from 'wreq-js';
- *
- * const ws = await websocket({
- *   url: 'wss://echo.websocket.org',
- *   browser: 'chrome_142',
- *   onMessage: (data) => {
- *     console.log('Received:', data);
- *   },
- *   onClose: (event) => {
- *     console.log('Connection closed:', event.code, event.reason);
- *   },
- *   onError: (error) => {
- *     console.error('Error:', error);
- *   }
- * });
- *
- * // Send text message
- * await ws.send('Hello World');
- *
- * // Send binary message
- * await ws.send(Buffer.from([1, 2, 3]));
- *
- * // Close connection
- * await ws.close();
- * ```
+ * WHATWG-style WebSocket API with async connection establishment.
  */
 declare class WebSocket {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly url: string;
+    protocol: string;
+    extensions: string;
+    readyState: number;
+    private _binaryType;
+    private _bufferedAmount;
+    private _onopen;
+    private _onmessage;
+    private _onclose;
+    private _onerror;
+    private _onHandlerOrder;
+    private _listenerOrderCounter;
+    private readonly _listeners;
+    private readonly _legacyCallbacks;
+    private readonly _openDispatchMode;
     private _connection;
+    private _connectPromise;
+    private _closeOptions;
     private _finalizerToken;
-    private _closed;
-    private _closing;
-    constructor(connection: NativeWebSocketConnection);
-    /**
-     * Send a message (text or binary)
-     */
-    send(data: string | Buffer | ArrayBuffer | ArrayBufferView): Promise<void>;
-    /**
-     * Close the WebSocket connection
-     */
-    close(): Promise<void>;
+    private _openEventDispatched;
+    private _openEventQueued;
+    private _closeEventDispatched;
+    private _nativeCloseStarted;
+    private _pendingMessages;
+    private _sendChain;
+    constructor(init: InternalWebSocketInit);
+    constructor(url: string | URL, protocols?: string | string[]);
+    constructor(url: string | URL, protocols?: string | string[], options?: WebSocketOptions);
+    constructor(url: string | URL, options?: WebSocketOptions);
+    get binaryType(): WebSocketBinaryType;
+    set binaryType(value: WebSocketBinaryType);
+    get bufferedAmount(): number;
+    get onopen(): ((this: WebSocket, event: WebSocketOpenEvent) => void) | null;
+    set onopen(listener: ((this: WebSocket, event: WebSocketOpenEvent) => void) | null);
+    get onmessage(): ((this: WebSocket, event: WebSocketMessageEvent) => void) | null;
+    set onmessage(listener: ((this: WebSocket, event: WebSocketMessageEvent) => void) | null);
+    get onclose(): ((this: WebSocket, event: WebSocketCloseEvent) => void) | null;
+    set onclose(listener: ((this: WebSocket, event: WebSocketCloseEvent) => void) | null);
+    get onerror(): ((this: WebSocket, event: WebSocketErrorEvent) => void) | null;
+    set onerror(listener: ((this: WebSocket, event: WebSocketErrorEvent) => void) | null);
+    static _connectWithInit(init: InternalWebSocketInit): Promise<WebSocket>;
+    private static buildStandaloneInit;
+    private connect;
+    private _waitUntilConnected;
+    private scheduleOpenEventAfterConnect;
+    private scheduleOpenEventAfterAwait;
+    private scheduleOpenEventWithDepth;
+    private releaseConnectionTracking;
+    private toMessageEventData;
+    private invokeListener;
+    private createBaseEvent;
+    private getOnHandler;
+    private getOnHandlerOrder;
+    private getListenerMap;
+    private dispatchEvent;
+    private dispatchOpenEvent;
+    private dispatchMessageEvent;
+    private dispatchCloseEvent;
+    private dispatchErrorEvent;
+    private handleNativeMessage;
+    private handleNativeError;
+    private handleNativeClose;
+    private finalizeClosed;
+    private startNativeClose;
+    addEventListener(type: "open", listener: ((event: WebSocketOpenEvent) => void) | null, options?: WebSocketAddEventListenerOptions): void;
+    addEventListener(type: "message", listener: ((event: WebSocketMessageEvent) => void) | null, options?: WebSocketAddEventListenerOptions): void;
+    addEventListener(type: "close", listener: ((event: WebSocketCloseEvent) => void) | null, options?: WebSocketAddEventListenerOptions): void;
+    addEventListener(type: "error", listener: ((event: WebSocketErrorEvent) => void) | null, options?: WebSocketAddEventListenerOptions): void;
+    addEventListener(type: string, listener: unknown, options?: WebSocketAddEventListenerOptions): void;
+    removeEventListener(type: "open", listener: ((event: WebSocketOpenEvent) => void) | null): void;
+    removeEventListener(type: "message", listener: ((event: WebSocketMessageEvent) => void) | null): void;
+    removeEventListener(type: "close", listener: ((event: WebSocketCloseEvent) => void) | null): void;
+    removeEventListener(type: "error", listener: ((event: WebSocketErrorEvent) => void) | null): void;
+    removeEventListener(type: string, listener: unknown): void;
+    private getSendByteLength;
+    private normalizeSendPayload;
+    send(data: string | Buffer | ArrayBuffer | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
 }
 /**
- * Create a WebSocket connection with browser impersonation
- *
- * @param options - WebSocket options
- * @returns Promise that resolves to the WebSocket instance
+ * Create a WebSocket connection with browser impersonation.
  */
-declare function websocket(options: WebSocketOptions): Promise<WebSocket>;
+declare function websocket(url: string | URL, options?: WebSocketOptions): Promise<WebSocket>;
+declare function websocket(options: LegacyWebSocketOptions): Promise<WebSocket>;
 
 declare const _default: {
     fetch: typeof fetch;
@@ -754,6 +899,7 @@ declare const _default: {
     Response: typeof Response;
     Transport: typeof Transport;
     Session: typeof Session;
+    RequestError: typeof RequestError;
 };
 
-export { type BodyInit, type BrowserProfile, type CookieMode, type CreateSessionOptions, type CreateTransportOptions, type EmulationOS, Headers, type HeadersInit, RequestError, type RequestInit, type RequestOptions, Response, Session, type SessionHandle, Transport, WebSocket, type WebSocketOptions, createSession, createTransport, _default as default, fetch, get, getOperatingSystems, getProfiles, post, request, websocket, withSession };
+export { type BodyInit, type BrowserProfile, type CookieMode, type CreateSessionOptions, type CreateTransportOptions, type EmulationOS, Headers, type HeadersInit, RequestError, type RequestInit, type RequestOptions, Response, Session, type SessionHandle, type SessionWebSocketOptions, Transport, WebSocket, type WebSocketBinaryType, type WebSocketCloseEvent, type WebSocketErrorEvent, type WebSocketEventType, type WebSocketMessageEvent, type WebSocketOpenEvent, type WebSocketOptions, createSession, createTransport, _default as default, fetch, get, getOperatingSystems, getProfiles, post, request, websocket, withSession };