specters 2.0.0

package/README.md

@@ -0,0 +1,159 @@
+# Specter Node.js Bindings
+
+Node.js bindings for Specter, a high-performance HTTP client with full TLS, HTTP/2, and HTTP/3 fingerprint control.
+
+## 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
+
+## Installation
+
+```bash
+npm install @specter/client
+```
+
+## Quick Start
+
+```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');
+
+// Impersonate Chrome 142
+const client = Client.builder()
+  .fingerprint(FingerprintProfile.Chrome142)
+  .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 client = Client.builder().timeouts(timeouts).build();
+```
+
+## HTTP Methods
+
+```javascript
+const { Client } = require('@specter/client');
+
+const client = Client.builder().build();
+
+// GET
+const response = await client.get('https://api.example.com/items').send();
+
+// 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();
+
+// PATCH
+const response = await client.patch('https://api.example.com/items/1').send();
+
+// HEAD
+const response = await client.head('https://api.example.com/items/1').send();
+
+// OPTIONS
+const response = await client.options('https://api.example.com/items').send();
+
+// Arbitrary method
+const response = await client.request('PURGE', 'https://api.example.com/cache').send();
+```
+
+## 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
+
+## Request Builder
+
+```javascript
+const { Client } = require('@specter/client');
+
+const client = Client.builder().build();
+
+const response = await client
+  .post('https://api.example.com/items')
+  .header('Authorization', 'Bearer token')
+  .json(JSON.stringify({ name: 'example' }))
+  .send();
+
+console.log(response.status);
+```
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the native module
+npm run build
+
+# Run tests
+npm test
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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,
+}
+
+/** 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. */
+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 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 */
+  h3Upgrade(enabled: boolean): this;
+  /** Set timeout configuration */
+  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 */
+  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;
+
+/** Sensible defaults for normal API calls. */
+export function timeoutsApiDefaults(): Timeouts;
+
+/** Sensible defaults for streaming responses. */
+export function timeoutsStreamingDefaults(): Timeouts;
+
+export {};

package/index.js

@@ -0,0 +1,130 @@
+/**
+ * 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.
+ *
+ * @example
+ * const { clientBuilder, FingerprintProfile } = require('@specter/client');
+ *
+ * async function main() {
+ *   // Create a client with default settings
+ *   const client = clientBuilder().build();
+ *
+ *   // Simple GET request
+ *   const response = await client.get('https://httpbin.org/get').send();
+ *   console.log(`Status: ${response.status}`);
+ *   console.log(response.text());
+ *
+ *   // POST with JSON body
+ *   const response2 = await client.post('https://api.example.com/data')
+ *     .header('Authorization', 'Bearer token')
+ *     .json(JSON.stringify({ name: 'test' }))
+ *     .send();
+ *   console.log(JSON.parse(response2.json()));
+ * }
+ *
+ * main();
+ */
+
+const { loadBinding } = require('@napi-rs/wasm-runtime');
+const path = require('path');
+
+// Try to load the native binding
+let nativeBinding;
+
+// Platform to binary name mapping based on napi-rs naming convention
+// Format: specter.{os}-{arch}[-{libc}].node
+const platformBinaries = {
+  'darwin-arm64': 'specter.darwin-arm64.node',
+  'darwin-x64': 'specter.darwin-x64.node',
+  'linux-arm64-gnu': 'specter.linux-arm64-gnu.node',
+  'linux-x64-gnu': 'specter.linux-x64-gnu.node',
+  'linux-x64-musl': 'specter.linux-x64-musl.node',
+  'win32-x64-msvc': 'specter.win32-x64-msvc.node',
+};
+
+function getPlatformKey() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === 'darwin') {
+    return `darwin-${arch}`;
+  }
+  if (platform === 'win32') {
+    return `win32-${arch}-msvc`;
+  }
+  if (platform === 'linux') {
+    // Check if we're on musl by looking at the libc
+    const isMusl = (() => {
+      try {
+        const { execSync } = require('child_process');
+        return execSync('ldd --version 2>&1').toString().includes('musl');
+      } catch {
+        return false;
+      }
+    })();
+    return `linux-${arch}-${isMusl ? 'musl' : 'gnu'}`;
+  }
+  return null;
+}
+
+function loadNativeBinding() {
+  // Try platform-specific binary first
+  const platformKey = getPlatformKey();
+  if (platformKey && platformBinaries[platformKey]) {
+    try {
+      nativeBinding = require(`./${platformBinaries[platformKey]}`);
+      return nativeBinding;
+    } catch (e) {
+      // Continue to fallback
+    }
+  }
+
+  // Try all known binaries
+  for (const binaryName of Object.values(platformBinaries)) {
+    try {
+      nativeBinding = require(`./${binaryName}`);
+      return nativeBinding;
+    } catch (e) {
+      // Continue to next platform
+    }
+  }
+
+  // Try loading from build directory
+  try {
+    nativeBinding = require('./specter.node');
+    return nativeBinding;
+  } catch (e) {
+    // Fall through
+  }
+
+  // Try loading from target
+  try {
+    nativeBinding = require('./build/Release/specter.node');
+    return nativeBinding;
+  } catch (e) {
+    // Fall through
+  }
+
+  throw new Error(
+    `Failed to load native binding for Specter. ` +
+    `Please ensure you've built the native module with "npm run build".`
+  );
+}
+
+// Load the binding
+const binding = loadNativeBinding();
+
+// Export the native types
+module.exports.Client = binding.Client;
+module.exports.ClientBuilder = binding.ClientBuilder;
+module.exports.RequestBuilder = binding.RequestBuilder;
+module.exports.Response = binding.Response;
+module.exports.CookieJar = binding.CookieJar;
+module.exports.FingerprintProfile = binding.FingerprintProfile;
+module.exports.HttpVersion = binding.HttpVersion;
+module.exports.Timeouts = binding.Timeouts;
+module.exports.clientBuilder = binding.clientBuilder;
+module.exports.timeoutsApiDefaults = binding.timeoutsApiDefaults;
+module.exports.timeoutsStreamingDefaults = binding.timeoutsStreamingDefaults;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "specters",
+  "version": "2.0.0",
+  "description": "Node.js bindings for Specter HTTP client with TLS/HTTP2/HTTP3 fingerprint control",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "binaryName": "specter",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "x86_64-unknown-linux-musl",
+      "aarch64-unknown-linux-gnu"
+    ]
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "scripts": {
+    "build": "napi build --platform --release --dts index.gen.d.ts",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm --no-gh-release",
+    "artifacts": "napi artifacts",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0-alpha",
+    "jest": "^29.7.0"
+  },
+  "keywords": [
+    "http",
+    "http3",
+    "fingerprint",
+    "tls",
+    "client",
+    "async",
+    "native"
+  ],
+  "author": "Jared Boynton",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaredboynton/specter.git",
+    "directory": "bindings/node"
+  },
+  "optionalDependencies": {
+    "specters-darwin-x64": "2.0.0",
+    "specters-darwin-arm64": "2.0.0",
+    "specters-linux-x64-gnu": "2.0.0",
+    "specters-linux-x64-musl": "2.0.0",
+    "specters-linux-arm64-gnu": "2.0.0"
+  }
+}