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

package/src/utils/PageCache.ts

@@ -0,0 +1,252 @@
+import LoggerProxy from '../logger-proxy';
+
+/**
+ * Common pagination metadata interface used across all APIs.
+ * @public
+ * @template T - Additional metadata properties specific to the API
+ */
+export interface PaginationMeta {
+  /** Organization ID */
+  orgid?: string;
+  /** Current page number */
+  page?: number;
+  /** Page size for current data set */
+  pageSize?: number;
+  /** Number of pages */
+  totalPages?: number;
+  /** Total number of items */
+  totalRecords?: number;
+  /** Total number of items (alias for compatibility) */
+  totalItems?: number;
+  /** Current page number (alias for compatibility) */
+  currentPage?: number;
+  /** Map of pagination links */
+  links?: Record<string, string>;
+}
+
+/**
+ * Common paginated response interface used across all APIs.
+ * @public
+ * @template T - The type of data items in the response
+ */
+export interface PaginatedResponse<T> {
+  /** Array of data items */
+  data: T[];
+  /** Pagination metadata */
+  meta: PaginationMeta;
+}
+
+/**
+ * Common search and pagination parameters interface.
+ * @public
+ */
+export interface BaseSearchParams {
+  /** Search keyword */
+  search?: string;
+  /** Filter criteria using RSQL syntax */
+  filter?: string;
+  /** Attributes to be returned */
+  attributes?: string;
+  /** Page number (starts from 0) */
+  page?: number;
+  /** Number of items per page */
+  pageSize?: number;
+  /** Sort field */
+  sortBy?: string;
+  /** Sort direction */
+  sortOrder?: 'asc' | 'desc';
+}
+
+/**
+ * Default pagination constants used across all APIs.
+ * @public
+ */
+export const PAGINATION_DEFAULTS = {
+  /** Default page number */
+  PAGE: 0,
+  /** Default page size */
+  PAGE_SIZE: 100,
+} as const;
+
+/**
+ * Interface for cached page entry with metadata
+ * @public
+ */
+export interface PageCacheEntry<T> {
+  /** Cached data items for this page */
+  data: T[];
+  /** Timestamp when this page was cached */
+  timestamp: number;
+  /** Total metadata if available */
+  totalMeta?: {
+    totalPages?: number;
+    totalRecords?: number;
+  };
+}
+
+/**
+ * Interface for cache validation parameters
+ * @public
+ */
+export interface CacheValidationParams {
+  /** Search query parameter */
+  search?: string;
+  /** Filter parameter */
+  filter?: string;
+  /** Attributes parameter */
+  attributes?: string;
+  /** Sort by parameter */
+  sortBy?: string;
+}
+
+/**
+ * Default cache TTL in minutes
+ */
+const DEFAULT_CACHE_TTL_MINUTES = 5;
+
+/**
+ * Page cache utility class for managing paginated API response caching.
+ * Provides consistent caching behavior across all Contact Center APIs.
+ *
+ * @class PageCache
+ * @public
+ * @template T - The type of data items being cached
+ * @example
+ * ```typescript
+ * // Create a cache instance for a specific data type
+ * const cache = new PageCache<AddressBookEntry>('AddressBook');
+ *
+ * // Check if we can use cache (no search/filter parameters)
+ * if (cache.canUseCache({ search, filter })) {
+ *   const cacheKey = cache.buildCacheKey(orgId, page, pageSize);
+ *   const cachedPage = cache.getCachedPage(cacheKey);
+ *
+ *   if (cachedPage) {
+ *     return cachedPage.data;
+ *   }
+ * }
+ *
+ * // Cache API response
+ * cache.cachePage(cacheKey, responseData, responseMeta);
+ * ```
+ */
+export class PageCache<T> {
+  private cache: Map<string, PageCacheEntry<T>> = new Map();
+  private apiName: string;
+
+  /**
+   * Creates an instance of PageCache
+   * @param {string} apiName - Name of the API using this cache (for logging)
+   * @public
+   */
+  constructor(apiName: string) {
+    this.apiName = apiName;
+  }
+
+  /**
+   * Checks if cache can be used for the given parameters.
+   * Cache is only used for simple pagination without search/filter/attributes/sort.
+   * @param {CacheValidationParams} params - Parameters to validate
+   * @returns {boolean} True if cache can be used
+   * @public
+   */
+  public canUseCache(params: CacheValidationParams): boolean {
+    const {search, filter, attributes, sortBy} = params;
+
+    return !search && !filter && !attributes && !sortBy;
+  }
+
+  /**
+   * Builds a cache key for the given parameters
+   * @param {string} orgId - Organization ID
+   * @param {number} page - Page number
+   * @param {number} pageSize - Page size
+   * @returns {string} Cache key
+   * @public
+   */
+  public buildCacheKey(orgId: string, page: number, pageSize: number): string {
+    return `${orgId}:${page}:${pageSize}`;
+  }
+
+  /**
+   * Gets a cached page if it exists and is valid
+   * @param {string} cacheKey - Cache key to look up
+   * @returns {PageCacheEntry<T> | null} Cached page entry or null if not found/expired
+   * @public
+   */
+  public getCachedPage(cacheKey: string): PageCacheEntry<T> | null {
+    const cachedEntry = this.cache.get(cacheKey);
+
+    if (!cachedEntry) {
+      return null;
+    }
+
+    // Check if cache entry is expired
+    const now = Date.now();
+    const cacheAge = (now - cachedEntry.timestamp) / (1000 * 60); // in minutes
+
+    if (cacheAge >= DEFAULT_CACHE_TTL_MINUTES) {
+      LoggerProxy.log(`Cache entry expired for key: ${cacheKey}`, {
+        module: this.apiName,
+        method: 'getCachedPage',
+      });
+      this.cache.delete(cacheKey);
+
+      return null;
+    }
+
+    return cachedEntry;
+  }
+
+  /**
+   * Caches a page of data with metadata
+   * @param {string} cacheKey - Cache key
+   * @param {T[]} data - Data items to cache
+   * @param {any} meta - Metadata from API response
+   * @public
+   */
+  public cachePage(cacheKey: string, data: T[], meta?: any): void {
+    const cacheEntry: PageCacheEntry<T> = {
+      data,
+      timestamp: Date.now(),
+      totalMeta: meta
+        ? {
+            totalPages: meta.totalPages,
+            totalRecords: meta.totalRecords || meta.totalItems,
+          }
+        : undefined,
+    };
+
+    this.cache.set(cacheKey, cacheEntry);
+
+    LoggerProxy.log(`Cached page with ${data.length} items for key: ${cacheKey}`, {
+      module: this.apiName,
+      method: 'cachePage',
+    });
+  }
+
+  /**
+   * Clears all cached entries
+   * @public
+   */
+  public clearCache(): void {
+    const cacheSize = this.cache.size;
+    this.cache.clear();
+
+    LoggerProxy.log(`Cleared ${cacheSize} cache entries`, {
+      module: this.apiName,
+      method: 'clearCache',
+    });
+  }
+
+  /**
+   * Gets the current number of cached entries
+   * @returns {number} Number of cached entries
+   * @public
+   */
+  public getCacheSize(): number {
+    return this.cache.size;
+  }
+}
+
+export default PageCache;

