nlcurl 0.7.0 → 0.9.0

package/dist/utils/url.d.ts

@@ -1,62 +1,55 @@
 /**
- * Resolves `relative` against `base`. When `base` is `undefined` or the
- * resolution fails, `relative` is returned as-is.
+ * Resolve a relative URL against an optional base.
  *
- * @param {string | undefined} base     - Base URL string.
- * @param {string}             relative - Relative or absolute URL to resolve.
- * @returns {string} The resolved absolute URL, or `relative` if resolution fails.
+ * @param {string | undefined} base - Base URL string.
+ * @param {string} relative - Relative or absolute URL string.
+ * @returns {string} Resolved absolute URL string.
  */
 export declare function resolveURL(base: string | undefined, relative: string): string;
 /**
- * Appends `params` as query-string parameters to `url`. Existing parameters in
- * the URL are preserved. `undefined` and `null` values are omitted.
+ * Append query parameters to a URL string.
  *
- * @param {string}                                        url    - Base URL.
- * @param {Record<string, string | number | boolean>}     [params] - Key-value pairs to append.
- * @returns {string} URL with appended query parameters.
+ * @param {string} url - Base URL string.
+ * @param {Record<string, string | number | boolean>} [params] - Key-value pairs to append.
+ * @returns {string} URL string with appended query parameters.
  */
 export declare function appendParams(url: string, params?: Record<string, string | number | boolean>): string;
 /**
- * Parses `raw` into a `URL` object.
+ * Parse a URL string into a `URL` object.
  *
- * @param {string} raw - Absolute URL string to parse.
- * @returns {URL} Parsed URL.
- * @throws {TypeError} If `raw` is not a valid absolute URL.
+ * @param {string} raw - Raw URL string.
+ * @returns {URL} Parsed `URL` instance.
  */
 export declare function parseURL(raw: string): URL;
 /**
- * Returns the origin of `url` in `scheme://hostname:port` form. The port is
- * always included explicitly, defaulting to `443` for `https:` and `80` for
- * `http:`.
+ * Extract the origin (scheme + hostname + port) from a URL.
  *
  * @param {string} url - Absolute URL string.
  * @returns {string} Origin string (e.g. `"https://example.com:443"`).
  */
 export declare function originOf(url: string): string;
 /**
- * Extracts the hostname from `url` for use as the TLS SNI server-name value.
+ * Extract the hostname for TLS SNI from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Hostname without port (e.g. `"example.com"`).
+ * @returns {string} Hostname string.
  */
 export declare function sniHost(url: string): string;
 /**
- * Extracts the host and port from `url`. The port defaults to `443` for
- * `https:` and `80` for `http:` when not explicitly specified in the URL.
+ * Extract the hostname and port from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {{ host: string; port: number }} Hostname and numeric port.
+ * @returns {{ host: string; port: number }} Object with `host` and numeric `port`.
  */
 export declare function hostPort(url: string): {
     host: string;
     port: number;
 };
 /**
- * Returns the path and query string of `url` suitable for use as the
- * request-target in an HTTP/1.1 request line.
+ * Extract the request path (pathname + search) from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Path + query string (e.g. `"/search?q=hello"`).
+ * @returns {string} Path string suitable for an HTTP request line.
  */
 export declare function requestPath(url: string): string;
 //# sourceMappingURL=url.d.ts.map

package/dist/utils/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO7E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,CASpG;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOpE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C"}
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO7E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,CASpG;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOpE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/utils/url.js

