# Socket

## 📖 Socket Module

The `socket` module in the **ono-web** package provides a **WebSocket client** to subscribe and listen to real-time updates from the ONO core node network.

***

### 📦 Importing

To use the socket module, import it as follows:

```javascript
const OnoSocketClient = require('ono-web').socket;
```

***

### 🚀 Class: `OnoSocketClient`

The `OnoSocketClient` class allows you to **connect**, **subscribe to events**, and **receive real-time updates** from the ONO blockchain network.

***

### 🔨 Constructor

#### `new OnoSocketClient(coreHost?)`

Creates a new instance of the socket client.\
If no `coreHost` is provided, it defaults to `ws://core.ono.gg`.

#### 📥 Parameters

| Name       | Type   | Required | Description                                                          |
| ---------- | ------ | -------- | -------------------------------------------------------------------- |
| `coreHost` | string | Optional | Custom ONO core node WebSocket address (e.g., `ws://127.0.0.1:5001`) |

#### 📝 Example

```javascript
const client = new OnoSocketClient(); // Uses default ws://core.ono.gg
const client = new OnoSocketClient('http://127.0.0.1:5001'); // Custom address
```

***

### 📡 Methods

#### 1. `subscribe(handler, errorHandler)`

Connects to the WebSocket server and subscribes to real-time blockchain updates (like new blocks, transactions, etc.).

#### 📥 Parameters

| Name           | Type     | Description                                                                 |
| -------------- | -------- | --------------------------------------------------------------------------- |
| `handler`      | function | Callback that handles incoming messages. Receives `(message, socketClient)` |
| `errorHandler` | function | Callback to handle JSON parsing or connection errors. Receives `(error)`    |

#### ✅ Behavior

* Establishes a WebSocket connection.
* Automatically manages connection open/close state.
* Calls `handler` when a message is received.
* Calls `errorHandler` if there’s an error processing a message.

#### 📝 Example

```javascript
const client = new OnoSocketClient();

client.subscribe(
    (message, socket) => {
        console.log('Received message:', message);
    },
    (error) => {
        console.error('Socket error:', error);
    }
);
```

***

#### 2. `setCoreHost(address)`

Changes the WebSocket core host **after initialization**, allowing reconnection to a different node.

#### 📥 Parameters

| Name      | Type   | Description                                                         |
| --------- | ------ | ------------------------------------------------------------------- |
| `address` | string | New WebSocket address for core node (e.g., `http://127.0.0.1:5001`) |

#### 📝 Example

```javascript
client.setCoreHost('http://127.0.0.1:5001');
```

***

#### 3. `disconnect()`

Gracefully closes the WebSocket connection and unsubscribes from updates.

#### 📝 Example

```javascript
client.disconnect();
```

***

### 📚 Usage Example (Full Flow)

```javascript
const OnoSocketClient = require('ono-web').socket;

// Initialize client
const client = new OnoSocketClient('http://127.0.0.1:5001');

// Subscribe to blockchain events
client.subscribe(
    (message, socket) => {
        console.log('New update:', message);
    },
    (error) => {
        console.error('Failed to handle message:', error);
    }
);

// After some time, disconnect if needed
setTimeout(() => {
    client.disconnect();
    console.log('Disconnected from ONO core node.');
}, 60000); // Disconnect after 1 minute
```

***

### ⚙️ Internal Mechanics

* Each client instance gets a **unique `node-id`** using UUID, passed as query parameter for identification:\
  `ws://core.ono.gg?node-id=generated-uuid`
* Automatically manages:
  * Connection opening
  * Re-subscription protection
  * Message parsing and error handling

***

### 🚨 Notes

* Make sure your core node allows external WebSocket connections if using a remote or custom host.
* Handle sensitive events securely when working with `/secure` WebSocket updates.
* Always manage `disconnect()` properly to avoid memory leaks or dangling connections.