### Install fetch-socks

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Install the fetch-socks package using npm.

```shell
npm install fetch-socks
```

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

### Equivalent socksDispatcher and Agent Initialization

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Demonstrates that calling socksDispatcher with connection options is equivalent to creating an Undici Agent with a connector created by socksConnector.

```javascript
import { socksConnector, socksDispatcher } from "fetch-socks";
import { Agent } from "undici";

const proxy = { type: 5, host: "::1", port: 1080 };
const connect = { /* ... */ };
const agentOptions = { /* ... */ };

socksDispatcher(proxy, { ...agentOptions, connect });

// Is equivalent to
new Agent({ ...agentOptions, connect: socksConnector(proxy, connect) });
```

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

### socksDispatcher(proxies, options?)

Source: https://context7.com/kaciras/fetch-socks/llms.txt

Creates a fully configured Undici Agent that routes all connections through the given SOCKS proxy or proxy chain. The returned agent can be passed to `fetch` as the `dispatcher` option, or set as the global dispatcher to proxy all requests transparently. Accepts an optional `SocksDispatcherOptions` object that forwards all standard Undici `Agent` options plus a `connect` field for TLS upgrade settings. Passing an empty array as `proxies` causes direct connections (no proxy).

```APIDOC
## socksDispatcher(proxies, options?)

### Description
Creates a fully configured Undici `Agent` that routes all connections through the given SOCKS proxy or proxy chain. The returned agent can be passed to `fetch` as the `dispatcher` option, or set as the global dispatcher to proxy all requests transparently. Accepts an optional `SocksDispatcherOptions` object that forwards all standard Undici `Agent` options plus a `connect` field for TLS upgrade settings. Passing an empty array as `proxies` causes direct connections (no proxy).

### Method
`socksDispatcher`

### Parameters
#### `proxies`
- **type**: `object` or `Array<object>` - Required - Configuration for the SOCKS proxy or an array of proxies for chaining.
  - **type**: `number` - Required - SOCKS protocol version (4 or 5).
  - **host**: `string` - Required - The hostname or IP address of the proxy server.
  - **port**: `number` - Required - The port of the proxy server.
  - **userId**: `string` - Optional - Username for SOCKS authentication.
  - **password**: `string` - Optional - Password for SOCKS authentication.

#### `options`
- **type**: `object` - Optional - Additional options for the Undici Agent.
  - **connect**: `object` - Optional - TLS upgrade settings.
    - **rejectUnauthorized**: `boolean` - Optional - Whether to reject unauthorized TLS certificates.

### Request Example
```typescript
import { socksDispatcher } from "fetch-socks";

// Single SOCKS5 proxy
const dispatcher = socksDispatcher({
  type: 5,
  host: "127.0.0.1",
  port: 1080,
});

const response = await fetch("https://example.com", { dispatcher });
console.log(response.status);
console.log(await response.text());

// SOCKS5 with username/password authentication
const authDispatcher = socksDispatcher({
  type: 5,
  host: "proxy.example.com",
  port: 1080,
  userId: "foo",
  password: "bar",
});

const secureResponse = await fetch("https://api.example.com/data", {
  dispatcher: authDispatcher,
});
console.log(await secureResponse.json());

// SOCKS5 proxy chain (two hops)
const chainDispatcher = socksDispatcher([
  { type: 5, host: "first-proxy.example.com",  port: 1080, userId: "user1", password: "pass1" },
  { type: 5, host: "second-proxy.example.com", port: 1081 },
]);

const chainResponse = await fetch("https://example.com", { dispatcher: chainDispatcher });
console.log(chainResponse.status);

// TLS over SOCKS (disable cert verification for self-signed certs)
const tlsDispatcher = socksDispatcher(
  { type: 5, host: "127.0.0.1", port: 1080 },
  { connect: { rejectUnauthorized: false } },
);

const tlsResponse = await fetch("https://internal.corp", { dispatcher: tlsDispatcher });
console.log(await tlsResponse.text());

// Set proxy globally
const kGlobalDispatcher = Symbol.for("undici.globalDispatcher.2"); // undici >= 8
(global as any)[kGlobalDispatcher] = socksDispatcher({
  type: 5,
  host: "127.0.0.1",
  port: 1080,
});

const implicitResponse = await fetch("https://example.com"); // routed through proxy
console.log(implicitResponse.status);

// Proxy WebSocket connections
const wsDispatcher = socksDispatcher({ type: 5, host: "127.0.0.1", port: 1080 });
import { WebSocket } from "undici";

