@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
@@ -1,250 +0,0 @@
1
- # Config Service - AI Agent Guide
2
-
3
- > **Legacy/reference-only.** Canonical SDD: [`config-spec.md`](config-spec.md). Use the package [manifest](../../../../.sdd/manifest.json) and [`SPEC_INDEX.md`](../../../../ai-docs/SPEC_INDEX.md) for routing; code and tests remain the behavioral referee.
4
- >
5
- > **Purpose**: Fetch and aggregate agent configuration data from multiple API endpoints to build the AgentProfile.
6
- >
7
- > **Legacy scope:** See [Root AGENTS.md](../../../../AGENTS.md) for the orchestrator and cross-scope rules.
8
-
9
- ---
10
-
11
- ## Overview
12
-
13
- The Config Service is an **internal service** that builds the comprehensive AgentProfile (`Profile` type) by:
14
- 1. Fetching the user desktop-login aggregate (agent identity plus `agentProfile`)
15
- 2. Fetching the organization desktop-login aggregate (org info, org settings, tenant configuration, URL mappings, AI feature, Microsoft/Webex config)
16
- 3. Fetching teams
17
- 4. Fetching aux codes (idle/wrapup codes)
18
- 5. Fetching site and, when the agent profile enables it, dial-plan data
19
- 6. Aggregating all data into a single AgentProfile
20
-
21
- 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.
22
-
23
-
24
- ---
25
-
26
- ## File Structure
27
-
28
- ```
29
- services/config/
30
- ├── index.ts # AgentConfigService class
31
- ├── types.ts # Profile, CC_EVENTS, types
32
- ├── constants.ts # API endpoints, defaults
33
- ├── Util.ts # parseAgentConfigs helper
34
- └── ai-docs/
35
- ├── AGENTS.md # Usage documentation
36
- └── ARCHITECTURE.md # This file
37
- ```
38
-
39
- ---
40
-
41
- ## Quick Usage
42
-
43
- ```typescript
44
- // Config service is used internally during the registration flow.
45
- // Inside cc.ts → connectWebsocket(), after WebSocket connection is established:
46
- const agentId = data.agentId;
47
- const orgId = this.$webex.credentials.getOrgId();
48
- this.agentConfig = await this.services.config.getAgentConfig(orgId, agentId);
49
-
50
- // The returned AgentProfile contains all agent configuration:
51
- LoggerProxy.info(`Agent ID: ${this.agentConfig.agentId}`, {
52
- module: 'cc',
53
- method: 'connectWebsocket',
54
- });
55
- LoggerProxy.info(`Teams: ${this.agentConfig.teams}`, {
56
- module: 'cc',
57
- method: 'connectWebsocket',
58
- });
59
- ```
60
-
61
- ---
62
-
63
- ## Key Capabilities
64
-
65
- - **AgentProfile Aggregation**: Combines data from 6 API endpoints (5 when the agent profile disables dial plans)
66
- - **Aux Codes Fetching**: Gets all idle and wrapup codes with pagination
67
- - **Team Data**: Retrieves agent's team assignments
68
- - **Dial Plan**: Fetches number transformation rules
69
- - **Outdial ANI**: Retrieves outbound caller ID options (standalone, publicly exposed via `cc.ts`)
70
- - **Multimedia Profile**: Fetches channel capacity and blending config (standalone, not yet publicly exposed)
71
- - **Paginated Data Access**: `getListOfTeams` and `getListOfAuxCodes` support custom pagination independent of profile building. `getListOfTeams` takes a `userDbId` — the `user.dbId` carried by the user desktop-login aggregate, not the CI user id — rather than a list of team ids
72
-
73
- ---
74
-
75
- ## AgentProfile Object (Key Fields)
76
-
77
- 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:
78
-
79
- | Field | Type | Description |
80
- |-------|------|-------------|
81
- | `agentId` | string | Unique agent identifier |
82
- | `agentName` | string | Display name |
83
- | `agentMailId` | string | Email address |
84
- | `teams` | [`TeamList[]`](../types.ts) | Assigned teams (runtime data from `getAllTeams()` — `Profile` type declares `Team[]` but actual objects are `TeamList` with `id`, `name`, `teamType`, `siteId`, etc.) |
85
- | `defaultDn` | string | Default dial number |
86
- | `idleCodes` | [`Entity[]`](../types.ts) | Available idle codes |
87
- | `wrapupCodes` | [`Entity[]`](../types.ts) | Available wrapup codes |
88
- | `webRtcEnabled` | boolean | WebRTC calling enabled |
89
- | `loginVoiceOptions` | [`LoginOption[]`](../types.ts) | Available login types |
90
- | `dialPlan` | [`DialPlan`](../types.ts) | Number transformation rules |
91
- | `isOutboundEnabledForAgent` | boolean | Outbound calling allowed |
92
- | `outDialEp` | string | Outbound entry point ID |
93
-
94
- ---
95
-
96
- ## Data Aggregation Flow
97
-
98
- The following diagram shows how `getAgentConfig` orchestrates six API calls and combines their results into the AgentProfile via `parseAgentConfigs()`:
99
-
100
- ```
101
- getUserDesktopLoginConfig ──┐ (awaited first; supplies dbId, siteId, dialPlanEnabled)
102
- │
103
- getOrgDesktopLoginConfig ───┤ (org info, org settings, tenant config, urlMappings,
104
- │ aiFeature, microsoftConfig, webexConfig)
105
- getAllAuxCodes ─────────────┼──► parseAgentConfigs() ──► AgentProfile
106
- │
107
- getAllTeams ────────────────┤ (filtered by userId == user.dbId)
108
- │
109
- getSiteInfo ────────────────┤ (team → site fallback for multimediaProfileId)
110
- │
111
- getDialPlanData ────────────┘ (only when agentProfile.dialPlanEnabled)
112
- ```
113
-
114
- ---
115
-
116
- ## API Methods (Internal)
117
-
118
- ### `getAgentConfig(orgId, agentId)`
119
-
120
- Main method that aggregates all configuration data into the AgentProfile.
121
-
122
- **Returns**: `Promise<Profile>`
123
-
124
- **Flow**:
125
- 1. Fire the user aggregate (`getUserDesktopLoginConfig`), the org aggregate (`getOrgDesktopLoginConfig`) and aux codes (`getAllAuxCodes`) in parallel
126
- 2. Await the user aggregate — it supplies `user.dbId`, `user.siteId` and `agentProfile.dialPlanEnabled`
127
- 3. Fetch site info (`getSiteInfo`) and teams filtered by `userId` (`getAllTeams`)
128
- 4. Fetch dial plan if `agentProfile.dialPlanEnabled` (`getDialPlanData`)
129
- 5. `Promise.all` the five remaining promises
130
- 6. Resolve `multimediaProfileId` from the team value, falling back to the site value
131
- 7. Parse and combine all data (`parseAgentConfigs`)
132
-
133
- ---
134
-
135
- ## Standalone APIs (Not Part of AgentProfile Building)
136
-
137
- These methods exist in `AgentConfigService` but are **not** part of the `getAgentConfig()` aggregation flow. They can be used independently by applications.
138
-
139
- | Method | Status | Returns | Description |
140
- |--------|--------|---------|-------------|
141
- | `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). |
142
- | `getMultimediaProfileById(orgId, multimediaProfileId)` | **Not exposed, never called** | `MultimediaProfileResponse` | Fetch channel capacities (chat, email, telephony, social) and blending config. Available but unused anywhere. |
143
- | `getListOfTeams(orgId, page, pageSize, userDbId)` | Used internally by `getAllTeams()` | `ListTeamsResponse` | Single-page team fetch with pagination metadata, filtered by `user.dbId` (the wire field is `filter=userId==` but the value is the database id, not the CI user id). The filter value must stay unquoted — the quoted form returns HTTP 400. |
144
- | `getListOfAuxCodes(orgId, page, pageSize, filter, attributes)` | Used internally by `getAllAuxCodes()` | `ListAuxCodesResponse` | Single-page aux code fetch with pagination metadata. Useful for custom pagination. |
145
-
146
- Additionally, the following endpoints are defined in `constants.ts` `endPointMap` but are consumed by separate service classes, not by `AgentConfigService`:
147
-
148
- | Endpoint | Used By | Description |
149
- |----------|---------|-------------|
150
- | `queueList` | [`Queue.ts`](../../Queue.ts) | Fetch contact service queues |
151
- | `entryPointDialNumberList` | [`EntryPoint.ts`](../../EntryPoint.ts) | Fetch profile-scoped entry-point dial-number mappings |
152
- | `addressBookEntries` | [`AddressBook.ts`](../../AddressBook.ts) | Fetch address book entries |
153
-
154
- ---
155
-
156
- ## Key Types
157
-
158
- Types used by the config service, all defined in [`types.ts`](../types.ts):
159
-
160
- | Type | Description |
161
- |------|-------------|
162
- | `Profile` | Final aggregated agent config returned by `getAgentConfig()` |
163
- | `OrgDesktopLoginResponse` | Response from `getOrgDesktopLoginConfig()` — `organization`, `organizationSetting`, `tenantConfiguration`, `urlMappings`, `aiFeature`, `microsoftConfig`, `webexConfig` |
164
- | `UserDesktopLoginResponse` | Response from `getUserDesktopLoginConfig()` — `user` and `agentProfile` sections |
165
- | `AgentResponse` | `user` section of the user aggregate — agent metadata, `dbId`, `siteId`, `agentProfileId` |
166
- | `AgentProfile` | `agentProfile` section of the user aggregate — layout, dial-plan enablement, login options |
167
- | `TeamList` | Team record from API — `id`, `name`, `teamType`, `siteId`, `multiMediaProfileId` |
168
- | `ListTeamsResponse` | Paginated wrapper around `TeamList[]` with `meta` for pagination |
169
- | `OrgInfo` | Organization info — `tenantId`, timezone |
170
- | `OrgSettings` | Org feature flags — `webRtcEnabled`, `sensitiveDataMaskingEnabled` |
171
- | `TenantData` | Tenant-level config — inactivity timeout, `forceDefaultDn`, `outdialEnabled` |
172
- | `SiteInfo` | Site config — `id`, `name`, `multimediaProfileId` |
173
- | `OrgUrlMappings` | Keyed external URL mappings — `ACQUEON_API_URL`, `ACQUEON_CONSOLE_URL` |
174
- | `MicrosoftConfig` | Org-level Microsoft presence config — `showUserDetails`, `stateSynchronization` |
175
- | `WebexConfig` | Org-level Webex presence config — `showUserDetails`, `stateSynchronization` |
176
- | `MultimediaProfileResponse` | Multimedia profile — channel capacities and settings |
177
- | `AuxCode` | Auxiliary code record — `id`, `name`, `description`, `workTypeCode` |
178
- | `ListAuxCodesResponse` | Paginated wrapper around `AuxCode[]` with `meta` |
179
- | `DialPlanEntity` | Dial plan rule — regex pattern, prefix, strip digits, `active` |
180
- | `Entity` | Basic entity info — `isSystem`, `name`, `id`, `description` |
181
- | `WrapupData` | Wrap-up config — auto-wrapup settings, available wrapup codes |
182
- | `OutdialAniParams` | Parameters for `getOutdialAniEntries()` — ANI ID, pagination, filtering |
183
-
184
- ## Events (CC_EVENTS)
185
-
186
- The config service defines event constants used throughout the SDK:
187
-
188
- | Event Category | Examples |
189
- |----------------|----------|
190
- | Agent Events | WELCOME, AGENT_LOGOUT, AGENT_STATE_CHANGE |
191
- | Task Events | AGENT_CONTACT, AGENT_OFFER_CONTACT, CONTACT_ENDED |
192
- | Login Events | AGENT_STATION_LOGIN_SUCCESS, AGENT_STATION_LOGIN_FAILED |
193
-
194
- See [`types.ts`](../types.ts) for complete list.
195
-
196
- ---
197
-
198
- ## Types Defined
199
-
200
- Key types in `services/config/types.ts`:
201
-
202
- | Type | Description |
203
- |------|-------------|
204
- | `Profile` | Complete AgentProfile |
205
- | `CC_EVENTS` | All event constants |
206
- | `CC_AGENT_EVENTS` | Agent-specific events |
207
- | `CC_TASK_EVENTS` | Task-specific events |
208
- | `AuxCode` | Idle/wrapup code definition |
209
- | `Team` | Team configuration |
210
- | `AgentProfile` | Agent profile settings from the user aggregate |
211
- | `LoginOption` | Login types (BROWSER, EXTENSION, AGENT_DN) |
212
-
213
- ---
214
-
215
- ## Error Handling
216
-
217
- All API methods within the config service throw errors on failure. Since `getAgentConfig` calls multiple sub-APIs (`getUserDesktopLoginConfig`, `getOrgDesktopLoginConfig`, `getAllAuxCodes`, `getAllTeams`, `getSiteInfo`, `getDialPlanData`) and awaits them via `Promise.all`, **a failure in any single sub-API will cause the entire AgentProfile fetch to fail**. There is no partial profile — either all data is successfully fetched and aggregated, or the operation throws.
218
-
219
- ```typescript
220
- try {
221
- const profile = await this.services.config.getAgentConfig(orgId, agentId);
222
- } catch (error) {
223
- LoggerProxy.error(`Config fetch failed: ${error}`, {
224
- module: 'ConfigService',
225
- method: 'getAgentConfig',
226
- });
227
- throw error;
228
- }
229
- ```
230
-
231
- ---
232
-
233
- ## Usage in cc.ts
234
-
235
- ```typescript
236
- // In register() -> connectWebsocket()
237
- const agentId = data.agentId;
238
- const orgId = this.$webex.credentials.getOrgId();
239
- this.agentConfig = await this.services.config.getAgentConfig(orgId, agentId);
240
- ```
241
-
242
- ---
243
-
244
- ## Related
245
-
246
- - [Root AGENTS.md](../../../../AGENTS.md) - Orchestrator and cross-scope rules
247
- - [ARCHITECTURE.md](ARCHITECTURE.md) - Technical deep-dive
248
- - [types.ts](../types.ts) - Type definitions
249
- - [Util.ts](../Util.ts) - AgentProfile parsing utilities
250
- - [constants.ts](../constants.ts) - API endpoints
@@ -1,413 +0,0 @@
1
- # Config Service - Architecture
2
-
3
- > **Legacy/reference-only.** Canonical SDD: [`config-spec.md`](config-spec.md). Use the package [manifest](../../../../.sdd/manifest.json) and [`SPEC_INDEX.md`](../../../../ai-docs/SPEC_INDEX.md) for routing; code and tests remain the behavioral referee.
4
-
5
- > **Purpose**: Technical documentation for agent configuration aggregation.
6
-
7
- ---
8
-
9
- ## Component Overview
10
-
11
- | Component | File | Responsibility |
12
- |-----------|------|----------------|
13
- | `AgentConfigService` | `config/index.ts` | Main config service class |
14
- | `parseAgentConfigs` | `config/Util.ts` | Profile parsing/aggregation |
15
- | `endPointMap` | `config/constants.ts` | API endpoint definitions |
16
- | `types` | `config/types.ts` | Types, events, interfaces |
17
-
18
- ---
19
-
20
- ## Data Flow
21
-
22
- ```mermaid
23
- sequenceDiagram
24
- participant CC as ContactCenter
25
- participant Cfg as AgentConfigService
26
- participant WR as WebexRequest
27
- participant API as Backend APIs
28
-
29
- CC->>Cfg: getAgentConfig(orgId, agentId)
30
-
31
- par Wave 1 — fire immediately
32
- Cfg->>WR: getUserDesktopLoginConfig
33
- Cfg->>WR: getOrgDesktopLoginConfig
34
- Cfg->>WR: getAllAuxCodes
35
- end
36
-
37
- WR->>API: 3 parallel API calls
38
- API-->>WR: Responses
39
- Note over Cfg: await userConfig (supplies dbId, siteId, dialPlanEnabled)
40
-
41
- par Wave 2 — depends on userConfig
42
- Cfg->>WR: getSiteInfo(user.siteId)
43
- Cfg->>WR: getAllTeams(user.dbId)
44
- Cfg->>WR: getDialPlanData (only if agentProfile.dialPlanEnabled)
45
- end
46
-
47
- Note over Cfg: Single Promise.all() awaits 5 promises<br/>(org aggregate + aux codes + site + teams + conditional dialPlan)
48
- Note over Cfg: multimediaProfileId = team value, else site value
49
-
50
- WR->>API: Remaining API calls
51
- API-->>WR: Responses
52
-
53
- Cfg->>Cfg: parseAgentConfigs(allData)
54
- Cfg-->>CC: Profile
55
- ```
56
-
57
- ---
58
-
59
- ## API Endpoints
60
-
61
- The config service uses multiple API endpoints to fetch agent configuration data. These endpoints are defined in `constants.ts` and include:
62
-
63
- - **User desktop-login aggregate**: agent identity plus the `agentProfile` section in one call
64
- - **Organization desktop-login aggregate**: organization info, organization settings, tenant configuration, URL mappings, AI feature, Microsoft/Webex config in one call
65
- - **Team & site**: Team memberships filtered by the agent's `userId`, plus site information
66
- - **Auxiliary codes**: Idle codes and wrap-up codes with pagination
67
- - **Communication settings**: Dial plans, multimedia profiles
68
- - **Outbound features**: Queue lists, entry points, address books, outdial ANI entries
69
-
70
- ### Endpoint Definitions
71
-
72
- All endpoints are relative to the WCC API Gateway base URL. Query parameters like `agentView=true` filter responses to agent-relevant data.
73
-
74
- **Example Usage:**
75
- ```typescript
76
- // Fetch the user desktop-login aggregate
77
- const resource = endPointMap.userDesktopLogin('org-123', 'agent-456');
78
- // Result: "organization/org-123/v2/user/by-ci-user-id/agent-456/desktop-login"
79
-
80
- // Fetch teams with pagination, filtered by the user's database id
81
- const resource = endPointMap.listTeams('org-123', 0, 100, 'user-db-id');
82
- // Result: "organization/org-123/v2/team?page=0&pageSize=100&agentView=true&filter=userId==user-db-id"
83
-
84
- // Fetch the organization desktop-login aggregate
85
- const resource = endPointMap.orgDesktopLogin('org-123');
86
- // Result: "organization/org-123/desktop-login"
87
- ```
88
-
89
- **Full Endpoint Map:**
90
- ```typescript
91
- export const endPointMap = {
92
- orgDesktopLogin: (orgId: string) =>
93
- `organization/${orgId}/desktop-login`,
94
-
95
- userDesktopLogin: (orgId: string, ciUserId: string) =>
96
- `organization/${orgId}/v2/user/by-ci-user-id/${ciUserId}/desktop-login`,
97
-
98
- multimediaProfile: (orgId: string, multimediaProfileId: string) =>
99
- `organization/${orgId}/multimedia-profile/${multimediaProfileId}`,
100
-
101
- // The filter value must stay unquoted — the quoted form returns HTTP 400.
102
- listTeams: (orgId: string, page: number, pageSize: number, userDbId: string) =>
103
- `organization/${orgId}/v2/team?page=${page}&pageSize=${pageSize}` +
104
- `&agentView=true&filter=userId==${userDbId}`,
105
-
106
- listAuxCodes: (orgId: string, page: number, pageSize: number, filter: string[], attributes: string[]) =>
107
- `organization/${orgId}/v2/auxiliary-code?page=${page}&pageSize=${pageSize}${
108
- filter && filter.length > 0 ? `&filter=id=in=(${filter})` : ''
109
- }&attributes=${attributes}`,
110
-
111
- siteInfo: (orgId: string, siteId: string) =>
112
- `organization/${orgId}/site/${siteId}`,
113
-
114
- dialPlan: (orgId: string) =>
115
- `organization/${orgId}/dial-plan?agentView=true`,
116
-
117
- queueList: (orgId: string, queryParams: string) =>
118
- `/organization/${orgId}/v2/contact-service-queue?${queryParams}`,
119
-
120
- entryPointDialNumberList: (orgId: string, queryParams: string) =>
121
- `/organization/${orgId}/v3/dial-number?${queryParams}`,
122
-
123
- addressBookEntries: (orgId: string, addressBookId: string, queryParams: string) =>
124
- `/organization/${orgId}/v2/address-book/${addressBookId}/entry?${queryParams}`,
125
-
126
- outdialAniEntries: (orgId: string, outdialANI: string, queryParams: string) =>
127
- `organization/${orgId}/v2/outdial-ani/${outdialANI}/entry${
128
- queryParams ? `?${queryParams}` : ''
129
- }`,
130
- };
131
- ```
132
-
133
- ---
134
-
135
- ## Pagination Pattern
136
-
137
- For endpoints with pagination (teams, aux codes):
138
-
139
- ```typescript
140
- import {DEFAULT_PAGE} from './constants'; // DEFAULT_PAGE = 0
141
-
142
- public async getAllTeams(orgId, pageSize, filter): Promise<TeamList[]> {
143
- let allTeams: TeamList[] = [];
144
- let page = DEFAULT_PAGE;
145
-
146
- // First request to get totalPages
147
- const firstResponse = await this.getListOfTeams(orgId, page, pageSize, filter);
148
- allTeams = allTeams.concat(firstResponse.data);
149
- const totalPages = firstResponse.meta.totalPages;
150
-
151
- // Parallel requests for remaining pages
152
- const requests = [];
153
- for (page = DEFAULT_PAGE + 1; page < totalPages; page += 1) {
154
- requests.push(this.getListOfTeams(orgId, page, pageSize, filter));
155
- }
156
-
157
- const responses = await Promise.all(requests);
158
- for (const response of responses) {
159
- allTeams = allTeams.concat(response.data);
160
- }
161
-
162
- return allTeams;
163
- }
164
- ```
165
-
166
- ---
167
-
168
- ## Profile Parsing
169
-
170
- `parseAgentConfigs` in Util.ts combines all data into a unified `Profile` object. See [types.ts](../types.ts) for full type definitions.
171
-
172
- ### API Response Structures
173
-
174
- The service fetches data from multiple APIs with these response structures:
175
-
176
- | API Method | Response Type | Key Fields | Usage |
177
- |------------|---------------|------------|-------|
178
- | `getUserDesktopLoginConfig` | `UserDesktopLoginResponse` | `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 |
179
- | `getOrgDesktopLoginConfig` | `OrgDesktopLoginResponse` | `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 |
180
- | `getAllTeams` | `TeamList[]` | `id`, `name`, `teamType`, `siteId`, `siteName`, `multiMediaProfileId` (+ more) | Team details for the teams the agent belongs to |
181
- | `getAllAuxCodes` | `AuxCode[]` | `id`, `name`, `workTypeCode`, `active`, `isSystemCode`, `defaultCode` | Auxiliary codes for idle/wrap-up states |
182
- | `getDialPlanData` | `DialPlanEntity[]` | `id`, `name`, `regularExpression`, `prefix`, `strippedChars`, `active` | Dial plan rules for outbound calling |
183
- | `getSiteInfo` | `SiteInfo` | Site-specific configuration | Site details, including the `multimediaProfileId` fallback |
184
-
185
- These responses are parsed and aggregated into a single `Profile` object by the `parseAgentConfigs` function.
186
-
187
- ### Profile Aggregation Function
188
-
189
- ```typescript
190
- // See full implementation in Util.ts
191
- function parseAgentConfigs(profileData: {
192
- orgConfig: OrgDesktopLoginResponse; // See types.ts:OrgDesktopLoginResponse
193
- userData: AgentResponse; // `user` section; see types.ts:AgentResponse
194
- agentProfileData: AgentProfile; // `agentProfile` section; see types.ts:AgentProfile
195
- teamData: TeamList[]; // See types.ts:TeamList
196
- auxCodes: AuxCode[]; // See types.ts:AuxCode
197
- dialPlanData: DialPlanEntity[]; // See types.ts:DialPlanEntity
198
- multimediaProfileId: string;
199
- }): Profile { // See types.ts:Profile
200
- const { orgConfig, userData, agentProfileData, teamData, auxCodes,
201
- dialPlanData } = profileData;
202
- const {
203
- organization: orgInfoData,
204
- organizationSetting: orgSettingsData,
205
- tenantConfiguration: tenantData,
206
- urlMappings,
207
- aiFeature,
208
- microsoftConfig,
209
- webexConfig,
210
- } = orgConfig;
211
-
212
- // Aux code filtering via getFilterAuxCodes():
213
- // - checks auxCode.workTypeCode and auxCode.active
214
- // - the aggregate returns the full org pool, so no per-agent restriction is applied
215
- // - maps to Entity {id, name, isSystem, isDefault}
216
- const wrapupCodes = getFilterAuxCodes(auxCodes, WRAP_UP_CODE);
217
- const idleCodes = getFilterAuxCodes(auxCodes, IDLE_CODE);
218
-
219
- // Hardcoded "Available" state always appended to idle codes
220
- idleCodes.push({ id: '0', name: 'Available', isSystem: false, isDefault: false });
221
-
222
- return {
223
- agentId: userData.ciUserId, // NOTE: uses ciUserId for agent identification
224
- analyserUserId: userData.id, // NOTE: userData.id is used for analytics/reporting
225
- agentName: `${userData.firstName} ${userData.lastName}`,
226
- teams: teamData, // TeamList[] straight from the team API; Profile.teams is TeamList[]
227
- idleCodes, // NOTE: Filtered via getFilterAuxCodes() + hardcoded "Available" state
228
- wrapupCodes, // NOTE: Filtered via getFilterAuxCodes()
229
- webRtcEnabled: orgSettingsData.webRtcEnabled,
230
- loginVoiceOptions: agentProfileData.loginVoiceOptions ?? [],
231
- enterpriseId: orgInfoData.tenantId,
232
- tenantTimezone: orgInfoData.timezone,
233
- multimediaProfileId: profileData.multimediaProfileId,
234
- // ... 30+ more fields — see Util.ts:184-258 for full implementation
235
- };
236
- }
237
- ```
238
-
239
- ---
240
-
241
- ## Error Handling
242
-
243
- Each method follows consistent error handling:
244
-
245
- ```typescript
246
- public async getUserDesktopLoginConfig(
247
- orgId: string,
248
- ciUserId: string
249
- ): Promise<UserDesktopLoginResponse> {
250
- LoggerProxy.info('Fetching user desktop-login configuration', {
251
- module: CONFIG_FILE_NAME,
252
- method: METHODS.GET_USER_DESKTOP_LOGIN_CONFIG,
253
- });
254
-
255
- try {
256
- const resource = endPointMap.userDesktopLogin(orgId, ciUserId);
257
- const response = await this.webexReq.request({
258
- service: WCC_API_GATEWAY,
259
- resource,
260
- method: HTTP_METHODS.GET,
261
- });
262
-
263
- if (response.statusCode !== 200) {
264
- throw new Error(`API call failed with ${response.statusCode}`);
265
- }
266
-
267
- LoggerProxy.log('getUserDesktopLoginConfig api success.', {
268
- module: CONFIG_FILE_NAME,
269
- method: METHODS.GET_USER_DESKTOP_LOGIN_CONFIG,
270
- });
271
-
272
- return Promise.resolve(response.body);
273
- } catch (error) {
274
- LoggerProxy.error(`getUserDesktopLoginConfig API call failed with ${error}`, {
275
- module: CONFIG_FILE_NAME,
276
- method: METHODS.GET_USER_DESKTOP_LOGIN_CONFIG,
277
- });
278
- throw error;
279
- }
280
- }
281
- ```
282
-
283
- ---
284
-
285
- ## Troubleshooting
286
-
287
- ### Common Issues and Log Patterns
288
-
289
- #### Issue: Profile incomplete or getAgentConfig fails
290
-
291
- **Cause**: One of the parallel API calls failed (network error, 401/403/404/500 response)
292
-
293
- **Log patterns to search for:**
294
- ```typescript
295
- // General config failure
296
- "getAgentConfig call failed"
297
- "module": "config/index.ts", "method": "getAgentConfig"
298
-
299
- // Specific API method failures
300
- "getUserDesktopLoginConfig API call failed"
301
- "getOrgDesktopLoginConfig API call failed"
302
- "getAllTeams API call failed"
303
- "getAllAuxCodes API call failed"
304
-
305
- // Look for HTTP error codes
306
- "API call failed with 401" // Authentication
307
- "API call failed with 403" // Authorization
308
- "API call failed with 404" // Not found
309
- "API call failed with 500" // Server error
310
- ```
311
-
312
- **Solution**:
313
- 1. Check logs for specific API that failed
314
- 2. Verify orgId and agentId are correct
315
- 3. Ensure authentication tokens are valid
316
- 4. Check network connectivity to WCC API Gateway
317
-
318
- #### Issue: Empty teams or aux codes
319
-
320
- **Cause**: Pagination not completing or filter parameters incorrect
321
-
322
- **Log patterns:**
323
- ```typescript
324
- "getAllTeams API call failed"
325
- "getAllAuxCodes API call failed"
326
- "method": "getListOfTeams"
327
- "method": "getListOfAuxCodes"
328
- ```
329
-
330
- **Solution**:
331
- 1. Check `totalPages` in first response
332
- 2. Verify the team filter carries a valid `userDbId` (`user.dbId`, not the CI user id) and that aux-code filters contain valid IDs
333
- 3. Check if pageSize is appropriate (default: 100)
334
- 4. Ensure all pages are fetched in Promise.all()
335
-
336
- #### Issue: WebRTC or other features not enabled
337
-
338
- **Cause**: Organization or tenant settings have feature disabled
339
-
340
- **Log patterns:**
341
- ```typescript
342
- "getOrgDesktopLoginConfig api success."
343
- "getUserDesktopLoginConfig api success."
344
- ```
345
-
346
- **Solution**:
347
- 1. Check `orgSettingsData.webRtcEnabled` in response
348
- 2. Check `tenantData.outdialEnabled` for outbound features
349
- 3. Verify feature is enabled in admin portal settings
350
- 4. Confirm agentProfileData has correct feature flags
351
-
352
- #### Issue: Missing dial plan data
353
-
354
- **Cause**: `dialPlanEnabled` is false in desktop profile
355
-
356
- **Solution**:
357
- 1. Check `agentProfileData.dialPlanEnabled` value
358
- 2. Verify dial plans are assigned in agent profile configuration
359
- 3. Note: dial plan fetch only happens if `dialPlanEnabled === true`
360
-
361
- #### Issue: Expected auxiliary codes missing from the returned pool
362
-
363
- **Log patterns:**
364
- ```typescript
365
- "method": "getFilterAuxCodes"
366
- ```
367
-
368
- **Solution**:
369
- 1. `getFilterAuxCodes` no longer applies a per-agent restriction list — the full organization pool is returned for every agent
370
- 2. `Profile.idleCodesAccess` / `wrapupCodesAccess` still report `ALL` or `SPECIFIC` from `agentProfileData`
371
- 3. Ensure aux codes have `active: true` status and the expected `workTypeCode`
372
- 4. Note: "Available" state is always appended to idle codes
373
-
374
- ---
375
-
376
- ## Types and Events
377
-
378
- The config service defines comprehensive TypeScript types for all data structures. See [types.ts](../types.ts) for complete definitions.
379
-
380
- ### Core Types
381
-
382
- **Configuration Types:**
383
- - `Profile` - Unified agent profile after aggregation
384
- - `OrgDesktopLoginResponse` - Organization desktop-login aggregate
385
- - `UserDesktopLoginResponse` - User desktop-login aggregate (`user` + `agentProfile`)
386
- - `AgentResponse` - `user` section of the user aggregate
387
- - `AgentProfile` - `agentProfile` section of the user aggregate
388
- - `TeamList` - Team data with full details (id, name, teamType, siteId, multiMediaProfileId, etc.)
389
- - `AuxCode` - Auxiliary code definition
390
- - `Entity` - Filtered code entity (used for idle/wrapup codes in Profile)
391
-
392
- **Organization Types:**
393
- - `OrgInfo` - Organization metadata
394
- - `OrgSettings` - Organization-level feature flags
395
- - `TenantData` - Tenant configuration and feature enablement
396
- - `SiteInfo` - Site-specific configuration
397
-
398
- **Communication Types:**
399
- - `DialPlanEntity` - Dial plan rule definition (includes `active`)
400
- - `OrgUrlMappings` - Keyed external service URL mappings
401
- - `MicrosoftConfig` / `WebexConfig` - Org-level presence configuration
402
- - `MultimediaProfile` - Multimedia profile configuration
403
-
404
- **Note:** The config service itself does not emit events. For agent and task events, see the Agent and Task services. Event constants are defined in [types.ts](../types.ts) under `CC_AGENT_EVENTS` and `CC_TASK_EVENTS`.
405
-
406
- ---
407
-
408
- ## Related Files
409
-
410
- - [index.ts](../index.ts) - Service implementation with all API methods
411
- - [types.ts](../types.ts) - Complete type definitions and event constants
412
- - [Util.ts](../Util.ts) - Profile parsing utilities (parseAgentConfigs, getFilterAuxCodes, etc.)
413
- - [constants.ts](../constants.ts) - API endpoints, default values, and method names