specters 2.2.0 → 3.0.0

package/README.md

@@ -1,161 +1,95 @@
 # Specter Node.js Bindings
 
-Node.js bindings for Specter, a high-performance HTTP client with full TLS, HTTP/2, and HTTP/3 fingerprint control.
+Node.js bindings for Specter, a high-performance async HTTP client with TLS, HTTP/2, HTTP/3, RFC 6455 WebSocket, and RFC 8441 Extended CONNECT support.
 
 ## Features
 
-- **Native async/await**: Promise-based API with native performance
-- **Browser fingerprinting**: Impersonate Chrome, Firefox, or use custom TLS/HTTP2 settings
-- **HTTP/3 support**: Automatic upgrade via Alt-Svc headers
-- **Connection pooling**: HTTP/2 multiplexing and HTTP/1.1 keep-alive
-- **Timeout control**: Granular timeouts for connect, TTFB, read/write idle, and total request time
-- **Automatic decompression**: gzip, deflate, brotli, zstd
+- Promise-based HTTP, RFC 6455 WebSocket, and RFC 8441 raw tunnel APIs
+- Browser fingerprinting for Chrome, Firefox, or default TLS settings
+- HTTP/2, HTTP/3, connection pooling, and automatic decompression
+- Cookie store and shared cookie jar support across HTTP and WebSocket handshakes
+- Granular connect, TTFB, read/write idle, total, pool, and WebSocket handshake timeouts
 
 ## Installation
 
 ```bash
-npm install @specter/client
+npm install specters
 ```
 
-## Quick Start
+## HTTP
 
 ```javascript
-const { Client } = require('@specter/client');
-
-async function main() {
-  // Create a client with default settings
-  const client = Client.builder().build();
-  
-  // Make a GET request
-  const response = await client.get('https://httpbin.org/get').send();
-  console.log(`Status: ${response.status}`);
-  console.log(await response.text());
-}
-
-main();
-```
-
-## Browser Impersonation
-
-```javascript
-const { Client, FingerprintProfile } = require('@specter/client');
+const { clientBuilder, FingerprintProfile } = require('specters');
 
-// Impersonate Chrome 146 (current stable)
-const client = Client.builder()
-  .fingerprint(FingerprintProfile.Chrome146)
-  .build();
-
-// Or pick a specific version (142, 143, 144, 145, 146)
-const client = Client.builder()
+const client = clientBuilder()
   .fingerprint(FingerprintProfile.Chrome142)
+  .cookieStore(true)
   .build();
 
-// Or Firefox 133
-const client = Client.builder()
-  .fingerprint(FingerprintProfile.Firefox133)
-  .build();
-```
-
-## Timeout Configuration
-
-```javascript
-const { Client, timeoutsApiDefaults, timeoutsStreamingDefaults } = require('@specter/client');
-
-// Use preset timeout configurations
-const client1 = Client.builder().apiTimeouts().build();
-const client2 = Client.builder().streamingTimeouts().build();
-
-// Or configure manually
-const timeouts = {
-  connect: 10.0,      // TCP + TLS handshake
-  ttfb: 30.0,         // Time to first byte
-  readIdle: 60.0,     // Max time between chunks
-  total: 120.0        // Total request deadline
-};
+const response = await client
+  .post('https://example.com/items')
+  .header('Authorization', 'Bearer token')
+  .json(JSON.stringify({ name: 'example' }))
+  .send();
 
-const client = Client.builder().timeouts(timeouts).build();
+console.log(response.status);
+console.log(response.text());
 ```
 
-## HTTP Methods
+## RFC 6455 WebSockets
 
 ```javascript
-const { Client } = require('@specter/client');
-
-const client = Client.builder().build();
-
-// GET
-const response = await client.get('https://api.example.com/items').send();
+const { CLOSE_NORMAL, clientBuilder } = require('specters');
 
-// POST
-const response = await client.post('https://api.example.com/items').send();
-
-// PUT
-const response = await client.put('https://api.example.com/items/1').send();
-
-// DELETE
-const response = await client.delete('https://api.example.com/items/1').send();
+const client = clientBuilder()
+  .cookieStore(true)
+  .http2PriorKnowledge(false)
+  .build();
 
-// PATCH
-const response = await client.patch('https://api.example.com/items/1').send();
+const ws = await client.websocket('wss://example.com/socket')
+  .header('Origin', 'https://example.com')
+  .subprotocol('chat.v1')
+  .maxMessageSize(1 << 20)
+  .handshakeTimeout(10)
+  .connect();
 
-// HEAD
-const response = await client.head('https://api.example.com/items/1').send();
+await ws.sendText('hello');
+const message = await ws.next();
 
-// OPTIONS
-const response = await client.options('https://api.example.com/items').send();
+if (message.type === 'text') {
+  console.log(message.text);
+}
 
-// Arbitrary method
-const response = await client.request('PURGE', 'https://api.example.com/cache').send();
+await ws.close({ code: CLOSE_NORMAL, reason: 'done' });
 ```
 
