@webex/contact-center 0.0.0-next.1

package/src/services/constants.ts

@@ -0,0 +1,111 @@
+/**
+ * Post-authentication event name.
+ * @type {string}
+ * @public
+ * @example
+ * if (event === POST_AUTH) { ... }
+ * @ignore
+ */
+export const POST_AUTH = 'postauth';
+
+/**
+ * API gateway identifier for Webex Contact Center.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const WCC_API_GATEWAY = 'wcc-api-gateway';
+
+/**
+ * Domain identifier for WCC Calling RTMS.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const WCC_CALLING_RTMS_DOMAIN = 'wcc-calling-rtms-domain';
+
+/**
+ * Default RTMS domain for production use.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const DEFAULT_RTMS_DOMAIN = 'rtw.prod-us1.rtmsprod.net';
+
+/**
+ * Timeout in milliseconds for WebSocket events.
+ * @type {number}
+ * @public
+ * @example
+ * setTimeout(() => { ... }, WEBSOCKET_EVENT_TIMEOUT);
+ * @ignore
+ */
+export const WEBSOCKET_EVENT_TIMEOUT = 20000;
+
+/**
+ * Agent role identifier.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const AGENT = 'agent';
+
+// CC GATEWAY API URL PATHS
+/**
+ * API path for notification subscription.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const SUBSCRIBE_API = 'v1/notification/subscribe';
+
+/**
+ * API path for agent login.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const LOGIN_API = 'v1/agents/login';
+
+/**
+ * Prefix for WebRTC-related API endpoints.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const WEB_RTC_PREFIX = 'webrtc-';
+
+/**
+ * API path for agent session state changes.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const STATE_CHANGE_API = 'v1/agents/session/state';
+
+/**
+ * Message for deregistering WebCalling line and cleaning up resources.
+ * @type {string}
+ * @public
+ * @ignore
+ */
+export const DEREGISTER_WEBCALLING_LINE_MSG =
+  'Deregistering WebCalling line and cleaning up resources';
+
+// WebCallingService method names
+export const METHODS = {
+  SET_LOGIN_OPTION: 'setLoginOption',
+  HANDLE_MEDIA_EVENT: 'handleMediaEvent',
+  HANDLE_DISCONNECT_EVENT: 'handleDisconnectEvent',
+  REGISTER_CALL_LISTENERS: 'registerCallListeners',
+  CLEAN_UP_CALL: 'cleanUpCall',
+  GET_RTMS_DOMAIN: 'getRTMSDomain',
+  REGISTER_WEB_CALLING_LINE: 'registerWebCallingLine',
+  DEREGISTER_WEB_CALLING_LINE: 'deregisterWebCallingLine',
+  ANSWER_CALL: 'answerCall',
+  MUTE_UNMUTE_CALL: 'muteUnmuteCall',
+  IS_CALL_MUTED: 'isCallMuted',
+  DECLINE_CALL: 'declineCall',
+  MAP_CALL_TO_TASK: 'mapCallToTask',
+  GET_TASK_ID_FOR_CALL: 'getTaskIdForCall',
+};

package/src/services/core/Err.ts

