@telegenta/webclient 3.1.2 → 3.2.1

package/README.md

@@ -4,7 +4,10 @@ A browser client library for using Telegenta phone services
 
 # Detailed documentation
 
-Please go to: https://www.telegenta.com/docs/index.html
+Please go to: https://www.telegenta.com/docs/webclient/latest/index.html
+
+Documentation for a specific version is at `https://www.telegenta.com/docs/webclient/<version>/index.html`,
+e.g. https://www.telegenta.com/docs/webclient/3.2.0/index.html
 
 ## Why this library?
 
@@ -142,6 +145,33 @@ If you are migrating from 1.7.x release into 2.x, some code breaking changes nee
 
 This library uses the JsSIP library (www.jssip.net) created by José Luis Milàn, Iñaki Baz Castillo and Saúl Ibarra Corretgé
 
+## Changelog
+
+3.2.0
+- Phone.setCallToken(token): replace the call token without restarting (tokens expire after 30 min).
+  With useCallDataInfoEvent, the callDataInfo subscription keeps the token from start(); call
+  start() again to move it to the new token.
+- Phone.prepareMedia({ deviceId }) and Phone.setInputDevice(deviceId): microphone selection
+- Phone.prepareMedia() without a deviceId resets a microphone previously chosen with setInputDevice()
+- Phone.setOutputDevice(deviceId) and Phone.outputDeviceSelectionSupported: speaker selection
+- prepareMedia() releases the microphone after the permission probe
+- Phone.resumeAudio(): resumes the signal-tone AudioContext; call it from a user-gesture handler,
+  since a phone started on page load gets a "suspended" context and plays no tones. Tones also
+  try to resume it themselves. One AudioContext per Phone is now reused across start()/stop()
+  (previously every start() created a new one that was never closed)
+- prepareMedia() now rejects instead of throwing synchronously, and a failed request no longer
+  changes the selected microphone or media-permission state unless the browser actually denied
+  permission (NotAllowedError/SecurityError)
+- start() no longer mutates the shared default options between Phone instances
+- stop() now always marks the phone stopped
+- Phone.register(): re-sends REGISTER without restarting the phone or dropping active calls
+  (throws NotReady if not started) - for recovering a REGISTER refresh that failed for a reason
+  other than bad credentials, which JsSIP does not retry on its own
+- connectionStateChange now carries `cause` and `statusCode` alongside `state` when
+  state is REGISTRATION_FAILED (from JsSIP's registrationFailed event), so callers can tell a
+  transient network failure (JsSIP retries on its own) apart from an authentication/authorization
+  failure (401/403) that needs a fresh call session
+
 #### License
 
 This software is provided for free together with our service

package/dist/telegenta.js

@@ -1643,6 +1643,9 @@ class Phone extends EventEmitter {
         this._eventClient = null;
         this._options = null;
 
+        // getUserMedia audio constraint: true (default device) or { deviceId: { exact } }
+        this._audioConstraints = true;
+
         // List of active sessions
         this._sessionCounter = 0;
         this._activeSessions = {};
@@ -1658,6 +1661,7 @@ class Phone extends EventEmitter {
         this._repeatToneActive = false;
         this._repeatToneSequence = [];
         this._repeatToneSequencePos = 0;
+        this._toneContext = null;
         this._toneGainProcessor = null;
         this._oscillator1 = null;
         this._oscillator2 = null;
@@ -1677,29 +1681,83 @@ class Phone extends EventEmitter {
      * Prepare media and get media permission from browser
      * This must be done prior to using the phone or getting device lists.
      *
-     * @return A promise which will be resolved when user accepts access to media devices
+     * On failure the previously selected input device (see {@link setInputDevice}) and the
+     * current media-permission state are left untouched, unless the browser reports the
+     * request was actually denied (NotAllowedError / SecurityError), in which case
+     * hasMediaPermission/hasMediaPermissionError are updated to reflect that.
      *
-     */
-    prepareMedia() {
+     * @param {object} [mediaOptions]
+     * @param {string} [mediaOptions.deviceId] Microphone deviceId (from enumerateDevices); omit or leave
+     *   out to select the browser default device, which also resets a device previously chosen with
+     *   {@link setInputDevice}
+     * @return {Promise} Resolved when user accepts access to media devices; rejected (never thrown
+     *   synchronously) otherwise, e.g. when the browser denies permission or has no mediaDevices API
+     */
+    async prepareMedia(mediaOptions = {}) {
         this.log.info('Get media permission');
-        const self = this;
-        const constraints = { audio: true, video: false };
-        return new Promise(function (resolve, reject) {
-            navigator.mediaDevices.getUserMedia(constraints).then(
-                () => {
-                    self._mediaPermission = true;
-                    self._mediaPermissionError = false;
-                    self.log.info('Media permission granted');
-                    resolve();
-                },
-                (err) => {
-                    self._mediaPermission = false;
-                    self._mediaPermissionError = true;
-                    self.log.error('Denied media permission: ' + err);
-                    reject(err);
-                },
-            );
-        });
+        const deviceId = (mediaOptions || {}).deviceId || null;
+        const audioConstraints = deviceId ? { deviceId: { exact: deviceId } } : true;
+        const constraints = { audio: audioConstraints, video: false };
+
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia(constraints);
+            // Only the permission is needed here; release the device again.
+            stream.getTracks().forEach((track) => track.stop());
+            this.setInputDevice(deviceId);
+            this._mediaPermission = true;
+            this._mediaPermissionError = false;
+            this.log.info('Media permission granted');
+        } catch (err) {
+            if (err && (err.name === 'NotAllowedError' || err.name === 'SecurityError')) {
+                this._mediaPermission = false;
+                this._mediaPermissionError = true;
+                this.log.error('Denied media permission: ' + err);
+            } else {
+                this.log.error('Unable to get requested media device: ' + err);
+            }
+            throw err;
+        }
+    }
+
+    /**
+     * Select the microphone used for subsequent calls and answers.
+     * @param {string|null} deviceId Microphone deviceId, or null for the browser default
+     */
+    setInputDevice(deviceId) {
+        this._audioConstraints = deviceId ? { deviceId: { exact: deviceId } } : true;
+    }
+
+    /**
+     * Current getUserMedia audio constraint (true = default device)
+     */
+    get audioConstraints() {
+        return this._audioConstraints;
+    }
+
+    /**
+     * True when the browser can route audio to a chosen output device (HTMLMediaElement.setSinkId)
+     */
+    get outputDeviceSelectionSupported() {
+        return typeof this._remoteAudioElement.setSinkId === 'function';
+    }
+
+    /**
+     * Route call audio and signal tones to an output device.
+     * @param {string|null} deviceId Output deviceId (from enumerateDevices), or null for the default
+     * @return {Promise<boolean>} false when the browser does not support output selection
+     * @throws Rejects if the browser's HTMLMediaElement.setSinkId() call rejects, e.g. for an
+     *   unknown deviceId or one the browser is not allowed to use (NotAllowedError)
+     */
+    async setOutputDevice(deviceId) {
+        if (!this.outputDeviceSelectionSupported) {
+            return false;
+        }
+        const sinkId = deviceId || '';
+        await Promise.all([
+            this._remoteAudioElement.setSinkId(sinkId),
+            this._toneAudioElement.setSinkId(sinkId),
+        ]);
+        return true;
     }
 
     /**
@@ -1735,7 +1793,7 @@ class Phone extends EventEmitter {
         }
 
         // Apply options
-        this._options = Object.assign(options, phoneOptions);
+        this._options = Object.assign({}, options, phoneOptions);
 
         this._initToneGenerator();
 
@@ -1898,8 +1956,11 @@ class Phone extends EventEmitter {
             self._setConnectionState('UNREGISTERED');
         });
 
-        this._UA.on('registrationFailed', function (/* data */) {
-            self._setConnectionState('REGISTRATION_FAILED');
+        this._UA.on('registrationFailed', function (data) {
+            self._setConnectionState('REGISTRATION_FAILED', {
+                cause: data?.cause,
+                statusCode: data?.response?.status_code,
+            });
         });
 
         this._UA.start();
@@ -1924,6 +1985,11 @@ class Phone extends EventEmitter {
         this._UA.stop();
         delete this._UA;
 
+        // Always mark the phone stopped from here on, even if there is no event client to
+        // disconnect below - otherwise isStarted stays true and a later start() would try to
+        // stop() this same (already torn down) instance again.
+        this._isStarted = false;
+
         // Disconnect event client if needed
         if (!this._eventClient) {
             this.log.debug('Event client not running, not stopping');
@@ -1935,11 +2001,23 @@ class Phone extends EventEmitter {
         } catch {
             this.log.warning('Unable to disconnect event client');
         }
-
-        this._isStarted = false;
         this.log.info('Phone client successfully stopped');
     }
 
+    /**
+     * Re-send REGISTER without tearing down the websocket connection or any active calls.
+     * Use this to recover from a REGISTER refresh that failed for a reason other than bad
+     * credentials (e.g. a timeout or a 5xx from the registrar) while the transport itself stayed
+     * up - JsSIP does not retry those on its own. Safe to call during an active call.
+     * @throws NotReady - If phone is not started
+     */
+    register() {
+        if (!this._isStarted) {
+            throw new NotReady('Phone is not started');
+        }
+        this._UA.register();
+    }
+
     /**
      * Start a new call
      * If you have other active calls they will be set on hold
@@ -2041,6 +2119,27 @@ class Phone extends EventEmitter {
         return this._options;
     }
 
+    /**
+     * Replace the call token used by subsequent calls and answers.
+     * Call tokens expire (30 min); renew via the API and pass the new token here.
+     *
+     * With useCallDataInfoEvent, the callDataInfo subscription keeps the token from start();
+     * call start() again to move it to the new token.
+     *
+     * @param {string} token New call token
+     * @throws NotReady - If phone is not started
+     * @throws InvalidOptions - If token is empty
+     */
+    setCallToken(token) {
+        if (!this._isStarted) {
+            throw new NotReady('Phone is not started');
+        }
+        if (!token) {
+            throw new InvalidOptions('callToken', 'Missing call token');
+        }
+        this._options.callToken = token;
+    }
+
     /**
      * Return list of current sessions
      * @returns [Session]
@@ -2106,6 +2205,7 @@ class Phone extends EventEmitter {
      */
     playTone(duration, freq1, freq2 = 0, callback = null) {
         this.log.debug(`Playing tone ${freq1} / ${freq2} for ${duration} ms`);
+        this._resumeToneContext();
 
         this._oscillator1.frequency.value = freq1;
         this._oscillator2.frequency.value = freq2;
@@ -2172,8 +2272,35 @@ class Phone extends EventEmitter {
         }
     }
 
-    // Initialize tone generator
+    /**
+     * Resume the Web Audio context behind signal tones (ringing, ringback, busy, DTMF feedback).
+     * Browsers create an AudioContext "suspended" when it is not created during a user gesture
+     * (e.g. a phone started on page load); call this from a user-gesture handler (click, keydown)
+     * so tones are audible. Safe to call before {@link start} and any number of times.
+     * @return {Promise<boolean>} false when the browser has no Web Audio API or resuming failed
+     */
+    async resumeAudio() {
+        try {
+            this._initToneGenerator();
+        } catch {
+            return false;
+        }
+        try {
+            await this._toneContext.resume();
+            return this._toneContext.state === 'running';
+        } catch (err) {
+            this.log.warning('Unable to resume audio context: ' + err);
+            return false;
+        }
+    }
+
+    // Initialize tone generator. One AudioContext per Phone, reused across start()/stop() -
+    // browsers cap the number of live contexts and a new one per start() would leak.
     _initToneGenerator() {
+        if (this._toneContext && this._toneContext.state !== 'closed') {
+            return;
+        }
+
         // Create audio context
         const AudioContext = window.AudioContext || window.webkitAudioContext || false;
         if (!AudioContext) {
@@ -2181,6 +2308,7 @@ class Phone extends EventEmitter {
         }
 
         const ctx = new AudioContext();
+        this._toneContext = ctx;
         this._toneStreamNode = ctx.createMediaStreamDestination();
         this._toneAudioElement.srcObject = this._toneStreamNode.stream;
 
@@ -2200,6 +2328,14 @@ class Phone extends EventEmitter {
         this._oscillator2.start();
     }
 
+    // Best effort: a context created outside a user gesture is suspended until resumed.
+    _resumeToneContext() {
+        const ctx = this._toneContext;
+        if (ctx && ctx.state === 'suspended' && typeof ctx.resume === 'function') {
+            ctx.resume().catch((err) => this.log.debug('Audio context resume refused: ' + err));
+        }
+    }
+
     /**
      * Hold all active calls
      * @throws NotAllowed If there are connection calls
@@ -2312,17 +2448,23 @@ class Phone extends EventEmitter {
      * @property {string} REGISTRATION_FAILED Registration failed
      */
     // Set connection state and emit event
-    _setConnectionState(state) {
+    _setConnectionState(state, extra = {}) {
         /**
          * @event connectionStateChange
          * @type {object}
          * @param {CONNECTION_STATE} state - The current connection state
+         * @param {string} [cause] - For REGISTRATION_FAILED only: JsSIP's registrationFailed
+         *   cause, e.g. 'Connection Error', 'Request Timeout' (network/transport issues, JsSIP
+         *   will keep retrying on its own), 'Authentication Error' (401), or 'Rejected' (403 -
+         *   account disabled or credentials rejected by the registrar)
+         * @param {number} [statusCode] - For REGISTRATION_FAILED only: the SIP status code of
+         *   the failed REGISTER response, when JsSIP received one (e.g. 401, 403)
          */
 
         this.log.info('Connection state: ' + state);
         this._connectionState = state;
         try {
-            this.emit('connectionStateChange', { state: state });
+            this.emit('connectionStateChange', { state: state, ...extra });
         } catch (e) {
             this.log.error('Exception in connectionStateChange event: ' + e);
         }
@@ -2370,18 +2512,15 @@ class Phone extends EventEmitter {
          * @param {string} effectiveCidNameStr - Phone number name used as a-number for call
          * @param {boolean} callPrivacy - Call privacy used for call (number hidden)
          * @param {number} hangupCauseQ850 - Q.850 hangup cause code
-         * @param {Object[]} recordings - List of recordings done for this call
-         * @param {number} recordings[].startTime - Time recording was started
-         * @param {number} recordings[].length - Recording length in milliseconds
-         * @param {number} recordings[].size - Recording size (bytes)
-         * @param {number} recordings[].urlPlayer - URL for recording with player
-         * @param {number} recordings[].url - URL for recording without player
-         * @param {number} recordings[].retentionDate - Date recording will be automatically deleted
          */
 
         let e;
         e = camelcaseKeys(eventData);
-        e.recordings = camelcaseKeys(eventData.recordings);
+        // The call data event no longer carries recordings. Uploads are
+        // asynchronous, so the array was almost always empty by the time the CDR
+        // was processed, and the event cannot be re-fired once a recording lands
+        // because call_token is never persisted on the CDR. A dedicated
+        // "recording ready" event will replace it.
 
         // Event all duration fields are in seconds, convert to millisecs
         e.duration = e.duration * 1000;
@@ -2474,7 +2613,7 @@ class Session extends EventEmitter {
         this.destinationNumber = number;
 
         let options = {
-            mediaConstraints: { audio: true, video: false },
+            mediaConstraints: { audio: this._phone.audioConstraints, video: false },
             pcConfig: {
                 iceServers: [{ urls: ['stun:stun.l.google.com:19302'] }],
             },
@@ -2828,7 +2967,7 @@ class Session extends EventEmitter {
      */
     answer(metaInfo = null) {
         let options = {
-            mediaConstraints: { audio: true, video: false },
+            mediaConstraints: { audio: this._phone.audioConstraints, video: false },
             pcConfig: {
                 iceServers: [{ urls: ['stun:stun.l.google.com:19302'] }],
             },