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

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 +21 -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 +53 -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 +816 -26
  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 +29 -2
  14. package/dist/constants.js.map +1 -1
  15. package/dist/index.js +66 -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 +287 -37
  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 +55 -35
  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 +127 -9
  101. package/dist/types/config.d.ts +7 -0
  102. package/dist/types/constants.d.ts +23 -0
  103. package/dist/types/index.d.ts +38 -17
  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 +150 -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 +125 -13
  141. package/dist/types/utils/PageCache.d.ts +20 -3
  142. package/dist/types.js +90 -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 +1047 -48
  150. package/src/config.ts +7 -0
  151. package/src/constants.ts +36 -0
  152. package/src/index.ts +49 -11
  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 +362 -40
  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 +11 -11
  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 +145 -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 +159 -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 +3595 -120
  217. package/test/unit/spec/index.ts +891 -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 +483 -54
  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;
@@ -384,6 +402,50 @@ export interface WebexSDK {
384
402
  logger: Logger;
385
403
  }
386
404
 
405
+ /** Current browser voice availability. @public */
406
+ export enum VOICE_CONNECTION_STATUS {
407
+ READY = 'ready',
408
+ UNAVAILABLE = 'unavailable',
409
+ NOT_REQUIRED = 'not-required',
410
+ }
411
+
412
+ /** Stable error codes for browser voice availability failures. @public */
413
+ export enum VOICE_CONNECTION_ERROR {
414
+ NOT_READY = 'BROWSER_VOICE_NOT_READY',
415
+ }
416
+
417
+ /** Browser voice line registration states. @public */
418
+ export enum VoiceLineStatus {
419
+ UNKNOWN = 'unknown',
420
+ CONNECTING = 'connecting',
421
+ REGISTERED = 'registered',
422
+ RECONNECTING = 'reconnecting',
423
+ RECONNECTED = 'reconnected',
424
+ UNREGISTERED = 'unregistered',
425
+ ERROR = 'error',
426
+ }
427
+
428
+ /** Mobius socket states reported by the Calling SDK. @public */
429
+ export enum VoiceMobiusSocketStatus {
430
+ UNKNOWN = 'unknown',
431
+ NOT_IN_USE = 'not-in-use',
432
+ CONNECTED = 'connected',
433
+ DISCONNECTED = 'disconnected',
434
+ }
435
+
436
+ /**
437
+ * Current browser voice availability and the underlying line and Mobius states.
438
+ * Mobius socket state is separate from Contact Center WebSocket health.
439
+ * @public
440
+ */
441
+ export type VoiceConnectionState = {
442
+ status: VOICE_CONNECTION_STATUS;
443
+ lineStatus: VoiceLineStatus;
444
+ mobiusSocketStatus: VoiceMobiusSocketStatus;
445
+ reason?: string;
446
+ retryable?: boolean;
447
+ };
448
+
387
449
  /**
388
450
  * An interface for the `ContactCenter` class.
389
451
  * The `ContactCenter` package is designed to provide a set of APIs to perform various operations for the Agent flow within Webex Contact Center.
@@ -404,6 +466,16 @@ export interface IContactCenter {
404
466
  * cc.register().then(profile => { ... });
405
467
  */
406
468
  register(): Promise<Profile>;
469
+
470
+ /** Returns the system-managed WellbeingBreak idle code for the registered session. */
471
+ getWellbeingBreakIdleCode(): Promise<Entity>;
472
+
473
+ /**
474
+ * Returns the current browser voice availability snapshot.
475
+ * @returns Current browser voice state, including line and Mobius socket status
476
+ * @public
477
+ */
478
+ getVoiceConnectionState(): VoiceConnectionState;
407
479
  }
408
480
 
409
481
  /**
@@ -555,18 +627,16 @@ export type RequestBody =
555
627
 
556
628
  /**
557
629
  * 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.
630
+ * Buddy agents are other agents who can be consulted or transferred to.
559
631
  * @public
560
632
  * @example
561
633
  * const opts: BuddyAgents = { mediaType: 'telephony', state: 'Available' };
562
- * @ignore
563
634
  */
