@webex/contact-center 3.8.1 → 3.9.0-next.10

package/src/services/Queue.ts

@@ -0,0 +1,277 @@
+import {HTTP_METHODS, WebexSDK} from '../types';
+import type {
+  ContactServiceQueue,
+  ContactServiceQueuesResponse,
+  ContactServiceQueueSearchParams,
+} from '../types';
+import LoggerProxy from '../logger-proxy';
+import WebexRequest from './core/WebexRequest';
+import PageCache, {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';
+import {METHODS} from '../constants';
+
+/**
+ * Queue API class for managing Webex Contact Center contact service queues.
+ * Provides functionality to fetch contact service queues using the queue API.
+ *
+ * @class Queue
+ * @public
+ * @example
+ * ```typescript
+ * import Webex from 'webex';
+ *
+ * const webex = new Webex({ credentials: 'YOUR_ACCESS_TOKEN' });
+ * const cc = webex.cc;
+ *
+ * // Register and login first
+ * await cc.register();
+ * await cc.stationLogin({ teamId: 'team123', loginOption: 'BROWSER' });
+ *
+ * // Get Queue API instance from ContactCenter
+ * const queueAPI = cc.queue;
+ *
+ * // Get all queues
+ * const queues = await queueAPI.getQueues();
+ *
+ * // Get queues with pagination
+ * const queues = await queueAPI.getQueues({
+ *   page: 0,
+ *   pageSize: 50
+ * });
+ *
+ * // Search for specific queues
+ * const searchResults = await queueAPI.getQueues({
+ *   search: 'support',
+ *   filter: 'name=="Support Queue"'
+ * });
+ * ```
+ */
+export class Queue {
+  private webexRequest: WebexRequest;
+  private webex: WebexSDK;
+  private metricsManager: MetricsManager;
+
+  // Page cache using the common utility
+  private pageCache: PageCache<ContactServiceQueue>;
+
+  /**
+   * Creates an instance of Queue
+   * @param {WebexSDK} webex - The Webex SDK instance
+   * @public
+   */
+  constructor(webex: WebexSDK) {
+    this.webex = webex;
+    this.webexRequest = WebexRequest.getInstance({webex});
+    this.pageCache = new PageCache<ContactServiceQueue>('Queue');
+    this.metricsManager = MetricsManager.getInstance({webex});
+  }
+
+  /**
+   * Fetches contact service queues for the organization
+   * @param {ContactServiceQueueSearchParams} [params] - Search and pagination parameters
+   * @returns {Promise<ContactServiceQueuesResponse>} Promise resolving to contact service queues
+   * @throws {Error} If the API call fails
+   * @public
+   * @example
+   * ```typescript
+   * // Get all queues with default pagination
+   * const response = await queueAPI.getQueues();
+   *
+   * // Get queues with specific pagination
+   * const response = await queueAPI.getQueues({
+   *   page: 0,
+   *   pageSize: 25
+   * });
+   *
+   * // Search for queues
+   * const response = await queueAPI.getQueues({
+   *   search: 'support',
+   *   filter: 'queueType=="INBOUND"'
+   * });
+   * ```
+   */
+  public async getQueues(
+    params: ContactServiceQueueSearchParams = {}
+  ): Promise<ContactServiceQueuesResponse> {
+    const startTime = Date.now();
+    const {
+      page = PAGINATION_DEFAULTS.PAGE,
+      pageSize = PAGINATION_DEFAULTS.PAGE_SIZE,
+      search,
+      filter,
+      attributes,
+      sortBy,
+      sortOrder,
+      desktopProfileFilter,
+      provisioningView,
+      singleObjectResponse,
+    } = params;
+
+    const orgId = this.webex.credentials.getOrgId();
+    const isSearchRequest = !!(search || filter || attributes || sortBy);
+
+    LoggerProxy.info('Fetching contact service queues', {
+      module: 'Queue',
+      method: METHODS.GET_QUEUES,
+      data: {
+        orgId,
+        page,
+        pageSize,
+        isSearchRequest,
+      },
+    });
+
+    // 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`, {
+          module: 'Queue',
+          method: 'getQueues',
+          data: {
+            cacheHit: true,
+            duration,
+            recordCount: cachedPage.data.length,
+            page,
+            pageSize,
+          },
+        });
+
+        return {
+          data: cachedPage.data,
+          meta: {
+            page,
+            pageSize,
+            totalPages: cachedPage.totalMeta?.totalPages,
+            totalRecords: cachedPage.totalMeta?.totalRecords,
+            orgid: orgId,
+          },
+        };
+      }
+    }
+
+    // Start timing only for actual API calls (not cache hits)
+    this.metricsManager.timeEvent(METRIC_EVENT_NAMES.QUEUE_FETCH_SUCCESS);
+
+    try {
+      // Build query parameters according to spec
+      const queryParams = new URLSearchParams({
+        page: page.toString(),
+        pageSize: pageSize.toString(),
+      });
+
+      if (filter) queryParams.append('filter', filter);
+      if (attributes) queryParams.append('attributes', attributes);
+      if (search) queryParams.append('search', search);
+      if (sortBy) queryParams.append('sortBy', sortBy);
+      if (sortOrder) queryParams.append('sortOrder', sortOrder);
+      if (desktopProfileFilter !== undefined)
+        queryParams.append('desktopProfileFilter', desktopProfileFilter.toString());
+      if (provisioningView !== undefined)
+        queryParams.append('provisioningView', provisioningView.toString());
+      if (singleObjectResponse !== undefined)
+        queryParams.append('singleObjectResponse', singleObjectResponse.toString());
+
+      const resource = endPointMap.queueList(orgId, queryParams.toString());
+
+      LoggerProxy.log('Making API request to fetch contact service queues', {
+        module: 'Queue',
+        method: METHODS.GET_QUEUES,
+        data: {
+          resource,
+          service: WCC_API_GATEWAY,
+        },
+      });
+
+      const response = await this.webexRequest.request({
+        service: WCC_API_GATEWAY,
+        resource,
+        method: HTTP_METHODS.GET,
+      });
+
+      const duration = Date.now() - startTime;
+
+      const recordCount = response.body?.data?.length || 0;
+      const totalRecords = response.body?.meta?.totalRecords;
+
+      LoggerProxy.log(`Successfully retrieved ${recordCount} contact service queues`, {
+        module: 'Queue',
+        method: METHODS.GET_QUEUES,
+        data: {
+          statusCode: response.statusCode,
+          duration,
+          recordCount,
+          totalRecords,
+          isSearchRequest,
+          page,
+          pageSize,
+        },
+      });
+
+      // Only track metrics for search requests or first page loads to reduce metric volume
+      if (isSearchRequest || page === 0) {
+        this.metricsManager.trackEvent(
+          METRIC_EVENT_NAMES.QUEUE_FETCH_SUCCESS,
+          {
+            orgId,
+            statusCode: response.statusCode,
+            recordCount,
+            totalRecords,
+            isSearchRequest,
+            isFirstPage: page === 0,
+          },
+          ['behavioral', 'operational']
+        );
+      }
+
+      // 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 contact service queues for future requests', {
+          module: 'Queue',
+          method: METHODS.GET_QUEUES,
+          data: {
+            cacheKey,
+            recordCount,
+          },
+        });
+      }
+
+      return response.body;
+    } catch (error) {
+      const errorData = {
+        orgId,
+        error: error instanceof Error ? error.message : String(error),
+        isSearchRequest,
+        page,
+        pageSize,
+      };
+
+      LoggerProxy.error('Failed to fetch contact service queues', {
+        module: 'Queue',
+        method: METHODS.GET_QUEUES,
+        data: errorData,
+        error,
+      });
+
+      // Track all failures for troubleshooting
+      this.metricsManager.trackEvent(METRIC_EVENT_NAMES.QUEUE_FETCH_FAILED, errorData, [
+        'behavioral',
+        'operational',
+      ]);
+
+      throw error;
+    }
+  }
+}
+
+export default Queue;

