@webex/contact-center 3.13.0-next.1 → 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 (84) hide show
  1. package/.repo-context.json +704 -0
  2. package/.sdd/manifest.json +1065 -339
  3. package/AGENTS.md +935 -60
  4. package/dist/webex.js +1 -1
  5. package/docs/adr/0001-spec-source-policy.md +97 -0
  6. package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
  7. package/docs/adr/0003-repo-standards-migration.md +104 -0
  8. package/docs/adr/index.md +35 -0
  9. package/docs/architecture.md +460 -0
  10. package/docs/getting-started.md +142 -0
  11. package/docs/index.md +53 -0
  12. package/docs/specs/README.md +98 -0
  13. package/package.json +10 -9
  14. package/schemas/repo-context.schema.json +796 -0
  15. package/src/docs/README.md +727 -0
  16. package/src/metrics/docs/README.md +710 -0
  17. package/src/services/agent/docs/README.md +673 -0
  18. package/src/services/config/docs/README.md +530 -0
  19. package/src/services/core/docs/README.md +993 -0
  20. package/src/services/docs/README.md +765 -0
  21. package/src/services/task/docs/README.md +1569 -0
  22. package/src/services/task/state-machine/docs/README.md +1388 -0
  23. package/src/utils/AGENTS.md +6 -4
  24. package/src/utils/docs/README.md +413 -0
  25. package/umd/contact-center.min.js +2 -2
  26. package/umd/contact-center.min.js.map +1 -1
  27. package/ai-docs/ARCHITECTURE.md +0 -168
  28. package/ai-docs/CONTRACTS.md +0 -64
  29. package/ai-docs/GETTING_STARTED.md +0 -168
  30. package/ai-docs/GLOSSARY.md +0 -43
  31. package/ai-docs/README.md +0 -138
  32. package/ai-docs/REVIEW_CHECKLIST.md +0 -41
  33. package/ai-docs/RULES.md +0 -444
  34. package/ai-docs/SECURITY.md +0 -52
  35. package/ai-docs/SERVICE_STATE.md +0 -52
  36. package/ai-docs/SPEC_INDEX.md +0 -65
  37. package/ai-docs/adr/0001-spec-source-policy.md +0 -55
  38. package/ai-docs/adr/README.md +0 -8
  39. package/ai-docs/adr/_adr-template.md +0 -31
  40. package/ai-docs/contact-center-spec.md +0 -388
  41. package/ai-docs/features/contact-owner-change-refactor.md +0 -78
  42. package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
  43. package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
  44. package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
  45. package/ai-docs/patterns/event-driven-patterns.md +0 -485
  46. package/ai-docs/patterns/testing-patterns.md +0 -480
  47. package/ai-docs/patterns/typescript-patterns.md +0 -365
  48. package/ai-docs/templates/README.md +0 -102
  49. package/ai-docs/templates/documentation/create-agents-md.md +0 -240
  50. package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
  51. package/ai-docs/templates/existing-service/bug-fix.md +0 -254
  52. package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
  53. package/ai-docs/templates/new-method/00-master.md +0 -80
  54. package/ai-docs/templates/new-method/01-requirements.md +0 -232
  55. package/ai-docs/templates/new-method/02-implementation.md +0 -295
  56. package/ai-docs/templates/new-method/03-tests.md +0 -201
  57. package/ai-docs/templates/new-method/04-validation.md +0 -141
  58. package/ai-docs/templates/new-service/00-master.md +0 -109
  59. package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
  60. package/ai-docs/templates/new-service/02-code-generation.md +0 -346
  61. package/ai-docs/templates/new-service/03-integration.md +0 -178
  62. package/ai-docs/templates/new-service/04-test-generation.md +0 -205
  63. package/ai-docs/templates/new-service/05-validation.md +0 -145
  64. package/src/metrics/ai-docs/AGENTS.md +0 -350
  65. package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
  66. package/src/metrics/ai-docs/metrics-spec.md +0 -971
  67. package/src/services/agent/ai-docs/AGENTS.md +0 -240
  68. package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
  69. package/src/services/agent/ai-docs/agent-spec.md +0 -505
  70. package/src/services/ai-docs/AGENTS.md +0 -386
  71. package/src/services/ai-docs/services-spec.md +0 -512
  72. package/src/services/config/ai-docs/AGENTS.md +0 -250
  73. package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
  74. package/src/services/config/ai-docs/config-spec.md +0 -669
  75. package/src/services/core/ai-docs/AGENTS.md +0 -381
  76. package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
  77. package/src/services/core/ai-docs/core-spec.md +0 -797
  78. package/src/services/task/ai-docs/AGENTS.md +0 -457
  79. package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
  80. package/src/services/task/ai-docs/task-spec.md +0 -1501
  81. package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
  82. package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
  83. package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
  84. package/src/utils/ai-docs/utils-spec.md +0 -391
