@webex/contact-center 3.12.0-webex-services-ready.4 → 3.13.0

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 (250) hide show
  1. package/.sdd/manifest.json +24 -13
  2. package/ai-docs/ARCHITECTURE.md +1 -1
  3. package/ai-docs/CONTRACTS.md +19 -3
  4. package/ai-docs/SECURITY.md +1 -1
  5. package/ai-docs/SERVICE_STATE.md +4 -0
  6. package/ai-docs/contact-center-spec.md +50 -6
  7. package/ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md +362 -0
  8. package/ai-docs/features/contact-owner-change-refactor.md +78 -0
  9. package/dist/cc.js +757 -22
  10. package/dist/cc.js.map +1 -1
  11. package/dist/config.js +7 -0
  12. package/dist/config.js.map +1 -1
  13. package/dist/constants.js +23 -2
  14. package/dist/constants.js.map +1 -1
  15. package/dist/index.js +34 -12
  16. package/dist/index.js.map +1 -1
  17. package/dist/metrics/MetricsManager.js +16 -0
  18. package/dist/metrics/MetricsManager.js.map +1 -1
  19. package/dist/metrics/behavioral-events.js +110 -0
  20. package/dist/metrics/behavioral-events.js.map +1 -1
  21. package/dist/metrics/constants.js +33 -0
  22. package/dist/metrics/constants.js.map +1 -1
  23. package/dist/services/AddressBook.js +18 -15
  24. package/dist/services/AddressBook.js.map +1 -1
  25. package/dist/services/AnswerCallOnWebexService.js +202 -0
  26. package/dist/services/AnswerCallOnWebexService.js.map +1 -0
  27. package/dist/services/ApiAiAssistant.js +221 -11
  28. package/dist/services/ApiAiAssistant.js.map +1 -1
  29. package/dist/services/EntryPoint.js +46 -68
  30. package/dist/services/EntryPoint.js.map +1 -1
  31. package/dist/services/Queue.js +27 -22
  32. package/dist/services/Queue.js.map +1 -1
  33. package/dist/services/WebCallingService.js +10 -2
  34. package/dist/services/WebCallingService.js.map +1 -1
  35. package/dist/services/WebexCrossClientService.js +225 -0
  36. package/dist/services/WebexCrossClientService.js.map +1 -0
  37. package/dist/services/WxAppTelephonyMercurySync.js +111 -0
  38. package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
  39. package/dist/services/config/Util.js +46 -46
  40. package/dist/services/config/Util.js.map +1 -1
  41. package/dist/services/config/constants.js +34 -77
  42. package/dist/services/config/constants.js.map +1 -1
  43. package/dist/services/config/index.js +100 -226
  44. package/dist/services/config/index.js.map +1 -1
  45. package/dist/services/config/types.js +51 -18
  46. package/dist/services/config/types.js.map +1 -1
  47. package/dist/services/constants.js +11 -1
  48. package/dist/services/constants.js.map +1 -1
  49. package/dist/services/core/Err.js.map +1 -1
  50. package/dist/services/core/Utils.js +25 -1
  51. package/dist/services/core/Utils.js.map +1 -1
  52. package/dist/services/core/WebexRequest.js +6 -2
  53. package/dist/services/core/WebexRequest.js.map +1 -1
  54. package/dist/services/core/aqm-reqs.js +17 -11
  55. package/dist/services/core/aqm-reqs.js.map +1 -1
  56. package/dist/services/core/constants.js +9 -1
  57. package/dist/services/core/constants.js.map +1 -1
  58. package/dist/services/core/types.js.map +1 -1
  59. package/dist/services/core/websocket/WebSocketManager.js +17 -1
  60. package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
  61. package/dist/services/task/Task.js +275 -8
  62. package/dist/services/task/Task.js.map +1 -1
  63. package/dist/services/task/TaskFactory.js +11 -6
  64. package/dist/services/task/TaskFactory.js.map +1 -1
  65. package/dist/services/task/TaskManager.js +590 -42
  66. package/dist/services/task/TaskManager.js.map +1 -1
  67. package/dist/services/task/TaskUtils.js +11 -1
  68. package/dist/services/task/TaskUtils.js.map +1 -1
  69. package/dist/services/task/WebexCallingUtils.js +70 -0
  70. package/dist/services/task/WebexCallingUtils.js.map +1 -0
  71. package/dist/services/task/constants.js +14 -2
  72. package/dist/services/task/constants.js.map +1 -1
  73. package/dist/services/task/contact.js +29 -0
  74. package/dist/services/task/contact.js.map +1 -1
  75. package/dist/services/task/digital/Digital.js +4 -3
  76. package/dist/services/task/digital/Digital.js.map +1 -1
  77. package/dist/services/task/state-machine/TaskStateMachine.js +162 -53
  78. package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -1
  79. package/dist/services/task/state-machine/actions.js +6 -1
  80. package/dist/services/task/state-machine/actions.js.map +1 -1
  81. package/dist/services/task/state-machine/guards.js +7 -10
  82. package/dist/services/task/state-machine/guards.js.map +1 -1
  83. package/dist/services/task/state-machine/types.js.map +1 -1
  84. package/dist/services/task/state-machine/uiControlsComputer.js +118 -18
  85. package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -1
  86. package/dist/services/task/types.js +47 -1
  87. package/dist/services/task/types.js.map +1 -1
  88. package/dist/services/task/voice/Voice.js +477 -17
  89. package/dist/services/task/voice/Voice.js.map +1 -1
  90. package/dist/services/task/voice/WebRTC.js +6 -3
  91. package/dist/services/task/voice/WebRTC.js.map +1 -1
  92. package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
  93. package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
  94. package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
  95. package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
  96. package/dist/services/wxAppDiagnosticLogging.js +159 -0
  97. package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
  98. package/dist/services/wxAppTelephonyUtils.js +19 -0
  99. package/dist/services/wxAppTelephonyUtils.js.map +1 -0
  100. package/dist/types/cc.d.ts +102 -8
  101. package/dist/types/config.d.ts +7 -0
  102. package/dist/types/constants.d.ts +21 -0
  103. package/dist/types/index.d.ts +34 -15
  104. package/dist/types/metrics/MetricsManager.d.ts +6 -0
  105. package/dist/types/metrics/constants.d.ts +31 -0
  106. package/dist/types/services/AddressBook.d.ts +2 -1
  107. package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
  108. package/dist/types/services/ApiAiAssistant.d.ts +48 -4
  109. package/dist/types/services/EntryPoint.d.ts +7 -5
  110. package/dist/types/services/Queue.d.ts +5 -3
  111. package/dist/types/services/WebexCrossClientService.d.ts +32 -0
  112. package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
  113. package/dist/types/services/config/Util.d.ts +4 -8
  114. package/dist/types/services/config/constants.d.ts +28 -76
  115. package/dist/types/services/config/index.d.ts +16 -64
  116. package/dist/types/services/config/types.d.ts +146 -173
  117. package/dist/types/services/constants.d.ts +9 -0
  118. package/dist/types/services/core/Err.d.ts +2 -0
  119. package/dist/types/services/core/Utils.d.ts +10 -0
  120. package/dist/types/services/core/WebexRequest.d.ts +1 -0
  121. package/dist/types/services/core/constants.d.ts +7 -0
  122. package/dist/types/services/core/types.d.ts +2 -0
  123. package/dist/types/services/task/Task.d.ts +34 -5
  124. package/dist/types/services/task/TaskFactory.d.ts +4 -2
  125. package/dist/types/services/task/TaskUtils.d.ts +6 -0
  126. package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
  127. package/dist/types/services/task/constants.d.ts +12 -0
  128. package/dist/types/services/task/contact.d.ts +4 -0
  129. package/dist/types/services/task/digital/Digital.d.ts +4 -3
  130. package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +304 -56
  131. package/dist/types/services/task/state-machine/guards.d.ts +6 -5
  132. package/dist/types/services/task/state-machine/types.d.ts +9 -1
  133. package/dist/types/services/task/types.d.ts +192 -5
  134. package/dist/types/services/task/voice/Voice.d.ts +68 -11
  135. package/dist/types/services/task/voice/WebRTC.d.ts +5 -4
  136. package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
  137. package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
  138. package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
  139. package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
  140. package/dist/types/types.d.ts +80 -13
  141. package/dist/types/utils/PageCache.d.ts +20 -3
  142. package/dist/types.js +54 -8
  143. package/dist/types.js.map +1 -1
  144. package/dist/utils/PageCache.js +19 -5
  145. package/dist/utils/PageCache.js.map +1 -1
  146. package/dist/webex.js +9 -1
  147. package/dist/webex.js.map +1 -1
  148. package/package.json +10 -9
  149. package/src/cc.ts +969 -38
  150. package/src/config.ts +7 -0
  151. package/src/constants.ts +24 -0
  152. package/src/index.ts +39 -10
  153. package/src/metrics/MetricsManager.ts +16 -0
  154. package/src/metrics/ai-docs/metrics-spec.md +138 -21
  155. package/src/metrics/behavioral-events.ts +112 -0
  156. package/src/metrics/constants.ts +36 -0
  157. package/src/services/AddressBook.ts +17 -6
  158. package/src/services/AnswerCallOnWebexService.ts +239 -0
  159. package/src/services/ApiAiAssistant.ts +297 -13
  160. package/src/services/EntryPoint.ts +59 -60
  161. package/src/services/Queue.ts +29 -12
  162. package/src/services/WebCallingService.ts +16 -2
  163. package/src/services/WebexCrossClientService.ts +298 -0
  164. package/src/services/WxAppTelephonyMercurySync.ts +142 -0
  165. package/src/services/agent/ai-docs/AGENTS.md +1 -1
  166. package/src/services/agent/ai-docs/agent-spec.md +1 -0
  167. package/src/services/ai-docs/AGENTS.md +10 -10
  168. package/src/services/ai-docs/services-spec.md +25 -5
  169. package/src/services/config/Util.ts +52 -82
  170. package/src/services/config/ai-docs/AGENTS.md +35 -40
  171. package/src/services/config/ai-docs/ARCHITECTURE.md +90 -103
  172. package/src/services/config/ai-docs/config-spec.md +132 -132
  173. package/src/services/config/constants.ts +39 -85
  174. package/src/services/config/index.ts +116 -277
  175. package/src/services/config/types.ts +140 -195
  176. package/src/services/constants.ts +10 -0
  177. package/src/services/core/Err.ts +1 -0
  178. package/src/services/core/Utils.ts +28 -0
  179. package/src/services/core/WebexRequest.ts +3 -1
  180. package/src/services/core/ai-docs/core-spec.md +25 -11
  181. package/src/services/core/aqm-reqs.ts +18 -12
  182. package/src/services/core/constants.ts +8 -0
  183. package/src/services/core/types.ts +33 -1
  184. package/src/services/core/websocket/WebSocketManager.ts +26 -2
  185. package/src/services/task/Task.ts +386 -12
  186. package/src/services/task/TaskFactory.ts +33 -6
  187. package/src/services/task/TaskManager.ts +857 -41
  188. package/src/services/task/TaskUtils.ts +13 -0
  189. package/src/services/task/WebexCallingUtils.ts +136 -0
  190. package/src/services/task/ai-docs/ARCHITECTURE.md +1 -0
  191. package/src/services/task/ai-docs/task-spec.md +190 -8
  192. package/src/services/task/constants.ts +13 -0
  193. package/src/services/task/contact.ts +30 -0
  194. package/src/services/task/digital/Digital.ts +11 -4
  195. package/src/services/task/state-machine/TaskStateMachine.ts +235 -81
  196. package/src/services/task/state-machine/actions.ts +5 -2
  197. package/src/services/task/state-machine/ai-docs/AGENTS.md +6 -4
  198. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +35 -16
  199. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +103 -33
  200. package/src/services/task/state-machine/guards.ts +7 -10
  201. package/src/services/task/state-machine/types.ts +16 -1
  202. package/src/services/task/state-machine/uiControlsComputer.ts +206 -32
  203. package/src/services/task/types.ts +269 -4
  204. package/src/services/task/voice/Voice.ts +625 -17
  205. package/src/services/task/voice/WebRTC.ts +11 -4
  206. package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
  207. package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
  208. package/src/services/wxAppDiagnosticLogging.ts +286 -0
  209. package/src/services/wxAppTelephonyUtils.ts +14 -0
  210. package/src/types.ts +108 -13
  211. package/src/utils/AGENTS.md +21 -10
  212. package/src/utils/PageCache.ts +38 -5
  213. package/src/utils/ai-docs/utils-spec.md +21 -11
  214. package/src/webex.js +8 -0
  215. package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
  216. package/test/unit/spec/cc.ts +3408 -152
  217. package/test/unit/spec/index.ts +885 -0
  218. package/test/unit/spec/metrics/MetricsManager.ts +25 -0
  219. package/test/unit/spec/metrics/behavioral-events.ts +60 -0
  220. package/test/unit/spec/services/AddressBook.ts +37 -6
  221. package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
  222. package/test/unit/spec/services/ApiAiAssistant.ts +269 -8
  223. package/test/unit/spec/services/EntryPoint.ts +87 -40
  224. package/test/unit/spec/services/Queue.ts +123 -12
  225. package/test/unit/spec/services/WebCallingService.ts +38 -0
  226. package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
  227. package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
  228. package/test/unit/spec/services/config/Util.ts +501 -0
  229. package/test/unit/spec/services/config/index.ts +313 -543
  230. package/test/unit/spec/services/core/Utils.ts +22 -0
  231. package/test/unit/spec/services/core/WebexRequest.ts +8 -7
  232. package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
  233. package/test/unit/spec/services/core/websocket/WebSocketManager.ts +64 -14
  234. package/test/unit/spec/services/task/Task.ts +2257 -11
  235. package/test/unit/spec/services/task/TaskFactory.ts +56 -2
  236. package/test/unit/spec/services/task/TaskManager.ts +5559 -1493
  237. package/test/unit/spec/services/task/TaskUtils.ts +72 -0
  238. package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
  239. package/test/unit/spec/services/task/contact.ts +33 -0
  240. package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +1501 -92
  241. package/test/unit/spec/services/task/state-machine/guards.ts +210 -8
  242. package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +445 -7
  243. package/test/unit/spec/services/task/voice/Voice.ts +1710 -4
  244. package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
  245. package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
  246. package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
  247. package/test/unit/spec/wellnessSampleUtils.ts +288 -0
  248. package/typedoc.md +1 -1
  249. package/umd/contact-center.min.js +2 -2
  250. package/umd/contact-center.min.js.map +1 -1