@@ -0,0 +1,126 @@
+import {WebexRequestPayload} from '../../types';
+import {Failure} from './GlobalTypes';
+
+/**
+ * Err module provides a structured way to handle errors in the Contact Center plugin.
+ * @ignore
+ */
+
+export type ErrDetails = {status: number; type: string; trackingId: string};
+
+export type AgentErrorIds =
+  | {'Service.aqm.agent.stationLogin': ErrDetails}
+  | {'Service.aqm.agent.stationLoginFailed': Failure}
+  | {'Service.aqm.agent.stateChange': Failure}
+  | {'Service.aqm.agent.reload': Failure}
+  | {'Service.aqm.agent.logout': Failure}
+  | {'Service.reqs.generic.failure': {trackingId: string}}
+  | {'Service.aqm.agent.BuddyAgentsRetrieveFailed': Failure};
+
+export type vteamType = 'inboundqueue' | 'inboundentrypoint' | string;
+
+export type TaskErrorIds =
+  | {'Service.aqm.task.accept': Failure}
+  | {'Service.aqm.task.end': Failure}
+  | {'Service.aqm.task.wrapup': Failure}
+  | {'Service.aqm.task.AgentVteamTransferFailed': Failure}
+  | {'Service.aqm.task.AgentBlindTransferFailedEvent': Failure}
+  | {'Service.aqm.task.AgentConsultTransferFailed': Failure}
+  | {'Service.aqm.task.consult': Failure}
+  | {'Service.aqm.err.trackingId': {trackingId: string}}
+  | {'Service.aqm.task.consultAccept': Failure}
+  | {'Service.aqm.task.consultConference': Failure}
+  | {'Service.aqm.task.consultEnd': Failure}
+  | {'Service.aqm.task.cancelCtq': Failure}
+  | {'Service.aqm.task.hold': Failure}
+  | {'Service.aqm.task.unHold': Failure}
+  | {'Service.aqm.task.VteamListFailed': Failure}
+  | {'Service.aqm.task.pauseRecording': Failure}
+  | {'Service.aqm.task.resumeRecording': Failure}
+  | {'Service.aqm.dialer.startOutdial': Failure}
+  | {'Service.reqs.generic.failure': {trackingId: string}};
+
+export type ReqError =
+  | 'Service.aqm.reqs.GenericRequestError'
+  | {'Service.aqm.reqs.Pending': {key: string; msg: string}}
+  | {'Service.aqm.reqs.PendingEvent': {key: string}}
+  | {'Service.aqm.reqs.Timeout': {key: string; response: WebexRequestPayload}}
+  | {'Service.aqm.reqs.TimeoutEvent': {key: string}};
+
+export interface Ids {
+  'Service.aqm.agent': AgentErrorIds;
+  'Service.aqm.reqs': ReqError;
+  'Service.aqm.task': TaskErrorIds;
+}
+
+export type IdsGlobal =
+  | 'system' // to handle errors that was not created by 'new Err.WithId()'
+  | 'handle'
+  | 'fallback';
+
+export type IdsSub = Ids[keyof Ids];
+
+export type IdsMessage = IdsGlobal | keyof Ids | Exclude<IdsSub, object>;
+
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I
+) => void
+  ? I
+  : never;
+
+export type FlattenUnion<T> = {
+  [K in keyof UnionToIntersection<T>]: K extends keyof T
+    ? T[K] extends any[]
+      ? T[K]
+      : T[K] extends object
+      ? FlattenUnion<T[K]>
+      : T[K]
+    : UnionToIntersection<T>[K];
+};
+export type IdsDetailsType = FlattenUnion<Exclude<IdsSub, string>>;
+
+export type IdsDetails = keyof IdsDetailsType;
+
+export type Id = IdsMessage | IdsDetails;
+
+export class Message extends Error {
+  readonly id: Id;
+
+  constructor(id: IdsMessage);
+  constructor(id: IdsMessage, message: string);
+  constructor(id: IdsMessage, errror: Error);
+  constructor(id: IdsMessage, value?: string | Error) {
+    super();
+
+    this.id = id;
+    this.stack = new Error().stack!;
+
+    if (typeof value === 'string') {
+      this.message = value;
+    } else if (value instanceof Error) {
+      this.message = value.message;
+      this.name = value.name;
+    } else {
+      this.message = '';
+    }
+  }
+
+  // Marker to distinct Err class from other errors
+  private isErr = 'yes';
+}
+
+export class Details<T extends IdsDetails> extends Error {
+  readonly id: Id;
+  readonly details: IdsDetailsType[T];
+
+  constructor(id: T, details: IdsDetailsType[T]) {
+    super();
+
+    this.id = id;
+    this.stack = new Error().stack!;
+    this.details = details;
+  }
+
+  // Marker to distinct Err class from other errors
+  private isErr = 'yes';
+}

package/src/services/core/GlobalTypes.ts

@@ -0,0 +1,34 @@
+/**
+ * Generic message interface used throughout the plugin
+ * @template T - Type of the data payload (defaults to any)
+ * @private
+ * @ignore
+ */
+export type Msg<T = any> = {
+  /** Message/Event type identifier */
+  type: string;
+  /** Organization identifier */
+  orgId: string;
+  /** Unique tracking identifier for the message/Event */
+  trackingId: string;
+  /** Message/Event payload data */
+  data: T;
+};
+
+/**
+ * Represents a failure message with specific error details
+ * @private
+ * @ignore
+ */
+export type Failure = Msg<{
+  /** Agent identifier associated with the failure */
+  agentId: string;
+  /** Tracking identifier for the failure event */
+  trackingId: string;
+  /** Numeric code indicating the reason for failure */
+  reasonCode: number;
+  /** Organization identifier */
+  orgId: string;
+  /** Human-readable description of the failure reason */
+  reason: string;
+}>;

