@webex/plugin-meetings 3.0.0-beta.13 → 3.0.0-beta.131

package/src/annotation/annotation.types.ts

@@ -0,0 +1,42 @@
+/**
+ * Type for an StrokeData Object
+ */
+type StrokeData = {
+  deviceId: string;
+  toUserId: string;
+  requesterId: string;
+  content: string;
+  shareInstanceId: string;
+  encryptionKeyUrl: string;
+  version: string;
+};
+
+type RequestData = {
+  toUserId: string;
+  toDeviceUrl: string;
+  shareInstanceId: string;
+};
+
+type CommandRequestBody = {
+  actionType: string;
+  resourceType: string;
+  shareInstanceId: string;
+  receivers?: any[];
+};
+
+interface IAnnotationChannel {
+  // === below is for presenter
+  acceptRequest: (approval) => undefined | Promise<void>;
+  declineRequest: (approval) => undefined | Promise<void>;
+  closeAnnotation: (requestData: RequestData) => undefined | Promise<void>;
+  changeAnnotationOptions: (options, meeting) => undefined | Promise<void>;
+  // === below is for attendee
+  approveAnnotation: (requestData: RequestData) => undefined | Promise<void>;
+  cancelApproveAnnotation: (requestData: RequestData, approval) => undefined | Promise<void>;
+  sendStrokeData: (strokeData: StrokeData) => void;
+  // =====
+  approvalUrlUpdate: (approvalUrl: string) => void;
+  locusUrlUpdate: (locusUrl: string) => void;
+}
+
+export type {StrokeData, RequestData, CommandRequestBody, IAnnotationChannel};

package/src/annotation/constants.ts

@@ -0,0 +1,36 @@
+export const EVENT_TRIGGERS = {
+  ANNOTATION_STROKE_DATA: 'annotation:strokeData',
+  ANNOTATION_COMMAND: 'annotation:command',
+};
+export const ANNOTATION_RESOURCE_TYPE = 'AnnotationOnShare';
+export const ANNOTATION_RELAY_TYPES = {
+  ANNOTATION_CLIENT: 'annotation.client',
+};
+
+export const ANNOTATION_STATUS = {
+  NO_ANNOTATION: 'NO_ANNOTATION',
+  RUNNING_ANNOTATION: 'RUNNING_ANNOTATION',
+};
+
+export const ANNOTATION_POLICY = {
+  ANYONE_CAN_ANNOTATE: 'AnyoneCanAnnotate',
+  APPROVAL: 'Approval',
+  ANNOTATION_NOT_ALLOWED: 'AnnotationNotAllowed',
+};
+
+export const ANNOTATION_REQUEST_TYPE = {
+  ANNOTATION_MESSAGE: 'annotation_message',
+};
+
+export const enum ANNOTATION_ACTION_TYPE {
+  REQUESTED = 'REQUESTED',
+  ACCEPTED = 'ACCEPTED',
+  DECLINED = 'DECLINED',
+  OFFERED = 'OFFERED',
+  CANCELED = 'CANCELED',
+  EXPIRED = 'EXPIRED',
+  REVOKED = 'REVOKED',
+  CLOSED = 'CLOSED',
+}
+
+export const ANNOTATION = 'annotation';

package/src/annotation/index.ts

