@webex/contact-center 3.12.0-next.8 → 3.12.0-task-refactor.1

package/src/services/task/state-machine/uiControlsComputer.ts

@@ -0,0 +1,529 @@
+/**
+ * UI Controls Computer - Centralized logic for computing UI control states
+ */
+
+import {
+  InteractionUIControls,
+  TASK_CHANNEL_TYPE,
+  TaskData,
+  TaskUILeg,
+  TaskUIControls,
+  VOICE_VARIANT,
+} from '../types';
+import {TaskContext, UIControlConfig} from './types';
+import {TaskState, MAX_PARTICIPANTS_IN_MULTIPARTY_CONFERENCE} from './constants';
+import {
+  getIsCustomerInCall,
+  getConferenceParticipantsCount,
+  getIsConferenceInProgress,
+  getIsConsultInProgressForConferenceControls,
+  getIsConsultedAgentForControls,
+  getServerHoldStateForControls,
+} from '../TaskUtils';
+
+const DISABLED = {isVisible: false, isEnabled: false} as const;
+const VISIBLE_ENABLED = {isVisible: true, isEnabled: true} as const;
+const VISIBLE_DISABLED = {isVisible: true, isEnabled: false} as const;
+
+function getDefaultInteractionUIControls(): InteractionUIControls {
+  return {
+    accept: DISABLED,
+    decline: DISABLED,
+    hold: DISABLED,
+    mute: DISABLED,
+    end: DISABLED,
+    transfer: DISABLED,
+    consult: DISABLED,
+    consultTransfer: DISABLED,
+    endConsult: DISABLED,
+    recording: DISABLED,
+    conference: DISABLED,
+    wrapup: DISABLED,
+    exitConference: DISABLED,
+    transferConference: DISABLED,
+    mergeToConference: DISABLED,
+    switch: DISABLED,
+  };
+}
+
+function createTaskUIControls(
+  main: InteractionUIControls,
+  consult: InteractionUIControls,
+  activeLeg: TaskUILeg
+): TaskUIControls {
+  return {
+    main,
+    consult,
+    activeLeg,
+  };
+}
+
+export function getDefaultUIControls(): TaskUIControls {
+  return createTaskUIControls(
+    getDefaultInteractionUIControls(),
+    getDefaultInteractionUIControls(),
+    'main'
+  );
+}
+
+function computeVoiceInteractionUIControls(
+  state: TaskState,
+  context: TaskContext,
+  config: UIControlConfig,
+  fallbackTaskData?: TaskData,
+  currentLeg: TaskUILeg = 'main'
+): InteractionUIControls {
+  // Early exit for idle
+  if (state === TaskState.IDLE) {
+    return getDefaultInteractionUIControls();
+  }
+
+  // Essential data
+  const taskData = context.taskData ?? fallbackTaskData ?? null;
+  const interaction = taskData?.interaction;
+  const mainCallId = interaction?.mainInteractionId || taskData?.interactionId;
+  const isWebrtc = config.voiceVariant === VOICE_VARIANT.WEBRTC;
+  const isOutdial = interaction?.outboundType === 'OUTDIAL';
+  const serverHold = getServerHoldStateForControls(context, mainCallId, fallbackTaskData);
+
+  // Backend-derived checks
+  const customerInCall =
+    interaction && mainCallId ? getIsCustomerInCall(interaction, mainCallId) : false;
+  // EP-DN/secondary legs can have incomplete media participant lists; fall back to participants map.
+  const customerPresent =
+    customerInCall ||
+    Boolean(
+      interaction &&
+        interaction.participants &&
+        Object.values(interaction.participants).some(
+          (p: any) => p?.pType === 'Customer' && !p?.hasLeft
+        )
+    );
+  const participantCount =
+    interaction && mainCallId ? getConferenceParticipantsCount(interaction, mainCallId) : 0;
+  const maxParticipants = participantCount >= MAX_PARTICIPANTS_IN_MULTIPARTY_CONFERENCE;
+  const selfAgentId = config.agentId ?? taskData?.agentId;
+  const consultInProgress = getIsConsultInProgressForConferenceControls(
+    interaction,
+    mainCallId,
+    selfAgentId
+  );
+  const conferenceFromBackend = taskData ? getIsConferenceInProgress(taskData) : false;
+  // Note: ownership is used by some controls; keep computations local to those controls
+
+  // Context flags (set by state machine actions)
+  const {consultInitiator, consultDestinationAgentJoined, consultCallHeld, consultFromConference} =
+    context;
+  const {recordingControlsAvailable} = context;
+
+  const stateImpliesHeld = state === TaskState.HELD || state === TaskState.RESUME_INITIATING;
+  const stateImpliesConnected =
+    state === TaskState.CONNECTED || state === TaskState.HOLD_INITIATING;
+  const isHeld = stateImpliesHeld || serverHold === true;
+  const isConnected = stateImpliesConnected || (!stateImpliesHeld && serverHold === false);
+
+  // State categories for cleaner logic
+  const isConsulting =
+    state === TaskState.CONSULTING ||
+    state === TaskState.CONSULT_INITIATING ||
+    state === TaskState.CONF_INITIATING;
+  const isConferencing = state === TaskState.CONFERENCING;
+  const isWrappingUp = state === TaskState.WRAPPING_UP;
+  const selfInMainCall =
+    Boolean(selfAgentId) &&
+    Boolean(mainCallId) &&
+    Boolean(interaction?.media?.[mainCallId]?.participants?.includes(selfAgentId as string));
+  const conferenceActive = isConferencing || conferenceFromBackend || consultFromConference;
+  // Treat consult initiator as "in conference" even if mainCall participant list lags while consulting.
+  const inConference = conferenceActive && (isConferencing || selfInMainCall || consultInitiator);
+
+  // Check if this is a consulted agent (must be after isConsulting is computed).
+  const isSoleAgentOnCall = participantCount <= 1 && !isConsulting && !inConference;
+  const isConsulted =
+    inConference || isSoleAgentOnCall
+      ? false
+      : getIsConsultedAgentForControls(taskData, context, isConsulting);
+
+  // Active call = can perform call operations
+  const isActive =
+    state === TaskState.CONNECTED ||
+    state === TaskState.HELD ||
+    state === TaskState.HOLD_INITIATING ||
+    state === TaskState.RESUME_INITIATING ||
+    isConsulting ||
+    isConferencing;
+
+  // Consulted agents have limited controls until they're in conference or wrapup
+  // Use inConference (not isConferencing) so controls remain enabled after state downgrade
+  const hasFullControls = !isConsulted || consultInitiator || inConference || isWrappingUp;
+  const consultOwnedBySelf =
+    consultInitiator || (Boolean(selfAgentId) && taskData?.consultingAgentId === selfAgentId);
+  const hasConsultMedia = Boolean(
+    taskData?.consultMediaResourceId ||
+      Object.values(interaction?.media ?? {}).some((media: any) => media?.mType === 'consult')
+  );
+  const hasParallelConsultLeg =
+    consultOwnedBySelf &&
+    !isConsulting &&
+    !isConsulted &&
+    (consultInProgress || consultCallHeld || hasConsultMedia);
+  const consultLegOnHold = isConsulting && consultCallHeld;
+
+  return {
+    // Accept/Decline: Voice tasks in offered state
+    // For outdial, accept is disabled (auto-answer handles it), decline remains enabled
+    // For Extension mode (non-WebRTC), accept shows as disabled "Ringing" button
+    accept:
+      state === TaskState.OFFERED && !interaction?.isTerminated
+        ? {isVisible: true, isEnabled: isWebrtc && !isOutdial}
+        : DISABLED,
+    decline:
+      isWebrtc && state === TaskState.OFFERED && !interaction?.isTerminated
+        ? VISIBLE_ENABLED
+        : DISABLED,
+
+    // Hold: visible in connected/held/conference, disabled in conference/consulting
+    hold: (() => {
+      if (!hasFullControls) return DISABLED;
+      if (consultOwnedBySelf && (isConsulting || hasParallelConsultLeg || consultCallHeld)) {
+        return DISABLED;
+      }
+      if (hasParallelConsultLeg) return DISABLED;
+      if (state === TaskState.OFFERED) return DISABLED;
+      if (isWrappingUp) return DISABLED;
+      // Visibility: connected || held || inConference
+      if (!(isConnected || isHeld || inConference)) return DISABLED;
+      // Enabled: (connected || held) && !inConference && !isConsulting
+      const canHold = (isConnected || isHeld) && !inConference && !isConsulting;
+
+      return canHold ? VISIBLE_ENABLED : VISIBLE_DISABLED;
+    })(),
+
+    // Mute: WebRTC only, active calls; hidden entirely during wrapup
+    mute: (() => {
+      if (!isWebrtc) return DISABLED;
+      if (isWrappingUp) return DISABLED;
+      if (isConsulting) return VISIBLE_ENABLED;
+
+      if (isConnected || isHeld || isConferencing) {
+        if (inConference) return VISIBLE_ENABLED;
+
+        return isHeld ? VISIBLE_DISABLED : VISIBLE_ENABLED;
+      }
+
+      return DISABLED;
+    })(),
+
+    // End: varies by state; during consulting only on main leg (consult held)
+    end: (() => {
+      if (!config.isEndTaskEnabled) return DISABLED;
+      if (hasParallelConsultLeg) return VISIBLE_DISABLED;
+
+      if (isConsulting) {
+        if (currentLeg === 'consult' && consultCallHeld) return DISABLED;
+
+        return consultInitiator && consultCallHeld ? VISIBLE_ENABLED : DISABLED;
+      }
+
+      if (inConference) {
+        if (isConsulted) return DISABLED;
+
+        if (consultInProgress) return VISIBLE_DISABLED;
+
+        return isWrappingUp ? VISIBLE_DISABLED : VISIBLE_ENABLED;
+      }
+      if (!hasFullControls) return DISABLED;
+      if (isActive) return isHeld || isWrappingUp ? VISIBLE_DISABLED : VISIBLE_ENABLED;
+
+      return DISABLED;
+    })(),
+
+    // Transfer: connected/held, not in conference
+    transfer: (() => {
+      if (hasParallelConsultLeg) {
+        if (state === TaskState.CONNECTED) return VISIBLE_ENABLED;
+        if (state === TaskState.HELD) return VISIBLE_DISABLED;
+      }
+      if (isConsulting) {
+        if (!consultInitiator) return DISABLED;
+        if (consultLegOnHold) return VISIBLE_DISABLED;
+
+        return consultDestinationAgentJoined ? VISIBLE_ENABLED : VISIBLE_DISABLED;
+      }
+      if (!hasFullControls || inConference) return DISABLED;
+      if (state === TaskState.CONNECTED || state === TaskState.HELD) return VISIBLE_ENABLED;
+
+      return DISABLED;
+    })(),
+
+    // Consult: connected/held/conference when conditions met
+    consult: (() => {
+      const isConnectedOrHeld = state === TaskState.CONNECTED || state === TaskState.HELD;
+
+      if (hasParallelConsultLeg) return DISABLED;
+      if (!hasFullControls || !(isConnectedOrHeld || inConference)) {
+        return DISABLED;
+      }
+
+      // Enabled conditions differ by state
+      const canFromConnected =
+        !maxParticipants && customerPresent && !consultInProgress && !isConsulted;
+      const canFromConference =
+        !maxParticipants && customerPresent && !consultInProgress && !isConsulting;
+
+      const isEnabled = inConference ? canFromConference : canFromConnected;
+
+      return {isVisible: true, isEnabled};
+    })(),
+
+    // ConsultTransfer: always hidden (use transfer button)
+    consultTransfer: DISABLED,
+
+    // EndConsult: during consulting
+    endConsult: (() => {
+      if (!isConsulting) return DISABLED;
+      if (isConsulted && isConferencing) return DISABLED;
+      if (!isConsulted && isConferencing && !(consultInitiator && conferenceFromBackend)) {
+        return DISABLED;
+      }
+
+      return {isVisible: true, isEnabled: consultInitiator || config.isEndConsultEnabled};
+    })(),
+
+    // Recording: connected/held only, not in consult/conference
+    recording: (() => {
+      if (!recordingControlsAvailable || !config.isRecordingEnabled) return DISABLED;
+      if (!hasFullControls || isConsulting || inConference) return DISABLED;
+      if (state === TaskState.CONNECTED || state === TaskState.HELD) {
+        return VISIBLE_ENABLED;
+      }
+
+      return DISABLED;
+    })(),
+
+    // Conference: during consulting, enabled on both legs when agent joined
+    // Label changes based on leg: "Conference" on main leg, "Merge" on consult leg
+    conference: (() => {
+      if (hasParallelConsultLeg) {
+        if (state === TaskState.CONNECTED) {
+          return maxParticipants ? VISIBLE_DISABLED : VISIBLE_ENABLED;
+        }
+        if (state === TaskState.HELD) return VISIBLE_DISABLED;
+
+        return DISABLED;
+      }
+      if (!hasFullControls || !isConsulting) return DISABLED;
+      if (!consultInitiator) return DISABLED;
+      if (consultLegOnHold) return VISIBLE_DISABLED;
+
+      return consultDestinationAgentJoined && !maxParticipants ? VISIBLE_ENABLED : VISIBLE_DISABLED;
+    })(),
+
+    // Wrapup: wrapping up state
+    wrapup: isWrappingUp ? VISIBLE_ENABLED : DISABLED,
+
+    // ExitConference: in conference, not consulting from conference
+    exitConference: (() => {
+      if (isConsulted && !isConferencing) return DISABLED;
+      if (!inConference) return DISABLED;
+      const consultingFromConference = consultInitiator && isConsulting && conferenceFromBackend;
+
+      return consultingFromConference ? VISIBLE_DISABLED : VISIBLE_ENABLED;
+    })(),
+
+    // TransferConference: in conference with active consult, owner consulting from conference
+    transferConference: (() => {
+      if (hasParallelConsultLeg || consultLegOnHold) return DISABLED;
+      if (!inConference || !isConsulting) return DISABLED;
+      if (!consultInitiator || isConsulted) return DISABLED;
+
+      return consultDestinationAgentJoined ? VISIBLE_ENABLED : VISIBLE_DISABLED;
+    })(),
+
+    // MergeToConference: mirrors conference control, enabled on both legs
+    mergeToConference: (() => {
+      if (!isConsulting || !consultInitiator) return DISABLED;
+      if (consultLegOnHold) return VISIBLE_DISABLED;
+
+      return consultDestinationAgentJoined && !maxParticipants ? VISIBLE_ENABLED : VISIBLE_DISABLED;
+    })(),
+
+    // Switch: visible only on the currently active leg
+    switch: (() => {
+      if (currentLeg === 'consult') {
+        if (!isConsulting || !consultInitiator || consultCallHeld) return DISABLED;
+
+        return consultDestinationAgentJoined ? VISIBLE_ENABLED : VISIBLE_DISABLED;
+      }
+
+      if (hasParallelConsultLeg && state === TaskState.CONNECTED) {
+        return consultDestinationAgentJoined ? VISIBLE_ENABLED : VISIBLE_DISABLED;
+      }
+
+      return DISABLED;
+    })(),
+  };
+}
+
+function computeDigitalInteractionUIControls(
+  state: TaskState,
+  context: TaskContext,
+  fallbackTaskData?: TaskData
+): InteractionUIControls {
+  const taskData = context.taskData ?? fallbackTaskData ?? null;
+  const isTerminated = taskData?.interaction?.isTerminated ?? false;
+
+  const isConnected = state === TaskState.CONNECTED;
+  const isWrappingUp = state === TaskState.WRAPPING_UP;
+
+  return {
+    accept: state === TaskState.OFFERED ? VISIBLE_ENABLED : DISABLED,
+    decline: DISABLED,
+    hold: DISABLED,
+    mute: DISABLED,
+    end: isConnected && !isWrappingUp ? VISIBLE_ENABLED : DISABLED,
+    transfer: isConnected && !isWrappingUp ? VISIBLE_ENABLED : DISABLED,
+    consult: DISABLED,
+    consultTransfer: DISABLED,
+    endConsult: DISABLED,
+    recording: DISABLED,
+    conference: DISABLED,
+    wrapup: isTerminated || isWrappingUp ? VISIBLE_ENABLED : DISABLED,
+    exitConference: DISABLED,
+    transferConference: DISABLED,
+    mergeToConference: DISABLED,
+    switch: DISABLED,
+  };
+}
+
+function getVoiceLegState(
+  currentState: TaskState,
+  context: TaskContext,
+  config: UIControlConfig,
+  fallbackTaskData?: TaskData
+): {hasConsultLeg: boolean; activeLeg: TaskUILeg; mainState: TaskState; consultState: TaskState} {
+  if (currentState === TaskState.WRAPPING_UP) {
+    return {
+      hasConsultLeg: false,
+      activeLeg: 'main',
+      mainState: currentState,
+      consultState: TaskState.CONSULTING,
+    };
+  }
+
+  const taskData = context.taskData ?? fallbackTaskData ?? null;
+  const interaction = taskData?.interaction;
+  const mainCallId = interaction?.mainInteractionId || taskData?.interactionId;
+  const selfAgentId = config.agentId ?? taskData?.agentId;
+  const consultInProgress = getIsConsultInProgressForConferenceControls(
+    interaction,
+    mainCallId,
+    selfAgentId
+  );
+  const isConsultingState =
+    currentState === TaskState.CONSULTING ||
+    currentState === TaskState.CONSULT_INITIATING ||
+    currentState === TaskState.CONF_INITIATING;
+  const consultOwnedBySelf =
+    context.consultInitiator ||
+    (Boolean(selfAgentId) && taskData?.consultingAgentId === selfAgentId);
+  const hasConsultMedia = Boolean(
+    taskData?.consultMediaResourceId ||
+      Object.values(interaction?.media ?? {}).some((media: any) => media?.mType === 'consult')
+  );
+  const hasConsultLeg = Boolean(
+    consultOwnedBySelf &&
+      !taskData?.isConsulted &&
+      !interaction?.isTerminated &&
+      (consultInProgress || isConsultingState || context.consultCallHeld || hasConsultMedia)
+  );
+
+  if (!hasConsultLeg) {
+    return {
+      hasConsultLeg: false,
+      activeLeg: 'main',
+      mainState: currentState,
+      consultState: TaskState.CONSULTING,
+    };
+  }
+
+  return {
+    hasConsultLeg: true,
+    activeLeg: context.consultCallHeld ? 'main' : 'consult',
+    mainState: context.consultCallHeld ? TaskState.CONNECTED : TaskState.HELD,
+    consultState: isConsultingState ? currentState : TaskState.CONSULTING,
+  };
+}
+
+export function computeUIControls(
+  currentState: TaskState,
+  context: TaskContext,
+  fallbackTaskData?: TaskData
+): TaskUIControls {
+  if (currentState === TaskState.TERMINATED || currentState === TaskState.COMPLETED) {
+    return getDefaultUIControls();
+  }
+
+  switch (context.uiControlConfig.channelType) {
+    case TASK_CHANNEL_TYPE.VOICE: {
+      const {hasConsultLeg, activeLeg, mainState, consultState} = getVoiceLegState(
+        currentState,
+        context,
+        context.uiControlConfig,
+        fallbackTaskData
+      );
+
+      const mainControls = computeVoiceInteractionUIControls(
+        mainState,
+        context,
+        context.uiControlConfig,
+        fallbackTaskData,
+        'main'
+      );
+      const consultControls = hasConsultLeg
+        ? computeVoiceInteractionUIControls(
+            consultState,
+            context,
+            context.uiControlConfig,
+            fallbackTaskData,
+            'consult'
+          )
+        : getDefaultInteractionUIControls();
+
+      return createTaskUIControls(mainControls, consultControls, activeLeg);
+    }
+    case TASK_CHANNEL_TYPE.DIGITAL:
+      return createTaskUIControls(
+        computeDigitalInteractionUIControls(currentState, context, fallbackTaskData),
+        getDefaultInteractionUIControls(),
+        'main'
+      );
+    default:
+      return getDefaultUIControls();
+  }
+}
+
+function haveInteractionUIControlsChanged(
+  previous: InteractionUIControls,
+  next: InteractionUIControls
+): boolean {
+  return (Object.keys(next) as (keyof InteractionUIControls)[]).some((key) => {
+    const prev = previous[key];
+    const curr = next[key];
+
+    return prev.isVisible !== curr.isVisible || prev.isEnabled !== curr.isEnabled;
+  });
+}
+
+export function haveUIControlsChanged(
+  previous: TaskUIControls | undefined,
+  next: TaskUIControls
+): boolean {
+  if (!previous) return true;
+
+  return (
+    previous.activeLeg !== next.activeLeg ||
+    haveInteractionUIControlsChanged(previous.main, next.main) ||
+    haveInteractionUIControlsChanged(previous.consult, next.consult)
+  );
+}

