@telegenta/webclient 3.0.1 → 3.1.2

package/README.md

@@ -39,63 +39,49 @@ and you are ready to go. The client has no external requirements (like jQuery an
 
 Before starting, you will need an account on telegenta.com, to create sip accounts and api tokens.
 
-#### Example 1: Simple phone with static account
+Runnable examples live in `demos/`. They load the browser bundle from `../dist/telegenta.min.js`, so
+run `npm run build` first, then serve the directory over https. WebRTC requires a secure context;
+`localhost` counts as secure, but opening a demo as `file://...` does not - media permissions are not
+remembered there, so you will be prompted for the microphone every time.
 
-In this example we will use a normal SIP User account, as it does not require you to use our API service.
+#### Example: phone with a provisioning token
 
-Log into the administration frontend (https://admin.telegenta.com) and create a "SIP User account", this will provide
-you with credentials (username and password). Once you have these open the embedded html client provided with this
-library /embedded_client/index.html and modify the credentials:
+`demos/phone_client.html` is a complete softphone - start/stop, outbound calls, transfer, listen-in,
+incoming calls and the event client.
 
-```
-// SIP account username and password
-var USERNAME='your username';
-var PASSWORD='your password';
-
-window.onload = function () {
-...
-```
-
-Now open the file (index.html) in your browser. After you have been prompted for permission to use the audio devices,
-you should have a working phone.
-Note: If you are viewing a file using "file://index.html", it is not considered a secure connection by the browser
-and media permissions are not remembered, so you will be prompted every time you open the file.
-However, once you move the file to a secure webserver (https), this will no longer be an issue.
-
-#### Example 2: Using SIP Flex accounts
+First create a static API token in the admin interface
+(https://admin.telegenta.com/integration/access-tokens). Open the demo and paste the token in; it then
 
-When using SIP flex accounts, you need to use our API service to retrieve account information first.
-This approach solves the authentication problem and provides you with short-lived sip accounts used in client sessions.
-For this example we need a backend service and we provide a simple example in PHP using the built in Webserver.
+1. requests a short-lived provisioning token with `GET /api/get-call-session/?id=<account id>`, and
+2. starts the phone with that token:
 
-First go to the admin interface and create following 2 items:
+```
+const opts = {
+    // Enable event client
+    connectEventService: true,
 
-1. SIP Flex account with "flex account identification" set to 'test'
-2. A static api token (https://admin.telegenta.com/integration/access-tokens).
+    // Subscribe to detailed information about call after processing
+    useCallDataInfoEvent: true,
 
-Now open the file /embedded_client/server.html and insert the API token at the top of the file:
+    // Enable incoming calls (you must set a phone number to call the account also)
+    register: true,
 
-```
-// Your API Token
-$api_auth_token = '<your api token>';
+    // Configure client with provision token
+    provisionToken: data.provision_token,
+};
 
-// The flex account identification (this is set when configuring your flex accounts)
-// It possible to have multiple sip flex accounts with different configurations
-$flex_identification = 'test';
-...
+phoneClient.start(opts);
 ```
 
-Once you have added the token, you can start the php Webserver (requires php v5.4+) like this:
+Issuing the provisioning token from your own backend is the recommended integration: the short-lived
+token is all that reaches the browser, and your API token stays on the server.
 
-```
-cd embedded_client
-php -S localhost:9000
-```
+The remaining demos cover narrower cases:
 
-Now open the URL http://localhost:9000/server.php and you should see the phone and be able to perform calls.
-Note: If you use any other host than localhost, you won't be able to call because the built in php webserver does not
-support secure (https) connections and this is required by the browser to use WebRTC. If needed, you can tunnel to
-localhost using your ssh client for testing.
+- `demos/event_client.html` - the event client on its own, without a phone
+- `demos/calldata_available.html` - subscribing to call data after a call completes
+- `demos/add_phone_number.html` - adding a phone number through the API
+- `demos/embedded_config.html` - embedding the admin config pages with a config token
 
 ## Approaching the integration
 
@@ -106,15 +92,10 @@ Depending on how much flexibility you need, you can choose between the following
     We believe in using standard protocols as much as possible and it will work nicely, but you need to address most
     of the issues we listed above in the previous section yourself.
 
-2.  Use our free library (lib/telegenta.min.js) and provide your own frontend
-    This way you just need to handle events and use javascript methods like call, hangup, startRecord, etc..
-
-3.  Use our complete embedded phone client with frontend.
-    We have made a simple phone with frontend, which can be easily included in your own project. Just grab the
-    index.html, style.css and embedded_phone.js and insert it into your own project.
-    We named the JS and CSS to try and avoid any potential conflicts.
-    You only need to provide it with credentials or provisioning token (as in the example above) from you backend and
-    you are set to start calling.
+2.  Use our free library and provide your own frontend.
+    Load `dist/telegenta.min.js` in the browser (global `Telegenta`) or import the package in your
+    bundler, then handle events and use javascript methods like call, hangup, startRecord, etc..
+    `demos/phone_client.html` shows the whole flow end to end.
 
 ## Migrating from 2.x
 

package/demos/calldata_available.html

@@ -45,7 +45,7 @@
         eventClient = new Telegenta.EventClient(logger);
 
         // Connect to event server
-        eventClient.connect('wss://api.telegenta.com/es/').then(function () {
+        eventClient.connect('wss://esvc.telegenta.com/').then(function () {
             console.info(`Connected to server`);
         }, function (reason) {
             console.error(`Unable to connect to event service: ${reason}`);

package/demos/event_client.html

@@ -53,7 +53,7 @@
         let eventClient;
         let subscriptionId = null;
         const API_URL = 'https://api.telegenta.com/api';
-        const EVENT_CLIENT_URL = 'wss://api.telegenta.com/es/';
+        const EVENT_CLIENT_URL = 'wss://esvc.telegenta.com/';
 
         // Start when DOM is ready
         window.onload = function () {

package/dist/telegenta.js

@@ -25,23 +25,23 @@ class LogHandler {
     }
 
     debug(...args) {
-        this._doLog(LOGLVL$1.DEBUG, args);
+        this._doLog(LOGLVL.DEBUG, args);
     }
 
     info(...args) {
-        this._doLog(LOGLVL$1.INFO, args);
+        this._doLog(LOGLVL.INFO, args);
     }
 
     warn(...args) {
-        this._doLog(LOGLVL$1.WARN, args);
+        this._doLog(LOGLVL.WARN, args);
     }
 
     warning(...args) {
-        this._doLog(LOGLVL$1.WARN, args);
+        this._doLog(LOGLVL.WARN, args);
     }
 
     error(...args) {
-        this._doLog(LOGLVL$1.ERROR, args);
+        this._doLog(LOGLVL.ERROR, args);
     }
 
     _doLog(level, args) {
@@ -60,19 +60,19 @@ class LogHandler {
             this.extHandler(LOGLVLSTR[level], args);
         } else {
             switch (level) {
-                case LOGLVL$1.DEBUG:
+                case LOGLVL.DEBUG:
                     console.debug(args);
                     break;
 
-                case LOGLVL$1.INFO:
+                case LOGLVL.INFO:
                     console.info(args);
                     break;
 
-                case LOGLVL$1.WARN:
+                case LOGLVL.WARN:
                     console.warn(args);
                     break;
 
-                case LOGLVL$1.ERROR:
+                case LOGLVL.ERROR:
                     console.error(args);
                     break;
 
@@ -91,7 +91,7 @@ class LogHandler {
  * @property {number} INFO 2 Informational messages (default)
  * @property {number} DEBUG 3 Debug messages
  */
-const LOGLVL$1 = {
+const LOGLVL = {
     DEBUG: 3,
     INFO: 2,
     WARN: 1,
@@ -168,10 +168,11 @@ class InvalidParameter extends Error {
 
 /**
  * Exception raised if trying to perform actions that require active session
+ * @property message - Error message
  */
 class NoActiveSession extends Error {
-    constructor() {
-        super();
+    constructor(message) {
+        super(message);
         this.name = 'NoActiveSession';
     }
 }
@@ -291,6 +292,43 @@ function browserIsEdge() {
     return (navigator.userAgent.indexOf("Edge") !== -1)
 }
 
+// SIP header names are RFC 3261 tokens
+const HEADER_NAME_RE = /^[A-Za-z0-9\-.!%*_+`'~]+$/;
+
+const HTML_ENTITIES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+    '\r': '&#13;',
+    '\n': '&#10;',
+};
+
+// Build custom SIP header lines from a { name: value } map.
+// Names must be tokens - a bad one is always a programming error, so it throws.
+// Values are HTML encoded rather than rejected: that strips the CR/LF which
+// would otherwise let a value inject further headers, while still letting
+// punctuation through.
+function buildCustomHeaders(setHeader) {
+    if (!setHeader) {
+        return [];
+    }
+
+    if (typeof setHeader !== 'object' || Array.isArray(setHeader)) {
+        throw new TypeError(`Invalid setHeader argument: expected an object, got ${typeof setHeader}`);
+    }
+
+    return Object.entries(setHeader).map(([name, value]) => {
+        if (!HEADER_NAME_RE.test(name)) {
+            throw new TypeError(`Invalid SIP header name: "${name}"`);
+        }
+        // Single pass, so an encoded '&' is not encoded again.
+        const encoded = String(value).replace(/[&<>"'\r\n]/g, (c) => HTML_ENTITIES[c]);
+        return `${name}: ${encoded}`;
+    });
+}
+
 // Request timeout after 10 sec
 const REQUEST_TIMEOUT = 10000;
 
@@ -348,7 +386,7 @@ class Request {
 class Requestor extends EventEmitter {
     constructor(logger = null) {
         super();
-        this.log = logger ? logger : new LogHandler(LOGLVL$1.INFO);
+        this.log = logger ? logger : new LogHandler(LOGLVL.INFO);
         this._pendingRequests = [];
     }
 
@@ -363,13 +401,13 @@ class Requestor extends EventEmitter {
         let msg;
         try {
             msg = JSON.parse(message);
-        } catch (err) {
+        } catch {
             this.log.warning("Unable to parse message: " + message);
             return;
         }
 
         // Validate msg fields
-        if (!msg.hasOwnProperty("type") || !msg.hasOwnProperty("id")) {
+        if (!Object.hasOwn(msg, "type") || !Object.hasOwn(msg, "id")) {
             this.log.warning(`Invalid message received: ${msg} - missing type or id`);
             return;
         }
@@ -522,7 +560,7 @@ class Requestor extends EventEmitter {
 // Keep alive in seconds
 const PING_INTERVAL = 50;
 
-const ES_DEFAULT_SERVER_URL = 'wss://api.telegenta.com/es/';
+const ES_DEFAULT_SERVER_URL = 'wss://esvc.telegenta.com/';
 
 // Starting retry interval
 const RETRY_INTERVAL_START = 1 + Math.random();
@@ -620,7 +658,7 @@ class EventClient {
             throw new InvalidParameter('You must specify both event spec and callback function');
         }
 
-        if (!eventSpecification.hasOwnProperty('event_name')) {
+        if (!Object.hasOwn(eventSpecification, 'event_name')) {
             throw new InvalidParameter('Your event specification must contain event name');
         }
 
@@ -1504,7 +1542,7 @@ function camelcaseKeys(input, options) {
 
 const options = {
     wssServer: 'wss://api.telegenta.com/sip/',
-    eventServer: 'wss://api.telegenta.com/es/',
+    eventServer: 'wss://esvc.telegenta.com/',
     provisionToken: null,
     authorizationUsername: null,
     password: null,
@@ -1625,10 +1663,10 @@ class Phone extends EventEmitter {
         this._oscillator2 = null;
 
         // Set default logger
-        this.log = logger ? logger : new LogHandler(LOGLVL$1.INFO);
+        this.log = logger ? logger : new LogHandler(LOGLVL.INFO);
 
         // Handle jssip debug logs
-        if (this.log.level === LOGLVL$1.DEBUG) {
+        if (this.log.level === LOGLVL.DEBUG) {
             JsSIP.debug.disable('JsSIP:*');
         } else {
             JsSIP.debug.disable('JsSIP:*');
@@ -1703,10 +1741,10 @@ class Phone extends EventEmitter {
 
         // Unpack provisioning token if specified
         if (this._options.provisionToken) {
-            let pt = null;
+            let pt;
             try {
                 pt = JSON.parse(atob(this._options.provisionToken));
-            } catch (err) {
+            } catch {
                 throw new InvalidOptions('provisionToken', 'Invalid token');
             }
 
@@ -1782,7 +1820,7 @@ class Phone extends EventEmitter {
             );
         }
 
-        let wsSocket = null;
+        let wsSocket;
         try {
             wsSocket = new JsSIP.WebSocketInterface(this._options.wssServer);
         } catch (err) {
@@ -1894,7 +1932,7 @@ class Phone extends EventEmitter {
         try {
             this._eventClient.disconnect();
             delete this._eventClient;
-        } catch (e) {
+        } catch {
             this.log.warning('Unable to disconnect event client');
         }
 
@@ -1913,9 +1951,11 @@ class Phone extends EventEmitter {
      * @param {number} [params.answerCallTimeout=0] Hangup call with NO ANSWER if call is not picked up before specified interval (seconds). If 0, timeout is disabled.
      * @param {number} [params.maximumCallCost] Maximum call cost (in customer currency) allowed for call. The call will automatically be stopped when the specified cost has been reached. Setting this to 0 disables checking for maximum cost.
      * @param {string} [params.metaInfo] Add meta info to call, which will be available in server events and inside call complete webhook (max 256 chars)
+     * @param {object} [params.setHeader] Custom SIP headers to add to the INVITE, as {name: value}.
      * @return {Session} object for call
      * @throws NotReady - If phone is not ready to call
      * @throws NotAllowed - If there are calls currently connecting
+     * @throws InvalidParameter - If setHeader contains an invalid header name or container
      *
      */
     call(number, params = {}) {
@@ -1940,6 +1980,7 @@ class Phone extends EventEmitter {
                 explicitCallerId: null,
                 explicitShortCallerId: null,
                 metaInfo: null,
+                setHeader: null,
                 _isListenCall: false,
             },
             params,
@@ -1982,7 +2023,7 @@ class Phone extends EventEmitter {
      */
     getSessionByUUID(uuid) {
         for (let key in this._activeSessions) {
-            if (this._activeSessions.hasOwnProperty(key)) {
+            if (Object.hasOwn(this._activeSessions, key)) {
                 if (this._activeSessions[key].uuid === uuid) {
                     return this._activeSessions[key];
                 }
@@ -2007,7 +2048,7 @@ class Phone extends EventEmitter {
     get sessions() {
         let s = [];
         for (let key in this._activeSessions) {
-            if (this._activeSessions.hasOwnProperty(key)) {
+            if (Object.hasOwn(this._activeSessions, key)) {
                 s.push(this._activeSessions[key]);
             }
         }
@@ -2172,7 +2213,7 @@ class Phone extends EventEmitter {
 
         // Iterate through all active calls and hold them
         for (let key in this._activeSessions) {
-            if (this._activeSessions.hasOwnProperty(key)) {
+            if (Object.hasOwn(this._activeSessions, key)) {
                 let session = this._activeSessions[key];
                 if (session.state === 'ACTIVE') {
                     session.hold();
@@ -2246,7 +2287,7 @@ class Phone extends EventEmitter {
     // Return true if there are calls currently connecting
     _checkForConnectingCalls() {
         for (let key in this._activeSessions) {
-            if (this._activeSessions.hasOwnProperty(key)) {
+            if (Object.hasOwn(this._activeSessions, key)) {
                 let session = this._activeSessions[key];
                 if (
                     session.state === 'INITIALIZING' ||
@@ -2495,6 +2536,23 @@ class Session extends EventEmitter {
             }
         }
 
+        // Custom headers last, so they cannot displace the built-in ones.
+        // Must be before _UA.call() below: jssip clones extraHeaders synchronously
+        // inside connect(), so anything pushed after that call never reaches the INVITE.
+        let customHeaders;
+        try {
+            customHeaders = buildCustomHeaders(callParams.setHeader);
+        } catch (error) {
+            if (error instanceof TypeError) {
+                throw new InvalidParameter(error.message);
+            }
+            throw error;
+        }
+        for (const header of customHeaders) {
+            this.log.debug('Adding custom header: ' + header);
+            options.extraHeaders.push(header);
+        }
+
         // Prepare invite uri
         const uri = 'sip:' + number + '@telegenta.com';
 
@@ -2613,7 +2671,7 @@ class Session extends EventEmitter {
                         self.log.info(`Answer call timeout after ${self._answerCallTimeout} seconds`);
                         try {
                             self.hangup();
-                        } catch (e) {
+                        } catch {
                             self.log.info('No active session, ignoring answer call timeout');
                         }
                     }, self._answerCallTimeout * 1000);
@@ -2867,6 +2925,30 @@ class Session extends EventEmitter {
         }
     }
 
+    /**
+     * Raw WebRTC statistics for this session's peer connection.
+     *
+     * Returns the browser's own `RTCStatsReport` untouched, so callers can read
+     * any statistic the browser exposes - RTP packet and byte counters, the
+     * DTLS/ICE transport state, codec and candidate-pair details.
+     *
+     * @returns {Promise<RTCStatsReport>} The peer connection's statistics
+     * @throws NoActiveSession - If the session has no established peer connection
+     * (thrown synchronously, before the promise is created)
+     *
+     * @example
+     * const report = await session.getRTCStats();
+     * for (const stat of report.values()) {
+     *   if (stat.type === 'inbound-rtp') console.log(stat.packetsReceived);
+     * }
+     */
+    getRTCStats() {
+        if (!this._webRTCSession || !this._webRTCSession.connection) {
+            throw new NoActiveSession('no peer connection for this session');
+        }
+        return this._webRTCSession.connection.getStats();
+    }
+
     // RECORDING
     /**
      * Start recording
@@ -3660,4 +3742,4 @@ class Session extends EventEmitter {
     }
 }
 
-export { EventClient, EventServiceNotConnected, InvalidMediaDevice, InvalidOptions, InvalidParameter, LOGLVL$1 as LOGLVL, LogHandler, MediaNotPrepared, NoActiveSession, NotAllowed, NotReady, Phone, Request, Requestor, Session, UnableToConnect, browserIsChrome, browserIsEdge, browserIsFirefox, browserIsOpera, browserIsSafari, compareObjects, createDurationString, createUUID };
+export { EventClient, EventServiceNotConnected, InvalidMediaDevice, InvalidOptions, InvalidParameter, LOGLVL, LogHandler, MediaNotPrepared, NoActiveSession, NotAllowed, NotReady, Phone, Request, Requestor, Session, UnableToConnect, browserIsChrome, browserIsEdge, browserIsFirefox, browserIsOpera, browserIsSafari, buildCustomHeaders, compareObjects, createDurationString, createUUID };