564
635
  export type BuddyAgents = {
565
636
  /**
566
- * The media type channel to filter buddy agents.
567
- * Determines which channel capability the returned agents must have.
637
+ * The media type channel to filter buddy agents. Defaults to telephony when omitted.
568
638
  */
569
- mediaType: 'telephony' | 'chat' | 'social' | 'email';
639
+ mediaType?: 'telephony' | 'chat' | 'social' | 'email';
570
640
 
571
641
  /**
572
642
  * Optional filter for agent state.
@@ -574,6 +644,11 @@ export type BuddyAgents = {
574
644
  * If omitted, returns both available and idle agents.
575
645
  */
576
646
  state?: 'Available' | 'Idle';
647
+
648
+ /**
649
+ * Applies the default state policy for the operation. An explicit state takes precedence.
650
+ */
651
+ action?: 'Consult' | 'Transfer';
577
652
  };
578
653
 
579
654
  /**
@@ -587,11 +662,17 @@ export type ConfigFlags = {
587
662
  webRtcEnabled: boolean;
588
663
  autoWrapup: boolean;
589
664
  aiFeature?: AIFeatureFlags;
665
+ /** Agent-profile policy used to derive task consult/transfer destination controls. */
666
+ consultTransfer?: Contact.ConsultTransferDestinationConfig;
590
667
  /**
591
668
  * Optional toggle to globally enable/disable recording controls.
592
669
  * Falls back to backend hints when omitted.
593
670
  */
594
671
  isRecordingEnabled?: boolean;
672
+ /** Whether wxApp thick-client answer controls/APIs are enabled (WXCC-6026) */
673
+ enableWxBetterTogether?: boolean;
674
+ /** Read-only observability: live usersub answer-calls-on-wxcc state for wxApp offer diagnostics. */
675
+ getWxAppUsersubPublished?: () => boolean;
595
676
  };
596
677
 
597
678
  /**
@@ -681,10 +762,12 @@ export interface AddressBookEntrySearchParams extends BaseSearchParams {
681
762
  export interface EntryPointRecord {
682
763
  id: string;
683
764
  name: string;
765
+ /** Dialled number mapped to this entry point when included in the list response. */
766
+ number?: string;
684
767
  description?: string;
685
- type: string;
686
- isActive: boolean;
687
- orgId: string;
768
+ type?: string;
769
+ isActive?: boolean;
770
+ orgId?: string;
688
771
  createdAt?: string;
689
772
  updatedAt?: string;
690
773
  settings?: Record<string, any>;
@@ -921,6 +1004,63 @@ export type RealTimeAssistanceUserActionParams = {
921
1004
  languageCode?: string;
922
1005
  };
923
1006
 