package/src/services/config/constants.ts

@@ -67,7 +67,6 @@ export const METHODS = {
   GET_TENANT_DATA: 'getTenantData',
   GET_URL_MAPPING: 'getURLMapping',
   GET_DIAL_PLAN_DATA: 'getDialPlanData',
-  GET_QUEUES: 'getQueues',
 
   // Util methods
   PARSE_AGENT_CONFIGS: 'parseAgentConfigs',
@@ -245,5 +244,30 @@ export const endPointMap = {
    * @ignore
    */
   queueList: (orgId: string, queryParams: string) =>
-    `organization/${orgId}/v2/contact-service-queue?${queryParams}`,
+    `/organization/${orgId}/v2/contact-service-queue?${queryParams}`,
+  /**
+   * Gets the endpoint for entry points list with custom query parameters.
+   * @param orgId - Organization ID.
+   * @param queryParams - Query parameters string.
+   * @returns The endpoint URL string.
+   * @public
+   * @example
+   * const url = endPointMap.entryPointList('org123', 'page=0&pageSize=10');
+   * @ignore
+   */
+  entryPointList: (orgId: string, queryParams: string) =>
+    `/organization/${orgId}/v2/entry-point?${queryParams}`,
+  /**
+   * Gets the endpoint for address book entries with custom query parameters.
+   * @param orgId - Organization ID.
+   * @param addressBookId - Address book ID.
+   * @param queryParams - Query parameters string.
+   * @returns The endpoint URL string.
+   * @public
+   * @example
+   * const url = endPointMap.addressBookEntries('org123', 'book456', 'page=0&pageSize=10');
+   * @ignore
+   */
+  addressBookEntries: (orgId: string, addressBookId: string, queryParams: string) =>
+    `/organization/${orgId}/v2/address-book/${addressBookId}/entry?${queryParams}`,
 };

package/src/services/config/index.ts

@@ -20,7 +20,6 @@ import {
   AuxCode,
   MultimediaProfileResponse,
   SiteInfo,
-  ContactServiceQueue,
 } from './types';
 import WebexRequest from '../core/WebexRequest';
 import {WCC_API_GATEWAY} from '../constants';
@@ -686,58 +685,5 @@ export default class AgentConfigService {
     }
   }
 
