@webex/contact-center 3.11.0 → 3.12.0-auth-prejoin-fetch.1

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

@@ -0,0 +1,191 @@
+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 {WrapupData} from '../../config/types';
+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
+  ) {
+    const mergedCallOptions: VoiceUIControlOptions = {
+      ...callOptions,
+      voiceVariant: VOICE_VARIANT.WEBRTC,
+    };
+
+    super(contact, data, mergedCallOptions, wrapupData, agentId);
+    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/wxAppVoiceMethods.ts

@@ -0,0 +1,307 @@
+import AnswerCallOnWebexService from '../../AnswerCallOnWebexService';
+import LoggerProxy from '../../../logger-proxy';
+import {METHODS} from '../../../constants';
+import {getErrorDetails} from '../../core/Utils';
+import {TaskData, TaskToggleMuteOptions, TaskTransmitDtmfOptions} from '../types';
+import {TaskState} from '../state-machine';
+import {
+  decodedLineOwnerId,
+  getWebexCallingDeviceDetailsForAgent,
+  WebexCallingDeviceDetails,
+} from '../WebexCallingUtils';
+
+type WxAppParticipant = {
+  deviceType?: string;
+  deviceCallId?: string;
+  deviceId?: string;
+};
+
+export type WxAppVoiceDependencies = {
+  enableWxBetterTogether: boolean;
+  answerCallOnWebexService?: AnswerCallOnWebexService;
+  agentId?: string;
+  getTaskData: () => TaskData;
+  getTaskState: () => TaskState | undefined;
+  getWxAppMuted: () => boolean;
+  setWxAppMuted: (muted: boolean) => void;
+};
+
+/** @deprecated Use {@link WxAppVoiceDependencies} */
+export type WxAppVoiceDeps = WxAppVoiceDependencies;
+
+export type WxAppVoiceLifecycle = {
+  setWxAppAcceptInFlight: (inFlight: boolean) => void;
+  setWxAppAnswerPending: (pending: boolean) => void;
+  resetWxAppMuted: () => void;
+  syncWxAppMuteFromCallDetails: () => Promise<boolean | undefined>;
+  mapWxAppVoiceError: (error: unknown, method: string) => never;
+};
+
+const isWxAppParticipant = (participant: unknown): participant is WxAppParticipant =>
+  (participant as WxAppParticipant)?.deviceType === 'wxApp' &&
+  typeof (participant as WxAppParticipant)?.deviceCallId === 'string' &&
+  (participant as WxAppParticipant).deviceCallId.trim() !== '' &&
+  typeof (participant as WxAppParticipant)?.deviceId === 'string' &&
+  (participant as WxAppParticipant).deviceId.trim() !== '';
+
+const isOutdialTask = (deps: WxAppVoiceDependencies): boolean =>
+  deps.getTaskData()?.interaction?.outboundType === 'OUTDIAL';
+
+function getWxAppAgentParticipant(deps: WxAppVoiceDependencies): unknown {
+  const taskData = deps.getTaskData();
+  const participants = taskData.interaction?.participants;
+  const agentId = deps.agentId ?? taskData.agentId;
+
+  if (!participants || !agentId) {
+    return undefined;
+  }
+
+  if (participants[agentId]) {
+    return participants[agentId];
+  }
+
+  return Object.values(participants).find(
+    (participant) => (participant as {id?: string})?.id === agentId
+  );
+}
+
+export function getCallingDeviceDetails(
+  deps: WxAppVoiceDependencies
+): WebexCallingDeviceDetails | undefined {
+  const taskData = deps.getTaskData();
+  const participant = getWxAppAgentParticipant(deps);
+
+  if (!isWxAppParticipant(participant)) {
+    return undefined;
+  }
+
+  return getWebexCallingDeviceDetailsForAgent(
+    deps.agentId ?? taskData.agentId,
+    taskData.interaction?.participants
+  );
+}
+
+export function isWebexAppCallingOffer(deps: WxAppVoiceDependencies): boolean {
+  if (!deps.enableWxBetterTogether) {
+    return false;
+  }
+
+  const state = deps.getTaskState();
+  if (state !== TaskState.OFFERED) {
+    return false;
+  }
+
+  const details = getCallingDeviceDetails(deps);
+
+  return Boolean(details);
+}
+
+/** Inbound wxApp offer only — outdial decline uses CC routing, not telephony reject. */
+export function isWebexAppInboundCallingOffer(deps: WxAppVoiceDependencies): boolean {
+  return isWebexAppCallingOffer(deps) && !isOutdialTask(deps);
+}
+
+export function getWebexCallingCallId(deps: WxAppVoiceDependencies): string | null {
+  const state = deps.getTaskState();
+  if (
+    !state ||
+    state === TaskState.OFFERED ||
+    state === TaskState.IDLE ||
+    state === TaskState.WRAPPING_UP ||
+    state === TaskState.TERMINATED ||
+    state === TaskState.COMPLETED
+  ) {
+    return null;
+  }
+
+  return getCallingDeviceDetails(deps)?.deviceCallId ?? null;
+}
+
+export function getWxAppLineOwnerId(deps: WxAppVoiceDependencies): string | undefined {
+  const participant = getWxAppAgentParticipant(deps) as {lineOwnerId?: string} | undefined;
+  const lineOwnerId = participant?.lineOwnerId;
+
+  return typeof lineOwnerId === 'string' && lineOwnerId.trim() !== '' ? lineOwnerId : undefined;
+}
+
+export function resolveWxAppLineOwnerId(
+  deps: WxAppVoiceDependencies,
+  override?: string
+): string | undefined {
+  if (typeof override === 'string' && override.trim() !== '') {
+    return override;
+  }
+
+  return decodedLineOwnerId(getWxAppLineOwnerId(deps));
+}
+
+function assertWxAppEnabled(deps: WxAppVoiceDependencies): void {
+  if (!deps.enableWxBetterTogether) {
+    throw new Error('enableWxBetterTogether is disabled');
+  }
+
+  if (!deps.answerCallOnWebexService) {
+    throw new Error('AnswerCallOnWebexService is unavailable');
+  }
+}
+
+export async function acceptOnWebex(
+  deps: WxAppVoiceDependencies,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  if (!isWebexAppCallingOffer(deps)) {
+    throw new Error('Task is not a wxApp calling offer');
+  }
+
+  const details = getCallingDeviceDetails(deps);
+  if (!details) {
+    throw new Error('WxApp calling device details are unavailable');
+  }
+
+  await deps.answerCallOnWebexService.answerCall({
+    callId: details.deviceCallId,
+    endpointId: details.deviceId,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
+  });
+}
+
+export async function rejectOnWebex(
+  deps: WxAppVoiceDependencies,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  if (!isWebexAppInboundCallingOffer(deps)) {
+    throw new Error('Task is not a wxApp inbound calling offer');
+  }
+
+  const details = getCallingDeviceDetails(deps);
+  if (!details) {
+    throw new Error('WxApp calling device details are unavailable');
+  }
+
+  await deps.answerCallOnWebexService.rejectCall({
+    callId: details.deviceCallId,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
+  });
+}
+
+export async function toggleMuteOnWebex(
+  deps: WxAppVoiceDependencies,
+  options?: {lineOwnerId?: string; muted?: boolean}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  const callId = getWebexCallingCallId(deps);
+  if (!callId) {
+    throw new Error('WxApp call ID is unavailable');
+  }
+
+  const targetMuted = options?.muted ?? !deps.getWxAppMuted();
+  const request = targetMuted
+    ? deps.answerCallOnWebexService.muteCall.bind(deps.answerCallOnWebexService)
+    : deps.answerCallOnWebexService.unmuteCall.bind(deps.answerCallOnWebexService);
+
+  await request({
+    callId,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options?.lineOwnerId),
+  });
+  deps.setWxAppMuted(targetMuted);
+}
+
+export async function transmitDtmfOnWebex(
+  deps: WxAppVoiceDependencies,
+  options: {dtmf: string; lineOwnerId?: string}
+): Promise<void> {
+  assertWxAppEnabled(deps);
+
+  const callId = getWebexCallingCallId(deps);
+  if (!callId) {
+    throw new Error('WxApp call ID is unavailable');
+  }
+
+  LoggerProxy.info('transmitDtmf', {
+    module: 'wxAppVoiceMethods',
+    method: METHODS.TRANSMIT_DTMF,
+    data: {
+      callId,
+      dtmfLength: options.dtmf.length,
+      hasLineOwnerId: Boolean(options.lineOwnerId),
+    },
+  });
+
+  await deps.answerCallOnWebexService.transmitDtmf({
+    callId,
+    dtmf: options.dtmf,
+    lineOwnerId: resolveWxAppLineOwnerId(deps, options.lineOwnerId),
+  });
+}
+
+export async function runWxAppAccept(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  try {
+    lifecycle.setWxAppAcceptInFlight(true);
+    lifecycle.setWxAppAnswerPending(true);
+    await acceptOnWebex(deps, options);
+    lifecycle.resetWxAppMuted();
+    await lifecycle.syncWxAppMuteFromCallDetails();
+  } catch (error) {
+    lifecycle.setWxAppAnswerPending(false);
+    lifecycle.mapWxAppVoiceError(error, METHODS.ACCEPT);
+  } finally {
+    lifecycle.setWxAppAcceptInFlight(false);
+  }
+}
+
+export async function runWxAppReject(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options?: {lineOwnerId?: string}
+): Promise<void> {
+  try {
+    await rejectOnWebex(deps, options);
+  } catch (error) {
+    lifecycle.mapWxAppVoiceError(error, METHODS.REJECT);
+  }
+}
+
+export async function runWxAppToggleMute(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options?: TaskToggleMuteOptions
+): Promise<void> {
+  try {
+    await toggleMuteOnWebex(deps, options);
+  } catch (error) {
+    lifecycle.mapWxAppVoiceError(error, METHODS.TOGGLE_MUTE);
+  }
+}
+
+export async function runWxAppTransmitDtmf(
+  deps: WxAppVoiceDependencies,
+  lifecycle: WxAppVoiceLifecycle,
+  options: TaskTransmitDtmfOptions
+): Promise<void> {
+  try {
+    await transmitDtmfOnWebex(deps, options);
+  } catch (error) {
+    lifecycle.mapWxAppVoiceError(error, METHODS.TRANSMIT_DTMF);
+  }
+}
+
+export function mapWxAppVoiceError(error: unknown, method: string, module: string): never {
+  if (
+    error instanceof Error &&
+    (error as Error & {isWxAppTelephonyError?: boolean}).isWxAppTelephonyError
+  ) {
+    throw error;
+  }
+
+  const {error: detailedError} = getErrorDetails(error, method, module);
+  throw detailedError;
+}

package/src/services/wxAppTelephonyUtils.ts

@@ -0,0 +1,14 @@
+/**
+ * Expected Hydra responses when mute backfill races call creation (WXCC-6026).
+ * These must not be logged as errors — see task-spec wxApp mute backfill guard.
+ */
+export function isWxAppCallNotFoundError(error: unknown): boolean {
+  const err = error as {status?: number | string; message?: string};
+  if (err?.status === 400 || err?.status === '400') {
+    return true;
+  }
+
+  const message = String(err?.message ?? error ?? '');
+
+  return message.includes('Call not found') || message.includes('101002');
+}