@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.
Files changed (84) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1065 -339
  3. package/AGENTS.md +935 -60
  4. package/dist/webex.js +1 -1
  5. package/docs/adr/0001-spec-source-policy.md +97 -0
  6. package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
  7. package/docs/adr/0003-repo-standards-migration.md +104 -0
  8. package/docs/adr/index.md +35 -0
  9. package/docs/architecture.md +460 -0
  10. package/docs/getting-started.md +142 -0
  11. package/docs/index.md +53 -0
  12. package/docs/specs/README.md +98 -0
  13. package/package.json +10 -9
  14. package/schemas/repo-context.schema.json +796 -0
  15. package/src/docs/README.md +727 -0
  16. package/src/metrics/docs/README.md +710 -0
  17. package/src/services/agent/docs/README.md +673 -0
  18. package/src/services/config/docs/README.md +530 -0
  19. package/src/services/core/docs/README.md +993 -0
  20. package/src/services/docs/README.md +765 -0
  21. package/src/services/task/docs/README.md +1569 -0
  22. package/src/services/task/state-machine/docs/README.md +1388 -0
  23. package/src/utils/AGENTS.md +6 -4
  24. package/src/utils/docs/README.md +413 -0
  25. package/umd/contact-center.min.js +2 -2
  26. package/umd/contact-center.min.js.map +1 -1
  27. package/ai-docs/ARCHITECTURE.md +0 -168
  28. package/ai-docs/CONTRACTS.md +0 -64
  29. package/ai-docs/GETTING_STARTED.md +0 -168
  30. package/ai-docs/GLOSSARY.md +0 -43
  31. package/ai-docs/README.md +0 -138
  32. package/ai-docs/REVIEW_CHECKLIST.md +0 -41
  33. package/ai-docs/RULES.md +0 -444
  34. package/ai-docs/SECURITY.md +0 -52
  35. package/ai-docs/SERVICE_STATE.md +0 -52
  36. package/ai-docs/SPEC_INDEX.md +0 -65
  37. package/ai-docs/adr/0001-spec-source-policy.md +0 -55
  38. package/ai-docs/adr/README.md +0 -8
  39. package/ai-docs/adr/_adr-template.md +0 -31
  40. package/ai-docs/contact-center-spec.md +0 -388
  41. package/ai-docs/features/contact-owner-change-refactor.md +0 -78
  42. package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
  43. package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
  44. package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
  45. package/ai-docs/patterns/event-driven-patterns.md +0 -485
  46. package/ai-docs/patterns/testing-patterns.md +0 -480
  47. package/ai-docs/patterns/typescript-patterns.md +0 -365
  48. package/ai-docs/templates/README.md +0 -102
  49. package/ai-docs/templates/documentation/create-agents-md.md +0 -240
  50. package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
  51. package/ai-docs/templates/existing-service/bug-fix.md +0 -254
  52. package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
  53. package/ai-docs/templates/new-method/00-master.md +0 -80
  54. package/ai-docs/templates/new-method/01-requirements.md +0 -232
  55. package/ai-docs/templates/new-method/02-implementation.md +0 -295
  56. package/ai-docs/templates/new-method/03-tests.md +0 -201
  57. package/ai-docs/templates/new-method/04-validation.md +0 -141
  58. package/ai-docs/templates/new-service/00-master.md +0 -109
  59. package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
  60. package/ai-docs/templates/new-service/02-code-generation.md +0 -346
  61. package/ai-docs/templates/new-service/03-integration.md +0 -178
  62. package/ai-docs/templates/new-service/04-test-generation.md +0 -205
  63. package/ai-docs/templates/new-service/05-validation.md +0 -145
  64. package/src/metrics/ai-docs/AGENTS.md +0 -350
  65. package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
  66. package/src/metrics/ai-docs/metrics-spec.md +0 -971
  67. package/src/services/agent/ai-docs/AGENTS.md +0 -240
  68. package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
  69. package/src/services/agent/ai-docs/agent-spec.md +0 -505
  70. package/src/services/ai-docs/AGENTS.md +0 -386
  71. package/src/services/ai-docs/services-spec.md +0 -512
  72. package/src/services/config/ai-docs/AGENTS.md +0 -250
  73. package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
  74. package/src/services/config/ai-docs/config-spec.md +0 -669
  75. package/src/services/core/ai-docs/AGENTS.md +0 -381
  76. package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
  77. package/src/services/core/ai-docs/core-spec.md +0 -797
  78. package/src/services/task/ai-docs/AGENTS.md +0 -457
  79. package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
  80. package/src/services/task/ai-docs/task-spec.md +0 -1501
  81. package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
  82. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
  83. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
  84. package/src/utils/ai-docs/utils-spec.md +0 -391
