@webex/contact-center 3.12.0-llmrefactor.7 → 3.12.0-llmrefactor.9

package/src/services/task/voice/wxAppVoiceMethods.ts

@@ -1,14 +1,24 @@
-import AnswerCallOnWebexService from '../../AnswerCallOnWebexService';
+import {EventPayload} from '@webex/internal-plugin-metrics/src/metrics.types';
+
+import AnswerCallOnWebexService, {WxAppTelephonyError} from '../../AnswerCallOnWebexService';
 import LoggerProxy from '../../../logger-proxy';
 import {METHODS} from '../../../constants';
 import {getErrorDetails} from '../../core/Utils';
+import {Failure} from '../../core/GlobalTypes';
 import {TaskData, TaskToggleMuteOptions, TaskTransmitDtmfOptions} from '../types';
 import {TaskState} from '../state-machine';
+import MetricsManager from '../../../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../../../metrics/constants';
 import {
   decodedLineOwnerId,
   getWebexCallingDeviceDetailsForAgent,
   WebexCallingDeviceDetails,
 } from '../WebexCallingUtils';
+import {
+  logWxAppTelephonyAction,
+  logWxAppValidationFailure,
+  type WxAppTelephonyAction,
+} from '../../wxAppDiagnosticLogging';
 
 type WxAppParticipant = {
   deviceType?: string;
@@ -20,6 +30,7 @@ export type WxAppVoiceDependencies = {
   enableWxBetterTogether: boolean;
   answerCallOnWebexService?: AnswerCallOnWebexService;
   agentId?: string;
+  metricsManager: MetricsManager;
   getTaskData: () => TaskData;
   getTaskState: () => TaskState | undefined;
   getWxAppMuted: () => boolean;
@@ -135,12 +146,86 @@ export function resolveWxAppLineOwnerId(
   return decodedLineOwnerId(getWxAppLineOwnerId(deps));
 }
 
+function getInteractionId(deps: WxAppVoiceDependencies): string | undefined {
+  return deps.getTaskData()?.interactionId;
+}
+
+function logTelephonyFailure(
+  action: WxAppTelephonyAction,
+  deps: WxAppVoiceDependencies,
+  error: unknown
+): void {
+  const wxError = error as WxAppTelephonyError;
+  logWxAppTelephonyAction({
+    action,
+    phase: 'failed',
+    interactionId: getInteractionId(deps),
+    trackingId: wxError.trackingId,
+    httpStatus: wxError.status,
+    failureReason: wxError.message,
+  });
+}
+
+function getWxAppTelephonyMetricFailurePayload(
+  deps: WxAppVoiceDependencies,
+  error: unknown
+): Record<string, string> {
+  const wxError = error as WxAppTelephonyError;
+  const payload: Record<string, string> = {
+    taskId: getInteractionId(deps) ?? '',
+    error: error instanceof Error ? error.toString() : String(error),
+  };
+
+  if (wxError.trackingId) {
+    payload.trackingId = wxError.trackingId;
+  }
+
+  return payload;
+}
+
+type AqmWrappedError = {
+  details?: Failure;
+};
+
+function getWxAppOutdialDeclineFailurePayload(
+  deps: WxAppVoiceDependencies,
+  error: unknown
+): EventPayload {
+  const base: EventPayload = {
+    taskId: getInteractionId(deps) ?? '',
+    error: error instanceof Error ? error.toString() : String(error),
+  };
+  const aqmDetails = (error as AqmWrappedError).details;
+
+  if (aqmDetails) {
+    return {...base, ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(aqmDetails)};
+  }
+
+  return getWxAppTelephonyMetricFailurePayload(deps, error);
+}
+
+function logWxAppOutdialDeclineFailure(deps: WxAppVoiceDependencies, error: unknown): void {
+  const aqmDetails = (error as AqmWrappedError).details;
+  const wxError = error as WxAppTelephonyError;
+
+  logWxAppTelephonyAction({
+    action: 'decline',
+    phase: 'failed',
+    interactionId: getInteractionId(deps),
+    trackingId: aqmDetails?.trackingId ?? wxError.trackingId,
+    httpStatus: wxError.status,
+    failureReason: aqmDetails?.data?.reason ?? wxError.message,
+  });
+}
+
 function assertWxAppEnabled(deps: WxAppVoiceDependencies): void {
   if (!deps.enableWxBetterTogether) {
+    logWxAppValidationFailure('enableWxBetterTogether_disabled', getInteractionId(deps));
     throw new Error('enableWxBetterTogether is disabled');
   }
 
   if (!deps.answerCallOnWebexService) {
+    logWxAppValidationFailure('answer_call_on_webex_service_unavailable', getInteractionId(deps));
     throw new Error('AnswerCallOnWebexService is unavailable');
   }
 }
@@ -149,14 +234,18 @@ export async function acceptOnWebex(
   deps: WxAppVoiceDependencies,
   options?: {lineOwnerId?: string}
 ): Promise<void> {
+  const interactionId = getInteractionId(deps);
+  logWxAppTelephonyAction({action: 'accept', phase: 'started', interactionId});
   assertWxAppEnabled(deps);
 
   if (!isWebexAppCallingOffer(deps)) {
+    logWxAppValidationFailure('not_wxApp_calling_offer', interactionId);
     throw new Error('Task is not a wxApp calling offer');
   }
 
   const details = getCallingDeviceDetails(deps);
   if (!details) {
+    logWxAppValidationFailure('wxApp_device_details_unavailable', interactionId);
     throw new Error('WxApp calling device details are unavailable');
   }
 
@@ -165,20 +254,25 @@ export async function acceptOnWebex(
     endpointId: details.deviceId,
     lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
   });
+  logWxAppTelephonyAction({action: 'accept', phase: 'success', interactionId});
 }
 
 export async function rejectOnWebex(
   deps: WxAppVoiceDependencies,
   options?: {lineOwnerId?: string}
 ): Promise<void> {
+  const interactionId = getInteractionId(deps);
+  logWxAppTelephonyAction({action: 'decline', phase: 'started', interactionId});
   assertWxAppEnabled(deps);
 
   if (!isWebexAppInboundCallingOffer(deps)) {
+    logWxAppValidationFailure('not_wxApp_inbound_calling_offer', interactionId);
     throw new Error('Task is not a wxApp inbound calling offer');
   }
 
   const details = getCallingDeviceDetails(deps);
   if (!details) {
+    logWxAppValidationFailure('wxApp_device_details_unavailable', interactionId);
     throw new Error('WxApp calling device details are unavailable');
   }
 
@@ -186,16 +280,20 @@ export async function rejectOnWebex(
     callId: details.deviceCallId,
     lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
   });
+  logWxAppTelephonyAction({action: 'decline', phase: 'success', interactionId});
 }
 
 export async function toggleMuteOnWebex(
   deps: WxAppVoiceDependencies,
   options?: {lineOwnerId?: string; muted?: boolean}
 ): Promise<void> {
+  const interactionId = getInteractionId(deps);
+  logWxAppTelephonyAction({action: 'mute', phase: 'started', interactionId});
   assertWxAppEnabled(deps);
 
   const callId = getWebexCallingCallId(deps);
   if (!callId) {
+    logWxAppValidationFailure('wxApp_call_id_unavailable', interactionId);
     throw new Error('WxApp call ID is unavailable');
   }
 
@@ -209,16 +307,20 @@ export async function toggleMuteOnWebex(
     lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
   });
   deps.setWxAppMuted(targetMuted);
