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

package/src/services/task/TaskUtils.ts

@@ -1,8 +1,173 @@
 /* eslint-disable import/prefer-default-export */
 import {Interaction, ITask, TaskData, MEDIA_CHANNEL} from './types';
-import {CC_EVENTS} from '../config/types';
-import {OUTDIAL_DIRECTION, OUTDIAL_MEDIA_TYPE, OUTBOUND_TYPE} from '../../constants';
 import {LoginOption} from '../../types';
+import {
+  PARTICIPANT_TYPE,
+  MEDIA_TYPE_MAIN_CALL,
+  CONSULT_STATE,
+  INTERACTION_STATE,
+  MEDIA_TYPE_CONSULT,
+} from './state-machine/constants';
+import {TaskContext} from './state-machine/types';
+import {CC_EVENTS} from '../config/types';
+import {OUTBOUND_TYPE, OUTDIAL_DIRECTION, OUTDIAL_MEDIA_TYPE} from '../../constants';
+
+type AISummaryError = Error & {data?: Record<string, unknown>};
+
+export const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
+export const createSummaryError = (errorCode: string): AISummaryError => {
+  const error = new Error(errorCode) as AISummaryError;
+
+  error.data = {errorCode};
+
+  return error;
+};
+
+const CAMPAIGN_PREVIEW_OUTBOUND_TYPES = ['STANDARD_PREVIEW_CAMPAIGN', 'DIRECT_PREVIEW_CAMPAIGN'];
+const CAMPAIGN_PREVIEW_CAMPAIGN_TYPES = ['preview_standard', 'preview_direct'];
+
+/**
+ * Checks if the customer is still in the call (not left)
+ *
+ * @param interaction - The interaction object
+ * @param interactionId - The main interaction ID
+ * @returns true if customer is in the call
+ */
+export const getIsCustomerInCall = (interaction: Interaction, interactionId: string): boolean => {
+  const mainCallMedia = interaction.media?.[interactionId];
+  const participants = interaction.participants;
+  if (!mainCallMedia?.participants || !participants) {
+    return false;
+  }
+
+  return mainCallMedia.participants.some((participantId: string) => {
+    const participant = participants[participantId];
+
+    return participant?.pType === PARTICIPANT_TYPE.CUSTOMER && !participant.hasLeft;
+  });
+};
+
+/**
+ * Gets the count of active agent participants in the conference
+ * Excludes Customer, Supervisor, and VVA participant types
+ *
+ * @param interaction - The interaction object
+ * @param interactionId - The main interaction ID
+ * @returns Number of active agent participants
+ */
+export const getConferenceParticipantsCount = (
+  interaction: Interaction,
+  interactionId: string
+): number => {
+  const mainCallMedia = interaction.media?.[interactionId];
+  const participants = interaction.participants;
+  if (!mainCallMedia?.participants || !participants) {
+    return 0;
+  }
+
+  let count = 0;
+  for (const participantId of mainCallMedia.participants) {
+    const participant = participants[participantId];
+    if (
+      participant &&
+      participant.pType !== PARTICIPANT_TYPE.CUSTOMER &&
+      participant.pType !== PARTICIPANT_TYPE.SUPERVISOR &&
+      participant.pType !== PARTICIPANT_TYPE.VVA &&
+      !participant.hasLeft
+    ) {
+      count += 1;
+    }
+  }
+
+  return count;
+};
+
+/**
+ * Determines if a consult is actively in-progress for conference control gating.
+ * This is used to disable conference controls (End/Consult) only when a consult leg
+ * still exists outside the main call participants.
+ */
+export const getIsConsultInProgressForConferenceControls = (
+  interaction: Interaction | undefined,
+  mainCallId: string | undefined,
+  selfAgentId: string | undefined
+): boolean => {
+  if (!interaction || !mainCallId) return false;
+
+  const mainParticipants = interaction.media?.[mainCallId]?.participants;
+  if (!Array.isArray(mainParticipants) || mainParticipants.length === 0) return false;
+
+  const mainSet = new Set(mainParticipants);
+  const media = interaction.media;
+  if (!media) return false;
+
+  return Object.values(media).some((m: any) => {
+    if (!m || m.mType !== 'consult') return false;
+    if (!Array.isArray(m.participants) || m.participants.length === 0) return false;
+
+    return m.participants.some((participantId: string) => {
+      const p: any = interaction.participants?.[participantId];
+      if (!p || p.hasLeft) return false;
+      if (selfAgentId && participantId === selfAgentId) return false;
+      if (mainSet.has(participantId)) return false;
+
+      const participantType = String(p.pType ?? '').toUpperCase();
+      const isEpDnParticipant =
+        participantType === 'EP-DN' || participantType === 'EP_DN' || participantType === 'DN';
+      if (isEpDnParticipant) {
+        if (!selfAgentId) {
+          return true;
+        }
+        const selfConsultState = interaction.participants?.[selfAgentId]?.consultState as
+          | string
+          | undefined;
+
+        return (
+          selfConsultState === 'consulting' ||
+          selfConsultState === 'conferencing' ||
+          selfConsultState === 'consultInitiated'
+        );
+      }
+
+      const consultState = p.consultState as string | undefined;
+      const isRonaPendingConsultee = consultState === 'consultReserved' && p.hasJoined === false;
+      const consultLegActive =
+        consultState === 'consulting' ||
+        p.currentState === 'consulting' ||
+        (p.isConsulted === true && consultState !== 'consultCompleted' && !isRonaPendingConsultee);
+
+      return consultLegActive;
+    });
+  });
+};
+
+export const getIsConsultedAgentForControls = (
+  taskData: TaskData | null,
+  context: TaskContext,
+  isConsultingState: boolean
+): boolean => {
+  return Boolean(taskData?.isConsulted) || (isConsultingState && !context.consultInitiator);
+};
+
+export const getServerHoldStateForControls = (
+  context: TaskContext,
+  mainCallId?: string,
+  fallbackTaskData?: TaskData | null
+): boolean | undefined => {
+  const media = context.taskData?.interaction?.media ?? fallbackTaskData?.interaction?.media;
+  if (!media) return undefined;
+
+  if (mainCallId && media[mainCallId]) {
+    return media[mainCallId].isHold ?? false;
+  }
+
+  const mediaId = context.taskData?.mediaResourceId ?? fallbackTaskData?.mediaResourceId;
+  if (!mediaId) return undefined;
+
+  return media[mediaId]?.isHold;
+};
 
 /**
  * Determines if the given agent is the primary agent (owner) of the task
@@ -32,7 +197,9 @@ export const isParticipantInMainInteraction = (task: ITask, agentId: string): bo
 
   return Object.values(task.data.interaction.media).some(
     (mediaObj) =>
-      mediaObj && mediaObj.mType === 'mainCall' && mediaObj.participants?.includes(agentId)
+      mediaObj &&
+      mediaObj.mType === MEDIA_TYPE_MAIN_CALL &&
+      mediaObj.participants?.includes(agentId)
   );
 };
 
@@ -56,33 +223,110 @@ export const checkParticipantNotInInteraction = (task: ITask, agentId: string):
 
 /**
  * Determines if a conference is currently in progress based on the number of active agent participants
- * @param TaskData - The payLoad data to check for conference status
+ * @param data - The task data to check for conference status
  * @returns true if there are 2 or more active agent participants in the main call, false otherwise
+ *
+ * For Agent B (consulted agent), their task's interactionId may be different from the main call.
+ * We use mainInteractionId from the interaction if available, otherwise fallback to interactionId.
  */
 export const getIsConferenceInProgress = (data: TaskData): boolean => {
-  const mediaMainCall = data.interaction.media?.[data?.interactionId];
+  if (!data.interaction) return false;
+
+  const mainCallId = data.interaction.mainInteractionId || data.interactionId;
+  const mediaMainCall = data.interaction.media?.[mainCallId];
   const participantsInMainCall = new Set(mediaMainCall?.participants);
-  const participants = data.interaction.participants;
+  const {participants} = data.interaction;
 
   const agentParticipants = new Set();
-  if (participantsInMainCall.size > 0) {
-    participantsInMainCall.forEach((participantId: string) => {
-      const participant = participants?.[participantId];
-      if (
-        participant &&
-        participant.pType !== 'Customer' &&
-        participant.pType !== 'Supervisor' &&
-        !participant.hasLeft &&
-        participant.pType !== 'VVA'
-      ) {
-        agentParticipants.add(participantId);
-      }
-    });
-  }
+  participantsInMainCall.forEach((participantId: string) => {
+    const participant = participants[participantId];
+    if (
+      participant &&
+      participant.pType !== PARTICIPANT_TYPE.CUSTOMER &&
+      participant.pType !== PARTICIPANT_TYPE.SUPERVISOR &&
+      participant.pType !== PARTICIPANT_TYPE.VVA &&
+      !participant.hasLeft
+    ) {
+      agentParticipants.add(participantId);
+    }
+  });
 
   return agentParticipants.size >= 2;
 };
 
