@webex/plugin-meetings 2.59.8 → 2.60.0-next.2

package/src/breakouts/README.md

@@ -0,0 +1,220 @@
+# Breakout Sessions
+
+Breakout sessions are like meetings within meetings. They have separate roster lists and titles. Participants can move between breakouts and the main session.
+
+### Enabling
+
+To enable breakouts the `breakoutsSupported` parameter must be passed to the meeting join method.
+
+### Structure
+
+The current breakout session is accessible as follows:
+
+```javascript
+breakouts.currentBreakoutSession;
+```
+
+Other breakout sessions are available in the breakouts collection. These are breakouts that you known about. If you are an attendee, you may not know about all the breakout sessions in the meeting.
+
+```javascript
+breakouts.breakouts;
+```
+
+note: The `currentBreakoutSession` is NOT a member of the `breakouts.breakouts` collection.
+
+Some information about the state of breakouts is available on the `meeting.breakouts` object itself
+
+```javascript
+// The number of seconds after ending breakouts before the participants are returned to the main session
+breakouts.delayCloseTime;
+
+// Whether the participant is allowed back to the main session
+breakouts.allowBackToMain;
+```
+
+### Attendee functionality
+
+The normal meeting members are updated when you move in and out of a breakout session.
+
+The following are methods available to attendees of a meeting:
+
+```javascript
+// Join a breakout
+// This can be used when the participant is in the main session or in a different breakout session
+// when call join function, should send message to metrics
+/* Breakout Sessions created during meetings allow participants to move into smaller breakout sessions and then 
+   return to the main meeting at a later time. These moves can be initiated by the user or by the meeting 
+   host/co-host.  The goal of this metric is to track these moves in production by instrumenting them for 
+   analysis from the end user's experience perspective.
+*/
+breakout.join();
+
+// Leave a breakout
+// This will cause the participant to return to the main session
+breakouts.currentBreakoutSession.leave();
+
+// Ask for help when in a breakout session. 10 second cooldown.
+breakout.currentBreakoutSession.askForHelp();
+```
+
+#### Members
+
+Each breakout session has members. Members represent other entities within the meeting.
+The current breakout session members are accessed via the meeting object i.e. they will automatically
+be updated when the user moves between sessions.
+
+To see which members are in other sessions, you can access them via the breakout model. The Members
+class is the same as that of the main meeting.
+
+```javascript
+breakout = breakouts.breakouts.models[0];
+breakout.members;
+```
+
+#### breakouts events
+
+```javascript
+// When the breakouts in the breakouts collection changes. This includes updates to session members
+on('meeting:breakouts:update', (breakouts) => {});
+
+// When the breakout sessions end this event will be fired
+on('meeting:breakouts:closing', () => {});
+
+// When the host sends a message to the breakout this event will fire
+on('meeting:breakouts:message', {senderUserId, sentTime, message, sessionId});
+```
+
+When breakouts are started there are several possibilities:
+
+1. The attendee is forced to join a session
+2. The attendee is assigned to a session, but can join when they feel like it
+3. The attendee is not assigned to a session, and can choose which session they want to join
+
+```javascript
+breakout.assigned; // Assigned to a session, but not in it yet
+breakout.assignedCurrent; // Forced to join a session
+breakout.active; // The session exists
+breakout.allowed; // The user is allowed to join the session
+breakout.requested; // The user has been requested to join the session
+```
+
+The above attributes of the breakout sessions, combined with the `meeting:breakouts:update` event allow you to determine which situation you are in.
+
+A host can signal attendees to move to a particular session. In this case the following is available. Using the same event, and the `requested` attribute of the breakout you can determine which session is to be moved to. Requesting return to the main session is the current use case of this.
+
+### Host functionality
+
+The following are methods available to a hosts of a meeting.
+
+note: None of these are currently implemented
+
+```javascript
+
+// Move a participant to breakout
+breakout.move(participant)
+
+// Remove someone from a breakout session
+// This returns them to the main session
+breakout.remove(participant)
+
+// Deletes a breakout session
+// This can only be done when breakouts are inactive
+breakout.delete()
+
+/*
+Create breakout sessions, Type is array
+Format: [{'name':'session1', "anyoneCanJoin" : true}]
+*/
+breakouts.create(sessions)
+
+// Delete all breakout sessions
+breakouts.clearSessions()
+
+// update breakout session with params
+// if unlockEdit is true, will release lock editing after update finish
+breakout.update(params, unlockEdit)
+
+// Start breakout sessions with necessary params
+breakouts.start(params)
+
+// Assign a particpant/participants to breakouts/a breakout
+// sessions should be like: [{id:'xx',memberIds:['111'],emails:['111@ss.com',anyone: true]},...]
+breakouts.assign(sessions)
+
+// Dynammic assign a particpant/participants to breakouts/main (not used by now)
+// Admit lobby waiting participants to a breakout directly
+// sessions should be like: [{id:'xx',participants:['111'],targetState:'JOINED'},...]
+breakouts.dynamicAssign(sessions)
+
+// End breakout sessions with necessary params
+breakouts.end(params)
+
+// get breakout sessions with/without param editlock
+breakouts.getBreakout(editlock?)
+
+// Enable breakout sessions
+breakouts.enable()
+
+// Enable and lock breakout 
+breakouts.enableAndLockBreakout()
+
+// Lock breakout
+breakouts.lockBreakout()
+
+// Unlock breakout
+breakouts.unLockEditBreakout()
+
+// Disable breakout sessions
+breakouts.disable()
+
+// Send message asking all participants to return to the main session
+breakouts.askAllToReturn()
+
+// Send a message to a breakout session
+// You can determine which participant types receive the message, if no type set, default is to all participants
+breakout.broadcast(message, {participants: boolean, cohosts: boolean, presenters: boolean})
+
+// Send a message to All breakout sessions
+// You can determine which participant types receive the message,  if no type set, default is to all participants
+breakouts.broadcast(message, {participants: boolean, cohosts: boolean, presenters: boolean})
+
+// When breakouts are active you can cancel the automatic end of all sessions by calling this
+// method. It cannot be restarted, only manually ending breakouts is possible after calling this
+breakouts.cancelAutomaticEnd()
+
+IBreakoutConfig {
+  /*
+  Number of sessions to count down before returning users to main session. Seconds. Default 60. 0 means off
+  */
+  countdownTimer: Number,
+  /*
+  Whether attendees are allowed to return to the main meeting
+  */
+  allowReturntoMainMeeting: Boolean,
+  /*
+  Whether attendees are allowed to join later
+  */
+  allowJoinLater: Boolean,
+  /*
+  The timeout after which breakouts are automatically ended. Seconds. Default 1800 (30 minutes) Miniumum 5 minutes.
+  */
+  automaticallyEndBreakoutsAfter: Number,
+  /*
+  How participants are assigned to breakouts.
+  auto -> participants are automatically placed in sessions
+  */
+  assignmentMethod: 'auto' | 'manual' | 'choose'
+}
+
+// Configure settings on breakouts
+breakouts.configure(config)
+
+// set whether anyone can join the breakout or whether it is just assigned participants that can join
+breakout.setOpen(isOpen)
+
+// When the members change for a given breakout
+on('meeting:breakout:members:update', ({sessionId, members}) => {
+
+})
+
+```