package/test/unit/spec/cc.ts

@@ -7,6 +7,11 @@ import {
   WebexSDK,
 } from '../../../src/types';
 import ContactCenter from '../../../src/cc';
+import EntryPoint from '../../../src/services/EntryPoint';
+import type {EntryPointListResponse} from '../../../src/types';
+import AddressBook from '../../../src/services/AddressBook';
+import Queue from '../../../src/services/Queue';
+import type {ContactServiceQueuesResponse} from '../../../src/types';
 import MockWebex from '@webex/test-helper-mock-webex';
 import {StationLoginSuccess, AGENT_EVENTS} from '../../../src/services/agent/types';
 import {SetStateResponse} from '../../../src/types';
@@ -1387,88 +1392,6 @@ describe('webex.cc', () => {
     });
   });
 
-  describe('getQueues', () => {
-    it('should return queues response when successful', async () => {
-      const mockQueuesResponse = [
-        {
-          queueId: 'queue1',
-          queueName: 'Queue 1',
-        },
-        {
-          queueId: 'queue2',
-          queueName: 'Queue 2',
-        },
-      ];
-
-      webex.cc.services.config.getQueues = jest.fn().mockResolvedValue(mockQueuesResponse);
-
-      const result = await webex.cc.getQueues();
-
-      // Verify logging calls
-      expect(LoggerProxy.info).toHaveBeenCalledWith('Fetching queues', {
-        module: CC_FILE,
-        method: 'getQueues',
-      });
-      expect(LoggerProxy.log).toHaveBeenCalledWith(
-        `Successfully retrieved ${result.length} queues`,
-        {
-          module: CC_FILE,
-          method: 'getQueues',
-        }
-      );
-
-      expect(webex.cc.services.config.getQueues).toHaveBeenCalledWith(
-        'mockOrgId',
-        0,
-        100,
-        undefined,
-        undefined
-      );
-      expect(result).toEqual(mockQueuesResponse);
-    });
-
-    it('should throw an error if orgId is not present', async () => {
-      jest.spyOn(webex.credentials, 'getOrgId').mockResolvedValue(undefined);
-      webex.cc.services.config.getQueues = jest.fn();
-
-      try {
-        await webex.cc.getQueues();
-      } catch (error) {
-        expect(error).toEqual(new Error('Org ID not found.'));
-        expect(LoggerProxy.info).toHaveBeenCalledWith('Fetching queues', {
-          module: CC_FILE,
-          method: 'getQueues',
-        });
-        expect(LoggerProxy.error).toHaveBeenCalledWith('Org ID not found.', {
-          module: CC_FILE,
-          method: 'getQueues',
-        });
-        expect(webex.cc.services.config.getQueues).not.toHaveBeenCalled();
-      }
-    });
-
-    it('should throw an error if config getQueues throws an error', async () => {
-      webex.cc.services.config.getQueues = jest.fn().mockRejectedValue(new Error('Test error.'));
-
-      try {
-        await webex.cc.getQueues();
-      } catch (error) {
-        expect(error).toEqual(new Error('Test error.'));
-        expect(LoggerProxy.info).toHaveBeenCalledWith('Fetching queues', {
-          module: CC_FILE,
-          method: 'getQueues',
-        });
-        expect(webex.cc.services.config.getQueues).toHaveBeenCalledWith(
-          'mockOrgId',
-          0,
-          100,
-          undefined,
-          undefined
-        );
-      }
-    });
-  });
-
   describe('uploadLogs', () => {
     it('should upload logs successfully', async () => {
       const uploadLogsMock = jest.spyOn(webex.cc.webexRequest, 'uploadLogs').mockResolvedValue({
@@ -1796,6 +1719,31 @@ describe('webex.cc', () => {
     });
   });
 
+  describe('API property exposure', () => {
+    it('should provide getEntryPoints wrapper that delegates to EntryPoint', async () => {
+      const spy = jest
+        .spyOn(EntryPoint.prototype, 'getEntryPoints')
+        .mockResolvedValue({} as EntryPointListResponse);
+      await webex.cc.getEntryPoints();
+      expect(spy).toHaveBeenCalled();
+      spy.mockRestore();
+    });
+
+    it('should expose addressBook API', () => {
+      expect(webex.cc.addressBook).toBeDefined();
+      expect(webex.cc.addressBook).toBeInstanceOf(AddressBook);
+    });
+
+    it('should provide getQueues wrapper that delegates to Queue', async () => {
+      const spy = jest
+        .spyOn(Queue.prototype, 'getQueues')
+        .mockResolvedValue({} as ContactServiceQueuesResponse);
+      await webex.cc.getQueues();
+      expect(spy).toHaveBeenCalled();
+      spy.mockRestore();
+    });
+  });
+
   describe('updateAgentProfile', () => {
     beforeEach(() => {
       webex.cc.agentConfig = {

package/test/unit/spec/metrics/MetricsManager.ts

@@ -3,7 +3,6 @@ import MetricsManager from '../../../../src/metrics/MetricsManager';
 import {METRIC_EVENT_NAMES} from '../../../../src/metrics/constants';
 import {WebexSDK} from '../../../../src/types';
 import {EventPayload} from '@webex/internal-plugin-metrics/src/metrics.types';
-import LoggerProxy from '../../../../src/logger-proxy';
 
 describe('MetricsManagerImplementation', () => {
   let webex: WebexSDK;

package/test/unit/spec/metrics/behavioral-events.ts

@@ -12,6 +12,20 @@ describe('metrics/behavioral-events', () => {
         verb: 'set',
       });
 
+      expect(getEventTaxonomy(METRIC_EVENT_NAMES.AGENT_CONTACT_ASSIGN_FAILED)).toEqual({
+        product,
+        agent: 'service',
+        target: 'agent_contact_assign',
+        verb: 'fail',
+      });
+
+      expect(getEventTaxonomy(METRIC_EVENT_NAMES.AGENT_INVITE_FAILED)).toEqual({
+        product,
+        agent: 'service',
+        target: 'agent_invite',
+        verb: 'fail',
+      });
+
       expect(getEventTaxonomy(METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS)).toEqual({
         product,
         agent: 'user',