@@ -37,13 +37,13 @@ The Core service provides the foundational infrastructure layer that all other s
37
37
 
38
38
  | Component | File | Description |
39
39
  |---|---|---|
40
- | `WebSocketManager` | [`WebSocketManager.ts`](../websocket/WebSocketManager.ts) | Manages the WebSocket connection lifecycle including initialization, message dispatch, and graceful shutdown. Emits `message` events for incoming data and `socketClose` when the connection drops while reconnect is allowed. |
40
+ | `WebSocketManager` | [`WebSocketManager.ts`](../websocket/WebSocketManager.ts) | Manages the WebSocket connection lifecycle including initialization, message dispatch, and graceful shutdown. Validates the subscribe/register `webSocketUrl` against the RoutingNotifs allow-list before opening a socket. Emits `message` events for incoming data and `socketClose` when the connection drops while reconnect is allowed. |
41
41
  | `ConnectionService` | [`connection-service.ts`](../websocket/connection-service.ts) | Orchestrates reconnection logic and keepalive heartbeats on top of `WebSocketManager`. Detects connection loss/recovery and emits `connectionLost` details; ContactCenter owns any `silentRelogin()` policy. |
42
42
  | `WebexRequest` | [`WebexRequest.ts`](../WebexRequest.ts) | Singleton HTTP client that forwards service/resource/method/body options to the authenticated host request API and provides `uploadLogs` diagnostics. |
