@webex/contact-center 3.12.0-webex-services-ready.4 → 3.13.0

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 (250) hide show
  1. package/.sdd/manifest.json +24 -13
  2. package/ai-docs/ARCHITECTURE.md +1 -1
  3. package/ai-docs/CONTRACTS.md +19 -3
  4. package/ai-docs/SECURITY.md +1 -1
  5. package/ai-docs/SERVICE_STATE.md +4 -0
  6. package/ai-docs/contact-center-spec.md +50 -6
  7. package/ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md +362 -0
  8. package/ai-docs/features/contact-owner-change-refactor.md +78 -0
  9. package/dist/cc.js +757 -22
  10. package/dist/cc.js.map +1 -1
  11. package/dist/config.js +7 -0
  12. package/dist/config.js.map +1 -1
  13. package/dist/constants.js +23 -2
  14. package/dist/constants.js.map +1 -1
  15. package/dist/index.js +34 -12
  16. package/dist/index.js.map +1 -1
  17. package/dist/metrics/MetricsManager.js +16 -0
  18. package/dist/metrics/MetricsManager.js.map +1 -1
  19. package/dist/metrics/behavioral-events.js +110 -0
  20. package/dist/metrics/behavioral-events.js.map +1 -1
  21. package/dist/metrics/constants.js +33 -0
  22. package/dist/metrics/constants.js.map +1 -1
  23. package/dist/services/AddressBook.js +18 -15
  24. package/dist/services/AddressBook.js.map +1 -1
  25. package/dist/services/AnswerCallOnWebexService.js +202 -0
  26. package/dist/services/AnswerCallOnWebexService.js.map +1 -0
  27. package/dist/services/ApiAiAssistant.js +221 -11
  28. package/dist/services/ApiAiAssistant.js.map +1 -1
  29. package/dist/services/EntryPoint.js +46 -68
  30. package/dist/services/EntryPoint.js.map +1 -1
  31. package/dist/services/Queue.js +27 -22
  32. package/dist/services/Queue.js.map +1 -1
  33. package/dist/services/WebCallingService.js +10 -2
  34. package/dist/services/WebCallingService.js.map +1 -1
  35. package/dist/services/WebexCrossClientService.js +225 -0
  36. package/dist/services/WebexCrossClientService.js.map +1 -0
  37. package/dist/services/WxAppTelephonyMercurySync.js +111 -0
  38. package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
  39. package/dist/services/config/Util.js +46 -46
  40. package/dist/services/config/Util.js.map +1 -1
  41. package/dist/services/config/constants.js +34 -77
  42. package/dist/services/config/constants.js.map +1 -1
  43. package/dist/services/config/index.js +100 -226
  44. package/dist/services/config/index.js.map +1 -1
  45. package/dist/services/config/types.js +51 -18
  46. package/dist/services/config/types.js.map +1 -1
  47. package/dist/services/constants.js +11 -1
  48. package/dist/services/constants.js.map +1 -1
  49. package/dist/services/core/Err.js.map +1 -1
  50. package/dist/services/core/Utils.js +25 -1
  51. package/dist/services/core/Utils.js.map +1 -1
  52. package/dist/services/core/WebexRequest.js +6 -2
  53. package/dist/services/core/WebexRequest.js.map +1 -1
  54. package/dist/services/core/aqm-reqs.js +17 -11
  55. package/dist/services/core/aqm-reqs.js.map +1 -1
  56. package/dist/services/core/constants.js +9 -1
  57. package/dist/services/core/constants.js.map +1 -1
  58. package/dist/services/core/types.js.map +1 -1
  59. package/dist/services/core/websocket/WebSocketManager.js +17 -1
  60. package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
  61. package/dist/services/task/Task.js +275 -8
  62. package/dist/services/task/Task.js.map +1 -1
  63. package/dist/services/task/TaskFactory.js +11 -6
  64. package/dist/services/task/TaskFactory.js.map +1 -1
  65. package/dist/services/task/TaskManager.js +590 -42
  66. package/dist/services/task/TaskManager.js.map +1 -1
  67. package/dist/services/task/TaskUtils.js +11 -1
  68. package/dist/services/task/TaskUtils.js.map +1 -1
  69. package/dist/services/task/WebexCallingUtils.js +70 -0
  70. package/dist/services/task/WebexCallingUtils.js.map +1 -0
  71. package/dist/services/task/constants.js +14 -2
  72. package/dist/services/task/constants.js.map +1 -1
  73. package/dist/services/task/contact.js +29 -0
  74. package/dist/services/task/contact.js.map +1 -1
  75. package/dist/services/task/digital/Digital.js +4 -3
  76. package/dist/services/task/digital/Digital.js.map +1 -1
  77. package/dist/services/task/state-machine/TaskStateMachine.js +162 -53
  78. package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -1
  79. package/dist/services/task/state-machine/actions.js +6 -1
  80. package/dist/services/task/state-machine/actions.js.map +1 -1
  81. package/dist/services/task/state-machine/guards.js +7 -10
  82. package/dist/services/task/state-machine/guards.js.map +1 -1
  83. package/dist/services/task/state-machine/types.js.map +1 -1
  84. package/dist/services/task/state-machine/uiControlsComputer.js +118 -18
  85. package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -1
  86. package/dist/services/task/types.js +47 -1
  87. package/dist/services/task/types.js.map +1 -1
  88. package/dist/services/task/voice/Voice.js +477 -17
  89. package/dist/services/task/voice/Voice.js.map +1 -1
  90. package/dist/services/task/voice/WebRTC.js +6 -3
  91. package/dist/services/task/voice/WebRTC.js.map +1 -1
  92. package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
  93. package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
  94. package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
  95. package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
  96. package/dist/services/wxAppDiagnosticLogging.js +159 -0
  97. package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
  98. package/dist/services/wxAppTelephonyUtils.js +19 -0
  99. package/dist/services/wxAppTelephonyUtils.js.map +1 -0
  100. package/dist/types/cc.d.ts +102 -8
  101. package/dist/types/config.d.ts +7 -0
  102. package/dist/types/constants.d.ts +21 -0
  103. package/dist/types/index.d.ts +34 -15
  104. package/dist/types/metrics/MetricsManager.d.ts +6 -0
  105. package/dist/types/metrics/constants.d.ts +31 -0
  106. package/dist/types/services/AddressBook.d.ts +2 -1
  107. package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
  108. package/dist/types/services/ApiAiAssistant.d.ts +48 -4
  109. package/dist/types/services/EntryPoint.d.ts +7 -5
  110. package/dist/types/services/Queue.d.ts +5 -3
  111. package/dist/types/services/WebexCrossClientService.d.ts +32 -0
  112. package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
  113. package/dist/types/services/config/Util.d.ts +4 -8
  114. package/dist/types/services/config/constants.d.ts +28 -76
  115. package/dist/types/services/config/index.d.ts +16 -64
  116. package/dist/types/services/config/types.d.ts +146 -173
  117. package/dist/types/services/constants.d.ts +9 -0
  118. package/dist/types/services/core/Err.d.ts +2 -0
  119. package/dist/types/services/core/Utils.d.ts +10 -0
  120. package/dist/types/services/core/WebexRequest.d.ts +1 -0
  121. package/dist/types/services/core/constants.d.ts +7 -0
  122. package/dist/types/services/core/types.d.ts +2 -0
  123. package/dist/types/services/task/Task.d.ts +34 -5
  124. package/dist/types/services/task/TaskFactory.d.ts +4 -2
  125. package/dist/types/services/task/TaskUtils.d.ts +6 -0
  126. package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
  127. package/dist/types/services/task/constants.d.ts +12 -0
  128. package/dist/types/services/task/contact.d.ts +4 -0
  129. package/dist/types/services/task/digital/Digital.d.ts +4 -3
  130. package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +304 -56
  131. package/dist/types/services/task/state-machine/guards.d.ts +6 -5
  132. package/dist/types/services/task/state-machine/types.d.ts +9 -1
  133. package/dist/types/services/task/types.d.ts +192 -5
  134. package/dist/types/services/task/voice/Voice.d.ts +68 -11
  135. package/dist/types/services/task/voice/WebRTC.d.ts +5 -4
  136. package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
  137. package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
  138. package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
  139. package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
  140. package/dist/types/types.d.ts +80 -13
  141. package/dist/types/utils/PageCache.d.ts +20 -3
  142. package/dist/types.js +54 -8
  143. package/dist/types.js.map +1 -1
  144. package/dist/utils/PageCache.js +19 -5
  145. package/dist/utils/PageCache.js.map +1 -1
  146. package/dist/webex.js +9 -1
  147. package/dist/webex.js.map +1 -1
  148. package/package.json +10 -9
  149. package/src/cc.ts +969 -38
  150. package/src/config.ts +7 -0
  151. package/src/constants.ts +24 -0
  152. package/src/index.ts +39 -10
  153. package/src/metrics/MetricsManager.ts +16 -0
  154. package/src/metrics/ai-docs/metrics-spec.md +138 -21
  155. package/src/metrics/behavioral-events.ts +112 -0
  156. package/src/metrics/constants.ts +36 -0
  157. package/src/services/AddressBook.ts +17 -6
  158. package/src/services/AnswerCallOnWebexService.ts +239 -0
  159. package/src/services/ApiAiAssistant.ts +297 -13
  160. package/src/services/EntryPoint.ts +59 -60
  161. package/src/services/Queue.ts +29 -12
  162. package/src/services/WebCallingService.ts +16 -2
  163. package/src/services/WebexCrossClientService.ts +298 -0
  164. package/src/services/WxAppTelephonyMercurySync.ts +142 -0
  165. package/src/services/agent/ai-docs/AGENTS.md +1 -1
  166. package/src/services/agent/ai-docs/agent-spec.md +1 -0
  167. package/src/services/ai-docs/AGENTS.md +10 -10
  168. package/src/services/ai-docs/services-spec.md +25 -5
  169. package/src/services/config/Util.ts +52 -82
  170. package/src/services/config/ai-docs/AGENTS.md +35 -40
  171. package/src/services/config/ai-docs/ARCHITECTURE.md +90 -103
  172. package/src/services/config/ai-docs/config-spec.md +132 -132
  173. package/src/services/config/constants.ts +39 -85
  174. package/src/services/config/index.ts +116 -277
  175. package/src/services/config/types.ts +140 -195
  176. package/src/services/constants.ts +10 -0
  177. package/src/services/core/Err.ts +1 -0
  178. package/src/services/core/Utils.ts +28 -0
  179. package/src/services/core/WebexRequest.ts +3 -1
  180. package/src/services/core/ai-docs/core-spec.md +25 -11
  181. package/src/services/core/aqm-reqs.ts +18 -12
  182. package/src/services/core/constants.ts +8 -0
  183. package/src/services/core/types.ts +33 -1
  184. package/src/services/core/websocket/WebSocketManager.ts +26 -2
  185. package/src/services/task/Task.ts +386 -12
  186. package/src/services/task/TaskFactory.ts +33 -6
  187. package/src/services/task/TaskManager.ts +857 -41
  188. package/src/services/task/TaskUtils.ts +13 -0
  189. package/src/services/task/WebexCallingUtils.ts +136 -0
  190. package/src/services/task/ai-docs/ARCHITECTURE.md +1 -0
  191. package/src/services/task/ai-docs/task-spec.md +190 -8
  192. package/src/services/task/constants.ts +13 -0
  193. package/src/services/task/contact.ts +30 -0
  194. package/src/services/task/digital/Digital.ts +11 -4
  195. package/src/services/task/state-machine/TaskStateMachine.ts +235 -81
  196. package/src/services/task/state-machine/actions.ts +5 -2
  197. package/src/services/task/state-machine/ai-docs/AGENTS.md +6 -4
  198. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +35 -16
  199. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +103 -33
  200. package/src/services/task/state-machine/guards.ts +7 -10
  201. package/src/services/task/state-machine/types.ts +16 -1
  202. package/src/services/task/state-machine/uiControlsComputer.ts +206 -32
  203. package/src/services/task/types.ts +269 -4
  204. package/src/services/task/voice/Voice.ts +625 -17
  205. package/src/services/task/voice/WebRTC.ts +11 -4
  206. package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
  207. package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
  208. package/src/services/wxAppDiagnosticLogging.ts +286 -0
  209. package/src/services/wxAppTelephonyUtils.ts +14 -0
  210. package/src/types.ts +108 -13
  211. package/src/utils/AGENTS.md +21 -10
  212. package/src/utils/PageCache.ts +38 -5
  213. package/src/utils/ai-docs/utils-spec.md +21 -11
  214. package/src/webex.js +8 -0
  215. package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
  216. package/test/unit/spec/cc.ts +3408 -152
  217. package/test/unit/spec/index.ts +885 -0
  218. package/test/unit/spec/metrics/MetricsManager.ts +25 -0
  219. package/test/unit/spec/metrics/behavioral-events.ts +60 -0
  220. package/test/unit/spec/services/AddressBook.ts +37 -6
  221. package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
  222. package/test/unit/spec/services/ApiAiAssistant.ts +269 -8
  223. package/test/unit/spec/services/EntryPoint.ts +87 -40
  224. package/test/unit/spec/services/Queue.ts +123 -12
  225. package/test/unit/spec/services/WebCallingService.ts +38 -0
  226. package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
  227. package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
  228. package/test/unit/spec/services/config/Util.ts +501 -0
  229. package/test/unit/spec/services/config/index.ts +313 -543
  230. package/test/unit/spec/services/core/Utils.ts +22 -0
  231. package/test/unit/spec/services/core/WebexRequest.ts +8 -7
  232. package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
  233. package/test/unit/spec/services/core/websocket/WebSocketManager.ts +64 -14
  234. package/test/unit/spec/services/task/Task.ts +2257 -11
  235. package/test/unit/spec/services/task/TaskFactory.ts +56 -2
  236. package/test/unit/spec/services/task/TaskManager.ts +5559 -1493
  237. package/test/unit/spec/services/task/TaskUtils.ts +72 -0
  238. package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
  239. package/test/unit/spec/services/task/contact.ts +33 -0
  240. package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +1501 -92
  241. package/test/unit/spec/services/task/state-machine/guards.ts +210 -8
  242. package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +445 -7
  243. package/test/unit/spec/services/task/voice/Voice.ts +1710 -4
  244. package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
  245. package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
  246. package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
  247. package/test/unit/spec/wellnessSampleUtils.ts +288 -0
  248. package/typedoc.md +1 -1
  249. package/umd/contact-center.min.js +2 -2
  250. package/umd/contact-center.min.js.map +1 -1
