A TeamSpeak 3 bot written in Node.js (using [`ts3-nodejs-library`](https://www.npmjs.com/package/ts3-nodejs-library)) that can receive commands in channels or private messages, authenticate users via token, and communicate with a custom API to perform various container and server operations.
> **Table of Contents**
> - [Features](#features)
> - [Prerequisites](#prerequisites)
> - [Installation](#installation)
> - [Configuration](#configuration)
> - [Usage](#usage)
> - [Available Commands](#available-commands)
> - [Folder Structure](#folder-structure)
> - [Contributing](#contributing)
> - [License](#license)
---
## Features
- **TeamSpeak Connection**: Connects to a TS3 server as a Query Client bot.
- **Token Management**: Asks users for their API token via private message, and stores them securely in a JSON file.
- **API Integration**: Makes authenticated API calls (with a custom header `x-ssh-auth`) to manage a container (start, stop, restart, get stats/info, etc.).
- **Command Parsing**: In-channel commands prefixed with `!`, and private message commands.
- **Directory/Command Execution**: Allows users to run commands (`!x <command>`) inside the container and navigate directories (`cd`, `cd ..`, `cd ~`, etc.).
- **Extensible**: Easily add more commands or API endpoints.
---
## Prerequisites
1.**Node.js (v14 or later)**
Make sure you have Node.js installed. You can check by running:
-`tokens.json` (an empty file to store user tokens)
See [Configuration](#configuration) below for details.
---
## Configuration
You need two main JSON files to make the bot work:
1.**`config.json`**
An example configuration might look like this:
```json
{
"TS_HOST": "127.0.0.1",
"TS_QUERY_PORT": 10011,
"TS_SERVER_PORT": 9987,
"TS_USERNAME": "serveradmin",
"TS_PASSWORD": "supersecretpassword",
"apiBaseURL": "http://localhost:3000"
}
```
-`TS_HOST`: The IP/hostname of your TeamSpeak server.
-`TS_QUERY_PORT`: The query port (default is `10011`).
-`TS_SERVER_PORT`: The virtual server port (default is `9987`).
-`TS_USERNAME`&`TS_PASSWORD`: Your TeamSpeak query login credentials.
-`apiBaseURL`: The base URL of your custom API (for container operations).
2.**`tokens.json`**
This file stores the tokens per user, in JSON format. It’s empty or non-existent on first run:
```json
{}
```
The bot automatically populates this file with user tokens after requesting them via private message.
Make sure both files are located in the same directory where the bot is run.
---
## Usage
1.**Start the bot**:
```bash
npm start
```
or
```bash
node index.js
```
_(Adjust the filename if necessary.)_
2.**Check the console** for the bot’s output:
- It will print `TeamSpeak bot is ready and connected.` once fully started.
- When a user connects, it may request a token if one is not already stored.
3.**Interact in TeamSpeak**:
- Open your TeamSpeak client and connect to the same server.
- In a channel or server chat, prefix commands with `!` (e.g., `!hello`, `!stats`, etc.).
- If you don’t have a token on record, the bot will send you a private message prompting you to reply with your token. Just **reply without `!`** to that private message.
---
## Available Commands
All commands should be typed in a channel or server chat with an exclamation mark (`!`) prefix. Some **private message** commands (`!ping`, or direct token entry) are also available.
| `!uptime` | Returns uptime information (`/uptime`). | `!uptime` |
| `!start` | Starts the container/server via `/start`. | `!start` |
| `!stop` | Stops the container/server via `/stop`. | `!stop` |
| `!restart` | Restarts the container/server via `/restart`. | `!restart` |
| `!info` | Shows container/server info such as IP, memory, CPU, restarts, status, etc. (`/info`). | `!info` |
| `!time` | Shows when the container will expire (`/time`). | `!time` |
| `!root-password` | Requests and returns a new root password (`/rootpass`). | `!root-password` |
| `!new-api-key` | Generates and returns a new API key (`/new-key`). | `!new-api-key` |
| `!key-expire-time` | Checks when the current API key will expire (`/key-time`). | `!key-expire-time` |
| `!x <command>` | Executes a command in the container at the user’s working directory (`/exec`). Allows `cd` usage. | `!x cd /root`, `!x ls -la`, etc. |
| `!notify <message>` | Sends a custom notification via the API (`/notify`). | `!notify System going offline` |
### Special `!x` Sub-Commands (In-Container Navigation)
-`!x cd <path>` — Change directory.
-`!x cd /root` (absolute path)
-`!x cd ..` (move up one directory)
-`!x cd ~` (go to `/root`)
-`!x <any_command>` — Executes `<any_command>` in the current directory of the container.
