@webex/plugin-meetings 3.0.0-beta.3 → 3.0.0-beta.300

package/src/interpretation/README.md

@@ -0,0 +1,60 @@
+# Simultaneous Interpretation
+
+Simultaneous Interpretation (SI) feature provides support for interpretation of in-meeting audio. The host will specify the target languages at schedule time and assign language pairs to the desired interpreters. Each interpreter will use their client to indicate the language spoken at any point in time. For example, Alice might be translating between English and French. When an English speaker is talking in the meeting, Alice will use her client to indicate she is speaking French. When a French speaker is talking, Alice will indicate that she is speaking English. The host’s client will display the status of each interpreter including the current interpretation direction.
+
+### Structure
+SI languages are available in the siLanguages collection. List the languages which current meeting support to do simultaneous interpretation. Can subscribe the language's voice channel which you want to listen from the list.
+
+```javascript
+interpretation.siLanguages;
+```
+### Attendee functionality
+```javascript
+//subscribe this si language's voice channel
+siLanguage.subscribe();
+
+//unsubscribe this si language's voice channel
+siLanguage.unsubscribe();
+```
+### Host functionality
+The following are methods available to the host of a meeting.
+
+```javascript
+//get the support list of interpretation languages. only host is allowed to call it
+interpretation.getSupportLanguages();
+
+//get the interpreters list of the meeting
+interpretation.getInterpreters();
+
+//update the interpreters list, input parameter is an array of interpreters
+interpretation.updateInterpreters([{
+  sourceLanguage : 'fr-FR',
+  targetLanguage : 'zh-ZH',
+  usingResource : {
+    id : 'a96747e2-1fc6-41d3-9ac7-512dd9478b6e'
+  },
+  order : 0
+},]);
+```
+
+### Interpreter functionality
+
+The following are methods available to the interpreters of a meeting.
+
+```javascript
+//Change direction of interpretation for an interpreter participant
+interpretation.changeDirection();
+
+//Handoff between interpreters, input paramerter participantId is the target to handoff
+interpretation.handoffInterpreter(participantId);
+
+//in-active interpreter request to handoff to self
+interpretation.requestHandoff();
+
+//accept the request of handoff, input paramter url is from last approval event which generate by server side
+interpretation.acceptRequest(url);
+
+//decline the request of handoff, input paramter url is from last approval event which generate by server side
+interpretation.declineRequest(url);
+
+```

package/src/interpretation/collection.ts

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import AmpCollection from 'ampersand-collection';
+
+import {MEETINGS} from '../constants';
+
+import SILanguage from './siLanguage';
+
+const SILanguageCollection = AmpCollection.extend({
+  model: SILanguage,
+
+  namespace: MEETINGS,
+
+  mainIndex: 'languageName',
+});
+
+export default SILanguageCollection;

package/src/interpretation/index.ts