package/src/services/core/Utils.ts

@@ -0,0 +1,132 @@
+import * as Err from './Err';
+import {LoginOption, WebexRequestPayload} from '../../types';
+import {Failure} from './GlobalTypes';
+import LoggerProxy from '../../logger-proxy';
+import WebexRequest from './WebexRequest';
+
+/**
+ * Extracts common error details from a Webex request payload.
+ *
+ * @param errObj - The Webex request payload object.
+ * @returns An object containing the tracking ID and message body.
+ * @private
+ * @ignore
+ */
+const getCommonErrorDetails = (errObj: WebexRequestPayload) => {
+  return {
+    trackingId: errObj?.headers?.trackingid || errObj?.headers?.TrackingID,
+    msg: errObj?.body,
+  };
+};
+
+export const isValidDialNumber = (input: string): boolean => {
+  // This regex checks for a valid dial number format for only few countries such as US, Canada.
+  const regexForDn = /1[0-9]{3}[2-9][0-9]{6}([,]{1,10}[0-9]+){0,1}/;
+
+  return regexForDn.test(input);
+};
+
+export const getStationLoginErrorData = (failure: Failure, loginOption: LoginOption) => {
+  let duplicateLocationMessage = 'This value is already in use';
+
+  if (loginOption === LoginOption.EXTENSION) {
+    duplicateLocationMessage = 'This extension is already in use';
+  }
+
+  if (loginOption === LoginOption.AGENT_DN) {
+    duplicateLocationMessage =
+      'Dial number is in use. Try a different one. For help, reach out to your administrator or support team.';
+  }
+
+  const errorCodeMessageMap = {
+    DUPLICATE_LOCATION: {
+      message: duplicateLocationMessage,
+      fieldName: loginOption,
+    },
+    INVALID_DIAL_NUMBER: {
+      message:
+        'Enter a valid US dial number. For help, reach out to your administrator or support team.',
+      fieldName: loginOption,
+    },
+  };
+
+  const defaultMessage = 'An error occurred while logging in to the station';
+  const defaultFieldName = 'generic';
+
+  const reason = failure?.data?.reason || '';
+
+  return {
+    message: errorCodeMessageMap[reason]?.message || defaultMessage,
+    fieldName: errorCodeMessageMap[reason]?.fieldName || defaultFieldName,
+  };
+};
+
+/**
+ * Extracts error details and logs the error. Also uploads logs for the error unless it is a silent relogin agent not found error.
+ *
+ * @param error - The error object, expected to have a `details` property of type Failure.
+ * @param methodName - The name of the method where the error occurred.
+ * @param moduleName - The name of the module where the error occurred.
+ * @returns An object containing the error instance and the reason string.
+ * @public
+ * @example
+ * const details = getErrorDetails(error, 'fetchData', 'DataModule');
+ * if (details.error) { handleError(details.error); }
+ * @ignore
+ */
+export const getErrorDetails = (error: any, methodName: string, moduleName: string) => {
+  let errData = {message: '', fieldName: ''};
+
+  const failure = error.details as Failure;
+  const reason = failure?.data?.reason ?? `Error while performing ${methodName}`;
+
+  if (!(reason === 'AGENT_NOT_FOUND' && methodName === 'silentRelogin')) {
+    LoggerProxy.error(`${methodName} failed with reason: ${reason}`, {
+      module: moduleName,
+      method: methodName,
+      trackingId: failure?.trackingId,
+    });
+    // we can add more conditions here if not needed for specific cases eg: silentReLogin
+    WebexRequest.getInstance().uploadLogs({
+      correlationId: failure?.trackingId,
+    });
+  }
+
+  if (methodName === 'stationLogin') {
+    errData = getStationLoginErrorData(failure, error.loginOption);
+
+    LoggerProxy.error(
+      `${methodName} failed with reason: ${reason}, message: ${errData.message}, fieldName: ${errData.fieldName}`,
+      {
+        module: moduleName,
+        method: methodName,
+        trackingId: failure?.trackingId,
+      }
+    );
+  }
+
+  const err = new Error(reason ?? `Error while performing ${methodName}`);
+  // @ts-ignore - add custom property to the error object for backward compatibility
+  err.data = errData;
+
+  return {
+    error: err,
+    reason,
+  };
+};
+
+/**
+ * Creates an error details object suitable for use with the Err.Details class.
+ *
+ * @param errObj - The Webex request payload object.
+ * @returns An instance of Err.Details with the generic failure message and extracted details.
+ * @public
+ * @example
+ * const errDetails = createErrDetailsObject(webexRequestPayload);
+ * @ignore
+ */
+export const createErrDetailsObject = (errObj: WebexRequestPayload) => {
+  const details = getCommonErrorDetails(errObj);
+
+  return new Err.Details('Service.reqs.generic.failure', details);
+};

