@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
package/AGENTS.md ADDED
@@ -0,0 +1,969 @@
1
+ <!-- sdd-generated-metadata
2
+ doc_kind: agent-entry
3
+ generated_from: agents@0.3.0
4
+ generated_by: claude-code
5
+ approved_by: rarajes2@cisco.com
6
+ updated_at: 2026-11-17T03:03:58Z
7
+ validation_status: pass-with-warnings
8
+ -->
9
+
10
+ # AI Agent Instructions
11
+
12
+ Package-scoped SDD entry for `@webex/contact-center`. `@webex/contact-center` is a published Webex SDK
13
+ plugin for agent registration, configuration, realtime events, task/call control, data lookup, and
14
+ telemetry. It registers as `webex.cc` (`src/index.ts`). This file orients agents working in this
15
+ package. The monorepo root `AGENTS.md` governs workspace-wide setup.
16
+
17
+ **What it is:**
18
+
19
+ - A TypeScript SDK package embedded in the Webex SDK host.
20
+ - A client of Webex Contact Center REST, WebSocket, calling, and metrics services.
21
+
22
+ **What it is NOT:**
23
+
24
+ - It is not a standalone backend and owns no durable datastore.
25
+ - It does not render a UI; it exposes state and UI-control contracts to host applications.
26
+
27
+ ## Working Method
28
+
29
+ - Read the relevant package files before editing. Do not edit blind.
30
+ - Code and tests are the behavioral referee; never invent APIs, paths, events, flags, or states.
31
+ - Understand the task and affected surfaces before writing code.
32
+ - Prefer focused edits over rewriting whole files.
33
+ - Test or validate before declaring done.
34
+ - Keep output concise. If something is uncertain, say so instead of guessing.
35
+
36
+ Developer workflow:
37
+
38
+ 1. Read this file for package rules, then use [`docs/specs/README.md`](docs/specs/README.md) to
39
+ select the owning canonical module spec.
40
+ 2. Check the module spec's requirements, public surface, source paths, test evidence, and documented
41
+ gaps against the relevant code/tests.
42
+ 3. Before coding, present the affected files and contracts and wait for confirmation. For a new
43
+ method, settle its target file and name, parameters (required or optional), return shape, backend
44
+ call (HTTP verb, endpoint, payload, and whether the result arrives in the HTTP response or as a
45
+ WebSocket message), events, metric names, and success and failure behavior. For a bug, settle the
46
+ unexpected and expected behavior, the reproduction steps or logs and tracking id, and the affected
47
+ layer (plugin `src/cc.ts`, a service under `src/services/`, core `src/services/core/`, or types).
48
+ 4. Implement the smallest approved change; update the owning module spec, the contract index in
49
+ [`docs/architecture.md`](docs/architecture.md), and `.sdd/manifest.json` when public behavior or
50
+ routing changes.
51
+ 5. Run the package commands below plus manifest/conformance checks; materially changed generated
52
+ specs require validation on the configured independent runtime.
53
+ 6. Review the final diff for source/test fidelity, compatibility, secrets, and unrelated files before
54
+ staging.
55
+
56
+ Task routing inside this file: a new method or feature on an existing service uses
57
+ [Public methods and new code placement](#public-methods-and-new-code-placement) and
58
+ [Logging, metrics, and errors](#logging-metrics-and-errors); a new service also uses
59
+ [Services and constants](#services-and-constants); a bug fix starts from
60
+ [Common bug patterns](#common-bug-patterns); every change ends with [Testing Workflow](#4-testing-workflow).
61
+
62
+ ## Canonical Repository Documentation
63
+
64
+ Before changing code or documentation, start with:
65
+
66
+ - [`docs/index.md`](docs/index.md) for package documentation navigation;
67
+ - [`docs/architecture.md`](docs/architecture.md) for package boundaries, interactions, and the
68
+ contract index;
69
+ - [`docs/specs/README.md`](docs/specs/README.md) for the manifest-backed module and contract registry;
70
+ - the affected module's spec: [`src/docs/README.md`](src/docs/README.md) (plugin and public API),
71
+ [`src/metrics/docs/README.md`](src/metrics/docs/README.md),
72
+ [`src/services/docs/README.md`](src/services/docs/README.md),
73
+ [`src/services/agent/docs/README.md`](src/services/agent/docs/README.md),
74
+ [`src/services/config/docs/README.md`](src/services/config/docs/README.md),
75
+ [`src/services/core/docs/README.md`](src/services/core/docs/README.md),
76
+ [`src/services/task/docs/README.md`](src/services/task/docs/README.md),
77
+ [`src/services/task/state-machine/docs/README.md`](src/services/task/state-machine/docs/README.md),
78
+ or [`src/utils/docs/README.md`](src/utils/docs/README.md); and
79
+ - [`docs/adr/index.md`](docs/adr/index.md) plus applicable concrete ADRs for durable decisions.
80
+
81
+ Follow `.sdd/manifest.json` for each contract's publication state and canonical source;
82
+ `.sdd/manifest.json` is authoritative for SDD coverage, and `docs/specs/README.md` mirrors it. Every
83
+ module is `Partial` today: existing docs help, but code must be cross-checked until migration,
84
+ coverage, and validation pass. This package publishes an SDK, so its contract artifact is
85
+ `package.json` with the `src/index.ts` typed entry (`types` is `dist/types/index.d.ts`) and the
86
+ `dist/webex.js` main built from `src/webex.js`. It serves no HTTP API of its own, so no OpenAPI applies.
87
+
88
+ ## 1. Commands (Run First)
89
+
90
+ Use only documented commands. Do not invent alternatives when a command is missing. Run every command
91
+ below from the workspace root. The package scripts run through `yarn workspace @webex/contact-center`
92
+ followed by the script name; `package.json` in `packages/@webex/contact-center` defines them.
93
+
94
+ | Task | Command |
95
+ | ---------------------- | ------- |
96
+ | Install dependencies | `yarn` (workspace root) |
97
+ | Start dev environment | N/A — library package with no start script in `package.json` |
98
+ | Run tests | `yarn workspace @webex/contact-center test:unit` (the `@webex/contact-center` workspace `test:unit` script; Jest collects coverage) |
99
+ | Run linters | `yarn workspace @webex/contact-center test:style` (the workspace `test:style` script: eslint over `src/**/*.ts`) |
100
+ | Build/release artifact | `yarn workspace @webex/contact-center build:src` (babel output, source maps, then the `build` script for `@webex/calling` and the `dist/types` declarations) |
101
+ | Format code | `yarn workspace @webex/contact-center fix:prettier` (prettier over `src/**/*.ts`); `yarn workspace @webex/contact-center fix:lint` applies eslint fixes |
102
+ | Build with dependencies | `yarn workspace @webex/contact-center compile` (runs `build:src` for this package and its workspace dependencies in topological order) |
103
+ | Style and unit together | `yarn workspace @webex/contact-center test` (runs `test:style`, then `test:unit`) |
104
+ | E2E | `yarn workspace @webex/contact-center test:e2e` (Playwright with the workspace `playwright.config.ts`, which runs the monorepo-root `cc_playwright/` suites; see its README) |
105
+ | API reference | `yarn workspace @webex/contact-center build:docs` (typedoc into the workspace `docs/wxcc` folder, outside this package) |
106
+ | Publish | `yarn workspace @webex/contact-center deploy:npm` (release automation only) |
107
+
108
+ To run one spec file, add the `--targets` option that the workspace root `AGENTS.md` describes, with a
109
+ path relative to `test/unit/spec/` (for example `cc.ts`). There is no `test:integration` or
110
+ `test:browser` script.
111
+
112
+ If a required command is unknown, stop and ask for the exact command.
113
+
114
+ ## 2. Agent Persona and Scope
115
+
116
+ You are the Webex JS SDK engineering assistant for `@webex/contact-center`.
117
+
118
+ Primary outcomes:
119
+
120
+ - Deliver production-safe changes with lint and unit tests (with coverage) passing.
121
+ - Preserve existing behavior unless a change request explicitly requires a behavior change.
122
+ - Keep docs and configuration aligned with code changes.
123
+
124
+ Definition of done:
125
+
126
+ 1. Requested change is implemented, after the affected files and contracts were confirmed.
127
+ 2. Unit tests and lint pass; the 85% coverage bar remains satisfied.
128
+ 3. Public types/events/methods remain compatible or include a migration plan.
129
+ 4. State, error, timeout, and cleanup paths are covered.
130
+ 5. Spec/docs and `.sdd/manifest.json` are updated with code changes.
131
+ 6. No secrets or sensitive data are committed or logged.
132
+ 7. PR summary includes risks and rollback notes.
133
+
134
+ ## 3. Repository Knowledge
135
+
136
+ ### Tech Stack
137
+
138
+ | Area | Tooling | Version |
139
+ | ---------------- | ------- | ------- |
140
+ | Language runtime | TypeScript sources (one JavaScript entry, `src/webex.js`, and a JavaScript keepalive worker) on node | node 22.14 for workspace development (workspace root `AGENTS.md`; `.nvmrc` `lts/jod`); package `engines` `>=20.x`; typescript `5.4.5` |
141
+ | Build tool | yarn workspaces, `@webex/legacy-tools` over babel, and `tsc` for declarations | yarn `3.4.1` (root `packageManager`) |
142
+ | Test framework | jest through `webex-legacy-tools test --unit --runner jest`, `@webex/jest-config-legacy` extended by `jest.config.js`, `@webex/test-helper-mock-webex` | jest `27.5.1` |
143
+ | Lint/format | eslint with the monorepo root `.eslintrc.js` (the package has none of its own), prettier | eslint `^8.24.0`, prettier `2.5.1` |
144
+ | Runtime libraries | `WebexPlugin` from `@webex/webex-core`, Node `events` `EventEmitter`, XState, WebSocket, `@webex/calling` for WebRTC, Mercury, metrics | xstate `5.24.0` |
145
+
146
+ ### Project Map
147
+
148
+ Request path: Host Webex SDK → ContactCenter plugin → Services/Task/Metrics → REST + WebSocket + WebRTC
149
+ backends. The full architecture is in [`docs/architecture.md`](docs/architecture.md).
150
+
151
+ - `src/`: public plugin/API orchestration
152
+ - `src/metrics/`: telemetry
153
+ - `src/services/`: service composition and integrations
154
+ - `src/services/{agent,config,core}/`: agent, profile, and transport capabilities
155
+ - `src/services/task/`: task/call lifecycle
156
+ - `src/services/task/state-machine/`: typed XState lifecycle engine
157
+ - `src/utils/`: pagination/page cache contracts
158
+
159
+ Key files:
160
+
161
+ - `src/index.ts`: registers the `cc` plugin and lists every published export and type.
162
+ - `src/cc.ts`: `ContactCenter` (extends `WebexPlugin`), the `webex.cc` public API and WebSocket event
163
+ fan-out.
164
+ - `src/types.ts`, `src/constants.ts`, `src/config.ts`: public types, SDK-wide constants and
165
+ `METHODS`, and the plugin config defaults (`allowMultiLogin`, `allowAutomatedRelogin`, and others).
166
+ - `src/logger-proxy.ts`: `LoggerProxy`, the only logging entry point.
167
+ - `src/services/index.ts`: the `Services` singleton.
168
+ - `src/services/AddressBook.ts`, `EntryPoint.ts`, `Queue.ts`, `UserPreference.ts`, `ApiAiAssistant.ts`,
169
+ `WebCallingService.ts` and the other single-file services beside them.
170
+ - `src/webex.js`, `src/webex-config.ts`: the standalone `Webex` constructor and its config; `umd/` holds
171
+ the committed browser bundle.
172
+ - `test/unit/spec/`: unit specs mirroring `src/`; `test/unit/fixtures/` and `__mocks__/workerMock.js`
173
+ hold shared helpers.
174
+ - `dist/`: generated build output. Never edit by hand.
175
+
176
+ ### Critical Constraints
177
+
178
+ - AQM completion may arrive over WebSocket after an HTTP acknowledgement; do not treat the
179
+ acknowledgement as completion. Preserve AQM HTTP-plus-WebSocket correlation, timeout, and recovery
180
+ semantics; settlement and the `TIMEOUT_REQ` default are CORE-R-003 in
181
+ [core Requirements](src/services/core/docs/README.md#requirements).
182
+ - Listener cleanup requires the same function reference used at registration; preserve listener
183
+ identity for cleanup and avoid blocking the event loop in handlers.
184
+ - Config aggregation is all-or-nothing; returning a partial profile creates inconsistent runtime
185
+ behavior. `getAgentConfig` awaits the user desktop-login aggregate, then fetches the five dependent
186
+ parts with one `Promise.all`, and rethrows on any failure (`src/services/config/index.ts`).
187
+ - Task transitions must go through typed TaskEvent mapping and guards; see
188
+ [`src/services/task/state-machine/docs/README.md`](src/services/task/state-machine/docs/README.md).
189
+ - PageCache bypasses search/filter/attributes/sort queries to avoid stale or incorrect reuse
190
+ (`canUseCache` in `src/utils/PageCache.ts`).
191
+ - Use MetricsManager timing/tracking patterns without blocking product behavior.
192
+ - Use typed event constants; preserve `trigger` versus `emit` ownership (see
193
+ [Events](#events)).
194
+ - Credentials come from the host Webex SDK; validate inputs and use authenticated service routing.
195
+ - `cc.register()` must run before any agent operation: it opens the WebSocket, so task and agent
196
+ events arrive only after it.
197
+ - The published surface is what `src/index.ts` exports; renaming or removing an export, a public
198
+ method, an event name, or a type field is a breaking change for host applications.
199
+
200
+ ## 4. Testing Workflow
201
+
202
+ Run checks in this order, from the workspace root:
203
+
204
+ 1. `yarn workspace @webex/contact-center build:src`
205
+ 2. `yarn workspace @webex/contact-center test:unit`
206
+ 3. `yarn workspace @webex/contact-center test:style`
207
+ 4. `yarn workspace @webex/contact-center test:e2e` only when the change needs it (see Ask First).
208
+
209
+ On a fresh or outdated checkout, run `yarn workspace @webex/contact-center compile` first so workspace dependencies such as
210
+ `@webex/calling` have a current `dist/`; specs also import workspace packages such as
211
+ `@webex/test-helper-mock-webex` and `@webex/internal-plugin-mercury` by name.
212
+
213
+ Testing rules:
214
+
215
+ - Mirror source paths under `test/unit/spec/`; cover positive and negative behavior and retain the 85%
216
+ global coverage threshold.
217
+ - Every new source file must have a corresponding test file. The test file location mirrors the
218
+ source file path: `src/cc.ts` → `test/unit/spec/cc.ts`, `src/logger-proxy.ts` →
219
+ `test/unit/spec/logger-proxy.ts`, `src/metrics/MetricsManager.ts` →
220
+ `test/unit/spec/metrics/MetricsManager.ts`, `src/services/agent/index.ts` →
221
+ `test/unit/spec/services/agent/index.ts`, `src/services/task/Task.ts` →
222
+ `test/unit/spec/services/task/Task.ts`, `src/services/WebCallingService.ts` →
223
+ `test/unit/spec/services/WebCallingService.ts`. Logic files with no mirrored spec today include
224
+ `src/services/index.ts`, `src/services/core/Err.ts`, `src/services/task/state-machine/actions.ts`,
225
+ `src/services/task/taskDataNormalizer.ts`, `src/services/wxAppTelephonyUtils.ts`, and
226
+ `src/utils/PageCache.ts`; pin their current behavior before changing them.
227
+ - `jest.config.js` sets `collectCoverage: true`, `clearMocks: true`, and 85% global branch, function,
228
+ line, and statement thresholds. Reports go to `coverage/` (junit under `coverage/junit`, the HTML
229
+ report, lcov) and, through `testResultsProcessor: 'jest-junit'`, to `junit.xml` at the package root
230
+ (ignored by Git).
231
+ - Specs use Jest (`expect`, `jest.fn()`, `jest.mock`, `jest.spyOn`), not the sinon and chai helpers
232
+ the workspace root `AGENTS.md` describes for other plugins. Use fake timers
233
+ (`jest.useFakeTimers()`) for time-dependent behavior, and parametrize (`it.each`) when more than
234
+ three cases are alike.
235
+ - For a new method, test the success case, the error case (including the `getErrorDetails` call), edge
236
+ cases, the metrics tracking (`timeEvent` and `trackEvent` calls asserted), the logging (`LoggerProxy`
237
+ calls), and optional parameters.
238
+ - For a bug fix, add a regression test that reproduces the original bug (fails before the fix, passes
239
+ after) to prevent the same issue from recurring.
240
+ - Prefer exact matches over `expect.objectContaining` in new tests. Exact matches catch unexpected
241
+ field changes and keep tests rigorous: use `toEqual` with the full expected object, and use
242
+ `expect.objectContaining()` or `expect.arrayContaining()` only for a specific reason such as
243
+ dynamic fields like timestamps. Existing tests may use `expect.objectContaining` for complex
244
+ objects; this is acceptable but not preferred for new code.
245
+ - Do not remove tests to make CI pass.
246
+
247
+ Spec setup used by `test/unit/spec/cc.ts`:
248
+
249
+ - `import 'jsdom-global/register';` first, then `import '../../../__mocks__/workerMock';`, which
250
+ defines a global `Worker` (its `postMessage` calls `onmessage`) for the keepalive worker and sets
251
+ `global.URL.createObjectURL = jest.fn(() => 'blob:http://localhost:3000/12345');`.
252
+ - `jest.mock` the module singletons (`src/logger-proxy`, `src/services`, `src/services/task/TaskManager`,
253
+ `src/metrics/MetricsManager`, `src/services/core/WebexRequest`), and mock `uuid` with
254
+ `jest.mock('uuid', () => ({v4: () => 'mock-tracking-uuid'}))`.
255
+ - Build the host with `MockWebex` and cast it once: `MockWebex` requires the `as unknown as WebexSDK`
256
+ double-cast, so do not use this pattern elsewhere.
257
+ - Spy the singleton getters and the error helper, then construct the plugin:
258
+
259
+ ```typescript
260
+ webex = MockWebex({
261
+ children: {
262
+ cc: ContactCenter,
263
+ mercury: Mercury,
264
+ },
265
+ logger: {
266
+ log: jest.fn(),
267
+ error: jest.fn(),
268
+ info: jest.fn(),
269
+ },
270
+ credentials: {
271
+ getOrgId: jest.fn(() => 'mockOrgId'),
272
+ },
273
+ config: config,
274
+ once: jest.fn((event, callback) => callback()),
275
+ }) as unknown as WebexSDK;
276
+
277
+ jest.spyOn(MetricsManager, 'getInstance').mockReturnValue(mockMetricsManager);
278
+ jest.spyOn(Services, 'getInstance').mockReturnValue(mockServicesInstance as any);
279
+ jest.spyOn(TaskManager, 'getTaskManager').mockReturnValue(mockTaskManager);
280
+ jest.spyOn(WebexRequest, 'getInstance').mockReturnValue(mockWebexRequest);
281
+ webex.cc = new ContactCenter({parent: webex});
282
+ getErrorDetailsSpy = jest.spyOn(Utils, 'getErrorDetails');
283
+ ```
284
+
285
+ Service specs that construct a class directly (for example `test/unit/spec/services/AddressBook.ts`)
286
+ automock `jest.mock('../../../../src/logger-proxy')` and `src/metrics/MetricsManager`, pass a plain
287
+ mock `webex` with `credentials.getOrgId` and `request`, and reset `(WebexRequest as any).instance =
288
+ undefined` in `beforeEach`. Internal plugins come from real children (`mercury: Mercury`) plus
289
+ `jest.spyOn(webex.internal.mercury, 'connect')`.
290
+
291
+ Event listeners and their callbacks are tested by spying on the registration, extracting the callback
292
+ via `mock.calls`, and invoking it directly:
293
+
294
+ ```typescript
295
+ it('should handle websocket message and emit event', async () => {
296
+ await webex.cc.register(); // register() adds the 'message' listener
297
+
298
+ // Step 1: Find the registered callback via mock.calls
299
+ const onCalls = mockServicesInstance.webSocketManager.on.mock.calls;
300
+ const messageCall = onCalls.find(([event]) => event === 'message');
301
+ const wsHandler = messageCall[1];
302
+
303
+ // Step 2: Spy on the emit
304
+ const emitSpy = jest.spyOn(webex.cc, 'emit');
305
+
306
+ // Step 3: Invoke the callback directly with test data
307
+ wsHandler(JSON.stringify({
308
+ type: 'AgentStateChange',
309
+ data: { type: 'AgentStateChangeSuccess', agentId: 'agent-123', state: 'Available' },
310
+ }));
311
+
312
+ // Step 4: Assert exact emit arguments
313
+ expect(emitSpy).toHaveBeenCalledWith('agent:stateChange', {
314
+ type: 'AgentStateChangeSuccess',
315
+ agentId: 'agent-123',
316
+ state: 'Available',
317
+ });
318
+ });
319
+ ```
320
+
321
+ Spy on `emit` for events that `handleWebsocketMessage` re-emits and on `trigger` for events forwarded
322
+ from `TaskManager` (`task:incoming`, `task:hydrate`); the spec asserts on whichever method the code
323
+ calls. Assert the error helper with its exact arguments, for example
324
+ `expect(getErrorDetailsSpy).toHaveBeenCalledWith(error, 'startOutdial', CC_FILE)`; `CC_FILE` is
325
+ `'cc'`.
326
+
327
+ ## 5. Code Style and Patterns
328
+
329
+ Coding expectations:
330
+
331
+ - Follow repository style rules and static analysis output. `yarn workspace @webex/contact-center test:style` applies the monorepo root
332
+ `.eslintrc.js` to `src/**/*.ts` only; its ignore patterns skip `**/test/**/*`. It enforces
333
+ `max-len` 100, single quotes, `newline-before-return`, and `no-console` (which still allows
334
+ `console.warn` and `console.error`).
335
+ - Prefer small, composable functions over large procedural blocks.
336
+ - Make error handling explicit at system boundaries.
337
+ - Keep public interfaces stable unless a breaking change is requested.
338
+ - Always use async/await over raw Promises.
339
+ - Avoid `any` type unless absolutely necessary, and prefer `unknown` over `any` for unknown types.
340
+ `@typescript-eslint/no-explicit-any` is off, so lint does not catch it; the few justified uses in
341
+ `src/services/task/types.ts` carry an `eslint-disable-next-line` comment.
342
+ - TypeScript strict mode is not enabled: the shared root `tsconfig.json` sets `alwaysStrict` but not
343
+ `strict`, so the compiler does not enforce null checks; guard optional data with optional chaining.
344
+ - All public APIs must have explicit return types.
345
+ - External packages first, then package types/constants, service imports, local utilities, and
346
+ type-only imports (`import type`), as `src/cc.ts` orders them: `@webex/webex-core`, `events`, and
347
+ `uuid`, then `./types` and `./constants`, then `./services` and `./logger-proxy`. New runtime
348
+ dependencies require approval.
349
+ - Before adding a literal path, filename, command, workflow identifier, status, or other policy
350
+ value, search the repository for exact and semantically equivalent uses. When repeated production
351
+ values represent one shared contract, move them to the narrowest owning shared module or catalog as
352
+ one canonical named constant, enum, or type and update consumers. Keep incidental similarities,
353
+ one-off implementation details, and independent test fixtures local.
354
+ - Do not import a default, named, object, or namespace binding and immediately re-export it.
355
+ Consumers should import from the owning module; `src/index.ts` uses direct named re-exports
356
+ (`export {default as AddressBook} from './services/AddressBook'`).
357
+ - Do not write inline runtime `typeof` checks outside descriptively named guard implementations.
358
+ Import and reuse the owning guard (`isRecord` in `src/services/core/Utils.ts`) instead; TypeScript
359
+ type-position `typeof` queries remain allowed.
360
+
361
+ Pattern example:
362
+
363
+ ```text
364
+ Preferred:
365
+ - Validate input in the public cc or task method before calling a service.
366
+ - Return the typed service response; augment failures with getErrorDetails.
367
+ - Log with LoggerProxy and {module, method, trackingId}; time and track every operation.
368
+
369
+ Avoid:
370
+ - Passing unvalidated payloads deep into the services.
371
+ - Swallowing exceptions, double-logging after getErrorDetails, or synthesizing success.
372
+ - Raw event-name strings, console logging, or logging tokens.
373
+ ```
374
+
375
+ Before submitting code (each rule lives in the linked subsection):
376
+
377
+ - All public APIs have JSDoc with `@public`, `@param`, `@returns`, `@example`
378
+ ([Naming and files](#naming-and-files)).
379
+ - LoggerProxy used for all logging with module/method context; no `console.log` or `console.error`
380
+ ([Logging, metrics, and errors](#logging-metrics-and-errors)).
381
+ - MetricsManager tracks success/failure for all operations
382
+ ([Logging, metrics, and errors](#logging-metrics-and-errors)).
383
+ - Error handling follows the `getErrorDetails` pattern
384
+ ([Logging, metrics, and errors](#logging-metrics-and-errors)).
385
+ - No hardcoded credentials or sensitive data ([Never](#never)).
386
+ - Event constants used (not string literals) ([Events](#events)).
387
+ - Method names added to the owning `METHODS` constant ([Services and constants](#services-and-constants)).
388
+ - Types exported appropriately ([Public methods and new code placement](#public-methods-and-new-code-placement)).
389
+ - Unit tests added/updated ([Testing Workflow](#4-testing-workflow)).
390
+ - No `any` types without justification (Coding expectations above).
391
+
392
+ ### Naming and files
393
+
394
+ Use PascalCase classes/files, camelCase methods, SCREAMING_SNAKE_CASE constants, and typed event
395
+ constants from their owning module.
396
+
397
+ | Element | Convention | Example |
398
+ |---|---|---|
399
+ | Classes | PascalCase | `ContactCenter`, `TaskManager` |
400
+ | Interfaces | PascalCase with `I` prefix for contracts | `IContactCenter`, `ITask`, `IVoice` |
401
+ | Types | PascalCase | `SetStateResponse`, `BuddyAgentsResponse` |
402
+ | Enums/Constants | SCREAMING_SNAKE_CASE | `CC_EVENTS`, `METRIC_EVENT_NAMES` |
403
+ | Methods | camelCase | `stationLogin`, `setAgentState` |
404
+ | Private properties | camelCase with `$` prefix for SDK references | `$webex`, `$config` |
405
+ | Regular private | camelCase | `agentConfig`, `eventEmitter` |
406
+ | Module constants | SCREAMING_SNAKE_CASE | `CC_FILE`, `READY` |
407
+
408
+ Public value objects that mirror wire values are PascalCase too (`LoginOption`, `VoiceLineStatus`).
409
+
410
+ | Type | Convention | Example |
411
+ |------|------------|---------|
412
+ | Class files | PascalCase | `TaskManager.ts`, `WebSocketManager.ts` |
413
+ | Type files | lowercase | `types.ts` |
414
+ | Constant files | lowercase | `constants.ts` |
415
+ | Index files | lowercase | `index.ts` |
416
+ | Utility files | PascalCase | `Utils.ts`, `Err.ts` |
417
+
418
+ Older modules keep kebab-case or camelCase names (`aqm-reqs.ts`, `connection-service.ts`,
419
+ `logger-proxy.ts`, `taskDataNormalizer.ts`, `uiControlsComputer.ts`); do not rename them.
420
+
421
+ JSDoc: all public methods and types must have comprehensive JSDoc with `@public`, `@param`,
422
+ `@returns`, `@throws` where the method rejects, and `@example`; typedoc (`yarn workspace @webex/contact-center build:docs`) renders
423
+ them. Mark internals with the `@private` or `@ignore` tag:
424
+
425
+ ```typescript
426
+ /**
427
+ * Internal utility function.
428
+ * @private
429
+ * @ignore
430
+ */
431
+ private helperMethod(): void {
432
+ // implementation
433
+ }
434
+ ```
435
+
436
+ ```typescript
437
+ /**
438
+ * Description of what this type represents.
439
+ * @public
440
+ */
441
+ export type MyType = {
442
+ /** Description of this field */
443
+ fieldName: string;
444
+ /** Optional field description */
445
+ optionalField?: number;
446
+ };
447
+ ```
448
+
449
+ A rejection's reason is the error `message` (see [Logging, metrics, and errors](#logging-metrics-and-errors)),
450
+ so document `@throws {Error}` with the reason in `error.message`.
451
+
452
+ ### Logging, metrics, and errors
453
+
454
+ Logging: use LoggerProxy with module/method context and tracking identifiers; never use console
455
+ logging in implementation or log credentials/sensitive data (`console` appears only inside JSDoc
456
+ examples).
457
+
458
+ ```typescript
459
+ // ✅ REQUIRED pattern
460
+ import LoggerProxy from '../../logger-proxy';
461
+
462
+ LoggerProxy.info('Starting operation', {
463
+ module: 'ModuleName',
464
+ method: 'methodName',
465
+ });
466
+ ```
467
+
468
+ `LogContext` (`src/types.ts`) has optional `module`, `method`, `interactionId`, `trackingId`, `data`,
469
+ and `error` fields. Always pass `module` (the file constant such as `CC_FILE`) and `method` (a
470
+ `METHODS` entry); `LoggerProxy.format` writes `unknown` when they are missing. Add `trackingId` for
471
+ request correlation, `interactionId` for the task or call, `data` for extra context, and `error` for
472
+ error logs. Event handlers log each reception the same way: `handleWebsocketMessage` in `src/cc.ts`
473
+ calls `LoggerProxy.log` with `Received event:` plus the event type, `module: CC_FILE`, and
474
+ `method: METHODS.HANDLE_WEBSOCKET_MESSAGE`.
475
+
476
+ | Level | Use Case | Example |
477
+ |---|---|---|
478
+ | `trace` | Detailed debugging | Entry/exit of complex functions |
479
+ | `log` | General information | Operation completed successfully |
480
+ | `info` | Important milestones | Starting registration, login |
481
+ | `warn` | Potential issues | Non-critical issues that don't break flow: the disabled campaign-preview actions in `src/cc.ts`, an empty dial number in `src/services/core/Utils.ts`; no stack trace |
482
+ | `error` | Failures | API errors, exceptions in catch blocks (the default for failure paths); `LoggerProxy.format` appends the stack only at this level, when the context `error` is an `Error` |
483
+
484
+ Never log sensitive data:
485
+
486
+ ```typescript
487
+ // ❌ WRONG
488
+ LoggerProxy.log(`User token: ${token}`);
489
+
490
+ // ✅ CORRECT
491
+ LoggerProxy.log('Token received', {
492
+ module: 'Auth',
493
+ method: 'login',
494
+ // No sensitive data in logs
495
+ });
496
+ ```
497
+
498
+ Errors: preserve structured backend details and tracking ids through shared Core helpers; never
499
+ swallow failures or synthesize success. In a catch block, read `const failure = error.details as
500
+ Failure`, track the failure metric, then throw the `error` that `getErrorDetails(error, methodName,
501
+ moduleName)` returns (task API calls use `generateTaskErrorObject`); its `message` is the backend
502
+ reason. Both helpers already log through `LoggerProxy.error` and upload logs (both skipped by
503
+ `getErrorDetails` for `AGENT_NOT_FOUND` during `silentRelogin`), so do not double-log errors when
504
+ using `getErrorDetails`. The helper contracts and the `Failure` fields are in
505
+ [core Caller-visible failure modes](src/services/core/docs/README.md#caller-visible-failure-modes).
506
+
507
+ Metrics: `MetricsManager.getInstance({webex})` returns the singleton. Start timing at method entry
508
+ with `timeEvent([SUCCESS, FAILED])`, then call `trackEvent(name, payload, types)` on the success path
509
+ and in the catch block. `types` is a list of `'behavioral'`, `'operational'`, and `'business'`
510
+ (default `['behavioral']`). Build payloads with `MetricsManager.getCommonTrackingFieldForAQMResponse`
511
+ and `getCommonTrackingFieldForAQMResponseFailed`. Add new events to `src/metrics/constants.ts` inside
512
+ `METRIC_EVENT_NAMES`, named with `_SUCCESS` and `_FAILED` suffixes (for example
513
+ `FETCH_BUDDY_AGENTS_SUCCESS` / `FETCH_BUDDY_AGENTS_FAILED`) and valued in title case
514
+ (`'Fetch Buddy Agents Success'`); a behavioral event also needs its taxonomy in
515
+ `src/metrics/behavioral-events.ts`. Details:
516
+ [`src/metrics/docs/README.md`](src/metrics/docs/README.md).
517
+
518
+ Standard public method, as `getBuddyAgents` in `src/cc.ts` implements it:
519
+
520
+ ```typescript
521
+ public async getBuddyAgents(data: BuddyAgents): Promise<BuddyAgentsResponse> {
522
+ const {action, state, mediaType = 'telephony'} = data;
523
+ const buddyAgentState = state ?? (action === 'Transfer' ? AGENT_STATE_AVAILABLE : undefined);
524
+
525
+ LoggerProxy.info('Fetching buddy agents', {
526
+ module: CC_FILE,
527
+ method: METHODS.GET_BUDDY_AGENTS,
528
+ });
529
+ try {
530
+ this.metricsManager.timeEvent([
531
+ METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_SUCCESS,
532
+ METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_FAILED,
533
+ ]);
534
+ const resp = await this.services.agent.buddyAgents({
535
+ data: {
536
+ agentProfileId: this.agentConfig.agentProfileID,
537
+ mediaType,
538
+ ...(buddyAgentState ? {state: buddyAgentState} : {}),
539
+ },
540
+ });
541
+
542
+ this.metricsManager.trackEvent(
543
+ METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_SUCCESS,
544
+ {
545
+ ...MetricsManager.getCommonTrackingFieldForAQMResponse(resp),
546
+ mediaType,
547
+ buddyAgentState,
548
+ buddyAgentCount: resp.data.agentList.length,
549
+ },
550
+ ['operational']
551
+ );
552
+
553
+ LoggerProxy.log(`Successfully retrieved ${resp.data.agentList.length} buddy agents`, {
554
+ module: CC_FILE,
555
+ method: METHODS.GET_BUDDY_AGENTS,
556
+ trackingId: resp.trackingId,
557
+ });
558
+
559
+ return resp;
560
+ } catch (error) {
561
+ const failureResp = error.details as Failure;
562
+
563
+ this.metricsManager.trackEvent(
564
+ METRIC_EVENT_NAMES.FETCH_BUDDY_AGENTS_FAILED,
565
+ {
566
+ ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failureResp),
567
+ mediaType,
568
+ buddyAgentState,
569
+ },
570
+ ['operational']
571
+ );
572
+ const {error: detailedError} = getErrorDetails(error, METHODS.GET_BUDDY_AGENTS, CC_FILE);
573
+ throw detailedError;
574
+ }
575
+ }
576
+ ```
577
+
578
+ When a catch block does not use `getErrorDetails`, at minimum log the error and rethrow:
579
+
580
+ ```typescript
581
+ // ❌ WRONG - silently swallowing errors
582
+ try {
583
+ await riskyOperation();
584
+ } catch (error) {
585
+ // doing nothing
586
+ }
587
+
588
+ // ✅ CORRECT - at minimum log the error
589
+ try {
590
+ await riskyOperation();
591
+ } catch (error) {
592
+ LoggerProxy.error(`Operation failed: ${error}`, {
593
+ module: 'ModuleName',
594
+ method: 'methodName',
595
+ });
596
+ throw error;
597
+ }
598
+ ```
599
+
600
+ ### Events
601
+
602
+ Define events as const objects with `as const`:
603
+
604
+ ```typescript
605
+ export const MY_EVENTS = {
606
+ SUCCESS: 'MySuccess',
607
+ FAILED: 'MyFailed',
608
+ } as const;
609
+
610
+ // Extract union type
611
+ type Enum<T extends Record<string, unknown>> = T[keyof T];
612
+ export type MY_EVENTS = Enum<typeof MY_EVENTS>;
613
+ ```
614
+
615
+ That is the pattern for WebSocket wire names, where const objects give runtime access to the values:
616
+ `CC_EVENTS = {...CC_AGENT_EVENTS, ...CC_TASK_EVENTS}` in `src/services/config/types.ts` (for example `AGENT_STATE_CHANGE: 'AgentStateChange'`). The names
617
+ the SDK emits to applications are TypeScript enums: `AGENT_EVENTS` in `src/services/agent/types.ts`
618
+ (`'agent:stateChange'`, `'agent:stationLoginSuccess'`, ...), `TASK_EVENTS` in
619
+ `src/services/task/types.ts` (`'task:incoming'`, `'task:hydrate'`, `'task:autoAnswered'`, ...), and
620
+ `VOICE_CONNECTION_EVENTS` in `src/services/config/types.ts`.
621
+
622
+ Always use event constants:
623
+
624
+ ```typescript
625
+ import {AGENT_EVENTS} from './services/agent/types';
626
+
627
+ // ✅ CORRECT
628
+ this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE, eventData);
629
+
630
+ // ❌ WRONG
631
+ this.emit('stateChange', eventData);
632
+ ```
633
+
634
+ There are two methods for emitting events, `trigger` and `emit`, and which one to use depends on what
635
+ the class extends:
636
+
637
+ | Class extends | Method | `@ts-ignore` needed? | Example classes |
638
+ |---------------|--------|----------------------|-----------------|
639
+ | `WebexPlugin` | `trigger` | Yes | `cc.ts` (ContactCenter) |
640
+ | `EventEmitter` | `emit` | No | Task, TaskManager, WebCallingService, WebSocketManager, ConnectionService |
641
+
642
+ `ContactCenter` extends `WebexPlugin`, whose Ampersand events mixin aliases `emit` to `trigger`; the
643
+ typings expose neither, so both need `// @ts-ignore` on `cc`. `src/cc.ts` uses `trigger` for events it
644
+ forwards from `TaskManager` and `WebCallingService` (`handleIncomingTask`, `handleTaskHydrate`,
645
+ `handleVoiceConnectionStateChange`) and `emit` in `handleWebsocketMessage` for agent events and the
646
+ wellness break. For new code on the `cc` object, use `trigger`, and keep an existing call's method,
647
+ because the specs spy on it.
648
+
649
+ Always store the callback as a named function reference; inline anonymous functions make it
650
+ impossible to call `.off()`. Prefer arrow function properties (`handleWebsocketMessage`, `handleIncomingTask`), which keep `this` and one
651
+ reference; a `.bind(this)` at registration creates a reference that `off()` cannot match. The known
652
+ listener-cleanup defects are recorded in
653
+ [Pitfalls and constraints](src/docs/README.md#pitfalls-and-constraints).
654
+
655
+ Internal services listen to each other: the constructor's `this.$webex.once(READY, ...)` block
656
+ registers the `TaskManager` listeners (`incomingTaskListener()`), `register()` registers the WebSocket
657
+ `message` listener and, through `setupEventListeners()`, the `connectionLost` listener, and
658
+ `deregister()` removes them. Always clean up resources: every `on()` must have a corresponding `off()`
659
+ in the deregister/cleanup path, and an open socket is closed only after checking `isSocketClosed`:
660
+
661
+ ```typescript
662
+ public async deregister(): Promise<void> {
663
+ // Remove event listeners
664
+ this.taskManager.off(TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
665
+ this.services.webSocketManager.off('message', this.handleWebsocketMessage);
666
+
667
+ // Close connections
668
+ if (!this.services.webSocketManager.isSocketClosed) {
669
+ this.services.webSocketManager.close(false, 'Unregistering the SDK');
670
+ }
671
+
672
+ // Clear state
673
+ this.agentConfig = null;
674
+ }
675
+ ```
676
+
677
+ Applications subscribe on the `cc` object or on task instances. Always use named callbacks so `.off()`
678
+ can reference the same function:
679
+
680
+ ```typescript
681
+ const cc = webex.cc;
682
+
683
+ // Define named callbacks (required for .off() to work)
684
+ const handleStateChange = (event) => {
685
+ // handle agent state change
686
+ };
687
+
688
+ const handleLoginSuccess = (event) => {
689
+ // handle login success
690
+ };
691
+
692
+ const handleIncomingTask = (task) => {
693
+ // handle incoming task
694
+ };
695
+
696
+ // Subscribe — agent events (from cc)
697
+ cc.on(AGENT_EVENTS.AGENT_STATE_CHANGE, handleStateChange);
698
+ cc.on(AGENT_EVENTS.AGENT_STATION_LOGIN_SUCCESS, handleLoginSuccess);
699
+
700
+ // Subscribe — task events (from cc)
701
+ cc.on(TASK_EVENTS.TASK_INCOMING, handleIncomingTask);
702
+
703
+ // Unsubscribe — pass the same function reference
704
+ cc.off(AGENT_EVENTS.AGENT_STATE_CHANGE, handleStateChange);
705
+ cc.off(AGENT_EVENTS.AGENT_STATION_LOGIN_SUCCESS, handleLoginSuccess);
706
+ cc.off(TASK_EVENTS.TASK_INCOMING, handleIncomingTask);
707
+ ```
708
+
709
+ Events flow through a standard pipeline: receive from transport, parse, log, route, and emit to
710
+ listeners. For `cc`, the Register and Recovery flows in
711
+ [`src/docs/README.md`](src/docs/README.md#data-flow-and-sequence-coverage) and its
712
+ [Protocol and wire format](src/docs/README.md#protocol-and-wire-format) (the `CC_EVENTS` allow-list)
713
+ own the details; the WebSocket transport is in
714
+ [`src/services/core/docs/README.md`](src/services/core/docs/README.md#data-flow-and-sequence-coverage).
715
+
716
+ To add a new event:
717
+
718
+ 1. Add the wire constant to the matching `CC_*_EVENTS` object in `src/services/config/types.ts`; it
719
+ joins `CC_EVENTS`, and therefore the re-emit allow-list, through the spread.
720
+ 2. Add the application-facing name to `AGENT_EVENTS` (`'agent:...'`) or `TASK_EVENTS` (`'task:...'`).
721
+ 3. Handle it in `handleWebsocketMessage` (agent events) or the task WebSocket handling in
722
+ `TaskManager`, using the method rule above.
723
+ 4. Document it in the emitting method's JSDoc and export any new payload type from `src/index.ts`.
724
+
725
+ ### Services and constants
726
+
727
+ Services use singleton pattern via `Services` class:
728
+
729
+ ```typescript
730
+ // Access services through Services singleton
731
+ this.services = Services.getInstance({
732
+ webex: this.$webex,
733
+ connectionConfig: this.getConnectionConfig(),
734
+ });
735
+
736
+ // Use services
737
+ await this.services.agent.stationLogin({data});
738
+ await this.services.config.getAgentConfig(orgId, agentId);
739
+ ```
740
+
741
+ `Services` (`src/services/index.ts`) holds `agent` (`routingAgent`), `config` (`AgentConfigService`),
742
+ `contact` (`src/services/task/contact.ts`), `dialer` (`src/services/task/dialer.ts`),
743
+ `webSocketManager`, `rtdWebSocketManager`, and `connectionService`. `ContactCenter` builds it, the
744
+ `TaskManager` and `MetricsManager` singletons, and the single-file services inside its
745
+ `this.$webex.once(READY, ...)` block; non-AQM services are instantiated directly in `cc.ts`. Details:
746
+ [`src/services/docs/README.md`](src/services/docs/README.md).
747
+
748
+ Agent/contact services use factory pattern: an AQM service is a function of `AqmReqs` that returns
749
+ `routing.req` (or `routing.reqEmpty`) request definitions. The real `stateChange` in
750
+ `src/services/agent/index.ts`:
751
+
752
+ ```typescript
753
+ stateChange: routing.req((p: {data: Agent.StateChange}) => ({
754
+ url: '/v1/agents/session/state',
755
+ host: WCC_API_GATEWAY,
756
+ data: p.data,
757
+ err,
758
+ method: HTTP_METHODS.PUT,
759
+ notifSuccess: {
760
+ bind: {
761
+ type: CC_EVENTS.AGENT_STATE_CHANGE,
762
+ data: {type: CC_EVENTS.AGENT_STATE_CHANGE_SUCCESS},
763
+ },
764
+ msg: {} as Agent.StateChangeSuccess,
765
+ },
766
+ notifFail: {
767
+ bind: {
768
+ type: CC_EVENTS.AGENT_STATE_CHANGE,
769
+ data: {type: CC_EVENTS.AGENT_STATE_CHANGE_FAILED},
770
+ },
771
+ errId: 'Service.aqm.agent.stateChange',
772
+ },
773
+ })),
774
+ ```
775
+
776
+ `method` is optional: `aqm-reqs.ts` defaults to POST when `data` is present and GET otherwise.
777
+ `notifSuccess.bind` and `notifFail.bind` match the WebSocket message `type` and `data.type` that settle
778
+ the promise, and `errId` names the `Err.Details` failure. The flow is HTTP request, backend
779
+ processing, then the WS message: `aqm-reqs` resolves or rejects the promise from that message, and
780
+ `cc.ts` `handleWebsocketMessage()` receives the same message and emits the matching `AGENT_EVENTS`
781
+ name. `getBuddyAgents` works the same way: its result is the `BuddyAgents` WebSocket
782
+ message, not the HTTP response. Methods that call REST directly (`AgentConfigService`, the single-file
783
+ services) use `WebexRequest`.
784
+
785
+ Single-file REST services (`AddressBook.ts`, `EntryPoint.ts`, `Queue.ts`, `UserPreference.ts`) use
786
+ `WebexRequest.getInstance({webex})` for HTTP calls (not raw `webex.request`), `PageCache` for
787
+ pagination, and `MetricsManager` for tracking. Their constructor takes `webex` and, for a profile
788
+ dependency, a getter, as in `new AddressBook(this.$webex, () => this.agentConfig?.addressBookId)`.
789
+ They export the class both named and as default. Study `src/services/AddressBook.ts` or
790
+ `src/services/EntryPoint.ts` as the reference implementation for a new REST service.
791
+
792
+ | Placement | Integration point | Types location | Constants location |
793
+ |---|---|---|---|
794
+ | **Folder-based** | `cc.ts` or `Services` singleton | Service folder's `types.ts` | Service folder's `constants.ts` |
795
+ | **Single-file** | `cc.ts` directly | Root `src/types.ts` | `src/services/constants.ts` |
796
+ | **Sub-module** | Parent service | Parent's `types.ts` | Parent's `constants.ts` |
797
+
798
+ Single-file service types such as `AddressBookEntry`, `EntryPointRecord`, and `ContactServiceQueue`
799
+ are defined in root `src/types.ts`; some live elsewhere (`UserPreference` types are in
800
+ `src/services/config/types.ts`).
801
+
802
+ Folder-based services are `agent/` (`index.ts` and `types.ts`), `config/` (`index.ts`, `types.ts`,
803
+ `constants.ts`, `Util.ts`), `core/`, and `task/`; sub-modules are files inside a service folder, such
804
+ as `task/voice/Voice.ts` and `task/digital/Digital.ts`, which `TaskFactory` instantiates.
805
+
806
+ Constants hierarchy (search in this order before adding one):
807
+
808
+ | Level | File | What lives here | Examples |
809
+ |---|---|---|---|
810
+ | **Root** | `src/constants.ts` | SDK-wide file names, method names, global settings | `CC_FILE`, `TASK_FILE`, `READY`, `METHODS`, `TIMEOUT_DURATION` |
811
+ | **Services shared** | `src/services/constants.ts` | API gateways, auth, network constants shared across services | `WCC_API_GATEWAY`, `POST_AUTH`, `WEBSOCKET_EVENT_TIMEOUT` |
812
+ | **Metrics** | `src/metrics/constants.ts` | All metric event names | `METRIC_EVENT_NAMES` (single object with all events) |
813
+ | **Config** | `src/services/config/constants.ts` | Endpoint maps, pagination defaults, agent states | `endPointMap`, `DEFAULT_PAGE_SIZE`, `AGENT_STATE_AVAILABLE` |
814
+ | **Core** | `src/services/core/constants.ts` | Transport timeouts and keepalive settings | `TIMEOUT_REQ`, `KEEPALIVE_WORKER_INTERVAL` |
815
+ | **Service-specific** | `src/services/task/constants.ts` | Constants used only within that service | `TASK_API`, `HOLD`, `TIMEOUT_PREVIEW_ACCEPT` |
816
+
817
+ Before defining any new constant, search the existing constants hierarchy to check if it already
818
+ exists or belongs at a shared level; duplicates or a constant at the wrong level create drift. For
819
+ each constant: grep for the constant name or value across all `constants.ts` files; if found,
820
+ import from that file and do not redefine it; if not found, add it at the narrowest correct level.
821
+ Create a new `constants.ts` only for a folder-based service that has none and has constants that do
822
+ not belong at a shared level (`agent/` has none). `TASK_FILE` already exists twice, in
823
+ `src/constants.ts` (`'Task'`) and `src/services/task/constants.ts` (`'task'`); `METHODS` exists per
824
+ level (root, config, core, task), so add a method name to the `METHODS` of the file whose module
825
+ logs it.
826
+
827
+ ### Public methods and new code placement
828
+
829
+ - The public method lives on the object that owns the feature's scope: `cc` (`src/cc.ts`) for
830
+ SDK-level operations (`cc.stationLogin()`, `cc.setAgentState()`), `task` for per-interaction
831
+ operations (`task.hold()`, `task.transfer()`, `task.end()`). New public objects may be introduced in
832
+ the future. If the feature is internal to a service or only consumed by other services, it gets no
833
+ public method.
834
+ - A public method is either a public wrapper over an internal service call, where the
835
+ implementation lives in a service module and the public method delegates to it (`cc.getBuddyAgents`
836
+ calls `this.services.agent.buddyAgents` with `agentProfileId` from `this.agentConfig`), or a public
837
+ service accessor. Use the public service accessors on `cc` (`cc.addressBook.getEntries()`,
838
+ `cc.queue.getQueues()`), not `cc.services`, which is private; `entryPoint` is private and reached
839
+ through the `cc.getEntryPoints()` wrapper.
840
+ - Task methods are defined on `Task` (`src/services/task/Task.ts`) and overridden per channel in
841
+ `Voice`, `WebRTC`, and `Digital`; the base method calls `unsupportedMethodError` for a channel that
842
+ does not support it (`Voice.hold()` delegates to `holdResume()`, which calls `this.contact.hold`).
843
+ - Feature placement: extend an existing service when the feature naturally extends current service
844
+ responsibility, needs only 1-2 methods in the same domain, or the service already owns the required
845
+ events, state, or API integration. Create a new service or module when the feature introduces a
846
+ distinct domain boundary/responsibility, needs its own lifecycle, dependencies, or state
847
+ orchestration, is expected to grow into multiple related methods/classes, or would create low
848
+ cohesion or cross-domain coupling in an existing service.
849
+ - Emit events only when consumers need to react asynchronously to state changes (WS-driven methods
850
+ like `stationLogin`, `setAgentState`); for a request-response method, the returned Promise is
851
+ sufficient.
852
+ - Types: public types (what consumers see) go in `src/types.ts`; internal/service types (with extra
853
+ fields like `agentProfileId`) go in `src/services/[service]/types.ts`. For example the public
854
+ `BuddyAgents` in `src/types.ts` has optional `mediaType`, `state`, and `action`, while
855
+ `src/services/agent/types.ts` `BuddyAgents` adds the required `agentProfileId`;
856
+ `BuddyAgentsResponse` is `Agent.BuddyAgentsSuccess | Error`. A type is published only when
857
+ `src/index.ts` exports it (`export type {...} from './types'` or from a service `types.ts`).
858
+ - A new top-level public service is a `public` property on `ContactCenter` with JSDoc, created in the
859
+ `this.$webex.once(READY, ...)` block; an AQM service is a new `Services` member created from
860
+ `aqmReq`; a sub-module is created by its parent.
861
+
862
+ ### Common bug patterns
863
+
864
+ Trace the execution flow along the call chain plugin → service → core, find where behavior diverges
865
+ from the expected behavior, and check whether existing tests should have caught it.
866
+
867
+ - Async/Promise issues: a service call that is not awaited (`await this.services.agent.stateChange({data})`).
868
+ - Missing error handling: an empty `catch`; route it through `getErrorDetails` and rethrow.
869
+ - Event listener leaks: a listener registered without a stored reference or without a matching
870
+ `off()` (see [Events](#events)).
871
+ - Type mismatches: reading the wrong property of a response; check the actual response type (AQM
872
+ responses such as `StationLoginSuccess` are `Msg` envelopes with the payload under `data`, while
873
+ emitted event payloads are that inner `data`).
874
+ - Missing null checks: the compiler does not enforce them, so use optional chaining
875
+ (`this.agentConfig?.teams?.[0]?.name`).
876
+
877
+ ## 6. Git Workflow
878
+
879
+ - Branch naming: no package convention is defined; follow the workspace `CONTRIBUTING.md`.
880
+ - Commit format: conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`), which
881
+ the workspace `CONTRIBUTING.md` requires for pull requests.
882
+ - Keep commits focused and reversible.
883
+ - Rebase on the target branch before opening a pull request.
884
+
885
+ PR checklist:
886
+
887
+ - What changed and why.
888
+ - Tests run and results, including the coverage summary.
889
+ - Risk and impact on applications that use `webex.cc`, task objects, the published types, and the
890
+ `umd/contact-center.min.js` bundle.
891
+ - Rollback approach.
892
+
893
+ ### Review checks
894
+
895
+ Run by a runtime different from the generator. Findings remain drafts until explicitly published.
896
+
897
+ | # | Check | What it verifies | Severity if it fails |
898
+ |---|---|---|---|
899
+ | C1 | Spec-currency + WHAT/WHY | Specs/docs and code land together; every requirement states WHAT and WHY | Blocking |
900
+ | C2 | Contract correctness | Provides/Requires and public API/event/type deltas are complete | Blocking |
901
+ | C3 | Code-vs-spec match | Signatures, flows, states, timeouts, and architecture match code | Blocking |
902
+ | C4 | Test adequacy | Positive/negative cases and 85% package threshold | Important |
903
+ | C5 | Error handling/input validation | Structured failures, tracking ids, validation, no swallowed errors | Important |
904
+ | C6 | Security baseline | Host auth, no secrets/sensitive logs, safe transport mapping | Blocking |
905
+
906
+ | # | Check | When it applies | What it verifies | Severity |
907
+ |---|---|---|---|---|
908
+ | K1 | Regression guard | Partial module or modified/removed guarantee | Characterization and invariants | Blocking |
909
+ | K2 | Grounding | Partial module | Stable file-path evidence; code cross-check | Important |
910
+ | K3 | Drift threshold | Any tracked module | Drift remains within policy | Important |
911
+ | K4 | Coverage-state accuracy | Promotion/demotion | Status matches evidence | Medium |
912
+
913
+ | # | Check | What it verifies | Severity |
914
+ |---|---|---|---|
915
+ | X1 | Cross-runtime review | Validator runtime differs from the generator runtime recorded in the manifest `validation` block | Blocking |
916
+ | X2 | Observability | LoggerProxy/metrics adequate; no sensitive logging | Medium |
917
+ | X3 | Rollout safety | Defaults, compatibility, rollback/recovery safe | Important |
918
+
919
+ 1. Run all six core checks.
920
+ 2. Add K1–K4 for current Partial modules.
921
+ 3. Add X1–X3 for high-risk, contract, security, state, transport, or autonomous changes.
922
+
923
+ Output: a compliance matrix, severity-sorted findings, and a Pass / Pass-with-warnings / Blocked
924
+ verdict. Draft only.
925
+
926
+ ## 7. Boundaries and Escalation
927
+
928
+ ### Always
929
+
930
+ - Prefer existing patterns over introducing new architecture.
931
+ - Keep changes minimal for the requested scope.
932
+ - Call out assumptions and unknowns explicitly.
933
+ - Read-only inspection and approved low-risk documentation maintenance may proceed without asking.
934
+ - Update the owning module spec and contract catalog in the same change as behavior, contracts,
935
+ state, events, or public types.
936
+ - Partial modules require code cross-checking and characterization before risky changes.
937
+ - Load this file, the router, and only the affected module specs; stop on a blocking contract,
938
+ security, source-fidelity, conformance, or validation finding. Generated specs require review by the
939
+ manifest-configured independent runtime.
940
+ - When a new service folder needs its own spec, add it as a manifest module with its spec at the
941
+ module's `docs/README.md` and route it from `docs/specs/README.md` (ask first).
942
+ - Add a rule here when a review correction recurs; remove duplication when tooling enforces it.
943
+
944
+ ### Ask First
945
+
946
+ - Code changes, public contract changes, state-machine changes, security-sensitive work, or new
947
+ dependencies.
948
+ - Breaking changes to existing APIs (method signatures, event names, `src/index.ts` exports, type
949
+ fields), with the migration path.
950
+ - Changing AQM bindings, timeouts, or retry and relogin behavior (`allowAutomatedRelogin`,
951
+ `TIMEOUT_REQ`).
952
+ - Renaming or revaluing a `METRIC_EVENT_NAMES` entry, which changes reported telemetry.
953
+ - Running `yarn workspace @webex/contact-center test:e2e`, which drives live Contact Center tenants with credentials from the
954
+ monorepo-root `cc_playwright/.env`.
955
+ - Large refactors, and any destructive data or infrastructure operation.
956
+
957
+ ### Never
958
+
959
+ - Push, publish, deploy, delete, or post externally without explicit human approval.
960
+ - Commit secrets, keys, or credentials: API keys, tokens, secrets; passwords or authentication data;
961
+ private keys or certificates. No hardcoded secrets, tokens, keys, or connection strings; never log
962
+ them.
963
+ - Bypass required checks by disabling tests or linters, or lower the coverage threshold.
964
+ - Edit `dist/` or `umd/` by hand.
965
+ - Rewrite history on shared branches.
966
+ - Change unrelated files "while here" without clear need.
967
+ - Add a `.sdd/templates` directory, a copy of the templates, or a link to them in this package. The
968
+ templates live once at the monorepo root, `../../../.sdd/templates/repo-standards`, and
969
+ `.sdd/manifest.json` refers to them through `layout.monorepo_package`.