-  /**
-   * Fetches the list of queues for the given orgId.
-   * @ignore
-   * @param {string} orgId - organization ID for which the queues are to be fetched.
-   * @param {number} page - the page number to fetch.
-   * @param {number} pageSize - the number of queues to fetch per page.
-   * @param {string} search - optional search string
-   * @param {string} filter - optional filter string
-   * @returns Promise<ContactServiceQueue[]> - A promise that resolves to the list of contact service queues.
-   * @throws {Error} - Throws an error if the API call fails or if the response status is not 200.
-   * @private
-   */
-  public async getQueues(
-    orgId: string,
-    page: number,
-    pageSize: number,
-    search?: string,
-    filter?: string
-  ): Promise<ContactServiceQueue[]> {
-    LoggerProxy.info('Fetching queue list', {
-      module: CONFIG_FILE_NAME,
-      method: METHODS.GET_QUEUES,
-    });
-
-    try {
-      let queryParams = `page=${page}&pageSize=${pageSize}&desktopProfileFilter=true`;
-      if (search) queryParams += `&search=${search}`;
-      if (filter) queryParams += `&filter=${filter}`;
-
-      const resource = endPointMap.queueList(orgId, queryParams);
-      const response = await this.webexReq.request({
-        service: WCC_API_GATEWAY,
-        resource,
-        method: HTTP_METHODS.GET,
-      });
-
-      if (response.statusCode !== 200) {
-        throw new Error(`API call failed with ${response.statusCode}`);
-      }
-
-      LoggerProxy.log('getQueues API success.', {
-        module: CONFIG_FILE_NAME,
-        method: METHODS.GET_QUEUES,
-      });
-
-      return response.body?.data;
-    } catch (error) {
-      LoggerProxy.error(`getQueues API call failed with ${error}`, {
-        module: CONFIG_FILE_NAME,
-        method: METHODS.GET_QUEUES,
-      });
-      throw error;
-    }
-  }
+  // getQueues removed - use Queue instead
 }

