@webex/contact-center 3.13.0-next.1 → 3.13.0-next.11
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 +1065 -339
- package/AGENTS.md +935 -60
- package/dist/webex.js +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
- 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 +10 -9
- package/schemas/repo-context.schema.json +796 -0
- package/src/docs/README.md +727 -0
- package/src/metrics/docs/README.md +710 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/docs/README.md +530 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/docs/README.md +765 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/utils/AGENTS.md +6 -4
- package/src/utils/docs/README.md +413 -0
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
- package/ai-docs/ARCHITECTURE.md +0 -168
- package/ai-docs/CONTRACTS.md +0 -64
- package/ai-docs/GETTING_STARTED.md +0 -168
- package/ai-docs/GLOSSARY.md +0 -43
- package/ai-docs/README.md +0 -138
- package/ai-docs/REVIEW_CHECKLIST.md +0 -41
- package/ai-docs/RULES.md +0 -444
- package/ai-docs/SECURITY.md +0 -52
- package/ai-docs/SERVICE_STATE.md +0 -52
- package/ai-docs/SPEC_INDEX.md +0 -65
- package/ai-docs/adr/0001-spec-source-policy.md +0 -55
- package/ai-docs/adr/README.md +0 -8
- package/ai-docs/adr/_adr-template.md +0 -31
- package/ai-docs/contact-center-spec.md +0 -388
- package/ai-docs/features/contact-owner-change-refactor.md +0 -78
- package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
- package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
- package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
- package/ai-docs/patterns/event-driven-patterns.md +0 -485
- package/ai-docs/patterns/testing-patterns.md +0 -480
- package/ai-docs/patterns/typescript-patterns.md +0 -365
- package/ai-docs/templates/README.md +0 -102
- package/ai-docs/templates/documentation/create-agents-md.md +0 -240
- package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
- package/ai-docs/templates/existing-service/bug-fix.md +0 -254
- package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
- package/ai-docs/templates/new-method/00-master.md +0 -80
- package/ai-docs/templates/new-method/01-requirements.md +0 -232
- package/ai-docs/templates/new-method/02-implementation.md +0 -295
- package/ai-docs/templates/new-method/03-tests.md +0 -201
- package/ai-docs/templates/new-method/04-validation.md +0 -141
- package/ai-docs/templates/new-service/00-master.md +0 -109
- package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
- package/ai-docs/templates/new-service/02-code-generation.md +0 -346
- package/ai-docs/templates/new-service/03-integration.md +0 -178
- package/ai-docs/templates/new-service/04-test-generation.md +0 -205
- package/ai-docs/templates/new-service/05-validation.md +0 -145
- package/src/metrics/ai-docs/AGENTS.md +0 -350
- package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
- package/src/metrics/ai-docs/metrics-spec.md +0 -971
- package/src/services/agent/ai-docs/AGENTS.md +0 -240
- package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
- package/src/services/agent/ai-docs/agent-spec.md +0 -505
- package/src/services/ai-docs/AGENTS.md +0 -386
- package/src/services/ai-docs/services-spec.md +0 -512
- package/src/services/config/ai-docs/AGENTS.md +0 -250
- package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
- package/src/services/config/ai-docs/config-spec.md +0 -669
- package/src/services/core/ai-docs/AGENTS.md +0 -381
- package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
- package/src/services/core/ai-docs/core-spec.md +0 -797
- package/src/services/task/ai-docs/AGENTS.md +0 -457
- package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
- package/src/services/task/ai-docs/task-spec.md +0 -1501
- package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
- package/src/utils/ai-docs/utils-spec.md +0 -391
|
@@ -0,0 +1,727 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: Module Spec
|
|
3
|
+
title: 'Contact Center plugin specification'
|
|
4
|
+
description: Responsibilities, boundaries, design, state, invariants, and verification for the ContactCenter WebexPlugin (webex.cc) and the package entry of @webex/contact-center.
|
|
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
|
+
# Contact Center plugin
|
|
17
|
+
|
|
18
|
+
This source-local document at `src/docs/README.md` owns the stable specification for **the Contact
|
|
19
|
+
Center plugin**: the `ContactCenter` WebexPlugin registered as `webex.cc`, the package entry
|
|
20
|
+
`src/index.ts`, the standalone `Webex` constructor in `src/webex.js`, and the package-level config,
|
|
21
|
+
constants, types, and logger. The transport, agent, configuration, task, and calling collaborators
|
|
22
|
+
belong to the [services module](../services/docs/README.md); telemetry to the
|
|
23
|
+
[metrics module](../metrics/docs/README.md); pagination caching to the
|
|
24
|
+
[utils module](../utils/docs/README.md). Ground every claim in package evidence and link to the
|
|
25
|
+
[package architecture](../../docs/architecture.md) instead of repeating broader facts. No service
|
|
26
|
+
specification exists because this package is a client library.
|
|
27
|
+
|
|
28
|
+
Related context: [documentation index](../../docs/index.md) ·
|
|
29
|
+
[package agent instructions](../../AGENTS.md)
|
|
30
|
+
|
|
31
|
+
## Metadata
|
|
32
|
+
|
|
33
|
+
| Field | Value |
|
|
34
|
+
|---|---|
|
|
35
|
+
| Owner | @webex/web-sdk |
|
|
36
|
+
| Source path | `src` |
|
|
37
|
+
| Resource kind | package |
|
|
38
|
+
| Status | Active |
|
|
39
|
+
| Last verified | 2026-11-16 at `0b8c34db7f` |
|
|
40
|
+
| Module id | `contact-center` |
|
|
41
|
+
| Parent spec | — |
|
|
42
|
+
| Doc kind | Module spec |
|
|
43
|
+
| Coverage score | Pending coverage assessment |
|
|
44
|
+
| Validation status | pass-with-warnings — assessed 2026-11-17; validator runtime 01a1e76f-2293-79a0-9f8f-f060038448dd; 0 Blocking, 0 Important, 4 Minor findings. |
|
|
45
|
+
|
|
46
|
+
## Applicability
|
|
47
|
+
|
|
48
|
+
| Condition ID | Status | Evidence or reason | Owned section |
|
|
49
|
+
| ------------ | ------ | ------------------ | ------------- |
|
|
50
|
+
| `module.has_tiers` | N/A | No tier policy exists in `package.json` or under src | Tier |
|
|
51
|
+
| `module.has_ui` | N/A | `src/cc.ts` renders nothing; every public method returns a promise or a value. The browser sample lives outside this package | UI use-case flow |
|
|
52
|
+
| `module.crosses_service_boundaries` | Applicable | `src/cc.ts` drives the Contact Center REST gateway and notification WebSockets through Services, Mercury, and the Webex device | Cross-boundary use-case flow |
|
|
53
|
+
| `module.holds_client_state` | Applicable | `src/cc.ts` keeps the agent profile, wellness session, idle-code cache, wxApp flags, and listener registrations in memory | Client state model |
|
|
54
|
+
| `module.enforces_domain_rules` | Applicable | Preview skip and remove guards, the event allow-list, the Available voice guard, and wellness identity checks in `src/cc.ts` | Business rules and invariants |
|
|
55
|
+
| `module.is_concurrent_async` | Applicable | `src/cc.ts` reacts to READY, WebSocket messages, TaskManager events, and ConnectionService events | Concurrency and reactive flow |
|
|
56
|
+
| `module.owns_persistence` | N/A | Nothing under src writes durable storage; `src/webex-config.ts` selects memory store adapters | Data, schema, and migration discipline |
|
|
57
|
+
| `module.stateful_transitions` | Applicable | Bootstrap, register, recovery, and deregister lifecycle in `src/cc.ts` | State machine |
|
|
58
|
+
| `module.exposes_wire_protocol` | Applicable | Subscribe request, Welcome event, notification envelopes, and Wellness_Break_Handler parsing in `src/cc.ts` and `src/constants.ts` | Protocol and wire format |
|
|
59
|
+
| `module.ui_multi_screen` | N/A | No UI | UI flow |
|
|
60
|
+
| `module.large_data_model` | N/A | The large payload types belong to child modules; `src/types.ts` holds request, config, and event shapes only | Data model |
|
|
61
|
+
| `module.returns_caller_errors` | Applicable | `src/cc.ts` rethrows detailed errors from getErrorDetails and throws local validation errors | Caller-visible failure modes |
|
|
62
|
+
| `module.module_specific_conventions` | Applicable | LoggerProxy context, metric timing, and error wrapping repeated by every public method of `src/cc.ts` | Module-specific rules |
|
|
63
|
+
| `module.published_package` | Applicable | `package.json` names @webex/contact-center and declares main, exports, types, and the deploy:npm script | Export stability |
|
|
64
|
+
| `module.embedded_in_host` | Applicable | `src/index.ts` registers the plugin into a host Webex SDK instance | Host integration and theming |
|
|
65
|
+
| `module.has_design_tradeoff` | Applicable | `src/cc.ts` is one façade over many collaborators that it builds at READY | Key design trade-off |
|
|
66
|
+
| `module.has_submodules` | Applicable | The metrics, services, and utils folders under src own their own specs (has_submodules computed by module_tree.py) | Sub-modules |
|
|
67
|
+
|
|
68
|
+
## Evidence register
|
|
69
|
+
|
|
70
|
+
Every requirement cites stable source and test file paths. Code and tests are the behavioral referee;
|
|
71
|
+
missing or contradictory evidence blocks promotion.
|
|
72
|
+
|
|
73
|
+
| Evidence | What it establishes |
|
|
74
|
+
| -------- | ------------------- |
|
|
75
|
+
| `src/cc.ts` | `ContactCenter` (namespace `cc`): READY-time construction, `register`, `deregister`, station login and logout, agent state, preview campaign, outdial, wellness, voice readiness, wxApp Better Together, WebSocket routing, and silent relogin; its JSDoc and comments are the recorded rationale. It also justifies the extension subsections under Design overview (Agent Wellness Break, wxApp Better Together) and under Data flow and sequence coverage (Bootstrap, Register, Deregister, Recovery, Station login, logout, and agent state, Preview campaign and outdial, Wellness notifications) |
|
|
76
|
+
| `src/index.ts` | `registerPlugin('cc', ContactCenter, {config})` and the root barrel of classes, enums, value objects, and types |
|
|
77
|
+
| `src/webex.js` | The npm `main`: side-effect imports of authorization, Mercury, logger, support, and `./index`; `WebexCore.extend`; `Webex.init` merge; constants attached to the constructor |
|
|
78
|
+
| `src/config.ts` | Registered plugin defaults under `cc` |
|
|
79
|
+
| `src/webex-config.ts` | Standalone constructor defaults (Hydra URL, device, memory storage) |
|
|
80
|
+
| `src/constants.ts` | `READY`, `WELLNESS_BREAK_HANDLER`, `DEFAULT_VOICE_CONNECTION_STATE`, `METHODS`, `AI_SUMMARY_ERROR_CODES`, outdial constants |
|
|
81
|
+
| `src/types.ts` | `IContactCenter`, `CCPluginConfig`, `WebexSDK`, `LoginOption`, voice connection enums, wellness value objects, `GenericError` |
|
|
82
|
+
| `src/logger-proxy.ts` | Static `LoggerProxy` that formats every log line with `PLUGIN_CC`, module, method, and optional ids |
|
|
83
|
+
| `src/services/ApiAiAssistant.ts` | Wellness action validation and the direct `/event` POST that must return 202 |
|
|
84
|
+
| `src/services/config/Util.ts` | The `isWellnessBreakEnabled` gate computed from the AI feature row and the organization licence count |
|
|
85
|
+
| `src/services/WebCallingService.ts` | Voice connection snapshot, readiness check, and reset on line deregistration |
|
|
86
|
+
| `package.json` | Name, `main`, `exports`, `types`, `devMain`, dependencies, and scripts |
|
|
87
|
+
| `jest.config.js` | 85% global branch, function, line, and statement threshold |
|
|
88
|
+
| `test/unit/spec/cc.ts` | ContactCenter behavior: construction, register, station login and logout, agent state, wellness contracts, buddy agents, silent relogin, outdial, queues, upload logs, deregister, WebSocket events, API properties, profile update, outdial ANI, preview campaign, and the private wxApp toggle |
|
|
89
|
+
| `test/unit/spec/index.ts` | TypeScript-compiler checks of the exact root export list, rejected internals, AI summary literals, and retained ITask signatures |
|
|
90
|
+
| `test/unit/spec/logger-proxy.ts` | LoggerProxy formatting |
|
|
91
|
+
| `test/unit/spec/wellnessSampleUtils.ts` | Transition helpers and surface guards of the monorepo wellness browser sample |
|
|
92
|
+
|
|
93
|
+
## Purpose and boundary
|
|
94
|
+
|
|
95
|
+
Contact Center is one of nine confirmed Contact Center SDK modules and the root of the module tree.
|
|
96
|
+
|
|
97
|
+
- Responsibility: Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing.
|
|
98
|
+
- In scope: the `ContactCenter` plugin and its public methods and properties; plugin registration and
|
|
99
|
+
the root barrel; the standalone `Webex` constructor; plugin config validation and defaults;
|
|
100
|
+
WebSocket message mapping to SDK events; wellness notification normalization; relogin policy;
|
|
101
|
+
wxApp Better Together session hooks; `LoggerProxy`.
|
|
102
|
+
- Out of scope: request/notification correlation, sockets, and REST clients (services); task
|
|
103
|
+
objects and the task state machine (services task modules); metric submission (metrics);
|
|
104
|
+
page caching (utils); backend records, which remain owned by Webex Contact Center.
|
|
105
|
+
- Consumers: agent desktop applications and widgets through `webex.cc`, script-tag pages through the
|
|
106
|
+
UMD bundle `umd/contact-center.min.js`, and the monorepo browser sample.
|
|
107
|
+
|
|
108
|
+
The `@webex/contact-center` package is a Webex SDK plugin that provides a TypeScript/JavaScript API for building Contact Center agent applications. It enables:
|
|
109
|
+
|
|
110
|
+
- **Agent Session Management**: Register, login, logout, state changes
|
|
111
|
+
- **Task Handling**: Inbound/outbound calls, chat, transfers, conferences
|
|
112
|
+
- **Real-time Events**: WebSocket-based notifications for agent and task events
|
|
113
|
+
- **Browser-based Calling**: WebRTC integration for browser softphone
|
|
114
|
+
- **Metrics & Diagnostics**: Built-in telemetry and log upload
|
|
115
|
+
|
|
116
|
+
Answer on Webex, Agent Wellness Break, and browser voice readiness are listed as Public surface rows.
|
|
117
|
+
|
|
118
|
+
## Structure and key files
|
|
119
|
+
|
|
120
|
+
| Path | Responsibility |
|
|
121
|
+
| ---- | -------------- |
|
|
122
|
+
| `src/index.ts` | Package entry: Contact Center root exports and the `registerPlugin('cc', ContactCenter, {config})` call |
|
|
123
|
+
| `src/cc.ts` | The `ContactCenter` WebexPlugin class: façade and lifecycle orchestration |
|
|
124
|
+
| `src/types.ts` | Package-level public types and value objects (`IContactCenter`, `CCPluginConfig`, `LoginOption`, voice enums, wellness value objects) |
|
|
125
|
+
| `src/constants.ts` | Package constants: `READY`, `WELLNESS_BREAK_HANDLER`, `METHODS`, `DEFAULT_VOICE_CONNECTION_STATE`, `AI_SUMMARY_ERROR_CODES` |
|
|
126
|
+
| `src/config.ts` | Registered plugin defaults: `allowMultiLogin` false, `allowAutomatedRelogin` true, `disableWebRTCRegistration` false, `enableWxBetterTogether` false, `clientType` `WebexCCSDK`, `isKeepAliveEnabled` false, `force` true, metrics client name and type |
|
|
127
|
+
| `src/logger-proxy.ts` | Static logger that drops messages until `initialize` and formats each line as timestamp, `PLUGIN_CC`, level, module, method, ids, data, and error |
|
|
128
|
+
| `src/webex.js` | npm `main` and UMD entry: `Webex` constructor, `Webex.init`, constants attached for browser samples |
|
|
129
|
+
| `src/webex-config.ts` | Standalone defaults: Hydra URL, ephemeral validated device, memory storage adapters |
|
|
130
|
+
| `src/docs/README.md` | This module specification |
|
|
131
|
+
| `src/services/UserPreference.ts` | User-preference CRUD implementation exposed through `cc.userPreference` (services module) |
|
|
132
|
+
| `src/services/task/dialer.ts` | Preview-campaign AQM request implementations (services task module) |
|
|
133
|
+
| `src/services/task/types.ts` | `PreviewContactPayload`, `DropConferenceParticipantPayload`, `TaskResponse`, and task contract types (services task module) |
|
|
134
|
+
| `package.json` | Package name, entry points, scripts, dependencies |
|
|
135
|
+
| `jest.config.js` | Jest configuration and the coverage threshold |
|
|
136
|
+
| `typedoc.json` | API reference build from `src/index.ts` |
|
|
137
|
+
| `umd/contact-center.min.js` | Tracked UMD build of `src/webex.js` (workspace webpack entry `contact-center`) |
|
|
138
|
+
| `test/unit/spec/cc.ts` | ContactCenter unit cases |
|
|
139
|
+
| `test/unit/spec/index.ts` | Root barrel contract cases |
|
|
140
|
+
|
|
141
|
+
The three child-module rows name files that back façade methods; their behavior is specified by the
|
|
142
|
+
child module that owns them (Sub-modules). dist/ is generated by `build:src` and never edited by hand.
|
|
143
|
+
|
|
144
|
+
## Sub-modules
|
|
145
|
+
|
|
146
|
+
| Sub-module | Responsibility | Specification |
|
|
147
|
+
| ---------- | -------------- | ------------- |
|
|
148
|
+
| `src/metrics` | `MetricsManager` and the metric event taxonomy used by every ContactCenter method | [metrics module spec](../metrics/docs/README.md) |
|
|
149
|
+
| `src/services` | Services composition root, transport core, agent, config, task, calling, wxApp, AI assistant, address book, entry point, queue, and user preference clients | [services module spec](../services/docs/README.md) |
|
|
150
|
+
| `src/utils` | `PageCache` and pagination defaults | [utils module spec](../utils/docs/README.md) |
|
|
151
|
+
|
|
152
|
+
## Public surface
|
|
153
|
+
|
|
154
|
+
| Contract ID | Type | Surface | Purpose | Compatibility / deprecation | Schema / detail link | Root index |
|
|
155
|
+
|---|---|---|---|---|---|---|
|
|
156
|
+
| `contact-center-sdk` | SDK / event / internal API | Published `@webex/contact-center` exports and the `ContactCenter` (`cc`) WebexPlugin API. | Stable module consumption boundary. | Additive changes by default; breaking package exports require a major-version transition. | `src/index.ts`, `package.json` | [package architecture](../../docs/architecture.md) |
|
|
157
|
+
| `contact-center-sdk` | SDK API / event | `getVoiceConnectionState()`, `voice:connectionStateChange`, and exported voice status/error symbols. | Let hosts observe local browser voice readiness and allow the SDK to reject only transitions into `Available` while required voice is unavailable. | Additive API/event; local login controls requirement and line deregistration on station logout resets the snapshot. | `src/cc.ts`, `src/services/WebCallingService.ts`, `src/types.ts`, `src/services/config/types.ts` | [package architecture](../../docs/architecture.md) |
|
|
158
|
+
| `contact-center-sdk` | SDK data API | Existing `getQueues` and `getEntryPoints` methods, their existing search/response types, and full `ContactServiceQueue` / `EntryPointRecord` rows. | Provide consult/transfer telephony defaults without adding a parallel list API or projected destination model. | Defaults are overridable through the existing filter/sort/profile parameters; full record types remain the response contract. | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/types.ts` | [package architecture](../../docs/architecture.md) |
|
|
159
|
+
| `contact-center-sdk` | SDK task control API | Ordered `TaskUIControls.consultTransferDestinations` arrays using the existing destination values. | Give all Task consumers the same ordered, action-specific destination visibility without a second policy call. | Additive public field; consumers may hide SDK-allowed categories but must not enable omitted categories. | `src/cc.ts`, `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts`, `src/index.ts` | [package architecture](../../docs/architecture.md) |
|
|
160
|
+
| `contact-center-sdk` | SDK data API | Exported `UserPreference`, `cc.userPreference`, and user-preference request/response types. | Read and mutate user preferences through authenticated REST operations. | Additive public API; removals or signature changes are breaking. | `src/services/UserPreference.ts`, `src/services/config/types.ts` | [package architecture](../../docs/architecture.md) |
|
|
161
|
+
| `contact-center-sdk` | SDK task API | `acceptPreviewContact`, `skipPreviewContact`, `removePreviewContact`. | Resolve campaign preview reservations through typed AQM operations. | Additive public API; removals or signature changes are breaking. | `src/cc.ts`, `src/services/task/dialer.ts`, `src/services/task/types.ts` | [package architecture](../../docs/architecture.md) |
|
|
162
|
+
| `contact-center-sdk` | SDK task API | Exported `DropConferenceParticipantPayload` and `ITask.dropConferenceParticipant`. | Remove a conference participant through the media-specific task implementation and correlated AQM completion. | Additive public API; removals or signature changes are breaking. | `src/index.ts`, `src/services/task/types.ts`, `src/services/task/voice/Voice.ts` | [package architecture](../../docs/architecture.md) |
|
|
163
|
+
| `contact-center-sdk` | SDK API / events | `Profile.isWellnessBreakEnabled`, `cc.apiAIAssistant.requestWellnessBreak`, `cc.apiAIAssistant.respondToWellnessBreak`, `getWellbeingBreakIdleCode`, and the wellness notification event contract. | Let hosts implement the public wellness-break lifecycle without reproducing backend payloads, routing rules, or session validation. | Additive public API; the effective gate is false unless all supported configuration inputs are affirmative. | `src/cc.ts`, `src/types.ts`, `src/services/ApiAiAssistant.ts`, `src/services/config/types.ts` | [package architecture](../../docs/architecture.md) |
|
|
164
|
+
| `contact-center-sdk` | SDK API / config | `enableWxBetterTogether` init flag and `isWxBetterTogetherEnabled()` (wxApp Better Together, WXCC-6026). | Let hosts opt into Webex App answer, mute, and DTMF routing at init and read the flag. | Init-only in Phase 1; the private runtime setter is not public. | `src/cc.ts`, `src/config.ts`, `src/types.ts` | [package architecture](../../docs/architecture.md) |
|
|
165
|
+
| `contact-center-sdk` | SDK entry | Package `main` and `exports['.']`: `dist/webex.js`, the `Webex` constructor with `Webex.init(attrs)`, the re-exported barrel, and `Webex.CC_AGENT_EVENTS`, `Webex.WELLNESS_BREAK_NOTIFICATION_ACTIONS`, `Webex.WELLNESS_BREAK_USER_ACTIONS`. | One import gives a configured SDK with `webex.cc`; the UMD build exposes the constants to script-tag pages. | Default export `Webex`; `types` points at the declarations of `src/index.ts`. | `src/webex.js`, `package.json` | [package architecture](../../docs/architecture.md) |
|
|
166
|
+
| `contact-center-cc-events` | Event enums | `CC_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `VOICE_CONNECTION_EVENTS` re-exported from the root. | Name the notification types the plugin re-emits and the voice state event. | Additive values; renames are breaking. | `src/services/config/types.ts`, `src/index.ts` | [package architecture](../../docs/architecture.md) |
|
|
167
|
+
| `contact-center-agent-events` | Event enum and types | `AGENT_EVENTS` (also as type `AgentEvents`) and the agent request/response types re-exported from the root. | Name the agent events `cc` emits after mapping notifications. | Additive values; renames are breaking. | `src/services/agent/types.ts`, `src/index.ts` | [package architecture](../../docs/architecture.md) |
|
|
168
|
+
| `contact-center-task-events` | Event enum and types | `TASK_EVENTS` (also as type `TaskEvents`), `ITask`, `TaskData`, `TaskResponse`, the task payload and UI-control types, and `getDefaultUIControls`. | Name the task events `cc` and Task emit and the task payload contracts. | Additive values; renames are breaking. | `src/services/task/types.ts`, `src/index.ts` | [package architecture](../../docs/architecture.md) |
|
|
169
|
+
|
|
170
|
+
The contracts are indexed in the [package architecture](../../docs/architecture.md). The event
|
|
171
|
+
contracts are owned by the services modules that declare them; this module re-exports them.
|
|
172
|
+
|
|
173
|
+
## Dependencies
|
|
174
|
+
|
|
175
|
+
| Dependency | Why it is required | Failure behavior |
|
|
176
|
+
| ---------- | ------------------ | ---------------- |
|
|
177
|
+
| Webex SDK host/plugin lifecycle (`@webex/webex-core`, contract `webex-core-plugin-runtime`) | `WebexPlugin`, `registerPlugin`, `webex.request`, credentials, logger, and the `ready` event | Nothing is constructed until READY; a config validation error thrown in the READY handler leaves the plugin without collaborators |
|
|
178
|
+
| Contact Center REST and WebSocket backends (`wxcc-api-gateway`, `wxcc-websocket-notifications`) | Agent, task, configuration, and AI assistant operations and the notifications that settle them | Errors are rethrown as detailed errors; see Caller-visible failure modes |
|
|
179
|
+
| Services, TaskManager, MetricsManager, WebCallingService, UserPreference, and data-service modules | Collaborators the façade delegates to (services and metrics modules) | Their rejections propagate through `getErrorDetails` |
|
|
180
|
+
| `@webex/calling` (contract `webex-calling-sdk`) | Browser line registration for BROWSER login, used through WebCallingService | Line registration failure fails station login or silent relogin |
|
|
181
|
+
| `@webex/internal-plugin-mercury` (contract `webex-internal-mercury`) and the Webex device | Mercury for browser calling and for wxApp mute sync | A `mercury.connect()` failure during register is logged and contained; wxApp failures roll back without failing login |
|
|
182
|
+
| `@webex/internal-plugin-support` (contract `webex-internal-support`) | Log upload through WebexRequest | `uploadLogs()` rejects with the support error |
|
|
183
|
+
| `@webex/plugin-authorization`, `@webex/plugin-logger` | Loaded by `src/webex.js` for the standalone constructor | A missing install fails at import time |
|
|
184
|
+
|
|
185
|
+
## Requirements
|
|
186
|
+
|
|
187
|
+
| ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
|
|
188
|
+
|---|---|---|---|---|---|---|
|
|
189
|
+
| CONTACT_CENTER-R-001 | Construct the service graph once after the host Webex SDK emits READY, before `register()` is invoked. | Collaborators require initialized host request, logger, and plugin configuration state. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; the READY handler and its construction assertions were rechecked at 0b8c34db7f. | PRESENT |
|
|
190
|
+
| CONTACT_CENTER-R-002 | `register()` must attach connection/message listeners, connect the primary WebSocket, and return the fetched Profile or rethrow a logged failure. A failure also tracks the register-failed metric and starts a log upload correlated with the error tracking id. | Applications need an explicit readiness boundary and must never observe a synthetic successful registration. | `src/cc.ts` | `test/unit/spec/cc.ts` | The log upload is started without being awaited. | PRESENT |
|
|
191
|
+
| CONTACT_CENTER-R-003 | Delegate agent, task, data, user-preference, preview-campaign, AI-assistant, calling, and telemetry behavior to their owning collaborators while preserving typed package methods and events. Existing `getQueues` and `getEntryPoints` delegate to their services with unchanged signatures and full-record responses; the services own consult/transfer telephony filter, profile-view, ordering, and cache defaults while honoring explicit existing-parameter overrides. Before preview delegation, reject disabled skip/remove actions from task campaign flags. | A thin stable façade avoids parallel consumer APIs while service-owned defaults keep ordinary widget calls consistent and preserve an override path for other consumers. | `src/cc.ts`, `src/types.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/UserPreference.ts`, `src/services/task/dialer.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/UserPreference.ts`, `test/unit/spec/services/task/dialer.ts` | Public preview delegation is covered; the `campaignPreviewSkipDisabled` and `campaignPreviewRemoveDisabled` early-exit guards still lack direct unit coverage (the skip and remove cases cover success and failure only). | PRESENT |
|
|
192
|
+
| CONTACT_CENTER-R-004 | `deregister()` must remove registered listeners, stop applicable host/calling resources, close primary and RTD WebSockets, clear agent configuration, and surface cleanup failures, including a wxApp usersub publish error that it rethrows after local cleanup. | Listener or connection leaks create duplicate events and stale authenticated sessions in long-lived hosts. | `src/cc.ts` | `test/unit/spec/cc.ts` | Known defects in current code: the `connectionLost` listener and the `TASK_MERGED` listener are not removed, and a call without agent configuration throws before the sockets close (Pitfalls and constraints). | WEAK |
|
|
193
|
+
| CONTACT_CENTER-R-005 | On a `connectionLost` event that reports `isSocketReconnected`, ContactCenter must own recovery policy and invoke private `silentRelogin()` only when automated relogin is allowed; an event that reports `isConnectionLost` is only logged. | ConnectionService reports transport state; only ContactCenter has agent profile and policy context for authentication recovery. | `src/cc.ts` | `test/unit/spec/cc.ts` | `handleConnectionLost` has no direct unit case; the `silentRelogin` cases cover reload, `AGENT_NOT_FOUND`, errors, device types, and usersub publication. | PRESENT |
|
|
194
|
+
| CONTACT_CENTER-R-006 | Expose Agent Wellness Break actions through `cc.apiAIAssistant` (`requestWellnessBreak`, `respondToWellnessBreak`), the lookup `cc.getWellbeingBreakIdleCode()`, and the action-value objects and types through the package exports. Derive the public action unions from those `as const` value objects. Action calls accept no identity or context-mutating API; ApiAIAssistant reads effective enablement and agent/session identity from a read-only provider supplied by ContactCenter at construction, reads the organization from the Webex credentials, and rejects when that context is incomplete. Logout, deregistration entry, a current-session multi-login close, and relogin update the provider's source state. The exact system idle-code cache and its in-flight lookup are owned by one registration generation; a newer registration or deregistration rejects a late result instead of caching it. | Wellness actions and cached configuration are registration-scoped and must not leak across agents, relogins, multi-login closures, organizations, or registrations; one public value/type source prevents wire-value drift. | `src/cc.ts`, `src/types.ts`, `src/services/ApiAiAssistant.ts`, `src/index.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | The backend-delivered `agentWellbeing.enable` value is treated as the server rollout decision because no distinct rollout field exists in the supported SDK response contracts. | PRESENT |
|
|
195
|
+
| CONTACT_CENTER-R-007 | When wellness is effectively enabled, connect the RTD WebSocket even if transcripts and suggested responses are disabled. Route valid `Wellness_Break_Handler` messages from the primary or RTD data-notification socket to `CC_AGENT_EVENTS.WELLNESS_BREAK`. Notification eligibility is scoped to the current agent and organization and deliberately does not compare the notification-provided `agentSessionId` with the active session; outbound wellness APIs remain active-session validated. Ignore malformed or foreign-identity messages without logging the full payload. | A long-lived host needs parity with Desktop notification routing without dropping legitimate nudges whose backend session metadata differs, while actions must still be sent only for the active local session. | `src/cc.ts`, `src/constants.ts`, `src/services/config/types.ts`, `src/services/ApiAiAssistant.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | Notification delivery remains best-effort; the backend owns offer generation and ordering. | PRESENT |
|
|
196
|
+
| CONTACT_CENTER-R-008 | The standalone constructor in `src/webex.js` exposes `CC_AGENT_EVENTS`, `WELLNESS_BREAK_NOTIFICATION_ACTIONS`, and `WELLNESS_BREAK_USER_ACTIONS` as static properties of `Webex`, so the UMD bundle gives script-tag pages, including the monorepo wellness browser sample, the same wire values as module consumers. The sample's own lifecycle is an external consumer flow (Use cases and flows), not a requirement of this module. | The `src/webex.js` comment: browser samples must use the same constants as module consumers, which avoids duplicated wire literals. | `src/webex.js`, `src/types.ts`, `src/services/config/types.ts` | `test/unit/spec/wellnessSampleUtils.ts` | The surface guard case checks the constants the sample consumes; no unit case loads `src/webex.js` itself. | PRESENT |
|
|
197
|
+
| CONTACT_CENTER-R-009 | Expose `getVoiceConnectionState()` and `voice:connectionStateChange` through the Contact Center package façade. Track local browser line registration separately from Mobius socket status; mark voice required only when the local BROWSER login enables WebRTC registration; preserve the socket failure reason across line keepalive events; detach all line listeners and reset the snapshot on logout. Keep the `REGISTERED` listener active for later registration recovery. Preserve browser line registration during silent relogin unless `disableWebRTCRegistration` is enabled, even when voice is not required by the profile. Clear a stale local voice requirement when a station login notification reports `EXTENSION` or `AGENT_DN`. Reject only transitions into `Available` while required browser voice is unavailable, and send the `BROWSER_VOICE_NOT_READY` validation error through the existing failure metric/log path. | Contact Center hosts need reliable local readiness signals and agents must be able to leave `Available` during outages; multi-login notifications from another SDK instance must not create or retain a false local requirement. | `src/cc.ts`, `src/services/WebCallingService.ts`, `src/types.ts`, `src/services/config/types.ts`, `src/index.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/WebCallingService.ts` | The sample displays the current state; registration retries and socket recovery are reflected independently. | PRESENT |
|
|
198
|
+
| CONTACT_CENTER-R-010 | Importing the package registers `ContactCenter` as public plugin `cc` with the `src/config.ts` defaults, and `src/index.ts` exports exactly the root barrel list pinned by `test/unit/spec/index.ts`, without the AI-summary internals (`AIAssistantEventName`, `AISummaryTimeoutCodeByInboundType`, `AI_SUMMARY_DURATION_MS`, `AI_SUMMARY_REQUEST_CANCELLED`, `AI_ASSISTANT_CLIENT_TYPE`). The npm `main` is the built `src/webex.js`, which imports authorization, Mercury, logger, and support and re-exports the barrel. | Applications reach the API as `webex.cc`; the barrel test fails on any added, removed, or leaked export so the published surface changes only deliberately. | `src/index.ts`, `src/webex.js`, `src/config.ts`, `package.json` | `test/unit/spec/index.ts` | No unit case loads `src/webex.js` itself. | PRESENT |
|
|
199
|
+
| CONTACT_CENTER-R-011 | `enableWxBetterTogether` (default false) is an init-only flag read by `isWxBetterTogetherEnabled()`. After station login and silent relogin, ContactCenter applies the wxApp session hooks described under Design overview without failing the login, and `deregister()` clears the flag. | The private setter's JSDoc makes the init flag the Phase 1 host contract and keeps the runtime toggle internal; usersub state suppresses Webex App toasts, so a stale value must be cleared after a page refresh. | `src/cc.ts`, `src/config.ts`, `src/services/WebexCrossClientService.ts`, `src/services/WxAppTelephonyMercurySync.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/WebexCrossClientService.ts`, `test/unit/spec/services/WxAppTelephonyMercurySync.ts` | Compatibility with `allowMultiLogin: true` is stated by the design but has no dedicated case. | PRESENT |
|
|
200
|
+
| CONTACT_CENTER-R-012 | At READY, ContactCenter throws `Invalid Contact Center configuration: disableWebRTCRegistration cannot be true when allowMultiLogin is false. …` when that combination is configured, before any collaborator is created. The subscribe request carries `force`, `isKeepAliveEnabled`, `clientType`, and `allowMultiLogin` from the plugin config. | The error text states the reason: an SDK instance can receive Mobius/WebRTC task events only when it registers WebRTC or allows multi-login. | `src/cc.ts`, `src/config.ts`, `src/types.ts` | `test/unit/spec/cc.ts` | `getConnectionConfig` falls back to `allowMultiLogin` true when no config is present, while the registered default is false. | PRESENT |
|
|
201
|
+
|
|
202
|
+
## Design overview
|
|
203
|
+
|
|
204
|
+
`ContactCenter` is the package façade and lifecycle owner. Its constructor waits for the host Webex SDK `READY` event, validates plugin configuration, initializes `WebexRequest`, obtains the singleton `Services` graph, and constructs calling, wxApp (AnswerCallOnWebexService, WebexCrossClientService, WxAppTelephonyMercurySync), AI-assistant, metrics, task-management, `UserPreference`, and data-service collaborators. `register()` is deliberately narrower: it attaches runtime listeners and establishes the primary Contact Center WebSocket subscription.
|
|
205
|
+
|
|
206
|
+
Direct data/configuration and user-preference operations return authenticated REST responses. Enabled agent/task AQM operations, including preview-campaign accept/skip/remove, send authenticated HTTP requests but resolve or reject only after a matching WebSocket notification. Before delegating preview skip/remove, ContactCenter checks the task's campaign-disable flags and throws locally when the corresponding flag is `'true'`. TaskManager converts backend task events into Task instances and typed state-machine events. ContactCenter maps package-facing events through WebexPlugin `trigger` (task and voice events) or WebexPlugin `emit` (WebSocket agent events and wellness events); the private `eventEmitter` it constructs is not used.
|
|
207
|
+
|
|
208
|
+
Stack: TypeScript 5.4, WebexPlugin, Node EventEmitter, WebSocket/WebRTC integrations, Jest 27, Yarn 3.4.1.
|
|
209
|
+
|
|
210
|
+
### Agent Wellness Break
|
|
211
|
+
|
|
212
|
+
The public enablement signal is `Profile.isWellnessBreakEnabled`. It is true only when the backend-delivered AI feature row has `agentWellbeing.enable === true`, `wellnessBreakReminders === 'ENABLED'`, and the organization reports `aiAssistantQuantity > 0`. The SDK does not create a Desktop Split client or invent a rollout response field: the backend controls rollout by deciding whether the delivered AI feature configuration enables wellness for the organization.
|
|
213
|
+
|
|
214
|
+
When registration silently restores an already logged-in station, the returned `Profile.agentSessionId` projects that active session. It is absent when registration has no active session. This lets hosts recover session-scoped state after refresh without reading SDK internals or trusting a notification's session id.
|
|
215
|
+
|
|
216
|
+
Design rationale: ContactCenter, not the caller, owns wellness identity. ApiAIAssistant receives a
|
|
217
|
+
read-only provider instead of a setter, so a host cannot send an action for another agent or session
|
|
218
|
+
(CONTACT_CENTER-R-006, `INV-008`). Notification session metadata is diagnostic only, so a legitimate
|
|
219
|
+
nudge is not dropped when the backend's session id differs, while outbound actions still use the
|
|
220
|
+
active local session (CONTACT_CENTER-R-007, `INV-010`).
|
|
221
|
+
|
|
222
|
+
### wxApp Better Together (WXCC-6026)
|
|
223
|
+
|
|
224
|
+
Contract ID: `contact-center-sdk` ([package architecture](../../docs/architecture.md)). Task telephony routing, UI controls, and mute events are specified in the [task module spec](../services/task/docs/README.md). Service collaborators: [services module spec](../services/docs/README.md).
|
|
225
|
+
|
|
226
|
+
- **Init flag:** `webex.init({ cc: { enableWxBetterTogether: boolean } })` — default `false`. When `true`, ContactCenter enables wxApp telephony routing on tasks after supported station login. **Compatible with `allowMultiLogin: true`** (multiple SDK sessions may receive offers; wxApp telephony is routed per active task instance). **Phase 1 is init-only** — to change the flag after SDK init, re-init with updated config.
|
|
227
|
+
- **Read API:** `cc.isWxBetterTogetherEnabled()` returns the current init flag value.
|
|
228
|
+
- **Phase 2 (internal/private):** `setManageWebexCallingInWxcc(enabled)` remains as a private implementation for future runtime toggle; hosts must not call it in Phase 1.
|
|
229
|
+
- **Post-login hooks:** `ensureWxAppPostStationLogin()` runs after successful `stationLogin()` and after `silentRelogin()` on socket reconnect. A BROWSER login is skipped (with a skip metric when the flag is on). When the init flag is ON, it publishes usersub `true`, connects Mercury/device for mute sync, and backfills mute state on active tasks. Failures roll back wxApp config and release partial Mercury/device resources without failing station login. When OFF, it force-publishes usersub `false` (clears stale suppression after page refresh) and tears down wxApp Mercury resources; a failed false publish is retried (Concurrency and reactive flow).
|
|
230
|
+
- **Teardown:** `deregister()`, station logout, and wxApp teardown paths call `teardownWxAppLocalState()` — publish usersub `false`, unsubscribe Mercury, release CC-owned device/Mercury connections, and reset **session runtime** state (usersub active flag, Mercury subscriptions, task-manager wxApp routing) so stale session flags do not apply on relogin. The host init flag (`enableWxBetterTogether`) is **not** cleared on station logout — it persists until `deregister()` or re-init per Phase 1 contract. Local cleanup runs even when usersub publish fails; `deregister()` rethrows the publish error after its local cleanup.
|
|
231
|
+
- **Host telephony surface:** Hosts call unified `task.accept()`, `task.decline()`, `task.toggleMute({ muted? })`, and `task.transmitDtmf({ dtmf })`; SDK `Voice` routes wxApp legs internally when the flag is active. Shared-line `lineOwnerId` defaults from the wxApp agent participant when omitted.
|
|
232
|
+
|
|
233
|
+
Evidence: `src/cc.ts`, `src/config.ts`, `src/services/WebexCrossClientService.ts`, `src/services/WxAppTelephonyMercurySync.ts`, `test/unit/spec/cc.ts`.
|
|
234
|
+
|
|
235
|
+
## Data flow and sequence coverage
|
|
236
|
+
|
|
237
|
+
Call style: in-process promise methods on `webex.cc`. Collaborators make authenticated HTTPS calls
|
|
238
|
+
through `webex.request`, and the primary and RTD WebSockets deliver notifications that settle AQM
|
|
239
|
+
operations and drive events.
|
|
240
|
+
|
|
241
|
+
Sequence coverage:
|
|
242
|
+
|
|
243
|
+
| Operation group | Entry and outcome | Diagram or evidence | Failure and recovery coverage |
|
|
244
|
+
| --------------- | ----------------- | ------------------- | ----------------------------- |
|
|
245
|
+
| READY-time bootstrap | Host `ready` event; collaborators built once | Bootstrap | Invalid configuration throws in the READY handler before any collaborator exists, so later readiness-dependent use fails |
|
|
246
|
+
| Registration | `register()`; resolves the Profile | Register | Connection/subscription failure is logged, metrics record failure, logs upload, and the error is rethrown; RTD and Mercury failures are contained |
|
|
247
|
+
| Deregistration | `deregister()`; resolves void | Deregister | Cleanup failure is measured, logged, and rethrown; no synthetic success; a throw after listener removal leaves a partial teardown (State machine) |
|
|
248
|
+
| Connection recovery | ConnectionService `connectionLost` event; session reloaded | Recovery | ContactCenter chooses silent relogin or preserves failure state; `AGENT_NOT_FOUND` is silent |
|
|
249
|
+
| Station login, logout, and agent state | `stationLogin`, `stationLogout`, `setAgentState`, `updateAgentProfile`; resolve the AQM response | Station login, logout, and agent state | Dial-number and browser-voice validation, AQM failure or timeout, and line registration failure reject with detailed errors |
|
|
250
|
+
| Preview campaign and outdial | `acceptPreviewContact`, `skipPreviewContact`, `removePreviewContact`, `startOutdial`; resolve `TaskResponse` | Preview campaign and outdial | Disabled skip or remove throws before transport; AQM failures are tracked and rethrown |
|
|
251
|
+
| Wellness notifications | `Wellness_Break_Handler` on the primary or RTD socket; emits `WellnessBreak` | Wellness notifications | Invalid notifications are dropped and measured |
|
|
252
|
+
|
|
253
|
+
### Bootstrap
|
|
254
|
+
|
|
255
|
+
```mermaid
|
|
256
|
+
sequenceDiagram
|
|
257
|
+
participant Host as Host Webex SDK
|
|
258
|
+
participant CC as ContactCenter
|
|
259
|
+
participant S as Services
|
|
260
|
+
participant TM as TaskManager
|
|
261
|
+
Host-->>CC: READY
|
|
262
|
+
CC->>CC: validatePluginConfig()
|
|
263
|
+
alt configuration valid
|
|
264
|
+
CC->>CC: WebexRequest.getInstance(webex)
|
|
265
|
+
CC->>S: Services.getInstance(webex, connectionConfig)
|
|
266
|
+
CC->>CC: create WebCallingService + wxApp services + ApiAIAssistant + MetricsManager
|
|
267
|
+
CC->>TM: getTaskManager(aiAssistant, contact, calling, primaryWS, rtdWS)
|
|
268
|
+
CC->>CC: listen to TaskManager task events
|
|
269
|
+
CC->>CC: create EntryPoint + AddressBook + Queue + UserPreference; initialize LoggerProxy
|
|
270
|
+
else invalid configuration
|
|
271
|
+
CC-->>Host: validatePluginConfig() throws; no collaborator is created
|
|
272
|
+
end
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### Register
|
|
276
|
+
|
|
277
|
+
```mermaid
|
|
278
|
+
sequenceDiagram
|
|
279
|
+
participant App
|
|
280
|
+
participant CC as ContactCenter
|
|
281
|
+
participant WS as Primary WebSocketManager
|
|
282
|
+
participant Cfg as AgentConfigService
|
|
283
|
+
participant Agent as Services.agent
|
|
284
|
+
participant Metrics
|
|
285
|
+
App->>CC: register()
|
|
286
|
+
CC->>CC: new wellness registration generation; clear idle-code cache
|
|
287
|
+
CC->>Metrics: time register success/failure
|
|
288
|
+
CC->>CC: setupEventListeners(); listen for WS messages
|
|
289
|
+
CC->>WS: initWebSocket({body, resource: SUBSCRIBE_API})
|
|
290
|
+
WS-->>CC: Welcome data containing agentId
|
|
291
|
+
CC->>Cfg: getAgentConfig(orgId, agentId)
|
|
292
|
+
alt profile fetched
|
|
293
|
+
Cfg-->>CC: Profile
|
|
294
|
+
CC->>CC: set TaskManager/config/AI flags
|
|
295
|
+
opt applicable AI feature or wellness enabled
|
|
296
|
+
CC->>CC: start RTD WebSocket; log but contain RTD failure
|
|
297
|
+
end
|
|
298
|
+
opt browser calling applicable
|
|
299
|
+
CC->>CC: mercury.connect(); log but contain failure
|
|
300
|
+
end
|
|
301
|
+
opt allowAutomatedRelogin
|
|
302
|
+
CC->>Agent: reload()
|
|
303
|
+
Agent-->>CC: relogin result, AGENT_NOT_FOUND, or error
|
|
304
|
+
end
|
|
305
|
+
CC->>Metrics: track registration success
|
|
306
|
+
CC-->>App: Profile (with agentSessionId when a logged-in session was restored)
|
|
307
|
+
else primary subscription/profile/relogin failure
|
|
308
|
+
CC->>Metrics: track registration failure
|
|
309
|
+
CC->>CC: uploadLogs(correlationId)
|
|
310
|
+
CC-->>App: throw error
|
|
311
|
+
end
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
### Deregister
|
|
315
|
+
|
|
316
|
+
```mermaid
|
|
317
|
+
sequenceDiagram
|
|
318
|
+
participant App
|
|
319
|
+
participant CC as ContactCenter
|
|
320
|
+
participant Host as Mercury/device
|
|
321
|
+
participant WS as Primary + RTD WebSockets
|
|
322
|
+
App->>CC: deregister()
|
|
323
|
+
CC->>CC: new wellness registration generation; clear wellness session and idle-code cache
|
|
324
|
+
CC->>CC: clear AI summary state; remove TaskManager/message/connection listeners
|
|
325
|
+
CC->>CC: teardownWxAppLocalState(clearInitFlag)
|
|
326
|
+
opt browser calling resources active
|
|
327
|
+
CC->>Host: disconnect Mercury; unregister device
|
|
328
|
+
end
|
|
329
|
+
CC->>WS: close(false, reason)
|
|
330
|
+
CC->>CC: agentConfig = null
|
|
331
|
+
alt cleanup succeeds
|
|
332
|
+
CC-->>App: void
|
|
333
|
+
else wxApp usersub publish failed
|
|
334
|
+
CC-->>App: throw publish error after local cleanup
|
|
335
|
+
else throw after listener removal (no agentConfig, Mercury or device failure)
|
|
336
|
+
CC-->>App: throw error; listeners are already removed and sockets may stay open
|
|
337
|
+
end
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### Recovery
|
|
341
|
+
|
|
342
|
+
```mermaid
|
|
343
|
+
sequenceDiagram
|
|
344
|
+
participant CS as ConnectionService
|
|
345
|
+
participant CC as ContactCenter
|
|
346
|
+
participant Agent as Services.agent
|
|
347
|
+
CS-->>CC: connectionLost(details)
|
|
348
|
+
CC->>CC: handleConnectionLost(details)
|
|
349
|
+
alt details.isConnectionLost
|
|
350
|
+
CC->>CC: log only
|
|
351
|
+
else details.isSocketReconnected and allowAutomatedRelogin
|
|
352
|
+
CC->>CC: silentRelogin()
|
|
353
|
+
CC->>Agent: reload()
|
|
354
|
+
alt relogin succeeds
|
|
355
|
+
Agent-->>CC: relogin result; update agent config/device state
|
|
356
|
+
opt lastStateChangeReason is agent-wss-disconnect
|
|
357
|
+
CC->>CC: setAgentState(Available); log but contain failure
|
|
358
|
+
end
|
|
359
|
+
CC->>CC: ensureWxAppPostStationLogin()
|
|
360
|
+
else AGENT_NOT_FOUND
|
|
361
|
+
Agent-->>CC: handled silently
|
|
362
|
+
else other failure
|
|
363
|
+
Agent--xCC: throw detailed error
|
|
364
|
+
end
|
|
365
|
+
else relogin disabled
|
|
366
|
+
CC->>CC: make no relogin call; retain reported transport state
|
|
367
|
+
end
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
### Station login, logout, and agent state
|
|
371
|
+
|
|
372
|
+
```mermaid
|
|
373
|
+
sequenceDiagram
|
|
374
|
+
participant App
|
|
375
|
+
participant CC as ContactCenter
|
|
376
|
+
participant Agent as Services.agent
|
|
377
|
+
participant Calling as WebCallingService
|
|
378
|
+
App->>CC: stationLogin({teamId, loginOption, dialNumber})
|
|
379
|
+
alt AGENT_DN and number outside the dial plan
|
|
380
|
+
CC-->>App: throw INVALID_DIAL_NUMBER
|
|
381
|
+
end
|
|
382
|
+
CC->>Agent: stationLogin (AQM; deviceId webrtc- prefix for BROWSER)
|
|
383
|
+
Agent-->>CC: StationLoginSuccess or failure notification
|
|
384
|
+
CC->>Calling: setLoginOption; setBrowserVoiceRequired
|
|
385
|
+
opt browser voice required
|
|
386
|
+
CC->>Calling: registerWebCallingLine()
|
|
387
|
+
end
|
|
388
|
+
CC->>CC: keep agentSessionId; update agentConfig; ensureWxAppPostStationLogin()
|
|
389
|
+
CC-->>App: response with mmProfile counts and notifsTrackingId
|
|
390
|
+
App->>CC: setAgentState({state, auxCodeId})
|
|
391
|
+
alt Available while required browser voice is not ready
|
|
392
|
+
CC-->>App: throw BROWSER_VOICE_NOT_READY
|
|
393
|
+
else
|
|
394
|
+
CC->>Agent: stateChange (AQM)
|
|
395
|
+
Agent-->>CC: StateChangeSuccess or failure
|
|
396
|
+
CC-->>App: response
|
|
397
|
+
end
|
|
398
|
+
App->>CC: stationLogout({logoutReason})
|
|
399
|
+
CC->>Agent: logout (AQM)
|
|
400
|
+
CC->>Calling: deregisterWebCallingLine()
|
|
401
|
+
CC->>CC: teardownWxAppLocalState(); clear wellness session
|
|
402
|
+
CC-->>App: LogoutSuccess
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
Every failure branch tracks the failed metric and rethrows the `getErrorDetails` error.
|
|
406
|
+
`updateAgentProfile()` runs `stationLogout()` then `stationLogin()` and returns the login response
|
|
407
|
+
typed `AgentDeviceTypeUpdateSuccess`.
|
|
408
|
+
|
|
409
|
+
### Preview campaign and outdial
|
|
410
|
+
|
|
411
|
+
```mermaid
|
|
412
|
+
sequenceDiagram
|
|
413
|
+
participant App
|
|
414
|
+
participant CC as ContactCenter
|
|
415
|
+
participant TM as TaskManager
|
|
416
|
+
participant Dialer as Services.dialer
|
|
417
|
+
App->>CC: skipPreviewContact(payload) or removePreviewContact(payload)
|
|
418
|
+
CC->>TM: getTask(interactionId)
|
|
419
|
+
alt campaignPreviewSkipDisabled or campaignPreviewRemoveDisabled is 'true'
|
|
420
|
+
CC-->>App: throw Error (action is disabled), no request sent
|
|
421
|
+
else allowed
|
|
422
|
+
CC->>Dialer: skipPreviewContact or removePreviewContact (AQM)
|
|
423
|
+
Dialer-->>CC: TaskResponse or failure
|
|
424
|
+
CC-->>App: TaskResponse or detailed error
|
|
425
|
+
end
|
|
426
|
+
App->>CC: acceptPreviewContact(payload) (no pre-guard)
|
|
427
|
+
CC->>Dialer: acceptPreviewContact (AQM)
|
|
428
|
+
App->>CC: startOutdial(destination, origin)
|
|
429
|
+
CC->>Dialer: startOutdial with entryPointId outDialEp, OUTBOUND, telephony, OUTDIAL
|
|
430
|
+
Dialer-->>CC: TaskResponse or failure
|
|
431
|
+
CC-->>App: TaskResponse or detailed error
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
`cc.startOutdial(destination, origin)` places an outbound call from the logged-in agent:
|
|
435
|
+
|
|
436
|
+
- `destination` is the number to call (the customer DN; `DialerPayload` documents at most 36
|
|
437
|
+
characters). ContactCenter does not validate or normalize it.
|
|
438
|
+
- `origin` is the outbound ANI (caller ID) shown to the customer, typically one of the numbers
|
|
439
|
+
returned by `cc.getOutdialAniEntries({outdialANI})`. The TypeScript signature requires it, but the
|
|
440
|
+
method forwards `undefined` unchanged when it is omitted, and the unit spec covers both calls.
|
|
441
|
+
- The method sends one AQM request through `Services.dialer.startOutdial`: a POST to `/v1/tasks/` on
|
|
442
|
+
the Contact Center API gateway with body `{destination, origin, entryPointId, direction, attributes,
|
|
443
|
+
mediaType, outboundType}`, where `entryPointId` is the profile's `outDialEp`, `direction` is
|
|
444
|
+
`OUTBOUND`, `attributes` is `{}`, `mediaType` is `telephony`, and `outboundType` is `OUTDIAL`.
|
|
445
|
+
- It resolves with the `AgentOfferContact` notification (`TaskResponse`) and rejects with the
|
|
446
|
+
`getErrorDetails` error when `AgentOutboundFailed` arrives or the request times out. The `Task`
|
|
447
|
+
object reaches the application through the task events owned by the task module, not as this
|
|
448
|
+
return value.
|
|
449
|
+
|
|
450
|
+
```typescript
|
|
451
|
+
const cc = webex.cc;
|
|
452
|
+
await cc.register();
|
|
453
|
+
await cc.stationLogin({teamId: 'team123', loginOption: 'BROWSER'});
|
|
454
|
+
|
|
455
|
+
// destination is the number to call; origin is the outbound ANI (caller ID)
|
|
456
|
+
const response = await cc.startOutdial('+14155550100', '+14155550199');
|
|
457
|
+
console.log(response);
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
### Wellness notifications
|
|
461
|
+
|
|
462
|
+
```mermaid
|
|
463
|
+
sequenceDiagram
|
|
464
|
+
participant WS as Primary or RTD WebSocket
|
|
465
|
+
participant CC as ContactCenter
|
|
466
|
+
participant TM as TaskManager
|
|
467
|
+
participant Metrics as MetricsManager
|
|
468
|
+
participant App
|
|
469
|
+
WS-->>CC: message (primary: handleWebsocketMessage; RTD: handleRTDWebsocketMessage)
|
|
470
|
+
alt type is Wellness_Break_Handler
|
|
471
|
+
CC->>CC: normalizeWellnessBreakEvent(payload)
|
|
472
|
+
alt flag on, known actionEvent, agent and organization ids match
|
|
473
|
+
CC-->>App: emit WellnessBreak (WellnessBreakEvent)
|
|
474
|
+
else disabled, malformed, unknown action, missing or mismatched identity
|
|
475
|
+
CC->>Metrics: AI_ASSISTANT_WELLNESS_EVENT_INVALID with reason
|
|
476
|
+
end
|
|
477
|
+
else RTD message of another type
|
|
478
|
+
CC->>TM: handleRealtimeWebsocketEvent(event)
|
|
479
|
+
else primary message of another type
|
|
480
|
+
CC->>CC: map agent events
|
|
481
|
+
end
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
## Class and component relationships
|
|
485
|
+
|
|
486
|
+
```mermaid
|
|
487
|
+
classDiagram
|
|
488
|
+
class WebexPlugin
|
|
489
|
+
class ContactCenter
|
|
490
|
+
class Services
|
|
491
|
+
class WebexRequest
|
|
492
|
+
class MetricsManager
|
|
493
|
+
class TaskManager
|
|
494
|
+
class WebCallingService
|
|
495
|
+
class ApiAIAssistant
|
|
496
|
+
class AnswerCallOnWebexService
|
|
497
|
+
class WebexCrossClientService
|
|
498
|
+
class WxAppTelephonyMercurySync
|
|
499
|
+
class EntryPoint
|
|
500
|
+
class AddressBook
|
|
501
|
+
class Queue
|
|
502
|
+
class UserPreference
|
|
503
|
+
class LoggerProxy
|
|
504
|
+
WebexPlugin <|-- ContactCenter
|
|
505
|
+
ContactCenter --> WebexRequest : initializes/uses for log upload
|
|
506
|
+
ContactCenter --> Services : agent/config/contact/dialer + WebSockets
|
|
507
|
+
ContactCenter --> MetricsManager : timings and tracking
|
|
508
|
+
ContactCenter --> TaskManager : task lifecycle/events
|
|
509
|
+
ContactCenter --> WebCallingService : browser calling
|
|
510
|
+
ContactCenter --> ApiAIAssistant : transcript/suggestion/wellness API
|
|
511
|
+
ContactCenter --> WebexCrossClientService : wxApp usersub
|
|
512
|
+
ContactCenter --> WxAppTelephonyMercurySync : wxApp mute sync
|
|
513
|
+
ContactCenter --> EntryPoint
|
|
514
|
+
ContactCenter --> AddressBook
|
|
515
|
+
ContactCenter --> Queue
|
|
516
|
+
ContactCenter --> UserPreference
|
|
517
|
+
ContactCenter ..> LoggerProxy : initialize(webex.logger)
|
|
518
|
+
TaskManager --> ApiAIAssistant
|
|
519
|
+
TaskManager --> WebCallingService
|
|
520
|
+
TaskManager --> AnswerCallOnWebexService
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
`Services`, `WebexRequest`, `MetricsManager`, and `TaskManager` are obtained through their singleton
|
|
524
|
+
accessors; the other collaborators are constructed per plugin instance at READY.
|
|
525
|
+
|
|
526
|
+
## Use cases and flows
|
|
527
|
+
|
|
528
|
+
| Use case | Actor or caller | Primary steps and outcome | Failure or boundary behavior | Evidence |
|
|
529
|
+
| -------- | --------------- | ------------------------- | ---------------------------- | -------- |
|
|
530
|
+
| `UC-1` | Host application | Host bootstrap: after host READY, initialize the complete collaborator graph exactly once. | Invalid plugin configuration throws in the READY handler | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
531
|
+
| `UC-2` | Host application | Register: attach listeners and establish the primary WebSocket subscription before returning Profile. | Failure is measured, logs upload, and the error is rethrown | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
532
|
+
| `UC-3` | Host application or widget | Delegate SDK operations: validate/map public inputs, call the owning collaborator, track metrics, and return or emit typed results. | Detailed errors from `getErrorDetails` | `src/cc.ts`, `src/index.ts`, `test/unit/spec/cc.ts` |
|
|
533
|
+
| `UC-4` | ConnectionService | Recover connection: consume ConnectionService state and conditionally reload the agent session through ContactCenter policy. | `AGENT_NOT_FOUND` is silent; other relogin errors reject in the listener | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
534
|
+
| `UC-5` | Host application | Deregister: remove the same listener identities, shut down applicable host/WebSocket resources, and clear in-memory profile state. | Cleanup errors are rethrown; listener identity gaps in Pitfalls and constraints | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
535
|
+
| `UC-6` | Host application and agent | Wellness lifecycle: consume an agent/org-scoped offer regardless of its notification session metadata, report a user action using the active local session, resolve the system idle code, and demonstrate legacy Idle/Available transitions. | Disabled or incomplete context rejects before transport | `src/cc.ts`, `src/services/ApiAiAssistant.ts`, `src/services/config/index.ts`, `test/unit/spec/cc.ts` |
|
|
536
|
+
|
|
537
|
+
External consumer flow, not owned by this module: the monorepo wellness browser sample (docs/samples/contact-center: app.js, wellness-utils.js, index.html) drives `UC-6`. Its helpers are pinned by `test/unit/spec/wellnessSampleUtils.ts`.
|
|
538
|
+
|
|
539
|
+
The standalone SDK browser sample keeps `WellbeingBreak` out of the ordinary status selector. It reads the exported wellness wire constants from the standalone `Webex` constructor, seeds its current session and legacy state from a logged-in registration profile after silent relogin, and shows only the action name in its latest-event display. It creates a session-scoped recovery marker before changing legacy state, clears manual-request eligibility when a break starts so the request control remains disabled after restoration until another `SUGGEST_WELLNESS_BREAK`, confirms the transition, sends `ACCEPTED` only after state success, and waits for every task to leave incoming, active, consult, conference, campaign, and wrap-up work before starting its 60-second demonstration timer. Restoration targets `Available / 0`, retries bounded failures, and retains reconnect recovery ownership after exhaustion. Authoritative external Available changes end the local lifecycle, while refresh recovery restores a matching current session without replaying the offer, response action, or break. Pure helpers own notification, response, logout, and deregistration transition decisions; a failed rejection/no-response delivery retains and re-arms its offer. If SDK deregistration completes its local teardown but reports a deferred error, the sample still detaches listeners and resets its local controls. It revokes manual-request eligibility on `WELLNESS_BREAK_NOT_ALLOWED`, and its logout cleanup ignores a different agent session.
|
|
540
|
+
|
|
541
|
+
### Cross-boundary use-case flow
|
|
542
|
+
|
|
543
|
+
| Boundary | Transport and ordering | Compatibility | Timeout, retry, and recovery |
|
|
544
|
+
| -------- | ---------------------- | ------------- | ---------------------------- |
|
|
545
|
+
| Contact Center notification WebSocket (`UC-2`, `UC-4`) | Subscribe over HTTPS, then one primary socket; messages are handled in arrival order by AqmReqs, ContactCenter, and TaskManager listeners | Notification type names mirrored in `CC_EVENTS` | ConnectionService reconnects; ContactCenter reloads the session on reconnect when allowed |
|
|
546
|
+
| RTD WebSocket (`UC-6`) | Started after the profile when an AI feature or wellness is enabled; not awaited by `register()` | Same subscribe body, `RTD_SUBSCRIBE_API` resource | A failure is logged and registration continues |
|
|
547
|
+
| Contact Center REST gateway (`UC-3`) | `webex.request` through the services clients | Owned by the backend; the package owns no route | Errors become detailed errors; no automatic retry here |
|
|
548
|
+
| Mercury and the Webex device (`UC-2`, wxApp) | Connected for browser voice during register and for wxApp mute sync after login | Host internal plugins | Connect failures are logged; wxApp failures roll back |
|
|
549
|
+
| AI assistant `/event` (`UC-6`) | Direct POST of a `CUSTOM_EVENT` | HTTP 202 required | Other statuses reject; no retry |
|
|
550
|
+
|
|
551
|
+
## Client state model
|
|
552
|
+
|
|
553
|
+
ContactCenter retains in-memory `agentConfig`, collaborator references, event listeners, task collections through TaskManager, and connection/recovery state. Remote Webex services remain authoritative for agent, task, and organization data. Registration establishes runtime connectivity but does not imply station login; deregistration tears down SDK resources but does not itself perform station logout. The package owns only in-memory profile/task/listener/cache/connection state.
|
|
554
|
+
|
|
555
|
+
| State or slice | Owner | Initial state | Transition triggers | Reset or persistence boundary |
|
|
556
|
+
| -------------- | ----- | ------------- | ------------------- | ----------------------------- |
|
|
557
|
+
| `agentConfig` (Profile) | `ContactCenter` | undefined | Set by `register()`; updated by station login, silent relogin, and login notifications | Set to null by `deregister()`; memory only |
|
|
558
|
+
| `currentAgentSessionId` | `ContactCenter` | undefined | Station login, relogin, and login-success notifications set it | Cleared on logout, current-session multi-login close, registration failure, each profile fetch during register, and deregister |
|
|
559
|
+
| `wellbeingBreakIdleCode`, `wellnessRegistrationGeneration` | `ContactCenter` | undefined, 0 | A lookup fills the cache; each `register()` and `deregister()` increments the generation | The cache is cleared on every register, profile fetch, and deregister |
|
|
560
|
+
| `$config.enableWxBetterTogether` | `ContactCenter` | From init config | Rolled back to false when an enabled post-login hook fails | Cleared by `deregister()` |
|
|
561
|
+
| wxApp ownership flags and retry timer | `ContactCenter` | false, none | Set when wxApp opened Mercury or registered the device; timer set on a failed false publish | Cleared on release and teardown |
|
|
562
|
+
| Voice connection snapshot | `WebCallingService` | `DEFAULT_VOICE_CONNECTION_STATE` (`not-required`) | Line and Mobius socket events | Reset on line deregistration at station logout; `getVoiceConnectionState()` returns the default when no service exists |
|
|
563
|
+
|
|
564
|
+
## Business rules and invariants
|
|
565
|
+
|
|
566
|
+
| ID | Invariant | WHY | Enforcement source | Test evidence |
|
|
567
|
+
| -- | --------- | --- | ------------------ | ------------- |
|
|
568
|
+
| `INV-001` | Collaborators are initialized after host READY and before their use; `register()` must not be documented as their constructor boundary. | Collaborators need the host request, logger, and configuration that exist only after READY (CONTACT_CENTER-R-001). | `src/cc.ts` | `test/unit/spec/cc.ts` |
|
|
569
|
+
| `INV-002` | AQM promises complete only from correlated WebSocket success/failure or timeout, not from HTTP acknowledgement. | The HTTP response only acknowledges the request; the backend reports the outcome on the socket. | `src/services/core/aqm-reqs.ts` | `test/unit/spec/services/core/aqm-reqs.ts` |
|
|
570
|
+
| `INV-003` | `skipPreviewContact` checks `campaignPreviewSkipDisabled` and `removePreviewContact` checks `campaignPreviewRemoveDisabled` on the matching task. When the applicable value is `'true'`, ContactCenter throws before initiating an HTTP or WebSocket-correlated AQM operation; `acceptPreviewContact` has no equivalent pre-guard. | The campaign disables those actions for the reservation; a local throw avoids a request the backend would reject. | `src/cc.ts` | None found (CONTACT_CENTER-R-003 gap) |
|
|
571
|
+
| `INV-004` | `handleWebsocketMessage` only re-emits event names that belong to the typed `CC_EVENTS` allow-list (the values of `CC_AGENT_EVENTS` and `CC_TASK_EVENTS`); an untrusted `eventData.data.type` outside that allow-list is not emitted as an event name. Mapped `AGENT_EVENTS` names come only from fixed switch cases. | The comment on `CC_EVENT_ALLOW_LIST`: guard against emitting an arbitrary event name supplied by the socket payload. | `src/cc.ts` | `test/unit/spec/cc.ts` |
|
|
572
|
+
| `INV-005` | ContactCenter owns automated relogin policy; ConnectionService owns transport-state detection/emission. | Only ContactCenter has the profile and config needed to relogin (CONTACT_CENTER-R-005). | `src/cc.ts`, `src/services/core/websocket/connection-service.ts` | `test/unit/spec/cc.ts` |
|
|
573
|
+
| `INV-006` | Deregistration does not station-logout the agent. | Deregistration tears down SDK resources; the agent session stays on the backend for relogin. | `src/cc.ts` | `test/unit/spec/cc.ts` |
|
|
574
|
+
| `INV-007` | Published methods/types/events remain semver-sensitive through `src/index.ts`. | The barrel is the published declaration surface. | `src/index.ts`, `package.json` | `test/unit/spec/index.ts` |
|
|
575
|
+
| `INV-008` | Wellness actions take no public identity or context-mutating input and require the effective profile flag plus non-empty organization (from the Webex credentials), registered-agent, and current-session context (from the internal live provider); all checks fail closed after current-session logout, multi-login close, or deregistration. | CONTACT_CENTER-R-006 | `src/cc.ts`, `src/services/ApiAiAssistant.ts` | `test/unit/spec/services/ApiAiAssistant.ts`, `test/unit/spec/cc.ts` |
|
|
576
|
+
| `INV-009` | Wellness action unions derive from exported `as const` value objects; backend message-type and enablement sentinels use internal constants rather than duplicated literals. | One public value source prevents wire-value drift (CONTACT_CENTER-R-006). | `src/types.ts`, `src/constants.ts`, `src/services/config/constants.ts` | `test/unit/spec/cc.ts` |
|
|
577
|
+
| `INV-010` | Malformed, unknown-action, stale-agent, and stale-org wellness notifications are ignored and measured without logging the full payload. A different notification `agentSessionId` is retained as diagnostic metadata and does not make an otherwise valid current-agent/current-org wellness event stale. | CONTACT_CENTER-R-007 | `src/cc.ts` | `test/unit/spec/cc.ts` |
|
|
578
|
+
| `INV-011` | `setAgentState` rejects a transition into `Available` with `BROWSER_VOICE_NOT_READY` only while browser voice is required and not ready; other states are never blocked. | Agents must be able to leave `Available` during outages (CONTACT_CENTER-R-009). | `src/cc.ts`, `src/services/WebCallingService.ts` | `test/unit/spec/cc.ts` |
|
|
579
|
+
|
|
580
|
+
## Concurrency and reactive flow
|
|
581
|
+
|
|
582
|
+
READY initialization, REST promises, AQM WebSocket correlation, TaskManager events, calling events, and connection timers execute asynchronously. Listener cleanup must use the registered function identity. Message listeners are independent: AqmReqs correlates pending requests, ContactCenter maps package events, TaskManager owns task lifecycle, and ConnectionService tracks liveness/reconnect state.
|
|
583
|
+
|
|
584
|
+
- Execution model: one JavaScript event loop; public methods are `async` except `getVoiceConnectionState()` and `isWxBetterTogetherEnabled()`.
|
|
585
|
+
- Ordering guarantees: within `register()`, the profile is fetched before RTD start, Mercury connect, and silent relogin; the RTD socket start is not awaited. Within a WebSocket message, wellness handling runs before agent event mapping.
|
|
586
|
+
- Idempotency and retry: no public method retries. A failed wxApp usersub false publish (flag-off post-login hook or teardown) is retried up to three times, 30 seconds apart. A repeated `register()` attaches another `connectionLost` listener (Pitfalls and constraints).
|
|
587
|
+
- Shared-state protection: the wellness registration generation and the captured organization reject a stale idle-code lookup; there is no lock.
|
|
588
|
+
- Blocking restrictions: socket message handlers are synchronous; `handleConnectionLost` awaits `silentRelogin()`, and a rejection there has no caller.
|
|
589
|
+
|
|
590
|
+
## State machine
|
|
591
|
+
|
|
592
|
+
```mermaid
|
|
593
|
+
stateDiagram-v2
|
|
594
|
+
[*] --> AwaitingHostReady
|
|
595
|
+
AwaitingHostReady --> Initialized: host READY + collaborators created
|
|
596
|
+
AwaitingHostReady --> Unusable: READY + invalid plugin config throws
|
|
597
|
+
Initialized --> Registering: register()
|
|
598
|
+
Registering --> Registered: WebSocket/profile success
|
|
599
|
+
Registering --> Initialized: registration failure
|
|
600
|
+
Registered --> Recovering: connectionLost reports socket reconnected
|
|
601
|
+
Recovering --> Registered: reconnect/relogin succeeds
|
|
602
|
+
Recovering --> Registered: relogin disabled; transport state reported
|
|
603
|
+
Registered --> Deregistering: deregister()
|
|
604
|
+
Deregistering --> Initialized: listeners/resources cleared
|
|
605
|
+
Deregistering --> Initialized: wxApp publish error rethrown after local cleanup
|
|
606
|
+
Deregistering --> PartiallyTornDown: throw after listener removal (no agentConfig, Mercury or device failure)
|
|
607
|
+
PartiallyTornDown --> Registering: register()
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
- Guards: `allowAutomatedRelogin` decides the relogin; `isSocketReconnected` decides whether a
|
|
611
|
+
`connectionLost` event triggers recovery.
|
|
612
|
+
- Station login is a separate backend state; registration neither logs in nor logs out.
|
|
613
|
+
- PartiallyTornDown: TaskManager, message, and connection listeners are removed (except the two
|
|
614
|
+
identity defects in Pitfalls and constraints) and wxApp state is torn down, but the sockets may stay
|
|
615
|
+
open and `agentConfig` may remain set. A later `register()` attaches the listeners again.
|
|
616
|
+
- No terminal state except Unusable; register and deregister can repeat on one instance.
|
|
617
|
+
|
|
618
|
+
## Protocol and wire format
|
|
619
|
+
|
|
620
|
+
Authenticated REST initiates direct data/config operations and AQM agent/task operations. For AQM, the HTTP response is acknowledgement only; `notifSuccess.bind`/`notifFail.bind` match WebSocket payloads that settle the promise. Wellness actions are the exception: ApiAIAssistant posts a direct `CUSTOM_EVENT` to `/event` and requires HTTP 202. The primary and RTD WebSockets can carry `Wellness_Break_Handler`; ContactCenter routes it before task-specific traffic. Payload and event names are owned by `src/types.ts`, `src/services/config/types.ts`, `src/services/agent/types.ts`, and `src/services/task/types.ts`.
|
|
621
|
+
|
|
622
|
+
| Message or frame | Version | Producer or serializer | Consumer or parser | Compatibility and ordering rule |
|
|
623
|
+
| ---------------- | ------- | ---------------------- | ------------------ | ------------------------------- |
|
|
624
|
+
| Subscribe request `{force, isKeepAliveEnabled, clientType, allowMultiLogin}` | — | `getConnectionConfig` in `src/cc.ts` | Contact Center subscribe endpoint (`SUBSCRIBE_API`, `RTD_SUBSCRIBE_API`) | Defaults from `src/config.ts` |
|
|
625
|
+
| Welcome event with `agentId` | — | Contact Center backend | `connectWebsocket` in `src/cc.ts` | First message after subscribe; `agentId` keys the profile fetch |
|
|
626
|
+
| Notification envelope `{type, data: {type, ...}, keepalive, trackingId}` | — | Contact Center backend | `handleWebsocketMessage` in `src/cc.ts` | Keepalives are not re-emitted; `data.type` is re-emitted only from the allow-list (`INV-004`) |
|
|
627
|
+
| `Wellness_Break_Handler` notification | — | Contact Center backend (primary or RTD socket) | `normalizeWellnessBreakEvent` in `src/cc.ts` | Requires matching `notifType`, a known `actionEvent`, and agent and three organization ids equal to the current ones |
|
|
628
|
+
| `WellnessBreakEvent` `{agentId, orgId, agentSessionId, actionEvent, actionText?, interactionId?, trackingId?}` | — | `src/cc.ts` | Applications listening for `WellnessBreak` | Optional fields appear only when present as strings |
|
|
629
|
+
|
|
630
|
+
## Caller-visible failure modes
|
|
631
|
+
|
|
632
|
+
| Condition | Signal or result | Caller behavior | Retry or recovery | Evidence |
|
|
633
|
+
| --------- | ---------------- | --------------- | ----------------- | -------- |
|
|
634
|
+
| Invalid plugin configuration at READY | `Error` `Invalid Contact Center configuration: …` thrown in the READY handler | Fix the config (allow multi-login or WebRTC registration) | Re-init; no collaborator exists | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
635
|
+
| An AQM operation gets no correlated notification before its timeout | AqmReqs rejects `Service.aqm.reqs.Timeout`; the façade logs, uploads logs, and rethrows `Error` with the backend reason or `Error while performing` plus the method name | Treat the outcome as unknown and wait for the next agent or task notification | Retry only operations that are safe to repeat | `src/services/core/aqm-reqs.ts`, `src/services/core/Utils.ts` |
|
|
636
|
+
| The same AQM request is already pending | `Service.aqm.reqs.Pending` | Wait for the first request to settle | Retry after it settles | `src/services/core/aqm-reqs.ts` |
|
|
637
|
+
| Backend failure notification or REST error | `Error` whose message is `details.data.reason`; station login also sets `data.message` and `data.fieldName` | Show the reason; read the tracking id from the log | Caller decides | `src/services/core/Utils.ts`, `src/cc.ts` |
|
|
638
|
+
| AGENT_DN login with a number outside the dial plan | `INVALID_DIAL_NUMBER`, wrapped by `getErrorDetails` | Correct the dial number | Retry the login | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
639
|
+
| `setAgentState` to `Available` while required browser voice is not ready | `BROWSER_VOICE_NOT_READY` with `details.type` `SDK_VALIDATION_ERROR` | Wait for `voice:connectionStateChange` to report ready | Retry after ready | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
640
|
+
| Wellness lookup while disabled, or after the registration or organization changed | `WELLNESS_BREAK_NOT_ENABLED` or `WELLNESS_BREAK_REGISTRATION_CHANGED` (`SDK_VALIDATION_ERROR`) | Re-read the profile | Retry after the new registration | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
641
|
+
| Preview skip or remove disabled by the campaign | Plain `Error` `Skip action is disabled …` or `Remove action is disabled …`, not wrapped | Hide the action | None | `src/cc.ts` |
|
|
642
|
+
| `getOutdialAniEntries` with no organization id | Plain `Error('Org ID not found.')` | Authorize the host SDK first | Retry after authorization | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
643
|
+
| Silent relogin reports an unsupported device type | `Unsupported device type: …`, wrapped; `AGENT_NOT_FOUND` is swallowed | Station login again | None automatic | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
644
|
+
| `register()`, `deregister()`, or `updateAgentProfile()` fails | The original error rethrown after logging and metrics | Inspect the error | Call again; a failed `deregister()` may leave a partial teardown (State machine) | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
645
|
+
|
|
646
|
+
## Pitfalls and constraints
|
|
647
|
+
|
|
648
|
+
- READY-time construction and `register()` are different lifecycle boundaries; moving collaborator creation into `register()` can duplicate listeners and use uninitialized host services.
|
|
649
|
+
- Listener cleanup must use the same bound function identities registered during setup or repeated register/deregister cycles will leak handlers. Known defects in current code: `setupEventListeners()` registers `handleConnectionLost.bind(this)` while `deregister()` removes the unbound method, so the `connectionLost` listener stays attached and each `register()` adds another; `deregister()` never removes the `TASK_MERGED` TaskManager listener. The deregister test asserts only the `off` arguments.
|
|
650
|
+
- `deregister()` reads `agentConfig.webRtcEnabled` without a guard, so a call with no agent configuration (registration never succeeded, or a second deregister) throws a TypeError after listener removal and wxApp teardown but before the sockets close.
|
|
651
|
+
- `types` resolves to the declarations of `src/index.ts`, whose default export is `ContactCenter`, while `main` loads the built `src/webex.js`, whose default export is the `Webex` constructor; the named exports agree because `src/webex.js` re-exports the barrel.
|
|
652
|
+
- The `startOutdial` JSDoc in `src/cc.ts` lists errors (agent not configured for outbound, invalid E.164 number, agent not Available) and an example that calls `task.on` on the result; the method performs none of those checks and resolves with the offer notification, not a `Task`.
|
|
653
|
+
- `IContactCenter` in `src/types.ts` declares only `register`, `getWellbeingBreakIdleCode`, and `getVoiceConnectionState`; the rest of the public API is declared by the class alone.
|
|
654
|
+
- `getEntryPoints` and `getQueues` are façade wrappers; `entryPoint` is private while `addressBook`, `queue`, `userPreference`, and `apiAIAssistant` are public properties.
|
|
655
|
+
|
|
656
|
+
## Module-specific rules
|
|
657
|
+
|
|
658
|
+
- Do: log through `LoggerProxy` with `module: CC_FILE` and a `METHODS` name, and never log a full notification payload.
|
|
659
|
+
- Do: in each public operation, `timeEvent` the success and failure metrics first, then `trackEvent` exactly one of them, and rethrow the `getErrorDetails` error.
|
|
660
|
+
- Do: add or remove a root export in `src/index.ts` and in the expected list of `test/unit/spec/index.ts` in the same change.
|
|
661
|
+
- DO route agent recovery decisions through ContactCenter because it owns profile/config policy.
|
|
662
|
+
- DON'T synthesize successful register/deregister results after a dependency or cleanup failure.
|
|
663
|
+
- DON'T let transport services call `silentRelogin()` directly.
|
|
664
|
+
|
|
665
|
+
## Export stability
|
|
666
|
+
|
|
667
|
+
The npm export/type-declaration surface is semver-sensitive. Additive optional types are compatible; removals, renames, or semantic changes require a major-version migration.
|
|
668
|
+
|
|
669
|
+
Compatibility notes:
|
|
670
|
+
|
|
671
|
+
- Do not remove or reinterpret exported symbols/events without a documented consumer migration.
|
|
672
|
+
|
|
673
|
+
| Export or entry point | Consumer | Stability | Versioning and deprecation rule | Declaration or API report |
|
|
674
|
+
| --------------------- | -------- | --------- | ------------------------------- | ------------------------- |
|
|
675
|
+
| `main` and `exports['.']` (`dist/webex.js`): default `Webex` and the re-exported barrel | Applications | Public | Workspace release process; breaking changes need a major version | `package.json`, `src/webex.js` |
|
|
676
|
+
| `types` (`dist/types/index.d.ts`): the root barrel of `src/index.ts` | TypeScript consumers | Public, pinned by the barrel test | Same | `package.json`, `src/index.ts` |
|
|
677
|
+
| Public plugin `cc` and its methods and properties | Applications | Public | Same | `src/cc.ts`, `src/index.ts` |
|
|
678
|
+
| `exports['./package']` | Tooling | Public | Same | `package.json` |
|
|
679
|
+
| `umd/contact-center.min.js` | Script-tag pages | Public | Rebuilt by the workspace webpack entry | `src/webex.js` |
|
|
680
|
+
|
|
681
|
+
`yarn workspace @webex/contact-center build` writes the declarations to dist/types; `yarn workspace @webex/contact-center build:docs` publishes the typedoc API
|
|
682
|
+
reference. No API report exists.
|
|
683
|
+
|
|
684
|
+
## Host integration and theming
|
|
685
|
+
|
|
686
|
+
The module registers as `cc` through the Webex SDK plugin system and depends on host-provided Webex credentials, configuration, request routing, and lifecycle events. It renders no UI and defines no theme contract.
|
|
687
|
+
|
|
688
|
+
- Mount or entry contract: `registerPlugin('cc', ContactCenter, {config})` on import; reached as `webex.cc`.
|
|
689
|
+
- Required providers, peers, or host versions: an authorized host with `credentials.getOrgId()`, `request`, `logger`, `internal.mercury`, `internal.device`, and `internal.support`; Node 20 or later per `package.json` engines.
|
|
690
|
+
- Theme and design-token contract: none.
|
|
691
|
+
- Accessibility and lifecycle obligations: call `register()` after READY and `deregister()` at teardown.
|
|
692
|
+
|
|
693
|
+
## Key design trade-off
|
|
694
|
+
|
|
695
|
+
| Chosen trade-off | Preserved invariant or benefit | Cost or limitation | Decision evidence |
|
|
696
|
+
| ---------------- | ------------------------------ | ------------------ | ----------------- |
|
|
697
|
+
| A single plugin surface centralizes compatibility and event routing, while specialized modules retain implementation ownership | One typed consumption boundary and one place for relogin policy | This costs careful bootstrap and cleanup ordering | `src/cc.ts` |
|
|
698
|
+
| Singleton `Services`, `WebexRequest`, `MetricsManager`, and `TaskManager` | Every collaborator shares one socket set and one task registry | Two plugin instances in one process share them | `src/cc.ts`, `src/services/index.ts` |
|
|
699
|
+
|
|
700
|
+
## Verification
|
|
701
|
+
|
|
702
|
+
`test/unit/spec/cc.ts` is the characterization baseline. Cover READY-time construction, registration success/failure, listener identity, existing queue/entry-point method delegation, WebSocket event mapping, preview-campaign operations (including disabled skip/remove pre-guards, which still need cases), automated-relogin enabled/disabled branches, browser-calling conditions, and deregistration cleanup/error paths. Use Queue and EntryPoint service tests for default policy and explicit existing-parameter overrides, `test/unit/spec/services/UserPreference.ts` for user-preference CRUD, and `test/unit/spec/services/task/dialer.ts` for preview AQM request contracts. Preserve the package-wide 85% branch/function/line/statement threshold.
|
|
703
|
+
|
|
704
|
+
All rows are unit level (Jest through `yarn workspace @webex/contact-center test:unit`).
|
|
705
|
+
|
|
706
|
+
| Requirement or invariant | Test level | Positive evidence | Negative or boundary evidence | Gap |
|
|
707
|
+
| ------------------------ | ---------- | ----------------- | ----------------------------- | --- |
|
|
708
|
+
| CONTACT_CENTER-R-001, `INV-001` | Unit | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts` | READY-time ownership and initialization order are asserted; none |
|
|
709
|
+
| CONTACT_CENTER-R-002 | Unit | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts` | register success/failure and log-upload path are covered; none |
|
|
710
|
+
| CONTACT_CENTER-R-003, `INV-003` | Unit | `test/unit/spec/cc.ts`, `test/unit/spec/services/UserPreference.ts`, `test/unit/spec/services/task/dialer.ts`, `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts` | `test/unit/spec/cc.ts` | Add direct tests proving disabled skip/remove flags throw before dialer invocation |
|
|
711
|
+
| CONTACT_CENTER-R-004 | Unit | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts` | listener/resource cleanup and error propagation are covered; the test does not assert that the registered `connectionLost` and `TASK_MERGED` callbacks are the ones removed, nor a deregister without agent configuration |
|
|
712
|
+
| CONTACT_CENTER-R-005, `INV-005` | Unit | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts` | relogin policy is covered through `silentRelogin`; add a direct `handleConnectionLost` case |
|
|
713
|
+
| CONTACT_CENTER-R-006, `INV-008`, `INV-009` | Unit | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | Effective-gate and organization/agent/session validation, current-session multi-login invalidation, registration-generation idle-code cache ownership, identity-free public input, exact request body, action validation, and direct-HTTP failure paths are covered; none |
|
|
714
|
+
| CONTACT_CENTER-R-007, `INV-010` | Unit | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/services/ApiAiAssistant.ts` | Wellness normalization on primary and RTD notification sockets, notification-session mismatch acceptance, invalid agent/org filtering, and active-session outbound validation are covered; none |
|
|
715
|
+
| CONTACT_CENTER-R-008 | Unit | `test/unit/spec/wellnessSampleUtils.ts` | `test/unit/spec/wellnessSampleUtils.ts` | Standalone browser constant exposure is checked through the sample surface guard; `src/webex.js` is not loaded by a unit case |
|
|
716
|
+
| CONTACT_CENTER-R-009, `INV-011` | Unit | `test/unit/spec/cc.ts`, `test/unit/spec/services/WebCallingService.ts` | `test/unit/spec/cc.ts` | none |
|
|
717
|
+
| CONTACT_CENTER-R-010, `INV-007` | Unit (TypeScript compiler) | `test/unit/spec/index.ts` | `test/unit/spec/index.ts` | no case loads `src/webex.js` |
|
|
718
|
+
| CONTACT_CENTER-R-011 | Unit | `test/unit/spec/cc.ts`, `test/unit/spec/services/WebexCrossClientService.ts` | `test/unit/spec/cc.ts` | no case for `allowMultiLogin: true` with the flag on |
|
|
719
|
+
| CONTACT_CENTER-R-012 | Unit | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts` | none |
|
|
720
|
+
| `INV-002` | Unit | `test/unit/spec/services/core/aqm-reqs.ts` | `test/unit/spec/services/core/aqm-reqs.ts` | owned by the services core module |
|
|
721
|
+
| `INV-004` | Unit | `test/unit/spec/cc.ts` | `test/unit/spec/cc.ts` | none |
|
|
722
|
+
| `INV-006` | Unit | `test/unit/spec/cc.ts` | None found | no case asserts that deregister sends no logout |
|
|
723
|
+
|
|
724
|
+
Record coverage gaps explicitly: the preview guards, `handleConnectionLost`, the listener-identity
|
|
725
|
+
defects, and the unguarded second `deregister()` have no unit case. A module specification is
|
|
726
|
+
complete only when its public surface, invariants, failure modes, and test evidence agree with the
|
|
727
|
+
implementation. Coverage measurement remains pending; independent validation on 2026-11-17 passed with warnings (0 Blocking, 0 Important, 4 Minor). No coverage promotion was performed.
|