@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
@@ -0,0 +1,286 @@
1
+ import LoggerProxy from '../logger-proxy';
2
+
3
+ export const WXAPP_LOG_FEATURE = 'wxApp';
4
+ export const WXAPP_LOG_PREFIX = '[CC wxApp]';
5
+
6
+ export type WxAppAcceptReason =
7
+ | 'wxApp_offer_ready'
8
+ | 'wxApp_answer_pending'
9
+ | 'wxApp_accept_in_flight'
10
+ | 'extension_non_wxApp_offer'
11
+ | 'browser_webrtc_offer'
12
+ | 'outdial_auto_answer';
13
+
14
+ export type WxAppSessionSkipReason =
15
+ | 'unsupported_browser_login'
16
+ | 'flag_disabled'
17
+ | 'mercury_subscribe_failed'
18
+ | 'publish_failed';
19
+
20
+ export type WxAppTelephonyAction = 'accept' | 'decline' | 'mute' | 'dtmf';
21
+ export type WxAppTelephonyPhase = 'started' | 'success' | 'failed';
22
+
23
+ type WxAppLogData = Record<string, string | boolean | number | undefined>;
24
+
25
+ /** Last 8 chars of callId for correlation without logging full id. */
26
+ export function callIdSuffix(callId: string | null | undefined): string | undefined {
27
+ if (!callId) {
28
+ return undefined;
29
+ }
30
+
31
+ return callId.length <= 8 ? callId : callId.slice(-8);
32
+ }
33
+
34
+ function formatLogSuffix(data: WxAppLogData, keys?: string[]): string {
35
+ const entries = keys
36
+ ? keys.map((key) => [key, data[key]] as const)
37
+ : Object.entries(data).filter(([key]) => key !== 'feature' && key !== 'event');
38
+
39
+ const parts = entries
40
+ .filter(([, value]) => value !== undefined && value !== null && value !== '')
41
+ .map(([key, value]) => `${key}=${String(value)}`);
42
+
43
+ return parts.length > 0 ? ` ${parts.join(' ')}` : '';
44
+ }
45
+
46
+ function logWxApp(
47
+ message: string,
48
+ method: string,
49
+ data: WxAppLogData,
50
+ suffixKeys?: string[]
51
+ ): void {
52
+ const suffix = formatLogSuffix(data, suffixKeys);
53
+ LoggerProxy.log(`${WXAPP_LOG_PREFIX} ${message}${suffix}`, {
54
+ module: 'wxAppDiagnosticLogging',
55
+ method,
56
+ data: {feature: WXAPP_LOG_FEATURE, ...data},
57
+ });
58
+ }
59
+
60
+ function logWxAppWarn(
61
+ message: string,
62
+ method: string,
63
+ data: WxAppLogData,
64
+ suffixKeys?: string[]
65
+ ): void {
66
+ const suffix = formatLogSuffix(data, suffixKeys);
67
+ LoggerProxy.warn(`${WXAPP_LOG_PREFIX} ${message}${suffix}`, {
68
+ module: 'wxAppDiagnosticLogging',
69
+ method,
70
+ data: {feature: WXAPP_LOG_FEATURE, ...data},
71
+ });
72
+ }
73
+
74
+ function logWxAppError(
75
+ message: string,
76
+ method: string,
77
+ data: WxAppLogData,
78
+ suffixKeys?: string[]
79
+ ): void {
80
+ const suffix = formatLogSuffix(data, suffixKeys);
81
+ LoggerProxy.error(`${WXAPP_LOG_PREFIX} ${message}${suffix}`, {
82
+ module: 'wxAppDiagnosticLogging',
83
+ method,
84
+ data: {feature: WXAPP_LOG_FEATURE, ...data},
85
+ });
86
+ }
87
+
88
+ export function logWxAppSessionReadiness(params: {
89
+ enableWxBetterTogether: boolean;
90
+ loginOption: string | undefined;
91
+ wxAppHooksApplied: boolean;
92
+ usersubPublished: boolean;
93
+ mercurySubscribed: boolean;
94
+ telephonyTaskType: 'Voice' | 'WebRTC' | 'unknown';
95
+ skipReason?: WxAppSessionSkipReason;
96
+ }): void {
97
+ const data: WxAppLogData = {
98
+ event: 'session_readiness',
99
+ enableWxBetterTogether: params.enableWxBetterTogether,
100
+ loginOption: params.loginOption,
101
+ wxAppHooksApplied: params.wxAppHooksApplied,
102
+ usersubPublished: params.usersubPublished,
103
+ mercurySubscribed: params.mercurySubscribed,
104
+ telephonyTaskType: params.telephonyTaskType,
105
+ skipReason: params.skipReason,
106
+ };
107
+
108
+ logWxApp('session readiness', 'logWxAppSessionReadiness', data, [
109
+ 'usersubPublished',
110
+ 'mercurySubscribed',
111
+ 'loginOption',
112
+ 'enableWxBetterTogether',
113
+ 'telephonyTaskType',
114
+ 'skipReason',
115
+ ]);
116
+ }
117
+
118
+ export function deriveWxAppAcceptReason(params: {
119
+ isWxAppInboundOffer: boolean;
120
+ isWxAppOutdialOffer: boolean;
121
+ isWebrtc: boolean;
122
+ isOutdial: boolean;
123
+ wxAppAcceptInFlight: boolean;
124
+ wxAppAnswerPending: boolean;
125
+ enableWxBetterTogether: boolean;
126
+ hasDeviceCallId: boolean;
127
+ }): WxAppAcceptReason {
128
+ if (params.isWxAppInboundOffer || params.isWxAppOutdialOffer) {
129
+ if (params.wxAppAcceptInFlight) {
130
+ return 'wxApp_accept_in_flight';
131
+ }
132
+ if (params.wxAppAnswerPending) {
133
+ return 'wxApp_answer_pending';
134
+ }
135
+
136
+ return 'wxApp_offer_ready';
137
+ }
138
+
139
+ if (params.isWebrtc && !params.isOutdial) {
140
+ return 'browser_webrtc_offer';
141
+ }
142
+
143
+ if (params.isOutdial) {
144
+ return 'outdial_auto_answer';
145
+ }
146
+
147
+ if (params.enableWxBetterTogether && !params.hasDeviceCallId) {
148
+ return 'extension_non_wxApp_offer';
149
+ }
150
+
151
+ return 'extension_non_wxApp_offer';
152
+ }
153
+
154
+ export function logWxAppOfferDecision(params: {
155
+ interactionId: string;
156
+ acceptVisible: boolean;
157
+ acceptEnabled: boolean;
158
+ acceptReason: WxAppAcceptReason;
159
+ wxAppParticipantDeviceType?: string;
160
+ hasDeviceCallId: boolean;
161
+ hasDeviceId?: boolean;
162
+ usersubPublished?: boolean;
163
+ }): void {
164
+ const data: WxAppLogData = {
165
+ event: 'offer_decision',
166
+ interactionId: params.interactionId,
167
+ acceptVisible: params.acceptVisible,
168
+ acceptEnabled: params.acceptEnabled,
169
+ acceptReason: params.acceptReason,
170
+ wxAppParticipantDeviceType: params.wxAppParticipantDeviceType,
171
+ hasDeviceCallId: params.hasDeviceCallId,
172
+ hasDeviceId: params.hasDeviceId,
173
+ usersubPublished: params.usersubPublished,
174
+ };
175
+
176
+ logWxApp('offer decision', 'logWxAppOfferDecision', data, [
177
+ 'acceptReason',
178
+ 'hasDeviceCallId',
179
+ 'hasDeviceId',
180
+ 'usersubPublished',
181
+ 'interactionId',
182
+ 'acceptVisible',
183
+ 'acceptEnabled',
184
+ ]);
185
+ }
186
+
187
+ export function logWxAppOfferParticipantMismatch(params: {
188
+ interactionId: string;
189
+ usersubPublished: boolean;
190
+ hasDeviceCallId: boolean;
191
+ hasDeviceId: boolean;
192
+ participantDeviceType?: string;
193
+ acceptVisible: boolean;
194
+ acceptEnabled: boolean;
195
+ acceptReason: WxAppAcceptReason;
196
+ }): void {
197
+ const data: WxAppLogData = {
198
+ event: 'participant_fields_mismatch',
199
+ interactionId: params.interactionId,
200
+ usersubPublished: params.usersubPublished,
201
+ hasDeviceCallId: params.hasDeviceCallId,
202
+ hasDeviceId: params.hasDeviceId,
203
+ participantDeviceType: params.participantDeviceType ?? 'missing',
204
+ acceptVisible: params.acceptVisible,
205
+ acceptEnabled: params.acceptEnabled,
206
+ acceptReason: params.acceptReason,
207
+ };
208
+
209
+ logWxAppWarn('participant fields mismatch', 'logWxAppOfferParticipantMismatch', data, [
210
+ 'usersubPublished',
211
+ 'hasDeviceCallId',
212
+ 'hasDeviceId',
213
+ 'acceptReason',
214
+ 'interactionId',
215
+ 'participantDeviceType',
216
+ ]);
217
+ }
218
+
219
+ export function logWxAppTelephonyAction(params: {
220
+ action: WxAppTelephonyAction;
221
+ phase: WxAppTelephonyPhase;
222
+ interactionId?: string;
223
+ trackingId?: string;
224
+ httpStatus?: number | string;
225
+ failureReason?: string;
226
+ }): void {
227
+ const payload: WxAppLogData = {
228
+ event: 'telephony_action',
229
+ action: params.action,
230
+ phase: params.phase,
231
+ interactionId: params.interactionId,
232
+ trackingId: params.trackingId,
233
+ httpStatus: params.httpStatus,
234
+ failureReason: params.failureReason,
235
+ };
236
+
237
+ if (params.phase === 'failed') {
238
+ logWxAppError(
239
+ `telephony ${params.action} ${params.phase}`,
240
+ 'logWxAppTelephonyAction',
241
+ payload,
242
+ ['interactionId', 'trackingId', 'httpStatus', 'failureReason']
243
+ );
244
+ } else {
245
+ logWxApp(`telephony ${params.action} ${params.phase}`, 'logWxAppTelephonyAction', payload, [
246
+ 'interactionId',
247
+ 'action',
248
+ 'phase',
249
+ ]);
250
+ }
251
+ }
252
+
253
+ export function logWxAppValidationFailure(reason: string, interactionId?: string): void {
254
+ logWxAppError(
255
+ 'validation failed',
256
+ 'logWxAppValidationFailure',
257
+ {
258
+ event: 'validation_failed',
259
+ reason,
260
+ interactionId,
261
+ },
262
+ ['reason', 'interactionId']
263
+ );
264
+ }
265
+
266
+ export function logWxAppMercuryMuteSync(params: {
267
+ phase: 'received' | 'applied' | 'dropped';
268
+ muted?: boolean;
269
+ callIdSuffix?: string;
270
+ interactionId?: string;
271
+ dropReason?: string;
272
+ }): void {
273
+ logWxApp(
274
+ `mercury mute sync ${params.phase}`,
275
+ 'logWxAppMercuryMuteSync',
276
+ {
277
+ event: 'mercury_mute_sync',
278
+ phase: params.phase,
279
+ muted: params.muted,
280
+ callIdSuffix: params.callIdSuffix,
281
+ interactionId: params.interactionId,
282
+ dropReason: params.dropReason,
283
+ },
284
+ ['phase', 'muted', 'callIdSuffix', 'interactionId', 'dropReason']
285
+ );
286
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Expected Hydra responses when mute backfill races call creation (WXCC-6026).
3
+ * These must not be logged as errors — see task-spec wxApp mute backfill guard.
4
+ */
5
+ export function isWxAppCallNotFoundError(error: unknown): boolean {
6
+ const err = error as {status?: number | string; message?: string};
7
+ if (err?.status === 400 || err?.status === '400') {
8
+ return true;
9
+ }
10
+
11
+ const message = String(err?.message ?? error ?? '');
12
+
13
+ return message.includes('Call not found') || message.includes('101002');
14
+ }
package/src/types.ts CHANGED
@@ -8,6 +8,7 @@ import * as Agent from './services/agent/types';
8
8
  import * as Contact from './services/task/types';
9
9
  import {
10
10
  AIFeatureFlags,
11
+ Entity,
11
12
  Profile,
12
13
  CreateUserPreferenceRequest,
13
14
  UpdateUserPreferenceRequest,
@@ -74,6 +75,8 @@ export type WebexRequestPayload = {
74
75
  uri?: string;
75
76
  /** Whether to add authorization header */
76
77
  addAuthHeader?: boolean;
78
+ /** Request timeout in milliseconds */
79
+ timeout?: number;
77
80
  /** Custom headers to include in request */
78
81
  headers?: {
79
82
  [key: string]: string | null;
@@ -93,12 +96,19 @@ export type WebexRequestPayload = {
93
96
  */
94
97
  type Listener = (e: string, data?: unknown) => void;
95
98
 
99
+ /**
100
+ * Mercury event handler callback.
101
+ * @internal
102
+ * @ignore
103
+ */
104
+ type MercuryEventHandler = (data?: unknown) => void;
105
+
96
106
  /**
97
107
  * Event listener removal function type.
98
108
  * @internal
99
109
  * @ignore
100
110
  */
101
- type ListenerOff = (e: string) => void;
111
+ type ListenerOff = (e: string, handler?: MercuryEventHandler) => void;
102
112
 
103
113
  /**
104
114
  * Service host configuration.
@@ -163,6 +173,8 @@ export interface CCPluginConfig {
163
173
  callingClientConfig: CallingClientConfig;
164
174
  /** Whether to skip Mobius/WebRTC registration for browser login flows */
165
175
  disableWebRTCRegistration?: boolean;
176
+ /** Whether wxApp Better Together (telephony REST + usersub) is enabled at init (WXCC-6026) */
177
+ enableWxBetterTogether?: boolean;
166
178
  }
167
179
 
168
180
  /**
@@ -293,6 +305,12 @@ interface IWebexInternal {
293
305
  version: string;
294
306
  /** Calling behavior configuration */
295
307
  callingBehavior: string;
308
+ /** Whether the device is registered with WDM */
309
+ registered?: boolean;
310
+ /** Register the device with WDM */
311
+ register?: () => Promise<void>;
312
+ /** Unregister the device from WDM */
313
+ unregister?: () => Promise<void>;
296
314
  };
297
315
  /** Presence service */
298
316
  presence: unknown;
@@ -404,6 +422,9 @@ export interface IContactCenter {
404
422
  * cc.register().then(profile => { ... });
405
423
  */
406
424
  register(): Promise<Profile>;
425
+
426
+ /** Returns the system-managed WellbeingBreak idle code for the registered session. */
427
+ getWellbeingBreakIdleCode(): Promise<Entity>;
407
428
  }
408
429
 
409
430
  /**
@@ -555,18 +576,16 @@ export type RequestBody =
555
576
 
556
577
  /**
557
578
  * Represents the options to fetch buddy agents for the logged in agent.
558
- * Buddy agents are other agents who can be consulted or transfered to.
579
+ * Buddy agents are other agents who can be consulted or transferred to.
559
580
  * @public
560
581
  * @example
561
582
  * const opts: BuddyAgents = { mediaType: 'telephony', state: 'Available' };
562
- * @ignore
563
583
  */
564
584
  export type BuddyAgents = {
565
585
  /**
566
- * The media type channel to filter buddy agents.
567
- * Determines which channel capability the returned agents must have.
586
+ * The media type channel to filter buddy agents. Defaults to telephony when omitted.
568
587
  */
569
- mediaType: 'telephony' | 'chat' | 'social' | 'email';
588
+ mediaType?: 'telephony' | 'chat' | 'social' | 'email';
570
589
 
571
590
  /**
572
591
  * Optional filter for agent state.
@@ -574,6 +593,11 @@ export type BuddyAgents = {
574
593
  * If omitted, returns both available and idle agents.
575
594
  */
576
595
  state?: 'Available' | 'Idle';
596
+
597
+ /**
598
+ * Applies the default state policy for the operation. An explicit state takes precedence.
599
+ */
600
+ action?: 'Consult' | 'Transfer';
577
601
  };
578
602
 
579
603
  /**
@@ -587,11 +611,17 @@ export type ConfigFlags = {
587
611
  webRtcEnabled: boolean;
588
612
  autoWrapup: boolean;
589
613
  aiFeature?: AIFeatureFlags;
614
+ /** Agent-profile policy used to derive task consult/transfer destination controls. */
615
+ consultTransfer?: Contact.ConsultTransferDestinationConfig;
590
616
  /**
591
617
  * Optional toggle to globally enable/disable recording controls.
592
618
  * Falls back to backend hints when omitted.
593
619
  */
594
620
  isRecordingEnabled?: boolean;
621
+ /** Whether wxApp thick-client answer controls/APIs are enabled (WXCC-6026) */
622
+ enableWxBetterTogether?: boolean;
623
+ /** Read-only observability: live usersub answer-calls-on-wxcc state for wxApp offer diagnostics. */
624
+ getWxAppUsersubPublished?: () => boolean;
595
625
  };
596
626
 
597
627
  /**
@@ -681,10 +711,12 @@ export interface AddressBookEntrySearchParams extends BaseSearchParams {
681
711
  export interface EntryPointRecord {
682
712
  id: string;
683
713
  name: string;
714
+ /** Dialled number mapped to this entry point when included in the list response. */
715
+ number?: string;
684
716
  description?: string;
685
- type: string;
686
- isActive: boolean;
687
- orgId: string;
717
+ type?: string;
718
+ isActive?: boolean;
719
+ orgId?: string;
688
720
  createdAt?: string;
689
721
  updatedAt?: string;
690
722
  settings?: Record<string, any>;
@@ -921,6 +953,63 @@ export type RealTimeAssistanceUserActionParams = {
921
953
  languageCode?: string;
922
954
  };
923
955
 
956
+ /**
957
+ * Wellness notification actions delivered by the Contact Center notification service.
958
+ * @public
959
+ */
960
+ export const WELLNESS_BREAK_NOTIFICATION_ACTIONS = {
961
+ PROVIDE_WELLNESS_BREAK: 'PROVIDE_WELLNESS_BREAK',
962
+ SUGGEST_WELLNESS_BREAK: 'SUGGEST_WELLNESS_BREAK',
963
+ WELLNESS_BREAK_NOT_ALLOWED: 'WELLNESS_BREAK_NOT_ALLOWED',
964
+ } as const;
965
+
966
+ /** Union of supported wellness notification actions. @public */
967
+ export type WellnessBreakNotificationAction = Enum<typeof WELLNESS_BREAK_NOTIFICATION_ACTIONS>;
968
+
969
+ /**
970
+ * Agent actions accepted by the wellness action API.
971
+ * @public
972
+ */
973
+ export const WELLNESS_BREAK_USER_ACTIONS = {
974
+ REQUESTED: 'REQUESTED',
975
+ ACCEPTED: 'ACCEPTED',
976
+ REJECTED: 'REJECTED',
977
+ NO_RESPONSE: 'NO_RESPONSE',
978
+ } as const;
979
+
980
+ /** Union of supported wellness action API values. @public */
981
+ export type WellnessBreakUserAction = Enum<typeof WELLNESS_BREAK_USER_ACTIONS>;
982
+
983
+ /**
984
+ * Validated, agent-scoped wellness notification emitted by Contact Center.
985
+ * @public
986
+ */
987
+ export interface WellnessBreakEvent {
988
+ /** Agent identifier */
989
+ agentId: string;
990
+ /** Organization identifier */
991
+ orgId: string;
992
+ /** Session identifier supplied by the notification; it may differ from the consumer's active session */
993
+ agentSessionId: string;
994
+ /** Backend wellness action */
995
+ actionEvent: WellnessBreakNotificationAction;
996
+ /** Optional untrusted plain-text message supplied by the backend */
997
+ actionText?: string;
998
+ /** Optional normalized interaction diagnostic */
999
+ interactionId?: string;
1000
+ /** Notification diagnostic only; never an action-request correlation identifier */
1001
+ trackingId?: string;
1002
+ }
1003
+
1004
+ /**
1005
+ * Parameters for responding to a backend-provided wellness offer.
1006
+ * @public
1007
+ */
1008
+ export interface RespondToWellnessBreakParams {
1009
+ /** Agent response; REQUESTED is available only through requestWellnessBreak */
1010
+ action: Exclude<WellnessBreakUserAction, typeof WELLNESS_BREAK_USER_ACTIONS.REQUESTED>;
1011
+ }
1012
+
924
1013
  /**
925
1014
  * Supported AI Assistant event categories.
926
1015
  * @public
@@ -958,18 +1047,24 @@ export const AIAssistantEventName = {
958
1047
  GET_SUGGESTIONS: 'GET_SUGGESTIONS',
959
1048
  /** Add extra context to refine a suggested response */
960
1049
  ADD_SUGGESTIONS_EXTRA_CONTEXT: 'ADD_SUGGESTIONS_EXTRA_CONTEXT',
961
- /** Request mid-call summary generation */
962
- GET_MID_CALL_SUMMARY: 'GET_MID_CALL_SUMMARY',
963
1050
  /** Request post-call summary generation */
964
1051
  GET_POST_CALL_SUMMARY: 'GET_POST_CALL_SUMMARY',
965
- /** Mid-call summary response event */
966
- MID_CALL_SUMMARY_RESPONSE: 'MID_CALL_SUMMARY_RESPONSE',
1052
+ /** Request consult mid-call summary generation */
1053
+ GET_MID_CALL_CONSULT_SUMMARY: 'GET_MID_CALL_CONSULT_SUMMARY',
1054
+ /** Request transfer mid-call summary generation */
1055
+ GET_MID_CALL_TRANSFER_SUMMARY: 'GET_MID_CALL_TRANSFER_SUMMARY',
967
1056
  /** Post-call summary response event */
968
1057
  POST_CALL_SUMMARY_RESPONSE: 'POST_CALL_SUMMARY_RESPONSE',
1058
+ /** Consult mid-call summary response event */
1059
+ MID_CALL_CONSULT_SUMMARY_RESPONSE: 'MID_CALL_CONSULT_SUMMARY_RESPONSE',
1060
+ /** Transfer mid-call summary response event */
1061
+ MID_CALL_TRANSFER_SUMMARY_RESPONSE: 'MID_CALL_TRANSFER_SUMMARY_RESPONSE',
969
1062
  /** Suggested digital response event */
970
1063
  SUGGESTED_RESPONSES_DIGITAL: 'SUGGESTED_RESPONSES_DIGITAL',
971
1064
  /** User action on a suggested response adaptive card */
972
1065
  SUGGESTED_RESPONSES_USER_ACTION: 'SUGGESTED_RESPONSES_USER_ACTION',
1066
+ /** Agent Wellness Break request/response action */
1067
+ WELLNESS_BREAK_ACTION: 'WellnessBreakAction',
973
1068
  } as const;
974
1069
 
975
1070
  /**
@@ -12,7 +12,7 @@ The utils scope currently provides shared pagination and cache behavior for cont
12
12
 
13
13
  - **Typed Pagination Contracts**: Reusable interfaces for response metadata and query params
14
14
  - **Generic In-Memory Page Caching**: `PageCache<T>` utility for simple pagination reuse
15
- - **Cache Safety Rules**: Explicit bypass behavior for search/filter/sort scenarios
15
+ - **Cache Safety Rules**: Explicit bypass behavior for query variants and enabled result/response-shape flags
16
16
  - **Spec-Driven Utility Workflow**: Utility-specific implementation and validation flow documented inline in this file
17
17
 
18
18
  | Component | File | Description |
@@ -36,7 +36,7 @@ src/utils/
36
36
 
37
37
  ## PageCache Utility
38
38
 
39
- `PageCache<T>` provides a consistent caching model for paginated list APIs. It is optimized for simple page browsing and intentionally bypasses cache for parameterized query cases (`search`, `filter`, `attributes`, `sortBy`).
39
+ `PageCache<T>` provides a consistent caching model for paginated list APIs. It is optimized for simple page browsing and intentionally bypasses cache for parameterized query cases (`search`, `filter`, `attributes`, `sortBy`) and enabled result/response-shape flags (`desktopProfileFilter`, `provisioningView`, `singleObjectResponse`).
40
40
 
41
41
  ### Reference Usage
42
42
 
@@ -49,8 +49,16 @@ const page = PAGINATION_DEFAULTS.PAGE;
49
49
  const pageSize = PAGINATION_DEFAULTS.PAGE_SIZE;
50
50
  const cacheKey = cache.buildCacheKey(scopeId, page, pageSize);
51
51
 
52
- // Include sortBy only for services that support sorting.
53
- const canUseCache = cache.canUseCache({search, filter, attributes, sortBy});
52
+ // Include every supported result- or response-shape-changing input.
53
+ const canUseCache = cache.canUseCache({
54
+ search,
55
+ filter,
56
+ attributes,
57
+ sortBy,
58
+ desktopProfileFilter,
59
+ provisioningView,
60
+ singleObjectResponse,
61
+ });
54
62
 
55
63
  if (canUseCache) {
56
64
  const cachedEntry = cache.getCachedPage(cacheKey);
@@ -80,7 +88,7 @@ return response;
80
88
  ```mermaid
81
89
  graph TD
82
90
  A[Request arrives with scopeId/page/pageSize] --> B{canUseCache?}
83
- B -->|No: search/filter/attributes/sortBy provided| C[Bypass cache and call API]
91
+ B -->|No: query variant or enabled result/shape flag| C[Bypass cache and call API]
84
92
  B -->|Yes| D[buildCacheKey scopeId:page:pageSize]
85
93
  D --> E["getCachedPage(cacheKey)"]
86
94
  E -->|Miss| C
@@ -138,11 +146,14 @@ Contract passed to `canUseCache()`:
138
146
  - `filter?: string`
139
147
  - `attributes?: string`
140
148
  - `sortBy?: string`
149
+ - `desktopProfileFilter?: boolean`
150
+ - `provisioningView?: boolean`
151
+ - `singleObjectResponse?: boolean`
141
152
 
142
153
  Behavior note:
143
154
 
144
- - Cache bypass is triggered by `sortBy`, not by `sortOrder` alone.
145
- - If a new service treats `sortOrder` as meaningful without `sortBy`, extend `CacheValidationParams` and `canUseCache()` together.
155
+ - Cache bypass is triggered by a truthy query variant or enabled result/response-shape flag; an explicit `false` boolean remains cache-compatible because it is semantically equivalent to omission.
156
+ - `sortOrder` is not a `CacheValidationParams` field. A service where it changes the wire order without `sortBy` must pass an effective `sortBy`; Queue normalizes a direction-only request to `sortBy: 'name'` before cache validation.
146
157
 
147
158
  ### `BaseSearchParams`
148
159
 
@@ -175,8 +186,9 @@ Returns `true` only when all of these are absent:
175
186
  - `filter`
176
187
  - `attributes`
177
188
  - `sortBy`
189
+ - `desktopProfileFilter`, `provisioningView`, or `singleObjectResponse` when `true`
178
190
 
179
- `sortOrder` alone does not trigger cache bypass because `CacheValidationParams` currently keys bypass on fields that materially change the query result set in existing consumers.
191
+ An explicit `false` boolean remains eligible. `sortOrder` is normalized by the consuming service when it changes the effective wire order; Queue passes `sortBy: 'name'` for a direction-only request.
180
192
 
181
193
  ### `buildCacheKey(scopeId: string, page: number, pageSize: number): string`
182
194
 
@@ -223,7 +235,6 @@ Current consumers of `PageCache` and defaults:
223
235
  | Consumer | File | Usage |
224
236
  | ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
225
237
  | `AddressBook` | [`../services/AddressBook.ts`](../services/AddressBook.ts) | Caches paged address-book responses |
226
- | `EntryPoint` | [`../services/EntryPoint.ts`](../services/EntryPoint.ts) | Caches paged entry-point responses |
227
238
  | `Queue` | [`../services/Queue.ts`](../services/Queue.ts) | Caches paged queue responses |
228
239
  | `Public type contracts` | [`../types.ts`](../types.ts) | Re-exports pagination/search contracts into SDK-facing types |
229
240
 
@@ -268,7 +279,7 @@ flowchart TD
268
279
  - [ ] `canUseCache()` bypass conditions are unchanged or intentionally updated
269
280
  - [ ] `totalRecords`/`totalItems` mapping behavior is preserved
270
281
  - [ ] Logging still uses `LoggerProxy` with `module` and `method`
271
- - [ ] AddressBook/EntryPoint/Queue integration behavior remains correct
282
+ - [ ] AddressBook/Queue cache integration remains correct; EntryPoint remains explicitly uncached
272
283
 
273
284
  ---
274
285
 
@@ -97,6 +97,12 @@ export interface CacheValidationParams {
97
97
  attributes?: string;
98
98
  /** Sort by parameter */
99
99
  sortBy?: string;
100
+ /** Desktop-profile filtering changes the returned result set */
101
+ desktopProfileFilter?: boolean;
102
+ /** Provisioning-view filtering changes the returned result set */
103
+ provisioningView?: boolean;
104
+ /** Single-object response mode changes the response shape */
105
+ singleObjectResponse?: boolean;
100
106
  }
