@webex/contact-center 3.12.0-next.13 → 3.12.0-next.130

package/src/services/core/Utils.ts

@@ -4,14 +4,22 @@ import {Failure, AugmentedError} from './GlobalTypes';
 import LoggerProxy from '../../logger-proxy';
 import WebexRequest from './WebexRequest';
 import {
+  ConsultConferenceData,
+  consultConferencePayloadData,
+  ConsultTransferDestinationType,
   TaskData,
-  ConsultTransferPayLoad,
   CONSULT_TRANSFER_DESTINATION_TYPE,
+  DESTINATION_TYPE,
   Interaction,
+  InteractionParticipant,
 } from '../task/types';
 import {PARTICIPANT_TYPES, STATE_CONSULT} from './constants';
 import {DialPlan} from '../config/types';
 
+/** Returns whether a value is a non-null object with string keys. */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
 /**
  * Extracts common error details from a Webex request payload.
  *
@@ -28,55 +36,68 @@ 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.
+ * Strips characters defined in the dial plan entry from the input string.
+ *
+ * @param input - The dial number to sanitize
+ * @param strippedChars - String of characters to remove from the input
+ * @returns The sanitized input with specified characters removed
  */
-const getAgentActionTypeFromTask = (taskData?: TaskData): 'DIAL_NUMBER' | '' => {
-  const destAgentType = taskData?.destinationType;
+export const stripDialPlanChars = (input: string, strippedChars: string): string => {
+  if (!strippedChars) {
+    return input;
+  }
 
-  // Check if destination requires dialing: direct dial number or entry point variants
-  const isDialNumber = destAgentType === 'DN';
-  const isEntryPointVariant = isEntryPointOrEpdn(destAgentType);
+  const charsToStrip = new Set(strippedChars.split(''));
 
-  // If the destination type is a dial number or an entry point variant, return 'DIAL_NUMBER'
-  return isDialNumber || isEntryPointVariant ? 'DIAL_NUMBER' : '';
+  return input
+    .split('')
+    .filter((c) => !charsToStrip.has(c))
+    .join('');
 };
 
-// Fallback regex for US/Canada dial numbers when no dial plan entries are configured
-export const FALLBACK_DIAL_NUMBER_REGEX = /1[0-9]{3}[2-9][0-9]{6}([,]{1,10}[0-9]+){0,1}/;
-
 /**
  * Validates a dial number against the provided dial plan regex patterns.
  * A number is valid if it matches at least one regex pattern in the dial plans.
- * Falls back to US/Canada regex validation if no dial plan entries are configured.
+ * Skips validation when no dial plan entries are configured, deferring to the server.
  *
  * @param input - The dial number to validate
  * @param dialPlanEntries - Array of dial plan entries containing regex patterns
- * @returns true if the input matches at least one dial plan regex pattern, false otherwise
+ * @returns true if the input matches at least one dial plan regex pattern or no entries are configured, false otherwise
  */
 export const isValidDialNumber = (
   input: string,
   dialPlanEntries: DialPlan['dialPlanEntity']
 ): boolean => {
+  if (!input) {
+    LoggerProxy.warn('Dial number is empty or undefined.', {
+      module: 'Utils',
+      method: 'isValidDialNumber',
+    });
+
+    return false;
+  }
+
   if (!dialPlanEntries || dialPlanEntries.length === 0) {
-    LoggerProxy.info('No dial plan entries found. Falling back to US number validation.');
+    LoggerProxy.log(
+      'No dial plan entries found. Skipping client-side validation, deferring to server.',
+      {module: 'Utils', method: 'isValidDialNumber'}
+    );
 
-    return FALLBACK_DIAL_NUMBER_REGEX.test(input);
+    return true;
   }
 
   return dialPlanEntries.some((entry) => {
     try {
+      const sanitizedInput = stripDialPlanChars(input, entry.strippedChars);
       const regex = new RegExp(entry.regex);
 
-      return regex.test(input);
-    } catch {
+      return regex.test(sanitizedInput);
+    } catch (e) {
+      LoggerProxy.warn(`Failed to validate dial number against entry "${entry.name}": ${e}`, {
+        module: 'Utils',
+        method: 'isValidDialNumber',
+      });
+
       return false;
     }
   });
@@ -243,6 +264,7 @@ export const createErrDetailsObject = (errObj: WebexRequestPayload) => {
   return new Err.Details('Service.reqs.generic.failure', details);
 };
 
+/*
 /**
  * Gets the consulted agent ID from the media object by finding the agent
  * in the consult media participants (excluding the current agent).
@@ -321,9 +343,16 @@ export const calculateDestAgentId = (interaction: Interaction, agentId: string):
     return destAgentIdCBT;
   }
 
-  return interaction.participants[consultingAgent]?.type === PARTICIPANT_TYPES.EP_DN
-    ? interaction.participants[consultingAgent]?.epId
-    : interaction.participants[consultingAgent]?.id;
+  const participant = interaction.participants[consultingAgent];
+  if (!participant) {
+    return '';
+  }
+
+  if (participant.type === PARTICIPANT_TYPES.EP_DN) {
+    return (participant as InteractionParticipant & {epId?: string}).epId ?? '';
+  }
+
+  return participant.id ?? '';
 };
 
 /**
@@ -358,16 +387,77 @@ export const calculateDestType = (interaction: Interaction, agentId: string): st
   return CONSULT_TRANSFER_DESTINATION_TYPE.AGENT;
 };
 
+/**
+ * Gets the destination agent ID from participants.
+ * Finds a participant who is not the current agent and is an agent type.
+ *
+ * @param participants - The participants object from interaction
+ * @param agentId - The current agent's ID
+ * @returns The destination agent ID, or undefined if none found
+ */
+export const buildConsultConferenceParamData = (
+  dataPassed: consultConferencePayloadData,
+  interactionIdPassed: string
+): {interactionId: string; data: ConsultConferenceData} => {
+  const data: ConsultConferenceData = {
+    ...('agentId' in dataPassed && {agentId: dataPassed.agentId}),
+    to: dataPassed.destAgentId,
+    destinationType: '',
+  };
+
+  if ('destinationType' in dataPassed) {
+    const destinationType = String(dataPassed.destinationType || '').trim();
+    const normalizedDestinationType = destinationType.toUpperCase().replace(/[-_\s]/g, '');
+
+    if (normalizedDestinationType === 'DN' || normalizedDestinationType === 'DIALNUMBER') {
+      data.destinationType = DESTINATION_TYPE.DIALNUMBER;
+    } else if (normalizedDestinationType === 'EPDN' || normalizedDestinationType === 'ENTRYPOINT') {
+      data.destinationType = DESTINATION_TYPE.ENTRYPOINT;
+    } else if (normalizedDestinationType === 'QUEUE') {
+      data.destinationType = DESTINATION_TYPE.QUEUE;
+    } else if (normalizedDestinationType === 'AGENT') {
+      data.destinationType = DESTINATION_TYPE.AGENT;
+    } else {
+      data.destinationType = destinationType as ConsultConferenceData['destinationType'];
+    }
+  } else {
+    data.destinationType = DESTINATION_TYPE.AGENT;
+  }
+
+  return {
+    interactionId: interactionIdPassed,
+    data,
+  };
+};
+
+/**
+ * Derives the consult transfer destination type based on task data.
+ * This function determines the appropriate destination type for a consult transfer
+ * by examining the destination type stored in the task data.
+ *
+ * @param taskData - The task data containing destination information
+ * @returns The derived consult transfer destination type
+ * @public
+ */
 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;
+  taskData: TaskData
+): ConsultTransferDestinationType => {
+  const destType = taskData?.destinationType;
+  const normalizedDestType = String(destType || '')
+    .toUpperCase()
+    .replace(/[-_\s]/g, '');
+
+  // Map destination types to consult transfer destination types
+  if (normalizedDestType === 'DN' || normalizedDestType === 'DIALNUMBER') {
+    return CONSULT_TRANSFER_DESTINATION_TYPE.DIALNUMBER;
+  }
+  if (normalizedDestType === 'EPDN' || normalizedDestType === 'ENTRYPOINT') {
+    return CONSULT_TRANSFER_DESTINATION_TYPE.ENTRYPOINT;
+  }
+  if (normalizedDestType === 'QUEUE') {
+    return CONSULT_TRANSFER_DESTINATION_TYPE.QUEUE;
   }
 
+  // Default to agent if no specific type matches
   return CONSULT_TRANSFER_DESTINATION_TYPE.AGENT;
 };

package/src/services/core/WebexRequest.ts

@@ -34,14 +34,16 @@ class WebexRequest {
     resource: string;
     method: HTTP_METHODS;
     body?: RequestBody;
+    headers?: Record<string, string | null>;
   }): Promise<IHttpResponse> {
-    const {service, resource, method, body} = options;
+    const {service, resource, method, body, headers} = options;
 
     return this.webex.request({
       service,
       resource,
       method,
       body,
+      ...(headers ? {headers} : {}),
     });
   }
 