package/ai-docs/RULES.md DELETED
@@ -1,444 +0,0 @@
1
- # Rules — @webex/contact-center
2
-
3
- > Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md). These rules are extracted from current package code and reviewed package documentation.
4
-
5
- ## Coverage Map (which docs/specs to trust)
6
- | Module | Manifest coverage state | What it means here |
7
- |---|---|---|
8
- | `src` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
9
- | `src/metrics` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
10
- | `src/services` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
11
- | `src/services/agent` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
12
- | `src/services/config` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
13
- | `src/services/core` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
14
- | `src/services/task` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
15
- | `src/services/task/state-machine` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
16
- | `src/utils` | Partial | Existing docs help, but code must be cross-checked until migration, coverage, and validation pass. |
17
-
18
- ## Autonomy & Ask-First
19
- - **May proceed:** read-only inspection and approved low-risk documentation maintenance.
20
- - **Ask first / plan + confirm:** code changes, public contract changes, state-machine changes, security-sensitive work, or new dependencies.
21
- - **Never without explicit human approval:** push, publish, deploy, delete, or post externally.
22
-
23
- Before submitting code:
24
-
25
- - [ ] All public APIs have JSDoc with `@public`, `@param`, `@returns`, `@example`
26
-
27
- - [ ] LoggerProxy used for all logging with module/method context
28
-
29
- - [ ] MetricsManager tracks success/failure for all operations
30
-
31
- - [ ] Error handling follows `getErrorDetails` pattern
32
-
33
- - [ ] No `console.log` or `console.error`
34
-
35
- - [ ] No hardcoded credentials or sensitive data
36
-
37
- - [ ] Event constants used (not string literals)
38
-
39
- - [ ] Types exported appropriately
40
-
41
- - [ ] Unit tests added/updated
42
-
43
- - [ ] No `any` types without justification
44
-
45
- ## Naming
46
- - Use PascalCase classes/files, camelCase methods, SCREAMING_SNAKE_CASE constants, and typed event constants from their owning module.
47
-
48
- > **Purpose**: Defines the coding standards, conventions, and architectural rules that all code in `@webex/contact-center` must follow.
49
-
50
- - TypeScript strict mode is enabled
51
-
52
- - Avoid `any` type unless absolutely necessary (document justification with `// eslint-disable-line`)
53
-
54
- - Prefer `unknown` over `any` for unknown types
55
-
56
- - All public APIs must have explicit return types
57
-
58
- | Element | Convention | Example |
59
- |---|---|---|
60
- | Classes | PascalCase | `ContactCenter`, `TaskManager` |
61
-
62
- | Element | Convention | Example |
63
- |---|---|---|
64
- | Interfaces | PascalCase with `I` prefix for contracts | `IContactCenter`, `ITask`, `IVoice` |
65
-
66
- | Element | Convention | Example |
67
- |---|---|---|
68
- | Types | PascalCase | `SetStateResponse`, `BuddyAgentsResponse` |
69
-
70
- | Element | Convention | Example |
71
- |---|---|---|
72
- | Enums/Constants | SCREAMING_SNAKE_CASE | `CC_EVENTS`, `METRIC_EVENT_NAMES` |
73
-
74
- | Element | Convention | Example |
75
- |---|---|---|
76
- | Methods | camelCase | `stationLogin`, `setAgentState` |
77
-
78
- | Element | Convention | Example |
79
- |---|---|---|
80
- | Private properties | camelCase with `$` prefix for SDK references | `$webex`, `$config` |
81
-
82
- | Element | Convention | Example |
83
- |---|---|---|
84
- | Regular private | camelCase | `agentConfig`, `eventEmitter` |
85
-
86
- | Element | Convention | Example |
87
- |---|---|---|
88
- | Module constants | SCREAMING_SNAKE_CASE | `CC_FILE`, `READY` |
89
-
90
- - Component files: `PascalCase.ts` (e.g., `TaskManager.ts`, `WebSocketManager.ts`)
91
-
92
- - Type files: `types.ts` in service folders
93
-
94
- - Constant files: `constants.ts` in service folders
95
-
96
- - Index files: `index.ts` for exports
97
-
98
- All public methods and types must have comprehensive JSDoc:
99
-
100
- Use `@private` or `@ignore` tag:
101
-
102
- ```typescript
103
- /**
104
- * Internal utility function.
105
- * @private
106
- * @ignore
107
- */
108
- private helperMethod(): void {
109
- // implementation
110
- }
111
- ```
112
-
113
- ```typescript
114
- /**
115
- * Description of what this type represents.
116
- * @public
117
- */
118
- export type MyType = {
119
- /** Description of this field */
120
- fieldName: string;
121
- /** Optional field description */
122
- optionalField?: number;
123
- };
124
- ```
125
-
126
- Add new events to `src/metrics/constants.ts`:
127
-
128
- ```typescript
129
- export const METRIC_EVENT_NAMES = {
130
- // Existing events...
131
- NEW_OPERATION_SUCCESS: 'new operation success',
132
- NEW_OPERATION_FAILED: 'new operation failed',
133
- } as const;
134
- ```
135
-
136
- - **TypeScript patterns**: [`patterns/typescript-patterns.md`](patterns/typescript-patterns.md)
137
-
138
- - **Testing patterns**: [`patterns/testing-patterns.md`](patterns/testing-patterns.md)
139
-
140
- - **Event patterns**: [`patterns/event-driven-patterns.md`](patterns/event-driven-patterns.md)
141
-
142
- ## Logging
143
- - Use LoggerProxy with module/method context and tracking identifiers; never use console logging in implementation or log credentials/sensitive data.
144
-
145
- ```typescript
146
- // ✅ REQUIRED pattern
147
- import LoggerProxy from '../../logger-proxy';
148
-
149
- LoggerProxy.info('Starting operation', {
150
- module: 'ModuleName',
151
- method: 'methodName',
152
- });
153
- ```
154
-
155
- | Level | Use Case | Example |
156
- |---|---|---|
157
- | `trace` | Detailed debugging | Entry/exit of complex functions |
158
-
159
- | Level | Use Case | Example |
160
- |---|---|---|
161
- | `log` | General information | Operation completed successfully |
162
-
163
- | Level | Use Case | Example |
164
- |---|---|---|
165
- | `info` | Important milestones | Starting registration, login |
166
-
167
- | Level | Use Case | Example |
168
- |---|---|---|
169
- | `warn` | Potential issues | Deprecated usage, fallback behavior |
170
-
171
- | Level | Use Case | Example |
172
- |---|---|---|
173
- | `error` | Failures | API errors, exceptions |
174
-
175
- ```typescript
176
- // All log calls MUST include module and method
177
- {
178
- module: 'FileName', // Required: Class/file name
179
- method: 'methodName', // Required: Current method name
180
- trackingId?: string, // Optional: Request correlation ID
181
- interactionId?: string, // Optional: Task/call ID
182
- data?: object, // Optional: Additional context
183
- error?: Error, // Optional: Error object for error logs
184
- }
185
- ```
186
-
187
- Never log sensitive data:
188
-
189
- ```typescript
190
- // ❌ WRONG
191
- LoggerProxy.log(`User token: ${token}`);
192
-
193
- // ✅ CORRECT
194
- LoggerProxy.log('Token received', {
195
- module: 'Auth',
196
- method: 'login',
197
- // No sensitive data in logs
198
- });
199
- ```
200
-
201
- ## Error Handling
202
- - Preserve structured backend details and tracking ids through shared Core helpers; never swallow failures or synthesize success.
203
-
204
- ```typescript
205
- import {getErrorDetails} from './services/core/Utils';
206
- import {Failure} from './services/core/GlobalTypes';
207
-
208
- try {
209
- const result = await this.riskyOperation();
210
- return result;
211
- } catch (error) {
212
- const failure = error.details as Failure;
213
-
214
- // 1. Track failure metrics
215
- this.metricsManager.trackEvent(
216
- METRIC_EVENT_NAMES.OPERATION_FAILED,
217
- MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure),
218
- ['operational']
219
- );
220
-
221
- // 2. Get detailed error (logs automatically)
222
- const {error: detailedError} = getErrorDetails(
223
- error,
224
- 'methodName',
225
- 'ModuleName'
226
- );
227
-
228
- // 3. Throw augmented error
229
- throw detailedError;
230
- }
231
- ```
232
-
233
- ```typescript
234
- // ❌ WRONG - silently swallowing errors
235
- try {
236
- await riskyOperation();
237
- } catch (error) {
238
- // doing nothing
239
- }
240
-
241
- // ✅ CORRECT - at minimum log the error
242
- try {
243
- await riskyOperation();
244
- } catch (error) {
245
- LoggerProxy.error(`Operation failed: ${error}`, {
246
- module: 'ModuleName',
247
- method: 'methodName',
248
- });
249
- throw error;
250
- }
251
- ```
252
-
253
- ## Imports / Dependencies
254
- - External packages first, then package types/constants, service imports, local utilities, and type-only imports. New runtime dependencies require approval.
255
-
256
- Services use singleton pattern via `Services` class:
257
-
258
- ```typescript
259
- // Access services through Services singleton
260
- this.services = Services.getInstance({
261
- webex: this.$webex,
262
- connectionConfig: this.getConnectionConfig(),
263
- });
264
-
265
- // Use services
266
- await this.services.agent.stationLogin({data});
267
- await this.services.config.getAgentConfig(orgId, agentId);
268
- ```
269
-
270
- Agent/contact services use factory pattern:
271
-
272
- ```typescript
273
- // services/agent/index.ts
274
- export default function routingAgent(routing: AqmReqs) {
275
- return {
276
- methodName: routing.req((p: {data: ParamType}) => ({
277
- url: '/v1/endpoint',
278
- host: WCC_API_GATEWAY,
279
- data: p.data,
280
- err: createErrDetailsObject,
281
- method: HTTP_METHODS.POST, // Optional, defaults to POST
282
- notifSuccess: {
283
- bind: {
284
- type: CC_EVENTS.SUCCESS_EVENT,
285
- data: {type: CC_EVENTS.SUCCESS_EVENT},
286
- },
287
- msg: {} as SuccessType,
288
- },
289
- notifFail: {
290
- bind: {
291
- type: CC_EVENTS.FAIL_EVENT,
292
- data: {type: CC_EVENTS.FAIL_EVENT},
293
- },
294
- errId: 'Service.aqm.agent.methodName',
295
- },
296
- })),
297
- };
298
- }
299
- ```
300
-
301
- 1. External packages (`@webex/*`, `events`, `uuid`)
302
-
303
- 2. Internal absolute imports (types, constants)
304
-
305
- 3. Relative imports (local files)
306
-
307
- ```typescript
308
- // 1. External
309
- import {WebexPlugin} from '@webex/webex-core';
310
- import EventEmitter from 'events';
311
- import {v4 as uuidv4} from 'uuid';
312
-
313
- // 2. Internal types/constants
314
- import {WebexSDK, CCPluginConfig, AgentLogin} from './types';
315
- import {READY, CC_FILE, METHODS} from './constants';
316
-
317
- // 3. Relative imports
318
- import Services from './services';
319
- import LoggerProxy from './logger-proxy';
320
- import {getErrorDetails} from './services/core/Utils';
321
- ```
322
-
323
- - Public types: Export from `src/types.ts`
324
-
325
- - Internal types: Export from service-level `types.ts`
326
-
327
- - Services: Use default export for main class, named exports for types
328
-
329
- ## Testing
330
- - Mirror source paths under `test/unit/spec/`; cover positive and negative behavior and retain the 85% global coverage threshold.
331
-
332
- For full testing patterns including test file location, MockWebex setup, singleton mocking, LoggerProxy mocking, and test structure, see [`patterns/testing-patterns.md`](patterns/testing-patterns.md).
333
-
334
- ## Security
335
- - Credentials come from the host Webex SDK; validate inputs, use authenticated service routing, and follow `SECURITY.md`.
336
-
337
- Never commit:
338
-
339
- - API keys, tokens, secrets
340
-
341
- - Passwords or authentication data
342
-
343
- - Private keys or certificates
344
-
345
- ## Spec-Currency & Drift Thresholds
346
- - Update specs/docs in the same change as behavior, contracts, state, events, or public types.
347
- - Partial modules require code cross-checking and characterization before risky changes.
348
-
349
- ## Secrets Policy
350
- - No hardcoded secrets, tokens, keys, or connection strings; never log them.
351
-
352
- ## Concurrency & Async
353
- - Preserve listener identity for cleanup, avoid blocking the event loop, maintain AQM correlation/timeouts, and keep metrics non-blocking.
354
-
355
- ```typescript
356
- // Start timing at method entry
357
- this.metricsManager.timeEvent([
358
- METRIC_EVENT_NAMES.SUCCESS_EVENT,
359
- METRIC_EVENT_NAMES.FAILED_EVENT,
360
- ]);
361
-
362
- // Track on success
363
- this.metricsManager.trackEvent(
364
- METRIC_EVENT_NAMES.SUCCESS_EVENT,
365
- {
366
- ...MetricsManager.getCommonTrackingFieldForAQMResponse(response),
367
- // Add operation-specific fields
368
- },
369
- ['behavioral', 'operational']
370
- );
371
-
372
- // Track on failure (in catch block)
373
- this.metricsManager.trackEvent(
374
- METRIC_EVENT_NAMES.FAILED_EVENT,
375
- {
376
- ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure),
377
- },
378
- ['behavioral', 'operational']
379
- );
380
- ```
381
-
382
- Define events as const objects with `as const`:
383
-
384
- ```typescript
385
- export const MY_EVENTS = {
386
- SUCCESS: 'MySuccess',
387
- FAILED: 'MyFailed',
388
- } as const;
389
-
390
- // Extract union type
391
- type Enum<T extends Record<string, unknown>> = T[keyof T];
392
- export type MY_EVENTS = Enum<typeof MY_EVENTS>;
393
- ```
394
-
395
- Always use event constants:
396
-
397
- ```typescript
398
- import {AGENT_EVENTS} from './services/agent/types';
399
-
400
- // ✅ CORRECT
401
- this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE, eventData);
402
-
403
- // ❌ WRONG
404
- this.emit('stateChange', eventData);
405
- ```
406
-
407
- Always use async/await over raw Promises:
408
-
409
- ```typescript
410
- // ✅ CORRECT
411
- public async fetchData(): Promise<Data> {
412
- const result = await this.service.getData();
413
- return result;
414
- }
415
-
416
- // ❌ AVOID (when possible)
417
- public fetchData(): Promise<Data> {
418
- return this.service.getData().then(result => result);
419
- }
420
- ```
421
-
422
- Always clean up resources:
423
-
424
- ```typescript
425
- public async deregister(): Promise<void> {
426
- // Remove event listeners
427
- this.taskManager.off(TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
428
- this.services.webSocketManager.off('message', this.handleWebsocketMessage);
429
-
430
- // Close connections
431
- if (!this.services.webSocketManager.isSocketClosed) {
432
- this.services.webSocketManager.close(false, 'Reason');
433
- }
434
-
435
- // Clear state
436
- this.agentConfig = null;
437
- }
438
- ```
439
-
440
- ## Strict-Compliance Mode
441
- - In rigorous SDD runs, stop on unresolved questionnaire facts, source-fidelity failures, template-conformance blockers, or validator findings. Generated specs require review by the manifest-configured independent runtime.
442
-
443
- ## Maintenance
444
- - Add a rule when a review correction recurs; remove duplication when tooling enforces it. Patterns remain in `patterns/`.
@@ -1,52 +0,0 @@
1
- # Security Baseline — @webex/contact-center
2
-
3
- > Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md).
4
-
5
- ## Trust Boundaries
6
-
7
- | Boundary | Untrusted side | Trusted side | What is enforced at the crossing |
8
- |---|---|---|---|
9
- | Exported SDK methods | Host application input | ContactCenter/module methods | Typed inputs, runtime validation where implemented, typed errors |
10
- | REST construction | SDK data | Webex request/service routing | Host credentials, service identifier, method/path/payload mapping |
11
- | WebSocket parsing | Remote messages | ContactCenter/Task/AqmReqs | JSON parsing, event-type mapping, correlation/guards |
12
- | Logs/metrics | Runtime data | Remote observability systems | Context selection and no credential/sensitive-data logging |
13
-
14
- ## Authentication & Authorization Model
15
-
16
- - **Authentication:** supplied and maintained by the host Webex SDK (`src/services/core/WebexRequest.ts`).
17
- - **Authorization:** remote WCC services enforce tenant/agent permissions; this package must not bypass host service routing.
18
- - **Default posture:** no standalone credentials or local authorization store.
19
-
20
- ## Secret & Credential Handling
21
-
22
- - Secrets source and injection: host Webex SDK/runtime configuration; never source code.
23
- - Rotation: owned by the host credential system and remote services.
24
- - **Hard rule:** never commit or log secrets, tokens, keys, or connection strings.
25
-
26
- ## Data Classification & Handling
27
-
28
- | Data class | Examples | Storage rule | Logging rule | In transit |
29
- |---|---|---|---|---|
30
- | Identity/PII | agent id/name/email, dial number | ephemeral client memory; remote system of record | do not log raw sensitive values | host-resolved HTTPS/WSS |
31
- | Interaction data | task/customer/call metadata | ephemeral task state; remote system of record | use tracking/interaction ids, minimize payloads | HTTPS/WSS/WebRTC |
32
- | Credentials | access tokens/service auth | host-owned only | never log | HTTPS/WSS |
33
-
34
- ## Input Validation & Output Encoding Posture
35
-
36
- - Validate public inputs before request construction; use typed constants and endpoint builders; never concatenate credentials or executable commands.
37
-
38
- ## Transport & Headers
39
-
40
- - Authenticated requests use the Webex SDK service catalog and HTTPS. Realtime traffic uses host-resolved WSS; header/environment behavior is owned by `src/services/core/WebexRequest.ts` and the host request layer.
41
-
42
- ## Known Sensitive Areas & Accepted Risks
43
-
44
- | Area | Risk | Mitigation / why accepted | Owner |
45
- |---|---|---|---|
46
- | Log upload | Runtime context could contain sensitive values | Shared error helpers upload only approved diagnostic context; never add credentials/payload dumps | Contact Center maintainers |
47
- | WebSocket event parsing | Malformed/unexpected remote data | Parse defensively, map known event constants, ignore/reject invalid transitions | Core/Task maintainers |
48
- | Public dial/contact/participant-drop inputs | PII, external numbers, and participant identifiers | Validate and avoid logging raw values; sensitive AQM operations redact dynamic URLs and raw routing failures | Contact Center maintainers |
49
-
50
- ## Reporting & Review
51
-
52
- - Security-sensitive changes require package-owner review and independent SDD validation. Report vulnerabilities through the repository's documented Cisco security/support process.
@@ -1,52 +0,0 @@
1
- # Service State (living) — @webex/contact-center
2
-
3
- > Start here → root [`AGENTS.md`](../AGENTS.md) · router [`SPEC_INDEX.md`](SPEC_INDEX.md) · system [`ARCHITECTURE.md`](ARCHITECTURE.md). Read before adding a surface.
4
-
5
- ## Current Events
6
-
7
- | Event / topic | Direction | Producer/consumer | Payload ref |
8
- |---|---|---|---|
9
- | `agent:*` | publish | ContactCenter → application | `src/services/agent/types.ts` |
10
- | `task:*` | publish | Task/TaskManager → application | `src/services/task/types.ts` |
11
- | `CC_EVENTS` | consume | WCC WebSocket → Core/ContactCenter/Task/AqmReqs | `src/services/config/types.ts` |
12
- | realtime transcript/suggestion | consume/publish | RTD WebSocket → owning Task | `src/services/task/TaskManager.ts` |
13
- | `Wellness_Break_Handler` | consume/publish | Primary data-notification WebSocket → ContactCenter → `CC_AGENT_EVENTS.WELLNESS_BREAK` | `src/cc.ts`, `src/types.ts` |
14
-
15
- ## Data Stores
16
-
17
- | Store | Purpose | Owned by this service? |
18
- |---|---|---|
19
- | In-memory PageCache Map | temporary paginated lookup reuse | ephemeral only; yes for cache entries |
20
- | Remote WCC stores | agent/task/config domain state | no |
21
-
22
- ## External Dependencies
23
-
24
- | Dependency | Used for | Timeout / retry | Circuit breaker / fallback |
25
- |---|---|---|---|
26
- | WCC API gateway | agent/task/config/data operations | operation/AQM timeouts | propagate structured failure |
27
- | WCC WebSocket/RTD | realtime events and completion | reconnect and recovery timers | reconnect/silent relogin/restore failure |
28
- | Webex Calling | BROWSER call lifecycle | async registration/call timeouts | emit/rethrow calling failure |
29
- | Webex metrics | telemetry | nonblocking queued submission | log/drop without breaking product flow |
30
-
31
- ## Key Metrics & Performance Targets
32
-
33
- | Signal | Target | Where measured |
34
- |---|---|---|
35
- | Unit coverage | 85% branches/functions/lines/statements | package Jest configuration |
36
- | Operation duration/success/failure | no local numeric SLO routed | MetricsManager event taxonomy |
37
- | Connection recovery | explicit 8s disconnect, 5s retry, configured restore timeout | Core constants/ConnectionService |
38
-
39
- ## Feature Flags (current)
40
-
41
- | Flag/config | Gates | Current default | Owner | Safe to remove when |
42
- |---|---|---|---|---|
43
- | `allowAutomatedRelogin` | silent relogin after recovery | config-defined | ContactCenter | replacement recovery contract exists |
44
- | `webRtcEnabled` / login option | browser calling path | remote profile | Config/WCC | remote contract removed |
45
- | task UI/config flags | task controls and operations | profile/config-defined | Task/Config | owning behavior removed |
46
- | `Profile.isWellnessBreakEnabled` | wellness event/action APIs and system-code access | false unless backend AI enablement, reminders, and positive license quantity are all present | Config/ContactCenter | wellness contract removed |
47
-
48
- The backend-delivered `agentWellbeing.enable` value is the supported server rollout decision. The SDK combines it with `wellnessBreakReminders === 'ENABLED'` and `aiAssistantQuantity > 0`; it does not evaluate the Desktop Split flag or define a new rollout response field.
49
-
50
- ## Maintenance
51
-
52
- - Update the relevant row in the same change as any surface, dependency, timeout, metric, or flag.
@@ -1,65 +0,0 @@
1
- # Spec Index — @webex/contact-center
2
-
3
- > Start here → root [`AGENTS.md`](../AGENTS.md). This router mirrors `.sdd/manifest.json`; system overview: [`ARCHITECTURE.md`](ARCHITECTURE.md).
4
-
5
- ## Module Registry
6
-
7
- | Module | Responsibility | Manifest coverage state | Start here |
8
- |---|---|---|---|
9
- | `src` | Own the published Webex Contact Center SDK plugin surface, registration lifecycle, public method delegation, and application-facing event routing. | Partial | `ai-docs/contact-center-spec.md` |
10
- | `src/metrics` | Own timing, taxonomy, queuing, payload preparation, and submission for Contact Center behavioral, operational, and business telemetry. | Partial | `src/metrics/ai-docs/metrics-spec.md` |
11
- | `src/services` | Own composition and bootstrap order for backend request, realtime, data, and WebRTC service collaborators. | Partial | `src/services/ai-docs/services-spec.md` |
12
- | `src/services/agent` | Own agent login, logout, state-change, buddy-agent, device-update, and silent-relogin request contracts. | Partial | `src/services/agent/ai-docs/agent-spec.md` |
13
- | `src/services/config` | Own retrieval and aggregation of remote organization, agent, team, profile, auxiliary-code, dial-plan, and feature configuration. | Partial | `src/services/config/ai-docs/config-spec.md` |
14
- | `src/services/core` | Own authenticated HTTP, realtime WebSocket lifecycle, AQM request correlation, reconnect/keepalive behavior, and shared error normalization. | Partial | `src/services/core/ai-docs/core-spec.md` |
15
- | `src/services/task` | Own task creation, media-specific behavior, call-control operations, lifecycle orchestration, task events, and integration with the task state machine. | Partial | `src/services/task/ai-docs/task-spec.md` |
16
- | `src/services/task/state-machine` | Own deterministic task lifecycle states, transition guards/actions, typed internal events, and state-derived UI-control availability. | Partial | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` |
17
- | `src/utils` | Own shared pagination contracts and the bounded in-memory page cache used by Contact Center data services. | Partial | `src/utils/ai-docs/utils-spec.md` |
18
-
19
- ## Task Routing
20
-
21
- | If the task is… | Load |
22
- |---|---|
23
- | Understanding the package | `ARCHITECTURE.md` |
24
- | Working in a module | That module's specification from the registry |
25
- | Changing exported APIs/events/types | `CONTRACTS.md`, Contact Center spec, and owning module spec |
26
- | Changing task state | Task and Task State Machine specs |
27
- | Changing transport/recovery | Core spec and `SECURITY.md` |
28
- | New feature or defect | Run lifecycle intake against the affected module specs |
29
-
30
- ## Intake Routing
31
-
32
- ```text
33
- New feature / bug / contract change → lifecycle intake questionnaire → feature spec/design
34
- New module → update module registry + module spec + contracts
35
- Doc/spec backfill → reconcile target → conformance → coverage → independent validation
36
- ```
37
-
38
- ## Incident History
39
-
40
- | INC id | Date | Module | One-line | Link |
41
- |---|---|---|---|---|
42
- | None routed | 2026-07-07 | N/A | No incident/RCA source was supplied during onboarding. | N/A |
43
-
44
- ## Phase-Based Loading Protocol
45
-
46
- | Phase | Load |
47
- |---|---|
48
- | Orient | AGENTS.md + this file |
49
- | Specify | relevant module specs + questionnaire |
50
- | Build | selected module specs + RULES/patterns |
51
- | Verify | independent validation and coverage evidence |
52
-
53
- ## Spec Registry
54
-
55
- | Doc | Location | Purpose |
56
- |---|---|---|
57
- | Patterns | `patterns/` | Existing implementation conventions |
58
- | Rules | `RULES.md` | Enforceable do/don't constraints |
59
- | Glossary | `GLOSSARY.md` | Domain language |
60
- | Security | `SECURITY.md` | Trust boundaries and sensitive-data rules |
61
- | Contracts | `CONTRACTS.md` | Public/export/event/dependency index |
62
- | Service state | `SERVICE_STATE.md` | Current as-built surfaces/dependencies/flags |
63
- | Getting started | `GETTING_STARTED.md` | Build/test loop |
64
- | Decision records | `adr/` | Durable architecture decisions |
65
- | Review catalog | `REVIEW_CHECKLIST.md` | Review gates |
@@ -1,55 +0,0 @@
1
- # ADR-0001 — Migrate legacy Contact Center AI docs into canonical SDD specs
2
-
3
- | Field | Value |
4
- |---|---|
5
- | Status | Accepted |
6
- | Date | 2026-07-07 |
7
- | Deciders | Package maintainer / user |
8
- | Supersedes / Superseded by | none |
9
-
10
- ## Context
11
-
12
- The Contact Center package already contained module-local `AGENTS.md`, `ARCHITECTURE.md`, pattern, and workflow documents before canonical SDD specifications were introduced. Those files contain useful intent and examples, but allowing them to remain co-equal with the generated `*-spec.md` files would make documentation routing ambiguous and could preserve statements that have drifted from `src/**` and `test/**`.
13
-
14
- The source inventory and canonical targets are recorded in `packages/@webex/contact-center/.sdd/manifest.json`. Code and tests remain the behavioral referee for every migrated statement.
15
-
16
- ## Decision
17
-
18
- Use the `migrate-existing` source policy.
19
-
20
- - Preserve relevant legacy content by meaning in the canonical SDD specification for each module.
21
- - Treat manifest-routed legacy documents as reference-only migration sources, not canonical specifications.
22
- - Route agents through `.sdd/manifest.json` and `ai-docs/SPEC_INDEX.md` to the canonical target.
23
- - Retain legacy files with a banner pointing to their canonical target; if documentation conflicts with code or tests, code and tests win.
24
-
25
- The SDD route replaces the former package-local workflow, classification summary, specification-summary gate, and service-routing tables with one sequence: read package `AGENTS.md`, select the owning spec through `SPEC_INDEX.md`, verify requirements against source/tests, obtain approval for the affected files/contracts, update code and its owning spec together, and run generator-side conformance plus independent semantic validation before staging.
26
-
27
- | Module | Canonical target |
28
- |---|---|
29
- | `src` | `ai-docs/contact-center-spec.md` |
30
- | `src/metrics` | `src/metrics/ai-docs/metrics-spec.md` |
31
- | `src/services` | `src/services/ai-docs/services-spec.md` |
32
- | `src/services/agent` | `src/services/agent/ai-docs/agent-spec.md` |
33
- | `src/services/config` | `src/services/config/ai-docs/config-spec.md` |
34
- | `src/services/core` | `src/services/core/ai-docs/core-spec.md` |
35
- | `src/services/task` | `src/services/task/ai-docs/task-spec.md` |
36
- | `src/services/task/state-machine` | `src/services/task/state-machine/ai-docs/task-state-machine-spec.md` |
37
- | `src/utils` | `src/utils/ai-docs/utils-spec.md` |
38
-
39
- ## Alternatives Considered
40
-
41
- | Alternative | Pros | Cons | Why rejected |
42
- |---|---|---|---|
43
- | Keep legacy and SDD docs separate and co-equal | No migration work | Agents must choose between competing authorities; drift remains likely | Does not establish deterministic routing |
44
- | Reconcile every legacy document in place | Preserves familiar paths | Keeps multiple canonical shapes and complicates validation | The package needs one template-compatible SDD surface |
45
- | Delete legacy documents after migration | Removes ambiguity | Loses useful historical examples and context | Reference material remains valuable when clearly marked noncanonical |
46
-
47
- ## Consequences
48
-
49
- - **Positive:** Each module has one machine-routed canonical specification and a durable, reviewable policy record.
50
- - **Negative / cost:** Retained legacy documents require reference-only banners and must not be updated as independent authorities.
51
- - **Agents must:** Read the manifest and `SPEC_INDEX.md`, open the canonical `*-spec.md`, and cross-check behavior against source and tests.
52
-
53
- ## Revisit When
54
-
55
- - A module is promoted from `Partial` to `Specced`, a canonical target is relocated, or a legacy file is proposed for removal.
@@ -1,8 +0,0 @@
1
- # Architecture Decision Records
2
-
3
- Use this append-only directory for durable decisions that constrain future Contact Center SDK work.
4
-
5
- - One decision per `NNNN-short-title.md` file.
6
- - Accepted ADRs are immutable; supersede them with a new ADR.
7
- - Record Context, Decision, Alternatives Considered, Consequences, and Revisit When.
8
- - Link ADRs from the affected module specs and `ARCHITECTURE.md`.