+const EP_DN_MERGE_TERMINAL_CONSULT_EVENTS = new Set<string>([
+  CC_EVENTS.AGENT_CONSULT_ENDED,
+  CC_EVENTS.AGENT_CONSULT_CONFERENCE_ENDED,
+]);
+
+const isEpDnParticipantType = (pType: string | undefined): boolean => {
+  const normalized = String(pType ?? '').toUpperCase();
+
+  return normalized === 'EP-DN' || normalized === 'EP_DN' || normalized === 'DN';
+};
+
+/** EP-DN consult merged to conference before a second agent joins the main leg (CAI-8329). */
+export const isEpDnConsultPendingConferenceMerge = (
+  taskData: TaskData | undefined,
+  selfAgentId: string | undefined
+): boolean => {
+  if (!taskData?.interaction || !selfAgentId) return false;
+
+  if (taskData.type && EP_DN_MERGE_TERMINAL_CONSULT_EVENTS.has(taskData.type)) {
+    return false;
+  }
+
+  const interaction = taskData.interaction;
+  const mainCallId = interaction.mainInteractionId || taskData.interactionId;
+  if (!mainCallId) return false;
+
+  if (getConferenceParticipantsCount(interaction, mainCallId) > 1) return false;
+
+  const selfParticipant = interaction.participants?.[selfAgentId] as
+    | {consultState?: string}
+    | undefined;
+  if (taskData.isConsulted === true || selfParticipant?.consultState === 'consultCompleted') {
+    return false;
+  }
+
+  const mainParticipantIds = new Set(interaction.media?.[mainCallId]?.participants ?? []);
+  const hasEpDnOnConsultLegNotMain = Object.values(interaction.media ?? {}).some((media: any) => {
+    if (media?.mType !== MEDIA_TYPE_CONSULT) return false;
+
+    return (media.participants ?? []).some((participantId: string) => {
+      if (participantId === selfAgentId || mainParticipantIds.has(participantId)) return false;
+      const participant = interaction.participants?.[participantId] as
+        | {hasLeft?: boolean; pType?: string}
+        | undefined;
+      if (!participant || participant.hasLeft) return false;
+
+      return isEpDnParticipantType(participant.pType);
+    });
+  });
+  if (!hasEpDnOnConsultLegNotMain) return false;
+
+  const callProcessingDetails = interaction.callProcessingDetails as
+    | {hasCustomerLeft?: string}
+    | undefined;
+  const customerLeft =
+    callProcessingDetails?.hasCustomerLeft === 'true' ||
+    !getIsCustomerInCall(interaction, mainCallId);
+
+  const conferenceFromPayload =
+    interaction.state === INTERACTION_STATE.CONFERENCE ||
+    getIsConferenceInProgress(taskData) ||
+    (interaction.state === INTERACTION_STATE.POST_CALL && customerLeft);
+  if (!conferenceFromPayload) return false;
+
+  return (
+    taskData.consultingAgentId === selfAgentId ||
+    interaction.owner === selfAgentId ||
+    selfParticipant?.consultState === CONSULT_STATE.CONSULTING ||
+    selfParticipant?.consultState === CONSULT_STATE.CONFERENCING ||
+    selfParticipant?.consultState === 'consultInitiated'
+  );
+};
+
 /**
  * Checks if the current agent is a secondary agent in a consultation scenario.
  * Secondary agents are those who were consulted (not the original call owner).
@@ -104,17 +348,30 @@ export const isSecondaryAgent = (interaction: Interaction): boolean => {
 /**
  * Checks if the current agent is a secondary EP-DN (Entry Point Dial Number) agent.
  * This is specifically for telephony consultations to external numbers/entry points.
- * @param task - The task object containing interaction details
+ * @param interaction - The interaction object
  * @returns true if this is a secondary EP-DN agent in telephony consultation, false otherwise
  */
 export const isSecondaryEpDnAgent = (interaction: Interaction): boolean => {
-  if (!interaction) {
-    return false;
-  }
-
   return interaction.mediaType === 'telephony' && isSecondaryAgent(interaction);
 };
 