package/src/breakouts/breakout.ts

@@ -0,0 +1,188 @@
+/*!
+ * Copyright (c) 2015-2023 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import {WebexPlugin} from '@webex/webex-core';
+
+import uuid from 'uuid';
+import {_ID_, HTTP_VERBS, MEETINGS} from '../constants';
+import Members from '../members';
+import BreakoutRequest from './request';
+import breakoutEvent from './events';
+/**
+ * @class
+ */
+const Breakout = WebexPlugin.extend({
+  idAttribute: 'sessionId',
+
+  namespace: MEETINGS,
+
+  breakoutRequest: BreakoutRequest,
+  props: {
+    active: ['boolean', false, false], // this session is active
+    allowed: ['boolean', false, false], // allowed to join this session
+    assigned: ['boolean', false, false], // assigned to this session, but not necessarily joined yet
+    assignedCurrent: ['boolean', false, false], // assigned AND current session
+    requested: ['boolean', false, false], // requested by the host to join this session
+    current: ['boolean', false, false], // the current joined session
+    name: 'string',
+    sessionId: 'string',
+    sessionType: 'string',
+    groupId: 'string',
+    url: 'string', // where to send requests to
+    requestedLastModifiedTime: 'string',
+  },
+
+  derived: {
+    isMain: {
+      cache: false, // fix issue: sometimes the derived will not change even if the deps changed
+      deps: ['sessionType'],
+      /**
+       * If the breakout has no name, assume it is the main session
+       * @returns {boolean}
+       */
+      fn() {
+        return this.sessionType === 'MAIN';
+      },
+    },
+  },
+  /**
+   * initializer for the Breakout class
+   * @returns {void}
+   */
+  initialize() {
+    // @ts-ignore
+    this.breakoutRequest = new BreakoutRequest({webex: this.webex});
+    this.breakoutRosterLocus = null;
+  },
+
+  /**
+   * Joins the breakout session
+   * @returns {Promise}
+   */
+  async join() {
+    const breakoutMoveId = uuid.v4();
+    const deviceUrl = this.webex.internal.device.url;
+    const {meetingId} = this.collection.parent;
+    const meeting = this.webex.meetings.getMeetingByType(_ID_, meetingId);
+    breakoutEvent.onBreakoutMoveRequest(
+      {currentSession: this, meeting, breakoutMoveId},
+      // @ts-ignore
+      this.webex.internal.newMetrics.submitClientEvent.bind(this.webex.internal.newMetrics)
+    );
+    const result = await this.request({
+      method: HTTP_VERBS.POST,
+      uri: `${this.url}/move`,
+      body: {
+        breakoutMoveId,
+        deviceUrl,
+        groupId: this.groupId,
+        sessionId: this.sessionId,
+      },
+    });
+    breakoutEvent.onBreakoutMoveResponse(
+      {currentSession: this, meeting, breakoutMoveId},
+      // @ts-ignore
+      this.webex.internal.newMetrics.submitClientEvent.bind(this.webex.internal.newMetrics)
+    );
+
+    return result;
+  },
+
+  /**
+   * Leaves the breakout session to return to the main session
+   * @returns {Promise}
+   * @throws {Error} if an attempt is made to leave the main session or if the main session cannot be found
+   */
+  leave() {
+    if (this.isMain) {
+      throw new Error('Cannot leave the main session');
+    }
+
+    const mainSession = this.parent.breakouts.filter((breakout) => breakout.isMain)[0];
+
+    if (!mainSession) {
+      throw new Error('Cannot leave, no main session found');
+    }
+
+    return mainSession.join();
+  },
+
+  /**
+   * Sends a help request for the current breakout
+   * @returns {Promise}
+   */
+  askForHelp() {
+    return this.request({
+      method: HTTP_VERBS.POST,
+      uri: `${this.url}/help`,
+      body: {
+        groupId: this.groupId,
+        sessionId: this.sessionId,
+      },
+    });
+  },
+
+  /**
+   * inits the members object
+   * @returns {void}
+   */
+  initMembers() {
+    const {meetingId} = this.collection.parent;
+    const meeting = this.webex.meetings.getMeetingByType(_ID_, meetingId);
+    this.members = new Members(
+      {
+        meeting,
+      },
+      {parent: this.webex}
+    );
+  },
+
+  /**
+   * check sequence and determine whether to update the new roster or not
+   * @param {Object} locus Locus object
+   * @returns {Boolean}
+   */
+  isNeedHandleRoster(locus: any) {
+    if (!this.breakoutRosterLocus?.sequence?.entries?.length || !locus?.sequence?.entries?.length) {
+      return true;
+    }
+    const prevSequence = this.breakoutRosterLocus.sequence.entries[0];
+    const currentSequence = locus.sequence.entries[0];
+
+    return currentSequence > prevSequence;
+  },
+  /**
+   * Parses the participants from the locus object
+   * @param {Object} locus Locus object
+   * @returns {void}
+   */
+  parseRoster(locus) {
+    if (!this.members) {
+      this.initMembers();
+    }
+    if (!this.isNeedHandleRoster(locus)) {
+      return;
+    }
+    this.breakoutRosterLocus = locus;
+    this.members.locusParticipantsUpdate(locus);
+  },
+
+  /**
+   * Broadcast message to this breakout session's participants
+   * @param {String} message
+   * @param {Object} options
+   * @returns {Promise}
+   */
+  broadcast(message, options) {
+    return this.breakoutRequest.broadcast({
+      url: this.url,
+      message,
+      options,
+      groupId: this.groupId,
+      sessionId: this.sessionId,
+    });
+  },
+});
+
+export default Breakout;

