@webex/contact-center 3.9.0-next.9 → 3.10.0

package/src/types.ts

@@ -7,6 +7,7 @@ import {
 import * as Agent from './services/agent/types';
 import * as Contact from './services/task/types';
 import {Profile} from './services/config/types';
+import {PaginatedResponse, BaseSearchParams} from './utils/PageCache';
 
 /**
  * Generic type for converting a const enum object into a union type of its values.
@@ -192,6 +193,10 @@ export interface LogContext {
   method?: string;
   interactionId?: string;
   trackingId?: string;
+  /** Additional structured data to include in logs */
+  data?: Record<string, any>;
+  /** Error object to include in logs */
+  error?: Error | unknown;
 }
 
 /**
@@ -620,6 +625,181 @@ export type StationReLoginResponse = Agent.ReloginSuccess | Error;
  */
 export type SetStateResponse = Agent.StateChangeSuccess | Error;
 
+/**
+ * AddressBook types
+ */
+export interface AddressBookEntry {
+  id: string;
+  organizationId?: string;
+  version?: number;
+  name: string;
+  number: string;
+  createdTime?: number;
+  lastUpdatedTime?: number;
+}
+
+export type AddressBookEntriesResponse = PaginatedResponse<AddressBookEntry>;
+
+export interface AddressBookEntrySearchParams extends BaseSearchParams {
+  addressBookId?: string;
+}
+
+/**
+ * EntryPointRecord types
+ */
+export interface EntryPointRecord {
+  id: string;
+  name: string;
+  description?: string;
+  type: string;
+  isActive: boolean;
+  orgId: string;
+  createdAt?: string;
+  updatedAt?: string;
+  settings?: Record<string, any>;
+}
+
+export type EntryPointListResponse = PaginatedResponse<EntryPointRecord>;
+export type EntryPointSearchParams = BaseSearchParams;
+
+/**
+ * Queue types
+ */
+export interface QueueSkillRequirement {
+  organizationId?: string;
+  id?: string;
+  version?: number;
+  skillId: string;
+  skillName?: string;
+  skillType?: string;
+  condition: string;
+  skillValue: string;
+  createdTime?: number;
+  lastUpdatedTime?: number;
+}
+
+export interface QueueAgent {
+  id: string;
+  ciUserId?: string;
+}
+
+export interface AgentGroup {
+  teamId: string;
+}
+
+export interface CallDistributionGroup {
+  agentGroups: AgentGroup[];
+  order: number;
+  duration?: number;
+}
+
+export interface AssistantSkillMapping {
+  assistantSkillId?: string;
+  assistantSkillUpdatedTime?: number;
+}
+
+/**
+ * Configuration for a contact service queue
+ * @public
+ */
+export interface ContactServiceQueue {
+  /** Organization ID */
+  organizationId?: string;
+  /** Unique identifier for the queue */
+  id?: string;
+  /** Version of the queue */
+  version?: number;
+  /** Name of the Contact Service Queue */
+  name: string;
+  /** Description of the queue */
+  description?: string;
+  /** Queue type (INBOUND, OUTBOUND) */
+  queueType: 'INBOUND' | 'OUTBOUND';
+  /** Whether to check agent availability */
+  checkAgentAvailability: boolean;
+  /** Channel type (TELEPHONY, EMAIL, SOCIAL_CHANNEL, CHAT, etc.) */
+  channelType: 'TELEPHONY' | 'EMAIL' | 'FAX' | 'CHAT' | 'VIDEO' | 'OTHERS' | 'SOCIAL_CHANNEL';
+  /** Social channel type for SOCIAL_CHANNEL channelType */
+  socialChannelType?:
+    | 'MESSAGEBIRD'
+    | 'MESSENGER'
+    | 'WHATSAPP'
+    | 'APPLE_BUSINESS_CHAT'
+    | 'GOOGLE_BUSINESS_MESSAGES';
+  /** Service level threshold in seconds */
+  serviceLevelThreshold: number;
+  /** Maximum number of simultaneous contacts */
+  maxActiveContacts: number;
+  /** Maximum time in queue in seconds */
+  maxTimeInQueue: number;
+  /** Default music in queue media file ID */
+  defaultMusicInQueueMediaFileId: string;
+  /** Timezone for routing strategies */
+  timezone?: string;
+  /** Whether the queue is active */
+  active: boolean;
+  /** Whether outdial campaign 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 recording is permitted */
+  pauseRecordingPermitted: boolean;
+  /** Recording pause duration in seconds */
+  recordingPauseDuration?: number;
+  /** Control flow script URL */
+  controlFlowScriptUrl: string;
+  /** IVR requeue URL */
+  ivrRequeueUrl: string;
+  /** Overflow number for telephony */
+  overflowNumber?: string;
+  /** Vendor ID */
+  vendorId?: string;
+  /** Routing type */
+  routingType: 'LONGEST_AVAILABLE_AGENT' | 'SKILLS_BASED' | 'CIRCULAR' | 'LINEAR';
+  /** Skills-based routing type */
+  skillBasedRoutingType?: 'LONGEST_AVAILABLE_AGENT' | 'BEST_AVAILABLE_AGENT';
+  /** Queue routing type */
+  queueRoutingType: 'TEAM_BASED' | 'SKILL_BASED' | 'AGENT_BASED';
+  /** Queue skill requirements */
+  queueSkillRequirements?: QueueSkillRequirement[];
+  /** List of agents for agent-based queue */
+  agents?: QueueAgent[];
+  /** Call distribution groups */
+  callDistributionGroups: CallDistributionGroup[];
+  /** XSP version */
+  xspVersion?: string;
+  /** Subscription ID */
+  subscriptionId?: string;
+  /** Assistant skill mapping */
+  assistantSkill?: AssistantSkillMapping;
+  /** Whether this is a system default queue */
+  systemDefault?: boolean;
+  /** User who last updated agents list */
+  agentsLastUpdatedByUserName?: string;
+  /** Email of user who last updated agents list */
+  agentsLastUpdatedByUserEmailPrefix?: string;
+  /** When agents list was last updated */
+  agentsLastUpdatedTime?: number;
+  /** Creation timestamp in epoch millis */
+  createdTime?: number;
+  /** Last updated timestamp in epoch millis */
+  lastUpdatedTime?: number;
+}
+
+export type ContactServiceQueuesResponse = PaginatedResponse<ContactServiceQueue>;
+
+export interface ContactServiceQueueSearchParams extends BaseSearchParams {
+  desktopProfileFilter?: boolean;
+  provisioningView?: boolean;
+  singleObjectResponse?: boolean;
+}
+
 /**
  * Response type for buddy agents query operations.
  * Either a success response with list of buddy agents or an error.

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;