const ws = new WebSocket("ws://echo.example.com", { dispatcher: wsDispatcher });
ws.addEventListener("open", () => ws.send("hello"));
ws.addEventListener("message", (e) => console.log(e.data));

// Direct connection (empty proxy list)
const directDispatcher = socksDispatcher([]);
const directResponse = await fetch("https://example.com", { dispatcher: directDispatcher });
console.log(directResponse.status);
```

### Response
#### Success Response (200)
- **dispatcher**: `Agent` - An Undici Agent configured to use the specified SOCKS proxy(ies).
```

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

### Fetch via SOCKS5 Proxy

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Configure and use socksDispatcher to fetch resources through a SOCKS5 proxy. Ensure the proxy host and port are correctly specified.

```javascript
import { socksDispatcher } from "fetch-socks";

const dispatcher = socksDispatcher({
    type: 5,
    host: "::1",
    port: 1080,

    //userId: "username",
    //password: "password",
});

const response = await fetch("https://example.com", { dispatcher });
console.log(response.status);
console.log(await response.text());
```

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

### Fetch via SOCKS Proxy Chain (TypeScript)

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Use TypeScript to define a chain of SOCKS proxies for fetching resources. TLS options can be configured for the connection.

```typescript
import { fetch } from "undici";
import { socksDispatcher, SocksProxies } from "fetch-socks";

const proxyConfig: SocksProxies = [{
    type: 5,
    host: "::1",
    port: 1080,
}, {
    type: 5,
    host: "127.0.0.1",
    port: 1081,
}];

const dispatcher = socksDispatcher(proxyConfig, {
    connect: {
        // set some TLS options
        rejectUnauthorized: false,
    },
});

const response = await fetch("https://example.com", { dispatcher });
```

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

### Create Proxied Undici Agent with socksDispatcher

Source: https://context7.com/kaciras/fetch-socks/llms.txt

Use socksDispatcher to create an Undici Agent for proxying fetch requests. It supports single SOCKS5 proxies, username/password authentication, and proxy chaining.

```typescript
import { socksDispatcher } from "fetch-socks";

// --- Single SOCKS5 proxy ---
const dispatcher = socksDispatcher({
  type: 5,
  host: "127.0.0.1",
  port: 1080,
});

const response = await fetch("https://example.com", { dispatcher });
console.log(response.status);          // 200
console.log(await response.text());    // HTML of example.com
```

```typescript
// --- SOCKS5 with username/password authentication ---
const authDispatcher = socksDispatcher({
  type: 5,
  host: "proxy.example.com",
  port: 1080,
  userId: "foo",
  password: "bar",
});

const secureResponse = await fetch("https://api.example.com/data", {
  dispatcher: authDispatcher,
});
console.log(await secureResponse.json());
```

```typescript
// --- SOCKS5 proxy chain (two hops) ---
const chainDispatcher = socksDispatcher([
  { type: 5, host: "first-proxy.example.com",  port: 1080, userId: "user1", password: "pass1" },
  { type: 5, host: "second-proxy.example.com", port: 1081 },
]);

const chainResponse = await fetch("https://example.com", { dispatcher: chainDispatcher });
console.log(chainResponse.status);    // 200
```

```typescript
// --- TLS over SOCKS (disable cert verification for self-signed certs) ---
const tlsDispatcher = socksDispatcher(
  { type: 5, host: "127.0.0.1", port: 1080 },
  { connect: { rejectUnauthorized: false } },
);

const tlsResponse = await fetch("https://internal.corp", { dispatcher: tlsDispatcher });
console.log(await tlsResponse.text());
```

```typescript
// --- Set proxy globally (affects all fetch calls without explicit dispatcher) ---
const kGlobalDispatcher = Symbol.for("undici.globalDispatcher.2"); // undici >= 8
(global as any)[kGlobalDispatcher] = socksDispatcher({
  type: 5,
  host: "127.0.0.1",
  port: 1080,
});

const implicitResponse = await fetch("https://example.com"); // routed through proxy
console.log(implicitResponse.status);
```

```typescript
// --- Proxy WebSocket connections ---
const wsDispatcher = socksDispatcher({ type: 5, host: "127.0.0.1", port: 1080 });
import { WebSocket } from "undici";

const ws = new WebSocket("ws://echo.example.com", { dispatcher: wsDispatcher });
ws.addEventListener("open", () => ws.send("hello"));
ws.addEventListener("message", (e) => console.log(e.data)); // "hello"
```

```typescript
// --- Direct connection (empty proxy list) ---
const directDispatcher = socksDispatcher([]);
const directResponse = await fetch("https://example.com", { dispatcher: directDispatcher });
console.log(directResponse.status);   // 200, no proxy used
```

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

