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

package/src/cc.ts

@@ -44,13 +44,8 @@ import WebexRequest from './services/core/WebexRequest';
 import LoggerProxy from './logger-proxy';
 import {StateChange, Logout, StateChangeSuccess, AGENT_EVENTS} from './services/agent/types';
 import {getErrorDetails, isValidDialNumber} from './services/core/Utils';
-import {Profile, WelcomeEvent, CC_EVENTS, ContactServiceQueue} from './services/config/types';
-import {
-  AGENT_STATE_AVAILABLE,
-  AGENT_STATE_AVAILABLE_ID,
-  DEFAULT_PAGE,
-  DEFAULT_PAGE_SIZE,
-} from './services/config/constants';
+import {Profile, WelcomeEvent, CC_EVENTS} from './services/config/types';
+import {AGENT_STATE_AVAILABLE, AGENT_STATE_AVAILABLE_ID} from './services/config/constants';
 import {ConnectionLostDetails} from './services/core/websocket/types';
 import TaskManager from './services/task/TaskManager';
 import WebCallingService from './services/WebCallingService';
@@ -58,6 +53,15 @@ import {ITask, TASK_EVENTS, TaskResponse, DialerPayload} from './services/task/t
 import MetricsManager from './metrics/MetricsManager';
 import {METRIC_EVENT_NAMES} from './metrics/constants';
 import {Failure} from './services/core/GlobalTypes';
+import EntryPoint from './services/EntryPoint';
+import AddressBook from './services/AddressBook';
+import Queue from './services/Queue';
+import type {
+  EntryPointListResponse,
+  EntryPointSearchParams,
+  ContactServiceQueuesResponse,
+  ContactServiceQueueSearchParams,
+} from './types';
 
 /**
  * The main Contact Center plugin class that enables integration with Webex Contact Center.
@@ -163,6 +167,7 @@ import {Failure} from './services/core/GlobalTypes';
  *
  * @public
  */
