telos-client v1.0.3

telos-client

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

Table Of Contents

• Overview
• 'telos-client' vs. 'vx-client'
• Note on Promises
• Disclaimer on Active Development
• Installation
• Basic Usage
• Configuring the Client
  • Using options
  • Using methods
• Console Logging
  • Enabling Message Types
• Events
  • 'studio'
  • 'line'
  • 'book'
  • 'im' (Instant Message)
• Getting Started
  • Connecting
  • Logging In
  • Selecting a Studio
  • Shortcut
    • Flow without Shortcut
    • Shortcut Method
    • Flow with Shortcut
• Server Methods
  • cc
    • getServer
    • studioList
    • date
    • ping
    • setMode
    • login
  • studio
    • getStudio
    • showList
    • lineList
    • hybridList
    • selectStudio
    • selectShow
    • im
    • setBusyAll
    • dropHybrid
    • holdHybrid
  • studio.line
    • getLine
    • getCallerId
    • setLineComment
    • setCallerId
    • seizeLine
    • callLine
    • takeLine
    • takeNext
    • dropLine
    • lockLine
    • unlockLine
    • holdLine
    • raiseLine

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

• Most configuration details can be initialized when creating the client. These configuration settings can also easily be overwritten with applicable configuration methods

Via Options

new TelosClient(options);

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.

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>

• Before calling connect you must set the host address either in the configuration options or by the method setHost

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>

• If a username is not passed, it will default to 'user'
• If a password is not passed, it will default to the empty string ''
• The client instance will keep track of whether or not you are logged in for you

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>

• The studio Id must be greater than 0
• The client instance will keep track of whether or not you are in a studio for you.

Example

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

Shortcut

Flow without shortcut

• Because almost every method requires you to be connected, authenticated, and have a studio selected, you will often see this repetitive flow of events.

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

Shortcut Method

• Since this flow is so common, a built-in method has been included to simplify it

client.connectLoginSelect() : Promise\<boolean>

• This method performs all three actions for you

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

• Each section below outlines the getter and action methods for the respective "object" and "subobject" combinations According to the Livewire Control Protocol Spec pertaining to the VX Prime system

cc -- general server methods

GET: getServer

--Purpose

• Get the current state of attributes related to the server

--Definition

getServer() : Promise<Object>

--Usage

var Data = await client.getServer();

--Output "Data"

GET: studioList

--Purpose

• Get a read-only list of available studios.

--Definition

studioList() : Promise<Object>

--Usage

var Data = await client.studioList();

--Output "Data"

--studioList Array element object definition

GET: date

--Purpose

• Get a read-only string property mostly used for the VX phones to set their time because they don't have any RTC. ISO 8601 Date String Format.

--Definition

date() : Promise<Object>

--Usage

var Data = await client.date();

--Output "Data"

ACTION: ping

--Purpose

• To test if VX server is still alive.

--Definition

ping() : Promise<Boolean>

--Usage

var pong = await client.ping();
if(!pong)
    console.log("Server connection has died");

ACTION: setMode

--Purpose

• Write-only operation to tell the server of the current client's mode

--Definition

setMode(mode: String) : Promise

--Arguments

--Usage

//This method does not produce a response
await client.setMode();

ACTION: login

• Refer to the Logging In section in Getting Started

studio -- Studio Methods

GET: getStudio

--Purpose

• Get the state of attributes related to the currently selected studio

--Definition

getStudio() : Promise<Object>

--Usage

var Data = await client.getStudio()

--Output "Data"

GET: showList

--Purpose

• Get the list of shows in the currently selected studio

--Definition

showList() : Promise<Object>

--Usage

var Data = await client.showList();

--Output "Data"

--studioList Array element object definition

GET: lineList

--Purpose

• Get the list of lines and their attributes in the currently selected studio

--Definition

lineList() : Promise<Object>

--Usage

var Data = await client.lineList();

--Output "Data"

--lineList Array element object definition

GET: hybridList

--Purpose

• Get the list of hybrid lines in the currently selected studio

--Definition

hybridList() : Promise<Object>

--Usage

var Data = await client.hybridList();

--Output "Data"

ACTION: selectStudio

--Purpose

• Selected a studio on the server

--Definition

selectStudio(studioId: Number) : Promise<Boolean>

--Arguments

--Usage