package/src/services/config/types.ts

@@ -1050,68 +1050,3 @@ export type CallDistributionGroup = {
   /** Distribution time duration in seconds */
   duration: number;
 };
-
-/**
- * Comprehensive configuration for a contact service queue
- * @public
- */
-export type ContactServiceQueue = {
-  /** Unique identifier for the queue */
-  id: string;
-  /** Queue name */
-  name: string;
-  /** Queue description */
-  description: string;
-  /** Type of queue */
-  queueType: string;
-  /** Whether to check agent availability before routing */
-  checkAgentAvailability: boolean;
-  /** Type of channel this queue handles */
-  channelType: string;
-  /** Service level threshold in seconds */
-  serviceLevelThreshold: number;
-  /** Maximum number of active contacts allowed */
-  maxActiveContacts: number;
-  /** Maximum time contacts can wait in queue (seconds) */
-  maxTimeInQueue: number;
-  /** Default music on hold media file ID */
-  defaultMusicInQueueMediaFileId: string;
-  /** Queue timezone */
-  timezone: string;
-  /** Whether queue is active */
-  active: boolean;
-  /** Whether outbound campaign routing is enabled */
-  outdialCampaignEnabled: boolean;
-  /** Whether monitoring is permitted */
-  monitoringPermitted: boolean;
-  /** Whether parking is permitted */
-  parkingPermitted: boolean;
-  /** Whether recording is permitted */
-  recordingPermitted: boolean;
-  /** Whether recording all calls is permitted */
-  recordingAllCallsPermitted: boolean;
-  /** Whether pausing recordings is permitted */
-  pauseRecordingPermitted: boolean;
-  /** Maximum recording pause duration in seconds */
-  recordingPauseDuration: number;
-  /** Control flow script URL */
-  controlFlowScriptUrl: string;
-  /** IVR requeue URL */
-  ivrRequeueUrl: string;
-  /** Type of routing strategy */
-  routingType: string;
-  /** Queue-specific routing type */
-  queueRoutingType: string;
-  /** Queue skill requirements for routing */
-  queueSkillRequirements: object[];
-  /** Associated agents */
-  agents: object[];
-  /** Call distribution group configurations */
-  callDistributionGroups: CallDistributionGroup[];
-  /** Associated resource links */
-  links: Array<string>;
-  /** Timestamp when queue was created */
-  createdTime: string;
-  /** Timestamp when queue was last updated */
-  lastUpdatedTime: string;
-};

package/src/services/core/GlobalTypes.ts

@@ -32,3 +32,30 @@ export type Failure = Msg<{
   /** Human-readable description of the failure reason */
   reason: string;
 }>;
+
+/**
+ * Represents task API error details in a structured format
+ * @public
+ */
+export interface TaskError {
+  /** Original error object for throwing */
+  error: Error;
+  /** Unique tracking identifier for correlation */
+  trackingId: string;
+  /** Detailed error message from the API */
+  errorMessage: string;
+  /** Type/category of the error (e.g., "Bad Request") */
+  errorType: string;
+  /** Additional error context data */
+  errorData: string;
+  /** Numeric reason code */
+  reasonCode: number;
+}
+
+/**
+ * An Error object augmented with a flexible data field for additional context.
+ * Use this to attach structured data to thrown errors without ts-ignore.
+ */
+export interface AugmentedError extends Error {
+  data?: Record<string, any>;
+}

package/src/services/core/Utils.ts

@@ -1,8 +1,14 @@
 import * as Err from './Err';
 import {LoginOption, WebexRequestPayload} from '../../types';
-import {Failure} from './GlobalTypes';
+import {Failure, AugmentedError} from './GlobalTypes';
 import LoggerProxy from '../../logger-proxy';
 import WebexRequest from './WebexRequest';
