@webex/contact-center 3.12.0-next.9 → 3.12.0-task-refactor.2

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

@@ -0,0 +1,150 @@
+/**
+ * Constants for the task state machine.
+ * These enums define the allowed states, events, and built-in action identifiers.
+ */
+
+// ============================================
+// Conference Constants
+// ============================================
+
+/**
+ * Maximum number of participants allowed in a multi-party conference.
+ * Max 7 counted agents + 1 customer.
+ */
+export const MAX_PARTICIPANTS_IN_MULTIPARTY_CONFERENCE = 7;
+
+// ============================================
+// Participant Type Constants
+// ============================================
+
+/** Participant types for conference filtering */
+export const PARTICIPANT_TYPE = {
+  CUSTOMER: 'Customer',
+  SUPERVISOR: 'Supervisor',
+  VVA: 'VVA',
+} as const;
+
+export type ParticipantType = (typeof PARTICIPANT_TYPE)[keyof typeof PARTICIPANT_TYPE];
+
+// ============================================
+// Media Type Constants
+// ============================================
+
+/** Media type for consult calls */
+export const MEDIA_TYPE_CONSULT = 'consult';
+
+/** Media type for main calls */
+export const MEDIA_TYPE_MAIN_CALL = 'mainCall';
+
+// ============================================
+// State Machine Enums
+// ============================================
+
+export enum TaskState {
+  IDLE = 'IDLE',
+  OFFERED = 'OFFERED',
+  CONNECTED = 'CONNECTED',
+
+  // Intermediate states for async operations
+  HOLD_INITIATING = 'HOLD_INITIATING',
+  HELD = 'HELD',
+  RESUME_INITIATING = 'RESUME_INITIATING',
+  CONSULT_INITIATING = 'CONSULT_INITIATING',
+  CONSULTING = 'CONSULTING',
+  CONF_INITIATING = 'CONF_INITIATING',
+
+  CONFERENCING = 'CONFERENCING',
+  WRAPPING_UP = 'WRAPPING_UP',
+  COMPLETED = 'COMPLETED',
+  TERMINATED = 'TERMINATED',
+
+  // NOT IMPLEMENTED: MPC (Multi-Party Conference) states
+  CONSULT_INITIATED = 'CONSULT_INITIATED',
+  CONSULT_COMPLETED = 'CONSULT_COMPLETED',
+  // NOT IMPLEMENTED: Post-call state (isWxccPostCallEnabled feature flag)
+  POST_CALL = 'POST_CALL',
+  // NOT IMPLEMENTED: Parked state
+  PARKED = 'PARKED',
+  // NOT IMPLEMENTED: Monitoring/Supervisory states
+  MONITORING = 'MONITORING',
+}
+
+export enum TaskEvent {
+  TASK_INCOMING = 'TASK_INCOMING',
+  TASK_OFFERED = 'TASK_OFFERED',
+
+  // Offer events
+  OFFER_CONSULT = 'OFFER_CONSULT',
+  HYDRATE = 'HYDRATE',
+
+  // Internal "data refresh" events
+  CONTACT_UPDATED = 'CONTACT_UPDATED',
+  CONTACT_OWNER_CHANGED = 'CONTACT_OWNER_CHANGED',
+
+  // Assignment events
+  ASSIGN = 'ASSIGN',
+
+  // Hold/Resume events
+  HOLD_SUCCESS = 'HOLD_SUCCESS',
+  HOLD_FAILED = 'HOLD_FAILED',
+  UNHOLD_SUCCESS = 'UNHOLD_SUCCESS',
+  UNHOLD_FAILED = 'UNHOLD_FAILED',
+  HOLD_INITIATED = 'HOLD_INITIATED',
+  UNHOLD_INITIATED = 'UNHOLD_INITIATED',
+
+  // Consult events
+  CONSULT = 'CONSULT',
+  CONSULT_SUCCESS = 'CONSULT_SUCCESS',
+  CONSULT_CREATED = 'CONSULT_CREATED',
+  CONSULTING_ACTIVE = 'CONSULTING_ACTIVE',
+  CONSULT_END = 'CONSULT_END',
+  CONSULT_FAILED = 'CONSULT_FAILED',
+
+  // Conference events
+  MERGE_TO_CONFERENCE = 'MERGE_TO_CONFERENCE',
+  CONFERENCE_START = 'CONFERENCE_START',
+  CONFERENCE_FAILED = 'CONFERENCE_FAILED',
+  CONFERENCE_END = 'CONFERENCE_END',
+  TRANSFER_CONFERENCE = 'TRANSFER_CONFERENCE',
+  TRANSFER_CONFERENCE_SUCCESS = 'TRANSFER_CONFERENCE_SUCCESS',
+  TRANSFER_CONFERENCE_FAILED = 'TRANSFER_CONFERENCE_FAILED',
+  PARTICIPANT_LEAVE = 'PARTICIPANT_LEAVE',
+  EXIT_CONFERENCE = 'EXIT_CONFERENCE',
+  EXIT_CONFERENCE_SUCCESS = 'EXIT_CONFERENCE_SUCCESS',
+  EXIT_CONFERENCE_FAILED = 'EXIT_CONFERENCE_FAILED',
+
+  // Recording events
+  RECORDING_STARTED = 'RECORDING_STARTED',
+  PAUSE_RECORDING = 'PAUSE_RECORDING',
+  RESUME_RECORDING = 'RESUME_RECORDING',
+
+  // Transfer events
+  TRANSFER_SUCCESS = 'TRANSFER_SUCCESS',
+  TRANSFER_FAILED = 'TRANSFER_FAILED',
+
+  // Wrapup events
+  WRAPUP_COMPLETE = 'WRAPUP_COMPLETE',
+
+  // End events
+  TASK_WRAPUP = 'TASK_WRAPUP',
+  RONA = 'RONA', // Ring On No Answer
+  CONTACT_ENDED = 'CONTACT_ENDED',
+
+  // Failure events
+  ASSIGN_FAILED = 'ASSIGN_FAILED',
+  INVITE_FAILED = 'INVITE_FAILED',
+  OUTBOUND_FAILED = 'OUTBOUND_FAILED',
+
+  // Switch events (toggle between consult and main call)
+  SWITCH_TO_MAIN_CALL = 'SWITCH_TO_MAIN_CALL',
+  SWITCH_TO_CONSULT = 'SWITCH_TO_CONSULT',
+
+  // Accept/Decline (WebRTC)
+  ACCEPT = 'ACCEPT',
+  DECLINE = 'DECLINE',
+  END = 'END',
+
+  // Queue events
+  CTQ_CANCEL = 'CTQ_CANCEL', // Cancel To Queue
+  CTQ_CANCEL_FAILED = 'CTQ_CANCEL_FAILED',
+}

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

