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

package/dist/types/services/task/state-machine/actions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Task State Machine Actions - Action implementations executed during state transitions
+ */
+import { TaskContext, TaskEventPayload, UIControlConfig, TaskActionsMap } from './types';
+import { TaskState } from './constants';
+export declare function createInitialContext(uiControlConfig: UIControlConfig, initialState?: TaskState): TaskContext;
+export declare function updateUIControls(currentState: TaskState): import("xstate").ActionFunction<TaskContext, TaskEventPayload, TaskEventPayload, {}, import("xstate").ProvidedActor, never, never, never, never>;
+export declare const actions: TaskActionsMap;

package/dist/types/services/task/state-machine/constants.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Constants for the task state machine.
+ * These enums define the allowed states, events, and built-in action identifiers.
+ */
+/**
+ * Maximum number of participants allowed in a multi-party conference.
+ * Max 7 counted agents + 1 customer.
+ */
+export declare const MAX_PARTICIPANTS_IN_MULTIPARTY_CONFERENCE = 7;
+/** Participant types for conference filtering */
+export declare const PARTICIPANT_TYPE: {
+    readonly CUSTOMER: "Customer";
+    readonly SUPERVISOR: "Supervisor";
+    readonly VVA: "VVA";
+};
+export type ParticipantType = (typeof PARTICIPANT_TYPE)[keyof typeof PARTICIPANT_TYPE];
+/** Media type for consult calls */
+export declare const MEDIA_TYPE_CONSULT = "consult";
+/** Media type for main calls */
+export declare const MEDIA_TYPE_MAIN_CALL = "mainCall";
+export declare enum TaskState {
+    IDLE = "IDLE",
+    OFFERED = "OFFERED",
+    CONNECTED = "CONNECTED",
+    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",
+    CONSULT_INITIATED = "CONSULT_INITIATED",
+    CONSULT_COMPLETED = "CONSULT_COMPLETED",
+    POST_CALL = "POST_CALL",
+    PARKED = "PARKED",
+    MONITORING = "MONITORING"
+}
+export declare enum TaskEvent {
+    TASK_INCOMING = "TASK_INCOMING",
+    TASK_OFFERED = "TASK_OFFERED",
+    OFFER_CONSULT = "OFFER_CONSULT",
+    HYDRATE = "HYDRATE",
+    CONTACT_UPDATED = "CONTACT_UPDATED",
+    CONTACT_OWNER_CHANGED = "CONTACT_OWNER_CHANGED",
+    ASSIGN = "ASSIGN",
+    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 = "CONSULT",
+    CONSULT_SUCCESS = "CONSULT_SUCCESS",
+    CONSULT_CREATED = "CONSULT_CREATED",
+    CONSULTING_ACTIVE = "CONSULTING_ACTIVE",
+    CONSULT_END = "CONSULT_END",
+    CONSULT_FAILED = "CONSULT_FAILED",
+    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_STARTED = "RECORDING_STARTED",
+    PAUSE_RECORDING = "PAUSE_RECORDING",
+    RESUME_RECORDING = "RESUME_RECORDING",
+    TRANSFER_SUCCESS = "TRANSFER_SUCCESS",
+    TRANSFER_FAILED = "TRANSFER_FAILED",
+    WRAPUP_COMPLETE = "WRAPUP_COMPLETE",
+    TASK_WRAPUP = "TASK_WRAPUP",
+    RONA = "RONA",// Ring On No Answer
+    CONTACT_ENDED = "CONTACT_ENDED",
+    ASSIGN_FAILED = "ASSIGN_FAILED",
+    INVITE_FAILED = "INVITE_FAILED",
+    OUTBOUND_FAILED = "OUTBOUND_FAILED",
+    SWITCH_TO_MAIN_CALL = "SWITCH_TO_MAIN_CALL",
+    SWITCH_TO_CONSULT = "SWITCH_TO_CONSULT",
+    ACCEPT = "ACCEPT",
+    DECLINE = "DECLINE",
+    END = "END",
+    CTQ_CANCEL = "CTQ_CANCEL",// Cancel To Queue
+    CTQ_CANCEL_FAILED = "CTQ_CANCEL_FAILED"
+}

