@webex/contact-center 3.12.0 → 3.13.0-next.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (297) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1613 -0
  3. package/AGENTS.md +969 -0
  4. package/dist/cc.js +1102 -47
  5. package/dist/cc.js.map +1 -1
  6. package/dist/config.js +13 -0
  7. package/dist/config.js.map +1 -1
  8. package/dist/constants.js +46 -3
  9. package/dist/constants.js.map +1 -1
  10. package/dist/index.js +86 -17
  11. package/dist/index.js.map +1 -1
  12. package/dist/metrics/MetricsManager.js +16 -0
  13. package/dist/metrics/MetricsManager.js.map +1 -1
  14. package/dist/metrics/behavioral-events.js +211 -0
  15. package/dist/metrics/behavioral-events.js.map +1 -1
  16. package/dist/metrics/constants.js +58 -4
  17. package/dist/metrics/constants.js.map +1 -1
  18. package/dist/services/AddressBook.js +18 -15
  19. package/dist/services/AddressBook.js.map +1 -1
  20. package/dist/services/AnswerCallOnWebexService.js +202 -0
  21. package/dist/services/AnswerCallOnWebexService.js.map +1 -0
  22. package/dist/services/ApiAiAssistant.js +369 -14
  23. package/dist/services/ApiAiAssistant.js.map +1 -1
  24. package/dist/services/EntryPoint.js +46 -68
  25. package/dist/services/EntryPoint.js.map +1 -1
  26. package/dist/services/Queue.js +27 -22
  27. package/dist/services/Queue.js.map +1 -1
  28. package/dist/services/UserPreference.js +427 -0
  29. package/dist/services/UserPreference.js.map +1 -0
  30. package/dist/services/WebCallingService.js +287 -37
  31. package/dist/services/WebCallingService.js.map +1 -1
  32. package/dist/services/WebexCrossClientService.js +225 -0
  33. package/dist/services/WebexCrossClientService.js.map +1 -0
  34. package/dist/services/WxAppTelephonyMercurySync.js +111 -0
  35. package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
  36. package/dist/services/config/Util.js +48 -48
  37. package/dist/services/config/Util.js.map +1 -1
  38. package/dist/services/config/constants.js +57 -79
  39. package/dist/services/config/constants.js.map +1 -1
  40. package/dist/services/config/index.js +100 -226
  41. package/dist/services/config/index.js.map +1 -1
  42. package/dist/services/config/types.js +100 -40
  43. package/dist/services/config/types.js.map +1 -1
  44. package/dist/services/constants.js +19 -1
  45. package/dist/services/constants.js.map +1 -1
  46. package/dist/services/core/Err.js.map +1 -1
  47. package/dist/services/core/Utils.js +131 -32
  48. package/dist/services/core/Utils.js.map +1 -1
  49. package/dist/services/core/WebexRequest.js +6 -2
  50. package/dist/services/core/WebexRequest.js.map +1 -1
  51. package/dist/services/core/aqm-reqs.js +17 -11
  52. package/dist/services/core/aqm-reqs.js.map +1 -1
  53. package/dist/services/core/constants.js +9 -1
  54. package/dist/services/core/constants.js.map +1 -1
  55. package/dist/services/core/types.js.map +1 -1
  56. package/dist/services/core/websocket/WebSocketManager.js +26 -6
  57. package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
  58. package/dist/services/core/websocket/connection-service.js +3 -1
  59. package/dist/services/core/websocket/connection-service.js.map +1 -1
  60. package/dist/services/core/websocket/types.js.map +1 -1
  61. package/dist/services/index.js +6 -0
  62. package/dist/services/index.js.map +1 -1
  63. package/dist/services/task/Task.js +955 -0
  64. package/dist/services/task/Task.js.map +1 -0
  65. package/dist/services/task/TaskFactory.js +50 -0
  66. package/dist/services/task/TaskFactory.js.map +1 -0
  67. package/dist/services/task/TaskManager.js +1275 -504
  68. package/dist/services/task/TaskManager.js.map +1 -1
  69. package/dist/services/task/TaskUtils.js +221 -27
  70. package/dist/services/task/TaskUtils.js.map +1 -1
  71. package/dist/services/task/WebexCallingUtils.js +70 -0
  72. package/dist/services/task/WebexCallingUtils.js.map +1 -0
  73. package/dist/services/task/constants.js +22 -2
  74. package/dist/services/task/constants.js.map +1 -1
  75. package/dist/services/task/contact.js +29 -0
  76. package/dist/services/task/contact.js.map +1 -1
  77. package/dist/services/task/dialer.js +78 -0
  78. package/dist/services/task/dialer.js.map +1 -1
  79. package/dist/services/task/digital/Digital.js +78 -0
  80. package/dist/services/task/digital/Digital.js.map +1 -0
  81. package/dist/services/task/state-machine/TaskStateMachine.js +982 -0
  82. package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -0
  83. package/dist/services/task/state-machine/actions.js +572 -0
  84. package/dist/services/task/state-machine/actions.js.map +1 -0
  85. package/dist/services/task/state-machine/constants.js +161 -0
  86. package/dist/services/task/state-machine/constants.js.map +1 -0
  87. package/dist/services/task/state-machine/guards.js +379 -0
  88. package/dist/services/task/state-machine/guards.js.map +1 -0
  89. package/dist/services/task/state-machine/index.js +53 -0
  90. package/dist/services/task/state-machine/index.js.map +1 -0
  91. package/dist/services/task/state-machine/types.js +54 -0
  92. package/dist/services/task/state-machine/types.js.map +1 -0
  93. package/dist/services/task/state-machine/uiControlsComputer.js +703 -0
  94. package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -0
  95. package/dist/services/task/taskDataNormalizer.js +99 -0
  96. package/dist/services/task/taskDataNormalizer.js.map +1 -0
  97. package/dist/services/task/types.js +259 -5
  98. package/dist/services/task/types.js.map +1 -1
  99. package/dist/services/task/voice/Voice.js +1504 -0
  100. package/dist/services/task/voice/Voice.js.map +1 -0
  101. package/dist/services/task/voice/WebRTC.js +152 -0
  102. package/dist/services/task/voice/WebRTC.js.map +1 -0
  103. package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
  104. package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
  105. package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
  106. package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
  107. package/dist/services/wxAppDiagnosticLogging.js +159 -0
  108. package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
  109. package/dist/services/wxAppTelephonyUtils.js +19 -0
  110. package/dist/services/wxAppTelephonyUtils.js.map +1 -0
  111. package/dist/types/cc.d.ts +222 -10
  112. package/dist/types/config.d.ts +13 -0
  113. package/dist/types/constants.d.ts +40 -1
  114. package/dist/types/index.d.ts +58 -22
  115. package/dist/types/metrics/MetricsManager.d.ts +6 -0
  116. package/dist/types/metrics/constants.d.ts +52 -1
  117. package/dist/types/services/AddressBook.d.ts +2 -1
  118. package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
  119. package/dist/types/services/ApiAiAssistant.d.ts +67 -5
  120. package/dist/types/services/EntryPoint.d.ts +7 -5
  121. package/dist/types/services/Queue.d.ts +5 -3
  122. package/dist/types/services/UserPreference.d.ts +118 -0
  123. package/dist/types/services/WebexCrossClientService.d.ts +32 -0
  124. package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
  125. package/dist/types/services/config/Util.d.ts +4 -8
  126. package/dist/types/services/config/constants.d.ts +49 -76
  127. package/dist/types/services/config/index.d.ts +16 -64
  128. package/dist/types/services/config/types.d.ts +252 -114
  129. package/dist/types/services/constants.d.ts +16 -0
  130. package/dist/types/services/core/Err.d.ts +6 -0
  131. package/dist/types/services/core/Utils.d.ts +43 -13
  132. package/dist/types/services/core/WebexRequest.d.ts +1 -0
  133. package/dist/types/services/core/constants.d.ts +7 -0
  134. package/dist/types/services/core/types.d.ts +2 -0
  135. package/dist/types/services/core/websocket/WebSocketManager.d.ts +2 -0
  136. package/dist/types/services/core/websocket/types.d.ts +1 -1
  137. package/dist/types/services/index.d.ts +2 -0
  138. package/dist/types/services/task/Task.d.ts +186 -0
  139. package/dist/types/services/task/TaskFactory.d.ts +14 -0
  140. package/dist/types/services/task/TaskUtils.d.ts +54 -2
  141. package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
  142. package/dist/types/services/task/constants.d.ts +20 -0
  143. package/dist/types/services/task/contact.d.ts +4 -0
  144. package/dist/types/services/task/dialer.d.ts +30 -0
  145. package/dist/types/services/task/digital/Digital.d.ts +23 -0
  146. package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +1442 -0
  147. package/dist/types/services/task/state-machine/actions.d.ts +10 -0
  148. package/dist/types/services/task/state-machine/constants.d.ts +107 -0
  149. package/dist/types/services/task/state-machine/guards.d.ts +103 -0
  150. package/dist/types/services/task/state-machine/index.d.ts +13 -0
  151. package/dist/types/services/task/state-machine/types.d.ts +277 -0
  152. package/dist/types/services/task/state-machine/uiControlsComputer.d.ts +9 -0
  153. package/dist/types/services/task/taskDataNormalizer.d.ts +10 -0
  154. package/dist/types/services/task/types.d.ts +790 -66
  155. package/dist/types/services/task/voice/Voice.d.ts +241 -0
  156. package/dist/types/services/task/voice/WebRTC.d.ts +54 -0
  157. package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
  158. package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
  159. package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
  160. package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
  161. package/dist/types/types.d.ts +258 -11
  162. package/dist/types/utils/PageCache.d.ts +20 -3
  163. package/dist/types/webex.d.ts +1 -0
  164. package/dist/types.js +204 -6
  165. package/dist/types.js.map +1 -1
  166. package/dist/utils/PageCache.js +19 -5
  167. package/dist/utils/PageCache.js.map +1 -1
  168. package/dist/webex.js +22 -2
  169. package/dist/webex.js.map +1 -1
  170. package/docs/adr/0001-spec-source-policy.md +97 -0
  171. package/docs/adr/0002-consult-transfer-list-policy.md +345 -0
  172. package/docs/adr/0003-repo-standards-migration.md +104 -0
  173. package/docs/adr/index.md +35 -0
  174. package/docs/architecture.md +460 -0
  175. package/docs/getting-started.md +142 -0
  176. package/docs/index.md +53 -0
  177. package/docs/specs/README.md +98 -0
  178. package/package.json +17 -12
  179. package/schemas/repo-context.schema.json +796 -0
  180. package/src/cc.ts +1439 -105
  181. package/src/config.ts +13 -0
  182. package/src/constants.ts +53 -1
  183. package/src/docs/README.md +727 -0
  184. package/src/index.ts +72 -16
  185. package/src/metrics/MetricsManager.ts +16 -0
  186. package/src/metrics/behavioral-events.ts +218 -0
  187. package/src/metrics/constants.ts +63 -4
  188. package/src/metrics/docs/README.md +710 -0
  189. package/src/services/AddressBook.ts +17 -6
  190. package/src/services/AnswerCallOnWebexService.ts +239 -0
  191. package/src/services/ApiAiAssistant.ts +494 -15
  192. package/src/services/EntryPoint.ts +59 -60
  193. package/src/services/Queue.ts +29 -12
  194. package/src/services/UserPreference.ts +509 -0
  195. package/src/services/WebCallingService.ts +362 -40
  196. package/src/services/WebexCrossClientService.ts +298 -0
  197. package/src/services/WxAppTelephonyMercurySync.ts +142 -0
  198. package/src/services/agent/docs/README.md +673 -0
  199. package/src/services/config/Util.ts +54 -84
  200. package/src/services/config/constants.ts +64 -86
  201. package/src/services/config/docs/README.md +530 -0
  202. package/src/services/config/index.ts +116 -277
  203. package/src/services/config/types.ts +238 -125
  204. package/src/services/constants.ts +18 -0
  205. package/src/services/core/Err.ts +3 -0
  206. package/src/services/core/Utils.ts +151 -37
  207. package/src/services/core/WebexRequest.ts +3 -1
  208. package/src/services/core/aqm-reqs.ts +18 -12
  209. package/src/services/core/constants.ts +8 -0
  210. package/src/services/core/docs/README.md +993 -0
  211. package/src/services/core/types.ts +33 -1
  212. package/src/services/core/websocket/WebSocketManager.ts +37 -8
  213. package/src/services/core/websocket/connection-service.ts +5 -1
  214. package/src/services/core/websocket/types.ts +1 -1
  215. package/src/services/docs/README.md +765 -0
  216. package/src/services/index.ts +4 -0
  217. package/src/services/task/Task.ts +1211 -0
  218. package/src/services/task/TaskFactory.ts +82 -0
  219. package/src/services/task/TaskManager.ts +1551 -584
  220. package/src/services/task/TaskUtils.ts +316 -25
  221. package/src/services/task/WebexCallingUtils.ts +136 -0
  222. package/src/services/task/constants.ts +21 -0
  223. package/src/services/task/contact.ts +30 -0
  224. package/src/services/task/dialer.ts +80 -0
  225. package/src/services/task/digital/Digital.ts +102 -0
  226. package/src/services/task/docs/README.md +1569 -0
  227. package/src/services/task/state-machine/TaskStateMachine.ts +1320 -0
  228. package/src/services/task/state-machine/actions.ts +741 -0
  229. package/src/services/task/state-machine/constants.ts +172 -0
  230. package/src/services/task/state-machine/docs/README.md +1388 -0
  231. package/src/services/task/state-machine/guards.ts +442 -0
  232. package/src/services/task/state-machine/index.ts +28 -0
  233. package/src/services/task/state-machine/types.ts +258 -0
  234. package/src/services/task/state-machine/uiControlsComputer.ts +1135 -0
  235. package/src/services/task/taskDataNormalizer.ts +137 -0
  236. package/src/services/task/types.ts +974 -70
  237. package/src/services/task/voice/Voice.ts +1878 -0
  238. package/src/services/task/voice/WebRTC.ts +194 -0
  239. package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
  240. package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
  241. package/src/services/wxAppDiagnosticLogging.ts +286 -0
  242. package/src/services/wxAppTelephonyUtils.ts +14 -0
  243. package/src/types.ts +323 -13
  244. package/src/utils/AGENTS.md +291 -0
  245. package/src/utils/PageCache.ts +38 -5
  246. package/src/utils/docs/README.md +413 -0
  247. package/src/webex.js +10 -0
  248. package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
  249. package/test/unit/spec/cc.ts +4046 -181
  250. package/test/unit/spec/index.ts +891 -0
  251. package/test/unit/spec/logger-proxy.ts +70 -0
  252. package/test/unit/spec/metrics/MetricsManager.ts +25 -0
  253. package/test/unit/spec/metrics/behavioral-events.ts +60 -0
  254. package/test/unit/spec/services/AddressBook.ts +37 -6
  255. package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
  256. package/test/unit/spec/services/ApiAiAssistant.ts +442 -23
  257. package/test/unit/spec/services/EntryPoint.ts +87 -40
  258. package/test/unit/spec/services/Queue.ts +123 -12
  259. package/test/unit/spec/services/UserPreference.ts +401 -0
  260. package/test/unit/spec/services/WebCallingService.ts +484 -49
  261. package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
  262. package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
  263. package/test/unit/spec/services/config/Util.ts +501 -0
  264. package/test/unit/spec/services/config/index.ts +318 -548
  265. package/test/unit/spec/services/core/Utils.ts +447 -8
  266. package/test/unit/spec/services/core/WebexRequest.ts +8 -7
  267. package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
  268. package/test/unit/spec/services/core/websocket/WebSocketManager.ts +132 -56
  269. package/test/unit/spec/services/core/websocket/connection-service.ts +3 -1
  270. package/test/unit/spec/services/task/AutoWrapup.ts +63 -0
  271. package/test/unit/spec/services/task/Task.ts +2723 -0
  272. package/test/unit/spec/services/task/TaskFactory.ts +116 -0
  273. package/test/unit/spec/services/task/TaskManager.ts +4800 -1586
  274. package/test/unit/spec/services/task/TaskUtils.ts +307 -0
  275. package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
  276. package/test/unit/spec/services/task/contact.ts +33 -0
  277. package/test/unit/spec/services/task/dialer.ts +190 -0
  278. package/test/unit/spec/services/task/digital/Digital.ts +105 -0
  279. package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +4060 -0
  280. package/test/unit/spec/services/task/state-machine/guards.ts +839 -0
  281. package/test/unit/spec/services/task/state-machine/types.ts +18 -0
  282. package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +3101 -0
  283. package/test/unit/spec/services/task/taskTestUtils.ts +87 -0
  284. package/test/unit/spec/services/task/voice/Voice.ts +2355 -0
  285. package/test/unit/spec/services/task/voice/WebRTC.ts +235 -0
  286. package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
  287. package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
  288. package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
  289. package/test/unit/spec/wellnessSampleUtils.ts +288 -0
  290. package/typedoc.md +1 -1
  291. package/umd/contact-center.min.js +2 -2
  292. package/umd/contact-center.min.js.map +1 -1
  293. package/dist/services/task/index.js +0 -1525
  294. package/dist/services/task/index.js.map +0 -1
  295. package/dist/types/services/task/index.d.ts +0 -650
  296. package/src/services/task/index.ts +0 -1801
  297. package/test/unit/spec/services/task/index.ts +0 -2184
