sshsurf-ts3-bot/README.md

# Linux TeamSpeak Bot

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:
   ```bash
   node -v
   ```
2. **TeamSpeak 3 server credentials**  
   - Hostname/IP
   - Query Port
   - Server Port
   - Query Username & Password
3. **API Endpoint** (for container/server control):
   - A valid base URL for the API (e.g., `https://your-api.example.com` or `http://localhost:3000`).

---

## Installation

1. **Clone or download** this repository:
   ```bash
   git clone https://git.ssh.surf/snxraven/sshsurf-ts3-bot.git
   ```
2. **Install dependencies** in the project directory:
   ```bash
   cd sshsurf-ts3-bot
   npm install
   ```
3. **Create configuration files**:
   - `config.json`  
   - `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
   node teamspeak.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.

| Command                | Description                                                                                       | Example                          |
|------------------------|---------------------------------------------------------------------------------------------------|----------------------------------|
| `!hello`              | Calls `/hello` on the API and returns the “hello” message.                                        | `!hello`                         |
| `!name`               | Returns the username from the API (`/name`).                                                      | `!name`                          |
| `!stats`              | Shows the container/server stats (`/stats`).                                                      | `!stats`                         |
| `!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.

---

## Folder Structure

```
linux-teamspeak-bot/
├── config.json         // Your TS3 + API config
├── tokens.json         // Stored user tokens
├── package.json        // Node.js dependencies
├── teamspeak.js            // Main bot code
└── README.md           // This documentation
```