43
43
  | `AqmReqs` | [`aqm-reqs.ts`](../aqm-reqs.ts) | Factory for creating request methods that send HTTP requests and wait for correlated WebSocket notifications (success or failure). Used by routing and task services to implement their API methods. |
44
44
  | `Utils` | [`Utils.ts`](../Utils.ts) | Shared utility functions including `getErrorDetails()` for standardized error handling, `generateTaskErrorObject()` for task-specific errors, and `createErrDetailsObject()` for constructing error detail objects. |
45
45
  | `Err` | [`Err.ts`](../Err.ts) | Error class definitions. `Err.Details` carries structured error metadata (status, type, trackingId) for consistent error propagation. |
46
- | `constants` | [`constants.ts`](../constants.ts) | Timeout values, interval durations, participant types, interaction states, and method name constants used throughout the core layer. Any new constants for core should be defined here. |
46
+ | `constants` | [`constants.ts`](../constants.ts) | Timeout values, interval durations, participant types, interaction states, method name constants, and the `ALLOWED_ROUTING_NOTIFS_DOMAINS` WebSocket host allow-list used throughout the core layer. Any new constants for core should be defined here. |
47
47
 
48
48
  ## Purpose / Responsibility
49
49
  Own authenticated HTTP, realtime WebSocket lifecycle, AQM request correlation, reconnect/keepalive behavior, and shared error normalization.
