hypermc-api-user-install-bot/README.md

Here's a detailed `README.md` file for the provided code, which is a Discord bot for managing Minecraft servers using the MyMCLib API. This README includes installation instructions, configuration steps, usage, and a breakdown of the commands.

### README.md

---

# My-MC Link Discord Bot (BETA)

Welcome to the **My-MC Link Discord Bot**, a Discord bot designed to manage your Minecraft servers directly through Discord commands! This bot uses the MyMCLib API to interact with your server, allowing you to perform essential tasks like starting/stopping servers, managing players, installing mods, and much more.

## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Commands](#commands)
- [Token Handling](#token-handling)
- [Usage](#usage)
- [Contributing](#contributing)

## Features
- Start, stop, and restart your Minecraft server with simple commands.
- Check real-time server statistics like memory usage, CPU, and more.
- Manage player bans/unbans, send messages to players, and view online players.
- Install, uninstall, and list mods directly from Discord.
- View real-time server logs and connection details (SFTP, P2P, etc.).
- Works as a **user-installable app**!

## Installation

### Prerequisites
- **Node.js**: Ensure you have Node.js (v16 or later) installed on your machine.
- **npm**: Comes bundled with Node.js for installing dependencies.
- **Discord Bot Token**: You will need to create a Discord bot and get its token. [Learn how](https://discordjs.guide/preparations/setting-up-a-bot-application.html#creating-your-bot).

### Steps

1. **Clone the Repository**
   ```bash
   git clone https://git.ssh.surf/hypermc/hypermc-api-user-install-bot
   cd hypermc-api-user-install-bot
   ```

2. **Install Dependencies**
   Install all necessary dependencies using `npm`:
   ```bash
   npm install
   ```

3. **Configuration**
   You need to create a `config.json` file for the bot's configuration. Here's an example:
   ```json
   {
     "token": "YOUR_DISCORD_BOT_TOKEN",
     "clientId": "YOUR_DISCORD_CLIENT_ID",
     "endpoint": "YOUR_AUTHENTICATION_ENDPOINT",
     "password": "YOUR_AUTHENTICATION_PASSWORD"
   }
   ```

4. **Run the Bot**
   Once everything is configured, start the bot:
   ```bash
   node bot.js
   ```

## Configuration

The `config.json` file must contain the following:

- **token**: The token for your Discord bot.
- **clientId**: The client ID of your bot from the Discord developer portal.
- **endpoint**: The authentication endpoint for obtaining user API tokens.
- **password**: The password required by the authentication service.

Here is an example `config.json` file:
```json
{
  "token": "YOUR_DISCORD_BOT_TOKEN",
  "clientId": "YOUR_DISCORD_CLIENT_ID",
  "endpoint": "https://your-auth-endpoint.com/auth",
  "password": "your-auth-password"
}
```

## Commands

The bot provides the following commands to manage your Minecraft server:

- `/server-time` – Get the current server time.
- `/server-stats` – Get server statistics, including CPU and memory usage.
- `/server-log` – Retrieve the real-time server log URL.
- `/start-server` – Start the Minecraft server.
- `/stop-server` – Stop the Minecraft server.
- `/restart-server` – Restart the Minecraft server.
- `/create-link` – Create a custom server link.
- `/create-sftp-link` – Create an SFTP link.
- `/get-connection-hash` – Retrieve the server's P2P connection hash.
- `/get-connection-hash-sftp` – Retrieve the server's SFTP connection hash.
- `/get-players` – Get a list of players currently online on the server.
- `/get-website-url` – Get the server's website URL.
- `/get-map-url` – Get the server's map URL.
- `/ban-player` – Ban a player by username.
- `/unban-player` – Unban a player by username.
- `/send-message` – Send a message to all players on the server.
- `/send-private-message` – Send a private message to a specific player.
- `/execute-console-command` – Execute a command in the server console.
- `/give-item` – Give an item to a player.
- `/install-mod` – Install a mod on the server by its ID.
- `/uninstall-mod` – Uninstall a mod from the server by its ID.
- `/get-installed-mods` – List all installed mods on the server.

## Token Handling

This bot automatically handles user API tokens. When a user runs any command, the bot checks if a valid token exists for that user. If not, it fetches and stores a new token via the configured authentication endpoint.

Tokens are stored in a `tokens.json` file on the server.

- **fetchAndSaveToken**: Automatically requests and stores a new API token if needed.
- **getToken**: Retrieves a stored token or requests a new one if none exists or if the token is invalid.

### Token Persistence

The tokens are stored locally in a `tokens.json` file using the `jsonfile` package:
```json
{
  "userId": "user-token"
}
```

The bot will load tokens from this file when needed and automatically refresh them if expired or invalid.

## Usage

Once the bot is up and running, invite it to your Discord server. Users can run commands like `/server-time` or `/start-server` to interact with the Minecraft server.

Commands can be run either in public channels or privately, depending on how you've set up the bot. Some responses can also be made ephemeral (visible only to the user who executed the command).

For example:
- Running `/server-stats` will display current server stats like CPU and memory usage.
- Running `/install-mod modid` will install a specified mod on the server.

### Example Command Usage

```bash
/server-stats
# Displays server statistics

/ban-player username:exampleUser
# Bans 'exampleUser' from the Minecraft server

/give-item username:exampleUser item:diamond amount:5
# Gives 5 diamonds to 'exampleUser'
```

## Contributing

Feel free to open an issue or submit a pull request if you'd like to contribute to this project. Any improvements or additional features are welcome!