package/src/services/task/taskDataNormalizer.ts

@@ -0,0 +1,137 @@
+import {
+  CallProcessingBooleanKey,
+  InteractionBooleanKey,
+  ParticipantBooleanKey,
+  TaskData,
+} from './types';
+
+const booleanKeys: CallProcessingBooleanKey[] = [
+  'recordingStarted',
+  'recordInProgress',
+  'isPaused',
+  'pauseResumeEnabled',
+  'ctqInProgress',
+  'outdialTransferToQueueEnabled',
+  'taskToBeSelfServiced',
+  'CONTINUE_RECORDING_ON_TRANSFER',
+  'isParked',
+  'participantInviteTimeout',
+  'checkAgentAvailability',
+];
+
+const interactionBooleanKeys: InteractionBooleanKey[] = [
+  'isFcManaged',
+  'isMediaForked',
+  'isTerminated',
+];
+
+const participantBooleanKeys: ParticipantBooleanKey[] = [
+  'autoAnswerEnabled',
+  'hasJoined',
+  'hasLeft',
+  'isConsulted',
+  'isInPredial',
+  'isOffered',
+  'isWrapUp',
+  'isWrappedUp',
+];
+
+const toBoolean = (value: unknown): boolean | undefined => {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    const normalized = value.toLowerCase();
+
+    if (normalized === 'true') {
+      return true;
+    }
+    if (normalized === 'false') {
+      return false;
+    }
+  }
+
+  return undefined;
+};
+
+const normalizeFields = <T extends Record<string, any>>(obj: T, keys: string[]): T | undefined => {
+  let updated: T | undefined;
+
+  keys.forEach((key) => {
+    const normalized = toBoolean(obj[key]);
+
+    if (typeof normalized !== 'undefined') {
+      if (!updated) {
+        updated = {...obj};
+      }
+      (updated as any)[key] = normalized;
+    }
+  });
+
+  return updated;
+};
+
+/**
+ * Normalize backend task payload quirks so downstream code can rely on actual booleans.
+ *
+ * Applies to every Agent Contact websocket event before it reaches the state machine:
+ * - Converts string booleans in callProcessingDetails to actual booleans.
+ * - Also normalizes known boolean fields on interaction and participants.
+ * - Keeps payload shape intact; only coerces known boolean fields.
+ */
+export function normalizeTaskData(data: TaskData): TaskData {
+  const interaction = data?.interaction;
+
+  if (!interaction) {
+    return data;
+  }
+
+  const details = interaction.callProcessingDetails;
+  const updatedDetails = details ? normalizeFields(details, booleanKeys) : undefined;
+  const updatedInteractionBooleans = normalizeFields(
+    interaction,
+    interactionBooleanKeys as string[]
+  );
+
+  let updatedParticipants: typeof interaction.participants | undefined;
+  const participants = interaction.participants || {};
+  Object.keys(participants).forEach((id) => {
+    const participant = participants[id];
+    const normalized = normalizeFields(participant, participantBooleanKeys);
+    if (normalized) {
+      if (!updatedParticipants) {
+        updatedParticipants = {...participants};
+      }
+      updatedParticipants[id] = normalized;
+    }
+  });
+
+  let updatedMedia: typeof interaction.media | undefined;
+  const mediaEntries = interaction.media || {};
+  Object.keys(mediaEntries).forEach((id) => {
+    const media = mediaEntries[id];
+    const normalized = normalizeFields(media, ['isHold']);
+    if (normalized) {
+      if (!updatedMedia) {
+        updatedMedia = {...mediaEntries};
+      }
+      updatedMedia[id] = normalized;
+    }
+  });
+
+  if (!updatedDetails && !updatedInteractionBooleans && !updatedParticipants && !updatedMedia) {
+    return data;
+  }
+
+  return {
+    ...data,
+    interaction: {
+      ...interaction,
+      ...(updatedInteractionBooleans || {}),
+      callProcessingDetails: updatedDetails || details,
+      participants: updatedParticipants || interaction.participants,
+      media: updatedMedia || interaction.media,
+    },
+  };
+}