+import {
+  TaskData,
+  ConsultTransferPayLoad,
+  CONSULT_TRANSFER_DESTINATION_TYPE,
+  Interaction,
+} from '../task/types';
 
 /**
  * Extracts common error details from a Webex request payload.
@@ -19,6 +25,28 @@ const getCommonErrorDetails = (errObj: WebexRequestPayload) => {
   };
 };
 
+/**
+ * Checks if the destination type represents an entry point variant (EPDN or ENTRYPOINT).
+ */
+const isEntryPointOrEpdn = (destAgentType?: string): boolean => {
+  return destAgentType === 'EPDN' || destAgentType === 'ENTRYPOINT';
+};
+
+/**
+ * Determines if the task involves dialing a number based on the destination type.
+ * Returns 'DIAL_NUMBER' for dial-related destinations, empty string otherwise.
+ */
+const getAgentActionTypeFromTask = (taskData?: TaskData): 'DIAL_NUMBER' | '' => {
+  const destAgentType = taskData?.destinationType;
+
+  // Check if destination requires dialing: direct dial number or entry point variants
+  const isDialNumber = destAgentType === 'DN';
+  const isEntryPointVariant = isEntryPointOrEpdn(destAgentType);
+
+  // If the destination type is a dial number or an entry point variant, return 'DIAL_NUMBER'
+  return isDialNumber || isEntryPointVariant ? 'DIAL_NUMBER' : '';
+};
+
 export const isValidDialNumber = (input: string): boolean => {
   // This regex checks for a valid dial number format for only few countries such as US, Canada.
   const regexForDn = /1[0-9]{3}[2-9][0-9]{6}([,]{1,10}[0-9]+){0,1}/;
@@ -115,6 +143,62 @@ export const getErrorDetails = (error: any, methodName: string, moduleName: stri
   };
 };
 
