@webex/contact-center 3.12.0-next.16 → 3.12.0-next.161

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

@@ -0,0 +1,194 @@
+import {LocalMicrophoneStream, CALL_EVENT_KEYS} from '@webex/calling';
+import {CC_FILE} from '../../../constants';
+import {getErrorDetails} from '../../core/Utils';
+import routingContact from '../contact';
+import {
+  TaskData,
+  TaskResponse,
+  TASK_EVENTS,
+  IWebRTC,
+  VoiceUIControlOptions,
+  VOICE_VARIANT,
+  TaskToggleMuteOptions,
+} from '../types';
+import Voice from './Voice';
+import WebCallingService from '../../WebCallingService';
+import type {WrapupData} from '../../config/types';
+import type ApiAIAssistant from '../../ApiAiAssistant';
+import MetricsManager from '../../../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../../../metrics/constants';
+import LoggerProxy from '../../../logger-proxy';
+
+export default class WebRTC extends Voice implements IWebRTC {
+  private localAudioStream: LocalMicrophoneStream;
+  private webCallingService: WebCallingService;
+
+  constructor(
+    contact: ReturnType<typeof routingContact>,
+    webCallingService: WebCallingService,
+    data: TaskData,
+    callOptions?: VoiceUIControlOptions,
+    wrapupData?: WrapupData,
+    agentId?: string,
+    agentName?: string,
+    apiAIAssistant?: ApiAIAssistant
+  ) {
+    const mergedCallOptions: VoiceUIControlOptions = {
+      ...callOptions,
+      voiceVariant: VOICE_VARIANT.WEBRTC,
+    };
+
+    super(contact, data, mergedCallOptions, wrapupData, agentId, agentName, apiAIAssistant);
+    this.webCallingService = webCallingService;
+    this.registerWebCallListeners();
+  }
+
+  private registerWebCallListeners() {
+    this.webCallingService.on(CALL_EVENT_KEYS.REMOTE_MEDIA, this.handleRemoteMedia);
+  }
+
+  private handleRemoteMedia = (track: MediaStreamTrack) => {
+    this.emit(TASK_EVENTS.TASK_MEDIA, track);
+  };
+
+  /**
+   * This method is used to unregister the web call listeners.
+   * @returns void
+   * @example
+   * ```typescript
+   * task.unregisterWebCallListeners();
+   * ```
+   */
+  public unregisterWebCallListeners() {
+    this.webCallingService.off(CALL_EVENT_KEYS.REMOTE_MEDIA, this.handleRemoteMedia);
+  }
+
+  /**
+   * This is used for incoming task accept by agent.
+   *
+   * @returns Promise<TaskResponse>
+   * @throws Error
+   * @example
+   * ```typescript
+   * task.accept().then(()=>{}).catch(()=>{})
+   * ```
+   */
+  public async accept(): Promise<TaskResponse> {
+    LoggerProxy.log(`Accepting WebRTC task for taskId:${this.data.interactionId}`, {
+      module: 'WebRTC',
+      method: 'accept',
+    });
+    try {
+      this.metricsManager.timeEvent([
+        METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
+        METRIC_EVENT_NAMES.TASK_ACCEPT_FAILED,
+      ]);
+
+      const constraints = {audio: true};
+      const localStream = await navigator.mediaDevices.getUserMedia(constraints);
+      const audioTrack = localStream.getAudioTracks()[0];
+      this.localAudioStream = new LocalMicrophoneStream(new MediaStream([audioTrack]));
+      this.webCallingService.answerCall(this.localAudioStream, this.data.interactionId);
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_ACCEPT_SUCCESS,
+        {
+          taskId: this.data.interactionId,
+          ...MetricsManager.getCommonTrackingFieldForAQMResponse(this.data),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+
+      return Promise.resolve();
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_ACCEPT_FAILED,
+        {
+          taskId: this.data.interactionId,
+          error: error.toString(),
+          ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(
+            (error as any).details || {}
+          ),
+        },
+        ['operational', 'behavioral', 'business']
+      );
+      const {error: detailedError} = getErrorDetails(error, 'accept', CC_FILE);
+      throw detailedError;
+    }
+  }
+
+  /**
+   * This is used for the incoming task decline by agent.
+   *
+   * @returns Promise<TaskResponse>
+   * @throws Error
+   * @example
+   * ```typescript
+   * task.decline().then(()=>{}).catch(()=>{})
+   * ```
+   */
+  public async decline(): Promise<TaskResponse> {
+    LoggerProxy.log(`Declining WebRTC task for taskId:${this.data.interactionId}`, {
+      module: 'WebRTC',
+      method: 'decline',
+    });
+    try {
+      this.metricsManager.timeEvent([
+        METRIC_EVENT_NAMES.TASK_DECLINE_SUCCESS,
+        METRIC_EVENT_NAMES.TASK_DECLINE_FAILED,
+      ]);
+
+      this.webCallingService.declineCall(this.data.interactionId);
+      this.unregisterWebCallListeners();
+
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_DECLINE_SUCCESS,
+        {taskId: this.data.interactionId},
+        ['operational', 'behavioral']
+      );
+
+      return Promise.resolve();
+    } catch (error) {
+      this.metricsManager.trackEvent(
+        METRIC_EVENT_NAMES.TASK_DECLINE_FAILED,
+        {
+          taskId: this.data.interactionId,
+          error: error.toString(),
+          ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(
+            (error as any).details || {}
+          ),
+        },
+        ['operational', 'behavioral']
+      );
+      const {error: detailedError} = getErrorDetails(error, 'decline', CC_FILE);
+      throw detailedError;
+    }
+  }
+
+  /**
+   * This is used for the placing the call in mute or unmute by the agent.
+   *
+   * @throws Error
+   * @example
+   * ```typescript
+   * task.toggleMute().then(()=>{}).catch(()=>{})
+   * ```
+   */
+  public async toggleMute(options?: TaskToggleMuteOptions) {
+    if (options) {
+      // parameter intentionally unused — WebRTC toggles from local stream state
+    }
+    LoggerProxy.log(`Toggling mute WebRTC task for taskId:${this.data.interactionId}`, {
+      module: 'WebRTC',
+      method: 'toggleMute',
+    });
+    try {
+      this.webCallingService.muteUnmuteCall(this.localAudioStream);
+
+      return Promise.resolve();
+    } catch (error) {
+      const {error: detailedError} = getErrorDetails(error, 'mute', CC_FILE);
+      throw detailedError;
+    }
+  }
+}

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