+  logWxAppTelephonyAction({action: 'mute', phase: 'success', interactionId});
 }
 
 export async function transmitDtmfOnWebex(
   deps: WxAppVoiceDependencies,
   options: {dtmf: string; lineOwnerId?: string}
 ): Promise<void> {
+  const interactionId = getInteractionId(deps);
+  logWxAppTelephonyAction({action: 'dtmf', phase: 'started', interactionId});
   assertWxAppEnabled(deps);
 
   const callId = getWebexCallingCallId(deps);
   if (!callId) {
+    logWxAppValidationFailure('wxApp_call_id_unavailable', interactionId);
     throw new Error('WxApp call ID is unavailable');
   }
 
@@ -226,7 +328,8 @@ export async function transmitDtmfOnWebex(
     module: 'wxAppVoiceMethods',
     method: METHODS.TRANSMIT_DTMF,
     data: {
-      callId,
+      interactionId,
+      callIdSuffix: callId.length <= 8 ? callId : callId.slice(-8),
       dtmfLength: options.dtmf.length,
       hasLineOwnerId: Boolean(options.lineOwnerId),
     },
@@ -237,6 +340,7 @@ export async function transmitDtmfOnWebex(
     dtmf: options.dtmf,
     lineOwnerId: resolveWxAppLineOwnerId(deps, options.lineOwnerId),
   });
+  logWxAppTelephonyAction({action: 'dtmf', phase: 'success', interactionId});
 }
 
 export async function runWxAppAccept(
@@ -244,14 +348,32 @@ export async function runWxAppAccept(
   lifecycle: WxAppVoiceLifecycle,
   options?: {lineOwnerId?: string}
 ): Promise<void> {
+  const taskId = getInteractionId(deps);
+
+  deps.metricsManager.timeEvent([
+    METRIC_EVENT_NAMES.WXAPP_TASK_ACCEPT_SUCCESS,
+    METRIC_EVENT_NAMES.WXAPP_TASK_ACCEPT_FAILED,
+  ]);
+
   try {
     lifecycle.setWxAppAcceptInFlight(true);
     lifecycle.setWxAppAnswerPending(true);
     await acceptOnWebex(deps, options);
     lifecycle.resetWxAppMuted();
     await lifecycle.syncWxAppMuteFromCallDetails();
+
+    deps.metricsManager.trackEvent(METRIC_EVENT_NAMES.WXAPP_TASK_ACCEPT_SUCCESS, {taskId}, [
+      'operational',
+      'behavioral',
+    ]);
   } catch (error) {
     lifecycle.setWxAppAnswerPending(false);
+    logTelephonyFailure('accept', deps, error);
+    deps.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_TASK_ACCEPT_FAILED,
+      getWxAppTelephonyMetricFailurePayload(deps, error),
+      ['operational', 'behavioral']
+    );
     lifecycle.mapWxAppVoiceError(error, METHODS.ACCEPT);
   } finally {
     lifecycle.setWxAppAcceptInFlight(false);
@@ -263,21 +385,89 @@ export async function runWxAppReject(
   lifecycle: WxAppVoiceLifecycle,
   options?: {lineOwnerId?: string}
 ): Promise<void> {
+  const taskId = getInteractionId(deps);
+
+  deps.metricsManager.timeEvent([
+    METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_SUCCESS,
+    METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_FAILED,
+  ]);
+
   try {
     await rejectOnWebex(deps, options);
+
+    deps.metricsManager.trackEvent(METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_SUCCESS, {taskId}, [
+      'operational',
+      'behavioral',
+    ]);
   } catch (error) {
+    logTelephonyFailure('decline', deps, error);
+    deps.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_FAILED,
+      getWxAppTelephonyMetricFailurePayload(deps, error),
+      ['operational', 'behavioral']
+    );
     lifecycle.mapWxAppVoiceError(error, METHODS.REJECT);
   }
 }
 
+export async function runWxAppOutdialDecline<T>(
+  deps: WxAppVoiceDependencies,
+  executeCancel: () => Promise<T>
+): Promise<T> {
+  const taskId = getInteractionId(deps);
+
+  deps.metricsManager.timeEvent([
+    METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_SUCCESS,
+    METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_FAILED,
+  ]);
+
+  try {
+    const result = await executeCancel();
+
+    deps.metricsManager.trackEvent(METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_SUCCESS, {taskId}, [
+      'operational',
+      'behavioral',
+    ]);
+
+    return result;
+  } catch (error) {
+    logWxAppOutdialDeclineFailure(deps, error);
+    deps.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_TASK_DECLINE_FAILED,
+      getWxAppOutdialDeclineFailurePayload(deps, error),
+      ['operational', 'behavioral']
+    );
+    throw error;
+  }
+}
+
 export async function runWxAppToggleMute(
   deps: WxAppVoiceDependencies,
   lifecycle: WxAppVoiceLifecycle,
   options?: TaskToggleMuteOptions
 ): Promise<void> {
+  const taskId = getInteractionId(deps);
+
+  deps.metricsManager.timeEvent([
+    METRIC_EVENT_NAMES.WXAPP_TASK_MUTE_SUCCESS,
+    METRIC_EVENT_NAMES.WXAPP_TASK_MUTE_FAILED,
+  ]);
+
   try {
     await toggleMuteOnWebex(deps, options);
+
+    deps.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_TASK_MUTE_SUCCESS,
+      {taskId, targetMuted: deps.getWxAppMuted()},
+      ['operational', 'behavioral']
+    );
   } catch (error) {
+    logTelephonyFailure('mute', deps, error);
+    deps.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_TASK_MUTE_FAILED,
+      getWxAppTelephonyMetricFailurePayload(deps, error),
+      ['operational', 'behavioral']
+    );
     lifecycle.mapWxAppVoiceError(error, METHODS.TOGGLE_MUTE);
   }
 }