101
107
 
102
108
  /**
@@ -116,8 +122,18 @@ const DEFAULT_CACHE_TTL_MINUTES = 5;
116
122
  * // Create a cache instance for a specific data type
117
123
  * const cache = new PageCache<AddressBookEntry>('AddressBook');
118
124
  *
119
- * // Check if we can use cache (no search/filter parameters)
120
- * if (cache.canUseCache({ search, filter })) {
125
+ * // Check if we can use cache for the complete result/response-shape input set
126
+ * if (
127
+ * cache.canUseCache({
128
+ * search,
129
+ * filter,
130
+ * attributes,
131
+ * sortBy,
132
+ * desktopProfileFilter,
133
+ * provisioningView,
134
+ * singleObjectResponse,
135
+ * })
136
+ * ) {
121
137
  * const cacheKey = cache.buildCacheKey(orgId, page, pageSize);
122
138
  * const cachedPage = cache.getCachedPage(cacheKey);
123
139
  *
@@ -145,15 +161,32 @@ export class PageCache<T> {
145
161
 
146
162
  /**
147
163
  * Checks if cache can be used for the given parameters.
148
- * Cache is only used for simple pagination without search/filter/attributes/sort.
164
+ * Cache is only used for simple pagination without query variants or enabled
165
+ * result/response-shape flags.
149
166
  * @param {CacheValidationParams} params - Parameters to validate
150
167
  * @returns {boolean} True if cache can be used
151
168
  * @public
152
169
  */
153
170
  public canUseCache(params: CacheValidationParams): boolean {
154
- const {search, filter, attributes, sortBy} = params;
171
+ const {
172
+ search,
173
+ filter,
174
+ attributes,
175
+ sortBy,
176
+ desktopProfileFilter,
177
+ provisioningView,
178
+ singleObjectResponse,
179
+ } = params;
155
180
 
156
- return !search && !filter && !attributes && !sortBy;
181
+ return (
182
+ !search &&
183
+ !filter &&
184
+ !attributes &&
185
+ !sortBy &&
186
+ !desktopProfileFilter &&
187
+ !provisioningView &&
188
+ !singleObjectResponse
189
+ );
157
190
  }
158
191
 
159
192
  /**