@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.
- package/.sdd/manifest.json +24 -13
- package/ai-docs/ARCHITECTURE.md +1 -1
- package/ai-docs/CONTRACTS.md +19 -3
- package/ai-docs/SECURITY.md +1 -1
- package/ai-docs/SERVICE_STATE.md +4 -0
- package/ai-docs/contact-center-spec.md +50 -6
- package/ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md +362 -0
- package/ai-docs/features/contact-owner-change-refactor.md +78 -0
- package/dist/cc.js +757 -22
- package/dist/cc.js.map +1 -1
- package/dist/config.js +7 -0
- package/dist/config.js.map +1 -1
- package/dist/constants.js +23 -2
- package/dist/constants.js.map +1 -1
- package/dist/index.js +34 -12
- package/dist/index.js.map +1 -1
- package/dist/metrics/MetricsManager.js +16 -0
- package/dist/metrics/MetricsManager.js.map +1 -1
- package/dist/metrics/behavioral-events.js +110 -0
- package/dist/metrics/behavioral-events.js.map +1 -1
- package/dist/metrics/constants.js +33 -0
- package/dist/metrics/constants.js.map +1 -1
- package/dist/services/AddressBook.js +18 -15
- package/dist/services/AddressBook.js.map +1 -1
- package/dist/services/AnswerCallOnWebexService.js +202 -0
- package/dist/services/AnswerCallOnWebexService.js.map +1 -0
- package/dist/services/ApiAiAssistant.js +221 -11
- package/dist/services/ApiAiAssistant.js.map +1 -1
- package/dist/services/EntryPoint.js +46 -68
- package/dist/services/EntryPoint.js.map +1 -1
- package/dist/services/Queue.js +27 -22
- package/dist/services/Queue.js.map +1 -1
- package/dist/services/WebCallingService.js +10 -2
- package/dist/services/WebCallingService.js.map +1 -1
- package/dist/services/WebexCrossClientService.js +225 -0
- package/dist/services/WebexCrossClientService.js.map +1 -0
- package/dist/services/WxAppTelephonyMercurySync.js +111 -0
- package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
- package/dist/services/config/Util.js +46 -46
- package/dist/services/config/Util.js.map +1 -1
- package/dist/services/config/constants.js +34 -77
- package/dist/services/config/constants.js.map +1 -1
- package/dist/services/config/index.js +100 -226
- package/dist/services/config/index.js.map +1 -1
- package/dist/services/config/types.js +51 -18
- package/dist/services/config/types.js.map +1 -1
- package/dist/services/constants.js +11 -1
- package/dist/services/constants.js.map +1 -1
- package/dist/services/core/Err.js.map +1 -1
- package/dist/services/core/Utils.js +25 -1
- package/dist/services/core/Utils.js.map +1 -1
- package/dist/services/core/WebexRequest.js +6 -2
- package/dist/services/core/WebexRequest.js.map +1 -1
- package/dist/services/core/aqm-reqs.js +17 -11
- package/dist/services/core/aqm-reqs.js.map +1 -1
- package/dist/services/core/constants.js +9 -1
- package/dist/services/core/constants.js.map +1 -1
- package/dist/services/core/types.js.map +1 -1
- package/dist/services/core/websocket/WebSocketManager.js +17 -1
- package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
- package/dist/services/task/Task.js +275 -8
- package/dist/services/task/Task.js.map +1 -1
- package/dist/services/task/TaskFactory.js +11 -6
- package/dist/services/task/TaskFactory.js.map +1 -1
- package/dist/services/task/TaskManager.js +590 -42
- package/dist/services/task/TaskManager.js.map +1 -1
- package/dist/services/task/TaskUtils.js +11 -1
- package/dist/services/task/TaskUtils.js.map +1 -1
- package/dist/services/task/WebexCallingUtils.js +70 -0
- package/dist/services/task/WebexCallingUtils.js.map +1 -0
- package/dist/services/task/constants.js +14 -2
- package/dist/services/task/constants.js.map +1 -1
- package/dist/services/task/contact.js +29 -0
- package/dist/services/task/contact.js.map +1 -1
- package/dist/services/task/digital/Digital.js +4 -3
- package/dist/services/task/digital/Digital.js.map +1 -1
- package/dist/services/task/state-machine/TaskStateMachine.js +162 -53
- package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -1
- package/dist/services/task/state-machine/actions.js +6 -1
- package/dist/services/task/state-machine/actions.js.map +1 -1
- package/dist/services/task/state-machine/guards.js +7 -10
- package/dist/services/task/state-machine/guards.js.map +1 -1
- package/dist/services/task/state-machine/types.js.map +1 -1
- package/dist/services/task/state-machine/uiControlsComputer.js +118 -18
- package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -1
- package/dist/services/task/types.js +47 -1
- package/dist/services/task/types.js.map +1 -1
- package/dist/services/task/voice/Voice.js +477 -17
- package/dist/services/task/voice/Voice.js.map +1 -1
- package/dist/services/task/voice/WebRTC.js +6 -3
- package/dist/services/task/voice/WebRTC.js.map +1 -1
- package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
- package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
- package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
- package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
- package/dist/services/wxAppDiagnosticLogging.js +159 -0
- package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
- package/dist/services/wxAppTelephonyUtils.js +19 -0
- package/dist/services/wxAppTelephonyUtils.js.map +1 -0
- package/dist/types/cc.d.ts +102 -8
- package/dist/types/config.d.ts +7 -0
- package/dist/types/constants.d.ts +21 -0
- package/dist/types/index.d.ts +34 -15
- package/dist/types/metrics/MetricsManager.d.ts +6 -0
- package/dist/types/metrics/constants.d.ts +31 -0
- package/dist/types/services/AddressBook.d.ts +2 -1
- package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
- package/dist/types/services/ApiAiAssistant.d.ts +48 -4
- package/dist/types/services/EntryPoint.d.ts +7 -5
- package/dist/types/services/Queue.d.ts +5 -3
- package/dist/types/services/WebexCrossClientService.d.ts +32 -0
- package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
- package/dist/types/services/config/Util.d.ts +4 -8
- package/dist/types/services/config/constants.d.ts +28 -76
- package/dist/types/services/config/index.d.ts +16 -64
- package/dist/types/services/config/types.d.ts +146 -173
- package/dist/types/services/constants.d.ts +9 -0
- package/dist/types/services/core/Err.d.ts +2 -0
- package/dist/types/services/core/Utils.d.ts +10 -0
- package/dist/types/services/core/WebexRequest.d.ts +1 -0
- package/dist/types/services/core/constants.d.ts +7 -0
- package/dist/types/services/core/types.d.ts +2 -0
- package/dist/types/services/task/Task.d.ts +34 -5
- package/dist/types/services/task/TaskFactory.d.ts +4 -2
- package/dist/types/services/task/TaskUtils.d.ts +6 -0
- package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
- package/dist/types/services/task/constants.d.ts +12 -0
- package/dist/types/services/task/contact.d.ts +4 -0
- package/dist/types/services/task/digital/Digital.d.ts +4 -3
- package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +304 -56
- package/dist/types/services/task/state-machine/guards.d.ts +6 -5
- package/dist/types/services/task/state-machine/types.d.ts +9 -1
- package/dist/types/services/task/types.d.ts +192 -5
- package/dist/types/services/task/voice/Voice.d.ts +68 -11
- package/dist/types/services/task/voice/WebRTC.d.ts +5 -4
- package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
- package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
- package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
- package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
- package/dist/types/types.d.ts +80 -13
- package/dist/types/utils/PageCache.d.ts +20 -3
- package/dist/types.js +54 -8
- package/dist/types.js.map +1 -1
- package/dist/utils/PageCache.js +19 -5
- package/dist/utils/PageCache.js.map +1 -1
- package/dist/webex.js +9 -1
- package/dist/webex.js.map +1 -1
- package/package.json +10 -9
- package/src/cc.ts +969 -38
- package/src/config.ts +7 -0
- package/src/constants.ts +24 -0
- package/src/index.ts +39 -10
- package/src/metrics/MetricsManager.ts +16 -0
- package/src/metrics/ai-docs/metrics-spec.md +138 -21
- package/src/metrics/behavioral-events.ts +112 -0
- package/src/metrics/constants.ts +36 -0
- package/src/services/AddressBook.ts +17 -6
- package/src/services/AnswerCallOnWebexService.ts +239 -0
- package/src/services/ApiAiAssistant.ts +297 -13
- package/src/services/EntryPoint.ts +59 -60
- package/src/services/Queue.ts +29 -12
- package/src/services/WebCallingService.ts +16 -2
- package/src/services/WebexCrossClientService.ts +298 -0
- package/src/services/WxAppTelephonyMercurySync.ts +142 -0
- package/src/services/agent/ai-docs/AGENTS.md +1 -1
- package/src/services/agent/ai-docs/agent-spec.md +1 -0
- package/src/services/ai-docs/AGENTS.md +10 -10
- package/src/services/ai-docs/services-spec.md +25 -5
- package/src/services/config/Util.ts +52 -82
- package/src/services/config/ai-docs/AGENTS.md +35 -40
- package/src/services/config/ai-docs/ARCHITECTURE.md +90 -103
- package/src/services/config/ai-docs/config-spec.md +132 -132
- package/src/services/config/constants.ts +39 -85
- package/src/services/config/index.ts +116 -277
- package/src/services/config/types.ts +140 -195
- package/src/services/constants.ts +10 -0
- package/src/services/core/Err.ts +1 -0
- package/src/services/core/Utils.ts +28 -0
- package/src/services/core/WebexRequest.ts +3 -1
- package/src/services/core/ai-docs/core-spec.md +25 -11
- package/src/services/core/aqm-reqs.ts +18 -12
- package/src/services/core/constants.ts +8 -0
- package/src/services/core/types.ts +33 -1
- package/src/services/core/websocket/WebSocketManager.ts +26 -2
- package/src/services/task/Task.ts +386 -12
- package/src/services/task/TaskFactory.ts +33 -6
- package/src/services/task/TaskManager.ts +857 -41
- package/src/services/task/TaskUtils.ts +13 -0
- package/src/services/task/WebexCallingUtils.ts +136 -0
- package/src/services/task/ai-docs/ARCHITECTURE.md +1 -0
- package/src/services/task/ai-docs/task-spec.md +190 -8
- package/src/services/task/constants.ts +13 -0
- package/src/services/task/contact.ts +30 -0
- package/src/services/task/digital/Digital.ts +11 -4
- package/src/services/task/state-machine/TaskStateMachine.ts +235 -81
- package/src/services/task/state-machine/actions.ts +5 -2
- package/src/services/task/state-machine/ai-docs/AGENTS.md +6 -4
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +35 -16
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +103 -33
- package/src/services/task/state-machine/guards.ts +7 -10
- package/src/services/task/state-machine/types.ts +16 -1
- package/src/services/task/state-machine/uiControlsComputer.ts +206 -32
- package/src/services/task/types.ts +269 -4
- package/src/services/task/voice/Voice.ts +625 -17
- package/src/services/task/voice/WebRTC.ts +11 -4
- package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
- package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
- package/src/services/wxAppDiagnosticLogging.ts +286 -0
- package/src/services/wxAppTelephonyUtils.ts +14 -0
- package/src/types.ts +108 -13
- package/src/utils/AGENTS.md +21 -10
- package/src/utils/PageCache.ts +38 -5
- package/src/utils/ai-docs/utils-spec.md +21 -11
- package/src/webex.js +8 -0
- package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
- package/test/unit/spec/cc.ts +3408 -152
- package/test/unit/spec/index.ts +885 -0
- package/test/unit/spec/metrics/MetricsManager.ts +25 -0
- package/test/unit/spec/metrics/behavioral-events.ts +60 -0
- package/test/unit/spec/services/AddressBook.ts +37 -6
- package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
- package/test/unit/spec/services/ApiAiAssistant.ts +269 -8
- package/test/unit/spec/services/EntryPoint.ts +87 -40
- package/test/unit/spec/services/Queue.ts +123 -12
- package/test/unit/spec/services/WebCallingService.ts +38 -0
- package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
- package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
- package/test/unit/spec/services/config/Util.ts +501 -0
- package/test/unit/spec/services/config/index.ts +313 -543
- package/test/unit/spec/services/core/Utils.ts +22 -0
- package/test/unit/spec/services/core/WebexRequest.ts +8 -7
- package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
- package/test/unit/spec/services/core/websocket/WebSocketManager.ts +64 -14
- package/test/unit/spec/services/task/Task.ts +2257 -11
- package/test/unit/spec/services/task/TaskFactory.ts +56 -2
- package/test/unit/spec/services/task/TaskManager.ts +5559 -1493
- package/test/unit/spec/services/task/TaskUtils.ts +72 -0
- package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
- package/test/unit/spec/services/task/contact.ts +33 -0
- package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +1501 -92
- package/test/unit/spec/services/task/state-machine/guards.ts +210 -8
- package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +445 -7
- package/test/unit/spec/services/task/voice/Voice.ts +1710 -4
- package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
- package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
- package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
- package/test/unit/spec/wellnessSampleUtils.ts +288 -0
- package/typedoc.md +1 -1
- package/umd/contact-center.min.js +2 -2
- 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,
|
|
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`,
|
|
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->>
|
|
368
|
-
alt
|
|
369
|
-
WS
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
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
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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(
|
|
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
|
-
|
|
180
|
-
|
|
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 {
|
|
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 {
|
|
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
|
-
|
|
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}`,
|