ts3-nodejs-library
TeamSpeak Server Query API
Last updated 2 months ago by multivitamin .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install ts3-nodejs-library 
SYNC missed versions from official npm registry.

TS3-NodeJS-Library

Build Status npm Coverage Status Discord

The TS3 NodeJS Library has been strongly influenced by PlanetTeamSpeaks TS3 PHP Framework

Introduction

This library can connect to a TeamSpeak Server Query interface, send and receive commands aswell as upload and download files via Filetransfer!

With vscode you will receive powerful autocomplete of functions and their return values, so vscode is highly recommended!

Install

npm install --save ts3-nodejs-library

Documentation

You can find all necessary documentation here!

Example

Send a message to all non Query Clients connected:

//import with typescript
import { TeamSpeak, QueryProtocol } from "ts3-nodejs-library"
//import with javascript
//const { TeamSpeak } = require("ts3-nodejs-library")

//create a new connection
TeamSpeak.connect({
  host: "localhost",
  protocol: QueryProtocol.RAW, //optional
  queryport: 10011, //optional
  serverport: 9987,
  username: "serveradmin",
  password: "",
  nickname: "NodeJS Query Framework"
}).then(async teamspeak => {
  const clients = await teamspeak.clientList({ client_type: 0 })
  clients.forEach(client => {
    console.log("Sending 'Hello!' Message to", client.nickname)
    client.message("Hello!")
  })
}).catch(e => {
  console.log("Catched an error!")
  console.error(e)
})

Quickstart

Connecting to a TeamSpeak Server

There are 2 ways to connect with the TeamSpeak Server: using the wrapper TeamSpeak.connect() or by instanciating the TeamSpeak class by yourself

to connect with TeamSpeak.connect():

import { TeamSpeak } from "ts3-nodejs-library"

TeamSpeak.connect({
  host: "127.0.0.1",
  queryport: 10011
}).then(teamspeak => {
  //you are now connected
}).catch(e => {
  //an error occured during connecting
})

when instanciating it by yourself:

import { TeamSpeak } from "ts3-nodejs-library"

const teamspeak = new TeamSpeak({
  host: "127.0.0.1",
  queryport: 10011
})

teamspeak.on("ready", () => {
  //teamspeak connected successfully
})

teamspeak.on("error", () => {
  //teamspeak had an error
})

Configuration

Parameter Default Description
host "127.0.0.1" hostname to connect to
queryport 10011 queryport to connect to
protocol "raw" either use telnet or ssh to connect to the server
serverport empty the server port to select when connecting
username empty the username to login with (required when using ssh)
password empty the password to login with (required when using ssh)
nickname empty the nickname to connect with when selecting a server
readyTimeout 10000 timeout in ms to wait for the connection to be built
keepAlive true wether a keepalive should be sent to the teamspeak server
localAddress empty local address the socket should connect from

Error handling when connecting

the method TeamSpeak.connect() will do error handling for you, when the query fails to connect or some of the commands which are being initially used to connect may encounter an error then the query will disconnect and reject the Promise with an error

However when instanciating TeamSpeak by yourself an error event might get thrown but the ready event will never fire

thats why TeamSpeak.connect() is more preferable to build a connection

Basic Usage

Sending a command

Sending a command is simple, every command will return a Promise. If you do not know what a Promise is then please read the documentation first: developer.mozilla.org > Promise

When using NodeJS then Promises are essential for further progress

Using Promises

teamspeak.whoami().then(whoami => {
  console.log(whoami)
})

Using Async/Await

(async () => {
  const whoami = await teamspeak.whoami()
  console.log(whoami)
})()

whoami will then give you an object like

{
  virtualserver_status: "online",
  virtualserver_unique_identifier: "t1lytXTeyvmHXvNJ4ZcBBd15ugs=",
  virtualserver_port: 9987,
  virtualserver_id: 1,
  client_id: 2,
  client_channel_id: 1,
  client_nickname: "serveradmin",
  client_database_id: 0,
  client_login_name: "serveradmin",
  client_unique_identifier: "serveradmin",
  client_origin_server_id: 0
}

Events

To register for events you need to execute teamspeak.registerEvent() first in order to even receive events.

Registering for all available Events

Promise.all([
  teamspeak.registerEvent("server"),
  teamspeak.registerEvent("channel", 0),
  teamspeak.registerEvent("textserver"),
  teamspeak.registerEvent("textchannel"),
  teamspeak.registerEvent("textprivate")
])

When being registered for events you can use teamspeak.on() to register your event handlers

teamspeak.on("textmessage", ev => {
  console.log(`${ev.invoker.nickname} just send the message "${ev.msg}"`)
})

Flood Protection

Flooding will be handled automatically.

When the Query gets accused of Flooding then it will return error with id 524 and an error message which states how much time needs to be waited.

This will be parsed automatically and the Query will wait for the given time (normally its 1 second) + 100 additional milliseconds (sometimes it happens the query gets banned when still sending too early)

Reconnecting

