@webex/plugin-meetings 3.12.0-next.9 → 3.12.0-next.91

package/src/controls-options-manager/index.ts

@@ -1,10 +1,10 @@
 import {camelCase} from 'lodash';
+import ParameterError from '../common/errors/parameter';
 import PermissionError from '../common/errors/permission';
-import {CONTROLS, HTTP_VERBS} from '../constants';
 import MeetingRequest from '../meeting/request';
 import LoggerProxy from '../common/logs/logger-proxy';
 import {Control, Setting} from './enums';
-import {ControlConfig} from './types';
+import {ControlConfig, ViewTheParticipantListProperties} from './types';
 import Util from './util';
 import {CAN_SET, CAN_UNSET, ENABLED} from './constants';
 
@@ -56,6 +56,10 @@ export default class ControlsOptionsManager {
    */
   private mainLocusUrl: string;
 
+  private getControls: () => Record<string, any> = () => ({});
+
+  private isWebinar: () => boolean = () => false;
+
   /**
    * @param {MeetingRequest} request
    * @param {Object} options
@@ -67,6 +71,8 @@ export default class ControlsOptionsManager {
     options?: {
       locusUrl: string;
       displayHints?: Array<string>;
+      getControls?: () => Record<string, any>;
+      isWebinar?: () => boolean;
     }
   ) {
     this.initialize(request);
@@ -89,7 +95,12 @@ export default class ControlsOptionsManager {
    * @public
    * @memberof ControlsOptionsManager
    */
-  public set(options?: {locusUrl: string; displayHints?: Array<string>}) {
+  public set(options?: {
+    locusUrl: string;
+    displayHints?: Array<string>;
+    getControls?: () => Record<string, any>;
+    isWebinar?: () => boolean;
+  }) {
     this.extract(options);
   }
 
@@ -141,9 +152,20 @@ export default class ControlsOptionsManager {
    * @private
    * @memberof ControlsOptionsManager
    */
-  private extract(options?: {locusUrl: string; displayHints?: Array<string>}) {
+  private extract(options?: {
+    locusUrl: string;
+    displayHints?: Array<string>;
+    getControls?: () => Record<string, any>;
+    isWebinar?: () => boolean;
+  }) {
     this.setDisplayHints(options?.displayHints);
     this.setLocusUrl(options?.locusUrl);
+    if (options?.getControls) {
+      this.getControls = options.getControls;
+    }
+    if (options?.isWebinar) {
+      this.isWebinar = options.isWebinar;
+    }
   }
 
   /**
@@ -153,6 +175,12 @@ export default class ControlsOptionsManager {
    * @returns {Promise<Array<any>>}- Promise resolving if the request was successful.
    */
   public update(...controls: Array<ControlConfig>) {
+    if (!this.locusUrl) {
+      return Promise.reject(
+        new ParameterError('The associated locusUrl for update() controls must be defined.')
+      );
+    }
+
     const payloads = controls.map((control) => {
       if (!Object.keys(Control).includes(control.scope)) {
         throw new Error(
@@ -166,25 +194,33 @@ export default class ControlsOptionsManager {
         );
       }
 
+      let {properties} = control;
+
+      if (control.scope === Control.viewTheParticipantList) {
+        const props = properties as ViewTheParticipantListProperties;
+        const current = this.getControls()?.viewTheParticipantList;
+        properties = {
+          enabled: props.enabled ?? current?.enabled ?? false,
+          ...(this.isWebinar() && {
+            panelistEnabled: props.panelistEnabled ?? current?.panelistEnabled ?? false,
+            attendeeCount: props.attendeeCount ?? Boolean(current?.attendeeCount) ?? false,
+          }),
+        };
+      }
+
       return {
-        [control.scope]: control.properties,
+        [control.scope]: properties,
       };
     });
 
     return payloads.reduce((previous, payload) => {
-      const extraBody =
-        this.mainLocusUrl && this.mainLocusUrl !== this.locusUrl
-          ? {authorizingLocusUrl: this.locusUrl}
-          : {};
-
-      return previous.then(() =>
-        // @ts-ignore
-        this.request.request({
-          uri: `${this.mainLocusUrl || this.locusUrl}/${CONTROLS}`,
-          body: {...payload, ...extraBody},
-          method: HTTP_VERBS.PATCH,
-        })
-      );
+      const requestParams = Util.getControlsRequestParams({
+        body: payload,
+        locusUrl: this.locusUrl,
+        mainLocusUrl: this.mainLocusUrl,
+      });
+
+      return previous.then(() => this.sendControlsRequest(requestParams));
     }, Promise.resolve());
   }
 
@@ -200,6 +236,12 @@ export default class ControlsOptionsManager {
     [Setting.muteOnEntry]?: boolean;
     [Setting.roles]?: Array<string>;
   }): Promise<any> {
+    if (!this.locusUrl) {
+      return Promise.reject(
+        new ParameterError('The associated locusUrl for setControls() must be defined.')
+      );
+    }
+
     LoggerProxy.logger.log(
       `ControlsOptionsManager:index#setControls --> ${JSON.stringify(setting)}`
     );
@@ -258,17 +300,34 @@ export default class ControlsOptionsManager {
     if (error) {
       return Promise.reject(error);
     }
-    const extraBody =
-      this.mainLocusUrl && this.mainLocusUrl !== this.locusUrl
-        ? {authorizingLocusUrl: this.locusUrl}
-        : {};
-
-    // @ts-ignore
-    return this.request.request({
-      uri: `${this.mainLocusUrl || this.locusUrl}/${CONTROLS}`,
-      body: {...body, ...extraBody},
-      method: HTTP_VERBS.PATCH,
+
+    const requestParams = Util.getControlsRequestParams({
+      body,
+      locusUrl: this.locusUrl,
+      mainLocusUrl: this.mainLocusUrl,
     });
+
+    return this.sendControlsRequest(requestParams);
+  }
+
+  /**
+   * Sends a controls request to Locus. When authorizingLocusUrl is present in the body,
+   * we use a plain request() because the response contains the main session Locus DTO
+   * instead of the breakout we're in, so we don't want to parse it as a delta.
+   * Otherwise we use locusDeltaRequest() for normal delta processing.
+   *
+   * @param {Object} requestParams - The request parameters from getControlsRequestParams.
+   * @returns {Promise<any>}
+   */
+  private sendControlsRequest(requestParams: {
+    uri: string;
+    body: Record<string, any>;
+    method: string;
+  }): Promise<any> {
+    return requestParams.body.authorizingLocusUrl
+      ? // @ts-ignore
+        this.request.request(requestParams)
+      : this.request.locusDeltaRequest(requestParams);
   }
 
   /**

package/src/controls-options-manager/util.ts

@@ -1,5 +1,6 @@
-import {DISPLAY_HINTS} from '../constants';
+import {CONTROLS, DISPLAY_HINTS, HTTP_VERBS} from '../constants';
 import {Control} from './enums';
+import {AUDIO_CONTROL_BODY_KEYS} from './constants';
 import {
   ControlConfig,
   AudioProperties,
@@ -400,6 +401,85 @@ class Utils {
 
     return determinant;
   }
+
+  /**
+   * Check if all body keys represent audio controls.
+   *
+   * @param {Record<string, any>} body - The request body to inspect.
+   * @returns {boolean} - True if every key in the body is an audio control key.
+   */
+  public static isAudioControl(body: Record<string, any>): boolean {
+    return Object.keys(body).every((key) => AUDIO_CONTROL_BODY_KEYS.has(key));
+  }
+
+  /**
+   * Check if the current locus URL differs from the main locus URL,
+   * indicating a breakout session.
+   *
+   * @param {string} locusUrl - The current locus URL.
+   * @param {string} [mainLocusUrl] - The main locus URL.
+   * @returns {boolean} - True if in a breakout session.
+   */
+  public static isBreakoutLocusUrl(locusUrl: string, mainLocusUrl?: string): boolean {
+    return Boolean(mainLocusUrl) && mainLocusUrl !== locusUrl;
+  }
+
+  /**
+   * Resolve the target URL and extra body fields for a controls request,
+   * handling breakout session routing. Note: This is a pure computation function.
+   * It does not validate that locusUrl is
+   * defined. Callers must guard against falsy locusUrl before
+   * invoking this function.
+   * Mixed audio and non-audio keys in a single body (e.g., {audio: {...},
+   * raiseHand: {...}}) are treated as non-audio and routed to mainLocusUrl with
+   * authorizingLocusUrl. This means the audio portion would go through unsupported
+   * cross-locus authorization. Callers must not produce mixed payloads — update()
+   * sends each control scope as a separate request, and setControls() only handles
+   * audio-related settings.
+   *
+   * The authorizingLocusUrl mechanism on PATCH /loci/{lid}/controls is not supported
+   * for audio control updates (mute/unmute, muteOnEntry, disallowUnmute).
+   * Audio controls are not wired into the cross-locus GraphQL authorization path that
+   * other control types (raiseHand, viewParticipantList, admit, reactions, etc.) use.
+   * Specifically, the GraphQL authorization layer does not recognize audio as a control
+   * type eligible for remote locus authorization.
+   * This means authorizingLocusUrl is effectively ignored for audio controls and the
+   * server evaluates the request against the target locus only, where the host may not
+   * be currently joined.
+   * Audio control updates must be sent directly to the locus the user is currently in.
+   * If the host is in a breakout and wants to mute participants in that breakout, the
+   * request should target the breakout locus URL directly, not the main session locus
+   * with authorizingLocusUrl.
+   * Meeting-wide audio control actions (e.g., muting panelists across all breakouts
+   * from a single request) are not currently supported through this mechanism.
+   *
+   * @param {object} options
+   * @param {Record<string, any>} options.body - The request body.
+   * @param {string} options.locusUrl - The current locus URL. Must be defined (callers must validate).
+   * @param {string} [options.mainLocusUrl] - The main locus URL.
+   * @returns {{ uri: string, body: Record<string, any>, method: string }}
+   */
+  public static getControlsRequestParams(options: {
+    body: Record<string, any>;
+    locusUrl: string;
+    mainLocusUrl?: string;
+  }): {
+    uri: string;
+    body: Record<string, any>;
+    method: string;
+  } {
+    const {body, locusUrl, mainLocusUrl} = options;
+
+    const isAudio = Utils.isAudioControl(body);
+    const inBreakout = Utils.isBreakoutLocusUrl(locusUrl, mainLocusUrl);
+    const targetUrl = inBreakout && !isAudio ? mainLocusUrl : locusUrl;
+
+    return {
+      uri: `${targetUrl}/${CONTROLS}`,
+      body: inBreakout && !isAudio ? {...body, authorizingLocusUrl: locusUrl} : body,
+      method: HTTP_VERBS.PATCH,
+    };
+  }
 }
 
 export default Utils;

package/src/hashTree/constants.ts

@@ -8,3 +8,19 @@ export const DataSetNames = {
   SELF: 'self', // sent to web client, over Mercury
   UNJOINED: 'unjoined', // sent when you are not joined, but can still see some stuff from the meeting (mutually exclusive with "main")
 };
+
+// Priority order for initializing data sets — higher priority names come first.
+// Data sets not listed here will be initialized after all prioritized ones.
+// MAIN must come before SELF because LocusInfo.updateFromHashTree processes the
+// batch of updatedObjects in order, and the SELF handler in updateLocusFromHashTreeObject
+// checks locus.info?.isWebinar (which comes from MAIN) to decide whether to create a
+// participant object for webinar attendees. If SELF were initialized first, locus.info
+// would not yet be populated and the attendee participant would be skipped.
+export const DATA_SET_INIT_PRIORITY: string[] = [DataSetNames.MAIN, DataSetNames.SELF];
+
+// Data sets for which we normally receive events over LLM connection
+export const LLM_DATASET_NAMES = [
+  DataSetNames.MAIN,
+  DataSetNames.ATD_ACTIVE,
+  DataSetNames.ATD_UNMUTED,
+];