### Install impers via npm

Source: https://lexiforest.github.io/impers/install

Run this command to install the impers package in your project.

```bash
npm install impers
```

--------------------------------

### Perform an HTTP GET request

Source: https://lexiforest.github.io/impers/api/functions/get

Demonstrates how to use the get() function to fetch data from a URL with query parameters and log the JSON response.

```typescript
const response = await get("https://httpbin.org/get", {  

  params: { key: "value" }  

});  

console.log(response.json());  
```

--------------------------------

### Perform an HTTP GET request

Source: https://lexiforest.github.io/impers/api/functions/request

An example of using the request() function to perform a GET request to a URL and logging the JSON response.

```typescript
const response = await request("GET", "https://httpbin.org/get");  

console.log(response.json());
```

--------------------------------

### get(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/get

Performs an HTTP GET request to the specified URL with optional request configurations.

```APIDOC
## get(url, options?)

### Description
Make an HTTP GET request to a specified URL.

### Signature
`get(url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **url** (string) - Required - Request URL
- **options** (RequestOptions) - Optional - Request options

### Returns
- **Promise<Response>** - A promise that resolves to the Response object.

### Example
```javascript
const response = await get("https://httpbin.org/get", {  
  params: { key: "value" }  
});  
console.log(response.json());
```
```

--------------------------------

### Make an HTTP POST request

Source: https://lexiforest.github.io/impers/api/functions/post

Example demonstrating how to use the post() function to send a JSON payload to a URL and log the response.

```typescript
const response = await post("https://httpbin.org/post", {  

  json: { key: "value" }  

});  

console.log(response.json());  
```

--------------------------------

### Managing HTTP Sessions with impers

Source: https://lexiforest.github.io/impers/sessions

Demonstrates initializing a session, performing GET requests to set and retrieve cookies, and closing the session.

```typescript
import { Session } from "impers";  

  

const session = new Session();  

  

// httpbin is an HTTP test website, this endpoint makes the server set cookies  

await session.get("https://httpbin.org/cookies/set/foo/bar");  

console.log(session.cookies);  

// Cookies { foo: 'bar' }  

  

// retrieve cookies again to verify  

const r = await session.get("https://httpbin.org/cookies");  

console.log(r.json());  

// { cookies: { foo: 'bar' } }  

  

// Don't forget to close the session when done  

await session.close();
```

--------------------------------

### Session.get(url, options?)

Source: https://lexiforest.github.io/impers/api/classes/Session

Performs an HTTP GET request.

```APIDOC
## GET [url]

### Description
Performs an HTTP GET request using the session.

### Parameters
- **url** (string) - Required - The target URL.
- **options** (RequestOptions) - Optional - Request configuration.
```

--------------------------------

### impers.get(url, options)

Source: https://lexiforest.github.io/impers/usage

Performs an HTTP GET request with optional browser impersonation, proxy settings, or custom TLS fingerprints.

```APIDOC
## impers.get(url, options)

### Description
Performs an HTTP GET request. Supports browser impersonation (chrome, safari, firefox), custom JA3/Akamai strings, and proxy configuration.

### Parameters
- **url** (string) - Required - The target URL.
- **options** (object) - Optional - Configuration object:
  - **impersonate** (string) - Optional - Browser identifier (e.g., "chrome", "chrome124", "safari", "firefox").
  - **ja3** (string) - Optional - Custom JA3 string.
  - **akamai** (string) - Optional - Custom Akamai string.
  - **proxy** (string) - Optional - Proxy URL (e.g., "http://localhost:3128" or "socks5://localhost:1080").
  - **stream** (boolean) - Optional - Enable streaming mode.
  - **headerCallback** (function) - Optional - Callback for raw response header chunks.
  - **contentCallback** (function) - Optional - Callback for response body chunks.
```

--------------------------------

### Session.get(url)

Source: https://lexiforest.github.io/impers/sessions

Performs an HTTP GET request using the session, which automatically handles and persists cookies.

```APIDOC
## GET session.get(url)

### Description
Performs an HTTP GET request to the specified URL. The session object maintains cookies received from the server across multiple requests.

### Parameters
- **url** (string) - Required - The target URL to fetch.

### Returns
- **Promise** - Resolves with the response object containing the request result.
```

--------------------------------

### Perform Concurrent GET Requests with Session

Source: https://lexiforest.github.io/impers/concurrent-requests

Uses Promise.all to map an array of URLs to session.get calls, ensuring efficient concurrent execution. The session must be closed in a finally block to release resources.

```javascript
import { Session } from "impers";  

  

const urls = [  

  "https://httpbin.org/get",  

  "https://httpbin.org/ip",  

  "https://httpbin.org/user-agent",  

];  

  

const session = new Session({ impersonate: "chrome124" });  

  

try {  

  const results = await Promise.all(  

    urls.map(url => session.get(url))  

  );  

  

  for (const r of results) {  

    console.log(r.status, r.url);  

  }  

} finally {  

  await session.close();  

}  
```

--------------------------------

### Display impers CLI help

Source: https://lexiforest.github.io/impers/impersonation

Run the help command to see available options for the impers CLI tool.

```bash
npx impers --help
```

--------------------------------

### wsConnect(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/wsConnect

Establishes a connection to a WebSocket server.

```APIDOC
## wsConnect(url, options?)

### Description
Connects to a WebSocket server and returns an AsyncWebSocket instance.

### Signature
`wsConnect(url: string, options?: WebSocketOptions): Promise<AsyncWebSocket>`

### Parameters
- **url** (string) - Required - The URL of the WebSocket server to connect to.
- **options** (WebSocketOptions) - Optional - Configuration options for the WebSocket connection.

### Returns
- **Promise<AsyncWebSocket>** - A promise that resolves to an AsyncWebSocket object.
```

--------------------------------

### fetch(input, init?)

Source: https://lexiforest.github.io/impers/api/functions/fetch

Fetches a resource using the impers library, supporting standard Fetch API semantics along with ImpersRequestInit extensions.

```APIDOC
## fetch(input, init?)

### Description
Fetch a resource, returning a standard global Response. This mirrors the global Fetch API while exposing impers' impersonation and transport options via ImpersRequestInit.

### Signature
`fetch(input: string | URL | Request, init?: ImpersRequestInit): Promise<Response>`

### Parameters
- **input** (string | URL | Request) - Required - A URL string, URL, or global Request.
- **init** (ImpersRequestInit) - Optional - Standard RequestInit plus impers extensions.

### Returns
- **Promise<Response>** - A global Response object.

### Example
```javascript
const res = await fetch("https://example.com", { impersonate: "chrome124" });
console.log(res.status, await res.text());
```
```

--------------------------------

### AsyncWebSocket.connect()

Source: https://lexiforest.github.io/impers/api/classes/AsyncWebSocket

Establishes a connection to a WebSocket server.

```APIDOC
## static connect(url, options?)

### Description
Connects to a specified WebSocket server and returns an AsyncWebSocket instance.

### Parameters
- **url** (string) - Required - The WebSocket URL to connect to.
- **options** (WebSocketOptions) - Optional - Configuration options for the connection.
```

--------------------------------

### new Response(init)

Source: https://lexiforest.github.io/impers/api/classes/Response

Creates a new instance of the Response class.

```APIDOC
## Constructor

### Description
Creates a new Response instance based on the provided initialization object.

### Signature
`new Response(init: ResponseInit): Response`

### Parameters
- **init** (ResponseInit) - Required - Configuration object for the response.
```

--------------------------------

### Basic usage of fetch() with impersonation

Source: https://lexiforest.github.io/impers/api/functions/fetch

Demonstrates how to perform a fetch request using the impersonate option to specify a browser profile.

```typescript
const res = await fetch("https://example.com", { impersonate: "chrome124" });  

console.log(res.status, await res.text());
```

--------------------------------

### new Session(options?)

Source: https://lexiforest.github.io/impers/api/classes/Session

Creates a new instance of the Session class.

```APIDOC
## Constructor

### Description
Initializes a new Session instance for making HTTP requests.

### Parameters
- **options** (SessionOptions) - Optional - Configuration options for the session.
```

--------------------------------

### new Request(method, url, init?)

Source: https://lexiforest.github.io/impers/api/classes/Request

Creates a new instance of the Request class.

```APIDOC
## Constructor

### Description
Creates a new Request instance.

### Parameters
- **method** (string) - Required - The HTTP method.
- **url** (string | URL) - Required - The request URL.
- **init** (RequestInit) - Optional - Initialization options.
```

--------------------------------

### Uploading Files

Source: https://lexiforest.github.io/impers/usage

Illustrates the files option for uploading local files or Buffers with specific metadata.

```javascript
await impers.post("https://httpbin.org/post", {  

  data: { user: "alice" },  

  files: {  

    avatar: {  

      filename: "avatar.txt",  

      content: Buffer.from("avatar data"),  

      contentType: "text/plain",  

    },  

    screenshot: "/path/to/screenshot.png",  

  },  

});
```

--------------------------------

### options(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/options

Makes an HTTP OPTIONS request to the provided URL.

```APIDOC
## options(url, options?)

### Description
Make an HTTP OPTIONS request to the specified URL.

### Signature
`options(url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **url** (string) - Required - Request URL
- **options** (RequestOptions) - Optional - Request options

### Returns
- **Promise<Response>** - A promise that resolves to the Response object.
```

--------------------------------

### Save impers API key

Source: https://lexiforest.github.io/impers/impersonation

Store your impersonate.pro API key in the local configuration file.

```bash
npx impers config --api-key imp_your_api_key
```

--------------------------------

### Perform a request with the low-level Curl API

Source: https://lexiforest.github.io/impers/low-level-curl

Demonstrates initializing a Curl instance, setting the target URL, handling response data with a write function, and applying browser impersonation. The cleanup method is called in a finally block to ensure resources are released.

```typescript
import { Curl, CurlOpt } from "impers";  

  

const curl = new Curl();  

const chunks: Buffer[] = [];  

  

try {  

  curl.setOpt(CurlOpt.URL, "https://example.com");  

  curl.setWriteFunction((chunk) => chunks.push(Buffer.from(chunk)));  

  

  // Browser impersonation (requires curl-impersonate)  

  curl.impersonate("chrome124");  

  

  // Or use manual fingerprinting  

  // curl.setJa3("771,4865-4866-...");  

  // curl.setAkamai("1:65536;...");  

  

  curl.perform();  

  console.log(Buffer.concat(chunks).toString());  

} finally {  

  curl.cleanup();  

}  
```

--------------------------------

### Set LIBCURL_PATH environment variable

Source: https://lexiforest.github.io/impers/install

Use this command to point to a custom libcurl-impersonate library path if you do not wish to use the automatically downloaded version.

```bash
export LIBCURL_PATH=/path/to/libcurl-impersonate.so
```

--------------------------------

### WebSocketOptions

Source: https://lexiforest.github.io/impers/api/interfaces/WebSocketOptions

Configuration options for WebSocket connections.

```APIDOC
## Interface: WebSocketOptions

### Description
Configuration object for initializing WebSocket connections.

### Properties
- **auth** (AuthType) - Optional - Authentication credentials.
- **autoReconnect** (boolean) - Optional - Whether to automatically reconnect on disconnect.
- **cookies** (CookiesInit) - Optional - Request cookies.
- **headers** (HeadersInit) - Optional - Request headers.
- **impersonate** (string) - Optional - Browser identifier to impersonate.
- **maxMessageSize** (number) - Optional - Maximum message size in bytes (default: 64MB).
- **maxReconnectAttempts** (number) - Optional - Maximum number of reconnect attempts.
- **proxy** (string) - Optional - Proxy URL.
- **reconnectDelay** (number) - Optional - Delay between reconnect attempts in milliseconds.
- **timeout** (number) - Optional - Connection timeout in seconds.
- **verify** (boolean) - Optional - Whether to verify SSL certificates (default: true).
```

--------------------------------

### head(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/head

Performs an HTTP HEAD request to the provided URL. Returns a Promise that resolves to a Response object.

```APIDOC
## head(url, options?)

### Description
Make an HTTP HEAD request to the specified URL.

### Signature
`head(url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **url** (string) - Required - Request URL
- **options** (RequestOptions) - Optional - Request options

### Returns
- **Promise<Response>** - A promise that resolves to the Response object.
```

--------------------------------

### request(method, url, options?)

Source: https://lexiforest.github.io/impers/api/functions/request

Performs an HTTP request with the specified method, URL, and optional configuration.

```APIDOC
## request(method, url, options?)

### Description
Make an HTTP request to a specified URL using the provided HTTP method and optional configuration.

### Signature
`request(method: string, url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **method** (string) - Required - HTTP method (e.g., GET, POST, PUT, DELETE)
- **url** (string) - Required - The target URL for the request
- **options** (RequestOptions) - Optional - Configuration options for the request

### Returns
- **Promise<Response>** - A promise that resolves to the Response object.

### Example
```javascript
const response = await request("GET", "https://httpbin.org/get");
console.log(response.json());
```
```

--------------------------------

### Connect to a WebSocket and send a message

Source: https://lexiforest.github.io/impers/websockets

Establishes a WebSocket connection with a specified impersonation profile, sends a message, and listens for the response until a specific condition is met.

```javascript
import * as impers from "impers";  

  

const ws = await impers.wsConnect("wss://echo.websocket.org", {  

  impersonate: "chrome124",  

});  

  

await ws.send("Hello, World!");  

  

for await (const message of ws) {  

  console.log("Received:", message);  

  if (message.type === "text" && message.data === "Hello, World!") {  

    break;  

  }  

}  

  

await ws.close();
```

--------------------------------

### versionInfo()

Source: https://lexiforest.github.io/impers/api/classes/Easy

Retrieves detailed version information.

```APIDOC
## versionInfo()

### Description
Get detailed version information.

### Returns
- **unknown** - Detailed version information object.
```

--------------------------------

### List available fingerprints

Source: https://lexiforest.github.io/impers/impersonation

View all builtin and cached fingerprints.

```bash
npx impers list
```

--------------------------------

### Browser Impersonation and Proxy Configuration

Source: https://lexiforest.github.io/impers/usage

Demonstrates how to use the impersonate parameter to mimic browser TLS fingerprints, pin specific versions, provide custom JA3/Akamai strings, and configure HTTP/SOCKS proxies.

```javascript
import * as impers from "impers";  

  

// Notice the impersonate parameter  

const r = await impers.get("https://tls.peet.ws/api/all", { impersonate: "chrome" });  

  

console.log(r.json());  

// output: {..., "ja3_hash": "aa56c057ad164ec4fdcb7a5a283be9fc", ...}  

// the JA3 fingerprint should be the same as the target browser  

  

// To keep using the latest browser version as impers updates,  

// simply set impersonate="chrome" without specifying a version.  

// Other similar values are: "safari" and "firefox"  

const r2 = await impers.get("https://tls.peet.ws/api/all", { impersonate: "chrome" });  

  

// To pin a specific version, use version numbers together.  

const r3 = await impers.get("https://tls.peet.ws/api/all", { impersonate: "chrome124" });  

  

// To impersonate other than browsers, bring your own JA3/Akamai strings.  

// See the examples directory for details.  

const r4 = await impers.get("https://tls.peet.ws/api/all", {  

  ja3: "771,4865-4866-4867-49195-49199,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0",  

  akamai: "1:65536;3:1000;4:6291456;6:262144|15663105|0|m,a,s,p",  

});  

  

// HTTP/SOCKS proxies are supported  

const r5 = await impers.get("https://tls.peet.ws/api/all", {  

  impersonate: "chrome",  

  proxy: "http://localhost:3128",  

});  

  

const r6 = await impers.get("https://tls.peet.ws/api/all", {  

  impersonate: "chrome",  

  proxy: "socks5://localhost:1080",  

});
```

--------------------------------

### version()

Source: https://lexiforest.github.io/impers/api/classes/Easy

Retrieves the libcurl version string.

```APIDOC
## version()

### Description
Get libcurl version string.

### Returns
- **string** - The version string.
```

--------------------------------

### post(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/post

Makes an HTTP POST request to the specified URL with optional request configurations.

```APIDOC
## post(url, options?)

### Description
Make an HTTP POST request.

### Signature
`post(url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **url** (string) - Required - Request URL
- **options** (RequestOptions) - Optional - Request options

### Returns
- **Promise<Response>** - Response object

### Example
```javascript
const response = await post("https://httpbin.org/post", {  
  json: { key: "value" }  
});  
console.log(response.json());
```
```

--------------------------------

### Session.request(method, url, options?)

Source: https://lexiforest.github.io/impers/api/classes/Session

Makes a generic HTTP request.

```APIDOC
## [method] [url]

### Description
Executes an HTTP request with the specified method.

### Parameters
- **method** (string) - Required - The HTTP method (e.g., GET, POST).
- **url** (string) - Required - The target URL.
- **options** (RequestOptions) - Optional - Request configuration.
```

--------------------------------

### impers.wsConnect

Source: https://lexiforest.github.io/impers/websockets

Establishes a new WebSocket connection with specific impersonation settings.

```APIDOC
## impers.wsConnect(url, options)

### Description
Establishes a WebSocket connection to the specified URL with optional impersonation settings.

### Parameters
- **url** (string) - Required - The WebSocket server URL.
- **options** (object) - Optional - Configuration object containing the `impersonate` string.

### Usage Example
```javascript
const ws = await impers.wsConnect("wss://echo.websocket.org", {
  impersonate: "chrome124",
});
```
```

--------------------------------

### Configure custom JA3 and Akamai fingerprints

Source: https://lexiforest.github.io/impers/custom-fingerprints

Demonstrates how to pass JA3 and Akamai fingerprint strings directly to the impers.get method.

```typescript
import * as impers from "impers";  

  

// JA3 TLS fingerprint format: tls_version,ciphers,extensions,curves,curve_formats  

const ja3 = "771,4865-4866-4867-49195-49199,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0";  

  

// Akamai HTTP/2 fingerprint format: settings|window_update|streams|header_order  

const akamai = "1:65536;3:1000;4:6291456;6:262144|15663105|0|m,a,s,p";  

  

const r = await impers.get("https://tls.peet.ws/api/all", { ja3, akamai });
```

--------------------------------

### getPlatformInfo()

Source: https://lexiforest.github.io/impers/api/functions/getPlatformInfo

Retrieves an object containing platform-specific information including architecture, platform name, and Apple Silicon status.

```APIDOC
## getPlatformInfo()

### Description
Retrieves an object containing platform-specific information including architecture, platform name, and Apple Silicon status.

### Signature
`getPlatformInfo(): object`

### Returns
- **arch** (string) - The system architecture.
- **isAppleSilicon** (boolean) - Indicates if the device is running on Apple Silicon.
- **platform** (string) - The name of the platform.
```

--------------------------------

### resolveLibrary()

Source: https://lexiforest.github.io/impers/api/functions/resolveLibrary

Resolves the libcurl library path based on environment variables, auto-detection, or downloading.

```APIDOC
## resolveLibrary()

### Description
Resolves the libcurl library path with the following priority: 
1. LIBCURL_IMPERSONATE_PATH env var
2. LIBCURL_PATH env var
3. Auto-detect curl-impersonate in common locations
4. Download curl-impersonate into cache (optional)
5. System libcurl

### Signature
`resolveLibrary(): Promise<LibraryInfo>`

### Returns
- **Promise<LibraryInfo>** - A promise that resolves to the library information.
```

--------------------------------

### setJa3Options(curl, ja3, permute?)

Source: https://lexiforest.github.io/impers/api/functions/setJa3Options

Parses and applies a JA3 fingerprint string to a provided curl handle.

```APIDOC
## setJa3Options(curl, ja3, permute?)

### Description
Parses and applies a JA3 fingerprint string to a curl handle. The JA3 format expected is: tls_version,ciphers,extensions,curves,curve_formats.

### Parameters
- **curl** (Easy) - Required - The Curl instance to configure.
- **ja3** (string) - Required - JA3 fingerprint string (e.g., "771,4865-4866-4867-49195-49199,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0").
- **permute?** (boolean) - Optional - If true, does not set extension order, allowing for random permutation. Defaults to false.

### Returns
- **void**
```

--------------------------------

### List fingerprints in JSON format

Source: https://lexiforest.github.io/impers/impersonation

Output the list of available fingerprints in a machine-readable JSON format.

```bash
npx impers list --json
```

--------------------------------

### aContent()

Source: https://lexiforest.github.io/impers/api/classes/Response

Retrieves the response content as a Buffer asynchronously.

```APIDOC
## aContent()

### Description
Async content getter that returns the response body as a Buffer.

### Returns
- **Promise<Buffer>**
```

--------------------------------

### new CurlMulti(options?)

Source: https://lexiforest.github.io/impers/api/classes/CurlMulti

Creates a new instance of the CurlMulti class.

```APIDOC
## Constructor

### Signature
`new CurlMulti(options?: MultiOptions)`

### Description
Initializes a new multi-handle interface for managing concurrent transfers.

### Parameters
- **options** (MultiOptions) - Optional - Configuration options for the multi-handle.
```

--------------------------------

### Handling Response Streams

Source: https://lexiforest.github.io/impers/usage

Demonstrates using contentCallback and headerCallback to process response body and header chunks as they are received.

```javascript
await impers.get("https://example.com/data", {  

  impersonate: "firefox",  

  stream: true,  

  headerCallback: (chunk) => {  

    console.log(chunk.toString("latin1"));  

  },  

  contentCallback: (chunk) => {  

    console.log(chunk);  

  },  

});
```

--------------------------------

### Update fingerprint cache

Source: https://lexiforest.github.io/impers/impersonation

Fetch the latest fingerprints and save them to the local cache.

```bash
npx impers update
```

--------------------------------

### Session.post(url, options?)

Source: https://lexiforest.github.io/impers/api/classes/Session

Performs an HTTP POST request.

```APIDOC
## POST [url]

### Description
Performs an HTTP POST request using the session.

### Parameters
- **url** (string) - Required - The target URL.
- **options** (RequestOptions) - Optional - Request configuration.
```

--------------------------------

### perform()

Source: https://lexiforest.github.io/impers/api/classes/CurlMulti

Adds a Curl handle and performs the transfer asynchronously.

```APIDOC
## perform()

### Signature
`perform(curl: Easy): Promise<TransferResult>`

### Description
Adds a Curl handle to the multi-handle and executes the transfer asynchronously. Returns a Promise that resolves when the transfer completes.

### Parameters
- **curl** (Easy) - Required - The Curl handle to perform.
```

--------------------------------

### new Fingerprint(value?)

Source: https://lexiforest.github.io/impers/api/classes/Fingerprint

Constructs a new instance of the Fingerprint class, optionally initialized with a partial Fingerprint object.

```APIDOC
## Constructor

### Description
Creates a new instance of the `Fingerprint` class.

### Signature
`new Fingerprint(value?: Partial<Fingerprint>): Fingerprint`

### Parameters
- **value** (Partial<Fingerprint>) - Optional - An object containing partial properties to initialize the Fingerprint instance. Defaults to `{}`.
```

--------------------------------

### put(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/put

Makes an HTTP PUT request to the specified URL.

```APIDOC
## put(url, options?)

### Description
Make an HTTP PUT request to the provided URL with optional request configurations.

### Signature
`put(url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **url** (string) - Required - The request URL.
- **options** (RequestOptions) - Optional - The request options.

### Returns
- **Promise<Response>** - A promise that resolves to the Response object.
```

--------------------------------

### clone()

Source: https://lexiforest.github.io/impers/api/classes/Request

Creates a clone of the current request.

```APIDOC
## Method: clone()

### Description
Clones the current request instance.

### Returns
- **Request** - A new instance of the Request.
```

--------------------------------

### resolveLibcurlPath()

Source: https://lexiforest.github.io/impers/api/functions/resolveLibcurlPath

Retrieves the path to the libcurl library as a promise.

```APIDOC
## resolveLibcurlPath()

### Description
Retrieves the file system path for the libcurl library.

### Signature
`resolveLibcurlPath(): Promise<string>`

### Returns
- **Promise<string>** - A promise that resolves to the string path of the libcurl library.
```

--------------------------------

### addPart(options)

Source: https://lexiforest.github.io/impers/api/classes/CurlMime

Adds a new part to the MIME structure.

```APIDOC
## addPart

### Description
Adds a part to the MIME structure using the provided options.

### Parameters
- **options** (CurlMimePartOptions) - Required - Configuration options for the MIME part.
```

--------------------------------

### new CurlMime(curl)

Source: https://lexiforest.github.io/impers/api/classes/CurlMime

Creates a new instance of the CurlMime class.

```APIDOC
## Constructor

### Description
Creates a new CurlMime instance associated with a cURL Easy handle.

### Parameters
- **curl** (Easy) - Required - The cURL Easy handle to associate with the MIME object.
```

--------------------------------

### aText()

Source: https://lexiforest.github.io/impers/api/classes/Response

Retrieves the response content as a string asynchronously.

```APIDOC
## aText()

### Description
Async text getter that returns the response body as a string.

### Returns
- **Promise<string>**
```

--------------------------------

### Use extraFp for fine-grained fingerprint control

Source: https://lexiforest.github.io/impers/custom-fingerprints

Shows how to define an extraFp object to specify detailed TLS signature algorithms, supported groups, and HTTP/2 settings.

```typescript
// For fine-grained control, use extraFp  

const extraFp: impers.ExtraFingerprint = {  

  tlsSigAlgs: ["ecdsa_secp256r1_sha256", "rsa_pss_rsae_sha256"],  

  tlsSupportedGroups: ["X25519", "P-256", "P-384"],  

  http2Settings: {  

    1: 65536,   // HEADER_TABLE_SIZE  

    3: 1000,    // MAX_CONCURRENT_STREAMS  

    4: 6291456, // INITIAL_WINDOW_SIZE  

    6: 262144,  // MAX_HEADER_LIST_SIZE  

  },  

  http2PseudoHeaderOrder: ["m", "a", "s", "p"],  

};  

  

const r2 = await impers.get("https://tls.peet.ws/api/all", { extraFp });
```

--------------------------------

### setOpt(option, value)

Source: https://lexiforest.github.io/impers/api/classes/Easy

Sets a curl option, automatically selecting the correct variant based on the value type.

```APIDOC
## setOpt(option, value)

### Description
Set a curl option. Automatically selects the correct setopt variant based on value type.

### Parameters
- **option** (number) - Required - The curl option identifier.
- **value** (unknown) - Required - The value to set for the option.

### Returns
- **void**
```

--------------------------------

### AsyncWebSocket.send()

Source: https://lexiforest.github.io/impers/api/classes/AsyncWebSocket

Sends binary data over the WebSocket connection.

```APIDOC
## send(data)

### Description
Sends binary data to the server.

### Parameters
- **data** (Buffer | Uint8Array) - Required - The binary data to send.
```

--------------------------------

### setContent()

Source: https://lexiforest.github.io/impers/api/classes/Response

Sets the response content directly.

```APIDOC
## setContent(content)

### Description
Set the response content directly.

### Parameters
- **content** (Buffer) - Required - The content to set.

### Returns
- **void**
```

--------------------------------

### FingerprintManager Methods

Source: https://lexiforest.github.io/impers/api/classes/FingerprintManager

A collection of static methods available in the FingerprintManager class for managing fingerprints and configuration settings.

```APIDOC
## FingerprintManager Methods

### getApiKey(env?)
Retrieves the API key from the environment.

### getApiRoot(env?)
Retrieves the API root URL from the environment.

### getConfigDir(env?)
Retrieves the configuration directory path.

### getConfigPath(env?)
Retrieves the full path to the configuration file.

### getFingerprint(target, env?)
Retrieves a specific fingerprint by target string.

### getFingerprintPath(env?)
Retrieves the path where fingerprints are stored.

### listFingerprints(env?)
Returns a list of FingerprintRow objects.

### loadFingerprints(env?)
Loads all fingerprints into a record object.

### setApiKey(apiKey, env?)
Sets the API key in the provided environment.

### updateFingerprints(env?)
Updates the fingerprint records and returns a promise resolving to the number of updated items.
```

--------------------------------

### setJa3(ja3, permute?)

Source: https://lexiforest.github.io/impers/api/classes/Easy

Applies a JA3 TLS fingerprint to the curl session.

```APIDOC
## setJa3(ja3, permute?)

### Description
Apply JA3 TLS fingerprint to the current session. Requires curl-impersonate for full extension control.

### Parameters
- **ja3** (string) - Required - JA3 fingerprint string (format: tls_version,ciphers,extensions,curves,curve_formats).
- **permute** (boolean) - Optional - If true, don't enforce extension order (allows random permutation). Defaults to false.

### Returns
- **void**
```

--------------------------------

### hasImpersonateSupport()

Source: https://lexiforest.github.io/impers/api/classes/Easy

Checks if impersonation is available in the current environment.

```APIDOC
## hasImpersonateSupport()

### Description
Check if impersonation is available.

### Returns
- **boolean** - Returns true if supported, false otherwise.
```

--------------------------------

### Sending JSON and Form Data

Source: https://lexiforest.github.io/impers/usage

Shows how to send JSON payloads using the json key and application/x-www-form-urlencoded data using the data key.

```javascript
await impers.post("https://httpbin.org/post", {  

  json: { message: "hello" },  

});  

  

await impers.post("https://httpbin.org/post", {  

  data: { username: "test", password: "secret" },  

});
```

--------------------------------

### setStringList(option, values)

Source: https://lexiforest.github.io/impers/api/classes/Easy

Sets a curl_slist option from an array of strings.

```APIDOC
## setStringList(option, values)

### Description
Set a curl_slist option from an array of strings.

### Parameters
- **option** (number) - Required - The curl option identifier.
- **values** (string[]) - Required - An array of strings to set.

### Returns
- **void**
```

--------------------------------

### json()

Source: https://lexiforest.github.io/impers/api/classes/Response

Parses the response body as JSON synchronously.

```APIDOC
## json<T>()

### Description
Parse response body as JSON (sync).

### Returns
- **T**
```

--------------------------------

### aJson()

Source: https://lexiforest.github.io/impers/api/classes/Response

Parses the response body as JSON asynchronously.

```APIDOC
## aJson<T>()

### Description
Async JSON parser that returns the response body parsed as type T.

### Returns
- **Promise<T>**
```

--------------------------------

### Sending Multipart Form Data

Source: https://lexiforest.github.io/impers/usage

Demonstrates sending multipart/form-data requests, including explicit parts with filenames and content types.

```javascript
await impers.post("https://httpbin.org/post", {  

  multipart: [  

    { name: "title", value: "Quarterly report" },  

    {  

      name: "attachment",  

      value: Buffer.from("file contents"),  

      filename: "report.txt",  

      contentType: "text/plain",  

    },  

  ],  

});
```

--------------------------------

### free()

Source: https://lexiforest.github.io/impers/api/classes/CurlMime

Frees the resources associated with the CurlMime instance.

```APIDOC
## free

### Description
Releases the memory and resources allocated for the CurlMime instance.
```

--------------------------------

### close()

Source: https://lexiforest.github.io/impers/api/classes/CurlMulti

Closes the multi-handle and cleans up resources.

```APIDOC
## close()

### Signature
`close(): Promise<void>`

### Description
Closes the multi-handle and releases all associated resources.
```

--------------------------------

### iterContent()

Source: https://lexiforest.github.io/impers/api/classes/Response

Iterates over the response content in chunks.

```APIDOC
## iterContent(chunkSize?)

### Description
Iterate over response content in chunks.

### Parameters
- **chunkSize** (number) - Optional - The size of each chunk.

### Returns
- **AsyncIterableIterator<Buffer>**
```

--------------------------------

### setAkamaiOptions(curl, akamai)

Source: https://lexiforest.github.io/impers/api/functions/setAkamaiOptions

Configures a curl handle with the specified Akamai HTTP/2 fingerprint string.

```APIDOC
## setAkamaiOptions(curl, akamai)

### Description
Parses and applies an Akamai HTTP/2 fingerprint string to a curl handle. The fingerprint format follows the structure: settings|window_update|streams|header_order.

### Parameters
- **curl** (Easy) - Required - The Curl instance to configure.
- **akamai** (string) - Required - Akamai fingerprint string (e.g., "1:65536;3:1000;4:6291456;6:262144|15663105|0|m,a,s,p").

### Returns
- **void** - This function does not return a value.
```

--------------------------------

### Curl Class Interface

Source: https://lexiforest.github.io/impers/low-level-curl

The primary interface for executing HTTP requests with browser impersonation.

```APIDOC
## Curl Class

### Description
The `Curl` class provides a low-level interface for making HTTP requests. It supports browser impersonation to mimic specific browser fingerprints.

### Methods
- **setOpt(option, value)**: Sets a curl option.
- **setWriteFunction(callback)**: Sets a callback to handle incoming data chunks.
- **impersonate(browser)**: Sets the browser impersonation profile (e.g., 'chrome124').
- **setJa3(fingerprint)**: Manually sets the JA3 fingerprint.
- **setAkamai(fingerprint)**: Manually sets the Akamai fingerprint.
- **perform()**: Executes the request.
- **cleanup()**: Cleans up resources used by the curl instance.
```

--------------------------------

### impers.post(url, options)

Source: https://lexiforest.github.io/impers/usage

Performs an HTTP POST request with support for various body types including JSON, form data, multipart, and file uploads.

```APIDOC
## impers.post(url, options)

### Description
Performs an HTTP POST request. Supports multiple body formats and streaming input.

### Parameters
- **url** (string) - Required - The target URL.
- **options** (object) - Optional - Configuration object:
  - **json** (object) - Optional - JSON payload.
  - **data** (object) - Optional - application/x-www-form-urlencoded payload.
  - **multipart** (array) - Optional - Array of multipart parts.
  - **files** (object) - Optional - File upload mapping.
  - **readCallback** (function) - Optional - Callback for incremental body supply.
  - **readCallbackSize** (number) - Optional - Total byte size for readCallback.
```

--------------------------------

### patch(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/patch

Makes an HTTP PATCH request to the specified URL with optional request configurations.

```APIDOC
## patch(url, options?)

### Description
Make an HTTP PATCH request.

### Signature
`patch(url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **url** (string) - Required - Request URL
- **options** (RequestOptions) - Optional - Request options

### Returns
- **Promise<Response>** - Response object
```

--------------------------------

### Hide implementation details in stack traces

Source: https://lexiforest.github.io/impers/api/classes/FingerprintError

Shows how to use the constructorOpt argument in Error.captureStackTrace to omit specific functions from the generated stack trace.

```typescript
function a() {  

  b();  

}  

  

function b() {  

  c();  

}  

  

function c() {  

  // Create an error without stack trace to avoid calculating the stack trace twice.  

  const { stackTraceLimit } = Error;  

  Error.stackTraceLimit = 0;  

  const error = new Error();  

  Error.stackTraceLimit = stackTraceLimit;  

  

  // Capture the stack trace above function b  

  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace  

  throw error;  

}  

  

a();  
```

--------------------------------

### attach(curl)

Source: https://lexiforest.github.io/impers/api/classes/CurlMime

Attaches the MIME structure to a cURL handle.

```APIDOC
## attach

### Description
Attaches the current MIME structure to the specified cURL Easy handle.

### Parameters
- **curl** (Easy) - Required - The cURL Easy handle to attach the MIME structure to.
```

--------------------------------

### iterLines()

Source: https://lexiforest.github.io/impers/api/classes/Response

Iterates over the response content line by line.

```APIDOC
## iterLines(delimiter?, keepEnds?)

### Description
Iterate over response content line by line.

### Parameters
- **delimiter** (string) - Optional - The line delimiter (default: "\n").
- **keepEnds** (boolean) - Optional - Whether to keep the line endings (default: false).

### Returns
- **AsyncIterableIterator<string>**
```

--------------------------------

### setExtraFingerprintOptions(curl, fp)

Source: https://lexiforest.github.io/impers/api/functions/setExtraFingerprintOptions

Applies ExtraFingerprint options to a curl handle.

```APIDOC
## setExtraFingerprintOptions(curl, fp)

### Description
Applies ExtraFingerprint options to a curl handle.

### Parameters
- **curl** (Easy) - The Curl instance to configure.
- **fp** (ExtraFingerprint) - Extra fingerprint options.

### Returns
- **void**
```

--------------------------------

### raiseForStatus()

Source: https://lexiforest.github.io/impers/api/classes/Response

Raises an exception if the status code indicates an error.

```APIDOC
## raiseForStatus()

### Description
Raise an exception if the status code indicates an error.

### Returns
- **void**
```

--------------------------------

### Perform request with preset fingerprint

Source: https://lexiforest.github.io/impers/impersonation

Use a cached fingerprint name directly in the impersonate request option.

```javascript
const response = await impers.get("https://example.com", {  

  impersonate: "edge_146_macos_26",  

});
```

--------------------------------

### Request Properties

Source: https://lexiforest.github.io/impers/api/classes/Request

Read-only properties available on the Request instance.

```APIDOC
## Properties

- **body** (Buffer | null) - The request body.
- **headers** (Headers) - The request headers.
- **method** (string) - The HTTP method.
- **url** (URL) - The request URL.
```

--------------------------------

### AsyncWebSocket.recv()

Source: https://lexiforest.github.io/impers/api/classes/AsyncWebSocket

Receives a message from the WebSocket with an optional timeout.

```APIDOC
## recv(timeout?)

### Description
Receives a message from the WebSocket connection using polling.

### Parameters
- **timeout** (number) - Optional - The timeout duration for the receive operation.
```

--------------------------------

### close()

Source: https://lexiforest.github.io/impers/api/classes/Response

Closes the response and cleans up resources.

```APIDOC
## close()

### Description
Close the response and perform cleanup of resources.

### Returns
- **Promise<void>**
```

--------------------------------

### getFingerprint(target)

Source: https://lexiforest.github.io/impers/api/functions/getFingerprint

Generates a Fingerprint object based on the provided target string.

```APIDOC
## getFingerprint(target)

### Description
Generates a `Fingerprint` for a specified target string.

### Signature
`getFingerprint(target: string): Fingerprint`

### Parameters
- **target** (string) - Required - The input string to generate a fingerprint for.

### Returns
- **Fingerprint** - The resulting fingerprint object.
```

--------------------------------

### Request Accessors

Source: https://lexiforest.github.io/impers/api/classes/Request

Getters for inspecting request details.

```APIDOC
## Accessors

- **hasBody**(): boolean - Checks if the body exists.
- **hostname**(): string - Returns the hostname.
- **href**(): string - Returns the full URL as a string.
- **pathname**(): string - Returns the pathname.
- **search**(): string - Returns the query string.
- **text**(): string | null - Returns the body as a string.
```

--------------------------------

### aClose()

Source: https://lexiforest.github.io/impers/api/classes/Response

Closes the response and cleans up resources asynchronously.

```APIDOC
## aClose()

### Description
Alias for the close method, used to asynchronously close the response and clean up resources.

### Returns
- **Promise<void>**
```

--------------------------------

### closeSharedMulti()

Source: https://lexiforest.github.io/impers/api/functions/closeSharedMulti

Closes the shared multi instance.

```APIDOC
## closeSharedMulti()

### Description
Closes the shared multi instance.

### Signature
`closeSharedMulti(): Promise<void>`

### Returns
- **Promise<void>** - A promise that resolves when the shared multi instance has been closed.
```

--------------------------------

### getSharedMulti()

Source: https://lexiforest.github.io/impers/api/functions/getSharedMulti

Retrieves or creates a shared CurlMulti instance.

```APIDOC
## getSharedMulti()

### Description
Get or create a shared CurlMulti instance.

### Returns
- **CurlMulti** - The shared instance of CurlMulti.
```

--------------------------------

### Incremental Request Body with readCallback

Source: https://lexiforest.github.io/impers/usage

Uses readCallback to supply request body data incrementally, optionally specifying the total size via readCallbackSize.

```javascript
const chunks = [Buffer.from("hello "), Buffer.from("world")];  

  

await impers.post("https://httpbin.org/post", {  

  headers: { "Content-Type": "text/plain" },  

  readCallbackSize: chunks.reduce((total, chunk) => total + chunk.length, 0),  

  readCallback: () => chunks.shift(),  

});
```

--------------------------------

### setStream()

Source: https://lexiforest.github.io/impers/api/classes/Response

Sets the response stream for streaming responses.

```APIDOC
## setStream(stream)

### Description
Set the response stream (for streaming responses).

### Parameters
- **stream** (AsyncIterable<Buffer>) - Required - The stream to set.

### Returns
- **void**
```

--------------------------------

### Omit frames from stack trace using constructorOpt

Source: https://lexiforest.github.io/impers/api/classes/CertificateVerifyError

Shows how to use the constructorOpt argument in Error.captureStackTrace to hide specific implementation details from the generated stack trace.

```typescript
function a() {  

  b();  

}  

  

function b() {  

  c();  

}  

  

function c() {  

  // Create an error without stack trace to avoid calculating the stack trace twice.  

  const { stackTraceLimit } = Error;  

  Error.stackTraceLimit = 0;  

  const error = new Error();  

  Error.stackTraceLimit = stackTraceLimit;  

  

  // Capture the stack trace above function b  

  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace  

  throw error;  

}  

  

a();
```

--------------------------------

### Customize fingerprint headers

Source: https://lexiforest.github.io/impers/impersonation

Retrieve an editable fingerprint object to modify headers before using it in a request.

```javascript
const fingerprint = impers.getFingerprint("edge_146_macos_26");  

fingerprint.headers["User-Agent"] = "custom user agent";  

  

const response = await impers.get("https://example.com", {  

  impersonate: fingerprint,  

});
```

--------------------------------

### WebSocket Operations

Source: https://lexiforest.github.io/impers/websockets

Methods for sending data, receiving messages, and closing the connection.

```APIDOC
## WebSocket Instance Methods

### ws.send(data)
Sends a message through the established WebSocket connection.

### Iterating Messages
The WebSocket instance supports asynchronous iteration to receive messages.

### ws.close()
Closes the active WebSocket connection.

### Usage Example
```javascript
await ws.send("Hello, World!");

for await (const message of ws) {
  console.log("Received:", message);
}

await ws.close();
```
```

--------------------------------

### Capture stack trace on an object

Source: https://lexiforest.github.io/impers/api/classes/CertificateVerifyError

Demonstrates how to use Error.captureStackTrace to add a .stack property to an object, which records the location where the method was called.

```typescript
const myObject = {};  

Error.captureStackTrace(myObject);  

myObject.stack;  // Similar to `new Error().stack`
```

--------------------------------

### Session.close()

Source: https://lexiforest.github.io/impers/api/classes/Session

Closes the session and releases resources.

```APIDOC
## close()

### Description
Closes the session and releases associated resources.
```

--------------------------------

### del(url, options?)

Source: https://lexiforest.github.io/impers/api/functions/del

Performs an HTTP DELETE request to the specified URL with optional request configurations.

```APIDOC
## del(url, options?)

### Description
Make an HTTP DELETE request.

### Signature
`del(url: string, options?: RequestOptions): Promise<Response>`

### Parameters
- **url** (string) - Required - Request URL
- **options** (RequestOptions) - Optional - Request options

### Returns
- **Promise<Response>** - Response object
```

--------------------------------

### Capture stack trace on an object

Source: https://lexiforest.github.io/impers/api/classes/FingerprintError

Demonstrates using Error.captureStackTrace to add a .stack property to an object, representing the location where the method was called.

```typescript
const myObject = {};  

Error.captureStackTrace(myObject);  

myObject.stack;  // Similar to `new Error().stack`  
```

--------------------------------

### setWriteFunction(fn)

Source: https://lexiforest.github.io/impers/api/classes/Easy

Sets the write callback function for the curl session.

```APIDOC
## setWriteFunction(fn)

### Description
Set write callback function.

### Parameters
- **fn** (WriteCallback) - Required - The callback function to handle writing data.

### Returns
- **void**
```

--------------------------------

### isClosed

Source: https://lexiforest.github.io/impers/api/classes/CurlMulti

Checks if the multi-handle has been closed.

```APIDOC
## isClosed

### Signature
`get isClosed(): boolean`

### Description
Returns true if the multi-handle has been closed, false otherwise.
```

--------------------------------

### setReadFunction(fn)

Source: https://lexiforest.github.io/impers/api/classes/Easy

Sets the read callback function for the curl session.

```APIDOC
## setReadFunction(fn)

### Description
Set read callback function.

### Parameters
- **fn** (ReadCallback) - Required - The callback function to handle reading data.

### Returns
- **void**
```

--------------------------------

### cancel()

Source: https://lexiforest.github.io/impers/api/classes/CurlMulti

Cancels a specific transfer.

```APIDOC
## cancel()

### Signature
`cancel(curl: Easy, error?: Error): boolean`

### Description
Cancels a specific transfer associated with the provided Curl handle.

### Parameters
- **curl** (Easy) - Required - The Curl handle to cancel.
- **error** (Error) - Optional - An optional error object to associate with the cancellation.
```

--------------------------------

### AsyncWebSocket.close()

Source: https://lexiforest.github.io/impers/api/classes/AsyncWebSocket

Closes the active WebSocket connection.

```APIDOC
## close(code?, reason?)

### Description
Closes the WebSocket connection with an optional status code and reason.

### Parameters
- **code** (number) - Optional - The close status code (default: 1000).
- **reason** (string) - Optional - The reason for closing the connection.
```

--------------------------------

### activeCount

Source: https://lexiforest.github.io/impers/api/classes/CurlMulti

Retrieves the number of currently active transfers.

```APIDOC
## activeCount

### Signature
`get activeCount(): number`

### Description
Returns the current number of active transfers being managed by the multi-handle.
```