@webex/plugin-meetings 3.0.0-beta.4 → 3.0.0-beta.400

package/src/interceptors/locusRetry.ts

@@ -0,0 +1,67 @@
+/*!
+ * Copyright (c) 2015-2020 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import {Interceptor} from '@webex/http-core';
+
+const rateLimitExpiryTime = new WeakMap();
+/**
+ * @class
+ */
+export default class LocusRetryStatusInterceptor extends Interceptor {
+  /**
+   * @returns {LocusRetryStatusInterceptor}
+   */
+  static create() {
+    // @ts-ignore
+    return new LocusRetryStatusInterceptor({webex: this});
+  }
+
+  /**
+   * Handle response errors
+   * @param {Object} options
+   * @param {WebexHttpError} reason
+   * @returns {Promise<WebexHttpError>}
+   */
+  onResponseError(options, reason) {
+    if ((reason.statusCode === 503 || reason.statusCode === 429) && options.uri.includes('locus')) {
+      const hasRetriedLocusRequest = rateLimitExpiryTime.get(this);
+      const retryAfterTime = options.headers['retry-after'] || 2000;
+
+      if (hasRetriedLocusRequest) {
+        rateLimitExpiryTime.set(this, false);
+
+        return Promise.reject(options);
+      }
+      rateLimitExpiryTime.set(this, true);
+
+      return this.handleRetryRequestLocusServiceError(options, retryAfterTime);
+    }
+
+    return Promise.reject(reason);
+  }
+
+  /**
+   * Handle retries for locus service unavailable errors
+   * @param {Object} options associated with the request
+   * @param {number} retryAfterTime retry after time in milliseconds
+   * @returns {Promise}
+   */
+  handleRetryRequestLocusServiceError(options, retryAfterTime) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        clearTimeout(timeout);
+
+        // @ts-ignore
+        this.webex
+          .request({
+            method: options.method,
+            uri: options.uri,
+            body: options.body,
+          })
+          .then(resolve)
+          .catch(reject);
+      }, retryAfterTime);
+    });
+  }
+}

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,349 @@
+/*!
+ * 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 {bool} is target language changed
+   */
+  updateSelfInterpretation({interpretation, selfParticipantId}) {
+    const preTargetLanguage = this.targetLanguage;
+    const {originalLanguage, sourceLanguage, order, isActive, targetLanguage, receiveLanguage} =
+      interpretation || {};
+    this.set({originalLanguage, sourceLanguage, order, isActive, targetLanguage, receiveLanguage});
+    this.set('selfParticipantId', selfParticipantId);
+    this.set('selfIsInterpreter', !!targetLanguage);
+
+    return !!(preTargetLanguage !== targetLanguage);
+  },
+
+  /**
+   * Get the language code of the interpreter target language
+   * @returns {number}
+   */
+  getTargetLanguageCode() {
+    if (this.selfIsInterpreter) {
+      return this.siLanguages.get(this.targetLanguage)?.languageCode;
+    }
+
+    return 0;
+  },
+
+  /**
+   * 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;