+/**
+ * Extracts error details from task API errors and logs them. Also uploads logs for the error.
+ * This handles the specific error format returned by task API calls.
+ *
+ * @param error - The error object from task API calls with structure: {id: string, details: {trackingId: string, msg: {...}}}
+ * @param methodName - The name of the method where the error occurred.
+ * @param moduleName - The name of the module where the error occurred.
+ * @returns AugmentedError containing structured error details on err.data for metrics and logging
+ * @public
+ * @example
+ * const taskError = generateTaskErrorObject(error, 'transfer', 'TaskModule');
+ * throw taskError.error;
+ * @ignore
+ */
+export const generateTaskErrorObject = (
+  error: any,
+  methodName: string,
+  moduleName: string
+): AugmentedError => {
+  const trackingId = error?.details?.trackingId || error?.trackingId || '';
+  const errorMsg = error?.details?.msg;
+
+  const fallbackMessage =
+    (error && typeof error.message === 'string' && error.message) ||
+    `Error while performing ${methodName}`;
+  const errorMessage = errorMsg?.errorMessage || fallbackMessage;
+  const errorType =
+    errorMsg?.errorType ||
+    (error && typeof error.name === 'string' && error.name) ||
+    'Unknown Error';
+  const errorData = errorMsg?.errorData || '';
+  const reasonCode = errorMsg?.reasonCode || 0;
+
+  // Log and upload for Task API formatted errors
+  LoggerProxy.error(`${methodName} failed: ${errorMessage} (${errorType})`, {
+    module: moduleName,
+    method: methodName,
+    trackingId,
+  });
+  WebexRequest.getInstance().uploadLogs({
+    correlationId: trackingId,
+  });
+
+  const reason = `${errorType}: ${errorMessage}${errorData ? ` (${errorData})` : ''}`;
+  const err: AugmentedError = new Error(reason);
+  err.data = {
+    message: errorMessage,
+    errorType,
+    errorData,
+    reasonCode,
+    trackingId,
+  };
+
+  return err;
+};
+
 /**
  * Creates an error details object suitable for use with the Err.Details class.
  *
@@ -130,3 +214,73 @@ export const createErrDetailsObject = (errObj: WebexRequestPayload) => {
 
   return new Err.Details('Service.reqs.generic.failure', details);
 };
+
+/**
+ * Derives the consult transfer destination type based on the provided task data.
+ *
+ * Logic parity with desktop behavior:
+ * - If agent action is dialing a number (DN/EPDN/ENTRYPOINT):
+ *   - ENTRYPOINT/EPDN map to ENTRYPOINT
+ *   - DN maps to DIALNUMBER
+ * - Otherwise defaults to AGENT
+ *
+ * @param taskData - The task data used to infer the agent action and destination type
+ * @returns The normalized destination type to be used for consult transfer
+ */
+/**
+ * Checks if a participant type represents a non-customer participant.
+ * Non-customer participants include agents, dial numbers, entry point dial numbers,
+ * and entry points.
+ */
+const isNonCustomerParticipant = (participantType: string): boolean => {
+  return (
+    participantType === 'Agent' ||
+    participantType === 'DN' ||
+    participantType === 'EpDn' ||
+    participantType === 'entryPoint'
+  );
+};
+
+/**
+ * Gets the destination agent ID from participants data by finding the first
+ * non-customer participant that is not the current agent and is not in wrap-up state.
+ *
+ * @param participants - The participants data from the interaction
+ * @param agentId - The current agent's ID to exclude from the search
+ * @returns The destination agent ID, or empty string if none found
+ */
+export const getDestinationAgentId = (
+  participants: Interaction['participants'],
+  agentId: string
+): string => {
+  let id = '';
+
+  if (participants) {
+    Object.keys(participants).forEach((participant) => {
+      const participantData = participants[participant];
+      if (
+        isNonCustomerParticipant(participantData.type) &&
+        participantData.id !== agentId &&
+        !participantData.isWrapUp
+      ) {
+        id = participantData.id;
+      }
+    });
+  }
+
+  return id;
+};
+
+export const deriveConsultTransferDestinationType = (
+  taskData?: TaskData
+): ConsultTransferPayLoad['destinationType'] => {
+  const agentActionType = getAgentActionTypeFromTask(taskData);
+
+  if (agentActionType === 'DIAL_NUMBER') {
+    return isEntryPointOrEpdn(taskData?.destinationType)
+      ? CONSULT_TRANSFER_DESTINATION_TYPE.ENTRYPOINT
+      : CONSULT_TRANSFER_DESTINATION_TYPE.DIALNUMBER;
+  }
+
+  return CONSULT_TRANSFER_DESTINATION_TYPE.AGENT;
+};

package/src/services/core/aqm-reqs.ts

@@ -224,11 +224,6 @@ export default class AqmReqs {
     }
 
     if (event.keepalive === 'true') {
-      LoggerProxy.info(`Keepalive from web socket`, {
-        module: AQM_REQS_FILE,
-        method: METHODS.ON_MESSAGE,
-      });
-
       return;
     }
 

package/src/services/core/websocket/WebSocketManager.ts

@@ -178,10 +178,6 @@ export class WebSocketManager extends EventEmitter {
         issueReason = 'WebSocket auto close timed out. Forcefully closed websocket.';
       } else {
         const onlineStatus = navigator.onLine;
-        LoggerProxy.info(`[WebSocketStatus] | desktop online status is ${onlineStatus}`, {
-          module: WEB_SOCKET_MANAGER_FILE,
-          method: METHODS.WEB_SOCKET_ON_CLOSE_HANDLER,
-        });
         issueReason = !onlineStatus
           ? 'network issue'
           : 'missing keepalive from either desktop or notif service';

package/src/services/task/TaskManager.ts

@@ -270,6 +270,7 @@ export default class TaskManager extends EventEmitter {
             break;
           case CC_EVENTS.AGENT_CONSULTING:
             // Received when agent is in an active consult state
+            // TODO: Check if we can use backend consult state instead of isConsulted
             task = this.updateTaskData(task, payload.data);
             if (task.data.isConsulted) {
               // Fire only if you are the agent who received the consult request