@@ -0,0 +1,204 @@
+import MetricsManager from '../../../metrics/MetricsManager';
+import {METRIC_EVENT_NAMES} from '../../../metrics/constants';
+import {
+  deriveWxAppAcceptReason,
+  logWxAppOfferDecision,
+  logWxAppOfferParticipantMismatch,
+  WxAppAcceptReason,
+} from '../../wxAppDiagnosticLogging';
+import {TaskState} from '../state-machine';
+import {VoiceVariant, VOICE_VARIANT} from '../types';
+import {
+  getCallingDeviceDetails,
+  getWxAppParticipantDiagnostics,
+  WxAppVoiceDependencies,
+} from './wxAppVoiceMethods';
+
+/** Defer mismatch WARN/metric so transient WS ordering gaps (~200–300 ms) do not false-alarm. */
+export const WXAPP_PARTICIPANT_MISMATCH_GRACE_MS = 500;
+
+export type WxAppOfferObservabilityContext = {
+  getInteractionId: () => string;
+  getTaskState: () => TaskState | undefined;
+  getAcceptControl: () => {isVisible: boolean; isEnabled: boolean} | undefined;
+  getVoiceVariant: () => VoiceVariant;
+  isOutdial: () => boolean;
+  isWxAppInboundOffer: () => boolean;
+  isWxAppCallingOffer: () => boolean;
+  getWxAppAcceptInFlight: () => boolean;
+  getWxAppAnswerPending: () => boolean;
+  getEnableWxBetterTogether: () => boolean;
+  getUsersubPublished: () => boolean;
+  getWxAppVoiceDependencies: () => WxAppVoiceDependencies;
+  getMetricsManager: () => MetricsManager;
+};
+
+/**
+ * OFFERED-state wxApp offer diagnostics: acceptReason logging and deferred participant mismatch.
+ * Invoked from Voice.updateUiControls — observability only.
+ */
+export class WxAppOfferObservability {
+  private lastLoggedWxAppAcceptReason?: WxAppAcceptReason;
+  private lastLoggedWxAppParticipantMismatch = false;
+  private wxAppParticipantMismatchGraceTimer?: ReturnType<typeof setTimeout>;
+  private disposed = false;
+
+  public handleUiControlsUpdate(ctx: WxAppOfferObservabilityContext): void {
+    if (this.disposed) {
+      return;
+    }
+
+    if (!ctx.getEnableWxBetterTogether()) {
+      this.cancelGraceTimer();
+
+      return;
+    }
+
+    const state = ctx.getTaskState();
+    if (state !== TaskState.OFFERED) {
+      this.cancelGraceTimer();
+
+      return;
+    }
+
+    const accept = ctx.getAcceptControl();
+    if (!accept?.isVisible) {
+      return;
+    }
+
+    const deps = ctx.getWxAppVoiceDependencies();
+    const isOutdial = ctx.isOutdial();
+    const isWxAppInboundOffer = ctx.isWxAppInboundOffer();
+    const isWxAppOutdialOffer = ctx.isWxAppCallingOffer() && isOutdial;
+    const deviceDetails = getCallingDeviceDetails(deps);
+    const participantDiagnostics = getWxAppParticipantDiagnostics(deps);
+    const usersubPublished = ctx.getUsersubPublished();
+    const acceptReason = deriveWxAppAcceptReason({
+      isWxAppInboundOffer,
+      isWxAppOutdialOffer,
+      isWebrtc: ctx.getVoiceVariant() === VOICE_VARIANT.WEBRTC,
+      isOutdial,
+      wxAppAcceptInFlight: ctx.getWxAppAcceptInFlight(),
+      wxAppAnswerPending: ctx.getWxAppAnswerPending(),
+      enableWxBetterTogether: ctx.getEnableWxBetterTogether(),
+      hasDeviceCallId: participantDiagnostics.hasDeviceCallId,
+    });
+
+    if (acceptReason !== this.lastLoggedWxAppAcceptReason) {
+      this.lastLoggedWxAppAcceptReason = acceptReason;
+
+      logWxAppOfferDecision({
+        interactionId: ctx.getInteractionId(),
+        acceptVisible: accept.isVisible,
+        acceptEnabled: accept.isEnabled,
+        acceptReason,
+        wxAppParticipantDeviceType:
+          deviceDetails?.deviceType ?? participantDiagnostics.participantDeviceType,
+        hasDeviceCallId: participantDiagnostics.hasDeviceCallId,
+        hasDeviceId: participantDiagnostics.hasDeviceId,
+        usersubPublished,
+      });
+    }
+
+    if (participantDiagnostics.hasValidWxAppParticipant || !usersubPublished) {
+      this.cancelGraceTimer();
+    } else if (!ctx.isOutdial() && !this.lastLoggedWxAppParticipantMismatch) {
+      this.scheduleGraceTimer(ctx);
+    }
+  }
+
+  public dispose(): void {
+    this.disposed = true;
+    this.cancelGraceTimer();
+  }
+
+  private cancelGraceTimer(): void {
+    if (this.wxAppParticipantMismatchGraceTimer !== undefined) {
+      clearTimeout(this.wxAppParticipantMismatchGraceTimer);
+      this.wxAppParticipantMismatchGraceTimer = undefined;
+    }
+  }
+
+  private scheduleGraceTimer(ctx: WxAppOfferObservabilityContext): void {
+    if (
+      this.disposed ||
+      this.lastLoggedWxAppParticipantMismatch ||
+      this.wxAppParticipantMismatchGraceTimer !== undefined
+    ) {
+      return;
+    }
+
+    this.wxAppParticipantMismatchGraceTimer = setTimeout(() => {
+      this.wxAppParticipantMismatchGraceTimer = undefined;
+      this.emitParticipantMismatchIfStillNeeded(ctx);
+    }, WXAPP_PARTICIPANT_MISMATCH_GRACE_MS);
+  }
+
+  private emitParticipantMismatchIfStillNeeded(ctx: WxAppOfferObservabilityContext): void {
+    if (
+      this.disposed ||
+      !ctx.getEnableWxBetterTogether() ||
+      this.lastLoggedWxAppParticipantMismatch
+    ) {
+      return;
+    }
+
+    if (ctx.isOutdial()) {
+      return;
+    }
+
+    if (ctx.getTaskState() !== TaskState.OFFERED) {
+      return;
+    }
+
+    const accept = ctx.getAcceptControl();
+    if (!accept?.isVisible) {
+      return;
+    }
+
+    const deps = ctx.getWxAppVoiceDependencies();
+    const participantDiagnostics = getWxAppParticipantDiagnostics(deps);
+    const usersubPublished = ctx.getUsersubPublished();
+
+    if (!usersubPublished || participantDiagnostics.hasValidWxAppParticipant) {
+      return;
+    }
+
+    const isOutdial = ctx.isOutdial();
+    const acceptReason = deriveWxAppAcceptReason({
+      isWxAppInboundOffer: ctx.isWxAppInboundOffer(),
+      isWxAppOutdialOffer: ctx.isWxAppCallingOffer() && isOutdial,
+      isWebrtc: ctx.getVoiceVariant() === VOICE_VARIANT.WEBRTC,
+      isOutdial,
+      wxAppAcceptInFlight: ctx.getWxAppAcceptInFlight(),
+      wxAppAnswerPending: ctx.getWxAppAnswerPending(),
+      enableWxBetterTogether: ctx.getEnableWxBetterTogether(),
+      hasDeviceCallId: participantDiagnostics.hasDeviceCallId,
+    });
+
+    this.lastLoggedWxAppParticipantMismatch = true;
+
+    logWxAppOfferParticipantMismatch({
+      interactionId: ctx.getInteractionId(),
+      usersubPublished,
+      hasDeviceCallId: participantDiagnostics.hasDeviceCallId,
+      hasDeviceId: participantDiagnostics.hasDeviceId,
+      participantDeviceType: participantDiagnostics.participantDeviceType,
+      acceptVisible: accept.isVisible,
+      acceptEnabled: accept.isEnabled,
+      acceptReason,
+    });
+
+    ctx.getMetricsManager().trackEvent(
+      METRIC_EVENT_NAMES.WXAPP_OFFER_PARTICIPANT_FIELDS_MISSING,
+      {
+        taskId: ctx.getInteractionId(),
+        usersubPublished,
+        hasDeviceCallId: participantDiagnostics.hasDeviceCallId,
+        hasDeviceId: participantDiagnostics.hasDeviceId,
+        acceptReason,
+      },
+      ['operational', 'behavioral']
+    );
+  }
+}