@webex/contact-center 3.12.0 → 3.13.0-next.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (297) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1613 -0
  3. package/AGENTS.md +969 -0
  4. package/dist/cc.js +1102 -47
  5. package/dist/cc.js.map +1 -1
  6. package/dist/config.js +13 -0
  7. package/dist/config.js.map +1 -1
  8. package/dist/constants.js +46 -3
  9. package/dist/constants.js.map +1 -1
  10. package/dist/index.js +86 -17
  11. package/dist/index.js.map +1 -1
  12. package/dist/metrics/MetricsManager.js +16 -0
  13. package/dist/metrics/MetricsManager.js.map +1 -1
  14. package/dist/metrics/behavioral-events.js +211 -0
  15. package/dist/metrics/behavioral-events.js.map +1 -1
  16. package/dist/metrics/constants.js +58 -4
  17. package/dist/metrics/constants.js.map +1 -1
  18. package/dist/services/AddressBook.js +18 -15
  19. package/dist/services/AddressBook.js.map +1 -1
  20. package/dist/services/AnswerCallOnWebexService.js +202 -0
  21. package/dist/services/AnswerCallOnWebexService.js.map +1 -0
  22. package/dist/services/ApiAiAssistant.js +369 -14
  23. package/dist/services/ApiAiAssistant.js.map +1 -1
  24. package/dist/services/EntryPoint.js +46 -68
  25. package/dist/services/EntryPoint.js.map +1 -1
  26. package/dist/services/Queue.js +27 -22
  27. package/dist/services/Queue.js.map +1 -1
  28. package/dist/services/UserPreference.js +427 -0
  29. package/dist/services/UserPreference.js.map +1 -0
  30. package/dist/services/WebCallingService.js +287 -37
  31. package/dist/services/WebCallingService.js.map +1 -1
  32. package/dist/services/WebexCrossClientService.js +225 -0
  33. package/dist/services/WebexCrossClientService.js.map +1 -0
  34. package/dist/services/WxAppTelephonyMercurySync.js +111 -0
  35. package/dist/services/WxAppTelephonyMercurySync.js.map +1 -0
  36. package/dist/services/config/Util.js +48 -48
  37. package/dist/services/config/Util.js.map +1 -1
  38. package/dist/services/config/constants.js +57 -79
  39. package/dist/services/config/constants.js.map +1 -1
  40. package/dist/services/config/index.js +100 -226
  41. package/dist/services/config/index.js.map +1 -1
  42. package/dist/services/config/types.js +100 -40
  43. package/dist/services/config/types.js.map +1 -1
  44. package/dist/services/constants.js +19 -1
  45. package/dist/services/constants.js.map +1 -1
  46. package/dist/services/core/Err.js.map +1 -1
  47. package/dist/services/core/Utils.js +131 -32
  48. package/dist/services/core/Utils.js.map +1 -1
  49. package/dist/services/core/WebexRequest.js +6 -2
  50. package/dist/services/core/WebexRequest.js.map +1 -1
  51. package/dist/services/core/aqm-reqs.js +17 -11
  52. package/dist/services/core/aqm-reqs.js.map +1 -1
  53. package/dist/services/core/constants.js +9 -1
  54. package/dist/services/core/constants.js.map +1 -1
  55. package/dist/services/core/types.js.map +1 -1
  56. package/dist/services/core/websocket/WebSocketManager.js +26 -6
  57. package/dist/services/core/websocket/WebSocketManager.js.map +1 -1
  58. package/dist/services/core/websocket/connection-service.js +3 -1
  59. package/dist/services/core/websocket/connection-service.js.map +1 -1
  60. package/dist/services/core/websocket/types.js.map +1 -1
  61. package/dist/services/index.js +6 -0
  62. package/dist/services/index.js.map +1 -1
  63. package/dist/services/task/Task.js +955 -0
  64. package/dist/services/task/Task.js.map +1 -0
  65. package/dist/services/task/TaskFactory.js +50 -0
  66. package/dist/services/task/TaskFactory.js.map +1 -0
  67. package/dist/services/task/TaskManager.js +1275 -504
  68. package/dist/services/task/TaskManager.js.map +1 -1
  69. package/dist/services/task/TaskUtils.js +221 -27
  70. package/dist/services/task/TaskUtils.js.map +1 -1
  71. package/dist/services/task/WebexCallingUtils.js +70 -0
  72. package/dist/services/task/WebexCallingUtils.js.map +1 -0
  73. package/dist/services/task/constants.js +22 -2
  74. package/dist/services/task/constants.js.map +1 -1
  75. package/dist/services/task/contact.js +29 -0
  76. package/dist/services/task/contact.js.map +1 -1
  77. package/dist/services/task/dialer.js +78 -0
  78. package/dist/services/task/dialer.js.map +1 -1
  79. package/dist/services/task/digital/Digital.js +78 -0
  80. package/dist/services/task/digital/Digital.js.map +1 -0
  81. package/dist/services/task/state-machine/TaskStateMachine.js +982 -0
  82. package/dist/services/task/state-machine/TaskStateMachine.js.map +1 -0
  83. package/dist/services/task/state-machine/actions.js +572 -0
  84. package/dist/services/task/state-machine/actions.js.map +1 -0
  85. package/dist/services/task/state-machine/constants.js +161 -0
  86. package/dist/services/task/state-machine/constants.js.map +1 -0
  87. package/dist/services/task/state-machine/guards.js +379 -0
  88. package/dist/services/task/state-machine/guards.js.map +1 -0
  89. package/dist/services/task/state-machine/index.js +53 -0
  90. package/dist/services/task/state-machine/index.js.map +1 -0
  91. package/dist/services/task/state-machine/types.js +54 -0
  92. package/dist/services/task/state-machine/types.js.map +1 -0
  93. package/dist/services/task/state-machine/uiControlsComputer.js +703 -0
  94. package/dist/services/task/state-machine/uiControlsComputer.js.map +1 -0
  95. package/dist/services/task/taskDataNormalizer.js +99 -0
  96. package/dist/services/task/taskDataNormalizer.js.map +1 -0
  97. package/dist/services/task/types.js +259 -5
  98. package/dist/services/task/types.js.map +1 -1
  99. package/dist/services/task/voice/Voice.js +1504 -0
  100. package/dist/services/task/voice/Voice.js.map +1 -0
  101. package/dist/services/task/voice/WebRTC.js +152 -0
  102. package/dist/services/task/voice/WebRTC.js.map +1 -0
  103. package/dist/services/task/voice/wxAppOfferObservability.js +145 -0
  104. package/dist/services/task/voice/wxAppOfferObservability.js.map +1 -0
  105. package/dist/services/task/voice/wxAppVoiceMethods.js +395 -0
  106. package/dist/services/task/voice/wxAppVoiceMethods.js.map +1 -0
  107. package/dist/services/wxAppDiagnosticLogging.js +159 -0
  108. package/dist/services/wxAppDiagnosticLogging.js.map +1 -0
  109. package/dist/services/wxAppTelephonyUtils.js +19 -0
  110. package/dist/services/wxAppTelephonyUtils.js.map +1 -0
  111. package/dist/types/cc.d.ts +222 -10
  112. package/dist/types/config.d.ts +13 -0
  113. package/dist/types/constants.d.ts +40 -1
  114. package/dist/types/index.d.ts +58 -22
  115. package/dist/types/metrics/MetricsManager.d.ts +6 -0
  116. package/dist/types/metrics/constants.d.ts +52 -1
  117. package/dist/types/services/AddressBook.d.ts +2 -1
  118. package/dist/types/services/AnswerCallOnWebexService.d.ts +38 -0
  119. package/dist/types/services/ApiAiAssistant.d.ts +67 -5
  120. package/dist/types/services/EntryPoint.d.ts +7 -5
  121. package/dist/types/services/Queue.d.ts +5 -3
  122. package/dist/types/services/UserPreference.d.ts +118 -0
  123. package/dist/types/services/WebexCrossClientService.d.ts +32 -0
  124. package/dist/types/services/WxAppTelephonyMercurySync.d.ts +28 -0
  125. package/dist/types/services/config/Util.d.ts +4 -8
  126. package/dist/types/services/config/constants.d.ts +49 -76
  127. package/dist/types/services/config/index.d.ts +16 -64
  128. package/dist/types/services/config/types.d.ts +252 -114
  129. package/dist/types/services/constants.d.ts +16 -0
  130. package/dist/types/services/core/Err.d.ts +6 -0
  131. package/dist/types/services/core/Utils.d.ts +43 -13
  132. package/dist/types/services/core/WebexRequest.d.ts +1 -0
  133. package/dist/types/services/core/constants.d.ts +7 -0
  134. package/dist/types/services/core/types.d.ts +2 -0
  135. package/dist/types/services/core/websocket/WebSocketManager.d.ts +2 -0
  136. package/dist/types/services/core/websocket/types.d.ts +1 -1
  137. package/dist/types/services/index.d.ts +2 -0
  138. package/dist/types/services/task/Task.d.ts +186 -0
  139. package/dist/types/services/task/TaskFactory.d.ts +14 -0
  140. package/dist/types/services/task/TaskUtils.d.ts +54 -2
  141. package/dist/types/services/task/WebexCallingUtils.d.ts +11 -0
  142. package/dist/types/services/task/constants.d.ts +20 -0
  143. package/dist/types/services/task/contact.d.ts +4 -0
  144. package/dist/types/services/task/dialer.d.ts +30 -0
  145. package/dist/types/services/task/digital/Digital.d.ts +23 -0
  146. package/dist/types/services/task/state-machine/TaskStateMachine.d.ts +1442 -0
  147. package/dist/types/services/task/state-machine/actions.d.ts +10 -0
  148. package/dist/types/services/task/state-machine/constants.d.ts +107 -0
  149. package/dist/types/services/task/state-machine/guards.d.ts +103 -0
  150. package/dist/types/services/task/state-machine/index.d.ts +13 -0
  151. package/dist/types/services/task/state-machine/types.d.ts +277 -0
  152. package/dist/types/services/task/state-machine/uiControlsComputer.d.ts +9 -0
  153. package/dist/types/services/task/taskDataNormalizer.d.ts +10 -0
  154. package/dist/types/services/task/types.d.ts +790 -66
  155. package/dist/types/services/task/voice/Voice.d.ts +241 -0
  156. package/dist/types/services/task/voice/WebRTC.d.ts +54 -0
  157. package/dist/types/services/task/voice/wxAppOfferObservability.d.ts +39 -0
  158. package/dist/types/services/task/voice/wxAppVoiceMethods.d.ts +68 -0
  159. package/dist/types/services/wxAppDiagnosticLogging.d.ts +63 -0
  160. package/dist/types/services/wxAppTelephonyUtils.d.ts +5 -0
  161. package/dist/types/types.d.ts +258 -11
  162. package/dist/types/utils/PageCache.d.ts +20 -3
  163. package/dist/types/webex.d.ts +1 -0
  164. package/dist/types.js +204 -6
  165. package/dist/types.js.map +1 -1
  166. package/dist/utils/PageCache.js +19 -5
  167. package/dist/utils/PageCache.js.map +1 -1
  168. package/dist/webex.js +22 -2
  169. package/dist/webex.js.map +1 -1
  170. package/docs/adr/0001-spec-source-policy.md +97 -0
  171. package/docs/adr/0002-consult-transfer-list-policy.md +345 -0
  172. package/docs/adr/0003-repo-standards-migration.md +104 -0
  173. package/docs/adr/index.md +35 -0
  174. package/docs/architecture.md +460 -0
  175. package/docs/getting-started.md +142 -0
  176. package/docs/index.md +53 -0
  177. package/docs/specs/README.md +98 -0
  178. package/package.json +17 -12
  179. package/schemas/repo-context.schema.json +796 -0
  180. package/src/cc.ts +1439 -105
  181. package/src/config.ts +13 -0
  182. package/src/constants.ts +53 -1
  183. package/src/docs/README.md +727 -0
  184. package/src/index.ts +72 -16
  185. package/src/metrics/MetricsManager.ts +16 -0
  186. package/src/metrics/behavioral-events.ts +218 -0
  187. package/src/metrics/constants.ts +63 -4
  188. package/src/metrics/docs/README.md +710 -0
  189. package/src/services/AddressBook.ts +17 -6
  190. package/src/services/AnswerCallOnWebexService.ts +239 -0
  191. package/src/services/ApiAiAssistant.ts +494 -15
  192. package/src/services/EntryPoint.ts +59 -60
  193. package/src/services/Queue.ts +29 -12
  194. package/src/services/UserPreference.ts +509 -0
  195. package/src/services/WebCallingService.ts +362 -40
  196. package/src/services/WebexCrossClientService.ts +298 -0
  197. package/src/services/WxAppTelephonyMercurySync.ts +142 -0
  198. package/src/services/agent/docs/README.md +673 -0
  199. package/src/services/config/Util.ts +54 -84
  200. package/src/services/config/constants.ts +64 -86
  201. package/src/services/config/docs/README.md +530 -0
  202. package/src/services/config/index.ts +116 -277
  203. package/src/services/config/types.ts +238 -125
  204. package/src/services/constants.ts +18 -0
  205. package/src/services/core/Err.ts +3 -0
  206. package/src/services/core/Utils.ts +151 -37
  207. package/src/services/core/WebexRequest.ts +3 -1
  208. package/src/services/core/aqm-reqs.ts +18 -12
  209. package/src/services/core/constants.ts +8 -0
  210. package/src/services/core/docs/README.md +993 -0
  211. package/src/services/core/types.ts +33 -1
  212. package/src/services/core/websocket/WebSocketManager.ts +37 -8
  213. package/src/services/core/websocket/connection-service.ts +5 -1
  214. package/src/services/core/websocket/types.ts +1 -1
  215. package/src/services/docs/README.md +765 -0
  216. package/src/services/index.ts +4 -0
  217. package/src/services/task/Task.ts +1211 -0
  218. package/src/services/task/TaskFactory.ts +82 -0
  219. package/src/services/task/TaskManager.ts +1551 -584
  220. package/src/services/task/TaskUtils.ts +316 -25
  221. package/src/services/task/WebexCallingUtils.ts +136 -0
  222. package/src/services/task/constants.ts +21 -0
  223. package/src/services/task/contact.ts +30 -0
  224. package/src/services/task/dialer.ts +80 -0
  225. package/src/services/task/digital/Digital.ts +102 -0
  226. package/src/services/task/docs/README.md +1569 -0
  227. package/src/services/task/state-machine/TaskStateMachine.ts +1320 -0
  228. package/src/services/task/state-machine/actions.ts +741 -0
  229. package/src/services/task/state-machine/constants.ts +172 -0
  230. package/src/services/task/state-machine/docs/README.md +1388 -0
  231. package/src/services/task/state-machine/guards.ts +442 -0
  232. package/src/services/task/state-machine/index.ts +28 -0
  233. package/src/services/task/state-machine/types.ts +258 -0
  234. package/src/services/task/state-machine/uiControlsComputer.ts +1135 -0
  235. package/src/services/task/taskDataNormalizer.ts +137 -0
  236. package/src/services/task/types.ts +974 -70
  237. package/src/services/task/voice/Voice.ts +1878 -0
  238. package/src/services/task/voice/WebRTC.ts +194 -0
  239. package/src/services/task/voice/wxAppOfferObservability.ts +204 -0
  240. package/src/services/task/voice/wxAppVoiceMethods.ts +575 -0
  241. package/src/services/wxAppDiagnosticLogging.ts +286 -0
  242. package/src/services/wxAppTelephonyUtils.ts +14 -0
  243. package/src/types.ts +323 -13
  244. package/src/utils/AGENTS.md +291 -0
  245. package/src/utils/PageCache.ts +38 -5
  246. package/src/utils/docs/README.md +413 -0
  247. package/src/webex.js +10 -0
  248. package/test/unit/fixtures/aiSummaryTestUtils.ts +40 -0
  249. package/test/unit/spec/cc.ts +4046 -181
  250. package/test/unit/spec/index.ts +891 -0
  251. package/test/unit/spec/logger-proxy.ts +70 -0
  252. package/test/unit/spec/metrics/MetricsManager.ts +25 -0
  253. package/test/unit/spec/metrics/behavioral-events.ts +60 -0
  254. package/test/unit/spec/services/AddressBook.ts +37 -6
  255. package/test/unit/spec/services/AnswerCallOnWebexService.ts +264 -0
  256. package/test/unit/spec/services/ApiAiAssistant.ts +442 -23
  257. package/test/unit/spec/services/EntryPoint.ts +87 -40
  258. package/test/unit/spec/services/Queue.ts +123 -12
  259. package/test/unit/spec/services/UserPreference.ts +401 -0
  260. package/test/unit/spec/services/WebCallingService.ts +484 -49
  261. package/test/unit/spec/services/WebexCrossClientService.ts +509 -0
  262. package/test/unit/spec/services/WxAppTelephonyMercurySync.ts +136 -0
  263. package/test/unit/spec/services/config/Util.ts +501 -0
  264. package/test/unit/spec/services/config/index.ts +318 -548
  265. package/test/unit/spec/services/core/Utils.ts +447 -8
  266. package/test/unit/spec/services/core/WebexRequest.ts +8 -7
  267. package/test/unit/spec/services/core/aqm-reqs.ts +142 -1
  268. package/test/unit/spec/services/core/websocket/WebSocketManager.ts +132 -56
  269. package/test/unit/spec/services/core/websocket/connection-service.ts +3 -1
  270. package/test/unit/spec/services/task/AutoWrapup.ts +63 -0
  271. package/test/unit/spec/services/task/Task.ts +2723 -0
  272. package/test/unit/spec/services/task/TaskFactory.ts +116 -0
  273. package/test/unit/spec/services/task/TaskManager.ts +4800 -1586
  274. package/test/unit/spec/services/task/TaskUtils.ts +307 -0
  275. package/test/unit/spec/services/task/WebexCallingUtils.ts +153 -0
  276. package/test/unit/spec/services/task/contact.ts +33 -0
  277. package/test/unit/spec/services/task/dialer.ts +190 -0
  278. package/test/unit/spec/services/task/digital/Digital.ts +105 -0
  279. package/test/unit/spec/services/task/state-machine/TaskStateMachine.ts +4060 -0
  280. package/test/unit/spec/services/task/state-machine/guards.ts +839 -0
  281. package/test/unit/spec/services/task/state-machine/types.ts +18 -0
  282. package/test/unit/spec/services/task/state-machine/uiControlsComputer.ts +3101 -0
  283. package/test/unit/spec/services/task/taskTestUtils.ts +87 -0
  284. package/test/unit/spec/services/task/voice/Voice.ts +2355 -0
  285. package/test/unit/spec/services/task/voice/WebRTC.ts +235 -0
  286. package/test/unit/spec/services/task/voice/wxAppOfferObservability.ts +361 -0
  287. package/test/unit/spec/services/task/voice/wxAppVoiceMethods.ts +719 -0
  288. package/test/unit/spec/services/wxAppDiagnosticLogging.ts +179 -0
  289. package/test/unit/spec/wellnessSampleUtils.ts +288 -0
  290. package/typedoc.md +1 -1
  291. package/umd/contact-center.min.js +2 -2
  292. package/umd/contact-center.min.js.map +1 -1
  293. package/dist/services/task/index.js +0 -1525
  294. package/dist/services/task/index.js.map +0 -1
  295. package/dist/types/services/task/index.d.ts +0 -650
  296. package/src/services/task/index.ts +0 -1801
  297. package/test/unit/spec/services/task/index.ts +0 -2184