@@ -0,0 +1,332 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+import {WebexPlugin} from '@webex/webex-core';
+import LoggerProxy from '../common/logs/logger-proxy';
+import {HTTP_VERBS, INTERPRETATION, MEETINGS} from '../constants';
+
+import SILanguageCollection from './collection';
+
+/**
+ * @class SimultaneousInterpretation
+ */
+const SimultaneousInterpretation = WebexPlugin.extend({
+  namespace: MEETINGS,
+  collections: {
+    siLanguages: SILanguageCollection,
+  },
+
+  props: {
+    locusUrl: 'string', // appears current meeting's locus url
+    approvalUrl: 'string', // appears current meeting's approval url for handoff between interpreters
+    originalLanguage: 'string', // appears current meeting's original language
+    sourceLanguage: 'string', // appears self interpreter's source language
+    targetLanguage: 'string', // appears self interpreter's target language
+    receiveLanguage: 'string', // appears self's receive language
+    order: 'number', // appears the order of self as interpreter
+    isActive: 'boolean', // appears self is interpreter and is active
+    selfParticipantId: 'string', // appears the self participant id
+    canManageInterpreters: 'boolean', // appears the ability to manage interpreters
+    supportLanguages: 'array', // appears the support languages
+    meetingSIEnabled: 'boolean', // appears the meeting support SI feature
+    hostSIEnabled: 'boolean', // appears the meeting host/interpreter feature of SI enabled
+    selfIsInterpreter: 'boolean', // current user is interpreter or not
+  },
+  derived: {
+    shouldQuerySupportLanguages: {
+      cache: false,
+      deps: ['canManageInterpreters', 'hostSIEnabled'],
+      /**
+       * Returns should query support languages or not
+       * @returns {boolean}
+       */
+      fn() {
+        return !!(this.canManageInterpreters && this.hostSIEnabled);
+      },
+    },
+  },
+  /**
+   * initialize for interpretation
+   * @returns {void}
+   */
+  initialize() {
+    this.listenTo(this, 'change:shouldQuerySupportLanguages', () => {
+      if (this.canManageInterpreters && !this.supportLanguages) {
+        this.querySupportLanguages();
+      }
+    });
+    this.listenToHandoffRequests();
+  },
+
+  /**
+   * Calls this to clean up listeners
+   * @returns {void}
+   */
+  cleanUp() {
+    this.stopListening();
+  },
+  /**
+   * Update the current locus url of the meeting
+   * @param {string} locusUrl // locus url
+   * @returns {void}
+   */
+  locusUrlUpdate(locusUrl) {
+    this.set('locusUrl', locusUrl);
+  },
+  /**
+   * Update the approval url for handoff
+   * @param {string} approvalUrl // approval url
+   * @returns {void}
+   */
+  approvalUrlUpdate(approvalUrl) {
+    this.set('approvalUrl', approvalUrl);
+  },
+  /**
+   * Update whether self has capability to manage interpreters (only host can manage it)
+   * @param {boolean} canManageInterpreters
+   * @returns {void}
+   */
+  updateCanManageInterpreters(canManageInterpreters) {
+    this.set('canManageInterpreters', canManageInterpreters);
+  },
+  /**
+   * Update whether the meeting's host si is enabled or not
+   * @param {boolean} hostSIEnabled
+   * @returns {void}
+   */
+  updateHostSIEnabled(hostSIEnabled) {
+    this.set('hostSIEnabled', hostSIEnabled);
+  },
+
+  /**
+   * Update whether the meeting support SI feature or not from meeting info
+   * @param {boolean} meetingSIEnabled
+   * @param {boolean} selfIsInterpreter
+   * @returns {void}
+   */
+  updateMeetingSIEnabled(meetingSIEnabled: boolean, selfIsInterpreter): void {
+    this.set('meetingSIEnabled', meetingSIEnabled);
+    this.set('selfIsInterpreter', selfIsInterpreter);
+  },
+
+  /**
+   * Update the interpretation languages channels which user can choose to subscribe
+   * @param {Object} interpretation
+   * @returns {void}
+   */
+  updateInterpretation(interpretation) {
+    this.siLanguages.set(interpretation?.siLanguages || []);
+  },
+  /**
+   * Update self's interpretation information (self is interpreter)
+   * @param {Object} interpretation
+   * @param {String} selfParticipantId
+   * @returns {void}
+   */
+  updateSelfInterpretation({interpretation, selfParticipantId}) {
+    const {originalLanguage, sourceLanguage, order, isActive, targetLanguage, receiveLanguage} =
+      interpretation || {};
+    this.set({originalLanguage, sourceLanguage, order, isActive, targetLanguage, receiveLanguage});
+    this.set('selfParticipantId', selfParticipantId);
+  },
+  /**
+   * query interpretation languages
+   * @returns {Promise}
+   */
+  querySupportLanguages() {
+    return this.request({
+      method: HTTP_VERBS.GET,
+      uri: `${this.locusUrl}/languages/interpretation`,
+    })
+      .then((result) => {
+        this.set('supportLanguages', result.body?.siLanguages);
+        this.trigger(INTERPRETATION.EVENTS.SUPPORT_LANGUAGES_UPDATE);
+      })
+      .catch((error) => {
+        LoggerProxy.logger.error('Meeting:interpretation#querySupportLanguages failed', error);
+        throw error;
+      });
+  },
+  /**
+   * get interpreters of the meeting
+   * @returns {Promise}
+   */
+  getInterpreters() {
+    return this.request({
+      method: HTTP_VERBS.GET,
+      uri: `${this.locusUrl}/interpretation/interpreters`,
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#getInterpreters failed', error);
+      throw error;
+    });
+  },
+  /**
+   * update interpreters of the meeting
+   * @param {Array} interpreters
+   * @returns {Promise}
+   */
+  updateInterpreters(interpreters) {
+    return this.request({
+      method: HTTP_VERBS.PATCH,
+      uri: `${this.locusUrl}/controls`,
+      body: {
+        interpretation: {
+          interpreters,
+        },
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#updateInterpreters failed', error);
+      throw error;
+    });
+  },
+  /**
+   * Change direction of interpretation for an interpreter participant
+   * @returns {Promise}
+   */
+  changeDirection() {
+    if (!this.sourceLanguage || !this.targetLanguage) {
+      return Promise.reject(new Error('Missing sourceLanguage or targetLanguage'));
+    }
+
+    if (!this.selfParticipantId) {
+      return Promise.reject(new Error('Missing self participant id'));
+    }
+
+    return this.request({
+      method: HTTP_VERBS.PATCH,
+      uri: `${this.locusUrl}/participant/${this.selfParticipantId}/controls`,
+      body: {
+        interpretation: {
+          sourceLanguage: this.targetLanguage,
+          targetLanguage: this.sourceLanguage,
+          isActive: this.isActive,
+          order: this.order,
+        },
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#changeDirection failed', error);
+      throw error;
+    });
+  },
+  /**
+   * Sets up a listener for handoff requests from mercury
+   * @returns {void}
+   */
+  listenToHandoffRequests() {
+    this.listenTo(this.webex.internal.mercury, 'event:locus.approval_request', (event) => {
+      if (event?.data?.approval?.resourceType === INTERPRETATION.RESOURCE_TYPE) {
+        const {receivers, initiator, actionType, url} = event.data.approval;
+        const receiverId = receivers?.[0]?.participantId;
+        const isReceiver = !!receiverId && receiverId === this.selfParticipantId;
+        const senderId = initiator?.participantId;
+        const isSender = !!senderId && senderId === this.selfParticipantId;
+        if (!isReceiver && !isSender) {
+          return;
+        }
+        this.trigger(INTERPRETATION.EVENTS.HANDOFF_REQUESTS_ARRIVED, {
+          actionType,
+          isReceiver,
+          isSender,
+          senderId,
+          receiverId,
+          url,
+        });
+      }
+    });
+  },
+  /**
+   * handoff the active interpreter role to another interpreter in same group, only the interpreter is allowed to call this api
+   * @param {string} participantId the participant id you want to hand off
+   * @returns {Promise}
+   */
+  handoffInterpreter(participantId) {
+    if (!participantId) {
+      return Promise.reject(new Error('Missing target participant id'));
+    }
+    if (!this.approvalUrl) {
+      return Promise.reject(new Error('Missing approval url'));
+    }
+
+    return this.request({
+      method: HTTP_VERBS.POST,
+      uri: this.approvalUrl,
+      body: {
+        actionType: INTERPRETATION.ACTION_TYPE.OFFERED,
+        resourceType: INTERPRETATION.RESOURCE_TYPE,
+        receivers: [
+          {
+            participantId,
+          },
+        ],
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#handoffInterpreter failed', error);
+      throw error;
+    });
+  },
+  /**
+   * the in-active interpreter request to hand off the active role to self
+   * @returns {Promise}
+   */
+  requestHandoff() {
+    if (!this.approvalUrl) {
+      return Promise.reject(new Error('Missing approval url'));
+    }
+
+    return this.request({
+      method: HTTP_VERBS.POST,
+      uri: this.approvalUrl,
+      body: {
+        actionType: INTERPRETATION.ACTION_TYPE.REQUESTED,
+        resourceType: INTERPRETATION.RESOURCE_TYPE,
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#requestHandoff failed', error);
+      throw error;
+    });
+  },
+  /**
+   * accept the request of handoff
+   * @param {String} url the url get from last approval event
+   * @returns {Promise}
+   */
+  acceptRequest(url) {
+    if (!url) {
+      return Promise.reject(new Error('Missing the url to accept'));
+    }
+
+    return this.request({
+      method: HTTP_VERBS.PUT,
+      uri: url,
+      body: {
+        actionType: INTERPRETATION.ACTION_TYPE.ACCEPTED,
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#acceptRequest failed', error);
+      throw error;
+    });
+  },
+  /**
+   * decline the request of handoff
+   * @param {String} url the url get from last approval event
+   * @returns {Promise}
+   */
+  declineRequest(url) {
+    if (!url) {
+      return Promise.reject(new Error('Missing the url to decline'));
+    }
+
+    return this.request({
+      method: HTTP_VERBS.PUT,
+      uri: url,
+      body: {
+        actionType: INTERPRETATION.ACTION_TYPE.DECLINED,
+      },
+    }).catch((error) => {
+      LoggerProxy.logger.error('Meeting:interpretation#declineRequest failed', error);
+      throw error;
+    });
+  },
+});
+
+export default SimultaneousInterpretation;

package/src/interpretation/siLanguage.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import {WebexPlugin} from '@webex/webex-core';
+import {MEETINGS} from '../constants';
+
+const SILanguage = WebexPlugin.extend({
+  idAttribute: 'languageName',
+
+  namespace: MEETINGS,
+  props: {
+    languageCode: 'number',
+    languageName: 'string',
+  },
+});
+
+export default SILanguage;

package/src/locus-info/controlsUtils.ts

@@ -0,0 +1,222 @@
+import {isEqual} from 'lodash';
+import {BREAKOUTS} from '../constants';
+
+const ControlsUtils: any = {};
+
+/**
+ * Controls
+ * @typedef {Object} LocusControls
+ * @property {Object} record
+ * @property {Boolean} record.recording
+ * @property {Object} record.meta
+ * @property {String} record.meta.modifiedBy
+ */
+
+/**
+ * parse the relevant host values that we care about: id
+ * @param {LocusControls} controls
+ * @returns {Object} parsedObject - parsed host or null if host was undefined
+ * @returns {String} parsedObject.recordingId
+ */
+ControlsUtils.parse = (controls: any) => {
+  const parsedControls = {...controls};
+
+  if (controls && controls.record) {
+    parsedControls.record = {
+      modifiedBy: ControlsUtils.getId(controls),
+      paused: controls.record.paused ? controls.record.paused : false,
+      recording: controls.record.recording,
+      lastModified: controls.record.meta.lastModified,
+    };
+  }
+
+  if (controls && controls.meetingContainer) {
+    parsedControls.meetingContainer = {
+      meetingContainerUrl: controls.meetingContainer.meetingContainerUrl,
+    };
+  }
+
+  if (controls && controls.transcribe) {
+    parsedControls.transcribe = {
+      transcribing: controls.transcribe.transcribing,
+      caption: controls.transcribe.caption,
+    };
+  }
+
+  if (controls && controls.entryExitTone) {
+    parsedControls.entryExitTone = controls.entryExitTone.enabled
+      ? controls.entryExitTone.mode
+      : null;
+  }
+
+  if (controls && controls.video) {
+    parsedControls.videoEnabled = controls.video.enabled;
+  }
+
+  if (controls?.muteOnEntry) {
+    parsedControls.muteOnEntry = {enabled: controls.muteOnEntry.enabled};
+  }
+
+  if (controls?.shareControl) {
+    parsedControls.shareControl = {control: controls.shareControl.control};
+  }
+
+  if (controls?.disallowUnmute) {
+    parsedControls.disallowUnmute = {enabled: controls.disallowUnmute.enabled};
+  }
+
+  if (controls?.reactions) {
+    parsedControls.reactions = {
+      enabled: controls.reactions.enabled,
+      showDisplayNameWithReactions: controls.reactions.showDisplayNameWithReactions,
+    };
+  }
+
+  if (controls?.viewTheParticipantList) {
+    parsedControls.viewTheParticipantList = {enabled: controls.viewTheParticipantList.enabled};
+  }
+
+  if (controls?.raiseHand) {
+    parsedControls.raiseHand = {enabled: controls.raiseHand.enabled};
+  }
+
+  if (controls?.video) {
+    parsedControls.video = {enabled: controls.video.enabled};
+  }
+
+  return parsedControls;
+};
+
+/**
+ * parses and returns previous state vs current state and triggers the changes.
+ * @param {LocusControls} oldControls previous state
+ * @param {LocusControls} newControls current state
+ * @returns {Object} combination of state plus the changes
+ */
+ControlsUtils.getControls = (oldControls: any, newControls: any) => {
+  const previous = ControlsUtils.parse(oldControls);
+  const current = ControlsUtils.parse(newControls);
+
+  return {
+    previous,
+    current,
+    updates: {
+      hasMuteOnEntryChanged: current?.muteOnEntry?.enabled !== previous?.muteOnEntry?.enabled,
+
+      hasShareControlChanged: current?.shareControl?.control !== previous?.shareControl?.control,
+
+      hasDisallowUnmuteChanged:
+        current?.disallowUnmute?.enabled !== previous?.disallowUnmute?.enabled,
+
+      hasReactionsChanged: current?.reactions?.enabled !== previous?.reactions?.enabled,
+
+      hasReactionDisplayNamesChanged:
+        current?.reactions?.showDisplayNameWithReactions !==
+        previous?.reactions?.showDisplayNameWithReactions,
+
+      hasViewTheParticipantListChanged:
+        current?.viewTheParticipantList?.enabled !== previous?.viewTheParticipantList?.enabled,
+
+      hasRaiseHandChanged: current?.raiseHand?.enabled !== previous?.raiseHand?.enabled,
+
+      hasVideoChanged: current?.video?.enabled !== previous?.video?.enabled,
+
+      hasRecordingPausedChanged:
+        current?.record &&
+        !isEqual(previous?.record?.paused, current.record.paused) &&
+        (previous?.record?.recording || current?.record?.recording), // see comments directly below
+
+      hasRecordingChanged:
+        current?.record &&
+        !isEqual(previous?.record?.recording, current?.record?.recording) && // upon first join, previous?.record?.recording = undefined; thus, never going to be equal and will always return true
+        (previous?.record?.recording || current?.record?.recording), // therefore, condition added to prevent false firings of #meeting:recording:stopped upon first joining a meeting
+
+      hasMeetingContainerChanged:
+        current?.meetingContainer &&
+        !isEqual(
+          previous?.meetingContainer?.meetingContainerUrl,
+          current?.meetingContainer?.meetingContainerUrl
+        ),
+
+      hasTranscribeChanged:
+        current?.transcribe &&
+        !isEqual(previous?.transcribe?.transcribing, current?.transcribe?.transcribing) && // upon first join, previous?.record?.recording = undefined; thus, never going to be equal and will always return true
+        (previous?.transcribe?.transcribing || current?.transcribe?.transcribing), // therefore, condition added to prevent false firings of #meeting:recording:stopped upon first joining a meeting
+
+      hasEntryExitToneChanged: !!(
+        newControls.entryExitTone &&
+        !isEqual(previous?.entryExitTone, current?.entryExitTone) &&
+        (previous?.entryExitTone || current?.entryExitTone)
+      ),
+
+      hasBreakoutChanged: !isEqual(previous?.breakout, current?.breakout),
+
+      hasInterpretationChanged: !isEqual(previous?.interpretation, current?.interpretation),
+
+      hasVideoEnabledChanged:
+        newControls.video?.enabled !== undefined &&
+        !isEqual(previous?.videoEnabled, current?.videoEnabled),
+    },
+  };
+};
+
+/**
+ * Extract the id from the record controls object
+ * @param {LocusControls} controls
+ * @returns {String|null}
+ */
+ControlsUtils.getId = (controls: any) => {
+  if (controls.record.meta) {
+    return controls.record.meta.modifiedBy;
+  }
+
+  return null;
+};
+
+/**
+ * check whether to replace the meeting's members or not.
+ * For case joined breakout session, need replace meeting's members
+ * @param {LocusControls} oldControls
+ * @param {LocusControls} controls
+ * @returns {Boolean}
+ */
+ControlsUtils.isNeedReplaceMembers = (oldControls: any, controls: any) => {
+  // no breakout case
+  if (!oldControls?.breakout || !controls?.breakout) {
+    return false;
+  }
+
+  return (
+    oldControls.breakout.groupId !== controls.breakout.groupId ||
+    oldControls.breakout.sessionId !== controls.breakout.sessionId
+  );
+};
+
+/**
+ * determine the switch status between breakout session and main session.
+ * @param {LocusControls} oldControls
+ * @param {LocusControls} controls
+ * @returns {Object}
+ */
+ControlsUtils.getSessionSwitchStatus = (oldControls: any, controls: any) => {
+  const status = {isReturnToMain: false, isJoinToBreakout: false};
+  // no breakout case
+  if (!oldControls?.breakout || !controls?.breakout) {
+    return status;
+  }
+
+  status.isReturnToMain =
+    oldControls.breakout.sessionType === BREAKOUTS.SESSION_TYPES.BREAKOUT &&
+    controls.breakout.sessionType === BREAKOUTS.SESSION_TYPES.MAIN;
+  status.isJoinToBreakout =
+    oldControls.breakout.sessionType === BREAKOUTS.SESSION_TYPES.MAIN &&
+    controls.breakout.sessionType === BREAKOUTS.SESSION_TYPES.BREAKOUT;
+
+  return status;
+};
+
+ControlsUtils.isMainSessionDTO = (locus: any) => {
+  return locus?.controls?.breakout?.sessionType !== BREAKOUTS.SESSION_TYPES.BREAKOUT;
+};
+
+export default ControlsUtils;

package/src/locus-info/{embeddedAppsUtils.js → embeddedAppsUtils.ts}

@@ -1,7 +1,6 @@
 import {EMBEDDED_APP_TYPES} from '../constants';
 
-const EmbeddedAppsUtils = {};
-
+const EmbeddedAppsUtils: any = {};
 const SLIDO_REGEX = /.sli.do\//;
 
 /**
@@ -9,8 +8,8 @@ const SLIDO_REGEX = /.sli.do\//;
  * @param {Object} embeddedApp - raw embedded app object
  * @returns {Object} parsedObject - parsed embedded app object
  */
-EmbeddedAppsUtils.parseApp = (embeddedApp) => {
-  const parsedApp = {...embeddedApp};
+EmbeddedAppsUtils.parseApp = (embeddedApp: object) => {
+  const parsedApp: any = {...embeddedApp};
 
   parsedApp.type = EMBEDDED_APP_TYPES.OTHER;
   const url = parsedApp.instanceInfo?.appInstanceUrl;
@@ -29,7 +28,7 @@ EmbeddedAppsUtils.parseApp = (embeddedApp) => {
  * @param {any[]} apps2 - an array of apps
  * @returns {boolean} true if the arrays are different
  */
-EmbeddedAppsUtils.areSimilar = (apps1, apps2) => {
+EmbeddedAppsUtils.areSimilar = (apps1: any[], apps2: any[]) => {
   if (!apps1 || !apps2) {
     return apps1 === apps2;
   }
@@ -52,7 +51,7 @@ EmbeddedAppsUtils.areSimilar = (apps1, apps2) => {
  * @param {array} embeddedApps
  * @returns {array} result - new array of parsed embedded app objects
  */
-EmbeddedAppsUtils.parse = (embeddedApps) =>
+EmbeddedAppsUtils.parse = (embeddedApps: Array<any>) =>
   embeddedApps && embeddedApps.map(EmbeddedAppsUtils.parseApp);
 
 export default EmbeddedAppsUtils;