@webex/plugin-meetings 1.147.1 → 1.148.0

package/src/constants.js

@@ -1220,6 +1220,7 @@ export const METRICS_OPERATIONAL_MEASURES = {
   SET_MEETING_QUALITY_FAILURE: 'js_sdk_set_meeting_quality_failures',
   STOP_FLOOR_REQUEST_FAILURE: 'js_sdk_stop_floor_request_failures',
   ADD_DIAL_IN_FAILURE: 'js_sdk_add_dial_in_failure',
+  ADD_DIAL_OUT_FAILURE: 'js_sdk_add_dial_out_failure',
   UPDATE_MEDIA_FAILURE: 'js_sdk_update_media_failures',
   UNMUTE_AUDIO_FAILURE: 'js_sdk_unmute_audio_failures',
   UNMUTE_VIDEO_FAILURE: 'js_sdk_unmute_video_failures',
@@ -1232,3 +1233,12 @@ export const METRICS_OPERATIONAL_MEASURES = {
   UPLOAD_LOGS_FAILURE: 'js_sdk_upload_logs_failure',
   RECEIVE_TRANSCRIPTION_FAILURE: 'js_sdk_receive_transcription_failure'
 };
+
+export const PSTN_STATUS = {
+  JOINED: 'JOINED', // we have provisioned a pstn device, which can be used to connect
+  CONNECTED: 'CONNECTED', // user is connected to audio with pstn device
+  LEFT: 'LEFT', // user has disconnected from the pstn device
+  TRANSFERRING: 'TRANSFERRING', // usually happens in dial-out after the CONNECTED state
+  SUCCESS: 'SUCCESS', // happens after the transfer (TRANSFERRING) is successful
+  UNKNOWN: '' // placeholder if we haven't been told what the status is
+};

package/src/meeting/index.js

@@ -57,6 +57,7 @@ import {
   ONLINE,
   OFFLINE,
   PC_BAIL_TIMEOUT,
+  PSTN_STATUS,
   QUALITY_LEVELS,
   RECORDING_STATE,
   ROAP_SEQ_PRE,
@@ -710,13 +711,14 @@ export default class Meeting extends StatelessWebexPlugin {
      */
     this.floorGrantPending = false;
     /**
-     * The latest status of the dial in device (can be "JOINED", "CONNECTED", "LEFT" or "")
+     * The latest status of the dial in device (can be "JOINED", "CONNECTED", "LEFT",
+     * "TRANSFERRING", "SUCCESS" or "")
      * @instance
      * @type {String}
      * @private
      * @memberof Meeting
      */
-    this.dialInDeviceStatus = '';
+    this.dialInDeviceStatus = PSTN_STATUS.UNKNOWN;
     /**
      * the url for provisioned device used to dial in
      * @instance
@@ -725,6 +727,23 @@ export default class Meeting extends StatelessWebexPlugin {
      * @memberof Meeting
      */
     this.dialInUrl = '';
+    /**
+     * The latest status of the dial out device (can be "JOINED", "CONNECTED", "LEFT",
+     * "TRANSFERRING", "SUCCESS" or "")
+     * @instance
+     * @type {String}
+     * @private
+     * @memberof Meeting
+     */
+    this.dialOutDeviceStatus = PSTN_STATUS.UNKNOWN;
+    /**
+     * the url for provisioned device used to dial out
+     * @instance
+     * @type {String}
+     * @private
+     * @memberof Meeting
+     */
+    this.dialOutUrl = '';
     /**
      * @instance
      * @type {MediaMetrics}
@@ -1144,9 +1163,28 @@ export default class Meeting extends StatelessWebexPlugin {
   pstnUpdate(payload) {
     if (this.locusInfo.self) {
       const dialInPstnDevice = payload.newSelf?.pstnDevices.find((device) => device.url === this.dialInUrl);
+      const dialOutPstnDevice = payload.newSelf?.pstnDevices.find((device) => device.url === this.dialOutUrl);
+      let changed = false;
 
       if (dialInPstnDevice) {
-        this.dialInDeviceStatus = dialInPstnDevice.dialingStatus ?? dialInPstnDevice.state;
+        const newStatus = dialInPstnDevice.dialingStatus ?? dialInPstnDevice.state;
+
+        if (newStatus !== this.dialInDeviceStatus) {
+          this.dialInDeviceStatus = newStatus;
+          changed = true;
+        }
+      }
+
+      if (dialOutPstnDevice) {
+        const newStatus = dialOutPstnDevice.dialingStatus ?? dialOutPstnDevice.state;
+
+        if (newStatus !== this.dialOutDeviceStatus) {
+          this.dialOutDeviceStatus = newStatus;
+          changed = true;
+        }
+      }
+
+      if (changed) {
         Trigger.trigger(
           this,
           {
@@ -1157,7 +1195,11 @@ export default class Meeting extends StatelessWebexPlugin {
           {
             dialIn: {
               status: this.dialInDeviceStatus,
-              attendeeId: dialInPstnDevice.attendeeId
+              attendeeId: dialInPstnDevice?.attendeeId
+            },
+            dialOut: {
+              status: this.dialOutDeviceStatus,
+              attendeeId: dialOutPstnDevice?.attendeeId
             }
           }
         );
@@ -3313,7 +3355,7 @@ export default class Meeting extends StatelessWebexPlugin {
   /**
    * Use phone for meeting audio
    * @param {String} phoneNumber If provided, it will dial-out using this number. If not provided, dial-in will be used
-   * @returns {Promise} Resolves once the dial-in or dial-out request has completed
+   * @returns {Promise} Resolves once the dial-in or dial-out request has completed, or rejects if it failed
    * @public
    * @memberof Meeting
    */
@@ -3322,17 +3364,28 @@ export default class Meeting extends StatelessWebexPlugin {
       return this.dialInPstn();
     }
 
-    return Promise.reject(new Error('Dial-out is not supported yet'));
+    return this.dialOutPstn(phoneNumber);
+  }
+
+  /**
+   * Determines if the given pstnStatus is in a state which implies the phone is provisioned
+   * @param {String} pstnStatus
+   * @returns {Boolean}
+   * @private
+   * @memberof Meeting
+   */
+  isPhoneProvisioned(pstnStatus) {
+    return [PSTN_STATUS.JOINED, PSTN_STATUS.CONNECTED, PSTN_STATUS.SUCCESS].includes(pstnStatus);
   }
 
   /**
    * Enable dial-in for audio
-   * @returns {Promise} Resolves once the dial-in request has completed
+   * @returns {Promise} Resolves once the dial-in request has completed, or rejects if it failed
    * @private
    * @memberof Meeting
    */
   dialInPstn() {
-    if (this.dialInDeviceStatus === 'CONNECTED' || this.dialInDeviceStatus === 'JOINED') return Promise.resolve(); // prevent multiple dial in devices from being provisioned
+    if (this.isPhoneProvisioned(this.dialInDeviceStatus)) return Promise.resolve(); // prevent multiple dial in devices from being provisioned
 
     const {correlationId, locusUrl} = this;
 
@@ -3357,6 +3410,47 @@ export default class Meeting extends StatelessWebexPlugin {
           stack: error.stack
         }
       );
+
+      return Promise.reject(error);
+    });
+  }
+
+  /**
+   * Enable dial-out for audio
+   * @param {String} phoneNumber Phone number to dial out to
+   * @returns {Promise} Resolves once the dial-out request has completed (it doesn't wait for the user to answer the phone), or rejects if it failed
+   * @private
+   * @memberof Meeting
+   */
+  dialOutPstn(phoneNumber) {
+    if (this.isPhoneProvisioned(this.dialOutDeviceStatus)) return Promise.resolve(); // prevent multiple dial out devices from being provisioned
+
+    const {correlationId, locusUrl} = this;
+
+    if (!this.dialOutUrl) this.dialOutUrl = `dialout:///${uuid.v4()}`;
+
+    return this.meetingRequest.dialOut({
+      correlationId,
+      dialOutUrl: this.dialOutUrl,
+      phoneNumber,
+      locusUrl,
+      clientUrl: this.deviceUrl
+    }).then((res) => {
+      this.locusInfo.onFullLocus(res.body.locus);
+    }).catch((error) => {
+      Metrics.sendOperationalMetric(
+        METRICS_OPERATIONAL_MEASURES.ADD_DIAL_OUT_FAILURE,
+        {
+          correlation_id: this.correlationId,
+          dial_out_url: this.dialOutUrl,
+          locus_id: locusUrl.split('/').pop(),
+          client_url: this.deviceUrl,
+          reason: error.error?.message,
+          stack: error.stack
+        }
+      );
+
+      return Promise.reject(error);
     });
   }
 