package/src/breakouts/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 Breakout from './breakout';
+
+const BreakoutCollection = AmpCollection.extend({
+  model: Breakout,
+
+  namespace: MEETINGS,
+
+  mainIndex: 'sessionId',
+});
+
+export default BreakoutCollection;

package/src/breakouts/edit-lock-error.ts

@@ -0,0 +1,25 @@
+import {ERROR_DICTIONARY} from '../constants';
+
+/**
+ * Extended Error object to signify breakout related errors
+ */
+export default class BreakoutEditLockedError extends Error {
+  code: any;
+  error: any;
+  sdkMessage: any;
+
+  /**
+   *
+   * @constructor
+   * @param {String} [message]
+   * @param {Object} [error]
+   */
+  constructor(message: string = ERROR_DICTIONARY.BREAKOUT_EDIT.MESSAGE, error: any = null) {
+    super(message);
+    this.name = ERROR_DICTIONARY.BREAKOUT_EDIT.NAME;
+    this.sdkMessage = ERROR_DICTIONARY.BREAKOUT_EDIT.MESSAGE;
+    this.error = error;
+    this.stack = error ? error.stack : new Error().stack;
+    this.code = ERROR_DICTIONARY.BREAKOUT_EDIT.CODE;
+  }
+}

package/src/breakouts/events.ts