+
 export default class ContactCenter extends WebexPlugin implements IContactCenter {
   /**
    * The plugin's unique namespace identifier in the Webex SDK.
@@ -243,6 +248,71 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
    */
   private metricsManager: MetricsManager;
 
+  /**
+   * API instance for managing Webex Contact Center entry points
+   * Provides functionality to fetch entry points with caching support
+   * @type {EntryPoint}
+   * @public
+   * @example
+   * ```typescript
+   * const cc = webex.cc;
+   * await cc.register();
+   * await cc.stationLogin({ teamId: 'team123', loginOption: 'BROWSER' });
+   *
+   * // Access EntryPointRecord
+   * const response = await cc.entryPoint.getEntryPoints({
+   *   page: 0,
+   *   pageSize: 50
+   * });
+   * ```
+   */
+  private entryPoint: EntryPoint;
+
+  /**
+   * API instance for managing Webex Contact Center address book contacts
+   * Provides functionality to fetch address book entries with caching support
+   * @type {AddressBook}
+   * @public
+   * @example
+   * ```typescript
+   * const cc = webex.cc;
+   * await cc.register();
+   * await cc.stationLogin({ teamId: 'team123', loginOption: 'BROWSER' });
+   *
+   * // Access AddressBook API
+   * const response = await cc.addressBook.getEntries({
+   *   page: 0,
+   *   pageSize: 25
+   * });
+   * ```
+   */
+  public addressBook: AddressBook;
+
+  /**
+   * API instance for managing Webex Contact Center queues
+   * Provides functionality to fetch queues with caching support
+   * @type {Queue}
+   * @public
+   * @example
+   * ```typescript
+   * const cc = webex.cc;
+   * await cc.register();
+   * await cc.stationLogin({ teamId: 'team123', loginOption: 'BROWSER' });
+   *
+   * // Access Queue API
+   * const response = await cc.queue.getQueues({
+   *   page: 0,
+   *   pageSize: 50
+   * });
+   *
+   * // Filter queues by specific criteria
+   * const filteredQueues = await cc.queue.getQueues({
+   *   filter: 'id=="queue-id-123"'
+   * });
+   * ```
+   */
+  private queue: Queue;
+
   /**
    * Logger utility for Contact Center plugin
    * Provides consistent logging across the plugin
@@ -289,6 +359,13 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       );
       this.incomingTaskListener();
 
+      // Initialize API instances
+      // will have future function for indivdual fetch etc so better be in an object
+      this.entryPoint = new EntryPoint(this.$webex);
+      this.addressBook = new AddressBook(this.$webex, () => this.agentConfig?.addressBookId);
+      this.queue = new Queue(this.$webex);
+
+      // Initialize logger
       LoggerProxy.initialize(this.$webex.logger);
     });
   }
@@ -984,6 +1061,20 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       method: METHODS.HANDLE_WEBSOCKET_MESSAGE,
     });
 
+    // Emit metrics for all websocket events except keepalive and welcome
+    const topLevelType = eventData.type;
+    const nestedType = eventData?.data?.type;
+    if (topLevelType !== CC_EVENTS.WELCOME && eventData.keepalive !== 'true') {
+      const metricsPayload: Record<string, any> = {
+        ws_event_type: nestedType || topLevelType,
+        top_level_type: topLevelType,
+        has_data: Boolean(eventData.data),
+      };
+      this.metricsManager.trackEvent(METRIC_EVENT_NAMES.WEBSOCKET_EVENT_RECEIVED, metricsPayload, [
+        'operational',
+      ]);
+    }
+
     switch (eventData.type) {
       case CC_EVENTS.AGENT_MULTI_LOGIN:
         // @ts-ignore
@@ -1398,79 +1489,6 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
     }
   }
 
-  /**
-   * This is used for getting the list of queues to which a task can be consulted or transferred.
-   * @param {string} [search] - Optional search string to filter queues by name
-   * @param {string} [filter] - Optional OData filter expression (e.g., 'teamId eq "team123"')
-   * @param {number} [page=0] - Page number for paginated results, starting at 0
-   * @param {number} [pageSize=100] - Number of queues to return per page
-   * @returns Promise<ContactServiceQueue[]> Resolves with the list of queues
-   * @throws Error If the operation fails
-   * @public
-   * @example
-   * ```typescript
-   * const cc = webex.cc;
-   * await cc.register();
-   * await cc.stationLogin({ teamId: 'team123', loginOption: 'BROWSER' });
-   *
-   * // Basic usage - get all queues
-   * const allQueues = await cc.getQueues();
-   *
-   * // Search for specific queues
-   * const salesQueues = await cc.getQueues('sales'); // Search for 'sales' in queue names
-   *
-   * // Use filtering and pagination
-   * const filteredQueues = await cc.getQueues(
-   *   '', // No search term
-   *   'teamId eq "team123"', // Filter by team
-   *   0,  // First page
-   *   50  // 50 items per page
-   * );
-   *
-   * // Process queue results
-   * queues.forEach(queue => {
-   *   console.log('Queue:', {
-   *     id: queue.queueId,
-   *     name: queue.queueName,
-   *     channelType: queue.channelType,
-   *     isActive: queue.isActive,
-   *     description: queue.description
-   *   });
-   * });
-   * ```
-   */
-  public async getQueues(
-    search?: string,
-    filter?: string,
-    page = DEFAULT_PAGE,
-    pageSize = DEFAULT_PAGE_SIZE
-  ): Promise<ContactServiceQueue[]> {
-    LoggerProxy.info('Fetching queues', {
-      module: CC_FILE,
-      method: METHODS.GET_QUEUES,
-    });
-
-    const orgId = this.$webex.credentials.getOrgId();
-
-    if (!orgId) {
-      LoggerProxy.error('Org ID not found.', {
-        module: CC_FILE,
-        method: METHODS.GET_QUEUES,
-      });
-
-      throw new Error('Org ID not found.');
-    }
-
-    const result = await this.services.config.getQueues(orgId, page, pageSize, search, filter);
-
-    LoggerProxy.log(`Successfully retrieved ${result?.length} queues`, {
-      module: CC_FILE,
-      method: METHODS.GET_QUEUES,
-    });
-
-    return result;
-  }
-
   /**
    * Uploads logs to help troubleshoot SDK issues.
    *
@@ -1615,4 +1633,26 @@ export default class ContactCenter extends WebexPlugin implements IContactCenter
       throw error;
     }
   }
+
+  /**
+   * Returns paginated entry points for the organization.
+   * Thin wrapper around internal EntryPoint instance.
+   * @public
+   */
+  public async getEntryPoints(
+    params: EntryPointSearchParams = {}
+  ): Promise<EntryPointListResponse> {
+    return this.entryPoint.getEntryPoints(params);
+  }
+
+  /**
+   * Returns paginated contact service queues for the organization.
+   * Thin wrapper around internal Queue instance.
+   * @public
+   */
+  public async getQueues(
+    params: ContactServiceQueueSearchParams = {}
+  ): Promise<ContactServiceQueuesResponse> {
+    return this.queue.getQueues(params);
+  }
 }