@@ -0,0 +1,530 @@
1
+ ---
2
+ type: Module Spec
3
+ title: 'Config service specification'
4
+ description: Responsibilities, boundaries, design, invariants, and verification for the Contact Center config service (AgentConfigService, the AgentProfile aggregation, and the CC event-name constants).
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
+ # Config service
17
+
18
+ This source-local document at `src/services/config/docs/README.md` owns the stable specification for
19
+ **the config service**: `AgentConfigService`, which fetches and aggregates agent configuration data
20
+ from multiple API endpoints to build the AgentProfile, the `parseAgentConfigs` mapper, the
21
+ `endPointMap` resource builders, and the configuration and event types in `types.ts`, including the
22
+ `CC_EVENTS` event-name constants. This is the authoritative documentation for the Config service
23
+ scope. See the [package agent instructions](../../../../AGENTS.md) for the orchestrator and
24
+ cross-scope rules. 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 library. The parent module is the
27
+ [services specification](../../docs/README.md).
28
+
29
+ Related context: [documentation index](../../../../docs/index.md) ·
30
+ [package agent instructions](../../../../AGENTS.md)
31
+
32
+ ## Metadata
33
+
34
+ | Field | Value |
35
+ | ----- | ----- |
36
+ | Owner | @webex/web-sdk |
37
+ | Source path | `src/services/config` |
38
+ | Resource kind | module |
39
+ | Status | Active |
40
+ | Last verified | 2026-11-16 at `0b8c34db7f` |
41
+ | Module id | `config` |
42
+ | Parent spec | [src/services](../../docs/README.md) |
43
+ | Doc kind | Module spec |
44
+ | Coverage score | Pending coverage assessment |
45
+ | Validation status | pass-with-warnings — assessed 2026-11-17; validator runtime 01a1e76f-2293-79a0-9f8f-f060038448dd; 0 Blocking, 0 Important, 4 Minor findings. |
46
+
47
+ ## Applicability
48
+
49
+ | Condition ID | Status | Evidence or reason | Owned section |
50
+ | ------------ | ------ | ------------------ | ------------- |
51
+ | `module.has_tiers` | N/A | No tier policy exists in `package.json` or under src | Tier |
52
+ | `module.has_ui` | N/A | `src/services/config/index.ts` only returns promises; nothing renders | UI use-case flow |
53
+ | `module.crosses_service_boundaries` | Applicable | `src/services/config/index.ts` calls the Contact Center API gateway through `src/services/core/WebexRequest.ts` | Cross-boundary use-case flow |
54
+ | `module.holds_client_state` | N/A | `src/services/config/index.ts` keeps only the WebexRequest handle; the built profile is stored by `src/cc.ts` | Client state model |
55
+ | `module.enforces_domain_rules` | Applicable | All-or-nothing aggregation in `src/services/config/index.ts` and the wellness and aux-code rules in `src/services/config/Util.ts` | Business rules and invariants |
56
+ | `module.is_concurrent_async` | Applicable | `src/services/config/index.ts` starts requests in parallel and joins them with Promise.all | Concurrency and reactive flow |
57
+ | `module.owns_persistence` | N/A | Nothing in `src/services/config/index.ts` writes storage | Data, schema, and migration discipline |
58
+ | `module.stateful_transitions` | N/A | `src/services/config/index.ts` has no state machine | State machine |
59
+ | `module.exposes_wire_protocol` | Applicable | REST resource shapes in `src/services/config/constants.ts`; WebSocket event names in `src/services/config/types.ts` | Protocol and wire format |
60
+ | `module.ui_multi_screen` | N/A | No UI | UI flow |
61
+ | `module.large_data_model` | N/A | Manifest profile false; the response and profile types in `src/services/config/types.ts` are summarized under Public surface | Data model |
62
+ | `module.returns_caller_errors` | Applicable | Every method in `src/services/config/index.ts` logs and rethrows | Caller-visible failure modes |
63
+ | `module.module_specific_conventions` | Applicable | Event-constant and logging conventions in `src/services/config/types.ts` and `src/services/config/index.ts` | Module-specific rules |
64
+ | `module.published_package` | N/A | Manifest profile false; package exports are owned by `src/index.ts` and the package spec | Export stability |
65
+ | `module.embedded_in_host` | N/A | No host theme or mount API | Host integration and theming |
66
+ | `module.has_design_tradeoff` | Applicable | All-or-nothing Promise.all aggregation in `src/services/config/index.ts` | Key design trade-off |
67
+ | `module.has_submodules` | N/A | The module tree computed by scripts/module_tree.py lists no child of src/services/config (manifest has_submodules false) | Sub-modules |
68
+
69
+ ## Evidence register
70
+
71
+ Every requirement cites stable source and test file paths. Code and tests are the behavioral referee;
72
+ missing or contradictory evidence blocks promotion.
73
+
74
+ | Evidence | What it establishes |
75
+ | -------- | ------------------- |
76
+ | `src/services/config/index.ts` | `AgentConfigService` and its twelve public methods; the staged `getAgentConfig` orchestration; the per-method log, status-check, and rethrow pattern; the operation groups that justify the `Profile aggregation`, `Pagination`, and `Wellness idle-code lookup` subsections under Data flow and sequence coverage |
77
+ | `src/services/config/Util.ts` | `parseAgentConfigs` and its helpers `getFilterAuxCodes`, `getFilteredDialplanEntries`, `getDefaultWrapUpCode`, `getMsftConfig`, `getWebexConfig`, `getDefaultAgentDN`; the wellness gate |
78
+ | `src/services/config/constants.ts` | `endPointMap`, `DEFAULT_PAGE` (0), `DEFAULT_PAGE_SIZE` (100), `DEFAULT_AUXCODE_ATTRIBUTES`, `WELLBEING_BREAK_IDLE_CODE`, `WELLNESS_BREAK_REMINDERS_ENABLED`, `COLLABORATION_ACCESS`, `METHODS` |
79
+ | `src/services/config/types.ts` | `CC_TASK_EVENTS` (66 keys), `CC_AGENT_EVENTS` (19 keys), `CC_EVENTS`, `VOICE_CONNECTION_EVENTS`, `Profile`, and the response types (catalog source of `contact-center-cc-events`) |
80
+ | `src/services/index.ts` | `Services` constructs one `AgentConfigService` as `services.config` |
81
+ | `src/cc.ts` | Consumers: `connectWebsocket` stores `getAgentConfig` as `this.agentConfig`; `getWellbeingBreakIdleCode` and `getOutdialAniEntries` wrap the service; `CC_EVENT_ALLOW_LIST` filters re-emitted WebSocket event names |
82
+ | `src/index.ts`, `src/webex.js` | Public re-export of `CC_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `VOICE_CONNECTION_EVENTS`, `IDLE_CODE`, `WRAP_UP_CODE`, and the config types; `Webex.CC_AGENT_EVENTS` |
83
+ | `src/services/core/WebexRequest.ts` | The singleton HTTP wrapper over `webex.request` used by every method |
84
+ | `src/services/core/websocket/WebSocketManager.ts` | Resolves registration on the `CC_EVENTS.WELCOME` message |
85
+ | `src/services/WebCallingService.ts` | Emits `VOICE_CONNECTION_EVENTS.STATE_CHANGE` |
86
+ | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `src/services/UserPreference.ts` | Other consumers of `endPointMap` |
87
+ | `src/services/ApiAiAssistant.ts` | Consumes `AIFeatureFlags` through `setAIFeatureFlags` |
88
+ | `src/constants.ts` | `CONFIG_FILE_NAME` is `config-index`, the log `module` of every config method |
89
+ | `test/unit/spec/services/config/index.ts` | Unit cases for every request method, pagination, the wellness lookup, `getAgentConfig` staging and rejection, and `getOutdialAniEntries` |
90
+ | `test/unit/spec/services/config/Util.ts` | Unit cases for `parseAgentConfigs` field mapping, aux codes, dial plan, and the wellness gate |
91
+ | `test/unit/spec/cc.ts` | WebSocket allow-list cases: an unknown `data.type` is not emitted; a known one is emitted verbatim |
92
+ | `package.json` | TypeScript 5.4.5 and Jest 27.5.1 |
93
+
94
+ ## Purpose and boundary
95
+
96
+ - Responsibility: Config is one of nine confirmed Contact Center SDK modules. Own retrieval and
97
+ aggregation of remote organization, agent, team, profile, auxiliary-code, dial-plan, and feature
98
+ configuration, and own the event-name constants of the `contact-center-cc-events` contract.
99
+ - In scope: `AgentConfigService` request methods and pagination, `parseAgentConfigs`, the
100
+ `endPointMap` resource builders, the system wellness idle-code lookup, the outdial ANI lookup, and the
101
+ types and event constants in `src/services/config/types.ts`.
102
+ - Out of scope: when the profile is fetched and how it is stored or used (`src/cc.ts`, see the
103
+ [package specification](../../../docs/README.md)); emitting events (ContactCenter, the
104
+ [agent service](../../agent/docs/README.md), and the [task service](../../task/docs/README.md));
105
+ HTTP transport (the [core service](../../core/docs/README.md)); queue, entry-point, address-book,
106
+ and user-preference requests that only borrow `endPointMap`.
107
+ - Consumers: `ContactCenter` in `src/cc.ts` through `services.config`; every module that imports the
108
+ event constants or types; applications through the re-exports in `src/index.ts`.
109
+
110
+ ## Structure and key files
111
+
112
+ | Path | Responsibility |
113
+ | ---- | -------------- |
114
+ | `src/services/config/index.ts` | `AgentConfigService`: service implementation with all API methods |
115
+ | `src/services/config/types.ts` | Complete type definitions and event constants (`Profile`, response types, `CC_EVENTS`) |
116
+ | `src/services/config/Util.ts` | AgentProfile parsing utilities (`parseAgentConfigs`, `getFilterAuxCodes`, etc.) |
117
+ | `src/services/config/constants.ts` | API endpoints (`endPointMap`), default values, and method names |
118
+ | `src/services/config/docs/README.md` | This module specification |
119
+ | `test/unit/spec/services/config/index.ts` | Unit cases for `AgentConfigService` |
120
+ | `test/unit/spec/services/config/Util.ts` | Unit cases for `parseAgentConfigs` |
121
+
122
+ ## Public surface
123
+
124
+ | Surface | Consumer | Compatibility commitment | Source |
125
+ | ------- | -------- | ------------------------ | ------ |
126
+ | `contact-center-cc-events`: `CC_EVENTS`, `CC_AGENT_EVENTS`, `CC_TASK_EVENTS`, `VOICE_CONNECTION_EVENTS`, and the `CC_EVENTS` value union type (exported as `ContactCenterEvents`) | Applications (re-exported by `src/index.ts`; `Webex.CC_AGENT_EVENTS` in `src/webex.js`), ContactCenter, agent, task, and core modules | Values equal the backend WebSocket `type` strings and are public event names; renaming or removing a value is a breaking change | `src/services/config/types.ts` |
127
+ | `contact-center-sdk` (owned by the package spec): `Profile` and the configuration response types (`OrgDesktopLoginResponse`, `UserDesktopLoginResponse`, `TeamList`, `AuxCode`, `Entity`, `DialPlan`, and the others listed below). Field rules: `aiFeature` CONFIG-R-002, `maskSensitiveData` and `MultimediaProfileResponse` CONFIG-R-004, `isWellnessBreakEnabled` CONFIG-R-006 | Applications through `src/index.ts` | Exported TypeScript types; renaming or removing a field breaks consumers | `src/services/config/types.ts`, `src/index.ts` |
128
+ | `contact-center-services` (owned by the services spec): `AgentConfigService` methods `getAgentConfig(orgId, agentId)` (CONFIG-R-001, CONFIG-R-005), `getOrgDesktopLoginConfig(orgId)`, `getUserDesktopLoginConfig(orgId, ciUserId)`, `getSiteInfo(orgId, siteId)`, `getDialPlanData(orgId)`, `getMultimediaProfileById(orgId, multimediaProfileId)`, `getListOfTeams`, `getAllTeams`, `getListOfAuxCodes`, `getAllAuxCodes` (CONFIG-R-003), `getOutdialAniEntries(orgId, params)` (CONFIG-R-010), and `getWellbeingBreakIdleCode(orgId)` (CONFIG-R-007) | `src/cc.ts` through `services.config`; `getOutdialAniEntries` and `getWellbeingBreakIdleCode` reach applications through ContactCenter wrappers, and ContactCenter caches the wellness code per registration | Internal; marked `@private`/`@ignore`; not exported by `src/index.ts` | `src/services/config/index.ts`, `src/services/index.ts`, `src/cc.ts` |
129
+ | `endPointMap` | This service, plus [`Queue.ts`](../../Queue.ts) (`queueList`), [`EntryPoint.ts`](../../EntryPoint.ts) (`entryPointDialNumberList`), [`AddressBook.ts`](../../AddressBook.ts) (`addressBookEntries`), and [`UserPreference.ts`](../../UserPreference.ts) (`userPreference`, `userPreferenceCreate`), which are not called by `AgentConfigService` | Internal resource builders for contract `wxcc-api-gateway`; route shapes in Protocol and wire format | `src/services/config/constants.ts` |
130
+
131
+ Exact package exports are indexed in the [package architecture](../../../../docs/architecture.md).
132
+
133
+ Compatibility: the desktop-login aggregate change is breaking for consumers of these types and needs a major version of the published package (`package.json`; semver rule in the [package architecture](../../../../docs/architecture.md)). The types `DesktopProfileResponse` (replaced by `AgentProfile`), `URLMapping`, and `AIFeatureFlagsResponse` and the field `Profile.environment` no longer exist in src (`test/unit/spec/services/config/Util.ts` asserts that `parseAgentConfigs` emits no `environment`); `TenantData.callVariablesSuppressed` is now `boolean`, and `parseAgentConfigs` copies it onto the returned profile; `getListOfTeams(orgId, page, pageSize, userDbId)` now filters teams by the user's database id (`filter=userId=={userDbId}`) instead of a list of team ids; auxiliary codes come from the unrestricted organization pool (CONFIG-R-011); and `webexConfig.stateSynchronizationWebex` is now read from the organization-level `webexConfig.stateSynchronization` (`src/services/config/Util.ts`), so it can change from `false` to `true`.
134
+
135
+ These methods exist in `AgentConfigService` but are **not** part of the `getAgentConfig()` aggregation flow. They can be used independently of profile building; applications reach them only through ContactCenter wrappers, because `services` is a private field of ContactCenter in `src/cc.ts`.
136
+
137
+ | Method | Status | Returns | Description |
138
+ | ------ | ------ | ------- | ----------- |
139
+ | `getOutdialAniEntries(orgId, params)` | **Publicly exposed** via `cc.getOutdialAniEntries()` | `OutdialAniEntriesResponse` | Fetch outbound ANI entries for caller ID selection. Supports pagination and search via [`OutdialAniParams`](../types.ts). |
140
+ | `getMultimediaProfileById(orgId, multimediaProfileId)` | **Not exposed, never called** | `MultimediaProfileResponse` | Fetch channel capacities (chat, email, telephony, social) and blending config. Available but unused anywhere. |
141
+ | `getListOfTeams(orgId, page, pageSize, userDbId)` | Used internally by `getAllTeams()` | `ListTeamsResponse` | Single-page team fetch with pagination metadata, filtered by `userDbId`. |
142
+ | `getListOfAuxCodes(orgId, page, pageSize, filter, attributes)` | Used internally by `getAllAuxCodes()` | `ListAuxCodesResponse` | Single-page aux code fetch with pagination metadata. Useful for custom pagination. |
143
+
144
+ The AgentProfile is defined as the [`Profile`](../types.ts) type. This is not an exhaustive list — see [`types.ts`](../types.ts) for the full 50+ field definition. Key fields:
145
+
146
+ | Field | Type | Description |
147
+ | ----- | ---- | ----------- |
148
+ | `agentId` | string | Unique agent identifier |
149
+ | `agentName` | string | Display name |
150
+ | `agentMailId` | string | Email address |
151
+ | `teams` | [`TeamList[]`](../types.ts) | Assigned teams (runtime data from `getAllTeams()`; `Profile` declares `TeamList[]`) |
152
+ | `defaultDn` | string | Default dial number |
153
+ | `idleCodes` | [`Entity[]`](../types.ts) | Available idle codes |
154
+ | `wrapupCodes` | [`Entity[]`](../types.ts) | Available wrapup codes |
155
+ | `webRtcEnabled` | boolean | WebRTC calling enabled |
156
+ | `loginVoiceOptions` | [`LoginOption[]`](../types.ts) | Available login types |
157
+ | `dialPlan` | [`DialPlan`](../types.ts) | Number transformation rules |
158
+ | `isOutboundEnabledForAgent` | boolean | Outbound calling allowed |
159
+ | `outDialEp` | string | Outbound entry point ID |
160
+ | `allowConsultToQueue` | boolean | Whether consult-to-queue is enabled on the Desktop Profile |
161
+ | `accessQueue` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab queue access scope from Desktop Profile |
162
+ | `accessEntryPoint` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab entry-point access scope from Desktop Profile |
163
+ | `accessBuddyTeam` | `'ALL' \| 'SPECIFIC' \| 'NONE'` | Collaboration tab buddy-team access scope from Desktop Profile |
164
+ | `isWellnessBreakEnabled` | boolean | Effective wellness gate derived from backend enablement/reminder configuration and positive AI Assistant license quantity |
165
+
166
+ `parseAgentConfigs()` maps the three `access*` fields from the user aggregate's `AgentProfile` section onto the public `Profile` returned by `cc.register()`.
167
+
168
+ Types used by the config service, all defined in [`types.ts`](../types.ts):
169
+
170
+ | Type | Description |
171
+ | ---- | ----------- |
172
+ | `Profile` | Final aggregated agent config returned by `getAgentConfig()` |
173
+ | `OrgDesktopLoginResponse` | Response from `getOrgDesktopLoginConfig()`; sections in Protocol and wire format |
174
+ | `UserDesktopLoginResponse` | Response from `getUserDesktopLoginConfig()` — `user` and `agentProfile` sections (fields in Protocol and wire format) |
175
+ | `AgentResponse` | `user` section of the user aggregate — agent metadata, `dbId`, `siteId`, `agentProfileId` |
176
+ | `AgentProfile` | `agentProfile` section of the user aggregate — layout, dial-plan enablement, login options |
177
+ | `TeamList` | Team record from API — `id`, `name`, `teamType`, `siteId`, `multiMediaProfileId` |
178
+ | `ListTeamsResponse` | Paginated wrapper around `TeamList[]` with `meta` for pagination |
179
+ | `OrgInfo` | Organization info — `tenantId`, timezone |
180
+ | `OrgSettings` | Org feature flags — `webRtcEnabled`, `maskSensitiveData` |
181
+ | `TenantData` | Tenant-level config — inactivity timeout, `forceDefaultDn`, `outdialEnabled` |
182
+ | `SiteInfo` | Site config — `id`, `name`, `multimediaProfileId` |
183
+ | `OrgUrlMappings` | Keyed external URL mappings — `ACQUEON_API_URL`, `ACQUEON_CONSOLE_URL` |
184
+ | `MicrosoftConfig` | Org-level Microsoft presence config — `showUserDetails`, `stateSynchronization` |
185
+ | `WebexConfig` | Org-level Webex presence config — `showUserDetails`, `stateSynchronization` |
186
+ | `MultimediaProfileResponse` | Multimedia profile — channel capacities and settings |
187
+ | `AuxCode` | Auxiliary code record — `id`, `name`, `description`, `workTypeCode` |
188
+ | `ListAuxCodesResponse` | Paginated wrapper around `AuxCode[]` with `meta` |
189
+ | `DialPlanEntity` | Dial plan rule — regex pattern, prefix, strip digits, `active` |
190
+ | `Entity` | Basic entity info — `isSystem`, `name`, `id`, `isDefault` |
191
+ | `WrapupData` | Wrap-up config — auto-wrapup settings, available wrapup codes |
192
+ | `OutdialAniParams` | Parameters for `getOutdialAniEntries()` — ANI ID, pagination, filtering |
193
+ | `LoginOption` | Login types (BROWSER, EXTENSION, AGENT_DN) |
194
+ | `Team` | Team configuration; declared in `src/types.ts`, not in this module, and not used by `Profile.teams` |
195
+
196
+ ## Dependencies
197
+
198
+ | Dependency | Why it is required | Failure behavior |
199
+ | ---------- | ------------------ | ---------------- |
200
+ | WebexRequest (`src/services/core/WebexRequest.ts`, [core service](../../core/docs/README.md)) | Singleton taken in the constructor; every method calls `request({service: WCC_API_GATEWAY, resource, method: GET})` | A rejection is logged and rethrown by the calling method |
201
+ | WCC organization/profile/team/site/tenant APIs (contract `wxcc-api-gateway`, service name `wcc-api-gateway`) | Desktop-login aggregates, teams, auxiliary codes, site, dial plan, multimedia profile, and outdial ANI resources | Non-200 responses become `Error('API call failed with {statusCode}')`, except in `getOutdialAniEntries` |
202
+ | ContactCenter registration flow (`src/cc.ts`) | Supplies `orgId` from credentials and `agentId` from the Welcome event, and stores the resolved profile | A `getAgentConfig` rejection propagates into registration |
203
+ | Backend notification names (contract `wxcc-websocket-notifications`) | `CC_AGENT_EVENTS` and `CC_TASK_EVENTS` mirror the WebSocket message `type` strings | A backend type missing from the constants is not re-emitted by `src/cc.ts` |
204
+ | `LoggerProxy` (`src/logger-proxy.ts`) | Info, log, and error lines with `module: CONFIG_FILE_NAME` | None |
205
+ | `LOST_CONNECTION_RECOVERY_TIMEOUT` (`src/services/core/constants.ts`) | Default for `Profile.lostConnectionRecoveryTimeout` when the tenant value is falsy | None |
206
+
207
+ ## Requirements
208
+
209
+ | ID | WHAT | WHY | Source Evidence | Test / Example Evidence | Assumptions / Gaps | Confidence |
210
+ | --- | ---- | --- | --------------- | ----------------------- | ------------------ | ---------- |
211
+ | CONFIG-R-001 | Start the user desktop-login, organization desktop-login, and auxiliary-code requests together; after the user aggregate resolves, start site, teams, and the conditional dial plan; join all five with `Promise.all`. | Dependent IDs and all-or-nothing consistency require staged orchestration. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None. | PRESENT |
212
+ | CONFIG-R-002 | Include the organization aggregate's `aiFeature` section in `parseAgentConfigs` so `Profile.aiFeature` reflects the organization feature contract. | ApiAIAssistant behavior is gated by the remote organization feature contract. | `src/services/config/index.ts`, `src/services/config/Util.ts` | `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` | `src/cc.ts` passes `Profile.aiFeature` to `setAIFeatureFlags` and into the task config flags. | PRESENT |
213
+ | CONFIG-R-003 | Paginate teams and auxiliary codes until completion and include `desktopProfileFilter=true` for auxiliary-code requests. | A partial or unfiltered set yields invalid profile/team/auxiliary choices. | `src/services/config/constants.ts`, `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None. | PRESENT |
214
+ | CONFIG-R-004 | Expose current response/field names: `MultimediaProfileResponse`, `OrgSettings.maskSensitiveData`, and real TeamList fields only. | Type-name drift causes invalid consumer code and incorrect privacy behavior. | `src/services/config/types.ts` | `test/unit/spec/services/config/index.ts`, `test/unit/spec/services/config/Util.ts` | `maskSensitiveData` defaults to false when the organization value is falsy. | PRESENT |
215
+ | CONFIG-R-005 | Reject the entire profile aggregation when any required dependent request fails. | Consumers must never receive an internally inconsistent partial Profile. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | Rejection is asserted for five of the six requests; a `getDialPlanData` rejection inside `getAgentConfig` is not asserted. | PRESENT |
216
+ | CONFIG-R-006 | Always populate `Profile.isWellnessBreakEnabled`; set it true only when `agentWellbeing.enable` is true, `wellnessBreakReminders` is `ENABLED`, and `OrgSettings.aiAssistantQuantity` is greater than zero. Missing or null inputs fail closed. | Hosts need one license-and-server-rollout-aware signal rather than reconstructing partial configuration. | `src/services/config/Util.ts`, `src/services/config/types.ts` | `test/unit/spec/services/config/Util.ts` | The supported SDK contracts expose no separate rollout response field; backend delivery of enabled `agentWellbeing` configuration is the rollout decision. `Profile` declares the field optional. | PRESENT |
217
+ | CONFIG-R-007 | Retrieve the wellness idle code from `/v2/auxiliary-code` using `workType=IDLE_CODE`, `customFilter=isSystemCode==true`, and `desktopProfileFilter=false`; follow pagination and accept only the exact active system code name `WellbeingBreak`. | The dedicated state must be independent of desktop-profile filtering and must never fall back to a similarly named or non-system code. | `src/services/config/index.ts`, `src/services/config/constants.ts` | `test/unit/spec/services/config/index.ts` | `src/cc.ts` caches the result per registration and rejects with `WELLNESS_BREAK_NOT_ENABLED` when the profile flag is false. | PRESENT |
218
+ | CONFIG-R-008 | `CC_EVENTS` is the spread of `CC_AGENT_EVENTS` and `CC_TASK_EVENTS`; each value is the backend WebSocket `type` string, and `src/cc.ts` re-emits a message's `data.type` only when it is one of these values. | The values are the public event names applications subscribe to, and the allow-list stops an unknown or server-injected type from being emitted (comment on `CC_EVENT_ALLOW_LIST` in `src/cc.ts`). | `src/services/config/types.ts`, `src/cc.ts`, `src/index.ts` | `test/unit/spec/cc.ts`, `test/unit/spec/index.ts` | The shared `BuddyAgents` value is listed under Pitfalls and constraints. | Present |
219
+ | CONFIG-R-009 | `getAgentConfig` resolves `multimediaProfileId` from the first team's `multiMediaProfileId`, falling back to the site's `multimediaProfileId` when there is no team or the team has none. | The multimedia profile defines channel capacities; teams override the site default. | `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` | None. | Present |
220
+ | CONFIG-R-010 | `getOutdialAniEntries(orgId, params)` adds only the provided `page`, `pageSize`, `search`, `filter`, and `attributes` query parameters, resolves `response.body?.data`, and rethrows a request rejection; it does not check `statusCode`. | `cc.getOutdialAniEntries` is the public caller-ID lookup and records the result count in metrics. | `src/services/config/index.ts`, `src/cc.ts` | `test/unit/spec/services/config/index.ts` | A resolved non-200 response yields `undefined`, not an error (asserted by the 404 and 500 cases). | Present |
221
+ | CONFIG-R-011 | `parseAgentConfigs` keeps active aux codes of each `workTypeCode` from the full pool as `Entity` values, appends the synthetic idle code `{id: '0', name: 'Available'}`, and sets `defaultWrapupCode` to the default wrap-up code id or an empty string. | The desktop-login aggregate does not carry per-agent restriction lists, so the whole pool applies (JSDoc of `getFilterAuxCodes`). | `src/services/config/Util.ts` | `test/unit/spec/services/config/Util.ts` | None. | Present |
222
+ | CONFIG-R-012 | When `dialPlanEnabled` is true, `Profile.dialPlan` is `{type: 'adhocDial', dialPlanEntity}` built from every active plan; otherwise it is `undefined` and no dial-plan request is made. | The aggregate does not carry the per-profile `dialPlans` selection, so all active plans apply (JSDoc of `getFilteredDialplanEntries`). | `src/services/config/Util.ts`, `src/services/config/index.ts` | `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` | None. | Present |
223
+
224
+ ## Design overview
225
+
226
+ The Config Service is an **internal service** that builds the comprehensive AgentProfile (`Profile` type) from six requests; their order is under Profile aggregation.
227
+
228
+ The AgentProfile is the central configuration object required for an agent to operate within the contact center. It is built during the registration flow (`cc.register()`) and contains all the data an agent needs: identity, team assignments, dial plans, aux codes, login options, and feature flags. Once constructed, the AgentProfile is stored on the `ContactCenter` plugin instance as `this.agentConfig` and is used by other services (Agent, Task) throughout the session.
229
+
230
+ ```typescript
231
+ // Config service is used internally during the registration flow.
232
+ // Inside cc.ts → connectWebsocket(), after WebSocket connection is established:
233
+ const agentId = data.agentId;
234
+ const orgId = this.$webex.credentials.getOrgId();
235
+ this.agentConfig = await this.services.config.getAgentConfig(orgId, agentId);
236
+ ```
237
+
238
+ Stack: TypeScript 5.4 REST client, Promise-based parallel aggregation, Jest 27.
239
+
240
+ Config separates its stable consumption boundary from collaborators so ownership and failure behavior stay explicit; profile creation is all-or-nothing (CONFIG-R-005).
241
+
242
+ `parseAgentConfigs` in Util.ts combines all data into a unified `Profile` object. See [types.ts](../types.ts) for full type definitions.
243
+
244
+ [`parseAgentConfigs`](../Util.ts) takes one object `{orgConfig, userData, agentProfileData, teamData, auxCodes, dialPlanData, multimediaProfileId}` typed `OrgDesktopLoginResponse`, `AgentResponse` (the `user` section), `AgentProfile` (the `agentProfile` section), `TeamList[]`, `AuxCode[]`, `DialPlanEntity[]`, and string, and returns a `Profile`. It destructures `organization` (orgInfoData), `organizationSetting` (orgSettingsData), `tenantConfiguration` (tenantData), `urlMappings`, `aiFeature`, `microsoftConfig`, and `webexConfig` from `orgConfig`. `getFilterAuxCodes(auxCodes, WRAP_UP_CODE)` and `getFilterAuxCodes(auxCodes, IDLE_CODE)` check `workTypeCode` and `active` over the full org pool (the aggregate returns no per-agent restriction) and map to `Entity` `{id, name, isSystem, isDefault}`; the hardcoded "Available" state (`id: '0'`) is always appended to idle codes. The returned profile sets `agentId` from `userData.ciUserId`, `analyserUserId` from `userData.id`, `agentName` from `firstName` and `lastName`, `teams` from `teamData` as-is, `webRtcEnabled` from `orgSettingsData`, `loginVoiceOptions` from `agentProfileData.loginVoiceOptions ?? []`, `enterpriseId` from `orgInfoData.tenantId`, `tenantTimezone` from `orgInfoData.timezone`, `multimediaProfileId` from the input, and `aiFeature` unchanged, plus the remaining fields: see Util.ts for the full implementation.
245
+
246
+ ## Data flow and sequence coverage
247
+
248
+ Call style: in-process promise calls on `AgentConfigService`, each of which makes authenticated HTTPS
249
+ GET requests through `WebexRequest.request` to the `wcc-api-gateway` service.
250
+
251
+ Sequence coverage:
252
+
253
+ | Operation group | Entry and outcome | Diagram or evidence | Failure and recovery coverage |
254
+ | --------------- | ----------------- | ------------------- | ----------------------------- |
255
+ | Profile aggregation and AI feature flags | `getAgentConfig(orgId, agentId)` resolves one `Profile` | Profile aggregation diagram; `src/services/config/index.ts` | Any required request rejection rejects `getAgentConfig`; no partial Profile is returned. |
256
+ | Team/aux-code pagination | `getAllTeams`, `getAllAuxCodes` resolve the concatenated list | Pagination diagram; `src/services/config/index.ts` | Continue until page metadata is exhausted; any page rejection rejects the operation. |
257
+ | Wellness system idle code | `getWellbeingBreakIdleCode(orgId)` resolves one `Entity` | Wellness idle-code lookup diagram; `src/services/config/index.ts` | Sequential pages stop at the first match; no match rejects with `WELLBEING_BREAK_IDLE_CODE_NOT_FOUND`; a non-200 page rejects. |
258
+ | Single-resource fetches | `getOrgDesktopLoginConfig`, `getUserDesktopLoginConfig`, `getSiteInfo`, `getDialPlanData`, `getMultimediaProfileById`, `getListOfTeams`, `getListOfAuxCodes` resolve the response body | `src/services/config/index.ts` | Non-200 throws `API call failed with {statusCode}`; rejections are logged and rethrown. |
259
+ | Outdial ANI lookup | `getOutdialAniEntries(orgId, params)` resolves `body.data` | `src/services/config/index.ts` | Rejections are rethrown; a resolved non-200 response yields `undefined`. |
260
+
261
+ AI-feature retrieval shares the same actors, ordering, Promise aggregation, and all-or-nothing failure outcome as the other profile dependencies, so it is represented in the Profile aggregation diagram rather than duplicated.
262
+
263
+ ### Profile aggregation
264
+
265
+ Main method that aggregates all configuration data into the AgentProfile.
266
+
267
+ **Returns**: `Promise<Profile>`
268
+
269
+ **Flow**:
270
+
271
+ 1. Fire the user aggregate (`getUserDesktopLoginConfig`), the org aggregate (`getOrgDesktopLoginConfig`) and aux codes (`getAllAuxCodes`) in parallel
272
+ 2. Await the user aggregate — it supplies `user.dbId`, `user.siteId` and `agentProfile.dialPlanEnabled`
273
+ 3. Fetch site info (`getSiteInfo`) and teams filtered by `userId` (`getAllTeams`)
274
+ 4. Fetch dial plan if `agentProfile.dialPlanEnabled` (`getDialPlanData`)
275
+ 5. `Promise.all` the five remaining promises
276
+ 6. Resolve `multimediaProfileId` from the team value, falling back to the site value
277
+ 7. Parse and combine all data (`parseAgentConfigs`)
278
+
279
+ The following diagram shows how `getAgentConfig` orchestrates six API calls and combines their results into the AgentProfile via `parseAgentConfigs()`:
280
+
281
+ ```mermaid
282
+ sequenceDiagram
283
+ participant CC as ContactCenter
284
+ participant Cfg as AgentConfigService
285
+ participant API as WCC APIs
286
+ participant Util as parseAgentConfigs
287
+ CC->>Cfg: getAgentConfig(orgId, agentId)
288
+ par requests started before user data resolves
289
+ Cfg->>API: getUserDesktopLoginConfig
290
+ Cfg->>API: getOrgDesktopLoginConfig
291
+ Cfg->>API: getAllAuxCodes
292
+ end
293
+ API-->>Cfg: user.dbId / user.siteId / agentProfile.dialPlanEnabled
294
+ par user-dependent requests
295
+ Cfg->>API: getSiteInfo + getAllTeams(filter userId==dbId)
296
+ Cfg->>API: conditional dial plan gated on agentProfile.dialPlanEnabled
297
+ end
298
+ Note over Cfg,API: Promise.all awaits 5 result promises after the user aggregate
299
+ alt all succeed
300
+ API-->>Cfg: five results
301
+ Cfg->>Cfg: multimediaProfileId = team value, else site value
302
+ Cfg->>Util: parseAgentConfigs(orgConfig, userData, agentProfileData, ...)
303
+ Util-->>Cfg: Profile including aiFeature
304
+ Cfg-->>CC: Profile
305
+ else any fails
306
+ Cfg-->>CC: throw; no partial Profile
307
+ end
308
+ ```
309
+
310
+ ### Pagination
311
+
312
+ For endpoints with pagination (teams, aux codes):
313
+
314
+ `getAllTeams(orgId, pageSize, userDbId)` starts at `DEFAULT_PAGE` (0), awaits the first `getListOfTeams(orgId, page, pageSize, userDbId)` request to get `totalPages` from `firstResponse.meta.totalPages`, concatenates `firstResponse.data` into `allTeams`, then issues parallel requests for the remaining pages from `DEFAULT_PAGE + 1` while `page < totalPages`, awaits them with `Promise.all`, and concatenates each `response.data` in request order before it returns `allTeams`. `getAllAuxCodes(orgId, pageSize, filter, attributes)` follows the same pattern over `getListOfAuxCodes`. Both log `{method} API call failed with {error}` and rethrow on any rejection.
315
+
316
+ ```mermaid
317
+ sequenceDiagram
318
+ participant Caller
319
+ participant Cfg as AgentConfigService
320
+ participant WR as WebexRequest
321
+ participant API as WCC API
322
+ Caller->>Cfg: getAllTeams(orgId, pageSize, userDbId) / getAllAuxCodes(orgId, pageSize, filter, attributes)
323
+ Cfg->>WR: request page 0
324
+ WR->>API: authenticated GET
325
+ alt first page succeeds
326
+ API-->>Cfg: page 0 data + meta.totalPages
327
+ par remaining pages 1..totalPages-1
328
+ Cfg->>WR: Promise.all(page requests)
329
+ WR->>API: authenticated GETs
330
+ API-->>Cfg: remaining page responses
331
+ end
332
+ alt every remaining page succeeds
333
+ Cfg->>Cfg: concatenate responses in request order
334
+ Cfg-->>Caller: complete accumulated list
335
+ else any remaining page rejects
336
+ Cfg-->>Caller: reject; do not return a partial list
337
+ end
338
+ else first page rejects
339
+ Cfg-->>Caller: reject
340
+ end
341
+ ```
342
+
343
+ ### Wellness idle-code lookup
344
+
345
+ `getWellbeingBreakIdleCode(orgId)` requests `endPointMap.systemIdleCodes` pages one at a time (the code comment says pagination is intentionally sequential so the lookup can stop as soon as the code is found) and returns the first entry that is active, a system code, and named exactly `WellbeingBreak`.
346
+
347
+ ```mermaid
348
+ sequenceDiagram
349
+ participant CC as ContactCenter
350
+ participant Cfg as AgentConfigService
351
+ participant WR as WebexRequest
352
+ participant API as WCC API
353
+ CC->>Cfg: getWellbeingBreakIdleCode(orgId)
354
+ loop page = 0 while page < totalPages
355
+ Cfg->>WR: request systemIdleCodes(orgId, page, 100)
356
+ WR->>API: authenticated GET
357
+ alt statusCode is not 200
358
+ Cfg-->>CC: reject Error(API call failed with statusCode)
359
+ else exact active system code WellbeingBreak on this page
360
+ Cfg-->>CC: Entity {id, name, isSystem: true, isDefault}
361
+ else no match
362
+ Cfg->>Cfg: totalPages = meta.totalPages ?? 1, page += 1
363
+ end
364
+ end
365
+ Cfg-->>CC: reject Error(WELLBEING_BREAK_IDLE_CODE_NOT_FOUND)
366
+ ```
367
+
368
+ ## Class and component relationships
369
+
370
+ ```mermaid
371
+ classDiagram
372
+ class ContactCenter
373
+ class AgentConfigService
374
+ class WebexRequest
375
+ class parseAgentConfigs
376
+ class Profile
377
+ ContactCenter --> AgentConfigService : getAgentConfig
378
+ AgentConfigService --> WebexRequest : six dependent requests
379
+ AgentConfigService --> parseAgentConfigs : aggregate results
380
+ parseAgentConfigs --> Profile : aiFeature + maskSensitiveData
381
+ ```
382
+
383
+ `Services` in `src/services/index.ts` owns the single `AgentConfigService` instance; the service takes
384
+ the `WebexRequest` singleton in its constructor and holds no other state.
385
+
386
+ ## Use cases and flows
387
+
388
+ | Use case | Actor or caller | Primary steps and outcome | Failure or boundary behavior | Evidence |
389
+ | -------- | --------------- | ------------------------- | ---------------------------- | -------- |
390
+ | `UC-001` | ContactCenter `connectWebsocket` during `cc.register()` | Two-wave profile aggregation: start the user, organization, and aux-code requests together, then site, teams, and the conditional dial plan once the user aggregate resolves, and parse one complete Profile or reject the whole operation (see Profile aggregation). | Any rejection rejects registration's profile step | `src/services/config/index.ts`, `src/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` |
391
+ | `UC-002` | `getAgentConfig`, or a caller needing custom pagination | Paginated teams/aux codes: follow backend page metadata to completion; auxiliary-code requests include `desktopProfileFilter=true`. | Any page rejection rejects the list | `src/services/config/index.ts`, `test/unit/spec/services/config/index.ts` |
392
+ | `UC-003` | `getAgentConfig` | Dial plan and URL mappings: request dial-plan data only when the agent profile enables it, keep only `active` plans, and map the organization aggregate's `urlMappings` into the profile. | Empty or absent `urlMappings` yield empty Acqueon URLs | `src/services/config/index.ts`, `src/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` |
393
+ | `UC-004` | `cc.getOutdialAniEntries` | Outdial ANI retrieval: return the organization-scoped ANI list (`body.data`) through authenticated WebexRequest and propagate request rejections without a partial substitute. | A resolved non-200 response returns `undefined` | `src/services/config/index.ts`, `src/cc.ts`, `test/unit/spec/services/config/index.ts` |
394
+ | `UC-005` | `parseAgentConfigs`; `cc.getWellbeingBreakIdleCode` | Wellness configuration: produce one fail-closed effective profile flag and retrieve the exact system wellness idle code across pages. | No exact code rejects with `WELLBEING_BREAK_IDLE_CODE_NOT_FOUND` | `src/services/config/Util.ts`, `src/services/config/index.ts`, `test/unit/spec/services/config/Util.ts`, `test/unit/spec/services/config/index.ts` |
395
+
396
+ ### Cross-boundary use-case flow
397
+
398
+ | Boundary | Transport and ordering | Compatibility | Timeout, retry, and recovery |
399
+ | -------- | ---------------------- | ------------- | ---------------------------- |
400
+ | Contact Center API gateway (`UC-001` to `UC-005`) | `webex.request` with service `wcc-api-gateway` and method GET; ordering under Profile aggregation | Resource shapes in Protocol and wire format | No timeout or retry in this module; the first rejection rejects the operation |
401
+ | Backend WebSocket notifications (contract `wxcc-websocket-notifications`) | Delivered to `src/cc.ts`, which matches `data.type` against `CC_EVENTS` values | Values must equal the backend strings | Unknown types are dropped by the allow-list |
402
+
403
+ ## Business rules and invariants
404
+
405
+ | ID | Invariant | WHY | Enforcement source | Test evidence |
406
+ | --- | --------- | --- | ------------------ | ------------- |
407
+ | `INV-001` | `isWellnessBreakEnabled` is always boolean and defaults false when any gate is absent, disabled, or unlicensed. | Fail-closed gating of a licensed feature. | `src/services/config/Util.ts` | `test/unit/spec/services/config/Util.ts` |
408
+ | `INV-002` | The system wellness code lookup is separate from profile auxiliary-code aggregation and uses `desktopProfileFilter=false`. | The system code need not appear in the agent-selectable idle-code list (JSDoc of `getWellbeingBreakIdleCode`). | `src/services/config/constants.ts`, `src/services/config/index.ts` | `test/unit/spec/services/config/index.ts` |
409
+
410
+ ## Concurrency and reactive flow
411
+
412
+ - Execution model: one JavaScript event loop; every method is `async`.
413
+ - Ordering guarantees: the initial user desktop-login lookup supplies identifiers for the later requests (order under Profile aggregation). Team and aux-code pagination awaits the first page for `meta.totalPages`, then requests the remaining pages in parallel and concatenates them in request order. Only the wellness idle-code lookup awaits pages in order and stops from returned metadata or at the first match.
414
+ - Idempotency and retry: every method is a read; nothing retries or deduplicates.
415
+ - Shared-state protection: no shared mutable state; `parseAgentConfigs` builds a new object per call.
416
+ - Blocking restrictions: none in this module; the caller in `src/cc.ts` awaits `getAgentConfig` before
417
+ it configures the task manager.
418
+
419
+ ## Protocol and wire format
420
+
421
+ All Config operations are authenticated REST calls through WebexRequest. Important current routes include:
422
+
423
+ | Message or frame | Version | Producer or serializer | Consumer or parser | Compatibility and ordering rule |
424
+ | ---------------- | ------- | ---------------------- | ------------------ | ------------------------------- |
425
+ | Organization desktop-login aggregate: `endPointMap.orgDesktopLogin(orgId)` builds `organization/{orgId}/desktop-login`; response `OrgDesktopLoginResponse` | — | Contact Center API gateway | `getOrgDesktopLoginConfig`, `parseAgentConfigs` | Key fields: `organization`: `tenantId`, `timezone`. `organizationSetting`: `webRtcEnabled`, `maskSensitiveData`, `campaignManagerEnabled`, `aiAssistantQuantity`. `tenantConfiguration`: `outdialEnabled`, `forceDefaultDn`, `privacyShieldVisible`, `timeoutDesktopInactivityEnabled`. Optional `urlMappings`, `aiFeature`, `microsoftConfig`, `webexConfig`. All organization-, tenant- and feature-scoped configuration in one call |
426
+ | User desktop-login aggregate: `endPointMap.userDesktopLogin(orgId, ciUserId)` builds `organization/{orgId}/v2/user/by-ci-user-id/{ciUserId}/desktop-login`; response `UserDesktopLoginResponse` | v2 | Contact Center API gateway | `getUserDesktopLoginConfig`, `getAgentConfig`, `parseAgentConfigs` | Key fields: `user`: `ciUserId`, `id`, `dbId`, `firstName`, `lastName`, `email`, `agentProfileId`, `siteId`. `agentProfile`: `dialPlanEnabled`, `accessWrapUpCode`, `accessIdleCode`, `loginVoiceOptions`, `viewableStatistics`. Agent identity, team-filter id, site reference, and desktop settings in one call |
427
+ | Teams: `endPointMap.listTeams(orgId, page, pageSize, userDbId)` builds `organization/{orgId}/v2/team?page={page}&pageSize={pageSize}&agentView=true&filter=userId=={userDbId}`; response `ListTeamsResponse` of `TeamList` records | v2 | Contact Center API gateway | `getListOfTeams`, `getAllTeams` | The wire field is `userId` but the value is the user's database id (`user.dbId`); `meta.totalPages` drives pagination; channel capacities belong to `MultimediaProfileResponse` |
428
+ | Auxiliary codes: `endPointMap.listAuxCodes(orgId, page, pageSize, filter, attributes)` builds `organization/{orgId}/v2/auxiliary-code?page={page}&pageSize={pageSize}`, then `&filter=id=in=({filter})` only when filter has length, then `&attributes={attributes}&desktopProfileFilter=true`; response `ListAuxCodesResponse` | v2 | Contact Center API gateway | `getListOfAuxCodes`, `getAllAuxCodes`, `getFilterAuxCodes` | `getAgentConfig` requests `DEFAULT_AUXCODE_ATTRIBUTES`: `id`, `isSystemCode`, `name`, `defaultCode`, `workTypeCode`, `active` |
429
+ | Wellness system idle code: `endPointMap.systemIdleCodes(orgId, page, pageSize)` builds `organization/{orgId}/v2/auxiliary-code?page={page}&pageSize={pageSize}&workType=IDLE_CODE&customFilter=isSystemCode==true&desktopProfileFilter=false` | v2 | Contact Center API gateway | `getWellbeingBreakIdleCode` | Desktop Profile filtering is bypassed |
430
+ | Multimedia profile: `endPointMap.multimediaProfile(orgId, multimediaProfileId)` builds `organization/{orgId}/multimedia-profile/{multimediaProfileId}`; response `MultimediaProfileResponse` | — | Contact Center API gateway | `getMultimediaProfileById` | Channel capacities and blending settings |
431
+ | Dial plan: `endPointMap.dialPlan(orgId)` builds `organization/{orgId}/dial-plan?agentView=true`; response `DialPlanEntity[]` (`id`, `name`, `regularExpression`, `prefix`, `strippedChars`, `active`) | — | Contact Center API gateway | `getDialPlanData`, `getFilteredDialplanEntries` | Requested only when the agent profile enables dial plans; dial plan rules for outbound calling |
432
+ | Site: `endPointMap.siteInfo(orgId, siteId)` builds `organization/{orgId}/site/{siteId}`; response `SiteInfo` | — | Contact Center API gateway | `getSiteInfo`, `getAgentConfig` | Site details, including the `multimediaProfileId` fallback |
433
+ | Outdial ANI entries: `endPointMap.outdialAniEntries(orgId, outdialANI, queryParams)` builds `organization/{orgId}/v2/outdial-ani/{outdialANI}/entry`, plus `?{queryParams}` only when queryParams is non-empty; response body `data` is `OutdialAniEntriesResponse` | v2 | Contact Center API gateway | `getOutdialAniEntries` | Query parameters only for provided `OutdialAniParams` fields |
434
+ | Builders used by other services: `queueList` (`/organization/{orgId}/v2/contact-service-queue?{queryParams}`), `entryPointDialNumberList` (`/organization/{orgId}/v3/dial-number?{queryParams}`), `addressBookEntries` (`/organization/{orgId}/v2/address-book/{addressBookId}/entry?{queryParams}`), `userPreference` (`organization/{orgId}/user-preference/{userId}`), `userPreferenceCreate` (`organization/{orgId}/user-preference`) | v2, v3 | `src/services/config/constants.ts` | `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/services/AddressBook.ts`, `src/services/UserPreference.ts` | Not called by `AgentConfigService`; user preferences also use non-GET verbs |
435
+ | WebSocket message `type` and `data.type` names | — | Contact Center notification socket | `src/cc.ts`, `src/services/core/websocket/WebSocketManager.ts` | Must equal a `CC_EVENTS` value to be re-emitted |
436
+
437
+ All endpoints are relative to the WCC API Gateway base URL. Query parameters like `agentView=true` filter responses to agent-relevant data.
438
+
439
+ Exact resources live in `src/services/config/constants.ts`; response/profile fields live in `src/services/config/types.ts`. These responses are parsed and aggregated into a single `Profile` object by the `parseAgentConfigs` function.
440
+
441
+ ## Caller-visible failure modes
442
+
443
+ All API methods within the config service throw errors on failure, except that `getOutdialAniEntries` resolves `undefined` for a non-200 response. A failure in any required request, including `getOrgDesktopLoginConfig`, causes the entire AgentProfile fetch to fail (CONFIG-R-005). There is no partial profile — either all data is successfully fetched and aggregated, or the operation throws.
444
+
445
+ Each method follows consistent error handling:
446
+
447
+ Every single-request method, for example `getUserDesktopLoginConfig(orgId, ciUserId)`, logs `LoggerProxy.info` with `module: CONFIG_FILE_NAME` and its `METHODS` name, builds the resource with `endPointMap` (here `endPointMap.userDesktopLogin(orgId, ciUserId)`), awaits `this.webexReq.request({service: WCC_API_GATEWAY, resource, method: HTTP_METHODS.GET})`, throws `new Error('API call failed with {statusCode}')` when `response.statusCode !== 200`, logs `getUserDesktopLoginConfig api success.` through `LoggerProxy.log`, and resolves `response.body`; its catch logs `getUserDesktopLoginConfig API call failed with {error}` through `LoggerProxy.error` and rethrows the error. `getDialPlanData` skips the info line, and `getOutdialAniEntries` skips the status check.
448
+
449
+ A caller wraps the aggregation the same way; the service has already logged the failure:
450
+
451
+ ```typescript
452
+ try {
453
+ const profile = await this.services.config.getAgentConfig(orgId, agentId);
454
+ } catch (error) {
455
+ // getAgentConfig already logged `getAgentConfig call failed with ${error}`
456
+ // with module CONFIG_FILE_NAME and method getAgentConfig, then rethrew.
457
+ throw error;
458
+ }
459
+ ```
460
+
461
+ **Log patterns to search for:**
462
+
463
+ ```typescript
464
+ // General config failure
465
+ "getAgentConfig call failed"
466
+ "module": "config-index", "method": "getAgentConfig"
467
+
468
+ // Specific API method failures
469
+ "getUserDesktopLoginConfig API call failed"
470
+ "getOrgDesktopLoginConfig API call failed"
471
+ "getAllTeams API call failed"
472
+ "getAllAuxCodes API call failed"
473
+
474
+ // Non-200 responses (thrown as errors)
475
+ "API call failed with 404"
476
+ "API call failed with 500"
477
+ ```
478
+
479
+ | Condition | Signal or result | Caller behavior | Retry or recovery | Evidence |
480
+ | --------- | ---------------- | --------------- | ----------------- | -------- |
481
+ | One of the parallel API calls failed (network error, HTTP error, or a non-200 response) | `getAgentConfig` rejects with the original error after logging `getAgentConfig call failed with {error}`; a resolved non-200 response becomes `Error('API call failed with {statusCode}')` | Registration fails at the profile step; check the logs for the specific API that failed (each method logs `{method} API call failed with {error}`) | No retry in this module | `src/services/config/index.ts` |
482
+ | Pagination not completing: a team or aux-code page rejects or is not 200 (for example because filter parameters are incorrect) | `getAllTeams` or `getAllAuxCodes` rejects after `getAllTeams API call failed` or `getAllAuxCodes API call failed` | `getAgentConfig` rejects; no partial list is returned | No retry in this module | `src/services/config/index.ts` |
483
+ | Organization or tenant settings have the feature disabled | No error; `webRtcEnabled` (from `orgSettingsData.webRtcEnabled`) or `isOutboundEnabledForTenant` (from `tenantData.outdialEnabled`, the tenant flag for outbound features) is false | Read the flag before offering the feature | None | `src/services/config/Util.ts` |
484
+ | `dialPlanEnabled` is false in the desktop profile | No dial-plan request is made (the dial plan fetch only happens if `dialPlanEnabled === true`); `Profile.dialPlan` is `undefined` | Dial without transformation rules | None | `src/services/config/index.ts`, `src/services/config/Util.ts` |
485
+ | Expected auxiliary codes missing from the returned pool | `getFilterAuxCodes` applies the full organization pool for every agent; aux codes without `active: true` or with another `workTypeCode` are left out; the "Available" state is always appended to idle codes; `Profile.idleCodesAccess` / `wrapUpData.wrapUpProps.wrapUpCodeAccess` still report `ALL` or `SPECIFIC` from `agentProfileData` | Use `idleCodes` and `wrapupCodes` as returned | None | `src/services/config/Util.ts` |
486
+ | Wellness idle code absent | Rejects with `WELLBEING_BREAK_IDLE_CODE_NOT_FOUND` | `cc.getWellbeingBreakIdleCode` surfaces the error | None | `src/services/config/index.ts` |
487
+ | Outdial ANI response not 200 | Resolves `undefined` | Treat as no entries | None | `src/services/config/index.ts` |
488
+
489
+ ## Pitfalls and constraints
490
+
491
+ - The team filter value must stay unquoted (`filter=userId=={dbId}`) — the quoted form returns HTTP 400 — and must not carry an `attributes=` projection, which would strip `multiMediaProfileId`, `teamType` and `siteName`.
492
+ - `AGENT_BUDDY_AGENTS` and `AGENT_BUDDY_AGENTS_SUCCESS` share the value `BuddyAgents`, so a listener
493
+ cannot tell them apart; some task values (`REAL_TIME_TRANSCRIPTION`, `SUGGESTED_RESPONSE`, and others)
494
+ are upper-case strings rather than PascalCase.
495
+ - `queueList`, `entryPointDialNumberList`, and `addressBookEntries` resources start with `/`; the
496
+ config-owned resources do not.
497
+
498
+ ## Module-specific rules
499
+
500
+ - DO add a new backend notification type to `CC_AGENT_EVENTS` or `CC_TASK_EVENTS` before relying on
501
+ ContactCenter to re-emit it.
502
+ - DO log through `LoggerProxy` with `module: CONFIG_FILE_NAME` and a `METHODS` name.
503
+
504
+ ## Key design trade-off
505
+
506
+ | Chosen trade-off | Preserved invariant or benefit | Cost or limitation | Decision evidence |
507
+ | ---------------- | ------------------------------ | ------------------ | ----------------- |
508
+ | One `Promise.all` over all profile dependencies | Consumers get a complete Profile or an error (CONFIG-R-005) | One failed optional-looking call (for example the dial plan) fails registration's profile step | `src/services/config/index.ts` |
509
+ | Two desktop-login aggregates instead of separate organization, setting, tenant, URL-mapping, AI-feature, user, and agent-profile calls | Fewer requests per registration | Per-agent aux-code and dial-plan selections are not carried, so the full active pools apply | `src/services/config/types.ts`, `src/services/config/Util.ts` |
510
+
511
+ ## Verification
512
+
513
+ `test/unit/spec/services/config/index.ts` must cover staged user-first orchestration, five-promise aggregation, AI-feature mapping, conditional dial plan, the `userDbId` team filter, pagination, auxiliary-code URL filtering, real response field names, and whole-profile rejection on any required failure.
514
+
515
+ | Requirement or invariant | Test level | Positive evidence | Negative or boundary evidence | Gap |
516
+ | ------------------------ | ---------- | ----------------- | ----------------------------- | --- |
517
+ | `CONFIG-R-001`, `CONFIG-R-009` | Unit | `test/unit/spec/services/config/index.ts` (getAgentConfig staging, team and site arguments, multimedia fallback cases) | `test/unit/spec/services/config/index.ts` | Call order is asserted through arguments, not timing |
518
+ | `CONFIG-R-002` | Unit | `test/unit/spec/services/config/Util.ts` (aiFeature pass-through, absent section) | `test/unit/spec/services/config/Util.ts` | None |
519
+ | `CONFIG-R-003` | Unit | `test/unit/spec/services/config/index.ts` (getListOfTeams unquoted filter, getListOfAuxCodes URL, getAllTeams, getAllAuxCodes) | `test/unit/spec/services/config/index.ts` (non-200 pages) | None |
520
+ | `CONFIG-R-004` | Unit | `test/unit/spec/services/config/index.ts`, `test/unit/spec/services/config/Util.ts` | None found | Types are compile-time only |
521
+ | `CONFIG-R-005` | Unit | `test/unit/spec/services/config/index.ts` | `test/unit/spec/services/config/index.ts` (five rejecting calls) | Keep an explicit rejection assertion for each required dependency category; the dial-plan rejection is missing |
522
+ | `CONFIG-R-006`, `INV-001` | Unit | `test/unit/spec/services/config/Util.ts` (wellness enabled) | `test/unit/spec/services/config/Util.ts` (missing gate, absent section) | A null `aiAssistantQuantity` is not asserted |
523
+ | `CONFIG-R-007`, `INV-002` | Unit | `test/unit/spec/services/config/index.ts` (system-code query across pages) | `test/unit/spec/services/config/index.ts` (inactive and look-alike codes) | A non-200 page is not asserted |
524
+ | `CONFIG-R-008` | Unit | `test/unit/spec/cc.ts` (known type emitted), `test/unit/spec/index.ts` (exports) | `test/unit/spec/cc.ts` (unknown type not emitted) | None |
525
+ | `CONFIG-R-010` | Unit | `test/unit/spec/services/config/index.ts` (minimal, full, partial parameters) | `test/unit/spec/services/config/index.ts` (rejection, 404, 500, missing body) | None |
526
+ | `CONFIG-R-011`, `CONFIG-R-012` | Unit | `test/unit/spec/services/config/Util.ts` (aux codes, dial plan) | `test/unit/spec/services/config/Util.ts` (no default code, dial planning disabled) | None |
527
+
528
+ Run `yarn workspace @webex/contact-center test:unit` from the workspace root. A module specification is complete only when its public surface,
529
+ invariants, failure modes, and test evidence agree with the implementation; coverage is pending a fresh
530
+ coverage review and independent validation.