@webex/contact-center 3.9.0-next.2 → 3.9.0-next.21

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,46 @@ 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}`,
+
+  /**
+   * Gets the endpoint for outdial ANI entries with custom query parameters.
+   * @param orgId - Organization ID.
+   * @param outdialANI - Outdial ANI ID.
+   * @param queryParams - Query parameters string.
+   * @returns The endpoint URL string.
+   * @public
+   * @example
+   * const url = endPointMap.outdialAniEntries('org123', 'ani456', 'page=0&pageSize=10');
+   * @ignore
+   */
+  outdialAniEntries: (orgId: string, outdialANI: string, queryParams: string) =>
+    `organization/${orgId}/v2/outdial-ani/${outdialANI}/entry${
+      queryParams ? `?${queryParams}` : ''
+    }`,
 };

package/src/services/config/index.ts

@@ -9,9 +9,9 @@ import {
   DesktopProfileResponse,
   ListAuxCodesResponse,
   AgentResponse,
+  TenantData,
   OrgInfo,
   OrgSettings,
-  TenantData,
   URLMapping,
   TeamList,
   DialPlanEntity,
@@ -20,11 +20,12 @@ import {
   AuxCode,
   MultimediaProfileResponse,
   SiteInfo,
-  ContactServiceQueue,
+  OutdialAniEntriesResponse,
+  OutdialAniParams,
 } from './types';
 import WebexRequest from '../core/WebexRequest';
 import {WCC_API_GATEWAY} from '../constants';
-import {CONFIG_FILE_NAME} from '../../constants';
+import {CONFIG_FILE_NAME, METHODS as MAIN_METHODS} from '../../constants';
 import {parseAgentConfigs} from './Util';
 import {
   DEFAULT_AUXCODE_ATTRIBUTES,
@@ -686,56 +687,55 @@ export default class AgentConfigService {
     }
   }
 
+  // getQueues removed - use Queue instead
+
   /**
-   * Fetches the list of queues for the given orgId.
+   * Fetches outdial ANI (Automatic Number Identification) entries for the given orgId and outdial ANI ID.
    * @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.
+   * @param {string} orgId - organization ID for which the outdial ANI entries are to be fetched.
+   * @param {OutdialAniParams} params - parameters object containing outdialANI and optional pagination/filtering options
+   * @returns {Promise<OutdialAniEntriesResponse>} - A promise that resolves to the outdial ANI entries response.
    * @throws {Error} - Throws an error if the API call fails or if the response status is not 200.
    * @private
    */
-  public async getQueues(
+  public async getOutdialAniEntries(
     orgId: string,
-    page: number,
-    pageSize: number,
-    search?: string,
-    filter?: string
-  ): Promise<ContactServiceQueue[]> {
-    LoggerProxy.info('Fetching queue list', {
+    params: OutdialAniParams
+  ): Promise<OutdialAniEntriesResponse> {
+    const {outdialANI, page, pageSize, search, filter, attributes} = params;
+
+    LoggerProxy.info('Fetching outdial ANI entries', {
       module: CONFIG_FILE_NAME,
-      method: METHODS.GET_QUEUES,
+      method: MAIN_METHODS.GET_OUTDIAL_ANI_ENTRIES,
     });
 
     try {
-      let queryParams = `page=${page}&pageSize=${pageSize}&desktopProfileFilter=true`;
-      if (search) queryParams += `&search=${search}`;
-      if (filter) queryParams += `&filter=${filter}`;
+      const queryParams = [];
+      if (page !== undefined) queryParams.push(`page=${page}`);
+      if (pageSize !== undefined) queryParams.push(`pageSize=${pageSize}`);
+      if (search) queryParams.push(`search=${search}`);
+      if (filter) queryParams.push(`filter=${filter}`);
+      if (attributes) queryParams.push(`attributes=${attributes}`);
+
+      const queryString = queryParams.length > 0 ? queryParams.join('&') : '';
+      const resource = endPointMap.outdialAniEntries(orgId, outdialANI, queryString);
 
-      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.', {
+      LoggerProxy.log('getOutdialAniEntries API success.', {
         module: CONFIG_FILE_NAME,
-        method: METHODS.GET_QUEUES,
+        method: MAIN_METHODS.GET_OUTDIAL_ANI_ENTRIES,
       });
 
       return response.body?.data;
     } catch (error) {
-      LoggerProxy.error(`getQueues API call failed with ${error}`, {
+      LoggerProxy.error(`getOutdialAniEntries API call failed with ${error}`, {
         module: CONFIG_FILE_NAME,
-        method: METHODS.GET_QUEUES,
+        method: MAIN_METHODS.GET_OUTDIAL_ANI_ENTRIES,
       });
       throw error;
     }

package/src/services/config/types.ts

@@ -45,6 +45,28 @@ export const CC_TASK_EVENTS = {
   AGENT_CONSULT_END_FAILED: 'AgentConsultEndFailed',
   /** Event emitted when consultation conference ends */
   AGENT_CONSULT_CONFERENCE_ENDED: 'AgentConsultConferenceEnded',
+  /** Event emitted when consultation conference is in progress */
+  AGENT_CONSULT_CONFERENCING: 'AgentConsultConferencing',
+  /** Event emitted when consultation conference starts */
+  AGENT_CONSULT_CONFERENCED: 'AgentConsultConferenced',
+  /** Event emitted when consultation conference fails */
+  AGENT_CONSULT_CONFERENCE_FAILED: 'AgentConsultConferenceFailed',
+  /** Event emitted when participant joins conference */
+  PARTICIPANT_JOINED_CONFERENCE: 'ParticipantJoinedConference',
+  /** Event emitted when participant leaves conference */
+  PARTICIPANT_LEFT_CONFERENCE: 'ParticipantLeftConference',
+  /** Event emitted when participant leaving conference fails */
+  PARTICIPANT_LEFT_CONFERENCE_FAILED: 'ParticipantLeftConferenceFailed',
+  /** Event emitted when consultation conference end fails */
+  AGENT_CONSULT_CONFERENCE_END_FAILED: 'AgentConsultConferenceEndFailed',
+  /** Event emitted when conference is successfully transferred */
+  AGENT_CONFERENCE_TRANSFERRED: 'AgentConferenceTransferred',
+  /** Event emitted when conference transfer fails */
+  AGENT_CONFERENCE_TRANSFER_FAILED: 'AgentConferenceTransferFailed',
+  /** Event emitted when consulted participant is moving/being transferred */
+  CONSULTED_PARTICIPANT_MOVING: 'ConsultedParticipantMoving',
+  /** Event emitted for post-call activity by participant */
+  PARTICIPANT_POST_CALL_ACTIVITY: 'ParticipantPostCallActivity',
   /** Event emitted when contact is blind transferred */
   AGENT_BLIND_TRANSFERRED: 'AgentBlindTransferred',
   /** Event emitted when blind transfer fails */
@@ -1052,66 +1074,45 @@ export type CallDistributionGroup = {
 };
 
 /**
- * Comprehensive configuration for a contact service queue
+ * Represents a single outdial ANI (Automatic Number Identification) entry
  * @public
  */
-export type ContactServiceQueue = {
-  /** Unique identifier for the queue */
+export type OutdialAniEntry = {
+  /** Unique identifier for the ANI entry */
   id: string;
-  /** Queue name */
+  /** Display name for the ANI entry */
   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;
+  /** Phone number associated with this ANI entry */
+  number: string;
+  /** Related links for this ANI entry */
+  links: string[];
+  /** Timestamp when this entry was created (Unix timestamp in milliseconds) */
+  createdTime: number;
+  /** Timestamp when this entry was last updated (Unix timestamp in milliseconds) */
+  lastUpdatedTime: number;
+};
+
+/**
+ * Response structure for outdial ANI entries API call
+ * @public
+ */
+export type OutdialAniEntriesResponse = OutdialAniEntry[];
+
+/**
+ * Parameters for fetching outdial ANI entries
+ * @public
+ */
+export type OutdialAniParams = {
+  /** Outdial ANI ID from agent profile */
+  outdialANI: string;
+  /** Page number for pagination (optional) */
+  page?: number;
+  /** Number of entries per page (optional) */
+  pageSize?: number;
+  /** Search string to filter entries (optional) */
+  search?: string;
+  /** Filter expression for advanced filtering (optional) */
+  filter?: string;
+  /** Comma-separated list of attributes to include in response (optional) */
+  attributes?: 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>;
+}