@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.
- package/.sdd/manifest.json +24 -13
- package/ai-docs/ARCHITECTURE.md +1 -1
- package/ai-docs/CONTRACTS.md +21 -3
- package/ai-docs/SECURITY.md +1 -1
- package/ai-docs/SERVICE_STATE.md +4 -0
- package/ai-docs/contact-center-spec.md +53 -6
- package/ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md +362 -0
- package/ai-docs/features/contact-owner-change-refactor.md +78 -0
- package/dist/cc.js +816 -26
- package/dist/cc.js.map +1 -1
- package/dist/config.js +7 -0
- package/dist/config.js.map +1 -1
- package/dist/constants.js +29 -2
- package/dist/constants.js.map +1 -1
- package/dist/index.js +66 -12
- package/dist/index.js.map +1 -1
- package/dist/metrics/MetricsManager.js +16 -0
- package/dist/metrics/MetricsManager.js.map +1 -1
- package/dist/metrics/behavioral-events.js +110 -0
- package/dist/metrics/behavioral-events.js.map +1 -1
- package/dist/metrics/constants.js +33 -0
- package/dist/metrics/constants.js.map +1 -1
- package/dist/services/AddressBook.js +18 -15
- package/dist/services/AddressBook.js.map +1 -1
- package/dist/services/AnswerCallOnWebexService.js +202 -0
- package/dist/services/AnswerCallOnWebexService.js.map +1 -0
- package/dist/services/ApiAiAssistant.js +221 -11
- package/dist/services/ApiAiAssistant.js.map +1 -1
- package/dist/services/EntryPoint.js +46 -68
- package/dist/services/EntryPoint.js.map +1 -1
- package/dist/services/Queue.js +27 -22
- package/dist/services/Queue.js.map +1 -1
- package/dist/services/WebCallingService.js +287 -37
- package/dist/services/WebCallingService.js.map +1 -1
- package/dist/services/WebexCrossClientService.js +225 -0
- package/dist/services/WebexCrossClientService.js.map +1 -0
- package/dist/services/WxAppTelephonyMercurySync.js +111 -0
- package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
- package/dist/services/config/Util.js +46 -46
- package/dist/services/config/Util.js.map +1 -1
- package/dist/services/config/constants.js +34 -77
- package/dist/services/config/constants.js.map +1 -1
- package/dist/services/config/index.js +100 -226
- package/dist/services/config/index.js.map +1 -1
- package/dist/services/config/types.js +55 -35
- package/dist/services/config/types.js.map +1 -1
- package/dist/services/constants.js +11 -1
- package/dist/services/constants.js.map +1 -1
- package/dist/services/core/Err.js.map +1 -1
- package/dist/services/core/Utils.js +25 -1
- package/dist/services/core/Utils.js.map +1 -1
- package/dist/services/core/WebexRequest.js +6 -2
- package/dist/services/core/WebexRequest.js.map +1 -1
- package/dist/services/core/aqm-reqs.js +17 -11
- package/dist/services/core/aqm-reqs.js.map +1 -1
- package/dist/services/core/constants.js +9 -1
- package/dist/services/core/constants.js.map +1 -1
- package/dist/services/core/types.js.map +1 -1
- package/dist/services/core/websocket/WebSocketManager.js +17 -1
- package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
- package/dist/services/task/Task.js +275 -8
- package/dist/services/task/Task.js.map +1 -1
- package/dist/services/task/TaskFactory.js +11 -6
- package/dist/services/task/TaskFactory.js.map +1 -1
- package/dist/services/task/TaskManager.js +590 -42
- package/dist/services/task/TaskManager.js.map +1 -1
- package/dist/services/task/TaskUtils.js +11 -1
- package/dist/services/task/TaskUtils.js.map +1 -1
- package/dist/services/task/WebexCallingUtils.js +70 -0
- package/dist/services/task/WebexCallingUtils.js.map +1 -0
- package/dist/services/task/constants.js +14 -2
- package/dist/services/task/constants.js.map +1 -1
- package/dist/services/task/contact.js +29 -0
- package/dist/services/task/contact.js.map +1 -1
- package/dist/services/task/digital/Digital.js +4 -3
- package/dist/services/task/digital/Digital.js.map +1 -1
- package/dist/services/task/state-machine/TaskStateMachine.js +162 -53
- package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -1
- package/dist/services/task/state-machine/actions.js +6 -1
- package/dist/services/task/state-machine/actions.js.map +1 -1
- package/dist/services/task/state-machine/guards.js +7 -10
- package/dist/services/task/state-machine/guards.js.map +1 -1
- package/dist/services/task/state-machine/types.js.map +1 -1
- package/dist/services/task/state-machine/uiControlsComputer.js +118 -18
- package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -1
- package/dist/services/task/types.js +47 -1
- package/dist/services/task/types.js.map +1 -1
- package/dist/services/task/voice/Voice.js +477 -17
- package/dist/services/task/voice/Voice.js.map +1 -1
- package/dist/services/task/voice/WebRTC.js +6 -3
- package/dist/services/task/voice/WebRTC.js.map +1 -1
- package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
- package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
- package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
- package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
- package/dist/services/wxAppDiagnosticLogging.js +159 -0
- package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
- package/dist/services/wxAppTelephonyUtils.js +19 -0
- package/dist/services/wxAppTelephonyUtils.js.map +1 -0
- package/dist/types/cc.d.ts +127 -9
- package/dist/types/config.d.ts +7 -0
- package/dist/types/constants.d.ts +23 -0
- package/dist/types/index.d.ts +38 -17
- package/dist/types/metrics/MetricsManager.d.ts +6 -0
- package/dist/types/metrics/constants.d.ts +31 -0
- package/dist/types/services/AddressBook.d.ts +2 -1
- package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
- package/dist/types/services/ApiAiAssistant.d.ts +48 -4
- package/dist/types/services/EntryPoint.d.ts +7 -5
- package/dist/types/services/Queue.d.ts +5 -3
- package/dist/types/services/WebexCrossClientService.d.ts +32 -0
- package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
- package/dist/types/services/config/Util.d.ts +4 -8
- package/dist/types/services/config/constants.d.ts +28 -76
- package/dist/types/services/config/index.d.ts +16 -64
- package/dist/types/services/config/types.d.ts +150 -173
- package/dist/types/services/constants.d.ts +9 -0
- package/dist/types/services/core/Err.d.ts +2 -0
- package/dist/types/services/core/Utils.d.ts +10 -0
- package/dist/types/services/core/WebexRequest.d.ts +1 -0
- package/dist/types/services/core/constants.d.ts +7 -0
- package/dist/types/services/core/types.d.ts +2 -0
- package/dist/types/services/task/Task.d.ts +34 -5
- package/dist/types/services/task/TaskFactory.d.ts +4 -2
- package/dist/types/services/task/TaskUtils.d.ts +6 -0
- package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
- package/dist/types/services/task/constants.d.ts +12 -0
- package/dist/types/services/task/contact.d.ts +4 -0
- package/dist/types/services/task/digital/Digital.d.ts +4 -3
- package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +304 -56
- package/dist/types/services/task/state-machine/guards.d.ts +6 -5
- package/dist/types/services/task/state-machine/types.d.ts +9 -1
- package/dist/types/services/task/types.d.ts +192 -5
- package/dist/types/services/task/voice/Voice.d.ts +68 -11
- package/dist/types/services/task/voice/WebRTC.d.ts +5 -4
- package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
- package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
- package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
- package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
- package/dist/types/types.d.ts +125 -13
- package/dist/types/utils/PageCache.d.ts +20 -3
- package/dist/types.js +90 -8
- package/dist/types.js.map +1 -1
- package/dist/utils/PageCache.js +19 -5
- package/dist/utils/PageCache.js.map +1 -1
- package/dist/webex.js +9 -1
- package/dist/webex.js.map +1 -1
- package/package.json +10 -9
- package/src/cc.ts +1047 -48
- package/src/config.ts +7 -0
- package/src/constants.ts +36 -0
- package/src/index.ts +49 -11
- package/src/metrics/MetricsManager.ts +16 -0
- package/src/metrics/ai-docs/metrics-spec.md +138 -21
- package/src/metrics/behavioral-events.ts +112 -0
- package/src/metrics/constants.ts +36 -0
- package/src/services/AddressBook.ts +17 -6
- package/src/services/AnswerCallOnWebexService.ts +239 -0
- package/src/services/ApiAiAssistant.ts +297 -13
- package/src/services/EntryPoint.ts +59 -60
- package/src/services/Queue.ts +29 -12
- package/src/services/WebCallingService.ts +362 -40
- package/src/services/WebexCrossClientService.ts +298 -0
- package/src/services/WxAppTelephonyMercurySync.ts +142 -0
- package/src/services/agent/ai-docs/AGENTS.md +1 -1
- package/src/services/agent/ai-docs/agent-spec.md +1 -0
- package/src/services/ai-docs/AGENTS.md +11 -11
- package/src/services/ai-docs/services-spec.md +25 -5
- package/src/services/config/Util.ts +52 -82
- package/src/services/config/ai-docs/AGENTS.md +35 -40
- package/src/services/config/ai-docs/ARCHITECTURE.md +90 -103
- package/src/services/config/ai-docs/config-spec.md +132 -132
- package/src/services/config/constants.ts +39 -85
- package/src/services/config/index.ts +116 -277
- package/src/services/config/types.ts +145 -195
- package/src/services/constants.ts +10 -0
- package/src/services/core/Err.ts +1 -0
- package/src/services/core/Utils.ts +28 -0
- package/src/services/core/WebexRequest.ts +3 -1
- package/src/services/core/ai-docs/core-spec.md +25 -11
- package/src/services/core/aqm-reqs.ts +18 -12
- package/src/services/core/constants.ts +8 -0
- package/src/services/core/types.ts +33 -1
- package/src/services/core/websocket/WebSocketManager.ts +26 -2
- package/src/services/task/Task.ts +386 -12
- package/src/services/task/TaskFactory.ts +33 -6
- package/src/services/task/TaskManager.ts +857 -41
- package/src/services/task/TaskUtils.ts +13 -0
- package/src/services/task/WebexCallingUtils.ts +136 -0
- package/src/services/task/ai-docs/ARCHITECTURE.md +1 -0
- package/src/services/task/ai-docs/task-spec.md +190 -8
- package/src/services/task/constants.ts +13 -0
- package/src/services/task/contact.ts +30 -0
- package/src/services/task/digital/Digital.ts +11 -4
- package/src/services/task/state-machine/TaskStateMachine.ts +235 -81
- package/src/services/task/state-machine/actions.ts +5 -2
- package/src/services/task/state-machine/ai-docs/AGENTS.md +6 -4
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +35 -16
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +103 -33
- package/src/services/task/state-machine/guards.ts +7 -10
- package/src/services/task/state-machine/types.ts +16 -1
- package/src/services/task/state-machine/uiControlsComputer.ts +206 -32
- package/src/services/task/types.ts +269 -4
- package/src/services/task/voice/Voice.ts +625 -17
- package/src/services/task/voice/WebRTC.ts +11 -4
- package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
- package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
- package/src/services/wxAppDiagnosticLogging.ts +286 -0
- package/src/services/wxAppTelephonyUtils.ts +14 -0
- package/src/types.ts +159 -13
- package/src/utils/AGENTS.md +21 -10
- package/src/utils/PageCache.ts +38 -5
- package/src/utils/ai-docs/utils-spec.md +21 -11
- package/src/webex.js +8 -0
- package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
- package/test/unit/spec/cc.ts +3595 -120
- package/test/unit/spec/index.ts +891 -0
- package/test/unit/spec/metrics/MetricsManager.ts +25 -0
- package/test/unit/spec/metrics/behavioral-events.ts +60 -0
- package/test/unit/spec/services/AddressBook.ts +37 -6
- package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
- package/test/unit/spec/services/ApiAiAssistant.ts +269 -8
- package/test/unit/spec/services/EntryPoint.ts +87 -40
- package/test/unit/spec/services/Queue.ts +123 -12
- package/test/unit/spec/services/WebCallingService.ts +483 -54
- package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
- package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
- package/test/unit/spec/services/config/Util.ts +501 -0
- package/test/unit/spec/services/config/index.ts +313 -543
- package/test/unit/spec/services/core/Utils.ts +22 -0
- package/test/unit/spec/services/core/WebexRequest.ts +8 -7
- package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
- package/test/unit/spec/services/core/websocket/WebSocketManager.ts +64 -14
- package/test/unit/spec/services/task/Task.ts +2257 -11
- package/test/unit/spec/services/task/TaskFactory.ts +56 -2
- package/test/unit/spec/services/task/TaskManager.ts +5559 -1493
- package/test/unit/spec/services/task/TaskUtils.ts +72 -0
- package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
- package/test/unit/spec/services/task/contact.ts +33 -0
- package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +1501 -92
- package/test/unit/spec/services/task/state-machine/guards.ts +210 -8
- package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +445 -7
- package/test/unit/spec/services/task/voice/Voice.ts +1710 -4
- package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
- package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
- package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
- package/test/unit/spec/wellnessSampleUtils.ts +288 -0
- package/typedoc.md +1 -1
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
|
@@ -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
|
|
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
|
|
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
|
|
686
|
-
isActive
|
|
687
|
-
orgId
|
|
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
|
-
/**
|
|
966
|
-
|
|
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
|
/**
|
package/src/utils/AGENTS.md
CHANGED
|
@@ -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
|
|
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
|
|
53
|
-
const canUseCache = cache.canUseCache({
|
|
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:
|
|
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
|
|
145
|
-
-
|
|
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
|
-
`
|
|
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/
|
|
282
|
+
- [ ] AddressBook/Queue cache integration remains correct; EntryPoint remains explicitly uncached
|
|
272
283
|
|
|
273
284
|
---
|
|
274
285
|
|