LinkUp-P2P-Chat/chatBot/README.md

# Bot System Documentation

## Overview

This document provides a comprehensive guide to the bot system, detailing its structure, functionalities, and how to set it up. This bot system leverages the Hyperswarm network to enable decentralized communication and supports various types of messages, including text, files, and audio.

## Table of Contents

1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
   - [Configuration](#configuration)
3. [Bot Architecture](#bot-architecture)
   - [Client Class](#client-class)
   - [Message Classes](#message-classes)
4. [Command Handling](#command-handling)
5. [Event Handling](#event-handling)
6. [Running the Bot](#running-the-bot)
7. [API Reference](#api-reference)

## Introduction

This bot system is designed for decentralized chat rooms using the Hyperswarm network. It supports multiple message types and dynamic command handling, making it highly customizable and extensible.

## Getting Started

### Prerequisites

- Node.js (version 14.x or later)
- npm (version 6.x or later)

### Installation

1. Clone the repository:
   ```bash
   git clone https://git.ssh.surf/snxraven/LinkUp-P2P-Chat.git
   cd LinkUp-P2P-Chat
   ```

2. Install the dependencies:
   ```bash
   npm install
   ```

3. Change to bot directory
   ```bash
   cd chatBot
   ```

4. Run the bot:
   ```
   node bot.js
   ```


### Configuration

Create a `.env` file in the root directory and add the following environment variables:

```
BOT_NAME=MyBot
ON_READY_MESSAGE=Bot is ready and operational!
LINKUP_ROOM_ID=<room_id>
```

## Bot Architecture

### Client Class

The `Client` class is the core component of the bot system. It handles connections to the Hyperswarm network, manages message sending and receiving, and emits events for various actions.

#### Constructor

```javascript
constructor(botName)
```

- `botName`: The name of the bot.

#### Methods

- `initializeServeDrive()`: Initializes the ServeDrive for serving files and audio.
- `getRandomPort()`: Returns a random port number.
- `fetchAvatar(filePath)`: Fetches and sets the bot's avatar from a local file.
- `setupSwarm()`: Sets up the Hyperswarm network and connection handlers.
- `joinChatRoom(chatRoomID)`: Joins a specified chat room.
- `sendTextMessage(message)`: Sends a text message.
- `sendFileMessage(filePath, fileType)`: Sends a file message.
- `sendAudioMessage(filePath, audioType)`: Sends an audio message.
- `sendMessage(message)`: Sends a generic message.
- `destroy()`: Disconnects the bot and shuts down the Hyperswarm network.

### Message Classes

The bot system supports various message types through dedicated classes, all extending the base `Message` class.

#### Message Class

```javascript
class Message {
    constructor(messageType, peerName, peerAvatar, topic, timestamp)
}
```

#### TextMessage Class

```javascript
class TextMessage extends Message {
    constructor(peerName, peerAvatar, topic, timestamp, message)
    static new(bot, message)
}
```

#### FileMessage Class

```javascript
class FileMessage extends Message {
    constructor(peerName, peerAvatar, topic, timestamp, fileName, fileUrl, fileType, fileData)
    static new(bot, fileName, fileUrl, fileType, fileBuffer)
}
```

#### AudioMessage Class

```javascript
class AudioMessage extends Message {
    constructor(peerName, peerAvatar, topic, timestamp, audioUrl, audioType, audioData)
    static new(bot, audioUrl, audioType, audioBuffer)
}
```

#### IconMessage Class

```javascript
class IconMessage extends Message {
    constructor(peerName, peerAvatar, timestamp)
    static new(bot, avatarBuffer)
}
```

## Command Handling

Commands are dynamically loaded from the `commands` directory. Each command is a JavaScript module with a default export containing a `handler` function.

### Example Command Module

```javascript
// commands/example.js
export default {
  handler: (bot, args, message) => {
    bot.sendTextMessage(`Example command executed with args: ${args.join(' ')}`);
  }
};
```

## Event Handling

The bot uses Node.js `EventEmitter` to handle events. Key events include:

- `onMessage`: Triggered when a new message is received.
- `onFile`: Triggered when a file message is received.
- `onAudio`: Triggered when an audio message is received.
- `onIcon`: Triggered when an icon message is received.
- `onError`: Triggered when there is a connection error.
- `onBotJoinRoom`: Triggered when the bot joins a room.

### Example Event Listener

```javascript
bot.on('onMessage', (peer, message) => {
  console.log(`Message from ${message.peerName}: ${message.message}`);
});
```

## Running the Bot

To start the bot, run the following command:

```bash
node bot.js
```

Ensure that the `.env` file is correctly configured and that all necessary dependencies are installed.

## API Reference

### Client

- `constructor(botName)`: Creates a new instance of the Client.
- `initializeServeDrive()`: Initializes ServeDrive.
- `getRandomPort()`: Generates a random port number.
- `fetchAvatar(filePath)`: Fetches the bot's avatar.
- `setupSwarm()`: Sets up the Hyperswarm network.
- `joinChatRoom(chatRoomID)`: Joins a specified chat room.
- `sendTextMessage(message)`: Sends a text message.
- `sendFileMessage(filePath, fileType)`: Sends a file message.
- `sendAudioMessage(filePath, audioType)`: Sends an audio message.
- `sendMessage(message)`: Sends a generic message.
- `destroy()`: Disconnects the bot.

### TextMessage

- `constructor(peerName, peerAvatar, topic, timestamp, message)`: Creates a new text message.
- `static new(bot, message)`: Creates a new text message instance.

### FileMessage

- `constructor(peerName, peerAvatar, topic, timestamp, fileName, fileUrl, fileType, fileData)`: Creates a new file message.
- `static new(bot, fileName, fileUrl, fileType, fileBuffer)`: Creates a new file message instance.

### AudioMessage

- `constructor(peerName, peerAvatar, topic, timestamp, audioUrl, audioType, audioData)`: Creates a new audio message.
- `static new(bot, audioUrl, audioType, audioBuffer)`: Creates a new audio message instance.

### IconMessage

- `constructor(peerName, peerAvatar, timestamp)`: Creates a new icon message.
- `static new(bot, avatarBuffer)`: Creates a new icon message instance.