### socksDispatcher

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Creates an Undici Agent with a SOCKS connector. This function simplifies the process of setting up a dispatcher for SOCKS proxying with fetch and WebSocket.

```APIDOC
## `socksDispatcher(proxies, options?)`

Create a Undici Agent with socks connector.

* `proxies` Same as `socksConnector`'s.
* `options` (optional) [Agent options](https://undici.nodejs.org/#/docs/api/Agent). The `connect` property will be used to create socks connector.

```javascript
import { socksConnector, socksDispatcher } from "fetch-socks";
import { Agent } from "undici";

const proxy = { type: 5, host: "::1", port: 1080 };
const connect = { /* ... */ };
const agentOptions = { /* ... */ };

socksDispatcher(proxy, { ...agentOptions, connect });

// Is equivalent to
new Agent({ ...agentOptions, connect: socksConnector(proxy, connect) });
```
```

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

### socksConnector

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Creates an Undici connector that establishes a connection through SOCKS proxies. This can be used to chain multiple SOCKS proxies.

```APIDOC
## `socksConnector(proxies, connectOptions?)`

Create an [Undici connector](https://undici.nodejs.org/#/docs/api/Connector) which establish the connection through socks proxies.

* `proxies` The proxy server to use or the list of proxy servers to chain. If you pass an empty array it will connect directly.
* `connectOptions` (optional) The options used to perform directly connect or TLS upgrade, see [here](https://undici.nodejs.org/#/docs/api/Connector?id=parameter-buildconnectorbuildoptions)
```

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

### Set Global SOCKS Proxy

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Set the SOCKS dispatcher globally to proxy all subsequent fetch requests. Supports different undici versions.

```javascript
import { socksDispatcher } from "fetch-socks";

const dispatcher = socksDispatcher({ /* ... */});

// For undici <= 7
global[Symbol.for("undici.globalDispatcher.1")] = dispatcher;

// For undici >= 8
global[Symbol.for("undici.globalDispatcher.2")] = dispatcher;
```

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

### Proxy WebSocket Connections

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Use socksDispatcher to proxy WebSocket connections. The dispatcher should be passed in the WebSocket constructor options.

```javascript
import { socksDispatcher } from "fetch-socks";

const dispatcher = socksDispatcher({ /* ... */});
const ws = new WebSocket(`ws://example.com`, { dispatcher });
```

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

### HTTP Tunneling with socksConnector

Source: https://github.com/kaciras/fetch-socks/blob/master/README.md

Create a SOCKS connection over an HTTP tunnel using socksConnector. This involves establishing an HTTP connection first and then performing the SOCKS handshake.

```javascript
import { Client, Agent } from "undici";
import { socksConnector } from "fetch-socks";

const socksConnect = socksConnector({
    type: 5,
    host: "::1",
    port: 1080,
});

async function connect(options, callback) {
    // First establish a connection to the HTTP proxy server (localhost:80).
    const client = new Client("http://localhost:80");
    const { socket, statusCode } = await client.connect({
        // Tell the server to connect to the next ([::1]:1080)
        path: "::1:1080",
    });
    if (statusCode !== 200) {
        callback(new Error("Proxy response !== 200 when HTTP Tunneling"));
    } else {
        // Perform socks handshake on the connection.
        socksConnect({ ...options, httpSocket: socket }, callback);
    }
}

const dispatcher = new Agent({ connect });
const response = await fetch("https://example.com", { dispatcher });
```

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

### Create Undici Connector with socksConnector

Source: https://context7.com/kaciras/fetch-socks/llms.txt

Use `socksConnector` to create an Undici-compatible Connector for SOCKS proxies. It can be used inside a custom Agent, for performing SOCKS handshakes on pre-existing sockets (like HTTP CONNECT tunnels), or for proxy chaining.

```typescript
import { socksConnector } from "fetch-socks";
import { Agent, Client, fetch } from "undici";
import * as net from "node:net";

// --- Use connector inside a custom Agent ---
const connector = socksConnector(
  { type: 5, host: "127.0.0.1", port: 1080 },
  { timeout: 5000 },                    // 5 s connect timeout
);

const agent = new Agent({ connect: connector });
const response = await fetch("https://example.com", { dispatcher: agent });
console.log(response.status);          // 200
```

```typescript
// Equivalent shorthand via socksDispatcher:
// socksDispatcher({ type: 5, host: "127.0.0.1", port: 1080 }, { connect: { timeout: 5000 } })
```

```typescript
// --- Perform SOCKS handshake on a pre-existing socket (HTTP CONNECT tunnel) ---
const socksConnect = socksConnector({
  type: 5,
  host: "127.0.0.1",
  port: 1080,
});

