search

pwbrown / telos-client

An interactive TCP client abstraction for the Telos VX Prime phone server.
GNU General Public License v3.0
4 stars 0 forks source link

readme

CircleCI

telos-client

An interactive TCP client abstraction for the Telos VX Prime phone server.

Table Of Contents

Overview

Telos Client is Node.js implementation of the interactive TCP protocol used by "Telos VX Prime" VoIP (Voice over IP) phone systems. The Livewire Control Protocol "LWCP" used by the VX-Prime server is designed to allow direct interaction with the system to monitor the state of the studio and its phone lines, and perform actions on the system. Telos client is a simple, clean API for managing a connection with the VX-Prime server, listening for studio changes, and performing actions within the studio.

Telos Client vs. VX Client

Telos Client can be considered as version 1.0.0 of the package "vx-client" as it performs the same functionality. The reason that telos client is a seperate package is because it does not offer legacy syntax support for systems already using vx-client. Telos Client has a nearly identical set of methods, but the logging system is brand new and the entire library is strictly Promise based to adopt a more modern feel whereas vx-client is strictly callback based.

Note on Promises

The decision to adopt a Promise based system for Telos Client was made to result in a cleaner implementation when incoporated into an application.

PLEASE READ THIS: Every implementation of Promises in this library will NEVER "reject", but instead will resolve a "null" value in the case of an error. This was decided to reduce the subjectively unappealing usage of try/catch statements in application code to catch errors. Instead, if the Promise resolves a null value, you can use the built in logging system to print out errors, warnings, stack traces, and I/O messages from the server in order to debug unexpected behavior.

Disclaimer

This library is in active developement and will be tested over time. The syntax of this library will not change dramatically over the period of testing, but the functionality may change. Use at your own risk.

Installation

Yarn

$ yarn add telos-client

NPM

$ npm install --save telos-client

Basic Usage

const TelosClient = require('telos-client');
const client = new TelosClient();

client.setHost('10.1.1.1');

client.connect().then(async function(success){
    if(success)
        var server = await client.getServer();
})

Configuring the Client

Via Options

new TelosClient([options]);

Property Description Type Required Default
log Specify the types of log messages to display. Formatted as a colon separated string (ex. "err:warn:input"). String NO
host Specify the host address to connect to String NO
port Specify the port to connect on Number NO 20518
studioId Specify the default studio id to connect to Number NO 1
username Specify the username for logging in to the server String NO 'user'
password Specify the password for logging in to the server String NO ''

Via Methods

Set Host Address

client.setHost(host: String)

Set Port Number

client.setPort(port: Number)

Set Studio ID

client.setStudioId(studioId: Number)

Set Username

client.setUsername(username: String)

Set Password

client.setPassword(password: String)

Console Logging

Telos Client includes a logging system to optimize application building and debugging. There are various different message types that are used throughout the system and can be toggled with the "log" option when configuring the client.

Message Type Color Description Aliases
error red Error messages are displayed whenever a fatal error occurs as a result of using the library incorrectly or passing an invalid message. Errors will not terminate the application so it is important to enable this option whenever developing to ensure that all errors are noticed. error, errors, err
warning orange Warning messages are displayed whenever an error occurs that does not affect the performance of the client and are typically mitigated through the use of default values. warning, warnings, warn
trace magenta Trace messages are displayed in tandem with error messages if the end-user needs to see the stack trace leading to the error. They will only display if the error type is also enabled. trace, stack, stack trace, stacktrace
input green Input messages are displayed whenever TCP message is received by the client. Input messages are not parsed other than ignoring trailing or leading whitespace. input, in, request, req
output green Output messages are displayed whenever a TCP message is sent by the client. Output messages are the actual representation of what is sent. output, out, response, res

Enabling console message types

const TelosClient = require('telos-client');
const client = new TelosClient({

    // Enable message types by passing a ":" seperated string of any combination of message type aliases
    log: "err:in:out"
})

Events

The Telos VX system takes input from many different sources and thus changes frequently while being used. For many methods that retrieve data, they are tracked and resolved internally as part of the Promise resolution flow. For any other event triggered by the system, you will need to listen and track them using the events detailed below.

'studio'

Studio events are fired whenever a change within the studio has been made. Primarily these are called in response to changes of attributes within the studio such as setting the studio to the "busy all" state.

client.on('studio', (data) => {
    // Analyze studio changes here
})

'line'

Line events are fired whenever a change is made to a studio line. These can occur from a change requested by the end-user or naturally by the making and receive of calls on the line. This should be the application's primary way of reacting to changes within the system and staying up to date. NOTE: The "callerId" attribute may not be sent with the line event or the studio even. Be sure to manually request callerId fields if they are not returned and desired.

client.on('line', (data) => {
    // Analyze line changes here

    // Line events will always include the additional "line" property
    //   This indicates the number of the line that has triggered the event
    console.log(`Line Number: ${data.line}`);
})

'book'

The book system is not thoroughly documented here as it has been untested. But if you decide to test the methods related to "studio.book", you can listen to the changes here.

client.on('book', (data) => {
    // Analyze book changes here
})

'im'

Instant messages can be tracked within the selected studio using the 'im' event. Refer to the im method for more details on sending messages. Keep in mind that you will only receive instant messages that have been sent within the studio that has been selected.

client.on('im', (data) => {
    console.log(`A message has been sent from "${data.from}": ${data.message}`)
})

Getting Started

NOTE: The next three "sub-sections" describe the manual way to connect to the server, login, and select a studio, while the forth section provides a nice shortcut to condense it all.

Connecting

client.connect() : Promise\<boolean>

Example

...
client.setHost('your.vxserver.net');

client.connect().then(function(success){
    console.log(success? "Connected" : "Failed to connect");
})

Logging In

NOTE: Logging in is a prerequisite for ALL methods except [getServer]().

client.login([username: String [, password: String]]) : Promise\<boolean>

Example

/** assume we are inside an async function **/
var loggedIn = await client.login('myusername', 'somepassword');
console.log(loggedIn? "Logged in" : "Failed to log in");

Selecting A Studio

NOTE: Selecting a studio is a prerequisite for ALL methods except [studioList](), [date](), [getServer](), [setMode](), and [ping]().

client.selectStudio(studioId: Number) : Promise\<boolean>

Example

...
var studioSelected = await client.selectStudio(1);
console.log(studioSelected? "Studio selected": "Studio NOT selected");

Shortcut

Flow without shortcut

Shortcut Method

client.connectLoginSelect() : Promise\<boolean>

Example

...
var initialized = await client.connectLoginSelect();
console.log(initialized? "Ready to go" : "Something went wrong");

Flow with shortcut

+---------------------------+
|client.connectLoginSelect()+<------+
+------------+--------------+       |
             |                      |
             |                      |
             v                      |
     +-------+--------+             |
     |Still Connected?+-----NO------+
     +----+-----------+
          |     ^
         YES    |
          |     |
          |     |
          v     |
+--------------------------------------+
|client.*() //Execute some other method|
+--------------------------------------+

Server Methods

cc -- general server methods

GET: getServer

--Purpose