TeamSpeak 3 TypeScript ServerQuery Client

This client is designed to help you to create your own application wich need to communicate with the TeamSpeak 3 Server through the ServerQuery API.

Installation

$ npm install @ts3/query-client --save

Introduction

Since the version 3, the client do not use anymore callbacks and implement exclusively promises.

Promises are resolved when the error ID is equal to 0 and rejected when the error ID is equal or greater than 1, a resolved Promise return always an Array of object.

Events

The client emit a lot of events, they allow you to debug and write your logfiles as you want.

| Event name | Arguments | Description ---|---|--- info | {string} msg | Give info message error | {iError} err | Error object wich contain the id, the msg and the query. warn | {string} msg | Warning messages are emitted when you update some sensitive features. connect | none | See Net Event connect end | none | See Net Event end close | none | See Net Event close

Interfaces

Some interfaces are available to type your data, you can load them from @ts3/query-client/interfaces

Errors

Errors are provided with 3 parameters:

• {number} id: The error ID, if the error comes from the socket the ID is always 9000
• {string} msg: The error message
• {string} query: The query which occur the error

Note: The query is not available when the error is not occurred by a query.

Data

The data are always given when the promise is resolved, this is always an object wich contains these informations:

{
    query: {
        id: number,
        query: string
    },
    data: [{..row1..}, {..row2..}] 
}

TODO

This client is a work in progress, i have some ideas to implement when i had the time :

• Interfaces for each kind of data
• Attach an event name on query
• Each server command as a method
• Implement filetransfert methods and interfaces
• Units tests

Feel free to open a pull request to improve the client.

Anti Flood

The client is provided with an anti-flood feature.

It's highly recommended to get the instanceinfo properties just after the login command and adjust the AntiFlood configuration. By default you can send 10 queries each 3 seconds, ask your hoster about the flood rate limit if you are banned with the default values.

You can update the AntiFlood configuration with .setAntiFloodLimits(commands, time), the function return the new configuration.

If your client is whitelisted you can disable this feature by using .disableAntiFlood(), you can aslo enable it with .enableAntiFlood().

Connect to the server

Connect the QueryClient to the TS3 server, the event connect is emitted when the QueryClient is successfully connected to the server.

import TS3QueryClient from "@ts3/query-client";
import {iError} from "@ts3/query-client/interfaces";


(async () => {
    
    let TS3Client = new TS3QueryClient();
    
    // Connect to the server
    let connected = await TS3Client.connect("127.0.0.1", 10011).catch((err: iError) => {
        
        if(err.id > 0) {
            console.log(err.id, err.msg);
            process.exit(1); // Connection failed, kill the process
        }
    
    });
    
});

Build and send your query

You can build and escape your queries easily. If you want send the query in priority you can use queryNow.

TS3Client.query('serveredit', {virtualserver_name:'TeamSpeak ]|[ Server'}, []).then(
    (renamed: boolean) => { // serveredit don't return data, get true when the query is resolved
       if(renamed)
           console.log("Virtualserver name edited!");
    },
    (err: iError) => {

        // If the server return an error
        if(err.id > 0)
            // do the stuff
      
    }
);

Send query

If you need you can send raw queries, they are not escaped. If you want send the query in priority you can use sendNow.

let clientlist = await TS3Client.send(`clientlist`).catch((err: iError) => {

  // If the server return an error
  if(err.id > 0)
      // do the stuff
});

if(clientlist.data.length > 0)
    // Perform treatment on the clientlist

Prepared queries

For more efficience you can set a lots of prepared querie, this is a good way to reuse the same queries in many places with differents values.

If you want execute the query in priority you can use executeNow.

Note: You must respect the arguments list order used in your query

// Prepare the queries
TS3Client.prepare('serverEdit', 'serveredit virtualserver_name=%s virtualserver_password=%s');
TS3Client.prepare('setVServerMaxClients', 'serveredit virtualserver_maxclients=%d');

// Execute the query, the values are escaped using teamspeak3-utils
TS3Client.execute('serveredit', ['TeamSpeak ]|[ Server', 'newPassword']).catch((err) => {

  // If the server return an error
  if(err.id > 0) throw new Error(err.msg);

  console.log(rows)
  // Do the stuff...
});

TS3Client.execute('setVServerMaxClients', ['numbers expected']);

TeamSpeak 3 Query Utilities

The client use the @ts3/query-utils package, so you can import it in your application.