@@ -15,11 +15,13 @@ import {TIMEOUT_DURATION, WEB_CALLING_SERVICE_FILE} from '../constants';
15
15
  import LoggerProxy from '../logger-proxy';
16
16
  import {
17
17
  DEFAULT_RTMS_DOMAIN,
18
+ ALLOWED_RTMS_DOMAIN,
18
19
  POST_AUTH,
19
20
  WCC_CALLING_RTMS_DOMAIN,
20
21
  DEREGISTER_WEBCALLING_LINE_MSG,
21
22
  METHODS,
22
23
  } from './constants';
24
+ import {isAllowedUrlHost} from './core/Utils';
23
25
 
24
26
  /**
25
27
  * WebCallingService provides WebRTC calling functionality for Contact Center agents.
@@ -141,9 +143,21 @@ export default class WebCallingService extends EventEmitter {
141
143
  const rtmsURL = this.webex.internal.services.get(WCC_CALLING_RTMS_DOMAIN);
142
144
 
143
145
  try {
144
- const url = new URL(rtmsURL);
146
+ const hostname = new URL(rtmsURL).hostname.toLowerCase();
147
+
148
+ if (!isAllowedUrlHost(rtmsURL, [ALLOWED_RTMS_DOMAIN])) {
149
+ LoggerProxy.error(
150
+ `Non-allow-listed RTMS host from u2c catalogue: ${hostname} so falling back to default domain`,
151
+ {
152
+ module: WEB_CALLING_SERVICE_FILE,
153
+ method: METHODS.GET_RTMS_DOMAIN,
154
+ }
155
+ );
156
+
157
+ return DEFAULT_RTMS_DOMAIN;
158
+ }
145
159
 
146
- return url.hostname;
160
+ return hostname;
147
161
  } catch (error) {
148
162
  LoggerProxy.error(
149
163
  `Invalid URL from u2c catalogue: ${rtmsURL} so falling back to default domain`,
@@ -0,0 +1,298 @@
1
+ import LoggerProxy from '../logger-proxy';
2
+ import {METHODS} from '../constants';
3
+ import {WebexSDK} from '../types';
4
+ import MetricsManager from '../metrics/MetricsManager';
5
+ import {METRIC_EVENT_NAMES} from '../metrics/constants';
6
+
7
+ const WEBEX_CROSS_CLIENT_FILE = 'WebexCrossClientService';
8
+ const DEFAULT_CROSS_CLIENT_STATE_TTL = 900;
9
+ const EXPIRATION_OFFSET_MS = 60_000;
10
+ /** Must match Agent Desktop usersub publish — Webex App reads `wxcc` cross-client state. */
11
+ const DEFAULT_APP_NAME = 'wxcc';
12
+ const REFRESH_RETRY_DELAY_MS = 30_000;
13
+ const MAX_REFRESH_RETRIES = 3;
14
+
15
+ type RefreshTimer = ReturnType<typeof setTimeout>;
16
+
17
+ /**
18
+ * Publishes usersub cross-client state so Webex App suppresses native calling toasts (WXCC-6026).
19
+ */
20
+ export default class WebexCrossClientService {
21
+ private webex: WebexSDK;
22
+ private refreshTimer?: RefreshTimer;
23
+ private refreshRetryTimer?: RefreshTimer;
24
+ private answerCallsState = false;
25
+ private appName = DEFAULT_APP_NAME;
26
+ /** Incremented on teardown/disable to ignore stale refresh timer callbacks. */
27
+ private refreshGeneration = 0;
28
+ /** Monotonic id for usersub publish metrics timers; stale publishes cancel only their own timer. */
29
+ private usersubPublishMetricsId = 0;
30
+
31
+ constructor(webex: WebexSDK) {
32
+ this.webex = webex;
33
+ }
34
+
35
+ private extractDeviceIdFromUrl(url: string): string {
36
+ const match = url.match(/\/devices\/([^/?]+)/);
37
+
38
+ return match ? match[1] : '';
39
+ }
40
+
41
+ private getDeviceUrl(): string | undefined {
42
+ return this.webex.internal.device?.url;
43
+ }
44
+
45
+ private clearRefreshTimer(): void {
46
+ if (this.refreshTimer) {
47
+ clearTimeout(this.refreshTimer);
48
+ this.refreshTimer = undefined;
49
+ }
50
+
51
+ if (this.refreshRetryTimer) {
52
+ clearTimeout(this.refreshRetryTimer);
53
+ this.refreshRetryTimer = undefined;
54
+ }
55
+ }
56
+
57
+ private scheduleRefreshRetry(
58
+ userId: string,
59
+ ttl: number,
60
+ scheduledGeneration: number,
61
+ retryAttempt: number
62
+ ): void {
63
+ if (
64
+ retryAttempt >= MAX_REFRESH_RETRIES ||
65
+ scheduledGeneration !== this.refreshGeneration ||
66
+ !this.answerCallsState
67
+ ) {
68
+ return;
69
+ }
70
+
71
+ this.refreshRetryTimer = setTimeout(async () => {
72
+ if (scheduledGeneration !== this.refreshGeneration || !this.answerCallsState) {
73
+ return;
74
+ }
75
+
76
+ try {
77
+ await this.setManageWebexCallingInWxcc(true, {userId, ttl, appName: this.appName});
78
+ } catch (error) {
79
+ LoggerProxy.error(`WebexCrossClientService refresh retry failed: ${error}`, {
80
+ module: WEBEX_CROSS_CLIENT_FILE,
81
+ method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
82
+ });
83
+ this.scheduleRefreshRetry(userId, ttl, scheduledGeneration, retryAttempt + 1);
84
+ }
85
+ }, REFRESH_RETRY_DELAY_MS);
86
+ }
87
+
88
+ private startRefreshTimer(userId: string, ttl: number): void {
89
+ this.clearRefreshTimer();
90
+
91
+ if (!this.answerCallsState) {
92
+ return;
93
+ }
94
+
95
+ const refreshTime = ttl * 1000 - EXPIRATION_OFFSET_MS;
96
+ const scheduledGeneration = this.refreshGeneration;
97
+ this.refreshTimer = setTimeout(async () => {
98
+ if (scheduledGeneration !== this.refreshGeneration || !this.answerCallsState) {
99
+ return;
100
+ }
101
+
102
+ try {
103
+ await this.setManageWebexCallingInWxcc(true, {userId, ttl, appName: this.appName});
104
+ } catch (error) {
105
+ LoggerProxy.error(`WebexCrossClientService refresh failed: ${error}`, {
106
+ module: WEBEX_CROSS_CLIENT_FILE,
107
+ method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
108
+ });
109
+ this.scheduleRefreshRetry(userId, ttl, scheduledGeneration, 0);
110
+ }
111
+ }, refreshTime);
112
+ }
113
+
114
+ private publishCrossClientState(
115
+ users: string[],
116
+ ttl: number,
117
+ composition: Record<string, unknown>,
118
+ logContext: string
119
+ ): Promise<unknown> {
120
+ const body = {
121
+ users,
122
+ compositions: [
123
+ {
124
+ type: 'cross-client-state',
125
+ ttl,
126
+ composition,
127
+ },
128
+ ],
129
+ };
130
+
131
+ return this.webex
132
+ .request({
133
+ method: 'POST',
134
+ service: 'usersub',
135
+ resource: 'publish',
136
+ body,
137
+ })
138
+ .then((response: {body?: unknown}) => response?.body)
139
+ .catch((error: unknown) => {
140
+ LoggerProxy.error(`WebexCrossClientService.${logContext} failed: ${error}`, {
141
+ module: WEBEX_CROSS_CLIENT_FILE,
142
+ method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
143
+ });
144
+
145
+ return Promise.reject(error);
146
+ });
147
+ }
148
+
149
+ public async setManageWebexCallingInWxcc(
150
+ enable: boolean,
151
+ options?: {userId?: string; ttl?: number; appName?: string; trackPublishMetrics?: boolean}
152
+ ): Promise<void> {
153
+ const operationGeneration = this.refreshGeneration;
154
+ const userId = options?.userId ?? this.webex.internal.device?.userId;
155
+ const ttl = options?.ttl ?? DEFAULT_CROSS_CLIENT_STATE_TTL;
156
+ const appName = options?.appName ?? DEFAULT_APP_NAME;
157
+ const trackPublishMetrics = options?.trackPublishMetrics ?? false;
158
+ this.appName = appName;
159
+
160
+ if (!userId) {
161
+ const error = 'User ID is unavailable for cross-client publish';
162
+ this.trackUsersubPreflightFailure(enable, 'user_id_unavailable', error, trackPublishMetrics);
163
+ throw new Error(error);
164
+ }
165
+
166
+ const deviceUrl = this.getDeviceUrl();
167
+ if (!deviceUrl) {
168
+ const error = 'Device URL is unavailable for cross-client publish';
169
+ this.trackUsersubPreflightFailure(
170
+ enable,
171
+ 'device_url_unavailable',
172
+ error,
173
+ trackPublishMetrics
174
+ );
175
+ throw new Error(error);
176
+ }
177
+
178
+ const composition = {
179
+ devices: [
180
+ {
181
+ deviceId: this.extractDeviceIdFromUrl(deviceUrl),
182
+ appName,
183
+ state: {
184
+ 'answer-calls-on-wxcc': enable,
185
+ },
186
+ },
187
+ ],
188
+ };
189
+
190
+ const metricsManager = MetricsManager.getInstance();
191
+ const usersubPublishEventKeys = [
192
+ METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_SUCCESS,
193
+ METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
194
+ ];
195
+
196
+ let publishMetricsId = 0;
197
+ if (trackPublishMetrics) {
198
+ this.usersubPublishMetricsId += 1;
199
+ publishMetricsId = this.usersubPublishMetricsId;
200
+ metricsManager.timeEvent(usersubPublishEventKeys);
201
+ }
202
+
203
+ try {
204
+ await this.publishCrossClientState([userId], ttl, composition, 'setManageWebexCallingInWxcc');
205
+ } catch (error) {
206
+ if (trackPublishMetrics) {
207
+ if (operationGeneration !== this.refreshGeneration) {
208
+ if (publishMetricsId === this.usersubPublishMetricsId) {
209
+ metricsManager.cancelTimedEvent(usersubPublishEventKeys);
210
+ }
211
+ } else {
212
+ metricsManager.trackEvent(
213
+ METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
214
+ {
215
+ enableWxBetterTogether: enable,
216
+ usersubPublished: this.answerCallsState,
217
+ error: error instanceof Error ? error.toString() : String(error),
218
+ },
219
+ ['operational', 'behavioral']
220
+ );
221
+ }
222
+ }
223
+
224
+ throw error;
225
+ }
226
+
227
+ if (operationGeneration !== this.refreshGeneration) {
228
+ if (trackPublishMetrics && publishMetricsId === this.usersubPublishMetricsId) {
229
+ metricsManager.cancelTimedEvent(usersubPublishEventKeys);
230
+ }
231
+
232
+ return;
233
+ }
234
+
235
+ this.answerCallsState = enable;
236
+
237
+ if (enable) {
238
+ this.startRefreshTimer(userId, ttl);
239
+ } else {
240
+ this.refreshGeneration += 1;
241
+ this.clearRefreshTimer();
242
+ }
243
+
244
+ if (trackPublishMetrics) {
245
+ metricsManager.trackEvent(
246
+ METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_SUCCESS,
247
+ {
248
+ enableWxBetterTogether: enable,
249
+ usersubPublished: enable,
250
+ },
251
+ ['operational', 'behavioral']
252
+ );
253
+ }
254
+
255
+ LoggerProxy.log(`Cross-client answer-calls-on-wxcc set to ${enable}`, {
256
+ module: WEBEX_CROSS_CLIENT_FILE,
257
+ method: METHODS.SET_MANAGE_WEBEX_CALLING_IN_WXCC,
258
+ data: {
259
+ appName,
260
+ deviceId: this.extractDeviceIdFromUrl(deviceUrl),
261
+ ttl,
262
+ },
263
+ });
264
+ }
265
+
266
+ private trackUsersubPreflightFailure(
267
+ enable: boolean,
268
+ skipReason: 'user_id_unavailable' | 'device_url_unavailable',
269
+ error: string,
270
+ trackPublishMetrics: boolean
271
+ ): void {
272
+ if (!trackPublishMetrics) {
273
+ return;
274
+ }
275
+
276
+ MetricsManager.getInstance().trackEvent(
277
+ METRIC_EVENT_NAMES.WXAPP_USERSUB_PUBLISH_FAILED,
278
+ {
279
+ enableWxBetterTogether: enable,
280
+ usersubPublished: this.answerCallsState,
281
+ skipReason,
282
+ error,
283
+ },
284
+ ['operational', 'behavioral']
285
+ );
286
+ }
287
+
288
+ public teardown(): void {
289
+ this.refreshGeneration += 1;
290
+ this.clearRefreshTimer();
291
+ this.answerCallsState = false;
292
+ }
293
+
294
+ /** Whether usersub `answer-calls-on-wxcc: true` was successfully published this session. */
295
+ public isAnswerCallsStateActive(): boolean {
296
+ return this.answerCallsState;
297
+ }
298
+ }
@@ -0,0 +1,142 @@
1
+ import LoggerProxy from '../logger-proxy';
2
+ import {METHODS} from '../constants';
3
+ import {WebexSDK} from '../types';
4
+ import MetricsManager from '../metrics/MetricsManager';
5
+ import {METRIC_EVENT_NAMES} from '../metrics/constants';
6
+ import {callIdSuffix, logWxAppMercuryMuteSync} from './wxAppDiagnosticLogging';
7
+
8
+ const WXAPP_TELEPHONY_MERCURY_SYNC_FILE = 'WxAppTelephonyMercurySync';
9
+
10
+ export const TELEPHONY_CALL_MUTED = 'event:telephony_calls.muted';
11
+ export const TELEPHONY_CALL_UNMUTED = 'event:telephony_calls.unmuted';
12
+
13
+ export type UpdatedCallMuteStateEvent = {
14
+ data: {
15
+ actorId: string;
16
+ callId: string;
17
+ muted: boolean;
18
+ };
19
+ };
20
+
21
+ type MuteChangeHandler = (callId: string, muted: boolean) => void;
22
+
23
+ /**
24
+ * Subscribes to Mercury telephony mute/unmute events for wxApp thick-client sync (AD parity).
25
+ */
26
+ export default class WxAppTelephonyMercurySync {
27
+ private webex: WebexSDK;
28
+ private subscribedAgentId?: string;
29
+ private muteChangeHandler?: MuteChangeHandler;
30
+ private boundMuteHandler?: (event: UpdatedCallMuteStateEvent) => void;
31
+ private boundUnmuteHandler?: (event: UpdatedCallMuteStateEvent) => void;
32
+
33
+ constructor(webex: WebexSDK) {
34
+ this.webex = webex;
35
+ }
36
+
37
+ private decodeBase64(value: string): string {
38
+ try {
39
+ return atob(value);
40
+ } catch {
41
+ return value;
42
+ }
43
+ }
44
+
45
+ private handleMuteStateEvent = (agentId: string, event: UpdatedCallMuteStateEvent): void => {
46
+ const {actorId, callId, muted} = event?.data ?? {};
47
+ if (!actorId || !callId || muted === undefined) {
48
+ logWxAppMercuryMuteSync({
49
+ phase: 'dropped',
50
+ dropReason: 'missing_mercury_event_fields',
51
+ });
52
+
53
+ return;
54
+ }
55
+
56
+ const decodedActorId = this.decodeBase64(actorId);
57
+ const decodedCallId = this.decodeBase64(callId);
58
+
59
+ if (!decodedActorId.endsWith(agentId)) {
60
+ logWxAppMercuryMuteSync({
61
+ phase: 'dropped',
62
+ muted,
63
+ callIdSuffix: callIdSuffix(decodedCallId),
64
+ dropReason: 'actor_id_mismatch',
65
+ });
66
+
67
+ return;
68
+ }
69
+
70
+ logWxAppMercuryMuteSync({
71
+ phase: 'received',
72
+ muted,
73
+ callIdSuffix: callIdSuffix(decodedCallId),
74
+ });
75
+
76
+ this.muteChangeHandler?.(decodedCallId, muted);
77
+ };
78
+
79
+ public subscribe(agentId: string, onMuteChange: MuteChangeHandler): void {
80
+ this.unsubscribe();
81
+
82
+ const mercury = this.webex.internal.mercury;
83
+ if (!mercury) {
84
+ LoggerProxy.error('Mercury is unavailable for wxApp mute sync', {
85
+ module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
86
+ method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
87
+ });
88
+
89
+ MetricsManager.getInstance().trackEvent(
90
+ METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_FAILED,
91
+ {error: 'Mercury is unavailable for wxApp mute sync', mercurySubscribed: false},
92
+ ['operational', 'behavioral']
93
+ );
94
+
95
+ return;
96
+ }
97
+
98
+ this.subscribedAgentId = agentId;
99
+ this.muteChangeHandler = onMuteChange;
100
+
101
+ this.boundMuteHandler = (event: UpdatedCallMuteStateEvent) => {
102
+ this.handleMuteStateEvent(agentId, event);
103
+ };
104
+ this.boundUnmuteHandler = (event: UpdatedCallMuteStateEvent) => {
105
+ this.handleMuteStateEvent(agentId, event);
106
+ };
107
+
108
+ mercury.on(TELEPHONY_CALL_MUTED, this.boundMuteHandler);
109
+ mercury.on(TELEPHONY_CALL_UNMUTED, this.boundUnmuteHandler);
110
+
111
+ MetricsManager.getInstance().trackEvent(
112
+ METRIC_EVENT_NAMES.WXAPP_MERCURY_SUBSCRIBE_SUCCESS,
113
+ {mercurySubscribed: true},
114
+ ['operational', 'behavioral']
115
+ );
116
+
117
+ LoggerProxy.log('Subscribed to wxApp telephony Mercury mute sync', {
118
+ module: WXAPP_TELEPHONY_MERCURY_SYNC_FILE,
119
+ method: METHODS.SYNC_WXAPP_MUTE_FROM_MERCURY,
120
+ });
121
+ }
122
+
123
+ public unsubscribe(): void {
124
+ const mercury = this.webex.internal.mercury;
125
+
126
+ if (mercury && this.boundMuteHandler) {
127
+ mercury.off(TELEPHONY_CALL_MUTED, this.boundMuteHandler);
128
+ }
129
+ if (mercury && this.boundUnmuteHandler) {
130
+ mercury.off(TELEPHONY_CALL_UNMUTED, this.boundUnmuteHandler);
131
+ }
132
+
133
+ this.subscribedAgentId = undefined;
134
+ this.muteChangeHandler = undefined;
135
+ this.boundMuteHandler = undefined;
136
+ this.boundUnmuteHandler = undefined;
137
+ }
138
+
139
+ public isSubscribed(): boolean {
140
+ return Boolean(this.subscribedAgentId && this.muteChangeHandler);
141
+ }
142
+ }
@@ -14,7 +14,7 @@ const cc = webex.cc;
14
14
  // Register and login