@@ -0,0 +1,442 @@
1
+ /**
2
+ * Task State Machine Guards
3
+ *
4
+ * Guard functions that determine if a state transition is allowed.
5
+ * These functions validate the current context before allowing transitions.
6
+ *
7
+ * All guards are consolidated here for:
8
+ * - Single source of truth
9
+ * - Easy testing
10
+ * - Reusability across state machine transitions
11
+ *
12
+ * Guards are organized by category:
13
+ * 1. Helper Functions - Extract data from events/context
14
+ * 2. Hydrate Guards - For state restoration on page refresh
15
+ * 3. Conference Guards - Conference state checks
16
+ * 4. Customer Guards - Customer presence checks
17
+ * 5. Consult Guards - Consult flow checks
18
+ * 6. Wrapup Guards - End-of-call flow checks
19
+ * 7. Server State Guards - Check backend-reported state
20
+ * 8. Recording Guards - Recording state checks
21
+ */
22
+
23
+ import {TaskContext, TaskEventPayload} from './types';
24
+ import {TaskData} from '../types';
25
+ import {
26
+ getIsCustomerInCall,
27
+ getConferenceParticipantsCount,
28
+ getIsConferenceInProgress,
29
+ isCampaignPreviewTask,
30
+ isEpDnConsultPendingConferenceMerge,
31
+ } from '../TaskUtils';
32
+ import {TaskEvent, INTERACTION_STATE, CONSULT_STATE, MEDIA_TYPE_CONSULT} from './constants';
33
+
34
+ export const getTaskDataFromEvent = (event?: TaskEventPayload): TaskData | undefined =>
35
+ event && typeof event === 'object' && 'taskData' in event
36
+ ? (event as {taskData?: TaskData}).taskData
37
+ : undefined;
38
+
39
+ export const getSelfAgentId = (context: TaskContext, taskData?: TaskData): string | undefined =>
40
+ context.uiControlConfig?.agentId ?? context.taskData?.agentId ?? taskData?.agentId;
41
+
42
+ export const isSelfConsultingAgent = (context: TaskContext, taskData?: TaskData): boolean => {
43
+ const selfAgentId = getSelfAgentId(context, taskData);
44
+ if (!selfAgentId) return false;
45
+
46
+ return taskData?.consultingAgentId === selfAgentId;
47
+ };
48
+
49
+ /**
50
+ * Detects an active consult during post_call state (customer left but agents still consulting).
51
+ * Shared by hydration guard (isInteractionConsulting) and action (deriveTaskDataUpdates).
52
+ */
53
+ export const hasActiveConsultInPostCall = (
54
+ taskData: TaskData | undefined,
55
+ selfAgentId?: string
56
+ ): boolean => {
57
+ if (taskData?.interaction?.state !== INTERACTION_STATE.POST_CALL || !selfAgentId) return false;
58
+
59
+ const selfParticipant = taskData.interaction?.participants?.[selfAgentId];
60
+ const hasConsultMedia = Object.values(taskData.interaction?.media ?? {}).some(
61
+ (media) => (media as {mType?: string})?.mType === MEDIA_TYPE_CONSULT
62
+ );
63
+
64
+ return selfParticipant?.consultState === CONSULT_STATE.CONSULTING && hasConsultMedia;
65
+ };
66
+
67
+ /**
68
+ * Determines if this agent should enter WRAPPING_UP state.
69
+ * Priority: agentsPendingWrapUp > wrapUpRequired / participant.isWrapUp > ownership > !isConsulted
70
+ */
71
+ export const shouldWrapUpForThisAgent = (context: TaskContext, taskData: TaskData): boolean => {
72
+ const selfAgentId = getSelfAgentId(context, taskData);
73
+ if (!selfAgentId) return false;
74
+
75
+ const pending = taskData?.agentsPendingWrapUp;
76
+ if (Array.isArray(pending) && pending.length > 0) {
77
+ return pending.includes(selfAgentId);
78
+ }
79
+
80
+ const participantWrapUp = taskData?.interaction?.participants?.[selfAgentId]?.isWrapUp === true;
81
+ const wrapUpRequired = taskData?.wrapUpRequired === true;
82
+ if (wrapUpRequired || participantWrapUp) {
83
+ return true;
84
+ }
85
+
86
+ const owner = taskData?.interaction?.owner;
87
+ if (owner && owner === selfAgentId) {
88
+ return true;
89
+ }
90
+
91
+ if (taskData?.isConsulted === false) {
92
+ return true;
93
+ }
94
+
95
+ return false;
96
+ };
97
+
98
+ export interface GuardParams {
99
+ context: TaskContext;
100
+ event?: TaskEventPayload;
101
+ }
102
+
103
+ export type GuardFunction = (params: GuardParams) => boolean;
104
+
105
+ export const guards = {
106
+ // Hydrate Guards
107
+ isInteractionTerminated: ({context, event}: GuardParams): boolean => {
108
+ const taskData = getTaskDataFromEvent(event);
109
+
110
+ if (taskData?.interaction?.isTerminated === true) return true;
111
+
112
+ const selfAgentId = getSelfAgentId(context, taskData);
113
+ if (selfAgentId && taskData?.interaction?.participants?.[selfAgentId]?.isWrapUp === true) {
114
+ return true;
115
+ }
116
+
117
+ return false;
118
+ },
119
+
120
+ isInteractionConsulting: ({event, context}: GuardParams): boolean => {
121
+ const taskData = getTaskDataFromEvent(event);
122
+
123
+ if (taskData?.interaction?.state === INTERACTION_STATE.CONSULTING) return true;
124
+
125
+ // Hydrate can report interaction as conference/hold while this agent is actively consulting.
126
+ // Detect consult by participant consultState + consult media, independent of top-level state.
127
+ const selfAgentId = getSelfAgentId(context, taskData);
128
+ const selfParticipant = selfAgentId ? taskData?.interaction?.participants?.[selfAgentId] : null;
129
+ const hasConsultMedia = Object.values(taskData?.interaction?.media ?? {}).some(
130
+ (media: any) => media?.mType === MEDIA_TYPE_CONSULT
131
+ );
132
+ const selfActiveConsult = selfParticipant?.consultState === CONSULT_STATE.CONSULTING;
133
+ const selfPendingConsultInitiated =
134
+ selfParticipant?.consultState === 'consultInitiated' && taskData?.isConsulted === false;
135
+ if ((selfActiveConsult || selfPendingConsultInitiated) && hasConsultMedia) {
136
+ return true;
137
+ }
138
+
139
+ // EP_DN consulted agent: backend reports state as 'connected' but CPD indicates consult
140
+ const cpd = taskData?.interaction?.callProcessingDetails;
141
+ if (
142
+ cpd?.relationshipType === 'consult' &&
143
+ taskData?.interaction?.state === INTERACTION_STATE.CONNECTED
144
+ ) {
145
+ return true;
146
+ }
147
+
148
+ // Customer left during consult: interaction state is "post_call" but consult
149
+ // between agents is still active. Detect via agent's consultState + consult media.
150
+ if (hasActiveConsultInPostCall(taskData, getSelfAgentId(context, taskData))) {
151
+ return true;
152
+ }
153
+
154
+ // Customer left during consult: interaction state is "post_call" but consult
155
+ // between agents is still active. Detect via agent's consultState + consult media.
156
+ if (taskData?.interaction?.state === INTERACTION_STATE.POST_CALL) {
157
+ const postCallSelfAgentId = getSelfAgentId(context, taskData);
158
+ const postCallSelfParticipant = postCallSelfAgentId
159
+ ? taskData?.interaction?.participants?.[postCallSelfAgentId]
160
+ : null;
161
+ const hasPostCallConsultMedia = Object.values(taskData?.interaction?.media ?? {}).some(
162
+ (media: any) => media?.mType === MEDIA_TYPE_CONSULT
163
+ );
164
+ if (
165
+ postCallSelfParticipant?.consultState === CONSULT_STATE.CONSULTING &&
166
+ hasPostCallConsultMedia
167
+ ) {
168
+ return true;
169
+ }
170
+ }
171
+
172
+ return false;
173
+ },
174
+
175
+ isEpDnPendingConferenceMergeHydrate: ({event, context}: GuardParams): boolean => {
176
+ const taskData = getTaskDataFromEvent(event);
177
+
178
+ return isEpDnConsultPendingConferenceMerge(taskData, getSelfAgentId(context, taskData));
179
+ },
180
+
181
+ isInteractionHeld: ({event}: GuardParams): boolean => {
182
+ const taskData = getTaskDataFromEvent(event);
183
+
184
+ if (taskData?.interaction?.state === 'hold') return true;
185
+
186
+ const mainMediaId = taskData?.interaction?.mainInteractionId || taskData?.interactionId;
187
+ if (mainMediaId && taskData?.interaction?.media?.[mainMediaId]?.isHold === true) {
188
+ return true;
189
+ }
190
+
191
+ return false;
192
+ },
193
+
194
+ isInteractionConnected: ({event}: GuardParams): boolean => {
195
+ const taskData = getTaskDataFromEvent(event);
196
+
197
+ return taskData?.interaction?.state === INTERACTION_STATE.CONNECTED;
198
+ },
199
+
200
+ isConferencingByParticipants: ({event}: GuardParams): boolean => {
201
+ const taskData = getTaskDataFromEvent(event);
202
+ if (!taskData) return false;
203
+ const mainCallId = taskData.interaction?.mainInteractionId || taskData.interactionId;
204
+ const media = taskData.interaction?.media?.[mainCallId];
205
+ const participants = taskData.interaction?.participants;
206
+ if (!media?.participants || !participants) return false;
207
+ let agentCount = 0;
208
+ for (const pId of media.participants) {
209
+ const p = participants[pId];
210
+ if (p && p.pType !== 'Customer' && p.pType !== 'Supervisor' && !p.hasLeft) {
211
+ agentCount += 1;
212
+ }
213
+ }
214
+
215
+ return agentCount >= 2;
216
+ },
217
+
218
+ // Conference Guards
219
+ conferenceInProgressFromEvent: ({event}: GuardParams): boolean => {
220
+ const taskData = getTaskDataFromEvent(event);
221
+ if (!taskData?.interaction) return false;
222
+
223
+ return getIsConferenceInProgress(taskData);
224
+ },
225
+
226
+ /**
227
+ * Conference hold signal for conference-downgraded consult-end transitions.
228
+ * Backend can report this as boolean or string.
229
+ */
230
+ isConferenceHoldParticipantFromEvent: ({context, event}: GuardParams): boolean => {
231
+ const taskData = getTaskDataFromEvent(event) ?? context.taskData;
232
+ const callProcessingDetails = taskData?.interaction?.callProcessingDetails as
233
+ | {conferenceHoldParticipant?: boolean | string}
234
+ | undefined;
235
+ const conferenceHoldParticipant = callProcessingDetails?.conferenceHoldParticipant;
236
+
237
+ return conferenceHoldParticipant === true || conferenceHoldParticipant === 'true';
238
+ },
239
+
240
+ /**
241
+ * Conference downgrade check specifically for transitioning back to CONNECTED.
242
+ *
243
+ * Returns true only when:
244
+ * - conference has downgraded (fewer than 2 active agent participants in main call)
245
+ * - customer is still in the call
246
+ * - current agent is still in the main call
247
+ */
248
+ shouldDowngradeConferenceToConnected: ({context, event}: GuardParams): boolean => {
249
+ const eventTaskData = getTaskDataFromEvent(event);
250
+ const taskData = eventTaskData ?? context.taskData;
251
+ if (!taskData?.interaction) return false;
252
+
253
+ const selfAgentId = getSelfAgentId(context, taskData);
254
+ if (!selfAgentId) return false;
255
+
256
+ const mainCallId = taskData.interaction.mainInteractionId || taskData.interactionId;
257
+ if (!mainCallId) return false;
258
+
259
+ // Don't downgrade while backend still reports conference.
260
+ if (taskData.interaction.state === INTERACTION_STATE.CONFERENCE) return false;
261
+
262
+ const agentParticipantsCount = getConferenceParticipantsCount(taskData.interaction, mainCallId);
263
+ if (agentParticipantsCount >= 2) return false;
264
+
265
+ const customerInCall = getIsCustomerInCall(taskData.interaction, mainCallId);
266
+ if (!customerInCall) return false;
267
+
268
+ const selfInMainCall = Boolean(
269
+ taskData.interaction.media?.[mainCallId]?.participants?.includes(selfAgentId)
270
+ );
271
+
272
+ return selfInMainCall;
273
+ },
274
+
275
+ // Consult Guards
276
+ /**
277
+ * Check if this agent initiated the consult (using event data)
278
+ * Handles both consultingAgentId and fallback to context flag
279
+ */
280
+ didInitiateConsult: ({context, event}: GuardParams): boolean => {
281
+ const taskData = getTaskDataFromEvent(event);
282
+ if (taskData?.isConsulted === true) return false;
283
+
284
+ return taskData?.consultingAgentId
285
+ ? isSelfConsultingAgent(context, taskData)
286
+ : context.consultInitiator === true;
287
+ },
288
+
289
+ /**
290
+ * EP-DN / consulted consult legs can arrive as AGENT_CONTACT_ASSIGNED without a preceding
291
+ * AgentConsulting event. When that happens, we should enter CONSULTING (not CONNECTED).
292
+ */
293
+ isConsultingAssignment: ({event}: GuardParams): boolean => {
294
+ const taskData = getTaskDataFromEvent(event);
295
+ if (!taskData) return false;
296
+
297
+ const relationshipType = taskData.interaction?.callProcessingDetails?.relationshipType;
298
+
299
+ return (
300
+ taskData.isConsulted === true ||
301
+ relationshipType === 'consult' ||
302
+ taskData.interaction?.state === INTERACTION_STATE.CONSULTING
303
+ );
304
+ },
305
+
306
+ // Wrapup Guards
307
+ isCampaignPreviewContactEnded: ({context, event}: GuardParams): boolean => {
308
+ if (event?.type !== TaskEvent.CONTACT_ENDED) {
309
+ return false;
310
+ }
311
+
312
+ const taskData = getTaskDataFromEvent(event);
313
+ if (!isCampaignPreviewTask(taskData)) {
314
+ return false;
315
+ }
316
+
317
+ const selfAgentId = getSelfAgentId(context, taskData);
318
+ const pending = taskData?.agentsPendingWrapUp;
319
+ const isPendingWrapUp =
320
+ Array.isArray(pending) && !!selfAgentId && pending.includes(selfAgentId);
321
+ const participantIsWrapUp =
322
+ !!selfAgentId && taskData?.interaction?.participants?.[selfAgentId]?.isWrapUp === true;
323
+ const explicitWrapUp =
324
+ taskData?.wrapUpRequired === true ||
325
+ participantIsWrapUp ||
326
+ isPendingWrapUp ||
327
+ taskData?.interaction?.state === 'wrapUp';
328
+
329
+ return !explicitWrapUp;
330
+ },
331
+
332
+ shouldWrapUp: ({context, event}: GuardParams): boolean => {
333
+ const taskData = getTaskDataFromEvent(event);
334
+ if (!taskData) return false;
335
+
336
+ if (event?.type === TaskEvent.CONFERENCE_END) {
337
+ const selfAgentId = getSelfAgentId(context, taskData);
338
+ if (!selfAgentId) return false;
339
+
340
+ const pending = taskData?.agentsPendingWrapUp;
341
+ if (Array.isArray(pending) && pending.length > 0) {
342
+ return pending.includes(selfAgentId);
343
+ }
344
+
345
+ const participantWrapUp =
346
+ taskData?.interaction?.participants?.[selfAgentId]?.isWrapUp === true;
347
+ const wrapUpRequired = taskData?.wrapUpRequired === true;
348
+
349
+ return wrapUpRequired || participantWrapUp;
350
+ }
351
+
352
+ return shouldWrapUpForThisAgent(context, taskData);
353
+ },
354
+
355
+ /**
356
+ * Check if wrapUpRequired in payload OR is consult initiator
357
+ */
358
+ shouldWrapUpOrIsInitiator: ({context, event}: GuardParams): boolean => {
359
+ const taskData = getTaskDataFromEvent(event);
360
+
361
+ return Boolean(taskData?.wrapUpRequired || context.consultInitiator);
362
+ },
363
+
364
+ /**
365
+ * True when an updated lifecycle event shows that this agent left the main interaction.
366
+ *
367
+ * Returns true when the event names this agent, or when this agent is absent from the
368
+ * updated participants map. EP-DN payloads remove the leaving participant instead of
369
+ * setting hasLeft. Remaining in the map with hasLeft, or disappearing only from
370
+ * mainCall media, is not treated as departure.
371
+ */
372
+ didCurrentAgentLeaveMainInteraction: ({context, event}: GuardParams): boolean => {
373
+ const taskData = getTaskDataFromEvent(event);
374
+ const selfAgentId = getSelfAgentId(context, taskData);
375
+ if (!selfAgentId) return false;
376
+
377
+ const participantIdFromEvent =
378
+ event && typeof event === 'object' && 'participantId' in event
379
+ ? (event as {participantId?: string}).participantId
380
+ : undefined;
381
+ const participantId = participantIdFromEvent ?? taskData?.participantId;
382
+
383
+ if (Boolean(participantId) && participantId === selfAgentId) {
384
+ return true;
385
+ }
386
+ // EP-DN payloads remove the leaving participant from the map instead of setting hasLeft.
387
+ const participants = taskData?.interaction?.participants;
388
+ if (participants && !(selfAgentId in participants)) {
389
+ return true;
390
+ }
391
+
392
+ return false;
393
+ },
394
+
395
+ /**
396
+ * True when this agent initiated the conference transfer (widgets or desktop).
397
+ * Mirrors determineConsultInitiator: consultingAgentId === self only (not consultState).
398
+ */
399
+ isSelfConferenceTransferInitiator: ({context, event}: GuardParams): boolean => {
400
+ if (context.transferConferenceRequested === true) return true;
401
+
402
+ const taskData = getTaskDataFromEvent(event);
403
+ const selfAgentId = getSelfAgentId(context, taskData);
404
+ if (!selfAgentId || !taskData) return false;
405
+
406
+ return taskData.consultingAgentId === selfAgentId;
407
+ },
408
+
409
+ /**
410
+ * True when another agent performed conference transfer and this agent should
411
+ * only refresh task data (stay in the current state). False when this agent
412
+ * initiated the transfer (desktop or widgets) or has left the interaction.
413
+ */
414
+ isPassiveConferenceTransferObserver: ({context, event}: GuardParams): boolean => {
415
+ if (guards.isSelfConferenceTransferInitiator({context, event})) return false;
416
+
417
+ const taskData = getTaskDataFromEvent(event);
418
+ const selfAgentId = getSelfAgentId(context, taskData);
419
+ if (selfAgentId && taskData?.interaction?.participants) {
420
+ if (!(selfAgentId in taskData.interaction.participants)) return false;
421
+ if (taskData.interaction.participants[selfAgentId]?.hasLeft === true) return false;
422
+ }
423
+
424
+ return true;
425
+ },
426
+
427
+ isCampaignReservationAccept: ({event}: GuardParams): boolean => {
428
+ return event?.type === TaskEvent.TASK_INCOMING && event.isCampaignReservationAccept === true;
429
+ },
430
+
431
+ // Server State Guards
432
+ isPrimaryMediaOnHold: ({event}: GuardParams): boolean => {
433
+ const taskData = getTaskDataFromEvent(event);
434
+ if (!taskData) return false;
435
+ const mediaId = taskData.mediaResourceId;
436
+ if (!mediaId) return false;
437
+
438
+ return taskData.interaction?.media?.[mediaId]?.isHold === true;
439
+ },
440
+ };
441
+
442
+ export type GuardName = keyof typeof guards;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Task State Machine
3
+ *
4
+ * Export all state machine components for easy importing
5
+ */
6
+
7
+ // Main state machine
8
+ export {createTaskStateMachine} from './TaskStateMachine';
9
+ export type {TaskStateMachine} from './TaskStateMachine';
10
+
11
+ // Types & enums
12
+ export {TaskState, TaskEvent} from './constants';
13
+ export {isEventOfType} from './types';
14
+ export type {
15
+ TaskContext,
16
+ TaskEventPayload,
17
+ TaskStateMachineConfig,
18
+ UIControlConfig,
19
+ TaskActionsMap,
20
+ TaskActionArgs,
21
+ } from './types';
22
+
23
+ // Guards
24
+ export {guards} from './guards';
25
+ export type {GuardParams, GuardFunction} from './guards';
26
+
27
+ // Actions
28
+ export {actions, createInitialContext} from './actions';