With version 2.3 this library is able to reconnect to its TeamSpeak Server when the connection has been lost. It restores its full context this includes:

  • selecting the server
  • logging in with the last credentials
  • subscribing to all used events
  • selecting the correct nickname

all commands which have been added in meantime while the teamspeak server was not connected will be still executed after and all pending commands will be sent AFTER connecting and restoring the context

an example on how this looks like:

import { TeamSpeak, QueryProtocol } from "./src/TeamSpeak"

TeamSpeak.connect({
  host: "127.0.0.1",
  queryport: 10011,
  serverport: 9987,
  protocol: QueryProtocol.RAW,
  username: "serveradmin",
  password: "xxx",
  nickname: "test"
}).then(async teamspeak => {

  teamspeak.on("close", async () => {
    console.log("disconnected, trying to reconnect...")
    await teamspeak.reconnect(-1, 1000)
    console.log("reconnected!")
  })

})

Update Notes from 1.x to 2.x

With version 2.x support for Client Events has been dropped instead use the events from the main class TeamSpeak. Additionally it comes with TeamSpeak.connect() in order to use a promise to connect to a teamspeak server. Multiple node methods have been replaced with a getter for ex: client.getDBID() -> client.databaseId, client.getUID() -> client.uniqueIdentifier, channel.getID() -> channel.cid The testing environment now runs via jest which makes mocking and testing easier. Since this project now is written in TypeScript vscode should now be completely capable to autocomplete, so there is no need to update docs on @types. Documentation software has been switched from documentation to typedoc

Update Notes to 2.3

The close event now only gets fired when a connection has been successfully established first! In order to get errors when connecting to a server use the error event instead. This was required in order to implement the reconnect logic.

Authors

See also the list of contributors who participated in this project.

Current Tags

  • 2.4.4                                ...           latest (2 months ago)
  • 3.0.4                                ...           next (16 days ago)

64 Versions

  • 3.0.4                                ...           16 days ago
  • 3.0.3                                ...           16 days ago
  • 3.0.2                                ...           a month ago
  • 3.0.1                                ...           a month ago
  • 3.0.0                                ...           a month ago
  • 2.4.4                                ...           2 months ago
  • 2.4.3                                ...           2 months ago
  • 2.4.2                                ...           2 months ago
  • 2.4.1                                ...           3 months ago
  • 2.4.0                                ...           4 months ago
  • 2.3.3                                ...           4 months ago
  • 2.3.2                                ...           5 months ago
  • 2.3.1                                ...           6 months ago
  • 2.3.0                                ...           6 months ago
  • 2.2.0                                ...           7 months ago
  • 2.1.0                                ...           8 months ago
  • 2.0.3-a                                ...           9 months ago
  • 2.0.3                                ...           9 months ago
  • 2.0.2                                ...           10 months ago
  • 2.0.1                                ...           10 months ago
  • 2.0.0-a                                ...           10 months ago
  • 2.0.0                                ...           10 months ago
  • 1.16.1                                ...           10 months ago
  • 1.16.0                                ...           a year ago
  • 1.15.0                                ...           a year ago
  • 1.14.0                                ...           a year ago
  • 1.13.1                                ...           a year ago
  • 1.13.0                                ...           a year ago
  • 1.12.5                                ...           a year ago
  • 1.12.4                                ...           a year ago
  • 1.12.3                                ...           a year ago
  • 1.12.2                                ...           a year ago
  • 1.12.1                                ...           a year ago
  • 1.12.0                                ...           a year ago
  • 1.11.3                                ...           a year ago
  • 1.11.2                                ...           2 years ago
  • 1.11.1                                ...           2 years ago
  • 1.11.0                                ...           2 years ago
  • 1.10.3                                ...           2 years ago
  • 1.10.2                                ...           2 years ago
  • 1.10.1                                ...           2 years ago
  • 1.10.0                                ...           2 years ago
  • 1.9.0                                ...           2 years ago
  • 1.8.4                                ...           2 years ago
  • 1.8.3                                ...           2 years ago
  • 1.8.2                                ...           2 years ago
  • 1.8.1                                ...           2 years ago
  • 1.8.0                                ...           2 years ago
  • 1.7.1                                ...           2 years ago
  • 1.7.0                                ...           2 years ago
  • 1.6.0                                ...           2 years ago
  • 1.5.0                                ...           2 years ago
  • 1.4.0                                ...           2 years ago
  • 1.3.0                                ...           2 years ago
  • 1.2.2                                ...           2 years ago
  • 1.2.1                                ...           2 years ago
  • 1.2.0                                ...           2 years ago
  • 1.1.2                                ...           2 years ago
  • 1.1.1                                ...           2 years ago
  • 1.1.0                                ...           2 years ago
  • 1.0.1                                ...           2 years ago
  • 1.0.0-b                                ...           2 years ago
  • 1.0.0-a                                ...           2 years ago
  • 1.0.0                                ...           2 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 25
Dependencies (1)
Dev Dependencies (12)
Dependents (1)

Copyright 2014 - 2016 © taobao.org |