1007
+ /**
1008
+ * Wellness notification actions delivered by the Contact Center notification service.
1009
+ * @public
1010
+ */
1011
+ export const WELLNESS_BREAK_NOTIFICATION_ACTIONS = {
1012
+ PROVIDE_WELLNESS_BREAK: 'PROVIDE_WELLNESS_BREAK',
1013
+ SUGGEST_WELLNESS_BREAK: 'SUGGEST_WELLNESS_BREAK',
1014
+ WELLNESS_BREAK_NOT_ALLOWED: 'WELLNESS_BREAK_NOT_ALLOWED',
1015
+ } as const;
1016
+
1017
+ /** Union of supported wellness notification actions. @public */
1018
+ export type WellnessBreakNotificationAction = Enum<typeof WELLNESS_BREAK_NOTIFICATION_ACTIONS>;
1019
+
1020
+ /**
1021
+ * Agent actions accepted by the wellness action API.
1022
+ * @public
1023
+ */
1024
+ export const WELLNESS_BREAK_USER_ACTIONS = {
1025
+ REQUESTED: 'REQUESTED',
1026
+ ACCEPTED: 'ACCEPTED',
1027
+ REJECTED: 'REJECTED',
1028
+ NO_RESPONSE: 'NO_RESPONSE',
1029
+ } as const;
1030
+
1031
+ /** Union of supported wellness action API values. @public */
1032
+ export type WellnessBreakUserAction = Enum<typeof WELLNESS_BREAK_USER_ACTIONS>;
1033
+
1034
+ /**
1035
+ * Validated, agent-scoped wellness notification emitted by Contact Center.
1036
+ * @public
1037
+ */
1038
+ export interface WellnessBreakEvent {
1039
+ /** Agent identifier */
1040
+ agentId: string;
1041
+ /** Organization identifier */
1042
+ orgId: string;
1043
+ /** Session identifier supplied by the notification; it may differ from the consumer's active session */
1044
+ agentSessionId: string;
1045
+ /** Backend wellness action */
1046
+ actionEvent: WellnessBreakNotificationAction;
1047
+ /** Optional untrusted plain-text message supplied by the backend */
1048
+ actionText?: string;
1049
+ /** Optional normalized interaction diagnostic */
1050
+ interactionId?: string;
1051
+ /** Notification diagnostic only; never an action-request correlation identifier */
1052
+ trackingId?: string;
1053
+ }
1054
+
1055
+ /**
1056
+ * Parameters for responding to a backend-provided wellness offer.
1057
+ * @public
1058
+ */
1059
+ export interface RespondToWellnessBreakParams {
1060
+ /** Agent response; REQUESTED is available only through requestWellnessBreak */
1061
+ action: Exclude<WellnessBreakUserAction, typeof WELLNESS_BREAK_USER_ACTIONS.REQUESTED>;
1062
+ }
1063
+
924
1064
  /**
925
1065
  * Supported AI Assistant event categories.
926
1066
  * @public
@@ -958,18 +1098,24 @@ export const AIAssistantEventName = {
958
1098
  GET_SUGGESTIONS: 'GET_SUGGESTIONS',
959
1099
  /** Add extra context to refine a suggested response */
960
1100
  ADD_SUGGESTIONS_EXTRA_CONTEXT: 'ADD_SUGGESTIONS_EXTRA_CONTEXT',
961
- /** Request mid-call summary generation */
962
- GET_MID_CALL_SUMMARY: 'GET_MID_CALL_SUMMARY',
963
1101
  /** Request post-call summary generation */
964
1102
  GET_POST_CALL_SUMMARY: 'GET_POST_CALL_SUMMARY',
965
- /** Mid-call summary response event */
966
- MID_CALL_SUMMARY_RESPONSE: 'MID_CALL_SUMMARY_RESPONSE',
1103
+ /** Request consult mid-call summary generation */
1104
+ GET_MID_CALL_CONSULT_SUMMARY: 'GET_MID_CALL_CONSULT_SUMMARY',
1105
+ /** Request transfer mid-call summary generation */
1106
+ GET_MID_CALL_TRANSFER_SUMMARY: 'GET_MID_CALL_TRANSFER_SUMMARY',
967
1107
  /** Post-call summary response event */
968
1108
  POST_CALL_SUMMARY_RESPONSE: 'POST_CALL_SUMMARY_RESPONSE',
1109
+ /** Consult mid-call summary response event */
1110
+ MID_CALL_CONSULT_SUMMARY_RESPONSE: 'MID_CALL_CONSULT_SUMMARY_RESPONSE',
1111
+ /** Transfer mid-call summary response event */
1112
+ MID_CALL_TRANSFER_SUMMARY_RESPONSE: 'MID_CALL_TRANSFER_SUMMARY_RESPONSE',
969
1113
  /** Suggested digital response event */
970
1114
  SUGGESTED_RESPONSES_DIGITAL: 'SUGGESTED_RESPONSES_DIGITAL',
971
1115
  /** User action on a suggested response adaptive card */
972
1116
  SUGGESTED_RESPONSES_USER_ACTION: 'SUGGESTED_RESPONSES_USER_ACTION',
1117
+ /** Agent Wellness Break request/response action */
1118
+ WELLNESS_BREAK_ACTION: 'WellnessBreakAction',
973
1119
  } as const;
974
1120
 
975
1121
  /**
@@ -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