@@ -3368,13 +3462,14 @@ export default class Meeting extends StatelessWebexPlugin {
    * @returns {Promise}
    */
   disconnectPhoneAudio() {
-    if (this.dialInDeviceStatus === 'CONNECTED') {
-      return MeetingUtil.leavePstn(this, this.dialInUrl);
-    }
-
-    // TODO: handle dial out
-
-    return Promise.resolve();
+    return Promise.all([
+      this.isPhoneProvisioned(this.dialInDeviceStatus) ?
+        MeetingUtil.disconnectPhoneAudio(this, this.dialInUrl) :
+        Promise.resolve(),
+      this.isPhoneProvisioned(this.dialOutDeviceStatus) ?
+        MeetingUtil.disconnectPhoneAudio(this, this.dialOutUrl) :
+        Promise.resolve()
+    ]);
   }
 
   /**

package/src/meeting/request.js

@@ -20,6 +20,7 @@ import {
   MEDIA,
   PARTICIPANT,
   PROVISIONAL_TYPE_DIAL_IN,
+  PROVISIONAL_TYPE_DIAL_OUT,
   SEND_DTMF_ENDPOINT,
   _SLIDES_
 } from '../constants';
@@ -182,6 +183,48 @@ export default class MeetingRequest extends StatelessWebexPlugin {
     });
   }
 
+  /**
+   * Make a network request to add a dial out device
+   * @param {Object} options
+   * @param {String} options.correlationId
+   * @param {String} options.localUrl url for the meeting
+   * @param {String} options.dialOutUrl identifier for the to-be provisioned device
+   * @param {String} options.phoneNumber phone number to dial out to
+   * @param {String} options.clientUrl identifier for the web device
+   * @returns {Promise}
+   * @private
+   */
+  dialOut({
+    locusUrl, dialOutUrl, phoneNumber, clientUrl, correlationId
+  }) {
+    LoggerProxy.logger.info(
+      'Meeting:request#dialOut --> Provisioning a dial out device',
+      correlationId
+    );
+    const uri = `${locusUrl}/${PARTICIPANT}`;
+
+    const body = {
+      device: {
+        deviceType: deviceType.PROVISIONAL,
+        provisionalType: PROVISIONAL_TYPE_DIAL_OUT,
+        url: dialOutUrl,
+        dialoutAddress: phoneNumber,
+        clientUrl
+      },
+      correlationId
+    };
+
+    return this.request({
+      method: HTTP_VERBS.POST,
+      uri,
+      body
+    }).catch((err) => {
+      LoggerProxy.logger.error(`Meeting:request#dialOut --> Error provisioning a dial out device, error ${err}`);
+
+      throw err;
+    });
+  }
+
   /**
    * Syns the missed delta event
    * @param {Object} options
@@ -241,21 +284,20 @@ export default class MeetingRequest extends StatelessWebexPlugin {
   }
 
   /**
-   * Make a network request to make a provisioned pstn device leave the meeting
+   * Make a network request to make a provisioned phone leave the meeting
    * @param {Object} options
    * @param {String} options.locusUrl
-   * @param {String} options.selfId
-   * @param {String} options.deviceUrl
-   * @param {String} options.resourceId,
+   * @param {String} options.phoneUrl
    * @param {String} options.correlationId
+   * @param {String} options.selfId
    * @returns {Promise}
    * @private
    */
-  leavePstn({
-    locusUrl, dialInUrl, correlationId, selfId
+  disconnectPhoneAudio({
+    locusUrl, phoneUrl, correlationId, selfId
   }) {
     LoggerProxy.logger.info(
-      `Meeting:request#leavePstn --> request device ${dialInUrl} to leaving`,
+      `Meeting:request#disconnectPhoneAudio --> request phone ${phoneUrl} to leave`,
       correlationId
     );
     const uri = `${locusUrl}/${PARTICIPANT}/${selfId}/${LEAVE}`;
@@ -263,7 +305,7 @@ export default class MeetingRequest extends StatelessWebexPlugin {
     const body = {
       device: {
         deviceType: deviceType.PROVISIONAL,
-        url: dialInUrl
+        url: phoneUrl
       },
       correlationId
     };
@@ -273,7 +315,9 @@ export default class MeetingRequest extends StatelessWebexPlugin {
       uri,
       body
     }).catch((err) => {
-      LoggerProxy.logger.error(`Meeting:request#leavePstn --> Error when requesting pstn device ${dialInUrl} to leave, error ${err}`);
+      LoggerProxy.logger.error(
+        `Meeting:request#disconnectPhoneAudio --> Error when requesting phone ${phoneUrl} to leave, error ${err}`
+      );
 
       throw err;
     });

package/src/meeting/util.js

@@ -134,7 +134,7 @@ MeetingUtil.cleanUp = (meeting) => {
     .then(() => meeting.roap.stop(meeting.correlationId, meeting.roapSeq));
 };
 
-MeetingUtil.leavePstn = (meeting, dialInUrl) => {
+MeetingUtil.disconnectPhoneAudio = (meeting, phoneUrl) => {
   if (meeting.meetingState === FULL_STATE.INACTIVE) {
     return Promise.reject(new MeetingNotActiveError());
   }
@@ -143,11 +143,11 @@ MeetingUtil.leavePstn = (meeting, dialInUrl) => {
     locusUrl: meeting.locusUrl,
     selfId: meeting.selfId,
     correlationId: meeting.correlationId,
-    dialInUrl
+    phoneUrl
   };
 
   return meeting.meetingRequest
-    .leavePstn(options)
+    .disconnectPhoneAudio(options)
     .then((response) => {
       if (response?.body?.locus) {
         meeting.locusInfo.onFullLocus(response.body.locus);
@@ -155,7 +155,7 @@ MeetingUtil.leavePstn = (meeting, dialInUrl) => {
     })
     .catch((err) => {
       LoggerProxy.logger.error(
-        `Meeting:util#leavePstn --> An error occured while trying to leave pstn with an id of ${
+        `Meeting:util#disconnectPhoneAudio --> An error occured while disconnecting phone audio in meeting ${
           meeting.id
         }, error: ${err}`
       );

package/test/unit/spec/meeting/index.js

@@ -1902,7 +1902,9 @@ describe('plugin-meetings', () => {
 
       describe('#usePhoneAudio', () => {
         beforeEach(() => {
-          meeting.meetingRequest.dialIn = sinon.stub().returns(Promise.resolve());
+          meeting.meetingRequest.dialIn = sinon.stub().returns(Promise.resolve({body: {locus: 'testData'}}));
+          meeting.meetingRequest.dialOut = sinon.stub().returns(Promise.resolve({body: {locus: 'testData'}}));
+          meeting.locusInfo.onFullLocus = sinon.stub().returns(Promise.resolve());
         });
 
         it('with no parameters triggers dial-in, delegating request to meetingRequest correctly', async () => {
@@ -1915,8 +1917,11 @@ describe('plugin-meetings', () => {
             locusUrl: meeting.locusUrl,
             clientUrl: meeting.deviceUrl
           });
+          assert.calledWith(meeting.locusInfo.onFullLocus, 'testData');
+          assert.notCalled(meeting.meetingRequest.dialOut);
 
           meeting.meetingRequest.dialIn.resetHistory();
+          meeting.locusInfo.onFullLocus.resetHistory();
 
           // try again. the dial in urls should match
           await meeting.usePhoneAudio();
@@ -1927,6 +1932,65 @@ describe('plugin-meetings', () => {
             locusUrl: meeting.locusUrl,
             clientUrl: meeting.deviceUrl
           });
+          assert.calledWith(meeting.locusInfo.onFullLocus, 'testData');
+          assert.notCalled(meeting.meetingRequest.dialOut);
+        });
+
+        it('given a phone number, triggers dial-out, delegating request to meetingRequest correctly', async () => {
+          const phoneNumber = '+442088241000';
+
+          await meeting.usePhoneAudio(phoneNumber);
+          const DIAL_OUT_URL = meeting.dialOutUrl;
+
+          assert.calledWith(meeting.meetingRequest.dialOut, {
+            correlationId: meeting.correlationId,
+            dialOutUrl: DIAL_OUT_URL,
+            locusUrl: meeting.locusUrl,
+            clientUrl: meeting.deviceUrl,
+            phoneNumber
+          });
+          assert.calledWith(meeting.locusInfo.onFullLocus, 'testData');
+          assert.notCalled(meeting.meetingRequest.dialIn);
+
+          meeting.meetingRequest.dialOut.resetHistory();
+          meeting.locusInfo.onFullLocus.resetHistory();
+
+          // try again. the dial out urls should match
+          await meeting.usePhoneAudio(phoneNumber);
+
+          assert.calledWith(meeting.meetingRequest.dialOut, {
+            correlationId: meeting.correlationId,
+            dialOutUrl: DIAL_OUT_URL,
+            locusUrl: meeting.locusUrl,
+            clientUrl: meeting.deviceUrl,
+            phoneNumber
+          });
+          assert.calledWith(meeting.locusInfo.onFullLocus, 'testData');
+          assert.notCalled(meeting.meetingRequest.dialIn);
+        });
+
+        it('rejects if the request failed (dial in)', () => {
+          const error = 'something bad happened';
+
+          meeting.meetingRequest.dialIn = sinon.stub().returns(Promise.reject(error));
+
+          return meeting.usePhoneAudio().then(() => Promise.reject(new Error('Promise resolved when it should have rejected'))).catch((e) => {
+            assert.equal(e, error);
+
+            return Promise.resolve();
+          });
+        });
+
+        it('rejects if the request failed (dial out)', async () => {
+          const error = 'something bad happened';
+
+          meeting.meetingRequest.dialOut = sinon.stub().returns(Promise.reject(error));
+
+          return meeting.usePhoneAudio('+441234567890').then(() => Promise.reject(new Error('Promise resolved when it should have rejected'))).catch((e) => {
+            assert.equal(e, error);
+
+            return Promise.resolve();
+          });
         });
       });
 

package/test/unit/spec/meeting/request.js

@@ -152,23 +152,48 @@ describe('plugin-meetings', () => {
         assert.equal(requestParams.body.device.clientUrl, 'clientUrl');
       });
 
-      it('sends leave pstn request', async () => {
+      it('sends dial out pstn request', async () => {
+        const locusUrl = 'locusUrl';
+        const clientUrl = 'clientUrl';
+        const correlationId = 'random-uuid';
+        const dialOutUrl = 'url';
+        const phoneNumber = '+442088241000';
+
+        await meetingsRequest.dialOut({
+          locusUrl,
+          clientUrl,
+          correlationId,
+          dialOutUrl,
+          phoneNumber
+        });
+        const requestParams = meetingsRequest.request.getCall(0).args[0];
+
+        assert.equal(requestParams.method, 'POST');
+        assert.equal(requestParams.uri, `${locusUrl}/participant`);
+        assert.equal(requestParams.body.device.url, dialOutUrl);
+        assert.equal(requestParams.body.device.deviceType, 'PROVISIONAL');
+        assert.equal(requestParams.body.device.provisionalType, 'DIAL_OUT');
+        assert.equal(requestParams.body.device.clientUrl, 'clientUrl');
+        assert.equal(requestParams.body.device.dialoutAddress, phoneNumber);
+      });
+
+      it('sends disconnect phone audio request', async () => {
         const locusUrl = 'locusUrl';
         const selfId = 'selfId';
         const correlationId = 'random-uuid';
-        const dialInUrl = 'url';
+        const phoneUrl = 'url';
 
-        await meetingsRequest.leavePstn({
+        await meetingsRequest.disconnectPhoneAudio({
           locusUrl,
           selfId,
           correlationId,
-          dialInUrl
+          phoneUrl
         });
         const requestParams = meetingsRequest.request.getCall(0).args[0];
 
         assert.equal(requestParams.method, 'PUT');
         assert.equal(requestParams.uri, `${locusUrl}/participant/${selfId}/leave`);
-        assert.equal(requestParams.body.device.url, dialInUrl);
+        assert.equal(requestParams.body.device.url, phoneUrl);
         assert.equal(requestParams.body.device.deviceType, 'PROVISIONAL');
       });
     });