@@ -287,9 +477,28 @@ export async function runWxAppTransmitDtmf(
   lifecycle: WxAppVoiceLifecycle,
   options: TaskTransmitDtmfOptions
 ): Promise<void> {
+  const taskId = getInteractionId(deps);
+
+  deps.metricsManager.timeEvent([
+    METRIC_EVENT_NAMES.WXAPP_TASK_DTMF_SUCCESS,
+    METRIC_EVENT_NAMES.WXAPP_TASK_DTMF_FAILED,
+  ]);
+
   try {
     await transmitDtmfOnWebex(deps, options);
+
+    deps.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_TASK_DTMF_SUCCESS,
+      {taskId, dtmfLength: options.dtmf.length},
+      ['operational', 'behavioral']
+    );
   } catch (error) {
+    logTelephonyFailure('dtmf', deps, error);
+    deps.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_TASK_DTMF_FAILED,
+      getWxAppTelephonyMetricFailurePayload(deps, error),
+      ['operational', 'behavioral']
+    );
     lifecycle.mapWxAppVoiceError(error, METHODS.TRANSMIT_DTMF);
   }
 }

package/src/services/wxAppDiagnosticLogging.ts

@@ -0,0 +1,174 @@
+import LoggerProxy from '../logger-proxy';
+
+export const WXAPP_LOG_FEATURE = 'wxApp';
+export const WXAPP_LOG_PREFIX = '[CC wxApp]';
+
+export type WxAppAcceptReason =
+  | 'wxApp_offer_ready'
+  | 'wxApp_answer_pending'
+  | 'wxApp_accept_in_flight'
+  | 'extension_non_wxApp_offer'
+  | 'browser_webrtc_offer'
+  | 'outdial_auto_answer';
+
+export type WxAppSessionSkipReason =
+  | 'unsupported_browser_login'
+  | 'flag_disabled'
+  | 'mercury_subscribe_failed'
+  | 'publish_failed';
+
+export type WxAppTelephonyAction = 'accept' | 'decline' | 'mute' | 'dtmf';
+export type WxAppTelephonyPhase = 'started' | 'success' | 'failed';
+
+type WxAppLogData = Record<string, string | boolean | number | undefined>;
+
+/** Last 8 chars of callId for correlation without logging full id. */
+export function callIdSuffix(callId: string | null | undefined): string | undefined {
+  if (!callId) {
+    return undefined;
+  }
+
+  return callId.length <= 8 ? callId : callId.slice(-8);
+}
+
+function logWxApp(message: string, method: string, data: WxAppLogData): void {
+  LoggerProxy.info(`${WXAPP_LOG_PREFIX} ${message}`, {
+    module: 'wxAppDiagnosticLogging',
+    method,
+    data: {feature: WXAPP_LOG_FEATURE, ...data},
+  });
+}
+
+function logWxAppError(message: string, method: string, data: WxAppLogData): void {
+  LoggerProxy.error(`${WXAPP_LOG_PREFIX} ${message}`, {
+    module: 'wxAppDiagnosticLogging',
+    method,
+    data: {feature: WXAPP_LOG_FEATURE, ...data},
+  });
+}
+
+export function logWxAppSessionReadiness(params: {
+  enableWxBetterTogether: boolean;
+  loginOption: string | undefined;
+  wxAppHooksApplied: boolean;
+  usersubPublished: boolean;
+  mercurySubscribed: boolean;
+  telephonyTaskType: 'Voice' | 'WebRTC' | 'unknown';
+  skipReason?: WxAppSessionSkipReason;
+}): void {
+  logWxApp('session readiness', 'logWxAppSessionReadiness', {
+    event: 'session_readiness',
+    enableWxBetterTogether: params.enableWxBetterTogether,
+    loginOption: params.loginOption,
+    wxAppHooksApplied: params.wxAppHooksApplied,
+    usersubPublished: params.usersubPublished,
+    mercurySubscribed: params.mercurySubscribed,
+    telephonyTaskType: params.telephonyTaskType,
+    skipReason: params.skipReason,
+  });
+}
+
+export function deriveWxAppAcceptReason(params: {
+  isWxAppInboundOffer: boolean;
+  isWxAppOutdialOffer: boolean;
+  isWebrtc: boolean;
+  isOutdial: boolean;
+  wxAppAcceptInFlight: boolean;
+  wxAppAnswerPending: boolean;
+  enableWxBetterTogether: boolean;
+  hasDeviceCallId: boolean;
+}): WxAppAcceptReason {
+  if (params.isWxAppInboundOffer || params.isWxAppOutdialOffer) {
+    if (params.wxAppAcceptInFlight) {
+      return 'wxApp_accept_in_flight';
+    }
+    if (params.wxAppAnswerPending) {
+      return 'wxApp_answer_pending';
+    }
+
+    return 'wxApp_offer_ready';
+  }
+
+  if (params.isWebrtc && !params.isOutdial) {
+    return 'browser_webrtc_offer';
+  }
+
+  if (params.isOutdial) {
+    return 'outdial_auto_answer';
+  }
+
+  if (params.enableWxBetterTogether && !params.hasDeviceCallId) {
+    return 'extension_non_wxApp_offer';
+  }
+
+  return 'extension_non_wxApp_offer';
+}
+
+export function logWxAppOfferDecision(params: {
+  interactionId: string;
+  acceptVisible: boolean;
+  acceptEnabled: boolean;
+  acceptReason: WxAppAcceptReason;
+  wxAppParticipantDeviceType?: string;
+  hasDeviceCallId: boolean;
+}): void {
+  logWxApp('offer decision', 'logWxAppOfferDecision', {
+    event: 'offer_decision',
+    interactionId: params.interactionId,
+    acceptVisible: params.acceptVisible,
+    acceptEnabled: params.acceptEnabled,
+    acceptReason: params.acceptReason,
+    wxAppParticipantDeviceType: params.wxAppParticipantDeviceType,
+    hasDeviceCallId: params.hasDeviceCallId,
+  });
+}
+
+export function logWxAppTelephonyAction(params: {
+  action: WxAppTelephonyAction;
+  phase: WxAppTelephonyPhase;
+  interactionId?: string;
+  trackingId?: string;
+  httpStatus?: number | string;
+  failureReason?: string;
+}): void {
+  const payload: WxAppLogData = {
+    event: 'telephony_action',
+    action: params.action,
+    phase: params.phase,
+    interactionId: params.interactionId,
+    trackingId: params.trackingId,
+    httpStatus: params.httpStatus,
+    failureReason: params.failureReason,
+  };
+
+  if (params.phase === 'failed') {
+    logWxAppError(`telephony ${params.action} ${params.phase}`, 'logWxAppTelephonyAction', payload);
+  } else {
+    logWxApp(`telephony ${params.action} ${params.phase}`, 'logWxAppTelephonyAction', payload);
+  }
+}
+
+export function logWxAppValidationFailure(reason: string, interactionId?: string): void {
+  logWxAppError('validation failed', 'logWxAppValidationFailure', {
+    event: 'validation_failed',
+    reason,
+    interactionId,
+  });
+}
+
+export function logWxAppMercuryMuteSync(params: {
+  phase: 'received' | 'applied' | 'dropped';
+  muted?: boolean;
+  callIdSuffix?: string;
+  interactionId?: string;
+  dropReason?: string;
+}): void {
+  logWxApp(`mercury mute sync ${params.phase}`, 'logWxAppMercuryMuteSync', {
+    event: 'mercury_mute_sync',
+    phase: params.phase,
+    muted: params.muted,
+    callIdSuffix: params.callIdSuffix,
+    interactionId: params.interactionId,
+    dropReason: params.dropReason,
+  });
+}