@@ -0,0 +1,339 @@
+import uuid from 'uuid';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import {WebexPlugin, config} from '@webex/webex-core';
+import TriggerProxy from '../common/events/trigger-proxy';
+
+import {
+  EVENT_TRIGGERS,
+  ANNOTATION_RELAY_TYPES,
+  ANNOTATION,
+  ANNOTATION_REQUEST_TYPE,
+  ANNOTATION_ACTION_TYPE,
+  ANNOTATION_RESOURCE_TYPE,
+} from './constants';
+
+import {StrokeData, RequestData, IAnnotationChannel, CommandRequestBody} from './annotation.types';
+import {HTTP_VERBS} from '../constants';
+
+/**
+ * @description Annotation to handle LLM and Mercury message and locus API
+ * @class
+ */
+class AnnotationChannel extends WebexPlugin implements IAnnotationChannel {
+  namespace = ANNOTATION;
+
+  private seqNum: number;
+
+  hasSubscribedToEvents: boolean;
+
+  approvalUrl: string;
+  locusUrl: string;
+  deviceUrl: string;
+
+  /**
+   * Initializes annotation module
+   */
+  constructor(...args) {
+    super(...args);
+    this.seqNum = 1;
+  }
+
+  /**
+   * Process Stroke Data
+   * @param {request} request stroke data
+   * @returns {void}
+   */
+  private processStrokeMessage(request) {
+    this.decryptContent(request.value.encryptionKeyUrl, request.value.content).then(
+      (decryptedContent) => {
+        request.value.content = decryptedContent;
+        TriggerProxy.trigger(
+          this,
+          {
+            file: 'annotation',
+            function: 'processStrokeMessage',
+          },
+          EVENT_TRIGGERS.ANNOTATION_STROKE_DATA,
+          {
+            payload: request.value,
+          }
+        );
+      }
+    );
+  }
+
+  /** bind all events from mercury
+   * @param {Object} e
+   * @returns {undefined}
+   */
+  private eventCommandProcessor(e) {
+    if (
+      e?.data?.eventType === 'locus.approval_request' &&
+      e?.data?.approval?.resourceType === ANNOTATION_RESOURCE_TYPE &&
+      e?.data?.approval?.actionType
+    ) {
+      TriggerProxy.trigger(
+        this,
+        {
+          file: 'annotation',
+          function: 'approval_request',
+        },
+        EVENT_TRIGGERS.ANNOTATION_COMMAND,
+        {
+          type: e.data.approval.actionType,
+          payload: e.data.approval,
+        }
+      );
+      this.seqNum = (e?.sequenceNumber || 0) + 1;
+    }
+  }
+
+  /** bind all events from llm
+   * @param {Object} e
+   * @returns {undefined}
+   */
+  private eventDataProcessor(e) {
+    switch (e?.data?.relayType) {
+      case ANNOTATION_RELAY_TYPES.ANNOTATION_CLIENT:
+        this.seqNum = (e?.sequenceNumber || 0) + 1;
+        this.processStrokeMessage(e.data.request);
+        break;
+      default:
+        break;
+    }
+  }
+
+  /**
+   * Listen to websocket messages
+   * @returns {undefined}
+   */
+  private listenToEvents() {
+    if (!this.hasSubscribedToEvents) {
+      // @ts-ignore
+      this.webex.internal.mercury.on(
+        'event:locus.approval_request',
+        this.eventCommandProcessor,
+        this
+      );
+      // @ts-ignore
+      this.webex.internal.llm.on('event:relay.event', this.eventDataProcessor, this);
+      this.hasSubscribedToEvents = true;
+    }
+  }
+
+  /**
+   * set locusUrl
+   * @param {string} locusUrl
+   * @returns {void}
+   */
+  public locusUrlUpdate(locusUrl: string) {
+    this.locusUrl = locusUrl;
+    this.listenToEvents();
+  }
+
+  /**
+   * set approved url
+   * @param {string} approvalUrl
+   * @returns {void}
+   */
+  public approvalUrlUpdate(approvalUrl: string) {
+    this.approvalUrl = approvalUrl;
+  }
+
+  /**
+   * accept request
+   * @param {object} approval
+   * @returns {Promise}
+   */
+  public acceptRequest(approval) {
+    // @ts-ignore
+    return this.request({
+      method: HTTP_VERBS.PUT,
+      url: approval.url,
+      body: {
+        resourceType: ANNOTATION_RESOURCE_TYPE,
+        actionType: ANNOTATION_ACTION_TYPE.ACCEPTED,
+      },
+    });
+  }
+
+  /**
+   * presenter declined request annotation
+   * @param {approval} approval
+   * @returns {Promise}
+   */
+  public declineRequest(approval) {
+    // @ts-ignore
+    return this.request({
+      method: HTTP_VERBS.PUT,
+      url: approval.url,
+      body: {
+        resourceType: ANNOTATION_RESOURCE_TYPE,
+        actionType: ANNOTATION_ACTION_TYPE.DECLINED,
+      },
+    });
+  }
+
+  /**
+   * request approved annotation
+   * @param {RequestData} requestData
+   * @returns {Promise}
+   */
+  public approveAnnotation(requestData: RequestData) {
+    return this.sendAnnotationAction(ANNOTATION_ACTION_TYPE.REQUESTED, requestData);
+  }
+
+  /**
+   * cancel approved annotation
+   * @param {object} requestData
+   * @param {object} approval
+   * @returns {Promise}
+   */
+  public cancelApproveAnnotation(requestData: RequestData, approval) {
+    const body: CommandRequestBody = {
+      actionType: ANNOTATION_ACTION_TYPE.CANCELED,
+      resourceType: 'AnnotationOnShare',
+      shareInstanceId: requestData.shareInstanceId,
+    };
+
+    // @ts-ignore
+    return this.request({
+      method: HTTP_VERBS.PUT,
+      url: `${approval.url}`,
+      body,
+    });
+  }
+
+  /**
+   * close annotation
+   * @param {object} requestData
+   * @returns {Promise}
+   */
+  public closeAnnotation(requestData: RequestData) {
+    return this.sendAnnotationAction(ANNOTATION_ACTION_TYPE.CLOSED, requestData);
+  }
+
+  /**
+   * send annotation command
+   * @param {ANNOTATION_ACTION_TYPE} actionType
+   * @param {RequestData} requestData
+   * @returns {Promise}
+   */
+  private sendAnnotationAction = async (
+    actionType: ANNOTATION_ACTION_TYPE,
+    requestData: RequestData
+  ): Promise<void> => {
+    const body: CommandRequestBody = {
+      actionType,
+      resourceType: 'AnnotationOnShare',
+      shareInstanceId: requestData.shareInstanceId,
+    };
+    if (requestData?.toUserId) {
+      body.receivers = [{participantId: requestData.toUserId, deviceUrl: requestData.toDeviceUrl}];
+    }
+
+    // @ts-ignore
+    return this.request({
+      method: HTTP_VERBS.POST,
+      url: `${this.approvalUrl}`,
+      body,
+    });
+  };
+
+  /**
+   * decrypt data
+   * @param {string} encryptionKeyUrl
+   * @param {string} content encrypted content
+   * @returns {string} decrypted content
+   */
+  private decryptContent = (encryptionKeyUrl: string, content: string): Promise<any> => {
+    // @ts-ignore
+    return this.webex.internal.encryption.decryptText(encryptionKeyUrl, content).then((res) => {
+      return res;
+    });
+  };
+
+  /**
+   * encrypt data
+   * @param {string} encryptionKeyUrl
+   * @param {string} content original content
+   * @returns {string} encrypted content
+   */
+  private encryptContent = (encryptionKeyUrl: string, content: string): Promise<any> => {
+    // @ts-ignore
+    return this.webex.internal.encryption.encryptText(encryptionKeyUrl, content).then((res) => {
+      return res;
+    });
+  };
+
+  /**
+   * Sends stroke data to presenter
+   * @param {StrokeData} strokeData
+   * @returns {void}
+   */
+  public sendStrokeData = (strokeData: StrokeData): void => {
+    // @ts-ignore
+    if (!this.webex.internal.llm.isConnected()) return;
+    this.encryptContent(strokeData.encryptionKeyUrl, strokeData.content).then(
+      (encryptedContent) => {
+        this.publishEncrypted(encryptedContent, strokeData);
+      }
+    );
+  };
+
+  /**
+   * Change annotation options
+   * @param {object} options
+   * @param {object} meeting
+   * @returns {Promise}
+   */
+  public changeAnnotationOptions(options, meeting) {
+    return meeting?.meetingRequest.changeMeetingFloor(options);
+  }
+
+  /**
+   * private encrypted the strokes data
+   * @param {string} encryptedContent
+   * @param {StrokeData} strokeData
+   * @returns {void}
+   */
+  private publishEncrypted(encryptedContent: string, strokeData: StrokeData) {
+    const data = {
+      id: `${this.seqNum}`,
+      type: 'publishRequest',
+      recipients: {
+        // @ts-ignore
+        route: this.webex.internal.llm.getBinding(),
+      },
+      headers: {
+        to: strokeData.toUserId,
+      },
+      data: {
+        eventType: 'relay.event',
+        relayType: ANNOTATION_RELAY_TYPES.ANNOTATION_CLIENT,
+        request: {
+          value: {
+            type: ANNOTATION_REQUEST_TYPE.ANNOTATION_MESSAGE,
+            content: encryptedContent,
+            deviceId: strokeData.deviceId,
+            seq: this.seqNum,
+            requesterId: strokeData.requesterId,
+            version: strokeData.version,
+            shareInstanceId: strokeData.shareInstanceId,
+            encryptionKeyUrl: strokeData.encryptionKeyUrl,
+          },
+        },
+      },
+      trackingId: `${config.trackingIdPrefix}_${uuid.v4().toString()}`,
+      timestamp: new Date().getTime(),
+      sequenceNumber: this.seqNum,
+      filterMessage: false,
+    };
+
+    // @ts-ignore
+    this.webex.internal.llm.socket.send(data);
+    this.seqNum += 1;
+  }
+}
+
+export default AnnotationChannel;

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}) => {
+
+})
+
+```