package/dist/types/services/task/state-machine/guards.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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';
+export declare const getTaskDataFromEvent: (event?: TaskEventPayload) => TaskData | undefined;
+export declare const getSelfAgentId: (context: TaskContext, taskData?: TaskData) => string | undefined;
+export declare const isSelfConsultingAgent: (context: TaskContext, taskData?: TaskData) => boolean;
+/**
+ * Determines if this agent should enter WRAPPING_UP state.
+ * Priority: agentsPendingWrapUp > wrapUpRequired / participant.isWrapUp > ownership > !isConsulted
+ */
+export declare const shouldWrapUpForThisAgent: (context: TaskContext, taskData: TaskData) => boolean;
+export interface GuardParams {
+    context: TaskContext;
+    event?: TaskEventPayload;
+}
+export type GuardFunction = (params: GuardParams) => boolean;
+export declare const guards: {
+    isInteractionTerminated: ({ context, event }: GuardParams) => boolean;
+    isInteractionConsulting: ({ event }: GuardParams) => boolean;
+    isInteractionHeld: ({ event }: GuardParams) => boolean;
+    isInteractionConnected: ({ event }: GuardParams) => boolean;
+    isConferencingByParticipants: ({ event }: GuardParams) => boolean;
+    conferenceInProgressFromEvent: ({ event }: GuardParams) => boolean;
+    /**
+     * 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;
+    /**
+     * Check if this agent initiated the consult (using event data)
+     * Handles both consultingAgentId and fallback to context flag
+     */
+    didInitiateConsult: ({ context, event }: GuardParams) => boolean;
+    /**
+     * 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;
+    shouldWrapUp: ({ context, event }: GuardParams) => boolean;
+    /**
+     * Check if wrapUpRequired in payload OR is consult initiator
+     */
+    shouldWrapUpOrIsInitiator: ({ context, event }: GuardParams) => boolean;
+    /**
+     * 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;
+    isPrimaryMediaOnHold: ({ event }: GuardParams) => boolean;
+};
+export type GuardName = keyof typeof guards;

package/dist/types/services/task/state-machine/index.d.ts

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

package/dist/types/services/task/state-machine/types.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Task State Machine Types
+ *
+ * Type definitions for the XState-based task state machine.
+ * These types define states, events, context, and schemas for task lifecycle management.
+ */
+import type { AnyStateNodeConfig, ActionFunctionMap, EventObject, ActionArgs } from 'xstate';
+import { DestinationType, TaskChannelType, TaskData, TaskUIControls, VoiceVariant } from '../types';
+import { TaskEvent, TaskState } from './constants';
+/**
+ * Represents a participant in a conference call
+ */
+export interface ConferenceParticipant {
+    /** Unique identifier for the participant */
+    id: string;
+    /** Type of participant (agent, customer, or external party) */
+    type: 'AGENT' | 'CUSTOMER' | 'EXTERNAL';
+    /** Display name of the participant */
+    name?: string;
+    /** Timestamp when participant joined the conference */
+    joinedAt: Date;
+    /** Whether this participant initiated the conference */
+    isInitiator: boolean;
+    /** Whether this participant can be removed from the conference */
+    canBeRemoved: boolean;
+}
+/**
+ * UI Control configuration for the task
+ */
+export interface UIControlConfig {
+    /** Whether end call button is enabled (config option) */
+    isEndTaskEnabled: boolean;
+    /** Whether end consult button is enabled (config option) */
+    isEndConsultEnabled: boolean;
+    /** Channel type determines which controls are available */
+    channelType: TaskChannelType;
+    /** Optional voice channel variant to toggle WebRTC-specific controls */
+    voiceVariant?: VoiceVariant;
+    /** Whether recording controls should be shown for this task */
+    isRecordingEnabled: boolean;
+    /** Current agent ID for ownership checks (transfer conference) */
+    agentId?: string;
+}
+/**
+ * Task state machine context.
+ * Only stores data that cannot be derived from state machine state.
+ */
+export interface TaskContext {
+    taskData: TaskData | null;
+    consultInitiator: boolean;
+    exitingConference: boolean;
+    consultFromConference: boolean;
+    transferConferenceRequested: boolean;
+    consultDestinationType: DestinationType | null;
+    consultDestinationAgentId: string | null;
+    consultDestinationAgentJoined: boolean;
+    consultCallHeld: boolean;
+    recordingControlsAvailable: boolean;
+    recordingInProgress: boolean;
+    uiControlConfig: UIControlConfig;
+    uiControls: TaskUIControls;
+}
+export type RecordingStateUpdate = Partial<Pick<TaskContext, 'recordingControlsAvailable' | 'recordingInProgress'>>;
+/**
+ * Base event type - all events have a type property
+ */
+type BaseEvent<T extends TaskEvent> = {
+    type: T;
+};
+/**
+ * Event payload mapping - defines the payload for each event type
+ */
+interface TaskEventPayloadMap {
+    [TaskEvent.TASK_INCOMING]: BaseEvent<TaskEvent.TASK_INCOMING> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.TASK_OFFERED]: BaseEvent<TaskEvent.TASK_OFFERED> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.OFFER_CONSULT]: BaseEvent<TaskEvent.OFFER_CONSULT> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.HYDRATE]: BaseEvent<TaskEvent.HYDRATE> & {
+        taskData: TaskData;
+        agentId?: string;
+    };
+    [TaskEvent.CONTACT_UPDATED]: BaseEvent<TaskEvent.CONTACT_UPDATED> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.CONTACT_OWNER_CHANGED]: BaseEvent<TaskEvent.CONTACT_OWNER_CHANGED> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.ASSIGN]: BaseEvent<TaskEvent.ASSIGN> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.HOLD_INITIATED]: BaseEvent<TaskEvent.HOLD_INITIATED> & {
+        mediaResourceId: string;
+    };
+    [TaskEvent.HOLD_SUCCESS]: BaseEvent<TaskEvent.HOLD_SUCCESS> & {
+        mediaResourceId: string;
+        taskData?: TaskData;
+    };
+    [TaskEvent.HOLD_FAILED]: BaseEvent<TaskEvent.HOLD_FAILED> & {
+        reason?: string;
+        mediaResourceId: string;
+    };
+    [TaskEvent.UNHOLD_INITIATED]: BaseEvent<TaskEvent.UNHOLD_INITIATED> & {
+        mediaResourceId: string;
+    };
+    [TaskEvent.UNHOLD_SUCCESS]: BaseEvent<TaskEvent.UNHOLD_SUCCESS> & {
+        mediaResourceId: string;
+        taskData?: TaskData;
+    };
+    [TaskEvent.UNHOLD_FAILED]: BaseEvent<TaskEvent.UNHOLD_FAILED> & {
+        reason?: string;
+        mediaResourceId: string;
+    };
+    [TaskEvent.CONSULT]: BaseEvent<TaskEvent.CONSULT> & {
+        destination: string;
+        destAgentId?: string;
+        destinationType: DestinationType;
+    };
+    [TaskEvent.CONSULT_SUCCESS]: BaseEvent<TaskEvent.CONSULT_SUCCESS> & {
+        taskData?: TaskData;
+    };
+    [TaskEvent.CONSULT_CREATED]: BaseEvent<TaskEvent.CONSULT_CREATED> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.CONSULTING_ACTIVE]: BaseEvent<TaskEvent.CONSULTING_ACTIVE> & {
+        consultDestinationAgentJoined: boolean;
+        taskData?: TaskData;
+    };
+    [TaskEvent.CONSULT_END]: BaseEvent<TaskEvent.CONSULT_END> & {
+        taskData?: TaskData;
+    };
+    [TaskEvent.CONSULT_FAILED]: BaseEvent<TaskEvent.CONSULT_FAILED> & {
+        reason?: string;
+        taskData?: TaskData;
+    };
+    [TaskEvent.MERGE_TO_CONFERENCE]: BaseEvent<TaskEvent.MERGE_TO_CONFERENCE>;
+    [TaskEvent.CONFERENCE_START]: BaseEvent<TaskEvent.CONFERENCE_START> & {
+        participants?: ConferenceParticipant[];
+        taskData?: TaskData;
+    };
+    [TaskEvent.CONFERENCE_FAILED]: BaseEvent<TaskEvent.CONFERENCE_FAILED> & {
+        reason?: string;
+        taskData?: TaskData;
+    };
+    [TaskEvent.CONFERENCE_END]: BaseEvent<TaskEvent.CONFERENCE_END> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.TRANSFER_CONFERENCE]: BaseEvent<TaskEvent.TRANSFER_CONFERENCE> & {
+        agentId?: string;
+    };
+    [TaskEvent.PARTICIPANT_LEAVE]: BaseEvent<TaskEvent.PARTICIPANT_LEAVE> & {
+        participantId?: string;
+        taskData: TaskData;
+    };
+    [TaskEvent.EXIT_CONFERENCE]: BaseEvent<TaskEvent.EXIT_CONFERENCE> & {
+        agentId?: string;
+    };
+    [TaskEvent.EXIT_CONFERENCE_SUCCESS]: BaseEvent<TaskEvent.EXIT_CONFERENCE_SUCCESS> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.EXIT_CONFERENCE_FAILED]: BaseEvent<TaskEvent.EXIT_CONFERENCE_FAILED> & {
+        reason?: string;
+    };
+    [TaskEvent.TRANSFER_CONFERENCE_SUCCESS]: BaseEvent<TaskEvent.TRANSFER_CONFERENCE_SUCCESS> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.TRANSFER_CONFERENCE_FAILED]: BaseEvent<TaskEvent.TRANSFER_CONFERENCE_FAILED> & {
+        reason?: string;
+    };
+    [TaskEvent.RECORDING_STARTED]: BaseEvent<TaskEvent.RECORDING_STARTED> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.PAUSE_RECORDING]: BaseEvent<TaskEvent.PAUSE_RECORDING> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.RESUME_RECORDING]: BaseEvent<TaskEvent.RESUME_RECORDING> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.TRANSFER_SUCCESS]: BaseEvent<TaskEvent.TRANSFER_SUCCESS> & {
+        taskData?: TaskData;
+    };
+    [TaskEvent.TRANSFER_FAILED]: BaseEvent<TaskEvent.TRANSFER_FAILED> & {
+        reason?: string;
+        taskData?: TaskData;
+    };
+    [TaskEvent.WRAPUP_COMPLETE]: BaseEvent<TaskEvent.WRAPUP_COMPLETE> & {
+        taskData?: TaskData;
+    };
+    [TaskEvent.TASK_WRAPUP]: BaseEvent<TaskEvent.TASK_WRAPUP> & {
+        taskData?: TaskData;
+    };
+    [TaskEvent.RONA]: BaseEvent<TaskEvent.RONA> & {
+        taskData?: TaskData;
+        reason?: string;
+    };
+    [TaskEvent.CONTACT_ENDED]: BaseEvent<TaskEvent.CONTACT_ENDED> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.ASSIGN_FAILED]: BaseEvent<TaskEvent.ASSIGN_FAILED> & {
+        reason?: string;
+    };
+    [TaskEvent.INVITE_FAILED]: BaseEvent<TaskEvent.INVITE_FAILED> & {
+        reason?: string;
+    };
+    [TaskEvent.OUTBOUND_FAILED]: BaseEvent<TaskEvent.OUTBOUND_FAILED> & {
+        reason?: string;
+        taskData?: TaskData;
+    };
+    [TaskEvent.SWITCH_TO_MAIN_CALL]: BaseEvent<TaskEvent.SWITCH_TO_MAIN_CALL>;
+    [TaskEvent.SWITCH_TO_CONSULT]: BaseEvent<TaskEvent.SWITCH_TO_CONSULT>;
+    [TaskEvent.ACCEPT]: BaseEvent<TaskEvent.ACCEPT>;
+    [TaskEvent.DECLINE]: BaseEvent<TaskEvent.DECLINE>;
+    [TaskEvent.END]: BaseEvent<TaskEvent.END> & {
+        taskData?: TaskData;
+    };
+    [TaskEvent.CTQ_CANCEL]: BaseEvent<TaskEvent.CTQ_CANCEL> & {
+        taskData: TaskData;
+    };
+    [TaskEvent.CTQ_CANCEL_FAILED]: BaseEvent<TaskEvent.CTQ_CANCEL_FAILED> & {
+        taskData: TaskData;
+    };
+}
+/**
+ * Union of all possible event payloads
+ */
+export type TaskEventPayload = TaskEventPayloadMap[TaskEvent];
+/**
+ * Type guard to check event type
+ */
+export declare function isEventOfType<T extends TaskEvent>(event: TaskEventPayload | undefined, type: T): event is TaskEventPayloadMap[T];
+/**
+ * Recording control state for UI controls computer
+ */
+export interface RecordingControlState {
+    available: boolean;
+    inProgress: boolean;
+}
+/**
+ * State machine configuration type
+ */
+export interface TaskStateMachineConfig {
+    id: string;
+    initial: TaskState;
+    context: TaskContext;
+    states: Record<string, AnyStateNodeConfig>;
+}
+export type TaskActionsMap = ActionFunctionMap<TaskContext, TaskEventPayload, never, {
+    type: string;
+    params: undefined;
+}, never, never, EventObject>;
+export type TaskActionArgs = ActionArgs<TaskContext, TaskEventPayload, TaskEventPayload>;
+export {};

package/dist/types/services/task/state-machine/uiControlsComputer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * UI Controls Computer - Centralized logic for computing UI control states
+ */
+import { TaskData, TaskUIControls } from '../types';
+import { TaskContext } from './types';
+import { TaskState } from './constants';
+export declare function getDefaultUIControls(): TaskUIControls;
+export declare function computeUIControls(currentState: TaskState, context: TaskContext, fallbackTaskData?: TaskData): TaskUIControls;
+export declare function haveUIControlsChanged(previous: TaskUIControls | undefined, next: TaskUIControls): boolean;

package/dist/types/services/task/taskDataNormalizer.d.ts

@@ -0,0 +1,10 @@
+import { TaskData } from './types';
+/**
+ * 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 declare function normalizeTaskData(data: TaskData): TaskData;