@@ -0,0 +1,291 @@
1
+ # Utils
2
+
3
+ > **Legacy/reference-only.** Canonical SDD: [`docs/README.md`](docs/README.md). Use the package [manifest](../../.sdd/manifest.json) and [module registry](../../docs/specs/README.md) for routing; code and tests remain the behavioral referee.
4
+ >
5
+ > **Legacy scope:** This guide covers shared pagination/cache contracts used by data services. For repository rules and cross-service conventions, see the [root orchestrator AGENTS.md](../../AGENTS.md).
6
+
7
+ ---
8
+
9
+ ## Key Capabilities
10
+
11
+ The utils scope currently provides shared pagination and cache behavior for contact-center data services:
12
+
13
+ - **Typed Pagination Contracts**: Reusable interfaces for response metadata and query params
14
+ - **Generic In-Memory Page Caching**: `PageCache<T>` utility for simple pagination reuse
15
+ - **Cache Safety Rules**: Explicit bypass behavior for query variants and enabled result/response-shape flags
16
+ - **Spec-Driven Utility Workflow**: Utility-specific implementation and validation flow documented inline in this file
17
+
18
+ | Component | File | Description |
19
+ | --------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
20
+ | `PageCache` | [`PageCache.ts`](./PageCache.ts) | Generic in-memory cache utility for paginated API responses with TTL expiry and helper methods for key generation and cache eligibility checks. |
21
+ | `Pagination Types` | [`PageCache.ts`](./PageCache.ts) | `PaginationMeta`, `PaginatedResponse<T>`, `BaseSearchParams`, and `PageCacheEntry<T>` shared across data services. |
22
+ | `Pagination Defaults` | [`PageCache.ts`](./PageCache.ts) | `PAGINATION_DEFAULTS` (`PAGE`, `PAGE_SIZE`) used by services for consistent request defaults. |
23
+ | `Specs Workflow` | `AGENTS.md` (inline) | Mermaid flow for specs-driven utility changes, acceptance criteria, and drift checks. |
24
+
25
+ ---
26
+
27
+ ## File Structure
28
+
29
+ ```
30
+ src/utils/
31
+ ├── AGENTS.md # This file: utils scope guide
32
+ ├── PageCache.ts # Generic cache + pagination contracts/defaults
33
+ └── docs/
34
+ └── README.md # Canonical utils module spec
35
+ ```
36
+
37
+ ---
38
+
39
+ ## PageCache Utility
40
+
41
+ `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`).
42
+
43
+ ### Reference Usage
44
+
45
+ ```typescript
46
+ import PageCache, {PAGINATION_DEFAULTS} from '../utils/PageCache';
47
+
48
+ const cache = new PageCache<MyItem>('MyService');
49
+
50
+ const page = PAGINATION_DEFAULTS.PAGE;
51
+ const pageSize = PAGINATION_DEFAULTS.PAGE_SIZE;
52
+ const cacheKey = cache.buildCacheKey(scopeId, page, pageSize);
53
+
54
+ // Include every supported result- or response-shape-changing input.
55
+ const canUseCache = cache.canUseCache({
56
+ search,
57
+ filter,
58
+ attributes,
59
+ sortBy,
60
+ desktopProfileFilter,
61
+ provisioningView,
62
+ singleObjectResponse,
63
+ });
64
+
65
+ if (canUseCache) {
66
+ const cachedEntry = cache.getCachedPage(cacheKey);
67
+ if (cachedEntry) {
68
+ return {
69
+ data: cachedEntry.data,
70
+ meta: {
71
+ page,
72
+ pageSize,
73
+ ...cachedEntry.totalMeta,
74
+ },
75
+ };
76
+ }
77
+ }
78
+
79
+ const response = await fetchPageFromApi();
80
+
81
+ if (canUseCache && response.data) {
82
+ cache.cachePage(cacheKey, response.data, response.meta);
83
+ }
84
+
85
+ return response;
86
+ ```
87
+
88
+ ### Cache Lifecycle
89
+
90
+ ```mermaid
91
+ graph TD
92
+ A[Request arrives with scopeId/page/pageSize] --> B{canUseCache?}
93
+ B -->|No: query variant or enabled result/shape flag| C[Bypass cache and call API]
94
+ B -->|Yes| D[buildCacheKey scopeId:page:pageSize]
95
+ D --> E["getCachedPage(cacheKey)"]
96
+ E -->|Miss| C
97
+ E -->|Hit and not expired| F[Return cached data and totalMeta]
98
+ E -->|Hit but expired >= 5 minutes| G[Delete entry and treat as miss]
99
+ G --> C
100
+ C --> H[Receive API response]
101
+ H --> I["cachePage(cacheKey, data, meta)"]
102
+ I --> J[Return fresh response]
103
+ ```
104
+
105
+ ---
106
+
107
+ ## Public Contracts
108
+
109
+ All public contracts for utils are defined in [`PageCache.ts`](./PageCache.ts).
110
+
111
+ ### `PaginationMeta`
112
+
113
+ Common pagination metadata used across list APIs.
114
+
115
+ | Field | Type | Notes |
116
+ | ----------------------------- | ------------------------ | ----------------------- |
117
+ | `orgid` | `string` | Organization identifier |
118
+ | `page` / `currentPage` | `number` | Current page aliases |
119
+ | `pageSize` | `number` | Items per page |
120
+ | `totalPages` | `number` | Total page count |
121
+ | `totalRecords` / `totalItems` | `number` | Total item aliases |
122
+ | `links` | `Record<string, string>` | Pagination link map |
123
+
124
+ ### `PaginatedResponse<T>`
125
+
126
+ Canonical paginated response type:
127
+
128
+ ```typescript
129
+ interface PaginatedResponse<T> {
130
+ data: T[];
131
+ meta: PaginationMeta;
132
+ }
133
+ ```
134
+
135
+ ### `PageCacheEntry<T>`
136
+
137
+ Shape of a cached page entry returned by `getCachedPage()`:
138
+
139
+ - `data: T[]`
140
+ - `timestamp: number` (epoch milliseconds)
141
+ - `totalMeta?: { totalPages?: number; totalRecords?: number }`
142
+
143
+ ### `CacheValidationParams`
144
+
145
+ Contract passed to `canUseCache()`:
146
+
147
+ - `search?: string`
148
+ - `filter?: string`
149
+ - `attributes?: string`
150
+ - `sortBy?: string`
151
+ - `desktopProfileFilter?: boolean`
152
+ - `provisioningView?: boolean`
153
+ - `singleObjectResponse?: boolean`
154
+
155
+ Behavior note:
156
+
157
+ - 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.
158
+ - `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.
159
+
160
+ ### `BaseSearchParams`
161
+
162
+ Common query parameter contract with pagination and sorting:
163
+
164
+ - `search`, `filter`, `attributes`
165
+ - `page`, `pageSize`
166
+ - `sortBy`, `sortOrder`
167
+
168
+ ### `PAGINATION_DEFAULTS`
169
+
170
+ Standard defaults exported for callers:
171
+
172
+ - `PAGE: 0`
173
+ - `PAGE_SIZE: 100`
174
+
175
+ ---
176
+
177
+ ## PageCache API
178
+
179
+ ### `constructor(apiName: string)`
180
+
181
+ Creates a typed cache instance and stores `apiName` for `LoggerProxy` context.
182
+
183
+ ### `canUseCache(params: CacheValidationParams): boolean`
184
+
185
+ Returns `true` only when all of these are absent:
186
+
187
+ - `search`
188
+ - `filter`
189
+ - `attributes`
190
+ - `sortBy`
191
+ - `desktopProfileFilter`, `provisioningView`, or `singleObjectResponse` when `true`
192
+
193
+ 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.
194
+
195
+ ### `buildCacheKey(scopeId: string, page: number, pageSize: number): string`
196
+
197
+ Builds deterministic cache key format:
198
+
199
+ ```text
200
+ ${scopeId}:${page}:${pageSize}
201
+ ```
202
+
203
+ ### `getCachedPage(cacheKey: string): PageCacheEntry<T> | null`
204
+
205
+ Behavior:
206
+
207
+ 1. Returns `null` if key not found
208
+ 2. Computes cache age in minutes
209
+ 3. If age is `>= 5`, logs expiry, deletes entry, returns `null`
210
+ 4. Otherwise returns cached entry
211
+
212
+ ### `cachePage(cacheKey: string, data: T[], meta?: any): void`
213
+
214
+ Stores entry with:
215
+
216
+ - `data`
217
+ - `timestamp`
218
+ - `totalMeta.totalPages`
219
+ - `totalMeta.totalRecords` mapped from `meta.totalRecords || meta.totalItems`
220
+
221
+ ### `clearCache(): void`
222
+
223
+ Clears all entries and logs cleared entry count.
224
+
225
+ ### `getCacheSize(): number`
226
+
227
+ Returns current in-memory entry count.
228
+
229
+ Note: `clearCache()` and `getCacheSize()` are available for future use and are not currently called by existing consumers.
230
+
231
+ ---
232
+
233
+ ## Consumer Map
234
+
235
+ Current consumers of `PageCache` and defaults:
236
+
237
+ | Consumer | File | Usage |
238
+ | ----------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
239
+ | `AddressBook` | [`../services/AddressBook.ts`](../services/AddressBook.ts) | Caches paged address-book responses |
240
+ | `Queue` | [`../services/Queue.ts`](../services/Queue.ts) | Caches paged queue responses |
241
+ | `Public type contracts` | [`../types.ts`](../types.ts) | Re-exports pagination/search contracts into SDK-facing types |
242
+
243
+ Cross-scope mention:
244
+
245
+ - Services-layer docs reference utils caching contracts at [`../services/docs/README.md`](../services/docs/README.md).
246
+
247
+ ---
248
+
249
+ ## Spec-Driven Utility Changes
250
+
251
+ When changing `src/utils` behavior or contracts:
252
+
253
+ 1. Follow the workflow diagram below
254
+ 2. Define acceptance criteria for contract and runtime behavior
255
+ 3. Verify cache TTL, bypass rules, and key schema
256
+ 4. Validate no spec drift before shipping
257
+
258
+ ```mermaid
259
+ flowchart TD
260
+ A[Change proposed in src/utils] --> B{Classify change scope}
261
+ B -->|Contract change| C[Document expected API/type behavior]
262
+ B -->|Runtime behavior change| D[Document cache behavior and TTL impact]
263
+ B -->|Both| C
264
+ C --> E[Update the utils spec docs/README.md contracts and consumer map]
265
+ D --> F[Validate cache key schema and bypass conditions]
266
+ E --> G[Run drift check against PageCache.ts and consumer services]
267
+ F --> G
268
+ G --> H{Behavior and docs aligned?}
269
+ H -->|No| I[Revise implementation/docs and re-validate]
270
+ I --> G
271
+ H -->|Yes| J[Prepare PR with acceptance criteria and evidence]
272
+ ```
273
+
274
+ ---
275
+
276
+ ## Validation Checklist
277
+
278
+ - [ ] Public types remain backward-compatible or migration is documented
279
+ - [ ] `PAGINATION_DEFAULTS` changes are intentional and propagated to consumers
280
+ - [ ] Cache TTL behavior remains explicit and covered by tests
281
+ - [ ] `canUseCache()` bypass conditions are unchanged or intentionally updated
282
+ - [ ] `totalRecords`/`totalItems` mapping behavior is preserved
283
+ - [ ] Logging still uses `LoggerProxy` with `module` and `method`
284
+ - [ ] AddressBook/Queue cache integration remains correct; EntryPoint remains explicitly uncached
285
+
286
+ ---
287
+
288
+ ## Related
289
+
290
+ - [Root orchestrator AGENTS.md](../../AGENTS.md) - Task routing and critical package rules
291
+ - [PageCache implementation](./PageCache.ts)
@@ -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
  /**