@@ -0,0 +1,303 @@
+/**
+ * Task State Machine Guards
+ *
+ * Guard functions that determine if a state transition is allowed.
+ * These functions validate the current context before allowing transitions.
+ *
+ * All guards are consolidated here for:
+ * - Single source of truth
+ * - Easy testing
+ * - Reusability across state machine transitions
+ *
+ * Guards are organized by category:
+ * 1. Helper Functions - Extract data from events/context
+ * 2. Hydrate Guards - For state restoration on page refresh
+ * 3. Conference Guards - Conference state checks
+ * 4. Customer Guards - Customer presence checks
+ * 5. Consult Guards - Consult flow checks
+ * 6. Wrapup Guards - End-of-call flow checks
+ * 7. Server State Guards - Check backend-reported state
+ * 8. Recording Guards - Recording state checks
+ */
+
+import {TaskContext, TaskEventPayload} from './types';
+import {TaskData} from '../types';
+import {
+  getIsCustomerInCall,
+  getConferenceParticipantsCount,
+  getIsConferenceInProgress,
+} from '../TaskUtils';
+import {TaskEvent} from './constants';
+
+export const getTaskDataFromEvent = (event?: TaskEventPayload): TaskData | undefined =>
+  event && typeof event === 'object' && 'taskData' in event
+    ? (event as {taskData?: TaskData}).taskData
+    : undefined;
+
+export const getSelfAgentId = (context: TaskContext, taskData?: TaskData): string | undefined =>
+  context.uiControlConfig?.agentId ?? context.taskData?.agentId ?? taskData?.agentId;
+
+export const isSelfConsultingAgent = (context: TaskContext, taskData?: TaskData): boolean => {
+  const selfAgentId = getSelfAgentId(context, taskData);
+  if (!selfAgentId) return false;
+
+  return taskData?.consultingAgentId === selfAgentId;
+};
+
+/**
+ * Determines if this agent should enter WRAPPING_UP state.
+ * Priority: agentsPendingWrapUp > wrapUpRequired / participant.isWrapUp > ownership > !isConsulted
+ */
+export const shouldWrapUpForThisAgent = (context: TaskContext, taskData: TaskData): boolean => {
+  const selfAgentId = getSelfAgentId(context, taskData);
+  if (!selfAgentId) return false;
+
+  const pending = taskData?.agentsPendingWrapUp;
+  if (Array.isArray(pending) && pending.length > 0) {
+    return pending.includes(selfAgentId);
+  }
+
+  const participantWrapUp = taskData?.interaction?.participants?.[selfAgentId]?.isWrapUp === true;
+  const wrapUpRequired = taskData?.wrapUpRequired === true;
+  if (wrapUpRequired || participantWrapUp) {
+    return true;
+  }
+
+  const owner = taskData?.interaction?.owner;
+  if (owner && owner === selfAgentId) {
+    return true;
+  }
+
+  if (taskData?.isConsulted === false) {
+    return true;
+  }
+
+  return false;
+};
+
+export interface GuardParams {
+  context: TaskContext;
+  event?: TaskEventPayload;
+}
+
+export type GuardFunction = (params: GuardParams) => boolean;
+
+export const guards = {
+  // Hydrate Guards
+  isInteractionTerminated: ({context, event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+
+    if (taskData?.interaction?.isTerminated === true) return true;
+
+    const selfAgentId = getSelfAgentId(context, taskData);
+    if (selfAgentId && taskData?.interaction?.participants?.[selfAgentId]?.isWrapUp === true) {
+      return true;
+    }
+
+    return false;
+  },
+
+  isInteractionConsulting: ({event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+
+    if (taskData?.interaction?.state === 'consulting') return true;
+
+    // EP_DN consulted agent: backend reports state as 'connected' but CPD indicates consult
+    const cpd = taskData?.interaction?.callProcessingDetails;
+    if (cpd?.relationshipType === 'consult' && taskData?.interaction?.state === 'connected') {
+      return true;
+    }
+
+    return false;
+  },
+
+  isInteractionHeld: ({event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+
+    if (taskData?.interaction?.state === 'hold') return true;
+
+    const mainMediaId = taskData?.interaction?.mainInteractionId || taskData?.interactionId;
+    if (mainMediaId && taskData?.interaction?.media?.[mainMediaId]?.isHold === true) {
+      return true;
+    }
+
+    return false;
+  },
+
+  isInteractionConnected: ({event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+
+    return taskData?.interaction?.state === 'connected';
+  },
+
+  isConferencingByParticipants: ({event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+    if (!taskData) return false;
+    const mainCallId = taskData.interaction?.mainInteractionId || taskData.interactionId;
+    const media = taskData.interaction?.media?.[mainCallId];
+    const participants = taskData.interaction?.participants;
+    if (!media?.participants || !participants) return false;
+    let agentCount = 0;
+    for (const pId of media.participants) {
+      const p = participants[pId];
+      if (p && p.pType !== 'Customer' && p.pType !== 'Supervisor' && !p.hasLeft) {
+        agentCount += 1;
+      }
+    }
+
+    return agentCount >= 2;
+  },
+
+  // Conference Guards
+  conferenceInProgressFromEvent: ({event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+    if (!taskData?.interaction) return false;
+
+    return getIsConferenceInProgress(taskData);
+  },
+
+  /**
+   * Conference downgrade check specifically for transitioning back to CONNECTED.
+   *
+   * Returns true only when:
+   * - conference has downgraded (fewer than 2 active agent participants in main call)
+   * - customer is still in the call
+   * - current agent is still in the main call
+   */
+  shouldDowngradeConferenceToConnected: ({context, event}: GuardParams): boolean => {
+    const eventTaskData = getTaskDataFromEvent(event);
+    const taskData = eventTaskData ?? context.taskData;
+    if (!taskData?.interaction) return false;
+
+    const selfAgentId = getSelfAgentId(context, taskData);
+    if (!selfAgentId) return false;
+
+    const mainCallId = taskData.interaction.mainInteractionId || taskData.interactionId;
+    if (!mainCallId) return false;
+
+    // Don't downgrade while backend still reports conference.
+    if (taskData.interaction.state === 'conference') return false;
+
+    const agentParticipantsCount = getConferenceParticipantsCount(taskData.interaction, mainCallId);
+    if (agentParticipantsCount >= 2) return false;
+
+    const customerInCall = getIsCustomerInCall(taskData.interaction, mainCallId);
+    if (!customerInCall) return false;
+
+    const selfInMainCall = Boolean(
+      taskData.interaction.media?.[mainCallId]?.participants?.includes(selfAgentId)
+    );
+
+    return selfInMainCall;
+  },
+
+  // Consult Guards
+  /**
+   * Check if this agent initiated the consult (using event data)
+   * Handles both consultingAgentId and fallback to context flag
+   */
+  didInitiateConsult: ({context, event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+    if (taskData?.isConsulted === true) return false;
+
+    return taskData?.consultingAgentId
+      ? isSelfConsultingAgent(context, taskData)
+      : context.consultInitiator === true;
+  },
+
+  /**
+   * EP-DN / consulted consult legs can arrive as AGENT_CONTACT_ASSIGNED without a preceding
+   * AgentConsulting event. When that happens, we should enter CONSULTING (not CONNECTED).
+   */
+  isConsultingAssignment: ({event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+    if (!taskData) return false;
+
+    const relationshipType = taskData.interaction?.callProcessingDetails?.relationshipType;
+
+    return (
+      taskData.isConsulted === true ||
+      relationshipType === 'consult' ||
+      taskData.interaction?.state === 'consulting'
+    );
+  },
+
+  // Wrapup Guards
+  shouldWrapUp: ({context, event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+    if (!taskData) return false;
+
+    if (event?.type === TaskEvent.CONFERENCE_END) {
+      const selfAgentId = getSelfAgentId(context, taskData);
+      if (!selfAgentId) return false;
+
+      const pending = taskData?.agentsPendingWrapUp;
+      if (Array.isArray(pending) && pending.length > 0) {
+        return pending.includes(selfAgentId);
+      }
+
+      const participantWrapUp =
+        taskData?.interaction?.participants?.[selfAgentId]?.isWrapUp === true;
+      const wrapUpRequired = taskData?.wrapUpRequired === true;
+
+      return wrapUpRequired || participantWrapUp;
+    }
+
+    return shouldWrapUpForThisAgent(context, taskData);
+  },
+
+  /**
+   * Check if wrapUpRequired in payload OR is consult initiator
+   */
+  shouldWrapUpOrIsInitiator: ({context, event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+
+    return Boolean(taskData?.wrapUpRequired || context.consultInitiator);
+  },
+
+  /**
+   * True if PARTICIPANT_LEAVE indicates that *this* agent left the conference.
+   *
+   * Important: PARTICIPANT_LEAVE is broadcast to all agents in the conference.
+   * Only the agent whose id matches the leaving participant should transition to
+   * TERMINATED / WRAPPING_UP based on wrapup rules.
+   */
+  didCurrentAgentLeaveConference: ({context, event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+    const selfAgentId = getSelfAgentId(context, taskData);
+    if (!selfAgentId) return false;
+
+    const participantIdFromEvent =
+      event && typeof event === 'object' && 'participantId' in event
+        ? (event as {participantId?: string}).participantId
+        : undefined;
+    const participantId = participantIdFromEvent ?? taskData?.participantId;
+
+    if (Boolean(participantId) && participantId === selfAgentId) {
+      return true;
+    }
+
+    //    For EP-DN agents the backend removes the leaving participant entirely
+    //    from the participants map (rather than setting hasLeft). If this task
+    //    is in CONFERENCING (implied by the guard being evaluated here) but the
+    //    agent is absent from the updated participants, they have left.
+    const participants = taskData?.interaction?.participants;
+    if (participants && !(selfAgentId in participants)) {
+      return true;
+    }
+
+    return false;
+  },
+
+  // Server State Guards
+  isPrimaryMediaOnHold: ({event}: GuardParams): boolean => {
+    const taskData = getTaskDataFromEvent(event);
+    if (!taskData) return false;
+    const mediaId = taskData.mediaResourceId;
+    if (!mediaId) return false;
+
+    return taskData.interaction?.media?.[mediaId]?.isHold === true;
+  },
+};
+
+export type GuardName = keyof typeof guards;

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

@@ -0,0 +1,28 @@
+/**
+ * Task State Machine
+ *
+ * Export all state machine components for easy importing
+ */
+
+// Main state machine
+export {createTaskStateMachine} from './TaskStateMachine';
+export type {TaskStateMachine} from './TaskStateMachine';
+
+// Types & enums
+export {TaskState, TaskEvent} from './constants';
+export {isEventOfType} from './types';
+export type {
+  TaskContext,
+  TaskEventPayload,
+  TaskStateMachineConfig,
+  UIControlConfig,
+  TaskActionsMap,
+  TaskActionArgs,
+} from './types';
+
+// Guards
+export {guards} from './guards';
+export type {GuardParams, GuardFunction} from './guards';
+
+// Actions
+export {actions, createInitialContext} from './actions';