+/**
+ * Checks if the task belongs to a campaign preview interaction.
+ * Campaign preview ContactEnded events are terminal cleanup events and should not trigger wrapup.
+ */
+export const isCampaignPreviewTask = (taskData?: TaskData | null): boolean => {
+  const outboundType = taskData?.interaction?.outboundType ?? '';
+  const cpd = taskData?.interaction?.callProcessingDetails as unknown as
+    | Record<string, string | undefined>
+    | undefined;
+  const campaignType = cpd?.campaignType ?? '';
+
+  return (
+    CAMPAIGN_PREVIEW_OUTBOUND_TYPES.includes(outboundType) ||
+    CAMPAIGN_PREVIEW_CAMPAIGN_TYPES.includes(campaignType)
+  );
+};
+
 /**
  * Checks if auto-answer is enabled for the agent participant
  * @param interaction - The interaction object
@@ -221,6 +478,40 @@ export const shouldAutoAnswerTask = (
   return false;
 };
 
+/**
+ * Gets the consult media resource ID for switch-call operations.
+ * Searches for the consult media leg in the interaction.
+ *
+ * @param interaction - The interaction object
+ * @param consultMediaResourceId - The consult media resource ID from task data
+ * @param agentId - Current agent ID
+ * @returns The consult media resource ID or undefined
+ */
+export const getConsultMediaResourceId = (
+  interaction: Interaction | undefined,
+  consultMediaResourceId: string | undefined,
+  agentId: string | undefined
+): string | undefined => {
+  // First priority: use consultMediaResourceId from task data if available
+  if (consultMediaResourceId) {
+    return consultMediaResourceId;
+  }
+
+  // Second priority: search for consult media leg in interaction.media
+  if (!interaction?.media || !agentId) {
+    return undefined;
+  }
+
+  // Find the consult media leg where this agent is a participant
+  for (const [mediaId, media] of Object.entries(interaction.media)) {
+    if (media.mType === 'consult' && media.participants?.includes(agentId)) {
+      return mediaId;
+    }
+  }
+
+  return undefined;
+};
+
 /**
  * Checks if a task is a campaign preview reservation that has not yet been accepted.
  * Campaign preview tasks should not trigger incoming call handling until the agent

package/src/services/task/WebexCallingUtils.ts

@@ -0,0 +1,136 @@
+import {TaskState} from './state-machine/constants';
+
+export type WebexCallingDeviceDetails = {
+  deviceType: string;
+  deviceId: string;
+  deviceCallId: string;
+};
+
+type WebexCallingParticipant = {
+  id?: unknown;
+  deviceType?: unknown;
+  deviceCallId?: unknown;
+  deviceId?: unknown;
+};
+
+const normalizeId = (id: unknown): string | undefined => {
+  if (typeof id !== 'string') {
+    return undefined;
+  }
+
+  const normalizedId = id.trim();
+
+  return normalizedId === '' ? undefined : normalizedId;
+};
+
+const isParticipantsById = (participants: unknown): participants is Record<string, unknown> =>
+  Boolean(participants) &&
+  typeof participants === 'object' &&
+  !Array.isArray(participants) &&
+  !(participants instanceof Map);
+
+const hasWebexCallingDeviceDetails = (
+  participant: unknown
+): participant is WebexCallingParticipant &
+  Pick<WebexCallingDeviceDetails, 'deviceCallId' | 'deviceId'> => {
+  const participantDetails = participant as WebexCallingParticipant | undefined;
+
+  return (
+    typeof participantDetails?.deviceCallId === 'string' &&
+    participantDetails.deviceCallId.trim() !== '' &&
+    typeof participantDetails?.deviceId === 'string' &&
+    participantDetails.deviceId.trim() !== ''
+  );
+};
+
+const isWebexCallingParticipantForAgent = (
+  participant: unknown,
+  agentId: string
+): participant is WebexCallingParticipant &
+  Pick<WebexCallingDeviceDetails, 'deviceCallId' | 'deviceId'> => {
+  const participantDetails = participant as WebexCallingParticipant | undefined;
+
+  return (
+    normalizeId(participantDetails?.id) === agentId && hasWebexCallingDeviceDetails(participant)
+  );
+};
+
+const getWebexCallingDeviceDetails = (
+  participant: WebexCallingParticipant &
+    Pick<WebexCallingDeviceDetails, 'deviceCallId' | 'deviceId'>
+): WebexCallingDeviceDetails => ({
+  deviceType: typeof participant.deviceType === 'string' ? participant.deviceType : '',
+  deviceId: participant.deviceId,
+  deviceCallId: participant.deviceCallId,
+});
+
+export function getWebexCallingDeviceDetailsForAgent(
+  agentId: string | undefined,
+  participants: unknown
+): WebexCallingDeviceDetails | undefined {
+  const normalizedAgentId = normalizeId(agentId);
+  if (!normalizedAgentId || !isParticipantsById(participants)) {
+    return undefined;
+  }
+
+  const agentParticipant = participants[normalizedAgentId];
+  const matchingAgentParticipant = hasWebexCallingDeviceDetails(agentParticipant)
+    ? agentParticipant
+    : Object.values(participants).find((participant) =>
+        isWebexCallingParticipantForAgent(participant, normalizedAgentId)
+      );
+
+  if (!matchingAgentParticipant || !hasWebexCallingDeviceDetails(matchingAgentParticipant)) {
+    return undefined;
+  }
+
+  return getWebexCallingDeviceDetails(matchingAgentParticipant);
+}
+
+export function isWebexCallingCallForAgent(
+  agentId: string | undefined,
+  participants: unknown
+): boolean {
+  return Boolean(getWebexCallingDeviceDetailsForAgent(agentId, participants));
+}
+
+/** Matches wxAppVoiceMethods.getWebexCallingCallId engaged semantics for uiControls. */
+export function isWxAppEngagedForControls(
+  enableWxBetterTogether: boolean,
+  agentId: string | undefined,
+  participants: unknown,
+  state: TaskState
+): boolean {
+  if (!enableWxBetterTogether) {
+    return false;
+  }
+
+  if (
+    !state ||
+    state === TaskState.OFFERED ||
+    state === TaskState.IDLE ||
+    state === TaskState.WRAPPING_UP ||
+    state === TaskState.TERMINATED ||
+    state === TaskState.COMPLETED
+  ) {
+    return false;
+  }
+
+  const details = getWebexCallingDeviceDetailsForAgent(agentId, participants);
+
+  return details?.deviceType === 'wxApp';
+}
+
+export function decodedLineOwnerId(lineOwnerId?: string): string | undefined {
+  if (!lineOwnerId) {
+    return undefined;
+  }
+
+  try {
+    const decoded = atob(lineOwnerId);
+
+    return decoded.split('/').pop();
+  } catch {
+    return undefined;
+  }
+}