@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
package/AGENTS.md
ADDED
|
@@ -0,0 +1,969 @@
|
|
|
1
|
+
<!-- sdd-generated-metadata
|
|
2
|
+
doc_kind: agent-entry
|
|
3
|
+
generated_from: agents@0.3.0
|
|
4
|
+
generated_by: claude-code
|
|
5
|
+
approved_by: rarajes2@cisco.com
|
|
6
|
+
updated_at: 2026-11-17T03:03:58Z
|
|
7
|
+
validation_status: pass-with-warnings
|
|
8
|
+
-->
|
|
9
|
+
|
|
10
|
+
# AI Agent Instructions
|
|
11
|
+
|
|
12
|
+
Package-scoped SDD entry for `@webex/contact-center`. `@webex/contact-center` is a published Webex SDK
|
|
13
|
+
plugin for agent registration, configuration, realtime events, task/call control, data lookup, and
|
|
14
|
+
telemetry. It registers as `webex.cc` (`src/index.ts`). This file orients agents working in this
|
|
15
|
+
package. The monorepo root `AGENTS.md` governs workspace-wide setup.
|
|
16
|
+
|
|
17
|
+
**What it is:**
|
|
18
|
+
|
|
19
|
+
- A TypeScript SDK package embedded in the Webex SDK host.
|
|
20
|
+
- A client of Webex Contact Center REST, WebSocket, calling, and metrics services.
|
|
21
|
+
|
|
22
|
+
**What it is NOT:**
|
|
23
|
+
|
|
24
|
+
- It is not a standalone backend and owns no durable datastore.
|
|
25
|
+
- It does not render a UI; it exposes state and UI-control contracts to host applications.
|
|
26
|
+
|
|
27
|
+
## Working Method
|
|
28
|
+
|
|
29
|
+
- Read the relevant package files before editing. Do not edit blind.
|
|
30
|
+
- Code and tests are the behavioral referee; never invent APIs, paths, events, flags, or states.
|
|
31
|
+
- Understand the task and affected surfaces before writing code.
|
|
32
|
+
- Prefer focused edits over rewriting whole files.
|
|
33
|
+
- Test or validate before declaring done.
|
|
34
|
+
- Keep output concise. If something is uncertain, say so instead of guessing.
|
|
35
|
+
|
|
36
|
+
Developer workflow:
|
|
37
|
+
|
|
38
|
+
1. Read this file for package rules, then use [`docs/specs/README.md`](docs/specs/README.md) to
|
|
39
|
+
select the owning canonical module spec.
|
|
40
|
+
2. Check the module spec's requirements, public surface, source paths, test evidence, and documented
|
|
41
|
+
gaps against the relevant code/tests.
|
|
42
|
+
3. Before coding, present the affected files and contracts and wait for confirmation. For a new
|
|
43
|
+
method, settle its target file and name, parameters (required or optional), return shape, backend
|
|
44
|
+
call (HTTP verb, endpoint, payload, and whether the result arrives in the HTTP response or as a
|
|
45
|
+
WebSocket message), events, metric names, and success and failure behavior. For a bug, settle the
|
|
46
|
+
unexpected and expected behavior, the reproduction steps or logs and tracking id, and the affected
|
|
47
|
+
layer (plugin `src/cc.ts`, a service under `src/services/`, core `src/services/core/`, or types).
|
|
48
|
+
4. Implement the smallest approved change; update the owning module spec, the contract index in
|
|
49
|
+
[`docs/architecture.md`](docs/architecture.md), and `.sdd/manifest.json` when public behavior or
|
|
50
|
+
routing changes.
|
|
51
|
+
5. Run the package commands below plus manifest/conformance checks; materially changed generated
|
|
52
|
+
specs require validation on the configured independent runtime.
|
|
53
|
+
6. Review the final diff for source/test fidelity, compatibility, secrets, and unrelated files before
|
|
54
|
+
staging.
|
|
55
|
+
|
|
56
|
+
Task routing inside this file: a new method or feature on an existing service uses
|
|
57
|
+
[Public methods and new code placement](#public-methods-and-new-code-placement) and
|
|
58
|
+
[Logging, metrics, and errors](#logging-metrics-and-errors); a new service also uses
|
|
59
|
+
[Services and constants](#services-and-constants); a bug fix starts from
|
|
60
|
+
[Common bug patterns](#common-bug-patterns); every change ends with [Testing Workflow](#4-testing-workflow).
|
|
61
|
+
|
|
62
|
+
## Canonical Repository Documentation
|
|
63
|
+
|
|
64
|
+
Before changing code or documentation, start with:
|
|
65
|
+
|
|
66
|
+
- [`docs/index.md`](docs/index.md) for package documentation navigation;
|
|
67
|
+
- [`docs/architecture.md`](docs/architecture.md) for package boundaries, interactions, and the
|
|
68
|
+
contract index;
|
|
69
|
+
- [`docs/specs/README.md`](docs/specs/README.md) for the manifest-backed module and contract registry;
|
|
70
|
+
- the affected module's spec: [`src/docs/README.md`](src/docs/README.md) (plugin and public API),
|
|
71
|
+
[`src/metrics/docs/README.md`](src/metrics/docs/README.md),
|
|
72
|
+
[`src/services/docs/README.md`](src/services/docs/README.md),
|
|
73
|
+
[`src/services/agent/docs/README.md`](src/services/agent/docs/README.md),
|
|
74
|
+
[`src/services/config/docs/README.md`](src/services/config/docs/README.md),
|
|
75
|
+
[`src/services/core/docs/README.md`](src/services/core/docs/README.md),
|
|
76
|
+
[`src/services/task/docs/README.md`](src/services/task/docs/README.md),
|
|
77
|
+
[`src/services/task/state-machine/docs/README.md`](src/services/task/state-machine/docs/README.md),
|
|
78
|
+
or [`src/utils/docs/README.md`](src/utils/docs/README.md); and
|
|
79
|
+
- [`docs/adr/index.md`](docs/adr/index.md) plus applicable concrete ADRs for durable decisions.
|
|
80
|
+
|
|
81
|
+
Follow `.sdd/manifest.json` for each contract's publication state and canonical source;
|
|
82
|
+
`.sdd/manifest.json` is authoritative for SDD coverage, and `docs/specs/README.md` mirrors it. Every
|
|
83
|
+
module is `Partial` today: existing docs help, but code must be cross-checked until migration,
|
|
84
|
+
coverage, and validation pass. This package publishes an SDK, so its contract artifact is
|
|
85
|
+
`package.json` with the `src/index.ts` typed entry (`types` is `dist/types/index.d.ts`) and the
|
|
86
|
+
`dist/webex.js` main built from `src/webex.js`. It serves no HTTP API of its own, so no OpenAPI applies.
|
|
87
|
+
|
|
88
|
+
## 1. Commands (Run First)
|
|
89
|
+
|
|
90
|
+
Use only documented commands. Do not invent alternatives when a command is missing. Run every command
|
|
91
|
+
below from the workspace root. The package scripts run through `yarn workspace @webex/contact-center`
|
|
92
|
+
followed by the script name; `package.json` in `packages/@webex/contact-center` defines them.
|
|
93
|
+
|
|
94
|
+
| Task | Command |
|
|
95
|
+
| ---------------------- | ------- |
|
|
96
|
+
| Install dependencies | `yarn` (workspace root) |
|
|
97
|
+
| Start dev environment | N/A — library package with no start script in `package.json` |
|
|
98
|
+
| Run tests | `yarn workspace @webex/contact-center test:unit` (the `@webex/contact-center` workspace `test:unit` script; Jest collects coverage) |
|
|
99
|
+
| Run linters | `yarn workspace @webex/contact-center test:style` (the workspace `test:style` script: eslint over `src/**/*.ts`) |
|
|
100
|
+
| Build/release artifact | `yarn workspace @webex/contact-center build:src` (babel output, source maps, then the `build` script for `@webex/calling` and the `dist/types` declarations) |
|
|
101
|
+
| Format code | `yarn workspace @webex/contact-center fix:prettier` (prettier over `src/**/*.ts`); `yarn workspace @webex/contact-center fix:lint` applies eslint fixes |
|
|
102
|
+
| Build with dependencies | `yarn workspace @webex/contact-center compile` (runs `build:src` for this package and its workspace dependencies in topological order) |
|
|
103
|
+
| Style and unit together | `yarn workspace @webex/contact-center test` (runs `test:style`, then `test:unit`) |
|
|
104
|
+
| E2E | `yarn workspace @webex/contact-center test:e2e` (Playwright with the workspace `playwright.config.ts`, which runs the monorepo-root `cc_playwright/` suites; see its README) |
|
|
105
|
+
| API reference | `yarn workspace @webex/contact-center build:docs` (typedoc into the workspace `docs/wxcc` folder, outside this package) |
|
|
106
|
+
| Publish | `yarn workspace @webex/contact-center deploy:npm` (release automation only) |
|
|
107
|
+
|
|
108
|
+
To run one spec file, add the `--targets` option that the workspace root `AGENTS.md` describes, with a
|
|
109
|
+
path relative to `test/unit/spec/` (for example `cc.ts`). There is no `test:integration` or
|
|
110
|
+
`test:browser` script.
|
|
111
|
+
|
|
112
|
+
If a required command is unknown, stop and ask for the exact command.
|
|
113
|
+
|
|
114
|
+
## 2. Agent Persona and Scope
|
|
115
|
+
|
|
116
|
+
You are the Webex JS SDK engineering assistant for `@webex/contact-center`.
|
|
117
|
+
|
|
118
|
+
Primary outcomes:
|
|
119
|
+
|
|
120
|
+
- Deliver production-safe changes with lint and unit tests (with coverage) passing.
|
|
121
|
+
- Preserve existing behavior unless a change request explicitly requires a behavior change.
|
|
122
|
+
- Keep docs and configuration aligned with code changes.
|
|
123
|
+
|
|
124
|
+
Definition of done:
|
|
125
|
+
|
|
126
|
+
1. Requested change is implemented, after the affected files and contracts were confirmed.
|
|
127
|
+
2. Unit tests and lint pass; the 85% coverage bar remains satisfied.
|
|
128
|
+
3. Public types/events/methods remain compatible or include a migration plan.
|
|
129
|
+
4. State, error, timeout, and cleanup paths are covered.
|
|
130
|
+
5. Spec/docs and `.sdd/manifest.json` are updated with code changes.
|
|
131
|
+
6. No secrets or sensitive data are committed or logged.
|
|
132
|
+
7. PR summary includes risks and rollback notes.
|
|
133
|
+
|
|
134
|
+
## 3. Repository Knowledge
|
|
135
|
+
|
|
136
|
+
### Tech Stack
|
|
137
|
+
|
|
138
|
+
| Area | Tooling | Version |
|
|
139
|
+
| ---------------- | ------- | ------- |
|
|
140
|
+
| Language runtime | TypeScript sources (one JavaScript entry, `src/webex.js`, and a JavaScript keepalive worker) on node | node 22.14 for workspace development (workspace root `AGENTS.md`; `.nvmrc` `lts/jod`); package `engines` `>=20.x`; typescript `5.4.5` |
|
|
141
|
+
| Build tool | yarn workspaces, `@webex/legacy-tools` over babel, and `tsc` for declarations | yarn `3.4.1` (root `packageManager`) |
|
|
142
|
+
| Test framework | jest through `webex-legacy-tools test --unit --runner jest`, `@webex/jest-config-legacy` extended by `jest.config.js`, `@webex/test-helper-mock-webex` | jest `27.5.1` |
|
|
143
|
+
| Lint/format | eslint with the monorepo root `.eslintrc.js` (the package has none of its own), prettier | eslint `^8.24.0`, prettier `2.5.1` |
|
|
144
|
+
| Runtime libraries | `WebexPlugin` from `@webex/webex-core`, Node `events` `EventEmitter`, XState, WebSocket, `@webex/calling` for WebRTC, Mercury, metrics | xstate `5.24.0` |
|
|
145
|
+
|
|
146
|
+
### Project Map
|
|
147
|
+
|
|
148
|
+
Request path: Host Webex SDK → ContactCenter plugin → Services/Task/Metrics → REST + WebSocket + WebRTC
|
|
149
|
+
backends. The full architecture is in [`docs/architecture.md`](docs/architecture.md).
|
|
150
|
+
|
|
151
|
+
- `src/`: public plugin/API orchestration
|
|
152
|
+
- `src/metrics/`: telemetry
|
|
153
|
+
- `src/services/`: service composition and integrations
|
|
154
|
+
- `src/services/{agent,config,core}/`: agent, profile, and transport capabilities
|
|
155
|
+
- `src/services/task/`: task/call lifecycle
|
|
156
|
+
- `src/services/task/state-machine/`: typed XState lifecycle engine
|
|
157
|
+
- `src/utils/`: pagination/page cache contracts
|
|
158
|
+
|
|
159
|
+
Key files:
|
|
160
|
+
|
|
161
|
+
- `src/index.ts`: registers the `cc` plugin and lists every published export and type.
|
|
162
|
+
- `src/cc.ts`: `ContactCenter` (extends `WebexPlugin`), the `webex.cc` public API and WebSocket event
|
|
163
|
+
fan-out.
|
|
164
|
+
- `src/types.ts`, `src/constants.ts`, `src/config.ts`: public types, SDK-wide constants and
|
|
165
|
+
`METHODS`, and the plugin config defaults (`allowMultiLogin`, `allowAutomatedRelogin`, and others).
|
|
166
|
+
- `src/logger-proxy.ts`: `LoggerProxy`, the only logging entry point.
|
|
167
|
+
- `src/services/index.ts`: the `Services` singleton.
|
|
168
|
+
- `src/services/AddressBook.ts`, `EntryPoint.ts`, `Queue.ts`, `UserPreference.ts`, `ApiAiAssistant.ts`,
|
|
169
|
+
`WebCallingService.ts` and the other single-file services beside them.
|
|
170
|
+
- `src/webex.js`, `src/webex-config.ts`: the standalone `Webex` constructor and its config; `umd/` holds
|
|
171
|
+
the committed browser bundle.
|
|
172
|
+
- `test/unit/spec/`: unit specs mirroring `src/`; `test/unit/fixtures/` and `__mocks__/workerMock.js`
|
|
173
|
+
hold shared helpers.
|
|
174
|
+
- `dist/`: generated build output. Never edit by hand.
|
|
175
|
+
|
|
176
|
+
### Critical Constraints
|
|
177
|
+
|
|
178
|
+
- AQM completion may arrive over WebSocket after an HTTP acknowledgement; do not treat the
|
|
179
|
+
acknowledgement as completion. Preserve AQM HTTP-plus-WebSocket correlation, timeout, and recovery
|
|
180
|
+
semantics; settlement and the `TIMEOUT_REQ` default are CORE-R-003 in
|
|
181
|
+
[core Requirements](src/services/core/docs/README.md#requirements).
|
|
182
|
+
- Listener cleanup requires the same function reference used at registration; preserve listener
|
|
183
|
+
identity for cleanup and avoid blocking the event loop in handlers.
|
|
184
|
+
- Config aggregation is all-or-nothing; returning a partial profile creates inconsistent runtime
|
|
185
|
+
behavior. `getAgentConfig` awaits the user desktop-login aggregate, then fetches the five dependent
|
|
186
|
+
parts with one `Promise.all`, and rethrows on any failure (`src/services/config/index.ts`).
|
|
187
|
+
- Task transitions must go through typed TaskEvent mapping and guards; see
|
|
188
|
+
[`src/services/task/state-machine/docs/README.md`](src/services/task/state-machine/docs/README.md).
|
|
189
|
+
- PageCache bypasses search/filter/attributes/sort queries to avoid stale or incorrect reuse
|
|
190
|
+
(`canUseCache` in `src/utils/PageCache.ts`).
|
|
191
|
+
- Use MetricsManager timing/tracking patterns without blocking product behavior.
|
|
192
|
+
- Use typed event constants; preserve `trigger` versus `emit` ownership (see
|
|
193
|
+
[Events](#events)).
|
|
194
|
+
- Credentials come from the host Webex SDK; validate inputs and use authenticated service routing.
|
|
195
|
+
- `cc.register()` must run before any agent operation: it opens the WebSocket, so task and agent
|
|
196
|
+
events arrive only after it.
|
|
197
|
+
- The published surface is what `src/index.ts` exports; renaming or removing an export, a public
|
|
198
|
+
method, an event name, or a type field is a breaking change for host applications.
|
|
199
|
+
|
|
200
|
+
## 4. Testing Workflow
|
|
201
|
+
|
|
202
|
+
Run checks in this order, from the workspace root:
|
|
203
|
+
|
|
204
|
+
1. `yarn workspace @webex/contact-center build:src`
|
|
205
|
+
2. `yarn workspace @webex/contact-center test:unit`
|
|
206
|
+
3. `yarn workspace @webex/contact-center test:style`
|
|
207
|
+
4. `yarn workspace @webex/contact-center test:e2e` only when the change needs it (see Ask First).
|
|
208
|
+
|
|
209
|
+
On a fresh or outdated checkout, run `yarn workspace @webex/contact-center compile` first so workspace dependencies such as
|
|
210
|
+
`@webex/calling` have a current `dist/`; specs also import workspace packages such as
|
|
211
|
+
`@webex/test-helper-mock-webex` and `@webex/internal-plugin-mercury` by name.
|
|
212
|
+
|
|
213
|
+
Testing rules:
|
|
214
|
+
|
|
215
|
+
- Mirror source paths under `test/unit/spec/`; cover positive and negative behavior and retain the 85%
|
|
216
|
+
global coverage threshold.
|
|
217
|
+
- Every new source file must have a corresponding test file. The test file location mirrors the
|
|
218
|
+
source file path: `src/cc.ts` → `test/unit/spec/cc.ts`, `src/logger-proxy.ts` →
|
|
219
|
+
`test/unit/spec/logger-proxy.ts`, `src/metrics/MetricsManager.ts` →
|
|
220
|
+
`test/unit/spec/metrics/MetricsManager.ts`, `src/services/agent/index.ts` →
|
|
221
|
+
`test/unit/spec/services/agent/index.ts`, `src/services/task/Task.ts` →
|
|
222
|
+
`test/unit/spec/services/task/Task.ts`, `src/services/WebCallingService.ts` →
|
|
223
|
+
`test/unit/spec/services/WebCallingService.ts`. Logic files with no mirrored spec today include
|
|
224
|
+
`src/services/index.ts`, `src/services/core/Err.ts`, `src/services/task/state-machine/actions.ts`,
|
|
225
|
+
`src/services/task/taskDataNormalizer.ts`, `src/services/wxAppTelephonyUtils.ts`, and
|
|
226
|
+
`src/utils/PageCache.ts`; pin their current behavior before changing them.
|
|
227
|
+
- `jest.config.js` sets `collectCoverage: true`, `clearMocks: true`, and 85% global branch, function,
|
|
228
|
+
line, and statement thresholds. Reports go to `coverage/` (junit under `coverage/junit`, the HTML
|
|
229
|
+
report, lcov) and, through `testResultsProcessor: 'jest-junit'`, to `junit.xml` at the package root
|
|
230
|
+
(ignored by Git).
|
|
231
|
+
- Specs use Jest (`expect`, `jest.fn()`, `jest.mock`, `jest.spyOn`), not the sinon and chai helpers
|
|
232
|
+
the workspace root `AGENTS.md` describes for other plugins. Use fake timers
|
|
233
|
+
(`jest.useFakeTimers()`) for time-dependent behavior, and parametrize (`it.each`) when more than
|
|
234
|
+
three cases are alike.
|
|
235
|
+
- For a new method, test the success case, the error case (including the `getErrorDetails` call), edge
|
|
236
|
+
cases, the metrics tracking (`timeEvent` and `trackEvent` calls asserted), the logging (`LoggerProxy`
|
|
237
|
+
calls), and optional parameters.
|
|
238
|
+
- For a bug fix, add a regression test that reproduces the original bug (fails before the fix, passes
|
|
239
|
+
after) to prevent the same issue from recurring.
|
|
240
|
+
- Prefer exact matches over `expect.objectContaining` in new tests. Exact matches catch unexpected
|
|
241
|
+
field changes and keep tests rigorous: use `toEqual` with the full expected object, and use
|
|
242
|
+
`expect.objectContaining()` or `expect.arrayContaining()` only for a specific reason such as
|
|
243
|
+
dynamic fields like timestamps. Existing tests may use `expect.objectContaining` for complex
|
|
244
|
+
objects; this is acceptable but not preferred for new code.
|
|
245
|
+
- Do not remove tests to make CI pass.
|
|
246
|
+
|
|
247
|
+
Spec setup used by `test/unit/spec/cc.ts`:
|
|
248
|
+
|
|
249
|
+
- `import 'jsdom-global/register';` first, then `import '../../../__mocks__/workerMock';`, which
|
|
250
|
+
defines a global `Worker` (its `postMessage` calls `onmessage`) for the keepalive worker and sets
|
|
251
|
+
`global.URL.createObjectURL = jest.fn(() => 'blob:http://localhost:3000/12345');`.
|
|
252
|
+
- `jest.mock` the module singletons (`src/logger-proxy`, `src/services`, `src/services/task/TaskManager`,
|
|
253
|
+
`src/metrics/MetricsManager`, `src/services/core/WebexRequest`), and mock `uuid` with
|
|
254
|
+
`jest.mock('uuid', () => ({v4: () => 'mock-tracking-uuid'}))`.
|
|
255
|
+
- Build the host with `MockWebex` and cast it once: `MockWebex` requires the `as unknown as WebexSDK`
|
|
256
|
+
double-cast, so do not use this pattern elsewhere.
|
|
257
|
+
- Spy the singleton getters and the error helper, then construct the plugin:
|
|
258
|
+
|
|
259
|
+
```typescript
|
|
260
|
+
webex = MockWebex({
|
|
261
|
+
children: {
|
|
262
|
+
cc: ContactCenter,
|
|
263
|
+
mercury: Mercury,
|
|
264
|
+
},
|
|
265
|
+
logger: {
|
|
266
|
+
log: jest.fn(),
|
|
267
|
+
error: jest.fn(),
|
|
268
|
+
info: jest.fn(),
|
|
269
|
+
},
|
|
270
|
+
credentials: {
|
|
271
|
+
getOrgId: jest.fn(() => 'mockOrgId'),
|
|
272
|
+
},
|
|
273
|
+
config: config,
|
|
274
|
+
once: jest.fn((event, callback) => callback()),
|
|
275
|
+
}) as unknown as WebexSDK;
|
|
276
|
+
|
|
277
|
+
jest.spyOn(MetricsManager, 'getInstance').mockReturnValue(mockMetricsManager);
|
|
278
|
+
jest.spyOn(Services, 'getInstance').mockReturnValue(mockServicesInstance as any);
|
|
279
|
+
jest.spyOn(TaskManager, 'getTaskManager').mockReturnValue(mockTaskManager);
|
|
280
|
+
jest.spyOn(WebexRequest, 'getInstance').mockReturnValue(mockWebexRequest);
|
|
281
|
+
webex.cc = new ContactCenter({parent: webex});
|
|
282
|
+
getErrorDetailsSpy = jest.spyOn(Utils, 'getErrorDetails');
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Service specs that construct a class directly (for example `test/unit/spec/services/AddressBook.ts`)
|
|
286
|
+
automock `jest.mock('../../../../src/logger-proxy')` and `src/metrics/MetricsManager`, pass a plain
|
|
287
|
+
mock `webex` with `credentials.getOrgId` and `request`, and reset `(WebexRequest as any).instance =
|
|
288
|
+
undefined` in `beforeEach`. Internal plugins come from real children (`mercury: Mercury`) plus
|
|
289
|
+
`jest.spyOn(webex.internal.mercury, 'connect')`.
|
|
290
|
+
|
|
291
|
+
Event listeners and their callbacks are tested by spying on the registration, extracting the callback
|
|
292
|
+
via `mock.calls`, and invoking it directly:
|
|
293
|
+
|
|
294
|
+
```typescript
|
|
295
|
+
it('should handle websocket message and emit event', async () => {
|
|
296
|
+
await webex.cc.register(); // register() adds the 'message' listener
|
|
297
|
+
|
|
298
|
+
// Step 1: Find the registered callback via mock.calls
|
|
299
|
+
const onCalls = mockServicesInstance.webSocketManager.on.mock.calls;
|
|
300
|
+
const messageCall = onCalls.find(([event]) => event === 'message');
|
|
301
|
+
const wsHandler = messageCall[1];
|
|
302
|
+
|
|
303
|
+
// Step 2: Spy on the emit
|
|
304
|
+
const emitSpy = jest.spyOn(webex.cc, 'emit');
|
|
305
|
+
|
|
306
|
+
// Step 3: Invoke the callback directly with test data
|
|
307
|
+
wsHandler(JSON.stringify({
|
|
308
|
+
type: 'AgentStateChange',
|
|
309
|
+
data: { type: 'AgentStateChangeSuccess', agentId: 'agent-123', state: 'Available' },
|
|
310
|
+
}));
|
|
311
|
+
|
|
312
|
+
// Step 4: Assert exact emit arguments
|
|
313
|
+
expect(emitSpy).toHaveBeenCalledWith('agent:stateChange', {
|
|
314
|
+
type: 'AgentStateChangeSuccess',
|
|
315
|
+
agentId: 'agent-123',
|
|
316
|
+
state: 'Available',
|
|
317
|
+
});
|
|
318
|
+
});
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Spy on `emit` for events that `handleWebsocketMessage` re-emits and on `trigger` for events forwarded
|
|
322
|
+
from `TaskManager` (`task:incoming`, `task:hydrate`); the spec asserts on whichever method the code
|
|
323
|
+
calls. Assert the error helper with its exact arguments, for example
|
|
324
|
+
`expect(getErrorDetailsSpy).toHaveBeenCalledWith(error, 'startOutdial', CC_FILE)`; `CC_FILE` is
|
|
325
|
+
`'cc'`.
|
|
326
|
+
|
|
327
|
+
## 5. Code Style and Patterns
|
|
328
|
+
|
|
329
|
+
Coding expectations:
|
|
330
|
+
|
|
331
|
+
- Follow repository style rules and static analysis output. `yarn workspace @webex/contact-center test:style` applies the monorepo root
|
|
332
|
+
`.eslintrc.js` to `src/**/*.ts` only; its ignore patterns skip `**/test/**/*`. It enforces
|
|
333
|
+
`max-len` 100, single quotes, `newline-before-return`, and `no-console` (which still allows
|
|
334
|
+
`console.warn` and `console.error`).
|
|
335
|
+
- Prefer small, composable functions over large procedural blocks.
|
|
336
|
+
- Make error handling explicit at system boundaries.
|
|
337
|
+
- Keep public interfaces stable unless a breaking change is requested.
|
|
338
|
+
- Always use async/await over raw Promises.
|
|
339
|
+
- Avoid `any` type unless absolutely necessary, and prefer `unknown` over `any` for unknown types.
|
|
340
|
+
`@typescript-eslint/no-explicit-any` is off, so lint does not catch it; the few justified uses in
|
|
341
|
+
`src/services/task/types.ts` carry an `eslint-disable-next-line` comment.
|
|
342
|
+
- TypeScript strict mode is not enabled: the shared root `tsconfig.json` sets `alwaysStrict` but not
|
|
343
|
+
`strict`, so the compiler does not enforce null checks; guard optional data with optional chaining.
|
|
344
|
+
- All public APIs must have explicit return types.
|
|
345
|
+
- External packages first, then package types/constants, service imports, local utilities, and
|
|
346
|
+
type-only imports (`import type`), as `src/cc.ts` orders them: `@webex/webex-core`, `events`, and
|
|
347
|
+
`uuid`, then `./types` and `./constants`, then `./services` and `./logger-proxy`. New runtime
|
|
348
|
+
dependencies require approval.
|
|
349
|
+
- Before adding a literal path, filename, command, workflow identifier, status, or other policy
|
|
350
|
+
value, search the repository for exact and semantically equivalent uses. When repeated production
|
|
351
|
+
values represent one shared contract, move them to the narrowest owning shared module or catalog as
|
|
352
|
+
one canonical named constant, enum, or type and update consumers. Keep incidental similarities,
|
|
353
|
+
one-off implementation details, and independent test fixtures local.
|
|
354
|
+
- Do not import a default, named, object, or namespace binding and immediately re-export it.
|
|
355
|
+
Consumers should import from the owning module; `src/index.ts` uses direct named re-exports
|
|
356
|
+
(`export {default as AddressBook} from './services/AddressBook'`).
|
|
357
|
+
- Do not write inline runtime `typeof` checks outside descriptively named guard implementations.
|
|
358
|
+
Import and reuse the owning guard (`isRecord` in `src/services/core/Utils.ts`) instead; TypeScript
|
|
359
|
+
type-position `typeof` queries remain allowed.
|
|
360
|
+
|
|
361
|
+
Pattern example:
|
|
362
|
+
|
|
363
|
+
```text
|
|
364
|
+
Preferred:
|
|
365
|
+
- Validate input in the public cc or task method before calling a service.
|
|
366
|
+
- Return the typed service response; augment failures with getErrorDetails.
|
|
367
|
+
- Log with LoggerProxy and {module, method, trackingId}; time and track every operation.
|
|
368
|
+
|
|
369
|
+
Avoid:
|
|
370
|
+
- Passing unvalidated payloads deep into the services.
|
|
371
|
+
- Swallowing exceptions, double-logging after getErrorDetails, or synthesizing success.
|
|
372
|
+
- Raw event-name strings, console logging, or logging tokens.
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
Before submitting code (each rule lives in the linked subsection):
|
|
376
|
+
|
|
377
|
+
- All public APIs have JSDoc with `@public`, `@param`, `@returns`, `@example`
|
|
378
|
+
([Naming and files](#naming-and-files)).
|
|
379
|
+
- LoggerProxy used for all logging with module/method context; no `console.log` or `console.error`
|
|
380
|
+
([Logging, metrics, and errors](#logging-metrics-and-errors)).
|
|
381
|
+
- MetricsManager tracks success/failure for all operations
|
|
382
|
+
([Logging, metrics, and errors](#logging-metrics-and-errors)).
|
|
383
|
+
- Error handling follows the `getErrorDetails` pattern
|
|
384
|
+
([Logging, metrics, and errors](#logging-metrics-and-errors)).
|
|
385
|
+
- No hardcoded credentials or sensitive data ([Never](#never)).
|
|
386
|
+
- Event constants used (not string literals) ([Events](#events)).
|
|
387
|
+
- Method names added to the owning `METHODS` constant ([Services and constants](#services-and-constants)).
|
|
388
|
+
- Types exported appropriately ([Public methods and new code placement](#public-methods-and-new-code-placement)).
|
|
389
|
+
- Unit tests added/updated ([Testing Workflow](#4-testing-workflow)).
|
|
390
|
+
- No `any` types without justification (Coding expectations above).
|
|
391
|
+
|
|
392
|
+
### Naming and files
|
|
393
|
+
|
|
394
|
+
Use PascalCase classes/files, camelCase methods, SCREAMING_SNAKE_CASE constants, and typed event
|
|
395
|
+
constants from their owning module.
|
|
396
|
+
|
|
397
|
+
| Element | Convention | Example |
|
|
398
|
+
|---|---|---|
|
|
399
|
+
| Classes | PascalCase | `ContactCenter`, `TaskManager` |
|
|
400
|
+
| Interfaces | PascalCase with `I` prefix for contracts | `IContactCenter`, `ITask`, `IVoice` |
|
|
401
|
+
| Types | PascalCase | `SetStateResponse`, `BuddyAgentsResponse` |
|
|
402
|
+
| Enums/Constants | SCREAMING_SNAKE_CASE | `CC_EVENTS`, `METRIC_EVENT_NAMES` |
|
|
403
|
+
| Methods | camelCase | `stationLogin`, `setAgentState` |
|
|
404
|
+
| Private properties | camelCase with `$` prefix for SDK references | `$webex`, `$config` |
|
|
405
|
+
| Regular private | camelCase | `agentConfig`, `eventEmitter` |
|
|
406
|
+
| Module constants | SCREAMING_SNAKE_CASE | `CC_FILE`, `READY` |
|
|
407
|
+
|
|
408
|
+
Public value objects that mirror wire values are PascalCase too (`LoginOption`, `VoiceLineStatus`).
|
|
409
|
+
|
|
410
|
+
| Type | Convention | Example |
|
|
411
|
+
|------|------------|---------|
|
|
412
|
+
| Class files | PascalCase | `TaskManager.ts`, `WebSocketManager.ts` |
|
|
413
|
+
| Type files | lowercase | `types.ts` |
|
|
414
|
+
| Constant files | lowercase | `constants.ts` |
|
|
415
|
+
| Index files | lowercase | `index.ts` |
|
|
416
|
+
| Utility files | PascalCase | `Utils.ts`, `Err.ts` |
|
|
417
|
+
|
|
418
|
+
Older modules keep kebab-case or camelCase names (`aqm-reqs.ts`, `connection-service.ts`,
|
|
419
|
+
`logger-proxy.ts`, `taskDataNormalizer.ts`, `uiControlsComputer.ts`); do not rename them.
|
|
420
|
+
|
|
421
|
+
JSDoc: all public methods and types must have comprehensive JSDoc with `@public`, `@param`,
|
|
422
|
+
`@returns`, `@throws` where the method rejects, and `@example`; typedoc (`yarn workspace @webex/contact-center build:docs`) renders
|
|
423
|
+
them. Mark internals with the `@private` or `@ignore` tag:
|
|
424
|
+
|
|
425
|
+
```typescript
|
|
426
|
+
/**
|
|
427
|
+
* Internal utility function.
|
|
428
|
+
* @private
|
|
429
|
+
* @ignore
|
|
430
|
+
*/
|
|
431
|
+
private helperMethod(): void {
|
|
432
|
+
// implementation
|
|
433
|
+
}
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
```typescript
|
|
437
|
+
/**
|
|
438
|
+
* Description of what this type represents.
|
|
439
|
+
* @public
|
|
440
|
+
*/
|
|
441
|
+
export type MyType = {
|
|
442
|
+
/** Description of this field */
|
|
443
|
+
fieldName: string;
|
|
444
|
+
/** Optional field description */
|
|
445
|
+
optionalField?: number;
|
|
446
|
+
};
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
A rejection's reason is the error `message` (see [Logging, metrics, and errors](#logging-metrics-and-errors)),
|
|
450
|
+
so document `@throws {Error}` with the reason in `error.message`.
|
|
451
|
+
|
|
452
|
+
### Logging, metrics, and errors
|
|
453
|
+
|
|
454
|
+
Logging: use LoggerProxy with module/method context and tracking identifiers; never use console
|
|
455
|
+
logging in implementation or log credentials/sensitive data (`console` appears only inside JSDoc
|
|
456
|
+
examples).
|
|
457
|
+
|
|
458
|
+
```typescript
|
|
459
|
+
// ✅ REQUIRED pattern
|
|
460
|
+
import LoggerProxy from '../../logger-proxy';
|
|
461
|
+
|
|
462
|
+
LoggerProxy.info('Starting operation', {
|
|
463
|
+
module: 'ModuleName',
|
|
464
|
+
method: 'methodName',
|
|
465
|
+
});
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
`LogContext` (`src/types.ts`) has optional `module`, `method`, `interactionId`, `trackingId`, `data`,
|
|
469
|
+
and `error` fields. Always pass `module` (the file constant such as `CC_FILE`) and `method` (a
|
|
470
|
+
`METHODS` entry); `LoggerProxy.format` writes `unknown` when they are missing. Add `trackingId` for
|
|
471
|
+
request correlation, `interactionId` for the task or call, `data` for extra context, and `error` for
|
|
472
|
+
error logs. Event handlers log each reception the same way: `handleWebsocketMessage` in `src/cc.ts`
|
|
473
|
+
calls `LoggerProxy.log` with `Received event:` plus the event type, `module: CC_FILE`, and
|
|
474
|
+
`method: METHODS.HANDLE_WEBSOCKET_MESSAGE`.
|
|
475
|
+
|
|
476
|
+
| Level | Use Case | Example |
|
|
477
|
+
|---|---|---|
|
|
478
|
+
| `trace` | Detailed debugging | Entry/exit of complex functions |
|
|
479
|
+
| `log` | General information | Operation completed successfully |
|
|
480
|
+
| `info` | Important milestones | Starting registration, login |
|
|
481
|
+
| `warn` | Potential issues | Non-critical issues that don't break flow: the disabled campaign-preview actions in `src/cc.ts`, an empty dial number in `src/services/core/Utils.ts`; no stack trace |
|
|
482
|
+
| `error` | Failures | API errors, exceptions in catch blocks (the default for failure paths); `LoggerProxy.format` appends the stack only at this level, when the context `error` is an `Error` |
|
|
483
|
+
|
|
484
|
+
Never log sensitive data:
|
|
485
|
+
|
|
486
|
+
```typescript
|
|
487
|
+
// ❌ WRONG
|
|
488
|
+
LoggerProxy.log(`User token: ${token}`);
|
|
489
|
+
|
|
490
|
+
// ✅ CORRECT
|
|
491
|
+
LoggerProxy.log('Token received', {
|
|
492
|
+
module: 'Auth',
|
|
493
|
+
method: 'login',
|
|
494
|
+
// No sensitive data in logs
|
|
495
|
+
});
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
Errors: preserve structured backend details and tracking ids through shared Core helpers; never
|
|
499
|
+
swallow failures or synthesize success. In a catch block, read `const failure = error.details as
|
|
500
|
+
Failure`, track the failure metric, then throw the `error` that `getErrorDetails(error, methodName,
|
|
501
|
+
moduleName)` returns (task API calls use `generateTaskErrorObject`); its `message` is the backend
|
|
502
|
+
reason. Both helpers already log through `LoggerProxy.error` and upload logs (both skipped by
|
|
503
|
+
`getErrorDetails` for `AGENT_NOT_FOUND` during `silentRelogin`), so do not double-log errors when
|
|
504
|
+
using `getErrorDetails`. The helper contracts and the `Failure` fields are in
|
|
505
|
+
[core Caller-visible failure modes](src/services/core/docs/README.md#caller-visible-failure-modes).
|
|
506
|
+
|
|
507
|
+
Metrics: `MetricsManager.getInstance({webex})` returns the singleton. Start timing at method entry
|
|
508
|
+
with `timeEvent([SUCCESS, FAILED])`, then call `trackEvent(name, payload, types)` on the success path
|
|
509
|
+
and in the catch block. `types` is a list of `'behavioral'`, `'operational'`, and `'business'`
|
|
510
|
+
(default `['behavioral']`). Build payloads with `MetricsManager.getCommonTrackingFieldForAQMResponse`
|
|
511
|
+
and `getCommonTrackingFieldForAQMResponseFailed`. Add new events to `src/metrics/constants.ts` inside
|
|
512
|
+
`METRIC_EVENT_NAMES`, named with `_SUCCESS` and `_FAILED` suffixes (for example
|
|
513
|
+
`FETCH_BUDDY_AGENTS_SUCCESS` / `FETCH_BUDDY_AGENTS_FAILED`) and valued in title case
|
|
514
|
+
(`'Fetch Buddy Agents Success'`); a behavioral event also needs its taxonomy in
|
|
515
|
+
`src/metrics/behavioral-events.ts`. Details:
|
|
516
|
+
[`src/metrics/docs/README.md`](src/metrics/docs/README.md).
|
|
517
|
+
|
|
518
|
+
Standard public method, as `getBuddyAgents` in `src/cc.ts` implements it:
|
|
519
|
+
|
|
520
|
+
```typescript
|
|
521
|
+
public async getBuddyAgents(data: BuddyAgents): Promise<BuddyAgentsResponse> {
|
|
522
|
+
const {action, state, mediaType = 'telephony'} = data;
|
|
523
|
+
const buddyAgentState = state ?? (action === 'Transfer' ? AGENT_STATE_AVAILABLE : undefined);
|
|
524
|
+
|
|
525
|
+
LoggerProxy.info('Fetching buddy agents', {
|
|
526
|
+
module: CC_FILE,
|
|
527
|
+
method: METHODS.GET_BUDDY_AGENTS,
|
|
528
|
+
});
|
|
529
|
+
try {
|
|
530
|
+
this.metricsManager.timeEvent([
|
|
531
|
+
METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_SUCCESS,
|
|
532
|
+
METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_FAILED,
|
|
533
|
+
]);
|
|
534
|
+
const resp = await this.services.agent.buddyAgents({
|
|
535
|
+
data: {
|
|
536
|
+
agentProfileId: this.agentConfig.agentProfileID,
|
|
537
|
+
mediaType,
|
|
538
|
+
...(buddyAgentState ? {state: buddyAgentState} : {}),
|
|
539
|
+
},
|
|
540
|
+
});
|
|
541
|
+
|
|
542
|
+
this.metricsManager.trackEvent(
|
|
543
|
+
METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_SUCCESS,
|
|
544
|
+
{
|
|
545
|
+
...MetricsManager.getCommonTrackingFieldForAQMResponse(resp),
|
|
546
|
+
mediaType,
|
|
547
|
+
buddyAgentState,
|
|
548
|
+
buddyAgentCount: resp.data.agentList.length,
|
|
549
|
+
},
|
|
550
|
+
['operational']
|
|
551
|
+
);
|
|
552
|
+
|
|
553
|
+
LoggerProxy.log(`Successfully retrieved ${resp.data.agentList.length} buddy agents`, {
|
|
554
|
+
module: CC_FILE,
|
|
555
|
+
method: METHODS.GET_BUDDY_AGENTS,
|
|
556
|
+
trackingId: resp.trackingId,
|
|
557
|
+
});
|
|
558
|
+
|
|
559
|
+
return resp;
|
|
560
|
+
} catch (error) {
|
|
561
|
+
const failureResp = error.details as Failure;
|
|
562
|
+
|
|
563
|
+
this.metricsManager.trackEvent(
|
|
564
|
+
METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_FAILED,
|
|
565
|
+
{
|
|
566
|
+
...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failureResp),
|
|
567
|
+
mediaType,
|
|
568
|
+
buddyAgentState,
|
|
569
|
+
},
|
|
570
|
+
['operational']
|
|
571
|
+
);
|
|
572
|
+
const {error: detailedError} = getErrorDetails(error, METHODS.GET_BUDDY_AGENTS, CC_FILE);
|
|
573
|
+
throw detailedError;
|
|
574
|
+
}
|
|
575
|
+
}
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
When a catch block does not use `getErrorDetails`, at minimum log the error and rethrow:
|
|
579
|
+
|
|
580
|
+
```typescript
|
|
581
|
+
// ❌ WRONG - silently swallowing errors
|
|
582
|
+
try {
|
|
583
|
+
await riskyOperation();
|
|
584
|
+
} catch (error) {
|
|
585
|
+
// doing nothing
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
// ✅ CORRECT - at minimum log the error
|
|
589
|
+
try {
|
|
590
|
+
await riskyOperation();
|
|
591
|
+
} catch (error) {
|
|
592
|
+
LoggerProxy.error(`Operation failed: ${error}`, {
|
|
593
|
+
module: 'ModuleName',
|
|
594
|
+
method: 'methodName',
|
|
595
|
+
});
|
|
596
|
+
throw error;
|
|
597
|
+
}
|
|
598
|
+
```
|
|
599
|
+
|
|
600
|
+
### Events
|
|
601
|
+
|
|
602
|
+
Define events as const objects with `as const`:
|
|
603
|
+
|
|
604
|
+
```typescript
|
|
605
|
+
export const MY_EVENTS = {
|
|
606
|
+
SUCCESS: 'MySuccess',
|
|
607
|
+
FAILED: 'MyFailed',
|
|
608
|
+
} as const;
|
|
609
|
+
|
|
610
|
+
// Extract union type
|
|
611
|
+
type Enum<T extends Record<string, unknown>> = T[keyof T];
|
|
612
|
+
export type MY_EVENTS = Enum<typeof MY_EVENTS>;
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
That is the pattern for WebSocket wire names, where const objects give runtime access to the values:
|
|
616
|
+
`CC_EVENTS = {...CC_AGENT_EVENTS, ...CC_TASK_EVENTS}` in `src/services/config/types.ts` (for example `AGENT_STATE_CHANGE: 'AgentStateChange'`). The names
|
|
617
|
+
the SDK emits to applications are TypeScript enums: `AGENT_EVENTS` in `src/services/agent/types.ts`
|
|
618
|
+
(`'agent:stateChange'`, `'agent:stationLoginSuccess'`, ...), `TASK_EVENTS` in
|
|
619
|
+
`src/services/task/types.ts` (`'task:incoming'`, `'task:hydrate'`, `'task:autoAnswered'`, ...), and
|
|
620
|
+
`VOICE_CONNECTION_EVENTS` in `src/services/config/types.ts`.
|
|
621
|
+
|
|
622
|
+
Always use event constants:
|
|
623
|
+
|
|
624
|
+
```typescript
|
|
625
|
+
import {AGENT_EVENTS} from './services/agent/types';
|
|
626
|
+
|
|
627
|
+
// ✅ CORRECT
|
|
628
|
+
this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE, eventData);
|
|
629
|
+
|
|
630
|
+
// ❌ WRONG
|
|
631
|
+
this.emit('stateChange', eventData);
|
|
632
|
+
```
|
|
633
|
+
|
|
634
|
+
There are two methods for emitting events, `trigger` and `emit`, and which one to use depends on what
|
|
635
|
+
the class extends:
|
|
636
|
+
|
|
637
|
+
| Class extends | Method | `@ts-ignore` needed? | Example classes |
|
|
638
|
+
|---------------|--------|----------------------|-----------------|
|
|
639
|
+
| `WebexPlugin` | `trigger` | Yes | `cc.ts` (ContactCenter) |
|
|
640
|
+
| `EventEmitter` | `emit` | No | Task, TaskManager, WebCallingService, WebSocketManager, ConnectionService |
|
|
641
|
+
|
|
642
|
+
`ContactCenter` extends `WebexPlugin`, whose Ampersand events mixin aliases `emit` to `trigger`; the
|
|
643
|
+
typings expose neither, so both need `// @ts-ignore` on `cc`. `src/cc.ts` uses `trigger` for events it
|
|
644
|
+
forwards from `TaskManager` and `WebCallingService` (`handleIncomingTask`, `handleTaskHydrate`,
|
|
645
|
+
`handleVoiceConnectionStateChange`) and `emit` in `handleWebsocketMessage` for agent events and the
|
|
646
|
+
wellness break. For new code on the `cc` object, use `trigger`, and keep an existing call's method,
|
|
647
|
+
because the specs spy on it.
|
|
648
|
+
|
|
649
|
+
Always store the callback as a named function reference; inline anonymous functions make it
|
|
650
|
+
impossible to call `.off()`. Prefer arrow function properties (`handleWebsocketMessage`, `handleIncomingTask`), which keep `this` and one
|
|
651
|
+
reference; a `.bind(this)` at registration creates a reference that `off()` cannot match. The known
|
|
652
|
+
listener-cleanup defects are recorded in
|
|
653
|
+
[Pitfalls and constraints](src/docs/README.md#pitfalls-and-constraints).
|
|
654
|
+
|
|
655
|
+
Internal services listen to each other: the constructor's `this.$webex.once(READY, ...)` block
|
|
656
|
+
registers the `TaskManager` listeners (`incomingTaskListener()`), `register()` registers the WebSocket
|
|
657
|
+
`message` listener and, through `setupEventListeners()`, the `connectionLost` listener, and
|
|
658
|
+
`deregister()` removes them. Always clean up resources: every `on()` must have a corresponding `off()`
|
|
659
|
+
in the deregister/cleanup path, and an open socket is closed only after checking `isSocketClosed`:
|
|
660
|
+
|
|
661
|
+
```typescript
|
|
662
|
+
public async deregister(): Promise<void> {
|
|
663
|
+
// Remove event listeners
|
|
664
|
+
this.taskManager.off(TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
|
|
665
|
+
this.services.webSocketManager.off('message', this.handleWebsocketMessage);
|
|
666
|
+
|
|
667
|
+
// Close connections
|
|
668
|
+
if (!this.services.webSocketManager.isSocketClosed) {
|
|
669
|
+
this.services.webSocketManager.close(false, 'Unregistering the SDK');
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
// Clear state
|
|
673
|
+
this.agentConfig = null;
|
|
674
|
+
}
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
Applications subscribe on the `cc` object or on task instances. Always use named callbacks so `.off()`
|
|
678
|
+
can reference the same function:
|
|
679
|
+
|
|
680
|
+
```typescript
|
|
681
|
+
const cc = webex.cc;
|
|
682
|
+
|
|
683
|
+
// Define named callbacks (required for .off() to work)
|
|
684
|
+
const handleStateChange = (event) => {
|
|
685
|
+
// handle agent state change
|
|
686
|
+
};
|
|
687
|
+
|
|
688
|
+
const handleLoginSuccess = (event) => {
|
|
689
|
+
// handle login success
|
|
690
|
+
};
|
|
691
|
+
|
|
692
|
+
const handleIncomingTask = (task) => {
|
|
693
|
+
// handle incoming task
|
|
694
|
+
};
|
|
695
|
+
|
|
696
|
+
// Subscribe — agent events (from cc)
|
|
697
|
+
cc.on(AGENT_EVENTS.AGENT_STATE_CHANGE, handleStateChange);
|
|
698
|
+
cc.on(AGENT_EVENTS.AGENT_STATION_LOGIN_SUCCESS, handleLoginSuccess);
|
|
699
|
+
|
|
700
|
+
// Subscribe — task events (from cc)
|
|
701
|
+
cc.on(TASK_EVENTS.TASK_INCOMING, handleIncomingTask);
|
|
702
|
+
|
|
703
|
+
// Unsubscribe — pass the same function reference
|
|
704
|
+
cc.off(AGENT_EVENTS.AGENT_STATE_CHANGE, handleStateChange);
|
|
705
|
+
cc.off(AGENT_EVENTS.AGENT_STATION_LOGIN_SUCCESS, handleLoginSuccess);
|
|
706
|
+
cc.off(TASK_EVENTS.TASK_INCOMING, handleIncomingTask);
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
Events flow through a standard pipeline: receive from transport, parse, log, route, and emit to
|
|
710
|
+
listeners. For `cc`, the Register and Recovery flows in
|
|
711
|
+
[`src/docs/README.md`](src/docs/README.md#data-flow-and-sequence-coverage) and its
|
|
712
|
+
[Protocol and wire format](src/docs/README.md#protocol-and-wire-format) (the `CC_EVENTS` allow-list)
|
|
713
|
+
own the details; the WebSocket transport is in
|
|
714
|
+
[`src/services/core/docs/README.md`](src/services/core/docs/README.md#data-flow-and-sequence-coverage).
|
|
715
|
+
|
|
716
|
+
To add a new event:
|
|
717
|
+
|
|
718
|
+
1. Add the wire constant to the matching `CC_*_EVENTS` object in `src/services/config/types.ts`; it
|
|
719
|
+
joins `CC_EVENTS`, and therefore the re-emit allow-list, through the spread.
|
|
720
|
+
2. Add the application-facing name to `AGENT_EVENTS` (`'agent:...'`) or `TASK_EVENTS` (`'task:...'`).
|
|
721
|
+
3. Handle it in `handleWebsocketMessage` (agent events) or the task WebSocket handling in
|
|
722
|
+
`TaskManager`, using the method rule above.
|
|
723
|
+
4. Document it in the emitting method's JSDoc and export any new payload type from `src/index.ts`.
|
|
724
|
+
|
|
725
|
+
### Services and constants
|
|
726
|
+
|
|
727
|
+
Services use singleton pattern via `Services` class:
|
|
728
|
+
|
|
729
|
+
```typescript
|
|
730
|
+
// Access services through Services singleton
|
|
731
|
+
this.services = Services.getInstance({
|
|
732
|
+
webex: this.$webex,
|
|
733
|
+
connectionConfig: this.getConnectionConfig(),
|
|
734
|
+
});
|
|
735
|
+
|
|
736
|
+
// Use services
|
|
737
|
+
await this.services.agent.stationLogin({data});
|
|
738
|
+
await this.services.config.getAgentConfig(orgId, agentId);
|
|
739
|
+
```
|
|
740
|
+
|
|
741
|
+
`Services` (`src/services/index.ts`) holds `agent` (`routingAgent`), `config` (`AgentConfigService`),
|
|
742
|
+
`contact` (`src/services/task/contact.ts`), `dialer` (`src/services/task/dialer.ts`),
|
|
743
|
+
`webSocketManager`, `rtdWebSocketManager`, and `connectionService`. `ContactCenter` builds it, the
|
|
744
|
+
`TaskManager` and `MetricsManager` singletons, and the single-file services inside its
|
|
745
|
+
`this.$webex.once(READY, ...)` block; non-AQM services are instantiated directly in `cc.ts`. Details:
|
|
746
|
+
[`src/services/docs/README.md`](src/services/docs/README.md).
|
|
747
|
+
|
|
748
|
+
Agent/contact services use factory pattern: an AQM service is a function of `AqmReqs` that returns
|
|
749
|
+
`routing.req` (or `routing.reqEmpty`) request definitions. The real `stateChange` in
|
|
750
|
+
`src/services/agent/index.ts`:
|
|
751
|
+
|
|
752
|
+
```typescript
|
|
753
|
+
stateChange: routing.req((p: {data: Agent.StateChange}) => ({
|
|
754
|
+
url: '/v1/agents/session/state',
|
|
755
|
+
host: WCC_API_GATEWAY,
|
|
756
|
+
data: p.data,
|
|
757
|
+
err,
|
|
758
|
+
method: HTTP_METHODS.PUT,
|
|
759
|
+
notifSuccess: {
|
|
760
|
+
bind: {
|
|
761
|
+
type: CC_EVENTS.AGENT_STATE_CHANGE,
|
|
762
|
+
data: {type: CC_EVENTS.AGENT_STATE_CHANGE_SUCCESS},
|
|
763
|
+
},
|
|
764
|
+
msg: {} as Agent.StateChangeSuccess,
|
|
765
|
+
},
|
|
766
|
+
notifFail: {
|
|
767
|
+
bind: {
|
|
768
|
+
type: CC_EVENTS.AGENT_STATE_CHANGE,
|
|
769
|
+
data: {type: CC_EVENTS.AGENT_STATE_CHANGE_FAILED},
|
|
770
|
+
},
|
|
771
|
+
errId: 'Service.aqm.agent.stateChange',
|
|
772
|
+
},
|
|
773
|
+
})),
|
|
774
|
+
```
|
|
775
|
+
|
|
776
|
+
`method` is optional: `aqm-reqs.ts` defaults to POST when `data` is present and GET otherwise.
|
|
777
|
+
`notifSuccess.bind` and `notifFail.bind` match the WebSocket message `type` and `data.type` that settle
|
|
778
|
+
the promise, and `errId` names the `Err.Details` failure. The flow is HTTP request, backend
|
|
779
|
+
processing, then the WS message: `aqm-reqs` resolves or rejects the promise from that message, and
|
|
780
|
+
`cc.ts` `handleWebsocketMessage()` receives the same message and emits the matching `AGENT_EVENTS`
|
|
781
|
+
name. `getBuddyAgents` works the same way: its result is the `BuddyAgents` WebSocket
|
|
782
|
+
message, not the HTTP response. Methods that call REST directly (`AgentConfigService`, the single-file
|
|
783
|
+
services) use `WebexRequest`.
|
|
784
|
+
|
|
785
|
+
Single-file REST services (`AddressBook.ts`, `EntryPoint.ts`, `Queue.ts`, `UserPreference.ts`) use
|
|
786
|
+
`WebexRequest.getInstance({webex})` for HTTP calls (not raw `webex.request`), `PageCache` for
|
|
787
|
+
pagination, and `MetricsManager` for tracking. Their constructor takes `webex` and, for a profile
|
|
788
|
+
dependency, a getter, as in `new AddressBook(this.$webex, () => this.agentConfig?.addressBookId)`.
|
|
789
|
+
They export the class both named and as default. Study `src/services/AddressBook.ts` or
|
|
790
|
+
`src/services/EntryPoint.ts` as the reference implementation for a new REST service.
|
|
791
|
+
|
|
792
|
+
| Placement | Integration point | Types location | Constants location |
|
|
793
|
+
|---|---|---|---|
|
|
794
|
+
| **Folder-based** | `cc.ts` or `Services` singleton | Service folder's `types.ts` | Service folder's `constants.ts` |
|
|
795
|
+
| **Single-file** | `cc.ts` directly | Root `src/types.ts` | `src/services/constants.ts` |
|
|
796
|
+
| **Sub-module** | Parent service | Parent's `types.ts` | Parent's `constants.ts` |
|
|
797
|
+
|
|
798
|
+
Single-file service types such as `AddressBookEntry`, `EntryPointRecord`, and `ContactServiceQueue`
|
|
799
|
+
are defined in root `src/types.ts`; some live elsewhere (`UserPreference` types are in
|
|
800
|
+
`src/services/config/types.ts`).
|
|
801
|
+
|
|
802
|
+
Folder-based services are `agent/` (`index.ts` and `types.ts`), `config/` (`index.ts`, `types.ts`,
|
|
803
|
+
`constants.ts`, `Util.ts`), `core/`, and `task/`; sub-modules are files inside a service folder, such
|
|
804
|
+
as `task/voice/Voice.ts` and `task/digital/Digital.ts`, which `TaskFactory` instantiates.
|
|
805
|
+
|
|
806
|
+
Constants hierarchy (search in this order before adding one):
|
|
807
|
+
|
|
808
|
+
| Level | File | What lives here | Examples |
|
|
809
|
+
|---|---|---|---|
|
|
810
|
+
| **Root** | `src/constants.ts` | SDK-wide file names, method names, global settings | `CC_FILE`, `TASK_FILE`, `READY`, `METHODS`, `TIMEOUT_DURATION` |
|
|
811
|
+
| **Services shared** | `src/services/constants.ts` | API gateways, auth, network constants shared across services | `WCC_API_GATEWAY`, `POST_AUTH`, `WEBSOCKET_EVENT_TIMEOUT` |
|
|
812
|
+
| **Metrics** | `src/metrics/constants.ts` | All metric event names | `METRIC_EVENT_NAMES` (single object with all events) |
|
|
813
|
+
| **Config** | `src/services/config/constants.ts` | Endpoint maps, pagination defaults, agent states | `endPointMap`, `DEFAULT_PAGE_SIZE`, `AGENT_STATE_AVAILABLE` |
|
|
814
|
+
| **Core** | `src/services/core/constants.ts` | Transport timeouts and keepalive settings | `TIMEOUT_REQ`, `KEEPALIVE_WORKER_INTERVAL` |
|
|
815
|
+
| **Service-specific** | `src/services/task/constants.ts` | Constants used only within that service | `TASK_API`, `HOLD`, `TIMEOUT_PREVIEW_ACCEPT` |
|
|
816
|
+
|
|
817
|
+
Before defining any new constant, search the existing constants hierarchy to check if it already
|
|
818
|
+
exists or belongs at a shared level; duplicates or a constant at the wrong level create drift. For
|
|
819
|
+
each constant: grep for the constant name or value across all `constants.ts` files; if found,
|
|
820
|
+
import from that file and do not redefine it; if not found, add it at the narrowest correct level.
|
|
821
|
+
Create a new `constants.ts` only for a folder-based service that has none and has constants that do
|
|
822
|
+
not belong at a shared level (`agent/` has none). `TASK_FILE` already exists twice, in
|
|
823
|
+
`src/constants.ts` (`'Task'`) and `src/services/task/constants.ts` (`'task'`); `METHODS` exists per
|
|
824
|
+
level (root, config, core, task), so add a method name to the `METHODS` of the file whose module
|
|
825
|
+
logs it.
|
|
826
|
+
|
|
827
|
+
### Public methods and new code placement
|
|
828
|
+
|
|
829
|
+
- The public method lives on the object that owns the feature's scope: `cc` (`src/cc.ts`) for
|
|
830
|
+
SDK-level operations (`cc.stationLogin()`, `cc.setAgentState()`), `task` for per-interaction
|
|
831
|
+
operations (`task.hold()`, `task.transfer()`, `task.end()`). New public objects may be introduced in
|
|
832
|
+
the future. If the feature is internal to a service or only consumed by other services, it gets no
|
|
833
|
+
public method.
|
|
834
|
+
- A public method is either a public wrapper over an internal service call, where the
|
|
835
|
+
implementation lives in a service module and the public method delegates to it (`cc.getBuddyAgents`
|
|
836
|
+
calls `this.services.agent.buddyAgents` with `agentProfileId` from `this.agentConfig`), or a public
|
|
837
|
+
service accessor. Use the public service accessors on `cc` (`cc.addressBook.getEntries()`,
|
|
838
|
+
`cc.queue.getQueues()`), not `cc.services`, which is private; `entryPoint` is private and reached
|
|
839
|
+
through the `cc.getEntryPoints()` wrapper.
|
|
840
|
+
- Task methods are defined on `Task` (`src/services/task/Task.ts`) and overridden per channel in
|
|
841
|
+
`Voice`, `WebRTC`, and `Digital`; the base method calls `unsupportedMethodError` for a channel that
|
|
842
|
+
does not support it (`Voice.hold()` delegates to `holdResume()`, which calls `this.contact.hold`).
|
|
843
|
+
- Feature placement: extend an existing service when the feature naturally extends current service
|
|
844
|
+
responsibility, needs only 1-2 methods in the same domain, or the service already owns the required
|
|
845
|
+
events, state, or API integration. Create a new service or module when the feature introduces a
|
|
846
|
+
distinct domain boundary/responsibility, needs its own lifecycle, dependencies, or state
|
|
847
|
+
orchestration, is expected to grow into multiple related methods/classes, or would create low
|
|
848
|
+
cohesion or cross-domain coupling in an existing service.
|
|
849
|
+
- Emit events only when consumers need to react asynchronously to state changes (WS-driven methods
|
|
850
|
+
like `stationLogin`, `setAgentState`); for a request-response method, the returned Promise is
|
|
851
|
+
sufficient.
|
|
852
|
+
- Types: public types (what consumers see) go in `src/types.ts`; internal/service types (with extra
|
|
853
|
+
fields like `agentProfileId`) go in `src/services/[service]/types.ts`. For example the public
|
|
854
|
+
`BuddyAgents` in `src/types.ts` has optional `mediaType`, `state`, and `action`, while
|
|
855
|
+
`src/services/agent/types.ts` `BuddyAgents` adds the required `agentProfileId`;
|
|
856
|
+
`BuddyAgentsResponse` is `Agent.BuddyAgentsSuccess | Error`. A type is published only when
|
|
857
|
+
`src/index.ts` exports it (`export type {...} from './types'` or from a service `types.ts`).
|
|
858
|
+
- A new top-level public service is a `public` property on `ContactCenter` with JSDoc, created in the
|
|
859
|
+
`this.$webex.once(READY, ...)` block; an AQM service is a new `Services` member created from
|
|
860
|
+
`aqmReq`; a sub-module is created by its parent.
|
|
861
|
+
|
|
862
|
+
### Common bug patterns
|
|
863
|
+
|
|
864
|
+
Trace the execution flow along the call chain plugin → service → core, find where behavior diverges
|
|
865
|
+
from the expected behavior, and check whether existing tests should have caught it.
|
|
866
|
+
|
|
867
|
+
- Async/Promise issues: a service call that is not awaited (`await this.services.agent.stateChange({data})`).
|
|
868
|
+
- Missing error handling: an empty `catch`; route it through `getErrorDetails` and rethrow.
|
|
869
|
+
- Event listener leaks: a listener registered without a stored reference or without a matching
|
|
870
|
+
`off()` (see [Events](#events)).
|
|
871
|
+
- Type mismatches: reading the wrong property of a response; check the actual response type (AQM
|
|
872
|
+
responses such as `StationLoginSuccess` are `Msg` envelopes with the payload under `data`, while
|
|
873
|
+
emitted event payloads are that inner `data`).
|
|
874
|
+
- Missing null checks: the compiler does not enforce them, so use optional chaining
|
|
875
|
+
(`this.agentConfig?.teams?.[0]?.name`).
|
|
876
|
+
|
|
877
|
+
## 6. Git Workflow
|
|
878
|
+
|
|
879
|
+
- Branch naming: no package convention is defined; follow the workspace `CONTRIBUTING.md`.
|
|
880
|
+
- Commit format: conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`), which
|
|
881
|
+
the workspace `CONTRIBUTING.md` requires for pull requests.
|
|
882
|
+
- Keep commits focused and reversible.
|
|
883
|
+
- Rebase on the target branch before opening a pull request.
|
|
884
|
+
|
|
885
|
+
PR checklist:
|
|
886
|
+
|
|
887
|
+
- What changed and why.
|
|
888
|
+
- Tests run and results, including the coverage summary.
|
|
889
|
+
- Risk and impact on applications that use `webex.cc`, task objects, the published types, and the
|
|
890
|
+
`umd/contact-center.min.js` bundle.
|
|
891
|
+
- Rollback approach.
|
|
892
|
+
|
|
893
|
+
### Review checks
|
|
894
|
+
|
|
895
|
+
Run by a runtime different from the generator. Findings remain drafts until explicitly published.
|
|
896
|
+
|
|
897
|
+
| # | Check | What it verifies | Severity if it fails |
|
|
898
|
+
|---|---|---|---|
|
|
899
|
+
| C1 | Spec-currency + WHAT/WHY | Specs/docs and code land together; every requirement states WHAT and WHY | Blocking |
|
|
900
|
+
| C2 | Contract correctness | Provides/Requires and public API/event/type deltas are complete | Blocking |
|
|
901
|
+
| C3 | Code-vs-spec match | Signatures, flows, states, timeouts, and architecture match code | Blocking |
|
|
902
|
+
| C4 | Test adequacy | Positive/negative cases and 85% package threshold | Important |
|
|
903
|
+
| C5 | Error handling/input validation | Structured failures, tracking ids, validation, no swallowed errors | Important |
|
|
904
|
+
| C6 | Security baseline | Host auth, no secrets/sensitive logs, safe transport mapping | Blocking |
|
|
905
|
+
|
|
906
|
+
| # | Check | When it applies | What it verifies | Severity |
|
|
907
|
+
|---|---|---|---|---|
|
|
908
|
+
| K1 | Regression guard | Partial module or modified/removed guarantee | Characterization and invariants | Blocking |
|
|
909
|
+
| K2 | Grounding | Partial module | Stable file-path evidence; code cross-check | Important |
|
|
910
|
+
| K3 | Drift threshold | Any tracked module | Drift remains within policy | Important |
|
|
911
|
+
| K4 | Coverage-state accuracy | Promotion/demotion | Status matches evidence | Medium |
|
|
912
|
+
|
|
913
|
+
| # | Check | What it verifies | Severity |
|
|
914
|
+
|---|---|---|---|
|
|
915
|
+
| X1 | Cross-runtime review | Validator runtime differs from the generator runtime recorded in the manifest `validation` block | Blocking |
|
|
916
|
+
| X2 | Observability | LoggerProxy/metrics adequate; no sensitive logging | Medium |
|
|
917
|
+
| X3 | Rollout safety | Defaults, compatibility, rollback/recovery safe | Important |
|
|
918
|
+
|
|
919
|
+
1. Run all six core checks.
|
|
920
|
+
2. Add K1–K4 for current Partial modules.
|
|
921
|
+
3. Add X1–X3 for high-risk, contract, security, state, transport, or autonomous changes.
|
|
922
|
+
|
|
923
|
+
Output: a compliance matrix, severity-sorted findings, and a Pass / Pass-with-warnings / Blocked
|
|
924
|
+
verdict. Draft only.
|
|
925
|
+
|
|
926
|
+
## 7. Boundaries and Escalation
|
|
927
|
+
|
|
928
|
+
### Always
|
|
929
|
+
|
|
930
|
+
- Prefer existing patterns over introducing new architecture.
|
|
931
|
+
- Keep changes minimal for the requested scope.
|
|
932
|
+
- Call out assumptions and unknowns explicitly.
|
|
933
|
+
- Read-only inspection and approved low-risk documentation maintenance may proceed without asking.
|
|
934
|
+
- Update the owning module spec and contract catalog in the same change as behavior, contracts,
|
|
935
|
+
state, events, or public types.
|
|
936
|
+
- Partial modules require code cross-checking and characterization before risky changes.
|
|
937
|
+
- Load this file, the router, and only the affected module specs; stop on a blocking contract,
|
|
938
|
+
security, source-fidelity, conformance, or validation finding. Generated specs require review by the
|
|
939
|
+
manifest-configured independent runtime.
|
|
940
|
+
- When a new service folder needs its own spec, add it as a manifest module with its spec at the
|
|
941
|
+
module's `docs/README.md` and route it from `docs/specs/README.md` (ask first).
|
|
942
|
+
- Add a rule here when a review correction recurs; remove duplication when tooling enforces it.
|
|
943
|
+
|
|
944
|
+
### Ask First
|
|
945
|
+
|
|
946
|
+
- Code changes, public contract changes, state-machine changes, security-sensitive work, or new
|
|
947
|
+
dependencies.
|
|
948
|
+
- Breaking changes to existing APIs (method signatures, event names, `src/index.ts` exports, type
|
|
949
|
+
fields), with the migration path.
|
|
950
|
+
- Changing AQM bindings, timeouts, or retry and relogin behavior (`allowAutomatedRelogin`,
|
|
951
|
+
`TIMEOUT_REQ`).
|
|
952
|
+
- Renaming or revaluing a `METRIC_EVENT_NAMES` entry, which changes reported telemetry.
|
|
953
|
+
- Running `yarn workspace @webex/contact-center test:e2e`, which drives live Contact Center tenants with credentials from the
|
|
954
|
+
monorepo-root `cc_playwright/.env`.
|
|
955
|
+
- Large refactors, and any destructive data or infrastructure operation.
|
|
956
|
+
|
|
957
|
+
### Never
|
|
958
|
+
|
|
959
|
+
- Push, publish, deploy, delete, or post externally without explicit human approval.
|
|
960
|
+
- Commit secrets, keys, or credentials: API keys, tokens, secrets; passwords or authentication data;
|
|
961
|
+
private keys or certificates. No hardcoded secrets, tokens, keys, or connection strings; never log
|
|
962
|
+
them.
|
|
963
|
+
- Bypass required checks by disabling tests or linters, or lower the coverage threshold.
|
|
964
|
+
- Edit `dist/` or `umd/` by hand.
|
|
965
|
+
- Rewrite history on shared branches.
|
|
966
|
+
- Change unrelated files "while here" without clear need.
|
|
967
|
+
- Add a `.sdd/templates` directory, a copy of the templates, or a link to them in this package. The
|
|
968
|
+
templates live once at the monorepo root, `../../../.sdd/templates/repo-standards`, and
|
|
969
|
+
`.sdd/manifest.json` refers to them through `layout.monorepo_package`.
|