@@ -1,10 +1,9 @@
 /**
- * Resolves `relative` against `base`. When `base` is `undefined` or the
- * resolution fails, `relative` is returned as-is.
+ * Resolve a relative URL against an optional base.
  *
- * @param {string | undefined} base     - Base URL string.
- * @param {string}             relative - Relative or absolute URL to resolve.
- * @returns {string} The resolved absolute URL, or `relative` if resolution fails.
+ * @param {string | undefined} base - Base URL string.
+ * @param {string} relative - Relative or absolute URL string.
+ * @returns {string} Resolved absolute URL string.
  */
 export function resolveURL(base, relative) {
     if (!base)
@@ -17,12 +16,11 @@ export function resolveURL(base, relative) {
     }
 }
 /**
- * Appends `params` as query-string parameters to `url`. Existing parameters in
- * the URL are preserved. `undefined` and `null` values are omitted.
+ * Append query parameters to a URL string.
  *
- * @param {string}                                        url    - Base URL.
- * @param {Record<string, string | number | boolean>}     [params] - Key-value pairs to append.
- * @returns {string} URL with appended query parameters.
+ * @param {string} url - Base URL string.
+ * @param {Record<string, string | number | boolean>} [params] - Key-value pairs to append.
+ * @returns {string} URL string with appended query parameters.
  */
 export function appendParams(url, params) {
     if (!params || Object.keys(params).length === 0)
@@ -36,19 +34,16 @@ export function appendParams(url, params) {
     return parsed.toString();
 }
 /**
- * Parses `raw` into a `URL` object.
+ * Parse a URL string into a `URL` object.
  *
- * @param {string} raw - Absolute URL string to parse.
- * @returns {URL} Parsed URL.
- * @throws {TypeError} If `raw` is not a valid absolute URL.
+ * @param {string} raw - Raw URL string.
+ * @returns {URL} Parsed `URL` instance.
  */
 export function parseURL(raw) {
     return new URL(raw);
 }
 /**
- * Returns the origin of `url` in `scheme://hostname:port` form. The port is
- * always included explicitly, defaulting to `443` for `https:` and `80` for
- * `http:`.
+ * Extract the origin (scheme + hostname + port) from a URL.
  *
  * @param {string} url - Absolute URL string.
  * @returns {string} Origin string (e.g. `"https://example.com:443"`).
@@ -59,20 +54,19 @@ export function originOf(url) {
     return `${u.protocol}//${u.hostname}:${port}`;
 }
 /**
- * Extracts the hostname from `url` for use as the TLS SNI server-name value.
+ * Extract the hostname for TLS SNI from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Hostname without port (e.g. `"example.com"`).
+ * @returns {string} Hostname string.
  */
 export function sniHost(url) {
     return new URL(url).hostname;
 }
 /**
- * Extracts the host and port from `url`. The port defaults to `443` for
- * `https:` and `80` for `http:` when not explicitly specified in the URL.
+ * Extract the hostname and port from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {{ host: string; port: number }} Hostname and numeric port.
+ * @returns {{ host: string; port: number }} Object with `host` and numeric `port`.
  */
 export function hostPort(url) {
     const u = new URL(url);
@@ -83,11 +77,10 @@ export function hostPort(url) {
     };
 }
 /**
- * Returns the path and query string of `url` suitable for use as the
- * request-target in an HTTP/1.1 request line.
+ * Extract the request path (pathname + search) from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Path + query string (e.g. `"/search?q=hello"`).
+ * @returns {string} Path string suitable for an HTTP request line.
  */
 export function requestPath(url) {
     const u = new URL(url);

package/dist/utils/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,QAAgB;IACnE,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,MAAkD;IAC1F,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAE5D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,WAAW,GAAG,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,QAAQ;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,QAAgB;IACnE,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,MAAkD;IAC1F,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAE5D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,WAAW,GAAG,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,QAAQ;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW;KAClD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC"}

package/dist/ws/client.d.ts

@@ -1,104 +1,86 @@
 import { EventEmitter } from "node:events";
-/**
- * Options for creating a {@link WebSocketClient} connection.
- *
- * @typedef  {Object}    WebSocketOptions
- * @property {string}    [impersonate]  - Browser profile name for fingerprint impersonation.
- * @property {boolean}   [stealth]      - Use the stealth TLS engine for byte-level fingerprinting.
- * @property {Record<string, string>} [headers] - Additional HTTP upgrade request headers.
- * @property {string[]}  [protocols]    - Sub-protocol names to negotiate.
- * @property {boolean}   [insecure]     - Skip TLS certificate validation for `wss:` connections.
- * @property {number}    [timeout]      - Connection timeout in milliseconds.
- */
+/** Configuration options for a WebSocket connection. */
 export interface WebSocketOptions {
+    /** Browser profile name to impersonate for TLS fingerprinting. */
     impersonate?: string;
+    /** Use the stealth TLS engine for fingerprint impersonation. */
     stealth?: boolean;
+    /** Additional HTTP headers to include in the upgrade request. */
     headers?: Record<string, string>;
+    /** Subprotocols to offer during the upgrade handshake. */
     protocols?: string[];
+    /** Skip TLS certificate verification. */
     insecure?: boolean;
+    /** Connection timeout in milliseconds. */
     timeout?: number;
-    /** Enable `permessage-deflate` compression (RFC 7692). Default: `false`. */
+    /** Enable per-message deflate compression. */
     compress?: boolean;
 }
-/**
- * WebSocket connection state.
- *
- * @typedef {'connecting' | 'open' | 'closing' | 'closed'} WebSocketState
- */
+/** Current lifecycle state of the WebSocket connection. */
 export type WebSocketState = "connecting" | "open" | "closing" | "closed";
-/**
- * Typed event map for {@link WebSocketClient}.
- *
- * @typedef  {Object}                           WebSocketEvents
- * @property {[]}                               open    - Emitted when the connection is established.
- * @property {[data: string | Buffer, isBinary: boolean]} message - Emitted for each incoming message.
- * @property {[code: number, reason: string]}   close   - Emitted when the connection closes.
- * @property {[error: Error]}                   error   - Emitted on connection or protocol errors.
- * @property {[data: Buffer]}                   ping    - Emitted when a PING frame is received.
- * @property {[data: Buffer]}                   pong    - Emitted when a PONG frame is received.
- */
+/** Event map for {@link WebSocketClient} emitter. */
 export interface WebSocketEvents {
+    /** Fired when the connection has been established. */
     open: [];
+    /** Fired when a text or binary message is received. */
     message: [data: string | Buffer, isBinary: boolean];
+    /** Fired when the connection has been cleanly closed. */
     close: [code: number, reason: string];
+    /** Fired on transport or protocol errors. */
     error: [error: Error];
+    /** Fired when a ping frame is received. */
     ping: [data: Buffer];
+    /** Fired when a pong frame is received. */
     pong: [data: Buffer];
 }
 /**
- * WebSocket client with optional browser fingerprint impersonation. Emits
- * typed lifecycle events (`open`, `message`, `close`, `error`, `ping`, `pong`).
- * The connection is initiated asynchronously in the constructor; listen for
- * the `'open'` event before sending frames.
- *
- * @example
- * const ws = new WebSocketClient('wss://echo.example.com', { impersonate: 'chrome136' });
- * ws.on('open', () => ws.sendText('hello'));
- * ws.on('message', (data) => console.log(data));
+ * RFC 6455 WebSocket client with optional TLS fingerprinting
+ * and per-message deflate compression.
  */
 export declare class WebSocketClient extends EventEmitter {
+    /** Current connection lifecycle state. */
     state: WebSocketState;
+    /** Negotiated subprotocol, or empty string if none. */
     protocol: string;
+    /** Original WebSocket URL. */
     readonly url: string;
     private socket;
     private parser;
     private fragments;
     private fragmentOpcode;
+    private fragmentSize;
+    private static readonly MAX_FRAGMENT_SIZE;
     private deflate;
     /**
-     * Creates a new WebSocketClient and begins connecting to `url`.
+     * Create a new WebSocket connection.
      *
-     * @param {string}           url       - WebSocket URL (`ws:` or `wss:`).
-     * @param {WebSocketOptions} [options={}] - Connection and impersonation options.
+     * @param {string} url - `ws://` or `wss://` URL to connect to.
+     * @param {WebSocketOptions} [options] - Connection and TLS options.
      */
     constructor(url: string, options?: WebSocketOptions);
     /**
-     * Sends a UTF-8 text message.
+     * Send a UTF-8 text message.
      *
-     * @param {string} data - Text to send.
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {string} data - Text payload to send.
      */
     sendText(data: string): void;
     /**
-     * Sends a binary message.
+     * Send a binary message.
      *
-     * @param {Buffer} data - Binary data to send.
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {Buffer} data - Binary payload to send.
      */
     sendBinary(data: Buffer): void;
     /**
-     * Sends a PING control frame.
+     * Send a WebSocket ping frame.
      *
-     * @param {Buffer} [data=Buffer.alloc(0)] - Optional ping payload (up to 125 bytes).
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {Buffer} [data] - Optional payload (up to 125 bytes).
      */
     ping(data?: Buffer): void;
     /**
-     * Initiates a graceful close handshake by sending a CLOSE frame with the
-     * given status code and reason. Does nothing if the connection is not open.
+     * Initiate a graceful close handshake.
      *
-     * @param {number} [code=1000]  - WebSocket close status code.
-     * @param {string} [reason=''] - Human-readable close reason (UTF-8, max 123 bytes).
+     * @param {number} [code] - Close status code (default `1000`).
+     * @param {string} [reason] - Human-readable close reason.
      */
     close(code?: number, reason?: string): void;
     private assertOpen;

package/dist/ws/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ws/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY3C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,EAAE,CAAC;IACT,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IACxC,KAAK,EAAE,cAAc,CAAgB;IACrC,QAAQ,SAAM;IACrB,SAAgB,GAAG,EAAE,MAAM,CAAC;IAE5B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,OAAO,CAAkC;IAEjD;;;;;OAKG;gBACS,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAWvD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAe5B;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAc9B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,GAAE,MAAwB,GAAG,IAAI;IAK1C;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAK,GAAG,IAAI;IAarC,OAAO,CAAC,UAAU;YAMJ,OAAO;IA4DrB,OAAO,CAAC,cAAc;IAiHtB,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,WAAW;CA6EpB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ws/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY3C,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE1E,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,IAAI,EAAE,EAAE,CAAC;IACT,uDAAuD;IACvD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpD,yDAAyD;IACzD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,6CAA6C;IAC7C,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtB,2CAA2C;IAC3C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrB,2CAA2C;IAC3C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;CACtB;AAiBD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,0CAA0C;IACnC,KAAK,EAAE,cAAc,CAAgB;IAC5C,uDAAuD;IAChD,QAAQ,SAAM;IACrB,8BAA8B;IAC9B,SAAgB,GAAG,EAAE,MAAM,CAAC;IAE5B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;IAC7D,OAAO,CAAC,OAAO,CAAkC;IAEjD;;;;;OAKG;gBACS,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAWvD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAe5B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAc9B;;;;OAIG;IACH,IAAI,CAAC,IAAI,GAAE,MAAwB,GAAG,IAAI;IAK1C;;;;;OAKG;IACH,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAK,GAAG,IAAI;IAarC,OAAO,CAAC,UAAU;YAMJ,OAAO;IAgErB,OAAO,CAAC,cAAc;IAoHtB,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,WAAW;CAoHpB"}

package/dist/ws/client.js

@@ -6,31 +6,43 @@ import { NLcURLError, ConnectionError } from "../core/errors.js";
 import { validateWebSocketUrl } from "../core/validation.js";
 import { encodeFrame, FrameParser, Opcode, generateWebSocketKey, computeAcceptKey } from "./frame.js";
 import { buildDeflateOffer, parseDeflateResponse, PerMessageDeflate } from "./permessage-deflate.js";
+/** Strict UTF-8 text decoder that throws on invalid sequences (RFC 6455 §8.1). */
+const strictUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
 /**
- * WebSocket client with optional browser fingerprint impersonation. Emits
- * typed lifecycle events (`open`, `message`, `close`, `error`, `ping`, `pong`).
- * The connection is initiated asynchronously in the constructor; listen for
- * the `'open'` event before sending frames.
- *
- * @example
- * const ws = new WebSocketClient('wss://echo.example.com', { impersonate: 'chrome136' });
- * ws.on('open', () => ws.sendText('hello'));
- * ws.on('message', (data) => console.log(data));
+ * Validate and decode a buffer as UTF-8 text.
+ * Returns the decoded string, or null if the buffer contains invalid UTF-8.
+ */
+function decodeUtf8Strict(buf) {
+    try {
+        return strictUtf8Decoder.decode(buf);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * RFC 6455 WebSocket client with optional TLS fingerprinting
+ * and per-message deflate compression.
  */
 export class WebSocketClient extends EventEmitter {
+    /** Current connection lifecycle state. */
     state = "connecting";
+    /** Negotiated subprotocol, or empty string if none. */
     protocol = "";
+    /** Original WebSocket URL. */
     url;
     socket = null;
     parser = new FrameParser();
     fragments = [];
     fragmentOpcode = Opcode.TEXT;
+    fragmentSize = 0;
+    static MAX_FRAGMENT_SIZE = 64 * 1024 * 1024;
     deflate = null;
     /**
-     * Creates a new WebSocketClient and begins connecting to `url`.
+     * Create a new WebSocket connection.
      *
-     * @param {string}           url       - WebSocket URL (`ws:` or `wss:`).
-     * @param {WebSocketOptions} [options={}] - Connection and impersonation options.
+     * @param {string} url - `ws://` or `wss://` URL to connect to.
+     * @param {WebSocketOptions} [options] - Connection and TLS options.
      */
     constructor(url, options = {}) {
         super();
@@ -42,10 +54,9 @@ export class WebSocketClient extends EventEmitter {
         });
     }
     /**
-     * Sends a UTF-8 text message.
+     * Send a UTF-8 text message.
      *
-     * @param {string} data - Text to send.
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {string} data - Text payload to send.
      */
     sendText(data) {
         this.assertOpen();
@@ -63,10 +74,9 @@ export class WebSocketClient extends EventEmitter {
         }
     }
     /**
-     * Sends a binary message.
+     * Send a binary message.
      *
-     * @param {Buffer} data - Binary data to send.
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {Buffer} data - Binary payload to send.
      */
     sendBinary(data) {
         this.assertOpen();
@@ -83,21 +93,19 @@ export class WebSocketClient extends EventEmitter {
         }
     }
     /**
-     * Sends a PING control frame.
+     * Send a WebSocket ping frame.
      *
-     * @param {Buffer} [data=Buffer.alloc(0)] - Optional ping payload (up to 125 bytes).
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {Buffer} [data] - Optional payload (up to 125 bytes).
      */
     ping(data = Buffer.alloc(0)) {
         this.assertOpen();
         this.socket.write(encodeFrame(Opcode.PING, data));
     }
     /**
-     * Initiates a graceful close handshake by sending a CLOSE frame with the
-     * given status code and reason. Does nothing if the connection is not open.
+     * Initiate a graceful close handshake.
      *
-     * @param {number} [code=1000]  - WebSocket close status code.
-     * @param {string} [reason=''] - Human-readable close reason (UTF-8, max 123 bytes).
+     * @param {number} [code] - Close status code (default `1000`).
+     * @param {string} [reason] - Human-readable close reason.
      */
     close(code = 1000, reason = "") {
         if (this.state !== "open")
@@ -138,7 +146,9 @@ export class WebSocketClient extends EventEmitter {
         else {
             const net = await import("node:net");
             transport = await new Promise((resolve, reject) => {
-                const sock = net.createConnection({ host, port }, () => resolve(sock));
+                const sock = net.createConnection({ host, port }, () => {
+                    resolve(sock);
+                });
                 sock.once("error", reject);
                 if (options.timeout) {
                     sock.setTimeout(options.timeout, () => {
@@ -152,7 +162,9 @@ export class WebSocketClient extends EventEmitter {
         await this.performUpgrade(transport, parsed, options);
         this.state = "open";
         this.emit("open");
-        transport.on("data", (chunk) => this.onData(chunk));
+        transport.on("data", (chunk) => {
+            this.onData(chunk);
+        });
         transport.on("error", (err) => {
             this.state = "closed";
             this.emit("error", err);
@@ -212,11 +224,13 @@ export class WebSocketClient extends EventEmitter {
                 const headerStr = text.substring(0, headerEnd);
                 const [statusLine, ...headerLines] = headerStr.split("\r\n");
                 if (!statusLine) {
-                    return reject(new NLcURLError("Empty upgrade response", "ERR_WS_UPGRADE"));
+                    reject(new NLcURLError("Empty upgrade response", "ERR_WS_UPGRADE"));
+                    return;
                 }
                 const statusMatch = statusLine.match(/^HTTP\/\d\.\d (\d{3})/);
                 if (!statusMatch || statusMatch[1] !== "101") {
-                    return reject(new NLcURLError(`WebSocket upgrade failed: ${statusLine}`, "ERR_WS_UPGRADE"));
+                    reject(new NLcURLError(`WebSocket upgrade failed: ${statusLine}`, "ERR_WS_UPGRADE"));
+                    return;
                 }
                 const headers = new Map();
                 for (const line of headerLines) {
@@ -227,7 +241,8 @@ export class WebSocketClient extends EventEmitter {
                 }
                 const accept = headers.get("sec-websocket-accept");
                 if (accept !== expectedAccept) {
-                    return reject(new NLcURLError("Invalid Sec-WebSocket-Accept header", "ERR_WS_UPGRADE"));
+                    reject(new NLcURLError("Invalid Sec-WebSocket-Accept header", "ERR_WS_UPGRADE"));
+                    return;
                 }
                 this.protocol = headers.get("sec-websocket-protocol") ?? "";
                 const extHeader = headers.get("sec-websocket-extensions");
@@ -277,39 +292,82 @@ export class WebSocketClient extends EventEmitter {
                         this.deflate
                             .decompress(frame.payload)
                             .then((decompressed) => {
-                            const data = isBinary ? decompressed : decompressed.toString("utf8");
-                            this.emit("message", data, isBinary);
+                            if (isBinary) {
+                                this.emit("message", decompressed, true);
+                            }
+                            else {
+                                const text = decodeUtf8Strict(decompressed);
+                                if (text === null) {
+                                    this.close(1007, "Invalid UTF-8");
+                                    return;
+                                }
+                                this.emit("message", text, false);
+                            }
                         })
                             .catch((err) => this.emit("error", err));
                     }
                     else {
-                        const data = isBinary ? frame.payload : frame.payload.toString("utf8");
-                        this.emit("message", data, isBinary);
+                        if (isBinary) {
+                            this.emit("message", frame.payload, true);
+                        }
+                        else {
+                            const text = decodeUtf8Strict(frame.payload);
+                            if (text === null) {
+                                this.close(1007, "Invalid UTF-8");
+                                return;
+                            }
+                            this.emit("message", text, false);
+                        }
                     }
                 }
                 else {
                     this.fragmentOpcode = frame.opcode;
                     this.fragments = [frame.payload];
+                    this.fragmentSize = frame.payload.length;
                 }
                 break;
             case Opcode.CONTINUATION:
+                this.fragmentSize += frame.payload.length;
+                if (this.fragmentSize > WebSocketClient.MAX_FRAGMENT_SIZE) {
+                    this.close(1009, "Message too big");
+                    return;
+                }
                 this.fragments.push(frame.payload);
                 if (frame.fin) {
                     const assembled = Buffer.concat(this.fragments);
                     this.fragments = [];
+                    this.fragmentSize = 0;
                     const isBinary = this.fragmentOpcode === Opcode.BINARY;
                     if (this.deflate) {
                         this.deflate
                             .decompress(assembled)
                             .then((decompressed) => {
-                            const data = isBinary ? decompressed : decompressed.toString("utf8");
-                            this.emit("message", data, isBinary);
+                            if (isBinary) {
+                                this.emit("message", decompressed, true);
+                            }
+                            else {
+                                const text = decodeUtf8Strict(decompressed);
+                                if (text === null) {
+                                    this.close(1007, "Invalid UTF-8");
+                                    return;
+                                }
+                                this.emit("message", text, false);
+                            }
                         })
                             .catch((err) => this.emit("error", err));
                     }
                     else {
-                        const data = isBinary ? assembled : assembled.toString("utf8");
-                        this.emit("message", data, isBinary);
+                        if (isBinary) {
+                            this.emit("message", assembled, true);
+                        }
+                        else {
+                            const text = decodeUtf8Strict(assembled);
+                            if (text === null) {
+                                this.close(1007, "Invalid UTF-8");
+                                return;
+                            }
+                            this.emit("message", text, false);
+                        }
                     }
                 }
                 break;