@webex/contact-center 3.11.0 → 3.12.0-auth-prejoin-fetch.1

package/src/services/ApiAiAssistant.ts

@@ -0,0 +1,412 @@
+import {v4 as uuidv4} from 'uuid';
+import LoggerProxy from '../logger-proxy';
+import MetricsManager from '../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../metrics/constants';
+import {CC_FILE, METHODS} from '../constants';
+import {
+  HTTP_METHODS,
+  WebexSDK,
+  IHttpResponse,
+  AIAssistantEventType,
+  AIAssistantEventName,
+  HistoricTranscriptsResponse,
+  RealTimeAssistanceParams,
+  RealTimeAssistanceUserActionParams,
+} from '../types';
+import {getErrorDetails} from './core/Utils';
+import {
+  AI_ASSISTANT_BASE_URL_TEMPLATE,
+  AI_ASSISTANT_ENV_MAP,
+  AI_ASSISTANT_API_URLS,
+  WCC_API_GATEWAY,
+} from './constants';
+import {AIFeatureFlags} from './config/types';
+
+/**
+ * ApiAIAssistant provides AI Assistant APIs for transcript controls.
+ * @public
+ */
+export class ApiAIAssistant {
+  private webex: WebexSDK;
+  private metricsManager: MetricsManager;
+  private aiFeature: AIFeatureFlags;
+
+  constructor(webex: WebexSDK) {
+    this.webex = webex;
+    this.metricsManager = MetricsManager.getInstance({webex});
+  }
+
+  public setAIFeatureFlags(aiFeature: AIFeatureFlags): void {
+    this.aiFeature = aiFeature;
+  }
+
+  private getBaseUrl(): string {
+    const wccApiGatewayUrl = this.webex.internal.services.get(WCC_API_GATEWAY) || '';
+
+    if (!wccApiGatewayUrl) {
+      const {error: detailedError} = getErrorDetails(
+        new Error('AI_ASSISTANT_BASE_URL_NOT_AVAILABLE'),
+        METHODS.GET_BASE_URL,
+        CC_FILE
+      );
+      throw detailedError;
+    }
+
+    let hostname = '';
+    try {
+      hostname = new URL(wccApiGatewayUrl).hostname.toLowerCase();
+    } catch (error) {
+      hostname = wccApiGatewayUrl.toLowerCase();
+    }
+
+    const resolvedEnv = AI_ASSISTANT_ENV_MAP[hostname];
+    if (!resolvedEnv) {
+      const {error: detailedError} = getErrorDetails(
+        new Error('AI_ASSISTANT_BASE_URL_NOT_AVAILABLE'),
+        METHODS.GET_BASE_URL,
+        CC_FILE
+      );
+      throw detailedError;
+    }
+
+    return AI_ASSISTANT_BASE_URL_TEMPLATE.replace('%s', resolvedEnv);
+  }
+
+  /**
+   * Sends an event to the AI Assistant service.
+   * @param agentId - agent identifier
+   * @param interactionId - interaction/conversation identifier
+   * @param eventType - the type of event (e.g. 'CUSTOM_EVENT')
+   * @param eventName - the name of the event (e.g. 'GET_TRANSCRIPTS')
+   * @param eventMetaData - event-specific fields to include in eventDetails.data
+   * @param languageCode - language code within eventDetails.data
+   * @param trackingId - tracking identifier within eventDetails.data
+   */
+  public async sendEvent(
+    agentId: string,
+    interactionId: string,
+    eventType: AIAssistantEventType,
+    eventName: AIAssistantEventName,
+    eventMetaData?: Record<string, unknown>,
+    languageCode?: string,
+    trackingId?: string
+  ): Promise<Record<string, unknown>> {
+    LoggerProxy.info('Sending event', {
+      module: CC_FILE,
+      method: METHODS.SEND_EVENT,
+      interactionId,
+      data: {eventType, eventName, eventMetaData},
+    });
+    this.metricsManager.timeEvent([
+      METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_EVENT_SUCCESS,
+      METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_EVENT_FAILED,
+    ]);
+
+    try {
+      const baseUrl = this.getBaseUrl();
+      const orgId = this.webex.credentials.getOrgId();
+      const response = (await this.webex.request({
+        uri: `${baseUrl}${AI_ASSISTANT_API_URLS.EVENT}`,
+        method: HTTP_METHODS.POST,
+        addAuthHeader: true,
+        body: {
+          agentId,
+          orgId,
+          eventType,
+          eventName,
+          eventDetails: {
+            data: {
+              ...eventMetaData,
+              interactionId,
+              actionTimeStamp: String(Date.now()),
+              languageCode,
+              trackingId,
+            },
+          },
+        },
+      })) as IHttpResponse;
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_EVENT_SUCCESS,
+        {agentId, orgId, interactionId, eventType, eventName},
+        ['operational']
+      );
+
+      return response?.body || {};
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_EVENT_FAILED,
+        {
+          interactionId,
+          eventType,
+          eventName,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        ['operational']
+      );
+
+      const {error: detailedError} = getErrorDetails(error, METHODS.SEND_EVENT, CC_FILE);
+      throw detailedError;
+    }
+  }
+
+  /**
+   * Requests real-time assistance for an interaction.
+   *
+   * @param params - Real-time assistance request parameters
+   * @returns HTTP response body from the AI Assistant event API
+   * @public
+   */
+  public async getRealTimeAssistance(params: RealTimeAssistanceParams) {
+    const {agentId, interactionId, context} = params;
+    const trimmedContext = context?.trim();
+    const languageCode = params.languageCode ?? 'en';
+    const trackingId = `WX_CC_SDK_${uuidv4()}`;
+    const eventName = trimmedContext
+      ? AIAssistantEventName.ADD_SUGGESTIONS_EXTRA_CONTEXT
+      : AIAssistantEventName.GET_SUGGESTIONS;
+
+    const loggerContext = {
+      module: CC_FILE,
+      method: METHODS.GET_REAL_TIME_ASSISTANCE,
+      interactionId,
+      trackingId,
+      data: {eventName},
+    };
+
+    LoggerProxy.info('Requesting real-time assistance', loggerContext);
+
+    this.metricsManager.timeEvent([
+      METRIC_EVENT_NAMES.AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_SUCCESS,
+      METRIC_EVENT_NAMES.AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_FAILED,
+    ]);
+
+    try {
+      if (!this.aiFeature?.suggestedResponses?.enable) {
+        const {error: detailedError} = getErrorDetails(
+          new Error('SUGGESTED_RESPONSES_NOT_ENABLED'),
+          METHODS.GET_REAL_TIME_ASSISTANCE,
+          CC_FILE
+        );
+        throw detailedError;
+      }
+
+      const orgId = this.webex.credentials.getOrgId();
+
+      const response = await this.sendEvent(
+        agentId,
+        interactionId,
+        AIAssistantEventType.CUSTOM_EVENT,
+        eventName,
+        trimmedContext !== undefined ? {context: trimmedContext} : undefined,
+        languageCode,
+        trackingId
+      );
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_SUCCESS,
+        {
+          agentId,
+          orgId,
+          interactionId,
+          eventName,
+          trackingId,
+          context,
+        },
+        ['operational']
+      );
+      LoggerProxy.log('Real-time assistance request succeeded', loggerContext);
+
+      return response;
+    } catch (error) {
+      LoggerProxy.error('Real-time assistance request failed', {...loggerContext, error});
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_GET_REAL_TIME_ASSISTANCE_FAILED,
+        {
+          agentId,
+          interactionId,
+          trackingId,
+          eventName,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        ['operational']
+      );
+
+      const {error: detailedError} = getErrorDetails(
+        error,
+        METHODS.GET_REAL_TIME_ASSISTANCE,
+        CC_FILE
+      );
+      throw detailedError;
+    }
+  }
+
+  /**
+   * Sends user action feedback for a real-time assistance adaptive card.
+   *
+   * @param params - Real-time assistance user action parameters
+   * @returns HTTP response body from the AI Assistant event API
+   * @public
+   */
+  public async sendRealTimeAssistanceUserAction(
+    params: RealTimeAssistanceUserActionParams
+  ): Promise<Record<string, unknown>> {
+    const {agentId, interactionId, adaptiveCardId, actionId} = params;
+    const actionType = 'Action.Submit';
+    const languageCode = params.languageCode ?? 'en';
+    const trackingId = `WX_CC_SDK_${uuidv4()}`;
+
+    const loggerContext = {
+      module: CC_FILE,
+      method: METHODS.SEND_REAL_TIME_ASSISTANCE_USER_ACTION,
+      interactionId,
+      trackingId,
+      data: {actionId, adaptiveCardId},
+    };
+
+    LoggerProxy.info('Sending real-time assistance user action', loggerContext);
+
+    this.metricsManager.timeEvent([
+      METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_SUCCESS,
+      METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_FAILED,
+    ]);
+
+    try {
+      if (!this.aiFeature?.suggestedResponses?.enable) {
+        const {error: detailedError} = getErrorDetails(
+          new Error('SUGGESTED_RESPONSES_NOT_ENABLED'),
+          METHODS.SEND_REAL_TIME_ASSISTANCE_USER_ACTION,
+          CC_FILE
+        );
+        throw detailedError;
+      }
+
+      const orgId = this.webex.credentials.getOrgId();
+      const response = await this.sendEvent(
+        agentId,
+        interactionId,
+        AIAssistantEventType.CUSTOM_EVENT,
+        AIAssistantEventName.SUGGESTED_RESPONSES_USER_ACTION,
+        {
+          adaptiveCardId,
+          userAction: {
+            actionType,
+            actionId,
+          },
+        },
+        languageCode,
+        trackingId
+      );
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_SUCCESS,
+        {
+          agentId,
+          orgId,
+          interactionId,
+          adaptiveCardId,
+          actionId,
+          trackingId,
+        },
+        ['operational']
+      );
+      LoggerProxy.log('Real-time assistance user action sent', loggerContext);
+
+      return response;
+    } catch (error) {
+      LoggerProxy.error('Real-time assistance user action failed', {...loggerContext, error});
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_SEND_REAL_TIME_ASSISTANCE_USER_ACTION_FAILED,
+        {
+          agentId,
+          interactionId,
+          adaptiveCardId,
+          actionId,
+          trackingId,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        ['operational']
+      );
+
+      const {error: detailedError} = getErrorDetails(
+        error,
+        METHODS.SEND_REAL_TIME_ASSISTANCE_USER_ACTION,
+        CC_FILE
+      );
+      throw detailedError;
+    }
+  }
+
+  /**
+   * Fetches historic transcripts for an interaction.
+   * This API is allowed only when real-time transcription feature is enabled.
+   *
+   * @param interactionId - interaction/conversation identifier
+   */
+  public async fetchHistoricTranscripts(
+    agentId: string,
+    interactionId: string
+  ): Promise<HistoricTranscriptsResponse> {
+    LoggerProxy.info('Fetching historic transcripts', {
+      module: CC_FILE,
+      method: METHODS.FETCH_HISTORIC_TRANSCRIPTS,
+      interactionId,
+    });
+    this.metricsManager.timeEvent([
+      METRIC_EVENT_NAMES.AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS,
+      METRIC_EVENT_NAMES.AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED,
+    ]);
+    if (!this.aiFeature?.realtimeTranscripts?.enable) {
+      const {error: detailedError} = getErrorDetails(
+        new Error('REAL_TIME_TRANSCRIPTION_NOT_ENABLED'),
+        METHODS.FETCH_HISTORIC_TRANSCRIPTS,
+        CC_FILE
+      );
+      throw detailedError;
+    }
+
+    try {
+      const baseUrl = this.getBaseUrl();
+      const orgId = this.webex.credentials.getOrgId();
+      const response = (await this.webex.request({
+        uri: `${baseUrl}${AI_ASSISTANT_API_URLS.TRANSCRIPTS_LIST}`,
+        method: HTTP_METHODS.POST,
+        addAuthHeader: true,
+        body: {
+          agentId,
+          orgId,
+          interactionId,
+        },
+      })) as IHttpResponse;
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_SUCCESS,
+        {agentId, orgId, interactionId},
+        ['operational']
+      );
+
+      return response.body as HistoricTranscriptsResponse;
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.AI_ASSISTANT_FETCH_HISTORIC_TRANSCRIPTS_FAILED,
+        {
+          interactionId,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        ['operational']
+      );
+
+      if (error instanceof Error) {
+        throw error;
+      }
+      const {error: detailedError} = getErrorDetails(
+        error,
+        METHODS.FETCH_HISTORIC_TRANSCRIPTS,
+        CC_FILE
+      );
+      throw detailedError;
+    }
+  }
+}
+
+export default ApiAIAssistant;