-## Response Handling
-
-```javascript
-const response = await client.get('https://api.example.com/data').send();
-
-// Status code
-console.log(response.status);
-
-// Headers
-console.log(response.headers);  // Record<string, string>
-console.log(response.getHeader('content-type'));
-
-// Body
-console.log(response.text());      // Decompressed text
-console.log(response.json());      // JSON string (use JSON.parse)
-const data = response.bytes();     // Buffer
-
-// Response metadata
-console.log(response.httpVersion); // "HTTP/2", "HTTP/1.1", etc.
-console.log(response.isSuccess);   // true for 2xx status
+RFC 6455 sockets are framed message connections. `send*`, `next`, and `close` operations are serialized per socket to preserve Rust's mutable socket contract; avoid running multiple receive loops on the same socket.
 
-## Request Builder
+## RFC 8441 HTTP/2 Tunnels
 
 ```javascript
-const { Client } = require('@specter/client');
+const { clientBuilder } = require('specters');
 
-const client = Client.builder().build();
+const client = clientBuilder()
+  .http2PriorKnowledge(true)
+  .build();
 
-const response = await client
-  .post('https://api.example.com/items')
-  .header('Authorization', 'Bearer token')
-  .json(JSON.stringify({ name: 'example' }))
-  .send();
+const tunnel = await client.websocketH2('https://example.com/h2-tunnel')
+  .header('Origin', 'https://example.com')
+  .open();
 
-console.log(response.status);
-```
+await tunnel.sendBytes(Buffer.from('raw bytes'), false);
+const data = await tunnel.recvBytes();
+await tunnel.closeSend();
 ```
 
+RFC 8441 exposes a raw byte tunnel over HTTP/2 Extended CONNECT. It is intentionally separate from the RFC 6455 framed `WebSocket` API.
+
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Build the native module
 npm run build