@@ -0,0 +1,56 @@
+// eslint-disable-next-line import/prefer-default-export
+import {ClientEvent} from '@webex/internal-plugin-metrics';
+
+const breakoutEvent: {
+  onBreakoutMoveRequest: (eventInfo: any, submitClientEvent: any) => void;
+  onBreakoutMoveResponse: (eventInfo: any, submitClientEvent: any) => void;
+  onBreakoutJoinResponse: (eventInfo: any, submitClientEvent: any) => void;
+  postMoveCallAnalyzer: (
+    event: ClientEvent['name'],
+    eventInfo: any,
+    submitClientEvent: any
+  ) => void;
+} = {
+  onBreakoutMoveRequest: (eventInfo, submitClientEvent) => {
+    breakoutEvent.postMoveCallAnalyzer(
+      'client.breakout-session.move.request',
+      eventInfo,
+      submitClientEvent
+    );
+  },
+  onBreakoutMoveResponse: (eventInfo, submitClientEvent) => {
+    breakoutEvent.postMoveCallAnalyzer(
+      'client.breakout-session.move.response',
+      eventInfo,
+      submitClientEvent
+    );
+  },
+  onBreakoutJoinResponse: (eventInfo, submitClientEvent) => {
+    breakoutEvent.postMoveCallAnalyzer(
+      'client.breakout-session.join.response',
+      eventInfo,
+      submitClientEvent
+    );
+  },
+  postMoveCallAnalyzer: (event: ClientEvent['name'], eventInfo: any, submitClientEvent) => {
+    if (!eventInfo?.breakoutMoveId || !eventInfo?.meeting) {
+      return;
+    }
+    if (!eventInfo.meeting.meetingInfo?.enableConvergedArchitecture) {
+      return;
+    }
+    submitClientEvent({
+      name: event,
+      payload: {
+        identifiers: {
+          breakoutMoveId: eventInfo.breakoutMoveId,
+          breakoutSessionId: eventInfo?.currentSession?.sessionId,
+          breakoutGroupId: eventInfo?.currentSession?.groupId,
+        },
+      },
+      options: {meetingId: eventInfo.meeting.id},
+    });
+  },
+};
+
+export default breakoutEvent;