@webex/contact-center 3.13.0-next.1 → 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 +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,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: ADR
|
|
3
|
+
title: ADR-0003 - Repo-standards migration
|
|
4
|
+
description: Migrate the earlier generated SDD documentation of @webex/contact-center into the repo-standards layout and delete the older documentation folders after review.
|
|
5
|
+
tags: [adr]
|
|
6
|
+
timestamp: 2026-11-16T00:00:00Z
|
|
7
|
+
status: accepted
|
|
8
|
+
---
|
|
9
|
+
<!-- sdd-generated-metadata
|
|
10
|
+
doc_kind: standing-doc
|
|
11
|
+
generated_from: adr@0.3.0
|
|
12
|
+
generated_by: claude-code
|
|
13
|
+
approved_by: rarajes2@cisco.com
|
|
14
|
+
updated_at: 2026-11-17T03:03:58Z
|
|
15
|
+
validation_status: pass-with-warnings
|
|
16
|
+
-->
|
|
17
|
+
|
|
18
|
+
# ADR-0003 - Repo-standards migration
|
|
19
|
+
|
|
20
|
+
| Field | Value |
|
|
21
|
+
| ------------- | ----- |
|
|
22
|
+
| Status | Accepted |
|
|
23
|
+
| Decision date | 2026-11-16 |
|
|
24
|
+
| Deciders | rarajes2@cisco.com (confirmed in chat) |
|
|
25
|
+
| Supersedes | [ADR-0001 - Spec source policy](0001-spec-source-policy.md) |
|
|
26
|
+
| Superseded by | N/A |
|
|
27
|
+
|
|
28
|
+
## Context
|
|
29
|
+
|
|
30
|
+
[ADR-0001](0001-spec-source-policy.md) made the earlier generated module specifications canonical and
|
|
31
|
+
kept the hand-written module guides beside them as reference-only material. Those specifications,
|
|
32
|
+
the package-wide architecture, contract, glossary, security, service-state, rules, pattern, and
|
|
33
|
+
template documents, and three earlier feature records all lived in documentation folders of an older
|
|
34
|
+
Repo Annotation layout. The monorepo root now holds one Repo Standards template set
|
|
35
|
+
(`../../../.sdd/templates/repo-standards`) that every onboarded package uses, and the older layout
|
|
36
|
+
leaves this package with two documentation shapes.
|
|
37
|
+
|
|
38
|
+
## Decision
|
|
39
|
+
|
|
40
|
+
Use the `migrate-existing` source policy again, this time into the repo-standards layout:
|
|
41
|
+
|
|
42
|
+
- Each of the nine manifest modules keeps its path; its canonical specification moves to the
|
|
43
|
+
`docs/README.md` file inside the module directory, listed in the
|
|
44
|
+
[Module registry](../specs/README.md#module-registry).
|
|
45
|
+
- Package-wide content moves by meaning into the standing documents under `docs/`
|
|
46
|
+
([architecture](../architecture.md), [getting started](../getting-started.md),
|
|
47
|
+
[specification registry](../specs/README.md), and these ADRs), into `.repo-context.json`, and
|
|
48
|
+
into the package [`AGENTS.md`](../../AGENTS.md), which is merged in place.
|
|
49
|
+
- The consult and transfer list policy becomes [ADR-0002](0002-consult-transfer-list-policy.md).
|
|
50
|
+
- `src/utils/AGENTS.md` is retained as reference-only context; the Utils module specification is
|
|
51
|
+
canonical.
|
|
52
|
+
- Every claim is checked against `src/` and `test/unit/spec` before it is carried; stale claims are
|
|
53
|
+
corrected or recorded as stale in the local source-fidelity inventories.
|
|
54
|
+
- The older documentation folders are deleted after source fidelity, conformance, the checkers, and
|
|
55
|
+
the user's review of the diff, in a separate final commit.
|
|
56
|
+
|
|
57
|
+
## Why
|
|
58
|
+
|
|
59
|
+
One template set across the monorepo gives agents and reviewers the same document shapes in every
|
|
60
|
+
package, and deleting the older folders after review removes the second documentation family that
|
|
61
|
+
ADR-0001 had to keep marked as reference-only.
|
|
62
|
+
|
|
63
|
+
## Alternatives considered
|
|
64
|
+
|
|
65
|
+
| Alternative | Why it was not selected |
|
|
66
|
+
| ----------- | ----------------------- |
|
|
67
|
+
| Keep the older layout beside the repo-standards documents (`keep-separate`) | Two documentation families with overlapping authority stay in the package |
|
|
68
|
+
| Reconcile the older documents in place (`reconcile`) | Keeps the older document shapes, which the root templates do not generate or check |
|
|
69
|
+
| Keep the older files with reference-only banners, as ADR-0001 did | The repo-standards documents carry the content by meaning, so the banners only preserve drift |
|
|
70
|
+
|
|
71
|
+
## Consequences
|
|
72
|
+
|
|
73
|
+
**Positive:**
|
|
74
|
+
|
|
75
|
+
- One canonical specification per module beside its code, and one standing-document set under
|
|
76
|
+
`docs/`, all generated from the root Repo Standards templates.
|
|
77
|
+
- No reference-only copies of migrated content remain once the deletion commit lands.
|
|
78
|
+
|
|
79
|
+
**Negative / tradeoffs:**
|
|
80
|
+
|
|
81
|
+
- History that lived only in the older documents (earlier correction records and onboarding
|
|
82
|
+
metadata) is kept in the local source-fidelity inventories, not in committed documents.
|
|
83
|
+
- Coverage states are carried, not reassessed, until a fresh coverage review runs.
|
|
84
|
+
|
|
85
|
+
## Constraint on future changes
|
|
86
|
+
|
|
87
|
+
Change a module's behavior together with its `docs/README.md` specification and, for a contract,
|
|
88
|
+
the architecture contract index and `.sdd/manifest.json`. Do not reintroduce a parallel
|
|
89
|
+
documentation folder; code and tests remain the behavioral referee.
|
|
90
|
+
|
|
91
|
+
## Follow-up
|
|
92
|
+
|
|
93
|
+
- [ ] Delete the older documentation folders in a separate commit after the user reviews the diff.
|
|
94
|
+
- [ ] Run a coverage review and an independent validation on another runtime.
|
|
95
|
+
|
|
96
|
+
## Revisit when
|
|
97
|
+
|
|
98
|
+
- The root Repo Standards templates change their layout, or a module is added, split, or moved.
|
|
99
|
+
|
|
100
|
+
## References
|
|
101
|
+
|
|
102
|
+
- `.sdd/manifest.json` `spec_source_policy`, `spec_sources`, and `template_migration`
|
|
103
|
+
- [ADR-0001 - Spec source policy](0001-spec-source-policy.md)
|
|
104
|
+
- [Specification registry](../specs/README.md)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
<!-- sdd-generated-metadata
|
|
2
|
+
doc_kind: standing-doc
|
|
3
|
+
generated_from: adr-index@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
|
+
# Architectural decision records
|
|
11
|
+
|
|
12
|
+
Use this append-only directory for numbered records of durable decisions that constrain future Contact
|
|
13
|
+
Center SDK work and its documentation.
|
|
14
|
+
Add a concrete ADR (for example, `0042-cache-policy.md`) when a decision is non-obvious, hard to
|
|
15
|
+
reverse, or worth explaining to a future contributor. Do not edit an accepted decision in place when
|
|
16
|
+
its outcome changes; supersede it with a new ADR and link both records.
|
|
17
|
+
|
|
18
|
+
- One decision per `NNNN-short-title.md` file in this folder, started from the repo-standards ADR
|
|
19
|
+
template under the monorepo root `.sdd/templates/repo-standards/docs/adr/`.
|
|
20
|
+
- Link ADRs from the affected module specs and the [package architecture](../architecture.md).
|
|
21
|
+
|
|
22
|
+
## Index
|
|
23
|
+
|
|
24
|
+
- [ADR-0001 - Spec source policy](0001-spec-source-policy.md) — accepted 2026-07-07; superseded by
|
|
25
|
+
ADR-0003
|
|
26
|
+
- [ADR-0002 - Consult and transfer list policy](0002-consult-transfer-list-policy.md) — accepted
|
|
27
|
+
2026-08-19
|
|
28
|
+
- [ADR-0003 - Repo-standards migration](0003-repo-standards-migration.md) — accepted 2026-11-16;
|
|
29
|
+
supersedes ADR-0001
|
|
30
|
+
|
|
31
|
+
Add new entries as ADRs are accepted. Keep this list in numeric order.
|
|
32
|
+
|
|
33
|
+
Each ADR should state its context, decision, alternatives, consequences, and the condition that would
|
|
34
|
+
cause the team to revisit it. Record the deciders, any superseded decision, and the constraint future
|
|
35
|
+
changes must preserve.
|
|
@@ -0,0 +1,460 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: Architecture
|
|
3
|
+
title: '@webex/contact-center architecture'
|
|
4
|
+
description: Package-wide boundaries, resources, interactions, dependencies, contracts, and cross-cutting architecture.
|
|
5
|
+
tags: [architecture]
|
|
6
|
+
---
|
|
7
|
+
<!-- sdd-generated-metadata
|
|
8
|
+
doc_kind: standing-doc
|
|
9
|
+
generated_from: architecture@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
|
+
# @webex/contact-center architecture
|
|
17
|
+
|
|
18
|
+
Canonical architecture for the `@webex/contact-center` package. This page owns the package
|
|
19
|
+
boundaries, the module inventory, how the modules interact with each other and with the Webex SDK host
|
|
20
|
+
and the Contact Center backend, the contract index, and the cross-cutting security, observability, and
|
|
21
|
+
state rules. Behavior of each module lives in its module specification, listed in the
|
|
22
|
+
[specification registry](specs/README.md).
|
|
23
|
+
|
|
24
|
+
Related context: [specification registry](specs/README.md) ·
|
|
25
|
+
[package agent instructions](../AGENTS.md)
|
|
26
|
+
|
|
27
|
+
## Applicability
|
|
28
|
+
|
|
29
|
+
| Condition ID | Status | Evidence or reason | Owned section |
|
|
30
|
+
| ------------------------------------ | ---------- | ------------------ | ------------- |
|
|
31
|
+
| `repo.owns_datastore` | N/A | No file under src writes durable storage; remote Contact Center services own agent, task, and configuration records, and `src/utils/PageCache.ts` is an in-memory Map | Repository data and schema |
|
|
32
|
+
| `repo.holds_client_state` | Applicable | `src/cc.ts` keeps the agent profile and session; `src/services/task/TaskManager.ts` keeps the task collection; `src/services/WebCallingService.ts` keeps the voice connection state | Client state model |
|
|
33
|
+
| `repo.components_interact` | Applicable | `src/cc.ts` constructs and wires Services, TaskManager, MetricsManager, WebCallingService, and the data services | Dependency and interaction topology |
|
|
34
|
+
| `repo.domain_data_across_components` | Applicable | The agent profile from `src/services/config/index.ts` is read by `src/cc.ts`, the task layer, and the AI assistant | Object and data ownership |
|
|
35
|
+
| `repo.caches_data` | Applicable | `src/utils/PageCache.ts`, used by `src/services/AddressBook.ts` and `src/services/Queue.ts` | Caching catalog |
|
|
36
|
+
| `repo.observability_convention` | Applicable | `src/logger-proxy.ts` log format and `src/metrics/MetricsManager.ts` event taxonomy | Observability patterns |
|
|
37
|
+
| `repo.deploys_to_infra` | N/A | Library published to npm by the deploy:npm script in `package.json`; it runs inside the host application and owns no infrastructure | Runtime and infrastructure |
|
|
38
|
+
| `repo.shared_base_libs` | Applicable | ContactCenter extends WebexPlugin from @webex/webex-core (`src/cc.ts`); the legacy build and test stack comes from `babel.config.js` and `jest.config.js`, and lint from the workspace root ESLint config | Shared and base libraries |
|
|
39
|
+
| `repo.is_monorepo` | N/A | This SDD root is one package; the workspace around it is out of scope (`package.json`) | Package map and inter-package dependencies |
|
|
40
|
+
| `repo.multi_platform` | N/A | One browser-oriented code path; `src/webex.js` is both the npm main and the UMD entry | Platform matrix |
|
|
41
|
+
| `repo.published_package` | Applicable | `package.json` publishes @webex/contact-center through the deploy:npm script | Release and versioning |
|
|
42
|
+
| `repo.embedded_in_host` | Applicable | `src/index.ts` registers the plugin cc into the host Webex SDK | Host integration and theming |
|
|
43
|
+
| `repo.exposes_commands_or_artifacts` | Applicable | `package.json` scripts; `typedoc.json` writes the API reference; the workspace webpack builds `umd/contact-center.min.js` from `src/webex.js` | Commands and generated artifacts |
|
|
44
|
+
| `repo.cross_repo_deps_material` | Applicable | Every agent and task operation depends on the Contact Center API gateway and notification WebSocket (`src/services/core/WebexRequest.ts`, `src/services/core/websocket/WebSocketManager.ts`) | Cross-repository topology |
|
|
45
|
+
| `repo.security_arch_warranted` | Applicable | Host credentials, agent identity, dial numbers, and customer interaction data cross `src/services/core/WebexRequest.ts` and the WebSocket handlers in `src/cc.ts` | Security architecture |
|
|
46
|
+
|
|
47
|
+
## Design overview
|
|
48
|
+
|
|
49
|
+
The `@webex/contact-center` package is a Webex SDK plugin that provides a TypeScript/JavaScript API for building Contact Center agent applications. It enables:
|
|
50
|
+
|
|
51
|
+
- **Agent Session Management**: Register, login, logout, state changes
|
|
52
|
+
- **Task Handling**: Inbound/outbound calls, chat, transfers, conferences
|
|
53
|
+
- **Real-time Events**: WebSocket-based notifications for agent and task events
|
|
54
|
+
- **Browser-based Calling**: WebRTC integration for browser softphone
|
|
55
|
+
- **Metrics & Diagnostics**: Built-in telemetry and log upload
|
|
56
|
+
|
|
57
|
+
The package is a host-embedded SDK plugin. `ContactCenter` owns the public façade and composes services for configuration, agent requests, tasks/calling, data lookup, realtime events, transport, and metrics. Remote Webex services own durable domain data.
|
|
58
|
+
|
|
59
|
+
Two interaction styles are deliberate: direct REST for immediate data/configuration responses, and AQM HTTP initiation followed by correlated WebSocket completion for event-driven agent/task operations. Typed events and XState isolate consumers from raw backend messages.
|
|
60
|
+
|
|
61
|
+
| Technology | Purpose |
|
|
62
|
+
|------------|---------|
|
|
63
|
+
| **TypeScript** | Primary language; the workspace `tsconfig.json` sets `alwaysStrict`, not the full `strict` flag |
|
|
64
|
+
| **WebexPlugin** | Base class from `@webex/webex-core` |
|
|
65
|
+
| **EventEmitter** | Event handling for real-time updates |
|
|
66
|
+
| **WebSocket** | Real-time communication with Contact Center |
|
|
67
|
+
| **WebRTC** | Browser-based calling (via WebCalling) |
|
|
68
|
+
| **Jest** | Unit testing framework |
|
|
69
|
+
|
|
70
|
+
## Resource inventory and responsibilities
|
|
71
|
+
|
|
72
|
+
The package is one published resource made of nine manifest modules.
|
|
73
|
+
|
|
74
|
+
| Resource | Kind | Responsibility | Owner | Source | Detailed specification |
|
|
75
|
+
| -------- | ---- | -------------- | ----- | ------ | ---------------------- |
|
|
76
|
+
| @webex/contact-center | package (nine modules) | The Contact Center agent SDK plugin `webex.cc`, its standalone `Webex` constructor, and its public exports | @webex/web-sdk | `package.json` | [Specification registry](specs/README.md) |
|
|
77
|
+
|
|
78
|
+
| Component | Responsibility (one line) | Docs |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| `src` | Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing. | [`src/docs/README.md`](../src/docs/README.md) |
|
|
81
|
+
| `src/metrics` | Own timing, taxonomy, queuing, payload preparation, and submission for Contact Center behavioral, operational, and business telemetry. | [`src/metrics/docs/README.md`](../src/metrics/docs/README.md) |
|
|
82
|
+
| `src/services` | Own composition and bootstrap order for backend request and realtime collaborators (the Services singleton), plus the direct REST data, user preference, AI assistant, and WebRTC service classes that ContactCenter constructs. | [`src/services/docs/README.md`](../src/services/docs/README.md) |
|
|
83
|
+
| `src/services/agent` | Own agent login, logout, state-change, buddy-agent, and reload request contracts; ContactCenter uses reload for silent relogin and stationLogin for device updates. | [`src/services/agent/docs/README.md`](../src/services/agent/docs/README.md) |
|
|
84
|
+
| `src/services/config` | Own retrieval and aggregation of remote organization, agent, team, profile, auxiliary-code, dial-plan, and feature configuration. | [`src/services/config/docs/README.md`](../src/services/config/docs/README.md) |
|
|
85
|
+
| `src/services/core` | Own authenticated HTTP, realtime WebSocket lifecycle, AQM request correlation, reconnect/keepalive behavior, and shared error normalization. | [`src/services/core/docs/README.md`](../src/services/core/docs/README.md) |
|
|
86
|
+
| `src/services/task` | Own task creation, media-specific behavior, call-control operations, lifecycle orchestration, task events, and integration with the task state machine. | [`src/services/task/docs/README.md`](../src/services/task/docs/README.md) |
|
|
87
|
+
| `src/services/task/state-machine` | Own deterministic task lifecycle states, transition guards/actions, typed internal events, and state-derived UI-control availability. | [`src/services/task/state-machine/docs/README.md`](../src/services/task/state-machine/docs/README.md) |
|
|
88
|
+
| `src/utils` | Own shared pagination contracts and the bounded in-memory page cache used by Contact Center data services. | [`src/utils/docs/README.md`](../src/utils/docs/README.md) |
|
|
89
|
+
|
|
90
|
+
Object composition at runtime (`src/cc.ts`, `src/services/index.ts`):
|
|
91
|
+
|
|
92
|
+
```text
|
|
93
|
+
ContactCenter (cc.ts), constructed on the Webex READY event
|
|
94
|
+
├── WebexRequest (singleton) → authenticated HTTP and log upload
|
|
95
|
+
├── Services (singleton)
|
|
96
|
+
│ ├── agent/ → Agent operations (login, logout, state, buddy agents, reload)
|
|
97
|
+
│ ├── config/ → Configuration fetching
|
|
98
|
+
│ ├── contact, dialer → Task operations (hold, transfer, wrapup, outdial, campaign preview)
|
|
99
|
+
│ └── core/ → WebSocketManager (primary and RTD), ConnectionService, AqmReqs
|
|
100
|
+
├── TaskManager → Task lifecycle (Task, Voice, WebRTC, Digital)
|
|
101
|
+
├── WebCallingService, ApiAIAssistant, MetricsManager
|
|
102
|
+
├── AnswerCallOnWebexService, WebexCrossClientService, WxAppTelephonyMercurySync → Better Together (wxApp) answer, cross-client state, and Mercury mute sync
|
|
103
|
+
└── AddressBook, EntryPoint, Queue, UserPreference → direct REST data services
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Interaction and execution flows
|
|
107
|
+
|
|
108
|
+
```mermaid
|
|
109
|
+
flowchart LR
|
|
110
|
+
Host[Host Webex SDK] --> CC[ContactCenter]
|
|
111
|
+
CC --> Services
|
|
112
|
+
CC --> Task
|
|
113
|
+
CC --> Metrics
|
|
114
|
+
Services --> Agent
|
|
115
|
+
Services --> Config
|
|
116
|
+
Services --> Core
|
|
117
|
+
Services --> Utils
|
|
118
|
+
Task --> StateMachine[Task state machine]
|
|
119
|
+
Services --> REST[WCC REST]
|
|
120
|
+
Core <--> WS[WCC WebSocket]
|
|
121
|
+
Task --> Calling[Webex Calling/WebRTC]
|
|
122
|
+
Metrics --> Telemetry[Webex metrics]
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Nodes are manifest modules: `Services` is the `src/services` module, whose AddressBook and Queue
|
|
126
|
+
classes use the Utils page cache.
|
|
127
|
+
|
|
128
|
+
Public calls enter through `src/cc.ts`; direct REST returns through WebexRequest, while AQM operations resolve after matching WebSocket notifications. TaskManager converts backend events to task/state-machine events.
|
|
129
|
+
|
|
130
|
+
The collaborators in the composition tree are built once, on the Webex READY event; `register()` only subscribes to realtime messages, connects the WebSocket, obtains the remote agent profile, and routes agent/task events, and `deregister()` tears down listeners/connections.
|
|
131
|
+
|
|
132
|
+
| From | To | Interaction or transport | Purpose | Failure or compatibility behavior |
|
|
133
|
+
| ---- | -- | ------------------------ | ------- | --------------------------------- |
|
|
134
|
+
| Host application | `webex.cc` | In-process method calls and plugin events | Agent, task, data, and diagnostics operations | Promises reject with the errors described in the owning module spec; `register()` uploads logs on failure |
|
|
135
|
+
| `ContactCenter` | Services agent and dialer factories | AqmReqs: HTTP request, then a matched WebSocket notification | Station login, logout, state change, buddy agents, outdial, campaign preview | Settles on the success or failure notification or on the 20000 ms `TIMEOUT_REQ` default (`src/services/core/constants.ts`) |
|
|
136
|
+
| `ContactCenter` data services | Contact Center API gateway | WebexRequest HTTP | Address book, entry points, queues, user preferences, AI assistant | HTTP errors propagate after metrics and logging |
|
|
137
|
+
| ConnectionService | `ContactCenter` | `connectionLost` event | Socket loss and reconnect | On reconnect, `silentRelogin()` runs when `allowAutomatedRelogin` is true |
|
|
138
|
+
| WebSocketManager (primary and RTD) | ContactCenter, TaskManager, AqmReqs | `message` events | Realtime routing and AQM request completion | Unknown message types are ignored |
|
|
139
|
+
| TaskManager | Task instances and `ContactCenter` | Task events | Task offer, hydrate, merge, and lifecycle | Malformed or unknown messages are ignored |
|
|
140
|
+
|
|
141
|
+
## Dependency topology
|
|
142
|
+
|
|
143
|
+
| Dependency | Type (internal / external / peer) | How used | Failure / version handling |
|
|
144
|
+
|---|---|---|---|
|
|
145
|
+
| `@webex/webex-core` | external / peer | Runtime package dependency: plugin host, request/service routing; required | Workspace/declared version; errors propagate through owning module and fail the operation |
|
|
146
|
+
| `@webex/calling` | external / peer | Runtime package dependency: browser line/call lifecycle, required for BROWSER login | Workspace/declared version; calling failures are surfaced to the caller |
|
|
147
|
+
| `@webex/internal-plugin-metrics` | external / peer | Runtime package dependency: telemetry submission through MetricsManager; host-dependent | Workspace/declared version; nonblocking, errors never break the product flow |
|
|
148
|
+
| `@webex/internal-plugin-mercury` | external / peer | Runtime package dependency: Better Together (wxApp) telephony events | Workspace/declared version; errors propagate through owning module |
|
|
149
|
+
| `@webex/internal-plugin-support` | external / peer | Runtime package dependency for log upload (`uploadLogs`) | Workspace/declared version; upload errors are logged and rethrown by `src/services/core/WebexRequest.ts` |
|
|
150
|
+
| `@webex/plugin-authorization`, `@webex/plugin-logger` | external / peer | Loaded by `src/webex.js` for the standalone constructor (identity, logging) | Workspace/declared version |
|
|
151
|
+
| `xstate` | external | Task state machine runtime | Pinned `5.24.0` in `package.json` |
|
|
152
|
+
| `wcc-api-gateway` and the WCC notification WebSocket | external Webex service | Service-catalog identifier resolved through the host Webex SDK, not an npm package dependency; agent, task, config, and realtime contracts, required for runtime operations | Host service-catalog availability; structured error, reconnect, or timeout through the owning module against a remote compatible contract |
|
|
153
|
+
|
|
154
|
+
- Workspace glob: root `package.json` `workspaces`; this scoped package is public and consumes internal/public sibling packages through `workspace:*` dependencies, so it always builds against the sibling sources in the same checkout; `yarn workspace @webex/contact-center build` first runs `build:src` for `@webex/calling`.
|
|
155
|
+
|
|
156
|
+
No import cycle exists: the sibling packages this package uses do not import it.
|
|
157
|
+
|
|
158
|
+
## Public and consumer surfaces
|
|
159
|
+
|
|
160
|
+
The contract index: one row per `contract_catalog.definitions` ID in `.sdd/manifest.json`. Exact
|
|
161
|
+
definitions stay in the native TypeScript sources; the behavior of each symbol group is specified in
|
|
162
|
+
the owning module specification linked in the Owner column.
|
|
163
|
+
|
|
164
|
+
| Surface | Type | Owner | Consumers | Compatibility policy | Source |
|
|
165
|
+
| ------- | ---- | ----- | --------- | -------------------- | ------ |
|
|
166
|
+
| `contact-center-sdk` — npm package @webex/contact-center: `webex.cc` (`ContactCenter`, implementing `IContactCenter`) with station login, agent state, browser voice state (`getVoiceConnectionState`), buddy agents, queue and entry-point lists, campaign preview, Better Together, and wellness methods; `routingAgent`, `Task`, `AddressBook`, `ApiAIAssistant`, `UserPreference`, `getDefaultUIControls`, the event enums, and the public types | SDK, published | [`src`](../src/docs/README.md); data services in [`src/services`](../src/services/docs/README.md); consult and transfer defaults in [ADR-0002](adr/0002-consult-transfer-list-policy.md) | Agent desktop applications, the Contact Center sample, widgets | Public, semver: removals, renames, payload reinterpretation, or semantic breaks need a major version | `package.json` |
|
|
167
|
+
| `contact-center-cc-events` — `CC_EVENTS`, `CC_AGENT_EVENTS` (including `WELLNESS_BREAK`), `CC_TASK_EVENTS`, `VOICE_CONNECTION_EVENTS` (`voice:connectionStateChange`) | Event, published | [`src/services/config`](../src/services/config/docs/README.md); emission by ContactCenter in [`src`](../src/docs/README.md) | Applications; AqmReqs, ContactCenter, and TaskManager | Additive; values equal backend message names | `src/services/config/types.ts` |
|
|
168
|
+
| `contact-center-agent-events` — `AGENT_EVENTS` (`agent:*`) and agent request and response types | Event, published | [`src/services/agent`](../src/services/agent/docs/README.md) | Applications | Additive constants | `src/services/agent/types.ts` |
|
|
169
|
+
| `contact-center-task-events` — `TASK_EVENTS` (`task:*`, including `task:hydrate`, `task:wrapup`, `task:midCallSummaryReceived`, `task:wxapp-mute-state-updated`), `TaskData`, `TaskResponse`, and task payload types | Event, published | [`src/services/task`](../src/services/task/docs/README.md) | Applications holding `ITask` objects | Additive constants; semantic extensions keep existing event names | `src/services/task/types.ts` |
|
|
170
|
+
| `contact-center-task-state-machine` — state machine factory, `TaskState`, `TaskEvent`, guards, actions, UI-control computer | SDK, internal (only `getDefaultUIControls` is re-exported) | [`src/services/task/state-machine`](../src/services/task/state-machine/docs/README.md) | Task and TaskManager | Internal; `TaskUIControls` fields are public and additive | `src/services/task/state-machine/index.ts` |
|
|
171
|
+
| `contact-center-services` — Services composition root and request factories | SDK, internal | [`src/services`](../src/services/docs/README.md) | ContactCenter, TaskManager | Internal | `src/services/index.ts` |
|
|
172
|
+
| `contact-center-core-transport` — AqmReqs, WebexRequest, WebSocketManager, ConnectionService, error helpers | SDK, internal | [`src/services/core`](../src/services/core/docs/README.md) | Services, ContactCenter, TaskManager | Internal | `src/services/core/aqm-reqs.ts` |
|
|
173
|
+
| `contact-center-metrics` — `METRIC_EVENT_NAMES` and the MetricsManager submission API | Event, internal | [`src/metrics`](../src/metrics/docs/README.md) | Every module that tracks events | Internal; names reach the Webex metrics backend | `src/metrics/constants.ts` |
|
|
174
|
+
| `contact-center-page-cache` — PageCache and pagination types and defaults | SDK, internal | [`src/utils`](../src/utils/docs/README.md) | AddressBook, Queue; EntryPoint reads its defaults | Internal | `src/utils/PageCache.ts` |
|
|
175
|
+
| `wxcc-api-gateway` — Contact Center REST API through `webex.request` service `wcc-api-gateway` | HTTP, external | Contact Center backend | Services, Config, data services | Owned by the backend; the package owns no route | Webex Contact Center API gateway (external) |
|
|
176
|
+
| `wxcc-websocket-notifications` — Contact Center notification WebSocket, primary and RTD | Event, external | Contact Center backend | Core, ContactCenter, TaskManager | Owned by the backend; names mirrored in `CC_EVENTS` | Webex Contact Center notification WebSocket (external) |
|
|
177
|
+
| `webex-core-plugin-runtime` — `registerPlugin`, `WebexPlugin`, `webex.request`, READY | SDK, external | `@webex/webex-core` | `src/index.ts`, `src/cc.ts` | Workspace version | @webex/webex-core workspace package (external) |
|
|
178
|
+
| `webex-calling-sdk` — calling client, line, call objects | SDK, external | `@webex/calling` | WebCallingService, WebRTC tasks | Workspace version | @webex/calling workspace package (external) |
|
|
179
|
+
| `webex-internal-mercury` — Mercury event stream | SDK, external | `@webex/internal-plugin-mercury` | Better Together (wxApp) telephony synchronisation | Workspace version | @webex/internal-plugin-mercury workspace package (external) |
|
|
180
|
+
| `webex-internal-metrics` — internal metrics submission | SDK, external | `@webex/internal-plugin-metrics` | MetricsManager | Workspace version | @webex/internal-plugin-metrics workspace package (external) |
|
|
181
|
+
| `webex-internal-support` — log upload | SDK, external | `@webex/internal-plugin-support` | `uploadLogs` | Workspace version | @webex/internal-plugin-support workspace package (external) |
|
|
182
|
+
| `xstate-runtime` — actor and state-machine runtime | SDK, external | `xstate` | Task state machine | Pinned 5.24.0 | xstate npm dependency (external) |
|
|
183
|
+
|
|
184
|
+
No OpenAPI/AsyncAPI/proto schema was found in scope; exact SDK and event contracts remain in TypeScript declarations and owning module specs.
|
|
185
|
+
|
|
186
|
+
<!-- Include if: the repository holds client-side or in-memory session state. [condition-id: repo.holds_client_state] -->
|
|
187
|
+
|
|
188
|
+
## Client state model
|
|
189
|
+
|
|
190
|
+
- ContactCenter retains agent profile, task collections, WebSocket/reconnect flags, metrics queues/timers, page-cache entries, and task actors in memory.
|
|
191
|
+
- Remote systems remain authoritative for agent/task/configuration records.
|
|
192
|
+
|
|
193
|
+
| State or slice | Owner | Transition triggers | Persistence or reset boundary |
|
|
194
|
+
| -------------- | ----- | ------------------- | ----------------------------- |
|
|
195
|
+
| Agent profile (`agentConfig`) and active station session | `ContactCenter` (`src/cc.ts`) | `register()`, station login, logout, silent relogin | Memory; cleared by `deregister()` |
|
|
196
|
+
| Task collection | TaskManager (`src/services/task/TaskManager.ts`) | Contact notifications, hydration, task removal | Memory; one XState actor per task |
|
|
197
|
+
| Voice connection state | WebCallingService (`src/services/WebCallingService.ts`) | Line registration and Mobius socket events | Memory; reset on line deregistration |
|
|
198
|
+
| Pending metrics events | MetricsManager (`src/metrics/MetricsManager.ts`) | `trackEvent`, the metrics ready signal | Memory; cleared when metrics are disabled |
|
|
199
|
+
| Cached pages | PageCache (`src/utils/PageCache.ts`) | `cachePage`, expiry on read | Memory; five-minute TTL |
|
|
200
|
+
|
|
201
|
+
## Cross-cutting architecture
|
|
202
|
+
|
|
203
|
+
### Security
|
|
204
|
+
|
|
205
|
+
- Trust boundaries, identity flow, credentials, data classes, and sensitive areas: see [Security architecture](#security-architecture).
|
|
206
|
+
|
|
207
|
+
### Observability and operations
|
|
208
|
+
|
|
209
|
+
- Logging, metrics, and diagnostic log upload conventions: see [Observability patterns](#observability-patterns).
|
|
210
|
+
- Ownership: the workspace `.github/CODEOWNERS` default rule assigns `@webex/web-sdk`; no line names this package. No dashboards or runbooks are recorded in this package.
|
|
211
|
+
|
|
212
|
+
### Quality attributes
|
|
213
|
+
|
|
214
|
+
Package compatibility and event-loop safety are primary: published exports/types are semver-sensitive, telemetry is non-blocking, listeners are cleaned up, and reconnect/timeouts are explicit.
|
|
215
|
+
|
|
216
|
+
| Signal | Target | Where measured |
|
|
217
|
+
|---|---|---|
|
|
218
|
+
| Unit coverage | 85% branches/functions/lines/statements | package Jest configuration |
|
|
219
|
+
| Operation duration/success/failure | no local numeric SLO routed | MetricsManager event taxonomy |
|
|
220
|
+
| Connection recovery | explicit 8s disconnect, 5s retry, configured restore timeout (50s `LOST_CONNECTION_RECOVERY_TIMEOUT` default) | Core constants/ConnectionService |
|
|
221
|
+
|
|
222
|
+
<!-- Include if: repository resources call, import, or exchange events with one another. [condition-id: repo.components_interact] -->
|
|
223
|
+
|
|
224
|
+
## Dependency and interaction topology
|
|
225
|
+
|
|
226
|
+
The representative flow above shows the calls into Services and Core. This view adds the feedback
|
|
227
|
+
and event edges it does not show: realtime events back into ContactCenter and Task, the state
|
|
228
|
+
machine's actions and UI controls back to Task, and the data services' use of the page cache. The
|
|
229
|
+
event names on these edges are indexed in [Public and consumer surfaces](#public-and-consumer-surfaces).
|
|
230
|
+
|
|
231
|
+
```mermaid
|
|
232
|
+
flowchart TD
|
|
233
|
+
Core -->|events| CC
|
|
234
|
+
Core -->|events| Task
|
|
235
|
+
StateMachine -->|actions/UI controls| Task
|
|
236
|
+
DataServices[Data services] -->|call| PageCache
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
| From | To | Kind (call / event) | Purpose |
|
|
240
|
+
|---|---|---|---|
|
|
241
|
+
| Task state machine | Task | event | Actions and UI-control updates applied back to the Task |
|
|
242
|
+
| Data services | PageCache | call | Bounded pagination reuse |
|
|
243
|
+
|
|
244
|
+
<!-- Include if: repository-owned domain data spans multiple resources. [condition-id: repo.domain_data_across_components] -->
|
|
245
|
+
|
|
246
|
+
## Object and data ownership
|
|
247
|
+
|
|
248
|
+
| Domain object | System-of-record (owning component) | Read by |
|
|
249
|
+
|---|---|---|
|
|
250
|
+
| Agent/Profile | Remote WCC services; Config aggregates a local view | ContactCenter, Agent, Task |
|
|
251
|
+
| Task/Interaction | Remote WCC services; Task owns client representation | ContactCenter consumers |
|
|
252
|
+
| Metric event | Metrics module until submission; remote metrics backend after submit | Observability systems |
|
|
253
|
+
| Cached page | Utils PageCache (ephemeral only) | AddressBook, Queue |
|
|
254
|
+
|
|
255
|
+
The package owns no datastore:
|
|
256
|
+
|
|
257
|
+
| Store | Purpose | Owned by this service? |
|
|
258
|
+
|---|---|---|
|
|
259
|
+
| In-memory PageCache Map | temporary paginated lookup reuse | ephemeral only; yes for cache entries |
|
|
260
|
+
| Remote WCC stores | agent/task/config domain state | no |
|
|
261
|
+
|
|
262
|
+
<!-- Include if: the repository caches data. [condition-id: repo.caches_data] -->
|
|
263
|
+
|
|
264
|
+
## Caching catalog
|
|
265
|
+
|
|
266
|
+
| Cache | Backend | What it holds | TTL | Invalidation trigger |
|
|
267
|
+
|---|---|---|---|---|
|
|
268
|
+
| PageCache | in-memory Map, one per AddressBook or Queue instance | simple paginated data-service pages keyed by `bookId` or `orgId`, page, and page size | 5 minutes | expiry on read; `clearCache()` exists but no consumer calls it; search, filter, attributes, sort, and profile-view queries bypass |
|
|
269
|
+
|
|
270
|
+
Failure behavior: a cache miss or bypass makes the backend request; a backend failure is not cached.
|
|
271
|
+
Cache eligibility rules are in the [Utils spec](../src/utils/docs/README.md) and
|
|
272
|
+
[ADR-0002](adr/0002-consult-transfer-list-policy.md).
|
|
273
|
+
|
|
274
|
+
<!-- Include if: the repository has logging, metrics, tracing, or audit conventions worth standardizing. [condition-id: repo.observability_convention] -->
|
|
275
|
+
|
|
276
|
+
## Observability patterns
|
|
277
|
+
|
|
278
|
+
- **Logging:** LoggerProxy with module/method and tracking/interaction identifiers; no credentials or sensitive payloads.
|
|
279
|
+
- **Metrics:** METRIC_EVENT_NAMES plus behavioral taxonomy and `WXCC_SDK_` operational/business names.
|
|
280
|
+
- **Audit:** no local audit store; remote services own operational records.
|
|
281
|
+
- **Log upload:** `register()` failures and the shared error helpers upload diagnostic logs through `uploadLogs` (`src/services/core/WebexRequest.ts`).
|
|
282
|
+
|
|
283
|
+
| Signal | Convention or required fields | Propagation or naming rule | Primary evidence |
|
|
284
|
+
| ------- | ----------------------------- | -------------------------- | ---------------- |
|
|
285
|
+
| Logs | `LoggerProxy.log`, `info`, `warn`, `error`, `trace` with a `{module, method}` context, optional `interactionId`, `trackingId`, `data`, `error` | Formatted as `module:… - method:… - interactionId:… - trackingId:…` after the package log prefix; `redactSensitiveLogs` on an AQM request suppresses URLs and routing payloads | `src/logger-proxy.ts` |
|
|
286
|
+
| Metrics | `trackEvent(name, payload, ['behavioral' / 'operational' / 'business'])`; `timeEvent` adds durations | Operational and business names are submitted as `WXCC_SDK_` followed by the event name; behavioral names map through the taxonomy | `src/metrics/MetricsManager.ts` |
|
|
287
|
+
| Traces | None | Backend `trackingId` values are carried into logs and metrics | `src/metrics/MetricsManager.ts` |
|
|
288
|
+
| Audit | None | Remote services own operational records | `src/cc.ts` |
|
|
289
|
+
|
|
290
|
+
<!-- Include if: modules inherit a shared or base library stack. [condition-id: repo.shared_base_libs] -->
|
|
291
|
+
|
|
292
|
+
## Shared and base libraries
|
|
293
|
+
|
|
294
|
+
| Library | What every module inherits from it | Version floor |
|
|
295
|
+
|---|---|---|
|
|
296
|
+
| LoggerProxy/MetricsManager | package logging and telemetry conventions | package-local |
|
|
297
|
+
| `@webex/babel-config-legacy`, `@webex/jest-config-legacy`, `@webex/legacy-tools` | build and test stack (`babel.config.js`, `jest.config.js`, which adds the 85% coverage threshold); lint uses the workspace root ESLint config because the package has no ESLint config of its own | workspace version |
|
|
298
|
+
|
|
299
|
+
<!-- Include if: the repository publishes a package or consumer artifact. [condition-id: repo.published_package] -->
|
|
300
|
+
|
|
301
|
+
## Release and versioning
|
|
302
|
+
|
|
303
|
+
| Artifact | Publish target | Versioning rule | Deprecation window | Changelog or migration obligation |
|
|
304
|
+
| -------- | -------------- | --------------- | ------------------ | --------------------------------- |
|
|
305
|
+
| `@webex/contact-center`, including `dist/types` | npm through `yarn workspace @webex/contact-center deploy:npm` | Semver through the workspace release tooling | None declared | The workspace generates changelogs centrally; a removal, rename, payload reinterpretation, or semantic break needs a major-version consumer transition, consumer notes, and a `BREAKING CHANGE:` note |
|
|
306
|
+
| UMD `umd/contact-center.min.js` | Committed bundle served to the Contact Center sample | Built by the workspace webpack from `src/webex.js` | None declared | Rebuild with the package |
|
|
307
|
+
|
|
308
|
+
- **Deprecation:** mark symbols/types in source/JSDoc, retain through an announced transition, and update changelog/spec/catalog together.
|
|
309
|
+
|
|
310
|
+
<!-- Include if: the repository is embedded in a host application. [condition-id: repo.embedded_in_host] -->
|
|
311
|
+
|
|
312
|
+
## Host integration and theming
|
|
313
|
+
|
|
314
|
+
- Registered as WebexPlugin child `cc`; the host supplies credentials, configuration, request routing, logger, internal plugins, and lifecycle. The package renders no UI or theme.
|
|
315
|
+
|
|
316
|
+
| Host or integration | Mount or entry contract | Required providers or peers | Theming and accessibility constraints |
|
|
317
|
+
| ------------------- | ----------------------- | --------------------------- | ------------------------------------- |
|
|
318
|
+
| Webex SDK (`webex` or the package `Webex.init`) | `registerPlugin('cc', ContactCenter, {config})`; collaborators are built on READY | authorization, logger, mercury, metrics, support plugins | None: no UI |
|
|
319
|
+
|
|
320
|
+
Host configuration (`config.cc`, defaults in `src/config.ts`) and remote profile gates:
|
|
321
|
+
|
|
322
|
+
| Flag/config | Gates | Current default | Owner | Safe to remove when |
|
|
323
|
+
|---|---|---|---|---|
|
|
324
|
+
| `allowAutomatedRelogin` | silent relogin after recovery | `true` (`src/config.ts`) | ContactCenter | replacement recovery contract exists |
|
|
325
|
+
| `Profile.webRtcEnabled` and `Profile.loginVoiceOptions` | browser calling path (BROWSER login option) | remote profile | Config/WCC | remote contract removed |
|
|
326
|
+
| `Profile.allowConsultToQueue` and the other Desktop Profile access flags | task consult/transfer destinations and controls | remote profile (`consultToQueue`) | Task/Config | owning behavior removed |
|
|
327
|
+
| `Profile.isWellnessBreakEnabled` | wellness event/action APIs and system-code access | false unless backend AI enablement, reminders, and positive license quantity are all present | Config/ContactCenter | wellness contract removed |
|
|
328
|
+
|
|
329
|
+
The backend-delivered `agentWellbeing.enable` value is the supported server rollout decision. The SDK combines it with `wellnessBreakReminders === 'ENABLED'` and `aiAssistantQuantity > 0`; it does not evaluate the Desktop Split flag or define a new rollout response field.
|
|
330
|
+
|
|
331
|
+
<!-- Include if: the repository exposes commands, generators, or stable file outputs. [condition-id: repo.exposes_commands_or_artifacts] -->
|
|
332
|
+
|
|
333
|
+
## Commands and generated artifacts
|
|
334
|
+
|
|
335
|
+
| Command or artifact | Owner | Inputs | Output or side effect | Compatibility boundary |
|
|
336
|
+
| ------------------- | ----- | ------ | --------------------- | ---------------------- |
|
|
337
|
+
| `yarn workspace @webex/contact-center build:src` | Package scripts | `src` | JavaScript and maps in `dist/` through `webex-legacy-tools`, then runs `build` | `dist/` is generated and ignored by Git |
|
|
338
|
+
| `yarn workspace @webex/contact-center build` | Package scripts | `src`, `tsconfig.json` | Builds `@webex/calling` sources, then declarations in `dist/types` | `types` points at them |
|
|
339
|
+
| `yarn workspace @webex/contact-center compile` | Package scripts | This package and its workspace dependencies | `build:src` for each, in topological order | Workspace order |
|
|
340
|
+
| `yarn workspace @webex/contact-center test:unit` | Package scripts | `test/unit/spec` | Jest run with the 85% coverage threshold; writes `coverage/` and `junit.xml` (ignored by Git) | Fails below 85% |
|
|
341
|
+
| `yarn workspace @webex/contact-center test:style` | Package scripts | `src/**/*.ts` | ESLint run | Markdown is not linted |
|
|
342
|
+
| `yarn workspace @webex/contact-center test:e2e` | Workspace Playwright | `../../../playwright.config.ts`, `cc_playwright` | End-to-end run against the sample app | Needs environment credentials |
|
|
343
|
+
| `yarn workspace @webex/contact-center build:docs` | Package scripts | `typedoc.json`, `src/index.ts` | API reference in the workspace `docs/wxcc` folder | Output lives outside this package |
|
|
344
|
+
| `umd/contact-center.min.js` | Workspace webpack | `src/webex.js` | Browser bundle for the sample | Regenerated, not hand-edited |
|
|
345
|
+
|
|
346
|
+
<!-- Include if: cross-repository dependencies materially affect behavior or delivery. [condition-id: repo.cross_repo_deps_material] -->
|
|
347
|
+
|
|
348
|
+
## Cross-repository topology
|
|
349
|
+
|
|
350
|
+
- **External services:** WCC REST/WebSocket/RTD and Webex metrics backends.
|
|
351
|
+
|
|
352
|
+
| Category | In use | Notes |
|
|
353
|
+
|---|---|---|
|
|
354
|
+
| Datastores | Remote WCC-owned stores | Package owns no durable store. |
|
|
355
|
+
| Messaging / streaming | WebSocket notification and RTD streams | Used for realtime events and AQM completion. |
|
|
356
|
+
| Cloud / platform services | Webex service catalog, WCC APIs, Calling/WebRTC, metrics | Host SDK supplies credentials/routing. |
|
|
357
|
+
|
|
358
|
+
| Dependency | Used for | Timeout / retry | Circuit breaker / fallback |
|
|
359
|
+
|---|---|---|---|
|
|
360
|
+
| WCC API gateway | agent/task/config/data operations | operation/AQM timeouts | propagate structured failure |
|
|
361
|
+
| WCC WebSocket/RTD | realtime events and completion | reconnect and recovery timers | reconnect/silent relogin/restore failure |
|
|
362
|
+
| Webex Calling | BROWSER call lifecycle | async registration/call timeouts | emit/rethrow calling failure |
|
|
363
|
+
| Webex metrics | telemetry | nonblocking queued submission | log/drop without breaking product flow |
|
|
364
|
+
|
|
365
|
+
<!-- Include if: trust boundaries or identity flows warrant a dedicated architectural view. [condition-id: repo.security_arch_warranted] -->
|
|
366
|
+
|
|
367
|
+
## Security architecture
|
|
368
|
+
|
|
369
|
+
The host Webex SDK establishes identity and injects authenticated service routing. Trust boundaries occur at exported SDK input, REST request construction, WebSocket parsing/event mapping, log upload, and metrics submission. Transport security is provided by host-resolved HTTPS/WSS services; durable encryption is remote-service owned.
|
|
370
|
+
|
|
371
|
+
```mermaid
|
|
372
|
+
flowchart LR
|
|
373
|
+
App[host application] -->|access token at init| Host[Webex SDK host]
|
|
374
|
+
App -->|SDK inputs| CC[webex.cc]
|
|
375
|
+
CC -->|webex.request wcc-api-gateway| REST[WCC API gateway over HTTPS]
|
|
376
|
+
CC -->|subscribe, then WSS URL| WS[WCC notification WebSocket]
|
|
377
|
+
Host -->|credentials and service catalog| REST
|
|
378
|
+
WS -->|JSON notifications| CC
|
|
379
|
+
CC -->|uploadLogs| Support[Webex support log upload]
|
|
380
|
+
CC -->|metrics| Metrics[Webex metrics]
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
| Boundary | Untrusted side | Trusted side | What is enforced at the crossing |
|
|
384
|
+
|---|---|---|---|
|
|
385
|
+
| Exported SDK methods | Host application input | ContactCenter/module methods | Typed inputs, runtime validation where implemented, typed errors |
|
|
386
|
+
| REST construction | SDK data | Webex request/service routing | Host credentials, service identifier, method/path/payload mapping |
|
|
387
|
+
| WebSocket parsing | Remote messages | ContactCenter/Task/AqmReqs | JSON parsing, event-type mapping, correlation/guards |
|
|
388
|
+
| Logs/metrics | Runtime data | Remote observability systems | Context selection and no credential/sensitive-data logging |
|
|
389
|
+
|
|
390
|
+
- **Authentication and secrets:** supplied and maintained by the host Webex SDK (`src/services/core/WebexRequest.ts`); secrets come from the host Webex SDK/runtime configuration, never source code, and rotation is owned by the host credential system and remote services, so the package has no standalone credentials or local authorization store.
|
|
391
|
+
- **Authorization:** remote WCC services enforce tenant/agent permissions; this package must not bypass host service routing.
|
|
392
|
+
- **Hard rule:** never commit or log secrets, tokens, keys, or connection strings.
|
|
393
|
+
- Validate public inputs before request construction; use typed constants and endpoint builders; never concatenate credentials or executable commands.
|
|
394
|
+
- Authenticated requests use the Webex SDK service catalog and HTTPS. Realtime traffic uses host-resolved WSS; header/environment behavior is owned by `src/services/core/WebexRequest.ts` and the host request layer.
|
|
395
|
+
- WebSocketManager connects only to a `wss:` URL whose host is in `ALLOWED_ROUTING_NOTIFS_DOMAINS` (`cisco.com`, `ciscoccservice.com`) and rejects any other subscribe response (`src/services/core/websocket/WebSocketManager.ts`).
|
|
396
|
+
|
|
397
|
+
| Data class | Examples | Storage rule | Logging rule | In transit |
|
|
398
|
+
|---|---|---|---|---|
|
|
399
|
+
| Identity/PII | agent id/name/email, dial number | ephemeral client memory; remote system of record | do not log raw sensitive values | host-resolved HTTPS/WSS |
|
|
400
|
+
| Interaction data | task/customer/call metadata | ephemeral task state; remote system of record | use tracking/interaction ids, minimize payloads | HTTPS/WSS/WebRTC |
|
|
401
|
+
| Credentials | access tokens/service auth | host-owned only | never log | HTTPS/WSS |
|
|
402
|
+
|
|
403
|
+
| Area | Risk | Mitigation / why accepted | Owner |
|
|
404
|
+
|---|---|---|---|
|
|
405
|
+
| Log upload | Runtime context could contain sensitive values | Shared error helpers upload only approved diagnostic context; never add credentials/payload dumps | Contact Center maintainers |
|
|
406
|
+
| WebSocket event parsing | Malformed/unexpected remote data | Parse defensively, map known event constants, ignore/reject invalid transitions | Core/Task maintainers |
|
|
407
|
+
| Public dial/contact/participant-drop inputs | PII, external numbers, and participant identifiers | Validate and avoid logging raw values; sensitive AQM operations redact dynamic URLs and raw routing failures | Contact Center maintainers |
|
|
408
|
+
|
|
409
|
+
- Security-sensitive changes require package-owner review and independent SDD validation. Report vulnerabilities through the repository's documented Cisco security/support process.
|
|
410
|
+
|
|
411
|
+
## Domain language
|
|
412
|
+
|
|
413
|
+
| Term | Definition (one or two sentences) | Authoritative location (file/type) | Notes / synonyms to avoid |
|
|
414
|
+
|---|---|---|---|
|
|
415
|
+
| ContactCenter | Host-embedded Webex plugin exposing the package API. | `src/cc.ts` | Registered as `cc`. |
|
|
416
|
+
| Agent Profile | Aggregated remote configuration used during an agent session. | `src/services/config/types.ts` | Do not call it durable local state. |
|
|
417
|
+
| Task | Client representation of a contact-center interaction and its operations. | `src/services/task/Task.ts` | Backed by remote interaction data. |
|
|
418
|
+
| AQM request | HTTP initiation whose success/failure may be delivered by correlated WebSocket notification. | `src/services/core/aqm-reqs.ts` | Not request-over-WebSocket. |
|
|
419
|
+
| TaskEvent | Typed internal state-machine event mapped from API calls or backend events. | `src/services/task/state-machine/constants.ts` | Distinct from raw CC_EVENTS. |
|
|
420
|
+
| PageCache | Five-minute in-memory cache for simple paginated data-service requests. | `src/utils/PageCache.ts` | Parameterized searches bypass it. |
|
|
421
|
+
|
|
422
|
+
Further terms used across modules:
|
|
423
|
+
|
|
424
|
+
| Term | Repository-specific meaning | Authoritative source |
|
|
425
|
+
| ---- | --------------------------- | -------------------- |
|
|
426
|
+
| Station login | Agent sign-in to a Contact Center station with a `LoginOption` of `BROWSER`, `EXTENSION`, or `AGENT_DN` | `src/types.ts` |
|
|
427
|
+
| Silent relogin | ContactCenter's private recovery that calls the agent `reload` request after the WebSocket reconnects, when `allowAutomatedRelogin` is true | `src/cc.ts` |
|
|
428
|
+
| Better Together (wxApp) | Answering and controlling Contact Center calls in the Webex app, enabled by the `enableWxBetterTogether` init flag | `src/config.ts` |
|
|
429
|
+
| Auxiliary code | An idle (`IDLE_CODE`) or wrap-up (`WRAP_UP_CODE`) reason from the organization configuration | `src/services/config/types.ts` |
|
|
430
|
+
| Entry point dial number (EPDN) | The backend destination type `entrypointDialNumber` that a public `entryPoint` transfer is translated to | `src/services/task/constants.ts` |
|
|
431
|
+
|
|
432
|
+
| Abbreviation | Expansion | Meaning in this repo |
|
|
433
|
+
|---|---|---|
|
|
434
|
+
| WCC | Webex Contact Center | Remote Contact Center service family. |
|
|
435
|
+
| AQM | Agent Queue Manager | Backend operation/correlation pattern. |
|
|
436
|
+
| RTD | Realtime data/transcription | Secondary realtime WebSocket stream. |
|
|
437
|
+
| RONA | Ring On No Answer (task types also say Redirection on No Answer) | Offered-task failure state/event. |
|
|
438
|
+
| ANI | Automatic Number Identification | Outbound caller-id selection data. |
|
|
439
|
+
|
|
440
|
+
| Term | Context / module | Meaning here |
|
|
441
|
+
|---|---|---|
|
|
442
|
+
| Event | Config/Core | Raw backend WebSocket event. |
|
|
443
|
+
| Event | Task state machine | Typed TaskEvent after mapping. |
|
|
444
|
+
| State | Agent | Backend agent availability/substatus. |
|
|
445
|
+
| State | Task | XState task lifecycle state. |
|
|
446
|
+
|
|
447
|
+
## References and maintenance
|
|
448
|
+
|
|
449
|
+
| Reference | Location | When to read |
|
|
450
|
+
|---|---|---|
|
|
451
|
+
| Architecture decisions | [adr/index.md](adr/index.md) | Durable design choices and supersession |
|
|
452
|
+
| Repo patterns | [package agent instructions](../AGENTS.md) | Existing TypeScript, event, and testing conventions |
|
|
453
|
+
| Enforceable rules | [package agent instructions](../AGENTS.md) | Constraints for every change |
|
|
454
|
+
|
|
455
|
+
- Instantiated specifications and routing: [specs/README.md](specs/README.md)
|
|
456
|
+
- Update this catalog, the owning module spec, TypeScript declarations, and manifest in the same change as a contract.
|
|
457
|
+
- Add new entities, events, states, or renamed concepts here in the same change.
|
|
458
|
+
- Update the relevant row in the same change as any surface, dependency, timeout, metric, or flag.
|
|
459
|
+
- Update this document in the same change that alters package boundaries, resource ownership,
|
|
460
|
+
cross-resource interaction, or cross-cutting architecture.
|