15
15
  const profile = await cc.register();
16
16
  await cc.stationLogin({
17
- teamId: profile.teams[0].teamId,
17
+ teamId: profile.teams[0].id,
18
18
  loginOption: 'BROWSER',
19
19
  });
20
20
 
@@ -87,6 +87,7 @@ Key nested WebSocket binds use the actual outer/data constants, for example `CC_
87
87
  | AGENT-R-003 | Buddy-agent lookup must preserve its typed request and correlated response contract. | Consult/transfer selection depends on backend-filtered availability. | `src/services/agent/index.ts` | `test/unit/spec/services/agent/index.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
88
88
  | AGENT-R-004 | The agent factory exposes `reload`, while ContactCenter alone decides when automated relogin is permitted. | Transport recovery lacks the profile/policy context required to mutate an agent session safely. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
89
89
  | AGENT-R-005 | Device/profile update must be documented as `ContactCenter.updateAgentProfile`, not as an agent-factory method. | Calling a non-existent `routingAgent.deviceUpdate` would fail at runtime. | `src/cc.ts` | `test/unit/spec/cc.ts` | None; source and test evidence rechecked during the 2026-07-09 remediation; independent document revalidation pending. | PRESENT |
90
+ | AGENT-R-006 | BROWSER station login must send `dialNumber` and `deviceId` as `webrtc-{agentId}` on `POST /v1/agents/login`. EXTENSION and AGENT_DN continue to send the caller-supplied dial number for both fields. | QRM stores `agent.dn` from `dialNumber`. Legacy VPOP RTMS only treats a DN as WebRTC when it starts with `webrtc-`; a bare UUID gets a steering prefix and the agent invite fails with SIP 484. | `src/cc.ts` | `test/unit/spec/cc.ts` | Public `stationLogin({loginOption: 'BROWSER'})` input is unchanged; only the backend login payload is prefixed. | PRESENT |
90
91
 
