@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.
- package/.repo-context.json +704 -0
- package/.sdd/manifest.json +1065 -339
- package/AGENTS.md +935 -60
- package/dist/webex.js +1 -1
- package/docs/adr/0001-spec-source-policy.md +97 -0
- package/{ai-docs/features/consult-transfer-list-policy/spec/feature-spec.md → docs/adr/0002-consult-transfer-list-policy.md} +227 -244
- package/docs/adr/0003-repo-standards-migration.md +104 -0
- package/docs/adr/index.md +35 -0
- package/docs/architecture.md +460 -0
- package/docs/getting-started.md +142 -0
- package/docs/index.md +53 -0
- package/docs/specs/README.md +98 -0
- package/package.json +10 -9
- package/schemas/repo-context.schema.json +796 -0
- package/src/docs/README.md +727 -0
- package/src/metrics/docs/README.md +710 -0
- package/src/services/agent/docs/README.md +673 -0
- package/src/services/config/docs/README.md +530 -0
- package/src/services/core/docs/README.md +993 -0
- package/src/services/docs/README.md +765 -0
- package/src/services/task/docs/README.md +1569 -0
- package/src/services/task/state-machine/docs/README.md +1388 -0
- package/src/utils/AGENTS.md +6 -4
- package/src/utils/docs/README.md +413 -0
- package/umd/contact-center.min.js +2 -2
- package/umd/contact-center.min.js.map +1 -1
- package/ai-docs/ARCHITECTURE.md +0 -168
- package/ai-docs/CONTRACTS.md +0 -64
- package/ai-docs/GETTING_STARTED.md +0 -168
- package/ai-docs/GLOSSARY.md +0 -43
- package/ai-docs/README.md +0 -138
- package/ai-docs/REVIEW_CHECKLIST.md +0 -41
- package/ai-docs/RULES.md +0 -444
- package/ai-docs/SECURITY.md +0 -52
- package/ai-docs/SERVICE_STATE.md +0 -52
- package/ai-docs/SPEC_INDEX.md +0 -65
- package/ai-docs/adr/0001-spec-source-policy.md +0 -55
- package/ai-docs/adr/README.md +0 -8
- package/ai-docs/adr/_adr-template.md +0 -31
- package/ai-docs/contact-center-spec.md +0 -388
- package/ai-docs/features/contact-owner-change-refactor.md +0 -78
- package/ai-docs/features/generated-spec-conformance-fidelity-remediation/spec/feature-spec.md +0 -117
- package/ai-docs/features/residual-warning-coverage-completion/spec/feature-spec.md +0 -203
- package/ai-docs/features/validator-code-fidelity-drift-fix/spec/feature-spec.md +0 -315
- package/ai-docs/patterns/event-driven-patterns.md +0 -485
- package/ai-docs/patterns/testing-patterns.md +0 -480
- package/ai-docs/patterns/typescript-patterns.md +0 -365
- package/ai-docs/templates/README.md +0 -102
- package/ai-docs/templates/documentation/create-agents-md.md +0 -240
- package/ai-docs/templates/documentation/create-architecture-md.md +0 -295
- package/ai-docs/templates/existing-service/bug-fix.md +0 -254
- package/ai-docs/templates/existing-service/feature-enhancement.md +0 -450
- package/ai-docs/templates/new-method/00-master.md +0 -80
- package/ai-docs/templates/new-method/01-requirements.md +0 -232
- package/ai-docs/templates/new-method/02-implementation.md +0 -295
- package/ai-docs/templates/new-method/03-tests.md +0 -201
- package/ai-docs/templates/new-method/04-validation.md +0 -141
- package/ai-docs/templates/new-service/00-master.md +0 -109
- package/ai-docs/templates/new-service/01-pre-questions.md +0 -159
- package/ai-docs/templates/new-service/02-code-generation.md +0 -346
- package/ai-docs/templates/new-service/03-integration.md +0 -178
- package/ai-docs/templates/new-service/04-test-generation.md +0 -205
- package/ai-docs/templates/new-service/05-validation.md +0 -145
- package/src/metrics/ai-docs/AGENTS.md +0 -350
- package/src/metrics/ai-docs/ARCHITECTURE.md +0 -338
- package/src/metrics/ai-docs/metrics-spec.md +0 -971
- package/src/services/agent/ai-docs/AGENTS.md +0 -240
- package/src/services/agent/ai-docs/ARCHITECTURE.md +0 -304
- package/src/services/agent/ai-docs/agent-spec.md +0 -505
- package/src/services/ai-docs/AGENTS.md +0 -386
- package/src/services/ai-docs/services-spec.md +0 -512
- package/src/services/config/ai-docs/AGENTS.md +0 -250
- package/src/services/config/ai-docs/ARCHITECTURE.md +0 -413
- package/src/services/config/ai-docs/config-spec.md +0 -669
- package/src/services/core/ai-docs/AGENTS.md +0 -381
- package/src/services/core/ai-docs/ARCHITECTURE.md +0 -698
- package/src/services/core/ai-docs/core-spec.md +0 -797
- package/src/services/task/ai-docs/AGENTS.md +0 -457
- package/src/services/task/ai-docs/ARCHITECTURE.md +0 -595
- package/src/services/task/ai-docs/task-spec.md +0 -1501
- package/src/services/task/state-machine/ai-docs/AGENTS.md +0 -460
- package/src/services/task/state-machine/ai-docs/ARCHITECTURE.md +0 -1156
- package/src/services/task/state-machine/ai-docs/task-state-machine-spec.md +0 -2247
- 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/`.
|
package/ai-docs/SECURITY.md
DELETED
|
@@ -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.
|
package/ai-docs/SERVICE_STATE.md
DELETED
|
@@ -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.
|
package/ai-docs/SPEC_INDEX.md
DELETED
|
@@ -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.
|
package/ai-docs/adr/README.md
DELETED
|
@@ -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`.
|