package/src/index.ts

@@ -26,6 +26,22 @@ export {default as Task} from './services/task';
  */
 export {default as routingAgent} from './services/agent';
 
+// API exports (AddressBook is public, EntryPoint and Queue are accessed via cc wrappers)
+export {default as AddressBook} from './services/AddressBook';
+
+/** EntryPoint API types */
+export type {
+  EntryPointRecord,
+  EntryPointListResponse,
+  EntryPointSearchParams,
+  AddressBookEntry,
+  AddressBookEntriesResponse,
+  AddressBookEntrySearchParams,
+  ContactServiceQueuesResponse,
+  ContactServiceQueueSearchParams,
+  ContactServiceQueue,
+} from './types';
+
 // Enums
 /**
  * Task Events for Contact Center operations
@@ -157,8 +173,6 @@ export type {
 export type {
   /** Profile interface */
   Profile,
-  /** Contact service queue interface */
-  ContactServiceQueue,
   /** Response type from getUserUsingCI method */
   AgentResponse,
   /** Response from getDesktopProfileById */

package/src/logger-proxy.ts

@@ -105,6 +105,29 @@ export default class LoggerProxy {
     const interactionId = context.interactionId ? ` - interactionId:${context.interactionId}` : '';
     const trackingId = context.trackingId ? ` - trackingId:${context.trackingId}` : '';
 
-    return `${timestamp} ${LOG_PREFIX} - [${level}]: module:${moduleName} - method:${methodName}${interactionId}${trackingId} - ${message}`;
+    // Format additional data if provided
+    let dataString = '';
+    if (context.data) {
+      try {
+        dataString = ` - data:${JSON.stringify(context.data)}`;
+      } catch (e) {
+        dataString = ` - data:[object]`;
+      }
+    }
+
+    // Format error if provided
+    let errorString = '';
+    if (context.error) {
+      if (context.error instanceof Error) {
+        errorString = ` - error:${context.error.name}:${context.error.message}`;
+        if (context.error.stack && level === LOGGING_LEVEL.error) {
+          errorString += ` - stack:${context.error.stack}`;
+        }
+      } else {
+        errorString = ` - error:${String(context.error)}`;
+      }
+    }
+
+    return `${timestamp} ${LOG_PREFIX} - [${level}]: module:${moduleName} - method:${methodName}${interactionId}${trackingId}${dataString}${errorString} - ${message}`;
   }
 }

package/src/metrics/MetricsManager.ts

@@ -6,8 +6,8 @@ import {
 } from '@webex/internal-plugin-metrics/src/metrics.types';
 
 import {WebexSDK} from '../types';
-import {BehavioralEventTaxonomy, getEventTaxonomy} from './behavioral-events';
 import LoggerProxy from '../logger-proxy';
+import {BehavioralEventTaxonomy, getEventTaxonomy} from './behavioral-events';
 import {METRIC_EVENT_NAMES} from './constants';
 import {Failure} from '../services/core/GlobalTypes';
 import {PRODUCT_NAME} from '../constants';

package/src/metrics/behavioral-events.ts

@@ -329,6 +329,48 @@ const eventTaxonomyMap: Record<string, BehavioralEventTaxonomy> = {
     target: 'agent_device_type_update',
     verb: 'fail',
   },