91
92
  ## Design Overview
92
93
  `routingAgent` is a pure AQM factory. It receives an initialized AqmReqs instance and returns five request functions: `reload`, `logout`, `stationLogin`, `stateChange`, and `buddyAgents`. Each request config declares the endpoint/payload plus exact `CC_EVENTS` notification binds.
@@ -109,12 +109,12 @@ src/services/
109
109
  │ └── ARCHITECTURE.md
110
110
  │
111
111
  ├── AddressBook.ts # Address book entries — getEntries() with pagination/cache
112
- ├── EntryPoint.ts # Entry points — getEntryPoints() with pagination/cache
112
+ ├── EntryPoint.ts # Profile-scoped entry-point dial-number mappings (uncached)
113
113
  ├── Queue.ts # Queues — getQueues() with pagination/cache
114
114
  └── WebCallingService.ts # WebRTC calling — register/deregister line, answer/mute/decline
115
115
  ```
116
116
 
117
- Note: The `src/utils/` folder (sibling to `src/services/`) contains shared utilities like [`PageCache.ts`](../../utils/PageCache.ts) which provides generic pagination caching with `BaseSearchParams`, `PaginatedResponse`, and `PaginationMeta` types used by all data services.
117
+ Note: The `src/utils/` folder (sibling to `src/services/`) contains [`PageCache.ts`](../../utils/PageCache.ts), which provides pagination contracts/defaults shared by data-service types and optional page caching used by AddressBook and Queue. EntryPoint deliberately bypasses PageCache because every request is profile-scoped.
118
118
 
119
119
  ### Shared Constants (`src/services/constants.ts`)
120
120
 
@@ -137,8 +137,8 @@ Use [`constants.ts`](../constants.ts) as the canonical source for service-level
137
137
  | **Task Management** | [`task/`](../task/TaskManager.ts) | Task lifecycle (accept, hold, transfer, conference, wrapup), Task state machine, contact operations, outbound dialing |
138
138
  | **Configuration** | [`config/`](../config/index.ts) | Agent profile aggregation from 8+ API endpoints, org settings, teams, aux codes, dial plans |
139
139
  | **Core Infrastructure** | [`core/`](../core/WebexRequest.ts) | HTTP requests (`WebexRequest`), WebSocket management (`WebSocketManager`), connection lifecycle (`ConnectionService`), AQM request/response correlation (`AqmReqs`), error handling (`Utils`, `Err`) |
140
- | **Data Services** | [`AddressBook.ts`](../AddressBook.ts), [`Queue.ts`](../Queue.ts), [`EntryPoint.ts`](../EntryPoint.ts) | Standalone REST-based data services with pagination and caching for address books, queues, and entry points |
141
- | **Utilities** | [`src/utils/PageCache.ts`](../../utils/PageCache.ts) | Shared `PageCache<T>` generic class for pagination caching, plus `BaseSearchParams`, `PaginatedResponse`, and `PaginationMeta` types used by all data services |
140
+ | **Data Services** | [`AddressBook.ts`](../AddressBook.ts), [`Queue.ts`](../Queue.ts), [`EntryPoint.ts`](../EntryPoint.ts) | Standalone REST-based paginated services; AddressBook and Queue optionally cache eligible pages, while profile-scoped EntryPoint requests are always fetched |
141
+ | **Utilities** | [`src/utils/PageCache.ts`](../../utils/PageCache.ts) | Shared pagination contracts/defaults plus optional `PageCache<T>` reuse for AddressBook and Queue |
142
142
  | **WebRTC Calling** | [`WebCallingService.ts`](../WebCallingService.ts) | Browser-based voice calling via `@webex/calling`, line registration, call answer/mute/decline |
143
143
 
144
144
  ---
@@ -156,7 +156,7 @@ Each service folder contains its own `ai-docs/` with detailed documentation. **A
156
156
 
157
157
  > **Note**: The task state machine (`task/state-machine/`) is part of the Task service, not a separate service. Its dedicated docs live at [`task/state-machine/ai-docs/AGENTS.md`](../task/state-machine/ai-docs/AGENTS.md) and [`ARCHITECTURE.md`](../task/state-machine/ai-docs/ARCHITECTURE.md). Load these when working on state transitions, guards, or actions.
158
158
 
159
- **Data services** (AddressBook, Queue, EntryPoint) do not have dedicated ai-docs. Read their source files directly — they follow shared REST/pagination/caching patterns documented in [`ai-docs/patterns/typescript-patterns.md`](../../../ai-docs/patterns/typescript-patterns.md).
159
+ **Data services** (AddressBook, Queue, EntryPoint) do not have dedicated ai-docs. Read their source files directly. They share direct REST, pagination, logging, metrics, and error propagation, but cache policy is service-owned: AddressBook/Queue use PageCache when eligible and EntryPoint always fetches its profile-scoped mapping.
160
160
 
161
161
  **WebCallingService** also has no dedicated ai-docs, but it follows a different pattern: EventEmitter-based call lifecycle orchestration around `@webex/calling` (`createClient`, line registration/deregistration, `ICall` events), `callTaskMap` tracking, and async registration flows with timeout handling. Read [`WebCallingService.ts`](../WebCallingService.ts) directly when changing browser calling behavior.
162
162
 
@@ -271,16 +271,16 @@ const services = Services.getInstance({
271
271
 
272
272
  ## Data Services Pattern (AddressBook, Queue, EntryPoint)
273
273
 
274
- These three services share an identical pattern. Use any one as a reference when creating similar services:
274
+ These services share the direct REST and pagination pattern, with service-specific request mapping and cache policy:
275
275
 
276
276
  | Aspect | Pattern |
277
277
  |---|---|
278
- | **Class structure** | Standalone class with `WebexRequest`, `WebexSDK`, `MetricsManager`, `PageCache` |
278
+ | **Class structure** | Standalone class with `WebexRequest`, `WebexSDK`, and `MetricsManager`; cache-enabled services additionally own `PageCache` |
279
279
  | **Constructor** | `constructor(webex: WebexSDK)` — gets singletons via `.getInstance()` |
280
280
  | **HTTP calls** | `this.webexRequest.request({service: WCC_API_GATEWAY, resource, method: HTTP_METHODS.GET})` |
281
281
  | **Endpoints** | Uses `endPointMap` functions from `config/constants.ts` to build URL paths |
282
- | **Pagination** | Query params with `page`, `pageSize`; uses `PageCache` for caching |
283
- | **Caching** | `PageCache<T>` — caches pages for simple pagination, bypasses cache for search/filter |
282
+ | **Pagination** | Query params with `page` and `pageSize` |
283
+ | **Caching** | AddressBook/Queue may use `PageCache<T>` for eligible pages; EntryPoint always fetches because its request is desktop-profile scoped |
284
284
  | **Metrics** | `timeEvent` on API call start, `trackEvent` on success/failure |
285
285
  | **Logging** | `LoggerProxy` with `{module: 'ClassName', method: 'methodName'}` context |
286
286
  | **Error handling** | try/catch with `LoggerProxy.error` + `metricsManager.trackEvent` for failures, then re-throw so callers receive the error |
@@ -288,7 +288,7 @@ These three services share an identical pattern. Use any one as a reference when
288
288
  Reference files:
289
289
  - [`AddressBook.ts`](../AddressBook.ts) — includes `addressBookId` parameter
290
290
  - [`Queue.ts`](../Queue.ts) — includes additional query params (sortBy, sortOrder, etc.)
291
- - [`EntryPoint.ts`](../EntryPoint.ts) — simplest example
291
+ - [`EntryPoint.ts`](../EntryPoint.ts) — profile-scoped dial-number mapping without PageCache
292
292
 
293
293
  ---
294
294