async function connect(options: any, callback: any) {
  // First, open a raw TCP connection to the HTTP proxy
  const httpProxyClient = new Client("http://http-proxy.example.com:3128");
  const { socket, statusCode } = await httpProxyClient.connect({
    path: "127.0.0.1:1080",           // ask HTTP proxy to tunnel to the SOCKS proxy
  });

  if (statusCode !== 200) {
    return callback(new Error(`HTTP proxy returned ${statusCode}`));
  }

  // Now perform the SOCKS handshake on the existing TCP socket
  socksConnect({ ...options, httpSocket: socket }, callback);
}

const tunnelAgent = new Agent({ connect });
const tunnelResponse = await fetch("https://example.com", { dispatcher: tunnelAgent });
console.log(tunnelResponse.status);   // 200
```

```typescript
// --- Proxy chain with connector directly ---
const chainConnector = socksConnector([
  { type: 5, host: "proxy1.example.com", port: 1080 },
  { type: 5, host: "proxy2.example.com", port: 1081 },
]);

const chainAgent = new Agent({ connect: chainConnector });
const chainResponse = await fetch("http://example.com", { dispatcher: chainAgent });
console.log(chainResponse.status);    // 200
```

```typescript
// --- Direct connection (bypass proxy) ---
const directConnector = socksConnector([]);  // empty array → no proxy
const directAgent = new Agent({ connect: directConnector });
const directResponse = await fetch("https://example.com", { dispatcher: directAgent });
console.log(directResponse.status);   // 200
```

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

### Configure Proxies with SocksProxies Type

Source: https://context7.com/kaciras/fetch-socks/llms.txt

The `SocksProxies` type alias configures SOCKS proxies for `socksDispatcher` or `socksConnector`. It accepts a single `SocksProxy` object or an array for proxy chaining. Supports SOCKS4/5, authentication with userId/password.

```typescript
import { socksDispatcher, SocksProxies } from "fetch-socks";

// --- Typed proxy configuration ---
const singleProxy: SocksProxies = {
  type: 5,
  host: "127.0.0.1",
  port: 1080,
  userId: "alice",
  password: "secret",
};

// Array form enables proxy chaining
const proxyChain: SocksProxies = [
  { type: 5, host: "entry.example.com",  port: 1080, userId: "u1", password: "p1" },
  { type: 5, host: "middle.example.com", port: 1081 },
  { type: 4, host: "exit.example.com",   port: 1082 },
];

const dispatcher = socksDispatcher(proxyChain);
const response = await fetch("https://example.com", { dispatcher });
console.log(response.status); // 200
```

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

### SocksProxies type

Source: https://context7.com/kaciras/fetch-socks/llms.txt

Defines the type for SOCKS proxy configuration, accepting a single proxy object or an array for chaining. Used by both `socksConnector` and `socksDispatcher`.

```APIDOC
### `SocksProxies` type — Proxy configuration

`SocksProxies` is a re-exported type alias that accepts either a single `SocksProxy` object or an array of `SocksProxy` objects (from the [`socks`](https://www.npmjs.com/package/socks) package). Both `socksConnector` and `socksDispatcher` accept this type as their first argument. The key fields of `SocksProxy` are `type` (4 or 5), `host` or `ipaddress`, `port`, and optionally `userId` / `password` for authenticated SOCKS5.

#### Example Usage:

1.  **Typed proxy configuration (single proxy)**
    ```typescript
    import { socksDispatcher, SocksProxies } from "fetch-socks";

    const singleProxy: SocksProxies = {
      type: 5,
      host: "127.0.0.1",
      port: 1080,
      userId: "alice",
      password: "secret",
    };

    const dispatcher = socksDispatcher(singleProxy);
    const response = await fetch("https://example.com", { dispatcher });
    console.log(response.status);
    ```

2.  **Proxy chaining (array of proxies)**
    ```typescript
    import { socksDispatcher, SocksProxies } from "fetch-socks";

    const proxyChain: SocksProxies = [
      { type: 5, host: "entry.example.com",  port: 1080, userId: "u1", password: "p1" },
      { type: 5, host: "middle.example.com", port: 1081 },
      { type: 4, host: "exit.example.com",   port: 1082 },
    ];

    const dispatcher = socksDispatcher(proxyChain);
    const response = await fetch("https://example.com", { dispatcher });
    console.log(response.status);
    ```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.