+
+  // EntryPoint API Events
+  [METRIC_EVENT_NAMES.ENTRYPOINT_FETCH_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'entrypoint_fetch',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.ENTRYPOINT_FETCH_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'entrypoint_fetch',
+    verb: 'fail',
+  },
+
+  // AddressBook API Events
+  [METRIC_EVENT_NAMES.ADDRESSBOOK_FETCH_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'addressbook_fetch',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.ADDRESSBOOK_FETCH_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'addressbook_fetch',
+    verb: 'fail',
+  },
+
+  // Queue API Events
+  [METRIC_EVENT_NAMES.QUEUE_FETCH_SUCCESS]: {
+    product,
+    agent: 'user',
+    target: 'queue_fetch',
+    verb: 'complete',
+  },
+  [METRIC_EVENT_NAMES.QUEUE_FETCH_FAILED]: {
+    product,
+    agent: 'user',
+    target: 'queue_fetch',
+    verb: 'fail',
+  },
 };
 
 /**

package/src/metrics/constants.ts

@@ -117,8 +117,23 @@ export const METRIC_EVENT_NAMES = {
   WEBSOCKET_DEREGISTER_SUCCESS: 'Websocket Deregister Success',
   WEBSOCKET_DEREGISTER_FAIL: 'Websocket Deregister Failed',
 
+  // WebSocket message events
+  WEBSOCKET_EVENT_RECEIVED: 'Websocket Event Received',
+
   AGENT_DEVICE_TYPE_UPDATE_SUCCESS: 'Agent Device Type Update Success',
   AGENT_DEVICE_TYPE_UPDATE_FAILED: 'Agent Device Type Update Failed',
+
+  // EntryPoint API Events
+  ENTRYPOINT_FETCH_SUCCESS: 'Entrypoint Fetch Success',
+  ENTRYPOINT_FETCH_FAILED: 'Entrypoint Fetch Failed',
+
+  // AddressBook API Events
+  ADDRESSBOOK_FETCH_SUCCESS: 'AddressBook Fetch Success',
+  ADDRESSBOOK_FETCH_FAILED: 'AddressBook Fetch Failed',
+
+  // Queue API Events
+  QUEUE_FETCH_SUCCESS: 'Queue Fetch Success',
+  QUEUE_FETCH_FAILED: 'Queue Fetch Failed',
 } as const;
 
 /**

package/src/services/AddressBook.ts

@@ -0,0 +1,291 @@
+import {HTTP_METHODS, WebexSDK} from '../types';
+import type {
+  AddressBookEntry,
+  AddressBookEntriesResponse,
+  AddressBookEntrySearchParams,
+} 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';
+
+/**
+ * AddressBook API class for managing Webex Contact Center address book entries.
+ * Provides functionality to fetch address book entries using the entry API.
+ *
+ * @class AddressBook
+ * @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 AddressBook API instance from ContactCenter
+ * const addressBookAPI = cc.addressBook;
+ *
+ * // Get entries from agent's default address book
+ * const entries = await addressBookAPI.getEntries();
+ *
+ * // Get entries from a specific address book with pagination
+ * const entries = await addressBookAPI.getEntries({
+ *   addressBookId: 'addressBookId123',
+ *   page: 0,
+ *   pageSize: 50
+ * });
+ *
+ * // Search for specific entries
+ * const searchResults = await addressBook.getEntries({
+ *   search: 'john',
+ *   filter: 'name=="John Doe"'
+ * });
+ * ```
+ */
+export class AddressBook {
+  private webexRequest: WebexRequest;
+  private webex: WebexSDK;
+  private getAddressBookId: () => string;
+  private metricsManager: MetricsManager;
+
+  // Page cache using the common utility
+  private pageCache: PageCache<AddressBookEntry>;
+
+  /**
+   * Creates an instance of AddressBook
+   * @param {WebexSDK} webex - The Webex SDK instance
+   * @param {() => string} getAddressBookId - Function to get the addressBookId from agent profile
+   * @public
+   */
+  constructor(webex: WebexSDK, getAddressBookId: () => string) {
+    this.webex = webex;
+    this.webexRequest = WebexRequest.getInstance({webex});
+    this.getAddressBookId = getAddressBookId;
+    this.pageCache = new PageCache<AddressBookEntry>('AddressBook');
+    this.metricsManager = MetricsManager.getInstance({webex});
+  }
+
+  /**
+   * Fetches address book entries for a specific address book using the entry API
+   * @param {AddressBookEntrySearchParams} [params] - Search and pagination parameters including addressBookId
+   * @returns {Promise<AddressBookEntriesResponse>} Promise resolving to address book entries
+   * @throws {Error} If the API call fails
+   * @public
+   * @example
+   * ```typescript
+   * // Get entries from agent's default address book
+   * const response = await addressBookAPI.getEntries();
+   *
+   * // Get entries from a specific address book with pagination
+   * const response = await addressBookAPI.getEntries({
+   *   addressBookId: 'addressBookId123',
+   *   page: 0,
+   *   pageSize: 25
+   * });
+   * ```
+   */
+  public async getEntries(
+    params: AddressBookEntrySearchParams = {}
+  ): Promise<AddressBookEntriesResponse> {
+    const startTime = Date.now();
+    const {
+      addressBookId,
+      page = PAGINATION_DEFAULTS.PAGE,
+      pageSize = PAGINATION_DEFAULTS.PAGE_SIZE,
+      search,
+      filter,
+      attributes,
+    } = params;
+
+    // Use provided addressBookId or fall back to agent's address book
+    const bookId = addressBookId || this.getAddressBookId();
+    const orgId = this.webex.credentials.getOrgId();
+    const isSearchRequest = !!(search || filter || attributes);
+
+    LoggerProxy.info('Fetching address book entries', {
+      module: 'AddressBook',
+      method: 'getEntries',
+      data: {
+        orgId,
+        bookId,
+        page,
+        pageSize,
+        isSearchRequest,
+      },
+    });
+
+    // Check if we can use cache for simple pagination (no search/filter/attributes)
+    if (this.pageCache.canUseCache({search, filter, attributes})) {
+      const cacheKey = this.pageCache.buildCacheKey(bookId, page, pageSize);
+      const cachedPage = this.pageCache.getCachedPage(cacheKey);
+
+      if (cachedPage) {
+        const duration = Date.now() - startTime;
+
+        LoggerProxy.info(`Returning page ${page} from cache`, {
+          module: 'AddressBook',
+          method: 'getEntries',
+          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,
+          },
+        };
+      }
+    }
+
+    // Start timing for the operation
+    this.metricsManager.timeEvent(METRIC_EVENT_NAMES.ADDRESSBOOK_FETCH_SUCCESS);
+
+    // Validate address book id early to avoid bad requests
+    if (!bookId) {
+      const errorData = {
+        orgId,
+        bookId,
+        isSearchRequest,
+        page,
+        pageSize,
+        error: 'Missing addressBookId for agent. Ensure agent profile contains addressBookId.',
+      };
+      LoggerProxy.error('AddressBook called without a valid addressBookId', {
+        module: 'AddressBook',
+        method: 'getEntries',
+        data: errorData,
+      });
+
+      this.metricsManager.trackEvent(METRIC_EVENT_NAMES.ADDRESSBOOK_FETCH_FAILED, errorData, [
+        'behavioral',
+        'operational',
+      ]);
+
+      throw new Error('AddressBook: addressBookId is not available for the current agent.');
+    }
+
+    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);
+
+      const resource = endPointMap.addressBookEntries(orgId, bookId, queryParams.toString());
+
+      LoggerProxy.info('Making API request to fetch address book entries', {
+        module: 'AddressBook',
+        method: 'getEntries',
+        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.info(`Successfully retrieved ${recordCount} address book entries`, {
+        module: 'AddressBook',
+        method: 'getEntries',
+        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.ADDRESSBOOK_FETCH_SUCCESS,
+          {
+            orgId,
+            bookId,
+            statusCode: response.statusCode,
+            recordCount,
+            totalRecords,
+            isSearchRequest,
+            isFirstPage: page === 0,
+          },
+          ['behavioral', 'operational']
+        );
+      }
+
+      // Cache the page data for simple pagination (no search/filter/attributes)
+      if (this.pageCache.canUseCache({search, filter, attributes}) && response.body?.data) {
+        const cacheKey = this.pageCache.buildCacheKey(bookId, page, pageSize);
+        this.pageCache.cachePage(cacheKey, response.body.data, response.body.meta);
+
+        LoggerProxy.info('Cached address book entries for future requests', {
+          module: 'AddressBook',
+          method: 'getEntries',
+          data: {
+            cacheKey,
+            recordCount,
+          },
+        });
+      }
+
+      return response.body;
+    } catch (error) {
+      const errorData = {
+        orgId,
+        bookId,
+        error: error instanceof Error ? error.message : String(error),
+        isSearchRequest,
+        page,
+        pageSize,
+      };
+
+      LoggerProxy.error('Failed to fetch address book entries', {
+        module: 'AddressBook',
+        method: 'getEntries',
+        data: errorData,
+        error,
+      });
+
+      // Track all failures for troubleshooting
+      this.metricsManager.trackEvent(METRIC_EVENT_NAMES.ADDRESSBOOK_FETCH_FAILED, errorData, [
+        'behavioral',
+        'operational',
+      ]);
+
+      throw error;
+    }
+  }
+}
+
+export default AddressBook;