-
-# Run tests
 npm test
 ```
 

package/index.d.ts

@@ -1,164 +1,196 @@
-/**
- * Specter - Node.js bindings for the Specter HTTP client.
- *
- * A high-performance async HTTP client with full TLS, HTTP/2, and HTTP/3
- * fingerprint control for browser impersonation.
- */
-
-/** Browser fingerprint profiles for impersonation. */
 export enum FingerprintProfile {
-  /** Chrome 142 on macOS */
-  Chrome142 = 0,
-  /** Firefox 133 on macOS */
-  Firefox133 = 1,
-  /** No fingerprinting - use default TLS settings */
-  None = 2,
+  Chrome142,
+  Chrome143,
+  Chrome144,
+  Chrome145,
+  Chrome146,
+  Firefox133,
+  None,
 }
 
-/** HTTP version preference. */
 export enum HttpVersion {
-  /** Force HTTP/1.1 */
-  Http1_1 = 0,
-  /** Attempt HTTP/2, fallback to HTTP/1.1 */
-  Http2 = 1,
-  /** Attempt HTTP/3, fallback to HTTP/2, fallback to HTTP/1.1 */
-  Http3 = 2,
-  /** HTTP/3 only, no fallback */
-  Http3Only = 3,
-  /** Let the client decide based on server support */
-  Auto = 4,
-}
-
-/** Timeout configuration for HTTP requests. */
+  Http1_1,
+  Http2,
+  Http3,
+  Http3Only,
+  Auto,
+}
+
 export interface Timeouts {
-  /** TCP + TLS/QUIC handshake timeout in seconds */
   connect?: number;
-  /** Time-to-first-byte timeout in seconds */
   ttfb?: number;
-  /** Maximum time between received bytes in seconds (resets on each chunk) */
   readIdle?: number;
-  /** Maximum time between sent bytes in seconds */
   writeIdle?: number;
-  /** Absolute deadline for entire request in seconds */
   total?: number;
-  /** Time to wait for a pooled connection in seconds */
   poolAcquire?: number;
 }
 
-/** HTTP request builder for setting headers and body. */
+export interface WebSocketMessage {
+  type: 'text' | 'binary' | 'ping' | 'pong' | 'close';
+  text?: string;
+  data?: Buffer;
+  code?: number;
+  reason?: string;
+}
+
+export interface WebSocketCloseFrame {
+  code?: number;
+  reason?: string;
+}
+
+export interface H2TunnelEvent {
+  type: 'data' | 'endStream' | 'reset' | 'goAway';
+  data?: Buffer;
+  reason?: string;
+  lastStreamId?: number;
+}
+
+export interface H3TunnelEvent {
+  type: 'data' | 'endStream' | 'reset' | 'goAway';
+  data?: Buffer;
+  reason?: string;
+  lastStreamId?: bigint;
+}
+
 export class RequestBuilder {
-  /** Add a header to the request. Returns this for chaining. */
   header(key: string, value: string): this;
-  /** Set all headers (replaces existing headers). Returns this for chaining. */
   headers(headers: string[][]): this;
-  /** Set the request body as bytes. Returns this for chaining. */
   body(body: Buffer): this;
-  /** Set the request body as JSON string and add Content-Type header. Returns this for chaining. */
   json(jsonStr: string): this;
-  /** Set the request body as form data and add Content-Type header. Returns this for chaining. */
   form(formStr: string): this;
-  /** Send the request and return the response. */
   send(): Promise<Response>;
 }
 
-/** HTTP response with decompression support. */
 export class Response {
-  /** HTTP status code */
   get status(): number;
-  /** Response headers as an object */
   get headers(): Record<string, string>;
-  /** Get all headers as an array of [key, value] pairs */
   headersList(): string[][];
-  /** Get a specific header value by name */
   getHeader(name: string): string | null;
-  /** Get the response body as text (with decompression if needed) */
   text(): string;
-  /** Get the response body as a Buffer */
   bytes(): Buffer;
-  /** Parse the response body as JSON and return as string. Use JSON.parse to convert to an object. */
   json(): string;
-  /** HTTP version string */
   get httpVersion(): string;
-  /** Effective URL (after redirects) */
   get effectiveUrl(): string | null;
-  /** Check if the response status is successful (2xx) */
   get isSuccess(): boolean;
-  /** Check if the response is a redirect (3xx) */
   get isRedirect(): boolean;
-  /** Get the redirect URL from Location header if present */
   get redirectUrl(): string | null;
-  /** Get the Content-Type header value */
   get contentType(): string | null;
 }
 
-/** Builder for creating HTTP clients. */
 export class ClientBuilder {
-  /** Set the fingerprint profile */
   fingerprint(profile: FingerprintProfile): this;
-  /** Set HTTP/2 preference */
   preferHttp2(prefer: boolean): this;
-  /** Enable or disable automatic HTTP/3 upgrade via Alt-Svc headers */
+  http2PriorKnowledge(enabled: boolean): this;
   h3Upgrade(enabled: boolean): this;
-  /** Set timeout configuration */
+  cookieStore(enabled: boolean): this;
+  cookieJar(jar: CookieJar): this;
   timeouts(timeouts: Timeouts): this;
-  /** Use API-optimized timeout defaults */
   apiTimeouts(): this;
-  /** Use streaming-optimized timeout defaults */
   streamingTimeouts(): this;
-  /** Set total request timeout in seconds */
   totalTimeout(timeoutSecs: number): this;
-  /** Set connect timeout in seconds */
   connectTimeout(timeoutSecs: number): this;
-  /** Set TTFB (time-to-first-byte) timeout in seconds */
   ttfbTimeout(timeoutSecs: number): this;
-  /** Set read idle timeout in seconds */
   readTimeout(timeoutSecs: number): this;
-  /** Skip TLS certificate verification for all connections (DANGEROUS - for testing only) */
   dangerAcceptInvalidCerts(accept: boolean): this;
-  /** Automatically skip TLS certificate verification for localhost connections */
   localhostAllowsInvalidCerts(allow: boolean): this;
-  /** Load root certificates from the operating system's certificate store */
   withPlatformRoots(enabled: boolean): this;
-  /** Build the client */
   build(): Client;
 }
 
-/** HTTP client with TLS/HTTP2/HTTP3 fingerprint control. */
 export class Client {
-  /** Create a GET request builder */
+  websocket(url: string): WebSocketBuilder;
+  websocketH2(url: string): WebSocketH2Builder;
+  websocketH3(url: string): WebSocketH3Builder;
   get(url: string): RequestBuilder;
-  /** Create a POST request builder */
   post(url: string): RequestBuilder;
-  /** Create a PUT request builder */
   put(url: string): RequestBuilder;
-  /** Create a DELETE request builder */
   delete(url: string): RequestBuilder;
-  /** Create a PATCH request builder */
   patch(url: string): RequestBuilder;
-  /** Create a HEAD request builder */
   head(url: string): RequestBuilder;
-  /** Create an OPTIONS request builder */
   options(url: string): RequestBuilder;
-  /** Create a request builder for an arbitrary HTTP method */
   request(method: string, url: string): RequestBuilder;
 }
 
-/** Cookie jar for manual cookie management. */
 export class CookieJar {
   constructor();
-  /** Get the number of cookies in the jar */
   get length(): number;
-  /** Check if the cookie jar is empty */
   get isEmpty(): boolean;
 }
 
-/** Create a new client builder */
-export function clientBuilder(): ClientBuilder;
+export class WebSocketBuilder {
+  header(key: string, value: string): this;
+  headers(headers: Record<string, string>): this;
+  subprotocol(value: string): this;
+  subprotocols(values: string[]): this;
+  maxMessageSize(bytes: number): this;
+  maxFrameSize(bytes: number): this;
+  connectTimeout(timeoutSecs: number): this;
+  handshakeTimeout(timeoutSecs: number): this;
+  readTimeout(timeoutSecs: number): this;
+  writeTimeout(timeoutSecs: number): this;
+  connect(): Promise<WebSocket>;
+}
 
-/** Sensible defaults for normal API calls. */
-export function timeoutsApiDefaults(): Timeouts;
+export class WebSocket {
+  get url(): string;
+  get protocol(): string | null;
+  send(message: WebSocketMessage): Promise<void>;
+  sendText(text: string): Promise<void>;
+  sendBinary(data: Buffer): Promise<void>;
+  sendPing(data?: Buffer): Promise<void>;
+  sendPong(data?: Buffer): Promise<void>;
+  next(): Promise<WebSocketMessage>;
+  close(frame?: WebSocketCloseFrame): Promise<void>;
+}
 
-/** Sensible defaults for streaming responses. */
-export function timeoutsStreamingDefaults(): Timeouts;
+export class WebSocketH2Builder {
+  header(key: string, value: string): this;
+  headers(headers: string[][]): this;
+  subprotocol(value: string): this;
+  connectTimeout(timeoutSecs: number): this;
+  readTimeout(timeoutSecs: number): this;
+  writeTimeout(timeoutSecs: number): this;
+  connect(): Promise<WebSocketH2Tunnel>;
+}
+
+export class WebSocketH2Tunnel {
+  sendBytes(data: Buffer, endStream?: boolean): Promise<void>;
+  recvBytes(): Promise<Buffer | null>;
+  recvEvent(): Promise<H2TunnelEvent | null>;
+  closeSend(): Promise<void>;
+}
+
+export class WebSocketH3Builder {
+  header(key: string, value: string): this;
+  headers(headers: string[][]): this;
+  subprotocol(value: string): this;
+  connectTimeout(timeoutSecs: number): this;
+  readTimeout(timeoutSecs: number): this;
+  writeTimeout(timeoutSecs: number): this;
+  connect(): Promise<WebSocketH3Tunnel>;
+}
+
+export class WebSocketH3Tunnel {
+  sendBytes(data: Buffer, fin?: boolean): Promise<void>;
+  recvBytes(): Promise<Buffer | null>;
+  recvEvent(): Promise<H3TunnelEvent | null>;
+  closeSend(): Promise<void>;
+}
 
-export {};
+export const CLOSE_NORMAL: number;
+export const CLOSE_GOING_AWAY: number;
+export const CLOSE_PROTOCOL_ERROR: number;
+export const CLOSE_UNSUPPORTED: number;
+export const CLOSE_NO_STATUS: number;
+export const CLOSE_ABNORMAL: number;
+export const CLOSE_INVALID_PAYLOAD: number;
+export const CLOSE_POLICY_VIOLATION: number;
+export const CLOSE_MESSAGE_TOO_BIG: number;
+export const CLOSE_MANDATORY_EXTENSION: number;
+export const CLOSE_INTERNAL_ERROR: number;
+export const CLOSE_TLS_ERROR: number;
+
+export function isValidCloseCode(code: number): boolean;
+export function clientBuilder(): ClientBuilder;
+export function timeoutsApiDefaults(): Timeouts;
+export function timeoutsStreamingDefaults(): Timeouts;

package/index.js

@@ -8,7 +8,7 @@
 const { execSync } = require('node:child_process');
 const { readFileSync } = require('node:fs');
 
-const PACKAGE_VERSION = '2.2.0';
+const PACKAGE_VERSION = '3.0.0';
 
 const targets = {
   'darwin-x64': {
@@ -131,9 +131,29 @@ module.exports.ClientBuilder = binding.ClientBuilder;
 module.exports.RequestBuilder = binding.RequestBuilder;
 module.exports.Response = binding.Response;
 module.exports.CookieJar = binding.CookieJar;
+module.exports.WebSocketBuilder = binding.WebSocketBuilder;
+module.exports.WebSocket = binding.WebSocket;
+module.exports.WebSocketH2Builder = binding.WebSocketH2Builder;
+module.exports.WebSocketH2Tunnel = binding.WebSocketH2Tunnel;
+module.exports.WebSocketH3Builder = binding.WebSocketH3Builder;
+module.exports.WebSocketH3Tunnel = binding.WebSocketH3Tunnel;
+module.exports.WebSocketCloseFrame = binding.WebSocketCloseFrame;
 module.exports.FingerprintProfile = binding.FingerprintProfile;
 module.exports.HttpVersion = binding.HttpVersion;
 module.exports.Timeouts = binding.Timeouts;
+module.exports.CLOSE_NORMAL = binding.CLOSE_NORMAL;
+module.exports.CLOSE_GOING_AWAY = binding.CLOSE_GOING_AWAY;
+module.exports.CLOSE_PROTOCOL_ERROR = binding.CLOSE_PROTOCOL_ERROR;
+module.exports.CLOSE_UNSUPPORTED = binding.CLOSE_UNSUPPORTED;
+module.exports.CLOSE_NO_STATUS = binding.CLOSE_NO_STATUS;
+module.exports.CLOSE_ABNORMAL = binding.CLOSE_ABNORMAL;
+module.exports.CLOSE_INVALID_PAYLOAD = binding.CLOSE_INVALID_PAYLOAD;
+module.exports.CLOSE_POLICY_VIOLATION = binding.CLOSE_POLICY_VIOLATION;
+module.exports.CLOSE_MESSAGE_TOO_BIG = binding.CLOSE_MESSAGE_TOO_BIG;
+module.exports.CLOSE_MANDATORY_EXTENSION = binding.CLOSE_MANDATORY_EXTENSION;
+module.exports.CLOSE_INTERNAL_ERROR = binding.CLOSE_INTERNAL_ERROR;
+module.exports.CLOSE_TLS_ERROR = binding.CLOSE_TLS_ERROR;
+module.exports.isValidCloseCode = binding.isValidCloseCode;
 module.exports.clientBuilder = binding.clientBuilder;
 module.exports.timeoutsApiDefaults = binding.timeoutsApiDefaults;
 module.exports.timeoutsStreamingDefaults = binding.timeoutsStreamingDefaults;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specters",
-  "version": "2.2.0",
-  "description": "Node.js bindings for Specter HTTP client with TLS/HTTP2/HTTP3 fingerprint control",
+  "version": "3.0.0",
+  "description": "Node.js bindings for Specter HTTP, WebSocket, HTTP/2, and HTTP/3 tunnel client",
   "main": "index.js",
   "types": "index.d.ts",
   "napi": {
@@ -29,11 +29,16 @@
     "artifacts": "napi artifacts --output-dir ./artifacts",
     "test": "jest"
   },
+  "jest": {
+    "testMatch": [
+      "**/__tests__/*.test.js"
+    ]
+  },
   "optionalDependencies": {
-    "specters-darwin-x64": "2.2.0",
-    "specters-darwin-arm64": "2.2.0",
-    "specters-linux-x64-gnu": "2.2.0",
-    "specters-linux-arm64-gnu": "2.2.0"
+    "specters-darwin-x64": "3.0.0",
+    "specters-darwin-arm64": "3.0.0",
+    "specters-linux-x64-gnu": "3.0.0",
+    "specters-linux-arm64-gnu": "3.0.0"
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.6.2",
@@ -55,4 +60,4 @@
     "url": "https://github.com/jaredboynton/specter.git",
     "directory": "bindings/node"
   }
-}
+}