@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.
- package/.repo-context.json +704 -0
- package/.sdd/manifest.json +1613 -0
- package/AGENTS.md +969 -0
- package/dist/cc.js +1102 -47
- package/dist/cc.js.map +1 -1
- package/dist/config.js +13 -0
- package/dist/config.js.map +1 -1
- package/dist/constants.js +46 -3
- package/dist/constants.js.map +1 -1
- package/dist/index.js +86 -17
- 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 +211 -0
- package/dist/metrics/behavioral-events.js.map +1 -1
- package/dist/metrics/constants.js +58 -4
- 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 +369 -14
- 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/UserPreference.js +427 -0
- package/dist/services/UserPreference.js.map +1 -0
- package/dist/services/WebCallingService.js +287 -37
- 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 +48 -48
- package/dist/services/config/Util.js.map +1 -1
- package/dist/services/config/constants.js +57 -79
- 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 +100 -40
- package/dist/services/config/types.js.map +1 -1
- package/dist/services/constants.js +19 -1
- package/dist/services/constants.js.map +1 -1
- package/dist/services/core/Err.js.map +1 -1
- package/dist/services/core/Utils.js +131 -32
- 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 +26 -6
- package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
- package/dist/services/core/websocket/connection-service.js +3 -1
- package/dist/services/core/websocket/connection-service.js.map +1 -1
- package/dist/services/core/websocket/types.js.map +1 -1
- package/dist/services/index.js +6 -0
- package/dist/services/index.js.map +1 -1
- package/dist/services/task/Task.js +955 -0
- package/dist/services/task/Task.js.map +1 -0
- package/dist/services/task/TaskFactory.js +50 -0
- package/dist/services/task/TaskFactory.js.map +1 -0
- package/dist/services/task/TaskManager.js +1275 -504
- package/dist/services/task/TaskManager.js.map +1 -1
- package/dist/services/task/TaskUtils.js +221 -27
- 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 +22 -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/dialer.js +78 -0
- package/dist/services/task/dialer.js.map +1 -1
- package/dist/services/task/digital/Digital.js +78 -0
- package/dist/services/task/digital/Digital.js.map +1 -0
- package/dist/services/task/state-machine/TaskStateMachine.js +982 -0
- package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -0
- package/dist/services/task/state-machine/actions.js +572 -0
- package/dist/services/task/state-machine/actions.js.map +1 -0
- package/dist/services/task/state-machine/constants.js +161 -0
- package/dist/services/task/state-machine/constants.js.map +1 -0
- package/dist/services/task/state-machine/guards.js +379 -0
- package/dist/services/task/state-machine/guards.js.map +1 -0
- package/dist/services/task/state-machine/index.js +53 -0
- package/dist/services/task/state-machine/index.js.map +1 -0
- package/dist/services/task/state-machine/types.js +54 -0
- package/dist/services/task/state-machine/types.js.map +1 -0
- package/dist/services/task/state-machine/uiControlsComputer.js +703 -0
- package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -0
- package/dist/services/task/taskDataNormalizer.js +99 -0
- package/dist/services/task/taskDataNormalizer.js.map +1 -0
- package/dist/services/task/types.js +259 -5
- package/dist/services/task/types.js.map +1 -1
- package/dist/services/task/voice/Voice.js +1504 -0
- package/dist/services/task/voice/Voice.js.map +1 -0
- package/dist/services/task/voice/WebRTC.js +152 -0
- package/dist/services/task/voice/WebRTC.js.map +1 -0
- 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 +222 -10
- package/dist/types/config.d.ts +13 -0
- package/dist/types/constants.d.ts +40 -1
- package/dist/types/index.d.ts +58 -22
- package/dist/types/metrics/MetricsManager.d.ts +6 -0
- package/dist/types/metrics/constants.d.ts +52 -1
- 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 +67 -5
- package/dist/types/services/EntryPoint.d.ts +7 -5
- package/dist/types/services/Queue.d.ts +5 -3
- package/dist/types/services/UserPreference.d.ts +118 -0
- 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 +49 -76
- package/dist/types/services/config/index.d.ts +16 -64
- package/dist/types/services/config/types.d.ts +252 -114
- package/dist/types/services/constants.d.ts +16 -0
- package/dist/types/services/core/Err.d.ts +6 -0
- package/dist/types/services/core/Utils.d.ts +43 -13
- 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/core/websocket/WebSocketManager.d.ts +2 -0
- package/dist/types/services/core/websocket/types.d.ts +1 -1
- package/dist/types/services/index.d.ts +2 -0
- package/dist/types/services/task/Task.d.ts +186 -0
- package/dist/types/services/task/TaskFactory.d.ts +14 -0
- package/dist/types/services/task/TaskUtils.d.ts +54 -2
- package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
- package/dist/types/services/task/constants.d.ts +20 -0
- package/dist/types/services/task/contact.d.ts +4 -0
- package/dist/types/services/task/dialer.d.ts +30 -0
- package/dist/types/services/task/digital/Digital.d.ts +23 -0
- package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +1442 -0
- package/dist/types/services/task/state-machine/actions.d.ts +10 -0
- package/dist/types/services/task/state-machine/constants.d.ts +107 -0
- package/dist/types/services/task/state-machine/guards.d.ts +103 -0
- package/dist/types/services/task/state-machine/index.d.ts +13 -0
- package/dist/types/services/task/state-machine/types.d.ts +277 -0
- package/dist/types/services/task/state-machine/uiControlsComputer.d.ts +9 -0
- package/dist/types/services/task/taskDataNormalizer.d.ts +10 -0
- package/dist/types/services/task/types.d.ts +790 -66
- package/dist/types/services/task/voice/Voice.d.ts +241 -0
- package/dist/types/services/task/voice/WebRTC.d.ts +54 -0
- 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 +258 -11
- package/dist/types/utils/PageCache.d.ts +20 -3
- package/dist/types/webex.d.ts +1 -0
- package/dist/types.js +204 -6
- 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 +22 -2
- package/dist/webex.js.map +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/docs/adr/0002-consult-transfer-list-policy.md +345 -0
- package/docs/adr/0003-repo-standards-migration.md +104 -0
- package/docs/adr/index.md +35 -0
- package/docs/architecture.md +460 -0
- package/docs/getting-started.md +142 -0
- package/docs/index.md +53 -0
- package/docs/specs/README.md +98 -0
- package/package.json +17 -12
- package/schemas/repo-context.schema.json +796 -0
- package/src/cc.ts +1439 -105
- package/src/config.ts +13 -0
- package/src/constants.ts +53 -1
- package/src/docs/README.md +727 -0
- package/src/index.ts +72 -16
- package/src/metrics/MetricsManager.ts +16 -0
- package/src/metrics/behavioral-events.ts +218 -0
- package/src/metrics/constants.ts +63 -4
- package/src/metrics/docs/README.md +710 -0
- package/src/services/AddressBook.ts +17 -6
- package/src/services/AnswerCallOnWebexService.ts +239 -0
- package/src/services/ApiAiAssistant.ts +494 -15
- package/src/services/EntryPoint.ts +59 -60
- package/src/services/Queue.ts +29 -12
- package/src/services/UserPreference.ts +509 -0
- package/src/services/WebCallingService.ts +362 -40
- package/src/services/WebexCrossClientService.ts +298 -0
- package/src/services/WxAppTelephonyMercurySync.ts +142 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/Util.ts +54 -84
- package/src/services/config/constants.ts +64 -86
- package/src/services/config/docs/README.md +530 -0
- package/src/services/config/index.ts +116 -277
- package/src/services/config/types.ts +238 -125
- package/src/services/constants.ts +18 -0
- package/src/services/core/Err.ts +3 -0
- package/src/services/core/Utils.ts +151 -37
- package/src/services/core/WebexRequest.ts +3 -1
- package/src/services/core/aqm-reqs.ts +18 -12
- package/src/services/core/constants.ts +8 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/core/types.ts +33 -1
- package/src/services/core/websocket/WebSocketManager.ts +37 -8
- package/src/services/core/websocket/connection-service.ts +5 -1
- package/src/services/core/websocket/types.ts +1 -1
- package/src/services/docs/README.md +765 -0
- package/src/services/index.ts +4 -0
- package/src/services/task/Task.ts +1211 -0
- package/src/services/task/TaskFactory.ts +82 -0
- package/src/services/task/TaskManager.ts +1551 -584
- package/src/services/task/TaskUtils.ts +316 -25
- package/src/services/task/WebexCallingUtils.ts +136 -0
- package/src/services/task/constants.ts +21 -0
- package/src/services/task/contact.ts +30 -0
- package/src/services/task/dialer.ts +80 -0
- package/src/services/task/digital/Digital.ts +102 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/TaskStateMachine.ts +1320 -0
- package/src/services/task/state-machine/actions.ts +741 -0
- package/src/services/task/state-machine/constants.ts +172 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/services/task/state-machine/guards.ts +442 -0
- package/src/services/task/state-machine/index.ts +28 -0
- package/src/services/task/state-machine/types.ts +258 -0
- package/src/services/task/state-machine/uiControlsComputer.ts +1135 -0
- package/src/services/task/taskDataNormalizer.ts +137 -0
- package/src/services/task/types.ts +974 -70
- package/src/services/task/voice/Voice.ts +1878 -0
- package/src/services/task/voice/WebRTC.ts +194 -0
- 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 +323 -13
- package/src/utils/AGENTS.md +291 -0
- package/src/utils/PageCache.ts +38 -5
- package/src/utils/docs/README.md +413 -0
- package/src/webex.js +10 -0
- package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
- package/test/unit/spec/cc.ts +4046 -181
- package/test/unit/spec/index.ts +891 -0
- package/test/unit/spec/logger-proxy.ts +70 -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 +442 -23
- package/test/unit/spec/services/EntryPoint.ts +87 -40
- package/test/unit/spec/services/Queue.ts +123 -12
- package/test/unit/spec/services/UserPreference.ts +401 -0
- package/test/unit/spec/services/WebCallingService.ts +484 -49
- 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 +318 -548
- package/test/unit/spec/services/core/Utils.ts +447 -8
- 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 +132 -56
- package/test/unit/spec/services/core/websocket/connection-service.ts +3 -1
- package/test/unit/spec/services/task/AutoWrapup.ts +63 -0
- package/test/unit/spec/services/task/Task.ts +2723 -0
- package/test/unit/spec/services/task/TaskFactory.ts +116 -0
- package/test/unit/spec/services/task/TaskManager.ts +4800 -1586
- package/test/unit/spec/services/task/TaskUtils.ts +307 -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/dialer.ts +190 -0
- package/test/unit/spec/services/task/digital/Digital.ts +105 -0
- package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +4060 -0
- package/test/unit/spec/services/task/state-machine/guards.ts +839 -0
- package/test/unit/spec/services/task/state-machine/types.ts +18 -0
- package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +3101 -0
- package/test/unit/spec/services/task/taskTestUtils.ts +87 -0
- package/test/unit/spec/services/task/voice/Voice.ts +2355 -0
- package/test/unit/spec/services/task/voice/WebRTC.ts +235 -0
- 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
- package/dist/services/task/index.js +0 -1525
- package/dist/services/task/index.js.map +0 -1
- package/dist/types/services/task/index.d.ts +0 -650
- package/src/services/task/index.ts +0 -1801
- 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 |
|