package/src/services/core/WebexRequest.ts

@@ -0,0 +1,103 @@
+import {WEBEX_REQUEST_FILE} from '../../constants';
+import LoggerProxy from '../../logger-proxy';
+import {METHODS} from './constants';
+import {METRIC_EVENT_NAMES} from '../../metrics/constants';
+import MetricsManager from '../../metrics/MetricsManager';
+import {
+  WebexSDK,
+  HTTP_METHODS,
+  IHttpResponse,
+  RequestBody,
+  UploadLogsResponse,
+  LogsMetaData,
+} from '../../types';
+
+class WebexRequest {
+  private webex: WebexSDK;
+  private static instance: WebexRequest;
+
+  public static getInstance(options?: {webex: WebexSDK}): WebexRequest {
+    if (!WebexRequest.instance && options && options.webex) {
+      WebexRequest.instance = new WebexRequest(options);
+    }
+
+    return WebexRequest.instance;
+  }
+
+  private constructor(options: {webex: WebexSDK}) {
+    const {webex} = options;
+    this.webex = webex;
+  }
+
+  public async request(options: {
+    service: string;
+    resource: string;
+    method: HTTP_METHODS;
+    body?: RequestBody;
+  }): Promise<IHttpResponse> {
+    const {service, resource, method, body} = options;
+
+    return this.webex.request({
+      service,
+      resource,
+      method,
+      body,
+    });
+  }
+
+  /**
+   * This is used for uploading the logs to backend/mats.
+   *
+   * @param metaData - meta data to be uploaded.
+   */
+  public async uploadLogs(metaData: LogsMetaData = {}): Promise<UploadLogsResponse> {
+    const feedbackId = crypto.randomUUID();
+    try {
+      const response = await this.webex.internal.support.submitLogs(
+        {...metaData, feedbackId},
+        undefined, // we dont send logs but take from webex logger
+        {type: 'diff'} // this is to take the diff logs from previous upload
+      );
+      LoggerProxy.info(`Logs uploaded successfully with feedbackId: ${feedbackId}`, {
+        module: WEBEX_REQUEST_FILE,
+        method: METHODS.UPLOAD_LOGS,
+      });
+
+      MetricsManager.getInstance().trackEvent(
+        METRIC_EVENT_NAMES.UPLOAD_LOGS_SUCCESS,
+        {
+          trackingId: response?.trackingid,
+          feedbackId,
+          correlationId: metaData?.correlationId,
+        },
+        ['behavioral']
+      );
+
+      return {
+        trackingid: response.trackingid,
+        ...(response.url ? {url: response.url} : {}),
+        ...(response.userId ? {userId: response.userId} : {}),
+        ...(response.correlationId ? {correlationId: response.correlationId} : {}),
+        feedbackId,
+      };
+    } catch (error) {
+      LoggerProxy.error(`Error uploading logs: ${error}`, {
+        module: WEBEX_REQUEST_FILE,
+        method: METHODS.UPLOAD_LOGS,
+      });
+
+      MetricsManager.getInstance().trackEvent(
+        METRIC_EVENT_NAMES.UPLOAD_LOGS_FAILED,
+        {
+          stack: error?.stack,
+          feedbackId,
+          correlationId: metaData?.correlationId,
+        },
+        ['behavioral']
+      );
+      throw error;
+    }
+  }
+}
+
+export default WebexRequest;