feat(meetings): add site preferences API (#4955)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: chrisadubois

packages/@webex/plugin-meetings/src/config.ts

@@ -82,6 +82,7 @@ export default {
     enableExtmap: false,
     enableAutomaticLLM: false,
     installedOrgID: undefined,
+    multipartSitePrefixList: ['.my.', '.mydmz.', '.mybts.', '.mydev.', '.myats2.', '.myats.'],
     experimental: {
       enableMediaNegotiatedEvent: false,
       enableUnifiedMeetings: true,

packages/@webex/plugin-meetings/src/index.ts

@@ -65,6 +65,11 @@ export * as REACTIONS from './reactions/reactions';
 export * as sdkAnnotationTypes from './annotation/annotation.types';
 export * as MeetingInfoV2 from './meeting-info/meeting-info-v2';
 export {type Reaction} from './reactions/reactions.type';
+export {SitePreferenceSelectOption} from './meetings/meetings.types';
+export type {
+  FetchSitePreferencesMeViaSiteOptions,
+  SitePreferencesResponse,
+} from './meetings/meetings.types';
 
 export {
   CaptchaError,

packages/@webex/plugin-meetings/src/meetings/index.ts

@@ -55,10 +55,12 @@ import PasswordError from '../common/errors/password-error';
 import CaptchaError from '../common/errors/captcha-error';
 import MeetingCollection from './collection';
 import {
+  FetchSitePreferencesMeViaSiteOptions,
   MEETING_KEY,
   INoiseReductionEffect,
   IVirtualBackgroundEffect,
   MeetingRegistrationStatus,
+  SitePreferencesResponse,
 } from './meetings.types';
 import MeetingsUtil from './util';
 import PermissionError from '../common/errors/permission';
@@ -1405,6 +1407,31 @@ export default class Meetings extends WebexPlugin {
     return this.personalMeetingRoom;
   }
 
+  /**
+   * Fetches site preferences for the provided Webex site, or the preferred Webex site.
+   * This is used to determine capabilities of the site, such as whether scheduling a webinar is supported.
+   *
+   * @param {object} [options]
+   * @param {string} [options.siteUrl] - Webex site URL. Defaults to preferredWebexSite, for example "cisco.webex.com".
+   * @param {string} [options.siteName] - Site name query override. Defaults to the site name derived from siteUrl, for example "cisco" for "cisco.webex.com".
+   * @param {SitePreferenceSelectOption[]} [options.selectOptions] - Preference sections to fetch. Defaults to 'scheduling'.
+   * @returns {Promise<SitePreferencesResponse>} site preferences response body
+   * @throws {ParameterError}
+   * @public
+   * @memberof Meetings
+   * @example
+   * const preferences = await webex.meetings.fetchSitePreferencesMeViaSite();
+   * const supportScheduleWebinar = preferences?.scheduling?.supportScheduleWebinar;
+   */
+  public fetchSitePreferencesMeViaSite(
+    options: FetchSitePreferencesMeViaSiteOptions = {}
+  ): Promise<SitePreferencesResponse> {
+    return this.request.fetchSitePreferencesMeViaSite({
+      ...options,
+      siteUrl: options.siteUrl || this.preferredWebexSite,
+    });
+  }
+
   /**
    * Returns basic information about a meeting that exists or
    * used to exist in the MeetingCollection

packages/@webex/plugin-meetings/src/meetings/meetings.types.ts

@@ -31,3 +31,22 @@ export type MeetingRegistrationStatus = {
   mercuryConnect: boolean;
   checkH264Support: boolean;
 };
+
+export enum SitePreferenceSelectOption {
+  SCHEDULING = 'scheduling',
+}
+
+export type FetchSitePreferencesMeViaSiteOptions = {
+  siteUrl?: string;
+  siteName?: string;
+  selectOptions?: SitePreferenceSelectOption[];
+};
+
+export const DEFAULT_SITE_PREFERENCE_SELECT_OPTIONS = [SitePreferenceSelectOption.SCHEDULING];
+
+export type SitePreferencesResponse = {
+  scheduling?: {
+    supportScheduleWebinar?: boolean;
+    webinarWebLink?: string;
+  };
+};

packages/@webex/plugin-meetings/src/meetings/request.ts

@@ -2,7 +2,14 @@
 import {StatelessWebexPlugin} from '@webex/webex-core';
 
 import LoggerProxy from '../common/logs/logger-proxy';
+import ParameterError from '../common/errors/parameter';
 import {HTTP_VERBS, API, RESOURCE} from '../constants';
+import {
+  DEFAULT_SITE_PREFERENCE_SELECT_OPTIONS,
+  type FetchSitePreferencesMeViaSiteOptions,
+  type SitePreferencesResponse,
+} from './meetings.types';
+import MeetingsUtil from './util';
 
 /**
  * @class MeetingRequest
@@ -45,6 +52,42 @@ export default class MeetingRequest extends StatelessWebexPlugin {
     return this.webex.internal.services.getMeetingPreferences();
   }
 
+  /**
+   * Fetches site preferences from a given site given a select option and a siteUrl with an optional siteName. If siteName is not provided, it will be derived from the siteUrl. If siteUrl is not provided, it will throw an error. If selectOptions is not provided, it will default to scheduling.
+   *
+   * @param {object} [options]
+   * @param {string} [options.siteUrl] - Webex site URL, for example "cisco.webex.com".
+   * @param {string} [options.siteName] - Site name query override. Defaults to the site name derived from options.siteUrl, e.g., "cisco".
+   * @param {SitePreferenceSelectOption[]} [options.selectOptions] - Preference sections to fetch. Defaults to 'scheduling'.
+   * @returns {Promise<SitePreferencesResponse>} site preferences response body
+   * @throws {ParameterError}
+   * @public
+   * @memberof MeetingRequest
+   */
+  fetchSitePreferencesMeViaSite(
+    options: FetchSitePreferencesMeViaSiteOptions = {}
+  ): Promise<SitePreferencesResponse> {
+    const {siteUrl, selectOptions = DEFAULT_SITE_PREFERENCE_SELECT_OPTIONS} = options;
+
+    if (!siteUrl) {
+      throw new ParameterError(
+        'No siteUrl available. Call register() before fetching site preferences or provide options.siteUrl.'
+      );
+    }
+
+    // @ts-ignore - config comes from registerPlugin
+    const multipartSitePrefixList = this.config.meetings.multipartSitePrefixList || [];
+    const siteName = options.siteName || MeetingsUtil.getSiteName(siteUrl, multipartSitePrefixList);
+
+    // @ts-ignore
+    return this.request({
+      method: HTTP_VERBS.GET,
+      uri: `https://${siteUrl}/wbxappapi/v1/users/me/preference?select=${encodeURIComponent(
+        selectOptions.join(',')
+      )}&siteurl=${encodeURIComponent(siteName)}`,
+    }).then((res: any) => res.body);
+  }
+
   // locus federation, determines and populate locus if the responseBody has remote URLs to fetch locus details
 
   /**

packages/@webex/plugin-meetings/src/meetings/util.ts

@@ -153,6 +153,30 @@ MeetingsUtil.parseDefaultSiteFromMeetingPreferences = (userPreferences) => {
   return result;
 };
 
+MeetingsUtil.getSiteName = (site: string, multipartSitePrefixList: string[] = []) => {
+  if (!site) {
+    return null;
+  }
+
+  let siteName: string | undefined;
+
+  multipartSitePrefixList.forEach((multipartSitePrefix) => {
+    if (!siteName && site.includes(multipartSitePrefix)) {
+      const secondDot = site.indexOf('.', site.indexOf('.') + 1);
+
+      siteName = site.substring(0, secondDot);
+    }
+  });
+
+  if (siteName) {
+    return siteName;
+  }
+
+  siteName = site.substring(0, site.indexOf('.'));
+
+  return siteName;
+};
+
 /**
  * Will check to see if the H.264 media codec is supported.
  * @async

packages/@webex/plugin-meetings/test/unit/spec/meetings/index.js

@@ -14,12 +14,14 @@ import StaticConfig from '@webex/plugin-meetings/src/common/config';
 import TriggerProxy from '@webex/plugin-meetings/src/common/events/trigger-proxy';
 import LoggerProxy from '@webex/plugin-meetings/src/common/logs/logger-proxy';
 import LoggerConfig from '@webex/plugin-meetings/src/common/logs/logger-config';
+import ParameterError from '@webex/plugin-meetings/src/common/errors/parameter';
 import Meeting, {CallStateForMetrics} from '@webex/plugin-meetings/src/meeting';
 import {Services} from '@webex/webex-core';
 import MeetingUtil from '@webex/plugin-meetings/src/meeting/util';
 import Meetings from '@webex/plugin-meetings/src/meetings';
 import MeetingCollection from '@webex/plugin-meetings/src/meetings/collection';
 import MeetingsUtil from '@webex/plugin-meetings/src/meetings/util';
+import {SitePreferenceSelectOption} from '@webex/plugin-meetings/src/meetings/meetings.types';
 import PersonalMeetingRoom from '@webex/plugin-meetings/src/personal-meeting-room';
 import Reachability from '@webex/plugin-meetings/src/reachability';
 import Metrics from '@webex/plugin-meetings/src/metrics';
@@ -1356,6 +1358,87 @@ describe('plugin-meetings', () => {
             );
           });
         });
+        describe('#fetchSitePreferencesMeViaSite', () => {
+          const sitePreferencesResponse = {
+            scheduling: {
+              supportScheduleWebinar: true,
+              webinarWebLink: 'https://go.webex.com/webappng/sites/go/webinar/scheduler',
+            },
+          };
+
+          beforeEach(() => {
+            webex.meetings.request.fetchSitePreferencesMeViaSite = sinon
+              .stub()
+              .resolves(sitePreferencesResponse);
+          });
+
+          it('should have #fetchSitePreferencesMeViaSite', () => {
+            assert.exists(webex.meetings.fetchSitePreferencesMeViaSite);
+          });
+
+          it('fetches scheduling preferences for the preferred Webex site by default', async () => {
+            webex.meetings.preferredWebexSite = 'go.webex.com';
+
+            const result = await webex.meetings.fetchSitePreferencesMeViaSite();
+
+            assert.deepEqual(result, sitePreferencesResponse);
+            assert.calledOnceWithExactly(
+              webex.meetings.request.fetchSitePreferencesMeViaSite,
+              {
+                siteUrl: 'go.webex.com',
+              }
+            );
+          });
+
+          it('uses the provided Webex site instead of the preferred Webex site', async () => {
+            webex.meetings.preferredWebexSite = 'preferred.webex.com';
+
+            await webex.meetings.fetchSitePreferencesMeViaSite({siteUrl: 'go.webex.com'});
+
+            assert.calledOnceWithExactly(
+              webex.meetings.request.fetchSitePreferencesMeViaSite,
+              {
+                siteUrl: 'go.webex.com',
+              }
+            );
+          });
+
+          it('forwards custom site name and preference sections to the request helper', async () => {
+            webex.meetings.preferredWebexSite = 'go.webex.com';
+
+            await webex.meetings.fetchSitePreferencesMeViaSite({
+              siteName: 'custom-site',
+              selectOptions: [SitePreferenceSelectOption.SCHEDULING],
+            });
+
+            assert.calledOnceWithExactly(
+              webex.meetings.request.fetchSitePreferencesMeViaSite,
+              {
+                siteUrl: 'go.webex.com',
+                siteName: 'custom-site',
+                selectOptions: [SitePreferenceSelectOption.SCHEDULING],
+              }
+            );
+          });
+
+          it('throws when no Webex site is available', () => {
+            webex.meetings.preferredWebexSite = '';
+            webex.meetings.request.fetchSitePreferencesMeViaSite.throws(
+              new ParameterError(
+                'No siteUrl available. Call register() before fetching site preferences or provide options.siteUrl.'
+              )
+            );
+
+            assert.throws(
+              () => webex.meetings.fetchSitePreferencesMeViaSite(),
+              ParameterError,
+              'No siteUrl available. Call register() before fetching site preferences or provide options.siteUrl.'
+            );
+            assert.calledOnceWithExactly(webex.meetings.request.fetchSitePreferencesMeViaSite, {
+              siteUrl: '',
+            });
+          });
+        });
         describe('Static shortcut proxy methods', () => {
           describe('MeetingCollection getByKey proxies', () => {
             beforeEach(() => {