package/src/services/EntryPoint.ts

@@ -2,12 +2,40 @@ import {HTTP_METHODS, WebexSDK} from '../types';
 import type {EntryPointRecord, EntryPointListResponse, EntryPointSearchParams} from '../types';
 import LoggerProxy from '../logger-proxy';
 import WebexRequest from './core/WebexRequest';
-import PageCache, {PAGINATION_DEFAULTS} from '../utils/PageCache';
+import {PAGINATION_DEFAULTS} from '../utils/PageCache';
 import MetricsManager from '../metrics/MetricsManager';
 import {WCC_API_GATEWAY} from './constants';
 import {endPointMap} from './config/constants';
 import {METRIC_EVENT_NAMES} from '../metrics/constants';
 
+const DEFAULT_ENTRY_POINT_ATTRIBUTES = 'id,dialledNumber,entryPointId,entryPointName';
+const DEFAULT_ENTRY_POINT_SORT_FIELD = 'entryPointName';
+
+type DialNumberEntryPointRecord = {
+  id: string;
+  dialledNumber?: string;
+  entryPointId: string;
+  entryPointName: string;
+};
+
+const mergeEntryPointAttributes = (attributes?: string): string => {
+  const mergedAttributes = new Set(DEFAULT_ENTRY_POINT_ATTRIBUTES.split(','));
+
+  attributes
+    ?.split(',')
+    .map((attribute) => attribute.trim())
+    .filter(Boolean)
+    .forEach((attribute) => mergedAttributes.add(attribute));
+
+  return Array.from(mergedAttributes).join(',');
+};
+
+const mapDialNumberEntryPoint = (item: DialNumberEntryPointRecord): EntryPointRecord => ({
+  id: item.entryPointId,
+  name: item.entryPointName,
+  ...(item.dialledNumber ? {number: item.dialledNumber} : {}),
+});
+
 /**
  * EntryPoint class for managing Webex Contact Center entry points.
  * Provides functionality to fetch, search, and paginate through entry points.
@@ -35,7 +63,7 @@ import {METRIC_EVENT_NAMES} from '../metrics/constants';
  * });
  *
  * // Search for specific entry points
- * const searchResults = await entryPointAPI.searchEntryPoints({
+ * const searchResults = await entryPointAPI.getEntryPoints({
  *   search: 'support',
  *   filter: 'type=="voice"'
  * });
@@ -46,9 +74,6 @@ export class EntryPoint {
   private webex: WebexSDK;
   private metricsManager: MetricsManager;
 
-  // Page cache using the common utility
-  private pageCache: PageCache<EntryPointRecord>;
-
   /**
    * Creates an instance of EntryPoint
    * @param {WebexSDK} webex - The Webex SDK instance
@@ -57,19 +82,21 @@ export class EntryPoint {
   constructor(webex: WebexSDK) {
     this.webex = webex;
     this.webexRequest = WebexRequest.getInstance({webex});
-    this.pageCache = new PageCache<EntryPointRecord>('EntryPoint');
     this.metricsManager = MetricsManager.getInstance({webex});
   }
 
   /**
-   * Fetches entry points for the organization with pagination support
-   * @param {EntryPointSearchParams} [params] - Search and pagination parameters
+   * Fetches entry-point dial-number mappings for the organization with pagination support. By
+   * default, returns the agent's desktop-profile-filtered mappings in backend entry-point-name order.
+   * Search, filter, attribute, and sort parameters can customize the request while desktop-profile
+   * scoping and required mapping fields remain SDK-owned.
+   * @param {EntryPointSearchParams} [params] - Search, pagination, and compatible override parameters.
    * @returns {Promise<EntryPointListResponse>} Promise resolving to paginated entry points
    * @throws {Error} If the API call fails
    * @public
    * @example
    * ```typescript
-   * // Get first page of entry points
+   * // Get the first page using the default entry-point policy
    * const response = await entryPointAPI.getEntryPoints();
    *
    * // Get specific page with custom page size
@@ -89,12 +116,14 @@ export class EntryPoint {
       search,
       filter,
       attributes,
-      sortBy,
+      sortBy = 'name',
       sortOrder = 'asc',
     } = params;
 
     const orgId = this.webex.credentials.getOrgId();
-    const isSearchRequest = !!(search || filter || attributes || sortBy);
+    const hasCustomSort = sortBy !== 'name' || sortOrder !== 'asc';
+    const isSearchRequest = !!(search || filter || attributes || hasCustomSort);
+    const effectiveSortBy = sortBy === 'name' ? DEFAULT_ENTRY_POINT_SORT_FIELD : sortBy;
 
     LoggerProxy.info(
       `Fetching entry points - orgId: ${orgId}, page: ${page}, pageSize: ${pageSize}, isSearchRequest: ${isSearchRequest}`,
@@ -104,51 +133,24 @@ export class EntryPoint {
       }
     );
 
-    // Check if we can use cache for simple pagination (no search/filter/attributes/sort)
-    if (this.pageCache.canUseCache({search, filter, attributes, sortBy})) {
-      const cacheKey = this.pageCache.buildCacheKey(orgId, page, pageSize);
-      const cachedPage = this.pageCache.getCachedPage(cacheKey);
-
-      if (cachedPage) {
-        const duration = Date.now() - startTime;
-
-        LoggerProxy.log(
-          `Returning page ${page} from cache - cacheHit: true, duration: ${duration}ms, recordCount: ${cachedPage.data.length}, pageSize: ${pageSize}`,
-          {
-            module: 'EntryPoint',
-            method: 'getEntryPoints',
-          }
-        );
-
-        return {
-          data: cachedPage.data,
-          meta: {
-            page,
-            pageSize,
-            totalPages: cachedPage.totalMeta?.totalPages,
-            totalRecords: cachedPage.totalMeta?.totalRecords,
-          },
-        };
-      }
-    }
-
-    // Start timing only for actual API calls (not cache hits)
     this.metricsManager.timeEvent(METRIC_EVENT_NAMES.ENTRYPOINT_FETCH_SUCCESS);
 
     try {
-      // Build query parameters
       const queryParams = new URLSearchParams({
         page: page.toString(),
         pageSize: pageSize.toString(),
-        sortOrder,
+        attributes: mergeEntryPointAttributes(attributes),
       });
 
       if (search) queryParams.append('search', search);
       if (filter) queryParams.append('filter', filter);
-      if (attributes) queryParams.append('attributes', attributes);
-      if (sortBy) queryParams.append('sortBy', sortBy);
+      if (effectiveSortBy) {
+        queryParams.append('sort', `${effectiveSortBy},${sortOrder.toUpperCase()}`);
+      }
+      queryParams.append('desktopProfileFilter', 'true');
+      queryParams.append('includeEntryPointName', 'true');
 
-      const resource = endPointMap.entryPointList(orgId, queryParams.toString());
+      const resource = endPointMap.entryPointDialNumberList(orgId, queryParams.toString());
 
       LoggerProxy.log(
         `Making API request to fetch entry points - resource: ${resource}, service: ${WCC_API_GATEWAY}`,
@@ -162,12 +164,21 @@ export class EntryPoint {
         service: WCC_API_GATEWAY,
         resource,
         method: HTTP_METHODS.GET,
+        headers: {
+          'X-ORGANIZATION-ID': orgId,
+          'x-ignore-internal-data': 'false',
+        },
       });
 
+      const responseBody: EntryPointListResponse = {
+        ...response.body,
+        data: (response.body?.data ?? []).map(mapDialNumberEntryPoint),
+      };
+
       const duration = Date.now() - startTime;
 
-      const recordCount = response.body?.data?.length || 0;
-      const totalRecords = response.body?.meta?.totalRecords;
+      const recordCount = responseBody.data.length;
+      const totalRecords = responseBody.meta?.totalRecords;
 
       LoggerProxy.log(`Successfully retrieved ${recordCount} entry points`, {
         module: 'EntryPoint',
@@ -199,19 +210,7 @@ export class EntryPoint {
         );
       }
 
-      // Cache the page data for simple pagination (no search/filter/attributes/sort)
-      if (this.pageCache.canUseCache({search, filter, attributes, sortBy}) && response.body?.data) {
-        const cacheKey = this.pageCache.buildCacheKey(orgId, page, pageSize);
-        this.pageCache.cachePage(cacheKey, response.body.data, response.body.meta);
-
-        LoggerProxy.log('Cached entry points data for future requests', {
-          module: 'EntryPoint',
-          method: 'getEntryPoints',
-          data: {cacheKey, recordCount},
-        });
-      }
-
-      return response.body;
+      return responseBody;
     } catch (error) {
       const errorData = {
         orgId,