@webex/contact-center 3.12.0 → 3.13.0-next.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.repo-context.json +704 -0
- package/.sdd/manifest.json +1613 -0
- package/AGENTS.md +969 -0
- package/dist/cc.js +1102 -47
- package/dist/cc.js.map +1 -1
- package/dist/config.js +13 -0
- package/dist/config.js.map +1 -1
- package/dist/constants.js +46 -3
- package/dist/constants.js.map +1 -1
- package/dist/index.js +86 -17
- package/dist/index.js.map +1 -1
- package/dist/metrics/MetricsManager.js +16 -0
- package/dist/metrics/MetricsManager.js.map +1 -1
- package/dist/metrics/behavioral-events.js +211 -0
- package/dist/metrics/behavioral-events.js.map +1 -1
- package/dist/metrics/constants.js +58 -4
- package/dist/metrics/constants.js.map +1 -1
- package/dist/services/AddressBook.js +18 -15
- package/dist/services/AddressBook.js.map +1 -1
- package/dist/services/AnswerCallOnWebexService.js +202 -0
- package/dist/services/AnswerCallOnWebexService.js.map +1 -0
- package/dist/services/ApiAiAssistant.js +369 -14
- package/dist/services/ApiAiAssistant.js.map +1 -1
- package/dist/services/EntryPoint.js +46 -68
- package/dist/services/EntryPoint.js.map +1 -1
- package/dist/services/Queue.js +27 -22
- package/dist/services/Queue.js.map +1 -1
- package/dist/services/UserPreference.js +427 -0
- package/dist/services/UserPreference.js.map +1 -0
- package/dist/services/WebCallingService.js +287 -37
- package/dist/services/WebCallingService.js.map +1 -1
- package/dist/services/WebexCrossClientService.js +225 -0
- package/dist/services/WebexCrossClientService.js.map +1 -0
- package/dist/services/WxAppTelephonyMercurySync.js +111 -0
- package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
- package/dist/services/config/Util.js +48 -48
- package/dist/services/config/Util.js.map +1 -1
- package/dist/services/config/constants.js +57 -79
- package/dist/services/config/constants.js.map +1 -1
- package/dist/services/config/index.js +100 -226
- package/dist/services/config/index.js.map +1 -1
- package/dist/services/config/types.js +100 -40
- package/dist/services/config/types.js.map +1 -1
- package/dist/services/constants.js +19 -1
- package/dist/services/constants.js.map +1 -1
- package/dist/services/core/Err.js.map +1 -1
- package/dist/services/core/Utils.js +131 -32
- package/dist/services/core/Utils.js.map +1 -1
- package/dist/services/core/WebexRequest.js +6 -2
- package/dist/services/core/WebexRequest.js.map +1 -1
- package/dist/services/core/aqm-reqs.js +17 -11
- package/dist/services/core/aqm-reqs.js.map +1 -1
- package/dist/services/core/constants.js +9 -1
- package/dist/services/core/constants.js.map +1 -1
- package/dist/services/core/types.js.map +1 -1
- package/dist/services/core/websocket/WebSocketManager.js +26 -6
- package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
- package/dist/services/core/websocket/connection-service.js +3 -1
- package/dist/services/core/websocket/connection-service.js.map +1 -1
- package/dist/services/core/websocket/types.js.map +1 -1
- package/dist/services/index.js +6 -0
- package/dist/services/index.js.map +1 -1
- package/dist/services/task/Task.js +955 -0
- package/dist/services/task/Task.js.map +1 -0
- package/dist/services/task/TaskFactory.js +50 -0
- package/dist/services/task/TaskFactory.js.map +1 -0
- package/dist/services/task/TaskManager.js +1275 -504
- package/dist/services/task/TaskManager.js.map +1 -1
- package/dist/services/task/TaskUtils.js +221 -27
- package/dist/services/task/TaskUtils.js.map +1 -1
- package/dist/services/task/WebexCallingUtils.js +70 -0
- package/dist/services/task/WebexCallingUtils.js.map +1 -0
- package/dist/services/task/constants.js +22 -2
- package/dist/services/task/constants.js.map +1 -1
- package/dist/services/task/contact.js +29 -0
- package/dist/services/task/contact.js.map +1 -1
- package/dist/services/task/dialer.js +78 -0
- package/dist/services/task/dialer.js.map +1 -1
- package/dist/services/task/digital/Digital.js +78 -0
- package/dist/services/task/digital/Digital.js.map +1 -0
- package/dist/services/task/state-machine/TaskStateMachine.js +982 -0
- package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -0
- package/dist/services/task/state-machine/actions.js +572 -0
- package/dist/services/task/state-machine/actions.js.map +1 -0
- package/dist/services/task/state-machine/constants.js +161 -0
- package/dist/services/task/state-machine/constants.js.map +1 -0
- package/dist/services/task/state-machine/guards.js +379 -0
- package/dist/services/task/state-machine/guards.js.map +1 -0
- package/dist/services/task/state-machine/index.js +53 -0
- package/dist/services/task/state-machine/index.js.map +1 -0
- package/dist/services/task/state-machine/types.js +54 -0
- package/dist/services/task/state-machine/types.js.map +1 -0
- package/dist/services/task/state-machine/uiControlsComputer.js +703 -0
- package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -0
- package/dist/services/task/taskDataNormalizer.js +99 -0
- package/dist/services/task/taskDataNormalizer.js.map +1 -0
- package/dist/services/task/types.js +259 -5
- package/dist/services/task/types.js.map +1 -1
- package/dist/services/task/voice/Voice.js +1504 -0
- package/dist/services/task/voice/Voice.js.map +1 -0
- package/dist/services/task/voice/WebRTC.js +152 -0
- package/dist/services/task/voice/WebRTC.js.map +1 -0
- package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
- package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
- package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
- package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
- package/dist/services/wxAppDiagnosticLogging.js +159 -0
- package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
- package/dist/services/wxAppTelephonyUtils.js +19 -0
- package/dist/services/wxAppTelephonyUtils.js.map +1 -0
- package/dist/types/cc.d.ts +222 -10
- package/dist/types/config.d.ts +13 -0
- package/dist/types/constants.d.ts +40 -1
- package/dist/types/index.d.ts +58 -22
- package/dist/types/metrics/MetricsManager.d.ts +6 -0
- package/dist/types/metrics/constants.d.ts +52 -1
- package/dist/types/services/AddressBook.d.ts +2 -1
- package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
- package/dist/types/services/ApiAiAssistant.d.ts +67 -5
- package/dist/types/services/EntryPoint.d.ts +7 -5
- package/dist/types/services/Queue.d.ts +5 -3
- package/dist/types/services/UserPreference.d.ts +118 -0
- package/dist/types/services/WebexCrossClientService.d.ts +32 -0
- package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
- package/dist/types/services/config/Util.d.ts +4 -8
- package/dist/types/services/config/constants.d.ts +49 -76
- package/dist/types/services/config/index.d.ts +16 -64
- package/dist/types/services/config/types.d.ts +252 -114
- package/dist/types/services/constants.d.ts +16 -0
- package/dist/types/services/core/Err.d.ts +6 -0
- package/dist/types/services/core/Utils.d.ts +43 -13
- package/dist/types/services/core/WebexRequest.d.ts +1 -0
- package/dist/types/services/core/constants.d.ts +7 -0
- package/dist/types/services/core/types.d.ts +2 -0
- package/dist/types/services/core/websocket/WebSocketManager.d.ts +2 -0
- package/dist/types/services/core/websocket/types.d.ts +1 -1
- package/dist/types/services/index.d.ts +2 -0
- package/dist/types/services/task/Task.d.ts +186 -0
- package/dist/types/services/task/TaskFactory.d.ts +14 -0
- package/dist/types/services/task/TaskUtils.d.ts +54 -2
- package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
- package/dist/types/services/task/constants.d.ts +20 -0
- package/dist/types/services/task/contact.d.ts +4 -0
- package/dist/types/services/task/dialer.d.ts +30 -0
- package/dist/types/services/task/digital/Digital.d.ts +23 -0
- package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +1442 -0
- package/dist/types/services/task/state-machine/actions.d.ts +10 -0
- package/dist/types/services/task/state-machine/constants.d.ts +107 -0
- package/dist/types/services/task/state-machine/guards.d.ts +103 -0
- package/dist/types/services/task/state-machine/index.d.ts +13 -0
- package/dist/types/services/task/state-machine/types.d.ts +277 -0
- package/dist/types/services/task/state-machine/uiControlsComputer.d.ts +9 -0
- package/dist/types/services/task/taskDataNormalizer.d.ts +10 -0
- package/dist/types/services/task/types.d.ts +790 -66
- package/dist/types/services/task/voice/Voice.d.ts +241 -0
- package/dist/types/services/task/voice/WebRTC.d.ts +54 -0
- package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
- package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
- package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
- package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
- package/dist/types/types.d.ts +258 -11
- package/dist/types/utils/PageCache.d.ts +20 -3
- package/dist/types/webex.d.ts +1 -0
- package/dist/types.js +204 -6
- package/dist/types.js.map +1 -1
- package/dist/utils/PageCache.js +19 -5
- package/dist/utils/PageCache.js.map +1 -1
- package/dist/webex.js +22 -2
- package/dist/webex.js.map +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/docs/adr/0002-consult-transfer-list-policy.md +345 -0
- package/docs/adr/0003-repo-standards-migration.md +104 -0
- package/docs/adr/index.md +35 -0
- package/docs/architecture.md +460 -0
- package/docs/getting-started.md +142 -0
- package/docs/index.md +53 -0
- package/docs/specs/README.md +98 -0
- package/package.json +17 -12
- package/schemas/repo-context.schema.json +796 -0
- package/src/cc.ts +1439 -105
- package/src/config.ts +13 -0
- package/src/constants.ts +53 -1
- package/src/docs/README.md +727 -0
- package/src/index.ts +72 -16
- package/src/metrics/MetricsManager.ts +16 -0
- package/src/metrics/behavioral-events.ts +218 -0
- package/src/metrics/constants.ts +63 -4
- package/src/metrics/docs/README.md +710 -0
- package/src/services/AddressBook.ts +17 -6
- package/src/services/AnswerCallOnWebexService.ts +239 -0
- package/src/services/ApiAiAssistant.ts +494 -15
- package/src/services/EntryPoint.ts +59 -60
- package/src/services/Queue.ts +29 -12
- package/src/services/UserPreference.ts +509 -0
- package/src/services/WebCallingService.ts +362 -40
- package/src/services/WebexCrossClientService.ts +298 -0
- package/src/services/WxAppTelephonyMercurySync.ts +142 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/Util.ts +54 -84
- package/src/services/config/constants.ts +64 -86
- package/src/services/config/docs/README.md +530 -0
- package/src/services/config/index.ts +116 -277
- package/src/services/config/types.ts +238 -125
- package/src/services/constants.ts +18 -0
- package/src/services/core/Err.ts +3 -0
- package/src/services/core/Utils.ts +151 -37
- package/src/services/core/WebexRequest.ts +3 -1
- package/src/services/core/aqm-reqs.ts +18 -12
- package/src/services/core/constants.ts +8 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/core/types.ts +33 -1
- package/src/services/core/websocket/WebSocketManager.ts +37 -8
- package/src/services/core/websocket/connection-service.ts +5 -1
- package/src/services/core/websocket/types.ts +1 -1
- package/src/services/docs/README.md +765 -0
- package/src/services/index.ts +4 -0
- package/src/services/task/Task.ts +1211 -0
- package/src/services/task/TaskFactory.ts +82 -0
- package/src/services/task/TaskManager.ts +1551 -584
- package/src/services/task/TaskUtils.ts +316 -25
- package/src/services/task/WebexCallingUtils.ts +136 -0
- package/src/services/task/constants.ts +21 -0
- package/src/services/task/contact.ts +30 -0
- package/src/services/task/dialer.ts +80 -0
- package/src/services/task/digital/Digital.ts +102 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/TaskStateMachine.ts +1320 -0
- package/src/services/task/state-machine/actions.ts +741 -0
- package/src/services/task/state-machine/constants.ts +172 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/services/task/state-machine/guards.ts +442 -0
- package/src/services/task/state-machine/index.ts +28 -0
- package/src/services/task/state-machine/types.ts +258 -0
- package/src/services/task/state-machine/uiControlsComputer.ts +1135 -0
- package/src/services/task/taskDataNormalizer.ts +137 -0
- package/src/services/task/types.ts +974 -70
- package/src/services/task/voice/Voice.ts +1878 -0
- package/src/services/task/voice/WebRTC.ts +194 -0
- package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
- package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
- package/src/services/wxAppDiagnosticLogging.ts +286 -0
- package/src/services/wxAppTelephonyUtils.ts +14 -0
- package/src/types.ts +323 -13
- package/src/utils/AGENTS.md +291 -0
- package/src/utils/PageCache.ts +38 -5
- package/src/utils/docs/README.md +413 -0
- package/src/webex.js +10 -0
- package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
- package/test/unit/spec/cc.ts +4046 -181
- package/test/unit/spec/index.ts +891 -0
- package/test/unit/spec/logger-proxy.ts +70 -0
- package/test/unit/spec/metrics/MetricsManager.ts +25 -0
- package/test/unit/spec/metrics/behavioral-events.ts +60 -0
- package/test/unit/spec/services/AddressBook.ts +37 -6
- package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
- package/test/unit/spec/services/ApiAiAssistant.ts +442 -23
- package/test/unit/spec/services/EntryPoint.ts +87 -40
- package/test/unit/spec/services/Queue.ts +123 -12
- package/test/unit/spec/services/UserPreference.ts +401 -0
- package/test/unit/spec/services/WebCallingService.ts +484 -49
- package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
- package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
- package/test/unit/spec/services/config/Util.ts +501 -0
- package/test/unit/spec/services/config/index.ts +318 -548
- package/test/unit/spec/services/core/Utils.ts +447 -8
- package/test/unit/spec/services/core/WebexRequest.ts +8 -7
- package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
- package/test/unit/spec/services/core/websocket/WebSocketManager.ts +132 -56
- package/test/unit/spec/services/core/websocket/connection-service.ts +3 -1
- package/test/unit/spec/services/task/AutoWrapup.ts +63 -0
- package/test/unit/spec/services/task/Task.ts +2723 -0
- package/test/unit/spec/services/task/TaskFactory.ts +116 -0
- package/test/unit/spec/services/task/TaskManager.ts +4800 -1586
- package/test/unit/spec/services/task/TaskUtils.ts +307 -0
- package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
- package/test/unit/spec/services/task/contact.ts +33 -0
- package/test/unit/spec/services/task/dialer.ts +190 -0
- package/test/unit/spec/services/task/digital/Digital.ts +105 -0
- package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +4060 -0
- package/test/unit/spec/services/task/state-machine/guards.ts +839 -0
- package/test/unit/spec/services/task/state-machine/types.ts +18 -0
- package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +3101 -0
- package/test/unit/spec/services/task/taskTestUtils.ts +87 -0
- package/test/unit/spec/services/task/voice/Voice.ts +2355 -0
- package/test/unit/spec/services/task/voice/WebRTC.ts +235 -0
- package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
- package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
- package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
- package/test/unit/spec/wellnessSampleUtils.ts +288 -0
- package/typedoc.md +1 -1
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
- package/dist/services/task/index.js +0 -1525
- package/dist/services/task/index.js.map +0 -1
- package/dist/types/services/task/index.d.ts +0 -650
- package/src/services/task/index.ts +0 -1801
- package/test/unit/spec/services/task/index.ts +0 -2184
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: ADR
|
|
3
|
+
title: ADR-0002 - Consult and transfer list policy
|
|
4
|
+
description: The SDK owns the default consult and transfer destination policy (eligibility, request shaping, backend ordering, cache safety, and Task destination controls) on its existing list and transfer methods.
|
|
5
|
+
tags: [adr]
|
|
6
|
+
timestamp: 2026-08-19T00:00:00Z
|
|
7
|
+
status: accepted
|
|
8
|
+
---
|
|
9
|
+
<!-- sdd-generated-metadata
|
|
10
|
+
doc_kind: standing-doc
|
|
11
|
+
generated_from: adr@0.3.0
|
|
12
|
+
generated_by: claude-code
|
|
13
|
+
approved_by: rarajes2@cisco.com
|
|
14
|
+
updated_at: 2026-11-17T03:03:58Z
|
|
15
|
+
validation_status: pass-with-warnings
|
|
16
|
+
-->
|
|
17
|
+
|
|
18
|
+
# ADR-0002 - Consult and transfer list policy
|
|
19
|
+
|
|
20
|
+
| Field | Value |
|
|
21
|
+
| ------------- | ----- |
|
|
22
|
+
| Status | Accepted |
|
|
23
|
+
| Decision date | 2026-08-19 |
|
|
24
|
+
| Deciders | Contact Center SDK maintainers (developer-approved, 2026-08-19) |
|
|
25
|
+
| Supersedes | N/A |
|
|
26
|
+
| Superseded by | N/A |
|
|
27
|
+
|
|
28
|
+
Related context: [package architecture](../architecture.md) · [specification registry](../specs/README.md) ·
|
|
29
|
+
[package agent instructions](../../AGENTS.md) · [ADR index](index.md)
|
|
30
|
+
|
|
31
|
+
## Context
|
|
32
|
+
|
|
33
|
+
This document owns the reusable consult/transfer destination-list policy. The SDK applies default telephony eligibility, ordering, profile views, and cache safety through the existing list methods; consumers use compatible existing parameters only when they need a different filter or sort.
|
|
34
|
+
|
|
35
|
+
This decision was raised as feature key `CAI-8354`, work type Defect, change class Contract, from a
|
|
36
|
+
developer-approved consult/transfer behavior review; the paired change in the Webex widgets repository
|
|
37
|
+
consumes it.
|
|
38
|
+
|
|
39
|
+
Consult/transfer list decisions were split across the SDK and widgets. Generic SDK query types exposed low-level request choices, while widgets always restricted buddy agents to Available, filtered queues after fetching them, rebuilt pagination metadata, and could independently affect presentation order. That produced inconsistent behavior between consumers.
|
|
40
|
+
|
|
41
|
+
The goal is to make the SDK the single owner of the default consult/transfer policy without adding parallel list methods or response signatures. The existing Queue method returns eligible full records, while the existing EntryPoint method maps profile-scoped dial-number rows to the established response wrapper. Queue, EntryPoint, and AddressBook request backend ordering, buddy-agent behavior is action-aware, CMS sort syntax is serialized correctly, and query variants that change results cannot reuse an incompatible cached page. Consumers render the response order and metadata without a second sort or filter.
|
|
42
|
+
|
|
43
|
+
### Defect context
|
|
44
|
+
|
|
45
|
+
- Observed versus expected behavior: widgets and SDK callers could construct different destination requests, the services serialized sort with keys the CMS list API does not consume, and cache eligibility ignored view/shape flags; expected behavior is one SDK-owned default policy and unchanged backend response order.
|
|
46
|
+
- Reproduction and environment: issue Consult and Transfer destination requests for the same task media and compare query parameters and results across SDK consumers.
|
|
47
|
+
- Regression range or last known good state: unknown; the existing APIs and older query serialization predate the corrected defaults.
|
|
48
|
+
- Severity, frequency, and workaround: user-visible whenever eligibility/order differs; consumers could manually duplicate flags, but that perpetuates the ownership defect.
|
|
49
|
+
- Diagnostic evidence: `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts`, `src/utils/PageCache.ts`.
|
|
50
|
+
|
|
51
|
+
### Stakeholders
|
|
52
|
+
|
|
53
|
+
| Stakeholder | Need or decision | Status |
|
|
54
|
+
| --- | --- | --- |
|
|
55
|
+
| Contact Center agents | Destination eligibility and order are consistent across consumers. | Decided |
|
|
56
|
+
| SDK consumers | Reusable defaults without duplicating backend query knowledge. | Decided |
|
|
57
|
+
| Widget maintainers | Thin calls that pass only UI/runtime context. | Decided in the paired widgets delta |
|
|
58
|
+
| SDK maintainers | Existing list APIs remain the only queue and entry-point public methods; existing parameters provide overrides. | Decided |
|
|
59
|
+
|
|
60
|
+
There are no open product decisions for this delta.
|
|
61
|
+
|
|
62
|
+
### Prior work and evidence
|
|
63
|
+
|
|
64
|
+
| Source | What it establishes | Decision or disposition |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| `src/cc.ts` | The public façade keeps the established list method names/signatures and owns buddy-agent action policy. | Used |
|
|
67
|
+
| `src/types.ts`, `src/index.ts` | Existing queue/entry-point request and response types remain the public list contracts; entry-point rows expose the mapped dialled number as optional `number`. | Used |
|
|
68
|
+
| `src/services/Queue.ts` | The existing Queue path owns default query serialization and view flags. | Used |
|
|
69
|
+
| `src/services/EntryPoint.ts` | The existing EntryPoint path owns the desktop-profile dial-number query, field mapping, and backend ordering. | Used |
|
|
70
|
+
| `src/services/core/WebexRequest.ts` | The shared request wrapper forwards optional per-request headers needed by the dial-number endpoint while leaving other requests unchanged. | Used |
|
|
71
|
+
| `src/services/AddressBook.ts` | AddressBook owns its backend ordering default and caller override. | Used |
|
|
72
|
+
| `src/utils/PageCache.ts` | Cache eligibility must include every result- or shape-changing query option. | Used |
|
|
73
|
+
| `test/unit/spec/cc.ts` | Action mapping and thin delegation through the existing list methods are asserted. | Used |
|
|
74
|
+
| `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` | Default policy, existing-parameter overrides, CMS sort serialization, view flags, and cache behavior are asserted. | Used |
|
|
75
|
+
| `src/services/task/state-machine/uiControlsComputer.ts`, `src/services/task/types.ts` | Task UI controls are the existing SDK-owned decision surface and can carry ordered destination availability. | Used |
|
|
76
|
+
| `test/unit/spec/services/task/state-machine/uiControlsComputer.ts`, `test/unit/spec/services/task/TaskFactory.ts` | Profile/media/direction gating, outbound flag path, ordering, and factory propagation are asserted. | Used |
|
|
77
|
+
| `src/services/task/Task.ts`, `src/services/task/constants.ts`, `test/unit/spec/services/task/Task.ts` | Direct entry-point transfer routing is translated to the backend EPDN value and sent through the vteam transfer path. | Used |
|
|
78
|
+
| The workspace sample docs/samples/contact-center/app.js (outside this package) | The sample renders buddy-agent state labels and mapped entry-point numbers while using the existing list methods and Task destination controls. | Used |
|
|
79
|
+
|
|
80
|
+
## Decision
|
|
81
|
+
|
|
82
|
+
The SDK is the single owner of the default consult/transfer destination policy, applied through the
|
|
83
|
+
existing `getBuddyAgents`, `getQueues`, `getEntryPoints`, AddressBook, and `Task.transfer()` surfaces
|
|
84
|
+
and through `TaskUIControls.consultTransferDestinations`.
|
|
85
|
+
|
|
86
|
+
**In scope:**
|
|
87
|
+
|
|
88
|
+
- Put consult/transfer defaults on the existing queue and entry-point list methods.
|
|
89
|
+
- Map Consult versus Transfer to the correct buddy-agent state behavior.
|
|
90
|
+
- Default omitted buddy-agent and queue media context to telephony.
|
|
91
|
+
- Retain the existing queue/entry-point parameter and response wrappers; keep full Queue records, map EntryPoint dial-number rows to truthful `EntryPointRecord` fields, and retain compatible filter/sort overrides without exposing the fixed entry-point profile-scoping flag.
|
|
92
|
+
- Default EntryPoint requests to backend `entryPointName,ASC` and AddressBook requests to `name,ASC` while allowing callers to pass another `sortBy`/`sortOrder` pair.
|
|
93
|
+
- Serialize CMS ordering as `sort=FIELD,ORDER` (for example `sort=name,ASC`).
|
|
94
|
+
- Bypass the base pagination cache for every filter/view/shape flag that changes a result.
|
|
95
|
+
- Keep the existing queue and entry-point method signatures and preserve explicit buddy-agent state callers.
|
|
96
|
+
- Compute ordered, action-specific destination availability once on each Task and expose it through `TaskUIControls`, using Desktop Profile access, media, direction, and outbound queue-transfer capability.
|
|
97
|
+
- Keep direct Entry Point available for eligible voice transfers and translate its public destination type to the backend EPDN value inside `Task.transfer()`.
|
|
98
|
+
|
|
99
|
+
**Out of scope:**
|
|
100
|
+
|
|
101
|
+
- Client-side sorting of agents, queues, or entry points.
|
|
102
|
+
- Changing backend order after a response is received.
|
|
103
|
+
- Adding parallel queue/entry-point APIs or projected destination response types.
|
|
104
|
+
- Changing generic queue ordering, address-book projection, events, authentication, retries, or metrics taxonomy.
|
|
105
|
+
- Adding a feature flag, data migration, commit, publication, or push.
|
|
106
|
+
- Adding a separate destination-policy fetch method that Task consumers must call before rendering.
|
|
107
|
+
|
|
108
|
+
### Decision rules and owning requirements
|
|
109
|
+
|
|
110
|
+
Each decision rule keeps its `SDK-LIST-R-*` identifier; the behavior is specified by the module
|
|
111
|
+
requirement it links, which is authoritative.
|
|
112
|
+
|
|
113
|
+
| Decision rule | Rule | Owning module requirement | Test evidence |
|
|
114
|
+
| --- | --- | --- | --- |
|
|
115
|
+
| `SDK-LIST-R-001` | `getQueues` defaults to inbound, active, telephony queues in backend `name,ASC` order with the desktop-profile, agent, and first-level views; optional fields set to `undefined` keep the defaults, while explicit `false` and an explicit empty filter override them | [SERVICES-R-007](../../src/services/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/cc.ts` |
|
|
116
|
+
| `SDK-LIST-R-002` | `getEntryPoints` maps profile-scoped `/v3/dial-number` rows to `{id, name, number?}` in backend `entryPointName,ASC` order | [SERVICES-R-007](../../src/services/docs/README.md) | `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/core/WebexRequest.ts` |
|
|
117
|
+
| `SDK-LIST-R-003` | Buddy agents: Transfer adds `Available`, Consult sends no state, media defaults to telephony, an explicit `state` wins | [AGENT-R-009](../../src/services/agent/docs/README.md) | `test/unit/spec/cc.ts` |
|
|
118
|
+
| `SDK-LIST-R-004` | Existing parameters (buddy-agent `state`, queue, entry-point, and address-book filters and sorts) override the defaults | [SERVICES-R-007](../../src/services/docs/README.md), [SERVICES-R-016](../../src/services/docs/README.md), [AGENT-R-009](../../src/services/agent/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`, `test/unit/spec/services/AddressBook.ts` |
|
|
119
|
+
| `SDK-LIST-R-005` | Ordering is sent as one combined CMS `sort` value, never as separate `sortBy`/`sortOrder` keys | [SERVICES-R-007](../../src/services/docs/README.md), [SERVICES-R-016](../../src/services/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/AddressBook.ts` |
|
|
120
|
+
| `SDK-LIST-R-006` | Only simple pagination may use the page cache | [UTILS-R-001](../../src/utils/docs/README.md) | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/AddressBook.ts` |
|
|
121
|
+
| `SDK-LIST-R-007` | No JavaScript sort or reorder of list responses | This ADR, Constraint on future changes | `test/unit/spec/services/EntryPoint.ts` |
|
|
122
|
+
| `SDK-LIST-R-008` | Typing stays on `BuddyAgents`, `TaskUIControls`, and `EntryPointRecord` (optional `number`) with no one-off aliases | [CONTACT_CENTER-R-003](../../src/docs/README.md), [TASK_STATE_MACHINE-R-004](../../src/services/task/state-machine/docs/README.md) | `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` |
|
|
123
|
+
| `SDK-LIST-R-009` | Failures reject with the existing measured and logged errors; no synthetic list | This ADR, Failure behavior | `test/unit/spec/cc.ts` |
|
|
124
|
+
| `SDK-LIST-R-010` | AddressBook defaults to `name,ASC` and accepts caller sorts | [SERVICES-R-016](../../src/services/docs/README.md) | `test/unit/spec/services/AddressBook.ts` |
|
|
125
|
+
| `SDK-LIST-R-011` | Non-default queue media goes through the existing `filter` parameter; the SDK never interpolates a media string | [SERVICES-R-007](../../src/services/docs/README.md) | `test/unit/spec/services/Queue.ts` |
|
|
126
|
+
| `SDK-LIST-R-012` | Every Task exposes ordered `consult` and `transfer` destination arrays | [TASK-R-009](../../src/services/task/docs/README.md), [TASK_STATE_MACHINE-R-004](../../src/services/task/state-machine/docs/README.md) | `test/unit/spec/services/task/TaskFactory.ts`, `test/unit/spec/services/task/state-machine/uiControlsComputer.ts` |
|
|
127
|
+
| `SDK-LIST-R-013` | `Task.transfer()` sends a public `entryPoint` destination as `entrypointDialNumber` through `vteamTransfer` | [Task spec](../../src/services/task/docs/README.md) `transfer` | `test/unit/spec/services/task/Task.ts` |
|
|
128
|
+
| `SDK-LIST-R-014` | The Contact Center sample treats a present empty destination array as no destinations | This ADR (the sample is outside the package) | Manual sample flow |
|
|
129
|
+
|
|
130
|
+
### Contract changes
|
|
131
|
+
|
|
132
|
+
| API or operation | Change | Consumer impact | Compatibility expectation | Canonical definition |
|
|
133
|
+
| --- | --- | --- | --- | --- |
|
|
134
|
+
| Buddy-agent input | Add optional `action` to the existing options object and make `mediaType` optional with a telephony default. | Consumers may pass Consult/Transfer instead of choosing state. | Additive public option; explicit-state callers remain supported and take precedence. | `src/types.ts` |
|
|
135
|
+
| Existing queue list | Apply the telephony filter, profile views, and `name,ASC` by default. | Thin clients call `getQueues`; other consumers use existing parameters for overrides. | Intentional default correction; method and response signature unchanged. | `src/cc.ts`, `src/services/Queue.ts` |
|
|
136
|
+
| Existing entry-point list | Fetch desktop-profile `/v3/dial-number` mappings with the required organization/internal-data headers, request entry-point names, map fields row-for-row, and use `entryPointName,ASC` by default. | Thin clients call `getEntryPoints` and receive the displayed number without joining another endpoint. | Intentional default correction; method and response wrapper unchanged. | `src/cc.ts`, `src/services/EntryPoint.ts`, `src/services/config/constants.ts`, `src/services/core/WebexRequest.ts` |
|
|
137
|
+
| `EntryPointRecord` | Add optional mapped `number`; make configuration-only `type`, `isActive`, and `orgId` optional for truthful mapped-list typing. | Consumers can render the dialled number without a cast and cannot assume absent configuration fields. | Additive field with a type-correctness adjustment; no new response wrapper. | `src/types.ts` |
|
|
138
|
+
| Task destination controls | Add ordered `consultTransferDestinations.consult` and `.transfer` arrays to `TaskUIControls`. | Task consumers render availability directly; no separate policy call or raw profile injection is needed. | Additive public field using the existing destination values; no new standalone public alias. | `src/services/task/types.ts`, `src/services/task/state-machine/uiControlsComputer.ts`, `src/index.ts` |
|
|
139
|
+
| Existing `Task.transfer` entry-point input | Correct internal transport and backend destination translation. | Consumers keep passing `{to, destinationType: 'entryPoint'}` from the Task control array. | Behavioral bug fix; no method or public payload signature change. | `src/services/task/Task.ts`, `src/services/task/constants.ts` |
|
|
140
|
+
|
|
141
|
+
**Provides — MODIFIED:** The package keeps the existing queue, entry-point, buddy-agent, and Task transfer methods. Queue retains its established request/full-response signature and telephony defaults; EntryPoint retains its request/response wrapper while mapping desktop-profile dial-number rows to typed `{id, name, number?}` records in backend order; buddy agents accept action-aware input through `BuddyAgents`; `TaskUIControls` exposes inline ordered action-specific destination availability; direct entry-point transfer uses SDK-owned EPDN/vteam translation without changing the public payload.
|
|
142
|
+
|
|
143
|
+
**Requires — MODIFIED:** Queue, EntryPoint, and AddressBook services require CMS list endpoints to honor the combined sort value. Queue requires its profile/agent/first-level views; EntryPoint requires `/v3/dial-number` to honor the organization/internal-data headers, desktop-profile filtering, `includeEntryPointName`, and mapping attributes. Direct entry-point transfer requires the WCC vteam transfer operation to accept the established `entrypointDialNumber` destination and selected entry-point identifier. The SDK continues to rely on host-authenticated Webex requests and backend response ordering.
|
|
144
|
+
|
|
145
|
+
No event contract changes.
|
|
146
|
+
|
|
147
|
+
| Entity or payload | Requested field or shape | Purpose | Ownership | Privacy, retention, or compatibility constraint |
|
|
148
|
+
| --- | --- | --- | --- | --- |
|
|
149
|
+
| Buddy-agent input | Existing options object with optional `action`, `mediaType`, and explicit `state`; explicit state takes precedence | Derive Consult/Transfer eligibility without a parallel public input type. | SDK public type | No credential or persistent data. |
|
|
150
|
+
| Queue search input | Existing page, page size, search, filter, sort, and profile parameters | Consumer-controlled pagination plus optional default overrides. | Existing SDK public type | No second media-bearing request type. |
|
|
151
|
+
| Queue backend query | Default inbound/active/telephony filter, name ascending, desktop-profile/agent/first-level views, and no field projection | Full queue result using the default list policy. | Queue service | Fixed filter/views bypass simple-page caching. |
|
|
152
|
+
| Entry-point backend query | `/v3/dial-number`, `X-ORGANIZATION-ID`, `x-ignore-internal-data=false`, `desktopProfileFilter=true`, `includeEntryPointName=true`, required mapping attributes, and `entryPointName,ASC` | Return profile-scoped EP-DN rows with the visible dialled number. | EntryPoint service and shared WebexRequest wrapper | The service does not use PageCache for these profile-scoped requests. |
|
|
153
|
+
| Entry-point response row | `id=entryPointId`, `name=entryPointName`, optional `number=dialledNumber` | Let consumers route by entry-point ID and display the mapped dialled number without a cast or second request. | `EntryPointRecord` public type | Mapping preserves response order and pagination metadata. |
|
|
154
|
+
| Direct entry-point transfer payload | Caller-selected `to`; public `entryPoint` translated internally to `entrypointDialNumber` | Invoke the supported vteam transfer operation without consumer-side backend knowledge. | Task service | Translation is transport-only; metrics retain the caller-facing destination type and no new public field is required. |
|
|
155
|
+
| AddressBook backend query | Existing caller-selected fields plus name ascending by default | Backend-ordered dial numbers without a specialized façade. | AddressBook service | A non-default sort bypasses the default-order cache. |
|
|
156
|
+
|
|
157
|
+
### Scenarios and interactions
|
|
158
|
+
|
|
159
|
+
| Scenario | Actor | Preconditions | Expected behavior | Failure or boundary behavior | Requirements |
|
|
160
|
+
| --- | --- | --- | --- | --- | --- |
|
|
161
|
+
| Consult buddy agents | SDK consumer | `action=Consult` | Telephony defaults when absent; state is omitted; backend order is preserved. | Request rejection is measured/logged and rethrown; applying the Transfer-only `Available` filter is invalid. | `SDK-LIST-R-003`, `SDK-LIST-R-007` |
|
|
162
|
+
| Transfer buddy agents | SDK consumer | `action=Transfer` | State `Available` is sent for the selected media. | An explicit `state` takes precedence over `action` when both are supplied; an omitted state filter would return idle agents. | `SDK-LIST-R-003`, `SDK-LIST-R-008` |
|
|
163
|
+
| Queue list | SDK consumer | Existing method called with page/search and optional filter override | SDK applies the default telephony policy and returns full records unchanged; an explicit existing filter overrides eligibility, for example `channelType==SOCIAL_CHANNEL`. | HTTP failure is propagated without a synthetic page; repeated view-filtered calls reach the backend, never a simple-page cache hit; no second media-bearing method signature. | `SDK-LIST-R-001`, `SDK-LIST-R-006`, `SDK-LIST-R-007`, `SDK-LIST-R-011` |
|
|
164
|
+
| Entry-point list | SDK consumer | Existing method called with page/search and optional compatible overrides | SDK fetches desktop-profile dial-number mappings with backend `sort=entryPointName,ASC`, preserves backend order/meta, and returns `{id, name, number?}` rows through `EntryPointListResponse`. | HTTP failure is propagated without a synthetic page; the widget neither sorts nor requests the mapping itself. | `SDK-LIST-R-002`, `SDK-LIST-R-007`, `SDK-LIST-R-008`, `SDK-LIST-R-009` |
|
|
165
|
+
| Dial-number list | SDK consumer | AddressBook page/search supplied | AddressBook applies backend `name,ASC` by default and returns the response unchanged. | A custom sort overrides the default and bypasses the default-order cache; the consumer never has to supply the default itself. | `SDK-LIST-R-010` |
|
|
166
|
+
| Specialized list consumer | SDK consumer | Uses an existing list method with explicit parameters | Explicit filter/sort/profile inputs override defaults; the backend receives the requested field/order and returns arrays and metadata in backend order. | No parallel consult/transfer method or projected response type is required; the SDK never overwrites the caller's explicit behavior or applies a JavaScript `.sort()`. | `SDK-LIST-R-004`, `SDK-LIST-R-005`, `SDK-LIST-R-007` |
|
|
167
|
+
| Direct entry-point transfer | SDK consumer | Voice Task exposes Entry Point in the Transfer destination array | `Task.transfer({to, destinationType: 'entryPoint'})` sends `{to, destinationType: 'entrypointDialNumber'}` through `vteamTransfer`. | Vteam rejection is measured and rethrown; `blindTransfer` is not invoked and the category is not hidden. | `SDK-LIST-R-012`, `SDK-LIST-R-013` |
|
|
168
|
+
| Sample receives an empty destination array | Sample user | Task exposes the requested action with `[]` | Destination selector is cleared and disabled. | Missing/undefined destination controls use the sample's compatibility defaults; legacy defaults never replace an explicit empty array. | `SDK-LIST-R-014` |
|
|
169
|
+
|
|
170
|
+
### Failure behavior
|
|
171
|
+
|
|
172
|
+
| Failure | SDK behavior | Consumer-visible result | Evidence |
|
|
173
|
+
| --- | --- | --- | --- |
|
|
174
|
+
| Buddy-agent AQM rejection | Record failure context and rethrow. | Promise rejects; no synthetic agent list. | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
175
|
+
| Queue HTTP rejection | Service metrics/logging remain active and the error propagates. | Promise rejects; no synthetic paginated result. | `src/services/Queue.ts`, `test/unit/spec/services/Queue.ts` |
|
|
176
|
+
| Entry-point HTTP rejection | Service metrics/logging remain active and the error propagates. | Promise rejects; no synthetic paginated result. | `src/services/EntryPoint.ts`, `test/unit/spec/services/EntryPoint.ts` |
|
|
177
|
+
| Missing action-based media | Default to telephony. | Valid request with predictable channel. | `src/cc.ts`, `test/unit/spec/cc.ts` |
|
|
178
|
+
| Non-default queue media eligibility | Consumer supplies a complete allowlisted RSQL value through the existing `filter` field; the SDK performs no media-string interpolation. | Existing queue method returns matching records or propagates the backend error. | `src/services/Queue.ts`, service tests |
|
|
179
|
+
| Direct entry-point vteam transfer rejection | Preserve existing Task transfer error normalization, failure metrics, and rethrow semantics. | `Task.transfer()` rejects; no fallback blind-transfer request is made. | `src/services/task/Task.ts`, `test/unit/spec/services/task/Task.ts` |
|
|
180
|
+
|
|
181
|
+
- Existing methods make one delegated list request and add no retry or request fan-out.
|
|
182
|
+
- Queue, EntryPoint, and AddressBook callers use compatible explicit existing parameters when they require non-default behavior.
|
|
183
|
+
- View/filter/shape queries bypass cache rather than risk stale or cross-policy results.
|
|
184
|
+
- Errors remain caller-visible; the SDK does not manufacture an empty success response.
|
|
185
|
+
|
|
186
|
+
## Why
|
|
187
|
+
|
|
188
|
+
Backend-requested order and one SDK-owned eligibility decision reach every consumer unchanged, while
|
|
189
|
+
consumers with another need keep an explicit override through the parameters the methods already
|
|
190
|
+
accept. The decision log records the rationale for each step of the decision:
|
|
191
|
+
|
|
192
|
+
| Date | Decision or change | Rationale | Owner |
|
|
193
|
+
| --- | --- | --- | --- |
|
|
194
|
+
| 2026-08-21 | Replaced provisional `dbId` with typed `EntryPointRecord.number` populated from the backend `/v3/dial-number` mapping, and kept the existing `getEntryPoints` method/response wrapper. | Runtime testing showed no `dbId`; the dialled number belongs to the EP-DN mapping, and consumers should not join or reinterpret backend data. | Developer + Codex |
|
|
195
|
+
| 2026-08-21 | Made Queue defaults resilient to optional properties explicitly set to `undefined`, retained explicit false/empty overrides, and made the sample honor a present empty destination array. | Common object-building patterns must not silently disable safe SDK defaults, and an explicit Task policy decision must not be replaced by sample fallback categories. | Developer + Codex |
|
|
196
|
+
| 2026-08-20 | Kept Entry Point available for eligible voice transfers and corrected `Task.transfer()` to use vteam routing with internal `entrypointDialNumber` translation. | The backend transfer policy supports direct entry-point transfer; hiding it would remove valid functionality, while consumers should not know the backend EPDN literal. | Developer + Codex |
|
|
197
|
+
| 2026-08-19 | Kept action/media typing inside `BuddyAgents`, inlined the destination arrays on `TaskUIControls`, removed the new root aliases, and removed `dbId` additions from queue/entry-point records. | The established methods and types already express the required behavior; consumers do not need standalone aliases or an unused record field. | Developer + Codex |
|
|
198
|
+
| 2026-08-19 | Assigned all reusable eligibility, query, ordering, and cache decisions to the SDK. | Keep widgets thin and prevent cross-consumer behavior drift. | Developer + Codex |
|
|
199
|
+
| 2026-08-19 | Made backend response order authoritative and prohibited SDK-side JavaScript sorting. | One backend ordering decision must reach every consumer unchanged. | Developer + Codex |
|
|
200
|
+
| 2026-08-19 | Moved EntryPoint and AddressBook `name,ASC` ordering to service defaults and removed the specialized dial-number façade. | Widgets must work without supplying SDK-owned decisions; other consumers can pass explicit sort overrides. | Developer + Codex |
|
|
201
|
+
| 2026-08-19 | Removed the specialized queue/entry-point methods and destination response/options types and kept default policy on existing `getQueues`/`getEntryPoints` with existing overrides. | Consumers should keep established method signatures; a parallel list abstraction adds needless public surface and projection complexity. The later EP-DN correction retained the response wrapper while mapping truthful fields. | Developer + Codex |
|
|
202
|
+
| 2026-08-19 | Put ordered Consult/Transfer destination availability directly on every Task's `uiControls` instead of adding `getConsultTransferDestinationPolicy`. | The Task already owns UI decisions and live interaction data, so consumers should not make a second request or reproduce profile/media/direction rules. | Developer + Codex |
|
|
203
|
+
|
|
204
|
+
## Alternatives considered
|
|
205
|
+
|
|
206
|
+
| Alternative | Why it was not selected |
|
|
207
|
+
| ----------- | ----------------------- |
|
|
208
|
+
| Keep consult/transfer filtering, pagination rebuilding, and ordering in the widgets | It is the defect being fixed; see the 2026-08-19 log row that assigns the decisions to the SDK |
|
|
209
|
+
| Add specialized queue and entry-point methods with projected destination types | See the 2026-08-19 log row that removed them |
|
|
210
|
+
| Sort agents, queues, or entry points in JavaScript | See the 2026-08-19 log row that made backend order authoritative |
|
|
211
|
+
| Add `getConsultTransferDestinationPolicy` | See the 2026-08-19 log row that put the destinations on `uiControls` |
|
|
212
|
+
| Expose a provisional `EntryPointRecord.dbId` | See the 2026-08-21 log row that introduced `number` |
|
|
213
|
+
| Hide Entry Point from voice Transfer controls | See the 2026-08-20 log row on entry-point transfer |
|
|
214
|
+
|
|
215
|
+
## Consequences
|
|
216
|
+
|
|
217
|
+
**Positive:**
|
|
218
|
+
|
|
219
|
+
- Consumers call the existing list methods and read `uiControls.consultTransferDestinations` without
|
|
220
|
+
reproducing profile, media, direction, eligibility, or ordering rules.
|
|
221
|
+
- Query variants can no longer reuse a cached page created under a different view.
|
|
222
|
+
- Direct entry-point transfer works from the Task control array without consumer-side backend values.
|
|
223
|
+
|
|
224
|
+
**Negative / tradeoffs:**
|
|
225
|
+
|
|
226
|
+
- The default request behavior of `getQueues`, `getEntryPoints`, and the AddressBook list changed
|
|
227
|
+
without a signature change, so generic callers needing the old behavior must pass explicit overrides.
|
|
228
|
+
- Default Queue calls always bypass the simple-page cache, and profile-scoped EntryPoint requests are
|
|
229
|
+
never cached, so repeated calls reach the backend.
|
|
230
|
+
|
|
231
|
+
### Public API and semver impact
|
|
232
|
+
|
|
233
|
+
| Export or entry point | Change | Affected consumers | Required version change | Deprecation or migration |
|
|
234
|
+
| --- | --- | --- | --- | --- |
|
|
235
|
+
| Existing `getQueues` / `getEntryPoints` | Default request behavior changes; signatures do not | Widgets and other SDK consumers | Behavioral semver review | Pass compatible existing filters/sorts when different behavior is required; entry-point profile scoping remains SDK-owned. |
|
|
236
|
+
| `BuddyAgents` | Add optional action-based defaults to the existing options object while retaining explicit state | Existing and new consumers | Minor | Existing explicit-state calls remain valid and override action defaults. |
|
|
237
|
+
| `TaskUIControls` | Add inline ordered, action-specific destination availability using existing destination values | Task UI consumers | Minor | Read the matching action array; first item is the default category. |
|
|
238
|
+
| `Task.transfer` | Route the existing public `entryPoint` value through vteam transfer as backend `entrypointDialNumber` | Existing voice-task consumers | Patch/behavioral correction | No caller migration; backend translation is SDK-owned. |
|
|
239
|
+
| `EntryPointRecord` | Add optional mapped `number`; configuration-only fields become optional | Entry-point list consumers | Behavioral/type-contract review | Render `number` when present and handle configuration-only fields as optional. |
|
|
240
|
+
|
|
241
|
+
### Cross-package impact
|
|
242
|
+
|
|
243
|
+
| Package | Change | Dependency direction | Release sequencing | Owner |
|
|
244
|
+
| --- | --- | --- | --- | --- |
|
|
245
|
+
| `@webex/contact-center` | Owns action/default/filter/order/cache policy and Task destination visibility/order decisions. | SDK → consumers | Build/release first. | SDK maintainers |
|
|
246
|
+
| `@webex/cc-store` | Delegates entry points directly to the existing SDK method; uses the existing queue `filter` parameter only for a non-telephony active task. | store → SDK | Consume a compatible SDK release. | Widgets maintainers |
|
|
247
|
+
| `@webex/cc-task` and `@webex/cc-components` | Supply action and render results. | UI → store → SDK | Release after compatible store/SDK. | Widgets maintainers |
|
|
248
|
+
|
|
249
|
+
| Repository or module | Impact | Owner |
|
|
250
|
+
| --- | --- | --- |
|
|
251
|
+
| `src` | Public façade and exports | SDK maintainers |
|
|
252
|
+
| `src/services` | Queue/EntryPoint/AddressBook wire query construction | SDK maintainers |
|
|
253
|
+
| `src/services/agent` | Existing correlated buddy-agent operation receives façade-derived state | SDK maintainers |
|
|
254
|
+
| `src/services/task` | Direct entry-point transfer dispatch and backend destination translation | SDK maintainers |
|
|
255
|
+
| `src/utils` | Cache eligibility for query variants | SDK maintainers |
|
|
256
|
+
| Webex widgets repository | Thin consumer of the new defaults | Widgets maintainers |
|
|
257
|
+
|
|
258
|
+
The current behavior is specified in the owning module specifications: the façade policy in the
|
|
259
|
+
[Contact Center plugin spec](../../src/docs/README.md), the Queue, EntryPoint, and AddressBook wire
|
|
260
|
+
queries in the [Services spec](../../src/services/docs/README.md), the buddy-agent request in the
|
|
261
|
+
[Agent spec](../../src/services/agent/docs/README.md), cache eligibility in the
|
|
262
|
+
[Utils spec](../../src/utils/docs/README.md), direct entry-point transfer in the
|
|
263
|
+
[Task spec](../../src/services/task/docs/README.md), and the destination controls in the
|
|
264
|
+
[Task state machine spec](../../src/services/task/state-machine/docs/README.md).
|
|
265
|
+
|
|
266
|
+
### Risks and mitigations
|
|
267
|
+
|
|
268
|
+
| Risk or assumption | Evidence | Mitigation or decision owner |
|
|
269
|
+
| --- | --- | --- |
|
|
270
|
+
| CMS ignores ordering when encoded as legacy separate keys. | `src/services/Queue.ts`, `src/services/EntryPoint.ts` | Use and test combined `sort=FIELD,ORDER` (for example `sort=name,ASC`) serialization. |
|
|
271
|
+
| Simple cache returns a page created under a different view. | `src/utils/PageCache.ts` | Make every result/shape flag cache-disqualifying and retain repeated-call tests. |
|
|
272
|
+
| New EntryPoint/AddressBook ordering defaults affect generic callers. | `src/services/EntryPoint.ts`, `src/services/AddressBook.ts` | Make the correction explicit, retain caller overrides, and test both default and custom order. |
|
|
273
|
+
| A consumer re-sorts backend results. | `test/unit/spec/cc.ts` | Return the delegated response unchanged and document backend order as authoritative. |
|
|
274
|
+
| Direct entry-point transfer is sent to the blind-transfer operation or with the public destination literal. | `src/services/task/Task.ts`, established transfer-policy behavior | Route through `vteamTransfer`, translate to `entrypointDialNumber`, and assert the exact payload. |
|
|
275
|
+
| Entry-point configuration records do not contain the visible dialled number, and widget runtime returned no provisional `dbId`. | The backend /v3/dial-number contract returns dialledNumber, entryPointId, and entryPointName. | Move the EP-DN request/mapping into existing `getEntryPoints`, type `number`, and keep widget rendering declarative. |
|
|
276
|
+
|
|
277
|
+
### Observability, operations, and migration
|
|
278
|
+
|
|
279
|
+
- Existing buddy-agent success/failure metrics retain media and derived state context plus count, without logging agent identities.
|
|
280
|
+
- Existing Queue and EntryPoint request/success/failure metrics continue to cover the default and overridden calls.
|
|
281
|
+
- Existing Task transfer success/failure metrics continue to report the caller-facing entry-point destination while transport uses the backend EPDN value.
|
|
282
|
+
- No new metric taxonomy, PII-bearing log, credential log, trace, or alert is introduced.
|
|
283
|
+
|
|
284
|
+
- Build and run the complete Contact Center unit suite and style check before publishing.
|
|
285
|
+
- Release the SDK before or with widgets that require the corrected existing-method defaults and Task controls.
|
|
286
|
+
- Rollback is a coordinated package-version/code rollback; no persisted state, schema, or cache migration is required.
|
|
287
|
+
|
|
288
|
+
- Compatibility: list method names and response wrappers remain unchanged; explicit buddy-agent state remains supported; optional `EntryPointRecord.number` is additive and configuration-only entry-point fields are now optional. Queue/AddressBook request `name,ASC`; EntryPoint requests mapped, profile-scoped `entryPointName,ASC` rows while retaining compatible filter/sort overrides.
|
|
289
|
+
- Data or consumer transition: thin consumers continue using `getQueues` and `getEntryPoints`; consumers needing different behavior pass existing query overrides.
|
|
290
|
+
- Coexistence period: no parallel list surface exists.
|
|
291
|
+
- Completion and rollback outcome: consumers no longer own the default consult/transfer policy; rollback restores prior calls without data cleanup.
|
|
292
|
+
|
|
293
|
+
| Signal or support surface | Required change | Consumer or operator | Acceptance evidence |
|
|
294
|
+
| --- | --- | --- | --- |
|
|
295
|
+
| Buddy-agent operational metrics | Report derived action state and media without identities. | SDK maintainers | `test/unit/spec/cc.ts` |
|
|
296
|
+
| Queue request metrics/logs | Preserve existing request success/failure coverage for default and overridden calls. | SDK maintainers | `test/unit/spec/services/Queue.ts` |
|
|
297
|
+
| Entry-point request metrics/logs | Preserve existing request success/failure coverage for default and overridden calls. | SDK maintainers | `test/unit/spec/services/EntryPoint.ts` |
|
|
298
|
+
|
|
299
|
+
### Acceptance evidence
|
|
300
|
+
|
|
301
|
+
The test evidence for each decision rule is in the decision-rule table under Decision. The success
|
|
302
|
+
and guardrail metrics are:
|
|
303
|
+
|
|
304
|
+
| Metric | Baseline | Target | Measurement source |
|
|
305
|
+
| --- | --- | --- | --- |
|
|
306
|
+
| Consumers that must recreate the default queue/entry-point policy | Widgets did | 0 for ordinary existing-method calls | `src/services/Queue.ts`, `src/services/EntryPoint.ts` |
|
|
307
|
+
| JavaScript-side destination sorts in the changed SDK path | 0 | 0 | `src/cc.ts`, `src/services/Queue.ts`, `src/services/EntryPoint.ts` |
|
|
308
|
+
| Cache hits for view/filter/shape query variants | Possible | 0 | `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts` |
|
|
309
|
+
| Contact Center unit failures | Unknown before change | 0 | All suites under test/unit/spec |
|
|
310
|
+
| Contact Center build/style errors | Unknown before change | 0 | Package build and style commands |
|
|
311
|
+
|
|
312
|
+
## Constraint on future changes
|
|
313
|
+
|
|
314
|
+
While this decision is active, keep the policy on the existing methods: do not add parallel
|
|
315
|
+
consult/transfer list methods or projected response types, do not sort or reorder list responses in
|
|
316
|
+
JavaScript, keep every result- or shape-changing query option cache-disqualifying in `PageCache`, keep
|
|
317
|
+
desktop-profile scoping of entry points SDK-owned, keep the `entryPoint` to `entrypointDialNumber`
|
|
318
|
+
translation inside `Task.transfer()`, and keep `consultTransferDestinations` ordered Agent, Queue, Dial
|
|
319
|
+
Number, Entry Point with the first item as the consumer default.
|
|
320
|
+
|
|
321
|
+
## Follow-up
|
|
322
|
+
|
|
323
|
+
- The paired widgets feature spec must reference this SDK delta as the owner of queue eligibility/order/profile views and entry-point dial-number mapping/order; widgets delegate entry points without media filtering and may pass a queue filter for an active non-telephony task.
|
|
324
|
+
|
|
325
|
+
## Revisit when
|
|
326
|
+
|
|
327
|
+
- The CMS list APIs or `/v3/dial-number` change how they honor the combined `sort` value, the
|
|
328
|
+
desktop-profile views, or `includeEntryPointName`.
|
|
329
|
+
- The WCC vteam transfer operation stops accepting `entrypointDialNumber`.
|
|
330
|
+
- A consumer needs a destination category or order that the Task controls cannot express.
|
|
331
|
+
|
|
332
|
+
## References
|
|
333
|
+
|
|
334
|
+
- `src/cc.ts`
|
|
335
|
+
- `src/types.ts`
|
|
336
|
+
- `src/services/Queue.ts`
|
|
337
|
+
- `src/services/EntryPoint.ts`
|
|
338
|
+
- `src/services/AddressBook.ts`
|
|
339
|
+
- `src/utils/PageCache.ts`
|
|
340
|
+
- `src/services/task/Task.ts`
|
|
341
|
+
- `src/services/task/state-machine/uiControlsComputer.ts`
|
|
342
|
+
- `test/unit/spec/services/Queue.ts`, `test/unit/spec/services/EntryPoint.ts`,
|
|
343
|
+
`test/unit/spec/services/AddressBook.ts`, `test/unit/spec/cc.ts`,
|
|
344
|
+
`test/unit/spec/services/task/Task.ts`, `test/unit/spec/services/task/state-machine/uiControlsComputer.ts`
|
|
345
|
+
- The workspace sample docs/samples/contact-center/app.js (outside this package)
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: ADR
|
|
3
|
+
title: ADR-0003 - Repo-standards migration
|
|
4
|
+
description: Migrate the earlier generated SDD documentation of @webex/contact-center into the repo-standards layout and delete the older documentation folders after review.
|
|
5
|
+
tags: [adr]
|
|
6
|
+
timestamp: 2026-11-16T00:00:00Z
|
|
7
|
+
status: accepted
|
|
8
|
+
---
|
|
9
|
+
<!-- sdd-generated-metadata
|
|
10
|
+
doc_kind: standing-doc
|
|
11
|
+
generated_from: adr@0.3.0
|
|
12
|
+
generated_by: claude-code
|
|
13
|
+
approved_by: rarajes2@cisco.com
|
|
14
|
+
updated_at: 2026-11-17T03:03:58Z
|
|
15
|
+
validation_status: pass-with-warnings
|
|
16
|
+
-->
|
|
17
|
+
|
|
18
|
+
# ADR-0003 - Repo-standards migration
|
|
19
|
+
|
|
20
|
+
| Field | Value |
|
|
21
|
+
| ------------- | ----- |
|
|
22
|
+
| Status | Accepted |
|
|
23
|
+
| Decision date | 2026-11-16 |
|
|
24
|
+
| Deciders | rarajes2@cisco.com (confirmed in chat) |
|
|
25
|
+
| Supersedes | [ADR-0001 - Spec source policy](0001-spec-source-policy.md) |
|
|
26
|
+
| Superseded by | N/A |
|
|
27
|
+
|
|
28
|
+
## Context
|
|
29
|
+
|
|
30
|
+
[ADR-0001](0001-spec-source-policy.md) made the earlier generated module specifications canonical and
|
|
31
|
+
kept the hand-written module guides beside them as reference-only material. Those specifications,
|
|
32
|
+
the package-wide architecture, contract, glossary, security, service-state, rules, pattern, and
|
|
33
|
+
template documents, and three earlier feature records all lived in documentation folders of an older
|
|
34
|
+
Repo Annotation layout. The monorepo root now holds one Repo Standards template set
|
|
35
|
+
(`../../../.sdd/templates/repo-standards`) that every onboarded package uses, and the older layout
|
|
36
|
+
leaves this package with two documentation shapes.
|
|
37
|
+
|
|
38
|
+
## Decision
|
|
39
|
+
|
|
40
|
+
Use the `migrate-existing` source policy again, this time into the repo-standards layout:
|
|
41
|
+
|
|
42
|
+
- Each of the nine manifest modules keeps its path; its canonical specification moves to the
|
|
43
|
+
`docs/README.md` file inside the module directory, listed in the
|
|
44
|
+
[Module registry](../specs/README.md#module-registry).
|
|
45
|
+
- Package-wide content moves by meaning into the standing documents under `docs/`
|
|
46
|
+
([architecture](../architecture.md), [getting started](../getting-started.md),
|
|
47
|
+
[specification registry](../specs/README.md), and these ADRs), into `.repo-context.json`, and
|
|
48
|
+
into the package [`AGENTS.md`](../../AGENTS.md), which is merged in place.
|
|
49
|
+
- The consult and transfer list policy becomes [ADR-0002](0002-consult-transfer-list-policy.md).
|
|
50
|
+
- `src/utils/AGENTS.md` is retained as reference-only context; the Utils module specification is
|
|
51
|
+
canonical.
|
|
52
|
+
- Every claim is checked against `src/` and `test/unit/spec` before it is carried; stale claims are
|
|
53
|
+
corrected or recorded as stale in the local source-fidelity inventories.
|
|
54
|
+
- The older documentation folders are deleted after source fidelity, conformance, the checkers, and
|
|
55
|
+
the user's review of the diff, in a separate final commit.
|
|
56
|
+
|
|
57
|
+
## Why
|
|
58
|
+
|
|
59
|
+
One template set across the monorepo gives agents and reviewers the same document shapes in every
|
|
60
|
+
package, and deleting the older folders after review removes the second documentation family that
|
|
61
|
+
ADR-0001 had to keep marked as reference-only.
|
|
62
|
+
|
|
63
|
+
## Alternatives considered
|
|
64
|
+
|
|
65
|
+
| Alternative | Why it was not selected |
|
|
66
|
+
| ----------- | ----------------------- |
|
|
67
|
+
| Keep the older layout beside the repo-standards documents (`keep-separate`) | Two documentation families with overlapping authority stay in the package |
|
|
68
|
+
| Reconcile the older documents in place (`reconcile`) | Keeps the older document shapes, which the root templates do not generate or check |
|
|
69
|
+
| Keep the older files with reference-only banners, as ADR-0001 did | The repo-standards documents carry the content by meaning, so the banners only preserve drift |
|
|
70
|
+
|
|
71
|
+
## Consequences
|
|
72
|
+
|
|
73
|
+
**Positive:**
|
|
74
|
+
|
|
75
|
+
- One canonical specification per module beside its code, and one standing-document set under
|
|
76
|
+
`docs/`, all generated from the root Repo Standards templates.
|
|
77
|
+
- No reference-only copies of migrated content remain once the deletion commit lands.
|
|
78
|
+
|
|
79
|
+
**Negative / tradeoffs:**
|
|
80
|
+
|
|
81
|
+
- History that lived only in the older documents (earlier correction records and onboarding
|
|
82
|
+
metadata) is kept in the local source-fidelity inventories, not in committed documents.
|
|
83
|
+
- Coverage states are carried, not reassessed, until a fresh coverage review runs.
|
|
84
|
+
|
|
85
|
+
## Constraint on future changes
|
|
86
|
+
|
|
87
|
+
Change a module's behavior together with its `docs/README.md` specification and, for a contract,
|
|
88
|
+
the architecture contract index and `.sdd/manifest.json`. Do not reintroduce a parallel
|
|
89
|
+
documentation folder; code and tests remain the behavioral referee.
|
|
90
|
+
|
|
91
|
+
## Follow-up
|
|
92
|
+
|
|
93
|
+
- [ ] Delete the older documentation folders in a separate commit after the user reviews the diff.
|
|
94
|
+
- [ ] Run a coverage review and an independent validation on another runtime.
|
|
95
|
+
|
|
96
|
+
## Revisit when
|
|
97
|
+
|
|
98
|
+
- The root Repo Standards templates change their layout, or a module is added, split, or moved.
|
|
99
|
+
|
|
100
|
+
## References
|
|
101
|
+
|
|
102
|
+
- `.sdd/manifest.json` `spec_source_policy`, `spec_sources`, and `template_migration`
|
|
103
|
+
- [ADR-0001 - Spec source policy](0001-spec-source-policy.md)
|
|
104
|
+
- [Specification registry](../specs/README.md)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
<!-- sdd-generated-metadata
|
|
2
|
+
doc_kind: standing-doc
|
|
3
|
+
generated_from: adr-index@0.3.0
|
|
4
|
+
generated_by: claude-code
|
|
5
|
+
approved_by: rarajes2@cisco.com
|
|
6
|
+
updated_at: 2026-11-17T03:03:58Z
|
|
7
|
+
validation_status: pass-with-warnings
|
|
8
|
+
-->
|
|
9
|
+
|
|
10
|
+
# Architectural decision records
|
|
11
|
+
|
|
12
|
+
Use this append-only directory for numbered records of durable decisions that constrain future Contact
|
|
13
|
+
Center SDK work and its documentation.
|
|
14
|
+
Add a concrete ADR (for example, `0042-cache-policy.md`) when a decision is non-obvious, hard to
|
|
15
|
+
reverse, or worth explaining to a future contributor. Do not edit an accepted decision in place when
|
|
16
|
+
its outcome changes; supersede it with a new ADR and link both records.
|
|
17
|
+
|
|
18
|
+
- One decision per `NNNN-short-title.md` file in this folder, started from the repo-standards ADR
|
|
19
|
+
template under the monorepo root `.sdd/templates/repo-standards/docs/adr/`.
|
|
20
|
+
- Link ADRs from the affected module specs and the [package architecture](../architecture.md).
|
|
21
|
+
|
|
22
|
+
## Index
|
|
23
|
+
|
|
24
|
+
- [ADR-0001 - Spec source policy](0001-spec-source-policy.md) — accepted 2026-07-07; superseded by
|
|
25
|
+
ADR-0003
|
|
26
|
+
- [ADR-0002 - Consult and transfer list policy](0002-consult-transfer-list-policy.md) — accepted
|
|
27
|
+
2026-08-19
|
|
28
|
+
- [ADR-0003 - Repo-standards migration](0003-repo-standards-migration.md) — accepted 2026-11-16;
|
|
29
|
+
supersedes ADR-0001
|
|
30
|
+
|
|
31
|
+
Add new entries as ADRs are accepted. Keep this list in numeric order.
|
|
32
|
+
|
|
33
|
+
Each ADR should state its context, decision, alternatives, consequences, and the condition that would
|
|
34
|
+
cause the team to revisit it. Record the deciders, any superseded decision, and the constraint future
|
|
35
|
+
changes must preserve.
|