package/src/services/core/ai-docs/AGENTS.md

@@ -0,0 +1,381 @@
+# Core Service - AI Agent Guide
+
+> **Legacy/reference-only.** Canonical SDD: [`core-spec.md`](core-spec.md). Use the package [manifest](../../../../.sdd/manifest.json) and [`SPEC_INDEX.md`](../../../../ai-docs/SPEC_INDEX.md) for routing; code and tests remain the behavioral referee.
+>
+> **Legacy scope:** Core infrastructure components include WebSocket management, HTTP requests, error handling, and utilities. For repository rules and cross-service patterns, see the [root orchestrator AGENTS.md](../../../../AGENTS.md).
+
+---
+
+## Key Capabilities
+
+The Core service provides the foundational infrastructure layer that all other services depend on:
+
+- **WebSocket Communication**: Real-time bidirectional messaging with the contact center backend, including automatic reconnection and keepalive management
+- **HTTP Request Handling**: Authenticated REST API calls to WCC API Gateway with built-in error handling and log upload support
+- **AQM Request/Response Pattern**: A structured pattern used by the routing and contact layers to send HTTP requests to the contact center backend and correlate responses/failures via WebSocket notifications
+- **Error Handling & Logging**: Standardized error extraction, logging via `LoggerProxy`, and log upload utilities that all services use for consistent error reporting
+
+| Component | File | Description |
+|-----------|------|-------------|
+| `WebSocketManager` | [`WebSocketManager.ts`](../websocket/WebSocketManager.ts) | Manages the WebSocket connection lifecycle including initialization, message dispatch, and graceful shutdown. Emits `message` events for incoming data and `socketClose` when the connection drops while reconnect is allowed. |
+| `ConnectionService` | [`connection-service.ts`](../websocket/connection-service.ts) | Orchestrates reconnection logic and keepalive heartbeats on top of `WebSocketManager`. Detects connection loss and triggers `silentRelogin()` to restore agent state transparently. |
+| `WebexRequest` | [`WebexRequest.ts`](../WebexRequest.ts) | Singleton HTTP client that wraps authenticated requests to the WCC API Gateway. Handles service routing, response parsing, and provides a `uploadLogs` method for diagnostics. |
+| `AqmReqs` | [`aqm-reqs.ts`](../aqm-reqs.ts) | Factory for creating request methods that send HTTP requests and wait for correlated WebSocket notifications (success or failure). Used by routing and task services to implement their API methods. |
+| `Utils` | [`Utils.ts`](../Utils.ts) | Shared utility functions including `getErrorDetails()` for standardized error handling, `generateTaskErrorObject()` for task-specific errors, and `createErrDetailsObject()` for constructing error detail objects. |
+| `Err` | [`Err.ts`](../Err.ts) | Error class definitions. `Err.Details` carries structured error metadata (status, type, trackingId) for consistent error propagation. |
+| `constants` | [`constants.ts`](../constants.ts) | Timeout values, interval durations, participant types, interaction states, and method name constants used throughout the core layer. Any new constants for core should be defined here. |
+
+---
+
+## File Structure
+
+```
+services/core/
+├── aqm-reqs.ts           # AQM request handler
+├── constants.ts          # Core constants
+├── Err.ts                # Error classes
+├── GlobalTypes.ts        # Failure, Msg<T>, etc.
+├── types.ts              # Request/response types
+├── Utils.ts              # Utility functions
+├── WebexRequest.ts       # HTTP client
+└── websocket/
+    ├── WebSocketManager.ts    # Main WS handler
+    ├── connection-service.ts  # Connection lifecycle
+    ├── keepalive.worker.js    # Keepalive worker
+    └── types.ts               # WS types
+```
+
+---
+
+
+## WebSocketManager
+
+`WebSocketManager` handles the raw WebSocket connection to the contact center backend. It is instantiated by the `Services` layer and used internally — other services interact with it through `ConnectionService`.
+
+### Reference Usage
+
+```typescript
+// Initialize in Services
+this.webSocketManager = new WebSocketManager({webex});
+
+// Connect
+const welcomeEvent = await webSocketManager.initWebSocket({
+  body: connectionConfig,
+});
+
+// Listen for messages
+webSocketManager.on('message', (event) => {
+  const data = JSON.parse(event);
+  // Handle event
+});
+
+// Close
+webSocketManager.close(false, 'Reason');
+```
+
+### Events
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `message` | string (JSON) | WebSocket message received |
+| `socketClose` | - | Socket closed while reconnect is allowed |
+
+### Connection Lifecycle
+
+`WebSocketManager` and `ConnectionService` work together to manage the full connection lifecycle. `WebSocketManager` owns the raw socket while `ConnectionService` adds reconnection intelligence and keepalive on top.
+
+**Connection Flow:**
+
+```
+1. initWebSocket() called
+2. ConnectionService listeners attached (`message`, `socketClose`) during construction
+3. WebSocket connects to backend
+4. Keepalive worker started on `onopen`
+5. Welcome event received
+6. Runtime messages/keepalive processed via existing listeners
+```
+
+**Reconnection Flow:**
+
+```
+1. Connection lost detected
+2. ConnectionService emits 'connectionLost'
+3. cc.handleConnectionLost() called
+4. silentRelogin() attempted
+5. On success: state restored
+6. On AGENT_NOT_FOUND: handle silently
+```
+
+### Keepalive
+
+A Web Worker ([`keepalive.worker.js`](../websocket/keepalive.worker.js)) runs alongside the WebSocket to detect connection loss and keep the socket alive. It starts on `onopen` and sends `{keepalive: 'true'}` to the backend every **4 seconds** (`KEEPALIVE_WORKER_INTERVAL`). The worker also monitors `navigator.onLine` — if the network goes offline and the socket doesn't close within **16 seconds** (`CLOSE_SOCKET_TIMEOUT`), it force-closes the socket.
+
+On the receiving side, `ConnectionService.onPing()` listens for all WebSocket messages and resets two timers on each message:
+- **`reconnectingTimer`** (8s / `WS_DISCONNECT_ALLOWED`) — if no message arrives within 8s, marks connection as lost
+- **`restoreTimer`** (`lostConnectionRecoveryTimeout` from agent config) — if connection isn't restored within this window, marks restore as failed
+
+When a keepalive response arrives after a lost-connection state, `ConnectionService` resets its flags and dispatches a recovery event. If the socket fully closes, `ConnectionService` retries `initWebSocket()` every **5 seconds** (`CONNECTIVITY_CHECK_INTERVAL`).
+
+---
+
+## WebexRequest
+
+`WebexRequest` is a singleton HTTP client that all services use to make authenticated REST API calls to the contact center backend. It handles service URL resolution, request formatting, and response parsing.
+
+### The `service` Property
+
+The `service` field in request options is a **service identifier string** that the Webex SDK's internal service catalog (`this.webex.request()`) resolves to a base URL at runtime. All contact center API calls use:
+
+```typescript
+import {WCC_API_GATEWAY} from '../constants';
+// WCC_API_GATEWAY = 'wcc-api-gateway'
+```
+
+This constant is defined in [`services/constants.ts`](../../constants.ts). The Webex SDK maps `'wcc-api-gateway'` to the appropriate contact center API gateway URL based on the environment. The `resource` is then appended as the path.
+
+### Reference Usage
+
+```typescript
+// Get singleton
+const webexReq = WebexRequest.getInstance({webex});
+
+// Make request
+const response = await webexReq.request({
+  service: WCC_API_GATEWAY,  // resolved to base URL by Webex SDK
+  resource: '/v1/endpoint',  // appended as path
+  method: HTTP_METHODS.POST,
+  body: { key: 'value' },   // optional request payload
+});
+
+// Upload logs
+await webexReq.uploadLogs({
+  correlationId: trackingId,
+});
+```
+
+### Response Structure
+
+```typescript
+{
+  statusCode: 200,
+  body: { /* response data */ },
+  headers: {
+    trackingid: 'uuid',
+  },
+}
+```
+
+---
+
+## AqmReqs
+
+The AQM (Agent Queue Manager) layer provides a request/response pattern over HTTP + WebSocket. Services like **routing** and **contact** use `AqmReqs` to define API methods that:
+
+1. Send an HTTP request to the contact center backend via `WebexRequest`
+2. Wait for a correlated WebSocket notification indicating success or failure
+3. Return the typed result or throw a structured error
+
+This decouples the request initiation (HTTP) from the asynchronous result delivery (WebSocket), which matches the contact center backend's event-driven architecture.
+
+### Reference Usage
+
+```typescript
+// Define request configuration
+const serviceMethod = routing.req((p: {data: ParamType}) => ({
+  url: '/v1/endpoint',
+  host: WCC_API_GATEWAY,
+  data: p.data,
+  method: HTTP_METHODS.POST,
+  err: errorHandler,
+  notifSuccess: {
+    bind: {type: CC_EVENTS.SUCCESS, data: {type: CC_EVENTS.SUCCESS}},
+    msg: {} as SuccessType,
+  },
+  notifFail: {
+    bind: {type: CC_EVENTS.FAIL, data: {type: CC_EVENTS.FAIL}},
+    errId: 'Service.aqm.operation',
+  },
+}));
+
+// Call method
+const result = await serviceMethod({data: params});
+```
+
+---
+
+## Error Handling Utilities
+
+### `getErrorDetails()`
+
+Standard error handler for SDK operations:
+
+```typescript
+import {getErrorDetails} from './services/core/Utils';
+
+try {
+  await operation();
+} catch (error) {
+  const {error: detailedError, reason} = getErrorDetails(
+    error,
+    'methodName',  // Method name for logging
+    'ModuleName'   // Module name for logging
+  );
+
+  // getErrorDetails automatically:
+  // 1. Logs the error
+  // 2. Uploads logs (unless AGENT_NOT_FOUND in silentRelogin)
+  // 3. Extracts reason from error.details
+  // 4. Creates Error with reason as message
+
+  throw detailedError;
+}
+```
+
+### `generateTaskErrorObject()`
+
+Error handler for task operations:
+
+```typescript
+import {generateTaskErrorObject} from './services/core/Utils';
+
+try {
+  await taskOperation();
+} catch (error) {
+  const taskError = generateTaskErrorObject(
+    error,
+    'transfer',
+    'TaskModule'
+  );
+  throw taskError;
+}
+```
+
+---
+
+## Type Definitions
+
+### Msg\<T\>
+
+Generic message wrapper used throughout the SDK. All WebSocket messages and AQM responses conform to this shape:
+
+```typescript
+export type Msg<T = any> = {
+  type: string;       // Message/Event type identifier
+  orgId: string;      // Organization identifier
+  trackingId: string; // Unique tracking identifier
+  data: T;            // Message/Event payload data
+};
+
+// Usage — the payload type goes into `data`
+export type LoginSuccess = Msg<{
+  agentId: string;
+  status: string;
+  // ...
+}>;
+// Resulting shape: { type, orgId, trackingId, data: { agentId, status, ... } }
+```
+
+### Failure
+
+A specific `Msg<T>` for failure responses. Access error details via `failure.data`:
+
+```typescript
+export type Failure = Msg<{
+  agentId: string;
+  trackingId: string;
+  reasonCode: number;
+  orgId: string;
+  reason: string;
+}>;
+
+// Usage in catch
+const failure = error.details as Failure;
+LoggerProxy.error(`Operation failed: ${failure.data?.reason}`, {
+  module: 'MyService',
+  method: 'myMethod',
+  trackingId: failure?.trackingId,
+});
+```
+
+### AugmentedError
+
+Error interface with a flexible data field for additional context:
+
+```typescript
+export interface AugmentedError extends Error {
+  data?: Record<string, any>;
+}
+```
+
+---
+
+## Error Classes
+
+### Err.Details
+
+```typescript
+import * as Err from './Err';
+
+const error = new Err.Details('Service.aqm.agent.login', {
+  status: 401,
+  type: 'UNAUTHORIZED',
+  trackingId: 'uuid',
+});
+```
+
+### createErrDetailsObject
+
+```typescript
+import {createErrDetailsObject} from './Utils';
+
+const errDetails = createErrDetailsObject(webexRequestPayload);
+// Returns Err.Details with trackingId and body
+```
+
+---
+
+## Constants
+
+All core-level constants (timeouts, intervals, participant types, method names) are defined in [`constants.ts`](../constants.ts). Any new constants for the core layer should be added there.
+
+---
+
+## Best Practices
+
+### Always Use Error Utilities
+
+```typescript
+// Correct
+const {error: detailedError} = getErrorDetails(error, method, module);
+throw detailedError;
+
+// Wrong - loses context
+throw error;
+```
+
+### Check Response Status
+
+```typescript
+const response = await webexReq.request({...});
+
+if (response.statusCode !== 200) {
+  throw new Error(`API call failed with ${response.statusCode}`);
+}
+```
+
+### Extract TrackingId
+
+```typescript
+const trackingId = response.headers?.trackingid ||
+                   response.headers?.TrackingID;
+```
+
+---
+
+## Related
+
+- [Root Orchestrator AGENTS.md](../../../../AGENTS.md) - Task routing, critical rules, cross-service patterns
+- [WebSocketManager.ts](../websocket/WebSocketManager.ts)
+- [WebexRequest.ts](../WebexRequest.ts)
+- [Utils.ts](../Utils.ts)
+- [GlobalTypes.ts](../GlobalTypes.ts)