@@ -259,12 +259,14 @@ connectionService.on('connectionLost', (details: ConnectionLostDetails) => {
259
259
  | CORE-R-004 | ConnectionService must emit transport-state details and retry `initWebSocket({body, resource})`; ContactCenter owns relogin policy. | Separating transport detection from agent recovery prevents Core from mutating package-level session state. | `src/services/core/websocket/connection-service.ts` | `test/unit/spec/services/core/websocket/connection-service.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
260
260
  | CORE-R-005 | The keepalive worker must use the configured 4-second interval and 16-second close-socket timeout; AQM defaults to 20 seconds unless disabled/overridden. | Accurate timing is required for predictable recovery and request failure behavior. | `src/services/core/constants.ts` | `test/unit/spec/services/core/websocket/WebSocketManager.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
261
261
  | CORE-R-006 | Treat Core timeout, keepalive, and recovery constants as fixed behavior controls, not rollout flags; Core owns no feature-gate evaluation. | Conflating operational constants with rollout policy could disable transport or correlation paths unexpectedly. | `src/services/core/constants.ts`, `src/services/index.ts` | `test/unit/spec/services/core/websocket/WebSocketManager.ts` | None; rollout applicability is explicitly N/A for Core. | PRESENT |
262
+ | CORE-R-007 | AQM routing-failure logging never emits the raw routing message payload or error verbatim; the failure-bind path logs only a fixed redacted diagnostic regardless of `redactSensitiveLogs`. When an AQM request additionally sets `redactSensitiveLogs`, timeout logs must also omit the request URL, bind key, and response while preserving settlement and cleanup behavior. | Dynamic request paths and routing messages can contain participant identifiers or phone numbers that must not enter diagnostic logs. | `src/services/core/aqm-reqs.ts`, `src/services/core/types.ts` | `test/unit/spec/services/core/aqm-reqs.ts` | The timeout flag is internal and opt-in; ordinary AQM logging remains backward compatible while routing-failure logging is unconditionally redacted. | PRESENT |
263
+ | CORE-R-008 | `WebSocketManager` opens a socket only for a subscribe/register `webSocketUrl` that parses as a `wss` URL whose host equals, or is a subdomain of, an entry in `ALLOWED_ROUTING_NOTIFS_DOMAINS`; a malformed, non-`wss`, or non-allow-listed URL is rejected with an error and no socket is opened. | A server-controlled subscribe response could otherwise direct the realtime connection to an untrusted or non-secure endpoint. | `src/services/core/websocket/WebSocketManager.ts`, `src/services/core/constants.ts` | `test/unit/spec/services/core/websocket/WebSocketManager.ts` | The allow-list is a fixed domain set; subdomain matching is exact suffix matching on the parsed hostname. | PRESENT |
262
264
 
263
265
  ## Design Overview
264
266
  Core separates four responsibilities:
265
267
 
266
268
  1. `WebexRequest` wraps the authenticated host request API and service-catalog routing.
267
- 2. `WebSocketManager` registers a subscription using both `body` and `resource`, connects the socket, owns the keepalive worker, and emits raw messages/socket lifecycle events.
269
+ 2. `WebSocketManager` registers a subscription using both `body` and `resource`, validates the returned `webSocketUrl` against the `ALLOWED_ROUTING_NOTIFS_DOMAINS` allow-list before connecting the socket, owns the keepalive worker, and emits raw messages/socket lifecycle events.
268
270
  3. `AqmReqs` registers bind matchers on the primary WebSocket, sends HTTP through WebexRequest, and settles requests only from matching notifications, HTTP failure, or timeout.
269
271
  4. `ConnectionService` observes message/socket liveness, emits connection-state details, and retries socket initialization. ContactCenter listens to those details and owns optional silent relogin.
270
272
 
@@ -293,7 +295,7 @@ const setState = aqmReqs.req((p: {data: Agent.StateChange}) => ({
293
295
  await setState({data: stateChangePayload});
294
296
  ```
295
297
 
296
- `CLOSE_SOCKET_TIMEOUT` is 16000 ms. `CONNECTIVITY_CHECK_INTERVAL` drives reconnect attempts separately. `TIMEOUT_REQ` is the 20000 ms default AQM timeout; `WEBSOCKET_EVENT_TIMEOUT` is not the active AqmReqs default.
298
+ `CLOSE_SOCKET_TIMEOUT` is 16000 ms. `CONNECTIVITY_CHECK_INTERVAL` drives reconnect attempts separately. `TIMEOUT_REQ` is the 20000 ms default AQM timeout; `WEBSOCKET_EVENT_TIMEOUT` is not the active AqmReqs default. Routing-failure diagnostics are always redacted to a fixed message that omits the raw payload and error. A request configuration may additionally set internal `redactSensitiveLogs: true` to redact timeout diagnostics (request URL, bind key, and response); neither redaction changes correlation, errors, timing, or cleanup.
297
299
 
298
300
  ## Data Flow
299
301
  ```mermaid
@@ -364,12 +366,17 @@ sequenceDiagram
364
366
  Caller->>WSM: initWebSocket({body, resource})
365
367
  WSM->>Host: register(body, resource)
366
368
  Host-->>WSM: WebSocket URL/subscription
367
- WSM->>WS: connect()
368
- alt welcome
369
- WS-->>WSM: Welcome event
370
- WSM-->>Caller: WelcomeResponse
371
- else register/connect failure
372
- WSM-->>Caller: throw error
369
+ WSM->>WSM: validate webSocketUrl against wss + allow-list
370
+ alt allow-listed wss URL
371
+ WSM->>WS: connect()
372
+ alt welcome
373
+ WS-->>WSM: Welcome event
374
+ WSM-->>Caller: WelcomeResponse
375
+ else connect failure
376
+ WSM-->>Caller: throw error
377
+ end
378
+ else malformed / non-wss / non-allow-listed URL
379
+ WSM-->>Caller: throw error (no socket opened)
373
380
  end
374
381
  ```
375
382
 
@@ -447,6 +454,8 @@ WebSocketManager owns socket/welcome/worker state. AqmReqs owns pending success/
447
454
 
448
455
  ## Business Rules & Invariants
449
456
  - Core must preserve its typed public/event contracts and must not invent backend states or responses. Enforced in `src/services/core/WebexRequest.ts`.
457
+ - A subscribe/register `webSocketUrl` is trusted only when it is a `wss` URL on the `ALLOWED_ROUTING_NOTIFS_DOMAINS` allow-list; otherwise `WebSocketManager` throws and never opens a socket. Enforced in `src/services/core/websocket/WebSocketManager.ts`.
458
+ - AQM routing-failure logs never contain the raw routing payload or error verbatim. Enforced in `src/services/core/aqm-reqs.ts`.
450
459
  - Rollout applicability is N/A for Core: keepalive, timeout, and reconnect constants control behavior, while Services constructs Core without a feature gate.
451
460
 
452
461
  ## Concurrency & Reactive Flow
@@ -467,7 +476,7 @@ stateDiagram-v2
467
476
  ```
468
477
 
469
478
  ## Protocol / Wire Format
470
- `WebSocketManager.initWebSocket` accepts `{body: SubscribeRequest, resource: string}`. Subscription uses the host Webex request API; AqmReqs operational HTTP uses the WebexRequest wrapper. AQM request configs carry `host`, `url`, optional `method`/`data`, `notifSuccess.bind`, optional `notifFail.bind`, optional cancel bind, and optional timeout. HTTP acknowledgement never substitutes for the matching WebSocket operation result.
479
+ `WebSocketManager.initWebSocket` accepts `{body: SubscribeRequest, resource: string}`. Subscription uses the host Webex request API; the returned `webSocketUrl` must be a `wss` URL on the `ALLOWED_ROUTING_NOTIFS_DOMAINS` allow-list or the socket is not opened. AqmReqs operational HTTP uses the WebexRequest wrapper. AQM request configs carry `host`, `url`, optional `method`/`data`, `notifSuccess.bind`, optional `notifFail.bind`, optional cancel bind, and optional timeout. HTTP acknowledgement never substitutes for the matching WebSocket operation result.
471
480
 
472
481
  ## Error Handling & Failure Modes
473
482
  | Condition | Signal (error/code/result) | Caller recovery |
@@ -711,11 +720,14 @@ export const generateTaskErrorObject = (
711
720
  ## Pitfalls
712
721
  - `initWebSocket` requires both `body` and `resource`; omitting `resource` registers against no durable subscription endpoint.
713
722
  - AqmReqs installs notification binds before HTTP and never resolves from acknowledgement; duplicate binds, timeout, and cleanup ordering are correctness-critical.
723
+ - AQM routing-failure logs are always redacted; sensitive AQM configurations must also use the opt-in `redactSensitiveLogs` flag so dynamic URLs and responses are not included in timeout logs.
724
+ - Do not open the WebSocket directly from a subscribe/register response; the `webSocketUrl` must first pass `wss` scheme and allow-listed host validation.
714
725
  - Keepalive closure (16 seconds), lost-connection detection (8 seconds), reconnect interval (5 seconds), and recovery timeout (50 seconds) are separate controls and must not be conflated.
715
726
 
716
727
  ## Module Do's / Don'ts
717
728
  - DO keep authentication and service resolution in the host Webex request layer; `WebexRequest.request` is a thin delegating wrapper.
718
729
  - DO mask authorization headers in the `AqmReqs` HTTP-error/timeout paths before those details are logged or surfaced.
730
+ - DO enable `redactSensitiveLogs` for AQM requests whose dynamic URL or event payload can contain identity/PII.
719
731
  - DO clear success/failure/cancel bind entries together when an AQM request settles.
720
732
  - DON'T move silent-relogin policy into ConnectionService; it emits transport state only.
721
733
  - DON'T treat timeout constants as feature flags or reuse one timer for another lifecycle purpose.
@@ -747,6 +759,8 @@ Unit tests mirror module paths under `test/unit/spec/services/core`. Preserve po
747
759
  | `CORE-R-004` | `test/unit/spec/services/core/websocket/connection-service.ts` | None. |
748
760
  | `CORE-R-005` | `test/unit/spec/services/core/websocket/WebSocketManager.ts` | Keep timer-value assertions synchronized with constants. |
749
761
  | `CORE-R-006` | `test/unit/spec/services/core/websocket/WebSocketManager.ts` | Feature-gate absence is verified from construction/source rather than a dedicated negative test. |
762
+ | `CORE-R-007` | `test/unit/spec/services/core/aqm-reqs.ts` | None. |
763
+ | `CORE-R-008` | `test/unit/spec/services/core/websocket/WebSocketManager.ts` | None. |
750
764
 
751
765
  ## Traceability
752
766
  - Repo architecture: `../../../../ai-docs/ARCHITECTURE.md` · Registry: `../../../../ai-docs/SPEC_INDEX.md`
@@ -117,16 +117,15 @@ export default class AqmReqs {
117
117
  clear();
118
118
  const notifFail = c.notifFail!;
119
119
  if ('errId' in notifFail) {
120
- LoggerProxy.log(`Routing request failed: ${JSON.stringify(msg)}`, {
121
- module: AQM_REQS_FILE,
122
- method: METHODS.CREATE_PROMISE,
123
- });
124
- const eerr = new Err.Details(notifFail.errId, msg as any);
125
- LoggerProxy.log(`Routing request failed: ${eerr}`, {
120
+ const error = new Err.Details(notifFail.errId, msg as any);
121
+
122
+ // The raw routing-failure payload/error is never logged verbatim; only a
123
+ // redacted, non-sensitive diagnostic is emitted regardless of redactSensitiveLogs.
124
+ LoggerProxy.log('Routing request failed (sensitive details redacted)', {
126
125
  module: AQM_REQS_FILE,
127
126
  method: METHODS.CREATE_PROMISE,
128
127
  });
129
- reject(eerr);
128
+ reject(error);
130
129
  } else {
131
130
  reject(notifFail.err(msg as any));
132
131
  }
@@ -176,13 +175,20 @@ export default class AqmReqs {
176
175
  if (response?.headers) {
177
176
  response.headers.Authorization = '*';
178
177
  }
179
- LoggerProxy.error(
180
- `Routing request timeout${keySuccess}${JSON.stringify(response)}${c.url}`,
181
- {
178
+ if (c.redactSensitiveLogs) {
179
+ LoggerProxy.error('Routing request timeout (sensitive details redacted)', {
182
180
  module: AQM_REQS_FILE,
183
181
  method: METHODS.CREATE_PROMISE,
184
- }
185
- );
182
+ });
183
+ } else {
184
+ LoggerProxy.error(
185
+ `Routing request timeout${keySuccess}${JSON.stringify(response)}${c.url}`,
186
+ {
187
+ module: AQM_REQS_FILE,
188
+ method: METHODS.CREATE_PROMISE,
189
+ }
190
+ );
191
+ }
186
192
  reject(
187
193
  new Err.Details('Service.aqm.reqs.Timeout', {
188
194
  key: keySuccess,
@@ -80,6 +80,14 @@ export const PARTICIPANT_TYPES = {
80
80
  /** Interaction state for consultation */
81
81
  export const STATE_CONSULT = 'consult';
82
82
 
83
+ /**
84
+ * Trusted domains for the RoutingNotifs WebSocket connection. A `webSocketUrl` returned by the
85
+ * subscribe/register API is only opened when its hostname matches one of these domains exactly
86
+ * or is a subdomain of one of them.
87
+ * @ignore
88
+ */
89
+ export const ALLOWED_ROUTING_NOTIFS_DOMAINS = ['cisco.com', 'ciscoccservice.com'];
90
+
83
91
  // Method names for core services
84
92
  export const METHODS = {
85
93
  // WebexRequest methods
@@ -1,4 +1,10 @@
1
- import {HTTP_METHODS, RequestBody, WebexRequestPayload} from '../../types';
1
+ import {
2
+ AIAssistantEventName,
3
+ AIAssistantEventType,
4
+ HTTP_METHODS,
5
+ RequestBody,
6
+ WebexRequestPayload,
7
+ } from '../../types';
2
8
  import * as Err from './Err';
3
9
  import {Msg} from './GlobalTypes';
4
10
 
@@ -20,6 +26,8 @@ export type Req<TRes, TErr> = {
20
26
  url: string;
21
27
  host?: string;
22
28
  method?: HTTP_METHODS;
29
+ /** Suppress request URLs and routing payloads from AQM logs for sensitive operations. */
30
+ redactSensitiveLogs?: boolean;
23
31
  err?:
24
32
  | ((errObj: WebexRequestPayload) => Err.Details<'Service.reqs.generic.failure'>)
25
33
  | Err.IdsMessage
@@ -46,3 +54,27 @@ export type ConfEmpty<TRes, TErr> = () => Req<TRes, TErr>;
46
54
  export type Res<TRes, TReq> = (p: TReq, cbRes?: CbRes<TRes>) => Promise<TRes>;
47
55
  export type ResEmpty<TRes> = (cbRes?: CbRes<TRes>) => Promise<TRes>;
48
56
  export type CbRes<TRes> = (res: any) => void | TRes;
57
+
58
+ /** @internal Pending request completed by a correlated RTD response. */
59
+ export type PendingRtdRequest<T> = {
60
+ correlationId: string;
61
+ rtdEventType: string;
62
+ timeoutId?: ReturnType<typeof setTimeout>;
63
+ resolve: (payload: T) => void;
64
+ reject: (error: Error) => void;
65
+ };
66
+
67
+ /** @internal Request configuration for an event completed by an RTD response. */
68
+ export type RtdRequestOptions = Readonly<{
69
+ correlationId: string;
70
+ rtdEventType: string;
71
+ timeoutMs: number;
72
+ createTimeoutError: () => Error;
73
+ agentId: string;
74
+ interactionId: string;
75
+ eventType: AIAssistantEventType;
76
+ eventName: AIAssistantEventName;
77
+ eventMetaData?: Record<string, unknown>;
78
+ publishTimestamp?: number;
79
+ timeout?: number;
80
+ }>;
@@ -5,8 +5,14 @@ import {ConnectionLostDetails} from './types';
5
5
  import {CC_EVENTS, SubscribeResponse, WelcomeResponse} from '../../config/types';
6
6
  import LoggerProxy from '../../../logger-proxy';
7
7
  import workerScript from './keepalive.worker';
8
- import {KEEPALIVE_WORKER_INTERVAL, CLOSE_SOCKET_TIMEOUT, METHODS} from '../constants';
8
+ import {
9
+ KEEPALIVE_WORKER_INTERVAL,
10
+ CLOSE_SOCKET_TIMEOUT,
11
+ METHODS,
12
+ ALLOWED_ROUTING_NOTIFS_DOMAINS,
13
+ } from '../constants';
9
14
  import {WEB_SOCKET_MANAGER_FILE} from '../../../constants';
15
+ import {isAllowedUrlHost} from '../Utils';
10
16
 
11
17
  /**
12
18
  * WebSocketManager handles the WebSocket connection for Contact Center operations.
@@ -107,7 +113,25 @@ export class WebSocketManager extends EventEmitter {
107
113
  body: connectionConfig,
108
114
  headers: isIntEnv && orgId ? {'X-ORGANIZATION-ID': orgId} : undefined,
109
115
  });
110
- this.url = subscribeResponse.body.webSocketUrl;
116
+ const {webSocketUrl} = subscribeResponse.body;
117
+
118
+ // Only a `wss` URL whose hostname is, or is a subdomain of, one of the allow-listed
119
+ // RoutingNotifs domains is considered trusted.
120
+ let isWssUrl = false;
121
+
122
+ try {
123
+ isWssUrl = !!webSocketUrl && new URL(webSocketUrl).protocol === 'wss:';
124
+ } catch (error) {
125
+ isWssUrl = false;
126
+ }
127
+
128
+ if (!isWssUrl || !isAllowedUrlHost(webSocketUrl, ALLOWED_ROUTING_NOTIFS_DOMAINS)) {
129
+ throw new Error(
130
+ 'Rejected webSocketUrl from RoutingNotifs registration: scheme or host not allow-listed'
131
+ );
132
+ }
133
+
134
+ this.url = webSocketUrl;
111
135
  } catch (e) {
112
136
  LoggerProxy.error(
113
137
  `Register API Failed, Request to RoutingNotifs websocket registration API failed ${e}`,