# holesail-client

> A client for connecting to Holesail P2P reverse proxy.

Latest version **2.3.0** (published 2025-10-26) · GPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install holesail-client
pnpm add holesail-client
yarn add holesail-client
bun add holesail-client
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: no vulnerabilities; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.3.0 |
| Published | 2025-10-26 |
| First published | 2024-03-07 |
| Weekly downloads | 0 |
| License | GPL-3.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 45.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | supersuryaansh |
| Maintainers | supersuryaansh |
| Keywords | holesail, hyperdht, supersu |

## Links

- npm: https://www.npmjs.com/package/holesail-client
- Repository: https://github.com/holesail/holesail-client
- Homepage: https://github.com/holesail/holesail-client#readme
- Issues: https://github.com/holesail/holesail-client/issues
- npm.io page: https://npm.io/package/holesail-client

## Dependencies (4)

- [b4a](https://npm.io/package/b4a.md) ^1.7.3
- [z32](https://npm.io/package/z32.md) ^1.1.0
- [hyperdht](https://npm.io/package/hyperdht.md) ^6.27.0
- [@holesail/hyper-cmd-lib-net](https://npm.io/package/@holesail/hyper-cmd-lib-net.md) ^1.1.1

## Recent versions

- 2.3.0 (latest) — 2025-10-26
- 3.0.0-dev.0 (dev) — 2026-09-09
- 2.2.0 — 2025-08-07
- 2.1.1 — 2025-07-25
- 2.1.0 — 2025-05-25
- 2.0.5 — 2025-03-30
- 2.0.4 — 2025-03-30
- 2.0.3 — 2025-03-29
- 2.0.2 — 2025-03-26
- 2.0.1 — 2025-03-23
- 2.0.0 — 2025-03-23
- 1.1.7 — 2024-12-16
- 1.1.6 — 2024-11-09
- 1.1.5 — 2024-11-07
- 1.1.4 — 2024-09-15
- … 11 more at https://npm.io/package/holesail-client/versions

## README

# Holesail Client

[Join our Discord Support Server](https://discord.gg/TQVacE7Vnj)

The Holesail Client is a Node.js and Bare module for connecting to Holesail Servers with secure and efficient data relaying.

---

## Installation

Install the Holesail Client module via npm:

```bash
npm install holesail-client
```

---

## Usage

### Importing the Module

To use the module, require it in your project:

```javascript
const HolesailClient = require('holesail-client')
```

### Creating an Instance

Create a new instance of the `HolesailClient` class by passing your peer key:

```javascript
const client = new HolesailClient({ key: '<key>' })
```

#### Secure Mode

To avoid leaking access capability on the DHT, pass the optional "secure" flag. Ensure the server is also configured for secure mode:

```javascript
const client = new HolesailClient({ key: '<key>', secure: true })
```

### Connecting to the Server

Use the `connect` method to establish a connection to the Holesail Server, opts are auto detected but you can specify custom opts:

```javascript
client.connect({ port: 5000, host: '127.0.0.1', udp: true }, () => {
  console.log('Connected to the server')
})
```

### Destroying the Connection

To terminate the connection and clean up resources, call the `destroy` method:

```javascript
client.destroy()
```

---

### Resuming and Pausing

You can also resume or pause the connection:

```javascript
await client.resume()
await client.pause()
```

---

## Example

Here is a complete example demonstrating how to use the Holesail Client:

```javascript
const HolesailClient = require('holesail-client')

// Replace with your peer key
const client = new HolesailClient({ key: 'fwkkgncpatjpt5j6n53beqjoz7wtxtbse8d7u9z1y17esbz5dhpo' })

client.connect({ port: 8000, host: '127.0.0.1', udp: true }, () => {
  console.log('Connected to the server')
})

setTimeout(() => {
  console.log('Closing connection...')
  client.destroy()
}, 5000)
```

---

## API Reference

### `new HolesailClient(opts)`

Creates a new instance of the `HolesailClient` class.

#### Parameters:

- opts (object): Options object:
  - key (string): A hexadecimal string representing your peer key.
  - secure (boolean, optional): Pass true to enable private connections. The server must also be running in secure mode. [See private vs public mode](https://docs.holesail.io/terminology/private-vs-public-connection-string)

---

### `connect(options, callback)`

Establishes a connection to a Holesail Server.

#### Parameters:

- `options` (object): Connection options:
  - `port` (number): Port number of the server.
  - `address` (string): IP address of the server (default: "127.0.0.1").
  - `udp` (boolean, optional): Set to `true` for UDP connections.
- `callback` (function): A function called once the connection is successfully established.

---

### `destroy()`

Terminates the connection and releases associated resources.

### `resume()`

Resumes the connection if it was paused.

### `pause()`

Pauses the connection.

### `get(opts)`

Retrieves a mutable record stored on the DHT.

---

### `client.info`

Provides information about the current state of the client, including:

- state: Current state of the client (e.g., 'listening', 'paused', 'destroyed').
- secure: Indicates whether the connection is private.
- port: Current port used for the connection.
- host: Current host used for the connection.
- protocol: Current protocol being used ('udp' or 'tcp').
- key: Connection key from the server.
- publicKey: The public key announced on DHT for discovery.

---

## License

Holesail Client is released under the [GPL-v3 License](https://www.gnu.org/licenses/gpl-3.0.en.html).

For more details, see the [LICENSE](https://www.gnu.org/licenses/gpl-3.0.en.html) file.

---

## Community and Support

Join our [Discord Support Server](https://discord.gg/TQVacE7Vnj) for help, discussions, and updates.

---
_Source: https://npm.io/package/holesail-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._