@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,673 @@
1
+ ---
2
+ type: Module Spec
3
+ title: 'Agent service specification'
4
+ description: Responsibilities, boundaries, design, invariants, and verification for the agent service module, the routingAgent request factory behind station login, logout, state change, buddy agents, and reload.
5
+ tags: [module, specification]
6
+ ---
7
+ <!-- sdd-generated-metadata
8
+ doc_kind: module-spec
9
+ generated_from: module-spec@0.3.0
10
+ generated_by: claude-code
11
+ approved_by: rarajes2@cisco.com
12
+ updated_at: 2026-11-17T03:03:58Z
13
+ validation_status: pass-with-warnings
14
+ -->
15
+
16
+ # Agent service
17
+
18
+ This source-local document at `src/services/agent/docs/README.md` owns the stable specification for
19
+ **the agent service**: the `routingAgent(AqmReqs)` request factory in `src/services/agent/index.ts`,
20
+ the agent request, notification, and event types in `src/services/agent/types.ts` (contract
21
+ `contact-center-agent-events`), and the agent-specific behavior of the ContactCenter methods that wrap
22
+ it (`stationLogin`, `stationLogout`, `setAgentState`, `getBuddyAgents`, and the private silent relogin).
23
+ The ContactCenter class as a whole belongs to the [root module specification](../../../docs/README.md);
24
+ the AqmReqs transport belongs to the [core module specification](../../core/docs/README.md); the
25
+ services composition root that builds this factory is the parent
26
+ [services specification](../../docs/README.md). Ground every claim in package evidence and link to the
27
+ [package architecture](../../../../docs/architecture.md) instead of repeating broader facts. No service
28
+ specification exists because this package is a library.
29
+
30
+ Related context: [documentation index](../../../../docs/index.md) ·
31
+ [package agent instructions](../../../../AGENTS.md)
32
+
33
+ ## Metadata
34
+
35
+ | Field | Value |
36
+ | ----- | ----- |
37
+ | Owner | @webex/web-sdk |
38
+ | Source path | `src/services/agent` |
39
+ | Resource kind | module |
40
+ | Status | Active |
41
+ | Last verified | 2026-11-16 at `0b8c34db7f` |
42
+ | Module id | `agent` |
43
+ | Parent spec | [src/services](../../docs/README.md) |
44
+ | Doc kind | Module spec |
45
+ | Coverage score | Pending coverage assessment |
46
+ | Validation status | pass-with-warnings — assessed 2026-11-17; validator runtime 01a1e76f-2293-79a0-9f8f-f060038448dd; 0 Blocking, 0 Important, 4 Minor findings. |
47
+
48
+ ## Applicability
49
+
50
+ | Condition ID | Status | Evidence or reason | Owned section |
51
+ | ------------ | ------ | ------------------ | ------------- |
52
+ | `module.has_tiers` | N/A | No tier policy exists in `package.json` or under src | Tier |
53
+ | `module.has_ui` | N/A | Every request function and wrapper returns a promise; nothing renders | UI use-case flow |
54
+ | `module.crosses_service_boundaries` | Applicable | `src/services/agent/index.ts` targets the WCC API gateway and completes on Contact Center WebSocket notifications | Cross-boundary use-case flow |
55
+ | `module.holds_client_state` | N/A | The factory keeps no state; the agent configuration it updates is owned by `src/cc.ts` | Client state model |
56
+ | `module.enforces_domain_rules` | Applicable | Login-option, dial-number, browser-voice, and buddy-filter rules in `src/cc.ts` around the factory calls | Business rules and invariants |
57
+ | `module.is_concurrent_async` | Applicable | Every request in `src/services/agent/index.ts` is an AqmReqs promise settled by a WebSocket notification | Concurrency and reactive flow |
58
+ | `module.owns_persistence` | N/A | Nothing in the module writes storage | Data, schema, and migration discipline |
59
+ | `module.stateful_transitions` | N/A | Agent state lives in the backend; the module sends requests and relays notifications | State machine |
60
+ | `module.exposes_wire_protocol` | Applicable | Endpoint paths, payload types, and nested notification binds in `src/services/agent/index.ts` and `src/services/agent/types.ts` | Protocol and wire format |
61
+ | `module.ui_multi_screen` | N/A | No UI | UI flow |
62
+ | `module.large_data_model` | N/A | `src/services/agent/types.ts` holds message and payload types only | Data model |
63
+ | `module.returns_caller_errors` | Applicable | `src/services/agent/index.ts` declares errIds and error transformers; `src/cc.ts` rethrows them through getErrorDetails | Caller-visible failure modes |
64
+ | `module.module_specific_conventions` | Applicable | Each request keeps endpoint, method, and both binds in one config in `src/services/agent/index.ts` | Module-specific rules |
65
+ | `module.published_package` | N/A | The module is not a package; the package export is owned by the root module | Export stability |
66
+ | `module.embedded_in_host` | N/A | No host embedding | Host integration and theming |
67
+ | `module.has_design_tradeoff` | Applicable | HTTP initiation with WebSocket completion through `src/services/core/aqm-reqs.ts` | Key design trade-off |
68
+ | `module.has_submodules` | N/A | The module directory has no child module (module_tree.py reports none) | Sub-modules |
69
+
70
+ ## Evidence register
71
+
72
+ | Evidence | What it establishes |
73
+ | -------- | ------------------- |
74
+ | `src/services/agent/index.ts` | The `routingAgent` request functions with their endpoints, methods, `CC_EVENTS` binds, error transformers, and errIds |
75
+ | `src/services/agent/types.ts` | `AGENT_EVENTS`, request types (`Logout`, `StateChange`, `UserStationLogin`, `BuddyAgents`), notification types (`StationLoginSuccess`, `LogoutSuccess`, `StateChangeSuccess`, `BuddyAgentsSuccess`, `ReloginSuccess`), `StationLoginSuccessResponse`, `DeviceTypeUpdateSuccess`, `AgentState`, `LoginOption`, and their JSDoc |
76
+ | `src/services/config/types.ts` | The `CC_EVENTS` string values the binds use, for example `StationLogin` with nested `AgentStationLoginSuccess` |
77
+ | `src/services/index.ts` | The services root builds `agent` as `routingAgent(aqmReq)` |
78
+ | `src/cc.ts` | ContactCenter wrappers `stationLogin`, `stationLogout`, `setAgentState`, `getBuddyAgents`, `updateAgentProfile`; `getDeviceId`; `handleWebsocketMessage`; `handleConnectionLost`; `silentRelogin`; the in-code reason for the `webrtc-` dial number |
79
+ | `src/services/core/aqm-reqs.ts` | `req` and `reqEmpty`, nested bind matching, the POST-if-data default method, the one-pending-request-per-bind rule, and the timeout rejection |
80
+ | `src/services/core/constants.ts` | `TIMEOUT_REQ` is 20000 ms |
81
+ | `src/services/core/Utils.ts` | `createErrDetailsObject`, `getErrorDetails`, `getStationLoginErrorData`, and `isValidDialNumber` |
82
+ | `src/services/constants.ts` | `WCC_API_GATEWAY` (`wcc-api-gateway`) and `WEB_RTC_PREFIX` (`webrtc-`) |
83
+ | `src/services/config/constants.ts` | `AGENT_STATE_AVAILABLE` (`Available`) and `AGENT_STATE_AVAILABLE_ID` (`0`) |
84
+ | `src/types.ts` | Public `AgentLogin`, `AgentProfileUpdate`, `BuddyAgents` (with `action`), the response aliases, and `CCPluginConfig.allowAutomatedRelogin` |
85
+ | `src/config.ts` | `allowAutomatedRelogin` defaults to true |
86
+ | `src/index.ts` | Public exports of `routingAgent`, `AGENT_EVENTS`, and the agent types |
87
+ | `src/metrics/constants.ts` | The station, state-change, and buddy-agent metric names |
88
+ | `test/unit/spec/services/agent/index.ts` | Five cases; each asserts only that the request function delegates to `req` or `reqEmpty` and returns a value |
89
+ | `test/unit/spec/cc.ts` | `stationLogin`, `stationLogout`, `setAgentStatus`, `getBuddyAgents`, `silentRelogin`, `cc.getDeviceId`, `handleWebsocketMessage events`, and `updateAgentProfile` suites |
90
+ | `test/unit/spec/services/core/Utils.ts` | `getStationLoginErrorData` message and fieldName cases |
91
+ | `src/cc.ts` | Justifies the extension subsections under Data flow and sequence coverage: one subsection per operation group the wrappers implement (station login, station logout, state change, buddy-agent lookup, recovery reload) plus the WebSocket event mapping and silent-relogin flows |
92
+
93
+ ## Purpose and boundary
94
+
95
+ - Purpose: Manage agent lifecycle including login, logout, state changes, and buddy agent queries.
96
+ - Responsibility: Agent owns the `routingAgent(AqmReqs)` request factory for station login, station logout, agent-state change, buddy-agent lookup, and agent-session reload. ContactCenter exposes the application-facing methods/events and owns profile/device updates plus recovery policy.
97
+ - In scope: Own AQM request definitions for station login/logout, state change, buddy-agent queries, and reload, the routing payload and notification types, and `AGENT_EVENTS`.
98
+ - Out of scope: Device/profile update and automated relogin orchestration belong to ContactCenter. Request correlation, timeouts, and the socket belong to AqmReqs and the core module.
99
+ - Consumers: the services root (`services.agent`), ContactCenter, and applications that import `routingAgent` or `AGENT_EVENTS` from the package.
100
+
101
+ The capabilities applications reach through ContactCenter:
102
+
103
+ - **Station Login**: Login with browser (WebRTC), extension, or dial number
104
+ - **Station Logout**: Logout from current station with reason
105
+ - **State Management**: Toggle between Available/Idle states with aux codes
106
+ - **Buddy Agents**: Query available agents for consult/transfer
107
+ - **Silent Relogin**: Automatic re-authentication on reconnection, and during `cc.register()`, when `allowAutomatedRelogin` is enabled
108
+
109
+ ## Structure and key files
110
+
111
+ | Path | Responsibility |
112
+ | ---- | -------------- |
113
+ | `src/services/agent/index.ts` | Agent service factory: the AQM request definitions |
114
+ | `src/services/agent/types.ts` | Agent types and events: request payloads, notification messages, `AGENT_EVENTS` |
115
+ | `src/cc.ts` | ContactCenter wrappers, WebSocket-to-event mapping, and silent relogin around the factory |
116
+ | `src/services/index.ts` | Builds the factory once as `services.agent` |
117
+ | `test/unit/spec/services/agent/index.ts` | Factory delegation tests |
118
+ | `test/unit/spec/cc.ts` | Wrapper, event-mapping, relogin, and profile-update tests |
119
+
120
+ ## Public surface
121
+
122
+ The public `cc.*` methods are part of the published `contact-center-sdk` contract owned by the
123
+ [root module](../../../docs/README.md); this module owns their agent semantics below.
124
+
125
+ | Surface | Consumer | Compatibility commitment | Source |
126
+ | ------- | -------- | ------------------------ | ------ |
127
+ | `contact-center-agent-events`: `AGENT_EVENTS`, the routing request types (`Logout`, `StateChange`, `UserStationLogin`, `BuddyAgents`), the notification types (`StationLoginSuccess`, `LogoutSuccess`, `StateChangeSuccess`, `BuddyAgentsSuccess`, `ReloginSuccess`), `StationLoginSuccessResponse`, and `AgentState` | Applications listening on `webex.cc`; TypeScript consumers | Published; event names and payload shapes change only with a package release | `src/services/agent/types.ts` |
128
+ | `contact-center-sdk`: the `routingAgent` export, the ContactCenter agent methods (`stationLogin`, `stationLogout`, `setAgentState`, `getBuddyAgents`, `updateAgentProfile`), and the response aliases `StationLoginResponse`, `StationLogoutResponse`, `BuddyAgentsResponse`, `SetStateResponse`, and `UpdateDeviceTypeResponse` | Applications | Published; the request function names and the method signatures are stable | `src/index.ts`, `src/types.ts` |
129
+
130
+ Login options:
131
+
132
+ | Option | Description | Requires dialNumber |
133
+ |--------|-------------|---------------------|
134
+ | `BROWSER` | WebRTC softphone in browser | No |
135
+ | `EXTENSION` | Desk phone extension | Yes |
136
+ | `AGENT_DN` | Direct dial number | Yes |
137
+
138
+ `cc.stationLogin(params)`: Login agent to a station.
139
+
140
+ **Parameters**:
141
+
142
+ - `teamId` (string): Team to login to
143
+ - `loginOption` ('BROWSER' | 'EXTENSION' | 'AGENT_DN'): Device type
144
+ - `dialNumber` (string, optional): Required for EXTENSION/AGENT_DN
145
+
146
+ **Returns**: `Promise<StationLoginResponse>`
147
+
148
+ ```typescript
149
+ // Browser login
150
+ const response = await cc.stationLogin({
151
+ teamId: 'team-123',
152
+ loginOption: 'BROWSER',
153
+ });
154
+
155
+ // Extension login
156
+ const response = await cc.stationLogin({
157
+ teamId: 'team-123',
158
+ loginOption: 'EXTENSION',
159
+ dialNumber: '1234',
160
+ });
161
+ ```
162
+
163
+ `cc.stationLogout(params)`: Logout agent from station.
164
+
165
+ - `logoutReason` (string, optional): 'User requested logout' | 'Inactivity Logout' | 'User requested agent profile update'
166
+
167
+ **Returns**: `Promise<StationLogoutResponse>`
168
+
169
+ ```typescript
170
+ await cc.stationLogout({
171
+ logoutReason: 'User requested logout',
172
+ });
173
+ ```
174
+
175
+ `cc.setAgentState(params)`: Change agent state (Available/Idle).
176
+
177
+ - `state` (`AgentState`: 'Available' | 'Idle' | 'RONA' | string): New state
178
+ - `auxCodeId` (string): Auxiliary code ID
179
+ - `lastStateChangeReason` (string, optional): Reason for change
180
+ - `agentId` (string, optional): Agent ID (defaults to current agent)
181
+
182
+ **Returns**: `Promise<SetStateResponse>`
183
+
184
+ ```typescript
185
+ // Go Available
186
+ await cc.setAgentState({
187
+ state: 'Available',
188
+ auxCodeId: '0',
189
+ });
190
+
191
+ // Go to Idle with specific code
192
+ await cc.setAgentState({
193
+ state: 'Idle',
194
+ auxCodeId: 'break-code-123',
195
+ lastStateChangeReason: 'Coffee break',
196
+ });
197
+ ```
198
+
199
+ `cc.getBuddyAgents(params)`: Get list of agents for consult/transfer.
200
+
201
+ - `state` (string, optional): Filter by state ('Available', 'Idle')
202
+ - `mediaType` (string, optional): Media type filter ('telephony', 'chat', 'social', 'email'); defaults to 'telephony'
203
+ - `action` ('Consult' | 'Transfer', optional): applies the default state filter when `state` is omitted
204
+
205
+ **Returns**: `Promise<BuddyAgentsResponse>`
206
+
207
+ ```typescript
208
+ const response = await cc.getBuddyAgents({
209
+ state: 'Available',
210
+ mediaType: 'telephony',
211
+ });
212
+
213
+ response.data.agentList.forEach(agent => {
214
+ console.log(`${agent.agentName} (${agent.state})`);
215
+ });
216
+ ```
217
+
218
+ End-to-end usage after registration:
219
+
220
+ ```typescript
221
+ const cc = webex.cc;
222
+
223
+ // Register and login
224
+ const profile = await cc.register();
225
+ await cc.stationLogin({
226
+ teamId: profile.teams[0].id,
227
+ loginOption: 'BROWSER',
228
+ });
229
+
230
+ // Set state to Available
231
+ await cc.setAgentState({
232
+ state: 'Available',
233
+ auxCodeId: '0',
234
+ });
235
+
236
+ // Get available agents for transfer
237
+ const buddies = await cc.getBuddyAgents({
238
+ state: 'Available',
239
+ mediaType: 'telephony',
240
+ });
241
+ ```
242
+
243
+ Events (`AGENT_EVENTS`) that ContactCenter emits:
244
+
245
+ | Event | Type | Description |
246
+ |-------|------|-------------|
247
+ | `agent:stationLoginSuccess` | `StationLoginSuccessResponse` | Login succeeded |
248
+ | `agent:stationLoginFailed` | Failure notification data | Login failed |
249
+ | `agent:logoutSuccess` | `LogoutSuccess` | Logout succeeded |
250
+ | `agent:logoutFailed` | Failure notification data | Logout failed |
251
+ | `agent:stateChange` | `StateChangeSuccess` | State changed (any source) |
252
+ | `agent:stateChangeSuccess` | `StateChangeSuccess` | State change succeeded |
253
+ | `agent:stateChangeFailed` | Failure notification data | State change failed |
254
+ | `agent:multiLogin` | Object | Multi-login detected |
255
+ | `agent:reloginSuccess` | `ReloginSuccess` with `mmProfile` and `notifsTrackingId` in place of `channelsMap` | Silent relogin succeeded |
256
+ | `agent:dnRegistered` | Object | DN registration complete |
257
+
258
+ ```typescript
259
+ cc.on('agent:stateChange', (event) => {
260
+ console.log(`State: ${event.subStatus}, AuxCode: ${event.auxCodeId}`);
261
+ });
262
+
263
+ cc.on('agent:multiLogin', (event) => {
264
+ console.warn('Another session detected');
265
+ });
266
+ ```
267
+
268
+ Agent states:
269
+
270
+ The `AgentState` type (`'Available' | 'Idle' | 'RONA' | string`) is extensible -- the `string` union member allows backend-defined states beyond the known values listed below.
271
+
272
+ | State | SubStatus | Description |
273
+ |---|---|---|
274
+ | LoggedIn | Available | Ready to receive tasks |
275
+ | LoggedIn | Idle | On break or not ready (uses aux code for sub-reason) |
276
+ | RONA | - | Rang but no answer; agent failed to accept offered task |
277
+ | LoggedOut | - | Not logged in |
278
+ | LoggedIn | *(custom)* | Additional org-specific states defined via aux codes |
279
+
280
+ > **Note**: `AgentState` is a union with `string`, so consumers should handle unknown state values gracefully rather than exhaustively matching only the known literals.
281
+
282
+ ## Dependencies
283
+
284
+ | Dependency | Why it is required | Failure behavior |
285
+ | ---------- | ------------------ | ---------------- |
286
+ | AqmReqs and WCC API gateway (`src/services/core/aqm-reqs.ts`, service `wcc-api-gateway`) | Sends each request through `webex.request` and correlates the result | An HTTP rejection clears the pending entry and rejects through the request's `err` transformer |
287
+ | Correlated WebSocket success/failure notifications (contract `wxcc-websocket-notifications`) | The nested notification is the completion signal | A failure notification rejects with `Err.Details(errId)`; no notification rejects with `Service.aqm.reqs.Timeout` after 20000 ms |
288
+ | Registered ContactCenter profile and connection state (`src/cc.ts`) | Wrappers read `agentConfig` (agent id, profile id, dial plan, `webRtcEnabled`) | Wrappers assume registration; without it they fail when they read `agentConfig` |
289
+ | ContactCenter metrics, web calling, and logging (`src/cc.ts`) | Timing and tracking, browser line registration, structured errors | Metric and log calls do not change the request outcome |
290
+
291
+ Preconditions for the wrappers:
292
+
293
+ - Requires `cc.register()` to be called first
294
+ - Agent profile must be fetched before login
295
+ - WebRTC (BROWSER option) requires mercury connection
296
+
297
+ `cc.register()` connects Mercury when any of the agent's login voice options requires browser voice.
298
+
299
+ ## Requirements
300
+
301
+ | ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
302
+ |---|---|---|---|---|---|---|
303
+ | AGENT-R-001 | routingAgent station login/logout must use the documented WCC endpoints (`POST /v1/agents/login`, `POST /v1/agents/logout`) and settle on their nested `CC_EVENTS` success/failure notifications. | The backend operation is asynchronous and HTTP acknowledgement is not final agent state. | `src/services/agent/index.ts` | `test/unit/spec/services/agent/index.ts`, `test/unit/spec/cc.ts` | The factory test asserts delegation to `req` only; endpoint and bind values are not asserted. | PRESENT |
304
+ | AGENT-R-002 | State change must use PUT `/v1/agents/session/state` and preserve typed success/failure binds. | Agent availability drives routing eligibility and must not be inferred from request acknowledgement. | `src/services/agent/index.ts` | `test/unit/spec/services/agent/index.ts`, `test/unit/spec/cc.ts` | The PUT method and binds are not asserted by a unit test. | PRESENT |
305
+ | AGENT-R-003 | Buddy-agent lookup must preserve its typed request and correlated response contract. | Consult/transfer selection depends on backend-filtered availability. | `src/services/agent/index.ts` | `test/unit/spec/services/agent/index.ts`, `test/unit/spec/cc.ts` | The `POST /v1/agents/buddyList` endpoint is not asserted by a unit test. | PRESENT |
306
+ | AGENT-R-004 | The agent factory exposes `reload`, while ContactCenter alone decides when automated relogin is permitted. | Transport recovery lacks the profile/policy context required to mutate an agent session safely. | `src/cc.ts` | `test/unit/spec/cc.ts` | None. | PRESENT |
307
+ | AGENT-R-005 | Device/profile update is `ContactCenter.updateAgentProfile`: it calls `stationLogout` with reason 'User requested agent profile update', then `stationLogin` with the new `loginOption`, `dialNumber`, and `teamId`, and returns the login response typed `AgentDeviceTypeUpdateSuccess`; `routingAgent` has no `deviceUpdate` function. | The factory has no device-update request, so a device or team change reuses the logout and login flows with their metrics; calling a non-existent `routingAgent.deviceUpdate` would fail at runtime. | `src/cc.ts`, `src/services/agent/index.ts` | `test/unit/spec/cc.ts` | No test asserts that `routingAgent.deviceUpdate` is absent. | PRESENT |
308
+ | AGENT-R-006 | BROWSER station login must send `dialNumber` and `deviceId` as `webrtc-{agentId}` on `POST /v1/agents/login`. EXTENSION and AGENT_DN continue to send the caller-supplied dial number for both fields. | QRM stores `agent.dn` from `dialNumber`. Legacy VPOP RTMS only treats a DN as WebRTC when it starts with `webrtc-`; a bare UUID gets a steering prefix and the agent invite fails with SIP 484. | `src/cc.ts` | `test/unit/spec/cc.ts` | Public `stationLogin({loginOption: 'BROWSER'})` input is unchanged; only the backend login payload is prefixed. | PRESENT |
309
+ | AGENT-R-007 | An AGENT_DN station login whose dial number fails `isValidDialNumber` against the profile dial plan rejects with `INVALID_DIAL_NUMBER` before any request is sent. | The backend would otherwise register an unreachable DN; the reason maps to a field message for the login form. | `src/cc.ts` | `test/unit/spec/services/core/Utils.ts` | No `test/unit/spec/cc.ts` case drives the AGENT_DN rejection. | PRESENT |
310
+ | AGENT-R-008 | `setAgentState` rejects a change to Available with `VOICE_CONNECTION_ERROR.NOT_READY` (type `SDK_VALIDATION_ERROR`) when browser voice is required and not ready; Idle and non-browser changes proceed. | An Available agent without a registered browser line would be offered calls it cannot answer. | `src/cc.ts` | `test/unit/spec/cc.ts` | None. | PRESENT |
311
+ | AGENT-R-009 | `getBuddyAgents` sends `agentProfileId` from the profile, defaults `mediaType` to `telephony`, and, when `state` is omitted, filters on Available for `action: 'Transfer'` and sends no state for Consult. | A transfer needs an agent who can take the call now; a consult may target an Idle agent. | `src/cc.ts`, `src/types.ts` | `test/unit/spec/cc.ts` | None. | PRESENT |
312
+ | AGENT-R-010 | Station login success and relogin success replace `channelsMap` with `mmProfile` counts per channel and add `notifsTrackingId`. | Applications receive capacity numbers instead of raw channel id lists. | `src/cc.ts`, `src/services/agent/types.ts` | `test/unit/spec/cc.ts` | None. | PRESENT |
313
+
314
+ ## Design overview
315
+
316
+ The agent service uses a factory pattern: `routingAgent` is a pure AQM factory. It receives an initialized AqmReqs instance and returns five request functions: `reload`, `logout`, `stationLogin`, `stateChange`, and `buddyAgents`. Each request config declares the endpoint/payload plus exact `CC_EVENTS` notification binds.
317
+
318
+ The factory initiates authenticated HTTP requests and supplies `CC_EVENTS` success/failure binds to AqmReqs. The services root builds it once as `services.agent` (`src/services/index.ts`); the factory holds no state.
319
+
320
+ ContactCenter validates and enriches public inputs, starts metrics, delegates to the factory, performs browser-calling work when required, and maps backend notifications to application-facing events. `updateAgentProfile()` and private `silentRelogin()` are ContactCenter methods; the latter calls `services.agent.reload()` only after package-level recovery policy permits it.
321
+
322
+ Stack: TypeScript 5.4 AQM request factory, REST initiation, WebSocket completion events, Jest 27.
323
+
324
+ Metrics ContactCenter tracks around the factory calls (`timeEvent` before the call, `trackEvent` after it):
325
+
326
+ | Metric | Type | When Tracked |
327
+ | ---------------------------- | --------------------------------- | ------------------------ |
328
+ | `STATION_LOGIN_SUCCESS` | behavioral, business, operational | Login succeeds |
329
+ | `STATION_LOGIN_FAILED` | behavioral, business, operational | Login fails |
330
+ | `STATION_LOGOUT_SUCCESS` | behavioral, business, operational | Logout succeeds |
331
+ | `STATION_LOGOUT_FAILED` | behavioral, business, operational | Logout fails |
332
+ | `AGENT_STATE_CHANGE_SUCCESS` | behavioral, business, operational | State change succeeds |
333
+ | `AGENT_STATE_CHANGE_FAILED` | behavioral, business, operational | State change fails |
334
+ | `FETCH_BUDDY_AGENTS_SUCCESS` | operational | Buddy agents fetched |
335
+ | `FETCH_BUDDY_AGENTS_FAILED` | operational | Buddy agents fetch fails |
336
+
337
+ ## Data flow and sequence coverage
338
+
339
+ Call style: in-process promise calls from ContactCenter into the factory; AqmReqs sends an authenticated
340
+ HTTP request to the WCC API gateway and settles the promise from the matching Contact Center WebSocket
341
+ notification.
342
+
343
+ Sequence coverage:
344
+
345
+ | Operation group | Entry and outcome | Diagram or evidence | Failure and recovery coverage |
346
+ | --------------- | ----------------- | ------------------- | ----------------------------- |
347
+ | Station login | `cc.stationLogin` → `stationLogin` → `POST /v1/agents/login`; resolves `StationLoginResponse` | Station login | Pre-request `INVALID_DIAL_NUMBER` rejection, nested failure notification, HTTP rejection, and timeout throw |
348
+ | Station logout | `cc.stationLogout` → `logout` → `POST /v1/agents/logout`; resolves `StationLogoutResponse` | Station logout | Nested failure/timeout rejects and calling deregistration occurs only after success |
349
+ | State change | `cc.setAgentState` → `stateChange` → `PUT /v1/agents/session/state`; resolves `SetStateResponse` | State change | Pre-request browser-voice rejection; failure notification or timeout returns a structured rejection |
350
+ | Buddy agents | `cc.getBuddyAgents` → `buddyAgents` → `POST /v1/agents/buddyList`; resolves `BuddyAgentsResponse` | Buddy-agent lookup | Correlated retrieval failure/timeout rejects |
351
+ | Reload | Reconnect or `cc.register()` → private `silentRelogin` → `reload` → `POST /v1/agents/reload` | Recovery reload | Disabled policy keeps the reported state; `AGENT_NOT_FOUND` is silent; other relogin failures throw |
352
+ | Event mapping | WebSocket message → `handleWebsocketMessage` → `AGENT_EVENTS` emit | WebSocket-to-application event mapping | Types outside `CC_EVENTS` are not emitted |
353
+
354
+ ### Station login
355
+
356
+ ```mermaid
357
+ sequenceDiagram
358
+ participant App
359
+ participant CC as ContactCenter
360
+ participant Svc as Services.agent
361
+ participant AQM as AqmReqs
362
+ participant WS as WebSocket
363
+ participant BE as Backend
364
+ App->>CC: stationLogin(params)
365
+ CC->>CC: timeEvent(LOGIN_SUCCESS, LOGIN_FAILED)
366
+ alt AGENT_DN dial number fails isValidDialNumber
367
+ CC->>CC: trackEvent(LOGIN_FAILED)
368
+ CC-->>App: throw INVALID_DIAL_NUMBER (no request sent)
369
+ else valid input
370
+ CC->>Svc: stationLogin({data})
371
+ Svc->>AQM: req(config)
372
+ AQM->>BE: HTTP POST /v1/agents/login
373
+ alt nested success
374
+ BE-->>WS: AgentStationLoginSuccess
375
+ WS-->>AQM: matching success notification
376
+ AQM-->>Svc: StationLoginSuccess
377
+ Svc-->>CC: login response
378
+ CC->>CC: Register WebCalling if BROWSER and enabled
379
+ CC->>CC: trackEvent(LOGIN_SUCCESS)
380
+ CC-->>App: StationLoginResponse
381
+ else nested failure, HTTP rejection, or timeout
382
+ WS-->>AQM: failure notification or no completion
383
+ AQM-->>CC: structured rejection
384
+ CC->>CC: trackEvent(LOGIN_FAILED)
385
+ CC-->>App: throw detailed error
386
+ end
387
+ end
388
+ ```
389
+
390
+ The diagram's `LOGIN_SUCCESS` and `LOGIN_FAILED` are `METRIC_EVENT_NAMES.STATION_LOGIN_SUCCESS` and
391
+ `STATION_LOGIN_FAILED`. The browser line is registered only when the login option is BROWSER, the
392
+ profile has `webRtcEnabled`, and `disableWebRTCRegistration` is not set.
393
+
394
+ ### Station logout
395
+
396
+ ```mermaid
397
+ sequenceDiagram
398
+ participant App
399
+ participant CC as ContactCenter
400
+ participant Agent as routingAgent
401
+ participant AQM as AqmReqs
402
+ participant WS as Primary WebSocket
403
+ App->>CC: stationLogout({logoutReason})
404
+ CC->>Agent: logout({data})
405
+ Agent->>AQM: POST /v1/agents/logout + nested binds
406
+ alt AGENT_LOGOUT_SUCCESS
407
+ WS-->>AQM: matching nested success
408
+ AQM-->>CC: LogoutSuccess
409
+ CC->>CC: track success; deregister WebCalling line
410
+ CC-->>App: StationLogoutResponse
411
+ else failure, HTTP rejection, or timeout
412
+ WS-->>AQM: matching failure or no completion
413
+ CC->>CC: track failure
414
+ CC-->>App: throw detailed error
415
+ end
416
+ ```
417
+
418
+ ### State change
419
+
420
+ ```mermaid
421
+ sequenceDiagram
422
+ participant App
423
+ participant CC as ContactCenter
424
+ participant Agent as routingAgent
425
+ participant AQM as AqmReqs
426
+ participant WS as Primary WebSocket
427
+ App->>CC: setAgentState(data)
428
+ alt Available while browser voice is required and not ready
429
+ CC-->>App: throw VOICE_CONNECTION_ERROR.NOT_READY (no request sent)
430
+ else request allowed
431
+ CC->>Agent: stateChange({data + agentId})
432
+ Agent->>AQM: PUT /v1/agents/session/state + binds
433
+ alt AGENT_STATE_CHANGE_SUCCESS
434
+ WS-->>AQM: matching nested success
435
+ AQM-->>CC: StateChangeSuccess
436
+ CC-->>App: SetStateResponse
437
+ else failure, HTTP rejection, or timeout
438
+ WS-->>AQM: matching failure or no completion
439
+ AQM-->>CC: structured rejection
440
+ CC-->>App: throw detailed error
441
+ end
442
+ end
443
+ ```
444
+
445
+ ### Buddy-agent lookup
446
+
447
+ ```mermaid
448
+ sequenceDiagram
449
+ participant App
450
+ participant CC as ContactCenter
451
+ participant Agent as routingAgent
452
+ participant AQM as AqmReqs
453
+ participant WS as Primary WebSocket
454
+ App->>CC: getBuddyAgents(query)
455
+ CC->>Agent: buddyAgents({data})
456
+ Agent->>AQM: POST /v1/agents/buddyList + binds
457
+ alt AGENT_BUDDY_AGENTS_SUCCESS
458
+ WS-->>AQM: matching nested success
459
+ AQM-->>App: BuddyAgentsResponse
460
+ else retrieve failure or timeout
461
+ WS-->>AQM: matching failure or no completion
462
+ AQM-->>App: structured rejection
463
+ end
464
+ ```
465
+
466
+ ### Recovery reload
467
+
468
+ ```mermaid
469
+ sequenceDiagram
470
+ participant CS as ConnectionService
471
+ participant CC as ContactCenter
472
+ participant Agent as routingAgent
473
+ CS-->>CC: connectionLost(details)
474
+ alt automated relogin allowed
475
+ CC->>CC: silentRelogin()
476
+ CC->>Agent: reload()
477
+ alt AgentReloginSuccess
478
+ Agent-->>CC: relogin result
479
+ CC->>CC: update agentConfig and device state
480
+ opt lastStateChangeReason is agent-wss-disconnect
481
+ CC->>CC: setAgentState Available (aux code 0)
482
+ end
483
+ else AGENT_NOT_FOUND
484
+ Agent-->>CC: relogin failure
485
+ CC->>CC: handle silently
486
+ else other failure
487
+ Agent-->>CC: relogin failure
488
+ CC->>CC: throw detailed error
489
+ end
490
+ else not allowed
491
+ CC->>CC: retain reported state
492
+ end
493
+ ```
494
+
495
+ Automatic relogin on WebSocket reconnection: `handleConnectionLost` runs the relogin only for a `connectionLost` message with `isSocketReconnected`; `connectWebsocket` during `cc.register()` also calls `silentRelogin()` when `allowAutomatedRelogin` is set, and a relogin failure there rejects `cc.register()`.
496
+
497
+ ### WebSocket-to-application event mapping
498
+
499
+ ```mermaid
500
+ flowchart LR
501
+ A[WebSocket Message] --> B[WebSocketManager]
502
+ B --> C[cc.handleWebsocketMessage]
503
+ C --> D{Event Type?}
504
+ D -->|AGENT_STATE_CHANGE| E[emit agent:stateChange]
505
+ D -->|data.type check| F{Nested Type?}
506
+ F -->|STATION_LOGIN_SUCCESS| G[Transform channelsMap]
507
+ G --> H[emit agent:stationLoginSuccess]
508
+ F -->|LOGOUT_SUCCESS| I[emit agent:logoutSuccess]
509
+ ```
510
+
511
+ The diagram shows the main branches. On the outer type, `AGENT_MULTI_LOGIN` also emits
512
+ `agent:multiLogin`. On the nested `data.type`, `AGENT_RELOGIN_SUCCESS` is transformed like login success
513
+ and emits `agent:reloginSuccess`; the state-change success and failure, station-login failure, logout
514
+ failure, and `AGENT_DN_REGISTERED` types emit their `AGENT_EVENTS` value with the notification data.
515
+ Before this mapping, any `data.type` found in `CC_EVENTS` is also re-emitted under its raw name.
516
+
517
+ The login success event transforms `channelsMap` to `mmProfile`:
518
+
519
+ ```typescript
520
+ // Incoming
521
+ channelsMap: {
522
+ chat: ['channel-1', 'channel-2'],
523
+ email: ['channel-3'],
524
+ social: [],
525
+ telephony: ['channel-4'],
526
+ }
527
+
528
+ // Transformed
529
+ mmProfile: {
530
+ chat: 2, // Length of arrays
531
+ email: 1,
532
+ social: 0,
533
+ telephony: 1,
534
+ }
535
+ ```
536
+
537
+ ## Class and component relationships
538
+
539
+ ```mermaid
540
+ classDiagram
541
+ class ContactCenter
542
+ class routingAgent
543
+ class AqmReqs
544
+ class WebSocketManager
545
+ ContactCenter --> routingAgent : public agent operations / reload
546
+ routingAgent --> AqmReqs : request factories
547
+ AqmReqs --> WebSocketManager : correlated notifications
548
+ ContactCenter --> ContactCenter : updateAgentProfile + silentRelogin ownership
549
+ ```
550
+
551
+ ## Use cases and flows
552
+
553
+ | Use case | Actor or caller | Primary steps and outcome | Failure or boundary behavior | Evidence |
554
+ | -------- | --------------- | ------------------------- | ---------------------------- | -------- |
555
+ | `UC-1` Station login/logout | Application | validate public input in ContactCenter, initiate through routingAgent, settle from nested WebSocket notification | Invalid AGENT_DN dial number, failure notification, HTTP rejection, or timeout throws a detailed error | `src/cc.ts`, `src/services/agent/index.ts`, `test/unit/spec/services/agent/index.ts` |
556
+ | `UC-2` State change | Application or silent relogin | PUT the state payload and return the correlated typed response | Browser voice not ready, failure notification, or timeout throws | `src/services/agent/index.ts`, `test/unit/spec/services/agent/index.ts` |
557
+ | `UC-3` Buddy-agent query | Application selecting a consult or transfer target | retrieve backend-filtered candidates for consult/transfer | Retrieval failure or timeout throws | `src/services/agent/index.ts`, `test/unit/spec/services/agent/index.ts` |
558
+ | `UC-4` Recovery reload | ConnectionService reconnect or `cc.register()` | ContactCenter decides whether to invoke private relogin and the factory's `reload` | `AGENT_NOT_FOUND` returns silently; other failures throw | `src/cc.ts`, `test/unit/spec/cc.ts` |
559
+ | `UC-5` Device/profile update | Application | ContactCenter owns `updateAgentProfile`; the agent factory has no device-update method | A failing logout or login is tracked and rethrown | `src/cc.ts`, `test/unit/spec/cc.ts` |
560
+
561
+ ### Cross-boundary use-case flow
562
+
563
+ | Boundary | Transport and ordering | Compatibility | Timeout, retry, and recovery |
564
+ | -------- | ---------------------- | ------------- | ---------------------------- |
565
+ | WCC API gateway (`UC-1` to `UC-5`) | Authenticated HTTP through `webex.request` with service `wcc-api-gateway`; the HTTP response is only an acknowledgement | Paths under `/v1/agents/`; contract `wxcc-api-gateway` | HTTP rejection rejects at once; no retry in this module |
566
+ | Contact Center WebSocket (`UC-1` to `UC-5`) | AqmReqs matches the outer `type` and the nested `data.type` of each notification against the request's binds | Contract `wxcc-websocket-notifications`; `CC_EVENTS` values | No matching notification within 20000 ms rejects with `Service.aqm.reqs.Timeout`; recovery after reconnect is the silent relogin (`UC-4`) |
567
+
568
+ ## Business rules and invariants
569
+
570
+ | ID | Invariant | WHY | Enforcement source | Test evidence |
571
+ | -- | --------- | --- | ------------------ | ------------- |
572
+ | `INV-001` | Every request's success and failure binds match both the outer notification `type` and the nested `data.type`; flattening either bind can settle the wrong request. | One outer type carries several outcomes (`StationLogin` carries both `AgentStationLoginSuccess` and `AgentStationLoginFailed`), so only the nested type tells success from failure. | `src/services/agent/index.ts`, `src/services/core/aqm-reqs.ts` | none found for the agent binds |
573
+ | `INV-002` | After a successful EXTENSION or AGENT_DN login, `agentConfig.dn` and `defaultDn` hold the dial number, and `deviceType` holds the login option. | Later calls and relogin read the DN from the profile. | `src/cc.ts` | `test/unit/spec/cc.ts` |
574
+ | `INV-003` | Silent relogin after an `agent-wss-disconnect` requests Available with aux code `0`; any other last reason keeps the backend state. | A socket drop moved the agent out of Available without the agent asking. | `src/cc.ts` | `test/unit/spec/cc.ts` |
575
+
576
+ ## Concurrency and reactive flow
577
+
578
+ - Execution model: one JavaScript event loop; every request function returns a promise that AqmReqs settles from a WebSocket message. Async operations must remain non-blocking.
579
+ - Ordering guarantees: within `stationLogin`, the browser line is registered only after the login notification resolves; within `stationLogout`, the line is deregistered only after the logout notification resolves.
580
+ - Idempotency and retry: AqmReqs rejects a second request with the same success or failure bind key while one is pending (`Service.aqm.reqs.Pending`), so two concurrent `stationLogin` calls do not both reach the backend. Nothing in this module retries.
581
+ - Shared-state protection: the factory has no state; ContactCenter is the single writer of `agentConfig`.
582
+ - Blocking restrictions: none; all I/O is in AqmReqs and WebexRequest.
583
+
584
+ ## Protocol and wire format
585
+
586
+ Request, response, and event payload ownership is anchored in `src/services/agent/index.ts`. HTTP initiates backend work where applicable; WebSocket messages provide realtime events and, for AQM flows, correlated completion.
587
+
588
+ For example, station login defines the real outer and nested event binds shown in the first table row.
589
+
590
+ | Message or frame | Version | Producer or serializer | Consumer or parser | Compatibility and ordering rule |
591
+ | ---------------- | ------- | ---------------------- | ------------------ | ------------------------------- |
592
+ | `POST /v1/agents/login` with `UserStationLogin` | v1 path | `stationLogin` in `src/services/agent/index.ts` | WCC API gateway | Completes on outer `StationLogin` with nested `AgentStationLoginSuccess` or `AgentStationLoginFailed` |
593
+ | `POST /v1/agents/logout` with `Logout` | v1 path | `logout` | WCC API gateway | Completes on outer `Logout` with nested `AgentLogoutSuccess` or `AgentLogoutFailed` |
594
+ | `PUT /v1/agents/session/state` with `StateChange` | v1 path | `stateChange` | WCC API gateway | Completes on outer `AgentStateChange` with nested `AgentStateChangeSuccess` or `AgentStateChangeFailed` |
595
+ | `POST /v1/agents/buddyList` with `BuddyAgents` | v1 path | `buddyAgents` | WCC API gateway | Completes on outer and nested `BuddyAgents`, or nested `BuddyAgentsRetrieveFailed` |
596
+ | `POST /v1/agents/reload` with an empty body | v1 path | `reload` | WCC API gateway | Completes on outer and nested `AgentReloginSuccess` or `AgentReloginFailed` |
597
+
598
+ Each agent method defines a `routing.req` (or, for `reload`, `routing.reqEmpty`) callback returning `url`,
599
+ `host: WCC_API_GATEWAY`, `data: p.data`, an `err` transformer, an optional `method`, `notifSuccess` with
600
+ a `bind` of outer `type` and nested `data: {type}` plus a `msg` type hint such as
601
+ `Agent.StationLoginSuccess`, and `notifFail` with its `bind` and an `errId` such as
602
+ `Service.aqm.agent.stationLoginFailed`; see [the factory](../index.ts). AqmReqs uses the given `method`,
603
+ or POST if data present, GET otherwise; only `stateChange` (PUT) and `buddyAgents` (POST) set it.
604
+
605
+ Key nested WebSocket binds use the actual outer/data constants, for example `CC_EVENTS.AGENT_STATION_LOGIN` with `data.type = CC_EVENTS.AGENT_STATION_LOGIN_SUCCESS` or `CC_EVENTS.AGENT_STATION_LOGIN_FAILED`. The package export index is in the [root module specification](../../../docs/README.md).
606
+
607
+ ## Caller-visible failure modes
608
+
609
+ | Condition | Signal or result | Caller behavior | Retry or recovery | Evidence |
610
+ | --------- | ---------------- | --------------- | ----------------- | -------- |
611
+ | AGENT_DN dial number fails the dial plan | `Error('INVALID_DIAL_NUMBER')` before any request; `error.data` has the field message and `fieldName` | Show `error.data.message` on the dial-number field | Correct the number and call again | `src/cc.ts`, `src/services/core/Utils.ts` |
612
+ | Extension or DN already in use by another session | Backend reason `DUPLICATE_LOCATION`: `Error('DUPLICATE_LOCATION')` with the in-use message for the login option | Show `error.data.message` on the `error.data.fieldName` field | Log in with another extension or DN | `src/services/core/Utils.ts`, `test/unit/spec/services/core/Utils.ts` |
613
+ | Other backend failure notification | `Error` whose message is the notification `data.reason`; for `stationLogin`, `error.data` has the generic login message and fieldName `generic` | Branch on `error.message` | Logs are uploaded with the failure tracking id | `src/cc.ts`, `src/services/core/Utils.ts` |
614
+ | HTTP rejection, timeout after 20000 ms, or the same request already pending | AqmReqs rejects with `Service.aqm.agent.stationLogin`, `Service.reqs.generic.failure`, `Service.aqm.reqs.Timeout`, or `Service.aqm.reqs.Pending` details; these carry no `data.reason`, so the wrapper throws `Error` with the message Error while performing followed by the method name | Treat the outcome as unknown and wait for an agent event; never synthesize success | Call again once the pending call has settled | `src/services/core/aqm-reqs.ts`, `src/services/core/Utils.ts` |
615
+ | Available requested while browser voice is not ready | `Error` whose message is `VOICE_CONNECTION_ERROR.NOT_READY`; no request sent | Wait for `voice:connectionStateChange` to report voice ready, or choose an Idle code | Call again when voice is ready | `src/cc.ts`, `test/unit/spec/cc.ts` |
616
+ | Silent relogin finds no agent session | Reason `AGENT_NOT_FOUND`; returns without throwing, error logging, or log upload | Nothing to handle; the agent is logged out | Call `stationLogin` | `src/cc.ts`, `src/services/core/Utils.ts` |
617
+ | Silent relogin does not run | `allowAutomatedRelogin` is false (it defaults to true) | Set `config.cc.allowAutomatedRelogin` to true in `Webex.init` | Relogin then runs on the next reconnect or register | `src/config.ts`, `src/cc.ts` |
618
+
619
+ For `stationLogin`, special error handling extracts field-specific messages: `getStationLoginErrorData`
620
+ in `src/services/core/Utils.ts` builds an `errorCodeMessageMap` in which `DUPLICATE_LOCATION` gives the
621
+ message 'This extension is already in use' for EXTENSION, a 'Dial number is in use' message for
622
+ AGENT_DN, and 'This value is already in use' otherwise, and `INVALID_DIAL_NUMBER` gives 'Enter a valid
623
+ dial number. For help, reach out to your administrator or support team.'; both set `fieldName` to the
624
+ `loginOption`, and any other reason gets a generic message with fieldName `generic`.
625
+
626
+ > **Host-application example:** `showStationLoginError` represents consumer-owned UI handling. SDK package implementation must use `LoggerProxy` and must not log raw runtime values.
627
+
628
+ ```typescript
629
+ try {
630
+ await cc.stationLogin(params);
631
+ } catch (error) {
632
+ showStationLoginError({
633
+ message: error.message,
634
+ fieldName: error.data?.fieldName,
635
+ fieldMessage: error.data?.message,
636
+ });
637
+ }
638
+ ```
639
+
640
+ ## Pitfalls and constraints
641
+
642
+ - `CC_EVENTS.AGENT_BUDDY_AGENTS` and `AGENT_BUDDY_AGENTS_SUCCESS` share the value `BuddyAgents`, so the buddy-list success bind is the same string at both levels.
643
+ - The `stationLogin` HTTP error transformer is marked `istanbul ignore next` and has no unit test.
644
+
645
+ ## Module-specific rules
646
+
647
+ - DO keep HTTP endpoint/method and WebSocket success/failure binds in the same routing factory definition.
648
+ - DO keep browser-calling registration/deregistration in ContactCenter around successful station operations.
649
+ - DON'T resolve an agent operation from HTTP acknowledgement.
650
+ - DON'T move automated relogin policy into the agent factory or ConnectionService.
651
+
652
+ ## Key design trade-off
653
+
654
+ | Chosen trade-off | Preserved invariant or benefit | Cost or limitation | Decision evidence |
655
+ | ---------------- | ------------------------------ | ------------------ | ----------------- |
656
+ | HTTP initiates each operation while the correlated WebSocket notification is the completion signal | Matches backend semantics: the agent state is final only when the backend reports it | Timeout/correlation complexity, and one pending request per bind key | `src/services/agent/index.ts`, `src/services/core/aqm-reqs.ts` |
657
+
658
+ ## Verification
659
+
660
+ Use `test/unit/spec/services/agent/index.ts` for the factory and `test/unit/spec/cc.ts` for public validation, metrics, calling, updateAgentProfile, and recovery ownership. Cover success, nested failure, HTTP rejection, and timeout without inventing a `deviceUpdate` factory method. The factory test only checks that each request function delegates to `req` or `reqEmpty`; endpoint, method, bind, and payload values are not asserted. Run `yarn workspace @webex/contact-center test:unit` from the workspace root.
661
+
662
+ | Requirement or invariant | Test level | Positive evidence | Negative or boundary evidence | Gap |
663
+ | ------------------------ | ---------- | ----------------- | ----------------------------- | --- |
664
+ | `AGENT-R-001` | Unit | `test/unit/spec/services/agent/index.ts` logout and stationLogin cases; `test/unit/spec/cc.ts` stationLogin and stationLogout success | `test/unit/spec/cc.ts` stationLogin and stationLogout error cases | Endpoints and binds not asserted |
665
+ | `AGENT-R-002` | Unit | `test/unit/spec/services/agent/index.ts` stateChange case; `test/unit/spec/cc.ts` setAgentStatus success | `test/unit/spec/cc.ts` setAgentStatus error case | PUT method and binds not asserted |
666
+ | `AGENT-R-003`, `AGENT-R-009` | Unit | `test/unit/spec/cc.ts` getBuddyAgents success, Transfer, and Consult cases | `test/unit/spec/cc.ts` getBuddyAgents error case | Endpoint not asserted |
667
+ | `AGENT-R-004`, `INV-003` | Unit | `test/unit/spec/cc.ts` silentRelogin cases | `test/unit/spec/cc.ts` AGENT_NOT_FOUND and relogin error cases; register with relogin disabled | None |
668
+ | `AGENT-R-005` | Unit | `test/unit/spec/cc.ts` updateAgentProfile cases | `test/unit/spec/cc.ts` logout and login failure cases | No assertion that `routingAgent.deviceUpdate` is absent |
669
+ | `AGENT-R-006` | Unit | `test/unit/spec/cc.ts` BROWSER login and cc.getDeviceId cases | `test/unit/spec/cc.ts` EXTENSION and AGENT_DN getDeviceId cases | None |
670
+ | `AGENT-R-007` | Unit | `test/unit/spec/services/core/Utils.ts` isValidDialNumber and getStationLoginErrorData cases | none found | No wrapper-level AGENT_DN rejection case |
671
+ | `AGENT-R-008` | Unit | `test/unit/spec/cc.ts` setAgentStatus Idle and non-browser cases | `test/unit/spec/cc.ts` browser-voice rejection case | None |
672
+ | `AGENT-R-010`, `INV-002` | Unit | `test/unit/spec/cc.ts` stationLogin and handleWebsocketMessage events mapped-payload cases | none found | None |
673
+ | `INV-001` | None | none found | none found | No test asserts the agent bind values |