var selected = await client.selectStudio(1);
if(!selected)
    console.log("Failed to select a studio");

ACTION: selectShow

--Purpose

• Select a show within the currently selected studio

--Definition

selectShow(showId: Number) : Promise<Boolean>

--Arguments

--Usage

var selected = await client.selectShow(1);
if(!selected)
    console.log("Failed to select a show");

ACTION: im

--Purpose

• Send an instant message to all other clients within the currently selected studio

--Definition

im(from: String, message: String) : Promise

--Arguments

--Usage

await client.im("Me", "Hello World");

ACTION: setBusyAll

--Purpose

• Set the state of all lines in the studio to busy or not busy

--Definition

setBusyAll(state: Boolean) : Promise

--Arguments

--Usage

await client.setBusyAll(false);

ACTION: dropHybrid

--Purpose

• Drop the call on a hybrid line

--Definition

dropHybrid(hybrid: Number) : Promise

--Arguments

--Usage

await client.dropHybrid(1);

ACTION: holdHybrid

--Purpose

• Hold the call on a hybrid line

--Definition

holdHybrid(hybrid: Number) : Promise

--Arguments

--Usage

await client.holdHybrid(1);

studio.line -- studio line methods

GET: getLine

--Purpose

• Get the attributes of a specific line

--Definition

getLine(lineId: Number) : Promise<Object>

--Arguments

--Usage

var Data = await client.getLine(1);

--Output "Data"

GET: getCallerId

--Purpose

• Get the caller ID value of a specific line

--Definition

getCallerId(lineId: Number) : Promise<Object>

--Arguments

--Usage

var Data = await client.getCallerId(1);

--Output "Data"

ACTION: setLineComment

--Purpose

• Set the comment string of a specific line. Can only be set when not "IDLE"

--Definition

setLineComment(lineId: Number, comment: String) : Promise

--Arguments

--Usage

await client.setLineComment(1, "Caller Name: John Smith, Topic: Programming");

ACTION: setCallerId

--Purpose

• Set the caller ID string of a specific line. Can only be set when not "IDLE"

--Definition

setCallerId(lineId: Number, callerId: String) : Promise

--Arguments

--Usage

await client.setCallerId(1, "John Smith");

ACTION: seizeLine

--Purpose

• Reserve the specified line for the current client so that nobody can call from it except the client

--Definition

seizeLine(lineId: Number) : Promise

--Arguments

--Usage

await client.seizeLine(3);

ACTION: callLine

--Purpose

• Creates all call to the specified number and puts it on a hybrid or handset

--Definition

callLine(lineId: Number, number: String [, additionalConfig: Object]) : Promise

--Arguments

--additionalConfig - Definition

--Usage

await client.callLine(1,'18001231234');

ACTION: takeLine

--Purpose

• Takes the call on the specified line to the air on.

--Definition

takeLine(lineId: Number [, additionalConfig: Object]) : Promise

--Arguments

--additionalConfig - Definition

--Usage

await client.takeLine();

ACTION: takeNext

--Purpose

• Takes the call on the air specified by the next or producerNext studio attribute depending on the client mode (TALENT or PRODUCER)

--Definition

takeNext() : Promise

--Usage

await client.takeNext();

ACTION: dropLine

--Purpose

• Drops the call on the line specified.

--Definition

dropLine(lineId: Number) : Promise

--Arguments

--Usage

await client.dropLine(2);

ACTION: lockLine

--Purpose

• Locks the call on the line specified if the call is "ON_AIR"

--Definition

lockLine(lineId: Number) : Promise

--Arguments

--Usage

await client.lockLine(4);

ACTION: unlockLine

--Purpose

• Unlocks the call on the line specified if the call is "ON_AIR_LOCKED"

--Definition

unlockLine(lineId: Number) : Promise

--Arguments

--Usage

await client.unlockLine(4);

ACTION: holdLine

--Purpose

• Holds a call in either the "ON_HOLD" OR "ON_HOLD_READ" state

--Definition

holdLine(lineId: Number, ready: Boolean) : Promise

--Arguments

--Usage

await client.holdLine(2, false);

ACTION: raiseLine

--Purpose

• Raises the priority of the selected line in the next queue.

--Definition

raiseLine(lineId: Number) : Promise

--Arguments

--Usage

await client.raiseLine(2);